dsh-skill-pool 0.3.7 → 0.4.0

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.
package/CONTRACTS-v3.md CHANGED
@@ -8,11 +8,13 @@
8
8
  1. **文档版本 4**:新增顶层 `groups`;技能的 `modes` / `workspaces` 旁增加
9
9
  `modesFrom` / `workspacesFrom`(`group` = 继承组,`self` = 用自己的)。
10
10
  2. **组的键**:Git 来源 `repo:<source.project>`;无仓库的本地导入 `import:<sourceId>`;
11
- 没有来源的成员不分组。组记录 `{key, kind, modes[], workspaces[]}`。
11
+ 没有来源的成员不分组。组记录 `{key, kind, enabled, modes[], workspaces[]}`。
12
12
  3. **生效条件**:每个维度独立——`from === 'group'` 且组存在则用组的值,否则用成员自己的值;
13
13
  组不存在时回落成员自己的值。`resolvePool` 语义不变,判定前先算生效条件。
14
14
  4. **迁移**:v3 → v4 是显式迁移(`store.migrateV3`),按组内现状推出组值并标记继承,
15
- 保证迁移前后 `resolvePool` 对任意会话逐条相同;其余未知版本仍重置为空文档。
15
+ 保证迁移前后 `resolvePool` 对任意会话逐条相同。读取文件时,v1 / v2 / 未知版本一律拒绝
16
+ (`state-unsupported-version`),不会重置覆盖;纯函数 `normalizeState` 的旧行为只保留给
17
+ 内部写入/测试,不再是任何读取路径的回退。
16
18
  5. **模式列表**:`inventory.modes` 不再注入 `default`;`default` 只是 `modeOf()` 的内部兜底。
17
19
  `buildInventory` 额外返回 `defaultMode`(预设注册表的默认预设)供面板初始化预览。
18
20
  6. **预览**:`/resolve` 增加 `allModes` / `allWorkspaces`(值为 `1`),用于"全部模式/全部工作区"
@@ -28,8 +30,9 @@
28
30
  (不再保留可更新的空壳);它是该仓库最后一个来源时,组也一并删除。
29
31
  11. **恢复**:`POST /source/update {id, force?, restore?}`;`restore` 先清空 `excluded` 再强制重装,
30
32
  `force` 表示提交未变也重装。面板在来源行显示「已排除 N 个」与恢复入口。
31
- 12. **整组开关**:组记录增加 `enabled`(默认 true)。生效 = 成员 `enabled` 且组 `enabled`;
32
- 组开关不改成员自己的值,重新打开即恢复。`POST /group` 接受 `enabled`。
33
+ 12. **整组开关**:组记录增加 `enabled`(新建组默认 true;读取时必须是布尔值,缺失拒绝)。
34
+ 生效 = 成员 `enabled` 且组 `enabled`;组开关不改成员自己的值,重新打开即恢复。
35
+ `POST /group` 接受 `enabled`。
33
36
  面板:资源组头一个开关 + 设置 tab「分组开关」卡片(按仓库列出成员数、模式、工作区)。
34
37
  13. **折叠**:资源 tab 的仓库组与来源 tab 的仓库组都默认折叠,点 ▸ 或组名展开;折叠状态只在客户端内存里。
