dsh-session-conductor 1.3.13 → 1.3.17

package/lib/features/base-routes.js

@@ -0,0 +1,156 @@
+// dsh-session-conductor — 基础路由（语言包 / 会话列表）
+//
+// 【为什么单独成文件】原先内联在 lib/apply.js 的 `ctx.inject(["webServer"])` 回调里（该回调上千行，
+// 审计 readability/max-function-length 拦截）。这里只搬「注册」这部分，handler 体逐字保留。
+//
+// ⚠️ 语言包路径：原先写 `./i18n/zh.json`（相对 lib/apply.js）。本文件位于 lib/features/，
+// 必须改成 `../i18n/...`，否则运行时读不到语言包、页面文案会整块变空。
+import { readFileSync } from 'node:fs';
+import { readJson, send } from '../http.js';
+import { log } from '../shared/log.js';
+import { invalidateSessionListCache } from '../sessions/list-cache.js';
+import { readListIndex } from '../features/session-messaging/index.js';
+import { buildSessionListCached } from '../sessions/list.js';
+
+/**
+ * 注册基础路由（语言包 + 会话列表）。
+ * @param {object} deps
+ * @param {object} deps.webServer 宿主 webServer 服务
+ * @param {object} deps.ctx 插件 ctx
+ * @returns {void}
+ */
+export function registerBaseRoutes({ webServer, ctx }) {
+    // i18n 语言包：**只读一次并缓存**。原先每个请求都同步读两个 JSON（约 33 KB）并解析，
+    // 既阻塞事件循环（审计 io-risk 高风险），又纯属浪费 —— 语言包在一个进程生命周期内不会变。
+    let i18nCache = null;
+    const loadI18n = () => {
+      if (i18nCache !== null) return i18nCache;
+      i18nCache = {
+        zh: JSON.parse(readFileSync(new URL("../i18n/zh.json", import.meta.url), "utf8")),
+        en: JSON.parse(readFileSync(new URL("../i18n/en.json", import.meta.url), "utf8")),
+      };
+      return i18nCache;
+    };
+
+    // ---------- GET /api/session-conductor/i18n ----------
+    // 语言包外置 lib/i18n/{zh,en}.json（单份权威，改文案无需重打包 client bundle）：
+    // 浏览器端 ModuleLoader 的 require 不支持相对路径 JSON（require("./i18n/*.json") 抛 missed-the-module-table），
+    // 故由宿主侧读外置 JSON 经 HTTP 暴露、客户端 fetch 拉取合并（语言包外置做法）。
+    webServer.register({
+      kind: "exact",
+      path: "/api/session-conductor/i18n",
+      handler: async (req, res) => {
+        try {
+          if ((req.method ?? "GET") !== "GET") {
+            return send(res, 405, { ok: false, error: { code: "METHOD", message: "Method Not Allowed" } });
+          }
+          const { zh, en } = loadI18n();
+          return send(res, 200, { ok: true, zh, en });
+        } catch (error) {
+          return send(res, 500, { ok: false, error: { code: "INTERNAL", message: String(error?.message ?? error) } });
+        }
+      },
+    });
+
+    // ---------- 预览页已移出本插件 ----------
+    // 原先这里用 /api/session-conductor/preview/<settings|panel> 同源服务 assets/preview-*.html
+    // （那两份 html 由已移除的 tools/preview-snapshot.sh 生成）。现在预览能力统一由独立插件
+    // dsh-useful-tools 的 `preview` 工具提供：gen 生成 + serve 带 backend 反代真实后端，
+    // 效果等价且本插件不必再托管静态页，故路由与产物一并移除。
+
+    // ---------- GET /api/session-conductor/list ----------
+    webServer.register({
+      kind: "exact",
+      path: "/api/session-conductor/list",
+      handler: async (req, res) => {
+        try {
+          // 非 GET 请求会改动会话列表内容，先失效列表缓存，使面板随后的 refresh 立刻看到最新（而非 5s TTL 内的旧列表）。
+          if (req.method !== "GET") invalidateSessionListCache();
+          // 索引直读（`?fromIndex=true`）：与 `list_sessions` 工具的 `fromIndex` **同义** ——
+          //   直接读落盘索引、**不做全量构建**，秒回精简列表（不含 live 状态与归档态）。
+          //   原先路由只认 job / stream 两个声明，传 fromIndex 会被**静默忽略** ⇒ 悄悄退化成
+          //   226 秒级的全量构建（本机实测一次 41 秒才回），调用方以为拿到了快照、实际被钉在慢路径上。
+          if (String(req.url ?? "").includes("fromIndex=true")) {
+            const items = await readListIndex(ctx);
+            if (!items) {
+              send(res, 200, { ok: true, fromIndex: true, sessions: [], hint: "落盘索引为空或尚未建立；去掉 fromIndex 走一次刷新（会重建索引，冷缓存可能很慢）" });
+              return;
+            }
+            send(res, 200, { ok: true, fromIndex: true, sessions: items, hint: "来自落盘索引，不含 live 状态与归档态；要实时状态请去掉 fromIndex 走刷新" });
+            return;
+          }
+          // job 模式（`?job=1` 或 `Accept: application/x-job`）：冷缓存下全量构建很慢
+          //   （本机实测 201 份日志 / 1.5 GB 时 226 秒），把构建交给宿主后台 job 并**立即**返回 jobId，
+          //   调用方改用 job_output / job_list 取结果，前台不再被钉住。
+          //   默认（无 job 声明）仍走下面的普通 JSON / NDJSON 流式分支 —— 一字不动，避免改坏面板。
+          const wantJob = /application\/x-job/i.test(req.headers?.accept ?? "")
+            || String(req.url ?? "").includes("job=1");
+          if (wantJob) {
+            const jobs = ctx?.get?.("jobs");
+            if (!jobs || typeof jobs.start !== "function") {
+              send(res, 501, { ok: false, error: { code: "unsupported", message: "宿主未挂载 jobs 服务，无法注册后台 job；请改用默认（流式/JSON）路径" } });
+              return;
+            }
+            // 构建只做一次；完成后顺手失效 TTL，保证随后任何一条路径读到的都是本次结果
+            const done = buildSessionListCached(ctx).then(
+              (sessions) => { invalidateSessionListCache(); return { status: "completed", output: JSON.stringify({ ok: true, sessions }) }; },
+              (error) => ({ status: "failed", detail: String(error?.message ?? error) }),
+            );
+            const spec = { kind: "session-conductor-list", label: "list（会话列表刷新）", run: () => ({ cancel: () => {}, done }) };
+            // HTTP 入口没有执行主体 ⇒ 用「无主」注册（宿主存在全局 job 控制器即可）；
+            // 无主不可用时如实回 501，由调用方决定是否改用默认路径（不静默吞掉）。
+            try {
+              send(res, 200, { ok: true, async: true, jobId: jobs.start(spec), hint: "用宿主 job_output / job_list 取结果" });
+            } catch (error) {
+              // 后台 job 不可用（HTTP 入口**没有执行主体**，宿主 job 控制器会拒绝无主注册 ——
+              //   实测回的是「no job controller serves this agent」）：不再直接 501 把调用方堵死；
+              //   退一步给**索引快照**（秒回、明确标注来源与「不含 live 状态」），索引也没有才如实 501。
+              const items = await readListIndex(ctx).catch(() => null);
+              if (items) {
+                send(res, 200, {
+                  ok: true,
+                  async: false,
+                  fromIndex: true,
+                  sessions: items,
+                  jobUnavailable: String(error?.message ?? error),
+                  hint: "后台 job 不可用，已回退为落盘索引快照（不含 live 状态）；要实时状态请走默认或流式分支",
+                });
+                return;
+              }
+              send(res, 501, { ok: false, error: { code: "unsupported", message: `注册后台 job 失败：${String(error?.message ?? error)}（且落盘索引不可用，无回退）` } });
+            }
+            return;
+          }
+          // list 流式（仅当请求声明 Accept: application/x-ndjson）——live 会话先快速
+          // 写出，冷会话串行逐个解析边写边出，前端 fetch stream 逐行追加（每获取一个立即显示，
+          // 不等全部）；排序由前端按 updatedAt 倒序插入保持（流式下后端不再整体排序）。
+          // 默认（无 Accept 头/旧前端/预览页垫片）仍返回普通 JSON——兼容不匹配的调用方。
+          const wantStream =
+            /application\/x-ndjson/i.test(req.headers?.accept ?? "") || String(req.url ?? "").includes("stream=1");
+          if (!wantStream) {
+            const sessions = await buildSessionListCached(ctx);
+            send(res, 200, { ok: true, sessions });
+            return;
+          }
+          res.setHeader("Content-Type", "application/x-ndjson; charset=utf-8");
+          res.setHeader("Cache-Control", "no-store");
+          if (res.socket?.setNoDelay) res.socket.setNoDelay(true);
+          res.write(JSON.stringify({ ok: true, stream: true }) + "\n"); // 头行（前端跳过非会话行）
+          // 立即把头行推出去：冷缓存时后面要逐份解压上百份日志（实测 41~226 秒），
+          // 若头行压在缓冲里，浏览器这侧会一直「没有响应」，看起来就像接口挂了。
+          // flushHeaders/flush 老版本不一定有，取不到就跳过（写操作本身已尽量及时）。
+          try {
+            if (typeof res.flushHeaders === "function") res.flushHeaders();
+            if (typeof res.flush === "function") res.flush();
+          } catch { /* 不支持 flush 的宿主不影响主流程 */ }
+          const onItem = (item) => { try { res.write(JSON.stringify(item) + "\n"); } catch { /* 连接已断 */ } };
+          await buildSessionListCached(ctx, { onItem, serial: true });
+          try { res.end(); } catch { /* 连接已断 */ }
+        } catch (error) {
+          try {
+            res.end(JSON.stringify({ ok: false, error: { code: "internal", message: String(error?.message ?? error) } }) + "\n");
+          } catch { /* 连接已断 */ }
+        }
+      },
+    });
+}

