比较常见的状态是知识走一条 RAG 管道，用户记忆走一个独立的 memory 服务，工具使用经验干脆没有沉淀机制，靠 system prompt 里手写的几条注意事项撑着。跑长周期任务时问题集中爆发：第三十轮时 Agent 忘了第五轮的约束；召回了一段错误文档，事后想归因，向量库只给一个相似度 0.83，别的什么都没有。

这两个 case 背后是同一个架构缺陷：上下文没有被当作一个独立子系统来设计，它只是若干条数据管道的松散集合。

最近把火山引擎开源的 OpenViking 看了一遍，它把自己定位成「面向 AI 智能体的上下文数据库」，GitHub 上 27.2k star。这个定位本身就是一个架构主张：上下文应该是 Agent 架构里一个有统一接口、有存储模型、有检索语义、可观测的独立组件，地位类比业务系统里的数据库。

沿着这个主张往下拆，它有几个设计决策对做 Agent 架构的人有一些参考价值。

统一存储模型

Agent 架构里第一个要回答的问题：记忆、知识、技能这三类上下文，存储模型是分开还是统一。

分开是多数团队的现状，也是我们踩过的坑——三套 schema、三套检索接口、三套更新逻辑，Agent 侧要维护三种访问心智。OpenViking 的选择是统一：全部抽象成文件，挂在 viking:// 协议下的虚拟文件系统里，每个条目一个唯一 URI。它给出的目录结构：

viking://
├── resources/              # 资源：项目文档、代码库、网页等
│   └── my_project/
│       ├── docs/
│       │   ├── api/
│       │   └── tutorials/
│       └── src/
└── user/
    └── {user_id}/
        ├── memories/
        │   └── preferences/
        │       ├── writing_style
        │       └── coding_habits
        ├── resources/
        │   └── private_project/
        ├── skills/
        │   ├── search_code
        │   └── analyze_data
        └── peers/
            └── web-visitor-alice/

Agent 用 ls、tree、find 浏览自己的上下文。

从架构角度来看，这个统一带来两个收益。第一，定位从概率性变成确定性。扁平向量库里想精确更新某个用户的编码习惯记忆，只能靠 metadata filter 打补丁；文件系统里就是一个路径寻址，viking://user/{user_id}/memories/preferences/coding_habits，增删改查全部确定。多租户隔离也顺带解决了——user/{user_id} 这层目录天然就是隔离边界，商业版文档里明确把多租户共享和隔离列为核心场景。

第二，Agent 与上下文之间的接口收敛成了一套文件操作原语。这一点对架构的影响比看起来大。我们之前自研记忆系统时设计过一套 memory.query(scope, filter, ...) 风格的 API，模型调用的出错率明显高于让它直接操作路径。文件系统是 LLM 预训练语料里高频出现的心智模型，ls 和 tree 的语义模型天然理解，不需要在 prompt 里教。接口设计顺着模型先验走，省下的是持续的 prompt 工程成本。

代价在写入侧的分类决策。内容归置到哪个路径，做错了后续检索会系统性偏航，扁平向量库至少没有「放错文件夹」这种失败模式。OpenViking 靠写入时的自动语义处理来做归置，这个环节的质量上限决定了整棵文件树的可用性，我认为是它工程上最脆弱的一环。

预算分层供给

第二个架构问题：上下文以什么粒度供给给模型。

传统 RAG 的答案是 chunk 全量——检索 top-k 塞进 prompt，k 靠拍脑袋。这在架构上等于把上下文预算的管理责任丢给了一个魔法数字。OpenViking 的方案是写入时预计算三层表示：

• L0（摘要）：约 100 tokens，一句话总结，快速判断相关性
• L1（概览）：约 2k tokens，核心信息和使用场景，供规划阶段决策
• L2（详情）：完整原始数据，确有必要时才读

每个目录也带自己的 .abstract 和 .overview，Agent 读任何完整文件之前，先花 100 个 token 判断这个方向值不值得深入。

放到 Agent 的执行循环里看，这三层恰好对应了三个阶段的信息需求：候选筛选阶段用 L0 扫一遍，规划阶段对少数目标加载 L1，执行阶段只对必要条目读 L2。上下文供给从一次性的赌博变成了跟随 Agent 决策流程的渐进加载，粒度和阶段对齐了。

数据上，OpenViking 0.3.22 在 LoCoMo 长对话记忆评测里，三种 Agent 集成的准确率到 80–83%，原生记忆只有 24–57%；输入 token 减少 34.3%–91.0%，查询时延降低 58.45%–66.10%。token 降幅区间这么宽，说明收益高度依赖任务形态：判断型任务能省九成，需要全量细节的任务省不了多少。评测脚本在仓库 ./benchmark 目录，可自行复现。

架构上的 trade-off 转移到了写入路径。L0/L1 由模型生成，每次数据摄入都有一笔推理开销，且是异步的——README 明确提示 add-resource 不加 --wait 时语义处理需要等待。写入吞吐敏感或数据高频变更的场景，这条路径会成为瓶颈。更隐蔽的风险是摘要写歪：L0 错了，后续所有基于它的相关性判断连带出错，等于在检索链路最上游埋单点。官方提供 ov reindex <uri> --mode semantic_and_vectors 重新生成语义产物再刷新向量，说明他们自己也预期摘要需要返工。

即便不引入 OpenViking，「写入时预计算多粒度表示、按 Agent 决策阶段供给」这个模式可以直接抄进自建架构。

检索即导航

检索组件在 Agent 架构里通常被实现成一个无状态函数：query 进，top-k 出。OpenViking 把它改成了一个有过程的导航。

先通过意图分析生成多个检索条件；向量检索定位初始切片所在的高分目录；在该目录下二次检索，高分结果更新进候选集；有子目录就逐层递归；最终返回最相关的上下文，连同周边语境一起。

一句话概括：先锁定高分目录，再向下精细探索。

这解决的是扁平 top-k 在 Agent 场景下的一个结构性缺陷——碎片没有语境。命中一个 chunk，Agent 不知道它前后是什么、属于哪份文档的哪个章节，拿到的是信息孤岛。导航式检索的返回结果自带位置和邻居：这段内容出自 API 文档的鉴权章节，同目录下还有 endpoints 说明。对代码库问答这类强依赖结构的任务，这个差异是决定性的。

代价：多轮向量查询加上可能的多次判断，单次检索的绝对延迟一定高于一把梭的 ANN。前面提到的时延降低 58%–66%，我的理解是端到端口径——省下的 token 让生成阶段变快，摊平了检索阶段的开销。架构选型时要按流量形态判断：Agent 任务型场景，单次任务价值高、容忍秒级检索，划算；高 QPS 低延迟的在线检索，这套递归策略不合适。

全链路留痕

Agent 架构的可观测性讨论，通常止步于工具调用日志。OpenViking 把留痕做进了检索内部：每次查询都保留完整的目录浏览轨迹，结果不对时能看到它出自哪条路径。

做过 RAG 生产运维的人知道 bad case 归因有多难。用户投诉答案错了，排查下来只能看到「这几个 chunk 相似度最高所以被召回」，正确内容为什么没进 top-k，向量空间不会解释。最后退化成调 embedding、调 chunk 大小、调 k 值的炼丹循环。

轨迹留存把归因变成可逐步 debug 的过程：检索在哪个目录拐错了弯、哪一层的 L0 摘要误导了判断，路径上每一步可查。修复动作随之有了着力点——重写某个目录的 abstract，或者调整文件归置，都对应到具体操作。配套的 OpenViking Helper 桌面端（Beta，支持 macOS 和 Windows x64）能解析 Claude Code、Codex、Trae 的会话，展示召回、Prompt 注入、MCP 调用、捕获和提交事件，Agent 与上下文系统之间的全部交互摆在明面上。

这一条我建议所有做 Agent 基础设施的团队照抄，无论用不用 OpenViking：把「检索决策可回放」写进架构的非功能需求。存储和埋点的成本，第一次生产事故排查时就能收回来。

经验回写闭环

多数 Agent 架构是开环的：任务执行完，除了对话历史什么都不留，下次遇到同类任务从零开始。OpenViking 在架构里补了一条回写路径：会话通过 session.commit() 显式提交后，系统异步提取两类内容写入长期记忆——用户偏好，和 Agent 经验，落到对应的 /memory 目录下。

用户偏好各家都在做。Agent 经验这条更值得看：从任务执行结果里提取操作技巧、工具使用经验，供后续同类任务复用。tau2-bench 的数据：经验记忆让任务成功率在 Retail 提升 6.87 个百分点，Airline 提升 11.87 个百分点，对比同一 LLM 无记忆基线。模型没动，纯靠架构里加一条经验沉淀回路，拿到两位数以内的成功率增量。

对比另一条提升路线——攒数据做 SFT 或 RL 微调，周期以周计，成本以万计。经验记忆改的是上下文而非权重，迭代周期是每次会话。两条路线不互斥，但在架构演进的排序上，外置经验回路的边际成本低得多，应该排在微调前面。

两处要留神。一是提取质量：异步抽取本身是 LLM 调用，抽错等于往长期记忆注入脏数据，且脏记忆会在后续任务里持续生效，危害大于一次性的错误回答。二是显式 commit 这个设计——记忆更新由开发者主动触发而非全自动，「哪些会话值得沉淀」的裁量权留在应用层。我们内部一度想做全自动沉淀，现在倾向于保留这个开关，至少在提取质量有验证机制之前。

接入成本

把这套东西放进现有 Agent 架构的成本，不高。

Python 3.10 以上，pip install openviking --upgrade，openviking-server init 走交互式向导——支持火山引擎、OpenAI、Codex OAuth、Kimi、GLM 和本地 Ollama，选 Ollama 还能按硬件拉合适的模型。openviking-server doctor 启动前体检配置、Python 版本、提供商连通性和磁盘空间。有官方 Docker 镜像和 Helm 部署。

集成面很宽：Claude Code、Codex、OpenClaw、Hermes、Cursor、Trae、OpenCode、pi、MCP 客户端、LangChain / LangGraph 都有官方接入，集成做的事是把召回注入 Agent 上下文并自动提交会话记忆。如果你的架构本来就走 MCP 或 LangGraph，接入成本主要在配置层。

许可证要过法务。主项目 AGPLv3，crates/ov_cli 和 examples 是 Apache 2.0。AGPLv3 自用没问题，基于它对外提供网络服务会触发传染性条款的开源义务。商业版 OpenViking Service 承诺与开源版共享同一套代码内核，差异在托管运维、基于 VikingDB 的规模（宣称万亿级向量、百亿数据毫秒级检索）、SLA 和企业级安全合规，有至多 50 个文件的免费试用和迁移工具。开源版默认本地存储加单机向量引擎，数据规模上去后的可靠性要自己扛，架构容量规划时要计入。

背后有论文支撑：VikingMem（arXiv:2605.29640），已被 VLDB 2026 接收，开源版实现了论文描述的部分核心能力。团队在按数据库系统的标准做存储和检索设计，这在 Agent 记忆类项目里少见。

需要注意的点

三点。

其一，整个体系的地基是写入时的自动语义处理——摘要、概览、目录归置全靠模型生成，这些产物没有质量下界。LoCoMo 和 tau2-bench 覆盖的场景有限，换到术语密集的企业知识库，L0 摘要的准确率会不会崩，要拿自己的真实数据验证，别信 benchmark 直接上生产。

其二，导航式检索的延迟特性划定了适用边界，架构选型时按流量形态判断，前面说过了。

其三，项目还早，README 自己承认「要做的事还很多」。1813 次 commit、92 个 open issue、320 个 PR，迭代活跃，反面是 API 稳定性存疑，核心链路重度依赖它要做好跟版本的准备。

回到 Agent 架构本身。「上下文作为独立子系统」「统一文件存储模型」「按决策阶段分层供给」「检索决策可回放」「经验回写闭环」，这五个设计每一个都能脱离 OpenViking 独立存在。

以上

现在我们看到很多的 AI 产品，，本质上还是「把聊天框做得更厚一点」。用户打开一个窗口，对着通识大模型说需求，模型在一个长 session 里记上下文、调几个工具、写几段内容、偶尔执行点操作。这个模式我称它为「Session First」。

「Session First」的模式跑得起来，落地也快。过去一段时间，桌面端的很多产品，包括一些 codex cc 一类的形态，都是这么长出来的。先有聊天，再把能力缝进去。先有 session，再把工具挂上去。整个产品又快又省，因为它继承的是大模型最自然的交互方式：对话。

但如果把时间线拉长，我觉得 Session First 像是一个过渡层。它把大模型带进软件，却没有真正重写软件。

另一个逻辑是 「Agent First」。

这里说的 Agent First，不是把 prompt 包一层 workflow 就算 agent。这里说的是一种更彻底的软件设计取向：系统从一开始就假设调用者不只是人，也包括 agent；系统的能力边界、接口形态、文档组织、安全机制、运行时观测，都优先围绕 agent 来设计。聊天只是入口之一，不再是核心结构。

过去我们是在和「通识大模型」对话，未来更多时候，我们是在和「带有领域知识、工具能力、任务规划能力的专用 agent」协作。再往前走，单一 agent 很可能都不够，基于 MaaS 的 agent teams 会逐步成为复杂任务的常态。Sakana AI 这类工作给了行业一个很有代表性的信号：多智能体协作，不只是研究兴趣，它在复杂探索任务上确实可能优于单体。

这种两种不同的范式，其实也没有高级和低级之分。二者背后的系统假设不同，工程代价不同，性能瓶颈不同，能解决的问题类型也不同。

Session First 和 Agent First 的不同

Session First 和 Agent First，表面上都可能长得像「用户输入一句话，系统输出一个结果」。很多人可能会觉得两者只是包装差异。其实差异蛮大的。

Session First 的中心对象是「会话」。系统假设一切能力都围绕一个持续增长的上下文展开。用户说一句，模型接一句；模型靠历史消息理解意图，靠当前 prompt 决定行为。工具调用存在，但工具通常是会话的附属物。它们由模型在 session 内临时选择、临时编排、临时解释。

所以在 Session First 里，能力组织方式通常是这样的：

1. 先有一个大而全的聊天入口；
2. 再有一组工具函数；
3. 再在 system prompt 或 tool spec 里告诉模型什么时候调用它们；
4. 复杂任务靠更长的上下文、更复杂的提示词、更精细的 few-shot 去兜。

这个模式最大的好处，是产品和研发都能快速起跑。我们不需要先把系统抽象成可组合能力，也不需要先考虑 agent 的长期运行、恢复、权限边界、状态持久化。只要模型够强、上下文够长、工具挂得上去，很多事情都能先做出来。

Agent First 的中心对象则是「行动体」。系统假设执行任务的主体是 agent，它会自己读取规范、规划步骤、调用工具、检查结果、重试修正。人在这个系统里依然重要，但人不再是唯一的控制中心。更准确地说，系统从「为人类交互而生」转向「为可委托执行而生」。

这个变化会连锁改写很多设计决策。

传统软件里，人是第一类公民。系统主要通过 UI 提供能力，文档写给人看，按钮给人点，异常信息也默认人会读。Agent First 里，agent 变成第一类公民。系统的关键界面不再是页面和按钮，而是 API、工具协议、语义化描述、状态机、权限模型、回调事件、执行日志。

传统模式是：

• 人读文档；
• 人理解业务逻辑；
• 人决定点哪个按钮；
• 人承担串联流程的责任。

Agent 模式是：

• Agent 读取规范；
• Agent 形成计划；
• Agent 调用工具；
• Agent 分析返回值；
• Agent 根据反馈继续执行或者回滚。

这不是交互方式的小修小补，这是控制权和复杂性承载位置的转移。

Session First 把复杂性藏在会话里。
Agent First 把复杂性显式地放进系统结构里。

我更倾向后者。因为在规模化阶段会 Session First 开始需要大量的修补并且还不合脚。

Session First 的红利

Session First 也不是说不行了，落后了，它只是有自己的舒适区或边界。

它为什么会成为大多数团队的第一个选择？因为它天然适合模型的原生能力。

大模型最成熟的接口就是聊天接口。你给它上下文，它续写；你给它 instruction，它服从；你给它工具定义，它在概率空间里学着调用。这是当前已经成熟了的，并且对于大家的谁知来说没有门槛的。。产品经理能理解，前端能接，后端能包，用户也能马上用。

从落地顺序看，Session First 有三个明显优势。

交付速度快

最早一批 AI 应用能起量，基本都吃到了这个红利。做一个对话框，叠一层历史上下文，挂几类工具，外加 prompt 工程和少量业务逻辑，一个可卖的产品就出来了。

