@chongyan/autospec 1.0.2 → 1.0.3

package/knowledge/03-guides/36-evaluate-ai-artifact.md

@@ -1,192 +0,0 @@
----
-name: ai-artifact-evaluator
-description: AI 评估产出物质量，生成结构化评分和改进建议
-type: review
----
-
-## 定位
-
-对各类产出物进行深度质量评估，补充自动化检查无法覆盖的质量判断。
-
-## 与现有技能的关系
-
-- **复用**：consistency-checker.md 的六维检测能力
-- **增强**：新增结构化评分输出
-- **新增**：下游反馈追踪机制
-
-## 输入
-
-- 必须输入：
-  - artifactPath: 产出物路径
-  - artifactType: 产出物类型 (REQUIREMENT | DESIGN | CODE | REVIEW | TEST)
-- 可选输入：
-  - context: 相关上下文（上游产物、历史案例）
-  - evalConfig: 评测配置
-
-## 评估维度
-
-### 需求文档 (REQUIREMENT)
-
-| 维度 | 权重 | 评估要点 |
-|-----|------|---------|
-| 清晰度 | 30% | 需求描述是否明确无歧义 |
-| 完整性 | 25% | 是否覆盖所有业务场景 |
-| 可测试性 | 25% | 验收标准是否可转化为测试 |
-| 边界覆盖 | 20% | 是否考虑异常场景 |
-
-### 设计文档 (DESIGN)
-
-| 维度 | 权重 | 评估要点 |
-|-----|------|---------|
-| 合理性 | 30% | 架构设计是否合理 |
-| 覆盖度 | 25% | 是否覆盖所有需求点 |
-| 可实现性 | 25% | 技术方案是否可行 |
-| 接口完整性 | 20% | API 定义是否完整 |
-
-### 代码审查报告 (REVIEW)
-
-| 维度 | 权重 | 评估要点 |
-|-----|------|---------|
-| 问题真实性 | 35% | 发现的问题是否真实存在 |
-| 建议可执行性 | 30% | 修复建议是否具体可行 |
-| 覆盖全面性 | 20% | 是否覆盖关键模块 |
-| 深度 | 15% | 分析是否深入 |
-
-## 输出格式
-
-```json
-{
-  "score": 85,
-  "grade": "B",
-  "dimensions": {
-    "clarity": {
-      "score": 90,
-      "issues": [],
-      "strengths": ["需求描述清晰", "验收标准明确"]
-    },
-    "completeness": {
-      "score": 80,
-      "issues": ["缺少异常场景描述"],
-      "strengths": ["覆盖主要业务流程"]
-    }
-  },
-  "improvements": [
-    {
-      "priority": "high",
-      "area": "completeness",
-      "suggestion": "补充异常场景处理：用户取消操作、网络超时等",
-      "example": "建议添加：当用户取消支付时，系统应..."
-    }
-  ],
-  "comparisonWithHistory": {
-    "betterThan": 0.75,
-    "comment": "质量优于 75% 的历史同类产出物"
-  },
-  "confidence": 0.85
-}
-```
-
-## 执行步骤
-
-### Step 1: 读取产出物
-
-```
-1. 读取指定路径的产出物内容
-2. 识别产出物类型
-3. 加载对应的评估维度配置
-```
-
-### Step 2: 读取上下文
-
-```
-1. 如果是设计文档，读取对应的需求文档作为上下文
-2. 如果是审查报告，读取被审查的代码/文档
-3. 加载历史优秀案例（如有）
-```
-
-### Step 3: 分维度评估
-
-```
-对每个评估维度：
-1. 分析产出物在该维度的表现
-2. 识别具体问题和优点
-3. 给出 0-100 的评分
-4. 记录评估依据
-```
-
-### Step 4: 计算综合评分
-
-```
-1. 按权重计算各维度得分
-2. 汇总为综合评分
-3. 确定等级 (A/B/C/D/F)
-```
-
-### Step 5: 生成改进建议
-
-```
-1. 按优先级排序改进建议
-2. 每个建议包含：
-   - 优先级
-   - 改进领域
-   - 具体建议
-   - 示例（如适用）
-```
-
-### Step 6: 输出结果
-
-```
-1. 输出结构化 JSON 结果
-2. 将结果写入 metrics.json
-```
-
-## 反模式清单 (DP7)
-
-1. **无依据评分**：没有具体分析就给出分数
-   - 检测：每个评分必须有 issues 或 strengths 支撑
-
-2. **过于宽松**：所有评分都很高，没有改进空间
-   - 检测：必须有至少一个改进建议
-
-3. **建议不可执行**：建议过于笼统
-   - 检测：每个建议必须有具体的改进方向
-
-4. **忽略上下文**：评估设计时不考虑需求
-   - 检测：必须引用上游产物进行覆盖度分析
-
-## 采样策略
-
-| 场景 | 执行策略 |
-|-----|---------|
-| 首次生成 | 必评（建立基线） |
-| 后续生成 | 30% 采样 |
-| 低分产物 (<70) | 100% 重评 |
-| 人工标记 | 100% 评估 |
-
-## 与 metrics.json 的集成
-
-评估完成后，更新 metrics.json：
-
-```json
-{
-  "artifacts": {
-    "requirement.md": {
-      "evaluations": {
-        "quality": {
-          "score": 85,
-          "grade": "B",
-          "dimensions": {...},
-          "improvements": [...],
-          "evaluatedAt": "2026-03-24T10:00:00Z"
-        }
-      }
-    }
-  }
-}
-```
-
-## 适用场景
-
-- 产出物生成后自动触发
-- 手动执行 `/autospec:evaluate`
-- 低分产出物重评

package/knowledge/03-guides/37-plan-ai-evaluation.md

@@ -1,374 +0,0 @@
----
-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天"
-    }
-  }
-}
-```