@anxi78/dsh-yuanbao 0.2.1 → 0.3.0

package/README.md

@@ -1,5 +1,7 @@
 # dsh-yuanbao
 
+[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)
+
 中文 | [English](./README_EN.md)
 
 基于 [deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) 的元宝 IM 通道插件，将元宝开放平台 WebSocket 消息接入 dsh agent runtime。
@@ -19,7 +21,7 @@ npm: [`@anxi78/dsh-yuanbao`](https://www.npmjs.com/package/@anxi78/dsh-yuanbao)
 ## 与上游的差异
 
 > 对比基准：上游 `9446ebd`（fix: support yuanbao group replies）
-> 统计：**18 个文件，+2591 / -70 行**
+> 统计：**23 个文件，+4012 / -115 行**
 
 ### 一、新增功能
 
@@ -75,6 +77,73 @@ pinnedSessionId: ''                  # pinned 模式下的目标会话 ID
 
 **留空自动回退到 per-peer**，不会因为配置错误把消息塞进空会话。
 
+#### 5. 群聊上下文
+
+**@bot 时能看到群里刚才聊了什么**，而不只是当前这一条。
+
+| 项 | 说明 |
+|---|---|
+| `src/chat-history.ts` | 文本历史（每会话 200 条）+ 媒体历史（50 条）+ 最后一条消息追踪 |
+| `src/inbound.ts` | 在 @bot 检查**之前**先记录，没 @bot 的消息也会进历史 |
+
+拼进上下文的格式：
+
+```
+[群聊最近消息（按时间顺序，最后一条最旧→最新）]
+Alice: 刚才那个方案怎么样
+Bob: 我觉得可以
+[以上是 @bot 之前的消息，下面是本次 @bot 的内容]
+```
+
+回复完成后按 `historyLimit` 清掉已消费的部分，避免下次重复。
+
+配置项：
+
+```yaml
+historyLimit: 20    # 默认 20 条，0 = 关闭
+```
+
+**持久化**：历史落盘到 `~/.dsh/.yuanbao-history.json`，重启不再失忆。
+（只存文本，不存媒体 —— 媒体的 url 带签名时效，过期了也用不了。）
+
+#### 6. 发图后立刻 @bot，自动带上那张图
+
+**场景**：用户先发一张图（这条 @ 不到 bot），紧接着 @bot 问「这张图是什么」。
+
+**触发条件（缺一不可）：**
+
+| 条件 | 说明 |
+|---|---|
+| **同一个人** | 上一条必须是当前发送者发的 |
+| **必须是最后一条** | 中间有任何人的消息都不算，**包括自己发的文字** |
+| **只对图片** | 文件不生效，图+文件混合也不生效 |
+
+实现要点：`chatLastMessage` 单独追踪「最后一条消息」——文本历史只记有正文的消息，
+纯图片会被跳过，所以需要独立的记录来判断上一条到底是什么。
+
+#### 7. 引用消息（文字 + 媒体）
+
+**引用信息不在 `msg_body`，而在消息级的 `cloud_custom_data`：**
+
+```json
+{ "quote": { "desc": "被引用的文字", "type": 2, "id": "msgId" } }
+```
+
+`type`：1 文字 / 2 图片 / 3 文件 / 4 视频 / 5 语音。
+
+| 引用类型 | 处理 |
+|---|---|
+| **文字** | 格式化为 `> [引用消息 from 某人]: 内容` |
+| **媒体** | `desc` 为空，按 `id` 回查媒体历史 → 换取真实 COS 地址 → 下载 → 作为附件 |
+
+**关键坑**：入站媒体给的是 `hunyuan.tencent.com/api/resource/download?resourceId=xxx`，
+直接 GET 返回 **401**。必须先调 `/api/resource/v1/download` 换取真正的 COS 地址。
+
+#### 8. 设置面板持久化
+
+设置存到 `~/.dsh/.yuanbao-settings.json`，重启不丢。
+（为什么不写 `cordis.patch.yml`：那是静态配置，改一次要手写 YAML 再重启。）
+
 ### 二、修复的问题
 
 #### 1. 群消息发送失败（`bot_id is required`）
@@ -144,34 +213,38 @@ Cordis 插件读取未声明的服务会抛错。新增的 `createServiceReader`
 
 ### 四、文件清单
 
-**新增（8 个）**
+**新增（10 个）**
 
 ```
 assets/builtin-stickers.json   542 行   内置表情库
-client.js                      219 行   设置面板
-src/media.ts                   203 行   入站媒体
+client.js                      327 行   设置面板
+src/media.ts                   207 行   入站媒体
 src/outbound-media.ts          363 行   出站媒体
 src/services.ts                 59 行   服务读取封装
 src/stickers.ts                131 行   表情包
 src/tools.ts                   407 行   Agent 工具
+src/chat-history.ts            363 行   文本/媒体历史、持久化
+src/quote.ts                   157 行   引用消息解析
 src/dsh-tools.d.ts              13 行   工具类型声明
 ```
 
-**修改（10 个）**
+**修改（13 个）**
 
 ```
-src/bridge.ts                   +71    复用 gateway account、注册工具
-src/transport/sender.ts        +173    发送结果传播、身份校验
-src/transport/outbound.ts      +116    媒体消息支持
-src/session/manager.ts         +104    会话路由
-src/inbound.ts                 +106    @提及判定、媒体提取
-src/index.ts                    +91    服务注入、配置
-src/gateway/index.ts            +33    account 暴露、httpAuth
-src/config.ts                    +6    会话路由配置
-src/types.ts                     +8    类型定义
-package.json                    +16    client 入口声明
+src/inbound.ts                 主要改动  @提及判定、媒体提取、历史、自动附图
+src/transport/sender.ts         +265    发送结果传播、身份校验、COS 地址换取
+src/transport/outbound.ts       +116    媒体消息支持
+src/session/manager.ts          +104    会话路由
+src/bridge.ts                    +71    复用 gateway account、注册工具
+src/index.ts                     +91    服务注入、配置、历史恢复
+src/gateway/index.ts             +33    account 暴露、httpAuth
+src/config.ts                    +10    会话路由、historyLimit
+src/types.ts                     +10    类型定义
+package.json                     +16    client 入口声明
 ```
 
+**总计**：`23 files changed, 4012 insertions(+), 115 deletions(-)`
+
 ### 五、同步上游
 
 ```bash
@@ -394,6 +467,7 @@ agent-default-model:
 | `sessionIdleTimeout` | number | `1800000` | 会话闲置超时，默认 30 分钟 |
 | `sessionMode` | `per-peer` / `pinned` | `per-peer` | **本分支新增**：会话路由模式 |
 | `pinnedSessionId` | string | `''` | **本分支新增**：pinned 模式下的目标会话 ID，留空回退 per-peer |
+| `historyLimit` | number | `20` | **本分支新增**：群聊上下文条数，@bot 时带上最近 N 条；0 = 关闭 |
 | `processingTimeoutMs` | number | `120000` | Agent 处理超时 |
 | `maxReconnectAttempts` | number | `100` | WebSocket 最大重连次数 |
 | `access.c2cMode` | `open` / `allowlist` / `disabled` | `open` | 私聊访问控制 |

package/README_EN.md

@@ -1,5 +1,7 @@
 # dsh-yuanbao
 
+[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)
+
 [中文](./README.md) | English
 
 A Yuanbao IM channel plugin for [deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) (dsh). It connects Yuanbao Open Platform WebSocket messages to the dsh agent runtime.

package/client.js

@@ -13,7 +13,7 @@
  *   slots.inject('settings.section', () => slots.register({...}, () => h(Panel)))
  */
 window.__ModuleLoader__.load({
-  id: 'dsh-yuanbao',
+  id: '@anxi78/dsh-yuanbao',
   factory: (require) => {
     const React = require('react')
     const h = React.createElement
@@ -309,10 +309,10 @@ select.yb-input{font-family:inherit;cursor:pointer;appearance:none;background-im
       inject: ['slots', 'sessions'],
       apply(ctx) {
         const style = document.createElement('style')
-        style.setAttribute('data-plugin-css', 'dsh-yuanbao')
+        style.setAttribute('data-plugin-css', '@anxi78/dsh-yuanbao')
         style.textContent = CSS
         document.head.appendChild(style)
-        ctx.effect(() => () => style.remove(), 'dsh-yuanbao: 设置页样式')
+        ctx.effect(() => () => style.remove(), '@anxi78/dsh-yuanbao: 设置页样式')
 
         const slots = (typeof ctx.get === 'function' ? ctx.get('slots') : undefined) || ctx.slots
         if (!slots) return

package/cordis.patch.yml

@@ -1,6 +1,6 @@
 - insert:
     - id: dsh-yuanbao
-      name: 'dsh-yuanbao'
+      name: '@anxi78/dsh-yuanbao'
       config:
         appKey: !!js process.env.YUANBAO_APP_KEY ?? ''
         appSecret: !!js process.env.YUANBAO_APP_SECRET ?? ''

package/dist/chat-history.d.ts

@@ -1,15 +1,20 @@
 /**
- * 聊天媒体历史
- * =============
- * 元宝的「引用消息」只带被引用消息的 id 和类型，媒体类引用（图片/文件）
- * 的 desc 是空的。要还原出真实内容，必须靠本地缓存：
+ * 聊天历史
+ * =========
+ * 两类历史，生命周期不同：
  *
- *   收到媒体消息 → 记下 { messageId, medias[] }
- *   收到引用消息 → 按 quote.id 查缓存 → 找到原来的 URL 和文件名
+ *   1. 文本历史（chatTextHistories）
+ *      群里每条消息都记下来，@bot 时拼进上下文，让 agent 知道刚才在聊什么。
+ *      回复完成后按 limit 清空已消费的部分。
  *
- * 为什么要独立于消息历史：
- *   群聊里 @bot 之后消息历史会被清理，但引用随时可能指向更早的图片。
- *   媒体历史单独存，生命周期更长。
+ *   2. 媒体历史（chatMediaHistories）
+ *      记录消息携带的图片/文件，供「引用消息」按 id 回查。
+ *      独立存储：@bot 后文本历史会被清理，但引用随时可能指向更早的图片。
+ *
+ * 为什么要自己维护文本历史：
+ *   元宝只把「@bot 的那条消息」推给插件，群里的其他消息插件根本收不到。
+ *   等等——实际上群消息都会推送，只是没有 @ 时被 requireMention 丢掉了。
+ *   所以在丢弃之前先记进历史，@bot 时就能带上上下文。
  */
 import type { InboundMedia } from './media.js';
 /** 一条媒体历史记录 */
@@ -27,13 +32,80 @@ export type MediaHistoryEntry = {
         kind?: 'image' | 'file';
     }>;
 };
+/** 一条文本历史记录 */
+export type TextHistoryEntry = {
+    /** 消息 id */
+    messageId?: string;
+    /** 发送者昵称（优先）或账号 */
+    sender: string;
+    /** 发送者账号（稳定标识） */
+    senderId?: string;
+    /** 消息正文（已去除 @bot 的部分） */
+    body: string;
+    /** 消息时间戳（ms） */
+    timestamp: number;
+};
 /** chatKey → 媒体历史 */
 export declare const chatMediaHistories: Map<string, MediaHistoryEntry[]>;
+/** chatKey → 文本历史 */
+export declare const chatTextHistories: Map<string, TextHistoryEntry[]>;
+/**
+ * chatKey → 该会话收到的**最后一条消息**的元信息。
+ *
+ * 和 chatTextHistories 的区别：文本历史只记有正文的消息，
+ * 纯图片消息没有正文会被跳过。但「发图后立刻 @bot」需要知道
+ * 上一条消息**到底是什么**（哪怕它没有文字），所以单独记一份。
+ */
+export type LastMessageEntry = {
+    /** 消息 id */
+    messageId?: string;
+    /** 发送者账号（稳定标识，用于判断是不是同一个人） */
+    senderId?: string;
+    /** 发送者昵称 */
+    senderNickname?: string;
+    /** 这条消息携带的媒体类型（image/file/undefined） */
+    mediaKinds: Array<'image' | 'file'>;
+    /** 媒体列表（供自动附图使用） */
+    medias: Array<{
+        url: string;
+        name?: string;
+        kind?: 'image' | 'file';
+    }>;
+    /** 记录时间 */
+    timestamp: number;
+};
+export declare const chatLastMessage: Map<string, LastMessageEntry>;
 /**
  * 生成会话级缓存键。
  * 群聊用 group:{groupCode}，私聊用 direct:{fromAccount}。
  */
 export declare function deriveChatKey(isGroup: boolean, groupCode?: string, fromAccount?: string): string;
+/**
+ * 记录一条群聊文本消息。
+ *
+ * 空正文（比如纯图片消息）不记 —— 图片走媒体历史，
+ * 这里记了也只是空行，反而污染上下文。
+ */
+export declare function rememberText(chatKey: string, entry: {
+    messageId?: string;
+    sender: string;
+    senderId?: string;
+    body: string;
+}): void;
+/**
+ * 取出最近 limit 条文本历史。
+ *
+ * 返回的是**当前消息之前**的历史 —— 调用方应在记录当前消息之前调用，
+ * 否则当前消息会重复出现（一次在历史里，一次在正文里）。
+ */
+export declare function recentText(chatKey: string, limit: number): TextHistoryEntry[];
+/**
+ * 消费掉最近 limit 条历史。
+ *
+ * 回复完成后调用：这些内容已经进了 agent 的上下文，
+ * 下次再拼一遍就是重复。
+ */
+export declare function consumeText(chatKey: string, limit: number): void;
 /**
  * 记录一条消息携带的媒体。
  *
@@ -50,5 +122,39 @@ export declare function rememberMedia(chatKey: string, entry: {
  * 从后往前找 —— 引用通常指向较近的消息。
  */
 export declare function findMediaByMessageId(chatKey: string, messageId: string | undefined): MediaHistoryEntry | undefined;
-/** 清空某个会话的历史（会话结束时调用） */
+/**
+ * 记录「这个会话收到的最后一条消息」。
+ *
+ * 每条消息都要调（包括没有正文的纯图片消息），
+ * 这样「发图后立刻 @bot」才能判断上一条到底是什么。
+ */
+export declare function rememberLastMessage(chatKey: string, entry: {
+    messageId?: string;
+    senderId?: string;
+    senderNickname?: string;
+    medias: InboundMedia[];
+}): void;
+/** 取这个会话的最后一条消息（没有则 undefined） */
+export declare function lastMessage(chatKey: string): LastMessageEntry | undefined;
+/**
+ * 取最近一条媒体记录。
+ *
+ * 用于「发图后立刻 @bot」的自动附图机制：需要判断上一条消息
+ * 是不是同一人发的图片。只看最后一条，不做模糊匹配。
+ */
+export declare function latestMedia(chatKey: string): MediaHistoryEntry | undefined;
+/** 清空某个会话的全部历史（会话结束时调用） */
 export declare function clearChatHistory(chatKey: string): void;
+/** 安排一次防抖写盘（200ms 内的多次改动合并成一次） */
+export declare function schedulePersist(logger?: {
+    warn: (m: string) => void;
+}): void;
+/**
+ * 启动时从磁盘恢复文本历史。
+ *
+ * 只恢复最近的条目，过旧的历史带进上下文反而干扰。
+ */
+export declare function loadPersistedHistory(logger?: {
+    info: (m: string) => void;
+    warn: (m: string) => void;
+}): Promise<void>;

package/dist/chat-history.js

@@ -1,20 +1,30 @@
 /**
- * 聊天媒体历史
- * =============
- * 元宝的「引用消息」只带被引用消息的 id 和类型，媒体类引用（图片/文件）
- * 的 desc 是空的。要还原出真实内容，必须靠本地缓存：
+ * 聊天历史
+ * =========
+ * 两类历史，生命周期不同：
  *
- *   收到媒体消息 → 记下 { messageId, medias[] }
- *   收到引用消息 → 按 quote.id 查缓存 → 找到原来的 URL 和文件名
+ *   1. 文本历史（chatTextHistories）
+ *      群里每条消息都记下来，@bot 时拼进上下文，让 agent 知道刚才在聊什么。
+ *      回复完成后按 limit 清空已消费的部分。
  *
- * 为什么要独立于消息历史：
- *   群聊里 @bot 之后消息历史会被清理，但引用随时可能指向更早的图片。
- *   媒体历史单独存，生命周期更长。
+ *   2. 媒体历史（chatMediaHistories）
+ *      记录消息携带的图片/文件，供「引用消息」按 id 回查。
+ *      独立存储：@bot 后文本历史会被清理，但引用随时可能指向更早的图片。
+ *
+ * 为什么要自己维护文本历史：
+ *   元宝只把「@bot 的那条消息」推给插件，群里的其他消息插件根本收不到。
+ *   等等——实际上群消息都会推送，只是没有 @ 时被 requireMention 丢掉了。
+ *   所以在丢弃之前先记进历史，@bot 时就能带上上下文。
  */
-/** 每个会话保留多少条记录 */
-const MAX_ENTRIES = 50;
+/** 媒体历史每个会话保留多少条 */
+const MEDIA_MAX_PER_CHAT = 50;
+/** 文本历史每个会话最多保留多少条（防止无限增长） */
+const TEXT_MAX_PER_CHAT = 200;
 /** chatKey → 媒体历史 */
 export const chatMediaHistories = new Map();
+/** chatKey → 文本历史 */
+export const chatTextHistories = new Map();
+export const chatLastMessage = new Map();
 /**
  * 生成会话级缓存键。
  * 群聊用 group:{groupCode}，私聊用 direct:{fromAccount}。
@@ -24,6 +34,68 @@ export function deriveChatKey(isGroup, groupCode, fromAccount) {
         return `group:${groupCode}`;
     return `direct:${fromAccount || 'unknown'}`;
 }
+// ---------------------------------------------------------------------------
+// 文本历史
+// ---------------------------------------------------------------------------
+/**
+ * 记录一条群聊文本消息。
+ *
+ * 空正文（比如纯图片消息）不记 —— 图片走媒体历史，
+ * 这里记了也只是空行，反而污染上下文。
+ */
+export function rememberText(chatKey, entry) {
+    const body = (entry.body || '').trim();
+    if (!body)
+        return;
+    const list = chatTextHistories.get(chatKey) ?? [];
+    list.push({
+        messageId: entry.messageId,
+        sender: entry.sender,
+        senderId: entry.senderId,
+        body,
+        timestamp: Date.now(),
+    });
+    while (list.length > TEXT_MAX_PER_CHAT)
+        list.shift();
+    chatTextHistories.set(chatKey, list);
+}
+/**
+ * 取出最近 limit 条文本历史。
+ *
+ * 返回的是**当前消息之前**的历史 —— 调用方应在记录当前消息之前调用，
+ * 否则当前消息会重复出现（一次在历史里，一次在正文里）。
+ */
+export function recentText(chatKey, limit) {
+    if (limit <= 0)
+        return [];
+    const list = chatTextHistories.get(chatKey);
+    if (!list || list.length === 0)
+        return [];
+    return list.slice(-limit);
+}
+/**
+ * 消费掉最近 limit 条历史。
+ *
+ * 回复完成后调用：这些内容已经进了 agent 的上下文，
+ * 下次再拼一遍就是重复。
+ */
+export function consumeText(chatKey, limit) {
+    if (limit <= 0) {
+        chatTextHistories.delete(chatKey);
+        return;
+    }
+    const list = chatTextHistories.get(chatKey);
+    if (!list)
+        return;
+    if (list.length <= limit) {
+        chatTextHistories.delete(chatKey);
+        return;
+    }
+    chatTextHistories.set(chatKey, list.slice(0, list.length - limit));
+}
+// ---------------------------------------------------------------------------
+// 媒体历史
+// ---------------------------------------------------------------------------
 /**
  * 记录一条消息携带的媒体。
  *
@@ -43,7 +115,7 @@ export function rememberMedia(chatKey, entry) {
         medias,
     });
     // LRU：超出上限就丢最旧的
-    while (list.length > MAX_ENTRIES)
+    while (list.length > MEDIA_MAX_PER_CHAT)
         list.shift();
     chatMediaHistories.set(chatKey, list);
 }
@@ -65,7 +137,139 @@ export function findMediaByMessageId(chatKey, messageId) {
     }
     return undefined;
 }
-/** 清空某个会话的历史（会话结束时调用） */
+/**
+ * 记录「这个会话收到的最后一条消息」。
+ *
+ * 每条消息都要调（包括没有正文的纯图片消息），
+ * 这样「发图后立刻 @bot」才能判断上一条到底是什么。
+ */
+export function rememberLastMessage(chatKey, entry) {
+    const medias = (entry.medias || [])
+        .filter(m => m.url)
+        .map(m => ({ url: m.url, name: m.name, kind: m.kind }));
+    chatLastMessage.set(chatKey, {
+        messageId: entry.messageId,
+        senderId: entry.senderId,
+        senderNickname: entry.senderNickname,
+        mediaKinds: medias.map(m => m.kind).filter((k) => Boolean(k)),
+        medias,
+        timestamp: Date.now(),
+    });
+}
+/** 取这个会话的最后一条消息（没有则 undefined） */
+export function lastMessage(chatKey) {
+    return chatLastMessage.get(chatKey);
+}
+/**
+ * 取最近一条媒体记录。
+ *
+ * 用于「发图后立刻 @bot」的自动附图机制：需要判断上一条消息
+ * 是不是同一人发的图片。只看最后一条，不做模糊匹配。
+ */
+export function latestMedia(chatKey) {
+    const list = chatMediaHistories.get(chatKey);
+    if (!list || list.length === 0)
+        return undefined;
+    return list[list.length - 1];
+}
+/** 清空某个会话的全部历史（会话结束时调用） */
 export function clearChatHistory(chatKey) {
     chatMediaHistories.delete(chatKey);
+    chatTextHistories.delete(chatKey);
+    chatLastMessage.delete(chatKey);
+}
+// ---------------------------------------------------------------------------
+// 持久化
+// ---------------------------------------------------------------------------
+// 历史原本只在内存里，DSH 一重启就全没了。
+// 这里落盘到 ~/.dsh/.yuanbao-history.json，启动时读回。
+//
+// 设计取舍：
+//   · 只存文本历史，不存媒体历史 —— 媒体的 url 有签名时效，过期了也用不了
+//   · 写入做防抖，避免每条消息都碰一次磁盘
+//   · 读取失败静默忽略，历史丢失不能阻断插件启动
+const HISTORY_FILE = '.yuanbao-history.json';
+/** 每个会话最多落盘多少条（比内存上限小，控制文件体积） */
+const PERSIST_MAX_PER_CHAT = 50;
+function historyPath() {
+    const home = process.env.DSH_HOME
+        || (process.env.HOME ? `${process.env.HOME}/.dsh` : '');
+    if (!home)
+        return '';
+    return `${home}/${HISTORY_FILE}`;
+}
+let persistTimer;
+let persistPending = false;
+/** 把当前文本历史写入磁盘（异步、防抖、失败只警告） */
+async function flushHistory(logger) {
+    const file = historyPath();
+    if (!file)
+        return;
+    const chats = {};
+    for (const [key, list] of chatTextHistories) {
+        if (list.length === 0)
+            continue;
+        chats[key] = list.slice(-PERSIST_MAX_PER_CHAT);
+    }
+    const payload = { version: 1, chats };
+    try {
+        const { writeFile, mkdir } = await import('node:fs/promises');
+        const { dirname } = await import('node:path');
+        await mkdir(dirname(file), { recursive: true });
+        await writeFile(file, `${JSON.stringify(payload)}\n`, 'utf8');
+    }
+    catch (error) {
+        logger?.warn(`history persist failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/** 安排一次防抖写盘（200ms 内的多次改动合并成一次） */
+export function schedulePersist(logger) {
+    if (!historyPath())
+        return;
+    persistPending = true;
+    if (persistTimer)
+        return;
+    persistTimer = setTimeout(() => {
+        persistTimer = undefined;
+        if (!persistPending)
+            return;
+        persistPending = false;
+        void flushHistory(logger);
+    }, 200);
+    // 不让定时器拖住进程退出
+    if (typeof persistTimer === 'object' && persistTimer && 'unref' in persistTimer) {
+        persistTimer.unref();
+    }
+}
+/**
+ * 启动时从磁盘恢复文本历史。
+ *
+ * 只恢复最近的条目，过旧的历史带进上下文反而干扰。
+ */
+export async function loadPersistedHistory(logger) {
+    const file = historyPath();
+    if (!file)
+        return;
+    try {
+        const { readFile } = await import('node:fs/promises');
+        const raw = await readFile(file, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || parsed.version !== 1 || !parsed.chats)
+            return;
+        let restored = 0;
+        for (const [key, list] of Object.entries(parsed.chats)) {
+            if (!Array.isArray(list) || list.length === 0)
+                continue;
+            chatTextHistories.set(key, list.slice(-TEXT_MAX_PER_CHAT));
+            restored += list.length;
+        }
+        logger?.info(`history restored: ${restored} entries across ${Object.keys(parsed.chats).length} chats`);
+    }
+    catch (error) {
+        // 文件不存在是正常的首次启动
+        const msg = error instanceof Error ? error.message : String(error);
+        if (!msg.includes('ENOENT')) {
+            logger?.warn(`history load failed: ${msg}`);
+        }
+    }
 }

package/dist/config.js

@@ -26,6 +26,9 @@ const schemaObject = Schema.object({
     pinnedSessionId: Schema.string()
         .default('')
         .description('sessionMode=pinned 时使用的会话 ID（在 DSH 会话列表里能看到，形如 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx）。留空则回退到 per-peer'),
+    historyLimit: Schema.number()
+        .default(20)
+        .description('群聊上下文条数：@bot 时把最近 N 条群消息一起带给 agent。设为 0 关闭'),
     processingTimeoutMs: Schema.number().default(120000).description('Agent processing timeout in ms'),
     maxReconnectAttempts: Schema.number().default(100).description('Maximum WebSocket reconnect attempts'),
     access: Schema.object({