@sidleo3/dsh-chat 0.0.4

package/host/file-log.mjs

@@ -0,0 +1,169 @@
+/**
+ * 渠道日志落盘（hub 所有）：把 `[dsh-chat-*]` 这些行同时写进文件。
+ *
+ * 为什么需要它：出故障时唯一的现场是"用户那台终端"，而终端输出既搜不了、也不会随
+ * 会话导出带走——排查时只能靠人肉回忆滚屏。"发了没反应"这类问题，必须有可检索的日志。
+ *
+ * 约束：
+ * - **日志本身绝不能成为故障源**：任何 IO 异常都被吞掉（最多 stderr 提一句）；
+ * - 异步追加 + 单文件上限 + 一次轮转（`x.log` → `x.log.1`），不无限增长；
+ * - 只负责文件，不改变原有 logger 的行为。
+ *
+ * @module dsh-chat/host/file-log
+ */
+
+import { appendFile, mkdir, rename, stat } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+const DEFAULT_MAX_BYTES = 2 * 1024 * 1024;
+const LEVELS = ['debug', 'info', 'warn', 'error'];
+
+function stamp() {
+  return new Date().toISOString();
+}
+
+/** 单行日志的长度上限：SDK 会把整个 axios 请求对象丢进来。 */
+const MAX_FIELD_CHARS = 2000;
+
+function clip(text) {
+  return text.length > MAX_FIELD_CHARS ? `${text.slice(0, MAX_FIELD_CHARS)}…` : text;
+}
+
+/**
+ * HTTP 客户端错误（axios 形态）压成一行摘要。
+ *
+ * 飞书 SDK 失败时把整个错误对象丢进 logger：`config`/`request`/`response` 三份且互相
+ * 引用，串起来一次几 KB，而真正的信息只有状态码、平台 code 和 msg。凑巧的是这类失败
+ * 往往每十分钟重试一次——现场就被它自己淹了。所以这类对象只留摘要。
+ */
+function httpErrorSummary(value) {
+  const status = value?.response?.status ?? value?.status;
+  if (!status || (!value?.config && !value?.request && !value?.response)) return null;
+  const data = value.response?.data ?? {};
+  const code = data?.code ?? value?.code;
+  const message = String(data?.msg ?? value?.message ?? '').replace(/\s+/gu, ' ').trim();
+  const parts = [`HTTP ${status}`];
+  if (value.statusText) parts.push(String(value.statusText));
+  if (code !== undefined && code !== null && code !== '') parts.push(`code=${code}`);
+  if (message) parts.push(message);
+  return parts.join(' ');
+}
+
+/** 把任意一个参数压成一行可读文本。 */
+function oneLine(value) {
+  if (typeof value === 'string') return value;
+  if (value === null || value === undefined) return String(value);
+  if (value instanceof Error) {
+    return `${value.name}: ${value.message}${value.code ? `（code ${value.code}）` : ''}`;
+  }
+  if (typeof value !== 'object') return String(value);
+  // SDK 常把参数打包成数组（`logger.error([err, ctx])`），逐个压好再拼。
+  if (Array.isArray(value)) return clip(value.map(oneLine).filter((part) => part !== '').join(' '));
+  const http = httpErrorSummary(value);
+  if (http) return clip(http);
+  try {
+    const seen = new WeakSet();
+    const text = JSON.stringify(value, (key, item) => {
+      if (typeof item === 'object' && item !== null) {
+        if (seen.has(item)) return '[循环引用]';
+        seen.add(item);
+      }
+      return item;
+    });
+    if (typeof text !== 'string') return String(value);
+    return clip(text);
+  } catch {
+    return String(value);
+  }
+}
+
+/**
+ * 拼一行日志正文。
+ *
+ * 第三方 SDK（飞书）是按 `logger.error(obj, obj)` 调的：直接 `String()` 只会写出
+ * `[object Object],[object Object]`，而日志是排查时唯一的现场——这种行等于没写。
+ */
+function describe(message, rest = []) {
+  return [message, ...rest].map(oneLine).filter((part) => part !== '').join(' ');
+}
+
+/**
+ * 创建一个按大小轮转的日志文件写入口。
+ *
+ * @param options - { path, maxBytes }。
+ * @returns { write, path }；`write` 永不抛错。
+ */
+export function createLogFileSink({ path, maxBytes = DEFAULT_MAX_BYTES } = {}) {
+  if (typeof path !== 'string' || !path) throw new TypeError('日志文件需要 path。');
+  let queue = Promise.resolve();
+  let size = null;
+  let warned = false;
+
+  async function rotateIfNeeded(nextLength) {
+    if (size === null) {
+      try {
+        size = (await stat(path)).size;
+      } catch {
+        size = 0;
+      }
+    }
+    if (size > 0 && size + nextLength > maxBytes) {
+      await rename(path, `${path}.1`).catch(() => {});
+      size = 0;
+    }
+  }
+
+  function write(line) {
+    const text = `${line}\n`;
+    queue = queue.then(async () => {
+      try {
+        await mkdir(dirname(path), { recursive: true });
+        await rotateIfNeeded(text.length);
+        await appendFile(path, text, 'utf8');
+        size = (size ?? 0) + text.length;
+      } catch (error) {
+        if (!warned) {
+          warned = true;
+          // 只提醒一次，且不改变调用方流程。
+          process.stderr.write(`[dsh-chat] 写日志文件失败（${path}）：${error?.message ?? error}\n`);
+        }
+      }
+    });
+    return queue;
+  }
+
+  return { write, path, flush: () => queue };
+}
+
+/**
+ * 把一个 logger 包成"原样转发 + 落盘"。
+ *
+ * @param options - { logger, sink, scope }。
+ * @returns 与入参同形的 logger（缺哪个级别就补一个空实现）。
+ */
+export function withFileSink({ logger, sink, scope = '' }) {
+  if (!sink?.write) return logger;
+  const wrapped = {};
+  for (const level of LEVELS) {
+    const inner = typeof logger?.[level] === 'function' ? logger[level].bind(logger) : null;
+    wrapped[level] = (message, ...rest) => {
+      try {
+        inner?.(message, ...rest);
+      } finally {
+        // 消息里通常已经带 `[dsh-chat-<渠道>]` 前缀，别再加一遍。
+        const text = describe(message, rest);
+        const prefix = scope && !text.startsWith('[') ? `[${scope}] ` : '';
+        sink.write(`${stamp()} ${level.toUpperCase().padEnd(5)} ${prefix}${text}`);
+      }
+    };
+  }
+  // 第三方 SDK（如飞书）会调 trace：给它一个落点，免得日志调用本身把流程打断。
+  if (typeof wrapped.trace !== 'function') wrapped.trace = wrapped.debug;
+  // 自定义 logger 可能还带别的方法，原样保留。
+  return Object.assign(Object.create(Object.getPrototypeOf(logger ?? {}) ?? Object.prototype), logger ?? {}, wrapped);
+}
+
+/** 日志目录（hub 数据目录下，所有渠道共用一处，方便一起看）。 */
+export function channelLogPath(logsDir, name) {
+  return join(logsDir, `${name}.log`);
+}

