@chongyan/autospec 1.0.1

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

@@ -0,0 +1,219 @@
+---
+name: ai-pipeline-evaluator
+description: 基于 Trace 日志生成流程评测报告
+type: review
+---
+
+## 定位
+
+基于过程指标 + 结果指标 + 路径指标，自动生成流程评测报告，识别改进机会，触发进化机制。
+
+## 输入
+
+- 必须输入：
+  - traceId: 流程追踪 ID
+- 可选输入：
+  - logs/: 相关日志文件
+  - metrics: 质量指标数据
+
+## 评测维度
+
+### 1. 过程指标 (权重 30%)
+
+| 指标 | 权重 | 说明 |
+|-----|------|------|
+| Layer1 首次通过率 | 25% | 代码质量 |
+| Layer2 首次通过率 | 20% | 设计质量 |
+| 人工介入率 | 15% | 自主能力（反向） |
+| 回退率 | 15% | 流程顺畅度（反向） |
+| 错误率 | 10% | 稳定性（反向） |
+| 阶段成功率 | 15% | 完成度 |
+
+### 2. 结果指标 (权重 40%)
+
+| 指标 | 权重 | 说明 |
+|-----|------|------|
+| 产出物平均评分 | 40% | 产出质量 |
+| 一致性评分 | 30% | 产物一致性 |
+| 结构完整性 | 30% | 规范遵循 |
+
+### 3. 路径指标 (权重 30%)
+
+| 指标 | 权重 | 说明 |
+|-----|------|------|
+| 流程合规性 | 30% | 规范遵循 |
+| 执行效率 | 25% | 资源利用 |
+| 决策质量 | 25% | 自主决策能力 |
+| 异常处理 | 20% | 容错能力 |
+
+## 输出格式
+
+```markdown
+# AutoSpec 流程评测报告
+
+## 执行摘要
+
+| 指标 | 值 |
+|-----|-----|
+| Trace ID | {{traceId}} |
+| 执行时间 | {{duration}} |
+| 综合评分 | {{overallScore}}/100 ({{grade}}) |
+
+## 过程指标
+
+### Layer1/Layer2 验证
+- Layer1 首次通过率: {{layer1FirstPassRate}}%
+- Layer2 首次通过率: {{layer2FirstPassRate}}%
+
+### 流程效率
+- 阶段成功率: {{stageSuccessRate}}%
+- 回退次数: {{rollbackCount}}
+- 人工介入次数: {{humanInterventionCount}}
+
+### 错误分析
+- 总错误数: {{errorCount}}
+- 错误类型分布: {{errorTypeDistribution}}
+
+## 结果指标
+
+### 产出物质量
+| 产出物 | 评分 | 主要问题 |
+|-------|------|---------|
+{{#artifacts}}
+| {{name}} | {{score}} | {{mainIssue}} |
+{{/artifacts}}
+
+### 一致性检测
+- 一致性问题数: {{consistencyIssues}}
+- 主要不一致类型: {{mainInconsistency}}
+
+## 路径指标
+
+### 流程合规性
+- 阶段路径: {{stagePath}}
+- 违规项: {{violations}}
+
+### 执行效率
+- 重复操作: {{repeatedOps}} 次
+- 工具使用效率: {{toolEfficiency}}%
+
+### 决策质量
+- 人工介入率: {{humanRate}}%
+- 自动决策成功率: {{autoSuccessRate}}%
+
+## 改进建议
+
+### 高优先级
+{{#highPrioritySuggestions}}
+- {{.}}
+{{/highPrioritySuggestions}}
+
+### 中优先级
+{{#mediumPrioritySuggestions}}
+- {{.}}
+{{/mediumPrioritySuggestions}}
+
+## 进化触发建议
+
+{{#evolutionTriggers}}
+- **{{type}}**: {{reason}}
+  - 建议行动: {{action}}
+{{/evolutionTriggers}}
+```
+
+## 执行步骤
+
+### Step 1: 收集数据
+
+```
+1. 读取 metrics.json
+2. 读取 trace 日志
+3. 读取产出物评测结果
+```
+
+### Step 2: 计算各维度分数
+
+```
+1. 计算过程指标分数
+2. 计算结果指标分数
+3. 计算路径指标分数
+```
+
+### Step 3: 计算综合评分
+
+```
+overallScore = process * 0.3 + result * 0.4 + path * 0.3
+grade = getGrade(overallScore)
+```
+
+### Step 4: 分析改进点
+
+```
+1. 识别低分维度
+2. 分析问题根因
+3. 生成改进建议
+```
+
+### Step 5: 检测进化触发
+
+```
+1. 检测重复错误模式
+2. 检测低效阶段
+3. 检测质量下降信号
+```
+
+### Step 6: 生成报告
+
+```
+1. 生成 Markdown 格式报告
+2. 保存到 .autospec/logs/evaluation/
+3. 更新 metrics.json
+```
+
+## 进化触发规则
+
+| 条件 | 触发动作 |
+|-----|---------|
+| 同类错误 >= 3 次 | 创建 practice-log |
+| 质量分数 < 70 | 触发 methodology 审查 |
+| 新模式识别 | 触发 skill 提案 |
+| 阶段效率持续低 | 触发 skill 优化 |
+
+## 与 metrics.json 的集成
+
+评测结果写入 metrics.json：
+
+```json
+{
+  "qualityScore": {
+    "overall": 85,
+    "grade": "B",
+    "breakdown": {
+      "process": { "score": 80 },
+      "result": { "score": 88 },
+      "path": { "score": 86 }
+    }
+  },
+  "evaluationReport": {
+    "path": ".autospec/logs/evaluation/eval-2026-03-24.md",
+    "generatedAt": "2026-03-24T10:00:00Z"
+  }
+}
+```
+
+## 适用场景
+
+- 流程结束时自动触发（Stop Hook）
+- 手动执行 `/autospec:evaluate`
+- 定期质量审计
+
+## 反模式清单 (DP7)
+
+1. **忽略上下文**：不考虑任务复杂度
+   - 检测：结合任务评估调整评分标准
+
+2. **建议不可执行**：建议过于笼统
+   - 检测：每个建议必须指向具体改进点
+
+3. **过度惩罚**：对所有问题都扣分
+   - 检测：区分关键问题和次要问题

