dsh-plugin-tool-management 0.9.1 → 0.11.0

package/lib/mcp/state-section.js

@@ -9,18 +9,33 @@
 // 这类信息在任何工具 schema 里都拿不到：工具只暴露 `mcp__<server>__<tool>` 的名字与
 // 参数，永远不会说「A 挂了改用 B」。所以「列出 server」只是载体。
 //
-// 范围（2026-09-15 用户裁定）：
-//   - **只列「当前真正可用」的 server**：配置上已启用 **且** 有**未被停用**的工具
-//     （enabledToolCount > 0；场景档案收窄与手动逐工具开关都会写停用表，这里如实扣减）。
-//     没开的不进（用户明确要求）；工具全被停用的也不进（模型调不到，留着只会谎报数量）。
+// 范围（2026-09-15 用户裁定；2026-09-17 按实测修正"可用"的判据）：
+//   - 分两档，判据全部可验证：
+//       ① **可用**：配置上已启用 **且** 当前真实注册了未被停用的工具
+//          （`liveEnabledToolCount > 0`；场景档案收窄与手动逐工具开关都会写停用表，这里如实扣减）。
+//       ② **曾经连上、现在不可用**：已启用、当前一个工具都没注册，但「已知工具」缓存非空。
+//          这是**状态变化**，要报 —— 模型据此给"检查网络/命令/凭据"的建议，而不是把
+//          "配了但连不上"读成"本机没配"（后者会让它建议用户去装一个）。同时，用户写在那台
+//          server 上的备注（placeholder 就是「A 不可用时改用 B 兜底」）恰恰只在此时才有用，
+//          不列就永远送不到。
+//     不列的三类：**没开**（用户明确要求）、**工具全被停用**（模型调不到，留着只会谎报数量）、
+//     **从未连上过**（缓存也空 —— 一直没成功过，不该反复打扰；这条抄的是 Claude Code 的通知
+//     策略：一直没连上的不提示，昨天还好今天挂的才提示）。
 //   - 只列 **server 名 + 工具数 + 备注**；**具体工具名绝不注入** ——
 //     已启用 server 的工具本来就在模型自己的工具 schema 里（`mcp__<server>__<tool>`），
 //     段里再列一遍是重复；模型按前缀就能对上号。
 //   - 工具数只算**当前可用**的：被停用的那一部分不显示（它就是模型 schema 里没有的），
-//     数字必须与模型能调到的工具对得上。
+//     数字必须与模型能调到的工具对得上。②档没有当前数字，所以写的是「上次连上时 N 个工具」——
+//     那是历史事实，不是现状，措辞上必须区分开。
 //   - 无备注 → 只有名字 + 工具数（正是「不写就只知道名字」）。
-//   - 不写「已启用」字样：能进段的都是可用的，标状态是废话。
-//   - 无可用 server → 返回 `''`（renderPrompt 删空段，零 token 成本）。
+//   - 不写「已启用」字样：能进段的都是可用的，标状态是废话；②档则必须标，否则就是谎报。
+//   - 两档都空 → 返回 `''`（renderPrompt 删空段，零 token 成本）。
+//
+// 一条**测不出来**的边界（写在这里免得后来者以为它是 bug）：宿主没有暴露"MCP 已连接"这个信号
+// （插件清单只有 entryId / moduleName / enabled / fiberPhase），所以本模块只能读"工具有没有注册"。
+// 而官方 dsh-mcp-client 在**掉线后不会立刻摘掉工具**：`maxAttempts: 10`、退避 500ms 翻倍到 30s，
+// 约 2.5 分钟后才 `tools unregistered`；若把 `reconnect.enabled` 设为 false 则**永久保留**。
+// 也就是说那个窗口内本段仍会把它算作①档。这不是判据写错，是插件身份决定的观测上限。
 //
 // 同步性：`text()` 必须同步返回（renderPrompt 不接受 Promise），而 MCP 清单是异步读盘 →
 // 与子智能体目录同构的 stale-while-revalidate（见 src/subagents/catalog.ts）。
