From bc4176fda0a7dc56d6fd7e1371fd6566ca553c0e Mon Sep 17 00:00:00 2001 From: catlog22 Date: Sat, 17 Jan 2026 10:38:06 +0800 Subject: [PATCH] docs: consolidate documentation with 4-level workflow guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add WORKFLOW_GUIDE.md (EN) and WORKFLOW_GUIDE_CN.md (CN) - Simplify README.md to highlight 4-level workflow system - Remove redundant docs: MCP_*.md, WORKFLOW_DECISION_GUIDE*.md, WORKFLOW_DIAGRAMS.md - Move COMMAND_SPEC.md to docs/ - Move codex_mcp.md, CODEX_LENS_AUTO_HYBRID.md to codex-lens/docs/ - Delete temporary debug documents and outdated files Root directory: 28 → 14 MD files --- API_SETTINGS_IMPLEMENTATION.md | 196 ---- DASHBOARD_OPERATIONS.md | 508 ----------- DASHBOARD_OPERATIONS_EN.md | 508 ----------- EMBEDDINGS_IMPROVEMENTS_SUMMARY.md | 167 ---- MCP_FINAL_FIX.md | 248 ----- MCP_FIX_SUMMARY.md | 227 ----- MCP_INSTALL_DEBUG.md | 274 ------ MCP_OPTIMIZATION_SUMMARY.md | 94 -- README.md | 351 ++----- WORKFLOW_DECISION_GUIDE.md | 853 ------------------ WORKFLOW_DECISION_GUIDE_EN.md | 744 --------------- WORKFLOW_DIAGRAMS.md | 764 ---------------- WORKFLOW_GUIDE.md | 700 ++++++++++++++ WORKFLOW_GUIDE_CN.md | 671 ++++++++++++++ .../docs/CODEX_LENS_AUTO_HYBRID.md | 0 codex_mcp.md => codex-lens/docs/codex_mcp.md | 0 codex_prompt.md | 96 -- COMMAND_SPEC.md => docs/COMMAND_SPEC.md | 0 docs/workflows/ISSUE_LOOP_WORKFLOW.md | 435 --------- test-rules-cli-generation.md | 138 --- 20 files changed, 1459 insertions(+), 5515 deletions(-) delete mode 100644 API_SETTINGS_IMPLEMENTATION.md delete mode 100644 DASHBOARD_OPERATIONS.md delete mode 100644 DASHBOARD_OPERATIONS_EN.md delete mode 100644 EMBEDDINGS_IMPROVEMENTS_SUMMARY.md delete mode 100644 MCP_FINAL_FIX.md delete mode 100644 MCP_FIX_SUMMARY.md delete mode 100644 MCP_INSTALL_DEBUG.md delete mode 100644 MCP_OPTIMIZATION_SUMMARY.md delete mode 100644 WORKFLOW_DECISION_GUIDE.md delete mode 100644 WORKFLOW_DECISION_GUIDE_EN.md delete mode 100644 WORKFLOW_DIAGRAMS.md create mode 100644 WORKFLOW_GUIDE.md create mode 100644 WORKFLOW_GUIDE_CN.md rename CODEX_LENS_AUTO_HYBRID.md => codex-lens/docs/CODEX_LENS_AUTO_HYBRID.md (100%) rename codex_mcp.md => codex-lens/docs/codex_mcp.md (100%) delete mode 100644 codex_prompt.md rename COMMAND_SPEC.md => docs/COMMAND_SPEC.md (100%) delete mode 100644 docs/workflows/ISSUE_LOOP_WORKFLOW.md delete mode 100644 test-rules-cli-generation.md diff --git a/API_SETTINGS_IMPLEMENTATION.md b/API_SETTINGS_IMPLEMENTATION.md deleted file mode 100644 index 047a980c..00000000 --- a/API_SETTINGS_IMPLEMENTATION.md +++ /dev/null @@ -1,196 +0,0 @@ -# API Settings 页面实现完成 - -## 创建的文件 - -### 1. JavaScript 文件 -**位置**: `ccw/src/templates/dashboard-js/views/api-settings.js` (28KB) - -**主要功能**: -- ✅ Provider Management (提供商管理) - - 添加/编辑/删除提供商 - - 支持 OpenAI, Anthropic, Google, Ollama, Azure, Mistral, DeepSeek, Custom - - API Key 管理（支持环境变量） - - 连接测试功能 - -- ✅ Endpoint Management (端点管理) - - 创建自定义端点 - - 关联提供商和模型 - - 缓存策略配置 - - 显示 CLI 使用示例 - -- ✅ Cache Management (缓存管理) - - 全局缓存开关 - - 缓存统计显示 - - 清除缓存功能 - -### 2. CSS 样式文件 -**位置**: `ccw/src/templates/dashboard-css/31-api-settings.css` (6.8KB) - -**样式包括**: -- 卡片式布局 -- 表单样式 -- 进度条 -- 响应式设计 -- 空状态显示 - -### 3. 国际化支持 -**位置**: `ccw/src/templates/dashboard-js/i18n.js` - -**添加的翻译**: -- 英文：54 个翻译键 -- 中文：54 个翻译键 -- 包含所有 UI 文本、提示信息、错误消息 - -### 4. 配置更新 - -#### dashboard-generator.ts -- ✅ 添加 `31-api-settings.css` 到 CSS 模块列表 -- ✅ 添加 `views/api-settings.js` 到 JS 模块列表 - -#### navigation.js -- ✅ 添加 `api-settings` 路由处理 -- ✅ 添加标题更新逻辑 - -#### dashboard.html -- ✅ 添加导航菜单项 (Settings 图标) - -## API 端点使用 - -该页面使用以下后端 API（已存在）: - -### Provider APIs -- `GET /api/litellm-api/providers` - 获取所有提供商 -- `POST /api/litellm-api/providers` - 创建提供商 -- `PUT /api/litellm-api/providers/:id` - 更新提供商 -- `DELETE /api/litellm-api/providers/:id` - 删除提供商 -- `POST /api/litellm-api/providers/:id/test` - 测试连接 - -### Endpoint APIs -- `GET /api/litellm-api/endpoints` - 获取所有端点 -- `POST /api/litellm-api/endpoints` - 创建端点 -- `PUT /api/litellm-api/endpoints/:id` - 更新端点 -- `DELETE /api/litellm-api/endpoints/:id` - 删除端点 - -### Model Discovery -- `GET /api/litellm-api/models/:providerType` - 获取提供商支持的模型列表 - -### Cache APIs -- `GET /api/litellm-api/cache/stats` - 获取缓存统计 -- `POST /api/litellm-api/cache/clear` - 清除缓存 - -### Config APIs -- `GET /api/litellm-api/config` - 获取完整配置 -- `PUT /api/litellm-api/config/cache` - 更新全局缓存设置 - -## 页面特性 - -### Provider 管理 -``` -+-- Provider Card ------------------------+ -| OpenAI Production [Edit] [Del] | -| Type: openai | -| Key: sk-...abc | -| URL: https://api.openai.com/v1 | -| Status: ✓ Enabled | -+-----------------------------------------+ -``` - -### Endpoint 管理 -``` -+-- Endpoint Card ------------------------+ -| GPT-4o Code Review [Edit] [Del]| -| ID: my-gpt4o | -| Provider: OpenAI Production | -| Model: gpt-4-turbo | -| Cache: Enabled (60 min) | -| Usage: ccw cli -p "..." --model my-gpt4o| -+-----------------------------------------+ -``` - -### 表单功能 -- **Provider Form**: - - 类型选择（8 种提供商） - - API Key 输入（支持显示/隐藏） - - 环境变量支持 - - Base URL 自定义 - - 启用/禁用开关 - -- **Endpoint Form**: - - 端点 ID（CLI 使用） - - 显示名称 - - 提供商选择（动态加载） - - 模型选择（根据提供商动态加载） - - 缓存策略配置 - - TTL（分钟） - - 最大大小（KB） - - 自动缓存文件模式 - -## 使用流程 - -### 1. 添加提供商 -1. 点击 "Add Provider" -2. 选择提供商类型（如 OpenAI） -3. 输入显示名称 -4. 输入 API Key（或使用环境变量） -5. 可选：输入自定义 API Base URL -6. 保存 - -### 2. 创建自定义端点 -1. 点击 "Add Endpoint" -2. 输入端点 ID（用于 CLI） -3. 输入显示名称 -4. 选择提供商 -5. 选择模型（自动加载该提供商支持的模型） -6. 可选：配置缓存策略 -7. 保存 - -### 3. 使用端点 -```bash -ccw cli -p "Analyze this code..." --model my-gpt4o -``` - -## 代码质量 - -- ✅ 遵循现有代码风格 -- ✅ 使用 i18n 函数支持国际化 -- ✅ 响应式设计（移动端友好） -- ✅ 完整的表单验证 -- ✅ 用户友好的错误提示 -- ✅ 使用 Lucide 图标 -- ✅ 模态框复用现有样式 -- ✅ 与后端 API 完全集成 - -## 测试建议 - -1. **基础功能测试**: - - 添加/编辑/删除提供商 - - 添加/编辑/删除端点 - - 清除缓存 - -2. **表单验证测试**: - - 必填字段验证 - - API Key 显示/隐藏 - - 环境变量切换 - -3. **数据加载测试**: - - 模型列表动态加载 - - 缓存统计显示 - - 空状态显示 - -4. **国际化测试**: - - 切换语言（英文/中文） - - 验证所有文本正确显示 - -## 下一步 - -页面已完成并集成到项目中。启动 CCW Dashboard 后： -1. 导航栏会显示 "API Settings" 菜单项（Settings 图标） -2. 点击进入即可使用所有功能 -3. 所有操作会实时同步到配置文件 - -## 注意事项 - -- 页面使用现有的 LiteLLM API 路由（`litellm-api-routes.ts`） -- 配置保存在项目的 LiteLLM 配置文件中 -- 支持环境变量引用格式：`${VARIABLE_NAME}` -- API Key 在显示时会自动脱敏（显示前 4 位和后 4 位） diff --git a/DASHBOARD_OPERATIONS.md b/DASHBOARD_OPERATIONS.md deleted file mode 100644 index aa18eb17..00000000 --- a/DASHBOARD_OPERATIONS.md +++ /dev/null @@ -1,508 +0,0 @@ -# CCW Dashboard 操作指南 - -**版本**: 6.2.0 -**更新日期**: 2025-12-20 - -本文档提供 CCW Dashboard 各功能视图的详细操作步骤说明。 - ---- - -## 目录 - -1. [首页概览操作](#1-首页概览操作) -2. [会话详情操作](#2-会话详情操作) -3. [CLI 管理器操作](#3-cli-管理器操作) -4. [核心记忆操作](#4-核心记忆操作) -5. [MCP 服务器管理操作](#5-mcp-服务器管理操作) -6. [Hook 管理器操作](#6-hook-管理器操作) -7. [技能管理器操作](#7-技能管理器操作) -8. [CodexLens 索引管理操作](#8-codexlens-索引管理操作) - ---- - -## 1. 首页概览操作 - -### 1.1 进入方式 -- 启动 Dashboard 后自动显示 -- 点击侧边栏 **"概览"** 导航项 - -### 1.2 项目切换 -1. 点击顶部操作栏的 **项目路径选择器** -2. 从下拉列表选择最近项目，或点击 **"浏览..."** 选择新项目 -3. 系统自动加载新项目数据 - -### 1.3 数据刷新 -- 点击顶部操作栏的 **刷新按钮** (🔄) -- 或等待 WebSocket 自动推送更新 - -### 1.4 活跃会话轮播 -- 自动轮播显示当前活跃的工作流会话 -- 点击会话卡片进入会话详情 - -### 1.5 统计卡片 -显示以下统计信息： -- 会话总数 -- 活跃会话数 -- 已归档会话数 -- 任务完成率 - ---- - -## 2. 会话详情操作 - -### 2.1 进入方式 -- 从首页点击会话卡片 -- 从侧边栏 **"会话"** > **"全部/活跃/已归档"** 列表点击 - -### 2.2 会话列表操作 - -| 操作 | 步骤 | -|------|------| -| 筛选会话 | 点击 **"全部/活跃/已归档"** 标签切换 | -| 搜索会话 | 在搜索框输入会话 ID 或描述 | -| 查看详情 | 点击会话行展开详情 | - -### 2.3 会话详情面板 - -#### 基本信息区 -- 会话 ID、创建时间、状态 -- 会话描述和目标 - -#### 任务列表区 -| 操作 | 说明 | -|------|------| -| 查看任务 | 任务以列表形式显示，包含状态图标 | -| 展开任务 | 点击任务行查看详细信息 | -| 任务状态 | 🔵 待处理 / 🟡 进行中 / 🟢 完成 / 🔴 失败 | - -#### 操作按钮 -| 按钮 | 功能 | -|------|------| -| **归档** | 将会话标记为已归档 | -| **删除** | 删除会话（需确认） | -| **导出** | 导出会话数据为 JSON | - -### 2.4 任务抽屉 - -点击任务后打开的详情抽屉： - -| 区域 | 内容 | -|------|------| -| 头部 | 任务标题、状态徽章 | -| 上下文 | 相关文件列表、依赖项 | -| 执行日志 | 实时执行输出（WebSocket 推送） | -| 操作区 | 重试、跳过、标记完成 | - ---- - -## 3. CLI 管理器操作 - -### 3.1 进入方式 -侧边栏 **"项目"** > **"状态"** - -### 3.2 CLI 工具状态面板 - -#### 工具状态卡片 -每个工具（Gemini/Qwen/Codex）显示： -- 安装状态：✅ 已安装 / ❌ 未安装 -- 版本信息 -- 默认模型配置 - -#### 设置默认工具 -1. 点击工具卡片上的 **"设为默认"** 按钮 -2. 确认选择 - -#### 模型配置 -1. 点击 **"配置"** 按钮 -2. 在弹出的模态框中设置： - - 主模型 (Primary Model) - - 备用模型 (Fallback Model) -3. 点击 **"保存"** - -### 3.3 安装/卸载向导 - -#### 安装工具 -1. 点击未安装工具的 **"安装"** 按钮 -2. 按向导步骤操作： - - 确认系统要求 - - 输入 API 密钥（如需要） - - 选择安装选项 -3. 等待安装完成 - -#### 卸载工具 -1. 点击已安装工具的 **"卸载"** 按钮 -2. 确认卸载操作 -3. 等待卸载完成 - -### 3.4 执行历史 - -侧边栏 **"项目"** > **"历史"** - -| 操作 | 说明 | -|------|------| -| 查看记录 | 列表显示执行时间、工具、提示词摘要 | -| 展开详情 | 点击记录查看完整输入/输出 | -| 恢复会话 | 点击 **"继续"** 按钮使用 `--resume` 恢复 | -| 复制命令 | 点击 **"复制"** 图标复制执行命令 | - ---- - -## 4. 核心记忆操作 - -### 4.1 进入方式 -侧边栏 **"记忆"** > **"核心记忆"** - -### 4.2 记忆列表视图 - -#### 查看记忆 -- 记忆条目以卡片形式显示 -- 包含：标题、摘要、标签、创建时间 - -#### 创建记忆 -1. 点击 **"+ 新建记忆"** 按钮 -2. 填写表单： - | 字段 | 说明 | - |------|------| - | 标题 | 记忆标题（必填） | - | 内容 | 记忆正文（Markdown 支持） | - | 标签 | 分类标签（逗号分隔） | - | 优先级 | 高/中/低 | -3. 点击 **"保存"** - -#### 编辑记忆 -1. 点击记忆卡片的 **"编辑"** 图标 -2. 修改内容 -3. 点击 **"保存"** - -#### 归档/删除 -- **归档**: 点击 **"归档"** 图标，记忆移至归档列表 -- **删除**: 点击 **"删除"** 图标，确认后永久删除 - -### 4.3 集群视图 - -切换到 **"集群"** 标签页 - -#### 查看集群 -- 自动聚类的会话分组显示 -- 每个集群显示：名称、成员数、创建时间 - -#### 自动聚类 -1. 点击 **"自动聚类"** 按钮 -2. 设置参数： - | 参数 | 说明 | - |------|------| - | 相似度阈值 | 0.0-1.0，默认 0.7 | - | 最小成员数 | 集群最小会话数 | -3. 点击 **"执行"** -4. 等待聚类完成 - -#### 集群管理 -| 操作 | 步骤 | -|------|------| -| 查看成员 | 点击集群卡片展开成员列表 | -| 重命名 | 点击集群名称编辑 | -| 合并集群 | 选中多个集群，点击 **"合并"** | -| 删除集群 | 点击 **"删除"** 图标（成员不会删除） | - -### 4.4 嵌入管理 - -#### 查看嵌入状态 -- 显示已生成嵌入的记忆数量 -- 显示待生成嵌入的记忆数量 - -#### 生成嵌入 -1. 点击 **"生成嵌入"** 按钮 -2. 选择范围： - - 全部未嵌入 - - 选中的记忆 -3. 等待生成完成（进度条显示） - ---- - -## 5. MCP 服务器管理操作 - -### 5.1 进入方式 -侧边栏 **"配置"** > **"MCP 服务器"** - -### 5.2 服务器列表 - -#### 查看服务器 -- 列表显示已配置的服务器 -- 每行显示：名称、类型、状态、配置来源 - -#### 状态指示 -- 🟢 运行中 -- 🔴 已停止 -- 🟡 启动中 - -### 5.3 创建服务器 - -#### 手动创建 -1. 点击 **"+ 添加服务器"** 按钮 -2. 填写表单： - | 字段 | 说明 | - |------|------| - | 名称 | 服务器标识名（必填） | - | 命令 | 启动命令（如 `node`） | - | 参数 | 命令参数数组 | - | 环境变量 | KEY=VALUE 格式 | - | 配置范围 | 项目级 / 全局 | -3. 点击 **"保存"** - -#### 从模板安装 -1. 点击 **"模板"** 标签 -2. 浏览可用模板 -3. 点击模板的 **"安装"** 按钮 -4. 确认或修改配置 -5. 点击 **"确认安装"** - -### 5.4 编辑/删除 - -| 操作 | 步骤 | -|------|------| -| 编辑 | 点击 **"编辑"** 图标 → 修改配置 → 保存 | -| 删除 | 点击 **"删除"** 图标 → 确认删除 | -| 启用/禁用 | 切换状态开关 | - -### 5.5 配置文件位置 - -| 范围 | 文件路径 | -|------|----------| -| 项目级 | `.mcp.json` | -| 全局 | `~/.claude/settings.json` | - ---- - -## 6. Hook 管理器操作 - -### 6.1 进入方式 -侧边栏 **"配置"** > **"Hooks"** - -### 6.2 Hook 列表 - -#### 按类型查看 -- **PreToolUse**: 工具使用前触发 -- **PostToolUse**: 工具使用后触发 -- **Notification**: 通知类钩子 - -#### 列表信息 -每个 Hook 显示：名称、类型、匹配工具、命令摘要 - -### 6.3 创建 Hook - -#### 向导模式 -1. 点击 **"+ 添加 Hook"** 按钮 -2. 选择 Hook 类型 -3. 填写配置： - | 字段 | 说明 | - |------|------| - | 名称 | Hook 标识名 | - | 匹配器 | 匹配的工具名称（支持通配符 `*`） | - | 命令 | 执行的 Shell 命令 | - | 超时 | 命令超时时间（毫秒） | - | 范围 | 项目级 / 全局 | -4. 点击 **"保存"** - -#### 从模板创建 -1. 点击 **"模板"** 标签 -2. 选择预设模板（如：格式化检查、安全扫描） -3. 点击 **"使用模板"** -4. 根据需要修改配置 -5. 点击 **"保存"** - -### 6.4 编辑/删除 - -| 操作 | 步骤 | -|------|------| -| 编辑 | 点击 Hook 行 → 修改配置 → 保存 | -| 删除 | 点击 **"删除"** 图标 → 确认 | -| 启用/禁用 | 切换状态开关 | - -### 6.5 配置文件位置 - -| 范围 | 文件路径 | -|------|----------| -| 项目级 | `.claude/settings.local.json` | -| 全局 | `~/.claude/settings.json` | - ---- - -## 7. 技能管理器操作 - -### 7.1 进入方式 -侧边栏 **"记忆"** > **"技能"** - -### 7.2 技能列表 - -#### 分类视图 -- **项目技能**: `./.claude/skills/` 目录下的技能 -- **用户技能**: `~/.claude/skills/` 目录下的技能 - -#### 技能卡片信息 -- 技能名称 -- 描述 -- 版本号 -- 工具数量 -- 支持文件数量 - -### 7.3 查看技能详情 - -1. 点击技能卡片 -2. 详情面板显示： - - 完整描述 - - 包含的工具列表 - - 支持文件列表 - - 依赖信息 - -### 7.4 创建技能 - -#### 从文件夹导入 -1. 点击 **"+ 导入技能"** 按钮 -2. 选择包含技能文件的目录 -3. 确认技能信息 -4. 点击 **"导入"** - -#### 通过 CLI 生成 -1. 点击 **"+ 生成技能"** 按钮 -2. 输入技能描述 -3. 选择生成选项： - - 目标目录（项目/用户） - - 包含的能力 -4. 点击 **"生成"** -5. 等待 AI 生成完成 - -### 7.5 删除技能 - -1. 点击技能卡片的 **"删除"** 图标 -2. 确认删除操作 -3. 技能文件将被移除 - ---- - -## 8. CodexLens 索引管理操作 - -### 8.1 进入方式 -侧边栏 **"项目"** > **"状态"** → CodexLens 面板 - -### 8.2 索引状态 - -#### 状态指示 -| 状态 | 说明 | -|------|------| -| ✅ 已索引 | 项目已建立索引 | -| ⚠️ 过期 | 索引需要更新 | -| ❌ 未索引 | 项目未建立索引 | - -#### 索引统计 -- 总索引大小 -- 项目数量 -- 向量索引数 -- FTS 索引数 - -### 8.3 初始化索引 - -1. 点击 **"初始化索引"** 按钮 -2. 选择索引模式： - | 模式 | 说明 | - |------|------| - | FTS | 全文搜索，速度快 | - | 向量 | 语义搜索，需要嵌入模型 | - | 混合 | FTS + 向量，功能最全 | -3. 选择要索引的语言/文件类型 -4. 点击 **"开始索引"** -5. 查看进度条和实时日志 - -### 8.4 清理索引 - -#### 清理当前项目 -1. 点击 **"清理项目索引"** 按钮 -2. 确认操作 -3. 当前项目索引被删除 - -#### 清理所有索引 -1. 点击 **"清理所有索引"** 按钮 -2. 输入确认文字 -3. 所有索引被删除 - -### 8.5 语义依赖管理 - -#### 检查状态 -- 显示 Python 环境状态 -- 显示已安装的依赖包 - -#### 安装依赖 -1. 点击 **"安装语义依赖"** 按钮 -2. 等待安装完成 -3. 查看安装日志 - -### 8.6 嵌入模型管理 - -#### 查看模型 -- 列出可用的嵌入模型 -- 显示已下载/未下载状态 - -#### 下载模型 -1. 点击未下载模型的 **"下载"** 按钮 -2. 等待下载完成 -3. 模型可用于向量索引 - -#### 删除模型 -1. 点击已下载模型的 **"删除"** 按钮 -2. 确认删除 -3. 模型文件被移除 - -### 8.7 测试搜索 - -1. 在测试区输入搜索查询 -2. 选择搜索模式： - - `auto`: 自动选择 - - `hybrid`: 混合搜索 - - `exact`: 精确匹配 - - `ripgrep`: 文本搜索 -3. 点击 **"搜索"** -4. 查看搜索结果 - ---- - -## 通用操作说明 - -### 键盘快捷键 - -| 快捷键 | 功能 | -|--------|------| -| `Escape` | 关闭模态框/侧边栏 | -| `Ctrl+R` / `Cmd+R` | 刷新数据 | - -### 主题与语言切换 - -| 操作 | 位置 | -|------|------| -| 切换主题 | 顶部操作栏太阳/月亮图标 | -| 切换语言 | 顶部操作栏 EN/ZH 按钮 | - -### 错误处理 - -| 错误类型 | 处理方式 | -|----------|----------| -| 网络错误 | 检查连接，点击刷新重试 | -| 权限错误 | 检查文件/目录权限 | -| 验证错误 | 检查表单必填字段 | -| 超时错误 | 增加超时设置或分批操作 | - -### WebSocket 连接 - -- **自动重连**: 断开后自动尝试重连 -- **心跳保活**: 定期发送心跳保持连接 -- **状态指示**: 页脚显示连接状态 - ---- - -## 相关文档 - -- [DASHBOARD_GUIDE.md](DASHBOARD_GUIDE.md) - Dashboard 用户指南 -- [COMMAND_REFERENCE.md](COMMAND_REFERENCE.md) - 命令参考 -- [GETTING_STARTED_CN.md](GETTING_STARTED_CN.md) - 快速入门 - ---- - -**CCW Dashboard** - Claude Code Workflow 可视化控制中心操作手册 diff --git a/DASHBOARD_OPERATIONS_EN.md b/DASHBOARD_OPERATIONS_EN.md deleted file mode 100644 index 74bc129c..00000000 --- a/DASHBOARD_OPERATIONS_EN.md +++ /dev/null @@ -1,508 +0,0 @@ -# CCW Dashboard Operations Guide - -**Version**: 6.2.0 -**Updated**: 2025-12-20 - -This document provides detailed step-by-step operation instructions for each CCW Dashboard view. - ---- - -## Table of Contents - -1. [Home Overview Operations](#1-home-overview-operations) -2. [Session Detail Operations](#2-session-detail-operations) -3. [CLI Manager Operations](#3-cli-manager-operations) -4. [Core Memory Operations](#4-core-memory-operations) -5. [MCP Server Management Operations](#5-mcp-server-management-operations) -6. [Hook Manager Operations](#6-hook-manager-operations) -7. [Skills Manager Operations](#7-skills-manager-operations) -8. [CodexLens Index Management Operations](#8-codexlens-index-management-operations) - ---- - -## 1. Home Overview Operations - -### 1.1 Entry Point -- Displayed automatically after Dashboard launch -- Click **"Overview"** in the sidebar navigation - -### 1.2 Project Switching -1. Click the **Project Path Selector** in the top action bar -2. Select from recent projects dropdown, or click **"Browse..."** to select a new project -3. System automatically loads the new project data - -### 1.3 Data Refresh -- Click the **Refresh Button** (🔄) in the top action bar -- Or wait for WebSocket automatic push updates - -### 1.4 Active Session Carousel -- Auto-rotates through currently active workflow sessions -- Click a session card to enter session details - -### 1.5 Statistics Cards -Displays the following statistics: -- Total sessions -- Active sessions -- Archived sessions -- Task completion rate - ---- - -## 2. Session Detail Operations - -### 2.1 Entry Point -- Click a session card from the home page -- Click from sidebar **"Sessions"** > **"All/Active/Archived"** list - -### 2.2 Session List Operations - -| Operation | Steps | -|-----------|-------| -| Filter sessions | Click **"All/Active/Archived"** tabs to switch | -| Search sessions | Enter session ID or description in search box | -| View details | Click session row to expand details | - -### 2.3 Session Detail Panel - -#### Basic Information Area -- Session ID, creation time, status -- Session description and objectives - -#### Task List Area -| Operation | Description | -|-----------|-------------| -| View tasks | Tasks displayed as list with status icons | -| Expand task | Click task row to view detailed information | -| Task status | 🔵 Pending / 🟡 In Progress / 🟢 Completed / 🔴 Failed | - -#### Action Buttons -| Button | Function | -|--------|----------| -| **Archive** | Mark session as archived | -| **Delete** | Delete session (requires confirmation) | -| **Export** | Export session data as JSON | - -### 2.4 Task Drawer - -Detail drawer opened after clicking a task: - -| Area | Content | -|------|---------| -| Header | Task title, status badge | -| Context | Related files list, dependencies | -| Execution log | Real-time execution output (WebSocket push) | -| Actions | Retry, Skip, Mark complete | - ---- - -## 3. CLI Manager Operations - -### 3.1 Entry Point -Sidebar **"Project"** > **"Status"** - -### 3.2 CLI Tool Status Panel - -#### Tool Status Cards -Each tool (Gemini/Qwen/Codex) displays: -- Installation status: ✅ Installed / ❌ Not installed -- Version information -- Default model configuration - -#### Set Default Tool -1. Click **"Set as Default"** button on tool card -2. Confirm selection - -#### Model Configuration -1. Click **"Configure"** button -2. In the modal dialog, set: - - Primary Model - - Fallback Model -3. Click **"Save"** - -### 3.3 Install/Uninstall Wizard - -#### Install Tool -1. Click **"Install"** button on uninstalled tool -2. Follow wizard steps: - - Confirm system requirements - - Enter API key (if required) - - Select installation options -3. Wait for installation to complete - -#### Uninstall Tool -1. Click **"Uninstall"** button on installed tool -2. Confirm uninstall operation -3. Wait for uninstall to complete - -### 3.4 Execution History - -Sidebar **"Project"** > **"History"** - -| Operation | Description | -|-----------|-------------| -| View records | List displays execution time, tool, prompt summary | -| Expand details | Click record to view full input/output | -| Resume session | Click **"Continue"** button to resume with `--resume` | -| Copy command | Click **"Copy"** icon to copy execution command | - ---- - -## 4. Core Memory Operations - -### 4.1 Entry Point -Sidebar **"Memory"** > **"Core Memory"** - -### 4.2 Memory List View - -#### View Memories -- Memory entries displayed as cards -- Includes: title, summary, tags, creation time - -#### Create Memory -1. Click **"+ New Memory"** button -2. Fill in the form: - | Field | Description | - |-------|-------------| - | Title | Memory title (required) | - | Content | Memory body (Markdown supported) | - | Tags | Category tags (comma-separated) | - | Priority | High/Medium/Low | -3. Click **"Save"** - -#### Edit Memory -1. Click **"Edit"** icon on memory card -2. Modify content -3. Click **"Save"** - -#### Archive/Delete -- **Archive**: Click **"Archive"** icon, memory moves to archive list -- **Delete**: Click **"Delete"** icon, confirm for permanent deletion - -### 4.3 Cluster View - -Switch to **"Clusters"** tab - -#### View Clusters -- Auto-clustered session groups displayed -- Each cluster shows: name, member count, creation time - -#### Auto Clustering -1. Click **"Auto Cluster"** button -2. Set parameters: - | Parameter | Description | - |-----------|-------------| - | Similarity Threshold | 0.0-1.0, default 0.7 | - | Minimum Members | Minimum sessions per cluster | -3. Click **"Execute"** -4. Wait for clustering to complete - -#### Cluster Management -| Operation | Steps | -|-----------|-------| -| View members | Click cluster card to expand member list | -| Rename | Click cluster name to edit | -| Merge clusters | Select multiple clusters, click **"Merge"** | -| Delete cluster | Click **"Delete"** icon (members not deleted) | - -### 4.4 Embedding Management - -#### View Embedding Status -- Shows count of memories with generated embeddings -- Shows count of memories pending embedding - -#### Generate Embeddings -1. Click **"Generate Embeddings"** button -2. Select scope: - - All unembedded - - Selected memories -3. Wait for generation to complete (progress bar displayed) - ---- - -## 5. MCP Server Management Operations - -### 5.1 Entry Point -Sidebar **"Config"** > **"MCP Servers"** - -### 5.2 Server List - -#### View Servers -- List displays configured servers -- Each row shows: name, type, status, config source - -#### Status Indicators -- 🟢 Running -- 🔴 Stopped -- 🟡 Starting - -### 5.3 Create Server - -#### Manual Creation -1. Click **"+ Add Server"** button -2. Fill in the form: - | Field | Description | - |-------|-------------| - | Name | Server identifier (required) | - | Command | Start command (e.g., `node`) | - | Arguments | Command arguments array | - | Environment Variables | KEY=VALUE format | - | Config Scope | Project / Global | -3. Click **"Save"** - -#### Install from Template -1. Click **"Templates"** tab -2. Browse available templates -3. Click template's **"Install"** button -4. Confirm or modify configuration -5. Click **"Confirm Install"** - -### 5.4 Edit/Delete - -| Operation | Steps | -|-----------|-------| -| Edit | Click **"Edit"** icon → Modify config → Save | -| Delete | Click **"Delete"** icon → Confirm deletion | -| Enable/Disable | Toggle status switch | - -### 5.5 Configuration File Locations - -| Scope | File Path | -|-------|-----------| -| Project | `.mcp.json` | -| Global | `~/.claude/settings.json` | - ---- - -## 6. Hook Manager Operations - -### 6.1 Entry Point -Sidebar **"Config"** > **"Hooks"** - -### 6.2 Hook List - -#### View by Type -- **PreToolUse**: Triggered before tool use -- **PostToolUse**: Triggered after tool use -- **Notification**: Notification hooks - -#### List Information -Each hook displays: name, type, matching tool, command summary - -### 6.3 Create Hook - -#### Wizard Mode -1. Click **"+ Add Hook"** button -2. Select hook type -3. Fill in configuration: - | Field | Description | - |-------|-------------| - | Name | Hook identifier | - | Matcher | Tool name to match (supports wildcard `*`) | - | Command | Shell command to execute | - | Timeout | Command timeout (milliseconds) | - | Scope | Project / Global | -4. Click **"Save"** - -#### Create from Template -1. Click **"Templates"** tab -2. Select preset template (e.g., format check, security scan) -3. Click **"Use Template"** -4. Modify configuration as needed -5. Click **"Save"** - -### 6.4 Edit/Delete - -| Operation | Steps | -|-----------|-------| -| Edit | Click hook row → Modify config → Save | -| Delete | Click **"Delete"** icon → Confirm | -| Enable/Disable | Toggle status switch | - -### 6.5 Configuration File Locations - -| Scope | File Path | -|-------|-----------| -| Project | `.claude/settings.local.json` | -| Global | `~/.claude/settings.json` | - ---- - -## 7. Skills Manager Operations - -### 7.1 Entry Point -Sidebar **"Memory"** > **"Skills"** - -### 7.2 Skills List - -#### Category View -- **Project Skills**: Skills in `./.claude/skills/` directory -- **User Skills**: Skills in `~/.claude/skills/` directory - -#### Skill Card Information -- Skill name -- Description -- Version number -- Tool count -- Support file count - -### 7.3 View Skill Details - -1. Click skill card -2. Detail panel displays: - - Full description - - Included tools list - - Support files list - - Dependency information - -### 7.4 Create Skill - -#### Import from Folder -1. Click **"+ Import Skill"** button -2. Select directory containing skill files -3. Confirm skill information -4. Click **"Import"** - -#### Generate via CLI -1. Click **"+ Generate Skill"** button -2. Enter skill description -3. Select generation options: - - Target directory (Project/User) - - Included capabilities -4. Click **"Generate"** -5. Wait for AI generation to complete - -### 7.5 Delete Skill - -1. Click **"Delete"** icon on skill card -2. Confirm delete operation -3. Skill files will be removed - ---- - -## 8. CodexLens Index Management Operations - -### 8.1 Entry Point -Sidebar **"Project"** > **"Status"** → CodexLens panel - -### 8.2 Index Status - -#### Status Indicators -| Status | Description | -|--------|-------------| -| ✅ Indexed | Project has established index | -| ⚠️ Outdated | Index needs update | -| ❌ Not indexed | Project has no index | - -#### Index Statistics -- Total index size -- Project count -- Vector index count -- FTS index count - -### 8.3 Initialize Index - -1. Click **"Initialize Index"** button -2. Select index mode: - | Mode | Description | - |------|-------------| - | FTS | Full-text search, fast | - | Vector | Semantic search, requires embedding model | - | Hybrid | FTS + Vector, full features | -3. Select languages/file types to index -4. Click **"Start Indexing"** -5. View progress bar and real-time logs - -### 8.4 Clean Index - -#### Clean Current Project -1. Click **"Clean Project Index"** button -2. Confirm operation -3. Current project index is deleted - -#### Clean All Indexes -1. Click **"Clean All Indexes"** button -2. Enter confirmation text -3. All indexes are deleted - -### 8.5 Semantic Dependency Management - -#### Check Status -- Shows Python environment status -- Shows installed dependency packages - -#### Install Dependencies -1. Click **"Install Semantic Dependencies"** button -2. Wait for installation to complete -3. View installation logs - -### 8.6 Embedding Model Management - -#### View Models -- Lists available embedding models -- Shows downloaded/not downloaded status - -#### Download Model -1. Click **"Download"** button on undownloaded model -2. Wait for download to complete -3. Model available for vector indexing - -#### Delete Model -1. Click **"Delete"** button on downloaded model -2. Confirm deletion -3. Model files are removed - -### 8.7 Test Search - -1. Enter search query in test area -2. Select search mode: - - `auto`: Auto select - - `hybrid`: Hybrid search - - `exact`: Exact match - - `ripgrep`: Text search -3. Click **"Search"** -4. View search results - ---- - -## Common Operations - -### Keyboard Shortcuts - -| Shortcut | Function | -|----------|----------| -| `Escape` | Close modal/sidebar | -| `Ctrl+R` / `Cmd+R` | Refresh data | - -### Theme & Language Switching - -| Operation | Location | -|-----------|----------| -| Switch theme | Sun/moon icon in top action bar | -| Switch language | EN/ZH button in top action bar | - -### Error Handling - -| Error Type | Resolution | -|------------|------------| -| Network error | Check connection, click refresh to retry | -| Permission error | Check file/directory permissions | -| Validation error | Check required form fields | -| Timeout error | Increase timeout settings or batch operations | - -### WebSocket Connection - -- **Auto reconnect**: Automatically attempts reconnection after disconnect -- **Heartbeat keepalive**: Periodic heartbeat to maintain connection -- **Status indicator**: Connection status shown in footer - ---- - -## Related Documentation - -- [DASHBOARD_GUIDE.md](DASHBOARD_GUIDE.md) - Dashboard User Guide -- [COMMAND_REFERENCE.md](COMMAND_REFERENCE.md) - Command Reference -- [GETTING_STARTED.md](GETTING_STARTED.md) - Getting Started Guide - ---- - -**CCW Dashboard** - Claude Code Workflow Visual Control Center Operations Manual diff --git a/EMBEDDINGS_IMPROVEMENTS_SUMMARY.md b/EMBEDDINGS_IMPROVEMENTS_SUMMARY.md deleted file mode 100644 index 2594ad0a..00000000 --- a/EMBEDDINGS_IMPROVEMENTS_SUMMARY.md +++ /dev/null @@ -1,167 +0,0 @@ -# CodexLens Embeddings Statistics Improvements - -## Summary - -Improved the CodexLens `init` and `status` commands to return comprehensive embeddings statistics, making it easy for users to understand embeddings coverage. - -## Changes Made - -### 1. Updated `init` command (Task 1) - -**File**: `codex-lens/src/codexlens/cli/commands.py` (lines 142-219) - -**Key Changes**: -- Changed from `generate_embeddings()` to `generate_embeddings_recursive()` -- Now processes all `_index.db` files recursively in the index tree -- Passes `index_root` (directory) instead of `index_path` (file) -- Returns comprehensive coverage statistics after generation - -**Imports Added**: -```python -from codexlens.cli.embedding_manager import generate_embeddings_recursive, get_embeddings_status -``` - -**Result Structure**: -```json -{ - "embeddings": { - "generated": true, - "total_indexes": 26, - "total_files": 303, - "files_with_embeddings": 303, - "coverage_percent": 100.0, - "total_chunks": 500 - } -} -``` - -**Console Output**: -- Shows files processed count -- Shows total chunks created -- Shows indexes processed (successful/total) - -### 2. Updated `status` command (Task 2) - -**File**: `codex-lens/src/codexlens/cli/commands.py` (lines 642-713) - -**Key Changes**: -- Added embeddings coverage check using `get_embeddings_status()` -- Updates `vector_search` feature flag based on coverage (>= 50%) -- Includes embeddings data in JSON output -- Displays embeddings statistics in console output - -**Imports Added**: -```python -from codexlens.cli.embedding_manager import get_embeddings_status -``` - -**Result Structure**: -```json -{ - "embeddings": { - "total_indexes": 26, - "total_files": 303, - "files_with_embeddings": 303, - "files_without_embeddings": 0, - "coverage_percent": 100.0, - "total_chunks": 500, - "indexes_with_embeddings": 26, - "indexes_without_embeddings": 0 - }, - "features": { - "exact_fts": true, - "fuzzy_fts": true, - "hybrid_search": true, - "vector_search": true // true when coverage >= 50% - } -} -``` - -**Console Output**: -``` -Search Backends: - Exact FTS: ✓ (unicode61) - Fuzzy FTS: ✓ (trigram) - Hybrid Search: ✓ (RRF fusion) - Vector Search: ✓ (embeddings available) - -Embeddings Coverage: - Total Indexes: 26 - Total Files: 303 - Files with Embeddings: 303 - Coverage: 100.0% - Total Chunks: 500 -``` - -## Benefits - -1. **Transparency**: Users can now see exactly what embeddings were generated -2. **Coverage Visibility**: Clear percentage showing embeddings coverage across all files -3. **Recursive Processing**: All index databases in the tree are processed, not just the root -4. **Feature Detection**: Vector search is automatically enabled when coverage is sufficient (>= 50%) -5. **Comprehensive Stats**: Shows total indexes, files, chunks, and coverage percentage - -## Backward Compatibility - -- All changes are backward compatible -- Gracefully handles cases where embeddings are not available -- ImportError handling for when embedding_manager is not available -- Existing JSON output structure is extended, not changed - -## Testing - -Created test script: `test_embeddings_improvements.py` - -Tests verify: -- Init command reports embeddings statistics correctly -- Status command shows embeddings coverage -- JSON output includes all required fields -- Console output displays statistics properly - -## Usage Examples - -### Init with embeddings -```bash -codexlens init /path/to/project --json -# Returns comprehensive embeddings statistics -``` - -### Check status -```bash -codexlens status --json -# Shows embeddings coverage and feature availability -``` - -### Init without embeddings -```bash -codexlens init /path/to/project --no-embeddings --json -# Returns embeddings: {"generated": false, "error": "Skipped (--no-embeddings)"} -``` - -## Files Modified - -1. `codex-lens/src/codexlens/cli/commands.py` - Updated init and status commands - -## Implementation Details - -### Init Command Flow -1. Build index tree as before -2. If `--no-embeddings` not set: - - Call `generate_embeddings_recursive(index_root)` instead of `generate_embeddings(index_path)` - - After generation, call `get_embeddings_status(index_root)` to get coverage stats - - Include comprehensive statistics in result -3. Return result with embeddings coverage data - -### Status Command Flow -1. Collect index statistics as before -2. Call `get_embeddings_status(index_root)` to check embeddings -3. Set `vector_search` feature flag based on coverage >= 50% -4. Include embeddings info in JSON output -5. Display embeddings statistics in console output - -## Error Handling - -- Handles ImportError when embedding_manager not available -- Handles cases where embeddings don't exist (returns 0% coverage) -- Graceful fallback if get_embeddings_status fails -- Debug logging for failed operations diff --git a/MCP_FINAL_FIX.md b/MCP_FINAL_FIX.md deleted file mode 100644 index 855eec01..00000000 --- a/MCP_FINAL_FIX.md +++ /dev/null @@ -1,248 +0,0 @@ -# CCW MCP 工具安装问题 - 最终修复报告 - -## 🎯 通过 Gemini AI 发现的关键问题 - -### 问题 4: 事件监听器注册失败 ⚠️ **根本原因** ✅ 已修复 -**文件**: `views/mcp-manager.js` Line 1407 -**严重性**: Critical - 导致所有按钮完全无响应 -**原因**: 使用 `querySelector` 只返回第一个匹配元素，如果 DOM 中有多个元素或选择器匹配错误，事件监听器会附加到错误的元素上 -**症状**: 按钮点击无任何反应，控制台无错误，调试困难 - -**修复前**: -```javascript -const btn = document.querySelector(`button[data-action="${action}"]`); -if (btn) { - btn.addEventListener('click', async (e) => { - e.preventDefault(); - await handler(); - }); -} -``` - -**修复后**: -```javascript -const btns = document.querySelectorAll(`button[data-action="${action}"]`); - -if (btns.length > 0) { - console.log(`[MCP] Attaching listener to ${action} (${btns.length} button(s) found)`); - btns.forEach(btn => { - btn.addEventListener('click', async (e) => { - e.preventDefault(); - console.log(`[MCP] Button clicked: ${action}`); - try { - await handler(); - } catch (err) { - console.error(`[MCP] Error executing handler for ${action}:`, err); - if (typeof showRefreshToast === 'function') { - showRefreshToast(`Action failed: ${err.message}`, 'error'); - } - } - }); - }); -} else { - console.warn(`[MCP] No buttons found for action: ${action}`); -} -``` - -**修复优势**: -1. ✅ 使用 `querySelectorAll` 确保所有匹配按钮都绑定事件 -2. ✅ 添加详细的控制台日志，便于调试 -3. ✅ 添加错误捕获和用户友好的错误提示 -4. ✅ 添加警告日志，发现选择器不匹配问题 - ---- - -### 问题 5: MCP 计数显示错误 ✅ 已修复 -**文件**: `components/mcp-manager.js` Line 398 -**严重性**: Medium - 显示 2/2 但实际只有 1 个服务器 -**原因**: 路径格式不一致 - `loadMcpConfig` 使用 `\\`，`updateMcpBadge` 使用 `/` - -**修复前**: -```javascript -function updateMcpBadge() { - const badge = document.getElementById('badgeMcpServers'); - if (badge) { - const currentPath = projectPath; // Keep original format (forward slash) - const projectData = mcpAllProjects[currentPath]; - // ... - } -} -``` - -**修复后**: -```javascript -function updateMcpBadge() { - const badge = document.getElementById('badgeMcpServers'); - if (badge) { - // IMPORTANT: Use same path normalization as loadMcpConfig - const currentPath = projectPath.replace(/\//g, '\\'); - const projectData = mcpAllProjects[currentPath]; - // ... - console.log('[MCP Badge]', { currentPath, totalServers, enabledServers, disabledServers }); - badge.textContent = `${enabledServers}/${totalServers}`; - } -} -``` - ---- - -## 📊 完整问题清单 - -| # | 问题 | 文件 | 严重性 | 状态 | -|---|------|------|--------|------| -| 1 | API 端点不匹配 | components/mcp-manager.js | Critical | ✅ 已修复 | -| 2 | 未定义函数引用 | views/mcp-manager.js | High | ✅ 已修复 | -| 3 | 全局作用域污染 | views/mcp-manager.js | Medium | ✅ 已修复 | -| 4 | **querySelector 单选器失效** | views/mcp-manager.js | **Critical** | ✅ 已修复 | -| 5 | MCP 计数路径不一致 | components/mcp-manager.js | Medium | ✅ 已修复 | - ---- - -## 🔍 Gemini AI 分析价值 - -Gemini AI 深度分析提供了关键洞察： - -1. **执行流程追踪**: 确认 `attachMcpEventListeners()` 在 DOM 更新后立即调用 -2. **选择器匹配验证**: 发现 `data-action` 属性完全匹配 -3. **根本原因识别**: 定位到 `querySelector` vs `querySelectorAll` 的关键差异 -4. **静默失败诊断**: 指出缺少日志导致调试困难 -5. **修复建议**: 提供完整的代码修复方案，包括错误处理 - ---- - -## 🧪 测试验证步骤 - -### 1. 重启服务 -```bash -cd D:\Claude_dms3\ccw -npm run dev -``` - -### 2. 打开浏览器控制台 -- 访问 `http://localhost:3456` -- 按 `F12` 打开控制台 -- **现在应该能看到调试日志**: - ``` - [MCP] Attaching listener to install-ccw-workspace (1 button(s) found) - [MCP] Attaching listener to install-ccw-global (1 button(s) found) - [MCP] Attaching listener to update-ccw-workspace (1 button(s) found) - [MCP] Attaching listener to update-ccw-global (1 button(s) found) - [MCP] Attaching listener to install-ccw-codex (1 button(s) found) - ``` - -### 3. 点击按钮测试 -点击任何 CCW Tools 按钮，应该看到： -``` -[MCP] Button clicked: install-ccw-workspace -Installing CCW Tools MCP to workspace... -``` - -如果失败，会看到： -``` -[MCP] Error executing handler for install-ccw-workspace: <错误详情> -``` - -### 4. 验证 MCP 计数 -- 导航到 MCP Manager -- 检查左侧导航栏的 MCP 徽章 -- **现在应该显示正确的计数** (1/1 而不是 2/2) -- 控制台会显示: - ``` - [MCP Badge] { currentPath: 'D:\\dongdiankaifa9', totalServers: 1, enabledServers: 1, disabledServers: [] } - ``` - ---- - -## ✅ 预期结果 - -### 所有按钮现在应该正常工作 - -#### 1. 工作空间安装/更新 -- **位置**: CCW Tools MCP 卡片 -- **按钮**: "安装到工作空间" / "在工作空间更新" -- **预期**: 点击后显示加载提示，成功后显示成功消息 - -#### 2. 全局安装/更新 -- **位置**: CCW Tools MCP 卡片 -- **按钮**: "Install to global" / "Update Globally" -- **预期**: 更新 `~/.claude.json` - -#### 3. Codex 安装 -- **位置**: Codex 模式的 CCW Tools MCP 卡片 -- **按钮**: "Install" / "Update" -- **预期**: 更新 `~/.codex/config.toml` - -#### 4. 从其他项目安装 -- **位置**: "Available from Other Projects" 部分 -- **预期**: 弹出配置类型选择对话框 - -#### 5. MCP 计数显示 -- **位置**: 左侧导航栏 MCP Manager 徽章 -- **预期**: 显示正确的启用/总计数量 (例如 1/1) - ---- - -## 🐛 调试指南 - -### 如果按钮仍然无响应 - -#### 检查控制台日志 -如果看不到 `[MCP] Attaching listener` 日志： -- ❌ `attachMcpEventListeners()` 函数没有被调用 -- 解决方法: 检查 `renderMcpManager()` 是否正确调用了该函数 - -#### 如果看到 "No buttons found" -``` -[MCP] No buttons found for action: install-ccw-workspace -``` -- ❌ `data-action` 属性不匹配或按钮未渲染 -- 解决方法: 检查 HTML 生成逻辑，确保 `data-action` 属性正确设置 - -#### 如果看到点击日志但无反应 -``` -[MCP] Button clicked: install-ccw-workspace -``` -但之后无进一步输出： -- ❌ 函数执行被阻塞或抛出未捕获的错误 -- 解决方法: 检查 `installCcwToolsMcp()` 函数实现 - -#### 如果 MCP 计数仍然错误 -控制台应该显示: -``` -[MCP Badge] { currentPath: '...', totalServers: 1, enabledServers: 1, disabledServers: [] } -``` -- 如果 `currentPath` 格式错误 (例如包含 `/` 而不是 `\\`)，说明路径规范化失败 -- 如果 `totalServers` 不正确，检查 `mcpAllProjects` 数据结构 - ---- - -## 📋 修复文件清单 - -``` -D:\Claude_dms3\ccw\src\templates\dashboard-js\components\mcp-manager.js - - Line 398: updateMcpBadge 路径规范化修复 - - Line 404: 添加调试日志 - -D:\Claude_dms3\ccw\src\templates\dashboard-js\views\mcp-manager.js - - Line 1407-1420: querySelector → querySelectorAll + 完整错误处理 -``` - ---- - -## 🎯 关键收获 - -1. **工具链选择**: Gemini AI 在执行流程追踪和根本原因分析上表现出色 -2. **调试友好**: 添加详细日志是诊断"静默失败"的关键 -3. **健壮性设计**: `querySelectorAll` + 错误捕获 > 简单的 `querySelector` -4. **路径规范化**: 在 Windows 系统上，路径格式必须一致（统一使用 `\\`） - ---- - -## 🚀 下一步 - -重启服务后测试所有按钮功能。如果仍有问题，请提供： -1. 完整的浏览器控制台输出（包括 `[MCP]` 前缀的所有日志） -2. Network 标签中的 API 请求详情 -3. 具体点击的按钮和操作步骤 - -所有修复已合并到代码库，重新编译完成。 diff --git a/MCP_FIX_SUMMARY.md b/MCP_FIX_SUMMARY.md deleted file mode 100644 index 86b5b358..00000000 --- a/MCP_FIX_SUMMARY.md +++ /dev/null @@ -1,227 +0,0 @@ -# CCW MCP 工具安装问题修复总结 - -## 📊 问题发现 - -通过 Gemini AI 深度分析，发现了 3 个导致 MCP 安装按钮无响应的关键问题： - -### 🔴 问题 1: API 端点不匹配（Critical） -- **文件**: `ccw/src/templates/dashboard-js/components/mcp-manager.js` -- **影响**: 全局安装/更新按钮完全无响应 -- **根本原因**: 前端调用 `/api/mcp-add-global`，后端定义 `/api/mcp-add-global-server` -- **修复位置**: - - Line 960: `installCcwToolsMcp()` 全局安装 - - Line 1024: `updateCcwToolsMcp()` 全局更新 - -### 🔴 问题 2: 未定义的函数引用（High） -- **文件**: `ccw/src/templates/dashboard-js/views/mcp-manager.js` -- **影响**: "从其他项目安装" 按钮抛出 ReferenceError -- **根本原因**: 调用不存在的 `installMcpToProject`，正确名称是 `copyMcpServerToProject` -- **修复位置**: - - Line 1352: Install to project 按钮事件处理 - - Line 1847: 模板安装逻辑 - -### 🟡 问题 3: 全局作用域污染（Medium） -- **文件**: `ccw/src/templates/dashboard-js/views/mcp-manager.js` -- **影响**: CCW Tools 工作空间/全局更新按钮可能无响应 -- **根本原因**: 使用内联 `onclick` 属性，函数不在全局作用域 -- **修复位置**: - - Line 239: Codex 安装按钮 - - Lines 424, 430: 工作空间/全局更新按钮 - - Lines 437, 443: 工作空间/全局安装按钮 - - Lines 1397-1413: 新增健壮的事件监听器 - -## ✅ 已修复的文件 - -``` -D:\Claude_dms3\ccw\src\templates\dashboard-js\components\mcp-manager.js - - Line 960: API 端点修正 (/api/mcp-add-global-server) - - Line 1024: API 端点修正 (/api/mcp-add-global-server) - -D:\Claude_dms3\ccw\src\templates\dashboard-js\views\mcp-manager.js - - Line 239: onclick → data-action (Codex) - - Line 424: onclick → data-action (update workspace) - - Line 430: onclick → data-action (update global) - - Line 437: onclick → data-action (install workspace) - - Line 443: onclick → data-action (install global) - - Line 1352: installMcpToProject → copyMcpServerToProject - - Line 1397-1413: 新增 CCW Tools 事件监听器 - - Line 1847: installMcpToProject → copyMcpServerToProject -``` - -## 🔧 修复方案详解 - -### 方案 1: API 端点统一 -```javascript -// 修复前 -fetch('/api/mcp-add-global', { ... }) // ❌ 404 Not Found - -// 修复后 -fetch('/api/mcp-add-global-server', { ... }) // ✅ 匹配后端路由 -``` - -### 方案 2: 函数名称修正 -```javascript -// 修复前 -await installMcpToProject(serverName, serverConfig); // ❌ ReferenceError - -// 修复后 -await copyMcpServerToProject(serverName, serverConfig); // ✅ 正确函数 -``` - -### 方案 3: 事件处理重构 -```html - - - - - -``` - -```javascript -// 新增事件监听器 -const ccwActions = { - 'update-ccw-workspace': () => updateCcwToolsMcp('workspace'), - 'update-ccw-global': () => updateCcwToolsMcp('global'), - 'install-ccw-workspace': () => installCcwToolsMcp('workspace'), - 'install-ccw-global': () => installCcwToolsMcp('global'), - 'install-ccw-codex': () => installCcwToolsMcpToCodex() -}; - -Object.entries(ccwActions).forEach(([action, handler]) => { - const btn = document.querySelector(`button[data-action="${action}"]`); - if (btn) { - btn.addEventListener('click', async (e) => { - e.preventDefault(); - await handler(); - }); - } -}); -``` - -## 🧪 测试场景 - -### ✅ 现在应该正常工作的按钮 - -#### 1. CCW Tools 工作空间安装/更新 -- **位置**: MCP Manager → CCW Tools MCP 卡片 -- **按钮**: "Install to Workspace" / "Update in Workspace" -- **测试步骤**: - 1. 选择至少一个工具（勾选复选框） - 2. 点击按钮 - 3. **预期结果**: 提示 "Installing/Updating CCW Tools MCP to workspace..." - 4. 成功后显示: "CCW Tools installed/updated to workspace (N tools)" - -#### 2. CCW Tools 全局安装/更新 -- **位置**: MCP Manager → CCW Tools MCP 卡片 -- **按钮**: "Install Globally" / "Update Globally" -- **测试步骤**: - 1. 选择至少一个工具 - 2. 点击按钮 - 3. **预期结果**: 提示 "Installing/Updating CCW Tools MCP globally..." - 4. 成功后显示: "CCW Tools installed/updated globally (N tools)" - -#### 3. Codex 安装/更新 -- **位置**: MCP Manager → Codex 模式 → CCW Tools MCP 卡片 -- **按钮**: "Install" / "Update" -- **测试步骤**: - 1. 切换到 Codex 模式 - 2. 选择工具 - 3. 点击按钮 - 4. **预期结果**: 成功提示 - -#### 4. 从其他项目安装 -- **位置**: MCP Manager → Available from Other Projects 部分 -- **按钮**: 服务器卡片上的文本按钮或图标按钮 -- **测试步骤**: - 1. 找到其他项目的 MCP 服务器 - 2. 点击 "Install to Project" 或文件夹图标 - 3. **预期结果**: 弹出配置类型选择对话框 - 4. 选择后成功安装 - -## 📋 验证清单 - -在重启服务后，请逐项验证： - -- [ ] **CCW Tools 工作空间安装** - 点击按钮有反应，控制台无错误 -- [ ] **CCW Tools 工作空间更新** - 修改工具选择后可更新 -- [ ] **CCW Tools 全局安装** - 安装到 ~/.claude.json -- [ ] **CCW Tools 全局更新** - 可更新全局配置 -- [ ] **Codex 模式安装** - 安装到 ~/.codex/config.toml -- [ ] **从其他项目安装** - 文本按钮工作正常 -- [ ] **从其他项目安装** - 图标按钮工作正常 -- [ ] **浏览器控制台** - 无 ReferenceError 或 404 错误 - -## 🚀 启动测试 - -### 1. 重启服务（必须） -```bash -cd D:\Claude_dms3\ccw -npm run dev -``` - -### 2. 打开浏览器控制台 -- 访问: `http://localhost:3456` -- 按 `F12` 打开开发者工具 -- 切换到 **Console** 标签 - -### 3. 逐个测试按钮 -按照上述测试场景，逐个点击按钮并观察： -- 浏览器控制台输出 -- Network 标签中的 API 请求 -- 页面上的成功/失败提示 - -## 📊 API 端点映射表 - -| 前端调用 | 后端路由 | 状态 | -|---------|---------|------| -| `/api/mcp-add-global-server` | `/api/mcp-add-global-server` | ✅ 匹配 | -| `/api/mcp-copy-server` | `/api/mcp-copy-server` | ✅ 匹配 | -| `/api/codex-mcp-add` | `/api/codex-mcp-add` | ✅ 匹配 | -| `/api/mcp-config` | `/api/mcp-config` | ✅ 匹配 | -| `/api/mcp-toggle` | `/api/mcp-toggle` | ✅ 匹配 | - -## 🐛 如果仍有问题 - -### 检查项： -1. **服务是否重启？** 必须重启才能加载新代码 -2. **浏览器缓存？** 按 `Ctrl+Shift+R` 强制刷新 -3. **控制台错误？** 检查是否有 JavaScript 错误 -4. **Network 请求？** 查看 API 请求的状态码和响应 - -### 需要提供的调试信息： -- 浏览器控制台完整错误信息（截图或文本） -- Network 标签中失败请求的详情 -- CCW View 服务端控制台输出 -- 点击的具体按钮和操作步骤 - -## 📈 修复效果 - -| 问题 | 修复前 | 修复后 | -|-----|-------|-------| -| 全局安装按钮 | ❌ 404 错误 | ✅ 正常工作 | -| 全局更新按钮 | ❌ 404 错误 | ✅ 正常工作 | -| 工作空间安装 | ⚠️ 可能失效 | ✅ 稳定工作 | -| 工作空间更新 | ⚠️ 可能失效 | ✅ 稳定工作 | -| 从其他项目安装 | ❌ ReferenceError | ✅ 正常工作 | -| Codex 安装 | ⚠️ 可能失效 | ✅ 稳定工作 | - -## 🎯 技术细节 - -### Gemini 分析发现 -Gemini AI 通过执行流程追踪和代码模式分析，准确识别了： -1. 前后端 API 端点不一致 -2. 函数名称拼写错误导致的引用失败 -3. JavaScript 作用域问题导致的事件处理失效 - -### 修复优势 -- **健壮性提升**: 使用 `addEventListener` 替代内联 `onclick` -- **可维护性**: 函数名称统一，减少混淆 -- **调试友好**: 所有 API 调用端点与后端完全匹配 - -## 📝 修复日志 - -- **2025-12-17**: 初始问题报告 - 安装按钮无响应 -- **2025-12-17**: 发现 API 端点不匹配问题（问题 1） -- **2025-12-17**: Gemini 分析发现额外 2 个问题（问题 2、3） -- **2025-12-17**: 完成所有修复并重新编译 -- **2025-12-17**: 创建完整的测试和调试指南 diff --git a/MCP_INSTALL_DEBUG.md b/MCP_INSTALL_DEBUG.md deleted file mode 100644 index 2a87681d..00000000 --- a/MCP_INSTALL_DEBUG.md +++ /dev/null @@ -1,274 +0,0 @@ -# CCW MCP 工具安装问题调试指南 - -## 🎯 已修复的所有问题（完整清单） - -### 问题 1: API 端点不匹配 ✅ 已修复 -**位置**: `components/mcp-manager.js` -**原因**: 前端调用 `/api/mcp-add-global`，后端定义 `/api/mcp-add-global-server` -**修复**: -- Line 960: `installCcwToolsMcp()` - 全局安装端点已修正 -- Line 1024: `updateCcwToolsMcp()` - 全局更新端点已修正 - -### 问题 2: 未定义的函数引用 ✅ 已修复 -**位置**: `views/mcp-manager.js` -**原因**: 调用不存在的函数 `installMcpToProject`，正确函数名是 `copyMcpServerToProject` -**修复**: -- Line 1352: "Install to Project" 按钮事件处理已修正 -- Line 1847: 模板安装逻辑已修正 - -### 问题 3: 全局作用域污染导致按钮失效 ✅ 已修复 -**位置**: `views/mcp-manager.js` -**原因**: CCW Tools 按钮使用内联 `onclick` 属性，函数不在全局作用域导致无响应 -**修复**: -- Lines 239, 424, 430, 437, 443: 所有 `onclick` 改为 `data-action` 属性 -- Line 1397-1413: 添加健壮的事件监听器，使用 `addEventListener` - -## 测试步骤 - -### 1. 重启 CCW View 服务 - -**重要：** 必须重启服务才能加载修复后的代码。 - -```bash -# 方法 1: 直接运行 -cd D:\Claude_dms3\ccw -npm run dev - -# 方法 2: 使用 ccw 命令 -ccw view -``` - -### 2. 打开浏览器控制台 - -在浏览器中访问 `http://localhost:3456`，按 `F12` 打开开发者工具，切换到 **Console** 标签。 - -### 3. 测试安装按钮 - -#### 测试场景 A: 安装到工作空间 (Workspace) - -1. 导航到 **MCP Manager** 页面 -2. 找到 **CCW Tools MCP** 卡片 -3. 选择至少一个工具（勾选复选框） -4. 点击 **"Install to Workspace"** 按钮 -5. **观察控制台输出**： - - ✅ 成功：看到 "Installing CCW Tools MCP to workspace..." 提示 - - ❌ 失败：看到错误信息 - -#### 测试场景 B: 安装到全局 (Global) - -1. 选择至少一个工具 -2. 点击 **"Install Globally"** 按钮 -3. **观察控制台输出** - -#### 测试场景 C: 更新工具配置 - -1. 如果已安装，修改工具选择（添加或删除工具） -2. 点击 **"Update in Workspace"** 或 **"Update Globally"** 按钮 -3. **观察控制台输出** - -#### 测试场景 D: 从其他项目安装 - -1. 滚动到 **"Available from Other Projects"** 部分 -2. 找到想要安装的 MCP 服务器 -3. 点击 **"Install to Project"** 按钮 -4. **观察控制台输出** - -## 常见错误排查 - -### 错误 1: 502 Bad Gateway - -**原因：** CCW View 服务未正确运行 - -**解决方法：** -```bash -# 停止所有 node 进程 -taskkill /F /IM node.exe - -# 重新启动服务 -cd D:\Claude_dms3\ccw -npm run dev -``` - -### 错误 2: 404 Not Found (API 端点) - -**原因：** API 路由未正确加载 - -**解决方法：** -1. 确认已运行 `npm run build` -2. 检查 `dist/core/routes/mcp-routes.js` 是否存在 -3. 重启服务 - -### 错误 3: 按钮点击无反应 - -**检查清单：** -- [ ] 是否选择了至少一个工具？（如果没有选择，会显示警告） -- [ ] 浏览器控制台是否有 JavaScript 错误？ -- [ ] 网络标签是否显示 API 请求？ - -**调试方法：** -```javascript -// 在浏览器控制台执行以下命令测试函数是否可用 -typeof installCcwToolsMcp // 应该返回 "function" -typeof updateCcwToolsMcp // 应该返回 "function" -``` - -### 错误 4: Network Error / CORS Error - -**原因：** 前后端端口不一致 - -**解决方法：** -- 确认 CCW View 运行在正确的端口（默认 3456） -- 检查浏览器访问的 URL 是否正确 - -## 网络请求监控 - -在浏览器开发者工具的 **Network** 标签中，点击按钮后应该看到： - -### 成功的请求示例 - -**请求：** -``` -POST http://localhost:3456/api/mcp-add-global-server -``` - -**请求体：** -```json -{ - "serverName": "ccw-tools", - "serverConfig": { - "command": "npx", - "args": ["-y", "ccw-mcp"], - "env": { - "CCW_ENABLED_TOOLS": "write_file,edit_file,codex_lens,smart_search" - } - } -} -``` - -**响应：** -```json -{ - "success": true, - "serverName": "ccw-tools", - "scope": "global" -} -``` - -### 失败的请求示例 - -**状态码：** 404, 500, 502 - -**常见错误响应：** -```json -{ - "error": "serverName and serverConfig are required", - "status": 400 -} -``` - -## 日志检查 - -### 服务器日志 - -CCW View 服务运行时的控制台输出应该显示： -``` -CCW Dashboard running at http://localhost:3456 -``` - -如果看到错误，记录完整错误信息。 - -### 浏览器日志 - -打开控制台（F12）后，所有与 MCP 相关的日志会显示： -- API 请求和响应 -- JavaScript 错误 -- 网络错误 - -## 成功安装的验证 - -安装成功后，应该： -1. 看到成功提示：`"CCW Tools installed to workspace (4 tools)"` -2. MCP 卡片显示 ✓ 图标和工具数量 -3. 在项目根目录生成 `.mcp.json` 文件（workspace 安装） -4. 或在 `~/.claude.json` 中添加配置（global 安装） - -## 手动验证配置文件 - -### Workspace 安装 (.mcp.json) - -```bash -cat D:\Claude_dms3\.mcp.json -``` - -应该包含： -```json -{ - "mcpServers": { - "ccw-tools": { - "command": "npx", - "args": ["-y", "ccw-mcp"], - "env": { - "CCW_ENABLED_TOOLS": "write_file,edit_file,codex_lens,smart_search" - } - } - } -} -``` - -### Global 安装 (~/.claude.json) - -```bash -# Windows -type %USERPROFILE%\.claude.json - -# Linux/Mac -cat ~/.claude.json -``` - -应该包含 `mcpServers` 部分。 - -## 需要报告的信息 - -如果问题仍未解决，请提供： - -1. **浏览器控制台完整错误信息** -2. **Network 标签中失败的 API 请求详情** - - 请求 URL - - 请求方法 - - 状态码 - - 响应内容 -3. **CCW View 服务端日志** -4. **操作系统和浏览器版本** -5. **CCW 版本** (`ccw --version`) - -## 快速测试脚本 - -在浏览器控制台运行以下脚本测试完整流程： - -```javascript -// 测试 API 端点可用性 -async function testMcpEndpoints() { - const endpoints = [ - '/api/mcp-config', - '/api/mcp-add-global-server', - '/api/mcp-copy-server' - ]; - - for (const endpoint of endpoints) { - try { - const response = await fetch(endpoint); - console.log(`✓ ${endpoint}: ${response.status}`); - } catch (error) { - console.error(`✗ ${endpoint}: ${error.message}`); - } - } -} - -testMcpEndpoints(); -``` - -## 已知限制 - -- 必须至少选择一个工具才能安装 -- 安装到全局需要写入 `~/.claude.json` 的权限 -- Windows 用户确保路径使用正确的斜杠方向 diff --git a/MCP_OPTIMIZATION_SUMMARY.md b/MCP_OPTIMIZATION_SUMMARY.md deleted file mode 100644 index 49248c60..00000000 --- a/MCP_OPTIMIZATION_SUMMARY.md +++ /dev/null @@ -1,94 +0,0 @@ -# Session Management Design Evolution Analysis - -## 1. Abstraction Layer Value Analysis - -The current architecture employs a "Thick Tool, Thin CLI" pattern. - -* **CLI Layer (`session.ts`)**: Acts primarily as a UI adapter. Its value lies in: - * **UX Enhancement**: formatting JSON outputs into human-readable text (colors, indentation). - * **Shortcuts**: providing semantic commands like `status` and `task` which map to generic `update` operations in the backend. - * **Safety**: specialized error handling (e.g., `EPIPE`) and user feedback. -* **Tool Layer (`session-manager.ts`)**: Encapsulates the core business logic. - * **Centralized Security**: The `validatePathParams` and `findSession` functions ensure operations are confined to valid session scopes, preventing path traversal. - * **Path Routing**: The `PATH_ROUTES` constant abstracts the physical file structure away from the logical operations. Consumers request "plan" or "task", not specific file paths. - * **Polymorphism**: Handles both "Standard WFS" (heavy workflow) and "Lite" (ephemeral) sessions through a unified interface. - -**Verdict**: The abstraction is high-value for **security** and **consistency**, ensuring that all session interactions (whether from CLI or Agent) adhere to the same structural invariants. However, the semantic mapping is thinning, with the CLI often just passing raw JSON `content` directly to the tool. - -## 2. Hidden Complexity Costs - -The "Unified Session Manager" design hides significant complexity that is beginning to leak: - -* **Discovery Overhead**: `findSession` performs a linear search across 4 distinct directory roots (`active`, `archived`, `lite-plan`, `lite-fix`) for *every single operation*. As the number of sessions grows, this disk I/O could become a bottleneck. -* **Leaky Abstractions in Handling "Lite" Sessions**: - * `executeInit` contains explicit branching logic (`if (location === 'lite-plan'...)`). - * `executeArchive` explicitly throws errors for Lite sessions. - * The "Unified" interface creates a false promise of compatibility; consumers must "know" that `archive` doesn't work for Lite sessions, breaking the Liskov Substitution Principle. -* **Routing Table Explosion**: `PATH_ROUTES` is becoming a "God Object" mapping. It mixes different domains: - * Core Workflow (`session`, `plan`) - * Task Management (`task`, `summary`) - * Review Systems (`review-dim`, `review-iter`) - * Lite System (`lite-plan`, `exploration`) - * *Cost*: Adding a new feature requires touching the Schema, the Routing Table, and often the Operation Switch. - -## 3. Parameter Transformation Overhead - -Data undergoes multiple transformations, creating friction: - -1. **CLI Args -> Options Object**: `args` parsed into `InitOptions`, `ReadOptions`. -2. **Options -> Tool Params**: Specialized options (`options.taskId`) are manually mapped to generic `path_params`. - * *Risk*: The CLI must implicitly know which `content_type` requires which `path_params`. For example, `readAction` manually constructs `path_params` for `taskId`, `filename`, `dimension`, etc. If the Tool changes a required param, the CLI breaks. -3. **Tool Params -> Zod Validation**: The tool re-validates the structure. -4. **Tool -> File System**: The tool maps logical params to physical paths. - -**High Friction Area**: The generic `path_params` object. It forces a loose contract. A strict type system (e.g., distinct interfaces for `ReadTaskParams` vs `ReadPlanParams`) is lost in favor of a generic `Record`. - -## 4. Alternative Architecture Proposals - -### Proposal A: Domain-Specific Tools (Split by Lifecycle) -Split the monolithic `session_manager` into targeted tools. -* **Components**: `wfs_manager` (Standard Workflow), `lite_session_manager` (Lite/Ephemeral). -* **Pros**: - * Clean separation of concerns. `lite` tools don't need `archive` or `task` logic. - * Simpler Schemas. - * Faster discovery (look in 1 place). -* **Cons**: - * Agent confusion: "Which tool do I use to read a file?" - * Duplicated utility code (file reading, writing). - -### Proposal B: Resource-Oriented Architecture (REST-like) -Focus on Resources rather than Operations. -* **Components**: `task_tool` (CRUD for tasks), `session_tool` (Lifecycle), `file_tool` (Safe FS access within session). -* **Pros**: - * Aligns with how LLMs think (Action on Object). - * `task_tool` can enforce strict schemas for task status updates, removing the "magic string" status updates in the current CLI. -* **Cons**: - * Loss of the "Session" as a coherent unit of work. - * Harder to implement "global" operations like `archive` which touch multiple resources. - -### Proposal C: Strategy Pattern (Internal Refactor) -Keep the Unified Interface, but refactor internals. -* **Design**: `SessionManager` class delegates to `SessionStrategy` implementations (`StandardStrategy`, `LiteStrategy`). -* **Pros**: - * Removes `if (lite)` checks from main logic. - * Preserves the simple "one tool" interface for Agents. - * Allows `LiteStrategy` to throw "NotSupported" cleanly or handle `archive` differently (e.g., delete). -* **Cons**: - * Does not solve the `path_params` loose typing issue. - -## 5. Recommended Optimal Design - -**Hybrid Approach: Strategy Pattern + Stronger Typing** - -1. **Refactor `session-manager.ts` to use a Strategy Pattern.** - * Define a `SessionStrategy` interface: `init`, `resolvePath`, `list`, `archive`. - * Implement `StandardWorkflowStrategy` and `LiteWorkflowStrategy`. - * The `handler` simply identifies the session type (via `findSession` or input param) and delegates. - -2. **Flatten the Path Resolution.** - * Instead of `path_params: { task_id: "1" }`, promote widely used IDs to top-level optional params in the Zod schema: `task_id?: string`, `filename?: string`. This makes the contract explicit to the LLM. - -3. **Deprecate "Hybrid" content types.** - * Instead of `content_type="lite-plan"`, just use `content_type="plan"` and let the `LiteStrategy` decide where that lives (`plan.json` vs `IMPL_PLAN.md`). This unifies the language the Agent uses—it always "reads the plan", regardless of session type. - -**Benefit**: This maintains the ease of use for the Agent (one tool) while cleaning up the internal complexity and removing the "Leaky Abstractions" where the Agent currently has to know if it's in a Lite or Standard session to ask for the right file type. \ No newline at end of file diff --git a/README.md b/README.md index cf04fe56..1399d051 100644 --- a/README.md +++ b/README.md @@ -1,312 +1,137 @@ -# 🚀 Claude Code Workflow (CCW) - -[![Run in Smithery](https://smithery.ai/badge/skills/catlog22)](https://smithery.ai/skills?ns=catlog22&utm_source=github&utm_medium=badge) - +# Claude Code Workflow (CCW)
-[![Version](https://img.shields.io/badge/version-v6.3.19-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases) +[![Version](https://img.shields.io/badge/version-v6.3.33-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases) [![npm](https://img.shields.io/npm/v/claude-code-workflow.svg)](https://www.npmjs.com/package/claude-code-workflow) [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) -[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)]() -[![Visual Tests](https://github.com/catlog22/Claude-Code-Workflow/actions/workflows/visual-tests.yml/badge.svg)](https://github.com/catlog22/Claude-Code-Workflow/actions/workflows/visual-tests.yml) -**Languages:** [English](README.md) | [中文](README_CN.md) +**[English](README.md) | [中文](README_CN.md)**
--- -**Claude Code Workflow (CCW)** is a JSON-driven multi-agent development framework with intelligent CLI orchestration (Gemini/Qwen/Codex), context-first architecture, and automated workflow execution. It transforms AI development from simple prompt chaining into a powerful orchestration system. +**CCW** is a JSON-driven multi-agent development framework with intelligent CLI orchestration. It provides **4-level workflow system** from rapid execution to full brainstorming, transforming AI development into powerful orchestration. -> **🎉 Version 6.3.19: Search Enhancement & CLI Tools Upgrade** -> -> **New Features**: -> - 🔍 **Dense + Reranker Search**: Cross-Encoder reranking for improved result relevance -> - 💻 **OpenCode AI Support**: New OpenCode CLI tool integration -> - 🛠️ **Service Architecture**: Preload service, cache management, UV package manager support -> - 📊 **Issue Multi-Queue Execution**: Supports Codex for long-running autonomous work -> -> **Recommended Workflow**: -> - 🚀 **Issue Workflow** (`/issue:plan` → `/issue:queue` → `/issue:execute`): Recommend **Codex** executor for long-running autonomous coding -> -> See [CHANGELOG.md](CHANGELOG.md) for complete details and migration guide. +## Key Features -> 📚 **New to CCW?** Check out the [**Getting Started Guide**](GETTING_STARTED.md) for a beginner-friendly 5-minute tutorial! +| Feature | Description | +|---------|-------------| +| **4-Level Workflows** | From `lite-lite-lite` (instant) to `brainstorm` (multi-role analysis) | +| **Multi-CLI Orchestration** | Gemini, Qwen, Codex, Claude - auto-select or manual | +| **Dependency-Aware Parallelism** | Agent parallel execution without worktree complexity | +| **Issue Workflow** | Post-development maintenance with optional worktree isolation | +| **JSON-First State** | `.task/IMPL-*.json` as single source of truth | +| **Dashboard** | Visual session management, CodexLens search, graph explorer | + +> 📖 **New?** See [Workflow Guide](WORKFLOW_GUIDE.md) for the complete 4-level workflow system. --- -## ✨ Core Concepts +## Quick Start -CCW is built on a set of core principles that distinguish it from traditional AI development approaches: +### Install -- **Context-First Architecture**: Eliminates uncertainty during execution through pre-defined context gathering, ensuring agents have the right information *before* implementation. -- **JSON-First State Management**: Task state is fully stored in `.task/IMPL-*.json` files as the single source of truth, enabling programmatic orchestration without state drift. -- **Autonomous Multi-Stage Orchestration**: Commands chain-invoke specialized sub-commands and agents to automate complex workflows with zero user intervention. -- **Multi-Model Strategy**: Leverages the unique strengths of different AI models (e.g., Gemini for analysis, Codex for implementation) for superior results. -- **Layered Memory System**: A 4-tier documentation system that provides context at the appropriate abstraction level, preventing information overload. -- **Specialized Role-Based Agents**: A suite of agents (`@code-developer`, `@test-fix-agent`, etc.) that emulate a real software team for diverse tasks. - ---- - -## ⚙️ Installation - -### **📋 Requirements** - -| Platform | Node.js | Additional | -|----------|---------|------------| -| Windows | 20.x or 22.x LTS (recommended) | Node 23+ requires [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) | -| macOS | 18.x+ | Xcode Command Line Tools | -| Linux | 18.x+ | build-essential | - -> **Note**: The `better-sqlite3` dependency requires native compilation. Using Node.js LTS versions avoids build issues. - -### **📦 npm Install (Recommended)** - -Install globally via npm: ```bash npm install -g claude-code-workflow -``` - -Then install workflow files to your system: -```bash -# Interactive installation -ccw install - -# Global installation (to ~/.claude) ccw install -m Global - -# Project-specific installation -ccw install -m Path -p /path/to/project ``` -### **✅ Verify Installation** -After installation, open **Claude Code** and verify that workflow commands are available by running: -```bash -/workflow:session:list -``` -If slash commands (e.g., `/workflow:*`) are recognized, the installation was successful. +### Choose Your Workflow Level ---- +| Level | Command | Use Case | +|-------|---------|----------| +| **1** | `/workflow:lite-lite-lite` | Quick fixes, config changes | +| **2** | `/workflow:lite-plan` | Clear single-module features | +| **2** | `/workflow:lite-fix` | Bug diagnosis and fix | +| **2** | `/workflow:multi-cli-plan` | Multi-perspective analysis | +| **3** | `/workflow:plan` | Multi-module development | +| **3** | `/workflow:tdd-plan` | Test-driven development | +| **4** | `/workflow:brainstorm:auto-parallel` | New features, architecture design | -## 🖥️ CCW CLI Tool - -The `ccw` command provides a powerful CLI for managing your Claude Code Workflow installation: - -### **Commands** - -| Command | Description | -|---------|-------------| -| `ccw install` | Install workflow files to Global (~/.claude) or specific Path | -| `ccw upgrade` | Upgrade existing installations to current package version | -| `ccw uninstall` | Remove workflow files from an installation | -| `ccw view` | Open the workflow dashboard in browser | -| `ccw serve` | Start dashboard server without opening browser | -| `ccw list` | List all managed installations | -| `ccw cli -p "..."` | Execute CLI tools (Gemini/Qwen/Codex) with prompt | -| `ccw core-memory` | Manage session clustering and memory | - -### **Usage Examples** +### Example Workflows ```bash -# Install globally -ccw install -m Global +# Level 1: Instant execution +/workflow:lite-lite-lite "Fix typo in README" -# Install to specific project -ccw install -m Path -p ./my-project +# Level 2: Lightweight planning +/workflow:lite-plan "Add JWT authentication" +/workflow:lite-fix "User upload fails with 413 error" -# Open dashboard -ccw view +# Level 3: Standard planning with session +/workflow:plan "Implement payment gateway integration" +/workflow:execute -# Start dashboard server on custom port -ccw serve --port 8080 - -# Upgrade all installations -ccw upgrade -a - -# List installations -ccw list -``` - -### **Dashboard Features** - -The CCW Dashboard (`ccw view`) provides: -- 📊 **Session Overview**: View all workflow sessions with status and progress -- 📋 **Task Management**: Track task execution and completion -- 🔍 **CodexLens Manager**: Native code indexing with FTS + Semantic + Hybrid search -- 🧠 **Core Memory**: Session clustering visualization with cluster management -- 📄 **CLAUDE.md Manager**: File tree viewer for configuration management -- 🎯 **Skills Manager**: View and manage Claude Code skills -- 🕸️ **Graph Explorer**: Interactive code relationship visualization (Cytoscape.js) -- ⚙️ **MCP Manager**: Configure and monitor MCP servers -- 🪝 **Hook Manager**: Manage Claude Code hooks -- ❓ **Help View**: Internationalized help documentation -- 💻 **CLI Manager**: CLI execution history with session resume - -> 📖 See [**Dashboard Guide**](DASHBOARD_GUIDE.md) and [**Dashboard Operations**](DASHBOARD_OPERATIONS_EN.md) for detailed documentation. - ---- - -## 🔒 Security - -The dashboard server is **localhost-bound by default** and **API endpoints require authentication**. See `ccw/docs/SECURITY.md` for the full security model, token usage, and safe deployment guidance. - ---- - -## 🛠️ Command Reference - -CCW provides a rich set of commands for managing workflows, tasks, and interactions with AI tools. For a complete list and detailed descriptions of all available commands, please refer to the [**COMMAND_REFERENCE.md**](COMMAND_REFERENCE.md) file. - -For detailed technical specifications of each command, see [**COMMAND_SPEC.md**](COMMAND_SPEC.md). - ---- - -### 💡 **Need Help? Use the Interactive Command Guide** - -CCW includes a built-in **Command Guide Skill** to help you discover and use commands effectively: - -- **`CCW-help`** - Get interactive help and command recommendations -- **`CCW-issue`** - Report bugs or request features using guided templates - -The Command Guide provides: -- 🔍 **Smart Command Search** - Find commands by keyword, category, or use case -- 🤖 **Next-Step Recommendations** - Get suggestions for what to do after any command -- 📖 **Detailed Documentation** - View arguments, examples, and best practices -- 🎓 **Beginner Onboarding** - Learn the 14 core commands through guided learning paths -- 📝 **Issue Reporting** - Generate standardized bug reports and feature requests - -**Usage Examples**: -``` -User: "CCW-help" -→ Interactive menu with command search, recommendations, and documentation - -User: "What should I do after /workflow:plan?" -→ Recommends /workflow:execute, /workflow:action-plan-verify with workflow patterns - -User: "CCW-issue" -→ Guided template generation for bugs, features, or question inquiries +# Level 4: Multi-role brainstorming +/workflow:brainstorm:auto-parallel "Design real-time collaboration system" --count 5 +/workflow:plan --session WFS-xxx +/workflow:execute ``` --- -## 🚀 Quick Start - -The best way to get started is by following the 5-minute tutorial in the [**Getting Started Guide**](GETTING_STARTED.md). - -Here's a quick example of a common development workflow: - -### **Option 1: Lite-Plan Workflow** (⚡ Recommended for Quick Tasks) - -Lightweight interactive workflow with in-memory planning and immediate execution: +## CLI Tool ```bash -# Basic usage with auto-detection -/workflow:lite-plan "Add JWT authentication to user login" - -# Force code exploration -/workflow:lite-plan -e "Refactor logging module for better performance" - -# Basic usage -/workflow:lite-plan "Add unit tests for authentication service" +ccw install # Install workflow files +ccw view # Open dashboard +ccw cli -p "..." # Execute CLI tools (Gemini/Qwen/Codex) +ccw upgrade -a # Upgrade all installations ``` -**Interactive Flow**: -1. **Phase 1**: Automatic task analysis and smart code exploration (if needed) -2. **Phase 2**: Answer clarification questions (if any) -3. **Phase 3**: Review generated plan and task breakdown -4. **Phase 4**: Three-dimensional confirmation: - - ✅ Confirm/Modify/Cancel task - - 🔧 Choose execution: Agent / Provide Plan Only / CLI (Gemini/Qwen/Codex) - - 🔍 Optional code review: No / Claude / Gemini / Qwen / Codex -5. **Phase 5**: Watch live execution and task tracking +### Dashboard Features -### **Option 2: Lite-Fix Workflow** (🐛 Recommended for Bug Fixes) - -Intelligent bug diagnosis and fix workflow with adaptive severity assessment: - -```bash -# Standard bug fix (auto-adapts based on severity) -/workflow:lite-fix "User avatar upload fails with 413 error" - -# Production hotfix mode -/workflow:lite-fix --hotfix "Payment gateway 5xx errors" -``` - -**Workflow Features**: -- **Phase 1**: Intelligent root cause diagnosis with adaptive search -- **Phase 2**: Automatic impact assessment and risk scoring -- **Phase 3**: Fix strategy generation based on complexity -- **Phase 4**: Risk-aware verification planning -- **Phase 5**: User confirmation with execution selection -- **Phase 6**: Execution dispatch with complete artifact tracking - -**Session Artifacts** (saved to `.workflow/.lite-fix/{bug-slug}-{timestamp}/`): -- `diagnosis.json` - Root cause analysis and reproduction steps -- `impact.json` - Risk score, severity, and workflow adaptations -- `fix-plan.json` - Fix strategy and implementation tasks -- `task.json` - Enhanced Task JSON with complete context -- `followup.json` - Auto-generated follow-up tasks (hotfix mode only) - -### **Option 3: Full Workflow** (📋 Comprehensive Planning) - -Traditional multi-stage workflow for complex projects: - -1. **Create Plan** (auto-starts session): - ```bash - /workflow:plan "Implement JWT-based user login and registration" - ``` -2. **Execute Plan**: - ```bash - /workflow:execute - ``` -3. **View Status** (optional): - ```bash - /workflow:status - ``` +- **Session Overview** - Track workflow sessions and progress +- **CodexLens** - FTS + Semantic + Hybrid code search +- **Graph Explorer** - Interactive code relationship visualization +- **CLI Manager** - Execution history with session resume --- -## 📚 Documentation +## Documentation -CCW provides comprehensive documentation to help you get started quickly and master advanced features: - -### 📖 **Getting Started** -- [**Getting Started Guide**](GETTING_STARTED.md) - 5-minute quick start tutorial -- [**Installation Guide**](INSTALL.md) - Detailed installation instructions ([中文](INSTALL_CN.md)) -- [**Workflow Decision Guide**](WORKFLOW_DECISION_GUIDE.md) - 🌳 Interactive flowchart to choose the right command -- [**Examples**](EXAMPLES.md) - Real-world use cases and practical examples -- [**FAQ**](FAQ.md) - Common questions and troubleshooting - -### 🖥️ **Dashboard** -- [**Dashboard Guide**](DASHBOARD_GUIDE.md) - Dashboard user guide and interface overview -- [**Dashboard Operations**](DASHBOARD_OPERATIONS_EN.md) - Detailed operation instructions - -### 🔄 **Workflow Guides** -- [**Issue Loop Workflow**](docs/workflows/ISSUE_LOOP_WORKFLOW.md) - Batch issue processing with two-phase lifecycle (accumulate → resolve) - -### 🏗️ **Architecture & Design** -- [**Architecture Overview**](ARCHITECTURE.md) - System design and core components -- [**Project Introduction**](PROJECT_INTRODUCTION.md) - Detailed project overview -- [**Workflow Diagrams**](WORKFLOW_DIAGRAMS.md) - Visual workflow representations - -### 📋 **Command Reference** -- [**Command Reference**](COMMAND_REFERENCE.md) - Complete list of all commands -- [**Command Spec**](COMMAND_SPEC.md) - Detailed technical specifications -- [**Command Flow Standard**](COMMAND_FLOW_STANDARD.md) - Command design patterns - -### 🤝 **Contributing** -- [**Contributing Guide**](CONTRIBUTING.md) - How to contribute to CCW -- [**Changelog**](CHANGELOG.md) - Version history and release notes +| Document | Description | +|----------|-------------| +| [**Workflow Guide**](WORKFLOW_GUIDE.md) | 4-level workflow system (recommended) | +| [**Getting Started**](GETTING_STARTED.md) | 5-minute quick start | +| [**Dashboard Guide**](DASHBOARD_GUIDE.md) | Dashboard user guide | +| [**FAQ**](FAQ.md) | Common questions | +| [**Changelog**](CHANGELOG.md) | Version history | --- -## 🤝 Contributing & Support +## Architecture -- **Repository**: [GitHub - Claude-Code-Workflow](https://github.com/catlog22/Claude-Code-Workflow) -- **Issues**: Report bugs or request features on [GitHub Issues](https://github.com/catlog22/Claude-Code-Workflow/issues). -- **Discussions**: Join the [Community Forum](https://github.com/catlog22/Claude-Code-Workflow/discussions). -- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines. +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Main Workflow (4 Levels) │ +│ Level 1: lite-lite-lite (instant, no artifacts) │ +│ Level 2: lite-plan / lite-fix / multi-cli-plan (→ lite-execute)│ +│ Level 3: plan / tdd-plan / test-fix-gen (session persistence) │ +│ Level 4: brainstorm:auto-parallel → plan → execute │ +└─────────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────────┐ +│ Issue Workflow (Supplement) │ +│ discover → plan → queue → execute (worktree isolation) │ +└─────────────────────────────────────────────────────────────────┘ +``` -## 📄 License +**Core Principles:** +- **Dependency Analysis** solves parallelism - no worktree needed for main workflow +- **Issue Workflow** supplements main workflow for post-development maintenance +- Select workflow level based on complexity - avoid over-engineering -This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details. +--- + +## Contributing + +- **Repository**: [GitHub](https://github.com/catlog22/Claude-Code-Workflow) +- **Issues**: [Report bugs or request features](https://github.com/catlog22/Claude-Code-Workflow/issues) +- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md) + +## License + +MIT License - see [LICENSE](LICENSE) diff --git a/WORKFLOW_DECISION_GUIDE.md b/WORKFLOW_DECISION_GUIDE.md deleted file mode 100644 index 8a550662..00000000 --- a/WORKFLOW_DECISION_GUIDE.md +++ /dev/null @@ -1,853 +0,0 @@ -# 🌳 CCW Workflow Decision Guide - -本指南帮助您选择正确的命令和工作流程，适用于软件开发的完整生命周期。 - ---- - -## 📊 全生命周期命令选择流程图 - -```mermaid -flowchart TD - Start([开始新任务]) --> Q0{这是Bug修复吗?} - - Q0 -->|是| BugFix[🐛 Bug修复流程] - Q0 -->|否| Q1{知道要做什么吗?} - - BugFix --> BugSeverity{了解问题根因?} - BugSeverity -->|清楚| LiteFix[/ /workflow:lite-fix
标准Bug修复 /] - BugSeverity -->|生产事故| HotFix[/ /workflow:lite-fix --hotfix
热修复模式 /] - BugSeverity -->|不清楚| BugDiag[/ /workflow:lite-fix
自动诊断根因 /] - - BugDiag --> LiteFix - LiteFix --> BugComplete[Bug修复完成] - HotFix --> FollowUp[/ 自动生成跟进任务
全面修复+事后分析 /] - FollowUp --> BugComplete - BugComplete --> End([任务完成]) - - Q1 -->|不知道| Ideation[💡 构思阶段
需求探索] - Q1 -->|知道| Q2{知道怎么做吗?} - - Ideation --> BrainIdea[/ /workflow:brainstorm:auto-parallel
探索产品方向和功能定位 /] - BrainIdea --> Q2 - - Q2 -->|不知道| Design[🏗️ 设计探索阶段
架构方案探索] - Q2 -->|知道| Q3{需要UI设计吗?} - - Design --> BrainDesign[/ /workflow:brainstorm:auto-parallel
探索技术方案和架构 /] - BrainDesign --> Q3 - - Q3 -->|需要| UIDesign[🎨 UI设计阶段] - Q3 -->|不需要| Q4{任务复杂度?} - - UIDesign --> Q3a{有参考设计吗?} - Q3a -->|有| UIImitate[/ /workflow:ui-design:imitate-auto
--input 本地文件/图片 /] - Q3a -->|无| UIExplore[/ /workflow:ui-design:explore-auto
--prompt 设计描述 /] - - UIImitate --> UISync[/ /workflow:ui-design:design-sync
同步设计系统 /] - UIExplore --> UISync - UISync --> Q4 - - Q4 -->|简单快速| LitePlan[⚡ 轻量规划
/workflow:lite-plan] - Q4 -->|复杂完整| FullPlan[📋 完整规划
/workflow:plan] - - LitePlan --> Q5{需要代码探索?} - Q5 -->|需要| LitePlanE[/ /workflow:lite-plan -e
任务描述 /] - Q5 -->|不需要| LitePlanNormal[/ /workflow:lite-plan
任务描述 /] - - LitePlanE --> LiteConfirm[三维确认:
1️⃣ 任务批准
2️⃣ 执行方式
3️⃣ 代码审查] - LitePlanNormal --> LiteConfirm - - LiteConfirm --> Q6{选择执行方式} - Q6 -->|Agent| LiteAgent[/ /workflow:lite-execute
使用@code-developer /] - Q6 -->|CLI工具| LiteCLI[CLI执行
Gemini/Qwen/Codex] - Q6 -->|仅计划| UserImpl[用户手动实现] - - FullPlan --> PlanVerify{验证计划质量?} - PlanVerify -->|是| Verify[/ /workflow:action-plan-verify /] - PlanVerify -->|否| Execute - Verify --> Q7{验证通过?} - Q7 -->|否| FixPlan[修复计划问题] - Q7 -->|是| Execute - FixPlan --> Execute - - Execute[🚀 执行阶段
/workflow:execute] - LiteAgent --> TestDecision - LiteCLI --> TestDecision - UserImpl --> TestDecision - Execute --> TestDecision - - TestDecision{需要测试吗?} - TestDecision -->|TDD模式| TDD[/ /workflow:tdd-plan
测试驱动开发 /] - TestDecision -->|后置测试| TestGen[/ /workflow:test-gen
生成测试 /] - TestDecision -->|已有测试| TestCycle[/ /workflow:test-cycle-execute
测试修复循环 /] - TestDecision -->|不需要| Review - - TDD --> TDDExecute[/ /workflow:execute
Red-Green-Refactor /] - TDDExecute --> TDDVerify[/ /workflow:tdd-verify
验证TDD合规 /] - TDDVerify --> Review - - TestGen --> TestExecute[/ /workflow:execute
执行测试任务 /] - TestExecute --> TestResult{测试通过?} - TestResult -->|否| TestCycle - TestResult -->|是| Review - - TestCycle --> TestPass{通过率≥95%?} - TestPass -->|否,继续修复| TestCycle - TestPass -->|是| Review - - Review[📝 审查阶段] - Review --> Q8{需要专项审查?} - Q8 -->|安全| SecurityReview[/ /workflow:review
--type security /] - Q8 -->|架构| ArchReview[/ /workflow:review
--type architecture /] - Q8 -->|质量| QualityReview[/ /workflow:review
--type quality /] - Q8 -->|综合| GeneralReview[/ /workflow:review
综合审查 /] - Q8 -->|不需要| Complete - - SecurityReview --> Complete - ArchReview --> Complete - QualityReview --> Complete - GeneralReview --> Complete - - Complete[✅ 完成阶段
/workflow:session:complete] - Complete --> End - - style Start fill:#e1f5ff - style BugFix fill:#ffccbc - style LiteFix fill:#ffccbc - style HotFix fill:#ff8a65 - style BugDiag fill:#ffccbc - style BugComplete fill:#c8e6c9 - style End fill:#c8e6c9 - style BrainIdea fill:#fff9c4 - style BrainDesign fill:#fff9c4 - style UIImitate fill:#f8bbd0 - style UIExplore fill:#f8bbd0 - style LitePlan fill:#b3e5fc - style FullPlan fill:#b3e5fc - style Execute fill:#c5e1a5 - style TDD fill:#ffccbc - style TestGen fill:#ffccbc - style TestCycle fill:#ffccbc - style Review fill:#d1c4e9 - style Complete fill:#c8e6c9 -``` - ---- - -## 🎯 决策关键点说明 - -### 0️⃣ **首要决策 - "这是Bug修复吗？"** - -| 情况 | 命令 | 说明 | -|------|------|------| -| 🐛 **标准Bug修复** | `/workflow:lite-fix "bug描述"` | 自适应严重性评估，完整诊断→影响评估→修复→验证 | -| 🔥 **生产热修复** | `/workflow:lite-fix --hotfix "bug描述"` | 最小化诊断，快速修复，自动生成跟进任务 | -| ❓ **根因不清楚** | `/workflow:lite-fix` | 自动进行深度诊断并执行修复 | -| ✅ **功能开发** | 继续后续流程 | 不是Bug修复，按正常开发流程 | - -**Lite-Fix 工作流特性**: -- **阶段 1**: 智能根因诊断（自适应搜索策略） -- **阶段 2**: 自动影响评估和风险评分（0-10分） -- **阶段 3**: 修复策略生成（单一最优 vs 多选项） -- **阶段 4**: 风险感知验证计划（完整测试 → 烟雾测试） -- **阶段 5**: 用户确认（执行方式 + 验证级别 + 可选审查） -- **阶段 6**: 执行调度 + 会话产物跟踪 - -**会话产物** (保存到 `.workflow/.lite-fix/{bug-slug}-{timestamp}/`): -- `diagnosis.json` - 根因分析、复现步骤 -- `impact.json` - 风险评分、严重性、工作流适应 -- `fix-plan.json` - 修复策略、实现任务 -- `task.json` - 完整上下文的增强任务 JSON -- `followup.json` - 跟进任务（仅热修复模式） - -**示例**： -```bash -# 标准Bug修复（自动适应严重性） -/workflow:lite-fix "用户头像上传失败，返回 413 错误" -→ 自动诊断 → 风险评分 6.5 (High) → 快速修复策略 → 集成测试 - -# 生产热修复（紧急修复） -/workflow:lite-fix --hotfix "支付网关返回 5xx 错误" -→ 最小化诊断 → 假设 Critical → 手术式修复 → 烟雾测试 -→ 自动生成: 全面修复任务（3天内）+ 事后分析（1周内） - -# 根因不清楚（lite-fix 自动诊断） -/workflow:lite-fix "购物车随机丢失商品" -→ 自动深度诊断 → 识别根因 → 实现修复 -``` - -**何时使用 lite-fix**: -- ✅ 任何有明确症状的Bug（自动适应严重性） -- ✅ 本地化修复（1-5个文件） -- ✅ 生产事故（使用 `--hotfix` 模式） -- ✅ 根因不清楚（自动进行深度诊断） -- ❌ 需要架构变更 → 用 `/workflow:plan --mode bugfix` - ---- - -### 1️⃣ **构思阶段 - "知道要做什么吗？"** - -| 情况 | 命令 | 说明 | -|------|------|------| -| ❌ 不确定产品方向 | `/workflow:brainstorm:auto-parallel "探索XXX领域的产品机会"` | 产品经理、用户体验专家等多角色分析 | -| ✅ 明确功能需求 | 跳过，进入设计阶段 | 已知道要构建什么功能 | - -**示例**： -```bash -# 不确定场景：我想做一个协作工具，但不确定具体做什么 -/workflow:brainstorm:auto-parallel "探索团队协作工具的产品定位和核心功能" --count 5 - -# 确定场景：我要做一个实时文档协作编辑器（需求明确） -# 跳过构思，进入设计阶段 -``` - ---- - -### 2️⃣ **设计阶段 - "知道怎么做吗？"** - -| 情况 | 命令 | 说明 | -|------|------|------| -| ❌ 不知道技术方案 | `/workflow:brainstorm:auto-parallel "设计XXX系统架构"` | 系统架构师、安全专家等分析技术方案 | -| ✅ 清晰实现路径 | 跳过，直接进入规划 | 已知道用什么技术栈、架构模式 | - -**示例**： -```bash -# 不知道怎么做：实时协作编辑的冲突解决机制？用什么算法？ -/workflow:brainstorm:auto-parallel "设计实时协作文档编辑系统的冲突解决机制" --count 4 - -# 知道怎么做：使用Operational Transformation + WebSocket + Redis -# 跳过设计探索，直接规划实现 -/workflow:plan "使用OT算法实现实时协作编辑，WebSocket通信，Redis存储" -``` - ---- - -### 3️⃣ **UI设计阶段 - "需要UI设计吗？"** - -| 情况 | 命令 | 说明 | -|------|------|------| -| 🎨 有参考设计 | `/workflow:ui-design:imitate-auto --input "本地文件/图片"` | 基于本地参考文件/图片复制设计 | -| 🎨 从零设计 | `/workflow:ui-design:explore-auto --prompt "描述"` | 生成多个设计变体 | -| ⏭️ 后端/无UI | 跳过 | 纯后端API、CLI工具等 | - -**示例**： -```bash -# 有参考：使用本地截图或代码文件 -/workflow:ui-design:imitate-auto --input "design-refs/*.png" -# 或从现有代码导入 -/workflow:ui-design:imitate-auto --input "./src/components" - -# 无参考：从零设计 -/workflow:ui-design:explore-auto --prompt "现代简洁的文档协作编辑界面" --style-variants 3 - -# 同步设计到项目 -/workflow:ui-design:design-sync --session WFS-xxx --selected-prototypes "v1,v2" -``` - ---- - -### 4️⃣ **规划阶段 - 选择工作流类型** - -| 工作流 | 适用场景 | 特点 | -|--------|---------|------| -| `/workflow:lite-plan` | 快速任务、小功能 | 内存规划、三维确认、快速执行 | -| `/workflow:plan` | 复杂项目、团队协作 | 持久化计划、质量门禁、完整追溯 | - -**Lite-Plan 三维确认**： -1. **任务批准**：确认/修改/取消 -2. **执行方式**：Agent / 提供计划 / CLI工具（Gemini/Qwen/Codex） -3. **代码审查**：否 / Claude / Gemini / Qwen / Codex - -**示例**： -```bash -# 简单任务 -/workflow:lite-plan "添加用户头像上传功能" - -# 需要代码探索 -/workflow:lite-plan -e "重构认证模块为OAuth2标准" - -# 复杂项目 -/workflow:plan "实现完整的实时协作编辑系统" -/workflow:action-plan-verify # 验证计划质量 -/workflow:execute -``` - ---- - -### 5️⃣ **测试阶段 - 选择测试策略** - -| 策略 | 命令 | 适用场景 | -|------|------|---------| -| **TDD模式** | `/workflow:tdd-plan` | 从头开始，测试驱动开发 | -| **后置测试** | `/workflow:test-gen` | 代码已完成，补充测试 | -| **测试修复** | `/workflow:test-cycle-execute` | 已有测试，需要修复失败用例 | - -**示例**： -```bash -# TDD：先写测试，再实现 -/workflow:tdd-plan "用户认证模块" -/workflow:execute # Red-Green-Refactor循环 -/workflow:tdd-verify # 验证TDD合规 - -# 后置测试：代码完成后补测试 -/workflow:test-gen WFS-user-auth-implementation -/workflow:execute - -# 测试修复：已有测试，但失败率高 -/workflow:test-cycle-execute --max-iterations 5 -# 自动迭代修复直到通过率≥95% -``` - ---- - -### 6️⃣ **审查阶段 - 选择审查类型** - -| 类型 | 命令 | 关注点 | -|------|------|--------| -| **安全审查** | `/workflow:review --type security` | SQL注入、XSS、认证漏洞 | -| **架构审查** | `/workflow:review --type architecture` | 设计模式、耦合度、可扩展性 | -| **质量审查** | `/workflow:review --type quality` | 代码风格、复杂度、可维护性 | -| **综合审查** | `/workflow:review` | 全方位检查 | - -**示例**： -```bash -# 安全关键系统 -/workflow:review --type security - -# 架构重构后 -/workflow:review --type architecture - -# 日常开发 -/workflow:review --type quality -``` - ---- - -### 7️⃣ **CLI 工具协作模式 - 多模型智能协同** - -本项目集成了三种 CLI 工具，支持灵活的串联、并行和混合执行方式： - -| 工具 | 核心能力 | 上下文长度 | 适用场景 | -|------|---------|-----------|---------| -| **Gemini** | 深度分析、架构设计、规划 | 超长上下文 | 代码理解、执行流追踪、技术方案评估 | -| **Qwen** | 代码审查、模式识别 | 超长上下文 | Gemini 备选、多维度分析 | -| **Codex** | 精确代码撰写、Bug定位 | 标准上下文 | 功能实现、测试生成、代码重构 | - -#### 📋 三种执行模式 - -**1. 串联执行（Serial Execution）** - 顺序依赖 - -适用场景：后续任务依赖前一任务的结果 - -```bash -# 示例：分析后实现 -# Step 1: Gemini 分析架构 -使用 gemini 分析认证模块的架构设计，识别关键组件和数据流 - -# Step 2: Codex 基于分析结果实现 -让 codex 根据上述架构分析，实现 JWT 认证中间件 -``` - -**执行流程**： -``` -Gemini 分析 → 输出架构报告 → Codex 读取报告 → 实现代码 -``` - ---- - -**2. 并行执行（Parallel Execution）** - 同时进行 - -适用场景：多个独立任务，无依赖关系 - -```bash -# 示例：多维度分析 -用 gemini 分析认证模块的安全性，关注 JWT、密码存储、会话管理 -用 qwen 分析认证模块的性能瓶颈，识别慢查询和优化点 -让 codex 为认证模块生成单元测试，覆盖所有核心功能 -``` - -**执行流程**： -``` - ┌─ Gemini: 安全分析 ─┐ -并行 ───┼─ Qwen: 性能分析 ──┼─→ 汇总结果 - └─ Codex: 测试生成 ─┘ -``` - ---- - -**3. 混合执行（Hybrid Execution）** - 串并结合 - -适用场景：复杂任务，部分并行、部分串联 - -```bash -# 示例：完整功能开发 -# Phase 1: 并行分析（独立任务） -使用 gemini 分析现有认证系统的架构模式 -用 qwen 评估 OAuth2 集成的技术方案 - -# Phase 2: 串联实现（依赖 Phase 1） -让 codex 基于上述分析，实现 OAuth2 认证流程 - -# Phase 3: 并行优化（独立任务） -用 gemini 审查代码质量和安全性 -让 codex 生成集成测试 -``` - -**执行流程**： -``` -Phase 1: Gemini 分析 ──┐ - Qwen 评估 ────┼─→ Phase 2: Codex 实现 ──→ Phase 3: Gemini 审查 ──┐ - │ Codex 测试 ──┼─→ 完成 - └────────────────────────────────────────────────┘ -``` - ---- - -#### 🎯 语义调用 vs 命令调用 - -**方式一：自然语言语义调用**（推荐） - -```bash -# 用户只需自然描述，Claude Code 自动调用工具 -"使用 gemini 分析这个模块的依赖关系" -→ Claude Code 自动生成：cd src && gemini -p "分析依赖关系" - -"让 codex 实现用户注册功能" -→ Claude Code 自动生成：codex -C src/auth --full-auto exec "实现注册" -``` - ---- - -#### 🔗 语义调用与结果上下文（Memory） - -通过自然语言描述，Claude 会自动选择并执行适当的 CLI 工具（Gemini/Qwen/Codex），分析结果作为后续操作的上下文。 - -**1. 语义调用示例** - -```bash -# 用自然语言描述需求，Claude 自动选择工具 -"使用 gemini 分析认证模块架构" -→ Claude 自动执行 Gemini CLI 并保存结果 - -"让 qwen 评估性能瓶颈" -→ Claude 自动执行 Qwen CLI 并保存结果 - -"用 codex 实现这个功能" -→ Claude 自动执行 Codex CLI -``` - -**2. 结果作为规划依据** - -```bash -# Step 1: 分析现状（生成 memory） -使用 gemini 深度分析认证系统的架构、安全性和性能问题 -→ 输出：详细分析报告（自动保存） - -# Step 2: 基于分析结果规划 -/workflow:plan "根据上述 Gemini 分析报告重构认证系统" -→ 系统自动读取 .chat/ 中的分析报告作为上下文 -→ 生成精准的实施计划 -``` - -**3. 结果作为实现依据** - -```bash -# Step 1: 并行分析（生成多个 memory） -使用 gemini 分析现有代码结构 -用 qwen 评估技术方案可行性 -→ 输出：多份分析报告 - -# Step 2: 基于所有分析结果实现 -让 codex 综合上述 Gemini 和 Qwen 的分析，实现最优方案 -→ Codex 自动读取前序分析结果 -→ 生成符合架构设计的代码 -``` - -**4. 跨会话引用** - -```bash -# 引用历史会话的分析结果 -"参考 WFS-2024-001 中的架构分析，用 codex 实现新的支付模块" -→ Claude 自动加载指定会话的上下文 -→ 基于历史分析进行实现 -``` - -**5. Memory 更新循环** - -```bash -# 迭代优化流程 -使用 gemini 分析当前实现的问题 -→ 生成问题报告（memory） - -让 codex 根据问题报告优化代码 -→ 实现改进（更新 memory） - -用 qwen 验证优化效果 -→ 验证报告（追加 memory） - -# 所有结果累积为完整的项目 memory -→ 支持后续决策和实现 -``` - -**Memory 流转示例**： - -``` -┌─────────────────────────────────────────────────────────────┐ -│ Phase 1: 分析阶段（生成 Memory） │ -├─────────────────────────────────────────────────────────────┤ -│ Gemini 分析 → 架构分析报告 (.chat/analyze-001.md) │ -│ Qwen 评估 → 方案评估报告 (.chat/analyze-002.md) │ -└─────────────────────┬───────────────────────────────────────┘ - │ 作为 Memory 输入 - ↓ -┌─────────────────────────────────────────────────────────────┐ -│ Phase 2: 规划阶段（使用 Memory） │ -├─────────────────────────────────────────────────────────────┤ -│ /workflow:plan → 读取分析报告 → 生成实施计划 │ -│ (.task/IMPL-*.json) │ -└─────────────────────┬───────────────────────────────────────┘ - │ 作为 Memory 输入 - ↓ -┌─────────────────────────────────────────────────────────────┐ -│ Phase 3: 实现阶段（使用 Memory） │ -├─────────────────────────────────────────────────────────────┤ -│ Codex 实现 → 读取计划+分析 → 生成代码 │ -│ (.chat/execute-001.md) │ -└─────────────────────┬───────────────────────────────────────┘ - │ 作为 Memory 输入 - ↓ -┌─────────────────────────────────────────────────────────────┐ -│ Phase 4: 验证阶段（使用 Memory） │ -├─────────────────────────────────────────────────────────────┤ -│ Gemini 审查 → 读取实现代码 → 质量报告 │ -│ (.chat/review-001.md) │ -└─────────────────────────────────────────────────────────────┘ - │ - ↓ - 完整的项目 Memory 库 - 支持未来所有决策和实现 -``` - -**最佳实践**： - -1. **保持连续性**：在同一会话中执行相关任务，自动共享 memory -2. **显式引用**：跨会话时明确引用历史分析（如"参考 WFS-xxx 的分析"） -3. **增量更新**：每次分析和实现都追加到 memory，形成完整的决策链 -4. **定期整理**：使用 `/memory:update-related` 将 CLI 结果整合到 CLAUDE.md -5. **质量优先**：高质量的分析 memory 能显著提升后续实现质量 - ---- - -#### 🔄 工作流集成示例 - -**集成到 Lite 工作流**： - -```bash -# 1. 规划阶段：Gemini 分析 -/workflow:lite-plan -e "重构支付模块" -→ 三维确认选择 "CLI 工具执行" - -# 2. 执行阶段：选择执行方式 -# 选项 A: 串联执行 -→ "使用 gemini 分析支付流程" → "让 codex 重构代码" - -# 选项 B: 并行分析 + 串联实现 -→ "用 gemini 分析架构" + "用 qwen 评估方案" -→ "让 codex 基于分析结果重构" -``` - -**集成到 Full 工作流**： - -```bash -# 1. 规划阶段 -/workflow:plan "实现分布式缓存" -/workflow:action-plan-verify - -# 2. 分析阶段（并行） -使用 gemini 分析现有缓存架构 -用 qwen 评估 Redis 集群方案 - -# 3. 实现阶段（串联） -/workflow:execute # 或使用 CLI -让 codex 实现 Redis 集群集成 - -# 4. 测试阶段（并行） -/workflow:test-gen WFS-cache -→ 内部使用 gemini 分析 + codex 生成测试 - -# 5. 审查阶段（串联） -用 gemini 审查代码质量 -/workflow:review --type architecture -``` - ---- - -#### 💡 最佳实践 - -**何时使用串联**： -- 实现依赖设计方案 -- 测试依赖代码实现 -- 优化依赖性能分析 - -**何时使用并行**： -- 多维度分析（安全+性能+架构） -- 多模块独立开发 -- 同时生成代码和测试 - -**何时使用混合**： -- 复杂功能开发（分析→设计→实现→测试） -- 大规模重构（评估→规划→执行→验证） -- 技术栈迁移（调研→方案→实施→优化） - -**工具选择建议**： -1. **需要理解代码** → Gemini（首选）或 Qwen -2. **需要编写代码** → Codex -3. **复杂分析** → Gemini + Qwen 并行（互补验证） -4. **精确实现** → Codex（基于 Gemini 分析） -5. **快速原型** → 直接使用 Codex - ---- - -## 🔄 典型场景完整流程 - -### 场景A：新功能开发（知道怎么做） - -```bash -# 1. 规划 -/workflow:plan "添加JWT认证和权限管理" - -# 2. 验证计划 -/workflow:action-plan-verify - -# 3. 执行 -/workflow:execute - -# 4. 测试 -/workflow:test-gen WFS-jwt-auth -/workflow:execute - -# 5. 审查 -/workflow:review --type security - -# 6. 完成 -/workflow:session:complete -``` - ---- - -### 场景B：新功能开发（不知道怎么做） - -```bash -# 1. 设计探索 -/workflow:brainstorm:auto-parallel "设计分布式缓存系统架构" --count 5 - -# 2. UI设计（如需要） -/workflow:ui-design:explore-auto --prompt "缓存管理后台界面" -/workflow:ui-design:design-sync --session WFS-xxx - -# 3. 规划 -/workflow:plan - -# 4. 验证 -/workflow:action-plan-verify - -# 5. 执行 -/workflow:execute - -# 6. TDD测试 -/workflow:tdd-plan "缓存系统核心模块" -/workflow:execute - -# 7. 审查 -/workflow:review --type architecture -/workflow:review --type security - -# 8. 完成 -/workflow:session:complete -``` - ---- - -### 场景C：快速功能开发（Lite工作流） - -```bash -# 1. 轻量规划（可能需要代码探索） -/workflow:lite-plan -e "优化数据库查询性能" - -# 2. 三维确认 -# - 确认任务 -# - 选择Agent执行 -# - 选择Gemini代码审查 - -# 3. 自动执行（/workflow:lite-execute内部调用） - -# 4. 完成 -``` - ---- - -### 场景D：Bug修复（标准流程） - -```bash -# 1. 标准Bug修复（自动适应严重性） -/workflow:lite-fix "用户登录后token立即过期" - -# 工作流自动执行: -# → Phase 1: 诊断根因（JWT验证逻辑错误） -# → Phase 2: 影响评估（风险评分 7.1 - High） -# → Phase 3: 修复策略（快速补丁 vs 全面重构） -# → Phase 4: 验证计划（集成测试） -# → Phase 5: 用户确认（选择Agent执行） -# → Phase 6: 执行修复 + 生成产物 - -# 2. 会话产物自动保存到: -# .workflow/.lite-fix/user-login-token-expire-2025-01-23-14-30-45/ -# ├── diagnosis.json -# ├── impact.json -# ├── fix-plan.json -# └── task.json - -# 3. 完成 -``` - ---- - -### 场景E：生产热修复（紧急模式） - -```bash -# 1. 热修复模式（最小化诊断） -/workflow:lite-fix --hotfix "支付网关返回 5xx 错误" - -# 工作流自动执行: -# → Phase 1: 最小化诊断（已知问题） -# → Phase 2: 假设 Critical（跳过详细评估） -# → Phase 3: 单一手术式修复 -# → Phase 4: 烟雾测试（2-3分钟） -# → Phase 5: 用户确认部署 -# → Phase 6: 执行 + 自动生成跟进任务 - -# 2. 自动生成跟进任务: -# .workflow/.lite-fix/{session}/followup.json -# ├── FOLLOWUP-001: 全面修复（3天内到期） -# └── FOLLOWUP-002: 事后分析（1周内到期） - -# 3. 完成 -``` - ---- - -## 🎓 命令选择快速参考 - -### 按知识程度选择 - -| 你的情况 | 推荐命令 | -|---------|---------| -| 💭 不知道做什么 | `/workflow:brainstorm:auto-parallel "探索产品方向"` | -| ❓ 知道做什么，不知道怎么做 | `/workflow:brainstorm:auto-parallel "设计技术方案"` | -| ✅ 知道做什么，知道怎么做 | `/workflow:plan "具体实现描述"` | -| ⚡ 简单明确的小任务 | `/workflow:lite-plan "任务描述"` | -| 🐛 标准Bug修复 | `/workflow:lite-fix "bug描述"` | -| 🔥 生产热修复 | `/workflow:lite-fix --hotfix "bug描述"` | - -### 按项目阶段选择 - -| 阶段 | 命令 | -|------|------| -| 📋 **需求分析** | `/workflow:brainstorm:auto-parallel` | -| 🏗️ **架构设计** | `/workflow:brainstorm:auto-parallel` | -| 🎨 **UI设计** | `/workflow:ui-design:explore-auto` / `imitate-auto` | -| 📝 **实现规划** | `/workflow:plan` / `/workflow:lite-plan` | -| 🚀 **编码实现** | `/workflow:execute` / `/workflow:lite-execute` | -| 🐛 **Bug修复** | `/workflow:lite-fix` (标准) / `--hotfix` (紧急) | -| 🧪 **测试** | `/workflow:tdd-plan` / `/workflow:test-gen` | -| 🔧 **测试修复** | `/workflow:test-cycle-execute` | -| 📖 **代码审查** | `/workflow:review` | -| ✅ **项目完成** | `/workflow:session:complete` | - -### 按工作模式选择 - -| 模式 | 工作流 | 适用场景 | -|------|--------|---------| -| **🚀 敏捷快速** | Lite工作流 | 个人开发、快速迭代、原型验证 | -| **🐛 Bug修复** | Lite-Fix工作流 | Bug诊断修复、生产热修复、测试修复循环 | -| **📋 规范完整** | Full工作流 | 团队协作、企业项目、长期维护 | -| **🧪 质量优先** | TDD工作流 | 核心模块、关键功能、高可靠性需求 | -| **🎨 设计导向** | UI-Design工作流 | 前端项目、用户界面、设计系统 | - ---- - -## 💡 专家建议 - -### 🔧 Issue 批量执行工作流 (v6.3.19 新增) - -**适用场景**: 多个相关 Issue 需要批量规划和执行，支持长时间自主工作 - -| 阶段 | 命令 | 说明 | -|------|------|------| -| **规划** | `/issue:plan` | 为 Issue 生成解决方案和任务分解 | -| **排队** | `/issue:queue` | 将解决方案形成执行队列，分析依赖关系 | -| **执行** | `/issue:execute` | DAG 驱动的并行执行，每个解决方案一次提交 | - -**执行器选择**: -| 执行器 | 推荐场景 | 超时 | -|--------|----------|------| -| **Codex (推荐)** | 长时间自主编码，复杂多任务解决方案 | 2小时 | -| Gemini | 需要大上下文分析的实现 | 1小时 | -| Agent | Claude Code 子代理执行复杂任务 | 同步 | - -**为什么推荐 Codex**: -- ✅ **长时间自主工作**: 2小时超时，适合复杂解决方案 -- ✅ **完整写权限**: 自主创建、修改、删除文件 -- ✅ **后台执行**: 支持 `run_in_background: true`，不阻塞其他工作 -- ✅ **工作树隔离**: 配合 `--worktree` 实现真正并行执行 - -**示例工作流**: -```bash -# 1. 规划多个 Issue -/issue:plan ISS-001 ISS-002 ISS-003 - -# 2. 形成执行队列 -/issue:queue - -# 3. 使用 Codex 执行（推荐长时间任务） -/issue:execute --worktree -# → 选择 Codex 执行器 -# → 启用工作树隔离 -# → 并行批次自动执行 -``` - ---- - -### ✅ 最佳实践 - -1. **不确定时用头脑风暴**：宁可多花10分钟探索方案，也不要盲目实现后推翻重来 -2. **Bug修复优先用lite-fix**：自动适应严重性，完整产物跟踪，热修复自动生成跟进任务 -3. **复杂项目用Full工作流**：持久化计划便于团队协作和长期维护 -4. **小任务用Lite工作流**：快速完成，减少overhead -5. **关键模块用TDD**：测试驱动开发保证质量 -6. **定期更新内存**：`/memory:update-related` 保持上下文准确 -7. **批量 Issue 用 issue 工作流**：`/issue:plan` → `/issue:queue` → `/issue:execute`，推荐 Codex 执行长时间任务 - -### ❌ 常见陷阱 - -1. **盲目跳过头脑风暴**：对不熟悉的技术领域也不探索，导致返工 -2. **过度使用头脑风暴**：简单功能也头脑风暴，浪费时间 -3. **忽略计划验证**：不运行 `/workflow:action-plan-verify`，导致执行时发现计划问题 -4. **Bug修复使用错误工具**：复杂Bug用lite-plan而非lite-fix，缺少诊断和影响评估 -5. **忽略测试**：不生成测试，代码质量无法保证 -6. **不完成会话**：不运行 `/workflow:session:complete`，会话状态混乱 - ---- - -## 🔗 相关文档 - -- [Getting Started Guide](GETTING_STARTED.md) - 快速入门教程 -- [Command Reference](COMMAND_REFERENCE.md) - 完整命令列表 -- [Architecture Overview](ARCHITECTURE.md) - 系统架构说明 -- [Examples](EXAMPLES.md) - 真实场景示例 -- [FAQ](FAQ.md) - 常见问题解答 - ---- - -**最后更新**: 2026-01-12 -**版本**: 6.3.19 diff --git a/WORKFLOW_DECISION_GUIDE_EN.md b/WORKFLOW_DECISION_GUIDE_EN.md deleted file mode 100644 index 09a5ca80..00000000 --- a/WORKFLOW_DECISION_GUIDE_EN.md +++ /dev/null @@ -1,744 +0,0 @@ -# 🌳 CCW Workflow Decision Guide - -This guide helps you choose the right commands and workflows for the complete software development lifecycle. - ---- - -## 📊 Full Lifecycle Command Selection Flowchart - -```mermaid -flowchart TD - Start([Start New Feature/Project]) --> Q1{Know what to build?} - - Q1 -->|No| Ideation[💡 Ideation Phase
Requirements Exploration] - Q1 -->|Yes| Q2{Know how to build?} - - Ideation --> BrainIdea[/ /workflow:brainstorm:auto-parallel
Explore product direction and positioning /] - BrainIdea --> Q2 - - Q2 -->|No| Design[🏗️ Design Exploration
Architecture Solution Discovery] - Q2 -->|Yes| Q3{Need UI design?} - - Design --> BrainDesign[/ /workflow:brainstorm:auto-parallel
Explore technical solutions and architecture /] - BrainDesign --> Q3 - - Q3 -->|Yes| UIDesign[🎨 UI Design Phase] - Q3 -->|No| Q4{Task complexity?} - - UIDesign --> Q3a{Have reference design?} - Q3a -->|Yes| UIImitate[/ /workflow:ui-design:imitate-auto
--input local files/images /] - Q3a -->|No| UIExplore[/ /workflow:ui-design:explore-auto
--prompt design description /] - - UIImitate --> UISync[/ /workflow:ui-design:design-sync
Sync design system /] - UIExplore --> UISync - UISync --> Q4 - - Q4 -->|Simple & Quick| LitePlan[⚡ Lightweight Planning
/workflow:lite-plan] - Q4 -->|Complex & Complete| FullPlan[📋 Full Planning
/workflow:plan] - - LitePlan --> Q5{Need code exploration?} - Q5 -->|Yes| LitePlanE[/ /workflow:lite-plan -e
task description /] - Q5 -->|No| LitePlanNormal[/ /workflow:lite-plan
task description /] - - LitePlanE --> LiteConfirm[Three-Dimensional Confirmation:
1️⃣ Task Approval
2️⃣ Execution Method
3️⃣ Code Review] - LitePlanNormal --> LiteConfirm - - LiteConfirm --> Q6{Choose execution method} - Q6 -->|Agent| LiteAgent[/ /workflow:lite-execute
Using @code-developer /] - Q6 -->|CLI Tools| LiteCLI[CLI Execution
Gemini/Qwen/Codex] - Q6 -->|Plan Only| UserImpl[Manual User Implementation] - - FullPlan --> PlanVerify{Verify plan quality?} - PlanVerify -->|Yes| Verify[/ /workflow:action-plan-verify /] - PlanVerify -->|No| Execute - Verify --> Q7{Verification passed?} - Q7 -->|No| FixPlan[Fix plan issues] - Q7 -->|Yes| Execute - FixPlan --> Execute - - Execute[🚀 Execution Phase
/workflow:execute] - LiteAgent --> TestDecision - LiteCLI --> TestDecision - UserImpl --> TestDecision - Execute --> TestDecision - - TestDecision{Need testing?} - TestDecision -->|TDD Mode| TDD[/ /workflow:tdd-plan
Test-Driven Development /] - TestDecision -->|Post-Implementation Testing| TestGen[/ /workflow:test-gen
Generate tests /] - TestDecision -->|Existing Tests| TestCycle[/ /workflow:test-cycle-execute
Test-fix cycle /] - TestDecision -->|No| Review - - TDD --> TDDExecute[/ /workflow:execute
Red-Green-Refactor /] - TDDExecute --> TDDVerify[/ /workflow:tdd-verify
Verify TDD compliance /] - TDDVerify --> Review - - TestGen --> TestExecute[/ /workflow:execute
Execute test tasks /] - TestExecute --> TestResult{Tests passed?} - TestResult -->|No| TestCycle - TestResult -->|Yes| Review - - TestCycle --> TestPass{Pass rate ≥95%?} - TestPass -->|No, continue fixing| TestCycle - TestPass -->|Yes| Review - - Review[📝 Review Phase] - Review --> Q8{Need specialized review?} - Q8 -->|Security| SecurityReview[/ /workflow:review
--type security /] - Q8 -->|Architecture| ArchReview[/ /workflow:review
--type architecture /] - Q8 -->|Quality| QualityReview[/ /workflow:review
--type quality /] - Q8 -->|Comprehensive| GeneralReview[/ /workflow:review
Comprehensive review /] - Q8 -->|No| Complete - - SecurityReview --> Complete - ArchReview --> Complete - QualityReview --> Complete - GeneralReview --> Complete - - Complete[✅ Completion Phase
/workflow:session:complete] - Complete --> End([Project Complete]) - - style Start fill:#e1f5ff - style End fill:#c8e6c9 - style BrainIdea fill:#fff9c4 - style BrainDesign fill:#fff9c4 - style UIImitate fill:#f8bbd0 - style UIExplore fill:#f8bbd0 - style LitePlan fill:#b3e5fc - style FullPlan fill:#b3e5fc - style Execute fill:#c5e1a5 - style TDD fill:#ffccbc - style TestGen fill:#ffccbc - style TestCycle fill:#ffccbc - style Review fill:#d1c4e9 - style Complete fill:#c8e6c9 -``` - ---- - -## 🎯 Decision Point Explanations - -### 1️⃣ **Ideation Phase - "Know what to build?"** - -| Situation | Command | Description | -|-----------|---------|-------------| -| ❌ Uncertain about product direction | `/workflow:brainstorm:auto-parallel "Explore XXX domain product opportunities"` | Multi-role analysis with Product Manager, UX Expert, etc. | -| ✅ Clear feature requirements | Skip to design phase | Already know what functionality to build | - -**Examples**: -```bash -# Uncertain scenario: Want to build a collaboration tool, but unsure what exactly -/workflow:brainstorm:auto-parallel "Explore team collaboration tool positioning and core features" --count 5 - -# Certain scenario: Building a real-time document collaboration editor (requirements clear) -# Skip ideation, move to design phase -``` - ---- - -### 2️⃣ **Design Phase - "Know how to build?"** - -| Situation | Command | Description | -|-----------|---------|-------------| -| ❌ Don't know technical approach | `/workflow:brainstorm:auto-parallel "Design XXX system architecture"` | System Architect, Security Expert analyze technical solutions | -| ✅ Clear implementation path | Skip to planning | Already know tech stack, architecture patterns | - -**Examples**: -```bash -# Don't know how: Real-time collaboration conflict resolution? Which algorithm? -/workflow:brainstorm:auto-parallel "Design conflict resolution mechanism for real-time collaborative document editing" --count 4 - -# Know how: Using Operational Transformation + WebSocket + Redis -# Skip design exploration, go directly to planning -/workflow:plan "Implement real-time collaborative editing using OT algorithm, WebSocket communication, Redis storage" -``` - ---- - -### 3️⃣ **UI Design Phase - "Need UI design?"** - -| Situation | Command | Description | -|-----------|---------|-------------| -| 🎨 Have reference design | `/workflow:ui-design:imitate-auto --input "local files/images"` | Copy design from local reference files/images | -| 🎨 Design from scratch | `/workflow:ui-design:explore-auto --prompt "description"` | Generate multiple design variants | -| ⏭️ Backend/No UI | Skip | Pure backend API, CLI tools, etc. | - -**Examples**: -```bash -# Have reference: Use local screenshots or code files -/workflow:ui-design:imitate-auto --input "design-refs/*.png" -# Or import from existing code -/workflow:ui-design:imitate-auto --input "./src/components" - -# No reference: Design from scratch -/workflow:ui-design:explore-auto --prompt "Modern minimalist document collaboration editing interface" --style-variants 3 - -# Sync design to project -/workflow:ui-design:design-sync --session WFS-xxx --selected-prototypes "v1,v2" -``` - ---- - -### 4️⃣ **Planning Phase - Choose Workflow Type** - -| Workflow | Use Case | Characteristics | -|----------|----------|-----------------| -| `/workflow:lite-plan` | Quick tasks, small features | In-memory planning, three-dimensional confirmation, fast execution | -| `/workflow:plan` | Complex projects, team collaboration | Persistent plans, quality gates, complete traceability | - -**Lite-Plan Three-Dimensional Confirmation**: -1. **Task Approval**: Confirm / Modify / Cancel -2. **Execution Method**: Agent / Provide Plan / CLI Tools (Gemini/Qwen/Codex) -3. **Code Review**: No / Claude / Gemini / Qwen / Codex - -**Examples**: -```bash -# Simple task -/workflow:lite-plan "Add user avatar upload feature" - -# Need code exploration -/workflow:lite-plan -e "Refactor authentication module to OAuth2 standard" - -# Complex project -/workflow:plan "Implement complete real-time collaborative editing system" -/workflow:action-plan-verify # Verify plan quality -/workflow:execute -``` - ---- - -### 5️⃣ **Testing Phase - Choose Testing Strategy** - -| Strategy | Command | Use Case | -|----------|---------|----------| -| **TDD Mode** | `/workflow:tdd-plan` | Starting from scratch, test-driven development | -| **Post-Implementation Testing** | `/workflow:test-gen` | Code complete, add tests | -| **Test Fixing** | `/workflow:test-cycle-execute` | Existing tests, need to fix failures | - -**Examples**: -```bash -# TDD: Write tests first, then implement -/workflow:tdd-plan "User authentication module" -/workflow:execute # Red-Green-Refactor cycle -/workflow:tdd-verify # Verify TDD compliance - -# Post-implementation testing: Add tests after code complete -/workflow:test-gen WFS-user-auth-implementation -/workflow:execute - -# Test fixing: Existing tests with high failure rate -/workflow:test-cycle-execute --max-iterations 5 -# Auto-iterate fixes until pass rate ≥95% -``` - ---- - -### 6️⃣ **Review Phase - Choose Review Type** - -| Type | Command | Focus | -|------|---------|-------| -| **Security Review** | `/workflow:review --type security` | SQL injection, XSS, authentication vulnerabilities | -| **Architecture Review** | `/workflow:review --type architecture` | Design patterns, coupling, scalability | -| **Quality Review** | `/workflow:review --type quality` | Code style, complexity, maintainability | -| **Comprehensive Review** | `/workflow:review` | All-around inspection | - -**Examples**: -```bash -# Security-critical system -/workflow:review --type security - -# After architecture refactoring -/workflow:review --type architecture - -# Daily development -/workflow:review --type quality -``` - ---- - -### 7️⃣ **CLI Tools Collaboration Mode - Multi-Model Intelligent Coordination** - -This project integrates three CLI tools supporting flexible serial, parallel, and hybrid execution: - -| Tool | Core Capabilities | Context Length | Use Cases | -|------|------------------|----------------|-----------| -| **Gemini** | Deep analysis, architecture design, planning | Ultra-long context | Code understanding, execution flow tracing, technical solution evaluation | -| **Qwen** | Code review, pattern recognition | Ultra-long context | Gemini alternative, multi-dimensional analysis | -| **Codex** | Precise code writing, bug location | Standard context | Feature implementation, test generation, code refactoring | - -#### 📋 Three Execution Modes - -**1. Serial Execution** - Sequential dependency - -Use case: Subsequent tasks depend on previous results - -```bash -# Example: Analyze then implement -# Step 1: Gemini analyzes architecture -Use gemini to analyze the authentication module's architecture design, identify key components and data flow - -# Step 2: Codex implements based on analysis -Have codex implement JWT authentication middleware based on the above architecture analysis -``` - -**Execution flow**: -``` -Gemini analysis → Output architecture report → Codex reads report → Implement code -``` - ---- - -**2. Parallel Execution** - Concurrent processing - -Use case: Multiple independent tasks with no dependencies - -```bash -# Example: Multi-dimensional analysis -Use gemini to analyze authentication module security, focus on JWT, password storage, session management -Use qwen to analyze authentication module performance bottlenecks, identify slow queries and optimization points -Have codex generate unit tests for authentication module, covering all core features -``` - -**Execution flow**: -``` - ┌─ Gemini: Security analysis ─┐ -Parallel ┼─ Qwen: Performance analysis ┼─→ Aggregate results - └─ Codex: Test generation ────┘ -``` - ---- - -**3. Hybrid Execution** - Combined serial and parallel - -Use case: Complex tasks with both parallel and serial phases - -```bash -# Example: Complete feature development -# Phase 1: Parallel analysis (independent tasks) -Use gemini to analyze existing authentication system architecture patterns -Use qwen to evaluate OAuth2 integration technical solutions - -# Phase 2: Serial implementation (depends on Phase 1) -Have codex implement OAuth2 authentication flow based on above analysis - -# Phase 3: Parallel optimization (independent tasks) -Use gemini to review code quality and security -Have codex generate integration tests -``` - -**Execution flow**: -``` -Phase 1: Gemini analysis ──┐ - Qwen evaluation ──┼─→ Phase 2: Codex implementation ──→ Phase 3: Gemini review ──┐ - │ Codex tests ───┼─→ Complete - └──────────────────────────────────────────────────────────────┘ -``` - ---- - -#### 🎯 Semantic Invocation vs Command Invocation - -**Method 1: Natural Language Semantic Invocation** (Recommended) - -```bash -# Users simply describe naturally, Claude Code auto-invokes tools -"Use gemini to analyze this module's dependencies" -→ Claude Code auto-generates: cd src && gemini -p "Analyze dependencies" - -"Have codex implement user registration feature" -→ Claude Code auto-generates: codex -C src/auth --full-auto exec "Implement registration" -``` - ---- - -#### 🔗 Semantic Invocation & Results Context (Memory) - -Through natural language, Claude automatically selects and executes appropriate CLI tools (Gemini/Qwen/Codex), with results serving as context for subsequent operations. - -**1. Semantic Invocation Examples** - -```bash -# Describe needs in natural language, Claude auto-selects tools -"Use gemini to analyze authentication module architecture" -→ Claude auto-executes Gemini CLI and saves results - -"Have qwen evaluate performance bottlenecks" -→ Claude auto-executes Qwen CLI and saves results - -"Use codex to implement this feature" -→ Claude auto-executes Codex CLI -``` - -**2. Results as Planning Basis** - -```bash -# Step 1: Analyze current state (generate memory) -Use gemini to deeply analyze authentication system architecture, security, and performance issues -→ Output: Detailed analysis report (auto-saved) - -# Step 2: Plan based on analysis results -/workflow:plan "Refactor authentication system based on above Gemini analysis report" -→ System automatically reads analysis reports from .chat/ as context -→ Generate precise implementation plan -``` - -**3. Results as Implementation Basis** - -```bash -# Step 1: Parallel analysis (generate multiple memories) -Use gemini to analyze existing code structure -Use qwen to evaluate technical solution feasibility -→ Output: Multiple analysis reports - -# Step 2: Implement based on all analysis results -Have codex synthesize above Gemini and Qwen analyses to implement optimal solution -→ Codex automatically reads prior analysis results -→ Generate code conforming to architecture design -``` - -**4. Cross-Session References** - -```bash -# Reference historical session analysis results -"Refer to architecture analysis in WFS-2024-001, use codex to implement new payment module" -→ Claude automatically loads specified session context -→ Implement based on historical analysis -``` - -**5. Memory Update Loop** - -```bash -# Iterative optimization flow -Use gemini to analyze problems in current implementation -→ Generate problem report (memory) - -Have codex optimize code based on problem report -→ Implement improvements (update memory) - -Use qwen to verify optimization effectiveness -→ Verification report (append to memory) - -# All results accumulate as complete project memory -→ Support subsequent decisions and implementation -``` - -**Memory Flow Example**: - -``` -┌─────────────────────────────────────────────────────────────┐ -│ Phase 1: Analysis Phase (Generate Memory) │ -├─────────────────────────────────────────────────────────────┤ -│ Gemini analysis → Architecture report (.chat/analyze-001.md)│ -│ Qwen evaluation → Solution report (.chat/analyze-002.md) │ -└─────────────────────┬───────────────────────────────────────┘ - │ As Memory Input - ↓ -┌─────────────────────────────────────────────────────────────┐ -│ Phase 2: Planning Phase (Use Memory) │ -├─────────────────────────────────────────────────────────────┤ -│ /workflow:plan → Read analysis reports → Generate plan │ -│ (.task/IMPL-*.json) │ -└─────────────────────┬───────────────────────────────────────┘ - │ As Memory Input - ↓ -┌─────────────────────────────────────────────────────────────┐ -│ Phase 3: Implementation Phase (Use Memory) │ -├─────────────────────────────────────────────────────────────┤ -│ Codex implement → Read plan+analysis → Generate code │ -│ (.chat/execute-001.md) │ -└─────────────────────┬───────────────────────────────────────┘ - │ As Memory Input - ↓ -┌─────────────────────────────────────────────────────────────┐ -│ Phase 4: Verification Phase (Use Memory) │ -├─────────────────────────────────────────────────────────────┤ -│ Gemini review → Read implementation code → Quality report│ -│ (.chat/review-001.md) │ -└─────────────────────────────────────────────────────────────┘ - │ - ↓ - Complete Project Memory Library - Supporting All Future Decisions and Implementation -``` - -**Best Practices**: - -1. **Maintain Continuity**: Execute related tasks in the same session to automatically share memory -2. **Explicit References**: Explicitly reference historical analyses when crossing sessions (e.g., "Refer to WFS-xxx analysis") -3. **Incremental Updates**: Each analysis and implementation appends to memory, forming complete decision chain -4. **Regular Organization**: Use `/memory:update-related` to consolidate CLI results into CLAUDE.md -5. **Quality First**: High-quality analysis memory significantly improves subsequent implementation quality - ---- - -#### 🔄 Workflow Integration Examples - -**Integration with Lite Workflow**: - -```bash -# 1. Planning phase: Gemini analysis -/workflow:lite-plan -e "Refactor payment module" -→ Three-dimensional confirmation selects "CLI Tools execution" - -# 2. Execution phase: Choose execution method -# Option A: Serial execution -→ "Use gemini to analyze payment flow" → "Have codex refactor code" - -# Option B: Parallel analysis + Serial implementation -→ "Use gemini to analyze architecture" + "Use qwen to evaluate solution" -→ "Have codex refactor based on analysis results" -``` - -**Integration with Full Workflow**: - -```bash -# 1. Planning phase -/workflow:plan "Implement distributed cache" -/workflow:action-plan-verify - -# 2. Analysis phase (parallel) -Use gemini to analyze existing cache architecture -Use qwen to evaluate Redis cluster solution - -# 3. Implementation phase (serial) -/workflow:execute # Or use CLI -Have codex implement Redis cluster integration - -# 4. Testing phase (parallel) -/workflow:test-gen WFS-cache -→ Internally uses gemini analysis + codex test generation - -# 5. Review phase (serial) -Use gemini to review code quality -/workflow:review --type architecture -``` - ---- - -#### 💡 Best Practices - -**When to use serial**: -- Implementation depends on design solution -- Testing depends on code implementation -- Optimization depends on performance analysis - -**When to use parallel**: -- Multi-dimensional analysis (security + performance + architecture) -- Multi-module independent development -- Simultaneous code and test generation - -**When to use hybrid**: -- Complex feature development (analysis → design → implementation → testing) -- Large-scale refactoring (evaluation → planning → execution → verification) -- Tech stack migration (research → solution → implementation → optimization) - -**Tool selection guidelines**: -1. **Need to understand code** → Gemini (preferred) or Qwen -2. **Need to write code** → Codex -3. **Complex analysis** → Gemini + Qwen parallel (complementary verification) -4. **Precise implementation** → Codex (based on Gemini analysis) -5. **Quick prototype** → Direct Codex usage - ---- - -## 🔄 Complete Flow for Typical Scenarios - -### Scenario A: New Feature Development (Know How to Build) - -```bash -# 1. Planning -/workflow:plan "Add JWT authentication and permission management" - -# 2. Verify plan -/workflow:action-plan-verify - -# 3. Execute -/workflow:execute - -# 4. Testing -/workflow:test-gen WFS-jwt-auth -/workflow:execute - -# 5. Review -/workflow:review --type security - -# 6. Complete -/workflow:session:complete -``` - ---- - -### Scenario B: New Feature Development (Don't Know How to Build) - -```bash -# 1. Design exploration -/workflow:brainstorm:auto-parallel "Design distributed cache system architecture" --count 5 - -# 2. UI design (if needed) -/workflow:ui-design:explore-auto --prompt "Cache management dashboard interface" -/workflow:ui-design:design-sync --session WFS-xxx - -# 3. Planning -/workflow:plan - -# 4. Verification -/workflow:action-plan-verify - -# 5. Execution -/workflow:execute - -# 6. TDD testing -/workflow:tdd-plan "Cache system core modules" -/workflow:execute - -# 7. Review -/workflow:review --type architecture -/workflow:review --type security - -# 8. Complete -/workflow:session:complete -``` - ---- - -### Scenario C: Quick Feature Development (Lite Workflow) - -```bash -# 1. Lightweight planning (may need code exploration) -/workflow:lite-plan -e "Optimize database query performance" - -# 2. Three-dimensional confirmation -# - Confirm task -# - Choose Agent execution -# - Choose Gemini code review - -# 3. Auto-execution (called internally by /workflow:lite-execute) - -# 4. Complete -``` - ---- - -### Scenario D: Bug Fixing - -```bash -# 1. Intelligent bug fix workflow (includes diagnosis) -/workflow:lite-fix "User login fails with token expired error" - -# 2. Test fix (if needed) -/workflow:test-cycle-execute - -# 3. Complete -``` - ---- - -## 🎓 Quick Command Reference - -### Choose by Knowledge Level - -| Your Situation | Recommended Command | -|----------------|---------------------| -| 💭 Don't know what to build | `/workflow:brainstorm:auto-parallel "Explore product direction"` | -| ❓ Know what, don't know how | `/workflow:brainstorm:auto-parallel "Design technical solution"` | -| ✅ Know what and how | `/workflow:plan "Specific implementation description"` | -| ⚡ Simple, clear small task | `/workflow:lite-plan "Task description"` | -| 🐛 Bug fixing | `/workflow:lite-fix "bug description"` | - -### Choose by Project Phase - -| Phase | Command | -|-------|---------| -| 📋 **Requirements Analysis** | `/workflow:brainstorm:auto-parallel` | -| 🏗️ **Architecture Design** | `/workflow:brainstorm:auto-parallel` | -| 🎨 **UI Design** | `/workflow:ui-design:explore-auto` / `imitate-auto` | -| 📝 **Implementation Planning** | `/workflow:plan` / `/workflow:lite-plan` | -| 🚀 **Coding Implementation** | `/workflow:execute` / `/workflow:lite-execute` | -| 🧪 **Testing** | `/workflow:tdd-plan` / `/workflow:test-gen` | -| 🔧 **Test Fixing** | `/workflow:test-cycle-execute` | -| 📖 **Code Review** | `/workflow:review` | -| ✅ **Project Completion** | `/workflow:session:complete` | - -### Choose by Work Mode - -| Mode | Workflow | Use Case | -|------|----------|----------| -| **🚀 Agile & Fast** | Lite Workflow | Personal dev, rapid iteration, prototype validation | -| **📋 Standard & Complete** | Full Workflow | Team collaboration, enterprise projects, long-term maintenance | -| **🧪 Quality-First** | TDD Workflow | Core modules, critical features, high reliability requirements | -| **🎨 Design-Driven** | UI-Design Workflow | Frontend projects, user interfaces, design systems | - ---- - -## 💡 Expert Advice - -### 🔧 Issue Batch Execution Workflow (v6.3.19 New) - -**Use Case**: Multiple related issues requiring batch planning and execution, supports long-running autonomous work - -| Phase | Command | Description | -|-------|---------|-------------| -| **Plan** | `/issue:plan` | Generate solutions and task breakdown for issues | -| **Queue** | `/issue:queue` | Form execution queue, analyze dependencies | -| **Execute** | `/issue:execute` | DAG-driven parallel execution, one commit per solution | - -**Executor Selection**: -| Executor | Recommended For | Timeout | -|----------|-----------------|---------| -| **Codex (Recommended)** | Long-running autonomous coding, complex multi-task solutions | 2 hours | -| Gemini | Large context analysis and implementation | 1 hour | -| Agent | Claude Code sub-agent for complex tasks | Sync | - -**Why Codex is Recommended**: -- ✅ **Long-running autonomous work**: 2-hour timeout, suitable for complex solutions -- ✅ **Full write access**: Autonomously create, modify, delete files -- ✅ **Background execution**: Supports `run_in_background: true`, non-blocking -- ✅ **Worktree isolation**: Combined with `--worktree` for true parallel execution - -**Example Workflow**: -```bash -# 1. Plan multiple issues -/issue:plan ISS-001 ISS-002 ISS-003 - -# 2. Form execution queue -/issue:queue - -# 3. Execute with Codex (recommended for long tasks) -/issue:execute --worktree -# → Select Codex executor -# → Enable worktree isolation -# → Parallel batches auto-execute -``` - ---- - -### ✅ Best Practices - -1. **Use brainstorming when uncertain**: Better to spend 10 minutes exploring solutions than blindly implementing and rewriting -2. **Use Full workflow for complex projects**: Persistent plans facilitate team collaboration and long-term maintenance -3. **Use Lite workflow for small tasks**: Complete quickly, reduce overhead -4. **Use TDD for critical modules**: Test-driven development ensures quality -5. **Regularly update memory**: `/memory:update-related` keeps context accurate -6. **Use issue workflow for batch issues**: `/issue:plan` → `/issue:queue` → `/issue:execute`, recommend Codex for long-running tasks - -### ❌ Common Pitfalls - -1. **Blindly skipping brainstorming**: Not exploring unfamiliar technical domains leads to rework -2. **Overusing brainstorming**: Brainstorming even simple features wastes time -3. **Ignoring plan verification**: Not running `/workflow:action-plan-verify` causes execution issues -4. **Ignoring testing**: Not generating tests, code quality cannot be guaranteed -5. **Not completing sessions**: Not running `/workflow:session:complete` causes session state confusion - ---- - -## 🔗 Related Documentation - -- [Getting Started Guide](GETTING_STARTED.md) - Quick start tutorial -- [Command Reference](COMMAND_REFERENCE.md) - Complete command list -- [Architecture Overview](ARCHITECTURE.md) - System architecture explanation -- [Examples](EXAMPLES.md) - Real-world scenario examples -- [FAQ](FAQ.md) - Frequently asked questions - ---- - -**Last Updated**: 2026-01-12 -**Version**: 6.3.19 diff --git a/WORKFLOW_DIAGRAMS.md b/WORKFLOW_DIAGRAMS.md deleted file mode 100644 index 2fa4d426..00000000 --- a/WORKFLOW_DIAGRAMS.md +++ /dev/null @@ -1,764 +0,0 @@ -# Claude Code Workflow (CCW) - Enhanced Workflow Diagrams - -Based on comprehensive analysis of changes since v1.0, this document provides detailed mermaid diagrams illustrating the CCW architecture and execution flows. - -## 1. System Architecture Overview - -```mermaid -graph TB - subgraph "CLI Interface Layer" - CLI[CLI Commands] - GEM[Gemini CLI] - COD[Codex CLI] - WRAPPER[Gemini Wrapper] - end - - subgraph "Session Management" - SESSION["workflow-session.json"] - WDIR[".workflow/ directories"] - ACTIVE_DIR[".workflow/active/"] - ARCHIVE_DIR[".workflow/archives/"] - end - - subgraph "Task System" - TASK_JSON[".task/impl-*.json"] - HIERARCHY["Task Hierarchy (max 2 levels)"] - STATUS["Task Status Management"] - end - - subgraph "Agent Orchestration" - PLAN_AGENT[Conceptual Planning Agent] - ACTION_AGENT[Action Planning Agent] - CODE_AGENT[Code Developer] - REVIEW_AGENT[Code Review Agent] - MEMORY_AGENT[Memory Gemini Bridge] - end - - subgraph "Template System" - ANALYSIS_TMPL[Analysis Templates] - DEV_TMPL[Development Templates] - PLAN_TMPL[Planning Templates] - REVIEW_TMPL[Review Templates] - end - - subgraph "Output Generation" - TODO_MD["TODO_LIST.md"] - IMPL_MD["IMPL_PLAN.md"] - SUMMARY[".summaries/"] - CHAT[".chat/ sessions"] - end - - CLI --> GEM - CLI --> COD - CLI --> WRAPPER - WRAPPER --> GEM - - GEM --> PLAN_AGENT - COD --> CODE_AGENT - - PLAN_AGENT --> TASK_JSON - ACTION_AGENT --> TASK_JSON - CODE_AGENT --> TASK_JSON - - TASK_JSON --> HIERARCHY - HIERARCHY --> STATUS - - SESSION --> MARKER - MARKER --> WDIR - - ANALYSIS_TMPL --> GEM - DEV_TMPL --> COD - PLAN_TMPL --> PLAN_AGENT - - TASK_JSON --> TODO_MD - TASK_JSON --> IMPL_MD - STATUS --> SUMMARY - GEM --> CHAT - COD --> CHAT -``` - -## 2. Command Execution Flow - -```mermaid -sequenceDiagram - participant User - participant CLI - participant GeminiWrapper as Gemini Wrapper - participant GeminiCLI as Gemini CLI - participant CodexCLI as Codex CLI - participant Agent - participant TaskSystem as Task System - participant FileSystem as File System - - User->>CLI: Command Request - CLI->>CLI: Parse Command Type - - alt Analysis Task - CLI->>GeminiWrapper: Analysis Request - GeminiWrapper->>GeminiWrapper: Check Token Limit - GeminiWrapper->>GeminiWrapper: Set Approval Mode - GeminiWrapper->>GeminiCLI: Execute Analysis - GeminiCLI->>FileSystem: Read Codebase - GeminiCLI->>Agent: Route to Planning Agent - else Development Task - CLI->>CodexCLI: Development Request - CodexCLI->>Agent: Route to Code Agent - end - - Agent->>TaskSystem: Create/Update Tasks - TaskSystem->>FileSystem: Save task JSON - Agent->>Agent: Execute Task Logic - Agent->>FileSystem: Apply Changes - Agent->>TaskSystem: Update Task Status - TaskSystem->>FileSystem: Regenerate Markdown Views - Agent->>CLI: Return Results - CLI->>User: Display Results -``` - -## 3. Session Management Flow - -```mermaid -stateDiagram-v2 - [*] --> SessionInit: Create New Session - - SessionInit --> CreateStructure: mkdir .workflow/WFS-session-name - CreateStructure --> CreateJSON: Create workflow-session.json - CreateJSON --> CreatePlan: Create IMPL_PLAN.md - CreatePlan --> CreateTasks: Create .task/ directory - CreateTasks --> Active: Session Ready in .workflow/active/ - - Active --> Paused: Switch to Another Session - Active --> Working: Execute Tasks - Active --> Completed: All Tasks Done - - Paused --> Active: Resume Session (set marker) - Working --> Active: Task Complete - Completed --> [*]: Archive Session - - state Working { - [*] --> TaskExecution - TaskExecution --> AgentProcessing - AgentProcessing --> TaskUpdate - TaskUpdate --> [*] - } -``` - -## 4. Task Lifecycle Management - -```mermaid -graph TD - subgraph "Task Creation" - REQ[Requirements] --> ANALYZE{Analysis Needed?} - ANALYZE -->|Yes| GEMINI[Gemini Analysis] - ANALYZE -->|No| DIRECT[Direct Creation] - GEMINI --> CONTEXT[Extract Context] - CONTEXT --> TASK_JSON[Create impl-*.json] - DIRECT --> TASK_JSON - end - - subgraph "Task Hierarchy" - TASK_JSON --> SIMPLE{<5 Tasks?} - SIMPLE -->|Yes| SINGLE[Single Level: impl-N] - SIMPLE -->|No| MULTI[Two Levels: impl-N.M] - - SINGLE --> EXEC1[Direct Execution] - MULTI --> DECOMP[Task Decomposition] - DECOMP --> SUBTASKS[Create Subtasks] - SUBTASKS --> EXEC2[Execute Leaf Tasks] - end - - subgraph "Task Execution" - EXEC1 --> AGENT_SELECT[Select Agent] - EXEC2 --> AGENT_SELECT - AGENT_SELECT --> PLAN_A[Planning Agent] - AGENT_SELECT --> CODE_A[Code Agent] - AGENT_SELECT --> REVIEW_A[Review Agent] - - PLAN_A --> UPDATE_STATUS[Update Status] - CODE_A --> UPDATE_STATUS - REVIEW_A --> UPDATE_STATUS - - UPDATE_STATUS --> COMPLETED{All Done?} - COMPLETED -->|No| NEXT_TASK[Next Task] - COMPLETED -->|Yes| SUMMARY[Generate Summary] - - NEXT_TASK --> AGENT_SELECT - SUMMARY --> REGEN[Regenerate Views] - REGEN --> DONE[Session Complete] - end -``` - -## 5. CLI Tool Integration Architecture - -```mermaid -graph TB - subgraph "User Input Layer" - CMD[User Commands] - INTENT{Task Intent} - end - - subgraph "CLI Routing Layer" - DISPATCHER[Command Dispatcher] - GEMINI_ROUTE[Gemini Route] - CODEX_ROUTE[Codex Route] - end - - subgraph "Gemini Analysis Path" - WRAPPER[Gemini Wrapper] - TOKEN_CHECK{Token Limit Check} - APPROVAL_MODE[Set Approval Mode] - GEMINI_EXEC[Gemini Execution] - - subgraph "Gemini Features" - ALL_FILES[--all-files Mode] - PATTERNS["@{pattern} Mode"] - TEMPLATES[Template Integration] - end - end - - subgraph "Codex Development Path" - CODEX_EXEC[Codex --full-auto exec] - AUTO_DISCOVERY[Automatic File Discovery] - CONTEXT_AWARE[Context-Aware Execution] - - subgraph "Codex Features" - EXPLICIT_PATTERNS["@{pattern} Control"] - AUTONOMOUS[Full Autonomous Mode] - TEMPLATE_INTEGRATION[Template Support] - end - end - - subgraph "Backend Processing" - FILE_ANALYSIS[File Analysis] - CONTEXT_EXTRACTION[Context Extraction] - CODE_GENERATION[Code Generation] - VALIDATION[Validation & Testing] - end - - subgraph "Output Layer" - RESULTS[Command Results] - ARTIFACTS[Generated Artifacts] - DOCUMENTATION[Updated Documentation] - end - - CMD --> INTENT - INTENT -->|Analyze/Review/Understand| GEMINI_ROUTE - INTENT -->|Implement/Build/Develop| CODEX_ROUTE - - GEMINI_ROUTE --> WRAPPER - WRAPPER --> TOKEN_CHECK - TOKEN_CHECK -->|<2M tokens| ALL_FILES - TOKEN_CHECK -->|>2M tokens| PATTERNS - ALL_FILES --> APPROVAL_MODE - PATTERNS --> APPROVAL_MODE - APPROVAL_MODE --> GEMINI_EXEC - GEMINI_EXEC --> TEMPLATES - - CODEX_ROUTE --> CODEX_EXEC - CODEX_EXEC --> AUTO_DISCOVERY - AUTO_DISCOVERY --> CONTEXT_AWARE - CONTEXT_AWARE --> AUTONOMOUS - AUTONOMOUS --> TEMPLATE_INTEGRATION - - TEMPLATES --> FILE_ANALYSIS - TEMPLATE_INTEGRATION --> FILE_ANALYSIS - - FILE_ANALYSIS --> CONTEXT_EXTRACTION - CONTEXT_EXTRACTION --> CODE_GENERATION - CODE_GENERATION --> VALIDATION - VALIDATION --> RESULTS - - RESULTS --> ARTIFACTS - ARTIFACTS --> DOCUMENTATION -``` - -## 6. Agent Workflow Coordination - -```mermaid -sequenceDiagram - participant TaskSystem as Task System - participant PlanningAgent as Conceptual Planning - participant ActionAgent as Action Planning - participant CodeAgent as Code Developer - participant ReviewAgent as Code Review - participant MemoryAgent as Memory Bridge - - TaskSystem->>PlanningAgent: New Complex Task - PlanningAgent->>PlanningAgent: Strategic Analysis - PlanningAgent->>ActionAgent: High-Level Plan - - ActionAgent->>ActionAgent: Break Down into Tasks - ActionAgent->>TaskSystem: Create Task Hierarchy - TaskSystem->>TaskSystem: Generate impl-*.json files - - loop For Each Implementation Task - TaskSystem->>CodeAgent: Execute Task - CodeAgent->>CodeAgent: Analyze Context - CodeAgent->>CodeAgent: Generate Code - CodeAgent->>TaskSystem: Update Status - - TaskSystem->>ReviewAgent: Review Code - ReviewAgent->>ReviewAgent: Quality Check - ReviewAgent->>ReviewAgent: Test Validation - ReviewAgent->>TaskSystem: Approval/Feedback - - alt Code Needs Revision - TaskSystem->>CodeAgent: Implement Changes - else Code Approved - TaskSystem->>TaskSystem: Mark Complete - end - end - - TaskSystem->>MemoryAgent: Update Documentation - MemoryAgent->>MemoryAgent: Generate Summaries - MemoryAgent->>MemoryAgent: Update README/Docs - MemoryAgent->>TaskSystem: Documentation Complete -``` - -## 7. Template System Architecture - -```mermaid -graph LR - subgraph "Template Categories" - ANALYSIS[Analysis Templates] - DEVELOPMENT[Development Templates] - PLANNING[Planning Templates] - AUTOMATION[Automation Templates] - REVIEW[Review Templates] - INTEGRATION[Integration Templates] - end - - subgraph "Template Files" - ANALYSIS --> PATTERN[pattern.txt] - ANALYSIS --> ARCH[architecture.txt] - ANALYSIS --> SECURITY[security.txt] - - DEVELOPMENT --> FEATURE[feature.txt] - DEVELOPMENT --> COMPONENT[component.txt] - DEVELOPMENT --> REFACTOR[refactor.txt] - - PLANNING --> BREAKDOWN[task-breakdown.txt] - PLANNING --> MIGRATION[migration.txt] - - AUTOMATION --> SCAFFOLD[scaffold.txt] - AUTOMATION --> DEPLOY[deployment.txt] - - REVIEW --> CODE_REVIEW[code-review.txt] - - INTEGRATION --> API[api-design.txt] - INTEGRATION --> DATABASE[database.txt] - end - - subgraph "Usage Integration" - CLI_GEMINI[Gemini CLI] - CLI_CODEX[Codex CLI] - AGENTS[Agent System] - - CLI_GEMINI --> ANALYSIS - CLI_CODEX --> DEVELOPMENT - CLI_CODEX --> AUTOMATION - AGENTS --> PLANNING - AGENTS --> REVIEW - AGENTS --> INTEGRATION - end - - subgraph "Template Resolution" - CAT_CMD["$(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt)"] - MULTI_TMPL[Multi-Template Composition] - HEREDOC[HEREDOC Support] - end - - PATTERN --> CAT_CMD - FEATURE --> CAT_CMD - BREAKDOWN --> CAT_CMD - - CAT_CMD --> MULTI_TMPL - MULTI_TMPL --> HEREDOC - HEREDOC --> CLI_GEMINI - HEREDOC --> CLI_CODEX -``` - -## 8. Complexity Management System - -```mermaid -flowchart TD - INPUT[Task Input] --> ASSESS{Assess Complexity} - - ASSESS -->|<5 tasks| SIMPLE[Simple Workflow] - ASSESS -->|5-15 tasks| MEDIUM[Medium Workflow] - ASSESS -->|>15 tasks| COMPLEX[Complex Workflow] - - subgraph "Simple Workflow" - SIMPLE_STRUCT[Single-Level: impl-N] - SIMPLE_EXEC[Direct Execution] - SIMPLE_MIN[Minimal Overhead] - - SIMPLE --> SIMPLE_STRUCT - SIMPLE_STRUCT --> SIMPLE_EXEC - SIMPLE_EXEC --> SIMPLE_MIN - end - - subgraph "Medium Workflow" - MEDIUM_STRUCT[Two-Level: impl-N.M] - MEDIUM_PROGRESS[Progress Tracking] - MEDIUM_DOCS[Auto Documentation] - - MEDIUM --> MEDIUM_STRUCT - MEDIUM_STRUCT --> MEDIUM_PROGRESS - MEDIUM_PROGRESS --> MEDIUM_DOCS - end - - subgraph "Complex Workflow" - COMPLEX_STRUCT[Deep Hierarchy] - COMPLEX_ORCHESTRATION[Multi-Agent Orchestration] - COMPLEX_COORD[Full Coordination] - - COMPLEX --> COMPLEX_STRUCT - COMPLEX_STRUCT --> COMPLEX_ORCHESTRATION - COMPLEX_ORCHESTRATION --> COMPLEX_COORD - end - - subgraph "Dynamic Adaptation" - RUNTIME_UPGRADE[Runtime Complexity Upgrade] - SATURATION_CONTROL[Task Saturation Control] - INTELLIGENT_DECOMP[Intelligent Decomposition] - end - - SIMPLE_MIN --> RUNTIME_UPGRADE - MEDIUM_DOCS --> RUNTIME_UPGRADE - COMPLEX_COORD --> SATURATION_CONTROL - SATURATION_CONTROL --> INTELLIGENT_DECOMP -``` - -## Key Architectural Changes Since v1.0 - -### Major Enhancements: -1. **Intelligent Task Saturation Control**: Prevents overwhelming agents with too many simultaneous tasks -2. **Gemini Wrapper Intelligence**: Automatic token management and approval mode detection -3. **Path-Specific Analysis**: Task-specific path management for precise CLI analysis -4. **Template System Integration**: Unified template system across all CLI tools -5. **Session Context Passing**: Proper context management for agent coordination -6. **On-Demand File Creation**: Improved performance through lazy initialization -7. **Enhanced Error Handling**: Comprehensive error logging and recovery -8. **Codex Full-Auto Mode**: Maximum autonomous development capabilities -9. **Cross-Tool Template Compatibility**: Seamless template sharing between Gemini and Codex - -### Performance Improvements: -- 10-minute execution timeout for complex operations -- Sub-millisecond JSON query performance -- Atomic session switching with zero overhead -- Intelligent file discovery reducing context switching - -## 9. Complete Development Workflow (Workflow vs Task Commands) - -```mermaid -graph TD - START[Project Requirement] --> SESSION["/workflow:session:start"] - - SESSION --> PLANNING_CHOICE{Choose Planning Method} - - PLANNING_CHOICE -->|Collaborative Analysis| BRAINSTORM["/workflow:brainstorm"] - PLANNING_CHOICE -->|AI-Powered Planning| GEMINI_PLAN["/gemini:mode:plan"] - PLANNING_CHOICE -->|Document Analysis| DOC_ANALYSIS["Document Review"] - PLANNING_CHOICE -->|Direct Planning| DIRECT_PLAN["/workflow:plan"] - - subgraph "Brainstorming Path" - BRAINSTORM --> SYNTHESIS["/workflow:brainstorm:synthesis"] - SYNTHESIS --> BRAINSTORM_PLAN["/workflow:plan --from-brainstorming"] - end - - subgraph "Gemini Planning Path" - GEMINI_PLAN --> GEMINI_ANALYSIS["Gemini Analysis Results"] - GEMINI_ANALYSIS --> GEMINI_WF_PLAN["/workflow:plan"] - end - - subgraph "Document Analysis Path" - DOC_ANALYSIS --> DOC_INSIGHTS["Extract Requirements"] - DOC_INSIGHTS --> DOC_PLAN["/workflow:plan"] - end - - BRAINSTORM_PLAN --> WORKFLOW_EXECUTE - GEMINI_WF_PLAN --> WORKFLOW_EXECUTE - DOC_PLAN --> WORKFLOW_EXECUTE - DIRECT_PLAN --> WORKFLOW_EXECUTE - - WORKFLOW_EXECUTE["/workflow:execute"] --> TASK_CREATION["Auto-Create Tasks"] - - subgraph "Task Management Layer" - TASK_CREATION --> TASK_BREAKDOWN["/task:breakdown"] - TASK_BREAKDOWN --> TASK_EXECUTE["/task:execute"] - TASK_EXECUTE --> TASK_STATUS{Task Status} - - TASK_STATUS -->|More Tasks| NEXT_TASK["/task:execute next"] - TASK_STATUS -->|Blocked| TASK_REPLAN["/task:replan"] - TASK_STATUS -->|Complete| TASK_DONE[Task Complete] - - NEXT_TASK --> TASK_EXECUTE - TASK_REPLAN --> TASK_EXECUTE - end - - TASK_DONE --> ALL_DONE{All Tasks Done?} - ALL_DONE -->|No| TASK_EXECUTE - ALL_DONE -->|Yes| WORKFLOW_REVIEW["/workflow:review"] - - WORKFLOW_REVIEW --> FINAL_DOCS["/update-memory-related"] - FINAL_DOCS --> PROJECT_COMPLETE[Project Complete] -``` - -## 10. Workflow Command Relationships - -```mermaid -graph LR - subgraph "Session Management" - WFS_START["/workflow:session:start"] - WFS_RESUME["/workflow:session:resume"] - WFS_LIST["/workflow:session:list"] - WFS_COMPLETE["/workflow:session:complete"] - - WFS_START --> WFS_LIST - WFS_LIST --> WFS_RESUME - WFS_RESUME --> WFS_COMPLETE - end - - subgraph "Planning Phase" - WF_BRAINSTORM["/workflow:brainstorm"] - WF_PLAN["/workflow:plan"] - WF_PLAN_DEEP["/workflow:plan-deep"] - - WF_BRAINSTORM --> WF_PLAN - WF_PLAN_DEEP --> WF_PLAN - end - - subgraph "Execution Phase" - WF_EXECUTE["/workflow:execute"] - WF_REVIEW["/workflow:review"] - - WF_EXECUTE --> WF_REVIEW - end - - subgraph "Task Layer" - TASK_CREATE["/task:create"] - TASK_BREAKDOWN["/task:breakdown"] - TASK_EXECUTE["/task:execute"] - TASK_REPLAN["/task:replan"] - - TASK_CREATE --> TASK_BREAKDOWN - TASK_BREAKDOWN --> TASK_EXECUTE - TASK_EXECUTE --> TASK_REPLAN - TASK_REPLAN --> TASK_EXECUTE - end - - WFS_START --> WF_BRAINSTORM - WF_PLAN --> WF_EXECUTE - WF_EXECUTE --> TASK_CREATE -``` - -## 11. Planning Method Selection Flow - -```mermaid -flowchart TD - PROJECT_START[New Project/Feature] --> COMPLEXITY{Assess Complexity} - - COMPLEXITY -->|Simple < 5 tasks| SIMPLE_FLOW - COMPLEXITY -->|Medium 5-15 tasks| MEDIUM_FLOW - COMPLEXITY -->|Complex > 15 tasks| COMPLEX_FLOW - - subgraph SIMPLE_FLOW["Simple Workflow"] - S_DIRECT["/workflow:plan (direct)"] - S_EXECUTE["/workflow:execute --type=simple"] - S_TASKS["Direct task execution"] - - S_DIRECT --> S_EXECUTE --> S_TASKS - end - - subgraph MEDIUM_FLOW["Medium Workflow"] - M_CHOICE{Planning Method?} - M_GEMINI["/gemini:mode:plan"] - M_DOCS["Review existing docs"] - M_PLAN["/workflow:plan"] - M_EXECUTE["/workflow:execute --type=medium"] - M_BREAKDOWN["/task:breakdown"] - - M_CHOICE -->|AI Planning| M_GEMINI - M_CHOICE -->|Documentation| M_DOCS - M_GEMINI --> M_PLAN - M_DOCS --> M_PLAN - M_PLAN --> M_EXECUTE - M_EXECUTE --> M_BREAKDOWN - end - - subgraph COMPLEX_FLOW["Complex Workflow"] - C_BRAINSTORM["/workflow:brainstorm --perspectives=multiple"] - C_SYNTHESIS["/workflow:brainstorm:synthesis"] - C_PLAN_DEEP["/workflow:plan-deep"] - C_PLAN["/workflow:plan --from-brainstorming"] - C_EXECUTE["/workflow:execute --type=complex"] - C_TASKS["Hierarchical task management"] - - C_BRAINSTORM --> C_SYNTHESIS - C_SYNTHESIS --> C_PLAN_DEEP - C_PLAN_DEEP --> C_PLAN - C_PLAN --> C_EXECUTE - C_EXECUTE --> C_TASKS - end -``` - -## 12. Brainstorming to Execution Pipeline - -```mermaid -sequenceDiagram - participant User - participant WF as Workflow System - participant BS as Brainstorm Agents - participant PLAN as Planning Agent - participant TASK as Task System - participant EXEC as Execution Agents - - User->>WF: /workflow:session:start "Feature Name" - WF->>User: Session Created - - User->>BS: /workflow:brainstorm "topic" --perspectives=system-architect,security-expert - BS->>BS: Multiple Agent Perspectives - BS->>WF: Generate Ideas & Analysis - - User->>BS: /workflow:brainstorm:synthesis - BS->>WF: Consolidated Recommendations - - User->>PLAN: /workflow:plan --from-brainstorming - PLAN->>PLAN: Convert Ideas to Implementation Plan - PLAN->>WF: Generate IMPL_PLAN.md + TODO_LIST.md - - User->>WF: /workflow:execute --type=complex - WF->>TASK: Auto-create task hierarchy - TASK->>TASK: Create impl-*.json files - - loop Task Execution - User->>EXEC: /task:execute impl-1 - EXEC->>EXEC: Execute Implementation - EXEC->>TASK: Update task status - - alt Task needs breakdown - EXEC->>TASK: /task:breakdown impl-1 - TASK->>TASK: Create subtasks - else Task blocked - EXEC->>TASK: /task:replan impl-1 - TASK->>TASK: Adjust task plan - end - end - - User->>WF: /workflow:review - WF->>User: Quality validation complete - - User->>WF: /update-memory-related - WF->>User: Documentation updated -``` - -## 13. Task Command Hierarchy and Dependencies - -```mermaid -graph TB - subgraph "Workflow Layer" - WF_PLAN["/workflow:plan"] - WF_EXECUTE["/workflow:execute"] - WF_REVIEW["/workflow:review"] - end - - subgraph "Task Management Layer" - TASK_CREATE["/task:create"] - TASK_BREAKDOWN["/task:breakdown"] - TASK_REPLAN["/task:replan"] - end - - subgraph "Task Execution Layer" - TASK_EXECUTE["/task:execute"] - - subgraph "Execution Modes" - MANUAL["--mode=guided"] - AUTO["--mode=auto"] - end - - subgraph "Agent Selection" - CODE_AGENT["--agent=code-developer"] - PLAN_AGENT["--agent=planning-agent"] - REVIEW_AGENT["--agent=code-review-test-agent"] - end - end - - subgraph "Task Hierarchy" - MAIN_TASK["impl-1 (Main Task)"] - SUB_TASK1["impl-1.1 (Subtask)"] - SUB_TASK2["impl-1.2 (Subtask)"] - - MAIN_TASK --> SUB_TASK1 - MAIN_TASK --> SUB_TASK2 - end - - WF_PLAN --> TASK_CREATE - WF_EXECUTE --> TASK_CREATE - TASK_CREATE --> TASK_BREAKDOWN - TASK_BREAKDOWN --> MAIN_TASK - MAIN_TASK --> SUB_TASK1 - MAIN_TASK --> SUB_TASK2 - - SUB_TASK1 --> TASK_EXECUTE - SUB_TASK2 --> TASK_EXECUTE - - TASK_EXECUTE --> MANUAL - TASK_EXECUTE --> AUTO - TASK_EXECUTE --> CODE_AGENT - TASK_EXECUTE --> PLAN_AGENT - TASK_EXECUTE --> REVIEW_AGENT - - TASK_EXECUTE --> TASK_REPLAN - TASK_REPLAN --> TASK_BREAKDOWN -``` - -## 14. CLI Integration in Workflow Context - -```mermaid -graph LR - subgraph "Planning Phase CLIs" - GEMINI_PLAN["/gemini:mode:plan"] - GEMINI_ANALYZE["/gemini:analyze"] - CODEX_PLAN["/codex:mode:plan"] - end - - subgraph "Execution Phase CLIs" - GEMINI_EXEC["/gemini:execute"] - CODEX_AUTO["/codex:mode:auto"] - CODEX_EXEC["/codex:execute"] - end - - subgraph "Workflow Commands" - WF_BRAINSTORM["/workflow:brainstorm"] - WF_PLAN["/workflow:plan"] - WF_EXECUTE["/workflow:execute"] - end - - subgraph "Task Commands" - TASK_CREATE["/task:create"] - TASK_EXECUTE["/task:execute"] - end - - subgraph "Context Integration" - UPDATE_MEMORY["/update-memory-related"] - CONTEXT["/context"] - end - - GEMINI_PLAN --> WF_PLAN - GEMINI_ANALYZE --> WF_BRAINSTORM - CODEX_PLAN --> WF_PLAN - - WF_PLAN --> TASK_CREATE - WF_EXECUTE --> TASK_EXECUTE - - TASK_EXECUTE --> GEMINI_EXEC - TASK_EXECUTE --> CODEX_AUTO - TASK_EXECUTE --> CODEX_EXEC - - CODEX_AUTO --> UPDATE_MEMORY - GEMINI_EXEC --> CONTEXT - - UPDATE_MEMORY --> WF_EXECUTE - CONTEXT --> TASK_EXECUTE -``` \ No newline at end of file diff --git a/WORKFLOW_GUIDE.md b/WORKFLOW_GUIDE.md new file mode 100644 index 00000000..c24a1ad1 --- /dev/null +++ b/WORKFLOW_GUIDE.md @@ -0,0 +1,700 @@ +# CCW Workflow Difficulty Guide + +## Overview + +CCW provides two workflow systems: **Main Workflow** and **Issue Workflow**, working together to cover the complete software development lifecycle. + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ Main Workflow │ +│ │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ +│ │ Level 1 │ → │ Level 2 │ → │ Level 3 │ → │ Level 4 │ │ +│ │ Rapid │ │ Lightweight │ │ Standard │ │ Brainstorm │ │ +│ │ │ │ │ │ │ │ │ │ +│ │ lite-lite- │ │ lite-plan │ │ plan │ │ brainstorm │ │ +│ │ lite │ │ lite-fix │ │ tdd-plan │ │ :auto- │ │ +│ │ │ │ multi-cli- │ │ test-fix- │ │ parallel │ │ +│ │ │ │ plan │ │ gen │ │ ↓ │ │ +│ │ │ │ │ │ │ │ plan │ │ +│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ +│ │ +│ Complexity: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━▶ │ +│ Low High │ +└─────────────────────────────────────────────────────────────────────────────┘ + │ + │ After development + ▼ +┌─────────────────────────────────────────────────────────────────────────────┐ +│ Issue Workflow │ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ Accumulate │ → │ Plan │ → │ Execute │ │ +│ │ Discover & │ │ Batch │ │ Parallel │ │ +│ │ Collect │ │ Planning │ │ Execution │ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ │ +│ │ +│ Supplementary role: Maintain main branch stability, worktree isolation │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Main Workflow vs Issue Workflow + +### Design Philosophy + +| Aspect | Main Workflow | Issue Workflow | +|--------|---------------|----------------| +| **Purpose** | Primary development cycle | Post-development maintenance | +| **Timing** | Feature development phase | After main workflow completes | +| **Scope** | Complete feature implementation | Targeted fixes/enhancements | +| **Parallelism** | Dependency analysis → Agent parallel | Worktree isolation (optional) | +| **Branch Model** | Work on current branch | Can use isolated worktree | + +### Why Main Workflow Doesn't Use Worktree Automatically? + +**Dependency analysis already solves parallelism**: + +1. Planning phase (`/workflow:plan`) performs dependency analysis +2. Automatically identifies task dependencies and critical paths +3. Partitions into **parallel groups** (independent tasks) and **serial chains** (dependent tasks) +4. Agents execute independent tasks in parallel without filesystem isolation + +``` +┌─────────────────────────────────────────────────┐ +│ Dependency Analysis │ +│ │ +│ Task A ─────┐ │ +│ ├──→ Parallel Group 1 ──→ Agent 1 │ +│ Task B ─────┘ │ +│ │ +│ Task C ────────→ Serial Chain ──────→ Agent 2 │ +│ ↓ │ +│ Task D ────────→ │ +│ │ +│ Same worktree, parallelism through scheduling │ +└─────────────────────────────────────────────────┘ +``` + +### Why Issue Workflow Supports Worktree? + +Issue Workflow serves as a **supplementary mechanism** with different scenarios: + +1. Main development complete, merged to `main` +2. Issues discovered requiring fixes +3. Need to fix without affecting current development +4. Worktree isolation keeps main branch stable + +``` +Development → Release → Discover Issue → Worktree Fix → Merge back + ↑ │ + └────────────── Continue new feature ←─────────────────┘ +``` + +--- + +## Level 1: Rapid Execution (lite-lite-lite) + +**Simplest - Single CLI analysis to execution, zero artifacts** + +### Characteristics + +| Property | Value | +|----------|-------| +| **Complexity** | Low | +| **Artifacts** | None | +| **State** | Stateless | +| **CLI Selection** | Auto-analyze task type | +| **Iteration** | Via AskUser | + +### Flow + +``` +User Input → Clarification → Auto-select CLI → Parallel Analysis → Show Results → Direct Execute + ↓ + No intermediate files +``` + +### Command + +```bash +/workflow:lite-lite-lite +# Or CCW auto-selects for simple tasks +``` + +### Use Cases + +- ✅ Quick fixes +- ✅ Simple feature additions +- ✅ Configuration adjustments +- ✅ Small-scope renaming +- ❌ Multi-module changes +- ❌ Need persistent records + +--- + +## Level 2: Lightweight Planning + +**Lightweight - In-memory planning or single analysis, fast iteration** + +### Included Workflows + +| Workflow | Purpose | Artifacts | Execution | +|----------|---------|-----------|-----------| +| `lite-plan` | Clear requirement development | memory://plan | → `lite-execute` | +| `lite-fix` | Bug diagnosis and fix | `.workflow/.lite-fix/` | → `lite-execute` | +| `multi-cli-plan` | Multi-perspective tasks | `.workflow/.multi-cli-plan/` | → `lite-execute` | + +### Common Characteristics + +| Property | Value | +|----------|-------| +| **Complexity** | Low-Medium | +| **State** | Session-scoped / Lightweight persistence | +| **Execution** | Unified via `lite-execute` | +| **Use Case** | Relatively clear requirements | + +--- + +### 2.1 lite-plan → lite-execute + +**In-memory planning + Direct execution** + +``` +┌─────────────────┐ ┌─────────────────┐ +│ lite-plan │ ──→ │ lite-execute │ +│ In-memory plan │ │ Direct execute │ +└─────────────────┘ └─────────────────┘ +``` + +```bash +/workflow:lite-plan # Planning +/workflow:lite-execute # Execution +``` + +**Use Case**: Clear single-module features + +--- + +### 2.2 lite-fix + +**Intelligent diagnosis + Fix (5 phases)** + +``` +Phase 1: Bug Analysis & Diagnosis + ├─ Intelligent severity pre-assessment (Low/Medium/High/Critical) + └─ Parallel cli-explore-agent diagnosis (1-4 angles) + +Phase 2: Clarification (optional) + └─ Aggregate clarification needs, AskUserQuestion + +Phase 3: Fix Planning + ├─ Low/Medium → Claude direct planning + └─ High/Critical → cli-lite-planning-agent + +Phase 4: Confirmation & Selection + └─ User confirms execution method + +Phase 5: Execute + └─ SlashCommand("/workflow:lite-execute --in-memory --mode bugfix") +``` + +```bash +/workflow:lite-fix # Standard fix +/workflow:lite-fix --hotfix # Emergency hotfix (skip diagnosis) +``` + +**Artifacts**: `.workflow/.lite-fix/{bug-slug}-{date}/` +- `diagnosis-{angle}.json` (1-4 diagnosis files) +- `diagnoses-manifest.json` +- `fix-plan.json` + +**Use Case**: Bug diagnosis, production emergencies + +--- + +### 2.3 multi-cli-plan → lite-execute + +**Multi-CLI collaborative analysis + Consensus convergence (5 phases)** + +``` +Phase 1: Context Gathering + └─ ACE semantic search, build context package + +Phase 2: Multi-CLI Discussion (iterative) + ├─ cli-discuss-agent executes Gemini + Codex + Claude + ├─ Cross-verification, synthesize solutions + └─ Loop until convergence or max rounds + +Phase 3: Present Options + └─ Display solutions with trade-offs + +Phase 4: User Decision + └─ User selects solution + +Phase 5: Plan Generation + ├─ cli-lite-planning-agent generates plan + └─ → lite-execute +``` + +```bash +/workflow:multi-cli-plan "task description" # Multi-CLI collaborative planning +/workflow:lite-execute # Execute selected solution +``` + +**Artifacts**: `.workflow/.multi-cli-plan/{MCP-task-slug-date}/` +- `rounds/*/synthesis.json` (per-round analysis) +- `context-package.json` +- `IMPL_PLAN.md` + `plan.json` + +**vs lite-plan comparison**: + +| Aspect | multi-cli-plan | lite-plan | +|--------|---------------|-----------| +| **Context** | ACE semantic search | Manual file patterns | +| **Analysis** | Multi-CLI cross-verification | Single planning | +| **Iteration** | Multiple rounds until convergence | Single round | +| **Confidence** | High (consensus-driven) | Medium (single perspective) | + +**Use Case**: Multi-perspective analysis, technology selection, solution comparison + +--- + +## Level 3: Standard Planning + +**Standard - Complete planning + Persistent Session + Verification** + +### Included Workflows + +| Workflow | Purpose | Phases | Artifact Location | +|----------|---------|--------|-------------------| +| `plan` | Complex feature development | 5 phases | `.workflow/active/{session}/` | +| `tdd-plan` | Test-driven development | 6 phases | `.workflow/active/{session}/` | +| `test-fix-gen` | Test fix generation | 5 phases | `.workflow/active/WFS-test-{session}/` | + +### Common Characteristics + +| Property | Value | +|----------|-------| +| **Complexity** | Medium-High | +| **Artifacts** | Persistent files (`.workflow/active/{session}/`) | +| **State** | Full session management | +| **Verification** | Built-in verification steps | +| **Execution** | `/workflow:execute` | +| **Use Case** | Multi-module, traceable tasks | + +--- + +### 3.1 plan → verify → execute + +**5-phase complete planning workflow** + +``` +Phase 1: Session Discovery + └─ /workflow:session:start --auto + +Phase 2: Context Gathering + └─ /workflow:tools:context-gather + └─ Returns context-package.json + conflict_risk + +Phase 3: Conflict Resolution (conditional) + └─ IF conflict_risk ≥ medium → /workflow:tools:conflict-resolution + +Phase 4: Task Generation + └─ /workflow:tools:task-generate-agent + └─ Returns IMPL_PLAN.md + IMPL-*.json + TODO_LIST.md + +Return: Summary + Next Steps +``` + +```bash +/workflow:plan "task description" # Complete planning +/workflow:action-plan-verify # Verify plan (recommended) +/workflow:execute # Execute +/workflow:review # (optional) Review +``` + +**Artifacts**: `.workflow/active/{WFS-session}/` +- `workflow-session.json` +- `IMPL_PLAN.md` +- `TODO_LIST.md` +- `.task/IMPL-*.json` +- `.process/context-package.json` + +**Use Case**: Multi-module changes, refactoring, dependency analysis needed + +--- + +### 3.2 tdd-plan → execute → tdd-verify + +**6-phase test-driven development workflow** + +``` +Phase 1: Session Discovery + └─ /workflow:session:start --type tdd --auto + +Phase 2: Context Gathering + └─ /workflow:tools:context-gather + +Phase 3: Test Coverage Analysis + └─ /workflow:tools:test-context-gather + └─ Detect test framework, analyze coverage + +Phase 4: Conflict Resolution (conditional) + └─ IF conflict_risk ≥ medium → /workflow:tools:conflict-resolution + +Phase 5: TDD Task Generation + └─ /workflow:tools:task-generate-tdd + └─ Generate IMPL tasks with built-in Red-Green-Refactor cycles + +Phase 6: TDD Structure Validation + └─ Verify TDD structure compliance +``` + +```bash +/workflow:tdd-plan "feature description" # TDD planning +/workflow:action-plan-verify # Verify (recommended) +/workflow:execute # Execute (follow Red-Green-Refactor) +/workflow:tdd-verify # Verify TDD compliance +``` + +**TDD Task Structure**: +- Each IMPL task contains complete internal Red-Green-Refactor cycle +- `meta.tdd_workflow: true` +- `flow_control.implementation_approach` contains 3 steps (red/green/refactor) +- Green phase includes test-fix-cycle configuration + +**Use Case**: Test-driven development, high-quality feature requirements + +--- + +### 3.3 test-fix-gen → test-cycle-execute + +**5-phase test fix generation workflow** + +``` +Phase 1: Create Test Session + └─ /workflow:session:start --type test --new + +Phase 2: Gather Test Context + ├─ Session Mode: /workflow:tools:test-context-gather + └─ Prompt Mode: /workflow:tools:context-gather + +Phase 3: Test Generation Analysis + └─ /workflow:tools:test-concept-enhanced + └─ Multi-layer test requirements (L0: Static, L1: Unit, L2: Integration, L3: E2E) + +Phase 4: Generate Test Tasks + └─ /workflow:tools:test-task-generate + └─ IMPL-001 (generate) + IMPL-001.5 (quality gate) + IMPL-002 (execute fix) + +Phase 5: Return Summary + └─ → /workflow:test-cycle-execute +``` + +**Dual-mode support**: +| Mode | Input Pattern | Context Source | +|------|---------------|----------------| +| Session Mode | `WFS-xxx` | Source session summaries | +| Prompt Mode | Text/file path | Direct codebase analysis | + +```bash +/workflow:test-fix-gen WFS-user-auth-v2 # Session Mode +/workflow:test-fix-gen "Test the auth API" # Prompt Mode +/workflow:test-cycle-execute # Execute test-fix cycle +``` + +**Artifacts**: `.workflow/active/WFS-test-{session}/` +- `.task/IMPL-001.json` (test understanding & generation) +- `.task/IMPL-001.5-review.json` (quality gate) +- `.task/IMPL-002.json` (test execution & fix cycle) +- `.process/TEST_ANALYSIS_RESULTS.md` + +**Use Case**: Test failure fixes, coverage improvement + +--- + +## Level 4: Brainstorming (brainstorm:auto-parallel) + +**Most Complex - Multi-role brainstorming + Complete planning + Execution** + +### Characteristics + +| Property | Value | +|----------|-------| +| **Complexity** | High | +| **Artifacts** | Multi-role analysis docs + `IMPL_PLAN.md` | +| **Role Count** | 3-9 (default 3) | +| **Execution Mode** | Phase 1/3 sequential, Phase 2 parallel | + +### 3-Phase Flow + +``` +Phase 1: Interactive Framework Generation + └─ /workflow:brainstorm:artifacts + ├─ Topic analysis, generate questions + ├─ Role selection (user confirmation) + ├─ Role question collection + ├─ Conflict detection and resolution + └─ Generate guidance-specification.md + +Phase 2: Parallel Role Analysis (parallel) + └─ N × Task(conceptual-planning-agent) + ├─ Each role analyzes independently + └─ Parallel generate {role}/analysis.md + +Phase 3: Synthesis Integration + └─ /workflow:brainstorm:synthesis + └─ Integrate all role analyses → synthesis-specification.md +``` + +### Commands + +```bash +/workflow:brainstorm:auto-parallel "topic" [--count N] [--style-skill package] +/workflow:plan --session {sessionId} # Plan based on brainstorm results +/workflow:action-plan-verify # Verify +/workflow:execute # Execute +``` + +### Available Roles + +| Role | Description | +|------|-------------| +| `system-architect` | System Architect | +| `ui-designer` | UI Designer | +| `ux-expert` | UX Expert | +| `product-manager` | Product Manager | +| `product-owner` | Product Owner | +| `data-architect` | Data Architect | +| `scrum-master` | Scrum Master | +| `subject-matter-expert` | Domain Expert | +| `test-strategist` | Test Strategist | + +### Artifact Structure + +``` +.workflow/active/WFS-{topic}/ +├── workflow-session.json # Session metadata +└── .brainstorming/ + ├── guidance-specification.md # Framework (Phase 1) + ├── {role}/ + │ ├── analysis.md # Main document + │ └── analysis-{slug}.md # Sub-documents (optional, max 5) + └── synthesis-specification.md # Integration (Phase 3) +``` + +### Use Cases + +- ✅ New feature design +- ✅ System architecture refactoring +- ✅ Exploratory requirements +- ✅ Uncertain implementation approach +- ✅ Multi-dimensional trade-offs needed +- ❌ Clear requirements +- ❌ Time-sensitive tasks + +--- + +## Issue Workflow + +**Main Workflow Supplement - Post-development continuous maintenance** + +### Two-Phase Lifecycle + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ Phase 1: Accumulation │ +│ │ +│ Triggers: │ +│ • Post-task review │ +│ • Code review findings │ +│ • Test failures │ +│ │ +│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ +│ │ discover │ │ discover- │ │ new │ │ +│ │ Auto-find │ │ by-prompt │ │ Manual │ │ +│ └────────────┘ └────────────┘ └────────────┘ │ +│ │ +│ Continuously accumulate issues to pending queue │ +└─────────────────────────────────────────────────────────────────────┘ + │ + │ After sufficient accumulation + ▼ +┌─────────────────────────────────────────────────────────────────────┐ +│ Phase 2: Batch Resolution │ +│ │ +│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ +│ │ plan │ ──→ │ queue │ ──→ │ execute │ │ +│ │ --all- │ │ Optimize │ │ Parallel │ │ +│ │ pending │ │ order │ │ execution │ │ +│ └────────────┘ └────────────┘ └────────────┘ │ +│ │ +│ Supports worktree isolation, maintains main branch stability │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +### Command List + +**Accumulation Phase:** +```bash +/issue:discover # Multi-perspective auto-discovery +/issue:discover-by-prompt # Prompt-based discovery +/issue:new # Manual creation +``` + +**Batch Resolution:** +```bash +/issue:plan --all-pending # Batch plan all pending +/issue:queue # Generate optimized execution queue +/issue:execute # Parallel execution +``` + +### Collaboration with Main Workflow + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ Development Iteration Loop │ +│ │ +│ ┌─────────┐ ┌─────────┐ │ +│ │ Feature │ ──→ Main Workflow ──→ Done ──→│ Review │ │ +│ │ Request │ (Level 1-4) └────┬────┘ │ +│ └─────────┘ │ │ +│ ▲ │ Issues found │ +│ │ ▼ │ +│ │ ┌─────────┐ │ +│ │ │ Issue │ │ +│ │ │ Workflow│ │ +│ Continue│ └────┬────┘ │ +│ new │ │ │ +│ feature │ ┌──────────────────────────┘ │ +│ │ │ Fix complete │ +│ │ ▼ │ +│ ┌────┴────┐◀────── │ +│ │ Main │ Merge │ +│ │ Branch │ back │ +│ └─────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Workflow Selection Guide + +### Quick Selection Table + +| Scenario | Recommended Workflow | Level | +|----------|---------------------|-------| +| Quick fixes, config adjustments | `lite-lite-lite` | 1 | +| Clear single-module features | `lite-plan → lite-execute` | 2 | +| Bug diagnosis and fix | `lite-fix` | 2 | +| Production emergencies | `lite-fix --hotfix` | 2 | +| Technology selection, solution comparison | `multi-cli-plan → lite-execute` | 2 | +| Multi-module changes, refactoring | `plan → verify → execute` | 3 | +| Test-driven development | `tdd-plan → execute → tdd-verify` | 3 | +| Test failure fixes | `test-fix-gen → test-cycle-execute` | 3 | +| New features, architecture design | `brainstorm:auto-parallel → plan → execute` | 4 | +| Post-development issue fixes | Issue Workflow | - | + +### Decision Flowchart + +``` +Start + │ + ├─ Is it post-development maintenance? + │ ├─ Yes → Issue Workflow + │ └─ No ↓ + │ + ├─ Are requirements clear? + │ ├─ Uncertain → Level 4 (brainstorm:auto-parallel) + │ └─ Clear ↓ + │ + ├─ Need persistent Session? + │ ├─ Yes → Level 3 (plan / tdd-plan / test-fix-gen) + │ └─ No ↓ + │ + ├─ Need multi-perspective / solution comparison? + │ ├─ Yes → Level 2 (multi-cli-plan) + │ └─ No ↓ + │ + ├─ Is it a bug fix? + │ ├─ Yes → Level 2 (lite-fix) + │ └─ No ↓ + │ + ├─ Need planning? + │ ├─ Yes → Level 2 (lite-plan) + │ └─ No → Level 1 (lite-lite-lite) +``` + +### Complexity Indicators + +System auto-evaluates complexity based on these keywords: + +| Weight | Keywords | +|--------|----------| +| +2 | refactor, migrate, architect, system | +| +2 | multiple, across, all, entire | +| +1 | integrate, api, database | +| +1 | security, performance, scale | + +- **High complexity** (≥4): Auto-select Level 3-4 +- **Medium complexity** (2-3): Auto-select Level 2 +- **Low complexity** (<2): Auto-select Level 1 + +--- + +## ACE Tool Configuration + +ACE MCP can be configured directly using official settings, no relay server required: + +```json +{ + "mcpServers": { + "ace-tool": { + "command": "npx", + "args": ["-y", "@anthropic/ace-mcp"], + "env": { + "AUGMENT_API_KEY": "your-augment-api-key" + } + } + } +} +``` + +Usage: +```javascript +mcp__ace-tool__search_context({ + project_root_path: "/path/to/project", + query: "authentication logic" +}) +``` + +--- + +## Summary + +### Level Overview + +| Level | Name | Included Workflows | Artifacts | Execution | +|-------|------|-------------------|-----------|-----------| +| **1** | Rapid | `lite-lite-lite` | None | Direct execute | +| **2** | Lightweight | `lite-plan`, `lite-fix`, `multi-cli-plan` | Memory/Lightweight files | → `lite-execute` | +| **3** | Standard | `plan`, `tdd-plan`, `test-fix-gen` | Session persistence | → `execute` / `test-cycle-execute` | +| **4** | Brainstorm | `brainstorm:auto-parallel` → `plan` | Multi-role analysis + Session | → `execute` | +| **-** | Issue | `discover` → `plan` → `queue` → `execute` | Issue records | Worktree isolation (optional) | + +### Core Principles + +1. **Main Workflow** solves parallelism through **dependency analysis + Agent parallel execution**, no worktree needed +2. **Issue Workflow** serves as a **supplementary mechanism**, supporting worktree isolation to maintain main branch stability +3. Select appropriate workflow level based on task complexity, **avoid over-engineering** +4. Level 2 workflow selection criteria: + - Clear requirements → `lite-plan` + - Bug fix → `lite-fix` + - Need multi-perspective → `multi-cli-plan` +5. Level 3 workflow selection criteria: + - Standard development → `plan` + - Test-driven → `tdd-plan` + - Test fix → `test-fix-gen` diff --git a/WORKFLOW_GUIDE_CN.md b/WORKFLOW_GUIDE_CN.md new file mode 100644 index 00000000..d6a012b9 --- /dev/null +++ b/WORKFLOW_GUIDE_CN.md @@ -0,0 +1,671 @@ +# CCW Workflow Difficulty Guide + +## Overview + +CCW 提供两类工作流体系：**主干工作流** (Main Workflow) 和 **Issue 工作流** (Issue Workflow)，它们协同覆盖软件开发的完整生命周期。 + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ Main Workflow (主干工作流) │ +│ │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ +│ │ Level 1 │ → │ Level 2 │ → │ Level 3 │ → │ Level 4 │ │ +│ │ 急速执行 │ │ 轻量规划 │ │ 标准规划 │ │ 头脑风暴 │ │ +│ │ │ │ │ │ │ │ │ │ +│ │ lite-lite- │ │ lite-plan │ │ plan │ │ brainstorm │ │ +│ │ lite │ │ lite-fix │ │ tdd-plan │ │ :auto- │ │ +│ │ │ │ multi-cli- │ │ test-fix- │ │ parallel │ │ +│ │ │ │ plan │ │ gen │ │ ↓ │ │ +│ │ │ │ │ │ │ │ plan │ │ +│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ +│ │ +│ 复杂度: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━▶ │ +│ 低 高 │ +└─────────────────────────────────────────────────────────────────────────────┘ + │ + │ 开发完成后 + ▼ +┌─────────────────────────────────────────────────────────────────────────────┐ +│ Issue Workflow (Issue 工作流) │ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ Accumulate │ → │ Plan │ → │ Execute │ │ +│ │ 发现 & 积累 │ │ 批量规划 │ │ 并行执行 │ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ │ +│ │ +│ 补充角色: 维护主分支稳定，支持 worktree 隔离 │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 主干工作流与 Issue 工作流的关系 + +### 设计哲学 + +| 维度 | 主干工作流 (Main) | Issue 工作流 (Issue) | +|------|-------------------|---------------------| +| **定位** | 主要开发周期 | 开发后的维护补充 | +| **时机** | 功能开发阶段 | 主干开发完成后 | +| **范围** | 完整功能实现 | 针对性修复/增强 | +| **并行策略** | 依赖分析 → Agent 并行 | Worktree 隔离 (可选) | +| **分支模型** | 在当前分支工作 | 可使用独立 worktree | + +### 为什么主干工作流不自动使用 Worktree？ + +**依赖分析已解决并行问题**： + +1. 规划阶段 (`/workflow:plan`) 执行依赖分析 +2. 自动识别任务依赖和关键路径 +3. 划分**并行组** (独立任务) 和**串行链** (依赖任务) +4. Agent 并行执行独立任务，无需文件系统隔离 + +``` +┌─────────────────────────────────────────────────┐ +│ Dependency Analysis (依赖分析) │ +│ │ +│ Task A ─────┐ │ +│ ├──→ Parallel Group 1 ──→ Agent 1 │ +│ Task B ─────┘ │ +│ │ +│ Task C ────────→ Serial Chain ──────→ Agent 2 │ +│ ↓ │ +│ Task D ────────→ │ +│ │ +│ 同一 worktree，通过调度实现并行 │ +└─────────────────────────────────────────────────┘ +``` + +### 为什么 Issue 工作流支持 Worktree？ + +Issue 工作流作为**补充机制**，场景不同： + +1. 主干开发完成，已合并到 `main` +2. 发现需要修复的问题 +3. 需要在不影响当前开发的情况下修复 +4. Worktree 隔离让主分支保持稳定 + +``` +开发完成 → 发布 → 发现 Issue → Worktree 隔离修复 → 合并回主干 + ↑ │ + └──────────── 继续新功能开发 ←─────────────────┘ +``` + +--- + +## Level 1: 急速执行 (lite-lite-lite) + +**最简单 - 一次 CLI 分析到执行，零产物** + +### 特点 + +| 属性 | 值 | +|------|-----| +| **复杂度** | 低 | +| **产物** | 无文件 | +| **状态** | 无状态 | +| **CLI 选择** | 自动分析任务类型 | +| **迭代方式** | 通过 AskUser | + +### 流程 + +``` +用户输入 → 需求澄清 → 自动选择 CLI → 并行分析 → 展示结果 → 直接执行 + ↓ + 无中间文件 +``` + +### 命令 + +```bash +/workflow:lite-lite-lite +# 或 CCW 自动识别简单任务时选择 +``` + +### 适用场景 + +- ✅ 快速修复 +- ✅ 简单功能添加 +- ✅ 配置调整 +- ✅ 小范围重命名 +- ❌ 多模块改动 +- ❌ 需要持久化记录 + +--- + +## Level 2: 轻量规划 + +**轻量 - 内存规划或单次分析，快速迭代** + +### 包含工作流 + +| 工作流 | 用途 | 产物 | 执行方式 | +|--------|------|------|----------| +| `lite-plan` | 明确需求的功能开发 | memory://plan | → `lite-execute` | +| `lite-fix` | Bug 诊断修复 | `.workflow/.lite-fix/` | → `lite-execute` | +| `multi-cli-plan` | 需要多视角的任务 | `.workflow/.multi-cli-plan/` | → `lite-execute` | + +### 共同特点 + +| 属性 | 值 | +|------|-----| +| **复杂度** | 低-中 | +| **状态** | 会话内 / 轻量持久化 | +| **执行** | 统一通过 `lite-execute` | +| **适用** | 需求相对明确的任务 | + +--- + +### 2.1 lite-plan → lite-execute + +**内存规划 + 直接执行** + +``` +┌─────────────────┐ ┌─────────────────┐ +│ lite-plan │ ──→ │ lite-execute │ +│ 内存中规划 │ │ 直接执行 │ +└─────────────────┘ └─────────────────┘ +``` + +```bash +/workflow:lite-plan # 规划 +/workflow:lite-execute # 执行 +``` + +**适用**: 明确需求的单模块功能 + +--- + +### 2.2 lite-fix + +**智能诊断 + 修复 (5 阶段)** + +``` +Phase 1: Bug Analysis & Diagnosis + ├─ 智能严重性预评估 (Low/Medium/High/Critical) + └─ 并行 cli-explore-agent 诊断 (1-4 个角度) + +Phase 2: Clarification (可选) + └─ 聚合澄清需求，AskUserQuestion + +Phase 3: Fix Planning + ├─ Low/Medium → Claude 直接规划 + └─ High/Critical → cli-lite-planning-agent + +Phase 4: Confirmation & Selection + └─ 用户确认执行方式 + +Phase 5: Execute + └─ SlashCommand("/workflow:lite-execute --in-memory --mode bugfix") +``` + +```bash +/workflow:lite-fix # 标准修复 +/workflow:lite-fix --hotfix # 紧急热修复 (跳过诊断) +``` + +**产物**: `.workflow/.lite-fix/{bug-slug}-{date}/` +- `diagnosis-{angle}.json` (1-4 个诊断文件) +- `diagnoses-manifest.json` +- `fix-plan.json` + +**适用**: Bug 诊断修复、紧急生产问题 + +--- + +### 2.3 multi-cli-plan → lite-execute + +**多 CLI 协作分析 + 共识收敛 (5 阶段)** + +``` +Phase 1: Context Gathering + └─ ACE 语义搜索，构建上下文包 + +Phase 2: Multi-CLI Discussion (迭代) + ├─ cli-discuss-agent 执行 Gemini + Codex + Claude + ├─ 交叉验证，合成方案 + └─ 循环直到收敛或达到最大轮数 + +Phase 3: Present Options + └─ 展示方案及权衡 + +Phase 4: User Decision + └─ 用户选择方案 + +Phase 5: Plan Generation + ├─ cli-lite-planning-agent 生成计划 + └─ → lite-execute +``` + +```bash +/workflow:multi-cli-plan "task description" # 多 CLI 协作规划 +/workflow:lite-execute # 执行选定方案 +``` + +**产物**: `.workflow/.multi-cli-plan/{MCP-task-slug-date}/` +- `rounds/*/synthesis.json` (每轮分析) +- `context-package.json` +- `IMPL_PLAN.md` + `plan.json` + +**vs lite-plan 对比**: + +| 维度 | multi-cli-plan | lite-plan | +|------|---------------|-----------| +| **上下文** | ACE 语义搜索 | 手动文件模式 | +| **分析** | 多 CLI 交叉验证 | 单次规划 | +| **迭代** | 多轮直到收敛 | 单轮 | +| **置信度** | 高 (共识驱动) | 中 (单一视角) | + +**适用**: 需要多视角分析、技术选型、方案比较 + +--- + +## Level 3: 标准规划 + +**标准 - 完整规划 + 持久化 Session + 验证** + +### 包含工作流 + +| 工作流 | 用途 | 阶段数 | 产物位置 | +|--------|------|--------|----------| +| `plan` | 复杂功能开发 | 5 阶段 | `.workflow/active/{session}/` | +| `tdd-plan` | 测试驱动开发 | 6 阶段 | `.workflow/active/{session}/` | +| `test-fix-gen` | 测试修复生成 | 5 阶段 | `.workflow/active/WFS-test-{session}/` | + +### 共同特点 + +| 属性 | 值 | +|------|-----| +| **复杂度** | 中-高 | +| **产物** | 持久化文件 (`.workflow/active/{session}/`) | +| **状态** | 完整 session 管理 | +| **验证** | 内置验证步骤 | +| **执行** | `/workflow:execute` | +| **适用** | 多模块、需要追溯的任务 | + +--- + +### 3.1 plan → verify → execute + +**5 阶段完整规划工作流** + +``` +Phase 1: Session Discovery + └─ /workflow:session:start --auto + +Phase 2: Context Gathering + └─ /workflow:tools:context-gather + └─ 返回 context-package.json + conflict_risk + +Phase 3: Conflict Resolution (条件触发) + └─ IF conflict_risk ≥ medium → /workflow:tools:conflict-resolution + +Phase 4: Task Generation + └─ /workflow:tools:task-generate-agent + └─ 返回 IMPL_PLAN.md + IMPL-*.json + TODO_LIST.md + +Return: Summary + Next Steps +``` + +```bash +/workflow:plan "task description" # 完整规划 +/workflow:action-plan-verify # 验证计划 (推荐) +/workflow:execute # 执行 +/workflow:review # (可选) 审查 +``` + +**产物**: `.workflow/active/{WFS-session}/` +- `workflow-session.json` +- `IMPL_PLAN.md` +- `TODO_LIST.md` +- `.task/IMPL-*.json` +- `.process/context-package.json` + +**适用**: 多模块改动、重构任务、需要依赖分析 + +--- + +### 3.2 tdd-plan → execute → tdd-verify + +**6 阶段测试驱动开发工作流** + +``` +Phase 1: Session Discovery + └─ /workflow:session:start --type tdd --auto + +Phase 2: Context Gathering + └─ /workflow:tools:context-gather + +Phase 3: Test Coverage Analysis + └─ /workflow:tools:test-context-gather + └─ 检测测试框架，分析覆盖率 + +Phase 4: Conflict Resolution (条件触发) + └─ IF conflict_risk ≥ medium → /workflow:tools:conflict-resolution + +Phase 5: TDD Task Generation + └─ /workflow:tools:task-generate-tdd + └─ 生成内置 Red-Green-Refactor 循环的 IMPL 任务 + +Phase 6: TDD Structure Validation + └─ 验证 TDD 结构合规性 +``` + +```bash +/workflow:tdd-plan "feature description" # TDD 规划 +/workflow:action-plan-verify # 验证 (推荐) +/workflow:execute # 执行 (遵循 Red-Green-Refactor) +/workflow:tdd-verify # 验证 TDD 流程合规 +``` + +**TDD 任务结构**: +- 每个 IMPL 任务包含完整的 Red-Green-Refactor 内部循环 +- `meta.tdd_workflow: true` +- `flow_control.implementation_approach` 包含 3 步 (red/green/refactor) +- Green 阶段包含 test-fix-cycle 配置 + +**适用**: 测试驱动开发、高质量要求的功能 + +--- + +### 3.3 test-fix-gen → test-cycle-execute + +**5 阶段测试修复生成工作流** + +``` +Phase 1: Create Test Session + └─ /workflow:session:start --type test --new + +Phase 2: Gather Test Context + ├─ Session Mode: /workflow:tools:test-context-gather + └─ Prompt Mode: /workflow:tools:context-gather + +Phase 3: Test Generation Analysis + └─ /workflow:tools:test-concept-enhanced + └─ 多层测试需求 (L0: Static, L1: Unit, L2: Integration, L3: E2E) + +Phase 4: Generate Test Tasks + └─ /workflow:tools:test-task-generate + └─ IMPL-001 (生成) + IMPL-001.5 (质量门) + IMPL-002 (执行修复) + +Phase 5: Return Summary + └─ → /workflow:test-cycle-execute +``` + +**双模式支持**: +| 模式 | 输入模式 | 上下文来源 | +|------|----------|-----------| +| Session Mode | `WFS-xxx` | 源 session 摘要 | +| Prompt Mode | 文本/文件路径 | 直接代码库分析 | + +```bash +/workflow:test-fix-gen WFS-user-auth-v2 # Session Mode +/workflow:test-fix-gen "Test the auth API" # Prompt Mode +/workflow:test-cycle-execute # 执行测试修复循环 +``` + +**产物**: `.workflow/active/WFS-test-{session}/` +- `.task/IMPL-001.json` (测试理解与生成) +- `.task/IMPL-001.5-review.json` (质量门) +- `.task/IMPL-002.json` (测试执行与修复循环) +- `.process/TEST_ANALYSIS_RESULTS.md` + +**适用**: 测试失败修复、覆盖率提升 + +--- + +## Level 4: 头脑风暴 (brainstorm:auto-parallel) + +**最复杂 - 多角色头脑风暴 + 完整规划 + 执行** + +### 特点 + +| 属性 | 值 | +|------|-----| +| **复杂度** | 高 | +| **产物** | 多角色分析文档 + `IMPL_PLAN.md` | +| **角色数** | 3-9 个 (默认 3) | +| **执行模式** | Phase 1/3 串行，Phase 2 并行 | + +### 3 阶段流程 + +``` +Phase 1: Interactive Framework Generation + └─ /workflow:brainstorm:artifacts + ├─ Topic 分析，生成问题 + ├─ 角色选择 (用户确认) + ├─ 角色问题收集 + ├─ 冲突检测与解决 + └─ 生成 guidance-specification.md + +Phase 2: Parallel Role Analysis (并行) + └─ N × Task(conceptual-planning-agent) + ├─ 每个角色独立分析 + └─ 并行生成 {role}/analysis.md + +Phase 3: Synthesis Integration + └─ /workflow:brainstorm:synthesis + └─ 整合所有角色分析 → synthesis-specification.md +``` + +### 命令 + +```bash +/workflow:brainstorm:auto-parallel "topic" [--count N] [--style-skill package] +/workflow:plan --session {sessionId} # 基于头脑风暴结果规划 +/workflow:action-plan-verify # 验证 +/workflow:execute # 执行 +``` + +### 可用角色 + +| 角色 | 描述 | +|------|------| +| `system-architect` | 系统架构师 | +| `ui-designer` | UI 设计师 | +| `ux-expert` | UX 专家 | +| `product-manager` | 产品经理 | +| `product-owner` | 产品负责人 | +| `data-architect` | 数据架构师 | +| `scrum-master` | 敏捷教练 | +| `subject-matter-expert` | 领域专家 | +| `test-strategist` | 测试策略师 | + +### 产物结构 + +``` +.workflow/active/WFS-{topic}/ +├── workflow-session.json # Session 元数据 +└── .brainstorming/ + ├── guidance-specification.md # 框架 (Phase 1) + ├── {role}/ + │ ├── analysis.md # 主文档 + │ └── analysis-{slug}.md # 子文档 (可选，最多 5 个) + └── synthesis-specification.md # 整合 (Phase 3) +``` + +### 适用场景 + +- ✅ 全新功能设计 +- ✅ 系统架构重构 +- ✅ 探索性需求 +- ✅ 不确定如何实现 +- ✅ 需要多维度权衡 +- ❌ 需求已明确 +- ❌ 时间紧迫的任务 + +--- + +## Issue 工作流 + +**主干工作流的补充 - 开发后的持续维护** + +### 两阶段生命周期 + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ Phase 1: Accumulation (积累阶段) │ +│ │ +│ 触发源: │ +│ • 任务完成后的 review │ +│ • 代码审查发现 │ +│ • 测试失败 │ +│ │ +│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ +│ │ discover │ │ discover- │ │ new │ │ +│ │ 自动发现 │ │ by-prompt │ │ 手动创建 │ │ +│ └────────────┘ └────────────┘ └────────────┘ │ +│ │ +│ 持续积累 Issue 到待处理队列 │ +└─────────────────────────────────────────────────────────────────────┘ + │ + │ 积累足够后 + ▼ +┌─────────────────────────────────────────────────────────────────────┐ +│ Phase 2: Batch Resolution (批量解决) │ +│ │ +│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ +│ │ plan │ ──→ │ queue │ ──→ │ execute │ │ +│ │ --all- │ │ 优化顺序 │ │ 并行执行 │ │ +│ │ pending │ │ 冲突分析 │ │ │ │ +│ └────────────┘ └────────────┘ └────────────┘ │ +│ │ +│ 支持 Worktree 隔离，保持主分支稳定 │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +### 命令清单 + +**积累阶段:** +```bash +/issue:discover # 多视角自动发现 +/issue:discover-by-prompt # 基于提示发现 +/issue:new # 手动创建 +``` + +**批量解决:** +```bash +/issue:plan --all-pending # 批量规划所有待处理 +/issue:queue # 生成优化执行队列 +/issue:execute # 并行执行 +``` + +### 与主干工作流的协作模式 + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ 开发迭代循环 │ +│ │ +│ ┌─────────┐ ┌─────────┐ │ +│ │ Feature │ ──→ Main Workflow ──→ 完成 ──→│ Review │ │ +│ │ Request │ (Level 1-4) └────┬────┘ │ +│ └─────────┘ │ │ +│ ▲ │ 发现问题 │ +│ │ ▼ │ +│ │ ┌─────────┐ │ +│ │ │ Issue │ │ +│ │ │ Workflow│ │ +│ 继续 │ └────┬────┘ │ +│ 新功能│ │ │ +│ │ ┌──────────────────────────────┘ │ +│ │ │ 修复完成 │ +│ │ ▼ │ +│ ┌────┴────┐◀────── │ +│ │ Main │ 合并 │ +│ │ Branch │ 回主干 │ +│ └─────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 工作流选择指南 + +### 快速选择表 + +| 场景 | 推荐工作流 | Level | +|------|-----------|-------| +| 快速修复、配置调整 | `lite-lite-lite` | 1 | +| 明确需求的单模块功能 | `lite-plan → lite-execute` | 2 | +| Bug 诊断修复 | `lite-fix` | 2 | +| 紧急生产问题 | `lite-fix --hotfix` | 2 | +| 技术选型、方案比较 | `multi-cli-plan → lite-execute` | 2 | +| 多模块改动、重构 | `plan → verify → execute` | 3 | +| 测试驱动开发 | `tdd-plan → execute → tdd-verify` | 3 | +| 测试失败修复 | `test-fix-gen → test-cycle-execute` | 3 | +| 全新功能、架构设计 | `brainstorm:auto-parallel → plan → execute` | 4 | +| 开发后问题修复 | Issue Workflow | - | + +### 决策流程图 + +``` +开始 + │ + ├─ 是开发后的维护问题？ + │ ├─ 是 → Issue Workflow + │ └─ 否 ↓ + │ + ├─ 需求是否明确？ + │ ├─ 不确定 → Level 4 (brainstorm:auto-parallel) + │ └─ 明确 ↓ + │ + ├─ 需要持久化 Session？ + │ ├─ 是 → Level 3 (plan / tdd-plan / test-fix-gen) + │ └─ 否 ↓ + │ + ├─ 需要多视角 / 方案比较？ + │ ├─ 是 → Level 2 (multi-cli-plan) + │ └─ 否 ↓ + │ + ├─ 是 Bug 修复？ + │ ├─ 是 → Level 2 (lite-fix) + │ └─ 否 ↓ + │ + ├─ 是否需要规划？ + │ ├─ 是 → Level 2 (lite-plan) + │ └─ 否 → Level 1 (lite-lite-lite) +``` + +### 复杂度指标 + +系统根据以下关键词自动评估复杂度： + +| 权重 | 关键词 | +|------|--------| +| +2 | refactor, 重构, migrate, 迁移, architect, 架构, system, 系统 | +| +2 | multiple, 多个, across, 跨, all, 所有, entire, 整个 | +| +1 | integrate, 集成, api, database, 数据库 | +| +1 | security, 安全, performance, 性能, scale, 扩展 | + +- **高复杂度** (≥4): 自动选择 Level 3-4 +- **中复杂度** (2-3): 自动选择 Level 2 +- **低复杂度** (<2): 自动选择 Level 1 + +--- + +## 总结 + +### 分级总览 + +| Level | 名称 | 包含工作流 | 产物 | 执行方式 | +|-------|------|-----------|------|----------| +| **1** | 急速执行 | `lite-lite-lite` | 无 | 直接执行 | +| **2** | 轻量规划 | `lite-plan`, `lite-fix`, `multi-cli-plan` | 内存/轻量文件 | → `lite-execute` | +| **3** | 标准规划 | `plan`, `tdd-plan`, `test-fix-gen` | Session 持久化 | → `execute` / `test-cycle-execute` | +| **4** | 头脑风暴 | `brainstorm:auto-parallel` → `plan` | 多角色分析 + Session | → `execute` | +| **-** | Issue | `discover` → `plan` → `queue` → `execute` | Issue 记录 | Worktree 隔离 (可选) | + +### 核心原则 + +1. **主干工作流**通过**依赖分析 + Agent 并行**解决并行问题，无需 worktree +2. **Issue 工作流**作为**补充机制**，支持 worktree 隔离以保持主分支稳定 +3. 根据任务复杂度选择合适的工作流层级，**避免过度工程化** +4. Level 2 的三个工作流选择依据： + - 需求明确 → `lite-plan` + - Bug 修复 → `lite-fix` + - 需要多视角 → `multi-cli-plan` +5. Level 3 的三个工作流选择依据： + - 标准开发 → `plan` + - 测试驱动 → `tdd-plan` + - 测试修复 → `test-fix-gen` diff --git a/CODEX_LENS_AUTO_HYBRID.md b/codex-lens/docs/CODEX_LENS_AUTO_HYBRID.md similarity index 100% rename from CODEX_LENS_AUTO_HYBRID.md rename to codex-lens/docs/CODEX_LENS_AUTO_HYBRID.md diff --git a/codex_mcp.md b/codex-lens/docs/codex_mcp.md similarity index 100% rename from codex_mcp.md rename to codex-lens/docs/codex_mcp.md diff --git a/codex_prompt.md b/codex_prompt.md deleted file mode 100644 index 4b2d4c16..00000000 --- a/codex_prompt.md +++ /dev/null @@ -1,96 +0,0 @@ -## Custom Prompts - -Custom prompts turn your repeatable instructions into reusable slash commands, so you can trigger them without retyping or copy/pasting. Each prompt is a Markdown file that Codex expands into the conversation the moment you run it. - -### Where prompts live - -- Location: store prompts in `$CODEX_HOME/prompts/` (defaults to `~/.codex/prompts/`). Set `CODEX_HOME` if you want to use a different folder. -- File type: Codex only loads `.md` files. Non-Markdown files are ignored. Both regular files and symlinks to Markdown files are supported. -- Naming: The filename (without `.md`) becomes the prompt name. A file called `review.md` registers the prompt `review`. -- Refresh: Prompts are loaded when a session starts. Restart Codex (or start a new session) after adding or editing files. -- Conflicts: Files whose names collide with built-in commands (like `init`) stay hidden in the slash popup, but you can still invoke them with `/prompts:`. - -### File format - -- Body: The file contents are sent verbatim when you run the prompt (after placeholder expansion). -- Frontmatter (optional): Add YAML-style metadata at the top of the file to improve the slash popup. - - ```markdown - --- - description: Request a concise git diff review - argument-hint: FILE= [FOCUS=
] - --- - ``` - - - `description` shows under the entry in the popup. - - `argument-hint` (or `argument_hint`) lets you document expected inputs, though the current UI ignores this metadata. - -### Placeholders and arguments - -- Numeric placeholders: `$1`–`$9` insert the first nine positional arguments you type after the command. `$ARGUMENTS` inserts all positional arguments joined by a single space. Use `$$` to emit a literal dollar sign (Codex leaves `$$` untouched). -- Named placeholders: Tokens such as `$FILE` or `$TICKET_ID` expand from `KEY=value` pairs you supply. Keys are case-sensitive—use the same uppercase name in the command (for example, `FILE=...`). -- Quoted arguments: Double-quote any value that contains spaces, e.g. `TICKET_TITLE="Fix logging"`. -- Invocation syntax: Run prompts via `/prompts: ...`. When the slash popup is open, typing either `prompts:` or the bare prompt name will surface `/prompts:` suggestions. -- Error handling: If a prompt contains named placeholders, Codex requires them all. You will see a validation message if any are missing or malformed. - -### Running a prompt - -1. Start a new Codex session (ensures the prompt list is fresh). -2. In the composer, type `/` to open the slash popup. -3. Type `prompts:` (or start typing the prompt name) and select it with ↑/↓. -4. Provide any required arguments, press Enter, and Codex sends the expanded content. - -### Examples - -### Example 1: Basic named arguments - -**File**: `~/.codex/prompts/ticket.md` - -```markdown ---- -description: Generate a commit message for a ticket -argument-hint: TICKET_ID= TICKET_TITLE= ---- - -Please write a concise commit message for ticket $TICKET_ID: $TICKET_TITLE -``` - -**Usage**: - -``` -/prompts:ticket TICKET_ID=JIRA-1234 TICKET_TITLE="Fix login bug" -``` - -**Expanded prompt sent to Codex**: - -``` -Please write a concise commit message for ticket JIRA-1234: Fix login bug -``` - -**Note**: Both `TICKET_ID` and `TICKET_TITLE` are required. If either is missing, Codex will show a validation error. Values with spaces must be double-quoted. - -### Example 2: Mixed positional and named arguments - -**File**: `~/.codex/prompts/review.md` - -```markdown ---- -description: Review code in a specific file with focus area -argument-hint: FILE=<path> [FOCUS=<section>] ---- - -Review the code in $FILE. Pay special attention to $FOCUS. -``` - -**Usage**: - -``` -/prompts:review FILE=src/auth.js FOCUS="error handling" -``` - -**Expanded prompt**: - -``` -Review the code in src/auth.js. Pay special attention to error handling. - -``` \ No newline at end of file diff --git a/COMMAND_SPEC.md b/docs/COMMAND_SPEC.md similarity index 100% rename from COMMAND_SPEC.md rename to docs/COMMAND_SPEC.md diff --git a/docs/workflows/ISSUE_LOOP_WORKFLOW.md b/docs/workflows/ISSUE_LOOP_WORKFLOW.md deleted file mode 100644 index 0ed22c01..00000000 --- a/docs/workflows/ISSUE_LOOP_WORKFLOW.md +++ /dev/null @@ -1,435 +0,0 @@ -# CCW Issue Loop 工作流完全指南 - -> 两阶段生命周期设计，支持在项目迭代中积累问题并集中解决 - ---- - -## 目录 - -1. [什么是 Issue Loop 工作流](#什么是-issue-loop-工作流) -2. [核心架构](#核心架构) -3. [两阶段生命周期](#两阶段生命周期) -4. [命令详解](#命令详解) -5. [使用场景](#使用场景) -6. [推荐策略](#推荐策略) -7. [串行无监管执行](#串行无监管执行) -8. [最佳实践](#最佳实践) - ---- - -## 什么是 Issue Loop 工作流 - -Issue Loop 是 CCW (Claude Code Workflow) 中的批量问题处理工作流，专为处理项目迭代过程中积累的多个问题而设计。与单次修复不同，Issue Loop 采用 **"积累 → 规划 → 队列 → 执行"** 的模式，实现问题的批量发现和集中解决。 - -### 核心理念 - -``` -传统模式：发现问题 → 立即修复 → 发现问题 → 立即修复 → ... - ↓ -Issue Loop：持续积累 → 集中规划 → 队列优化 → 批量执行 -``` - -**优势**： -- 避免频繁上下文切换 -- 冲突检测和依赖排序 -- 并行执行支持 -- 完整的追踪和审计 - ---- - -## 核心架构 - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ Issue Loop Workflow │ -├─────────────────────────────────────────────────────────────────┤ -│ Phase 1: Accumulation (积累) │ -│ /issue:discover, /issue:discover-by-prompt, /issue:new │ -├─────────────────────────────────────────────────────────────────┤ -│ Phase 2: Batch Resolution (批量解决) │ -│ /issue:plan → /issue:queue → /issue:execute │ -└─────────────────────────────────────────────────────────────────┘ -``` - -### 数据流转 - -``` -issues.jsonl → solutions/<id>.jsonl → queues/<queue-id>.json → 执行 - ↓ ↓ ↓ - Issue 记录 解决方案 优先级排序 + 冲突检测 -``` - ---- - -## 两阶段生命周期 - -### Phase 1: Accumulation (积累阶段) - -在项目正常迭代过程中，持续发现和记录问题： - -| 触发场景 | 对应命令 | 说明 | -|----------|----------|------| -| 任务完成后 Review | `/issue:discover` | 自动分析代码发现潜在问题 | -| 代码审查发现 | `/issue:new` | 手动创建结构化 Issue | -| 测试失败 | `/issue:discover-by-prompt` | 根据描述创建 Issue | -| 用户反馈 | `/issue:new` | 手动录入反馈问题 | - -**Issue 状态流转**： -``` -registered → planned → queued → executing → completed - ↓ - issue-history.jsonl -``` - -### Phase 2: Batch Resolution (批量解决阶段) - -积累足够 Issue 后，集中处理： - -``` -Step 1: /issue:plan --all-pending # 为所有待处理 Issue 生成解决方案 -Step 2: /issue:queue # 形成执行队列（冲突检测 + 排序） -Step 3: /issue:execute # 批量执行（串行或并行） -``` - ---- - -## 命令详解 - -### 积累阶段命令 - -#### `/issue:new` -手动创建结构化 Issue： -```bash -ccw issue init <id> --title "Issue 标题" --priority P2 -``` - -#### `/issue:discover` -自动分析代码发现问题： -```bash -# 使用 gemini 进行多视角分析 -# 发现：bug、安全问题、性能问题、代码规范等 -``` - -#### `/issue:discover-by-prompt` -根据描述创建 Issue： -```bash -# 输入问题描述，自动生成结构化 Issue -``` - -### 批量解决阶段命令 - -#### `/issue:plan` -为 Issue 生成解决方案： -```bash -ccw issue plan --all-pending # 规划所有待处理 Issue -ccw issue plan ISS-001 # 规划单个 Issue -``` - -**输出**：每个 Issue 生成包含以下内容的解决方案： -- 修改点 (modification_points) -- 实现步骤 (implementation) -- 测试要求 (test) -- 验收标准 (acceptance) - -#### `/issue:queue` -形成执行队列： -```bash -ccw issue queue # 创建新队列 -ccw issue queue add <id> # 添加到当前队列 -ccw issue queue list # 查看队列历史 -``` - -**关键功能**： -- 冲突检测：使用 Gemini CLI 分析解决方案间的文件冲突 -- 依赖排序：根据依赖关系确定执行顺序 -- 优先级加权：高优先级 Issue 优先执行 - -#### `/issue:execute` -执行队列中的解决方案： -```bash -ccw issue next # 获取下一个待执行解决方案 -ccw issue done <item_id> # 标记完成 -ccw issue done <id> --fail # 标记失败 -``` - -### 管理命令 - -```bash -ccw issue list # 列出活跃 Issue -ccw issue status <id> # 查看 Issue 详情 -ccw issue history # 查看已完成 Issue -ccw issue update --from-queue # 从队列同步状态 -``` - ---- - -## 使用场景 - -### 场景 1: 项目迭代后的技术债务清理 - -``` -1. 完成 Sprint 功能开发 -2. 执行 /issue:discover 发现技术债务 -3. 积累一周后，执行 /issue:plan --all-pending -4. 使用 /issue:queue 形成队列 -5. 使用 codex 执行 /issue:execute 批量处理 -``` - -### 场景 2: 代码审查后的批量修复 - -``` -1. 完成 PR 代码审查 -2. 对每个发现执行 /issue:new 创建 Issue -3. 积累本次审查的所有发现 -4. 执行 /issue:plan → /issue:queue → /issue:execute -``` - -### 场景 3: 测试失败的批量处理 - -``` -1. 运行测试套件 -2. 对失败的测试执行 /issue:discover-by-prompt -3. 一次性规划所有失败修复 -4. 串行执行确保不引入新问题 -``` - -### 场景 4: 安全漏洞批量修复 - -``` -1. 安全扫描发现多个漏洞 -2. 每个漏洞创建 Issue 并标记 P1 优先级 -3. 使用 /issue:queue 自动按严重度排序 -4. 执行修复并验证 -``` - ---- - -## 推荐策略 - -### 何时使用 Issue Loop - -| 条件 | 推荐 | -|------|------| -| 问题数量 >= 3 | Issue Loop | -| 问题涉及多个模块 | Issue Loop | -| 问题间可能有依赖 | Issue Loop | -| 需要冲突检测 | Issue Loop | -| 单个简单 bug | `/workflow:lite-fix` | -| 紧急生产问题 | `/workflow:lite-fix --hotfix` | - -### 积累策略 - -**推荐阈值**： -- 积累 5-10 个 Issue 后集中处理 -- 或按时间周期（如每周五下午）统一处理 -- 紧急问题除外，立即标记 P1 并单独处理 - -### 队列策略 - -```javascript -// 冲突检测规则 -if (solution_A.files ∩ solution_B.files !== ∅) { - // 存在文件冲突，需要串行执行 - queue.addDependency(solution_A, solution_B) -} - -// 优先级排序 -sort by: - 1. priority (P1 > P2 > P3) - 2. dependencies (被依赖的先执行) - 3. complexity (低复杂度先执行) -``` - ---- - -## 串行无监管执行 - -**推荐使用 Codex 命令进行串行无监管执行**： - -```bash -codex -p "@.codex/prompts/issue-execute.md" -``` - -### 执行流程 - -``` -INIT: ccw issue next - ↓ -WHILE solution exists: - ├── 1. 解析 solution JSON - ├── 2. 逐个执行 tasks: - │ ├── IMPLEMENT: 按步骤实现 - │ ├── TEST: 运行测试验证 - │ └── VERIFY: 检查验收标准 - ├── 3. 提交代码 (每个 solution 一次 commit) - ├── 4. 报告完成: ccw issue done <id> - └── 5. 获取下一个: ccw issue next - ↓ -COMPLETE: 输出最终报告 -``` - -### Worktree 模式（推荐并行执行） - -```bash -# 创建隔离的工作树 -codex -p "@.codex/prompts/issue-execute.md --worktree" - -# 恢复中断的执行 -codex -p "@.codex/prompts/issue-execute.md --worktree /path/to/existing" -``` - -**优势**： -- 并行执行器不冲突 -- 主工作目录保持干净 -- 执行完成后易于清理 -- 支持中断恢复 - -### 执行规则 - -1. **永不中途停止** - 持续执行直到队列为空 -2. **一次一个解决方案** - 完全完成（所有任务 + 提交 + 报告）后继续 -3. **解决方案内串行** - 每个任务的实现/测试/验证按顺序完成 -4. **测试必须通过** - 任何任务测试失败则修复后继续 -5. **每解决方案一次提交** - 所有任务共享一次 commit -6. **自我验证** - 所有验收标准必须通过 -7. **准确报告** - 使用 `ccw issue done` 报告完成 -8. **优雅处理失败** - 失败时报告并继续下一个 - -### Commit 格式 - -``` -[commit_type](scope): [solution.description] - -## Solution Summary -- **Solution-ID**: SOL-ISS-20251227-001-1 -- **Issue-ID**: ISS-20251227-001 -- **Risk/Impact/Complexity**: low/medium/low - -## Tasks Completed -- [T1] 实现用户认证: Modify src/auth/ -- [T2] 添加测试覆盖: Add tests/auth/ - -## Files Modified -- src/auth/login.ts -- tests/auth/login.test.ts - -## Verification -- All unit tests passed -- All acceptance criteria verified -``` - ---- - -## 最佳实践 - -### 1. Issue 质量 - -创建高质量的 Issue 描述： -```json -{ - "title": "清晰简洁的标题", - "context": { - "problem": "具体问题描述", - "impact": "影响范围", - "reproduction": "复现步骤（如适用）" - }, - "priority": "P1-P5" -} -``` - -### 2. Solution 审查 - -在执行前审查生成的解决方案： -```bash -ccw issue status <id> # 查看解决方案详情 -``` - -检查点： -- 修改点是否准确 -- 测试覆盖是否充分 -- 验收标准是否可验证 - -### 3. 队列监控 - -```bash -ccw issue queue # 查看当前队列状态 -ccw issue queue list # 查看队列历史 -``` - -### 4. 失败处理 - -```bash -# 单个失败 -ccw issue done <id> --fail --reason '{"task_id": "T1", "error": "..."}' - -# 重试失败项 -ccw issue retry --queue QUE-xxx -``` - -### 5. 历史追溯 - -```bash -ccw issue history # 查看已完成 Issue -ccw issue history --json # JSON 格式导出 -``` - ---- - -## 工作流对比 - -| 维度 | Issue Loop | lite-fix | coupled | -|------|------------|----------|---------| -| **适用场景** | 批量问题 | 单个 bug | 复杂功能 | -| **问题数量** | 3+ | 1 | 1 | -| **生命周期** | 两阶段 | 单次 | 多阶段 | -| **冲突检测** | 有 | 无 | 无 | -| **并行支持** | Worktree 模式 | 无 | 无 | -| **追踪审计** | 完整 | 基础 | 完整 | - ---- - -## 快速参考 - -### 完整流程命令 - -```bash -# 1. 积累阶段 -/issue:new # 手动创建 -/issue:discover # 自动发现 - -# 2. 规划阶段 -/issue:plan --all-pending - -# 3. 队列阶段 -/issue:queue - -# 4. 执行阶段（推荐使用 codex） -codex -p "@.codex/prompts/issue-execute.md" - -# 或手动执行 -/issue:execute -``` - -### CLI 命令速查 - -```bash -ccw issue list # 列出 Issue -ccw issue status <id> # 查看详情 -ccw issue plan --all-pending # 批量规划 -ccw issue queue # 创建队列 -ccw issue next # 获取下一个 -ccw issue done <id> # 标记完成 -ccw issue history # 查看历史 -``` - ---- - -## 总结 - -Issue Loop 工作流是 CCW 中处理批量问题的最佳选择，通过两阶段生命周期设计，实现了问题的高效积累和集中解决。配合 Codex 的串行无监管执行能力，可以在保证质量的同时大幅提升效率。 - -**记住**： -- 积累足够数量（5-10 个）后再集中处理 -- 使用 Codex 进行串行无监管执行 -- 利用 Worktree 模式实现并行执行 -- 保持 Issue 描述的高质量 diff --git a/test-rules-cli-generation.md b/test-rules-cli-generation.md deleted file mode 100644 index 0969bfef..00000000 --- a/test-rules-cli-generation.md +++ /dev/null @@ -1,138 +0,0 @@ -# Test: Rules CLI Generation Feature - -## Overview -This document demonstrates the CLI generation feature for Rules Manager. - -## API Usage - -### Endpoint -``` -POST /api/rules/create -``` - -### Mode: CLI Generation -Set `mode: 'cli-generate'` in the request body. - -## Generation Types - -### 1. From Description -Generate rule from natural language description: - -```json -{ - "mode": "cli-generate", - "generationType": "description", - "description": "Always use TypeScript strict mode and proper type annotations", - "fileName": "typescript-strict.md", - "location": "project", - "subdirectory": "", - "projectPath": "D:/Claude_dms3" -} -``` - -### 2. From Template -Generate rule from template type: - -```json -{ - "mode": "cli-generate", - "generationType": "template", - "templateType": "error-handling", - "fileName": "error-handling-rules.md", - "location": "project", - "subdirectory": "", - "projectPath": "D:/Claude_dms3" -} -``` - -### 3. From Code Extraction -Extract rules from existing codebase: - -```json -{ - "mode": "cli-generate", - "generationType": "extract", - "extractScope": "ccw/src/**/*.ts", - "extractFocus": "error handling, async patterns, type safety", - "fileName": "extracted-patterns.md", - "location": "project", - "subdirectory": "", - "projectPath": "D:/Claude_dms3" -} -``` - -## Response Format - -### Success Response -```json -{ - "success": true, - "fileName": "typescript-strict.md", - "location": "project", - "path": "D:/Claude_dms3/.claude/rules/typescript-strict.md", - "subdirectory": null, - "generatedContent": "# TypeScript Strict Mode\n\n...", - "executionId": "1734168000000-gemini" -} -``` - -### Error Response -```json -{ - "error": "CLI execution failed: ...", - "stderr": "..." -} -``` - -## Implementation Details - -### Function: `generateRuleViaCLI()` - -**Parameters:** -- `generationType`: 'description' | 'template' | 'extract' -- `description`: Rule description (for 'description' mode) -- `templateType`: Template type (for 'template' mode) -- `extractScope`: File pattern like 'src/**/*.ts' (for 'extract' mode) -- `extractFocus`: Focus areas like 'error handling, naming' (for 'extract' mode) -- `fileName`: Target file name (must end with .md) -- `location`: 'project' or 'user' -- `subdirectory`: Optional subdirectory within rules folder -- `projectPath`: Project root path - -**Process:** -1. Build CLI prompt based on generation type -2. Execute Gemini CLI with 10-minute timeout -3. Extract generated content from stdout -4. Create rule file using `createRule()` -5. Return result with execution ID - -### Prompt Templates - -#### Description Mode -``` -PURPOSE: Generate Claude Code memory rule from description -MODE: write -RULES: $(cat ~/.claude/workflows/cli-templates/prompts/universal/00-universal-rigorous-style.txt) -``` - -#### Extract Mode -``` -PURPOSE: Extract coding rules from codebase -MODE: analysis -CONTEXT: @{extractScope} -RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-code-patterns.txt) -``` - -## Error Handling - -- CLI execution timeout: 10 minutes (600000ms) -- Empty content validation -- File existence checking -- Generation type validation - -## Integration - -The feature integrates with: -- **cli-executor.ts**: For Gemini CLI execution -- **createRule()**: For file creation -- **Rules Manager UI**: For user interface (to be implemented)