chattercatcher 0.2.5 → 0.2.7

package/AGENTS.md

@@ -116,6 +116,16 @@ npm run build
 - 后台任务必须能从 CLI 和 Web UI 观察。
 - 核心本地运行不能依赖 SaaS-only 服务。
 
+## 发布纪律
+
+每次发版必须：
+
+- 更新 `CHANGELOG.md`，按时间倒序记录本次版本的新增、修复和变更。
+- 确保 `package.json` 的 `files` 字段包含 `CHANGELOG.md`。
+- `CHANGELOG.md` 使用中文，格式参考 https://keepachangelog.com/zh-CN/1.1.0/。
+- 版本号遵守 SemVer。
+- Claude 负责版本 bump、PR 创建和 merge；用户负责 `npm publish`。
+
 ## 文档规则
 
 - 以后所有项目文档默认使用中文。

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+## [0.2.7] - 2026-05-30
+
+### Added
+- 个人档案（Personal Profiles）：自动从群聊消息中识别成员，建立以人物为中心的知识档案。每个成员拥有独立的 profile entries，按 category 分类，包含事实（fact）和推断（inferred）两种类型。
+- Dream 处理器：周期性批量分析新消息，自动提取人物档案变化。Dream 只基于当前批次消息输出档案更新，带证据引用和置信度评分。
+- 档案 RAG 工具：`get_person_profile` 和 `search_person_messages` 两个 Agent 工具，让问答系统可以检索人物档案并按人物搜索消息来辅助回答问题。
+- 档案修正：支持通过 Web API 显式纠正或删除档案条目，用户可指定修正理由和证据。
+- 档案 Web API：`GET /api/persons`、`GET /api/persons/:personId/profile`、`GET /api/persons/:personId/messages`、`POST /api/persons/:personId/profile/entries/:entryId/correct` 和 `DELETE /api/persons/:personId/profile/entries/:entryId` 等接口，Web UI 可展示和维护人物档案。
+- 发布要求：`CHANGELOG.md` 纳入 npm 发布包，每次发版必须更新。
+
+## [0.2.5] - 2026-05-27
+
+### Added
+- Web UI QA trace 详情页：展示推理过程、工具调用、证据和回答细节。
+
+### Fixed
+- 飞书消息使用 Markdown post 格式发送，修复纯文本兼容性问题。
+
+## [0.2.2] - 2026-05-25
+
+### Fixed
+- 所有 LLM prompt 统一使用北京时间（Asia/Shanghai），修复 UTC 时间导致的日期偏差。
+
+## [0.2.0] - 2026-05-24
+
+### Added
+- 飞书回复支持 Markdown 富文本格式。
+- Web UI 重构为液态玻璃暗色主题。
+
+## [0.1.32] - 2026-05-23
+
+### Fixed
+- 检测飞书富文本内容错误并自动降级。
+
+## [0.1.31] - 2026-05-22
+
+### Fixed
+- 限制飞书富文本回退逻辑，避免格式错误。
+
+## [0.1.27] - 2026-05-20
+
+### Added
+- 初始公开发布：本地飞书/Lark 家庭群 RAG 记忆机器人。
+- 飞书长连接 Gateway。
+- SQLite FTS5 + embedding 混合 RAG 检索。
+- 会话记忆块（episode summary）。
+- 群内自然语言定时任务。
+- 文件知识源导入（txt/md/json/csv/tsv/log/docx/pdf）。
+- 本地 Web UI。
+- 相对时间归一化。

package/README.md

@@ -57,13 +57,15 @@ ChatterCatcher 是一个早期 MVP。它已经具备飞书长连接接入、本
 
 近期亮点：
 
+- **个人档案（Personal Profiles）**：自动识别群聊中的成员，为每个人建立独立的知识档案。档案条目按 category 分类，区分事实（fact）和推断（inferred），带置信度评分和证据引用。
+- **Dream 处理器**：周期性批量分析新消息，自动提取人物档案变化。Dream 只基于当前批次消息输出更新，不回顾全部历史，保证处理效率。
 - **无 native 向量库依赖**：语义向量写入 SQLite，避免 LanceDB 平台包在不同 macOS/CPU 架构上安装失败。
 - **SQLite FTS + embedding 混合 RAG**：关键词和语义检索并行召回，回答前必须先找到本地证据。
