Wiki Notes

Appearance

08. 项目实战与作品集 ​

版本：v1.3

最后更新：2026-07-09

适用对象：准备通过 Agent 项目积累真实工程经验、沉淀作品集、做团队分享、准备面试或内部转岗的学习者与工程师

1. 为什么项目是 Agent 学习的核心 ​

Agent 这类能力，只看文档很难真正掌握。

你必须通过项目来学习：

  • 什么时候设计出问题
  • 哪一步最容易不稳定
  • 工具该怎么切
  • 状态该怎么存
  • 评测该怎么做

所以，项目不是“学完之后再做”，而是学习本身。

如果你想先看一篇同时把 LLM 与 Agent 放在一起比较、并且带完整 Claude 风格示例代码的专题，建议先跳到：

2. 建议的项目顺序 ​

建议按下面顺序推进：

  1. 单工具 Agent
  2. 多工具 Agent
  3. 知识库 Agent
  4. Router Agent
  5. 审批型 Agent
  6. 完整业务 Agent

这个顺序的好处是：

  • 难度逐步上升
  • 每个项目都能复用上一个项目的经验

更稳妥的推进原则是：

  • 每做完一个项目，都把“为什么不需要更复杂模式”写下来

根据 Anthropic《Building Effective AI Agents》与 OpenAI Building agents 学习路线在 2026-07-07 可访问的说明，真实项目里最有价值的能力之一，不是你会不会一上来做多 Agent，而是你能不能证明：

  • 先用更简单的形态已经不够了

3. 做项目时，先写一页“边界说明”再开工 ​

很多 Demo 做到后面越来越乱，不是因为代码不够多，而是因为开工前没写清楚这几个问题：

  1. 用户真正要解决什么问题。
  2. 为什么这个问题需要 Agent，而不是单次调用或 workflow。
  3. 哪些外部系统要接入。
  4. 哪些动作有副作用。
  5. 哪些地方必须人工审批。

建议每个项目先写一个一页纸设计稿，至少包含：

项目字段需要写清楚什么
problem真实问题是什么
why_agent为什么不能只用 workflow
tools需要哪些工具
state哪些状态必须持久化
approval哪些动作必须审批
eval用什么方式判断改动变好

如果这页写不出来，后面项目通常会越做越像“把模型接到了几个接口上”。

4. 项目 1：单工具 Agent ​

目标：

  • 学会最小工具调用闭环

推荐题目：

  • 天气查询助手
  • 搜索问答助手

必做点：

  • 工具 schema
  • 参数校验
  • 错误处理

验收标准：

  • 能稳定调用工具
  • 能在失败时给出合理反馈

额外建议：

  • 记录最小 trace：用户输入、工具请求、工具返回、最终回答
  • 故意制造 2 到 3 种失败情况，例如参数错误、空结果、超时

作品集表达重点：

  • 不要只说“我做了个天气助手”
  • 要说“我如何设计工具 schema、失败反馈和最小观测”

5. 项目 2：多工具 Agent ​

目标：

  • 学会让模型在多个工具中做选择

推荐题目：

  • 搜索 + 网页读取总结助手
  • 文件检索 + 问答助手

必做点：

  • 工具说明清晰
  • 避免工具混用
  • 记录工具调用链

验收标准：

  • 能解释为什么选这个工具而不是另一个

额外建议：

  • 不要默认把所有工具都暴露给模型
  • 记录至少一个“缩小工具面后更稳定”的例子

作品集表达重点：

  • 为什么这里是多工具选择，而不是 Router 或多 Agent
  • 工具边界怎么控，失败怎么兜住

6. 项目 3：知识库 Agent ​

目标：

  • 学会把 RAG 放进 Agent 体系

推荐题目：

  • 本地文档问答
  • 产品手册问答
  • 课程资料问答

必做点：

  • 文档切分
  • 检索
  • 引用来源
  • 失败样本分析

验收标准：

  • 用户能看到答案基于哪些内容

额外建议：

  • 明确把“检索失败”和“生成偏离证据”分成两类问题
  • 保留 10 条左右失败样本，开始积累最早的一版评测集

作品集表达重点：

  • 你的系统如何处理引用、忠实性和无答案场景
  • 你如何证明它不是“看起来像知道，其实在猜”

7. 项目 4：Router Agent ​

目标：

  • 学会问题分类与路径分发

