Metadata-Version: 2.5
Name: shinnjyuu-echo-kit
Version: 0.5.0
Summary: Reusable experiments and verification workflows for AI coding assistants
Project-URL: Repository, https://github.com/shinnjyuu/echo-kit
Project-URL: Issues, https://github.com/shinnjyuu/echo-kit/issues
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: filelock<4,>=3.16
Requires-Dist: keyring<26,>=25
Requires-Dist: markdown-it-py<5,>=3
Requires-Dist: packaging<27,>=24
Requires-Dist: playwright==1.63.0
Requires-Dist: psutil<8,>=6
Requires-Dist: tomlkit<1,>=0.13
Description-Content-Type: text/markdown

# Echo Kit

**让 AI 为你的项目做实验、查问题、验收结果，并把这些过程留下来反复使用。**

Echo Kit 是一套供 AI 编程助手调用的工具。它帮助 AI 复用项目的启动和测试流程，执行检查，并留下结果、日志和文件等证据。换一个会话或换一位同事，也能沿用项目里已经整理好的验证方法。

本页面向第一次了解 Echo Kit 的人。负责接入项目的 AI 请阅读 [AI 接入指南](README.ai.md)。

## 它能帮我做什么？

比如，你刚让 AI 修复了一个文件导出功能，还想知道：页面能操作吗？文件真的下载了吗？内容对不对？

接入对应的验收用例后，你可以直接告诉 AI：

> 用 Echo Kit 验证这次导出功能的修改，检查页面操作、文件下载和内容，并把结果和证据给我。

AI 就可以复用项目中约定的流程，准备所需服务、执行这些检查，并告诉你哪些通过、哪些失败、哪些还没验证。下次改到同一功能，还能继续使用这套流程。

| 你想做的事 | Echo Kit 提供的支持 |
| --- | --- |
| 比较两种算法、参数或实现 | 分别运行候选方案，保存每次结果，对比检查项和指标 |
| 验收一次功能修改 | 按用例准备服务、登录和浏览器，收集接口或页面检查结果 |
| 让后续 AI 和同事接着用 | 把配置和验证脚本保存在项目里，留下可查看的运行记录 |
| 多个 AI 会话同时工作 | 在同一台机器、同一系统用户下，识别服务等资源的占用冲突 |
| 持续使用新版工具和说明 | 普通命令启动时检查并使用最新稳定版；离线或准备失败继续使用当前可用版（0.4.0 起） |

具体检查什么、怎样判断正确，由项目自己的验证脚本定义；AI 会在首次接入时复用或补充这些脚本。实验、服务管理和功能验收可以按需使用。

## 第一次使用：复制给 AI

**你不需要提前安装 Echo Kit，也不需要先下载这个仓库。** 打开你自己的项目，使用能够联网、读写项目文件并执行命令的 AI 编程助手，把下面整段话发给它。提示词已经包含工具地址。

```text
请为当前项目接入 Echo Kit，让后续 AI 会话能够复用
项目的实验、调试和验收能力。

官方仓库：https://github.com/shinnjyuu/echo-kit
请先阅读仓库根目录的 README.ai.md，按其中的步骤获取工具，
再遵循所选版本的 echo-init Skill 和公开协议完成接入。
不要假设本机已经安装 Echo Kit 或其运行环境；请自行检查，
按官方说明安装所需工具，并记录本次使用的版本。

先了解当前项目的开发约定、目录结构、启动方式和已有测试，
优先复用现有命令与脚本。若已有部分接入，请在原有基础上补齐，
保留团队修改。根据项目实际需要选择能力，
先打通一个有实际价值的最小本地验证流程。

请把可复用的配置、适配器和后续 AI 使用入口留在项目中；
默认直接调用最新版 Echo Kit，无需项目版本文件或任务生命周期；
本机路径和凭据按协议处理。只对无法从项目中确定、
且影响接入的关键事项向我提问。
操作共享业务环境需要另行取得授权，不要提交或推送代码。

完成后说明：接入了什么、实际验证了什么、还有哪些未完成事项、
证据在哪里，以及我以后可以怎样让 AI 使用这些能力。
```

AI 会先检查项目和本机环境，再安装工具、配置所需能力并运行最小验证。你只需补充它无法从项目里确定的信息，例如目标测试环境或登录方式。

## 接入后，我会得到什么？

- **可以重复使用的验证流程**：项目里保存配置和验证脚本，后续会话可以继续调用。
- **有依据的结果**：每次运行留下检查结论和报告；用例还可以保存截图、下载文件等证据。
- **清楚的交接说明**：哪些能力已经可用、哪些确实跑通过、下一次应该怎样使用。

例如，接入相应能力后，你可以继续这样交代 AI：

> 用 Echo Kit 对比当前实现和候选实现，各运行三次，把指标差异给我。

> 用 Echo Kit 跑一下这个项目已有的 API 验收，说明通过、失败和未验证的部分。

> 看一下上次失败的运行记录，结合日志和检查结果定位问题。

项目的业务依赖和开发方式仍由项目管理。前端、后端和验收脚本可以在不同目录，也可以连接已经运行的外部服务。

## 使用条件与当前范围

Echo Kit 本身需要 Python 3.11+，业务项目可以使用其他语言。AI 可以协助安装工具及其运行环境。普通实验和 API 验收不要求 Docker；使用工具托管的浏览器时才需要 Docker。

**AI 工具退出、更新或崩溃后，托管的本地服务可能停止，这是设计允许的场景。** Echo Kit 支持服务在命令结束后继续复用，但不保证跨宿主退出存活，也不保证随宿主退出自动清理。后续 AI 应先检查状态，再复用或按需启动。详见[服务生命周期约定](docs/protocol.md#managed-service-lifetime)。

当前验证记录覆盖 Windows 和 Linux 容器；macOS 尚未验证。登录需要项目正常的认证流程。截图、日志和下载文件可能含业务数据，分享前请检查。

验收结论只覆盖实际执行的检查。Kit 会标明失败、受阻和未验证的情况；历史记录用于追查过程，不保证重跑结果完全一致。

## 项目文档分层

Echo Kit 0.3.0 起支持区分团队共享文档与个人私有文档：共享文档使用相对路径、纳入 Git；个人文档允许本机绝对路径、排除 Git。AI 可通过 `docs list` 发现入口、`docs show` 读取、`docs check` 检查。已有项目主动执行 `docs setup` 接入，保留原有文件。见[项目文档说明](docs/project-documents.md)。

## 进一步阅读

- [AI 接入指南](README.ai.md)：从未安装到完成项目接入，也适合希望手动配置的开发者。
- [独立演示](docs/demo.md)：用示例项目体验实验、API 验收和浏览器验收。
- [公开协议](docs/protocol.md)：编写项目适配器、配置认证和管理运行结果。
- [默认最新版与旧入口迁移](docs/updates.md)：启动检查、离线回退和文档同步。
- [验证记录](docs/validation.md)与[多会话协作验证](docs/operations-validation.md)：已验证的范围和平台限制。
- [发布维护说明](docs/publishing.md)：面向维护者的构建和发布流程。


## 多个服务一起启动

0.5.0 起，`echo-kit services up` 默认最多同时启动 4 个服务，无需让 AI 一条一条执行。已有服务会复用，失败会保留已启动服务并报告原因。`services up --jobs 1` 可串行排障，默认并发数可通过 `[service_startup] concurrency = 4` 设置。

统一构建、特殊启动顺序由项目脚本负责；Kit 管理各服务进程、等待就绪并记录耗时。详见[启动约定](docs/protocol.md#parallel-service-startup)。
