workspace-cli AI Native Web 功能与使用指南

本文面向实际使用 workspace-cli Web 控制台的研发人员，详细说明如何启动和访问 Web、完成首次配置，以及如何在浏览器中管理需求、研发、测试和发布流程。

Web 控制台不是一套独立于 CLI 的新流程。它和 CLI、daemon、Worker、主 Agent 共用同一个 workspace-cli home、SQLite 数据库、Git worktree、Artifact 和状态机。因此：

• CLI 创建或修改的对象会出现在 Web 中。
• Web 发起的长操作可以回到 CLI 查询。
• 关闭浏览器不会停止已经提交的 Agent、Git、测试或发布任务。
• 使用不同 --home 启动的 CLI 和 Web 属于不同工作区，数据不会互通。

相关文档：

• AI Native 开发流程指南：CLI 和完整研发流程说明。
• AI Native Web 操作需求方案：产品边界和交互要求。
• AI Native Web 技术实现方案：服务端、事务、SSE 和安全设计。

1. Web 版本能做什么

Web 控制台覆盖 AI Native 研发流程的主要日常操作：

Web 同时展示 AI Native 和传统 manual 对象。列表和详情会标明“AI Native”或“传统流程”，不会把 manual 对象静默转换成 AI Native 状态机。

2. 使用前准备

2.1 初始化 workspace-cli home

首次使用先初始化：

workspace init

默认 home 是 ~/.workspace-cli。如果使用自定义 home，后续所有 CLI 命令必须保持一致：

workspace --home /data/team-a web start
workspace --home /data/team-a web status

也可以使用环境变量：

export WORKSPACE_CLI_HOME=/data/team-a
workspace web start

解析优先级为：全局 --home > WORKSPACE_CLI_HOME > ~/.workspace-cli。

2.2 Provider 和 Git 准备

如果要运行 AI Native Agent，请先保证所选 Provider CLI 已安装并完成认证，例如 Codex 或 Claude Code。Repo 的 Git remote 也必须能在启动 Web 的宿主机上正常访问。

可以在正式提交需求前用 CLI 做基础检查：

workspace agent list
workspace agent health <agent-name>
workspace mcp health
workspace agent daemon status

Provider 不可用时，Web 可以正常查看数据，但对应 Worker pool 不会可靠执行 Job。

3. 启动、访问和停止 Web

3.1 本机启动

推荐的日常启动方式：

workspace web start

默认行为：

• 监听 127.0.0.1:8080。
• 检查并启动兼容的 coordinator daemon。
• 后台启动 Web 单实例。
• 输出访问 URL 和五分钟有效的一次性配对码。
• 尝试打开本机默认浏览器。

输出示例：

url:            http://127.0.0.1:8080
pairing-code:   ABCD-EFGH-IJKL-MNOP
expires-in:     5m
log:            ~/.workspace-cli/runtime/web/web.log

不希望自动打开浏览器时使用：

workspace web start --no-open

修改端口：

workspace web start --port 9080

前台运行并直接查看日志：

workspace web start --foreground --no-open

Ctrl+C 会停止前台 Web 服务，但不会把已经进入 daemon/Worker 的业务任务伪装成失败。

3.2 启动参数

配置文件中可以设置：

web_host: "127.0.0.1"
web_port: 8080
web_tls_cert: ""
web_tls_key: ""
web_operator_action_parallelism: 2

显式命令行参数会覆盖配置值。

3.3 局域网访问和 TLS

非 loopback 地址默认必须配置 TLS：

workspace web start \
  --host 192.168.1.20 \
  --tls-cert /secure/path/web.crt \
  --tls-key /secure/path/web.key

证书必须：

• 当前时间有效。
• 包含监听主机名或 IP。
• 与私钥匹配。
• 私钥文件不能被 group 或 other 读取。

在完全可信的临时局域网中可以显式启用明文 HTTP：

workspace web start --host 0.0.0.0 --allow-insecure-http

这是降级模式。终端和页面会持续显示警告，浏览器会话最长十五分钟，网络中的其他设备可能观察到明文流量。不要在公共 Wi-Fi、办公访客网络或互联网入口使用。

3.4 查看状态、重启和停止

workspace web status
workspace web status --json
workspace web restart
workspace web stop

正常停止最多等待十秒：

workspace web stop --timeout 20s

只有在正常停止超时、并且确认需要终止 Web 进程时才使用：

workspace web stop --timeout 10s --force

