skill-tuning

技能调优

针对技能执行问题进行自主诊断与优化。

架构

┌─────────────────────────────────────────────────────┐
│  Phase 0: Read Specs (mandatory)                    │
│  → problem-taxonomy.md, tuning-strategies.md         │
└─────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────┐
│  Orchestrator (state-driven)                         │
│  Read state → Select action → Execute → Update → ✓ │
└─────────────────────────────────────────────────────┘
        ↓                           ↓
┌──────────────────────┐   ┌──────────────────┐
│  Diagnosis Phase     │   │ Gemini CLI       │
│  • Context          │   │ Deep analysis    │
│  • Memory           │   │ (on-demand)      │
│  • DataFlow         │   │                  │
│  • Agent            │   │ Complex issues   │
│  • Docs             │   │ Architecture     │
│  • Token Usage      │   │ Performance      │
└──────────────────────┘   └──────────────────┘
                ↓
        ┌───────────────────┐
        │  Fix & Verify     │
        │  Apply → Re-test  │
        └───────────────────┘

检测到的核心问题

优先级	问题	根本原因	修复策略
P0	违规编写	中间文件、状态膨胀、文件中转	eliminate_intermediate、minimize_state
P1	数据流中断	状态分散、格式不一致	state_centralization、schema_enforcement
P2	Agent 协作	链条脆弱、没有错误处理	error_wrapping、result_validation
P3	上下文膨胀	历史记录无界、传递完整内容	sliding_window、path_reference
P4	长程遗忘	丢失早期约束	constraint_injection、checkpoint_restore
P5	令牌消耗	提示词冗长、状态膨胀	prompt_compression、lazy_loading

问题类别（详细规格）

请参阅 specs/problem-taxonomy.md，了解：

• 检测模式（正则表达式/检查）
• 严重程度计算
• 影响评估

调优策略（详细规格）

请参阅 specs/tuning-strategies.md，了解：

• 每个类别有 10 种以上的策略
• 实现模式
• 验证方法

工作流

步骤	操作	编排器决策	输出
1	action-init	status='pending'	创建备份和会话
2	action-analyze-requirements	初始化后	所需维度 + 覆盖范围
3	诊断（6 种类型）	关注领域	state.diagnosis.{type}
4	action-gemini-analysis	存在关键问题或用户请求	深入发现
5	action-generate-report	所有诊断完成	state.final_report
6	action-propose-fixes	发现问题	state.proposed_fixes[]
7	action-apply-fix	有待处理的修复	已应用并验证
8	action-complete	质量门禁通过	session.status='completed'

操作参考

类别	操作	用途
设置	action-init	初始化备份和会话状态
分析	action-analyze-requirements	通过 Gemini CLI 分解用户请求
诊断	action-diagnose-{context,memory,dataflow,agent,docs,token_consumption}	检测特定类别的问题
深度分析	action-gemini-analysis	Gemini CLI：处理复杂/关键问题
报告	action-generate-report	汇总发现 → final_report
修复	action-propose-fixes, action-apply-fix	生成并应用修复
验证	action-verify	重新运行诊断并检查门禁
退出	action-complete, action-abort	完成或回滚

完整操作详情：phases/actions/

状态管理

唯一可信数据源：.workflow/.scratchpad/skill-tuning-{ts}/state.json

{
  "status": "pending|running|completed|failed",
  "target_skill": { "name": "...", "path": "..." },
  "diagnosis": {
    "context": {...},
    "memory": {...},
    "dataflow": {...},
    "agent": {...},
    "docs": {...},
    "token_consumption": {...}
  },
  "issues": [{"id":"...", "severity":"...", "category":"...", "strategy":"..."}],
  "proposed_fixes": [...],
  "applied_fixes": [...],
  "quality_gate": "pass|fail",
  "final_report": "..."
}

请参阅 phases/state-schema.md，了解完整架构。

编排器逻辑

请参阅 phases/orchestrator.md，了解：

• 决策逻辑（终止检查 → 操作选择）
• 状态转换
• 错误恢复

核心原则

1. 问题优先：先诊断，再修复
2. 数据驱动：记录轨迹、令牌计数和快照
3. 迭代进行：反复执行，直至通过质量门禁
4. 可逆：所有更改均设有备份检查点
5. 非侵入式：尽可能少地更改，尽可能清晰地呈现

使用示例

# Basic skill diagnosis
/skill-tuning "Fix memory leaks in my skill"

# Deep analysis with Gemini
/skill-tuning "Architecture issues in async workflow"

# Focus on specific areas
/skill-tuning "Optimize token consumption and fix agent coordination"

# Custom issue
/skill-tuning "My skill produces inconsistent outputs"

输出

完成后，请查看：

• .workflow/.scratchpad/skill-tuning-{ts}/state.json - 包含 final_report 的完整状态
• state.final_report - Markdown 摘要（位于 state.json 中）
• state.applied_fixes - 已应用修复及其验证结果的列表

Reference Documents

Document	Purpose
specs/problem-taxonomy.md	Classification + detection patterns
specs/tuning-strategies.md	Fix implementation guide
specs/dimension-mapping.md	Dimension ↔ Spec mapping
specs/quality-gates.md	Quality verification criteria
phases/orchestrator.md	Workflow orchestration
phases/state-schema.md	State structure definition
phases/actions/	Individual action implementations