xiaxi626/dsh-skills-nexus

dsh-skills-nexus

CI
dsh.so risk
dsh.so install
GitHub License

一个通用的 DSH 技能适配器。安装一次，之后即可将任意包含 SKILL.md 的 GitHub
仓库注册为 DSH 技能——每次只需一条命令。技能仓库本身保持纯净：无需 Cordis 插件代码，无需 package.json，也无需
cordis.patch.yml。

Nexus 的工作原理是将 SKILL.md 仓库克隆到本地 ~/.dsh/skills-nexus/repos/
目录，并在官方 DSH 技能根目录
（~/.dsh/skills/）中创建符号链接。官方文件系统提供程序会自动发现、
监视并提供这些技能——无需自定义提供程序或运行时扫描。

为什么

dsh plugin --profile  add "github:owner/repo" 会转发给 pnpm，并且
只有带有 dsh.bundle.patch 的包才会作为 profile 层被激活。一个仅包含
SKILL.md + references/ + scripts/ 的内容仓库没有 Cordis
包装器，因此这条路径行不通。dsh-skills-nexus 填补了这一空白：

| 命令 | 安装内容 | 需要 dsh.bundle.patch 吗？ |
|---|---|---|
| dsh plugin add github:owner/dsh-skills-nexus | nexus 本身（一次） | 是 |
| dsh-skills-nexus add github:owner/any-skill | 纯 SKILL.md 内容仓库 | 否 |

不确定哪条命令适合你的仓库？ 请阅读
nexus 与 dsh plugin —— 何时使用哪一个。
简而言之：仓库有 SKILL.md → 用 nexus；仓库是纯插件
（cordis.patch.yml / dsh.bundle.patch，没有 SKILL.md）→ 用 dsh plugin；
两者都有 → 由你选择（nexus = 内容，plugin = 代码）。

安装 nexus

全局安装 CLI——这才是将 dsh-skills-nexus 命令
放到你的 shell PATH 上的方式：

npm install -g github:xiaxi626/dsh-skills-nexus

lib/ 编译产物已随仓库提交，因此没有构建
步骤——安装即可使用。（一旦该包发布到 npm，你可以改用
npm install -g dsh-skills-nexus。）

dsh plugin add 不会提供 shell 命令。 将 nexus 注册为
DSH 插件（dsh plugin --profile web add "github:xiaxi626/dsh-skills-nexus"）
只会将该包安装到 profile 的 node_modules 中，并注册一个
Cordis 层，其 apply() 是有意为之的空操作——技能发现是通过
nexus 在 ~/.dsh/skills/ 中创建的符号链接加上官方
文件系统提供程序完成的。因此，该插件层在两方面都是可选的：它
对 CLI 没有影响，而且没有它技能也能加载——发现过程会运行
完全通过符号链接 + 官方 provider 实现。dsh-skills-nexus 命令仅来自上述全局 npm 安装（或开发期间的 npm link）。

用法

注册一个 skill 仓库（克隆到 ~/.dsh/skills-nexus/repos// 下）
dsh-skills-nexus add github:owner/repo
dsh-skills-nexus add github:owner/repo#dev          # 选择分支/标签
dsh-skills-nexus add https://github.com/owner/repo
dsh-skills-nexus add owner/repo                     # 简写形式
dsh-skills-nexus add github:owner/a github:owner/b  # 一次调用安装多个仓库
dsh-skills-nexus add github:owner/repo --yes         # 跳过“是否为包装仓库？”提示
dsh-skills-nexus add github:owner/repo --subdir skills/foo   # 仅安装集合仓库中的某个子目录
dsh-skills-nexus add github:owner/repo --subdir skills --name owner-skills   # 自定义条目名称（回退链：--name > 子目录叶子名 > 仓库名）

查看 / 维护
dsh-skills-nexus list                               # 所有已注册的 skill（+ 来源仓库、提交、子目录、状态）
dsh-skills-nexus update [name]                      # 刷新（分支固定：pull；标签/提交固定：校验）
dsh-skills-nexus enable                       # 创建符号链接（默认）
dsh-skills-nexus disable                      # 移除符号链接但不删除克隆
dsh-skills-nexus remove ...                   # 删除克隆 + 符号链接 + 取消注册（一个或多个）
dsh-skills-nexus remove 'theme-'                   # ...或使用针对 skill 名称匹配的  / ? 通配符

值选项（--name、--ref、--subdir）也接受 --flag=value 形式（例如 --subdir=skills/foo、--name=owner-skills）；布尔选项 --yes 不接受值。

