diff --git a/.claude/skills/ccw-coordinator/README.md b/.claude/skills/ccw-coordinator/README.md index 77a83fb3..3a53578f 100644 --- a/.claude/skills/ccw-coordinator/README.md +++ b/.claude/skills/ccw-coordinator/README.md @@ -1,6 +1,13 @@ # CCW Coordinator -交互式命令编排工具 +交互式命令编排工具:选择命令 → 形成命令链 → 通过 ccw cli 调用 Claude 循环执行 + +## 核心特性 + +- ✅ **仅支持 Claude**:所有执行通过 `ccw cli --tool claude` 调用 +- ✅ **命令在提示词中**:提示词直接包含完整命令调用(如 `/workflow:lite-plan --yes "任务"`) +- ✅ **智能参数组装**:根据命令 YAML 头自动生成正确参数 +- ✅ **循环执行**:每次根据上次完成情况组装下个命令的提示词 ## 使用 @@ -12,34 +19,143 @@ ## 流程 -1. 用户描述任务 -2. Claude推荐命令链 -3. 用户确认或调整 -4. 执行命令链 -5. 生成报告 +1. **用户描述任务**(如"实现用户注册功能") +2. **Claude 推荐命令链**(如 lite-plan → lite-execute → test-cycle-execute) +3. **用户确认或调整**(可以修改顺序或添加/删除命令) +4. **循环执行**: + - 第1个命令:`ccw cli -p "任务: xxx\n/workflow:lite-plan --yes \"xxx\"" --tool claude` + - 第2个命令:`ccw cli -p "任务: xxx\n前序: ...\n/workflow:lite-execute --yes --in-memory" --tool claude` + - ... 以此类推 +5. **生成报告**(保存到 `.workflow/.ccw-coordinator/{timestamp}/`) -## 示例 +## 示例场景 -**Bug修复** +### 标准开发流程 + +**任务**:实现用户注册功能 + +**推荐命令链**: ``` -任务: 修复登录bug -推荐: lite-fix → test-cycle-execute +1. /workflow:lite-plan +2. /workflow:lite-execute +3. /workflow:test-cycle-execute ``` -**新功能** +**执行过程**: +- `lite-plan` → 生成 IMPL_PLAN.md 和探索文件 +- `lite-execute --in-memory` → 使用规划执行任务 +- `test-cycle-execute --session="WFS-xxx"` → 运行测试 + +### Bug 修复 + +**任务**:修复登录页面验证失败问题 + +**推荐命令链**: ``` -任务: 实现注册功能 -推荐: plan → execute → test-cycle-execute +1. /workflow:lite-fix +``` + +**执行过程**: +- `lite-fix --yes "修复登录页面验证失败问题"` → 独立修复(不依赖规划) + +### 完整规划流程 + +**任务**:重构认证模块 + +**推荐命令链**: +``` +1. /workflow:plan +2. /workflow:execute +3. /workflow:review-session-cycle +``` + +**执行过程**: +- `plan` → 生成完整规划文档 +- `execute --resume-session="WFS-xxx"` → 执行规划 +- `review-session-cycle --session="WFS-xxx"` → 审查改动 + +## 提示词示例 + +### 第一个命令 + +``` +任务: 实现用户注册功能,包括邮箱验证和密码加密 + +/workflow:lite-plan --yes "实现用户注册功能,包括邮箱验证和密码加密" +``` + +### 第二个命令 + +``` +任务: 实现用户注册功能,包括邮箱验证和密码加密 + +前序完成: +- /workflow:lite-plan: WFS-register-2025-01-24 (IMPL_PLAN.md, exploration-architecture.json) + +/workflow:lite-execute --yes --in-memory +``` + +### 第三个命令 + +``` +任务: 实现用户注册功能,包括邮箱验证和密码加密 + +前序完成: +- /workflow:lite-plan: WFS-register-2025-01-24 (IMPL_PLAN.md) +- /workflow:lite-execute: WFS-register-2025-01-24 (完成) + +/workflow:test-cycle-execute --yes --session="WFS-register-2025-01-24" +``` + +## 架构说明 + +``` +用户触发: /ccw-coordinator + ↓ +Orchestrator (主流程状态机) + ├─ action-init (初始化会话) + ├─ action-command-selection (选择命令,Claude 推荐) + ├─ action-command-build (调整命令链,可选) + ├─ action-command-execute (循环调用 ccw cli) + │ └─ for each command: + │ 1. 组装提示词 + │ 2. ccw cli --tool claude + │ 3. 解析产物 + │ 4. 更新状态 + └─ action-complete (生成报告) +``` + +## 输出结构 + +``` +.workflow/.ccw-coordinator/{timestamp}/ +├── state.json # 会话状态(命令链、执行结果) +├── command-chain.json # 编排的完整命令链 +├── execution-log.md # 执行日志 +├── final-summary.md # 最终报告 +├── commands/ # 各命令执行详情 +│ ├── 01-workflow-lite-plan.log +│ ├── 02-workflow-lite-execute.log +│ └── 03-workflow-test-cycle-execute.log +└── logs/ # 错误和警告 + ├── errors.log + └── warnings.log ``` ## 文件说明 | 文件 | 用途 | |------|------| -| SKILL.md | Skill入口 | -| phases/orchestrator.md | 编排逻辑 | -| phases/state-schema.md | 状态定义 | -| phases/actions/*.md | 动作实现 | +| SKILL.md | Skill 入口和架构说明 | +| phases/orchestrator.md | 编排器实现(状态机决策逻辑) | +| phases/state-schema.md | 状态结构定义 | +| phases/actions/action-command-execute.md | **核心**:循环执行逻辑 | | specs/specs.md | 命令库、验证规则、注册表 | -| tools/chain-validate.cjs | 验证工具 | -| tools/command-registry.cjs | 命令注册表工具 | +| tools/chain-validate.cjs | 命令链验证工具 | +| tools/command-registry.cjs | 命令注册表(按需提取 YAML 头) | + +## 详细文档 + +- 架构和设计原则 → **SKILL.md** +- 执行逻辑和提示词组装 → **phases/actions/action-command-execute.md** +- 命令库和验证规则 → **specs/specs.md** diff --git a/.claude/skills/ccw-coordinator/SKILL.md b/.claude/skills/ccw-coordinator/SKILL.md index cec008c3..bd0188ec 100644 --- a/.claude/skills/ccw-coordinator/SKILL.md +++ b/.claude/skills/ccw-coordinator/SKILL.md @@ -6,63 +6,115 @@ allowed-tools: Task, AskUserQuestion, Read, Write, Bash, Glob, Grep # CCW Coordinator -交互式命令编排工具:允许用户依次选择命令,形成命令串,然后依次调用claude cli执行整个命令串。 +交互式命令编排工具:允许用户依次选择命令,形成命令链,然后通过 ccw cli 调用 Claude 循环执行每个命令。 -支持灵活的工作流组合,提供交互式界面用于命令选择、编排和执行管理。 +**核心特性**: +- **保持为 Skill**:用户通过 `/ccw-coordinator` 触发 +- **仅支持 Claude**:所有执行通过 `ccw cli --tool claude` 调用 +- **命令在提示词中体现**:提示词直接包含完整命令调用(如 `/workflow:lite-plan --yes "任务"`) +- **智能参数组装**:根据命令 YAML 头的 `argument-hint` 组装正确参数 +- **循环执行**:每次根据上次完成情况和下个命令参数动态组装提示词 ## Architecture Overview ``` +用户: /ccw-coordinator + ↓ ┌─────────────────────────────────────────────────────────────────┐ -│ Orchestrator (状态驱动决策) │ -│ 根据用户选择编排命令和执行流程 │ +│ Orchestrator (主流程状态机) │ +│ 直接在 Claude Code 主流程中运行 │ └───────────────┬─────────────────────────────────────────────────┘ │ ┌───────────┼───────────┬───────────────┐ ↓ ↓ ↓ ↓ ┌─────────┐ ┌──────────────┐ ┌────────────┐ ┌──────────┐ -│ Init │ │ Command │ │ Command │ │ Execute │ +│ Init │ │ Command │ │ Command │ │ Execute │ ← 核心 │ │ │ Selection │ │ Build │ │ │ -│ │ │ │ │ │ │ │ -│ 初始化 │ │ 选择命令 │ │ 编排调整 │ │ 执行链 │ -└─────────┘ └──────────────┘ └────────────┘ └──────────┘ - │ │ │ │ - └───────────────┼──────────────┴────────────┘ - │ +│ 初始化 │ │ 选择命令 │ │ 编排调整 │ │ 循环调用 │ +│ 会话 │ │ 推荐确认 │ │ (可选) │ │ ccw cli │ +└─────────┘ └──────────────┘ └────────────┘ └────┬─────┘ + │ │ │ │ + └───────────────┼──────────────┴──────────────┘ + │ │ + ↓ │ + ┌──────────────┐ │ + │ Complete │ │ + │ 生成报告 │ │ + └──────────────┘ │ + │ + ┌──────────────────────────────┘ + │ 循环执行每个命令 ↓ - ┌──────────────┐ - │ Complete │ - │ 生成报告 │ - └──────────────┘ + ┌───────────────────────────────────────┐ + │ action-command-execute │ + │ for each command in chain: │ + │ 1. 组装提示词 │ + │ 2. 调用 ccw cli --tool claude │ + │ 3. 解析产物 │ + │ 4. 更新状态 │ + └───────────────────┬───────────────────┘ + │ + ↓ + ┌───────────────────────────────┐ + │ ccw cli -p " │ + │ 任务: xxx │ + │ 前序: /workflow:lite-plan │ + │ /workflow:lite-execute ..." │ + │ --tool claude --mode write │ + └───────────────┬───────────────┘ + │ + ↓ + ┌───────────────┐ + │ Claude 执行 │ + │ workflow 命令 │ + └───────────────┘ ``` ## Key Design Principles -1. **智能推荐**: Claude 根据用户任务描述,自动推荐最优命令链 -2. **交互式编排**: 用户通过交互式界面选择和编排命令,实时反馈 -3. **无状态动作**: 每个动作独立执行,通过共享状态进行通信 -4. **灵活的命令库**: 支持ccw workflow命令和标准claude cli命令 -5. **执行透明性**: 展示执行进度、结果和可能的错误 -6. **会话持久化**: 保存编排会话,支持中途暂停和恢复 -7. **智能提示词生成**: 根据任务上下文和前序产物自动生成 ccw cli 提示词 -8. **自动确认**: 所有命令自动添加 `-y` 参数,跳过交互式确认,实现无人值守执行 +1. **智能推荐**:Claude 根据用户任务描述自动推荐最优命令链 +2. **交互式编排**:用户通过交互界面选择和编排命令,实时反馈推荐 +3. **状态持久化**:会话状态保存到 `state.json`,支持中途暂停和恢复 +4. **仅支持 Claude**:所有执行通过 `ccw cli --tool claude` 调用 +5. **命令在提示词中**:提示词直接包含完整命令调用,不是告诉 Claude 去执行什么 +6. **智能参数组装**:根据命令的 YAML 头 `argument-hint` 动态生成参数 +7. **循环执行**:每个命令执行后立即更新状态,根据产物组装下个命令的提示词 +8. **自动确认**:所有命令自动添加 `-y` 参数,跳过交互式确认 +9. **产物追踪**:自动提取会话 ID 和产物文件,用于后续命令链接 ## Intelligent Prompt Generation -执行命令时,系统根据以下信息智能生成 `ccw cli -p` 提示词: +执行命令时,系统智能生成 `ccw cli -p` 提示词。 + +### 核心原则 + +**提示词直接包含完整命令调用**,而不是告诉 Claude 去执行什么: + +``` +✅ 正确: +任务: 实现用户注册 + +/workflow:lite-plan --yes "实现用户注册" + +❌ 错误: +任务: 实现用户注册 +命令: /workflow:lite-plan +参数格式: [--yes] "task" +执行要求: 请执行 lite-plan 命令 +``` ### 提示词构成 ```javascript -// 集成命令注册表 (~/.claude/tools/command-registry.js) +// 集成命令注册表(按需提取) const registry = new CommandRegistry(); -registry.buildRegistry(); - -function generatePrompt(cmd, state) { - const cmdMeta = registry.getCommand(cmd.command); +const commandMeta = registry.getCommands(commandNames); +function generatePrompt(cmd, state, commandMeta) { + // 1. 任务描述 let prompt = `任务: ${state.task_description}\n`; + // 2. 前序完成情况 if (state.execution_results.length > 0) { const previousOutputs = state.execution_results .filter(r => r.status === 'success') @@ -77,16 +129,37 @@ function generatePrompt(cmd, state) { prompt += `\n前序完成:\n${previousOutputs}\n`; } - // 从 YAML 头提取命令元数据 - if (cmdMeta) { - prompt += `\n命令: ${cmd.command}`; - if (cmdMeta.argumentHint) { - prompt += ` ${cmdMeta.argumentHint}`; - } - } + // 3. 组装完整命令行(关键) + const commandLine = assembleCommandLine(cmd, state, commandMeta); + prompt += `\n${commandLine}`; return prompt; } + +// 根据 argument-hint 智能组装参数 +function assembleCommandLine(cmd, state, commandMeta) { + let commandLine = cmd.command; // /workflow:lite-plan + + // 添加 --yes 标志 + commandLine += ' --yes'; + + // 根据命令类型添加特定参数 + const cmdName = cmd.command.split(':').pop(); + + if (cmdName === 'lite-plan') { + commandLine += ` "${state.task_description}"`; + } else if (cmdName === 'lite-execute') { + // 如果有前序规划,使用 --in-memory + if (state.execution_results.some(r => r.command.includes('plan'))) { + commandLine += ' --in-memory'; + } else { + commandLine += ` "${state.task_description}"`; + } + } + // ... 其他命令类型 + + return commandLine; +} ``` ### 产物追踪 @@ -108,14 +181,32 @@ function generatePrompt(cmd, state) { ### 命令调用示例 +**第一个命令(lite-plan)**: +```bash +ccw cli -p "任务: 实现用户认证功能 + +/workflow:lite-plan --yes \"实现用户认证功能\"" --tool claude --mode write -y +``` + +**第二个命令(lite-execute)**: ```bash -# 自动生成的智能提示词 ccw cli -p "任务: 实现用户认证功能 前序完成: -- /workflow:lite-plan: WFS-plan-20250123 (.workflow/IMPL_PLAN.md) +- /workflow:lite-plan: WFS-auth-2025-01-24 (IMPL_PLAN.md, exploration-architecture.json) -命令: /workflow:lite-execute [--resume-session=\"session-id\"]" /workflow:lite-execute +/workflow:lite-execute --yes --in-memory" --tool claude --mode write -y +``` + +**第三个命令(test-cycle-execute)**: +```bash +ccw cli -p "任务: 实现用户认证功能 + +前序完成: +- /workflow:lite-plan: WFS-auth-2025-01-24 (IMPL_PLAN.md) +- /workflow:lite-execute: WFS-auth-2025-01-24 (完成) + +/workflow:test-cycle-execute --yes --session=\"WFS-auth-2025-01-24\"" --tool claude --mode write -y ``` ### 命令注册表集成 diff --git a/.claude/skills/ccw-coordinator/phases/actions/action-command-execute.md b/.claude/skills/ccw-coordinator/phases/actions/action-command-execute.md index 855c020f..5776acca 100644 --- a/.claude/skills/ccw-coordinator/phases/actions/action-command-execute.md +++ b/.claude/skills/ccw-coordinator/phases/actions/action-command-execute.md @@ -1,6 +1,13 @@ # action-command-execute -依次执行命令链,智能生成 ccw cli 提示词 +循环执行命令链,通过 ccw cli 调用 Claude 执行每个命令。 + +## 核心原则 + +1. **仅支持 Claude**:所有执行通过 `ccw cli --tool claude` 调用 +2. **命令在提示词中体现**:提示词直接包含完整的命令调用(如 `/workflow:lite-plan --yes "任务"`) +3. **智能参数组装**:根据命令的 `argument-hint` 组装正确的参数 +4. **循环执行**:每次根据上次完成情况和下个命令参数组装提示词 ## 命令注册表集成 @@ -14,46 +21,171 @@ const commandNames = command_chain.map(cmd => cmd.command); const commandMeta = registry.getCommands(commandNames); ``` -## 提示词生成策略 +## 参数组装逻辑 + +根据命令的 `argument-hint` 和执行上下文,智能组装命令行参数: + +```javascript +function assembleCommandLine(cmd, state, commandMeta) { + const cmdInfo = commandMeta[cmd.command]; + const { task_description, execution_results } = state; + + let commandLine = cmd.command; // e.g., /workflow:lite-plan + + // 1. 添加 --yes 标志(跳过确认) + commandLine += ' --yes'; + + // 2. 根据命令类型添加特定参数 + const cmdName = cmd.command.split(':').pop(); // lite-plan, lite-execute, etc. + + switch (cmdName) { + case 'lite-plan': + case 'plan': + case 'multi-cli-plan': + case 'tdd-plan': + // 规划命令:需要任务描述 + commandLine += ` "${task_description}"`; + break; + + case 'lite-execute': + // 执行命令:如果有前序规划产物,使用 --in-memory + if (execution_results.some(r => + r.command.includes('plan') && r.status === 'success' + )) { + commandLine += ' --in-memory'; + } else { + commandLine += ` "${task_description}"`; + } + break; + + case 'execute': + // 标准执行:可能需要 --resume-session + const planResult = execution_results.find(r => + r.command.includes('plan') && r.status === 'success' + ); + if (planResult?.summary?.session) { + commandLine += ` --resume-session="${planResult.summary.session}"`; + } + break; + + case 'lite-fix': + // 修复命令:如果有 hotfix 标志 + if (cmd.hotfix) { + commandLine += ' --hotfix'; + } + commandLine += ` "${task_description}"`; + break; + + case 'test-cycle-execute': + case 'test-gen': + case 'test-fix-gen': + // 测试命令:使用前序会话 + const execResult = execution_results.find(r => + (r.command.includes('execute') || r.command.includes('fix')) && + r.status === 'success' + ); + if (execResult?.summary?.session) { + commandLine += ` --session="${execResult.summary.session}"`; + } + break; + + case 'review-session-cycle': + case 'review-module-cycle': + case 'review-fix': + // 审查命令:使用前序会话 + const prevSession = execution_results + .filter(r => r.status === 'success' && r.summary?.session) + .pop()?.summary?.session; + if (prevSession) { + commandLine += ` --session="${prevSession}"`; + } + break; + + default: + // 其他命令:尝试传递任务描述 + if (cmdInfo?.argumentHint?.includes('task') || + cmdInfo?.argumentHint?.includes('description')) { + commandLine += ` "${task_description}"`; + } + } + + // 3. 添加用户自定义参数(如果有) + if (cmd.customArgs) { + commandLine += ` ${cmd.customArgs}`; + } + + return commandLine; +} +``` + +## 提示词生成 + +提示词结构:任务描述 + 前序完成 + 完整命令行 ```javascript function generatePrompt(cmd, state, commandMeta) { const { task_description, execution_results } = state; - // 获取命令元数据(从已提取的 commandMeta) - const cmdInfo = commandMeta[cmd.command]; - - // 提取前序产物信息 - const previousOutputs = execution_results - .filter(r => r.status === 'success') - .map(r => { - const summary = r.summary; - if (summary?.session) { - return `- ${r.command}: ${summary.session} (${summary.files?.join(', ') || '完成'})`; - } - return `- ${r.command}: 已完成`; - }) - .join('\n'); - - // 根据命令类型构建提示词 + // 1. 任务描述 let prompt = `任务: ${task_description}\n`; - if (previousOutputs) { + // 2. 前序完成情况 + const successResults = execution_results.filter(r => r.status === 'success'); + if (successResults.length > 0) { + const previousOutputs = successResults + .map(r => { + const summary = r.summary; + if (summary?.session) { + const files = summary.files?.length > 0 + ? summary.files.join(', ') + : '完成'; + return `- ${r.command}: ${summary.session} (${files})`; + } + return `- ${r.command}: 已完成`; + }) + .join('\n'); + prompt += `\n前序完成:\n${previousOutputs}\n`; } - // 添加命令元数据上下文 - if (cmdInfo) { - prompt += `\n命令: ${cmd.command}`; - if (cmdInfo.argumentHint) { - prompt += ` ${cmdInfo.argumentHint}`; - } - } + // 3. 组装完整命令行(关键) + const commandLine = assembleCommandLine(cmd, state, commandMeta); + prompt += `\n${commandLine}`; return prompt; } ``` +### 提示词示例 + +**第一个命令(lite-plan)**: +``` +任务: 实现用户注册功能,包括邮箱验证和密码加密 + +/workflow:lite-plan --yes "实现用户注册功能,包括邮箱验证和密码加密" +``` + +**第二个命令(lite-execute)**: +``` +任务: 实现用户注册功能,包括邮箱验证和密码加密 + +前序完成: +- /workflow:lite-plan: WFS-register-2025-01-24 (IMPL_PLAN.md, exploration-architecture.json) + +/workflow:lite-execute --yes --in-memory +``` + +**第三个命令(test-cycle-execute)**: +``` +任务: 实现用户注册功能,包括邮箱验证和密码加密 + +前序完成: +- /workflow:lite-plan: WFS-register-2025-01-24 (IMPL_PLAN.md) +- /workflow:lite-execute: WFS-register-2025-01-24 (完成) + +/workflow:test-cycle-execute --yes --session="WFS-register-2025-01-24" +``` + ## 执行逻辑 ```javascript @@ -62,23 +194,37 @@ for (let i = current_command_index; i < command_chain.length; i++) { console.log(`[${i+1}/${command_chain.length}] 执行: ${cmd.command}`); - // 生成智能提示词 + // 1. 生成智能提示词 const prompt = generatePrompt(cmd, state, commandMeta); + // 2. 转义提示词中的特殊字符 + const escapedPrompt = prompt + .replace(/\\/g, '\\\\') + .replace(/"/g, '\\"') + .replace(/\n/g, '\\n'); + try { - // 使用 ccw cli 执行(添加 -y 参数跳过确认) - const result = Bash(`ccw cli -p "${prompt.replace(/"/g, '\\"')}" ${cmd.command} -y`, { + // 3. 调用 ccw cli(仅支持 claude) + const result = Bash(`ccw cli -p "${escapedPrompt}" --tool claude --mode write -y`, { run_in_background: true }); + // 4. 等待执行完成(通过 hook 回调) + // ... 等待逻辑由调用者处理 + + // 5. 解析输出,提取产物 + const summary = extractSummary(result.stdout); + + // 6. 记录执行结果 execution_results.push({ command: cmd.command, status: result.exit_code === 0 ? 'success' : 'failed', exit_code: result.exit_code, output: result.stdout, - summary: extractSummary(result.stdout) // 提取关键产物 + summary: summary }); + // 7. 更新命令状态 command_chain[i].status = 'completed'; current_command_index = i + 1; @@ -86,17 +232,37 @@ for (let i = current_command_index; i < command_chain.length; i++) { error_count++; command_chain[i].status = 'failed'; - if (error_count >= 3) break; + // 错误上限检查 + if (error_count >= 3) { + console.log('连续错误超过3次,中止执行'); + break; + } + // 用户决策 const action = await AskUserQuestion({ - options: ['重试', '跳过', '中止'] + questions: [{ + question: `命令 ${cmd.command} 执行失败,如何处理?`, + header: "Error", + multiSelect: false, + options: [ + { label: "重试", description: "重新执行此命令" }, + { label: "跳过", description: "跳过此命令,继续下一个" }, + { label: "中止", description: "终止整个命令链" } + ] + }] }); - if (action === '重试') i--; - if (action === '中止') break; + if (action.answers['Error'] === '重试') i--; + if (action.answers['Error'] === '中止') break; } - updateState({ command_chain, execution_results, current_command_index, error_count }); + // 8. 持久化状态 + updateState({ + command_chain, + execution_results, + current_command_index, + error_count + }); } ``` @@ -104,14 +270,21 @@ for (let i = current_command_index; i < command_chain.length; i++) { ```javascript function extractSummary(output) { - // 从输出提取关键产物信息 - // 例如: 会话ID, 文件路径, 任务完成状态等 - const sessionMatch = output.match(/WFS-\w+-\d+/); - const fileMatch = output.match(/\.workflow\/[^\s]+/g); + // 从 ccw cli 输出提取关键产物信息 + + // 1. 提取会话 ID (WFS-* 或其他格式) + const sessionMatch = output.match(/WFS-[\w-]+/); + + // 2. 提取产物文件路径 + const fileMatches = output.match(/\.workflow\/[^\s\n\r"']+/g); + + // 3. 提取完成状态 + const isSuccess = /✓|completed|success|完成/i.test(output); return { - session: sessionMatch?.[0], - files: fileMatch || [], + session: sessionMatch?.[0] || null, + files: fileMatches ? [...new Set(fileMatches)] : [], // 去重 + status: isSuccess ? 'success' : 'unknown', timestamp: new Date().toISOString() }; } @@ -119,6 +292,58 @@ function extractSummary(output) { ## 状态更新 -- execution_results (包含 summary 产物信息) -- command_chain[].status -- current_command_index +每次命令执行后立即更新 `state.json`: + +```javascript +function updateState(updates) { + const statePath = `${workDir}/state.json`; + const currentState = JSON.parse(Read(statePath)); + + const newState = { + ...currentState, + ...updates, + updated_at: new Date().toISOString() + }; + + Write(statePath, JSON.stringify(newState, null, 2)); +} +``` + +### 更新字段 + +| 字段 | 说明 | +|------|------| +| `execution_results` | 每个命令的执行结果(含 summary 产物信息) | +| `command_chain[].status` | 各命令状态(pending/in_progress/completed/failed) | +| `current_command_index` | 当前执行到的命令索引 | +| `error_count` | 连续错误计数 | + +## 日志记录 + +每个命令执行详情保存到独立日志: + +```javascript +function logCommandExecution(index, cmd, result, workDir) { + const logPath = `${workDir}/commands/${String(index + 1).padStart(2, '0')}-${cmd.command.replace(/[/:]/g, '-')}.log`; + + const logContent = ` +# Command Execution Log +Command: ${cmd.command} +Status: ${result.status} +Exit Code: ${result.exit_code} +Timestamp: ${new Date().toISOString()} + +## Prompt +${result.prompt} + +## Output +${result.output} + +## Summary +Session: ${result.summary?.session || 'N/A'} +Files: ${result.summary?.files?.join(', ') || 'N/A'} +`; + + Write(logPath, logContent); +} +``` diff --git a/.claude/skills/ccw-coordinator/specs/prompt-templates.md b/.claude/skills/ccw-coordinator/specs/prompt-templates.md new file mode 100644 index 00000000..f84ed6c6 --- /dev/null +++ b/.claude/skills/ccw-coordinator/specs/prompt-templates.md @@ -0,0 +1,544 @@ +# Prompt Templates for CLI Execution + +通过 `ccw cli --tool claude` 执行各类命令的提示词模板和实际示例。 + +--- + +## 模板格式 + +``` +任务: {task_description} + +{前序完成信息(如果有)} +{完整的命令调用} +``` + +### 组件说明 + +| 组件 | 说明 | 例子 | +|------|------|------| +| `任务:` | 用户的任务描述 | "实现用户注册功能" | +| 前序完成 | 已完成命令的会话和产物 | "- /workflow:lite-plan: WFS-001 (IMPL_PLAN.md)" | +| 命令行 | 完整的命令调用 | "/workflow:lite-plan --yes \"任务\"" | + +--- + +## 1. 规划命令 (Planning) + +### 1.1 lite-plan + +**模板**: +``` +任务: {task_description} + +/workflow:lite-plan --yes "{task_description}" +``` + +**实例 - 简单任务**: +``` +任务: 添加用户登出功能 + +/workflow:lite-plan --yes "添加用户登出功能" +``` + +**实例 - 复杂任务**: +``` +任务: 重构认证模块,实现 JWT 刷新令牌和会话管理 + +/workflow:lite-plan --yes "重构认证模块,实现 JWT 刷新令牌和会话管理" +``` + +**实例 - 带探索强制**: +``` +任务: 优化数据库查询性能 + +/workflow:lite-plan --yes --explore "优化数据库查询性能" +``` + +### 1.2 plan + +**模板**: +``` +任务: {task_description} + +/workflow:plan --yes "{task_description}" +``` + +**实例**: +``` +任务: 实现支付系统集成 (Stripe) + +/workflow:plan --yes "实现支付系统集成 (Stripe)" +``` + +### 1.3 multi-cli-plan + +**模板**: +``` +任务: {task_description} + +/workflow:multi-cli-plan --yes "{task_description}" +``` + +**实例**: +``` +任务: 设计微服务架构并实现 API 网关 + +/workflow:multi-cli-plan --yes "设计微服务架构并实现 API 网关" +``` + +--- + +## 2. 执行命令 (Execution) + +### 2.1 lite-execute(有规划产物) + +**模板**: +``` +任务: {task_description} + +前序完成: +- /workflow:lite-plan: {session_id} ({artifact_files}) + +/workflow:lite-execute --yes --in-memory +``` + +**实例**: +``` +任务: 实现用户注册功能 + +前序完成: +- /workflow:lite-plan: WFS-register-2025-01-24 (IMPL_PLAN.md, exploration-architecture.json, exploration-security.json) + +/workflow:lite-execute --yes --in-memory +``` + +### 2.2 lite-execute(无规划产物) + +**模板**: +``` +任务: {task_description} + +/workflow:lite-execute --yes "{task_description}" +``` + +**实例**: +``` +任务: 修复页面布局响应式问题 + +/workflow:lite-execute --yes "修复页面布局响应式问题" +``` + +### 2.3 execute(有规划会话) + +**模板**: +``` +任务: {task_description} + +前序完成: +- /workflow:plan: {session_id} ({artifact_files}) + +/workflow:execute --yes --resume-session="{session_id}" +``` + +**实例**: +``` +任务: 实现微服务网关 + +前序完成: +- /workflow:plan: WFS-gateway-2025-01-24 (IMPL_PLAN.md, .workflow/tasks/) + +/workflow:execute --yes --resume-session="WFS-gateway-2025-01-24" +``` + +--- + +## 3. Bug 修复命令 (BugFix) + +### 3.1 lite-fix(轻量级修复) + +**模板**: +``` +任务: {task_description} + +/workflow:lite-fix --yes "{task_description}" +``` + +**实例**: +``` +任务: 修复登录表单验证失败问题 + +/workflow:lite-fix --yes "修复登录表单验证失败问题" +``` + +### 3.2 lite-fix --hotfix(紧急修复) + +**模板**: +``` +任务: {task_description} + +/workflow:lite-fix --yes --hotfix "{task_description}" +``` + +**实例**: +``` +任务: 紧急修复生产环境支付流程中断 + +/workflow:lite-fix --yes --hotfix "紧急修复生产环境支付流程中断" +``` + +--- + +## 4. 测试命令 (Testing) + +### 4.1 test-cycle-execute(有前序执行) + +**模板**: +``` +任务: {task_description} + +前序完成: +- /workflow:lite-execute: {session_id} ({artifact_files}) + +/workflow:test-cycle-execute --yes --session="{session_id}" +``` + +**实例**: +``` +任务: 实现用户注册功能 + +前序完成: +- /workflow:lite-plan: WFS-register-2025-01-24 (IMPL_PLAN.md) +- /workflow:lite-execute: WFS-register-2025-01-24 (完成) + +/workflow:test-cycle-execute --yes --session="WFS-register-2025-01-24" +``` + +### 4.2 test-gen(生成测试) + +**模板**: +``` +任务: {task_description} + +/workflow:test-gen --yes "{task_description}" +``` + +**实例**: +``` +任务: 为认证模块生成单元测试 + +/workflow:test-gen --yes "为认证模块生成单元测试" +``` + +### 4.3 test-fix-gen(生成测试和修复) + +**模板**: +``` +任务: {task_description} + +/workflow:test-fix-gen --yes "{task_description}" +``` + +**实例**: +``` +任务: 生成并修复数据库连接超时问题的测试 + +/workflow:test-fix-gen --yes "生成并修复数据库连接超时问题的测试" +``` + +--- + +## 5. 代码审查命令 (Review) + +### 5.1 review-session-cycle(审查执行会话) + +**模板**: +``` +任务: {task_description} + +前序完成: +- /workflow:execute: {session_id} ({artifact_files}) + +/workflow:review-session-cycle --yes --session="{session_id}" +``` + +**实例**: +``` +任务: 实现支付系统集成 + +前序完成: +- /workflow:plan: WFS-payment-2025-01-24 (IMPL_PLAN.md) +- /workflow:execute: WFS-payment-2025-01-24 (完成) + +/workflow:review-session-cycle --yes --session="WFS-payment-2025-01-24" +``` + +### 5.2 review-module-cycle(审查特定模块) + +**模板**: +``` +任务: {task_description} + +/workflow:review-module-cycle --yes "{module_path}" --dimensions="{dimensions}" +``` + +**实例**: +``` +任务: 审查认证模块的安全性 + +/workflow:review-module-cycle --yes "src/auth" --dimensions="security,error-handling" +``` + +### 5.3 review-fix(审查和修复) + +**模板**: +``` +任务: {task_description} + +前序完成: +- /workflow:review-session-cycle: {session_id} ({findings}) + +/workflow:review-fix --yes --session="{session_id}" +``` + +**实例**: +``` +任务: 修复代码审查发现的问题 + +前序完成: +- /workflow:review-session-cycle: WFS-payment-2025-01-24 (审查完成) + +/workflow:review-fix --yes --session="WFS-payment-2025-01-24" +``` + +--- + +## 6. 验证命令 (Verification) + +### 6.1 plan-verify(计划验证) + +**模板**: +``` +任务: {task_description} + +前序完成: +- /workflow:plan: {session_id} (IMPL_PLAN.md) + +/workflow:plan-verify --yes --session="{session_id}" +``` + +**实例**: +``` +任务: 验证支付系统实现计划 + +前序完成: +- /workflow:plan: WFS-payment-2025-01-24 (IMPL_PLAN.md) + +/workflow:plan-verify --yes --session="WFS-payment-2025-01-24" +``` + +### 6.2 tdd-verify(TDD 验证) + +**模板**: +``` +任务: {task_description} + +前序完成: +- /workflow:execute: {session_id} (完成) + +/workflow:tdd-verify --yes --session="{session_id}" +``` + +**实例**: +``` +任务: 验证 TDD 流程合规性 + +前序完成: +- /workflow:execute: WFS-tdd-auth-2025-01-24 (完成) + +/workflow:tdd-verify --yes --session="WFS-tdd-auth-2025-01-24" +``` + +--- + +## 7. 常见命令链提示词 + +### 7.1 标准开发流程:plan → execute → test + +**第 1 步 - 规划**: +``` +任务: 实现用户注册功能,包括邮箱验证和密码加密 + +/workflow:lite-plan --yes "实现用户注册功能,包括邮箱验证和密码加密" +``` + +**第 2 步 - 执行**: +``` +任务: 实现用户注册功能,包括邮箱验证和密码加密 + +前序完成: +- /workflow:lite-plan: WFS-register-2025-01-24 (IMPL_PLAN.md, exploration-architecture.json, exploration-security.json) + +/workflow:lite-execute --yes --in-memory +``` + +**第 3 步 - 测试**: +``` +任务: 实现用户注册功能,包括邮箱验证和密码加密 + +前序完成: +- /workflow:lite-plan: WFS-register-2025-01-24 (IMPL_PLAN.md) +- /workflow:lite-execute: WFS-register-2025-01-24 (完成) + +/workflow:test-cycle-execute --yes --session="WFS-register-2025-01-24" +``` + +### 7.2 完整规划流程:plan → execute → review → review-fix + +**第 1 步 - 规划**: +``` +任务: 重构认证模块,实现 OAuth2 和会话管理 + +/workflow:plan --yes "重构认证模块,实现 OAuth2 和会话管理" +``` + +**第 2 步 - 执行**: +``` +任务: 重构认证模块,实现 OAuth2 和会话管理 + +前序完成: +- /workflow:plan: WFS-auth-2025-01-24 (IMPL_PLAN.md, .workflow/tasks/) + +/workflow:execute --yes --resume-session="WFS-auth-2025-01-24" +``` + +**第 3 步 - 审查**: +``` +任务: 重构认证模块,实现 OAuth2 和会话管理 + +前序完成: +- /workflow:plan: WFS-auth-2025-01-24 (IMPL_PLAN.md) +- /workflow:execute: WFS-auth-2025-01-24 (完成) + +/workflow:review-session-cycle --yes --session="WFS-auth-2025-01-24" +``` + +**第 4 步 - 审查修复**: +``` +任务: 重构认证模块,实现 OAuth2 和会话管理 + +前序完成: +- /workflow:plan: WFS-auth-2025-01-24 (IMPL_PLAN.md) +- /workflow:execute: WFS-auth-2025-01-24 (完成) +- /workflow:review-session-cycle: WFS-auth-2025-01-24 (审查完成) + +/workflow:review-fix --yes --session="WFS-auth-2025-01-24" +``` + +### 7.3 Bug 修复 + 测试 + +**第 1 步 - 修复**: +``` +任务: 修复页面加载超时问题 + +/workflow:lite-fix --yes "修复页面加载超时问题" +``` + +**第 2 步 - 测试**: +``` +任务: 修复页面加载超时问题 + +前序完成: +- /workflow:lite-fix: WFS-fix-timeout-2025-01-24 (完成) + +/workflow:test-cycle-execute --yes --session="WFS-fix-timeout-2025-01-24" +``` + +--- + +## 8. 参数组装规则 + +### 规则 1:任务描述 + +- 规划命令(`lite-plan`, `plan` 等)**必须** 包含任务描述 +- 格式:`命令 --yes "任务描述"` + +### 规则 2:会话复用 + +- 执行命令在有规划产物时使用 `--in-memory` +- 其他命令使用 `--session="WFS-xxx"` 引用前序会话 + +### 规则 3:自动确认 + +- 所有命令都添加 `--yes` 标志跳过交互式确认 + +### 规则 4:文件路径 + +- 需要文件路径时(如 `review-module-cycle`),使用相对于项目根的路径 +- 例:`src/auth`, `src/modules/payment` + +--- + +## 9. 特殊情况处理 + +### 9.1 特殊字符转义 + +**问题**:提示词中包含双引号 + +**解决**: +```bash +# 在双引号内使用 \" +ccw cli -p "任务: 实现 \"特殊\" 功能\n/workflow:lite-plan ..." --tool claude +``` + +### 9.2 多行任务描述 + +**问题**:任务描述很长 + +**解决**: +``` +任务: 实现完整的支付系统,包括: +- Stripe 集成 +- 订单管理 +- 发票生成 +- 退款处理 + +/workflow:plan --yes "实现完整的支付系统:Stripe 集成、订单管理、发票生成、退款处理" +``` + +### 9.3 特殊路径处理 + +**问题**:路径包含空格 + +**解决**: +``` +任务: 审查用户管理模块 + +/workflow:review-module-cycle --yes "src/modules/user management" --dimensions="security" +``` + +--- + +## 10. 调试技巧 + +### 查看实际调用 + +在 `action-command-execute.md` 中添加日志: + +```javascript +console.log(`[DEBUG] Assembling prompt for: ${cmd.command}`) +console.log(`[DEBUG] Prompt:\n${prompt}`) +console.log(`[DEBUG] CLI Call:\nccw cli -p "${escapedPrompt}" --tool claude --mode write -y`) +``` + +### 验证产物提取 + +检查 `.workflow/.ccw-coordinator/{timestamp}/commands/` 目录下的日志文件,查看 CLI 输出和产物提取结果。 + +### 测试提示词 + +手动调用 ccw cli 测试: + +```bash +ccw cli -p "任务: 测试任务\n/workflow:lite-plan --yes \"测试任务\"" --tool claude --mode write -y +``` diff --git a/.claude/skills/ccw-coordinator/specs/specs.md b/.claude/skills/ccw-coordinator/specs/specs.md index c0c24746..7191ef83 100644 --- a/.claude/skills/ccw-coordinator/specs/specs.md +++ b/.claude/skills/ccw-coordinator/specs/specs.md @@ -344,19 +344,28 @@ const cmdInfo = commandMeta[cmd.command]; ### 提示词生成 -智能提示词自动包含: +智能提示词直接包含完整命令调用: -1. **任务上下文**: 用户任务描述 -2. **前序产物**: 已完成命令的产物信息 -3. **命令元数据**: 命令的参数提示和描述 +1. **任务描述**: 用户的任务描述 +2. **前序产物**: 已完成命令的会话和产物信息 +3. **完整命令行**: 下个命令的完整调用(通过 `argument-hint` 组装) +**✅ 正确示例**: ``` 任务: 实现用户注册功能 前序完成: - /workflow:lite-plan: WFS-plan-001 (IMPL_PLAN.md) +/workflow:lite-execute --yes --in-memory +``` + +**❌ 旧的错误示例**(不再使用): +``` +任务: 实现用户注册功能 +前序完成: +- /workflow:lite-plan: WFS-plan-001 (IMPL_PLAN.md) 命令: /workflow:lite-execute [--resume-session="session-id"] ``` -详见 `tools/README.md`。 +详见 `tools/README.md` 和 `specs/prompt-templates.md`。 diff --git a/.claude/skills/ccw-coordinator/tools/README.md b/.claude/skills/ccw-coordinator/tools/README.md index b44335b0..58222c6f 100644 --- a/.claude/skills/ccw-coordinator/tools/README.md +++ b/.claude/skills/ccw-coordinator/tools/README.md @@ -70,20 +70,42 @@ node .claude/skills/ccw-coordinator/tools/command-registry.cjs lite-plan lite-ex const commandNames = command_chain.map(cmd => cmd.command); const commandMeta = registry.getCommands(commandNames); -// 2. 生成提示词时使用 -function generatePrompt(cmd, state, commandMeta) { +// 2. 参数组装时使用 argumentHint +function assembleCommandLine(cmd, state, commandMeta) { const cmdInfo = commandMeta[cmd.command]; + let commandLine = cmd.command; // /workflow:lite-plan + + commandLine += ' --yes'; // 自动确认 + + // 根据 argumentHint 智能组装参数 + const cmdName = cmd.command.split(':').pop(); + if (cmdName === 'lite-plan') { + commandLine += ` "${state.task_description}"`; + } else if (cmdName === 'lite-execute' && hasPlanResult(state)) { + commandLine += ' --in-memory'; + } + + return commandLine; +} + +// 3. 生成提示词(直接包含完整命令) +function generatePrompt(cmd, state, commandMeta) { let prompt = `任务: ${state.task_description}\n`; - if (cmdInfo?.argumentHint) { - prompt += `命令: ${cmd.command} ${cmdInfo.argumentHint}`; + // 添加前序完成 + if (state.execution_results.length > 0) { + prompt += `\n前序完成:\n${formatResults(state.execution_results)}\n`; } + // 组装完整命令行(关键) + const commandLine = assembleCommandLine(cmd, state, commandMeta); + prompt += `\n${commandLine}`; + return prompt; } ``` -确保 `ccw cli -p "..."` 提示词包含准确的命令参数提示。 +确保 `ccw cli -p "..."` 提示词直接包含完整命令调用,而不是准则。 ### 目录查找逻辑