package/host/guidance.mjs

@@ -0,0 +1,73 @@
+/**
+ * 每会话的来源提示词登记表（host 侧，进程内单例语义）。
+ *
+ * 提示词 RPC 不携带消息来源，所以渠道在派发 prompt 时把"本次生效的增强提示词"
+ * 发布进来；host 把它物化成该 Session 的动态提示词上下文，只在渲染文本变化时
+ * 追加一条持久快照。key 是 Session id，因此"指定用户 / 指定群"各属独立会话时
+ * 天然各自生效。
+ *
+ * @module dsh-chat/host/guidance
+ */
+
+/** 动态提示词上下文名。 */
+export const SOURCE_GUIDANCE_CONTEXT = 'dsh-chat:source-guidance';
+
+/** 上下文拼接顺序：跟在策略类事实之后。 */
+export const SOURCE_GUIDANCE_ORDER = 125;
+
+/** 单会话提示词上限（与设置上限一致）。 */
+const GUIDANCE_MAX_LENGTH = 8_000;
+
+/** 保留会话数上限，避免被废弃会话无限撑大。 */
+const MAX_SESSIONS = 1_024;
+
+/**
+ * 创建提示词登记表。
+ *
+ * @returns { publish, get, forget, size }。
+ */
+export function createGuidanceRegistry() {
+  /** @type {Map<string, string>} */
+  const bySession = new Map();
+
+  return {
+    /**
+     * 发布一个会话当前生效的提示词；空值表示清除。
+     *
+     * @param sessionId - 目标 Session。
+     * @param guidance - 提示词正文。
+     */
+    publish(sessionId, guidance) {
+      if (typeof sessionId !== 'string' || !sessionId) return;
+      const text = typeof guidance === 'string' ? guidance.slice(0, GUIDANCE_MAX_LENGTH) : '';
+      bySession.delete(sessionId);
+      if (!text.trim()) return;
+      bySession.set(sessionId, text);
+      while (bySession.size > MAX_SESSIONS) {
+        bySession.delete(bySession.keys().next().value);
+      }
+    },
+
+    /**
+     * @param sessionId - Session id。
+     * @returns 该会话的提示词，未登记时为 undefined。
+     */
+    get(sessionId) {
+      return typeof sessionId === 'string' ? bySession.get(sessionId) : undefined;
+    },
+
+    /**
+     * 会话离开时清掉登记。
+     *
+     * @param sessionId - Session id。
+     */
+    forget(sessionId) {
+      if (typeof sessionId === 'string') bySession.delete(sessionId);
+    },
+
+    /** @returns 当前登记数量。 */
+    get size() {
+      return bySession.size;
+    },
+  };
+}