--force 仍会校验 PID、可执行文件和进程启动身份，避免误杀其他进程。

4. 浏览器配对和会话管理

4.1 首次配对

1. 运行 workspace web start。
2. 打开终端输出的 URL。
3. 在配对页输入 pairing-code。
4. 填写可识别的设备名称，例如“开发机 Chrome”或“测试手机”。
5. 点击“进入控制台”。

配对码五分钟过期、只能成功使用一次。过期或已经使用时重新签发：

workspace web pair

每次 web pair 会撤销未使用的旧配对码并生成一个新码，不会中断已经登录的正常浏览器会话。

4.2 会话有效期

• 本机 HTTP 或 HTTPS：正常会话最长二十四小时。
• 非 loopback 明文 HTTP：最长十五分钟，并在页面显示安全警告。
• 每个浏览器/设备都有独立会话，可以单独撤销。

4.3 查看和撤销设备

Web：进入“配置”中的“已配对设备”，查看设备名称、最后访问时间和状态，点击“撤销”。

CLI：

workspace web sessions list
workspace web sessions revoke <session-id>
workspace web sessions revoke --all

撤销后，该浏览器的后续 API 请求和实时事件连接会立即失效，需要重新配对。

5. 首次配置推荐顺序

进入“配置”页面后，建议按以下顺序配置。

5.1 Repo

填写：

• Repo 名称：流程中使用的稳定短名称，例如 backend。
• Git URL：SSH、HTTPS 或本地 Git URL。
• Remote：通常为 origin。
• 默认分支：例如 main。

可执行操作：

• “添加 Repo”：进入持久化操作队列，完成 bare clone 和登记。
• “更新”：修改 URL、remote 或 base branch。
• “同步”：显式获取远端 base branch。
• “移除”：执行安全移除；正在被活动需求或 Release 使用时会被拒绝。

Repo 的 clone、sync、update 和 remove 可能包含 Git 外部副作用，因此页面会把它们放入“操作队列”。提交后请到操作详情查看进度，不要因为页面没有立即变化而重复点击。

5.2 Agent

新增 Agent 时至少选择：

• 名称。
• Provider：codex 或 claude。
• 角色：coordinator、analysis、coding 或 testing。
• 模型，可留空使用 Provider 默认值。
• Sandbox。

页面支持查看健康状态、更新模型、启用/停用、执行健康检查和删除。健康检查属于持久化操作，可在“操作队列”查看结果。

角色建议：

5.3 Worker Pool

Worker pool 把一个执行角色绑定到一个 Agent。配置项包括：

• role 和 Agent。
• parallelism：该 pool 允许同时执行的任务数。
• max workers：最多启动的 Worker 数。
• poll interval：轮询间隔。
• lease：Job 所有权租约时间。

页面明确显示有效并发：

effective concurrency = min(parallelism, max_workers)

停用 pool 后不会再 claim 新 Job，但不会强制终止当前正在运行的 Job。

5.4 Review Policy

Review policy 用于约束分析或研发阶段的 Review 循环：

• 阶段：analysis 或 development。
• 最大 Review 轮次。
• 通过条件。
• 最大允许严重度。

页面支持新增、更新和删除。被需求引用的 policy 删除会被服务端拒绝。

5.5 Daemon 和系统健康

页面顶部可启动/校验或停止 coordinator daemon。“系统健康”区域展示：

• Web、数据库和 daemon 状态。
• Provider/Agent 健康状态与消息。
• Worker pool live workers 和 capacity。
• MCP transport、tool count 和 tool names。
• TLS 状态。

开始正式流程前，应至少确认 daemon、数据库和所需 Agent 为可用状态。

6. 工作台的使用方法

登录后的“工作台”用于快速回答“现在最需要处理什么”。

6.1 指标卡

展示：

• 需求总数。
• Release 总数。
• 运行中的 Job。
• 阻塞 Job。
• 待处理 Approval。

6.2 流程概览

按 requirement/release workflow 状态统计，例如：

• pending_acceptance
• analyzing
• pending_development
• developing
• development_completed
• testing
• pending_release
• release:stale
• release:publish_in_progress

6.3 我的待办

汇总待处理 Approval，以及 blocked、waiting_user_input Job。点击条目进入相应 Approval 或 Job 页面。

6.4 正在执行

显示正在 leased/running 的 Job、角色和类型。点击可以进入 Job 详情，进一步查看 Run、事件和输出。