package/lib/features/member-model/batch.js

@@ -0,0 +1,97 @@
+// dsh-session-conductor — 批量把模型/权限应用到多个成员
+//
+// 【为什么单独抽一层】「对全部子代理统一模型/权限」在指令和 AI 工具两边都要用，
+// 而且批量写会话日志有几个必须统一的纪律：
+//   ① **串行**执行：并发写多个会话日志容易互相干扰（每个都是一次读-改-写），串行最省心；
+//   ② **逐个隔离失败**：某个成员失败（日志损坏、名册状态异常）不能中断其余成员；
+//   ③ **回执必须带名单**：批量操作最怕「不知道改了谁」，所以结果逐条列出、并统计成功/失败数。
+import { log } from "../../shared/log.js";
+import { switchAgentModel } from "./switch.js";
+import { switchMemberPermission } from "./permission.js";
+
+/** 成员显示名（名字 + 短 id，便于人核对）。 */
+export function memberDisplay(member, sessionId) {
+  const name = member?.name ?? null;
+  const shortId = sessionId ? `${sessionId.slice(0, 8)}…` : "?";
+  return name ? `${name}(${shortId})` : String(sessionId ?? "?");
+}
+
+/**
+ * 批量切换模型。
+ *
+ * @param {object} ctx 插件 context
+ * @param {Array<{sessionId: string, member?: object, agent?: object|null}>} targets 目标列表（已解析）
+ * @param {{provider: string, model: string}} route 目标路由
+ * @returns {Promise<{rows: Array<{sessionId: string, label: string, ok: boolean, detail: string}>, okCount: number, failCount: number}>}
+ */
+export async function applyModelToMany(ctx, targets, { provider, model }) {
+  const rows = [];
+  for (const t of targets) {
+    const label = memberDisplay(t.member, t.sessionId);
+    try {
+      const result = await switchAgentModel(ctx, t.sessionId, provider, model, t.agent ?? null);
+      if (result?.error) {
+        rows.push({ sessionId: t.sessionId, label, ok: false, detail: String(result.error) });
+      } else {
+        rows.push({ sessionId: t.sessionId, label, ok: true, detail: String(result.via ?? "") });
+      }
+    } catch (error) {
+      rows.push({ sessionId: t.sessionId, label, ok: false, detail: String(error?.message ?? error) });
+    }
+  }
+  const okCount = rows.filter((r) => r.ok).length;
+  log(ctx, `批量切换模型：${okCount}/${rows.length} 成功（${provider}/${model}）`);
+  return { rows, okCount, failCount: rows.length - okCount };
+}
+
+/**
+ * 批量切换权限预设。
+ *
+ * @param {object} ctx 插件 context
+ * @param {Array<{sessionId: string, member?: object}>} targets 目标列表（已解析）
+ * @param {string} preset 目标预设名
+ * @returns {Promise<{rows: Array<{sessionId: string, label: string, ok: boolean, detail: string}>, okCount: number, failCount: number}>}
+ */
+export async function applyPermissionToMany(ctx, targets, preset) {
+  const rows = [];
+  for (const t of targets) {
+    const label = memberDisplay(t.member, t.sessionId);
+    try {
+      const result = await switchMemberPermission(ctx, t.sessionId, preset);
+      if (result?.error) {
+        rows.push({ sessionId: t.sessionId, label, ok: false, detail: String(result.error) });
+      } else {
+        const from = result.from ?? "(未记录)";
+        const note = result.note ? `；${result.note}` : "";
+        rows.push({ sessionId: t.sessionId, label, ok: true, detail: `${from} → ${result.to}${note}` });
+      }
+    } catch (error) {
+      rows.push({ sessionId: t.sessionId, label, ok: false, detail: String(error?.message ?? error) });
+    }
+  }
+  const okCount = rows.filter((r) => r.ok).length;
+  log(ctx, `批量切换权限：${okCount}/${rows.length} 成功（${preset}）`);
+  return { rows, okCount, failCount: rows.length - okCount };
+}
+
+/**
+ * 渲染批量结果（先名单、后逐条结果、最后统计）。
+ *
+ * 批量操作的价值一半在「改了谁」的可核对性上，所以名单一定要完整列出，
+ * 不能只给一句「已处理 N 个」。
+ *
+ * @param {string} title 标题行（如「批量切换模型 → sa6400/deepseek-v4.1-flash」）
+ * @param {{rows: Array<{label: string, ok: boolean, detail: string}>, okCount: number, failCount: number}} report
+ * @param {string[]} [extra] 额外说明行
+ * @returns {string}
+ */
+export function renderBatchReport(title, report, extra = []) {
+  const lines = [title, ""];
+  lines.push(`受影响成员（共 ${report.rows.length} 个）：`);
+  for (const r of report.rows) lines.push(`  ${r.ok ? "✅" : "❌"} ${r.label}`);
+  lines.push("", "逐条结果：");
+  for (const r of report.rows) lines.push(`  ${r.ok ? "✅" : "❌"} ${r.label}：${r.detail || (r.ok ? "成功" : "失败")}`);
+  lines.push("", `统计：成功 ${report.okCount} 个 ｜ 失败 ${report.failCount} 个`);
+  for (const line of extra) if (line) lines.push(line);
+  return lines.join("\n");
+}

