chattercatcher 0.1.14 → 0.1.16

package/README.md

@@ -15,7 +15,7 @@
 </p>
 
 <p align="center">
-  静默保存家庭群里的重要消息和文件，被 @ 时用可追溯引用回答。
+  静默保存家庭群里的重要消息、文件和碎片化上下文，被 @ 时用可追溯引用回答。
 </p>
 
 <p align="center">
@@ -53,7 +53,15 @@
 
 ## 项目状态
 
-ChatterCatcher 是一个早期 MVP。它已经具备飞书长连接接入、本地消息存储、SQLite FTS、SQLite embedding 向量检索、OpenAI-compatible LLM/Embedding、CLI、本地 Web UI 和带引用回答。
+ChatterCatcher 是一个早期 MVP。它已经具备飞书长连接接入、本地消息存储、SQLite FTS、SQLite embedding 向量检索、会话记忆块、OpenAI-compatible LLM/Embedding、CLI、本地 Web UI 和带引用回答。
+
+近期亮点：
+
+- **无 native 向量库依赖**：语义向量写入 SQLite，避免 LanceDB 平台包在不同 macOS/CPU 架构上安装失败。
+- **SQLite FTS + embedding 混合 RAG**：关键词和语义检索并行召回，回答前必须先找到本地证据。
+- **自动识别飞书机器人身份**：可通过 App ID / App Secret 自动获取 `botOpenId`，减少手动配置错误。
+- **会话记忆块**：把 10 分钟窗口、静默 2 分钟后的碎片聊天整理成 episode summary，让“我要发一个 API key”与后续短消息保持上下文关联。
+- **敏感摘要保护**：会话摘要会脱敏疑似 token/API key；原始消息仍保留在本地，方便必要时追溯。
 
 当前核心方向是：
 
@@ -109,15 +117,16 @@ ChatterCatcher 是一个早期 MVP。它已经具备飞书长连接接入、本
 
 | 模块 | 能力 |
 | --- | --- |
-| 飞书 Gateway | 官方长连接、`im.message.receive_v1` 事件、重复投递保护、附件下载入口 |
+| 飞书 Gateway | 官方长连接、`im.message.receive_v1` 事件、自动 `botOpenId` 获取、重复投递保护、附件下载入口 |
 | 消息入库 | 普通文本消息写入 SQLite；`@` 提问直接回答并跳过入库 |
-| RAG 检索 | SQLite FTS 关键词检索、SQLite embedding 向量检索、混合重排、证据来源保留 |
+| 会话记忆块 | 默认 10 分钟窗口 + 2 分钟静默期，把碎片聊天整理成可检索 episode summary，并关联原始消息 |
+| RAG 检索 | SQLite FTS 关键词检索、SQLite embedding 向量检索、episode summary 检索、混合重排、证据来源保留 |
 | 问答 | OpenAI-compatible chat completions、证据不足时说不知道、回答带引用 |
 | 引用格式 | 展示“谁在什么时候说了什么”，避免暴露 `ou_` / `oc_` 等 opaque id |
 | 文件知识源 | 支持 txt、md、json、csv、tsv、log、docx、pdf 导入和解析 |
 | CLI | setup、settings、doctor、gateway、process、index、files、export、restore |
 | Web UI | 本地状态看板、自动刷新、最近消息、群聊、文件库和解析任务 |
-| 隐私 | 配置与密钥分离；导出不包含 API Key、App Secret 或 token |
+| 隐私 | 配置与密钥分离；导出不包含 API Key、App Secret 或 token；会话摘要会脱敏疑似密钥 |
 | 数据管理 | 本地导出/恢复、按消息/文件/群删除本地知识库数据 |
 
 ---
@@ -130,13 +139,16 @@ flowchart LR
   Gateway --> Router["消息路由"]
 
   Router -->|"普通消息"| SQLite["SQLite messages"]
+  SQLite --> Episode["Episode summaries"]
   SQLite --> FTS["SQLite FTS5"]
+  Episode --> EpisodeFTS["Episode FTS5"]
   SQLite --> Indexer["Embedding Indexer"]
   Indexer --> Vectors["SQLite embedding vectors"]
 
   Router -->|"@ 提问"| QA["Question Handler"]
   QA --> Hybrid["Hybrid Retriever"]
   FTS --> Hybrid
