workspace-cli AINative 研发平台需求方案

面向用户的端到端配置、执行、实时观察、人工确认和故障恢复操作见 AI Native 开发流程指南。本文聚焦产品需求、状态约束和验收标准。

本文的 V1 边界描述 AI Native Core CLI 阶段，因此保留“V1 不做 Web UI”的历史约束；后续局域网单用户 Web 扩展见 AI Native Web 操作需求方案。

1. 产品定位

workspace-cli 在“本地需求开发空间管理工具”的基础上扩展为本地优先的 AINative 研发协作平台。平台仍以 Git repo、需求 workspace、feature worktree 和 release branch 为底层开发单元，并把原来由用户手动驱动的需求分析、开发、Review、测试、修 bug 和发布协作，升级为由主 Agent 协调、多个 Worker Agent 执行的状态驱动流程。

V1 保持本地单用户形态，不引入远程服务、多用户权限、Web UI 或外部队列。所有状态继续保存在 workspace-cli home 下的 SQLite 数据库中；所有代码改动仍落在需求 feature worktree 中；release 分支仍是可重建产物，发布仍复用现有 workspace release integrate 和 workspace release publish 的安全语义。

当前实施与验收范围包含 Codex CLI 和 Claude Code。两种 Provider 都必须通过命令构造、MCP、流式结果解析、主 Agent 会话和 Worker 调度测试；本机安装对应 CLI 时执行真实 smoke。

主 Agent 是用户的交互入口和协调者。用户通过主 Agent 聊天来操作 workspace-cli，例如提交需求、查看需求列表、查看需求状态、标记方案终稿、创建 release、观察测试结果。主 Agent 不直接修改业务代码，而是通过 workspace-cli MCP 工具和状态机分配任务、推进阶段、感知需求和 release 状态变化。

Worker 是实际执行分析、编码、测试的本地 Agent 进程池。每个 Worker 绑定一个 Codex 或 Claude Code Agent 配置。Worker 支持配置并行度和最大数量，用于控制同一类任务最多同时跑多少个 Agent 进程。

2. 调研结论

• Codex CLI 支持非交互执行，适合作为分析、编码、测试 Worker。官方文档说明 codex exec 可用于 CI、脚本和管道，支持 JSONL 输出，并且默认在只读 sandbox 中运行；自动化需要改代码时应显式使用 --sandbox workspace-write。参考：https://developers.openai.com/codex/noninteractive。
• Codex 支持 MCP server 配置，MCP server 可以是 stdio 本地进程，也可以是 streamable HTTP 服务；Codex 会读取 MCP server 的 instructions 并把工具提供给 Agent。参考：https://developers.openai.com/codex/mcp。
• Codex 的 MCP server 配置来自 config.toml 中的 [mcp_servers.<name>] 或等价 -c mcp_servers.<name>.* 覆盖，而不是 provider 进程参数里的 --mcp-config。因此 workspace-cli 启动 Codex 主 Agent 或 Codex Worker 时，必须生成 job/session scoped 的配置记录，并通过 -c 注入只带 capability token 的 workspace mcp serve；不能把 CODEX_HOME 改到临时目录，否则真实 Codex 会丢失用户登录态。
• Codex 自身也可以作为 MCP server 暴露给更高层编排系统，官方示例用 codex mcp-server 让 Agents SDK 调用 Codex，并支持多 Agent workflow。参考：https://developers.openai.com/codex/guides/agents-sdk。
• Codex 的低摩擦本地权限模型是 workspace-write 加 on-request，自动化可以使用 never，但 danger-full-access 只适合外部已隔离环境。参考：https://developers.openai.com/codex/concepts/sandboxing。
• Claude Code CLI 支持 claude -p 非交互模式、--output-format json|stream-json、--mcp-config、--system-prompt-file 和 --permission-mode，因此可以作为另一个 Worker provider。参考：https://code.claude.com/docs/en/cli-reference。
• Claude Code 也支持 MCP，官方建议通过 MCP 连接 issue tracker、监控、数据库、GitHub 等外部工具；它也可以通过 claude mcp serve 作为 stdio MCP server 被其他应用连接。参考：https://code.claude.com/docs/en/mcp。
• 当前仓库已经实现本地 repo、requirement、feature worktree、ready、release integrate、release publish 和 reopen 修 bug 的底层流程，因此 AINative 方案应叠加在现有服务层上，而不是替换现有 Git/release 状态机。

3. 核心概念

