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,111 @@
+# Inbox `reply` Test Plan
+
+## Scope
+
+This document covers reply behavior within an existing thread via `inbox reply`.
+
+Shared conventions live in [../_shared/README.md](../_shared/README.md).
+
+## case: reply-adds-answer-message
+
+### 用例意义
+
+验证 `reply` 默认会向现有线程追加一条 `answer` 消息，并保持线程状态不变。
+
+### 前置条件
+
+- 已存在一个非终态线程 `THREAD_ID`
+
+### 输入
+
+```bash
+inbox --db TMPDIR/coord.db --json reply --from leader --to worker-a --thread THREAD_ID --summary "Retry read timeouts" --body "Yes, include read timeouts in the retry policy."
+```
+
+### 预期输出
+
+- 命令退出码为 `0`
+- `message.kind == "answer"`
+- `thread.thread_id == THREAD_ID`
+- 线程状态保持原值
+
+### 断言结论
+
+- `reply` 是线程内追加消息，而不是状态转换命令
+
+## case: reply-supports-control-kind
+
+### 用例意义
+
+验证 `reply --kind control` 可以发送控制类消息，而不局限于默认 `answer`。
+
+### 前置条件
+
+- 已存在一个非终态线程 `THREAD_ID`
+
+### 输入
+
+```bash
+inbox --db TMPDIR/coord.db --json reply --from leader --to worker-a --thread THREAD_ID --kind control --summary "Pause rollout" --body "Pause rollout until QA confirms the fix."
+```
+
+### 预期输出
+
+- 命令退出码为 `0`
+- `message.kind == "control"`
+
+### 断言结论
+
+- `reply` 的消息种类可由调用方显式指定
+
+## case: reply-attaches-artifact
+
+### 用例意义
+
+验证 `reply` 支持追加带附件的答复消息。
+
+### 前置条件
+
+- 已存在一个非终态线程 `THREAD_ID`
+- `TMPDIR/decision.md` 已存在
+
+### 输入
+
+```bash
+inbox --db TMPDIR/coord.db --json reply --from leader --to worker-a --thread THREAD_ID --summary "Retry read timeouts" --artifact TMPDIR/decision.md --artifact-kind brief --artifact-metadata-json '{"label":"decision"}'
+```
+
+### 预期输出
+
+- 命令退出码为 `0`
+- `message.artifacts` 长度为 `1`
+- artifact 路径、kind、metadata 都可读
+
+### 断言结论
+
+- `reply` 与 `send/update/done/fail` 共享附件写入契约
+
+## case: reply-rejects-invalid-payload-json
+
+### 用例意义
+
+验证 `reply` 对非法 `--payload-json` 输入返回稳定错误契约。
+
+### 前置条件
+
+- 已存在一个非终态线程 `THREAD_ID`
+
+### 输入
+
+```bash
+inbox --db TMPDIR/coord.db --json reply --from leader --to worker-a --thread THREAD_ID --summary "Retry read timeouts" --payload-json not-json
+```
+
+### 预期输出
+
+- 退出码为 `30`
+- JSON 错误码为 `invalid_input`
+
+### 断言结论
+
+- `reply` 的 payload 与其他消息写入命令一样需要通过 JSON 校验