@chongyan/autospec 1.0.2 → 1.0.3

package/knowledge/03-guides/32-analyze-ai-agent.md

@@ -1,362 +0,0 @@
----
-name: agent-analyzer
-description: 当检测到Agent框架依赖时，分析Agent的能力、工具和架构。用于理解AI智能体系统的结构。
-type: ai
----
-
-## 定位
-
-AI专用技能。分析Agent的能力、可用工具、决策逻辑和协作关系。
-
-## 输入
-
-- 必须输入：Agent代码路径或项目目录
-- 可选输入：框架类型（langchain/crewai/autogen等）
-
-## 输出
-
-```json
-{
-  "framework": "langchain",
-  "agents": [
-    {
-      "name": "ResearchAgent",
-      "role": "信息收集",
-      "description": "负责从网络和文档中收集信息",
-      "tools": [
-        {"name": "web_search", "description": "网络搜索"},
-        {"name": "document_reader", "description": "文档读取"}
-      ],
-      "decisionLogic": "ReAct",
-      "llmConfig": {
-        "model": "gpt-4",
-        "temperature": 0.7
-      },
-      "collaborators": ["WriterAgent"]
-    },
-    {
-      "name": "WriterAgent",
-      "role": "内容生成",
-      "description": "负责根据收集的信息生成内容",
-      "tools": [
-        {"name": "write_file", "description": "写入文件"}
-      ],
-      "decisionLogic": "Plan-Execute",
-      "collaborators": ["ResearchAgent"]
-    }
-  ],
-  "orchestration": {
-    "type": "sequential",
-    "description": "Agent按顺序执行：ResearchAgent → WriterAgent"
-  },
-  "evaluationNeeds": {
-    "dimensions": ["任务完成率", "响应质量", "工具使用正确性"],
-    "suggestions": [
-      "建议测试Agent能否正确使用工具",
-      "建议测试多Agent协作是否正常"
-    ]
-  }
-}
-```
-
-## 执行步骤
-
-### Step 1: 识别框架（确定性）
-
-基于依赖和代码特征识别Agent框架：
-
-```
-框架识别规则：
-- langchain: 依赖langchain，代码中有 Agent, Tool, Chain
-- crewai: 依赖crewai，代码中有 Agent, Crew, Task
-- autogen: 依赖autogen，代码中有 AssistantAgent, UserProxyAgent
-- semantic-kernel: 依赖semantic-kernel，代码中有 Kernel, Plugin
-```
-
-### Step 2: Grep获取Agent定义（高效）
-
-搜索Agent定义模式：
-
-```bash
-# LangChain风格
-grep -r -n -A 10 "Agent\|create_agent\|initialize_agent" --include="*.py" .
-
-# CrewAI风格
-grep -r -n -A 10 "@agent\|class.*Agent\|Agent(" --include="*.py" .
-
-# AutoGen风格
-grep -r -n -A 10 "AssistantAgent\|UserProxyAgent" --include="*.py" .
-```
-
-### Step 3: 分析Agent能力（模型）
-
-基于代码上下文分析Agent：
-
-```
-模型输入：
-{
-  "framework": "langchain",
-  "codeContexts": "
-    # agent.py
-    research_agent = Agent(
-      role='Researcher',
-      tools=[web_search, document_reader],
-      ...
-    )
-  ",
-  "task": "分析Agent的能力、工具、决策逻辑，输出JSON格式"
-}
-```
-
-### Step 4: 分析协作关系（模型）
-
-分析Agent之间的协作：
-
-```
-关注点：
-- Agent之间如何通信
-- 执行顺序（顺序/并行/条件）
-- 共享状态如何管理
-```
-
-### Step 5: 输出结果
-
-汇总Agent分析结果，包括评测建议。
-
-## 工作流模式
-
-根据业界最佳实践，识别以下工作流模式：
-
-### 工作流 vs Agent
-
-| 类型 | 说明 | 适用场景 |
-|------|------|----------|
-| **Workflow** | 预定义代码路径编排LLM和工具 | 确定性任务、可预测 |
-| **Agent** | LLM动态指导自己的流程和工具使用 | 开放性问题、需要灵活性 |
-
-### 工作流模式（从简单到复杂）
-
-| 模式 | 说明 | 适用场景 | 识别特征 |
-|------|------|----------|----------|
-| **Prompt Chaining** | 提示链，将任务分解为顺序步骤 | 任务可分解为固定子任务 | 多步骤LLM调用链 |
-| **Routing** | 路由，将输入分类到专用处理流程 | 复杂任务有明确分类 | 分类器+条件分支 |
-| **Parallelization** | 并行化，同时处理多个子任务 | 独立子任务可并行 | 多LLM调用+聚合 |
-| **Orchestrator-workers** | 编排器-工作者，中心LLM动态分配任务 | 复杂任务无法预知子任务 | 中心调度+动态分发 |
-| **Evaluator-optimizer** | 评估器-优化器，循环优化 | 有明确评估标准 | 生成-评估循环 |
-
-### Agent模式
-
-当LLM具备以下能力时使用Agent：
-- 理解复杂输入
-- 推理和规划
-- 可靠使用工具
-- 从错误中恢复
-
-Agent关键特征：
-- 从环境获取"ground truth"（工具调用结果、代码执行结果）
-- 在检查点暂停等待人类反馈
-- 包含停止条件（如最大迭代次数）
-
-## 工具设计原则
-
-工具设计应遵循以下原则（Agent-Computer Interface, ACI）：
-
-### 工具设计原则
-
-1. **给模型足够token思考**：避免模型在思考过程中被截断
-2. **格式接近自然文本**：让模型容易理解和生成
-3. **无格式化开销**：避免需要精确计数的格式
-4. **像对待HCI一样对待ACI**：投入同样多的精力设计工具接口
-
-### 工具设计检查清单
-
-```
-- [ ] 工具描述清晰，包含示例用法
-- [ ] 参数名称和描述直观
-- [ ] 边界情况有说明
-- [ ] 输入格式要求明确
-- [ ] 与其他工具边界清晰
-- [ ] 测试模型使用工具的错误模式
-- [ ] 使用绝对路径（避免相对路径错误）
-```
-
-## 决策逻辑类型
-
-| 类型 | 说明 | 特点 |
-|------|------|------|
-| **ReAct** | 推理-行动循环 | 每步思考后执行 |
-| **Plan-Execute** | 规划-执行 | 先规划全流程再执行 |
-| **Reflexion** | 反思改进 | 执行后反思优化 |
-| **MRKL** | 模块化推理 | 组合多个专家模块 |
-| **Evaluator-optimizer** | 评估-优化循环 | 基于反馈迭代改进 |
-
-## Agent可靠性设计检查
-
-根据最佳实践，检查Agent设计可靠性：
-
-### 必须检查项
-
-1. **停止条件**
-   - 是否有最大迭代次数限制？
-   - 是否有超时机制？
-   - 是否定义了明确的完成条件？
-
-2. **错误处理**
-   - 工具调用失败如何处理？
-   - 是否有重试机制？
-   - 错误是否可恢复？
-
-3. **检查点机制**
-   - 是否在关键步骤暂停等待确认？
-   - 是否有人类反馈回路？
-   - 是否记录决策点？
-
-4. **透明度**
-   - 是否显示Agent的规划步骤？
-   - 是否可追溯决策过程？
-   - 是否有日志记录？
-
-### 建议检查项
-
-1. **安全性**
-   - 是否有输入验证？
-   - 是否有输出过滤？
-   - 是否有访问控制？
-
-2. **可观测性**
-   - 是否记录每步的输入输出？
-   - 是否有性能指标？
-   - 是否有错误统计？
-
-## 增强的评估建议
-
-根据长时运行Agent测试的最佳实践：
-
-### 评估维度扩展
-
-| 维度 | 指标 | 方法 | 优先级 |
-|------|------|------|--------|
-| **任务完成率** | success_rate, completion_rate | 自动验证 | 高 |
-| **工具使用可靠性** | tool_call_success_rate, error_recovery_rate | 日志分析 | 高 |
-| **决策质量** | reasoning_quality, planning_accuracy | LLM评估 | 高 |
-| **透明度** | decision_traceability, human_oversight | 审计日志 | 中 |
-| **效率** | latency, token_usage, iteration_count | 自动统计 | 中 |
-| **安全性** | guardrail_pass_rate, input_validation | 红队测试 | 高 |
-
-### 长时运行Agent测试
-
-根据harness设计原则：
-
-1. **状态管理测试**
-   - Agent能否正确维护状态？
-   - 状态在长时间运行后是否一致？
-   - 状态恢复机制是否有效？
-
-2. **错误恢复测试**
-   - 工具调用失败后能否恢复？
-   - 是否有优雅降级机制？
-   - 错误累积是否导致失败？
-
-3. **资源管理测试**
-   - 内存使用是否可控？
-   - 是否有资源清理机制？
-   - 长时间运行是否性能下降？
-
-### AI-Resistant评估设计
-
-根据AI-Resistant评估设计原则：
-
-1. **防止评估数据泄露**
-   - 使用未见过的测试用例
-   - 动态生成评估数据
-   - 分离训练和评估数据
-
-2. **防止提示注入**
-   - 评估输入多样化
-   - 边界情况测试
-   - 对抗性测试
-
-3. **真实能力测试**
-   - 开放式任务评估
-   - 多步骤推理测试
-   - 实际场景模拟
-
-## 调用时机
-
-- 检测到Agent框架依赖时
-- AI功能开发前的设计阶段
-- 需要理解现有Agent系统时
-- 需要评估Agent可靠性时
-
-## 示例
-
-**输入**：
-```
-项目目录：/project
-框架：langchain（已检测到依赖）
-```
-
-**Grep搜索**：
-```
-找到文件：agents/researcher.py, agents/writer.py, main.py
-```
-
-**代码上下文**：
-```python
-# agents/researcher.py
-research_agent = Agent(
-    role="Researcher",
-    goal="收集相关信息",
-    tools=[WebSearchTool(), DocumentReaderTool()],
-    verbose=True
-)
-
-# agents/writer.py
-writer_agent = Agent(
-    role="Writer",
-    goal="生成内容",
-    tools=[FileWriterTool()],
-    verbose=True
-)
-
-# main.py
-crew = Crew(
-    agents=[research_agent, writer_agent],
-    tasks=[research_task, write_task],
-    process=Process.sequential
-)
-```
-
-**输出**：
-```json
-{
-  "framework": "langchain",
-  "agents": [
-    {
-      "name": "research_agent",
-      "role": "Researcher",
-      "tools": [
-        {"name": "WebSearchTool", "description": "网络搜索"},
-        {"name": "DocumentReaderTool", "description": "文档读取"}
-      ],
-      "decisionLogic": "ReAct"
-    },
-    {
-      "name": "writer_agent",
-      "role": "Writer",
-      "tools": [
-        {"name": "FileWriterTool", "description": "文件写入"}
-      ],
-      "decisionLogic": "ReAct"
-    }
-  ],
-  "orchestration": {
-    "type": "sequential",
-    "description": "顺序执行"
-  },
-  "evaluationNeeds": {
-    "dimensions": ["任务完成率", "工具使用正确性"],
-    "suggestions": ["测试Agent能否正确调用工具"]
-  }
-}
-```

package/knowledge/03-guides/33-analyze-ai-rag.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大小对检索效果的影响",
-      "测试问答准确性"
-    ]
-  }
-}
-```