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,117 @@
+# Inbox `fetch` Test Plan
+
+## Scope
+
+This document covers agent-scoped candidate thread retrieval via `inbox fetch`.
+
+Shared conventions live in [../_shared/README.md](../_shared/README.md).
+
+## case: fetch-returns-pending-thread-for-target-agent
+
+### 用例意义
+
+验证 `fetch` 能按目标执行者拉取待处理线程。
+
+### 前置条件
+
+- `leader` 已向 `worker-a` 发送至少一个 `pending` 线程
+
+### 输入
+
+```bash
+inbox --db TMPDIR/coord.db --json fetch --agent worker-a --status pending
+```
+
+### 预期输出
+
+- 命令退出码为 `0`
+- 返回 `data.threads`
+- 至少包含一个 `assigned_to == "worker-a"` 且 `status == "pending"` 的线程
+
+### 断言结论
+
+- `fetch` 默认是执行者视角的候选工作列表，不是全局线程扫描
+
+## case: fetch-respects-status-and-limit-filters
+
+### 用例意义
+
+验证 `fetch` 同时遵守状态过滤与返回上限。
+
+### 前置条件
+
+- `worker-a` 拥有多个不同状态的线程
+- 其中至少两个线程满足目标状态过滤条件
+
+### 输入
+
+```bash
+inbox --db TMPDIR/coord.db --json fetch --agent worker-a --status pending,blocked --limit 1
+```
+
+### 预期输出
+
+- 命令退出码为 `0`
+- 返回线程数不超过 `1`
+- 返回的每条线程都满足 `status in ["pending","blocked"]`
+
+### 断言结论
+
+- `fetch` 的 `status` 与 `limit` 会同时生效
+- 返回顺序按 `updated_at` 倒序，优先暴露最新线程
+
+## case: fetch-unread-uses-read-cursor
+
+### 用例意义
+
+验证 `fetch --unread` 基于 agent 的 read cursor 计算未读，而不是仅按线程是否存在新消息。
+
+### 前置条件
+
+- `leader` 已向 `worker-e` 发送一个 `pending` 线程 `THREAD_ID`
+
+### 输入
+
+```bash
+inbox --db TMPDIR/coord.db --json fetch --agent worker-e --status pending --unread
+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
+inbox --db TMPDIR/coord.db --json send --from leader --to worker-e --thread THREAD_ID --summary "Use sentence case" --body "Keep the nav labels in sentence case."
+inbox --db TMPDIR/coord.db --json fetch --agent worker-e --status pending --unread
+```
+
+### 预期输出
+
+- 第一次 `fetch --unread` 返回该线程
+- `show --mark-read` 后，第二次 `fetch --unread` 无匹配结果
+- 新消息追加后，第三次 `fetch --unread` 再次返回该线程
+
+### 断言结论
+
+- 未读判断依赖 `thread_reads.last_read_message_id`
+- 新消息到达会让同线程重新进入未读结果集
+
+## case: fetch-returns-no-matching-work-when-empty
+
+### 用例意义
+
+验证 `fetch` 在没有匹配线程时返回稳定的“无工作”错误契约。
+
+### 前置条件
+
+- 空数据库已完成 `init`
+
+### 输入
+
+```bash
+inbox --db TMPDIR/coord.db --json fetch --agent worker-z --status pending
+```
+
+### 预期输出
+
+- 退出码为 `10`
+- JSON 错误码为 `no_matching_work`
+
+### 断言结论
+
+- 空结果不是成功空数组，而是显式的“无匹配工作”信号