dsh-qqbot-buddy 1.0.0-alpha.0 → 1.0.0-alpha.2

package/README.md

@@ -4,9 +4,10 @@
 支持配置档（Profile）/作用域绑定、可管理的工具与技能、SQLite + FTS5 长期记忆与知识库、
 群友库、人格卡与表情包，并提供多机器人隔离运行。
 
-- 适用版本：`1.0.0-alpha.0`（v2 分支）
+- 适用版本：`1.0.0-alpha.2`（v2 分支）
 - 运行环境：**Node.js ≥ 24**（使用内置 `node:sqlite`）、dsh 0.2.x
 - 依赖：QQ 官方机器人平台的 `appId` / `appSecret`（WebSocket 接入，无需公网回调）
+- npm：[dsh-qqbot-buddy](https://www.npmjs.com/package/dsh-qqbot-buddy)（当前 alpha 走 `@next` 标签）
 - 许可证：MIT
 
 ---
@@ -15,7 +16,7 @@
 
 | 模块 | 说明 |
 | --- | --- |
-| 独立控制台 | 随插件进程启动的 Web 管理台（默认 `127.0.0.1:6198`），token 登录、SSE 实时事件、开机即用，无需额外部署前端或数据库 |
+| 独立控制台 | 随插件进程启动的 Web 管理台（默认 `127.0.0.1:6198`），token 登录、SSE 实时事件、开机即用，无需额外部署前端或数据库；与 dsh Web 双向快捷入口（控制台顶栏 → dsh Web；dsh Web 右下角 → QQ 控制台） |
 | 多机器人 | 每个 bot 独立工作目录 `<workspace>/bots/<botId>`，凭据、会话、日志互不影响；同一进程可管理多个 bot |
 | 配置档与绑定 | 三层策略：`global < bot < profile`；按 `群聊 / 私聊 / 指定 openid` 绑定不同配置档（精确 > 类型通配 > bot 通配 > 默认档），切换配置档不丢记忆 |
 | 提示词管理 | 人设卡、人格卡、口头禅、能力边界、工具指引；控制台提供**提示词拼合预览**，按真实顺序查看每段内容与字符数 |
@@ -63,7 +64,23 @@
 - 已安装 dsh（`dsh --version` 可用），并初始化过至少一个 profile
 - QQ 官方机器人平台的 bot（获取 `appId`、`appSecret`，并在平台开启所需的群/私聊权限）
 
-### 方式一：从 GitHub 安装（推荐）
+### 方式一：npm 安装（推荐）
+
+```bash
+# 装到默认 web profile（当前是 alpha 版本，使用 @next 标签）
+dsh plugin --profile web add dsh-qqbot-buddy@next
+
+# 或装到指定 profile
+dsh plugin --profile qqbot add dsh-qqbot-buddy@next
+
+# 或使用安装器（自动校验/初始化 profile、登记 bundle、自检）
+npx -y --package=dsh-qqbot-buddy@next dsh-qqbot-buddy-install --profile qqbot --spec dsh-qqbot-buddy@next
+```
+
+> 稳定版发布后可直接 `dsh plugin add dsh-qqbot-buddy`（不带 `@next`）。
+> 安装完成后**重启 dsh**，控制台随插件一起启动。
+
+### 方式二：从 GitHub 安装（无需 npm 账号）
 
 ```bash
 # 安装到默认 web profile
@@ -77,9 +94,8 @@ npx -y github:Ethereal-ljq/dsh-qqbot-buddy#v2 --dry-run
 ```
 
 安装器会完成：初始化/校验 profile → 安装插件与运行期依赖 → 登记进 `dsh.profile.bundles` → 自检。
-安装完成后**重启 dsh**，控制台随插件一起启动。
 
-### 方式二：本地开发安装
+### 方式三：本地开发安装
 
 ```bash
 git clone -b v2 https://github.com/Ethereal-ljq/dsh-qqbot-buddy.git
@@ -191,7 +207,8 @@ QQ 开放平台 (WebSocket)
 ## 开发
 
 ```bash
-npm test                     # 单元测试（node --test，434 例）
+npm test                     # 单元测试（node --test，437 例）
+npm run verify:recall        # 真机验证记忆/知识库自动注入（需要控制台在线）
 npm run console:build        # tsc 严格检查 + vite 构建控制台
 npm run console:dev          # 控制台前端开发模式（代理到 6198）
 node scripts/dev-console.mjs # 只启动控制台后端（不连 QQ）
@@ -234,4 +251,4 @@ scripts/                安装器、迁移、探针等工具
 
 ## 许可证
 
-[MIT](LICENSE)
+[MIT](LICENSE)

package/docs/USER-GUIDE.md

@@ -31,11 +31,23 @@ Web 管理控制台。你不需要额外部署数据库、消息队列或前端
 
 ## 1. 安装、升级与卸载
 
-### 1.1 从 GitHub 安装（推荐）
+### 1.1 安装（npm 推荐 / GitHub 备选）
+
+**方式 A：npm（推荐）**
+
+    dsh plugin --profile web add dsh-qqbot-buddy@next
+    # 或指定 profile
+    dsh plugin --profile qqbot add dsh-qqbot-buddy@next
+    # 或使用安装器（自动初始化/校验 profile、登记 bundle、自检）
+    npx -y --package=dsh-qqbot-buddy@next dsh-qqbot-buddy-install --profile qqbot --spec dsh-qqbot-buddy@next
+
+当前发布的是 `1.0.0-alpha.0`，使用 `@next` 标签；稳定版发布后可直接 `dsh plugin add dsh-qqbot-buddy`。
+
+**方式 B：从 GitHub 安装（无需 npm 账号）**
 
     npx -y github:Ethereal-ljq/dsh-qqbot-buddy#v2
 
-安装器会：把插件包装进 dsh profile（默认 `web`）→ 登记到 `dsh.profile.bundles` →
+安装器会：把插件装进 dsh profile（默认 `web`）→ 登记到 `dsh.profile.bundles` →
 用 `dsh --profile web --dump-config` 自检插件已进入插件树。安装过程**不构建前端、不联网拉前端依赖**。
 
 常用参数：
@@ -57,10 +69,10 @@ Web 管理控制台。你不需要额外部署数据库、消息队列或前端
 `--local` 会跳过 `node_modules`、`.git`、`.work` 和顶层 `test`，不会经过 pnpm。
 前端源码改动后需要 `npm run build:web` 重建 `web/dist` 再本地安装。
 
-> 全新 DSH_HOME 无需手工初始化：安装器检测到 profile 不存在或缺少
-> `@deepseek-ai/dsh-base` / `@deepseek-ai/dsh-web-app` 时，会自动用 dsh 随附模板初始化
-> （等价的命令是 `dsh --profile web --dump-default-config`），然后再安装本插件。
-> 若你看到「初始化 profile（使用 dsh 随附模板）」说明走了这条路径。
+> 全新 DSH_HOME 无需手工初始化：安装器检测到 profile 不存在时，会用 `npm pack` 打出的
+> 插件包执行 `dsh plugin --profile <name> add <tgz>` 完成 profile 初始化并装齐运行期依赖，
+> 再把插件目录覆盖为纯文件副本（不依赖仓库 `node_modules`）。远程安装则由 `dsh plugin add`
+> 自动创建 profile。若你看到「初始化 profile（dsh plugin add）」说明走了这条路径。
 
 ### 1.3 安装后首次启动
 
@@ -167,6 +179,12 @@ Web 管理控制台。你不需要额外部署数据库、消息队列或前端
 > 顶栏右上角有 **「dsh Web ↗」** 按钮：一键打开当前 dsh 进程的 Web 界面（链接自带本进程的鉴权 token，无需再手抄）。
 > 注意：该 token 每次重启 dsh 都会变，因此按钮只在当前进程生命周期内有效；不要把带 token 的链接转发给别人。
 
+**反向入口（dsh Web → 控制台）**：插件同时带一个 dsh Web 客户端入口——安装本插件的
+web profile 会在页面右下角显示悬浮的 **「QQ 控制台」** 按钮，点击经同源路由 `/qqbot-dashboard`
+302 到控制台（端口/地址跟随配置，不需要改前端）。若 web profile 只用于放入口、控制台跑在
+机器人 profile 里，可在该 profile 的 patch 配置里设 `console.enabled: false`（不重复启动控制台）
+并把 `console.port` 指向已有控制台端口即可。
+
 ![控制台总览](images/console-overview.png)
 
 *图 1：控制台总览——机器人运行状态、SSE 事件流与配置规模一屏可见。*
@@ -439,6 +457,38 @@ v2 暂未提供口头禅编辑 UI。v1 → v2 迁移时，旧 `phrases` / `promp
 
 *图 5：表情包页——按 (bot, hash) 去重，显示当日发送量与配额。*
 
+## 7.5 验证记忆与知识库是否自动注入
+
+不用真的在群里聊，控制台提供两条验证路径：
+
+**方式一：一键黑盒验证（推荐）**
+
+    node scripts/verify-recall.mjs
+    # 或：npm run verify:recall
+    # 指定机器人 / 问句 / 保留测试数据
+    node scripts/verify-recall.mjs --bot bot_xxx --query "记忆暗号是什么？知识库暗号是什么？" --keep
+
+脚本会通过控制台 API 写入带唯一暗号的临时记忆 + 知识库文档，然后：
+预览接口检查 `qqbot:memory` / `qqbot:knowledge` 段 → reset 测试 peer → 触发一轮真实模型对话 →
+读取会话文件里的 assistant 回复，确认两个暗号都被模型用上；结束自动删除测试数据。
+退出码：0 通过；2 召回层未命中；3 模型回复没用到暗号。
+
+**方式二：控制台 / API 单独看召回结果**
+
+1. 控制台「提示词预览」输入问句 → 查看「长期记忆」「知识库」两段是否有内容；
+2. 或直接调接口：
+
+       curl -H "cookie: <登录会话>" \
+         "http://127.0.0.1:6198/api/preview/prompt?bot=bot_xxx&query=记忆暗号是什么"
+
+3. 也可以调 `POST /api/memories/search`、`POST /api/kb/search` 看原始检索命中（用来区分"没入库"还是"召回没命中"）。
+
+**排查顺序**：入库 → 原始检索命中 → 预览段出现 → 模型回复引用；
+哪一步断了就查对应设置（记忆/知识库开关、topK、字符预算、query 是否太口语化）。
+
+**说明**：召回会用「整句 → 去疑问词的核心短语 → 拆词」多级候选，
+所以「你还记得我的暗号吗」「知识库暗号是什么」这类自然问句也能命中，不必背关键词。
+
 ## 8. 数据、备份、恢复与迁移
 
 ### 8.1 数据都在哪

package/lib/client.js

@@ -0,0 +1,73 @@
+/**
+ * dsh Web 客户端插件：在侧边栏底部（sidebar.footer.action 槽位）加一个
+ * 「QQ」快捷入口，点击后跳到 QQBot 控制台。
+ *
+ * 入口地址不走硬编码端口：服务端注册了同源路由 /qqbot-dashboard，会读取本插件
+ * 当前配置的 console 地址并 302 过去，这样改端口/监听地址都不需要改前端。
+ *
+ * 说明：这是 dsh Web 的 client module（window.__ModuleLoader__ 协议），
+ * 只在安装了本插件的 web profile 里出现；纯前端、无构建依赖。
+ */
+window.__ModuleLoader__.load({
+  id: 'dsh-qqbot-buddy',
+  factory: (require) => {
+    var module = { exports: {} };
+    var exports = module.exports;
+    Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+    const jsx = require('react/jsx-runtime');
+
+    const inject = ['slots'];
+    const PAGE = 'QQBot 控制台';
+
+    /** 侧边栏底部的 QQ 快捷入口（外链走同源 302）。 */
+    function QqbotDashboardAction() {
+      return jsx.jsxs('a', {
+        href: '/qqbot-dashboard',
+        target: '_blank',
+        rel: 'noreferrer',
+        title: PAGE + '（在新标签页打开）',
+        'aria-label': PAGE,
+        className: 'qqbot-dashboard-entry',
+        style: {
+          position: 'fixed',
+          right: '16px',
+          bottom: '16px',
+          zIndex: 40,
+          pointerEvents: 'auto',
+          display: 'inline-flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          gap: '4px',
+          padding: '6px 10px',
+          borderRadius: '999px',
+          border: '1px solid var(--dsw-alias-border-l2, rgba(128,128,128,.35))',
+          background: 'var(--dsw-alias-bg-layer-2, rgba(20,20,20,.72))',
+          color: 'var(--dsw-alias-label-primary, inherit)',
+          textDecoration: 'none',
+          fontSize: '12px',
+          fontWeight: 600,
+          letterSpacing: '0.02em',
+          lineHeight: 1,
+          boxShadow: '0 2px 10px rgba(0,0,0,.18)',
+        },
+        children: [
+          jsx.jsx('span', { 'aria-hidden': 'true', children: 'QQ 控制台' }),
+        ],
+      });
+    }
+
+    function apply(ctx) {
+      // shell.overlay 是覆盖层列表槽位：不会被折叠侧栏的 hover mask 挡住，
+      // 用 fixed 定位放在左下角，任何页面都能点。
+      ctx.slots.inject('shell.overlay', () => ctx.slots.register({
+        name: 'shell.overlay',
+        id: 'qqbot-dashboard',
+        order: 20,
+      }, QqbotDashboardAction));
+    }
+
+    exports.apply = apply;
+    exports.inject = inject;
+    return module.exports;
+  },
+});

package/lib/core/text/terms.js

@@ -36,6 +36,51 @@ function pushTerm(out, seen, value) {
   out.push(term);
 }
 
+// 疑问/口语后缀：自然问句（"记忆暗号是什么"）直接整句 phrase 查 FTS 会零命中，
+// 需要剥掉疑问词得到核心短语（"记忆暗号"）再查。
+const QUESTION_SUFFIX = /(?:是什么|是多少|多少|是谁|谁|是哪个|哪个|哪里|哪儿|怎么样|怎么|为什么|为何|是否|能不能|可不可以|记不记得|还记得|记得|知道|告诉我|说一下|一下|请告诉我|请问|吗|呢|呀|啊|吧|哦|嘛|来着|了)$/u;
+
+/**
+ * 生成检索候选短语（由宽到窄），供召回层逐个尝试。
+ * 例："记忆暗号是什么？" → ["记忆暗号是什么", "记忆暗号"]
+ *     "你还记得我的暗号吗" → [..., "暗号", ...]
+ * @param {string} text
+ * @param {{max?: number}} [options]
+ * @returns {string[]}
+ */
+export function queryCandidates(text, { max = 12 } = {}) {
+  const norm = typeof text === 'string' ? text.normalize('NFKC').trim().replace(/[？?！!。，,、：:；;\s]+$/u, '') : '';
+  if (norm === '') return [];
+  const out = [];
+  const seen = new Set();
+  const push = (value) => {
+    const term = String(value || '').trim();
+    if (term.length < 2) return;
+    const key = term.toLowerCase();
+    if (seen.has(key)) return;
+    seen.add(key);
+    out.push(term);
+  };
+  // 一段文本 + 反复剥疑问/口语后缀（"记忆暗号是什么" → "记忆暗号"）
+  const addVariants = (value) => {
+    let current = String(value || '').trim();
+    if (current === '') return;
+    push(current);
+    for (let i = 0; i < 5; i += 1) {
+      const next = current.replace(QUESTION_SUFFIX, '').trim();
+      if (next === current) break;
+      push(next);
+      current = next;
+    }
+  };
+  addVariants(norm);
+  // 多句/多问句：按标点切开，每段各自剥疑问词（一句里问两件事时也能得到两个核心短语）
+  for (const segment of norm.split(/[？?！!。，,、：:；;\s]+/u)) addVariants(segment);
+  // 拆词（含连接词/的 等）
+  for (const term of queryTerms(norm)) addVariants(term);
+  return out.slice(0, max);
+}
+
 /**
  * 把一句话拆成检索词。
  * @param {string} text
@@ -59,4 +104,4 @@ export function queryTerms(text, { maxTerms = MAX_TERMS } = {}) {
   return out.slice(0, maxTerms);
 }
 
-export default { queryTerms };
+export default { queryTerms, queryCandidates };

package/lib/host/recall.js

@@ -14,25 +14,26 @@ const DEFAULT_MEMBER_MAX = 3;
 const DEFAULT_KB_ITEMS = 5;
 const DEFAULT_MEMBER_CANDIDATES = 200;
 
-import { queryTerms } from '../core/text/terms.js';
+import { queryCandidates, queryTerms } from '../core/text/terms.js';
 
 const isObj = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 const strOf = (value) => (typeof value === 'string' ? value.trim() : '');
 
-export { queryTerms };
+export { queryTerms, queryCandidates };
 
-/** 多词检索：整句优先，空结果时逐词召回并去重（最多 limit 条）。 */
+/** 多短语检索：整句 → 去疑问词的核心短语 → 拆词，逐个召回并去重（最多 limit 条）。 */
 function searchWithFallback({ store, botId, text, limit, keyOf = (row) => row && row.id }) {
   const size = Number(limit) > 0 ? Number(limit) : DEFAULT_KB_ITEMS;
-  const first = typeof store.search === 'function' ? store.search({ botId, query: text, limit: size }) : [];
+  if (typeof store.search !== 'function') return [];
+  const first = store.search({ botId, query: text, limit: size });
   if (Array.isArray(first) && first.length > 0) return first;
-  const terms = queryTerms(text);
-  if (terms.length <= 1) return [];
+  const terms = queryCandidates(text);
+  if (terms.length === 0) return [];
   const merged = [];
   const seen = new Set();
   for (const term of terms) {
     let rows = [];
-    try { rows = typeof store.search === 'function' ? store.search({ botId, query: term, limit: size }) : []; } catch { rows = []; }
+    try { rows = store.search({ botId, query: term, limit: size }) || []; } catch { rows = []; }
     for (const row of Array.isArray(rows) ? rows : []) {
       const key = keyOf(row);
       if (key === undefined || key === null || seen.has(key)) continue;
@@ -188,11 +189,11 @@ export async function recallForPeer({ memory, knowledge, members, settings, botI
       const budget = Number(cfg.memory.recallChars) || DEFAULT_MEMORY_BUDGET;
       if (typeof memory.recallForPrompt === 'function') {
         let recalled = memory.recallForPrompt({ botId, query: text, budgetChars: budget, topK });
-        // 整句零命中时逐词召回（FTS phrase 匹配对长句不友好）
-        if ((typeof recalled !== 'string' || recalled.trim() === '') && queryTerms(text).length > 1) {
+        // 整句零命中时逐候选短语召回（FTS phrase 匹配对长句/问句不友好）
+        if (typeof recalled !== 'string' || recalled.trim() === '') {
           const seen = new Set();
           const lines = [];
-          for (const term of queryTerms(text)) {
+          for (const term of queryCandidates(text).slice(1)) {
             const part = memory.recallForPrompt({ botId, query: term, budgetChars: budget, topK });
             for (const line of String(part || '').split('\n')) {
               const key = line.trim();

package/lib/index.js

@@ -371,6 +371,52 @@ export async function apply(ctx, config) {
     }
   }
 
+  // ── dsh Web → QQBot 控制台快捷入口 ──
+  // 客户端插件（lib/client.js）只挂一个 href="/qqbot-dashboard" 的按钮；
+  // 这里注册同源 302 路由，读取当前 console 配置并跳转，改端口/地址无需动前端。
+  try {
+    ctx.inject(['webServer'], (webCtx) => {
+      try {
+        const resolveConsoleUrl = () => {
+          try {
+            const address = runtime.console && typeof runtime.console.address === 'function' ? runtime.console.address() : null;
+            const url = address && address.url ? String(address.url) : '';
+            if (url !== '') return url.endsWith('/') ? url : url + '/';
+          } catch { /* 控制台未启动/已关闭 */ }
+          // console.enabled=false 只表示「本 profile 不启动控制台」（例如 web profile 只放入口，
+          // 控制台跑在机器人 profile 里）；跳转仍按配置的 host/port 生成。
+          const consoleCfg = cfg.console || {};
+          let host = typeof consoleCfg.host === 'string' && consoleCfg.host !== '' ? consoleCfg.host : '127.0.0.1';
+          if (host === '0.0.0.0' || host === '::') host = '127.0.0.1';
+          const port = Number(consoleCfg.port) || 6198;
+          return 'http://' + host + ':' + port + '/';
+        };
+        webCtx.webServer.register({
+          kind: 'exact',
+          path: '/qqbot-dashboard',
+          handler: (req, res) => {
+            const target = resolveConsoleUrl();
+            if (target === '') {
+              res.statusCode = 503;
+              res.setHeader('content-type', 'text/plain; charset=utf-8');
+              res.end('QQBot 控制台未启用（dsh-qqbot-buddy 配置 console.enabled）');
+              return;
+            }
+            res.statusCode = 302;
+            res.setHeader('location', target);
+            res.setHeader('cache-control', 'no-store');
+            res.end();
+          },
+        });
+        logger.info('dsh Web 快捷入口已注册: /qqbot-dashboard');
+      } catch (err) {
+        logger.warn('dsh Web 快捷入口注册失败: ' + errText(err));
+      }
+    });
+  } catch (err) {
+    logger.warn('dsh Web 快捷入口注入失败: ' + errText(err));
+  }
+
   // ── 机器人宿主 ──
   try {
     const mod = await import('./host/agent.js');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-qqbot-buddy",
-  "version": "1.0.0-alpha.0",
+  "version": "1.0.0-alpha.2",
   "description": "DSH QQ 机器人插件 v2：自包含管理控制台、配置档/会话级配置、可管理的工具与技能、SQLite+FTS5 记忆与知识库",
   "type": "module",
   "license": "MIT",
@@ -25,6 +25,7 @@
   "exports": {
     ".": "./lib/index.js",
     "./console": "./lib/console/server.js",
+    "./client": "./lib/client.js",
     "./package.json": "./package.json"
   },
   "engines": {
@@ -33,6 +34,7 @@
   "scripts": {
     "test": "node --test test/*.test.js",
     "prepublishOnly": "node --test test/*.test.js",
+    "verify:recall": "node scripts/verify-recall.mjs",
     "setup:dev": "node scripts/setup-dev.mjs",
     "console:build": "npm --prefix web run build",
     "console:dev": "npm --prefix web run dev",
@@ -56,6 +58,13 @@
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-layout",
+        "@deepseek-ai/dsh-client-ui-renderer"
+      ]
     }
   },
   "bin": {

package/scripts/verify-recall.mjs

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+/**
+ * verify-recall —— 验证「记忆 / 知识库」是否被自动召回并进入模型回复。
+ *
+ * 做法（黑盒，不改动业务代码）：
+ *   1) 通过控制台 API 写入一条记忆 + 一条知识库文档，内容带唯一暗号；
+ *   2) 调 GET /api/preview/prompt 看 qqbot:memory / qqbot:knowledge 段是否包含暗号；
+ *   3) reset 一个测试 peer → debug-followup 用自然问句提问 → 等待会话文件里的 assistant 回复；
+ *   4) 检查回复是否包含两个暗号（证明模型确实拿到了注入内容）；
+ *   5) 默认清理写入的测试数据。
+ *
+ * 用法：
+ *   node scripts/verify-recall.mjs                      # 默认 http://127.0.0.1:6198
+ *   node scripts/verify-recall.mjs --base http://127.0.0.1:6198 --keep
+ *   node scripts/verify-recall.mjs --bot bot_xxx --peer c2c:TEST --query "我的暗号是什么？"
+ *
+ * 退出码：0 全部通过；2 召回层没命中；3 模型回复没用到暗号；1 环境/接口错误。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import zlib from 'node:zlib';
+
+const DEFAULT_BASE = 'http://127.0.0.1:6198';
+const DEFAULT_TOKEN_FILE = path.join(os.homedir(), '.dsh-qqbot', 'v2', 'console-token.txt');
+
+function parseArgs(argv) {
+  const out = {
+    base: process.env.QQBOT_CONSOLE_BASE || DEFAULT_BASE,
+    tokenFile: process.env.QQBOT_CONSOLE_TOKEN_FILE || DEFAULT_TOKEN_FILE,
+    token: '',
+    bot: '',
+    peer: '',
+    query: '请回答：记忆暗号是什么？知识库暗号是什么？',
+    waitMs: 120000,
+    keep: false,
+    json: false,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--base') out.base = argv[++i];
+    else if (arg === '--token') out.token = argv[++i];
+    else if (arg === '--token-file') out.tokenFile = argv[++i];
+    else if (arg === '--bot') out.bot = argv[++i];
+    else if (arg === '--peer') out.peer = argv[++i];
+    else if (arg === '--query') out.query = argv[++i];
+    else if (arg === '--wait') out.waitMs = Math.max(5000, Number(argv[++i]) || 120000);
+    else if (arg === '--keep') out.keep = true;
+    else if (arg === '--json') out.json = true;
+    else if (arg === '--help' || arg === '-h') {
+      process.stdout.write('用法: node scripts/verify-recall.mjs [--base URL] [--token TOKEN|--token-file FILE] [--bot ID] [--peer PEER] [--query TEXT] [--wait MS] [--keep] [--json]\n');
+      process.exit(0);
+    } else {
+      process.stderr.write('未知参数: ' + arg + '（--help 查看用法）\n');
+      process.exit(1);
+    }
+  }
+  return out;
+}
+
+const opts = parseArgs(process.argv.slice(2));
+const log = (...args) => { if (!opts.json) console.log(...args); };
+const fail = (code, message) => {
+  if (opts.json) console.log(JSON.stringify({ ok: false, code, error: message }));
+  else console.error('❌ ' + message);
+  process.exit(code);
+};
+
+function readToken() {
+  if (opts.token !== '') return opts.token;
+  try { return fs.readFileSync(opts.tokenFile, 'utf8').trim(); } catch {
+    fail(1, '读不到控制台 token：' + opts.tokenFile + '（可用 --token/--token-file 指定）');
+  }
+}
+
+const token = readToken();
+const base = opts.base.replace(/\/$/u, '');
+const headersJson = { 'content-type': 'application/json', 'x-qqbot-csrf': '1' };
+
+async function login() {
+  let res;
+  try {
+    res = await fetch(base + '/api/auth/login', {
+      method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ token }),
+    });
+  } catch (err) {
+    fail(1, '连不上控制台 ' + base + ': ' + (err && err.message || err));
+  }
+  if (!res.ok) fail(1, '控制台登录失败（HTTP ' + res.status + '）');
+  const cookie = (res.headers.get('set-cookie') || '').split(';')[0];
+  if (!cookie) fail(1, '控制台登录未返回会话 cookie');
+  return cookie;
+}
+
+function makeClient(cookie) {
+  return async function call(method, apiPath, body) {
+    const res = await fetch(base + apiPath, {
+      method,
+      headers: { ...headersJson, cookie },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    const text = await res.text();
+    let json;
+    try { json = JSON.parse(text); } catch { json = { raw: text }; }
+    return { status: res.status, body: json };
+  };
+}
+
+function findSessionFile(sessionId) {
+  const roots = [
+    process.env.DSH_HOME ? path.join(process.env.DSH_HOME, 'sessions') : '',
+    path.join(os.homedir(), '.dsh', 'sessions'),
+  ].filter(Boolean);
+  for (const root of roots) {
+    if (!fs.existsSync(root)) continue;
+    for (const dir of fs.readdirSync(root)) {
+      const file = path.join(root, dir, sessionId, 'session.v4.jsonl.zstd');
+      if (fs.existsSync(file)) return file;
+    }
+  }
+  return '';
+}
+
+function readAssistantText(file) {
+  const events = zlib.zstdDecompressSync(fs.readFileSync(file)).toString('utf8')
+    .split('\n').filter(Boolean)
+    .map((line) => { try { return JSON.parse(line); } catch { return null; } })
+    .filter(Boolean);
+  const texts = [];
+  for (const event of events) {
+    const message = event.data && event.data.message;
+    if (!message || message.role !== 'assistant' || !Array.isArray(message.content)) continue;
+    const text = message.content.filter((item) => item && item.type === 'text').map((item) => item.text).join('');
+    if (text.trim() !== '') texts.push(text);
+  }
+  return texts.join('\n');
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function main() {
+  const cookie = await login();
+  const call = makeClient(cookie);
+  const state = (await call('GET', '/api/state')).body || {};
+  const bots = Array.isArray(state.bots) ? state.bots : [];
+  const botId = opts.bot || (bots[0] && bots[0].id);
+  if (!botId) fail(1, '控制台里没有机器人（先建一个 bot）');
+  const defaultProfile = (Array.isArray(state.profiles) ? state.profiles : []).find((item) => item.isDefault);
+
+  const tag = 'VERIFY' + Math.random().toString(36).slice(2, 8).toUpperCase();
+  const memToken = tag + '-MEM';
+  const kbToken = tag + '-KB';
+  const peer = opts.peer || ('c2c:RECALL-' + tag);
+  const report = { ok: false, tag, botId, peer, steps: {} };
+  log('机器人: ' + botId);
+  log('测试 peer: ' + peer);
+  log('测试暗号: ' + memToken + ' / ' + kbToken);
+
+  // 1) 写入测试记忆与知识库文档
+  const mem = await call('POST', '/api/memories', {
+    botId, text: '记忆暗号是 ' + memToken, kind: 'fact', source: 'verify-recall',
+  });
+  if (mem.status !== 200) fail(1, '写入记忆失败（HTTP ' + mem.status + '）');
+  const kb = await call('POST', '/api/kb/ingest', {
+    botId,
+    title: '暗号知识库 ' + kbToken,
+    text: '本群知识库暗号是 ' + kbToken + '。这是一次自动注入验证的临时文档。',
+    source: 'verify-recall',
+  });
+  const kbId = kb.body && (kb.body.docId || (kb.body.doc && kb.body.doc.id));
+  if (kb.status !== 200 || !kbId) fail(1, '写入知识库失败（HTTP ' + kb.status + '）');
+  log('已写入：记忆 #' + mem.body.id + '，知识库 #' + kbId);
+
+  try {
+    // 2) 预览层：prompt 里是否出现暗号
+    const previewPath = '/api/preview/prompt?bot=' + encodeURIComponent(botId)
+      + (defaultProfile ? '&profile=' + encodeURIComponent(defaultProfile.id) : '')
+      + '&query=' + encodeURIComponent(opts.query);
+    const preview = (await call('GET', previewPath)).body || {};
+    const sections = Array.isArray(preview.sections) ? preview.sections : [];
+    const memSection = sections.find((item) => item.name === 'qqbot:memory');
+    const kbSection = sections.find((item) => item.name === 'qqbot:knowledge');
+    const recall = {
+      memory: String(memSection && memSection.text || '').includes(memToken),
+      knowledge: String(kbSection && kbSection.text || '').includes(kbToken),
+    };
+    report.steps.preview = { memory: recall.memory, knowledge: recall.knowledge, memoryChars: memSection && memSection.chars, knowledgeChars: kbSection && kbSection.chars };
+    log('预览召回：记忆 ' + (recall.memory ? '✅' : '❌') + '，知识库 ' + (recall.knowledge ? '✅' : '❌'));
+
+    // 3) 真模型链路：reset -> followup -> 读 assistant 回复
+    const reset = await call('POST', '/api/actions/reset-peer', { botId, peer });
+    const sessionId = reset.body && reset.body.newSessionId;
+    if (!sessionId) fail(1, 'reset-peer 未返回 sessionId');
+    await call('POST', '/api/actions/debug-followup', { botId, peer, text: opts.query, senderId: 'VERIFY_RECALL' });
+    log('已触发 debug-followup（session ' + sessionId + '），等待模型回复…');
+
+    let reply = '';
+    const deadline = Date.now() + opts.waitMs;
+    while (Date.now() < deadline) {
+      await sleep(2000);
+      const file = findSessionFile(sessionId);
+      if (!file) continue;
+      try {
+        const text = readAssistantText(file);
+        if (text.trim() !== '') { reply = text; break; }
+      } catch { /* 会话文件可能正在写入，继续等 */ }
+    }
+    const used = {
+      memory: reply.includes(memToken),
+      knowledge: reply.includes(kbToken),
+    };
+    report.steps.model = { replied: reply !== '', memory: used.memory, knowledge: used.knowledge, reply: reply.slice(0, 500) };
+    log('模型回复：' + (reply === '' ? '（超时未取到）' : JSON.stringify(reply.slice(0, 200))));
+    log('回复使用：记忆 ' + (used.memory ? '✅' : '❌') + '，知识库 ' + (used.knowledge ? '✅' : '❌'));
+
+    report.ok = recall.memory && recall.knowledge && used.memory && used.knowledge;
+    if (!recall.memory || !recall.knowledge) {
+      fail(2, '召回层未命中（检查记忆/知识库开关、query 与入库内容）');
+    }
+    if (!report.ok) {
+      fail(3, '召回层通过，但模型回复没有使用暗号（可能模型/上下文问题）');
+    }
+    if (opts.json) console.log(JSON.stringify(report));
+    else console.log('\n✅ 通过：记忆与知识库都已自动注入，并且模型在回复里用到了暗号。');
+  } finally {
+    if (!opts.keep) {
+      await call('DELETE', '/api/memories/' + mem.body.id);
+      if (kbId) await call('DELETE', '/api/kb/docs/' + kbId + '?bot=' + encodeURIComponent(botId));
+      await call('POST', '/api/actions/reset-peer', { botId, peer });
+      log('已清理测试数据（--keep 可保留）');
+    }
+  }
+}
+
+main().catch((err) => fail(1, '执行失败: ' + (err && err.stack || err)));