claude-code-workflow 6.3.18 → 6.3.19

package/.claude/skills/skill-generator/specs/execution-modes.md

@@ -0,0 +1,396 @@
+# Execution Modes Specification
+
+两种 Skill 执行模式的详细规范定义。
+
+---
+
+## 模式概览
+
+| 特性 | Sequential (顺序) | Autonomous (自主) |
+|------|-------------------|-------------------|
+| 执行顺序 | 固定（数字前缀） | 动态（编排器决策） |
+| 阶段依赖 | 强依赖 | 弱依赖/无依赖 |
+| 状态管理 | 隐式（阶段产出） | 显式（状态文件） |
+| 适用场景 | 流水线任务 | 交互式任务 |
+| 复杂度 | 低 | 中-高 |
+| 可扩展性 | 插入子阶段 | 添加新动作 |
+
+---
+
+## Mode 1: Sequential (顺序模式)
+
+### 定义
+
+阶段按固定顺序线性执行，每个阶段的输出作为下一阶段的输入。
+
+### 目录结构
+
+```
+phases/
+├── 01-{first-step}.md
+├── 02-{second-step}.md
+├── 02.5-{sub-step}.md      # 可选：子阶段
+├── 03-{third-step}.md
+└── ...
+```
+
+### 执行流程
+
+```
+┌─────────┐     ┌─────────┐     ┌─────────┐
+│Phase 01 │────▶│Phase 02 │────▶│Phase 03 │────▶ ...
+└─────────┘     └─────────┘     └─────────┘
+     │               │               │
+     ▼               ▼               ▼
+  output1.json   output2.md      output3.md
+```
+
+### Phase 文件规范
+
+```markdown
+# Phase N: {阶段名称}
+
+{一句话描述}
+
+## Objective
+
+{详细目标}
+
+## Input
+
+- 依赖: {上一阶段产出}
+- 配置: {配置文件}
+
+## Execution Steps
+
+### Step 1: {步骤}
+{执行代码或说明}
+
+### Step 2: {步骤}
+{执行代码或说明}
+
+## Output
+
+- **File**: `{输出文件}`
+- **Format**: {JSON/Markdown}
+
+## Next Phase
+
+→ [Phase N+1: xxx](0N+1-xxx.md)
+```
+
+### 适用场景
+
+- **文档生成**: 收集 → 分析 → 组装 → 优化
+- **代码分析**: 扫描 → 解析 → 报告
+- **数据处理**: 提取 → 转换 → 加载
+
+### 优点
+
+- 逻辑清晰，易于理解
+- 调试简单，可逐阶段验证
+- 输出可预测
+
+### 缺点
+
+- 灵活性低
+- 难以处理分支逻辑
+- 用户交互受限
+
+---
+
+## Mode 2: Autonomous (自主模式)
+
+### 定义
+
+无固定执行顺序，由编排器 (Orchestrator) 根据当前状态动态选择下一个动作。
+
+### 目录结构
+
+```
+phases/
+├── orchestrator.md          # 编排器：核心决策逻辑
+├── state-schema.md          # 状态结构定义
+└── actions/                 # 独立动作（无顺序）
+    ├── action-{a}.md
+    ├── action-{b}.md
+    ├── action-{c}.md
+    └── ...
+```
+
+### 核心组件
+
+#### 1. Orchestrator (编排器)
+
+```markdown
+# Orchestrator
+
+## Role
+
+根据当前状态选择并执行下一个动作。
+
+## State Reading
+
+读取状态文件: `{workDir}/state.json`
+
+## Decision Logic
+
+```javascript
+function selectNextAction(state) {
+  // 1. 检查终止条件
+  if (state.status === 'completed') return null;
+  if (state.error_count > MAX_RETRIES) return 'action-abort';
+  
+  // 2. 根据状态选择动作
+  if (!state.initialized) return 'action-init';
+  if (state.pending_items.length > 0) return 'action-process';
+  if (state.needs_review) return 'action-review';
+  
+  // 3. 默认动作
+  return 'action-complete';
+}
+```
+
+## Execution Loop
+
+```
+while (true) {
+  state = readState();
+  action = selectNextAction(state);
+  if (!action) break;
+  
+  result = executeAction(action, state);
+  updateState(result);
+}
+```
+```
+
+#### 2. State Schema (状态结构)
+
+```markdown
+# State Schema
+
+## 状态文件
+
+位置: `{workDir}/state.json`
+
+## 结构定义
+
+```typescript
+interface SkillState {
+  // 元信息
+  skill_name: string;
+  started_at: string;
+  updated_at: string;
+  
+  // 执行状态
+  status: 'pending' | 'running' | 'completed' | 'failed';
+  current_action: string | null;
+  completed_actions: string[];
+  
+  // 业务数据
+  context: Record<string, any>;
+  pending_items: any[];
+  results: Record<string, any>;
+  
+  // 错误追踪
+  errors: Array<{
+    action: string;
+    message: string;
+    timestamp: string;
+  }>;
+  error_count: number;
+}
+```
+
+## 初始状态
+
+```json
+{
+  "skill_name": "{skill-name}",
+  "started_at": "{ISO8601}",
+  "updated_at": "{ISO8601}",
+  "status": "pending",
+  "current_action": null,
+  "completed_actions": [],
+  "context": {},
+  "pending_items": [],
+  "results": {},
+  "errors": [],
+  "error_count": 0
+}
+```
+```
+
+#### 3. Action (动作)
+
+```markdown
+# Action: {action-name}
+
+## Purpose
+
+{动作目的}
+
+## Preconditions
+
+- [ ] 条件1
+- [ ] 条件2
+
+## Execution
+
+{执行逻辑}
+
+## State Updates
+
+```javascript
+return {
+  completed_actions: [...state.completed_actions, 'action-name'],
+  results: {
+    ...state.results,
+    action_name: { /* 结果 */ }
+  },
+  // 其他状态更新
+};
+```
+
+## Next Actions (Hints)
+
+- 成功时: `action-{next}`
+- 失败时: `action-retry` 或 `action-abort`
+```
+
+### 执行流程
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      Orchestrator Loop                           │
+│  ┌─────────────────────────────────────────────────────────┐    │
+│  │                                                          │    │
+│  │   ┌──────────┐     ┌──────────┐     ┌──────────┐        │    │
+│  │   │ Read     │────▶│ Select   │────▶│ Execute  │        │    │
+│  │   │ State    │     │ Action   │     │ Action   │        │    │
+│  │   └──────────┘     └──────────┘     └──────────┘        │    │
+│  │        ▲                                  │              │    │
+│  │        │                                  ▼              │    │
+│  │        │           ┌──────────┐                         │    │
+│  │        └───────────│ Update   │◀────────────────────────┘    │
+│  │                    │ State    │                              │
+│  │                    └──────────┘                              │
+│  │                                                          │    │
+│  └─────────────────────────────────────────────────────────┘    │
+│                              │                                   │
+│                              ▼                                   │
+│                    ┌──────────────────┐                         │
+│                    │ Termination?     │                         │
+│                    │ - completed      │                         │
+│                    │ - max_retries    │                         │
+│                    │ - user_abort     │                         │
+│                    └──────────────────┘                         │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 动作目录 (Action Catalog)
+
+在 `specs/action-catalog.md` 中定义：
+
+```markdown
+# Action Catalog
+
+## Available Actions
+
+| Action | Purpose | Preconditions | Effects |
+|--------|---------|---------------|---------|
+| action-init | 初始化状态 | status=pending | status=running |
+| action-process | 处理待办项 | pending_items.length>0 | pending_items-- |
+| action-review | 用户审核 | needs_review=true | needs_review=false |
+| action-complete | 完成任务 | pending_items.length=0 | status=completed |
+| action-abort | 中止任务 | error_count>MAX | status=failed |
+
+## Action Dependencies Graph
+
+```mermaid
+graph TD
+    INIT[action-init] --> PROCESS[action-process]
+    PROCESS --> PROCESS
+    PROCESS --> REVIEW[action-review]
+    REVIEW --> PROCESS
+    REVIEW --> COMPLETE[action-complete]
+    PROCESS --> ABORT[action-abort]
+```
+```
+
+### 适用场景
+
+- **交互式任务**: 问答、对话、表单填写
+- **状态机任务**: Issue 管理、工作流审批
+- **探索式任务**: 调试、诊断、搜索
+
+### 优点
+
+- 高度灵活，适应动态需求
+- 支持复杂分支逻辑
+- 易于扩展新动作
+
+### 缺点
+
+- 复杂度高
+- 状态管理开销
+- 调试难度大
+
+---
+
+## 模式选择指南
+
+### 决策流程
+
+```
+用户需求分析
+     │
+     ▼
+┌────────────────────────────┐
+│ 阶段间是否有强依赖关系？     │
+└────────────────────────────┘
+     │
+     ├── 是 → Sequential
+     │
+     └── 否 → 继续判断
+              │
+              ▼
+     ┌────────────────────────────┐
+     │ 是否需要动态响应用户意图？   │
+     └────────────────────────────┘
+              │
+              ├── 是 → Autonomous
+              │
+              └── 否 → Sequential
+```
+
+### 快速判断表
+
+| 问题 | Sequential | Autonomous |
+|------|------------|------------|
+| 输出结构是否固定？ | ✓ | ✗ |
+| 是否需要用户多轮交互？ | ✗ | ✓ |
+| 阶段是否可以跳过/重复？ | ✗ | ✓ |
+| 是否有复杂分支逻辑？ | ✗ | ✓ |
+| 调试是否需要简单？ | ✓ | ✗ |
+
+---
+
+## 混合模式
+
+某些复杂 Skill 可能需要混合使用两种模式：
+
+```
+phases/
+├── 01-init.md                 # Sequential: 初始化
+├── 02-orchestrator.md         # Autonomous: 核心交互循环
+│   └── actions/
+│       ├── action-a.md
+│       └── action-b.md
+└── 03-finalize.md             # Sequential: 收尾
+```
+
+**适用场景**:
+- 初始化和收尾固定，中间交互灵活
+- 多阶段任务，某阶段需要动态决策

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

