ChatGPTClaudeGrok / X / CursorGemini

DeepSeek Harness 技能装上不生效:SKILL.md 只扫一层导致整类全部丢失

故障排查发布于 2026-11-03作者: DeepSeek Plugin 插件市场
DeepSeek Harness技能发现SKILL.mdskill-filesystem分类目录静默失败
按 <root>/<category>/<skill>/SKILL.md 摆放技能库后整类不可见,无警告也无日志。原因是 dsh-skill-filesystem 每个根只扫一层,目录过不了形状检查就被静默 continue。本文讲清发现层的边界、扁平化规避与诊断提案。

DeepSeek Harness(DSH)里最常见的一句「技能装了不生效」,有一个很容易被误判成配置写错的原因:技能发现只扫描一层。 @deepseek-ai/dsh-skill-filesystem 从一组固定根发现技能,每个根只扫一层;如果你的库按 library/category-a/skill-1/SKILL.md 这样组织,那么 category-a 这一层没有 SKILL.md,形状检查失败,被一句裸 continue 静默丢掉——期望 3 个技能,实际 0 个,无警告、无日志。这属于设计限制,不是回归:社区回复交叉引用 #9608 与 #9375,确认它是技能面「发现层」的静默失败,而这三层里只有这一层完全没有诊断(#11898)。

先复现:三层目录摆好后是零技能

关键判据是:把根指向分类目录的父级时技能数为 0,指向分类目录本身时技能数正常。 步骤:

  1. 按分类结构摆放技能库。
text
library/
  category-a/
    skill-1/SKILL.md
    skill-2/SKILL.md
  category-b/
    skill-3/SKILL.md
  1. 把 customSkillDirs 指向库根。
yaml
- id: skill-filesystem
  config:
    customSkillDirs:
      - /path/to/library

预期:技能列表里 0 个,日志里没有任何「跳过」「拒绝」「无法识别」的行。

  1. 把 customSkillDirs 改成逐个分类目录。
yaml
    customSkillDirs:
      - /path/to/library/category-a
      - /path/to/library/category-b

预期:3 个技能全部出现。这一步很关键:它证明技能文件本身没问题,问题只在「根与技能之间隔了几层」。

  1. 确认没有别的原因。 若第 3 步仍然 0 个,方向应转到观测层(complete:false)或渲染层(whenToUse),不要套用本篇结论。

代码位置:locator 为 undefined 的那一句 continue

一句话结论:discoverRoot() 对每个直接子项要求 <child>/SKILL.md,分类目录没有这个文件,于是 locator 为空、被跳过。 逻辑拆开看:

  1. 目录项的处理:子项是目录时,locator 为 { path: join(entry.path, 'SKILL.md'), directory: entry.path }。
  2. 文件项的处理:子项以 .md 结尾时,locator 指向该文件,directory 取根路径。
  3. 其它情况:locator 为 void 0,紧接着 if (locator === void 0) continue;——分类目录正好落在这一支,注释原文写着 a category is dropped here, silently。
  4. 第二处静默:parseSkillFile 返回 undefined 时同样 continue,没有任何日志。
  5. watch 也是 depth: 1:这与 #9608 里指出的 watch 深度一致,说明「一层」不只是扫描策略,也是观测策略。

所以这不是「文件权限」或「YAML 写错」能解释的现象:目录确实被看到了,只是在形状检查处被判定「不是技能目录」。

两个旋钮都拼不出「项目级 + 分类粒度」

一句话结论:roots() 的项目层是两个写死路径,customSkillDirs 是宿主/预设级,任意组合都无法表达「这个项目只看分类 A」。 事实清单:

  1. 项目层固定:<project>/.dsh/skills 与 <project>/.agents/skills 由 roots() 硬编码,没有配置入口。
  2. 自定义目录全局:customSkillDirs 挂在 provider 上,改了它对整个宿主或预设生效,无法按项目区分。
  3. 唯一可行的项目级手段是逐技能建链接:在 <project>/.dsh/skills 里一个技能一个链接,每个项目 O(n),库一增长就要重做,而且把「来源」和「技能」两件事混成一件。
  4. 没有诊断出口:SkillCatalogSnapshot 只有 { skills, complete },没有 reason,消费方即使想解释也说不清是哪个根。

这也是为什么「分类目录不可见」和「技能库不可移植」经常一起出现:它们来自同一套根模型。

规避:扁平化,或者逐分类枚举

一句话结论:不改源码的前提下,要么把技能拍平到根下一层,要么把每个分类目录单独登记;两者都能用,但都牺牲了分类组织的便利。 两个方案:

  1. 扁平化:把 library/category-a/skill-1/ 整体移到 library/skill-1/,保证 <root>/<skill>/SKILL.md 成立。预期:技能全部可见。代价是失去分类层级,只能靠命名前缀区分。
  2. 逐分类枚举:每个分类目录写进 customSkillDirs。预期:3 个技能可见。代价是库一增长就要改配置,而且作用域是整个宿主或预设。
  3. 链接方案:在项目级固定根里为每个技能建一个链接。预期:项目内可见。代价是 O(n) 维护,且与「来源」语义混淆。
  4. 升级前先自检:改完配置后重启,确认技能数符合预期,并留意 complete 字段是否变化——它至少能告诉你「有根没观测成功」。

三层静默失败:先分清你遇到的是哪一层

一句话结论:发现层、观测层、渲染层的症状相似但机制不同,混着查会互相误导。 对照:

