📎 说明：这篇文章是我在准备搭agent时学习过程的整理跟 《Agentic 入门：让 AI 不再一把梭，而是像人一样反复干活》 一起整理的。按理说这篇应该更早发，但当时一直没整理顺，所以拖到了后面。内容还是以我自己的学习理解为主。

我最早注意到 Context Engineering（上下文工程），大概是在 Prompt Engineering 被聊得很热之后。

Context Engineering（上下文工程）最早接触是Prompt Engineering 概念火了一段时间之后。
在这之前好像AI应用开发的核心焦点一直是“提示词工程（Prompt Engineering）”。然而，随着大语言模型（LLM）从单次问答向能够自主运行的智能体（Agent）演进，上下文工程（Context Engineering）变得更加重要。

很多时候，真正决定模型表现的，不是你那句话写得漂不漂亮，而是它在那一刻到底看到了什么，没看到什么。

所以我现在更愿意把这件事理解成：做大模型应用，重点正在从“怎么把话说漂亮”，慢慢转到“怎么把上下文组织对”。

一、先说问题：Prompt Engineering 到底卡在哪儿？

只要你认真用过一段时间 AI，大概率都会碰到这种情况：

你写了一个很长的 Prompt，感觉已经把话说明白了，结果模型要么没懂，要么回答得很飘。可你换个问法，它又突然正常了。

你开始怀疑：是我 Prompt 写得不好，还是模型本身忽强忽弱？

这个现象背后，其实是个更底层的问题：模型能不能干好活，很大程度上取决于它当下到底能看到什么。

Prompt Engineering 解决的是“怎么把问题问清楚”。这当然重要，但它管不了另一件更麻烦的事: 当你要处理的信息，已经不是一轮对话能装下的时候，该怎么办？

比如：

• 你有一本 500 页的技术文档，想让 AI 帮你答用户问题
• 你的系统里有十几个上下文来源（用户历史、实时数据、业务规则、代码片段……）
• 你的 Agent 要跑十几步任务，中间状态要一直传下去

到了这些场景里，“怎么问”就不是最核心的问题了，“怎么喂”才是。

这就是 Context Engineering 要解决的事。

二、那 Context Engineering 到底是什么？

Anthropic 的说法是，它可以看成是从 Prompt Engineering 往前走了一步《Effective context engineering for AI agents》，但两者盯的东西并不一样：

• Prompt Engineering：怎么写好这一句话
• Context Engineering：怎么组织整个信息环境

如果用我自己的话讲，后者更像是在做“信息架构”，你要决定：

1. 哪些信息该放进上下文
2. 这些信息按什么结构组织
3. 什么时机、以什么方式把它们喂给模型
4. 超出上下文窗口时，怎么选择性地保留和丢弃

这件事听起来像工程，不是因为这个词高级，而是它真的就是工程问题。它不是让你背几个提示词套路，而是要把整个信息流理清楚。

有一个比方我觉得很贴：

Prompt Engineering 是教你怎么跟一个人说话；Context Engineering 是在他开口之前，帮你决定他今天能看到哪些材料、能记得哪些背景、桌上摆的是什么资料。

三、它真正卡住的，不只是窗口大小，而是“注意力预算”

很多人第一次接触上下文工程，都会先盯着“上下文窗口够不够大”。

这个视角没错，但还不够。

但我现在越来越觉得，更准确的说法应该是：模型真正稀缺的，不只是 token 容量，而是注意力预算。

你可以把上下文窗口理解成模型工作的“临时内存”。窗口大，确实代表理论上能塞进去更多东西；但塞得进，不等于它就能稳定地理解、提取、关联这些内容。

这时候会出现一个很现实的问题：上下文腐烂（Context rot）。

说白了就是，上下文越长、信息越杂，模型越容易出现下面这些毛病：

• 前面明明给过规则，后面还是忘
• 中间插入很多工具输出后，开始抓不住重点
• 看起来“都读了”，但真正回答时只抓住开头和结尾
• 局部结论没问题，一到多步任务串起来就开始漂

所以 Context Engineering 的核心不是“拼命往里塞”，而是：用尽量少、但信号强的信息，占住模型最宝贵的注意力。

所以很多 AI 系统上线以后表现不稳，问题不一定出在模型不够聪明，很多时候就是上下文里混进了太多低信号内容。

四、底层是什么？先聊 Self-Attention

要真正理解”上下文”对模型意味着什么，绕不开一篇 2017 年的论文：《Attention Is All You Need》《Attention Is All You Need》，也就是提出 Transformer 架构的那篇。

它里面最核心的东西是 Self-Attention（自注意力机制）。

粗暴一点讲，模型在生成每一个词的时候，都会去“扫一眼”上下文里别的词，算一遍“谁跟我现在最相关”，再决定往下吐什么。

这意味着：模型的能力，很大程度上取决于窗口里装了什么。

你给它看的内容越准确、越有结构、越聚焦，它的注意力就越能集中在真正重要的部分。你塞一堆无关信息进去，它不会自动过滤掉，它只会”稀释”它的注意力。

所以“上下文工程”这件事，如果往底层追，本质上就是在跟 Self-Attention 的工作方式打交道。

五、系统提示词也有讲究：别太死，也别太飘

很多人一提上下文工程，第一反应还是去改 System Prompt。

这当然要改，但我现在觉得，问题通常不是“写得不够长”，而是写得那个劲儿不对。

我现在更认同一个判断：好的系统提示词，应该在“规则足够清楚”和“保留模型推理空间”之间找到平衡。

两个极端都不行：

• 写成 if-else 说明书，模型像被绑住手脚，遇到复杂情况反而不会变通
• 写得过于抽象，只说“请你专业、严谨、友好”，基本等于没说

我现在更倾向于把系统提示词拆成几个清楚的区块，比如：

• 背景信息：这个 Agent 是干什么的
• 目标：这次任务最终要达成什么结果
• 约束：哪些事情不能做，哪些风险要优先规避
• 工具说明：什么时候该调用什么工具
• 输出要求：最后结果要长什么样

你会发现，这时候你做的已经不只是“写一句提示词”了，而是在给模型搭一个小型运行环境。

六、RAG 里最容易踩的坑，Anthropic 想了个解法

现在很多 AI 应用都在做 RAG（检索增强生成）——就是把一堆文档切片，存进向量数据库，等用户提问时捞出相关片段塞给模型。

这条路当然没错，但里头有个很容易被忽略的问题：文档一切片，背景信息很容易丢。

举个例子：你有一份技术文档，里面有一段话：

“这个接口的超时时间配置建议设为 5 秒。”

这句话单独拿出来是完整的，但如果你不知道这是在说”内网服务调用”而不是”公网 HTTP 请求”，这条建议可能直接坑掉你。

Anthropic 在 2024 年提出了 Contextual Retrieval《Contextual Retrieval》 来解这个问题。核心思路其实不复杂：

在切片存储之前，先让模型给每个片段加一段 **”上下文注释”**，说明它来自哪个文档、属于哪个章节、要解决什么问题。然后把这个带注释的片段再做向量化。

这样检索出来的内容，就不只是一句话，而是“一句话 + 它原本待着的语义背景”，命中质量会明显好一些。

配合 BM25 关键字检索（而不是单纯依赖语义向量），精确度进一步提升。

简单来说：不是切得多就能捞得准，要让每一块碎片都知道自己是从哪来的。

七、真正有用的方式，不是预加载全部，而是按需取用

很多系统在早期都会很自然地走一条路：既然上下文重要，那就多塞一点。

比如：

• 用户资料全塞进去
• 历史对话全塞进去
• 检索结果 top 10 全塞进去
• 工具执行日志原样全塞进去

一开始看起来确实会有一种“信息很全”的安全感，但很快就会遇到两个问题：

1. 模型越来越贵
2. 模型越来越乱

更像样一点的做法，其实是 Just-in-time context，也就是“即时上下文”。

它的思路是：默认只保留索引、摘要、标识符，真正需要的时候再去取原文。

比如不要把整个代码库文档直接扔进上下文，而是先给模型：

• 文件路径
• 模块索引
• 函数签名
• 哪些文档可能相关

然后让它在任务执行过程中，通过检索、搜索、读取工具，一步步把真正需要的信息拿进来。

这种方式本质上是在做“渐进式披露”。不是一上来把整个图书馆砸给模型，而是先把目录递给它，再让它决定该翻哪几页。

这比一次性预加载所有材料，更接近人类真正工作的方式。

八、长任务为什么特别容易翻车？因为上下文会被历史污染

上面说的 Contextual Retrieval，主要解决的是“单次检索”的质量问题。但到了更复杂的 Agent 场景里，还会多出另一个麻烦：上下文不是一开始就完整的，它是任务跑着跑着一点点堆起来的。

多步 Agent 工作流最烦人的地方，不一定是某一步直接做错，而是前面做过的所有事，最后都会变成后面的上下文负担。

比如一个任务跑了二十几步之后，上下文里可能已经混着：

• 早期已经失效的假设
• 很长但价值不高的工具输出
• 中途试错留下来的噪音
• 真正关键但只出现过一次的结论

这时候问题就不是“窗口够不够”，而是历史信息正在污染当前决策。

所以长周期任务里，通常就得想办法处理这件事。常见做法大概有三类：

① 压缩（Compaction）

当窗口快满时，不是简单截断，而是把已经完成的阶段总结成高保真摘要，把冗长原始过程替换掉。

② 外部记忆（Structured note-taking / Agent memory）

把待办、关键决策、阶段性结论写到上下文窗口外，比如 NOTES.md、状态文件或者数据库。后续即使重新开一个新窗口，也能快速续上。

③ 子智能体隔离（Sub-agent）

把特别耗 token 的探索任务丢给独立子智能体去做，让它在自己的“干净窗口”里完成搜索、归纳，再把浓缩后的结论返回主智能体。

这三件事，本质上都在解决一个问题：别让历史细节一直赖在窗口里，持续污染当前判断。

九、Anthropic 的工程实践：XML 标签、工具边界和 Prompt Caching

具体到工程实践，Anthropic 在这篇文章里《Effective context engineering for AI agents》 给了几个我觉得挺接地气的抓手：

① XML 标签

当你需要在上下文里放多个来源的信息（用户资料 + 业务规则 + 代码片段 + 历史记录），用纯文本堆在一起，模型很容易把它们”混为一谈”。

用 XML 标签把它们显式分开，能让模型更清楚哪块是哪块：

1
2
3
4
5
6
7
8
9
10
11

<user_profile>
  用户是一个年营收 500 万的 SaaS 创业公司 CTO
</user_profile>

<business_rules>
  禁止直接推荐未上线的功能
</business_rules>

<user_query>
  我们应该怎么设计权限系统？
</user_query>

这玩意儿不是什么魔法，说白了就是把结构摆明白，别让模型自己猜。

② 工具边界要清楚

很多 Agent 失败，不是因为工具不够多，而是因为工具太多、定义太像、边界太模糊。

如果一个工具库里同时有：

• search_docs
• lookup_docs
• find_doc_context
• query_knowledge

那别说模型，人都得先愣一下。

我现在越来越觉得，工具其实就是模型和外部世界的契约。契约越清楚，模型越稳；契约越含糊，它越容易瞎试。

③ Prompt Caching（提示词缓存）

如果你的系统里有一段很长的固定上下文（比如一份 300 页的产品手册），每次用户提问都要把这段内容完整喂给模型，成本很高。

Prompt Caching 允许你把这段内容缓存在 API 层，后续调用直接复用，不重复计算。

这事看起来像纯工程优化，但很关键。因为它会直接决定：“长期带着一大坨稳定上下文工作”这件事，在成本上到底能不能成立。

十、Karpathy 的那个比喻：上下文窗口是模型工作的“临时内存”

在 OpenAI 前首席科学家 Andrej Karpathy 的一个演讲里《Software Is Changing (Again)》演讲，他把上下文窗口比作大模型的”有限内存”。

这个比方我觉得挺好懂：

模型本体里存的是”知识”，但它在干活时看到的，只有上下文窗口里的内容。超出窗口的东西，它看不见，也不存在。

这就是为什么：

• 你聊了很长一段时间之后，模型开始”忘事”
• 你让它处理一个超长文档，它只抓住了开头和结尾
• 你的多轮 Agent 任务执行到一半开始乱套

根本原因都一样：窗口装不下了，或者装的东西不对。

上下文工程要做的，说到底就是在这个有限空间里，把最该放进去的东西，用合适的方式放进去。

十一、整理一张表：四个角度看上下文工程

把这四个角度放在一起看，我自己现在的理解是，Context Engineering 其实横跨了四层：

• 模型层：注意力到底怎么分配
• 检索层：拿进来的资料到底准不准
• 工作流层：多步任务怎么传递状态
• 工程层：成本、延迟、缓存、工具契约怎么控制

也正因为它跨层，所以它不是一个“提示词小技巧”，而是 AI 系统设计里绕不过去的一部分。

十二、我目前的几个实际感受

老实说，我自己学这块之前，踩过的坑还真不少：

1. 把所有背景信息一股脑塞进 System Prompt。当时总觉得“多给一点总没错”，结果就是模型越来越飘。后来才明白，不是信息越多越好，是相关信息越准越好。