如果团队处在探索期，需求还没稳定，任务边界也不清晰，Session First 的性价比很高。因为我们可以把大量未定型的业务规则临时编码进 prompt，而不是过早地固化到接口和状态机里。说白了，它适合试错。

交互弹性高

很多需求在早期根本说不清。用户自己也不知道该点哪个按钮，只知道「我想把这堆信息处理一下」。这时聊天入口比传统 UI 更自然。Session First 天然适合承接模糊需求，尤其适合开放式任务、咨询类任务、内容类任务。

对通识模型友好

Session First 依赖的是模型在语言理解和上下文整合上的强项。很多场景下，不需要精细建模世界状态，只需要让模型在一个较长的 session 里维持语义连贯，效果就已经够用了。

所以如果一个产品主要解决的是下面这些问题，Session First 我认为完全合理：

• 单轮或短链路任务；
• 任务结果主要是文本、建议、草稿、分析；
• 工具调用数量少，失败代价低；
• 用户愿意在回路中持续确认；
• 业务状态变化弱，对幂等性和恢复能力要求不高。

比如代码解释、文档问答、简历润色、轻量报表分析、知识库检索助手，这些都很适合。

问题出在很多团队做着做着，把它用到了不该用的地方。

Session 的代价

Session First 最大的问题，不是效果问题，而是系统复杂性的位置不对。

我们可以把 session 理解成一个不断膨胀的黑盒。任务描述、历史记录、工具调用痕迹、失败重试信息、用户偏好、临时约束，全都塞进去。模型在黑盒里靠注意力机制和 token 预算自行判断什么重要、什么该忽略、什么该继续执行。

短任务还行。链路一长，问题就开始多了。

状态污染

会话越长，状态越容易脏。一个典型问题是历史上下文对当前决策的隐性干扰。模型没有传统意义上的干净状态管理，它只有一段被不断续写的上下文。早期的一句错误假设、一次失败调用、一个过时约束，都可能在后续步骤中持续影响行为。

工程上我们会看到一些很烦的现象：

• 明明用户已经修改目标，模型还沿着旧计划跑；
• 明明工具返回了失败，模型把失败结果当成成功上下文继续推理；
• 明明当前任务和上个任务无关，模型还把旧 session 里的偏好带进来。

这些都不是 prompt 多写两句能解决的。因为根因在于 session 本身不是一个严谨的状态容器。

上下文成本失控

Session First 很吃上下文。任务越复杂，历史越长，系统 prompt 越复杂，tool spec 越多，token 消耗越惊人。很多团队前期盯着模型单价，后期才发现账单真正膨胀的是「无效上下文」。

更糟的是，这部分成本并不总能换来线性收益。超过某个长度以后，模型对上下文的利用率明显下降。你花了更多 token，只换来更模糊的关注分布、更高的遗漏概率。

有一些系统，一次复杂任务真正有价值的工作 token 可能只占总 token 的 20% 到 30%，剩下的都在重复喂历史、喂规则、喂工具描述、喂先前失败记录。这样的系统，成本结构很难看。

工具选择不稳定

在 Session First 里，工具往往是通过提示词暴露给模型。模型根据自然语言描述决定什么时候调哪个工具。这种方式灵活，但稳定性一般。尤其当工具数量上来以后，工具间语义重叠、参数边界相近、返回格式不一致，模型的选择质量会迅速下降。

一个常见误区，是以为给工具写更长更详细的 description 就能解决。实际经验正相反：description 越长，竞争工具越多，模型越容易在语义相邻区域摇摆。最终你会发现，问题不是模型笨，而是整个工具层根本没有被设计成适合被模型消费。

可恢复性差

Session 是连续流，不擅长离散恢复。任务执行到一半，模型挂了、超时了、工具限流了、用户关闭页面了，系统怎么从中间恢复？很多 Session First 产品的恢复策略要么是重放整个对话，要么让模型读历史「自己想起来」。

这个策略在低风险任务里还能接受，在执行型任务里就很危险。因为它没有明确的检查点，没有确定的已完成步骤，没有结构化的执行日志，恢复质量完全依赖模型在长上下文里的自我理解。

可观测性弱

你问一个 Session First 系统：「为什么它刚才这么做？」答案通常很难给。因为真正的决策过程埋在 session 和模型隐状态里。你最多能看到 prompt、工具调用记录和输出，但很难形成稳定的、可归因的行为分析。

这会直接影响调试、评估、审计和优化。团队很容易陷入一种很熟悉的工作流：改 prompt、跑样例、感觉好一点、上线、再出新问题、继续改 prompt。系统像在「训一头很聪明但脾气不稳定的动物」，而不是在维护一个可控软件。

转向 Agent

Agent First 出现，本质上是在回答一个问题：当任务不再是聊天，而是委托执行时，系统该怎么设计？

用一名话来概括：Session First 优先组织对话，Agent First 优先组织能力、状态和约束。

这两者的差别，在简单场景里不明显；一旦任务变成多步骤、长周期、高风险、强工具依赖，这个差别会迅速放大。

Agent First 的核心变化有三层。

第一层，agent 拥有独立的任务身份。
它不再只是当前聊天窗口里的一个响应函数，而是一个可启动、可暂停、可恢复、可审计的执行单元。它有自己的目标、记忆、工具权限、运行环境和生命周期。

第二层，系统能力被显式结构化。
什么能力能调用，输入输出是什么，失败怎么表示，重试边界在哪，副作用怎么隔离，全部要写清楚。因为 agent 不是靠「猜」来用系统，它得靠规范来用系统。

第三层，任务执行被流程化和可观测化。
agent 的计划、步骤、结果检查、异常处理、人工介入点，都需要成为系统的一部分，而不是 prompt 里的一段希望。

这就是为什么我说 Agent First 更像软件设计理念，而不只是交互升级。它要求开发者从一开始就考虑 agent 的接入体验。注意，这里的「接入体验」不是 SDK 文档写得漂不漂亮，而是系统有没有把 agent 当成真正的使用者来对待。

对人友好的系统，重点是 UI。
对 agent 友好的系统，重点是 API、协议、文档、沙箱、日志。

这个顺序一换，整套架构都会变。

第一类公民

传统软件的第一类公民是人。因为系统操作链条默认由人承担：读页面、理解状态、做选择、点按钮、确认风险、处理异常。

Agent First 的变化在于，这条链路开始迁移给 agent。系统如果还保留「很多关键信息只藏在页面里、很多操作只能靠人脑理解、很多异常只有人看得懂」的设计，那 agent 就只能在外面绕路，最后产品体验会非常拧巴。

所以所谓「agent 是第一类公民」，落到工程上至少意味着四件事。

能力必须接口化

页面点击不是能力，API 才是。
表格展示不是能力，结构化查询和变更才是。
人工读懂的描述不算完成，机器可消费的 schema 才算完成。

很多团队表面上说在做 agent，实际上只是让模型去模拟用户点页面，或者让 Playwright 去跑浏览器自动化。这能用，但我通常把它看成过渡手段，不会把它当成长期基建。因为 UI 自动化的脆弱性太高，成本也太高。一旦页面变了、字段换了、弹窗多了、权限策略改了，整个链路就坏了。

如果一项业务能力值得被 agent 使用，那它应该先被抽成稳定接口。

语义必须外显

我们靠经验猜按钮含义，agent 不行。我们得把操作语义、字段含义、约束条件、异常语义都写出来。很多传统系统文档的问题，不是文档少，而是文档默认阅读者是熟悉业务的人。里面有大量省略、上下文跳跃、术语别名、口头约定。

人能脑补。agent 不会脑补，它会误解。

机器友好的文档，不是把原文档丢给 RAG 就结束了。它要求内容可索引、可切片、可定位、可引用、可验证。最好还能区分「定义」「约束」「样例」「反例」「危险操作」「返回码语义」。

权限必须细粒度

给人开的权限，往往是按角色开的。给 agent 开权限，粒度要更细。因为 agent 的调用频率高、组合能力强、自动化程度高，任何一个权限放大，都可能把小问题变成系统性事故。

我见过一些团队初期为了快，直接给 agent 一个「管理员 token」，想着先把链路跑通。跑通确实跑通了，后面风控和审计基本没法收场。Agent First 里，权限模型必须从 day 1 就设计进去。至少要做到工具级、资源级、动作级的边界清晰。

结果必须可审计

如果 agent 能执行动作，那所有关键动作都要留痕，谁发起、为什么发起、使用了哪些上下文、调用了哪些工具、拿到了哪些结果、做了什么决策、是否有人确认，都得能追出来。

这不是为了满足审计部门，而是为了我们自己能把系统维护下去。没有可审计性，复杂 agent 系统很快会变成「偶尔非常惊艳，偶尔完全失控」的黑箱。

四层结构

如果我们把 Agent First 的工程原则压缩成一个递进结构，它可以拆成四层：能力层、理解层、连接层、信任层。

API 优先

最底下是能力层，也就是 API 优先。它解决的是「Agent 能做什么」。

很多 AI 团队容易犯一个错误：先做 prompt，再做工具，再补 API。顺序反了。只要你准备认真做 agent，API 就应该先于 prompt 存在。

因为 prompt 负责引导决策，API 才负责承载能力。没有稳定能力面，agent 的执行质量永远靠运气。

我看一个系统适不适合 Agent First，第一眼就看它的 API 长什么样。重点不在 REST 还是 GraphQL，也不在用不用 MCP，而在这几个问题：

• 接口语义是否单一清晰；
• 参数是否结构化且有约束；
• 返回值是否可判定成功失败；
• 幂等性是否明确；
• 长任务是否支持异步和回调；
• 副作用操作是否支持 dry-run 或预检查；
• 错误码是否可用于 agent 自恢复。

举个很实际的坑。很多内部系统的 API 是给前端页面写的，不是给 agent 写的。于是你会看到：

• 一个接口返回几十个业务无关字段；
• 失败时只返回「操作失败，请联系管理员」；
• 同一个字段在不同接口里名字还不一样；
• 创建和更新共用一个入口，副作用混杂；
• 数据查询支持模糊匹配，但没有稳定过滤条件。

这种 API 给前端开发凑合能用，给 agent 基本就是灾难。因为 agent 消费接口时最怕三件事：语义不稳定、返回不可判定、失败不可恢复。

API 优先不是一句口号，它意味着你要为了 agent 重写一部分服务边界。代价不小，但省下的是后面无数轮 prompt 补丁。

机器文档

有了能力层，还不够。Agent 知道系统「能做什么」，不代表它知道「怎么正确地做」。

这就是理解层，也就是机器友好文档。

很多团队对文档的理解还停留在「给模型塞进知识库」。坦白说，这一步最多算资料接入，不算文档工程。机器友好文档要求内容本身就是为 agent 理解和执行设计的。

我们写文档喜欢写背景、写故事、写注意事项穿插在长段落里。机器文档要反过来，尽量消除叙事性，强化检索和判定性。什么场景能用哪个接口，前置条件是什么，参数组合有什么限制，成功条件是什么，失败后应该重试还是终止，全部要能被定位出来。

我比较推崇一种写法：把文档拆成五类最小单元。

1. 定义单元：术语、对象、字段、状态含义。
2. 操作单元：动作描述、输入输出、前置条件、后置条件。
3. 约束单元：权限要求、配额、时序、互斥关系。
4. 异常单元：错误码、成因、恢复建议、是否可重试。
5. 样例单元：正确示例、错误示例、边界示例。

这样写出来的文档，对人读可能不友好，但对 agent 非常友好。因为 agent 需要的不是阅读体验，而是最短路径上的高密度语义。

还有一个容易被忽略的点：文档版本化。
如果系统能力在变，而 agent 依赖旧文档决策，事故几乎是必然的。机器文档必须带版本、带生效范围、带弃用说明。更进一步，文档变更最好能够被 agent 订阅或者被平台主动推送。否则你会得到一堆「以前能跑今天突然不行」的鬼问题。

协议层

再往上一层是连接层，也就是标准化协议。我们都知道 MCP，它当前重要性确实在上升。

Agent First 一旦进入平台化阶段，连接成本会成为瓶颈。每接一个系统都重新对工具做 schema 包装、鉴权对接、错误语义映射、流式交互适配，团队很快就会被集成工作拖死。标准协议的价值就在这里：让 agent 对外部能力做到尽可能低摩擦的即插即用。

协议不是为了优雅，是为了降低耦合和重复劳动。它至少解决三个问题：

• 能力发现：agent 如何知道外部提供了哪些工具和资源；
• 调用协商：参数 schema、返回 schema、流式能力、状态反馈如何统一；
• 安全边界：认证、授权、调用隔离、资源限制如何标准化表达。

MCP 这类协议的意义，不只是统一 tool calling 的表面格式，更重要的是把「能力元数据」变成平台可理解的对象。一旦元数据标准化，很多平台能力才能长出来：自动装配、权限编排、调用治理、能力市场、兼容性检查、离线评测。

协议统一不会自动带来效果统一。现实里最常见的问题是：大家都说自己支持标准，结果 schema 质量参差不齐，语义粒度不一致，错误处理风格也不同。最后 agent 虽然能连上，依旧很难稳定用好。

所以协议层只是接入下限，不是体验上限。系统方如果指望「支持 MCP 了，agent 就能用了」，十有八九会失望。

信任成本

最上面一层是信任层：安全、沙箱、可观测性。它解决的是「Agent 如何被安全地使用」。

这层往往是被低估的。因为很多团队在前期更关心效果演示，安全和观测总想放后面补。等 agent 真开始执行动作，补起来就很痛苦。

Agent 系统的风险和传统自动化脚本不完全一样。脚本通常路径固定、输入有限、行为可枚举。Agent 的输入是开放的，计划是动态的，工具组合是可变的，自修正带来恢复能力，也带来行为不可预测性。这种系统如果没有信任层，部署规模一上来迟早出事。

信任层可以分为三块。

安全边界

包括权限控制、数据隔离、密钥管理、配额限制、危险操作确认机制。所有高风险动作都要能分级：只读、可写、可执行、不可逆。不同级别的动作，对应不同的确认和审计策略。

还有一件事必须单独说：prompt injection。
只要 agent 会读取外部内容、再基于内容调用工具，prompt injection 就不是附加风险，而是基本风险。你不能假设模型会自己免疫。系统层必须有输入隔离、指令优先级控制、工具调用白名单、敏感动作二次确认、结果验证。

沙箱执行

如果 agent 能运行代码、操作文件、访问网络，就必须有沙箱。别指望靠「模型会守规矩」来兜底。资源限制、网络出口策略、文件系统隔离、进程生命周期管理，这些都是必须项。

很多桌面端产品今天还在用一个比较重的本地 session 容器去承接 agent 行为，这在早期合理，因为本地环境天然带着用户上下文和工具可得性。但一旦平台化，执行环境一定要可控、可回收、可复制。否则你会发现 bug 根本没法稳定复现。

可观测性

这一块经常被做得太浅。普通日志不够。你需要的是面向 agent 的运行时观测：任务级 trace、步骤级事件、工具调用链、上下文快照、计划变更、重试原因、人工接管点、最终结果评估。

有了这些数据，很多事情才有可能做：行为分析、失败归因、离线回放、A/B 对比、策略优化、合规审计。

我甚至会说，没有可观测性，Agent First 根本不成立。因为你没法持续优化一个你看不见的系统。

单体与团队

再往前一步，Agent First 还会带来一个自然演进：从单一 agent 走向 agent teams。

这个趋势不难理解。单体 agent 的优势是简单、上下文统一、决策路径短。缺点也明显：任务一复杂，规划、执行、验证、知识检索、异常恢复全压在一个主体上，容易出现上下文拥堵和角色冲突。模型一边要想战略，一边要写细节，一边还要检查自己，稳定性会下降。

多 agent 协作的思路，是把不同职责拆开。比如规划 agent 负责分解任务，执行 agent 负责调用工具，验证 agent 负责检查输出，审计 agent 负责看风险和合规。你提到 Sakana AI，我觉得它给行业的启发就在这里：复杂问题的效果上限，未必来自更大的单体，而可能来自更合理的协作结构。

但别高估 agent teams 的短期收益。它的工程成本很高。

第一，通信成本会增加。
agent 之间传递的信息如果不够压缩，token 成本会迅速膨胀。很多团队做多 agent，最后账单翻倍，效果提升却不明显，问题就出在这里。

第二，错误归因更难。
单体 agent 出错，你还知道看一条链。多 agent 出错，很可能是上游规划有偏差、中游执行误解了任务、下游验证规则又太松。没有细致的 trace，很难定位。