6.5 Release 风险和最近活动

Release 风险突出显示 stale 和 publish-in-progress 对象。最近活动展示 Requirement/Release 状态变化，方便回到对应详情页。

工作台刷新只读取本地事实，不会因为页面刷新高频执行远程 Git fetch；需要远端状态时使用 Repo“同步”或 Release“刷新远端状态”。

7. 需求流程操作

7.1 提交 AI Native 需求

进入“需求”后点击“提交需求”，填写：

提交成功后：

1. Requirement、Repo 绑定、初始 status event、revision 和审计记录原子写入。
2. 状态进入 pending_acceptance。
3. 页面跳转到需求详情。

如果保存失败，不会留下半个 Requirement 或部分 Repo 绑定。

7.2 查看列表和模式

需求列表展示编号、标题、AI Native/传统模式、workflow 状态、priority 和更新时间。

传统 manual Requirement 只显示其实际存在的传统状态，不会显示虚构的 AI Native 分析/Review 阶段。

7.3 采纳需求并分配 Agent

在需求详情的“Agent 与 Review Policy”区域选择：

• 分析 Agent。
• 研发 Agent。
• 测试 Agent。
• 分析 Review Policy。
• 研发 Review Policy。

勾选“采纳并开始分析”会保存分配并推进流程；取消勾选则只保存分配。

如果 Agent、Policy、Repo 或健康条件不完整，服务端会拒绝推进，页面保留当前业务状态。

7.4 查看需求详情

详情页集中展示：

• 描述、验收标准和 priority。
• 关联 Repo 和状态。
• workflow 状态和可执行的下一步按钮。
• Agent/Policy 分配。
• 关联 Job 和状态轨迹。
• Artifact 全版本、内容和 final 标识。
• Artifact 新修订创建与版本比较。
• 只读代码 diff。
• 关联 Bug。

页面只会启用当前状态允许的操作。禁用按钮的提示会说明门禁条件。

7.5 编辑和并发冲突

需求标题保存使用 revision/ETag 乐观并发控制。如果 CLI 或其他浏览器已经修改了同一个需求，旧页面提交会得到 revision conflict，而不是覆盖新数据。

发生冲突时：

1. 页面保留当前输入草稿。
2. 重新查看最新详情。
3. 对比并重新提交需要保留的修改。

7.6 Artifact 操作

在需求详情中可以：

• 查看每种 Artifact 的所有版本。
• 点击版本读取 Markdown、JSON 或文本内容。
• 填写类型、阶段、标题和 Markdown 内容，创建新修订。
• 选择同一实体和类型的两个版本进行逐行比较。
• 通过 Artifact finalization Approval 选择最终需求设计和技术设计。

创建修订不会覆盖历史版本。浏览器不能提交宿主机绝对路径，Artifact 存储路径由服务端安全派生。

7.7 研发操作

“流程操作”只显示服务端返回的当前可执行动作，常见动作包括：

• 准备研发工作区。
• 完成研发。
• 重新打开需求。
• 归档需求。

准备 workspace、finish 和 reopen 可能涉及 Git worktree、commit、push 或清理，会进入“操作队列”。操作详情中可以查看 durable checkpoint 和事件。

8. Release、测试、Bug 和发布

8.1 创建 Release

进入“Release”点击“创建 Release”，填写：

• 标题。
• Release 编号。
• 需求编号，多个编号用逗号分隔。
• 默认测试命令，可留空。

创建 Release 涉及 workspace 和成员关系，因此请求会立即返回持久化 action，并跳转“操作队列”。等待 action 成功后再进入 Release 详情。

8.2 管理 Release 范围

Release 详情的“需求范围”区域可以：

• 查看当前成员及顺序。
• 从可选需求中加入成员。
• 将需求移出范围。

范围变更使用 Release revision 控制。其他终端或浏览器修改范围后，旧页面不能用陈旧 revision 覆盖新范围。

8.3 集成 Release

点击“集成需求”并确认后，操作进入持久化队列。集成过程：

• 为每个 Repo 创建/恢复 release worktree。
• 按范围合并需求 feature commit。
• 记录 integrated base SHA、release SHA 和诊断。
• 冲突或脏 worktree 按 Repo 报错。

浏览器关闭不会取消集成。重新打开“操作队列”可以继续查看同一个 operation key。

8.4 启动测试

Release 进入可测试状态后点击“开始测试”。确认面板允许：