• AINative 协作模式：由 workspace-cli 启动主 Agent、Worker pool、任务队列和 MCP 控制面，让 Agent 根据需求状态自主推进分析、开发、测试和修复。
• 主 Agent：面向用户的协调 Agent。它读取需求和 release 状态，设置需求的分析 Agent、Coding Agent、测试 Agent，创建任务，推进状态，并向用户解释当前进展和阻塞点。
• Agent 配置：可复用的 Agent 定义，包含 provider、角色、模型、系统提示词、工具权限、命令模板、环境变量和默认工作目录。
• Coordinator daemon：本地常驻调度进程。它监听需求、release、job 和 bug 状态变化，创建缺失的系统 job，必要时启动 coordinator Agent job 来完成 Agent 分配、阻塞解释和下一步建议。
• Worker pool：某一类任务的执行池，绑定一个 Agent 配置，包含 parallelism 和 max_workers。parallelism 限制同时执行的 job 数，max_workers 限制本地最多保留多少个存活 worker 进程。
• Worker instance：daemon 启动的一个具体执行槽，负责 claim job、运行 provider 进程、上报 heartbeat 和写入 run 结果。
• Agent job：一个可调度任务，例如“分析需求”“Review 技术方案”“执行开发步骤 3”“测试 release”“修复 bug”。job 是状态机和 Worker pool 的边界。
• Agent run：job 的一次执行尝试，记录 provider、命令、开始/结束时间、退出码、stdout/stderr 摘要、结果 artifact 和错误。
• Agent run event：Agent run 执行过程中的增量事件，例如开始、阶段进展、模型输出摘要、tool call、artifact 创建、测试命令输出、阻塞原因和结束。
• 人工确认请求：Agent 或 workspace-cli 在需要用户判断时创建的确认项，例如需求澄清、方案终稿确认、发布确认、测试命令缺失、技术方案不可实施。
• Artifact：需求、release 或 release test run 生命周期中的文档产物，包括需求设计方案、技术实现方案、分析 Review、开发步骤计划、步骤 Review、技术实现报告、总 Review 报告、测试报告和 bug 修复报告。
• Review policy：每个阶段的 review 门槛配置，例如最大 review 次数、通过条件、允许的最高风险级别。
• Bug：测试 Agent 在 release 集成测试中发现的问题。Bug 必须关联一个需求，并驱动 Coding Agent 回到该需求 feature 分支修复。
• Release test run：一次 release 集成测试任务，记录测试 Agent、包含需求范围快照、测试命令、Review 结论、bug 列表、测试报告和通过状态。
• MCP 控制面：workspace-cli 暴露给 Agent 的结构化工具集合。Agent 通过 MCP 操作需求、artifact、job、release 和 bug，而不是自由拼接 shell 命令。
• Capability token：job-scoped 权限令牌。不同角色的 Agent 只能调用自己阶段允许的工具和对象，避免分析 Agent 改代码、测试 Agent 直接改 release 分支。

4. 需求状态

AINative 流程新增 workflow_status 字段，不替代现有 requirements.status、ready_at、completed_at 和 archived_at。现有字段继续服务 Git/release 底层流程；workflow_status 表示 Agent 协作阶段。

阻塞、失败、等待人工输入不作为业务状态。它们记录在 agent_jobs.status、requirement_bugs.status、release_test_runs.status、human_approval_requests.status、requirement_status_events 和 release_status_events 中，需求仍停留在当前业务阶段。

5. Agent 和 Worker 配置需求

5.1 Agent 配置

每个 Agent 配置必须支持：

• name：唯一名称，例如 main-coordinator、codex-analysis、codex-coding、claude-test。
• provider：codex 或 claude。
• role：coordinator、analysis、coding、testing。
• model：provider 模型名，可为空表示 provider 默认。
• system_prompt：内联文本或 prompt 文件路径。
• command：provider 命令模板，默认由 workspace-cli 生成。
• sandbox：provider 权限策略，例如 Codex 的 workspace-write 或 Claude 的 permission mode。
• approval_policy：自动化时默认无交互；主 Agent 交互模式可以保留用户确认。
• enabled：健康检查失败时可禁用。
• metadata：JSON 字段，用于保存 provider 特有配置。

analysis、coding、testing 和后台 coordinator job 启动时必须实际使用所绑定 Agent 的 model、system_prompt 和 system_prompt 文件内容，不能只在 agent show 中保存。内联 prompt、文件 prompt 和 job input 按固定顺序组合；prompt 文件不可读时 job 不得启动 provider，路径错误写入 job last_error 并按正常 retry/max-attempts 规则处理，claimed worker 必须恢复 idle。达到最大次数后 job 进入 failed，但这个已收敛的 job-level 配置错误不能终止 daemon。

