dsh-session-conductor 1.3.19 → 1.4.5

package/lib/sessions/export-restore.js

@@ -0,0 +1,384 @@
+// dsh-session-conductor — 从「会话导出包」恢复/覆盖会话
+//
+// 【为什么需要】DSH 的会话导出包是**明文 jsonl** 目录结构（`session.v4.jsonl` +
+// `subagents/<id>/session.v4.jsonl` + `media/`），而运行时读的是
+// `session.v4.jsonl.zstd` —— 带校验和的**多帧** zstd 容器，首帧必须恰好一行 header。
+// 因此「把备份覆盖回去」不是简单拷贝：必须按官方容器格式重新编码，否则宿主会报
+// 「会话文件 总和检查码不匹配」或 `corrupt session log`（本机两种都踩过）。
+//
+// 【三种坑与本模块的对应做法】
+//   ① 无校验和帧 ⇒ 宿主拒读：压缩时固定带 ZSTD_c_checksumFlag（复用 zstd-frames 的 CHECKSUM_OPTIONS）。
+//   ② 单帧塞进整份日志 ⇒ 读取端一次性解压整帧、内存尖峰：按 eventsPerFrame 分帧（宿主自己也是分批 append）。
+//   ③ 覆盖 seeded 会话时打乱 inherited 标记 ⇒ 宿主断言 "seeded session requires an inherited event count"：
+//      只覆盖日志文件本身，不动 projcache 与目录内其它文件；报告里回显 inherited 标记位置供核对。
+//
+// 【安全】默认 dryRun：只扫描并报告「会覆盖哪些会话、事件多少、帧多少」，不写盘。
+// 真正写盘时：先校验 header.id 与目标一致、事件 seq 严格连续，再写 tmp 后 rename 原子替换；
+// 写完重新逐帧解码复核事件数与末事件，复核不通过即记为错误。
+
+import { readFileSync, writeFileSync, renameSync, existsSync, mkdirSync, readdirSync, statSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import zlib from 'node:zlib';
+import { createHash } from 'node:crypto';
+import { scanZstdFrames, validateHeaderFrame, decodeAllFrames, CHECKSUM_OPTIONS } from '../zstd-frames.js';
+import { sessionsRootOf, findSessionLogById } from './events.js';
+import { log } from '../shared/log.js';
+
+/** 每个 zstd 事件帧里装多少条事件（宿主自己也是分批 append，太大会让读取端内存尖峰）。 */
+const DEFAULT_EVENTS_PER_FRAME = 1000;
+
+/** 导出包里明文的固定文件名。 */
+const PLAIN_NAME = 'session.v4.jsonl';
+
+/**
+ * 把一个明文 jsonl 编码成 DSH 官方 zstd 多帧容器（首帧恰好一行 header，每帧带校验和）。
+ *
+ * @param {string} plainText 明文 jsonl 全文
+ * @param {{eventsPerFrame?: number}} [opts]
+ * @returns {{ok: true, buffer: Buffer, header: object, eventCount: number, frames: number, inheritedAt: number|null}
+ *          | {ok: false, error: string}}
+ */
+export function encodePlainToZstd(plainText, opts = {}) {
+  const eventsPerFrame = Math.max(1, opts.eventsPerFrame ?? DEFAULT_EVENTS_PER_FRAME);
+  const lines = String(plainText).split('\n').filter((l) => l.trim() !== '');
+  if (lines.length < 2) return { ok: false, error: '明文事件不足（至少需要 header + 1 条事件）' };
+
+  let header;
+  try {
+    header = JSON.parse(lines[0]);
+  } catch (error) {
+    return { ok: false, error: `首行不是合法 JSON：${String(error?.message ?? error)}` };
+  }
+  if (header?.type !== 'session' || !header?.id) return { ok: false, error: '首行不是 session header' };
+
+  // 事件必须 seq 严格连续：不连续的日志写出去宿主也会判 corrupt，这里直接拒绝
+  const events = [];
+  let prev = -1;
+  let gaps = 0;
+  let bad = 0;
+  let inheritedAt = null;
+  for (let i = 1; i < lines.length; i += 1) {
+    let e;
+    try {
+      e = JSON.parse(lines[i]);
+    } catch {
+      bad += 1;
+      continue;
+    }
+    if (typeof e?.seq === 'number') {
+      if (prev >= 0 && e.seq !== prev + 1) gaps += 1;
+      prev = e.seq;
+    }
+    if (e?.type === 'session/end-seed' && e?.data?.inherited === true) inheritedAt = e.seq;
+    events.push(e);
+  }
+  if (bad > 0) return { ok: false, error: `明文里有 ${bad} 行坏 JSON` };
+  if (gaps > 0) return { ok: false, error: `明文事件 seq 不连续（${gaps} 处），拒绝编码` };
+
+  const frames = [zlib.zstdCompressSync(Buffer.from(lines[0] + '\n', 'utf8'), CHECKSUM_OPTIONS)];
+  for (let i = 0; i < events.length; i += eventsPerFrame) {
+    const chunk = events.slice(i, i + eventsPerFrame).map((e) => JSON.stringify(e)).join('\n') + '\n';
+    frames.push(zlib.zstdCompressSync(Buffer.from(chunk, 'utf8'), CHECKSUM_OPTIONS));
+  }
+  return { ok: true, buffer: Buffer.concat(frames), header, eventCount: events.length, frames: frames.length, inheritedAt };
+}
+
+/**
+ * 扫描导出包目录，列出「里面有哪些会话、各自对应哪个目标目录」。
+ *
+ * 目标目录解析顺序：① 按会话 id 找现有会话目录（覆盖已有会话）② 找不到就用同族目录
+ * （导出包里父会话所在的项目目录）新建 —— 同族会话必然同 cwd，避免自己实现路径编码。
+ *
+ * @param {string} exportDir 解压后的导出包目录
+ * @param {{home?: string}} [opts]
+ * @returns {{entries: Array<object>, error?: string}}
+ */
+export function scanExportDir(exportDir, opts = {}) {
+  if (!existsSync(exportDir)) return { entries: [], error: `导出目录不存在：${exportDir}` };
+  // 注意：sessionsRootOf() 不接受参数（它只读 process.env.DSH_HOME），
+  // 所以要支持自定义 home 必须自己拼 <home>/sessions，不能把 home 当参数传进去。
+  const root = opts.home ? join(opts.home, 'sessions') : sessionsRootOf();
+  const entries = [];
+
+  const readHeaderOf = (plainPath) => {
+    try {
+      const firstLine = readFileSync(plainPath, 'utf8').split('\n', 1)[0];
+      return JSON.parse(firstLine);
+    } catch {
+      return null;
+    }
+  };
+
+  // 父会话（导出包根下的 session.v4.jsonl）
+  const parentPlain = join(exportDir, PLAIN_NAME);
+  let familyDir = null;
+  if (existsSync(parentPlain)) {
+    const header = readHeaderOf(parentPlain);
+    if (header?.id) {
+      const existing = findSessionLogById(header.id, root);
+      const targetDir = existing ? join(existing, '..') : null;
+      if (targetDir) familyDir = join(targetDir, '..');
+      entries.push({
+        role: 'parent',
+        id: header.id,
+        plainPath: parentPlain,
+        targetDir,
+        action: targetDir ? 'overwrite' : 'skip',
+        reason: targetDir ? '' : '找不到该会话的现有目录',
+      });
+    }
+  }
+
+  // 子代理（subagents/<id>/session.v4.jsonl）
+  const subsDir = join(exportDir, 'subagents');
+  if (existsSync(subsDir)) {
+    for (const name of readdirSync(subsDir)) {
+      const plainPath = join(subsDir, name, PLAIN_NAME);
+      if (!existsSync(plainPath)) continue;
+      const header = readHeaderOf(plainPath);
+      const id = header?.id;
+      if (!id) {
+        entries.push({ role: 'subagent', id: name, plainPath, targetDir: null, action: 'skip', reason: '明文 header 无法解析' });
+        continue;
+      }
+      const existing = findSessionLogById(id, root);
+      if (existing) {
+        entries.push({ role: 'subagent', id, plainPath, targetDir: join(existing, '..'), action: 'overwrite' });
+      } else if (familyDir) {
+        entries.push({ role: 'subagent', id, plainPath, targetDir: join(familyDir, id), action: 'create' });
+      } else {
+        entries.push({ role: 'subagent', id, plainPath, targetDir: null, action: 'skip', reason: '既无现有目录、又无同族目录可落' });
+      }
+      if (id !== name) {
+        const last = entries[entries.length - 1];
+        last.reason = `${last.reason ? last.reason + '；' : ''}目录名(${name})与 header.id 不一致`;
+      }
+    }
+  }
+  return { entries };
+}
+
+/**
+ * 从导出包的 `media/` 恢复附件对象到内容寻址对象库。
+ *
+ * 【为什么必须做】会话消息里引用的是 `sha256:<64hex>` 附件对象，宿主按
+ * `<DSH_HOME>/attachments/v1/objects/<前两位>/<64hex>` 取文件。只覆盖会话日志而不恢复
+ * 附件，会话就会在下一轮报「Attachment object is missing」（本机实测：恢复 4 个会话后
+ * 168 个引用里缺 27 个）。
+ *
+ * 【安全】导出包里的文件名形如 `sha256:<64hex>.<ext>`，这里**逐个重算 sha256 与文件名比对**，
+ * 不一致直接拒绝（不把坏文件写进对象库）；已存在的对象跳过（内容寻址天然幂等）。
+ *
+ * @param {object} o
+ * @param {string} o.exportDir 解压后的导出包目录
+ * @param {string} o.home DSH_HOME
+ * @param {boolean} [o.dryRun] true 只统计不写盘（默认 true）
+ * @returns {{placed:number, existed:number, rejected:number, dryRun:boolean, errors:string[]}}
+ */
+export async function restoreExportMedia(o) {
+  const dryRun = o?.dryRun !== false;
+  const mediaDir = join(o?.exportDir ?? '', 'media');
+  const out = { placed: 0, existed: 0, rejected: 0, dryRun, errors: [] };
+  if (!existsSync(mediaDir)) return out;
+  const objRoot = join(o?.home ?? '', 'attachments', 'v1', 'objects');
+
+  for (const name of readdirSync(mediaDir)) {
+    const m = /^sha256:([0-9a-f]{64})(?:\.[A-Za-z0-9]+)?$/.exec(name);
+    if (!m) {
+      out.rejected += 1;
+      out.errors.push(`跳过（命名不合规范）：${name}`);
+      continue;
+    }
+    const hash = m[1];
+    const target = join(objRoot, hash.slice(0, 2), hash);
+    if (existsSync(target)) {
+      out.existed += 1;
+      continue;
+    }
+    let buf;
+    try {
+      buf = readFileSync(join(mediaDir, name));
+    } catch (e) {
+      out.rejected += 1;
+      out.errors.push(`${name}：读取失败 ${String(e?.message ?? e)}`);
+      continue;
+    }
+    // 内容自证：重算 sha256 必须等于文件名里的 hash
+    const actual = createHash('sha256').update(buf).digest('hex');
+    if (actual !== hash) {
+      out.rejected += 1;
+      out.errors.push(`${name}：内容校验失败（实际 sha256=${actual.slice(0, 12)}…），拒绝写入`);
+      continue;
+    }
+    if (dryRun) {
+      out.placed += 1;
+      continue;
+    }
+    try {
+      mkdirSync(join(objRoot, hash.slice(0, 2)), { recursive: true, mode: 0o700 });
+      writeFileSync(target, buf, { mode: 0o600 });
+      out.placed += 1;
+    } catch (e) {
+      out.rejected += 1;
+      out.errors.push(`${name}：写入失败 ${String(e?.message ?? e)}`);
+    }
+  }
+  return out;
+}
+
+/**
+ * 恢复后让「新日志」真正生效：清投影缓存 + 尝试把 live 会话卸载回冷状态。
+ *
+ * 【为什么必须做】DSH 有**三层状态**：会话日志（磁盘）/ projcache（投影缓存）/ 进程内存里的 agent。
+ * 只覆盖磁盘日志时，界面仍显示旧内容——本机实测：日志 11:20 已覆盖，projcache 还停在 11:06，
+ * 打开会话看到的就是替换前的内容。因此恢复后必须：
+ *   ① 删掉该会话的 projcache 条目（否则冷读仍会拿旧投影）；
+ *   ② 若会话还是 live 的（内存里有 agent），把它 detach 回冷状态，下次打开才会重新从磁盘读。
+ *
+ * detach 需要插件 ctx（要 agents/sessions 服务）；没有 ctx 时只清缓存并如实标注，
+ * 由调用方提示「需重载/重启宿主」。
+ *
+ * @param {object} o
+ * @param {string} o.home DSH_HOME
+ * @param {string} o.sessionId 会话 id
+ * @param {object} [o.ctx] 插件 ctx（有则尝试 detach）
+ * @returns {Promise<{projcacheCleared: boolean, detached: boolean, note?: string}>}
+ */
+async function invalidateAfterRestore({ home, sessionId, ctx }) {
+  const out = { projcacheCleared: false, detached: false };
+  // ① 清投影缓存
+  try {
+    const cacheFile = join(home, 'storages', 'session_projcache', 'sessions', `${sessionId}.json`);
+    if (existsSync(cacheFile)) {
+      unlinkSync(cacheFile);
+      out.projcacheCleared = true;
+    }
+  } catch (error) {
+    out.note = `清投影缓存失败：${String(error?.message ?? error)}`;
+  }
+  // ② 尝试 detach（让内存态丢弃；非 live 幂等返回 ok）
+  if (ctx) {
+    try {
+      const { detachSessionAgent } = await import('./detach.js');
+      const r = await detachSessionAgent(ctx, sessionId);
+      out.detached = r?.ok === true;
+      if (!r?.ok && r?.error?.message && !out.note) out.note = `detach 未执行：${r.error.message}`;
+    } catch (error) {
+      if (!out.note) out.note = `detach 失败：${String(error?.message ?? error)}`;
+    }
+  } else if (!out.note) {
+    out.note = '未传 ctx，未尝试 detach（若会话仍打开着，需重载/重启宿主才能看到新内容）';
+  }
+  return out;
+}
+
+/**
+ * 按导出包恢复/覆盖会话。
+ *
+ * @param {object} o
+ * @param {string} o.exportDir 解压后的导出包目录
+ * @param {string} [o.home] DSH_HOME（缺省按宿主约定推导）
+ * @param {string[]} [o.sessionIds] 只处理这些会话（缺省全部）
+ * @param {boolean} [o.dryRun] true 只扫描报告（默认 true）
+ * @param {number} [o.eventsPerFrame]
+ * @param {object} [o.ctx] 可选：传插件 ctx 时顺带写日志，并尝试 detach（把 live 会话卸载回冷状态）
+ * @param {boolean} [o.invalidate] 默认 true：恢复后清该会话 projcache，避免「覆盖了但界面还是旧内容」
+ * @param {boolean} [o.media] 默认 true：同时把导出包 media/ 里的附件恢复到对象库
+ *   （只覆盖日志不恢复附件，会话下一轮会报 Attachment object is missing）
+ * @returns {Promise<{ok:boolean, dryRun:boolean, results:Array<object>, errors:Array<string>}>}
+ */
+export async function restoreSessionsFromExport(o) {
+  const dryRun = o?.dryRun !== false;
+  const { entries, error } = scanExportDir(o?.exportDir, { home: o?.home });
+  if (error) return { ok: false, dryRun, results: [], errors: [error] };
+  const only = Array.isArray(o?.sessionIds) && o.sessionIds.length > 0 ? new Set(o.sessionIds) : null;
+  const results = [];
+  const errors = [];
+
+  for (const entry of entries) {
+    if (only && !only.has(entry.id)) continue;
+    if (entry.action === 'skip') {
+      results.push({ ...entry, status: 'skipped' });
+      continue;
+    }
+    let plain;
+    try {
+      plain = readFileSync(entry.plainPath, 'utf8');
+    } catch (e) {
+      errors.push(`${entry.id}：读明文失败 ${String(e?.message ?? e)}`);
+      results.push({ ...entry, status: 'error' });
+      continue;
+    }
+    const encoded = encodePlainToZstd(plain, { eventsPerFrame: o?.eventsPerFrame });
+    if (!encoded.ok) {
+      errors.push(`${entry.id}：${encoded.error}`);
+      results.push({ ...entry, status: 'error' });
+      continue;
+    }
+    if (encoded.header.id !== entry.id) {
+      errors.push(`${entry.id}：明文 header.id=${encoded.header.id} 与目录不一致`);
+      results.push({ ...entry, status: 'error' });
+      continue;
+    }
+    const summary = {
+      ...entry,
+      status: dryRun ? 'would-restore' : 'restored',
+      eventCount: encoded.eventCount,
+      frames: encoded.frames,
+      inheritedAt: encoded.inheritedAt,
+      bytes: encoded.buffer.length,
+    };
+    if (dryRun) {
+      results.push(summary);
+      continue;
+    }
+    // 真正写盘：目录缺则建，写 tmp 后 rename 原子替换，再逐帧复核
+    try {
+      if (!existsSync(entry.targetDir)) {
+        mkdirSync(entry.targetDir, { recursive: true, mode: 0o700 });
+        summary.created = true;
+      }
+      const target = join(entry.targetDir, 'session.v4.jsonl.zstd');
+      const tmp = join(entry.targetDir, '.session.restore.tmp');
+      writeFileSync(tmp, encoded.buffer, { mode: 0o600 });
+      renameSync(tmp, target);
+      const after = readFileSync(target);
+      const headerCheck = await validateHeaderFrame(after);
+      const { frames } = scanZstdFrames(after);
+      const checksums = frames.map((fr) => (after.readUInt8(fr.start + 4) & 0x04) !== 0);
+      const backLines = (await decodeAllFrames(after)).split('\n').filter((l) => l.trim() !== '');
+      const okVerify = headerCheck.ok && checksums.every(Boolean) && backLines.length - 1 === encoded.eventCount;
+      summary.verified = okVerify;
+      summary.sizeMB = Math.round((statSync(target).size / 1048576) * 10) / 10;
+      if (!okVerify) {
+        errors.push(
+          `${entry.id}：写后复核未通过（首帧 ${headerCheck.ok}、校验和 ${checksums.every(Boolean)}、事件 ${backLines.length - 1}/${encoded.eventCount}）`,
+        );
+      } else if (o?.invalidate !== false) {
+        // 复核通过才失效：顺序很重要——先确保磁盘是对的，再丢缓存/卸载
+        const inv = await invalidateAfterRestore({ home: o?.home ?? '', sessionId: entry.id, ctx: o?.ctx });
+        summary.projcacheCleared = inv.projcacheCleared;
+        summary.detached = inv.detached;
+        if (inv.note) summary.note = inv.note;
+      }
+      results.push(summary);
+    } catch (e) {
+      errors.push(`${entry.id}：写盘失败 ${String(e?.message ?? e)}`);
+      results.push({ ...summary, status: 'error' });
+    }
+  }
+  // 附件：只恢复会话日志、不恢复 media 会让会话下一轮报 Attachment object is missing
+  let media = null;
+  if (o?.media !== false) {
+    try {
+      media = await restoreExportMedia({ exportDir: o?.exportDir, home: o?.home ?? '', dryRun });
+      if (media.rejected > 0) errors.push(...media.errors.slice(0, 5));
+    } catch (e) {
+      errors.push(`恢复附件失败：${String(e?.message ?? e)}`);
+    }
+  }
+  if (o?.ctx) {
+    log(o.ctx, `导出包恢复：${dryRun ? '预览' : '执行'} ${results.length} 项，附件 ${media ? `新增 ${media.placed}/已有 ${media.existed}/拒绝 ${media.rejected}` : '未处理'}，错误 ${errors.length} 条`);
+  }
+  return { ok: errors.length === 0, dryRun, results, errors, media };
+}

package/lib/sessions/member-trace.js

@@ -16,6 +16,8 @@ import { readFile } from "node:fs/promises";
 import { findSessionLogById, sessionsRootOf } from "./events.js";
 // 流式逐事件读取的公共底座（与记忆取回共用；本模块只负责「按 turn/step 怎么组织」）
 import { streamSessionEvents } from "./log-stream.js";
+// 目标解析的公共底座（id / 前缀 / 标题 / 成员名；与记忆取回共用）
+import { resolveTargetSession } from "./resolve.js";
 
 /** 单条文本默认截断长度（summary 模式下更短，见 SUMMARY_CLIP）。 */
 const DEFAULT_MAX_ITEM = 800;
@@ -292,9 +294,10 @@ export function registerMemberTraceTool(ctx, defineTool, tools, deps = {}) {
       const selfId = exec?.agent?.session?.id;
       if (!selfId) return "拿不到当前会话 id，无法读取轨迹。";
 
-      // 目标解析：与记忆取回共用同一套（成员名 → id / 前缀 / 标题；命中多个给候选，不猜）
+      // 目标解析走公共底座（sessions/resolve.js）：id / id 前缀 / 标题 / 成员名，命中多个给候选不猜。
+      // 两个工具（本工具与记忆取回）共用同一套，避免各自一套解析各缺一块。
       const want = typeof args?.session === "string" ? args.session.trim() : "";
-      const resolveFn = resolve ?? (await import("../features/memory-recall/index.js")).resolveSessionTarget;
+      const resolveFn = resolve ?? resolveTargetSession;
       const rounds = Math.min(
         Number.isSafeInteger(args?.rounds) && args.rounds > 0 ? args.rounds : 1,
         maxRounds,
@@ -308,12 +311,14 @@ export function registerMemberTraceTool(ctx, defineTool, tools, deps = {}) {
 
       let targetId = selfId;
       if (want && want !== selfId) {
-        const hit = await resolveFn(ctx, want, selfId);
+        const hit = await resolveFn(ctx, want, selfId, { agent: exec?.agent });
         if (hit?.candidates) {
           return `「${want}」匹配到多个目标，请用更完整的 id 重试：\n`
             + hit.candidates.slice(0, 10).map((c) => `- ${c.id}${c.title ? ` ｜ ${c.title}` : ""}`).join("\n");
         }
-        if (!hit?.id) return `找不到目标会话「${want}」：没有匹配的成员名 / 会话 id / id 前缀 / 标题。`;
+        if (!hit?.id) {
+          return `找不到目标会话「${want}」：没有匹配的成员名 / 会话 id / id 前缀 / 标题。`;
+        }
         targetId = hit.id;
       }
 

package/lib/sessions/resolve.js

@@ -0,0 +1,120 @@
+// dsh-session-conductor — 会话目标解析（公共底座）
+//
+// 【为什么抽出来】「用户/AI 给一个模糊的目标（id / id 前缀 / 标题 / 成员名），解析成确切 sessionId」
+// 这件事原先只写在记忆取回里（`resolveSessionTarget`），成员轨迹又自己接了一套，两边各有缺口。
+//
+// 【原先的缺陷】旧实现判断「这是不是一个会话目录」用的是 `dir.startsWith("session-")`。
+// 主会话的目录名确实是 `session-<uuid>` 形式，**但子代理/成员会话的目录名是裸 UUID**
+// （例如 `c9a6a72c-908e-4040-b88c-2e6ce5014378`）。于是成员会话永远进不了候选集，
+// 完整 id 和 id 前缀都解析不出来，工具只好报「找不到目标会话」。
+//
+// 【现在的判据】不看目录名叫什么，只看**里面有没有会话日志文件**（`findSessionLog`）——
+// 这是宿主自己也用的判据，且与目录命名规则解耦（v0/v3/v4 各格式都能识别）。
+//
+// 【为什么异步】会话目录可能上千个；同步 stat/readdir 会把事件循环钉住，拖慢整个宿主。
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { findSessionLog } from "../session-log.js";
+import { sessionsRootOf } from "./events.js";
+
+/**
+ * 列出全部会话 id（按「目录里有会话日志」判断，不看目录名前缀）。
+ *
+ * @param {string} root 会话根目录
+ * @returns {Promise<string[]>}
+ */
+async function listSessionIds(root) {
+  const ids = [];
+  const isDir = async (p) => {
+    try { return (await stat(p)).isDirectory(); } catch { return false; }
+  };
+  if (!root || !(await isDir(root))) return ids;
+  for (const group of await readdir(root)) {
+    const groupPath = join(root, group);
+    if (!(await isDir(groupPath))) continue;
+    for (const dir of await readdir(groupPath)) {
+      const dirPath = join(groupPath, dir);
+      if (!(await isDir(dirPath))) continue;
+      // 关键：用「有没有日志文件」而不是「目录名像不像 session-xxx」
+      if (findSessionLog(dirPath)) ids.push(dir);
+    }
+  }
+  return ids;
+}
+
+/**
+ * 把一个模糊目标解析成会话 id。支持：完整 id → id 前缀 → 标题子串。
+ *
+ * 多个命中时**不猜**，返回候选清单交给调用方展示。
+ *
+ * @param {object} ctx 插件 context（用于落盘索引里的标题）
+ * @param {string} want 用户给的目标
+ * @param {string} [selfId] 当前会话 id（等于它时直接返回）
+ * @param {{root?: string}} [opts]
+ * @returns {Promise<{id: string, title?: string|null} | {candidates: Array<{id: string, title?: string|null}>} | null>}
+ *          null = 三段都没命中
+ */
+export async function resolveSessionId(ctx, want, selfId, opts = {}) {
+  const raw = String(want ?? "").trim();
+  if (!raw) return null;
+  if (selfId && raw === selfId) return { id: selfId };
+
+  const root = opts.root ?? sessionsRootOf();
+  const ids = await listSessionIds(root);
+
+  if (ids.includes(raw)) return { id: raw };
+  const byPrefix = ids.filter((id) => id.startsWith(raw));
+  if (byPrefix.length === 1) return { id: byPrefix[0] };
+  if (byPrefix.length > 1) return { candidates: byPrefix.map((id) => ({ id })) };
+
+  // 标题子串：只查落盘索引（避免为了解析一个参数去逐份读日志）
+  try {
+    const { loadListDiskCache } = await import("./list-cache.js");
+    let entries = {};
+    try { entries = loadListDiskCache(ctx)?.entries ?? {}; } catch { entries = {}; }
+    const lower = raw.toLowerCase();
+    const byTitle = Object.entries(entries)
+      .filter(([, e]) => String(e?.title ?? "").toLowerCase().includes(lower))
+      .map(([id, e]) => ({ id, title: e?.title ?? null }));
+    if (byTitle.length === 1) return byTitle[0];
+    if (byTitle.length > 1) return { candidates: byTitle };
+  } catch {
+    // 索引不可用：退化为只按 id 解析
+  }
+  return null;
+}
+
+/**
+ * 解析目标会话，**额外支持 Team 成员名**。
+ *
+ * 成员名是日常最顺手的写法（`read_member_trace({ session: "writer" })`），但成员名既不是会话 id
+ * 也不是会话标题，通用解析认不了。这里在通用解析未命中时补一层成员解析。
+ *
+ * 用动态 `import()` 引成员定位：`sessions/` 是本插件底层，`features/member-model/` 是上层，
+ * 静态引用会形成层级倒置；且宿主没装 agent-team 时成员解析本就不可用，动态导入让那种情况自然降级。
+ *
+ * @param {object} ctx 插件 context
+ * @param {string} want 用户给的目标
+ * @param {string} [selfId] 当前会话 id
+ * @param {{root?: string, agent?: object}} [opts] agent 用于成员名册的作用域（缺省按全局名册）
+ * @returns {Promise<{id: string, title?: string|null, matched?: string} | {candidates: Array<{id: string, title?: string|null}>} | null>}
+ */
+export async function resolveTargetSession(ctx, want, selfId, opts = {}) {
+  const direct = await resolveSessionId(ctx, want, selfId, opts);
+  if (direct) return direct;
+
+  try {
+    const { findTargetAgent } = await import("../features/member-model/locate.js");
+    const found = findTargetAgent(ctx, want, { caller: opts.agent ?? null });
+    if (found?.sessionId) return { id: found.sessionId, matched: found.matched ?? "成员名" };
+    if (found?.error && /匹配到 \d+ 个/.test(String(found.error))) {
+      // 成员名模糊命中多个：把它转成候选清单，保持「不猜」的一致行为
+      const ids = [...String(found.error).matchAll(/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/g)]
+        .map((m) => ({ id: m[1] }));
+      if (ids.length > 1) return { candidates: ids };
+    }
+  } catch {
+    // 成员解析不可用：按未命中处理，由调用方给出统一报错
+  }
+  return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-session-conductor",
-  "version": "1.3.19",
+  "version": "1.4.5",
   "description": "DSH session management enhancement: archive/restore sessions, batch & conditional delete, AI auto-rename, interrupted-session auto-resume, release idle sessions, workspace grouping, undo last message, repair damaged session logs, value analysis, full-text search, per-member model switching (list_models / set_member_model), and plan/closing template injection (system-prompt + context).",
   "type": "module",
   "main": "lib/index.js",