@chongyan/autospec 1.0.1 → 1.0.3

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

@@ -1,219 +0,0 @@
----
-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

@@ -1,339 +0,0 @@
----
-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大小对检索效果的影响",
-      "测试问答准确性"
-    ]
-  }
-}
-```