大家好 👋，我是 Moment，目前正在使用 Next.js、NestJS、LangChain 开发 DocFlow。这是一个面向 AI 场景的协同文档平台，集成了基于 Tiptap 的富文本编辑、NestJS 后端服务、实时协作与智能化工作流等核心模块。

在这个项目的持续打磨过程中，我积累了不少实战经验，不只是 Tiptap 的深度定制、编辑器性能优化和协同方案设计，也包括前端工程化建设、React 源码理解以及复杂项目架构实践。

如果你对 AI 全栈开发、文档编辑器、前端工程化或者 React 源码相关内容感兴趣，欢迎添加我的微信 yunmz777 一起交流。觉得项目还不错的话，也欢迎给 DocFlow 点个 star ⭐

这两年和别人聊下来，有个挺朴素的观察：工具都差不多，Cursor、Claude Code、Copilot 换来换去，有人照样顺滑往前推，有人却被 AI 拖进更深的坑里。倒不一定是模型突然变差了，更像是仓库本身经不起这么快地改——你一提速，漏的地方也跟得上提速。

我这边遇到过无数次那种很无聊的返工。后端字段改了，前端忘了跟。或者看起来类型都对，实际请求体还是对不上。编译绿灯，线上才发现分支走错。一出问题就先怀疑 prompt，改了两轮发现不对劲——常常是仓库里没有一套固定的摆放方式，模型猜这一步猜对了，下一步就和别处打架。

所以到了 2026 年，我反而更多把 NestJS 和 Monorepo 当作默认选项，不是因为它们听起来高级，单纯是省事：目录大致怎么长、模块怎么切、前后端能不能共用同一份类型说明，至少有个大家都认的底子。AI 跟着改文件的时候，不至于今天一套写法、明天换一套，你自己回看也少猜谜。

以前挑框架会问写着爽不爽。现在会先想过两个月再来需求，我还能不能一眼看出该动哪几块。NestJS + Monorepo 谈不上惊艳，只是让我觉得没那么容易失控。

写出来的快，后面收拾慢

现在问 AI 顺手写一段，在圈里早不新鲜了。身边人多少都会用用 Cursor、Copilot 一类，写 TS、改多文件的仓库，编辑器也更好跟一点。

省时间的是样板、CRUD、第一遍类型、顺带出来的测试草图。多文件改、读完再改、跑完再交 diff，大家也都摸熟了。网上还有一大把规则文件和模版，抄一抄就能开张。

麻烦的是它仍然吃你仓库长什么样。上下文一碎，就只能对着当前文件蒙，旧接口的臭毛病还能被带回来。约定没写进结构里，同一天里 ValidationPipe、手写 if、跳过注入直接 new 能并存。跨包改一半留一半、临上线才逐行对 diff，都常见。有人习惯 AI 打一版自己再改，省下的时间往往又赔在契约和安全上。

把这些和日常开发叠在一起看，AI 写代码早就不算新闻。起接口、跑 CRUD、补两层类型、顺带生成点测试，交给模型去做，往往不慢，第一眼看上去也像那么回事。别扭的是后半程：很多时候它不是写出 0 分，而是那种能跑、像样、却不对劲的 80 分——lint 不吵，预览也能点开，但分层含糊、命名各写各的、同一个概念在不同文件里换了三张脸。你要是真顺着往下叠需求，常常要到第二、第三次改动才猛然醒悟，省下来的时间没花在第一版上，全花在给前面的草率擦屁股上。

后面这几类我最熟：改一个字段，前后端各漏一处；鉴权相关的判断补丁似的散落在好几个文件里；新开的功能完全是另一套文件夹脾气；类型检查安安静静，DTO、落库和前端调用却已经各走各路。偶尔也会嘀咕，这算不算真省力。

我以前也会比谁敲得快、谁能更快翻出文档。现在更在乎仓库省不省返工，少折腾比好看重要。上下文窗口再大，翻起来顺不顺还是看你自己怎么摆文件夹。

好几个仓库并排的时候

很长一段时间里，我都觉得多 repo 很正常：前端一个仓，后端一个仓，再加共享类型包、组件库，听起来分工清清楚楚。

真到了天天开工、AI 也跟着一起改的时候，摩擦就出来了——业务明明是一套东西，代码却被切成几块互不接壤的地盘，没有哪个仓库能单独回答这一整块系统在干什么。人还能靠记忆和聊天记录勉强对齐，模型手里往往只有当前文件附近那点片段，它没有你那套我懂的脑内地图。

后果都很具体：字段名对不齐，import 指到老路径，接口说明还停留在上个版本，这边改了那边没人提醒，前后端各讲各的故事。于是就经常出现那种撕裂：嘴上都说 AI 很强，手头却在骂它不靠谱；细看往往不是模型突然变笨，而是你根本没给它看过全貌，它只能瞎蒙。

Monorepo 对我来说最实在的一条，就是相关代码至少在一个 workspace 里，搜得到、跳转不瞎跳，改一处牵动谁早一点露馅。

单 workspace 那点实在的好处

大家聊 Monorepo，常常一上来就是依赖 hoist、构建缓存、CI 提速、版本对齐——这些都实打实地省钱省时间。若你用的是 Turborepo、Nx 这类任务编排，改 libs/types 再触达 apps/web 时，turbo run build --filter=... 一类命令往往只跑受影响的那几条边，CI 和本地反馈都轻一些；AI 一口气动多个包的时候，也不太容易因为全量 build 太慢把思路打断。但我日常感触更深的，反而是更土的几件事：全局搜索能跨过 apps 和 libs，跳转定义不会再跳到另一个克隆仓库；开一个合并请求可以同时改 apps/api、前端调用处和 libs/types，评审的人也不用先在脑子里拼接三四份改动。

