🚀 快速安装

dsh plugin --profile web add @existence001100/dsh-skills-manager

安装后请重启 Web profile。安装前请查看环境要求与安装选项。

1.1.1 变更： 模型发起的 skill_manager install 或 skill_manager update 现在需要一次审批决定。要恢复 1.0.x 行为，请运行 skill_manager set-config config={"installGate":"off"}。详见安装确认门控。

🚀 安装 · ✨ 功能 · ⚙️ 配置 · 🐛 反馈

目录

• 为什么需要这个插件
• 核心特性
• 工作原理
• 快速开始
• 兼容性
• Skill 配置
• Hook 兼容性
• GitHub 托管的 Skills
• 安装确认门控
• 候选目录
• 项目级 Skills
• 管理与可观测性
• 权限与数据
• 安全
• 明确不做的决策
• 开发

为什么需要这个插件

DSH 内置的 skill 工具依赖模型先注意到一段简短摘要，再自行决定是否加载完整 Skill。实际使用中，模型经常错过有价值的 Skill；Skill 文件无法直接声明生命周期行为；散落在本地的 Skill 也很难持续同步。

dsh-skills-manager 补齐了这些能力：

• 每轮请求都主动匹配可用 Skill；
• 强匹配自动加载，弱匹配轻量提醒；
• 将 Claude Code 风格的 Hook 声明映射到 DSH 宿主事件；
• 从 GitHub 安装、更新和卸载 Skill；
• 隔离用户级与项目级覆盖配置；
• 同时提供 Settings 界面和 skill_manager 模型工具。

核心特性

图标	功能	说明
🚀	主动激活	强匹配注入完整 Skill，建议匹配只注入轻量提醒
🪝	Skill 级 Hook	支持 UserPromptSubmit、PreToolUse、PostToolUse、PostToolUseFailure 和 SessionStart
🔄	GitHub 生命周期	安装、更新、权威同步、卸载和 commit 变更报告
🧭	Workspace 作用域	项目 Skill 可覆盖用户 Skill，同时避免配置跨 workspace 泄漏
🛠️	内置管理	Settings 管理界面与 skill_manager 模型工具
🛂	安装确认门控	模型发起的 install / update 先请求一次审批；无审批通道时 fail-closed
🧩	能力缺口提案	可选候选目录提出缺失技能建议；每轮最多一条，绝不自动安装
🛡️	安全护栏	来源白名单、Git 参数数组、Hook 路径校验，Hook 不经过 shell

工作原理

flowchart LR
    U[用户消息] --> M[步骤前匹配器]
    M -->|auto| A[注入完整 Skill]
    M -->|suggest| S[注入轻量提醒]
    M -->|缺口| P2[候选目录]
    P2 -->|可选开启| PR[注入提案]
    T[工具调用] --> P[PreToolUse 策略]
    R[工具结果] --> O[PostToolUse 激活]
    I[模型调用 install/update] --> G{安装门控}
    G -->|allowed-once| Y[Git 克隆或拉取]
    G -->|拒绝 / 通道缺失| D[拒绝并附降级说明]
    Y --> C[DSH Skill 目录]
    C --> M

每个 Agent 步骤开始前，插件都会为可用 Skill 打分：

1. 明确提及 Skill 名称：+12；
2. 命中触发词或正则表达式：+7；
3. 描述或 whenToUse 词元重合：+4 到 +6。

默认每轮最多自动加载 2 个 Skill、建议 3 个。激活标记会写入会话历史；只要标记仍在可见上下文中，就不会重复注入完整内容。上下文压缩移除标记后，Skill 可以再次自动加载。

两条独立约束保证模型不会自作主张：

• 安装确认门控。 模型发起的 skill_manager install 与 skill_manager update 在执行任何 Git 命令之前，都会先向宿主审批接缝请求一次决定。只有 allowed-once 才继续；拒绝、取消、通道缺失或请求抛错一律 deny。模型会收到降级说明和结构化 code（见安装确认门控）。
• 能力缺口提案。 当可选的候选目录列出了尚未安装的来源时，匹配器可以在该轮首个 step 注入一条提案。提案属于模型上下文，不是 UI 卡片，也绝不会自动安装——模型仍需调用 install，而该调用会被上面的门控拦截。该分支默认关闭；目录缺失、分数不足、或声明的技能都已安装时保持静默（见候选目录）。

快速开始

环境要求

• DeepSeek Harness 0.1.1-rc.2、0.1.2-alpha.3、0.1.3-alpha.1 或 0.2.0-rc.2；
• Node.js ^22.19.0 || >=24.0.0；
• PATH 中存在 pnpm，供 dsh plugin 调用。

