# 🧩 dsh-skills-manager
**面向 DeepSeek Harness 的主动 Skill 激活、Hook 编排与 GitHub 同步插件。**
English ·
简体中文
[](https://www.npmjs.com/package/@existence001100/dsh-skills-manager)
[](https://github.com/Existence001100/dsh-skills-manager/actions/workflows/ci.yml)
[](./LICENSE)
[](https://nodejs.org/)
[](https://github.com/Existence001100/dsh-skills-manager/commits/main)
[](https://github.com/Existence001100/dsh-skills-manager/stargazers)
**🚀 快速安装**
```sh
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-配置) · [🐛 反馈](https://github.com/Existence001100/dsh-skills-manager/issues)
## 目录
- [为什么需要这个插件](#为什么需要这个插件)
- [核心特性](#核心特性)
- [工作原理](#工作原理)
- [快速开始](#快速开始)
- [兼容性](#兼容性)
- [Skill 配置](#skill-配置)
- [Hook 兼容性](#hook-兼容性)
- [GitHub 托管的 Skills](#github-托管的-skills)
- [安装确认门控](#安装确认门控)
- [候选目录](#候选目录)
- [项目级 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 |
## 工作原理
```mermaid
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 安装（推荐）
```sh
dsh plugin --profile web add @existence001100/dsh-skills-manager
```
DSH 会识别包内的 `dsh.bundle` manifest，并自动把 `@existence001100/dsh-skills-manager` 加入 Web Profile。安装完成后，请重启正在运行的 Web Profile。
### 从 GitHub 安装
```sh
dsh plugin --profile web add github:Existence001100/dsh-skills-manager
```
需要测试 `main` 中尚未发布的变更时，可以使用 GitHub 来源；如需可复现安装，请固定到具体 commit。
### 更新或卸载
```sh
dsh plugin --profile web update @existence001100/dsh-skills-manager
dsh plugin --profile web remove @existence001100/dsh-skills-manager
```
执行任一操作后请重启 Profile，确保运行时 composition 与已安装 Bundle 一致。
### 安装本地 Checkout 进行开发
```sh
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：
```yaml
---
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: