dsh-armory 2.0.0 → 2.2.0

package/lib/index.js

@@ -12,14 +12,18 @@ import { admitImportedServers } from "./import-admission.js";
 import { collectImportLocations, missingEnvNames, resolveImportLocation } from "./mcp-import-sources.js";
 import { deriveMcpPhase, formatMcpLog, sanitizeMcpLog } from "./mcp-observability.js";
 import { allMcpEntries, entriesForName, projectToolSchema, revisionOf, toolInventory } from "./mcp-registry.js";
+// Skill 看板的卸载落盘点：来源白名单 + 根目录包含性 + 符号链接/根目录校验（lib/skill-remove.js）。
+import { removeSkillFromDisk } from "./skill-remove.js";
 import { WHATS_NEW } from "./whats-new.js";
 import { probeMcpServersAuthorization, wbConnectorCatalog, wbConnectorCachedCount, wbConnectorPreview, wbSkillCatalog, wbSkillDetail, wbSkillInstall, wbSkillInstalled, wbSkillUninstall } from "./wb-market.js";
 // T03：多市场注册表（R4）与 codebuddy 插件市场（R5）的宿主侧数据层。
 import { readRegistry, upsertMarketplace } from "./wb-registry.js";
 import { wbPluginCatalog, wbPluginDetail, wbPluginUpdateCheck } from "./wb-plugin-market.js";
 // T06/Awesome：DSH 社区插件市场（awesome-dsh-plugins）的宿主侧数据层。
-import { wbAwesomeCatalog, wbAwesomeDetail, wbAwesomeUpdateCheck } from "./wb-awesome-market.js";
+import { wbAwesomeCatalog, wbAwesomeDetail, wbAwesomeReadme, wbAwesomeUpdateCheck } from "./wb-awesome-market.js";
 import { readState as readInstallState, record as recordInstallState, forget as forgetInstallState } from "./wb-install-state.js";
