本机运行的微信群消息 AI 摘要工具：选择群聊和时间范围，读取微信数据项目副本，生成可预览、下载和分享的摘要长图。
重点适配 Windows 版微信 v4 和 macOS 版微信 4.1.9。程序只读取本机有权访问的数据，不提供微信登录、自动发消息或 UI 自动化。
- 群聊摘要：选择一个或多个群、时间范围和过滤条件，生成 PNG 长图或 Markdown 文本预览。
- 完整上下文：保留消息时间、发送人、引用、文件和可用的媒体元信息；大输入自动按时间顺序分段处理。
- 媒体处理：按隐私设置尝试处理图片、视频、语音和音频；正文不可用时只保留可验证的消息元信息。
- 链接核查：先抓取可访问页面；支持 Responses
web_search或web_search_preview的端点会自动探测可用工具并让 AI 联网核查。 - 历史管理：搜索、查看、下载、复制、在文件夹中显示，或使用已保存摘要重新渲染，不重复调用 AI。
- 定时摘要：可选启用后台定时任务，单个群失败不会中断整轮处理。
- 本地安全：服务默认只监听
127.0.0.1；API Key 和数据库密钥保存在本机加密文件，不写入普通设置 JSON。
- 总结：选择群、时间范围和过滤条件，生成 PNG 或文本预览。
- 历史：搜索、预览、下载、复制、在文件夹中显示和重新渲染。
- 设置：配置 AI 接入、隐私脱敏、群白名单、定时摘要和验收证据。
仓库不会跟踪 docs/assets/ 下的运行截图；截图可能来自本机验收环境，不应作为公开文档素材提交。
| 平台 | 状态 | 关键差异 |
|---|---|---|
| Windows 10/11 + 微信 v4 | 主要支持 | Node.js 20+；支持只读自动密钥扫描、系统托盘、服务端 PNG 和 Windows 剪贴板兜底。当前本机 4.1.10.27 已有自动 key/db 运行态验证；微信版本、账号目录或同步状态变化后仍会自动复核，失败时需填写或粘贴有效手动密钥候选。 |
| macOS 13+ + 微信 4.1.9 | 已实现路径，需目标 Mac 真机确认 | Node.js 20+；必须手动填写数据库密钥；没有系统托盘、服务端 PNG 和系统剪贴板图片兜底，页面长图使用浏览器 Canvas。 |
macOS 的安装、密钥和平台限制见 macOS 使用指南。完整的页面操作说明见 用户手册。
- 安装 Node.js 20 或更高版本。
- 双击项目根目录的
启动.cmd。启动器会检查依赖、启动本地服务和托盘，并自动打开浏览器。
启动.cmd
默认地址为 http://127.0.0.1:7788；端口被占用时会自动顺延，按浏览器或托盘打开的实际地址为准。只看当前窗口日志时运行：
启动.cmd --console验收-记录微信哈希.cmd 只用于可选的启动前 A3 外部二进制基线记录，会写入 data/external-weixin-binary-baseline.json，不是程序运行依赖。
- 安装 Node.js 20 或更高版本。
- 在 Terminal 中进入项目根目录并运行：
chmod +x 启动.command
./启动.command首次启动会自动安装缺少的依赖。服务默认监听 http://127.0.0.1:7788，端口被占用时会顺延；按 Terminal 输出的实际 URL 访问，按 Ctrl+C 退出。
npm ci
npm run devnpm run dev 启动服务但不自动打开浏览器。
首次进入网页后按向导完成：
- 选择
OpenAI或Anthropic兼容提供方。 - 填写 Base URL 和 API Key，获取并选择模型。
- 检查微信账号和本地数据状态。
- 设置群白名单；留空表示不限制群选择。
Windows 会尽力扫描微信进程中的数据库密钥候选；扫描失败或账号状态变化时，在设置页填写手动密钥。macOS 当前必须手动填写数据库密钥。支持 64/96/128/160/192 位十六进制候选，以及向导提示的导出片段格式；多个候选请逐行粘贴。
程序会自动把微信数据库复制到项目内的 data/wxdb-mirror，后续查询和解密只操作项目副本及 outputs/.tmp/db 临时副本，不需要手动配置数据库路径。源库不可见或复制校验不通过时，程序会拒绝复用过期副本并提示重试。
- 在“总结”页选择群和时间范围，例如“今天”“最近 24h”或自定义范围。
- 按需设置发送人、关键词、消息类型等过滤条件。
- 点击“生成长图”或“生成文本预览”。多选群会分别生成并保存，页面预览最后完成的一张。
- 下载 PNG、复制图片或查看文件位置；文本预览需要文件时，再点击“导出 MD”。
- 在“历史”页搜索并打开结果。历史重渲染使用浏览器 Canvas，保存前由本地服务校验版本，原始文件保留。
发送给 AI 的内容只包含你选择的群和时间窗。媒体正文只有在设置允许且本机文件可读时才会作为输入；否则保留时间、发送人、时长和文件名等元信息继续总结。
链接处理分两层：
- 本地预览：服务尝试跟随跳转，读取可访问页面的标题、描述和正文片段。
- AI 查链：当兼容端点支持 Responses
web_search或web_search_preview时，程序自动探测并复用可用工具；不支持、网络受限、页面需要登录或返回错误时，退回本地页面内容、URL、标题和消息上下文。
因此“AI 查链 0/x”表示 x 个链接没有得到 AI 联网结果，不等于摘要流程一定失败；结果仍可能来自本地页面抓取。登录墙、验证码和强 JS 页面无法保证抓取成功。
- 微信源数据库只作为复制来源，不在源路径上查询、解密或计算内容哈希；查询和解密只发生在
data/wxdb-mirror与outputs/.tmp/db。 - 摘要发送到你配置的 AI 端点前，会按设置对手机号、身份证号和银行卡号等字段脱敏；是否发送媒体正文由隐私设置控制。
- API Key 和手动数据库密钥保存在
data/secrets.bin加密包；自动验证成功的候选保存在data/wxdb-keys.bin加密缓存。Windows 使用 DPAPI，macOS 使用 Keychain 条目wx-summary.secrets保护本机包装密钥。 - 普通设置保存在
data/settings.json；摘要、历史索引、临时文件和日志保存在outputs/。 .gitignore默认忽略data/运行数据、outputs/、数据库、媒体、日志、密钥、docs/assets/、内部计划和验收附件。不要提交真实 API Key、数据库密钥、微信数据库、聊天内容或未脱敏截图。
公开配置模板：data/settings.example.json。首次启动后常见的本机文件如下：
data/settings.json # 普通设置
data/secrets.bin # 加密 API Key / 手动密钥
data/wxdb-keys.bin # 加密的已验证密钥候选
data/wxdb-mirror/ # 微信项目副本
outputs/digests/ # PNG 与历史摘要
outputs/previews/ # 导出的 Markdown 预览
outputs/.tmp/ # 临时文件与脱敏日志
不要直接压缩当前工作目录发布源码；使用干净 clone 或 git archive HEAD，避免带出本机运行数据和 .git。
| 现象 | 处理 |
|---|---|
| 启动失败或找不到 Node.js | 安装 Node.js 20+；Windows 用 启动.cmd --console，macOS 用 ./启动.command 查看原始错误。 |
| 提示“需要手动密钥” | Windows 自动扫描未通过，或 macOS 当前平台必须手动配置；确认密钥属于当前选中的微信账号，并把多个候选逐行粘贴。 |
| 群列表为空或项目副本失败 | 保持微信运行，刷新群列表；按进度卡提示重试自动准备副本。不要继续使用不可见源库对应的旧副本。 |
AI 查链 0/x |
检查 AI Base URL、网络和本地页面预览；当前端点不支持联网工具时，摘要仍可使用消息上下文生成。 |
ai_quality_failed |
AI 返回了空洞或与消息数量不符的成品，质量保护拒绝保存；缩短时间范围、检查模型或稍后重试。 |
| PNG 复制失败 | 使用“下载 PNG”。Windows 有系统剪贴板兜底，macOS 受浏览器权限限制且没有系统兜底。 |
安装依赖后运行：
node tests/ai-web-search-compatibility.mjs
node tests/llm-connectivity-summary-contract.mjs
node tests/acceptance/static-checks.mjs
git diff --check改动托盘、项目副本、输出校验或设置持久化时，应一并运行对应的 tests/*.mjs 专项测试。
- 用户手册：完整的 Windows 操作、生成、历史、调度和隐私说明。
- macOS 使用指南：Node.js、手动密钥、平台限制和真机验收。
- 配置模板：不含密钥的公开配置结构。
- 许可证。
本项目只用于读取和总结你本机有权访问的微信数据。请遵守当地法律法规、平台规则和聊天参与者的隐私预期，不要把含有他人隐私的摘要、诊断包、数据库、媒体或密钥提交到公开仓库。