我最近大半年几乎每场技术分享都在听人讲 AI Agent越听越觉得不对劲。大家聊 Agent 的时候语气都很兴奋PPT 里必然有规划、记忆、工具调用、行动这四个模块架构图画得漂漂亮亮Demo 也能跑通——但一问到“这 Agent 在你们业务里到底帮你做了哪些决定、沉淀了哪些经验”场面立刻安静下来。这种项目我见得多了给它起个名字叫 AI 八股文框架选得专业、模型接得熟练、流程画得标准唯独缺了一样东西——知识本身。这篇文章是这个系列的第二篇想把一个我最近真正落地过的方向讲透怎么把知识沉淀给 AI Agent让项目从“演示得通”变成“真的能干活”。我不是来讲概念图的我讲的是我在 Obsidian 知识库、团队技术文档、专业领域技能包上实际摸索出来的一套做法。适合谁看如果你正在做 Agent 相关开发或者你打算把一个团队积累多年的经验变成 AI 可复用的资产这篇文章应该能帮你少走几条弯路。先说明白一个核心判断Agent 跑不起来通常不是模型不够强而是你压根没喂给它属于你业务的那部分知识。1. 为什么大多数 Agent 项目都是“知行分离”1.1 你做的到底是 Agent还是一个好看的流程图每次在社区里看到有人晒 Agent 项目我基本扫一眼就能判断它是不是八股文。症状非常统一。第一种叫套框架型不管业务是什么上来就是 LangChain、LangGraph、AutoGen 三件套然后画一张 Agent 架构图图里必有四个方框规划、记忆、工具、行动中间再画几条箭头。问一句你的 Agent 在业务上做决策的依据是什么答不上来或者说“靠大模型推理”。第二种叫堆工具型今天接一个浏览器自动化明天接一个代码生成器后天再接一个办公套件工具接了一大堆看起来全能了实际上每个都是 Demo 级别。问一个稍微带点上下文的问题它就懵了因为它对工具的理解只停留在函数签名层面根本不知道工具背后对应的业务规则是什么。第三种是我最看不上眼的炫 Prompt 型把提示词工程当成包治百病的神药。System Prompt 动辄几百行开头“你是一位资深架构师”中间“你具备以下领域的专业知识”最后“请注意回答的准确性和权威性”。你看着觉得挺全面让 Agent 去处理一个具体的领域问题立刻露馅。Prompt 写得再长也只是让模型演得像个专家不等于它真的懂你的业务。1.2 知行分离的根源Agent 的“知”太单薄了为什么这三个套路最后都走不通因为 Agent 在运行的时候它的“知识来源”其实非常有限。第一层是模型参数里自带的通用知识也就是大模型在训练时吃进去的海量互联网文本这些知识的优点是广缺点是浅而且和你的业务没有半毛钱关系。第二层是上下文窗口里临时的输入也就是你这次提问时带进去的信息这个范围极其有限通常只有几千到几万个 token根本装不下一套完整的领域经验。第三层是外挂工具返回的结果可惜大多数项目在这一层根本没有接入真正的知识源。我用一个老带新的类比来说明这个问题。一个刚从医学院毕业的实习生你让他背药理、病理、诊断学他能给你背出一整套教科书。但你要是让他独立坐诊面对一个症状不典型的病人他大概率会懵——因为他手里只有教科书式的通用知识没有跟着老医生在真实病人身上积累过的病例经验。现在的 Agent 就是那个实习生框架是它的白大褂模型是它的教科书但是真正让它值钱的“临床经验”也就是你团队这些年踩过的坑、验证过的方案、总结过的规律它完全没有。这就是知行分离的根源知的那部分太薄行的那部分自然立不住。1.3 “八股文”为什么危害特别大我说它是八股文不是说这些事情完全没用。框架值得学工具值得接Prompt 也值得写这些本身都是 Agent 工程的必要环节。问题在于当这些形式化的东西变成了项目的全部大家就会产生一种虚假的成就感架构图画完了、Demo 跑通了、分享稿写好了项目看起来已经完成了 80%实际上业务价值连 10% 都不到。危害更大的是这种风气会把整个行业的关注点带偏。你会发现最近连面试都在问 AgentAgent 的运行逻辑是什么、ReAct 范式怎么理解、记忆模块分几种。我承认这些是该懂的基础但候选人回答得再流畅也只能说明他读过几篇技术博客不能说明他做出过真正稳定解决业务问题的 Agent。知识沉淀这件事没有捷径它需要你俯下身子去整理文档、清洗数据、设计检索链路、持续迭代评估而不是画张架构图就能交差。这一篇我就是想把这条没有捷径的路尽量完整地写给你看。2. 把知识资产化Agent 能消费的四种知识形态2.1 知识不是文档而是需要“资产化”的东西很多团队一听“把知识沉淀给 Agent”第一反应是我们有 Wiki、有 Confluence、有各色网盘文档东西多得很直接喂给 Agent 就行。你要是真这么干跑出来的结果大概率是一场灾难。为什么因为大部分知识库是为了人阅读而组织的不是为机器消费而组织的。文档里充满了模糊的指向、省略的上下文、“众所周知”的前置条件人读了能脑补出来模型读了只会一头雾水。所以第一步要做的是转变观念知识要交给 Agent必须经过资产化处理。什么叫资产化就是让每一份知识都有明确的边界、格式、用途、更新状态像代码一样可以被检索、调用、版本管理。不是所有内容都有资格变成资产只有那些经过了验证的、可以被复用和评估的知识才值得进入 Agent 的循环。这个筛选动作本身就是价值。2.2 第一种形态技能包Skill把操作流程变成可执行的步骤技能包是我自己最看重的知识形态它解决的是“Agent 知道该怎么做一件事”的问题。一份合格的技能包不应该是一篇操作手册而是一份让 Agent 能“照着做”的结构化文档。我通常用 Markdown 来写但里面的格式有严格要求头部字段写清楚技能的名称、用途、适用条件、输入输出正文部分把流程拆成一步一步每一步都说明“这一步要做什么、为什么这么做、常见错误是什么”。举个例子更容易理解。假设你要沉淀一个“代码走查”技能交给 Agent不能只写“请对代码进行走查并提出改进建议”那等于什么都没写。你要拆第一步读取变更文件列表和关联需求文档第二步按规范检查命名、异常处理、边界条件第三步结合仓库里的历史缺陷案例库判断是否存在重复踩坑第四步输出问题清单每条问题必须标注严重级别和修改建议。每一步都对应可检索的依据Agent 执行起来才不会胡说。2.3 第二种形态工具定义把能力接口变成 Agent 可调用的函数Agent 要真正产生行动必须调用工具。很多项目死在工具调用上不是代码实现有 bug而是工具的说明书写得一塌糊涂。模型不知道这个工具在什么时候该调、调了该传什么参数、返回值代表什么含义它当然不敢调用或者干脆乱调。工具定义本质上是一份给模型看的接口文档。以我常用的 Spring Boot 工程为例我会把工具按业务能力分组每个工具用 JSON Schema 描述参数和返回结构然后在描述字段里把适用场景写得非常具体。注意这个描述不是给自己人看的是给模型看的所以别写“获取用户信息”这种泛泛而谈的东西要写“当用户询问其个人资料、账户信息、订单状态时调用返回值为用户的基本信息和近期订单列表”。写清楚触发条件比写清楚代码逻辑更重要。2.4 第三种形态检索底座把存量文档变成按需调用的知识技能包解决怎么做工具定义解决能做什么但对于大部分团队来说最值钱的知识还是散落在历史文档、FAQ、事故复盘、需求设计稿里。这些存量知识不可能一个个手工写成技能包所以你需要一个检索底座让 Agent 在回答问题时先去知识库里搜一圈再结合搜索结果生成答案。这就是大家常说的 RAG检索增强生成。检索底座不是搭一个向量数据库就完事里面有大量细节。内容切分要控制粒度切太碎了上下文断裂切太大了一次检索回来的噪音太多元数据至少要保留来源文档、创建时间、责任人、标签这样 Agent 引用答案时才能给出出处。我们后面实操部分会详细讲这里先记住一个原则检索底座的目的是让 Agent 在“开口回答之前”先“翻书”而不是靠记忆硬编。2.5 第四种形态决策样例把历史经验变成 Few-shot 参考最后一种形态容易被人忽略但效果往往最直接它叫决策样例。所谓决策样例就是把过去处理过的问题整理成“问题描述、判断逻辑、最终方案”三个要素组成的小样本在 Agent 遇到类似场景时作为参考输入喂进去。这相当于给 Agent 塞了几份“学长留下的作业答案”它模仿着做成功率会高很多。这个想法其实是从一句话里悟出来的经验不是概念而是“当时发生了什么、我怎么判断的、最后怎么解决的”。把这些整理成结构化样本比单纯的规章制度文档有用得多。我一般会把高价值决策样例归入技能包目录里作为技能包的附件这样 Agent 执行技能的时候不仅知道步骤还能参照真实的成功路径。3. 实操把 Obsidian 知识库变成 AI Agent 的“职业记忆”3.1 为什么选 Obsidian 当试验田我先交代一下背景我自己最常用 Obsidian 管理个人笔记身边认识的知识管理重度用户也几乎都在用它所以 Obsidian 作为知识沉淀试验田非常合适。它最大的优势是笔记全部是本地 Markdown 文件目录结构和文件格式都是开放透明的你既可以用插件生态现成的能力也可以自己写脚本处理。这对接 Agent 来说简直太友好了你不需要解析私有格式一个目录扫过去就能拿到全部知识。但一个现实问题也随之暴露Obsidian 默认的笔记组织方式是为“人脑联想”设计的双链、标签、反链都是给人看的。你要是原样把这些笔记丢给 Agent它面对的就是一堆互相引用、上下文割裂的碎片完全没法用。所以第一步必须重构笔记的组织结构。我花了整整两天把两年多的笔记过了一遍删掉了一大批“写过再也不看”的内容把真正有复用价值的笔记按主题归入几个大目录然后在每篇笔记头部加了 YAML front matter写上 title、tags、date、status、source 这些元信息。status 字段很关键我用来标记成熟度idea 代表只是想法draft 代表待整理final 代表确认过可以复用。3.2 打通检索链路本地向量库与索引方案笔记结构整理好之后下一步是让 Agent 能真正“读得进去”。我的选择是走本地检索链路把 Markdown 文件切块、向量化写入本地向量库然后通过接口暴露给 Agent。切块我用的策略是“按标题层级切”先按 H2 把一篇笔记切成大块如果某个 H2 下面的内容太长再按段落切成小块。这样既保留了上下文完整性又不会因为单块太大导致检索时语义被稀释。向量化模型我用的是本地部署的 embedding 模型速度还能接受隐私上也放心。写好的脚本定时扫描 Obsidian 目录发现新增或修改的笔记就重新切块和向量化增量写入本地向量库。检索接口支持两种方式关键词检索和语义检索两者取交集打分。刚开始我只用语义检索发现有些精确名词比如某个内部系统名称向量匹配容易跑偏加上关键词召回之后准确率明显上来了。3.3 给 Agent 定义技能入口Skills 目录的妙用知识库有了还得让 Agent 知道“什么时候该用这些知识”。我在 Obsidian vault 里单独建了一个 skills 目录一个技能对应一个 Markdown 文件。看起来很简单但这是整个系统里最关键的认知设计知识是被动资产技能是主动能力。光有知识库Agent 只是个字典你问它才答有了技能包Agent 才能主动完成一件需要多步骤推理的事情。我最早沉淀的技能是“周报生成”。这个技能文件里写了触发条件当用户提供本周工作事项列表或 Git 提交记录时触发输入格式一段文本或一个文件路径执行步骤先读取本周工作事项列表然后结合技能包里的项目进度知识库判断每件事属于哪个项目阶段再按模板生成周报最后标注风险项输出格式Markdown 表格列包含工作项、所属项目、完成状态、风险说明。跑通之后我又陆续沉淀了“需求复盘”“代码走查”“事故排查”几个常用技能每个技能都是同样的结构。Agent 拿到这样的技能执行出来的结果像模像样因为它的每一步都有明确的规则可循。3.4 闭环设计回答之后必须回写知识很多人做知识库加 Agent做到检索和生成就觉得完事了。但我觉得真正让这套系统产生复利的是最后一个动作回写。Agent 每次回答完问题我会人工判断这次回答是否有效如果有效就把问题、检索到的知识、最终答案、使用心得整理成一条新的记录存进 vault 里的 qa_records 目录。下次再遇到类似问题Agent 检索时就能命中这条历史记录直接给出经过验证的答案而不是重新推理一遍。这一步看起来简单实际上是把“用知识”和“沉淀知识”两个动作闭环起来。很多人说知识库用久了会腐烂因为文档更新跟不上业务变化。但你设计了回写机制以后每次有效的问答都在补充知识库相当于知识库保持了一种“越用越新”的状态。我用了三周之后qa_records 目录攒了两百多条记录Agent 回答问题的准确率肉眼可见地在提升。3.5 运行之后必须有评估机制最后分享一个特别容易被忽略的环节评估。很多人觉得知识库加了、技能包写了、Agent 能答了就万事大吉。我不这么看没有评估机制的 Agent 系统就像没有测试的代码你根本不知道下一次改动会不会把它改坏。我维护了一份固定测试问题集大概四十个问题覆盖从知识检索、技能执行到工具调用的各种场景。每周抽十分钟跑一遍给每次回答打分完全正确、部分正确、错误、胡说。把得分记录成趋势就能清楚地看到哪类知识在退化、哪类技能在变稳定。有一次我重构了向量化的切块策略跑完测试集发现代码走查类的回答质量下降了排查发现是切块后代码示例被拦腰截断模型理解不完整。如果没有评估机制这种回归错误可能要过很久才能从用户反馈中发现。4. 不同落地场景的实操路径与选型思路4.1 硬件与芯片场景用技能包沉淀 Verilog 开发经验开头提到的那批热搜词里有一条“ai agent verilog代码”挺有意思说明硬件领域的开发者也在琢磨 Agent 怎么提效。芯片验证这个方向我接触过一些团队他们的痛点和互联网行业很不一样。Verilog 开发链条长EDA 工具使用经验非常依赖“老人传新人”时序违例、约束写法、跨时钟域处理这些问题教科书上只有原理具体项目里全是细节。新人最容易卡的就是这些“经验性知识”。这种场景我觉得是最适合用技能包方式沉淀的。把团队过去的时序问题排查案例整理成结构化技能第一步复现问题记录违例路径和时钟域信息第二步结合代码定位可能的原因列出常见原因清单第三步依次排查每一步都有具体的检查命令和预期输出第四步给出修改建议并回归验证。把这些做成技能包之后Agent 在代码走查时就能结合真实排查经验给出有依据的提醒而不是泛泛背一遍通用编码规范。做这个事还有一个意外收获整理技能包的过程本身就是在做团队知识传承很多老师傅嘴上说“这些东西没法写”真逼着按结构写其实还是能写出来的。4.2 Java 工程场景Spring Boot 应用接入 Agent 的落地方案后端工程师想在自己工程里接入 Agent 能力我见过几条路有的直接在客户端里嵌套模型调用有的设计一个独立的 Agent 服务端。从知识沉淀的角度看我更推荐后一种。你做 Agent 服务端知识的维护只需要一份客户端统一走接口来问而不是每个客户端自己拼接大模型、自己维护知识库那样知识肯定无限分散。具体到 Spring Boot 工程里我会把 Agent 能力拆成四个层次。接入层暴露 HTTP 或消息队列接口接收客户端的提问请求理解层做意图识别判断这个请求属于“知识问答”“技能执行”还是“工具调用”知识层连接前面那段提到的向量库和技能包目录负责检索和组装上下文执行层调用具体业务工具。举个例子一个工单辅助系统用户问“帮我看看这个线上报错的处理记录”接入层收到问题理解层判断是知识问答知识层检索向量库中的历史工单复盘执行层调用工单系统获取当前状态最后模型整合成一段带出处的回答返回给客户端。这个架构里最容易出问题的地方在知识层因为团队历史工单往往散落在不同系统格式五花八门。我建议先做一轮清洗和脱敏至少把时间、系统、错误码、根因、解决方案这几个字段整理成统一格式再入库。宁可先入库 10% 高质量数据也别一次性灌入 100% 的垃圾数据。数据质量直接决定回答质量这一点怎么强调都不为过。4.3 团队知识库场景从 Wiki 到“可被检索的组织记忆”如果你的目标不是做一个新的 Agent 产品而是把团队这些年的 Wiki、复盘文档、设计稿变成 Agent 的“组织记忆”那就要在信息架构上多花功夫。最稳妥的做法是先做一轮咨询式的盘点把文档按类型分成公共知识和个体经验两大类。公共知识里还能再拆出制度流程、业务口径、技术规范、故障复盘这些子类个体经验则包括个人的踩坑记录、优化笔记、工具技巧。分类的目的是确定访问权限公共知识可以被团队 Agent 自由使用个体经验在默认情况下只给本人授权使用。盘点完之后要建立一个“知识运营”的机制这一点我在实践中感受特别深。知识库和代码库一样不维护就会腐烂。我建议每个团队指定一个知识库负责人负责审核入库内容的质量、检查过期文档、维护标签体系。不要觉得这是额外负担它其实是把以前散落在各处的“文档维护工作”集中了起来。只要有人负责知识库就会持续有用没人负责再好的工具也堆不起来。4.4 关于工具对接你的知识系统应该向生态开放前面提到有人讨论 Obsidian、draw.io 这类工具链能不能与 Agent 对接我的答案是可以而且应该朝着“完全对接”的方向走。核心原则是一切知识资产都应该能被 Agent 通过统一协议访问。笔记目录是知识画图工具的图源文件也是知识API 文档是知识数据库里的业务元数据同样是知识。只要它们被组织成结构化的、可检索的形式Agent 就能在需要时调取。Obsidian 在本地文件怎么处理我们前面已经走通了draw.io 之类的画图工具本质是 XML/文本格式的图源文件同样可以通过脚本解析成结构化描述进入检索底座。项目里如果有 Hermes 这类 Agent 运行时也可以通过 MCP 协议做标准化的接口对接。MCP 的好处是它定义了工具发现的统一方式Agent 一启动就能知道系统里有哪些知识源和工具不需要为集成一个新数据源而改对端代码。这套“知识资产化工具链”越来越成熟2026 年 Agent 应用的走向大概率是拼“谁能把知识组织得更结构化、谁能把工具接得更标准化”而不是拼谁的 Agent 框架画得更好看。5. 常见问题与排查技巧实录5.1 知识库建好了Agent 还是答非所问这个几乎每个人都会碰到。第一个排查点是检索环节有没有真正工作。我建议把检索单独测试输入一个测试问题看看向量库召回的 Top5 文档到底相关不相关。如果召回结果本身不对后面生成答案再厉害也白搭。切块粒度是召回失败最常见的原因一篇几千字的文档整体向量化之后语义被稀释检索时匹配不到真正关键的小段落。解决办法是切块控制在三百到五百字之间并且保留上下文标题让每个块自带语义背景。第二个排查点是问题本身是不是太依赖实时信息。比如用户问“当前线上订单量趋势如何”知识库里根本没有实时数据Agent 只能瞎编。解决方法是给 Agent 配置实时数据工具明确告诉它“涉及实时数据时必须调用订单查询工具不得直接回答”。把这句话写进系统提示词和工具描述里效果会好很多。5.2 Agent 一本正经地引用过期知识知识库最大的隐患是内容会过期尤其技术类的文档三个月前的方案可能已经被推翻了。Model 不知道时间你给它一篇旧文档它就当成真理引用。这个问题的解法分两层。第一层在入库时给每份知识资产打上 created_at、updated_at、valid_from、valid_to 这些时间字段检索链路里加一层过滤过期内容直接不召回。第二层更高级一点给知识资产增加“状态”字段active 代表当前有效、deprecated 代表已废弃、draft 代表草稿Agent 在回答时会优先使用 active 内容。但这里有个小坑有些知识本身是历史事实过期不代表没价值。比如事故复盘里记录的当时系统设计虽然现在系统已经重构了但这个历史记录对理解演进过程还是有价值的。我后来把“知识过期”细分成“方法过时”和“事实过期”方法过时的标记 deprecated 不再重用事实过期的则保留作为背景参考只是不会作为当前方案的依据。5.3 技能包写好了Agent 却完全不按步骤执行技能包文件写得清清楚楚步骤一、步骤二、步骤三Agent 拿到手就是不肯照着走而是跳步、合并步骤、甚至自己发明新流程。这个坑我也踩过。排查之后发现原因通常不在技能内容本身而在触发机制。Agent 没有能力判断“当前这个问题应该调用哪个技能”尤其是多个技能同时存在的时候它容易混淆。解决方案是在技能包的头部加上“适用场景”和“不适用的场景”描述越具体越好。比如“事故排查”技能下面写“适用场景线上服务异常、接口超时、内存泄漏”再写“不适用场景新增功能开发、代码重构、性能调优建议”。这能大幅提高技能路由的准确率。还有一个细节技能包里的步骤之间要有明确的输出条件。不要写“分析问题”这种不可验证的步骤要写“根据异常堆栈定位到具体类和方法输出问题复现路径”。Agent 每完成一步能检查自己是否真的完成了才能接着往下走。可验证性是技能包设计的关键。5.4 知识资产的安全边界怎么划团队知识库一旦交给 Agent安全就是一个必须前置考虑的问题。公司内部文档里很可能包含用户隐私、未公开的商业策略、内部系统的访问方式这些内容不能被随意提供给外部模型服务。我建议对知识资产做一个分级公开信息、内部信息、机密信息三个等级。机密信息在入库之前必须脱敏或直接不纳入 Agent 知识库内部信息在接入 Agent 时需要做身份鉴权不同的用户提问时Agent 只能检索到对应权限范围的知识。技术实现上最简单的方式是在检索链路里增加权限过滤先根据用户身份拿到允许访问的知识资产 ID 列表向量检索时用这个列表对结果做过滤。如果你用的是本地部署的模型隐私问题会好很多但权限控制逻辑依然必不可少。安全无小事尤其是 Agent 这种会“自动回答”的系统权限设计上的疏漏可能比人工服务出错更隐蔽、更难发现。5.5 怎么证明“加了知识库真的变聪明了”最后一个问题也是我最常被问到的怎么证明这套知识沉淀的方案真的有效我测试过几家企业大家在一件事上高度一致没有评估就没有优化。建议你花半天时间准备一份固定的评估问题集把你们业务里的典型场景拆成问题每个问题写上期望的回答要点。然后每次调整知识库或 Agent 逻辑之后跑一遍评估问题集记录分数。我用过一个简单的打分规则回答完整且要点齐全是优秀加两分基本正确但缺少某一要点加一分错误或误导性内容直接零分。跑一个月下来把分数画成趋势线能很直观地看到哪些改动带来了提升哪些改动带来了回退。这个评估集本身就是团队知识的一部分它在不停地提醒所有人Agent 的能力不是玄学是可度量、可改进的工程指标。整理这套方法论的过程里我自己最深的体会是真正让 Agent 变好用的不是更复杂的编排框架而是你愿不愿意把已有的经验老老实实地结构化成机器能消费的资产。一开始整理技能包和知识库会觉得很枯燥但坚持三四周之后你会看到一种正向循环在慢慢形成知识越用越多Agent 越用越准团队的判断标准也越来越统一。这个方向后续还能往 Skill 生态和 MCP 标准化工具接入上继续延伸把更多系统接入进来但根基始终是那句朴素的话先把知识沉淀下来Agent 才能真正知行合一。