package/lib/features/member-model/clone-member.js

@@ -0,0 +1,270 @@
+// dsh-session-conductor — 把成员「换名」成新成员（新建 + 搬会话内容）
+//
+// 【为什么需要它】宿主的 Team 成员名是**不可变身份字段**：`team/member` 投影里有断言
+//   if (prior.name !== member.name || prior.provider !== member.provider || prior.context !== member.context)
+//     throw new Error('changed immutable identity fields')
+// 而且只允许 provisioning → active 这一次写入，已 active 的成员再写必被 phase 校验拒绝；
+// 宿主侧也没有任何 rename 接口。所以「改名」唯一可行的路是：**新建一个成员，再把旧内容搬过去**。
+//
+// 【为什么这条路成立】成员名与会话内容是两份独立数据：
+//   · 成员名 → 存在 **Lead 会话日志**的 `team/member` 事件里（换名时由 spawn 写入新名）
+//   · 会话内容 → 存在 **成员自己的会话日志**里（本模块替换的就是这一份，其中没有 team/member）；
+//     实测该日志的事件里 0 处引用自己的 sessionId，因此**只换 header 就够**。
+//
+// 【搬运必须「原样复制」（一次真实事故换来的结论）】会话事件之间布满了跨事件引用：
+//   顶层 `sourceEventSeqs`、顶层 `surfaceOp { startSeq, endSeq }`、`data.messageSeqs`、
+//   `data.shadowedSeqs`、`data.headerSeq`，以及 compaction 的 start → summary/prune → end 强配对。
+//   任何 seq 重排或事件增删都会让这些关系断裂，宿主加载时直接判 corrupt。实测连续撞过三种：
+//     ① `sourceEventSeqs ranges must contain unique earlier seqs`
+//     ② `session/title messageSeqs must cite distinct earlier human user/message events`
+//     ③ `successful compaction/end requires one summary`
+//   而搬运本质就是复制：源 seq 本来就是 0..N 连续，所以正确做法是
+//   **事件一条不改、seq 一个不动，只替换 header 里的身份字段**。
+//
+// 【必须保留的两条硬约束】
+//   ① 帧必须带校验和：宿主读帧会验 checksum，缺了就报「会话文件 总和检查码不匹配」直接拒读；
+//   ② 目标成员不能正在跑：宿主以内存态优先，对运行中的成员改磁盘文件不生效，还可能被覆盖回去。
+import { readFileSync, writeFileSync, renameSync, copyFileSync, statSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { log } from "../../shared/log.js";
+import { findTargetAgent } from "./locate.js";
+import { PLACEHOLDER_PROMPT, waitUntilIdle } from "./create-teammate.js";
+
+/**
+ * 把源会话的事件原样搬到目标会话日志，**只替换 header 身份**。
+ *
+ * 设计要点（每一条都是为了避免破坏跨事件引用）：
+ *   · 源事件一条不丢、seq 一个不改 —— 引用关系因此天然保持，compaction 配对也完整；
+ *   · header 用**目标**自己的（id / cwd / parentSession / origin / delegationDepth / isSeeded），
+ *     否则新成员会变成旧成员；
+ *   · 只允许改 `subagent/descriptor` 里的 label / 模型路由（纯字符串字段，不参与任何引用）。
+ *
+ * @param {string} sourceFile 源成员会话日志
+ * @param {string} targetFile 目标成员会话日志
+ * @param {{label?: string, seedProvider?: string, seedModel?: string}} [opts]
+ *        label 改写 descriptor 的描述；seedProvider/seedModel 改写 descriptor 的模型路由（省略则沿用源）
+ * @returns {Promise<{ok: true, events: number, backup: string, size: number} | {ok: false, error: string}>}
+ */
+export async function transplantSessionLog(sourceFile, targetFile, opts = {}) {
+  const { decodeAllFrames } = await import("../../zstd-frames.js");
+  const { encodeSessionText } = await import("../../repair.js");
+
+  // ① 目标 header：新成员的身份，原样保留
+  let targetHead;
+  try {
+    const text = await decodeAllFrames(readFileSync(targetFile));
+    targetHead = JSON.parse(text.split("\n").find((l) => l.trim() !== ""));
+  } catch (error) {
+    return { ok: false, error: `读取目标会话 header 失败：${String(error?.message ?? error)}` };
+  }
+  if (!targetHead?.id) return { ok: false, error: "目标会话 header 缺少 id，无法确定新成员身份" };
+
+  // ② 源事件：全部读取，一条不丢（只跳过 header 那一行）
+  let sourceEvents;
+  try {
+    const text = await decodeAllFrames(readFileSync(sourceFile));
+    sourceEvents = [];
+    for (const line of text.split("\n")) {
+      if (line.trim() === "") continue;
+      let e;
+      try { e = JSON.parse(line); } catch { continue; }
+      if (e?.type === "session") continue;   // header 用目标的
+      sourceEvents.push(e);
+    }
+  } catch (error) {
+    return { ok: false, error: `读取源会话失败：${String(error?.message ?? error)}` };
+  }
+  if (sourceEvents.length === 0) return { ok: false, error: "源会话没有可搬运的事件" };
+
+  // ③ 仅改写 descriptor 的人类可读字段（不碰 seq、不碰任何引用）
+  for (const e of sourceEvents) {
+    if (e?.type !== "subagent/descriptor" || !e.data) continue;
+    if (opts.label !== undefined) e.data.label = String(opts.label);
+    if (opts.seedProvider !== undefined) e.data.agentProvider = String(opts.seedProvider);
+    if (opts.seedModel !== undefined) e.data.agentModel = String(opts.seedModel);
+  }
+
+  const outText = [JSON.stringify(targetHead), ...sourceEvents.map((e) => JSON.stringify(e))].join("\n") + "\n";
+  const encoded = await encodeSessionText(outText);   // 官方编码器：自带 checksum
+
+  // ④ 写前自检：解码回来**逐条与源对比**。这是唯一能证明「除 header 与 descriptor 外一字未改」的检查，
+  //    也是唯一能保证「源能加载 ⇒ 目标也能加载」的依据（跨事件引用全部原样）。
+  let verifyLines;
+  try {
+    const verifyText = await decodeAllFrames(encoded);
+    verifyLines = verifyText.split("\n").filter((l) => l.trim() !== "");
+  } catch (error) {
+    return { ok: false, error: `写前自检解码失败：${String(error?.message ?? error)}` };
+  }
+  if (verifyLines.length !== sourceEvents.length + 1) {
+    return { ok: false, error: `写前自检事件数不符（期望 ${sourceEvents.length + 1} 行，实际 ${verifyLines.length}）` };
+  }
+  const verifyHead = JSON.parse(verifyLines[0]);
+  if (verifyHead.id !== targetHead.id) {
+    return { ok: false, error: `写前自检 header 身份不符（期望 ${targetHead.id}，实际 ${verifyHead.id}）` };
+  }
+  const normalize = (v) => JSON.stringify(v);
+  for (let i = 0; i < sourceEvents.length; i += 1) {
+    let got;
+    try { got = JSON.parse(verifyLines[i + 1]); } catch {
+      return { ok: false, error: `写前自检第 ${i + 2} 行不是合法 JSON` };
+    }
+    const want = sourceEvents[i];
+    if (normalize(got) === normalize(want)) continue;
+    // descriptor 允许 label / 模型路由不同，其余必须逐字段一致
+    if (want?.type === "subagent/descriptor" && got?.type === "subagent/descriptor") {
+      const a = { ...want.data }; const b = { ...got.data };
+      delete a.label; delete b.label; delete a.agentProvider; delete b.agentProvider;
+      delete a.agentModel; delete b.agentModel;
+      if (normalize(a) === normalize(b) && got.seq === want.seq) continue;
+    }
+    return { ok: false, error: `写前自检失败：第 ${i + 2} 行（seq ${want?.seq ?? "?"} / ${want?.type ?? "?"}）与源不一致，放弃写入` };
+  }
+
+  // ⑤ 备份目标原日志 → 原子写回
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const backup = join(dirname(targetFile), `session.before-clone-${stamp}.bak`);
+  try {
+    copyFileSync(targetFile, backup);
+  } catch (error) {
+    return { ok: false, error: `备份目标日志失败（未写入）：${String(error?.message ?? error)}` };
+  }
+  const tmp = join(dirname(targetFile), ".session.clone.tmp");
+  writeFileSync(tmp, encoded, { mode: 0o600 });
+  renameSync(tmp, targetFile);
+
+  return { ok: true, events: sourceEvents.length, backup, size: statSync(targetFile).size };
+}
+
+/**
+ * 把成员 A 的会话内容克隆到一个新成员 B（B 用新名字，A 不动）。
+ *
+ * 四步：① 解析源成员 ② spawn 新成员（占位任务，只消耗极短提示）③ 中断并等它空闲
+ *      ④ 把源会话内容原样搬进新成员日志。
+ *
+ * @param {object} ctx 插件 context
+ * @param {object} exec 执行上下文（含 agent）
+ * @param {{source: string, name: string, description?: string, withHistory?: boolean,
+ *          provider?: string, model?: string, subagentProvider?: string}} args 参数
+ * @returns {Promise<object>} 回执对象（成功含 newMember，失败含 error）
+ */
+export async function cloneMemberAs(ctx, exec, args) {
+  const caller = exec?.agent ?? null;
+  const source = String(args?.source ?? "").trim();
+  const name = String(args?.name ?? "").trim();
+  if (!source) return { error: "source 不能为空（成员名 / sessionId / 标题关键字）" };
+  if (!name) return { error: "name 不能为空（新成员名，lower-kebab-case）" };
+
+  // ① 源成员
+  const found = findTargetAgent(ctx, source, { caller });
+  if (found?.error) return { error: `找不到源成员：${found.error}` };
+  if (found.sessionId === name) return { error: "新成员名与源成员相同，无需克隆" };
+
+  // 目标会话日志路径要在 spawn 之前确认定位能力可用（否则白建一个成员）
+  const { findSessionLogById, sessionsRootOf } = await import("../../sessions/events.js");
+  const sourceFile = findSessionLogById(found.sessionId, sessionsRootOf());
+  if (!sourceFile) return { error: `源成员会话日志不存在（sessionId=${found.sessionId}）` };
+
+  // ② 能力检查
+  const teams = ctx.get("agentTeams");
+  if (typeof teams?.spawnTeammate !== "function") return { error: "宿主未挂载 agentTeams.spawnTeammate，无法新建成员" };
+  const lead = caller;
+  if (!lead) return { error: "拿不到发起方 Agent（请从 Lead 会话调用）" };
+  let subagentProvider = String(args?.subagentProvider ?? "").trim();
+  if (!subagentProvider) {
+    try {
+      const list = ctx.get("subagents")?.list?.() ?? [];
+      subagentProvider = String(list[0] ?? "");
+    } catch { subagentProvider = ""; }
+  }
+  if (!subagentProvider) return { error: "拿不到子代理 provider（ctx.subagents.list() 为空），可显式传 subagentProvider" };
+
+  // ③ spawn + 中断 + 等空闲
+  let spawned;
+  try {
+    spawned = await teams.spawnTeammate(lead, {
+      name,
+      description: String(args?.description ?? `克隆自 ${found.member?.name ?? found.sessionId}`),
+      prompt: [{ type: "text", text: PLACEHOLDER_PROMPT }],
+      context: "fresh",
+      provider: subagentProvider,
+    });
+  } catch (error) {
+    return { error: `新建成员失败：${String(error?.message ?? error)}` };
+  }
+  const newId = spawned?.id ?? spawned?.sessionId ?? null;
+  if (!newId) return { error: "新建成员成功但拿不到 sessionId" };
+
+  try {
+    if (typeof teams.interrupt === "function") {
+      try { await teams.interrupt(lead, name); } catch { /* 可能已结束，继续等 */ }
+    }
+    const idle = await waitUntilIdle(teams, lead, name, null);
+    if (!idle.idle) {
+      return { error: `新成员仍在运行（status=${idle.status}），为避免覆盖其内存态，未搬内容；可稍后重试`, newMember: { name, sessionId: newId } };
+    }
+
+    // ④ 搬内容
+    if (args?.withHistory === false) {
+      return { ok: true, newMember: { name, sessionId: newId }, events: 0, note: "已按要求只建空成员，未搬历史" };
+    }
+    const targetFile = findSessionLogById(newId, sessionsRootOf());
+    if (!targetFile) return { error: `新成员会话日志不存在（sessionId=${newId}）`, newMember: { name, sessionId: newId } };
+
+    const moved = await transplantSessionLog(sourceFile, targetFile, {
+      seedProvider: String(args?.provider ?? "").trim() || undefined,
+      seedModel: String(args?.model ?? "").trim() || undefined,
+    });
+    if (!moved.ok) return { error: `搬会话内容失败：${moved.error}`, newMember: { name, sessionId: newId } };
+
+    log(ctx, `成员克隆：${found.sessionId} → ${newId}（${moved.events} 事件，${(moved.size / 1048576).toFixed(2)}MB）`);
+    return {
+      ok: true,
+      newMember: { name, sessionId: newId },
+      sourceMember: { name: found.member?.name ?? null, sessionId: found.sessionId },
+      events: moved.events,
+      backup: moved.backup,
+      sizeMB: Number((moved.size / 1048576).toFixed(2)),
+    };
+  } catch (error) {
+    return { error: `克隆过程失败：${String(error?.message ?? error)}`, newMember: { name, sessionId: newId } };
+  }
+}
+
+/**
+ * 渲染 clone_member_as 的回执。
+ *
+ * 要点：① 明确「新成员已建、旧成员未动」，避免误以为旧成员被改名/删除；
+ * ② 报出搬了多少事件与多大体积（这是唯一能说明「内容真的搬过去了」的量）；
+ * ③ 报出备份路径（搬错可回滚）；④ 失败时连带已建成员一起说明，免得留下孤儿成员。
+ *
+ * @param {{source?: string, name?: string, withHistory?: boolean}} args 调用参数
+ * @param {object} result cloneMemberAs 的返回
+ * @returns {string}
+ */
+export function renderCloneMemberResult(args, result) {
+  const lines = [];
+  if (result?.error) {
+    lines.push(`克隆失败：${result.error}`);
+    if (result.newMember?.sessionId) {
+      lines.push(`已创建但未搬内容的新成员：${result.newMember.name}(${result.newMember.sessionId})`);
+      lines.push("该成员是空壳，可按需删除（delete 或团队面板移除）。");
+    }
+    return lines.join("\n");
+  }
+  const nm = result.newMember ?? {};
+  lines.push(`已新建成员：${nm.name}(${nm.sessionId})`);
+  if (result.sourceMember?.sessionId) {
+    lines.push(`内容来源：${result.sourceMember.name ?? "(未命名)"}(${result.sourceMember.sessionId}) — 该成员本身未改动`);
+  }
+  if (result.note) {
+    lines.push(result.note);
+  } else {
+    lines.push(`搬运事件：${result.events} 条 ｜ 会话体积：${result.sizeMB}MB`);
+    lines.push(`回滚备份：${result.backup}`);
+  }
+  lines.push("");
+  lines.push("生效方式：新成员下次被唤醒时按磁盘日志加载（当前是冷会话，此时替换才生效）。");
+  lines.push("如需「改名」效果，旧成员可自行删除；名字唯一性由宿主保证，新名不能与现有成员重复。");
+  return lines.join("\n");
+}