「技能描述明明写着按 X 流程做,模型却完全没照做。」 在 DSH 排障中,这类问题并不少见,往往是因为一个前提没有厘清:技能简介是给模型「选」的,不是给模型「做」的。
排查时,常见的误判主要有六类:
- 把技能目录当成已经加载的完整指令;
- 以为提示词是每次原样粘贴的静态文件;
- 看到配置文件里有某段字符串,就认定它进了请求;
- 以为
complete: true会让工具 schema 和动态上下文一起消失; - 以为技能正文和说明会同步变化;
- 以为技能能授权工具调用。
先记住这一点:目录负责选择,正文负责执行;两者是不同时刻进入模型的两种东西。 站内基础版可参考系统提示词与技能怎样影响 Agent。
一、一个模型步骤之前会收到什么
系统提示词参考涵盖了上下文组装、有序段落、动态上下文和工具 schema这一整套内容。
Agent loop 会为即将执行的步骤组装这些输入,将段落渲染成提示词,并作为派生模型历史中的 system/message。提示词发生变化时,系统可以替换之前的节点;文档所述 in-history 模式则会追加更新。
这里需要澄清一个常见误解:它并非每次都原样粘贴一个静态文件。
技能参考描述的是另一条路径:技能消费方及其准确的工具定义可见时,可以提供会话目录,展示允许模型调用的技能名称和说明。
重点是后半句:选中后才加载完整技能正文;符合条件的用户显式调用也可以注入正文。目录用于选择,不等于完整指令。
四种输入,四种时机
| 输入 | 何时解析 | 面向模型的形式 |
|---|---|---|
| 提示词段落 | 组装提示词时 | 渲染后的系统消息 |
| 动态上下文 | 组装和准入刷新时 | 用户角色上下文快照 |
| 技能目录 | 符合条件的步骤前发现 | 持久化的用户角色提醒 |
| 已加载技能 | 工具调用或用户显式调用时 | 工具历史或注入的用户上下文 |
阅读这张表时,建议先看「面向模型的形式」这一列——同样是「影响模型」,落在历史里的位置完全不同。
二、系统提示词怎么组装
1. 段落的排序规则
PromptSection 有唯一名称、顺序,以及静态文本或按上下文计算的文本。
排序规则有两条,其中第二条容易被忽略:
- 先按顺序升序排列;
- 顺序相同时,按名称的代码单元顺序排列。
因此,发生同名冲突时,顺序不是由书写顺序决定,而是按代码单元顺序。
另外:作用域贡献可以遮蔽同名全局贡献。
2. 变量插值:失败不静默
默认情况下,文本中的变量会被插值;设置 interpolate: false 可保留原文。
有一条很硬的规定:无法解析的变量会使组装失败,而不是静默发送一个看似完整的提示词。
这其实是个好消息——组装失败是可见的,静默漏掉才是危险的。
3. complete: true 到底做了什么
系统提示词包说明介绍 Harness 身份、部署 persona 前后缀、可选运行时上下文和工具排序的配置。
它还介绍 complete: true 段落:协作组装完成后,它成为唯一提示词段落;存在多个生效的 complete 段落则组装失败。
但还需要明确一条边界:这不表示工具 schema 或动态上下文消失——它们是另外解析的组装部分。
4. 动态上下文不是段落的别名
动态 PromptContext 不是系统段落的另一个名字。
内容改变、或压缩移除它之后,loop 会把当前快照作为用户角色上下文记录。
作用域方面:作用域可以抑制可选运行时上下文,而标记为 required 的贡献仍会保留。
因此,比较两个 Agent 收到的内容时,需要考虑部署的作用域、配置和实际启用的插件——不能只比对源码。
5. 判断时遵循的原则
例如,部署 persona 可以规定一般答复风格,另一个插件提供工具使用说明。这些段落有各自顺序,作用域同名项还能改变最终选择。
因此,要判断一条指令是否进入请求,需要查看实际组装结果,不能只搜索某个插件源码或查看配置文件中的字符串。
三、技能怎么变成可用指令
1. 注册表与目录
技能注册表合并全局和作用域提供方;提供方可以列出候选项并加载选中的定义。
面向模型的目录只包含名称和规范化后的说明,不包含所有完整正文,也不包含绝对路径。
发现过程使用会话当前工作目录——这一点和上一节的路径解析是同一条线索。
2. 两个独立的控制项
用户调用和模型调用是两个独立控制项:一个技能可以对用户、对模型、对双方,或都不可调用。
因此,技能出现在列表中,并不能说明谁能调用它;需要分别检查这两个开关。
3. 两条加载路径
技能工具包说明描述了两条:
- 模型用准确名称调用
skill,把正文和资源指引作为工具历史接收; - 直接用户消息中出现匹配用户可调用技能的
/name标记时,也可以把同一种渲染后的指令内容注入当前步骤。
同时,目录会提示模型遵循已经注入的正文,不要重复加载。
但要记住:看到技能说明本身并不会自动加载指令。
4. 不完整与失效怎么表现
- 不完整的发现结果可以带警告列出已确认候选项,后续会重试;它不是权威的完整视图;
- 目录发布后,如果工具可见性丢失、或所有技能被移除,会追加空的替换目录,明确停用旧名称。
后一种情况需要注意:空目录是一种明确信号,不是「什么都没有发生」。
5. 正文会变,说明不一定变
技能正文可能改变而说明不变,因此后续加载可能读到不同内容,即使目录条目没有变化。
这也解释了一类很难复现的问题:同一个技能,两次调用得到的行为不一样——因为中间正文被改了,而目录看起来毫无变化。
四、行为不符合预期时怎么追
1. 五步
- 确定 Agent、会话和当前工作目录,检查提示词与技能插件是否真的组合在一起,以及该作用域是否能看到准确的
skill工具定义。 - 检查已渲染的系统段落和适用的运行时上下文,核对段落顺序、作用域遮蔽、persona 模板和变量错误。不要假定每个插件都向每个 Agent 贡献内容。
- 检查当前技能目录及其完整性。缺少相关技能时,查看提供方发现、调用策略和作用域;暂时不完整的观察不能证明技能已经删除。
- 确认完整正文是否真的通过工具加载、或由用户显式调用注入。读取当前正文和相关资源;仅凭目录说明无法还原模型收到的全部指令。
- 将这些输入与实际工具调用和结果对照。如果行为依赖外部操作,还需分别检查其权限及执行结果——提示词或技能正文不会自行完成操作。
2. 一个典型时序
同一会话先展示某个技能的简介,之后用户明确调用该技能,模型才收到完整步骤。
随后技能文件被修改,下一次加载可能得到新正文,但先前工具结果不会被追溯改写。
因此,把目录、加载结果和系统提示词作为独立证据,有助于解释为什么两次请求的任务指引不同。
3. 三个「看起来像 bug」的正常行为
- 技能列出了但模型没照做——目录不是指令,正文还没加载;
- 提示词里少了某段——可能被作用域遮蔽,或那个插件本就没贡献;
- 两次调用行为不同——正文变了但说明没变。
五、限制与安全边界
- 文档描述的是输入如何到达模型,并不保证模型一定遵循所有指令或选择正确技能。
- 技能是指令内容,不是授权,也不是安全边界。 工具调用仍受自身注册、限制、沙箱和审批策略约束。
- 执行前应检查技能来源、引用资源和请求产生的实际影响。
- 上下文可能包含敏感的工作区信息,技能及其资源也可能包含敏感指令或路径。检查发送给模型的内容,分享诊断前删除不必要的信息。
- 提供方已注册、技能已列出、或提示词组装成功,都不能证明内容可信。
- 作用域规则说明的是同名贡献如何选择,并没有给出解决所有自然语言冲突的通用优先级。 指令冲突时,应检查实际来源以及适用的用户和部署要求。
- 不要从技能简介猜测尚未加载的隐藏正文。
- 变量解析失败会让组装失败:这是可见信号,不要绕过它去猜「大概就是这样」。
complete: true不消除工具 schema 与动态上下文:它们另行解析,别把「唯一段落」误读成「唯一输入」。
六、术语速查
- 提示词段落:按顺序渲染到系统提示词的贡献。
- 动态上下文:以用户角色快照呈现的运行时信息。
- 技能目录:可发现的名称和说明,而非完整正文。
- 提供方:列出技能候选项并加载定义的来源。
- 作用域:为某个 Agent 选择或遮蔽贡献的层。
相关阅读
本文依据 DeepSeek Harness 官方系统提示词参考、技能参考、系统提示词包说明与技能工具包说明整理,由 DSH Plugin 社区(dsh-plugin.com)维护者撰写,首发于阿里云开发者社区。
原文地址:https://dsh-plugin.com/zh/blog/system-prompts-and-skills-influence-an-agent
插件与文档收录于:https://dsh-plugin.com/zh/blog