dsh-skill-tag 0.1.3 → 0.1.5

package/README.md

@@ -110,10 +110,13 @@ dsh plugin --profile <your-profile> add github:aawef/dsh-skill-manager-tags
 
 > 依赖 Node ≥ 20；需要 DSH `0.2.0-rc.1` 及以上（见 `engines.dsh`）。
 >
-> 宿主的 `@deepseek-ai/cordis` 与 `@deepseek-ai/dsh-storage-domain` 都声明为
-> **peerDependency**，由 DSH 本体提供，**不要自己安装**：本插件会 `import` 它的 `defineDomain`
-> 来注册存储域，必须与宿主使用同一份模块实例，装成 `dependencies` 会把旧版本提到 profile
-> 顶层、遮蔽宿主版本，导致 `workspaceController` 等服务无法上台（详见 CHANGELOG 2026-10-21）。
+> 宿主的 `@deepseek-ai/cordis` 声明为 **peerDependency**，由 DSH 本体提供，**不要自己安装**。
+>
+> 存储域 spec 由本插件 `src/storage/domain-spec.js` 本地构造（等价于宿主的 `defineDomain` /
+> `domainTable`），运行时通过 `ctx.storageDomain.open()` 交给宿主打开，**不 import 任何宿主内核包**。
+> 这样 profile 里不会出现与宿主同名的第二份模块副本：早期版本曾 `import`
+> `@deepseek-ai/dsh-storage-domain`，宿主升级（如 `0.2.1-rc.2` → `rc.3`）时那份旧副本会被判定
+> 不兼容并拒绝加载，导致存储域整体不启动、会话与工作区列表全空（详见 CHANGELOG 2026-10-24）。
 
 ### 本地开发式安装
 
@@ -181,6 +184,26 @@ node tools/auto-tag.mjs ... --domain ./my-domain-map.json --apply # 连领域轴
 表达式会被编译成 DNF（`{orTags, andGroups}`）再交给匹配引擎。
 标签改名时，**所有引用它的表达式会被按 token 原位改写**，不会失效。
 
+### 4. 路由型技能（router）别被拆散
+
+有些技能的职责就是「帮你挑别的技能」——description 里出现 *Use when the user asks…*
+*Router over the skills…* 这类措辞，还常带有 `skill-filesystem` 之类的下挂资源。
+
+插件**只按名字屏蔽，从不改任何 `SKILL.md` 的内容**，所以路由器自己的提示词一个字都不会变。
+会坏的是**依赖关系**：路由器可见、而它指向的技能被屏蔽时，模型照着提示去加载只会拿到
+`skill "X" is not available for model invocation` —— 这一轮路由白跑，还可能让模型反复试。
+
+所以配条件时请**把路由器和它的簇当成一个整体**（用簇标签一次圈住，别按领域标签零散地挑）：
+
+| 你想要的 | 表达式 |
+| --- | --- |
+| 整个簇（路由器 + 7 个 office 技能） | `routes:office` |
+| 只要路由器本身，不要成员 | `router * routes:office` |
+| 只要成员，不要路由器（自己挑，不需要分发提示） | `routes:office * !router` |
+
+插件运行时不认识"谁是路由器"（router 只是标签约定），这一层耦合靠表达式自己保证完整。
+选完可以用 `POST /skill-tag/api/workspaces/skills` 回读 `candidates`，确认路由器的簇成员没被拆散。
+
 ## HTTP API
 
 挂在 `/skill-tag/api` 前缀下。所有路由**同时接受 GET 和 POST**
@@ -229,7 +252,7 @@ src/storage/         storage domain schema + repository
 src/reveal.js        拉起系统文件管理器
 skills/tagging-skills/  随插件注册给宿主的一个 skill
 tools/auto-tag.mjs      一键打标签脚本（dry-run 默认）
-tests/               node:test，192 项
+tests/               node:test，194 项
 docs/                设计文档（见下）
 images/              README 用的界面截图（不进 npm 包）
 ```
@@ -251,7 +274,7 @@ images/              README 用的界面截图（不进 npm 包）
 
 ```bash
 npm install
-npm test          # 192 项
+npm test          # 194 项
 ```
 
 测试分两类，都在 `tests/` 下：

package/docs/deny-shadow-/350/246/206/347/233/226/347/216/207.md

@@ -114,6 +114,12 @@ skill-explorer / skills-manager 的 UI 快照、另一个 agent 的收集、`dom
 2. `recomputeDenials` 的 `universe` 在降级那一趟仍然偏窄（`denied` 靠
    `computeDeniedSkillIds` 兜底把已打标签的补了回来）。未打标签、且这一趟看不见的
    技能不会被判 deny —— 下一趟正常快照会纠正，且不影响已知名单。