5.2 Worker 配置

每个 Worker pool 必须支持：

• name：唯一名称。
• role：该 pool 可处理的 job role。
• agent_id：默认使用的 Agent 配置。
• parallelism：同一时刻最多执行多少个 job。
• max_workers：daemon 最多保留多少个存活 worker instance；即使 parallelism 更大，也不能超过该进程上限。
• poll_interval：空闲时轮询间隔。
• lease_seconds：job claim 租约时间。
• enabled：是否参与调度。

daemon 必须真正并发运行同一 pool 中不超过 min(parallelism, max_workers) 个 provider job，不能只在一个 tick 内批量 claim 后串行执行。为了保护 workspace，带 requirement_id 的 feature-workspace job 按 requirement 串行；不带 requirement 但带 release_id 的 release-workspace job 按 release 串行。不同 requirement 的 bugfix 即使属于同一 release，也允许并发。

parallelism 和 max_workers 是两个独立配置，允许 parallelism > max_workers；有效并发始终取两者最小值。daemon 必须按各 pool 的 poll_interval 持续调度，已有 provider run 不得阻塞其他 pool 的新 job。运行中的 heartbeat 必须同时刷新 worker heartbeat 和 job lease。

需求 priority 为正整数且数值越小越优先，默认 100。需求关联 job 的实际排序先比较需求 priority，再保留阶段内部的 Review、修复和步骤顺序；澄清修改 priority 时只重排 queued job。

daemon 创建的 worker key 必须在 retained lost/stopped 历史行存在时仍保持唯一，并包含 pool identity；replacement 不能使用 live worker count 直接复用旧 key。丢失 worker 后下一 tick 必须能创建 distinct replacement 并恢复容量。

daemon 默认由 workspace agent daemon start 作为后台单实例启动，status 和 stop 必须读取真实运行状态。workspace ai start 默认确保 daemon 已运行。daemon 使用持久化 heartbeat/lease 支持崩溃接管，并且退出时只能停止属于本实例的 Worker。

5.3 健康检查

• Codex provider 必须检查 codex --help 可执行。
• Claude provider 必须检查 claude --help 可执行；如果本机没有 claude，对应 Agent/Worker 仍可保存，但状态为 unavailable，daemon 不会调度。
• MCP 控制面必须提供 workspace mcp health，通过同一 stdio Serve 边界发送带临时 coordinator capability 的 tools/list，校验响应非空并展示 transport、tool count 和 tool names；mcp serve CLI 必须使用 Cobra 的输入流，以便真实命令路径和测试都走同一 stdio 协议。
• Worker 启动前必须检查对应需求 workspace、release workspace 或 artifact 目录存在。
• Coding/testing job 使用 job input 中的 requirement/release workspace 作为 provider CWD，并在 provider 启动前校验该目录和 artifact 目录真实存在且为目录；缺失时不得启动 provider，job 进入正常 retry/max-attempts 收敛并保留路径错误。
• analysis、后台 coordinator 等没有业务 workspace 的 job 必须使用 job-attempt scoped runtime CWD；交互式主 Agent 必须使用 session-scoped runtime CWD。真实 workspace home 只作为 MCP --home 和控制面环境变量传递，不能作为 workspace-write provider 的可写根目录，否则 Agent 可以绕过 capability 直接修改 workspace.db。

6. 实时执行可见性和人工确认

6.1 实时执行可见性

用户必须能在 Agent 工作时实时看到执行过程，而不是等 job 结束后只看报告。

必须支持：

• 通过主 Agent 聊天查看某个需求、release、job 的当前阶段、active jobs、当前 run、Worker、Agent、开始时间、heartbeat、最近事件和下一步。
• 通过 CLI 观察执行流，例如 workspace req watch <req>、workspace release watch <release>、workspace job watch <job-key>、workspace run tail <run-id>。
• 展示 Agent run event，包括阶段进展、模型输出摘要、tool call 摘要、测试命令输出摘要、artifact 创建、Review 结论、bug 创建和阻塞原因。
• 原始 provider stdout/stderr 仍写入 runtime 文件；DB 中只保存用户可读摘要、事件类型、关联对象和文件路径，避免数据库膨胀。
• 对用户隐藏 capability token、provider API key、环境变量 secret 和过长原始输出；capability token 不能出现在 agent_runs.command、provider event、JSON argv 摘要或可通过 MCP 读取的默认 raw tail 中，即使 provider 只输出 standalone signed token 也必须脱敏。只有显式本地管理员模式才能读取未脱敏文件。

