技能捆绑盒lihuu/dsh-lazy-skill

dsh-skill-bundle

一个用于 DeepSeek Harness 的插件，
它将相关技能分组到捆绑盒（bundle boxes）中。每个盒子有一个根（root）
技能和任意数量的子技能（sub-skills）；盒子可以通过 frontmatter
元数据（loadSubskills）加载，也可以让模型根据正文内容自行决定。

它以自激活的 Harness bundle 形式发布：安装 npm 包会添加一个补丁层，插入插件行，因此无需手动打补丁或创建符号链接。

为什么存在

Harness 已经允许模型按需加载技能，这对于少量不相关的技能来说效果很好。而一族相关技能——一个工具链、一个分阶段工作流、一个包含多个子任务的项目——在朴素做法下会产生实实在在的成本：

每个已安装的技能都会在每次相关提示的  目录中贡献一个模型可调用的名称和描述。因此，作为平级兄弟技能安装的一组技能会扩展该目录（以及它所消耗的提示预算），即使当前任务从未触及该组。已加载的技能正文只有在工具或斜杠调用之后才会进入上下文，但每个兄弟技能的摘要始终存在——浪费 token、膨胀上下文窗口、破坏 KV-cache 复用，并拖慢每一轮。

由此产生两个症状：

1. 上下文污染——不相关的组仍然通过其目录摘要消耗提示预算。
2. 不必要的问题——当上下文中存在许多兄弟技能摘要时，模型会偏离方向，去询问该使用哪一部分，而不是直接工作。

dsh-skill-bundle 让加载变得显式且按需：

- 一个组（一个捆绑盒）作为一个小的根技能暴露。
- 它的子技能不会预先编入目录。只有当盒子通过 loadSubskills 被拉入时，它们才会加载——而且只加载列出的那些。
- 在你请求之前，该组中的任何内容都不在上下文中。

你可以按盒子选择退出：没有 loadSubskills 时，盒子返回其简短的根正文，模型遵循该文本，这适用于你确实希望始终存在的盒子。

示例——一个“deploy”捆绑包

每次部署三个步骤：build、push、rollback。将它们包装在一个盒子中：

boxes/deploy/
SKILL.md          # 根技能，frontmatter 中有 loadSubskills
build/SKILL.md
push/SKILL.md
rollback/SKILL.md

使用 loadSubskills 时，告诉模型使用 deploy 会一次性加载全部三个子技能正文——它立即拥有 build/push/rollback 指令，可以运行整个部署，而无需询问“哪一个？”。

不使用它时，deploy 只返回其简短的正文文本，模型阅读并遵循该文本。

功能

- 捆绑盒——一个目录，包含一个根 SKILL.md 以及同级的子技能目录，每个子技能目录都有自己的 SKILL.md。
- 两种加载规则，由根技能的 frontmatter 决定：

| 根 frontmatter | 加载时盒子产生的内容 |
|---|---|
| loadSubskills: true | 每个子技能正文，按目录顺序（忽略根正文） |
| loadSubskills: [a, b] | 仅子技能 a + b 的正文，按该顺序（忽略根正文） |
| 无 loadSubskills | 根正文原样保留；由模型根据其文本自行决定 |

- 每个展开的子技能保留自己的身份和资源目录：
正文渲染为一个 skill_content 块，其资源基址为子技能自己的目录，
因此其中的相对路径能正确解析。
- 无效的 loadSubskills 值会显式报错（类型错误、未知子技能名，
或重复名称），而不是静默生成部分内容。
- 面向模型的工具：skill_browse（列出某个 box 的子技能名称——
仅摘要）、skill_load（按精确名称加载一个或多个技能），以及
用于根调用的标准 skill 工具。
- 无框架改动——一个普通的 Cordis 插件。

要求

- 一个可用的 DeepSeek Harness 安装（dsh），例如 dsh --profile web。

安装

该包是一个 Harness bundle：它声明了 dsh.bundle，并附带一个
预构建的 lib/ 以及默认的 boxes/，因此安装机器上无需构建工具链。

dsh plugin --profile web add @lihuu/dsh-skill-bundle
dsh --profile web --dump-config

第二条命令必须显示一个 dsh-skill-bundle 层。bundle 成员变更后，
正在运行的 profile 必须重启。

使用你自己的 boxes

默认情况下，插件在其安装包旁边解析 boxes（boxes/）。
要将其指向你自己的目录，请添加一个更靠后的补丁行（profile 或 home
级别），用相同的 id/name 和绝对路径 boxesDir 替换插入的行：

- insert:
- id: dsh-skill-bundle
name: '@lihuu/dsh-skill-bundle'
config:
boxesDir: /absolute/path/to/your/boxes

Harness 补丁行会替换完整的配置值，而不是深度合并它们，
因此请重新声明你需要的每个字段。

从源码构建（开发者）

npm install        # installs typescript + dev dependencies
npm run build      # tsc compiles src/ -> lib/
npm test           # build + node --test tests/*.test.mjs

lib/ 和 node_modules/ 已被 git 忽略；它们是重新构建的，而非提交的。

激活语义

- 每个 box 贡献一个模型可调用的根候选。
- 子候选对模型目录保持隐藏（modelInvocable:
false），并且仍可通过 Harness 斜杠调用直接由用户调用。
- 没有 loadSubskills 的根会原样返回自己的正文。
- loadSubskills: true 会按确定性（目录名）顺序展开每个直接子技能。
- loadSubskills: [name, ...] 会按声明的顺序精确展开那些子技能，
并忽略根正文。
- 激活后，子技能不会成为新的模型可见目录行；
skill_load 是用于精确加载隐藏子技能的模型工具。

创建技能 bundle

一个 box 只是一个目录。例如随附的 dsh-skill-bundle-guides box：

boxes/
dsh-skill-bundle-guides/
SKILL.md              # root skill
install-plugin/SKILL.md
create-bundle/SKILL.md
bundle-from-skills/SKILL.md
fix-frontmatter/SKILL.md

每个 SKILL.md 都需要在其 frontmatter 中包含 name + description：

name: dsh-skill-bundle-guides
description: "使用此插件的指南。"
loadSubskills:          # 可选：自动加载这些子技能
- install-plugin
- create-bundle
- bundle-from-skills
- fix-frontmatter

正文内容（当存在 loadSubskills 时会被忽略）。

子技能也是普通技能：

name: install-plugin
description: "如何安装 dsh-skill-bundle。"

如何安装此插件……

YAML 陷阱

YAML 1.2（此插件所使用的版本）会拒绝看起来像“紧凑映射”的普通标量。
如果某个值——例如 description——在冒号旁边包含逗号（a: x, b, c），
请用双引号将其包裹起来：

description: "a, b, c: 由于逗号/冒号而需要加引号"

许可证

MIT