产业报告里偶尔也能看到 Monorepo 与更高采纳率、更少来回改放在一块儿的讨论，口径各自不同，我不打算在这里背具体百分比。我自己觉得更实在的一点是，同一套索引里改契约，少了很多跨仓漏改。

一种常见的摆放方式大概是这样（命名随团队习惯变，道理差不多）：

• apps/web
• apps/api
• apps/worker
• libs/types
• libs/db
• libs/auth
• libs/ui
• libs/common

我手里在跑的一个仓库用的也是同一套思路，只是 app 名叫 apps/backend 和 apps/frontend，后端在 src 下拆 api、schema、types 等，根上还有 Turborepo 缓存和一份给助手看的 AGENTS.md。如下图所示：

树一展开，比在文字里凭空想象直观得多。

我以前在多仓库里改过一个 shared type，心里会一直挂着还有没有哪个仓库没 bump；现在在同一个 workspace 里，至少引用关系摊开在同一套工具链底下，TypeScript 或单元测试常常会比人肉更早喊疼——哪里还在用旧字段，哪里页面还在按老形状解构，grep 一下也有谱。

再比如后端改了接口返回字段，前端哪些 hooks、哪些组件真正吃到这一次响应，不必全靠记忆里上次好像聊过。这不是什么玄学体验，就是改动触发的影响范围更容易被看见、被追责到同一次合并请求里。

要做 AI 相关的增量也同理：Embedding、RAG、异步任务到底落在 libs/ai 还是单独 apps/worker，一开始就需要个说得过去的落点，不然半年后全是 import 魔法和临时脚本。Monorepo 不提供正确答案，但它逼你把这一坨归谁管迟早说清楚。

在这套习惯里待久了，工作状态会从我在维护好几个小项目悄悄换成我在推进同一个系统。不是口号，是你真的少了很多切仓库、对版本、猜依赖的上下文切换。

单仓也救不了后端胡写

所有代码塞一个仓库，只解决找得到文件，不解决你在 apps/api 里照样把 controller、service、库表访问、杂七杂八工具揉一团。AI 一次改五个文件，耦合只会涨得更快。

我后来还是上了 Nest，图的是入口、业务、横切几件事在目录上有固定叫法，新人进来知道往哪翻，补丁也能长得差不多。它不算最轻，我就看半年以后加模块还痛不痛。

Nest 那套烦人的分层

第一次学 Nest，很多人都会嫌它重：Module、Controller、Service、Guard、Pipe、Interceptor，条条框框比 Express、Fastify 裸奔多出一截，脚手架一念心里先咯噔一下。

但我后来承认，那些让我觉得烦的概念，多半正是复杂之后会回来的质问——HTTP 入口到底挂在哪儿，业务逻辑能不能别再黏在路由文件里，鉴权和校验是不是每次都重写一遍，异常最后统一长成什么样，跨模块的能力能不能复用而不是复制粘贴。你可以在项目很小的时候装作没看见，等体积上来，它们会以技术债的形式敲门。

Nest 对我有用的地方，就是它催你把那些事摊开：Controller 薄一点，Service 扛事，DTO 把进出的形状说清楚，Guard、Pipe、Interceptor 各管一截横切逻辑。写得丑归丑，至少在一条路上。

后端也不可能接口跑亮就结案，需求和权限还来。框架不写业务，只少几次从口头上重新约分层。

装饰器看多了，反而不容易乱窜

我以前当装饰器和 DI 是口味问题，现在要带着助手一起看代码，utils.ts 堆一切最头疼。Nest 那点样板至少是固定格式：@Controller 像关口，@Injectable() 多半进构造函数，Module 的 imports、providers 能看出依赖往哪边走。错误还会犯，多数是接错一层，不至于每个文件一种新的脾气。

构造函数里写字段比一层层 ../../../../ 好跟，对人类和编辑器都一样。

我不再纠结算不算魔法，只在乎新来的、审稿的、还有自动补全，是不是在同一个习惯里读这套目录。

生成越快，烂摊子越容易铺开

听上去怪，能力强了本应少管。我这边反正是反过来的，一次多出好几个文件，结构松的话脏东西也一起铺开。同样一个模型，在规矩紧的 Nest + Monorepo 里多半是补边角，在老脚本堆里经常是 import 散了、校验抄三遍、service 和 controller 又掰扯不清。

选型我就问两件事，多文件改完会不会散，下个补丁你能不能猜到哪一层动。Nest 不是唯一答案，只是我默认懒得再赌。

至于 Express、Fastify 裸着写，我见过太多靠自觉最后靠不住。轻量栈写小服务爽快，Hono、Elysia 我都用，业务一长我还是想有一层大家都认的摆放。Adonis、FoalTS 也行，模版和社区我这儿常碰到的是 Nest。

前后端接缝那档子事

语法、SQL、状态码啃得动，烦的是两半各搞各的目录、README、环境变量，改需求前先在心里对一遍口头合同，明明一个东西却干出两份工的感觉。

Nest + Monorepo 不能砍掉后端工作量，只是把缝抹窄一点。

同一个 workspace 改 API 和页面，共享类型和同一条 lint、tsconfig 脚本，少扯等你发包我先对齐版本的皮。以前在多个仓库里的流程，很多变成同一仓库里自己 refactor。