2. 以为 RAG 就是检索 + 拼接。直接切片、存向量、捞出来就完事。后来真碰到上下文断裂的问题，才意识到：片段不能只被捞出来，它还得“知道自己是谁、从哪来”。

3. 把 Prompt Engineering 和 Context Engineering 混在一起。一开始总觉得问题问对了就行，后来才发现，一到 Agent 场景里，“信息怎么组织”很多时候比“问题怎么问”更靠前。

4. 误以为长上下文天然更强。后来越做越发现，长上下文只是给了你“可以多放点东西进去”的机会，但如果没有筛选、压缩、分层和按需取用，它反而更容易把模型带偏。

说白了，上下文工程是软件工程在 AI 时代的一个延伸——你不只是在写 Prompt，你在设计信息流。

结尾

这篇还是偏学习整理，没有往代码实现那层展开太多，主要先把我自己脑子里这套概念骨架搭起来。

如果你也在做 AI 应用，或者已经开始搭 Agent / AI 系统，我现在会更建议先盯住这几个问题：

1. 你给模型的，到底是不是“最小但高信号”的信息？
2. 你的检索结果，是不是保留了足够的背景语义？
3. 你的多步任务里，有没有一套压缩、记忆、续跑机制？
4. 你的工具和提示词结构，是否清晰到让模型不用猜？

这些问题如果没想清楚，模型就算再聪明，系统表现也还是会一阵一阵的。

Anthropic 最新发布了一篇关于长期运行 Agent 应用 Harness 设计的深度技术文章，作者是 Prithvi Rajasekaran。文章分享了如何通过多 Agent 架构（生成器+评估器）来突破传统单 Agent 的能力天花板，实现复杂应用的自主构建。

核心问题：为什么简单实现不够？

传统的单 Agent 实现会遇到两个关键问题：

1. 上下文焦虑（Context Anxiety）

随着任务时间增长，模型会出现”上下文焦虑”——在接近上下文限制时提前结束工作。虽然上下文压缩（compaction）可以延长会话，但无法给 Agent 一个干净的 slate。解决方案是上下文重置（Context Reset）：完全清空上下文窗口，通过结构化交接（handoff）让新 Agent 接手。

2. 自我评估偏差

当要求 Agent 评估自己的工作质量时，它们往往过于乐观——即使质量明显 mediocre，也会自信地给予好评。这在主观任务（如设计）中尤为明显。

解决方案：分离生成与评估

借鉴 GAN（生成对抗网络）的思想，将生成器（generator）和评估器（evaluator）分离。虽然评估器也是 LLM，但调校一个独立的 skeptical evaluator 比让生成器自我批评要容易得多。

前端设计实验

作者首先在前端设计领域验证这个思路。Claude 默认倾向于安全、可预测的布局，技术可用但视觉平庸。

四项评分标准

为了让主观质量可量化，作者制定了四项评分标准：

重点：Design Quality 和 Originality 权重更高，明确惩罚”AI slop”（紫色渐变+白卡片的典型 AI 生成模式）。

迭代循环

• 生成器创建 HTML/CSS/JS 前端
• 评估器通过 Playwright MCP 与页面交互、截图、评分
• 反馈回流给生成器进行下一轮迭代
• 运行 5-15 轮迭代，每轮 4 小时

惊人发现：在为一个荷兰艺术博物馆设计网站的第 10 轮迭代中，生成器完全推翻了之前的设计，重新想象为一个 3D 空间体验——CSS 透视渲染的方格地板、自由位置悬挂的艺术品、门洞导航而非滚动点击。这是单次生成从未见过的创意飞跃。

扩展到全栈开发

基于前端实验的经验，作者将其应用到全栈开发，构建了一个三 Agent 架构：

架构设计

Sprint 契约

在每次 sprint 前，生成器和评估器协商”sprint 契约”：明确定义”完成”的标准和可测试的行为。这弥补了用户故事与可测试实现之间的鸿沟。

对比实验

Prompt：创建一个 2D 复古游戏制作器，包含关卡编辑器、精灵编辑器、实体行为和可玩测试模式。

关键差异：

• 单 Agent 版本：布局浪费空间、工作流程僵化、核心游戏功能损坏
• Harness 版本：完整 viewport 利用、一致的视觉识别、AI 集成加速工作流、实际可玩的游戏

持续优化

移除 Sprint 结构

随着 Opus 4.6 发布（规划更仔细、更长任务保持、更好的代码审查和调试能力），作者尝试简化 harness：

• 移除 sprint 结构，让生成器连续运行 2 小时以上
• 评估器改为单次最终评估而非每 sprint 评估
• 保留 planner（防止生成器 under-scope）和 evaluator（捕获边缘 bug）

新实验：浏览器端 DAW（数字音频工作站）

• 运行 4 小时，$124
• 生成器连续运行 2 小时无需分解
• 评估器仍捕获关键缺陷：剪辑无法拖动、音频录制仅 stub、效果可视化不足

结论：评估器不是固定的是/否决策，而是取决于任务是否超出生成器独立可靠完成的边界。

核心启示

1. 模型能力边界决定 harness 复杂度：随着模型改进，某些假设可能过时，值得定期 stress test
2. 分解任务 + 专业化 Agent：复杂任务中，分解并应用专业化 Agent 能带来提升
3. 新模型发布时重新评估 harness：剥离不再关键的组件，添加新组件实现更大能力
4. 有趣 harness 组合的空间不会缩小：随着模型改进，空间会移动，AI 工程师的工作是不断找到下一个新颖组合

关键引用

“The space of interesting harness combinations doesn’t shrink as models improve. Instead, it moves, and the interesting work for AI engineers is to keep finding the next novel combination.”

“It is always good practice to experiment with the model you’re building against, read its traces on realistic problems, and tune its performance to achieve your desired outcomes.”

原文链接：https://www.anthropic.com/engineering/harness-design-long-running-apps

作者：Prithvi Rajasekaran (Anthropic Labs)

研发负责人 / 全栈工程师

各位好，

13年一线研发，后端10年（主Java）、前端3年（主React），从写代码到带团队到架构设计，该踩的坑基本都踩过了。

上一段经历，从0到1组了个团队，主导了AI+SaaS宠物医院系统的架构设计和落地，3个月上了1.0版本，拿到天使客户认可。再之前在锐捷网络干了7年多，从前端主程做到Java主程再到LMT负责人，带过10人团队，负责过500+租户的SaaS运维平台核心模块。连续两年绩效A，拿过事业部优秀员工。

技术上，Java全家桶、React、微服务、数据库那些就不赘述了。比较有意思的是做过AI工程化落地——ASR医疗记录生成、RAG知识库、服务器容量预测（ClickHouse + Flink + Prophet + LLaMA2）。另外当过产品助理这段经历，让我在技术和业务之间能自如切换，不会出现”需求理解偏差导致返工”这种事。

带团队这事，比Debug代码难多了。但好在两边成绩单都还过得去。

详细简历在这里：

• 中文简历
• English Resume

代码问候，
Gamehu

联系方式：
电话：18515068121
邮箱：gamehu@yeah.net
Wechat：GamehuDB
Twitter：https://x.com/Gamehu520

P.S. 我的GitHub贡献图可能不够绿，但我的代码从不让服务器变红。

R&D Lead / Full Stack Engineer

Hello everyone,

13 years of hands-on R&D experience — 10 years in backend (primarily Java) and 3 years in frontend (primarily React). I’ve gone from writing code to leading teams to designing architectures. Basically, I’ve stepped into most of the pitfalls there are to find.

In my most recent role, I built a team from 0 to 1 and led the architecture design and implementation of an AI+SaaS veterinary hospital system. We shipped version 1.0 in 3 months and earned validation from our angel customers. Before that, I spent 7+ years at Ruijie Networks, progressing from Frontend Lead to Java Lead to LMT (Lifecycle Management Team) Lead. I managed a 10-person team and owned core modules of a SaaS operations platform serving 500+ tenants. Received “A” performance ratings for two consecutive years and won the Business Unit Outstanding Employee award.

Technically, I won’t bore you with the standard stack — Java ecosystem, React, microservices, databases, etc. What’s more interesting is my work on AI engineering and production deployment: ASR-based medical record generation, RAG knowledge bases, and server capacity prediction (ClickHouse + Flink + Prophet + LLaMA2). Additionally, my stint as a Product Assistant taught me to move fluidly between technical and business perspectives — you’ll never get “requirements misinterpretation leading to rework” from me.

Leading teams is way harder than debugging code. But fortunately, my report card on both fronts is decent enough.

Detailed resumes here:

• Chinese Resume
• English Resume

Code regards,
Gamehu

Contact:
Phone: 18515068121
Email: gamehu@yeah.net
WeChat: GamehuDB
Twitter: https://x.com/Gamehu520

P.S. My GitHub contribution graph may not be green enough, but my code never turns the server red.

最近产品里想要集成业务 Agent，真动手之前我想先把底层逻辑搞清楚，但是深入了解 agent 之前我看到了：Agentic。

它跟 Agent 不是一回事。Agent 是具体的东西，比如一个能自主干活的 AI 助手；Agentic 是一种工作方式——让 AI 能规划、执行、反思、修正，在循环里反复迭代，而不是一问一答就结束。搞懂 Agentic，才知道 Agent 该怎么搭。

说白了，Agentic 不是让 AI 更会说话，而是让 AI 更像一个会反复干活的人。

这篇是我自己的学习整理，不聊实现细节，就想先把这件事用人话讲透。

一、先想明白，我们平时到底是怎么用 AI 的

吴恩达先生以前讲过一个很形象的比喻[^1]。

他说我们现在大部分人用大模型，其实还是 Zero-shot（就是不给任何示例、不做任何拆解，直接让它一把回答）模式。你扔一个 prompt 进去，模型从第一句一路吐到最后一句，中途没有停顿，没有修改，也没有回头看一眼自己写得对不对。

这件事像什么？

像你让一个人从头到尾写一篇文章，但中途不准按退格键。

你想想，这活儿正常人都干不好，更别说我们还指望 AI 一把出神作。

这也是为什么，我现在回头看，会觉得很多时候不是 AI 本身忽强忽弱，而是我们给它的工作方式，本来就有点反人类。
不是它不能干，而是你要求它一次性把所有事情都想对、写对、做对。

但真实世界里的高手不是这么干活的。

不管是写文章、做方案、查资料，还是写代码，正常流程基本都是：

1. 先想一下目标是什么
2. 拆几个步骤出来
3. 缺信息就去查
4. 先搞一个初稿
5. 回头检查漏洞
6. 发现问题再改一轮

这套动作，我们人类觉得理所当然；一到 AI 身上，很多人反而想跳过。

所以我现在理解的 Agentic，本质上就是把这套”人类本来就会的迭代过程”，重新装回 AI 的工作流里。

用一张图来看，差别其实一目了然：

左边就是我们现在大部分人用 AI 的方式：一问一答，结束。
右边是 Agentic 的方式：它会自己转圈，直到结果靠谱为止。

二、Agentic 到底是什么？这是我目前最顺的一句解释

如果非要让我先给自己留一句最顺口的人话解释，我会这么说：

Agentic 不是让 AI 更聪明，而是让 AI 不再只回答一次。

它会在一个循环里反复工作。

比如你让它写一份研究报告，它不是上来就闷头输出 3000 字，而是可能先做这些事：

• 先列提纲，确认应该从哪几个角度展开
• 判断哪些部分信息不够，需要联网搜索或者调资料
• 先写一个版本
• 再自己检查这一版有没有逻辑漏洞、重复废话或者证据不足
• 然后按发现的问题继续改

你看，这不就是一个稍微靠谱点的人在做事的样子吗？

这里最关键的，不是”会不会调用工具”，也不是”会不会写代码”，而是它终于不再被限制在”一次生成、不可回头”的模式里了。

这件事带来的提升，其实很夸张。

吴恩达先生他们测过一组数据，挺有意思的：

GPT-3.5 裸跑代码题只有 48% 正确率，但套上 Agentic 循环以后，直接拉到 95%。比 GPT-4 裸跑的 67% 还高一大截。（数据来自吴恩达 2024 年在 Sequoia AI Ascent 的演讲 Agentic Design Patterns[^1]）

我觉得这组数字最值得咂摸的地方，不是某个模型赢了，而是它说明了一件事：

工作流设计，在很多场景下，已经开始比”模型单次裸跑能力”更重要了。

以前大家拼谁的 prompt 写得玄。
现在越来越像在拼，谁更懂得给 AI 安排一个像样的工作流程。

三、我先把 Agentic 拆成四个最核心的招式

吴恩达先生后来把 Agentic 总结成四种常见设计模式[^1]。我自己的感受是，这四个词看起来有点学术，但翻译成人话之后，反而会一下子清楚很多。

先上一张全景图，让你对这四个模式的关系有个整体感觉：

graph TB
    MA[多智能体协作
把任务分给不同角色] --> PL[规划
拆任务、定顺序]
    PL --> EX[执行 + 工具使用
干活、调工具]
    EX --> RF[反思
回头检查、修正]
    RF -->|发现问题| PL
    RF -->|通过| OUT[输出结果]
    style MA fill:#e6f3ff
    style PL fill:#fff3e6
    style EX fill:#e6ffe6
    style RF fill:#ffe6e6

