xtep-workspace 1.10.10

package//351/205/215/347/275/256/346/226/271/345/274/217.md

@@ -0,0 +1,330 @@
+# XtepWorkspace 配置指南
+
+本文档指导你如何配置和使用 XtepWorkspace。
+
+## 前置要求
+
+- **Node.js**: 20.19+ 或 22.12+（推荐使用 nvm 管理版本）
+- **支持 MCP 的 AI 工具**（如 Claude Code、Cursor、Windsurf、Cline 等）
+
+检查 Node.js 版本：
+```bash
+node --version
+```
+
+## 配置概览
+
+XtepWorkspace 的配置分为两部分：
+
+| 配置类型 | 必需性 | 适用平台 | 功能 |
+|---------|-------|---------|------|
+| **基础配置** | 必需 | 所有支持 MCP 的平台 | MCP 服务，提供完整的工作区管理能力 |
+| **增强配置** | 可选 | Claude Code、Cursor | Hook 系统，自动注入上下文和智能提醒 |
+
+---
+
+## 第一步：基础配置（MCP 服务）
+
+### 方式一：npm 安装（推荐）
+
+最简单的安装方式，两步完成：
+
+```bash
+# 1. 全局安装
+npm install -g xtep-workspace
+
+# 2. 运行配置向导
+xtep-workspace setup
+```
+
+配置向导会自动：
+- 检测已安装的 AI 工具（Claude Code、Cursor）
+- 配置 MCP 服务器
+- 添加权限（Claude Code）
+- 可选安装智能提醒 Hook
+
+**快速配置选项**：
+
+```bash
+# Claude Code 一键配置
+xtep-workspace setup --claude-code
+
+# Cursor 一键配置
+xtep-workspace setup --cursor
+
+# 查看当前配置状态
+xtep-workspace setup --status
+```
+
+**验证安装**：在 Claude Code 中输入 `/mcp` 查看已安装的服务器。
+
+### 方式二：源码安装（适用于自定义或其他平台）
+
+```bash
+# 克隆项目
+git clone <仓库地址>
+cd xtep-workspace
+
+# 安装依赖（包含 Web 前端）
+npm install
+cd web && npm install && cd ..
+
+# 构建项目（MCP 服务 + Web 界面）
+npm run build:all
+
+# 如仅需 MCP 服务，不需要 Web 界面：
+# npm run build
+```
+
+然后在 AI 工具中添加 MCP 服务器配置：
+
+```json
+{
+  "mcpServers": {
+    "xtep-workspace": {
+      "command": "node",
+      "args": ["/path/to/xtep-workspace/dist/check-node-version.js"]
+    }
+  }
+}
+```
+
+> 将 `/path/to/xtep-workspace` 替换为实际的项目路径。
+
+#### 各平台配置文件位置
+
+| 平台 | 配置文件路径 |
+|------|-------------|
+| **Claude Code** | `~/.claude.json`（用户级）或项目下 `.mcp.json`（项目级） |
+| **Cursor** | `~/.cursor/mcp.json` 或项目下 `.cursor/mcp.json` |
+| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |
+| **Cline** | VS Code 设置中的 `cline.mcpServers` |
+| **其他工具** | 参考对应工具的 MCP 配置文档 |
+
+> Claude Code 也可使用命令行添加：`claude mcp add xtep-workspace -s user -- node /path/to/dist/check-node-version.js`
+
+### 配置 MCP 工具权限（Claude Code）
+
+> 用于减少mcp工具权限请求带来的打断，提升对话体验
+
+**推荐方式**：使用 `xtep-workspace setup` 自动配置，或手动在 `~/.claude/settings.local.json` 中添加：
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "mcp__xtep-workspace"
+    ]
+  }
+}
+```
+
+**备选方式**：运行项目内的配置脚本（仅源码安装）：
+
+```bash
+./scripts/setup-claude-code.sh
+```
+
+### 验证配置
+
+重启你的 AI 工具，然后向 AI 说：
+
+> "介绍一下工作台的使用方式"
+
+如果返回 XtepWorkspace 的介绍信息，说明 MCP 配置成功。
+
+> **提示**：基础配置完成后，你已经可以使用 XtepWorkspace 的全部功能。如果你使用的是 Claude Code 或 Cursor，可以继续配置 Hook 系统获得更好的体验。
+
+---
+
+## 第二步：增强配置（Hook 系统，可选）
+
+Hook 系统可以在 AI 对话过程中**自动注入工作区上下文**，无需手动绑定会话。目前仅 **Claude Code** 和 **Cursor** 支持 Hook 机制。
+
+> **其他平台用户**：如果你使用的平台不支持 Hook，可以跳过此步骤。如果你的平台支持hook，可以提出需求，将会尽快支持。
+
+### 2.1 安装 Hook
+
+#### npm 用户
+
+```bash
+# 交互式安装
+xtep-workspace-hooks
+
+# 或指定安装类型
+xtep-workspace-hooks --claude-hooks
+xtep-workspace-hooks --cursor-hooks
+xtep-workspace-hooks --all
+```
+
+#### 源码用户
+
+```bash
+./scripts/install-global.sh
+```
+
+根据菜单提示选择：
+- `1` - 安装 Claude Code Hook
+- `2` - 安装 Cursor Hook
+- `3` - 全部安装
+- `4` - 卸载 Claude Code Hook
+- `5` - 卸载 Cursor Hook
+- `6` - 全部卸载
+
+#### 命令行安装
+
+```bash
+# Claude Code Hook
+./scripts/install-global.sh --claude-hooks
+
+# Cursor Hook
+./scripts/install-global.sh --cursor-hooks
+
+# 全部安装
+./scripts/install-global.sh --all
+
+# 卸载
+./scripts/install-global.sh --uninstall-claude-hooks
+./scripts/install-global.sh --uninstall-cursor-hooks
+./scripts/install-global.sh --uninstall-hooks
+
+# 查看帮助
+./scripts/install-global.sh --help
+```
+
+安装完成后，**需要重启对应的 IDE** 使配置生效。
+
+### 2.2 Hook 功能说明
+
+| 功能 | Claude Code | Cursor |
+|------|:-----------:|:------:|
+| 自动注入会话 ID | ✅ 会话开始时 | ✅ 检测到关键词时 |
+| 自动注入工作区上下文 | ✅ | ✅ |
+| 多窗口隔离 | ✅ | ✅ |
+| 智能提醒 | ✅ | ✅ |
+
+**智能提醒功能**（绑定工作区后自动启用）：
+
+| 提醒类型 | 触发条件 | 说明 |
+|---------|---------|------|
+| 问题提醒 | 节点有未解决的问题 | 提醒优先解决问题 |
+| 日志超时 | 执行中 + 最后日志 > 3 分钟 | 提醒记录工作进展 |
+| 子节点完成 | 监控中 + 所有子节点已完成 | 提醒汇总并完成节点 |
+| 计划确认 | 规划中 + 有子节点 | 提醒向用户确认计划 |
+| 无日志提醒 | 执行中 + 无日志 > 1 分钟 | 提醒开始记录日志 |
+| 问题记录 | 执行中 + 无问题记录 > 5 分钟 | 提醒使用 problem_update |
+
+智能提醒采用节流机制（3分钟间隔），问题提醒不受节流限制。
+
+### 2.3 平台差异
+
+| 特性 | Claude Code | Cursor |
+|------|-------------|--------|
+| 会话标识 | `session_id` | `conversation_id` |
+| 触发事件 | SessionStart, UserPromptSubmit | beforeSubmitPrompt |
+| Hook 配置文件 | `~/.claude/settings.json` | `~/.cursor/hooks.json` |
+
+---
+
+## 可选配置
+
+### 启动 Web 界面
+
+Web 界面提供可视化的工作区管理：
+
+```bash
+xtep-workspace webui
+```
+
+服务启动后会自动打开浏览器（默认端口 19540）。
+
+其他命令：
+```bash
+xtep-workspace webui status   # 查看服务状态
+xtep-workspace webui stop     # 停止服务
+xtep-workspace webui restart  # 重启服务
+```
+
+> 开发者相关命令（热更新、前端构建等）请参考 [README.md](README.md#开发) 的开发章节。
+
+### 环境变量
+
+| 变量名 | 说明 | 默认值 |
+|--------|------|--------|
+| `XTEP_PROJECT_ROOT` | 工作区数据存储路径 | 当前工作目录 |
+| `HTTP_PORT` | Web 服务端口 | 19540 |
+| `XTEP_HOST` | Web 服务监听地址 | 127.0.0.1 |
+
+---
+
+## 常见问题
+
+### MCP 服务未启动
+
+确保已正确安装 xtep-workspace（`npm install -g xtep-workspace`）。
+
+### 端口被占用
+
+如果默认端口被占用，可以设置环境变量更换端口：
+
+```bash
+HTTP_PORT=19542 xtep-workspace webui
+```
+
+### Node.js 版本不兼容
+
+使用 nvm 切换到兼容版本：
+
+```bash
+nvm install 20
+nvm use 20
+```
+
+### 权限不足
+
+如果脚本无法执行，添加执行权限：
+
+```bash
+chmod +x ./scripts/setup-claude-code.sh
+```
+
+### jq 未安装
+
+配置脚本使用 `jq` 来合并 JSON 配置。如果未安装 `jq`，脚本会使用简单模式，但推荐安装：
+
+```bash
+# macOS
+brew install jq
+
+# Ubuntu/Debian
+sudo apt-get install jq
+```
+
+---
+
+## 从源码安装迁移到 npm
+
+如果你之前使用源码安装，现在想切换到 npm 安装：
+
+```bash
+# 1. 安装 npm 包
+npm install -g xtep-workspace
+
+# 2. 运行配置向导（会自动覆盖旧的 MCP 配置）
+xtep-workspace setup
+```
+
+**说明：**
+- 工作区数据保存在 `~/.xtep-workspace/`，迁移后数据不会丢失
+- Hook 脚本会自动更新
+- 迁移完成后可删除旧的源码目录
+
+---
+
+## 下一步
+
+配置完成后，可以：
+
+1. 向 AI 说 "使用工作台，帮我实现 xxx 功能" 开始新任务
+2. 运行 `xtep-workspace webui` 启动 Web 界面查看工作区可视化
+3. 阅读 [用户指南](docs/user-guide.md) 了解完整工作流程