@colin4k1024/tsp 2.4.0

package/skills/agent-patterns-catalog/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: agent-patterns-catalog
+description: >
+  AI Agent 架构模式目录。提供 ReAct、Multi-Agent Conversation、Multi-Agent Workflow、
+  RAG Agent、Tool-Use Agent、Autonomous Agent 六种核心模式的参考架构、组件拓扑、
+  数据流、设计决策和框架无关的最佳实践。供 agent-dev-workshop Phase 2 调用。
+origin: ECC
+---
+
+# Agent Patterns Catalog
+
+AI Agent 架构模式目录，为 Agent 设计提供**框架无关**的参考架构。
+
+## 何时激活
+
+- `agent-dev-workshop` Phase 2 自动调用
+- 用户询问 Agent 架构模式选择
+- 需要对比不同 Agent 架构方案时
+
+## 模式索引
+
+| 模式 | 核心思想 | 适用场景 | Reference |
+|------|---------|---------|-----------|
+| ReAct Agent | 思考→行动→观察循环 | 通用任务、搜索+操作 | `references/react-agent.md` |
+| Multi-Agent Conversation | 多角色自由对话 | 辩论、评审、头脑风暴 | `references/multi-agent-conversation.md` |
+| Multi-Agent Workflow | DAG/Pipeline 编排 | 阶段式处理、内容生产 | `references/multi-agent-workflow.md` |
+| RAG Agent | 检索增强生成 | 知识问答、文档分析 | `references/rag-agent.md` |
+| Tool-Use Agent | 工具调用链 | API 集成、数据处理 | `references/tool-use-agent.md` |
+| Autonomous Agent | 自主规划+执行+反思 | 开放式任务、自主研究 | `references/autonomous-agent.md` |
+
+## 模式选择决策树
+
+```
+Q1: Agent 需要自主分解复杂任务吗？
+  ├─ Yes → Autonomous Agent
+  └─ No → Q2
+
+Q2: 涉及多个不同角色协作吗？
+  ├─ Yes → Q3
+  └─ No → Q4
+
+Q3: 角色之间需要自由对话还是固定流程？
+  ├─ 自由对话 → Multi-Agent Conversation
+  └─ 固定流程 → Multi-Agent Workflow
+
+Q4: 核心能力是知识检索吗？
+  ├─ Yes → RAG Agent
+  └─ No → Q5
+
+Q5: 需要推理+多步操作还是简单工具调用？
+  ├─ 推理+多步 → ReAct Agent
+  └─ 简单调用 → Tool-Use Agent
+```
+
+## 混合模式
+
+真实项目中常出现混合模式，常见组合：
+
+| 组合 | 场景 | 设计要点 |
+|------|------|---------|
+| RAG + ReAct | 基于知识库的推理和操作 | 检索作为一种 Tool 嵌入 ReAct 循环 |
+| RAG + Tool-Use | 知识问答 + 数据操作 | 检索和工具并列 |
+| Workflow + ReAct | 流水线中某阶段需要推理 | 流水线节点内部嵌入 ReAct loop |
+| Autonomous + Tool-Use | 自主规划 + 工具执行 | Plan 产出的子任务由 Tool Agent 执行 |
+
+## 使用方式
+
+```
+# 在 agent-dev-workshop Phase 2 中
+1. 根据 Phase 1 确认的 Agent 类型，读取对应 reference 文件
+2. 从 reference 中提取参考架构图
+3. 根据实际 spec 调整组件拓扑
+4. 记录设计决策
+```

package/skills/agent-patterns-catalog/references/autonomous-agent.md