• 填写本次 Test Agent ID；留空时使用 Release/流程默认值。
• 覆盖本次测试命令；留空时使用 Release 默认、Agent 默认或推断命令。

每次测试都创建独立 test run 和不可变快照，记录 requirement、repo、feature commit、release commit、实际命令和来源。

如果无法确定有效测试命令，不会静默跳过测试，而是创建 test_command_missing Approval。用户提供命令后恢复同一个测试上下文。

8.5 Test Run 详情

点击 Test run 可以查看：

• 当前状态和实际测试命令。
• 冻结的 requirement/repo/commit 快照。
• 关联 Bug。
• 历史 run 与当前 active run 的区别。

历史 passed 不等于当前可发布。只有最新、active、passed 且快照仍新鲜的 run 才能作为发布证明。

8.6 Bug 修复循环

Bug 详情展示标题、状态和严重度，并支持重试失败的修复 Job。

测试发现 Bug 后，典型流程为：

1. Bug 关联当前 Release、test run、Requirement 和 Repo。
2. Requirement 回到待研发状态。
3. Coding Agent 在对应 feature worktree 修复，而不是修改 release worktree。
4. 原 Release 被标记 stale，旧测试证明失效。
5. 修复完成后重新集成。
6. 创建新的完整测试快照并重新测试。

8.7 发布确认

发布按钮只在状态机允许时启用。点击后必须：

1. 查看当前 active passed test run。
2. 核对测试命令、冻结快照和 open Bug。
3. 勾选“我已核对测试结果、Bug 状态与发布快照”。
4. 可填写发布说明。
5. 确认执行。

请求会显式发送 tested=true，但服务端仍会重新校验：

• active test run 是 passed。
• run 属于当前 Release。
• immutable snapshot 与当前 scope/SHA 一致。
• 没有未解决 Bug。
• 发布确认 Approval 和当前状态有效。

部分 Repo 已发布、其余 Repo 失败时，Release 保持 publish_in_progress。修复外部问题后重试同一语义，已完成 Repo 不会被重复漂移。

9. Approval 使用说明

进入“Approval”可以查看所有人工门禁。详情页会根据类型渲染严格表单，而不是通用 JSON 输入框。

9.1 六类 Approval

9.2 处理原则

• 不确定时先打开关联 Requirement、Release、Job 或 Run 查看证据。
• “拒绝/阻塞”不是普通取消；它会按照 Approval 类型产生明确业务结果。
• Provider permission 只批准当前任务确实需要的最小 scope 和最短合理时效。
• 发布确认前不要只看“曾经通过”，必须看当前 active snapshot。

Approval 响应、原 Job 恢复、需求字段变更、状态事件和审计信息在同一业务事务提交，任一写入失败都会整体回滚。

10. 执行中心和实时事件

10.1 Job 列表

Job 列表展示：

• Job key。
• role 和 job type。
• 状态。
• attempt/max attempts。
• 取消和重试操作。

取消必须填写原因。服务端会持久化取消意图，避免 Web/daemon 分进程或重启时丢失。

10.2 Job 和 Run 详情

Job 详情展示所有 attempts 对应的 Run。Run 详情展示：

• Provider 和 attempt。
• Run 状态和错误。
• 结构化事件时间线。
• 脱敏 stdout/stderr 尾部。

原始输出读取有路径边界、大小上限、速率限制和脱敏处理，不会把 capability token、环境 secret 或任意宿主文件返回浏览器。

10.3 实时更新

Requirement、Release、Job、Run 和 Chat 页面使用 SSE 接收失效通知，并重新获取数据库快照。网络断开后浏览器会重连；如果游标已经失效，服务端发送 reset，页面重新加载当前事实。

SSE 只是低延迟通知，SQLite 和业务 Service 才是最终事实来源。

11. 操作队列和恢复

以下类型通常进入持久化操作队列：

• Repo add/update/sync/remove。
• Agent health。
• Requirement workspace prepare、finish、reopen。
• Release create、integrate、start-test、publish。
• 显式远端状态刷新。

Action 详情展示：

• action key 和类型。
• 资源范围。
• queued/running/succeeded/failed/interrupted/manual 等状态。
• attempt/max attempts。
• checkpoint。
• 按顺序记录的事件和错误。

11.1 什么时候取消

queued 或 running action 可以请求取消。取消只会在安全 step boundary 或支持 context cancellation 的外部命令处生效。已经完成的 Git 副作用不会被伪装成“从未执行”。