+// 自定义套件（Skill 看板）：读 / 整集合覆盖保存，数据层 lib/suites-registry.js。
+import { readSuites as readSkillSuites, saveSuites as writeSkillSuites } from "./suites-registry.js";
 import { applyTokens } from "./wb-auth-rules.js";
 import {
 	authorizationOverview as oauthOverview,
@@ -33,8 +37,8 @@ import {
 } from "./mcp-oauth.js";
 import { hasTeamBridge, installExpertSkills, listExpertRecent, listExpertSkills, prepareExpertPersona, readExpertPresets, recordExpertRecent, removeExpertPreset, uninstallExpertSkills, uninstallTeamMemberPersonas, wbExpertCatalog, wbExpertDetail, writeExpertPreset } from "./expert-market.js";
 import { attachPersona, detachPersona, listPersonas, reconcilePersonas } from "./session-persona.js";
-// OPT-19：clearTextCache 一并引入——toolTailor 的可选动作要回收解压文本缓存。
-import { clearTextCache, scanSessionLedger } from "./tool-ledger.js";
+// clearTextCache 的 import 已随 toolTailor 的「清空缓存」动作一起删掉（见下方 toolTailor 注释）。
+import { scanSessionLedger } from "./tool-ledger.js";
 import { evaluateEnvExpression, jsExpressionToTemplate } from "./workspace-config.js";
 import { canonicalWorkspacePath, installAgentRuntime, listWorkspaceRecords, liveWorkspaceAgentCount, projectConnectionsView, readWorkspaceConfigCached, reconcileWorkspaceConnections, reconcileWorkspaceRestricts, reconnectWorkspaceServer, withWorkspaceWrite, workspaceConnectionStatus, workspaceMountErrorsView, workspaceRestrictErrorView, workspaceScopeErrorsView, workspaceToolSchemas, writeWorkspaceConfigFile } from "./workspace-runtime.js";
 
@@ -989,7 +993,7 @@ async function listMcpServers(ctx) {
 let McpManagerGateway = (() => {
 	let _classSuper = TypertRemoteService;
 	let _instanceExtraInitializers = [];
-	let _list_decorators, _status_decorators, _enable_decorators, _disable_decorators, _reconnect_decorators, _tools_decorators, _builtins_decorators, _installBuiltins_decorators, _add_decorators, _update_decorators, _remove_decorators, _reveal_decorators, _previewImport_decorators, _importJson_decorators, _listWorkspaces_decorators, _getWorkspaceView_decorators, _addWorkspaceServer_decorators, _updateWorkspaceServer_decorators, _removeWorkspaceServer_decorators, _setWorkspaceExclude_decorators, _installWorkspaceBuiltins_decorators, _previewWorkspaceImport_decorators, _importWorkspaceJson_decorators, _revealWorkspaceServer_decorators, _projectConnections_decorators, _reconnectWorkspaceServer_decorators, _updateHint_decorators, _whatsNew_decorators, _scanImportSources_decorators, _previewImportSource_decorators, _importSource_decorators, _toolTailor_decorators, _wbConnectorCatalog_decorators, _wbConnectorCachedCount_decorators, _wbConnectorPreview_decorators, _wbConnectorInstall_decorators, _wbOAuthBegin_decorators, _wbOAuthPoll_decorators, _wbOAuthCancel_decorators, _wbOAuthToken_decorators, _wbOAuthOverview_decorators, _wbOAuthOpen_decorators, _wbSkillCatalog_decorators, _wbSkillDetail_decorators, _wbSkillInstall_decorators, _wbSkillUninstall_decorators, _wbSkillInstalled_decorators, _wbMarketRegistry_decorators, _wbMarketRegistryUpsert_decorators, _wbPluginCatalog_decorators, _wbPluginDetail_decorators, _wbInstallState_decorators, _wbInstallStateRecord_decorators, _wbInstallStateForget_decorators, _wbPluginUpdateCheck_decorators, _wbAwesomeCatalog_decorators, _wbAwesomeDetail_decorators, _wbAwesomeUpdateCheck_decorators;
+	let _list_decorators, _status_decorators, _enable_decorators, _disable_decorators, _reconnect_decorators, _tools_decorators, _builtins_decorators, _installBuiltins_decorators, _add_decorators, _update_decorators, _remove_decorators, _reveal_decorators, _previewImport_decorators, _importJson_decorators, _listWorkspaces_decorators, _getWorkspaceView_decorators, _addWorkspaceServer_decorators, _updateWorkspaceServer_decorators, _removeWorkspaceServer_decorators, _setWorkspaceExclude_decorators, _installWorkspaceBuiltins_decorators, _previewWorkspaceImport_decorators, _importWorkspaceJson_decorators, _revealWorkspaceServer_decorators, _projectConnections_decorators, _reconnectWorkspaceServer_decorators, _updateHint_decorators, _whatsNew_decorators, _scanImportSources_decorators, _previewImportSource_decorators, _importSource_decorators, _toolTailor_decorators, _wbConnectorCatalog_decorators, _wbConnectorCachedCount_decorators, _wbConnectorPreview_decorators, _wbConnectorInstall_decorators, _wbOAuthBegin_decorators, _wbOAuthPoll_decorators, _wbOAuthCancel_decorators, _wbOAuthToken_decorators, _wbOAuthOverview_decorators, _wbOAuthOpen_decorators, _wbSkillCatalog_decorators, _wbSkillDetail_decorators, _wbSkillInstall_decorators, _wbSkillUninstall_decorators, _wbSkillInstalled_decorators, _wbMarketRegistry_decorators, _wbMarketRegistryUpsert_decorators, _wbPluginCatalog_decorators, _wbPluginDetail_decorators, _wbInstallState_decorators, _wbInstallStateRecord_decorators, _wbInstallStateForget_decorators, _wbPluginUpdateCheck_decorators, _wbAwesomeCatalog_decorators, _wbAwesomeDetail_decorators, _wbAwesomeReadme_decorators, _wbAwesomeUpdateCheck_decorators;
 	return class McpManagerGateway extends _classSuper {
 		static {
 			const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
@@ -1111,6 +1115,8 @@ let McpManagerGateway = (() => {
 			__esDecorate(this, null, _wbAwesomeCatalog_decorators, { kind: "method", name: "wbAwesomeCatalog", static: false, private: false, access: { has: (obj) => "wbAwesomeCatalog" in obj, get: (obj) => obj.wbAwesomeCatalog }, metadata: _metadata }, null, _instanceExtraInitializers);
 			_wbAwesomeDetail_decorators = [Remote("wbAwesomeDetail")];
 			__esDecorate(this, null, _wbAwesomeDetail_decorators, { kind: "method", name: "wbAwesomeDetail", static: false, private: false, access: { has: (obj) => "wbAwesomeDetail" in obj, get: (obj) => obj.wbAwesomeDetail }, metadata: _metadata }, null, _instanceExtraInitializers);
+			_wbAwesomeReadme_decorators = [Remote("wbAwesomeReadme")];
+			__esDecorate(this, null, _wbAwesomeReadme_decorators, { kind: "method", name: "wbAwesomeReadme", static: false, private: false, access: { has: (obj) => "wbAwesomeReadme" in obj, get: (obj) => obj.wbAwesomeReadme }, metadata: _metadata }, null, _instanceExtraInitializers);
 			_wbAwesomeUpdateCheck_decorators = [Remote("wbAwesomeUpdateCheck")];
 			__esDecorate(this, null, _wbAwesomeUpdateCheck_decorators, { kind: "method", name: "wbAwesomeUpdateCheck", static: false, private: false, access: { has: (obj) => "wbAwesomeUpdateCheck" in obj, get: (obj) => obj.wbAwesomeUpdateCheck }, metadata: _metadata }, null, _instanceExtraInitializers);
 			if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
@@ -1308,12 +1314,12 @@ let McpManagerGateway = (() => {
 		async toolTailor(payload) {
 			// 只读账本：扫描本机会话日志 + 当前注册表 Schema，见 tool-ledger.js。
 			// days 由调用方传（7/30/90），缺省 30，服务端钳到 [1,365]。
-			// OPT-19：可选清空动作——payload.action === 'clearTextCache' 时先回收解压文本缓存
-			// 再出报告。透传性已核实（typert.js:35 payloadParam 的 schema 是 $any =
-			// z.unknown()，strict 只约束「必须有值」不做键剥离），额外键 action 能从客户端
-			// 原样到达这里，无需新增 RPC 契约。先清后扫：报告里的 textCache 快照直接呈现
-			// 清空后的状态，面板能立即看到「占用已归零」，不必再刷一次。
-			if (payload?.action === "clearTextCache") clearTextCache();
+			// 「清空解压文本缓存」这个可选动作已删（2026-10-23）：它曾声称「先清后扫，面板立即
+			// 看到占用归零」，实测恰好相反 —— 快照取在扫描之后，同一发调用里日志被重新解压回填，
+			// 前后都是 32 条 / 65.8 MB；而 clearTextCache() 的返回值（clearedBytes）压根没进报告
+			// （textCacheStats() 没这个键），面板只能恒显示「正在清空缓存…」。既然既不回收也不修
+			// 任何事，就不再留这条 RPC 分支。tool-ledger.js 仍导出 clearTextCache 原语：它是将来
+			// 真要改缓存策略（槽位按文件数自适应、或只缓存最近若干会话）时的落点，只是现在无人调用。
 			return buildToolTailorReport(this.ctx, payload || {});
 		}
 		async listWorkspaces() {
@@ -1616,6 +1622,41 @@ let McpManagerGateway = (() => {
 		else spawn(process.platform === "darwin" ? "open" : "xdg-open", [path], { detached: true, stdio: "ignore" }).unref();
 		return { note: "已交给系统打开" };
 	}
+	// 卸载一条已安装 skill：永久删除用户级/项目级 skills 根目录内的条目。
+	// 只信注册表给的 source/path（客户端传的路径不参与判断）；bundled / runtime / custom
+	// 由数据层拒绝并给出原因。删除后宿主注册表可能缓存了目录扫描结果——调用方
+	// （SkillBoard）先本地收敛列表再 listSkills 刷新，不把「没立刻消失」当成失败。
+	async removeSkill(payload) {
+		const name = String(payload?.name || "").trim();
+		if (!name) throw new Error("缺少 skill 名称");
+		const result = await withSkillScope(this.ctx, payload, async (registry, options) => {
+			if (typeof registry.get !== "function") throw new Error("宿主没有挂载 skill 注册表（@deepseek-ai/dsh-skill），无法卸载");
+			const skill = await registry.get(name, options);
+			if (!skill) throw new Error("没有找到这个 skill（可能刚被移动或删除）：" + name);
+			return removeSkillFromDisk(skill, { cwd: options.cwd, home: homedir() });
+		});
+		if (result === undefined) throw new Error("宿主没有挂载 skill 注册表（@deepseek-ai/dsh-skill），无法卸载");
+		return { note: `已卸载 ${name}（${result.kind === "symlink" ? "符号链接" : "目录"}：${result.path}）` };
+	}
+	// ── 自定义套件（Skill 看板）─────────────────────────────────────────
+	// 数据层在 lib/suites-registry.js（~/.dsh/armory/suites.json）；这里只做 RPC 转发。
+	//   listSkillSuites —— 永不抛错：文件缺失 / JSON 损坏 / 结构不对都回落空集合，
+	//     坏文件不该让整个 Skill 看板打不开。
+	//   saveSkillSuites —— 整集合覆盖（UI 的「保存」一次提交右侧全部套件）。
+	//     payload 形状不合格一律**抛错**，绝不回落成空数组：那等于把用户攒的套件全删了。
+	//     脏数据（无名 / 空成员 / id 重复 / 超上限）由数据层拒绝且不写盘，错误原样冒到面板。
+	// 不加 Remote 装饰器：与 listSkills / expertAttach 同一形态——strict 声明即可达，
+	// 装饰器只是 SRC fallback 的 marker（方向说明见 test/contract-consistency.mjs 顶部）。
+	async listSkillSuites() {
+		return readSkillSuites();
+	}
+	async saveSkillSuites(payload) {
+		const suites = Array.isArray(payload)
+			? payload
+			: (payload && typeof payload === "object" && Array.isArray(payload.suites) ? payload.suites : null);
+		if (suites === null) throw new Error("缺少套件集合：payload.suites 必须是数组");
+		return writeSkillSuites(suites);
+	}
 	// ── WorkBuddy 市场直连（连接器 MCP + SkillHub 技能）─────────────────
 	// 数据与安装逻辑都在 lib/wb-market.js；这里只做 RPC 转发与作用域相关的写盘收尾。
 	// 连接器安装复用 applyManagedImport / applyWorkspaceImport：准入、同名跳过、entry id
@@ -1840,6 +1881,9 @@ let McpManagerGateway = (() => {
 	async wbAwesomeDetail(payload) {
 		return wbAwesomeDetail(payload?.name);
 	}
+	async wbAwesomeReadme(payload) {
+		return wbAwesomeReadme(payload || {});
+	}
 	async wbAwesomeUpdateCheck() {
 		return wbAwesomeUpdateCheck();
 	}

package/lib/mcp-oauth.js

@@ -29,7 +29,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 
 /** 插件版本：DCR 的 clientInfo 与 UA 共用一处，避免两边各自漂移。 */
-const PLUGIN_VERSION = "2.0.0";
+const PLUGIN_VERSION = "2.2.0";
 const USER_AGENT = `dsh-armory/${PLUGIN_VERSION} (+mcp-oauth)`;
 const NET_TIMEOUT_MS = 15_000;
 /** 授权流程整体存活时间：超过就判过期，避免会话表无限增长。 */

package/lib/skill-remove.js

@@ -0,0 +1,125 @@
+// 已安装 skill 的卸载数据层（Skill 看板「卸载」的唯一落盘点）。
+//
+// 为什么不让客户端传路径直接删：path 来自 listSkills 的回包，但 RPC 入参是浏览器可写的。
+// 这里只认「宿主注册表给这条 skill 的真实 source + path」，并且把删除范围钉死在四类
+// skills 根目录里——用户级 ~/.agents/skills、~/.dsh/skills，项目级 <cwd>/.agents/skills、
+// <cwd>/.dsh/skills。随 DSH 分发（bundled）、运行时注册（runtime）、自定义目录（custom）
+// 一律拒绝：前两者不该由用户面板删，后者没有可信的根目录可用来做包含性校验。
+//
+// 安全闸门（按顺序，任一不过即抛错，绝不"尽力而为"地删）：
+//   1. source 在白名单内，且能推导出绝对根目录（项目级必须有 cwd）；
+//   2. path 是绝对路径，且 resolve 后严格位于根目录内（≠ 根自身，`..` 穿越不过）；
+//      宿主注册表返回的 path 通常指向 `<skill>/SKILL.md`，先归一化到其父目录再校验，
+//      否则会把 SKILL.md 当成「不是目录」误拒（GUI 验证抓到的真实形态）；
+//   3. 父目录的 realpath 必须仍在根目录 realpath 内（防祖先符号链接把写入面带到别处）；
+//   4. 目标是符号链接 → 只 unlink 链接本身，**绝不**触碰链接指向的目录；
+//   5. 目标是目录 → 其 realpath 仍在根内，且目录里确实有 SKILL.md（文件），才递归删除。
+//
+// 删除是**永久删除**（不进回收站）：UI 侧有二次确认，并明示不可撤销。这与用户对删除的
+// 偏好一致；不做「移到 .trash」这类软删除——那会让看板显示已卸载、磁盘却仍在。
+//
+// 纯数据层：零网络、零宿主依赖；home / cwd 可注入，测试用 mkdtemp 隔离。
+import { lstat, realpath, rm, stat, unlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+
+/** 可卸载来源：值与宿主注册表的 skill.source 一致，客户端 SKILL_REMOVABLE_SOURCES 必须同步。 */
+export const REMOVABLE_SKILL_SOURCES = ["user-agents", "user-dsh", "project-agents", "project-dsh"];
+
+/**
+ * 来源 → skills 根目录。project-* 需要 cwd；拿不到时返回 null（拒绝，而不是猜一个目录）。
+ * 只写「从哪来」，不校验存在性——存在性在删除流程里按目标路径判断。
+ */
+export function skillRootFor(source, options = {}) {
+	const home = options.home || homedir();
+	const cwd = options.cwd;
+	switch (source) {
+		case "user-agents": return join(home, ".agents", "skills");
+		case "user-dsh": return join(home, ".dsh", "skills");
+		case "project-agents": return cwd ? join(cwd, ".agents", "skills") : null;
+		case "project-dsh": return cwd ? join(cwd, ".dsh", "skills") : null;
+		default: return null;
+	}
+}
+
+/** 严格包含：child 在 parent 之内且不等于 parent。 */
+function isInside(parent, child) {
+	const rel = relative(parent, child);
+	return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+
+/** 包含或相等：符号链接项只做父目录校验，父目录可以就是根。 */
+function isInsideOrEqual(parent, child) {
+	const rel = relative(parent, child);
+	return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+function describeSource(source) {
+	return source ? `「${source}」` : "未知来源";
+}
+
+/**
+ * 从磁盘永久删除一条已发现的 skill。
+ *
+ * @param {{ name?: string, source?: string, path?: string }} skill 宿主注册表返回的条目（path 可为目录或目录内的 SKILL.md）
+ * @param {{ cwd?: string, home?: string }} [options]
+ * @returns {Promise<{ path: string, kind: "symlink" | "dir" }>}
+ */
+export async function removeSkillFromDisk(skill, options = {}) {
+	const source = typeof skill?.source === "string" ? skill.source : "";
+	const root = skillRootFor(source, options);
+	if (!root) {
+		if (source === "project-agents" || source === "project-dsh") {
+			throw new Error(`卸载项目级 skill 需要当前项目路径（来源：${describeSource(source)}）`);
+		}
+		throw new Error(`这个 skill 来自${describeSource(source)}，不在可卸载范围内（只支持用户级/项目级的 .dsh/skills 与 .agents/skills）`);
+	}
+	if (!isAbsolute(root)) throw new Error("拒绝卸载：无法确定 skills 根目录的绝对路径");
+	const raw = typeof skill?.path === "string" ? skill.path.trim() : "";
+	if (!raw) throw new Error("这个 skill 没有可卸载的磁盘路径（运行时注册的 skill 不落盘）");
+	if (!isAbsolute(raw)) throw new Error("拒绝卸载：skill 路径不是绝对路径");
+
+	const rawAbs = resolve(raw);
+	// 注册表把 skill.path 指向清单文件（<skill>/SKILL.md），删除目标是它所在的目录。
+	// 若直接拿清单路径去删，只会得到「该路径不是目录」——真实 GUI 首跑就撞上了。
+	const target = basename(rawAbs).toLowerCase() === "skill.md" ? dirname(rawAbs) : rawAbs;
+	const rootAbs = resolve(root);
+	if (!isInside(rootAbs, target)) {
+		throw new Error(`拒绝卸载：skill 路径不在预期的 skills 根目录内（${rootAbs}）`);
+	}
+
+	let info;
+	try {
+		info = await lstat(target);
+	} catch (error) {
+		if (error?.code === "ENOENT") throw new Error("这个 skill 已经不在磁盘上了（可能刚被移动或删除）");
+		throw error;
+	}
+
+	// 父目录的 realpath 校验：防「根内路径 → 祖先符号链接实际指向根外」。根目录本身是
+	// 符号链接（例如 ~/.agents → 别处）是允许的，所以比的是 realpath 后的根。
+	const rootReal = await realpath(rootAbs);
+	const parentReal = await realpath(dirname(target));
+	if (!isInsideOrEqual(rootReal, parentReal)) {
+		throw new Error("拒绝卸载：skill 路径经符号链接指向了 skills 根目录之外");
+	}
+
+	if (info.isSymbolicLink()) {
+		// 只删链接本身。链接可能指向任意位置（例如 tabbit 这种外部安装的 skill），
+		// rm/lstat 都不会跟随，但我们仍显式只用 unlink，语义一目了然。
+		await unlink(target);
+		return { path: target, kind: "symlink" };
+	}
+	if (!info.isDirectory()) throw new Error("拒绝卸载：该路径不是目录（也不是符号链接）");
+
+	const targetReal = await realpath(target);
+	if (!isInside(rootReal, targetReal)) {
+		throw new Error("拒绝卸载：skill 目录经符号链接指向了 skills 根目录之外");
+	}
+	const manifest = await stat(join(target, "SKILL.md")).catch(() => null);
+	if (!manifest || !manifest.isFile()) {
+		throw new Error("拒绝卸载：目录里没有 SKILL.md，看起来不是 skill 目录");
+	}
+	await rm(target, { recursive: true, force: false });
+	return { path: target, kind: "dir" };
+}

package/lib/suites-registry.js

@@ -0,0 +1,179 @@
+// 自定义套件（Skill 看板）—— ~/.dsh/armory/suites.json 的读写层。
+//
+// 职责：把「一组相关 skill 的命名组合」持久化，供两处消费——
+//   1. Skill 看板工具栏的「自定义套件」按钮 → 套件管理弹窗（增删改）；
+//   2. 输入框召唤菜单的技能子菜单 → 选中一个套件即把成员的 `/name` 逐个插进草稿，
+//      一次引用等于同时应用多个相关 skill（纯插件侧展开，宿主零改动）。
+//
+// 契约（与 UI 的分工，勿两头各写一套）：
+//   - id 由**本层**分配：UI 新建的套件传 id: ''，保存后必须以返回值里的 id 为准，
+//     不得拿旧副本再存一次（否则同一套件会分裂成两条）。
+//   - members 是**有序**数组（拖拽排序即数组序），展开时按序拼 `/name`。
+//   - 保存语义是**整集合覆盖**（UI 的「保存」一次提交右侧全部套件），不是增量 upsert；
+//     原子性靠 staging + rename，所以不存在「写一半」的中间态。
+//
+// 失败模式分档（对齐 execution-safety「失败模式处置分档」）：
+//   - 拒绝（抛错）：入参不是数组 / 条目不是对象 / 名称为空 / 成员为空 /
+//     非空 id 重复 / 套件总数超上限。这些都是「写进去就是脏数据」的形态。
+//   - 放行 + 截断：name / desc 超长、members 超上限、members 里的非字符串项——
+//     截断与丢弃都发生在 normalize 里，返回值就是落盘值，UI 以返回值为准。
+//   - 读取永不抛错：文件缺失 / JSON 损坏 / 结构不对 → 空集合（与 wb-registry、
+//     wb-install-state 同一口径），坏文件不炸面板。
+//
+// 纯数据层：零网络、零宿主依赖。存储根目录可注入（options.rootDir / 环境变量
+// DSH_ARMORY_HOME），测试用 mkdtemp 隔离，绝不碰真实 ~/.dsh。
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const SUITES_VERSION = 1;
+
+/** 套件名上限：召唤菜单一行 28px，名字过长会挤掉成员计数徽章。 */
+export const SUITE_NAME_MAX = 40;
+/** 说明上限：只用于弹窗与菜单 title 悬停，不做正文展示。 */
+export const SUITE_DESC_MAX = 120;
+/** 单套件成员上限：展开后是一整串 `/name`，再多草稿框也读不下去。 */
+export const SUITE_MEMBERS_MAX = 40;
+/** 套件总数上限：文件体积与菜单长度的双重保险丝。 */
+export const SUITES_MAX = 100;
+
+/** 存储根目录：显式 rootDir > 环境变量 > 真实 ~/.dsh/armory（与 wb-registry 同一解析序）。 */
+function armoryRoot(options = {}) {
+  return options.rootDir || process.env.DSH_ARMORY_HOME || join(homedir(), ".dsh", "armory");
+}
+
+/** 套件文件绝对路径（入参只能选根目录，文件名不可外部指定——避免路径穿越面）。 */
+export function suitesPath(options = {}) {
+  return join(armoryRoot(options), "suites.json");
+}
+
+function asString(value, fallback = "") {
+  return typeof value === "string" ? value : fallback;
+}
+
+function asTimestamp(value, fallback = 0) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+
+/** 截断到上限（超长属「放行 + 截断」档，不抛错）。 */
+function clampText(value, max) {
+  const text = asString(value).trim();
+  return text.length > max ? text.slice(0, max) : text;
+}
+
+/** 成员数组归一：只留非空字符串、按首次出现去重、截到上限（顺序即展开序）。 */
+function normalizeMembers(raw) {
+  if (!Array.isArray(raw)) return [];
+  const seen = new Set();
+  const members = [];
+  for (const item of raw) {
+    const name = typeof item === "string" ? item.trim() : "";
+    if (!name || seen.has(name)) continue;
+    seen.add(name);
+    members.push(name);
+    if (members.length >= SUITE_MEMBERS_MAX) break;
+  }
+  return members;
+}
+
+/**
+ * 把任意原始对象规范成一条完整的 Suite：缺失字段防御性补全，畸形成员丢弃。
+ * id 为空表示「新建」，由 saveSuites 分配；normalizeSuite 本身不造 id（保持纯函数）。
+ */
+export function normalizeSuite(raw) {
+  return {
+    id: asString(raw?.id).trim(),
+    name: clampText(raw?.name, SUITE_NAME_MAX),
+    desc: clampText(raw?.desc, SUITE_DESC_MAX),
+    members: normalizeMembers(raw?.members),
+    createdAt: asTimestamp(raw?.createdAt, 0),
+    updatedAt: asTimestamp(raw?.updatedAt, 0),
+  };
+}
+
+/** 默认 id 生成器：时间戳 36 进制 + 随机尾，够避免同毫秒连点撞车。 */
+function defaultCreateId() {
+  return `suite-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+/** 从磁盘读原始文档；不存在/损坏一律返回 null（由调用方决定回落语义）。 */
+async function readRawDoc(path) {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    return null; // ENOENT / ENOTDIR / JSON 解析失败同途处理
+  }
+}
+
+/** 拆出目录部分（路径既有 / 也有 \ 的 Windows 形态，不为 dirname 多引依赖）。 */
+function dirnameOf(path) {
+  const cut = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+  return cut > 0 ? path.slice(0, cut) : path;
+}
+
+/** staging + rename 原子写（与 wb-registry.writeAtomic 同一模式；Windows rename 不覆盖）。 */
+async function writeAtomic(path, doc) {
+  await mkdir(dirnameOf(path), { recursive: true });
+  await writeFile(`${path}.staging`, JSON.stringify(doc, null, 2));
+  await rm(path, { force: true });
+  await rename(`${path}.staging`, path);
+}
+
+/** 读取时同样过一遍 normalize：手改坏的条目在读侧就被拉回合法形状。 */
+function normalizeList(raw) {
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .filter((item) => item && typeof item === "object" && !Array.isArray(item))
+    .map(normalizeSuite)
+    .filter((suite) => suite.id && suite.name && suite.members.length);
+}
+
+/**
+ * 读全部套件。文件缺失 / 损坏 / 结构不对 → { version, suites: [] }，永不抛错。
+ * 读侧过滤掉「无 id / 无名 / 无成员」的残缺条目：它们展开后什么也插不进草稿，
+ * 留在列表里只是噪声（写侧本来也拒绝这种形态，读侧过滤只兜手改坏的文件）。
+ */
+export async function readSuites(options = {}) {
+  const raw = await readRawDoc(suitesPath(options));
+  const version = raw && typeof raw.version === "number" ? raw.version : SUITES_VERSION;
+  return { version, suites: normalizeList(raw?.suites) };
+}
+
+/**
+ * 整集合覆盖保存（UI「保存」= 一次提交右侧全部套件）。
+ *
+ * 校验（拒绝档）：入参必须是数组；每条必须是对象；名称非空；成员非空；
+ * 非空 id 不得重复；总数不超 SUITES_MAX。任一不过 → 抛错且不写盘（原文件保持不变）。
+ * 补全：空 id 分配新 id（createId 可注入，测试用确定性实现）；缺 createdAt 补 now。
+ * updatedAt 由调用方决定（传了就落，没传落 now）——同 payload 重放得到同结果，写侧幂等。
+ *
+ * 返回写入后的 { version, suites }：UI 必须用它刷新本地副本（新 id 只在这里出现）。
+ */
+export async function saveSuites(suites, options = {}) {
+  if (!Array.isArray(suites)) throw new Error("套件集合必须是数组");
+  if (suites.length > SUITES_MAX) throw new Error(`套件数量超过上限 ${SUITES_MAX} 个`);
+  const createId = typeof options.createId === "function" ? options.createId : defaultCreateId;
+  const now = Date.now();
+  const seenIds = new Set();
+  const list = suites.map((raw, index) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+      throw new Error(`第 ${index + 1} 条套件不是对象`);
+    }
+    const suite = normalizeSuite(raw);
+    if (!suite.name) throw new Error(`第 ${index + 1} 条套件缺少名称`);
+    if (!suite.members.length) throw new Error(`套件「${suite.name}」没有成员`);
+    const id = suite.id || String(createId(index) || "").trim();
+    if (!id) throw new Error(`第 ${index + 1} 条套件无法分配 id`);
+    if (seenIds.has(id)) throw new Error(`套件 id 重复：${id}`);
+    seenIds.add(id);
+    return {
+      ...suite,
+      id,
+      createdAt: suite.createdAt || now,
+      updatedAt: suite.updatedAt || now,
+    };
+  });
+  const path = suitesPath(options);
+  await writeAtomic(path, { version: SUITES_VERSION, suites: list });
+  return { version: SUITES_VERSION, suites: list };
+}