第三，协作协议本身就是复杂度。
谁能给谁发任务，谁对谁有覆盖权，冲突怎么解决，结果以谁为准，失败是否回滚，人工在什么点介入，这些全得定规则。规则一多，系统会变得很重。

它是复杂任务的方向，但不是所有产品都该急着上。很多团队连单体 agent 的能力边界、观测体系、权限模型都没建好，就直接跳多 agent，最后只会把问题放大。

个人的判断

如果今天让我给团队定路线，我不会在所有场景里一刀切推 Agent First，也不会继续把 Session First 当主架构。

我的判断是这样的：

凡是以「理解、生成、陪伴、咨询」为主，任务链条短，用户始终在线，副作用低的场景，Session First 依然是最有效率的方案。别把简单问题搞复杂。一个高质量 session 产品，照样能有非常强的竞争力。

凡是以「委托执行、跨系统操作、长周期任务、可恢复流程、强审计要求」为主的场景，应该尽早转向 Agent First。拖得越久，后面迁移成本越高。因为你的 prompt、工具、日志、权限、数据结构都会按 Session First 的惯性越长越歪，最后很难矫正。

从行业演进看，我认为我们会经历三个阶段：

第一阶段，通识模型 + 聊天入口主导。
第二阶段，聊天入口还在，但底层逐步 agent 化，能力和状态开始结构化。
第三阶段，很多系统默认面向 agent 开放，我们反而通过 agent 间接使用软件。

今天大多数团队还处在第一阶段和第二阶段之间。很多产品表面上已经在说 agent，骨子里还是 session 产品。这个阶段没什么丢人的，行业本来就处在过渡期。问题在于，团队自己得知道自己在哪，不要把一个 prompt-heavy 的聊天系统误以为已经完成了架构升级。

小结

Session First 帮行业把 AI 快速带进了产品。它的重要性不用否认。没有这一阶段，大量需求不会被激活，很多团队也不会积累起对模型能力边界的真实理解。

但它的问题也越来越明显：状态管理松散、成本结构失真、工具使用脆弱、恢复和审计能力薄弱。任务越复杂，缺点越放大。

Agent First 把软件重新组织了一遍：把会话里的隐含复杂性，搬回系统里显式管理；把面向人的操作界面，扩展成面向 agent 的能力界面；把「模型偶尔能做成」变成「系统可稳定交付」。

如果要走这条路，我们就需要重写 API，补文档债，需要重做权限和日志，就会发现以前很多偷过的懒都要补回来。可如果我们的目标不是做一个会聊天的功能，而是做一个能被委托工作的系统，这些账早晚都要还。

所以我现在看一个 AI 产品会更关心它底下埋的是 session，还是 agent。前者决定它今天看起来多聪明，后者决定它一年后还能不能继续长。

以上。

我们在落地 Agent 时面临的核心矛盾，是大模型的概率生成机制与工程系统所需的绝对确定性存在天然冲突。要获取大规模、可维护且值得信赖的代码，必须在系统外围构建 Harness。Harness 的本质是将不确定性转化为确定性。

提高信任度和可靠性需要极度压缩 Agent 的解决方案空间。我们必须放弃让模型「生成任何内容」的灵活性，转而采用包含大量技术细节的提示、规则和框架。特定的架构模式、强制执行的边界以及标准化的结构，构成了这套护栏的物理基础。

当前越来越多的团队在持续快速的产生代码，而这些演示很好看，当真的进入整个软件生命周期中，就会产生混乱，当越来越多的人随着时间的推移在仓库中堆砌代码，组织就开始堆人进行 review、反复返工，最后 AI 的吞吐量被人类注意力卡死，表面上用了 Agent，实际产能没上去，维护成本还更高。

当然，这是一种结果，也有人在过程中不停的构建基建，做 Harness 工程，整个代码不再是无序的扩张。从这个逻辑来讲，harness 的作用是把大模型输出从概率事件压回工程确定性的系统设计。

Agent 的 Harness

harness 是什么

很多人把 harness 比作一个操作系统，模型是 CPU，但我觉得并不是。

如果模型真的是 CPU，那它接收指令后的执行结果应该是绝对严格且可预测的；但大模型本质上是一个概率引擎，它在潜空间里做的是模式匹配与概率生成。因此，harness 并不是像操作系统那样去调度底层硬件资源或分配内存，它更像是一套概率过滤器和对齐机制。它依靠纯粹的工程手段，把模型那种发散的、充满不确定性的「创造力」或「幻觉」，强行压缩进一条狭窄、严谨且符合人类预期的流水线里。

这种工程逻辑在实践中，体现为无处不在的防御性设计和反馈闭环。当模型吐出一串代码或一个决策时，harness 并不负责直接「运行」它，而是负责「质检」和「纠偏」。它通过静态检查、架构规则扫描、自动化测试和沙箱验证，把模型给出的「大概率正确」转化为工程上非黑即白的「通过或驳回」。正是这种让概率不断撞击确定性规则的过程，才使得最终沉淀到代码库里的产物是安全、可控且符合系统长期利益的。

harness 解决确定性问题的终极目的，是为了在系统中建立无需人工干预的信任，从而真正释放 AI 的吞吐量。如果没有这套逻辑，模型生成的代码越多，人类审查的负担就越重，整个组织的运转速度依然会被人类的注意力瓶颈卡死。

Martin Fowler 的博客中发表了 Thoughtworks 的技术专家的一篇文章，将 OpenAI 文章中所描述的 harness 分为三个方面：

上下文工程

上下文工程需要做到动态与静态的交织

单纯依赖超长 Prompt 无法解决复杂工程问题。上下文工程的核心在于构建代码库中持续增强的知识库，并打通 Agent 对动态上下文的访问路径。

静态知识库定义了系统的基础法则。我们将领域模型、API 契约和历史架构决策文档化，作为 Agent 初始化的基线上下文。动态上下文决定了 Agent 在运行时的决策质量。系统需要将实时的可观测性数据、测试覆盖率报告甚至浏览器导航状态，实时注入到 Agent 的工作流中。缺乏动态上下文的 Agent 就像蒙眼狂奔的打字机，产出的代码在语法上完美，在逻辑上完全脱离系统现状。

架构约束

架构约束是确定性的防线。

完全依赖 LLM 进行自我反思和代码审查，在生产环境中极度危险。架构约束必须由确定性的自定义代码检查器和结构测试来强制执行。

我们通过静态分析工具拦截不合规的依赖调用，利用 AST（抽象语法树）解析确保代码分层符合规范。当 Agent 试图在 UI 层直接发起数据库连接时，确定性的检查器会立即阻断该行为，并将具体的错误堆栈和修复路径作为反馈输入给 Agent。这种混合架构确保了系统的底线由死板的规则守卫，Agent 的创造力被严格限制在安全的沙盒内。

垃圾回收

垃圾回收主要是用于对抗代码熵增。

完全自主的智能体引入了代码库衰败的新问题。Agent 会精准且不知疲倦地复现代码仓库中已存在的模式，包含那些不均衡或不够理想的遗留设计。随着时间的推移，这种行为不可避免地导致系统架构漂移。

最初，人类开发者试图手动处理这个问题。团队过去每周五要花费 20% 的时间清理「AI 残渣」。这种依赖人力的做法毫无可扩展性。

我们将资深工程师的主观品味转化为机械规则，提炼为「黄金原则」并直接编码到代码仓库中，建立了一个循环清理流程。我们强制要求使用共享的实用程序包，禁止手工编写零散的辅助工具，确保不变式集中管理。我们严禁使用猜测性的数据探测，强制验证边界或依赖类型化的 SDK，防止 Agent 基于虚幻的结构进行构建。

系统定期运行一组后台 Agent 任务，扫描代码库中的偏差、更新质量等级，并发起有针对性的重构 Pull Request。这些 PR 大多可以在一分钟内完成审查并自动合并。这套机制的功能等同于内存管理中的垃圾回收。技术债务如同高息贷款，通过高频的微小重构不断偿还，远胜过让债务累积到系统崩溃。人类的架构品味一旦被捕获并规则化，就会无情地应用于每一行代码，每天自动发现并消灭不良模式。

AI Agent Harness 的工程化落地

从几个流行的框架来看，主要是从流程强化、规格沉淀、任务编排等逻辑上来做事情。

将这些逻辑拆开可以分为四个维度：

上下文工程

上下文工程主要是在规范层解决问题，其主要解决的「规则文件失控」的问题，实现规格沉淀与对齐，以及上下文工程的可控。

之前，我们习惯把所有规范塞进类似于单个 .cursorrules 文件，导致 AI 上下文过载且容易忽略细节。这一层落地的第一步是建立结构化、按需加载的规范体系。主要做到如下的点：

• 规范模块化：将系统架构、数据库规范、错误处理等拆分为独立的结构化文档。
• 按需检索：AI 不需要每次都通读所有规范，而是根据当前所处的任务阶段，动态检索并加载所需的上下文。
• 任务记忆隔离：为每个独立任务建立物理隔离的工作区和日志。AI 每次开启新会话时，只读取当前任务的精确记忆，既解决了“跨会话失忆”，又屏蔽了无关信息的干扰。

以 Trellis 框架为例，Trellis 摒弃了单一庞大的全局提示词文件，而是采用 spec/ 目录将规范模块化（如拆分为 database-guidelines.md）。在执行任务时，它利用 tasks/ 目录下的 JSONL 配置文件，让 Agent 动态检索并按需加载上下文。

架构约束

架构约束的核心逻辑：用代码约束代码，实现闭环自愈。 口头约定或纯文本规范在 AI 面前是脆弱的，它极易为了「跑通逻辑」而破坏架构分层。

• 规则代码化：将核心的架构依赖规则（例如“前端组件严禁直接调用数据库”）编写为静态分析脚本或自定义 Linter。
• 带解释的强阻断：在代码提交或验证阶段强制执行这些拦截器。关键在于，报错信息不能仅仅是「检查失败」，必须输出高度结构化的指导：明确告诉 AI“为什么违反了规则”以及“正确的做法是什么”。
• 自动修复：AI 读取到结构化的报错指导后，能够自动理解并修正代码，形成无需人类介入的自愈闭环。

反馈循环

核心逻辑：降噪处理，防范死循环。 LLM 的注意力会被长篇大论的日志（如几千行的覆盖率输出）稀释注意力，从而忽略真正致命的错误。 因此我们需要做到：

• 零输出原则：改造验证脚本。如果测试通过，脚本应保持完全沉默；如果失败，只输出精简的错误堆栈和失败原因。
• 强制验收清单：在 AI 试图标记任务「已完成」之前，系统应强制拦截，要求其对照需求文档逐项确认边界条件。
• 防死循环干预：设定重试阈值。如果 AI 对同一文件连续修改多次且测试依然失败，系统应主动中断并强制其回滚代码、重新审视需求，防止 AI 陷入无效的「幻觉修 Bug」循环。

熵管理

熵管理主要是阻断「坏模式」的指数级扩散

核心逻辑：快速偿还技术债。 AI 复制坏代码的速度是指数级的。一旦允许一个临时的妥协方案合入主分支，AI 会在极短时间内将其复制到整个代码库。

• 高频垃圾收集：彻底放弃“集中清技术债”的传统做法。每天必须安排固定时间，专门 Review AI 生成的代码（人工或 AI 自动），及时识别新引入的坏模式。
• 规范资产的动态演进：一旦发现坏模式，立即让 AI 深度分析根因，并自动将正确的防范规则更新到规范库中。
• 团队级免疫：由于规范库与代码同源管理（存在于 Git 仓库中），当这段新规则被提交后，团队其他成员拉取代码时，他们的 AI 助手就能立刻“学会”这个新技能。这把偿还技术债的动作，变成了每天自动化、可积累的系统进化。

以 Cursor 为例，可以更新 Team Rules

组织级 Harness

聊完 Agent 的 Harness，再聊一下组织的。

人的角色已经变了

大家都知道康威定律，简单来说就是：设计系统的组织，其产生的设计受限于这些组织的沟通结构。

而系统设计到最后，也一定会遇到一个问题：谁来定义规则，谁来解释例外，谁来承担后果。

以前的软件开发分工相对稳定。PM 写需求，设计出稿，前后端分别实现，测试验证，运维发布。大家各自占一段链路，边界虽然有摩擦，但总体清楚。

AI 进来以后，边界开始模糊。

PM 已经可以直接产出前端原型，很多时候产出的还不是静态图，而是真能跑的页面代码。设计师也不再只是给稿子，很多交互和组件约束可以直接沉淀成生成资产。前端工程师花在纯页面搭建上的时间下降，开始更多介入状态管理、交互抽象、可维护性收拢。后端和算法也更早被拉进来，因为很多 AI 生成的原型一开始就会碰到真实数据和能力边界。

这是现在很多团队正在进行的转型。

如果组织还按旧的分工运转，Agent 会把协作缝隙快速放大。

组织级 Harness 要管什么

我理解的组织级 harness，重点在三件事：

1. 定义新的协作接口
2. 重新分配注意力
3. 把责任从「谁写了代码」改成「谁定义了系统」

协作接口要前移

以前很多问题可以留到开发阶段再对齐。现在不行。

因为 PM 通过 AI 已经能直接产出前端代码，需求不再是文字说明，而可能是一个可交互原型；设计规范也不再只是 Figma 标注，而是可以半自动映射到组件约束；后端接口能力如果不提前讲清楚，前面的生成很容易一路偏到错误方向。

所以组织里的评审必须前移，重点也得改。

过去的需求评审，很多时候在讨论功能要不要做。现在要多讨论三件事：

• 验收标准到底是什么
• 哪些边界不能突破
• 哪些部分允许先用原型推进，哪些必须工程化收拢后才能上线

这几个东西不提前定，后面会出现一个很常见的问题：原型阶段看起来进展飞快，进入工程化后才发现返工巨大。

注意力要重新分配

我现在越来越少鼓励资深工程师花时间逐行抠低风险代码。

这不是说 review 不重要，而是注意力要贵着用。

在 Agent 环境里，重要的工作变成了：

• 定义验收标准
• 设计架构边界
• 提炼黄金原则
• 识别系统性失败信号
• 决定哪些异常值得阻塞主流程
• 审核高风险改动和高影响面重构

反过来，低风险、重复性、局部性的东西，应该尽量交给自动化校验和后台清理任务。

如果一个组织还在让最贵的人力去看大批格式化差异、小工具改名、重复样板代码，那 harness 基本等于没有。

责任归属要重写

在 AI-Native 组织里，谁对结果负责？

PM 产出了页面代码，前端做了工程化收拢，Agent 自动补了测试，清理 Agent 又改了一轮共享工具。最后线上出问题，算谁的？

如果这个问题没有明确答案，团队会很快进入防御状态。每个人都怕接 AI 产出的锅，于是流程开始重新变重，所有人都试图把责任往后传。

所以组织级 harness 一定要明确责任模型。

可以按三层分：

• 需求责任：谁定义了目标与验收标准，谁负责需求正确性
• 架构责任：谁定义了边界、模式和约束，谁负责系统一致性
• 发布责任：谁决定进入生产环境，谁负责风险接受

不要再执着于「谁手写了这行代码」。就像团队管理一样，最后拍板的人担责。

可落地的 AI-Native 研发流程

以下为我们当前在跑的流程：

需求生成

第一步由 PM 主导，但交付物不再只是 PRD，而是带验收标准的可运行原型。

但是，原型代码不等于可直接上线代码。它的价值是澄清需求、暴露分歧、提前感知交互复杂度。

所以 PM 可以生成，但不能默认拥有工程决策权。最终所有的代码都需要前端工程师构建的工具链条，以及 AI 和人工的审核及合入。

联合评审

第二步是全员参与的需求评审与架构设计。设计、前端、后端、算法都要尽早介入。

这个阶段重点不是抠实现细节，而是确定：

• 用户路径是否成立
• 数据流怎么走
• 状态边界怎么划
• 哪些能力用现有服务承接
• 哪些模块需要新增抽象
• 风险点在哪
• 验收怎么自动化

这这一步的产出结构化进仓库，因为后面它会直接成为 Agent 的约束输入。

工程收拢

第三步是工程化整合。这个阶段前端、后端、算法开始把前面的原型和需求收敛进正式系统。

这里 Agent 会大量参与，但人类不能退出。重点工作包括：

• 把原型重构进现有组件和模块体系
• 校正状态管理、错误处理、埋点、权限、监控
• 对接真实接口和算法能力
• 补齐类型、边界验证和回归测试
• 处理跨模块影响面

这一段最考验 harness，因为原型代码最容易带着局部最优、全局失真、风格漂移的问题冲进主仓。

自动验证与灰度

最后一步是自动化测试、灰度发布和反馈回收。

