zero-workspace 0.0.2

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "zero-workspace",
+  "version": "0.0.2",
+  "description": "ZeroWorkspace MCP Server - 面向 AI 编程助手的分形任务跟踪系统",
+  "type": "module",
+  "main": "dist/cli/check-node-version.js",
+  "bin": {
+    "zero-workspace": "dist/cli/check-node-version.js",
+    "tw": "dist/cli/check-node-version.js",
+    "zeroworkspace": "dist/cli/check-node-version.js",
+    "tsworkspace": "dist/cli/check-node-version.js"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "dist/",
+    "web/dist/",
+    "plugin/",
+    "config/",
+    "docs/",
+    "README.md",
+    "CHANGELOG.md",
+    "配置方式.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zeroka/ZeroWorkspace.git"
+  },
+  "homepage": "https://github.com/zeroka/ZeroWorkspace#readme",
+  "bugs": {
+    "url": "https://github.com/zeroka/ZeroWorkspace/issues"
+  },
+  "author": "Zero <zeroka0106@gmail.com>",
+  "scripts": {
+    "build": "tsc",
+    "build:all": "tsc && cd web && npm run build",
+    "dev": "tsc --watch",
+    "dev:all": "concurrently -n api,web -c blue,green \"npm run start:http:dev\" \"cd web && npm run dev\"",
+    "start": "node dist/cli/check-node-version.js",
+    "start:mcp": "DISABLE_HTTP=true node dist/cli/check-node-version.js",
+    "start:mcp:dev": "ZERO_DEV=true DISABLE_HTTP=true node dist/cli/check-node-version.js",
+    "start:http": "node dist/http/index.js",
+    "start:http:dev": "ZERO_DEV=true node dist/http/index.js",
+    "dev:kill": "PID=$(lsof -ti :19541); if [ -n \"$PID\" ]; then kill -9 $PID && echo \"已杀掉进程: $PID\"; else echo '无运行中的开发服务'; fi",
+    "dev:restart": "npm run dev:kill && sleep 1 && npm run start:http:dev &",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "sync-versions": "npx tsx scripts/sync-versions.ts",
+    "check-versions": "npx tsx scripts/sync-versions.ts --check"
+  },
+  "keywords": [
+    "mcp",
+    "workspace",
+    "task-management",
+    "ai",
+    "claude",
+    "model-context-protocol"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@fastify/cors": "^11.1.0",
+    "@fastify/multipart": "^9.3.0",
+    "@fastify/static": "^8.3.0",
+    "@inquirer/prompts": "^8.1.0",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@types/adm-zip": "^0.5.7",
+    "@types/archiver": "^7.0.0",
+    "@types/semver": "^7.7.1",
+    "@types/unzipper": "^0.10.11",
+    "adm-zip": "^0.5.16",
+    "archiver": "^7.0.1",
+    "fastify": "^5.6.2",
+    "file-folder-dialogs": "^0.0.1",
+    "semver": "^7.7.3",
+    "unzipper": "^0.12.3",
+    "update-notifier": "^7.3.1",
+    "yaml": "^2.8.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/update-notifier": "^6.0.8",
+    "concurrently": "^9.2.1",
+    "pino-pretty": "^13.1.3",
+    "tsx": "^4.21.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  },
+  "directories": {
+    "doc": "docs",
+    "test": "tests"
+  },
+  "types": "./dist/cli/check-node-version.d.ts"
+}

package/plugin/README.md

