chattercatcher 0.1.0

package/docs/DEVELOPMENT_PLAN.md

@@ -0,0 +1,163 @@
+# 开发计划
+
+## 策略
+
+从最小可用闭环开始：
+
+```text
+接收飞书文字 -> 本地保存 -> RAG 检索 -> 带引用回答
+```
+
+这个闭环稳定后，再扩展文件理解、冲突处理和长期运行能力。
+
+## M1：可用的文字记忆
+
+目标：ChatterCatcher 可以安装、配置、连接飞书/Lark，并对群聊文字消息进行问答。
+
+### 范围
+
+- TypeScript 项目脚手架。
+- npm 全局 CLI 包。
+- 交互式 `chattercatcher setup`。
+- 可编辑的 `chattercatcher settings`。
+- 飞书/Lark Gateway start/status/stop 命令。
+- 飞书长连接事件接收。
+- 文字消息入库。
+- SQLite 元数据数据库。
+- 本地向量库。
+- SQLite FTS 关键词索引。
+- OpenAI-compatible chat provider。
+- OpenAI-compatible embedding provider。
+- `@机器人` 触发回答。
+- 来源引用。
+- 基础冲突处理。
+- 基础本地 Web UI：状态、历史、配置。
+- `chattercatcher doctor`。
+
+`doctor` 需要覆盖两类检查：
+
+- 默认离线检查：配置目录、飞书配置完整性、SQLite、LanceDB、RAG 策略。
+- 可选在线检查：`chattercatcher doctor --online` 调用 OpenAI-compatible chat 和 embedding 接口，确认模型连通性。
+
+### 验收标准
+
+- `npm install -g chattercatcher` 暴露 CLI。
+- `chattercatcher setup` 生成可用本地配置。
+- `chattercatcher gateway start` 能连接飞书/Lark。
+- 机器人能接收群文字消息。
+- 机器人保存消息文本、发送人、群、时间戳和原始 payload。
+- `@ChatterCatcher` 提问能返回简短答案和引用。
+- 明确的新信息优先于旧事实。
+- 模糊讨论不会被当成确定更新。
+- Web UI 可通过 `http://127.0.0.1:<port>` 访问。
+
+### 自测
+
+- CLI setup 使用临时配置目录 dry run。
+- 飞书事件 payload fixture 入库测试。
+- 已知消息检索测试。
+- 使用 mock LLM 的答案生成测试。
+- 冲突处理测试：
+  - 明确更新。
+  - 普通建议。
+  - 旧事实没有替代。
+- Web UI build 测试。
+
+## M2：文件成为知识源
+
+目标：文件、图片、语音、链接成为一等可检索来源。
+
+### 范围
+
+- 飞书媒体/文件下载。
+- 文件保存到本地数据目录。
+- PDF 解析。
+- DOCX 解析。
+- XLSX 解析。
+- PPTX 解析。
+- 纯文本和 Markdown 解析。
+- 图片 OCR 路径。
+- 语音转写路径。
+- 链接元数据提取。
+- chunking pipeline。
+- 索引任务队列。
+- Web UI 文件库。
+- 重建索引命令。
+- 文件引用。
+- 多文件交叉问答。
+
+### 验收标准
+
+- 群里发送的文件会被下载并本地保存。
+- 解析后的文件文本能在索引元数据中看到。
+- 解析失败任务可见、可重试。
+- 问题可以从文件内容中得到回答。
+- 答案能引用文件名和可用位置。
+- 多个文件可以共同参与一个答案。
+
+### 自测
+
+- 每种支持格式的 parser fixture 测试。
+- OCR fixture 测试。
+- 语音转写 mock 测试。
+- 索引重试测试。
+- 引用格式测试。
+- Web UI 文件库构建和交互测试。
+
+## M3：可信的家庭知识库
+
+目标：ChatterCatcher 足够可靠，可以长期作为家庭记忆系统运行。
+
+### 范围
+
+- 飞书云文档同步。
+- 事实抽取 pipeline。
+- 事实版本历史。
+- 冲突解释 UI。
+- 群级和成员级配置。
+- 数据删除控制。
+- 备份和恢复。
+- 定时摘要。
+- 服务安装：
+  - Windows service。
+  - macOS launchd。
+  - Linux systemd。
+- 可选 Docker 部署。
+- parser 插件接口。
+
+### 验收标准
+
+- 用户能检查某个事实为什么是当前版本。
+- 被覆盖的旧事实仍作为历史保留。
+- 用户能删除指定本地数据。
+- 数据可以导出和恢复。
+- Gateway 可以作为后台服务运行。
+- 定时摘要可以通过 CLI 或 Web UI 配置。
+
+### 自测
+
+- 事实抽取和版本测试。
+- 备份恢复测试。
+- 服务命令 dry-run 测试。
+- 群/成员配置测试。
+- 数据删除测试。
+
+## Backlog
+
+- 更多聊天平台。
+- 移动端友好的 Web UI。
+- 本地 LLM 和 embedding 默认配置。
+- 知识图谱可视化。
+- 手动捕获浏览器扩展。
+- 飞书富文本卡片。
+- 公开 npm 包发布加固。
+
+## 发布纪律
+
+每个里程碑结束时必须有：
+
+- 通过的自动化测试。
+- 手工 smoke test 记录。
+- 已更新的文档。
+- 一个或多个聚焦的 git commit。
+- 开始发版后维护 changelog。

