🏠 总目录📚 本教程 17 · 实战项目 ← →
📑 本页目录（点开跳转）

17 · 实战项目

⏱ 三个项目，每个 1–3 天 ｜ ⭐ 不做项目 = 没学过

🎯 一句话

三个递进的项目：单 Agent → 带验证循环 → 多 Agent。做完你就有了完整的手感。

💰 成本提示：项目一用第 1 章的 MockModel 可以零成本开发调试，逻辑通了再换真模型。 项目二三建议用中档模型，全部做完大概几美元。

🧠 ADHD 专属：怎么保证做得完

项目是最容易半途而废的东西。三条规则：

  1. 先跑通最烂的版本。 别一开始就想做完美。烂版本能跑 = 已经赢了 80%
  2. 每个项目切成 ≤1 小时的任务（下面已经切好），完成一个打勾
  3. 不允许优化「还没跑通的东西」。跑通 → 打勾 → 才准优化

🚫 必须避免：花两天配环境。用最简单的方式跑起来，工程化以后再说。

🥉 项目一：终端研究助手（1 天）

目标：一个能「搜资料 → 读内容 → 给出带引用的回答」的命令行 Agent。

练什么：第 1 章的循环 + 第 7 章的工具设计。

任务清单

🔨 关键代码片段

def search_web(query: str, max_results: str = "5") -> str:
    """搜索网页。返回标题、摘要和链接，不返回正文。
    需要正文时用 read_page(url)。"""
    results = do_search(query, int(max_results))
    if not results:
        return f"没有找到关于「{query}」的结果。试试更宽泛的关键词。"
    return "\n".join(
        f"[{i}] {r.title}\n    {r.snippet[:150]}\n    {r.url}"
        for i, r in enumerate(results))      # ⭐ 用短索引不用 UUID（第7章）

def read_page(url: str) -> str:
    """读取网页正文。内容会被截断。"""
    text = extract_main_text(url)
    LIMIT = 3000
    if len(text) > LIMIT:
        return (text[:LIMIT] +
                f"\n\n[正文已截断，原文共 {len(text)} 字。"
                f"如需后续内容，说明你要找什么，我会重新提取相关段落]")
    return text

✅ 通关标准

🎁 加分

🥈 项目二：带验证循环的代码修复 Agent（2 天）

目标：给它一个带失败测试的 Python 小项目，它自主「跑测试 → 读报错 → 改代码 → 再跑」直到全绿。

练什么：第 5、12 章的验证循环 —— 这是 Agent 编码能力的核心机制。

任务清单

🔨 关键：run_tests 的返回设计

def run_tests() -> str:
    """运行测试套件，返回失败摘要。"""
    r = subprocess.run(["pytest", "-q", "--tb=short"],
                       capture_output=True, text=True, timeout=120)
    if r.returncode == 0:
        return "✅ 全部测试通过。"
    # ⭐ 只返回失败部分，不返回全量输出（第4章：控制上下文）
    fails = extract_failures(r.stdout)      # 解析出失败的测试名 + 简短 traceback
    return (f"❌ {len(fails)} 个测试失败：\n\n" +
            "\n\n".join(f"{f.name}\n  {f.short_trace}" for f in fails[:5]) +
            (f"\n\n[还有 {len(fails)-5} 个失败未显示]" if len(fails) > 5 else ""))

✅ 通关标准

🥇 项目三：多 Agent 文档流水线（2–3 天）

目标：编排器-工作者架构——输入一个主题，产出一份多来源、经过审查的研究报告。

练什么：第 13 章的多 Agent 协作 + 第 4 章的上下文隔离。

架构

   编排器（大模型）
     │ 拆解主题 → 3-5 个子问题（结构化委派）
     ├──► 研究工作者1（小模型，独立上下文）──► 500字摘要+来源
     ├──► 研究工作者2 ──► 摘要+来源
     ├──► 研究工作者3 ──► 摘要+来源
     │ 综合成初稿
     ▼
   审查者（独立上下文）：核查引用、找矛盾、按 rubric 打分
     │ 不合格 → 带意见退回编排器（最多 2 轮）
     ▼
   最终报告

任务清单

🔨 关键：结构化委派

subtasks = [
  {"goal": "找出 2026 年 Q2 三家主要竞品的定价变化",
   "output_format": "每家一段，含具体价格和变化时间，300字以内",
   "tools": ["search_web", "read_page"],
   "boundaries": "只看官方定价页，不要看第三方评测；不要分析原因（别人在做）"},
  ...
]

🔨 关键：审查 rubric