add 接受多个仓库规格，remove 接受多个名称以及 /? 通配符；每个目标独立处理，只要有一个失败，退出码即为非零。由于 --name/--ref/--subdir 是按仓库设置的，它们不能与多个 add 规格组合使用——若要分别自定义，请运行单独的 add 命令。remove 通配符匹配到多个 skill 时会先列出它们并请求确认（--yes 可跳过）；请给模式加引号（'theme-'），以免被 shell 展开。

接受的仓库形式：github:owner/repo[#ref]、完整的 https:// URL（包括 /tree//... 子路径）、git+https://、git@/ssh://，以及裸 owner/repo 简写。

当你 add 一个仓库时，nexus 会在注册前检查克隆内容：

- 纯 SKILL.md 仓库 —— 直接注册。
- SKILL.md + DSH 插件包装 —— 询问是否忽略包装并按纯 SKILL.md 仓库管理。输入 y 继续，输入 n 中止并建议通过 dsh plugin add 安装。使用 --yes 跳过提示。
- 纯 DSH 插件（无 SKILL.md） —— 打印一条消息，告知你使用该仓库自己的 DSH 插件安装流程，然后退出而不注册。
- 两者皆非 —— 报告未找到 SKILL.md 或 DSH 插件标记，并以错误退出。
- 集合仓库（skills//SKILL.md 布局，例如 trae-community/trae-skills）——安装整个仓库时，根目录下不会产生任何可安装的技能；nexus 会拒绝它，并建议使用 --subdir 。如果安装产生的技能超过 20 个，会触发确认提示（可用 --yes 跳过）。

卸载

两个层级，按需选择：

移除单个技能

列出已注册的技能
dsh-skills-nexus list

移除一个（删除符号链接、克隆目录并取消注册）
dsh-skills-nexus remove

一次移除多个——按名称，或按 * / ? 通配符（需加引号）
dsh-skills-nexus remove
dsh-skills-nexus remove 'theme-' --yes

该技能会在下次重新加载时从 DSH 目录中消失。所有其他已注册的技能不受影响。

卸载 nexus 本身

Nexus 会留下三个相互独立的东西，由不同的命令清理——移除其中一个不会移除其他两个。下面带注释的代码块会逐一清除它们；只运行你需要的行即可。

每个人都会踩的坑——先读这里。 你在 shell 中输入的 dsh-skills-nexus 只来自下面的第 3 项（npm link 或 npm install -g）。--patch 只为当前 DSH 进程挂载一个层，而 dsh plugin add 只写入该 profile 的 node_modules——两者都不会在你的 shell PATH 上放置命令。所以“我安装了 GitHub 版本，但它仍然运行我本地的逻辑”意味着你输入的命令通过第 3 项的 npm link 进入了你的本地工作区；这与 GitHub 安装到第 2 项中的副本毫无关系。要真正切换到远程版本：npm uninstall -g dsh-skills-nexus，然后 npm install -g github:/。

1. 技能数据——位于 ~/.dsh/skills-nexus/ 下的克隆 + 清单（是数据，不是命令）
dsh-skills-nexus remove '' --yes          # '' 匹配所有已注册的技能

2. DSH profile 插件层——仅当你使用了 dsh plugin add 时（--patch 不会写入这里）
dsh plugin --profile web remove dsh-skills-nexus

3. 全局 CLI 命令——这才是你在 shell 中输入的 dsh-skills-nexus
npm uninstall -g dsh-skills-nexus

（可选）删除第 1 项遗留的任何技能数据目录
macOS / Linux：
rm -rf ~/.dsh/skills-nexus
Windows PowerShell：
Remove-Item -Recurse -Force ~/.dsh/skills-nexus

重启 DSH profile。插件层、CLI 命令以及所有受管理的技能都将消失。

切勿用裸的相对路径 Remove-Item -Recurse -Force dsh-skills-nexus 来“清理”：其效果取决于当前目录——在 npm 全局前缀目录下，它会删除 CLI 的 bin 垫片（命令会突然变成“未找到”），而在你克隆目录的父目录下，它会删除你的源码树。如果你确实想丢弃本地克隆，请用明确的完整路径删除它。

备用方案——手动移除（仅当 npm uninstall -g 不可用时）。
先删除 bin 垫片，再删除链接。切勿在以下情况传入 -Recurse：
移除链接：它是指向你克隆目录的一个 junction/symlink，而 -Recurse
会跟随它并删除你的源码树。

Windows PowerShell
Remove-Item -Force "$(npm prefix -g)\dsh-skills-nexus"               # bin shims
Remove-Item -Force "$(npm prefix -g)\node_modules\dsh-skills-nexus"   # the link — NO -Recurse

在 Git Bash / macOS / Linux 上，只需使用 npm uninstall -g dsh-skills-nexus；
不要在那里手动删除链接（对目录样式的链接执行 rm 是不安全的）。

本地测试步骤

你可以在自己的机器上完整测试 nexus，而无需推送到 GitHub 或
发布到 npm。请遵循以下五个步骤。

步骤 1 — 构建项目

在 dsh-skills-nexus/ 目录内：

cd dsh-skills-nexus
npm install
npm run build      # generates lib/

如果你做了更改并希望在构建前验证类型，请运行
npm run typecheck（仅类型检查，无输出）。

步骤 2 — 创建本地 overlay

在项目根目录创建 overlay.yml（注意：不要将其提交到 git，
它仅用于本地开发）：

overlay.yml
- insert:
- id: dsh-skills-nexus
Windows: '/C:/your/path/dsh-skills-nexus/lib/index.js'
macOS:   '/Users/your/path/dsh-skills-nexus/lib/index.js'
Linux:   '/home/your/path/dsh-skills-nexus/lib/index.js'
name: '/your/absolute/path/dsh-skills-nexus/lib/index.js'

name 应为 lib/index.js 的绝对路径。在 Windows 上，请在
盘符前加上 /，例如 '/C:/dev/dsh-skills-nexus/lib/index.js'；
在 macOS / Linux 上，使用标准的绝对路径，例如
'/home/user/dsh-skills-nexus/lib/index.js'。

或者用一行命令生成它（确保你已经 cd 到项目目录）：

Windows（Git Bash / MINGW）：

cat > overlay.yml  pwd -W 输出 Windows 风格的绝对路径（例如 C:/Users/xxx/dsh-skills-nexus）。
你必须在它前面加上 /，结果为 /C:/Users/xxx/dsh-skills-nexus/lib/index.js。
Node.js ESM 加载器在 Windows 上不接受裸 C:/... 路径（会将 c: 视为
协议）——它必须是 /C:/... 或 file:///C:/...。

macOS / Linux：
bash
cat > overlay.yml  pwd 输出 Unix 风格的绝对路径（例如 /Users/xxx/dsh-skills-nexus），
它已经以 / 开头，结果为 /Users/xxx/dsh-skills-nexus/lib/index.js。

步骤 3 — 以 patch 模式启动 DSH

npx @deepseek-ai/dsh web --patch overlay.yml

这会将 nexus 作为临时层挂载，仅对当前 DSH 进程生效——停止
进程后该层即消失；不会持久化到 profile 中。注意它
不会将 dsh-skills-nexus CLI 放到你的 shell PATH 上；该 shell
命令来自步骤 4 中的 npm link。更改代码后，请重新运行
npm run build 并重启 DSH 以应用更改。

步骤 4 — 添加技能并使用 CLI 测试
注意：在本地测试期间不要移动项目文件夹。如果你在 npm link 之后移动了它，重新运行 npm link 会失败并报错
EEXIST: file already exists —— 全局链接仍然指向旧的位置。请参阅下面的修复方法。

打开另一个终端：

将 CLI 全局链接以便于访问
cd dsh-skills-nexus
npm link

添加一个真实的 skill 仓库进行测试
dsh-skills-nexus add github:xiaxi626/theme-port-skill

验证它已被注册
dsh-skills-nexus list

检查是否已在官方根目录中创建符号链接
ls -la ~/.dsh/skills/

如果你移动了文件夹并且 npm link 失败并报错 EEXIST：

选项 A —— 使用 --force 覆盖（最简单，适用于所有平台）：

npm link --force

选项 B —— 使用 npm 移除过期的全局链接，然后重新链接（所有平台）：

npm uninstall -g dsh-skills-nexus
npm link

优先使用 npm uninstall -g 而不是手动删除 npm 全局前缀下的文件：
它可以在一个安全的步骤中移除 bin 垫片和链接，并避免在符号链接的全局包上
使用 Remove-Item / rm 时的误操作。

步骤 5 —— 在 DSH 中验证

注意：在步骤 3 中使用 --patch 启动的 DSH 进程是在你在步骤 4 中添加 skill
之前运行的，因此在原始 DSH 会话中询问“你有哪些 skills？”不会显示新的
skill —— provider 尚未扫描它。

你必须停止并重新启动：回到步骤 3 的终端，按 Ctrl+C 停止进程，然后重新运行：
npx @deepseek-ai/dsh web --patch overlay.yml

重启后，DSH 会重新加载文件系统 provider，它会扫描 ~/.dsh/skills/ 中的符号链接
并发现你刚刚添加的 skill。

重启后，在 DSH 会话中询问“你有哪些 skills？”或类似问题，并检查
theme-port-skill 是否出现在 skill 列表中。

本地测试后清理

--patch 没有向 profile 写入任何内容，因此没有需要移除的插件。本地测试只留下
两样东西 —— skill 数据和 npm link —— 所以请按照
卸载 nexus 本身 的第 1 项和第 3 项操作（先运行
dsh-skills-nexus remove '' --yes，然后运行 npm uninstall -g
dsh-skills-nexus）；跳过第 2 项（dsh plugin remove），它在这里不适用。

更轻量的验证（不启动 DSH）

如果你只想验证“克隆 + 创建符号链接 + 列出”的流程而不启动 DSH，请直接使用 CLI：

添加一个 skill
dsh-skills-nexus add github:xiaxi626/theme-port-skill

检查注册情况
dsh-skills-nexus list

验证符号链接已创建
ls -la ~/.dsh/skills/

如果 list 显示了预期的 skill，并且 ls -la 显示了指向 repos/ 目录的符号链接，
那么克隆 + 符号链接流程工作正常。

注意事项与限制

- 先 add 再可见：新添加的 skill 会在 DSH 重新扫描 ~/.dsh/skills/ 后出现。
如果 profile 已经在运行，请重新加载它 —— 该
官方文件系统提供程序将重新扫描 skills 根目录，并拾取新创建的符号链接。
- 版本固定与更新：使用 #branch、#tag 或 #commit-sha 固定一个 ref。安装时，清单会记录精确解析出的提交（commit）——这是一个轻量级锁，list 会显示它。update 只会快进分支固定的 skills（并打印提交变更）；标签/提交固定的 skills 是固定点：它会验证检出内容是否仍与固定点匹配（如果发生漂移则恢复它），而不是拉取，因此固定的版本永远不会悄悄漂移。当未给出 #ref 时，CLI 会通过 git ls-remote --symref 检测远程仓库的默认分支（回退到 main）。
- 仅限 skill 内容仓库：这不是对真实 Cordis 插件的 dsh plugin add 的替代。如果某个仓库已经附带 dsh.bundle.patch，请按常规方式安装它——nexus 适用于没有该文件的仓库。完整决策指南请参见 nexus vs dsh plugin。
- 集合仓库与 --subdir：集合仓库（skills 嵌套在子目录下，例如 trae-community/trae-skills）通过 --subdir  逐个安装——每次安装都是自己的条目，拥有自己的克隆（独立克隆设计，P1/P2 权衡请参见 docs/subdir-design.md）。不带 --subdir 安装整个仓库时，如果 skills 数量超过 20 个，会由确认提示进行防护。从同一仓库中挑选的条目各自保留自己的克隆，但 list 会显示 SOURCE 列（来源 owner/repo），因此同源条目很容易识别。
- 扁平 Markdown 过滤：没有 frontmatter name 和 description 的扁平 .md 文件不会被视为 skill——像 README.zh-CN.md、CONTRIBUTING.md 或 community-leaderboard.md 这样的集合仓库文档永远不会被“虚假安装”。类似文档的名称（readme、contributing、license、changelog、code-of-conduct、security）会在发现阶段被跳过。
- 名称冲突：DSH 按名称索引 skills；后安装的同名项会覆盖先前的。使用 --name 区分条目，或使用 --subdir 只安装你需要的内容。enable/disable 按条目生效，remove 会删除整个条目的克隆及其所有符号链接。
- Skill 名称验证：DSH 要求 skill 名称使用小写 kebab-case（由单个 - 分隔的 [a-z0-9]+ 段）。nexus 会在 add 时规范化无效的 frontmatter 名称（转换为 kebab-case），并用 ⚠ 发出警告。
- 构建脚本：由于 nexus 自行克隆内容仓库（而不是通过 pnpm），它完全绕过了 pnpm allowBuilds 拦截。
- Windows 链接：nexus 在 Windows 上创建目录联接（symlink(..., 'junction')），在其他平台上创建普通目录符号链接——两者都不需要开发者模式或管理员权限。

文档

- 架构——数据流、目录布局、SKILL.md 发现
- nexus 与 dsh plugin — 何时使用哪一个
- 子目录设计 — 集合仓库的 P1/P2 权衡
- 验证版本锁定功能（P0）
- 验证克隆重试功能（P0）
- 验证集合仓库支持（P1）
- 验证插件加载契约（plugin add → dsh web 冷启动）
- 贡献指南 — 项目结构、测试与 CI
- 更新日志

贡献

欢迎各种形式的贡献 — 缺陷修复、新命令、文档。
有关项目结构、本地设置和质量门禁，请参阅 CONTRIBUTING.md。

发现了缺陷或有想法？
提交 issue
— 我们使用 issue 模板，让提交更便捷。

许可证

MIT