mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-12 02:37:45 +08:00
feat: Add code analysis and LLM action templates with detailed configurations and examples
- Introduced a comprehensive code analysis action template for integrating code exploration and analysis capabilities. - Added LLM action template for seamless integration of LLM calls with customizable prompts and tools. - Implemented a benchmark search script to compare multiple search methods across various dimensions including speed, result quality, ranking stability, and coverage. - Provided preset configurations for common analysis tasks and LLM actions, enhancing usability and flexibility.
This commit is contained in:
catlog22
@@ -1,17 +1,42 @@
|
||||
# Phase 3: Phase Generation
|
||||
|
||||
根据执行模式生成 Phase 文件。
|
||||
根据执行模式生成 Phase 文件，包含声明式工作流编排和上下文策略支持。
|
||||
|
||||
## Objective
|
||||
|
||||
- Sequential 模式：生成顺序 Phase 文件 (`01-xx.md`, `02-xx.md`, ...)
|
||||
- Sequential 模式：生成顺序 Phase 文件 + **声明式编排器**
|
||||
- Autonomous 模式：生成编排器和动作文件
|
||||
- 支持 **文件上下文** 和 **内存上下文** 两种策略
|
||||
|
||||
## Input
|
||||
|
||||
- 依赖: `skill-config.json`, SKILL.md (Phase 1-2 产出)
|
||||
- 模板: `templates/sequential-phase.md`, `templates/autonomous-*.md`
|
||||
|
||||
## 上下文策略 (P0 增强)
|
||||
|
||||
根据 `config.context_strategy` 生成不同的上下文管理代码：
|
||||
|
||||
| 策略 | 适用场景 | 优点 | 缺点 |
|
||||
|------|----------|------|------|
|
||||
| `file` | 复杂多阶段任务 | 持久化、可调试、可恢复 | IO 开销 |
|
||||
| `memory` | 简单线性任务 | 速度快 | 无法恢复、调试困难 |
|
||||
|
||||
```javascript
|
||||
const CONTEXT_STRATEGIES = {
|
||||
file: {
|
||||
read: (key) => `JSON.parse(Read(\`\${workDir}/context/${key}.json\`))`,
|
||||
write: (key, data) => `Write(\`\${workDir}/context/${key}.json\`, JSON.stringify(${data}, null, 2))`,
|
||||
init: `Bash(\`mkdir -p "\${workDir}/context"\`)`
|
||||
},
|
||||
memory: {
|
||||
read: (key) => `state.context.${key}`,
|
||||
write: (key, data) => `state.context.${key} = ${data}`,
|
||||
init: `state.context = {}`
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1: 读取配置和模板
|
||||
@@ -19,19 +44,27 @@
|
||||
```javascript
|
||||
const config = JSON.parse(Read(`${workDir}/skill-config.json`));
|
||||
const skillDir = `.claude/skills/${config.skill_name}`;
|
||||
const contextStrategy = config.context_strategy || 'file'; // 默认文件策略
|
||||
|
||||
// 读取模板
|
||||
const sequentialTemplate = Read(`${skillRoot}/templates/sequential-phase.md`);
|
||||
const orchestratorTemplate = Read(`${skillRoot}/templates/autonomous-orchestrator.md`);
|
||||
const actionTemplate = Read(`${skillRoot}/templates/autonomous-action.md`);
|
||||
const skillRoot = '.claude/skills/skill-generator';
|
||||
```
|
||||
|
||||
### Step 2: Sequential 模式 - 生成阶段文件
|
||||
### Step 2: Sequential 模式 - 生成阶段文件 + 声明式编排器
|
||||
|
||||
```javascript
|
||||
if (config.execution_mode === 'sequential') {
|
||||
const phases = config.sequential_config.phases;
|
||||
|
||||
// ========== P0 增强: 生成声明式编排器 ==========
|
||||
const workflowOrchestrator = generateSequentialOrchestrator(config, phases);
|
||||
Write(`${skillDir}/phases/_orchestrator.md`, workflowOrchestrator);
|
||||
|
||||
// ========== P0 增强: 生成工作流定义 ==========
|
||||
const workflowDef = generateWorkflowDefinition(config, phases);
|
||||
Write(`${skillDir}/workflow.json`, JSON.stringify(workflowDef, null, 2));
|
||||
|
||||
// 生成各阶段文件
|
||||
for (let i = 0; i < phases.length; i++) {
|
||||
const phase = phases[i];
|
||||
const prevPhase = i > 0 ? phases[i-1] : null;
|
||||
@@ -45,14 +78,204 @@ if (config.execution_mode === 'sequential') {
|
||||
input: prevPhase ? prevPhase.output : "user input",
|
||||
output: phase.output,
|
||||
nextPhase: nextPhase ? nextPhase.id : null,
|
||||
config: config
|
||||
config: config,
|
||||
contextStrategy: contextStrategy
|
||||
});
|
||||
|
||||
Write(`${skillDir}/phases/${phase.id}.md`, content);
|
||||
}
|
||||
}
|
||||
|
||||
// ========== P0 增强: 声明式工作流定义 ==========
|
||||
function generateWorkflowDefinition(config, phases) {
|
||||
return {
|
||||
skill_name: config.skill_name,
|
||||
version: "1.0.0",
|
||||
execution_mode: "sequential",
|
||||
context_strategy: config.context_strategy || "file",
|
||||
|
||||
// 声明式阶段列表 (类似 software-manual 的 agents_to_run)
|
||||
phases_to_run: phases.map(p => p.id),
|
||||
|
||||
// 阶段配置
|
||||
phases: phases.map((p, i) => ({
|
||||
id: p.id,
|
||||
name: p.name,
|
||||
order: i + 1,
|
||||
input: i > 0 ? phases[i-1].output : null,
|
||||
output: p.output,
|
||||
// 可选的并行配置
|
||||
parallel: p.parallel || false,
|
||||
// 可选的条件执行
|
||||
condition: p.condition || null,
|
||||
// Agent 配置
|
||||
agent: p.agent || {
|
||||
type: "universal-executor",
|
||||
run_in_background: false
|
||||
}
|
||||
})),
|
||||
|
||||
// 终止条件
|
||||
termination: {
|
||||
on_success: "all_phases_completed",
|
||||
on_error: "stop_and_report",
|
||||
max_retries: 3
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
// ========== P0 增强: 声明式编排器 ==========
|
||||
function generateSequentialOrchestrator(config, phases) {
|
||||
return `# Sequential Orchestrator
|
||||
|
||||
声明式工作流编排器，按 \`workflow.json\` 定义顺序执行阶段。
|
||||
|
||||
## 工作流定义
|
||||
|
||||
\`\`\`javascript
|
||||
const workflow = JSON.parse(Read(\`\${skillDir}/workflow.json\`));
|
||||
\`\`\`
|
||||
|
||||
## 编排逻辑
|
||||
|
||||
\`\`\`javascript
|
||||
async function runSequentialWorkflow(workDir) {
|
||||
const workflow = JSON.parse(Read(\`\${skillDir}/workflow.json\`));
|
||||
const contextStrategy = workflow.context_strategy;
|
||||
|
||||
// 初始化上下文
|
||||
${config.context_strategy === 'file' ?
|
||||
`Bash(\`mkdir -p "\${workDir}/context"\`);` :
|
||||
`const state = { context: {} };`}
|
||||
|
||||
// 执行状态追踪
|
||||
const execution = {
|
||||
started_at: new Date().toISOString(),
|
||||
phases_completed: [],
|
||||
current_phase: null,
|
||||
errors: []
|
||||
};
|
||||
|
||||
Write(\`\${workDir}/execution-state.json\`, JSON.stringify(execution, null, 2));
|
||||
|
||||
// 按声明顺序执行阶段
|
||||
for (const phaseId of workflow.phases_to_run) {
|
||||
const phaseConfig = workflow.phases.find(p => p.id === phaseId);
|
||||
|
||||
// 更新执行状态
|
||||
execution.current_phase = phaseId;
|
||||
Write(\`\${workDir}/execution-state.json\`, JSON.stringify(execution, null, 2));
|
||||
|
||||
console.log(\`[Orchestrator] Executing: \${phaseId}\`);
|
||||
|
||||
try {
|
||||
// 检查条件执行
|
||||
if (phaseConfig.condition) {
|
||||
const shouldRun = evaluateCondition(phaseConfig.condition, execution);
|
||||
if (!shouldRun) {
|
||||
console.log(\`[Orchestrator] Skipping \${phaseId} (condition not met)\`);
|
||||
continue;
|
||||
}
|
||||
}
|
||||
|
||||
// 执行阶段
|
||||
const result = await executePhase(phaseId, phaseConfig, workDir);
|
||||
|
||||
// 记录完成
|
||||
execution.phases_completed.push({
|
||||
id: phaseId,
|
||||
completed_at: new Date().toISOString(),
|
||||
output: phaseConfig.output
|
||||
});
|
||||
|
||||
} catch (error) {
|
||||
execution.errors.push({
|
||||
phase: phaseId,
|
||||
message: error.message,
|
||||
timestamp: new Date().toISOString()
|
||||
});
|
||||
|
||||
// 错误处理策略
|
||||
if (workflow.termination.on_error === 'stop_and_report') {
|
||||
console.error(\`[Orchestrator] Failed at \${phaseId}: \${error.message}\`);
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
Write(\`\${workDir}/execution-state.json\`, JSON.stringify(execution, null, 2));
|
||||
}
|
||||
|
||||
// 完成
|
||||
execution.current_phase = null;
|
||||
execution.completed_at = new Date().toISOString();
|
||||
Write(\`\${workDir}/execution-state.json\`, JSON.stringify(execution, null, 2));
|
||||
|
||||
return execution;
|
||||
}
|
||||
|
||||
async function executePhase(phaseId, phaseConfig, workDir) {
|
||||
const phasePrompt = Read(\`\${skillDir}/phases/\${phaseId}.md\`);
|
||||
|
||||
// 使用 Task 调用 Agent
|
||||
const result = await Task({
|
||||
subagent_type: phaseConfig.agent?.type || 'universal-executor',
|
||||
run_in_background: phaseConfig.agent?.run_in_background || false,
|
||||
prompt: \`
|
||||
[PHASE] \${phaseId}
|
||||
[WORK_DIR] \${workDir}
|
||||
[INPUT] \${phaseConfig.input ? \`\${workDir}/\${phaseConfig.input}\` : 'None'}
|
||||
[OUTPUT] \${workDir}/\${phaseConfig.output}
|
||||
|
||||
\${phasePrompt}
|
||||
\`
|
||||
});
|
||||
|
||||
return JSON.parse(result);
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
## 阶段执行计划
|
||||
|
||||
| Order | Phase | Input | Output | Agent |
|
||||
|-------|-------|-------|--------|-------|
|
||||
${phases.map((p, i) =>
|
||||
`| ${i+1} | ${p.id} | ${i > 0 ? phases[i-1].output : '-'} | ${p.output} | ${p.agent?.type || 'universal-executor'} |`
|
||||
).join('\n')}
|
||||
|
||||
## 错误恢复
|
||||
|
||||
\`\`\`javascript
|
||||
// 从指定阶段恢复执行
|
||||
async function resumeFromPhase(phaseId, workDir) {
|
||||
const workflow = JSON.parse(Read(\`\${skillDir}/workflow.json\`));
|
||||
const startIndex = workflow.phases_to_run.indexOf(phaseId);
|
||||
|
||||
if (startIndex === -1) {
|
||||
throw new Error(\`Phase not found: \${phaseId}\`);
|
||||
}
|
||||
|
||||
// 从指定阶段开始执行
|
||||
const remainingPhases = workflow.phases_to_run.slice(startIndex);
|
||||
// ...继续执行
|
||||
}
|
||||
\`\`\`
|
||||
`;
|
||||
}
|
||||
|
||||
// 生成阶段文件（增强上下文策略支持）
|
||||
function generateSequentialPhase(params) {
|
||||
const contextCode = params.contextStrategy === 'file' ? {
|
||||
readPrev: `const prevOutput = JSON.parse(Read(\`\${workDir}/${params.input}\`));`,
|
||||
writeResult: `Write(\`\${workDir}/${params.output}\`, JSON.stringify(result, null, 2));`,
|
||||
readContext: (key) => `JSON.parse(Read(\`\${workDir}/context/${key}.json\`))`,
|
||||
writeContext: (key) => `Write(\`\${workDir}/context/${key}.json\`, JSON.stringify(data, null, 2))`
|
||||
} : {
|
||||
readPrev: `const prevOutput = state.context.prevPhaseOutput;`,
|
||||
writeResult: `state.context.${params.phaseId.replace(/-/g, '_')}_output = result;`,
|
||||
readContext: (key) => `state.context.${key}`,
|
||||
writeContext: (key) => `state.context.${key} = data`
|
||||
};
|
||||
|
||||
return `# Phase ${params.phaseNumber}: ${params.phaseName}
|
||||
|
||||
${params.phaseDescription}
|
||||
@@ -66,16 +289,15 @@ ${params.phaseDescription}
|
||||
|
||||
- 依赖: \`${params.input}\`
|
||||
- 配置: \`{workDir}/skill-config.json\`
|
||||
- 上下文策略: \`${params.contextStrategy}\`
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1: 准备工作
|
||||
### Step 1: 读取输入
|
||||
|
||||
\`\`\`javascript
|
||||
// 读取上一阶段产出
|
||||
${params.phaseNumber > 1 ?
|
||||
`const prevOutput = JSON.parse(Read(\`\${workDir}/${params.input}\`));` :
|
||||
`// 首阶段，直接从配置开始`}
|
||||
// 上下文策略: ${params.contextStrategy}
|
||||
${params.phaseNumber > 1 ? contextCode.readPrev : '// 首阶段，直接从配置开始'}
|
||||
\`\`\`
|
||||
|
||||
### Step 2: 核心处理
|
||||
@@ -83,26 +305,43 @@ ${params.phaseNumber > 1 ?
|
||||
\`\`\`javascript
|
||||
// TODO: 实现核心逻辑
|
||||
const result = {
|
||||
// 处理结果
|
||||
status: 'completed',
|
||||
data: {
|
||||
// 处理结果
|
||||
},
|
||||
metadata: {
|
||||
phase: '${params.phaseId}',
|
||||
timestamp: new Date().toISOString()
|
||||
}
|
||||
};
|
||||
\`\`\`
|
||||
|
||||
### Step 3: 输出结果
|
||||
|
||||
\`\`\`javascript
|
||||
Write(\`\${workDir}/${params.output}\`, JSON.stringify(result, null, 2));
|
||||
// 写入阶段产出 (上下文策略: ${params.contextStrategy})
|
||||
${contextCode.writeResult}
|
||||
|
||||
// 返回简要信息给编排器
|
||||
return {
|
||||
status: 'completed',
|
||||
output_file: '${params.output}',
|
||||
summary: '阶段 ${params.phaseNumber} 完成'
|
||||
};
|
||||
\`\`\`
|
||||
|
||||
## Output
|
||||
|
||||
- **File**: \`${params.output}\`
|
||||
- **Format**: ${params.output.endsWith('.json') ? 'JSON' : 'Markdown'}
|
||||
- **Context Strategy**: ${params.contextStrategy}
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
- [ ] 输入数据验证通过
|
||||
- [ ] 核心逻辑执行成功
|
||||
- [ ] 输出格式正确
|
||||
- [ ] 上下文正确保存
|
||||
|
||||
${params.nextPhase ?
|
||||
`## Next Phase\n\n→ [Phase ${params.phaseNumber + 1}: ${params.nextPhase}](${params.nextPhase}.md)` :
|
||||
@@ -111,186 +350,271 @@ ${params.nextPhase ?
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: Autonomous 模式 - 生成编排器
|
||||
### Step 3: Autonomous 模式 - 生成编排器 (增强版)
|
||||
|
||||
```javascript
|
||||
if (config.execution_mode === 'autonomous' || config.execution_mode === 'hybrid') {
|
||||
const contextStrategy = config.context_strategy || 'file';
|
||||
|
||||
// 生成状态 Schema
|
||||
const stateSchema = generateStateSchema(config);
|
||||
// 生成状态 Schema (增强文件策略支持)
|
||||
const stateSchema = generateStateSchema(config, contextStrategy);
|
||||
Write(`${skillDir}/phases/state-schema.md`, stateSchema);
|
||||
|
||||
// 生成编排器
|
||||
const orchestrator = generateOrchestrator(config);
|
||||
// 生成编排器 (增强版)
|
||||
const orchestrator = generateEnhancedOrchestrator(config, contextStrategy);
|
||||
Write(`${skillDir}/phases/orchestrator.md`, orchestrator);
|
||||
|
||||
// 生成动作目录
|
||||
const actionCatalog = generateActionCatalog(config);
|
||||
Write(`${skillDir}/specs/action-catalog.md`, actionCatalog);
|
||||
|
||||
// 生成动作文件
|
||||
for (const action of config.autonomous_config.actions) {
|
||||
const actionContent = generateAction(action, config);
|
||||
const actionContent = generateEnhancedAction(action, config, contextStrategy);
|
||||
Write(`${skillDir}/phases/actions/${action.id}.md`, actionContent);
|
||||
}
|
||||
}
|
||||
|
||||
function generateStateSchema(config) {
|
||||
return `# State Schema
|
||||
|
||||
## 状态文件
|
||||
|
||||
位置: \`{workDir}/state.json\`
|
||||
|
||||
## 结构定义
|
||||
|
||||
\`\`\`typescript
|
||||
interface ${toPascalCase(config.skill_name)}State {
|
||||
// 元信息
|
||||
skill_name: "${config.skill_name}";
|
||||
started_at: string;
|
||||
updated_at: string;
|
||||
|
||||
// 执行状态
|
||||
status: 'pending' | 'running' | 'completed' | 'failed';
|
||||
current_action: string | null;
|
||||
completed_actions: string[];
|
||||
|
||||
// 业务数据
|
||||
${config.autonomous_config.state_schema?.fields?.map(f =>
|
||||
` ${f.name}: ${f.type}; // ${f.description}`
|
||||
).join('\n') || ' context: Record<string, any>;'}
|
||||
|
||||
// 错误追踪
|
||||
errors: Array<{
|
||||
action: string;
|
||||
message: string;
|
||||
timestamp: string;
|
||||
}>;
|
||||
error_count: number;
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
## 初始状态
|
||||
|
||||
\`\`\`json
|
||||
{
|
||||
"skill_name": "${config.skill_name}",
|
||||
"started_at": "",
|
||||
"updated_at": "",
|
||||
"status": "pending",
|
||||
"current_action": null,
|
||||
"completed_actions": [],
|
||||
${config.autonomous_config.state_schema?.fields?.map(f =>
|
||||
` "${f.name}": ${getDefaultValue(f.type)}`
|
||||
).join(',\n') || ' "context": {}'}
|
||||
"errors": [],
|
||||
"error_count": 0
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
## 状态转换规则
|
||||
|
||||
| 当前状态 | 触发条件 | 目标状态 |
|
||||
|----------|----------|----------|
|
||||
| pending | 首次执行 | running |
|
||||
| running | 动作完成 | running |
|
||||
| running | 所有任务完成 | completed |
|
||||
| running | 错误超限 | failed |
|
||||
`;
|
||||
}
|
||||
|
||||
function generateOrchestrator(config) {
|
||||
// 增强版编排器生成
|
||||
function generateEnhancedOrchestrator(config, contextStrategy) {
|
||||
const actions = config.autonomous_config.actions;
|
||||
|
||||
return `# Orchestrator
|
||||
return `# Orchestrator (Enhanced)
|
||||
|
||||
## Role
|
||||
增强版编排器，支持声明式动作调度和文件上下文策略。
|
||||
|
||||
根据当前状态选择并执行下一个动作。
|
||||
## 配置
|
||||
|
||||
## State Reading
|
||||
- **上下文策略**: ${contextStrategy}
|
||||
- **终止条件**: ${config.autonomous_config.termination_conditions?.join(', ') || 'task_completed'}
|
||||
|
||||
## 声明式动作目录
|
||||
|
||||
\`\`\`javascript
|
||||
const state = JSON.parse(Read(\`\${workDir}/state.json\`));
|
||||
const ACTION_CATALOG = ${JSON.stringify(actions.map(a => ({
|
||||
id: a.id,
|
||||
name: a.name,
|
||||
preconditions: a.preconditions || [],
|
||||
effects: a.effects || [],
|
||||
priority: a.priority || 0
|
||||
})), null, 2)};
|
||||
\`\`\`
|
||||
|
||||
## Decision Logic
|
||||
## 上下文管理 (${contextStrategy} 策略)
|
||||
|
||||
\`\`\`javascript
|
||||
const ContextManager = {
|
||||
${contextStrategy === 'file' ? `
|
||||
// 文件策略: 持久化到 .scratchpad
|
||||
init: (workDir) => {
|
||||
Bash(\`mkdir -p "\${workDir}/context"\`);
|
||||
Write(\`\${workDir}/state.json\`, JSON.stringify(initialState, null, 2));
|
||||
},
|
||||
|
||||
readState: (workDir) => JSON.parse(Read(\`\${workDir}/state.json\`)),
|
||||
|
||||
writeState: (workDir, state) => {
|
||||
state.updated_at = new Date().toISOString();
|
||||
Write(\`\${workDir}/state.json\`, JSON.stringify(state, null, 2));
|
||||
},
|
||||
|
||||
readContext: (workDir, key) => {
|
||||
try {
|
||||
return JSON.parse(Read(\`\${workDir}/context/\${key}.json\`));
|
||||
} catch { return null; }
|
||||
},
|
||||
|
||||
writeContext: (workDir, key, data) => {
|
||||
Write(\`\${workDir}/context/\${key}.json\`, JSON.stringify(data, null, 2));
|
||||
}` : `
|
||||
// 内存策略: 仅在运行时保持
|
||||
state: null,
|
||||
context: {},
|
||||
|
||||
init: (workDir) => {
|
||||
ContextManager.state = { ...initialState };
|
||||
ContextManager.context = {};
|
||||
},
|
||||
|
||||
readState: () => ContextManager.state,
|
||||
|
||||
writeState: (workDir, state) => {
|
||||
state.updated_at = new Date().toISOString();
|
||||
ContextManager.state = state;
|
||||
},
|
||||
|
||||
readContext: (workDir, key) => ContextManager.context[key],
|
||||
|
||||
writeContext: (workDir, key, data) => {
|
||||
ContextManager.context[key] = data;
|
||||
}`}
|
||||
};
|
||||
\`\`\`
|
||||
|
||||
## 决策逻辑
|
||||
|
||||
\`\`\`javascript
|
||||
function selectNextAction(state) {
|
||||
// 1. 检查终止条件
|
||||
// 1. 终止条件检查
|
||||
${config.autonomous_config.termination_conditions?.map(c =>
|
||||
` if (${getTerminationCheck(c)}) return null;`
|
||||
).join('\n') || ' if (state.status === "completed") return null;'}
|
||||
|
||||
// 2. 错误检查
|
||||
// 2. 错误限制检查
|
||||
if (state.error_count >= 3) return 'action-abort';
|
||||
|
||||
// 3. 根据状态选择动作
|
||||
${actions.map(a =>
|
||||
` if (${getPreconditionCheck(a)}) return '${a.id}';`
|
||||
).join('\n')}
|
||||
// 3. 按优先级选择满足前置条件的动作
|
||||
const availableActions = ACTION_CATALOG
|
||||
.filter(a => checkPreconditions(a.preconditions, state))
|
||||
.filter(a => !state.completed_actions.includes(a.id))
|
||||
.sort((a, b) => b.priority - a.priority);
|
||||
|
||||
// 4. 默认: 完成
|
||||
if (availableActions.length > 0) {
|
||||
return availableActions[0].id;
|
||||
}
|
||||
|
||||
// 4. 默认完成
|
||||
return 'action-complete';
|
||||
}
|
||||
|
||||
function checkPreconditions(conditions, state) {
|
||||
if (!conditions || conditions.length === 0) return true;
|
||||
return conditions.every(cond => {
|
||||
// 支持多种条件格式
|
||||
if (cond.includes('===')) {
|
||||
const [left, right] = cond.split('===').map(s => s.trim());
|
||||
return eval(\`state.\${left}\`) === eval(right);
|
||||
}
|
||||
return state[cond] === true;
|
||||
});
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
## Execution Loop
|
||||
## 执行循环 (增强版)
|
||||
|
||||
\`\`\`javascript
|
||||
async function runOrchestrator() {
|
||||
while (true) {
|
||||
// 读取状态
|
||||
const state = JSON.parse(Read(\`\${workDir}/state.json\`));
|
||||
async function runOrchestrator(workDir) {
|
||||
console.log('=== Orchestrator Started ===');
|
||||
console.log(\`Context Strategy: ${contextStrategy}\`);
|
||||
|
||||
// 初始化
|
||||
ContextManager.init(workDir);
|
||||
|
||||
let iteration = 0;
|
||||
const MAX_ITERATIONS = 100;
|
||||
|
||||
while (iteration < MAX_ITERATIONS) {
|
||||
iteration++;
|
||||
|
||||
// 选择动作
|
||||
// 1. 读取状态
|
||||
const state = ContextManager.readState(workDir);
|
||||
console.log(\`[Iteration \${iteration}] Status: \${state.status}, Completed: \${state.completed_actions.length}\`);
|
||||
|
||||
// 2. 选择动作
|
||||
const actionId = selectNextAction(state);
|
||||
|
||||
if (!actionId) {
|
||||
console.log("任务完成或终止");
|
||||
console.log('=== All actions completed ===');
|
||||
state.status = 'completed';
|
||||
ContextManager.writeState(workDir, state);
|
||||
break;
|
||||
}
|
||||
|
||||
// 更新当前动作
|
||||
state.current_action = actionId;
|
||||
state.updated_at = new Date().toISOString();
|
||||
Write(\`\${workDir}/state.json\`, JSON.stringify(state, null, 2));
|
||||
console.log(\`[Iteration \${iteration}] Executing: \${actionId}\`);
|
||||
|
||||
// 执行动作
|
||||
// 3. 更新当前动作
|
||||
state.current_action = actionId;
|
||||
ContextManager.writeState(workDir, state);
|
||||
|
||||
// 4. 执行动作
|
||||
try {
|
||||
const result = await executeAction(actionId, state);
|
||||
const actionPrompt = Read(\`\${skillDir}/phases/actions/\${actionId}.md\`);
|
||||
|
||||
// 更新状态
|
||||
const result = await Task({
|
||||
subagent_type: 'universal-executor',
|
||||
run_in_background: false,
|
||||
prompt: \`
|
||||
[STATE]
|
||||
\${JSON.stringify(state, null, 2)}
|
||||
|
||||
[WORK_DIR]
|
||||
\${workDir}
|
||||
|
||||
[CONTEXT_STRATEGY]
|
||||
${contextStrategy}
|
||||
|
||||
[ACTION]
|
||||
\${actionPrompt}
|
||||
|
||||
[RETURN FORMAT]
|
||||
Return JSON: { "status": "completed"|"failed", "stateUpdates": {...}, "summary": "..." }
|
||||
\`
|
||||
});
|
||||
|
||||
const actionResult = JSON.parse(result);
|
||||
|
||||
// 5. 更新状态
|
||||
state.completed_actions.push(actionId);
|
||||
state.current_action = null;
|
||||
Object.assign(state, result.stateUpdates);
|
||||
Object.assign(state, actionResult.stateUpdates || {});
|
||||
|
||||
console.log(\`[Iteration \${iteration}] Completed: \${actionResult.summary || actionId}\`);
|
||||
|
||||
} catch (error) {
|
||||
console.error(\`[Iteration \${iteration}] Error: \${error.message}\`);
|
||||
state.errors.push({
|
||||
action: actionId,
|
||||
message: error.message,
|
||||
timestamp: new Date().toISOString()
|
||||
});
|
||||
state.error_count++;
|
||||
state.current_action = null;
|
||||
}
|
||||
|
||||
Write(\`\${workDir}/state.json\`, JSON.stringify(state, null, 2));
|
||||
ContextManager.writeState(workDir, state);
|
||||
}
|
||||
|
||||
console.log('=== Orchestrator Finished ===');
|
||||
return ContextManager.readState(workDir);
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
## Action Catalog
|
||||
## 动作目录
|
||||
|
||||
| Action | Purpose | Preconditions |
|
||||
|--------|---------|---------------|
|
||||
| Action | Priority | Preconditions | Effects |
|
||||
|--------|----------|---------------|---------|
|
||||
${actions.map(a =>
|
||||
`| [${a.id}](actions/${a.id}.md) | ${a.description || a.name} | ${a.preconditions?.join(', ') || '-'} |`
|
||||
`| [${a.id}](actions/${a.id}.md) | ${a.priority || 0} | ${a.preconditions?.join(', ') || '-'} | ${a.effects?.join(', ') || '-'} |`
|
||||
).join('\n')}
|
||||
|
||||
## Termination Conditions
|
||||
## 调试与恢复
|
||||
|
||||
${config.autonomous_config.termination_conditions?.map(c => `- ${c}`).join('\n') || '- status === "completed"'}
|
||||
\`\`\`javascript
|
||||
// 从特定状态恢复
|
||||
async function resumeFromState(workDir) {
|
||||
const state = ContextManager.readState(workDir);
|
||||
console.log(\`Resuming from: \${state.current_action || 'start'}\`);
|
||||
console.log(\`Completed actions: \${state.completed_actions.join(', ')}\`);
|
||||
return runOrchestrator(workDir);
|
||||
}
|
||||
|
||||
// 重试失败的动作
|
||||
async function retryFailedAction(workDir) {
|
||||
const state = ContextManager.readState(workDir);
|
||||
if (state.errors.length > 0) {
|
||||
const lastError = state.errors[state.errors.length - 1];
|
||||
console.log(\`Retrying: \${lastError.action}\`);
|
||||
state.error_count = Math.max(0, state.error_count - 1);
|
||||
ContextManager.writeState(workDir, state);
|
||||
return runOrchestrator(workDir);
|
||||
}
|
||||
}
|
||||
\`\`\`
|
||||
`;
|
||||
}
|
||||
|
||||
function generateAction(action, config) {
|
||||
// 增强版动作生成
|
||||
function generateEnhancedAction(action, config, contextStrategy) {
|
||||
return `# Action: ${action.name}
|
||||
|
||||
${action.description || '执行 ' + action.name + ' 操作'}
|
||||
@@ -301,23 +625,50 @@ ${action.description || 'TODO: 描述此动作的目的'}
|
||||
|
||||
## Preconditions
|
||||
|
||||
${action.preconditions?.map(p => `- [ ] ${p}`).join('\n') || '- [ ] 无特殊前置条件'}
|
||||
${action.preconditions?.map(p => `- [ ] \`${p}\``).join('\n') || '- [ ] 无特殊前置条件'}
|
||||
|
||||
## Context Access (${contextStrategy} 策略)
|
||||
|
||||
\`\`\`javascript
|
||||
// 读取共享上下文
|
||||
${contextStrategy === 'file' ?
|
||||
`const sharedData = JSON.parse(Read(\`\${workDir}/context/shared.json\`));` :
|
||||
`const sharedData = state.context.shared || {};`}
|
||||
|
||||
// 写入共享上下文
|
||||
${contextStrategy === 'file' ?
|
||||
`Write(\`\${workDir}/context/shared.json\`, JSON.stringify(updatedData, null, 2));` :
|
||||
`state.context.shared = updatedData;`}
|
||||
\`\`\`
|
||||
|
||||
## Execution
|
||||
|
||||
\`\`\`javascript
|
||||
async function execute(state) {
|
||||
// TODO: 实现动作逻辑
|
||||
|
||||
async function execute(state, workDir) {
|
||||
// 1. 读取必要数据
|
||||
${contextStrategy === 'file' ?
|
||||
`const input = JSON.parse(Read(\`\${workDir}/context/input.json\`));` :
|
||||
`const input = state.context.input || {};`}
|
||||
|
||||
// 2. 执行核心逻辑
|
||||
// TODO: 实现动作逻辑
|
||||
const result = {
|
||||
// 处理结果
|
||||
};
|
||||
|
||||
// 3. 返回状态更新
|
||||
// 3. 保存结果 (${contextStrategy} 策略)
|
||||
${contextStrategy === 'file' ?
|
||||
`Write(\`\${workDir}/context/${action.id.replace(/-/g, '_')}_result.json\`, JSON.stringify(result, null, 2));` :
|
||||
`// 结果通过 stateUpdates 返回`}
|
||||
|
||||
// 4. 返回状态更新
|
||||
return {
|
||||
status: 'completed',
|
||||
stateUpdates: {
|
||||
// 更新的状态字段
|
||||
}
|
||||
completed_actions: [...state.completed_actions, '${action.id}'],
|
||||
${contextStrategy === 'memory' ? `context: { ...state.context, ${action.id.replace(/-/g, '_')}_result: result }` : '// 文件策略：结果已保存到文件'}
|
||||
},
|
||||
summary: '${action.name} 完成'
|
||||
};
|
||||
}
|
||||
\`\`\`
|
||||
@@ -326,9 +677,11 @@ async function execute(state) {
|
||||
|
||||
\`\`\`javascript
|
||||
return {
|
||||
completed_actions: [...state.completed_actions, '${action.id}'],
|
||||
// 其他状态更新
|
||||
${action.effects?.map(e => ` // Effect: ${e}`).join('\n') || ''}
|
||||
status: 'completed',
|
||||
stateUpdates: {
|
||||
completed_actions: [...state.completed_actions, '${action.id}'],
|
||||
${action.effects?.map(e => ` // Effect: ${e}`).join('\n') || ' // 无额外效果'}
|
||||
}
|
||||
};
|
||||
\`\`\`
|
||||
|
||||
@@ -338,11 +691,62 @@ ${action.effects?.map(e => ` // Effect: ${e}`).join('\n') || ''}
|
||||
|----------|----------|
|
||||
| 数据验证失败 | 返回错误，不更新状态 |
|
||||
| 执行异常 | 记录错误，增加 error_count |
|
||||
| 上下文读取失败 | 使用默认值或跳过 |
|
||||
|
||||
## Next Actions (Hints)
|
||||
|
||||
- 成功时: 由编排器根据状态决定
|
||||
- 失败时: 重试或 \`action-abort\`
|
||||
- 成功: 由编排器根据 \`ACTION_CATALOG\` 优先级决定
|
||||
- 失败: 重试或 \`action-abort\`
|
||||
`;
|
||||
}
|
||||
|
||||
// 生成动作目录
|
||||
function generateActionCatalog(config) {
|
||||
const actions = config.autonomous_config.actions;
|
||||
|
||||
return `# Action Catalog
|
||||
|
||||
${config.display_name} 的可用动作目录（声明式）。
|
||||
|
||||
## 动作定义
|
||||
|
||||
\`\`\`json
|
||||
${JSON.stringify(actions.map(a => ({
|
||||
id: a.id,
|
||||
name: a.name,
|
||||
description: a.description,
|
||||
preconditions: a.preconditions || [],
|
||||
effects: a.effects || [],
|
||||
priority: a.priority || 0
|
||||
})), null, 2)}
|
||||
\`\`\`
|
||||
|
||||
## 动作依赖图
|
||||
|
||||
\`\`\`mermaid
|
||||
graph TD
|
||||
${actions.map((a, i) => {
|
||||
const deps = a.preconditions?.filter(p => p.startsWith('completed_actions.includes'))
|
||||
.map(p => p.match(/'([^']+)'/)?.[1])
|
||||
.filter(Boolean) || [];
|
||||
|
||||
if (deps.length === 0 && i === 0) {
|
||||
return ` START((Start)) --> ${a.id.replace(/-/g, '_')}[${a.name}]`;
|
||||
} else if (deps.length > 0) {
|
||||
return deps.map(d => ` ${d.replace(/-/g, '_')} --> ${a.id.replace(/-/g, '_')}[${a.name}]`).join('\n');
|
||||
}
|
||||
return '';
|
||||
}).filter(Boolean).join('\n')}
|
||||
${actions[actions.length-1]?.id.replace(/-/g, '_') || 'last'} --> END((End))
|
||||
\`\`\`
|
||||
|
||||
## 选择优先级
|
||||
|
||||
| Priority | Action | Description |
|
||||
|----------|--------|-------------|
|
||||
${actions.sort((a, b) => (b.priority || 0) - (a.priority || 0)).map(a =>
|
||||
`| ${a.priority || 0} | ${a.id} | ${a.description || a.name} |`
|
||||
).join('\n')}
|
||||
`;
|
||||
}
|
||||
```
|
||||
@@ -366,7 +770,8 @@ function getTerminationCheck(condition) {
|
||||
const checks = {
|
||||
'user_exit': 'state.status === "user_exit"',
|
||||
'error_limit': 'state.error_count >= 3',
|
||||
'task_completed': 'state.status === "completed"'
|
||||
'task_completed': 'state.status === "completed"',
|
||||
'max_iterations': 'iteration >= MAX_ITERATIONS'
|
||||
};
|
||||
return checks[condition] || `state.${condition}`;
|
||||
}
|
||||
@@ -381,14 +786,15 @@ function getPreconditionCheck(action) {
|
||||
|
||||
### Sequential 模式
|
||||
|
||||
- `phases/01-{step}.md`
|
||||
- `phases/02-{step}.md`
|
||||
- ...
|
||||
- `phases/_orchestrator.md` (声明式编排器)
|
||||
- `workflow.json` (工作流定义)
|
||||
- `phases/01-{step}.md`, `02-{step}.md`, ...
|
||||
|
||||
### Autonomous 模式
|
||||
|
||||
- `phases/orchestrator.md`
|
||||
- `phases/orchestrator.md` (增强版编排器)
|
||||
- `phases/state-schema.md`
|
||||
- `specs/action-catalog.md` (声明式动作目录)
|
||||
- `phases/actions/action-{name}.md` (多个)
|
||||
|
||||
## Next Phase
|
||||
|
||||
448
.claude/skills/skill-generator/specs/cli-integration.md
Normal file
448
.claude/skills/skill-generator/specs/cli-integration.md
Normal file
@@ -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 格式便于后续处理
|
||||
@@ -19,10 +19,32 @@
|
||||
|
||||
| 字段 | 类型 | 必需 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `execution_mode` | enum | ✓ | `sequential` \| `autonomous` |
|
||||
| `execution_mode` | enum | ✓ | `sequential` \| `autonomous` \| `hybrid` |
|
||||
| `phase_count` | number | 条件 | Sequential 模式下的阶段数 |
|
||||
| `action_count` | number | 条件 | Autonomous 模式下的动作数 |
|
||||
|
||||
### 2.5 上下文策略 (P0 增强)
|
||||
|
||||
| 字段 | 类型 | 必需 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `context_strategy` | enum | ✓ | `file` \| `memory` |
|
||||
|
||||
**策略对比**:
|
||||
|
||||
| 策略 | 持久化 | 可调试 | 可恢复 | 适用场景 |
|
||||
|------|--------|--------|--------|----------|
|
||||
| `file` | ✓ | ✓ | ✓ | 复杂多阶段任务（推荐） |
|
||||
| `memory` | ✗ | ✗ | ✗ | 简单线性任务 |
|
||||
|
||||
### 2.6 LLM 集成配置 (P1 增强)
|
||||
|
||||
| 字段 | 类型 | 必需 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `llm_integration` | object | 可选 | LLM 调用配置 |
|
||||
| `llm_integration.enabled` | boolean | - | 是否启用 LLM 调用 |
|
||||
| `llm_integration.default_tool` | enum | - | `gemini` \| `qwen` \| `codex` |
|
||||
| `llm_integration.fallback_chain` | string[] | - | 失败时的备选工具链 |
|
||||
|
||||
### 3. 工具依赖
|
||||
|
||||
| 字段 | 类型 | 必需 | 说明 |
|
||||
@@ -50,8 +72,19 @@ interface SkillConfig {
|
||||
triggers: string[]; // ["keyword1", "keyword2"]
|
||||
|
||||
// 执行模式
|
||||
execution_mode: 'sequential' | 'autonomous';
|
||||
|
||||
execution_mode: 'sequential' | 'autonomous' | 'hybrid';
|
||||
|
||||
// 上下文策略 (P0 增强)
|
||||
context_strategy: 'file' | 'memory'; // 默认: 'file'
|
||||
|
||||
// LLM 集成配置 (P1 增强)
|
||||
llm_integration?: {
|
||||
enabled: boolean; // 是否启用 LLM 调用
|
||||
default_tool: 'gemini' | 'qwen' | 'codex';
|
||||
fallback_chain: string[]; // ['gemini', 'qwen', 'codex']
|
||||
mode: 'analysis' | 'write'; // 默认 mode
|
||||
};
|
||||
|
||||
// Sequential 模式配置
|
||||
sequential_config?: {
|
||||
phases: Array<{
|
||||
@@ -211,7 +244,73 @@ AskUserQuestion({
|
||||
});
|
||||
```
|
||||
|
||||
### Phase 4: 工具依赖
|
||||
### Phase 4: 上下文策略 (P0 增强)
|
||||
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [
|
||||
{
|
||||
question: "选择上下文管理策略：",
|
||||
header: "上下文策略",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{
|
||||
label: "文件策略 (file)",
|
||||
description: "持久化到 .scratchpad，支持调试和恢复（推荐）"
|
||||
},
|
||||
{
|
||||
label: "内存策略 (memory)",
|
||||
description: "仅在运行时保持，速度快但无法恢复"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
});
|
||||
```
|
||||
|
||||
### Phase 5: LLM 集成 (P1 增强)
|
||||
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [
|
||||
{
|
||||
question: "是否需要 LLM 调用能力？",
|
||||
header: "LLM 集成",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{
|
||||
label: "启用 LLM 调用",
|
||||
description: "使用 gemini/qwen/codex 进行分析或生成"
|
||||
},
|
||||
{
|
||||
label: "不需要",
|
||||
description: "仅使用本地工具"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
});
|
||||
|
||||
// 如果启用 LLM
|
||||
if (llmEnabled) {
|
||||
AskUserQuestion({
|
||||
questions: [
|
||||
{
|
||||
question: "选择默认 LLM 工具：",
|
||||
header: "LLM 工具",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Gemini", description: "大上下文，适合分析任务（推荐）" },
|
||||
{ label: "Qwen", description: "代码生成能力强" },
|
||||
{ label: "Codex", description: "自主执行能力强，适合实现任务" }
|
||||
]
|
||||
}
|
||||
]
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 6: 工具依赖
|
||||
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
@@ -224,7 +323,8 @@ AskUserQuestion({
|
||||
{ label: "基础工具", description: "Task, Read, Write, Glob, Grep, Bash" },
|
||||
{ label: "用户交互", description: "AskUserQuestion" },
|
||||
{ label: "Chrome 截图", description: "mcp__chrome__*" },
|
||||
{ label: "外部搜索", description: "mcp__exa__search" }
|
||||
{ label: "外部搜索", description: "mcp__exa__search" },
|
||||
{ label: "CCW CLI 调用", description: "ccw cli (gemini/qwen/codex)" }
|
||||
]
|
||||
}
|
||||
]
|
||||
@@ -285,7 +385,7 @@ function validateSkillConfig(config) {
|
||||
|
||||
## 示例配置
|
||||
|
||||
### Sequential 模式示例
|
||||
### Sequential 模式示例 (增强版)
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -294,11 +394,33 @@ function validateSkillConfig(config) {
|
||||
"description": "Generate API documentation from source code",
|
||||
"triggers": ["generate api docs", "api documentation"],
|
||||
"execution_mode": "sequential",
|
||||
"context_strategy": "file",
|
||||
"llm_integration": {
|
||||
"enabled": true,
|
||||
"default_tool": "gemini",
|
||||
"fallback_chain": ["gemini", "qwen"],
|
||||
"mode": "analysis"
|
||||
},
|
||||
"sequential_config": {
|
||||
"phases": [
|
||||
{ "id": "01-scan", "name": "Code Scanning", "output": "endpoints.json" },
|
||||
{ "id": "02-parse", "name": "Schema Parsing", "output": "schemas.json" },
|
||||
{ "id": "03-generate", "name": "Doc Generation", "output": "api-docs.md" }
|
||||
{
|
||||
"id": "01-scan",
|
||||
"name": "Code Scanning",
|
||||
"output": "endpoints.json",
|
||||
"agent": { "type": "universal-executor", "run_in_background": false }
|
||||
},
|
||||
{
|
||||
"id": "02-analyze",
|
||||
"name": "LLM Analysis",
|
||||
"output": "analysis.json",
|
||||
"agent": { "type": "llm", "tool": "gemini", "mode": "analysis" }
|
||||
},
|
||||
{
|
||||
"id": "03-generate",
|
||||
"name": "Doc Generation",
|
||||
"output": "api-docs.md",
|
||||
"agent": { "type": "universal-executor", "run_in_background": false }
|
||||
}
|
||||
]
|
||||
},
|
||||
"allowed_tools": ["Task", "Read", "Write", "Glob", "Grep", "Bash"],
|
||||
|
||||
503
.claude/skills/skill-generator/templates/code-analysis-action.md
Normal file
503
.claude/skills/skill-generator/templates/code-analysis-action.md
Normal file
@@ -0,0 +1,503 @@
|
||||
# Code Analysis Action Template
|
||||
|
||||
代码分析动作模板，用于在 Skill 中集成代码探索和分析能力。
|
||||
|
||||
---
|
||||
|
||||
## 配置结构
|
||||
|
||||
```typescript
|
||||
interface CodeAnalysisActionConfig {
|
||||
id: string; // "analyze-structure", "explore-patterns"
|
||||
name: string; // "Code Structure Analysis"
|
||||
type: 'code-analysis'; // 动作类型标识
|
||||
|
||||
// 分析范围
|
||||
scope: {
|
||||
paths: string[]; // 目标路径
|
||||
patterns: string[]; // Glob 模式
|
||||
excludes?: string[]; // 排除模式
|
||||
};
|
||||
|
||||
// 分析类型
|
||||
analysis_type: 'structure' | 'patterns' | 'dependencies' | 'quality' | 'security';
|
||||
|
||||
// Agent 配置
|
||||
agent: {
|
||||
type: 'Explore' | 'cli-explore-agent' | 'universal-executor';
|
||||
thoroughness: 'quick' | 'medium' | 'very thorough';
|
||||
};
|
||||
|
||||
// 输出配置
|
||||
output: {
|
||||
format: 'json' | 'markdown';
|
||||
file: string;
|
||||
};
|
||||
|
||||
// MCP 工具增强
|
||||
mcp_tools?: string[]; // ['mcp__ace-tool__search_context']
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 模板生成函数
|
||||
|
||||
```javascript
|
||||
function generateCodeAnalysisAction(config) {
|
||||
const { id, name, scope, analysis_type, agent, output, mcp_tools = [] } = config;
|
||||
|
||||
return `
|
||||
# ${name}
|
||||
|
||||
## Action: ${id}
|
||||
|
||||
### 分析范围
|
||||
|
||||
- **路径**: ${scope.paths.join(', ')}
|
||||
- **模式**: ${scope.patterns.join(', ')}
|
||||
${scope.excludes ? `- **排除**: ${scope.excludes.join(', ')}` : ''}
|
||||
|
||||
### 执行逻辑
|
||||
|
||||
\`\`\`javascript
|
||||
async function execute${toPascalCase(id)}(context) {
|
||||
const workDir = context.workDir;
|
||||
const results = [];
|
||||
|
||||
// 1. 文件发现
|
||||
const files = await discoverFiles({
|
||||
paths: ${JSON.stringify(scope.paths)},
|
||||
patterns: ${JSON.stringify(scope.patterns)},
|
||||
excludes: ${JSON.stringify(scope.excludes || [])}
|
||||
});
|
||||
|
||||
console.log(\`Found \${files.length} files to analyze\`);
|
||||
|
||||
// 2. 使用 MCP 工具进行语义搜索（如果配置）
|
||||
${mcp_tools.length > 0 ? `
|
||||
const semanticResults = await mcp__ace_tool__search_context({
|
||||
project_root_path: context.projectRoot,
|
||||
query: '${getQueryForAnalysisType(analysis_type)}'
|
||||
});
|
||||
results.push({ type: 'semantic', data: semanticResults });
|
||||
` : '// No MCP tools configured'}
|
||||
|
||||
// 3. 启动 Agent 进行深度分析
|
||||
const agentResult = await Task({
|
||||
subagent_type: '${agent.type}',
|
||||
prompt: \`
|
||||
${generateAgentPrompt(analysis_type, scope)}
|
||||
\`,
|
||||
run_in_background: false
|
||||
});
|
||||
|
||||
results.push({ type: 'agent', data: agentResult });
|
||||
|
||||
// 4. 汇总结果
|
||||
const summary = aggregateResults(results);
|
||||
|
||||
// 5. 输出结果
|
||||
const outputPath = \`\${workDir}/${output.file}\`;
|
||||
${output.format === 'json'
|
||||
? `Write(outputPath, JSON.stringify(summary, null, 2));`
|
||||
: `Write(outputPath, formatAsMarkdown(summary));`}
|
||||
|
||||
return {
|
||||
success: true,
|
||||
output: '${output.file}',
|
||||
files_analyzed: files.length,
|
||||
analysis_type: '${analysis_type}'
|
||||
};
|
||||
}
|
||||
\`\`\`
|
||||
`;
|
||||
}
|
||||
|
||||
function getQueryForAnalysisType(type) {
|
||||
const queries = {
|
||||
structure: 'main entry points, module organization, exports',
|
||||
patterns: 'design patterns, abstractions, reusable components',
|
||||
dependencies: 'imports, external dependencies, coupling',
|
||||
quality: 'code complexity, test coverage, documentation',
|
||||
security: 'authentication, authorization, input validation, secrets'
|
||||
};
|
||||
return queries[type] || queries.structure;
|
||||
}
|
||||
|
||||
function generateAgentPrompt(type, scope) {
|
||||
const prompts = {
|
||||
structure: `分析以下路径的代码结构:
|
||||
${scope.paths.map(p => `- ${p}`).join('\\n')}
|
||||
|
||||
任务:
|
||||
1. 识别主要模块和入口点
|
||||
2. 分析目录组织结构
|
||||
3. 提取模块间的导入导出关系
|
||||
4. 生成结构概览图 (Mermaid)
|
||||
|
||||
输出格式: JSON
|
||||
{
|
||||
"modules": [...],
|
||||
"entry_points": [...],
|
||||
"structure_diagram": "mermaid code"
|
||||
}`,
|
||||
|
||||
patterns: `分析以下路径的设计模式:
|
||||
${scope.paths.map(p => `- ${p}`).join('\\n')}
|
||||
|
||||
任务:
|
||||
1. 识别使用的设计模式 (Factory, Strategy, Observer 等)
|
||||
2. 分析抽象层级
|
||||
3. 评估模式使用的恰当性
|
||||
4. 提取可复用的模式实例
|
||||
|
||||
输出格式: JSON
|
||||
{
|
||||
"patterns": [{ "name": "...", "location": "...", "usage": "..." }],
|
||||
"abstractions": [...],
|
||||
"reusable_components": [...]
|
||||
}`,
|
||||
|
||||
dependencies: `分析以下路径的依赖关系:
|
||||
${scope.paths.map(p => `- ${p}`).join('\\n')}
|
||||
|
||||
任务:
|
||||
1. 提取内部模块依赖
|
||||
2. 识别外部包依赖
|
||||
3. 分析耦合度
|
||||
4. 检测循环依赖
|
||||
|
||||
输出格式: JSON
|
||||
{
|
||||
"internal_deps": [...],
|
||||
"external_deps": [...],
|
||||
"coupling_score": 0-100,
|
||||
"circular_deps": [...]
|
||||
}`,
|
||||
|
||||
quality: `分析以下路径的代码质量:
|
||||
${scope.paths.map(p => `- ${p}`).join('\\n')}
|
||||
|
||||
任务:
|
||||
1. 评估代码复杂度
|
||||
2. 检查测试覆盖率
|
||||
3. 分析文档完整性
|
||||
4. 识别技术债务
|
||||
|
||||
输出格式: JSON
|
||||
{
|
||||
"complexity": { "avg": 0, "max": 0, "hotspots": [...] },
|
||||
"test_coverage": { "percentage": 0, "gaps": [...] },
|
||||
"documentation": { "score": 0, "missing": [...] },
|
||||
"tech_debt": [...]
|
||||
}`,
|
||||
|
||||
security: `分析以下路径的安全性:
|
||||
${scope.paths.map(p => `- ${p}`).join('\\n')}
|
||||
|
||||
任务:
|
||||
1. 检查认证授权实现
|
||||
2. 分析输入验证
|
||||
3. 检测敏感数据处理
|
||||
4. 识别常见漏洞模式
|
||||
|
||||
输出格式: JSON
|
||||
{
|
||||
"auth": { "methods": [...], "issues": [...] },
|
||||
"input_validation": { "coverage": 0, "gaps": [...] },
|
||||
"sensitive_data": { "found": [...], "protected": true/false },
|
||||
"vulnerabilities": [{ "type": "...", "severity": "...", "location": "..." }]
|
||||
}`
|
||||
};
|
||||
|
||||
return prompts[type] || prompts.structure;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 预置代码分析动作
|
||||
|
||||
### 1. 项目结构分析
|
||||
|
||||
```yaml
|
||||
id: analyze-project-structure
|
||||
name: Project Structure Analysis
|
||||
type: code-analysis
|
||||
scope:
|
||||
paths:
|
||||
- src/
|
||||
patterns:
|
||||
- "**/*.ts"
|
||||
- "**/*.js"
|
||||
excludes:
|
||||
- "**/node_modules/**"
|
||||
- "**/*.test.*"
|
||||
analysis_type: structure
|
||||
agent:
|
||||
type: Explore
|
||||
thoroughness: medium
|
||||
output:
|
||||
format: json
|
||||
file: structure-analysis.json
|
||||
mcp_tools:
|
||||
- mcp__ace-tool__search_context
|
||||
```
|
||||
|
||||
### 2. 设计模式提取
|
||||
|
||||
```yaml
|
||||
id: extract-design-patterns
|
||||
name: Design Pattern Extraction
|
||||
type: code-analysis
|
||||
scope:
|
||||
paths:
|
||||
- src/
|
||||
patterns:
|
||||
- "**/*.ts"
|
||||
analysis_type: patterns
|
||||
agent:
|
||||
type: cli-explore-agent
|
||||
thoroughness: very thorough
|
||||
output:
|
||||
format: markdown
|
||||
file: patterns-report.md
|
||||
```
|
||||
|
||||
### 3. 依赖关系分析
|
||||
|
||||
```yaml
|
||||
id: analyze-dependencies
|
||||
name: Dependency Analysis
|
||||
type: code-analysis
|
||||
scope:
|
||||
paths:
|
||||
- src/
|
||||
- packages/
|
||||
patterns:
|
||||
- "**/package.json"
|
||||
- "**/*.ts"
|
||||
analysis_type: dependencies
|
||||
agent:
|
||||
type: Explore
|
||||
thoroughness: medium
|
||||
output:
|
||||
format: json
|
||||
file: dependency-graph.json
|
||||
```
|
||||
|
||||
### 4. 安全审计
|
||||
|
||||
```yaml
|
||||
id: security-audit
|
||||
name: Security Audit
|
||||
type: code-analysis
|
||||
scope:
|
||||
paths:
|
||||
- src/auth/
|
||||
- src/api/
|
||||
patterns:
|
||||
- "**/*.ts"
|
||||
analysis_type: security
|
||||
agent:
|
||||
type: universal-executor
|
||||
thoroughness: very thorough
|
||||
output:
|
||||
format: json
|
||||
file: security-report.json
|
||||
mcp_tools:
|
||||
- mcp__ace-tool__search_context
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 使用示例
|
||||
|
||||
### 在 Phase 中使用
|
||||
|
||||
```javascript
|
||||
// phases/01-code-exploration.md
|
||||
|
||||
const analysisConfig = {
|
||||
id: 'explore-skill-structure',
|
||||
name: 'Skill Structure Exploration',
|
||||
type: 'code-analysis',
|
||||
scope: {
|
||||
paths: ['D:\\Claude_dms3\\.claude\\skills\\software-manual'],
|
||||
patterns: ['**/*.md'],
|
||||
excludes: ['**/node_modules/**']
|
||||
},
|
||||
analysis_type: 'structure',
|
||||
agent: {
|
||||
type: 'Explore',
|
||||
thoroughness: 'medium'
|
||||
},
|
||||
output: {
|
||||
format: 'json',
|
||||
file: 'skill-structure.json'
|
||||
}
|
||||
};
|
||||
|
||||
// 执行
|
||||
const result = await executeCodeAnalysis(analysisConfig, context);
|
||||
```
|
||||
|
||||
### 组合多种分析
|
||||
|
||||
```javascript
|
||||
// 串行执行多种分析
|
||||
const analyses = [
|
||||
{ type: 'structure', file: 'structure.json' },
|
||||
{ type: 'patterns', file: 'patterns.json' },
|
||||
{ type: 'dependencies', file: 'deps.json' }
|
||||
];
|
||||
|
||||
for (const analysis of analyses) {
|
||||
await executeCodeAnalysis({
|
||||
...baseConfig,
|
||||
analysis_type: analysis.type,
|
||||
output: { format: 'json', file: analysis.file }
|
||||
}, context);
|
||||
}
|
||||
|
||||
// 并行执行（独立分析）
|
||||
const parallelResults = await Promise.all(
|
||||
analyses.map(a => executeCodeAnalysis({
|
||||
...baseConfig,
|
||||
analysis_type: a.type,
|
||||
output: { format: 'json', file: a.file }
|
||||
}, context))
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Agent 选择指南
|
||||
|
||||
| 分析类型 | 推荐 Agent | Thoroughness | 原因 |
|
||||
|---------|-----------|--------------|------|
|
||||
| structure | Explore | medium | 快速获取目录结构 |
|
||||
| patterns | cli-explore-agent | very thorough | 需要深度代码理解 |
|
||||
| dependencies | Explore | medium | 主要分析 import 语句 |
|
||||
| quality | universal-executor | medium | 需要运行分析工具 |
|
||||
| security | universal-executor | very thorough | 需要全面扫描 |
|
||||
|
||||
---
|
||||
|
||||
## MCP 工具集成
|
||||
|
||||
### 语义搜索增强
|
||||
|
||||
```javascript
|
||||
// 使用 ACE 工具进行语义搜索
|
||||
const semanticContext = await mcp__ace_tool__search_context({
|
||||
project_root_path: projectRoot,
|
||||
query: 'authentication logic, user session management'
|
||||
});
|
||||
|
||||
// 将语义搜索结果作为 Agent 的输入上下文
|
||||
const agentResult = await Task({
|
||||
subagent_type: 'Explore',
|
||||
prompt: `
|
||||
基于以下语义搜索结果进行深度分析:
|
||||
|
||||
${semanticContext}
|
||||
|
||||
任务: 分析认证逻辑的实现细节...
|
||||
`,
|
||||
run_in_background: false
|
||||
});
|
||||
```
|
||||
|
||||
### smart_search 集成
|
||||
|
||||
```javascript
|
||||
// 使用 smart_search 进行精确搜索
|
||||
const exactMatches = await mcp__ccw_tools__smart_search({
|
||||
action: 'search',
|
||||
query: 'class.*Controller',
|
||||
mode: 'ripgrep',
|
||||
path: 'src/'
|
||||
});
|
||||
|
||||
// 使用 find_files 发现文件
|
||||
const configFiles = await mcp__ccw_tools__smart_search({
|
||||
action: 'find_files',
|
||||
pattern: '**/*.config.ts',
|
||||
path: 'src/'
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 结果聚合
|
||||
|
||||
```javascript
|
||||
function aggregateResults(results) {
|
||||
const aggregated = {
|
||||
timestamp: new Date().toISOString(),
|
||||
sources: [],
|
||||
summary: {},
|
||||
details: []
|
||||
};
|
||||
|
||||
for (const result of results) {
|
||||
aggregated.sources.push(result.type);
|
||||
|
||||
if (result.type === 'semantic') {
|
||||
aggregated.summary.semantic_matches = result.data.length;
|
||||
aggregated.details.push({
|
||||
source: 'semantic',
|
||||
data: result.data.slice(0, 10) // Top 10
|
||||
});
|
||||
}
|
||||
|
||||
if (result.type === 'agent') {
|
||||
aggregated.summary.agent_findings = extractKeyFindings(result.data);
|
||||
aggregated.details.push({
|
||||
source: 'agent',
|
||||
data: result.data
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
return aggregated;
|
||||
}
|
||||
|
||||
function extractKeyFindings(agentResult) {
|
||||
// 从 Agent 结果中提取关键发现
|
||||
// 实现取决于 Agent 的输出格式
|
||||
return {
|
||||
modules: agentResult.modules?.length || 0,
|
||||
patterns: agentResult.patterns?.length || 0,
|
||||
issues: agentResult.issues?.length || 0
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 最佳实践
|
||||
|
||||
1. **范围控制**
|
||||
- 使用精确的 patterns 减少分析范围
|
||||
- 配置 excludes 排除无关文件
|
||||
|
||||
2. **Agent 选择**
|
||||
- 快速探索用 Explore
|
||||
- 深度分析用 cli-explore-agent
|
||||
- 需要执行操作用 universal-executor
|
||||
|
||||
3. **MCP 工具组合**
|
||||
- 先用 mcp__ace-tool__search_context 获取语义上下文
|
||||
- 再用 Agent 进行深度分析
|
||||
- 最后用 smart_search 补充精确匹配
|
||||
|
||||
4. **结果缓存**
|
||||
- 将分析结果持久化到 workDir
|
||||
- 后续阶段可直接读取，避免重复分析
|
||||
|
||||
5. **Brief Returns**
|
||||
- Agent 返回路径 + 摘要，而非完整内容
|
||||
- 避免上下文溢出
|
||||
355
.claude/skills/skill-generator/templates/llm-action.md
Normal file
355
.claude/skills/skill-generator/templates/llm-action.md
Normal file
@@ -0,0 +1,355 @@
|
||||
# LLM Action Template
|
||||
|
||||
LLM 动作模板，用于在 Skill 中集成 LLM 调用能力。
|
||||
|
||||
---
|
||||
|
||||
## 配置结构
|
||||
|
||||
```typescript
|
||||
interface LLMActionConfig {
|
||||
id: string; // "llm-analyze", "llm-generate"
|
||||
name: string; // "LLM Analysis"
|
||||
type: 'llm'; // 动作类型标识
|
||||
|
||||
// LLM 工具配置
|
||||
tool: {
|
||||
primary: 'gemini' | 'qwen' | 'codex';
|
||||
fallback_chain: string[]; // ['gemini', 'qwen', 'codex']
|
||||
};
|
||||
|
||||
// 执行模式
|
||||
mode: 'analysis' | 'write';
|
||||
|
||||
// 提示词配置
|
||||
prompt: {
|
||||
template: string; // 提示词模板路径或内联
|
||||
variables: string[]; // 需要替换的变量
|
||||
};
|
||||
|
||||
// 输入输出
|
||||
input: string[]; // 依赖的上下文文件
|
||||
output: string; // 输出文件路径
|
||||
|
||||
// 超时配置
|
||||
timeout?: number; // 毫秒，默认 600000 (10min)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 模板生成函数
|
||||
|
||||
```javascript
|
||||
function generateLLMAction(config) {
|
||||
const { id, name, tool, mode, prompt, input, output, timeout = 600000 } = config;
|
||||
|
||||
return `
|
||||
# ${name}
|
||||
|
||||
## Action: ${id}
|
||||
|
||||
### 执行逻辑
|
||||
|
||||
\`\`\`javascript
|
||||
async function execute${toPascalCase(id)}(context) {
|
||||
const workDir = context.workDir;
|
||||
const state = context.state;
|
||||
|
||||
// 1. 收集输入上下文
|
||||
const inputContext = ${JSON.stringify(input)}.map(f => {
|
||||
const path = \`\${workDir}/\${f}\`;
|
||||
return Read(path);
|
||||
}).join('\\n\\n---\\n\\n');
|
||||
|
||||
// 2. 构建提示词
|
||||
const promptTemplate = \`${prompt.template}\`;
|
||||
const finalPrompt = promptTemplate
|
||||
${prompt.variables.map(v => `.replace('{{${v}}}', context.${v} || '')`).join('\n ')};
|
||||
|
||||
// 3. 执行 LLM 调用 (带 fallback)
|
||||
const tools = ['${tool.primary}', ${tool.fallback_chain.map(t => `'${t}'`).join(', ')}];
|
||||
let result = null;
|
||||
let usedTool = null;
|
||||
|
||||
for (const t of tools) {
|
||||
try {
|
||||
result = await callLLM(t, finalPrompt, '${mode}', ${timeout});
|
||||
usedTool = t;
|
||||
break;
|
||||
} catch (error) {
|
||||
console.log(\`\${t} failed: \${error.message}, trying next...\`);
|
||||
}
|
||||
}
|
||||
|
||||
if (!result) {
|
||||
throw new Error('All LLM tools failed');
|
||||
}
|
||||
|
||||
// 4. 保存结果
|
||||
Write(\`\${workDir}/${output}\`, result);
|
||||
|
||||
// 5. 更新状态
|
||||
state.llm_calls = (state.llm_calls || 0) + 1;
|
||||
state.last_llm_tool = usedTool;
|
||||
|
||||
return {
|
||||
success: true,
|
||||
output: '${output}',
|
||||
tool_used: usedTool
|
||||
};
|
||||
}
|
||||
|
||||
// LLM 调用封装
|
||||
async function callLLM(tool, prompt, mode, timeout) {
|
||||
const modeFlag = mode === 'write' ? '--mode write' : '--mode analysis';
|
||||
|
||||
// 使用 CCW CLI 统一接口
|
||||
const command = \`ccw cli -p "\${escapePrompt(prompt)}" --tool \${tool} \${modeFlag}\`;
|
||||
|
||||
const result = Bash({
|
||||
command,
|
||||
timeout,
|
||||
run_in_background: true // 异步执行
|
||||
});
|
||||
|
||||
// 等待完成
|
||||
return await waitForResult(result.task_id, timeout);
|
||||
}
|
||||
|
||||
function escapePrompt(prompt) {
|
||||
// 转义双引号和特殊字符
|
||||
return prompt.replace(/"/g, '\\\\"').replace(/\$/g, '\\\\$');
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
### Prompt 模板
|
||||
|
||||
\`\`\`
|
||||
${prompt.template}
|
||||
\`\`\`
|
||||
|
||||
### 变量说明
|
||||
|
||||
${prompt.variables.map(v => `- \`{{${v}}}\`: ${v} 变量`).join('\n')}
|
||||
`;
|
||||
}
|
||||
|
||||
function toPascalCase(str) {
|
||||
return str.split('-').map(s => s.charAt(0).toUpperCase() + s.slice(1)).join('');
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 预置 LLM 动作模板
|
||||
|
||||
### 1. 代码分析动作
|
||||
|
||||
```yaml
|
||||
id: llm-code-analysis
|
||||
name: LLM Code Analysis
|
||||
type: llm
|
||||
tool:
|
||||
primary: gemini
|
||||
fallback_chain: [qwen]
|
||||
mode: analysis
|
||||
prompt:
|
||||
template: |
|
||||
PURPOSE: 分析代码结构和模式，提取关键设计特征
|
||||
TASK:
|
||||
• 识别主要模块和组件
|
||||
• 分析依赖关系
|
||||
• 提取设计模式
|
||||
• 评估代码质量
|
||||
MODE: analysis
|
||||
CONTEXT: {{code_context}}
|
||||
EXPECTED: JSON 格式的分析报告，包含 modules, dependencies, patterns, quality_score
|
||||
RULES: $(cat ~/.claude/workflows/cli-templates/protocols/analysis-protocol.md)
|
||||
variables:
|
||||
- code_context
|
||||
input:
|
||||
- collected-code.md
|
||||
output: analysis-report.json
|
||||
timeout: 900000
|
||||
```
|
||||
|
||||
### 2. 文档生成动作
|
||||
|
||||
```yaml
|
||||
id: llm-doc-generation
|
||||
name: LLM Documentation Generation
|
||||
type: llm
|
||||
tool:
|
||||
primary: gemini
|
||||
fallback_chain: [qwen, codex]
|
||||
mode: write
|
||||
prompt:
|
||||
template: |
|
||||
PURPOSE: 根据分析结果生成高质量文档
|
||||
TASK:
|
||||
• 基于分析报告生成文档大纲
|
||||
• 填充各章节内容
|
||||
• 添加代码示例和说明
|
||||
• 生成 Mermaid 图表
|
||||
MODE: write
|
||||
CONTEXT: {{analysis_report}}
|
||||
EXPECTED: 完整的 Markdown 文档，包含目录、章节、图表
|
||||
RULES: $(cat ~/.claude/workflows/cli-templates/protocols/write-protocol.md)
|
||||
variables:
|
||||
- analysis_report
|
||||
input:
|
||||
- analysis-report.json
|
||||
output: generated-doc.md
|
||||
timeout: 1200000
|
||||
```
|
||||
|
||||
### 3. 代码重构建议动作
|
||||
|
||||
```yaml
|
||||
id: llm-refactor-suggest
|
||||
name: LLM Refactoring Suggestions
|
||||
type: llm
|
||||
tool:
|
||||
primary: codex
|
||||
fallback_chain: [gemini]
|
||||
mode: analysis
|
||||
prompt:
|
||||
template: |
|
||||
PURPOSE: 分析代码并提供重构建议
|
||||
TASK:
|
||||
• 识别代码异味 (code smells)
|
||||
• 评估复杂度热点
|
||||
• 提出具体重构方案
|
||||
• 估算重构影响范围
|
||||
MODE: analysis
|
||||
CONTEXT: {{source_code}}
|
||||
EXPECTED: 重构建议列表，每项包含 location, issue, suggestion, impact
|
||||
RULES: $(cat ~/.claude/workflows/cli-templates/protocols/analysis-protocol.md)
|
||||
variables:
|
||||
- source_code
|
||||
input:
|
||||
- source-files.md
|
||||
output: refactor-suggestions.json
|
||||
timeout: 600000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 使用示例
|
||||
|
||||
### 在 Phase 中使用 LLM 动作
|
||||
|
||||
```javascript
|
||||
// phases/02-llm-analysis.md
|
||||
|
||||
const llmConfig = {
|
||||
id: 'llm-analyze-skill',
|
||||
name: 'Skill Pattern Analysis',
|
||||
type: 'llm',
|
||||
tool: {
|
||||
primary: 'gemini',
|
||||
fallback_chain: ['qwen']
|
||||
},
|
||||
mode: 'analysis',
|
||||
prompt: {
|
||||
template: `
|
||||
PURPOSE: 分析现有 Skill 的设计模式
|
||||
TASK:
|
||||
• 提取 Skill 结构规范
|
||||
• 识别 Phase 组织模式
|
||||
• 分析 Agent 调用模式
|
||||
MODE: analysis
|
||||
CONTEXT: {{skill_source}}
|
||||
EXPECTED: 结构化的设计模式分析
|
||||
`,
|
||||
variables: ['skill_source']
|
||||
},
|
||||
input: ['collected-skills.md'],
|
||||
output: 'skill-patterns.json'
|
||||
};
|
||||
|
||||
// 执行
|
||||
const result = await executeLLMAction(llmConfig, {
|
||||
workDir: '.workflow/.scratchpad/skill-gen-xxx',
|
||||
skill_source: Read('.workflow/.scratchpad/skill-gen-xxx/collected-skills.md')
|
||||
});
|
||||
```
|
||||
|
||||
### 在 Orchestrator 中调度 LLM 动作
|
||||
|
||||
```javascript
|
||||
// autonomous-orchestrator 中的 LLM 动作调度
|
||||
|
||||
const actions = [
|
||||
{ type: 'collect', priority: 100 },
|
||||
{ type: 'llm', id: 'llm-analyze', priority: 90 }, // LLM 分析
|
||||
{ type: 'process', priority: 80 },
|
||||
{ type: 'llm', id: 'llm-generate', priority: 70 }, // LLM 生成
|
||||
{ type: 'validate', priority: 60 }
|
||||
];
|
||||
|
||||
for (const action of sortByPriority(actions)) {
|
||||
if (action.type === 'llm') {
|
||||
const llmResult = await executeLLMAction(
|
||||
getLLMConfig(action.id),
|
||||
context
|
||||
);
|
||||
context.state[action.id] = llmResult;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 错误处理
|
||||
|
||||
```javascript
|
||||
async function executeLLMActionWithRetry(config, context, maxRetries = 3) {
|
||||
let lastError = null;
|
||||
|
||||
for (let attempt = 1; attempt <= maxRetries; attempt++) {
|
||||
try {
|
||||
return await executeLLMAction(config, context);
|
||||
} catch (error) {
|
||||
lastError = error;
|
||||
console.log(`Attempt ${attempt} failed: ${error.message}`);
|
||||
|
||||
// 指数退避
|
||||
if (attempt < maxRetries) {
|
||||
await sleep(Math.pow(2, attempt) * 1000);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 所有重试失败
|
||||
return {
|
||||
success: false,
|
||||
error: lastError.message,
|
||||
fallback: 'manual_review_required'
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 最佳实践
|
||||
|
||||
1. **选择合适的工具**
|
||||
- 分析任务：Gemini（大上下文）> Qwen
|
||||
- 生成任务：Codex（自主执行）> Gemini > Qwen
|
||||
- 代码修改：Codex > Gemini
|
||||
|
||||
2. **配置 Fallback Chain**
|
||||
- 总是配置至少一个 fallback
|
||||
- 考虑工具特性选择 fallback 顺序
|
||||
|
||||
3. **超时设置**
|
||||
- 分析任务：10-15 分钟
|
||||
- 生成任务：15-20 分钟
|
||||
- 复杂任务：20-60 分钟
|
||||
|
||||
4. **提示词设计**
|
||||
- 使用 PURPOSE/TASK/MODE/CONTEXT/EXPECTED/RULES 结构
|
||||
- 引用标准协议模板
|
||||
- 明确输出格式要求
|
||||
Reference in New Issue
Block a user