@zaofan/dsh-qqbot 1.8.6 → 1.9.2

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

@@ -0,0 +1,350 @@
+/**
+ * session_watch_lib.mjs — 「回合结束回灌」的共用实现（放在 tools/lib/ 下，不被当工具扫描）
+ *
+ * 口径**照抄 qqbot 的 passive 收尾**（src/transport/outbound.ts:80-211）：
+ *   · 回合内累积 `assistant/message` 的正文（= 它的 noteGenerated(sessionKey, msgId, text)）
+ *   · `turn/end` 时结算（它的注释原文：「assistant/message 用完即清，turn/end 兜底清」）
+ *   · 取**最后一个正文块**的文本（它收尾时也是"把最后一块复制一份"）
+ *
+ * 本库只做两件事：挂监听、把末段正文回灌给创建者（父 agent）。
+ *
+ * ★ 2026-10-12 定案（主人）：回灌**模拟用户消息**（source.kind='user'）+ **唤醒**父会话。
+ *   `followup` 就是 `inject` 的唤醒档（inject=next-step 不唤醒；followup=next-turn 唤醒），
+ *   所以这里用 followup 即"注入 + 唤醒"。下面的历史分析仍保留，供追溯为什么不再走通知身份。
+ *   原因（实测结论）：`inject` 落 `agent/inbox/spliced **target=next-step**` —— 排队到下次组包、
+ *   **不产生回合**，因此既没有 turn 触发节点、**UI 上也什么都没有**。
+ *   而 `followup` 落 `target=next-turn` ⇒ 产生回合 ⇒ 被渲染成 `TurnTriggerNodeView`：
+ *   那个「白框」。回灌消息的 `source.kind='subagent-settled'` 决定白框标题
+ *   （dsh-client-ui-chat 的 turnTriggerDetails：subagent-settled → 「子任务状态更新」）。
+ *   代价：回灌会**唤醒父会话跑一轮**（烧 token），故正文里加了一行"无需回复"提示。
+ *
+ * ⚠️ 回灌消息的形状**必须**对齐宿主「子会话结算通知」（createSettlementMessage）：
+ *   { id, role:'user', content:[摘要行, 结尾正文引导语, ...正文块],
+ *     source:{ kind:'subagent-settled', form:'notice', summary, senderSessionId } }
+ *
+ * ⚠️ 注入前必须过 isInjectableMessage() 自检（fail-closed）。宿主的顺序是
+ *   **先 append 落盘、后读 `msg.source.kind`**：形状不合法时坏记录已经写进
+ *   `agent/inbox/spliced.data.inserted[]`，之后投影抛错 —— 会话文件从此无法加载。
+ *   事故实例：会话 9643a885 的 seq 4222 曾被写成 `inserted: ["<字符串>"]`。
+ *
+ * 用法：
+ *   import { register } from './lib/session_watch_lib.mjs';
+ *   await register(root, { parentAgentId, childSessionId, label });
+ */
+/**
+ * 版本标记：供调用方打印，用来确认**热刷后加载到的到底是哪一版**。
+ * 改动本文件时顺手把这个号 +1（或换日期），排查"改了不生效"时一眼就能看出来。
+ */
+export const __LIB_VERSION__ = 'lib-v10-20261012-首行给源会话id';
+
+/**
+ * 盯梢名单。**放在 globalThis 上**，不是模块局部变量。
+ *
+ * 原因：`tools/lib/` 的 import 带了 `?v=<mtime>` 版本号（为让热刷生效），
+ * 于是每改一次本文件就会产生一个**新的模块实例**。若名单是模块局部的，
+ * 改一次 lib 就把已登记的盯梢对象全丢了。放 globalThis 上跨实例共享。
+ */
+const WATCHING_KEY = Symbol.for('dsh-qqbot.session-watch.watching');
+const watching = (globalThis[WATCHING_KEY] ??= new Map()); // childSessionId -> { parentAgentId, label, lastText, seen, firedAt }
+
+/** 回灌钩子总开关。false = 正常挂 `session/event` 监听。 */
+const HOOK_DISABLED = false;
+
+/** 监听只装一次（跨模块实例去重）；handler 指针让新实例能立刻接管旧监听。 */
+const HOOK_KEY = Symbol.for('dsh-qqbot.session-watch.hook');
+const HANDLER_KEY = Symbol.for('dsh-qqbot.session-watch.handler');
+let hooked = false;
+
+/**
+ * turn/end 的 data.reason → 人话。
+ * 口径来自 webui 的两条文案（dsh-client-ui-chat/lib/client.js）：
+ *   "message.turnProcess.worked" = 已完成   ← 正常跑完
+ *   "message.stopped"            = 已停止   ← 被停止/中断
+ * 宿主在 index.js:912 把 event.data.reason 记进 inflight.endReason，webui 据此显示。
+ */
+function reasonText(reason) {
+  const r = String(reason ?? '').toLowerCase();
+  if (!r) return '结束';
+  if (/stop|abort|cancel|interrupt|halt/.test(r)) return '已停止';
+  if (/complet|done|finish|success|ok/.test(r)) return '已完成';
+  if (/error|fail/.test(r)) return '出错';
+  return r; // 未知取值就原样带出来，便于以后补映射
+}
+
+/**
+ * `notice` 摘要行的长度上限，与宿主 `dsh-llm` 的 CONTEXT_SUMMARY_MAX_CHARS 保持一致。
+ * 宿主原文注释：producer 的一行说明会写进持久日志，所以要限长。
+ */
+const CONTEXT_SUMMARY_MAX_CHARS = 120;
+
+/** 把摘要行压到上限内（超出用省略号），口径照抄宿主 dsh-llm 的 boundContextSummary()。 */
+function boundContextSummary(summary) {
+  const t = String(summary ?? '');
+  return t.length <= CONTEXT_SUMMARY_MAX_CHARS ? t : `${t.slice(0, CONTEXT_SUMMARY_MAX_CHARS - 1)}…`;
+}
+
+/**
+ * 取会话短 id 用于显示。
+ * ⚠️ 子会话 id 形如 `session-f147236a-…`，直接 slice(0,8) 只会得到无意义的 `session-`。
+ * 所以先剥掉 `session-` 前缀再截断。
+ */
+export function shortSessionId(id) {
+  const s = String(id ?? '');
+  return (s.startsWith('session-') ? s.slice(8) : s).slice(0, 8);
+}
+
+/**
+ * 把 `turn/end` 的 reason 归一成字符串。
+ *
+ * ⚠️ 2026-10-12 实测：`event.data.reason` **不是字符串而是对象**，形如
+ *   `{kind:'completed'}` 或 `{kind:'aborted', reason:{kind:'user'}}`。
+ * 旧代码直接 `String(reason)` ⇒ 摘要行里出现 `回合[object object]（reason=[object Object]）`。
+ * 本函数优先取最外层的 `kind`，没有就下钻内层 `reason`，都不是才退回 String()。
+ */
+export function reasonKind(value) {
+  if (value === null || value === undefined) return '';
+  if (typeof value === 'string') return value;
+  if (typeof value === 'object') {
+    if (typeof value.kind === 'string' && value.kind) return value.kind;
+    if (value.reason !== undefined && value.reason !== value) return reasonKind(value.reason);
+    if (typeof value.status === 'string' && value.status) return value.status;
+    if (typeof value.stopReason === 'string' && value.stopReason) return value.stopReason;
+  }
+  return String(value);
+}
+
+/**
+ * 把各种可能的 content 形状压成纯文本。
+ *
+ * ★ 2026-10-12 修（主人实测）：**只取 `type === 'text'` 的正文块**。
+ *   早先的过滤条件是 `x.type === 'text' || typeof x.text === 'string'` ——
+ *   而 **reasoning（思考）块同样带 `.text` 字符串**，于是思考被一起并进来，
+ *   回灌的"结尾正文"里冒出一整段英文思考（子会话 3bee83ac 那次实测）。
+ *   reasoning / tool-call 等块一律丢弃。
+ */
+function asText(c) {
+  if (typeof c === 'string') return c.trim();
+  if (Array.isArray(c)) {
+    return c
+      .filter((x) => x && x.type === 'text' && typeof x.text === 'string')
+      .map((x) => String(x.text))
+      .join('\n')
+      .trim();
+  }
+  if (c && typeof c === 'object') {
+    if (c.type === 'reasoning') return '';          // 思考块不算正文
+    if (typeof c.text === 'string') return String(c.text).trim();
+    if (Array.isArray(c.blocks)) return asText(c.blocks);  // 有些版本正文藏在 blocks 里
+  }
+  return '';
+}
+
+/** 从事件里尽力抽正文（assistant/message 的形状随版本变，逐层试） */
+function textOf(ev) {
+  const cands = [
+    ev?.data?.message?.content,
+    ev?.data?.content,
+    ev?.message?.content,
+    ev?.data?.text,
+    ev?.text,
+    ev?.data?.message?.text,
+  ];
+  for (const c of cands) {
+    const t = asText(c);
+    if (t) return t;
+  }
+  return '';
+}
+
+/** 兜底：直接从会话实例取"最后一条助手消息"的正文 */
+function lastAssistantText(root, sid) {
+  try {
+    const sess = root.get('sessions')?.get?.(sid);
+    const msgs = sess?.deriveMessages?.() ?? [];
+    for (let i = msgs.length - 1; i >= 0; i -= 1) {
+      const m = msgs[i];
+      const role = String(m?.role ?? m?.type ?? '');
+      if (role.includes('assistant')) {
+        const t = asText(m?.content);
+        if (t) return t;
+      }
+    }
+  } catch { /* ignore */ }
+  return '';
+}
+
+/**
+ * 注入前的形状自检（fail-closed）。
+ *
+ * 复刻宿主 v4 的准入条件（dsh-session-persistence-jsonl/lib/worker.cjs）：
+ *   ① `agent/inbox/spliced` 的 `inserted[]` 每项必须 `isSessionFormatJsonObject`；
+ *   ② 每项的 `source` 必须是对象、`kind` 为非空字符串、且 !== 'plugin'
+ *      （源码原文：`format v4 message requires a producer-owned source kind`）。
+ *
+ * 为什么必须自检而不是交给 inject()：宿主是**先 append 落盘、后读 source.kind** 的顺序。
+ * 传进非对象时，坏记录已经写进 `inserted[]`，之后投影抛错 —— 文件从此无法加载。
+ * 事故实例：会话 9643a885 的 seq 4222 被写成 `inserted: ["<字符串>"]`，整个会话读不出来。
+ */
+export function isInjectableMessage(m) {
+  if (!m || typeof m !== 'object' || Array.isArray(m)) return false;
+  if (typeof m.role !== 'string' || !m.role) return false;
+  if (!Array.isArray(m.content) || m.content.length === 0) return false;
+  const src = m.source;
+  if (!src || typeof src !== 'object' || Array.isArray(src)) return false;
+  if (typeof src.kind !== 'string' || !src.kind || src.kind === 'plugin') return false;
+  return true;
+}
+
+/**
+ * 构造一条「子会话结算通知」形状的回灌消息（纯函数，便于单测）。
+ *
+ * 形状**对齐宿主** dsh-subagent/lib/index.js 的 `createSettlementMessage()`：
+ *   source : { kind:'subagent-settled', form:'notice', summary, senderSessionId }
+ *   content: [ 摘要行, 结尾正文引导语, ...正文块 ]，role 由 createUserMessage 固定为 'user'
+ *
+ * 采用宿主形状的三个理由：
+ *   ① kind 是宿主自有的 producer-owned 值，不再冒充真人 user 发言；
+ *   ② senderSessionId 明确归属到具体子会话，UI 侧归进**子任务**那条通道而不是混进
+ *      用户真实发言流里 —— 这与上一轮「回灌插错位置」是同一类隐患；
+ *      ⚠️ 更正：dsh-client-ui-chat 的 turnTriggerDetails 里 `subagent-settled` 对应的是
+ *      「**子任务状态更新**」（icon subagent）；「收到任务消息」是 `agent-message`。本条注释早先写错；
+ *   ③ summary 与宿主同口径（dsh-llm CONTEXT_SUMMARY_MAX_CHARS = 120）。
+ *
+ * @param {{sessionId?: string, label?: string, rawReason?: string, text?: string}} input
+ * @returns 可直接交给 agent.inject() 的完整消息对象
+ */
+export function buildSettlementNotice(input = {}) {
+  const sid = String(input.sessionId ?? '');
+  const label = String(input.label ?? '');
+  const rawReason = String(input.rawReason ?? '');
+  const stage = reasonText(rawReason);
+  const summary = boundContextSummary(
+    `子会话${label ? '「' + label + '」' : ''} ${shortSessionId(sid)}… 回合${stage}` +
+    `${rawReason && rawReason !== stage ? '（reason=' + rawReason + '）' : ''}`,
+  );
+  return {
+    id: (globalThis.crypto?.randomUUID?.() ?? ('inj-' + Date.now().toString(36) + Math.random().toString(36).slice(2, 8))),
+    role: 'user',
+    content: [
+      // ★ 主人 2026-10-12 定：模拟用户消息的**首行直接给出源会话 id**（完整 id）。
+      { type: 'text', text: '【来自会话 ' + sid + '】' },
+      { type: 'text', text: summary },
+      { type: 'text', text: '它的结尾正文：' },
+      { type: 'text', text: String(input.text ?? '') },
+      { type: 'text', text: '（这是子会话的自动回灌，父会话无需回复。）' },
+    ],
+    // ★ 2026-10-12 主人定案：回灌**一律模拟用户消息**（source.kind='user'），
+    //   不再伪装成子会话结算通知 / 系统消息 / 开发者消息。
+    //   理由：那些身份要么被宿主拒收（system/developer 需要 turn+step 且非 JSON 可序列化即被丢），
+    //   要么在 UI 上归属混乱；统一成用户消息最简单、最可预期。
+    source: { kind: 'user' },
+  };
+}
+
+async function handler(root, session, event) {
+  try {
+    const sid = String(session?.id ?? session?.sessionId ?? '');
+    const w = sid ? watching.get(sid) : null;
+    if (!w) return;
+    const type = String(event?.type ?? '');
+
+    // 累积（对应 qqbot 的 noteGenerated）
+    if (type === 'assistant/message') {
+      const t = textOf(event);
+      if (t) w.lastText = t;
+      return;
+    }
+    if (type !== 'turn/end') return;
+
+    // 结算：优先用累积到的那一段；没有再从会话实例兜底取
+    let text = w.lastText;
+    w.lastText = ''; // ★ 取走即清空：否则"只有工具调用、没有正文"的回合会重复回灌上一回合的正文
+    if (!text) text = lastAssistantText(root, sid);
+    w.seen = (w.seen ?? 0) + 1;
+    w.lastReason = reasonKind(event?.data?.reason ?? event?.data?.status ?? event?.data?.stopReason);
+    if (!text) return; // 空回合（只有工具调用/无正文）→ 不回灌
+    // ★ 去重：兜底路径可能又取到"上一次已经灌过"的那段正文，内容相同就不再灌第二遍
+    if (text === w.lastSent) return;
+    w.lastSent = text;
+
+    const agents = root.get('agents');
+    const parent = agents?.get?.(w.parentAgentId) ?? null;
+    if (!parent) return; // 父不在（不 live）→ 静默跳过，不制造错误
+
+    const rawReason = reasonKind(event?.data?.reason ?? event?.data?.status ?? event?.data?.stopReason);
+    const candidate = buildSettlementNotice({ sessionId: sid, label: w.label, rawReason, text });
+    if (!isInjectableMessage(candidate)) return; // 自检不过 → 宁可这次不回灌
+    try {
+      // ★ 2026-10-12 定案（照抄 qqbot 插件的入站模式 —— dist/features/qq-user-questions.js:646）：
+      //     「忙时插话、空闲唤醒」
+      //       · 父会话**回合进行中(忙)** → `agent.inject`
+      //         = 宿主 `send(msg,'next-step',wakeup:false)`：进当前回合的下一个轮次边界，
+      //           她本轮就读到了；**不排进"下一回合"队列** ⇒ **不会挂到输入框**。
+      //       · 父会话**空闲** → `agent.followup` 唤醒它接着处理。
+      //   ⚠️ 之前无论忙闲都用 followup → 忙时落成 `target=next-turn` 排队消息，
+      //      前端把它当"待发送输入"显示在输入框上方（主人实测）。这才是那个毛病的根因。
+      const busy = (() => {
+        try {
+          const st = String(parent.status ?? parent.phase ?? '');
+          return st !== '' && st !== 'idle';
+        } catch { return false; }
+      })();
+      if (busy) await parent.inject(candidate);   // 插话（不唤醒、不排队、不进输入框）
+      else await parent.followup(candidate);      // 空闲 → 唤醒
+      w.firedAt = Date.now();
+    } catch { /* 注入失败 → 静默；监听里绝不抛，免得影响宿主事件链 */ }
+  } catch { /* 监听里绝不抛，免得影响宿主事件链 */ }
+}
+
+function installHook(root) {
+  if (HOOK_DISABLED) return;
+
+  // ① 把「当前实例的 handler」发布到 globalThis：已装好的那个监听会转发到最新实例，
+  //    所以改完 lib 热刷后新代码立刻接管，不必重挂监听。
+  globalThis[HANDLER_KEY] = (session, event) => { void handler(root, session, event); };
+
+  // ② 监听全局只装一次。lib 带 mtime 版本号加载，改一次就换一个模块实例；
+  //    若各实例各自 root.on 一遍，同一个 turn/end 会被回灌多次。
+  if (globalThis[HOOK_KEY]) { hooked = true; return; }
+  try {
+    // 与 qqbot 的 mc_tell 同款：挂在插件根 ctx 上，事件回调 (session, event)。
+    // 注意：回调里通过 globalThis 取 handler，永远调用最新那一版。
+    root.on('session/event', (session, event) => {
+      const h = globalThis[HANDLER_KEY];
+      if (typeof h === 'function') h(session, event);
+    });
+    globalThis[HOOK_KEY] = true;
+    hooked = true;
+  } catch { hooked = false; }
+}
+
+/**
+ * 登记一个"要盯着的子会话"。
+ * @returns 人话描述（挂成功/失败原因），不抛错。
+ */
+export async function register(root, opts = {}) {
+  const parentAgentId = String(opts.parentAgentId ?? '').trim();
+  const childSessionId = String(opts.childSessionId ?? '').trim();
+  const label = String(opts.label ?? '').trim();
+  if (!parentAgentId || !childSessionId) return '未挂（缺 parentAgentId 或 childSessionId）';
+  if (!root || typeof root.on !== 'function') return '未挂（root 不支持 .on）';
+  installHook(root);
+  if (HOOK_DISABLED) return '未挂（回灌钩子当前被 HOOK_DISABLED 主动关闭，属预期；恢复见 installHook 注释）';
+  if (!hooked) return '未挂（root.on 抛错）';
+  watching.set(childSessionId, { parentAgentId, label, lastText: '', seen: 0, firedAt: 0 });
+  return `已挂（子=${shortSessionId(childSessionId)}… → 父=${shortSessionId(parentAgentId)}…；回合结束即回灌末段正文）`;
+}
+
+/** 给别的工具（如 session_watch 状态查询）读当前盯着的清单 */
+export function listWatching() {
+  return [...watching.entries()].map(([sid, w]) => ({
+    childSessionId: sid,
+    shortId: shortSessionId(sid),
+    parentAgentId: w.parentAgentId,
+    parentShortId: shortSessionId(w.parentAgentId),
+    label: w.label,
+    hasText: !!w.lastText,
+    turnsSeen: w.seen ?? 0,
+    lastFiredAt: w.firedAt ?? 0,
+  }));
+}

