dsh-skill-pool 0.0.0-stage → 0.3.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,288 @@
1
+ # dsh-resource-pool v3 契约(冻结)
2
+
3
+ > 本文件是 v3 重构的唯一接口契约。Host / Client / 测试三方都以此为准。
4
+ > v2 契约见 `CONTRACTS.md`(归档参考,不再生效)。
5
+
6
+ ## v4 增量(2026-11-13,覆盖下文冲突处)
7
+
8
+ 1. **文档版本 4**:新增顶层 `groups`;技能的 `modes` / `workspaces` 旁增加
9
+ `modesFrom` / `workspacesFrom`(`group` = 继承组,`self` = 用自己的)。
10
+ 2. **组的键**:Git 来源 `repo:<source.project>`;无仓库的本地导入 `import:<sourceId>`;
11
+ 没有来源的成员不分组。组记录 `{key, kind, modes[], workspaces[]}`。
12
+ 3. **生效条件**:每个维度独立——`from === 'group'` 且组存在则用组的值,否则用成员自己的值;
13
+ 组不存在时回落成员自己的值。`resolvePool` 语义不变,判定前先算生效条件。
14
+ 4. **迁移**:v3 → v4 是显式迁移(`store.migrateV3`),按组内现状推出组值并标记继承,
15
+ 保证迁移前后 `resolvePool` 对任意会话逐条相同;其余未知版本仍重置为空文档。
16
+ 5. **模式列表**:`inventory.modes` 不再注入 `default`;`default` 只是 `modeOf()` 的内部兜底。
17
+ `buildInventory` 额外返回 `defaultMode`(预设注册表的默认预设)供面板初始化预览。
18
+ 6. **预览**:`/resolve` 增加 `allModes` / `allWorkspaces`(值为 `1`),用于"全部模式/全部工作区"
19
+ 这一预览选项——它要求忽略该维度,而不是把空串当成一个真实模式/工作区。
20
+ 7. **接口**:新增 `POST /group {key, modes?, workspaces?}`;`POST /item` 接受
21
+ `modesFrom` / `workspacesFrom`。技能行(`inventory.skills[]`)增加
22
+ `groupKey` / `groupName` / `modesFrom` / `workspacesFrom` / `effectiveModes` / `effectiveWorkspaces`。
23
+ 8. **来源**:面板按仓库分组展示,组内按每次导入列出;检查/更新/删除的粒度仍是
24
+ **一次导入**(每条 source 有自己的 `subdir` 与 `sha`),组头只汇总检查结果。
25
+ 9. **排除**:`source.excluded[]` 记录用户删掉的技能名;`installFromTree` 与
26
+ `updateGitSource` 跳过这些名字,所以更新不会把它们装回来。删除技能时写入排除。
27
+ 10. **清空即删除来源**:某个来源的技能被删光(或更新后一个都不剩)时,**连同来源记录一起删除**
28
+ (不再保留可更新的空壳);它是该仓库最后一个来源时,组也一并删除。
29
+ 11. **恢复**:`POST /source/update {id, force?, restore?}`;`restore` 先清空 `excluded` 再强制重装,
30
+ `force` 表示提交未变也重装。面板在来源行显示「已排除 N 个」与恢复入口。
31
+ 12. **整组开关**:组记录增加 `enabled`(默认 true)。生效 = 成员 `enabled` 且组 `enabled`;
32
+ 组开关不改成员自己的值,重新打开即恢复。`POST /group` 接受 `enabled`。
33
+ 面板:资源组头一个开关 + 设置 tab「分组开关」卡片(按仓库列出成员数、模式、工作区)。
34
+ 13. **折叠**:资源 tab 的仓库组与来源 tab 的仓库组都默认折叠,点 ▸ 或组名展开;折叠状态只在客户端内存里。
35
+ 14. **组级检查/更新**:来源 tab 的仓库组头显示汇总检查状态(任一 `update-available` → 有更新;
36
+ 否则任一 `error` → 失败;否则已是最新)与「检查 / 更新」按钮。检查走 `POST /source/check {ids}`,
37
+ 更新对组内每条 Git 来源依次 `POST /source/update {id}`,一条失败不影响其余。
38
+
39
+ ## 1. 产品模型
40
+
41
+ **一个全局资源池 = 用户的资源库。** 没有"资源库 → 资源池"的两步搬运。
42
+
43
+ - 用户导入一个技能或一个 MCP 连接,它**立即**成为池成员。
44
+ - 每个成员单独携带条件:`modes[]`(Agent 模式)与 `workspaces[]`(工作区),都可多选。
45
+ - 条件语义:**AND,空表示不限**。
46
+ - 只填 modes ⇒ 这些模式下的所有工作区可用。
47
+ - 只填 workspaces ⇒ 所有模式下、这些工作区内可用。
48
+ - 都填 ⇒ 两者同时满足才可用。
49
+ - 都空 ⇒ 处处可用(导入默认值)。
50
+ - 存储一份、全局共享:任何模式/工作区读的是同一个目录。条件只控制**可见性**,不复制文件。
51
+ - 设置页三个 Tab:**资源**(池成员列表)/ **来源**(Git 与 ZIP 导入来源、检查更新)/ **设置**。
52
+ - 不出现侧边栏入口。
53
+
54
+ ## 2. 存储
55
+
56
+ ### 2.1 状态文件
57
+
58
+ `$DSH_HOME/resource-pool/state.json`(可用 `Config.file` 覆盖):
59
+
60
+ ```jsonc
61
+ {
62
+ "version": 3,
63
+ "settings": {
64
+ "enabled": true, // 总开关;false 时完全不干预任何会话
65
+ "mcpGate": true, // MCP 命名空间门控
66
+ "injectSummary": true, // 是否注入系统提示摘要
67
+ "gateDefaultSkills": false // 是否连系统自带技能一起严格隐藏(默认关)
68
+ },
69
+ "skills": {
70
+ "<name>": {
71
+ "enabled": true,
72
+ "modes": [], // string[]
73
+ "workspaces": [], // string[] 绝对路径
74
+ "sourceId": "src_xxx", // 可空:手工/ZIP 导入的来源记录
75
+ "digest": "sha256:...", // 可空:内容摘要,用于更新判定
76
+ "installedAt": "2026-10-22T03:04:05.000Z"
77
+ }
78
+ },
79
+ "mcp": {
80
+ "<server>": {
81
+ "enabled": true, "modes": [], "workspaces": [], "installedAt": "...",
82
+ // 连接定义:Host 重启后由资源池据此重建 rp-<server> 的 Loader 行
83
+ "definition": {
84
+ "transport": "streamable-http" | "stdio",
85
+ "serverName": "<server>",
86
+ "url": "http://.../mcp", // streamable-http
87
+ "headers": { "Authorization": "Bearer ..." }, // 可空
88
+ "command": "npx", "args": [], "env": {}, "cwd": "" // stdio
89
+ }
90
+ }
91
+ },
92
+ "sources": {
93
+ "<sourceId>": {
94
+ "id": "src_xxx",
95
+ "kind": "git" | "zip" | "files",
96
+ "label": "owner/repo#main",
97
+ "provider": "github" | "gitlab", // kind=git 时
98
+ "project": "owner/repo", // kind=git 时
99
+ "branch": "main", // kind=git 时
100
+ "subdir": "", // kind=git 时
101
+ "tokenCredential": "RESOURCE_POOL_GIT_SRC_X", // 只存凭据名
102
+ "skills": ["a", "b"], // 该来源安装的技能名
103
+ "digest": "sha256:...",
104
+ "sha": "abc123", // kind=git 时的远端提交
105
+ "lastCheck": { "at": "...", "status": "up-to-date" | "update-available" | "error", "remote": "sha", "error": "" },
106
+ "createdAt": "..."
107
+ }
108
+ }
109
+ }
110
+ ```
111
+
112
+ 版本不符的旧文档一律重置为默认(`normalizeState` 既有行为)。
113
+
114
+ ### 2.2 资源目录(独立文件夹,不与系统技能混放)
115
+
116
+ ```
117
+ $DSH_HOME/resource-pool/library/skills/<name>/SKILL.md
118
+ $DSH_HOME/resource-pool/library/skills/<name>/... # 该技能的 references/scripts/assets
119
+ ```
120
+
121
+ - **绝不**写入 `$DSH_HOME/skills/`(系统 filesystem provider 扫描的位置)。
122
+ - 该目录由本插件自己的 skill provider 供给(见 §3),不依赖系统 provider 的 watch。
123
+ - 布局固定为目录包 `<name>/SKILL.md`;平铺 `*.md` 在安装时被规范成目录包。
124
+
125
+ ### 2.3 SKILL.md 格式
126
+
127
+ YAML frontmatter + Markdown 正文;必需 `name`(kebab-case)与 `description`;可选 `whenToUse`、`disable-model-invocation`、`user-invocable`、`metadata`。
128
+
129
+ ## 3. 技能供给(本插件的 provider)
130
+
131
+ 新文件 `src/provider.js`:
132
+
133
+ ```js
134
+ export const PROVIDER_NAME = 'resource-pool'
135
+
136
+ /**
137
+ * @param {{root: string, allowed: Set<string>|string[], logger?: object}} options
138
+ * @returns {import('@deepseek-ai/dsh-skill').SkillProvider}
139
+ */
140
+ export function createLibraryProvider({ root, allowed, logger })
141
+ ```
142
+
143
+ 行为:
144
+
145
+ - `list(options)`:扫描 `root` 下的一级目录,只返回 `allowed` 内、且存在合法 `SKILL.md` 的技能。
146
+ - 返回 `SkillCandidate[]`(同步完成,不读网络)。
147
+ - 字段:`name`(frontmatter `name`,非法则用目录名)、`description`(必填,缺失则跳过该技能)、`whenToUse?`、`invocation:{modelInvocable,userInvocable}`(由 `disable-model-invocation` / `user-invocable` 解析,默认 `true/true`)、`source:'custom'`、`provider:PROVIDER_NAME`、`rank:350`、`locator:{dir,file}`、`path:file`、`resourceBase:{kind:'directory', path:dir}`。
148
+ - 非法/不可读技能跳过并 `logger?.warn`,**不抛错**。
149
+ - 允许 1s 级别的 mtime 缓存;`list` 必须能容忍目录不存在(返回 `[]`)。
150
+ - `get(candidate, options)`:读取 `candidate.locator.file`,剥掉 frontmatter 后返回 `{...summary, content, metadata}`;文件消失返回 `undefined`。
151
+
152
+ 注册方式(属于 `src/activation.js`):**按 Agent 注册**,即
153
+ `agent.ctx.skills.registerProvider((control) => createLibraryProvider({ root, allowed }))`。
154
+ 因为 `SkillRegistry.registerProvider` 的文件化层语义由调用方 ctx 的 scope 决定,注册到 `agent.ctx` 就只对该 Agent 可见 ⇒ 未激活的库内技能在 registry 层就不存在,天然严格隐藏,**不再需要**摘掉原生 `skill` 工具或注册同名替代工具。
155
+
156
+ - 注册必须由 `agent.ctx.effect(...)` 持有,随 Agent 释放。
157
+ - 池内容或条件变化 ⇒ 释放旧注册并重新注册(旧注册 dispose 会自动失效 catalog 缓存)。
158
+ - `allowed` = `resolvePool()` 得出的技能名集合,与 `modes/workspaces` 无关的库内技能不进入 `allowed`。
159
+ - 库内文件被安装/更新/删除后,同样释放并重新注册(或调用 `control.invalidate()`)以刷新 catalog。
160
+
161
+ ## 4. 判定(`src/rules.js`,不改)
162
+
163
+ ```js
164
+ resolvePool(state, {mode, cwd}) -> {gated, skills: string[], mcpServers: string[], gateSkills, gateMcp}
165
+ ```
166
+
167
+ - 条件匹配:`scopeMatches`,modes ∧ workspaces,空即不限;工作区用 `isUnder` 词法前缀匹配。
168
+ - `gateSkills = 有技能成员 && settings.enabled !== false`(`gateDefaultSkills` 只影响是否连系统技能一起隐藏)。
169
+ - `gateMcp = 有 MCP 成员 && settings.mcpGate !== false`。
170
+ - 空池 ⇒ `gated:false` ⇒ 不干预。
171
+
172
+ ## 5. 生效(`src/activation.js`)
173
+
174
+ 每个 Agent 一次激活,三步:
175
+
176
+ 1. **技能层**:按 §3 注册 provider(`allowed` 为本次判定结果)。`gateDefaultSkills === true` 时额外摘掉全局技能……(v3 不实现该分支,仅保留设置位,见 §9)。
177
+ 2. **MCP 层**:从全局 `ctx.tools.schemas()` 取 `mcp__<server>__*`,不在 `mcpServers` 内的名字 `agent.ctx.tools.restrict({deny})`。
178
+ 3. **提示词**:`agent.ctx.systemPrompt.section({name:'resource-pool:active', order: getSectionOrder('TOOL_READ')-30, text})`,说明模式、工作区、可用技能与 MCP。
179
+
180
+ 生命周期与并发(不变):`agent/created` 必须 `await`;先算后放;每 Agent 一条 promise chain;`signature` 去重;`agent/disposed` 释放;插件卸载 `disposeAll`;`ctx.inject(['agents'], () => reapplyAll())`。
181
+
182
+ ## 6. HTTP API
183
+
184
+ 前缀 `/dsh-resource-pool`,全部经 `connection.admit(req)`;响应 `{ok:true, ...}` / `{ok:false, error:{code,message}}`。
185
+
186
+ | 方法 | 路径 | 请求 | 响应 |
187
+ |---|---|---|---|
188
+ | GET | `` | — | `{ok, meta, state, inventory, mounts}` |
189
+ | POST | `/item` | `{kind:'skill'\|'mcp', name, enabled?, modes?, workspaces?}` | `{ok, state}` |
190
+ | POST | `/item/remove` | `{kind, name}` | `{ok, state, removed}` |
191
+ | POST | `/settings` | `{patch}` | `{ok, state}` |
192
+ | GET | `/resolve?mode=&cwd=` | — | `{ok, pool}` |
193
+ | POST | `/skill/upload` | `{name?, description?, files:[{path, contentBase64}], scope?:{modes,workspaces}, overwrite?}` | `{ok, state, installed: string[], failures:[{name,error}]}` |
194
+ | POST | `/skill/zip` | `{label?, archiveBase64, scope?, overwrite?}` | 同上 |
195
+ | POST | `/source/git` | `{url, provider?, branch?, subdir?, token?, label?, scope?, overwrite?}` | `{ok, state, source, installed, failures}` |
196
+ | POST | `/source/check` | `{ids?: string[]}` | `{ok, state, results:[{id,label,status,current,remote,error?}]}` |
197
+ | POST | `/source/update` | `{id}` | `{ok, state, source, installed, failures}` |
198
+ | POST | `/source/delete` | `{id}` | `{ok, state, removed:[], skipped:[]}` |
199
+ | POST | `/mcp/import` | `{payload, scope?}` | `{ok, state, servers, mounts}`(立即返回,后台挂载) |
200
+ | POST | `/mcp/remove` | `{server}` | `{ok, state}` |
201
+ | GET | `/mounts` | — | `{ok, mounts}` |
202
+
203
+ 规则:
204
+
205
+ - 写操作:原子落盘 → `reapplyAll()` → 返回新 `state`。
206
+ - `scope` 缺省为 `{modes:[],workspaces:[]}`。
207
+ - `/mcp/import` 先同步校验定义(非法 ⇒ 400),**先把成员与 `definition` 落盘**,再后台挂载;`ready` 必须观测到 `mcp__<server>__*` 工具,20s 超时 ⇒ `failed`。
208
+ - 状态文件权限为 `0600`:`definition.headers` 可能携带 `Authorization` 之类的令牌。
209
+ - 启动恢复:插件激活且 `loader` 就绪后,`src/remount.js` 对每个 `enabled !== false` 且带 `definition` 的 MCP 成员重建 `mcp-client` 行(后台探测,失败只记日志/挂载表,不阻断启动)。没有 `definition` 的旧成员会被跳过,需要重新导入一次。
210
+ - 请求体上限 96MB,超出 413(`resource-pool/too-large`)。
211
+
212
+ ### 6.1 inventory 结构(供面板渲染)
213
+
214
+ ```jsonc
215
+ {
216
+ "skills": [{ "name","description","path","sourceId","sourceLabel","enabled","modes","workspaces","digest","installedAt","modelInvocable" }],
217
+ "nativeSkills": [{ "name","description","source","provider" }], // 系统/预设自带,只读展示
218
+ "mcp": [{ "server","tools":["..."],"managed":bool,"entryId","enabled","modes","workspaces","installedAt" }],
219
+ "modes": ["default", "..."],
220
+ "workspaces": ["/abs/path", "..."]
221
+ }
222
+ ```
223
+
224
+ ## 7. 资源库函数签名(`src/library.js`,供 web-api 调用)
225
+
226
+ ```js
227
+ export function librarySkillsRoot() // <dshHome>/resource-pool/library/skills
228
+ export function parseSkillDocument(text) // {meta, body, hadFrontmatter, frontmatter, spans}
229
+ export function bundleDigest(files) // 'sha256:<32hex>'
230
+ export async function listLibrarySkills({ root }) // [{name, description, path, dir, modelInvocable, userInvocable, digest, whenToUse?}]
231
+ export async function installFromFiles({ files, root, overwrite, name, description, scope }) // {installed, failures, digests}
232
+ export async function installFromZip({ archiveBase64, root, overwrite, label, scope }) // {installed, failures, digests}
233
+ export async function installFromGit({ url, branch, subdir, token, label, root, overwrite, scope }) // {source, installed, failures, digests}
234
+ export async function updateGitSource({ source, token, root }) // {changed, source, installed, failures, digests, removed}
235
+ export async function removeSourceSkills({ source, root, skipSkills }) // {removed, skipped}
236
+ export async function checkGitSource({ source, token }) // {id, label, status, current, remote} | throws
237
+ export async function removeSkillDir({ root, name }) // boolean
238
+ ```
239
+
240
+ - `installed` 是技能名数组;`failures` 是 `[{name, error}]`;`digests` 是 `{name: 'sha256:…'}`。
241
+ - `scope` 由调用方写入 state,本层不读 state。
242
+ - 安装落点一律 `librarySkillsRoot()`;**绝不写 `$DSH_HOME/skills/`**。
243
+ - ZIP/文件/Git 三条路径都必须先把平铺 `*.md` 规范成 `<name>/SKILL.md`。
244
+ - `parseSkillDocument` 必须解析 YAML 块标量(`>` / `|`,可带 chomping)与续行,并返回每个键的行范围 `spans`,供安装时整段替换。
245
+ - 安装时只重写 `name` 与 `description` 两个键;其余 frontmatter(含嵌套 `metadata:`)原样保留。
246
+ - `listLibrarySkills` 读磁盘真值:inventory 不能依赖 registry 全局视图(v3 的库 provider 是按 Agent 注册的)。
247
+ - Git 仓库地址:**任意主机**,`parseRepoUrl(url, {provider})` 从 URL 推导 `provider/project/host/origin/apiBase`。
248
+ - `/-/tree|blob|src/<branch>/<subdir>` 段被剥离为 `branchHint`/`subdirHint`(粘贴浏览器地址即可用)。
249
+ - 判定:`github.com` → github;否则 gitlab(`/-/` 标记亦判定 gitlab);`provider` 显式传入时优先。
250
+ - API 基址:github.com → `https://api.github.com`;GHE → `<origin>/api/v3`;GitLab(含自建)→ `<origin>/api/v4`。
251
+ - Git 身份:`source.sha` = 安装时记录的提交身份。GitHub 取 `repos/<p>/commits/<branch>` 的 `sha`,GitLab 取 `projects/<enc>/repository/commits/<branch>` 的 `id`;API 不可用时回退为 `archive:<sha256 前 16 位>`。
252
+ - 下载回退:归档接口返回 **406/403/415** 时(实例禁用归档),GitLab 走 `repository/tree?recursive` + `repository/files/:path/raw`
253
+ 重建目录树再入库;结果与归档路径一致,`sha` 仍取 commits API。GitHub 无此回退。
254
+ - 当 subdir 直接指向技能包本身(`SKILL.md` 位于 base 根)时,技能名回退为该目录名。
255
+ - `checkGitSource` 必须与记录的身份**同类比较**:`source.sha` 为 `archive:` 前缀时,API 失败可下载归档重算哈希再比较;记录的是真实 commit 时不得用归档哈希臆测,直接报错。检查**不得**覆盖 `source.sha`。
256
+
257
+ ## 8. 面板(`client.js`)
258
+
259
+ 三个 Tab:
260
+
261
+ 1. **资源**
262
+ - 顶部:条件预览(选择模式/工作区后显示"此处可用 N 项")+「导入资源」按钮。
263
+ - 技能区:每行 = 名称、描述、来源标签、`模式` 多选、`工作区` 多选、启用开关、删除。
264
+ - MCP 区:同上,另显示工具数量与挂载状态(mounting/ready/failed)。
265
+ - 只读区「系统技能」:列出 `nativeSkills`,说明"不归资源池管理"。
266
+ - 空态:引导导入。
267
+ 2. **来源**
268
+ - 每行:label、kind、技能数、`上次检查` 状态徽标(已是最新 / 有更新 / 错误)、「检查更新」「更新」「删除」。
269
+ - 顶部「检查全部更新」。
270
+ - ZIP/文件导入来源只读展示,无更新按钮。
271
+ 3. **设置**:总开关、MCP 门控、提示摘要、`gateDefaultSkills`(灰显标注 v3 未启用)、状态文件路径、版本。
272
+
273
+ 交互约定:
274
+
275
+ - **导入与设条件分离**:导入对话框只收集来源信息(文件 / ZIP / Git / MCP JSON),**不问模式与工作区**;
276
+ 新导入的资源默认对所有模式与工作区生效。条件的唯一编辑入口是资源行上的模式/工作区芯片。
277
+ API 仍接受 `scope`(给脚本/未来复用),但面板不再发送。
278
+ - 「导入资源」是页面级动作,位于**页面右上角**,与「刷新」并列;「资源」Tab 内不再出现导入按钮(空态只给文字引导)。
279
+ - 行内自动保存(320ms debounce,无保存按钮);错误就地显示。
280
+ - 上方选择器(Agent 模式 / 工作区)只用于**预览**"此处可用 N 项",不写任何资源。
281
+ - 字体与配色:根节点 13px 基准字号,控件禁止使用 `font` 简写(会重置字号);
282
+ 强调色用 `--dsw-alias-link`(随主题翻转的蓝),**不用** `--dsw-alias-brand-primary`(那是主按钮填充,暗色主题下近白)。
283
+
284
+ ## 9. 明确不在 v3 范围
285
+
286
+ - `gateDefaultSkills = true` 的严格模式(隐藏系统自带技能)——保留设置位,默认关,UI 标注"暂未启用"。
287
+ - MCP 细到单工具的门控(仍以 Server 为单位)。
288
+ - Git 自动轮询检查(只做手动「检查更新」)。
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 yejianping
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,199 @@
1
- # Temporary Holding Version
1
+ # dsh-skill-pool · 技能池(Skill / MCP)
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Skills pile up, and nobody knows which one loads where. **Skill Pool** keeps them in one
4
+ place: import from files, ZIP, GitHub or GitLab, auto-group them by repository, and pick the
5
+ exact Agent modes and workspaces each skill loads in — from the Settings panel, applied instantly.
6
+
7
+ 在 **设置 → 技能池**(无侧边栏入口)里维护**一个全局技能池**。技能池就是你的资源库:
8
+ 导入的技能与 MCP 连接**立即成为池成员**,不需要再"搬到池里"。每条成员单独设置
9
+ 「Agent 模式」与「工作区」条件,命中条件的会话才能看到它。
10
+
11
+ ## 界面
12
+
13
+ | 技能按仓库分组、默认折叠 | 组头直接设整组条件 |
14
+ |---|---|
15
+ | ![groups folded](https://raw.githubusercontent.com/rj-yejianping/dsh-skill-pool/main/docs/screenshots/v0.3.7-groups-folded.png) | ![group editor](https://raw.githubusercontent.com/rj-yejianping/dsh-skill-pool/main/docs/screenshots/v0.3.7-group-editor.png) |
16
+
17
+ | 来源按仓库折叠,组头带检查/更新 | 设置页的整组开关 |
18
+ |---|---|
19
+ | ![sources folded](https://raw.githubusercontent.com/rj-yejianping/dsh-skill-pool/main/docs/screenshots/v0.3.7-sources-folded.png) | ![group switches](https://raw.githubusercontent.com/rj-yejianping/dsh-skill-pool/main/docs/screenshots/v0.3.7-settings-group-switches.png) |
20
+
21
+ ## 三个 Tab
22
+
23
+ | Tab | 作用 |
24
+ |---|---|
25
+ | **资源** | 池成员清单(技能 / MCP)。技能**按仓库分组、默认折叠**(点组名或 ▸ 展开),组头一次设整组的模式/工作区,成员默认继承、可单独覆盖;每行还能改启用状态、删除。顶部可按当前预览条件查看"此处可用 N 项";底部只读列出系统自带技能 |
26
+ | **来源** | 导入来源(Git / ZIP / 文件),**按仓库分组、默认折叠**,组内按每次导入列出。组头直接带「检查 / 更新」对该仓库**全部导入**依次执行,并显示汇总状态;展开后每次导入仍可单独检查更新、更新、删除。ZIP/文件来源只读展示 |
27
+ | **设置** | 总开关、MCP 门控、提示摘要、**分组开关**、状态文件路径、版本 |
28
+
29
+ 导入入口是页面右上角的**导入资源**:文件、ZIP、GitHub/GitLab、MCP JSON。
30
+ **导入只负责导入**:新资源默认对所有模式/工作区生效,导入对话框不问条件;条件在资源行上单独设置,两件事分开。
31
+
32
+ ## 条件语义
33
+
34
+ 条件是**两个并列维度、同时生效(AND)**:
35
+
36
+ - `模式` 留空 = 所有 Agent 模式;否则需命中其中之一(如 `standard`、`cordis`)。
37
+ - `工作区` 留空 = 所有工作区;否则会话工作目录需等于其中之一,或位于其子目录下。
38
+ - 两者都留空 = 处处可用(导入默认值);`启用` 关掉 = 等价于不生效。
39
+ - 只填模式 / 只填工作区 / 两个都填,就是"仅模式""仅工作区""两者都要"三种用法。
40
+
41
+ **整组开关**:组头(资源 tab)和设置页的「分组开关」各有一个开关。关掉一个仓库组等于把它所有成员关掉,
42
+ 但**不改成员自己的开关**——重新打开就恢复原样。
43
+
44
+ **按仓库分组时**,条件有一层继承:
45
+
46
+ - 组(`repo:<project>`)上设一份模式/工作区,成员默认 `inherit` 这一份;
47
+ - 单个成员可以切到 `self` 单独设置,此时它完全不看组;
48
+ - 组不存在(本地 ZIP/文件导入、来源被删)时,成员用自己那份;
49
+ - `inherit` 与"显式全部"是两回事:前者跟着组走,后者写死"所有模式/工作区"。
50
+
51
+ ## 删除与排除
52
+
53
+ - **删除一个技能** = 删磁盘文件 + 移出池 + 在它所属来源的 `excluded[]` 里记一笔。
54
+ 之后这个来源**再更新也不会把它装回来**(更新时跳过 `excluded`)。
55
+ - **把一个来源的技能删光** = 这个来源记录连同它的「检查更新/更新/删除」入口一起消失,
56
+ 仓库组也会在它是该仓库最后一个来源时删掉。想重新用就先重新导入。
57
+ - 来源 tab 里,有排除记录的 Git 来源显示「已排除 N 个」和**恢复已排除**按钮:
58
+ 清空 `excluded` 并强制重装当前提交(`force`),被删的技能回到池里并重新继承组配置。
59
+ - 上游自己删掉了某个技能时,更新会正常清理,不算排除。
60
+
61
+ **模式列表只列真实预设**(来自 `agentPresets`,如 `standard` / `cordis` / `minimal` / `ptc`)。
62
+ 宿主在"会话没有任何预设"时会内部兜底一个 `default`,那是实现细节,不提供给用户选择,
63
+ 免得被当成"全部模式"。
64
+
65
+ **存储只有一份。** 所有模式、所有工作区读的是同一个库目录;条件只决定**可见性**,
66
+ 不复制、不隔离文件。
67
+
68
+ 生效方式(`agent/created` 时应用;配置变更后重放到所有活动会话):
69
+
70
+ 1. **技能严格隐藏(registry 级)**:每个 Agent 注册一个**只列本会话可用技能**的技能来源。
71
+ 未通过条件的技能在该 Agent 的技能注册表里**根本不存在**——既不出现在目录里,也无法被加载。
72
+ 不再摘改原生 `skill` 工具。
73
+ 2. **MCP 隐藏**:池外 Server 的 `mcp__<server>__*` 工具被 `restrict` 掉。
74
+ 3. **提示段**:注入「技能池已激活」,说明模式、工作区与可用资源,并要求不要调用未列出的。
75
+
76
+ ## 资源库:独立目录
77
+
78
+ ```
79
+ $DSH_HOME/resource-pool/library/skills/<name>/SKILL.md
80
+ ```
81
+
82
+ **不与 `$DSH_HOME/skills/` 混放**。技能池拥有自己的目录,也拥有自己的供给方式
83
+ (插件注册的技能来源),因此:
84
+
85
+ - 系统自带技能照常可用,不属于技能池管理;面板里以「系统技能」只读展示。
86
+ - 技能池技能的导入/更新/删除完全由本插件负责,不会被其它工具误改。
87
+ - 技能正文支持 `disable-model-invocation` / `user-invocable` / `whenToUse` / `metadata`,
88
+ 安装时**原样保留**未被使用的 frontmatter 键。
89
+ - `description` 写成 YAML 块标量(`>` / `|`)或续行也能正确解析;安装时会被规范化成单行描述,
90
+ 其余键不变。
91
+
92
+ 导入方式:
93
+
94
+ - **文件**:选 `.md`(可多选/目录),或粘贴带 frontmatter 的 Markdown。
95
+ - **ZIP**:内置解析(store/deflate),无需系统 `unzip`;支持「一个目录一个技能」与「整包一个技能」。
96
+ - **Git**:任意 GitHub / GitLab 地址,**自建(内网)实例同样支持**——主机与 API 路径从 URL 推导,不写死域名。
97
+ - 可直接粘贴浏览器地址:`https://yfgit.example.com/group/repo/-/tree/main/skills`
98
+ 会自动识别仓库、**分支 `main`** 与**子目录 `skills`**(GitLab 的 `/-/tree/`、`/-/blob/` 形态)。
99
+ - 也接受 `https://host/group/repo`、`https://host/group/repo.git`、`git@host:group/repo.git`、无协议粘贴。
100
+ - 可选**分支**、**子目录**、**访问令牌**(私有仓库,GitLab 用 `PRIVATE-TOKEN`、GitHub 用 `Bearer`)。
101
+ - 仓库类型默认**自动识别**(含 `/-/tree/` 判定为 GitLab,未知域名默认按 GitLab 处理);
102
+ GitHub Enterprise 可在导入对话框里显式选 `GitHub / GHE`(走 `/api/v3`)。
103
+ - 走 tarball 下载 + `tar` 解包,**不依赖 `git` 二进制**。
104
+ - 若实例**禁用了归档接口**(对 `/repository/archive.*` 返回 406,常见于加固过的内网 GitLab),
105
+ 自动改走 `tree` + 逐文件 `raw` 接口重建同一份目录树,导入结果一致(代价是请求数变多)。
106
+ - **检查更新**:按来源查询远端提交(GitHub/GitLab commits API),**不下载归档**即可判断;
107
+ 「有更新」后再执行更新。更新只覆盖该来源安装的技能,保留池内条件;上游删除的技能会一并清理。
108
+ - 未配置 token 时,GitHub 的 commits API 可能被限流(403)。此时若安装时记录的也是归档身份
109
+ (`archive:<hash>`),检查会改为下载归档重算哈希再比对,结论依然准确;若记录的是真实 commit
110
+ sha,则如实回报查询失败,不会臆测。
111
+ - **删除来源**:只删该来源安装、且没有被其它来源引用的技能;被引用的会跳过并提示。
112
+
113
+ ## 安装
114
+
115
+ ```bash
116
+ # npm(公开发布后)
117
+ dsh plugin --profile web add dsh-skill-pool
118
+
119
+ # 本地开发:先从源码目录打包,再装真实包
120
+ npm pack # → dsh-skill-pool-0.3.7.tgz
121
+ plugin_manager(action: "install_bundle", target: "/path/to/dsh-skill-pool-0.3.7.tgz")
122
+ ```
123
+
124
+ > 不要用 `link:` / 软链安装:Host 在 profile 目录下按 importer 路径做包解析,
125
+ > 软链会让 `@deepseek-ai/dsh-tools` 解析到 profile 之外而启动失败(`ERR_MODULE_NOT_FOUND`)。
126
+
127
+ 配置项(`cordis.patch.yml` 的 `config`):`file`(状态文件路径)、`promptLanguage`(`zh`/`en`)、
128
+ `enabled`(插件级总开关)。
129
+
130
+ > **改代码后必须 `remove_bundle` + `install_bundle`** 才会重新加载;`set_plugin` 会返回
131
+ > `overridden` / `restart-required`,不会热加载。装完请确认 profile 的 `dsh.profile.bundles`
132
+ > 没有丢条目。
133
+
134
+ > **包名与数据目录是两件事。** 插件从 `@dsh/resource-pool` 改名为 `dsh-skill-pool` 后,
135
+ > 磁盘上的数据目录**仍然是** `$DSH_HOME/resource-pool/`(状态文件、技能库),
136
+ > 因此升级不会丢已有技能与配置。只有包名、客户端模块 id、Web 路由前缀变了。
137
+
138
+ ## 数据与状态
139
+
140
+ `$DSH_HOME/resource-pool/state.json`(原子写,v4):
141
+
142
+ ```jsonc
143
+ {
144
+ "version": 4,
145
+ "settings": { "enabled": true, "mcpGate": true, "injectSummary": true, "gateDefaultSkills": false },
146
+ "groups": {
147
+ "repo:larksuite/cli": { "key": "repo:larksuite/cli", "kind": "repo", "modes": ["standard"], "workspaces": [] }
148
+ },
149
+ "skills": { "<name>": { "enabled": true, "modes": [], "workspaces": [],
150
+ "modesFrom": "group", "workspacesFrom": "group",
151
+ "sourceId": "src_x", "digest": "sha256:…", "installedAt": "…" } },
152
+ "mcp": { "<server>": { "enabled": true, "modes": [], "workspaces": [],
153
+ "definition": { "transport": "streamable-http", "url": "http://…/mcp", "headers": { "Authorization": "Bearer …" } } } },
154
+ "sources": { "<id>": { "kind": "git|zip|files", "skills": ["<name>"], "excluded": ["<name>"],
155
+ "sha": "…", "lastCheck": { "status": "up-to-date" } } }
156
+ }
157
+ ```
158
+
159
+ 组键:Git 来源用 `repo:<project>`(同仓库多次导入共用一个组),没有仓库的本地导入用
160
+ `import:<sourceId>`(一次导入一组),没有来源的成员不分组。
161
+
162
+ 状态文件与技能目录、MCP 连接记录分离:删掉状态文件只重置配置(库目录里的文件仍在,
163
+ 但不再被供给——重新导入即可)。
164
+
165
+ `groups` 里每项还有 `enabled`(默认 `true`),生效条件 = 成员开关 **且** 组开关。
166
+
167
+ v3 文档会被**迁移**到 v4 而不是丢弃:按仓库推出组、把成员已一致的取值灌给组并让成员继承,
168
+ 因此迁移前后每个会话看到的资源完全相同;组内本来就不一致的维度留空,成员保留自己的取值。
169
+ v1 / v2 文档仍然读到即重置(那两版的成员模型不同,猜映射会悄悄改变门控)。
170
+
171
+ MCP 成员额外保存 `definition`(连接定义:URL/命令/请求头),**这是为了扛住 Host 重启**:
172
+ Loader 行本身只存在于运行时,重启即消失;插件激活后会按 `definition` 重建
173
+ `rp-<server>` 行,所以导入过的 MCP 不会在重启后变成"0 个工具"的僵尸成员。
174
+ 没有 `definition` 的历史成员(0.3.5 及更早导入的)会被跳过,重新导入一次即补上。
175
+ 状态文件因此按 `0600` 写入——`definition.headers` 里可能有令牌。
176
+
177
+ ## 已知限制
178
+
179
+ - 技能池只管理自己导入的资源;**系统自带技能始终可用**,不参与门控
180
+ (`gateDefaultSkills` 设置位保留,v3 未启用)。
181
+ - MCP 的门控粒度是 **Server**,不是单个工具。
182
+ - 工作区按**会话创建时的工作目录**判定;子会话继承父工作区。路径比较是词法的,不解析符号链接。
183
+ - 技能文件被外部手改后,下一次重新应用(任一保存、重启插件)才保证刷新。
184
+ - 自建 GitHub Enterprise 需要显式选择类型(未知域名默认按 GitLab 处理)。
185
+ - 内网实例若使用自签证书,需要运行环境信任该证书(插件不做证书跳过)。
186
+ - 由本插件导入的 MCP 使用 `rp-<server>` Loader 行;`dsh-mcp-connector` 管理的 `mcp-<key>` 行不受影响。
187
+
188
+ ## 开发
189
+
190
+ ```
191
+ npm run lint # node --check 全部源码
192
+ npm test # node --test test/*.test.mjs
193
+ ```
194
+
195
+ 契约见 `CONTRACTS-v3.md`(v2 在 `CONTRACTS.md`,v1 在 `CONTRACTS-v1.md`)。
196
+
197
+ ## License
198
+
199
+ MIT © yejianping