Metadata-Version: 2.5
Name: shinnjyuu-echo-kit
Version: 0.8.2
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: pillow<13,>=11; sys_platform == 'win32'
Requires-Dist: playwright==1.63.0
Requires-Dist: psutil<8,>=6
Requires-Dist: pystray<0.20,>=0.19.5; sys_platform == 'win32'
Requires-Dist: tomlkit<1,>=0.13
Description-Content-Type: text/markdown

# Echo Kit

**简体中文** | [English](README.en.md)

**让 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.6.0 起，`echo-kit services up` 默认同时启动所有符合依赖条件的服务，无需让 AI 一条一条执行。已有服务会复用，失败会保留已启动服务并报告原因。`services up --jobs 1` 可串行排障，资源有限时可通过 `[service_startup] concurrency = 4` 显式限制并发数。

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


## 看见 AI 正在调试的页面

0.6.0 起，托管浏览器默认有头运行。`echo-kit browser up` 或页面验收会启动 Docker 浏览器，并尝试用系统默认浏览器打开只读观看页：你看到的是 AI 正在操作的同一个桌面，不绑定 Edge，也无需安装 VNC 客户端。观看页无法点击或输入，不会干扰实验。

首次使用会构建并缓存浏览器镜像，需要联网下载依赖，耗时比后续启动长。每个容器只尝试自动打开一次；关闭观看页不会停止实验，也不会被强制重开。返回的 `viewer_url` 可随时再次打开；`browser down` 停止并移除所属容器，运行占用仍受保护。

```toml
[browser]
headless = false    # 默认有头；true 适合不需要观看的批量实验
# auto_open = false  # 不自动弹出观看页；CI 环境默认不弹出
# viewer_port = 19324
```

已有旧容器不会偷偷切换模式；等实验结束后按提示执行 `browser down`、`browser up`。详见[可视浏览器约定](docs/protocol.md#visible-browser)。

## 获取当前指南与更新说明

AI 在新会话首次使用时读取对应指南，实际执行版本变化后重新读取：

```sh
echo-kit guide echo-init       # 项目接入
echo-kit guide echo-lab        # 实验
echo-kit guide echo-workbench  # 联调验证
echo-kit updates notes
echo-kit updates notes --since 0.5.0
```

指南一次返回同一执行包的 Skill、协议、当前更新说明和版本；支持 `--json`，无需工作区。普通调用检查最新版，`--offline` 读取当前可用包。`--version` 和 `runtime info` 是安装入口的诊断信息，不能代替业务执行版本。自动升级提示不代表项目已适配。

前端调试推荐 **Kit 管理的 Docker 浏览器与只读 noVNC**。Docker 或构建失败时先处理错误，不自动改接外部浏览器。已有 `browser.endpoint` 仍生效，但只是显式兼容例外：Kit 不管理其镜像、显示模式和观看页，也不保证外部观看链接只读。查看 `browser up/status` 的能力信息；要切换时先检查配置来源和运行占用，在授权范围内调整配置后启动托管浏览器，不停止或接管原外部容器。

项目文档只维护启动方式、用例、认证流程、团队规则和环境归属；个人机器信息留在私有文档。项目 Skill 可写成指向 `echo-kit guide echo-workbench` 的短入口。整理旧副本时保留项目事实，再将通用 Kit 用法改为 CLI 入口，不覆盖原文。需要离线分发完整 Skill 时仍可导出到空目录并比较合并。

## Windows 托盘：关了观看页也能找回来

0.8.0 起，在 Windows 桌面启动 Kit 托管服务或浏览器时，会自动出现 Echo Kit 托盘图标（可能收在右下角隐藏图标区）。关闭 noVNC 标签页后，右键托盘，选择项目的“打开调试画面”，即可继续看同一次实验，不用向 AI 发消息。

托盘显示进程与容器状态，不代表业务健康检查通过。无头模式、旧容器没有观看入口；外部浏览器不纳入托管列表。菜单没有停止或重启业务资源的按钮。

```sh
echo-kit tray start           # 当前项目已有资源时，手动显示入口
echo-kit --json tray status   # 无需工作区
echo-kit tray stop            # 只退出托盘，服务和实验继续
```

全部托管资源确认停止后，托盘等待 30 秒自动退出；查询失败显示“状态未知”。手动退出后，同一次操作不会重新拉起，下一次启动操作可以恢复。CI、非交互桌面或环境变量 `ECHO_KIT_TRAY=0` 禁用自动启动；macOS/Linux 继续使用观看链接。

托盘独立运行，但不是服务守护程序，也不开机启动。如果 Windows 宿主限制后台进程独立启动，Kit 提示原因并保留原观看链接，不影响调试结果。已有项目运行一次 `tray start` 或新的启动命令即可接入，不改配置或业务容器。
