dsh-skill-pool 0.0.0-stage → 0.3.8

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,406 @@
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, enabled, modes[], workspaces[]}`。
12
+ 3. **生效条件**:每个维度独立——`from === 'group'` 且组存在则用组的值,否则用成员自己的值;
13
+ 组不存在时回落成员自己的值。`resolvePool` 语义不变,判定前先算生效条件。
14
+ 4. **迁移**:v3 → v4 是显式迁移(`store.migrateV3`),按组内现状推出组值并标记继承,
15
+ 保证迁移前后 `resolvePool` 对任意会话逐条相同。读取文件时,v1 / v2 / 未知版本一律拒绝
16
+ (`state-unsupported-version`),不会重置覆盖;纯函数 `normalizeState` 的旧行为只保留给
17
+ 内部写入/测试,不再是任何读取路径的回退。
18
+ 5. **模式列表**:`inventory.modes` 不再注入 `default`;`default` 只是 `modeOf()` 的内部兜底。
19
+ `buildInventory` 额外返回 `defaultMode`(预设注册表的默认预设)供面板初始化预览。
20
+ 6. **预览**:`/resolve` 增加 `allModes` / `allWorkspaces`(值为 `1`),用于"全部模式/全部工作区"
21
+ 这一预览选项——它要求忽略该维度,而不是把空串当成一个真实模式/工作区。
22
+ 7. **接口**:新增 `POST /group {key, modes?, workspaces?}`;`POST /item` 接受
23
+ `modesFrom` / `workspacesFrom`。技能行(`inventory.skills[]`)增加
24
+ `groupKey` / `groupName` / `modesFrom` / `workspacesFrom` / `effectiveModes` / `effectiveWorkspaces`。
25
+ 8. **来源**:面板按仓库分组展示,组内按每次导入列出;检查/更新/删除的粒度仍是
26
+ **一次导入**(每条 source 有自己的 `subdir` 与 `sha`),组头只汇总检查结果。
27
+ 9. **排除**:`source.excluded[]` 记录用户删掉的技能名;`installFromTree` 与
28
+ `updateGitSource` 跳过这些名字,所以更新不会把它们装回来。删除技能时写入排除。
29
+ 10. **清空即删除来源**:某个来源的技能被删光(或更新后一个都不剩)时,**连同来源记录一起删除**
30
+ (不再保留可更新的空壳);它是该仓库最后一个来源时,组也一并删除。
31
+ 11. **恢复**:`POST /source/update {id, force?, restore?}`;`restore` 先清空 `excluded` 再强制重装,
32
+ `force` 表示提交未变也重装。面板在来源行显示「已排除 N 个」与恢复入口。
33
+ 12. **整组开关**:组记录增加 `enabled`(新建组默认 true;读取时必须是布尔值,缺失拒绝)。
34
+ 生效 = 成员 `enabled` 且组 `enabled`;组开关不改成员自己的值,重新打开即恢复。
35
+ `POST /group` 接受 `enabled`。
36
+ 面板:资源组头一个开关 + 设置 tab「分组开关」卡片(按仓库列出成员数、模式、工作区)。
37
+ 13. **折叠**:资源 tab 的仓库组与来源 tab 的仓库组都默认折叠,点 ▸ 或组名展开;折叠状态只在客户端内存里。
38
+ 14. **组级检查/更新**:来源 tab 的仓库组头显示汇总检查状态(任一 `update-available` → 有更新;
39
+ 否则任一 `error` → 失败;否则已是最新)与「检查 / 更新」按钮。检查走 `POST /source/check {ids}`,
40
+ 更新对组内每条 Git 来源依次 `POST /source/update {id}`,一条失败不影响其余。
41
+
42
+ ## 1. 产品模型
43
+
44
+ **一个全局资源池 = 用户的资源库。** 没有"资源库 → 资源池"的两步搬运。
45
+
46
+ - 用户导入一个技能或一个 MCP 连接,它**立即**成为池成员。
47
+ - 每个成员单独携带条件:`modes[]`(Agent 模式)与 `workspaces[]`(工作区),都可多选。
48
+ - 条件语义:**AND,空表示不限**。
49
+ - 只填 modes ⇒ 这些模式下的所有工作区可用。
50
+ - 只填 workspaces ⇒ 所有模式下、这些工作区内可用。
51
+ - 都填 ⇒ 两者同时满足才可用。
52
+ - 都空 ⇒ 处处可用(导入默认值)。
53
+ - 存储一份、全局共享:任何模式/工作区读的是同一个目录。条件只控制**可见性**,不复制文件。
54
+ - 设置页三个 Tab:**资源**(池成员列表)/ **来源**(Git 与 ZIP 导入来源、检查更新)/ **设置**。
55
+ - 不出现侧边栏入口。
56
+
57
+ ## 2. 存储
58
+
59
+ ### 2.1 状态文件
60
+
61
+ `$DSH_HOME/resource-pool/state.json`(可用 `Config.file` 覆盖):
62
+
63
+ ```jsonc
64
+ {
65
+ "version": 3,
66
+ "settings": {
67
+ "enabled": true, // 总开关;false 时完全不干预任何会话
68
+ "mcpGate": true, // MCP 命名空间门控
69
+ "injectSummary": true, // 是否注入系统提示摘要
70
+ "gateDefaultSkills": false // 是否连系统自带技能一起严格隐藏(默认关)
71
+ },
72
+ "skills": {
73
+ "<name>": {
74
+ "enabled": true,
75
+ "modes": [], // string[]
76
+ "workspaces": [], // string[] 绝对路径
77
+ "sourceId": "src_xxx", // 可空:手工/ZIP 导入的来源记录
78
+ "digest": "sha256:...", // 可空:内容摘要,用于更新判定
79
+ "installedAt": "2026-10-22T03:04:05.000Z"
80
+ }
81
+ },
82
+ "mcp": {
83
+ "<server>": {
84
+ "enabled": true, "modes": [], "workspaces": [], "installedAt": "...",
85
+ // 连接定义:Host 重启后由资源池据此重建 rp-<server> 的 Loader 行
86
+ "definition": {
87
+ "transport": "streamable-http" | "stdio",
88
+ "serverName": "<server>",
89
+ "url": "http://.../mcp", // streamable-http
90
+ "headers": { "Authorization": "Bearer ..." }, // 可空
91
+ "command": "npx", "args": [], "env": {}, "cwd": "" // stdio
92
+ }
93
+ }
94
+ },
95
+ "sources": {
96
+ "<sourceId>": {
97
+ "id": "src_xxx",
98
+ "kind": "git" | "zip" | "files",
99
+ "label": "owner/repo#main",
100
+ "provider": "github" | "gitlab", // kind=git 时
101
+ "project": "owner/repo", // kind=git 时
102
+ "branch": "main", // kind=git 时
103
+ "subdir": "", // kind=git 时
104
+ "tokenCredential": "RESOURCE_POOL_GIT_SRC_X", // 只存凭据名
105
+ "skills": ["a", "b"], // 该来源安装的技能名
106
+ "digest": "sha256:...",
107
+ "sha": "abc123", // kind=git 时的远端提交
108
+ "lastCheck": { "at": "...", "status": "up-to-date" | "update-available" | "error", "remote": "sha", "error": "" },
109
+ "createdAt": "..."
110
+ }
111
+ }
112
+ }
113
+ ```
114
+
115
+ 版本不符的旧文档在读取时拒绝;`normalizeState` 仍保留"未知版本返回空文档"的纯函数行为,
116
+ 仅供内部写入/迁移测试使用。
117
+
118
+ **读取失败与损坏(全部 fail-closed)**:
119
+
120
+ - 所有读取(`store.read()`,含面板 GET、`/resolve`、Agent 激活)和写入前读取都先校验完整
121
+ 文档:非法 JSON、JSON 非对象、不支持的版本、缺少必需段,以及会被规范化成更宽权限的语义错误
122
+ 直接抛 `StateReadError`(`resource-pool/state-*`),**不回退到默认文档**。包括:
123
+ - 非布尔开关;v4 成员/组缺少 `enabled`(不再默认成 `true`);
124
+ - 非数组或非法的 `modes`/`workspaces`、非法成员键、无效继承标记;
125
+ - v4 成员 `sourceId` 指向不存在来源且任一维度依赖 `group` 继承(显式 `self` 的旧悬空来源仍可读);
126
+ - `version: 3` 带非空 `groups` 或 `modesFrom`/`workspacesFrom`(v4-only 语义,拒绝而不是静默迁移);
127
+ - group key 会污染对象原型或含控制字符;其它旧 API 写入的安全旧 key 作为惰性遗留项保留,
128
+ 但只有 `repo:` / `import:` 可被来源引用,新的 `POST /group` 拒绝其它 key。
129
+ - 错误消息固定、单行、≤240 字符,不回显原始 version、map key、文件内容或凭据。
130
+ - 首次运行(文件从未存在)仍是合法的空文档。本进程已经观察过该路径后,再出现 `ENOENT`
131
+ 按 `state-missing` 失败;该进程内记录通过 `globalThis` 在新建 `StateStore`(插件热重载)间共享,
132
+ 不创建 marker 文件。非 `ENOENT` 的读取错误(EISDIR/权限等)也计入该进程记录,之后删除路径仍报
133
+ `state-missing`。全新 Host 进程无法区分文件被删与真正首次使用,此时按首次运行处理。
134
+ 插件重载会先释放旧限制层;重载时若文件仍损坏,已有 Agent 只能走保守层
135
+ (拒绝当时可见的 `mcp__*`),无法重建原来的精确范围——这是插件生命周期边界,不会假装已恢复。
136
+ - 更新(`store.update`)与直接 `store.write` 都使用同一校验,失败时**不修改原文件字节**。
137
+ HTTP 返回 500,错误消息只说明无法读取/不是合法 JSON/文档不合法,**不回显文件内容、definition
138
+ 或其中的凭据**。
139
+ - **已有 Agent**:激活失败时保留上一次成功安装的限制层(包括 MCP `restrict`),不先释放旧层;
140
+ 失败只记日志/状态,不把会话改成无门控。若某个已存在 Agent 没有旧层(例如插件重载后从损坏
141
+ 文件重建失败),`reapplyAll` 安装一个拒绝**当时可见**全部 `mcp__*` 工具的保守层;这是静态名单,
142
+ 动态新增工具仍是已知缺口,MCP resources/instructions 不受影响。
143
+ - **新 Agent**:没有旧层可保留时 `applyToAgent` 抛错;`agent/created` 是宿主串行 await 的监听器,
144
+ 因而创建被拒绝。不会通过捕获错误继续发布一个未门控的 Agent。
145
+ - MCP `restrict` 注册失败按激活失败处理;只有在新的 deny 层安装成功后才释放旧层。
146
+ - 面板 GET 返回 `resource-pool/state-*` 错误;`resource_pool_status` 返回 `stateStatus.ok=false`
147
+ 与安全错误码/恢复说明。写成功但重新应用失败返回 200 + 脱敏 warning;面板持久、可关闭提示。
148
+ - 保守 fallback 在可见工具列表短暂为空时保留旧 deny,不释放;下一次非空重放先注册后释放。
149
+ - MCP ambiguous predicate 覆盖重叠分隔符(`mcp__a___b`)、非法字符规范化、64 字符截断及
150
+ 任意 `_<12 位小写 hex>` 后缀(合法 clean raw 也会被误拒);mount readiness/inventory 使用同一
151
+ predicate,不能把这类名字归到前缀 server;若 server 全部工具都歧义,mount 会超时而非 ready。
152
+ - 已提交的写操作若重新应用有失败,HTTP 返回 200(保留已提交状态)并附带固定文案的
153
+ `warning: {code, message, failed?}`;不把内部错误或工具名回显给浏览器。
154
+ - 恢复前应先**备份** `state.json`(`0600`,可能含 MCP 令牌),再人工修复或从备份还原;
155
+ 插件不会自动备份,也不会自动重写损坏文件。修复后下一次保存或插件重载会重新应用。
156
+
157
+ ### 2.2 资源目录(独立文件夹,不与系统技能混放)
158
+
159
+ ```
160
+ $DSH_HOME/resource-pool/library/skills/<name>/SKILL.md
161
+ $DSH_HOME/resource-pool/library/skills/<name>/... # 该技能的 references/scripts/assets
162
+ ```
163
+
164
+ - **绝不**写入 `$DSH_HOME/skills/`(系统 filesystem provider 扫描的位置)。
165
+ - 该目录由本插件自己的 skill provider 供给(见 §3),不依赖系统 provider 的 watch。
166
+ - 布局固定为目录包 `<name>/SKILL.md`;平铺 `*.md` 在安装时被规范成目录包。
167
+
168
+ ### 2.3 SKILL.md 格式
169
+
170
+ YAML frontmatter + Markdown 正文;必需 `name`(kebab-case)与 `description`;可选 `whenToUse`、`disable-model-invocation`、`user-invocable`、`metadata`。
171
+
172
+ ## 3. 技能供给(本插件的 provider)
173
+
174
+ 新文件 `src/provider.js`:
175
+
176
+ ```js
177
+ export const PROVIDER_NAME = 'resource-pool'
178
+
179
+ /**
180
+ * @param {{root: string, allowed: Set<string>|string[], logger?: object}} options
181
+ * @returns {import('@deepseek-ai/dsh-skill').SkillProvider}
182
+ */
183
+ export function createLibraryProvider({ root, allowed, logger })
184
+ ```
185
+
186
+ 行为:
187
+
188
+ - `list(options)`:扫描 `root` 下的一级目录,只返回 `allowed` 内、且存在合法 `SKILL.md` 的技能。
189
+ - 返回 `SkillCandidate[]`(同步完成,不读网络)。
190
+ - 字段:`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}`。
191
+ - 非法/不可读技能跳过并 `logger?.warn`,**不抛错**。
192
+ - 允许 1s 级别的 mtime 缓存;`list` 必须能容忍目录不存在(返回 `[]`)。
193
+ - `get(candidate, options)`:读取 `candidate.locator.file`,剥掉 frontmatter 后返回 `{...summary, content, metadata}`;文件消失返回 `undefined`。
194
+
195
+ 注册方式(属于 `src/activation.js`):**按 Agent 注册**,即
196
+ `agent.ctx.skills.registerProvider((control) => createLibraryProvider({ root, allowed }))`。
197
+ 因为 `SkillRegistry.registerProvider` 的文件化层语义由调用方 ctx 的 scope 决定,注册到 `agent.ctx` 就只对该 Agent 可见 ⇒ 未激活的库内技能在 registry 层就不存在,天然严格隐藏,**不再需要**摘掉原生 `skill` 工具或注册同名替代工具。
198
+
199
+ - 注册必须由 `agent.ctx.effect(...)` 持有,随 Agent 释放。
200
+ - 池内容或条件变化 ⇒ 释放旧注册并重新注册(旧注册 dispose 会自动失效 catalog 缓存)。
201
+ - `allowed` = `resolvePool()` 得出的技能名集合,与 `modes/workspaces` 无关的库内技能不进入 `allowed`。
202
+ - 库内文件被安装/更新/删除后,同样释放并重新注册(或调用 `control.invalidate()`)以刷新 catalog。
203
+
204
+ ## 4. 判定(`src/rules.js`,不改)
205
+
206
+ ```js
207
+ resolvePool(state, {mode, cwd}) -> {gated, skills: string[], mcpServers: string[], gateSkills, gateMcp}
208
+ ```
209
+
210
+ - 条件匹配:`scopeMatches`,modes ∧ workspaces,空即不限;工作区用 `isUnder` 词法前缀匹配。
211
+ - `gateSkills = 有技能成员 && settings.enabled !== false`(`gateDefaultSkills` 只影响是否连系统技能一起隐藏)。
212
+ - `gateMcp = 有 MCP 成员 && settings.mcpGate !== false`。
213
+ - 空池 ⇒ `gated:false` ⇒ 不干预。
214
+
215
+ ## 5. 生效(`src/activation.js`)
216
+
217
+ 每个 Agent 一次激活,三步:
218
+
219
+ 1. **技能层**:按 §3 注册 provider(`allowed` 为本次判定结果)。`gateDefaultSkills === true` 时额外摘掉全局技能……(v3 不实现该分支,仅保留设置位,见 §9)。
220
+ 2. **MCP 层**:从全局 `ctx.tools.schemas()` 取 `mcp__<server>__*`,不在 `mcpServers` 内的名字 `agent.ctx.tools.restrict({deny})`。
221
+ 注意:`mcpServerOf` 以**第一个** `__` 解析 server,而 public 名无法可靠反查 server/raw;合法
222
+ Server 名本身含 `__` 时可能误归类。现在 `isAmbiguousMcpToolName` 对**多重 `__`、无分隔符或空
223
+ server/raw** 的公共名一律 deny,优先不扩权;代价是合法 server/raw 名含 `__` 的工具也被隐藏。
224
+ 这层仍是尽力而为的 Server 级限制,**不是**强安全边界:动态新增工具可绕过静态 deny,
225
+ MCP resources、server instructions 以及程序化/scoped 注册的隐藏服务都不受工具 deny 覆盖。
226
+ 3. **提示词**:`agent.ctx.systemPrompt.section({name:'resource-pool:active', order: getSectionOrder('TOOL_READ')-30, text})`,说明模式、工作区、可用技能与 MCP。
227
+
228
+ 生命周期与并发(不变):`agent/created` 必须 `await`;先算后放;每 Agent 一条 promise chain;`signature` 去重;`agent/disposed` 释放;插件卸载 `disposeAll`;`ctx.inject(['agents'], () => reapplyAll())`。
229
+
230
+ Fail-closed 增量:
231
+
232
+ - 读取/校验失败时,已有激活的 Agent 保留旧 layer,新的 `restrict` 先安装、旧的后释放;
233
+ - 没有旧激活的 Agent(新建路径)失败必须向上抛出,使 `agent/created` 拒绝创建;
234
+ - 已有保守层时,每次显式 `reapplyAll`/preset 重放都重新枚举当前可见 `mcp__*` 并**先注册后释放**,
235
+ 不会因为一次空清单就把 `activated` 当成健康激活而永不刷新;
236
+ - `tools.schemas()` 不可用而本次又需要 MCP 门控时视为激活失败,不能当作"没有工具要隐藏";
237
+ - `reapplyAll()` 返回 `{total, failed, degraded, under, over, conservative, noVisible, retainedOldGate, fallbackFailed, warnings}`;
238
+ 各维度独立计数(同一 Agent 可 under+over,跨 Agent 不互相覆盖);HTTP 按计数与固定脱敏文案组合,
239
+ `warnings` 不作为分类依据。`over` 仅当旧层实际阻挡当前不可见名或当前可见且已允许名;旧层名字全是
240
+ 当前可见且应禁时不算 over。`noVisible` 仅在异常降级且无新 deny 时置位;健康空工具面不算故障。
241
+ `fallbackFailed` 记录结构失败,`retainedOldGate` 仅在确实存在旧 restrict 层时为真;
242
+ 明确 `mcpGate:false` 且无层时返回 false 与固定“无可保留旧层”提示,不触发 conservative;
243
+ - 状态错误只影响资源池门控,不改变 MCP resources / server instructions 的既有边界。
244
+
245
+ ## 6. HTTP API
246
+
247
+ 前缀 `/dsh-resource-pool`,全部经 `connection.admit(req)`;响应 `{ok:true, ...}` / `{ok:false, error:{code,message}}`。
248
+
249
+ | 方法 | 路径 | 请求 | 响应 |
250
+ |---|---|---|---|
251
+ | GET | `` | — | `{ok, meta, state, inventory, mounts}` |
252
+ | POST | `/item` | `{kind:'skill'\|'mcp', name, enabled?, modes?, workspaces?, modesFrom?, workspacesFrom?}` | `{ok, state, warning?}` |
253
+ | POST | `/item/remove` | `{kind, name}` | `{ok, state, removed}` |
254
+ | POST | `/settings` | `{patch}` | `{ok, state}` |
255
+ | GET | `/resolve?mode=&cwd=` | — | `{ok, pool}` |
256
+ | POST | `/skill/upload` | `{name?, description?, files:[{path, contentBase64}], scope?:{modes,workspaces}, overwrite?}` | `{ok, state, installed: string[], failures:[{name,error}]}` |
257
+ | POST | `/skill/zip` | `{label?, archiveBase64, scope?, overwrite?}` | 同上 |
258
+ | POST | `/source/git` | `{url, provider?, branch?, subdir?, token?, label?, scope?, overwrite?}` | `{ok, state, source, installed, failures}` |
259
+ | POST | `/source/check` | `{ids?: string[]}` | `{ok, state, results:[{id,label,status,current,remote,error?}]}` |
260
+ | POST | `/source/update` | `{id}` | `{ok, state, source, installed, failures}` |
261
+ | POST | `/source/delete` | `{id}` | `{ok, state, removed:[], skipped:[]}` |
262
+ | POST | `/mcp/import` | `{payload, scope?}` | `{ok, state, servers, mounts}`(立即返回,后台挂载) |
263
+ | POST | `/mcp/remove` | `{server}` | `{ok, state}` |
264
+ | GET | `/mounts` | — | `{ok, mounts}` |
265
+
266
+ 规则:
267
+
268
+ - 写操作:原子落盘 → `reapplyAll()` → 返回新 `state`。若重新应用有失败或 `degraded`(有不可见
269
+ 旧 deny 被保留),仍返回 200 与已提交的 `state`,并附带按实际 warnings code 分类的脱敏 `warning`
270
+ (incomplete/conservative/degraded;混合会说明);不会把已提交的写操作回滚。Warning 只在本次
271
+ 写响应返回,后续 GET 不重发;面板会话内持久、需用户关闭,刷新/重新挂载后消失。
272
+ - 所有 scope/enabled 入参在落盘前严格校验:`modes` 必须是合法字符串数组(`[123]`、带空白的模式名
273
+ 400),`workspaces` 必须是绝对路径(相对路径 400),`enabled`/settings 开关必须是布尔值;
274
+ 省略字段保持"部分更新、保留原值",空数组仍是显式"全部"。非法输入返回 400 且文件字节不变。
275
+ - `POST /group` 的 `key` 必须是 `repo:<project>` 或 `import:<sourceId>`;旧 API 写入的其它安全 key
276
+ 仍可读(惰性、不可被来源引用),但不能新建。
277
+ - **无组旧标记**:成员 `modesFrom`/`workspacesFrom='group'` 但没有可解析组,是合法的旧默认格式
278
+ (回落成员自己的列表,空列表 = 全部);strict reader 保留它,不误报损坏。API 仅在**会改变
279
+ scope** 时拒绝:组可解析却只改 `modes`/`workspaces`(修改不会生效)→ 400 提示切 `self`;
280
+ 无有效组却提交修改后的 group 标记 → 400。仅 `enabled`/用途等部分更新保持原语义。
281
+ 面板合法的 self→group 继承动作(组可解析、值未改)允许;group→self 的仅标记切换会把
282
+ 当前生效的组值物化到 own 列表,面板携带空 own 列表也按“仅标记”处理,避免扩成全部。
283
+ - **重新导入/更新**:`installItems` 在换 sourceId 前捕获 effective enabled/modes/workspaces;
284
+ 若新来源没有等价组,物化为 `self`;显式 import `scope` 落 `self` 并优先。若仍是**同一个有效组**,
285
+ 保留成员 own `enabled`(组关闭再开启可恢复);换到另一个**维度值等价**的可解析组时继续继承,
286
+ 但 own enabled 固定为旧 effective enabled:旧 disabled 保守保持(新组 enabled 不自动打开,
287
+ 需用户显式启用成员);旧 enabled + 新组 disabled 则隐藏,新组重新开启恢复。组丢失或维度不等价
288
+ 则物化旧 effective scope/enabled 为 `self`,不采用可能扩大权限的新组值。
289
+ 文件/ZIP/Git/source update 共用该路径;真实 `/source/update` 路由有本地 GitLab 归档测试,
290
+ 覆盖组禁用期间更新后组重新启用恢复成员。
291
+ - **空工具快照 vs 全部允许**:只有 `tools.schemas()` 中 MCP 工具观察数为 0 且仍需门控时保留
292
+ 旧 restrict 层(交集);非空快照若所有可见 MCP 工具都已允许(`denyMcp=[]`)则释放旧 deny。
293
+ `mcpGate:false`/无 MCP 成员立即释放。若保留的是 conservative fallback,仍保持 conservative
294
+ 标志并清空 signature,文件再次损坏+新工具出现时会再次刷新;真实 DSH 限制层(含先注册新 deny
295
+ 再释放旧层)由 `npm run test:restrict` 覆盖;静态 deny 对新公共名的残余动态缺口不变。
296
+ - **按工具保留不可见旧 deny**:新的 deny 层按当前可见待禁工具逐工具注册;旧层包含当前不可见
297
+ 工具名时保留该层(无法注册未知名),否则释放。旧层混合不可见名与可见已允许名时不可拆分,
298
+ 保留整层并计入 `degraded`,HTTP 返回脱敏 warning,不声称完全应用。层数上界为曾见 MCP 工具数,
299
+ 重放不会无限增长;旧不可见层不能与当前新名单合并。
300
+ - **零限制层失败**:上次成功但 all-allowed(零 restrict 层)后读取失败,会尝试 conservative deny
301
+ 当前全部已知 MCP;失败显式 degraded。上次 `mcpGate:false`/无 MCP 成员则不覆盖全局关闭语义。
302
+ - **部分注册失败**:逐工具 restrict 有一个失败时保留全部旧层与已成功新层,清 signature,并区分:
303
+ - 失败名无旧层覆盖 → `activation-incomplete`(under-restriction,工具重新出现后、下次重放前可能可调用);
304
+ - 仅保留不可见旧层 → `activation-over-restricted`(over-restriction,可能暂时过度限制)。
305
+ 已覆盖的旧层/成功新层去重,连续失败 active 层数稳定;下一次非空重放收敛。新 Agent 没有旧层时
306
+ 仍拒绝创建。空可见清单不宣称安装 deny。真实 ToolsService+activation 探针(零层/race/多 agent/
307
+ scope-local OBSERVED GAP)由 `npm run test:activation` 覆盖。
308
+ - `POST /group` 的 `import:`/`repo:` 空名返回 400。
309
+ - **警告持久化**:写成功但重新应用失败返回 200 + 脱敏 `warning`;面板显示可关闭的持久警告条,
310
+ 不被后续成功响应或短 toast 覆盖。
311
+ - `POST /source/delete` 在删除共享来源前,把被引用成员当前生效的 `enabled`/`modes`/`workspaces`
312
+ 物化为它自己的 `self` 值,再清除 `sourceId`;并发删除多个共享来源也不能把空条件变成"处处可用"。
313
+ - `POST /item` **只编辑已存在的成员**:成员不存在(包括只改条件的请求)返回 400 `resource-pool/unknown-item`,不会新建成员;新建只由导入接口完成。这样删除期间迟到的保存不能把成员重新创建出来。
314
+ - 所有返回 `state` 的响应(概览与全部写操作)都经过公开投影:MCP 成员只含 `enabled`、`modes`、`workspaces`、`installedAt`,**绝不包含 `definition`**(URL/命令/headers/env 中的凭据)。落盘状态仍保留 `definition` 供启动重挂载;投影只影响浏览器响应。
315
+ - `scope` 缺省为 `{modes:[],workspaces:[]}`。
316
+ - `/mcp/import` 先同步校验定义(非法 ⇒ 400),**先把成员与 `definition` 落盘**,再后台挂载;`ready` 必须观测到 `mcp__<server>__*` 工具,20s 超时 ⇒ `failed`。
317
+ - 状态文件权限为 `0600`:`definition.headers` 可能携带 `Authorization` 之类的令牌。
318
+ - 启动恢复:插件激活且 `loader` 就绪后,`src/remount.js` 对每个 `enabled !== false` 且带 `definition` 的 MCP 成员重建 `mcp-client` 行(后台探测,失败只记日志/挂载表,不阻断启动)。没有 `definition` 的旧成员会被跳过,需要重新导入一次。
319
+ - 请求体上限 96MB,超出 413(`resource-pool/too-large`)。
320
+
321
+ ### 6.1 inventory 结构(供面板渲染)
322
+
323
+ ```jsonc
324
+ {
325
+ "skills": [{ "name","description","path","sourceId","sourceLabel","groupKey","groupName",
326
+ "enabled","effectiveEnabled","modes","workspaces","modesFrom","workspacesFrom",
327
+ "effectiveModes","effectiveWorkspaces","digest","installedAt","modelInvocable","missing" }],
328
+ "nativeSkills": [{ "name","description","source","provider" }], // 系统/预设自带,只读展示
329
+ "mcp": [{ "server","tools":["..."],"managed":bool,"entryId",
330
+ "enabled","modes","workspaces","installedAt" }],
331
+ "modes": ["standard", "..."], // 真实预设 id,不含 default 兜底
332
+ "workspaces": ["/abs/path", "..."],
333
+ "defaultMode": "standard" // 预设注册表默认值,可空
334
+ }
335
+ ```
336
+
337
+ - inventory 与任何 `state` 响应都不含 `definition`。
338
+ - `mcp[].tools` 只包含当前可观察到的 `mcp__<server>__*` 公开名;挂载状态在 `/mounts`,
339
+ 且断线时 schema/工具名可能仍是上一代(不能把"有 schema"当作在线)。
340
+ - 该接口只读;条件通过 `POST /item` 写入,不经过 inventory。
341
+
342
+ ## 7. 资源库函数签名(`src/library.js`,供 web-api 调用)
343
+
344
+ ```js
345
+ export function librarySkillsRoot() // <dshHome>/resource-pool/library/skills
346
+ export function parseSkillDocument(text) // {meta, body, hadFrontmatter, frontmatter, spans}
347
+ export function bundleDigest(files) // 'sha256:<32hex>'
348
+ export async function listLibrarySkills({ root }) // [{name, description, path, dir, modelInvocable, userInvocable, digest, whenToUse?}]
349
+ export async function installFromFiles({ files, root, overwrite, name, description, scope }) // {installed, failures, digests}
350
+ export async function installFromZip({ archiveBase64, root, overwrite, label, scope }) // {installed, failures, digests}
351
+ export async function installFromGit({ url, branch, subdir, token, label, root, overwrite, scope }) // {source, installed, failures, digests}
352
+ export async function updateGitSource({ source, token, root }) // {changed, source, installed, failures, digests, removed}
353
+ export async function removeSourceSkills({ source, root, skipSkills }) // {removed, skipped}
354
+ export async function checkGitSource({ source, token }) // {id, label, status, current, remote} | throws
355
+ export async function removeSkillDir({ root, name }) // boolean
356
+ ```
357
+
358
+ - `installed` 是技能名数组;`failures` 是 `[{name, error}]`;`digests` 是 `{name: 'sha256:…'}`。
359
+ - `scope` 由调用方写入 state,本层不读 state。
360
+ - 安装落点一律 `librarySkillsRoot()`;**绝不写 `$DSH_HOME/skills/`**。
361
+ - ZIP/文件/Git 三条路径都必须先把平铺 `*.md` 规范成 `<name>/SKILL.md`。
362
+ - `parseSkillDocument` 必须解析 YAML 块标量(`>` / `|`,可带 chomping)与续行,并返回每个键的行范围 `spans`,供安装时整段替换。
363
+ - 安装时只重写 `name` 与 `description` 两个键;其余 frontmatter(含嵌套 `metadata:`)原样保留。
364
+ - `listLibrarySkills` 读磁盘真值:inventory 不能依赖 registry 全局视图(v3 的库 provider 是按 Agent 注册的)。
365
+ - Git 仓库地址:**任意主机**,`parseRepoUrl(url, {provider})` 从 URL 推导 `provider/project/host/origin/apiBase`。
366
+ - `/-/tree|blob|src/<branch>/<subdir>` 段被剥离为 `branchHint`/`subdirHint`(粘贴浏览器地址即可用)。
367
+ - 判定:`github.com` → github;否则 gitlab(`/-/` 标记亦判定 gitlab);`provider` 显式传入时优先。
368
+ - API 基址:github.com → `https://api.github.com`;GHE → `<origin>/api/v3`;GitLab(含自建)→ `<origin>/api/v4`。
369
+ - Git 身份:`source.sha` = 安装时记录的提交身份。GitHub 取 `repos/<p>/commits/<branch>` 的 `sha`,GitLab 取 `projects/<enc>/repository/commits/<branch>` 的 `id`;API 不可用时回退为 `archive:<sha256 前 16 位>`。
370
+ - 下载回退:归档接口返回 **406/403/415** 时(实例禁用归档),GitLab 走 `repository/tree?recursive` + `repository/files/:path/raw`
371
+ 重建目录树再入库;结果与归档路径一致,`sha` 仍取 commits API。GitHub 无此回退。
372
+ - 当 subdir 直接指向技能包本身(`SKILL.md` 位于 base 根)时,技能名回退为该目录名。
373
+ - `checkGitSource` 必须与记录的身份**同类比较**:`source.sha` 为 `archive:` 前缀时,API 失败可下载归档重算哈希再比较;记录的是真实 commit 时不得用归档哈希臆测,直接报错。检查**不得**覆盖 `source.sha`。
374
+
375
+ ## 8. 面板(`client.js`)
376
+
377
+ 三个 Tab:
378
+
379
+ 1. **资源**
380
+ - 顶部:条件预览(选择模式/工作区后显示"此处可用 N 项")+「导入资源」按钮。
381
+ - 技能区:每行 = 名称、描述、来源标签、`模式` 多选、`工作区` 多选、启用开关、删除。
382
+ - MCP 区:同上,另显示工具数量与挂载状态(mounting/ready/failed)。
383
+ - 只读区「系统技能」:列出 `nativeSkills`,说明"不归资源池管理"。
384
+ - 空态:引导导入。
385
+ 2. **来源**
386
+ - 每行:label、kind、技能数、`上次检查` 状态徽标(已是最新 / 有更新 / 错误)、「检查更新」「更新」「删除」。
387
+ - 顶部「检查全部更新」。
388
+ - ZIP/文件导入来源只读展示,无更新按钮。
389
+ 3. **设置**:总开关、MCP 门控、提示摘要、`gateDefaultSkills`(灰显标注 v3 未启用)、状态文件路径、版本。
390
+
391
+ 交互约定:
392
+
393
+ - **导入与设条件分离**:导入对话框只收集来源信息(文件 / ZIP / Git / MCP JSON),**不问模式与工作区**;
394
+ 新导入的资源默认对所有模式与工作区生效。条件的唯一编辑入口是资源行上的模式/工作区芯片。
395
+ API 仍接受 `scope`(给脚本/未来复用),但面板不再发送。
396
+ - 「导入资源」是页面级动作,位于**页面右上角**,与「刷新」并列;「资源」Tab 内不再出现导入按钮(空态只给文字引导)。
397
+ - 行内自动保存(320ms debounce,无保存按钮);错误就地显示。
398
+ - 上方选择器(Agent 模式 / 工作区)只用于**预览**"此处可用 N 项",不写任何资源。
399
+ - 字体与配色:根节点 13px 基准字号,控件禁止使用 `font` 简写(会重置字号);
400
+ 强调色用 `--dsw-alias-link`(随主题翻转的蓝),**不用** `--dsw-alias-brand-primary`(那是主按钮填充,暗色主题下近白)。
401
+
402
+ ## 9. 明确不在 v3 范围
403
+
404
+ - `gateDefaultSkills = true` 的严格模式(隐藏系统自带技能)——保留设置位,默认关,UI 标注"暂未启用"。
405
+ - MCP 细到单工具的门控(仍以 Server 为单位)。
406
+ - 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.