推荐题目：

  • 客服请求分类助手
  • 企业内部问题分流助手

必做点：

  • 路由标准
  • 分类失败兜底
  • 不同路径的工具边界

验收标准：

  • 能统计不同类型请求的分流准确度

额外建议：

  • 为每个路由分支定义失败兜底
  • 不要把 Router 和多 Agent 混为一谈，先把它当成入口分发层

作品集表达重点：

  • 你的分类标准是什么
  • 错分流后系统怎么回退

8. 项目 5：审批型 Agent ​

目标：

  • 学会处理高风险动作

推荐题目：

  • 发邮件助手
  • 工单创建助手
  • 数据更新建议助手

必做点：

  • 读写分离
  • 审批节点
  • 审计日志

验收标准：

  • 没有审批时不能执行高风险动作

额外建议：

  • 审批对象至少保留工具名、参数快照、审批人、决策原因和最终执行结果
  • 明确区分 guardrails 和 approvals，不要把“规则校验”和“人工决策”混成一层

作品集表达重点：

  • 高风险动作为什么必须审批
  • 审批通过前后，系统状态分别是什么

9. 项目 6：完整业务 Agent ​

目标：

  • 把前面所有能力整合起来

推荐题目：

  • 研究与报告助手
  • 企业知识库行动助手
  • 客服工单处理助手
  • 代码解释与修复助手

必做点：

  • 工具
  • 状态
  • 上下文工程
  • 审批
  • 评测
  • README

验收标准：

  • 不是只会演示，而是能说明架构与边界

额外建议：

  • 准备一份失败回放或事故样例，不要只展示 happy path
  • 至少说明一个“后来为什么不得不从单 Agent 升级到 Router / workflow / graph”的真实原因

作品集表达重点：

  • 你的系统是怎么迭代出来的
  • 最不稳定的一层是什么，你是怎么把它补稳的

9.1 每个项目最好都按“里程碑”推进，而不是一口气做完 ​

很多 Agent 项目最后烂尾，不是因为方向不对，而是因为目标太大、边界太散。

更实用的做法通常是给每个项目拆成四个里程碑：

里程碑目标产出
M1 最小闭环能跑通主流程CLI / Web Demo、最小工具链
M2 稳定化能处理基本失败错误语义、fallback、最小 trace
M3 治理化能被解释和评估eval 集、失败桶、README、架构图
M4 展示化能给别人看懂demo 脚本、截图、回放样例、项目说明页

这四步的价值在于：

  • 先把“能跑”做出来
  • 再补“能解释、能评估、能展示”

比起一开始就想着：

  • 多 Agent
  • 全量工具
  • 复杂前端

通常更稳。

9.2 一个像样的 Agent 项目，最好至少留下一套 demo asset pack ​

很多项目代码写了不少，但最后很难展示，因为除了仓库本身几乎没有可复用素材。

更像作品的做法通常会同步沉淀一套 demo asset pack，至少包括：

  • 一张架构图
  • 一份项目一页纸
  • 一组演示输入
  • 一组失败样例
  • 一份 trace 或步骤回放截图
  • 一份评测摘要
  • 一段风险边界说明

这样你后面无论是：

  • 给面试官讲
  • 给团队做分享
  • 写博客
  • 做 README

都不会只能临时现场跑一遍。

10. 一个高质量 Agent 项目应该包含什么 ​

至少要有：

  1. 项目目标
  2. 场景说明
  3. 为什么选择 Agent
  4. 架构图
  5. 工具列表
  6. 状态设计
  7. 评测方法
  8. 安全边界
  9. 已知问题
  10. 后续优化方向

如果这些内容都没有，项目很容易看起来只是“跑通了个 Demo”。

更进一步，建议再加 4 个对象：

  1. 失败样本分桶
  2. trace 截图或结构化观测说明
  3. 审批 / 安全策略说明
  4. 成本和时延基线

这样项目就更像工程作品，而不是课堂练习。

10.1 再往上补一层，最好把“项目资产对象”也定义清楚 ​

如果你真的想把项目做成可长期维护的作品，建议至少维护这几类资产对象：

资产对象作用
design_doc说明问题、边界、模式选择
tool_contracts说明工具 schema、错误语义、审批边界
state_schema说明状态、记忆、恢复点
eval_bundle说明样本、graders、must-pass cases
trace_samples说明 happy path 与 failure path
release_notes说明每轮迭代为什么改、改后变好在哪

