@zaofan/dsh-qqbot 1.9.2 → 1.10.0

package/examples/ext-tools/session_watch.mjs

@@ -1,93 +1,139 @@
-/**
- * session_watch.mjs — 查看/补挂「回合结束回灌」钩子
- *
- * 配合 session_create 用：创建时会自动挂钩子（session_create → lib/session_watch_lib.register）。
- * 本工具负责：
- *   · list（默认）：列出正在盯的子会话（子 id / 父 id / 标签 / 是否已攒到正文 / 已结算几次）
- *   · attach：给一个"已存在的子会话"补挂钩子（创建时漏挂、或插件重启后钩子丢了的情况）
- *   · detach：取消盯某个子会话
- * ⚠️ 主人要求这类工具不给全部会话用：已落地 `expose: 'qq'`（2026-10-12），只在 QQ 会话注册。
- */
-import { statSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-
-/**
- * 带版本号地加载共用库 —— **必须这么加载**。
- *
- * 原因同 session_create.mjs：插件只给**工具文件本身**的 import 加了 `?v=<mtime>`，
- * 工具内部裸路径 import 会被 ESM 模块缓存永久命中 ⇒ 改 `tools/lib/` 热刷不生效。
- * （这里原来是顶层静态 import，等于永远锁死在插件启动那一刻的旧版本。）
- */
-async function loadWatchLib() {
-  const url = new URL('./lib/session_watch_lib.mjs', import.meta.url);
-  let v = '0';
-  try { v = String(statSync(fileURLToPath(url)).mtimeMs); } catch { /* 拿不到 mtime 就退回裸 import */ }
-  return import(v === '0' ? url.href : `${url.href}?v=${v}`);
-}
-
-/** 进程内自己维护的"取消盯梢"集合（库只管挂，取消在本工具侧记录） */
-const detached = new Set();
-
-export default {
-  name: 'session_watch',
-  // ★ 2026-10-12：**父会话专用**（"我作为父"去挂/摘回灌钩子）⇒ 不给子会话看。
-  // 只注册到 QQ 会话（子会话不可见）—— "我作为父"才需要挂/摘回灌钩子。
-  expose: 'qq',
-  description:
-    '查看/补挂「回合结束回灌」钩子：默认列出正在盯的子会话与状态；attach=给指定子会话补挂（子会话 id + 父会话 id）；detach=取消盯梢。' +
-    '（本工具是**兜底**通道：正常情况下让子会话自己用 send_message 回执即可。）',
-  inputSchema: {
-    action: { type: 'string', description: 'list（默认）=看状态 / attach=给已存在的子会话补挂 / detach=取消盯梢' },
-    child_session_id: { type: 'string', description: 'attach 或 detach 时要指定的子会话 id' },
-    parent_agent_id: { type: 'string', description: 'attach 时填**父会话 id**（历史上叫"父 agent id"，指的是同一个东西；不填＝用"我自己这个会话"）' },
-    label: { type: 'string', description: 'attach 时的标签，便于记认（可选）' },
-  },
-
-  async run(args = {}, env = {}) {
-    const ctx = env?.ctx ?? null;
-    const root = ctx && typeof ctx === 'object' && ctx.root ? ctx.root : ctx;
-    if (!root?.get) return { ok: false, msg: '拿不到宿主 ctx（需要 expose:\'all\'）' };
-
-    const lib = await loadWatchLib();
-
-    const action = String(args?.action ?? 'list').toLowerCase();
-    const p = (n) => String(n).padStart(2, '0');
-    const fmt = (t) => {
-      if (!t) return '—';
-      const d = new Date(t);
-      return Number.isNaN(d.getTime()) ? '—' : `${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
-    };
-
-    if (action === 'attach' || action === '补挂') {
-      const child = String(args?.child_session_id ?? '').trim();
-      const parent = String(args?.parent_agent_id ?? env?.exec?.agent?.id ?? '').trim();
-      if (!child) return { ok: false, msg: 'attach 需要 child_session_id' };
-      if (!parent) return { ok: false, msg: 'attach 需要 parent_agent_id（不填会用"我自己"）' };
-      detached.delete(child);
-      const r = await lib.register(root, { parentAgentId: parent, childSessionId: child, label: String(args?.label ?? '') });
-      return { ok: !String(r).startsWith('未挂'), msg: 'attach → ' + r };
-    }
-
-    if (action === 'detach' || action === '取消') {
-      const child = String(args?.child_session_id ?? '').trim();
-      if (!child) return { ok: false, msg: 'detach 需要 child_session_id' };
-      detached.add(child);
-      return { ok: true, msg: `已从盯梢名单移除 ${child.slice(0, 8)}…（注：钩子本身是全局一个，这里只是不再为它回灌）` };
-    }
-
-    // list
-    const items = lib.listWatching().filter((x) => !detached.has(x.childSessionId));
-    if (!items.length) {
-      return {
-        ok: true,
-        msg: '【回合结束回灌】当前没有盯着任何子会话。\n用 session_create 建会话时会自动挂；也可以用 attach 给已存在的子会话补挂。',
-      };
-    }
-    const lines = items.map(
-      (x) =>
-        `   · 子 ${x.shortId ?? x.childSessionId.slice(0, 8)}… → 父 ${x.parentShortId ?? x.parentAgentId.slice(0, 8)}…` +
-        `${x.label ? '  [' + x.label + ']' : ''}  攒到正文=${x.hasText ? 'Y' : 'N'}  已结算=${x.turnsSeen} 次  上次回灌=${fmt(x.lastFiredAt)}`,
-    );
-    return { ok: true, msg: `【回合结束回灌】正在盯 ${items.length} 个子会话：\n` + lines.join('\n') };
-  },
-};
+/**
+ * session_watch.mjs — 查看/补挂「回合结束回灌」钩子（含三档 + QQ 转发）
+ *
+ * 配合 session_create 用：创建时会自动挂钩子（session_create → lib/session_watch_lib.register）。
+ * 本工具负责：
+ *   · list（默认）：列出正在盯的子会话（子 id / 父 id / 标签 / **档位** / QQ 转发是否就绪 / 已结算几次）
+ *   · attach：给一个"已存在的子会话"补挂钩子（创建时漏挂、或插件重启后钩子丢了的情况）
+ *   · mode：改已挂盯梢的档位（一/二/三档随时可改）
+ *   · detach：取消盯某个子会话
+ *
+ * ★ 2026-10-12 主人定：三档（mode）
+ *   1 = 一档（默认）：末段正文回灌父会话 + **同时**转发到父会话所在的 QQ
+ *   2 = 二档：本回合**所有正文 + 报错**都转发 QQ，**不进**父会话上下文
+ *   3 = 三档：所有正文 + 报错**进**父会话上下文（**不唤醒**）+ 同时也转发 QQ
+ *
+ * ⚠️ 主人要求这类工具不给全部会话用：已落地 `expose: 'qq'`（2026-10-12），只在 QQ 会话注册。
+ */
+import { statSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * 带版本号地加载共用库 —— **必须这么加载**。
+ *
+ * 原因同 session_create.mjs：插件只给**工具文件本身**的 import 加了 `?v=<mtime>`，
+ * 工具内部裸路径 import 会被 ESM 模块缓存永久命中 ⇒ 改 `tools/lib/` 热刷不生效。
+ * （这里原来是顶层静态 import，等于永远锁死在插件启动那一刻的旧版本。）
+ */
+async function loadWatchLib() {
+  const url = new URL('./lib/session_watch_lib.mjs', import.meta.url);
+  let v = '0';
+  try { v = String(statSync(fileURLToPath(url)).mtimeMs); } catch { /* 拿不到 mtime 就退回裸 import */ }
+  return import(v === '0' ? url.href : `${url.href}?v=${v}`);
+}
+
+/** 档位 → 人话 */
+const modeText = (m) => (Number(m) === 2 ? '二档·只转QQ不进父' : (Number(m) === 3 ? '三档·进父不唤醒+转QQ' : '一档·末段回灌+转QQ'));
+/** 把用户给的档位写法归一（收 1/2/3 与中文「一档/二档/三档」） */
+function normMode(v) {
+  const s = String(v ?? '').trim();
+  if (/^(2|二)/.test(s)) return 2;
+  if (/^(3|三)/.test(s)) return 3;
+  if (/^(1|一)/.test(s)) return 1;
+  return 1;
+}
+
+export default {
+  name: 'session_watch',
+  // ★ 2026-10-12：**父会话专用**（"我作为父"去挂/摘回灌钩子）⇒ 不给子会话看。
+  expose: 'qq',
+  description:
+    '查看/补挂「回合结束回灌」钩子：默认列出正在盯的子会话、档位与状态；' +
+    'attach=给指定子会话补挂（子会话 id + 父会话 id + 可选 mode）；mode=改已挂盯梢的档位（1/2/3）；detach=取消盯梢。' +
+    '档位：1=只把末段正文回灌父会话并转发到父所在的QQ；2=只把该回合所有正文+报错转发QQ、不进父上下文；3=进父上下文但不唤醒、同时也转发QQ。',
+  inputSchema: {
+    action: { type: 'string', description: 'list（默认）=看状态 / attach=给已存在的子会话补挂 / mode=改档位 / detach=取消盯梢' },
+    child_session_id: { type: 'string', description: 'attach / mode / detach 时要指定的子会话 id' },
+    parent_agent_id: { type: 'string', description: 'attach 时填**父会话 id**（历史上叫"父 agent id"，指的是同一个东西；不填＝用"我自己这个会话"）' },
+    label: { type: 'string', description: 'attach 时的标签，便于记认（可选）' },
+    name: { type: 'string', description: '会话名（可选；只影响转发到 QQ 时行首归属里显示什么，缺省用 label）' },
+    preset: { type: 'string', description: '预设名（可选；同上，归属行显示用）' },
+    workspace: { type: 'string', description: '工作区名（可选；同上，归属行显示用，建议只写目录名）' },
+    mode: { type: 'string', description: '档位：1/一档（默认）=末段回灌父+转QQ；2/二档=只转QQ不进父上下文；3/三档=进父上下文但不唤醒+转QQ' },
+  },
+
+  async run(args = {}, env = {}) {
+    const ctx = env?.ctx ?? null;
+    const root = ctx && typeof ctx === 'object' && ctx.root ? ctx.root : ctx;
+    if (!root?.get) return { ok: false, msg: '拿不到宿主 ctx（需要 expose:\'all\'）' };
+
+    const lib = await loadWatchLib();
+
+    const action = String(args?.action ?? 'list').toLowerCase();
+    const p = (n) => String(n).padStart(2, '0');
+    const fmt = (t) => {
+      if (!t) return '—';
+      const d = new Date(t);
+      return Number.isNaN(d.getTime()) ? '—' : `${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
+    };
+
+    if (action === 'attach' || action === '补挂') {
+      const child = String(args?.child_session_id ?? '').trim();
+      const parent = String(args?.parent_agent_id ?? env?.exec?.agent?.id ?? '').trim();
+      if (!child) return { ok: false, msg: 'attach 需要 child_session_id' };
+      if (!parent) return { ok: false, msg: 'attach 需要 parent_agent_id（不填会用"我自己"）' };
+      const r = await lib.register(root, {
+        parentAgentId: parent,
+        childSessionId: child,
+        label: String(args?.label ?? ''),
+        mode: normMode(args?.mode),
+        // 归属行三件套（可选；不填就只显示短 id）
+        name: String(args?.name ?? args?.label ?? ''),
+        preset: String(args?.preset ?? ''),
+        workspace: String(args?.workspace ?? ''),
+        // ★ QQ 转发用的就是"我自己这个会话"的 sender + replyTarget
+        //   （replyTarget 自带最近 msgId ⇒ 被动优先；插件的 sendMarkdown 自带 markdown 降级链）
+        sender: env?.sender,
+        replyTarget: env?.replyTarget,
+        peerName: String(env?.replyTarget?.name ?? ''),
+      });
+      return { ok: !String(r).startsWith('未挂'), msg: 'attach → ' + r };
+    }
+
+    if (action === 'mode' || action === '档位') {
+      const child = String(args?.child_session_id ?? '').trim();
+      if (!child) return { ok: false, msg: 'mode 需要 child_session_id（先用 list 看）' };
+      // 已挂的直接改；没挂但库里能按短 id 找到也认
+      const hit = lib.listWatching().find((x) => x.childSessionId === child || x.shortId === child.slice(0, 8));
+      const target = hit ? hit.childSessionId : child;
+      const r = await lib.setMode(target, normMode(args?.mode));
+      return { ok: !String(r).includes('没找到'), msg: `mode → ${r}` };
+    }
+
+    if (action === 'detach' || action === '取消') {
+      const child = String(args?.child_session_id ?? '').trim();
+      if (!child) return { ok: false, msg: 'detach 需要 child_session_id' };
+      const hit = lib.listWatching().find((x) => x.childSessionId === child || x.shortId === child.slice(0, 8));
+      const r = await lib.unregister(hit ? hit.childSessionId : child);
+      return { ok: true, msg: r + `（${String(child).slice(0, 14)}…；钩子本身是全局一个，这里只是不再为它回灌/转发）` };
+    }
+
+    // list
+    const items = lib.listWatching();
+    if (!items.length) {
+      return {
+        ok: true,
+        msg: '【回合结束回灌】当前没有盯着任何子会话。\n用 session_create 建会话时会自动挂（可带 mode）；也可以用 attach 给已存在的子会话补挂。',
+      };
+    }
+    const lines = items.map(
+      (x) =>
+        `   · 子 ${x.shortId ?? x.childSessionId.slice(0, 8)}… → 父 ${x.parentShortId ?? x.parentAgentId.slice(0, 8)}…` +
+        `${x.label ? '  [' + x.label + ']' : ''}\n` +
+        `     档位=${modeText(x.mode)}  QQ转发=${x.qqReady ? '就绪' : '未就绪(没拿到 sender/replyTarget)'}` +
+        `${x.peerName ? ' → ' + x.peerName : ''}\n` +
+        `     已结算=${x.turnsSeen} 次  上次回灌=${fmt(x.lastFiredAt)}  最近被引用=${fmt(x.quotedAt)}`,
+    );
+    return { ok: true, msg: `【回合结束回灌】正在盯 ${items.length} 个子会话：\n` + lines.join('\n') };
+  },
+};

package/examples/ext-tools/sessions_list.mjs

@@ -1,180 +1,180 @@
-/**
- * sessions_list.mjs — 列出 DSH 的工作区与各会话（跨工作区 / 跨会话，纯只读）
- *
- * 定位：这是「把子代理那套搬到跨会话级」的第 1 块积木 —— 先能看见，再谈操作。
- * expose: 'all' ⇒ 所有通道（QQ / Web / 终端…）的会话都能用；env.ctx 是宿主的 cordis ctx。
- *
- * 数据来源（都是宿主现成服务，不自己扫盘）：
- *   · ctx.workspaceRegistry  （@deepseek-ai/dsh-workspace）      —— 有序、持久的工作区项目列表
- *   · ctx.sessionQuery       （@deepseek-ai/dsh-session-query）  —— 列会话（最新在前）、过滤、trace
- * ⚠️ 取服务用 cordis 运行时 `ctx.get(name)`，不需要 inject（见 qqbot 的实测经验）；
- *   并且优先用 `ctx.root`（插件根作用域）—— 会话作用域的 ctx 会随会话切换而失效。
- *
- * 失败哲学：任何一个服务缺失都只降级、不报错中断 —— 把"哪些服务可用"如实报出来，
- *          方便在别的 DSH 版本上继续排查。
- */
-const WORKSPACE_SERVICE = 'workspaceRegistry';
-const SESSION_SERVICE = 'sessionQuery';
-/** 探测用的候选服务名（有就报出来，便于后续工具挑正确的那个） */
-const PROBE = [WORKSPACE_SERVICE, SESSION_SERVICE, 'sessions', 'sessionPersistence', 'tools', 'systemPrompt', 'agents', 'goals'];
-
-/** 宽松取字段：宿主返回结构可能随版本变，这里按候选名依次试 */
-function pick(obj, names) {
-  if (!obj || typeof obj !== 'object') return undefined;
-  for (const n of names) {
-    const v = obj[n];
-    if (v !== undefined && v !== null) return v;
-  }
-  const h = obj.header;
-  if (h && typeof h === 'object') {
-    for (const n of names) {
-      const v = h[n];
-      if (v !== undefined && v !== null) return v;
-    }
-  }
-  return undefined;
-}
-
-/** 时间戳 → 本地 MM-dd HH:mm（吃 number / string / Date） */
-function fmtTime(v) {
-  if (v === undefined || v === null) return '';
-  try {
-    const d = v instanceof Date ? v : new Date(typeof v === 'number' ? v : String(v));
-    if (Number.isNaN(d.getTime())) return '';
-    // ⚠️ 用 UTC 字段显示：实测宿主把**本地时间**当 UTC 存
-    //   （createdAt=1791762071432 → UTC 23:41 才与主人的实际时间对得上；按本地读会多 8 小时）。
-    const p = (n) => String(n).padStart(2, '0');
-    return `${p(d.getUTCMonth() + 1)}-${p(d.getUTCDate())} ${p(d.getUTCHours())}:${p(d.getUTCMinutes())}`;
-  } catch { return ''; }
-}
-
-function safeGet(root, name) {
-  try { return root.get(name); } catch { return undefined; }
-}
-
-export default {
-  name: 'sessions_list',
-  description:
-    '列出 DSH 的工作区及其会话（跨工作区 / 跨会话）：默认按最新活跃在前，可用 limit 控制条数，可只看某个工作区。纯只读。',
-  expose: 'all',
-  inputSchema: {
-    workspace: { type: 'string', description: '只看标题/路径里含这段文字的工作区（可选；不填=全部）' },
-    limit: { type: 'integer', description: '每个工作区最多列几个会话（默认 10，上限 50）' },
-    debug: { type: 'boolean', description: 'true=附上服务探测结果与一条原始会话记录（排查用，默认 false）' },
-    full: { type: 'boolean', description: 'true=显示完整 session id 与血缘（parentSession/origin/depth），编排用（默认 false=精简）' },
-  },
-
-  async run(args = {}, env = {}) {
-    const ctx = env?.ctx ?? null;
-    const root = ctx && typeof ctx === 'object' && ctx.root ? ctx.root : ctx;
-    if (!root || typeof root.get !== 'function') {
-      return { ok: false, msg: '拿不到宿主 ctx（env.ctx 缺失或没有 .get）—— 本工具需要 expose:\'all\' 才能在跨通道环境里拿到宿主句柄' };
-    }
-
-    const limit = Math.max(1, Math.min(50, Number(args?.limit) > 0 ? Math.floor(Number(args.limit)) : 10));
-    const filter = String(args?.workspace ?? '').trim().toLowerCase();
-    const lines = [];
-    const notes = [];
-
-    // ── 服务探测（如实报出可用性，缺了也能看出原因）──
-    const probe = {};
-    for (const n of PROBE) {
-      const s = safeGet(root, n);
-      probe[n] = s === undefined || s === null ? null : typeof s;
-    }
-    const reg = safeGet(root, WORKSPACE_SERVICE);
-    const sq = safeGet(root, SESSION_SERVICE);
-
-    // ── ① 工作区列表 ──
-    let projects = [];
-    if (reg && typeof reg.list === 'function') {
-      try { projects = reg.list() || []; } catch (e) { notes.push('workspaceRegistry.list() 抛错: ' + (e?.message ?? e)); }
-    } else if (!reg) {
-      notes.push(`宿主没挂 ${WORKSPACE_SERVICE} 服务（工作区分组不可用）`);
-    }
-    if (!Array.isArray(projects)) projects = [];
-
-    // ── ② 会话列表（sessionQuery 优先）──
-    let sessions = [];
-    if (sq && typeof sq.listSessions === 'function') {
-      try { sessions = (await sq.listSessions()) || []; } catch (e) { notes.push('sessionQuery.listSessions() 抛错: ' + (e?.message ?? e)); }
-    } else if (!sq) {
-      notes.push(`宿主没挂 ${SESSION_SERVICE} 服务（会话查询不可用）`);
-    }
-    if (!Array.isArray(sessions)) sessions = [];
-
-    // 会话按"最新活跃"排序：优先 lastActivity / updatedAt / 创建时间，取不到的排最后
-    const timeOf = (s) => {
-      const t = pick(s, ['lastActivity', 'lastActivityAt', 'updatedAt', 'lastMessageAt', 'createdAt', 'createdAtMs', 'timestamp', 'startedAt']);
-      const d = t instanceof Date ? t : new Date(typeof t === 'number' ? t : String(t ?? ''));
-      return Number.isNaN(d.getTime()) ? 0 : d.getTime();
-    };
-    sessions.sort((a, b) => timeOf(b) - timeOf(a));
-
-    // 归属：一个会话只归给它 cwd 最长的那个工作区（否则父目录会把子目录工作区的会话一起列走）
-    const owners = new Map();
-    for (const s of sessions) {
-      const cwd = String(pick(s, ['cwd', 'workdir', 'directory', 'workingDirectory']) ?? '');
-      if (!cwd) continue;
-      let best = null;
-      for (const p of projects) {
-        const pd = String(pick(p, ['path', 'directory', 'dir', 'cwd']) ?? '');
-        if (!pd) continue;
-        if (cwd === pd) { const hit = pd.length + 10000; if (!best || hit > best.len) best = { len: hit, p }; continue; }
-        if (cwd.startsWith(pd + '\\') || cwd.startsWith(pd + '/')) { const hit = pd.length; if (!best || hit > best.len) best = { len: hit, p }; }
-      }
-      if (best) owners.set(s, best.p);
-    }
-
-    const full = !!args?.full;
-    const line = (s) => {
-      const id = String(pick(s, ['id', 'sessionId', 'sid']) ?? '?');
-      const title = String(pick(s, ['title', 'name', 'summary']) ?? '').slice(0, 40);
-      const live = pick(s, ['live', 'isLive']) ? 'live' : 'persisted';
-      const t = fmtTime(pick(s, ['lastActivity', 'lastActivityAt', 'updatedAt', 'createdAt', 'createdAtMs', 'startedAt']));
-      const short = id.length > 14 && !full ? id.slice(0, 8) + '…' + id.slice(-4) : id;
-      // 血缘（子代理实测建议：跨会话编排必须看到 parent/origin/depth，否则只能另开 debug 手工比对）
-      const origin = pick(s, ['origin']) ?? '';
-      const depth = pick(s, ['delegationDepth']);
-      const parent = String(pick(s, ['parentSession']) ?? '');
-      const lin = origin
-        ? `  origin=${origin}${depth !== undefined ? ' depth=' + depth : ''}${parent ? ' parent=' + (full ? parent : parent.slice(0, 8) + '…') : ''}`
-        : '';
-      return `   · ${t || '        '}  [${live}]  ${short}${title ? '  ' + title : ''}${lin}`;
-    };
-
-    // 有 workspaceRegistry 就按"目录 → 它的会话"分组；否则退化成一张平表
-    if (projects.length) {
-      for (const p of projects) {
-        const ptitle = String(pick(p, ['title', 'name']) ?? '(未命名)');
-        const pdir = String(pick(p, ['path', 'directory', 'dir', 'cwd']) ?? '');
-        if (filter && !(ptitle.toLowerCase().includes(filter) || pdir.toLowerCase().includes(filter))) continue;
-        const mine = sessions.filter((s) => owners.get(s) === p);
-        lines.push(`${ptitle}${pdir ? '  (' + pdir + ')' : ''}   —— ${mine.length} 个会话`);
-        if (!mine.length) lines.push('   · (这个工作区下没有可列的会话)');
-        for (const s of mine.slice(0, limit)) lines.push(line(s));
-        if (mine.length > limit) lines.push(`   … 还有 ${mine.length - limit} 个（用 limit 调整）`);
-      }
-      // 不属于任何工作区的会话
-      const ungrouped = sessions.filter((s) => !owners.get(s));
-      if (ungrouped.length && !filter) {
-        lines.push(`(不属于任何工作区的会话)   —— ${ungrouped.length} 个`);
-        for (const s of ungrouped.slice(0, limit)) lines.push(line(s));
-      }
-    } else {
-      lines.push(`（工作区分组不可用，退化成会话平表）共 ${sessions.length} 个`);
-      for (const s of sessions.slice(0, limit)) lines.push(line(s));
-    }
-
-    // 注（2026-10-12 主人定）：**不再**在首行显示"我 / 父代"。
-    // 会话来源改用另一条更直接的约定：**模拟用户消息的首行直接给出源会话 id**
-    // （见 session_send 与 lib/session_watch_lib.mjs）。
-    const head = `【DSH 工作区与会话】 工作区 ${projects.length} 个 / 会话 ${sessions.length} 个${filter ? `（筛选: ${args.workspace}）` : ''}`;
-    const tail = notes.length ? '\n' + notes.map((n) => '⚠ ' + n).join('\n') : '';
-    const dbg = args?.debug
-      ? '\n— 服务探测: ' + Object.entries(probe).map(([k, v]) => `${k}=${v ?? '✗'}`).join(', ') +
-        '\n— 首条会话原始结构: ' + JSON.stringify(sessions[0] ?? null).slice(0, 600)
-      : '';
-    return { ok: true, msg: [head, ...lines].join('\n') + tail + dbg };
-  },
-};
+/**
+ * sessions_list.mjs — 列出 DSH 的工作区与各会话（跨工作区 / 跨会话，纯只读）
+ *
+ * 定位：这是「把子代理那套搬到跨会话级」的第 1 块积木 —— 先能看见，再谈操作。
+ * expose: 'all' ⇒ 所有通道（QQ / Web / 终端…）的会话都能用；env.ctx 是宿主的 cordis ctx。
+ *
+ * 数据来源（都是宿主现成服务，不自己扫盘）：
+ *   · ctx.workspaceRegistry  （@deepseek-ai/dsh-workspace）      —— 有序、持久的工作区项目列表
+ *   · ctx.sessionQuery       （@deepseek-ai/dsh-session-query）  —— 列会话（最新在前）、过滤、trace
+ * ⚠️ 取服务用 cordis 运行时 `ctx.get(name)`，不需要 inject（见 qqbot 的实测经验）；
+ *   并且优先用 `ctx.root`（插件根作用域）—— 会话作用域的 ctx 会随会话切换而失效。
+ *
+ * 失败哲学：任何一个服务缺失都只降级、不报错中断 —— 把"哪些服务可用"如实报出来，
+ *          方便在别的 DSH 版本上继续排查。
+ */
+const WORKSPACE_SERVICE = 'workspaceRegistry';
+const SESSION_SERVICE = 'sessionQuery';
+/** 探测用的候选服务名（有就报出来，便于后续工具挑正确的那个） */
+const PROBE = [WORKSPACE_SERVICE, SESSION_SERVICE, 'sessions', 'sessionPersistence', 'tools', 'systemPrompt', 'agents', 'goals'];
+
+/** 宽松取字段：宿主返回结构可能随版本变，这里按候选名依次试 */
+function pick(obj, names) {
+  if (!obj || typeof obj !== 'object') return undefined;
+  for (const n of names) {
+    const v = obj[n];
+    if (v !== undefined && v !== null) return v;
+  }
+  const h = obj.header;
+  if (h && typeof h === 'object') {
+    for (const n of names) {
+      const v = h[n];
+      if (v !== undefined && v !== null) return v;
+    }
+  }
+  return undefined;
+}
+
+/** 时间戳 → 本地 MM-dd HH:mm（吃 number / string / Date） */
+function fmtTime(v) {
+  if (v === undefined || v === null) return '';
+  try {
+    const d = v instanceof Date ? v : new Date(typeof v === 'number' ? v : String(v));
+    if (Number.isNaN(d.getTime())) return '';
+    // ⚠️ 用 UTC 字段显示：实测宿主把**本地时间**当 UTC 存
+    //   （createdAt=1791762071432 → UTC 23:41 才与主人的实际时间对得上；按本地读会多 8 小时）。
+    const p = (n) => String(n).padStart(2, '0');
+    return `${p(d.getUTCMonth() + 1)}-${p(d.getUTCDate())} ${p(d.getUTCHours())}:${p(d.getUTCMinutes())}`;
+  } catch { return ''; }
+}
+
+function safeGet(root, name) {
+  try { return root.get(name); } catch { return undefined; }
+}
+
+export default {
+  name: 'sessions_list',
+  description:
+    '列出 DSH 的工作区及其会话（跨工作区 / 跨会话）：默认按最新活跃在前，可用 limit 控制条数，可只看某个工作区。纯只读。',
+  expose: 'all',
+  inputSchema: {
+    workspace: { type: 'string', description: '只看标题/路径里含这段文字的工作区（可选；不填=全部）' },
+    limit: { type: 'integer', description: '每个工作区最多列几个会话（默认 10，上限 50）' },
+    debug: { type: 'boolean', description: 'true=附上服务探测结果与一条原始会话记录（排查用，默认 false）' },
+    full: { type: 'boolean', description: 'true=显示完整 session id 与血缘（parentSession/origin/depth），编排用（默认 false=精简）' },
+  },
+
+  async run(args = {}, env = {}) {
+    const ctx = env?.ctx ?? null;
+    const root = ctx && typeof ctx === 'object' && ctx.root ? ctx.root : ctx;
+    if (!root || typeof root.get !== 'function') {
+      return { ok: false, msg: '拿不到宿主 ctx（env.ctx 缺失或没有 .get）—— 本工具需要 expose:\'all\' 才能在跨通道环境里拿到宿主句柄' };
+    }
+
+    const limit = Math.max(1, Math.min(50, Number(args?.limit) > 0 ? Math.floor(Number(args.limit)) : 10));
+    const filter = String(args?.workspace ?? '').trim().toLowerCase();
+    const lines = [];
+    const notes = [];
+
+    // ── 服务探测（如实报出可用性，缺了也能看出原因）──
+    const probe = {};
+    for (const n of PROBE) {
+      const s = safeGet(root, n);
+      probe[n] = s === undefined || s === null ? null : typeof s;
+    }
+    const reg = safeGet(root, WORKSPACE_SERVICE);
+    const sq = safeGet(root, SESSION_SERVICE);
+
+    // ── ① 工作区列表 ──
+    let projects = [];
+    if (reg && typeof reg.list === 'function') {
+      try { projects = reg.list() || []; } catch (e) { notes.push('workspaceRegistry.list() 抛错: ' + (e?.message ?? e)); }
+    } else if (!reg) {
+      notes.push(`宿主没挂 ${WORKSPACE_SERVICE} 服务（工作区分组不可用）`);
+    }
+    if (!Array.isArray(projects)) projects = [];
+
+    // ── ② 会话列表（sessionQuery 优先）──
+    let sessions = [];
+    if (sq && typeof sq.listSessions === 'function') {
+      try { sessions = (await sq.listSessions()) || []; } catch (e) { notes.push('sessionQuery.listSessions() 抛错: ' + (e?.message ?? e)); }
+    } else if (!sq) {
+      notes.push(`宿主没挂 ${SESSION_SERVICE} 服务（会话查询不可用）`);
+    }
+    if (!Array.isArray(sessions)) sessions = [];
+
+    // 会话按"最新活跃"排序：优先 lastActivity / updatedAt / 创建时间，取不到的排最后
+    const timeOf = (s) => {
+      const t = pick(s, ['lastActivity', 'lastActivityAt', 'updatedAt', 'lastMessageAt', 'createdAt', 'createdAtMs', 'timestamp', 'startedAt']);
+      const d = t instanceof Date ? t : new Date(typeof t === 'number' ? t : String(t ?? ''));
+      return Number.isNaN(d.getTime()) ? 0 : d.getTime();
+    };
+    sessions.sort((a, b) => timeOf(b) - timeOf(a));
+
+    // 归属：一个会话只归给它 cwd 最长的那个工作区（否则父目录 aiwork 会把子目录鲸鱼娘的会话全列走）
+    const owners = new Map();
+    for (const s of sessions) {
+      const cwd = String(pick(s, ['cwd', 'workdir', 'directory', 'workingDirectory']) ?? '');
+      if (!cwd) continue;
+      let best = null;
+      for (const p of projects) {
+        const pd = String(pick(p, ['path', 'directory', 'dir', 'cwd']) ?? '');
+        if (!pd) continue;
+        if (cwd === pd) { const hit = pd.length + 10000; if (!best || hit > best.len) best = { len: hit, p }; continue; }
+        if (cwd.startsWith(pd + '\\') || cwd.startsWith(pd + '/')) { const hit = pd.length; if (!best || hit > best.len) best = { len: hit, p }; }
+      }
+      if (best) owners.set(s, best.p);
+    }
+
+    const full = !!args?.full;
+    const line = (s) => {
+      const id = String(pick(s, ['id', 'sessionId', 'sid']) ?? '?');
+      const title = String(pick(s, ['title', 'name', 'summary']) ?? '').slice(0, 40);
+      const live = pick(s, ['live', 'isLive']) ? 'live' : 'persisted';
+      const t = fmtTime(pick(s, ['lastActivity', 'lastActivityAt', 'updatedAt', 'createdAt', 'createdAtMs', 'startedAt']));
+      const short = id.length > 14 && !full ? id.slice(0, 8) + '…' + id.slice(-4) : id;
+      // 血缘（子代理实测建议：跨会话编排必须看到 parent/origin/depth，否则只能另开 debug 手工比对）
+      const origin = pick(s, ['origin']) ?? '';
+      const depth = pick(s, ['delegationDepth']);
+      const parent = String(pick(s, ['parentSession']) ?? '');
+      const lin = origin
+        ? `  origin=${origin}${depth !== undefined ? ' depth=' + depth : ''}${parent ? ' parent=' + (full ? parent : parent.slice(0, 8) + '…') : ''}`
+        : '';
+      return `   · ${t || '        '}  [${live}]  ${short}${title ? '  ' + title : ''}${lin}`;
+    };
+
+    // 有 workspaceRegistry 就按"目录 → 它的会话"分组；否则退化成一张平表
+    if (projects.length) {
+      for (const p of projects) {
+        const ptitle = String(pick(p, ['title', 'name']) ?? '(未命名)');
+        const pdir = String(pick(p, ['path', 'directory', 'dir', 'cwd']) ?? '');
+        if (filter && !(ptitle.toLowerCase().includes(filter) || pdir.toLowerCase().includes(filter))) continue;
+        const mine = sessions.filter((s) => owners.get(s) === p);
+        lines.push(`${ptitle}${pdir ? '  (' + pdir + ')' : ''}   —— ${mine.length} 个会话`);
+        if (!mine.length) lines.push('   · (这个工作区下没有可列的会话)');
+        for (const s of mine.slice(0, limit)) lines.push(line(s));
+        if (mine.length > limit) lines.push(`   … 还有 ${mine.length - limit} 个（用 limit 调整）`);
+      }
+      // 不属于任何工作区的会话
+      const ungrouped = sessions.filter((s) => !owners.get(s));
+      if (ungrouped.length && !filter) {
+        lines.push(`(不属于任何工作区的会话)   —— ${ungrouped.length} 个`);
+        for (const s of ungrouped.slice(0, limit)) lines.push(line(s));
+      }
+    } else {
+      lines.push(`（工作区分组不可用，退化成会话平表）共 ${sessions.length} 个`);
+      for (const s of sessions.slice(0, limit)) lines.push(line(s));
+    }
+
+    // 注（2026-10-12 主人定）：**不再**在首行显示"我 / 父代"。
+    // 会话来源改用另一条更直接的约定：**模拟用户消息的首行直接给出源会话 id**
+    // （见 session_send 与 lib/session_watch_lib.mjs）。
+    const head = `【DSH 工作区与会话】 工作区 ${projects.length} 个 / 会话 ${sessions.length} 个${filter ? `（筛选: ${args.workspace}）` : ''}`;
+    const tail = notes.length ? '\n' + notes.map((n) => '⚠ ' + n).join('\n') : '';
+    const dbg = args?.debug
+      ? '\n— 服务探测: ' + Object.entries(probe).map(([k, v]) => `${k}=${v ?? '✗'}`).join(', ') +
+        '\n— 首条会话原始结构: ' + JSON.stringify(sessions[0] ?? null).slice(0, 600)
+      : '';
+    return { ok: true, msg: [head, ...lines].join('\n') + tail + dbg };
+  },
+};