@@ -0,0 +1,151 @@
+# Autonomous Agent 模式
+
+## 核心思想
+
+**Plan → Execute → Reflect** — Agent 自主将复杂目标分解为子任务计划，
+逐步执行，在每步执行后评估进展，必要时重新规划。适合开放式、长周期、目标驱动的任务。
+
+## 参考架构
+
+```mermaid
+graph TD
+    User[用户目标] --> Planner[Planner]
+    Planner -->|任务计划| TaskQueue[Task Queue]
+    TaskQueue -->|取出任务| Executor[Executor]
+    Executor -->|执行结果| Reflector[Reflector]
+    Reflector -->|评估| Decision{目标达成?}
+    Decision -->|否: 需重新规划| Planner
+    Decision -->|否: 继续执行| TaskQueue
+    Decision -->|是| Reporter[Reporter]
+    Reporter --> User
+    
+    Executor --> Tools[工具集]
+    Executor --> Memory[(Long-term Memory)]
+    Reflector --> Memory
+```
+
+## 核心循环
+
+```
+goal = user_input
+plan = planner.decompose(goal)
+memory = LongTermMemory()
+
+while not goal_achieved(plan, memory):
+    current_task = plan.next_task()
+    
+    # Execute
+    result = executor.run(current_task, tools, memory)
+    memory.store(current_task, result)
+    
+    # Reflect
+    reflection = reflector.evaluate(
+        goal=goal,
+        plan=plan,
+        completed=memory.get_completed(),
+        current_result=result
+    )
+    
+    if reflection.needs_replan:
+        plan = planner.replan(goal, memory, reflection.reason)
+    elif reflection.task_failed:
+        plan.retry_or_skip(current_task, reflection.suggestion)
+
+report = reporter.summarize(goal, memory)
+return report
+```
+
+## 组件职责
+
+| 组件 | 职责 | 关键配置 |
+|------|------|---------|
+| Planner | 目标分解、任务排序、重新规划 | `decomposition_strategy`, `max_tasks` |
+| Executor | 执行单个任务，调用工具 | `tools`, `timeout`, `max_retries` |
+| Reflector | 评估进展、判断是否需要调整 | `eval_criteria`, `replan_threshold` |
+| Memory | 存储执行历史和中间产物 | `backend`, `retrieval_strategy` |
+| Reporter | 汇总最终结果 | `format`, `include_trace` |
+
+## 规划策略
+
+| 策略 | 描述 | 适用场景 |
+|------|------|---------|
+| Top-Down | 先全局规划再执行 | 目标清晰、任务可预见 |
+| Incremental | 每次只规划下一步 | 探索性任务、信息不确定 |
+| Hierarchical | 多层级分解（目标→子目标→任务）| 复杂长期项目 |
+| Adaptive | 初始规划 + 动态调整 | 推荐的默认策略 |
+
+## 反思维度
+
+```yaml
+reflection:
+  dimensions:
+    - name: "progress"
+      question: "完成了多少？距离目标还有多远？"
+    - name: "quality"
+      question: "当前结果的质量是否达标？"
+    - name: "efficiency"
+      question: "是否有更高效的方法？"
+    - name: "feasibility"
+      question: "剩余计划是否仍然可行？"
+    - name: "risk"
+      question: "是否出现了新的风险或阻碍？"
+  
+  actions:
+    - "continue"       # 一切正常，继续执行
+    - "retry"          # 当前任务失败，重试
+    - "skip"           # 跳过当前任务
+    - "replan"         # 需要重新规划
+    - "escalate"       # 需要人类介入
+    - "complete"       # 目标已达成
+```
+
+## 适用场景
+
+- 开放式研究任务（"调研 X 领域的最新进展并写报告"）
+- 项目管理（"完成这个功能的开发"）
+- 数据分析（"分析销售数据并找出增长机会"）
+- 系统维护（"优化数据库慢查询"）
+
+## 安全约束
+
+```yaml
+safety:
+  # 资源限制
+  max_iterations: 50
+  max_total_tokens: 500000
+  max_tool_calls: 200
+  timeout: 3600s
+  
+  # 操作限制
+  require_confirmation:
+    - "delete_*"
+    - "send_email"
+    - "deploy_*"
+  
+  # 花费限制
+  max_cost_usd: 10.0
+  
+  # 紧急停止
+  stop_conditions:
+    - "连续 3 次相同失败"
+    - "检测到循环行为"
+    - "总成本超过阈值"
+```
+
+## 设计要点
+
+1. **目标明确性**：模糊的目标导致无限探索，启动前先与用户澄清目标和成功标准
+2. **任务粒度**：每个任务应在 1-5 个工具调用内完成
+3. **反思频率**：每完成一个任务就反思，不要等太久
+4. **退出条件**：必须有多重退出条件（目标达成、资源耗尽、人工干预）
+5. **可回溯性**：所有执行历史保存在 Memory 中，支持人类审查
+
+## 常见陷阱
+
+| 陷阱 | 表现 | 解决方案 |
+|------|------|---------|
+| 过度规划 | 花大量 token 在计划而非执行 | 限制计划步骤数，边做边调 |
+| 反思不足 | 执行偏离目标但未发现 | 每步强制反思 + 进度量化 |
+| 循环行为 | 重复执行相同操作 | 检测重复模式 + 自动打断 |
+| 目标漂移 | 逐渐偏离原始目标 | 每次反思回顾原始目标 |
+| 资源耗尽 | token 或时间用完 | 严格的资源预算 + 优先级 |

