workspace-cli AI Native 开发流程指南

本文面向实际使用 workspace-cli 组织 AI Native 研发的用户，说明如何配置主 Agent、专业 Agent 和 Worker pool，以及一个需求如何从提交、分析、开发、集成测试一直流转到发布。需求定义和边界见 AINative 研发平台需求方案，系统内部实现见 AINative 研发平台技术实现方案。

1. 流程目标

AI Native 模式不是让一个 Agent 在一个长会话里完成全部工作，而是把研发过程变成可观察、可恢复、带人工门禁的状态机：

• 主 Agent 是协调者。它和用户对话，观察需求与 release 状态，分配分析、开发、测试 Agent，并在需要人工判断时解释上下文。
• Worker Agent 是执行者。分析 Agent 产出并 Review 方案，Coding Agent 按计划修改 feature worktree，测试 Agent在只读 release workspace 中做整体 Review 和测试。
• daemon 是可靠调度器。即使主 Agent 交互会话退出，它仍可扫描状态、创建 Job、续租 Worker、恢复过期任务并推动已满足条件的流程。
• SQLite、artifact 文件和 Git 分支是事实来源。聊天记录不是流程状态，Agent 不得绕过 MCP 直接修改控制面数据库。
• 用户始终可以实时查看执行事件，并在需求澄清、方案定稿、权限提升、测试命令和发布确认等节点作出决定。

需求提交 -> 分析与 Review 循环 -> 人工定稿 -> 分步开发与 Review 循环
        -> 多需求 Release -> 集成测试与 Bug 修复循环 -> 人工发布确认 -> 发布

2. 角色和职责

一个 Agent 配置代表 Provider、模型、系统提示词和执行策略；一个 Worker pool 则把某个 role 绑定到一个 Agent，并定义并行度、最大 Worker 数、轮询间隔和 lease。多个 pool 可以使用不同 Provider，例如分析使用 Codex、开发使用 Claude Code、测试再使用 Codex。

3. 首次配置

3.1 初始化并注册代码仓库

workspace init
workspace repo add backend git@github.com:example/backend.git --base main
workspace repo add frontend git@github.com:example/frontend.git --base main
workspace repo sync

workspace-cli home 的解析优先级为 --home、WORKSPACE_CLI_HOME、~/.workspace-cli。同一套 AI Native 流程必须始终指向同一个 home，否则会连接到不同的数据库和 runtime。

3.2 配置主 Agent 和专业 Agent

workspace agent add main-codex \
  --provider codex \
  --role coordinator \
  --system-prompt-file ./prompts/coordinator.md

workspace agent add analysis-codex \
  --provider codex \
  --role analysis \
  --sandbox read-only \
  --system-prompt-file ./prompts/analysis.md

workspace agent add coding-claude \
  --provider claude \
  --role coding \
  --sandbox workspace-write \
  --system-prompt-file ./prompts/coding.md

workspace agent add testing-codex \
  --provider codex \
  --role testing \
  --sandbox read-only \
  --system-prompt-file ./prompts/testing.md

coordinator 与 Worker 的权限模型不同。Worker 即使配置了 danger-full-access，执行时也只会规范化为当前登记 worktree 内的 workspace-write，不会得到宿主文件系统或控制面文件的写权限。

配置后先做健康检查：

workspace agent list
workspace agent health main-codex
workspace agent health analysis-codex
workspace agent health coding-claude
workspace agent health testing-codex

健康检查失败时不要启动任务。先处理 Provider CLI 缺失、认证、模型名、sandbox backend 或系统提示词路径问题。

3.3 配置 Review 门槛

workspace review-policy add strict-analysis \
  --stage analysis \
  --max-rounds 5 \
  --pass-condition no_findings \
  --max-severity none

workspace review-policy add development-gate \
  --stage development \
  --max-rounds 3 \
  --pass-condition max_severity \
  --max-severity low

Review policy 有两个常用模式：