6.2 人工确认和需求澄清

以下场景必须创建人工确认请求，并让用户实时可见：

• 需求描述不清，需要用户补充范围、验收标准、repo 或优先级。
• 分析阶段已生成方案，需要用户选择或编辑需求设计方案和技术实现方案终稿。
• Coding Agent 判断技术方案不可实施或存在高风险分歧，需要用户或主 Agent 重新决策。
• 测试阶段无法确定或执行单测命令，需要用户补充命令或确认阻塞；不能用跳过测试来进入测试完成。
• release publish 前必须确认已测试和允许发布。
• Agent 需要超过当前 sandbox/approval policy 的权限时，必须停下等待用户确认。

人工确认请求必须包含确认类型、关联 requirement/release/job、问题说明、可选操作、默认建议、创建者、创建时间、状态和响应字段；pending 时响应字段为空。等待确认期间，相关 job 标记 blocked 或 waiting_user_input，业务 workflow status 保持当前阶段；用户响应后，主 Agent 或 daemon 根据响应继续创建下一步 job 或保持阻塞。

人工确认的响应必须是结构化数据，而不是只有自由文本：

• requirement_clarification：用户补充 message，可选更新 description、acceptance_criteria、repo 或 priority。
• artifact_finalization：用户选择或编辑终稿，响应必须包含 final_requirement_design_artifact_id 和 final_technical_design_artifact_id；service 在关闭 approval 后完成 artifact finalize，再允许需求进入开发阶段。
• implementation_blocker：用户选择 continue、replan 或 block，并可补充决策说明。
• test_command_missing：用户提供 test_command，或明确选择 block；不能静默跳过测试。
• publish_confirmation：用户响应 confirm=true|false，只有 true 才允许进入发布。
• provider_permission：用户响应授权范围、授权时长、允许的 sandbox 和 approval policy；授权后只在同一 job 的有效 grant 范围内恢复执行，未授权时 job 保持阻塞或失败。

7. 需求分析阶段

7.1 输入

• 用户提交的需求标题、描述、验收条件、影响 repo、上下文文件或链接。
• 当前 repo 列表、需求历史、release 状态。
• 主 Agent 分配的分析 Agent 和 Review policy。

7.2 过程

1. 用户通过主 Agent 或 CLI 提交需求，需求进入 pending_acceptance。
2. 主 Agent 采纳需求，补齐 repo 范围、分析 Agent、Coding Agent、测试 Agent 和 Review policy。
3. 需求进入 pending_analysis，coordinator daemon 的 watch loop 创建 analysis job。
4. 分析 Agent 生成需求设计方案 artifact 和技术实现方案 artifact。
5. Review job 对方案进行审查，输出独立 review artifact，包含风险等级、问题列表、是否通过和修改建议。
6. 如果未达到通过门槛，分析 Agent 根据 Review 结果生成下一版方案。
7. 循环直到达到 review policy 或超出最大次数。
8. 达到门槛后，需求进入 analysis_completed，用户可以查看、编辑并标记终稿。

7.3 Review policy

分析阶段至少支持两种通过门槛：

• strict：Review 必须没有问题才通过。
• no_high_risk：允许低风险或中风险建议存在，但不允许高风险问题。

每次 Review 必须单独生成 artifact，不覆盖历史版本。终稿只能从已生成的需求设计方案和技术实现方案中选择，也允许用户编辑后另存为用户修订版终稿。

7.4 输出

• requirement_design：需求设计方案，可多版本。
• technical_design：技术实现方案，可多版本。
• analysis_review：每次 Review 的记录。
• analysis_final_artifact_id 和 technical_final_artifact_id。

8. 开发阶段

8.1 输入

• 已标记终稿的需求设计方案和技术实现方案。
• 需求绑定 repo；进入开发前由 workspace-cli 准备 feature workspace。
• Coding Agent 配置和开发阶段 Review policy。

8.2 过程

1. 用户或主 Agent 将 analysis_completed 推进为 pending_development。
2. workspace-cli 调用开发 workspace 准备流程，为已存在的 AINative 需求创建或恢复 feature worktree；该流程不得创建第二条 requirement 记录。
3. workspace 准备成功后，需求进入 developing，随后 Coding Agent claim 开发 job。
4. Coding Agent 基于技术实现方案生成开发步骤计划 artifact。
5. daemon 将步骤拆成 step job；每个 step job 在需求 feature worktree 中执行。
6. 每个步骤完成后，必须创建独立 step review job。
7. Review 通过后才能进入下一步；未通过时创建修复 job，仍在同一步内循环。
8. 所有步骤完成后，Coding Agent 生成技术实现报告和总 Review 报告。
9. Coding Agent 调用底层 req finish 语义，提交、推送 feature 分支并清理 worktree，使需求达到 ready。
10. 需求进入 development_completed。

