maestro-flow 0.5.31 → 0.5.33

package/.agy/skills/skill-tuning/phases/actions/action-diagnose-token-consumption.md

@@ -0,0 +1,200 @@
+# Action: Diagnose Token Consumption
+
+Analyze target skill for token consumption inefficiencies and output optimization opportunities.
+
+## Purpose
+
+Detect patterns that cause excessive token usage:
+- Verbose prompts without compression
+- Large state objects with unnecessary fields
+- Full content passing instead of references
+- Unbounded arrays without sliding windows
+- Redundant file I/O (write-then-read patterns)
+
+## Detection Patterns
+
+| Pattern ID | Name | Detection Logic | Severity |
+|------------|------|-----------------|----------|
+| TKN-001 | Verbose Prompts | Prompt files > 4KB or high static/variable ratio | medium |
+| TKN-002 | Excessive State Fields | State schema > 15 top-level keys | medium |
+| TKN-003 | Full Content Passing | `view_file()` result embedded directly in prompt | high |
+| TKN-004 | Unbounded Arrays | `.push`/`concat` without `.slice(-N)` | high |
+| TKN-005 | Redundant Write→Read | `write_to_file(file)` followed by `view_file(file)` | medium |
+
+## Execution Steps
+
+```javascript
+async function diagnoseTokenConsumption(state, workDir) {
+  const issues = [];
+  const evidence = [];
+  const skillPath = state.target_skill.path;
+
+  // 1. Scan for verbose prompts (TKN-001)
+  const mdFiles = grep_search(`${skillPath}/**/*.md`);
+  for (const file of mdFiles) {
+    const content = view_file(file);
+    if (content.length > 4000) {
+      evidence.push({
+        file: file,
+        pattern: 'TKN-001',
+        severity: 'medium',
+        context: `File size: ${content.length} chars (threshold: 4000)`
+      });
+    }
+  }
+
+  // 2. Check state schema field count (TKN-002)
+  const stateSchema = grep_search(`${skillPath}/**/state-schema.md`)[0];
+  if (stateSchema) {
+    const schemaContent = view_file(stateSchema);
+    const fieldMatches = schemaContent.match(/^\s*\w+:/gm) || [];
+    if (fieldMatches.length > 15) {
+      evidence.push({
+        file: stateSchema,
+        pattern: 'TKN-002',
+        severity: 'medium',
+        context: `State has ${fieldMatches.length} fields (threshold: 15)`
+      });
+    }
+  }
+
+  // 3. Detect full content passing (TKN-003)
+  const fullContentPattern = /Read\([^)]+\)\s*[\+,]|`\$\{.*Read\(/g;
+  for (const file of mdFiles) {
+    const content = view_file(file);
+    const matches = content.match(fullContentPattern);
+    if (matches) {
+      evidence.push({
+        file: file,
+        pattern: 'TKN-003',
+        severity: 'high',
+        context: `Full content passing detected: ${matches[0]}`
+      });
+    }
+  }
+
+  // 4. Detect unbounded arrays (TKN-004)
+  const unboundedPattern = /\.(push|concat)\([^)]+\)(?!.*\.slice)/g;
+  for (const file of mdFiles) {
+    const content = view_file(file);
+    const matches = content.match(unboundedPattern);
+    if (matches) {
+      evidence.push({
+        file: file,
+        pattern: 'TKN-004',
+        severity: 'high',
+        context: `Unbounded array growth: ${matches[0]}`
+      });
+    }
+  }
+
+  // 5. Detect write-then-read patterns (TKN-005)
+  const writeReadPattern = /Write\([^)]+\)[\s\S]{0,100}Read\([^)]+\)/g;
+  for (const file of mdFiles) {
+    const content = view_file(file);
+    const matches = content.match(writeReadPattern);
+    if (matches) {
+      evidence.push({
+        file: file,
+        pattern: 'TKN-005',
+        severity: 'medium',
+        context: `Write-then-read pattern detected`
+      });
+    }
+  }
+
+  // Calculate severity
+  const highCount = evidence.filter(e => e.severity === 'high').length;
+  const mediumCount = evidence.filter(e => e.severity === 'medium').length;
+
+  let severity = 'none';
+  if (highCount > 0) severity = 'high';
+  else if (mediumCount > 2) severity = 'medium';
+  else if (mediumCount > 0) severity = 'low';
+
+  return {
+    status: 'completed',
+    issues_found: evidence.length,
+    severity: severity,
+    execution_time_ms: Date.now() - startTime,
+    details: {
+      patterns_checked: ['TKN-001', 'TKN-002', 'TKN-003', 'TKN-004', 'TKN-005'],
+      patterns_matched: [...new Set(evidence.map(e => e.pattern))],
+      evidence: evidence,
+      recommendations: generateRecommendations(evidence)
+    }
+  };
+}
+
+function generateRecommendations(evidence) {
+  const recs = [];
+  const patterns = [...new Set(evidence.map(e => e.pattern))];
+
+  if (patterns.includes('TKN-001')) {
+    recs.push('Apply prompt_compression: Extract static instructions to templates, use placeholders');
+  }
+  if (patterns.includes('TKN-002')) {
+    recs.push('Apply state_field_reduction: Remove debug/cache fields, consolidate related fields');
+  }
+  if (patterns.includes('TKN-003')) {
+    recs.push('Apply lazy_loading: Pass file paths instead of content, let agents read if needed');
+  }
+  if (patterns.includes('TKN-004')) {
+    recs.push('Apply sliding_window: Add .slice(-N) to array operations to bound growth');
+  }
+  if (patterns.includes('TKN-005')) {
+    recs.push('Apply output_minimization: Use in-memory data passing, eliminate temporary files');
+  }
+
+  return recs;
+}
+```
+
+## Output
+
+Write diagnosis result to `${workDir}/diagnosis/token-consumption-diagnosis.json`:
+
+```json
+{
+  "status": "completed",
+  "issues_found": 3,
+  "severity": "medium",
+  "execution_time_ms": 1500,
+  "details": {
+    "patterns_checked": ["TKN-001", "TKN-002", "TKN-003", "TKN-004", "TKN-005"],
+    "patterns_matched": ["TKN-001", "TKN-003"],
+    "evidence": [
+      {
+        "file": "phases/orchestrator.md",
+        "pattern": "TKN-001",
+        "severity": "medium",
+        "context": "File size: 5200 chars (threshold: 4000)"
+      }
+    ],
+    "recommendations": [
+      "Apply prompt_compression: Extract static instructions to templates"
+    ]
+  }
+}
+```
+
+## State Update
+
+```javascript
+updateState({
+  diagnosis: {
+    ...state.diagnosis,
+    token_consumption: diagnosisResult
+  }
+});
+```
+
+## Fix Strategies Mapping
+
+| Pattern | Strategy | Implementation |
+|---------|----------|----------------|
+| TKN-001 | prompt_compression | Extract static text to variables, use template inheritance |
+| TKN-002 | state_field_reduction | Audit and consolidate fields, remove non-essential data |
+| TKN-003 | lazy_loading | Pass paths instead of content, agents load when needed |
+| TKN-004 | sliding_window | Add `.slice(-N)` after push/concat operations |
+| TKN-005 | output_minimization | Use return values instead of file relay |

package/.agy/skills/skill-tuning/phases/actions/action-gemini-analysis.md

@@ -0,0 +1,322 @@
+# Action: Gemini Analysis
+
+动态调用 Gemini CLI 进行深度分析，根据用户需求或诊断结果选择分析类型。
+
+## Role
+
+- 接收用户指定的分析需求或从诊断结果推断需求
+- 构建适当的 CLI 命令
+- 执行分析并解析结果
+- 更新状态以供后续动作使用
+
+## Preconditions
+
+- `state.status === 'running'`
+- 满足以下任一条件:
+  - `state.gemini_analysis_requested === true` (用户请求)
+  - `state.issues.some(i => i.severity === 'critical')` (发现严重问题)
+  - `state.analysis_type !== null` (已指定分析类型)
+
+## Analysis Types
+
+### 1. root_cause - 问题根因分析
+
+针对用户描述的问题进行深度分析。
+
+```javascript
+const analysisPrompt = `
+PURPOSE: Identify root cause of skill execution issue: ${state.user_issue_description}
+TASK:
+• Analyze skill structure at: ${state.target_skill.path}
+• Identify anti-patterns in phase files
+• Trace data flow through state management
+• Check agent coordination patterns
+MODE: analysis
+CONTEXT: @**/*.md
+EXPECTED: JSON with structure:
+{
+  "root_causes": [
+    { "id": "RC-001", "description": "...", "severity": "high", "evidence": ["file:line"] }
+  ],
+  "patterns_found": [
+    { "pattern": "...", "type": "anti-pattern|best-practice", "locations": [] }
+  ],
+  "recommendations": [
+    { "priority": 1, "action": "...", "rationale": "..." }
+  ]
+}
+RULES: Focus on execution flow, state management, agent coordination
+`;
+```
+
+### 2. architecture - 架构审查
+
+评估 skill 的整体架构设计。
+
+```javascript
+const analysisPrompt = `
+PURPOSE: Review skill architecture for: ${state.target_skill.name}
+TASK:
+• Evaluate phase decomposition and responsibility separation
+• Check state schema design and data flow
+• Assess agent coordination and error handling
+• Review scalability and maintainability
+MODE: analysis
+CONTEXT: @**/*.md
+EXPECTED: Markdown report with sections:
+- Executive Summary
+- Phase Architecture Assessment
+- State Management Evaluation
+- Agent Coordination Analysis
+- Improvement Recommendations (prioritized)
+RULES: Focus on modularity, extensibility, maintainability
+`;
+```
+
+### 3. prompt_optimization - 提示词优化
+
+分析和优化 phase 中的提示词。
+
+```javascript
+const analysisPrompt = `
+PURPOSE: Optimize prompts in skill phases for better output quality
+TASK:
+• Analyze existing prompts for clarity and specificity
+• Identify ambiguous instructions
+• Check output format specifications
+• Evaluate constraint communication
+MODE: analysis
+CONTEXT: @phases/**/*.md
+EXPECTED: JSON with structure:
+{
+  "prompt_issues": [
+    { "file": "...", "issue": "...", "severity": "...", "suggestion": "..." }
+  ],
+  "optimized_prompts": [
+    { "file": "...", "original": "...", "optimized": "...", "rationale": "..." }
+  ]
+}
+RULES: Preserve intent, improve clarity, add structured output requirements
+`;
+```
+
+### 4. performance - 性能分析
+
+分析 Token 消耗和执行效率。
+
+```javascript
+const analysisPrompt = `
+PURPOSE: Analyze performance bottlenecks in skill execution
+TASK:
+• Estimate token consumption per phase
+• Identify redundant data passing
+• Check for unnecessary full-content transfers
+• Evaluate caching opportunities
+MODE: analysis
+CONTEXT: @**/*.md
+EXPECTED: JSON with structure:
+{
+  "token_estimates": [
+    { "phase": "...", "estimated_tokens": 1000, "breakdown": {} }
+  ],
+  "bottlenecks": [
+    { "type": "...", "location": "...", "impact": "high|medium|low", "fix": "..." }
+  ],
+  "optimization_suggestions": []
+}
+RULES: Focus on token efficiency, reduce redundancy
+`;
+```
+
+### 5. custom - 自定义分析
+
+用户指定的自定义分析需求。
+
+```javascript
+const analysisPrompt = `
+PURPOSE: ${state.custom_analysis_purpose}
+TASK: ${state.custom_analysis_tasks}
+MODE: analysis
+CONTEXT: @**/*.md
+EXPECTED: ${state.custom_analysis_expected}
+RULES: ${state.custom_analysis_rules || 'Follow best practices'}
+`;
+```
+
+## Execution
+
+```javascript
+async function executeGeminiAnalysis(state, workDir) {
+  // 1. 确定分析类型
+  const analysisType = state.analysis_type || determineAnalysisType(state);
+
+  // 2. 构建 prompt
+  const prompt = buildAnalysisPrompt(analysisType, state);
+
+  // 3. 构建 CLI 命令
+  const cliCommand = `maestro delegate "${escapeForShell(prompt)}" --to gemini --mode analysis --cd "${state.target_skill.path}"`;
+
+  console.log(`Executing Gemini analysis: ${analysisType}`);
+  console.log(`Command: ${cliCommand}`);
+
+  // 4. 执行 CLI (后台运行)
+  const result = run_command({
+    command: cliCommand,
+    run_in_background: true,
+    timeout: 300000  // 5 minutes
+  });
+
+  // 5. 等待结果
+  // 注意: 根据 CLAUDE.md 指引，CLI 后台执行后应停止轮询
+  // 结果会在 CLI 完成后写入 state
+
+  return {
+    stateUpdates: {
+      gemini_analysis: {
+        type: analysisType,
+        status: 'running',
+        started_at: new Date().toISOString(),
+        task_id: result.task_id
+      }
+    },
+    outputFiles: [],
+    summary: `Gemini ${analysisType} analysis started in background`
+  };
+}
+
+function determineAnalysisType(state) {
+  // 根据状态推断分析类型
+  if (state.user_issue_description && state.user_issue_description.length > 100) {
+    return 'root_cause';
+  }
+  if (state.issues.some(i => i.severity === 'critical')) {
+    return 'root_cause';
+  }
+  if (state.focus_areas.includes('architecture')) {
+    return 'architecture';
+  }
+  if (state.focus_areas.includes('prompt')) {
+    return 'prompt_optimization';
+  }
+  if (state.focus_areas.includes('performance')) {
+    return 'performance';
+  }
+  return 'root_cause';  // 默认
+}
+
+function buildAnalysisPrompt(type, state) {
+  const templates = {
+    root_cause: () => `
+PURPOSE: Identify root cause of skill execution issue: ${state.user_issue_description}
+TASK: • Analyze skill structure • Identify anti-patterns • Trace data flow issues • Check agent coordination
+MODE: analysis
+CONTEXT: @**/*.md
+EXPECTED: JSON { root_causes: [], patterns_found: [], recommendations: [] }
+RULES: Focus on execution flow, be specific about file:line locations
+`,
+    architecture: () => `
+PURPOSE: Review skill architecture for ${state.target_skill.name}
+TASK: • Evaluate phase decomposition • Check state design • Assess agent coordination • Review extensibility
+MODE: analysis
+CONTEXT: @**/*.md
+EXPECTED: Markdown architecture assessment report
+RULES: Focus on modularity and maintainability
+`,
+    prompt_optimization: () => `
+PURPOSE: Optimize prompts in skill for better output quality
+TASK: • Analyze prompt clarity • Check output specifications • Evaluate constraint handling
+MODE: analysis
+CONTEXT: @phases/**/*.md
+EXPECTED: JSON { prompt_issues: [], optimized_prompts: [] }
+RULES: Preserve intent, improve clarity
+`,
+    performance: () => `
+PURPOSE: Analyze performance bottlenecks in skill
+TASK: • Estimate token consumption • Identify redundancy • Check data transfer efficiency
+MODE: analysis
+CONTEXT: @**/*.md
+EXPECTED: JSON { token_estimates: [], bottlenecks: [], optimization_suggestions: [] }
+RULES: Focus on token efficiency
+`,
+    custom: () => `
+PURPOSE: ${state.custom_analysis_purpose}
+TASK: ${state.custom_analysis_tasks}
+MODE: analysis
+CONTEXT: @**/*.md
+EXPECTED: ${state.custom_analysis_expected}
+RULES: ${state.custom_analysis_rules || 'Best practices'}
+`
+  };
+
+  return templates[type]();
+}
+
+function escapeForShell(str) {
+  // 转义 shell 特殊字符
+  return str.replace(/"/g, '\\"').replace(/\$/g, '\\$').replace(/`/g, '\\`');
+}
+```
+
+## Output
+
+### State Updates
+
+```javascript
+{
+  gemini_analysis: {
+    type: 'root_cause' | 'architecture' | 'prompt_optimization' | 'performance' | 'custom',
+    status: 'running' | 'completed' | 'failed',
+    started_at: '2024-01-01T00:00:00Z',
+    completed_at: '2024-01-01T00:05:00Z',
+    task_id: 'xxx',
+    result: { /* 分析结果 */ },
+    error: null
+  },
+  // 分析结果合并到 issues
+  issues: [
+    ...state.issues,
+    ...newIssuesFromAnalysis
+  ]
+}
+```
+
+### Output Files
+
+- `${workDir}/diagnosis/gemini-analysis-${type}.json` - 原始分析结果
+- `${workDir}/diagnosis/gemini-analysis-${type}.md` - 格式化报告
+
+## Post-Execution
+
+分析完成后:
+1. 解析 CLI 输出为结构化数据
+2. 提取新发现的 issues 合并到 state.issues
+3. 更新 recommendations 到 state
+4. 触发下一步动作 (通常是 action-generate-report 或 action-propose-fixes)
+
+## Error Handling
+
+| Error | Recovery |
+|-------|----------|
+| CLI 超时 | 重试一次，仍失败则跳过 Gemini 分析 |
+| 解析失败 | 保存原始输出，手动处理 |
+| 无结果 | 标记为 skipped，继续流程 |
+
+## User Interaction
+
+如果 `state.analysis_type === null` 且无法自动推断，询问用户:
+
+```javascript
+ask_question({
+  questions: [{
+    question: '请选择 Gemini 分析类型',
+    header: '分析类型',
+    options: [
+      { label: '问题根因分析', description: '深度分析用户描述的问题' },
+      { label: '架构审查', description: '评估整体架构设计' },
+      { label: '提示词优化', description: '分析和优化 phase 提示词' },
+      { label: '性能分析', description: '分析 Token 消耗和执行效率' }
+    ],
+    multiSelect: false
+  }]
+});
+```