这会让你的项目从：

  • “一个仓库”

进化成：

  • “一套可解释的工程资产”

10.2 最值得展示的，不是功能数量，而是工程判断 ​

很多作品集会把重点放在：

  • 接了多少工具
  • 做了多少页面
  • 支持多少模式

但在真实面试或评审里，更容易打动人的通常是这些问题：

  • 为什么先从单 Agent 起步
  • 为什么后来不得不加 Router / approval / graph
  • 为什么这个工具被拆成读写两层
  • 为什么这个状态必须持久化
  • 为什么这个高风险动作不能自动执行

换句话说：

  • 工程判断 往往比 功能堆叠 更能说明能力

11. README 建议结构 ​

建议你的 README 至少有这些部分：

  1. 项目简介
  2. 使用场景
  3. 系统架构
  4. 技术栈
  5. 运行方式
  6. 工具说明
  7. 状态与流程说明
  8. 评测方法
  9. 风险边界
  10. 后续计划

如果项目要拿去求职或做团队分享，README 最好再补两块：

  • Failure cases：系统最容易错在哪里
  • Trade-offs：为什么采用当前模式，而不是更复杂或更简单的方案

11.1 README 最好再补一段“如何验证这个项目” ​

很多仓库 README 能说明“怎么跑”，但看不出“怎么验证它值不值得信”。

建议至少再补一段：

  • 有哪些 must-pass cases
  • 哪些样例是故意保留的失败案例
  • 当前最大风险边界是什么
  • 哪些数据和截图来自真实运行，而不是静态编造

这会让项目明显更可信。

12. 作品集怎么写才有说服力 ​

很多人作品集的问题，不是项目少，而是不会讲。

写作品集时，不要只写：

  • “我做了一个 AI Agent”

更有说服力的写法是：

  1. 我解决了什么问题
  2. 为什么这个问题需要 Agent
  3. 我用了哪些工具和状态设计
  4. 我如何处理高风险动作
  5. 我怎么评测效果
  6. 当前已知问题是什么

这类表达会明显更像工程实践，而不是实验截图。

更进一步的表达方式通常是：

  • 我最初用了什么简单方案
  • 它卡在了什么问题
  • 我为什么升级成当前架构
  • 升级后哪些指标变好了，哪些问题还没解

这种写法会让读者更容易相信你不是“堆概念”，而是真的做过取舍。

12.1 最好准备一个“5 分钟讲完”的项目版本 ​

很多项目并不是不够好，而是讲得太散。

更实用的准备方式通常是给每个重点项目都做一个 5-minute pitch，结构可以固定成：

  1. 这个问题为什么真实存在
  2. 为什么不是普通工作流
  3. 架构最关键的一个取舍是什么
  4. 最后系统最容易错在哪
  5. 你怎么用 eval / trace / approval 把它补稳

如果这五句讲不清，项目再大也容易显得空。

13. 求职视角下最值得做的项目类型 ​

如果你偏：

AI 应用工程师 ​

优先做：

  • 知识库 Agent
  • 研究助手
  • 报告生成助手

企业 Agent / 自动化方向 ​

优先做：

  • 工单助手
  • 审批型 Agent
  • CRM/文档系统整合助手

LLM 平台 / Agent 基础设施方向 ​

优先做：

  • MCP server
  • 工具平台
  • 状态工作流
  • 评测平台

更务实的建议是：

  • 不要同时做 6 个半成品
  • 最好做 2 个方向不同、但每个都能讲清边界与评测的项目

因为在求职里，可解释的工程取舍 往往比 项目数量 更有说服力。

13.1 如果想面企业内部 Agent / 平台方向，项目里最好显式展示这些对象 ​

很多人项目能跑，但一看就还是 demo 味很重。

如果你想往企业 Agent、Agent 平台、自动化治理方向走，项目里最好显式展示：

  • tool registry
  • approval object
  • trace sample
  • state schema
  • risk matrix
  • eval bundle

因为这些对象会明显体现：

  • 你不是只会接模型
  • 你理解的是系统，而不是单个 prompt

13.2 MCP、Skill、Tool 最好单独说明，不要混成一句“我接了很多能力” ​

很多项目介绍里最容易糊成一团的，就是：

  • tool
  • skill
  • MCP

更实用的区分通常是：

