@zaofan/dsh-qqbot 1.10.2 → 1.10.3

package/docs/USER-GUIDE.md

@@ -168,6 +168,35 @@ npx @deepseek-ai/dsh web --patch /path/to/dsh-qqbot/cordis.dev.yml
 - **怎么看有没有生效**：`session_watch action=list` 里每条盯梢末尾的 **`最近被引用=月-日 时:分`**，
   就是最近一次引用回流的落点时间；从没被引用过则不显示。
 
+**会话列表 · `/会话列表` 命令**(v1.10.3+): 三步向导选一个会话，**绑定它**并给你一行**可复制的路由模板**。
+不需要是子会话 —— 选一个**任意已有会话**（哪怕是很早以前建、早就休眠的）都能绑。
+
+- **三步**（每步一页 20 个，点字母选；可翻页 / 取消）：
+  1. **工作区** —— 显示**真实文件夹路径**（如 `D:\newwenjianjia\aiwork\鲸鱼娘`）+ 该区会话数，多的在前；
+  2. **该区会话** —— 每行 `🟢/⚪ 标题 · 短id · 创建时间`。**🟢 = 宿主里正在跑，⚪ = 已休眠**（都能绑，休眠的会被唤醒）。
+     ⚠️ **只有正在跑的会话才拿得到标题** —— 宿主**没给已结束会话存标题**，那些只能靠短 id + 时间认；
+  3. **回灌档位** —— `一档 / 二档 / 三档`，含义同 `/子会话`。
+- **选完吐出模板**：
+  ```
+  [s:xxxxxxxx] 在这里写你要发给这个会话的内容
+  ```
+  **复制这行、改掉后半句**，直接发到群里，这句话就被投进那个会话 ——
+  于是你也能**先引用一张图 / 一段别的内容，再补上这行标记**，把图片一起路由过去。
+- **别名**：`/sessionlist`、`/sessions`。
+- **怎么取数的**：直接问宿主服务（`sessionPersistence.list()` 给全部会话 + 真实 `cwd`；
+  `sessions.list()` 给 live 会话的标题）—— **不解压任何 `.zstd`**，所以一秒出结果、也不会卡。
+
+**通用路由 · 正文里带 `[s:会话id]` 就投给那个会话**(v1.10.3+)
+
+- **怎么写**：群里任何一条消息，只要**正文**里有 **`[s:8位短id]`**（或 `【会话 完整id】`），
+  这条消息就会被**投递进那个会话**，标记本身会被自动剥掉、不会出现在对方看到的内容里。
+- **和「引用回流」什么关系**：**回流**是"回"—— 必须**引用子会话发的那条转发消息**；
+  **路由**是"去"—— **任意会话、不用先绑过、不用是子会话**，只要正文里有那个 id。
+- **能带东西**：你的正文 + **这条消息自带的附件**（图片 / 文件会一并进去）——
+  所以"引用一张图 + 一行 `[s:xxxx]`"就能把图路由给对方。
+- **忙 / 闲两种处理**：目标会话**正在跑** → 当**插话**送进去；**空闲** → **唤醒**它。
+- **⚠️ 前提**：目标会话**必须是活着的**（宿主里有它的 agent）。没活着就**静默跳过**，绝不猜、也绝不新建。
+
 ### 🔨 锤子面板: 禁言 / 踢人 (v1.6.2+，2026-10-04 补充)
 
 dock 里的「🔨 锤子」（原「🔇 禁言」）下面分两页：**🔇 禁言**（走官方接口，机器人为管理员即可，无需任何登录）和 **👢 踢人**（**官方至今未开放踢人接口**，改走**你自己的 QQ 号** + 群官网 `qun.qq.com`）。

package/examples/ext-commands//344/274/232/350/257/235/345/210/227/350/241/250.mjs

