dsh-skill-tag 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-skill-tag contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,238 @@
-# Temporary Holding Version
+# dsh-skill-tag
 
-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.
+给 DSH 的**技能（skill）**打标签，然后用一条**布尔表达式**在「工作区 / 对话」两级
+选出真正要下发给模型的技能子集。
+
+装了几十上百个 skill 之后，真正的痛点不是"怎么分类"，而是"**这次对话只想让模型
+看到哪几个**"。全部下发会撑爆上下文、也会让路由互相打架；手工一条条开关又太累。
+这个插件把这件事变成一条表达式：
+
+```
+pdf + docx            # 只要处理文档的技能
+office * plugin       # 只要 office 包带来的、且是插件相关
+(aegis + tdd) * !wip  # 两个都要，且排除 wip
+```
+
+## 它能做什么
+
+| 能力 | 说明 |
+| --- | --- |
+| **全局标签** | 建/改名/删除标签，标签之间无层级 |
+| **标签组模板** | 把表达式存成模板（`前端组`、`只留本机技能`…），可复用、可求值 |
+| **布尔表达式** | `+`=OR、`*`=AND、`*` 优先、支持括号；改标签名会自动改写所有引用它的表达式 |
+| **工作区级筛选** | 每个工作区一套条件，只把命中的技能下发给该工作区的对话 |
+| **对话级筛选** | 每个对话可以有**自己的**快照，独立于所属工作区；可一键「继承工作区配置」 |
+| **禁用 / 手动添加** | 在标签命中之外额外放行某个技能，或强行屏蔽某个（即使它命中） |
+| **技能 ↔ 标签双向编辑** | 「tag 联系 skill」和「skill 联系 tag」两个方向都能改 |
+| **打开技能所在文件夹** | 任何列出技能的地方都有 📁 按钮，一点即在文件管理器里定位 |
+| **自带一个 skill** | 安装后你的 agent 会获得 `tagging-skills`，能照着文档自己给技能打标签 |
+
+## 安装
+
+这是一个 DSH（DeepSeek Harness）**插件**，装进 profile 后随宿主启动加载。
+
+### 一条命令
+
+```bash
+dsh plugin --profile <your-profile> add dsh-skill-tag
+```
+
+还没发布到 npm 之前，直接用仓库地址装：
+
+```bash
+dsh plugin --profile <your-profile> add github:aawef/dsh-skill-manager-tags
+```
+
+`dsh plugin` 本质是把参数转发给 profile 目录里的 pnpm，**它不会替你启用插件** ——
+装完还要在 profile 的 `package.json` 的 `dsh.profile.bundles` 数组里加上 `"dsh-skill-tag"`：
+
+```json
+{
+  "dsh": {
+    "profile": {
+      "bundles": [ "...", "dsh-skill-tag" ]
+    }
+  }
+}
+```
+
+**重启 DSH** 后生效（设置页会出现「Skill 标签」一项）。
+
+> 官方 DSH 桌面端的 `desktop` profile 归应用独占，命令行改不动它 ——
+> 桌面端请在 **Settings → Plugins** 或插件市场里安装。
+
+> 依赖 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）。
+
+### 本地开发式安装
+
+如果你直接改源码，注意**源码目录和 profile 的 `node_modules` 里那份是两个物理文件**，
+改完必须手动复制并校验哈希：
+
+```bash
+S=/path/to/your/dsh-skill-tag
+D=~/.dsh/profiles/<profile>/node_modules/dsh-skill-tag
+cp "$S/lib/client.js" "$D/lib/client.js"
+sha256sum "$S/lib/client.js" "$D/lib/client.js" | cut -c1-16
+```
+
+生效规则（很重要，搞混了会以为"改了没用"）：
+
+| 文件 | 改完之后 |
+| --- | --- |
+| `lib/client.js` | **刷新页面**即可（宿主 no-cache 加载） |
+| `lib/index.js`、`src/**`、`cordis.patch.yml` | **重启桌面进程** |
+
+## 怎么用
+
+### 1. 打标签
+
+设置 →「Skill 标签」，三个按钮：
+
+- **tag 联系 skill** —— 选一个标签，勾它包含哪些技能
+- **skill 联系 tag** —— 选一个技能，勾它拥有哪些标签
+- **编辑标签组** —— 写表达式、存成模板
+
+也可以让 agent 自己做：安装后 `tagging-skills` 这个 skill 会出现在技能列表里，
+里面是完整的推导法 + API 调用纪律。**不要照抄文档里的标签名**（`aegis`、`office-skills`
+只是某一台机器上的实例），按自己机器的技能清单推导。
+
+或者直接跑一键脚本（先 dry-run）：
+
+```bash
+node tools/auto-tag.mjs http://127.0.0.1:<PORT>                  # 只看计划，不落地
+node tools/auto-tag.mjs http://127.0.0.1:<PORT> --apply          # 落地来源轴
+node tools/auto-tag.mjs ... --domain ./my-domain-map.json --apply # 连领域轴一起
+```
+
+脚本幂等，重跑应输出 `tagsCreated: 0`。
+
+### 2. 给工作区/对话配条件
+
+- **工作区**：侧栏工作区行的「…」菜单 →「管理标签」
+- **对话**：会话行的「…」菜单，或聊天框左下角「+」→「管理对话标签」
+
+左列写标签条件表达式，右列是命中结果（可手动添加 / 禁用 / 恢复）。改完立刻生效：
+该对话下发给模型的技能列表就是右列那一份。
+
+### 3. 表达式语法
+
+| 语法 | 含义 |
+| --- | --- |
+| `A + B` | OR |
+| `A * B` | AND |
+| `(A + B) * C` | 括号；`*` 优先级高于 `+` |
+| `"my tag"` | 标签名含空格或 `+ * ( )` 时加引号（所以起名请用 kebab-case） |
+| 空串 | 无条件 = 全部技能（合法的"不筛选"） |
+
+表达式会被编译成 DNF（`{orTags, andGroups}`）再交给匹配引擎。
+标签改名时，**所有引用它的表达式会被按 token 原位改写**，不会失效。
+
+## HTTP API
+
+挂在 `/skill-tag/api` 前缀下。所有路由**同时接受 GET 和 POST**
+（`q(k) = body[k] ?? url.searchParams.get(k)`），所以浏览器直接敲 URL 也能调试。
+响应一律是 JSON；出错是 `{ok:false, error, code}`。
+
+| 路由 | 方法 | 主要参数 | 说明 |
+| --- | --- | --- | --- |
+| `/state` | GET | — | 全量快照：tags / skillLinks / templates / workspaces / conversations |
+| `/skills` | GET | `cwd` | 可打标签的技能清单（带 `path`）。**带 `cwd` 才能扫到项目级 `.dsh/skills`** |
+| `/skills/tags` | GET/POST | `skillName`, `tagIds` | 读/写一个技能拥有的标签。**写是整体覆盖**，见下方警告 |
+| `/skills/reveal` | POST | `skillName` 或 `path` | 拉起文件管理器定位该技能 |
+| `/tags` | POST | `tagId`, `name` | 建标签（同名会报 `already exists`） |
+| `/tags/rename` | POST | `tagId`, `name` | 改名并同步改写所有表达式 |
+| `/tags/link` | POST | `skillId`, `tagIds` | 关联 |
+| `/tags/unlink` | POST | `skillId` | 解除关联 |
+| `/tags/delete` | POST | `tagId` | 全局删除，返回 `affectedWorkspaces` |
+| `/templates/validate` | GET/POST | `expression` | 校验 → `{ok, errors, normalized, dnf, config}` |
+| `/templates/evaluate` | GET/POST | `templateId` | 求值（**要 `templateId`，不是 expression**） |
+| `/templates/expand` | GET/POST | `templateId` | 展开 |
+| `/templates` `/templates/update` `/templates/delete` | POST | — | 模板 CRUD |
+| `/workspaces/expression` | POST | `workspaceId`, `expression` | 改工作区条件 |
+| `/workspaces/skills` | GET | `workspaceId` | 读该工作区的候选项（`candidates`） |
+| `/workspaces/skills/add` `remove` `disable` `enable` | POST | `workspaceId`, `skillName` | 手动添加/移除/禁用/恢复 |
+| `/conversations/config` | GET/POST | `conversationId` | 对话双列配置的读/写 |
+| `/conversations/inherit` | POST | `conversationId` | 整体覆盖式继承所属工作区配置 |
+| `/conversations/candidates` | GET | `conversationId` | 该对话实际生效的技能列表 |
+
+> **警告**：`/skills/tags` 的写是**整体覆盖**。写之前必须先 GET 读回旧 `tagIds`
+> 再合并，否则会清掉已有标签。这是最容易踩的坑。
+
+## 目录结构
+
+```
+lib/index.js         宿主侧入口（ESM）：注册 filter provider / storage domain / HTTP API / 自带 skill
+lib/client.js        浏览器侧界面（__ModuleLoader__ 工厂，无构建步骤）
+src/domain/
+  expr.js            表达式引擎：tokenize / parse / toDnf / dnfToConfig / validateExpression
+  match.js           匹配：matches / candidatesFor
+  origin.js          来源轴推导（从 path 推出这个技能是哪个包带来的）
+  conv.js            对话四区状态（加载/豁免/未加载/屏蔽）
+  workspace.js       工作区视图
+src/api.js           HTTP 路由
+src/service.js       服务层（CRUD + 改名同步 + 迁移）
+src/storage/         storage domain schema + repository
+src/reveal.js        拉起系统文件管理器
+skills/tagging-skills/  随插件注册给宿主的一个 skill
+tools/auto-tag.mjs      一键打标签脚本（dry-run 默认）
+tests/               node:test，183 项
+docs/                设计文档（见下）
+```
+
+## 文档
+
+| 文件 | 内容 |
+| --- | --- |
+| [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) | 按日期倒序的完整开发记录 |
+
+## 开发
+
+```bash
+npm install
+npm test          # 183 项
+```
+
+测试分两类，都在 `tests/` 下：
+
+- `*.test.mjs` —— 单元/领域测试，被 `node --test` 自动收集
+- `__*.mjs` —— 手工脚本：HTTP 全链路冒烟（`__api-smoke`）、用迷你 React 运行时
+  执行真实组件并断言渲染结构（`__page-render` 等）
+
+**两个 glob 都要**，`npm test` 已经配好；只跑 `tests/**/*.test.mjs` 会漏掉 45 个用例。
+
+界面预览可以在没有浏览器扩展时生成静态 HTML：
+
+```bash
+node docs/preview/render-preview.mjs     # → docs/preview/标签组配置-preview.html
+```
+
+（产物已在 `.gitignore` 里排除。）
+
+### 改插件时的几条硬约束
+
+这几条都是踩过的坑，源码注释里也写了：
+
+- **宿主服务是声明式注入的**：没写进 `export const inject` 的服务，`ctx.<service>`
+  读属性会**直接抛** `cannot get property "x" without inject`。而且
+  `ctx.x ?? ctx.get("x")` 这种兜底照样抛 —— 左侧求值时就炸了。只能 `ctx.get()` + try/catch。
+- **注册给宿主的回调里抛异常 = host fatal**（整个桌面进程挂掉）。
+  `domain/changed` 监听器、provider 的 `list`/`get`、`apply()` 同步栈，全部 self-contain。
+- **新增 HTTP 路由必须重启桌面进程**，否则新路由 404 —— 这个 404 极易被误判成
+  "路由名写错了"。
+- `ctx.effect(() => fn())` 的 thunk **立刻执行**，它的**返回值**才是 dispose。
+  写成 `ctx.effect(() => domain.close())` 会在装配阶段就把 domain 关掉。
+
+## 许可证
+
+MIT — 见 [LICENSE](LICENSE)。

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+# dsh-skill-tag bundle patch: register the skill-tag host plugin (filter provider + storage domain + web API).
+- insert:
+    - id: dsh-skill-tag
+      name: dsh-skill-tag

