workspace-cli AI Native Web 操作需求方案

本文定义 workspace-cli AI Native Web 控制台的产品范围、页面结构、操作流程、交互门禁和验收标准。现有 AI Native 业务语义以 AI Native 研发平台需求方案 为准，CLI 端到端操作以 AI Native 开发流程指南 为准，实际使用方法见 AI Native Web 功能与使用指南，Web 服务和接口实现见 AI Native Web 技术实现方案。

1. 产品定位

AI Native Web 控制台是现有 CLI 研发流程的可视化、结构化操作入口，不是另一套研发流程。Web、CLI、主 Agent 和 Worker 必须共享同一个 workspace-cli home、SQLite 状态库、Git worktree、Service 状态机和审计记录。

现有 AI Native Core V1 的“暂不提供 Web UI”边界在本阶段被 Web 控制台扩展取代；其他核心边界继续保留：

• 仍是本地部署、局域网可访问的单用户系统，不建设远程多用户 SaaS。
• 仍由本机 coordinator daemon、Codex/Claude Code Provider 和 Worker pool 执行任务。
• 仍以 requirement feature worktree 作为长期开发位置，以可重建的 release worktree 作为集成测试位置。
• Web 不直接修改 SQLite、Git refs 或 artifact 存储文件，只调用与 CLI/MCP 相同的受控业务能力。
• Web 不保存或代理模型 API key，不绕过 Provider sandbox、Approval 或 capability 权限。

1.1 产品目标

• 用户通过 workspace web start 启动控制台，不需要独立安装或部署 Web 服务。
• 用户可以从一个界面管理需求、分析、研发、测试、Bug 修复、Release 和发布闭环。
• 用户可以实时查看 requirement、release、job、run、worker 和 Agent 的执行状态。
• 用户可以在 Web 中阅读、比较、修订和定稿 Artifact，并处理全部结构化 Approval。
• 用户可以通过持久化主 Agent 聊天会话查询状态、解释阻塞并发起受控操作。
• 浏览器断线、Web 服务重启或页面刷新不能中断后台 Agent、Git 操作或丢失审计信息。

1.2 核心原则

1. 同一事实来源：SQLite、Artifact 文件和 Git 状态是事实来源，页面缓存和聊天内容不是业务状态。
2. 状态驱动：页面只展示当前状态允许的操作，不提供任意修改状态枚举的入口。
3. 业务阶段与执行状态分离：workflow_status 表示研发阶段，queued/running/blocked/failed/waiting_user_input 表示执行情况。
4. 人工门禁不可跳过：需求澄清、方案定稿、实施阻塞、测试命令、权限提升和发布确认必须使用类型化 Approval。
5. 危险操作可解释：集成、重测、取消、重试和发布前展示影响范围、快照、前置检查和不可逆结果。
6. 断线可恢复：长操作和主 Agent 消息由持久化任务承载，不依赖单次 HTTP 请求存活。
7. 默认安全：非本机监听默认强制 TLS；只有显式 --allow-insecure-http 才可例外并持续告警。配对码单次有效，所有写操作校验会话、CSRF、Origin 和当前状态。

2. 用户、终端和范围

2.1 用户模型

Web 首版只有一个逻辑用户“本地操作者”。不同浏览器设备通过配对获得独立会话，审计记录必须保存会话 ID、设备标签、来源地址和操作时间，但不引入账号、组织或 RBAC。

用户承担以下职责：

• 提交需求、补充验收条件和关联 repo。
• 为需求选择 Agent 和 Review policy。
• 选择或编辑需求设计与技术方案终稿。
• 处理研发阻塞、测试命令缺失和 Provider 权限申请。
• 检查测试快照、未关闭 Bug 和发布影响后确认发布。
• 处理脏 worktree、外部提交、stale 和 publish_in_progress 等人工恢复事项。

2.2 终端适配

支持当前两个主流稳定版本的 Chrome、Edge、Safari 和 Firefox。禁用 JavaScript 时只展示不可操作的兼容提示。

2.3 Web 首版范围

• 仪表盘与全局待办。
• AI Native 与 manual requirement/release 的统一列表和模式标识。
• AI Native 需求提交、采纳、Agent/Policy 分配、分析、定稿、开发、测试和发布。
• manual requirement/release 的现有基础操作兼容。
• Artifact 阅读、版本比较、创建用户修订版和终稿选择。
• Job、Run、Worker、Agent、状态事件和诊断的实时观察。
• Approval 中心及六类结构化响应。
• Release test run、不可变测试快照、测试报告和 Bug 修复循环。
• Repo、Agent、Worker pool、Review policy、daemon 和 Web 服务配置/健康状态。
• 主 Agent Web 聊天、会话历史、上下文绑定、取消和重试。
• 登记 worktree 范围内的只读 commit、文件变更摘要和 diff。