简单说就是：多个角色分工（多智能体） → 每个角色先想清楚再动手（规划） → 该查就查、该调就调（工具使用） → 做完回头看一遍（反思） → 不行就再来一轮。

1. 反思（Reflection）

一句话类比：写完作文自己通读一遍，删掉废话、补上漏洞。

就是让 AI 不要交卷就跑，而是看一眼自己刚刚写了什么。

有没有逻辑不通的地方？
有没有明显没回答到题？
有没有一堆正确但没用的废话？

这一步特别像我们自己写完文章后，隔两分钟再回来看，突然发现：

“这段说了等于没说。”
“这个论点站不住。”
“这里应该删，不然啰嗦。”

很多看起来”更聪明”的 AI 应用，往往不是第一次就答得特别神，而是多了一轮自我审稿。

2. 工具使用（Tool Use）

一句话类比：查字典、翻参考书，而不是全靠记忆硬撑。

AI 靠自己脑补，肯定有上限。
所以你得允许它出门干活。

比如：

• 去搜资料
• 读文件
• 跑代码
• 查数据库
• 调 API
• 调用外部系统

工具这件事，本质上是在补模型的”手脚”。
只有脑子，没有手脚，它很多事永远只能停留在嘴上。

3. 规划（Planning）

一句话类比：做菜之前先看一遍菜谱，别上来就开火。

规划说白了就是，别一股脑往前冲，先想一下顺序。

面对复杂任务，先拆，再干，效率会高很多。比如：

• 先定目标
• 再拆子任务
• 然后决定哪些任务要查资料，哪些任务可以直接写
• 最后再汇总

人一旦不规划，容易瞎忙。
AI 一旦不规划，容易一本正经地跑偏。

4. 多智能体协作（Multi-agent Collaboration）

一句话类比：一个人拍电影不如分工——导演、编剧、摄影各管各的。

这个词听起来很高级，实际你可以把它理解成”别让一个 AI 同时扮演所有角色”。

比如一个负责搜集资料，一个负责写初稿，一个负责挑刺，一个负责做最终汇总。
甚至它们之间还可以互相辩论。

这套思路的价值，不在于搞得多复杂，而在于：
不同角色的关注点本来就不一样，拆开之后，结果往往比一个 AI 一把梭更稳。

四、从会跑到跑得稳，还差这两样东西：Harness 和 Traces

上面四个招式看起来挺简单的对吧？但一旦真让 AI 跑起来，你马上会碰到两个问题：

1. 它跑偏了你怎么兜住？
2. 它跑偏了你怎么知道？

第一个问题，对应的是 Harness；第二个问题，对应的是 Traces。

Harness：给 AI 装上安全带和工具腰带

如果我只把 Agentic 理解成”让 AI 多跑几轮”，那其实只理解了一半。

LangChain 的 Harrison Chase 提过一个我很认同的点：今天很多 Agentic 系统之所以变强，不只是因为模型本身更好了，而是因为我们给它加了一套越来越完整的”外围设施”。

他管这个叫 Harness。说白了，就是你在让 AI 干活之前，先给它搭好的一整套工作台——什么工具能用、什么文件能动、上下文怎么喂、出了问题怎么回滚。

举个具体的例子：你让 AI 帮你写一段代码。如果是裸跑，它只能凭记忆硬编。但如果有了 Harness，它可以先读你项目里的现有代码（文件系统权限），记住你之前说过的偏好（记忆机制），按步骤拆解任务（规划能力），跑完代码自动测试（验证机制），测试没过就自动回退（回滚机制）。

这时候你就能理解，为什么现在很多团队开始讲 Context Engineering（上下文工程），而不只是讲 Prompt Engineering 了。

打个比方：如果 Prompt 是你跟 AI 说的那句话，那 Context Engineering 就是你在它开口之前，帮它把该看的资料、该知道的规则、该用的工具全部摆到桌面上。

这俩压根不是一个量级的事。

以前大家总想找一句神 prompt 包打天下。
现在越来越像搭一个工作台，把 AI 放进去之后，它每一步都有人给它递对工具、递对材料、递对约束。

Agentic 拼到后面，拼的不是一句提示词写得多花，而是谁更会给 AI 配环境、配反馈、配护栏。

Traces：给 AI 装上飞行记录仪

好，Harness 解决了”怎么兜住”。但还有个问题：AI 跑偏了，你怎么知道它是在哪一步开始偏的？

传统软件有个好处——代码基本就是规则本身，程序为什么这么跑，你顺着代码就能看明白。

但 Agentic 不一样。它不是一条固定路径跑到底，而是在循环里不断判断、选择、调用工具、修正方向。你第 14 步看到它翻车的时候，真正的问题很可能出在第 3 步，甚至第 1 步。

这时候最有价值的东西就不是”它最终输出了什么”，而是它每一步的操作日志——每一步看到了什么上下文、为什么做出这个判断、调了哪些工具、工具返回了什么、它是基于什么决定继续还是回退。

这些记录，就是 Traces（追踪日志）。

它特别像什么？像飞行记录仪。

平时你可能不看，但一旦出事，没有它你基本就是瞎猜。

所以我现在会提醒自己，未来如果真要在业务里落地 Agentic，不能只盯着”能不能跑通”。没有 trace 的系统，很多时候只是看起来能跑，一出问题你根本没法定位。

五、对我这种准备落业务的人来说，更现实的姿势不是全自动，而是”人类在环”

上图展示的是一个理想的自主智能体循环：任务执行 → 任务创建 → 优先级排序 → 继续执行，理论上可以无限循环直到目标达成。

但看到这里，我自己先记一个结论：

小白入门 Agentic，千万别一上来就追求 100% 自动驾驶。

这事听起来很性感，做起来经常很危险。

因为长链路任务一旦完全放飞，AI 很容易在你没注意的时候，往一个看似合理、其实已经偏掉的方向一路狂奔。

所以比”全自动”更现实的做法，是先把它当成一个很强的起草机、陪练和执行器。

比如：

• 帮你先起一个方案初稿
• 帮你做一版调研汇总
• 帮你把一堆需求整理成结构化任务
• 帮你先生成代码骨架和测试思路

然后关键决策点交给人来审。

我很认同一种说法，叫 Keep the AI on the leash。
翻译得粗暴点，就是：别把绳子撒手。

你要给它一定的自主性，但这个自主性必须可调。

它能跑，但你随时能：

• 看见它干了什么
• 拒绝它的修改
• 编辑它的中间结果
• 在关键节点让它停下来等你确认

这就是所谓的 Human-in-the-loop（人类在关键节点把关）。

它听起来好像”不够自动化”，但对真实业务来说，这反而是更成熟的状态。
因为信任不是靠宣传建立的，是靠”我看得见、控得住、改得回”建立的。

六、如果我后面真要往业务里落，起步大概率会先套这个最小闭环

说了这么多，最后落到实操，我觉得最适合我这种还在往业务里试的人，Agentic 起步姿势就先四步：

graph LR
    P[1. 规划
拆任务、定目标] --> E[2. 执行
搜资料、调工具]
    E --> R[3. 自我反思
挑刺、补漏]
    R --> H[4. 人类审核
关键节点拍板]
    H -->|需要修正| P
    H -->|通过| D[交付]
    style P fill:#fff3e6
    style E fill:#e6ffe6
    style R fill:#ffe6e6
    style H fill:#e6f3ff

1. 规划

先别急着让 AI 干活，先让它拆任务。

问清楚目标是什么，输出物是什么，哪些约束不能碰，哪些信息还缺。

2. 执行

该搜资料就搜，该读文件就读，该调工具就调。
这一步别只让它靠记忆硬编。

3. 自我反思

让它自己回头挑刺。
检查逻辑、补证据、删废话、找风险点。

4. 人类审核

关键节点必须有人拍板。
尤其是涉及代码变更、对外发布、客户沟通、业务决策的内容。

这四步看起来很朴素，但已经足够构成一个靠谱的 Agentic 最小闭环。

它真正打碎的，其实也是我自己之前对 AI 的一个幻觉：

不是”有没有一个神 prompt 能一次性解决问题”，而是”我能不能把问题组织成一个能不断修正的流程”。

这两个思路，差别非常大。

七、最后记一笔

如果我现在还把 AI 只当成一个高级搜索框，或者一个会写字的聊天机器人，那我大概率还没真正进入 Agentic 这套工作方式。

Agentic 的重点，从来不是”让 AI 更像人聊天”，而是”让 AI 更像一个可以在工作流里持续推进任务的执行者”。

它会规划，会调用工具，会回头反思，会在必要的时候把决定权交还给人。

我越来越觉得，接下来 AI 应用真正拉开差距的地方，不是大家都在拼模型参数，而是谁先把这套工作方式吃透。

毕竟现实里真正靠谱的人，也不是因为他永远第一次就做对。
而是因为他会：

• 先想清楚
• 再动手
• 做完回头看
• 发现不对就改

现在，只不过我们开始要求 AI 也这么干了。

参考与延伸阅读

[^1]: AI Agents that Work: Agentic Design Patterns - Andrew Ng, DeepLearning.AI

延伸阅读：

• LLM Powered Autonomous Agents - Lilian Weng (OpenAI)
• Intro to Large Language Models - Andrej Karpathy
• Birth of BabyAGI - Yohei Nakajima

引言

先说明一下，我不是专业架构师。

之前在上一家公司，我更多做的是一些模块和组件级别的设计。真正意义上从 0 到 1 去设计一整套 AI + SaaS 系统，这次算是第一次，而且第一版已经上线了。

所以这篇不是想讲什么大方法论，也不是想摆什么架构姿势。我就是想趁第一版刚做完、产品也刚上线这个节点，老老实实回头看一遍：这套架构到底哪里想对了，哪里其实一开始很容易想偏，后面又该往哪个方向继续长。

场景并不抽象，就是很实际的那种：

• 单机构起步，但架构上要预留多机构扩展能力
• 后续希望还能继续扩

最开始我脑子里也闪过很多“终局形态”的东西，比如实时音频、拾音器、边缘盒子、流式 ASR之类。但第一版真的做下来以后，我反而更确定，这事不能按“终局幻想”来起手。

因为我做的不是写一份 PPT，也不是画一个看起来很唬人的全景图，而是在想：第一次真把产品做出来并上线时，这版架构最该优先解决什么，最不该一开始就做什么。

所以这篇我不想从科普角度写，也不想从“终局方案”往回倒推，我就想站在“第一版已经做完并且上线了”这个节点上，回头复盘一下我对这套架构的几个真实判断，以及我对下一阶段的打算。

另外还有两个底层想法，第一版做完以后我也越来越确认。

一个是，架构这事基本不可能一开始就设计到终局。真要硬往“一步到位”去做，很多时候不是做重了，就是做偏了。
但反过来也不能只盯着眼前这点需求，完全不看后面，不然技术债很容易越滚越大。

所以我现在更认可的状态是：别做过度/超前设计，但也别把明天大概率会出问题的坑，当成今天看不见。别把技术债留得过多过重

另一个是，架构不能脱离业务自己玩。
对我来说，架构不是先设计一套很漂亮的东西，再让业务来适配它，而是业务走到哪一步，架构就支撑到哪一步，同时再比当前业务多想半步。

这样做的好处也很现实：

• 成本可控
• 业务更容易买单
• 系统后面也还能继续长

一、第一个判断：这玩意儿本质上还是 SaaS，AI 只是把架构重点改了

第一版做完以后，我反而更不认同一种说法，就是只要系统里带 AI，它就好像跟传统 SaaS 完全不是一类东西了。

在我看来，不是。

这套系统的底子，依然是一个标准的行业 SaaS。

如果不用那些太虚的词，只说我自己现在真正在想的东西，这套系统至少得先把这些基础问题想清楚：

• 多租户怎么做，集团、中心医院、诊所之间怎么分层
• 一个集团下面多门店怎么表达
• 权限模型怎么设计，总部、店长、医生、护士分别能看什么、做什么
• 宠物、主人、就诊、病历、经营数据这些核心对象怎么设计
• 门店在用的能力和总部在用的能力怎么拆，也就是服务边界怎么划
• 哪些数据共享，哪些数据隔离
• AI 和后面的第三方能力从哪里接进来

这些东西一个都跑不掉。

如果这些没打稳，AI 做得再花也没意义。因为用户最终买单的，还是一个能跑业务、能沉淀数据、能让总部和门店都用起来的系统。

而且这里还有一个我现在越来越重视的点：软件架构不能脱离业务目标单独存在。

我们做这套产品，不是为了做一个“功能很多的宠物行业工具箱”，而是希望软件能真正深入到客户的经营和日常管理里，最终达到两个目标：

1. 提升一线执行效率
2. 辅助决策

如果离开这两个目标去谈架构，很多设计最后都会变成自嗨。

而且第一版做完以后，我对“架构要跟业务一起迭代”这件事更有感觉了。

不是说业务提什么，技术就机械配合什么。
而是当前业务最需要什么，架构就先把这块支撑稳；等业务往前走了，架构再跟着长。

这样做最现实的好处就是，不容易一开始把系统做得过重，同时也不至于后面业务一变，系统马上顶不住。

但 AI 的加入，确实把架构重点改了。

传统 SaaS 更多是在处理确定性流程。
比如录入、查询、审批、结算、统计，这些本质上都是规则系统。