package/skills/agent-patterns-catalog/references/multi-agent-conversation.md

@@ -0,0 +1,102 @@
+# Multi-Agent 对话模式
+
+## 核心思想
+
+多个专业化角色 Agent 通过**自由对话**协作完成任务。每个 Agent 有独立的系统提示和工具集，
+通过路由机制决定下一个发言者。适合需要多视角分析、辩论、协商的场景。
+
+## 参考架构
+
+```mermaid
+graph TD
+    User[用户输入] --> Router{路由/主持人}
+    Router -->|分派| A1[Agent: 研究员]
+    Router -->|分派| A2[Agent: 分析师]
+    Router -->|分派| A3[Agent: 评审员]
+    A1 -->|发言| SharedState[共享对话状态]
+    A2 -->|发言| SharedState
+    A3 -->|发言| SharedState
+    SharedState --> Router
+    Router -->|收敛| Summarizer[总结 Agent]
+    Summarizer --> User
+```
+
+## 路由策略
+
+| 策略 | 描述 | 适用场景 |
+|------|------|---------|
+| Round-Robin | 按固定顺序轮流发言 | 流水线式协作 |
+| LLM-Routed | 由 LLM 判断下一个发言者 | 开放式讨论 |
+| Function-Routed | 基于规则/关键词路由 | 确定性分发 |
+| Broadcast | 所有 Agent 同时接收并响应 | 投票/并行分析 |
+| Hierarchical | 上级 Agent 分派给下级 | 管理层级式协作 |
+
+## 对话协议
+
+```
+conversation = ConversationState()
+
+while not conversation.is_resolved:
+    next_speaker = router.select(conversation)
+    
+    message = next_speaker.respond(
+        conversation.history,
+        conversation.shared_context
+    )
+    
+    conversation.add_message(next_speaker.role, message)
+    
+    if convergence_check(conversation):
+        summary = summarizer.summarize(conversation)
+        break
+```
+
+## 组件职责
+
+| 组件 | 职责 | 关键配置 |
+|------|------|---------|
+| Router / Moderator | 选择下一发言者、判断收敛 | `strategy`, `max_rounds` |
+| Specialist Agent | 从特定视角响应 | `role`, `system_prompt`, `tools` |
+| Shared State | 维护对话历史和共享数据 | `max_history`, `summary_interval` |
+| Summarizer | 汇总讨论结果 | `format`, `key_points` |
+
+## 适用场景
+
+- 多角度分析和评审（安全评审 + 性能评审 + 架构评审）
+- 辩论式决策（正方、反方、裁判）
+- 专家会诊（多专科医生会诊）
+- 创意头脑风暴（发散 → 收敛）
+
+## 角色定义模板
+
+```yaml
+agent:
+  id: "researcher"
+  name: "研究员"
+  role: "负责搜索和收集相关信息"
+  system_prompt: |
+    你是一位严谨的研究员。
+    你的职责是搜索和整理与当前讨论相关的事实信息。
+    总是引用信息来源。不要推测或编造数据。
+  tools:
+    - web_search
+    - document_retrieval
+  speak_when: "需要事实依据、数据支撑、或其他 Agent 引用了未验证信息时"
+```
+
+## 设计要点
+
+1. **角色差异化**：每个 Agent 必须有明确不同的视角和能力
+2. **收敛机制**：必须定义何时停止讨论（轮数上限、共识检测、质量门槛）
+3. **共享状态**：决定哪些信息全局可见，哪些仅对特定 Agent 可见
+4. **发言秩序**：避免"同质化"——如果所有 Agent 说同样的话，减少 Agent 数量
+5. **冲突解决**：当 Agent 观点矛盾时，如何仲裁
+
+## 常见陷阱
+
+| 陷阱 | 表现 | 解决方案 |
+|------|------|---------|
+| 角色同质化 | 所有 Agent 给出相似回答 | 强化角色差异，限制信息共享 |
+| 无限讨论 | 对话无法收敛 | 设置 max_rounds + 收敛检测 |
+| Context 爆炸 | 对话太长超出窗口 | 定期摘要 + 滑动窗口 |
+| 羊群效应 | 后发言者跟随先发言者 | 独立思考后再交流，或并行生成 |

package/skills/agent-patterns-catalog/references/multi-agent-workflow.md

