Echo Kit

简体中文 | English

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

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

本页面向第一次了解 Echo Kit 的人。负责接入项目的 AI 请阅读 AI 接入指南。

它能帮我做什么？

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

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

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

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

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

第一次使用：复制给 AI

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

请为当前项目接入 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 应先检查状态，再复用或按需启动。详见服务生命周期约定。

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

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

项目文档分层

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

进一步阅读

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

多个服务一起启动

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

统一构建、特殊启动顺序由项目脚本负责；Kit 管理各服务进程、等待就绪并记录耗时。详见启动约定。

看见 AI 正在调试的页面

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

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

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

已有旧容器不会偷偷切换模式；等实验结束后按提示执行 browser down、browser up。详见可视浏览器约定。

获取当前指南与更新说明

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

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 发消息。

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

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 或新的启动命令即可接入，不改配置或业务容器。

测试账号也要准备好

初始化时，AI 会先判断用例是否需要登录，优先复用项目已有测试账号、种子数据或注册/管理入口；缺少可重复执行的入口时，再编写项目自己的准备脚本。账号准备是显式步骤，不会藏在登录或启动命令里。

准备后分别验证登录和用例所需的角色、租户权限。已有账号不擅自重置密码或扩权；无需登录的用例直接跳过。长期测试身份保留，临时身份只清理本次创建的记录。完整方法见 echo-kit guide echo-init；这是随包指导，不是 Kit 自动创建账号的新功能。