feat: 添加需求分析功能，支持维度拆解、覆盖度评估和歧义检测

2026-02-15 02:42:45 +08:00 · 2026-01-14 13:42:57 +08:00
parent 43b8cfc7b0
commit 9e55f51501
8 changed files with 1115 additions and 7 deletions
--- a/.claude/skills/skill-tuning/phases/actions/action-analyze-requirements.md
+++ b/.claude/skills/skill-tuning/phases/actions/action-analyze-requirements.md
@@ -0,0 +1,436 @@
+# Action: Analyze Requirements
+
+将用户问题描述拆解为多个分析维度，匹配 Spec，评估覆盖度，检测歧义。
+
+## Purpose
+
+- 将单一用户描述拆解为多个独立关注维度
+- 为每个维度匹配 problem-taxonomy（检测）+ tuning-strategies（修复）
+- 以"有修复策略"为标准判断是否满足需求
+- 检测歧义并在必要时请求用户澄清
+
+## Preconditions
+
+- [ ] `state.status === 'running'`
+- [ ] `state.target_skill !== null`
+- [ ] `state.completed_actions.includes('action-init')`
+- [ ] `!state.completed_actions.includes('action-analyze-requirements')`
+
+## Execution
+
+### Phase 1: 维度拆解 (Gemini CLI)
+
+调用 Gemini 对用户描述进行语义分析，拆解为独立维度：
+
+```javascript
+async function analyzeDimensions(state, workDir) {
+  const prompt = `
+PURPOSE: 分析用户问题描述，拆解为独立的关注维度
+TASK:
+• 识别用户描述中的多个关注点（每个关注点应该是独立的、可单独分析的）
+• 为每个关注点提取关键词（中英文均可）
+• 推断可能的问题类别：
+  - context_explosion: 上下文/Token 相关
+  - memory_loss: 遗忘/约束丢失相关
+  - dataflow_break: 状态/数据流相关
+  - agent_failure: Agent/子任务相关
+  - prompt_quality: 提示词/输出质量相关
+  - architecture: 架构/结构相关
+  - performance: 性能/效率相关
+  - error_handling: 错误/异常处理相关
+  - output_quality: 输出质量/验证相关
+  - user_experience: 交互/体验相关
+• 评估推断置信度 (0-1)
+
+INPUT:
+User description: ${state.user_issue_description}
+Target skill: ${state.target_skill.name}
+Skill structure: ${JSON.stringify(state.target_skill.phases)}
+
+MODE: analysis
+CONTEXT: @specs/problem-taxonomy.md @specs/dimension-mapping.md
+EXPECTED: JSON (不要包含 markdown 代码块标记)
+{
+  "dimensions": [
+    {
+      "id": "DIM-001",
+      "description": "关注点的简短描述",
+      "keywords": ["关键词1", "关键词2"],
+      "inferred_category": "问题类别",
+      "confidence": 0.85,
+      "reasoning": "推断理由"
+    }
+  ],
+  "analysis_notes": "整体分析说明"
+}
+RULES: 
+- 每个维度必须独立，不重叠
+- 低于 0.5 置信度的推断应标注需要澄清
+- 如果用户描述非常模糊，至少提取一个 "general" 维度
+`;
+
+  const cliCommand = `ccw cli -p "${escapeForShell(prompt)}" --tool gemini --mode analysis --cd "${state.target_skill.path}"`;
+  
+  console.log('Phase 1: 执行 Gemini 维度拆解分析...');
+  
+  const result = Bash({
+    command: cliCommand,
+    run_in_background: true,
+    timeout: 300000
+  });
+  
+  return result;
+}
+```
+
+### Phase 2: Spec 匹配
+
+基于 `specs/dimension-mapping.md` 规则为每个维度匹配检测模式和修复策略：
+
+```javascript
+function matchSpecs(dimensions) {
+  // 加载映射规则
+  const mappingRules = loadMappingRules();
+  
+  return dimensions.map(dim => {
+    // 匹配 taxonomy pattern
+    const taxonomyMatch = findTaxonomyMatch(dim.inferred_category, mappingRules);
+    
+    // 匹配 strategy
+    const strategyMatch = findStrategyMatch(dim.inferred_category, mappingRules);
+    
+    // 判断是否满足（核心标准：有修复策略）
+    const hasFix = strategyMatch !== null && strategyMatch.strategies.length > 0;
+    
+    return {
+      dimension_id: dim.id,
+      taxonomy_match: taxonomyMatch,
+      strategy_match: strategyMatch,
+      has_fix: hasFix,
+      needs_gemini_analysis: taxonomyMatch === null  // 无内置检测时需要 Gemini 深度分析
+    };
+  });
+}
+
+function findTaxonomyMatch(category, rules) {
+  const patternMapping = {
+    'context_explosion': { category: 'context_explosion', pattern_ids: ['CTX-001', 'CTX-002', 'CTX-003', 'CTX-004', 'CTX-005'], severity_hint: 'high' },
+    'memory_loss': { category: 'memory_loss', pattern_ids: ['MEM-001', 'MEM-002', 'MEM-003', 'MEM-004', 'MEM-005'], severity_hint: 'high' },
+    'dataflow_break': { category: 'dataflow_break', pattern_ids: ['DF-001', 'DF-002', 'DF-003', 'DF-004', 'DF-005'], severity_hint: 'critical' },
+    'agent_failure': { category: 'agent_failure', pattern_ids: ['AGT-001', 'AGT-002', 'AGT-003', 'AGT-004', 'AGT-005', 'AGT-006'], severity_hint: 'high' },
+    'performance': { category: 'performance', pattern_ids: ['CTX-001', 'CTX-003'], severity_hint: 'medium' },
+    'error_handling': { category: 'error_handling', pattern_ids: ['AGT-001', 'AGT-002'], severity_hint: 'medium' }
+  };
+  
+  return patternMapping[category] || null;
+}
+
+function findStrategyMatch(category, rules) {
+  const strategyMapping = {
+    'context_explosion': { strategies: ['sliding_window', 'path_reference', 'context_summarization', 'structured_state'], risk_levels: ['low', 'low', 'low', 'medium'] },
+    'memory_loss': { strategies: ['constraint_injection', 'state_constraints_field', 'checkpoint_restore', 'goal_embedding'], risk_levels: ['low', 'low', 'low', 'medium'] },
+    'dataflow_break': { strategies: ['state_centralization', 'schema_enforcement', 'field_normalization'], risk_levels: ['medium', 'low', 'low'] },
+    'agent_failure': { strategies: ['error_wrapping', 'result_validation', 'flatten_nesting'], risk_levels: ['low', 'low', 'medium'] },
+    'prompt_quality': { strategies: ['structured_prompt', 'output_schema', 'grounding_context', 'format_enforcement'], risk_levels: ['low', 'low', 'medium', 'low'] },
+    'architecture': { strategies: ['phase_decomposition', 'interface_contracts', 'plugin_architecture'], risk_levels: ['medium', 'medium', 'high'] },
+    'performance': { strategies: ['token_budgeting', 'parallel_execution', 'result_caching', 'lazy_loading'], risk_levels: ['low', 'low', 'low', 'low'] },
+    'error_handling': { strategies: ['graceful_degradation', 'error_propagation', 'structured_logging'], risk_levels: ['low', 'low', 'low'] },
+    'output_quality': { strategies: ['quality_gates', 'output_validation', 'template_enforcement'], risk_levels: ['low', 'low', 'low'] },
+    'user_experience': { strategies: ['progress_tracking', 'status_communication', 'interactive_checkpoints'], risk_levels: ['low', 'low', 'low'] }
+  };
+  
+  // Fallback to custom
+  return strategyMapping[category] || { strategies: ['custom'], risk_levels: ['medium'] };
+}
+```
+
+### Phase 3: 覆盖度评估
+
+评估所有维度的 Spec 覆盖情况：
+
+```javascript
+function evaluateCoverage(specMatches) {
+  const total = specMatches.length;
+  const withDetection = specMatches.filter(m => m.taxonomy_match !== null).length;
+  const withFix = specMatches.filter(m => m.has_fix).length;
+  
+  const rate = total > 0 ? Math.round((withFix / total) * 100) : 0;
+  
+  let status;
+  if (rate >= 80) {
+    status = 'satisfied';
+  } else if (rate >= 50) {
+    status = 'partial';
+  } else {
+    status = 'unsatisfied';
+  }
+  
+  return {
+    total_dimensions: total,
+    with_detection: withDetection,
+    with_fix_strategy: withFix,
+    coverage_rate: rate,
+    status: status
+  };
+}
+```
+
+### Phase 4: 歧义检测
+
+识别需要用户澄清的歧义点：
+
+```javascript
+function detectAmbiguities(dimensions, specMatches) {
+  const ambiguities = [];
+  
+  for (const dim of dimensions) {
+    const match = specMatches.find(m => m.dimension_id === dim.id);
+    
+    // 检测1: 低置信度 (< 0.5)
+    if (dim.confidence < 0.5) {
+      ambiguities.push({
+        dimension_id: dim.id,
+        type: 'vague_description',
+        description: `维度 "${dim.description}" 描述模糊，推断置信度低 (${dim.confidence})`,
+        possible_interpretations: suggestInterpretations(dim),
+        needs_clarification: true
+      });
+    }
+    
+    // 检测2: 无匹配类别
+    if (!match || (!match.taxonomy_match && !match.strategy_match)) {
+      ambiguities.push({
+        dimension_id: dim.id,
+        type: 'no_category_match',
+        description: `维度 "${dim.description}" 无法匹配到已知问题类别`,
+        possible_interpretations: ['custom'],
+        needs_clarification: true
+      });
+    }
+    
+    // 检测3: 关键词冲突（可能属于多个类别）
+    if (dim.keywords.length > 3 && hasConflictingKeywords(dim.keywords)) {
+      ambiguities.push({
+        dimension_id: dim.id,
+        type: 'conflicting_keywords',
+        description: `维度 "${dim.description}" 的关键词可能指向多个不同问题`,
+        possible_interpretations: inferMultipleCategories(dim.keywords),
+        needs_clarification: true
+      });
+    }
+  }
+  
+  return ambiguities;
+}
+
+function suggestInterpretations(dim) {
+  // 基于关键词推荐可能的解释
+  const categories = [
+    'context_explosion', 'memory_loss', 'dataflow_break', 'agent_failure',
+    'prompt_quality', 'architecture', 'performance', 'error_handling'
+  ];
+  return categories.slice(0, 4);  // 返回最常见的 4 个作为选项
+}
+
+function hasConflictingKeywords(keywords) {
+  // 检查关键词是否指向不同方向
+  const categoryHints = keywords.map(k => getKeywordCategoryHint(k));
+  const uniqueCategories = [...new Set(categoryHints.filter(c => c))];
+  return uniqueCategories.length > 1;
+}
+
+function getKeywordCategoryHint(keyword) {
+  const keywordMap = {
+    '慢': 'performance', 'slow': 'performance',
+    '遗忘': 'memory_loss', 'forget': 'memory_loss',
+    '状态': 'dataflow_break', 'state': 'dataflow_break',
+    'agent': 'agent_failure', '失败': 'agent_failure',
+    'token': 'context_explosion', '上下文': 'context_explosion'
+  };
+  return keywordMap[keyword.toLowerCase()];
+}
+```
+
+## User Interaction
+
+如果检测到需要澄清的歧义，暂停并询问用户：
+
+```javascript
+async function handleAmbiguities(ambiguities, dimensions) {
+  const needsClarification = ambiguities.filter(a => a.needs_clarification);
+  
+  if (needsClarification.length === 0) {
+    return null;  // 无需澄清
+  }
+  
+  const questions = needsClarification.slice(0, 4).map(a => {
+    const dim = dimensions.find(d => d.id === a.dimension_id);
+    
+    return {
+      question: `关于 "${dim.description}"，您具体指的是？`,
+      header: a.dimension_id,
+      options: a.possible_interpretations.map(interp => ({
+        label: getCategoryLabel(interp),
+        description: getCategoryDescription(interp)
+      })),
+      multiSelect: false
+    };
+  });
+  
+  return await AskUserQuestion({ questions });
+}
+
+function getCategoryLabel(category) {
+  const labels = {
+    'context_explosion': '上下文膨胀',
+    'memory_loss': '指令遗忘',
+    'dataflow_break': '数据流问题',
+    'agent_failure': 'Agent 协调问题',
+    'prompt_quality': '提示词质量',
+    'architecture': '架构问题',
+    'performance': '性能问题',
+    'error_handling': '错误处理',
+    'custom': '其他问题'
+  };
+  return labels[category] || category;
+}
+
+function getCategoryDescription(category) {
+  const descriptions = {
+    'context_explosion': 'Token 累积导致上下文过大',
+    'memory_loss': '早期指令或约束在后期丢失',
+    'dataflow_break': '状态数据在阶段间不一致',
+    'agent_failure': '子 Agent 调用失败或结果异常',
+    'prompt_quality': '提示词模糊导致输出不稳定',
+    'architecture': '阶段划分或模块结构不合理',
+    'performance': '执行慢或 Token 消耗高',
+    'error_handling': '错误恢复机制不完善',
+    'custom': '需要自定义分析的问题'
+  };
+  return descriptions[category] || '需要进一步分析';
+}
+```
+
+## Output
+
+### State Updates
+
+```javascript
+return {
+  stateUpdates: {
+    requirement_analysis: {
+      status: ambiguities.some(a => a.needs_clarification) ? 'needs_clarification' : 'completed',
+      analyzed_at: new Date().toISOString(),
+      dimensions: dimensions,
+      spec_matches: specMatches,
+      coverage: coverageResult,
+      ambiguities: ambiguities
+    },
+    // 根据分析结果自动优化 focus_areas
+    focus_areas: deriveOptimalFocusAreas(specMatches)
+  },
+  outputFiles: [
+    `${workDir}/requirement-analysis.json`,
+    `${workDir}/requirement-analysis.md`
+  ],
+  summary: generateSummary(dimensions, coverageResult, ambiguities)
+};
+
+function deriveOptimalFocusAreas(specMatches) {
+  const coreCategories = ['context', 'memory', 'dataflow', 'agent'];
+  const matched = specMatches
+    .filter(m => m.taxonomy_match !== null)
+    .map(m => {
+      // 映射到诊断 focus_area
+      const category = m.taxonomy_match.category;
+      if (category === 'context_explosion' || category === 'performance') return 'context';
+      if (category === 'memory_loss') return 'memory';
+      if (category === 'dataflow_break') return 'dataflow';
+      if (category === 'agent_failure' || category === 'error_handling') return 'agent';
+      return null;
+    })
+    .filter(f => f && coreCategories.includes(f));
+  
+  // 去重
+  return [...new Set(matched)];
+}
+
+function generateSummary(dimensions, coverage, ambiguities) {
+  const dimCount = dimensions.length;
+  const coverageStatus = coverage.status;
+  const ambiguityCount = ambiguities.filter(a => a.needs_clarification).length;
+  
+  let summary = `分析完成：${dimCount} 个维度`;
+  summary += `，覆盖度 ${coverage.coverage_rate}% (${coverageStatus})`;
+  
+  if (ambiguityCount > 0) {
+    summary += `，${ambiguityCount} 个歧义点待澄清`;
+  }
+  
+  return summary;
+}
+```
+
+### Output Files
+
+#### requirement-analysis.json
+
+```json
+{
+  "timestamp": "2024-01-01T00:00:00Z",
+  "target_skill": "skill-name",
+  "user_description": "原始用户描述",
+  "dimensions": [...],
+  "spec_matches": [...],
+  "coverage": {...},
+  "ambiguities": [...],
+  "derived_focus_areas": [...]
+}
+```
+
+#### requirement-analysis.md
+
+```markdown
+# 需求分析报告
+
+## 用户描述
+> ${user_issue_description}
+
+## 维度拆解
+
+| ID | 描述 | 类别 | 置信度 |
+|----|------|------|--------|
+| DIM-001 | ... | ... | 0.85 |
+
+## Spec 匹配
+
+| 维度 | 检测模式 | 修复策略 | 是否满足 |
+|------|----------|----------|----------|
+| DIM-001 | CTX-001,002 | sliding_window | ✓ |
+
+## 覆盖度评估
+
+- 总维度数: N
+- 有检测手段: M
+- 有修复策略: K (满足标准)
+- 覆盖率: X%
+- 状态: satisfied/partial/unsatisfied
+
+## 歧义点
+
+(如有)
+```
+
+## Error Handling
+
+| Error | Recovery |
+|-------|----------|
+| Gemini CLI 超时 | 重试一次，仍失败则使用简化分析 |
+| JSON 解析失败 | 尝试修复 JSON 或使用默认维度 |
+| 无法匹配任何类别 | 全部归类为 custom，触发 Gemini 深度分析 |
+
+## Next Actions
+
+- 如果 `requirement_analysis.status === 'completed'`: 继续到 `action-diagnose-*`
+- 如果 `requirement_analysis.status === 'needs_clarification'`: 等待用户澄清后重新执行
+- 如果 `coverage.status === 'unsatisfied'`: 自动触发 `action-gemini-analysis` 进行深度分析
--- a/.claude/skills/skill-tuning/phases/orchestrator.md
+++ b/.claude/skills/skill-tuning/phases/orchestrator.md
@@ -63,6 +63,24 @@ function selectNextAction(state) {
    return 'action-init';
  }