@@ -0,0 +1,124 @@
+# Multi-Agent 工作流模式
+
+## 核心思想
+
+将复杂任务拆解为**有向无环图（DAG）**中的阶段，每个阶段由专门的 Agent 负责，
+通过显式的输入/输出契约和质量门禁串联。适合流程确定、需要阶段质量保证的场景。
+
+## 参考架构
+
+```mermaid
+graph LR
+    Input[任务输入] --> S1[Stage 1: 数据采集]
+    S1 -->|Gate 1| S2[Stage 2: 分析处理]
+    S1 -->|Gate 1| S3[Stage 3: 知识检索]
+    S2 --> S4[Stage 4: 报告生成]
+    S3 --> S4
+    S4 -->|Gate 2| S5[Stage 5: 质量审查]
+    S5 -->|Pass| Output[最终输出]
+    S5 -->|Fail| S4
+```
+
+## 工作流定义
+
+```yaml
+workflow:
+  name: "research-report-pipeline"
+  stages:
+    - id: "collect"
+      agent: "data-collector"
+      inputs: ["user_query"]
+      outputs: ["raw_data"]
+      timeout: 60s
+      
+    - id: "analyze"
+      agent: "analyst"
+      inputs: ["raw_data"]
+      outputs: ["analysis_result"]
+      depends_on: ["collect"]
+      
+    - id: "retrieve"
+      agent: "knowledge-retriever"
+      inputs: ["user_query"]
+      outputs: ["relevant_docs"]
+      depends_on: ["collect"]
+      parallel_with: ["analyze"]
+      
+    - id: "generate"
+      agent: "report-writer"
+      inputs: ["analysis_result", "relevant_docs"]
+      outputs: ["draft_report"]
+      depends_on: ["analyze", "retrieve"]
+      
+    - id: "review"
+      agent: "quality-reviewer"
+      inputs: ["draft_report"]
+      outputs: ["final_report"]
+      depends_on: ["generate"]
+      gate:
+        condition: "score >= 0.8"
+        on_fail: "retry:generate"
+        max_retries: 2
+```
+
+## 组件职责
+
+| 组件 | 职责 | 关键配置 |
+|------|------|---------|
+| Workflow Engine | DAG 调度、状态跟踪 | `max_retries`, `timeout` |
+| Stage Agent | 执行单一阶段任务 | `inputs`, `outputs`, `tools` |
+| Quality Gate | 阶段间验证 | `condition`, `on_fail` |
+| State Store | 中间产物持久化 | `backend`, `ttl` |
+
+## 调度策略
+
+| 策略 | 描述 | 实现方式 |
+|------|------|---------|
+| Sequential | 严格顺序执行 | `depends_on` 链式依赖 |
+| Parallel | 无依赖阶段并行 | `parallel_with` 或自动检测 |
+| Conditional | 根据条件分支 | `gate.condition` + `on_fail` |
+| Fan-out / Fan-in | 一对多分发 + 汇聚 | 多阶段同一 `depends_on` |
+| Iterative | 循环直到条件满足 | `gate.on_fail: retry` |
+
+## 适用场景
+
+- 数据处理流水线（采集 → 清洗 → 分析 → 可视化）
+- 内容生产流水线（研究 → 撰写 → 审核 → 发布）
+- 软件发布流水线（编码 → 测试 → 审查 → 部署）
+- 多步骤任务自动化（表单提交 → 验证 → 处理 → 通知）
+
+## 设计要点
+
+1. **阶段粒度**：一个阶段 = 一个清晰的输入/输出变换，不要太粗也不要太细
+2. **契约优先**：先定义每个阶段的输入/输出 schema，再实现
+3. **幂等性**：每个阶段应支持重试而不产生副作用
+4. **超时控制**：每个阶段和整体工作流都设置超时
+5. **可观测性**：记录每个阶段的输入、输出、耗时、token 消耗
+
+## 质量门禁模板
+
+```yaml
+gate:
+  name: "report-quality-gate"
+  checks:
+    - type: "completeness"
+      condition: "all required sections present"
+    - type: "accuracy"
+      condition: "no factual contradictions"
+    - type: "format"
+      condition: "follows output schema"
+  on_pass: "continue"
+  on_fail:
+    action: "retry_previous"
+    max_retries: 2
+    feedback: "将检查失败原因反馈给上游 Agent"
+```
+
+## 常见陷阱
+
+| 陷阱 | 表现 | 解决方案 |
+|------|------|---------|
+| 阶段耦合 | 修改一个阶段影响其他阶段 | 严格的输入/输出 schema |
+| 重试风暴 | 质量门禁反复失败 | 设置 max_retries + 降级策略 |
+| 状态丢失 | 中间产物未持久化 | 每个阶段输出写入 state store |
+| 并行竞争 | 并行阶段写同一资源 | 输出隔离，在汇聚点合并 |