-- **相对时间归一化**：自动将”今天””明天””今晚”等相对时间表述转换为具体日期。所有 LLM 路径（会话摘要、RAG 问答、Agent 工具循环）统一注入当前时间并强调时间推导规则，让回答中的日期始终准确。
-- **群内定时任务**：在群里用自然语言创建 cron 定时任务，支持”每天 9 点总结昨天群聊”等日常需求。创建、查看、删除都在群里一句话搞定，任务限定当前群聊不能跨群。
-- **工具循环智能兜底**：当 Agent 多轮工具调用达到上限时，自动用对话历史生成最终答案，不再返回含混的”操作已提交”提示。
+- **相对时间归一化**：自动将"今天""明天""今晚"等相对时间表述转换为具体日期。所有 LLM 路径（会话摘要、RAG 问答、Agent 工具循环）统一注入当前时间并强调时间推导规则，让回答中的日期始终准确。
+- **群内定时任务**：在群里用自然语言创建 cron 定时任务，支持"每天 9 点总结昨天群聊"等日常需求。创建、查看、删除都在群里一句话搞定，任务限定当前群聊不能跨群。
+- **工具循环智能兜底**：当 Agent 多轮工具调用达到上限时，自动用对话历史生成最终答案，不再返回含混的"操作已提交"提示。
 - **自动识别飞书机器人身份**：可通过 App ID / App Secret 自动获取 `botOpenId`，减少手动配置错误。
-- **会话记忆块**：把 10 分钟窗口、静默 2 分钟后的碎片聊天整理成 episode summary，让”我要发一个 API key”与后续短消息保持上下文关联。
+- **会话记忆块**：把 10 分钟窗口、静默 2 分钟后的碎片聊天整理成 episode summary，让"我要发一个 API key"与后续短消息保持上下文关联。
 - **敏感摘要保护**：会话摘要会脱敏疑似 token/API key；原始消息仍保留在本地，方便必要时追溯。
 
 当前核心方向是：
@@ -71,8 +73,9 @@ ChatterCatcher 是一个早期 MVP。它已经具备飞书长连接接入、本
 - 让家庭群信息自然沉淀为本地知识库，而不是靠手动整理。
 - 所有事实性回答必须先检索 RAG 证据，不能把大量历史聊天直接塞给 LLM。
 - `@` 机器人的提问不进入知识库，避免污染检索结果。
-- 回答必须能追溯到“谁在什么时候说了什么”。
+- 回答必须能追溯到"谁在什么时候说了什么"。
 - 新信息覆盖旧信息时保留历史证据，并优先使用明确、更新的证据。
+- 自动为群成员建立个人档案，让机器人了解"谁喜欢什么""谁需要什么"。
 - 默认本地部署，Web UI 默认只监听 `127.0.0.1`。
 
 ---
@@ -109,7 +112,7 @@ ChatterCatcher 是一个早期 MVP。它已经具备飞书长连接接入、本
       <br />
       <strong>本地 Web UI</strong>
       <br />
-      查看 Gateway 状态、最近消息、群聊、文件库、解析任务和本地操作入口。
+      查看 Gateway 状态、最近消息、群聊、文件库、解析任务和人物档案。
     </td>
   </tr>
 </table>
@@ -122,20 +125,49 @@ ChatterCatcher 是一个早期 MVP。它已经具备飞书长连接接入、本
 | --- | --- |
 | 飞书 Gateway | 官方长连接、`im.message.receive_v1` 事件、自动 `botOpenId` 获取、重复投递保护、附件下载入口 |
 | 消息入库 | 普通文本消息写入 SQLite；`@` 提问直接回答并跳过入库 |
+| 人物档案 | 自动识别群成员并建立以人物为中心的档案。支持事实/推断分类、置信度评分、证据追溯、Dream 自动更新、显式修正 |
 | 会话记忆块 | 默认 10 分钟窗口 + 2 分钟静默期，把碎片聊天整理成可检索 episode summary，并关联原始消息 |