前端写了多年 TS，后端再随便 any 心就裂着。契约放在 libs/types 或用生成出来的 SDK 锁住一层，漂移少一桩是一桩。

包管理、CI、分支照旧两套角色，但至少不用每次从零切换脑回路。熟了以后，很难再忍受接口栏两头吵。

若以 Next.js App Router 或类似前端为主力，只是把 Nest 当成好好写业务和善后数据的那一半，这一套目录语言其实不难对齐。路由负责入口像 page，service 像抽出去的 server lib，pipe 和 interceptor 像中间件层。端到端类型上，有人喜欢 tRPC、zod 推断加共享 router，有人喜欢 OpenAPI 生成 client。任选一条你能长期维护的主线，把契约锁在 libs/types 或生成的 SDK 里，AI 在前端敲 mutation、fetch 时少一半凭空造字段。本地开发里，turbo（或等价物）跑 dev，改 shared 类型后两端热更新的节奏，也常和 AI 快速试错一小步合上拍。部署侧很多平台能对 monorepo 按 app 建制品，我不再想维护两份各写各的环境变量叙事。

审稿比生成更费工夫

现在大家爱讲几秒出一个功能。我自己的账本里，真正决定是否划算的，常常是后面的半小时到一个小时：目录有没有乱跑，边界有没有偷偷改写，类型和数据是否仍对齐，联动测试要不要补。如果生成省下打字时间，却成倍加到梳理结构上，账就对不上了。

Nest + Monorepo 做的很大一部分省事，是把一大批低级争议前置掉——共享字段在哪儿声明，模块职责默认怎样划，接口改了哪些地方按理应当红光报错。于是评审补丁时我更常在盯业务：权限有没有漏网的路径，异常场景会不会把脏数据写进去，性能热点是不是被忽视了，需求语义到底有没有偏差。

我现在的习惯能多懒就多懒，先跑测试和类型检查，再读业务。让 AI 顺手起一版 Vitest、Jest 或 e2e 骨架并不贵，红线测试挂了就先迭代 prompt。绿了再谈边界条件。@Injectable() 的好处是 mock provider 也相对直来直去，审 diff 的人会轻松一点。

以前看 AI 的补丁，像是在考古这东西为何出现在此；现在更多像是在核对这块业务说得圆不圆。这不是神话 AI，只是把本该机械的对齐成本压低了一层。

我没打算一锅炖成巨石

Monorepo 听上去像要把所有东西糊在一起，Nest 又像老派人做的三层后端。我自己的用法其实很土，源码和好改的契约放在一起，发布照样可以按 app 拆开。

• apps/web 托管前端
• apps/api 托管主 HTTP 服务
• apps/worker 托管队列或异步消费者
• libs/types 承载共享契约
• libs/ai 承载模型调用、RAG、prompt 组装之类
• libs/auth、libs/common 分摊认证与通用工具

仓库可以统一规范，制品依然可以按 app 构建发布；你可以先把复杂度关在清晰的包里，而不是一开始假装自己永远只需要一个 server.ts。这在 2026 格外常见——队列、异步生成任务、检索、后台配置、审计日志、多租户开关，后来都会陆续冒出来。

CI 里只对改动的 app 跑 turbo run test --filter=...@...（或等价过滤）之类，也早已是常规操作。共享代码动了，顺带跑会消费它的那几个 app，而不是每次全矩阵。托管侧不少平台认得 monorepo 根目录，apps/web 走静态或边缘，apps/api 单独开服务。源码和契约仍在一处捏着，生命周期和扩容却可以拆开看，不必心理上先投降成巨石。

Nest 自带 microservices、传输层那一套，真要把 auth 或大活拆出去，也还是在同一套路子里长枝，不用再拍脑袋起一套新目录癖。

我更在意的是：这些东西加进来的时候，是顺着现有的 libs/apps 生长，还是被迫堆出一层新的临时目录。前者不一定优雅，但至少有机会保持可读；后者常常意味着下一次 AI 生成又会发明一种新秩序。

人一多，文件夹比嘴上规矩管用

一个人单挑项目的时候，坏习惯还能靠记忆兜底；两三个人一起用 AI，风格漂移的速度会快得离谱。某人习惯函数式拼接，某人偏爱大类；有人把逻辑黏在 controller，有人把所有东西都塞进 util；几周下来，目录看起来像百家饭拼盘。

Nest + Monorepo 对团队的价值，不在于消灭分歧，而在于把大量本该口头重复的规矩，换成打开仓库就能看见的骨架——新功能默认落在哪个 app，共享代码朝哪个 lib 收敛，鉴权和 DTO 的习惯写法是什么。AI 这时更像在同一套轨道上补齐缺口，而不是每人拉着模型朝不同方向发明范式。

新人上手也会轻松一点：不必先听完三场口头约定才能下手改第一段代码，结构本身就带着大部分的别这么写。这当然不完美，但比纯粹依赖自律省心。

仓库根上挂一份短短的项目说明（例如 AGENTS.md、.cursorrules），往往比喊一百句我们风格是这样管用。仓库本身有条理，助手多半把你的效率往上抬。仓库本来就碎，它也会把那种碎法批量复制出去。条目宁可写得具体一点，也别只剩口号。

下面是一段示意，路径和工具名按你们真实栈改即可：

