dsh-skill-tag 0.1.2 → 0.1.4

package/README.md

@@ -27,6 +27,53 @@ office * plugin       # 只要 office 包带来的、且是插件相关
 | **打开技能所在文件夹** | 任何列出技能的地方都有 📁 按钮，一点即在文件管理器里定位 |
 | **自带一个 skill** | 安装后你的 agent 会获得 `tagging-skills`，能照着文档自己给技能打标签 |
 
+## 界面预览
+
+> 全部是真实实例截图（105 个技能 / 48 个标签 / 一个开了筛选的工作区），没有 mock。
+> 图片源文件在 `images/`（不进 npm 包，README 里用 raw 绝对地址，GitHub 与 npm 都能显示）。
+
+### 图 1 · 入口：会话行「…」→「管理标签」
+
+<img src="https://raw.githubusercontent.com/aawef/dsh-skill-manager-tags/main/images/session-menu.png" width="240" alt="会话行菜单里的管理标签入口">
+
+对话级的配置就挂在会话行的「…」菜单最下面，不用去翻设置页。
+
+### 图 2 · 入口：命令面板里的 `/skill-tag-manage`
+
+<img src="https://raw.githubusercontent.com/aawef/dsh-skill-manager-tags/main/images/command-palette.png" width="820" alt="命令面板中的管理对话标签命令">
+
+在输入框敲 `/` 也能直接开「管理对话标签」——同一个界面，省一次点菜单。
+
+### 图 3 · 打标签：设置 →「Skill 标签」
+
+<img src="https://raw.githubusercontent.com/aawef/dsh-skill-manager-tags/main/images/tag-settings.png" width="620" alt="Skill 标签管理页：新建标签、按来源分组的标签列表">
+
+三个页签分工明确：**tag 联系 skill**（一个标签包含哪些技能）、**skill 联系 tag**
+（一个技能拥有哪些标签）、**编辑标签组**（写表达式存模板）。
+标签按来源分组（`来自:aegis 23 个 Skill`），每条带 `tagId` 和「全局删除」。
+
+### 图 4 · 一个技能看它身上有哪些标签
+
+<img src="https://raw.githubusercontent.com/aawef/dsh-skill-manager-tags/main/images/skill-to-tags.png" width="640" alt="skill 联系 tag：左列技能、右列标签勾选">
+
+左列 `技能 (105)` 每行标着它有几个标签；右边勾选**即时保存**，不用点确认。
+这是配条件前最常开的一页：先看清楚"这个技能到底被哪些标签命中"。
+
+### 图 5 · 工作区「管理标签」：左写条件，右就是下发名单
+
+<img src="https://raw.githubusercontent.com/aawef/dsh-skill-manager-tags/main/images/workspace-filter.png" width="900" alt="工作区管理标签双列界面">
+
+左列是标签条件，下面实时显示**解析结果**和状态「有条件筛选（严格子集）」；
+右列 `技能 (54)` 就是该工作区下发给模型的全部技能，每行可以「查看 tag」「禁用」，
+📁 直接打开技能所在文件夹。底部还能「+ 精细化添加技能」「查看被禁用的技能」。
+
+### 图 6 · 对话「管理标签（对话）」：可以有自己的一份
+
+<img src="https://raw.githubusercontent.com/aawef/dsh-skill-manager-tags/main/images/conversation-filter.png" width="900" alt="对话级管理标签界面与继承来源">
+
+同一个工作区下的某个对话想单独收窄，就在这里改：它会记下**继承来源**与时间
+（`改动不影响工作区`），左下角一键「继承工作区配置」覆盖回来。
+
 ## 安装
 
 这是一个 DSH（DeepSeek Harness）**插件**，装进 profile 后随宿主启动加载。
@@ -97,6 +144,8 @@ sha256sum "$S/lib/client.js" "$D/lib/client.js" | cut -c1-16
 - **skill 联系 tag** —— 选一个技能，勾它拥有哪些标签
 - **编辑标签组** —— 写表达式、存成模板
 
+界面长什么样见上方「图 3」「图 4」。
+
 也可以让 agent 自己做：安装后 `tagging-skills` 这个 skill 会出现在技能列表里，
 里面是完整的推导法 + API 调用纪律。**不要照抄文档里的标签名**（`aegis`、`office-skills`
 只是某一台机器上的实例），按自己机器的技能清单推导。
@@ -114,10 +163,10 @@ node tools/auto-tag.mjs ... --domain ./my-domain-map.json --apply # 连领域轴
 ### 2. 给工作区/对话配条件
 
 - **工作区**：侧栏工作区行的「…」菜单 →「管理标签」
-- **对话**：会话行的「…」菜单，或聊天框左下角「+」→「管理对话标签」
+- **对话**：会话行的「…」菜单（图 1），或聊天框左下角「+」→「管理对话标签」（图 2）
 
 左列写标签条件表达式，右列是命中结果（可手动添加 / 禁用 / 恢复）。改完立刻生效：
