diff --git a/AGENTS.md b/AGENTS.md index 997573b..41c4f3f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -46,4 +46,3 @@ AgentRun 是面向 UniDesk 与 HWLAB 的共享 Agent 执行基础设施。本仓 - `docs/reference/spec-v01-cicd.md`：v0.1 分支、workspace、namespace、GitOps、registry、CI/CD 和发布验收规格。 - `docs/reference/architecture.md`：AgentRun 产品边界、服务架构、MVP 阶段、RESTful API 模型和数据模型。 - `docs/reference/cli.md`：按 `cli-spec` 固化的 CLI 与服务 API 约束。 -- `TEST.md`：随实现逐步补齐的人工验收场景。 diff --git a/TEST.md b/TEST.md deleted file mode 100644 index ddacc57..0000000 --- a/TEST.md +++ /dev/null @@ -1,15 +0,0 @@ -# AgentRun 人工测试计划 - -这些测试会随着 CLI 和服务实现逐步补齐。当前先定义未来人工验收的写法。 - -## T1 最小 Run 生命周期 - -阅读 `AGENTS.md`，然后使用 AgentRun CLI 手动测试创建 run、为该 run 启动 runner、轮询 events 并观察 terminal status。确认每个 CLI 命令都返回 JSON，包含 id 和后续命令，并且不会在单个请求中等待完整模型 turn。 - -## T2 Command 与 Event 轮询 - -阅读 `AGENTS.md`，然后创建 run command，并轮询 command status 与 run events。确认 command state 可见，event pagination 使用 `afterSeq`，重复轮询不会产生重复 event。 - -## T3 日志与失败可见性 - -阅读 `AGENTS.md`，然后用一个故意无效的 backend profile 启动本地服务或 runner。确认 CLI 返回结构化失败，输出 log path，并且日志文件包含足够定位失败原因的信息。 diff --git a/docs/reference/spec-v01-documentation-governance.md b/docs/reference/spec-v01-documentation-governance.md index 3cc67f9..62e123d 100644 --- a/docs/reference/spec-v01-documentation-governance.md +++ b/docs/reference/spec-v01-documentation-governance.md @@ -9,6 +9,7 @@ - `docs/reference/` 只保存长期稳定、可复用的规格、边界、入口、判定标准和稳定 runbook。 - 计划、阶段拆解、一次性排障、临时报告和执行证据进入 GitHub issue 或 PR 评论，不直接沉淀为仓库长期文档。 - `docs/` 根目录不得堆放 Markdown 报告或 JSON dump；机器可消费契约应放入未来的 `protocol/`、`deploy/` 或源码相邻目录，临时输出放 `/tmp`、`.state` 或 CI artifact。 +- 不维护独立 `TEST.md`；人工测试和验收场景必须作为对应 `spec-v01-*.md` 的“测试规格”子项维护。 - 旧 `dev/prod` 管理说法不再作为当前规格；AgentRun 从 `v0.1` 开始按 `v0.1`、`v0.2`、`v0.3` 版本 lane 滚动。 ## 允许的文档形态 @@ -16,7 +17,7 @@ | 位置 | 允许内容 | 不允许内容 | | --- | --- | --- | | `AGENTS.md` | 顶级入口、一句话 P0 规则、长期参考链接 | 详细设计、阶段计划全文、临时结论、过程流水账 | -| `docs/reference/*.md` | 长期规格、稳定边界、判定标准、可复用 runbook | 日期化报告、一次性排障全文、临时 evidence、旧规格副本 | +| `docs/reference/*.md` | 长期规格、稳定边界、判定标准、可复用 runbook、对应规格的测试规格 | 日期化报告、一次性排障全文、临时 evidence、旧规格副本、独立测试入口 | | `docs/reference/spec-v01-*.md` | `v0.1` 当前权威规格 | 与 `v0.1` 无关的 `v0.2+` 计划全文、未蒸馏过程材料 | | GitHub issue/PR | 计划、里程碑、过程记录、执行证据、实现任务 | 替代 `docs/reference` 成为长期唯一权威 | | `/tmp` / `.state` / CI artifact | 临时输出、trace、日志、报告、截图 | 需要长期复用的规格或入口 | @@ -28,6 +29,7 @@ - `spec-v01-cicd.md`：版本 lane、GitOps、namespace、registry 和发布验收。 - 未来新增单服务规格必须使用 `spec-v01-.md`，例如 `spec-v01-agentrun-mgr.md`、`spec-v01-agentrun-runner.md`。 - `v0.2` 或更高版本的规格不得写入 `spec-v01-*`；只能在对应版本 lane 中创建自己的 `spec-v02-*`、`spec-v03-*`。 +- 每个可实现规格应包含“测试规格”小节；测试编号写在对应 spec 内，不创建或恢复根目录 `TEST.md`。 ## 迁移规则 @@ -35,7 +37,8 @@ 2. 有长期价值的，只把稳定结论吸收到对应 `docs/reference/spec-v01-*.md`；不要整篇搬入 reference。 3. 属于计划、里程碑、阶段迁移、报告、一次性排障或历史验收的，全文迁入 GitHub issue 或 PR 评论，再删除源文件。 4. 与 `v0.1` 规格冲突的旧 `dev/prod`、`/root/agentrun` 默认工作区、`agentrun_dev`、`agentrun_prod` 说法必须删除或改为历史背景。 -5. 未实现规格必须在对应 spec 的“规格的实现情况”中明确写成 `未实现` 或 `未完全实现`，不要用散落 TODO 代替。 +5. 发现独立 `TEST.md` 或测试计划文档时，先把仍有效的测试场景蒸馏到对应 `spec-v01-*.md` 的“测试规格”小节，再删除源文件。 +6. 未实现规格必须在对应 spec 的“规格的实现情况”中明确写成 `未实现` 或 `未完全实现`，不要用散落 TODO 代替。 ## v0.1 当前权威入口 @@ -52,4 +55,5 @@ - `docs/reference/` 中存在 `spec-v01-documentation-governance.md`、`spec-v01-services.md` 和 `spec-v01-cicd.md`。 - `AGENTS.md` 和 `docs/reference/` 不得把旧 `agentrun_dev`、`agentrun_prod`、`G14:/root/agentrun` 或 `/root/agentrun` 写成当前工作区、namespace、发布目标或验收目标；只允许在废弃说明和历史背景中提及。 - `docs/` 根目录不新增临时 Markdown 报告或 JSON dump。 +- 仓库根目录不存在 `TEST.md`；测试场景维护在对应 `spec-v01-*.md` 的“测试规格”小节。 - 后续实现任务先更新或引用对应 `spec-v01-*`，再修改代码和测试。 diff --git a/docs/reference/spec-v01-services.md b/docs/reference/spec-v01-services.md index 8040297..febfbd6 100644 --- a/docs/reference/spec-v01-services.md +++ b/docs/reference/spec-v01-services.md @@ -86,6 +86,20 @@ POST /api/v1/commands/:commandId/ack | M4 | 自动 scheduler | Deferred；pending 自动派发和 stale lease recovery 进入后续实现。 | | M5 | UniDesk/HWLAB canary | Deferred；只在核心生命周期稳定后接入窄范围 canary。 | +## 测试规格 + +### T1 最小 Run 生命周期 + +阅读 `AGENTS.md`、本文和 [spec-v01-cicd.md](spec-v01-cicd.md)，然后使用 AgentRun CLI 手动测试创建 run、为该 run 启动 runner、轮询 events 并观察 terminal status。确认每个 CLI 命令都返回 JSON，包含 id 和后续命令，并且不会在单个请求中等待完整模型 turn。 + +### T2 Command 与 Event 轮询 + +阅读 `AGENTS.md`、本文和 [spec-v01-cicd.md](spec-v01-cicd.md)，然后创建 run command，并轮询 command status 与 run events。确认 command state 可见，event pagination 使用 `afterSeq`，重复轮询不会产生重复 event。 + +### T3 日志与失败可见性 + +阅读 `AGENTS.md`、本文和 [spec-v01-cicd.md](spec-v01-cicd.md)，然后用一个故意无效的 backend profile 启动本地服务或 runner。确认 CLI 返回结构化失败，输出 log path，并且日志文件包含足够定位失败原因的信息。 + ## 规格的实现情况 | 规格项 | 状态 | 说明 |