docs: 更新文档

WechatExplorer-Product-Manager-Handoff.md

@@ -0,0 +1,241 @@
+# WechatExplorer 产品经理交接
+
+> 面向下一任产品经理的产品事实、边界和文档维护说明。
+>
+> - 最后核验：2026-08-07
+> - 仓库版本：`2.1.9`
+> - 基准提交：`cd2c3cf`（`docs: 更新文档`）
+
+## 1. 接手时先记住什么
+
+WechatExplorer 当前可以定位为：
+
+> **一个本地优先的微信聊天记录查看、搜索、整理与 AI 分析工具。**
+
+它把几类原本分散的任务放在一起：
+
+- 浏览和搜索本机微信聊天；
+- 用 AI 查找历史信息，并回到来源消息核对；
+- 建立本地知识库，辅助跨会话、跨时间查找；
+- 生成群聊日报，转写语音，导出聊天档案；
+- 让外部 Agent 或应用内微信机器人按边界使用本机数据能力。
+
+产品表达应先回答用户能完成什么，再解释 Knowledge、Evidence、Citation、Search Trace、FTS 等内部术语。README 负责定位、主要价值和最短上手路径；完整步骤、限制和安全说明放在 `docs/`。
+
+### 事实来源优先级
+
+描述“当前支持”前，按以下顺序核验：
+
+1. 当前源码和 UI；
+2. 当前测试；
+3. `package.json`、构建和发布配置；
+4. 正式 `docs/`；
+5. README；
+6. 历史说明和产品设想。
+
+历史文档、旧版本描述和聊天记录不能单独证明当前能力。新增事实陈述时，最好同时写清限制并链接到正式文档或实现位置。
+
+## 2. 当前已验证的产品能力
+
+本节是能力地图，不替代正式使用手册。用户步骤和异常处理以链接的正式文档为准。
+
+### 2.1 连接与查看微信数据
+
+当前代码面向微信 4.x 数据结构，支持在 macOS 和 Windows 上连接本机微信数据。连接结果会受到微信版本、账号数据、系统权限和数据迁移状态影响。
+
+连接成功后，“档案”可以浏览已读取到的联系人、群聊、折叠群聊和公众号会话，并显示文本、图片、视频、语音、文件、链接、引用、小程序、表情和系统消息等类型。
+
+边界：消息类型可被读取，不等于对应媒体一定可以解码或显示。来源文件缺失、权限不足或微信存储方式变化都可能导致媒体不可用。
+
+来源：[第一次使用](./docs/user-guide/getting-started.md)、[查看和搜索聊天](./docs/user-guide/chat-archive.md)
+
+### 2.2 普通搜索与 AI Search
+
+档案内关键词搜索适合已知原话、文件名、人名或大致会话的任务。AI Search 适合“记得含义但不记得关键词或位置”的问题。
+
+AI Search 会先在本机查找候选聊天，再把完成任务所需的受控上下文交给用户配置的 AI Provider。回答可以展示来源会话、发送者、时间、来源标记和检索过程，并允许用户回到档案检查上下文。
+
+边界：Evidence、Citation 和 Search Trace 提供核对路径，不保证模型结论正确，也不保证选定范围之外没有遗漏。关键决定仍应回到原始消息确认。
+
+来源：[AI Search](./docs/user-guide/ai-search.md)、[如何核对 AI 回答来源](./docs/concepts/answer-sources.md)
+
+### 2.3 本地知识库
+
+用户可以主动为当前微信账号建立本地索引，并在之后同步新增或变化的记录。不同微信账号使用独立索引；界面会显示索引规模和磁盘占用。
+
+清理知识库不会删除微信原始数据库。知识库同步期间新的 AI 分析会暂停，但已有索引在部分异常情况下仍可能可用。
+
+边界：知识库是本地检索资料，不是新的微信数据库，也不是所有问题都必须先建立。只查一条已知原话时，普通搜索通常更直接。
+
+来源：[本地知识库](./docs/user-guide/knowledge.md)、`src/main/knowledge/`、`tests/unit/knowledge-*.test.ts`
+
+### 2.4 群聊日报
+
+用户可以选择一个群聊以及今天、昨天或近 7 天的范围，生成可能包含主题、重要消息、问答、资源、待办、未解决事项、关键词、活跃统计和可用媒体精选的报告。成功结果会保存为本地 HTML 和 PNG。
+
+边界：当前日报入口只支持群聊。具体栏目取决于所选消息、媒体可用性和模型能力；图片不可读或模型未通过图片理解验证时，图片精选会跳过。语音数量统计不代表语音内容已经转写或理解。
+
+来源：[群聊日报](./docs/user-guide/report.md)、`src/renderer/src/utils/group-report-facts.ts`
+
+### 2.5 本地语音转写
+
+应用使用本地 SenseVoice/sherpa-onnx 运行时转写微信语音，支持单条转写和按联系人或群聊批量处理。批量任务支持进度、取消、缓存复用和部分失败提示。
+
+成功转写的文本可以用于查看、本地知识库检索和导出。离线转写本身在本机完成；如果用户随后把转写文本用于 AI Search 或日报，文本会按对应 AI 功能的规则处理。
+
+边界：首次使用可能需要下载模型。失败或尚未转写的语音不会被自动当作已理解内容。
+
+来源：[语音转文字](./docs/user-guide/voice.md)、`src/main/voice-pipeline/`、`tests/unit/voice-*.test.ts`
+
+### 2.6 聊天导出
+
+当前支持 HTML、Markdown、CSV 和 JSON：
+
+| 能力                | 当前边界                                           |
+| ------------------- | -------------------------------------------------- |
+| HTML                | 可包含媒体和头像；支持最多五个会话合并             |
+| Markdown、CSV、JSON | 主要保留文本内容，不包含 HTML 资源文件             |
+| ZIP                 | 是 HTML 资源包的压缩选项，不是独立内容格式         |
+| 增量合并            | 仅适用于同名 HTML 档案                             |
+| 语音转写            | 只写入已经成功取得的转写文本，不会自动补齐失败内容 |
+
+导出不会修改微信原始数据库；删除导出文件也不会删除应用中的聊天或知识库。
+
+来源：[导出聊天](./docs/user-guide/export.md)、`src/main/export-service.ts`、`src/renderer/src/components/export/ExportWorkspace.tsx`、`tests/integration/export-media-flow.test.ts`
+
+### 2.7 外部 Agent 与 Local HTTP API
+
+外部 Agent 可以安装随应用提供的 Reader Skill，通过本机 Local HTTP API 按需读取联系人、会话、指定时间范围的聊天和群成员信息，也可以请求生成群聊总结图片。
+
+当前 API 默认地址为 `http://127.0.0.1:6131`：
+
+- `GET /api/v1/health` 不需要 Token；
+- 其他端点需要 `Authorization: Bearer <TOKEN>`；
+- Token 在 API Center 中显示、复制和重新生成；
+- 重新生成后旧 Token 立即失效；
+- API 没有细粒度用户 Scope，不应转发到公网。
+
+`6131` 是普通 Local HTTP API，当前不是 MCP Server。Reader Skill 不会自动监听微信实时消息。
+
+来源：[Agent 接入概览](./docs/agent/overview.md)、[Local HTTP API](./docs/agent/api.md)、[API 安全](./docs/agent/api-security.md)、[Reader Skill](./docs/agent/reader-skill.md)
+
+### 2.8 Agent Hub 与微信机器人
+
+Agent Hub 是应用内的实时微信入口。用户扫码连接一个微信机器人账号后，机器人收到文字消息，Agent Hub 可以查询本机数据、按需调用已配置的 AI，并把结果回复给触发请求的微信用户。
+
+当前明确支持的实时任务包括：
+
+- 查看最近会话，数量限制为 1 至 20；
+- 查询与某位联系人的近期聊天；
+- 总结与某位联系人近 7 天的聊天；
+- 生成今天、昨天或近 7 天的群聊总结图片；
+- 总结指定群成员的近期发言；
+- 对不需要读取聊天的普通文字请求给出有限的 AI 回复。
+
+边界：实时自然语言入口主要处理文字。底层连接器可以接收其他媒体，但 Agent Hub 尚未提供同等的图片、语音、文件和视频意图处理。它也没有群发、广播、定时任务或通用自主操作微信的能力。
+
+来源：[Agent Hub](./docs/agent/agent-hub.md)、`src/main/agent/`、Agent Hub 相关测试
+
+## 3. 隐私与安全边界
+
+“本地优先”不能表达成“所有数据永远不会离开电脑”。
+
+默认在本机完成的处理包括：微信数据库读取和解析、档案浏览、普通关键词搜索、本地知识库索引、离线语音转写、导出文件生成和本地日报历史。
+
+当用户主动使用 AI Search、群聊日报或图片理解，并配置远程 Provider 时，用户问题、受控检索上下文和最终用于总结的来源内容可能发送给该 Provider。Provider 的日志、保留、计费和地区规则不由 WechatExplorer 控制。
+
+外部 Agent 是否把 API 读取结果继续发送给云端模型，取决于 Agent 自己的配置。Agent Hub 的机器人账号、个人微信数据库连接和外部 Agent/API Token 是三条不同的安全边界。
+
+来源：[数据、隐私与安全](./docs/user-guide/privacy.md)
+
+## 4. 尚未实现或不能宣称的能力
+
+以下内容不是当前能力。未来讨论这些方向时，必须明确写成“未来场景 / 尚未实现”，且不能据此承诺路线图或发布时间：
+
+- **未来场景 / 尚未实现：**按固定时间自动生成或发送每日群聊总结；
+- **未来场景 / 尚未实现：**群发、广播或通用微信自动化；
+- **未来场景 / 尚未实现：**Agent Hub 对图片、语音、文件和视频提供与文字相同的实时理解能力；
+- **未来场景 / 尚未实现：**将 `127.0.0.1:6131` 作为 MCP Server 使用；
+- **未来场景 / 尚未实现：**对外提供实时入站 webhook 或由 Reader Skill 订阅实时微信消息；
+- **不能宣称：**所有微信 4.x 版本、所有账号和所有系统组合都能稳定连接；
+- **不能宣称：**所有图片、视频、文件或语音都一定能读取、解码或理解；
+- **不能宣称：**AI 回答或日报一定完整、准确，或者 Evidence 本身能保证结论正确；
+- **不能宣称：**启用远程 AI 后所有数据仍只停留在本机。
+
+## 5. 仅凭当前仓库仍无法确认的事项
+
+以下问题需要真实发布环境、用户研究或外部平台信息，不能仅凭当前源码和测试得出结论：
+
+1. GitHub Releases 中各平台安装包当前是否齐全、可下载，以及在不同系统安全策略下的实际安装成功率；
+2. 不同微信 4.x 小版本、历史迁移状态和真实账号规模下的连接成功率与兼容矩阵；
+3. 超大聊天历史下，索引、AI Search、日报、语音批处理和导出的真实耗时、容量上限与失败率；
+4. 微信机器人账号在长期运行中的登录稳定性、平台规则风险和账号限制；
+5. 用户是否真正理解并使用“来源核对”、Knowledge、Reader Skill 和 Agent Hub，以及这些功能是否改善了实际任务结果。
+
+这些事项在得到真实证据前，应写成“待验证”，不能转写成产品优势。
+
+## 6. 文档职责和维护方法
+
+### README
+
+README 只负责：
+
+- 一句话说明产品是什么；
+- 展示最重要的用户任务和差异；
+- 给出最短上手路径；
+- 引导到正式 docs。
+
+不要把完整 API、安全实现、数据库结构、检索原理或所有边缘情况塞进 README。
+
+### 正式 docs
+
+- `docs/user-guide/`：第一次使用、档案、AI Search、Knowledge、日报、语音、导出、隐私和排障；
+- `docs/concepts/`：来源核对和工作原理；
+- `docs/agent/`：Reader Skill、Local HTTP API、安全和 Agent Hub；
+- `docs/platform/`：平台权限和限制；
+- `docs/development/`：开发、测试、构建及代码与文档的对应关系。
+
+文档入口见：[docs 首页](./docs/README.md)。
+
+### 每次产品变更后的检查
+
+1. 用户是否能直接感知变化？如果能，检查 README 和对应 User Guide；
+2. 第一次使用路径是否变化？如果变化，检查 Getting Started；
+3. AI 的输入、来源或完整性提示是否变化？如果变化，检查 AI Search、Answer Sources 和 Privacy；
+4. API、Token、Reader Skill 或 Agent Hub 是否变化？如果变化，同步检查全部 Agent 文档；
+5. 兼容性、构建或发布范围是否变化？如果变化，检查平台和开发文档；
+6. 文案是否把“可能”“计划”“测试样例”误写成“当前支持”？
+
+推荐的能力陈述格式是：
+
+> 用户可以完成什么 + 当前限制是什么 + 事实来源在哪里。
+
+## 7. 下一任产品经理最应该关注的 5 个产品问题
+
+### 1. 新用户能否在几分钟内完成第一次连接
+
+连接微信数据是所有能力的前置条件。需要建立真实平台和微信版本的成功率、失败原因和耗时数据，而不只依赖开发环境与测试样例。
+
+### 2. 用户能否理解 AI 回答的可信边界
+
+“可回到来源核对”是重要差异，但目前仍需要验证用户是否会打开来源、是否看得懂覆盖提示，以及这些信息能否减少错误决策。
+
+### 3. Knowledge 是否解决了用户可感知的问题
+
+需要验证建立和同步索引的成本、等待时间与搜索收益是否匹配，并明确哪些任务适合普通搜索、哪些任务真正需要 Knowledge。
+
+### 4. Reader Skill 和 Agent Hub 的定位是否足够清楚且安全
+
+两条路径服务不同用户，也有不同的 Token、机器人账号和数据外发边界。需要验证入口命名、配置流程、权限提示和失败恢复是否让用户理解。
+
+### 5. 兼容性和分发是否足以支撑产品承诺
+
+需要维护真实的系统、处理器、微信版本和账号数据兼容矩阵，同时确认安装包、系统授权、连接器和升级路径在发布环境中可用。
+
+## 8. 接手原则
+
+- 先核实能力，再决定怎么宣传；
+- 用用户任务描述价值，用正式 docs 承担细节；
+- 明确区分当前能力、限制、待验证事项和未来场景；
+- 不因文案完整性补充不存在的能力；
+- 不把测试通过等同于真实用户环境已经得到验证。