8.3 约束

• Coding Agent 只能修改对应需求的 feature worktree。
• 开发 workspace 准备流程必须是幂等的：已存在干净 worktree 时复用，缺失时按绑定 repo 创建，遇到脏 worktree 或路径冲突时阻塞并保留需求状态。
• 不允许在 release worktree 中做长期修复。
• 每次 Review 都必须写入独立 artifact。
• 如果 req finish 进入 cleanup-pending，需求保持 developing，直到 cleanup 成功或人工处理。
• 如果 Coding Agent 发现技术方案不可实施，必须创建 implementation_blocker artifact，并把 job 标为 blocked，等待主 Agent 或用户处理。
• implementation step 和 step fix 的输入必须声明结构化 result contract；Coding Agent 返回 implementation_blocker.reason 时，daemon 自动写入独立 blocker artifact，并在同一 DB 事务内创建 typed approval、写实时 approval events 和阻塞 source job，不能继续创建 step Review。同一需求内不同 source job 或不同 run 的 blocker 必须分别保留 job/run-scoped approval，不能按 requirement 合并。
• implementation_blocker 选择 replan 并定稿新技术方案后，必须启动新的开发周期；旧周期的 plan、step、Review、fix 和 report 只保留为历史记录，不能阻止新作业创建，也不能混入新周期报告。
• daemon 必须在旧周期 job claim 后和 provider 运行期间复核当前开发周期；发现 requirement 已离开开发阶段或终稿 technical design 已切换时，取消旧 provider context 和 job，不允许继续产生 workspace/MCP 副作用或研发完成状态。

8.4 输出

• implementation_plan：按步骤展开的开发计划。
• implementation_step_review：每个步骤的 Review。
• implementation_report：技术实现报告。
• implementation_review：研发阶段总 Review。

9. 集成测试和修 bug 阶段

9.1 Release 创建

用户选择多个 development_completed 需求创建 release。release 仍复用现有 workspace release create、integrate、publish 底层流程，但新增测试 Agent 和 test run 记录。

9.2 测试循环

1. release integrate 成功后，相关需求进入 pending_testing。
2. 测试 Agent claim release test job，需求进入 testing。
3. 测试 Agent 根据需求设计方案、技术实现方案、实现报告、release worktree 和 test command 配置执行整体 Review 和单测；创建 test run 时必须按 requirement + repo 记录本次 active release scope、feature commit 和 release commit 快照。
4. test command 的来源按优先级解析：workspace release test start --test-command，来源记为 explicit；release 创建时记录的默认测试命令，来源记为 release_default；全局 agent_default_test_command，来源记为 agent_default。如果都为空，测试 Agent 可以基于仓库内容推断命令，来源记为 inferred，但必须在测试报告中记录实际执行命令；无法确定或执行任何单测时创建关联当前 release_test_run 的 test_command_missing approval，用户补充命令后来源记为 user_supplied 并恢复该 test run 重试，用户明确选择 block 后 test run 才标记 blocked，不能进入测试完成。
5. 如果发现问题，测试 Agent 创建 bug，关联具体需求、repo、文件、复现步骤、失败命令和风险等级。Agent 输出的显式 requirement ID/key 和 repo ID/name 必须命中当前 release_test_run_requirements immutable snapshot；未知或越界对象必须拒绝，不能退化到同 release 的 active membership。省略 repo 时只能从该 requirement 的唯一 snapshot repo 推断，多 repo scope 必须显式指定。status=failed 但没有 bug 的结果不得完成 job，必须阻塞 test run/job 并产生用户可见诊断。
6. bug_create 创建 open bug、把 requirement 退回 pending_development 和写 requirement_status_events 必须在同一事务中完成；event 保留 testing/coordinator actor、reason 和 created-by job。任一写入失败时 bug、workflow 和 event 全部回滚。
7. 主 Agent 或 coordinator watch loop 感知 bug 后，为对应需求创建 bugfix job。
8. Coding Agent 使用 req reopen 恢复 feature worktree，在 feature 分支修复 bug。
9. 修复完成后再次 req finish，release 标记 stale，重新 integrate。
10. 测试 Agent 重新执行 release test job。
11. 所有 bug 关闭且测试通过后，相关需求进入 testing_completed；release 只能由当前 workflow_status=testing 且该 release 最新的 passed release_test_run 进入 testing_completed，并记录 active_test_run_id。同一 completed test run 重试必须幂等且不新增 event，晚到旧 job 不得回退 pending-release/releasing/released/stale。随后发布确认流程基于 active_test_run_id 创建 publish_confirmation，再把 release 和 active requirements 推进到 pending_release；后续 release scope、需求 feature commit 或外部目标分支变化会使该 test run 失效并要求重新 integrate/test。