-3. `provider.get()` 对影子名字会回问宿主 `get`，而宿主选中的又是影子自己 →
+3. ~~`provider.get()` 对影子名字会回问宿主 `get`，而宿主选中的又是影子自己 →
    理论上可自递归。实际不可达（影子两个 invocation 都是 false，模型与 `/命令`
-   都调不到），暂不改。
+   都调不到），暂不改。~~
+   **2026-10-22 更正：可达，已修。** 模型侧走 `skill` 工具确实调不到（先 `list()`，
+   影子 `modelInvocable:false` 直接抛错），但 `dsh-tool-skill` 的 `agent/pre-step`
+   对 `/name` 手势是**先 `get` 再判 `userInvocable`**（line 909），于是人打一轮
+   `/<被屏蔽的技能名>` 就会触发 `registry.get → provider.get → registry.get`
+   的无限回环（async，栈不涨、Promise 不 settle → 静默卡死）。
+   现在 `get()` 对 denied 名字直接返回 deny 定义（`content: ""`），不再回问宿主。

package/lib/index.js

@@ -154,23 +154,35 @@ export function createFilterProvider(sessionId, upstream, denied, ensureFresh, l
 		},
 		async get(candidate, options) {
 			await freshen(options);
-			let base;
-			try {
-				base = await upstream.getDefinition(candidate, options);
-			} catch {
-				return undefined;
-			}
-			if (!base) return undefined;
+			// 被屏蔽的名字：**绝不**再回问宿主。
+			//
+			// 2026-10-22 实测的坑：宿主 registry.get(name) 的流程是
+			//   collect() → 选中胜出候选（在我们的 agent 层里就是这条影子）
+			//   → 调**影子自己的** provider.get(candidate)
+			// 而我们原先在这里调用 upstream.getDefinition → hostRegistry.get(name)
+			// → 又选中影子 → 又是我们 → registry.get 被无限反复调用。
+			// 一轮 `/<被屏蔽的技能名>` 就能撞上：dsh-tool-skill 的 agent/pre-step
+			// 对 `/name` 手势是**先 get 再判 invocation**（lib 内 line 909），
+			// 所以这条路真实可达，后果是 pre-step 永不 resolve（界面卡住）。
+			//
+			// 影子本来就没有正文可给（DENY + content:""），直接造定义即可；
+			// 形状必须满足宿主 validateDefinition：name/description/source/provider
+			// 非空字符串、invocation 是对象、content 是字符串。
 			if (denied.has(candidate.name)) {
 				return {
-					...base,
+					name: candidate.name,
+					description: `[blocked by skill-tag] ${candidate.description || candidate.name}`,
 					provider: PROVIDER_NAME,
-					description: `[blocked by skill-tag] ${base.description ?? candidate.description}`,
+					source: PROVIDER_SOURCE,
 					invocation: DENY,
 					content: "",
 				};
 			}
-			return base;
+			try {
+				return await upstream.getDefinition(candidate, options);
+			} catch {
+				return undefined;
+			}
 		},
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-skill-tag",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "给 DSH 的技能（skill）打标签，用一条布尔表达式在「工作区 / 对话」两级选出要下发给模型的技能子集",
   "type": "module",
   "main": "lib/index.js",
@@ -52,14 +52,13 @@
     "test:unit": "node --test \"tests/*.test.mjs\""
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": ">=4.0.2 <5",
-    "@deepseek-ai/dsh-storage-domain": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-rc.1 || 0.2.1-rc.2 || >=0.3.0 <1.0.0"
+    "@deepseek-ai/cordis": ">=4.0.2 <5"
   },
   "dependencies": {
     "zod": "^3.25.76"
   },
   "engines": {
     "node": ">=20",
-    "dsh": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-rc.1 || 0.2.1-rc.2 || >=0.2.1 <1.0.0"
+    "dsh": ">=0.2.0-rc.1 <1.0.0"
   }
 }

package/src/storage/domain-spec.js