@@ -0,0 +1,141 @@
+# ZeroWorkspace Plugin 系统
+
+本目录包含 ZeroWorkspace 的插件资源，供 AI 代理在执行任务时使用。
+
+## 目录结构
+
+```
+plugin/
+├── agents/          # 代理定义
+├── hooks/           # 钩子配置（已废弃）
+├── scripts/         # 钩子脚本
+└── skills/          # 技能定义
+```
+
+## Skills（技能）
+
+Skills 是指导 AI 执行特定任务的 SOP（标准操作流程）文档。系统根据流程自动触发相应的 Skill，**用户无需手动调用**。
+
+### 分类概览
+
+| 大类 | 触发方式 | 数量 |
+|------|----------|------|
+| 流程引导 | actionRequired 强制触发 | 3 |
+| 能力执行 | capability_select 创建能力节点 | 7 |
+| 派发角色 | 派发系统分配角色 | 4 |
+| 功能指南 | AI 主动调用 | 1 |
+
+### 流程引导类（3 个）
+
+在特定流程节点强制触发，引导 AI 完成流程。
+
+| Skill | 触发场景 | 作用 |
+|-------|----------|------|
+| `bootstrapping-workspace` | workspace_init 后 | 引导工作区启动流程 |
+| `dispatching-parent` | dispatch_node 后 | 协调派发执行流程 |
+| `starting-info-flow` | 现有工作区中用户请求新任务 | 引导能力选择、创建信息节点 |
+
+### 能力执行类（7 个）
+
+与 `scenarioCapabilities.json` 中的 CapabilityId 一一对应，在创建能力节点时触发。
+
+| CapabilityId | Skill | 说明 |
+|--------------|-------|------|
+| intent_alignment | `aligning-intent` | 意图对齐：澄清需求、确认验收标准 |
+| context_discovery | `discovering-context` | 上下文发现：探索代码库、理解现有状态 |
+| tech_research | `researching-tech` | 技术调研：评估技术选型、多维度比较 |
+| diagnosis | `diagnosing-issues` | 问题诊断：追踪根因、分析错误和性能瓶颈 |
+| measurement_analysis | `analyzing-measurements` | 度量分析：建立基准、对比数据、验证优化 |
+| solution_design | `designing-solutions` | 方案设计：定义接口、数据结构、实现路径 |
+| verification_strategy | `planning-verification` | 验证规划：设计测试用例、定义验收步骤 |
+
+**场景分布**（basePack = 必选，optionalPack = 可选）：
+
+| 场景 | basePack | optionalPack |
+|------|----------|--------------|
+| feature | intent_alignment, context_discovery | tech_research, solution_design, verification_strategy |
+| summary | intent_alignment, context_discovery | - |
+| optimize | intent_alignment, context_discovery, measurement_analysis | diagnosis, solution_design, verification_strategy |
+| debug | intent_alignment, context_discovery, diagnosis | solution_design, verification_strategy |
+| misc | intent_alignment | 全部可选 |
+
+### 派发角色类（4 个）
+
+在派发执行流程中，根据节点角色触发。
+
+| Skill | 角色 | 作用 |
+|-------|------|------|
+| `preparing-dispatch` | 准备者 | 准备派发节点，拆分任务 |
+| `executing-task` | dispatch_exec | 执行具体任务 |
+| `reviewing-spec` | dispatch_spec | 规格审查，验证是否满足需求 |
+| `reviewing-quality` | dispatch_quality | 质量审查，检查代码质量 |
+
+### 功能指南类（1 个）
+
+AI 在执行特定功能时主动调用，获取最佳实践指导。
+
+| Skill | 触发场景 | 作用 |
+|-------|----------|------|
+| `memo-create` | 创建 MEMO 时 | 指导 title/summary/content/tags 的格式规范 |
+
+## Agents（代理）
+
+定义 Claude Code 的子代理行为规范。
+
+| Agent | 用途 |
+|-------|------|
+| `zero-executor` | 任务执行代理，严格遵循 scope 执行任务 |
+| `zero-reviewer` | 审查代理，执行规格审查和质量审查 |
+
+## Scripts（脚本）
+
+| 脚本 | 用途 |
+|------|------|
+| `hook-entry.cjs` | Claude Code 钩子入口脚本 |
+| `cursor-hook-entry.cjs` | Cursor 钩子入口脚本 |
+| `openspec-import.cjs` | OpenSpec 导入脚本 |
+| `shared/` | 共享工具模块 |
+
+## Skill 文件规范
+
+每个 Skill 是一个 Markdown 文件，结构如下：
+
+```markdown
+---
+name: skill-name
+description: Use when [触发条件]. [能力说明]
+---
+
+# Skill Name
+
+## Announcement (MANDATORY)
+[执行前必须向用户宣布]
+
+## Core Thinking
+[核心思维模式]
+
+## SOP
+[标准操作流程]
+
+## Checklist
+[检查清单]
+
+## Mandatory Rules
+[强制规则]
+```
+
+### 命名规范
+
+- 目录名：使用动名词形式 + 连字符（如 `aligning-intent`）
+- 文件：`SKILL.md`
+
+### 关键约束
+
+1. **Recording**：对话输出对用户不可见，必须记录到工作区节点
+2. **Progressive Recording**：长任务必须中途记录，防止上下文丢失
+3. **Present before proceed**：完成后必须向用户展示结果，等待确认
+
+## 相关配置
+
+- `config/scenarioCapabilities.json` - 场景能力包配置
+- `src/services/CapabilityService.ts` - CapabilityId 到 Skill 目录的映射

package/plugin/agents/zero-executor.md