3. CLI 启动、访问和服务生命周期

3.1 命令面

workspace web start
workspace web status [--json]
workspace web stop
workspace web restart
workspace web pair
workspace web sessions list
workspace web sessions revoke <session-id>
workspace web sessions revoke --all

workspace web start 支持：

3.2 启动行为

1. 解析 home，优先级保持 --home > WORKSPACE_CLI_HOME > ~/.workspace-cli。
2. 加载配置并完成数据库迁移。
3. 检查同一 home 是否已有健康 Web 实例；已有实例时不重复启动，但仍撤销未使用旧码、签发一个新配对码并返回当前 URL。
4. 未传 --no-daemon 时确保 coordinator daemon 已运行且支持 Web 所需协议能力；daemon 启动、安全升级或兼容性校验失败时 Web 不启动，并显示诊断路径。显式 --no-daemon 时允许降级启动：如果 daemon 未运行，新 Agent Job/operator action 只排队不执行；如果已有 daemon 但协议不兼容，则拒绝新建这些任务并提示升级，不让其永久排队或被错误执行。
5. 校验监听地址、TLS 文件、端口和 runtime 目录权限。
6. 后台启动 Web 实例，等待健康检查通过后再返回成功。
7. 生成五分钟内有效的一次性配对码，在终端展示本机 URL、可用局域网 URL、配对码、日志路径和停止命令。
8. 非 headless 环境默认打开本机 URL；--no-open 时只输出信息。

停止或重启 Web 服务不得停止 coordinator daemon、取消 Worker Job 或终止进行中的 operator action。后台任务完成后继续写入数据库；Web 恢复时必须能重新展示结果。

3.3 配对和会话

1. 未认证浏览器只能访问配对页和健康检查。
2. 用户输入 CLI 展示的一次性配对码，可选设置设备标签。
3. 配对码最多尝试五次、五分钟过期、成功后立即失效；错误提示不得暴露码是否部分匹配。
4. TLS 或 loopback 下浏览器获得二十四小时会话；显式非 loopback 明文 HTTP 下会话最多十五分钟且 Web 重启即撤销。每个设备独立撤销。
5. workspace web pair 可以在服务运行期间签发新配对码。
6. 用户可在“系统 > 已配对设备”或 CLI 查看并撤销会话；撤销后该设备的 SSE 和后续 API 调用立即失败。
7. Web 服务重启后，未过期且未撤销的 TLS/loopback 会话继续有效；非 loopback insecure HTTP 会话按第 4 项全部撤销。

非 loopback 监听默认必须使用 HTTPS。只有显式传入 --allow-insecure-http 才允许 HTTP，启动输出和页面顶部必须持续显示“不安全连接”警告。

4. 信息架构与全局交互

4.1 主导航

Artifact 主要在需求、Release、test run 和聊天上下文中展示；执行中心提供跨实体检索入口，但不要求独立顶级 Artifact 导航。

4.2 桌面布局

┌──────────────┬────────────────────────────────────────┬──────────────────┐
│ 主导航       │ 页面标题 / 状态 / 主操作              │ 主 Agent / 待办  │
│ 工作台       ├────────────────────────────────────────┤ 上下文摘要       │
│ 需求         │ 筛选、看板、详情 Tab、时间线或编辑器   │ 聊天消息         │
│ Release      │                                        │ 操作建议         │
│ 待办审批     │                                        │ Pending Approval │
│ 执行中心     │                                        │                  │
│ 配置         │                                        │                  │
└──────────────┴────────────────────────────────────────┴──────────────────┘

右侧主 Agent 面板可收起或进入独立全屏页面。打开 requirement、release、job、run、approval 或 artifact 时，用户可以把当前对象附加为聊天上下文；系统必须明确展示已附加对象，不能隐式扩大范围。

4.3 全局状态表达

• 每个 requirement/release 同时展示“业务阶段”和“执行健康”。
• blocked、failed、waiting_user_input 以显眼但不替代阶段名称的徽标展示。
• 状态颜色不能是唯一信息载体，必须配合文字、图标和可访问标签。
• 所有列表支持按状态、模式、repo、Agent、priority、更新时间和是否阻塞筛选。
• priority 只允许正整数，数值越小越优先，默认 100；修改只影响 queued job 的排序。
• 页面不得显示“万能推进”按钮；操作名称必须表达业务意图，例如“采纳并开始分析”“选择终稿”“重新集成”“确认发布”。

