Agent 速成笔记 · 第 16 章 毕业设计：构建属于你的多智能体应用

Agent 速成笔记 · 第 16 章 毕业设计：构建属于你的多智能体应用

源：Datawhale《Hello-Agents》第 16 章 ｜ 定位：综合实战与全书收口 ｜ 一句话：把前 15 章学到的范式、工具、记忆、协议、评估收进一个可运行、可评审、可展示的开源项目里。

0. 一章速览（30 秒）

  • 一句话：毕业设计的形式是「往 Hello-Agents 的共创项目仓库提一个开源项目」——一份可运行的 Notebook 或 Python 脚本 + 完整依赖 + 清晰 README，走 Fork → 分支 → Pull Request → 社区 review → 合并主仓库的完整协作流程。
  • 本章解决什么问题：前面每章都在交付零件（范式、工具、记忆、通信协议、训练、评估），本章解决的是装配问题——选什么题、按什么标准设计、装哪些零件、交付哪些东西、凭什么算通过验收。
  • 必须记住的 5 个点：
    • 项目目录名固定为 {GitHub用户名}-{项目名称}（例：jjyaoao-CodeReviewAgent），PR 标题固定为 [毕业设计] 项目名称 - 简短描述——这两条是硬格式，不是建议；
    • 选题三原则：解决真实问题、在有限时间和资源内能做完、能清晰展示技术能力；"为了技术而技术"被明确排除；
    • 技术栈不是越多越好：范式、记忆、RAG、通信协议、强化学习都是按问题需要逐项加装的选配件，本章从未要求你把 15 章的功能全开；
    • 质量下限由一份 9 条测试清单 和两处硬约束把住：项目总大小不超过 5MB，视频、大型数据集、模型文件一律不进主仓库；
    • 评审是真实环节：社区成员会 review 你的代码并提改进建议，你要能改、能回帖、能说明改了什么。

1. 毕业设计的意义与交付形式（16.1）

1.1 为什么要做毕业设计

  • 是什么：一次「把学过的知识选择性整合进一个完整项目」的综合练习。原文强调的关键词是「选择性」——不是把 HelloAgents 的所有组件堆上去。
  • 真正的难点在哪：学过理论、会调 API 并不等于会做系统。本章直接点出三个待回答的问题：如何把知识应用到实际问题中？如何设计一个完整的系统？如何处理各种边界情况和异常？——注意第三问，它决定了一个作品是"能演示的 demo"还是"能被别人跑起来的项目"。
  • 能力清单（毕设真正要产出的东西）：
    • 独立设计并实现一个完整的智能体应用；
    • 熟练使用 HelloAgents 框架的各种功能；
    • 掌握 Git 与 GitHub 的基本操作；
    • 会写清晰的项目文档；
    • 参与开源社区的协作开发；
    • 最终得到一个可以展示的技术作品。
  • 工程要点：动手实践是本章反复出现的判断——「学习技术最好的方式不是看教程，而是动手实践」。这也决定了选题要偏"能跑、能演示"，而不是偏"能讲清原理"。

1.2 交付形式：四条硬要求

毕业设计以开源项目形式提交到 Hello-Agents 的共创项目仓库（Co-creation-projects 目录）。

项 要求 关键细节
项目命名 {你的GitHub用户名}-{项目名称} 示例：jjyaoao-CodeReviewAgent
项目内容 Notebook 或脚本 + 依赖 + README 可运行的 .ipynb 或 Python 脚本、requirements.txt、README.md；可选演示视频、截图、数据集
提交方式 GitHub Pull Request 先 Fork 上游仓库，再从特性分支发起 PR
评审流程 社区 review → 改进 → 合并 社区成员会 review 代码并提改进建议，通过后合并到主仓库
  • 为什么格式要这么死：共创仓库是多人共用的单一目录，命名规范、依赖清单、文档格式统一之后，评审成本才可控。这也是后面"大文件硬约束"的同一个理由。

2. 选题：原则、方向与示例（16.2）

2.1 三条选题原则