这一步先由专门的工程团队来负责，加入部分的 AI 成分，固化系统。

从 Agent 到组织，真正难的是控制系统

很多人以为 AI 落地的核心挑战在模型能力、成本或者工具接入。我现在看，最大挑战更集中在三个词：环境、反馈回路、控制系统。

环境决定 Agent 看到了什么、能做什么、不能做什么。

反馈回路决定错误会被放大，还是会被系统吸收成改进信号。

控制系统决定生成能力增长之后，组织是变得更稳，还是更乱。

这三个东西做不好，模型再强也只是更快地产生问题。

做得好，哪怕模型能力没到最顶尖，系统一样能稳定进化。因为工程上真正稀缺的，从来不是一次惊艳输出，而是长期重复地产出靠谱结果。

组织的 AI-Native 化

组织的 AI-Native 化也是慢慢进货，逐步推进的，先从小范围试起，再根据结果不断调整规则和流程。并且各家有各家的风格和气质。

第一，选一条链路打透。不要一开始就全组织铺开。先找一个协作关系清楚、反馈周期短、风险相对可控的场景，比如中后台、运营工具、内部系统，或者低风险服务改造。重点不是让 AI 多写代码，而是先验证：信息怎么给、边界怎么定、错误怎么发现、问题怎么清理。

第二，先改规则，再谈效率。很多团队一上来就问产能能提升多少，但更重要的是：规则有没有沉淀下来，错误能不能回流，坏模式能不能及时发现并清掉。如果这些没做好，所谓提效往往只是把问题推后，甚至把混乱放大。

第三，把人的位置往上移。资深工程师要逐渐从大量写代码，转向定规则、画边界、看反馈；技术管理者要从盯人和排期，转向设计流程、分层风险、明确责任；产品可以更早参与原型，但不能越过工程判断。

组织真正变成 AI-Native，不是因为每个人都在用 Agent，而是协作方式已经围绕 Agent 被重新设计过。

模型当然重要，但不是决定性因素。真正拉开差距的，是谁先意识到：Agent 不是一个更快的开发者，而是一个高吞吐的生产单元。它会放大环境本身。规则清楚，它就放大规则；流程混乱，它就放大混乱。

所以到最后，harness 这件事谈的根本不只是 AI。

谈的是工程纪律怎么重新编码。

谈的是组织协作怎么重新布线。

谈的是我们怎么把概率生成系统，放进一个仍然要求长期维护、长期演进、长期负责的软件世界。

这是我理解的「从 Agent 到组织」。

以上。

穿透复杂的表象，当前 LLM 的底层运行逻辑其实非常单一：它本质上是一个自回归的序列生成器，根据已有的上下文，计算词表中每一个 token 出现的概率分布，然后从中采样出下一个 token。

但这里的「概率」绝非毫无逻辑的随机掷骰子。 这种概率分布，是模型在海量预训练数据中内化的语言规律、世界知识以及逻辑推理能力的数学投影。通过多层 Transformer 网络与注意力机制（Attention），模型在极高的维度上完成了对上下文语义的深度解析与特征关联，从而将符合人类逻辑、契合当前语境的 token 赋予极高的概率权重。它是在用统计学的方式，重现人类的逻辑推理过程。

然而，无论其内部的概率计算多么精密，从软件工程的宏观视角来看，我们本质上依然是在传统的确定性系统中，强行引入了一个基于概率采样的非确定性组件。

传统软件工程建立在严格的确定性之上。输入特定的参数，经过固定的业务逻辑，必然得到预期的输出。现在我们将核心逻辑交由概率模型处理，相同的输入在不同的时间点，可能会产生完全不同的输出路径。

幻觉无法被根除。它是自回归模型的内生特性，是概率采样的必然产物。我们在进行系统架构设计时，必须将幻觉视为系统的常态。试图通过修改 Prompt 来彻底消除幻觉，在工程上徒劳无功。我们需要在系统边界处建立起拦截机制，用确定性的规则去兜底概率模型的不确定性。

容错度决定落地

当前商业化落地最顺畅、ROI 最高的场景，全部集中在高容错度领域。写行业报告、生成营销文案、文生图、视频生成、游戏 NPC 对话。这类场景的核心特征在于缺乏绝对的客观标准。

在内容创作领域，模型偶尔的逻辑发散会被用户视为创造力。工程团队不需要在接口的绝对可用性和输出的绝对准确性上死磕，只需要保证底线的内容安全和合理的响应延迟。系统可用性达到 95% 就能让用户产生极强的获得感。

一旦进入低容错度场景，工程实现的复杂度会呈指数级上升。医疗诊断、工业控制、核心交易链路。在这些领域，0.1% 的幻觉率都会导致灾难性的业务后果。我们在评估一个 AI 项目是否立项时，首要考量指标就是业务场景的容错底线。容错度越低，外围需要的确定性校验代码就越厚重，最终会导致系统的维护成本远超 AI 带来的效率提升。

知识外挂 RAG

RAG 的出现是为了解决模型内部知识更新滞后和私有数据隔离的问题。其核心原理是将外部文档切片、向量化，在用户提问时检索相关切片，拼接到 Prompt 中作为上下文喂给大模型。

在实际的工程环境里，RAG 的核心瓶颈在检索链路。切片策略直接决定了召回质量。按固定 token 长度切分会破坏语义完整性，导致关键信息被腰斩。按标点符号或段落切分会导致切片长度方差过大，影响向量化模型的表达能力。我们在生产环境中通常需要针对不同格式的文档编写定制化的解析器，将 PDF 或 Word 还原为结构化的文档树，再基于文档树的层级进行语义切片。

单一的向量检索在面对专有名词和长尾词汇时表现极差。我们必须采用混合检索架构：稠密向量检索加上稀疏词表检索。向量检索负责语义泛化，处理同义词和模糊表达。词表检索负责精准匹配产品型号、人名和内部项目代号。混合检索引入了多路召回合并的问题，通常需要引入倒数秩融合算法来重排结果。系统复杂度和查询延迟会成倍增加。

数据清洗占据了 RAG 项目 80% 的研发精力。直接将企业内部的原始文档灌入向量数据库，最终的问答准确率通常不到 40%。文档中存在大量的废话、过期的流程规范以及相互冲突的条款。垃圾进，垃圾出。我们在构建知识库之前，必须通过脚本和人工介入，对语料进行严格的去重、降噪和结构化提取。

工具调用确定性

为了弥补概率模型的缺陷，我们需要引入确定性的工具。Function Calling 机制本质上是给 LLM 接上双手。模型负责理解自然语言意图并提取结构化参数，具体的业务逻辑交由传统的确定性脚本执行。

工具调用的工程难点在于参数提取的稳定性。当注册的工具数量超过十个，或者参数结构嵌套层级过深时，模型的输出格式极易崩溃。我们在中间层必须加入严格的 Schema 校验机制。一旦校验失败，需要截断错误信息并触发重试。重试次数上限通常设定为 3 次，继续增加会耗尽上下文窗口并导致请求超时。

多轮工具调用会带来严重的延迟问题。模型每决定调用一次工具，都需要经历一次完整的网络请求和推理过程。如果一个复杂任务需要串行调用三个工具，用户的等待时间会轻易突破 10 秒。我们在架构设计时，需要尽可能将细粒度的 API 聚合成粗粒度的宏接口，减少模型与业务系统的交互频次。

Agent 架构的脆弱性与状态管理

多智能体（Multi-Agent）架构在技术社区被过度神话。多个大模型相互协作、自主规划任务的 Demo 看起来非常惊艳。在真实的工业场景中，完全由 LLM 自主驱动的 Agent 链路极其脆弱。

误差会在多步推理中被迅速放大。假设单个 Agent 节点的输出准确率为 90%，一个包含五个节点的串行任务，最终的成功率会暴跌至 59%。任何一个节点的幻觉都会导致后续链路彻底跑偏。

我们在生产环境中构建复杂任务流时，坚决摒弃由 LLM 自主决定执行路径的黑盒模式。控制流必须由传统的有向无环图（DAG）或状态机来接管。LLM 仅仅作为状态机中的一个计算节点，负责处理非结构化数据的理解和生成。节点与节点之间的状态流转、条件判断、异常重试，全部由确定性的代码实现。这种设计牺牲了系统的灵活性，换取了业务系统必须具备的稳定性和可观测性。

非确定性系统的测试与监控

非确定性系统的测试与监控，是传统软件工程团队转型 AI 开发时遇到的最大痛点。传统的单元测试基于断言，期望输出是固定的字符串或数值。面对 LLM 每次都不一样的回答，基于精确匹配的 CI/CD 流水线会全线崩溃。

我们重构了整个测试评估体系。引入 LLM-as-a-Judge 机制，使用一个能力更强、参数规模更大的模型来评估业务模型的输出质量。评估维度被拆解为相关性、事实一致性、格式合规性等具体指标。在每次模型版本迭代或 Prompt 修改后，必须在包含上千个真实业务 Case 的黄金数据集上运行自动化评估。只有各项指标的波动在可控范围内，才能进行灰度发布。

在监控层面，传统的 APM 工具无法满足需求。我们需要采集每一个请求的 Prompt 模板版本、输入变量、输出结果、Token 消耗量以及推理延迟。这些数据是后续进行 Bad Case 分析和模型微调的唯一原料。针对 Token 消耗的监控直接与业务成本挂钩。我们会在网关层设置严格的并发限制和预算熔断机制，防止恶意请求或死循环调用导致账单失控。

两种范式的碰撞

AI First 与 AI 辅助是完全不同的架构逻辑。

AI 辅助是在现有系统中打补丁。主干流程依然是传统的表单和按钮，AI 作为一个侧边栏或悬浮窗存在，提供总结、翻译、润色功能。开发成本极低，对原有系统无侵入。用户在遇到问题时，可以选择性地向 AI 求助。

AI First 要求重构整个交互形态和底层流转逻辑。系统不再依赖预设的菜单树，由 LLM 充当中央路由。用户的自然语言输入直接驱动底层状态机流转。这要求所有内部 API 具备极高的自描述能力，业务逻辑必须高度解耦。我们在推进 AI First 架构时，面临的最大阻力通常来自老旧系统的技术债。历史遗留的紧耦合代码根本无法被封装成独立的工具供模型调用。

财务场景的拆解

财务场景是典型的低容错度、高确定性要求的领域。将概率模型直接应用于财务核心链路会引发严重的合规风险。可落地的切入点集中在外围的非结构化数据处理和信息流转环节。

发票与报销单据的信息抽取是一个高价值场景。传统 OCR 结合正则匹配在面对版式多变的票据时维护成本极高。引入大模型进行多模态信息抽取，将非结构化的图片或 PDF 转换为结构化的 JSON 数据。抽取后的数据必须经过传统规则引擎的二次校验，例如金额试算平衡验证、税号合规性检查。模型在这里承担的是「粗加工」角色，最终的业务落库动作依然由确定性代码把控。

财务制度问答可以大幅降低沟通成本。基于企业内部报销规范构建 RAG 系统。员工在提单前通过自然语言查询报销标准。这里的 RAG 必须严格限制模型的发散，Prompt 中需强制要求「仅根据检索到的内容回答，未提及的内容直接回复不知道」。为了防止模型编造财务政策，我们会在输出层增加一层文本相似度校验，确保模型的回答与检索到的原文保持高度一致。

财务分析报告初稿生成也是一个可行的方向。将结构化的财务报表数据通过代码转换为文本描述，作为上下文喂给模型，让其生成趋势分析和异常波动提示。模型在这里仅作为「翻译官」和「排版员」，不参与任何数值计算。所有的同比、环比计算必须在传统代码层完成，将计算结果以明确的数值形式提供给模型。让 LLM 去做算术题是工程上的反模式。

数据隐私在财务场景中是不可逾越的红线。公有云 API 无法满足审计要求。我们通常需要采用本地私有化部署的开源模型。7B 到 14B 参数规模的模型经过量化处理后，可以在单张消费级显卡上流畅运行。通过针对财务语料的微调，这些小模型在特定信息抽取任务上的表现可以持平甚至超越千亿参数的通用大模型。私有化部署带来了硬件采购和模型运维的额外成本，需要在项目初期进行严格的 ROI 测算。

以上

SKILLS 和 渐进式披露 是 A 家最早提出来的方案，也是 OpenClaw 火了后大家一直讨论的哪个技能好用很核心的强依赖的实现逻辑。

如果把 Claude Code 的 skills 理解成一堆 prompt 文件，后面的很多设计都解释不通。

从其源码实现来看，会发现它在解决的核心问题是：怎么让模型保留足够强的技能召回能力，同时又不把常驻上下文撑爆。

这件事说穿了就是五个字：渐进式披露。

大概的逻辑是：

• 先告诉模型「系统里存在 skills 机制」。
• 再告诉它「当前有哪些 skill 名称和简短说明」。
• 等它真的决定调用某个 skill 时，再把正文、权限、hooks、模型覆盖、附加工具权限这些重内容展开。
• 如果某些 skill 还和路径、目录、文件类型绑定，那就继续往后拖，拖到模型真的碰到对应文件时再激活。

这是一个优雅且干净的工程化设计。它没有发明一套复杂到难以维护的 skill runtime，也没有把所谓智能寄托在黑盒检索器上，而是先把「披露成本」这件事控制住。

我们按工程实现往下拆：

• skill 在系统里到底被建模成什么
• 多来源 skill 是怎么统一装配的
• 渐进式披露具体分了哪几层
• 条件激活和动态发现是怎么接进文件操作链路的
• inline 和 fork 两条执行路径分别解决什么问题
• 这套设计真正适合什么场景，代价又是什么
• 如果要在自己的 Agent 里复刻，最短落地路径应该怎么走

一、先看 skills 在系统里被建模成什么

Claude Code 里，skill 最终会被统一建模成 Command，而且类型是 prompt。

最核心的构造函数是 createSkillCommand：

return {
type: 'prompt',
  name: skillName,
  description,
  hasUserSpecifiedDescription,
  allowedTools,
  argumentHint,
  argNames: argumentNames.length > 0 ? argumentNames : undefined,
  whenToUse,
  version,
  model,
  disableModelInvocation,
  userInvocable,
  context: executionContext,
  agent,
  effort,
  paths,
  contentLength: markdownContent.length,
  isHidden: !userInvocable,
  progressMessage: 'running',
  userFacingName(): string {
    return displayName || skillName
  },
  source,
  loadedFrom,
  hooks,
  skillRoot: baseDir,
async getPromptForCommand(args, toolUseContext) {
    ...
    return [{ type: 'text', text: finalContent }]
  },
}

这段代码说明有几个关键点：

• skill 不是特殊 runtime object，而是 prompt command
• skill 本体是 getPromptForCommand() 生成的一组文本 block
• skill 可以带：
  • allowedTools
  • model
  • effort
  • paths
  • hooks
  • context: inline | fork
• skill 的调用结果，不是「执行一段脚本」，而是把 skill 展开成后续对话消息，或者 fork 成子代理执行

如果我们自己做 Agent，建议参考。skill 不要单独发明一套 DSL runtime，直接把它抽象成「可延迟展开的 prompt 命令」就够了。

二、skills 的来源有哪几类

skills 并不只来自一个目录。getSkills() 会把多个来源统一聚合。[commands.ts] commands.ts#L353-L398

const [skillDirCommands, pluginSkills] = await Promise.all([
  getSkillDirCommands(cwd)...
  getPluginSkills()...
])
const bundledSkills = getBundledSkills()
const builtinPluginSkills = getBuiltinPluginSkillCommands()

然后 loadAllCommands() 再把这些东西和 workflow/plugin/内建命令一起合并。[commands.ts] commands.ts#L445-L469

也就是说，skills 的来源至少有：

• bundled skills
• 磁盘上的 /skills/
• plugin skills
• builtin plugin skills
• 兼容旧 /commands/ 目录加载进来的 prompt commands

SkillTool 根本不需要知道 skill 来自哪里。只要最后是 prompt command，就能走统一调用路径。

三、skills 的「渐进式披露」分 5 层

1）第一层：系统提示只声明「技能机制存在」

系统提示里不会把所有 skill 正文直接塞进去。它只给一个能力声明，告诉模型：

• 用户说 /<skill-name>，其实是在指 skill
• 可以用 SkillTool 去执行
• 不要乱猜，只能调用列出来的那些

这段在 [prompts.ts] prompts.ts#L353-L401：

hasSkills
  ? `/<skill-name> (e.g., /commit) is shorthand for users to invoke a user-invocable skill. When executed, the skill gets expanded to a full prompt. Use the ${SKILL_TOOL_NAME} tool to execute them. IMPORTANT: Only use ${SKILL_TOOL_NAME} for skills listed in its user-invocable skills section - do not guess or use built-in CLI commands.`
  : null