• no_findings：Review 必须没有剩余问题才通过，适合高风险需求分析。
• max_severity：允许不高于 max-severity 的已知问题，适合明确接受低风险项的开发步骤。

max-rounds 是自动循环上限，不是“达到次数即自动通过”。超过上限但仍不满足门槛时，流程必须停止并等待人工处理，不能静默进入下一阶段。

3.4 配置 Worker pool

workspace worker add analysis-pool \
  --role analysis \
  --agent analysis-codex \
  --parallelism 2 \
  --max-workers 2 \
  --poll-interval-ms 2000 \
  --lease-seconds 300

workspace worker add coding-pool \
  --role coding \
  --agent coding-claude \
  --parallelism 3 \
  --max-workers 4 \
  --poll-interval-ms 2000 \
  --lease-seconds 300

workspace worker add testing-pool \
  --role testing \
  --agent testing-codex \
  --parallelism 1 \
  --max-workers 1 \
  --poll-interval-ms 2000 \
  --lease-seconds 300

• parallelism 限制 pool 同时运行的 Job 数。
• max-workers 限制 pool 的存活 Worker instance 数，必须大于或等于期望并行度。
• 带 requirement workspace 的 Job 按 requirement 串行，避免两个 Coding Agent 同时改同一 feature worktree。
• 不同 requirement 可以并行；release-only Job 按 release 串行；同一 release 中不同 requirement 的 Bug 修复仍可在各自 feature worktree 并行。
• daemon 会在 Provider 执行期间续租。lease 一旦过期就不能被迟到 heartbeat 复活，只能先收敛旧 run 再重新 claim。

3.5 启动控制面和主 Agent

workspace agent daemon start
workspace agent daemon status
workspace ai start --agent main-codex

workspace ai start 会为主 Agent 创建有时效的 coordinator capability，并默认确保 daemon 已运行。主 Agent 退出后 daemon 可以继续处理已有任务；重新进入交互时再次运行 workspace ai start --agent main-codex。可通过 workspace ai sessions 查看交互会话审计记录。

4. 需求状态总览

workspace req create 创建的是兼容传统流程的 manual_active 需求；AI Native 需求应使用 workspace req submit。传统 release 对应 manual_release。release 还可能进入 stale 或 publish_in_progress：前者表示 feature、release 分支或测试快照已变化，需要重新集成测试；后者表示多 repo 发布只完成了一部分，需要按诊断修复后幂等重试。

5. 阶段一：需求提交、采纳和澄清

5.1 提交需求

workspace req submit "支付链路优化" \
  --key REQ-001 \
  --repo backend \
  --repo frontend \
  --description-file ./requirements/REQ-001.md \
  --acceptance-criteria-file ./requirements/REQ-001-acceptance.md \
  --priority 50

提交只登记需求和 repo 绑定，不会提前创建可写 worktree。初始状态是 pending_acceptance。优先级数值越小越先调度。

主 Agent 会检查目标、范围、验收标准、依赖仓库和风险。如果信息足够，它分配三个专业 Agent 和两个 Review policy：

workspace req assign-agents REQ-001 \
  --analysis-agent analysis-codex \
  --coding-agent coding-claude \
  --test-agent testing-codex \
  --analysis-review-policy strict-analysis \
  --development-review-policy development-gate

默认会把需求推进到 pending_analysis。需要先保存分配结果但不启动分析时加 --no-advance。

5.2 人工澄清

当 Agent 无法可靠判断需求口径、依赖、风险接受或验收标准时，Job 进入 waiting_user_input 并创建 approval。用户可一边看执行流，一边查看并回复：

workspace req watch REQ-001 --follow
workspace approval list --status pending
workspace approval show <approval-key>
workspace approval respond <approval-key> \
  --choice approve \
  --message "仅调整已登录用户支付链路，保持旧 API 兼容"

回复必须关联原 Job 和原实体。事务会同时记录 approval response、状态事件并恢复或创建后续 Job，避免出现“用户已回复但任务仍永久等待”的半状态。