REVIEW_RUBRIC = """按四个维度审查报告，每项 0-25 分：
- 引用完整：每个事实结论都有来源吗？
- 引用有效：来源真的支持该结论吗？（抽查 3 条）
- 覆盖完整：子问题都被回答了吗？
- 内部一致：有互相矛盾的说法吗？

输出 JSON：{"引用完整":分,"引用有效":分,"覆盖":分,"一致":分,
           "必须修复":["..."], "通过":true/false}
低于 70 分不通过。"""

✅ 通关标准

📝 项目 README 模板（作品集用）

# 项目名
## 它做什么（一句话 + 一张架构图）
## 关键设计决策
- 为什么这里用工作流不用自主 Agent（附降级测试数据）
- 工具返回为什么这么设计（附 token 对比）
- 验证为什么分离（附审查者抓出的真实案例）
## 成本与表现
| 任务 | 轮数 | token | 成本 | 结果 |
## 踩过的坑        ← ⭐ 这一节最加分
1. ...

🔑 「踩过的坑」最加分——它证明你真的做过，而不是抄的教程。

🔗 这一章连到哪里

去哪 为什么
Kaggle 25 ⭐「先跑通最烂的版本，再逐环替换」—— 这套做法的方法论出处
上线之后 20 项目跑通之后的下一半：上线、监控、发现它悄悄变差
全景导论 16 做完这几个项目，用它来决定下一个方向挖哪里

✅ 检查点

  1. 三条通用规则是什么？为什么「先跑通最烂版本」排第一？
  2. 研究助手项目里，「找不到就明说，不许编」为什么必须写进提示词？
  3. 工具返回内容为什么要截断？不截断会怎样？
  4. 代码修复 Agent 的 run_tests 为什么只返回失败摘要，而不是完整输出？
  5. 为什么审查 Agent 必须用独立上下文？
  6. T6「故意给一个错的测试」这个实验在测什么？
  7. 项目三的 T7 等预算对照实验回答了什么问题？为什么这个问题重要？
👀 答案
  1. ①先跑通最烂版本 ②任务切成 ≤1 小时的块 ③没跑通不准优化。第一条排第一是因为一条能从输入跑到输出的完整链路，会立刻告诉你瓶颈在哪——而半成品连"哪一环最弱"都看不出来。
  2. 因为模型的默认倾向是"给出一个答案"而不是"承认不知道"。不显式授权它说"找不到"，它就会编一个看起来合理的。这是幻觉最常见的来源之一。
  3. 因为工具返回的内容会全部进入上下文。一个返回 5 万字网页正文的工具，两次调用就把预算吃光了。不截断的直接后果是上下文腐烂，Agent 在第 5 轮就开始忘记任务目标。
  4. 同理——完整测试输出里绝大部分是"通过"的噪声。只返回失败摘要，既省上下文，又让模型的注意力集中在真正要修的地方。
  5. 因为共享上下文的审查会被"生成过程"污染——它看过那些推理，会倾向于认同。独立上下文的审查者只看产出物，判断更接近真实的第三方视角。🔗 这是第 12 章「生成与评估分离」的落地。
  6. 测模型会不会盲目迎合。给一个明显错误的测试，正确的行为是指出测试本身有问题，而不是改代码去迁就它。这直接对应第 12 章说的谄媚倾向。
  7. 回答「多 Agent 那 15 倍的 token 消耗，换来的效果提升值不值」。重要是因为多 Agent 的成本是隐性的——不做对照实验，你只会看到"效果好像更好了"，而看不到代价。很多任务用单 Agent + 好工具就够了。

🛑 完成了？

三个高难度挑战在等你，每个都对准一个「普通项目练不到」的核心矛盾：

⚡ 走神救援

三个递进项目：①研究助手（第1章循环+第7章工具设计，关键是"找不到就明说不许编"（模型默认倾向是给答案而不是承认不知道）+工具返回要截断（不截断会直接吃光上下文预算→第5轮就忘了任务目标））②代码修复Agent（验证循环改→测→读，run_tests只返回失败摘要——完整输出95%是"通过"的噪声；加独立上下文的审查Agent（共享上下文的审查会被生成过程污染，倾向于认同）；T6故意给错的测试看它会不会盲目迎合——正确行为是指出测试有问题）③多Agent流水线（结构化委派防重复劳动+rubric审查+退回只重跑有问题的部分；⭐T7等预算对照实验回答"15倍token换来的提升值不值"——多Agent的成本是隐性的，不做对照你只会看到"好像更好了"）。三规则：先跑通最烂版本（完整链路能立刻告诉你瓶颈在哪）、切成≤1小时任务、没跑通不准优化。

打卡记录保存在你的浏览器里，首页能看到总进度