一个好的毕业设计项目应当同时满足三点：

  1. 有实用性：解决真实的问题，而不是为了技术而技术；
  2. 可完成：在有限的时间和资源内做得完（这条是排除项：需要大规模训练、需要昂贵数据源、需要长期运营的题目直接出局）；
  3. 能展示技术能力：项目的形态要让人一眼看出你用了哪些智能体技术。

容易踩的坑：把"用上 RL"或"用上五个 Agent"当成选题目标。判据应反过来——先看问题需要什么，再决定装什么。

2.2 五个推荐选题方向

原文给出五个方向、每个方向 4 个候选题目，可以任选其一，也可以自提新想法。

方向 候选题目
生产力工具 智能代码审查助手、智能文档生成器、智能会议助手、智能邮件助手
学习辅助 智能学习伙伴、智能论文助手、智能编程导师、智能语言学习助手
创意娱乐 智能故事生成器、智能游戏 NPC、智能音乐推荐、智能菜谱助手
数据分析 智能数据分析师、智能股票分析、智能舆情监控、智能竞品分析
生活服务 智能健康助手、智能理财助手、智能购物助手、智能家居控制

方向与前文的对应关系（串联归纳，非原文结论）：创意娱乐类的"智能游戏 NPC"与第 15 章赛博小镇同源（角色化 NPC + 好感度一类的状态系统）；数据分析类的"舆情监控/竞品分析"与第 14 章自动化深度研究智能体的 TODO 驱动研究范式同源（收集 → 汇总 → 报告）；"智能家居控制"这类需要跨进程/跨工具生态的题目，天然适合挂接第 10 章的通信协议与第 13 章的 MCP 工具集成。也就是说，前 15 章的三个实战项目已经为你示范了三种题型，选相近方向等于自带参考实现。

2.3 选题示例剖析：CodeReviewAgent

原文用"智能代码审查助手"完整走了一遍"从问题到成果"的推导，这是最值得照抄的模板：

  • 问题分析：代码审查很重要，但人工审查耗时且容易遗漏；现有静态分析工具只能发现语法错误，无法理解代码逻辑，因此需要一个能理解代码语义、提供深度分析的智能助手。
    —— 注意这个论证结构：现有工具的能力缺口在哪，恰恰是 LLM 的用武之地。这就是"为什么必须用智能体，而不能写个脚本"的答案。
  • 核心功能（五条）：代码质量分析（代码风格、命名规范、注释完整性）、潜在 bug 检测（逻辑错误、边界条件问题、资源泄漏）、性能优化建议（识别性能瓶颈、提出优化方案）、安全漏洞扫描（SQL 注入、XSS 等安全问题）、最佳实践推荐（结合语言特性与设计模式）。
  • 预期成果：一个可运行的 Jupyter Notebook 展示完整审查流程；支持 Python、JavaScript 等主流语言；产出结构化 Markdown 格式的审查报告；报告里有具体的代码示例与改进建议。

可复用的规律：输出格式要在选题阶段就定死（这里是 Markdown 报告）。输出格式一旦确定，工具的参数设计、README 的"使用示例"、outputs/ 目录里的样例文件全都自然落位。

3. 从需求到架构：一套可复用的设计流程

本节是串联：本章只给出了"交付什么、按什么标准验收"，把 13～15 章三个完整项目（智能旅行助手、自动化深度研究智能体、赛博小镇）的推进方式抽象成流程，就是下面这套动作。

3.1 五步设计流程

  1. 问题定义：谁在什么场景遇到什么痛点？现有工具为什么不够？——照 2.3 的论证结构写成 2～3 句话，写不出来说明题目没想清楚。
  2. 能力清单拆分：把功能逐条判定归属——能用确定性代码做的，绝不交给 LLM（统计函数个数、检查行长超 79 字符、缩进是否为 4 的倍数，这些用 ast 和字符串检查就是几行 Python）；只有"理解语义、给建议、做归纳"这类真正需要推理的部分才交给模型。
  3. 定架构形态：单 Agent 还是多 Agent，要不要挂记忆/RAG/通信协议，按 3.2 的清单逐项决策。
  4. 定接口与数据：工具名、参数名与类型（name / type / description / required）要写清楚，因为这段描述会直接进入提示词，决定模型会不会正确调用；输出结构（如 Markdown 报告）同步冻结。
  5. 定演示叙事：Notebook 的阅读顺序本身是设计的一部分——先一段基础功能，再一段复杂场景，必要时再加一段性能评估。

