@chongyan/autospec 1.0.1

package/knowledge/guides/support/ai-evaluation-planner.md

@@ -0,0 +1,374 @@
+---
+name: evaluation-planner
+description: 当项目包含需要效果评测的组件（模型训练、Agent、RAG等）时，规划评测方案。包括评测维度、数据集、指标和流程设计。
+type: ai
+---
+
+## 定位
+
+AI专用技能。为需要效果评测的AI组件规划评测方案，包括评测维度、数据集构建、指标选择和流程设计。
+
+## 输入
+
+- 必须输入：项目结构分析结果、已检测的AI组件
+- 可选输入：Agent分析结果、RAG分析结果
+
+## 输出
+
+```json
+{
+  "evaluationScope": {
+    "components": ["agent-framework", "rag-application"],
+    "priority": "high",
+    "reason": "Agent和RAG直接面向用户，效果影响用户体验"
+  },
+  "evaluationPlan": [
+    {
+      "component": "ResearchAgent",
+      "type": "agent",
+      "dimensions": [
+        {
+          "name": "任务完成率",
+          "description": "Agent是否正确完成指定任务",
+          "metrics": ["success_rate", "error_rate"],
+          "method": "人工评估或自动验证"
+        },
+        {
+          "name": "工具使用正确性",
+          "description": "Agent是否正确选择和使用工具",
+          "metrics": ["tool_selection_accuracy", "tool_call_success_rate"],
+          "method": "日志分析"
+        },
+        {
+          "name": "响应质量",
+          "description": "Agent输出内容的质量",
+          "metrics": ["relevance_score", "helpfulness_score"],
+          "method": "LLM-as-Judge或人工评估"
+        }
+      ],
+      "dataset": {
+        "type": "synthetic",
+        "size": 100,
+        "generationMethod": "基于真实场景生成测试用例"
+      },
+      "process": {
+        "steps": [
+          "1. 准备测试用例数据集",
+          "2. 运行Agent执行任务",
+          "3. 收集执行日志和输出",
+          "4. 自动计算可量化指标",
+          "5. LLM-as-Judge评估响应质量",
+          "6. 人工抽检验证"
+        ]
+      }
+    },
+    {
+      "component": "RAG系统",
+      "type": "rag",
+      "dimensions": [
+        {
+          "name": "检索准确率",
+          "description": "检索到的文档是否相关",
+          "metrics": ["precision@k", "recall@k", "mrr"],
+          "method": "标注数据集评估"
+        },
+        {
+          "name": "回答相关性",
+          "description": "生成回答是否回答了问题",
+          "metrics": ["relevance_score", "faithfulness_score"],
+          "method": "LLM-as-Judge"
+        },
+        {
+          "name": "幻觉率",
+          "description": "回答是否包含虚假信息",
+          "metrics": ["hallucination_rate", "groundedness_score"],
+          "method": "事实核查"
+        }
+      ],
+      "dataset": {
+        "type": "curated",
+        "size": 50,
+        "generationMethod": "人工构建问答对"
+      },
+      "process": {
+        "steps": [
+          "1. 构建评测问答数据集",
+          "2. 运行RAG系统生成回答",
+          "3. 计算检索指标",
+          "4. LLM评估回答质量",
+          "5. 人工抽检幻觉问题"
+        ]
+      }
+    }
+  ],
+  "tools": {
+    "suggested": ["ragas", "deepeval", "arize-phoenix"],
+    "reason": "这些工具支持RAG和Agent评测，与LangChain集成良好"
+  },
+  "timeline": {
+    "estimated": "2-3天",
+    "breakdown": {
+      "dataset_preparation": "0.5天",
+      "evaluation_implementation": "1天",
+      "execution_and_analysis": "0.5-1天"
+    }
+  }
+}
+```
+
+## 执行步骤
+
+### Step 1: 确定评测范围（确定性）
+
+基于检测结果确定需要评测的组件：
+
+```
+评测触发条件：
+- needsEvaluation = true 的组件
+- 组件类型：model-training, inference-service, llm-application, agent-framework, rag-application
+```
+
+### Step 2: 分析组件特性（模型）
+
+分析每个组件的评测需求：
+
+```
+模型输入：
+{
+  "components": [
+    {"type": "agent-framework", "name": "ResearchAgent", "tools": ["web_search", "doc_reader"]},
+    {"type": "rag-application", "vectorStore": "ChromaDB", "retriever": "similarity"}
+  ],
+  "task": "为每个组件确定评测维度和指标"
+}
+```
+
+### Step 3: 设计评测维度（模型）
+
+基于组件类型设计评测维度：
+
+```
+Agent评测维度：
+- 任务完成率：是否完成指定任务
+- 工具使用：是否正确选择和使用工具
+- 推理能力：决策逻辑是否合理
+- 响应质量：输出是否有帮助
+
+RAG评测维度：
+- 检索质量：召回率、精确率、MRR
+- 生成质量：相关性、准确性、流畅性
+- 上下文利用：是否有效使用检索内容
+- 幻觉检测：是否存在虚假信息
+
+模型评测维度：
+- 准确性：Accuracy、F1、AUC
+- 性能：延迟、吞吐量
+- 鲁棒性：边界情况表现
+- 公平性：不同群体表现差异
+```
+
+### Step 4: 规划数据集（模型）
+
+设计评测数据集：
+
+```
+数据集类型：
+- synthetic: 合成数据（LLM生成）
+- curated: 人工构建
+- production: 生产数据采样
+- benchmark: 公开基准数据集
+
+考虑因素：
+- 数据量：平衡成本和统计显著性
+- 覆盖度：覆盖主要使用场景
+- 多样性：包含边界情况
+```
+
+### Step 5: 选择工具（确定性 + 模型）
+
+推荐评测工具：
+
+```
+确定性规则：
+- RAG评测 → ragas, deepeval, trulens
+- Agent评测 → langsmith, arize-phoenix
+- 模型评测 → mlflow, wandb, evaluate
+
+模型判断：
+- 根据项目技术栈选择兼容工具
+- 根据评测维度选择支持工具
+```
+
+### Step 6: 输出结果
+
+汇总评测方案，包括维度、数据集、工具和时间估算。
+
+## 评测设计
+
+根据业界最佳实践：
+
+### 评测结构
+
+**评估(eval)** = 给AI一个输入 + 应用评分逻辑到输出测量成功
+
+### 单轮 vs 多轮评测
+
+| 类型 | 说明 | 适用场景 |
+|------|------|----------|
+| **单轮评测** | 提示 → 响应 → 评分 | 简单任务、LLM非Agent场景 |
+| **多轮评测** | 多步交互、工具调用、状态修改 | Agent、复杂任务 |
+
+### Agent评测最佳实践
+
+1. **匹配系统复杂度**
+   - 简单Agent：单轮评测
+   - 复杂Agent：多轮评测 + 工具调用验证
+
+2. **评测维度**
+   - 任务完成率（自动验证）
+   - 工具使用正确性（日志分析）
+   - 决策质量（LLM评估）
+   - 效率（延迟、token消耗）
+
+3. **评分逻辑设计**
+   - 精确匹配：用于有明确答案的任务
+   - LLM-as-Judge：用于开放式任务
+   - 规则引擎：用于结构化输出
+
+### AI-Resistant评估设计
+
+根据AI-Resistant评估设计原则：
+
+1. **防止数据泄露**
+   - 使用未见过的测试用例
+   - 动态生成评估数据
+   - 分离训练和评估数据
+
+2. **防止提示注入**
+   - 评估输入多样化
+   - 边界情况测试
+
+3. **真实能力测试**
+   - 开放式任务评估
+   - 多步骤推理测试
+   - 实际场景模拟
+
+### 基础设施噪声控制
+
+根据基础设施噪声控制原则：
+
+1. **识别噪声来源**
+   - 环境差异（操作系统、依赖版本）
+   - 并发干扰
+   - 网络延迟
+
+2. **控制方法**
+   - 隔离测试环境
+   - 多次运行取中位数
+   - 记录和排除异常值
+
+## 评测维度模板
+
+### Agent评测
+
+| 维度 | 指标 | 方法 |
+|------|------|------|
+| 任务完成率 | success_rate, error_rate | 自动验证 |
+| 工具使用 | tool_accuracy, call_success | 日志分析 |
+| 推理质量 | reasoning_score | LLM评估 |
+| 响应质量 | relevance, helpfulness | LLM/人工评估 |
+| 效率 | latency, token_usage | 自动统计 |
+| **决策透明度** | decision_traceability | 审计日志 |
+| **错误恢复** | error_recovery_rate | 故障注入测试 |
+
+### RAG评测
+
+| 维度 | 指标 | 方法 |
+|------|------|------|
+| 检索质量 | precision@k, recall@k, MRR | 标注数据 |
+| 上下文相关性 | context_relevance | LLM评估 |
+| 忠实度 | faithfulness, groundedness | LLM评估 |
+| 回答相关性 | answer_relevance | LLM评估 |
+| 幻觉率 | hallucination_rate | 事实核查 |
+| **检索延迟** | retrieval_latency | 自动统计 |
+
+### 模型评测
+
+| 维度 | 指标 | 方法 |
+|------|------|------|
+| 准确性 | Accuracy, F1, AUC, BLEU, ROUGE | 自动计算 |
+| 性能 | Latency, Throughput | 压测 |
+| 鲁棒性 | Edge case accuracy | 边界测试 |
+| 公平性 | Demographic parity | 分组统计 |
+| **AI-Resistance** | unseen_test_performance | 未知数据测试 |
+
+## 调用时机
+
+- 检测到需要评测的AI组件时
+- 设计阶段规划评测方案
+- 交付前确认评测覆盖
+
+## 示例
+
+**输入**：
+```json
+{
+  "components": [
+    {"name": "ResearchAgent", "type": "agent-framework", "needsEvaluation": true},
+    {"name": "RAG系统", "type": "rag-application", "needsEvaluation": true}
+  ],
+  "techStack": ["langchain", "openai", "chromadb"]
+}
+```
+
+**输出**：
+```json
+{
+  "evaluationScope": {
+    "components": ["ResearchAgent", "RAG系统"],
+    "priority": "high"
+  },
+  "evaluationPlan": [
+    {
+      "component": "ResearchAgent",
+      "type": "agent",
+      "dimensions": [
+        {"name": "任务完成率", "metrics": ["success_rate"], "method": "自动验证"},
+        {"name": "工具使用正确性", "metrics": ["tool_accuracy"], "method": "日志分析"},
+        {"name": "响应质量", "metrics": ["relevance_score"], "method": "LLM-as-Judge"}
+      ],
+      "dataset": {
+        "type": "synthetic",
+        "size": 50,
+        "generationMethod": "生成研究任务测试用例"
+      }
+    },
+    {
+      "component": "RAG系统",
+      "type": "rag",
+      "dimensions": [
+        {"name": "检索准确率", "metrics": ["recall@4", "mrr"], "method": "标注评估"},
+        {"name": "回答相关性", "metrics": ["relevance"], "method": "LLM-as-Judge"},
+        {"name": "幻觉率", "metrics": ["hallucination_rate"], "method": "事实核查"}
+      ],
+      "dataset": {
+        "type": "curated",
+        "size": 30,
+        "generationMethod": "人工构建问答对"
+      }
+    }
+  ],
+  "tools": {
+    "suggested": ["ragas", "langsmith"],
+    "reason": "与LangChain集成良好，支持Agent和RAG评测"
+  },
+  "timeline": {
+    "estimated": "2天",
+    "breakdown": {
+      "dataset_preparation": "0.5天",
+      "evaluation_implementation": "1天",
+      "execution_and_analysis": "0.5天"
+    }
+  }
+}
+```

