ai-workflow-skill/docs/tests/inbox/fetch/README.md

Inbox fetch Test Plan

Scope

This document covers agent-scoped candidate thread retrieval via inbox fetch.

Shared conventions live in ../_shared/README.md.

case: fetch-returns-pending-thread-for-target-agent

用例意义

验证 fetch 能按目标执行者拉取待处理线程。

前置条件

• leader 已向 worker-a 发送至少一个 pending 线程

输入

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 拥有多个不同状态的线程
• 其中至少两个线程满足目标状态过滤条件

输入

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

输入

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

输入

inbox --db TMPDIR/coord.db --json fetch --agent worker-z --status pending

预期输出

• 退出码为 10
• JSON 错误码为 no_matching_work

断言结论

• 空结果不是成功空数组，而是显式的“无匹配工作”信号