测试 Agent 不得修改任何 release repo worktree。daemon 在 provider 启动前和结束后分别执行 Git dirty 检查；测试前已 dirty 时不得启动 provider，测试过程中产生 tracked 或 untracked 变更时不得采纳测试结果。两种情况都把 release test job 和 test run 标为 blocked，保留 release/requirement 业务阶段，写入用户可见的 release 诊断事件；测试过程中产生的变更还要写独立 run event。用户清理 worktree 后必须显式 retry，不能自动丢弃或回滚文件。

9.3 发布

发布沿用现有 release publish 语义：

• 发布前必须显式确认已测试。
• release worktree 和 publish worktree 必须干净。
• 发布目标分支有外部新 commit 时必须重新 integrate 和重新测试。
• publish-in-progress 期间禁止变更 release 范围或 reopen 相关需求。
• release 进入 pending_release 前必须已处于 testing_completed，且 active_test_run_id 指向当前通过的 release_test_run。发布确认流程基于该 test run 创建 publish_confirmation approval；approval payload 必须展示 test run 的 requirement+repo+commit 快照摘要。choice=confirm 等价于 approved + confirm=true；任何缺少 confirm=true 的 approved response 必须在写库前拒绝并保持 pending。用户确认前不得执行 publish，用户拒绝时 release 保持 pending_release 并记录状态事件，daemon 不自动重建同一 release/test run 的确认。
• 发布前必须校验当前 active release 的 requirement 集合、repo 集合和每个 requirement+repo 的提交与当前通过的 release_test_run 快照一致；不一致时拒绝发布并要求重新测试。
• 已处于 publish_in_progress 的 release 如果在重试 publish 前发现 snapshot 不一致，必须保持 publish_in_progress 并要求人工处理，不能自动改成 stale 或进入重测队列。
• 发布成功表示 release 代码已通过现有 publish 流程合并到目标默认分支 main 或 master。
• 发布成功后，active 集成范围内需求进入 released。

10. 主 Agent 协调需求

主 Agent 必须具备以下能力：

• 通过聊天创建需求、补充需求上下文、查询需求列表和状态。
• 根据默认规则或用户指令设置需求的分析 Agent、Coding Agent、测试 Agent。
• 监听需求和 release 状态变化，包括新需求、分析完成、开发完成、测试 bug、release stale、publish-in-progress。
• 主 Agent 的监听可以由两种运行形态完成：workspace ai start 的交互式 Codex CLI 会话负责用户聊天；workspace agent daemon start 的 coordinator watch loop 负责无交互时的状态扫描，并在需要主 Agent 判断时用默认主 Agent 配置启动非交互 coordinator_decide run。
• coordinator watch loop 必须覆盖 pending_acceptance 新需求、analysis_completed、development_completed、open 测试 bug、release stale、release publish_in_progress 和非 coordinator blocked job；每个 job input 必须带触发类型、实体/源 job 标识、当前状态、最近原因和允许的下一步约束，不能只传一个状态字符串。
• 需求/release 状态监听以最新匹配当前状态的 status event ID 作为观察代次，同一事件重复轮询不重复创建 job，新 status event 可以触发新的判断；open bug 以 bug ID 幂等，blocked job 以 source job ID + attempt 幂等。没有历史 status event 的兼容数据退化为实体+当前状态 key。
• publish_in_progress 的幂等诊断必须先于 coordinator 扫描写入，使主 Agent 看到 manual recovery 原因；coordinator 只能解释 next action，不能把该 release 自动降级为 stale。coordinator 自身 blocked job 不得递归生成新的 coordinator job。
• 在状态不满足自动推进条件时向用户解释阻塞原因。
• 实时展示 Agent 执行过程、pending approval、最近 run event 和 artifact 变化。
• 在出现需求澄清或人工确认请求时，主动询问用户并把用户响应写回 workspace-cli。
• 只通过 workspace-cli MCP 工具变更状态，不直接编辑 SQLite。
• 主 Agent 进程工作目录与 workspace home 状态目录隔离；Codex --cd 和 Claude 进程 CWD 指向 session runtime workspace，MCP server 仍使用真实 --home。
• 可以查看 artifacts，并把用户选择的方案标记为终稿。
• 可以为 release 创建测试任务和发布任务，但发布前必须保留用户确认入口。