package/knowledge/guides/support/ai-rag-analyzer.md

@@ -0,0 +1,339 @@
+---
+name: rag-analyzer
+description: 当检测到RAG应用组件时，分析RAG架构的检索策略、向量存储、文档处理流程。用于理解检索增强生成系统的结构。
+type: ai
+---
+
+## 定位
+
+AI专用技能。分析RAG应用的架构、检索策略、向量存储配置和文档处理流程。
+
+## 输入
+
+- 必须输入：RAG代码路径或项目目录
+- 可选输入：向量存储类型（已检测到的组件）
+
+## 输出
+
+```json
+{
+  "architecture": {
+    "type": "standard-rag",
+    "description": "标准RAG架构：文档加载 → 分块 → 向量化 → 存储 → 检索 → 生成"
+  },
+  "components": {
+    "documentLoader": {
+      "type": "PDFLoader",
+      "sources": ["local", "s3"],
+      "formats": ["pdf", "txt", "md"]
+    },
+    "textSplitter": {
+      "type": "RecursiveCharacterTextSplitter",
+      "chunkSize": 500,
+      "chunkOverlap": 50
+    },
+    "embeddings": {
+      "type": "OpenAIEmbeddings",
+      "model": "text-embedding-3-small",
+      "dimension": 1536
+    },
+    "vectorStore": {
+      "type": "ChromaDB",
+      "collection": "documents",
+      "persistDirectory": "./chroma_db"
+    },
+    "retriever": {
+      "type": "similarity",
+      "k": 4,
+      "scoreThreshold": 0.7
+    },
+    "llm": {
+      "type": "ChatOpenAI",
+      "model": "gpt-4",
+      "temperature": 0.1
+    }
+  },
+  "retrievalStrategy": {
+    "type": "similarity",
+    "enhancements": [],
+    "description": "基础相似度检索"
+  },
+  "generationConfig": {
+    "promptTemplate": "基于以下上下文回答问题：\n{context}\n\n问题：{question}",
+    "maxTokens": 1000
+  },
+  "evaluationNeeds": {
+    "dimensions": ["检索准确率", "回答相关性", "上下文利用率", "幻觉率"],
+    "suggestions": [
+      "建议测试检索召回率（Recall@K）",
+      "建议测试生成回答的准确性",
+      "建议测试不同查询类型的表现"
+    ]
+  }
+}
+```
+
+## 执行步骤
+
+### Step 1: 识别RAG框架（确定性）
+
+基于依赖和代码特征识别RAG框架：
+
+```
+框架识别规则：
+- langchain: 依赖langchain，代码中有 VectorStore, Retriever, Document
+- llamaindex: 依赖llamaindex，代码中有 Index, QueryEngine, Node
+- haystack: 依赖haystack，代码中有 Pipeline, DocumentStore
+- custom: 自定义RAG实现
+```
+
+### Step 2: Grep获取组件定义（高效）
+
+搜索RAG组件模式：
+
+```bash
+# LangChain风格
+grep -r -n -A 5 "VectorStore\|Retriever\|Document\|Embeddings" --include="*.py" .
+
+# LlamaIndex风格
+grep -r -n -A 5 "VectorStoreIndex\|QueryEngine\|NodeParser" --include="*.py" .
+
+# 文档加载
+grep -r -n -A 5 "Loader\|Document\|load\|split" --include="*.py" .
+```
+
+### Step 3: 分析组件配置（模型）
+
+基于代码上下文分析RAG组件：
+
+```
+模型输入：
+{
+  "framework": "langchain",
+  "codeContexts": "
+    # rag.py
+    vectorstore = Chroma.from_documents(
+      documents=splits,
+      embedding=OpenAIEmbeddings(),
+      persist_directory='./chroma_db'
+    )
+    retriever = vectorstore.as_retriever(
+      search_type='similarity',
+      k=4
+    )
+  ",
+  "task": "分析RAG组件配置，输出JSON格式"
+}
+```
+
+### Step 4: 分析检索策略（模型）
+
+分析检索增强策略：
+
+```
+关注点：
+- 基础检索：相似度、MMR、混合检索
+- 增强策略：重排序、查询改写、多查询
+- 过滤条件：元数据过滤、时间范围
+```
+
+### Step 5: 输出结果
+
+汇总RAG分析结果，包括评测建议。
+
+## Contextual Retrieval
+
+根据业界最佳实践，Contextual Retrieval技术：
+
+### 问题背景
+
+传统RAG在编码信息时移除上下文，导致系统无法从知识库中检索到相关信息。
+
+### 解决方案：Contextual Retrieval
+
+使用两种子技术：
+1. **Contextual Embeddings**：上下文嵌入
+2. **Contextual BM25**：上下文BM25
+
+**效果**：显著提升检索质量。
+
+### 何时使用
+
+- 知识库小于200,000 tokens（约500页）→ 直接使用长prompt
+- 使用prompt caching让成本更低
+
+### 检索策略类型
+
+| 类型 | 说明 | 适用场景 |
+|------|------|----------|
+| **similarity** | 相似度检索 | 简单问答 |
+| **mmr** | 最大边际相关性 | 多样性需求 |
+| **similarity_score_threshold** | 带阈值过滤 | 高精度需求 |
+| **hybrid** | 向量+关键词混合 | 精确匹配需求 |
+| **multi_query** | 多查询扩展 | 复杂问题 |
+| **rerank** | 重排序 | 高质量需求 |
+| **contextual** | 上下文增强检索 | 复杂文档检索 |
+
+## 分块策略优化
+
+分块策略优化：
+
+### 分块大小选择
+
+| 场景 | 建议chunk size | 理由 |
+|------|---------------|------|
+| 代码 | 100-200 tokens | 保持函数/类完整 |
+| 短文档 | 300-500 tokens | 保持语义完整 |
+| 长文档 | 500-1000 tokens | 平衡精度和覆盖 |
+| 复杂结构 | 可变大小 | 按章节/段落 |
+
+### 分块优化技术
+
+1. **重叠**：chunk_overlap建议为chunk_size的10-20%
+2. **父子索引**：小chunk用于检索，大chunk用于生成
+3. **元数据**：添加来源、标题、摘要等元数据
+4. **上下文前缀**：为每个chunk添加文档上下文
+
+## 向量存储选型原则
+
+| 场景 | 推荐选择 | 理由 |
+|------|----------|------|
+| 本地开发、轻量级 | 轻量级向量库 | 易于集成、无需额外服务 |
+| 生产环境、需要扩展 | 云端向量数据库 | 托管服务、自动扩展 |
+| 需要复杂过滤 | 高性能向量库 | 过滤能力强 |
+| 大规模数据 | 分布式方案 | 水平扩展能力 |
+
+## RAG评估维度
+
+扩展评估维度：
+
+### 检索质量评估
+
+| 指标 | 说明 | 测量方法 |
+|------|------|----------|
+| **Precision@K** | Top-K结果中相关文档比例 | 标注数据 |
+| **Recall@K** | 相关文档被召回的比例 | 标注数据 |
+| **MRR** | 第一个相关文档的排名倒数 | 自动计算 |
+| **NDCG** | 归一化折损累计增益 | 标注数据 |
+
+### 生成质量评估
+
+| 指标 | 说明 | 测量方法 |
+|------|------|----------|
+| **Context Relevance** | 检索内容与问题的相关程度 | LLM评估 |
+| **Answer Faithfulness** | 回答与检索内容的一致性 | LLM评估 |
+| **Answer Relevance** | 回答与问题的相关程度 | LLM评估 |
+| **Hallucination Rate** | 幻觉内容比例 | 事实核查 |
+
+### 上下文优化评估
+
+| 指标 | 说明 | 测量方法 |
+|------|------|----------|
+| **Context Utilization** | 模型利用检索内容的程度 | 日志分析 |
+| **Chunk Quality** | 分块是否保留完整语义 | 人工评估 |
+| **Retrieval Latency** | 检索延迟 | 自动统计 |
+
+## 调用时机
+
+- 检测到RAG应用组件时
+- AI功能开发前的设计阶段
+- 需要理解现有RAG系统时
+
+## 示例
+
+**输入**：
+```
+项目目录：/project
+向量存储：ChromaDB（已检测）
+LLM：OpenAI（已检测）
+```
+
+**Grep搜索**：
+```
+找到文件：rag/pipeline.py, rag/embeddings.py, rag/retriever.py
+```
+
+**代码上下文**：
+```python
+# rag/pipeline.py
+from langchain.document_loaders import PyPDFLoader
+from langchain.text_splitter import RecursiveCharacterTextSplitter
+from langchain.embeddings import OpenAIEmbeddings
+from langchain.vectorstores import Chroma
+from langchain.chains import RetrievalQA
+
+loader = PyPDFLoader("docs.pdf")
+documents = loader.load()
+
+text_splitter = RecursiveCharacterTextSplitter(
+    chunk_size=500,
+    chunk_overlap=50
+)
+splits = text_splitter.split_documents(documents)
+
+vectorstore = Chroma.from_documents(
+    documents=splits,
+    embedding=OpenAIEmbeddings(),
+    persist_directory="./chroma_db"
+)
+
+retriever = vectorstore.as_retriever(
+    search_type="similarity",
+    k=4
+)
+
+qa_chain = RetrievalQA.from_chain_type(
+    llm=ChatOpenAI(model="gpt-4"),
+    retriever=retriever,
+    return_source_documents=True
+)
+```
+
+**输出**：
+```json
+{
+  "architecture": {
+    "type": "standard-rag",
+    "description": "标准RAG：PDF加载 → 分块 → 向量化 → Chroma存储 → 相似度检索 → GPT-4生成"
+  },
+  "components": {
+    "documentLoader": {
+      "type": "PyPDFLoader",
+      "formats": ["pdf"]
+    },
+    "textSplitter": {
+      "type": "RecursiveCharacterTextSplitter",
+      "chunkSize": 500,
+      "chunkOverlap": 50
+    },
+    "embeddings": {
+      "type": "OpenAIEmbeddings"
+    },
+    "vectorStore": {
+      "type": "Chroma",
+      "persistDirectory": "./chroma_db"
+    },
+    "retriever": {
+      "type": "similarity",
+      "k": 4
+    },
+    "llm": {
+      "type": "ChatOpenAI",
+      "model": "gpt-4"
+    }
+  },
+  "retrievalStrategy": {
+    "type": "similarity",
+    "enhancements": [],
+    "description": "基础相似度检索，返回top-4文档"
+  },
+  "evaluationNeeds": {
+    "dimensions": ["检索准确率", "回答相关性", "来源引用准确性"],
+    "suggestions": [
+      "测试PDF文档的解析质量",
+      "测试不同chunk大小对检索效果的影响",
+      "测试问答准确性"
+    ]
+  }
+}
+```