6. 阶段二：需求分析与方案 Review Loop

进入 pending_analysis 后，daemon 创建分析 Job，Worker claim 后状态变为 analyzing。一个完整 Loop 包含：

1. 分析 Agent 读取需求、验收标准、repo 元数据和已有 artifact。
2. 生成 requirement_design，说明用户场景、范围、非目标、验收标准、边界和风险。
3. 生成 technical_design，说明架构、数据模型、接口、状态机、迁移、安全、测试和回滚。
4. 生成独立的 analysis_review，按严重级别记录问题和证据。
5. 若未达到 Review policy，创建修订 Job，生成新版本设计和新的 Review。
6. 达到门槛后进入 analysis_completed；超过最大轮次仍未通过则等待用户处理。

每轮产物都记录 metadata、文件路径、版本、SHA-256、创建者和时间。旧版本保留，用户可以比较任意两轮，不会被最新结果覆盖。

6.1 查看和编辑方案

workspace req artifact list REQ-001
workspace req artifact show REQ-001 <artifact-id>
workspace req artifact create REQ-001 \
  --type technical_design \
  --stage analysis \
  --title "技术方案-人工修订版" \
  --content-file ./technical-design.md

用户修改方案时应创建新版本，保留 Agent 原始产物和审计链。不要直接编辑 artifact 存储目录中的文件。

6.2 选择终稿

自动 Review 通过不等于用户已经定稿。用户应从候选版本中明确选择需求设计和技术设计：

workspace approval respond <artifact-finalization-approval> \
  --choice approve \
  --final-requirement-design-artifact <requirement-design-id> \
  --final-technical-design-artifact <technical-design-id>

也可以分别使用 workspace req artifact finalize REQ-001 <artifact-id> 管理 artifact；进入开发前系统仍会校验两类终稿是否都存在。定稿完成后需求进入 pending_development。

7. 阶段三：分步开发与 Review Loop

7.1 准备 feature workspace

workspace req prepare-workspace REQ-001

该命令按需求绑定的 repo 创建或复用 feature/<req-slug> worktree。Coding Agent 只能在数据库登记的这个 workspace 内写代码。其他需求 worktree、release worktree、workspace home、数据库、config、socket 和其他 runtime 都属于不可解除的控制面保护范围。

7.2 制定并执行实现计划

开发状态变为 developing 后，Coding Agent：

1. 读取已定稿的 requirement_design 和 technical_design。
2. 生成有顺序、可验证、可恢复的 implementation_plan。
3. 一次只执行一个步骤，并记录代码变更、命令输出和验证结果。
4. 每个实施步骤后创建独立 Review Job，生成独立 implementation_step_review artifact。
5. Review 不通过时在同一步骤中修复并重新 Review；通过后才进入下一步。
6. 如果技术方案不再可执行，创建 implementation_blocker approval，由用户选择继续、重新规划或阻塞。
7. 全部步骤完成后生成 implementation_report 和最终 implementation_review。

典型 blocker 回复：

workspace approval respond <approval-key> \
  --choice replan \
  --message "保留 API 兼容层，基于当前数据库版本重新拆分迁移步骤"

重新规划会保留旧计划和已完成步骤，不会把历史 Review 伪装成新计划的结果。只有计划覆盖完整、每个步骤通过门槛且最终报告写入成功，需求才进入 development_completed。

8. 阶段四：创建 Release 和形成测试快照

多个 development_completed 需求可以进入同一个 release：

workspace release create "2026-07-15 发布" \
  --key 2026-07-15 \
  --req REQ-001 \
  --req REQ-002 \
  --test-command "go test ./..."

workspace release integrate 2026-07-15
workspace release test start 2026-07-15 \
  --test-agent testing-codex

release 集成会从需求 feature 分支构建可重建的 release 分支和 worktree。测试启动时保存成员需求、feature SHA、release SHA、repo 和测试命令，形成不可变 test run snapshot。

测试命令按以下优先级解析：

