dsh-plugin-tool-management 0.9.1 → 0.11.0

package/lib/{history → sessions}/workspace.js

@@ -1,5 +1,5 @@
 import { lstat, mkdir, readFile, rm, writeFile } from "node:fs/promises";
-import { CapabilityRefusalError, createHistoryBridge, requiredSessionCapabilities } from "./bridge.js";
+import { CapabilityRefusalError, createSessionsBridge, requiredSessionCapabilities } from "./bridge.js";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { hubPath } from "../hub.js";
 import { sessionDir } from "@deepseek-ai/dsh-spill-local";
@@ -13,7 +13,7 @@ import { trackTombstone } from "./tombstone.js";
  * ——全量 grep `archivedSessionDetails` / `deleteArchivedSessions` / `unarchiveSessions`
  * 均不存在，`@michengai/dsh-archive-manager` 也未安装。因此下面所有
  * `typeof this.registry.X === "function"` 的委托分支在当前环境**都是死代码**，
- * 实际执行路径永远是 history/bridge.js 的私有适配（依赖官方声明为 private 的方法，
+ * 实际执行路径永远是 sessions/bridge.ts 的私有适配（依赖官方声明为 private 的方法，
  * 并直接改 registry.headers / sessionPaths / invalidSessionPaths）。
  * 所以「不再替换服务、不再与外部插件争注册」成立，但**不能由此推出耦合下降或零侵入**。
  * 另：改为门面后新增的墓碑 indexHeader 守卫只覆盖本门面的调用；宿主自身的
