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,115 +1,10 @@
-# Inbox `show` Test Plan
+# Inbox `show` Test Plan Index

-## Scope
+## Case Files

-This document covers per-thread detail retrieval via `inbox show`.
-
-Shared conventions live in [../_shared/README.md](../_shared/README.md).
-
-## case: show-returns-thread-and-message-history
-
-### 用例意义
-
-验证 `show` 会返回线程详情和完整消息历史。
-
-### 前置条件
-
- 已存在一个含多条消息的线程 `THREAD_ID`
-
-### 输入
-
-```bash
-inbox --db TMPDIR/coord.db --json show --thread THREAD_ID
-```
-
-### 预期输出
-
- 命令退出码为 `0`
- 返回 `data.thread`
- 返回 `data.messages`
- 消息按创建时间升序排列
-
-### 断言结论
-
- `show` 是线程详情与时间序历史的读取入口
-
-## case: show-includes-artifacts-per-message
-
-### 用例意义
-
-验证 `show` 返回的每条消息都包含其关联 artifact 列表。
-
-### 前置条件
-
- 线程 `THREAD_ID` 中至少一条消息附带 artifact
-
-### 输入
-
-```bash
-inbox --db TMPDIR/coord.db --json show --thread THREAD_ID
-```
-
-### 预期输出
-
- 命令退出码为 `0`
- 相关消息节点包含 `artifacts`
- artifact 的 `path`、`kind`、`metadata_json` 可读
-
-### 断言结论
-
- `show` 需要把附件一并展开，而不是只返回 message 基本字段
-
-## case: show-mark-read-advances-read-cursor
-
-### 用例意义
-
-验证 `show --mark-read` 会推进调用 agent 的 read cursor，并影响后续 unread 查询。
-
-### 前置条件
-
- `worker-e` 有一个未读线程 `THREAD_ID`
-
-### 输入
-
-```bash
-inbox --db TMPDIR/coord.db --agent worker-e --json show --thread THREAD_ID --mark-read
-inbox --db TMPDIR/coord.db --json fetch --agent worker-e --status pending --unread
-```
-
-### 预期输出
-
- `show` 成功
- 随后的 `fetch --unread` 对该线程不再返回结果
-
-### 断言结论
-
- `mark-read` 的副作用是推进该 agent 的 `last_read_message_id`
-
-## case: show-rejects-when-thread-missing
-
-### 用例意义
-
-验证 `show` 对不存在线程返回稳定的 not-found 错误契约。
-
-### 前置条件
-
- 空数据库已完成 `init`
-
-### 输入
-
-```bash
-inbox --db TMPDIR/coord.db --json show --thread thr_missing
-```
-
-### 预期输出
-
- 退出码为 `40`
- JSON 错误码为 `not_found`
-
-### 断言结论
-
- `show` 不会对缺失线程返回空对象
-
-## Notes
-
- 使用 `--mark-read` 时必须提供 agent 身份，可通过根级 `--agent` 或命令参数传入
+| Case Slug | File | Coverage Note |
+| --- | --- | --- |
+| `show-returns-thread-and-message-history` | [show-returns-thread-and-message-history.md](./show-returns-thread-and-message-history.md) | returns thread details and full time-ordered message history |
+| `show-includes-artifacts-per-message` | [show-includes-artifacts-per-message.md](./show-includes-artifacts-per-message.md) | expands per-message artifacts in the show payload |
+| `show-mark-read-advances-read-cursor` | [show-mark-read-advances-read-cursor.md](./show-mark-read-advances-read-cursor.md) | advances caller read cursor when `--mark-read` is used |
+| `show-rejects-when-thread-missing` | [show-rejects-when-thread-missing.md](./show-rejects-when-thread-missing.md) | returns stable not-found contract for missing thread |
@@ -0,0 +1,26 @@
+# case: show-includes-artifacts-per-message
+
+### 用例意义
+
+验证 `show` 返回的每条消息都包含其关联 artifact 列表。
+
+### 前置条件
+
+- 线程 `THREAD_ID` 中至少一条消息附带 artifact
+
+### 输入
+
+```bash
+inbox --db TMPDIR/coord.db --json show --thread THREAD_ID
+```
+
+### 预期输出
+
+- 命令退出码为 `0`
+- 相关消息节点包含 `artifacts`
+- artifact 的 `path`、`kind`、`metadata_json` 可读
+
+### 断言结论
+
+- `show` 需要把附件一并展开，而不是只返回 message 基本字段
+
@@ -0,0 +1,27 @@
+# case: show-mark-read-advances-read-cursor
+
+### 用例意义
+
+验证 `show --mark-read` 会推进调用 agent 的 read cursor，并影响后续 unread 查询。
+
+### 前置条件
+
+- `worker-e` 有一个未读线程 `THREAD_ID`
+
+### 输入
+
+```bash
+inbox --db TMPDIR/coord.db --agent worker-e --json show --thread THREAD_ID --mark-read
+inbox --db TMPDIR/coord.db --json fetch --agent worker-e --status pending --unread
+```
+
+### 预期输出
+
+- `show` 成功
+- 随后的 `fetch --unread` 对该线程不再返回结果
+
+### 断言结论
+
+- `mark-read` 的副作用是推进该 agent 的 `last_read_message_id`
+- 使用 `--mark-read` 时必须提供 agent 身份，可通过根级 `--agent` 或命令参数传入
+
@@ -0,0 +1,26 @@
+# case: show-rejects-when-thread-missing
+
+### 用例意义
+
+验证 `show` 对不存在线程返回稳定的 not-found 错误契约。
+
+### 前置条件
+
+- 空数据库已完成 `init`
+
+### 输入
+
+```bash
+inbox --db TMPDIR/coord.db --json show --thread thr_missing
+```
+
+### 预期输出
+
+- 退出码为 `40`
+- JSON 错误码为 `not_found`
+
+### 断言结论
+
+- `show` 不会对缺失线程返回空对象
+- `--thread` 是必填 flag；缺失时属于 `invalid_input` 类 usage error
+
@@ -0,0 +1,29 @@
+# case: show-returns-thread-and-message-history
+
+### 用例意义
+
+验证 `show` 会返回线程详情和完整消息历史。
+
+### 前置条件
+
+- 已存在一个含多条消息的线程 `THREAD_ID`
+
+### 输入
+
+```bash
+inbox --db TMPDIR/coord.db --json show --thread THREAD_ID
+```
+
+### 预期输出
+
+- 命令退出码为 `0`
+- 返回 `data.thread`
+- 返回 `data.messages`
+- 消息按创建时间升序排列
+
+### 断言结论
+
+- `show` 是线程详情与时间序历史的读取入口
+- `show` 不依赖线程是否处于活动态；只要线程存在，就应能读取包括终态线程在内的完整历史
+- 未使用 `--mark-read` 时，`show` 不要求提供 agent 身份
+