概念更像什么在项目里最该展示什么
Tool一个可调用能力单元schema、参数、错误语义、副作用边界
Skill一组可复用的方法包 / 任务配方适用场景、输入输出契约、什么时候触发
MCP一个把 tools / resources / prompts 标准化暴露出来的协议层server 边界、授权、租户隔离、暴露能力面

如果你是做作品集，最值得讲清楚的是：

Tool 应该怎么讲 ​

不要只说：

  • “我接了搜索工具、数据库工具、发邮件工具”

更有说服力的说法通常是：

  • 工具怎么拆成读写两层
  • 参数为什么这样设计
  • 错误语义和幂等性怎么处理
  • 哪些工具必须审批

Skill 应该怎么讲 ​

Skill 在不同平台里的叫法不完全一样，它不是像 MCP 那样的统一协议，更像：

  • 可复用的任务能力包
  • 某类问题的标准处理方法
  • 一组 prompts、tools、rules 和输出契约的组合

所以作品里更值得展示的是：

  • 这个 skill 解决什么重复问题
  • 它依赖哪些 tool / state / guardrail
  • 它的输入输出边界是什么
  • 什么时候应该触发，什么时候不该触发

MCP 应该怎么讲 ​

如果你做了 MCP server，不要只写：

  • “支持 MCP”

真正更能体现能力的是：

  • 暴露了哪些 tools / resources
  • 这些能力为什么适合做成协议层
  • OAuth / token / tenant / approval 怎么设计
  • 为什么这层不是直接散在业务代码里的函数调用

13.3 一个最容易打动人的讲法：先讲层级，再讲实现 ​

你可以用下面这个顺序讲自己的项目：

  1. Tool 层：我有哪些基础能力单元
  2. Skill 层：我把哪些重复任务抽成了复用能力
  3. MCP 层：我把哪些能力做成了标准化接入层

这样别人就更容易看出来：

  • 你不是只会写几个函数
  • 也不是只会堆一堆 prompts
  • 而是在搭一个可复用、可治理、可扩展的 Agent 系统

14. 一个项目什么时候算“从 Demo 进化成作品” ​

你可以用下面这张检查表来判断：

维度只有 Demo已经接近作品
目标定义只是能跑问题和边界清楚
工具设计有调用就行schema、错误和副作用清楚
状态治理靠对话历史撑住有状态字段和恢复思路
安全边界基本没写guardrails、approval、最小权限清楚
评测凭感觉有数据集、失败桶或前后对比
说明文档只有截图README、架构图、已知问题齐全

只要后面这一列能占大多数，这个项目就已经不只是“演示一下能跑”。

14.1 如果再往前走一步，它就不只是“作品”，而是“可交付方案” ​

一个项目从作品继续升级，通常会开始补这些东西：

  • release notes
  • 版本化 eval 结果
  • 风险门禁
  • 回放资产
  • 产物与执行记录

这时你展示的就不再只是：

  • “我做了一个 Agent”

而更像：

  • “我做了一套可以持续迭代的 Agent 系统”

15. 最容易让作品集掉价的几个问题 ​

  1. 只展示 happy path，不展示失败与约束。
  2. 说自己做了 multi-agent，却讲不清为什么不能用单 Agent。
  3. 提到评测，但没有任何样本、失败桶或对比结果。
  4. 提到安全，但没有审批、最小权限或护栏说明。
  5. 项目能跑，却没有 README、架构图和清晰边界。

这些问题单看都不大，但会直接让作品显得像“试了一下框架”。

15.1 还有一个特别常见的问题：没有基线，只剩“我觉得现在更好了” ​

很多人会说：

  • 这版效果比之前好

但拿不出：

  • 样本对比
  • 失败桶变化
  • trace 证据
  • 成本和时延变化

这会直接削弱说服力。

哪怕只是最小基线，也建议至少保留：

  • 10 到 20 条样例
  • 一轮旧结果
  • 一轮新结果
  • 失败分类变化

这样作品就会更像真实工程迭代。

16. 重点官方资源 ​

17. 本章后的行动建议 ​

现在就可以做的事情：

  1. 从 6 个项目里选 2 个
  2. 为每个项目写一页设计文档
  3. 每个项目先回答“为什么不是普通工作流”
  4. 每个项目都写评测和安全边界

做到这一步，你的 Agent 学习就不再只是“收藏资料”，而是已经进入真正能沉淀能力的阶段。