claude-code-workflow 6.3.18 → 6.3.19

package/.claude/skills/skill-generator/specs/cli-integration.md

@@ -0,0 +1,448 @@
+# CLI Integration Specification
+
+CCW CLI 集成规范，定义 Skill 中如何正确调用外部 CLI 工具。
+
+---
+
+## 执行模式
+
+### 1. 同步执行 (Blocking)
+
+适用于需要立即获取结果的场景。
+
+```javascript
+// Agent 调用 - 同步
+const result = Task({
+  subagent_type: 'universal-executor',
+  prompt: '执行任务...',
+  run_in_background: false  // 关键: 同步执行
+});
+
+// 结果立即可用
+console.log(result);
+```
+
+### 2. 异步执行 (Background)
+
+适用于长时间运行的 CLI 命令。
+
+```javascript
+// CLI 调用 - 异步
+const task = Bash({
+  command: 'ccw cli -p "..." --tool gemini --mode analysis',
+  run_in_background: true  // 关键: 后台执行
+});
+
+// 立即返回，不等待结果
+// task.task_id 可用于后续查询
+```
+
+---
+
+## CCW CLI 调用规范
+
+### 基础命令结构
+
+```bash
+ccw cli -p "<PROMPT>" --tool <gemini|qwen|codex> --mode <analysis|write>
+```
+
+### 参数说明
+
+| 参数 | 必需 | 说明 |
+|------|------|------|
+| `-p "<prompt>"` | ✓ | 提示词（使用双引号） |
+| `--tool <tool>` | ✓ | 工具选择: gemini, qwen, codex |
+| `--mode <mode>` | ✓ | 执行模式: analysis, write |
+| `--cd <path>` | - | 工作目录 |
+| `--includeDirs <dirs>` | - | 包含额外目录（逗号分隔） |
+| `--resume [id]` | - | 恢复会话 |
+
+### 模式选择
+
+```
+┌─ 分析/文档任务?
+│  └─→ --mode analysis (只读)
+│
+└─ 实现/修改任务?
+   └─→ --mode write (读写)
+```
+
+---
+
+## Agent 类型与选择
+
+### universal-executor
+
+通用执行器，最常用的 Agent 类型。
+
+```javascript
+Task({
+  subagent_type: 'universal-executor',
+  prompt: `
+执行任务:
+1. 读取配置文件
+2. 分析依赖关系
+3. 生成报告到 ${outputPath}
+  `,
+  run_in_background: false
+});
+```
+
+**适用场景**:
+- 多步骤任务执行
+- 文件操作（读/写/编辑）
+- 需要工具调用的任务
+
+### Explore
+
+代码探索 Agent，快速理解代码库。
+
+```javascript
+Task({
+  subagent_type: 'Explore',
+  prompt: `
+探索 src/ 目录:
+- 识别主要模块
+- 理解目录结构
+- 找到入口点
+
+Thoroughness: medium
+  `,
+  run_in_background: false
+});
+```
+
+**适用场景**:
+- 代码库探索
+- 文件发现
+- 结构理解
+
+### cli-explore-agent
+
+深度代码分析 Agent。
+
+```javascript
+Task({
+  subagent_type: 'cli-explore-agent',
+  prompt: `
+深度分析 src/auth/ 模块:
+- 认证流程
+- 会话管理
+- 安全机制
+  `,
+  run_in_background: false
+});
+```
+
+**适用场景**:
+- 深度代码理解
+- 设计模式识别
+- 复杂逻辑分析
+
+---
+
+## 会话管理
+
+### 会话恢复
+
+```javascript
+// 保存会话 ID
+const session = Bash({
+  command: 'ccw cli -p "初始分析..." --tool gemini --mode analysis',
+  run_in_background: true
+});
+
+// 后续恢复
+const continuation = Bash({
+  command: `ccw cli -p "继续分析..." --tool gemini --mode analysis --resume ${session.id}`,
+  run_in_background: true
+});
+```
+
+### 多会话合并
+
+```javascript
+// 合并多个会话的上下文
+const merged = Bash({
+  command: `ccw cli -p "汇总分析..." --tool gemini --mode analysis --resume ${id1},${id2}`,
+  run_in_background: true
+});
+```
+
+---
+
+## Skill 中的 CLI 集成模式
+
+### 模式 1: 单次调用
+
+简单任务，一次调用完成。
+
+```javascript
+// Phase 执行
+async function executePhase(context) {
+  const result = Bash({
+    command: `ccw cli -p "
+PURPOSE: 分析项目结构
+TASK: 识别模块、依赖、入口点
+MODE: analysis
+CONTEXT: @src/**/*
+EXPECTED: JSON 格式的结构报告
+" --tool gemini --mode analysis --cd ${context.projectRoot}`,
+    run_in_background: true,
+    timeout: 600000
+  });
+
+  // 等待完成
+  return await waitForCompletion(result.task_id);
+}
+```
+
+### 模式 2: 链式调用
+
+多步骤任务，每步依赖前一步结果。
+
+```javascript
+async function executeChain(context) {
+  // Step 1: 收集
+  const collectId = await runCLI('collect', context);
+
+  // Step 2: 分析 (依赖 Step 1)
+  const analyzeId = await runCLI('analyze', context, `--resume ${collectId}`);
+
+  // Step 3: 生成 (依赖 Step 2)
+  const generateId = await runCLI('generate', context, `--resume ${analyzeId}`);
+
+  return generateId;
+}
+
+async function runCLI(step, context, resumeFlag = '') {
+  const prompts = {
+    collect: 'PURPOSE: 收集代码文件...',
+    analyze: 'PURPOSE: 分析代码模式...',
+    generate: 'PURPOSE: 生成文档...'
+  };
+
+  const result = Bash({
+    command: `ccw cli -p "${prompts[step]}" --tool gemini --mode analysis ${resumeFlag}`,
+    run_in_background: true
+  });
+
+  return await waitForCompletion(result.task_id);
+}
+```
+
+### 模式 3: 并行调用
+
+独立任务并行执行。
+
+```javascript
+async function executeParallel(context) {
+  const tasks = [
+    { type: 'structure', tool: 'gemini' },
+    { type: 'dependencies', tool: 'gemini' },
+    { type: 'patterns', tool: 'qwen' }
+  ];
+
+  // 并行启动
+  const taskIds = tasks.map(task =>
+    Bash({
+      command: `ccw cli -p "分析 ${task.type}..." --tool ${task.tool} --mode analysis`,
+      run_in_background: true
+    }).task_id
+  );
+
+  // 等待全部完成
+  const results = await Promise.all(
+    taskIds.map(id => waitForCompletion(id))
+  );
+
+  return results;
+}
+```
+
+### 模式 4: Fallback 链
+
+工具失败时自动切换。
+
+```javascript
+async function executeWithFallback(context) {
+  const tools = ['gemini', 'qwen', 'codex'];
+  let result = null;
+
+  for (const tool of tools) {
+    try {
+      result = await runWithTool(tool, context);
+      if (result.success) break;
+    } catch (error) {
+      console.log(`${tool} failed, trying next...`);
+    }
+  }
+
+  if (!result?.success) {
+    throw new Error('All tools failed');
+  }
+
+  return result;
+}
+
+async function runWithTool(tool, context) {
+  const task = Bash({
+    command: `ccw cli -p "..." --tool ${tool} --mode analysis`,
+    run_in_background: true,
+    timeout: 600000
+  });
+
+  return await waitForCompletion(task.task_id);
+}
+```
+
+---
+
+## 提示词模板集成
+
+### 引用协议模板
+
+```bash
+# 分析模式 - 必须引用 analysis-protocol.md
+ccw cli -p "
+RULES: $(cat ~/.claude/workflows/cli-templates/protocols/analysis-protocol.md)
+$(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-code-patterns.txt)
+..." --tool gemini --mode analysis
+
+# 写入模式 - 必须引用 write-protocol.md
+ccw cli -p "
+RULES: $(cat ~/.claude/workflows/cli-templates/protocols/write-protocol.md)
+$(cat ~/.claude/workflows/cli-templates/prompts/development/02-implement-feature.txt)
+..." --tool codex --mode write
+```
+
+### 动态模板构建
+
+```javascript
+function buildPrompt(config) {
+  const { purpose, task, mode, context, expected, template } = config;
+
+  const protocolPath = mode === 'write'
+    ? '~/.claude/workflows/cli-templates/protocols/write-protocol.md'
+    : '~/.claude/workflows/cli-templates/protocols/analysis-protocol.md';
+
+  return `
+PURPOSE: ${purpose}
+TASK: ${task.map(t => `• ${t}`).join('\n')}
+MODE: ${mode}
+CONTEXT: ${context}
+EXPECTED: ${expected}
+RULES: $(cat ${protocolPath}) $(cat ${template})
+`;
+}
+```
+
+---
+
+## 超时配置
+
+### 推荐超时值
+
+| 任务类型 | 超时 (ms) | 说明 |
+|---------|----------|------|
+| 快速分析 | 300000 | 5 分钟 |
+| 标准分析 | 600000 | 10 分钟 |
+| 深度分析 | 1200000 | 20 分钟 |
+| 代码生成 | 1800000 | 30 分钟 |
+| 复杂任务 | 3600000 | 60 分钟 |
+
+### Codex 特殊处理
+
+Codex 需要更长的超时时间（建议 3x）。
+
+```javascript
+const timeout = tool === 'codex' ? baseTimeout * 3 : baseTimeout;
+
+Bash({
+  command: `ccw cli -p "..." --tool ${tool} --mode write`,
+  run_in_background: true,
+  timeout: timeout
+});
+```
+
+---
+
+## 错误处理
+
+### 常见错误
+
+| 错误 | 原因 | 处理 |
+|------|------|------|
+| ETIMEDOUT | 网络超时 | 重试或切换工具 |
+| Exit code 1 | 命令执行失败 | 检查参数，切换工具 |
+| Context overflow | 上下文过大 | 减少输入范围 |
+
+### 重试策略
+
+```javascript
+async function executeWithRetry(command, maxRetries = 3) {
+  let lastError = null;
+
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      const task = Bash({
+        command,
+        run_in_background: true,
+        timeout: 600000
+      });
+
+      return await waitForCompletion(task.task_id);
+    } catch (error) {
+      lastError = error;
+      console.log(`Attempt ${attempt} failed: ${error.message}`);
+
+      // 指数退避
+      if (attempt < maxRetries) {
+        await sleep(Math.pow(2, attempt) * 1000);
+      }
+    }
+  }
+
+  throw lastError;
+}
+```
+
+---
+
+## 最佳实践
+
+### 1. run_in_background 规则
+
+```
+Agent 调用 (Task):
+  run_in_background: false  → 同步，立即获取结果
+
+CLI 调用 (Bash + ccw cli):
+  run_in_background: true   → 异步，后台执行
+```
+
+### 2. 工具选择
+
+```
+分析任务: gemini > qwen
+生成任务: codex > gemini > qwen
+代码修改: codex > gemini
+```
+
+### 3. 会话管理
+
+- 相关任务使用 `--resume` 保持上下文
+- 独立任务不使用 `--resume`
+
+### 4. 提示词规范
+
+- 始终使用 PURPOSE/TASK/MODE/CONTEXT/EXPECTED/RULES 结构
+- 必须引用协议模板（analysis-protocol 或 write-protocol）
+- 使用 `$(cat ...)` 动态加载模板
+
+### 5. 结果处理
+
+- 持久化重要结果到 workDir
+- Brief returns: 路径 + 摘要，避免上下文溢出
+- JSON 格式便于后续处理