3.2 技术选型决策清单（什么时候装什么）

决策项 装它的信号 缓装/不装的信号
单 Agent 任务能在一个上下文里走完，步骤数可控，无角色分工 出现"必须并行"或"必须互相挑错"的需求
多 Agent 子任务可分离且角色不同（如旅行计划中的多角色协作、赛博小镇的多个 NPC） 只是想让代码看起来复杂；通信开销、上下文膨胀、调试难度会同步上涨
工具系统 需要外部信息或外部动作（读文件、查库、跑静态分析） 纯文本生成类任务
记忆 / RAG 需要记住用户偏好、跨会话状态，或要检索私有知识库 单轮、无状态、知识全在提示词里的任务
通信协议 工具需要复用外部生态、要跨进程/跨服务调用 工具全是本项目自写的本地函数
上下文工程 工具返回很长、多轮之后上下文明显膨胀 短对话、少量工具调用
Agentic-RL 你能构造出可验证的奖励 + 可反复交互的环境与算力 没有评分器、没法自动判定成败、算力受限（绝大多数毕设属于此类）
性能评估 报告里要给指标（准确率、响应时间等），需要拿数据说话 纯演示型项目也应至少给出响应时间与样例成功率
  • 判断口径的统一原则：每一项加装都必须能回答"去掉它会怎样"。如果去掉后效果没有可观察的差异，那它就是装饰，应该在文档里删掉而不是留在代码里。

4. 项目实施：阶段划分与里程碑

本节同样是串联——阶段名对应 16.4 的开发指南与 16.5 的提交流程，里程碑的判定标准来自本章的测试清单与格式要求。

阶段 目标 里程碑（可验证的完成信号）
0 选题与范围冻结 把痛点、用户、成功标准写成一页纸 能用两三句话讲清"谁的什么痛点、现有工具为什么不行"
1 最小闭环 单 Agent + 一两个工具先把主流程跑通 Notebook 能从头执行到尾不报错，产出第一份结果
2 能力加装 按 3.2 清单逐项加，一次只加一项 每加一项都有前后可对比的效果记录
3 工程化 拆目录、写异常处理、补注释 9 条测试清单全部打勾
4 文档与演示 README、依赖、样例输出、截图或视频 别人只拿仓库就能复现你的结果
5 开源协作 提 PR 并响应 review 建议已改、已回帖、PR 通过合并
  • 阶段 1 最容易被跳过，也最不该跳过：毕设最常见的失败模式是先花大量时间搭多 Agent 架构，最后没有一个完整跑通的演示。先闭环，再加装。
  • 阶段 3 的"异常处理"是原文测试清单里的独立一条（"处理了常见的异常情况"）。参照示例项目的做法：工具函数里对空输入直接返回错误信息，对语法错误做捕获并返回可读提示，而不是让整条链路崩掉。

5. 交付物清单与质量标准

5.1 目录结构

你的用户名-项目名称/
├── README.md            # 项目说明文档
├── requirements.txt     # Python 依赖列表
├── main.ipynb           # 主程序（含快速演示与完整功能）
├── .env.example         # 环境变量示例
├── .gitignore           # 忽略大文件
├── data/                # 数据文件（仅示例数据）
└── outputs/             # 输出结果与截图

当代码量变大时，可再拆出 src/，内部按 agents/、tools/、utils/ 三层组织——这与第 7 章 HelloAgents 的 core / agents / tools 分层是同一种思路：按职责分目录，接口保持统一。

5.2 四类交付物与质量线