11. MCP 控制面需求

workspace-cli 必须提供 workspace mcp serve，至少包含以下工具族：

• req_submit：提交新需求。
• req_list / req_show / req_watch：查询需求和聚合需求执行流。
• req_assign_agents：设置分析、Coding、测试 Agent。
• review_policy_list / review_policy_upsert / review_policy_remove：管理分析和开发阶段 Review 门槛；被需求引用的 policy 不允许删除。
• req_update_workflow_status：按状态机推进需求。
• req_prepare_workspace：为已存在需求创建或恢复 feature worktree。
• artifact_create / artifact_list / artifact_show / artifact_finalize：管理 requirement、release 和 release test run 文档产物。
• job_create / job_list / job_show / job_update：管理 Agent job。
• job_watch / run_tail：读取 Agent 执行过程事件和输出摘要。
• approval_list / approval_show / approval_respond：管理人工确认请求。
• bug_create / bug_list / bug_update：管理测试 bug。
• release_create / release_test_start / release_test_status / release_status / release_watch / release_integrate / release_publish：操作 release、release test run 和聚合 release 执行流。

MCP 工具必须基于 capability token 做权限校验。token 至少包含 role、requirement_id、release_id、release_test_run_id、job_id、allowed_tools 和 expires_at。

交互式主 Agent 使用 0600 的 session capability file，token 采用短有效期并在会话运行时轮换。MCP 每次调用必须验证 session 仍为 running；会话结束后立即撤销并删除 token 文件。

testing token 读取 requirement artifact，或 create/list/update release test bug、创建 bugfix job 时，目标 requirement/bug 必须属于 token 的 scoped release active membership；token 带 release_test_run_id 时必须优先以该 test run 的 immutable requirement snapshot 和 bug test_run_id 为准，不能被同时携带的 release_id 放宽。bug_create 省略 test_run_id 时必须默认绑定 token 的 release_test_run_id，显式指定其他 run 时必须拒绝，即使两个 run 属于同一个 release。bug_create 默认使用 token 的 job_id 作为 created-by audit；release-test job 的 release 和 input 中的 release_test_run_id 必须同时匹配。

release_test_run_id 的优先级适用于全部 MCP surface，而不只 bug：requirement list/show/watch、job list/show/watch、run tail、approval list/show、release-test artifact 和 watch 聚合都不能通过同一个 release_id 读取其他 test run。run-scoped worker 创建子 job 时必须自动绑定当前 test run，显式冲突必须拒绝；该 worker 也不能启动新 test run 或重新 integrate release。主 Agent 的 coordinator capability 保留完整跨周期视图。

run-scoped worker 创建子 job 时，省略 input/input_json 等价于空对象，仍必须成功默认绑定当前 test run。requirement status event 没有独立 test-run 字段时，只能向 run-scoped token 返回 job_id 可证明属于当前 run 的事件；无 job scope 或其他 run 的事件必须隐藏，coordinator 仍保留完整审计视图。

12. 非目标

• V1 不做远程多用户平台。
• V1 不做 Web UI。
• V1 不接管 GitHub PR、GitLab MR、Jira、Linear 或外部 issue 平台。
• V1 不把 release 分支作为长期修复分支。
• V1 不实现云端 Worker。
• V1 不保存或代理 OpenAI、Anthropic API key；provider 认证由对应 CLI 或用户环境负责。
• V1 不自动绕过 provider 的安全策略。

13. 验收标准