package/knowledge/guides/support/ai-path-evaluator.md

@@ -0,0 +1,274 @@
+---
+name: ai-path-evaluator
+description: AI 分析执行路径，评估 SDD 引导效果
+type: review
+---
+
+## 定位
+
+分析执行路径数据，评估 Spec-driven development (SDD) 的引导效果，识别框架改进机会。
+
+## 核心价值
+
+通过分析执行路径，量化评估框架是否有效引导 AI 按规范执行开发流程，为框架迭代提供数据支撑。
+
+## 输入
+
+- 必须输入：
+  - traceId: 流程追踪 ID
+  - executionPath: 执行路径数据
+- 可选输入：
+  - metrics: 质量指标数据
+  - frameworkRules: 框架规则定义
+
+## 评测维度
+
+### 1. 流程合规性 (权重 30%)
+
+评估执行路径是否符合框架定义的流程规范。
+
+**检查项**：
+- [ ] 阶段顺序是否正确（需求→设计→实现→测试→交付）
+- [ ] 必要阶段是否执行
+- [ ] 双层验证是否执行
+- [ ] 门禁检查是否通过
+
+**评分规则**：
+```javascript
+score = 100;
+// 阶段顺序违规扣分
+if (stageOrderViolation) score -= 20;
+// 缺失必要阶段扣分
+score -= missingStages.length * 15;
+// 未执行 Layer1 扣分
+if (!hasLayer1Execution) score -= 30;
+// 门禁阻止率影响
+score -= gateBlockedRate * 10;
+```
+
+### 2. 执行效率 (权重 25%)
+
+评估执行路径是否高效，识别浪费和重复。
+
+**检查项**：
+- [ ] 重复操作检测
+- [ ] 无效操作检测
+- [ ] 阶段耗时分析
+- [ ] 工具使用效率
+
+**评分规则**：
+```javascript
+score = 100;
+// 重复操作扣分
+score -= repeatedOperations.length * 5;
+// 回退次数扣分
+score -= rollbackCount * 5;
+// 工具调用效率
+efficiency = uniqueTools / totalToolCalls;
+score *= efficiency;
+```
+
+### 3. 决策质量 (权重 25%)
+
+评估决策点的合理性，反映框架的自主能力。
+
+**检查项**：
+- [ ] 人工介入必要性分析
+- [ ] 自动决策成功率
+- [ ] 决策类型分布
+
+**评分规则**：
+```javascript
+score = 100;
+// 人工介入率（越低越好）
+humanRate = humanDecisions / totalDecisions;
+score -= humanRate * 30;
+// 自动决策成功率
+score += autoDecisionSuccessRate * 20;
+```
+
+### 4. 异常处理 (权重 20%)
+
+评估异常情况处理是否得当。
+
+**检查项**：
+- [ ] 异常类型分布
+- [ ] 恢复成功率
+- [ ] 升级合理性
+
+**评分规则**：
+```javascript
+score = 100;
+// 恢复率加分
+score *= recoveryRate;
+// 升级率合理时不扣分
+if (escalateRate > 0.3) score -= 10;
+```
+
+## 输出格式
+
+```json
+{
+  "overallScore": 84,
+  "grade": "B",
+  "dimensions": {
+    "compliance": {
+      "score": 95,
+      "violations": [],
+      "strengths": ["阶段顺序正确", "双层验证完整"]
+    },
+    "efficiency": {
+      "score": 80,
+      "repeatedOps": 3,
+      "wastedOps": 1,
+      "suggestions": ["减少重复的 Read 操作"]
+    },
+    "decision": {
+      "score": 85,
+      "humanRate": 0.25,
+      "autoSuccessRate": 0.9,
+      "analysis": "人工介入主要集中在设计决策点"
+    },
+    "exception": {
+      "score": 75,
+      "recoveryRate": 0.8,
+      "escalateCount": 1,
+      "analysis": "大部分异常成功恢复"
+    }
+  },
+  "sddGuidanceEffect": {
+    "score": 82,
+    "analysis": "框架引导效果良好，AI 基本按规范执行",
+    "improvementAreas": [
+      "设计阶段的决策点可进一步自动化",
+      "减少重复操作的建议机制"
+    ]
+  },
+  "recommendations": [
+    {
+      "priority": "high",
+      "area": "efficiency",
+      "suggestion": "实现 Read 结果缓存，减少重复读取"
+    }
+  ]
+}
+```
+
+## 执行步骤
+
+### Step 1: 加载执行路径数据
+
+```
+1. 从 metrics.json 读取 executionPath
+2. 从 trace 日志读取详细事件
+3. 加载框架规则定义
+```
+
+### Step 2: 分析流程合规性
+
+```
+1. 检查阶段序列是否符合预期
+2. 检查必要阶段是否执行
+3. 检查双层验证执行情况
+4. 统计门禁通过/阻止情况
+```
+
+### Step 3: 分析执行效率
+
+```
+1. 检测重复操作（相同操作 >= 3 次）
+2. 检测无效操作（回退后的重做）
+3. 分析工具调用分布
+4. 计算效率指标
+```
+
+### Step 4: 分析决策质量
+
+```
+1. 统计决策类型分布
+2. 分析人工介入必要性
+3. 评估自动决策成功率
+4. 识别可自动化的决策点
+```
+
+### Step 5: 分析异常处理
+
+```
+1. 统计异常类型分布
+2. 计算恢复成功率
+3. 分析升级合理性
+4. 识别异常模式
+```
+
+### Step 6: 综合评估 SDD 引导效果
+
+```
+1. 汇总各维度评分
+2. 分析框架引导的成功点
+3. 识别需要改进的环节
+4. 生成改进建议
+```
+
+### Step 7: 输出报告
+
+```
+1. 输出结构化 JSON 结果
+2. 更新 metrics.json 的 pathEvaluation
+3. 触发进化机制（如有必要）
+```
+
+## SDD 引导效果评估标准
+
+| 分数范围 | 等级 | 引导效果 | 说明 |
+|---------|------|---------|------|
+| 90-100 | A | 优秀 | AI 完全按规范执行，极少人工介入 |
+| 80-89 | B | 良好 | AI 基本按规范执行，少量人工纠正 |
+| 70-79 | C | 一般 | AI 部分偏离规范，需要较多人工干预 |
+| 60-69 | D | 较差 | AI 经常偏离规范，人工干预频繁 |
+| <60 | F | 失败 | 框架引导失效，需要重新设计 |
+
+## 进化触发规则
+
+基于路径评测结果，自动触发进化机制：
+
+1. **合规性问题**：连续 3 次出现相同违规 → 更新 constitution 或 skill
+2. **效率问题**：重复操作模式出现 5 次 → 新增优化 skill
+3. **决策问题**：人工介入率 > 50% → 优化决策自动化
+4. **异常问题**：恢复率 < 60% → 增强异常处理机制
+
+## 与 metrics.json 的集成
+
+评估完成后，更新 metrics.json：
+
+```json
+{
+  "pathEvaluation": {
+    "compliance": { "score": 95, "violations": [] },
+    "efficiency": { "score": 80, "repeatedOps": 3 },
+    "decision": { "score": 85, "humanRate": 0.25 },
+    "exception": { "score": 75, "recoveryRate": 0.8 },
+    "overall": 84,
+    "evaluatedAt": "2026-03-24T10:00:00Z"
+  }
+}
+```
+
+## 适用场景
+
+- 流程结束时自动触发（Stop Hook）
+- 手动执行 `/evaluate`
+- 进化机制定期分析
+
+## 反模式清单 (DP7)
+
+1. **只看结果不看过程**：忽略执行路径中的细节
+   - 检测：必须分析具体事件序列
+
+2. **过度惩罚人工介入**：认为所有人工介入都是框架问题
+   - 检测：区分必要和非必要人工介入
+
+3. **忽略上下文**：不考虑任务复杂度
+   - 检测：结合任务复杂度调整评分标准
+
+4. **建议过于笼统**：没有具体可执行的改进建议
+   - 检测：每个建议必须指向具体的改进点