而 AI + SaaS 不一样的点在于，它把一个“结果不那么稳定”的处理环节塞进了原本稳定的业务链路里。

第一版做下来，我还是觉得这就是两者最大的区别。

不是多了一个模型服务，也不是页面上多了一个 AI 按钮，而是：

原来的系统主要是在执行确定规则，现在我要开始想办法把“不那么稳定的结果”稳稳地放进业务流程里。

这件事一旦成立，很多设计思路都会跟传统 SaaS 不一样。

二、第二个判断：AI + SaaS 和传统 SaaS 的区别，重点不在技术名词，在系统责任边界

我现在看这个问题，最核心的差异其实在责任边界。

传统 SaaS 的责任边界相对清楚：

• 前端负责采集输入
• 后端按规则处理
• 数据库存业务真相
• 报表系统做统计分析

只要规则是对的，系统结果通常就是可预期的。

但 AI + SaaS 不一样。

因为 AI 的结果很多时候不是“错或者对”这么简单，它经常是：

• 大方向对了，但细节不够稳
• 能生成，但格式不稳定
• 能抽取，但字段偶尔偏
• 没报错，但不好直接入库

所以我在做这类架构设计时，脑子里会比传统 SaaS 多一层问题：

1. AI 结果是不是业务真相？
2. 什么时候只能当草稿？
3. 谁来确认？
4. 错了以后怎么回退？
5. 怎么看它到底好不好用？

这几个问题如果不单独设计，AI 最后就很容易变成系统里一个“看起来高级，但责任全是人工兜底”的模块。

而且这里我现在回头看，除了“人工确认”本身，还少不了几件配套的事：

• 要有校验
• 要有留痕
• 要能审计
• 要知道是模型错了、流程错了，还是输入本身就有问题

再往业务上说得直白一点。

传统 SaaS 在大多数时候更像一个被动工具：

• 你录，我存
• 你查，我返
• 你点，我算

它的核心价值当然也很大，但更多是把业务流程线上化、结构化、可追溯化。

而 AI + SaaS 不一样的地方在于，它开始有机会从“被动响应”走向“主动参与”：

• 主动给出病历草稿
• 主动提炼摘要
• 主动发现异常点
• 主动给经营分析做提示
• 在规则允许的情况下，直接参与完成某个动作

第一版做完以后，我更确定这是一条很重要的分界线：

传统 SaaS 更像工具，AI + SaaS 更像会参与业务的助手。

它不只是把信息存起来，而是开始参与反馈、辅助决策，甚至在某些边界清晰的场景里直接把事情做完。

但这个前提一定是责任边界清楚，而不是把所有风险都重新甩回给人。

所以我现在回头看，第一版里最正确的一条原则就是：

AI 先做增强，不直接做裁决；先做草稿，不直接做真相。总之一定要预留口子让人工能参与到最终结果中

这也是我现在跟传统 SaaS 设计思路分叉最明显的地方。

三、第三个判断：第一次从 0 到 1 做这个产品，第一版最重要的不是实时，而是业务闭环

如果按传统软件思维，很容易觉得“架构高级”意味着实时、自动化、全链路采集。

但第一版做完以后，我反而更确认，第一次从 0 到 1 做这个产品，最重要的不是实时，而是闭环。

也就是说，我先要证明的是：

• 医生到底愿不愿意用 AI 结果
• AI 生成的病历草稿到底有没有实际价值
• 摘要、结构化抽取、辅助录入，这几个点哪个最值得先做
• 整个交互链路能不能跑通
• AI 的结果有没有真的进入经营与日常管理，而不是停留在“看起来挺聪明”

这些事情没跑通之前，我不太愿意一开始就把问题抬到“实时音频 + 设备采集 + 边缘节点”那个复杂度。

因为那样一来，系统的验证变量一下子就太多了。

我到时候都很难判断：

• 是 AI 本身没价值
• 还是采集方式不稳定
• 还是现场网络问题
• 还是硬件运维太重
• 还是门店根本不愿意配合

这种情况下，架构不是在帮我缩小问题，而是在帮我放大噪音。

现在回头看，我当时这个思路是对的：

第一版先做最小业务闭环，先证明 AI 在软件链路和管理链路里能成立，再考虑它在硬件链路里值不值得做深。

四、第四个判断：第一版不上拾音器，也不上边缘盒子，这个取舍我现在依然认

第一版做完以后，我依然觉得这个取舍是对的。

不是说以后一定不做，而是第一版确实不该这么起手。

说到底，这也是“架构逐步演进”这件事在我这个项目里的一个具体体现。

如果我一开始就按终局形态去堆，很可能会显得我想得很多，但真正落到第一版，成本不一定扛得住，业务也未必真买单。
但如果我只顾着先上线，完全不看后面，那等门店一多、数据一上来、链路一拉长，系统也会很快露出问题。

所以这里最难的其实不是选“重”还是“轻”，而是拿捏这个度。

原因很现实。

1. 这不是当前最核心的验证点

我第一版最想验证的，就是 AI 在病历生成、摘要提炼、结构化录入这些环节到底能不能形成价值。

而拾音器和边缘盒子，解决的是更后面的工程化问题：

• 自动采集
• 弱网缓存
• 实时流处理
• 多门店部署一致性
• 硬件和云端协同

这些当然重要，但它们不是当前第一性问题。

2. 一上硬件，复杂度会成倍上升

一旦加上硬件，我要额外处理的事情太多了：

• 设备安装
• 门店网络环境
• 音频质量
• 远程运维
• 故障排查
• 升级策略

而这些问题跟“AI 到底有没有产品价值”并不是一回事。

如果第一版就把它们全绑在一起，我很可能会把项目节奏拖慢。

3. 边缘盒子更像后续规模化阶段的优化件，不像我当前第一版的必需件

现在回头看，我对边缘盒子的判断还是没变：它更像是当业务跑起来以后，为了解决稳定性、缓存、补传、弱网和成本问题，才逐步变得必要的组件。

也就是说，它更偏工程放大器，而不是第一版价值验证器。

所以至少在第一版阶段，我没把它当默认配置。

五、第五个判断：第一版更应该先长成一个“带 AI 助手能力的 SaaS”，而不是“AI IoT 系统”

这是我第一版做完以后非常清晰的一个分界线。

如果按我现在回头看的思路，第一版更像一个带 AI 助手能力的 SaaS，而不是一个带重硬件形态的 AI 系统。

我第一版其实就是更倾向先用现有的软件入口去做输入：

• 医生手工录入问诊信息
• 医生或前台上传录音文件
• 问诊后补一段文字摘要
• 结合既有病历和检查结果补上下文

然后 AI 先做这几件事：

1. 生成病历草稿
2. 生成问诊摘要
3. 抽结构化字段

这里我最看重的，不是“炫”，而是架构能不能形成一个清晰闭环：

1
2
3
4
5
6
7

业务输入
  -> AI任务创建
  -> 上下文装配
  -> 模型处理
  -> 结果生成
  -> 医生确认
  -> 回写正式业务数据

只要这个闭环能稳定跑通，这个 0 到 1 的第一版就能积累很多非常关键的东西：

• 什么输入最有效
• 什么场景采纳率高
• 医生改动最多的是哪部分
• 结构化抽取最容易错在哪
• 单次任务的成本大概多少

而第一版上线以后，我也确实开始更清楚地看到了一个更重要的经营问题：

• 这套系统到底是在帮客户“省时间”
• 还是在帮客户“提质量”
• 还是已经开始帮客户“做判断”

这些数据，在我看来比第一天就把拾音器装进诊室更有价值。

六、第六个判断：这套架构和传统 SaaS 的真正区别，是要单独设计 AI 任务层，后面再看要不要长出辅助经营判断的能力

如果这事只是传统 SaaS，我的主线大概就是：

1

前端 -> API -> 业务服务 -> 数据库

但现在因为有 AI，这个链路在我脑子里已经不是这么简单了。

我在第一版里专门抽了一层出来，承接 AI 相关逻辑。

也就是我这里说的 AI 任务层。

这一层至少要管这些事情：

• 什么时候创建 AI 任务
• 任务吃哪些上下文
• 调哪个模型
• 模型返回后怎么校验
• 结果是进入草稿态还是直接丢弃
• 有没有失败重试
• 怎么记录状态

说白了，这一层不是简单转发一下请求，而是把业务上下文、模型能力、状态流转、校验逻辑和人工确认流程串起来。

这层如果不抽出来，AI 逻辑最后就会散在各个业务模块里。

到时候最麻烦的不是代码丑，而是：

• 你根本说不清 AI 到底在哪儿影响了业务
• 你很难统一做评测
• 你没法统计成本
• 你也没法稳定优化效果

所以第一版做完以后，我更明确了一件事，AI + SaaS 和传统 SaaS 的关键架构差异之一，就是：

传统 SaaS 的主干是业务服务层，AI + SaaS 需要在业务服务层之外，再长出一层 AI 任务层。

这层不是附属物，是骨架的一部分。

而且从上线后的视角看，这层不只是为了“把流程串起来”，它本质上还承担了稳定性和兜底职责。

至少在我现在的理解里，这一层后面一定要逐步补齐这些能力：

• 用状态机管理任务流转，而不是靠 if else 到处补
• 幂等处理，避免重复提交、重复执行
• 失败重试，但不能无限重试
• 超时控制，避免模型调用把主链路拖死
• 降级策略，模型不稳定时至少不能把核心业务流程卡住
• 可观测性，要能看到任务卡在哪一步、失败在哪一步

说白了，AI 任务层不只是“调一次模型”，它后面其实是一个带容错和兜底能力的处理链路。

而且我现在已经能感觉到，到了下一阶段，光有任务层可能还不够，后面很可能还会自然长出一块专门做经营分析、异常提醒、辅助判断的能力。

因为一旦系统开始服务经营和管理，它就不能只停留在“帮你生成一段文字”，而要开始回答这些问题：

• 这家门店最近的复诊率有没有异常
• 哪类服务项目转化更差
• 哪个医生的病历质量波动比较大
• 哪些经营动作值得提醒

到那个阶段，AI 的价值就不再只是内容生成，而是开始进入经营反馈和辅助决策。

七、第七个判断：第一版里，AI 结果不能直接等于业务真相，但下一阶段它可以逐步参与执行

这一点我现在回头看，基本还是不会妥协。

因为只要 AI 结果直接落正式数据，系统就会立刻变得很危险。

尤其在这种医疗相关场景里，我现在还是更倾向于把 AI 结果定义为：

• 草稿
• 建议
• 候选结果
• 辅助结构化信息

而不是最终记录。

所以第一版里，我实际更愿意让系统变成下面这种关系：

1
2
3
4
5
6

flowchart TD
    A["SaaS业务输入"] --> B["AI任务层"]
    B --> C["模型处理层"]
    C --> D["草稿结果层"]
    D --> E["医生确认/修订"]
    E --> F["正式业务数据"]

这里面最重要的，不是图画得多复杂，而是责任边界很清楚：

• AI 负责产出建议
• 医生负责确认
• 业务系统负责保存真相

这个边界不清，后面系统只会越来越难收。

而且上线以后我更确定一点：任何模型调用失败、结构化失败、结果不稳定，都不应该阻断核心业务流程。

也就是说，AI 这条链路可以失败，可以降级，可以回退到人工处理，但不能把主业务链路一起拖死。

这个在我看来其实也是架构设计里很现实的一部分，不能只想着“AI 成功时多聪明”，还得提前想好“它失败时系统怎么活”。

但另一方面，我也不认为 AI 永远只该停留在“建议层”。

我现在对下一阶段的看法是：

• 在高风险场景里，AI 先当建议者
• 在低风险、规则清晰、可审计的场景里，AI 后面是可以逐步参与执行的

比如一些经营类、运营类、流程类动作，未来完全可能从：

辅助生成 -> 辅助判断 -> 人工确认 -> 自动执行

一路往下演进。

这也是我觉得 AI + SaaS 和传统 SaaS 最终会拉开差距的地方。

传统 SaaS 更多还是一个承载流程的系统。
AI + SaaS 如果做得足够深，是有机会从“把流程记下来”走向“参与把事情做下去”的。

最后

写到这里，我其实更确定了自己做完第一版、并且产品已经上线以后，对这套架构的几个核心判断：

1. 这套系统的底子依然是 SaaS，不是先上 AI 再补业务
2. 软件架构不能脱离业务目标，我的目标不是做工具，而是深入客户经营和日常管理
3. AI + SaaS 和传统 SaaS 的区别，核心在于我要处理一个“结果不那么稳定的能力”进入业务链路后的责任边界
4. 第一版最重要的是业务闭环，不是实时
5. 第一版不上拾音器，也不上边缘盒子，这个取舍我现在依然认
6. 第一版更像一个带 AI 助手能力的 SaaS，而不是 AI IoT 系统
7. 架构上必须单独抽出 AI 任务层，下一阶段再看要不要单独做经营分析和辅助判断这块能力
8. AI 结果先当草稿，不直接当业务真相，但下一阶段可以逐步参与一些低风险动作

后面随着门店变多、采集量变大、实时性要求变强，拾音器、边缘节点这些东西大概率都会重新进入架构讨论。

但那应该发生在“软件闭环已经成立”之后，而不是之前。

至少以我当前这版软件设计来看，我更愿意先把这件事做对，再把它做重。