-| RAG 检索 | SQLite FTS 关键词检索、SQLite embedding 向量检索、episode summary 检索、混合重排、证据来源保留 |
+| RAG 检索 | SQLite FTS 关键词检索、SQLite embedding 向量检索、episode summary 检索、人物档案检索、混合重排、证据来源保留 |
 | 时间归一化 | 自动将相对时间（今天/明天/今晚）推导为具体日期，覆盖会话摘要、RAG 问答、Agent 工具循环全部 LLM 路径 |
 | 问答 | OpenAI-compatible chat completions、Agent 多轮工具调用、证据不足时说不知道、回答带引用、工具循环耗尽智能兜底 |
 | 定时任务 | 群内自然语言创建 cron 定时任务（如"每天 9 点总结昨天群聊"），限定当前群聊，支持创建/查看/删除 |
-| 引用格式 | 展示“谁在什么时候说了什么”，避免暴露 `ou_` / `oc_` 等 opaque id |
+| 引用格式 | 展示"谁在什么时候说了什么"，避免暴露 `ou_` / `oc_` 等 opaque id |
 | 文件知识源 | 支持 txt、md、json、csv、tsv、log、docx、pdf 导入和解析 |
-| CLI | setup、settings、doctor、gateway、process、index、files、export、restore |
-| Web UI | 本地状态看板、自动刷新、最近消息、群聊、文件库和解析任务 |
+| CLI | setup、settings、doctor、gateway、process、index、files、export、restore、profiles |
+| Web UI | 本地状态看板、自动刷新、最近消息、群聊、文件库、人物档案和解析任务 |
 | 隐私 | 配置与密钥分离；导出不包含 API Key、App Secret 或 token；会话摘要会脱敏疑似密钥 |
 | 数据管理 | 本地导出/恢复、按消息/文件/群删除本地知识库数据 |
 
 ---
 
+## 个人档案（Personal Profiles）
+
+ChatterCatcher 会自动识别群里的每个发言者，为他们建立个人档案。这不仅仅是记录"谁是谁"，更是让机器人理解群成员的偏好、需求和背景。
+
+### 档案条目类型
+
+- **事实（fact）**：从聊天中明确提取的事实信息，如"豆豆的编程课是每周六下午 2 点"。
+- **推断（inferred）**：从聊天模式中推断的信息，如"豆豆喜欢编程"，置信度相对较低。
+
+### 档案分类
+
+每条档案条目属于一个 category，例如：
+- `preference`：偏好（喜欢/不喜欢什么）
+- `schedule`：日程（固定活动时间）
+- `health`：健康相关信息
+- `skill`：技能和特长
+- `role`：家庭角色
+
+### Dream 自动更新
+
+Dream 处理器会定期运行，批量分析新的群聊消息，自动发现人物档案的新变化。它只基于最新的消息批次输出更新，带证据引用和置信度评分。没有足够证据时不会强行生成条目。
+
+### 显式修正
+
+用户可以通过 Web UI 或 API 显式纠正、删除档案条目，修正会记录理由和证据，保证档案的准确性和可追溯性。
+
+---
+
 ## 架构概览
 
 ```mermaid
@@ -149,12 +181,15 @@ flowchart LR
   Episode --> EpisodeFTS["Episode FTS5"]
   SQLite --> Indexer["Embedding Indexer"]
   Indexer --> Vectors["SQLite embedding vectors"]
+  SQLite --> Profiles["Personal Profiles"]
+  Profiles --> Dream["Dream Processor"]
 
   Router -->|"@ 提问"| QA["Question Handler"]
   QA --> Hybrid["Hybrid Retriever"]
   FTS --> Hybrid
   EpisodeFTS --> Hybrid
   Vectors --> Hybrid
+  Profiles --> Hybrid
   Hybrid --> LLM["OpenAI-compatible LLM"]
   LLM --> Reply["带引用回复原消息"]
   Reply --> Feishu
@@ -258,10 +293,10 @@ http://127.0.0.1:3878
 最近一次编程课是 2026-04-28 13:40 [S1]。
 
 引用：
-[S1] 群成员在 2026-04-26 13:36 说：”编程课的时间改成了后天13:40”
+[S1] 群成员在 2026-04-26 13:36 说："编程课的时间改成了后天13:40"
 ```
 