1. release test start --test-command 显式提供。
2. release 创建时保存的默认命令。
3. 全局 Agent 默认测试命令。
4. 测试 Agent 根据 repo 内容推断，并在报告中记录实际命令。
5. 都无法确定时创建 test_command_missing approval，等待用户提供。

workspace approval respond <approval-key> \
  --choice approve \
  --test-command "cd backend && go test ./..."

9. 阶段五：集成测试与 Bug 修复 Loop

测试 Agent 在 release workspace 中执行整体 Review 和测试，但该 workspace 对 Agent 保持只读。每轮测试生成 test_report，至少记录快照、命令、退出状态、通过项、失败项和证据。

发现缺陷时，测试 Agent 通过 MCP 把 Bug 关联到具体 requirement 和当前 release test run。流程随后执行：

1. release 保持在测试流程，Bug 状态为 open。
2. daemon 为 Bug 对应需求创建 bugfix Coding Job。
3. Coding Agent 只在该需求 feature worktree 分析、修复、Review，并生成 bugfix_report。
4. 修复后的 feature 分支重新集成进 release；release 分支不接受直接修改。
5. 原 test snapshot 失效，系统创建新的不可变 test run snapshot。
6. 测试 Agent重新做整体 Review 和测试。
7. 所有 Bug 已关闭且测试通过后，release 和成员需求进入 testing_completed。

实时查看 Bug 和测试状态：

workspace release test status 2026-07-15
workspace release bugs list 2026-07-15 --status open
workspace req bugs list REQ-001 --status open
workspace release watch 2026-07-15 --follow

任意 feature commit、release branch SHA、成员集合或测试命令变化都会让旧测试证明失效。系统必须重新集成和测试，不能复用“曾经通过”的报告直接发布。

10. 阶段六：发布确认和发布

测试通过后，系统执行发布前快照新鲜度检查并进入 pending_release，然后创建 publish_confirmation approval。用户先查看状态、测试报告、未关闭 Bug 和待确认内容：

workspace release status 2026-07-15
workspace release watch 2026-07-15
workspace approval show <publish-approval-key>
workspace approval respond <publish-approval-key> \
  --choice approve \
  --confirm
workspace release publish 2026-07-15

确认只授予本次 test snapshot 的发布许可；随后由主 Agent、用户或自动化调用 workspace release publish <release>。release 进入 releasing，workspace-cli 把各 repo 的 release 分支合并到登记的 main 或 master base branch。全部 repo 成功后，release 和需求进入 released。

多 repo 发布中途失败时状态进入 publish_in_progress。已发布 repo 的目标 SHA 会被锁定，不能因为重试而重复漂移；用户应按 workspace release watch 的诊断修复失败 repo，再重新执行：

workspace release publish 2026-07-15

如果 release 或 feature SHA 在确认后变化，发布会拒绝并标记 stale，必须重新集成、测试和确认。

11. 实时观察和人工控制

11.1 四个观察层级

需要排查 Provider 原始输出时使用：

workspace run tail <run-id> --raw --follow

原始输出默认做敏感信息脱敏。--unsafe-unredacted 只能与 --raw 一起使用，应只在可信终端和必要的故障排查中启用。

11.2 常用人工操作

workspace approval list --status pending
workspace job list --status running
workspace job show <job-key>
workspace job cancel <job-key> --reason "需求范围已调整"
workspace job retry <job-key>
workspace worker disable coding-pool
workspace worker enable coding-pool

• waiting_user_input：先查看 approval，再提供结构化选择或说明；不要直接 retry。
• blocked：查看阻塞原因，修正配置/方案/环境后按对应 approval 或 workflow 操作恢复。
• failed：先读 run 事件和原始尾部；只有失败原因已消除时才 retry。
• lost：通常表示 lease、进程或 daemon 异常。reconciliation 会撤销旧 capability 并收敛旧 run，再允许新 Worker claim。
• cancelled：代表用户或控制面明确终止；run、token、worker ownership 和终态事件会一起收敛。