本文数据来源于 JoshKale/jobs 项目，该项目由 Andrej Karpathy（前 OpenAI 联合创始人、Tesla AI 总监）发起，后由 Josh Kale 维护。项目基于美国劳工统计局（BLS）的342种职业数据，使用 Gemini Flash AI 模型对每个职业进行 AI 暴露评分（0-10分），分数越高表示被 AI 替代的风险越大。

核心发现

这份研究报告涵盖了美国经济中 342 种职业，涉及 1.43 亿个工作岗位。研究发现：

• 全行业平均暴露分：5.3/10（高于中位数）
• 高危职业（8分以上）：60 个
• 极高危职业（9-10分）：31 个

这意味着，约 6000 万个岗位处于高风险区间，占所有岗位的 **42%**。

Karpathy 的核心观点：”如果你的全部工作都在屏幕上进行，那你就危险了。”

评分标准解读

在深入了解高危职业之前，让我们先理解评分标准：

核心判断标准：工作产出是否是根本性的数字化的？如果能在家庭办公室通过电脑完成——写作、编程、分析、沟通——那么 AI 暴露就是天然高的。

高危职业排行榜（8分以上）

🚨 满分 10/10（最高风险）

1. 医疗转录员 (Medical transcriptionists)

暴露评分：10/10

AI 评估理由：医疗转录是一种纯粹数字化、常规性的信息处理任务，已经受到语音识别的严重冲击。现代 AI 语音转文字技术已经达到很高的准确率，可以自动识别医学术语并生成标准化文档。这项工作的核心——听录音并转写为文字——完全可以由 AI 完成，人类只需进行简单的校对即可。

为什么最危险？

• 工作完全数字化（音频→文字）
• 任务高度标准化和规范化
• 语音识别技术已经成熟
• 不需要人际互动或物理操作

⚠️ 9/10 分（极高风险）- 30个职业

以下是评分 9 分的职业，按字母顺序排列：

2. 账单和账户催收员 (Bill and account collectors)

暴露评分：9/10

工作几乎完全数字化，包括数据分析、查找追踪和电话/电脑沟通。AI 和自动化系统已经推动了该行业 10% 的就业下降。

3. 簿记、会计和审计文员 (Bookkeeping, accounting, and auditing clerks)

暴露评分：9/10

几乎完全数字化的日常工作，涉及信息处理、数据录入和数学验证。AI 和自动化软件已经能够以高精度执行这些任务。

4. 计算机和信息研究科学家 (Computer and information research scientists)

暴露评分：9/10

虽然这些科学家是构建 AI 的人，但他们创造的工具越来越能够自动化自己的核心任务，如编写代码、简化算法和分析实验结果。

5. 计算机程序员 (Computer programmers)

暴露评分：9/10

编写、测试和调试代码的核心任务完全数字化，与大语言模型的优势完美契合。BLS 特别预测由于自动化和 AI，该职业将出现下降。

6. 法庭记录员和同声传译员 (Court reporters and simultaneous captioners)

暴露评分：9/10

工作的核心产出是逐字数字转录，而 AI 语音转文字和自然语言处理在这一领域已经达到很高水平。

7. 客户服务代表 (Customer service representatives)

暴露评分：9/10

回答询问、处理订单和解决投诉的核心职责本质上是数字化和信息化的。大语言模型和 AI 代理已经能够处理复杂的自然语言交互。

8. 数据科学家 (Data scientists)

暴露评分：9/10

完全数字化的职业，以编码、统计建模和数据分析为中心——这些都是 AI 正在迅速达到或超越人类能力的领域。

9. 数据库管理员和架构师 (Database administrators and architects)

暴露评分：9/10

完全数字化的工作，涉及 SQL 编码、系统架构和数据管理。AI 已经可以自动化日常 DBA 任务，如性能调优和查询优化。

10. 桌面出版商 (Desktop publishers)

暴露评分：9/10

工作产品完全数字化，涉及常规信息处理、版面设计和基础编辑——这些都是 AI 高度擅长的领域。

11. 绘图员 (Drafters)

暴露评分：9/10

工作几乎完全数字化，将概念草图转换为技术 CAD 和 BIM 模型。AI 正在迅速发展出生成和优化设计的能力。

12. 经济学家 (Economists)

暴露评分：9/10

工作几乎完全数字化，涉及数据分析、数学建模和技术写作。AI 在数据处理、预测建模和报告生成方面表现出色。

13. 编辑 (Editors)

暴露评分：9/10

完全数字化的职业，以语言处理为核心——这是大语言模型的核心优势。AI 已经可以执行高级文案编辑、语法纠正和内容优化。

14. 财务分析师 (Financial analysts)

暴露评分：9/10

工作几乎完全数字化，涉及处理大型数据集、趋势分析和生成报告。AI 能够以更高的速度和准确性完成这些任务。

15. 财务文员 (Financial clerks)

暴露评分：9/10

执行常规的、以数字为先的任务，如数据录入、记录更新和基础财务计算，这些都是软件自动化的理想目标。

16. 普通办公室职员 (General office clerks)

暴露评分：9/10

核心职责——数据录入、文档格式化、日程安排和信息处理——几乎完全数字化和常规化。

17. 平面设计师 (Graphic designers)

暴露评分：9/10

根本性的数字化职业，核心任务——图像生成、版面创建和照片编辑——正被生成式 AI 迅速改变。

18. 保险核保人 (Insurance underwriters)

暴露评分：9/10

根本性的数字化职业，以常规信息处理、风险建模和数据分析为中心——这些都是 AI 擅长的领域。

19. 口译员和笔译员 (Interpreters and translators)

暴露评分：9/10

核心工作产品是纯粹数字化信息（文本和语音），而大语言模型在这一领域已经展现出接近人类水平的能力。

20. 市场研究分析师 (Market research analysts)

暴露评分：9/10

核心职责——数据收集、统计分析、趋势预测和报告生成——本质上是数字化的，与大语言模型的能力完美契合。

21. 数学家和统计学家 (Mathematicians and statisticians)

暴露评分：9/10

几乎完全数字化的工作，涉及数据分析、数学建模和编码——这些都是 AI 和大语言模型高度胜任的领域。

22. 医疗记录专员 (Medical records specialists)

暴露评分：9/10

几乎完全数字化，涉及在电子系统中处理、分类和录入数据。AI 已经高度擅长医疗编码和文档处理。

23. 运筹学分析师 (Operations research analysts)

暴露评分：9/10

几乎完全数字化的工作，涉及数据收集、数学建模和报告撰写——这些都是 AI 擅长的领域。

24. 律师助理和法律助理 (Paralegals and legal assistants)

暴露评分：9/10

核心职责——法律研究、文件起草和信息组织——本质上是数字化的，与大语言模型的优势完美契合。

25. 软件开发人员、QA 分析师和测试人员 (Software developers, QA analysts, and testers)

暴露评分：9/10

根本性的数字化职业，编码、调试和测试自动化的核心任务是大语言模型的主要应用场景。

26. 特效艺术家和动画师 (Special effects artists and animators)

暴露评分：9/10

几乎完全数字化的工作，3D 建模、渲染和动画的核心任务正被生成式 AI 和自动化工具直接颠覆。

27. 调查研究人员 (Survey researchers)

暴露评分：9/10

根本性的数字化知识职业，涉及背景研究、调查设计、统计分析和报告生成——全部都是 AI 的高暴露领域。

28. 技术文档撰写员 (Technical writers)

暴露评分：9/10

完全数字化的职业，将复杂信息综合成清晰文档——这是大语言模型的核心优势。

29. 旅行代理 (Travel agents)

暴露评分：9/10

核心功能——研究目的地、比较价格、构建行程和处理预订——完全数字化且常规化，已经被 AI 旅行规划工具大量替代。

30. Web 开发人员和数字设计师 (Web developers and digital designers)

暴露评分：9/10

完全数字化的职业，编写代码（HTML、JavaScript）、设计布局和创建原型都是 AI 迅速改进的领域。

31. 作家和作者 (Writers and authors)

暴露评分：9/10

核心工作产品完全数字化和文本化，与大语言模型的主要能力完美契合。AI 已经可以生成长篇连贯的叙述、营销文案和技术文档。

🔶 8/10 分（很高风险）- 29个职业

以下是评分 8 分的职业，同样面临很高的 AI 替代风险：

高危职业的共同点

通过分析这 60 个高危职业，我们可以总结出以下共同特征：

1. 工作产品完全数字化

几乎所有 8 分以上的职业，其工作产出都是数字化的：

• 文本（作家、编辑、技术文档撰写员）
• 代码（程序员、软件开发人员）
• 数据（数据科学家、财务分析师）
• 图像（平面设计师、特效艺术家）

2. 任务常规化和可预测

高危职业往往涉及：

• 信息处理和数据录入
• 模式识别和分类
• 规则驱动的决策
• 标准化的分析和报告

3. 不需要物理操作或人际互动

这些工作通常：

• 可以在家庭办公室完成
• 不需要体力劳动
• 不需要现场判断或手动操作
• 人际互动可以通过数字渠道完成

为什么这些职业最危险？

Goodhart 定律的启示

经济学中有一个著名的 Goodhart 定律：

“当一个指标变成目标时，它就不再是一个好的指标。”

在 AI 替代的语境下，这意味着：

当 AI 针对某个特定任务进行优化时，人类在该任务上的相对优势就会迅速丧失。

高危职业的共同点是：它们的核心任务恰好是 AI 正在快速优化的领域。

当前 AI 的能力边界

现代 AI（尤其是大语言模型）在以下领域已经达到或接近人类水平：

对软件行业的特别警示

作为一名软件从业者，我必须特别关注报告中的一些发现：

软件开发的 9/10 评分

软件开发人员、QA 分析师和测试人员被评为 9/10 分，这意味着：

1. 编码本身正被 AI 快速掌握

   • GitHub Copilot 等工具已经能够生成大量代码
   • AI 在代码审查、bug 修复方面的能力快速提升

2. 但并非所有软件工作都同样危险

报告指出，以下技能更难被自动化：

• 系统架构设计
• 将模糊的产品需求转化为精确的技术约束
• 理解”应该构建什么”和”为什么构建”

建议：软件从业者应该优先发展这些难以描述为”文本生成”的技能。

相对安全的职业有哪些？

为了对比，让我们看看评分最低的职业：

共同特点：需要物理存在、手工技能、实时人际互动或在不可预测的物理环境中工作。

结论与建议

核心结论

1. 6000 万美国岗位处于高危状态（评分 7+）
2. 屏幕依赖型职业全线告急——软件开发 9/10、律师 8/10、办公室职员 9/10
3. 蓝领体力工作成为避风港——水管工、清洁工、屋顶工等评分最低
4. AI 暴露不等于完全消失——很多工作将被重塑而非被替代

给职场人的建议

如果你处于高危职业：

1. 发展 AI 难以复制的技能

   • 复杂的人际沟通和情商
   • 跨领域整合和创新思维
   • 物理世界的判断和操作

2. 将 AI 视为工具而非威胁

   • 学习使用 AI 提高工作效率
   • 专注于 AI 不擅长的任务
   • 从执行者转变为策略制定者

3. 考虑职业转型

   • 向管理、策略或创意方向发展
   • 结合技术能力和领域专业知识
   • 发展需要物理存在或复杂人际互动的工作

无论你是哪个行业：

最重要的能力是适应能力和持续学习的能力。

AI 的发展速度远超预期，今天的安全职业明天可能就不再安全。保持学习、保持灵活，才是应对不确定性的最佳策略。

参考资料

1. JoshKale/jobs GitHub 仓库
2. AI 职业暴露可视化
3. 美国劳工统计局职业展望手册
4. Goodhart’s Law - Wikipedia
5. The Mythical Man-Month - Wikipedia

本文数据基于 Gemini Flash AI 模型的评估，仅供参考。AI 技术发展日新月异，实际情况可能与预测有所不同。

上一篇《从一次 tenantId 联调 bug，看我们该怎么给 AI 项目补齐 harness》里，我记录了一个真实项目中的 harness 搭建过程。

那次经历让我意识到：

AI 工程化的竞争力，不是”谁的模型更像天才”，而是”谁先把自己的真实环境整理成一个不会误导 agent 的工作台”。

但「补齐 harness」这件事，说起来容易，做起来却有很多模糊地带——

• Harness 到底包括哪些具体的东西？
• 什么场景下应该优先补哪部分？
• 业界那些号称”零手写代码”的项目，他们的 harness 是怎么设计的？

这篇不聊具体 bug 了，我想从概念、分类、工程实践三个层面，把 Harness 这件事系统地理清楚。

如果你也在搞 AI Coding，正在困惑”除了写 prompt 还应该做什么”，这篇应该能帮到你。

[^1]: Harness engineering: leveraging Codex in an agent-first world - OpenAI, 2026-02-11

什么是 Harness？

Harness = 用来控制、驱动、约束、评估一个系统行为的外部执行框架

换句话说：

• ❌ 不是业务逻辑
• ✅ 是”包在系统外面的一层控制系统”

类比理解

核心本质：让一个”有能力但不可控”的系统变得可控。[^2]

[^2]: Test harness - Wikipedia

传统软件中的 Harness（你其实一直在用）