@@ -0,0 +1,603 @@
+/**
+ * 会话列表.mjs — `/会话列表` 斜杠命令（扩展命令第五套）
+ *
+ * ★ 2026-10-14 主人需求（原话）：
+ *   「再做个 /会话列表 的斜杠命令：先列出工作区选项 → 选了以后再列出会话列表选项（一页不要太多）
+ *     → 再列出回灌模式。选择会话后可以**绑定任何已有会话**，不一定要建立的子会话，能钩子勾住并回灌吗？
+ *     选择成功后，往 qq 发送一条消息模板，该模板的开头包含了会话 id，只要用户复制这条模板、
+ *     修改发送就可以将这段话路由到对应会话 —— 这样就可以引用别的内容发送给路由的会话了（比如图片）」
+ *
+ * 所以本命令干三件事：
+ *   ① 三步向导：**工作区 → 该工作区的会话 → 回灌模式**；
+ *   ② 选完**绑上回灌钩子**（`register()` 的 childSessionId 本就认任意会话，不限"建出来的子会话"）；
+ *   ③ 往 QQ 发一条**可复制的模板**，开头带会话 id ⇒ 复制改内容即可路由到那个会话。
+ *
+ * 路由靠 `tools/lib/session_watch_lib.mjs` 的**通用路由**（正文里出现 `[s:短id]` 或 `【会话 id】` 就投递）。
+ *
+ * ⚠️ 从 `/子会话` 抄来的四条硬经验（都踩过）：
+ *   1. `paint()` 里**必须**做三件事：登记插件卡表、**命令侧自写注册表**、`W.set(cardId, st)`。
+ *      （paint 每次换新 cardId，只在 handler/翻页处登记会漏 ⇒ 选完一屏就报"向导已过期"）
+ *   2. 按钮 id **绝不能带冒号**：插件把 button_data 拆成 `ext:<工具名>:<卡id>:<按钮id>`，
+ *      要求**恰好 3 段**，带冒号会 split 出 4 段被静默丢弃（现象：点了只弹"操作成功"）。
+ *   3. 命令侧 `ctx.caps` 有值、**按钮回调的 ctx 是把能力平铺在自身**（没有 caps 键）
+ *      ⇒ 一律写 `ctx?.caps ?? ctx`。
+ *   4. `keyboardOf` / `regCardSelf` 里的**工具名必须与本文件一致**，否则插件查表查不到。
+ */
+const PAGE = 20;                          // 一页 20 个选项（4 行 × 5 列；第 5 行留给导航）
+const LETTERS = 'ABCDEFGHIJKLMNOPQRST';
+const CARD_EXPIRE_MS = 10 * 60_000;
+const MAX_PAGE_MS = 30 * 60_000;
+const TOOL = '会话列表';                   // ★ 必须与文件名/注册名一致
+
+const STEPS = ['workspace', 'session', 'mode'];
+const STEP_CN = {
+  workspace: '工作区',
+  session: '会话',
+  mode: '回灌模式',
+};
+
+/** 向导状态表（cardId → state） */
+const W = new Map();
+let seq = 0;
+
+/** 字符串兜底 */
+function cn(v) { return v === undefined || v === null ? '' : String(v); }
+function short(s, n) { const t = cn(s).replace(/\s+/g, ' ').trim(); return t.length > n ? t.slice(0, n) + '…' : t; }
+
+/** 诊断日志（沿用 /子会话 的做法：写死路径，排查"点了没反应"最有用） */
+const DIAG_FILE = 'D:/newwenjianjia/aiwork/鲸鱼娘/dshqqbot/.qqbot-extensions/data/会话列表-diag.log';
+async function diag(msg) {
+  try {
+    const { appendFile, mkdir } = await import('node:fs/promises');
+    const { dirname } = await import('node:path');
+    await mkdir(dirname(DIAG_FILE), { recursive: true });
+    await appendFile(DIAG_FILE, `${new Date().toISOString()} ${msg}\n`);
+  } catch { /* 诊断失败绝不影响主流程 */ }
+}
+
+/** 扩展数据根（与 /子会话 同口径） */
+function dataRootOf(ctx) {
+  try {
+    const caps = ctx?.caps ?? ctx ?? {};
+    const p = caps?.paths ?? {};
+    const cand = p.dataRoot ?? caps.dataRoot ?? ctx?.dataRoot ?? '';
+    if (cand) return String(cand);
+  } catch { /* ignore */ }
+  return 'D:/newwenjianjia/aiwork/鲸鱼娘/dshqqbot';
+}
+
+/** 命令侧自写卡表（不依赖插件是否注入 registerInteractionCard） */
+async function regCardSelf(ctx, cardId, buttonIds) {
+  const root = dataRootOf(ctx);
+  if (!root) return false;
+  try {
+    const { readFileSync, writeFileSync, mkdirSync } = await import('node:fs');
+    const { join, dirname } = await import('node:path');
+    const file = join(root, '.qqbot', 'ext-tool-cards.json');
+    let table = { version: 1, cards: [] };
+    try { table = JSON.parse(readFileSync(file, 'utf8')) ?? table; } catch { /* 首次或坏文件 */ }
+    if (!Array.isArray(table.cards)) table.cards = [];
+    const mc = ctx?.message ?? {};
+    const rt = ctx?.replyTarget ?? {};
+    const pe = ctx?.peer ?? {};
+    const scope = cn(rt.scope || ctx?.scope || pe.scope || mc.kind || ((mc.groupOpenid || pe.groupId || pe.peerId) ? 'group' : 'c2c'));
+    const targetId = cn(mc.groupOpenid || rt.targetId || pe.groupId || pe.groupOpenid || pe.peerId || pe.id || mc.senderId);
+    const now = Date.now();
+    table.cards = table.cards.filter((c) => Number(c?.expireAt ?? 0) > now && !(c?.toolName === TOOL && c?.cardId === cardId));
+    table.cards.push({ toolName: TOOL, cardId, buttonIds, scope, targetId, createdAt: now, expireAt: now + CARD_EXPIRE_MS });
+    if (table.cards.length > 200) table.cards = table.cards.slice(-200);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(table, null, 2));
+    return true;
+  } catch { return false; }
+}
+
+/** 发卡（markdown + 按钮键盘）；四级兜底，与 /子会话 同款 */
+async function sendCard(ctx, text, keyboard) {
+  const caps = ctx?.caps ?? ctx ?? {};
+  const mc = ctx?.message ?? {};
+  const rt = ctx?.replyTarget ?? {};
+  const pe = ctx?.peer ?? {};
+  const scope = cn(rt.scope || ctx?.scope || pe.scope || mc.kind || ((mc.groupOpenid || pe.groupId || pe.peerId) ? 'group' : 'c2c'));
+  const gid = cn(mc.groupOpenid || rt.targetId || rt.openid || rt.id || pe.groupId || pe.groupOpenid || (scope === 'group' ? (pe.peerId || pe.id) : '') || '');
+  const uid = cn(mc.senderId || rt.openid || rt.id || pe.openid || pe.userId || '');
+  const api = caps.api;
+  if (keyboard && typeof api === 'function' && (gid || uid)) {
+    const path = gid ? `/v2/groups/${gid}/messages` : `/v2/users/${uid}/messages`;
+    const body = { msg_type: 2, markdown: { content: text }, keyboard, ...(gid ? {} : { content: text }) };
+    try {
+      const r = await api(path, { method: 'POST', body });
+      void diag(`[sendCard] ①api=${JSON.stringify(r ?? null).slice(0, 140)}`);
+      if (r && r.ok !== false) return true;
+    } catch (e) { void diag(`[sendCard] ①抛错=${short(e?.message ?? e, 140)}`); }
+  }
+  try {
+    if (keyboard && typeof caps.markdownCard === 'function') {
+      const r2 = await caps.markdownCard(text, keyboard);
+      if (r2) return true;
+    }
+  } catch { /* ignore */ }
+  try {
+    if (keyboard && typeof ctx?.sender?.sendMarkdownWithKeyboard === 'function') {
+      await ctx.sender.sendMarkdownWithKeyboard(ctx.replyTarget, text, keyboard);
+      return true;
+    }
+  } catch { /* ignore */ }
+  try { if (typeof caps.markdown === 'function' && (await caps.markdown(text))) return true; } catch { /* ignore */ }
+  return false;
+}
+
+/** 按钮（id 不能带冒号） */
+function btn(id, label, style = 1) {
+  return {
+    id,
+    render_data: { label: short(label, 18), visited_label: short(label, 18), style },
+    action: { type: 1, permission: { type: 2 }, data: id, unsupport_tips: '请升级QQ客户端后重试' },
+  };
+}
+
+/** 拼 QQ inline_keyboard；★ 工具名必须是本命令 */
+function keyboardOf(rows, cardId) {
+  return {
+    content: {
+      rows: rows.map((r) => ({ buttons: r.map((b) => ({ ...b, action: { ...b.action, data: `ext:${TOOL}:${cardId}:${b.id}` } })) })),
+    },
+  };
+}
+
+/** 加载回灌库（按 mtime 版本化，改完 lib 热刷即生效） */
+async function loadLib() {
+  const url = new URL(`../tools/lib/session_watch_lib.mjs?v=${Date.now()}`, import.meta.url);
+  return await import(url.href);
+}
+
+/**
+ * 把工作区转义目录名**还原成真实路径**（主人 2026-10-14 要求「显示真实文件夹名字」）。
+ *
+ * 宿主规则（实测推导，见 `~/.dsh/sessions/`）：
+ *   · 整体被 `--` 包起来，首尾各去掉一层；
+ *   · **`-` = 路径分隔符**（`\`）；
+ *   · **`~XXXX` = 一个 UTF-16 码元**（中文/特殊字符都这么转义）；
+ *   · 开头的**单字母 + `-`** 是盘符（如 `D-` ⇒ `D:`）。
+ * 例：`--D-newwenjianjia-aiwork-~9CB8~9C7C~5A18--` ⇒ `D:\newwenjianjia\aiwork\鲸鱼娘`
+ *
+ * ⚠️ 已知不可逆点：原路径里若本来就有 `-`，会被同样当成分隔符（宿主转义时没有区分手段）。
+ */
+function wsPath(dir) {
+  const t = cn(dir).replace(/^--/, '').replace(/--$/, '');
+  const parts = [];
+  let cur = '';
+  let i = 0;
+  while (i < t.length) {
+    const ch = t[i];
+    if (ch === '-') { parts.push(cur); cur = ''; i += 1; continue; }
+    const m = /^~([0-9A-Fa-f]{4})/.exec(t.slice(i, i + 5));
+    if (m) { cur += String.fromCharCode(parseInt(m[1], 16)); i += 5; continue; }
+    cur += ch;
+    i += 1;
+  }
+  parts.push(cur);
+  const segs = parts.filter((p) => p !== '');
+  if (segs.length && /^[A-Za-z]$/.test(segs[0])) segs[0] = `${segs[0]}:`;
+  return segs.join('\\');
+}
+
+/** 卡片上显示用：太长时保留**尾部**（尾部才是能分辨的那几级） */
+function wsDisplay(dir, max = 52) {
+  const full = wsPath(dir);
+  if (full.length <= max) return full;
+  return '…' + full.slice(-(max - 1));
+}
+
+// ── 候选值：**优先问宿主服务**（工作区=会话的 cwd，会话=sessionPersistence.list()，
+//    标题=sessionTitle.get()），拿不到才回退扫盘。主人 2026-10-14 定：
+//    「一定要解析会话吗？不能从 web 界面里拿吗？就像会话排序一样」。──────
+
+const OPT_CACHE = new Map();
+const OPT_TTL_MS = 60 * 1000;         // 候选缓存：60 秒（新会话能及时冒出来）
+const TTL_CACHE = new Map();          // 标题缓存（带时间戳，5 分钟过期）
+const TITLE_TTL_MS = 5 * 60 * 1000;
+let KERNEL = null;
+const CTX_CACHE = { sender: null, replyTarget: null, agentId: '', sessionId: '' };
+
+/** 取宿主服务容器（cordis ctx）：handler 里缓存过就直接用，否则依次看 caps.kernel / kernel */
+function kernelOf(ctx) {
+  if (KERNEL) return KERNEL;
+  const c = ctx ?? {};
+  for (const v of [c?.caps?.kernel, c?.kernel]) if (v) return v;
+  return null;
+}
+
+/**
+ * 从容器里取服务：`kernel.get(name)` 是主路。
+ *
+ * ⚠️ 踩过的坑（2026-10-14 实测报错 `cannot get property "ctx" without inject`）：
+ *   cordis Context 上的 `ctx` / `caps` 等属性是 **getter**，未 inject 时**读取即抛**。
+ *   所以**绝不能**把它们放进数组字面量里"顺手取一下" —— 必须逐个包 try。
+ */
+function svcOf(ctx, name) {
+  const k = kernelOf(ctx);
+  if (!k) return null;
+  try {
+    if (typeof k.get === 'function') {
+      const v = k.get(name);
+      if (v) return v;
+    }
+  } catch { /* ignore */ }
+  for (const key of ['root', 'ctx', 'caps']) {
+    try {
+      const c = k[key];
+      if (!c) continue;
+      const v = typeof c.get === 'function' ? c.get(name) : c[name];
+      if (v) return v;
+    } catch { /* ignore */ }
+  }
+  return null;
+}
+
+/** 会话 id 归一：宿主持久化里带 `session-` 前缀，实时 agent id 不带 —— 两种都留一手 */
+function bareId(id) { const s = cn(id); return s.startsWith('session-') ? s.slice('session-'.length) : s; }
+function fullId(id) { const s = cn(id); return s.startsWith('session-') ? s : `session-${s}`; }
+
+/**
+ * 宿主里**全部**会话（含已结束的）。返回 [{id, cwd, createdAt, sizeBytes}]；
+ * 拿不到服务时返回 null，调用方回退扫盘。
+ */
+async function listAllSessions(ctx) {
+  const sp = svcOf(ctx, 'sessionPersistence');
+  if (!sp || typeof sp.list !== 'function') {
+    void diag(`[svc] 拿不到 sessionPersistence（kernel=${!!kernelOf(ctx)} sp=${!!sp}）`);
+    return null;
+  }
+  try {
+    const r = await sp.list();
+    const arr = Array.isArray(r) ? r : (r && typeof r === 'object' ? Object.values(r) : []);
+    const out = arr.map((it) => {
+      const h = it?.header ?? {};
+      return {
+        id: cn(h.id ?? it?.sessionId ?? it?.id),
+        cwd: cn(h.cwd ?? it?.cwd),
+        createdAt: Number(h.createdAt ?? it?.createdAt ?? 0) || 0,
+        sizeBytes: Number(it?.sizeBytes ?? 0) || 0,
+      };
+    }).filter((x) => x.id);
+    if (out.length === 0) return null;
+    return out;
+  } catch (e) {
+    void diag(`[svc] sessionPersistence.list 抛错=${short(e?.message ?? e, 160)}`);
+    return null;
+  }
+}
+
+/**
+ * live（正在跑）会话表：bare id → {title, cwd}。
+ *
+ * ★ 标题的唯一可靠来源（2026-10-14 实测定案）：
+ *   `sessions.list()` 每一项的 `log`（内存事件数组）里，**最后一个 `session/title` 事件的
+ *   `data.title`**。实测 14 个 live 会话全部取到标题（"做早饭会话问候""早饭群"…）。
+ *
+ * ⚠️ 两条死路（别再试）：
+ *   ① `sessionTitle.get(id)` 在本版宿主**是坏的** —— 抛 `session.snapshotEvents is not a function`；
+ *   ② `sessionPersistence.list()` 的 `header` 里**根本没有 title 字段**
+ *      （只有 version/id/createdAt/cwd/isSeeded/delegationDepth/agentPreset）。
+ *   ⇒ 已结束（非 live）的会话**拿不到标题**，只能显示短 id + 创建时间。
+ */
+async function liveMap(ctx) {
+  const hit = TTL_CACHE.get('live');
+  if (hit && Date.now() - hit.at < 15 * 1000) return hit.v;
+  const out = new Map();
+  const ss = svcOf(ctx, 'sessions');
+  if (ss && typeof ss.list === 'function') {
+    try {
+      const r = await ss.list();
+      const arr = Array.isArray(r) ? r : (r && typeof r === 'object' ? Object.values(r) : []);
+      for (const o of arr) {
+        const id = bareId(o?.id ?? o?.sessionId ?? '');
+        if (!id) continue;
+        let title = '';
+        const lg = o?.log;
+        if (Array.isArray(lg)) {
+          for (let i = lg.length - 1; i >= 0; i--) {
+            if (String(lg[i]?.type ?? '') === 'session/title') {
+              const t = lg[i]?.data?.title;
+              if (typeof t === 'string' && t) { title = t; break; }
+            }
+          }
+        }
+        out.set(id, { title, cwd: cn(o?.header?.cwd ?? '') });
+      }
+    } catch (e) { void diag(`[svc] sessions.list 抛错=${short(e?.message ?? e, 160)}`); }
+  }
+  TTL_CACHE.set('live', { at: Date.now(), v: out });
+  return out;
+}
+
+/** 会话数 / 工作区数 摘要（卡片顶部显示，让人一眼知道规模） */
+let LAST_SCOPE = '';
+
+async function optionsOf(ctx, step, st) {
+  const key = step === 'session' ? `session::${st.picked.workspace?.value ?? ''}` : step;
+  const hit = OPT_CACHE.get(key);
+  if (hit && Date.now() - hit.at < OPT_TTL_MS) return hit.v;
+  const out = await optionsOfRaw(ctx, step, st);
+  if (Array.isArray(out) && out.length > 0) OPT_CACHE.set(key, { at: Date.now(), v: out });
+  return out;
+}
+
+async function optionsOfRaw(ctx, step, st) {
+  try {
+    const lib = await loadLib();
+    if (step === 'workspace') {
+      const all = await listAllSessions(ctx);
+      if (all) {
+        const cnt = new Map();
+        for (const s of all) if (s.cwd) cnt.set(s.cwd, (cnt.get(s.cwd) ?? 0) + 1);
+        const list = [...cnt.entries()].sort((a, b) => b[1] - a[1]);
+        LAST_SCOPE = `宿主 ${all.length} 个会话 / ${list.length} 个工作区`;
+        void diag(`[opts] workspace 走宿主：${LAST_SCOPE}`);
+        return list.map(([cwd, n]) => ({ value: cwd, label: `${wsDisplay(cwd)}  · ${n} 个` }));
+      }
+      const dirs = lib.listWorkspaceDirs();
+      LAST_SCOPE = `扫盘 ${dirs.length} 个工作区（宿主服务不可用）`;
+      void diag(`[opts] workspace 回退扫盘：${dirs.length} 个`);
+      return dirs.map((d) => ({ value: d, label: wsDisplay(wsPath(d)) }));
+    }
+    if (step === 'session') {
+      const ws = st.picked.workspace?.value ?? '';
+      const live = await liveMap(ctx);
+      const all = await listAllSessions(ctx);
+      if (all) {
+        const seen = new Set();
+        const mine = all.filter((s) => {
+          const b = bareId(s.id);
+          if (seen.has(b)) return false;
+          seen.add(b);
+          return !ws || s.cwd === ws;
+        });
+        // 排序：**能叫出名字的（live 有标题）排最前** → 再按创建时间新在前。
+        // 理由：已结束的会话宿主里没有标题（见 liveMap 注释），只能靠时间认。
+        const score = (s) => (live.get(bareId(s.id))?.title ? 1 : 0);
+        mine.sort((a, b) => (score(b) - score(a)) || (b.createdAt - a.createdAt));
+        const shown = mine.slice(0, 80);
+        const named = mine.filter((s) => live.get(bareId(s.id))?.title).length;
+        LAST_SCOPE = `${mine.length} 个会话（${named} 个在线有名）`;
+        void diag(`[opts] session 走宿主 ws=${ws} 命中 ${mine.length}，有名 ${named}，取前 ${shown.length}`);
+        return shown.map((s) => {
+          const info = live.get(bareId(s.id));
+          const t = info?.title ?? '';
+          const when = s.createdAt
+            ? new Date(s.createdAt).toLocaleString('zh-CN', { month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit' })
+            : '—';
+          const tag = info ? '🟢' : '⚪';
+          const id8 = bareId(s.id).slice(0, 8);
+          const head = t ? short(t, 24) : id8;
+          return { value: s.id, label: `${tag} ${head}${t ? ` · ${id8}` : ''} · ${when}` };
+        });
+      }
+      const dirs = lib.listSessionDirs(ws || undefined);
+      void diag(`[opts] session 回退扫盘 ws=${ws} 得到 ${dirs.length} 个`);
+      return dirs.map((s) => {
+        const when = s.mtime ? new Date(s.mtime).toLocaleString('zh-CN', { month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit' }) : '—';
+        const isSub = s.id.startsWith('session-') ? '子会话 ' : '';
+        return { value: s.id, label: `${s.short}  ${isSub}${when}` };
+      });
+    }
+    if (step === 'mode') {
+      return [
+        { value: 1, label: '一档 · 末段回灌 + 转发到 QQ（默认）' },
+        { value: 2, label: '二档 · 全部正文 + 报错 只转 QQ（不进父上下文）' },
+        { value: 3, label: '三档 · 进父上下文但不唤醒 + 转 QQ' },
+      ];
+    }
+  } catch (e) { void diag(`[opts] ${step} 抛错=${short(e?.message ?? e, 160)}`); }
+  return [];
+}
+
+// ── 卡片渲染 ────────────────────────────────────────────────────────────
+
+function cardText(st) {
+  const L = [];
+  L.push(`### 🗂 会话列表 · 第 ${st.stepIdx + 1}/${STEPS.length} 步：${STEP_CN[st.step]}`);
+  L.push('');
+  for (const k of STEPS) {
+    const v = st.picked[k];
+    if (k === 'session') {
+      L.push(`- ${STEP_CN[k]}：${v ? `${short(v.label, 40)}（${short(v.value, 20)}）` : '（待选）'}`);
+    } else {
+      L.push(`- ${STEP_CN[k]}：${v ? v.label : '（待选）'}`);
+    }
+  }
+  L.push('');
+  if (LAST_SCOPE && st.step !== 'mode') L.push(`> ${LAST_SCOPE}`);
+  if (st.step === 'session') L.push('> 🟢=正在跑　⚪=已休眠（都能绑，休眠的会被唤醒）');
+  L.push('');
+  if (st.error) L.push(`⚠️ ${st.error}`, '');
+  const opts = st.options;
+  if (!opts.length) {
+    L.push('这一步没扫到候选 —— 换个工作区试试，或直接说一声让本鲸手工绑。');
+  } else {
+    const total = Math.max(1, Math.ceil(opts.length / PAGE));
+    L.push(`第 ${st.page + 1}/${total} 页（点字母选中）：`);
+    for (let i = 0; i < PAGE; i++) {
+      const idx = st.page * PAGE + i;
+      if (idx >= opts.length) break;
+      L.push(`**${LETTERS[i]}**. ${short(opts[idx].label, 46)}`);
+    }
+  }
+  return L.join('\n');
+}
+
+function cardKeyboard(st) {
+  const rows = [];
+  const opts = st.options;
+  const start = st.page * PAGE;
+  const cur = opts.slice(start, start + PAGE);
+  for (let r = 0; r * 5 < cur.length && r < 4; r++) {
+    const row = [];
+    for (let c = 0; c < 5; c++) {
+      const i = r * 5 + c;
+      if (i >= cur.length) break;
+      row.push(btn(`p${start + i}`, LETTERS[i]));
+    }
+    if (row.length) rows.push(row);
+  }
+  const nav = [];
+  if (st.page > 0) nav.push(btn('prev', '◀ 上一页', 1));
+  if (start + PAGE < opts.length) nav.push(btn('next', '下一页 ▶', 1));
+  rows.push(nav.length ? nav : [btn('noop', '·', 1)]);
+  rows.push([btn('cancel', '取消', 4)]);
+  return keyboardOf(rows, st.cardId);
+}
+
+/** 发/重发当前步骤的卡（★ 三件事全在这里做） */
+async function paint(ctx, st) {
+  st.options = await optionsOf(ctx, st.step, st);
+  if (st.page * PAGE >= st.options.length) st.page = Math.max(0, Math.ceil(st.options.length / PAGE) - 1);
+  st.cardId = `${TOOL}-${++seq}-${Date.now().toString(36)}`;
+  const kb = cardKeyboard(st);
+  const ok = await sendCard(ctx, cardText(st), kb);
+  const caps = ctx?.caps ?? ctx ?? {};
+  const allIds = [...st.options.map((_, i) => `p${i}`), 'prev', 'next', 'cancel', 'noop'];
+  try {
+    if (typeof caps.registerInteractionCard === 'function') {
+      caps.registerInteractionCard({ cardId: st.cardId, buttonIds: allIds, expireAt: Date.now() + CARD_EXPIRE_MS });
+    }
+  } catch { /* ignore */ }
+  try { await regCardSelf(ctx, st.cardId, allIds); } catch { /* ignore */ }
+  W.set(st.cardId, st);
+  if (W.size > 30) {
+    for (const k of [...W.keys()].slice(0, W.size - 30)) if (k !== st.cardId) W.delete(k);
+  }
+  void diag(`[paint] step=${st.step} page=${st.page} 选项=${st.options.length} 发出=${ok ? 'ok' : 'FAIL'} 表=${W.size}`);
+  if (!ok) st.error = '卡片没发出去（当前环境可能不支持富文本卡片）';
+  return ok;
+}
+
+/**
+ * 全部选完 → **绑上回灌钩子** + **发可复制模板**。
+ * 「绑定任何已有会话」这件事本身不需要新能力：`register()` 的 childSessionId 就是"任意会话 id"。
+ */
+async function bindNow(ctx, st) {
+  const lib = await loadLib();
+  const root = KERNEL ?? ctx?.caps?.kernel ?? ctx?.kernel ?? null;
+  const sess = st.picked.session ?? {};
+  const ws = st.picked.workspace?.value ?? '';
+  const mode = Number(st.picked.mode?.value ?? 1);
+  const parentId = CTX_CACHE.agentId || CTX_CACHE.sessionId || '';
+  void diag(`[bind] root=${!!root} parent=${parentId || '-'} child=${short(sess.value, 40)} mode=${mode}`);
+
+  if (!root || typeof root.on !== 'function') {
+    return { text: `⚠️ 拿不到宿主 ctx（需要权限包里的 kernel），这次没绑上。\n会话 id：\`${short(sess.value, 40)}\`` };
+  }
+  let result = '未挂（未知原因）';
+  try {
+    result = await lib.register(root, {
+      parentAgentId: parentId,
+      childSessionId: sess.value,
+      label: short(sess.label, 40),
+      mode,
+      sender: CTX_CACHE.sender,
+      replyTarget: CTX_CACHE.replyTarget,
+      name: short(sess.label, 40),
+      workspace: wsPath(ws),
+    });
+  } catch (e) {
+    result = '绑定抛错：' + short(e?.message ?? e, 120);
+  }
+
+  const sid = sess.value.startsWith('session-') ? sess.value.slice('session-'.length) : sess.value;
+  const key = sid.slice(0, 8);
+  const modeCn = mode === 2 ? '二档' : (mode === 3 ? '三档' : '一档');
+  const L = [];
+  L.push('### ✅ 已选定');
+  L.push('');
+  L.push(`- 会话：\`${short(sess.value, 44)}\``);
+  L.push(`- 工作区：${wsPath(ws)}`);
+  L.push(`- 回灌：**${modeCn}** · ${short(result, 60)}`);
+  L.push('');
+  L.push('**复制下面这行**，把文字改成你要发的内容就能路由给它（图片/引用也可以一起发）：');
+  L.push('');
+  L.push(`\`[s:${key}]\` 在这里写你要发给这个会话的内容`);
+  L.push('');
+  L.push('> 直接发这句就行；本鲸会把标记剥掉、把内容投递进那个会话。');
+  return { text: L.join('\n') };
+}
+
+/** 推进到下一步（或收尾） */
+async function advance(ctx, st) {
+  while (st.stepIdx < STEPS.length && st.picked[STEPS[st.stepIdx]]) st.stepIdx += 1;
+  if (st.stepIdx >= STEPS.length) {
+    W.delete(st.cardId);
+    const r = await bindNow(ctx, st);
+    try { const caps = ctx?.caps ?? ctx ?? {}; if (typeof caps.markdown === 'function') { await caps.markdown(r.text); return ''; } } catch { /* ignore */ }
+    return r.text;
+  }
+  st.step = STEPS[st.stepIdx];
+  st.page = 0;
+  st.error = '';
+  await paint(ctx, st);
+  return '';
+}
+
+export default {
+  name: ['会话列表', 'sessionlist', 'sessions'],  description: '三步向导（工作区 → 该区会话 → 回灌模式）绑定任意已有会话，并给出可复制的路由模板',
+  usage: '/会话列表',
+
+  async handler(ctx) {
+    KERNEL = ctx?.caps?.kernel ?? ctx?.kernel ?? KERNEL;
+    CTX_CACHE.sender = ctx?.sender ?? ctx?.caps?.sender ?? CTX_CACHE.sender;
+    CTX_CACHE.replyTarget = ctx?.replyTarget ?? ctx?.caps?.replyTarget ?? CTX_CACHE.replyTarget;
+    try {
+      const caps = ctx?.caps ?? {};
+      const psid = String(caps.peerSessionId ?? '');
+      if (psid) { CTX_CACHE.agentId = psid; CTX_CACHE.sessionId = psid; }
+      if (!CTX_CACHE.sender) CTX_CACHE.sender = ctx?.bot ?? caps.sender ?? null;
+      void diag(`[handler] kernel=${!!KERNEL} sender=${!!CTX_CACHE.sender} rt=${!!CTX_CACHE.replyTarget} peerSessionId=${psid || '-'}`);
+    } catch { /* ignore */ }
+
+    const st = {
+      picked: {},
+      stepIdx: 0,
+      step: STEPS[0],
+      page: 0,
+      options: [],
+      cardId: '',
+      error: '',
+    };
+    W.set('pending', st);
+    await paint(ctx, st);
+    W.delete('pending');
+    W.set(st.cardId, st);
+    return '';
+  },
+
+  async onInteraction(ctx, info) {
+    const cardId = cn(info?.cardId);
+    const bid = cn(info?.buttonId);
+    const st = W.get(cardId);
+    void diag(`[onInteraction] card=${cardId} btn=${bid} 命中=${!!st} keys=[${[...W.keys()].join(',')}]`);
+    if (!st) return '这个向导已经过期了，重新发一次 /会话列表 吧～';
+    if (st.startedAt && Date.now() - st.startedAt > MAX_PAGE_MS) { W.delete(cardId); return '向导放太久了，重新发一次吧～'; }
+    st.startedAt = st.startedAt ?? Date.now();
+
+    if (bid === 'cancel') { W.delete(cardId); return '已取消，没有绑定任何会话。'; }
+    if (bid === 'noop') return '';
+    if (bid === 'prev' || bid === 'next') {
+      st.page = Math.max(0, st.page + (bid === 'next' ? 1 : -1));
+      const ok = await paint(ctx, st);
+      W.delete(cardId);
+      W.set(st.cardId, st);
+      return ok ? `已翻到第 ${st.page + 1} 页 ✅（新卡片在上面）` : `翻页失败（第 ${st.page + 1} 页）`;
+    }
+    if (/^p\d+$/.test(bid)) {
+      const idx = Number(bid.slice(1));
+      const opt = st.options[idx];
+      if (!opt) return '这个选项没了，翻一页再选～';
+      st.picked[st.step] = opt;
+      st.stepIdx += 1;
+      const done = await advance(ctx, st);
+      return done || '';
+    }
+    return '';
+  },
+};

package/examples/ext-tools/lib/session_watch_lib.mjs

@@ -56,13 +56,13 @@
  * 版本标记：供调用方打印，用来确认**热刷后加载到的到底是哪一版**。
  * 改动本文件时顺手把这个号 +1（或换日期），排查"改了不生效"时一眼就能看出来。
  */
-export const __LIB_VERSION__ = 'lib-v12-20261012-归属行带会话名/预设/工作区';
+export const __LIB_VERSION__ = 'lib-v13-20261014-通用路由([s:短id] / 【会话 id】)+扫盘解析+会话列表';
 
 // ── ★ 2026-10-13 持久化改造（主人指示：**以本地存档为准，别只靠内存**）──────────────
 //   本文件的风格是"用到时动态 import"；这里用**顶层 await** 一次性取到同步版 fs，
 //   后面的 ensureLoaded()（同步读存档）才能被同步函数（如 listWatching）直接调用。
-const { readFileSync, writeFileSync, mkdirSync } = await import('node:fs');
-const { dirname } = await import('node:path');
+const { readFileSync, writeFileSync, mkdirSync, readdirSync, statSync } = await import('node:fs');
+const { dirname, join } = await import('node:path');
 const { fileURLToPath } = await import('node:url');
 
 /**
@@ -297,6 +297,102 @@ export function parseOwner(text) {
  * 短 id → 完整会话 id。**当场查**，不依赖任何持久台账（主人 2026-10-12 明确口径）。
  * 会话注册表的 API 形状随版本变，这里逐种试，全部失败就返回 ''。
  */
+// ── ★ 2026-10-14 主人需求：**通用路由**（正文里带会话 id ⇒ 投递到那个会话）─────────────
+/**
+ * 认两种写法（**不要求行首**，写在句子中间也认）：
+ *   `[s:xxxxxxxx]`       ← 推荐；短 id（uuid 前 8 位）或完整 uuid 都行
+ *   `【会话 xxxxxxxx】`   ← 兼容"直接复制模板再改"
+ *
+ * 与 `routeQuoteBack`（引用回流）的分工：
+ *   · `routeQuoteBack` 只认 `【子会话 xxxx】`，且**必须是已盯梢条目的父会话在说话** —— 语义是"回"；
+ *   · 本组函数认**任意 id**、**不需要绑定**、也不用先盯梢 —— 语义是"去"。
+ */
+const ROUTE_RE = /(?:\[s:|【\s*会话\s*)([0-9a-zA-Z][0-9a-zA-Z-]{2,63})\s*\]?】?/;
+
+/** 从正文里抽路由目标 key（返回 '' = 这不是一条路由消息） */
+export function parseRouteKey(text) {
+  const m = ROUTE_RE.exec(String(text ?? ''));
+  return m ? m[1] : '';
+}
+
+/** 剥掉路由标记 —— 送进目标会话的是"去掉标记后的正文" */
+export function stripRouteMark(text) {
+  return String(text ?? '')
+    .replace(new RegExp(ROUTE_RE.source, 'g'), ' ')
+    .replace(/[ \t]{2,}/g, ' ')
+    .trim();
+}
+
+/** `~/.dsh/sessions` 根目录（Windows 用 USERPROFILE，其余用 HOME） */
+function sessionsRootDir() {
+  const home = String(process.env.USERPROFILE || process.env.HOME || '').trim();
+  return home ? join(home, '.dsh', 'sessions') : '';
+}
+
+/**
+ * **扫盘**把短 id 解析成完整会话 id —— **不依赖对方是否 live**（这是"任何已有会话"的关键）。
+ * 目录形状：`~/.dsh/sessions/<工作区转义名>/<uuid>/`。
+ * @returns {{id: string, workspace: string}} 找不到时 id 为 ''
+ */
+export function findSessionOnDisk(key) {
+  const want = String(key ?? '').toLowerCase().trim();
+  if (!want) return { id: '', workspace: '' };
+  // 已经是完整 uuid ⇒ 直接认
+  if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(want)) {
+    return { id: want, workspace: '' };
+  }
+  if (want.length < 4) return { id: '', workspace: '' };
+  const root = sessionsRootDir();
+  if (!root) return { id: '', workspace: '' };
+  try {
+    for (const ws of readdirSync(root)) {
+      let entries = [];
+      try { entries = readdirSync(join(root, ws)); } catch { continue; }
+      for (const d of entries) {
+        const raw = String(d).toLowerCase();
+        // ⚠️ 会话目录名**可能带前缀**（子会话是 `session-<uuid>`）⇒ 两边都过 shortSessionId 再比，
+        //    否则像 `cf871e99` 这种短 id 会解析失败（本轮实测踩到）。
+        const sh = shortSessionId(String(d)).toLowerCase();
+        if (sh.startsWith(want) || raw.startsWith(want)) return { id: String(d), workspace: String(ws) };
+      }
+    }
+  } catch { /* ignore */ }
+  return { id: '', workspace: '' };
+}
+
+/**
+ * 列会话目录（按 mtime 从新到旧）—— 给「/会话列表」命令用。
+ * @param {string} [workspaceDir] 传了就只列该工作区；不传列全部
+ */
+export function listSessionDirs(workspaceDir) {
+  const root = sessionsRootDir();
+  if (!root) return [];
+  const out = [];
+  const pushWs = (ws) => {
+    const wsDir = join(root, ws);
+    let entries = [];
+    try { entries = readdirSync(wsDir); } catch { return; }
+    for (const d of entries) {
+      const dir = join(wsDir, d);
+      let mtime = 0;
+      try { mtime = statSync(dir).mtimeMs; } catch { /* ignore */ }
+      out.push({ id: String(d), short: shortSessionId(String(d)), workspace: String(ws), mtime });
+    }
+  };
+  try {
+    if (workspaceDir) pushWs(workspaceDir);
+    else for (const ws of readdirSync(root)) pushWs(ws);
+  } catch { /* ignore */ }
+  return out.sort((a, b) => (b.mtime || 0) - (a.mtime || 0));
+}
+
+/** 列出 `~/.dsh/sessions` 下的工作区转义目录名（给向导第一步用） */
+export function listWorkspaceDirs() {
+  const root = sessionsRootDir();
+  if (!root) return [];
+  try { return readdirSync(root).filter((d) => !String(d).startsWith('.')); } catch { return []; }
+}
+
 export function resolveShortId(root, short) {
   const want = String(short ?? '').toLowerCase();
   if (!want) return '';
@@ -558,6 +654,108 @@ function parentEntryOf(sid) {
  * 主人 2026-10-12 口径：**只靠行首的会话信息判断，不依赖台账**。
  * 短 id → 完整 id 用 resolveShortId 当场查；查不到就静默放弃（绝不猜）。
  */
+/**
+ * ★ 2026-10-14 主人需求：**通用路由** —— 把群里这条消息投递给"正文里点名的那个会话"。
+ *
+ * 流程：解析 key → 找会话（**先 live、后扫盘**）→ 投递（忙 `inject` 插话 / 闲 `followup` 唤醒）。
+ * 与 `routeQuoteBack` 的区别：**不限"已盯梢"、不限"父会话在说话"、认任意 id**。
+ *
+ * ★ 附件（2026-10-14 补）：QQ 里**引用图片/文件**时，图**不在正文里** —— 它在入站事件的
+ *   `attachments`（`{contentType,url,filename,asrText}`，见插件 `transport/inbound.ts`）。
+ *   只取文本会把图丢掉，所以这里额外把附件 URL/语音转写一并拼进载荷。
+ * @returns {Promise<{ok: boolean, reason: string, id?: string, workspace?: string, atts?: number}>}
+ */
+async function routeToSession(root, text, ev) {
+  try {
+    const key = parseRouteKey(text);
+    if (!key) return { ok: false, reason: 'no-key' };
+    const body = stripRouteMark(text);
+    // ① 先问宿主（快，只认 live）
+    let fullId = resolveShortId(root, key);
+    let workspace = '';
+    // ② live 查不到 ⇒ **扫盘**（"任何已有会话"就靠这一步）
+    if (!fullId) {
+      const disk = findSessionOnDisk(key);
+      fullId = disk.id;
+      workspace = disk.workspace;
+    }
+    if (!fullId) return { ok: false, reason: 'not-found', id: key };
+    const agents = (() => { try { return root?.get?.('agents'); } catch { return null; } })();
+    let target = (() => { try { return agents?.get?.(fullId) ?? null; } catch { return null; } })();
+    // ③ 没活着 ⇒ 试着唤醒（宿主 agents.resume；拿不到就算了，绝不硬造 agent）
+    if (!target && agents && typeof agents.resume === 'function') {
+      try { target = await agents.resume(fullId); } catch { /* ignore */ }
+    }
+    if (!target) return { ok: false, reason: 'not-live', id: fullId, workspace };
+    // ④ 附件（图片/文件的 URL、语音转写）—— 引用图片时图就在这里
+    const atts = attachmentsOf(ev);
+    if (!body && !atts.length) return { ok: false, reason: 'empty-body', id: fullId, workspace };
+    const lines = ['【群里有人把这条消息路由给你】'];
+    if (body) lines.push(body);
+    if (atts.length) {
+      lines.push('');
+      lines.push('（随消息一起来的附件：）');
+      for (const a of atts) {
+        const kind = String(a?.contentType ?? '');
+        const url = String(a?.url ?? '');
+        const name = String(a?.filename ?? '');
+        const asr = String(a?.asrText ?? '');
+        const tag = /image/i.test(kind) ? '图片' : (/video/i.test(kind) ? '视频' : (/audio|voice/i.test(kind) ? '语音' : (/file|application/i.test(kind) ? '文件' : '附件')));
+        let line = `- ${tag}`;
+        if (name) line += `：${name}`;
+        if (url) line += `\n  ${url}`;
+        if (asr) line += `\n  （语音转写）${asr}`;
+        lines.push(line);
+      }
+    }
+    lines.push('（这是跨会话路由，按需回应即可。）');
+    const msg = userText(lines.join('\n'));
+    if (!isInjectableMessage(msg)) return { ok: false, reason: 'bad-shape', id: fullId, workspace };
+    const busy = (() => {
+      try {
+        const st = String(target.status ?? target.phase ?? '');
+        return st !== '' && st !== 'idle';
+      } catch { return false; }
+    })();
+    if (busy) await target.inject(msg);
+    else await target.followup(msg);
+    return { ok: true, reason: busy ? 'inject' : 'followup', id: fullId, workspace, atts: atts.length };
+  } catch (e) {
+    return { ok: false, reason: 'error:' + (e instanceof Error ? e.message : String(e)) };
+  }
+}
+
+/**
+ * 从入站事件里挖附件（多路兜底，形状照插件 `transport/inbound.ts` 的 `RawAttachment`）。
+ * 只保留有 url / asrText 的项，避免塞一堆空对象过去。
+ */
+export function attachmentsOf(ev) {
+  const cands = [
+    ev?.data?.message?.attachments,
+    ev?.data?.attachments,
+    ev?.message?.attachments,
+    ev?.attachments,
+  ];
+  for (const c of cands) {
+    if (!Array.isArray(c) || c.length === 0) continue;
+    const out = [];
+    for (const a of c) {
+      if (!a || typeof a !== 'object') continue;
+      const url = String(a.url ?? a.URL ?? '').trim();
+      const asr = String(a.asrText ?? a.asr_text ?? '').trim();
+      if (!url && !asr) continue;
+      out.push({
+        contentType: String(a.contentType ?? a.content_type ?? ''),
+        url,
+        filename: String(a.filename ?? a.fileName ?? ''),
+        asrText: asr,
+      });
+    }
+    if (out.length) return out;
+  }
+  return [];
+}
+
 async function routeQuoteBack(root, inboundText) {
   const short = parseOwner(inboundText);
   if (!short) return;
@@ -640,12 +838,25 @@ async function handler(root, session, event) {
 
     // ── 引用回流：只关心**入站 user 消息**，且只在"某个盯梢对象的父会话"里认 ──
     if (type === 'user/message') {
+      const t = textOf(event);
+      // ★ 2026-10-14：**通用路由优先** —— 正文里出现会话 id（`[s:xxx]` / `【会话 xxx】`）就直接投给
+      //   那个会话。**不限已盯梢、不限是不是父会话**（主人要的"任何已有会话都能被点名"）。
+      if (t && parseRouteKey(t)) {
+        const r = await routeToSession(root, t, event);
+        try {
+          root?.logger?.info?.(
+            `[ext-hook:session-watch] 路由 ${r.ok ? '✅' : '✗'} ${r.reason}` +
+            (r.id ? ` → ${shortSessionId(r.id)}…${r.workspace ? `(${r.workspace})` : ''}` : '') +
+            (r.atts ? ` 附件${r.atts}个` : ''),
+          );
+        } catch { /* ignore */ }
+        return;
+      }
       const pe = parentEntryOf(sid);
       if (pe) {
         // ★ 2026-10-13：父会话一发言，就把重启后丢失的 QQ 转发能力补回来。
         //   转发一断，群里就没有带「【子会话 xxxx】」行首的转发消息 ⇒ 引用回流也认不到路。
         hydrateFwd(pe, root, session);
-        const t = textOf(event);
         if (t && OWNER_RE.test(t)) await routeQuoteBack(root, t);
       }
       return;

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 最长的那个工作区（否则父目录 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 };
-  },
-};
+/**
+ * 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 };
+  },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zaofan/dsh-qqbot",
-  "version": "1.10.2",
+  "version": "1.10.3",
   "description": "QQ Bot IM channel plugin for deepseek-harness (dsh)",
   "type": "module",
   "main": "./entry.js",