@@ -128,6 +128,7 @@ const deletedSchema = {
     },
 };
 const archivedBatchTargetSchema = {
+    // 校验通过后原样返回记录，调用方按 scope 判别式收窄（宿主返回值校验器，故返回 any）。
     parse(value) {
         if (typeof value !== "object" || value === null || Array.isArray(value))
             throw new TypeError("target must be an object");
@@ -229,7 +230,14 @@ function defaultWorkspaceSnapshotFile() {
 /**
  * 路径比较键：工作区的唯一性在宿主侧是 realpath 字符串相等（dsh-workspace
  * `realpathNormalize`），Windows 盘符大小写与分隔符拼写却可能不同，因此比较前
- * 先归一化。仅用于**分组与快照索引**，不参与任何写入或归属判定。
+ * 先归一化。
+ *
+ * ⚠ 它不是"只用于分组"：它决定**哪些会话被挂回哪条登记** —— `registerWorkspace` 会调
+ * `attachKnownSessions`，后者按这个键挑选会话并写宿主记账（`sessionIds`）；
+ * `ensureWorkspaceAccounting` 也拿它当去重键后 `host.create` + 挂回。
+ * 而且它比宿主更宽：宿主 `realpathNormalize` 只是 `fs.realpath`（**不做大小写归一**），
+ * 本函数在 Windows 上 `toLowerCase()` ⇒ `C:\Proj` 与 `c:\proj` 在插件里同组、在宿主里
+ * 可以是两条登记。挂回前应以宿主 `resolveByPath` 实际返回的 id 复核，而不是按归一字符串匹配。
  * @param {string} path - 原始路径。
  * @returns {string} 归一化后的比较键（空路径返回空串）。
  */
@@ -263,6 +271,16 @@ function workspaceBaseName(path) {
 // Standalone facade over the existing registry. Never instantiate/register a
 // second WorkspaceRegistry, and never open another copy of its storage domain.
 var ArchiveWorkspaceRegistry = class {
+    /** 宿主注入的上下文（服务读取按动态面处理，见 `HostContext`）。 */
+    ctx;
+    /** 宿主注册表实例；构造期由入参收窄，随后被 bridge 收窄后的实例覆盖。 */
+    registry;
+    /** sessions/bridge.ts 的适配句柄（能力门禁 + 私有接口包装）。 */
+    bridge;
+    /** 账本写入串行链（保证读-改-写不互相覆盖）。 */
+    ledgerTail;
+    /** 删除中的会话 id 集合（防 SUBAGENT 级联自环），首次用到才建。 */
+    deleting;
     /** 本进程内已物理删除的会话；阻止父类把 stale list() 重新编入索引。 */
     deletedSessionIds = /* @__PURE__ */ new Set();
     /** 墓碑插入顺序，用于在上限处淘汰最旧项。 */
@@ -272,8 +290,8 @@ var ArchiveWorkspaceRegistry = class {
     /** 被删生命周期的日志身份（createdAt/cwd）：冷复用探针区分“同 id 新会话”与 stale list() 的依据。 */
     deletedIdentities = /* @__PURE__ */ new Map();
     /** 会话 → 归档时刻（epoch ms）；保留期自动删除的基线。 */
-    archivedAtMap = /* @__PURE__ */ new Map();
-    archivedAtFile = null;
+    archivedAtMap = new Map();
+    archivedAtFile;
     archivedAtLoaded = false;
     /**
      * 「见过的登记」快照：归一化路径 → { path, title, id, at }。
@@ -282,8 +300,8 @@ var ArchiveWorkspaceRegistry = class {
      * 使按目录重建的分组仍能显示用户命名，并能区分「曾经登记过、现在被移除」
      * 与「从未登记过的目录」。只读辅助信息，不参与任何归属判定或写入。
      */
-    workspaceSnapshotMap = /* @__PURE__ */ new Map();
-    workspaceSnapshotFile = null;
+    workspaceSnapshotMap = new Map();
+    workspaceSnapshotFile;
     workspaceSnapshotLoaded = false;
     /** 快照上限：足够覆盖常见工作区数，又避免长驻进程无限增长。 */
     workspaceSnapshotLimit = 200;
@@ -293,7 +311,11 @@ var ArchiveWorkspaceRegistry = class {
      */
     ready = Promise.resolve();
     constructor(ctx, registry, config = {}) {
+        // 注入的 `sessionPersistence` 不在官方 `Context` 声明里（index.ts 的 inject 列表里有它），
+        // 因此这里按本文件的使用面收窄（其余成员仍走官方 `Context`）。
         this.ctx = ctx;
+        // 入参按「官方声明可见的公开面」声明（四个索引 Map 在官方 `WorkspaceRegistry` 里是 private，
+        // 运行时存在且由 bridge 的形状检查兜底），因此此处收窄为本文件实际使用的注册表面。
         this.registry = registry;
         this.archivedAtFile = config.archivedAtFile || defaultArchivedAtFile();
         this.workspaceSnapshotFile = config.workspaceSnapshotFile || defaultWorkspaceSnapshotFile();
@@ -301,7 +323,8 @@ var ArchiveWorkspaceRegistry = class {
             this.ready = Promise.resolve(config.ready).then(() => undefined, () => undefined);
         }
         this.ledgerTail = Promise.resolve();
-        this.bridge = createHistoryBridge(ctx, registry, (id, at) => this.recordArchive(id, at));
+        this.bridge = createSessionsBridge(ctx, registry, (id, at) => this.recordArchive(id, at));
+        // bridge 收窄后的注册表同样只声明运行时形状，这里还原为本文件的注册表面。
         this.registry = this.bridge.registry;
         this.bridge.observe();
     }
@@ -366,6 +389,7 @@ var ArchiveWorkspaceRegistry = class {
         this.archivedAtLoaded = true;
         try {
             const raw = await readFile(this.archivedAtFile, "utf8");
+            // 账本文件由本文件写出（id → epoch ms）；非有限值在下面逐个跳过。
             const obj = JSON.parse(raw);
             if (obj && typeof obj === "object") {
                 for (const [k, v] of Object.entries(obj)) {
@@ -514,6 +538,7 @@ var ArchiveWorkspaceRegistry = class {
                 cwd = header && typeof header.cwd === "string" && header.cwd ? header.cwd : undefined;
             }
             catch (error) {
+                // 宿主/文件系统抛出的错误按动态形状读 message（strict 下 catch 变量为 unknown）。
                 result.skipped.push({ sessionId, reason: `读不到会话头部：${String(error?.message ?? error)}` });
                 continue;
             }
@@ -541,6 +566,7 @@ var ArchiveWorkspaceRegistry = class {
                     result.registered.push(record);
                 }
                 catch (error) {
+                    // 宿主 realpath 拒绝的原始错误按动态形状读 message。
                     entry.failure = `无法解析工作区目录「${cwd}」：${String(error?.message ?? error)}`;
                 }
             }
@@ -560,6 +586,7 @@ var ArchiveWorkspaceRegistry = class {
                     result.attached.push(sessionId);
             }
             catch (error) {
+                // 宿主 attachSession 拒绝原因按动态形状读 message。
                 result.skipped.push({ sessionId, reason: String(error?.message ?? error) });
             }
         }
@@ -596,6 +623,7 @@ var ArchiveWorkspaceRegistry = class {
         const created = entity === undefined;
         if (created)
             entity = await host.create(target, typeof title === "string" && title.trim() ? title.trim() : undefined);
+        // 解析不到即走上面的 create 分支，此后 entity 必定已定义（类型层无法表达该不变式）。
         const record = {
             id: String(entity.id),
             path: String(entity.path ?? target),
@@ -633,6 +661,7 @@ var ArchiveWorkspaceRegistry = class {
                 attached.push(sessionId);
             }
             catch (error) {
+                // 宿主 attachSession 拒绝原因按动态形状读 message。
                 attachSkipped.push({ sessionId, reason: String(error?.message ?? error) });
             }
         }
@@ -917,12 +946,15 @@ var ArchiveWorkspaceRegistry = class {
         }
         return this.enqueueOperation(async () => {
             const requestedSessionIds = this.archivedSessionIdsForTarget(target);
+            // 批首取一次权威快照：批内每一条删除都要一次全库 `listStoredHeaders()`（含逐会话
+            // 读首行），这批复用同一份。取不到就退回逐条取 —— 快照失败不该废掉整批。
+            const storedIndex = await this.storedHeaderIndex().catch(() => undefined);
             const deletedSessionIds = [];
             const skippedSessionIds = [];
             const failures = [];
             for (const sessionId of requestedSessionIds) {
                 try {
-                    await this.deleteSessionCore(sessionId);
+                    await this.deleteSessionCore(sessionId, storedIndex);
                     deletedSessionIds.push(sessionId);
                 }
                 catch (error) {
@@ -963,6 +995,11 @@ var ArchiveWorkspaceRegistry = class {
             // 等待删除期间可能已进入的写回观察到墓碑并完成补删，再允许
             // 同 id 的未来新生命周期写入缓存。
             await projCache.whenIdle?.();
+            // 预留位：宿主**没有** `clearTombstone` 入口（全官方树 grep 零命中），
+            // 所以这里命中的是本插件 `bridge` guard 的墓碑（blocked.delete）——
+            // "已删会话会不会被误复活" 100% 取决于插件自己的两份内存墓碑
+            //（workspace 侧 FIFO-4096 + guard.blocked 无上限），插件重载即全清。
+            // 将来宿主补了 delete+whenIdle 时 bridge 会提前 return，这行才退化成对宿主对象的空转。
             projCache.clearTombstone?.(sessionId);
         }
         await this.cleanSpill(sessionId);
@@ -1017,8 +1054,9 @@ var ArchiveWorkspaceRegistry = class {
         }
         return this.enqueueOperation(() => this.deleteSessionCore(sessionId));
     }
-    /** 串行化后的删除主体（级联路径复用：它已持有操作链，绝不能再入队）。 */
-    async deleteSessionCore(sessionId) {
+    /** 串行化后的删除主体（级联路径复用：它已持有操作链，绝不能再入队）。
+     * @param storedIndex - 可选的批首 `id → header` 快照，见 {@link storedHeaderIndex}。 */
+    async deleteSessionCore(sessionId, storedIndex) {
         if (typeof this.registry.deleteSession === "function")
             return this.registry.deleteSession(sessionId);
         if (this.deleting?.has(sessionId))
@@ -1026,10 +1064,12 @@ var ArchiveWorkspaceRegistry = class {
         this.deleting ??= new Set();
         this.deleting.add(sessionId);
         try {
-            return await this.deleteLocalSession(sessionId);
+            return await this.deleteLocalSession(sessionId, storedIndex);
         }
         catch (error) {
             // Failed deletion must not permanently suppress a still-live session.
+            // （`clearTombstone` 是**预留位**：宿主无此入口，实际命中的是本插件 bridge guard
+            //  的墓碑 —— 说明见 `cleanupUnknownArchivedSession` 里那一处。）
             this.getProjectionCache()?.clearTombstone?.(sessionId);
             throw error;
         }
@@ -1037,8 +1077,8 @@ var ArchiveWorkspaceRegistry = class {
             this.deleting.delete(sessionId);
         }
     }
-    async deleteLocalSession(sessionId) {
-        if (!(await this.sessionKnown(sessionId)))
+    async deleteLocalSession(sessionId, storedIndex) {
+        if (!(await this.sessionKnown(sessionId, storedIndex)))
             throw new ArchiveUnknownSessionError(sessionId);
         const sessions = this.ctx.get("sessions");
         // 快速失败：删掉的顺序（flush → detach → 清缓存 → 删目录 → 清记账）里，
@@ -1061,8 +1101,13 @@ var ArchiveWorkspaceRegistry = class {
             // 持久化屏障先行：不能有未落盘的转录写入与目录删除竞争
             //（持久化后端按批关闭句柄，flush 过的会话不再持有打开的文件）。
             await sessions.flush(live);
-            // 从存储分离；`session/disposed` 同步触发，驱动浏览器端的
-            // `host/session-removed` 帧并启动投影缓存的最终写后落盘。
+            // 从存储分离；`session/disposed` 同步触发（payload 是 **Session 对象**），
+            // 由官方 `dsh-api-session-controller` 降级成 `api-session/removed`（payload 已降为
+            // **SessionId 字符串**）再转发到浏览器，并启动投影缓存的最终写后落盘。
+            // 名字别写成 `host/session-removed` —— 那个帧名在整个已安装树里不存在
+            //（`host/…` 是 cordis 服务/槽位名的前缀，不是线上帧命名空间）。
+            // 注意 `api-session/removed` 也是"发布回滚"与"作用域剪枝"发出的同一事件
+            //（官方 `dsh-session/lib/types/index.d.ts`），所以收到它**不能**等同于"用户删了会话"。
             const entry = sessions.liveEntryFor(live);
             sessions.detachEntered(entry);
         }
@@ -1074,7 +1119,7 @@ var ArchiveWorkspaceRegistry = class {
         await projCache?.whenIdle?.();
         if (projCache !== void 0)
             await projCache.delete(sessionId);
-        await this.deleteDescendants(sessionId);
+        await this.deleteDescendants(sessionId, storedIndex);
         await this.cleanSpill(sessionId);
         await this.removeTranscriptDirectory(sessionId);
         // 只有物理工件删除成功后才能提交记账清理；否则批量目标会因归档标记
@@ -1116,6 +1161,7 @@ var ArchiveWorkspaceRegistry = class {
             this.deletedSessionOrder.splice(idx, 1);
         // workspace 与 projection-cache 共同描述同一删除生命周期；新生命周期
         // 被接纳时必须同步撤销两处墓碑，否则缓存写入仍会永久被拦截。
+        // 右侧那处同样是**预留位**（宿主无 `clearTombstone`，命中的是 bridge guard 的墓碑）。
         this.getProjectionCache()?.clearTombstone?.(sessionId);
     }
     forgetIndexedSession(sessionId) {
@@ -1129,7 +1175,7 @@ var ArchiveWorkspaceRegistry = class {
      * 已删除会话对归档/删除入口都视为未知。实时复用同一 id 时撤墓碑，
      * 避免挡住新会话。
      */
-    async sessionKnown(id) {
+    async sessionKnown(id, storedIndex) {
         if (this.ctx.get("sessions")?.get(id) !== void 0) {
             this.clearTombstone(id);
             return true;
@@ -1137,7 +1183,10 @@ var ArchiveWorkspaceRegistry = class {
         if (this.deletedSessionIds.has(id))
             return this.coldReuseKnown(id);
         // Refresh from authoritative persistence, not the host's stale header cache.
-        const header = (await this.listStoredHeaders()).find((item) => item.id === id);
+        // 批量删除会传入**批首快照**（同一批里 k 次全库 list() 是纯浪费）；不传就是逐条取新鲜数据。
+        const header = storedIndex !== void 0
+            ? storedIndex.get(id)
+            : (await this.listStoredHeaders()).find((item) => item.id === id);
         if (!header)
             return false;
         await this.indexHeader(header);
@@ -1186,6 +1235,19 @@ var ArchiveWorkspaceRegistry = class {
     async listStoredHeaders() {
         return (await this.ctx.sessionPersistence.list()).map((item) => item.header ?? item);
     }
+    /**
+     * `id → header` 索引，供**一次批量操作内部**复用：`listStoredHeaders()` 每次都是
+     * 全库遍历 + 逐会话读首行，批量里逐条调用就是 O(k·n)。
+     *
+     * 只在批内有效 —— 它不随删除自动剔除，也不代表"此刻磁盘上的最新"；需要后者做判据的
+     * 地方（`coldReuseKnown` 的同 id 新生命周期比对）仍然自己取新鲜数据。
+     */
+    async storedHeaderIndex() {
+        const index = new Map();
+        for (const header of await this.listStoredHeaders())
+            index.set(header.id, header);
+        return index;
+    }
     async indexHeaders(items) {
         for (const item of items)
             await this.indexHeader(item.header ?? item);
@@ -1236,6 +1298,7 @@ var ArchiveWorkspaceRegistry = class {
                         stat = await lstat(path);
                     }
                     catch (error) {
+                        // Node 文件系统错误的 code 按动态形状读取（此处只关心 ENOENT）。
                         if (error?.code === "ENOENT")
                             continue; // Already removed on an earlier attempt.
                         throw error;
@@ -1277,6 +1340,7 @@ var ArchiveWorkspaceRegistry = class {
                 sessionIds: current.sessionIds.filter((id) => id !== sessionId),
                 updatedAt: /* @__PURE__ */ new Date().toISOString(),
             }));
+            // 实体快照的形状由宿主 `WorkspaceEntity` 决定（`record` 是私有字段，运行时存在）。
             const entity = this.entities.get(workspaceId);
             if (entity !== void 0)
                 entity.record = next;
@@ -1284,8 +1348,9 @@ var ArchiveWorkspaceRegistry = class {
     }
     /** 尽力而为的级联删除：删除 `sessionId` 的 SUBAGENT 子会话。
      * 仅头部标记 `origin: "subagent"` 的会话参与：单凭 `parentSession` 有歧义
-     *（fork 分支也携带它），而 fork 分支是独立的用户会话，绝不能被级联删除。 */
-    async deleteDescendants(sessionId) {
+     *（fork 分支也携带它），而 fork 分支是独立的用户会话，绝不能被级联删除。
+     * @param storedIndex - 可选的批首 `id → header` 快照，见 {@link storedHeaderIndex}。 */
+    async deleteDescendants(sessionId, storedIndex) {
         try {
             const descendants = [];
             const sessions = this.ctx.get("sessions");
@@ -1295,7 +1360,10 @@ var ArchiveWorkspaceRegistry = class {
                         session.header.origin === "subagent")
                         descendants.push(session.id);
                 }
-            for (const header of await this.listStoredHeaders()) {
+            const headers = storedIndex !== void 0
+                ? [...storedIndex.values()]
+                : await this.listStoredHeaders();
+            for (const header of headers) {
                 if (header.parentSession === sessionId &&
                     header.origin === "subagent" &&
                     !descendants.includes(header.id))
@@ -1303,9 +1371,9 @@ var ArchiveWorkspaceRegistry = class {
             }
             for (const childId of descendants) {
                 try {
-                    if (!(await this.sessionKnown(childId)))
+                    if (!(await this.sessionKnown(childId, storedIndex)))
                         continue;
-                    await this.deleteSessionCore(childId);
+                    await this.deleteSessionCore(childId, storedIndex);
                 }
                 catch (error) {
                     if (error instanceof ArchiveUnknownSessionError)

package/lib/skills/catalog.js

@@ -11,8 +11,9 @@
 //
 // 与官方目录的两处有意差别：
 //   - 只列**当前启用且可被模型调用**的（官方只过滤可调用性，不管用户在插件页关掉了谁）。
-//   - 结尾多一行：本预设没有官方 `skill` 加载工具（目录与工具是一起挂的），需要正文时得先
-//     `skill_manager_list` 取源文件路径再读那个文件 —— 不写这句，模型会以为有 `skill` 工具可调。
+//   - 「本预设没有官方 `skill` 加载工具，要正文先用 `skill_manager_list` 取源文件路径」那句
+//     2026-09-18 起挪进注入框架的 `how` 行（context-inject.ts 的 DOMAIN_FRAME.skills）——
+//     本段只排版清单，标题与"怎么用"一处一个出处。
 //
 // 同步性：`text()` 必须同步返回（注入通道每个 step 同步取文本），而技能清单是异步读盘 →
 // 与子智能体目录同构的 stale-while-revalidate：`text()` 返回缓存值并在超龄时后台重算，
@@ -72,13 +73,9 @@ export function renderSkillCatalog(data, maxEntries = SKILL_CATALOG_MAX_ENTRIES,
     const sorted = [...byName.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
     const shown = sorted.slice(0, Math.max(0, maxEntries));
     const lines = shown.map((row) => (row.description ? '- `' + row.name + '`: ' + row.description : '- `' + row.name + '`'));
-    const out = [
-        '## 技能',
-        '',
-        '**本预设没有官方 `skill` 加载工具；要技能正文时用 `skill_manager_list` 取源文件路径再读。**',
-        '',
-        ...lines,
-    ];
+    // 只有清单：标题、工具名与"只给摘要、读完再用"的纪律由注入通道的框架承担
+    // （2026-09-18 起，见 context-inject.ts 的 DOMAIN_FRAME 的 `how` 行）—— 一处内容一个出处。
+    const out = [...lines];
     const hidden = sorted.length - shown.length;
     if (hidden > 0)
         out.push('', `（另有 ${hidden} 个未列出，用 \`skill_manager_list\` 查。）`);