@@ -0,0 +1,265 @@
+# Scripting Integration Spec
+
+技能脚本集成规范，定义如何在技能中使用外部脚本执行确定性任务。
+
+## 核心原则
+
+1. **约定优于配置**：命名即 ID，扩展名即运行时
+2. **极简调用**：一行完成脚本调用
+3. **标准输入输出**：命令行参数输入，JSON 标准输出
+
+## 目录结构
+
+```
+.claude/skills/<skill-name>/
+├── scripts/                    # 脚本专用目录
+│   ├── process-data.py         # id: process-data
+│   ├── validate-output.sh      # id: validate-output
+│   └── transform-json.js       # id: transform-json
+├── phases/
+└── specs/
+```
+
+## 命名约定
+
+| 扩展名 | 运行时 | 执行命令 |
+|--------|--------|----------|
+| `.py` | python | `python scripts/{id}.py` |
+| `.sh` | bash | `bash scripts/{id}.sh` |
+| `.js` | node | `node scripts/{id}.js` |
+
+## 声明格式
+
+在 Phase 或 Action 文件的 `## Scripts` 部分声明：
+
+```yaml
+## Scripts
+
+- process-data
+- validate-output
+```
+
+## 调用语法
+
+### 基础调用
+
+```javascript
+const result = await ExecuteScript('script-id', { key: value });
+```
+
+### 参数命名转换
+
+调用时 JS 对象中的键会**自动转换**为 `kebab-case` 命令行参数：
+
+| JS 键名 | 转换后参数 |
+|---------|-----------|
+| `input_path` | `--input-path` |
+| `output_dir` | `--output-dir` |
+| `max_count` | `--max-count` |
+
+脚本中使用 `--input-path` 接收，调用时使用 `input_path` 传入。
+
+### 完整调用（含错误处理）
+
+```javascript
+const result = await ExecuteScript('process-data', {
+  input_path: `${workDir}/data.json`,
+  threshold: 0.9
+});
+
+if (!result.success) {
+  throw new Error(`脚本执行失败: ${result.stderr}`);
+}
+
+const { output_file, count } = result.outputs;
+```
+
+## 返回格式
+
+```typescript
+interface ScriptResult {
+  success: boolean;    // exit code === 0
+  stdout: string;      // 完整标准输出
+  stderr: string;      // 完整标准错误
+  outputs: {           // 从 stdout 最后一行解析的 JSON
+    [key: string]: any;
+  };
+}
+```
+
+## 脚本编写规范
+
+### 输入：命令行参数
+
+```bash
+# Python: argparse
+--input-path /path/to/file --threshold 0.9
+
+# Bash: 手动解析
+--input-path /path/to/file
+```
+
+### 输出：标准输出 JSON
+
+脚本最后一行必须打印单行 JSON：
+
+```json
+{"output_file": "/tmp/result.json", "count": 42}
+```
+
+### Python 模板
+
+```python
+import argparse
+import json
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument('--input-path', required=True)
+    parser.add_argument('--threshold', type=float, default=0.9)
+    args = parser.parse_args()
+
+    # 执行逻辑...
+    result_path = "/tmp/result.json"
+
+    # 输出 JSON
+    print(json.dumps({
+        "output_file": result_path,
+        "items_processed": 100
+    }))
+
+if __name__ == '__main__':
+    main()
+```
+
+### Bash 模板
+
+```bash
+#!/bin/bash
+
+# 解析参数
+while [[ "$#" -gt 0 ]]; do
+    case $1 in
+        --input-path) INPUT_PATH="$2"; shift ;;
+        *) echo "Unknown: $1" >&2; exit 1 ;;
+    esac
+    shift
+done
+
+# 执行逻辑...
+LOG_FILE="/tmp/process.log"
+echo "Processing $INPUT_PATH" > "$LOG_FILE"
+
+# 输出 JSON
+echo "{\"log_file\": \"$LOG_FILE\", \"status\": \"done\"}"
+```
+
+## ExecuteScript 实现
+
+```javascript
+async function ExecuteScript(scriptId, inputs = {}) {
+  const skillDir = GetSkillDir();
+
+  // 查找脚本文件
+  const extensions = ['.py', '.sh', '.js'];
+  let scriptPath, runtime;
+
+  for (const ext of extensions) {
+    const path = `${skillDir}/scripts/${scriptId}${ext}`;
+    if (FileExists(path)) {
+      scriptPath = path;
+      runtime = ext === '.py' ? 'python' : ext === '.sh' ? 'bash' : 'node';
+      break;
+    }
+  }
+
+  if (!scriptPath) {
+    throw new Error(`Script not found: ${scriptId}`);
+  }
+
+  // 构建命令行参数
+  const args = Object.entries(inputs)
+    .map(([k, v]) => `--${k.replace(/_/g, '-')} "${v}"`)
+    .join(' ');
+
+  // 执行脚本
+  const cmd = `${runtime} "${scriptPath}" ${args}`;
+  const { stdout, stderr, exitCode } = await Bash(cmd);
+
+  // 解析输出
+  let outputs = {};
+  try {
+    const lastLine = stdout.trim().split('\n').pop();
+    outputs = JSON.parse(lastLine);
+  } catch (e) {
+    // 无法解析 JSON，保持空对象
+  }
+
+  return {
+    success: exitCode === 0,
+    stdout,
+    stderr,
+    outputs
+  };
+}
+```
+
+## 使用场景
+
+### 适合脚本化的任务
+
+- 数据处理和转换
+- 文件格式转换
+- 批量文件操作
+- 复杂计算逻辑
+- 调用外部工具/库
+
+### 不适合脚本化的任务
+
+- 需要用户交互的任务
+- 需要访问 Claude 工具的任务
+- 简单的文件读写
+- 需要动态决策的任务
+
+## 路径约定
+
+### 脚本路径
+
+脚本路径相对于 `SKILL.md` 所在目录（技能根目录）：
+
+```
+.claude/skills/<skill-name>/    # 技能根目录（SKILL.md 所在位置）
+├── SKILL.md
+├── scripts/                     # 脚本目录
+│   └── process-data.py          # 相对路径: scripts/process-data.py
+└── phases/
+```
+
+`ExecuteScript` 自动从技能根目录查找脚本：
+```javascript
+// 实际执行: python .claude/skills/<skill-name>/scripts/process-data.py
+await ExecuteScript('process-data', { ... });
+```
+
+### 输出目录
+
+**推荐**：由调用方传递输出目录，而非脚本默认 `/tmp`：
+
+```javascript
+// 调用时指定输出目录（在工作流工作目录内）
+const result = await ExecuteScript('process-data', {
+  input_path: `${workDir}/data.json`,
+  output_dir: `${workDir}/output`    // 明确指定输出位置
+});
+```
+
+脚本应接受 `--output-dir` 参数，而非硬编码输出路径。
+
+## 最佳实践
+
+1. **单一职责**：每个脚本只做一件事
+2. **无副作用**：脚本不应修改全局状态
+3. **幂等性**：相同输入产生相同输出
+4. **错误明确**：错误信息写入 stderr，正常输出写入 stdout
+5. **快速失败**：参数验证失败立即退出
+6. **路径参数化**：输出路径由调用方指定，不硬编码