这一步只暴露了机制，没有暴露内容。

2）第二层：只披露 skill 名称和短描述

真正给模型看的 skill 列表，是通过 getSkillToolCommands() 过滤出来的。[commands.ts] commands.ts#L561-L580

return allCommands.filter(
  cmd =>
    cmd.type === 'prompt' &&
    !cmd.disableModelInvocation &&
    cmd.source !== 'builtin' &&
    (
      cmd.loadedFrom === 'bundled' ||
      cmd.loadedFrom === 'skills' ||
      cmd.loadedFrom === 'commands_DEPRECATED' ||
      cmd.hasUserSpecifiedDescription ||
      cmd.whenToUse
    ),
)

这段有两个要点：

• 只有 prompt 命令才能进 skill 列表
• 并不是所有 prompt command 都自动暴露，至少得满足可描述性要求

也就是说，可执行集合和对模型披露集合不是完全相同的。
Claude Code 在这里收了一刀，避免模型看到一堆没有描述、无法判断用途的技能。

3）第三层：列表本身还要走预算裁剪

skill 列表不是全量原文塞进 prompt，而是按预算压缩过的。核心逻辑在 [prompt.ts] tools/SkillTool/prompt.ts#L20-L171。

最关键的常量：

export const SKILL_BUDGET_CONTEXT_PERCENT = 0.01
export const DEFAULT_CHAR_BUDGET = 8_000
export const MAX_LISTING_DESC_CHARS = 250

以及格式化逻辑：

return `- ${cmd.name}: ${getCommandDescription(cmd)}`

和预算裁剪：

if (fullTotal <= budget) {
  return fullEntries.map(e => e.full).join('\n')
}

如果超预算，就会：

• bundled skills 尽量保留完整描述
• 其它 skills 截断 description
• 极端情况下退化成只发 - skill-name

这就是很典型的渐进式披露：先给最小可用索引，不给正文。

4）第四层：列表还是增量下发，不是每轮全量重发

技能列表通过 skill_listing attachment 发给模型。发送逻辑在 [attachments.ts] utils/attachments.ts#L2669-L2752。

核心逻辑：

const newSkills = allCommands.filter(cmd => !sent.has(cmd.name))
...
for (const cmd of newSkills) {
  sent.add(cmd.name)
}
...
return [
  {
    type: 'skill_listing',
    content,
    skillCount: newSkills.length,
    isInitial,
  },
]

这个 sentSkillNames 机制说明：

• 第一次发的是初始批次
• 后面只发新增的 skill
• resume 之后还会 suppress，避免重复污染上下文

然后 messages.ts 会把它包成系统提醒。[messages.ts] utils/messages.ts#L3763-L3772

return wrapMessagesInSystemReminder([
  createUserMessage({
    content: `The following skills are available for use with the Skill tool:\n\n${attachment.content}`,
    isMeta: true,
  }),
])

很多 Agent 会每轮把所有 tools / skills 全量重发，Claude Code 显然在认真控 token。 当然，如果技能不多，也可以直接全量发，不要过早优化。

5）第五层：真正的 skill 内容延迟到调用时才展开

直到调用 SkillTool，skill 的真实正文才会通过 command.getPromptForCommand() 生成。[SkillTool.ts] utils/processUserInput/processSlashCommand.tsx#L869-L920

这里才会发生：

• $ARGUMENTS 替换
• ${CLAUDE_SKILL_DIR} 替换
• ${CLAUDE_SESSION_ID} 替换
• markdown 内嵌 shell 执行
• hooks 注册
• 附加权限 attachment 注入
• invoked skill 记录

换句话说，skill 的重内容、重权限、重上下文副作用，都是按需加载。

四、除了延迟加载，它还做了「条件激活」

这也是渐进式披露的重要一层，而且很多人会漏掉。

1）带 paths frontmatter 的 skill，不会启动即暴露

getSkillDirCommands() 里会把 skill 分成两类：[loadSkillsDir.ts] loadSkillsDir.ts#L771-L803

if (
  skill.type === 'prompt' &&
  skill.paths &&
  skill.paths.length > 0 &&
  !activatedConditionalSkillNames.has(skill.name)
) {
  newConditionalSkills.push(skill)
} else {
  unconditionalSkills.push(skill)
}

然后 conditional skills 被先放进 conditionalSkills map，而不是直接进入模型可见集合。

这意味着：

• 你定义了某个 skill 只适用于 *.tsx
• 它不会在项目启动时就干扰所有任务
• 只有模型真的碰到匹配文件时，这个 skill 才会被激活

2）激活时机挂在文件操作上

FileRead / FileWrite / FileEdit 三个工具里，都有两步副作用：

• 发现上层目录里的 .claude/skills
• 激活匹配当前文件路径的 conditional skills

比如 FileReadTool：[FileReadTool.ts] /tools/FileReadTool/FileReadTool.ts#L575-L591

const newSkillDirs = await discoverSkillDirsForPaths([fullFilePath], cwd)
...
addSkillDirectories(newSkillDirs).catch(() => {})
...
activateConditionalSkillsForPaths([fullFilePath], cwd)

对应的激活实现是 [activateConditionalSkillsForPaths] skills/loadSkillsDir.ts#L997-L1058：

const skillIgnore = ignore().add(skill.paths)
...
if (skillIgnore.ignores(relativePath)) {
  dynamicSkills.set(name, skill)
  conditionalSkills.delete(name)
  activatedConditionalSkillNames.add(name)
}

这一步非常像条件规则系统，而不是纯静态注册。
效果就是：技能集合会随着你读写哪些文件而变化。

五、动态发现本身也是渐进式披露的一部分

除了 path-conditional activation，Claude Code 还支持目录级动态发现。

1）启动时只加载一部分 skill 目录

getSkillDirCommands() 启动时会加载：

• managed
• user
• project dirs
• additional dirs
• legacy commands

但它不会把所有嵌套目录里的 .claude/skills 一次性全扫出来。[loadSkillsDir.ts] skills/loadSkillsDir.ts#L638-L804

2）当模型碰到某个文件时，再向上走目录树找嵌套 skill

discoverSkillDirsForPaths() 会从当前文件的父目录开始，一路往上走到 cwd，查找 .claude/skills。[loadSkillsDir.ts] skills/loadSkillsDir.ts#L861-L915

while (currentDir.startsWith(resolvedCwd + pathSep)) {
  const skillDir = join(currentDir, '.claude', 'skills')
  ...
  await fs.stat(skillDir)
  ...
  newDirs.push(skillDir)
}

而且还做了两个非常实用的约束：

• 已检查过的目录不会重复 stat
• gitignored 目录里的 skills 不会静默加载

这个设计让：
技能跟着你进入子目录而出现，不跟整个仓库一起一次性曝光。

六、SkillTool 的调用链，实际上分 inline 和 fork 两条路

这是技能系统和普通 slash command 最大的不同之一。

1）调用前校验

SkillTool.validateInput() 会做：

• 去掉前导 /
• 检查 skill 是否存在
• 检查是否 disableModelInvocation
• 检查是否为 prompt 类型
  见 [SkillTool.ts] tools/SkillTool/SkillTool.ts#L355-L430

关键逻辑：

const commands = await getAllCommands(context)
const foundCommand = findCommand(normalizedCommandName, commands)
...
if (foundCommand.type !== 'prompt') {
  return {
    result: false,
    message: `Skill ${normalizedCommandName} is not a prompt-based skill`,
  }
}

2）权限检查

SkillTool.checkPermissions() 很细，除了 allow / deny 规则，还会对「只有安全属性的 skill」自动放行。[SkillTool.ts] /tools/SkillTool/SkillTool.ts#L433-L579

这个设计的意义是：

• 简单 declarative skill 不必每次都弹权限
• 带额外风险属性的 skill 要 ask user

3）inline skill：展开成后续对话消息

默认分支会走 processPromptSlashCommand()。[SkillTool.ts] tools/SkillTool/SkillTool.ts#L635-L644

getMessagesForPromptSlashCommand() 干的事情很丰富：[processSlashCommand.tsx] utils/processUserInput/processSlashCommand.tsx#L827-L920

• command.getPromptForCommand(args, context) 得到真正 skill 正文
• 注册 hooks
• addInvokedSkill() 记录 skill 内容，供 compact 时恢复
• 从 skill 文本里再抽 attachment
• 增加 command_permissions attachment
• 生成一批 messages

返回结构里最关键的是：

return {
  messages,
  shouldQuery: true,
  allowedTools: additionalAllowedTools,
  model: command.model,
  effort: command.effort,
  command
}

也就是说，inline skill 的本质是：
把 skill 变成一段新的上下文和权限修饰，然后让主对话继续跑。

4）fork skill：交给子代理跑，再把结果归还

如果 skill frontmatter 里声明 context === 'fork'，就走 executeForkedSkill()。[SkillTool.ts] tools/SkillTool/SkillTool.ts#L622-L633

它会：

• 构造子代理上下文
• runAgent()
• 收集 agent messages
• 抽取结果文本
• 最终返回 { status: 'forked', agentId, result }
  见 [executeForkedSkill] /tools/SkillTool/SkillTool.ts#L122-L290

这一步说明 Claude Code 已经把 skill 分成两类：

• 知识/流程模板型 skill：inline 展开
• 工作委派型 skill：fork 子代理执行

这个值得学一下。不是所有 skill 都应该展开在主上下文里。

七、结果返回逻辑

为什么它也算渐进式披露的一部分？

1）inline skill 的 tool_result

很轻

mapToolResultToToolResultBlockParam() 对 inline skill 的返回只是：

content: `Launching skill: ${result.commandName}`

见 [SkillTool.ts] tools/SkillTool/SkillTool.ts#L857-L862

也就是说，tool_result 本身不承载 skill 的全部结果。
真正有价值的内容在 newMessages 里，已经被送回主会话继续推理。

2）fork skill 的 tool_result

直接带最终结果

fork skill 返回的是：

content: `Skill "${result.commandName}" completed (forked execution).\n\nResult:\n${result.result}`

见 [SkillTool.ts] tools/SkillTool/SkillTool.ts#L848-L855

这是因为 fork skill 已经在独立上下文里把工作做完了，主线程要拿的是总结结果。

所以在 Claude Code 里，skill 结果返回不是单一模式，而是：

• inline：返回「已加载 skill」，真正内容进主对话
• fork：返回「子代理执行结果」

这也是一种披露控制。
不同执行语义，对结果暴露方式也不同。

八、如何简要实现

一个新 Agent，如何简要实现 skills 的发现、召回、调用、结果返回？

一个够用、够短、能落地的最小设计，不追求和 Claude Code 一模一样，但核心思路一致。

1）第一步：统一 skill 数据结构

最小结构建议这样：

type Skill = {
  name: string
  description: string
  whenToUse?: string
  contentLoader: (args: string, ctx: AgentContext) => Promise<string>
  allowedTools?: string[]
  model?: string
  effort?: 'low' | 'medium' | 'high'
  context?: 'inline' | 'fork'
  paths?: string[]
}

• contentLoader 允许延迟展开
• context 决定 inline/fork
• paths 支持条件激活
• allowedTools/model/effort 支持 skill 级上下文修饰

这和 Claude Code 的 createSkillCommand() 思路是一致的。[loadSkillsDir.ts] skills/loadSkillsDir.ts#L270-L401

2）第二步：启动时只加载「索引」，不要加载正文

最简做法：

• 扫描 skills 目录
• 解析 frontmatter
• 只把 name / description / whenToUse / paths / context 放进 registry
• skill 正文不要此时进 prompt

示意：

async function loadSkillIndex(skillDirs: string[]): Promise<Skill[]> {
const skills: Skill[] = []
for (const dir of skillDirs) {
    for (const skillFile of await listSkillFiles(dir)) {
      const raw = await readFile(skillFile, 'utf8')
      const { frontmatter, content } = parseFrontmatter(raw)
      skills.push({
        name: basename(dirname(skillFile)),
        description: String(frontmatter.description ?? ''),
        whenToUse: frontmatter.when_to_use ? String(frontmatter.when_to_use) : undefined,
        paths: Array.isArray(frontmatter.paths) ? frontmatter.paths : undefined,
        context: frontmatter.context === 'fork' ? 'fork' : 'inline',
        contentLoader: async () => content,
      })
    }
  }
return skills
}

这个阶段要学 Claude Code 的不是目录细节，而是索引和正文分离。

3）第三步：做一个「未发送 skill 集合」

这是渐进式披露的核心。

维护一个 session 级状态：

type SkillDisclosureState = {
  sentSkillNames: Set<string>
}

每轮只发送新的：

function getNewSkillListings(skills: Skill[], sent: Set<string>): Skill[] {
  const fresh = skills.filter(s => !sent.has(s.name))
  for (const s of fresh) sent.add(s.name)
  return fresh
}

然后把它格式化成短列表，而不是全文：

function formatSkillListing(skills: Skill[]): string {
  return skills.map(s => `- ${s.name}: ${s.description}`).join('\n')
}

这对应 Claude Code 的 sentSkillNames + skill_listing attachment 方案。

4）第四步：把文件操作接成动态发现触发器

如果你也想要「技能跟着目录出现」，最小版本就是：

• 用户或模型读/写/改文件时
• 从文件父目录往上走到 cwd
• 看有没有 .agent/skills 或 .claude/skills
• 找到新目录就加载 skill index

示意：

async function discoverSkillDirsForFile(filePath: string, cwd: string): Promise<string[]> {
const dirs: string[] = []
let current = dirname(filePath)
while (current.startsWith(cwd + sep)) {
    const candidate = join(current, '.agent', 'skills')
    if (await exists(candidate)) dirs.push(candidate)
    const parent = dirname(current)
    if (parent === current) break
    current = parent
  }
return dirs
}

Claude Code 的现成参考是 [discoverSkillDirsForPaths] skills/loadSkillsDir.ts#L861-L915。

5）第五步：做条件激活，而不是启动时全暴露

如果 skill 定义里有 paths，就不要一开始暴露。
等碰到匹配文件时再激活：

function activatePathScopedSkills(
  pending: Skill[],
  touchedFiles: string[],
): { active: Skill[]; remaining: Skill[] } {
const active: Skill[] = []
const remaining: Skill[] = []
for (const skill of pending) {
    if (!skill.paths || skill.paths.length === 0) {
      active.push(skill)
      continue
    }
    const matched = touchedFiles.some(file => matchAny(file, skill.paths!))
    if (matched) active.push(skill)
    else remaining.push(skill)
  }
return { active, remaining }
}

这就是 Claude Code conditionalSkills -> activateConditionalSkillsForPaths() 的最小复刻。

6）第六步：调用 skill 时才真正加载正文

不要提前把 skill 正文塞到 prompt。
调用时再做：

async function invokeSkill(
  skill: Skill,
  args: string,
  ctx: AgentContext,
): Promise<SkillInvocationResult> {
const prompt = await skill.contentLoader(args, ctx)

if (skill.context === 'fork') {
    const result = await runSubAgent({
      prompt,
      allowedTools: skill.allowedTools,
      model: skill.model,
      effort: skill.effort,
    })
    return { mode: 'fork', result }
  }

return {
    mode: 'inline',
    newMessages: [
      { role: 'user', content: `[SKILL:${skill.name}]` },
      { role: 'user', content: prompt, meta: true },
    ],
    allowedTools: skill.allowedTools,
    model: skill.model,
    effort: skill.effort,
  }
}

这就是 Claude Code SkillTool.call() 的最小骨架。[SkillTool.ts] tools/SkillTool/SkillTool.ts#L581-L863

7）第七步：结果返回必须分 inline 和 fork

直接照 Claude Code 的语义分两种：

inline

• 返回一个轻 tool_result：Launching skill: xxx
• 真正内容通过 newMessages 回到主对话继续推理

fork

• 返回最终结果摘要
• 子代理对话不污染主上下文

示意：

type SkillInvocationResult =
  | {
      mode: 'inline'
      newMessages: Message[]
      allowedTools?: string[]
      model?: string
      effort?: string
    }
  | {
      mode: 'fork'
      result: string
    }

这一步是很多新 Agent 最容易偷懒的地方。
要么所有 skill 都 inline，主上下文爆炸；要么所有 skill 都 fork，失去细粒度引导。

九、小结

「skills 的渐进式披露」其实就是 Claude Code 在控制 prompt 成本和能力密度时最典型的设计之一。它真正解决的问题不是「怎么找到一个 skill」，而是「怎么在不把上下文撑爆的前提下，让模型知道自己有技能可用」。

