docs: split inbox test plans into case files

2026-03-19 11:29:17 +08:00
parent 9beb7e93eb
commit 5f59350577
70 changed files with 1820 additions and 1606 deletions
@@ -1,111 +1,10 @@
-# Inbox `reply` Test Plan
+# Inbox `reply` Test Plan Index

-## Scope
+## Case Files

-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 校验
+| Case Slug | File | Coverage Note |
+| --- | --- | --- |
+| `reply-adds-answer-message` | [reply-adds-answer-message.md](./reply-adds-answer-message.md) | appends default `answer` message to an existing non-terminal thread |
+| `reply-supports-control-kind` | [reply-supports-control-kind.md](./reply-supports-control-kind.md) | supports explicit `--kind control` reply message |
+| `reply-attaches-artifact` | [reply-attaches-artifact.md](./reply-attaches-artifact.md) | appends reply message with artifact payload |
+| `reply-rejects-invalid-payload-json` | [reply-rejects-invalid-payload-json.md](./reply-rejects-invalid-payload-json.md) | rejects malformed `--payload-json` input |
@@ -0,0 +1,34 @@
+# 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` 是线程内追加消息，而不是状态转换命令
+
+## 补充约束
+
+- `--from` 未显式提供时，可以回退使用根级 `--agent`；如果两者都缺失，应返回 `invalid_input`
+- `--thread`、`--to`、`--summary` 都是必填 flag；缺失时属于 `invalid_input` 类 usage error
+- `reply` 只允许作用在既有非终态线程上；缺失线程应返回 `not_found`，终态线程应返回 `invalid_state`
+- `--body` 与 `--body-file` 互斥；不可读的 `--body-file` 应返回 `invalid_input`
+
@@ -0,0 +1,31 @@
+# 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` 共享附件写入契约
+
+## 补充约束
+
+- `artifact-kind` 与 `artifact-metadata-json` 依赖至少一个 `--artifact`；数量不匹配也应返回 `invalid_input`
+
@@ -0,0 +1,25 @@
+# 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 校验
+
@@ -0,0 +1,25 @@
+# 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` 的消息种类可由调用方显式指定
+