• 用户可以配置主 Agent、分析 Agent、Coding Agent、测试 Agent。
• 用户可以配置 Worker pool 的并行度和最大 worker 数。
• 用户可以为需求保存验收标准、正整数优先级，并分别绑定分析和开发 Review policy。
• 用户可以通过主 Agent 或 CLI 提交需求，并看到需求进入 pending_acceptance。
• 主 Agent 和 Worker Agent 启动后都只能通过带 capability token 的 workspace-cli MCP 工具操作平台状态。
• 主 Agent 可以为需求设置分析、Coding、测试 Agent。
• 分析阶段可以循环生成方案和 Review，并保存每次 artifact。
• 用户可以查看、编辑并标记需求设计方案和技术实现方案终稿。
• 用户可以实时查看需求、release、job 和 run 的执行过程。
• 需求澄清、方案终稿、测试命令缺失和发布确认都必须进入人工确认请求，不允许静默跳过。
• 进入开发前，workspace-cli 可以为已存在的 AINative 需求准备 feature worktree，且不会重复创建 requirement。
• 开发阶段可以按步骤执行、逐步 Review、生成实现报告和 Review 报告。
• 测试阶段可以创建 release test run，记录实际执行的 test command、测试报告和 requirement+repo+commit 快照，发现 bug 时能关联需求并驱动 feature 分支修复。
• release 分支不允许直接修复；修 bug 必须回 feature 分支。
• 所有关键状态变化都有 status event。
• release 的测试、stale、发布确认、publish-in-progress 和 released 变化都有 release status event。
• release 推进 active requirements 到 testing_completed、pending_release、releasing 或 released 时，每个 requirement 必须在同一 transaction 内写入对应 requirement status event。
• AINative release scope add/remove、feature/base/release branch 或 snapshot 变化导致 stale 时，必须原子写 status=stale、workflow_status=stale 和 release status event；legacy manual_release 仍保持原工作流兼容。
• AINative requirement submit 必须原子创建 requirement、repo bindings 和初始 status event；Agent assignment、进入 pending_development 以及 daemon 推进 requirement/release workflow 时，状态与对应 event 必须在同一 transaction 中提交。
• release-test bug 创建必须原子提交 bug、需求回退 pending_development、requirement status event 和用户可见 bug_created run event；任一写入失败时全部回滚。
• publish_confirmation 的 approve、cancel、reject response 必须与 release status event 及可用 run event 在同一 transaction 提交，不能先提交 response 再补写可见事件。
• 没有测试命令时，waiting_user_input release test run、immutable requirement+repo snapshots、test_command_missing approval 和 approval-request status event 必须在同一 transaction 创建；任一写入失败时不能留下 orphan test run。
• 有测试命令时也必须在同一 transaction 创建 queued test run 与完整 immutable snapshots；daemon 不得为缺失、部分或已不匹配当前 active scope 的历史 queued/waiting run 创建测试 job，而应阻塞旧 cycle 并提示启动新 cycle。
• invalid failed-output 的 blocked test run、用户可见 run event、failed agent run、blocked agent job 和 release status event 必须原子提交；中间写入失败不能留下 split blocked state。
• publish confirmation 的 confirm=true 不只在 service 校验，所有 store responder 也必须保持该持久化不变量，通用 responder 不得绕过专用事务。
• publish_confirmation create API 只能创建 pending request；任何 terminal initial status 必须拒绝，approved 只能由验证 confirm=true 的 response transaction 产生。
• MCP testing Agent 创建 test-run bug 时必须绑定 capability job 的 active Agent run，并在 bug transaction 中写用户可见 bug_created event；不存在 active run 时拒绝创建，不能只写业务状态。
• test-run capability 不得用 caller-supplied created_by_job_id 替换 capability job；显式值不一致时必须拒绝。service/store 直接创建 test-run bug 同样必须提供相互匹配的 job/run，不能存在没有 realtime event ownership 的旁路。
• release-test provider 的任何结果解析或 schema 校验错误都必须进入 atomic invalid-output blocker，包括空/非法 JSON、非法 status、缺少 test report 和 failed 无 bug；不能只对某一个错误子类型结构化阻塞。
• release worktree pre/post dirty blocker 与 invalid-output blocker 使用同一原子 execution-block transaction；run 尚未启动时可以省略 run event，run 已存在时 event 和 failed run 都是事务必需项。
• req reopen 必须在恢复 feature worktree 的同一业务事务中把受影响的 AINative release 标为 workflow stale 并写 event；重集成/重测必须监听 authoritative workflow_status=stale，同时兼容升级前仅 legacy status 为 stale 的记录。
• 同一 release 存在多个 test run 时，run-scoped capability 的 requirement/release watch 只返回当前 run 的 membership、jobs、approvals、bugs、status/run events 和 test artifacts，不得暴露或修改其他周期。
• 所有 Agent 执行都有 job 和 run 记录。
• 所有 Agent 执行过程都有可追踪的 run event；所有等待用户判断的事项都有人工确认记录。
• Codex provider 在本机可用时可以跑 fake 或真实 job。
• Claude provider 不在 PATH 时不会破坏 daemon，可展示 unavailable。