需求阶段与默认操作入口：

Release 的 stale 和 publish_in_progress 是必须单独突出显示的恢复状态：stale 只提供重新集成/测试路径；publish_in_progress 锁定范围并只提供诊断和幂等发布重试。

4.4 实时更新

• Requirement、Release、Job、Run、Approval 和聊天使用服务端事件流更新。
• 页面顶部展示连接状态：实时、正在重连、离线。
• 断线重连先从最后事件游标 best-effort 续传，再校验 authoritative snapshot revision；不能依赖事件流替代状态查询，也不能通过整页刷新制造重复通知。
• 事件到达后只刷新受影响的局部数据；用户正在编辑表单时不能覆盖未提交内容。
• 同一对象被 CLI 或其他浏览器修改时，页面展示“数据已变化”，重新拉取后再允许危险操作。

4.5 通知和待办

全局待办只包含需要用户行动的事项：

• Pending Approval。
• cleanup-pending、脏 worktree、Provider 不可用等人工阻塞。
• stale Release 需要重新集成/测试。
• publish_in_progress 需要人工恢复。
• Job 达到最大重试次数。

普通进度事件进入活动流，不弹出阻断通知。成功提示包含对象链接和结果摘要；失败提示包含错误码、原因、当前状态和允许的恢复动作。

4.6 Web 与 CLI 能力映射

Web 操作必须调用与下列 CLI 相同的 Service 语义；“实时查看”在 Web 中由 REST snapshot + SSE 代替 CLI --follow：

5. 工作台

5.1 页面目标

用户进入 Web 后，应在一个页面回答：

• 当前有多少需求处于分析、开发、测试、待发布和阻塞状态？
• 哪些 Job 正在运行，使用哪个 Agent/Worker，heartbeat 是否健康？
• 有哪些 Approval 等待处理？
• 哪些 Release stale、测试失败或 publish-in-progress？
• coordinator daemon、Web 服务和 Provider 是否可用？
• 下一步最需要用户处理什么？

5.2 组件

工作台刷新不得默认执行远程 Git fetch；远端同步由用户显式触发，或按低频后台策略执行并标记上次检查时间。

6. 需求提交、采纳和澄清

6.1 需求列表

列表支持表格和按 workflow 阶段分组的看板视图。每项至少展示：

• Key、标题、AI Native/manual 模式。
• workflow 阶段和底层 requirement stage。
• priority、repo、分析/Coding/测试 Agent。
• active job、pending approval、open bug 数。
• 最近更新时间和下一步。

manual 对象不显示不存在的 AI Native 阶段；使用“传统流程”徽标和其底层 active/ready/cleanup-pending/completed 状态。

6.2 提交 AI Native 需求

“提交需求”表单字段：

提交前显示摘要，成功后进入 pending_acceptance，写入初始 status event，并跳转详情页。保存失败不得留下部分 requirement/repo 绑定。

6.3 采纳与 Agent 分配

pending_acceptance 页面提供“采纳并开始分析”：

• 选择 analysis、coding、testing Agent。
• 选择 analysis 和 development Review policy。
• 展示 Agent health、Provider、模型、sandbox 和对应 Worker pool capacity。
• 可以“仅保存分配”而不推进；开始分析时必须验证所需 Agent、Policy 和 repo 完整。

信息不充分时，主 Agent 或用户创建/处理 requirement_clarification。响应表单支持 message，并可同时修订 description、acceptance criteria、repo 和 priority。成功后恢复原 Job 或创建下一步 Job，不能产生永久等待的半状态。

6.4 需求详情

7. 分析与方案定稿

7.1 分析工作台

进入 analyzing 后展示当前 analysis job、Review 轮次、Policy 门槛和产物时间线：

需求设计 v1 ─┐
技术方案 v1 ─┼─ Review v1（未通过）─ 修订
需求设计 v2 ─┤
技术方案 v2 ─┼─ Review v2（通过）── 等待终稿

每轮 Review 独立展示风险等级、问题、证据、建议和通过结论。达到最大轮次但仍未通过时，页面保持当前业务阶段并显示人工处理选项，不把“达到次数”当作通过。

7.2 Artifact 阅读和比较