交付物 必须包含 质量线
代码 main.ipynb 或 Python 脚本，必要时含 src/ 能正常运行不报错；有适当注释；异常情况有处理；文件和目录命名规范
依赖清单 requirements.txt 列出全部依赖；核心依赖 hello-agents[all]>=0.2.7，可视化可选 matplotlib>=3.7.0、plotly>=5.14.0，Web 可选 fastapi>=0.109.0、uvicorn>=0.27.0
项目文档 README.md 说明清晰、有可照做的使用示例、有亮点与未来计划
演示与报告 outputs/ 下的报告与截图；视频走外链 输出结果符合预期；大文件不入库

5.3 README 的固定章节

一份合格的 README 按这个顺序写：项目名称与一句话描述 → 项目简介（解决什么问题、有什么特色、适用于什么场景）→ 核心功能清单 → 技术栈（HelloAgents 框架、所用智能体范式、工具与 API、其他依赖）→ 快速开始（环境要求如 Python 3.10+、安装依赖、配置 API 密钥、运行项目）→ 使用示例（带代码与运行结果）→ 项目亮点 → 性能评估（准确率、响应时间等）→ 未来计划 → 贡献指南 → 许可证（示例用 MIT）→ 作者信息 → 致谢。

  • 为什么技术栈一栏很关键：它把"我用了哪个范式"直接写在了门面上。示例项目的技术栈写的是：HelloAgents 框架（SimpleAgent + ToolRegistry）、Python AST 模块（代码解析）、ModelScope API（Qwen2.5-72B 模型）——这种粒度正好：说清楚用了什么，不堆名词。

5.4 Notebook 的七段结构（骨架）

第 1 段 项目介绍：名称、简介、作者信息、日期（Markdown 单元格）
第 2 段 环境配置：安装依赖、导入 SimpleAgent / HelloAgentsLLM / BaseTool、load_dotenv()
第 3 段 工具定义：继承 BaseTool，声明 name / description，实现 run(query)->str
第 4 段 智能体构建：创建 LLM -> 创建 Agent(system_prompt=...) -> agent.add_tool(...)
第 5 段 功能演示：示例1 基础功能、示例2 复杂场景，各打印输入与结果
第 6 段 性能评估（可选）：跑评估代码并给出指标
第 7 段 总结与展望：实现的功能、遇到的挑战及解决方案、未来改进方向

这段骨架在干什么：把"能读懂"变成一种结构约束——评审者按 1→7 的顺序读，就自动获得背景、环境、实现、演示、评估、反思六段信息，不必在散乱单元格里找人。

5.5 最小实现的代码骨架

class CodeAnalysisTool(Tool):
    def __init__(self):
        super().__init__(name="code_analysis",
                         description="分析Python代码的结构、复杂度和潜在问题")

    def run(self, parameters):
        code = parameters.get("code", "")
        if not code:
            return "错误:代码不能为空"
        try:
            tree = ast.parse(code)
            functions = [n for n in ast.walk(tree) if isinstance(n, ast.FunctionDef)]
            classes = [n for n in ast.walk(tree) if isinstance(n, ast.ClassDef)]
            return str({"函数数量": len(functions), "类数量": len(classes),
                        "代码行数": len(code.split('\n')),
                        "函数列表": [f.name for f in functions]})
        except SyntaxError as e:
            return f"语法错误:{str(e)}"

    def get_parameters(self):
        return [ToolParameter(name="code", type="string",
                              description="要分析的Python代码", required=True)]

registry = ToolRegistry()
registry.register_tool(CodeAnalysisTool())
registry.register_tool(StyleCheckTool())
agent = SimpleAgent(name="代码审查助手", llm=HelloAgentsLLM(),
                    system_prompt=SYSTEM_PROMPT, tool_registry=registry)
review_result = agent.run(f"请审查以下Python代码:\n\n```python\n{sample_code}\n```")

这段在干什么：它示范了毕设项目的标准装配方式——确定性工作做成工具（ast 解析统计、PEP 8 风格检查），推理与表达交给 Agent，工具的 description 与 get_parameters() 共同构成模型看到的能力说明，最后由 system prompt 把"先调什么工具、报告包含哪几部分、输出 Markdown"三件事约束住。

