编者摘要：语义工程蒸馏专注 Agent 语义层分析与模式萃取，服务 Agent 自我迭代与 Harness 优化，不关注模块架构与代码质量。方法以模型 API 请求为分析终点，逆向溯源拆解请求载荷，追踪上下文原始入口；同时穷举静态与运行时动态上下文注入源，借助多 Agent 交叉核验规避遗漏。从工具引导、执行行为包装、信息结果封装三层解析工具语义；多 Agent 协作重点解析独立世界观、跨代理信息传递与协作模式语义差异。记忆分析聚焦语义定义、存储内容、提取方式、记忆曝光形式及其对世界观连续性的影响。时间轴分析考察信息放置位置、刷新、重建、反应式注入的动态语义权重；语言表达分析严格区分客观事实与推断，区分框架绑定提示与通用行为指导。基于版本提交等分层证据推断开发者设计意图，构建开发者画像。评价体系将世界观塑造置于最高优先级，其次为语义工程质量，代码质量作为独立可维护性维度评估。
7 个关键问题 Q&A
Q1：语义工程蒸馏为什么选择模型 API 请求作为分析起点，而不是从业务代码入口开始？
A：Agent 所有行为最终由发给大模型的 API 载荷决定，框架多层抽象会掩盖真实输入内容。从 API 终点逆向溯源，可以直接定位真正流入模型上下文的内容，避免被中间层业务逻辑干扰，抓住语义本质。
Q2：只做静态代码扫描，为什么无法穷尽全部上下文注入源？
A：大量上下文属于运行时动态注入，不会体现在静态代码文本。部分逻辑修改持久化存储，不在本轮消息生效，在下一轮请求循环自动携带。单一静态扫描会遗漏这类隐蔽注入路径。
Q3：工具语义工程的三层分别关注什么，为什么不能把工具只当作程序接口？
A：①工具引导：description、参数内嵌的场景、约束、使用策略；②执行行为包装：失败、空值、超长输出、重复调用的返回语义处理；③信息结果封装：工具输出针对模型能力做适配渲染。工具不只是调用接口，大量引导文本直接塑造模型调用工具的行为模式。
Q4：开展多 Agent 语义分析，最核心的两处分析难点是什么？
A：一是每个 Agent 拥有独立世界观，需要解析身份、环境、约束，判断多代理世界观是否一致互补；二是跨 Agent 信息传递存在语义变换，需要识别封装、截断、转述带来的信息损耗，理解协作模式背后的信任分配与风险控制逻辑。
Q5：记忆分析的重点不是存储技术，核心分析哪四个 Agent 视角的问题？
A：记忆的设计者语义定义；Agent 主观层面 “记住了什么”；信息如何提取、结构化、落盘，过程丢失哪些信息；记忆重新注入上下文的曝光形式，以及该形式带给 Agent 的认知地位。
Q6：同一段信息放在 system prompt 和 message 列表，二者语义上有什么本质区别？
A：system prompt 具备全局持续权威，没有时间锚点；message 列表绑定时序，能够建立事件因果关系。二者不是简单存放位置差异，是设计者对信息的时效性、权威性的语义设计。
Q7：蒸馏评价体系中，世界观塑造优先级最高，代码质量作为独立维度，背后逻辑是什么？
A：模型按照语义叙事框架开展行为，世界观直接决定 Agent 行为底线，是第一性要素。代码质量只影响可维护性；代码优秀但语义设计缺陷，Agent 运行效果依旧很差；语义工程优秀，即便代码一般，Agent 也可以产出良好表现。
附录 语义工程蒸馏方法论
（本文聚焦于从语义层对 Agent 开展分析与模式萃取，实现经验复用与借鉴。这也是 Agent 实现自我迭代的关键基础，只有建立该层面的全局认知，才能高效迭代 Harness 体系。本文不讨论 Agent 模块架构与代码质量，全部分析重心落在语义本身。
零、一句话挖掘 Agent
阅读本文时可直接使用如下提示词，在 dimagent /codex/claude /dsh 上均可取得 70‑80 分的挖掘效果。
（初步梳理项目结构 / 对目标应用解包还原代码），调度多Agent对目标Agent项目开展深度挖掘：提取最终投喂给大模型的上下文原文、信息来源以及上下文注入机制。挖掘过程中将原始素材持久化保存至 @../research/ 目录。挖掘全程反复论证校验，穷举全部上下文入口，执行多轮复核验证。全部验证完成后，输出完整分析报告。
一、从终点开始
所有 Agent 拥有同一个逻辑终点：向大模型发起 API 请求。 无论框架封装多少层抽象，提示词、用户输入、工具调用等全部要素，最终都必须汇入该 API 请求，才会产生 Agent 行为。蒸馏工作以此终点作为切入：定位组装并发起模型 API 请求的代码位置，拆解请求结构体，反向识别每一段上下文内容的来源。
以 ChatCompletion 类 API 为例，请求载荷通常包含 system prompt、多轮对话消息、工具调用消息，同时附带 reasoning_efforts、service_tier 等控制参数。 本环节核心任务：定位每一段载荷内容，向上溯源其生成链路。
二、逆向溯源
逆向溯源的核心思路：以 API 请求终点为锚点，反向遍历代码，梳理完整逻辑流程树，一路追踪至不可再拆分的原始数据入口。
流程树的中间节点普遍存在引入、变换逻辑，需要持续追问： 该文本来自模板原文，还是变量填充？变量取值源自何处？内容抵达最终请求前经历哪些变换（投影、压缩、截断、降级、包装）？一路追踪至叶节点：静态配置文件、硬编码常量、运行时动态计算结果。
代码研读需要额外关注：
-
同一段最终上下文渲染文本，可能由多路来源合并生成； -
不同变换链路承载差异化信息封装逻辑，并非所有中间信息都应当输入模型； -
除正向主流程，必须覆盖异常、错误分支，异常输出同样会暴露到模型上下文。
三、注入源的穷举
仅靠逆向溯源仍存在遗漏风险：大量上下文属于运行时动态注入，无法通过静态代码扫描发现。
穷举思路：识别框架内所有 “向上下文追加内容” 的接口，遍历全部调用点位。不同框架实现路径各不相同：声明式注册、命令式调用、消息队列、直接修改底层数据结构，同一框架往往并存多条注入路径，单一检索方式会造成遗漏。
典型隐蔽场景：框架不直接修改本轮消息，而是写入持久化存储，在下一轮请求循环自动携带该新增信息。
完备分析方案：启用多 Agent，以差异化分析视角交叉核验，输出核对清单。无需运行实验，即可最大限度穷尽各类动态插入逻辑。
四、工具的三层语义解析
工具语义工程分为三层，不能仅当作程序接口看待。
第一层：工具引导
工具的 description、schema 参数内包含大量引导性文本，用来告诉模型适用场景、调用方式、结果处理逻辑。工具命名、参数说明本身也属于引导。命名应当贴合业务场景，例如upload优于sendFileToRemote。
工具描述中会内嵌各类隐性约束：编码范式（编辑工具的最小改动原则）、安全规则（Bash 工具安全限制）、执行策略（读取工具文件查找优先级）。这部分属于语义工程，不等同于普通 API 文档。
第二层：执行行为包装
定义工具执行结果如何转化为模型可理解的语义信号。 需要明确：调用失败返回原始报错还是封装后的状态；空结果如何表达；超长输出选择硬截断还是落文件返回摘要；重复调用拦截后输出错误还是占位标记。
这套包装决定模型如何理解工具调用行为。例如后台异步 Shell 任务，通常用 XML 标记封装返回内容，告知模型该输出对应历史工具调用。
第三层：信息结果封装
控制工具输出如何渲染进上下文。多数 Agent 直接裸输出文本，优秀设计会根据模型能力做适配。 示例：读取工具具备图像解析能力，但后端模型不支持视觉时，不应直接输出 image‑block，改用占位标记；视觉模型可用图像块，非视觉模型切换为文件占位，甚至触发子节点完成图片转文字描述。
结果封装直接塑造 Agent 的内部认知：我执行了什么操作，得到了什么结论。
五、多 Agent 协作：从单请求到请求网络
开启多 Agent 协作后，分析对象不再是单次 API 请求，而是由多条请求序列构成的协作网络。每个 Agent 拥有独立系统提示词、工具集、上下文，同时存在跨主体信息流转。分析既要覆盖个体语义工程，也要解析协作层面的语义设计。
世界观塑造与上下文一致性
每个 Agent 拥有独立世界观，包含主体身份、环境信息、行为约束。需要解析每个 Agent 被赋予的世界观，判断多个 Agent 之间是相互一致还是互补关系。
示例：子代理被定义为 “隔离执行者，仅允许最终消息汇报”；另一个 Agent 定位为 “控制塔，负责规划调度”。世界观本身就是协作模式的设计。不少框架支持完全自定义子代理，子代理的全部能力由主 Agent 的上下文分配与组织逻辑生成。
信息传递包装
跨 Agent 通信会发生语义转换：父 Agent 提示词如何转化为子 Agent 输入，子 Agent 输出如何融入父 Agent 上下文。封装、截断、转述策略直接影响双方认知。
分析要点：传递完整原文还是摘要；摘要由发送方生成还是接收方重读处理；信息损耗在哪里；接收端认知是 “这是子代理输出” 还是 “客观事实”。
协作模式的语义差异
Fork、Swarm、Tower 等协作模式拥有不同信息流拓扑与角色设定。对比不同方案，反推设计者的场景判断：适用边界、信任分配、风险控制策略。若协作引导不足，会出现行为重叠、冲突、重复执行、代理间互不信任等现象。
六、记忆
定义
记忆是 Agent 与外部系统持续交互后，经过结构化持久化的历史记录。分析记忆的重点不是存储技术，而是设计者赋予记忆的语义定义。不同框架理解差异巨大：部分等价于对话历史，部分视作工作摘要，还有的用来留存推理链路与决策依据。
分析视角（站在 Agent 本体视角的四个核心问题）
- 记忆定义
设计者将记忆定位成什么？是历史纪要、推理判断，还是状态上下文。定义决定存储结构与重新曝光形式。 - 记了什么
不只看文件存储内容，更要明确 Agent 主观认知里 “我记得什么”。摘要代表工作历史，Todo 代表计划，Goal 代表目标判断。 - 怎么记的
交互信息如何提取、结构化、落盘。提取主体是框架自动处理还是模型主动保存；存储结构、存储位置；提取过程丢弃了哪些信息。 - 如何再次曝光
记忆重新注入上下文的形式，决定 Agent 对该段记忆的认知层级。原样恢复 =“我记得这件事”；摘要转述 =“别人告知我过往发生”；作为环境事实注入 =“当前客观状态就是 X”，三者语义权重完全不同。
记忆与世界观的关系
记忆持续参与世界观构建。持久项目记忆（动态更新的 AGENTS.md）把认知突破单会话；摘要压缩让历史认知不受窗口限制。记忆完整度、还原度直接决定 Agent 世界观的连续性。
会话重启、上下文压缩场景下，哪些记忆恢复、哪些丢失，恢复之后世界观是否保持连贯，反映设计者对 Agent 身份连续性的取舍。
七、时间轴分析
时间轴具备动态属性
Agent 请求时序由四方共同驱动：设计者预设策略、模型行为触发注入、外部环境变更、用户操作干预。开发者无法固定时间轴形态，只能定义规则：当特定事件发生，向上下文注入指定内容。
动态策略本身就是语义设计。提示词语义不只取决于文本内容，还取决于注入时机、放置位置、生效频次、失效条件。
- 放置位置
同样内容置于 system prompt 与 message 列表语义完全不同。System 具备全局权威，无时间锚点；消息列表自带时序，可以建立因果链条。时间戳一般放置在消息列表来强化时序。 - 刷新策略
常驻、每轮刷新、一次性注入，表达设计者对信息有效期的判断；还可随流程切换完整版、压缩版。 - 重建策略
上下文压缩后部分信息重新加载。分析视角应当向前看：为保障后续运行，Agent 需要哪些信息，而不是简单罗列不能丢失的历史条目。 - 反应式注入
非预设定时注入，响应模型行为、环境、用户动作，紧跟事件发生，传递因果关系。
分析方法
对每一段上下文，除文本本身，需要回答：为什么放在该位置；生效频次的用意；压缩后是否重建，重建依据；由什么事件触发，时机传递什么因果。
同时校验动态策略的自洽性。例如一条信息放入消息列表（时序语义），却每轮刷新（常驻效果），存在表象矛盾，需要挖掘背后真实设计意图。
提示强度与语义联动
放置位置、语气强度、刷新频率三者联动，共同决定信息的语义权重。
示例：system prompt (高强度)+ 强制禁令 (强语气)+ 全程常驻，对比 message 列表 (低强度)+ 温和措辞 + 每轮刷新，二者意图截然不同。
分析时对每条内容同时标注三个维度，校验组合逻辑。低强度搭配极强语气，或是高强度却仅一次性出现，背后必然存在设计考量。
时间轴分析负责动态时序语义，语言表达分析负责静态文本语义，二者结合才能还原完整意图。
八、语言表达分析
提示词的排版、措辞属于工程决策，而非审美偏好，是理解设计逻辑的关键。
分析纪律
严格区分两层：
- 可观测事实
写了什么、放置位置、措辞、重复次数，属于代码文本客观证据。 - 推断结论
推测设计者意图、对模型的潜在影响，必须显式标记为推断，不作为既定事实。
借用外部理论需要有据可依，人类认知研究结论不能直接套用到大模型，杜绝无依据假设。
分析维度
- 结构组装
片段排布顺序、条件分支位置、收尾设计。顺序位置是客观事实，解读意图需要标注推断。 - 包装行文
标签体系（不同标签是否赋予差异化权威）；语气轻重；叙述视角（第一 / 二 / 三人称）。措辞会影响行为，但影响方向与幅度需要实验验证。 - 连续语义
级联传导设计。例如 system 提示动态注入规则，动态注入又引导模型关注资源变更，进一步衍生新的上下文指导。
九、框架强相关提示 vs 通用行为指导
- 框架强相关
提示词和框架结构、代码流程、能力强绑定。逻辑：框架具备某能力，因此需要提示词引导模型正确使用该能力。剥离该框架能力，这段提示不再具备意义。 - 通用指导
矫正模型本身行为，和框架实现无关。
判别标准：移除对应框架能力，该段提示词是否仍然成立。
举例：要求模型多轮验证输出、减少向用户咨询，独立于框架存在。一部分用于弥补模型固有短板，一部分体现开发者期望的 Agent 人格。负向约束大多属于行为补丁；正向引导体现设计者目标。
十、开发者意图推断
开发者意图推断是蒸馏的核心环节。只看到 “是什么” 不足以理解系统，还需要回答 “为什么”，还原开发者当时面临的约束、痛点与取舍。需要分层收集证据，推导设计者心智。
证据分层（可靠性从高到低）
- 可靠证据
Git 提交历史、版本变更、PR 描述、配置项设计、对外暴露参数。代表开发者主动做出的决策。 - 间接证据
代码措辞、实现逻辑、变量命名。注意现代 Agent 工程大量代码由 Agent 生成，不能把全部代码细节归属于人类开发者想法。 - 分离产出
剥离区分哪些逻辑来自人类设计者，哪些来自 Agent 自身的生成习惯，作为分析产出。
间接证据推理必须写明证据链。当提交历史与代码细节冲突，以提交历史为准。
推理方法
- 决策点识别
每一处提示词都是选择结果。从措辞反推可选方案，例如选用 “禁止” 而非 “限制”，标记为推断。 - 联合对比
横向对比同类设计，对比维度：控制对象、硬约束 / 软引导、流程控制 / 结果控制、风险假设、信任边界，解读取舍背后的判断。 - 跨框架对比
不同框架处理同类问题的差异，映射不同开发者的认知。 - 演变分析
版本 Diff 远比单份快照重要，从迭代变更反推设计者发现的问题、认知更新、新增约束。 - 系统性推断
统计整体提示词体系，哪些行为反复约束、哪些场景给出完整流程、哪些只保留原则，反映开发者对模型能力的评估。
迭代机制
得到开发者画像之后，可以反向校验、迭代前面挖掘得到的语义设计。不同开发者的风险偏好会带来截然不同的设计，仅靠代码容易产生误读。
开发者画像维度：风险认知、信任边界、控制哲学、效率观念、用户体验取向。
十一、评价标准
蒸馏输出除分析报告外，还需要输出对 Agent 语义工程质量的评估。
第一优先级：世界观塑造（最高权重）
世界观、主体、环境信息的完备度与还原度优先于工具、流程机制。 可以类比叙事模型：模型沉浸在一套叙事框架中，依据框架做出行为。语义框架越贴合真实运行环境，行为管控、工具调用效果越好。
主体定义是世界观的核心。相同客观环境，不同角色定位会导向完全不同行为。
例：“你是在该目录执行任务的工具操作者” 倾向被动执行；“你和用户协同解决问题，工作目录为 XX” 会激发主动协作。客观事实不变，但 Agent 自我认知完全改变。
评价维度：
-
主体定义是否匹配 Agent 实际职责； -
环境事实信息是否完整披露； -
语义叙事框架和真实运行环境还原度； -
各处信息是否自洽，不存在世界观冲突。
第二优先级：语义工程质量
评估机制、信息流转、动态策略实现水平。 评价维度：
-
上下文信息准确、充分，无无效冗余； -
动态注入策略（位置、刷新、重建）匹配语义意图； -
措辞、包装、语气和信息重要程度匹配； -
整套语义机制内部自洽。
第三优先级：代码质量（独立维度）
代码架构、命名规范与语义工程相互独立。代码混乱，但语义设计优秀，Agent 依旧可以表现良好；代码工程优雅，但语义工程崩坏，运行效果依旧很差。
代码质量决定可维护性与迭代速度；长期维护下，糟糕代码会反过来拖累语义迭代。做蒸馏评估时，将代码质量作为独立可维护性指标，不和语义得分混为一谈。