@@ -0,0 +1,73 @@
+// skill-tag-plugin — 本地 domain spec 构造器
+//
+// 为什么不用 @deepseek-ai/dsh-storage-domain：
+//
+// 宿主已经通过 ctx.storageDomain.open(spec) 把 domain 能力注入进来了，插件真正
+// 需要的只是把 spec 构造宿主认识的形状：
+//
+//   { name, version, tables: { <tableName>: { valueSchema } }, global?, layout?, ... }
+//
+// 而宿主的 defineDomain 只做「校验 + 原样返回」，domainTable 只做
+// `{ valueSchema: schema }`。为了这两个纯函数去 import 内核包，会让 pnpm 必须
+// 在 profile 里再装一份 @deepseek-ai/dsh-storage-domain 实体，与宿主内置的同名
+// 模块形成「同一模块两份不同版本」——宿主每次升级（rc.2 → rc.3）都会因为旧副本
+// 被运行时判定不兼容而拒绝加载该插件，导致存储域整体不启动、会话与工作区列表
+// 全空。该故障在 0.2.0-rc.2 时代已经发生过一次（见 profiles/desktop/
+// pnpm-workspace.yaml 的 historical 注释），当时的做法是挪版本号 + 人工提醒，
+// 属于在地基上缝补。
+//
+// 现在改为本地等价实现，插件对宿主内核包零 import 依赖：升级宿主不再需要同步
+// 任何版本号，也不再有双份模块。
+//
+// 校验规则与宿主保持一致（宿主 @deepseek-ai/dsh-storage 的 UNIT_NAME_RE 为
+// /^[a-z][a-z0-9_]*$/；domain 名与表名都必须匹配）。宿主在 open() 时仍会二次
+// 校验，这里的校验只是让配置错误在模块加载时就暴露。
+
+const UNIT_NAME_RE = /^[a-z][a-z0-9_]*$/;
+
+/**
+ * 声明一张表：宿主只要求 { valueSchema } 这一层包装。
+ * @param {import("zod").ZodTypeAny} schema - 行记录的 zod schema
+ */
+export function domainTable(schema) {
+	return { valueSchema: schema };
+}
+
+/**
+ * 声明一个 domain：校验后原样返回 spec（与宿主 defineDomain 行为一致）。
+ * @param {object} spec - { name, version, tables, global?, layout?, compatibleVersions?, invalidRecords? }
+ */
+export function defineDomain(spec) {
+	if (!UNIT_NAME_RE.test(spec.name)) {
+		throw new Error(`domain name '${spec.name}' must match ${UNIT_NAME_RE}`);
+	}
+	if (!Number.isInteger(spec.version) || spec.version < 0) {
+		throw new Error(`domain '${spec.name}' version must be a non-negative integer, got ${spec.version}`);
+	}
+	for (const compat of spec.compatibleVersions ?? []) {
+		if (!Number.isInteger(compat) || compat < 0 || compat >= spec.version) {
+			throw new Error(
+				`domain '${spec.name}' compatibleVersions entries must be non-negative integers below version ${spec.version}, got ${compat}`,
+			);
+		}
+	}
+	if (spec.layout !== void 0 && spec.layout !== "single" && spec.layout !== "per-record") {
+		throw new Error(`domain '${spec.name}' layout must be 'single' or 'per-record', got ${spec.layout}`);
+	}
+	if (spec.invalidRecords !== void 0 && spec.invalidRecords !== "backup-and-skip") {
+		throw new Error(`domain '${spec.name}' invalidRecords must be 'backup-and-skip' when present, got ${spec.invalidRecords}`);
+	}
+	for (const table of Object.keys(spec.tables)) {
+		if (!UNIT_NAME_RE.test(table)) {
+			throw new Error(`domain '${spec.name}' table name '${table}' must match ${UNIT_NAME_RE}`);
+		}
+	}
+	// 宿主的 global schema 不接受 null：null 是介质的「从未写入」哨兵，
+	// 存进去的 null 无法与「不存在」区分，重新打开会静默回落到 initial。
+	if (spec.global !== void 0 && spec.global.schema.safeParse(null).success) {
+		throw new Error(
+			`domain '${spec.name}' global schema must not accept null: null is the medium's "never written" sentinel`,
+		);
+	}
+	return spec;
+}

package/src/storage/schema.js

@@ -1,8 +1,11 @@
 // skill-tag-plugin — storage domain schema (spec §12: 9 entity classes)
 //
-// Backed by @deepseek-ai/dsh-storage-domain defineDomain (evidence:
-// docs/evidence/extract-dsh-storage-domain.js — zod record schemas, KvTable
-// get/put/delete/update/entries, domain/changed events, caller closes).
+// Spec 形状由本仓库 src/storage/domain-spec.js 本地构造，刻意不 import 宿主内核包
+// @deepseek-ai/dsh-storage-domain（原因见该文件头部注释）。运行时通过
+// ctx.storageDomain.open(skillTagDomain) 交给宿主打开。
+//
+// KvTable 能力（get/put/delete/update/entries、domain/changed 事件、caller closes）
+// 来自宿主注入的 domain handle，见 docs/evidence/extract-dsh-storage-domain.js。
 //
 // Entity → table mapping (§12 table, one row per entity unless noted):
 //   tags            全局标签        {tagId, name, createdAt}   key=tagId
@@ -15,7 +18,7 @@
 //  "不要求必须用四张独立数据表"; they must persist, which they do here.)
 
 import { z } from "zod";
-import { defineDomain, domainTable } from "@deepseek-ai/dsh-storage-domain";
+import { defineDomain, domainTable } from "./domain-spec.js";
 
 // ── record schemas ──────────────────────────────────────────────────────────