层次症状是否有日志关键位置
发现层(本篇)整类技能不可见完全没有discoverRoot() 的裸 continue
观测层(#9608)一个根 watch 失败,整组 complete:falsereplaceWatcher 有日志逐根失败使整次观测失效
渲染层(#9375)whenToUse 写了但模型看不到无渲染时字段被丢弃

三层的共同点是「都不报错」,差别在于能不能从代码或日志里读出来:渲染层的字段被解析、校验、带到客户端后才丢,读代码即可确认;观测层至少有日志;发现层连「这个目录存在过」都无法被下游推断。

想让失败可见:在形状检查处补一条 warn

一句话结论:最小、最便宜的改进是在 locator === undefined 处打一条带路径的 warning,行为完全不变,只让静默变可见。 讨论里给出的提案按成本排序:

  1. 每个根一条 warning,例如 skill-filesystem: <root>/<dir> contains SKILL.md at depth 2 but is not a skill directory; ignored。它不需要新增配置面,只要一行日志。
  2. 增加 maxDepth 配置,默认 1。设为 2 即可直接发现 <category>/<skill>/SKILL.md,对现有部署零影响——默认值保持旧行为。
  3. 项目级追加根,例如 <project>/.dsh/skills.yml 里声明 roots:。配合第 2 条,「这个项目只看分类 A」就从 N 条链接变成一行声明。
  4. 可选:customSkillDirs 支持通配符(/path/to/library/*)。这是锦上添花,不是必需。
  5. 作用域要静态:提案特别强调第 3 条是「项目生命周期内静态」的,目录前缀稳定,KV cache 复用不受影响;刻意不做每轮动态裁剪,因为逐轮变化会破坏缓存前缀,净收益为负。

修复状态与预期

一句话结论:截至该讨论没有上游修复记录,也没有补丁分支;用户侧只能按上面的方式规避,或等 maxDepth 一类的能力落地。 三点说明:

  1. 性质:设计限制,不是回归。所以「换回旧版本就好了」这种思路不成立。
  2. 可观测性:当前连 complete:false 都可能不出现——它覆盖的是观测失败,不覆盖「目录被拒绝」。这也是提案把 warn 放在第一位的原因。
  3. 上报方式:仓库 CONTRIBUTING.md 说明当前不接受外部 PR,反馈走 Discussions;附上目录结构、customSkillDirs 配置与实际技能数,能省掉一轮澄清。

排查注意事项

技能不生效的排查原则是:先数技能数,再看目录层级,最后才看渲染字段。 六条要点:

  1. 先确认「0 个」还是「少了几个」:0 个多半是根层级问题,少了几个才去看观测或渲染。
  2. 把根指向分类目录本身做对照,能一步证明文件没坏。
  3. 别忽略「无日志」这个信号:发现层的特点就是完全没有输出,不是日志被过滤了。
  4. 扁平化是最省事的规避,先让技能跑起来,再谈分类组织。
  5. 区分三层,不要把 whenToUse 不生效当成发现失败。
  6. 升级或改配置后复查技能数,这类静默失败不会主动提醒你。

来源:Discussion #11898,相关讨论 #9608、#9375。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DeepSeek Harness 技能按分类目录摆放后一个都加载不出来,也没有日志,为什么?

因为 DeepSeek Harness 的 dsh-skill-filesystem 对每个根只扫描一层。它要求根的直接子项是技能目录并通过 <child>/SKILL.md 形状检查,而 category-a 这一层没有 SKILL.md,locator 为 undefined,被一句裸 continue 丢掉,所以零技能、零警告。

DeepSeek Harness 的技能发现只扫一层,是 bug 还是设计限制?

这属于 DeepSeek Harness 的设计限制,而不是回归。回复者交叉引用 #9608 与 #9375,确认这是同一族问题的发现层,watch 也是 depth: 1 但那是设计。它不需要改代码才能识别的渲染或观测缺陷,而是发现层本身没有二级目录语义。

不改 DeepSeek Harness 源码,怎么让按分类组织的技能被加载出来?

在 DeepSeek Harness 里把技能目录扁平化到根下一层,即 SKILL.md 直接放在 <root>/<skill>/SKILL.md。或者把 customSkillDirs 分别指向每个分类目录,例如 /path/to/library/category-a,代价是逐分类枚举,而且作用域是整个宿主或预设。

DeepSeek Harness 技能不可见,和 whenToUse 不渲染、complete:false 是一回事吗?

不是,在 DeepSeek Harness 里它们是技能面三层不同的静默失败。本条是发现层:目录被看到但不被识别,完全无日志;#9608 是观测层:某个根 watch 失败会让整组 complete 变 false,至少 replaceWatcher 有日志;#9375 是渲染层:whenToUse 被解析校验后,在渲染时被丢弃。

相关术语

discoverRoot
discoverRoot 是 dsh-skill-filesystem 里逐个根枚举技能目录的函数。它对每个直接子项做形状检查:目录要求存在 <child>/SKILL.md,文件要求以 .md 结尾;不符合的项被 continue 跳过,不会产生任何日志。— https://github.com/deepseek-ai/deepseek-harness/discussions/11898
customSkillDirs
customSkillDirs 是 dsh-skill-filesystem 的配置项,用于在默认根之外追加技能目录。它作用于宿主或预设级别,不是项目级别,因此无法表达「这个项目只看某个分类」这种作用域。— https://github.com/deepseek-ai/deepseek-harness/discussions/11898
SkillCatalogSnapshot
SkillCatalogSnapshot 是技能目录对外暴露的快照类型,字段只有 { skills, complete },没有 reason 字段。因此即便消费方想解释「为什么少了某个根」,也无从说明是哪一层、哪个路径出的问题。— https://github.com/deepseek-ai/deepseek-harness/discussions/11898

来源