它背后的思路：

• 先给索引
• 再给局部集合
• 再给真实正文
• 最后才给执行结果

这是一个很像搜索引擎的设计：摘要、点击、展开、消费，而不是把整本书扔给你。

以上。

OpenClaw 是最近 AI 圈最火的一个开源项目，没有之一。

从去年的 Agent 年，到今年的 AI 个人助理，OpenClaw 和去年 Manus 一样的，爆到不行，而且还是开源的版本。

由于最近自己也在做 Agent，于是也看了 OpenClaw 的代码来了解其记忆系统的实现。有一些觉得可以借鉴学习的地方。

OpenClaw 的记忆系统其实比较简单：它把「记忆」拆成了文件、索引、召回注入。

1. 「Agent 记忆系统」的定义

在 Agent 工程里，记忆是一套能力组合：

1. 持久化：跨会话保存事实、偏好、决策、未完成事项。
2. 可检索：能在需要时把相关片段拉出来，且可控预算。
3. 可注入：把召回结果以确定的结构进入模型上下文，不靠「它自己想起来」。
4. 可审计：出了错能定位「写入发生在什么时候」「召回命中了什么」「注入了哪些行」。
5. 可治理：能处理泄露风险、过期信息、重复信息、冲突信息。

OpenClaw 的实现路径非常「工程」：Markdown 作为事实源，SQLite 作为检索索引，toolResult 作为注入通道。

2. OpenClaw 的三层记忆

OpenClaw 的记忆从存储逻辑上来看可以分为三层：

2.1 会话记忆

• 介质：内存为主，但 OpenClaw 会把 session 打印成类似日志的文件，放到 sessions 目录。
• 内容：用户消息、OpenClaw 的思考过程、工具调用、skill 调用、最终回复。
• 边界：会话结束后「可用性」就不可靠了。你能在文件里回放，但模型下一次对话并不会天然带着它。

会话记忆更像「trace」。我们不能指望它解决跨会话连续性，只用它做排障、复盘、抽取素材（写入短期/长期）。

2.2 短期记忆

• 介质：磁盘，memory/YYYY-MM-DD.md 为主（参考内容给了例子 2026-03-10.md）。
• 内容：当天重要事件、过程笔记、TODO。关键点是「重要性」由人设与调教决定。
• 边界：短期记忆是追加式日志，质量会漂移。写得越多，噪声越大；但写得太少，又召回不到。

短期记忆适合承接「会话压缩之前的落盘」和「跨几天的上下文连续性」。它不是最终事实源，别把它当永久协议文档。

2.3 长期记忆

• 介质：工作区根目录 MEMORY.md（参考内容明确）。
• 内容：核心认知与关系、偏好风格、长期目标、进行中任务、关键事件/教训/决策。
• 边界：参考内容强调「只在主会话加载」，群聊等任务不加载，避免泄露。

MEMORY.md ==「可执行的组织记忆」。它的价值不在于「写得多」，在于「冲突少、可被召回、能约束后续行为」。这层要治理，要像维护配置一样维护。

3. OpenClaw 的文件布局

3.1 「会话快照」文件

快照文件主要是解决 /new、/reset 指令的断片

session-memory 的 Hook 会在你执行 /new 或 /reset 前，把上一会话最近 N 条对话（默认 15 条）抽出来，写成一个 Markdown 文件放到 workspace/memory/ 下。

• 命名：YYYY-MM-DD-<slug>.md，slug 通常由 LLM 根据主题生成；LLM 不可用就回退成 HHMM。
• 关键点：这种文件也会被检索索引到。原因是 listMemoryFiles() 会递归扫描 workspace/memory/ 下所有 .md，并不要求必须是 YYYY-MM-DD.md（ src/memory/internal.ts:115-145 ）。

这个机制对「人类工作流」很友好。很多团队的真实使用是：今天临时开了个话题，明天又忘了开在另一个会话里。会话快照能把碎片变成可检索素材，后面再沉淀进 MEMORY.md。

3.2 memory/main.sqlite：索引库

• memory/main.sqlite 基本可以确定是「记忆搜索（memory_search）」用的 SQLite 索引库。
• 索引对象：MEMORY.md、memory/**/*.md，以及你配置的 extraPaths，可选 session transcripts。
• 检索方式：FTS/BM25 关键词检索 +（可选）向量相似度检索（sqlite-vec）。
• 它存的典型结构：files、chunks、embedding_cache，以及可选的 FTS 表、向量虚表。

事实源是文本文件，索引是可重建的派生物。索引坏了你删掉重建就行；事实源坏了才是真的坏。

4. 怎么建索引：

建索引我们关心的三件事：增量、去重、成本

OpenClaw 的索引构建不是「每次全量重算」，也不是「精细 diff」：

• 更新粒度：按文件做增量。文件没变直接跳过。
• 分块粒度：文件变了就重建该文件 chunks。
• 向量成本：chunk embedding 通过缓存复用，避免重复调用 embedding provider。

4.1 扫描哪些文件会进索引

OpenClaw 会递归扫描 workspace/memory/ 下所有 .md，并包含 MEMORY.md/memory.md。对应定位是 src/memory/internal.ts:115-145。

4.2 文件级 hash：没变就跳过

文件 hash 的策略：

• Markdown：hash = sha256(content)（internal.ts:L245-L263）
• 多模态：buffer 也会 hash，最后把 {path, contentText, mimeType, dataHash} 做 JSON 再 sha256（internal.ts:L204-L243）
• 增量判定：对比 files 表里的 hash，一致就跳过（参考内容列了 memory 文件与 session 文件两条路径）。

hash 是增量的核心。它的意义不止省时间，还省钱：embedding provider 往往是计费点。这种主要是对于使用第三方 embedding 的。

4.3 分块策略：tokens*4 的字符近似

chunkMarkdown() 的策略：

• maxChars = tokens * 4，overlapChars = overlap * 4
• 以「行」为主，超长行会被切段
• 每块生成 hash=sha256(text)，并有 embeddingInput

tokens*4 这种近似在工程里挺常见，优点是简单、稳定、跨模型大差不差。缺点也明显：

• 语言差异会影响 token/char 比例；中英文混排时 chunk 尺寸会漂。
• 以行切块对 Markdown 友好，但对「一行很长的 JSON 或日志」不友好。

可以盯两个指标来调 chunking：

1. 平均召回 snippet 的「可读性」和「自洽性」；
2. SQLite 体积与索引更新耗时。chunk 太小召回碎，太大注入贵。

4.4 chunk 的唯一标识与 upsert

去重靠 id，chunk 写入策略如下：

• chunk id：sha256("${source}:${path}:${startLine}:${endLine}:${chunk.hash}:${provider.model}")
• 同一 id：ON CONFLICT(id) DO UPDATE 覆盖更新
• 文件要重建时会先清旧再写新（参考内容总结了「清旧再写新」语义）

这里有个很实际的 trade-off：

• 它不做「chunk diff」，所以文件变了就重建该文件 chunks，逻辑简单，坏处是 IO 多。
• 但 embedding 通过缓存复用，把最贵的部分压下去了。

另外，id 里带了 provider.model，这会带来一个工程后果：embedding 模型换了，chunk id 会变，索引层面等价于全量重建。 provider/model/providerKey 变化会触发 full reindex。

4.5 embedding_cache

embedding 缓存的主键设计：

• 主键：(provider, model, provider_key, hash)
• provider_key 会把 endpoint/headers 等纳入指纹，避免跨配置污染缓存（而且会剔除授权头的细节在参考内容里提到）。
• 批量加载命中就跳过 embed；miss 才请求，成功回写缓存（对应 manager-embedding-ops.ts 的行段）。

这是「上线能用」的关键。否则就会遇到一个很尴尬的情况：
索引更新频繁触发 embedding 重算 → 延迟抖动 → API 费暴涨 → 还可能被 provider 限流。 system prompt 的 skills 段落甚至提醒「假设有 rate limits，避免 tight loop」，这就有点被打过之后写进规范的味道。

5. 更新怎么触发

watch、interval、onSearch、session-delta

索引更新如果做得「过勤」，会把 CPU 和 IO 吃满；做得「过懒」，召回就是过期的。OpenClaw 在触发上给了多条路径：

1. watch：chokidar 监听 MEMORY.md、memory.md、memory/**/*.md（以及 extraPaths、多模态扩展），变更标记 dirty，debounce 后 sync(reason="watch")。
2. interval：sync.intervalMinutes>0 就 setInterval 定时跑。
3. onSessionStart：search 前 warmSession(sessionKey)，若开了 sync.onSessionStart，每个 sessionKey 首次触发后台 sync。
4. onSearch：search 时如果 dirty 且开了 sync.onSearch，后台触发 sync。
5. session-delta：监听 transcript 更新，累计新增 bytes/lines，达到阈值后把相关 session 文件标脏，再 sync。

还有两点：

• 单飞锁：同一时刻只跑一个 sync，复用同一个 Promise（参考内容定位 manager.ts:452-467）。
• 全量重建的原子 swap：写到 .tmp-UUID，完成后 swap（含 wal/-shm），避免半成品索引（参考内容定位 manager-sync-ops.ts:1050-1158）。

6. 召回是怎么发生的

主要看 buildMemorySection() 的代码，因为它把策略写死了：

提示词：
function buildSkillsSection(params: { skillsPrompt?: string; readToolName: string }) {
  const trimmed = params.skillsPrompt?.trim();
  if (!trimmed) {
    return [];
  }
  return [
    "## Skills (mandatory)",
    "Before replying: scan <available_skills> <description> entries.",
    `- If exactly one skill clearly applies: read its SKILL.md at <location> with \`${params.readToolName}\`, then follow it.`,
    "- If multiple could apply: choose the most specific one, then read/follow it.",
    "- If none clearly apply: do not read any SKILL.md.",
    "Constraints: never read more than one skill up front; only read after selecting.",
    "- When a skill drives external API writes, assume rate limits: prefer fewer larger writes, avoid tight one-item loops, serialize bursts when possible, and respect 429/Retry-After.",
    trimmed,
    "",
  ];
}

function buildMemorySection(params: {
  isMinimal: boolean;
  availableTools: Set<string>;
  citationsMode?: MemoryCitationsMode;
}) {
  if (params.isMinimal) {
    return [];
  }
  if (!params.availableTools.has("memory_search") && !params.availableTools.has("memory_get")) {
    return [];
  }
  const lines = [
    "## Memory Recall",
    "Before answering anything about prior work, decisions, dates, people, preferences, or todos: run memory_search on MEMORY.md + memory/*.md; then use memory_get to pull only the needed lines. If low confidence after search, say you checked.",
  ];
  if (params.citationsMode === "off") {
    lines.push(
      "Citations are disabled: do not mention file paths or line numbers in replies unless the user explicitly asks.",
    );
  } else {
    lines.push(
      "Citations: include Source: <path#line> when it helps the user verify memory snippets.",
    );
  }
  lines.push("");
  return lines;
}

工具描述：
 label: "Memory Search",
    name: "memory_search",
    description:
      "Mandatory recall step: semantically search MEMORY.md + memory/*.md (and optional session transcripts) before answering questions about prior work, decisions, dates, people, preferences, or todos; returns top snippets with path + lines. If response has disabled=true, memory retrieval is unavailable and should be surfaced to the user.",
    parameters: MemorySearchSchema,

有三点：

1. 触发条件写得具体：prior work / decisions / dates / people / preferences / todos。模型不需要猜「算不算记忆相关」。
2. 两阶段召回：先 memory_search 找片段，再 memory_get 精读少量行，控制注入体积。
3. 引用策略可控：citationsMode 可以关掉，避免模型动不动把路径行号甩出来（对产品形态很重要）。

两阶段召回比「一次性把相关文件 wholefile 塞进去」靠谱太多。

7. 召回结果怎么进上下文

toolResult 消息是关键通道

很多人以为「记忆」是把内容写进 system prompt。OpenClaw 不是这么干的。

召回结果会以工具执行结果的形式进入会话消息列表，后续模型调用自然「看得到」。

• 工具返回会被包装成 JSON 文本块（参考内容定位 jsonResult() 在 src/agents/tools/common.ts:230-239）。
• tool 返回会被标准化成 content[] + details（参考内容定位 src/agents/pi-tool-definition-adapter.ts 的 normalize）。
• 这些 toolResult 会被追加到 session messages，下一次模型调用会携带。

这条通道对排障非常友好：我们可以在 transcript 里看到「这次回答之前它到底召回了什么」。而且 toolResult 天然可控预算、可控格式，比让模型把记忆揉进自由文本稳得多。

8. 写入时机

8.1 会话快照写入

人为触发的「切会话」

当执行 /new、/reset 时，上一段会话尾部会被抽取成 YYYY-MM-DD-<slug>.md。这是「防断片」写入，价值是保住最近上下文。

坑：

• 抽取的 N 条对话里可能包含敏感信息。它会落在 memory/，并进入索引。
• 如果你把 workspace 目录同步到团队共享盘或提交到 repo，泄露面会扩大。

我们的做法：

• 明确区分「个人 workspace」和「团队 workspace」。个人的 memory/ 默认不进 repo。
• 开启 citations 时，产品侧要想清楚是否允许暴露路径与行号。

8.2 短期记忆写入

「需要我们调教，告诉她哪些重要」。

短期记忆要走「稀疏高密度」路线：条目少，但每条都能在未来的某个问题上直接复用。写入策略要围绕「将来会搜什么」来定，不要围绕「当下发生了什么」来记流水账。

8.3 长期记忆更新

心跳 / AGENTS.md / cron

三种更新机制：心跳、核心流程、cron。

读最近几天短期记忆 → 选值得长期记住的 → 提炼写入 MEMORY.md。

观点：

• cron 最稳，可观测、可控、可回滚。
• 心跳更新很容易在负载高时抖动，或者在你最不想更新的时候更新。
• 把它塞进核心流程（AGENTS.md）要谨慎，一旦每次任务都触发提炼，会把延迟拉上去。

一般做法：

• 工作日每天固定一次 consolidation（cron）。
• 遇到重大决策或事故复盘，当天手动提炼写入 MEMORY.md，不等自动化。

9. 怎么「调教」

把记忆当成协议，不当成日记

「告诉她哪些重要」。把「重要」拆成几类，每类有明确写入规则，避免模型自由发挥。

一般的规则：

1. 稳定偏好：例如输出格式偏好、技术栈偏好、代码风格偏好。
2. 组织事实：团队结构、系统边界、核心服务依赖、环境约束。
3. 关键决策：ADR 级别的决策，包含时间点与理由。
4. 长期目标与在途事项：能跨周追踪的，不写「今天要做的」。
5. 事故教训：明确到「哪个坑踩过」「如何避免」。

短期记忆（memory/YYYY-MM-DD.md）会允许更多过程性信息，但要满足一个条件：未来能被搜索问题命中。比如你写「今天讨论了 A」，基本没用；你写「决定 A 的原因是 B，后续若出现 C 用 D 回滚」，会有用一些。

如果希望 memory_search 在关键时刻召回到正确内容，就得用「未来的查询语句」来写记忆。

以上。

行业 Agent 是要能解决问题的，而查资料只是其中一步，后面还要做判断、走流程、调用系统、校验结果、留痕、可回放。

RAG 在这里的角色也变了：它不只是给模型喂上下文，而是给 Agent 提供可执行任务所需的依据、约束、参数和证据链。

今天我们聊一下行业 Agent 构建过程中的 RAG 怎么写，从目标、数据，检索以及使用 RAG 等等方面。

1. 行业 Agent 的 RAG 要服务什么能力

行业 Agent 常见的工作方式是「多步闭环」：

1. 识别问题类型与业务对象（客户、设备、合同、工单、订单、项目、账号等）
2. 查依据（制度、手册、知识库、历史工单、标准、接口文档）
3. 做动作（查系统、下发指令、开通配置、生成工单、发邮件、写报告、提审批）
4. 校验与回写（确认变更成功、回填字段、留痕、把引用/证据挂到工单）
5. 解释（给用户说明依据、影响范围、回滚方案、下一步建议）

所以行业 Agent 的 RAG 不只是「问答检索」，而是至少要覆盖这些信息类型：

• 规则依据：制度、条款、SOP、合规模板、变更规范
• 操作依据：系统使用手册、接口文档、参数含义、错误码处理
• 对象事实：来自业务系统的实时/准实时数据（用户信息、资源状态、库存、账单、设备状态）
• 历史经验：工单处理记录、故障复盘、已知问题（KEDB）
• 风险边界：禁用操作清单、权限范围、需要人工复核的条件