从 npm 安装（推荐）

dsh plugin --profile web add @existence001100/dsh-skills-manager

DSH 会识别包内的 dsh.bundle manifest，并自动把 @existence001100/dsh-skills-manager 加入 Web Profile。安装完成后，请重启正在运行的 Web Profile。

从 GitHub 安装

dsh plugin --profile web add github:Existence001100/dsh-skills-manager

需要测试 main 中尚未发布的变更时，可以使用 GitHub 来源；如需可复现安装，请固定到具体 commit。

更新或卸载

dsh plugin --profile web update @existence001100/dsh-skills-manager
dsh plugin --profile web remove @existence001100/dsh-skills-manager

执行任一操作后请重启 Profile，确保运行时 composition 与已安装 Bundle 一致。

安装本地 Checkout 进行开发

git clone https://github.com/Existence001100/dsh-skills-manager.git
cd dsh-skills-manager
pnpm install --frozen-lockfile
dsh plugin --profile web add .

插件自带的 cordis.patch.yml 会把 skill-manager 插入宿主 composition，对所有会话生效。

兼容性

组件	支持或持续验证范围
DeepSeek Harness	0.1.1-rc.2 依赖合同；0.1.2-alpha.3 依赖合同及隔离安装与 UI 烟测；0.1.3-alpha.1 发布标签源码接口核对及会话 Hook 回归测试；0.2.0-rc.2 隔离安装、Web 启动、Settings API 和真实 /name Skill 调用
Node.js	22.19.0 与 24.19.0
pnpm	11.19.0，使用 frozen lockfile
操作系统	Ubuntu 与 Windows CI 矩阵

0.1.3-alpha.1 适配支持 session.snapshotEvents() 和数组形式的可见消息序号，同时保留旧版 events API。该版本的完整安装/UI 烟测仍待对应宿主包在 npm 可用后验证。

使用 DSH 0.2.0-rc.2 时，请安装本插件 1.0.6 或更新版本：旧版插件发出的 source.kind: "plugin" 会被 DSH v4 会话格式拒绝。真实 Web Profile 测试中，/ponytail-help 成功注入完整 Skill 内容（skill-invocation），管理器消息使用 plugin:dsh-skills-manager，整轮对话正常完成。这验证了显式 Skill 调用和管理器注入；其他 0.2.x 宿主版本不在当前 peer 依赖范围内。

DSH 仍处于 developer preview。需要可复现安装时，请把插件固定到具体 commit；升级 DSH 依赖后应重新运行安装烟测。

Skill 配置

在 SKILL.md 的 frontmatter 中直接声明激活条件与 Hook：

---
name: repo-hardening
description: Review and harden a repository with build/test gates.
metadata:
  activation: auto             # auto | suggest | off
  triggers:
    - "harden"
    - "build fails"
    - "re:exit code \\d+"
  hooks:
    UserPromptSubmit:
      inject: "得出结论前必须先运行 build 与 test。"
    PreToolUse:
      - tool: bash
        when: "git push"       # 子串或 re:<pattern>
        decision: deny         # allow | deny | ask
        reason: "不允许直接 push"
    PostToolUse:
      - tool: bash
        when: "re:exit code [1-9]"
        action: activate
    SessionStart:
      activate: true
---

激活模式

模式	行为
auto	命中后立即注入完整 Skill
suggest	命中后添加轻量提醒，由模型决定是否加载
off	不参与自动匹配，但模型仍可手动调用

Codex 风格的 manual 与 disabled 会作为 off 的别名处理。如果没有声明 activation，带显式 triggers 的 Skill 默认为 auto，其他 Skill 默认为 suggest。

对于允许用户调用的 Skill，DSH 还支持输入 /name 直接加载完整内容，不受管理器是否建议该 Skill 的影响；单独的 suggest 只会添加提醒。

触发词与策略

• 普通触发词执行大小写不敏感的子串匹配。
• re: 前缀表示正则表达式；无效正则会被忽略。
• PreToolUse.tool 可以填写具体工具名或 *。
• 工具策略返回 allow、deny 或 ask，并可附带原因。
• 用户覆盖配置可以存储在上游 SKILL.md 之外，避免更新时丢失本地策略。

覆盖配置示例：

skill_manager set-triggers ponytail-review triggers=["review this diff","过度设计"]
skill_manager set-hooks repo-hardening hooks={"PostToolUse":[{"tool":"bash","when":"re:exit code [1-9]","action":"activate"}]}

Hook 兼容性

