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,112 @@
+# Inbox `done` Test Plan
+
+## Scope
+
+This document covers successful terminal completion via `inbox done`.
+
+Shared conventions live in [../_shared/README.md](../_shared/README.md).
+
+## case: done-marks-thread-terminal
+
+### 用例意义
+
+验证租约拥有者可以将线程推进到 `done` 终态，并生成结果消息。
+
+### 前置条件
+
+- `worker-a` 已成功 `claim` 线程 `THREAD_ID`
+
+### 输入
+
+```bash
+inbox --db TMPDIR/coord.db --json done --agent worker-a --thread THREAD_ID --summary "Retry policy implemented" --body "The HTTP client now retries the selected transient failures."
+```
+
+### 预期输出
+
+- 命令退出码为 `0`
+- `thread.status == "done"`
+- `message.kind == "result"`
+
+### 断言结论
+
+- `done` 会把线程推进到成功终态
+- 完成时会释放活跃 lease
+
+## case: done-persists-result-body-and-artifact
+
+### 用例意义
+
+验证 `done` 能持久化结果正文与附件，并被后续 `show` 读取。
+
+### 前置条件
+
+- `worker-a` 已成功 `claim` 线程 `THREAD_ID`
+- `TMPDIR/result.md` 已存在
+
+### 输入
+
+```bash
+inbox --db TMPDIR/coord.db --json done --agent worker-a --thread THREAD_ID --summary "Retry policy implemented" --body-file TMPDIR/result.md --artifact TMPDIR/result.md --artifact-kind report
+inbox --db TMPDIR/coord.db --json show --thread THREAD_ID
+```
+
+### 预期输出
+
+- `done` 成功
+- 最终结果消息 `body` 等于文件内容
+- 结果消息包含 1 个 `report` artifact
+
+### 断言结论
+
+- `done` 是结果交付命令，不只是状态切换命令
+
+## case: done-rejects-non-owner
+
+### 用例意义
+
+验证非租约拥有者不能代替执行者完成线程。
+
+### 前置条件
+
+- `worker-a` 已成功 `claim` 线程 `THREAD_ID`
+
+### 输入
+
+```bash
+inbox --db TMPDIR/coord.db --json done --agent worker-b --thread THREAD_ID --summary "Retry policy implemented"
+```
+
+### 预期输出
+
+- 退出码为 `20`
+- JSON 错误码为 `lease_conflict`
+
+### 断言结论
+
+- `done` 受活跃 lease 所属者约束
+
+## case: done-rejects-on-terminal-thread
+
+### 用例意义
+
+验证已进入终态的线程不能再次执行 `done`。
+
+### 前置条件
+
+- 线程 `THREAD_ID` 已经是 `done`、`failed` 或 `cancelled`
+
+### 输入
+
+```bash
+inbox --db TMPDIR/coord.db --json done --agent worker-a --thread THREAD_ID --summary "Retry policy implemented"
+```
+
+### 预期输出
+
+- 退出码为 `30`
+- JSON 错误码为 `invalid_state`
+
+### 断言结论
+
+- `done` 对终态线程是幂等失败，而不是重复成功