Metadata-Version: 2.5
Name: shinnjyuu-echo-kit
Version: 0.1.1
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: playwright==1.63.0
Requires-Dist: psutil<8,>=6
Description-Content-Type: text/markdown

# Echo Kit

让 AI 的实验、调试与验收成为团队可复用的工程能力。

发布维护见 [PyPI 发布说明](docs/publishing.md)。首次正式发布完成后可使用 `uvx --from shinnjyuu-echo-kit@latest echo-kit --version` 获取当前版本，再通过 `uvx --from shinnjyuu-echo-kit@具体版本 echo-kit …` 固定一轮任务的执行版本。

Python 3.11+。一个包提供 workspace、doctor、services、auth、browser、lab、verify、runs 和 Skill 导出。各能力按需使用，Lab 不要求 Docker 或服务启动。

```powershell
uv tool install .
echo-kit --help
echo-kit --workspace D:/my-project workspace init
echo-kit skills export D:/my-project/.agents/skills
```

也可以 `uv tool install git+<仓库地址>` 或安装 `dist` 中的 wheel。不需要发布公共包。Skills 的安装目录遵循所用 AI 助手规则；导出不会改助手配置。

## 独立演示

```powershell
uv sync --group dev
uv run python examples/create_demo.py --output D:/echo-demo
uv run echo-kit --workspace D:/echo-demo/qa --json workspace check
uv run echo-kit --workspace D:/echo-demo/qa lab compare arithmetic --variants baseline double --repeat 3
uv run echo-kit --workspace D:/echo-demo/qa verify run api
uv run echo-kit --workspace D:/echo-demo/qa verify run page
uv run echo-kit --workspace D:/echo-demo/qa services status
uv run echo-kit --workspace D:/echo-demo/qa runs list
```

示例生成互不嵌套的 frontend、backend、qa 三个目录，均不依赖魔方。`page` 需要正在运行的 Docker，首次启动容器需下载固定 Playwright 镜像及 npm 包。

## 配置与执行

共享 `echo-kit.toml` 与 `echo/` 适配、用例入 Git；`.echo-kit/local.toml` 深度覆盖共享配置，environment 覆盖随后生效。所有 `.echo-kit/` 状态不提交。绝对路径放本机覆盖，命令数组中的 `{python}` 指 Kit 解释器；业务 Python 应改为项目实际解释器。

命令必须使用数组，不隐式经过 Shell。`env_refs` 把指定环境变量传给适配器，敏感信息禁止写在 `command` 或 `env` 字面量。Kit 不记录全环境变量；项目脚本不得把秘密打印到 stdout 或写入证据。

全局选项置于模块前：`echo-kit --workspace PATH --environment NAME --json lab run CASE`。退出码 0 为已执行范围成功，1 为检查失败，2 为受阻或未验证，130 为中断。`services status` 的成功表示查询成功，请检查各实例的 ready 字段。

适配协议、认证和配置详见 [协议文档](docs/protocol.md)。业务依赖由项目管理，CLI 不导入业务模块。简单 `protocol="command"` 只核对退出码，不能证明语义正确。

## 运行与安全边界

托管服务持续运行；外部服务显式 `mode="external"`，不会停止。进程身份不匹配时不发送终止信号。未完成运行只保护其关联资源；无关联信息的旧记录仍需先收尾。使用 `runs cleanup ID` 核验终态，不能删除标记伪造收尾。

认证协议通过内存管道传秘密。只向受支持的系统凭据后端持久化；不可用时只保留当前调用内状态。独立 auth login 在这种情况下不会为下一条命令保留状态；verify 同次调用仍可使用。

报告只自动链接显式声明的产物。请求文件、适配输出、截图及 trace 可能包含业务数据，分享前审查。Kit 无法阻止恶意或错误适配器自行泄露数据；适配器是项目受信代码。

## 验证与限制

`uv run pytest` 运行核心测试；真实演示与 Docker 验收单独运行。具体证据见 `docs/validation.md`。macOS 未验证；不把单元模拟当成真实业务或平台验收。

第一版不提供 IDE 插件、Agent 引擎、通用验证码绕过、后台自动恢复。回放为已有记录与 Playwright trace 查看，不承诺重跑结果一致。

## 来源

服务归属、就绪等待与持续复用的设计，及 Lab 的案例／候选／独立重复执行概念，源自既有 Magic Cube Workbench 和 Agent Lab。为跨项目子进程协议重新实现，不引入原业务依赖、服务名、模型配置或私有凭据。

## 多会话协作

先运行 `echo-kit operations list` 查看共享操作，再使用 `echo-kit --actor "本轮验收说明" --workspace PATH verify run CASE`。同一服务被占用时返回 `resource_busy` 和占用者，AI 自行协调后重试；不自动排队。不同资源可并行，登录不再被整轮验收锁住。

`operations show ID` 查看历史；异常运行先 `runs cleanup ID`。仅在用户确认收尾、执行进程退出后使用 `operations resolve ID --note "确认说明"`。不会杀进程或清空历史。作用范围为同一机器、同一系统用户、使用新版 Echo 的操作；升级前先结束旧版任务。

构建类服务可以声明 `artifacts=["target/app.jar"]`，报告记录启动产物哈希。当前源码与运行版本分开记录；热更新服务不承诺固定版本。资源配置和边界见协议文档。