package/docs/PRD.md

@@ -0,0 +1,235 @@
+# ChatterCatcher 产品需求文档
+
+## 概述
+
+ChatterCatcher 是一个本地优先的飞书/Lark 家庭群机器人。它静默监听群聊，保存消息和文件，构建可检索的本地知识库，并在被 `@` 时基于证据回答问题。
+
+核心承诺：
+
+```text
+把机器人拉进家庭群。它记住群里的重要聊天和文件。之后直接问它，它用来源回答。
+```
+
+## 问题
+
+家庭里的重要信息经常以闲聊形式发布：
+
+- 活动日期。
+- 学校或出行安排。
+- 账单和付款信息。
+- 文档。
+- 截图。
+- 语音消息。
+- 链接。
+- 后续变更。
+
+大家经常忘记信息在哪里，只能去问某个最会找消息的人。这低效、重复，而且容易烦。
+
+## 目标
+
+- 无需手动打标签，也能捕获家庭群信息。
+- 支持文字、文件、图片、链接、语音和飞书文档链接。
+- 默认所有数据本地保存。
+- 使用 LLM 理解、回答、摘要和处理信息冲突。
+- 使用 embedding 和 RAG，让回答基于可追溯证据。
+- 用户 `@ChatterCatcher` 后，机器人给出简短直接回答。
+- 每个事实性回答都提供引用来源。
+- 新信息覆盖旧信息时保留历史证据。
+- 提供交互式 CLI 和基础本地 Web UI。
+
+## 非目标
+
+- ChatterCatcher 不是自主 Agent。
+- 不执行任意外部任务。
+- MVP 不做多租户 SaaS。
+- MVP 不做飞书以外的平台。
+- MVP 不需要公网访问。
+- 第一版不做企业级复杂权限系统。
+
+## 目标用户
+
+主要维护者：
+
+- 家里一个懂技术的人，负责安装、配置和维护。
+
+最终用户：
+
+- 飞书/Lark 家庭群成员，通过 `@机器人 + 问题` 使用。
+
+## 核心用户故事
+
+### 静默捕获
+
+作为家庭成员，我希望机器人静默保存群里的消息和文件，这样不用手动整理。
+
+验收标准：
+
+- 机器人加入群后能接收飞书群消息。
+- 机器人保存文字消息、发送人、群、时间戳和原始平台元数据。
+- 机器人下载支持的媒体和文件到本地。
+- 默认不主动回复，除非被 `@` 或用户显式配置。
+
+### 问答
+
+作为家庭成员，我希望直接 `@机器人` 提问，快速找到信息。
+
+验收标准：
+
+- `@ChatterCatcher 问题` 触发检索和回答。
+- 回答简短直接。
+- 回答包含来源引用。
+- 证据不足时，机器人明确说不知道。
+
+### 文件理解
+
+作为家庭成员，我希望文件也能像聊天消息一样被检索和问答。
+
+验收标准：
+
+- PDF、Word、Excel、PowerPoint、文本、Markdown、图片、链接、语音和飞书文档链接被捕获。
+- 解析后的文本会被切块、embedding、索引，并关联回源文件。
+- 回答能引用文件名，以及可用的页码、sheet 或 slide。
+
+### 冲突处理
+
+作为家庭成员，我希望机器人优先使用较新的确定信息，但不把闲聊讨论误判为更新。
+
+验收标准：
+
+- 明确更新会覆盖同一主体、同一谓词的旧事实。
+- 猜测、建议、讨论不会自动覆盖已确认事实。
+- 机器人能在必要时说明旧信息已经被新信息取代。
+
+示例：
+
+```text
+旧信息：活动 2026/5/30 举办。
+新信息：活动改到 2026/6/30。
+回答：活动目前是 2026/6/30。此前 2026/5/30 是旧信息。
+```
+
+### 引导式配置
+
+作为维护者，我希望 `npm install -g chattercatcher` 后通过交互式命令完成配置。
+
+验收标准：
+
+- `chattercatcher setup` 引导配置飞书、模型、embedding、存储、定时任务和 Web UI。
+- `chattercatcher settings` 可以修改和重置配置。
+- `chattercatcher doctor` 检查飞书凭证、模型连通性、embedding 兼容性和本地存储。
+
+## RAG 要求
+
+RAG 是产品核心，不是可选增强。
+
+问答必须经过：
+
+```text
+问题理解 -> 混合检索 -> 证据重排 -> 冲突处理 -> 答案生成 -> 引用输出
+```
+
+禁止：
+
+- 把全量聊天历史直接塞进 prompt。
+- 把大文件全文直接塞进 prompt。
+- 用上下文窗口替代向量索引和关键词索引。
+- 没有引用地给出事实性答案。
+
+## MVP 范围
+
+MVP 必须包含：
+
+- npm 全局包。
+- 交互式 CLI。
+- 飞书/Lark 自建应用连接。
+- 基于飞书长连接的本地 Gateway。
+- 本地存储。
+- 文字消息捕获。
+- 针对已捕获消息的 RAG。
+- OpenAI-compatible chat model。
+- OpenAI-compatible embedding model。
+- `@机器人` 触发问答。
+- 来源引用。
+- 基础冲突处理。
+- 基础本地 Web UI。
+
+MVP 暂缓：
+
+- 深度飞书云文档同步。
+- 高级权限系统。
+- 多平台支持。
+- 云部署。
+- 复杂自主工作流。
+
+## 产品命令
+
+必需 CLI 命令：
+
+```bash
+chattercatcher setup
+chattercatcher settings
+chattercatcher settings reset
+chattercatcher gateway start
+chattercatcher gateway stop
+chattercatcher gateway restart
+chattercatcher gateway status
+chattercatcher logs
+chattercatcher logs --follow
+chattercatcher index status
+chattercatcher index rebuild
+chattercatcher web start
+chattercatcher doctor
+chattercatcher export
+```
+
+## Web UI 要求
+
+本地 Web UI 需要提供：
+
+- Gateway 状态。
+- 飞书连接状态。
+- LLM 和 embedding 配置状态。
+- 最近群消息。
+- 群聊历史。
+- 文件库。
+- 索引任务。
+- 问答日志。
+- 配置编辑。
+- 重建索引和导出数据。
+
+默认监听地址：
+
+```text
+127.0.0.1
+```
+
+## 隐私要求
+
+- 默认本地保存数据。
+- Web UI 默认不对公网暴露。
+- secrets 和普通配置分开保存。
+- 不记录 secrets。
+- 后续需要支持删除群、消息和文件数据。
+
+## 飞书/Lark 集成
+
+MVP 集成模式：
+
+- 用户创建飞书/Lark 自建应用。
+- 用户启用机器人能力。
+- 用户配置所需权限。
+- 用户启用长连接事件订阅。
+- 用户订阅消息接收事件。
+- ChatterCatcher Gateway 通过飞书/Lark SDK 在本地建立长连接。
+
+设计参考 OpenClaw 的 Gateway 模式：本地 Gateway、App ID/App Secret 配置、长连接事件投递、群内 `@` 触发、CLI 可查看状态。
+
+## 成功指标
+
+家庭 MVP 的成功指标：
+
+- 一个懂技术的用户能在 30 分钟内完成安装配置。
+- 对近期聊天中的直接事实问题，至少 80% 能带引用回答。
+- 没有证据时不会自信胡说。
+- Gateway 能连续运行多天。
+- parser 或 embedding 失败后能通过重建索引恢复。