-注意：原文说的是”后天”，但 ChatterCatcher 已根据消息时间戳自动推导为具体日期。
+注意：原文说的是"后天"，但 ChatterCatcher 已根据消息时间戳自动推导为具体日期。
 
 ---
 
@@ -284,6 +319,8 @@ http://127.0.0.1:3878
 | `chattercatcher restore <file>` | 从导出文件恢复 |
 | `chattercatcher cron list` | 列出所有定时任务 |
 | `chattercatcher cron run` | 手动触发到期定时任务 |
+| `chattercatcher profiles list` | 列出所有人物档案 |
+| `chattercatcher profiles show <personId>` | 查看指定人物档案详情 |
 
 ---
 
@@ -298,7 +335,7 @@ ChatterCatcher 会在普通消息入库后尝试生成 **会话记忆块（episo
 3. 当窗口最后一条消息之后安静 2 分钟，认为这一小段对话可以整理。
 4. 调用 LLM 把碎片聊天总结成可检索事实。
 5. 将摘要写入本地 SQLite，并记录它关联的原始消息 ID。
-6. 问答时同时检索原始消息、文件证据和会话记忆块。
+6. 问答时同时检索原始消息、文件证据、会话记忆块和人物档案。
 
 会话摘要会脱敏疑似 API key、token、cookie、私钥和 URL 凭据；原始消息仍保存在本地数据库里，回答需要追溯时可以回到原始证据。
 
@@ -365,6 +402,7 @@ dist/
 - 聊天记录、文件内容、OCR 结果和语音转写都视为隐私数据。
 - App Secret、API Key 和 token 与普通配置分开保存。
 - 会话记忆块会脱敏疑似 API key、token、cookie、私钥和 URL 凭据，避免把敏感值扩散到摘要里。
+- 人物档案条目同样遵守隐私原则，只从本地已保存的消息中提取，不会另建远程档案。
 - 原始消息仍保存在本地数据库，方便在必要时追溯上下文。
 - 导出文件不包含密钥。
 - 事实性回答必须基于检索证据。
@@ -396,6 +434,14 @@ npm run dev -- --help
 
 不会。`@` 提问是查询意图，不是家庭事实。ChatterCatcher 会直接回答并跳过入库，避免污染 RAG。
 
+### 人物档案和 RAG 是什么关系？
+
+人物档案是 RAG 的一种证据来源。回答问题时，检索器会同时检索原始消息、文件、会话记忆块和人物档案。例如问"豆豆喜欢什么"，机器人可能从消息中找到直接回答，也可能从档案中找到汇总的偏好条目。
+
+### Dream 处理器是什么？
+
+Dream 是人物档案的自动更新机制。它会定期读取新消息，用 LLM 分析这些消息中是否包含人物信息的变化，并自动写入或更新档案条目。Dream 只基于当前批次的消息，不回看全部历史，保证效率和增量更新。
+
 ### 没有 embedding 能用吗？
 
 可以保留 SQLite FTS 关键词检索，但语义检索需要配置 embedding。建议运行 `chattercatcher doctor --online` 确认维度和连通性。
@@ -416,7 +462,7 @@ npm install -g chattercatcher@latest
 
 ### 会话记忆块是什么？
 
-会话记忆块是 ChatterCatcher 对一小段碎片聊天生成的本地摘要。它默认等待 10 分钟窗口结束并静默 2 分钟后生成，用来保留“上一句解释背景、下一句只发短内容”的上下文关系。可以运行 `chattercatcher process episodes` 手动触发。
+会话记忆块是 ChatterCatcher 对一小段碎片聊天生成的本地摘要。它默认等待 10 分钟窗口结束并静默 2 分钟后生成，用来保留"上一句解释背景、下一句只发短内容"的上下文关系。可以运行 `chattercatcher process episodes` 手动触发。
 
 ### 会话摘要会不会泄露 API key？