mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-13 02:41:50 +08:00
Add CLI endpoints documentation and unified script template for Bash and Python
- Updated AGENTS.md to include CLI tools usage and configuration details. - Introduced a new script template for both Bash and Python, outlining usage context, calling conventions, and implementation guidelines. - Provided examples for common patterns in both Bash and Python scripts. - Established a directory convention for script organization and naming.
This commit is contained in:
catlog22
368
.claude/skills/skill-generator/templates/script-template.md
Normal file
368
.claude/skills/skill-generator/templates/script-template.md
Normal file
@@ -0,0 +1,368 @@
|
||||
# Script Template
|
||||
|
||||
统一的脚本模板，覆盖 Bash 和 Python 两种运行时。
|
||||
|
||||
## Usage Context
|
||||
|
||||
| Phase | Usage |
|
||||
|-------|-------|
|
||||
| Optional | Phase/Action 中声明 `## Scripts` 时使用 |
|
||||
| Execution | 通过 `ExecuteScript('script-id', params)` 调用 |
|
||||
| Output Location | `.claude/skills/{skill-name}/scripts/{script-id}.{ext}` |
|
||||
|
||||
---
|
||||
|
||||
## 调用接口规范
|
||||
|
||||
所有脚本共享相同的调用约定：
|
||||
|
||||
```
|
||||
调用者
|
||||
↓ ExecuteScript('script-id', { key: value })
|
||||
↓
|
||||
脚本入口
|
||||
├─ 参数解析 (--key value)
|
||||
├─ 输入验证 (必需参数检查, 文件存在)
|
||||
├─ 核心处理 (数据读取 → 转换 → 写入)
|
||||
└─ 输出结果 (最后一行: 单行 JSON → stdout)
|
||||
├─ 成功: {"status":"success", "output_file":"...", ...}
|
||||
└─ 失败: stderr 输出错误信息, exit 1
|
||||
```
|
||||
|
||||
### 返回格式
|
||||
|
||||
```typescript
|
||||
interface ScriptResult {
|
||||
success: boolean; // exit code === 0
|
||||
stdout: string; // 标准输出
|
||||
stderr: string; // 标准错误
|
||||
outputs: object; // 从 stdout 最后一行解析的 JSON
|
||||
}
|
||||
```
|
||||
|
||||
### 参数约定
|
||||
|
||||
| 参数 | 必需 | 说明 |
|
||||
|------|------|------|
|
||||
| `--input-path` | ✓ | 输入文件路径 |
|
||||
| `--output-dir` | ✓ | 输出目录（由调用方指定） |
|
||||
| 其他 | 按需 | 脚本特定参数 |
|
||||
|
||||
---
|
||||
|
||||
## Bash 实现
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# {{script_description}}
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
# ============================================================
|
||||
# 参数解析
|
||||
# ============================================================
|
||||
|
||||
INPUT_PATH=""
|
||||
OUTPUT_DIR=""
|
||||
|
||||
while [[ "$#" -gt 0 ]]; do
|
||||
case $1 in
|
||||
--input-path) INPUT_PATH="$2"; shift ;;
|
||||
--output-dir) OUTPUT_DIR="$2"; shift ;;
|
||||
--help)
|
||||
echo "用法: $0 --input-path <path> --output-dir <dir>"
|
||||
exit 0
|
||||
;;
|
||||
*)
|
||||
echo "错误: 未知参数 $1" >&2
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
shift
|
||||
done
|
||||
|
||||
# ============================================================
|
||||
# 参数验证
|
||||
# ============================================================
|
||||
|
||||
[[ -z "$INPUT_PATH" ]] && { echo "错误: --input-path 是必需参数" >&2; exit 1; }
|
||||
[[ -z "$OUTPUT_DIR" ]] && { echo "错误: --output-dir 是必需参数" >&2; exit 1; }
|
||||
[[ ! -f "$INPUT_PATH" ]] && { echo "错误: 输入文件不存在: $INPUT_PATH" >&2; exit 1; }
|
||||
command -v jq &> /dev/null || { echo "错误: 需要安装 jq" >&2; exit 1; }
|
||||
|
||||
mkdir -p "$OUTPUT_DIR"
|
||||
|
||||
# ============================================================
|
||||
# 核心逻辑
|
||||
# ============================================================
|
||||
|
||||
OUTPUT_FILE="$OUTPUT_DIR/result.txt"
|
||||
ITEMS_COUNT=0
|
||||
|
||||
# TODO: 实现处理逻辑
|
||||
while IFS= read -r line; do
|
||||
echo "$line" >> "$OUTPUT_FILE"
|
||||
((ITEMS_COUNT++))
|
||||
done < "$INPUT_PATH"
|
||||
|
||||
# ============================================================
|
||||
# 输出 JSON 结果（使用 jq 构建，避免转义问题）
|
||||
# ============================================================
|
||||
|
||||
jq -n \
|
||||
--arg output_file "$OUTPUT_FILE" \
|
||||
--argjson items_processed "$ITEMS_COUNT" \
|
||||
'{output_file: $output_file, items_processed: $items_processed, status: "success"}'
|
||||
```
|
||||
|
||||
### Bash 常用模式
|
||||
|
||||
```bash
|
||||
# 文件遍历
|
||||
for file in "$INPUT_DIR"/*.json; do
|
||||
[[ -f "$file" ]] || continue
|
||||
# 处理逻辑...
|
||||
done
|
||||
|
||||
# 临时文件 (自动清理)
|
||||
TEMP_FILE=$(mktemp)
|
||||
trap "rm -f $TEMP_FILE" EXIT
|
||||
|
||||
# 工具依赖检查
|
||||
require_command() {
|
||||
command -v "$1" &> /dev/null || { echo "错误: 需要 $1" >&2; exit 1; }
|
||||
}
|
||||
require_command jq
|
||||
|
||||
# jq 处理
|
||||
VALUE=$(jq -r '.field' "$INPUT_PATH") # 读取字段
|
||||
jq '.field = "new"' input.json > output.json # 修改字段
|
||||
jq -s 'add' file1.json file2.json > merged.json # 合并文件
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Python 实现
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
{{script_description}}
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(description='{{script_description}}')
|
||||
parser.add_argument('--input-path', type=str, required=True, help='输入文件路径')
|
||||
parser.add_argument('--output-dir', type=str, required=True, help='输出目录')
|
||||
args = parser.parse_args()
|
||||
|
||||
# 验证输入
|
||||
input_path = Path(args.input_path)
|
||||
if not input_path.exists():
|
||||
print(f"错误: 输入文件不存在: {input_path}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
output_dir = Path(args.output_dir)
|
||||
output_dir.mkdir(parents=True, exist_ok=True)
|
||||
|
||||
# 执行处理
|
||||
try:
|
||||
result = process(input_path, output_dir)
|
||||
except Exception as e:
|
||||
print(f"错误: {e}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
# 输出 JSON 结果
|
||||
print(json.dumps(result))
|
||||
|
||||
|
||||
def process(input_path: Path, output_dir: Path) -> dict:
|
||||
"""核心处理逻辑"""
|
||||
# TODO: 实现处理逻辑
|
||||
|
||||
output_file = output_dir / 'result.json'
|
||||
|
||||
with open(input_path, 'r', encoding='utf-8') as f:
|
||||
data = json.load(f)
|
||||
|
||||
processed_count = len(data) if isinstance(data, list) else 1
|
||||
|
||||
with open(output_file, 'w', encoding='utf-8') as f:
|
||||
json.dump(data, f, indent=2, ensure_ascii=False)
|
||||
|
||||
return {
|
||||
'output_file': str(output_file),
|
||||
'items_processed': processed_count,
|
||||
'status': 'success'
|
||||
}
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
```
|
||||
|
||||
### Python 常用模式
|
||||
|
||||
```python
|
||||
# 文件遍历
|
||||
def process_files(input_dir: Path, pattern: str = '*.json') -> list:
|
||||
return [
|
||||
{'file': str(f), 'data': json.load(f.open())}
|
||||
for f in input_dir.glob(pattern)
|
||||
]
|
||||
|
||||
# 数据转换
|
||||
def transform(data: dict) -> dict:
|
||||
return {
|
||||
'id': data.get('id'),
|
||||
'name': data.get('name', '').strip(),
|
||||
'timestamp': datetime.now().isoformat()
|
||||
}
|
||||
|
||||
# 外部命令调用
|
||||
import subprocess
|
||||
|
||||
def run_command(cmd: list) -> str:
|
||||
result = subprocess.run(cmd, capture_output=True, text=True)
|
||||
if result.returncode != 0:
|
||||
raise RuntimeError(result.stderr)
|
||||
return result.stdout
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 运行时选择指南
|
||||
|
||||
```
|
||||
任务特征
|
||||
↓
|
||||
├─ 文件处理 / 系统命令 / 管道操作
|
||||
│ └─ 选 Bash (.sh)
|
||||
│
|
||||
├─ JSON 数据处理 / 复杂转换 / 数据分析
|
||||
│ └─ 选 Python (.py)
|
||||
│
|
||||
└─ 简单读写 / 格式转换
|
||||
└─ 任选（Bash 更轻量）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 生成函数
|
||||
|
||||
```javascript
|
||||
function generateScript(scriptConfig) {
|
||||
const runtime = scriptConfig.runtime || 'bash'; // 'bash' | 'python'
|
||||
const ext = runtime === 'python' ? '.py' : '.sh';
|
||||
|
||||
if (runtime === 'python') {
|
||||
return generatePythonScript(scriptConfig);
|
||||
}
|
||||
return generateBashScript(scriptConfig);
|
||||
}
|
||||
|
||||
function generateBashScript(scriptConfig) {
|
||||
const { description, inputs = [], outputs = [] } = scriptConfig;
|
||||
|
||||
const paramDefs = inputs.map(i =>
|
||||
`${i.name.toUpperCase().replace(/-/g, '_')}="${i.default || ''}"`
|
||||
).join('\n');
|
||||
|
||||
const paramParse = inputs.map(i =>
|
||||
` --${i.name}) ${i.name.toUpperCase().replace(/-/g, '_')}="$2"; shift ;;`
|
||||
).join('\n');
|
||||
|
||||
const paramValidation = inputs.filter(i => i.required).map(i => {
|
||||
const VAR = i.name.toUpperCase().replace(/-/g, '_');
|
||||
return `[[ -z "$${VAR}" ]] && { echo "错误: --${i.name} 是必需参数" >&2; exit 1; }`;
|
||||
}).join('\n');
|
||||
|
||||
return `#!/bin/bash
|
||||
# ${description}
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
${paramDefs}
|
||||
|
||||
while [[ "$#" -gt 0 ]]; do
|
||||
case $1 in
|
||||
${paramParse}
|
||||
*) echo "未知参数: $1" >&2; exit 1 ;;
|
||||
esac
|
||||
shift
|
||||
done
|
||||
|
||||
${paramValidation}
|
||||
|
||||
# TODO: 实现处理逻辑
|
||||
|
||||
# 输出结果 (jq 构建)
|
||||
jq -n ${outputs.map(o =>
|
||||
`--arg ${o.name} "$${o.name.toUpperCase().replace(/-/g, '_')}"`
|
||||
).join(' \\\n ')} \
|
||||
'{${outputs.map(o => `${o.name}: $${o.name}`).join(', ')}}'
|
||||
`;
|
||||
}
|
||||
|
||||
function generatePythonScript(scriptConfig) {
|
||||
const { description, inputs = [], outputs = [] } = scriptConfig;
|
||||
|
||||
const argDefs = inputs.map(i =>
|
||||
` parser.add_argument('--${i.name}', type=${i.type || 'str'}, ${
|
||||
i.required ? 'required=True' : `default='${i.default || ''}'`
|
||||
}, help='${i.description || i.name}')`
|
||||
).join('\n');
|
||||
|
||||
const resultFields = outputs.map(o =>
|
||||
` '${o.name}': None # ${o.description || o.name}`
|
||||
).join(',\n');
|
||||
|
||||
return `#!/usr/bin/env python3
|
||||
"""
|
||||
${description}
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(description='${description}')
|
||||
${argDefs}
|
||||
args = parser.parse_args()
|
||||
|
||||
# TODO: 实现处理逻辑
|
||||
result = {
|
||||
${resultFields}
|
||||
}
|
||||
|
||||
print(json.dumps(result))
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
`;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 目录约定
|
||||
|
||||
```
|
||||
scripts/
|
||||
├── process-data.py # id: process-data, runtime: python
|
||||
├── validate.sh # id: validate, runtime: bash
|
||||
└── transform.js # id: transform, runtime: node
|
||||
```
|
||||
|
||||
- **命名即 ID**: 文件名（不含扩展名）= 脚本 ID
|
||||
- **扩展名即运行时**: `.py` → python, `.sh` → bash, `.js` → node
|
||||
Reference in New Issue
Block a user