{ "metadata": { "id": "ch43", "title": "第43章：开源社区与贡献", "volume": "vol11", "volume_title": "生态与跨平台", "word_count": 6246, "difficulty": "intermediate", "prerequisites": [ "ch04" ], "key_concepts": [ "概述：开源对 Agent 生态的重要性", "开源：Agent 生态的基石", "Agent 开源项目分类全景", "参与开源的价值", "主要开源项目深度分析", "LangChain / LangGraph", "AutoGen", "CrewAI", "Dify", "其他值得关注的项目", "参与开源贡献：从 Issue 到 PR", "开源贡献的完整流程", "Issue 报告的艺术", "PR（Pull Request）最佳实践", "Code Review 参与指南" ], "learning_objectives": [], "estimated_tokens": 3748, "source_file": "vol11/ch43_开源社区与贡献.md" }, "overview": "", "sections": [ { "id": "43.1", "title": "43.1 概述：开源对 Agent 生态的重要性", "level": 2, "content": "", "subsections": [ { "id": "43.1.1", "title": "43.1.1 开源：Agent 生态的基石", "content": "如果你仔细审视当前的 Agent 技术版图，会发现一个不争的事实：**开源项目构成了整个 Agent 生态的底层基础设施**。\n\n从底层的模型框架（Transformers、vLLM）到中间的 Agent 框架（LangChain、AutoGen、CrewAI），再到上层的编排平台（Dify、Flowise），开源项目在每一个关键层级都扮演着不可替代的角色。据统计，2024-2025 年间，GitHub 上与 LLM/Agent 相关的仓库数量增长了超过 300%，其中 90% 以上是开源项目。\n\n开源对 Agent 生态的重要性体现在以下维度：\n\n**1. 技术民主化**\n- 开源让前沿的 Agent 技术不再是少数科技巨头的专利\n- 任何开发者都可以自由使用、学习、修改最先进的 Agent 框架\n- 降低了整个行业的技术门槛，加速了创新扩散\n\n**2. 标准化推动**\n- MCP 协议、OpenAI Function Calling 格式等事实标准，都诞生于开源社区\n- 开源项目之间的互相兼容和集成，推动了生态的标准化进程\n- 开放的 API 设计和协议规范，让不同工具之间的互操作成为可能\n\n**3. 安全与透明**\n- 开源代码的可审计性为企业级部署提供了安全基础\n- 社区的集体审查可以发现和修复单个团队可能遗漏的安全漏洞\n- 透明的开发过程建立了用户对 Agent 技术的信任\n\n**4. 人才生态**\n- 开源社区是培养 Agent 技术人才的天然土壤\n- 参与开源项目是展示技术能力、建立个人品牌的最有效途径之一\n- 社区的知识共享加速了整个领域的人才成长" }, { "id": "43.1.2", "title": "43.1.2 Agent 开源项目分类全景", "content": "当前的 Agent 开源项目可以按功能层级分为以下几大类：" }, { "id": "43.1.3", "title": "43.1.3 参与开源的价值", "content": "对于个人开发者而言，参与 Agent 开源社区的价值是多维度的：\n\n| 价值维度 | 具体体现 |\n|---------|---------|\n| **技术成长** | 阅读优秀代码、学习最佳实践、接触前沿技术 |\n| **职业发展** | 开源贡献是简历上最有说服力的技术证明 |\n| **人脉网络** | 结识全球顶尖开发者、获得协作机会 |\n| **个人品牌** | 在社区中建立技术影响力、成为领域专家 |\n| **商业机会** | 通过开源项目发现创业方向、获得投资关注 |\n| **成就感** | 看到自己的代码被数万人使用和认可 |\n\n---" } ] }, { "id": "43.2", "title": "43.2 主要开源项目深度分析", "level": 2, "content": "", "subsections": [ { "id": "43.2.1", "title": "43.2.1 LangChain / LangGraph", "content": "**项目概况：**\n- GitHub Stars: 90k+（LangChain 核心）+ 10k+（LangGraph）\n- 许可证: MIT\n- 主要语言: Python, TypeScript\n- 贡献者: 3000+\n\nLangChain 是目前最流行的 LLM 应用开发框架，提供了一套完整的工具链来构建基于 LLM 的应用。LangGraph 是其专注于 Agent 编排的子项目，支持构建有状态的、多 Actor 的 Agent 应用。\n\n**核心架构：**\n\n\n**LangGraph 状态图：**\n\n\n**参与贡献指南：**\n\nLangChain 项目的贡献流程比较成熟，以下是一些关键路径：\n\n1. **文档改进**：LangChain 的文档常常跟不上代码迭代速度，改进文档是最容易入手的贡献方式\n2. **Bug 修复**：关注 `good first issue` 标签的 Issue\n3. **新集成**：为新的 LLM Provider 或 Tool 提供集成（参考现有实现的模式）\n4. **性能优化**：LangChain 因抽象层级较多，存在不少性能优化空间" }, { "id": "43.2.2", "title": "43.2.2 AutoGen", "content": "**项目概况：**\n- GitHub Stars: 40k+\n- 许可证: MIT (AutoGen) / Apache 2.0 (AutoGen Studio)\n- 主要语言: Python\n- 贡献者: 500+\n\nAutoGen 是微软研究院开源的多 Agent 对话框架，专注于构建可以相互协作的 Agent 团队。其核心理念是\"通过对话解决问题\"——不同的 Agent 扮演不同角色，通过结构化的对话完成复杂任务。\n\n**核心模式：**" }, { "id": "43.2.3", "title": "43.2.3 CrewAI", "content": "**项目概况：**\n- GitHub Stars: 30k+\n- 许可证: MIT（部分企业功能有商业许可）\n- 主要语言: Python\n- 贡献者: 200+\n\nCrewAI 以\"角色扮演\"的理念构建多 Agent 系统，每个 Agent 有明确的角色定义、目标和工具集。相比 AutoGen 的自由对话模式，CrewAI 更强调结构化的任务编排和角色定义。" }, { "id": "43.2.4", "title": "43.2.4 Dify", "content": "**项目概况：**\n- GitHub Stars: 50k+\n- 许可证: Apache 2.0（附加企业条款）\n- 主要语言: TypeScript, Python\n- 贡献者: 400+\n\nDify 是一个开源的 LLM 应用开发平台，提供了可视化的工作流编排界面，降低了 Agent 应用的开发门槛。\n\n**核心特性：**\n- 可视化的 Workflow 编排器\n- 内置 RAG 引擎（支持多种向量数据库）\n- 模型管理（支持多模型切换和 A/B 测试）\n- 企业级特性（权限管理、审计日志、SSO）\n\n**参与贡献的关键领域：**\n\n1. **Workflow 节点**：开发新的 Workflow 节点类型（如 HTTP Request、代码执行、条件分支）\n2. **模型 Provider**：接入新的 LLM Provider\n3. **向量数据库集成**：支持新的向量数据库后端\n4. **UI/UX 改进**：改进可视化编排器的交互体验" }, { "id": "43.2.5", "title": "43.2.5 其他值得关注的项目", "content": "| 项目 | 定位 | Stars | 特色 |\n|------|------|-------|------|\n| **LlamaIndex** | RAG 框架 | 35k+ | 数据连接和索引引擎 |\n| **Semantic Kernel** | 企业 Agent 框架 | 22k+ | 微软官方、.NET/Python 双语言 |\n| **Flowise** | 可视化 Agent 编排 | 30k+ | 低代码拖拽式 |\n| **Open Interpreter** | 代码执行 Agent | 55k+ | 本地代码执行能力 |\n| **BabyAGI** | 自主任务 Agent | 15k+ | 任务自主分解和执行 |\n| **Haystack** | NLP 框架 | 16k+ | 端到端 NLP 管道 |\n| **Mem0** | 记忆层 | 20k+ | Agent 长期记忆管理 |\n\n---" } ] }, { "id": "43.3", "title": "43.3 参与开源贡献：从 Issue 到 PR", "level": 2, "content": "", "subsections": [ { "id": "43.3.1", "title": "43.3.1 开源贡献的完整流程", "content": "参与开源贡献并不是只有写代码这一条路。一个健康的项目需要各种类型的贡献：" }, { "id": "43.3.2", "title": "43.3.2 Issue 报告的艺术", "content": "一个好的 Issue 报告是开源社区最宝贵的贡献之一。以下是撰写高质量 Issue 的模板和方法：\n\nfrom langchain.agents import create_react_agent\n# ... 你的代码 ...\nTraceback (most recent call last):\n File \"test.py\", line 5\n ...\nTypeError: ..." }, { "id": "43.3.3", "title": "43.3.3 PR（Pull Request）最佳实践", "content": "提交 PR 是开源贡献的核心环节。一个高质量的 PR 需要遵循以下原则：\n\n**1. PR 描述模板**\n\n\n**2. Git 工作流**\n\n\n**3. 代码修改原则**\n\n- **最小变更原则**：每个 PR 只解决一个问题\n- **原子提交**：每次提交都是一个完整、独立的逻辑单元\n- **向后兼容**：尽量不破坏现有 API\n- **测试覆盖**：新增代码必须有对应的测试\n- **文档同步**：API 变更必须同步更新文档" }, { "id": "43.3.4", "title": "43.3.4 Code Review 参与指南", "content": "Code Review 不仅仅是维护者的工作，任何社区成员都可以参与：\n\nasync def get_or_create_session(self, session_id: str):\n try:\n return await self.db.sessions.insert(\n session_id=session_id,\n unique=True, # 如果已存在会抛出 IntegrityError\n )\n except IntegrityError:\n return await self.db.sessions.get(session_id=session_id)\n\n**Code Review 的检查清单：**\n\n1. **正确性**：代码是否正确实现了预期功能？\n2. **安全性**：是否存在注入、泄露等安全风险？\n3. **性能**：是否有明显的性能瓶颈？\n4. **可读性**：代码是否易于理解？命名是否清晰？\n5. **可维护性**：代码是否易于修改和扩展？\n6. **测试**：测试是否充分？是否覆盖了边界情况？\n7. **文档**：公共 API 是否有文档字符串？\n8. **风格**：是否符合项目的代码风格规范？\n\n---" } ] }, { "id": "43.4", "title": "43.4 代码规范：编写可贡献的代码", "level": 2, "content": "", "subsections": [ { "id": "43.4.1", "title": "43.4.1 Python 代码规范", "content": "Agent 项目绝大多数使用 Python 作为主要语言，以下是与 Agent 开发特别相关的代码规范：\n\n**类型注解（Type Hints）**\n\n\n**异步编程规范**\n\n\n**错误处理规范**" }, { "id": "43.4.2", "title": "43.4.2 TypeScript 代码规范", "content": "对于 Web 端和跨平台项目，TypeScript 的规范同样重要：" }, { "id": "43.4.3", "title": "43.4.3 测试规范", "content": "---" } ] }, { "id": "43.5", "title": "43.5 文档贡献", "level": 2, "content": "", "subsections": [ { "id": "43.5.1", "title": "43.5.1 文档的类型与重要性", "content": "在开源项目中，文档的重要性常常被低估。一份好的文档可以：\n\n1. **降低上手门槛**：新用户可以通过文档快速理解项目并开始使用\n2. **减少重复 Issue**：清晰的文档可以避免大量重复的问题\n3. **吸引贡献者**：好的文档是吸引新贡献者的重要因素\n4. **建立专业形象**：文档质量直接反映了项目的专业程度\n\n**Agent 项目文档的核心类型：**\n\n| 文档类型 | 目标读者 | 内容 | 重要性 |\n|---------|---------|------|--------|\n| **README.md** | 所有人 | 项目介绍、快速开始、安装、基本用法 | ⭐⭐⭐⭐⭐ |\n| **API 文档** | 开发者 | 接口定义、参数说明、返回值 | ⭐⭐⭐⭐⭐ |\n| **教程/Tutorials** | 新手 | 循序渐进的实践指南 | ⭐⭐⭐⭐ |\n| **概念指南** | 进阶用户 | 设计理念、核心概念解释 | ⭐⭐⭐⭐ |\n| **贡献指南** | 贡献者 | 开发环境搭建、PR 流程、代码规范 | ⭐⭐⭐⭐ |\n| **架构文档** | 深度贡献者 | 系统架构、模块设计、数据流 | ⭐⭐⭐ |\n| **Changelog** | 所有用户 | 版本变更记录 | ⭐⭐⭐ |" }, { "id": "43.5.2", "title": "43.5.2 撰写高质量 README", "content": "一个 Agent 项目的 README 应该包含以下核心部分：" }, { "id": "43.5.3", "title": "43.5.3 API 文档的撰写", "content": "对于 Agent 框架而言，API 文档是最常被查阅的文档类型：" }, { "id": "43.5.4", "title": "43.5.4 教程写作的艺术", "content": "好的教程应该像导游一样，引导读者从零开始一步步完成一个实际的项目。以下是一个 Agent 教程的示例框架：\n\n\n---" } ] }, { "id": "43.6", "title": "43.6 社区运营与知识分享", "level": 2, "content": "", "subsections": [ { "id": "43.6.1", "title": "43.6.1 社区参与的多层次模型", "content": "" }, { "id": "43.6.2", "title": "43.6.2 知识分享的渠道与方式", "content": "**1. 技术博客**\n\n\n**2. 开源项目文档站**\n\n使用 MkDocs、Docusaurus 等工具搭建项目文档站：\n\n\n**3. 视频教程与直播**\n\n- **技术分享会**：录制 15-30 分钟的技术分享视频\n- **代码走读**：逐行解析核心代码的设计思路\n- **Live Coding**：实时演示开发过程\n- **AMA（Ask Me Anything）**：定期举办社区问答" }, { "id": "43.6.3", "title": "43.6.3 构建个人技术品牌", "content": "在 Agent 开源社区中建立个人技术品牌的策略：\n\n**1. 持续输出**\n- 每周至少一篇技术博客\n- 定期在社交媒体分享学习笔记\n- 参与开源项目的讨论和 Review\n\n**2. 深度聚焦**\n- 选择一个细分方向（如 RAG、Tool Calling、Multi-Agent）深入\n- 成为该方向的社区专家\n- 在相关 Issue 和 PR 中提供高质量的技术意见\n\n**3. 创建个人项目**\n- 基于现有框架构建有创意的 Agent 应用\n- 发布为开源项目，展示技术实力\n- 良好的 README、文档和测试是加分项\n\n**4. 参与线下活动**\n- 参加 Agent/AI 相关的技术 Meetup\n- 在技术大会上分享经验\n- 与其他开发者面对面交流" }, { "id": "43.6.4", "title": "43.6.4 社区治理与可持续发展", "content": "一个健康的开源社区需要良好的治理机制：\n\n**1. 治理模型**\n\n| 模型 | 描述 | 适用阶段 |\n|------|------|---------|\n| **BDFL（仁慈独裁者）** | 由创始人做最终决策 | 项目早期 |\n| **核心团队** | 由核心贡献者投票 | 项目成长期 |\n| ** meritocracy（精英制）** | 基于贡献的权限递增 | 项目成熟期 |\n| **基金会** | 由第三方基金会管理 | 项目稳定期 |\n\n**2. 贡献者激励**\n\n- **Committer 权限**：对持续贡献者授予代码提交权限\n- **感谢信**：在 Release Note 中感谢贡献者\n- **Swag**：为贡献者提供项目贴纸、T 恤等\n- **会议赞助**：为活跃贡献者提供参加技术会议的机会\n\n**3. 可持续发展的关键**\n\n- **清晰的路线图**：让社区知道项目的方向\n- **及时的 Issue 响应**：贡献者的 Issue 被忽视是最伤害积极性的\n- **透明的决策过程**：重大决策通过 RFC（Request for Comments）讨论\n- **合理的代码审查**：及时且建设性的 Code Review\n- **友好的社区氛围**：对新手友好，禁止人身攻击\n\n---" } ] }, { "id": "本章小结", "title": "本章小结", "level": 2, "content": "开源是 Agent 生态的基石，参与开源社区是每一位 Agent 开发者都应该认真对待的事情。本章从开源生态全景、主要项目分析、贡献流程、代码规范、文档写作、社区运营六个维度，为读者提供了一套完整的开源参与指南。\n\n**核心要点回顾：**\n\n1. 开源构成了 Agent 生态的每一层基础设施\n2. 参与开源不仅仅是写代码，还包括 Issue 报告、文档改进、社区讨论等多种形式\n3. 高质量的 PR 需要清晰的描述、原子提交、充分的测试和同步的文档\n4. 代码规范（类型注解、错误处理、异步编程）是可贡献代码的基础\n5. 文档（README、API 文档、教程）的质量直接决定了项目的吸引力和可用性\n6. 知识分享（博客、演讲、教程）是建立个人技术品牌的最有效途径\n\n**给你的建议：**\n\n- **今天就开始**：找到你感兴趣的开源 Agent 项目，Star 它、阅读它的代码、尝试运行\n- **从小事做起**：从修正文档中的 typo、回答一个 Issue 开始\n- **持续参与**：开源贡献是一场马拉松，不是百米冲刺\n- **享受过程**：帮助他人、分享知识本身就有价值\n\n---\n\n*「开源的本质是信任的积累。每一行代码、每一个 PR、每一次 Review，都在为这份信任添砖加瓦。」*", "subsections": [] } ], "code_blocks": [ { "id": "code-1", "language": "text", "description": "当前的 Agent 开源项目可以按功能层级分为以下几大类：", "code": "┌─────────────────────────────────────────────────────────┐\n│ 应用层 (Application) │\n│ Open Interpreter · BabyAGI · AgentGPT · ChatDev │\n├─────────────────────────────────────────────────────────┤\n│ 编排层 (Orchestration) │\n│ Dify · Coze(部分开源) · Flowise · Langflow · FlowiseAI │\n├─────────────────────────────────────────────────────────┤\n│ 框架层 (Framework) │\n│ LangChain · AutoGen · CrewAI · LlamaIndex · Semantic K│\n├─────────────────────────────────────────────────────────┤\n│ 工具层 (Tool) │\n│ MCP协议 · OpenAI Plugins · Hugging Face Tools │\n├─────────────────────────────────────────────────────────┤\n│ 基础设施层 (Infrastructure) │\n│ vLLM · TGI · Ollama · ChromaDB · Milvus · Qdrant │\n├─────────────────────────────────────────────────────────┤\n│ 模型层 (Model) │\n│ LLaMA · Mistral · Qwen · DeepSeek · Yi │\n└─────────────────────────────────────────────────────────┘", "section_ref": "43.1.2", "runnable": false, "dependencies": [] }, { "id": "code-2", "language": "python", "description": "核心架构：", "code": "# LangChain 核心概念示例\nfrom langchain_core.messages import HumanMessage, SystemMessage\nfrom langchain_openai import ChatOpenAI\nfrom langchain_core.tools import tool\nfrom langgraph.prebuilt import create_react_agent\n\n# 定义工具\n@tool\ndef search_web(query: str) -> str:\n \"\"\"搜索网页获取最新信息\"\"\"\n # 实际实现中会调用搜索 API\n return f\"搜索结果: {query} 的相关信息...\"\n\n@tool\ndef read_file(path: str) -> str:\n \"\"\"读取本地文件内容\"\"\"\n with open(path, 'r') as f:\n return f.read()\n\n@tool\ndef run_code(code: str) -> str:\n \"\"\"执行 Python 代码并返回结果\"\"\"\n exec_globals = {}\n try:\n exec(code, exec_globals)\n return str(exec_globals.get('result', 'No result'))\n except Exception as e:\n return f\"Error: {e}\"\n\n# 创建 Agent\nmodel = ChatOpenAI(model=\"gpt-4o\")\nagent = create_react_agent(\n model=model,\n tools=[search_web, read_file, run_code],\n prompt=\"你是一个有帮助的 AI 助手，可以使用工具来完成用户的任务。\",\n)\n\n# 使用 Agent\nresult = agent.invoke({\n \"messages\": [HumanMessage(content=\"帮我分析 data.csv 文件并生成摘要\")]\n})", "section_ref": "43.2.1", "runnable": true, "dependencies": [ "langchain_core", "langchain_openai", "langgraph" ] }, { "id": "code-3", "language": "python", "description": "LangGraph 状态图：", "code": "# LangGraph - 构建有状态的 Agent 工作流\nfrom langgraph.graph import StateGraph, END\nfrom typing import TypedDict, Annotated, List\nimport operator\n\nclass AgentState(TypedDict):\n messages: List[str]\n next_agent: str\n intermediate_results: Annotated[list, operator.add]\n\ndef researcher_node(state: AgentState) -> AgentState:\n \"\"\"研究节点 - 搜索和收集信息\"\"\"\n # 调用搜索工具\n search_result = search_tool(state[\"messages\"][-1])\n return {\n \"intermediate_results\": [search_result],\n \"next_agent\": \"analyst\",\n }\n\ndef analyst_node(state: AgentState) -> AgentState:\n \"\"\"分析节点 - 分析和总结\"\"\"\n # 分析研究结果\n analysis = analyze_tool(state[\"intermediate_results\"])\n return {\n \"intermediate_results\": [analysis],\n \"next_agent\": \"writer\",\n }\n\ndef writer_node(state: AgentState) -> AgentState:\n \"\"\"写作节点 - 生成最终报告\"\"\"\n # 生成报告\n report = write_tool(state[\"intermediate_results\"])\n return {\n \"messages\": [report],\n \"next_agent\": END,\n }\n\n# 构建状态图\ngraph = StateGraph(AgentState)\ngraph.add_node(\"researcher\", researcher_node)\ngraph.add_node(\"analyst\", analyst_node)\ngraph.add_node(\"writer\", writer_node)\n\ngraph.add_edge(\"researcher\", \"analyst\")\ngraph.add_edge(\"analyst\", \"writer\")\ngraph.add_edge(\"writer\", END)\n\ngraph.set_entry_point(\"researcher\")\n\n# 编译并运行\napp = graph.compile()\nresult = app.invoke({\"messages\": [\"研究 Agent 技术的最新趋势\"]})", "section_ref": "43.2.1", "runnable": true, "dependencies": [ "langgraph", "operator" ] }, { "id": "code-4", "language": "python", "description": "核心模式：", "code": "# AutoGen - 多 Agent 协作\nimport autogen\n\nconfig_list = [\n {\"model\": \"gpt-4o\", \"api_key\": \"your-key\"},\n]\n\nllm_config = {\n \"config_list\": config_list,\n \"temperature\": 0,\n}\n\n# 创建不同角色的 Agent\nuser_proxy = autogen.UserProxyAgent(\n name=\"User\",\n human_input_mode=\"NEVER\", # 自动模式\n max_consecutive_auto_reply=5,\n code_execution_config={\"work_dir\": \"coding\"},\n system_message=\"你代表用户执行任务。如果代码需要执行，使用 User 代理。\",\n)\n\ncoder = autogen.AssistantAgent(\n name=\"Coder\",\n llm_config=llm_config,\n system_message=\"你是一个资深 Python 开发者。根据需求编写高质量的代码。\",\n)\n\nreviewer = autogen.AssistantAgent(\n name=\"Reviewer\",\n llm_config=llm_config,\n system_message=\"你是一个代码审查专家。检查代码的正确性、安全性和最佳实践。如果发现问题，指出并建议修改。\",\n)\n\ntester = autogen.AssistantAgent(\n name=\"Tester\",\n llm_config=llm_config,\n system_message=\"你是一个测试工程师。为给定的代码编写全面的单元测试。\",\n)\n\n# 定义工作流\ndef run_development_workflow(task: str):\n \"\"\"执行开发工作流：编码 → 审查 → 测试 → 修复\"\"\"\n # 第一步：编码\n user_proxy.initiate_chat(\n coder,\n message=f\"请完成以下任务：{task}\",\n )\n\n # 第二步：审查\n user_proxy.initiate_chat(\n reviewer,\n message=\"请审查上面的代码，给出改进建议。\",\n )\n\n # 第三步：测试\n user_proxy.initiate_chat(\n tester,\n message=\"为上面的代码编写单元测试。\",\n )\n\n# 群聊模式 - Agent 之间直接对话\ngroupchat = autogen.GroupChat(\n agents=[user_proxy, coder, reviewer, tester],\n messages=[],\n max_round=10,\n speaker_selection_method=\"auto\",\n)\n\nmanager = autogen.GroupChatManager(\n groupchat=groupchat,\n llm_config=llm_config,\n)\n\n# 启动群聊\nuser_proxy.initiate_chat(\n manager,\n message=\"我们需要开发一个简单的 REST API 服务，用于管理待办事项。请团队成员协作完成。\",\n)", "section_ref": "43.2.2", "runnable": true, "dependencies": [ "autogen" ] }, { "id": "code-5", "language": "python", "description": "CrewAI 以\"角色扮演\"的理念构建多 Agent 系统，每个 Agent 有明确的角色定义、目标和工具集。相比 AutoGen 的自由对话模式，CrewAI 更强调结构化的任务编排和角色定义。", "code": "# CrewAI - 角色驱动的多 Agent 协作\nfrom crewai import Agent, Task, Crew, Process\nfrom crewai_tools import SerperDevTool, ScrapeWebsiteTool\n\n# 定义工具\nsearch_tool = SerperDevTool()\nscrape_tool = ScrapeWebsiteTool()\n\n# 定义 Agent 角色\nresearcher = Agent(\n role='技术研究员',\n goal='深入研究指定的技术领域，收集最新的信息和趋势',\n backstory='你是一位经验丰富的技术研究员，擅长从海量信息中提取关键洞察。',\n tools=[search_tool, scrape_tool],\n verbose=True,\n allow_delegation=False,\n)\n\nwriter = Agent(\n role='技术写作者',\n goal='将研究结果转化为清晰、准确、有深度的技术文章',\n backstory='你是一位优秀的技术写作专家，擅长将复杂的技术概念转化为易懂的文章。',\n verbose=True,\n allow_delegation=False,\n)\n\neditor = Agent(\n role='技术编辑',\n goal='审查和修改技术文章，确保内容的准确性、连贯性和可读性',\n backstory='你是一位严谨的技术编辑，对内容质量有极高的标准。',\n verbose=True,\n allow_delegation=False,\n)\n\n# 定义任务\nresearch_task = Task(\n description='研究 2025 年 Agent 框架的最新发展趋势，包括 LangChain、AutoGen、CrewAI 等',\n expected_output='一份详细的研究报告，包含各框架的特点、对比和趋势分析',\n agent=researcher,\n)\n\nwriting_task = Task(\n description='基于研究报告，撰写一篇关于 Agent 框架选型的技术博客文章',\n expected_output='一篇 3000 字左右的技术博客文章',\n agent=writer,\n)\n\nediting_task = Task(\n description='审查并修改文章，确保技术准确性和可读性',\n expected_output='最终版本的精修文章',\n agent=editor,\n)\n\n# 创建团队并执行\ncrew = Crew(\n agents=[researcher, writer, editor],\n tasks=[research_task, writing_task, editing_task],\n process=Process.sequential, # 顺序执行\n verbose=True,\n)\n\nresult = crew.kickoff()\nprint(result)", "section_ref": "43.2.3", "runnable": true, "dependencies": [ "crewai", "crewai_tools" ] }, { "id": "code-6", "language": "text", "description": "参与开源贡献并不是只有写代码这一条路。一个健康的项目需要各种类型的贡献：", "code": "┌────────────────────────────────────────────────────────┐\n│ 开源贡献类型金字塔 │\n│ │\n│ ┌──────────────────┐ │\n│ │ 核心架构贡献 │ ← 最稀缺、最有价值 │\n│ │ (架构设计/重构) │ │\n│ ├──────────────────┤ │\n│ │ 新功能开发 │ ← 需要深入理解项目 │\n│ │ (Feature/Plugin)│ │\n│ ├──────────────────┤ │\n│ │ Bug 修复 │ ← 适合中级贡献者 │\n│ │ (Bug Fix/Hotfix)│ │\n│ ├──────────────────┤ │\n│ │ 文档与教程 │ ← 最适合新手入门 │\n│ │ (Docs/Tutorial) │ │\n│ ├──────────────────┤ │\n│ │ 社区参与 │ ← 任何人都可参与 │\n│ │ (Issue/Triage) │ │\n│ └──────────────────┘ │\n└────────────────────────────────────────────────────────┘", "section_ref": "43.3.1", "runnable": false, "dependencies": [] }, { "id": "code-7", "language": "markdown", "description": "一个好的 Issue 报告是开源社区最宝贵的贡献之一。以下是撰写高质量 Issue 的模板和方法：", "code": "## Bug 报告模板\n\n### 问题描述\n[简洁描述你遇到的问题。例如：\"在使用 X 功能时，当 Y 条件满足时，系统产生 Z 错误。\"]\n\n### 复现步骤\n1. 安装版本：`pip install langchain==0.1.0`\n2. 使用以下代码：\n", "section_ref": "43.3.2", "runnable": false, "dependencies": [] }, { "id": "code-8", "language": "text", "description": "from langchain.agents import createreactagent", "code": "\n3. 运行后得到以下错误：\n", "section_ref": "43.3.2", "runnable": false, "dependencies": [] }, { "id": "code-9", "language": "text", "description": "TypeError: ...", "code": "\n### 期望行为\n[描述你期望的正确行为]\n\n### 实际行为\n[描述实际发生了什么]\n\n### 环境信息\n- OS: macOS 14.0\n- Python: 3.11.5\n- LangChain: 0.1.0\n- OpenAI SDK: 1.0.0\n\n### 附加信息\n- [ ] 我已搜索已有的 Issues，确认这不是重复问题\n- [x] 我可以提供修复此 Bug 的 PR", "section_ref": "43.3.2", "runnable": false, "dependencies": [] }, { "id": "code-10", "language": "markdown", "description": "- [x] 我可以提供修复此 Bug 的 PR", "code": "## Feature 请求模板\n\n### 功能描述\n[清晰描述你希望添加的功能]\n\n### 动机\n[为什么需要这个功能？它解决了什么问题？]\n\n### 建议的实现方式\n[如果有可能，描述你建议的实现方式]\n\n### 替代方案\n[考虑过的其他替代方案]\n\n### 使用场景\n[描述具体的使用场景，帮助维护者理解需求]", "section_ref": "43.3.2", "runnable": false, "dependencies": [] }, { "id": "code-11", "language": "markdown", "description": "1. PR 描述模板", "code": "## 变更描述\n[简洁描述这次 PR 做了什么]\n\n## 变更类型\n- [ ] Bug 修复（非破坏性变更，修复了某个 Issue）\n- [x] 新功能（非破坏性变更，添加了新功能）\n- [ ] 破坏性变更（可能导致现有功能不兼容）\n- [ ] 文档更新\n\n## 关联 Issue\nFixes #123\nRelated to #456\n\n## 变更详情\n[详细描述代码变更的逻辑]\n\n### 实现方式\n[说明实现的技术方案和设计决策]\n\n### 为什么选择这个方案\n[对比其他可选方案，说明选择理由]\n\n## 测试\n- [x] 添加了单元测试\n- [x] 所有现有测试通过\n- [x] 手动测试通过\n\n## 截图（如有 UI 变更）\n[附上变更前后的截图对比]\n\n## 检查清单\n- [x] 代码遵循项目的代码风格规范\n- [x] 添加了必要的文档\n- [x] 更新了 CHANGELOG\n- [x] 没有引入新的警告", "section_ref": "43.3.3", "runnable": false, "dependencies": [] }, { "id": "code-12", "language": "bash", "description": "2. Git 工作流", "code": "# 1. Fork 项目\ngh repo fork langchain-ai/langchain --clone\n\n# 2. 创建特性分支\ncd langchain\ngit checkout -b feat/add-redis-tool\n\n# 3. 开发和提交（原子提交）\ngit add src/tools/redis_tool.py\ngit commit -m \"feat(tools): add Redis tool for caching operations\n\n- Implement RedisTool class with get/set/delete operations\n- Add connection pooling support\n- Include comprehensive error handling\n\nRefs: #1234\"\n\n# 4. 保持与上游同步\ngit remote add upstream https://github.com/langchain-ai/langchain.git\ngit fetch upstream\ngit rebase upstream/main\n\n# 5. 推送并创建 PR\ngit push origin feat/add-redis-tool\ngh pr create --title \"feat(tools): add Redis tool\" --body-file pr.md", "section_ref": "43.3.3", "runnable": false, "dependencies": [] }, { "id": "code-13", "language": "python", "description": "Code Review 不仅仅是维护者的工作，任何社区成员都可以参与：", "code": "# 好的 Code Review 评论示例\n\n# ❌ 差的评论：\"这段代码有问题\"\n# ✅ 好的评论：\n\"\"\"\n这里有一个潜在的并发安全问题。\n\n当多个请求同时调用 `get_or_create_session()` 时，\n可能会创建多个 session 而不是返回已有的 session。\n\n建议使用数据库级别的唯一约束来保证原子性：\n", "section_ref": "43.3.4", "runnable": true, "dependencies": [] }, { "id": "code-14", "language": "text", "description": "return await self.db.sessions.get(sessionid=sessionid)", "code": "\n这样可以避免竞态条件。你觉得这个方案如何？\n\"\"\"", "section_ref": "43.3.4", "runnable": false, "dependencies": [] }, { "id": "code-15", "language": "python", "description": "类型注解（Type Hints）", "code": "from typing import Optional, List, Dict, Any, AsyncGenerator\nfrom dataclasses import dataclass\nfrom enum import Enum\n\n# ✅ 好的类型注解 - 精确且有意义\n@dataclass\nclass AgentConfig:\n \"\"\"Agent 配置\"\"\"\n model: str\n temperature: float = 0.7\n max_tokens: int = 4096\n tools: Optional[List[str]] = None\n retry_policy: RetryPolicy = RetryPolicy.EXPONENTIAL\n\n\nclass RetryPolicy(Enum):\n \"\"\"重试策略\"\"\"\n NONE = \"none\"\n LINEAR = \"linear\"\n EXPONENTIAL = \"exponential\"\n\n\nasync def stream_chat(\n messages: List[Dict[str, str]],\n model: str,\n *,\n temperature: float = 0.7,\n max_tokens: int = 4096,\n tools: Optional[List[ToolDefinition]] = None,\n on_tool_call: Optional[AsyncToolCallHandler] = None,\n) -> AsyncGenerator[StreamEvent, None]:\n \"\"\"\n 流式聊天接口。\n\n Args:\n messages: 消息历史列表，每个消息包含 role 和 content。\n model: 模型标识符，如 \"gpt-4o\"、\"claude-3.5-sonnet\"。\n temperature: 生成温度，范围 [0, 2]。默认 0.7。\n max_tokens: 最大生成 token 数。默认 4096。\n tools: 可用的工具定义列表。如果为 None，则不使用工具。\n on_tool_call: 工具调用的异步回调函数。\n\n Yields:\n StreamEvent: 流式事件，包含类型和数据。\n\n Raises:\n ModelNotFoundError: 指定的模型不可用。\n RateLimitError: 超出 API 调用频率限制。\n AgentError: Agent 执行过程中的其他错误。\n\n Example:\n >>> async for event in stream_chat(messages, \"gpt-4o\"):\n ... if event.type == \"text_delta\":\n ... print(event.content, end=\"\")\n \"\"\"\n ...", "section_ref": "43.4.1", "runnable": true, "dependencies": [] }, { "id": "code-16", "language": "python", "description": "异步编程规范", "code": "import asyncio\nfrom contextlib import asynccontextmanager\nfrom functools import wraps\n\n# ✅ 正确的异步资源管理\n@asynccontextmanager\nasync def acquire_session(session_id: str):\n \"\"\"获取会话的上下文管理器\"\"\"\n session = await session_store.get(session_id)\n if not session:\n session = await session_store.create(session_id)\n try:\n yield session\n finally:\n await session.release()\n\n\n# ✅ 带超时的异步操作\nasync def call_model_with_timeout(\n prompt: str,\n timeout: float = 30.0,\n) -> str:\n \"\"\"带超时的模型调用\"\"\"\n try:\n return await asyncio.wait_for(\n model.generate(prompt),\n timeout=timeout,\n )\n except asyncio.TimeoutError:\n logger.warning(f\"Model call timed out after {timeout}s\")\n raise ModelTimeoutError(f\"Request exceeded {timeout}s timeout\")\n\n\n# ✅ 并发安全的工具调用\nasync def execute_tools_parallel(\n tool_calls: List[ToolCall],\n max_concurrent: int = 5,\n) -> List[ToolResult]:\n \"\"\"并发执行多个工具调用（限制并发数）\"\"\"\n semaphore = asyncio.Semaphore(max_concurrent)\n\n async def execute_one(call: ToolCall) -> ToolResult:\n async with semaphore:\n try:\n result = await tool_executor.execute(call)\n return ToolResult(call_id=call.id, content=result)\n except Exception as e:\n logger.error(f\"Tool {call.name} failed: {e}\")\n return ToolResult(call_id=call.id, content=str(e), is_error=True)\n\n return await asyncio.gather(*[execute_one(c) for c in tool_calls])", "section_ref": "43.4.1", "runnable": true, "dependencies": [ "contextlib" ] }, { "id": "code-17", "language": "python", "description": "错误处理规范", "code": "from typing import Union\nfrom pydantic import BaseModel, Field\n\n# ✅ 自定义异常层次\nclass AgentError(Exception):\n \"\"\"Agent 基础异常\"\"\"\n def __init__(self, message: str, *, code: str = \"AGENT_ERROR\"):\n self.message = message\n self.code = code\n super().__init__(message)\n\n\nclass ModelError(AgentError):\n \"\"\"模型相关错误\"\"\"\n pass\n\n\nclass ToolExecutionError(AgentError):\n \"\"\"工具执行错误\"\"\"\n def __init__(self, tool_name: str, message: str):\n self.tool_name = tool_name\n super().__init__(f\"Tool '{tool_name}' failed: {message}\",\n code=\"TOOL_EXECUTION_ERROR\")\n\n\nclass ContextOverflowError(AgentError):\n \"\"\"上下文溢出错误\"\"\"\n def __init__(self, total_tokens: int, limit: int):\n self.total_tokens = total_tokens\n self.limit = limit\n super().__init__(\n f\"Context overflow: {total_tokens} > {limit}\",\n code=\"CONTEXT_OVERFLOW\",\n )\n\n\n# ✅ 统一的错误响应\nclass ErrorResponse(BaseModel):\n \"\"\"统一的错误响应格式\"\"\"\n error: str = Field(description=\"错误类型\")\n message: str = Field(description=\"错误描述\")\n code: str = Field(description=\"错误码\")\n details: Optional[dict] = Field(default=None, description=\"错误详情\")\n\n\ndef handle_agent_errors(func):\n \"\"\"Agent 错误处理装饰器\"\"\"\n @wraps(func)\n async def wrapper(*args, **kwargs):\n try:\n return await func(*args, **kwargs)\n except ModelError as e:\n return ErrorResponse(\n error=\"model_error\",\n message=e.message,\n code=e.code,\n )\n except ToolExecutionError as e:\n return ErrorResponse(\n error=\"tool_error\",\n message=e.message,\n code=e.code,\n details={\"tool_name\": e.tool_name},\n )\n except ContextOverflowError as e:\n return ErrorResponse(\n error=\"context_overflow\",\n message=e.message,\n code=e.code,\n details={\"total_tokens\": e.total_tokens, \"limit\": e.limit},\n )\n except AgentError as e:\n return ErrorResponse(error=e.code, message=e.message, code=e.code)\n return wrapper", "section_ref": "43.4.1", "runnable": true, "dependencies": [ "pydantic" ] }, { "id": "code-18", "language": "typescript", "description": "对于 Web 端和跨平台项目，TypeScript 的规范同样重要：", "code": "// ✅ 精确的类型定义\ninterface AgentConfig {\n /** 模型标识符 */\n model: string;\n /** 生成温度，范围 [0, 2] */\n temperature?: number;\n /** 最大生成 token 数 */\n maxTokens?: number;\n /** 可用工具列表 */\n tools?: ToolDefinition[];\n /** 重试配置 */\n retry?: {\n maxAttempts: number;\n backoffMs: number;\n retryableErrors: string[];\n };\n}\n\n// 使用 Discriminated Union 区分不同类型的事件\ntype StreamEvent =\n | { type: 'text_delta'; content: string; messageId: string }\n | { type: 'tool_call'; callId: string; name: string; arguments: Record }\n | { type: 'tool_result'; callId: string; content: string; isError?: boolean }\n | { type: 'done'; usage: TokenUsage }\n | { type: 'error'; message: string; code: string };\n\n// 使用泛型实现类型安全的 API 客户端\nclass AgentAPIClient {\n async send(\n endpoint: string,\n request: AgentRequest,\n ): Promise {\n const response = await fetch(`${this.baseUrl}${endpoint}`, {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify(request),\n });\n\n if (!response.ok) {\n throw new AgentAPIError(response.status, await response.text());\n }\n\n return response.json() as Promise;\n }\n}", "section_ref": "43.4.2", "runnable": true, "dependencies": [] }, { "id": "code-19", "language": "python", "description": "", "code": "# tests/test_agent.py - Agent 测试示例\nimport pytest\nfrom unittest.mock import AsyncMock, patch, MagicMock\nfrom agent import Agent, AgentConfig\nfrom agent.exceptions import ModelError, ToolExecutionError\n\n\nclass TestAgentBasic:\n \"\"\"Agent 基础功能测试\"\"\"\n\n @pytest.fixture\n def agent_config(self):\n return AgentConfig(\n model=\"gpt-4o\",\n temperature=0.7,\n max_tokens=1024,\n )\n\n @pytest.fixture\n def agent(self, agent_config):\n return Agent(agent_config)\n\n @pytest.mark.asyncio\n async def test_simple_chat(self, agent):\n \"\"\"测试简单对话\"\"\"\n with patch.object(agent, '_call_model', new_callable=AsyncMock) as mock:\n mock.return_value = \"你好！我是 AI 助手。\"\n result = await agent.chat(\"你好\")\n assert result.content == \"你好！我是 AI 助手。\"\n mock.assert_called_once()\n\n @pytest.mark.asyncio\n async def test_tool_calling(self, agent):\n \"\"\"测试工具调用\"\"\"\n mock_tool = AsyncMock(return_value=\"搜索结果\")\n agent.register_tool(\"search\", mock_tool)\n\n with patch.object(agent, '_call_model', new_callable=AsyncMock) as mock_model:\n # 模拟模型返回工具调用\n mock_model.return_value = {\n \"tool_calls\": [{\"name\": \"search\", \"arguments\": {\"query\": \"test\"}}],\n }\n\n result = await agent.chat(\"搜索关于 Agent 的信息\")\n\n mock_tool.assert_called_once_with(query=\"test\")\n\n @pytest.mark.asyncio\n async def test_model_error_handling(self, agent):\n \"\"\"测试模型错误处理\"\"\"\n with patch.object(agent, '_call_model', new_callable=AsyncMock) as mock:\n mock.side_effect = ModelError(\"Rate limit exceeded\")\n with pytest.raises(ModelError):\n await agent.chat(\"test\")\n\n @pytest.mark.asyncio\n async def test_context_overflow(self, agent):\n \"\"\"测试上下文溢出处理\"\"\"\n # 构造超长上下文\n long_messages = [{\"role\": \"user\", \"content\": \"x\" * 100000}]\n\n with patch.object(agent, '_call_model', new_callable=AsyncMock) as mock:\n from agent.exceptions import ContextOverflowError\n mock.side_effect = ContextOverflowError(200000, 128000)\n with pytest.raises(ContextOverflowError):\n await agent.chat_with_history(long_messages)\n\n\nclass TestAgentStreaming:\n \"\"\"Agent 流式响应测试\"\"\"\n\n @pytest.mark.asyncio\n async def test_stream_response(self):\n \"\"\"测试流式响应\"\"\"\n agent = Agent(AgentConfig(model=\"gpt-4o\"))\n\n async def mock_stream():\n yield {\"type\": \"text_delta\", \"content\": \"你\"}\n yield {\"type\": \"text_delta\", \"content\": \"好\"}\n yield {\"type\": \"text_delta\", \"content\": \"！\"}\n yield {\"type\": \"done\"}\n\n with patch.object(agent, '_stream_model', return_value=mock_stream()):\n chunks = []\n async for event in agent.stream_chat(\"你好\"):\n if event.type == \"text_delta\":\n chunks.append(event.content)\n\n assert \"\".join(chunks) == \"你好！\"\n\n @pytest.mark.asyncio\n async def test_stream_with_tool_call(self):\n \"\"\"测试流式响应中的工具调用\"\"\"\n agent = Agent(AgentConfig(model=\"gpt-4o\"))\n mock_tool = AsyncMock(return_value=\"result\")\n\n async def mock_stream():\n yield {\"type\": \"text_delta\", \"content\": \"让我\"}\n yield {\"type\": \"tool_call\", \"name\": \"search\", \"arguments\": {\"q\": \"test\"}}\n yield {\"type\": \"text_delta\", \"content\": \"这是搜索结果\"}\n\n with patch.object(agent, '_stream_model', return_value=mock_stream()):\n events = []\n async for event in agent.stream_chat(\"搜索\"):\n events.append(event)\n\n assert any(e.type == \"tool_call\" for e in events)", "section_ref": "43.4.3", "runnable": true, "dependencies": [ "pytest", "agent" ] }, { "id": "code-20", "language": "markdown", "description": "一个 Agent 项目的 README 应该包含以下核心部分：", "code": "# ProjectName\n\n[一句话描述项目是什么]\n\n

\n \"Demo\"\n

\n\n## ✨ 特性\n\n- 🤖 **多模型支持**：支持 OpenAI、Anthropic、Google、开源模型等\n- 🔧 **工具集成**：内置 50+ 常用工具，支持自定义工具\n- 📚 **RAG 引擎**：内置检索增强生成，支持多种向量数据库\n- 🔄 **流式响应**：SSE 和 WebSocket 双模式流式输出\n- 🛡️ **安全可控**：内容过滤、权限管理、审计日志\n\n## 🚀 快速开始\n\n### 安装\n\n\\`\\`\\`bash\npip install projectname\n\\`\\`\\`\n\n### 基本使用\n\n\\`\\`\\`python\nfrom projectname import Agent\n\nagent = Agent(model=\"gpt-4o\")\nresult = agent.chat(\"你好，介绍一下你自己\")\nprint(result.content)\n\\`\\`\\`\n\n### 使用工具\n\n\\`\\`\\`python\nfrom projectname import Agent, tools\n\nagent = Agent(model=\"gpt-4o\")\nagent.use_tool(tools.WebSearch())\nagent.use_tool(tools.CodeInterpreter())\n\nresult = agent.chat(\"搜索最新的 AI 新闻并总结\")\n\\`\\`\\`\n\n## 📖 文档\n\n- [快速开始](docs/getting-started.md)\n- [工具使用指南](docs/tools.md)\n- [API 参考](docs/api.md)\n- [部署指南](docs/deployment.md)\n- [贡献指南](CONTRIBUTING.md)\n\n## 🛠️ 开发\n\n\\`\\`\\`bash\n# 克隆项目\ngit clone https://github.com/your/projectname.git\ncd projectname\n\n# 安装开发依赖\npip install -e \".[dev]\"\n\n# 运行测试\npytest tests/\n\n# 代码格式化\nruff format .\nruff check .\n\\`\\`\\`\n\n## 🤝 参与贡献\n\n欢迎所有形式的贡献！请阅读 [贡献指南](CONTRIBUTING.md) 了解详情。\n\n## 📄 许可证\n\nMIT License", "section_ref": "43.5.2", "runnable": false, "dependencies": [] }, { "id": "code-21", "language": "python", "description": "对于 Agent 框架而言，API 文档是最常被查阅的文档类型：", "code": "# 使用 Google 风格的文档字符串\nclass Agent:\n \"\"\"AI Agent 核心类。\n\n Agent 是一个可以与用户进行多轮对话、调用工具、\n 管理上下文的智能助手。\n\n Attributes:\n config: Agent 配置对象。\n tools: 已注册的工具列表。\n session: 当前会话状态。\n\n Examples:\n 基本使用::\n\n agent = Agent(model=\"gpt-4o\")\n response = agent.chat(\"你好\")\n\n 使用工具::\n\n agent = Agent(model=\"gpt-4o\")\n agent.use_tool(WebSearchTool())\n response = agent.chat(\"搜索最新的 AI 新闻\")\n\n 流式输出::\n\n async for event in agent.stream(\"讲个故事\"):\n if event.type == \"text_delta\":\n print(event.content, end=\"\")\n \"\"\"\n\n def chat(self, message: str, **kwargs) -> ChatResponse:\n \"\"\"发送消息并获取 Agent 响应。\n\n 这是最基本的对话方法，发送一条消息并等待完整的 Agent 响应。\n Agent 会自动管理上下文，包括系统提示、历史消息和工具调用结果。\n\n Args:\n message: 用户消息内容。\n model: 覆盖默认模型的模型标识符。\n 例如 \"gpt-4o\"、\"claude-3.5-sonnet\"。\n 如果不指定，使用 Agent 配置中的默认模型。\n temperature: 覆盖默认温度参数。范围 [0, 2]。\n max_tokens: 覆盖默认最大 token 数。\n system_prompt: 覆盖默认系统提示。\n tools: 本次对话可用的工具列表。如果为 None，\n 使用 Agent 已注册的所有工具。\n\n Returns:\n ChatResponse: 包含响应内容和元数据的响应对象。\n\n - content (str): Agent 的响应文本。\n - tool_calls (List[ToolCall]): 本次对话中的工具调用记录。\n - usage (TokenUsage): Token 使用统计。\n - duration_ms (float): 响应耗时（毫秒）。\n\n Raises:\n ModelNotFoundError: 指定的模型不可用。\n ContextOverflowError: 上下文超出模型限制。\n ToolExecutionError: 工具执行失败。\n RateLimitError: API 调用频率超限。\n\n Note:\n 此方法是异步的，但提供了同步封装。\n 在异步环境中，推荐使用 ``achat()`` 方法。\n\n Example:\n >>> agent = Agent(model=\"gpt-4o\")\n >>> response = agent.chat(\"什么是 MCP 协议？\")\n >>> print(response.content)\n 'MCP（Model Context Protocol）是...'\n >>> print(response.usage)\n TokenUsage(prompt=25, completion=150, total=175)\n \"\"\"\n ...", "section_ref": "43.5.3", "runnable": true, "dependencies": [] }, { "id": "code-22", "language": "markdown", "description": "好的教程应该像导游一样，引导读者从零开始一步步完成一个实际的项目。以下是一个 Agent 教程的示例框架：", "code": "# 教程：构建你的第一个 RAG Agent\n\n> **阅读时间**：30 分钟\n> **难度**：入门\n> **前置知识**：Python 基础、了解 LLM 基本概念\n\n## 你将学到什么\n\n完成这个教程后，你将能够：\n- ✅ 创建一个可以检索文档的 RAG Agent\n- ✅ 使用向量数据库存储和检索文档\n- ✅ 处理多轮对话中的上下文管理\n\n## 前置准备\n\n1. Python 3.10+\n2. OpenAI API Key\n3. 基本的命令行操作能力\n\n## 第一步：安装依赖\n\n[清晰的安装命令和可能的安装问题解决方案]\n\n## 第二步：准备文档\n\n[提供示例文档或文档准备方法]\n\n## 第三步：创建向量索引\n\n[代码 + 解释]\n\n## 第四步：构建 Agent\n\n[代码 + 解释]\n\n## 第五步：测试 Agent\n\n[测试命令 + 预期输出]\n\n## 常见问题\n\n### Q: 向量数据库启动失败？\nA: [解决方案]\n\n### Q: 中文文档检索效果不好？\nA: [解决方案]\n\n## 下一步\n\n[推荐进阶阅读和实践方向]", "section_ref": "43.5.4", "runnable": false, "dependencies": [] }, { "id": "code-23", "language": "text", "description": "", "code": "┌──────────────────────────────────────┐\n│ 社区领导层 │\n│ 核心维护者 · 架构决策 · 方向引导 │\n├──────────────────────────────────────┤\n│ 活跃贡献者 │\n│ 频繁 PR · Code Review · Issue 分类 │\n├──────────────────────────────────────┤\n│ 定期贡献者 │\n│ 偶尔 PR · 文档改进 · Bug 报告 │\n├──────────────────────────────────────┤\n│ 社区参与者 │\n│ Issue 讨论 · 功能建议 · 问答帮助 │\n├──────────────────────────────────────┤\n│ 使用者 │\n│ 使用项目 · 反馈问题 · Star 项目 │\n└──────────────────────────────────────┘", "section_ref": "43.6.1", "runnable": false, "dependencies": [] }, { "id": "code-24", "language": "markdown", "description": "1. 技术博客", "code": "# 撰写 Agent 技术博客的建议结构\n\n## 标题\n[具体、明确、包含关键词]\n# ❌ \"关于 Agent 的一些思考\"\n# ✅ \"我在开发 Agent CLI 中遇到的 5 个坑及解决方案\"\n\n## 引言（Hook）\n[用一个具体的问题或场景引入]\n\n## 问题背景\n[详细描述要解决的问题]\n\n## 技术方案\n[清晰的代码示例 + 架构图]\n\n## 实现细节\n[关键代码的详细解释]\n\n## 遇到的坑\n[真实的踩坑经验，最有价值的部分]\n\n## 性能对比\n[量化的数据对比]\n\n## 总结\n[核心要点回顾]", "section_ref": "43.6.2", "runnable": false, "dependencies": [] }, { "id": "code-25", "language": "yaml", "description": "使用 MkDocs、Docusaurus 等工具搭建项目文档站：", "code": "# mkdocs.yml - MkDocs 配置示例\nsite_name: AgentFramework\nsite_description: 开源 Agent 开发框架\nsite_author: YourName\n\ntheme:\n name: material\n language: zh\n palette:\n - scheme: default\n primary: indigo\n - scheme: slate\n primary: indigo\n\nnav:\n - 首页: index.md\n - 快速开始:\n - 安装: getting-started/installation.md\n - 第一个 Agent: getting-started/first-agent.md\n - 核心概念:\n - Agent: concepts/agent.md\n - 工具: concepts/tools.md\n - 会话: concepts/sessions.md\n - 记忆: concepts/memory.md\n - 进阶指南:\n - 自定义工具: advanced/custom-tools.md\n - RAG 集成: advanced/rag.md\n - 多 Agent 协作: advanced/multi-agent.md\n - 性能优化: advanced/performance.md\n - API 参考: api/\n - 贡献指南: contributing.md\n\nplugins:\n - search\n - mkdocstrings:\n handlers:\n python:\n options:\n docstring_style: google", "section_ref": "43.6.2", "runnable": false, "dependencies": [] } ], "tables": [ { "headers": [ "价值维度", "具体体现" ], "data": [ [ "**技术成长**", "阅读优秀代码、学习最佳实践、接触前沿技术" ], [ "**职业发展**", "开源贡献是简历上最有说服力的技术证明" ], [ "**人脉网络**", "结识全球顶尖开发者、获得协作机会" ], [ "**个人品牌**", "在社区中建立技术影响力、成为领域专家" ], [ "**商业机会**", "通过开源项目发现创业方向、获得投资关注" ], [ "**成就感**", "看到自己的代码被数万人使用和认可" ] ] }, { "headers": [ "项目", "定位", "Stars", "特色" ], "data": [ [ "**LlamaIndex**", "RAG 框架", "35k+", "数据连接和索引引擎" ], [ "**Semantic Kernel**", "企业 Agent 框架", "22k+", "微软官方、.NET/Python 双语言" ], [ "**Flowise**", "可视化 Agent 编排", "30k+", "低代码拖拽式" ], [ "**Open Interpreter**", "代码执行 Agent", "55k+", "本地代码执行能力" ], [ "**BabyAGI**", "自主任务 Agent", "15k+", "任务自主分解和执行" ], [ "**Haystack**", "NLP 框架", "16k+", "端到端 NLP 管道" ], [ "**Mem0**", "记忆层", "20k+", "Agent 长期记忆管理" ] ] }, { "headers": [ "文档类型", "目标读者", "内容", "重要性" ], "data": [ [ "**README.md**", "所有人", "项目介绍、快速开始、安装、基本用法", "⭐⭐⭐⭐⭐" ], [ "**API 文档**", "开发者", "接口定义、参数说明、返回值", "⭐⭐⭐⭐⭐" ], [ "**教程/Tutorials**", "新手", "循序渐进的实践指南", "⭐⭐⭐⭐" ], [ "**概念指南**", "进阶用户", "设计理念、核心概念解释", "⭐⭐⭐⭐" ], [ "**贡献指南**", "贡献者", "开发环境搭建、PR 流程、代码规范", "⭐⭐⭐⭐" ], [ "**架构文档**", "深度贡献者", "系统架构、模块设计、数据流", "⭐⭐⭐" ], [ "**Changelog**", "所有用户", "版本变更记录", "⭐⭐⭐" ] ] }, { "headers": [ "模型", "描述", "适用阶段" ], "data": [ [ "**BDFL（仁慈独裁者）**", "由创始人做最终决策", "项目早期" ], [ "**核心团队**", "由核心贡献者投票", "项目成长期" ], [ "** meritocracy（精英制）**", "基于贡献的权限递增", "项目成熟期" ], [ "**基金会**", "由第三方基金会管理", "项目稳定期" ] ] } ], "key_takeaways": [ "今天就开始：找到你感兴趣的开源 Agent 项目，Star 它、阅读它的代码、尝试运行", "从小事做起：从修正文档中的 typo、回答一个 Issue 开始", "持续参与：开源贡献是一场马拉松，不是百米冲刺", "享受过程：帮助他人、分享知识本身就有价值" ], "common_pitfalls": [], "related_chapters": [ "ch04" ] }