在 AI 火爆之前，Harness 这个概念已经在软件工程中存在几十年了。你可能每天都在用，只是没意识到。

1. Test Harness（测试框架）——最经典

这是 Harness 一词在软件工程中最常见的用法。

1
2
3
4
5
6
7
8
9

被测系统（SUT） ←→ Test Harness
                ↑
        ┌───────┴───────┐
        │  - 输入构造    │
        │  - Mock/Stub   │
        │  - 执行控制    │
        │  - 输出验证    │
        │  - 日志收集    │
        └───────────────┘

实际例子：

• JUnit / TestNG 测试框架
• 集成测试时启动的嵌入式数据库（H2）
• 模拟外部 API 的 WireMock / MockServer

2. Benchmark Harness（基准测试框架）

Java 开发者最熟悉的 JMH（Java Microbenchmark Harness）就是典型代表。[^3]

[^3]: JMH - OpenJDK

1
2
3
4
5
6
7
8

@BenchmarkMode(Mode.AverageTime)
@OutputTimeUnit(TimeUnit.MILLISECONDS)
public class MyBenchmark {
    @Benchmark
    public void testMethod() {
        // 被测代码
    }
}

Harness 的作用：

• 预热 JVM，消除 JIT 编译影响
• 多轮运行，统计置信区间
• 控制 GC 时机，减少干扰
• 输出标准化的性能报告

3. Integration Harness（集成测试框架）

日常开发中常用的：

1
2
3
4
5
6
7
8
9
10
11
12

# docker-compose.test.yml
version: '3'
services:
  app:
    build: .
    depends_on:
      - postgres
      - redis
  postgres:
    image: postgres:15
  redis:
    image: redis:7

这就是一种 Harness——构造一个可控的系统环境。

其他例子：

• 流量回放工具（GoReplay、TCPReplay）
• 混沌工程工具（Chaos Monkey）
• 负载测试工具（JMeter、k6）

4. 安全 Harness

• 沙箱（Sandbox）：限制程序能访问的资源
• Seccomp：Linux 系统调用过滤
• 浏览器沙箱：Chrome 的多进程架构

这些都是 Harness 的变体：给”有能力但不可控”的系统加上约束。

说明：上文采取的是”广义 harness”用法，用来帮助理解”外层控制框架”这一共同本质；在不同子领域里，具体术语并不完全相同（如 sandbox/seccomp 更常见的分类是 security isolation，test harness 是软件工程的固定用法，而 agentic coding 语境下的 harness 更接近 orchestration + context + tools + validation + feedback loops）。

2025 年底到 2026 年初：长时自主 Agent 的工程实践升温

到 2025 年底到 2026 年初，行业里关于长时自主 agent 的工程实践明显升温，多个团队开始公开分享长时任务、多 agent 协作、可读环境与 harness 设计经验。

从”人类驱动”到”长时自主”

之前的 AI 工具（包括 ChatGPT、Copilot）大多是人类驱动的——你需要不断提示下一步动作。

但 2026 年的新趋势是长时自主智能体（long-running autonomous agents）：

• OpenClaw：通过内存上下文 + 触发器 + Cron 任务，实现持续自主运行
• Cursor：报告了一个”构建浏览器”的长时自主编码实验，官方写法是 over 1 million lines of code；他们同时还展示了其他长期并发 agent 项目
• Anthropic：用并行 Claude agents 构建了一个 Rust 写的 C compiler，重点不是”炫技”，而是总结如何为长时自主 agent team 设计 harness

这些项目的共同点是：AI 不再等待人类指令，而是自主规划和执行长时任务。

新问题出现了

当 AI 可以连续运行数小时甚至数天时，Prompt Engineering 和 Context Engineering 都不够了：

• 如何确保跨会话的上下文连贯？
• 如何让下一个”接手”的 Agent 快速理解当前项目状态？
• 如何验证 Agent 的产出是否正确（而不是让它自己说”完成了”）？
• 如何设计工具和环境，让模型表现最佳？

这就是 Harness Engineering 要解决的问题。

为什么 AI 时代 Harness 突然重要？

因为 LLM = 非确定性系统（Non-deterministic system）

传统软件 vs AI 系统

同一个 Prompt：

• 第一次正确
• 第二次错误
• 第三次又正确

这就是 AI 开发的日常。

从 Prompt Engineering 到 Harness Engineering

阶段一：Prompt Engineering（2023-2024）

关注点是”我怎么写 prompt 更聪明”。

1

给定角色 + 分步骤 + 加示例 → 期望输出

阶段二：Context Engineering（2025）

Andrej Karpathy 在 2025 年的推文中强调：**”context engineering > prompt engineering”**。[^4]

关注点是”模型在推理时能看到什么完整上下文”。

1

RAG + MCP + Memory + 外部工具 → 丰富上下文

[^4]: Andrej Karpathy on X - 2025

阶段三：Harness Engineering（2026-）

当 AI 智能体开始执行长时自主任务（long-running autonomous tasks），Context Engineering 也不够用了。

Harness Engineering 的核心关注点：

1. 跨会话设计 —— 任务可能持续数小时、数天，需要中断和恢复
2. 多智能体协作 —— 不同 Agent 如何接力完成任务
3. 上下文检索 —— 每个新会话如何快速获取相关上下文
4. 工具设计 —— 选择什么样的工具让模型表现最佳
5. 验证机制 —— Agent 会过早声明”完成”，需要独立验证

智能体的常见问题：

• 忽略团队规范
• 生成违反架构依赖方向的代码
• 在并行执行时相互冲突
• 通过”熵增”逐渐降低代码质量
• 过早声明任务完成（而实际上有 bug）

这些问题不是”模型应该看到什么”，而是：

“系统应该阻止什么、测量什么、修复什么、验证什么”

2026 年 2 月，HashiCorp 联合创始人 Mitchell Hashimoto 在博客中明确使用了 “harness engineering” 这一说法，并赋予了它清晰的工程含义：”I don’t know if there is a broad industry-accepted term for this yet, but I’ve grown to calling this ‘harness engineering.’” [^5]

[^5]: Mitchell Hashimoto - My AI Adoption Journey - 2026-02

AI Harness 的核心定义

AI Harness = 用于系统性验证、评估、对比、约束 LLM 行为的工程基础设施

架构组成

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

┌──────────────────────┐
│     Test Dataset     │  ← 测试数据集（Prompt + Context）
│ (Prompt + Context)   │
└─────────┬────────────┘
          ↓
┌──────────────────────┐
│      Harness         │  ← 执行框架
│                      │
│ - 调用模型           │
│ - 控制参数           │
│ - 重试策略           │
│ - 日志记录           │
└─────────┬────────────┘
          ↓
┌──────────────────────┐
│     Evaluator        │  ← 评估器（规则 / LLM评估）
│ (规则 / LLM评估)     │
└─────────┬────────────┘
          ↓
┌──────────────────────┐
│      Metrics         │  ← 指标（准确率 / 稳定性 / 延迟）
│ (accuracy / score)   │
└──────────────────────┘

真实案例：没有 Harness vs 有 Harness

场景：客户对话意图识别

输入：客户说”这个太贵了”
期望输出：{"intent": "价格异议"}

❌ 没有 Harness

• 手动调 Prompt
• 靠感觉判断效果
• 不可复现

👉 玄学开发

✅ 有 Harness

Step 1：构建测试集

1
2
3
4
5
6
7
8
9
10
11
12

[
  {
    "id": "case_001",
    "input": "客户说：这个太贵了",
    "expected": {"intent": "价格异议"}
  },
  {
    "id": "case_002", 
    "input": "能便宜点吗",
    "expected": {"intent": "价格异议"}
  }
]

Step 2：执行 Harness

• 调用 LLM
• 控制 temperature
• 多次运行取平均

Step 3：评估

1
2
3
4
5
6
7
8
9
10
11

# 规则评估
assert actual.intent == expected.intent

# 或用 LLM 评估（LLM-as-a-Judge）
judge_prompt = f"""
评估以下输出是否正确：
输入：{input}
期望：{expected}
实际：{actual}
返回：正确/错误 + 原因
"""

Step 4：输出指标

1
2
3

accuracy = 87%
stability = 方差 < 5%
avg_latency = 450ms

👉 本质：把 AI 从”感觉好不好”变成”指标好不好”[^6]

[^6]: LLM Testing Framework Guide - Leanware, 2025-11-13

OpenAI 的实验数据

OpenAI 在 2025 年 8 月-2026 年 1 月进行了一项实验：[^1]

关键点：初期生产力很低，因为环境、工具、抽象和 repo 内部结构尚未充分为 agent 优化。随着 Harness 逐步完善，性能才大幅提升。

工程师的角色变成了”让智能体有用”——设计系统、架构和约束条件。

Harness 改变结果的惊人案例

案例 1：Hashline（Can Boluk, 2026）

安全研究员 Can Boluk 发布了一个实验，只改变智能体的编辑格式：[^5]

1
2
3
4
5
6
7
8
9

# 传统格式
function hello() {
  return "world";
}

# Hashline 格式（每行加 2-3 字符哈希）
1:a3|function hello() {
2:f1|  return "world";
3:0e|}

智能体可以通过哈希引用行（如”替换 2:f1”），而不需要精确重现字符串。

结果：

• Grok Code Fast 1 的基准测试分数从 6.7% → 68.3%
• 平均输出 token 减少约 20%
• 模型权重没变，只有 Harness 变了

案例 2：LangChain（Terminal Bench 2.0）

固定使用 gpt-5.2-codex 模型，只改进 Harness：[^5]

• 分数从 52.8% → 66.5%（+13.7 分）
• 排行榜排名从约 30 名 → 约 5 名

主要改进是添加了一个自动分析失败模式的工具。

结论：在换模型之前，先检查 Harness。它往往提供最高的 ROI。

AI Harness 的核心组件

基于 OpenAI、Anthropic、Vercel 等公司的实践，一个完整的 AI Harness 应该包含：[^7][^8]

[^7]: How to Evaluate LLMs on Your Own Data - AI Engineer Lab, 2026-03-13
[^8]: LLM Evaluation Framework - Zep AI, 2025-03-01
[^11]: Anthropic - Building a C compiler with a team of parallel Claudes
[^12]: Vercel - We removed 80% of our agent’s tools

0. 可读环境（Legible Environment）—— 长时任务的基础

对于长时运行的智能体，最重要但最容易被忽视的是环境可读性。

当一个新的 Agent 会话”接手”任务时，它需要在几分钟内理解：

• 项目当前状态是什么？
• 已经完成了什么？
• 下一步要做什么？

最佳实践：

关键原则：

每个会话应该能快速”读懂”项目，而不是靠猜测或试错。

Vercel 和 Anthropic 的实践表明：结构化的进度跟踪文件比复杂的记忆系统更有效。[^11]

1. Test Case 管理

1
2
3
4
5
6
7
8
9
10

{
  "id": "case_001",
  "input": "...",
  "expected": {...},
  "metadata": {
    "category": "价格异议",
    "difficulty": "medium",
    "source": "production_log"
  }
}

2. 执行器（Executor）

• 支持多模型（GPT / Claude / DeepSeek / Qwen）
• 支持多 Prompt 版本
• 控制温度、重试策略

3. Evaluator（评估器）

4. Metrics（指标）

• accuracy：意图识别准确率
• faithfulness：事实一致性（防幻觉）
• stability：多次运行方差
• latency：响应延迟
• cost：单次调用成本
• format_reliability：结构化输出成功率

5. E2E 验证（端到端测试）—— 防止”假完成”

关键洞察：Agent 有强烈的倾向过早声明任务”完成”。这一观察来自多个团队的自主 agent 实验总结。

单元测试不够，因为 Agent 可能：

• 代码通过了测试，但功能不工作
• 实现了功能，但引入了回归 bug
• 完成了任务，但破坏了其他模块

解决方案：提供端到端验证工具

反馈循环：

1

Agent 声明完成 → E2E 测试 → 失败 → 反馈给 Agent → 修复 → 重新验证

这比人工检查快得多，也更可靠。

6. 工具设计：通用优于专用

Vercel 的实践经验：[^12]

• 原来：大量 specialized tools
• 改进后：删掉大部分工具，只保留非常少的基础工具，核心是一个 execute arbitrary bash commands 的 file system agent，再加 ExecuteSQL

结果（在 5 个代表性查询上）：

• 成功率：从 80% → 100%
• 速度：从 274.8s → 77.4s，快 3.5 倍

原因：

• 模型对通用原生工具（如 bash）的理解更深刻
• 减少工具选择的开销
• 批处理减少往返次数

设计原则：

让模型直接面对 legible file system + 少量通用工具，而不是复杂的专用工具链。

7. CI/CD 集成

1
2
3

git push →
自动跑 harness →
指标下降 → 阻断发布

[^9]: DeepEval - LLM Evaluation Framework

可用的 Harness 工具生态

开源框架

商业平台

工程落地建议

起步三要素

1. 写上下文文件

   创建 CLAUDE.md 或 AGENTS.md，包含：

   • 项目结构
   • 构建命令
   • 编码规范

   每次智能体犯错，就添加一条防止再犯的规则。[^5]

2. 选择性地连接 MCP

   如果智能体经常引用某个外部系统，就通过 MCP 连接它。典型例子包括 Issue Tracker、Wiki、监控系统。

   但只连接必要的，否则 token 会被浪费。