如果我们只做「文档向量库 + 生成」，Agent 走到第 3 步就会卡：它不知道该调用哪个系统、需要哪些字段、什么情况下要停下来让人确认，也不知道怎么证明自己做对了。

2. 指标

行业 Agent 场景里，最好用三类指标描述：

2.1 任务完成类指标

• 任务成功率（最终动作成功并通过校验）
• 平均完成时长（端到端）
• 人工介入率（需要人确认/补充信息/兜底）
• 回滚率（执行后需要撤销/修正）

2.2 风险类指标（红线不能过）

• 越权率（检索/执行是否越权，目标是 0）
• 误执行率（不该执行却执行）
• 误答导致的错误操作（把“编出来的依据”当成执行依据）
• 引用不可追溯率（给不出来源或来源不支持结论）

2.3 知识与检索类指标（用于驱动迭代）

• 依据命中率（标准依据是否出现在 topK）
• 冲突处理正确率（新旧版本/多来源冲突时是否选对）
• 时效正确率（是否引用过期/废止内容）
• 覆盖率（高频问题是否覆盖）

行业 Agent 的 RAG 设计，最终要对这些指标负责。否则我们会陷入「答得像那么回事，但不敢让它动系统」的状态。

3. 数据层

行业 Agent 的 RAG，数据比模型更重要。

3.1 三类数据

1. 静态权威知识：制度、规范、手册、标准、产品文档
   目标：可追溯、版本可控、可引用
2. 动态业务事实：来自业务系统的数据（CRM、工单、CMDB、监控、计费、IAM 等）
   目标：可校验、可审计、最好可回放（至少保留查询快照）
3. 过程与经验：历史工单、故障复盘、处理记录、FAQ 演进
   目标：可过滤（质量参差）、可分级（权威/经验/猜测）

很多项目失败是因为把第 3 类当第 1 类用，把「经验」当「制度」。Agent 一旦据此去执行动作，风险会放大。

3.2 每个知识片段必须带的元数据

行业 Agent 需要的不只是「能搜到」，还要「能用来做动作」。建议每个 chunk 至少包含：

• doc_id / chunk_id
• source（系统/库）
• source_url（可点击或可定位）
• title_path（标题链）
• doc_type（制度/手册/接口文档/复盘/工单等）
• version、status（草稿/已发布/已废止）
• effective_from / effective_to（能给就给）
• owner（维护人/团队）
• updated_at
• 适用范围标签：产品线/地区/客户/机型/环境（生产/测试）
• 权限标签：RBAC/ABAC 所需字段
• 可执行性标签（建议加）：
  • 是否可作为执行依据（例如制度/已发布 SOP 才能）
  • 是否需要人工复核（高风险操作）
  • 是否仅供参考（复盘/经验）

这些标签对 Agent 比较关键：它能决定「能不能做、要不要停、怎么解释」。

3.3 文档解析与切分

行业 Agent 的 RAG 的切分策略，优先级一般是：

1. 按结构切：章/节/条款/接口字段说明/错误码条目
2. 把“前置条件/限制/例外”跟规则放一起
3. 表格与字段定义要保表头（字段含义脱离表头就没法用）
4. 把可执行步骤单独成块（SOP、Runbook、变更步骤）

注意：不要把「定义」「适用范围」「例外条款」切碎。Agent 执行动作时，最需要的就是边界条件和限制。

4. 索引与检索

行业 Agent 和常规的 Agent 不同，其更依赖于「过滤 + 排序 + 证据链」

4.1 使用混合检索

行业 Agent 的查询里会出现大量「硬信息」：

• 条款号、标准号、型号、错误码、参数名、接口路径、工单号、配置项名

纯向量在这些场景不稳。工程上更常用的是：

• 关键词/BM25：抓编号、术语、字段名、错误码
• 向量召回：抓语义相近、同义表达
• 融合 + 重排：把候选集排序成「最能支持动作/结论」的那几段

4.2 检索要先过滤，再找相似

行业 Agent 的过滤通常是强约束，如下：

• 权限过滤（用户/角色/租户/数据域）
• 状态过滤（废止、草稿默认不进）
• 生效时间过滤（尤其制度、计费、合规）
• 适用范围过滤（产品/地区/环境）
• 数据域隔离（内部/客户侧/合作方）

如果我们把这些留到生成阶段「让模型自己注意」，效果不可控，风险也不可控。

4.3 Agent 专用检索

不止检索答案，还要检索工具与参数

行业 Agent 经常需要两类额外检索：

1. 工具检索（Tool RAG）
   从「工具说明库/接口文档/SOP」里检索：该用哪个工具、需要哪些参数、有哪些限制、失败怎么处理。
2. 参数与字段检索（Schema RAG）
   从「数据字典/字段说明/枚举值」里检索：字段含义、可选值、校验规则、示例格式。

这两类检索的结果不一定直接展示给用户，但会决定 Agent 能不能把动作做对。

5. 固化 Agent 使用 RAG 的逻辑

行业 Agent 的 RAG 关键是要「把 RAG 插进决策点」

行业 Agent 常见的内部循环大致是：

• Plan（决定下一步做什么）
• Act（调用工具/检索/执行）
• Observe（拿到结果）
• Decide（是否继续、是否需要人确认、是否结束）
• Explain（对外输出）

RAG 的插入点建议固定成三处：

5.1 决策前

用 RAG 找「规则边界」

在 Agent 做出关键决策前，先检索：

• 是否允许执行（权限、合规、风险等级）
• 前置条件是什么（必须具备哪些信息、哪些系统状态）
• 需要的审批/确认是什么（是否必须人工确认）

这一步的输出的是「约束」，不是「答案」。它会影响下一步是继续、暂停还是转人工。

5.2 执行前

用 RAG 找「操作步骤与参数」

执行某个动作前，检索：

• SOP / Runbook / 接口文档
• 必填参数、参数来源
• 校验方式（执行后如何确认成功）
• 回滚方式（失败/异常如何撤销）

这一步的输出是「可执行步骤」，不是「解释性段落」。

5.3 执行后

用 RAG 做「结果判定与错误处理」

拿到工具返回值后，检索：

• 错误码含义与处理建议
• 常见失败原因
• 是否需要升级/转人工
• 是否需要二次校验（比如跨系统一致性）

这一步的输出是「下一步动作建议 + 证据」。

6. 生成与输出

行业 Agent 的输出要分层，不要把所有东西都写给用户

行业 Agent 的输出建议拆成三层，分别服务不同目标：

1. 用户层：结论/进展、需要用户补充什么、下一步怎么走
2. 证据层：引用依据（链接、页码、版本、生效日期）
3. 执行层（留痕层）：本次调用了什么工具、参数摘要、返回结果摘要、校验结果、回滚点

用户不一定要看到执行层细节，但系统必须存储这些内容。只有出了问题能回放，才敢放权。

同时，行业 Agent 的生成要有硬规则：

• 没有命中权威依据：不输出肯定结论
• 有冲突：必须把冲突来源、版本、生效时间写清楚
• 涉及高风险动作：必须停下来请求确认（并把依据与影响范围给出来）
• 引用必须来自检索上下文：不允许来虚的，「凭印象补一句」

7. 权限、审计、隔离

**行业 Agent 的 RAG 必须「检索前隔离」。

行业 Agent 一旦能调用系统，风险比问答高一个量级。权限要分两层：

7.1 知识权限

能不能看的问题

• 文档/知识片段按 ABAC/RBAC 做过滤
• 按租户隔离（多客户必做）
• 按数据域隔离（内部策略、客户信息、合作方信息）

7.2 行为权限

能不能做的问题

• 工具级权限：这个角色能调用哪些工具
• 动作级权限：同一工具下哪些操作允许（例如只读查询 vs 修改/下发）
• 参数级权限：同一动作下哪些资源范围允许（例如仅能操作自己负责的项目/客户）

很多团队只做了「知识权限」，没做「行为权限」。

这会导致不放心，即使 Agent 能查到 SOP，也能学会「怎么做」，但你又不敢让它真的做。

7.3 审计要能回答四个问题

• 为什么这么做（依据是什么）
• 做了什么（调用了哪些工具、关键参数是什么）
• 得到了什么（返回结果与校验结果）
• 谁批准的（如果需要人工确认）

没有这四个问题的答案，行业 Agent 很难通过安全审查，也很难在出事后定位责任与修复点。

8. 灰度上线策略

先控制风险，再谈覆盖率

行业 Agent 的上线节奏建议按权限逐步放开：

1. 只读 Agent：只检索、只解释、只给建议，不执行任何写操作
2. 半自动 Agent：可以生成“执行计划/工单草稿/变更单草稿”，必须人工确认后执行
3. 受限自动 Agent：只允许低风险、可回滚、可校验的动作自动执行（例如查询、对账、生成报表、创建工单、补全字段）
4. 高风险动作：默认保留人工确认，除非你能做到严格的权限、校验、回滚、审计，并且有明确的责任边界

上线必须准备三套兜底：

• 超时与降级：检索失败/重排失败/模型失败时怎么退化
• 失败回滚：执行失败怎么撤销，撤销失败怎么升级
• 人工接管：在关键节点能一键转人工，并把证据与执行轨迹带过去

9. 常见坑

1. 把「经验工单」当「标准答案」：Agent 会把偶发处理当成通用规则。必须分级与降权。
2. 只做知识库，不做数据字典与工具库：Agent 会不知道参数怎么填、字段是什么意思、错误码怎么解。
3. 只做检索，不做执行前校验与执行后校验：敢执行的前提是可校验、可回滚。
4. 权限只管文档，不管工具：最容易在这里翻车。
5. 没有回放评测：你不知道一次小改动会不会让 Agent 在某个分支上开始乱走。
6. 把「多轮对话」当「任务编排」：行业 Agent 的关键是状态机与决策点，不是聊得多。

最后，行业 Agent 的 RAG 如果要构建，不仅仅是算法的事情，需要更多的业务专家，业务 Owner 来直接参与，他们才是最懂行业的人。需要他们来定义「什么算答对/答错」、哪些文档权威、版本如何取舍、哪些内容不能答。

以上。

对于一个与大型语言模型（LLM）打过交道的开发者来说，上下文管理都是一个绕不开的核心问题。它不仅决定了 AI 的智能程度，也直接关系到系统的性能和成本。

上周研究了各家 Agent 系统的实现，各家的上下文管理策略都不相同。最简单最傻的策略是一个不断累加对话历史，这种策略很快就会遇到 Token 限制和 API 的成本问题。

如果你是一个技术负责人，或者正在开发 AI Agent 相关的产品，需要在性能和成本之间找到平衡点，这篇文章应该对你有一些帮助。

今天所聊的内容是基于对 Claude Code、Manus、Gemini CLI，OpenManus 等多个项目的分析，以及自己在实践中的一些思考。

为什么要做上下文管理？

最新的 LLM 现在提供 128K Token 或更多的上下文窗口。听起来还挺多的，但在真实世界的 Agent 场景中，这通常远远不够。

尤其是当 Agent 与网页或PDF等非结构化数据交互时，Token 数需求会爆炸。

并且，随着 Token 数的增加，模型性能会在超过一定长度后明显下降，这就像让一个人同时记住一本书的所有细节，理论上可能，实际上很难做好。

就算我们的大模型有更多的窗口上下文支持，成本也是一个需要考虑的问题，就算有前缀缓存这样的优化，但传输和预填充每个 Token 都是要付费的。

为了解决这些问题，许多团队选择了压缩策略。但过度激进的压缩不可避免地导致信息丢失。

这个问题的本质在于 Agent 必须根据所有先前状态预测下一个动作——而我们无法可靠地预测哪个观察结果可能在十步之后变得至关重要。从逻辑角度看，任何不可逆的压缩都带有风险。

接下来我们看一看各项目的上下文管理策略，看看从中能否给到各位看官一些启发。

OpenManus 的上下文管理策略

OpenManus 采用了一个相对简单直接的上下文管理方案，主要特点是：

1. 轻量级消息列表机制

• 使用固定长度（默认100条）的消息列表作为内存存储
• 采用简单的 FIFO（先进先出）策略，超出限制时截断最早的消息
• 没有智能的上下文压缩或摘要机制

2. Token 限制处理

• 实施硬性 token 检查，超限直接抛出异常终止
• 缺乏优雅的降级策略或自适应窗口裁剪
• 在长对话或工具密集场景中容易触碰上限

虽然上下文管理比较简单，但是 OpenManus 为不同使用场景提供了定制化的上下文处理，如浏览器场景会动态注入浏览器状态，截图保存等

总的来说，这是一个原型实现，并不适合作为生产级环境使用，如果要上到生产环境需要自行做精细化的处理和架构。

Manus 的上下文管理策略

Manus 没有开源，但是其官方有发一篇文章出来。

Manus 采用了一种创新的方法：将文件系统作为终极上下文存储，而不是依赖传统的内存中上下文管理。

文件系统作为存储有如下的核心特性：

• 无限容量：文件系统大小不受限制
• 天然持久化：数据自动保存，不会丢失
• 直接操作：智能体可以主动读写文件
• 结构化记忆：不仅是存储，更是结构化的外部记忆系统

相对于传统的将完整的观察结果保存在上下文中，容易超限，Manus 实现了可恢复的信息压缩：

• 观察结果指向外部文件（Document X, File Y）
• 上下文中只保留引用，不保存完整内容
• 需要时可以从文件系统恢复完整信息

具体实现：

• 网页内容可从上下文移除，只保留 URL
• 文档内容可省略，只保留文件路径
• 实现上下文压缩的同时不会永久丢失信息

Manus 团队认为，如果状态空间模型能够掌握基于文件的记忆管理：

• 将长期状态外部化而非保存在上下文中
• SSM 的速度和效率优势可能开启新型智能体
• 基于 SSM 的智能体可能成为神经图灵机的真正继任者

与 OpenManus 的简单消息列表管理，Manus 的方案更加成熟：

• OpenManus：固定长度消息列表，硬性截断，缺乏智能管理
• Manus：文件系统作为无限外部记忆，可恢复压缩，主动记忆管理

Claude Code 的上下文管理

Claude Code 没有开源代码，但是国外有大神反编译其源码（虽然大神自己说:这并非真正意义上的反编译或逆向工程尝试，而更像是对 Claude 团队杰出工作的致敬。）

地址：southbridge-research.notion.site/claude-code…

通过反编译内容的分析，可以大概了解一些其策略和比较巧妙的点：

TodoWrite 工具

Claude Code 引入 TodoWrite 工具，支持模型主动维护自己的 To-Do 列表，替代传统的多 Agent 分工策略。

其优势：

• 专注：Prompt 中反复提醒模型参考 ToDo，始终聚焦目标。
• 灵活：「交错思考」机制使得 ToDo 可动态增删。
• 透明：用户可实时查看计划与进度，提高信任度。

Token 统计的反向遍历

Toke 统计从后往前查找这个细节相当精妙。大部分系统都是傻乎乎地从头遍历，但 Claude Code 意识到了一个关键事实：Token 使用情况的统计信息总是出现在最新的 assistant 回复里。这种”知道去哪找”的优化思路，把原本可能的 O(n) 操作优化到了 O(k)，在高频调用场景下，这种优化带来的性能提升是指数级的。

92% 阈值

留 8% 的缓冲区既保证了压缩过程有足够的时间完成，又避免了频繁触发压缩带来的性能开销。更重要的是，这个缓冲区给了系统一个”反悔”的机会——如果压缩质量不达标，还有空间执行降级策略。

8 段式结构化摘要

Claude Code 的 8 段式结构特别值得借鉴：

1. Primary Request and Intent - 主要请求和意图

2. Key Technical Concepts - 关键技术概念

3. Files and Code Sections - 文件和代码片段

4. Errors and Fixes - 错误和修复

5. Problem Solving - 问题解决过程

6. All User Messages - 所有用户消息

7. Pending Tasks - 待处理任务

8. Current Work - 当前工作状态

优雅降级

当压缩失败时，系统不会死板地报错或者强行应用低质量的压缩结果，而是有一整套 Plan B、Plan C。从自适应重压缩，到混合模式保留，再到最后的保守截断——每一步都在努力保护用户体验。这种”永不放弃”的设计理念，让系统在各种极端情况下都能稳定运行。

向量化搜索

长期记忆层引入向量搜索，实际上是在为 AI 构建一个”联想记忆”系统。当用户提出新问题时，系统不仅能看到当前对话，还能”回忆”起过去处理过的类似问题。这种跨会话的知识迁移能力，让 Claude Code 从一个简单的对话工具进化成了一个真正的智能编程助手。

Gemini-cli 的上下文管理

Gemini-cli 的上下文管理走了一条和 Claude Code 相似但更加轻量的路线。它的核心理念很简单：文件系统就是天然的数据库。