@@ -0,0 +1,114 @@
+---
+name: zero-executor
+description: zeroWorkspace node executor specializing in atomic task execution with strict scope control
+tools: Read, Write, Edit, Bash, Glob, Grep, Skill, zero-workspace/*
+model: opus
+---
+
+You are a senior task executor. Execute ONLY what's specified, NEVER expand scope.
+
+**语言要求**: 所有日志（log_append）和结论（conclusion）MUST 使用中文输出。
+
+## ⚠️ STEP ZERO: Invoke Skill (MANDATORY)
+
+**CRITICAL: You MUST invoke Skill BEFORE any other action. No exceptions.**
+
+```
+Skill(skill: "executing-task")
+```
+
+**Why this is non-negotiable:**
+- Skill contains the complete SOP you need to follow
+- Skipping Skill = missing critical workflow steps = task failure
+- This is NOT optional, NOT "nice to have" - it's REQUIRED
+
+**If Skill tool unavailable**, use fallback (MUST do one or the other):
+```
+plugin_path(type: "skill", name: "executing-task") → Read the returned path
+```
+
+**NEVER proceed to context_get without first invoking Skill or reading SKILL.md.**
+
+## The Iron Law
+
+**MUST follow this exact sequence. No exceptions.**
+
+```
+1. context_get    → 验证节点信息完整性（MUST 先验证）
+2. context_focus  → 切换聚焦点（MUST 在 start 前）
+3. node_transition(action="start") → 开始执行
+4. log_append     → 每个关键步骤后记录（MUST，不是可选）
+5. 成功 → dispatch_complete(success=true)
+   失败 → problem_update → dispatch_complete(success=false)
+```
+
+## Red Flags
+
+**如果你在想这些，立即停止：**
+
+- "Skill 调用可以跳过，我知道该怎么做" → NEVER，Skill 包含你不知道的关键步骤
+- "我先跳过 context_get 直接开始" → NEVER
+- "这步太小不用 log_append" → ALWAYS log
+- "出错了但我先继续试试" → MUST problem_update first
+- "我直接 complete 不用 start" → 系统会拒绝
+
+## Anti-Patterns (NEVER DO)
+
+| Wrong | Right |
+|-------|-------|
+| 跳过 context_get 直接执行 | ALWAYS validate first |
+| 跳过 context_focus | ALWAYS focus before start |
+| 跳过 start 直接工作 | dispatch_complete 会失败 |
+| 修改后不记录日志 | 每个文件修改后 log_append |
+| 出错继续执行 | problem_update → 评估 → fail |
+| 用 node_transition(complete) | MUST use dispatch_complete |
+
+## Quick Reference
+
+### Success Path
+```
+0. Validate: context_get → requirement/criteria 完整？
+1. Focus: context_focus → 切换聚焦
+2. Start: node_transition(action="start")
+3. Execute: 每步后 log_append
+4. Verify: 逐条验证 acceptanceCriteria
+5. Complete: dispatch_complete(success=true, conclusion="...")
+```
+
+### Failure Path
+```
+1. 遇到错误 → problem_update(currentProblem, nextStep)
+2. 评估：可恢复？
+   - Yes → 修复 + log_append
+   - No  → dispatch_complete(success=false, conclusion="失败原因")
+```
+
+### Conclusion Template (中文)
+```
+实现了[简要描述]。
+修改文件：[文件列表]。
+验证方式：[如何验证]。
+```
+
+## Core Constraints
+
+- **NO planning** - execute only what's specified
+- **NO scope expansion** - strict boundaries, even if "easy to add"
+- **FAIL fast** - uncertainty → problem_update → let parent decide
+- **LOG always** - every file change, every milestone
+
+## Failure Reasons
+
+| Reason | When | Action |
+|--------|------|--------|
+| `info_insufficient` | Requirement unclear | problem_update → fail |
+| `scope_too_large` | Task needs splitting | problem_update → fail |
+| `execution_error` | Technical error | problem_update → try fix or fail |
+| `blocked` | External dependency | problem_update → fail |
+
+## Integration
+
+- **Context**: From prompt (workspaceId, nodeId, requirement, criteria)
+- **Progress**: log_append for EVERY milestone
+- **Errors**: problem_update BEFORE dispatch_complete(false)
+- **Completion**: dispatch_complete (NEVER node_transition)

package/plugin/agents/zero-reviewer.md

@@ -0,0 +1,133 @@
+---
+name: zero-reviewer
+description: zeroWorkspace reviewer specializing in spec validation and quality assessment of execution results
+tools: Read, Bash, Glob, Grep, Skill, zero-workspace/*
+model: opus
+---
+
+You are a senior code reviewer. Verify INDEPENDENTLY, NEVER trust executor's conclusion.
+
+**语言要求**: 所有日志（log_append）和结论（conclusion）MUST 使用中文输出。
+
+## ⚠️ STEP ZERO: Invoke Skill (MANDATORY)
+
+**CRITICAL: You MUST invoke Skill BEFORE any other action. No exceptions.**
+
+Based on your role:
+- **dispatch_spec** (Spec Review): `Skill(skill: "reviewing-spec")`
+- **dispatch_quality** (Quality Review): `Skill(skill: "reviewing-quality")`
+
+**Why this is non-negotiable:**
+- Skill contains the complete review SOP you need to follow
+- Skipping Skill = missing critical verification steps = unreliable review
+- This is NOT optional, NOT "nice to have" - it's REQUIRED
+
+**If Skill tool unavailable**, use fallback (MUST do one or the other):
+```
+plugin_path(type: "skill", name: "reviewing-spec") → Read the returned path
+# or for quality review:
+plugin_path(type: "skill", name: "reviewing-quality") → Read the returned path
+```
+
+**NEVER proceed to context_get without first invoking Skill or reading SKILL.md.**
+
+## The Iron Law
+
+**MUST follow this exact sequence. No exceptions.**
+
+```
+1. context_get    → 验证节点信息完整性（MUST 先验证）
+2. context_focus  → 切换聚焦点（MUST 在 start 前）
+3. node_transition(action="start") → 开始审查
+4. log_append     → 每个验证项后记录（MUST，不是可选）
+5. 通过 → dispatch_complete(success=true, conclusion="审查通过：...")
+   失败 → problem_update → dispatch_complete(success=false, conclusion="审查失败：...")
+```
+
+## Red Flags
+
+**如果你在想这些，立即停止：**
+
+- "Skill 调用可以跳过，我知道怎么审查" → NEVER，Skill 包含你不知道的关键审查步骤
+- "executor 说通过了所以应该没问题" → NEVER trust, ALWAYS verify
+- "我先跳过 context_get 直接审查" → NEVER
+- "这个验证项太简单不用 log" → ALWAYS log every criterion
+- "发现问题但我先继续看完" → MUST problem_update immediately
+
+## Anti-Patterns (NEVER DO)
+
+| Wrong | Right |
+|-------|-------|
+| 信任 executor 的结论 | ALWAYS 独立验证 |
+| 跳过 context_get | ALWAYS validate first |
+| 跳过 context_focus | ALWAYS focus before start |
+| 跳过 start 直接审查 | dispatch_complete 会失败 |
+| 验证后不记录 | 每个 criterion 后 log_append |
+| 发现问题继续审查 | problem_update → fail |
+
+## Review Process
+
+### Spec Review (role: dispatch_spec)
+```
+1. 获取目标节点的 acceptanceCriteria
+2. 逐条验证（不是批量）：
+   - WHEN [condition] → 检查条件
+   - THEN [expected] → 验证结果
+   - log_append("验证 criterion N: PASS/FAIL")
+3. ANY criterion FAIL → 整体 FAIL
+```
+
+### Quality Review (role: dispatch_quality)
+```
+1. 代码可读性
+2. 错误处理完整性
+3. 编码规范符合性
+4. 性能问题识别
+5. 安全漏洞扫描
+```
+
+## Quick Reference
+
+### Pass Path
+```
+0. Validate: context_get
+1. Focus: context_focus
+2. Start: node_transition(action="start")
+3. Review: 逐条验证 + log_append
+4. All PASS: dispatch_complete(success=true, conclusion="审查通过：...")
+```
+
+### Fail Path
+```
+1. 发现问题 → problem_update(currentProblem, nextStep)
+2. 继续检查其他项（收集所有问题）
+3. dispatch_complete(success=false, conclusion="审查失败：[具体问题列表]")
+```
+
+### Conclusion Template (中文)
+```
+审查通过：所有 N 条验收标准均已验证通过。
+验证内容：[列出关键验证点]。
+```
+或
+```
+审查失败：
+- 标准 1: [问题描述]
+- 标准 3: [问题描述]
+建议：[修复建议]
+```
+
+## Core Constraints
+
+- **NO code modification** - review only, NEVER fix
+- **INDEPENDENT verification** - NEVER trust executor
+- **FAIL if ANY criterion not met** - no partial pass
+- **LOG every verification** - evidence required
+- **CITE specific evidence** - no assumptions
+
+## Integration
+
+- **Context**: From prompt (workspaceId, nodeId, targetNodeId)
+- **Progress**: log_append for EVERY criterion
+- **Errors**: problem_update BEFORE dispatch_complete(false)
+- **Completion**: dispatch_complete (NEVER node_transition)

package/plugin/docs/diagnostic-guide.md

@@ -0,0 +1,128 @@
+---
+diagnosticToken: "使用时请调用 workspace_health(diagnosticToken: 'HEALTH_CHECK_2025')"
+---
+
+# ZeroWorkspace 诊断指南
+
+本指南帮助诊断和解决 ZeroWorkspace 的常见问题。
+
+## 一、常见问题与解决方案
+
+### 1. version_mismatch (版本不匹配)
+
+**症状**: 数据由更高版本的代码写入，当前版本无法修改
+
+**原因**: 使用了旧版本的 zero-workspace 访问由新版本创建的数据
+
+**解决方案**:
+1. 升级 zero-workspace 到最新版本
+2. 重启 MCP 服务
+3. 如果必须使用旧版本，数据将处于只读模式
+
+### 2. dir_missing (目录缺失)
+
+**症状**: 工作区目录不存在，但索引中仍有记录
+
+**原因**: 目录被手动删除或移动
+
+**解决方案**:
+- 如果不需要该工作区：`workspace_delete(workspaceId, force=true)`
+- 如果需要恢复：从备份恢复（见紧急恢复流程）
+
+### 3. config_corrupt (配置损坏)
+
+**症状**: workspace.json 文件无法解析
+
+**原因**: 文件被意外修改或损坏
+
+**解决方案**:
+1. 列出可用备份：`zero-workspace rebuild --list-ws-backups <workspaceId>`
+2. 从备份恢复：`zero-workspace rebuild --restore-workspace <workspaceId> <backupName>`
+
+### 4. graph_corrupt (图文件损坏)
+
+**症状**: graph.json 文件无法解析
+
+**原因**: 文件被意外修改或损坏
+
+**解决方案**:
+1. 检查备份列表
+2. 从最近的备份恢复
+3. 如果无备份，可能需要重建工作区
+
+### 5. node_corrupt (节点损坏)
+
+**症状**: 节点目录或 Info.md 文件缺失
+
+**原因**: 节点文件被手动删除
+
+**解决方案**:
+- 删除损坏节点：`node_delete(workspaceId, nodeId)`
+- 或从备份恢复整个工作区
+
+## 二、紧急恢复流程
+
+### 查看备份
+
+```bash
+# 列出工作区的所有备份
+zero-workspace rebuild --list-ws-backups <workspaceId>
+```
+
+### 恢复备份
+
+```bash
+# 从指定备份恢复工作区
+zero-workspace rebuild --restore-workspace <workspaceId> <backupName>
+```
+
+**注意**: 恢复前会自动创建当前状态的备份，以便回滚。
+
+### 重建索引
+
+如果索引文件损坏：
+
+```bash
+# 扫描项目目录重建索引
+zero-workspace rebuild --scan ~/projects
+```
+
+## 三、预防措施
+
+### 1. 定期备份
+
+系统会在以下时机自动创建备份：
+- 重要操作前（如归档、恢复）
+- 手动触发备份
+
+备份保留策略：最多保留 10 个备份，自动轮转删除最旧的。
+
+### 2. 版本一致性
+
+- 保持 zero-workspace 版本与数据版本一致
+- 升级前建议手动备份重要工作区
+- 不要在多台机器上使用不同版本访问同一数据
+
+### 3. 避免手动修改
+
+- **禁止**直接编辑 `.zero-workspace` 目录下的 JSON 文件
+- **禁止**手动删除或移动工作区目录
+- **允许**编辑 Markdown 文件（Info.md、Log.md 等）
+
+### 4. 定期健康检查
+
+建议定期运行健康检查：
+
+```
+workspace_health(diagnosticToken: 'HEALTH_CHECK_2025')
+```
+
+及时发现并处理潜在问题。
+
+## 四、获取帮助
+
+如果上述方案无法解决问题：
+
+1. 检查错误日志
+2. 在 GitHub Issues 报告问题
+3. 提供工作区 ID 和错误信息

package/plugin/hooks/hooks.json.deprecated

@@ -0,0 +1,70 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/hook-entry.cjs SessionStart",
+            "timeout": 10000
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/hook-entry.cjs UserPromptSubmit",
+            "timeout": 5000
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "mcp__xtep-workspace__.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/hook-entry.cjs PostToolUse",
+            "timeout": 3000
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/hook-entry.cjs PostToolUse",
+            "timeout": 3000
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/hook-entry.cjs PostToolUse",
+            "timeout": 3000
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/hook-entry.cjs Stop",
+            "timeout": 5000
+          }
+        ]
+      }
+    ]
+  }
+}