package/skills/agent-patterns-catalog/references/rag-agent.md

@@ -0,0 +1,128 @@
+# RAG Agent 架构模式
+
+## 核心思想
+
+**Retrieval-Augmented Generation** — 将外部知识库的检索能力与 LLM 生成能力结合，
+Agent 在回答前先从知识库中检索相关文档片段，以此作为上下文增强生成质量。
+
+## 参考架构
+
+```mermaid
+graph TD
+    User[用户查询] --> Agent[RAG Agent Core]
+    Agent -->|1. 查询理解| QueryProc[Query Processor]
+    QueryProc -->|2. 检索| Retriever{Retriever}
+    Retriever --> VS[(Vector Store)]
+    Retriever --> KW[(Keyword Index)]
+    Retriever --> KG[(Knowledge Graph)]
+    Retriever -->|3. 候选文档| Reranker[Reranker]
+    Reranker -->|4. Top-K| Generator[LLM Generator]
+    Generator -->|5. 生成回答| Agent
+    Agent --> User
+    
+    subgraph 离线流水线
+        Docs[原始文档] --> Loader[Document Loader]
+        Loader --> Chunker[Chunker]
+        Chunker --> Embedder[Embedding Model]
+        Embedder --> VS
+    end
+```
+
+## 离线流水线
+
+### 1. 文档加载
+
+| 数据源 | Loader 类型 | 注意事项 |
+|--------|-----------|---------|
+| PDF | PDF Parser | 表格和图片需特殊处理 |
+| Markdown | Text Splitter | 按标题层级拆分 |
+| HTML | HTML Parser | 去除导航和样板文本 |
+| 数据库 | SQL Loader | 定期增量同步 |
+| API | API Fetcher | 考虑速率限制和缓存 |
+
+### 2. 分块策略
+
+| 策略 | 片段大小 | 适用场景 |
+|------|---------|---------|
+| Fixed Size | 512-1024 tokens | 通用文本 |
+| Recursive | 按文档结构 | 带层级的文档 |
+| Semantic | 按语义边界 | 长文章、论文 |
+| Sentence | 按句子分割 | 对话、FAQ |
+| Parent-Child | 大块+小块 | 保留上下文 + 精确检索 |
+
+### 3. Embedding 模型选择
+
+| 模型 | 维度 | 适用语言 | 备注 |
+|------|------|---------|------|
+| text-embedding-3-small | 1536 | 多语言 | OpenAI，性价比高 |
+| text-embedding-3-large | 3072 | 多语言 | OpenAI，高精度 |
+| bge-m3 | 1024 | 中英文 | 开源，支持混合检索 |
+| nomic-embed-text | 768 | 英文 | 开源，本地部署 |
+
+### 4. 向量数据库
+
+| 数据库 | 部署方式 | 适用规模 | 混合检索 |
+|--------|---------|---------|---------|
+| Chroma | 嵌入式/独立 | 小-中 | ❌ |
+| Qdrant | Docker/Cloud | 中-大 | ✅ |
+| Milvus | Docker/Cloud | 大 | ✅ |
+| Weaviate | Docker/Cloud | 中-大 | ✅ |
+| pgvector | PostgreSQL 扩展 | 小-中 | ❌ |
+| FAISS | 嵌入式 | 中 | ❌ |
+
+## 在线检索
+
+### 查询理解
+
+```
+1. 意图分类 → 需要检索 / 直接回答 / 多步推理
+2. 查询重写 → 扩展关键词、分解子问题
+3. HyDE（可选）→ 先生成假设性答案，用假设答案做检索
+```
+
+### 检索策略
+
+| 策略 | 描述 | 适用场景 |
+|------|------|---------|
+| Dense | 纯向量相似度检索 | 语义匹配 |
+| Sparse | 关键词匹配（BM25） | 精确术语查找 |
+| Hybrid | Dense + Sparse 融合 | 生产推荐 |
+| Multi-Query | 生成多个查询变体 | 模糊问题 |
+| Self-Query | 从查询中提取过滤条件 | 结构化 + 非结构化 |
+
+### Reranking
+
+```
+candidates = retriever.search(query, top_k=20)
+reranked = reranker.rerank(query, candidates, top_k=5)
+context = format_context(reranked)
+answer = llm.generate(query, context)
+```
+
+## 组件职责
+
+| 组件 | 职责 | 关键配置 |
+|------|------|---------|
+| Document Loader | 加载和预处理文档 | `source_type`, `encoding` |
+| Chunker | 文档分块 | `chunk_size`, `overlap`, `strategy` |
+| Embedding Model | 文本向量化 | `model`, `dimension` |
+| Vector Store | 存储和检索向量 | `backend`, `index_type` |
+| Reranker | 候选文档重排序 | `model`, `top_k` |
+| Generator | 基于上下文生成回答 | `model`, `max_tokens` |
+
+## 设计要点
+
+1. **分块大小**：太小丢失上下文，太大引入噪声，通常 512-1024 token
+2. **Overlap**：相邻片段重叠 10-20%，避免信息在分割处丢失
+3. **Metadata**：每个片段保留来源、页码、时间戳，用于引用和过滤
+4. **Reranking**：比单纯增大 top_k 更有效
+5. **Hallucination Guard**：提示 LLM"仅基于提供的上下文回答，不确定时说不知道"
+
+## 常见陷阱
+
+| 陷阱 | 表现 | 解决方案 |
+|------|------|---------|
+| 检索不相关 | 返回的文档与问题无关 | 优化 embedding 模型 + 混合检索 |
+| 上下文不足 | 答案不完整 | 增大 top_k 或使用 parent-child 策略 |
+| 信息过时 | 知识库未更新 | 增量同步 + 时间衰减权重 |
+| 幻觉回答 | 生成了知识库中没有的内容 | Grounding 检查 + 引用要求 |