11.2 什么时候重试

failed、interrupted 或 manual action 在外部问题处理后可以重试，例如：

• Git 凭据恢复。
• 冲突或脏 worktree 已人工处理。
• Provider 重新可用。
• 网络恢复。
• publish-in-progress 的失败 Repo 已修复。

重试会读取 checkpoint，从可恢复位置继续，并遵守资源锁和 revision fence。

12. 主 Agent Chat

12.1 创建和选择会话

进入“主 Agent”后点击“新建会话”。每个会话和消息都持久化，不依赖浏览器页面一直打开。

12.2 选择上下文

发送消息前选择可见范围：

• 无业务上下文：仅做一般解释。
• 整个 workspace（只读）：允许读取全局状态，但不能直接绕过门禁写入。
• Requirement：冻结到指定需求范围。
• Release：冻结到指定 Release 范围。
• Job：冻结到指定 Job 及已授权关联对象。

显式上下文可以减少误关联和越界读取。消息创建后，其授权范围不会因为后续对话文本而自动扩大。

12.3 消息生命周期

每条用户消息会创建持久化 coordinator Job/Run/Event。页面显示 queued、running、succeeded、failed 或 cancelled 状态。

可以：

• 取消 queued/running 消息。
• 重试 failed/cancelled 消息。
• 查看主 Agent 返回的 Markdown 解释。
• 打开主 Agent 提议的结构化 action card。

主 Agent 只能提出受控操作卡。需求创建、Agent 分配、重试、集成、测试、发布和 Approval 仍必须进入相应结构化页面，不能通过聊天文本绕过确认门禁。

13. CLI 与 Web 对照

两种入口可以混用，但并发写入同一对象时必须尊重 revision conflict。不要在看到冲突后用重复点击覆盖其他终端刚提交的结果。

14. 日常推荐工作流

14.1 开始工作

workspace web start
workspace web status

进入页面后：

1. 查看工作台待办和 Release 风险。
2. 查看配置页 daemon、Provider、MCP 和 Worker 健康。
3. 先处理 waiting approval、blocked job 和 publish-in-progress。
4. 再提交新需求或启动新的 Release 操作。

14.2 需求到发布

提交需求
  -> 分配 Agent 和 Review Policy
  -> 采纳并开始分析
  -> 查看/修订/比较 Artifact
  -> 处理需求澄清和方案定稿 Approval
  -> 准备研发 workspace
  -> 查看开发 Job、Run、Review 和 diff
  -> 完成研发
  -> 创建 Release 并维护范围
  -> 集成
  -> 启动测试
  -> 修复 Bug、重新集成、重新测试
  -> 核对 active passed snapshot
  -> 发布确认
  -> 查看 publish action 完成

14.3 结束工作

Web 可以长期后台运行。如果需要停止 UI：

workspace web stop

停止 Web 不等于停止 coordinator daemon。如需停止 daemon，请在配置页操作，或使用：

workspace agent daemon stop

停止前先检查“操作队列”和“执行中心”，确认自己理解仍在后台运行的任务。

15. 常见问题和排障

进一步诊断命令：

workspace web status --json
workspace agent daemon status
workspace agent list
workspace mcp health
workspace approval list --status pending
workspace job list
workspace release status <release-key>

后台 Web 日志默认位于：

<workspace-home>/runtime/web/web.log

16. 安全注意事项

• Web 是本地单操作者控制面，不要直接暴露到互联网。
• 非 loopback 访问优先使用正确配置的 TLS。
• 配对码只通过可信终端传递，不要写入 issue、聊天群或长期日志。
• 不要把 Provider token、SSH 私钥、环境 secret 粘贴到需求、Artifact、聊天或 Approval 说明中。
• Provider 权限只批准最小 scope 和有限到期时间。
• Web 不提供任意文件浏览、Web Terminal 或任意宿主命令执行。
• Artifact、diff 和 raw tail 只能读取数据库登记对象派生的 canonical 路径。
• 发布前必须核对当前 active passed test snapshot，而不是只看历史测试记录。
• 使用 --force 停止、明文 LAN HTTP、危险发布和外部 Git 清理前，应确认影响范围。

按照本文流程使用时，Web 可以作为日常研发控制台；CLI 则继续适合脚本、自动化、紧急诊断和精确的低层操作。两者共享同一事实来源，可以根据场景安全切换。