🎯 今日核心问题

  1. 招聘方打开仓库,前 15 秒看哪几样东西?看不到就关掉的是什么?
  2. 为什么「技术亮点」不能写成功能清单?怎么写才能引出面试提问?
  3. 文档要写到什么程度算够?写多了也是负担。

📖 精读提纲

【一】前 15 秒:架构图 + 三个指标 + 一句定位

打开仓库的人不看代码,先扫 README。决定是否继续的判断顺序是:这句话说清它是干什么的吗 → 有没有一张能看懂的架构图 → 有没有数字 → 有没有测试和演示。

所以 README 第一屏(不滚动就能看到)必须包含四样:一句话定位、架构图、三个量化指标、一条起服务的命令。四个都有,面试官才会往下翻目录。

一句话定位的模板:<谁> 用 <什么机制> 解决 <什么问题>,把 <指标> 从 A 提到 B。反例:「一个基于大模型的企业级智能体平台」。正例:「给客服团队用的工单 Agent,把首次响应从 4 分钟压到 40 秒,答案引用可回溯到知识库原文」。

【二】架构图用文字版也能打动人

不用画得多漂亮,一张 Mermaid 图 + 一句分层说明,比截图堆砌强十倍。关键是让人一眼看出:模型在最内层,外面有工具层、持久层、可观测层。这就是「你不是在调 API」的视觉证据。

图下面紧跟一段「为什么这么分」:一句话说明每层的职责与依赖方向。这一段是给面试官的问题递刀——他一定会问「为什么工具要独立一层」。

【三】技术亮点写「问题 → 方案 → 数字」

每一条按三段式写,字数控制在 60 字以内:

前者是功能描述,后者是工程叙事。每一条亮点都埋一个可被追问的钩子,你提前准备答案,面试就变成了你的主场。三条亮点足够,写五条反而暴露重点不清。

【四】文档的完整清单(不要更多)

README.md(第一屏 + 亮点 + 快速开始 + 目录结构)、docs/architecture.md(分层与关键决策 ADR)、docs/api.md(接口与错误码表)、docs/eval.md(指标定义与测量方法)、docs/runbook.md(常见故障处置)、docs/scope.md(D1 写的边界)。

关键是 ADR(决策记录):每个「为什么不选 X」写 100 字。这是最容易被面试官当成加分项的东西——它证明你做过权衡,而不是照教程抄。

另外:LICENSE(MIT 或 Apache-2.0)、.env.example、一个 30 秒的 GIF 演示。GIF 比视频好,因为不需要点播放。

【五】README 第一屏的四件事

一句话定位、一张架构图、三个带测量方法的数字、一条起服务的命令,四样都要在不滚动的情况下看到。做到了,面试官才愿意往下翻目录;做不到,仓库再完整也只是一行「项目经历」。

💻 代码示例

README 骨架(可直接抄,把服务名和指标换成自己的):

# agent-ticket

> 给客服团队用的工单 Agent:首次响应 4 分钟 → 40 秒,每条结论可回溯知识库原文。

![build](https://img.shields.io/badge/build-passing-green)
![tests](https://img.shields.io/badge/regression-42%2F42-blue)
![license](https://img.shields.io/badge/license-MIT-lightgrey)

**[快速开始](#快速开始) · [架构](docs/architecture.md) · [评测](docs/eval.md) · [Runbook](docs/runbook.md)**

## 它解决什么

客服每天处理 300+ 售后工单,需要手工翻知识库、查订单。
本服务把「意图识别 → 知识检索 → 订单核对 → 草稿生成」串成一个 Agent,
人工只需确认与发送。

## 架构

flowchart LR

U[前端] --> C[Controller]

C --> A[Agent Loop]

A --> T[Tool Layer]

A --> L[LLM Client]

T --> D[(MySQL)]

T --> V[(向量库)]

A --> O[Trace/指标]


模型只出现在 Agent Loop 内;工具、持久化、可观测均可独立测试与替换。

## 三个数字

| 指标 | 结果 | 怎么测的 |
|---|---|---|
| 意图+草稿一次通过率 | 86%(基线 61%) | 120 条历史工单回归集 |
| 端到端 P95 | 6.8s(基线 14s) | 压测 200 并发 |
| 工具失败自动降级率 | 97% | 注入 500/超时故障演练 |

## 快速开始

cp .env.example .env # 填入 LLM_API_KEY

docker compose up -d

curl -X POST localhost:8080/api/agent/chat \

-H 'Content-Type: application/json' \

-d '{"question":"订单 A10086 到哪了"}'

【六】文档的三个常见错误

把注释搬进文档——写「ToolRegistry 用于注册工具」等于没写,有价值的只有:为什么这么设计、出问题怎么查、改这里牵连什么。没有错误码表——必须有 errorCode → 含义 → 前端表现 → 处置建议。截图代替图——截图过期且不可 diff,用 Mermaid 写进 Markdown。

【七】开源仓库的最后一公里

代码能跑不等于别人能跑。验收标准只有一条:cp .env.example .env 后 docker compose up 能起。需要每个变量带注释、数据库初始化脚本自动执行、README 的 curl 示例真能返回 200。star 不必强求,但有 CI 徽章、有 tag、有能看出迭代节奏的 commit 历史,比 star 有说服力。

✏️ 今日动手

按上面的骨架写完 README,补 docs/architecture.md 与三条 ADR(选 ReAct 而非 Plan-Execute、选压缩而非扩大上下文窗口、选 MySQL JSON 存 trace 而非建关联表)。录一个 30 秒 GIF:从提问到工具调用到引用高亮。

🔖 明日预告

最后一天:把这个项目翻译成简历上的一行、面试里的十五分钟,以及一张能扛住追问的答案卡。