35
38
  14. **组级检查/更新**:来源 tab 的仓库组头显示汇总检查状态(任一 `update-available` → 有更新;
@@ -63,7 +66,6 @@
63
66
  "settings": {
64
67
  "enabled": true, // 总开关;false 时完全不干预任何会话
65
68
  "mcpGate": true, // MCP 命名空间门控
66
- "injectSummary": true, // 是否注入系统提示摘要
67
69
  "gateDefaultSkills": false // 是否连系统自带技能一起严格隐藏(默认关)
68
70
  },
69
71
  "skills": {
@@ -109,7 +111,47 @@
109
111
  }
110
112
  ```
111
113
 
112
- 版本不符的旧文档一律重置为默认(`normalizeState` 既有行为)。
114
+ 版本不符的旧文档在读取时拒绝;`normalizeState` 仍保留"未知版本返回空文档"的纯函数行为,
115
+ 仅供内部写入/迁移测试使用。
116
+
117
+ **读取失败与损坏(全部 fail-closed)**:
118
+
119
+ - 所有读取(`store.read()`,含面板 GET、`/resolve`、Agent 激活)和写入前读取都先校验完整
120
+ 文档:非法 JSON、JSON 非对象、不支持的版本、缺少必需段,以及会被规范化成更宽权限的语义错误
121
+ 直接抛 `StateReadError`(`resource-pool/state-*`),**不回退到默认文档**。包括:
122
+ - 非布尔开关;v4 成员/组缺少 `enabled`(不再默认成 `true`);
123
+ - 非数组或非法的 `modes`/`workspaces`、非法成员键、无效继承标记;
124
+ - v4 成员 `sourceId` 指向不存在来源且任一维度依赖 `group` 继承(显式 `self` 的旧悬空来源仍可读);
125
+ - `version: 3` 带非空 `groups` 或 `modesFrom`/`workspacesFrom`(v4-only 语义,拒绝而不是静默迁移);
126
+ - group key 会污染对象原型或含控制字符;其它旧 API 写入的安全旧 key 作为惰性遗留项保留,
127
+ 但只有 `repo:` / `import:` 可被来源引用,新的 `POST /group` 拒绝其它 key。
128
+ - 错误消息固定、单行、≤240 字符,不回显原始 version、map key、文件内容或凭据。
129
+ - 首次运行(文件从未存在)仍是合法的空文档。本进程已经观察过该路径后,再出现 `ENOENT`
130
+ 按 `state-missing` 失败;该进程内记录通过 `globalThis` 在新建 `StateStore`(插件热重载)间共享,
131
+ 不创建 marker 文件。非 `ENOENT` 的读取错误(EISDIR/权限等)也计入该进程记录,之后删除路径仍报
132
+ `state-missing`。全新 Host 进程无法区分文件被删与真正首次使用,此时按首次运行处理。
133
+ 插件重载会先释放旧限制层;重载时若文件仍损坏,已有 Agent 只能走保守层
134
+ (拒绝当时可见的 `mcp__*`),无法重建原来的精确范围——这是插件生命周期边界,不会假装已恢复。
135
+ - 更新(`store.update`)与直接 `store.write` 都使用同一校验,失败时**不修改原文件字节**。
136
+ HTTP 返回 500,错误消息只说明无法读取/不是合法 JSON/文档不合法,**不回显文件内容、definition
137
+ 或其中的凭据**。
138
+ - **已有 Agent**:激活失败时保留上一次成功安装的限制层(包括 MCP `restrict`),不先释放旧层;
139
+ 失败只记日志/状态,不把会话改成无门控。若某个已存在 Agent 没有旧层(例如插件重载后从损坏
140
+ 文件重建失败),`reapplyAll` 安装一个拒绝**当时可见**全部 `mcp__*` 工具的保守层;这是静态名单,
141
+ 动态新增工具仍是已知缺口,MCP resources/instructions 不受影响。
142
+ - **新 Agent**:没有旧层可保留时 `applyToAgent` 抛错;`agent/created` 是宿主串行 await 的监听器,
143
+ 因而创建被拒绝。不会通过捕获错误继续发布一个未门控的 Agent。
144
+ - MCP `restrict` 注册失败按激活失败处理;只有在新的 deny 层安装成功后才释放旧层。
145
+ - 面板 GET 返回 `resource-pool/state-*` 错误;`resource_pool_status` 返回 `stateStatus.ok=false`
146
+ 与安全错误码/恢复说明。写成功但重新应用失败返回 200 + 脱敏 warning;面板持久、可关闭提示。
147
+ - 保守 fallback 在可见工具列表短暂为空时保留旧 deny,不释放;下一次非空重放先注册后释放。
148
+ - MCP ambiguous predicate 覆盖重叠分隔符(`mcp__a___b`)、非法字符规范化、64 字符截断及
149
+ 任意 `_<12 位小写 hex>` 后缀(合法 clean raw 也会被误拒);mount readiness/inventory 使用同一
150
+ predicate,不能把这类名字归到前缀 server;若 server 全部工具都歧义,mount 会超时而非 ready。
151
+ - 已提交的写操作若重新应用有失败,HTTP 返回 200(保留已提交状态)并附带固定文案的
152
+ `warning: {code, message, failed?}`;不把内部错误或工具名回显给浏览器。
153
+ - 恢复前应先**备份** `state.json`(`0600`,可能含 MCP 令牌),再人工修复或从备份还原;
154
+ 插件不会自动备份,也不会自动重写损坏文件。修复后下一次保存或插件重载会重新应用。
113
155
 
114
156
  ### 2.2 资源目录(独立文件夹,不与系统技能混放)
115
157
 
@@ -175,10 +217,30 @@ resolvePool(state, {mode, cwd}) -> {gated, skills: string[], mcpServers: string[
175
217
 
176
218
  1. **技能层**:按 §3 注册 provider(`allowed` 为本次判定结果)。`gateDefaultSkills === true` 时额外摘掉全局技能……(v3 不实现该分支,仅保留设置位,见 §9)。
177
219
  2. **MCP 层**:从全局 `ctx.tools.schemas()` 取 `mcp__<server>__*`,不在 `mcpServers` 内的名字 `agent.ctx.tools.restrict({deny})`。
220
+ 注意:`mcpServerOf` 以**第一个** `__` 解析 server,而 public 名无法可靠反查 server/raw;合法
221
+ Server 名本身含 `__` 时可能误归类。现在 `isAmbiguousMcpToolName` 对**多重 `__`、无分隔符或空
222
+ server/raw** 的公共名一律 deny,优先不扩权;代价是合法 server/raw 名含 `__` 的工具也被隐藏。
223
+ 这层仍是尽力而为的 Server 级限制,**不是**强安全边界:动态新增工具可绕过静态 deny,
224
+ MCP resources、server instructions 以及程序化/scoped 注册的隐藏服务都不受工具 deny 覆盖。
178
225
  3. **提示词**:`agent.ctx.systemPrompt.section({name:'resource-pool:active', order: getSectionOrder('TOOL_READ')-30, text})`,说明模式、工作区、可用技能与 MCP。
179
226
 
180
227
  生命周期与并发(不变):`agent/created` 必须 `await`;先算后放;每 Agent 一条 promise chain;`signature` 去重;`agent/disposed` 释放;插件卸载 `disposeAll`;`ctx.inject(['agents'], () => reapplyAll())`。
181
228
 
229
+ Fail-closed 增量:
230
+
231
+ - 读取/校验失败时,已有激活的 Agent 保留旧 layer,新的 `restrict` 先安装、旧的后释放;
232
+ - 没有旧激活的 Agent(新建路径)失败必须向上抛出,使 `agent/created` 拒绝创建;
233
+ - 已有保守层时,每次显式 `reapplyAll`/preset 重放都重新枚举当前可见 `mcp__*` 并**先注册后释放**,
234
+ 不会因为一次空清单就把 `activated` 当成健康激活而永不刷新;
235
+ - `tools.schemas()` 不可用而本次又需要 MCP 门控时视为激活失败,不能当作"没有工具要隐藏";
236
+ - `reapplyAll()` 返回 `{total, failed, degraded, under, over, conservative, noVisible, retainedOldGate, fallbackFailed, warnings}`;
237
+ 各维度独立计数(同一 Agent 可 under+over,跨 Agent 不互相覆盖);HTTP 按计数与固定脱敏文案组合,
238
+ `warnings` 不作为分类依据。`over` 仅当旧层实际阻挡当前不可见名或当前可见且已允许名;旧层名字全是
239
+ 当前可见且应禁时不算 over。`noVisible` 仅在异常降级且无新 deny 时置位;健康空工具面不算故障。
240
+ `fallbackFailed` 记录结构失败,`retainedOldGate` 仅在确实存在旧 restrict 层时为真;
241
+ 明确 `mcpGate:false` 且无层时返回 false 与固定“无可保留旧层”提示,不触发 conservative;
242
+ - 状态错误只影响资源池门控,不改变 MCP resources / server instructions 的既有边界。
243
+
182
244
  ## 6. HTTP API
183
245
 
184
246
  前缀 `/dsh-resource-pool`,全部经 `connection.admit(req)`;响应 `{ok:true, ...}` / `{ok:false, error:{code,message}}`。
@@ -186,7 +248,7 @@ resolvePool(state, {mode, cwd}) -> {gated, skills: string[], mcpServers: string[
186
248
  | 方法 | 路径 | 请求 | 响应 |
187
249
  |---|---|---|---|
188
250
  | GET | `` | — | `{ok, meta, state, inventory, mounts}` |
189
- | POST | `/item` | `{kind:'skill'\|'mcp', name, enabled?, modes?, workspaces?}` | `{ok, state}` |
251
+ | POST | `/item` | `{kind:'skill'\|'mcp', name, enabled?, modes?, workspaces?, modesFrom?, workspacesFrom?}` | `{ok, state, warning?}` |
190
252
  | POST | `/item/remove` | `{kind, name}` | `{ok, state, removed}` |
191
253
  | POST | `/settings` | `{patch}` | `{ok, state}` |
192
254
  | GET | `/resolve?mode=&cwd=` | — | `{ok, pool}` |
@@ -202,7 +264,53 @@ resolvePool(state, {mode, cwd}) -> {gated, skills: string[], mcpServers: string[
202
264
 
203
265
  规则:
204
266
 
205
- - 写操作:原子落盘 → `reapplyAll()` → 返回新 `state`。
267
+ - 写操作:原子落盘 → `reapplyAll()` → 返回新 `state`。若重新应用有失败或 `degraded`(有不可见
268
+ 旧 deny 被保留),仍返回 200 与已提交的 `state`,并附带按实际 warnings code 分类的脱敏 `warning`
269
+ (incomplete/conservative/degraded;混合会说明);不会把已提交的写操作回滚。Warning 只在本次
270
+ 写响应返回,后续 GET 不重发;面板会话内持久、需用户关闭,刷新/重新挂载后消失。
271
+ - 所有 scope/enabled 入参在落盘前严格校验:`modes` 必须是合法字符串数组(`[123]`、带空白的模式名
272
+ 400),`workspaces` 必须是绝对路径(相对路径 400),`enabled`/settings 开关必须是布尔值;
273
+ 省略字段保持"部分更新、保留原值",空数组仍是显式"全部"。非法输入返回 400 且文件字节不变。
274
+ - `POST /group` 的 `key` 必须是 `repo:<project>` 或 `import:<sourceId>`;旧 API 写入的其它安全 key
275
+ 仍可读(惰性、不可被来源引用),但不能新建。
276
+ - **无组旧标记**:成员 `modesFrom`/`workspacesFrom='group'` 但没有可解析组,是合法的旧默认格式
277
+ (回落成员自己的列表,空列表 = 全部);strict reader 保留它,不误报损坏。API 仅在**会改变
278
+ scope** 时拒绝:组可解析却只改 `modes`/`workspaces`(修改不会生效)→ 400 提示切 `self`;
279
+ 无有效组却提交修改后的 group 标记 → 400。仅 `enabled`/用途等部分更新保持原语义。
280
+ 面板合法的 self→group 继承动作(组可解析、值未改)允许;group→self 的仅标记切换会把
281
+ 当前生效的组值物化到 own 列表,面板携带空 own 列表也按“仅标记”处理,避免扩成全部。
282
+ - **重新导入/更新**:`installItems` 在换 sourceId 前捕获 effective enabled/modes/workspaces;
283
+ 若新来源没有等价组,物化为 `self`;显式 import `scope` 落 `self` 并优先。若仍是**同一个有效组**,
284
+ 保留成员 own `enabled`(组关闭再开启可恢复);换到另一个**维度值等价**的可解析组时继续继承,
285
+ 但 own enabled 固定为旧 effective enabled:旧 disabled 保守保持(新组 enabled 不自动打开,
286
+ 需用户显式启用成员);旧 enabled + 新组 disabled 则隐藏,新组重新开启恢复。组丢失或维度不等价
287
+ 则物化旧 effective scope/enabled 为 `self`,不采用可能扩大权限的新组值。
288
+ 文件/ZIP/Git/source update 共用该路径;真实 `/source/update` 路由有本地 GitLab 归档测试,
289
+ 覆盖组禁用期间更新后组重新启用恢复成员。
290
+ - **空工具快照 vs 全部允许**:只有 `tools.schemas()` 中 MCP 工具观察数为 0 且仍需门控时保留
291
+ 旧 restrict 层(交集);非空快照若所有可见 MCP 工具都已允许(`denyMcp=[]`)则释放旧 deny。
292
+ `mcpGate:false`/无 MCP 成员立即释放。若保留的是 conservative fallback,仍保持 conservative
293
+ 标志并清空 signature,文件再次损坏+新工具出现时会再次刷新;真实 DSH 限制层(含先注册新 deny
294
+ 再释放旧层)由 `npm run test:restrict` 覆盖;静态 deny 对新公共名的残余动态缺口不变。
295
+ - **按工具保留不可见旧 deny**:新的 deny 层按当前可见待禁工具逐工具注册;旧层包含当前不可见
296
+ 工具名时保留该层(无法注册未知名),否则释放。旧层混合不可见名与可见已允许名时不可拆分,
297
+ 保留整层并计入 `degraded`,HTTP 返回脱敏 warning,不声称完全应用。层数上界为曾见 MCP 工具数,
298
+ 重放不会无限增长;旧不可见层不能与当前新名单合并。
299
+ - **零限制层失败**:上次成功但 all-allowed(零 restrict 层)后读取失败,会尝试 conservative deny
300
+ 当前全部已知 MCP;失败显式 degraded。上次 `mcpGate:false`/无 MCP 成员则不覆盖全局关闭语义。
301
+ - **部分注册失败**:逐工具 restrict 有一个失败时保留全部旧层与已成功新层,清 signature,并区分:
302
+ - 失败名无旧层覆盖 → `activation-incomplete`(under-restriction,工具重新出现后、下次重放前可能可调用);
303
+ - 仅保留不可见旧层 → `activation-over-restricted`(over-restriction,可能暂时过度限制)。
304
+ 已覆盖的旧层/成功新层去重,连续失败 active 层数稳定;下一次非空重放收敛。新 Agent 没有旧层时
305
+ 仍拒绝创建。空可见清单不宣称安装 deny。真实 ToolsService+activation 探针(零层/race/多 agent/
306
+ scope-local OBSERVED GAP)由 `npm run test:activation` 覆盖。
307
+ - `POST /group` 的 `import:`/`repo:` 空名返回 400。
308
+ - **警告持久化**:写成功但重新应用失败返回 200 + 脱敏 `warning`;面板显示可关闭的持久警告条,
309
+ 不被后续成功响应或短 toast 覆盖。
310
+ - `POST /source/delete` 在删除共享来源前,把被引用成员当前生效的 `enabled`/`modes`/`workspaces`
311
+ 物化为它自己的 `self` 值,再清除 `sourceId`;并发删除多个共享来源也不能把空条件变成"处处可用"。
312
+ - `POST /item` **只编辑已存在的成员**:成员不存在(包括只改条件的请求)返回 400 `resource-pool/unknown-item`,不会新建成员;新建只由导入接口完成。这样删除期间迟到的保存不能把成员重新创建出来。
313
+ - 所有返回 `state` 的响应(概览与全部写操作)都经过公开投影:MCP 成员只含 `enabled`、`modes`、`workspaces`、`installedAt`,**绝不包含 `definition`**(URL/命令/headers/env 中的凭据)。落盘状态仍保留 `definition` 供启动重挂载;投影只影响浏览器响应。
206
314
  - `scope` 缺省为 `{modes:[],workspaces:[]}`。
207
315
  - `/mcp/import` 先同步校验定义(非法 ⇒ 400),**先把成员与 `definition` 落盘**,再后台挂载;`ready` 必须观测到 `mcp__<server>__*` 工具,20s 超时 ⇒ `failed`。
208
316
  - 状态文件权限为 `0600`:`definition.headers` 可能携带 `Authorization` 之类的令牌。
@@ -213,14 +321,23 @@ resolvePool(state, {mode, cwd}) -> {gated, skills: string[], mcpServers: string[
213
321
 
214
322
  ```jsonc
215
323
  {
216
- "skills": [{ "name","description","path","sourceId","sourceLabel","enabled","modes","workspaces","digest","installedAt","modelInvocable" }],
324
+ "skills": [{ "name","description","path","sourceId","sourceLabel","groupKey","groupName",
325
+ "enabled","effectiveEnabled","modes","workspaces","modesFrom","workspacesFrom",
326
+ "effectiveModes","effectiveWorkspaces","digest","installedAt","modelInvocable","missing" }],
217
327
  "nativeSkills": [{ "name","description","source","provider" }], // 系统/预设自带,只读展示
218
- "mcp": [{ "server","tools":["..."],"managed":bool,"entryId","enabled","modes","workspaces","installedAt" }],
219
- "modes": ["default", "..."],
220
- "workspaces": ["/abs/path", "..."]
328
+ "mcp": [{ "server","tools":["..."],"managed":bool,"entryId",
329
+ "enabled","modes","workspaces","installedAt" }],
330
+ "modes": ["standard", "..."], // 真实预设 id,不含 default 兜底
331
+ "workspaces": ["/abs/path", "..."],
332
+ "defaultMode": "standard" // 预设注册表默认值,可空
221
333
  }
222
334
  ```
223
335
 
336
+ - inventory 与任何 `state` 响应都不含 `definition`。
337
+ - `mcp[].tools` 只包含当前可观察到的 `mcp__<server>__*` 公开名;挂载状态在 `/mounts`,
338
+ 且断线时 schema/工具名可能仍是上一代(不能把"有 schema"当作在线)。
339
+ - 该接口只读;条件通过 `POST /item` 写入,不经过 inventory。
340
+
224
341
  ## 7. 资源库函数签名(`src/library.js`,供 web-api 调用)
225
342
 
226
343
  ```js
package/README.md CHANGED
@@ -103,6 +103,16 @@ $DSH_HOME/resource-pool/library/skills/<name>/SKILL.md
103
103
  - 走 tarball 下载 + `tar` 解包,**不依赖 `git` 二进制**。
104
104
  - 若实例**禁用了归档接口**(对 `/repository/archive.*` 返回 406,常见于加固过的内网 GitLab),
105
105
  自动改走 `tree` + 逐文件 `raw` 接口重建同一份目录树,导入结果一致(代价是请求数变多)。
106
+ - **重新导入/更新已有技能**:若成员原先继承仓库组条件,导入会先把当前**生效的**
107
+ `enabled`/`modes`/`workspaces` 保留下来;新来源没有可解析组时落成 `self`,不会把空列表
108
+ 解释成"所有模式/所有工作区"。显式 `scope` 优先并落成 `self`;旧组被禁用时仍保持禁用。
109
+ 文件、ZIP、Git 与来源更新共用同一条 `installItems` 路径。若来源更新后仍是**同一个有效组**,
110
+ 成员的 own `enabled` 保持不变,组关闭再打开会恢复该成员。若换到**另一个维度值等价的可解析组**,
111
+ 成员 own `enabled` 固定为**旧 effective enabled**:旧组 disabled 就保守保持 disabled(新组即使
112
+ enabled 也不会自动打开,需用户显式启用成员);旧组 enabled 而新组 disabled 则新组关闭会隐藏,
113
+ 新组重新启用才恢复。若组丢失或维度值不等价,则把旧 effective scope/enabled 物化为 `self`,
114
+ 旧有效范围优先,不采用可能扩大权限的新组值。
115
+ 真实 `/source/update` 路由(临时本地 GitLab 归档/commits 服务)有独立测试覆盖同组恢复。
106
116
  - **检查更新**:按来源查询远端提交(GitHub/GitLab commits API),**不下载归档**即可判断;
107
117
  「有更新」后再执行更新。更新只覆盖该来源安装的技能,保留池内条件;上游删除的技能会一并清理。
108
118
  - 未配置 token 时,GitHub 的 commits API 可能被限流(403)。此时若安装时记录的也是归档身份
@@ -117,15 +127,16 @@ $DSH_HOME/resource-pool/library/skills/<name>/SKILL.md
117
127
  dsh plugin --profile web add dsh-skill-pool
118
128
 
119
129
  # 本地开发:先从源码目录打包,再装真实包
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")
130
+ npm pack # → dsh-skill-pool-0.3.8.tgz
131
+ plugin_manager(action: "install_bundle", target: "/path/to/dsh-skill-pool-0.3.8.tgz")
122
132
  ```
123
133
 
124
134
  > 不要用 `link:` / 软链安装:Host 在 profile 目录下按 importer 路径做包解析,
125
135
  > 软链会让 `@deepseek-ai/dsh-tools` 解析到 profile 之外而启动失败(`ERR_MODULE_NOT_FOUND`)。
126
136
 
127
- 配置项(`cordis.patch.yml` 的 `config`):`file`(状态文件路径)、`promptLanguage`(`zh`/`en`)、
128
- `enabled`(插件级总开关)。
137
+ 配置项(`cordis.patch.yml` 的 `config`):`file`(状态文件路径)、
138
+ `enabled`(插件级总开关)。插件级 `enabled=false` 是刻意的"不门控":此时状态文件损坏不会阻止新 Agent
139
+ 创建(面板与状态工具仍会报告文件错误)。
129
140
 
130
141
  > **改代码后必须 `remove_bundle` + `install_bundle`** 才会重新加载;`set_plugin` 会返回
131
142
  > `overridden` / `restart-required`,不会热加载。装完请确认 profile 的 `dsh.profile.bundles`
@@ -142,9 +153,9 @@ plugin_manager(action: "install_bundle", target: "/path/to/dsh-skill-pool-0.3.7.
142
153
  ```jsonc
143
154
  {
144
155
  "version": 4,
145
- "settings": { "enabled": true, "mcpGate": true, "injectSummary": true, "gateDefaultSkills": false },
156
+ "settings": { "enabled": true, "mcpGate": true, "gateDefaultSkills": false },
146
157
  "groups": {
147
- "repo:larksuite/cli": { "key": "repo:larksuite/cli", "kind": "repo", "modes": ["standard"], "workspaces": [] }
158
+ "repo:larksuite/cli": { "key": "repo:larksuite/cli", "kind": "repo", "enabled": true, "modes": ["standard"], "workspaces": [] }
148
159
  },
149
160
  "skills": { "<name>": { "enabled": true, "modes": [], "workspaces": [],
150
161
  "modesFrom": "group", "workspacesFrom": "group",
@@ -159,14 +170,112 @@ plugin_manager(action: "install_bundle", target: "/path/to/dsh-skill-pool-0.3.7.
159
170
  组键:Git 来源用 `repo:<project>`(同仓库多次导入共用一个组),没有仓库的本地导入用
160
171
  `import:<sourceId>`(一次导入一组),没有来源的成员不分组。
161
172
 
162
- 状态文件与技能目录、MCP 连接记录分离:删掉状态文件只重置配置(库目录里的文件仍在,
163
- 但不再被供给——重新导入即可)。
164
-
165
- `groups` 里每项还有 `enabled`(默认 `true`),生效条件 = 成员开关 **且** 组开关。
173
+ 状态文件与技能目录、MCP 连接记录分离。**首次使用**(文件从未存在)视为合法的空配置;
174
+ 但文件存在却读不懂,或本进程已经观察过的文件随后消失,都按异常处理,不会退回默认配置。
175
+ 同一 Node 进程内新建的 `StateStore`(例如插件热重载)会通过进程内记录继续记住"该文件曾经存在";
176
+ **非 `ENOENT` 的读取错误(如 EISDIR/权限错误)也会写入该进程内记录**,因此路径随后被删除时不会
177
+ 被当成首启。这不会创建任何 marker 文件。全新 Host 进程仍无法区分"文件被删"与"真正首次使用",见下方边界。
178
+
179
+ **读取和写入都 fail-closed**:普通读取(含面板 GET、`/resolve`、Agent 激活)与更新(`/item`、导入、删除等)
180
+ 都会先校验完整文档(v4 严格校验,v3 走显式迁移)。非法 JSON、JSON 非对象、不支持的版本、缺少必需段,
181
+ 以及会被规范化成**更宽权限**的语义错误都会返回显式错误,绝不回退到空默认文档。包括:
182
+
183
+ - 非布尔开关;成员/组缺少 `enabled`(不再把缺失当成 `true`);
184
+ - 非数组或非法的 `modes`/`workspaces`、非法成员键、无效的继承标记;
185
+ - 成员 `sourceId` 指向不存在的来源、且该维度依赖 `group` 继承(无法解析继承时拒绝;
186
+ 显式 `self` 的旧悬空来源仍可读);
187
+ - `version: 3` 却带非空 `groups` 或 v4 继承标记(不能静默丢弃这些 v4-only 语义);
188
+ - groups 中会污染对象原型或含控制字符的键。
189
+
190
+ 写入边界也会严格校验 API 入参:`modes:[123]`、相对工作区路径、字符串 `enabled` 等直接 400,
191
+ 不会落盘成更宽的 `[]`。省略字段仍是"部分更新、保持原值"。面板 GET 返回 500;
192
+ 原文件**逐字节保留**,不会被自动重写。错误信息固定、单行、有长度上限,
193
+ **不回显文件内容、map 键、原始 version 值或任何凭据**。
194
+
195
+ - **已有 Agent**:重新激活时若读取失败,保留上一次成功安装的限制层并告警,**不会先释放旧层**。
196
+ 若插件重载后某个已有会话已经没有旧层可保留,会安装一个**保守回退**:拒绝当时可见的所有 MCP 工具
197
+ (静态名单;动态新增工具仍可能漏过,见已知限制)。
198
+ - **新 Agent**:状态无法安全读取时,`agent/created` 监听器抛错,宿主拒绝创建该 Agent;
199
+ 不会发布一个没有 MCP 门控的会话。修复文件后,下一次保存或插件重载会恢复正常。
200
+ - **空工具快照 vs 全部允许**:只有 `tools.schemas()` 中**一个 MCP 工具都没有**(observed
201
+ count = 0)才保留旧 restrict 层;非空快照即使 `denyMcp` 为空(所有可见 MCP 工具都已允许),
202
+ 也会释放旧 deny,避免用户启用后旧限制永久不消失。用户明确 `mcpGate:false`/池中无 MCP 成员
203
+ 也立即释放。保留期间是交集,下一次非空快照重放时按新状态注册/释放。
204
+ 若被保留的是**保守 fallback**(状态曾不可读),本次仍保持 `conservative` 标志并清空
205
+ signature:文件再次损坏且出现新 MCP 工具时,会再次刷新保守 deny 覆盖新工具,而不是误当成
206
+ 健康激活。健康但**零 restrict 层**的 all-allowed 激活(上次成功时全部允许)在之后读取失败时
207
+ 不能算“保留旧门控”:会尝试对当前已知全部 MCP 工具安装保守 deny;这一步失败会返回显式
208
+ degraded,不静默放行。上次成功明确 `mcpGate:false`/无 MCP 成员时保持全局关闭语义,不安装。
209
+ - **按工具分层保留不可见旧 deny**:每个当前可见的待禁工具各一层;旧层中若有当前不可见的工具名,
210
+ 该层保留(DSH restrict 不能注册未知名),可见且已允许的工具层则释放。这样部分快照不会丢掉
211
+ “暂时未注册的 other”旧 deny,other 同名重现时仍被隐藏;等它重新可见后再重建精确层。
212
+ 若旧层同时含不可见名和当前可见且已允许名,无法拆分,只能保留整层(暂时过度限制),并通过
213
+ `degraded` 计数/HTTP warning 明确报告,而不是声称完全应用。层数上界是“曾见过的 MCP 工具名数”;
214
+ 旧不可见层不能与当前新名单合并(DSH 不能注册未知名)。已覆盖的旧层/成功新层会去重,
215
+ 连续失败时 active 层数稳定;后续重放收敛。
216
+ **注册过程中单个 per-tool 失败**时:保留所有旧层 + 已成功的新层,清 signature/保持 degraded;
217
+ 下一次非空重放重试并收敛。新 Agent 没有旧授权可依赖时,部分 MCP 覆盖失败仍拒绝创建。
218
+ - **恢复路径**:修复文件后显式保存/重放,等所有相关工具重新可见,会释放旧不可见层并重建精确
219
+ per-tool 层;服务端后续重放不再返回该 warning,但面板已有的持久 banner 仍需用户手动关闭
220
+ (不会自动消失)。插件重载会先释放全部层;若状态仍坏则退化为保守层。
221
+ rescope/preset 重放与保存重放走同一逻辑。
222
+ - **结构化的 degraded 语义**:`reapplyAll` 返回独立计数
223
+ `failed / under / over / conservative / noVisible / retainedOldGate / fallbackFailed`,不是只靠
224
+ 一个 `degraded` 或 error 字符串:
225
+ - `under`(under-restriction):per-tool deny 注册失败,DSH 拒绝未知名;工具重新注册后、下次
226
+ 重放前**可能可调用**。
227
+ - `over`(over-restriction):旧层实际阻挡了**当前不可见**的名字,或**当前可见且已允许**的名字;
228
+ 旧层里的名字全都当前可见且仍应禁止时**不算 over**。
229
+ - `conservative`:已进入保守 deny 模式(可同时 under/over)。
230
+ - `noVisible`:仅在异常降级、无可见 MCP 工具且未安装新 deny 时置位;健康的空池/首次空工具面
231
+ 是正常状态,不产生该 flag 或 warning。
232
+ - `retainedOldGate` / `fallbackFailed`:激活失败时**确实存在**旧 restrict 层才置位;
233
+ 明确 `mcpGate:false`(无 restrict 层)时返回 `retainedOldGate=false`,提示“没有可保留的旧 MCP
234
+ 限制层”,不触发 conservative。保守层结构安装失败记 `fallbackFailed`,不会只落成 generic error。
235
+ 同一个 Agent 可同时 under+over;跨 Agent 的各维度独立计数,不会被优先级吞掉。HTTP warning 根据
236
+ 这些计数与固定脱敏文案组合显示实际组合;仍返回 200 和已提交 state;面板 warning 需手动关闭。
237
+ - **空清单/零层**:没有任何可见 MCP 工具时,不会宣称安装了新 deny;会保留旧层并 reported degraded。
238
+ 零 restrict 层但上次仍要求门控时,读取失败会尝试 conservative deny 当前全部已知 MCP,失败明确
239
+ incomplete,不静默放行;明确 `mcpGate:false` 不覆盖。
240
+ 真实 DSH 限制层的注册/交集/卸载/重注册,以及“先注册新 deny 再释放旧层”由
241
+ `npm run test:restrict` 验证;新注册的公共名在再次重放前仍可能绕过静态 deny,这是明确残余缺口。
242
+ - **降级可见**:面板 GET 返回 `resource-pool/state-*` 错误;`resource_pool_status` 工具在失败时返回
243
+ `stateStatus.ok=false`、错误码与恢复说明。写入成功但重新应用失败时,HTTP 仍返回 200(已提交状态保留)
244
+ 并附带脱敏的 `warning`;面板显示**持久、可手动关闭**的警告条(不再使用 3.2 秒成功 toast,也不会被
245
+ 后续成功响应清除),不会假装所有活动会话都已生效。服务端只在触发该写操作的响应里返回 warning,
246
+ 后续 GET 不会重发;该 banner 是当前面板会话的状态,用户需手动关闭,页面刷新/重新挂载后消失。
247
+ - **边界**:全新 Host 进程启动后若状态文件已被删除,无法区分"被删"与"真正首次使用",
248
+ 此时按首次运行处理(同进程内的新 `StateStore` 会记得,见上)。
249
+ 插件重载会先释放旧限制层;若重载时文件仍损坏,已有会话只能退化为上述保守层,
250
+ 无法重建原来的精确范围。请从备份恢复。插件**不会**自动生成备份。
251
+
252
+ 恢复前请先**自行备份** `state.json`(它按 `0600` 写入,可能含 MCP 令牌),再人工修复或从自己的备份恢复。
253
+
254
+ `groups` 每项还有必填的 `enabled`(新建组时默认 `true`;读取时缺失会被拒绝,
255
+ 避免把已关闭的组读成开启);生效条件 = 成员开关 **且** 组开关。
256
+ 旧 API 可能写入过任意 group key:只要键本身安全(非原型污染、无控制字符),这类组会作为
257
+ **惰性遗留项**保留,但只有 `repo:<project>` / `import:<sourceId>` 才能被来源引用;
258
+ 新的 `POST /group` 会拒绝其它 key(400),`import:`(空来源名)与 `repo:`(空项目)也返回 400,
259
+ 不再制造无法引用的组。
260
+
261
+ **无组/无来源成员的旧格式**:`modesFrom`/`workspacesFrom` 为 `group` 但没有可解析的组,是插件
262
+ 长期写入的合法默认标记(无组时按成员自己的列表回落;自己的列表为空即"全部")。strict reader
263
+ 不会把这种正常旧配置误判为损坏。新的 API 写入则更严格:
264
+ - 修改 `modes`/`workspaces` 却仍让该维度保持 `group`(组可解析)会返回 400,提示同时提交
265
+ `modesFrom:'self'` / `workspacesFrom:'self'`,避免"改了但没生效";
266
+ - 没有有效组却提交修改后的 `group` 标记同样 400,提示改用 `self`,避免产生无法解析的继承;
267
+ - 只改 `enabled`/用途等部分更新仍保留原标记与原语义,不会被误报为配置损坏。
268
+ - 面板的继承按钮合法地执行 self → group 切换(组可解析时允许),不会因“值没变”而误拒。
269
+ - group → self 的**仅标记切换**会把当前生效的组值物化到成员自己的列表,再切到 `self`;
270
+ 面板发送的空 own 列表也按此处理,避免一次继承开关把 scope 扩成全部模式/工作区。
166
271
 
167
272
  v3 文档会被**迁移**到 v4 而不是丢弃:按仓库推出组、把成员已一致的取值灌给组并让成员继承,
168
273
  因此迁移前后每个会话看到的资源完全相同;组内本来就不一致的维度留空,成员保留自己的取值。
169
- v1 / v2 文档仍然读到即重置(那两版的成员模型不同,猜映射会悄悄改变门控)。
274
+ v3 文档若包含非空 `groups` 或 `modesFrom`/`workspacesFrom`(v4-only 语义),迁移会丢失/重解释范围,
275
+ 因此直接拒绝并提示恢复备份,而不是静默迁移。
276
+ v1 / v2 / 未来未知版本在**读取时拒绝**(`resource-pool/state-unsupported-version`),
277
+ 不会重置覆盖(那两版的成员模型不同,猜映射会悄悄改变门控);纯函数 `normalizeState`
278
+ 对未知版本仍返回空文档,仅供内部工具与测试使用。
170
279
 
171
280
  MCP 成员额外保存 `definition`(连接定义:URL/命令/请求头),**这是为了扛住 Host 重启**:
172
281
  Loader 行本身只存在于运行时,重启即消失;插件激活后会按 `definition` 重建
@@ -174,11 +283,54 @@ Loader 行本身只存在于运行时,重启即消失;插件激活后会按
174
283
  没有 `definition` 的历史成员(0.3.5 及更早导入的)会被跳过,重新导入一次即补上。
175
284
  状态文件因此按 `0600` 写入——`definition.headers` 里可能有令牌。
176
285
 
286
+ ## MCP 可行性验证(发布门禁)
287
+
288
+ MCP 工具披露与开关所依赖的宿主能力**不由普通单测证明**。普通套件(`npm test`,161 个可移植测试)
289
+ 不需要安装 DSH;宿主探针 `test/mcp-feasibility.probe.mjs` 共 21 项,直接驱动**已安装**的 DSH
290
+ (默认 `/opt/dsh/lib/node_modules/@deepseek-ai/dsh`,**硬性要求 `0.2.2-rc.3`**;可用
291
+ `DSH_FEASIBILITY_ROOT` 指向别的安装树)。
292
+
293
+ | 命令 | 作用 | 结果 |
294
+ |---|---|---|
295
+ | `npm test` | 可移植单测,**不含**宿主探针 | 161/161;不代表宿主能力已验证 |
296
+ | `npm run test:lifecycle` | `index.js` 生命周期/恢复探针(需要已安装 DSH) | 当前环境 5/5;不是宿主能力门禁 |
297
+ | `npm run test:naming` | 真实 `publicToolName` 命名/歧义探针(需要已安装 DSH) | 当前环境 1/1;不是宿主能力门禁 |
298
+ | `npm run test:restrict` | 真实 `tools.restrict` 注册/交集/卸载/重注册探针(需要已安装 DSH) | 当前环境 1/1;不是宿主能力门禁 |
299
+ | `npm run test:activation` | 真实 ToolsService + production activation 探针(零层/竞态/多 agent/scope-local/over) | 当前环境 7/7;不是宿主能力门禁 |
300
+ | `npm run test:feasibility` | 可选探针 | 运行时缺失/版本不符时**逐项 `unverified` 并跳过,退出码 0** |
301
+ | `npm run verify:feasibility` | **发布或能力声明的强制门禁**(Node 包装器,POSIX/Windows 通用) | 缺失、版本不符或任一探针失败均非零退出 |
302
+
303
+ > `test:feasibility` 的绿色或跳过**不能**当成能力证据。发布前必须运行
304
+ > `npm run verify:feasibility`;通过表示 21/21 在当前安装的真实运行时通过。
305
+ > 21 项里包含刻意固定 **OBSERVED FAIL** 的检查:它们通过只说明已知缺陷仍可复现,不代表该能力可用。
306
+ > 实测结论与未测项见 `docs/mcp-feasibility-results.md`。
307
+
308
+ 探针只使用临时目录和受控 MCP 子进程:不加载用户 profile、不写用户状态、不访问 OpenViking,
309
+ 不需要真实凭据。
310
+
177
311
  ## 已知限制
178
312
 
313
+ - **MCP 只有 Server 级门控**:**没有**单工具开关(界面开关 / per-tool switch),也**没有** MCP
314
+ 渐进披露(按服务按需展开)。任务 4/5 在本版本**未实现**,不是隐藏的实验开关。
315
+ - 现有可行性证据不支持上述能力:当前代 public 名称无法可靠反查 server/raw(`mcpServerOf`
316
+ 按第一个 `__` 解析,合法服务名本身含 `__` 时可能把工具归到错误的 Server)。现在对
317
+ **有歧义的 `mcp__*` 名一律 deny**(`isAmbiguousMcpToolName`),包括重叠分隔符
318
+ (`mcp__a___b`)和宿主因截断/字符规范化附加 `_<12 hex>` 哈希的名字;mount readiness 与
319
+ inventory 也不再把这些名字归到前缀 server。代价是合法 server/raw 名本身含 `__` 的工具也会被
320
+ 隐藏,面板的 MCP 工具列表也不会把它们归到某个 server(无法安全归属)。动态新增工具仍可绕过
321
+ 静态 deny 名单;
322
+ 隐藏业务工具不影响 MCP resources 与 server instructions;断线后 schema/提示可能陈旧。
323
+ 这不是全面的 MCP 隔离证明。详见 `docs/mcp-feasibility-results.md`。
324
+ - **状态 fail-closed 只解决"损坏状态被当成空池"这一条**:新 Agent 在状态不可读时会被拒绝创建,
325
+ 已有 Agent 保留旧限制(没有旧层时退化为拒绝当时可见 MCP 工具的保守层;若随后工具列表
326
+ 短暂为空,会保留旧保守 deny 而不是释放它);它**不**把 MCP
327
+ 变成安全边界,也不修复静态 deny 的动态注册缺口。保守层/正常 deny 只覆盖**当前全球工具清单中
328
+ 可见的 `mcp__*` 公共名**,不覆盖 MCP resources、server instructions、程序化注册的 scoped/隐藏服务,
329
+ 也不能证明 Loader 名单完整。MCP 仍不是强安全边界。
330
+ - **GUI 与真实模型运行时未验证**:条件的浏览器交互、真实 Agent 循环的模型请求装配、
331
+ PTC/自定义执行器、真实 approval 服务与审计,均未在真实 profile 中实测;本仓库只验证代码与可移植路径。
179
332
  - 技能池只管理自己导入的资源;**系统自带技能始终可用**,不参与门控
180
333
  (`gateDefaultSkills` 设置位保留,v3 未启用)。
181
- - MCP 的门控粒度是 **Server**,不是单个工具。
182
334
  - 工作区按**会话创建时的工作目录**判定;子会话继承父工作区。路径比较是词法的,不解析符号链接。
183
335
  - 技能文件被外部手改后,下一次重新应用(任一保存、重启插件)才保证刷新。
184
336
  - 自建 GitHub Enterprise 需要显式选择类型(未知域名默认按 GitLab 处理)。
@@ -188,8 +340,15 @@ Loader 行本身只存在于运行时,重启即消失;插件激活后会按
188
340
  ## 开发
189
341
 
190
342
  ```
191
- npm run lint # node --check 全部源码
192
- npm test # node --test test/*.test.mjs
343
+ npm run lint # node --check 全部源码
344
+ npm test # 可移植单测 test/*.test.mjs(不含宿主探针)
345
+ npm run test:feasibility # 可选宿主探针;缺失运行时会跳过,不能当发布证据
346
+ npm run verify:feasibility # 强制宿主门禁:缺失/版本不符/失败均非零退出
347
+ npm run test:lifecycle # index.js 生命周期/恢复/保守回退探针(需要 DSH)
348
+ npm run test:naming # 真实 publicToolName 歧义/截断哈希探针(需要 DSH)
349
+ npm run test:restrict # 真实 tools.restrict 注册/卸载/重注册探针(需要 DSH)
350
+ npm run test:activation # 真实 ToolsService + activation 零层/竞态/多 agent 探针(需要 DSH)
351
+ node test-persisted-mcp.mjs # MCP 定义持久化/重挂载检查
193
352
  ```
194
353
 
195
354
  契约见 `CONTRACTS-v3.md`(v2 在 `CONTRACTS.md`,v1 在 `CONTRACTS-v1.md`)。