+  // 1.5. Requirement analysis (在 init 后，diagnosis 前)
+  if (state.status === 'running' &&
+      state.completed_actions.includes('action-init') &&
+      !state.completed_actions.includes('action-analyze-requirements')) {
+    return 'action-analyze-requirements';
+  }
+
+  // 1.6. 如果需求分析发现歧义需要澄清，暂停等待用户
+  if (state.requirement_analysis?.status === 'needs_clarification') {
+    return null;  // 等待用户澄清后继续
+  }
+
+  // 1.7. 如果需求分析覆盖度不足，优先触发 Gemini 深度分析
+  if (state.requirement_analysis?.coverage?.status === 'unsatisfied' &&
+      !state.completed_actions.includes('action-gemini-analysis')) {
+    return 'action-gemini-analysis';
+  }
+
  // 2. Check if Gemini analysis is requested or needed
  if (shouldTriggerGeminiAnalysis(state)) {
    return 'action-gemini-analysis';
@@ -295,6 +313,7 @@ After completing the action:
 | Action | Purpose | Preconditions | Effects |
 |--------|---------|---------------|---------|
 | [action-init](actions/action-init.md) | Initialize tuning session | status === 'pending' | Creates work dirs, backup, sets status='running' |
+| [action-analyze-requirements](actions/action-analyze-requirements.md) | Analyze user requirements | init completed | Sets requirement_analysis, optimizes focus_areas |
 | [action-diagnose-context](actions/action-diagnose-context.md) | Analyze context explosion | status === 'running' | Sets diagnosis.context |
 | [action-diagnose-memory](actions/action-diagnose-memory.md) | Analyze long-tail forgetting | status === 'running' | Sets diagnosis.memory |
 | [action-diagnose-dataflow](actions/action-diagnose-dataflow.md) | Analyze data flow issues | status === 'running' | Sets diagnosis.dataflow |
@@ -312,6 +331,7 @@ After completing the action:
 - `status === 'completed'`: Normal completion
 - `status === 'user_exit'`: User requested exit
 - `status === 'failed'`: Unrecoverable error
+- `requirement_analysis.status === 'needs_clarification'`: Waiting for user clarification (暂停，非终止)
 - `error_count >= max_errors`: Too many errors (default: 3)
 - `iteration_count >= max_iterations`: Max iterations reached (default: 5)
 - `quality_gate === 'pass'`: All quality criteria met
--- a/.claude/skills/skill-tuning/phases/state-schema.md
+++ b/.claude/skills/skill-tuning/phases/state-schema.md
@@ -67,6 +67,62 @@ interface TuningState {
  // === Output Paths ===
  work_dir: string;
  backup_dir: string;
+
+  // === Requirement Analysis (新增) ===
+  requirement_analysis: RequirementAnalysis | null;
+}
+
+interface RequirementAnalysis {
+  status: 'pending' | 'completed' | 'needs_clarification';
+  analyzed_at: string;
+
+  // Phase 1: 维度拆解
+  dimensions: Dimension[];
+
+  // Phase 2: Spec 匹配
+  spec_matches: SpecMatch[];
+
+  // Phase 3: 覆盖度
+  coverage: {
+    total_dimensions: number;
+    with_detection: number;      // 有 taxonomy pattern
+    with_fix_strategy: number;   // 有 tuning strategy (满足判断标准)
+    coverage_rate: number;       // 0-100%
+    status: 'satisfied' | 'partial' | 'unsatisfied';
+  };
+
+  // Phase 4: 歧义
+  ambiguities: Ambiguity[];
+}
+
+interface Dimension {
+  id: string;                    // e.g., "DIM-001"
+  description: string;           // 关注点描述
+  keywords: string[];            // 关键词
+  inferred_category: string;     // 推断的问题类别
+  confidence: number;            // 置信度 0-1
+}
+
+interface SpecMatch {
+  dimension_id: string;
+  taxonomy_match: {
+    category: string;            // e.g., "context_explosion"
+    pattern_ids: string[];       // e.g., ["CTX-001", "CTX-003"]
+    severity_hint: string;
+  } | null;
+  strategy_match: {
+    strategies: string[];        // e.g., ["sliding_window", "path_reference"]
+    risk_levels: string[];
+  } | null;
+  has_fix: boolean;              // 满足性判断核心
+}
+
+interface Ambiguity {
+  dimension_id: string;
+  type: 'multi_category' | 'vague_description' | 'conflicting_keywords';
+  description: string;
+  possible_interpretations: string[];
+  needs_clarification: boolean;
 }

 interface DiagnosisResult {
@@ -208,7 +264,8 @@ interface ErrorEntry {
  "error_count": 0,
  "max_errors": 3,
  "work_dir": null,
-  "backup_dir": null
+  "backup_dir": null,
+  "requirement_analysis": null
 }
 ```