• Markdown Artifact 提供目录、正文和元数据。
• 用户可以选择同类型两个版本做并排或逐行比较。
• 历史版本只读，不能覆盖或直接修改 artifact 文件。
• “创建人工修订版”从选定版本复制到编辑器，保存后创建新版本并记录 created_by=web_user。
• 保存前展示内容摘要；并发产生新版本不覆盖用户草稿。
• 过大、二进制或不支持预览的内容只展示安全元数据和受控下载/本机打开入口。

7.3 终稿选择

analysis_completed 必须展示 artifact_finalization Approval：

• 分别选择一个 requirement_design 和一个 technical_design。
• 候选必须属于当前 requirement 且类型正确。
• 展示版本、Review 结论、哈希、创建者和差异摘要。
• 用户可以先创建修订版再选择。
• 提交时两个 final ID 缺一不可；成功后原子 finalize 两类 Artifact，并允许进入 pending_development。

8. 研发工作台

8.1 进入开发

• 进入开发前展示最终需求设计、最终技术方案、repo 和 workspace 计划。
• req prepare-workspace 等价动作必须幂等：缺失时创建，干净时复用，脏目录或路径冲突时阻塞并保留状态。
• 页面展示每个 repo 的 feature branch、worktree path、准备结果和 Git clean 状态。
• 浏览器不允许编辑 worktree 文件或打开远程 Web Terminal。

8.2 开发周期和步骤

研发工作台以“开发周期”为一级分组。每个周期展示：

• 绑定的 final technical design。
• implementation_plan 及有序步骤。
• 每步的 implementation job、step review、fix job、验证结果和当前状态。
• implementation_report 与最终 implementation_review。

同一周期一次只突出一个可执行步骤。Review 未通过时，下一步保持锁定并说明原因；修复和再次 Review 仍归属原步骤。

8.3 Implementation blocker

技术方案不可实施时展示独立 blocker Artifact 和 implementation_blocker Approval：

• continue：按用户说明继续当前周期。
• replan：要求选择或创建新的技术方案终稿，启动新开发周期。
• block：保持阻塞，不创建后续 Job。

重新规划后旧周期完整保留为只读历史，默认折叠，不得把旧 Step/Review/Report 混入新周期完成度。

8.4 只读代码变更

Web 展示数据库登记 worktree 内的：

• repo、branch、HEAD commit 和与基线的提交摘要。
• changed file 列表、状态、增删行数。
• 文本 diff、截断提示和对应 Job/Run。

不支持任意路径输入、二进制内容、未登记 worktree 或通过 symlink 逃逸。diff 过大时按文件和总大小限制截断，并引导用户在本机 IDE 查看。

8.5 完成开发

“完成研发”前检查：

• 所有实施步骤和 Review 已通过。
• 实现报告和总 Review 已生成。
• requirement workspace 路径、repo 和目标 feature branch 与登记值一致；普通 active 流程允许存在 Coding Agent 的待提交改动，由 req finish 负责提交和推送。
• 如果是 cleanup-pending 的 cleanup-only 重试，则已提交/推送的 worktree 必须干净，不能把新改动混入清理。
• 没有 pending blocker Approval。

完成动作复用 req finish 语义。进入 cleanup-pending 时 requirement 保持 developing，页面展示已完成和待恢复步骤，并允许在问题处理后重试清理；不能显示为研发完成。

9. Release 创建与集成

9.1 Release 列表

展示 Key、标题、AI Native/manual 模式、workflow 状态、底层 status、成员需求、repo、active test run、open Bug、stale/publish-in-progress 诊断和更新时间。

9.2 创建 Release

AI Native Release 创建向导：

1. 填写标题和可选 Key。
2. 从 development_completed 需求中选择一个或多个成员。
3. 展示合并顺序、涉及 repo、feature commit 和冲突风险。
4. 可选择 Release 默认测试 Agent。
5. 可填写默认测试命令。
6. 确认范围并创建。

创建失败不得留下 orphan workspace 或部分 membership。manual requirement 可以创建 manual release，但页面必须明确其不进入 AI Native test/approval 状态机。

9.3 集成

“集成 Release”是长操作：

• 提交后立即返回 operation key，页面持续展示各 repo 进度。
• 浏览器关闭不取消集成。
• 禁止重复提交同一 Release 的运行中集成。
• 冲突、脏 worktree、外部 base 更新或 Git 错误按 repo 展示诊断。
• --force 等价的丢弃修改能力不作为普通按钮提供；需要独立危险确认并明确列出将丢失的路径。

集成成功后展示 release branch、integrated base SHA、release SHA 和 requirement feature SHA。

10. 集成测试与 Bug 修复

10.1 Test run