• 新功能落在 apps/api/src/<domain>/，按 Nest Module 拆分领域，别把所有业务都摊进同一个大目录。
• 共享类型与契约收口到 libs/types。DTO 一律配 class-validator，并在引导程序里全局启用 ValidationPipe。
• 鉴权走统一的 Guard（或团队约定的同一套切面），不要在每个 Controller 里各写一版 if。
• 跨包只引用对外公开的边界。优先用包名或 workspace: 协议对齐版本。禁止用一连串 ../../../ 掏进别的 apps/* 内部实现。

Claude Code、Cursor 之类读这类说明时会有点用，再配合仓库里实打实的 Nest 目录，跑偏会少一些。

总结

工具换了几轮，差的大头还是仓库难不难翻。多仓切开以后，光看当前窗口很容易蒙，import、字段名、契约各飘各的。拢进一个 workspace，找和改都短一截，TypeScript 报错和测试红条也常比人肉早。

Monorepo 只管东西在一锅里，治不好后端胡写。我上 Nest，图每层有个约定俗成的叫法，新人也好，编辑器补全也好，少走一点冤枉路。

写那几屏幕往往不费多少钟，时间都耗在审稿、对上类型、补测试。目录利落些，才能多在业务和坑上花功夫。

以后要挂队列、worker，鉴权再想拆出去，也愿意顺着现成的包长枝，不想再养一套谁也不知道的新规矩。

我平常就这么默认：Monorepo 先合上上下文，Nest 把后端层压住，剩下的靠习惯和 CI。写得多漂亮不敢说，只希望一群人加机器一起改的时候，烂得慢一点。

大家好 👋，我是 Moment，目前正在使用 Next.js、NestJS、LangChain 开发 DocFlow。这是一个面向 AI 场景的协同文档平台，集成了基于 Tiptap 的富文本编辑、NestJS 后端服务、实时协作与智能化工作流等核心模块。

在这个项目的持续打磨过程中，我积累了不少实战经验，不只是 Tiptap 的深度定制、编辑器性能优化和协同方案设计，也包括前端工程化建设、React 源码理解以及复杂项目架构实践。

如果你对 AI 全栈开发、文档编辑器、前端工程化或者 React 源码相关内容感兴趣，欢迎添加我的微信 yunmz777 一起交流。觉得项目还不错的话，也欢迎给 DocFlow 点个 star ⭐

很多项目在早期都能跑通，到了中后期却开始不稳。最常见的原因不是模型变差，而是上下文结构越来越乱。你把规则、问题、历史、检索结果、工具输出全部堆在一起，短期看起来省事，长期一定会出问题。常见表现有这些：

• 明明要求输出 JSON，模型还是自由发挥
• 明明给了检索结果，模型却忽略证据
• 明明上一轮说清楚了，这一轮又答偏
• 一加新条件，前面的格式约束就失效
• 出问题时很难定位是规则错、检索错还是历史污染

问题的核心不在提示词文案，而在上下文分层。role 的价值正是在这里。

role 的本质

role 不是标签装饰，它在告诉模型三件事：

• 这段内容来自谁
• 这段内容属于哪一层
• 这段内容应按什么优先级理解

同一句话放在不同 role，效果会明显不同。比如 请只输出 JSON 放在高优先级规则层通常更稳，塞进用户问题里更容易在复杂场景被冲掉。所以 role 解决的是上下文治理问题，不是接口语法问题。

常见 role 和信息来源

在多数对话接口里，核心角色通常是四类：

• developer
• system
• user
• assistant

还有一个容易混淆的点，工具返回结果通常不应当当作普通对话角色，而应作为独立证据输入。从工程视角看，一次请求里的上下文来源通常是五层：

• 规则层，通常来自 system 或 developer
• 任务层，来自当前 user
• 历史层，来自对话历史中的 user 与 assistant
• 事实层，来自 tool、检索或数据库
• 生成目标层，定义这一轮最终输出要求

四个核心角色怎么用

developer

developer 是应用开发者写给模型的长期行为约束。它描述这个助手长期应如何工作，而不是本轮要回答什么问题。适合放在这里的内容：

• 助手定位
• 默认语言
• 回答结构
• 输出格式
• 工具使用策略
• 不确定时的处理方式
• 禁止编造规则

const input = [
  {
    role: "developer",
    content:
      "你是技术讲解助手。默认中文。先给结论再展开。不确定时明确说明，不要编造。",
  },
  {
    role: "user",
    content: "请解释 JWT 和 Session 的区别",
  },
];

system

system 也是高优先级层，但更偏平台级或全局边界。它常用于跨场景都成立的底线规则。适合放在这里的内容：

• 全局身份边界
• 合规与安全要求
• 平台级能力限制
• 不可突破的红线

很多项目里 developer 与 system 会有重叠。只要职责清晰，是否拆开都可以。

user

user 承载本轮任务目标，不承载长期规则。它回答的是现在要做什么，而不是系统长期怎么做。常见内容：

• 当前问题
• 补充条件
• 输出偏好
• 输入材料

const input = [
  {
    role: "developer",
    content: "你是中文技术助手，回答准确并保持简洁。",
  },
  {
    role: "user",
    content: "请解释什么是 RAG，并给一个 TypeScript 场景示例",
  },
];

assistant

assistant 是模型历史回复层，作用是保持多轮连续性。它不是规则层，也不是事实仓库。

const input = [
  {
    role: "developer",
    content: "你是前端导师，解释时要循序渐进。",
  },
  {
    role: "user",
    content: "什么是向量数据库",
  },
  {
    role: "assistant",
    content: "向量数据库是为高维向量检索设计的存储与查询系统。",
  },
  {
    role: "user",
    content: "它和传统数据库的区别是什么",
  },
];

assistant 历史不是越多越好。历史过长、重复或噪声过多，会直接拉低后续轮次稳定性。

工具返回到底放哪层

工具结果、检索片段、数据库查询、网页抓取，本质上都是外部证据，不是模型自己说过的话。如果把这些内容伪装成 assistant 历史，会出现三个问题：

• 语义边界混乱，模型分不清自述和证据
• 历史层污染，后续轮次越来越难控
• 调试成本上升，问题定位困难

更稳的策略是：

• 规则放 system 或 developer
• 任务放 user
• 历史放 assistant
• 证据放独立事实层

在 RAG、Agent、工作流编排里，这一点几乎是稳定性的分水岭。

一句话说清楚：把规则、任务、历史、外部事实和生成目标分层放置，LLM 的稳定性、可信度和可调试性都会明显提升。

四种高频场景的组织方式

单轮问答

developer + user 即可，结构最轻。

const input = [
  {
    role: "developer",
    content: "你是中文技术助手，回答清晰且准确。",
  },
  {
    role: "user",
    content: "请解释什么是 SSE",
  },
];

多轮对话

在 developer + user 基础上加入必要 assistant 历史，保证上下文连续。

RAG 问答

规则、问题、证据分层，不要把检索内容伪装成 assistant。

const input = [
  {
    role: "developer",
    content: "仅依据提供资料回答，不确定时明确说明。",
  },
  {
    role: "user",
    content: "文档里如何定义 RLS",
  },
  // 检索结果作为独立证据输入
];

工具调用型 Agent

流程通常是规则定义、任务输入、模型决策、工具返回、最终回复。关键点始终是证据层和历史层分离。

这一段也可以直接用一张图讲透，重点表达每个角色的禁放内容、统一分层原则和高频错误。

如下图所示：

图里按左中右依次呈现禁放项、分层原则、错误清单，读者扫一眼就能建立正确的上下文组织习惯。

总结

给 LLM 传递上下文时，role 不是身份扮演，它是上下文架构的第一层。核心角色可以记成四个：

• developer 负责应用规则
• system 负责全局边界
• user 负责当前任务
• assistant 负责历史承接

工具返回、检索结果、数据库结果这类外部事实，应单独进入证据层。一句话总结这套方法就是，规则、任务、历史、外部事实、生成目标必须分层，各归各位。只要这件事做对，很多看起来像模型能力问题的现象，最终都能回到可治理的上下文工程问题。 如果把这套原则再压缩成一条执行口令，就是谁定义规则、谁提出任务、谁给出证据、谁负责输出，都必须放在各自那一层，不能混写。结构一旦干净，后续 prompt 设计、RAG 召回和 Agent 调试都会明显轻松。

大家好 👋，我是 Moment，目前正在使用 Next.js、NestJS、LangChain 开发 DocFlow。这是一个面向 AI 场景的协同文档平台，集成了基于 Tiptap 的富文本编辑、NestJS 后端服务、实时协作与智能化工作流等核心模块。

在这个项目的持续打磨过程中，我积累了不少实战经验，不只是 Tiptap 的深度定制、编辑器性能优化和协同方案设计，也包括前端工程化建设、React 源码理解以及复杂项目架构实践。

如果你对 AI 全栈开发、文档编辑器、前端工程化或者 React 源码相关内容感兴趣，欢迎添加我的微信 yunmz777 一起交流。觉得项目还不错的话，也欢迎给 DocFlow 点个 star ⭐

最近我给一些前端方向的实习生做内推，看了不少简历。投递里常能看出一种预设，找实习只要把前端做熟，页面和接口能啃下来，似乎就踩对了主线。初筛读多了会有另一种感受，当业务和岗位已经大量贴上大模型、RAG 或 Agent 时，纯前端技术栈写得再工整，也很难在一叠写法雷同的简历里单独把人托起来。

我想写的不是简历技巧，评审更常问的是，你有没有把智能接进一条可维护、可观测、也能和人协作的链路，还是只在项目名里多写几个关键词。

许多项目经历段落，技术名词很全，叙事却薄。写得多的几种模式是：

• 周期很短，却同时堆上 RAG、流式输出、鉴权与复杂治理，读者很难估计真实投入与掌握深度
• 段落像功能清单，缺少场景、难点、个人职责与可验证结果，性能数字也缺少口径与复现方式
• 形态集中在教程型对话台或后台管理，技术栈高度同质，差异化不明显
• Agent 被写成调模型、接工具，很少触及运行时、状态机、评测、观测与人在回路

还有一种写法，整段都在堆大家简历里常见的工程项，例如 JWT、双 token、RBAC、请求拦截器、SSE 或 WebSocket 流式、分片上传、虚拟列表。十条里七八条读起来像同一篇教程拆出来的，名词齐了，却看不出你解决的是哪一道别人没写清楚的难题。基本功当然要会，可若差异化只停在这一层，筛简历的人很难把你从同质化描述里拎出来。

简历上的项目经历一撞脸，筛简历的人就只好盯你有没有把系统做实。后面我按层写。

这两年简历里写 Agent 的人越来越多，细看实现却常常撞脸，核心路径几乎总是同一条。

接收用户输入，调用大模型，解析工具调用，执行工具，返回结果。

引用里那几步，无非是调模型、解析工具调用、执行、再把结果塞回模型。脚手架和跟练多了，半天跑通一个 Demo 很常见。评审里想听的，往往是上线以后要应付的那些事，超时、重试、成本、人要确认、出了事故怎么查和改，你有没有提前铺过路。

面试里真正该往下问的，早就不该是这种技能清单：

• 你会不会调 LLM
• 你会不会接 Tool
• 你会不会用 LangChain

而是更底层的这个问题：

你有没有把 Agent 当成一个系统，而不是一个函数调用？

能讲清楚这一句，面试官才会继续往下问。落地时大家会盯这几件事有没有做实，有没有进真实产品而不是停在演示分支：

• 有没有独立的 Agent Runtime
• 有没有显式状态机驱动的 Agent Loop
• 有没有把评测做成回归闸门
• 有没有把观测、检测、红队、安全、成本和用户干预整成闭环
• 能不能把这些能力真正接进产品，而不是停留在一段演示代码

缺了这些，名字再响亮，多半仍是一个带工具调用的聊天接口。本文不写怎么接 OpenAI、怎么声明 Tool，只写骨架。

从 Demo 到产品，Agent 系统到底还差哪几层骨架。

下面按层拆开说明。

为什么很多 Agent 项目能跑，但没有技术区分度

很多人会以为把大模型、多轮、Tool、Memory 和 RAG 勾齐，项目就算做完了。那点东西多半只盖住 demo 里的顺利路径，一遇到真实流量，缺的是运行时、安全、观测和评测这一整圈骨架，而不是再多接一个模型。

它们看起来像 Agent，实际上更像一个带工具调用的聊天接口。

一放量，问题会先挤在几块地方，很少单靠改一段 Prompt 就能压住：

• 同一类提问有时成有时败，工具忽对忽错
• 用户只看到转圈，不知道卡在推理还是在等工具
• 线上成功率掉了，分不清是模型、工具还是外部 API
• Prompt 改完自测像变聪明，线上指标却掉头
• 偏航多步也没有让人半途介入的口子
• token 和钱烧在哪些步骤，心里没底

根本原因多半不在 Prompt 花不花或 Tool 多不多，而在下面几块是否长期空白：运行时、状态机、可观测、评测、风险、HITL、Streaming、成本、异常和线上告警。填不全，项目就会一直像在交课堂作业。只会用 LangChain 也不等于会做 Agent，框架主要管编排，编排以外的那一圈才是评审想听你讲清楚的。

前端加 LangChain 开发者的真正优势

前端背景再叠上 LangChain、LangGraph、工具与记忆，常被低估。和算法岗比的不是论文厚度，而是能不能把智能体做成别人能长期点着用的产品。

你更占便宜的地方，是把 Agent 做成用户看得见、停得下来、出了问题能对上账的系统。

模型只是其中一个节点。好不好用还要看，现在在干什么、为什么选这个工具、失败怎么补、用户能不能打断、高风险要不要确认、耗时和钱能不能对上账、改完 Prompt 有没有回归、输出能不能验、输入和工具参数有没有护栏、线上有没有告警。这些早就不是单次推理，而是一整条链路的工程活。状态、异步、中间态、确认、埋点和展示，本来就是前端日常，这块你会比只写脚本的人更顺手。

介绍自己时不必缩成会接某家 API 的前端，可以收成一句实在话。

我负责把 LLM 编排、工具、状态机、可观测、评测和交互收成一条，给人用的是产品不是脚本。

交付物也更该像任务控制台，把推理、调工具、等确认、报错恢复这些阶段摊开，而不是聊天框里一条接一条的气泡。

把 Agent 理解成运行中的系统而不是调用链

先把问题问清楚，这东西在产线里更像一次短请求，还是像一趟要跑很久的任务。

不要把 Agent 理解为一次请求的处理流程，而要把它理解为一个持续运行的任务系统。

普通接口大约四步，请求进来，处理完就结束。Agent 更像长跑任务，中间状态多。下图是一条典型阶段划分，提醒自己别再用短接口的思维去估长任务。

图的意思很直白，Agent 更接近任务引擎，而不是只吐一段字的接口。接下来这些问题躲不掉，状态放哪、刷新后怎么续、工具超时重试还是交给人、高风险要不要审批、token 快顶了还跑不跑、工具能不能并行、连走几步没进展算不算打转。这些都算系统设计，不是多写两行 Prompt 能糊过去的。

一个有区分度的 Agent 系统应有的分层

聊 Agent 如果只停在调模型、调工具，听起来总像缺一块。动手前最好先想清楚，界面交互、流程编排、运行时控制、安全治理、可观测和评测各自归谁管，别全糊进一条链。

对外说法可以很简单，Agent 像一条流水线：

用户输入 → 模型推理 → 调用工具 → 返回结果

真要拆职责，可以收成六层：

• 交互层：用户看得见、点得着的界面，负责步骤展示、审批、中断、重试和结果反馈
• 编排层：用 LangChain、LangGraph 等把 Prompt、模型、工具、记忆和状态流转组织成可维护的流程
• 运行时 Harness：管理步数、超时、预算、快照、重试、取消和收尾，决定任务如何真正跑完或安全停下
• 安全与检测层：在输入、工具执行前、输出和轨迹上做规则与模型检测，拦住不该发生的行为
• 可观测层：用 Trace、Metrics、日志把每一步变成可查询、可对比、可回放的事实
• 评测层：通过离线集、回归闸门和线上灰度，用数据判断一次改动到底有没有变好

编排层按意图出计划和工具调用，运行时层在预算、超时和状态约束下执行。执行中安全层可能拦截或要审批，可观测层记全程，评测层再拿这些记录去约束下一版 Prompt、节点、工具和发版节奏。

分层不是为了把图画复杂，而是别把运行时、安全、回放、评测和灰度都指望 LangChain 自动搞定。框架主要管编排，编排外那一圈才决定工程含量。

用户意图从交互层进编排层，编排层再把可执行步骤交给运行时。

运行时不只是把流程跑完，还要在执行过程中持续接入安全检测和可观测能力。

可观测记录下来的事实，会进入评测体系，再反向约束下一轮编排和发布策略。

每层用一句话带过，细节可以另写。

交互层负责摊开给人看、给人控。过程可见、风险写操作前要确认、能中断和改向，这些要和运行时对齐，别事后在文案里补两行提示。

编排层用 Prompt、Tool、Memory、图或链把节点串起来。LangChain 一类框架主要管这一层，观测、中断、预算、版本和 bad case 回流多半在编排之外，别把欠账算在框架头上。

运行时层用 Harness 钉死步数、单步和整体超时、token 和墙钟预算、取消和收尾。结束由状态和 Harness 判定，预算触顶该降级就降级，别指望模型自己说做完了。

安全与检测要盖住输入、工具执行前、输出和轨迹。模型吐出来的 tool call 只是草稿，执行前要走白名单、schema、权限和风险分级，高危路径该审批就审批。

可观测层靠 Trace、分层指标和结构化日志，把一次任务从猜变成查，后面才好做归因、回放和调参。

评测层用离线用例、回归闸门和线上灰度回答有没有变好。Prompt、模型、工具或状态机一动，就该自动对比基线，线上反馈要能回灌进用例集。

六层都沾到，才像能交给别人托管的产品，而不是只证明链路能跑通的 Demo。

Agent Loop 应该是显式状态机而不是 while 循环

最朴素的 Agent Loop 是反复调模型、判断是否调工具、拿结果再回模型，直到产出答案。这个流程能跑通，但一进真实场景就容易失控，因为很多关键分支塞不进一个裸 while 循环。

真正容易栽跟头的几件事：

• 工具失败后的重试与止损
• 高风险动作前的人工确认
• 预算触顶后的降级与收尾
• 上下文过长时的压缩与续跑
• 用户中断后的恢复与回放

把 Loop 收成显式状态机，让系统在 Reasoning、ToolSelecting、Executing、AwaitingConfirmation、Recovering、Finalizing 等状态之间按条件跳转，分支写在表里，比藏在 if 里好查也好测。

状态机写清楚以后，日常会顺很多。状态一眼能看见，分支不再散在 if 里，前后端对得上号，暂停、恢复、撤销、重试也好接。

把它和前面的 AgentHarness 组合后，职责会更清晰：

• Harness 负责时间、步数、token、取消和强制收尾
• 状态机负责业务语义、路径选择和异常分支

上线以后，Loop 往往还要挂审批、检测、回滚、埋点和评测，能挂在状态切换点上就别散在业务代码里。

收个尾，Agent Loop 不该只是会转的循环，最好收成一台可解释、可干预、可恢复、也能审计的状态机。

把人设计进系统而不是把人当兜底

很多团队把 HITL 理解成出错后的兜底，这会让人机协同长期停在救火阶段。设计阶段就把哪些动作自动放行、哪些必须确认、哪些默认拒绝写清楚，比上线后救火省事。

HITL 是 Human-in-the-loop，意思是把人放进关键决策回路。系统负责执行与提议，人负责在高风险节点确认、纠偏和兜底。

风险分级可以先从三档起步，阈值和白名单由业务与合规共同维护：

• 低风险，默认自动执行，失败后可重试或降级，例如搜索文档、读取代码、查询只读数据、整理摘要
• 中风险，可自动执行但要留痕，并保留撤销窗口，例如文案修改、批量替换、工作区文件编辑
• 高风险，执行前必须阻断并等待确认，例如删除文件、外网请求、代码提交、数据库变更、发布和付费接口调用

差别通常不在有没有确认按钮，而在卡片里给不给够决策信息。动作是什么、为什么动、影响范围、能不能撤销、有没有备选，最好一眼能看完，别只剩一句是否继续。

审批如果只在前端拼文案，很快会和真实执行脱节。更省事的做法是把审批收成结构化数据，从后端下发，挂到同一条 trace 上，事件流里推 approval_required，回放、审计和告警都读同一份。

卡片上最好有：

• 风险等级、审批时限、发起来源一眼可见
• 受影响资源和变更范围可展开查看，必要时接 Diff
• 可逆操作提供 Undo 入口和预计回滚成本
• 支持改参数或切换替代动作后再执行，减少往返沟通
• 全量记录审批人、审批理由、执行结果，满足审计留痕

审批、trace、状态机和观测如果能共用一套模型，人机协同就不只是打补丁。

Streaming 应该让 Agent 过程可见

流式输出如果只用来更快吐 token，对 Agent 任务帮助有限。用户更想知道现在卡在哪一步、工具在干什么、要不要自己点一下。

事件可以粗分三类，最好走同一条推送通道，省得前端接好几套协议：

• token 层，持续输出自然语言内容
• step 层，推送每一步的动作、工具状态和中间结论
• progress 层，推送总进度、耗时和成本，减少等待焦虑

用一条联合类型把字段钉死，前后端少扯皮。下面是个示意，覆盖状态变化、工具起止、审批、进度和收尾，载体可以用 WebSocket 或 EventSource。

type AgentStreamEvent =
  | { type: "state_changed"; state: AgentState; at: number }
  | { type: "token"; text: string; stepId: string }
  | { type: "tool_started"; stepId: string; tool: string; args: unknown }
  | { type: "tool_finished"; stepId: string; ok: boolean; summary: string }
  | { type: "approval_required"; request: ApprovalRequest }
  | { type: "progress"; done: number; total: number; costUsd: number }
  | { type: "final"; answer: string; traceId: string }
  | { type: "error"; message: string; recoverable: boolean };

协议统一以后，时间线、步骤卡片、进度条和审批弹窗才好做，中间态不必全塞进气泡里。界面上比较值得先做的几件事：

• 步骤折叠与展开，避免长任务刷满屏幕
• Observation 面板分层展示工具入参、结果摘要、原始返回
• 工具日志实时滚动，失败步骤高亮并给出重试入口
• 全局状态浮层显示当前状态机节点与等待原因
• Stop、Retry、Continue、插话打断与后端取消契约对齐
• 人工接管入口用于切换执行策略或直接改写下一步
• 最终答案和中间证据联动，点击引用可回跳对应 step

同样是等三十秒，转圈和看着系统一步步推进，感受差很多。过程可见，用户能更早纠偏，也能少烧不少无效 token。

离线评测资产、线上观测与可迁移遥测

Agent 要长期迭代，既要离线侧能证明有没有变好，也要线上侧能看见真实流量里发生了什么，还要让埋点与字段尽量不因换观测后端而推倒重来。这一节把三件事收进一条工程链条：先固定可迁移遥测语义，再让离线评测与回归产出可进闸门的证据，最后在线上仍用同一套字段读 trace、成本、实验与用户反馈。底座语义与线上观测必须同源，否则灰度里对不上离线报表。

语义底座先把典型 span 名、属性键和事件形状写进约定，常见列包括 trace_id、span_id、model、token 进出与 cost_usd 等，并对齐 GenAI 与 OpenTelemetry 社区里已经有人在用的写法。这样换导出器或换观测后端时，主要改连接与映射，业务代码少动字段名。离线评测与回归靠版本化用例集、对结果与格式与合规的断言、与基线的对照统计、接入 CI 的闸门和可计量的回归耗时，把主观手感压成可复跑的 Eval 分数。线上可观测在同一套定义下读 trace 时间线、成本随时间和用量变化、AB 流量拆分、用户情绪与满意线索、以及告警与异常。工程上的收束是：语义先沉淀进离线证据，离线结论再拿去和线上 trace、金丝雀或灰度放量对齐，团队才不会各写各的报表。

落到工具时，离线侧靠版本化用例、对过程与结果的断言、基线对比和接入 CI 的闸门把手感变成证据。promptfoo、DeepEval、Ragas 分别偏配置、断言、指标，关键是同一套用例能从开发跑到发布。线上噪声更大，盯住任务完成率、工具成功与超时、成本与风险侧信号即可。Langfuse、LangSmith、Phoenix、Helicone 选型看能否把 trace、实验、分数和反馈收进同一面板。OpenTelemetry 的 GenAI 语义适合当公共约定，先统一 LLM、tool、agent 如何建 span，以及 token、延迟、错误码等字段，迁移成本主要在导出器。

前端加 LangChain 开发者可以重点讲的几点

前端把运行中的系统摊开给人看：状态、步骤、工具、风险、中断重试入口，以及 token 与成本摘要。trace 不应只躺在仓库里，而要变成时间线、Step 卡片、风险高亮和失败回放。模型差不多时，把过程讲清楚往往比再换一次模型更能换来信任和效率。

一个成熟 Agent 项目的技术区分度该怎么描述

重点不是接了哪个新模型，而是能否在真实业务里持续跑稳、可对比、可审计。下面是一段自述示例，可按实际情况改名词和程度。

我做的不是调模型、调工具的 Demo，而是面向真实用户的 Agent 运行系统。LLM 与编排负责生成与流转，Harness、状态机 Loop、风险控制、HITL、可观测和评测负责稳定与可治理。 工程上我会打通离线评测、线上观测和回归闸门，用统一遥测语义串起 trace、成本、质量与用户反馈，让每次迭代可对比、可回放、可审计。 我有前端背景，会把过程可视化、干预入口和体验指标当成主交付物，而不是只交最后一段文本。

总结

RAG 可以做，Agent 也可以做，它们都只是手段，不是终点。真正拉开差距的是你有没有把需求、执行、观测、评测和迭代接成闭环。下面四条自检，有一半答不上来，就值得对照正文里的分层补一补。

• 执行与韧性：是否有独立运行时与预算约束，Loop 是否显式状态机，故障能否回放，成本与步数是否可解释。
• 质量与证据：是否有维护中的评测集、CI 或合并前的回归闸门，红队用例是否像测试代码一样可复跑，而不是发版前凭手感点几下。
• 安全与过程：输入、工具调用前、输出与轨迹四层里，哪些已经落地成策略与埋点，高风险路径是否默认进审批而不是靠运气不触发。
• 观测与闭环：线上是否能同时看到 trace、成本、实验与用户反馈，离线分数与线上信号能否进同一套界面或同一套数据模型，而不是各团队各一份报表。

能跑通链路只是起点，能不能长期闭环才是标准。

你有没有把它做成一个能稳定运行、可观测、可评测、可干预、还能持续迭代的闭环系统。

走前端加 LangChain 这条线的人，手里正好捏着界面、状态和事件，把这些和模型、工具、观测、评测缝在一起，比单纯多接一个模型更难被模板替代，写进自我介绍里也更有话可说。