package/skills/agent-patterns-catalog/references/react-agent.md

@@ -0,0 +1,72 @@
+# ReAct Agent 架构模式
+
+## 核心思想
+
+**Reasoning + Acting** — Agent 在每一步中先推理（Thought），然后决定行动（Action），
+再根据行动结果观察（Observation），循环执行直到得出最终答案。
+
+## 参考架构
+
+```mermaid
+graph TD
+    User[用户输入] --> Agent[Agent Core]
+    Agent -->|1. Thought| LLM[LLM 推理]
+    LLM -->|2. Action| Router{工具路由}
+    Router --> T1[Tool 1]
+    Router --> T2[Tool 2]
+    Router --> T3[Tool N]
+    T1 -->|3. Observation| Agent
+    T2 -->|3. Observation| Agent
+    T3 -->|3. Observation| Agent
+    Agent -->|4. Final Answer| User
+    Agent --> Memory[Memory Store]
+```
+
+## 执行循环
+
+```
+while not done and iterations < max_iterations:
+    thought = llm.think(prompt + history + observations)
+    
+    if thought.is_final_answer:
+        return thought.answer
+    
+    action = thought.selected_tool
+    observation = tools.execute(action.name, action.params)
+    history.append(thought, action, observation)
+
+return "达到最大迭代次数，当前最佳结果: ..."
+```
+
+## 组件职责
+
+| 组件 | 职责 | 关键配置 |
+|------|------|---------|
+| Agent Core | 主控循环、维护状态 | `max_iterations`, `timeout` |
+| LLM Client | 推理、决策 | `model`, `temperature`, `max_tokens` |
+| Tool Registry | 注册工具、分发调用 | 工具列表、参数验证 |
+| Memory | 存储对话历史 | `type`, `window_size` |
+
+## 适用场景
+
+- 需要多步推理的通用任务（搜索 → 分析 → 汇总）
+- 信息收集和整合
+- 问答 + 操作（查询数据 → 执行修改）
+- 客户支持（诊断问题 → 查找解决方案 → 执行操作）
+
+## 设计要点
+
+1. **Prompt 设计**：必须清晰描述可用工具、何时使用、输出格式
+2. **终止条件**：明确定义什么是最终答案
+3. **迭代上限**：防止无限循环，建议 5-15 次
+4. **工具描述**：精确的工具描述是 ReAct 成功的关键
+5. **错误恢复**：工具失败时 Agent 应能尝试替代方案
+
+## 常见陷阱
+
+| 陷阱 | 表现 | 解决方案 |
+|------|------|---------|
+| 工具描述模糊 | Agent 选错工具或传错参数 | 精确的 description + few-shot |
+| 无限循环 | 反复调用相同工具 | 设置 max_iterations + 去重检测 |
+| 过度推理 | 不必要地调用工具 | 在 prompt 中明确"能直接回答则直接回答" |
+| 错误传播 | 一个工具失败导致后续全错 | 每步观察后评估是否继续 |