Release 详情的“测试”Tab 展示每次 test run，当前 active run 置顶。每个 run 至少包含：

• ID、状态、测试 Agent、开始/结束时间。
• 测试命令和来源：explicit、release_default、agent_default、inferred 或 user_supplied。
• requirement + repo + feature commit + release commit 不可变快照。
• 测试报告 Artifact、Run events、失败证据和 Bug。

旧 run 只读，不因新 run 覆盖。页面必须清楚区分“历史通过”和“当前可用于发布的 active passed run”。

10.2 启动测试

测试前展示范围快照和命令解析结果，并允许为本次 test run 选择或覆盖测试 Agent。只有 Release 已成功 integrate、release workspace 与 Artifact 目录存在且为目录、worktree clean、快照范围有效时才能创建/启动 test run；Testing Agent claim 后需求与 Release 进入 testing。未提供命令时允许测试 Agent 推断；无法确定命令，或命令存在但无法执行任何有效单测时，都创建关联当前 test run 的 test_command_missing Approval，而不是显示测试完成。

用户可以：

• 提供确定的 test command 并恢复同一 test run。
• 选择 block，让 test run 保持 blocked。

测试前已有脏 release worktree 时不得启动 Provider；测试后出现 tracked/untracked 修改时不得采纳结果。Web 只展示并保留现场，不能自动 reset/clean；用户清理后显式重试。

10.3 Bug

Bug 详情包含 requirement、release、test run、repo、文件、严重级别、复现步骤、失败命令、创建/修复 Job 和状态。Web 不能把 Bug 关联到当前 test run 快照之外的 requirement 或 repo。

Bug 修复流程：

1. 测试 Agent 创建 open Bug，requirement 回到 pending_development。
2. daemon 创建关联该 Bug、requirement 和 test run 的 bugfix Coding Job。
3. Provider 启动前由该 Job 的受控前置处理执行 req reopen、恢复 feature worktree，并在同一业务事务把受影响的 AI Native Release 标为 stale、写 release event；旧测试证明立即失效。Workspace 准备成功并 claim 后 requirement 进入 developing。
4. Coding Agent 在对应 feature worktree 修复并生成 bugfix_report。
5. 修复完成并通过 Review 后执行 req finish，关闭对应 Bug，使 requirement 恢复 ready 和 development_completed。
6. 用户或 coordinator 重新集成，形成新的 test run 快照。
7. 全量重新测试；旧测试通过结果不可复用。

测试结果为 failed 但没有合法 Bug 时，页面显示“测试输出无效”阻塞诊断，不允许进入 testing_completed。

进入 testing_completed 的硬门禁：

• Release 当前必须仍为 testing，且候选 run 是该 Release 最新的 passed test run。
• 当前 run 的实际测试命令、requirement、repo、feature commit 和 release commit 与 active scope 一致；命令来源只作不可变审计，不单独触发失效。
• 当前 run 范围内没有任何未解决 Bug。
• 成功后原子记录 active_test_run_id 并推进关联需求；对同一 completed run 重试必须幂等。
• 旧 run/job 的晚到结果不得回退 pending_release、releasing、released 或覆盖更新的 active run。

11. 发布确认和发布

11.1 发布前检查

进入 pending_release 前展示：

• active passed test run。
• requirement/repo/feature SHA/release SHA 快照。
• 实际测试命令和报告。
• open Bug 数量。
• release worktree 与 publish worktree clean 状态。
• 目标分支最新提交和 snapshot freshness。

open Bug 必须为零；当前实际 test command、成员范围、feature SHA、release SHA 或目标分支任一变化都会使测试证明失效，禁止进入发布确认并要求重新集成/测试。命令来源标签用于展示和审计，相同实际命令仅来源不同不要求重测。

11.2 Publish confirmation

publish_confirmation 必须使用专用确认面板：

• 显示将发布的全部 repo、目标分支和 commit。
• 显示确认所绑定的 test run ID。
• 用户明确选择“允许发布”或“拒绝”。
• 只有提交结构化 confirm=true 才视为批准。
• 拒绝后 Release 保持 pending_release，页面展示可再次人工发起确认的路径；daemon 不自动循环创建同一确认。

聊天中的“发布”请求只能打开或创建对应结构化确认，不能绕过面板直接发布。

11.3 发布执行

发布是 durable operator action：