Skill Hook	DSH 宿主事件	支持情况
UserPromptSubmit	agent/pre-step	✅ 激活期间每轮注入声明文本
PreToolUse	tools/pre-execute	✅ 根据工具名与参数执行 allow、deny 或 ask
PostToolUse	tools/post-execute	✅ 工具输出命中后激活 Skill
PostToolUseFailure	tools/post-execute	✅ 通过同一结果事件匹配失败文本
SessionStart	agent/session-start	✅ 无需匹配即可在会话开始时激活
SessionEnd / Stop	agent/disposed / agent/turn-stopping	⚠️ 仅可观察，不注入内容
PreCompact	DSH 核心无对应事件	⚠️ 未实现；压缩移除激活标记后可重新注入

GitHub 托管的 Skills

管理器接受 owner/repo 简写，以及完整的 https://、git@ 或 ssh:// Git URL。

skill_manager install owner/repo
skill_manager update
skill_manager status
skill_manager uninstall skill-name

安装过程中，插件会：

1. 将单一分支浅克隆到 <DSH_HOME>/skill-sources/<slug>；
2. 在最多 3 层目录中发现包含 SKILL.md 的目录；
3. 跳过 .git、node_modules、dist 和 build；
4. 把发现的 Skill 复制到 <DSH_HOME>/skills/<name>。

更新时会拉取配置的 ref，把来源重置到 FETCH_HEAD，再对已安装 Skill 执行权威同步。随后文件监视器自动使目录缓存失效并派发 skills/change。

插件 Manifest 按以下顺序检测：

1. .codex-plugin/plugin.json；
2. .claude-plugin/plugin.json。

Settings 页面会展示插件名称、版本、Skills 和 Hook 数量。Manifest 中指向仓库内部 Node 脚本的安全生命周期 Hook，可用于 SessionStart 与 UserPromptSubmit。

状态保存在 <DSH_HOME>/skill-manager.json，包括来源、ref、commit、安装路径、作用域覆盖和最近 50 条操作记录。

安装确认门控

模型不能自行安装或更新 Git 来源。每一次模型发起的 skill_manager install 与 skill_manager update 调用，都会先请求一次决定。

installGate	行为
ask（默认）	弹出一张审批卡，用户允许这一次后才执行。
deny	不弹卡，直接拒绝。模型会收到原因，并可指引用户去 Settings。
off	恢复 1.0.x 行为，不再询问。

卡片会写出 Git 来源，并说明安装会复制整个仓库。卡片同时说明：安装前 Hook 仍处于未验证状态，因为此时还没有克隆仓库。

门控是 fail-closed。审批通道不可用、请求抛错、用户拒绝或取消时，不会执行任何 Git 命令。模型会收到一段降级说明和一个结构化 code：

code	原因
user-rejected	用户拒绝了这张卡。
approval-cancelled	用户取消，或所在 turn 被中止。
approval-unavailable	当前部署没有挂载审批应答器。
approval-error	审批请求抛错。
policy-deny	installGate 为 deny。
invalid-source	URL 缺失或不受支持。文案与安装报错逐字一致。
no-agent	这次调用没有 agent，无法询问用户。

通过模型工具配置门控：

skill_manager set-config config={"installGate":"off"}

门控是插件策略，不是 Skill Hook。Skill 无法关闭它。

用户在 Settings → Skill 管理 中自己发起的安装不会被询问。用户发起动作，本身已经作出决定。

候选目录

只有当候选目录列出可安装来源时，插件才能提出能力缺口。该目录默认关闭，需要手动开启。

{
  "version": 1,
  "entries": [
    {
      "repo": "owner/repo",
      "description": "这个技能仓库覆盖什么",
      "triggers": ["review", "re:exit code [1-9]"],
      "skills": ["review-helper"],
      "hooks": { "PreToolUse": true },
      "verified": false
    }
  ]
}

字段	含义
repo	必填。必须通过与 install 相同的来源白名单。
description	必填。用于匹配的文本，上限 300 字符。
triggers	可选。语法同 metadata.triggers，上限 32 条。
skills	可选。声明的技能名，安装前未验证。
hooks	可选。声明的事件名，安装前未验证。
verified	可选。维护者已人工核对仓库。

• 路径来自 candidateCatalogPath，默认 <DSH_HOME>/skill-manager-candidates.json。
• 上限：200 条条目、描述 300 字符、每条 32 个触发词。
• 不在 Git 白名单内的 repo 整条丢弃。候选目录不能扩大可克隆范围。
• 候选目录只列来源，不是注册表：已安装技能元数据仍只来自 ctx.skills。
• 用 skill_manager set-config config={"proposeEnabled":true} 开启。
• 用 proposeThreshold（默认 7）与 maxPropose（默认 1，每轮最多一张）调节。
• 文件缺失、分数不足、或声明的技能都已安装时，分支保持静默。
• 加载失败时每个文件版本只警告一次，同一个坏文件不会重复刷日志。
• 提案属于模型上下文，可能不会出现在对话里，也没有 UI 追踪。