3. 从简单评估开始

   • 收集 50 个真实生产 Prompt
   • 在 3-5 个模型上运行
   • 人工评分，对比差异
   • 逐步自动化

常见陷阱

核心总结

Harness 的本质：让不可控系统变成可度量、可优化、可上线的工程系统

AI 开发的核心资产正在转移：

如果用传统软件工程类比，Harness Engineering 有点像 JUnit、CI/CD、测试基建、脚手架、约束机制和运行环境设计的组合体——它覆盖的不只是”评测和 CI”，还包括 agent legibility、repo as system of record、AGENTS.md、自动化反馈循环、工具约束、任务接力、E2E verification、并行协作结构。

你写的 Prompt、RAG 流程、Agent 逻辑——这些都需要被评估、被约束、被持续监控。

参考资源

官方/论文

• OpenAI Harness Engineering - OpenAI 官方文章
• OpenAI Evals - 官方评估框架
• HELM - Stanford - 全面的 LLM 评估基准
• Test Harness - Wikipedia

工程实践

• Promptfoo - 开源 Prompt 测试框架
• DeepEval - Python LLM 评估框架
• LangChain Evaluation - LangChain 评估指南

深度解读

• Beyond Prompts and Context: Harness Engineering - 概念演进时间线
• OpenAI Harness Engineering - InfoQ - 中文技术解读
• LLM Testing Framework Guide - 测试框架最佳实践
• How to Evaluate LLMs - 实用评估方法

官方工程博客

• OpenAI - Harness engineering - OpenAI 官方 Harness Engineering 文章
• Anthropic - Building a C compiler with parallel Claudes - Anthropic 并行 agent 实验
• Cursor - Scaling long-running autonomous coding - Cursor 长时自主编码实验
• Vercel - We removed 80% of our agent’s tools - Vercel 工具设计经验
• Mitchell Hashimoto - My AI Adoption Journey - Harness Engineering 概念提出

视频

• Andrej Karpathy - Software 2.0 - 关于 AI 软件范式的经典演讲

最后

我们正处在一个转折点。

Prompt Engineering 只是开始，Context Engineering 是中间阶段，而 Harness Engineering 是 AI 应用走向生产就绪的必经之路。

如果你正在开发 AI 应用，不妨从今天开始：

1. 收集 50 个真实的测试用例
2. 建立一个简单的评估脚本
3. 在每次 Prompt 变更时跑一遍

这就是 Harness 的起点。

前几天在 X 上看到一篇关于 Claude Code Skills 的深度分享，作者是 Anthropic 的 Thariq。文章总结了他们团队内部数百个 Skills 的实战经验，信息量很大，读完收获颇多。

原文链接：https://x.com/trq212/status/2033949937936085378

今天整理一下核心观点，顺便加上自己的一些思考。

一个常见误解

很多人以为 Skills “就是个 Markdown 文件”，放几句提示词而已。

实际上，Skills 是一个完整的文件夹，可以包含脚本、数据、模板等资源。Claude Code 会在合适的时候读取这些内容，就像给一个专家配备了全套工具箱。

这个区别很重要——它决定了你是做一个”简单的提示词模板”，还是做一个”真正能解决问题的智能助手”。

Skills 的九种类型

Thariq 把 Anthropic 内部的 Skills 分了九大类。这个分类很有参考价值，可以对照看看自己的技能库缺了哪一类：

1. 库与 API 参考

解释如何正确使用某个库、CLI 或 SDK。重点是记录边缘案例和常见陷阱，而不是重复文档。

例子：

• 内部计费库的 edge cases
• 出口网关的配置和调试方法
• 某个 SDK 的版本差异

2. 产品验证

描述如何测试代码是否正常工作，常搭配外部工具。

例子：

• 用 Playwright 跑完整注册流程
• 用 Stripe 测试卡验证结账流程
• 需要 TTY 的交互式 CLI 测试

这类 Skills 特别值得投入时间打磨，因为能保证 AI 输出的正确性。

3. 数据获取与分析

连接数据系统和监控平台，包含查询规范、仪表板 ID、常见工作流。

例子：

• 用户留存率查询
• Grafana/Datadog 数据源配置
• 转化率对比分析

4. 业务流程与团队自动化

把重复工作流压缩为一条命令。

例子：

• 聚合 Ticket、GitHub、Slack 生成站会报告
• 自动格式化周报
• 标准化 Ticket 创建流程

5. 代码脚手架与模板

为特定功能生成框架代码。

例子：

• 新建内部应用（预配置认证、日志、部署）
• 迁移文件模板 + 常见陷阱
• 新建服务/工作流的标准结构

6. 代码质量与评审

强制代码质量，帮助代码评审。

例子：

• 生成”新鲜视角”子 Agent 进行批判性评审
• 强制特定代码风格
• 测试编写指南

7. CI/CD 与部署

帮助获取、推送、部署代码。

例子：

• 监控 PR → 重试 flaky CI → 解决冲突 → 自动合并
• 渐进式部署 + 错误率监控 → 自动回滚
• Cherry-pick 到生产环境的标准流程

8. 运行手册 (Runbooks)

输入症状，输出结构化诊断报告。

例子：

• 某服务的调试手册（症状 → 工具 → 查询映射）
• On-call 告警自动排查
• 根据 request ID 关联所有相关日志

9. 基础设施运维

执行日常维护与操作（含破坏性操作，需要防护栏）。

例子：

• 发现孤儿资源 → 通知 → 浸泡期 → 用户确认 → 清理
• 依赖审批工作流
• 成本异常调查

制作 Skills 的实用技巧

1. 不要陈述显而易见的内容

Claude 已经知道很多东西。Skills 应该聚焦在”让 Claude 跳出常规思维”的信息上。

例子：前端设计 Skill 通过与用户迭代，避免 Inter 字体和紫色渐变等”AI 味”设计。

2. 建立 Gotchas 专区（最有价值的内容）

记录 Claude 使用这个 Skill 时常见的失败点，持续更新。

真实例子：

• “subscriptions 表是 append-only，取最高 version 而非最新 created_at”
• “API gateway 用 @request_id，billing service 用 trace_id，但值相同”
• “Staging 返回 200 但 Stripe webhook 未处理，需查 payment_events”

3. 利用文件系统做渐进式披露

Skill 是文件夹，可以把详细内容拆分到不同文件：

• references/api.md - 详细 API 签名
• assets/ - 模板文件供复制
• scripts/ - 现成脚本

让 Claude 知道文件夹内容，它会在需要时读取。

4. 避免过度约束

Skill 要可复用，指令不要过于死板。提供必要信息，保留适应性。

5. 提前考虑配置

部分 Skill 需要用户上下文（如 Slack 频道）。建议用 config.json 存储配置，未配置时让 Agent 询问用户。

6. 内存与数据存储

Skill 内可以实现”内存”：追加日志、JSON 或 SQLite。建议存入稳定路径（如 ~/.claude），避免 Skill 升级时丢失数据。

例子：standup-post 保留 standups.log，下次运行时自动对比昨日变化。

7. 存储脚本 + 生成代码

给 Claude 现成脚本/库，让它专注组合而非重写样板。

8. 按需 Hooks

仅在调用 Skill 时激活的临时 Hooks。

例子：

• /careful：仅在生产环境阻挡危险命令
• /freeze：锁定仅允许特定目录的编辑

分发与管理

小规模：检入仓库

直接放在 ./.claude/skills，适合小团队。

大规模：制作 Plugin

通过 Claude Code Plugin 市场分发，避免每个 Skill 都增加上下文负担。

管理市场的经验

• 无中心化审核团队
• 开发者先上传到 sandbox 文件夹，在内部渠道推广
• 获得 traction 后提 PR 进入市场

组合 Skills

直接通过名称引用其他 Skills，模型会自动调用（前提是已安装）。

衡量使用情况

使用 PreToolUse Hook 记录 Skill 使用日志，可以发现哪些是热门 Skill，哪些没人用。

我的几点思考

1. Skills 的本质是”可复用的上下文”

以前用 Claude，每次都要在对话里交代一堆背景信息。Skills 把这些背景”固化”下来，变成可复用的资产。

这和编程里的”抽象”是一个道理——把通用的东西抽出来，下次直接用。

2. Gotchas 比 Reference 更有价值

文档能告诉 Claude “API 怎么用”，但只有实战经验能告诉它 “这里容易踩坑”。

这也是人类工程师的价值所在——不是记得住多少文档，而是知道哪些地方容易出问题。

3. 从”用完即走”到”持续积累”

Thariq 提到他们大多数 Skills 最初只是几行文字 + 一个 gotcha，后来因 Claude 不断碰到新边缘案例而持续完善。

这和我们写代码一样——先跑起来，再迭代优化。不要想着一次做到完美。

4. 对国内用户的现实考量

Claude Code 在国内的使用还有一些门槛（网络、账号、价格）。但这些方法论是通用的：

• 如果你用 Cursor/Windsurf，可以借鉴这个分类思路整理 .cursorrules
• 如果你用其他 AI 工具，也可以建立自己的”提示词库”

核心是：有意识地积累和复用上下文，而不是每次都从零开始。

结语

Skills 还处于早期阶段，大家都在摸索最佳用法。这篇分享更像是一个”有用技巧合集”，而非权威指南。

最好的学习方式就是动手实验，不断迭代。

如果你已经在用 Claude Code，不妨从整理一个最常用的工作流开始，把它做成 Skill。你会发现，AI 助手越用越顺手。

参考链接：

• 原文推文 - @trq212
• Skilljar 课程 - 《Agent Skills》入门课程
• Claude Code 文档

最近输出有点频繁，主要是这几天项目没那么满，再加上龙虾每天都在逼我成长，老跟我聊各种话题。

今天刚好聊到一个很典型的管理问题：老板觉得工期慢，或者会追着问一句“这个时间还能不能再快点？”后来回头看，这事儿还真不是一个维度能说清的。

这事我是真踩过坑。

前阵子带团队做项目，老板很着急，想尽快把产品推出来。这个诉求本身没毛病，谁做项目不想快一点呢。

问题是，每次汇报进度，他都觉得还是慢，或者会继续追问一句：

“这个时间有没有办法再压一压？”

这句话听起来很普通，但真落到团队身上，杀伤力其实不小。

因为它后面往往会带出一连串动作：要不要加人，要不要并行，要不要砍流程，要不要先糙一点上线。

我后来回头看，问题根本不是一句“人不够”能解释的，甚至很多时候，核心矛盾都不是“要不要加人”。

真正的问题是：老板觉得慢，到底是真的慢，还是大家看问题的角度不一样？

如果硬套芒格那句老话，就是：别一上来就拿一个动作当答案。

单一思维最容易把人带沟里

工程师和老板在这件事上，其实都很容易掉进同一个坑：

• 进度慢
• 开始着急
• 立刻想办法压工期
• 先上动作，再看问题

逻辑听起来很顺，但现实里经常不成立。

因为软件研发不是搬砖。你以为自己在压时间，实际可能只是把复杂度、返工和沟通成本往后推。

所以这类问题，如果只用一个视角看，很容易越搞越乱。你得换几个角度一起看，才比较接近真相。

下面这几个角度，是我后来觉得最有用的。

五个视角，拆开看这件事

1. 心理学：损失厌恶——团队不一定是不会干，可能是不敢快

很多团队进度慢，不是因为能力差，而是因为大家怕出错。

一旦环境里“延期要挨骂”“出问题要背锅”这种信号太强，团队就会本能地保守。估时往大了估，执行往后拖，很多人宁愿慢一点，也不想冒风险。

这时候表面上看像是效率低，实际上是恐惧驱动出来的低效。

这种场景下，你跟老板如果只说“时间不够”，他通常听不进去。更有用的话术反而是：

“我观察下来，团队最近估时都比较保守，执行也容易拖到后面。不是大家不想快，更像是怕出问题。要不要先看看是不是当前沟通方式让大家太怕犯错了？”

这个说法的关键，不是替团队喊冤，而是把“慢”从能力问题，拉回到环境问题。

2. 经济学：边际效用递减——你想压工期，先算算代价

很多人一听“能不能更快”，第一反应就是加动作。

比如：

• 多上几个人
• 并行做更多事
• 少做一些校验
• 先把过程压扁

但经济学里有个很朴素的点，叫代价。

任何“更快”都不是白来的，你这边省下来的时间，往往会在另一边以返工、沟通、质量风险的形式补回来。

其中最典型的，就是中途加人。团队从 3 个人变成 5 个人，看上去只多了 2 个人，但沟通路径会从 3 条变成 10 条。再加上新人熟悉业务和上下文，短期内未必真能把工期压下来。

所以这时候你跟老板沟通，不要只说“压不了”，而是把代价说清楚：

“如果要继续压时间，不是不行，但代价得一起看。比如中途补人，短期内协作成本会明显上升；如果砍流程，后面返工和质量风险也会跟着上来。”

这类话比“我们已经很努力了”更有效，因为它是在聊投入产出。

3. 系统论：瓶颈理论——老板看到的是工期，项目卡住的可能是别的地方

这是我后面越来越信的一件事。

很多项目看起来卡在开发，实际上真正堵住节奏的，压根不是开发。

常见的瓶颈可能是：