• 进入 releasing 后按 repo 展示进度、目标 SHA 和错误。
• 页面关闭不取消发布。
• 当前范围或 SHA 与已确认快照不一致时拒绝并进入 stale，要求重新集成和测试。
• 实际 test command 或未解决 Bug 与已确认 test run 不一致时同样拒绝发布；命令来源标签本身不参与 freshness 比较。
• 部分 repo 成功时进入 publish_in_progress；已发布 SHA 锁定，用户修复失败 repo 后幂等重试。
• publish_in_progress 发现新快照不一致时保持当前状态并要求人工处理，不能自动降级。
• 全部 repo 成功后，Release 和 active requirements 才显示 released。

12. Approval 中心

12.1 通用要求

Approval 列表展示类型、标题、关联对象、来源 Job/Run、创建者、创建时间、默认建议和等待时长。响应提交前再次读取当前状态；已由其他入口处理时返回最新结果，不重复响应。

12.2 类型化表单

高风险选项展示不可逆影响并要求二次点击确认，但不得把自由文本输入当作结构化字段的替代。

13. 执行中心

13.1 Job

Job 列表支持按 status、role、type、requirement、release、Agent 和时间筛选。详情展示：

• Job key、role/type、priority、attempt/max attempts。
• lease owner、lease expiry、Worker、Agent 和 heartbeat。
• input/result 摘要、last error、关联实体。
• 全部 Run 和当前允许操作。

cancel 必须填写原因；retry 只在失败原因已经修复且 Service 允许时可用。waiting_user_input 引导用户处理 Approval，不把 retry 作为首选动作。

13.2 Run 和事件

Run 详情展示 provider、Agent、attempt、CWD、安全脱敏后的 command、时间、退出码、状态和结构化事件。事件类型包括进度、模型摘要、tool call、Artifact、测试输出、Approval、Bug、阻塞和终态。

默认不展示原始 stdout/stderr。管理员诊断入口只能读取受控尾部并继续脱敏；Web 首版不提供 unsafe-unredacted，未脱敏内容只允许用户在本机文件系统按 CLI 管理员流程查看。

14. 主 Agent Web 聊天

14.1 会话模型

• 用户可以创建、重命名、归档聊天会话。
• 会话历史持久化，Web 服务重启或切换设备后可恢复。
• 每条用户消息创建一个 coordinator_chat Job，使用配置的 coordinator Agent。
• 同一会话同一时刻只执行一条消息；其他消息进入 queued。
• 页面实时展示模型摘要、工具操作、关联 Artifact/Approval 和最终答复。
• 用户可以取消当前消息或在失败原因修复后重试；重试保留原消息和 attempt 审计。
• 取消意图必须持久化；Web 或 daemon 在取消过程中重启后仍能收敛到唯一消息/Job/Run 终态。

14.2 上下文和操作

聊天可显式绑定 requirement、release、job、run、approval、artifact 或 test run。页面必须以可见标签展示当前消息的读取范围；未绑定对象时业务范围为空。如需跨实体概览，用户必须显式选择“整个 workspace（只读）”范围；不得因为聊天位于某页面、上一条消息曾经绑定或工具支持 list 就隐式扩大权限。

主 Agent 只能通过 coordinator capability 和受控工具读取。实体范围在消息创建时冻结，可包含显式对象及页面说明的必要关联对象；返回列表、查看详情、订阅事件、展开关联和生成 action card 都必须受同一范围约束。

主 Agent 可以：

• 查询和汇总当前状态。
• 解释失败、阻塞、stale 和下一步。
• 为创建需求、分配 Agent、重试等普通操作生成结构化 action card，由用户确认后交给 Web Service 执行。
• 为危险动作生成操作预览或 Approval；Chat capability 本身保持只读。
• 导航用户到对应结构化页面。

主 Agent 不能：

• 绕过 Approval 或发布快照校验。
• 直接修改 Artifact 文件、SQLite 或 Git。
• 直接使用 Provider 原生 shell、filesystem 或网络工具读取宿主内容；业务上下文只能来自服务端授权的无副作用本地查询工具。
• 把聊天确认语句当作 confirm=true、终稿 ID 或 Provider grant。
• 读取 capability token、secret 或未脱敏输出。

15. 配置与系统管理

15.1 Repo

支持查看、新增、同步、更新和移除 repo，展示 URL、remote、base branch、bare path、最近同步和错误。正在被 active requirement/release 使用的 repo 不允许移除。

15.2 Agent

支持 Agent 的新增、查看、更新、启用、禁用、健康检查和删除。编辑字段包括 provider、role、model、system prompt/文件路径、command、sandbox、approval policy 和 provider schema 允许的 metadata。页面不得读取或展示 Provider 登录凭据、环境 secret 或未知 metadata 原文。