-该对话下发给模型的技能列表就是右列那一份。
+该对话下发给模型的技能列表就是右列那一份。两张双列界面见「图 5」「图 6」。
 
 ### 3. 表达式语法
 
@@ -132,6 +181,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**
@@ -180,27 +249,29 @@ src/storage/         storage domain schema + repository
 src/reveal.js        拉起系统文件管理器
 skills/tagging-skills/  随插件注册给宿主的一个 skill
 tools/auto-tag.mjs      一键打标签脚本（dry-run 默认）
-tests/               node:test，183 项
+tests/               node:test，192 项
 docs/                设计文档（见下）
+images/              README 用的界面截图（不进 npm 包）
 ```
 
 ## 文档
 
 | 文件 | 内容 |
 | --- | --- |
-| [docs/给技能打标签.md](docs/给技能打标签.md) | **打标签的完整手册**：三轴设计、API 调用序列、错误对照表、交付检查清单 |
-| [docs/标签组配置.md](docs/标签组配置.md) | 表达式编辑页的设计与验收 |
-| [docs/管理标签.md](docs/管理标签.md) | 工作区双列配置 |
-| [docs/对话管理标签.md](docs/对话管理标签.md) | 对话级配置与继承 |
-| [docs/技能发现与宿主对齐.md](docs/技能发现与宿主对齐.md) | 为什么"插件看到的技能数"曾经少于宿主，以及怎么对齐 |
-| [docs/skill联系tag与打开文件夹.md](docs/skill联系tag与打开文件夹.md) | 两个方向编辑 + 📁 按钮 |
-| [CHANGELOG.md](CHANGELOG.md) | 按日期倒序的完整开发记录 |
+| [docs/给技能打标签.md](https://github.com/aawef/dsh-skill-manager-tags/blob/main/docs/%E7%BB%99%E6%8A%80%E8%83%BD%E6%89%93%E6%A0%87%E7%AD%BE.md) | **打标签的完整手册**：三轴设计、API 调用序列、错误对照表、交付检查清单 |
+| [docs/标签组配置.md](https://github.com/aawef/dsh-skill-manager-tags/blob/main/docs/%E6%A0%87%E7%AD%BE%E7%BB%84%E9%85%8D%E7%BD%AE.md) | 表达式编辑页的设计与验收 |
+| [docs/管理标签.md](https://github.com/aawef/dsh-skill-manager-tags/blob/main/docs/%E7%AE%A1%E7%90%86%E6%A0%87%E7%AD%BE.md) | 工作区双列配置 |
+| [docs/对话管理标签.md](https://github.com/aawef/dsh-skill-manager-tags/blob/main/docs/%E5%AF%B9%E8%AF%9D%E7%AE%A1%E7%90%86%E6%A0%87%E7%AD%BE.md) | 对话级配置与继承 |
+| [docs/技能发现与宿主对齐.md](https://github.com/aawef/dsh-skill-manager-tags/blob/main/docs/%E6%8A%80%E8%83%BD%E5%8F%91%E7%8E%B0%E4%B8%8E%E5%AE%BF%E4%B8%BB%E5%AF%B9%E9%BD%90.md) | 为什么"插件看到的技能数"曾经少于宿主，以及怎么对齐 |
+| [docs/deny-shadow-覆盖率.md](https://github.com/aawef/dsh-skill-manager-tags/blob/main/docs/deny-shadow-%E8%A6%86%E7%9B%96%E7%8E%87.md) | 为什么包带来的技能会**静默漏网**（`path` 为 null 的那批），以及宿主对影子候选的强校验、层/rank 语义 |
+| [docs/skill联系tag与打开文件夹.md](https://github.com/aawef/dsh-skill-manager-tags/blob/main/docs/skill%E8%81%94%E7%B3%BBtag%E4%B8%8E%E6%89%93%E5%BC%80%E6%96%87%E4%BB%B6%E5%A4%B9.md) | 两个方向编辑 + 📁 按钮 |
+| [CHANGELOG.md](https://github.com/aawef/dsh-skill-manager-tags/blob/main/CHANGELOG.md) | 按日期倒序的完整开发记录 |
 
 ## 开发
 
 ```bash
 npm install