package/host/index.mjs

@@ -0,0 +1,7 @@
+/**
+ * dsh-chat Hub 的 host 打包入口。
+ *
+ * @module dsh-chat/host
+ */
+
+export { apply, inject, name } from './plugin.mjs';

package/host/interactions.mjs

@@ -0,0 +1,330 @@
+/**
+ * 人在环交互回传（hub 所有）：把 agent 的**提问**与**审批**送到 IM 里问、并从 IM 里收答案。
+ *
+ * 为什么要在 hub：这两件事与平台无关——渲染问题、等待回答、解析回答、超时兜底，
+ * 所有渠道一模一样；渠道只提供两样东西：
+ *   1. 怎么把一段文本发到某个会话（`attach` 时传入的 `send`）；
+ *   2. 入站文本先交给 `offer`，被认领了就不要再去跑模型。
+ *
+ * 关键取舍：
+ * - **超时/取消就交回其他应答方**（浏览器 UI）：`handle` 返回 null，上层 `next()`。
+ *   这样即使 IM 那侧没人回，也不会把这一轮卡死。
+ * - 只有已绑定的会话、且该渠道接入了 IM 回传时才认领；否则一样让给浏览器。
+ * - 未识别的回复在审批场景里按"拒绝"处理（fail closed），并留下日志。
+ *
+ * @module dsh-chat/host/interactions
+ */
+
+const DEFAULT_TIMEOUT_MS = 10 * 60_000;
+
+const APPROVE_PATTERN = /^(允许|同意|可以|好|好的|是|执行|ok|okay|yes|y|allow|approve)$/i;
+const REJECT_PATTERN = /^(拒绝|不允许|不同意|不可以|不行|不要|不用|否|不|取消|no|n|deny|reject|cancel)$/i;
+
+function waiterKey(channelId, botId, key) {
+  return `${channelId}\u0000${botId}\u0000${key}`;
+}
+
+/**
+ * 把一个问题渲染成一条 IM 文本。
+ *
+ * @param question - DSH 的 `AskUserQuestionItem`。
+ * @param options - { position, total }：多问题时给出进度。
+ * @returns 文本。
+ */
+export function renderQuestion(question, { position = 0, total = 1 } = {}) {
+  const header = question?.header || '需要你确认';
+  const lines = [total > 1 ? `❓ ${header}（${position}/${total}）` : `❓ ${header}`, ''];
+  lines.push(String(question?.question ?? ''));
+  if (question?.detail) {
+    lines.push('', String(question.detail));
+  }
+  const options = Array.isArray(question?.options) ? question.options : [];
+  if (options.length > 0) {
+    lines.push('');
+    options.forEach((option, index) => {
+      lines.push(`${index + 1}. ${option.label}${option.description ? ` —— ${option.description}` : ''}`);
+    });
+    lines.push('');
+    lines.push(question?.multiSelect
+      ? '可以回复多个编号（例如 1,3），也可以直接回复文字。'
+      : '回复编号或选项原文即可，也可以直接回复文字。');
+  } else {
+    lines.push('', '直接回复你的答案。');
+  }
+  return lines.join('\n');
+}
+
+/**
+ * 把一个问题渲染成卡片正文（不带按钮）：用于"多选/自由文本"这类按钮表达不了的提问，
+ * 好处是仍然留在**同一张卡片**里，不会再单独发一条文本消息把聊天记录撑满。
+ *
+ * @param question - DSH 的 `AskUserQuestionItem`。
+ * @returns 若干行文本（markdown）。
+ */
+export function renderQuestionLines(question) {
+  const lines = [];
+  const header = question?.header ? `**${question.header}**\n` : '';
+  lines.push(`${header}${question?.question ?? ''}`);
+  if (question?.detail) lines.push('', String(question.detail));
+  const options = Array.isArray(question?.options) ? question.options : [];
+  if (options.length > 0) {
+    lines.push('');
+    options.forEach((option, index) => {
+      lines.push(`${index + 1}. **${option.label}**${option.description ? ` —— ${option.description}` : ''}`);
+    });
+    lines.push('', question?.multiSelect
+      ? '可多选：回复编号（例如 `1,3`），也可以直接回复文字。'
+      : '回复编号或选项文字即可，也可以直接回复文字。');
+  } else {
+    lines.push('', '直接回复你的文字答案。');
+  }
+  return lines;
+}
+
+/**
+ * 渲染一次审批请求。
+ *
+ * @param request - `ApprovalRequestEvent`。
+ * @returns 文本。
+ */
+export function renderApproval(request) {
+  const lines = ['⚠️ 需要授权', ''];
+  lines.push(`工具：${request?.toolName ?? '未知'}`);
+  if (request?.reason) lines.push(`原因：${request.reason}`);
+  lines.push('', '回复「允许」执行一次，或「拒绝」取消。');
+  return lines.join('\n');
+}
+
+/**
+ * 把用户回复解析成一个问题的答案。
+ *
+ * 支持：编号（`2`）、选项原文、多选（`1,3`）、以及任意自由文本（走 `custom`）。
+ *
+ * @param question - `AskUserQuestionItem`。
+ * @param reply - 用户回复的原文。
+ * @returns `AskUserQuestionAnswerItem`。
+ */
+export function parseAnswer(question, reply) {
+  const raw = String(reply ?? '').trim();
+  const options = Array.isArray(question?.options) ? question.options : [];
+  // 选项原文本身可能带空格（例如「排查某个 App 异常」），所以先整体比一次；
+  // 多选才按逗号/顿号拆，绝不用空格拆——那会把选项标签拆碎。
+  const exact = options.find((option) => option.label === raw);
+  if (exact) return { id: String(question?.id ?? ''), selected: [exact.label] };
+  const tokens = question?.multiSelect
+    ? raw.split(/[,，、;；]+/).map((token) => token.trim()).filter(Boolean)
+    : [raw];
+  const selected = [];
+  const unmatched = [];
+  for (const token of tokens) {
+    const byIndex = /^\d+$/.test(token) ? options[Number(token) - 1] : undefined;
+    const byLabel = byIndex ?? options.find((option) => option.label === token);
+    if (byLabel) {
+      if (!selected.includes(byLabel.label)) selected.push(byLabel.label);
+      continue;
+    }
+    unmatched.push(token);
+  }
+  const answer = { id: String(question?.id ?? ''), selected };
+  if (unmatched.length > 0) {
+    // 一个选项都没匹配上时保留用户原文（多选拆分不该改写他的说法）。
+    answer.custom = unmatched.length === tokens.length ? raw : unmatched.join(' ');
+  }
+  return answer;
+}
+
+/**
+ * 解析审批回复。
+ *
+ * @param reply - 用户回复的原文。
+ * @returns 'allowed-once' | 'rejected' | null（认不出来）。
+ */
+export function parseApproval(reply) {
+  const raw = String(reply ?? '').trim();
+  if (APPROVE_PATTERN.test(raw)) return 'allowed-once';
+  if (REJECT_PATTERN.test(raw)) return 'rejected';
+  return null;
+}
+
+/**
+ * 创建交互服务。
+ *
+ * @param options - { logger, timeoutMs }。
+ * @returns { attach, has, offer, handle }。
+ */
+export function createInteractionService({ logger = console, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  /** `${channelId}\u0000${botId}` → send({ key, text }) */
+  const senders = new Map();
+  /** `${channelId}\u0000${botId}\u0000${key}` → { resolve } */
+  const waiters = new Map();
+
+  function senderFor(channelId, botId) {
+    return senders.get(`${channelId}\u0000${botId}`) ?? null;
+  }
+
+  /**
+   * 等一条回答；超时或取消返回 null（= 让给其他应答方）。
+   *
+   * @param options - { channelId, botId, key, kind, signal, budgetMs }。
+   * @returns `{ text, questionId }` 或 null。
+   */
+  function wait({ channelId, botId, key, kind, signal, budgetMs }) {
+    const timeout = Math.max(0, Number.isFinite(budgetMs) ? budgetMs : timeoutMs);
+    return new Promise((resolve) => {
+      const id = waiterKey(channelId, botId, key);
+      let settled = false;
+      const finish = (value) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        signal?.removeEventListener?.('abort', onAbort);
+        if (waiters.get(id)?.resolve === entry.resolve) waiters.delete(id);
+        if (value === null) {
+          logger.warn?.(`[dsh-chat] ${kind} 在 IM 里没有得到回答，交回其他应答方`
+            + `（${channelId}/${botId}/${key}）`);
+        }
+        resolve(value);
+      };
+      const entry = { resolve: (value) => finish(value) };
+      const timer = setTimeout(() => finish(null), timeout);
+      const onAbort = () => finish(null);
+      signal?.addEventListener?.('abort', onAbort, { once: true });
+      waiters.set(id, entry);
+    });
+  }
+
+  return Object.freeze({
+    /**
+     * 渠道接入 IM 回传：给出"怎么把文本发到这个机器人的某个会话"。
+     *
+     * @param options - { channelId, botId, send({ key, text }) }。
+     * @returns 注销函数。
+     */
+    attach({ channelId, botId, send, sendQuestion, sendQuestions, sendApproval }) {
+      if (typeof send !== 'function') throw new TypeError('交互回传需要渠道提供 send。');
+      const id = `${channelId}\u0000${botId}`;
+      senders.set(id, {
+        send,
+        // 可选：渠道能把问题/审批渲染成平台原生交互（飞书的按钮卡片），比纯文本好用得多。
+        // `sendQuestions` 是"一批问题一张卡、回答后就地更新"的形态，优先用它。
+        sendQuestions: typeof sendQuestions === 'function'
+          ? sendQuestions
+          : (typeof sendQuestion === 'function' ? null : null),
+        sendQuestion: typeof sendQuestion === 'function' ? sendQuestion : null,
+        sendApproval: typeof sendApproval === 'function' ? sendApproval : null,
+      });
+      return () => {
+        if (senders.get(id)?.send === send) senders.delete(id);
+      };
+    },
+
+    /** @returns 该渠道是否接入了 IM 回传（未接入则一律让给浏览器 UI）。 */
+    has: (channelId) => [...senders.keys()].some((id) => id.startsWith(`${channelId}\u0000`)),
+
+    /**
+     * 入站文本先过这里：属于某个待回答的问题/审批就认领，调用方**不要**再跑模型。
+     *
+     * @param options - { channelId, botId, key, text }。
+     * @returns 是否被认领。
+     */
+    offer({ channelId, botId, key, text, questionId }) {
+      const entry = waiters.get(waiterKey(channelId, botId, key));
+      if (!entry) return false;
+      logger.info?.(`[dsh-chat] IM 回答已认领：${channelId}/${botId}/${key}`
+        + `${questionId ? ` 问题=${questionId}` : ''}`);
+      entry.resolve({ text, questionId });
+      return true;
+    },
+
+    /**
+     * 应答一次提问/审批。
+     *
+     * @param options - { kind: 'question'|'approval', channelId, botId, key, request }。
+     * @returns 提问返回 `{ answers }`，审批返回 outcome 字符串；无法应答时返回 null。
+     */
+    async handle({ kind, channelId, botId, key, request }) {
+      const sender = senderFor(channelId, botId);
+      if (!sender) return null;
+
+      if (kind === 'approval') {
+        logger.info?.(`[dsh-chat] 审批已发往 IM：${channelId}/${botId}/${key}`
+          + ` 工具=${request?.toolName ?? '?'} 方式=${sender.sendApproval ? '卡片' : '文本'}`);
+        if (sender.sendApproval) {
+          await sender.sendApproval({ key, request });
+        } else {
+          await sender.send({ key, text: renderApproval(request) });
+        }
+        const reply = await wait({ channelId, botId, key, kind: '审批', signal: request?.signal });
+        if (reply === null) return null;
+        const outcome = parseApproval(reply.text);
+        if (outcome === null) {
+          logger.warn?.(`[dsh-chat] 审批回复无法识别（${JSON.stringify(reply.text)}），按拒绝处理`);
+          return 'rejected';
+        }
+        return outcome;
+      }
+
+      const questions = Array.isArray(request?.questions) ? request.questions : [];
+      if (questions.length === 0) return null;
+
+      // 一批问题只用一张卡片（渠道支持的话），回答后就地更新——避免每问一条把聊天记录撑满。
+      let useCard = typeof sender.sendQuestions === 'function';
+      const answered = new Map();
+      const render = async ({ final = false } = {}) => {
+        if (!useCard) return;
+        try {
+          await sender.sendQuestions({
+            key,
+            questions,
+            answered: Object.fromEntries(answered),
+            final,
+          });
+        } catch (error) {
+          logger.warn?.(`[dsh-chat] 提问卡片更新失败：${error?.message ?? error}`);
+        }
+      };
+
+      logger.info?.(`[dsh-chat] 提问已发往 IM：${channelId}/${botId}/${key}`
+        + ` 问题数=${questions.length} 方式=${useCard ? '卡片' : '文本'}`);
+      if (useCard) {
+        // 首发失败要真的退回文本，否则用户什么都看不到、这一轮白等。
+        try {
+          await sender.sendQuestions({ key, questions, answered: {}, final: false });
+        } catch (error) {
+          useCard = false;
+          logger.warn?.(`[dsh-chat] 提问卡片发送失败，回退为文本：${error?.message ?? error}`);
+        }
+      }
+      if (!useCard) {
+        for (const [index, question] of questions.entries()) {
+          await sender.send({
+            key,
+            text: renderQuestion(question, { position: index + 1, total: questions.length }),
+          });
+        }
+      }
+
+      const deadline = Date.now() + timeoutMs;
+      while (answered.size < questions.length) {
+        const budgetMs = deadline - Date.now();
+        if (budgetMs <= 0) return null;
+        const reply = await wait({
+          channelId, botId, key, kind: '提问', signal: request?.signal, budgetMs,
+        });
+        if (reply === null) return null;
+        // 按钮点击带 questionId（可以按任意顺序点）；手打文字则答给"第一个还没答的问题"。
+        const target = reply.questionId
+          ? questions.find((item) => item?.id === reply.questionId && !answered.has(item.id))
+          : questions.find((item) => !answered.has(item?.id));
+        if (!target) {
+          logger.info?.(`[dsh-chat] 忽略无法归属的回答（questionId=${reply.questionId ?? '无'}）`);
+          continue;
+        }
+        answered.set(target.id, parseAnswer(target, reply.text));
+        await render();
+      }
+      await render({ final: true });
+      return { answers: questions.map((question) => answered.get(question?.id)) };
+    },
+  });
+}