15.3 Worker pool

展示 role、绑定 Agent、parallelism、max workers、poll interval、lease、enabled、active jobs 和 live workers。有效并发明确显示为 min(parallelism, max_workers)。修改配置不得终止当前 running job；禁用后停止 claim 新任务。

15.4 Review policy

支持 analysis/development policy 的创建、查看、更新和删除，展示 max rounds、pass condition 和 max severity。被 requirement 引用时禁止删除。

15.5 系统

展示：

• workspace home、数据库和 artifact/runtime 路径。
• coordinator daemon/Web 实例 PID、状态、启动时间、heartbeat 和日志。
• Provider/isolation health。
• MCP transport、tool count、tool names 和最近 health 结果。
• Worker capacity 和 lost/stale 诊断。
• TLS 状态、监听地址和“不安全 HTTP”警告。
• 已配对设备及撤销入口。

路径只作脱敏展示，禁止通过 Web 任意浏览 workspace home。

16. Manual 流程兼容

Web 统一展示 manual 和 AI Native 对象，但不强制转换：

从局域网浏览器触发 dev 或 ide 无法在远端设备可靠打开宿主应用，因此页面只展示可复制 CLI 命令；在 Web 服务宿主机的浏览器中可提供“尝试在本机打开”，失败时不改变业务状态。

Web 不提供 manual 到 AI Native 的隐式转换。未来如支持迁移，必须单独设计状态、Artifact 和审计规则。

17. 错误、冲突和恢复

任何失败提示必须包含稳定错误码、用户可读消息、关联对象、当前状态和推荐下一步；不得直接把敏感路径、token、环境变量或完整 Provider stderr 暴露给浏览器。

18. 安全和隐私要求

• 非 loopback 默认强制 TLS；HTTP 必须显式接受风险并持续提示。
• Pairing code 和 session token 只保存哈希；session cookie 为 HttpOnly、SameSite=Strict，TLS 下 Secure。
• 所有写请求使用 CSRF token、Origin/Host allow-list 和 JSON content type 校验；不开放通用 CORS。
• 登录、配对和高频写接口进行速率限制。
• 所有 action 使用幂等 key；重复提交返回原 action，而不是重复执行。
• Web API 使用显式 DTO，不直接序列化 store struct 或 sql.Null*。
• Capability token、Provider secret、环境变量和未脱敏输出永不进入 DOM、URL、API 响应或浏览器日志。
• Artifact、diff 和日志访问必须从数据库登记对象派生 canonical path；拒绝浏览器提交的绝对路径、..、业务 symlink 和跨 workspace 访问。兼容数据库已有的绝对 Artifact path，但 canonical 后必须严格位于登记根目录。
• testing run scope 必须以 release_test_run_id 不可变快照为准，不能因同时存在 release_id 而扩大。
• Approval、状态迁移、Bug 回退、发布确认和关键事件继续使用 Service/Store 原子事务。
• Web session 终止不撤销正在运行的 Worker capability；Web chat job 的 capability 则随 Job/Run 终态撤销。

19. 性能和可用性

• 常规页面首屏在本地数据量 1,000 个 requirement、200 个 release、100,000 条 event 下应在 2 秒内可交互。
• 列表必须分页或虚拟化；默认不一次加载完整历史事件和原始日志。
• SSE 心跳不高于 15 秒；断线采用带上限的指数退避。
• Dashboard 高频刷新不得执行远程 Git fetch 或长事务。
• 数据库事务不能跨 Provider、Git 命令或网络等待持有。
• Artifact 和 diff 按需加载并限制单次响应大小。
• 键盘可完成主要导航、表单和 Approval；对比度和焦点状态满足 WCAG 2.1 AA 基线。
• 所有时间同时展示本地时区和可复制的 RFC3339 时间。

20. 非目标

• 远程多用户、组织、账号体系和 RBAC。
• 公网托管、云端数据库、外部队列或云 Worker。
• GitHub PR、GitLab MR、Jira、Linear 等外部平台接管。
• 浏览器代码编辑器、Web Terminal 或任意宿主命令执行。
• 在 release worktree 直接修复代码。
• 保存、代理或展示 OpenAI/Anthropic API key。
• 未脱敏 Provider 原始输出的 Web 查看。
• 离线编辑、PWA 安装和跨多个 workspace-cli home 的统一控制台。

21. 验收标准

21.1 启动和访问