package/examples/ext-tools/session_create.mjs

@@ -0,0 +1,201 @@
+/**
+ * session_create.mjs — 创建**子会话**（跨工作区/跨会话），走宿主 sessionController
+ *
+ * ⚠️ 本文件的来历：前面几个版本（v1~v5）都在绕路 —— 试图用 `ctx.sessions.create()` +
+ *   `ctx.agents.create()` 手工拼一个会话，结果一路撞墙（session 已存在 / agent id 不等于 session id /
+ *   选项读不到）。**权威范例是记忆插件 dsh-auto-memory**：它用宿主服务 `sessionController` 建会话，
+ *   源码原文（@a9i5k4/dsh-auto-memory/lib/index.js）：
+ *     created = await sc.create({
+ *       ...(workspaceId ? { workspaceId } : { cwd }),
+ *       ...(agentPreset ? { agentPreset } : {}),
+ *     })
+ *     const newId = String(created && (created.sessionId || created.id) || '')
+ *   两个坑（同文件注释）：
+ *     ① create() **只在传 workspaceId 时**才 attachSession；只传 cwd 仅设工作目录 → 会话落"未分组"；
+ *     ② 权限不在 create 里，走 `permissionPresets`（current 读 / set 写），完全权限预设名 = danger-full-access。
+ *
+ * ⚠️ 主人定（2026-10-12）：**派活是"父"的职责** ⇒ 本工具只在 QQ 会话注册（`expose: 'qq'`），
+ *   子会话看不到，免得无限套娃。回执通道是 `session_send`（那个对子会话开放）。
+ */
+import { statSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * 带版本号地加载共用库 —— **必须这么加载**。
+ *
+ * 背景：插件的 extension-store 只给**工具文件本身**的 import 加了 `?v=<mtime>`
+ * 来绕过 ESM 模块缓存；工具**内部**再 import 别的文件时，裸路径会被模块缓存永久命中。
+ * 后果：改了 `tools/lib/` 下的文件，热刷（tools_reload）**不会生效**，只有重启宿主才行 ——
+ * 这曾导致"以为改好了、实际跑的还是旧代码"（2026-10-12 实测踩到）。
+ */
+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}`);
+}
+
+export default {
+  name: 'session_create',
+  // ★ 2026-10-12 主人定：父会话专用 ⇒ 只在 QQ 会话注册（子会话不可见）。
+  expose: 'qq',
+  description:
+    '创建对话（跨工作区/跨会话）：可指定工作区（目录或标题片段，默认同工作区）、可给初始任务、默认完全权限；建好后自动给它挂"回合结束把末段正文回灌创建者"的钩子。',
+  inputSchema: {
+    task: { type: 'string', description: '初始任务文本（会自动送进新会话；不填=只建不派活）' },
+    workspace: { type: 'string', description: '目标工作区：目录路径片段或标题片段（可选；默认同工作区）' },
+    cwd: { type: 'string', description: '工作目录（可选；等价于指定工作区）' },
+    name: { type: 'string', description: '标签/备注（可选，建好后写进会话标题）' },
+    preset: { type: 'string', description: '权限预设（默认 danger-full-access 完全权限）' },
+agent_preset: { type: 'string', description: '人设（agent 预设）：收**任何字符** —— 先按预设名（显示名）反查 id，再按 id 匹配（忽略大小写；唯一子串也认）。如「标准模式」/standard（显示名与 id 都认）。不填=继承发起方自己' },
+    wake: { type: 'boolean', description: 'true=建完立刻跑一轮（默认 false=只追加不唤醒，省 token）' },
+    watch: { type: 'boolean', description: 'true=挂"回合结束回灌"钩子（默认 true）' },
+  },
+
+  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 me = String(env?.exec?.agent?.id ?? env?.exec?.sessionId ?? '').trim();
+    const svc = (k) => { try { return root.get(k); } catch { return undefined; } };
+    const sc = svc('sessionController');
+    if (!sc || typeof sc.create !== 'function') {
+      return { ok: false, msg: '宿主没有可用的 sessionController.create()（跨会话创建就靠它；请确认 dsh web 宿主版本）' };
+    }
+    const out = [`我=${me.slice(0, 8)}…  服务: sessionController ✓`];
+
+    // ── 解析目标工作区 → workspaceId（关键：只给 cwd 会落"未分组工作区"）──
+    const wantWs = String(args?.workspace ?? args?.cwd ?? '').trim();
+    let workspaceId = '';
+    let wsPath = '';
+    let myCwd = '';
+    try {
+      const reg = svc('workspaceRegistry');
+      const list = (reg?.list?.() ?? []).filter(Boolean);
+      if (me) {
+        const mine = list.find((w) => (w.sessionIds ?? []).includes(me));
+        myCwd = String(mine?.path ?? '');
+      }
+      const key = wantWs || myCwd;
+      if (key) {
+        const k = key.toLowerCase();
+        const hit = list.find((w) => String(w?.path ?? '').toLowerCase().includes(k)) ??
+                    list.find((w) => String(w?.title ?? '').toLowerCase().includes(k));
+        if (hit) { workspaceId = String(hit.id ?? ''); wsPath = String(hit.path ?? ''); }
+        else if (wantWs) out.push(`⚠ 没匹配到工作区「${wantWs}」，改用 cwd 直传（会落"未分组"，可能不是你要的）`);
+      }
+      out.push(`工作区: ${workspaceId ? wsPath + '  (id=' + workspaceId.slice(0, 8) + '…)' : '(未指定，继承宿主默认)'}`);
+    } catch (e) { out.push('工作区解析失败(继续): ' + String(e?.message ?? e)); }
+
+    // ── ① 建会话 ──
+    // ⚠️ 2026-10-12 实测纠错：`agentPreset` 是 **agent 预设**（standard / whale-girl / softwhale…），
+    //   **不是权限预设** —— 传 'danger-full-access' 会报 `Unknown agent preset: danger-full-access`。
+    //   权限是另一条链：permissionPresets.set(session, <权限预设名>)，完全权限 = 'danger-full-access'。
+    let myPreset = 'standard';
+    try {
+      const list = (await svc('sessionQuery')?.listSessions?.()) ?? [];
+      const mine = list.find((s) => String(s?.header?.id ?? s?.id) === me);
+      if (mine?.header?.agentPreset) myPreset = String(mine.header.agentPreset);
+    } catch { /* ignore */ }
+    // ★ 2026-10-12 主人定：人设参数收**任何字符** —— 先按「预设名」反查 id，再按「id」匹配。
+    //   匹配顺序与容忍度全在 lib/preset_resolve.mjs（按 mtime 版本化加载 ⇒ 改库不必给工具改名）。
+    const wantPreset = String(args?.agent_preset ?? '').trim();
+    let agentPreset = wantPreset || myPreset;
+    if (wantPreset) {
+      try {
+        const pu = new URL('./lib/preset_resolve.mjs', import.meta.url);
+        let pv = '0';
+        try { pv = String(statSync(fileURLToPath(pu)).mtimeMs); } catch { /* ignore */ }
+        const presetLib = await import(pv === '0' ? pu.href : pu.href + '?v=' + pv);
+        const r = await presetLib.resolvePreset(root, wantPreset);
+        if (r && r.error) return { ok: false, msg: out.join('\n') + '\n❌ 人设解析失败: ' + r.error };
+        if (r && r.id) {
+          agentPreset = r.id;
+          if (r.via !== 'id') out.push('人设: 「' + wantPreset + '」→ id=' + agentPreset + '（按 ' + r.via + ' 匹配）');
+        }
+      } catch (e) { out.push('人设解析跳过(沿用原值): ' + String(e?.message ?? e).slice(0, 110)); }
+    }
+    const permPreset = String(args?.preset ?? 'danger-full-access').trim() || 'danger-full-access';
+    out.push('agent 预设 = ' + agentPreset + (wantPreset ? '' : '（继承我自己）') + '  权限预设 = ' + permPreset);
+    let sid = '';
+    let created = null;
+    try {
+      const opts = {};
+      if (workspaceId) opts.workspaceId = workspaceId;
+      else if (wantWs || myCwd) opts.cwd = wantWs || myCwd;
+      opts.agentPreset = agentPreset;
+      created = await sc.create(opts);
+      sid = String(created?.sessionId ?? created?.id ?? '');
+      out.push(`① sessionController.create → ${sid ? 'ok ' + sid : '返回里没 sessionId/id（键: ' + Object.keys(created ?? {}).join(',') + '）'}`);
+    } catch (e) {
+      out.push('① sessionController.create 抛错: ' + String(e?.message ?? e));
+      return { ok: false, msg: out.join('\n') };
+    }
+    if (!sid) return { ok: false, msg: out.join('\n') + '\n（没拿到会话 id，中止）' };
+
+    // ── ② 权限：完全权限（走 permissionPresets，不在 create 里）──
+    try {
+      const pp = svc('permissionPresets');
+      if (pp && typeof pp.set === 'function') {
+        let sess = null;
+        try { sess = svc('sessions')?.get?.(sid) ?? null; } catch { /* ignore */ }
+        if (!sess) {
+          try { const r = await sc.resolveAgent(sid); sess = r?.agent?.session ?? null; } catch { /* ignore */ }
+        }
+        if (sess) { await pp.set(sess, permPreset); out.push('② 权限预设 → ' + permPreset); }
+        else out.push(`② 权限预设跳过（没有 live session 对象；会话默认权限等它首次唤醒后由 preset=${preset} 生效）`);
+      } else {
+        out.push('② permissionPresets 服务不可用（跳过；create 时已带 agentPreset）');
+      }
+    } catch (e) { out.push('② 权限设置失败(继续): ' + String(e?.message ?? e)); }
+
+    // ── ③ 初始任务 ──
+    const task = String(args?.task ?? '').trim();
+    if (task && typeof sc.prompt === 'function') {
+      // ✅ 权威形状（dsh-api-session-controller/lib/types/types.d.ts:319 SessionPromptRequest）：
+      //   { requestId, sessionId, mode: 'queue'|'steer', content: PromptContentPart[], clientTimeZone? }
+      //   之前传 {sessionId, text} 全错 —— content 位置放字符串导致内部解析炸 `signal.throwIfAborted`。
+      //   mode='queue' 排队（不打断）；mode='steer' 插话（等于 qqbot 的 interject）。
+      const rid = (globalThis.crypto?.randomUUID?.() ?? ('req-' + Date.now().toString(36) + Math.random().toString(36).slice(2, 8)));
+      const body = [{ type: 'text', text: task }];
+      const sig = new AbortController().signal;
+      // ★ 关键：signal 是**独立的第二参数**（同文件 page(request, signal) / list(signal) / control(signal) 同款），
+      //   塞进 request 里它读不到 → 报 `undefined.throwIfAborted`。
+      const req = { requestId: rid, sessionId: sid, mode: 'queue', content: body };
+      const shapes = [
+        ['(request, signal)  mode=queue', () => sc.prompt(req, sig)],
+        ['(request)         mode=queue', () => sc.prompt(req)],
+        ['(request, signal)  mode=steer', () => sc.prompt({ ...req, mode: 'steer' }, sig)],
+      ];
+      let via = '';
+      const errs = [];
+      for (const [lb, fn] of shapes) {
+        try { await fn(); via = lb; break; } catch (e) { errs.push(lb + '→' + String(e?.message ?? e).slice(0, 60)); }
+      }
+      out.push('③ 初始任务 → ' + (via ? 'ok（形式: ' + via + '）' : '全部形式被拒: ' + errs.join(' | ')));
+    } else if (task) {
+      out.push('③ 初始任务跳过（sessionController 没有 prompt()）');
+    }
+
+    // ── ④ 标题（可选）──
+    const label = String(args?.name ?? '').trim();
+    if (label && typeof sc.rename === 'function') {
+      try { await sc.rename({ sessionId: sid, title: label }); out.push('④ 标题 → ' + label); }
+      catch (e) { out.push('④ 标题设置失败: ' + String(e?.message ?? e).slice(0, 80)); }
+    }
+
+    // ── ⑤ 回合结束回灌钩子 ──
+    let watchMsg = '未挂（watch=false）';
+    if (args?.watch !== false) {
+      try {
+        const w = await loadWatchLib();
+        watchMsg = await w.register(root, { parentAgentId: me, childSessionId: sid, label }) +
+          '  [lib=' + (w.__LIB_VERSION__ ?? '未知(旧版无版本号)') + ']';
+      } catch (e) { watchMsg = '未挂（' + String(e?.message ?? e) + '）'; }
+    }
+    out.push('⑤ 回合结束回灌 → ' + watchMsg);
+
+    return { ok: true, msg: out.join('\n') + `\n\n新会话 id = ${sid}\n（用 session_watch 看钩子名单；用 session_children 看血缘）` };
+  },
+};