claude-code-workflow 6.3.50 → 6.3.51

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

@@ -1,265 +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. **路径参数化**：输出路径由调用方指定，不硬编码
+# Scripting Integration Specification
+
+Skill scripting integration specification that defines how to use external scripts for deterministic task execution.
+
+## Core Principles
+
+1. **Convention over configuration**: Naming is ID, file extension is runtime
+2. **Minimal invocation**: Complete script call in one line
+3. **Standard input/output**: Command-line parameters as input, JSON as standard output
+
+## Directory Structure
+
+```
+.claude/skills/<skill-name>/
+├── scripts/                    # Scripts directory
+│   ├── process-data.py         # id: process-data
+│   ├── validate-output.sh      # id: validate-output
+│   └── transform-json.js       # id: transform-json
+├── phases/
+└── specs/
+```
+
+## Naming Conventions
+
+| Extension | Runtime | Execution Command |
+|-----------|---------|-------------------|
+| `.py` | python | `python scripts/{id}.py` |
+| `.sh` | bash | `bash scripts/{id}.sh` |
+| `.js` | node | `node scripts/{id}.js` |
+
+## Declaration Format
+
+Declare in the `## Scripts` section of Phase or Action files:
+
+```yaml
+## Scripts
+
+- process-data
+- validate-output
+```
+
+## Invocation Syntax
+
+### Basic Call
+
+```javascript
+const result = await ExecuteScript('script-id', { key: value });
+```
+
+### Parameter Name Conversion
+
+Keys in the JS object are **automatically converted** to `kebab-case` command-line parameters:
+
+| JS Key Name | Converted Parameter |
+|-------------|-------------------|
+| `input_path` | `--input-path` |
+| `output_dir` | `--output-dir` |
+| `max_count` | `--max-count` |
+
+Use `--input-path` in scripts, pass `input_path` when calling.
+
+### Complete Call (with Error Handling)
+
+```javascript
+const result = await ExecuteScript('process-data', {
+  input_path: `${workDir}/data.json`,
+  threshold: 0.9
+});
+
+if (!result.success) {
+  throw new Error(`Script execution failed: ${result.stderr}`);
+}
+
+const { output_file, count } = result.outputs;
+```
+
+## Return Format
+
+```typescript
+interface ScriptResult {
+  success: boolean;    // exit code === 0
+  stdout: string;      // Complete standard output
+  stderr: string;      // Complete standard error
+  outputs: {           // JSON parsed from last line of stdout
+    [key: string]: any;
+  };
+}
+```
+
+## Script Writing Specification
+
+### Input: Command-line Parameters
+
+```bash
+# Python: argparse
+--input-path /path/to/file --threshold 0.9
+
+# Bash: manual parsing
+--input-path /path/to/file
+```
+
+### Output: Standard Output JSON
+
+Script must print single-line JSON on last line:
+
+```json
+{"output_file": "/tmp/result.json", "count": 42}
+```
+
+### Python Template
+
+```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()
+
+    # Execution logic...
+    result_path = "/tmp/result.json"
+
+    # Output JSON
+    print(json.dumps({
+        "output_file": result_path,
+        "items_processed": 100
+    }))
+
+if __name__ == '__main__':
+    main()
+```
+
+### Bash Template
+
+```bash
+#!/bin/bash
+
+# Parse parameters
+while [[ "$#" -gt 0 ]]; do
+    case $1 in
+        --input-path) INPUT_PATH="$2"; shift ;;
+        *) echo "Unknown: $1" >&2; exit 1 ;;
+    esac
+    shift
+done
+
+# Execution logic...
+LOG_FILE="/tmp/process.log"
+echo "Processing $INPUT_PATH" > "$LOG_FILE"
+
+# Output JSON
+echo "{\"log_file\": \"$LOG_FILE\", \"status\": \"done\"}"
+```
+
+## ExecuteScript Implementation
+
+```javascript
+async function ExecuteScript(scriptId, inputs = {}) {
+  const skillDir = GetSkillDir();
+
+  // Find script file
+  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}`);
+  }
+
+  // Build command-line parameters
+  const args = Object.entries(inputs)
+    .map(([k, v]) => `--${k.replace(/_/g, '-')} "${v}"`)
+    .join(' ');
+
+  // Execute script
+  const cmd = `${runtime} "${scriptPath}" ${args}`;
+  const { stdout, stderr, exitCode } = await Bash(cmd);
+
+  // Parse output
+  let outputs = {};
+  try {
+    const lastLine = stdout.trim().split('\n').pop();
+    outputs = JSON.parse(lastLine);
+  } catch (e) {
+    // Unable to parse JSON, keep empty object
+  }
+
+  return {
+    success: exitCode === 0,
+    stdout,
+    stderr,
+    outputs
+  };
+}
+```
+
+## Use Cases
+
+### Suitable for Scripting
+
+- Data processing and transformation
+- File format conversion
+- Batch file operations
+- Complex calculation logic
+- Call external tools/libraries
+
+### Not Suitable for Scripting
+
+- Tasks requiring user interaction
+- Tasks needing access to Claude tools
+- Simple file read/write
+- Tasks requiring dynamic decision-making
+
+## Path Conventions
+
+### Script Path
+
+Script paths are relative to the directory containing `SKILL.md` (skill root directory):
+
+```
+.claude/skills/<skill-name>/    # Skill root directory (SKILL.md location)
+├── SKILL.md
+├── scripts/                     # Scripts directory
+│   └── process-data.py          # Relative path: scripts/process-data.py
+└── phases/
+```
+
+`ExecuteScript` automatically finds scripts from skill root directory:
+```javascript
+// Actually executes: python .claude/skills/<skill-name>/scripts/process-data.py
+await ExecuteScript('process-data', { ... });
+```
+
+### Output Directory
+
+**Recommended**: Pass output directory from caller, not hardcode in script to `/tmp`:
+
+```javascript
+// Specify output directory when calling (in workflow working directory)
+const result = await ExecuteScript('process-data', {
+  input_path: `${workDir}/data.json`,
+  output_dir: `${workDir}/output`    // Explicitly specify output location
+});
+```
+
+Scripts should accept `--output-dir` parameter instead of hardcoding output paths.
+
+## Best Practices
+
+1. **Single Responsibility**: Each script does one thing
+2. **No Side Effects**: Scripts should not modify global state
+3. **Idempotence**: Same input produces same output
+4. **Clear Errors**: Error messages to stderr, normal output to stdout
+5. **Fail Fast**: Exit immediately on parameter validation failure
+6. **Parameterized Paths**: Output paths specified by caller, not hardcoded