+  EpisodeFTS --> Hybrid
   Vectors --> Hybrid
   Hybrid --> LLM["OpenAI-compatible LLM"]
   LLM --> Reply["带引用回复原消息"]
@@ -257,6 +269,7 @@ http://127.0.0.1:3878
 | `chattercatcher gateway status` | 查看 Gateway 状态 |
 | `chattercatcher gateway stop` | 停止 Gateway |
 | `chattercatcher process messages` | 立即处理消息索引任务 |
+| `chattercatcher process episodes` | 立即生成会话记忆块，把碎片聊天整理成可检索摘要 |
 | `chattercatcher index rebuild` | 重建 SQLite embedding 向量索引 |
 | `chattercatcher files add <path...>` | 导入本地文件知识源 |
 | `chattercatcher files jobs` | 查看文件解析任务 |
@@ -265,6 +278,29 @@ http://127.0.0.1:3878
 
 ---
 
+## 会话记忆块
+
+家庭群聊天经常是碎片化的：前一句说明背景，后一句只发一个短词、链接或密钥。只检索单条原始消息时，RAG 很容易丢失上下文。
+
+ChatterCatcher 会在普通消息入库后尝试生成 **会话记忆块（episode summary）**：
+
+1. 按群聊读取尚未整理过的原始消息。
+2. 默认以 10 分钟为窗口聚合相邻聊天。
+3. 当窗口最后一条消息之后安静 2 分钟，认为这一小段对话可以整理。
+4. 调用 LLM 把碎片聊天总结成可检索事实。
+5. 将摘要写入本地 SQLite，并记录它关联的原始消息 ID。
+6. 问答时同时检索原始消息、文件证据和会话记忆块。
+
+会话摘要会脱敏疑似 API key、token、cookie、私钥和 URL 凭据；原始消息仍保存在本地数据库里，回答需要追溯时可以回到原始证据。
+
+手动触发：
+
+```bash
+chattercatcher process episodes
+```
+
+---
+
 ## 本地数据目录
 
 默认数据目录：
@@ -297,6 +333,8 @@ dist/
 - 默认 Web UI 只监听 `127.0.0.1`。
 - 聊天记录、文件内容、OCR 结果和语音转写都视为隐私数据。
 - App Secret、API Key 和 token 与普通配置分开保存。
+- 会话记忆块会脱敏疑似 API key、token、cookie、私钥和 URL 凭据，避免把敏感值扩散到摘要里。
+- 原始消息仍保存在本地数据库，方便在必要时追溯上下文。
 - 导出文件不包含密钥。
 - 事实性回答必须基于检索证据。
 - 检索不到证据时必须说不知道。
@@ -345,6 +383,14 @@ npm install -g chattercatcher@latest
 
 家庭聊天是长期知识库，不应该靠把全部历史消息塞进上下文。RAG 可以控制证据范围、保留来源、降低幻觉，并让回答可追溯。
 
+### 会话记忆块是什么？
+
+会话记忆块是 ChatterCatcher 对一小段碎片聊天生成的本地摘要。它默认等待 10 分钟窗口结束并静默 2 分钟后生成，用来保留“上一句解释背景、下一句只发短内容”的上下文关系。可以运行 `chattercatcher process episodes` 手动触发。
+
+### 会话摘要会不会泄露 API key？
+
+摘要层会脱敏疑似 API key、token、cookie、私钥和 URL 凭据；原始消息仍然只保存在本地数据库，用于必要时追溯证据。
+
 ### Web UI 可以暴露到公网吗？
 
 默认不建议。ChatterCatcher 面向家庭隐私数据，默认只监听 `127.0.0.1`。

package/dist/cli.js