• 需求反复改
• 产品决策慢
• 测试环境不稳定
• 关键人拍板不及时
• 上下游依赖一直等

如果真正卡住项目的是这些地方，那你就算拼命压开发时间，也不一定有用。

就像高速收费站堵了，你在后面再多放几辆车，意义并不大。

我后来比较常用的做法，是先把时间花在哪儿拆出来。比如开发占多少、等确认占多少、返工占多少、等环境占多少。只要这个账一拉，很多争论就会自动消失。

因为当你能明确说出：

“开发只占整个周期的 30%，等决策和返工占了大头。”

那老板自然就会明白，问题不在“开发还不够快”。

4. 概率论：规划谬误——不是大家故意乐观，是人天生就会低估难度

项目管理里有个很烦但很真实的事：大家总会低估复杂度。

估计划的时候，脑子里默认都是理想状态：

• 需求差不多稳定
• 没有特别难的坑
• 联调不会出问题
• 关键人能及时回复

但真实项目哪有这么顺。

所以很多“老板觉得慢”的背后，其实不是团队真慢，而是最开始那个预期本来就立得太乐观。

这时候最有用的不是争辩，而是把历史数据翻出来。

比如你可以这么聊：

“同规模的需求我们过去做过 4 次，平均耗时是 3.5 周，最短也接近 3 周。现在按 2 周来压，风险会很高。”

一旦把“我感觉”换成“历史上就是这样”，沟通就会轻松很多。

老板不一定认同你，但他很难无视数据。

5. 决策理论：选项设计——别只回一句”压不了”，给他选项

这是我自己吃过亏之后改得最明显的一点。

以前老板一问“还能不能更快”，我第一反应就是解释为什么快不了。后来发现这种沟通方式很被动，因为你只有一个姿态：否定。

否定久了，对方很容易觉得你是在挡事。

更好的办法，是别只给结论，给方案。

比如直接摆三个选项：

方案 A：继续压工期，比如补人或者并行赶工，短期看上去积极，但协作成本和质量风险都会上来。

方案 B：先切核心功能上线，剩余部分下一轮补，整体节奏更稳。

方案 C：不继续压时间，接受延期一周，把质量保住。

这时候你不是在和老板对抗，而是在帮他做决策。

很多管理沟通，关键不在于“你说得对不对”，而在于“你有没有把选择面铺开”。

我后来是怎么处理这类问题的

后面再碰到类似场景，我基本会先做三件事。

1. 先找真实瓶颈

别急着下结论，先看时间到底耗在哪儿。

开发慢，只是结果。真正的原因，可能是确认慢、返工多、依赖卡住，甚至是汇报链路太长。

2. 汇报时别只报进度，要报权衡

我后来比较喜欢把方案讲成“快、稳、折中”三个版本。

• 快：能更早上线，但要接受技术债和返工风险
• 稳：周期更长，但质量更可控
• 折中：先上核心，剩下分批补

这样老板听到的就不只是“你们做不完”，而是“不同选择分别意味着什么”。

3. 核心团队尽量小

很多事情不是人越多越好，尤其是前期探索阶段。

团队小一点，沟通短一点，边界清一点，节奏通常反而更快。真要补人，也尽量补在外围，不要一股脑全塞进核心链路里。

一个很实用的自检框架

下次老板再说“这个时间还能不能再快点”，你可以先在脑子里过一遍这五个问题：

有时候你把这五个问题想清楚，答案基本就出来了。

写在最后

我现在越来越觉得，管理里很多“看起来很简单”的问题，其实都不能只拿一个招去解。

老板觉得慢，未必是真的慢。

他说“能不能再快点”，很多时候也不是在指挥具体动作，而是在表达压力、目标和预期。

而我们如果只会回一句“快不了”，那本质上也没有把问题讲清楚。

多元思维模型对我最大的价值，不是让我显得懂很多学科，而是提醒我：

先把问题看准，再决定用什么办法。

不然的话，压工期、加人、砍流程，最后都可能只是看起来很努力。

你最近如果也碰到类似的问题，不妨别急着给动作，先换两个角度看看。

很多时候，真正该先补的不是人，而是对问题的判断。

参考资料

• 《穷查理宝典》（Poor Charlie’s Almanack） - 彼得·考夫曼（Peter D. Kaufman）编，2005 年
• 查理·芒格 1994 年南加州大学商学院演讲 - 《论基本普世智慧及其与投资与商业的关系》
• 《人月神话》（The Mythical Man-Month） - 弗雷德里克·布鲁克斯（Frederick P. Brooks Jr.）著，1975 年
• 《目标》（The Goal） - 埃利亚胡·高德拉特（Eliyahu M. Goldratt）著，1984 年
• 丹尼尔·卡尼曼（Daniel Kahneman） - 损失厌恶（Loss Aversion） 理论

前几天我读了 OpenAI 那篇文章：Harness engineering: leveraging Codex in an agent-first world。

我读完最大的感受不是“AI 又强了”，而是另一个更接地气的结论：

很多时候，不是模型不够强，而是你的工程环境没有把“正确性”暴露给模型。

这两天我正好在自己项目里处理一个非常典型的问题：运营端新增门店和校验门店名时，如果和其它租户重名会误报；员工后台接口也有类似的租户范围问题。表面上看只是个 tenantId bug，但整个过程把一个事实暴露得很彻底：

AI 想高效干活，前提不是 prompt 更长，而是 harness 更清楚。

一、这次 bug 表面是租户问题，实质是“环境表达不清”

最初的现象其实很迷惑：

1. 运营端调用 admin/store/checkName
2. 明明传了 tenantId
3. 但接口判重却像是按别的租户在查

如果只看 Controller 参数，你会以为“不是都传进来了吗”。
但真正往下追，就会发现系统里其实混着两套租户来源：

• 请求里显式传入的 tenantId
• 线程上下文里的 TenantContextHolder

理论上，TenantContextHolder 也不是错的。因为网关或 filter 确实会从 header 里解析租户并写入上下文。问题在于：

后台管理接口的业务语义，不是‘当前会话属于哪个租户’，而是‘当前运营账号要操作哪个目标租户的数据’。

这两个概念，在多租户后台系统里根本不是一回事。

所以这次真正的问题不是一句“代码写错了”，而是：
系统没有把“哪一个租户才是业务真相”表达得足够显式。

这就是 harness 问题。

二、OpenAI 那篇文章对我最有启发的，不是模型能力，而是“把环境当产品做”

那篇文章里有几层意思我特别认同，我这里不逐字复述，只说我自己的理解。

1）Agent 的上限，很大程度取决于它能不能直接看到真实运行环境

如果模型只能读代码，看不到：

• 实际 HTTP 请求长什么样
• token 从哪里来
• 当前服务到底连的是哪套数据库
• 逻辑删除字段的业务语义是什么

那它就很容易陷入一种“静态推理正确，动态结论错误”的状态。

这次我们项目里就连续遇到了：

• 代码已经改了，但运行中的服务没重启
• checkName 返回 true/false 的语义，调用方理解反了
• 数据库里能查到门店记录，但那条记录其实已经逻辑删除

这些都不是大算法问题，而是工程上下文没有被收束成一个可验证的工作台。

2）入口文档不该是经验大杂烩，而应该是导航页

以前很多项目的 AGENTS.md、模块说明文档，最后都会越写越长。
每次踩坑补一条，最后谁都不想看，AI 也很难稳定执行。

所以我这次顺手把项目里的规则做了一个调整：

• AGENTS.md 和 CLAUDE.md 保留高层原则
• 具体的联调、token、租户、契约规则下沉到 docs/testing/

这不是为了“文档好看”，而是为了让规则能被持续修正，而不是散落在三个地方互相漂移。

3）真正有价值的，不是“写了规则”，而是“规则能被验证”

如果规则只是：

• 显式传 tenantId
• 统一走网关
• 做真实 HTTP 测试

那它还是有点抽象。

真正有效的规则必须长成下面这样：

• 运营端接口测试时，直接向用户索取运营端 token
• 同一个 token，对照请求 tenantId=A/B
• 至少保留一条原始 HTTP 响应
• 必要时补查数据库解释“为什么接口返回这样”

一旦规则写到这个粒度，AI 和人都更难自欺欺人。

三、这次我把项目规则怎么改了

结合这次联调前后对比，我最后把项目里的规则改成了三层。

第一层：入口文档只讲方向，不再堆细则

我在项目根目录 AGENTS.md 和 goodsop-app-server/CLAUDE.md 里增加了一个明确入口：

• docs/testing/README.md
• docs/testing/admin-http-harness.md
• docs/testing/tenant-data-scope.md

意思很简单：
入口文档只负责告诉 AI“去哪儿看”，真正经常变化的实战规则集中维护。

第二层：把运营端 HTTP harness 写成可执行规则

这次新增的 admin-http-harness.md 里，我重点固化了几件事：

1. 所有运营端联调统一走 http://localhost:9999
2. 测试运营端接口时，必须直接问用户要 token
3. 同一轮验证里，优先用同一个 token 只切换 query tenantId
4. 每次改动至少保留 1 个真实业务接口的原始响应
5. 失败排查顺序固定为：连通性 -> 网关 -> Nacos -> 鉴权上下文 -> 业务代码/SQL

这几条看起来朴素，但非常关键。因为 agent 一旦没有这些硬边界，就会在“如何拿 token”“是不是该直连服务”“这个请求到底算不算验证”上浪费很多轮次。

第三层：把租户数据范围语义写明白

tenant-data-scope.md 里，我把这次最核心的结论直接写死了：

1. 后台管理接口的数据范围以显式传入的目标 tenantId 为准
2. TenantContextHolder 是上下文机制，不是后台业务真相
3. checkName/checkPhone 必须同时校验接口契约和逻辑删除语义

尤其是第三点，这次特别有代表性。

我们一开始看到有些门店名“库里明明有记录，接口却返回可用”，很容易怀疑代码没改对。
后来一查数据库才发现：那几条是逻辑删除记录。也就是说，数据库里有行，不等于业务上仍占用名称。

这个结论如果不被写进规则里，下次还会重复争论。

四、这次代码层面的前后对比，也很说明问题

如果只看代码，这次改动其实不算复杂，核心就是两件事。

改动前

• Controller 收到了 tenantId
• 但部分 service 逻辑还是依赖 TenantContextHolder
• checkName 的返回在失败时没有稳定给出 data=false
• 联调时容易把“请求头租户”“目标业务租户”“逻辑删除记录”混在一起

改动后

• admin/store/*、admin/consultant/* 显式把 tenantId 往下传
• 需要上下文的地方用 TenantBroker.applyAs(tenantId, ...)
• checkName 改成：
  • 可用：data=true
  • 不可用：data=false
• 真实接口回归不只看代码，还做了：
  • tenantId=5584 与 tenantId=1 对照请求
  • 门店新增、关店、员工新增、修改、离职
  • 必要时补查 PG 解释结果

这里最关键的，不是“把某个 if 改对了”，而是从“我觉得这样应该对”变成了“我能证明它对，而且能解释为什么”。

这就是 harness 的价值。

五、对我们这种业务项目来说，AI 真正缺的不是智商，而是工作台

很多人谈 AI Coding，喜欢把重点放在模型选择、prompt 技巧、上下文窗口大小。

这些当然重要，但我现在越来越觉得，对真实业务项目来说，下面这些东西更值钱：

1）可直接使用的环境入口

• 正确的网关地址
• 正确的 token 获取方式
• 正确的数据库连接信息
• 正确的日志和服务发现排查路径

2）可复用的验证脚本或验证模板

不是“你自己去测一下”，而是给出：

• 请求地址
• header
• body
• 对照 tenantId
• 预期差异

3）不会漂移的规则系统

很多团队的问题不是没有规则，而是规则散在聊天记录、群公告、项目文档、某个人脑子里。

一旦 AI 进场，这种问题会被放大得更厉害。
因为 AI 特别依赖“哪个文档才是 system of record”。

六、我准备继续往前做的，不只是写博客

这次规则改完以后，我更想补的是一套更完整的 harness，而不只是几段说明文档。

如果继续做，我下一步大概率会补这些东西：

1. scripts/verify-admin-store.sh
   • 自动完成 page/checkName/create/close
2. scripts/verify-admin-consultant.sh
   • 自动完成 page/checkPhone/create/update/resign
3. 运行态环境说明
   • 当前服务实际连接哪套 PG/Redis
4. 接口契约回归样例
   • 尤其是 data/code/msg 这种容易被误解的接口

因为写到最后我越来越确信一件事：

AI 工程化的竞争力，不是“谁的模型更像天才”，而是“谁先把自己的真实环境整理成一个不会误导 agent 的工作台”。

结语

OpenAI 那篇文章给我的最大提醒，是别把 agent 当成一个只会补代码的聊天机器人。

它更像一个能力很强、速度很快，但极度依赖环境质量的工程协作者。

如果你的环境是模糊的：

• 文档入口混乱
• token 获取方式混乱
• 租户语义混乱
• 接口契约混乱

那 AI 就会在这些噪音里反复打转。

但如果你把 harness 补起来，很多原来需要人肉盯着的事情，就会突然顺很多。

所以这次一个看似普通的 tenantId bug，最后给我的启发反而比 bug 本身更大：

以后优化 AI Coding，不只是继续追模型，也要继续做环境。