@@ -53,32 +68,60 @@ export function normalizeMcpNote(value, maxLength) {
 /**
  * 渲染 MCP 状态段（纯函数，便于单独推理）。
  *
+ * 分两档：**可用**（当前真注册了可用工具）与**曾经连上、现在不可用**（当前没注册，
+ * 但「已知工具」缓存证明它曾经成功过）。判据与不列的三类见文件头。
+ *
  * 返回 `''` 表示不注入 —— 没有可用 server 的用户零 token 成本。
  */
 export function renderMcpStateSection(rows, opts = {}) {
     const maxEntries = opts.maxEntries ?? DEFAULT_MCP_MAX_ENTRIES;
     const noteMaxLength = opts.noteMaxLength ?? DEFAULT_MCP_NOTE_MAX_LENGTH;
-    // 工具数取**可用数**（停用表扣减后的）；旧调用方只给 toolCount 时退回它，行为不变。
-    const countOf = (r) => (Number.isFinite(Number(r.enabledToolCount)) ? Number(r.enabledToolCount) : (Number(r.toolCount) || 0));
-    // 「当前真正可用」= 已启用 且 还有没被停用的工具。任一不满足都不进段。
-    const usable = rows.filter((r) => !r.disabled && countOf(r) > 0);
-    if (!usable.length)
+    // 当前真实可用的工具数（停用表扣减后）。**优先读 live 那个数** —— 旧调用方只给
+    // enabledToolCount / toolCount 时逐级退回，行为与拆分之前一致（那个数在"从未连上过"的
+    // server 上恰好也是 0，所以退回不会造成谎报，只会少报）。
+    const liveEnabledOf = (r) => {
+        if (Number.isFinite(Number(r.liveEnabledToolCount)))
+            return Number(r.liveEnabledToolCount);
+        return Number.isFinite(Number(r.enabledToolCount)) ? Number(r.enabledToolCount) : (Number(r.toolCount) || 0);
+    };
+    // 当前注册了**几个**工具（不扣停用）。用来把"什么都没注册"与"注册了但都被停用"分开：
+    // 后者是用户的选择（该不列），前者才是"连不上"（该列并标注）。
+    const liveOf = (r) => (Number.isFinite(Number(r.liveToolCount)) ? Number(r.liveToolCount) : liveEnabledOf(r));
+    // 曾经连上过的证据。缺省 0 = 从未连上过（旧调用方给不出这个信号，按"不列"处理 —— 少说不错）。
+    const knownOf = (r) => Number(r.knownToolCount) || 0;
+    const usable = rows.filter((r) => !r.disabled && liveEnabledOf(r) > 0);
+    const offline = rows.filter((r) => !r.disabled && liveOf(r) === 0 && knownOf(r) > 0);
+    if (!usable.length && !offline.length)
         return '';
     // 按展示名排序：即使补丁文件里的行序变化，段文本也保持逐字节稳定（前缀缓存契约）。
-    const sorted = [...usable].sort((a, b) => {
+    // 两档各自排序，可用的一律排在前面（它才是模型当下能用的东西）。
+    const byName = (a, b) => {
         const x = String(a.serverName ?? '');
         const y = String(b.serverName ?? '');
         return x < y ? -1 : x > y ? 1 : 0;
-    });
-    const shown = sorted.slice(0, Math.max(0, maxEntries));
-    const lines = shown.map((r) => {
-        const count = countOf(r);
-        const head = '- **' + String(r.serverName ?? r.id) + '**（' + count + ' 个工具）';
+    };
+    const cap = Math.max(0, maxEntries);
+    const shownUsable = [...usable].sort(byName).slice(0, cap);
+    const shownOffline = [...offline].sort(byName).slice(0, cap);
+    const lineOf = (r, count, isOffline) => {
+        const name = String(r.serverName ?? r.id);
+        // ②档必须把状态写出来：不写就等于谎报"可用"。「上次连上时」四个字不能省 ——
+        // 那个数字是历史事实，写成"（N 个工具）"会被读成现状。
+        const head = isOffline
+            ? '- **' + name + '**（当前未连上；上次连上时 ' + count + ' 个工具）'
+            : '- **' + name + '**（' + count + ' 个工具）';
         const note = normalizeMcpNote(r.notes, noteMaxLength);
         return note ? head + ' — ' + MCP_NOTE_PREFIX + note : head;
-    });
-    const out = ['## MCP 服务器', '', ...lines];
-    const hidden = sorted.length - shown.length;
+    };
+    const lines = [
+        ...shownUsable.map((r) => lineOf(r, liveEnabledOf(r), false)),
+        ...shownOffline.map((r) => lineOf(r, knownOf(r), true)),
+    ];
+    // 只有清单：标题（`## 本机 MCP 服务器的当前状态`）与"该拿它做什么"由注入通道的框架承担
+    // （2026-09-18 起，见 context-inject.ts 的 DOMAIN_FRAME）—— 同一件事只有一个出处，
+    // 框架已经写了标题，正文再写一遍就是每步多付一行 token。
+    const out = [...lines];
+    const hidden = (usable.length + offline.length) - (shownUsable.length + shownOffline.length);
     if (hidden > 0)
         out.push('', `（另有 ${hidden} 台未列出。）`);
     return out.join('\n');

package/lib/{rules → memories}/archive-engine.js

@@ -1,4 +1,4 @@
-// src/rules/archive-engine.ts —— 场景档案引擎：sidecar 读写 + 运行时应用，全部经 deps 注入（无直接 I/O）。
+// src/memories/archive-engine.ts —— 场景档案引擎：sidecar 读写 + 运行时应用，全部经 deps 注入（无直接 I/O）。
 // 状态机（设计 §2.2）：进入 = 快照 → 先落盘 mode（留可退路径）→ 应用已定义段 → 记忆收窄为 {S}；
 //                     退出 = 恢复快照 → 落盘自由模式；切换 = 先退后进。
 // 失败语义（fail-closed）：任一步失败即反向恢复运行时并写回旧切片；回滚不全会如实写进错误文本。
@@ -12,22 +12,70 @@ export function createArchiveEngine(deps) {
         chain = queued.catch(() => undefined);
         return queued;
     };
+    /**
+     * 快照里的上层两行 → 退出时**真正要回写**的那些：现状 ≠ 快照值、且这一行现在还存在。
+     *
+     * 为什么必须过滤而不是逐行无条件回写：
+     *   - 快照是全量记录（进场景前每一行的原值），场景没碰过的行占绝大多数，逐行回写会让
+     *     补丁文件 / 状态文件白写一遍（MCP 那一侧还会连带触发宿主热重载与备份噪音）；
+     *   - 现状已经等于原值的行本来就无需还原。真正要回写的只有「场景期间被改过的行」——
+     *     档案改的，或用户自己在场景页面上改的（未锁定时可用，改动同步进档案）。
+     *     后者正是用户报的「场景里关掉 A 目录，退出后 A 与它下面的技能都没开回来」：
+     *     旧口径只记「进场景时被档案改动过的行」，而 A 在进场景时没被改动（档案里勾着
+     *     A 下面的技能），快照里根本没有 A 这一行。
+     *
+     * 快照里记过、但现在已不存在的行直接跳过：这类行在场景期间被删掉了，没有可还原的状态，
+     * 硬写还会让退出失败（MCP 启停按 id 定位，`未找到条目` 直接报错）。
+     * 读不到现状（列表读取抛错）→ 退回旧行为全量回写：宁可多写几行，不可少还原。
+     */
+    async function mcpServerRowsToRestore(rows) {
+        if (!rows.length)
+            return [];
+        let current;
+        try {
+            current = await deps.mcpServerStates();
+        }
+        catch {
+            return rows;
+        }
+        const byKey = new Map(current.map((s) => [s.id + '\u0000' + s.level, s.disabled]));
+        return rows.filter((x) => {
+            const key = x.id + '\u0000' + x.level;
+            return byKey.has(key) && byKey.get(key) !== x.disabled;
+        });
+    }
+    /** 同 mcpServerRowsToRestore：来源级的还原行。 */
+    async function skillSourceRowsToRestore(rows) {
+        if (!rows.length)
+            return [];
+        let current;
+        try {
+            current = await deps.skillSourceStates();
+        }
+        catch {
+            return rows;
+        }
+        const byRoot = new Map(current.map((s) => [s.root, s.enabled]));
+        return rows.filter((x) => byRoot.has(x.root) && byRoot.get(x.root) !== x.enabled);
+    }
     /**
      * 还原到快照（退出模式与失败回滚共用同一条路径）：
      * MCP 停用表**按快照原文整体回写**——模式自己写进去的键（未勾服务器的 ['*']）必须随之消失，
      * 否则退出后用户环境仍被静默停用（比"多留一个键"严重得多）；模式期间的手动改动按设计 §2.2
      * 不保留（「退出 = 恢复 mode.snapshot」，手动改动只在「保存到场景」时回写）。
      * 技能只写快照列出的键（这是既有批量通道的语义）：模式期间新增的技能保持现状。
+     * 上层两行（服务器级 / 来源级）按**全量**快照还原 —— 只回写与现状不同的行，见
+     * mcpServerRowsToRestore / skillSourceRowsToRestore。
      */
     async function restoreSnapshot(snapshot) {
         // 顺序与进入时**相反**：先恢复服务器级 / 来源级，再恢复工具级 / 技能级 ——
         // 来源还关着的时候写技能级策略会被吞掉（`skills/core.js` 的 sourceEnabled 判定）。
         // 老 snapshot 没有这两栏 → `?? []`，按旧行为只恢复下层。
-        const servers = snapshot.mcpServers ?? [];
+        const servers = await mcpServerRowsToRestore(snapshot.mcpServers ?? []);
         if (servers.length) {
             await deps.applyMcpServerSwitches(servers.map((x) => ({ id: x.id, level: x.level, enabled: !x.disabled })));
         }
-        const sources = snapshot.skillSources ?? [];
+        const sources = await skillSourceRowsToRestore(snapshot.skillSources ?? []);
         if (sources.length) {
             await deps.applySkillSourceSwitches(sources.map((x) => ({ root: x.root, enabled: x.enabled })));
         }
@@ -291,17 +339,24 @@ export function createArchiveEngine(deps) {
             // 备注段是例外：未定义 = 不覆盖任何备注（没有东西"因为未定义而需要关掉"）。
             const mcpSpec = (archive && archive.mcp) || {};
             const skillsSpec = (archive && archive.skills) || [];
-            // 先算计划、再拍快照：快照只记**将被改动**的服务器行 / 来源 / 人设（带改动前的状态），
-            // 退出时按记录精确恢复 —— 不动用户手动设置的其他行。
+            // 先读现状、再算计划：现状既喂给计划（算「哪些行需要改」），也**全量**写进快照。
+            // 快照记的是**每一行**服务器 / 来源的进场景前状态，不是只记「本次计划要改的行」——
+            // 场景期间用户可以在页面上改开关（未锁定时可用，改动同步进档案），只记计划行的话
+            // 这些改动就没有原值可回：用户报的「场景里关掉 A 目录，退出后 A 和它下面的技能都没开回来」，
+            // 就是 A 在进场景时没被档案改动（档案里勾着 A 下面的技能）而未进快照。
             let mcpPlan = null;
             let skillsPlan = null;
+            let mcpServerStates = [];
+            let skillSources = [];
             try {
+                mcpServerStates = await deps.mcpServerStates();
+                skillSources = await deps.skillSourceStates();
                 mcpPlan = computeMcpPlan(mcpSpec, {
                     configuredServers: await deps.configuredServers(),
                     knownTools: await deps.serverKnownTools(),
-                    serverStates: await deps.mcpServerStates(),
+                    serverStates: mcpServerStates,
                 });
-                skillsPlan = computeSkillsPlan(skillsSpec, await deps.knownSkillKeys(), await deps.skillSourceStates());
+                skillsPlan = computeSkillsPlan(skillsSpec, await deps.knownSkillKeys(), skillSources);
             }
             catch (e) {
                 return { ok: false, error: `读取运行时状态失败（未改动任何东西）：${msg(e)}` };
@@ -338,9 +393,9 @@ export function createArchiveEngine(deps) {
             }
             // 快照**恒拍**：三个域都按「与勾选集完全一致」应用（未定义 = 全关），所以任何场景
             // 进入都可能改动运行时（哪怕只是停掉几台服务器 / 几个技能），退出都得能精确还原。
-            const snapshot = snapshotRuntime(await deps.currentMcpRaw(), await deps.currentSkills(), 
-            // 直接用计划带出的 `*Before`（改动前的状态），不在这里反推 —— 反推容易搞反方向。
-            mcpPlan.serverSwitches.map((s) => ({ id: s.id, level: s.level, disabled: s.disabledBefore })), skillsPlan.sourceSwitches.map((s) => ({ root: s.root, enabled: s.enabledBefore })), personaRestore, personaRestoreOn, noteBefore, personaStates);
+            // 上层两行传**现状全量**（上面的 mcpServerStates / skillSources 就是进场景前的值），
+            // 不是计划里那几行 —— 退出按「现状 ≠ 记录值」回写（见 mcpServerRowsToRestore）。
+            const snapshot = snapshotRuntime(await deps.currentMcpRaw(), await deps.currentSkills(), mcpServerStates.map((s) => ({ id: s.id, level: s.level, disabled: s.disabled })), skillSources.map((s) => ({ root: s.root, enabled: s.enabled })), personaRestore, personaRestoreOn, noteBefore, personaStates);
             const entered = { ...slice, mode: { scene: target, snapshot }, active: [target] };
             try {
                 await deps.saveSlice({ ...slice, mode: entered.mode });

package/lib/{rules → memories}/archive.js

@@ -1,4 +1,4 @@
-// src/rules/archive.ts —— 场景档案数据模型与模式切换纯逻辑（无 I/O；I/O 由 archive-engine 注入）。
+// src/memories/archive.ts —— 场景档案数据模型与模式切换纯逻辑（无 I/O；I/O 由 archive-engine 注入）。
 // 勾选集语义（设计 §2.1）：段内存储「勾选的启用集合」；应用时该域置为与勾选集完全一致；
 // 段未定义 = 该域不碰；段已定义但全不勾 = 合法（全部停用）。清单只对"实时发现"的条目生效。
 // v2：MCP 段为两级——服务器勾选（mcp 键存在）+ 可选工具明细（'*' = 整台，string[] = 指定工具）。
@@ -160,8 +160,9 @@ export function computeSkillsPlan(skills, knownSkillKeys, sourceStates) {
 /**
  * 把「这次要改的上层行」并进快照 —— **已记录的行保持原值**（先记的才是进场景前的状态）。
  *
- * 为什么需要：进入模式时快照只记了**当时将要改动**的行；模式进行中用户改档案（改档案 = 立即生效）
- * 又可能新改到别的服务器 / 来源级行。退出必须回到「进场景前」，所以这些新改的行也得有记录。
+ * 为什么需要：新快照已是**全量**（进入时就记了每一行），这里是兜底 —— 旧快照只记了
+ * 当时将要改动的行，而模式进行中用户改档案（改档案 = 立即生效）又可能新改到别的行；
+ * 退出必须回到「进场景前」，所以这些新改的行也得有记录。
  * 反之，若某行在进入时就记过，它的 `*Before` 才是进场景前的值 —— 这次的中间态值必须丢弃。
  */
 export function mergeSnapshotSwitches(snapshot, mcpServers = [], skillSources = []) {
@@ -189,10 +190,8 @@ export function mergeSnapshotSwitches(snapshot, mcpServers = [], skillSources =
     };
 }
 export function snapshotRuntime(mcpRaw, skills, 
-/** **将被档案改动**的服务器行，带改动前的 `disabled`。 */
-mcpServers = [], 
-/** **将被档案改动**的来源，带改动前的 `enabled`。 */
-skillSources = [], 
+/** 上层两行：进场景前**每一行**的原值（全量；退出按「现状 ≠ 原值」回写）。 */
+mcpServers = [], skillSources = [], 
 /** **将被档案启用**的人设名（改动前停用的子集；退出时按此停回）。 */
 subagents = [], 
 /** **将被档案停用**的人设名（改动前启用的子集；退出时按此重新打开）。 */

package/lib/memories/constants.js

@@ -0,0 +1,128 @@
+// 规则/记忆域的模块级常量与无依赖小工具（2026-09-19 从 memories/service.ts 抽出）。
+//
+// 为什么单独一个文件：service.ts 里这些常量夹在类型与函数之间，而投影函数（projection.ts）、
+// 索引 IO（index-io.ts）、发现与快照（snapshot.ts）与 service 本体都要用同一份 `global` /
+// 预算上限 / 引导语 / 路径段校验。留在 service.ts 会让它们反过来 import service.ts —— 那是
+// 运行时循环依赖。抽到这个无依赖的一层，几边都 import 它即可。
+//
+// 这里只放**不依赖本域状态**的东西：常量、纯字符串函数、字节计算。
+// ── 预算与默认 ─────────────────────────────────────────────────────────────
+import { isValidSegment } from '../paths.js';
+export const MAX_SOURCE_DEPTH = 64; // 与 core.js 一致
+export const MAX_DIRECTORIES = 2000; // 目录预算
+export const MAX_ENTRIES = 20000; // 条目预算
+export const MAX_GROUP_SEGMENT_LENGTH = 64; // 场景/子目录段名长度上限
+export const MAX_DESCRIPTION_LENGTH = 500; // 派生/显式描述上限（派生超长截断，显式超长拒绝）
+export const MAX_RULE_BYTES = 1 << 18; // 正文上限 256 KiB
+export const DEFAULT_ORDER = 1000; // 默认投影 order（索引无记录时）
+export const DEFAULT_GROUP_ORDER = 1000; // 新场景默认 order
+export const SNAPSHOT_TTL_MS = 1000; // 读路径短 TTL 缓存，吸收 UI 密集轮询
+export const DEFAULT_MAX_BYTES = 65536; // 场景记忆段预算上限（字节）
+// ── 保留场景名 ─────────────────────────────────────────────────────────────
+/** 保留场景名：界面显示「全局」，恒定存在、不可删除，其记忆注入任何对话。 */
+export const GLOBAL_SCENE = 'global';
+/** 保留场景在界面上的显示名（磁盘上仍用 ASCII 目录/文件名）。 */
+export const GLOBAL_SCENE_LABEL = '全局';
+export const SHARED_GROUP = '_shared'; // 保留场景名：公共基线（历史语义，仍可使用）
+// ── 段渲染 ─────────────────────────────────────────────────────────────────
+export const TRUNCATION_MARKER = '<!-- truncated -->';
+// 段尾清单：让模型知道自己漏了什么。去掉伞标题后这里也不再挂「场景记忆」前缀 ——
+// 它紧跟在场景块之后，`参考信息` 与段首引导语同一说法。
+export const DROPPED_HEADING = '## 未注入的参考信息（超出预算）';
+/** 单行正文的最大长度：超过就退回「标题 + 正文块」，避免出现一条几千字符的列表行。 */
+export const INLINE_BODY_MAX = 120;
+/** 附件行里最多列几个文件名；多的只报总数（路径已经给了，缺的名字模型自己列目录即可）。 */
+export const ATTACHMENT_LIST_MAX = 10;
+/**
+ * 段首的引导语：让模型知道下面是**用户为本机写的参考信息**，并且**以它为准**
+ * —— 涉及本机的事一律照它办，确实无关时才放下。
+ *
+ * 写法（2026-09-16 用户裁定，基于真实注入结果的三次修正）：
+ *   - **单行、加粗**，不再用括号分两行 —— 括号跨行在真实提示词里读起来像被截断，
+ *     而加粗是 Markdown 里最省字符的强调手段（用户要求「加强模型对此的重视程度」）。
+ *   - **提到段首、整段只出现一次**：原来它挂在每个场景的段头里，多场景时会重复注入。
+ *   - **不点名任何工具**：模型从工具 schema 就知道 `memory_manager_list` 存在，点名反而
+ *     像在提示它去调；用户裁定「没启用的信息就是不想在当前用」，所以工具指引整句删除。
+ *     真正防探测的是**完整性声明**（「以下就是全部信息」），那半句必须留。
+ *   - **完整性声明按截断状态自适应**：真有条目因预算没注入时，段尾会有未注入清单，
+ *     此时不能再声称「全部」，否则和清单自相矛盾 —— 也正因为那时确实有东西没给到，
+ *     模型去查工具是**合理**的，不该再拦。
+ *
+ * 用词：不用「常驻」「注入」这类内部行话（模型没有先验）；用户裁定用「信息」而不是
+ * 「记忆」——「记忆」在系统提示词里指代不明，而这段的实质就是用户写的参考信息。
+ *
+ * 2026-09-17 重写（用户：「当前模式会不重视这些提示词」）。上一版的三个毛病都在**授权**
+ * 上，而不在措辞好不好看上：
+ *   1. 「与当前任务相关时直接采用」——**没有给"相关"的判据**。最省力的解读永远是"无关"，
+ *      因为判成无关不需要任何工作；
+ *   2. 通篇没有优先级规则。与本机实际情况冲突时，模型会默默按自己的默认假设走，
+ *      而用户完全不知道发生了什么；
+ *   3. 「无关时忽略」——「忽略」是这句话里**最后一个动词**，也是记得最牢的那个。它把
+ *      一个免打扰出口写成了对内容的态度许可。
+ * 现在：给出**判据**（凡涉及本机路径 / 配置 / 工具 / 习惯）、给出**裁决规则**、把出口降级为
+ * 「不必提及」（关于**要不要声明**，不是关于**要不要采用**）。出口保留是必要的 —— 去掉它
+ * 会让模型对无关条目强行攀附，那是另一种失真。
+ *
+ * 2026-09-17 第二版：**按条目类型分级授权**（用户采纳的四条里的第 1、4 条）。Claude Code
+ * 把两类内容分进两个系统、用**相反**的授权：用户指令（`claudemd.ts:89`）是
+ * "These instructions OVERRIDE any default behavior and you MUST follow them exactly as
+ * written"，而记忆（`memdir/memoryTypes.ts:202`）是
+ * "If a recalled memory conflicts with current information, trust what you observe now"
+ * —— 书里（ch11:25）说记忆是 "working notes, not gospel"。上一版把两类塞进一句授权，
+ * 对**场景说明**（用户写的约定）是对的，对**记忆条目**（可能是几个月前记下的事实）是错的。
+ * 好在这两类在渲染时就分处不同位置：场景说明在 `sceneHeader` 的 `**场景说明：…**` 里，
+ * 记忆条目在 `memoryBlock` 里 —— 所以一句话就能分级，不必改数据结构。
+ *
+ * 冲突阶梯（第 4 条）来自 Codex `base_instructions/default.md:22-27` 与 Claude Code 的
+ * `caller override > agent definition > parent model > default`：把"谁高于谁"写明，
+ * 模型才不会在「用户当场说的 ≠ 本机记录」时悬空。写明它还有一个反直觉的好处 ——
+ * 它让授权更可信：这说明本条不是要让记忆压过用户，只是要压过模型的默认假设。
+ */
+export const SCENE_MEMORY_NOTE = '**用户为本机写的参考信息：「场景说明」是用户的约定，一律照办，覆盖你的默认做法；其余条目是记录，可能已过期 —— 与当前实际情况冲突时以你看到的为准，与用户当场说的冲突时以用户为准。无关时不必提及。以下就是全部信息。**';
+/** 有未注入条目时的版本：去掉完整性声明（见上）。 */
+export const SCENE_MEMORY_NOTE_PARTIAL = '**用户为本机写的参考信息：「场景说明」是用户的约定，一律照办，覆盖你的默认做法；其余条目是记录，可能已过期 —— 与当前实际情况冲突时以你看到的为准，与用户当场说的冲突时以用户为准。无关时不必提及。**';
+// ── bundle 与索引 ──────────────────────────────────────────────────────────
+// bundle 附件限制（body 走 HTTP JSON + base64，故比技能上传收紧一档）。
+export const MAX_ATTACH_ENTRY_BYTES = 8 << 20; // 单个附件 8 MiB
+export const MAX_ATTACH_TOTAL_BYTES = 16 << 20; // 单次总大小 16 MiB
+export const MAX_ATTACH_ENTRIES = 32; // 单次最多 32 个
+export const LEGACY_BUNDLE_DOC = 'SKILL.md'; // 旧版 bundle 的正文文件名；仅在发现/附件排除时作只读兼容，新建一律用 bundleDocName()
+/** bundle 的正文文件名 = `<记忆名>.md`（与目录名一致，不再是固定的 SKILL.md）。 */
+export const bundleDocName = (name) => `${name}.md`;
+export const INDEX_VERSION = 1;
+// ── 段名约束提示 ───────────────────────────────────────────────────────────
+// 场景/子目录段名约束（§4 对照表 + §5.3）：任意 Unicode，但必须对文件系统安全。
+// 谓词收敛到 `../paths.ts` —— 此前这里与 subagents / imports / skills 各写一套，
+// 口径不一（这里漏了 Windows 保留设备名与控制字符，而那两样恰好是创建即失败/路径被截断）。
+/**
+ * 段名非法时的统一说明。与 `paths.ts` 的谓词保持同步 —— 此前六处报错文案各写一份，
+ * 谓词收紧后它们会集体变成过时描述（用户按提示改了还是被拒）。
+ */
+export const SEGMENT_RULE_HINT = `非空、≤${MAX_GROUP_SEGMENT_LENGTH} 字符、不含路径分隔符与 < > : " | ? *、不以 . 开头、首尾无空白、不是 Windows 保留设备名（CON/NUL 等）、不含控制字符`;
+// ── 小工具 ─────────────────────────────────────────────────────────────────
+/** UTF-8 字节长度（预算按字节算，不能按 UTF-16 码元）。 */
+export const byteLen = (s) => Buffer.byteLength(s, 'utf8');
+// ── 与索引层共用的路径常量与无依赖小工具（2026-09-19 从 memories/service.ts 下沉）──
+// 放在这里而非 service.ts：index-io / snapshot 都要用，留在 service.ts 会让它们反向引值，
+// 形成运行时循环依赖。
+/** 单个路径段（场景名或子目录名）是否合法。放宽后 `办公` / `日常` 均通过。 */
+export function isValidGroupSegment(segment) {
+    return isValidSegment(segment, MAX_GROUP_SEGMENT_LENGTH);
+}
+/** group/场景路径可多层（a/b/c），每段必须合法；_shared 作为保留场景名放行。 */
+export function isValidGroupPath(group) {
+    if (typeof group !== 'string' || group === '' || group.startsWith('/') || group.endsWith('/'))
+        return false;
+    return group.split('/').every(isValidGroupSegment);
+}
+export const message = (e) => String((e && e.message) || e);
+/** 业务校验失败的统一返回形态（与 skills core 一致）。ops 分域后各域都要用，故放在这一层。 */
+export const fail = (code, error, params) => (params ? { ok: false, error, code, params } : { ok: false, error, code });
+/**
+ * 记忆索引文件名 / 记忆回收站目录名（hub 根下）。
+ * 域叫「记忆」（工具 `memory_manager_*`、界面「记忆」页），所以按域命名 ——
+ * 旧名 `rules-index.json` / `rules-trash/` 由 hub 的启动迁移搬过来（见 hub.ts）。
+ */
+export const MEMORIES_INDEX_FILE = 'memories-index.json';
+/** 记忆回收站目录名（hub 根下）。ops 分域后 trash 域要用，故与索引文件名一起放在这一层。 */
+export const MEMORIES_TRASH_DIR = 'memories-trash';