zero-workspace 0.0.2

package/docs//347/224/250/346/210/267/346/211/213/345/206/214/344/270/216/346/212/200/346/234/257/346/214/207/345/215/227.md

@@ -0,0 +1,873 @@
+# ZeroWorkspace 用户手册与技术指南
+
+---
+
+## 能力概览
+
+### 核心能力一览
+
+**持久化工作区**
+- 任务信息跨会话保持，不因对话结束而丢失
+- 随时继续之前的任务，上下文完整恢复
+- 支持多工作区并行管理
+
+**结构化任务管理**
+- 将复杂任务分解为可追踪的节点树
+- 每个节点有明确的状态：待处理、进行中、已完成
+- 自动记录执行过程和结论
+
+**状态机约束**
+- 物理级防止 AI 跳步：必须按流程推进
+- 强制完成前置步骤才能进入下一阶段
+- 状态转换规则内置，无法绕过
+
+**派发系统**
+- 执行与审查分离：执行者专注实现，审查者验证质量
+- 双重保障：Spec Review（规范审查）+ Quality Review（质量审查）
+- 防止简化实现、遗漏需求
+
+**能力包系统**
+- 按需加载专业技能（调试、重构、测试设计等）
+- 标准化流程引导，确保执行质量
+- 可扩展，支持自定义能力包
+
+**MEMO 知识库**
+- 团队知识沉淀与共享
+- 支持结构化标签分类
+- 可导出为独立文档
+
+### 与现有方案对比
+
+| 特性 | Claude Code Plan 模式 | OpenSpec | ZeroWorkspace |
+|------|----------------------|----------|----------------|
+| 任务持久化 | 单次会话，关闭即丢失 | 静态文件，需手动维护 | 跨会话持久，自动保存 |
+| 上下文保持 | 对话压缩后丢失关键信息 | 需手动同步上下文 | 可AI自动唤起，并通过HOOK保持信息 |
+| 执行跟踪 | 无状态，靠对话记忆 | 无执行跟踪机制 | 完整状态机，实时追踪 |
+| 质量保障 | 依赖 AI 自觉性 | 规范约束，无强制力 | 状态机约束 + 派发审查 |
+| 复杂任务分解 | 手动分解，易遗漏 | 预定义结构，不够灵活 | 动态分解，按需调整 |
+| 知识沉淀 | 无，对话结束即消失 | 需要手动归档管理 | 工作区持久化 |
+| 复杂项目管理 | 无，只能单次规划 | 大型项目管理复杂，占用上下文 | 通过拓扑结构高效管理复杂项目计划 |
+| 多人协作 | 不支持 | 通过文件共享 | MEMO + 工作区导出 |
+
+### 相比 Claude Code 默认模式的优势
+
+**Plan 模式的局限**：
+- 规划只存在于当前对话，无法跨会话延续
+- 长对话压缩后，之前的规划细节会丢失
+- 没有执行状态追踪，AI 可能重复或遗漏步骤
+- 无法强制 AI 按规划执行，容易偏离
+
+**ZeroWorkspace 的解决方案**：
+- 工作区持久化存储，任务可跨天、跨周延续
+- 关键上下文自动注入，压缩不影响任务继续
+- 状态机物理约束，必须完成当前步骤才能继续
+- 派发系统强制审查，防止偷工减料
+
+### 相比 OpenSpec 的优势
+
+**OpenSpec 的局限**：
+- 需要预先编写完整规范，前期成本高
+- 静态文件，执行过程中难以调整
+- 没有执行跟踪，不知道进度和状态
+- 规范与执行分离，容易脱节
+
+**ZeroWorkspace 的解决方案**：
+- 动态规划，边执行边完善
+- 实时调整任务结构，灵活应对变化
+- 完整的执行状态追踪和日志记录
+- 规划与执行一体化，信息始终同步
+
+### 解决的核心痛点
+
+**1. 长对话上下文丢失**
+
+问题：Claude 对话过长时会自动压缩，导致之前讨论的需求、决策、代码位置等关键信息丢失。
+
+解决：工作区自动保护关键信息，压缩时注入必要上下文，确保 AI 始终了解任务全貌。
+
+**2. AI 跳步偷懒**
+
+问题：AI 有时会跳过分析步骤直接给出"简化实现"，或者遗漏需求中的细节。
+
+解决：状态机强制按流程执行，派发系统双重审查，物理级防止偷工减料。
+
+**3. 复杂任务失控**
+
+问题：多步骤任务容易混乱，不知道做到哪里了，哪些完成了哪些没完成。
+
+解决：结构化节点树 + 状态追踪，清晰展示任务全貌和当前进度。
+
+**4. 知识无法沉淀**
+
+问题：每次对话结束，讨论的技术方案、踩过的坑、做出的决策都消失了。
+
+解决：MEMO 系统持久化存储，支持标签分类和搜索，团队知识可累积复用。
+
+**5. 跨会话任务中断**
+
+问题：关闭对话后再次打开，需要重新描述任务背景，AI 不记得之前的进展。
+
+解决：工作区完整保存任务状态，一句"继续之前的任务"即可恢复上下文。
+
+### 优势场景
+
+**复杂功能开发**
+
+适用于涉及多个模块、多个文件的新功能实现。工作区帮助分解任务、追踪进度、确保每个模块都被正确实现。
+
+示例：实现用户认证系统（注册、登录、权限、Token 管理）
+
+**大规模重构**
+
+适用于需要严格控制范围和质量的代码重构。状态机约束确保重构按计划进行，派发审查保证重构质量。
+
+示例：将单体应用拆分为微服务架构
+
+**Bug 深度排查**
+
+适用于需要多轮调试、持续追踪的复杂问题。工作区记录每次尝试和结论，避免重复排查。
+
+示例：排查偶发的内存泄漏问题
+
+**技术调研**
+
+适用于需要沉淀结论、后续复用的研究任务。MEMO 记录调研结果，方便团队参考。
+
+示例：评估多个技术方案的优劣
+
+**团队协作**
+
+适用于多人接力开发的场景。通过工作区导出和 MEMO 共享，团队成员可以快速了解上下文。
+
+示例：前端开发完成后交接给后端联调
+
+---
+
+## 第一部分：用户手册
+
+### 1. 简介
+
+ZeroWorkspace 就像是 AI 的项目管理系统。
+
+想象你在和一个能干但健忘的同事合作——他很聪明，但对话一长就忘了早期的决策；任务一复杂就容易跑偏。ZeroWorkspace 就是给这个"同事"配的任务管理工具：把大任务拆成小步骤，每步都记录下来，随时能回顾进度。
+
+**核心概念**
+
+| 概念 | 说明 |
+|------|------|
+| 工作台 | ZeroWorkspace 本身，管理所有工作区的平台 |
+| 工作区 | 单个任务的完整记录，包含一棵任务树 |
+| 节点 | 任务树中的每个任务单元 |
+
+工作台是你的办公桌，工作区是桌上的每个项目文件夹，节点是文件夹里的待办事项。
+
+**谁会受益？**
+
+- 你：知道 AI 在做什么、做到哪了，能随时调整方向
+- AI：有结构化的任务管理，不再迷失在长对话中
+- 项目：所有变更有迹可循，出问题能回溯
+
+### 2. 快速开始
+
+**安装**
+
+```bash
+npm install -g zero-workspace
+zero-workspace setup  # 自动检测环境并配置
+```
+
+**启动 WebUI 服务（推荐）**
+
+```bash
+zero-workspace webui  # 启动后保持终端窗口打开
+```
+
+启动后访问终端显示的地址（默认 `http://localhost:19540`）即可查看任务进度。
+
+其他管理命令：
+```bash
+zero-workspace webui status  # 查看服务状态
+zero-workspace webui stop    # 停止服务
+zero-workspace webui restart # 重启服务
+```
+
+**支持的 AI 助手**
+
+| AI 助手 | 支持程度 | 说明 |
+|---------|---------|------|
+| Claude Code | 完全支持 | 所有功能可用，推荐使用 |
+| Cursor | 基础支持 | 派发模式降级为主进程执行 |
+| 其他 MCP 兼容助手 | 基础功能 | 支持 MCP 即可使用核心功能 |
+
+**第一次使用**
+
+在对话中明确提及"工作区"或"工作台"即可触发：
+
+```
+你：用工作台帮我实现一个用户登录功能
+```
+
+或者：
+
+```
+你：创建一个工作区，帮我做用户登录功能
+```
+
+AI 会自动创建工作区并开始工作。
+
+**对话示例**
+
+```
+你：用工作台帮我实现一个用户登录功能
+
+AI：好的，我来创建工作区管理这个任务。
+
+    工作区已创建：用户登录功能
+    WebUI 地址：http://localhost:19540/workspace/ws-xxx
+
+    让我先了解一下你的项目情况...
+    [AI 开始探索代码库]
+
+    我看到你的项目是一个 Express + React 应用。
+    我制定了以下计划：
+    1. 设计登录 API 接口
+    2. 实现后端认证逻辑
+    3. 创建前端登录表单
+    4. 添加登录状态管理
+
+    确认开始执行吗？
+
+你：好
+
+AI：开始执行第一个任务...
+    [逐步完成每个任务]
+
+    所有任务已完成！
+    新增文件：src/routes/auth.js, src/components/Login.tsx
+    修改文件：src/App.tsx, src/store/index.ts
+```
+
+关键点：
+- 不需要学新命令——用自然语言说任务就行
+- AI 会主动创建工作区——不需要手动操作
+- 计划需要你确认——AI 不会擅自开始执行
+- 过程可视化——随时打开 WebUI 看进度
+
+### 3. 核心概念
+
+**节点类型**
+
+| 类型 | 用途 | 说明 |
+|------|------|------|
+| planning（规划） | 拆分和组织子任务 | 像文件夹，可包含多个子节点 |
+| execution（执行） | 实际执行工作 | 像文件，写代码、调研、测试 |
+
+**节点状态**
+
+执行节点：pending（等待） -> implementing（执行中） -> completed（完成） / failed（失败）
+
+规划节点：pending -> planning（规划中） -> monitoring（等待子任务） -> completed
+
+**MEMO 草稿区**
+
+独立于节点树的存储区，用于存放长内容（设计文档、调研结果等）。适合跨节点复用的内容，可被多个节点引用，支持导出为独立文档。
+
+**派发模式**
+
+| 模式 | 特点 | 适用场景 |
+|------|------|----------|
+| 普通模式 | AI 直接执行 | 简单任务、强依赖上下文的任务 |
+| 派发模式 | 子任务派发给独立 Agent，完成后审查 | 复杂任务、可独立执行的子任务 |
+
+派发模式下，每个子任务会经过执行和审查两个阶段，确保质量。
+
+**能力包**
+
+根据任务场景自动推荐的功能模块：
+
+| 能力 | 用途 |
+|------|------|
+| intent_alignment | 意图对齐——澄清需求，确认验收标准 |
+| context_discovery | 上下文探索——扫描项目，理解架构 |
+| solution_design | 方案设计——设计接口和实现路径 |
+| verification_strategy | 验证策划——设计测试用例 |
+| diagnosis | 问题诊断——定位 bug 根因 |
+| tech_research | 技术调研——评估技术选型 |
+
+### 4. 使用流程
+
+一个任务从开始到结束会经过 5 个阶段：
+
+**阶段一：启动任务**
+
+在对话中明确提及"工作区"或"工作台"：
+
+```
+你：用工作台帮我实现搜索功能
+AI：好的，我来创建工作区管理这个任务。
+    工作区：搜索功能开发
+    WebUI：http://localhost:19540/workspace/ws-xxx
+    这个任务属于哪种场景？新功能/Bug修复/性能优化/总结分析？
+```
+
+**阶段二：信息收集/整理**
+
+根据你提供信息的完整度，AI 会选择：
+- 信息收集：你只说了"帮我做XXX"，AI 主动扫描项目、读文档
+- 信息总结：你已详细描述需求，AI 整理确认
+
+**阶段三：确认计划**
+
+这是最重要的检查点——AI 会在这里暂停，等你确认：
+
+```
+AI：我制定了以下计划：
+    1. 设计搜索接口
+    2. 实现后端搜索逻辑
+    3. 创建前端搜索组件
+    4. 添加搜索防抖
+    确认开始执行吗？
+
+你：好 / 第3个先不做 / 加一个分页功能
+```
+
+**阶段四：执行任务**
+
+AI 按顺序执行计划，每个任务都会：
+1. 开始前：标记任务为"进行中"
+2. 执行时：写代码、记录日志
+3. 完成后：写结论、标记为"已完成"
+
+可随时问"做到哪了？"查看进度。
+
+**阶段五：完成交付**
+
+所有任务完成后，AI 汇报：新增/修改的文件、测试方式、完成情况总结。
+
+### 5. 场景指南
+
+**场景 1：新功能开发**
+
+适用于实现新的功能模块。
+
+```
+你：用工作台帮我实现用户登录功能
+
+触发词：实现、开发、新增、添加
+AI 行为：
+1. 扫描项目结构，理解现有架构
+2. 与你澄清需求细节
+3. 制定实现计划并确认
+4. 逐步实现，每步记录结论
+```
+
+**场景 2：Bug 调试修复**
+
+适用于定位和修复问题。
+
+```
+你：用工作台帮我排查这个 bug：用户登录后偶尔会跳转失败
+
+触发词：修复、排查、调试、解决
+AI 行为：
+1. 复现问题，收集信息
+2. 分析可能原因
+3. 逐个验证假设
+4. 找到根因后修复
+```
+
+**场景 3：代码优化重构**
+
+适用于改进现有代码。
+
+```
+你：用工作台帮我重构用户模块，现在太乱了
+
+触发词：重构、优化、整理、清理
+AI 行为：
+1. 分析当前代码问题
+2. 设计改进方案
+3. 分步重构，确保每步可回滚
+4. 验证重构后功能正常
+```
+
+**场景 4：技术调研/文档总结**
+
+适用于研究和记录。
+
+```
+你：用工作台帮我调研 React 状态管理方案
+
+触发词：调研、分析、总结、对比
+AI 行为：
+1. 收集各方案信息
+2. 多维度对比分析
+3. 给出推荐建议
+4. 将结论记录到 MEMO
+```
+
+### 6. 进阶功能
+
+**继续之前的任务**
+
+关掉对话后，下次开启新对话时：
+
+```
+你：看看工作区的状态
+
+AI：博客评论功能 (ws-abc123)
+    整体进度：2/3 任务已完成
+    任务 1：创建评论数据模型（已完成）
+    任务 2：实现评论 API（已完成）
+    任务 3：创建评论组件（进行中）
+
+你：继续任务 3
+
+AI：好的，让我先回顾一下任务 3 的进展...
+```
+
+推荐流程：先查看状态 -> 确认聚焦点 -> 决定下一步。
+
+**追加需求 / 重开任务**
+
+```
+你：（任务已完成）还想加一个评论点赞功能
+AI：好的，在当前工作区新增任务...
+
+你：这个做错了，重新做一遍
+AI：好的，我把这个任务重新打开...
+```
+
+**多工作区管理**
+
+```
+你：我现在有几个工作区？
+AI：你有 3 个工作区：
+    1. 博客评论功能 - 进行中
+    2. 首页性能优化 - 已完成
+    3. 用户登录修复 - 已完成
+
+你：切换到评论功能
+AI：已切换，当前进度...
+```
+
+**工作区归档**
+
+完成的工作区建议归档而非删除，可供后期复盘：
+
+```
+你：把这个工作区归档
+AI：已归档工作区：博客评论功能
+```
+
+**导入导出**
+
+| 操作 | 入口 | 说明 |
+|------|------|------|
+| 导出 | 工作区详情页 -> EXPORT 按钮 | 导出为 .twsp 文件 |
+| 导入 | 设置 -> 索引管理 -> 管理 | 拖拽 .twsp 文件或目录 |
+
+**WebUI 功能**
+
+访问 `http://localhost:19540` 可以：
+- 任务树视图：树状展示所有节点，颜色区分状态
+- 节点详情：点击节点查看需求、结论、日志
+- 进度统计：各状态节点数量，完成百分比
+- MEMO 查看：查看 AI 记录的备忘信息
+- 实时更新：自动刷新，无需手动刷新
+
+### 7. 问题诊断
+
+**常见问题**
+
+| 问题 | 解答 |
+|------|------|
+| 必须用工作区吗？ | 不是。简单任务可以不用，复杂任务建议用 |
+| 不提"工作区"会怎样？ | AI 直接执行，不创建工作区 |
+| 为什么要确认计划？ | 防止 AI 跑偏，看一眼只需 10 秒 |
+| 任务太大怎么办？ | 说"帮我拆分"，AI 会分解任务 |
+| AI 做错了怎么办？ | 说"重新做"或"回滚" |
+| 关掉对话后工作区还在吗？ | 在，存储在项目 .zero-workspace/ 目录 |
+| WebUI 打不开？ | 运行 `zero-workspace webui restart` |
+
+**发现问题的信号**
+
+| 现象 | 解决方法 |
+|------|----------|
+| AI 直接执行不问确认 | "先展示计划让我确认" |
+| 节点直接变成完成 | "请先 start 节点再执行" |
+| AI 长时间没响应 | "怎么了？有什么问题吗" |
+| 结论很模糊 | "这个节点的结论是什么" |
+| 做了一半说完成 | "验收标准是什么？都满足了吗" |
+
+**纠正 AI 的话术**
+
+| 问题 | 你可以说 |
+|------|----------|
+| 跳过确认 | "先展示计划让我确认" |
+| 没记录 | "把这个记下来" |
+| 任务太大 | "这个太大了，拆分一下" |
+| 做错了 | "这个不对，重新做" |
+| 卡住了 | "有什么问题吗？需要我帮忙吗" |
+
+**触发词速查**
+
+| 意图 | 说法 |
+|------|------|
+| 创建工作区 | "用工作台帮我做xxx"、"创建一个工作区" |
+| 恢复任务 | "看看工作区状态" |
+| 查看进度 | "进度"、"做到哪了"、"状态" |
+| 确认计划 | "好"、"可以"、"继续" |
+| 调整计划 | "不对"、"调整一下"、"先不做" |
+| 重新执行 | "重新做"、"再试一次" |
+
+---
+
+## 第二部分：技术指南
+
+### 8. 系统架构
+
+**整体架构**
+
+ZeroWorkspace 采用统一入口设计，同时提供 MCP 和 HTTP 两种访问方式：
+
+```
+┌─────────────────────────────────────────────────┐
+│              统一入口 (index.ts)                 │
+├─────────────────────────────────────────────────┤
+│  ┌─────────────┐       ┌─────────────────────┐  │
+│  │  MCP Server │       │    HTTP Server      │  │
+│  │   (stdio)   │       │  ┌───────────────┐  │  │
+│  └──────┬──────┘       │  │  API (/api/*) │  │  │
+│         │              │  ├───────────────┤  │  │
+│         │              │  │  Web UI (静态) │  │  │
+│         │              │  └───────────────┘  │  │
+│         │              └──────────┬──────────┘  │
+│         │                         │             │
+│         └────────┬────────────────┘             │
+│                  ↓                              │
+│         共享服务层 (services.ts)                 │
+│         - WorkspaceService                      │
+│         - NodeService                           │
+│         - DispatchService                       │
+│         - MemoService                           │
+└─────────────────────────────────────────────────┘
+```
+
+**分层设计**
+
+| 层级 | 职责 | 主要模块 |
+|------|------|----------|
+| 接口层 | 对外暴露 MCP 工具和 HTTP API | mcp/, http/ |
+| 服务层 | 业务逻辑实现 | services/ |
+| 存储层 | 数据持久化 | storage/, FileSystemAdapter |
+| 类型层 | 类型定义和状态机 | types/ |
+
+**环境配置**
+
+| 环境变量 | 默认值 | 说明 |
+|----------|--------|------|
+| HTTP_PORT | 19540 | HTTP API 端口 |
+| ZERO_DEV | false | 开发模式（使用独立数据目录） |
+| DISABLE_HTTP | false | 禁用 HTTP server |
+
+**数据目录**
+
+| 环境 | 全局索引 | 项目数据 |
+|------|---------|---------|
+| 正式环境 | ~/.zero-workspace/ | {project}/.zero-workspace/ |
+| 开发环境 | ~/.zero-workspace-dev/ | {project}/.zero-workspace-dev/ |
+
+### 9. 数据模型
+
+**存储结构**
+
+```
+.zero-workspace/
+├── sessions.json              # 会话绑定信息
+└── ws-{id}/                   # 工作区目录
+    ├── Workspace.md           # 工作区元数据
+    ├── memos/                 # MEMO 存储
+    └── nodes/
+        ├── root/
+        │   └── Node.md        # 根节点数据
+        └── node-{id}/
+            └── Node.md        # 子节点数据
+```
+
+**工作区数据结构**
+
+```typescript
+interface Workspace {
+  id: string;                  // 工作区 ID
+  name: string;                // 工作区名称
+  goal: string;                // 目标描述
+  status: "active" | "archived";
+  rules: string[];             // 规则列表
+  rulesHash: string;           // 规则哈希（8位）
+  docs: DocReference[];        // 文档引用列表
+  focusedNodeId: string | null;// 当前聚焦节点
+  createdAt: number;
+  updatedAt: number;
+}
+```
+
+**节点数据结构**
+
+```typescript
+interface Node {
+  id: string;                  // 节点 ID
+  title: string;               // 节点标题
+  type: "planning" | "execution";
+  status: NodeStatus;          // 节点状态
+  role: NodeRole | null;       // 节点角色
+  requirement: string;         // 需求描述
+  conclusion: string | null;   // 结论
+  note: string;                // 备注
+  parentId: string | null;     // 父节点 ID
+  isolated: boolean;           // 是否隔离上下文
+  docs: DocReference[];        // 文档引用
+  references: Reference[];     // 跨节点引用
+}
+
+type NodeRole = "info_collection" | "info_summary" |
+                "dispatch_exec" | "dispatch_spec" | "dispatch_quality";
+```
+
+**状态机规则**
+
+执行节点状态流转：
+```
+pending -> implementing -> completed
+                       -> failed -> pending (reopen)
+```
+
+规划节点状态流转：
+```
+pending -> planning -> monitoring -> completed
+                                  -> cancelled
+```
+
+### 10. API 参考
+
+**工作区管理**
+
+```typescript
+workspace_init(name, goal, scenario, rules?, docs?)  // 创建工作区
+workspace_get(workspaceId)                           // 获取详情
+workspace_list(status?, cwd?)                        // 列出工作区
+workspace_delete(workspaceId, force?)                // 删除工作区
+workspace_archive(workspaceId)                       // 归档工作区
+workspace_restore(workspaceId)                       // 恢复归档
+```
+
+**节点管理**
+
+```typescript
+node_create(workspaceId, parentId, type, title, requirement, ...)
+node_get(workspaceId, nodeId)
+node_list(workspaceId, rootId?, depth?)
+node_update(workspaceId, nodeId, title?, requirement?, note?, conclusion?)
+node_delete(workspaceId, nodeId)
+node_transition(workspaceId, nodeId, action, conclusion?)
+```
+
+**上下文管理**
+
+```typescript
+context_get(workspaceId, nodeId, includeLog?, includeProblem?)
+context_focus(workspaceId, nodeId)
+node_isolate(workspaceId, nodeId, isolate)
+node_reference(workspaceId, nodeId, targetIdOrPath, action, description?)
+```
+
+**派发系统**
+
+```typescript
+dispatch_node(workspaceId, nodeId)         // 升级为派发母节点
+dispatch_create(workspaceId, parentId, exec, includeQuality?)
+dispatch_complete(workspaceId, nodeId, success, conclusion?)
+dispatch_enable(workspaceId, useGit?)      // 启用派发模式
+dispatch_disable(workspaceId)              // 禁用派发
+```
+
+**备忘系统**
+
+```typescript
+memo_create(workspaceId, title, summary, content, tags)
+memo_list(workspaceId, tags?)
+memo_get(workspaceId, memoId)
+memo_update(workspaceId, memoId, ...)
+memo_delete(workspaceId, memoId)
+```
+
+**会话管理**
+
+```typescript
+session_bind(sessionId, workspaceId, nodeId?)
+session_unbind(sessionId)
+session_status(sessionId)
+```
+
+### 11. 扩展开发
+
+**Hook 系统**
+
+Hook 允许在 AI 工作流程的关键节点插入自定义逻辑：
+
+| 事件 | 触发时机 | 用途 |
+|------|---------|------|
+| SessionStart | 会话启动/恢复 | 环境初始化、上下文注入 |
+| UserPromptSubmit | 用户提交消息前 | 验证、上下文注入 |
+| PreToolUse | 工具执行前 | 权限控制、参数修改 |
+| PostToolUse | 工具执行后 | 日志记录 |
+| PreCompact | Compact 操作前 | 预处理 |
+
+配置位置（优先级从高到低）：
+1. `.claude/settings.local.json` - 项目本地
+2. `.claude/settings.json` - 项目级
+3. `~/.claude/settings.json` - 用户级
+
+配置示例：
+```json
+{
+  "hooks": {
+    "SessionStart": [{
+      "matcher": "startup|clear|compact",
+      "hooks": [{
+        "type": "command",
+        "command": "node /path/to/hook.js SessionStart"
+      }]
+    }]
+  }
+}
+```
+
+**Skill 系统**
+
+Skill 是指导 AI 执行特定任务的 SOP 文档，系统根据流程自动触发：
+
+| 类型 | Skill | 触发场景 |
+|------|-------|----------|
+| 流程引导 | bootstrapping-workspace | 工作区创建后 |
+| 流程引导 | dispatching-parent | 派发升级后 |
+| 能力执行 | aligning-intent | 选择意图对齐能力时 |
+| 能力执行 | discovering-context | 选择上下文探索能力时 |
+| 能力执行 | designing-solutions | 选择方案设计能力时 |
+| 派发角色 | executing-task | dispatch_exec 角色 |
+| 派发角色 | reviewing-spec | dispatch_spec 角色 |
+
+更多 Skill 定义位于 `plugin/skills/{skill-name}/SKILL.md`。
+
+**Subagent 系统**
+
+Subagent 用于派发模式下的独立任务执行：
+
+```
+plugin/subagents/
+├── zero-executor/    # 执行者
+├── zero-tester/      # 测试者
+└── zero-reviewer/    # 审查者
+```
+
+每个 Subagent 有独立的 prompt 和工具权限定义。
+
+### 12. 安全与数据保护
+
+**版本兼容性检测**
+
+ZeroWorkspace 使用双重版本检测机制：
+
+| 版本类型 | 用途 |
+|----------|------|
+| 存储版本 (Storage Version) | 数据结构迁移 |
+| 代码版本 (Code Version) | 兼容性检查 |
+
+版本检测规则：
+- 数据版本 > 代码版本：设为只读模式，禁止写入
+- 数据版本 < 代码版本：允许操作，自动迁移
+- 仅 patch 版本差异：允许操作
+
+**数据完整性检测**
+
+- 启动时自动检测所有工作区
+- 检测孤立节点、循环引用等问题
+- 提供 `workspace_health` API 进行详细诊断
+
+**备份机制**
+
+- 支持导出为 .twsp 文件
+- 工作区归档保留完整历史
+- 节点日志永久保存
+
+### 13. 开发贡献
+
+**开发环境**
+
+```bash
+# 一键启动（推荐）
+npm run dev:all
+
+# 分别启动
+npm run start:http:dev   # 后端 HTTP API (端口 19541)
+cd web && npm run dev    # 前端 Vite (端口 5173)
+
+# 构建
+npm run build:all        # 后端 + 前端
+
+# 测试
+npm test
+```
+
+**项目结构**
+
+```
+src/
+├── index.ts           # MCP Server 入口
+├── types/             # 类型定义
+├── storage/           # 存储层
+├── services/          # 业务逻辑层
+├── tools/             # MCP Tools 定义
+├── prompts/           # AI 指南与话术
+├── http/              # HTTP 服务器
+└── utils/             # 工具函数
+
+web/
+├── src/
+│   ├── views/         # 页面组件
+│   ├── components/    # 通用组件
+│   ├── stores/        # Pinia 状态管理
+│   └── api/           # API 客户端
+```
+
+**数据分层**
+
+| 数据类型 | 权威来源 | 可直接编辑 |
+|---------|---------|:----------:|
+| 内容数据（requirement, conclusion） | Info.md | 可以 |
+| 结构数据（status, children） | graph.json | 不可以 |
+
+---
+
+## 附录
+
+**数据存储位置**
+
+```
+项目目录/
+└── .zero-workspace/
+    └── <工作区名称>_<id>/
+        ├── graph.json      # 节点树结构
+        ├── Workspace.md    # 工作区信息
+        └── nodes/
+            └── <节点名称>_<id>/
+                ├── Info.md  # 节点信息
+                └── Log.md   # 执行日志
+```
+
+**已知局限**
+
+- 长对话下 AI 对工作台的唤起能力可能下降
+- 派发模式需要 AI 助手支持 subagent 特性
+- WebUI 仅支持本机访问
+