项目级 Skills

Filesystem Provider 按以下优先级解析 Skill 根目录：

优先级	根目录	Source
1	<project>/.dsh/skills	project-dsh
2	<project>/.agents/skills	project-agents
3	宿主配置的目录	custom
4	<DSH_HOME>/skills	user-dsh
5	<agentsHome>/skills	user-agents
6	内置 Skills	bundled

项目 Skill 使用同一套匹配流程，并凭优先级在同名冲突中胜出。模式、触发词与 Hook 覆盖按 scope 和 cwd 存储，避免设置跨项目或泄漏到用户级 Skill。

项目内 Skill 仍由项目自己的 Git 仓库管理。管理器的 update 只同步用户级来源；项目改动由文件监视器自动刷新。

管理与可观测性

Settings 界面

页面展示激活控制、来源信息和 Skill 管理操作。

Settings → Skill 管理 提供：

• 跟随 DSH 当前显示语言切换的英文与简体中文界面；
• 主动激活总开关；
• 每轮自动加载数量限制；
• GitHub 安装与更新操作；
• 每个 Skill 的模式、触发词、Hook、来源与 commit 信息；
• 项目 workspace 选择；
• 卸载操作与最近历史。

模型工具

skill_manager 支持 status、install、update、uninstall、set-mode、set-triggers、set-hooks 与 set-config。项目记录使用 scope: project，并且必须提供 cwd。

事件

• skill-manager/hook — { event, skill, action, detail, at }，记录 Hook 活动。
• skill-manager/update — 安装、更新或卸载后的同步结果。
• skills/change — Skill 目录变化后由 Filesystem Provider 派发。

权限与数据

范围	行为
文件读取	读取宿主选择的 DSH 用户级与项目级 Skill 根目录，以及已配置 Git 来源中的元数据
文件写入	来源保存在 <DSH_HOME>/skill-sources，管理器拥有的 Skill 保存在 <DSH_HOME>/skills，状态保存在 <DSH_HOME>/skill-manager.json
网络	仅在用户请求安装或更新来源时调用本地 git；插件不实现遥测
进程	以参数数组运行 git，并可执行仓库内显式声明的 Node 生命周期 Hook，附带时间与输出限制
模型发起的安装	执行任何 Git 命令前先请求一次审批决定；没有审批通道时 fail-closed
凭据	不保存 Git 凭据；身份验证仍由用户的 Git 配置和凭据助手负责
会话上下文	读取当前提示与 Skill 目录进行匹配，并向当前会话注入激活或建议消息

卸载管理器拥有的 Skill 时会删除其复制目录。没有托管 Git 来源的本地手写 Skill 不会被管理器删除。

安全

• Git 来源必须匹配受支持的 URL 白名单。
• Git 参数以数组传递，不拼接为 shell 命令。
• Skill Hook 不经过 shell 执行。
• Manifest Hook 路径必须解析到克隆仓库内部的 Node 脚本。
• 无效正则和不受支持的 Hook 声明会被忽略。

安装带有可执行 Hook 的插件，意味着信任该仓库的代码。安装第三方来源前请先进行审查。

受支持版本与私密漏洞报告方式见 SECURITY.md。

明确不做的决策

决策	原因
不经询问直接安装	最终决定权留给用户。插件从不自行安装，因此也不提供静默安装模式。
approve / modify / reject 三态卡片	DSH 审批卡只支持 allow-once 与 reject。modify 没有可落地的接缝。
安装前探测仓库的 Hook	探测需要克隆和网络时间。卡片如实说明限制，不做猜测。
对未应答卡片做超时自动拒绝	任何超时数值都是武断的。未应答本身已经是 fail-closed，因为用户回答前不会执行任何操作。
把技能元数据存进候选目录	候选目录只列可安装来源。已安装技能元数据仍只来自 ctx.skills。

开发

pnpm test
pnpm lint

文件	职责
lib.js	纯函数：匹配、打分、状态、Hook 与 Manifest 处理
index.js	DSH 事件、工具、RPC、Git 操作与集成接线
client/client.js	Settings 管理界面
test.mjs	Node 测试套件
cordis.patch.yml	宿主 composition 补丁

欢迎在 GitHub 仓库提交 Issue 或 Pull Request。 开发环境、验证命令与 Pull Request 要求见 CONTRIBUTING.md。

License

本项目基于 MIT License 发布。