示例中的风格检查工具只做两件具体判断：行长是否超过 79 字符、缩进是否为 0/4/8/12 空格的规范倍数——这就是"能用代码做的绝不交给 LLM"的落地样子。

5.6 提交前测试清单（验收自查）

  • 代码能够正常运行，没有报错
  • README 文档完整，说明清晰
  • requirements.txt 包含所有依赖
  • 有清晰的使用示例
  • 代码有适当的注释
  • 输出结果符合预期
  • 处理了常见的异常情况
  • 项目结构清晰，文件命名规范
  • 大文件已妥善处理

5.7 大文件规范（硬约束）

约束 数值 / 规则
项目总大小 不超过 5MB
禁止直接提交 视频文件、大型数据集、模型文件
处理方案 外链（推荐）、独立资源仓库、只放示例数据
  • 方案一：外部链接（推荐）。数据集可放百度网盘、Google Drive、Kaggle、HuggingFace Datasets；视频放 B 站、YouTube、腾讯视频；模型放 HuggingFace Models、ModelScope；图片走 GitHub Issues 或图床，并在 README 中给出链接与提取码。
  • 方案二：独立资源仓库。资源多时单独建 项目名称-resources 仓库，README 里写清克隆与拷贝路径。
  • 方案三：只放示例数据。主仓库里保留小规模样例（如 data/sample.csv 100 条），完整数据集（如 10 万条）走外链并在文档中说明。
  • 为什么这么严：主仓库要保持轻量化。一个仓库被几个几百 MB 的文件污染后，所有协作者的克隆成本都会变高——这是开源协作中最典型的"一个人的方便，所有人的代价"。

5.8 提交 Pull Request 的规范

  • 提交流程：git status 检查改动 → git add → git commit -m "feat: 添加XXX毕业设计项目" → git push origin feature/你的项目名称。
  • 提交类型（commit type）：feat 新增功能或项目（毕设用这个）、fix 修复 bug、docs 文档更新、style 格式调整、refactor 重构、test 测试、chore 其他（如依赖更新）。
  • PR 标题格式：[毕业设计] 项目名称 - 简短描述，例如 [毕业设计] CodeReviewAgent - 智能代码审查助手、[毕业设计] StudyBuddy - AI学习伙伴、[毕业设计] DataAnalyst - 智能数据分析师。
  • PR 要填的字段：项目信息（名称、作者、项目类型）、项目简介（2～3 句）、核心功能清单、技术亮点（用了什么范式、实现了什么、优化了什么）、演示效果（截图或 GIF，可选）、自检清单（代码可运行、README 完整、依赖完整、有使用示例、有注释）、其他说明。
  • 分支选择：Base repository 为 datawhalechina/hello-agents、Base branch 为 main、Head repository 为你的 Fork、Compare branch 为 feature/你的项目名称。
  • 响应 review：在 PR 页面查看评论 → 按建议改代码 → git commit -m "fix: 根据review意见修改XXX" → 再次 push → 在 GitHub 上回复说明你的修改。

6. 常见问题与避坑

  1. 为了技术而技术：用上了多 Agent、RAG、RL，但解决的是一个三行脚本就能解决的问题。题目必须顶得住"为什么必须用智能体"这一问。
  2. 跳过最小闭环，直接上大架构：多 Agent 的调试复杂度远高于单 Agent，先跑通单 Agent 主流程再加装。
  3. 大文件混进主仓库：超过 5MB 的项目、视频、数据集、模型文件都属于禁项；提交前用测试清单核一遍。
  4. README 写成散文：评审者按 5.3 的章节顺序找信息，缺"安装依赖/配置密钥/运行项目"就没人能复现你的成果。
  5. API 密钥泄漏：把真实密钥写进 Notebook 并提交是高频事故。示例项目提供的正确做法是：给出 .env.example，把 LLM_API_KEY、LLM_BASE_URL、LLM_MODEL_ID、LLM_TIMEOUT（示例为 60）等参数走环境变量或 .env 文件；main.ipynb 中的 os.environ[...] 写法只是示例占位。
  6. 输出没有落盘：只 print 结果是不够的，把报告写进 outputs/（如 outputs/review_report.md）才能作为交付物被检查。
  7. 只提 PR 不看评论：评审意见不改、不回帖，项目就停在半路；PR 不是一次性动作。
  8. 选题过大：需要持续获取付费数据源、需要训练模型、需要长期运营的题目，在有限时间资源内做不完。
  9. 依赖不全：requirements.txt 漏项会让别人的第一次运行直接失败，这也是测试清单里单列一条的原因。