-npm test          # 183 项
+npm test          # 192 项
 ```
 
 测试分两类，都在 `tests/` 下：
@@ -209,7 +280,7 @@ npm test          # 183 项
 - `__*.mjs` —— 手工脚本：HTTP 全链路冒烟（`__api-smoke`）、用迷你 React 运行时
   执行真实组件并断言渲染结构（`__page-render` 等）
 
-**两个 glob 都要**，`npm test` 已经配好；只跑 `tests/**/*.test.mjs` 会漏掉 45 个用例。
+**两个 glob 都要**，`npm test` 已经配好；只跑 `tests/**/*.test.mjs` 会漏掉 46 个用例。
 
 界面预览可以在没有浏览器扩展时生成静态 HTML：
 
@@ -235,4 +306,4 @@ node docs/preview/render-preview.mjs     # → docs/preview/标签组配置-prev
 
 ## 许可证
 
-MIT — 见 [LICENSE](LICENSE)。
+MIT — 见 [LICENSE](https://github.com/aawef/dsh-skill-manager-tags/blob/main/LICENSE)。

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

@@ -0,0 +1,125 @@
+# deny-shadow 的覆盖率：为什么包带来的技能永远屏蔽不掉
+
+> 2026-10-22。线上实测复现 + 修复。适用于 `lib/index.js` 的 `createFilterProvider` /
+> `createUpstreamAdapter` / `createSkillDiscoverer`。
+
+## 1. 现象
+
+模型上下文里技能目录 71 条，插件口径 `universe 105 / visible 54 / denied 51`：
+
+- 71 − 17 = 54 = 插件 `visible` → 数字自洽，说明**恰好 17 个本该被屏蔽的技能漏网**；
+- 成功屏蔽 34 个，全部来自文件系统技能根（`~/.dsh/skills` 33 + `~/.agents/skills` 1）；
+- 漏网 17 个，全部来自别的 provider / npm 包 / 运行时：
+
+| 来源 | 数量 | 名字 |
+| --- | --- | --- |
+| aegis（bundled） | 4 | using-aegis, update-aegis, writing-skills, communicating-concisely |
+| mattpocock（custom） | 4 | ask-matt, research, teach, writing-for-agents |
+| archify | 1 | archify |
+| dsh-skill-tag（本插件） | 1 | tagging-skills |
+| office（bundled，`path` 为 null） | 7 | office, office-docx, office-export-pdf, office-pptx, office-recalculate, office-render, office-xlsx |
+
+分界线极干净：**`path` 落在文件系统技能根的 → 被屏蔽；由别的 provider 送进来的 → 全部漏网。**
+
+失效是**静默**的：插件日志、右列界面、`/skill-tag/api/skills` 全都对（universe 105），
+只有模型侧少了那 17 条影子。
+
+## 2. 根因
+
+### 2.1 发射范围 = 本次可见的 summary
+
+```js
+// 修前
+for (const summary of summaries) {
+  if (denied.has(summary.name)) shadows.push({ ...summary, invocation: DENY })
+}
+```
+
+只看得见的手才发影子。**看不见的名字，就算在 `denied` 里也一个字节都不发。**
+
+### 2.2 范围为何会变窄：重入守卫把宿主快照整段跳过
+
+`createUpstreamAdapter.summaries()` 在 `nesting.depth > 0` 时跳过
+`hostRegistry.snapshot()`，只剩扫盘结果：
+
+```js
+if (hostRegistry && nesting.depth === 0) { ... await hostRegistry.snapshot(...) }
+```
+
+### 2.3 守卫为何会被占住：与发现器共用一份计数器
+
+修前 `apply()` 里只有一份 `snapshotGuard`，同时交给 `createUpstreamAdapter` 与
+`createSkillDiscoverer`。于是任何**另一个** snapshot 在飞 —— 设置页 discoverer、
+skill-explorer / skills-manager 的 UI 快照、另一个 agent 的收集、`domain/changed`
+引发的并发刷新 —— 都会把否认路径挤成"只看得到扫盘结果"。
+
+触发是**时序相关**的，不是永久失效，所以更像偶发：同一时刻
+`GET /skill-tag/api/skills` 仍返回 105（那条路走的是发现器）。
+
+## 3. 宿主语义（修复必须遵守）
+
+`@deepseek-ai/dsh-skill`（asar 0.2.1-rc.2，源码核实）：
+
+| 事实 | 位置 |
+| --- | --- |
+| `layers = [global, ...chainLayers(scope)]`，逐层 `merged.set(name, entry)` → **近层整条覆盖同名**（不是按字段合并） | `collectFresh` |
+| 层内才按 `rank` 升序去重（`compareIndexedCandidates`：rank → providerOrder → localOrder） | `collectLayer` / `compareIndexedCandidates` |
+| `RUNTIME_RANK = 250`，`BUNDLED_SKILL_RANK = 600` | 同包常量 |
+| `validateCandidate` 强制：`name` 匹配 `/^[a-z0-9]+(?:-[a-z0-9]+)*$/`、`description` 非空字符串、`invocation` 是对象、`source` 字符串、`rank` 有限数、`provider` 必须等于 provider 自己的名字 | `validateCandidate` |
+| 候选校验失败 → `provider.list()` 抛错 → 宿主只记一条 `skill provider ... skipped` 并**丢弃该 provider 的全部候选** | `listLayerCandidates` 的 try/catch |
+| 模型侧口径：`snapshot({cwd, signal, scope: agent}).skills.filter(isModelInvocable)` | `dsh-tool-skill` |
+
+## 4. 修复
+
+三件事一起做（`lib/index.js`）：
+
+1. **影子按名字发**：`list()` 分两段 —— 看得见的照抄 summary；看不见的直接造一条
+   最小合法候选（`name` / `description` / `source` / `rank` / `provider` / `invocation`
+   齐全）。屏蔽是按键名生效的，不需要知道那名字长什么样。
+2. **两个出口各用一份计数器**：递归那圈只在 adapter 内部，`createSkillDiscoverer`
+   不在回路里；共用只会互相连坐。发现器另加同 key 并发合并。
+3. **观测**：发生补发时打一行 warn（`shadow backfill ... backfilled=N`，
+   降级时再带 `hostSnapshot=skipped(nested)`）；健康路径不刷日志。
+   `denied` 里的脏名字也会单独 warn，而不是让整批影子被宿主丢掉。
+
+配套细节：
+
+- `rank` 统一取 **0**，不照抄上游 rank。office 是 600，若同层里另有 rank 250 的
+  同名候选，影子会被顶掉 —— 屏蔽随即失效。
+- 上游 `summaries()` 抛错时**不再 `return []`**：返回空增量等于把全部技能放行，
+  正是本 bug 的一个分支。现在降级为"只用 `denied` 补影子"。
+- `source` 兜底为 `"skill-tag"`：上游 summary 缺 `source` 时宿主会以"非字符串"整段丢弃。
+
+## 5. 验证
+
+`tests/shadow-coverage.test.mjs`（8 条）：
+
+- 守卫被占 / 宿主 `snapshot` 直接抛错时，`denied` 里 22 个名字**全部**拿到影子；
+- 且造出来的候选逐个通过宿主 `validateCandidate` 的等价校验；
+- 脏名字只跳过自己，不炸整批；
+- 健康路径不刷日志、降级路径必留痕；
+- 同一名字只发一条影子。
+
+`tests/runtime.test.mjs` 另锁住"另一个出口在飞时否认路径仍要问宿主"。
+
+仓外的 `probe-nesting.mjs`（假 hostRegistry 23 技能 / 扫盘 7 个 / denied 全量）
+修前 `CASE B: emitted=7 missed=16`，修后 `emitted=23 missed=0`。
+
+## 6. 未决
+
+1. **补发会造出"幽灵影子"**：`denied` 里有、但本机已卸载的名字（历史标签残留）也会
+   拿到一条影子。它 `modelInvocable:false`，模型侧不可见（被 `isModelInvocable` 过滤），
+   只可能在技能列表 UI 里多一条「blocked by skill-tag」。要彻底消除需要给
+   `skill_links` 加路径/存在性证据，暂不做。
+2. `recomputeDenials` 的 `universe` 在降级那一趟仍然偏窄（`denied` 靠
+   `computeDeniedSkillIds` 兜底把已打标签的补了回来）。未打标签、且这一趟看不见的
+   技能不会被判 deny —— 下一趟正常快照会纠正，且不影响已知名单。
+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/docs//346/212/200/350/203/275/345/217/221/347/216/260/344/270/216/345/256/277/344/270/273/345/257/271/351/275/220.md

@@ -109,24 +109,36 @@ createSkillDiscoverer({ hostRegistry, rootsScan, agents })
 > 重新收集一遍 → 再次 `list()` → 再次 `summaries()` → 无限递归。
 > 所以嵌套时直接跳过宿主快照，只用自扫描（fs 扫描无重入）。
 
-#### 4.2.1 两个出口必须**共用**一份计数器
+#### 4.2.1 两个出口各用一份计数器（2026-10-22 修正）
 
-否认路径（`recomputeDenials` → `upstream.summaries`）和设置页路径
-（`createSkillDiscoverer`）问的是**同一个** `ctx.skills`，而这一圈重入
-**跨两个工厂函数**：
+> 早先的写法是**共用**一份 `snapshotGuard`，理由写的是"这一圈跨两个工厂函数"。
+> 那个理由是错的，而且代价很大：共用之后，设置页/UI 快照只要在飞，否认路径就被
+> 连坐判成"嵌套" → 跳过宿主快照 → 只看得见扫盘结果 → 包带来的技能全部漏网。
+> 详见 `docs/deny-shadow-覆盖率.md`。
 
+递归那一圈其实**只在 adapter 自己内部**：
+
+```
+provider.list() → freshen() → recomputeDenials() → upstream.summaries()
+  → hostRegistry.snapshot()          ← adapter 自己的守卫在这里 +1
+    → 宿主 collect → 收集到本插件自己的 provider
+      → provider.list() → freshen()（refreshing 里已有本 sessionId，直接返回）
+        → upstream.summaries()       ← 守卫已 > 0，跳过宿主快照 → 收敛
 ```
-设置页 /skills（带 scope）
-  → hostRegistry.snapshot()
-    → 收集到本插件的 per-agent provider
-      → provider.list() → freshen()
-        → recomputeDenials() → upstream.summaries()   ← 又要问宿主
+
+`createSkillDiscoverer` 不在这条回路里（它不是 provider，宿主的 snapshot 不会
+回调它），所以它的计数器与 deny 路径无关。`apply()` 里现在各自建一份：
+
+```js
+const upstreamGuard = { depth: 0 };   // → createUpstreamAdapter
+const discoverGuard = { depth: 0 };   // → createSkillDiscoverer
 ```
 
-各自一个计数器就互相看不见，于是递归到爆栈。`apply()` 里现在建一份
-`const snapshotGuard = { depth: 0 }`，同时传给 `createUpstreamAdapter` 与
-`createSkillDiscoverer`；两个工厂的函数签名都是 `guard = { depth: 0 }`
-（默认自己一份，测试/单用不受影响）。
+另外发现器里做了**同 key 并发合并**（`inFlight`）：设置页一次会并发打好几个
+接口，cwd + conversationId 相同的请求共用一次宿主快照，避免"自己把自己判成嵌套"。
+
+即使某次真的降级了（守卫被占 / 宿主抛错），**屏蔽结果也不再受影响** ——
+`provider.list()` 会按 `denied` 补齐看不见的名字，见 4.4。
 
 #### 4.2.2 否认路径也要带 `scope`
 
@@ -141,6 +153,34 @@ createSkillDiscoverer({ hostRegistry, rootsScan, agents })
 `convPayload` 全部 await 化；新增第三参 `hint = {conversationId, workspaceId}`
 透传给发现器。
 
+### 4.4 deny-shadow 按**名字**发射，不按"这一趟看得见谁"
+
+`createFilterProvider.list()` 原来只遍历 `upstream.summaries()` 的结果：
+
+```js
+for (const summary of summaries) if (denied.has(summary.name)) shadows.push(...)
+```
+
+于是**发射范围 = 本次能看到的 summary**。任何一次"看不见"的降级（守卫被占、
+宿主快照抛错）都会让 `denied` 里那些包带来的技能一条影子都收不到 —— 它们是原样
+透给模型，而不是被屏蔽。这就是 aegis / mattpocock / archify / office /
+tagging-skills 那 17 个长期漏网的原因（详见 `deny-shadow-覆盖率.md`）。
+
+现在分两段：
+
+1. 看得见的：照抄上游 summary（保留 `path` / `description`），只换 `invocation`
+   与 `provider`，`rank` 取 `0`；
+2. 看不见的：给 `denied` 里的每个名字**造一条最小合法候选** —— 屏蔽是按键名
+   生效的，不需要知道它长什么样。
+
+`rank: 0` 是硬约束：宿主只在**层内**按 `rank` 升序去重（`compareIndexedCandidates`），
+跨层是"近层整条覆盖"。照抄上游 rank（office = `BUNDLED_SKILL_RANK` 600）时，
+同层里若有 rank 更小的同名候选，影子会被顶掉。
+
+`denied` 里的历史脏名字（带空格 / 大写 / 中文）必须先过宿主的 kebab-case 校验
+再发 —— 一个不合法候选会让**整个** `provider.list()` 抛错，宿主随即丢弃本插件的
+全部贡献（日志 `skill provider "skill-tag" skipped`），比漏一个更糟。
+
 ## 5. 约束（踩过的坑）
 
 - **cordis 服务必须声明式注入**：`export const inject` 里没有的服务，读 `ctx.xxx`

package/lib/index.js

@@ -25,10 +25,36 @@ import { scanSkillRoots } from "../src/skill-scan.js";
 import { loadBundledSkill } from "../src/skill-doc.js";
 
 const PROVIDER_NAME = "skill-tag";
+/** 影子候选的 source（宿主要求是字符串，且只用于展示/排序以外的标识）。 */
+const PROVIDER_SOURCE = "skill-tag";
 
 const ON = { modelInvocable: true, userInvocable: true };
 const DENY = { modelInvocable: false, userInvocable: false };
 
+/**
+ * 宿主对 provider 返回的候选是**强校验**的（@deepseek-ai/dsh-skill validateCandidate）：
+ *   name 必须匹配 /^[a-z0-9]+(?:-[a-z0-9]+)*$/、description 非空字符串、
+ *   source 字符串、rank 有限数、provider 必须等于本 provider 的名字、
+ *   invocation 必须是对象且两个字段都是 boolean。
+ * 任一候选不合法 → **整个 provider.list() 抛错** → 宿主把本插件的贡献整段丢弃
+ * （日志："skill provider ... skipped"）→ 一个影子都不发，全部技能漏网。
+ * 所以「凭空造影子」时必须先过这一关，脏名字宁可丢掉也不能让它炸掉整批。
+ */
+const SKILL_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+function isSkillName(name) {
+	return typeof name === "string" && SKILL_NAME_RE.test(name);
+}
+
+/**
+ * 影子在**同一层内**的排序键（compareIndexedCandidates：rank 升序，小的先胜）。
+ * 取 0 而不是沿用上游 rank 的原因：宿主只在层内按 rank 去重，跨层是"近层整条覆盖"。
+ * 如果影子照抄上游 rank（office 是 BUNDLED_SKILL_RANK=600），同层里若有别的
+ * provider 用更小的 rank 提供同名候选（RUNTIME_RANK=250 一类的 agent 层 provider），
+ * 影子会被那条候选顶掉 —— 屏蔽随即失效。0 保证层内必胜。
+ */
+const SHADOW_RANK = 0;
+
 /**
  * Build the per-agent filter provider over a session's policy snapshot.
  * Mirrors proto/lib/index.js createFilterProvider: emits deny-shadows ONLY —
@@ -41,6 +67,7 @@ const DENY = { modelInvocable: false, userInvocable: false };
  * @param {Set<string>} denied  denied skill names for this session (live set)
  * @param {((options:any)=>Promise<void>)|undefined} [ensureFresh]
  *   Lazily (re)compute `denied` right before it is consulted.
+ * @param {((msg:string)=>void)|undefined} [logWarn]  观测出口（方案 C），可缺省。
  *
  *   为什么必须有它（2026-10-20 bug）：`denied` 原先只在 `domain/changed`
  *   事件里被填充，而那个事件由**写操作**触发。新对话第一次列技能时没有任何
@@ -48,7 +75,7 @@ const DENY = { modelInvocable: false, userInvocable: false };
  *   `domain/changed` 才开始过滤。用户看到的就是"第一条消息不受控，第二条才受控"。
  *   把刷新挂到 provider 的读路径上，第一次 `list()` 就已经是正确口径。
  */
-export function createFilterProvider(sessionId, upstream, denied, ensureFresh) {
+export function createFilterProvider(sessionId, upstream, denied, ensureFresh, logWarn) {
 	async function freshen(options) {
 		if (typeof ensureFresh !== "function") return;
 		// 这里抛错只会让本次降级为"沿用旧集合"，绝不冒回宿主。
@@ -59,46 +86,103 @@ export function createFilterProvider(sessionId, upstream, denied, ensureFresh) {
 		async list(options) {
 			await freshen(options);
 			// 宿主会 await 这里；抛出的 rejection 同样可能升级成 fatal。屏蔽技能
-			// 是"锦上添花"，上游扫不动时返回空增量，让宿主看到它原本的技能。
-			let summaries;
+			// 是"锦上添花"，上游扫不动时也不能什么都不发（那样等于全部放行）。
+			let summaries = [];
 			try {
-				summaries = await upstream.summaries(options);
-			} catch {
-				return [];
-			}
+				const got = await upstream.summaries(options);
+				if (Array.isArray(got)) summaries = got;
+			} catch { summaries = []; }
+
+			// ── 第一段：看得见的技能，照抄它的元信息做影子 ────────────────────
+			// 为什么要照抄：宿主 catalog 里这个条目的 description / path / whenToUse
+			// 还是上游那份，影子只换掉 invocation 与 provider，右列能看出"它被屏蔽了"。
 			const shadows = [];
+			const emitted = new Set();
 			for (const summary of summaries) {
-				if (denied.has(summary.name)) {
-					shadows.push({
-						...summary,
-						provider: PROVIDER_NAME,
-						description: "[blocked by skill-tag] " + (summary.description ?? summary.name),
-						invocation: DENY,
-						rank: typeof summary.rank === "number" && Number.isFinite(summary.rank) ? summary.rank : 400,
-					});
-				}
+				if (!summary || !denied.has(summary.name)) continue;
+				shadows.push({
+					...summary,
+					provider: PROVIDER_NAME,
+					source: typeof summary.source === "string" && summary.source !== "" ? summary.source : PROVIDER_SOURCE,
+					description: "[blocked by skill-tag] " + (summary.description || summary.name),
+					invocation: DENY,
+					rank: SHADOW_RANK,
+				});
+				emitted.add(summary.name);
+			}
+
+			// ── 第二段：denied 里但这一趟看不见的名字（本 bug 的根因补丁）──────
+			// 2026-10-22：原实现只遍历 summaries，于是"发射范围 = 本次能看到的
+			// summary"。当重入守卫被占住（另一个 snapshot 在飞）时宿主快照被整段
+			// 跳过，summaries 只剩扫盘结果 → 由别的 provider / npm 包 / 运行时送进来
+			// 的技能（aegis / mattpocock / archify / office / tagging-skills）
+			// 一条影子都没有，原样漏给模型（线上实测 17 个）。
+			// 修法：屏蔽是**按名字**生效的，不需要知道那名字长什么样 —— 看不见的
+			// 名字直接造一条最小合法候选，就能在近层整条覆盖上游那份。
+			let backfilled = 0;
+			const invalid = [];
+			for (const name of denied) {
+				if (emitted.has(name)) continue;
+				if (!isSkillName(name)) { invalid.push(name); continue; }
+				shadows.push({
+					name,
+					description: `[blocked by skill-tag] ${name}`,
+					provider: PROVIDER_NAME,
+					source: PROVIDER_SOURCE,
+					rank: SHADOW_RANK,
+					invocation: DENY,
+				});
+				emitted.add(name);
+				backfilled += 1;
+			}
+			// 方案 C：把这一趟的口径暴露出来。只在"确实发生了补发"或"有脏名字被
+			// 丢掉"时出声，健康路径一条日志都不写。
+			if (typeof logWarn === "function") {
+				try {
+					if (backfilled > 0) {
+						logWarn(`[skill-tag] shadow backfill session=${sessionId}`
+							+ ` visible=${summaries.length} denied=${denied.size}`
+							+ ` shadowed=${emitted.size} backfilled=${backfilled}`
+							+ `${upstream.lastDegraded === true ? " hostSnapshot=skipped(nested)" : ""}`);
+					}
+					if (invalid.length > 0) {
+						logWarn(`[skill-tag] denied names skipped (not kebab-case): ${invalid.slice(0, 8).join(", ")}`);
+					}
+				} catch { /* 观测不得影响主路径 */ }
 			}
 			return shadows;
 		},
 		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;
+			}
 		},
 	};
 }
@@ -118,14 +202,21 @@ export function createUpstreamAdapter({ rootsScan, hostRegistry, guard = { depth
 	 * 重新收集一遍 → 再次 list() → 再次 summaries() → 无限递归。
 	 * 所以嵌套时直接跳过宿主快照，只用自扫描（fs 扫描无重入）。
 	 *
-	 * `guard` 与 createSkillDiscoverer 共用（同一份 apply() 里的两个出口都问
-	 * 同一个 registry），否则「设置页带 scope 快照 → 我们的 provider → 否认路径
-	 * 再快照」会在两个计数器之间互相看不见。
+	 * 2026-10-22 修正：**不要再和 createSkillDiscoverer 共用一个计数器**。
+	 * 共用的后果是设置页那条读路径把计数器占住时，模型侧的否认路径也被迫降级
+	 * 成"只看得见扫盘结果"，于是包带来的技能全部漏网（线上 17 个）。
+	 * 递归那圈本来就只在 adapter 自己内部（snapshot → 宿主 collect → 本 provider
+	 * 的 list → freshen → 本 adapter 的 summaries），一份 adapter 自己的计数器
+	 * 就足以截断，discoverer 的计数器与它无关。
 	 */
 	const nesting = guard;
+	/** 本 adapter 最近一次 summaries() 是否跳过了宿主快照（只做观测用）。 */
+	let lastDegraded = false;
 	return {
+		get lastDegraded() { return lastDegraded; },
 		async summaries(options) {
 			const opts = options ?? {};
+			lastDegraded = false;
 			// 三段都可能抛（fs 权限、宿主 registry 未就绪、signal aborted）。
 			// 调用方是宿主的 provider 链，这里降级成"只看到能看到的那些"。
 			let scanned = [];
@@ -144,6 +235,10 @@ export function createUpstreamAdapter({ rootsScan, hostRegistry, guard = { depth
 					});
 					snapSkills = Array.isArray(snap?.skills) ? snap.skills : [];
 				} catch { snapSkills = []; } finally { nesting.depth -= 1; }
+			} else if (hostRegistry) {
+				// 有宿主但被嵌套挡住 —— 这一趟只看得到扫盘结果。调用方（provider.list）
+				// 会靠 denied 集合把看不见的名字补成影子，这里留个痕迹便于排查。
+				lastDegraded = true;
 			}
 			const byName = new Map();
 			for (const s of snapSkills) if (s?.name) byName.set(s.name, s);
@@ -268,6 +363,8 @@ export function runtimeDeniedSkills(ws, universe, candidates) {
  */
 export function createSkillDiscoverer({ hostRegistry, rootsScan, agents = null, guard = { depth: 0 } }) {
 	const nesting = guard;
+	/** 同 key 的并发请求合并成一次宿主快照（设置页刚打开时一次会打好几个接口）。 */
+	const inFlight = new Map();
 	/** conversationId（= sessionId）→ agent，用来取宿主 snapshot 的 scope。 */
 	function agentFor(conversationId) {
 		if (!conversationId || !agents || typeof agents.list !== "function") return null;
@@ -275,6 +372,33 @@ export function createSkillDiscoverer({ hostRegistry, rootsScan, agents = null,
 		try { list = agents.list() ?? []; } catch { return null; }
 		return list.find((a) => sessionIdOfAgent(a) === conversationId) ?? null;
 	}
+	/**
+	 * 问一次宿主，拿它的 skills。
+	 * @returns {Promise<object[]|null>} null = 这一趟没问成（守卫被占 / 宿主抛错 / 未就绪）
+	 */
+	function snapshotSkills(cwd, hint, key) {
+		const pending = (async () => {
+			if (!hostRegistry || typeof hostRegistry.snapshot !== "function") return null;
+			if (nesting.depth > 0) return null;
+			nesting.depth += 1;
+			try {
+				const scope = agentFor(hint?.conversationId);
+				const snap = await hostRegistry.snapshot({
+					...(cwd ? { cwd } : {}),
+					...(scope ? { scope } : {}),
+				});
+				return Array.isArray(snap?.skills) ? snap.skills : [];
+			} catch {
+				return null; // registry 未就绪 → 调用方退回自扫描
+			} finally { nesting.depth -= 1; }
+		})();
+		inFlight.set(key, pending);
+		void pending.then(
+			() => { if (inFlight.get(key) === pending) inFlight.delete(key); },
+			() => { if (inFlight.get(key) === pending) inFlight.delete(key); },
+		);
+		return pending;
+	}
 	return async function discoverSkills(cwd, hint) {
 		const out = new Map();
 		const put = (s) => {
@@ -288,18 +412,10 @@ export function createSkillDiscoverer({ hostRegistry, rootsScan, agents = null,
 			});
 		};
 		// 1) 宿主注册表（权威，与模型侧同源）
-		if (hostRegistry && typeof hostRegistry.snapshot === "function" && nesting.depth === 0) {
-			try {
-				nesting.depth += 1;
-				const scope = agentFor(hint?.conversationId);
-				const snap = await hostRegistry.snapshot({
-					...(cwd ? { cwd } : {}),
-					...(scope ? { scope } : {}),
-				});
-				const list = Array.isArray(snap?.skills) ? snap.skills : [];
-				for (const s of list) put(s);
-			} catch { /* registry 未就绪 → 退回自扫描 */ } finally { nesting.depth -= 1; }
-		}
+		const key = `${cwd ?? ""}::${hint?.conversationId ?? ""}`;
+		const pending = inFlight.get(key) ?? snapshotSkills(cwd, hint, key);
+		const hostSkills = await pending;
+		if (Array.isArray(hostSkills)) for (const s of hostSkills) put(s);
 		// 2) 自扫描补缺（不同名才补）
 		if (rootsScan) {
 			try {
@@ -591,7 +707,7 @@ export async function apply(ctx, config) {
 							// list() → 再次进 freshen，但 `refreshing` 里有本 sessionId，
 							// 第二趟直接返回，不会递归。
 							await refreshBySession(sessionId, options?.cwd ?? agentCwd, agent);
-						});
+						}, (message) => ctx.logger?.warn?.(message));
 					}),
 				),
 			);
@@ -602,17 +718,27 @@ export async function apply(ctx, config) {
 	}
 
 	// 两个出口（设置页的 discoverer 与否认路径的 upstream）问的是同一个
-	// `ctx.skills`，必须共用一份重入计数器：设置页带 scope 快照 → 宿主收集到
-	// 本插件的 per-agent provider → freshen → 否认路径再快照，这一圈跨两个
-	// 工厂函数，各自一个计数器就互相看不见。
-	const snapshotGuard = { depth: 0 };
+	// `ctx.skills`，但**重入计数器必须各用一份**。
+	//
+	// 2026-10-22 修正（此前是共用一份）：共用时，设置页那条读路径（或
+	// skill-explorer / skills-manager 的 UI 快照、另一个 agent 的收集、并发刷新）
+	// 只要有一个 snapshot 在飞，否认路径就被一起判成"嵌套" → 跳过宿主快照 →
+	// 只看得见扫盘结果 → 由别的 provider / npm 包 / 运行时送进来的技能全部漏网。
+	// 线上实测：34 个被屏蔽，17 个（aegis / mattpocock / archify / office /
+	// tagging-skills）永远穿透，而且完全静默。
+	//
+	// 现在递归只可能发生在 adapter 自己内部（snapshot → 宿主 collect → 本 provider
+	// 的 list → freshen → 本 adapter 的 summaries），一份 adapter 自己的计数器就够；
+	// 而且 provider.list 在看不见时会按 denied 补齐影子，压根不依赖这次快照。
+	const upstreamGuard = { depth: 0 };
+	const discoverGuard = { depth: 0 };
 
 	const upstream = createUpstreamAdapter({
 		hostRegistry: ctx.skills ?? null,
 		// rootsScan: host plane cannot see preset-layer providers; scan the
 		// official skill roots ourselves (skill-explorer pattern, discovery §5.4).
 		rootsScan: (options) => scanSkillRoots(options?.cwd, config?.customSkillDirs ?? []),
-		guard: snapshotGuard,
+		guard: upstreamGuard,
 	});
 
 	ctx.effect(() => () => { controls.clear(); sessionDenials.clear(); });
@@ -689,7 +815,7 @@ export async function apply(ctx, config) {
 				hostRegistry: ctx.skills ?? null,
 				rootsScan: (options) => scanSkillRoots(options?.cwd ?? null, config?.customSkillDirs ?? []),
 				agents: (() => { try { return ctx.get("agents") ?? null; } catch { return null; } })(),
-				guard: snapshotGuard,
+				guard: discoverGuard,
 			}),
 			// 会话 → 工作区 id：宿主 workspaceRegistry 是权威来源
 			(sessionId) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-skill-tag",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "给 DSH 的技能（skill）打标签，用一条布尔表达式在「工作区 / 对话」两级选出要下发给模型的技能子集",
   "type": "module",
   "main": "lib/index.js",
@@ -40,7 +40,10 @@
       "patch": "./cordis.patch.yml"
     },
     "client": {
-      "inject": ["@deepseek-ai/dsh-client-runtime", "@deepseek-ai/dsh-client-ui-slots"],
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-slots"
+      ],
       "platform": "web"
     }
   },