dsh-plugin-tool-management 0.9.1 → 0.11.0

package/lib/memories/index-io.js

@@ -0,0 +1,330 @@
+// 规则/记忆域的**索引 IO**（2026-09-19 从 memories/service.ts 抽出）。
+//
+// memories-index.json 的解析、校验、原子落盘与损坏隔离都在这里。索引是「启停/排序/标签/
+// 启用场景集合」的真源（记忆文件只负责正文），所以这一层必须 fail-closed：解析不出来就隔离
+// 坏文件并回退默认索引，绝不让半截数据流进界面。
+//
+// 对 service.ts 只做 type-only 引用（`import type`），避免与它形成运行时循环依赖。
+import { randomUUID } from 'node:crypto';
+import { readFileSync, renameSync, statSync } from 'node:fs';
+import { lstat, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { renameWithRetry } from '../skills/core.js';
+import { normalizePresetId } from '../prompts/preset-id.js';
+import { normalizeArchive } from './archive.js';
+import { DEFAULT_GROUP_ORDER, GLOBAL_SCENE, GLOBAL_SCENE_LABEL, INDEX_VERSION, isValidGroupPath, MEMORIES_INDEX_FILE } from './constants.js';
+import { normalizeActive } from './projection.js';
+/**
+ * 同目录临时文件 + rename 原子写（临时名 `.xxx.dsh-rules-<uuid>.tmp`）。
+ * rename 走 `renameWithRetry`：Windows 上杀软/索引器会短暂占住目标文件报
+ * EPERM/EACCES/EBUSY（用户实测：进入/退出模式时 memories-index.json 被 rename 撞上，
+ * 运行时已切换但状态落盘失败，界面开关停在旧状态、还得再点一次）。这种占用是
+ * 瞬时的，重试几轮就能过去；全失败才清理临时文件并把错误抛出。
+ */
+export async function writeFileAtomically(path, content) {
+    const temp = join(dirname(path), `.${basename(path)}.dsh-rules-${randomUUID()}.tmp`);
+    try {
+        await writeFile(temp, content, 'utf8');
+        await renameWithRetry(temp, path);
+    }
+    catch (error) {
+        await rm(temp, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+/** 二进制版原子写（附件用）：临时文件 + rename（同样带瞬时占用重试），失败清理临时文件。 */
+export async function writeFileAtomicBinary(path, data) {
+    const temp = join(dirname(path), `.${basename(path)}.dsh-rules-${randomUUID()}.tmp`);
+    try {
+        await writeFile(temp, data);
+        await renameWithRetry(temp, path);
+    }
+    catch (error) {
+        await rm(temp, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+// ── 递归发现 ───────────────────────────────────────────────────────────────
+export const defaultIndex = () => ({ version: INDEX_VERSION, rules: {}, groups: {}, scenes: {}, active: null, archives: {}, mode: { scene: null, snapshot: null } });
+/** 场景镜像条目归一化：只保留已知字段，非法值丢弃（容忍脏数据）。 */
+export function parseSceneEntry(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const obj = raw;
+    const out = {};
+    if (typeof obj.label === 'string' && obj.label.trim() !== '')
+        out.label = obj.label;
+    if (typeof obj.description === 'string' && obj.description !== '')
+        out.description = obj.description;
+    if (typeof obj.prompt === 'string') {
+        const prompt = normalizeScenePromptId(obj.prompt);
+        if (prompt)
+            out.prompt = prompt;
+    }
+    if (typeof obj.order === 'number' && Number.isFinite(obj.order))
+        out.order = obj.order;
+    if (typeof obj.createdAt === 'string' && obj.createdAt !== '')
+        out.createdAt = obj.createdAt;
+    // 场景锁定（v0.8）：读盘必须原样保留 —— 这里曾只重建已知字段，锁了也会被剥成未锁。
+    if (obj.locked === true)
+        out.locked = true;
+    return out;
+}
+export function parseScenes(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return {};
+    const out = {};
+    for (const [name, value] of Object.entries(raw)) {
+        if (!isValidGroupPath(name))
+            continue;
+        const entry = parseSceneEntry(value);
+        if (entry)
+            out[name] = entry;
+    }
+    return out;
+}
+/** 档案切片归一化：未知形态 → 空对象（容忍脏数据，与 §9.3 同哲学）。 */
+export function parseArchives(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return {};
+    const out = {};
+    for (const [name, value] of Object.entries(raw)) {
+        const archive = normalizeArchive(value);
+        if (Object.keys(archive).length)
+            out[name] = archive;
+    }
+    return out;
+}
+export function parseModeState(raw) {
+    const obj = (raw && typeof raw === 'object' ? raw : {});
+    const scene = typeof obj.scene === 'string' && obj.scene.trim() !== '' ? obj.scene : null;
+    const snapshotRaw = (obj.snapshot && typeof obj.snapshot === 'object' ? obj.snapshot : {});
+    const toFlagMap = (v) => {
+        const out = {};
+        if (v && typeof v === 'object' && !Array.isArray(v)) {
+            for (const [k, b] of Object.entries(v))
+                if (typeof b === 'boolean')
+                    out[k] = b;
+        }
+        return out;
+    };
+    // v2 快照：mcp = 停用表原文（serverName → ['*'] / 工具名）；skills = 启停布尔表。
+    const mcp = {};
+    const mcpRaw = snapshotRaw.mcp;
+    if (mcpRaw && typeof mcpRaw === 'object' && !Array.isArray(mcpRaw)) {
+        for (const [server, list] of Object.entries(mcpRaw)) {
+            if (Array.isArray(list))
+                mcp[server] = list.map((x) => String(x));
+        }
+    }
+    else if (snapshotRaw.tools && typeof snapshotRaw.tools === 'object' && !Array.isArray(snapshotRaw.tools)) {
+        // v1 快照兼容（升级前数据）：tools = 布尔启停表（key = `<server>/<tool>`，false = 停用）
+        // → 折算成 v2 的停用名单；否则退出模式会把「快照启停」错误还原成「全部启用」。
+        for (const [key, on] of Object.entries(snapshotRaw.tools)) {
+            if (on !== false)
+                continue;
+            const i = key.indexOf('/');
+            if (i <= 0 || i === key.length - 1)
+                continue;
+            const server = key.slice(0, i);
+            const tool = key.slice(i + 1);
+            const list = mcp[server] || (mcp[server] = []);
+            if (list.indexOf(tool) < 0)
+                list.push(tool);
+        }
+    }
+    // v2 快照的**服务器级 / 来源级**名单、v0.8 的子智能体名单、v0.9.1 的人设全量映射
+    // 必须原样透传 —— 这里曾把它们剥掉，结果退出模式时两张恢复名单全是空的：服务器级 MCP 与
+    // 技能来源永远不回滚（用户报的「MCP 不复原」「技能目录不回退」），只有工具级 / 技能级能还原。
+    const mcpServers = (Array.isArray(snapshotRaw.mcpServers) ? snapshotRaw.mcpServers : [])
+        .filter((x) => !!x && typeof x === 'object')
+        .map((x) => ({ id: String(x.id || ''), level: String(x.level || ''), disabled: x.disabled === true }))
+        .filter((x) => x.id !== '' && (x.level === 'global' || x.level === 'project'));
+    const skillSources = (Array.isArray(snapshotRaw.skillSources) ? snapshotRaw.skillSources : [])
+        .filter((x) => !!x && typeof x === 'object')
+        .map((x) => ({ root: String(x.root || ''), enabled: x.enabled === true }))
+        .filter((x) => x.root !== '');
+    const subagents = (Array.isArray(snapshotRaw.subagents) ? snapshotRaw.subagents : []).map((x) => String(x)).filter(Boolean);
+    // 同 subagents 一组：进入时被档案**关掉**的人设（退出要重新打开）。漏掉它 = 用户实测的
+    // 「进场景关掉了，退出却没开回来」——快照落盘后读回来就只剩「被启用」那一半名单。
+    const subagentsOn = (Array.isArray(snapshotRaw.subagentsOn) ? snapshotRaw.subagentsOn : []).map((x) => String(x)).filter(Boolean);
+    // v0.9.1 的人设**全量**开关映射（名字 → 进场景时是否开着）：同样必须原样透传 ——
+    // 剥掉它，退出模式就只能退回上面两个部分名单，「场景里手动开过的人设」不再被还原。
+    const subagentsAll = toFlagMap(snapshotRaw.subagentsAll);
+    // v0.8.1 的场景备注恢复名单：**必须原样透传**——这里漏掉它，退出模式时备注永不回退
+    //（与历史上 mcpServers / skillSources 被剥掉是同一类 bug）。
+    const mcpNotes = (Array.isArray(snapshotRaw.mcpNotes) ? snapshotRaw.mcpNotes : [])
+        .filter((x) => !!x && typeof x === 'object')
+        .map((x) => ({ id: String(x.id || ''), note: typeof x.note === 'string' ? x.note : null }))
+        .filter((x) => x.id !== '');
+    return {
+        scene,
+        snapshot: scene
+            ? {
+                mcp,
+                skills: toFlagMap(snapshotRaw.skills),
+                ...(mcpServers.length ? { mcpServers } : {}),
+                ...(skillSources.length ? { skillSources } : {}),
+                ...(subagents.length ? { subagents } : {}),
+                ...(subagentsOn.length ? { subagentsOn } : {}),
+                ...(Object.keys(subagentsAll).length ? { subagentsAll } : {}),
+                ...(mcpNotes.length ? { mcpNotes } : {}),
+            }
+            : null,
+    };
+}
+/** 解析 memories-index.json 原文；任何异常/版本不符 → 默认索引（容忍缺失，§9.3）。 */
+export function parseIndex(raw) {
+    const parsed = JSON.parse(raw);
+    if (!parsed || parsed.version !== INDEX_VERSION || typeof parsed.rules !== 'object' || parsed.rules === null)
+        throw new Error('bad index');
+    return {
+        version: INDEX_VERSION,
+        rules: (parsed.rules || {}),
+        groups: (parsed.groups || {}),
+        scenes: parseScenes(parsed.scenes),
+        active: normalizeActive(parsed.active),
+        archives: parseArchives(parsed.archives),
+        mode: parseModeState(parsed.mode),
+    };
+}
+// 索引损坏的进程级记录：stateDir → 损坏原文件被改名后的落点。
+//
+// 为什么需要它：原来 readIndex 的 catch 把「文件不存在」「读失败」「解析失败」三者合并成
+// 「返回默认索引」，而索引是启停/排序/标签/场景描述/归档/模式快照的**唯一**真相源 ——
+// 于是任意一次写操作都会把这份空索引落盘，一次解析失败就静默换掉用户全部配置，且没有
+// 任何提示；模式快照丢了之后，运行时 MCP/技能开关再也无法回滚。
+// 触发不限于文件损坏：parseIndex 对字段类型严格，跨版本降级读到新版结构同样会抛。
+//
+// 现在的口径分开处理两条路：
+//   - 读侧降级 —— 注入路径（readIndexSync）不能抛，返回默认索引，界面表现为「记忆都没了」，
+//     是可见症状而不是静默改写；
+//   - 写侧 fail-closed —— 拒绝落盘并把原因回给界面，用户的数据一个字节不动。
+export const corruptIndexes = new Map();
+/** 把损坏的索引改名留存并记录该 stateDir 已损坏（幂等，只记一次）。 */
+export function quarantineIndex(stateDir) {
+    const key = resolve(stateDir);
+    if (corruptIndexes.has(key))
+        return;
+    const abs = join(stateDir, MEMORIES_INDEX_FILE);
+    const kept = `${abs}.corrupt-${Date.now()}`;
+    try {
+        renameSync(abs, kept);
+        corruptIndexes.set(key, kept);
+    }
+    catch {
+        // 改名失败（被占用/权限）不改判定：仍然标记损坏并拒绝写，只是没有留存副本。
+        corruptIndexes.set(key, abs);
+    }
+    console.warn(`[dsh-plugin-tool-management] 记忆索引解析失败，已停止写入以免覆盖你的数据。`
+        + `损坏的原文件已留存为 ${kept} —— 请检查它（或删除后重启 DSH）再继续操作。`);
+}
+/** 该 stateDir 的索引是否已判定损坏（写侧拒绝落盘，读侧按「全部未启用」处理）。 */
+export function isIndexQuarantined(stateDir) {
+    return corruptIndexes.has(resolve(stateDir));
+}
+/** 解析索引；失败即隔离该文件并返回默认索引（写侧由 writeIndex 拦截）。 */
+export function parseOrQuarantine(stateDir, raw) {
+    try {
+        return parseIndex(raw);
+    }
+    catch {
+        quarantineIndex(stateDir);
+        return defaultIndex();
+    }
+}
+export async function readIndex(stateDir) {
+    let raw;
+    try {
+        raw = await readFile(join(stateDir, MEMORIES_INDEX_FILE), 'utf8');
+    }
+    catch {
+        // 文件不存在 = 全新用户；其余 IO 错误也按「没有索引」处理（与既有语义一致）。
+        return defaultIndex();
+    }
+    return parseOrQuarantine(stateDir, raw);
+}
+/**
+ * 同步读索引：注入文本的渲染路径不能 await（见文件内「两相扫描」注释）。
+ *
+ * 带 `mtimeMs:size` 指纹缓存：一次装配里这个函数会被调到 2 次以上，每个模型 step 都重读
+ * 重解一遍整份索引没有意义。指纹**必须**在 —— 索引可能被别的 DSH 实例或用户手工改动，
+ * 只按自身写入失效会让插件一直用旧值（表现为「记忆停不掉」）。stat 失败（文件被删 / 被
+ * 隔离改名）即丢缓存。同款手法见 `readPresetTextSync` 与 subagents 的 enabledStamp。
+ *
+ * ⚠️ 返回的可能是**缓存实例**，调用方只许读；写索引一律走异步 `readIndex`（它每次重新解析，
+ * 拿到新对象）。当前两个调用方（`sceneMemory` / `resolveScenePreset`）及其下游
+ * （`signatureOfIndex` / `resolveActiveScenes` / `sceneHeader` / `compareSceneBuckets` /
+ * `sceneOrderOf`）都已确认只读 —— 新增调用方请保持这条。
+ */
+export const indexSyncCache = new Map();
+export function readIndexSync(stateDir) {
+    const file = join(stateDir, MEMORIES_INDEX_FILE);
+    let key;
+    try {
+        const st = statSync(file);
+        key = `${st.mtimeMs}:${st.size}`;
+    }
+    catch {
+        // 文件不存在 = 全新用户；其余 IO 错误也按「没有索引」处理（与 readIndex 一致）。
+        indexSyncCache.delete(stateDir);
+        return defaultIndex();
+    }
+    const cached = indexSyncCache.get(stateDir);
+    if (cached && cached.key === key)
+        return cached.value;
+    const raw = readFileIfExistsSync(file);
+    const value = raw === null ? defaultIndex() : parseOrQuarantine(stateDir, raw);
+    indexSyncCache.set(stateDir, { key, value });
+    return value;
+}
+export async function writeIndex(stateDir, index) {
+    // 索引损坏时拒绝写入：这一次写会把空索引落盘，等于用一次解析失败换掉用户全部配置。
+    const kept = corruptIndexes.get(resolve(stateDir));
+    if (kept !== undefined) {
+        throw new Error(`记忆索引文件损坏，已拒绝写入以免覆盖你的数据（原文件留存为 ${kept}）。`
+            + `请检查或删除该损坏文件后重启 DSH，再重试本次操作。`);
+    }
+    await mkdir(stateDir, { recursive: true });
+    await writeFileAtomically(join(stateDir, MEMORIES_INDEX_FILE), JSON.stringify(index, null, 2));
+}
+// ── 场景记录（索引内，`memories-index.json` 的 scenes 切片）+ 旧布局迁移 ────────
+/** 索引条目 → 场景记录（供 UI 直接渲染）。 */
+export function sceneRecordOf(name, entry) {
+    const e = entry || {};
+    return {
+        name,
+        ...(name === GLOBAL_SCENE ? { label: e.label || GLOBAL_SCENE_LABEL } : (e.label ? { label: e.label } : {})),
+        ...(e.description ? { description: e.description } : {}),
+        ...(e.prompt ? { prompt: e.prompt } : {}),
+        order: e.order ?? (name === GLOBAL_SCENE ? 0 : DEFAULT_GROUP_ORDER),
+        ...(e.createdAt ? { createdAt: e.createdAt } : {}),
+    };
+}
+/** 提示词预设 id 的口径与提示词预设服务**同源**（用户裁定：id 什么都能写）。 */
+/** 校验场景要绑定的提示词预设 id；返回 `''` 表示解绑，`null` 表示非法。 */
+export function normalizeScenePromptId(value) {
+    const id = String(value ?? '').trim();
+    if (id === '')
+        return '';
+    const result = normalizePresetId(id);
+    return result.ok ? result.id : null;
+}
+/** 路径是否存在（不跟随符号链接；用于迁移前置判断）。 */
+export async function pathExists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function readFileIfExistsSync(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}

package/lib/memories/projection.js

@@ -0,0 +1,280 @@
+// 规则/记忆域的**投影与渲染**纯函数（2026-09-19 从 memories/service.ts 抽出）。
+//
+// 界定：这里只放「给定索引 + 已发现的条目，算出界面/注入看到的那份结果」的函数 ——
+// 不读索引文件、不改索引、不碰服务状态。快照构建（buildSnapshot）与 op 实现留在 service.ts。
+//
+// 为什么抽出来：service.ts 里这些函数夹在「索引读写」与「24 个 op」之间，而它们其实是
+// 另一件事——把磁盘事实翻译成模型与用户看到的文本。分开之后改渲染不必在 op 之间穿行。
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { ATTACHMENT_LIST_MAX, bundleDocName, DEFAULT_GROUP_ORDER, DEFAULT_ORDER, GLOBAL_SCENE, GLOBAL_SCENE_LABEL, INLINE_BODY_MAX, LEGACY_BUNDLE_DOC, SHARED_GROUP, } from './constants.js';
+// ── 索引归一化与场景解析 ───────────────────────────────────────────────────
+/** 启用场景集合归一化：非数组 → null（= 全部启用）；数组 → 去重后的字符串数组。 */
+export function normalizeActive(raw) {
+    if (!Array.isArray(raw))
+        return null;
+    const out = [];
+    const seen = new Set();
+    for (const item of raw) {
+        if (typeof item !== 'string')
+            continue;
+        const name = item.trim();
+        if (name === '' || seen.has(name))
+            continue;
+        seen.add(name);
+        out.push(name);
+    }
+    return out;
+}
+export function ensureSceneRecords(index, probeScenes) {
+    if (!index.scenes)
+        index.scenes = {};
+    let dirty = false;
+    if (!index.scenes[GLOBAL_SCENE]) {
+        index.scenes[GLOBAL_SCENE] = { label: GLOBAL_SCENE_LABEL, order: 0 };
+        dirty = true;
+    }
+    // 有目录但没记录（旧布局搬进来的、或用户手工建的目录）→ 补记录，label 用目录名。
+    for (const name of probeScenes) {
+        if (index.scenes[name])
+            continue;
+        index.scenes[name] = { order: DEFAULT_GROUP_ORDER };
+        dirty = true;
+    }
+    return dirty;
+}
+/**
+ * 活动场景解析（用户裁定 2026-09-15：**除「全局」外同时只能启用一个场景**）：
+ *   - `index.active` 为数组（新写入的唯一形态）→ 至多一个非保留场景启用；
+ *   - `index.active` 缺失 / null → 历史默认（"全部场景启用"）；**不再产生**新值，
+ *     新建场景时会被收敛成显式数组（见 `collapseActiveForNewScene`），
+ *     因此"新建即启用"不会发生；存量数据仍按老语义读，避免升级后注入范围突变。
+ *   - `_shared` 恒常启用（公共基线），不受开关影响
+ *   - 保留场景 `global` 恒常启用：它的记忆对任何对话都成立
+ * 缺失 memories-index.json 一律按默认值运行，不抛错（§9.3）。
+ * 场景生效与否只由 index.active 决定（场景档案/模式也写这一份）。
+ */
+export function resolveActiveScenes(index, knownScenes) {
+    const stored = normalizeActive(index.active);
+    const mode = stored === null ? 'all' : 'custom';
+    const active = new Set(stored === null ? knownScenes : stored);
+    active.add(SHARED_GROUP);
+    active.add(GLOBAL_SCENE);
+    return { active, mode };
+}
+/** 当前启用的**非保留**场景（单选模型下至多一个；多个时按场景顺序取第一个）。 */
+export function enabledSceneOf(index) {
+    const names = Object.keys(index.scenes || {});
+    const { active } = resolveActiveScenes(index, names);
+    const enabled = names
+        .filter((n) => n !== SHARED_GROUP && n !== GLOBAL_SCENE && active.has(n))
+        .sort((a, b) => sceneOrderOf(index, a) - sceneOrderOf(index, b) || a.localeCompare(b));
+    return enabled[0] ?? null;
+}
+/**
+ * 新建场景前把历史默认（`active = null` = 全部启用）收敛成显式数组，保证
+ * **新场景默认不启动**、且收敛后仍满足"至多一个非保留场景启用"：
+ *   - 已存在其它非保留场景 → 取顺序第一个作为启用场景（其余收敛掉，返回 `collapsed: true`）
+ *   - 不存在 → 空数组（什么都不启用）
+ * @returns 是否发生了收敛（供 UI 如实提示）。
+ */
+export function collapseActiveForNewScene(index) {
+    if (normalizeActive(index.active) !== null)
+        return false;
+    const names = Object.keys(index.scenes || {}).filter((n) => n !== SHARED_GROUP && n !== GLOBAL_SCENE);
+    const first = names.sort((a, b) => sceneOrderOf(index, a) - sceneOrderOf(index, b) || a.localeCompare(b))[0];
+    index.active = first === undefined ? [] : [first];
+    return true;
+}
+/** 场景名 = 分组路径的第一段（`web/frontend` 属于场景 `web`）。 */
+export function sceneOf(group) {
+    const idx = String(group || '').indexOf('/');
+    return idx >= 0 ? group.slice(0, idx) : group;
+}
+// ── 指纹 ───────────────────────────────────────────────────────────────────
+/** 指纹里必须包含一切影响渲染的索引字段（active / enabled / order / groups.order / scenes.order / label / description）。 */
+export function signatureOfIndex(index) {
+    const active = normalizeActive(index.active);
+    const rules = Object.keys(index.rules).sort().map((id) => {
+        const e = index.rules[id];
+        return `${id}\u0000${e.enabled === false ? '0' : '1'}\u0000${e.order ?? DEFAULT_ORDER}`;
+    });
+    const groups = Object.keys(index.groups).sort().map((g) => `${g}\u0000${index.groups[g]?.order ?? DEFAULT_GROUP_ORDER}`);
+    // 场景顺序决定段内场景的先后 → 必须进指纹，否则改顺序后段文本不会重算。
+    // label 与 description 同理（sceneHeader 的「场景说明」一行直接渲染 description）——
+    // 手改索引文件（带外变更）时只有指纹变化才会触发重算。
+    const scenes = Object.keys(index.scenes || {}).sort().map((s) => {
+        const e = index.scenes[s];
+        return `${s}\u0000${e.order ?? (s === GLOBAL_SCENE ? 0 : DEFAULT_GROUP_ORDER)}\u0000${e.label ?? ''}\u0000${e.description ?? ''}`;
+    });
+    return `A:${active === null ? '*' : active.join(',')}|R:${rules.join(';')}|G:${groups.join(';')}|S:${scenes.join(';')}`;
+}
+// ── 场景排序与标题 ─────────────────────────────────────────────────────────
+/** 场景排序键：索引 scenes.order 优先，回退到旧 groups.order，再回退默认值。 */
+export function sceneOrderOf(index, scene) {
+    if (scene === GLOBAL_SCENE)
+        return 0;
+    const s = index.scenes?.[scene]?.order;
+    if (typeof s === 'number' && Number.isFinite(s))
+        return s;
+    return index.groups[scene]?.order ?? DEFAULT_GROUP_ORDER;
+}
+/** 场景显示名：`global` → 「全局」（磁盘名保持 ASCII），其余用索引 label 或场景名。 */
+export function sceneLabel(scene, index) {
+    if (scene === GLOBAL_SCENE)
+        return index?.scenes?.[GLOBAL_SCENE]?.label || GLOBAL_SCENE_LABEL;
+    const label = index?.scenes?.[scene]?.label;
+    return label && label !== '' ? label : scene;
+}
+/** 单个场景的标题：**场景在最顶层**（`##`，与「子智能体」「MCP 服务器」等段同级）。 */
+export const sceneHeading = (scene) => `## 场景：${sceneLabel(scene)}`;
+/**
+ * 没填描述时的默认「场景说明」（用户裁定 2026-09-16：全局桶一直没有描述，读起来像缺了一块，
+ * 统一成"每个场景块都有场景说明"）。
+ *
+ * 默认句同时承担"这个场景是什么"的答疑（此前只有光秃秃的 `## 场景：X`，模型读不懂 —— 用户实测）：
+ * 两个恒常桶说明生效范围，用户场景说明它是当前启用的那份配置。
+ */
+export const defaultSceneDescription = (scene) => (scene === GLOBAL_SCENE ? '全局记忆，任何对话都生效'
+    : scene === SHARED_GROUP ? '共享记忆，任何对话都生效'
+        : '用户配置的上下文，当前启用');
+/**
+ * 单个场景的段头：场景标题 + **恒有**的 `场景说明：<描述>`。
+ *
+ * 场景描述（界面「描述（可选）」，≤60 字符）**此前从未注入过** —— 它正是「这个场景是
+ * 干什么的」的答案，属于模型做判断需要的上下文，而不是只给人看的元数据；界面上的文案
+ * 也从没把它标成「只给使用者看」（对比 AGENTS.md 预设的描述，那里是明确标注的）。
+ * 描述为空时给 `defaultSceneDescription` 的默认句（用户裁定：全局桶没描述时读起来像
+ * 缺了一块，统一成每个场景块都有说明）。
+ */
+export function sceneHeader(scene, index) {
+    const head = sceneHeading(scene);
+    const described = String(index?.scenes?.[scene]?.description ?? '').replaceAll(/\s+/g, ' ').trim();
+    const description = described === '' ? defaultSceneDescription(scene) : described;
+    // 加粗（用户裁定 2026-09-16）：与引导语同款强调，别让"场景说明"读起来像可忽略的普通正文。
+    return `${head}\n\n**场景说明：${description}**\n\n`;
+}
+/** 场景渲染顺序：全局 `global` 最先（它的记忆对任何对话都成立，先讲总则），
+ *  其次 `_shared`（历史保留名），其余按（索引 scenes.order, 场景名）。 */
+export function compareSceneBuckets(a, b, index) {
+    if (a === b)
+        return 0;
+    if (a === GLOBAL_SCENE)
+        return -1;
+    if (b === GLOBAL_SCENE)
+        return 1;
+    if (a === SHARED_GROUP)
+        return -1;
+    if (b === SHARED_GROUP)
+        return 1;
+    const ao = sceneOrderOf(index, a);
+    const bo = sceneOrderOf(index, b);
+    return ao - bo || a.localeCompare(b);
+}
+// ── bundle 附件 ────────────────────────────────────────────────────────────
+/**
+ * bundle 记忆的附件名（**同步**版 —— 段渲染必须同步返回，`listAttachments` 是异步的）。
+ * 口径与异步版一致：跳过正文本体（`<名>.md`，旧数据可能是 `SKILL.md`），只认普通文件。
+ */
+export function attachmentNamesSync(bundleDir, name) {
+    try {
+        const docNames = new Set([bundleDocName(name), LEGACY_BUNDLE_DOC]);
+        return readdirSync(bundleDir, { withFileTypes: true })
+            .filter((e) => e.isFile() && !docNames.has(e.name))
+            .map((e) => e.name)
+            .sort((a, b) => a.localeCompare(b));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * bundle 记忆的附件**摘要**（列表页用）：数量 / 总体积 / 前几个文件名。
+ *
+ * 口径与 `attachmentNamesSync`（也就是注入给模型的那份清单）逐字一致：跳过正文本体，
+ * 只认普通文件 —— 所以页面上的数字与模型实际看到的一致，不会出现「界面说 3 个、模型只见 2 个」。
+ * `names` 截到 ATTACHMENT_LIST_MAX：tooltip 列不下更多，要全看到编辑弹窗里去看。
+ *
+ * 目录读不到（索引残留了已消失的条目）→ 返回 null，让界面**什么都不显示**，
+ * 而不是谎报「0 个附件」。
+ */
+export function attachmentSummarySync(bundleDir, name) {
+    let names;
+    try {
+        const docNames = new Set([bundleDocName(name), LEGACY_BUNDLE_DOC]);
+        names = readdirSync(bundleDir, { withFileTypes: true })
+            .filter((e) => e.isFile() && !docNames.has(e.name))
+            .map((e) => e.name)
+            .sort((a, b) => a.localeCompare(b));
+    }
+    catch {
+        return null;
+    }
+    let bytes = 0;
+    for (const entry of names) {
+        try {
+            bytes += statSync(join(bundleDir, entry)).size;
+        }
+        catch { /* 读不到的条目不计体积 */ }
+    }
+    return { count: names.length, bytes, names: names.slice(0, ATTACHMENT_LIST_MAX) };
+}
+/**
+ * 附件行（只有 bundle 记忆才有）：**给目录与文件名，不给内容**。
+ * 附件可能是图片、二进制、大 md —— 全文注入又贵又会把段预算吃光；给路径，模型需要时自己读。
+ */
+export function attachmentLine(file) {
+    if (file.kind !== 'bundle')
+        return '';
+    const names = attachmentNamesSync(file.bundleDir, file.name);
+    if (names.length === 0)
+        return '';
+    const shown = names.slice(0, ATTACHMENT_LIST_MAX);
+    const more = names.length - shown.length;
+    return `附件目录：${file.bundleDir}（未注入正文，共 ${names.length} 个：${shown.join('、')}${more > 0 ? `，另 ${more} 个` : ''}）`;
+}
+// ── 单条记忆的渲染 ─────────────────────────────────────────────────────────
+/** 多行正文整体缩进 2 格（列在条目内容列上），空行保持空行、不加尾随空白。 */
+export const indentBody = (text) => text
+    .split('\n')
+    .map((line) => (line === '' ? line : '  ' + line))
+    .join('\n');
+/** 括号注解用的显式描述：派生描述与正文重复、不进段（只存在于界面投影）；换行压成单行，避免把「一行一条」的列表项撑断。 */
+export const explicitDescriptionOf = (f) => (f.descriptionDerived || !f.description ? '' : String(f.description).replaceAll(/\s+/g, ' ').trim());
+/**
+ * 单条信息的渲染形态 —— **能一行就一行，但恒为列表项**。
+ *
+ *   单行且不长的正文 → `- **名称**（描述） — 正文`（与 MCP / 子智能体两个段的列表同形；无显式描述时括号不出现）
+ *   多行或过长的正文 → `- **名称**（描述）` + 空行 + 缩进 2 格的正文（挂在条目下）
+ *
+ * 名称恒为标题：它就是这条记忆的身份（工具 id `<场景>/<名称>`、bundle 目录/文件名都以它为准），
+ * 用户说「记忆里的 X」、模型再调 `memory_manager_*` 时都对得上号；显式描述是括号注解，不抢标题。
+ *
+ * 为什么全都做成列表项：早先多行正文走 `### 名称` 标题块，附件行只能退化成与记忆**同级**的
+ * `- 附件目录：…`（没有父列表项可挂）—— 既可能被读成一条独立记忆，某些渲染器里还会把下一个
+ * `###` 标题吞进列表（与上一条粘连）。统一成「一条记忆 = 一个列表项、正文与附件都缩进挂在
+ * 条目下」后，两种记忆外观完全一致，归属也不再靠位置猜测。
+ *
+ * 为什么要分两种：用户常有十几条「一句话事实」（「提交格式：PDF」），每条都占标题 + 空行 +
+ * 正文三行，整段会散成一长串标题；压成一行后十条信息就是十行。多行正文是**用户写的完整
+ * Markdown**（可能自带标题、代码块、嵌套列表），整体缩进 2 格挂到条目下，结构原样保留。
+ *
+ * 返回值带 `inline`：调用方据此决定下一条记忆前要不要空行（单行条目连续排列，其余空行分隔）。
+ */
+export function memoryBlock(file) {
+    const desc = explicitDescriptionOf(file);
+    // 加粗的只有名称：`- **名称**（描述） — 正文`，与 MCP 段 `- **server**（N 个工具） — …` 同形。
+    const title = `**${file.name}**` + (desc === '' ? '' : `（${desc}）`);
+    const text = String(file.body ?? '').trim();
+    const inline = text === '' || (!text.includes('\n') && text.length <= INLINE_BODY_MAX);
+    const head = text === ''
+        ? `- ${title}`
+        : (inline ? `- ${title} — ${text}` : `- ${title}\n\n${indentBody(text)}`);
+    const attach = attachmentLine(file);
+    if (attach === '')
+        return { text: `${head}\n`, inline };
+    // 附件行恒为缩进子项：只用 `- ` 会被解析成与记忆**同级**的列表项（`- A` / `- 附件目录：A的` /
+    // `- B` … 四条平级，归属读不出来）。单行条目紧跟其后保持列表连续；多行条目前面空一行，
+    // 免得被读成用户正文自己的列表项。
+    return { text: inline ? `${head}\n  - ${attach}\n` : `${head}\n\n  - ${attach}\n`, inline };
+}