@sidleo3/skill-filesystem-plus

English | 中文

为 DeepSeek Harness（DSH）提供的可配置技能发现提供方，按 preset 选择性接管内置 dsh-skill-filesystem 的固定发现逻辑——四层扫描 + 可编辑的上级目录名，只在用户显式勾选的 preset 中生效。

本项目由 @sidleo3/skill-scan 更名而来；GitHub 仓库已改名为 sidleo/skill-filesystem-plus。旧配置（~/.dsh/dsh-skill-scan.json）会自动迁移。

核心设计

• 安装零改动：插件安装后不做任何事，不复制、不修改任何 preset，内置 skill-filesystem 照常工作
• 用户决定生效范围：在 Web GUI（侧栏 → 插件 → 本插件的配置页）里勾选要接管的 preset（多选）
• 完全替代：勾选某个 preset 后，profile 的 cordis.patch.yml 里写入该 preset 的 preset-<id> 覆盖行（内置 skill-filesystem 行 disabled，并接入本插件的 /preset provider 行）；未勾选的 preset 完全保持内置行为
• 取消即恢复：取消勾选只删除本插件自己那条覆盖行，其余 patch 条目逐字节不变
• 配置页跨 DSH 升级稳定：页面注册进侧栏插件页的 plugins.bundle.config 插槽（以包名为 key），配置数据存在本插件自己的 JSON 文件里，不依赖 DSH 的设置命名空间

功能

| 层级 | 优先级 | 扫描路径 | |---|---|---| | cwd（会话工作目录） | 最高 | <cwd>/<上级目录>/skills | | 项目目录（最近含 .git 的祖先） | 中 — 与「上级遍历」互斥 | <项目根>/<上级目录>/skills | | 上级遍历（从 cwd 向上逐级） | 中 — 与「项目目录」互斥 | 每个祖先的 <上级目录>/skills | | 全局（用户主目录 ~） | 最低 | ~/<上级目录>/skills |

• 可编辑上级目录 — 默认 .dsh、.agents；可增删改，并拖动排序调整优先级（越靠上越优先）。
• 互斥二选一 — 项目目录扫描与上级遍历只能开一个（UI 与宿主双重校验）。
• 技能格式 — 目录包（<名称>/SKILL.md）与平铺 Markdown 文件（<名称>.md）；解析 frontmatter 的 name、description、whenToUse、disable-model-invocation、user-invocable。
• 重名裁决 — 不同名技能全部加载；同名的只保留优先级最高（rank 最小）者。
• 即时失效 — 模型 write/edit 命中 <…>/skills/ 路径时立即刷新技能目录。
• 独立配置页 — 侧栏 → 插件 → 本插件卡片 → 配置，与内置插件配置页同一套 --dsw-alias-* token。

安装

从 npm 在线安装

dsh plugin --profile <profile> add @sidleo3/skill-filesystem-plus

dsh plugin 会把参数转发给 profile 目录里的 pnpm，并自动激活声明了 dsh.bundle 的包。装完重启 DSH 即可。

从本地 checkout 以 link 方式安装

git clone https://github.com/sidleo/skill-filesystem-plus.git
dsh plugin --profile <profile> add link:<仓库路径>

以 git 仓库方式安装（pnpm add github:user/repo）时，需在 profile 的 pnpm-workspace.yaml 里的 allowBuilds 中加入对应的包（pnpm 10+）。

使用：在 GUI 中按 preset 启用

1. 打开侧栏 插件，找到本插件卡片，进入它的配置页
2. 在「生效的预设」列表里勾选要接管的 preset（多选，只列出可接管的预设）
3. 勾选后写入 profile 的 cordis.patch.yml：新增一条 - id: preset-<id> 覆盖行，整份复制该预设的内置插件行、把 skill-filesystem 标为 disabled: true，并在末尾追加 @sidleo3/skill-filesystem-plus/preset 行
4. 重启 DSH 后，新会话选择该 preset 时使用本插件的四层扫描发现技能
5. 取消勾选 = 只删除本插件那条覆盖行，其他 patch 条目一字不动

已运行中的会话不受勾选/取消影响（preset 组合在会话创建时固定）；改动对之后新建的会话生效。

配置

所有设置都在插件配置页里（侧栏 → 插件 → 本插件 → 配置）：

• 四个层级开关。
• 上级目录列表：拖动排序优先级、逐行删除。
• 当前会话 cwd 的扫描根实时预览。
• 调试面板：列出实际发现到的技能。
• 保存即写回并刷新技能目录。

配置持久化在 ~/.dsh/dsh-skill-filesystem-plus.json（旧名 dsh-skill-scan.json 自动迁移）。

工作原理

1. Install = no-op：host 入口只暴露 GUI RPC + 声明 Config schema，不碰任何 preset
2. User picks presets：GUI 调 /api/skill-filesystem-plus/presets/apply，host 读取内置预设组合（dsh-agent-preset 声明式行的 presets/<id>.patch.yml）→ 备份 profile patch → 在 cordis.patch.yml 写入 preset-<id> 覆盖行（内置行逐行抄录，skill-filesystem 标 disabled: true，追加 /preset 行）
3. Discovery：该 preset 层里 /preset 行的 provider 在该预设层注册（skills.registerProvider 是 scope-aware），按四层扫描发现技能，完全替代内置发现
4. Removal：GUI 调 /api/skill-filesystem-plus/presets/remove，只删除本插件那条 preset-<id> 覆盖行
5. Config live-reload：provider 每次 list 都通过 ctx.fs 重读磁盘配置，GUI 保存后下一次目录刷新即生效

patch 用的是 replace 语义（不是 merge），所以覆盖行必须整份复制该预设的插件行；编辑一律按行进行，绝不 parse→re-serialize——预设行含 !!js 标签（如 disabled: !!js process.platform === 'win32'），整份解析会把标签求值成字符串，disabled 变成真值导致 shell 工具静默消失。

为什么需要「替换」

DSH 对同名技能先按层再按 rank 裁决。只要内置 skill-filesystem 仍挂在预设层，同名的就会被它赢走，与你配置的 rank 无关——所以要让「重名按优先级」真正生效，必须把该 preset 的 skill-filesystem 行禁用、改由本插件 provider 提供。

开源说明

本仓库是正式包形态，代码先在 DSH 动态插件（skf-1）中实测通过后迁入。src/ 是正式包源码；skill-scan-blueprint/ 保留更名前的动态插件形态作参考（不参与构建）。

自行发布：

pnpm install
pnpm build      # tsdown → lib/index.js + lib/preset.js + lib/client.js
npm publish

宿主端依赖 DSH 私有包（@deepseek-ai/dsh-skill、@deepseek-ai/dsh-agent-preset、@deepseek-ai/dsh-agent-preset-registry 等）。请在能解析到这些包的环境中构建；本包将其声明为 peerDependencies / devDependencies。

兼容性

适配 DSH 0.1.7-alpha 起：

• 配置页位于侧栏插件页的 plugins.bundle.config 插槽（0.1.7 起 Settings 的「插件」分区变为只读内置清单，旧的 settings.plugin.item 插槽已不存在）
• 预设接管通过 profile 的 cordis.patch.yml 覆盖行实现（agentPresetRegistry 的 list()/resolve() 只返回展示元信息，没有组合路径、没有 read/write）
• 配置数据仍存本插件自己的 ~/.dsh/dsh-skill-filesystem-plus.json

License

MIT