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,93 +1,9 @@
-# Inbox `wait-reply` Test Plan
+# Inbox `wait-reply` Test Plan Index

-## Scope
+## Case Files

-This document covers blocking reply wait behavior within one thread via `inbox wait-reply`.
-
-Shared conventions live in [../_shared/README.md](../_shared/README.md).
-
-## case: wait-reply-wakes-on-answer-after-message
-
-### 用例意义
-
-验证 `wait-reply` 可以从某条已知消息之后开始等待，并在答复到达后唤醒。
-
-### 前置条件
-
- `worker-c` 已拥有一个 `blocked` 线程 `THREAD_ID`
- 阻塞消息的 `message_id` 为 `BLOCKED_MESSAGE_ID`
-
-### 输入
-
-```bash
-inbox --db TMPDIR/coord.db --agent worker-c --json wait-reply --thread THREAD_ID --after-message BLOCKED_MESSAGE_ID --timeout-seconds 2
-inbox --db TMPDIR/coord.db --json reply --from leader --to worker-c --thread THREAD_ID --summary "Redirect to login" --body "Redirect guests to login for the MVP."
-```
-
-### 预期输出
-
- `wait-reply` 退出码为 `0`
- `wait-reply.data.woke == true`
- 返回的 `message.kind == "answer"`
-
-### 断言结论
-
- `wait-reply` 可以可靠地从既知消息边界之后等待后续答复
-
-## case: wait-reply-can-start-from-after-event
-
-### 用例意义
-
-验证 `wait-reply --after-event` 支持从既知事件游标之后恢复等待。
-
-### 前置条件
-
- 已通过先前的 `watch` 或 `wait-reply` 结果拿到某个 `NEXT_EVENT_ID`
- 线程 `THREAD_ID` 后续还会收到新的回复类消息
-
-### 输入
-
-```bash
-inbox --db TMPDIR/coord.db --agent worker-c --json wait-reply --thread THREAD_ID --after-event NEXT_EVENT_ID --timeout-seconds 2
-inbox --db TMPDIR/coord.db --json reply --from leader --to worker-c --thread THREAD_ID --summary "Redirect to login" --body "Redirect guests to login for the MVP."
-```
-
-### 预期输出
-
- `wait-reply` 在事件游标之后的新回复出现时被唤醒
- 返回新的 `next_event_id`
-
-### 断言结论
-
- `after-event` 允许等待逻辑在断点之后继续，而不会重复消费旧回复
-
-## case: wait-reply-times-out-when-no-reply
-
-### 用例意义
-
-验证在超时时间内没有匹配回复出现时，`wait-reply` 返回稳定超时契约。
-
-### 前置条件
-
- 存在一个线程 `THREAD_ID`
- 不会有新的 `answer/control/result` 消息到达
-
-### 输入
-
-```bash
-inbox --db TMPDIR/coord.db --agent worker-c --json wait-reply --thread THREAD_ID --timeout-seconds 1
-```
-
-### 预期输出
-
- 退出码为 `10`
- JSON 错误码为 `no_matching_work`
-
-### 断言结论
-
- `wait-reply` 超时被视为“没有等到匹配回复”
-
-## Notes
-
- 默认唤醒 kinds 为 `answer,control,result`
- 当返回消息是发给等待 agent 的外来消息时，`wait-reply` 会顺带推进该 agent 的 read cursor
+| Case Slug | File | Coverage Note |
+| --- | --- | --- |
+| `wait-reply-wakes-on-answer-after-message` | [wait-reply-wakes-on-answer-after-message.md](./wait-reply-wakes-on-answer-after-message.md) | wakes for a qualifying reply after known message boundary |
+| `wait-reply-can-start-from-after-event` | [wait-reply-can-start-from-after-event.md](./wait-reply-can-start-from-after-event.md) | resumes waiting from a known event cursor |
+| `wait-reply-times-out-when-no-reply` | [wait-reply-times-out-when-no-reply.md](./wait-reply-times-out-when-no-reply.md) | returns timeout contract when no qualifying reply arrives |
@@ -0,0 +1,29 @@
+# case: wait-reply-can-start-from-after-event
+
+### 用例意义
+
+验证 `wait-reply --after-event` 支持从既知事件游标之后恢复等待。
+
+### 前置条件
+
+- 已通过先前的 `watch` 或 `wait-reply` 结果拿到某个 `NEXT_EVENT_ID`
+- 线程 `THREAD_ID` 后续还会收到新的回复类消息
+
+### 输入
+
+```bash
+inbox --db TMPDIR/coord.db --agent worker-c --json wait-reply --thread THREAD_ID --after-event NEXT_EVENT_ID --timeout-seconds 2
+inbox --db TMPDIR/coord.db --json reply --from leader --to worker-c --thread THREAD_ID --summary "Redirect to login" --body "Redirect guests to login for the MVP."
+```
+
+### 预期输出
+
+- `wait-reply` 在事件游标之后的新回复出现时被唤醒
+- 返回新的 `next_event_id`
+
+### 断言结论
+
+- `after-event` 允许等待逻辑在断点之后继续，而不会重复消费旧回复
+- `--kinds` 支持自定义逗号分隔的唤醒消息类型；未显式提供时默认使用 `answer,control,result`
+- 默认唤醒 kinds 为 `answer,control,result`
+
@@ -0,0 +1,28 @@
+# case: wait-reply-times-out-when-no-reply
+
+### 用例意义
+
+验证在超时时间内没有匹配回复出现时，`wait-reply` 返回稳定超时契约。
+
+### 前置条件
+
+- 存在一个线程 `THREAD_ID`
+- 不会有新的 `answer/control/result` 消息到达
+
+### 输入
+
+```bash
+inbox --db TMPDIR/coord.db --agent worker-c --json wait-reply --thread THREAD_ID --timeout-seconds 1
+```
+
+### 预期输出
+
+- 退出码为 `10`
+- JSON 错误码为 `no_matching_work`
+
+### 断言结论
+
+- `wait-reply` 超时被视为“没有等到匹配回复”
+- `--thread` 是必填 flag；缺失时属于 `invalid_input` 类 usage error
+- `--timeout-seconds=0` 表示无限等待，而不是立即超时
+
@@ -0,0 +1,31 @@
+# case: wait-reply-wakes-on-answer-after-message
+
+### 用例意义
+
+验证 `wait-reply` 可以从某条已知消息之后开始等待，并在答复到达后唤醒。
+
+### 前置条件
+
+- `worker-c` 已拥有一个 `blocked` 线程 `THREAD_ID`
+- 阻塞消息的 `message_id` 为 `BLOCKED_MESSAGE_ID`
+
+### 输入
+
+```bash
+inbox --db TMPDIR/coord.db --agent worker-c --json wait-reply --thread THREAD_ID --after-message BLOCKED_MESSAGE_ID --timeout-seconds 2
+inbox --db TMPDIR/coord.db --json reply --from leader --to worker-c --thread THREAD_ID --summary "Redirect to login" --body "Redirect guests to login for the MVP."
+```
+
+### 预期输出
+
+- `wait-reply` 退出码为 `0`
+- `wait-reply.data.woke == true`
+- 返回的 `message.kind == "answer"`
+
+### 断言结论
+
+- `wait-reply` 可以可靠地从既知消息边界之后等待后续答复
+- `--agent` 不是必填；它主要用于在命中外来消息时推进该 agent 的 read cursor
+- `--after-message` 必须引用该线程中已知的消息；如果消息不存在，应返回 `not_found`
+- 当返回消息是发给等待 agent 的外来消息时，`wait-reply` 会顺带推进该 agent 的 read cursor
+