三层混合存储架构

与 Claude Code 类似，Gemini-cli 也采用了分层设计，但实现更加简洁：

第一层：纯内存工作区

• 存储当前会话的聊天历史、工具调用状态、循环检测状态
• 零延迟访问，不涉及任何 I/O 操作
• 会话结束即清空，不留痕迹

第二层：智能压缩层

• 触发阈值：70%（比 Claude Code 的 92% 更保守）
• 保留策略：最新 30% 的对话历史
• 压缩产物：5 段式结构化摘要

第三层：文件系统持久化

• 全局记忆：~/.gemini/GEMINI.md
• 项目记忆：向上递归查找直到项目根目录
• 子目录上下文：向下扫描并尊重忽略规则

70/30

Gemini-cli 选择了 70% 作为压缩触发点，30% 作为保留比例。这个比例设计很有讲究：

为什么是 70% 而不是 92%？

• 更早介入，避免紧急压缩导致的卡顿
• 给压缩过程留出充足的缓冲空间
• 适合轻量级应用场景，不追求极限性能

30% 保留的合理性

• 刚好覆盖最近 5-10 轮对话
• 足够维持上下文连续性
• 不会让用户感觉”突然失忆”

5 段式压缩：够用就好

相比 Claude Code 的 8 段式结构，Gemini-cli 的压缩更简洁：

1. overall_goal - 用户的主要目标

2. key_knowledge - 重要技术知识和决策

3. file_system_state - 文件系统当前状态

4. recent_actions - 最近执行的重要操作

5. current_plan - 当前执行计划

忽略规则

Gemini-cli 的 .geminiignore 机制是个亮点：

独立但兼容

• 可以单独在非 git 仓库中生效
• 与 .gitignore 并行工作，互不干扰
• 每个工具都有独立的忽略开关

明确的约束

• 修改 .geminiignore 需要重启会话才生效
• 这不是 bug，而是 feature——避免运行时状态混乱

Gemini-cli 的设计哲学可以总结为：不求最优，但求够用。

它没有追求理论上的完美压缩比，也没有搞复杂的向量检索，而是用最简单的方案解决了 80% 的问题。这种务实的态度在工程实践中往往更受欢迎——系统简单意味着 bug 少，维护容易，用户上手快。

特别是”文件系统就是数据库”这个理念，虽然听起来有点”土”，但在实际使用中却异常可靠。你不需要担心数据库挂了、连接断了、事务死锁了…文件就在那里，看得见摸得着，出了问题 cat 一下就知道怎么回事。

这种设计思路值得很多过度工程化的项目学习：有时候，简单就是最好的复杂。

小结

上下文是智能的边界，压缩是性能的艺术。

在与大型语言模型打交道的过程中，上下文管理已成为决定智能上限与系统稳健性的关键。虽然现代 LLM 提供了百万级 Token 的窗口，但在实际 Agent 场景中，这远远不够，尤其当涉及非结构化数据（如网页、PDF）时，Token 使用会迅速膨胀。即使有前缀缓存等机制，成本与性能的双重压力仍然存在。因此，上下文压缩成了必选项——但压缩得太激进，又会导致信息丢失，损害 Agent 的决策能力。

聪明的系统不是记住所有，而是记住该记住的。

应对上下文限制的最佳方式不是简单保留或截断历史，而是构建一个具备“记忆力”的智能系统。Claude Code 以三层记忆架构为核心（短期、高速；中期、结构化压缩；长期、跨会话向量化搜索），同时引入 TodoWrite 工具，让模型自我管理计划任务。这使得 Agent 能专注目标、灵活调整、透明运行，形成类人思维般的任务记忆系统。关键机制如 Token 反向遍历、92% 阈值缓冲、8段式摘要结构与优雅降级策略，共同打造了一个稳健又高效的上下文生态。

工程的智慧在于‘够用’，而非‘极致’。

对比 Gemini-cli、OpenManus 与 Manus 的上下文策略，可以看出不同系统在工程实现上的取舍哲学。Gemini-cli 采用实用主义的轻量分层设计，70/30 压缩策略既简单又高效，让用户可控又无需担心性能瓶颈；Manus 则大胆将文件系统作为智能体的“外部大脑”，通过引用而非存储规避 Token 限制；而 OpenManus 则为最小可运行原型提供了基础模板。这些方案展现出一个共识：上下文不一定要复杂，关键在于是否服务于目标。

以上。

最近一年，Multi-Agent 系统持续发热发烫，融资不断，火了起来。

从 AutoGPT 到 MetaGPT，从 CrewAI 到 LangGraph，各种多代理框架层出不穷。国内现象级的 Manus，以及当天由 MetaGPT 的同学开源的 OpenManus。OpenAI 的 Swarm、微软的 AutoGen，还有 Anthropic 的 Claude Code，每个大厂都在探索自己的 Multi-Agent 方案。GitHub 上相关项目的 Star 数动辄上万，社区讨论热度持续攀升。

从这股热潮，我们可以看出 AI 应用的一个重要趋势：从单一模型调用走向多智能体协作。就像软件开发从单体应用演进到微服务架构，AI 系统也在探索如何通过多个专门化的 Agent 协同工作，完成更复杂的任务。

当我们仔细观察这些 Multi-Agent 系统的架构时，会发现一个规律：

MetaGPT 里有个产品经理角色，负责协调其他工程师角色；AutoGen 支持 Manager-Worker 模式；Claude Code 更是明确采用了主循环引擎加子任务代理的设计。在 OpenAI Swarm 中，也能看到 Orchestrator Agent 的影子。

这些系统都采用了某种形式的「主从」架构——有一个 Agent 负责全局协调，其他 Agent 提供专门化支持。

为什么？巧合吗？

今天我们就聊聊 Multi-Agent 系统的主从架构。从大模型的底层原理开始。

1 从大模型的原理说起

1.1 大模型的「注意力」机制

要理解为什么需要主从架构，得先理解大模型是怎么「思考」的。

大模型的核心是 Transformer 架构，而 Transformer 的灵魂是注意力机制（Attention）。简单来说，模型在生成每个 token 时，会「注意」到输入中的所有相关信息（上下文窗口内），然后综合这些信息做出决策。

这里有个关键点：大模型的每次决策都是基于它能「看到”」的全部上下文。

这就像你在做一道数学题。如果题目是”小明有 5 个苹果，给了小红 2 个”，你要回答”小明还剩几个”，你必须同时看到”5 个”和”给了 2 个”这两个信息。如果你只看到其中一部分，就无法得出正确答案。

大模型也是如此。它的智能来源于对上下文的完整理解（其智能还来源于预训练时学到的知识，模式识别、知识迁移等能力）。一旦上下文缺失或者矛盾，模型的输出质量就会急剧下降。

1.2 多个模型协作的挑战

当多个大模型（Agent）需要协作时，如何保证它们都拥有必要的上下文？

假设我们有三个 Agent 并行进行开发部署工作：

• Agent A：负责前端开发
• Agent B：负责后端开发
• Agent C：负责部署运维

理想情况下，它们应该像一个经验丰富的全栈工程师一样，时刻知道其他部分的设计决策。但实际上，每个 Agent 都是独立的大模型实例，它们各自维护着自己的上下文。

这就产生了第一个问题：上下文分裂。

Agent A 决定使用 React，Agent B 决定用 Python Flask，这本来没问题。但当 Agent A 后续生成代码时假设后端返回 GraphQL，而 Agent B 实际提供的是 REST API，最终代码就无法正常工作。

并且大模型有个特性叫「自回归生成」——每个新的输出都依赖于之前的所有输出。这意味着一旦某个 Agent 做出了错误假设，这个错误会在后续生成中不断放大。

2 主从架构的设计哲学

2.1 为什么主从架构有效

主从架构的核心思想很简单：一个指挥，多个执行。一个主 Agent 掌控全局，其他从 Agent 提供子领域专业化的支持。

这个设计直接解决了上下文分裂的问题。主 Agent 始终维护着完整的任务上下文，它知道：

• 整体目标是什么
• 已经做了哪些决策
• 各个部分如何配合
• 当前的优先级是什么

从 Agent 则像是主 Agent 的「外脑」——当主 Agent 需要专门知识时，会调用相应的从 Agent，但最终的决策和执行都由主 Agent 完成。

在我们做具体实现的时候，每个不同的从 Agent 都有自己的角色和系统 Prompt。

2.2 Claude Code 的实践印证

Claude Code 的设计诠释了主从的理念。根据 Github 上逆向工程的分析，它的架构中：

nO 主循环引擎（主 Agent）负责：

• 维护完整的代码上下文
• 协调所有子任务
• 做最终决策
• 生成实际代码

I2A 子任务代理（从 Agent）负责：

• 回答特定问题
• 提供专业建议
• 探索可能的解决方案

Claude Code 刻意避免了子 Agent 的并行修改。当需要调查多个方向时，主 Agent 会有限范围内并行地咨询不同的子 Agent，确保每个决策都基于最新的完整上下文。

这种设计看起来「低效」，但实际上避免了大量的错误和重做，总体效率反而更高。

2.3 生物学的启发

并且，主从架构在生物界也是有比较多例子的。

人脑就是一个典型的例子。前额叶皮质充当「主 Agent」，负责高级决策和规划。而各个专门脑区（视觉皮层、听觉皮层、运动皮层等）就像「从 Agent」，处理特定类型的信息。

所有的感官输入最终都会汇聚到前额叶皮质，由它整合信息并做出决策。即使是反射动作，大脑也会在事后「知晓」并可能调整后续行为。

这种中心化的架构经过了数亿年的进化验证。

3 主从架构的技术实现

3.1 上下文管理

实现主从架构，最核心的是上下文管理。主 Agent 需要：

1. 维护完整但精简的上下文

并不是所有信息都同等重要。主 Agent 需要智能地压缩和总结历史信息。Claude Code 使用了一个策略：

当 token 使用量达到阈值的 92% 时，触发压缩机制。关键决策被保留，而从 Agent 的中间探索过程被压缩或丢弃。这样既保持了决策的连贯性，又避免了上下文爆炸。

2. 构建结构化的决策记录

不要只是简单地拼接所有的对话历史。需要结构化地记录：

• 任务目标和约束
• 已做出的关键决策
• 各决策之间的依赖关系
• 待解决的问题队列

3. 动态调整上下文窗口

根据任务的复杂度和当前阶段，动态调整传递给从 Agent 的上下文量。初期探索阶段可以更开放，后期执行阶段需要更精确。

3.2 Agent 的设计原则

Agent 不是越智能越好，而是要专注和可控：

1. 明确的能力边界

每个从 Agent 应该有清晰定义的能力范围。比如：

• 代码审查 Agent：只负责发现潜在问题
• 重构 Agent：只负责改进代码结构
• 测试 Agent：只负责生成测试用例

2. 标准化的输入输出

从 Agent 的接口要标准化，这样主 Agent 可以用统一的方式调用它们。输出格式也要规范，便于主 Agent 解析和整合。

3. 无状态设计

从 Agent 最好是无状态的，每次调用都是独立的。这样可以避免状态管理的复杂性，也便于并行化（当任务确实独立时）。

3.3 协调机制的关键点

主 Agent 的协调能力决定了整个系统的表现：

1. 任务分解策略

并不是所有任务都要分解。主 Agent 需要学会判断：

• 简单任务直接处理
• 复杂任务分解但保持上下文
• 探索性任务可以并行但结果需要串行整合

2. 冲突检测与解决

即使在主从架构下，从 Agent 的建议也可能相互矛盾。主 Agent 需要：

• 检测潜在的冲突
• 评估不同方案的优劣
• 做出最终决策并保持一致性

3. 优雅降级

当从 Agent 失败或不可用时，主 Agent 应该能够：

• 尝试从其它从 Agent 获取
• 降级到自己处理
• 调整任务策略

4 主从架构的优势与局限

4.1 主从架构的核心优势

1. 全局一致性保证主 Agent 作为唯一的决策中心，天然保证了架构决策的一致性。不只是技术栈的选择（比如统一使用 REST 还是 GraphQL），更重要的是接口约定、错误处理策略、命名规范等细节都能保持统一。这种一致性在复杂项目中价值巨大。

2. 清晰的决策链路每个决策都有明确的来源和依据。你可以在主 Agent 的对话历史中追踪每个架构决定是如何做出的，为什么选择某个方案。这种可追溯性在调试问题或向他人解释系统设计时非常有价值。

3. 优雅的错误处理主 Agent 掌握全局状态，当某个子任务失败时，它可以准确判断影响范围并制定恢复策略。比如，如果数据库设计出错，主 Agent 知道哪些 API 设计需要相应调整。而在去中心化系统中，这种级联影响很难追踪和修复。

4. 上下文利用最大化看似串行的决策流程，实际上优化了整体效率：

• 避免了重复劳动（多个 Agent 不会各自生成相似的代码）
• 减少了协调开销（不需要 Agent 间的大量通信）
• 上下文复用充分（主 Agent 的决策历史可以直接传递给从 Agent）

在 Claude Code 的实践中，这种设计让系统能在有限的 token 预算内完成相当复杂的编程任务。

4.2 主从架构的局限性

1. 主 Agent 成为性能瓶颈所有决策都要经过主 Agent，当需要并行处理多个复杂子任务时，主 Agent 的串行决策会限制整体效率。就像一个项目经理同时管理太多团队，协调成本会急剧上升。

2. 对主 Agent 能力的高度依赖系统的智能上限取决于主 Agent 的能力。如果主 Agent 对某个领域理解不深，即使有专业的从 Agent，整体表现也会受限。这就像一个不懂技术的经理，很难充分发挥技术团队的潜力。

3. 缺乏真正的协作智能主从架构本质上是”分解-执行-组合”的模式，缺少 Agent 之间的平等协商和创造性互动。在需要头脑风暴或多视角探索的任务中，这种层级结构可能限制了解决方案的多样性。

4. 任务分解的粒度难题主 Agent 需要准确判断任务分解的粒度。分得太细，协调成本高；分得太粗，从 Agent 可能无法胜任。而且随着任务复杂度增加，找到合适的分解方式越来越难。

4.3 适用场景分析

主从架构特别适合：

1. 工程化任务

• 代码生成
• 系统设计
• 文档编写

这些任务需要高度的一致性和结构化。

2. 有明确目标的任务

• 问题诊断
• 数据分析
• 流程自动化

目标明确时，中心化协调更高效。

3. 需要可控性的场景

• 金融交易
• 医疗诊断
• 法律咨询

这些领域不能接受不可预测的行为。

不太适合：

1. 创意生成

• 头脑风暴
• 艺术创作
• 探索性研究

2. 大规模并行处理

• 日志分析
• 图像批处理
• 分布式爬虫

3. 对等协作

• 多人游戏 AI
• 群体仿真
• 去中心化系统

5 小结

随着大模型能力的提升，主从架构也在演进：

• 更长的上下文窗口：GPT-4 已经支持 128K 的上下文，Claude 3 甚至到了 200K。这意味着主 Agent 可以维护更完整的历史，减少信息损失。
• 更好的指令跟随：新一代模型在指令跟随上有显著提升，从 Agent 可以更准确地理解和执行主 Agent 的指令。
• 原生的工具调用：模型开始原生支持函数调用，这让主从 Agent 之间的接口更加标准化和可靠。

如果你要实现一个主从架构的 Multi-Agent 系统，以下是一些建议：

1. 设计清晰的 Agent 角色：不要让从 Agent 职责过于宽泛。每个从 Agent 应该像 Unix 工具一样——做一件事，并做好。

2. 实现鲁棒的错误处理

从 Agent 失败是常态，不是异常。主 Agent 需要：

• 超时机制
• 重试策略
• 降级方案
• 错误隔离

3. 优化上下文传递：控制上下文的边界，并不是所有上下文都需要传递给给到 Agent。根据任务类型，精心设计上下文的内容和格式。

4. 监控和可观测性：记录所有的决策点和 Agent 交互，后面调试和优化用得上。

Multi-Agent 的主从架构，本质上是在解决一个古老的问题：如何组织多个智能体高效地完成复杂任务。

从生物进化到人类社会，从计算机架构到分布式系统，我们一次次地发现：在需要一致性和可控性的场景下，某种形式的中心化协调是必要的。

大模型的出现并没有改变这个规律。相反，由于大模型对上下文的强依赖，主从架构变得更加重要。

随着大模型能力的提升和 Agent 技术的成熟，我们会看到更多创新的架构出现。但无论如何演进，那些基本的原则——上下文一致性、决策可控性、错误可恢复性——都是我们在实践中需要谨慎考虑的。

以上。