chattercatcher 0.2.5 → 0.2.7

package/docs/DEVELOPMENT_PLAN.md

@@ -142,6 +142,41 @@
 - 群/成员配置测试。
 - 数据删除测试。
 
+
+## M4：人物档案（Personal Profiles）
+
+目标：ChatterCatcher 自动识别群成员，建立以人物为中心的知识档案，让问答系统理解"谁喜欢什么""谁需要什么"。
+
+### 范围
+
+- 人物身份自动识别：消息入库时从 senderId/senderName 解析人物身份。
+- 档案存储：PersonProfile 数据模型，包含 person、identities、entries。
+- ProfileRepository：本地 SQLite 仓储，支持 upsert、查询、修正。
+- Dream 处理器：周期性批量分析新消息，LLM 自动提取档案更新。
+- 档案 RAG 工具：get_person_profile 和 search_person_messages Agent 工具。
+- 档案修正：支持通过 API 显式纠正档案条目。
+- Web UI 档案页面：展示人物列表、档案详情和手动修正入口。
+- CLI 档案命令：profiles list、profiles show。
+
+### 验收标准
+
+- 消息入库时自动注册人物身份。
+- 每个群成员拥有独立的档案，包含事实和推断条目。
+- Dream 处理器能批量分析新消息并生成档案更新。
+- 档案条目带证据引用和置信度评分。
+- RAG 问答能检索人物档案作为证据源。
+- Web UI 可查看和修正人物档案。
+- CLI 可列出和查看人物档案。
+
+### 自测
+
+- 人物身份解析测试。
+- 档案 upsert 和查询测试。
+- Dream 处理器 mock LLM 测试。
+- 档案 RAG 工具集成测试。
+- 档案修正 API 测试。
+- Web UI 档案页面构建测试。
+
 ## Backlog
 
 - 更多聊天平台。
@@ -160,4 +195,13 @@
 - 手工 smoke test 记录。
 - 已更新的文档。
 - 一个或多个聚焦的 git commit。
-- 开始发版后维护 changelog。
+
+## 发版纪律
+
+每次发版必须：
+
+- 更新 `CHANGELOG.md`，按时间倒序记录新增、修复和变更。
+- `CHANGELOG.md` 使用中文，格式参考 https://keepachangelog.com/zh-CN/1.1.0/。
+- 版本号遵守 SemVer。
+- `package.json` 的 `files` 字段必须包含 `CHANGELOG.md`。
+- Claude 负责 version bump、PR 和 merge；用户负责 `npm publish`。

package/docs/PRD.md

@@ -118,6 +118,20 @@ ChatterCatcher 是一个本地优先的飞书/Lark 家庭群机器人。它静
 - `chattercatcher settings` 可以修改和重置配置。
 - `chattercatcher doctor` 检查飞书凭证、模型连通性、embedding 兼容性和本地存储。
 
+### 个人档案
+
+作为家庭成员，我希望机器人自动了解群成员的偏好、需求和背景，不用每次提问都从头解释。
+
+验收标准：
+
+- 机器人自动从消息中识别群成员，为每个人建立独立档案。
+- 档案条目分事实（fact）和推断（inferred），带置信度评分。
+- 档案按 category 分类（preference、schedule、health、skill 等）。
+- Dream 处理器周期性批量分析新消息，自动更新档案。
+- 用户可通过 Web UI 或 API 显式纠正档案条目。
+- 档案条目可追溯原始证据（哪条消息、谁说、说什么）。
+- 档案检索作为 RAG 证据源之一参与问答。
+
 ## RAG 要求
 
 RAG 是产品核心，不是可选增强。

package/docs/TECHNICAL_ARCHITECTURE.md

@@ -211,6 +211,80 @@ retrieval_debug_json
 created_at
 ```
 
+
+### person_profiles
+
+```text
+id
+primary_name
+notes
+created_at
+updated_at
+```
+
+### person_identities
+
+```text
+person_id
+platform
+platform_chat_id
+external_user_id
+display_name
+alias
+source
+first_seen_at
+last_seen_at
+```
+
+### profile_entries
+
+```text
+id
+person_id
+category
+content
+entry_type
+confidence
+status
+source
+created_at
+updated_at
+last_observed_at
+```
+
+### profile_evidence
+
+```text
+entry_id
+message_id
+quote
+reason
+```
+
+### dream_state
+
+```text
+platform
+platform_chat_id
+last_message_id
+last_message_sent_at
+updated_at
+```
+
+### dream_runs
+
+```text
+id
+platform
+platform_chat_id
+status
+processed_message_count
+generated_entry_count
+error
+started_at
+finished_at
+```
+
 ### jobs
 
 ```text
@@ -240,6 +314,49 @@ RAG 是强制架构路径，不能被 prompt 堆叠替代。
 
 答案生成器只能接收压缩后的证据块，不能接收无限制原始聊天历史。
 
+
+## 人物档案（Personal Profiles）
+
+人物档案是以人物为中心的知识组织方式。每个群成员在 ChatterCatcher 中拥有独立的档案，包含从聊天消息中提取的事实和推断。
+
+### 档案数据流
+
+```text
+消息入库 -> 人物身份解析 -> PersonIdentity 注册
+  -> Dream Processor（周期性批量分析）
+  -> LLM 提取档案更新
+  -> ProfileRepository upsert entries
+  -> RAG 检索时作为证据源
+```
+
+### 档案条目类型
+
+- **fact**：从聊天中明确提取的事实，如"豆豆的编程课是每周六下午 2 点"，置信度高。
+- **inferred**：从聊天模式推断的信息，如"豆豆喜欢编程"，置信度相对较低。
+
+### Dream 处理器
+
+Dream 是对人物档案的自动更新机制：
+
+1. 读取群的 dream_state，获取上次处理位置。
+2. 从 message 表批量拉取新消息（默认每批 100 条）。
+3. 收集本批消息涉及的所有 personId，加载现有档案。
+4. 将消息和现有档案通过 LLM 分析，输出档案更新列表。
+5. 验证每个更新：personId 存在、证据消息在本批次内、置信度在 0-1 范围。
+6. Upsert 档案条目，更新 dream_state 光标。
+7. 记录 dream_run（成功/失败/跳过）。
+
+Dream 只基于当前批次消息输出更新，不回看全部历史，保证增量处理效率。
+
+### RAG 集成
+
+档案检索工具集成在 Agent 工具循环中：
+
+- `get_person_profile`：根据 senderId + chatId 或 personId 检索特定人物的档案。
+- `search_person_messages`：按 personId 只检索某个人发过的消息。
+
+检索到的档案条目作为 RAG 证据源，和消息、文件、episode summary 一起参与重排和答案生成。
+
 ## 冲突处理
 
 冲突处理不能简单“最新消息赢”。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chattercatcher",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "本地优先的飞书/Lark 家庭群知识库机器人",
   "type": "module",
   "main": "dist/index.js",
@@ -23,7 +23,8 @@
     "docs/PRD.md",
     "docs/TECHNICAL_ARCHITECTURE.md",
     "README.md",
-    "AGENTS.md"
+    "AGENTS.md",
+    "CHANGELOG.md"
   ],
   "directories": {
     "doc": "docs"