package/docs/preview/render-conv-preview.mjs

@@ -0,0 +1,327 @@
+// 生成「对话 → 管理标签」界面的可视化预览（不依赖浏览器控制扩展）
+//
+// 做法同 render-manage-preview.mjs：用迷你 React 运行时真正执行 lib/client.js 里的
+// ManageTagsDialog（对话作用域）与 TagSettingsDialog，序列化成 HTML，再用 headless Edge 截图。
+//
+// 用法：node docs/preview/render-conv-preview.mjs
+// 产物：docs/preview/对话管理标签-preview.html
+
+import fs from "node:fs";
+import vm from "node:vm";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(HERE, "..", "..");
+const SOURCE = fs.readFileSync(path.join(ROOT, "lib", "client.js"), "utf8");
+const FRAGMENT = Symbol("Fragment");
+
+const TAGS = [
+	{ tagId: "t-a", name: "前端" },
+	{ tagId: "t-b", name: "测试" },
+	{ tagId: "t-c", name: "文档" },
+];
+const TEMPLATES = [
+	{ templateId: "tpl-1", name: "前端组", expression: "前端+测试*文档" },
+	{ templateId: "tpl-2", name: "纯后端", expression: "(前端+测试)*文档" },
+];
+const UNIVERSE = ["code-review", "tdd", "docx", "xlsx", "pdf", "webapp-testing"];
+const LINKS = [
+	{ skillId: "code-review", tagIds: ["t-a"] },
+	{ skillId: "tdd", tagIds: ["t-b"] },
+	{ skillId: "docx", tagIds: ["t-c"] },
+	{ skillId: "pdf", tagIds: ["t-c"] },
+];
+
+function makeFetcher(state) {
+	const hasFilter = () => state.expression.trim() !== "";
+	const hit = (name) => {
+		const ids = new Set((LINKS.find((l) => l.skillId === name)?.tagIds) ?? []);
+		if (!hasFilter()) return true;
+		return ids.has("t-a") || (ids.has("t-b") && ids.has("t-c"));
+	};
+	const view = () => {
+		const f = hasFilter();
+		const matched = f ? UNIVERSE.filter(hit) : UNIVERSE.slice();
+		const visible = [];
+		for (const n of matched) if (!state.disabledSkills.includes(n)) visible.push(n);
+		for (const n of state.manualSkills) if (!state.disabledSkills.includes(n) && !visible.includes(n)) visible.push(n);
+		return { hasFilter: f, matched, manual: state.manualSkills.slice(), disabled: state.disabledSkills.slice(), visible };
+	};
+	const payload = () => ({
+		ok: true,
+		conversationId: state.conversationId,
+		workspaceId: state.sourceWorkspaceId,
+		expression: state.expression,
+		config: hasFilter() ? { orTags: ["t-a"], andGroups: [{ groupId: "g1", tagIds: ["t-b", "t-c"] }] } : { orTags: [], andGroups: [] },
+		manualSkills: state.manualSkills.slice(),
+		disabledSkills: state.disabledSkills.slice(),
+		inheritedAt: state.inheritedAt,
+		sourceWorkspaceId: state.sourceWorkspaceId,
+		candidates: hasFilter() ? UNIVERSE.filter(hit) : [],
+		universe: UNIVERSE,
+		view: view(),
+	});
+	const respond = (p) => {
+		if (p === "/state") return { ok: true, tags: TAGS, skillLinks: LINKS, templates: TEMPLATES, workspaces: [], conversations: [] };
+		if (p === "/conversations/config") return payload();
+		if (p === "/conversations/inherit") {
+			// 假装工作区那份配置：前端+测试*文档 / 手动 xlsx / 禁用 pdf
+			state.expression = "前端+测试*文档";
+			state.manualSkills = ["xlsx"];
+			state.disabledSkills = ["pdf"];
+			state.sourceWorkspaceId = "ws-1";
+			state.inheritedAt = new Date().toISOString();
+			return payload();
+		}
+		if (p === "/conversations/expression") { state.expression = JSON.parse(state.lastBody ?? "{}").expression ?? ""; return { ok: true, conversation: {} }; }
+		if (p === "/conversations/skills/disable") {
+			const n = JSON.parse(state.lastBody ?? "{}").skillName;
+			state.disabledSkills.push(n);
+			state.manualSkills = state.manualSkills.filter((s) => s !== n);
+			return { ok: true, conversation: {} };
+		}
+		if (p === "/conversations/skills/enable") {
+			const n = JSON.parse(state.lastBody ?? "{}").skillName;
+			state.disabledSkills = state.disabledSkills.filter((s) => s !== n);
+			return { ok: true, conversation: {} };
+		}
+		if (p === "/conversations/skills/add") { state.manualSkills.push(JSON.parse(state.lastBody ?? "{}").skillName); return { ok: true, conversation: {} }; }
+		if (p === "/templates/validate") {
+			if (state.expression.trim() === "") {
+				return { ok: true, validation: { ok: true, errors: [], warnings: [], normalized: "", config: { orTags: [], andGroups: [] } } };
+			}
+			return {
+				ok: true,
+				validation: {
+					ok: true, errors: [], warnings: [], normalized: state.expression,
+					config: { orTags: ["t-a"], andGroups: [{ groupId: "g1", tagIds: ["t-b", "t-c"] }] },
+				},
+			};
+		}
+		return { ok: true };
+	};
+	return async (url, init) => {
+		const p = String(url).replace("/skill-tag/api", "");
+		if (init?.body) state.lastBody = init.body;
+		const out = respond(p);
+		return { json: async () => out };
+	};
+}
+
+function makeRuntime() {
+	const stores = new Map();
+	const pendingEffects = [];
+	function storeOf(Comp) {
+		let s = stores.get(Comp);
+		if (!s) { s = { hooks: [], cursor: 0 }; stores.set(Comp, s); }
+		return s;
+	}
+	const react = {
+		createElement: (type, props, ...children) => ({
+			type, props: props ?? {},
+			children: children.flat(Infinity).filter((c) => c !== null && c !== undefined && c !== false),
+		}),
+		Fragment: FRAGMENT,
+		useState(init) {
+			const s = storeOf(react.__cur);
+			const i = s.cursor++;
+			if (!(i in s.hooks)) s.hooks[i] = typeof init === "function" ? init() : init;
+			return [s.hooks[i], (n) => { s.hooks[i] = typeof n === "function" ? n(s.hooks[i]) : n; }];
+		},
+		useRef(init) {
+			const s = storeOf(react.__cur);
+			const i = s.cursor++;
+			if (!(i in s.hooks)) s.hooks[i] = { current: init ?? null };
+			return s.hooks[i];
+		},
+		useEffect(fn) { storeOf(react.__cur).cursor++; pendingEffects.push(fn); },
+		useMemo(fn) { storeOf(react.__cur).cursor++; return fn(); },
+		useCallback(fn) { storeOf(react.__cur).cursor++; return fn; },
+	};
+	function renderComponent(Comp, props) {
+		const s = storeOf(Comp);
+		s.cursor = 0;
+		const prev = react.__cur;
+		react.__cur = Comp;
+		try { return Comp(props); } finally { react.__cur = prev; }
+	}
+	function drain() {
+		for (const fn of pendingEffects.splice(0)) { try { fn(); } catch { /* 忽略 */ } }
+	}
+	function expand(node, depth = 0) {
+		if (node === null || node === undefined || node === false) return node;
+		if (typeof node !== "object") return node;
+		if (depth > 40) return node;
+		if (typeof node.type === "function") return expand(renderComponent(node.type, node.props), depth + 1);
+		return { ...node, children: (node.children ?? []).map((c) => expand(c, depth + 1)) };
+	}
+	/** 注意：必须 expand 之后才 drain，否则子组件（TagSettingsDialog）的 effect 不会入队 */
+	async function settle(Comp, props, rounds = 10) {
+		let tree = null;
+		for (let r = 0; r < rounds; r += 1) {
+			pendingEffects.length = 0;
+			tree = expand(renderComponent(Comp, props));
+			drain();
+			await new Promise((res) => setTimeout(res, 0));
+			await new Promise((res) => setTimeout(res, 0));
+		}
+		pendingEffects.length = 0;
+		tree = expand(renderComponent(Comp, props));
+		drain();
+		return tree;
+	}
+	return { react, settle };
+}
+
+const ESC = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" };
+const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ESC[c]);
+
+function toHtml(node) {
+	if (node === null || node === undefined || node === false) return "";
+	if (typeof node !== "object") return esc(node);
+	const { type, props = {}, children = [] } = node;
+	if (typeof type === "function") return "";
+	const inner = children.map(toHtml).join("");
+	const tag = typeof type === "string" ? type : "div";
+	const attrs = [];
+	const p = props ?? {};
+	if (p.style && typeof p.style === "object") {
+		attrs.push(`style="${esc(Object.entries(p.style).map(([k, v]) => `${k.replace(/[A-Z]/g, (m) => "-" + m.toLowerCase())}:${v}`).join(";"))}"`);
+	}
+	if (p.className) attrs.push(`class="${esc(p.className)}"`);
+	if (tag === "input") {
+		if (p.value !== undefined) attrs.push(`value="${esc(p.value)}"`);
+		if (p.placeholder) attrs.push(`placeholder="${esc(p.placeholder)}"`);
+		if (p.type) attrs.push(`type="${esc(p.type)}"`);
+		if (p.checked) attrs.push("checked");
+		return `<input ${attrs.join(" ")}>`;
+	}
+	if (tag === "textarea") {
+		if (p.value !== undefined) attrs.push(`value="${esc(p.value)}"`);
+		return `<textarea ${attrs.join(" ")}>${esc(p.value ?? "")}</textarea>`;
+	}
+	if (tag === "select") {
+		const opts = children.map((c) => {
+			if (!c || typeof c !== "object" || c.type !== "option") return toHtml(c);
+			const sel = c.props?.value === p.value ? " selected" : "";
+			return `<option value="${esc(c.props?.value ?? "")}"${sel}>${esc((c.children ?? []).map(toHtml).join(""))}</option>`;
+		}).join("");
+		return `<select ${attrs.join(" ")}>${opts}</select>`;
+	}
+	if (tag === "option") return `<option>${inner}</option>`;
+	if (tag === "button") {
+		if (p.disabled) attrs.push("disabled");
+		return `<button ${attrs.join(" ")}>${inner}</button>`;
+	}
+	return `<${tag} ${attrs.join(" ")}>${inner}</${tag}>`;
+}
+
+const walk = (n, f) => { if (!n || typeof n !== "object") return; f(n); for (const c of n.children ?? []) walk(c, f); };
+const findBtn = (tree, label) => {
+	const out = [];
+	walk(tree, (n) => {
+		if (n.type === "button" && (n.children ?? []).map(String).join("").trim() === label) out.push(n);
+	});
+	return out;
+};
+
+/** 载入 client.js，取回 shell.overlay 组件与 __test 助手 */
+function boot(rt, state) {
+	const sandbox = { console, setTimeout, clearTimeout, fetch: makeFetcher(state), window: { confirm: () => true, __ModuleLoader__: { load: () => {} } } };
+	sandbox.globalThis = sandbox;
+	vm.runInNewContext(SOURCE, sandbox, { filename: "lib/client.js" });
+	const out = { Dialog: null, helpers: null };
+	sandbox.window.__ModuleLoader__.load = ({ factory }) => {
+		const exp = factory((n) => (n === "react" ? rt.react : {}));
+		out.helpers = exp.__test;
+		exp.apply({
+			effect: (fn) => fn(),
+			slots: { inject: (_n, fn) => fn(), register: (o, C) => { if (o.name === "shell.overlay") out.Dialog = C; } },
+		});
+	};
+	// 再跑一次源码，这次 load 已就位，模块才会真正执行并注册槽位
+	vm.runInNewContext(SOURCE, sandbox, { filename: "lib/client.js" });
+	return out;
+}
+
+function scene(title, note, bodyHtml) {
+	return `<div class="cap"><b>${esc(title)}</b> ${note}</div><div class="shot">${bodyHtml}</div>`;
+}
+
+const htmls = [];
+
+// 场景①：对话已继承工作区配置（条件 + 手动添加 + 禁用一起搬过来），可在其上继续改
+{
+	const rt = makeRuntime();
+	const state = {
+		conversationId: "sess-7f3a", expression: "前端+测试*文档",
+		manualSkills: ["xlsx"], disabledSkills: ["pdf"],
+		sourceWorkspaceId: "ws-1", inheritedAt: new Date().toISOString(), lastBody: null,
+	};
+	const { Dialog, helpers } = boot(rt, state);
+	helpers.manageSet({ open: true, workspaceId: "", conversationId: "sess-7f3a" });
+	const tree = await rt.settle(Dialog, {});
+	htmls.push(scene(
+		"场景① 对话双列（已继承工作区）",
+		"左列多出「继承工作区配置」按钮，并标注继承来源与时间；右列技能同样可查看 tag / 禁用 / 添加",
+		`<div class="shot">${toHtml(tree)}</div>`,
+	));
+}
+
+// 场景②：对话尚未继承任何工作区（独立配置）
+{
+	const rt = makeRuntime();
+	const state = {
+		conversationId: "sess-9c11", expression: "",
+		manualSkills: [], disabledSkills: [],
+		sourceWorkspaceId: null, inheritedAt: null, lastBody: null,
+	};
+	const { Dialog, helpers } = boot(rt, state);
+	helpers.manageSet({ open: true, workspaceId: "", conversationId: "sess-9c11" });
+	const tree = await rt.settle(Dialog, {});
+	htmls.push(scene(
+		"场景② 对话双列（未继承，独立配置）",
+		"空条件 = 该对话掌握全部技能；点击「继承工作区配置」会把工作区那份整体搬过来",
+		`<div class="shot">${toHtml(tree)}</div>`,
+	));
+}
+
+// 场景③：对话版「tag 设置」—— 载入标签组后可继续编辑，保存目标是「对话」而不是工作区
+{
+	const rt = makeRuntime();
+	const state = {
+		conversationId: "sess-9c11", expression: "前端+测试",
+		manualSkills: [], disabledSkills: [],
+		sourceWorkspaceId: "ws-1", inheritedAt: new Date().toISOString(), lastBody: null,
+	};
+	const { Dialog, helpers } = boot(rt, state);
+	helpers.manageSet({ open: true, workspaceId: "", conversationId: "sess-9c11" });
+	let tree = await rt.settle(Dialog, {});
+	findBtn(tree, "tag 设置")[0]?.props?.onClick?.();
+	tree = await rt.settle(Dialog, {});
+	// 载入标签组「前端组」的运算
+	let sel = null;
+	walk(tree, (n) => { if (n.type === "select" && (n.children ?? []).some((c) => (c.children ?? []).map(String).join("").includes("前端组"))) sel = n; });
+	sel?.props?.onChange?.({ target: { value: "tpl-1" } });
+	tree = await rt.settle(Dialog, {});
+	htmls.push(scene(
+		"场景③ 对话版「tag 设置」",
+		"载入标签组「前端组」的运算到运算区后可继续编辑；底部按钮是 <b>保存到对话</b>，不会改工作区",
+		`<div class="shot">${toHtml(tree)}</div>`,
+	));
+}
+
+const head = `<!doctype html><html lang="zh"><head><meta charset="utf-8"><title>对话管理标签 · 界面预览</title>
+<style>
+ body{margin:0;background:#0e1117;color:#d7dce5;font-family:"Microsoft YaHei",ui-sans-serif,system-ui;padding:14px 0 30px}
+ .cap{padding:12px 24px 4px;font-size:13px;color:#8b93a7} .cap b{color:#e6ebf5}
+ /* 静态预览：把浮层的 fixed/absolute 全部拍平，否则嵌套的「tag 设置」会脱离文档流留下一大段空白 */
+ .shot *{position:static!important}
+ .shot>div{display:block!important;background:transparent!important}
+ .shot>div>div{margin:0 auto}
+ h1{font-size:16px;padding:0 24px;margin:8px 0 4px}
+ code{background:#1b2130;padding:1px 5px;border-radius:4px}
+</style></head><body><h1>对话 → 管理标签 · 界面预览</h1>`;
+fs.writeFileSync(path.join(HERE, "对话管理标签-preview.html"), head + htmls.join("") + "</body></html>");
+console.log("wrote docs/preview/对话管理标签-preview.html");