12. Artifact 和审计产物

状态事件、run event、approval request/response、main Agent session、capability grant/revoke 和发布 repo 结果构成审计链。artifact 文件和 DB metadata 必须一致；通过 CLI/MCP 创建和定稿，不要直接修改存储文件或 SQLite。

13. 安全和稳定性保证

1. Workspace 强绑定：requirement Job 只能使用对应 feature worktree，release 测试只能使用对应 release worktree，无代码 Job 使用隔离 runtime。路径会 canonicalize、检查 symlink 并与数据库登记值比对。
2. 控制面不可写：任何 Worker permission grant 都不能开放 workspace DB、WAL/SHM、config、daemon/operator socket、workspace home 或其他 Job runtime。
3. Provider 隔离：Codex 与 Claude Code 的凭据和 session 路径分开授权；Provider grant 只扩大当前代码 workspace policy。
4. 能力最小化：MCP capability 绑定 role、requirement、release、test run、job 和 run。每次请求实时查库校验，任务终态立即撤销。
5. Lease 不可复活：heartbeat 只续期仍由当前 Worker 持有且尚未过期的 lease/token。过期任务先由 reconciliation 收敛，再重新 claim。
6. 终态原子化：Job、run、worker、capability 和 terminal event 在同一事务更新，避免永久 running、重复 active run 或看不到终态。
7. Release 不可直接修复：测试发现的问题必须回到 requirement feature 分支修复，再重新集成形成新快照。
8. 发布快照校验：成员、feature SHA、release SHA、测试结果和目标分支任何一项漂移都阻止发布。

14. 故障恢复手册

15. 最小可运行示例

# 1. 配置一次
workspace agent add main-codex --provider codex --role coordinator
workspace agent add analysis-codex --provider codex --role analysis --sandbox read-only
workspace agent add coding-codex --provider codex --role coding --sandbox workspace-write
workspace agent add testing-codex --provider codex --role testing --sandbox read-only
workspace review-policy add strict-analysis --stage analysis --max-rounds 5 --pass-condition no_findings --max-severity none
workspace review-policy add development-gate --stage development --max-rounds 3 --pass-condition max_severity --max-severity low
workspace worker add analysis-pool --role analysis --agent analysis-codex --parallelism 2 --max-workers 2
workspace worker add coding-pool --role coding --agent coding-codex --parallelism 2 --max-workers 2
workspace worker add testing-pool --role testing --agent testing-codex --parallelism 1 --max-workers 1
workspace agent daemon start

# 2. 提交并分配需求
workspace req submit "支付链路优化" --key REQ-001 --repo backend --description-file ./REQ-001.md --acceptance-criteria-file ./REQ-001-acceptance.md
workspace req assign-agents REQ-001 --analysis-agent analysis-codex --coding-agent coding-codex --test-agent testing-codex --analysis-review-policy strict-analysis --development-review-policy development-gate
workspace req watch REQ-001 --follow

# 3. 分析完成后，在 approval 中选择两个终稿 artifact
workspace approval list --status pending
workspace approval respond <approval-key> --choice approve --final-requirement-design-artifact <id> --final-technical-design-artifact <id>
workspace req prepare-workspace REQ-001

# 4. 开发完成后创建 release 并测试
workspace release create "2026-07-15 发布" --key 2026-07-15 --req REQ-001 --test-command "go test ./..."
workspace release integrate 2026-07-15
workspace release test start 2026-07-15 --test-agent testing-codex
workspace release watch 2026-07-15 --follow

# 5. 测试通过后确认发布
workspace approval list --status pending
workspace approval respond <publish-approval-key> --choice approve --confirm
workspace release publish 2026-07-15
workspace release status 2026-07-15

这条主线同时保留了自主执行和人工控制：没有人工输入时，daemon 与专业 Agent 会继续推进可确定的工作；一旦出现需求口径、风险、权限、测试命令或发布责任问题，状态机会停在可观察的确认点，直到用户明确响应。