@@ -8,7 +8,7 @@ import fs13 from "fs/promises";
 // package.json
 var package_default = {
   name: "chattercatcher",
-  version: "0.1.14",
+  version: "0.1.16",
   description: "\u672C\u5730\u4F18\u5148\u7684\u98DE\u4E66/Lark \u5BB6\u5EAD\u7FA4\u77E5\u8BC6\u5E93\u673A\u5668\u4EBA",
   type: "module",
   main: "dist/index.js",
@@ -36,6 +36,7 @@ var package_default = {
   },
   scripts: {
     build: "tsup",
+    prepack: "npm run build",
     dev: "tsx src/cli.ts",
     lint: "tsc --noEmit",
     typecheck: "tsc --noEmit",
@@ -52,7 +53,7 @@ var package_default = {
   license: "MIT",
   dependencies: {
     "@inquirer/prompts": "^8.4.2",
-    "@larksuiteoapi/node-sdk": "^1.62.0",
+    "@larksuiteoapi/node-sdk": "^1.62.1",
     "better-sqlite3": "^12.9.0",
     commander: "^14.0.3",
     fastify: "^5.8.5",
@@ -114,7 +115,7 @@ var appConfigSchema = z.object({
   episodes: z.object({
     windowMinutes: z.number().int().positive().default(10),
     quietMinutes: z.number().int().positive().default(2)
-  })
+  }).default({ windowMinutes: 10, quietMinutes: 2 })
 });
 var appSecretsSchema = z.object({
   feishu: z.object({
@@ -1443,6 +1444,29 @@ var EpisodeRepository = class {
       messageIds: window.messages.map((message) => message.id)
     };
   }
+  getEpisodeCount() {
+    const row = this.database.prepare("SELECT count(*) AS count FROM memory_episodes").get();
+    return row.count;
+  }
+  listRecentEpisodes(limit = 20) {
+    return this.database.prepare(
+      `
+          SELECT
+            e.id,
+            e.chat_id AS chatId,
+            c.name AS chatName,
+            e.summary,
+            e.message_count AS messageCount,
+            e.started_at AS startedAt,
+            e.ended_at AS endedAt,
+            e.created_at AS createdAt
+          FROM memory_episodes e
+          JOIN chats c ON c.id = e.chat_id
+          ORDER BY e.ended_at DESC
+          LIMIT ?
+        `
+    ).all(limit);
+  }
   searchEpisodes(query, limit = 8) {
     const ftsQuery = escapeFtsQuery2(query);
     return this.database.prepare(
@@ -2668,6 +2692,13 @@ function assertFeishuConfig(config, secrets) {
     throw new Error("\u98DE\u4E66\u914D\u7F6E\u4E0D\u5B8C\u6574\u3002\u8BF7\u5148\u8FD0\u884C chattercatcher setup \u6216 chattercatcher settings\u3002");
   }
 }
+function formatGatewayStartError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  if (message.includes("PingInterval") || message.includes("system busy") || message.includes("1000040345")) {
+    return new Error(`\u98DE\u4E66\u957F\u8FDE\u63A5\u542F\u52A8\u5931\u8D25\uFF0C\u8BF7\u68C0\u67E5 App ID / App Secret \u662F\u5426\u6B63\u786E\uFF1B\u539F\u59CB\u9519\u8BEF\uFF1A${message}`);
+  }
+  return error instanceof Error ? error : new Error(message);
+}
 function createFeishuEventDispatcher(options) {
   const answeredMessageIds = /* @__PURE__ */ new Set();
   return new lark2.EventDispatcher({}).register({
@@ -2772,7 +2803,11 @@ function createFeishuGateway(options) {
   });
   return {
     async start() {
-      await wsClient.start({ eventDispatcher });
+      try {
+        await wsClient.start({ eventDispatcher });
+      } catch (error) {
+        throw formatGatewayStartError(error);
+      }
     },
     stop() {
       wsClient.close({ force: true });
@@ -3626,6 +3661,10 @@ function buildHtml() {
             <h2>\u6700\u8FD1\u6D88\u606F</h2>
             <div id="messages" class="empty">\u6B63\u5728\u8BFB\u53D6...</div>
           </section>
+          <section>
+            <h2>\u4F1A\u8BDD\u8BB0\u5FC6</h2>
+            <div id="episodes" class="empty">\u6B63\u5728\u8BFB\u53D6...</div>
+          </section>
         </div>
         <aside>
           <section>
@@ -3652,6 +3691,7 @@ function buildHtml() {
     <script>
       const metrics = document.querySelector("#metrics");
       const messages = document.querySelector("#messages");
+      const episodes = document.querySelector("#episodes");
       const chats = document.querySelector("#chats");
       const files = document.querySelector("#files");
       const fileJobs = document.querySelector("#file-jobs");
@@ -3715,6 +3755,7 @@ function buildHtml() {
           ["Gateway", formatGatewayValue(status.gateway), formatGatewayNote(status.gateway), gatewayClass],
           ["\u7FA4\u804A", status.data.chats, "\u672C\u5730\u7FA4\u804A\u6570", ""],
           ["\u6D88\u606F", status.data.messages, "\u5DF2\u5165\u5E93\u6D88\u606F", ""],
+          ["\u4F1A\u8BDD\u8BB0\u5FC6", status.data.episodes, "\u5DF2\u751F\u6210\u6458\u8981", ""],
           ["\u6587\u4EF6", status.data.files, "\u6587\u4EF6\u77E5\u8BC6\u6E90", ""],
         ].map(([label, value, note, extra]) => \`
           <div class="metric">
@@ -3748,6 +3789,29 @@ function buildHtml() {
         \`;
       }
 
+      function renderEpisodes(items) {
+        if (items.length === 0) {
+          episodes.className = "empty";
+          episodes.textContent = "\u8FD8\u6CA1\u6709\u4F1A\u8BDD\u8BB0\u5FC6\u3002\u9ED8\u8BA4\u5728 10 \u5206\u949F\u7A97\u53E3\u9759\u9ED8 2 \u5206\u949F\u540E\u751F\u6210\uFF0C\u4E5F\u53EF\u4EE5\u8FD0\u884C chattercatcher process episodes \u624B\u52A8\u89E6\u53D1\u3002";
+          return;
+        }
+        episodes.className = "";
+        episodes.innerHTML = \`
+          <div class="message-list">
+              \${items.map((item) => \`
+                <article class="message-item">
+                  <div class="message-meta">
+                    <span>\${escapeHtml(formatDateTime(item.startedAt))} - \${escapeHtml(formatDateTime(item.endedAt))}</span>
+                    <span>\${escapeHtml(displayChatName(item.chatName, "feishu"))}</span>
+                    <span>\${escapeHtml(item.messageCount)} \u6761\u6D88\u606F</span>
+                  </div>
+                  <div class="message-body">\${escapeHtml(item.summary)}</div>
+                </article>
+              \`).join("")}
+          </div>
+        \`;
+      }
+
       function renderChats(items) {
         if (items.length === 0) {
           chats.className = "empty";
@@ -3823,15 +3887,17 @@ function buildHtml() {
       }
 
       async function load() {
-        const [status, recent, chatList, fileList, jobList] = await Promise.all([
+        const [status, recent, episodeList, chatList, fileList, jobList] = await Promise.all([
           fetch("/api/status").then((response) => response.json()),
           fetch("/api/messages/recent?limit=20").then((response) => response.json()),
+          fetch("/api/episodes?limit=10").then((response) => response.json()),
           fetch("/api/chats").then((response) => response.json()),
           fetch("/api/files").then((response) => response.json()),
           fetch("/api/file-jobs").then((response) => response.json()),
         ]);
         renderMetrics(status);
         renderMessages(recent.items);
+        renderEpisodes(episodeList.items);
         renderChats(chatList.items);
         renderFiles(fileList.items);
         renderFileJobs(jobList.items);
@@ -3880,6 +3946,7 @@ function createWebApp(config) {
   const app = Fastify({ logger: false });
   const database = openDatabase(config);
   const messages = new MessageRepository(database);
+  const episodes = new EpisodeRepository(database);
   const fileJobs = new FileJobRepository(database);
   app.addHook("onClose", async () => {
     database.close();
@@ -3890,6 +3957,7 @@ function createWebApp(config) {
     data: {
       chats: messages.getChatCount(),
       messages: messages.getMessageCount(),
+      episodes: episodes.getEpisodeCount(),
       files: messages.listFiles(1e3).length
     },
     rag: {
@@ -3925,6 +3993,12 @@ function createWebApp(config) {
       items: messages.listRecentMessages(limit)
     };
   });
+  app.get("/api/episodes", async (request) => {
+    const limit = parseLimit(request.query.limit, 20, 100);
+    return {
+      items: episodes.listRecentEpisodes(limit)
+    };
+  });
   app.post("/api/process/messages", async (_request, reply) => {
     try {
       return await processMessagesNow({