7. 未来方向与前沿趋势（16.7）

原文章末把"毕设完成"定位成新的起点，并给出四条可继续推进的路径。它们同时也是智能体领域的延伸方向：

方向 具体内容
继续深入理论 更多智能体范式与算法、提示工程与上下文工程、多智能体协作机制
扩展技术栈 学 Web 开发做完整应用、学数据库做数据持久化、学部署把应用上线
打磨项目 添加更多功能、优化性能与用户体验、完善测试与文档
参与社区 帮助其他学习者、参与 Hello-Agents 框架开发、分享经验与心得
  • 与前文技术的接口（串联归纳）：理论学习这条线直接对应第 4 章的经典范式、第 9 章的上下文工程、第 10～11 章的通信协议与 Agentic-RL；"学部署、学数据库、做完整应用"这条线已经在第 13～15 章被示范过三次——旅行助手（多智能体 + MCP 工具集成 + 前端）、深度研究智能体（TODO 驱动 + 服务层 + 前端交互）、赛博小镇（NPC 智能体 + 好感度系统 + 后端服务 + Godot 场景与前后端通信），三者都是"从需求出发设计系统架构，再向下补工程能力"的样例。
  • 趋势层面的判断（原文原话）：AI 技术日新月异，智能体领域充满无限可能；希望保持好奇心持续学习新技术、用 AI 解决实际问题创造价值、把经验与成果分享给社区、不断打磨作品。原文的最强一句收在这：最好的学习方式就是动手实践。

8. 高频考点 & 易错点速查

  1. 项目命名格式 {GitHub用户名}-{项目名称}、PR 标题格式 [毕业设计] 项目名称 - 简短描述——两个格式必考。
  2. 交付物三件套：可运行的 .ipynb / Python 脚本、requirements.txt、README.md；演示视频与数据集是可选且不入主仓库。
  3. 选题三原则：有实用性（不是为技术而技术）、有限时间资源内可完成、能清晰展示技术能力。
  4. 五个选题方向及其定位：生产力工具、学习辅助、创意娱乐、数据分析、生活服务。
  5. 大文件约束：项目总大小 ≤ 5MB；禁提交视频、大型数据集、模型文件；三种处理方案中"外部链接"是推荐项。
  6. commit type 七类（feat/fix/docs/style/refactor/test/chore），毕设用 feat。
  7. 交付质量由"9 条测试清单 + 社区 review"共同把关，PR 提交后必须响应 review 意见。
  8. 易混点：框架提供的便利 ≠ 项目需要的能力——HelloAgents 支持多种范式、记忆、RAG、协议、RL，但毕设要求的是按问题选用，而非全量使用。

9. 与前后章节的衔接

本章是全书收口：输入来自第 1～15 章的全部零件——第 4 章与第 7 章的范式与框架（SimpleAgent、ReActAgent、PlanAndSolveAgent、ReflectionAgent、FunctionCallAgent、ToolRegistry）、第 8 章的记忆与检索、第 9 章的上下文工程、第 10 章的通信协议、第 11 章的 Agentic-RL、第 12 章的评估指标，以及第 13～15 章三个完整项目提供的三套架构范例。输出是一个属于你自己的、可被别人跑起来的开源作品。至此没有后续章节：读完本章，剩下的动作只有一件——选一个题目，把最小闭环先跑通。

10. 课后练习

在线试卷：https://md-quiz-online.app.workbuddy.host/

posted @ 2026-09-28 17:12  测试小罡  阅读(12)  评论(0)    收藏  举报