docs: add inbox markdown test plans

2026-03-19 10:54:39 +08:00
parent dab0506c5a
commit 9beb7e93eb
18 changed files with 2091 additions and 135 deletions
@@ -0,0 +1,139 @@
+# Inbox `update` Test Plan
+
+## Scope
+
+This document covers progress and blocked transitions via `inbox update`.
+
+Shared conventions live in [../_shared/README.md](../_shared/README.md).
+
+## case: update-moves-thread-to-in-progress
+
+### 用例意义
+
+验证租约拥有者可以把线程推进到 `in_progress`，并生成进度消息。
+
+### 前置条件
+
+- `worker-a` 已成功 `claim` 线程 `THREAD_ID`
+
+### 输入
+
+```bash
+inbox --db TMPDIR/coord.db --json update --agent worker-a --thread THREAD_ID --status in_progress --summary "Implementation started" --body "Scanning current HTTP client usage."
+```
+
+### 预期输出
+
+- 命令退出码为 `0`
+- `thread.status == "in_progress"`
+- `message.kind == "progress"`
+- `message.to_agent` 指向线程创建者
+
+### 断言结论
+
+- `update` 会把状态推进和消息追加合并为同一次事务
+
+## case: update-moves-thread-to-blocked-with-payload
+
+### 用例意义
+
+验证 `update --status blocked` 会写入阻塞问题消息，并保留结构化 payload。
+
+### 前置条件
+
+- `worker-a` 已成功 `claim` 线程 `THREAD_ID`
+
+### 输入
+
+```bash
+inbox --db TMPDIR/coord.db --json update --agent worker-a --thread THREAD_ID --status blocked --summary "Need timeout decision" --payload-json '{"question":"Should retries apply to read timeouts?"}'
+```
+
+### 预期输出
+
+- 命令退出码为 `0`
+- `thread.status == "blocked"`
+- `message.kind == "question"`
+- `message.payload_json.question` 保存提问内容
+
+### 断言结论
+
+- `blocked` 更新会生成面向创建者的问题消息
+
+## case: update-accepts-body-file-and-artifact
+
+### 用例意义
+
+验证 `update` 支持通过 `body-file` 与 artifact 发送结构化进度材料。
+
+### 前置条件
+
+- `worker-a` 已成功 `claim` 线程 `THREAD_ID`
+- `TMPDIR/progress.md` 已存在
+
+### 输入
+
+```bash
+inbox --db TMPDIR/coord.db --json update --agent worker-a --thread THREAD_ID --status in_progress --summary "Implementation started" --body-file TMPDIR/progress.md --artifact TMPDIR/progress.md --artifact-kind note
+inbox --db TMPDIR/coord.db --json show --thread THREAD_ID
+```
+
+### 预期输出
+
+- `update` 成功
+- 对应消息 `body` 等于文件内容
+- 对应消息包含 1 个 artifact，kind 为 `note`
+
+### 断言结论
+
+- `update` 的正文与 artifact 支持与 `send/reply/done/fail` 保持一致
+
+## case: update-rejects-invalid-payload-json
+
+### 用例意义
+
+验证 `update` 对非法 `--payload-json` 输入返回稳定错误契约。
+
+### 前置条件
+
+- `worker-a` 已成功 `claim` 线程 `THREAD_ID`
+
+### 输入
+
+```bash
+inbox --db TMPDIR/coord.db --json update --agent worker-a --thread THREAD_ID --status blocked --summary "Need timeout decision" --payload-json not-json
+```
+
+### 预期输出
+
+- 退出码为 `30`
+- JSON 错误码为 `invalid_input`
+
+### 断言结论
+
+- 阻塞问题的 payload 需要满足合法 JSON 约束
+
+## case: update-rejects-non-owner
+
+### 用例意义
+
+验证非租约拥有者不能更新线程状态。
+
+### 前置条件
+
+- `worker-a` 已成功 `claim` 线程 `THREAD_ID`
+
+### 输入
+
+```bash
+inbox --db TMPDIR/coord.db --json update --agent worker-b --thread THREAD_ID --status in_progress --summary "Implementation started"
+```
+
+### 预期输出
+
+- 退出码为 `20`
+- JSON 错误码为 `lease_conflict`
+
+### 断言结论
+
+- `update` 明确依赖活跃 lease 所属者