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,91 @@
+# Inbox `watch` Test Plan
+
+## Scope
+
+This document covers blocking thread-activity wait behavior via `inbox watch`.
+
+Shared conventions live in [../_shared/README.md](../_shared/README.md).
+
+## case: watch-wakes-on-matching-thread
+
+### 用例意义
+
+验证 `watch` 在新匹配线程到达时会被唤醒，并返回线程、消息与事件信息。
+
+### 前置条件
+
+- `worker-d` 当前没有匹配 `pending` 线程
+- `watch` 先于 `send` 启动
+
+### 输入
+
+```bash
+inbox --db TMPDIR/coord.db --json watch --agent worker-d --status pending --timeout-seconds 2
+inbox --db TMPDIR/coord.db --json send --from leader --to worker-d --subject "Build admin editor" --summary "Create the first editor screen"
+```
+
+### 预期输出
+
+- `watch` 退出码为 `0`
+- `watch.data.woke == true`
+- 返回 `thread`、`message`、`event`
+
+### 断言结论
+
+- `watch` 唤醒结果不仅说明“醒了”，还提供触发该唤醒的具体事件上下文
+
+## case: watch-respects-status-filter
+
+### 用例意义
+
+验证 `watch --status` 只会对匹配状态的后续事件唤醒。
+
+### 前置条件
+
+- 存在一个会被推进到 `blocked` 的线程 `THREAD_ID`
+- `watch` 以 `--status blocked` 先启动
+
+### 输入
+
+```bash
+inbox --db TMPDIR/coord.db --json watch --agent worker-c --status blocked --timeout-seconds 2
+inbox --db TMPDIR/coord.db --json update --agent worker-c --thread THREAD_ID --status blocked --summary "Need policy decision"
+```
+
+### 预期输出
+
+- `watch` 只在线程进入 `blocked` 后返回
+- 返回的 `thread.status == "blocked"`
+
+### 断言结论
+
+- `watch` 的状态过滤作用在“事件发生后的线程状态”上
+
+## case: watch-times-out-with-no-activity
+
+### 用例意义
+
+验证在超时时间内没有匹配活动时，`watch` 返回稳定超时契约。
+
+### 前置条件
+
+- 没有新匹配事件会发生
+
+### 输入
+
+```bash
+inbox --db TMPDIR/coord.db --json watch --agent worker-d --status pending --timeout-seconds 1
+```
+
+### 预期输出
+
+- 退出码为 `10`
+- JSON 错误码为 `no_matching_work`
+
+### 断言结论
+
+- `watch` 超时被归类为“无匹配工作”，而不是内部错误
+
+## Notes
+
+- 未传 `--after-event` 时，`watch` 默认从“当前时刻之后”开始等待，不会回放既有事件