zero-workspace 0.0.2

package/web/dist/assets/DocsView-Cxc0B63r.js

@@ -0,0 +1,1447 @@
+import{d as x,r as d,j as v,l as S,n as W,p as E,e as l,f as e,g as _,F as C,q as T,s as y,t as P,h as U,o as I,v as M,w as O,_ as z}from"./index-Cd_J3fZn.js";import{aC as R}from"./MarkdownContent-DXp6CtSP.js";const h=`# ZeroWorkspace 用户手册\r
+\r
+> AI 编程任务的结构化管理方案\r
+\r
+---\r
+\r
+## 这是什么？\r
+\r
+ZeroWorkspace 就像是 AI 的项目管理系统。\r
+\r
+想象你在和一个能干但健忘的同事合作——他很聪明，但对话一长就忘了早期的决策；任务一复杂就容易跑偏。ZeroWorkspace 就是给这个"同事"配的任务管理工具：把大任务拆成小步骤，每步都记录下来，随时能回顾进度。\r
+\r
+### 核心概念\r
+\r
+| 概念 | 说明 |\r
+|------|------|\r
+| **工作台** | ZeroWorkspace 本身，管理所有工作区的平台 |\r
+| **工作区** | 单个任务的完整记录，包含一棵任务树 |\r
+| **节点** | 任务树中的每个任务单元 |\r
+\r
+工作台是你的办公桌，工作区是桌上的每个项目文件夹，节点是文件夹里的待办事项。\r
+\r
+> 更多概念（节点类型、状态、派发模式等）请参阅 [术语表](#术语表)。\r
+\r
+### 解决什么问题？\r
+\r
+| 问题 | 没有工作台时 | 有工作台后 |\r
+|------|-------------|-----------|\r
+| **AI 忘事** | 对话超过 10 轮，AI 忘了开头说的需求 | 所有决策都记录在节点里，随时查阅 |\r
+| **过程黑盒** | 不知道 AI 做了什么、为什么这样做 | WebUI 实时展示任务树和执行日志 |\r
+| **粒度失控** | AI 一次规划太多，执行质量下降 | 强制拆分，一次只做一个任务 |\r
+| **难以继续** | 关掉对话就没了，下次从头来 | 工作区持久化，随时恢复进度 |\r
+\r
+### 谁会受益？\r
+\r
+- **你**：知道 AI 在做什么、做到哪了，能随时调整方向\r
+- **AI**：有结构化的任务管理，不再迷失在长对话中\r
+- **项目**：所有变更有迹可循，出问题能回溯\r
+\r
+---\r
+\r
+## 快速开始\r
+\r
+### 安装\r
+\r
+\`\`\`bash\r
+npm install -g zero-workspace\r
+zero-workspace setup  # 自动检测环境并配置\r
+\`\`\`\r
+\r
+**启动 WebUI 服务**（推荐）：\r
+\r
+\`\`\`bash\r
+zero-workspace webui  # 启动后保持终端窗口打开\r
+\`\`\`\r
+\r
+> **为什么要手动启动？** AI 助手启动时会自动启动 WebUI，后续打开的新对话会跳过启动共用服务，但关闭该对话窗口后 WebUI 也会停止，导致 WebUI 不可用。手动启动可以让 WebUI 独立运行，不受对话窗口影响。\r
+\r
+启动后访问终端显示的地址（默认 \`http://localhost:19540\`）即可查看任务进度。\r
+\r
+**其他管理命令**：\r
+\`\`\`bash\r
+zero-workspace webui status  # 查看服务状态\r
+zero-workspace webui stop    # 停止服务\r
+zero-workspace webui restart # 重启服务\r
+\`\`\`\r
+\r
+端口被占用时可指定其他端口：\`HTTP_PORT=19550 zero-workspace webui\`\r
+\r
+**支持的 AI 助手**：\r
+\r
+| AI 助手 | 支持程度 | 说明 |\r
+|---------|---------|------|\r
+| **Claude Code** | 完全支持 | 所有功能可用，推荐使用 |\r
+| **Cursor** | 基础支持 | subagent 和 skill 支持有限（见下方说明） |\r
+| **其他 MCP 兼容助手** | 基础功能 | 支持 MCP 即可使用核心功能 |\r
+\r
+Cursor 的限制：派发模式会降级为主进程执行（流程依然完整，但无法真正并行）；Skill 转化为读取说明形式，上下文消耗略有增加。\r
+\r
+其他智能体：只要支持 MCP 协议即可使用基础功能。如果智能体额外支持 subagent、skill 等特性，对应功能即可使用。配置方式需自行操作，可运行 \`zero-workspace -h\` 查看帮助。\r
+\r
+### 第一次使用\r
+\r
+**触发工作台的方式**：在对话中明确提及"**工作区**"或"**工作台**"。\r
+\r
+\`\`\`\r
+你：用工作台帮我实现一个用户登录功能\r
+\`\`\`\r
+\r
+或者：\r
+\r
+\`\`\`\r
+你：创建一个工作区，帮我做用户登录功能\r
+\`\`\`\r
+\r
+AI 会自动创建工作区并开始工作。下面是一个完整的对话示例：\r
+\r
+---\r
+\r
+**对话示例：实现登录功能**\r
+\r
+\`\`\`\r
+你：用工作台帮我实现一个用户登录功能\r
+\r
+AI：好的，我来创建工作区管理这个任务。\r
+\r
+    📋 工作区已创建：用户登录功能\r
+    🌐 WebUI 地址：http://localhost:19540/workspace/ws-xxx\r
+\r
+    让我先了解一下你的项目情况...\r
+\r
+    [AI 开始探索代码库]\r
+\r
+    我看到你的项目是一个 Express + React 应用，已有用户模型。\r
+\r
+    我制定了以下计划：\r
+    1. 设计登录 API 接口\r
+    2. 实现后端认证逻辑（JWT）\r
+    3. 创建前端登录表单\r
+    4. 添加登录状态管理\r
+\r
+    确认开始执行吗？\r
+\r
+你：好\r
+\r
+AI：开始执行第一个任务：设计登录 API 接口\r
+\r
+    [AI 开始工作...]\r
+\r
+    ✅ 任务 1 完成：\r
+    - 设计了 POST /api/auth/login 接口\r
+    - 入参：email, password\r
+    - 出参：token, user info\r
+\r
+    继续执行任务 2：实现后端认证逻辑\r
+\r
+    [继续工作...]\r
+\r
+你：（可以随时在浏览器打开 WebUI 查看进度）\r
+\r
+AI：🎉 所有任务已完成！\r
+\r
+    总结：\r
+    - 新增文件：src/routes/auth.js, src/components/Login.tsx\r
+    - 修改文件：src/App.tsx, src/store/index.ts\r
+    - 测试方式：访问 /login 页面\r
+\r
+    还有其他需要吗？\r
+\`\`\`\r
+\r
+---\r
+\r
+**关键点**：\r
+\r
+1. **你不需要学新命令**——用自然语言说任务就行\r
+2. **AI 会主动创建工作区**——不需要你手动操作\r
+3. **计划需要你确认**——AI 不会擅自开始执行\r
+4. **过程可视化**——随时打开 WebUI 看进度\r
+\r
+---\r
+\r
+## 术语表\r
+\r
+在深入使用之前，先了解几个核心概念。这些术语会在后文反复出现。\r
+\r
+### 基础结构\r
+\r
+| 术语 | 含义 |\r
+|------|------|\r
+| **工作台** | ZeroWorkspace 本身，管理所有工作区的平台 |\r
+| **工作区** | 单个任务的完整记录，包含目标、规则和一棵任务树 |\r
+| **节点** | 任务树中的每个任务单元，有类型、状态和内容 |\r
+\r
+### 节点类型\r
+\r
+每个节点有一个类型，决定它的用途：\r
+\r
+| 类型 | 用途 | 典型场景 |\r
+|------|------|----------|\r
+| **planning**（规划） | 拆分和组织子任务 | "实现登录功能"拆成"设计接口"+"实现后端"+"实现前端" |\r
+| **execution**（执行） | 实际执行工作 | 写代码、调研、测试 |\r
+\r
+**关系**：规划节点像文件夹，执行节点像文件。一个规划节点下可以有多个子节点（规划或执行）。\r
+\r
+**补充概念**：\r
+\r
+| 术语 | 含义 |\r
+|------|------|\r
+| **MEMO** | 独立于节点树的草稿区，用于存储长内容（设计文档、调研结果等） |\r
+| **引用** | 节点可以引用其他节点、MEMO 或外部文档，形成知识关联 |\r
+\r
+MEMO 适合存放跨节点复用的内容，比如一份设计方案可能被多个执行节点引用。\r
+\r
+**使用场景**：当内容不适合直接记录在节点中时（长文档、独立方案、跨节点复用的内容），可以让 AI 创建 MEMO：\r
+\r
+\`\`\`\r
+你：这个设计方案太长了，单独记录一下\r
+AI：好的，我创建一个 MEMO 来存放设计方案。\r
+\r
+    📝 MEMO 已创建：登录模块设计方案\r
+    已关联到当前节点。\r
+\`\`\`\r
+\r
+MEMO 由 AI 创建，可被多个节点引用。\r
+\r
+### 节点状态\r
+\r
+节点的生命周期通过状态流转表示：\r
+\r
+**执行节点状态**：\r
+\r
+| 状态 | 含义 | 下一步 |\r
+|------|------|--------|\r
+| **pending** | 等待开始 | AI 会按顺序执行，进入 implementing |\r
+| **implementing** | 正在执行 | AI 完成后进入 completed，失败进入 failed |\r
+| **completed** | 已完成 | 终态，任务结束 |\r
+| **failed** | 执行失败 | 可以重试（reopen），重新进入 pending |\r
+\r
+**规划节点状态**：\r
+\r
+| 状态 | 含义 | 下一步 |\r
+|------|------|--------|\r
+| **pending** | 等待开始 | 开始规划，进入 planning |\r
+| **planning** | 正在规划 | 子节点创建完成后，进入 monitoring |\r
+| **monitoring** | 等待子任务完成 | 所有子节点完成后，进入 completed |\r
+| **completed** | 所有子任务完成 | 终态 |\r
+| **cancelled** | 已取消 | 终态，任务放弃 |\r
+\r
+### 特殊节点角色\r
+\r
+某些执行节点有特殊角色，用于特定用途：\r
+\r
+| 角色 | 用途 | 何时出现 |\r
+|------|------|----------|\r
+| **info_collection**（信息收集） | AI 主动探索项目——扫描代码、读文档、理解架构 | 你没提供完整信息，AI 需要自己了解 |\r
+| **info_summary**（信息总结） | AI 整理已有信息——从对话/你提供的设计方案中提取 | 你已提供完整设计方案或需求描述 |\r
+| **dispatch_exec** | 派发任务的执行部分 | 启用派发模式时 |\r
+| **dispatch_spec** | 派发任务的规格审查 | 启用派发模式时 |\r
+| **dispatch_quality** | 派发任务的质量审查（可选） | 启用派发模式且开启质量审查时 |\r
+\r
+**info_collection vs info_summary**：二选一。AI 会根据你提供的信息完整度决定用哪个：\r
+- 你说"帮我实现搜索功能"→ AI 需要 info_collection，先探索代码库\r
+- 你说"根据这个设计文档实现搜索功能"（附设计方案）→ AI 用 info_summary，整理你提供的信息\r
+\r
+### 节点记录的信息\r
+\r
+每个节点会记录以下内容，帮助追踪任务全貌：\r
+\r
+| 字段 | 用途 | 何时记录 | 对话中如何触发 |\r
+|------|------|----------|----------------|\r
+| **requirement**（需求） | 任务描述、目标 | 创建节点时 | AI 自动记录，或你说"任务是..." |\r
+| **acceptanceCriteria**（验收标准） | WHEN/THEN 格式的验收条件 | 意图对齐时 | AI 整理后记录 |\r
+| **notes**（笔记） | 过程中的发现、决策 | 执行过程中 | 你说"记一下..."或 AI 主动记录 |\r
+| **conclusion**（结论） | 完成时的总结 | 任务完成时 | AI 完成时必须填写 |\r
+| **docs**（引用） | 关联的文档、MEMO、其他节点 | 任意时刻 | 你说"引用这个文档..." |\r
+| **Log**（日志） | 操作记录（谁在何时做了什么） | 自动记录 | 关键操作自动记录 |\r
+| **Problem**（问题） | 当前阻碍和下一步计划 | 遇到问题时 | 你说"卡住了"或 AI 主动记录 |\r
+\r
+**查看方式**：\r
+- **WebUI**：点击节点查看详情，包括需求、结论、日志、问题\r
+- **对话中**：问 AI "这个节点的结论是什么"、"现在卡在哪里"\r
+\r
+### 派发模式\r
+\r
+处理复杂任务时的一种执行方式：\r
+\r
+| 模式 | 特点 | 适用场景 |\r
+|------|------|----------|\r
+| **普通模式** | AI 直接执行，所有步骤在当前会话 | 简单任务、逻辑强依赖完整上下文的任务 |\r
+| **派发模式** | 子任务派发给独立 Agent 执行，完成后审查 | 复杂任务、可独立执行的子任务 |\r
+\r
+**派发节点状态**（仅在派发模式下）：\r
+\r
+| 状态 | 含义 |\r
+|------|------|\r
+| **pending** | 等待执行 |\r
+| **executing** | 子 Agent 正在执行 |\r
+| **passed** | 审查通过 |\r
+| **failed** | 审查失败，需重试 |\r
+\r
+### 能力包\r
+\r
+信息收集或信息总结阶段可选的功能模块，根据任务场景自动推荐：\r
+\r
+| 能力 | 用途 |\r
+|------|------|\r
+| **intent_alignment** | 意图对齐——澄清需求，确认验收标准 |\r
+| **context_discovery** | 上下文探索——扫描项目，理解架构 |\r
+| **solution_design** | 方案设计——设计接口和实现路径 |\r
+| **verification_strategy** | 验证策划——设计测试用例 |\r
+| **diagnosis** | 问题诊断——定位 bug 根因 |\r
+| **tech_research** | 技术调研——评估技术选型 |\r
+| **measurement_analysis** | 度量分析——性能基准测试 |\r
+\r
+### 其他概念\r
+\r
+| 术语 | 含义 |\r
+|------|------|\r
+| **会话绑定** | AI 会话与工作区的关联，确保对话中的操作作用到正确的工作区 |\r
+| **聚焦节点** | 当前正在操作的节点，AI 的工作上下文 |\r
+| **WebUI** | 浏览器中的可视化界面，实时展示任务树和执行日志 |\r
+\r
+---\r
+\r
+## 完整使用流程\r
+\r
+一个任务从开始到结束会经过 5 个阶段。了解这些阶段能帮你更好地与 AI 协作。\r
+\r
+### 阶段一：启动任务\r
+\r
+**触发方式**：在对话中明确提及"**工作区**"或"**工作台**"\r
+\r
+| 示例 | 说明 |\r
+|------|------|\r
+| "用工作台帮我实现搜索功能" | 提及"工作台" |\r
+| "创建一个工作区做这个任务" | 提及"工作区" |\r
+| "帮我实现搜索功能" | ❌ 不会触发，需加上"工作台/工作区" |\r
+\r
+**AI 会做什么**：\r
+\r
+1. 创建工作区（自动）\r
+2. 告知 WebUI 地址（你可以在浏览器打开查看）\r
+3. 询问任务场景（新功能/修复/优化/总结）\r
+\r
+**你会看到**：\r
+\r
+\`\`\`\r
+AI：好的，我来创建工作区管理这个任务。\r
+\r
+    📋 工作区：搜索功能开发\r
+    🌐 WebUI：http://localhost:19540/workspace/ws-xxx\r
+\r
+    这个任务属于哪种场景？\r
+    1. 新功能开发\r
+    2. Bug 修复\r
+    3. 性能优化\r
+    4. 总结分析\r
+\r
+你：1（或直接说"新功能"）\r
+\`\`\`\r
+\r
+### 阶段二：信息收集/整理\r
+\r
+根据你提供信息的完整度，AI 会选择不同的方式：\r
+\r
+**方式一：信息收集（info_collection）**\r
+\r
+当你只说了"帮我做XXX"，AI 需要**主动调研**：\r
+\r
+\`\`\`\r
+AI：让我先了解一下项目情况...\r
+\r
+    [扫描项目结构、读取文档]\r
+\r
+    我看到：\r
+    - 技术栈：Express + React\r
+    - 有两套 API：v1（旧）和 v2（新）\r
+\r
+    新功能应该加在哪个版本？\r
+\r
+你：v2\r
+\r
+AI：明白了，继续分析...\r
+\`\`\`\r
+\r
+**方式二：信息总结（info_summary）**\r
+\r
+当你已经详细描述了需求，或提供了完整设计方案，AI 只需要**整理确认**：\r
+\r
+\`\`\`\r
+你：用工作台帮我做用户登录，要求：\r
+    - 用 JWT 认证\r
+    - 支持邮箱和手机号登录\r
+    - 登录失败 3 次锁定 15 分钟\r
+\r
+AI：我来整理一下你的需求：\r
+\r
+    ## 需求确认\r
+\r
+    | WHEN | THEN |\r
+    |------|------|\r
+    | 用户输入正确凭据 | 返回 JWT token |\r
+    | 登录失败 3 次 | 账号锁定 15 分钟 |\r
+    | 锁定期间尝试登录 | 显示剩余锁定时间 |\r
+\r
+    还有其他要求吗？\r
+\r
+你：没了\r
+\r
+AI：好的，开始规划任务...\r
+\`\`\`\r
+\r
+**AI 如何选择**：\r
+- 你没提供项目细节 → 信息收集（探索代码库）\r
+- 你已经描述得很清楚 → 信息总结（整理确认）\r
+\r
+### 阶段三：确认计划\r
+\r
+**这是最重要的检查点**——AI 会在这里暂停，等你确认。\r
+\r
+**你会看到**：\r
+\r
+\`\`\`\r
+AI：信息收集完成，我制定了以下计划：\r
+\r
+    1. [规划] 设计搜索接口\r
+       - 定义 API 路由和参数\r
+       - 确定返回数据结构\r
+\r
+    2. [执行] 实现后端搜索逻辑\r
+       - 验收：GET /api/v2/search?q=xxx 返回结果\r
+\r
+    3. [执行] 创建前端搜索组件\r
+       - 验收：搜索框输入后显示结果列表\r
+\r
+    4. [执行] 添加搜索防抖和加载状态\r
+       - 验收：输入停顿 300ms 后才触发搜索\r
+\r
+    确认开始执行吗？\r
+\`\`\`\r
+\r
+**你可以**：\r
+\r
+| 你说 | AI 会 |\r
+|------|-------|\r
+| "好" / "可以" / "继续" | 开始执行计划 |\r
+| "第 3 个先不做" | 调整计划，跳过该任务 |\r
+| "把 2 和 3 合并" | 重新规划 |\r
+| "加一个分页功能" | 在计划中追加任务 |\r
+| "等等，先看看现有的搜索代码" | 暂停，AI 会去查看 |\r
+\r
+### 阶段四：执行任务\r
+\r
+**AI 会按顺序执行计划**，每个任务都会：\r
+\r
+1. **开始前**：标记任务为"进行中"\r
+2. **执行时**：写代码、记录日志\r
+3. **完成后**：写结论、标记为"已完成"\r
+\r
+**你可以**：\r
+\r
+\`\`\`\r
+你：做到哪了？\r
+\r
+AI：当前进度：\r
+    ✅ 任务 1：设计搜索接口（已完成）\r
+    🔄 任务 2：实现后端搜索逻辑（进行中）\r
+    ○ 任务 3：创建前端搜索组件（待开始）\r
+    ○ 任务 4：添加搜索防抖（待开始）\r
+\r
+    正在实现后端搜索逻辑，预计还需 2-3 分钟。\r
+\`\`\`\r
+\r
+**WebUI 状态说明**：\r
+\r
+| 图标/颜色 | 状态 | 含义 |\r
+|-----------|------|------|\r
+| ○ 灰色 | pending | 等待执行 |\r
+| ◐ 蓝色 | implementing | 正在执行 |\r
+| ● 绿色 | completed | 已完成 |\r
+| ✕ 红色 | failed | 执行失败 |\r
+| ⊘ 黄色 | monitoring | 等待子任务 |\r
+\r
+### 阶段五：完成交付\r
+\r
+**所有任务完成后，AI 会汇报**：\r
+\r
+\`\`\`\r
+AI：🎉 搜索功能开发完成！\r
+\r
+    完成情况：\r
+    ✅ 设计搜索接口 - 定义了 SearchRequest/SearchResponse 类型\r
+    ✅ 实现后端逻辑 - 支持关键词搜索和分页\r
+    ✅ 创建前端组件 - SearchBox + SearchResults\r
+    ✅ 添加防抖优化 - 300ms 防抖 + 加载状态\r
+\r
+    新增文件：\r
+    - src/api/v2/search.ts\r
+    - src/components/Search/index.tsx\r
+    - src/hooks/useSearch.ts\r
+\r
+    修改文件：\r
+    - src/routes/index.ts（添加路由）\r
+    - src/App.tsx（添加搜索入口）\r
+\r
+    测试方式：\r
+    1. 启动开发服务器：npm run dev\r
+    2. 访问首页，点击右上角搜索图标\r
+    3. 输入关键词，应该能看到搜索结果\r
+\r
+    还有其他需要吗？\r
+\`\`\`\r
+\r
+**你可以**：\r
+\r
+- 确认完成，结束任务\r
+- 提出新需求："再加一个搜索历史功能"\r
+- 报告问题："搜索结果没有高亮关键词"\r
+\r
+---\r
+\r
+## 如何保证 AI 行为\r
+\r
+你可能会问：AI 真的会按流程做事吗？会不会跳步骤、忘记记录、自己验证自己？\r
+\r
+ZeroWorkspace 用四层机制确保 AI "不得不"按规矩来：\r
+\r
+### 状态机：物理级约束\r
+\r
+普通 AI 助手全靠"自觉"——你说"先规划再执行"，AI 可能直接开始写代码。\r
+\r
+ZeroWorkspace 不信任自觉，用**状态转换表**强制约束：\r
+\r
+| 可能的问题 | 常见Spec | ZeroWorkspace |\r
+|-------------|---------|----------------|\r
+| AI 跳过规划直接执行 | 可能发生 | 不可能：节点必须从 pending→implementing，跳不过 |\r
+| 任务没完成就说"完成了" | 靠自觉 | 不可能：complete 需要填写 conclusion，系统验证 |\r
+| 同时做多个任务导致混乱 | 可能发生 | 不可能：同级节点只能有一个在执行中 |\r
+| 子任务没做完就汇总 | 可能发生 | 不可能：父节点 complete 前会检查所有子节点状态 |\r
+\r
+**实际效果**：AI 尝试非法操作时，系统直接拒绝并返回错误提示，而不是"希望"AI 遵守。\r
+\r
+### 自动监视与引导\r
+\r
+每次 AI 调用工具（修改代码、执行命令、操作节点），系统都会自动：\r
+\r
+1. **记录**：在日志中追加"谁在何时做了什么"\r
+2. **引导**：返回下一步必须做什么\r
+\r
+| 可能的问题 | 常见Spec | ZeroWorkspace |\r
+|-------------|---------|----------------|\r
+| AI 改了代码但没记录 | 经常发生 | 不可能：Hook 自动拦截每个修改操作并记录 |\r
+| AI 不知道下一步做什么 | "完成了，接下来呢？" | 系统自动返回 actionRequired，精确指导 |\r
+| AI 在多个任务间跳来跳去 | 聚焦点漂移 | Hook 自动聚焦到最后操作的节点 |\r
+\r
+### Skill：标准化流程\r
+\r
+市面上的 AI 助手用提示词引导行为，但提示词是建议，AI 可以忽略。\r
+\r
+ZeroWorkspace 的 Skill 是**强制性 SOP**：\r
+\r
+- **信息收集**：必须按"定位入口→分析依赖→追踪数据流→输出快照"的流程\r
+- **意图对齐**：必须产出 WHEN/THEN 格式的验收标准\r
+- **任务执行**：必须按"评估→计划→执行→验证→交付"五步走\r
+- **规格审查**：必须逐条验证验收标准，任何一条失败=整体失败\r
+\r
+| 可能的问题 | 常见Spec | ZeroWorkspace |\r
+|-------------|---------|----------------|\r
+| 每次执行方式不一致 | 看心情 | 同类任务强制走相同流程 |\r
+| 说"完成了"但没验证 | 靠自觉 | Skill 强制：执行→验证→记录→完成，缺一不可 |\r
+| 验证走过场 | 自己检查自己 | 审查 Skill 要求逐条验证，附带证据 |\r
+\r
+### 派发系统：执行与审查分离\r
+\r
+这是 ZeroWorkspace 核心设计之一：**让不同的 AI 相互检查**。\r
+\r
+常见Spec是"自己做自己查"——就像考试自己批卷子，很难客观。\r
+\r
+派发模式下，系统会启动多个独立 AI：\r
+\r
+| 角色 | 职责 | 约束 |\r
+|------|------|------|\r
+| **执行者**（zero-executor） | 写代码、实现功能 | 只能改需求范围内的代码，完成后提交审查 |\r
+| **规格审查**（zero-reviewer） | 验证是否符合需求 | **不能修改代码**，必须独立验证，不信任执行者的结论 |\r
+| **质量审查**（zero-reviewer） | 检查代码质量 | **不能修改代码**，检查可读性、安全性、性能 |\r
+\r
+| 可能的问题 | 常见Spec | ZeroWorkspace 派发模式 |\r
+|-------------|---------|------------------------|\r
+| 自己做自己查 | 总是这样 | 执行与审查由不同 AI 完成 |\r
+| 审查倾向于通过 | 利益冲突 | 审查者无法修改代码，只能判 pass/fail |\r
+| 失败后代码残留 | 手动回滚 | Git 模式自动回滚到执行前 |\r
+| 重试没有方向 | 从头再来 | 失败原因会传递给下一次执行 |\r
+\r
+### 为什么这套机制有效？\r
+\r
+核心哲学：**不依赖 AI 的"自觉"，用系统强制确保合规**。\r
+\r
+\`\`\`\r
+常见Spec流程的信任链：\r
+  用户 → 相信 AI → AI 自觉遵守 → 结果\r
+\r
+ZeroWorkspace 的信任链：\r
+  用户 → 系统强制 → AI 不得不遵守 → 结果\r
+         ↑\r
+    状态机拒绝非法操作\r
+    Hook 自动记录和引导\r
+    Skill 强制标准流程\r
+    派发分离执行与审查\r
+\`\`\`\r
+\r
+**你能感知到的变化**：\r
+\r
+- 打开 WebUI，每个节点都有完整的日志，知道 AI 做了什么\r
+- AI 不会跳过中间流程，必须一步步走完流程\r
+- 派发模式下，你能看到执行、审查、质量检查三个独立的记录\r
+- 出问题时，能追溯到具体哪一步出了问题\r
+\r
+---\r
+\r
+## 场景指南\r
+\r
+不同类型的任务有不同的最佳实践。以下是四种常见场景的完整对话示例。\r
+\r
+### 场景 1：新功能开发\r
+\r
+**适用于**：添加新功能、实现新特性、创建新模块\r
+\r
+**情况 A：你只说了要做什么（AI 需要探索项目）**\r
+\r
+\`\`\`\r
+你：用工作台帮我给博客系统加一个评论功能\r
+\r
+AI：好的，我来创建工作区管理这个任务。\r
+\r
+    📋 工作区：博客评论功能\r
+    🌐 WebUI：http://localhost:19540/workspace/ws-abc123\r
+\r
+    让我先了解一下你的博客系统...\r
+\r
+    [探索代码库]\r
+\r
+    我看到：\r
+    - 后端：Express + MongoDB\r
+    - 前端：React + TailwindCSS\r
+    - 已有文章模型 (Post)\r
+\r
+    我需要确认几个问题：\r
+    1. 评论需要用户登录吗？\r
+    2. 是否需要嵌套回复？\r
+\r
+你：需要登录，暂时不需要嵌套回复\r
+\r
+AI：明白了，我制定了以下计划...\r
+\`\`\`\r
+\r
+**情况 B：你提供了完整设计方案（AI 只需整理确认）**\r
+\r
+\`\`\`\r
+你：用工作台帮我做评论功能，设计如下：\r
+    - 数据模型：Comment { content, authorId, postId, createdAt }\r
+    - API：POST/GET /posts/:id/comments, DELETE /comments/:id\r
+    - 前端：CommentList + CommentInput 组件\r
+    - 需要登录才能评论\r
+\r
+AI：好的，我来整理一下你的设计方案。\r
+\r
+    📋 工作区：博客评论功能\r
+    🌐 WebUI：http://localhost:19540/workspace/ws-abc123\r
+\r
+    ## 需求确认\r
+\r
+    | WHEN | THEN |\r
+    |------|------|\r
+    | 用户提交评论 | 调用 POST API，评论显示在列表 |\r
+    | 未登录用户访问 | 隐藏评论输入框 |\r
+    | 删除评论 | 调用 DELETE API，列表刷新 |\r
+\r
+    设计方案清晰，确认开始执行吗？\r
+\r
+你：好\r
+\r
+AI：开始执行...\r
+\`\`\`\r
+\r
+### 场景 2：Bug 调试修复\r
+\r
+**适用于**：修复 bug、解决报错、排查问题\r
+\r
+**情况 A：你只描述了现象（AI 需要诊断）**\r
+\r
+\`\`\`\r
+你：用工作台帮我查一下，用户登录后刷新页面会被踢出\r
+\r
+AI：好的，这是一个 Bug 修复任务。让我创建工作区。\r
+\r
+    📋 工作区：登录状态丢失修复\r
+    🌐 WebUI：http://localhost:19540/workspace/ws-def456\r
+\r
+    让我先诊断问题...\r
+\r
+    [分析认证相关代码]\r
+\r
+    我找到了原因：AuthContext.tsx 中没有验证 token 是否过期，\r
+    当 token 过期时 decodeToken 返回 null，导致用户被踢出。\r
+\r
+    修复方案：添加 token 过期检查\r
+\r
+    确认这个修复方案吗？\r
+\r
+你：好\r
+\r
+AI：开始修复...\r
+\`\`\`\r
+\r
+**情况 B：你已经定位了问题原因（AI 只需确认方案）**\r
+\r
+\`\`\`\r
+你：用工作台帮我修一个 bug：\r
+    - 现象：登录后刷新会被踢出\r
+    - 原因：AuthContext.tsx 的 useEffect 没有验证 token 过期\r
+    - 方案：添加 isTokenExpired() 检查，过期则跳转登录页\r
+\r
+AI：好的，我来整理一下你的修复方案。\r
+\r
+    📋 工作区：登录状态丢失修复\r
+    🌐 WebUI：http://localhost:19540/workspace/ws-def456\r
+\r
+    ## 修复确认\r
+\r
+    | WHEN | THEN |\r
+    |------|------|\r
+    | token 有效 | 正常加载用户信息 |\r
+    | token 过期 | 显示"登录已过期"，跳转登录页 |\r
+\r
+    方案清晰，确认开始修复吗？\r
+\r
+你：好\r
+\r
+AI：开始修复...\r
+\`\`\`\r
+\r
+### 场景 3：代码优化重构\r
+\r
+**适用于**：性能优化、代码重构、技术债清理\r
+\r
+**情况 A：你只说了要优化（AI 需要分析性能）**\r
+\r
+\`\`\`\r
+你：用工作台帮我优化一下，首页加载太慢了\r
+\r
+AI：好的，这是一个性能优化任务。让我创建工作区。\r
+\r
+    📋 工作区：首页性能优化\r
+    🌐 WebUI：http://localhost:19540/workspace/ws-ghi789\r
+\r
+    让我先分析性能瓶颈...\r
+\r
+    [分析性能]\r
+\r
+    当前数据：首屏 4.2s，JS 包 1.8MB\r
+    问题：没有代码分割，图表库未按需加载\r
+\r
+    优化计划：\r
+    1. 配置路由级代码分割\r
+    2. 动态导入图表库\r
+    3. 添加图片懒加载\r
+\r
+    确认开始优化吗？\r
+\r
+你：好\r
+\r
+AI：开始优化...\r
+\`\`\`\r
+\r
+**情况 B：你已经提供了性能报告（AI 只需确认方案）**\r
+\r
+\`\`\`\r
+你：用工作台优化首页性能，我的分析：\r
+    - 当前：首屏 4.2s，JS 1.8MB\r
+    - 问题：bundle 没分割，chart.js 未按需加载\r
+    - 方案：路由分割 + 动态导入 + 图片懒加载\r
+\r
+AI：好的，我来整理一下你的优化方案。\r
+\r
+    📋 工作区：首页性能优化\r
+    🌐 WebUI：http://localhost:19540/workspace/ws-ghi789\r
+\r
+    ## 优化确认\r
+\r
+    | 优化项 | 预期效果 |\r
+    |--------|----------|\r
+    | 路由级代码分割 | 首页 JS 减少 50% |\r
+    | 动态导入图表库 | 首页不再包含 chart.js |\r
+    | 图片懒加载 | 首屏只加载可见图片 |\r
+\r
+    方案清晰，确认开始优化吗？\r
+\r
+你：好\r
+\r
+AI：开始优化...\r
+\`\`\`\r
+\r
+### 场景 4：文档/总结任务\r
+\r
+**适用于**：代码分析、文档生成、技术调研\r
+\r
+**情况 A：你需要 AI 探索代码库**\r
+\r
+\`\`\`\r
+你：创建一个工作区，帮我梳理一下这个项目的架构，我要写技术文档\r
+\r
+AI：好的，这是一个总结分析任务。让我创建工作区。\r
+\r
+    📋 工作区：项目架构梳理\r
+    🌐 WebUI：http://localhost:19540/workspace/ws-jkl012\r
+\r
+    让我分析项目结构...\r
+\r
+    [扫描项目、读取文档、分析代码]\r
+\r
+    ## 项目架构总结\r
+\r
+    ### 技术栈\r
+    | 层级 | 技术选型 |\r
+    |------|----------|\r
+    | 前端 | React + Redux + TailwindCSS |\r
+    | 后端 | Express + Sequelize |\r
+    | 数据库 | PostgreSQL |\r
+    | 部署 | Docker + Nginx |\r
+\r
+    ### 目录结构\r
+    src/\r
+    ├── api/          # 后端 API\r
+    ├── web/          # 前端应用\r
+    ├── shared/       # 共享代码\r
+    └── scripts/      # 工具脚本\r
+\r
+    ### 核心模块\r
+    1. 用户系统 - 注册、登录、权限\r
+    2. 商品系统 - CRUD、分类、搜索\r
+    3. 订单系统 - 下单、支付、物流\r
+    4. 后台管理 - 统计、内容管理\r
+\r
+    需要我把这些内容生成 ARCHITECTURE.md 文档吗？\r
+\r
+你：好\r
+\r
+AI：[生成文档]\r
+\r
+    ✅ 已创建 docs/ARCHITECTURE.md\r
+\r
+    文档包含：\r
+    - 项目概述\r
+    - 技术栈说明\r
+    - 目录结构详解\r
+    - 核心模块说明\r
+    - 数据流图\r
+    - 部署架构\r
+\r
+    需要补充其他内容吗？\r
+\`\`\`\r
+\r
+**情况 B：你已经提供了项目说明（AI 只需整理成文档）**\r
+\r
+\`\`\`\r
+你：用工作台帮我生成架构文档，项目信息如下：\r
+    - 技术栈：Express + React + PostgreSQL\r
+    - 目录：api/(后端), web/(前端), shared/(共享)\r
+    - 模块：用户、商品、订单、后台\r
+\r
+AI：好的，我来整理你提供的项目信息。\r
+\r
+    📋 工作区：项目架构梳理\r
+    🌐 WebUI：http://localhost:19540/workspace/ws-jkl012\r
+\r
+    ## 信息确认\r
+\r
+    根据你的描述，项目架构如下：\r
+    - 三层架构：前端 + 后端 + 共享\r
+    - 四大模块：用户、商品、订单、后台\r
+\r
+    还有需要补充的信息吗？（如部署方式、数据流等）\r
+\r
+你：没了，直接生成\r
+\r
+AI：[生成文档]\r
+\r
+    ✅ 已创建 docs/ARCHITECTURE.md\r
+\`\`\`\r
+\r
+---\r
+\r
+## 进阶功能\r
+\r
+掌握了基础流程后，以下进阶功能能让你更高效地使用 ZeroWorkspace。\r
+\r
+### 继续之前的任务\r
+\r
+关掉对话后，下次开启新对话时，建议让 AI **先了解状态再决定下一步**：\r
+\r
+\`\`\`\r
+你：看看工作区的状态\r
+\r
+AI：📋 博客评论功能 (ws-abc123)\r
+\r
+    整体进度：2/3 任务已完成\r
+\r
+    任务状态：\r
+    ✅ 任务 1：创建评论数据模型（已完成）\r
+    ✅ 任务 2：实现评论 API（已完成）\r
+    🔄 任务 3：创建评论组件（进行中）\r
+\r
+    当前聚焦：任务 3 - 创建评论组件\r
+    上次停在：组件结构设计阶段\r
+\r
+你：继续任务 3\r
+\r
+AI：好的，让我先回顾一下任务 3 的进展...\r
+\r
+    [查看节点日志和已完成内容]\r
+\r
+    我看到上次已经完成了：\r
+    - 组件目录结构\r
+    - CommentList 组件骨架\r
+\r
+    接下来需要：\r
+    - 实现评论输入框\r
+    - 添加样式\r
+\r
+    继续吗？\r
+\`\`\`\r
+\r
+**推荐的恢复流程**：\r
+\r
+1. **先查看状态**："看看工作区状态" / "进度怎么样了"\r
+2. **确认聚焦点**：AI 会告诉你当前在哪个节点\r
+3. **决定下一步**：继续当前任务 / 切换到其他任务\r
+\r
+**派发模式下的恢复**：\r
+\r
+如果之前在使用派发模式，对话清空后 AI 可能丢失派发上下文。建议：\r
+\r
+\`\`\`\r
+你：看看工作区状态，我之前在用派发模式\r
+\r
+AI：📋 博客评论功能 (ws-abc123)\r
+\r
+    派发状态：已启用\r
+    派发母节点：任务 3 - 创建评论组件\r
+\r
+    派发子节点状态：\r
+    - exec（执行）：已完成\r
+    - spec（规格审查）：进行中\r
+    - quality（质量审查）：待开始\r
+\r
+    需要我继续派发流程吗？\r
+\r
+你：好\r
+\r
+AI：回到派发母节点，继续规格审查...\r
+\`\`\`\r
+\r
+> **提示**：如果 AI 对派发状态理解不清晰，可以说"回到派发母节点，重新开始派发流程"让 AI 重新构建派发上下文。\r
+\r
+**上下文自动压缩时的处理**：\r
+\r
+对话过长时，AI 助手会自动压缩上下文（类似清空对话）。这时可能出现 AI "失忆"的情况，需要观察和提醒：\r
+\r
+\`\`\`\r
+你：（发现 AI 好像忘了之前讨论的内容）\r
+    你之前在做什么？看看工作区状态\r
+\r
+AI：让我查看一下...\r
+    [读取工作区和节点信息]\r
+\r
+    我看到当前在任务 3，之前的进展是...\r
+\`\`\`\r
+\r
+**降低上下文压缩风险的方法**：\r
+\r
+- **分段式完成任务**：将大任务拆分为独立阶段（调研 → 规划 → 执行 → 总结），每个阶段完成后记录结论再进入下一阶段\r
+- **使用派发模式**：复杂任务用派发模式执行，子 Agent 独立运行，不占用主会话上下文\r
+- **及时记录关键信息**：让 AI 把重要决策和发现记录到节点的 notes 或 conclusion 中\r
+\r
+### 追加需求 / 重开任务\r
+\r
+任务完成后想追加功能：\r
+\r
+\`\`\`\r
+你：（任务已完成）还想加一个评论点赞功能\r
+\r
+AI：好的，我来追加这个需求。\r
+\r
+    在当前工作区新增任务：\r
+    4. [执行] 实现评论点赞\r
+       - 后端 API：POST /api/comments/:id/like\r
+       - 前端显示点赞数和点赞按钮\r
+\r
+    确认开始吗？\r
+\`\`\`\r
+\r
+任务失败后想重试：\r
+\r
+\`\`\`\r
+你：重新做一遍\r
+\r
+AI：好的，我把任务 3 重新打开。\r
+\r
+    当前状态：implementing（进行中）\r
+\r
+    之前的失败原因是：组件样式冲突\r
+\r
+    这次我会：\r
+    1. 先检查现有样式\r
+    2. 使用 CSS Module 避免冲突\r
+\r
+    开始重试？\r
+\`\`\`\r
+\r
+新需求较复杂时，让 AI 重新收集信息：\r
+\r
+\`\`\`\r
+你：还想加一个评论审核功能，这个比较复杂，先收集一下信息\r
+\r
+AI：好的，这是一个较复杂的新需求，我先进行信息收集。\r
+\r
+    [创建信息收集节点]\r
+\r
+    让我了解一下：\r
+    1. 审核流程是怎样的？（自动 / 人工 / 混合）\r
+    2. 审核状态有哪些？（待审核 / 通过 / 拒绝）\r
+    3. 谁有审核权限？\r
+    4. 是否需要敏感词过滤？\r
+\r
+你：人工审核，管理员有权限，需要敏感词过滤\r
+\r
+AI：明白了，让我再看看现有的权限系统...\r
+\r
+    [探索代码库]\r
+\r
+    信息收集完成，我制定了以下计划：\r
+\r
+    1. [执行] 添加评论状态字段\r
+    2. [执行] 实现敏感词过滤\r
+    3. [执行] 创建审核 API\r
+    4. [执行] 添加管理后台审核页面\r
+\r
+    确认开始吗？\r
+\`\`\`\r
+\r
+> **提示**：复杂的新需求走一遍信息收集流程，能让 AI 更好地理解需求并制定合理计划，避免遗漏关键点。\r
+\r
+### 派发模式\r
+\r
+对于复杂任务，AI 可以把子任务派发给专门的执行器。\r
+\r
+**派发模式 vs 普通模式**：\r
+\r
+| 对比 | 普通模式 | 派发模式 |\r
+|------|----------|----------|\r
+| 执行者 | 主 AI 直接执行 | 专门的 executor 执行 |\r
+| 上下文 | 完整对话上下文 | 只有当前任务上下文 |\r
+| 审查 | 无 | 自动规格审查 |\r
+| 回滚 | 手动 | 自动（Git 模式） |\r
+| 适合 | 简单任务、强依赖完整上下文的任务 | 复杂任务、可独立执行的子任务 |\r
+\r
+**什么时候用派发模式**：\r
+\r
+| 任务类型 | 建议 | 原因 |\r
+|----------|------|------|\r
+| 中大规模代码任务 | ✅ 推荐派发 | 可拆分为独立单元执行 |\r
+| 整理/梳理任务 | ✅ 推荐派发 | 用派发整理局部结论，再集中总结 |\r
+| 小规模任务 | ❌ 不推荐 | 派发开销可能超过收益 |\r
+| Bug 修复 | ⚠️ 部分使用 | 上下文强相关，可只用派发做验证环节 |\r
+\r
+**简单判断**：如果任务能拆成多个"互不依赖"的子任务，就适合派发。\r
+\r
+**对话示例**：\r
+\r
+\`\`\`\r
+你：这个任务比较复杂，用派发模式\r
+\r
+AI：好的，启用派发模式。\r
+\r
+    派发模式说明：\r
+    - 每个子任务由独立的 executor 执行\r
+    - 执行完成后会有 reviewer 审查结果\r
+    - 失败时自动回滚代码变更\r
+\r
+    当前任务会被派发为：\r
+    1. 执行器执行 → 2. 规格审查 → 3. 质量审查（可选）\r
+\r
+    确认启用？\r
+\r
+你：好\r
+\r
+AI：派发模式已启用。\r
+\r
+    开始派发任务 1 给 zero-executor...\r
+\r
+    [executor 独立执行]\r
+\r
+    ✅ 执行完成\r
+    开始规格审查...\r
+\r
+    [reviewer 检查结果]\r
+\r
+    ✅ 规格审查通过\r
+    - 所有验收标准满足\r
+    - 代码变更已合并\r
+\r
+    继续派发下一个任务...\r
+\`\`\`\r
+\r
+**质量审查（可选）**：\r
+\r
+质量审查用于检查代码可读性、安全性、性能等，适合以下场景：\r
+\r
+| 场景 | 建议 |\r
+|------|------|\r
+| 代码质量要求高 | ✅ 开启 |\r
+| 重构/优化任务 | ✅ 开启 |\r
+| 快速迭代/原型开发 | ❌ 可不开启，节省时间 |\r
+\r
+AI 默认倾向不开启。你可以通过对话告知 AI：\r
+- "这个任务开启质量审查"\r
+- "最后一个子任务做质量审查"\r
+- "重构相关的任务都要质量审查"\r
+\r
+**成本与回滚**：\r
+\r
+- **时间消耗**：派发模式为每个子任务构建独立上下文并进行完整的实现——验证流程，时间消耗比普通模式更高。适合用在复杂或中大型任务上。\r
+- **自动回滚**：是 **Git 模式专属**功能，通过 Git 分支管理实现。\r
+\r
+> ⚠️ **注意**：Git 模式涉及 Git 操作，属于**实验功能**。使用前建议做好代码备份。\r
+\r
+### 多工作区管理\r
+\r
+同时进行多个任务时：\r
+\r
+\`\`\`\r
+你：我现在有几个工作区？\r
+\r
+AI：你有 3 个工作区：\r
+\r
+    1. 📋 博客评论功能 (ws-abc123)\r
+       状态：进行中，2/3 任务完成\r
+\r
+    2. 📋 首页性能优化 (ws-ghi789)\r
+       状态：已完成\r
+\r
+    3. 📋 用户登录修复 (ws-def456)\r
+       状态：已完成\r
+\r
+你：切换到评论功能\r
+\r
+AI：已切换到工作区：博客评论功能\r
+\r
+    当前进度：\r
+    ✅ 任务 1：创建评论数据模型\r
+    ✅ 任务 2：实现评论 API\r
+    🔄 任务 3：创建评论组件（进行中）\r
+\r
+    继续执行任务 3 吗？\r
+\`\`\`\r
+\r
+### 工作区管理\r
+\r
+**归档与删除**\r
+\r
+完成的工作区建议**归档**而非删除：\r
+\r
+\`\`\`\r
+你：把这个工作区归档\r
+AI：已归档工作区：博客评论功能\r
+\`\`\`\r
+\r
+| 处理方式 | 说明 |\r
+|----------|------|\r
+| **归档**（推荐） | 不会被 AI 直接查询到，提高巡检效率；可供后期复盘 |\r
+| **删除** | 不建议删除流程完备的工作区，会丢失执行记录 |\r
+\r
+> **提示**：归档的工作区仍保留在 \`.zero-workspace/\` 目录中，需要时可以恢复。\r
+\r
+**暂停与恢复**\r
+\r
+如果需要暂停任务，不建议直接关闭对话。更好的做法：\r
+\r
+\`\`\`\r
+你：我要离开了，把当前进度记录一下\r
+AI：好的，我来记录当前状态...\r
+\r
+    [记录到节点 notes/conclusion]\r
+\r
+    已记录：\r
+    - 当前在：任务 3 - 创建评论组件\r
+    - 进度：组件结构已完成，样式待实现\r
+    - 下一步：添加 CSS Module 样式\r
+\r
+    下次继续时说"看看工作区状态"即可恢复。\r
+\`\`\`\r
+\r
+**原因**：直接关闭可能导致执行中的节点状态不完整。让 AI 先记录上下文，后续恢复更顺畅。\r
+\r
+**导入导出**\r
+\r
+工作区支持导出为 \`.twsp\` 文件，便于备份、迁移或分享：\r
+\r
+| 操作 | 入口 | 说明 |\r
+|------|------|------|\r
+| **导出** | 工作区详情页 →「EXPORT」按钮 | 导出为 .twsp 文件，包含完整工作区数据 |\r
+| **导入** | 设置 → 索引管理 → 管理 | 拖拽 .twsp 文件或目录，自动扫描导入 |\r
+\r
+导入支持三种方式：\r
+- 拖拽 \`.twsp\` 文件直接导入\r
+- 拖拽项目目录自动扫描\r
+- 手动输入路径\r
+\r
+> **提示**：导入功能还可以扫描已索引路径，发现新工作区并清理无效条目。\r
+\r
+### 查看和导出日志\r
+\r
+每个任务的执行过程都会被记录：\r
+\r
+\`\`\`\r
+你：看看任务 2 的执行日志\r
+\r
+AI：任务 2 执行日志：\r
+\r
+    [10:32:15] 开始执行：实现评论 API\r
+    [10:32:20] 分析现有 API 结构\r
+    [10:33:05] 创建 src/routes/comments.js\r
+    [10:33:45] 实现 POST /api/posts/:id/comments\r
+    [10:34:30] 实现 GET /api/posts/:id/comments\r
+    [10:35:10] 实现 DELETE /api/comments/:id\r
+    [10:35:50] 添加路由注册\r
+    [10:36:00] 完成：评论 API 实现完成\r
+\r
+你：导出整个工作区的日志\r
+\r
+AI：日志已导出到：.zero-workspace/博客评论功能_ws-abc123/export.md\r
+\`\`\`\r
+\r
+### WebUI 功能\r
+\r
+访问 \`http://localhost:19540/workspace/<工作区ID>\` 可以：\r
+\r
+| 功能 | 说明 |\r
+|------|------|\r
+| 任务树视图 | 树状展示所有节点，颜色区分状态 |\r
+| 节点详情 | 点击节点查看需求、结论、日志 |\r
+| 进度统计 | 各状态节点数量，完成百分比 |\r
+| MEMO 查看 | 查看 AI 记录的备忘信息 |\r
+| 实时更新 | 自动刷新，无需手动刷新 |\r
+\r
+> **注意**：WebUI 仅支持本机访问（localhost）。如需远程访问，可通过端口映射工具实现。\r
+\r
+### OpenSpec 导入（实验功能）\r
+\r
+如果你的项目使用了 OpenSpec，可以通过两种方式与工作台配合使用。\r
+\r
+**信息总结**：把 OpenSpec 当做 PRD 来理解和梳理，产出是文档/总结。\r
+\r
+\`\`\`\r
+你：用工作台帮我梳理一下 OpenSpec 里 feature-login 的变更内容\r
+AI：[创建 summary 场景工作区] → [阅读 proposal.md、tasks.md] → [产出结构化总结]\r
+\`\`\`\r
+\r
+适合：想先理解变更内容、提取关键信息，再决定如何执行。\r
+\r
+**直接导入**：把 OpenSpec 任务结构批量映射为工作区节点，可直接开始执行。\r
+\r
+\`\`\`\r
+你：把 OpenSpec 的 feature-login 导入到工作台\r
+AI：[列出变更详情] → [确认后执行导入] → [直接创建工作区和对应节点]\r
+\`\`\`\r
+\r
+适合：已确定要执行 OpenSpec 中的任务，想跳过规划直接开始。\r
+\r
+> ⚠️ 这是实验功能，适合已有 OpenSpec 规范的项目。普通用户无需关注。\r
+\r
+---\r
+\r
+## 问题诊断\r
+\r
+### FAQ：常见问题\r
+\r
+**Q1：工作区是什么？我必须用吗？**\r
+\r
+工作区是一个任务的完整记录，包括需求、计划、执行过程、结论。你不是必须用——但当任务超过 3 步时，工作区能帮 AI 保持清晰的思路，也让你能追踪进度。\r
+\r
+**Q2：我可以不用工作台直接让 AI 做吗？**\r
+\r
+可以。只要不提及"工作区"或"工作台"，AI 会直接执行而不创建工作区。比如直接说"帮我改个 bug"，AI 就会像平常一样工作。适合简单的一次性任务。\r
+\r
+**Q3：为什么 AI 会问我确认计划？能跳过吗？**\r
+\r
+这是防止 AI 跑偏的关键检查点。你可以说"以后不用确认了"，但建议保留——看一眼计划只需要 10 秒，但修复跑偏的结果可能要 10 分钟。\r
+\r
+**Q4：任务太大了，AI 做不完怎么办？**\r
+\r
+说"这个太大了，帮我拆分"。AI 会把大任务分解成多个小任务，每个都有明确的验收标准。\r
+\r
+**Q5：AI 做错了怎么办？**\r
+\r
+说"这个不对，重新做"或"回滚"。如果是派发模式，代码会自动回滚；如果不是，你可能需要手动 git reset。\r
+\r
+**Q6：怎么看 AI 做了什么？**\r
+\r
+- **日常查看**：打开 WebUI，直观展示任务树、节点详情、执行日志\r
+- **查看元数据**：只有需要查看底层管理数据时，才去 \`.zero-workspace/\` 目录\r
+\r
+**Q7：关掉对话后工作区还在吗？**\r
+\r
+在。工作区存储在项目目录的 \`.zero-workspace/\` 下，不会因为关闭对话而丢失。下次说"继续"就能恢复。\r
+\r
+**Q8：一个项目可以有多个工作区吗？**\r
+\r
+可以。每个工作区是独立的任务，你可以同时进行多个任务。但建议完成一个再开始下一个，避免上下文混乱。\r
+\r
+**Q9：派发模式和普通模式有什么区别？**\r
+\r
+详见 [进阶功能 > 派发模式](#派发模式适合复杂任务)。简单来说：普通模式由主 AI 直接执行，派发模式将子任务交给专门的 executor，适合可拆分的中大型任务。\r
+\r
+**Q10：为什么有时候 AI 不创建工作区？**\r
+\r
+因为你没有明确提及"工作区"或"工作台"。试试说"用工作台帮我做xxx"或"创建一个工作区"。\r
+\r
+**Q11：我可以手动操作节点吗？**\r
+\r
+| 操作类型 | 能否操作 | 说明 |\r
+|----------|---------|------|\r
+| 节点逻辑关系（添加/删除/状态转换） | WebUI 可操作 | 仅在 AI 出现重要纰漏时使用，AI 会在下次调用时收到通知 |\r
+| 节点内容（需求/结论/笔记） | 需修改原始数据 | AI 总结不准确时可人工修正，但不会通知 AI |\r
+\r
+**原则**：优先让 AI 自行修复问题。手动操作是最后手段。\r
+\r
+**Q12：我手动改了代码，会影响工作区吗？**\r
+\r
+不会。工作区只记录任务结构和执行日志，不跟踪代码文件变化。你可以随时手动修改代码，工作区不会受到影响。但建议在 AI 执行任务期间避免同时修改相关代码，以免产生冲突。\r
+\r
+**Q13：WebUI 打不开怎么办？**\r
+\r
+1. **检查服务状态**：\`zero-workspace webui status\`\r
+2. **重启服务**：\`zero-workspace webui restart\`，然后刷新页面\r
+3. **端口被占用**：\`HTTP_PORT=19542 zero-workspace webui\`\r
+\r
+**Q14：工作区完成后怎么处理？暂停任务怎么办？**\r
+\r
+详见 [进阶功能 > 工作区管理](#工作区管理)。简单来说：完成后建议归档而非删除；暂停前让 AI 记录当前进度。\r
+\r
+### 发现问题的信号\r
+\r
+| 现象 | 可能原因 | 解决方法 |\r
+|------|----------|----------|\r
+| AI 直接执行不问确认 | 跳过了计划确认步骤 | 说"先展示计划让我确认" |\r
+| 没有告知 WebUI 地址 | AI 遗漏关键步骤 | 说"WebUI 地址是什么" |\r
+| 节点直接变成完成 | AI 跳步操作 | 说"请先 start 节点再执行" |\r
+| AI 长时间没响应 | 执行卡住或出错 | 说"怎么了？有什么问题吗" |\r
+| AI 说"我不确定" | 信息收集不充分 | 说"先收集信息再规划" |\r
+| 结论很模糊 | AI 没有总结 | 说"这个节点的结论是什么" |\r
+| 做了一半说完成了 | 验收标准不清晰 | 说"验收标准是什么？都满足了吗" |\r
+\r
+### 纠正 AI 的标准话术\r
+\r
+当你发现 AI 行为不对时，可以用这些话术纠正：\r
+\r
+| 问题 | 你可以说 |\r
+|------|----------|\r
+| 跳过确认 | "先展示计划让我确认" |\r
+| 没给链接 | "WebUI 地址是什么" |\r
+| 跳步操作 | "请先 start 节点再执行" |\r
+| 没记录 | "把这个记下来" |\r
+| 忘记结论 | "这个节点的结论是什么" |\r
+| 任务太大 | "这个太大了，拆分一下" |\r
+| 做错了 | "这个不对，重新做" |\r
+| 卡住了 | "有什么问题吗？需要我帮忙吗" |\r
+| 想放弃 | "这个先不做了" |\r
+\r
+---\r
+\r
+## 参考速查\r
+\r
+### 触发词速查\r
+\r
+| 意图 | 说法 |\r
+|------|------|\r
+| 创建工作区 | "用**工作台**帮我做xxx"、"创建一个**工作区**" |\r
+| 恢复任务 | "看看工作区状态"（推荐先查看再继续） |\r
+| 查看进度 | 进度、做到哪了、状态、现在什么情况 |\r
+| 确认计划 | 好、可以、继续、就这样、开始 |\r
+| 调整计划 | 不对、调整一下、先不做、跳过 |\r
+| 重新执行 | 重新做、再试一次、重来 |\r
+| 放弃任务 | 先不做了、取消、算了 |\r
+\r
+> **注意**：创建工作区必须明确提及"工作区"或"工作台"，否则 AI 会直接执行而不创建工作区。\r
+\r
+### 数据存储位置\r
+\r
+\`\`\`\r
+项目目录/\r
+└── .zero-workspace/\r
+    └── <工作区名称>_<id>/\r
+        ├── graph.json      # 节点树结构\r
+        ├── Info.md         # 工作区信息\r
+        └── nodes/\r
+            └── <节点名称>_<id>/\r
+                ├── Info.md  # 节点信息\r
+                └── Log.md   # 执行日志\r
+\`\`\`\r
+\r
+---\r
+\r
+## 已知局限\r
+\r
+以下是当前版本的已知局限。我们区分了"可改进"（未来可能通过优化解决）和"架构性"（由设计决定，短期不会改变）两类。\r
+\r
+### 可改进的局限\r
+\r
+**长对话下 AI 对工作台的唤起能力下降**\r
+\r
+当单个对话流程较长时，AI 可能逐渐"忘记"主动使用工作台工具，回到普通对话模式。这是 AI 上下文管理的固有挑战。\r
+\r
+- **表现**：AI 开始直接回答而不更新节点，或忘记记录结论\r
+- **应对**：提醒 AI"用工作台记录一下"或"更新节点状态"\r
+- **展望**：随着 AI 能力提升和提示优化，此问题有望改善\r
+\r
+**上下文恢复依赖记录完整性**\r
+\r
+暂停任务后恢复时，AI 能恢复多少上下文取决于之前记录的完整性。如果节点的 conclusion/notes 记录不充分，恢复后 AI 可能遗漏关键信息。\r
+\r
+- **表现**：恢复后 AI 对之前的决策细节不清楚\r
+- **应对**：暂停前让 AI 充分记录当前状态；恢复后先查看节点内容确认\r
+- **展望**：可通过更智能的自动记录机制改善\r
+\r
+**需求变更后节点结构可能不够理想**\r
+\r
+在项目进行中二次添加需求或修改需求时，新增的节点结构可能与原有规划不协调，或组织方式不够美观。这是由工作台的上下文机制和 AI 当时的上下文状态共同决定的。\r
+\r
+- **表现**：新增节点位置不合理，或与原有节点的层级关系混乱\r
+- **应对**：添加需求后，可让 AI "重新整理一下工作区结构"或具体描述期望的组织方式\r
+- **展望**：可通过增强引导机制优化，但由于 AI 决策的动态性，难以彻底解决\r
+\r
+### 架构性的局限\r
+\r
+**派发模式需要 AI 支持 subagent**\r
+\r
+派发模式依赖 AI 助手的 subagent（子代理）能力来执行子任务。并非所有 MCP 兼容的 AI 助手都完整支持此功能。\r
+\r
+- **Claude Code**：完全支持\r
+- **Cursor**：subagent 支持有限，派发模式可能无法正常工作\r
+- **其他 MCP 助手**：取决于具体实现\r
+\r
+这是 MCP 协议生态的现状，非工作台本身的限制。\r
+\r
+**历史工作区需手动管理**\r
+\r
+工作区不会自动删除或归档。随着使用时间增长，\`.zero-workspace/\` 目录下会积累历史工作区。\r
+\r
+- **设计原因**：自动清理可能误删有价值的历史记录\r
+- **应对**：定期归档已完成的工作区；不再需要的可手动删除\r
+\r
+---\r
+\r
+*本手册适用于 ZeroWorkspace v1.x*\r
+\r
+`,B={class:"docs-view"},H={class:"docs-header"},N={class:"header-right"},Q=["title"],Z={key:0,class:"icon-sun",viewBox:"0 0 24 24",fill:"none",stroke:"currentColor","stroke-width":"2"},L={key:1,class:"icon-moon",viewBox:"0 0 24 24",fill:"none",stroke:"currentColor","stroke-width":"2"},D={class:"docs-main"},q={class:"docs-sidebar"},G={class:"toc-nav"},J={class:"toc-list"},j=["onClick"],V=x({__name:"DocsView",setup($){const u=U();function g(){try{return JSON.parse(localStorage.getItem("zero-workspace-home-preferences")||"{}").theme||"light"}catch{return"light"}}const s=d(g());document.documentElement.setAttribute("data-theme",s.value);function k(){s.value=s.value==="light"?"dark":"light",document.documentElement.setAttribute("data-theme",s.value);const t=JSON.parse(localStorage.getItem("zero-workspace-home-preferences")||"{}");t.theme=s.value,localStorage.setItem("zero-workspace-home-preferences",JSON.stringify(t))}const a=v(()=>{const t=[],n=/^(#{2,3})\s+(.+)$/gm;let r;for(;(r=n.exec(h))!==null;){const c=r[1].length,i=r[2].trim(),p=i.toLowerCase().replace(/[^\w\u4e00-\u9fa5\s-]/g,"").replace(/\s+/g,"-").replace(/-+/g,"-").replace(/^-|-$/g,"");t.push({id:p,title:i,level:c})}return t}),A=d(""),o=d(null);function b(t){const n=document.getElementById(t);n&&(n.scrollIntoView({behavior:"smooth",block:"start"}),A.value=t)}function m(){if(!o.value)return;const t=100,n=o.value;let r="";for(const c of a.value){const i=document.getElementById(c.id);if(i){const p=i.getBoundingClientRect(),f=n.getBoundingClientRect();p.top-f.top<=t&&(r=c.id)}}r&&(A.value=r)}function w(){window.history.length>1?u.back():u.push("/")}return S(()=>{W(()=>{o.value&&(o.value.querySelectorAll("h2, h3").forEach(n=>{const c=(n.textContent||"").toLowerCase().replace(/[^\w\u4e00-\u9fa5\s-]/g,"").replace(/\s+/g,"-").replace(/-+/g,"-").replace(/^-|-$/g,"");n.id=c}),o.value.addEventListener("scroll",m),a.value.length>0&&a.value[0]&&(A.value=a.value[0].id))})}),E(()=>{o.value&&o.value.removeEventListener("scroll",m)}),(t,n)=>(I(),l("div",B,[e("header",H,[e("div",{class:"header-left"},[e("button",{class:"ws-btn text",onClick:w,title:"返回"},"<"),n[0]||(n[0]=e("h1",{class:"docs-title"},"用户手册",-1))]),e("div",N,[e("button",{class:"theme-toggle",onClick:k,title:s.value==="light"?"切换到深色模式":"切换到浅色模式"},[s.value==="light"?(I(),l("svg",Z,[...n[1]||(n[1]=[_('<circle cx="12" cy="12" r="5" data-v-dfcb658b></circle><line x1="12" y1="1" x2="12" y2="3" data-v-dfcb658b></line><line x1="12" y1="21" x2="12" y2="23" data-v-dfcb658b></line><line x1="4.22" y1="4.22" x2="5.64" y2="5.64" data-v-dfcb658b></line><line x1="18.36" y1="18.36" x2="19.78" y2="19.78" data-v-dfcb658b></line><line x1="1" y1="12" x2="3" y2="12" data-v-dfcb658b></line><line x1="21" y1="12" x2="23" y2="12" data-v-dfcb658b></line><line x1="4.22" y1="19.78" x2="5.64" y2="18.36" data-v-dfcb658b></line><line x1="18.36" y1="5.64" x2="19.78" y2="4.22" data-v-dfcb658b></line>',9)])])):(I(),l("svg",L,[...n[2]||(n[2]=[e("path",{d:"M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"},null,-1)])]))],8,Q)])]),e("div",D,[e("aside",q,[n[3]||(n[3]=e("div",{class:"sidebar-header"},[e("h3",null,"目录")],-1)),e("nav",G,[e("ul",J,[(I(!0),l(C,null,T(a.value,r=>(I(),l("li",{key:r.id,class:M(["toc-item",`level-${r.level}`,{active:A.value===r.id}]),onClick:c=>b(r.id)},O(r.title),11,j))),128))])])]),e("main",{ref_key:"contentRef",ref:o,class:"docs-content"},[y(R,{content:P(h)},null,8,["content"])],512)])]))}}),Y=z(V,[["__scopeId","data-v-dfcb658b"]]);export{Y as default};