• 用户可以通过 workspace web start 后台启动控制台，通过 status/stop/restart 管理同一 home 的单实例。
• 默认监听 127.0.0.1:8080；非 loopback 没有 TLS 时启动被拒绝，除非显式允许不安全 HTTP。
• 用户可以使用五分钟一次性配对码登录，撤销会话后对应设备立即失去访问。
• 默认启动必须确认 daemon 协议能力与 Web 兼容；不兼容 daemon 不会误 claim 新 action/chat，且页面给出可执行的升级诊断。
• Web 停止或浏览器断线不影响 daemon、Worker Job 和运行中的长操作。

21.2 需求、分析和研发

• 用户可以提交带 description、acceptance criteria、repo 和 priority 的 AI Native 需求，并看到初始状态事件。
• 用户可以采纳需求、分配三类 Agent 和两个 Review policy。
• 用户可以实时查看多轮需求设计、技术方案和 Review，并比较版本。
• 用户可以创建人工修订版并通过类型化 Approval 同时选择两类终稿。
• 用户可以查看 workspace 准备、开发周期、步骤、Review、Fix、报告和只读 diff。
• implementation blocker 选择 replan 后，新旧开发周期严格分离。
• cleanup-pending 不得错误展示为 development_completed。

21.3 测试、Bug 和发布

• 用户可以从多个 development_completed 需求创建、集成和测试 Release。
• Test run 展示实际 test command、来源和 requirement+repo+commit 不可变快照。
• 缺少测试命令或无法执行任何有效测试时必须出现 Approval，不能静默跳过。
• 测试 Bug 能回到对应 feature worktree 修复，并使旧 Release/test snapshot stale。
• 测试 Agent 修改 release worktree 时结果不被采纳，页面保留诊断并要求显式重试。
• 只有当前 testing Release 的最新 passed run、实际测试命令和 immutable snapshot 均新鲜且零未解决 Bug 时，才能原子写入 active_test_run_id 并进入测试完成；重复完成幂等，旧 Job 晚到不回退状态。
• 发布前必须展示 active passed test run 和完整快照；只有 confirm=true 后才能发布。
• 部分发布显示 publish_in_progress，修复后幂等重试，不重复漂移已发布 repo。

21.4 实时、聊天和恢复

• Requirement、Release、Job、Run 和聊天在不刷新整页时持续更新，断线后从游标恢复。
• 每条 Web 聊天消息都有 coordinator Job/Run/Event 和持久化回复。
• Chat 取消请求在 Web/daemon 分进程和重启场景下不丢失，与正常完成并发时只产生一个终态。
• 空上下文、显式实体和“整个 workspace（只读）”三种 Chat 范围均有可见标识；列表、详情、事件、关联对象和 action card 不会越过当前消息的冻结范围。
• 主 Agent 可以解释状态和发起受控操作，但不能用聊天文本绕过类型化门禁。
• 长操作有持久化 operation key，浏览器关闭或 Web 重启后仍可查询结果。
• CLI 与 Web 并发修改时，陈旧写入被拒绝并展示最新状态。

21.5 安全与兼容

• Web API 不返回 capability token、secret、未脱敏原始输出，以及任何未登记、未授权或越出 canonical scope 的文件内容。
• Artifact 编辑创建新版本，不覆盖历史；diff 只能读取登记 worktree。
• Manual 对象带模式标识并可完成原有基础流程，不被强制进入 AI Native 状态机。
• 桌面完成全部管理；手机可以查看状态、聊天并处理全部 Approval。
• Web 入口的 requirement submit、Agent assignment/进入开发、test run+snapshot+缺命令 Approval、Bug 回退、publish confirmation response，以及 release/requirement 状态与 event 必须按核心 Service 事务原子提交；注入任一写失败时全部回滚。

21.6 配置与 Approval

• 用户可以新增、查看、更新、同步和安全移除 Repo；被 active requirement/release 引用时删除被拒绝。
• 用户可以新增、查看、更新、启用、禁用、健康检查和删除 Agent，且 Web 不展示 credential 或未知 metadata 原文。
• 用户可以管理 Worker pool；页面展示有效并发 min(parallelism, max_workers)，禁用后不再 claim 新 Job且不终止 running Job。
• 用户可以管理 analysis/development Review policy；被 requirement 引用的 Policy 不允许删除。
• 系统健康可以通过与 workspace mcp health 相同的边界展示 MCP transport、tool count 和 tool names。
• requirement_clarification、artifact_finalization、implementation_blocker、test_command_missing、publish_confirmation 和 provider_permission 六类 Approval 都有严格类型化表单；grant/deny、必填字段、原 Job/Run 归属和恢复结果均经过验证。