fix: make packaging checks platform safe

fix: ad-hoc sign packaged macOS key helpers and app bundle
electron-builder 26 skips macOS signing entirely when no Developer ID identity is configured, so the packaged key helpers can ship unsigned or with a broken signature and macOS kills them even with SIP disabled. afterPack now verifies and ad-hoc re-signs the packaged xkey helpers and the outer app bundle, failing the build when a signature cannot be repaired.
2026-10-05 04:07:40 +08:00 · 2026-09-20 18:05:12 +08:00 · 2026-09-20 17:52:38 +08:00 · 2026-09-20 16:11:08 +08:00 · 2026-09-20 15:56:27 +08:00 · 2026-09-20 15:40:01 +08:00
609 changed files with 89336 additions and 14027 deletions
@@ -5,6 +5,9 @@ VITE_DB_KEY=
 # Set to true/1/yes/on for local development. Default is disabled.
 VITE_AUTO_LOGIN=false

+# Show the scheduled report debug notification test action. Default is disabled.
+VITE_SCHEDULED_REPORT_DEBUG=false
+
 # AI API Configuration (Optional, can be entered in UI)
 # 注意：发布版本不再自动读取以下环境变量。
 # 如果你只是本地开发想用默认值，可以在自己机器的 .env.local 里填，
@@ -25,16 +25,10 @@ jobs:
          node-version: 22
          cache: pnpm

-      - uses: actions/setup-go@v5
-        with:
-          go-version-file: services/wechat-connector/go.mod
-          cache-dependency-path: services/wechat-connector/go.sum
-
      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
+        run: pnpm install

      - name: Install Playwright Chromium
-        if: runner.os == 'macOS'
        run: pnpm exec playwright install chromium

      - name: Type check
@@ -52,9 +46,6 @@ jobs:
      - name: Skill installation instruction tests
        run: pnpm test:skill-install

-      - name: WeChat connector tests
-        run: pnpm test:wechat-connector
-
      - name: Build Electron test application
        run: pnpm test:e2e:build

@@ -64,6 +55,8 @@ jobs:
          WXE_E2E_CLOSE_DELAY_MS: 0

      - name: Platform visual regression
+        # GitHub-hosted Windows 无法稳定容纳项目统一的 1400×800 Electron 窗口，Windows visual regression 改由可控 Windows 桌面环境执行。
+        if: matrix.os != 'windows-latest'
        run: pnpm exec playwright test tests/e2e/visual.spec.ts
        env:
          WXE_E2E_CLOSE_DELAY_MS: 0
@@ -1,5 +1,6 @@
 node_modules
 *.tsbuildinfo
+electron.vite.config.[0-9]*.mjs
 dist
 out
 .env
@@ -9,15 +10,18 @@ out
 coverage/
 playwright-report/
 test-results/
-resources/connectors/wechat/
+resources/connectors/wechat-personal/
 .omc
 .codex/
-services/share-card-worker/.wrangler/
-services/share-card-worker/wrangler.local.jsonc
-docs/design/
-docs/ui-redesign-plan.md
-docs/ui-redesign-spec.md
-AGENTS.md
+skills-lock.json
+*__screenshots__
+
+/AGENTS.md
+/CLAUDE.md
+/.claude/
+/.workbuddy/
+/.ai-local/
+
 findings.md
 progress.md
 task_plan.md
@@ -2,3 +2,4 @@ singleQuote: true
 semi: false
 printWidth: 100
 trailingComma: none
+endOfLine: auto
@@ -8,7 +8,7 @@
      "cwd": "${workspaceRoot}",
      "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/electron-vite",
      "windows": {
-        "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/electron-vite.cmd"
+        "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/electron-vite.CMD"
      },
      "runtimeArgs": ["--sourcemap"],
      "env": {
@@ -7,5 +7,6 @@
  },
  "[json]": {
    "editor.defaultFormatter": "vscode.json-language-features"
-  }
+  },
+  "files.eol": "\n"
 }
@@ -0,0 +1,112 @@
+# 参与贡献
+
+> 这份文档同时写给人和 AI Agent。文末有给 Agent 的英文硬性规则。
+> 如果你只是想把 TraceMemo 跑起来，看[第一次使用](./docs/user-guide/getting-started.md)就够了。
+
+## 一句话规则
+
+**从 `develop` 拉分支，把 PR 提给 `develop`。**
+
+## 为什么不是 main
+
+| 分支      | 是什么                                                  | 接受 PR 吗     |
+| --------- | ------------------------------------------------------- | -------------- |
+| `main`    | 稳定版。只在发版时更新，对应 GitHub Releases 里的安装包 | 不接受         |
+| `develop` | 开发主线。所有改动先进这里，**随下一个版本一起发布**    | 唯一的目标分支 |
+
+指向 `main` 的 PR、或者不是基于 `develop` 拉出来的分支，会被直接关闭。不是不欢迎贡献，而是因为冲突合并 提交落后较多等原因
+
+## 提 PR 的完整流程
+
+```bash
+# 1. 基于 develop 拉分支（不要基于 main）
+git fetch origin
+git checkout -b feat/your-change origin/develop
+
+# 2. 改代码，只改与本任务相关的文件
+
+# 3. 自检
+pnpm install        # 需要 Node 22 与 pnpm 7.33.7
+pnpm typecheck
+pnpm test:unit      # 再按改动范围补跑 component / integration
+
+# 4. 提交
+git commit -m "feat: 一句话说明改了什么"
+
+# 5. 提 PR，目标分支必须是 develop
+gh pr create --base develop --head feat/your-change
+```
+
+## 提交信息
+
+默认**只写一行标题**：类型前缀 + 一句话说明。
+
+```
+feat: 新增本地查询能力
+fix: 修复查询工具时间契约
+docs: 整理开发文档
+```
+
+确实包含多个功能点时，标题之后每个功能点各写一行纯文本 —— 不要用列表符号，也不要写
+「设置侧：」「测试：」这类分节标题：
+
+```
+feat: 统一手动发送入口为文字转语音
+移除普通文本、图片和本地语音的手动发送入口
+保留文字转语音的生成、试听和发送能力
+```
+
+不要在提交信息里堆文件名清单、测试结果或实现过程叙述，那些属于 PR 描述。
+
+## 分支命名
+
+`feat/…`、`fix/…`、`docs/…`、`refactor/…`，后面接简短的英文或拼音描述。
+
+## PR 前自检
+
+| 你的改动                   | 至少跑这些                                                        |
+| -------------------------- | ----------------------------------------------------------------- |
+| 一般代码 / 服务 / 工具函数 | `pnpm typecheck` + 相关 `pnpm test:unit`                          |
+| 界面 / 交互                | `pnpm typecheck` + 相关 `pnpm test:component`，或针对该功能的 E2E |
+| preload / IPC 契约         | `pnpm typecheck` + 相关 contract 测试或 `pnpm test:integration`   |
+| 只改文档                   | 不需要跑测试                                                      |
+
+全部测试命令见 `package.json` 的 `scripts`；本地开发环境的说明见[开发概览](./docs/development/overview.md)。
+
+## 请不要提交这些东西
+
+- **构建产物**：`out/`、`dist/`、`build/` 下的二进制、`node_modules/`、`test-results/`、`playwright-report/`
+- **真实数据**：微信聊天内容、真实的 wxid / 群名 / 联系人名、聊天截图
+- **密钥**：API Key、Token、数据库密钥、图片解密密钥
+- **本机绝对路径**：`/Users/…`、`C:\Users\…`
+
+测试用的假数据请用一眼能看出是合成的命名，例如 `fixture-group`、`wxid_fixture_member`。
+
+## 合入之后
+
+PR 合进 `develop` 不会立刻出现在下载页，它随**下一个版本**发布。想提前用上，可以自行从
+`develop` 构建。
+
+## 如果你是 AI Agent
+
+请按顺序执行，不要凭直觉选分支：
+
+1. **基线**：`git fetch origin && git checkout -b <branch> origin/develop`。永远不要基于 `main`。
+2. **PR 目标**：`gh pr create --base develop`。无法确定时默认 `develop`；任何情况下都不要把
+   `main` 当 PR 目标。
+3. **改动范围**：只改与本任务相关的文件。不要顺手格式化、重排 import、升级依赖。
+4. **提交前**：跑 `pnpm typecheck` 和与本次改动相关的测试（见上表）。
+5. **提交信息**：一行标题，`type: 描述`。不要写文件清单、测试输出或过程叙述。
+6. **PR 描述**：说明改了什么、为什么改、怎么验证的；关联 Issue 用 `closes #123`。
+7. **禁止**：真实聊天数据、密钥、Token、本机绝对路径、构建产物。
+
+### Hard rules for AI agents (English)
+
+- Base branch: `origin/develop`. Never branch off `main`.
+- Open pull requests with base branch `develop`. PRs targeting `main` are closed without review.
+- One PR = one logical change. No drive-by reformatting, import reordering, or dependency upgrades.
+- Before opening a PR, run `pnpm typecheck` plus the tests relevant to your change.
+- Commit subject: a single line, `type: summary`. No file lists, no test logs, no process narration.
+- Never commit build output (`out/`, `dist/`, `test-results/`, `playwright-report/`), real WeChat
+  data, keys, tokens, or absolute local paths.
+- Changes merged into `develop` ship with the next release.
@@ -4,79 +4,87 @@
  <img src="./build/icon.png" width="120" alt="TraceMemo Logo" />
 </p>

-<h2 align="center">把微信聊过的事，找回来、问清楚、留下来</h2>
+<h2 align="center">把微信里的信息，记住、理解、监控，并在需要时行动</h2>
+
+<p align="center">本地优先的微信数据、AI 分析与自动化工作台</p>

 <p align="center">
-  本地优先的微信聊天记录工作台：查看、搜索、提问、总结和导出<br />
-  查看聊天 · 找回信息 · AI 问答 · 群聊日报总结 · 语音转写 · 导出 · 微信机器人 · Agent 接入
+  <img src="https://img.shields.io/github/stars/Wxw-Gu/TraceMemo?style=for-the-badge" alt="GitHub stars" />
+  <img src="https://img.shields.io/github/downloads/Wxw-Gu/TraceMemo/total?style=for-the-badge" alt="GitHub downloads" />
+  <img src="https://img.shields.io/github/v/release/Wxw-Gu/TraceMemo?style=for-the-badge" alt="Latest release" />
 </p>

 <p align="center">
-  <img src="https://img.shields.io/github/stars/Wxw-Gu/WechatExplorer?style=for-the-badge" alt="GitHub stars" />
-  <img src="https://img.shields.io/github/downloads/Wxw-Gu/WechatExplorer/total?style=for-the-badge" alt="GitHub downloads" />
-  <img src="https://img.shields.io/github/v/release/Wxw-Gu/WechatExplorer?style=for-the-badge" alt="Latest release" />
-</p>
-
-<p align="center">
-  <a href="https://github.com/Wxw-Gu/WechatExplorer/releases"><b>下载 TraceMemo</b></a>
+  <a href="https://github.com/Wxw-Gu/TraceMemo/releases"><b>下载 TraceMemo</b></a>
  ·
  <a href="./docs/user-guide/getting-started.md"><b>第一次使用</b></a>
  ·
  <a href="./docs/README.md"><b>完整文档</b></a>
+  ·
+  <a href="./docs/concepts/how-it-works.md"><b>TraceMemo 如何工作</b></a>
 </p>

 <p align="center">
-  <img src="./public/software-1.png" alt="TraceMemo 主界面" />
+  <img src="./public/日报.png" alt="TraceMemo 主界面" />
 </p>

 <p align="center">
-  <img src="./public/机器人.png" alt="TraceMemo 微信机器人" />
+  <img src="./public/问问微信.png" alt="TraceMemo 问问微信" />
 </p>

+<p align="center">
+  <img src="./public/退群监控.png" alt="TraceMemo 退群监控" />
+</p>
 ---

-## TraceMemo（迹忆）是什么
+## 🎨 社区日报模板

-TraceMemo（迹忆）是一款**本地优先、可追溯的 AI 微信知识与分析工作台**。
+TraceMemo 日报除了内置版式，也支持从社区模板市场安装更多样式。社区模板与默认日报读取同一份真实日报数据，只改变展示方式，适合手机长图分享、桌面归档、团队复盘等不同场景。

-TraceMemo 原名 **WechatExplorer**，是一次从“微信聊天记录探索工具”向“可追溯的本地 AI 知识工作台”演进后的正式品牌升级。
+<p align="center">
+  <a href="https://github.com/Wxw-Gu/TraceMemo-Templates"><b>浏览 TraceMemo 模板社区</b></a>
+  ·
+  <a href="https://github.com/Wxw-Gu/TraceMemo-Templates/tree/main/skills/tracememo-template-contributor"><b>用 AI 制作并投稿模板</b></a>
+</p>

-它可以帮你浏览、搜索和整理微信历史，也可以让 AI 帮你找回聊过的内容，并回到原始消息核对答案。
+在 TraceMemo 中打开：

-你可以直接浏览聊天，也可以用自然语言提问：
+**日报 → 今日日报 → 日报模板 → 模板市场**

-> “上个月我们讨论过哪些发布问题？”
->
-> “张三之前发过的项目地址在哪里？”
->
-> “技术交流群今天有哪些结论和待办？”
+即可查看、预览、安装和切换已发布的社区模板。

-它和普通聊天记录查看器最大的不同，是 AI 不只是告诉你答案，还会告诉你答案来自哪里。
+如果你有一张喜欢的日报长图、网页或前端项目，也可以把它交给 Codex、ChatGPT 或其他能够读取 GitHub 仓库的 AI，并让它读取 [TraceMemo Template Contributor Skill](https://github.com/Wxw-Gu/TraceMemo-Templates/tree/main/skills/tracememo-template-contributor)。AI 可以帮助你完成模板转换、真实预览，并在你确认满意后向 [TraceMemo-Templates](https://github.com/Wxw-Gu/TraceMemo-Templates) 提交 Pull Request。

-你可以看到答案参考了哪些内容、来自哪个会话和时间，再回到原始消息确认它有没有理解错。
-
-TraceMemo 不提供任何微信聊天数据，也不鼓励收集、上传、出售、共享或未经授权处理他人的聊天记录。使用 TraceMemo 时，请确保你对所处理的数据具有合法的访问和使用权限，并自行承担相应的数据安全与合规责任。
+模板通过审核并正式发布后，其他 TraceMemo 用户即可在模板市场中安装使用。

 ---

-## 为什么叫 TraceMemo（迹忆）
+## TraceMemo 是什么

-<details>  
-`Trace` 代表聊天记录留下的痕迹、可以追溯的信息来源、AI 搜索过程，以及从结果回到原始聊天上下文并核对证据的能力。
+TraceMemo（迹忆）原名 **WechatExplorer** 是一款本地优先的微信数据、AI 分析与自动化工作台，把聊天变成可浏览、可搜索、可理解、可追溯的信息。

-`Memo` 代表记忆、知识沉淀和长期保存：让聊天中产生的信息逐渐形成个人知识。
+先用档案找原话，再按需要使用 AI Search、日报、监控或 Agent。普通浏览、搜索和导出不需要 AI。

-“迹忆”可以理解为“留下痕迹的记忆”。
+## 核心能力

-TraceMemo 不是单纯查看微信聊天记录的工具，而是希望让聊天中产生的信息留下痕迹，并能够被再次找到、理解、验证和沉淀。
+- 💬 **聊天档案与搜索**：浏览会话，按关键词或身份信息查找。
+- 🔍 **AI Search / 问问微信**：用自然语言找回模糊记忆，并查看来源。
+- 🧠 **本地知识库**：建立索引，提升跨会话查询稳定性。
+- 📊 **群聊日报**：生成今日、昨日或近 7 天的群聊总结。
+- 👀 **群成员变化监控**：记录指定群聊的退群动态。
+- 🔊 **文字转语音**：生成语音，试听后发送到选定会话。
+- 🤖 **Agent Hub**：在微信里调用本机 TraceMemo。
+- 🔌 **外部 Agent / Local HTTP API**：让外部 Agent 查询本机微信历史。

-> **品牌说明**
->
-> TraceMemo（迹忆）原名 WechatExplorer。WechatExplorer 最初是一个用于查看和探索微信聊天记录的工具。随着本地搜索、AI 问答、来源追溯、知识库、日报、语音转写和 Agent 能力逐渐形成，项目已经从单纯的聊天记录查看器发展为本地 AI 知识与分析工作台，因此在 v2.2.0 正式更名为 TraceMemo（迹忆）。
+## 💻 平台支持

-</details>
+TraceMemo 2.4.0 支持：

---
+- **Windows x64**
+- **macOS Apple Silicon（M 系列 / arm64）**
+- **macOS Intel（x64）**
+
+Windows 与 macOS 均支持微信本地数据库连接与数据库 Key 获取。

 ## 项目缘起

@@ -88,11 +96,11 @@ TraceMemo 最早叫 **WechatExplorer**。

 第一个版本完成后，项目搁置了一段时间。后来重新捡起来，我还是想继续做群聊日报，但微信已经更新到 4.x，原来的微信 3.0 数据解析方案不再适用。

-为了支持微信 4.x，我开始重新研究数据访问。这部分工作得到了 **WeFlow** 很大的帮助。TraceMemo 目前的微信 4.x 数据连接能力，参考并使用了 **WeFlow 历史版本中的相关实现和思路**，包括数据库密钥获取、图片解密等底层能力。
+为了支持微信 4.x，我开始重新研究数据访问。这部分工作最初得到了 **WeFlow** 很大的帮助。早期 TraceMemo 曾参考 WeFlow 历史版本中的实现和思路，借此解决了数据库消息、密钥获取等微信 4.x 数据访问问题。

-> **没有 WeFlow，就没有今天的 TraceMemo。**
+随着项目继续发展，我逐步把这部分底层能力从原有实现中抽离，并重新实现了一套独立的数据访问兼容层。目前会继续保持与 WeFlow 历史接口和行为的兼容，以减少上层业务迁移成本。

-WeFlow 帮我跨过了微信 4.x 数据访问这道门槛，我才有机会继续做后面的事情：让聊天记录可以被搜索、理解和总结，也让 AI 给出的答案能够回到原始消息核对。
+也就是说，**WeFlow 是 TraceMemo 进入微信 数据访问领域的重要起点。没有 WeFlow，就没有今天的 TraceMemo。**

 在此基础上，项目陆续加入了：

@@ -105,12 +113,15 @@ WeFlow 帮我跨过了微信 4.x 数据访问这道门槛，我才有机会继
 - Reader Skill
 - Agent 接入
 - 多种聊天记录导出能力
+- 退群监控
+- 文字转语音
+- 持续监控自动化能力

 群聊日报后来被一些人看到，项目也开始有了 Star、Fork、使用反馈和功能建议。说实话，我一开始没想到，这个原本只给自己用的小工具，会得到这么多人的关注。

 这些关注和反馈让我决定认真把项目继续做下去。WechatExplorer 就这样一步一步变成了今天的 **TraceMemo（迹忆）**。

-感谢 WeFlow，也感谢每一位使用、关注和反馈过 TraceMemo 的人。
+感谢每一位使用、关注和反馈过的人。

 </details>

@@ -124,298 +135,54 @@ WeFlow 帮我跨过了微信 4.x 数据访问这道门槛，我才有机会继

 ## 从你的任务开始

-| 我现在想做什么                            | 在应用里打开                                                        | 需要准备什么                         |
-| ----------------------------------------- | ------------------------------------------------------------------- | ------------------------------------ |
-| 找一句记得原文或关键词的聊天              | [档案](./docs/user-guide/chat-archive.md)                           | 连接微信数据，不需要 AI              |
-| 找一件记得大意、但不知道在哪聊过的事      | [问问微信](./docs/user-guide/ai-search.md)                          | 配置 AI 服务，并选择会话和时间范围   |
-| 让长期、跨群聊查找更稳定                  | [问问微信 → 本地知识库](./docs/user-guide/knowledge.md)             | 主动建立本地索引；不会自动创建       |
-| 快速了解一个群今天、昨天或近 7 天聊了什么 | [日报](./docs/user-guide/report.md)                                 | 选择群聊并配置 AI 服务               |
-| 把群聊日报生成微信分享卡片（实验性）      | [微信分享卡片](./docs/deployment/experimental-wechat-share-card.md) | 自备 Cloudflare、域名和微信测试号    |
-| 把微信语音变成可搜索的文字                | [设置 → 语音转文字](./docs/user-guide/voice.md)                     | 准备本地语音模型                     |
-| 把聊天保存成 HTML、Markdown、CSV 或 JSON  | [导出](./docs/user-guide/export.md)                                 | 选择聊天、时间和格式，不需要 AI      |
-| 尽量保留之后捕获到的撤回消息              | [设置 → 防撤回](./docs/user-guide/recall-protection.md)             | 默认关闭；开启前先了解写入和性能边界 |
-| 直接在微信里向 TraceMemo 提问             | [微信机器人](./docs/agent/agent-hub.md)                             | 扫码连接机器人；总结类任务需要 AI    |
-| 让 Codex 等外部 Agent 查询微信历史        | [外部 Agent](./docs/agent/overview.md)                              | 安装 Reader Skill 并配置本机 Token   |
-
---
-
-## 最核心的三个能力
-
-### 生成群聊日报
-
-选择群聊和时间范围后，可以让 AI 把聊天整理成报告，并保存为 HTML 与 PNG 长图。
-
-报告包含：
-
- 热点
- 重要消息
- 资源
- 问答
- 待办
- 未解决事项
- 活跃统计
- 图片精选
-
-具体内容取决于消息、媒体是否可读以及模型能力。
-详细说明：[生成群聊日报](./docs/user-guide/report.md)
-
-</details>
-
-### AI 帮你找回聊过的内容
-
-打开“问问微信”，选择搜索范围和时间，然后像提问一样描述你想找的内容。
-
-TraceMemo 会先在本机查找候选消息，再把整理后的少量来源交给你配置的 AI 模型生成回答。
-
-你可以查看答案参考了哪些聊天、来自哪个人和时间，并从来源标记跳回原始消息核对；“查看检索详情”还会展示本次查找经历了哪些阶段。
-
-<p align="center">
-  <img src="./public/问一问.png" alt="问问微信与聊天来源" />
-</p>
-
-详细说明：[使用 AI 查找聊天信息](./docs/user-guide/ai-search.md)
-
-### 直接在微信里问你的历史聊天
-
-打开应用中的“Agent”入口（页面标题为“Agent Hub”，对应微信机器人功能），扫码连接一个微信机器人账号。
-
-例如，你可以直接给机器人发送：
-
- “最近 5 个会话”
- “张三最近和我聊了什么”
- “总结今天的技术交流群”
-
-TraceMemo 会在本机读取已连接的聊天数据并把结果回复到微信。
-
-这个入口不要求另外安装 Codex、Claude Code 等外部 Agent。
-
-当前主要处理文字消息，不支持群发、定时任务或通用自主操作微信；总结和自然语言理解需要先配置 AI 服务。
-
-详细步骤和能力边界见[在微信里向 TraceMemo 提问](./docs/agent/agent-hub.md)。
-
---
-
-## 其他能力
-
-### 本地知识库
-
-<details>
-“问问微信”里的“本地知识库”会为当前微信账号建立一份留在本机的可检索资料。
-
-它把聊天文本、附件信息和已有语音转写整理起来，让跨会话、跨时间查找更稳定。
-
-它只在用户主动建立后工作，可以同步、查看占用并清理；清理不会删除微信原始数据库。
-
-详细说明：[本地知识库](./docs/user-guide/knowledge.md)
-
-</details>
-
-### 实验性：生成微信分享卡片
-
-<details>
-TraceMemo 可以把群聊日报长图上传到你自己部署的 Cloudflare Worker 和 R2，并生成可在微信中分享的临时网页、二维码及卡片信息。
-
-该功能需要自备 Cloudflare 账号、域名和微信测试号，目前不属于开箱即用的稳定功能。
-
-<p align="center">
-  <img src="./public/微信卡片分享.png" alt="微信卡片分享效果示例" />
-</p>
-
-详细说明：[实验性微信分享卡片](./docs/deployment/experimental-wechat-share-card.md)。
-
-不熟悉命令行的用户，可以把[自动部署 Skill](./docs/skill/setup-wechat-share-card/SKILL.md)直接交给 Codex 或 Claude Code。
-
-</details>
-
-### 转写微信语音
-
-<details>  
-TraceMemo 支持在本机转写单条或批量微信语音，结果可以参与本地知识库检索和 HTML 导出。
-
-转写本身不要求把语音文件发送给在线 AI；随后用于 AI 问答或日报时，文字会按对应功能的规则处理。
-
-详细说明：[语音转文字](./docs/user-guide/voice.md)
-
-</details>
-
-### 导出长期可用的聊天档案
-
-<details>
-支持 HTML、CSV、JSON 和 Markdown。
-
-HTML 可携带媒体、头像和可选语音转写，支持最多五个会话合并，也可以压缩为 ZIP；增量合并、媒体资源和 ZIP 只适用于 HTML，其他格式主要保留文本内容。
-
-详细说明：[导出聊天](./docs/user-guide/export.md)
-
-</details>
-
-### 在外部 Agent 中查询微信历史
-
-<details>
-通过 Reader Skill 和本机 Local HTTP API，Codex、Claude Code、OpenClaw 等外部 Agent 可以按需查询联系人、群聊和聊天记录。
-
-这和微信机器人是两条不同路径：
-
- **微信机器人**：收到消息后在微信中回复。
- **外部 Agent**：主动查询历史。
-
-安装和技术说明请看[Agent 接入概览](./docs/agent/overview.md)与[Local HTTP API](./docs/agent/api.md)。
-
-</details>
-
---
-
-## 它如何工作
-
-```mermaid
-flowchart LR
-    A[本机微信数据] --> B[TraceMemo 读取与解析]
-    B --> C[聊天档案]
-    B --> D[本地知识库与搜索]
-    D --> E[筛选相关聊天来源]
-    E --> F[用户配置的 AI 模型]
-    F --> G[带来源的回答]
-    B --> H[整理日报输入]
-    H --> F
-    B --> I[聊天导出]
-    B --> J[Local HTTP API]
-    J --> K[外部 Agent]
-    L[微信机器人消息] --> M[Agent Hub]
-    M --> B
-    M --> F
-```
-
- 微信数据库读取、聊天解析、知识库索引和离线语音识别在本机完成。
- 普通浏览、普通搜索和导出不要求配置 AI 服务。
- 使用“问问微信”、群聊日报或图片理解等 AI 功能时，完成任务所需的内容可能发送到你选择的模型服务；具体发送范围和确认方式以对应功能页面为准。
- “问问微信”会先在本机缩小范围，不会默认把整个微信数据库作为一次模型请求发送。
-
-完整边界见：[数据、隐私与安全](./docs/user-guide/privacy.md)
-
---
-
-## 支持平台与安装包
-
-| 平台    | 处理器架构                     | Releases 安装包 |
-| ------- | ------------------------------ | --------------- |
-| Windows | x64                            | `-setup.exe`    |
-| macOS   | Apple Silicon（M 系列、arm64） | `.dmg`          |
-
-当前版本不支持 Intel 芯片的 Mac。
-
-当前代码面向微信 4.x 数据结构。实际连接结果仍会受到微信客户端版本、账号数据状态和系统权限影响；macOS 首次连接可能需要按页面提示完成额外授权。
-
---
+| 想做什么                           | 使用入口                      |
+| ---------------------------------- | ----------------------------- |
+| 找记得原文或关键词的消息           | 档案搜索                      |
+| 找记得大意、但不知道在哪聊过的内容 | AI Search / 问问微信          |
+| 长期跨群查询历史                   | 本地知识库                    |
+| 了解一个群今天或近 7 天聊了什么    | 群聊日报                      |
+| 持续关注群成员退出                 | 退群监控                      |
+| 按计划生成并发送群聊日报           | 定时日报                      |
+| 把文字生成微信语音                 | 文字转语音                    |
+| 在微信里向本机 TraceMemo 提问      | Agent Hub                     |
+| 让 Codex 等工具查询微信历史        | Reader Skill / Local HTTP API |
+| 把聊天保存成文件                   | 导出                          |

 ## 快速开始

-1. 从 [GitHub Releases](https://github.com/Wxw-Gu/WechatExplorer/releases) 下载安装包。
-2. 启动 TraceMemo，按照“第一次使用”页面选择微信数据目录。
-3. 第一次使用请先点击“开始连接”，按页面提示准备连接组件并获取数据库密钥；只有已经有密钥的高级用户才需要“手动连接”。
-4. 连接成功后打开“档案”，确认联系人和聊天消息已经出现。
-5. 先在“档案”里搜索一句你记得的原话；这一步不需要 AI。
-6. 需要 AI 问答或日报时，在“设置 → AI 模型”添加并测试 AI 服务，再打开“问问微信”或“日报”。
-7. 想直接在微信里提问时，打开“Agent”扫码连接微信机器人；想让 Codex 等外部 Agent 查询时，再进入“API”。
+1. 从 [GitHub Releases](https://github.com/Wxw-Gu/TraceMemo/releases) 下载对应平台的安装包。
+2. 启动应用，按“第一次使用”页面选择微信数据目录并完成连接。
+3. 打开“档案”，确认联系人和消息已加载后开始搜索。
+4. 需要 AI 时，在“设置 → AI 模型”添加并测试 Provider。

-Windows 安装后无法启动时，请先安装 [Microsoft Visual C++ x64 运行库](https://aka.ms/vc14/vc_redist.x64.exe)。
-
-当前完整测试过的微信客户端为 Windows `4.1.9.57` 和 macOS `4.1.8.100`；下载地址与连接要求见[第一次使用](./docs/user-guide/getting-started.md)。
-
-从 WechatExplorer v2.1.9 升级时，TraceMemo v2.2.0 会在首次启动检测旧设置、Knowledge、Token、AI Provider 和 Agent 数据，并在用户确认后复制到新的 TraceMemo 数据目录。
-
-迁移不会覆盖已有 TraceMemo 数据，也不会删除旧目录；详情见 [v2.2.0 正式品牌身份与安全升级迁移](./docs/agent/release-notes-v2.2.0.md)。
-
-如果 macOS 页面提示处理 SIP，请先阅读对应说明。具体步骤和限制见[第一次使用](./docs/user-guide/getting-started.md)。
-
-完整步骤：[第一次使用 TraceMemo](./docs/user-guide/getting-started.md)
-
---
-
-## 配置 AI
-
-需要 AI 问答、群聊日报或图片理解时，在“设置 → AI 模型”添加并测试一个服务。
-
-应用支持云端服务、Ollama 等本地服务和自定义接口；具体服务商的配置、计费和数据规则由服务商决定。
-
-使用本地服务可以减少数据离开电脑的路径，但本地服务的日志和配置仍由你自己负责。
-
-开发者和 Agent 用户可以从[Agent 接入概览](./docs/agent/overview.md)开始，再按需要查看[Local HTTP API](./docs/agent/api.md)与[API 安全](./docs/agent/api-security.md)。
-
---
+详细步骤见[第一次使用 TraceMemo](./docs/user-guide/getting-started.md)。

 ## 文档

- [文档首页](./docs/README.md)
- [第一次使用](./docs/user-guide/getting-started.md)
- [聊天档案与搜索](./docs/user-guide/chat-archive.md)
- [AI 查找聊天信息](./docs/user-guide/ai-search.md)
- [本地知识库](./docs/user-guide/knowledge.md)
- [群聊日报](./docs/user-guide/report.md)
- [实验性微信分享卡片](./docs/deployment/experimental-wechat-share-card.md)
- [微信分享卡片自动部署 Skill](./docs/skill/setup-wechat-share-card/SKILL.md)
- [语音转文字](./docs/user-guide/voice.md)
- [导出聊天](./docs/user-guide/export.md)
- [防撤回](./docs/user-guide/recall-protection.md)
- [数据、隐私与安全](./docs/user-guide/privacy.md)
- [Agent 接入](./docs/agent/overview.md)
- [微信机器人与 Agent Hub](./docs/agent/agent-hub.md)
- [Local HTTP API](./docs/agent/api.md)
- [开发与测试](./docs/development/overview.md)
+- [用户指南](./docs/README.md#用户指南)
+- [AI / Knowledge](./docs/README.md#ai-与知识库)
+- [Monitor / Automation](./docs/README.md#日报与自动化)
+- [Agent / API](./docs/README.md#agent--api)
+- [开发文档](./docs/development/overview.md)
+- [隐私与安全](./docs/user-guide/privacy.md)

---
+完整目录由[文档首页](./docs/README.md)维护。

-## 本地开发
+## 支持平台

-需要 Node.js、pnpm 7+、对应平台的 Electron/native 构建环境，以及 Go（用于微信连接器）。
+| 平台    | 架构                           | 微信连接                              | 安装包                          |
+| ------- | ------------------------------ | ------------------------------------- | ------------------------------- |
+| Windows | x64                            | 支持微信 4.x                          | `tracememo-<version>-setup.exe` |
+| macOS   | Apple Silicon（M 系列、arm64） | 自动获取数据库 Key，已适配微信 4.1.13 | `tracememo-<version>-arm64.dmg` |
+| macOS   | Intel（x64）                   | 自动获取数据库 Key，已适配微信 4.1.13 | `tracememo-<version>-x64.dmg`   |

-```bash
-pnpm install
-pnpm dev
-```
+## 参与贡献

-常用检查：
+稳定版在 `main`，只在发版时更新；所有改动都先进 `develop`，随**下一个版本**一起发布。

-```bash
-pnpm typecheck
-pnpm test:unit
-pnpm test:component
-pnpm test:integration
-pnpm test:e2e:build
-```
+**提 PR 请基于 `develop` 拉新分支，并把 PR 的目标分支设为 `develop`** —— 指向 `main` 的 PR 会被直接关闭。

-完整说明：[开发、测试与构建](./docs/development/overview.md)
-
---
-
-## 支持与反馈
-
-遇到问题时，先查看[常见问题与排查](./docs/user-guide/troubleshooting.md)。
-
-提交 Issue 时请提供：
-
- 操作系统
- 微信版本
- TraceMemo 版本
- 复现步骤
- 已遮挡敏感信息的截图
-
-请仅处理你有权访问的数据，并遵守适用的法律法规、组织政策和微信使用规则。
-
-数据库读取、解密、自动化和机器人能力都可能受平台版本与账号环境影响。
-
---
-
-## 许可说明
-
-TraceMemo 当前暂未提供独立的项目 `LICENSE` 文件。
-
-TraceMemo 允许个人使用、学习、修改、二次开发和 Fork，也欢迎基于项目进行非商业用途的再开发和分享。
-
-**但未经项目维护者书面许可，禁止将 TraceMemo 本身或基于 TraceMemo 的衍生版本用于商业用途，包括但不限于商业软件、付费服务、商业产品、SaaS 服务或其他直接或间接的商业活动。**
-
-仓库中的第三方组件以及参考项目均遵循各自适用的许可证和使用条款。TraceMemo 对第三方项目的参考、使用或集成，并不意味着这些第三方项目的代码或许可证发生变化。涉及第三方代码的部分，请以对应项目的许可证和授权范围为准。
-
---
+分支流程、提交信息风格、PR 前自检，以及**给 AI Agent 的硬性规则**，都在[参与贡献指南](./CONTRIBUTING.md)。

 ## 致谢

@@ -423,22 +190,33 @@ TraceMemo 的诞生离不开开源社区中许多优秀项目的工作。

 ### 特别感谢 WeFlow

-TraceMemo 在支持微信 4.x 时，参考并使用了 **[WeFlow](https://github.com/hicccc77/WeFlow)** 历史版本中的相关实现和思路，包括数据库密钥获取、图片解密等底层能力。
+TraceMemo 在早期适配微信 4.x 时，曾参考 **[WeFlow](https://github.com/hicccc77/WeFlow)** 历史版本中的相关实现和思路，包括数据库访问、密钥获取等底层能力。

-特别感谢作者 **hicccc77** 的理解和包容。项目与 WeFlow 的具体关系见[项目缘起](#项目缘起)。
+特别感谢作者 **[hicccc77](https://github.com/hicccc77)**。项目与 WeFlow 的具体关系见[项目缘起](#项目缘起)。

 ### 其他参考项目

 - **[WechatMessageExplorer](https://github.com/svcvit/WechatMessageExplorer)**
-  - 提供了数据库解析相关思路。
+  - 提供了数据解析相关思路。

 - **[chatlog](https://github.com/sjzar/chatlog)**
  - 提供了数据处理方面的参考。

+- **[wechat_chatter](https://github.com/yincongcyincong/wechat_chatter)**
+  - 提供了发送方面的参考。
+
 感谢所有开源作者，也感谢所有帮助 TraceMemo 发现问题、提出建议和持续使用它的人。

 ---

+## 最后说两句
+
+这个项目起初只是一个一时兴起的项目，所以它大概也不会有一份特别严肃的产品路线图。
+
+我可能会按照自己的兴趣继续折腾，也可能突然加入一些奇奇怪怪、但觉得有意思的功能—— 比如让AI给某个好友, 某个群发一个语音条(逗逗群友) 或者定时生成群聊日报并做成微信卡片。
+
+也因此，这个项目随时可能继续折腾，也可能因为其他事情暂时搁置。如果你有想要的功能，可以提Issue；如果觉得现有实现不符合你的需求，也欢迎直接 Fork 后自己改。
+
 <p align="center">
  <b>TraceMemo（迹忆）</b>
  <br />
@@ -0,0 +1,5 @@
+provider: github
+owner: Wxw-Gu
+repo: TraceMemo
+releaseType: release
+updaterCacheDirName: tracememo-updater
@@ -1,64 +1,71 @@
 # TraceMemo 文档

-TraceMemo 的文档按“你想完成什么”组织，而不是按源码模块组织。
+文档按产品任务和使用场景组织。需要集成或开发时，再看 Agent、概念和开发文档。

-## 从这里开始
+## 档案与搜索

- [第一次使用](./user-guide/getting-started.md)：安装、连接微信、完成第一次搜索和提问。
- [查看和搜索聊天](./user-guide/chat-archive.md)：找原话、回看上下文、处理媒体。
- [用 AI 查找聊天信息](./user-guide/ai-search.md)：理解普通搜索和 AI Search 的区别，并核对答案来源。
+- [第一次使用](./user-guide/getting-started.md)：安装、连接微信并完成第一次搜索。
+- [Intel Mac 获取微信密钥](./user-guide/intel-mac-key.md)：按页面检查结果准备环境并获取密钥。
+- [聊天档案与搜索](./user-guide/chat-archive.md)：浏览联系人和群聊，按关键词、备注、昵称、微信号或 wxid 查找消息；也包含档案中的文字转语音入口。

-## 你可以完成的任务
+## AI 与知识库

- [建立本地知识库](./user-guide/knowledge.md)
- [生成群聊日报和总结](./user-guide/report.md)
- [实验性：自托管微信分享卡片](./deployment/experimental-wechat-share-card.md)
- [交给 Agent 自动部署微信分享卡片](./skill/setup-wechat-share-card/SKILL.md)
- [语音转文字](./user-guide/voice.md)
- [导出聊天档案](./user-guide/export.md)
- [防撤回](./user-guide/recall-protection.md)
- [在微信里向 TraceMemo 提问](./agent/agent-hub.md)
- [数据、隐私与安全](./user-guide/privacy.md)
- [常见问题与排查](./user-guide/troubleshooting.md)
+- [AI Search / 问问微信](./user-guide/ai-search.md)：用自然语言找回记得大意、但不知道在哪个会话里的内容，并查看 Evidence、Citation 和 Search Trace。
+- [本地知识库](./user-guide/knowledge.md)：主动建立本地索引，提升跨会话、跨时间查询的稳定性。
+- [如何核对 AI 的回答来源](./concepts/answer-sources.md)：从来源回到原始消息，检查上下文和覆盖范围。
+- [从微信数据到回答、日报和导出](./concepts/how-it-works.md)：了解哪些步骤在本机完成，哪些 AI 功能可能调用 Provider。

-## 如果你想了解 AI 为什么这样回答
+## 日报与自动化

- [如何核对 AI 的回答来源](./concepts/answer-sources.md)：用用户语言解释依据、来源标记和查找过程。
- [从微信数据到回答、日报和导出](./concepts/how-it-works.md)：了解哪些步骤在本机完成，哪些步骤可能调用 Provider。
+- [群聊日报](./user-guide/report.md)：手动生成今日、昨日或近 7 天的群聊报告，也可以创建定时日报。
+- 定时日报会依次生成报告、保存 Report History，再按当前微信发送能力尝试通知；发送失败时可复用已有 PNG 重试。
+- 自动发送和监控动作通过统一执行边界，并保留执行记录；简要说明见[产品工作方式](./concepts/how-it-works.md#动作执行与审计)。

-## 微信机器人和外部 Agent
+## Monitor

-TraceMemo 有两种不同的接入方式。微信机器人是普通用户可以直接使用的产品能力；Reader Skill 和 Local HTTP API 面向已经在使用 Codex、Claude Code、OpenClaw 等外部 Agent 的用户。
+退群监控会比较当前成员与上一份有效快照，记录成员退出事件。它支持多群、Last Good Snapshot 和事件历史；监控关闭期间的变化不会在重新开启后补报。工作方式见[产品工作方式](./concepts/how-it-works.md#退群监控)。

-| 你想做什么                                                            | 应该看哪里                                                                 |
-| --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
-| 在微信里给机器人发消息，让本机读取数据、生成总结并回复                | [Agent Hub](./agent/agent-hub.md)                                          |
-| 在 Codex、Claude Code、OpenClaw 等外部 Agent 中主动查询过去的微信数据 | [Reader Skill](./agent/reader-skill.md) + [Local HTTP API](./agent/api.md) |
+## 语音能力

-### 在微信里提问
+- [语音转文字](./user-guide/voice.md)：在本机转写微信语音，结果可用于搜索、Knowledge 和导出。
+- [聊天档案与搜索](./user-guide/chat-archive.md#文字转语音)：把文字生成微信语音，试听后发送到当前联系人或群聊。

-打开应用一级导航中的“Agent”，进入“Agent Hub”后扫码登录微信机器人。机器人收到文字消息后，可以查询最近会话、读取联系人聊天、生成群聊总结图片或总结群成员发言，并把结果回复给发消息的人。它需要本地微信数据库已经连接；依赖 AI 的任务还需要配置 AI 服务。
+## Agent / API

- [Agent Hub](./agent/agent-hub.md)：连接机器人、查看运行状态和了解实时交互边界。
+Agent Hub 让微信机器人调用本机 TraceMemo；Reader Skill / Local HTTP API 让外部 Agent 主动查询历史数据。

-### 让外部 Agent 查询历史微信
+- [Agent 接入概览](./agent/overview.md)
+- [Agent Hub](./agent/agent-hub.md)
+- [Reader Skill](./agent/reader-skill.md)
+- [Local HTTP API](./agent/api.md)
+- [API 安全](./agent/api-security.md)

-连接 Reader Skill 后，你可以询问：
+## 导出与隐私

-> “总结今天技术交流群讨论了什么。”  
-> “过去一周有没有人提到这个项目？”
+- [导出聊天](./user-guide/export.md)：导出 HTML、Markdown、CSV 或 JSON 档案。
+- [数据、隐私与安全](./user-guide/privacy.md)：本地处理、Provider、媒体和 Token 的数据边界。
+- [常见问题与排查](./user-guide/troubleshooting.md)：按安装、连接、AI、媒体和 Agent 现象排查。

- [Agent 接入概览](./agent/overview.md)：先选择适合你的接入方式。
- [Reader Skill](./agent/reader-skill.md)：安装并让外部 Agent 按需读取聊天。
- [Local HTTP API](./agent/api.md)：完整端点和请求示例。
- [API 安全](./agent/api-security.md)：Bearer Token、CORS、轮换和边界。
+## 开发文档

-## 开发与平台
-
- [macOS 数据访问说明](./platform/macos.md)
 - [开发、测试与构建](./development/overview.md)
+- [界面开发规范：按钮与主题色](./development/ui-guidelines.md)
+- [微信系统消息解析与格式兼容](./development/wechat-system-message-parsing.md)
+- [Query Agent POC（开发测试入口）](./development/query-agent-poc.md)
 - [本地启动排障](./development/local-startup-troubleshooting.md)
- [v2.2.0 正式品牌身份与安全升级迁移](./agent/release-notes-v2.2.0.md)
- [v2.1.9 API 鉴权迁移说明](./agent/release-notes-v2.1.9.md)
+- [macOS 数据访问说明](./platform/macos.md)
+- [关闭 SIP 教程](./mac-disable-sip.md)

-当前工作区版本：**2.2.0**。文档只描述当前代码已经实现的能力；版本兼容性、AI Provider 行为和媒体读取结果可能随系统、微信客户端和服务商变化。
+## 实验性功能与第三方
+
+- [实验性：自托管微信分享卡片](./deployment/experimental-wechat-share-card.md)
+- [微信分享卡片自动部署 Skill](./skill/setup-wechat-share-card/SKILL.md)
+- [TraceMemo Reader Skill 文件](./skill/tracememo-reader/SKILL.md)
+- [第三方组件说明](./third-party/wechat-chatter/NOTICE.md)
+
+## 版本说明
+
+- [v2.2.0 品牌与安全迁移](./agent/release-notes-v2.2.0.md)
+- [v2.1.9 API 鉴权迁移](./agent/release-notes-v2.1.9.md)
+
+文档按当前 develop 已实现的能力维护，不在首页固定写死版本号。版本兼容性、AI Provider 行为和媒体读取结果可能随系统、微信客户端和服务商变化。
@@ -36,6 +36,7 @@ curl -H "Authorization: Bearer $TRACEMEMO_API_TOKEN" \
 | GET  | `/api/v1/chatroom`           | 群聊列表                               | `keyword`                                                       |
 | GET  | `/api/v1/recent_chat`        | 最近会话                               | `limit`，默认 50                                                |
 | GET  | `/api/v1/chatlog`            | 指定会话的聊天记录                     | 必填 `talker`；可选 `time` 或 `startTime`/`endTime`             |
+| GET  | `/api/v1/media/{mediaId}`    | 获取图片消息的二进制资源               | 原样使用 `/chatlog` 返回的 `media.url`，不要用消息 `id` 拼接     |
 | GET  | `/api/v1/group_snapshot`     | 群成员快照                             | 必填 `md5`                                                      |
 | GET  | `/api/v1/resolve`            | 将昵称、wxid 或 md5 解析为会话         | 必填 `q`                                                        |
 | POST | `/api/v1/report`             | 将结构化日报渲染为 HTML 与 PNG         | `GroupReportExportRequest` JSON                                 |
@@ -84,13 +85,114 @@ curl -H "$AUTH" "$BASE/chatlog?talker=技术交流群&time=2026-08-07"
 - `200`：请求成功；
 - `401`：缺少、错误或已失效的 Bearer Token；
 - `400`：参数或 JSON 请求体无效；
+- `422`：媒体标识格式错误，或目标消息不是可读取的图片（`NOT_IMAGE`）；
 - `403`：浏览器 Origin 不在允许的 loopback 列表；
- `404`：端点、会话或群聊不存在；
+- `404`：端点、会话或群聊不存在；媒体标识未登记、已过期、有歧义，或图片文件不存在（`NOT_FOUND`）。媒体请求遇到此状态时，先重新读取 `/chatlog` 并使用新的 `media.url`；若仍失败，再检查本地图片文件是否存在；
 - `503`：数据库或 Agent Hub 尚未就绪；
 - `500`：服务端处理或报告渲染失败。

 成功响应会返回端点对应的 JSON 对象，例如 `chatlog` 包含 `contact`、`query`、`count` 和 `messages`，`contact` 返回 `count` 与 `contacts`。

+图片消息在 `messages` 中保留原有字段，并额外提供 `media`：
+
+```json
+{
+  "type": "图片",
+  "content": "",
+  "media": {
+    "type": "image",
+    "available": true,
+    "url": "/api/v1/media/image%3A0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+  }
+}
+```
+
+当用户要求查看或理解图片时，使用 `media.url` 获取 `image/jpeg`、`image/png` 等真实二进制；不要根据 `[图片]` 猜测内容，也不要向 API 传入本地路径。
+
+`media.url` 包含当前数据库连接内的独立媒体标识，不等同于消息 `id`。不同会话的消息 `id` 可能重复，调用方应原样使用返回的地址，不自行拼接或解析。重启、重连或切换账号后须重新读取 `/chatlog` 获取新地址；旧的纯消息 ID 地址仅在无歧义时兼容。`available` 只表示消息带有图片定位信息，不保证本地图片文件仍存在或可以解密。
+
 ## 与 MCP 的关系

 当前实现没有把 `6131` 暴露为 MCP Server。需要在 Agent 中使用时，请安装随应用提供的 Reader Skill，并让 Skill 通过普通 HTTP 请求调用本 API。
+
+## LLM-friendly Query Tool API
+
+这些端点提供稳定的结构化 Query primitive，不接收自然语言问题，也不会调用 AI。它们与现有 API 共用端口、Bearer Token、loopback 和 CORS 安全策略。
+
+```bash
+BASE="http://127.0.0.1:6131/api/v1"
+AUTH="Authorization: Bearer ${TRACEMEMO_API_TOKEN:-$WECHATEXPLORER_API_TOKEN}"
+
+# 能力目录
+curl -H "$AUTH" "$BASE/query/capabilities"
+
+# BOBO 的第一条真实互动
+curl -X POST -H "$AUTH" -H 'Content-Type: application/json' "$BASE/query/messages" \
+  -d '{"target":{"query":"BOBO"},"timeRange":{"kind":"all"},"direction":"any","order":"asc","limit":1,"excludeSystem":true}'
+
+# 上个月 BOBO 发来的文件
+curl -X POST -H "$AUTH" -H 'Content-Type: application/json' "$BASE/query/messages" \
+  -d '{"target":{"query":"BOBO"},"timeRange":{"kind":"previous_month"},"direction":"from_target","messageTypes":["file"],"order":"desc","limit":1}'
+
+# 受限语义关键词检索（最多 4 个 variants）
+curl -X POST -H "$AUTH" -H 'Content-Type: application/json' "$BASE/query/search" \
+  -d '{"target":{"query":"BOBO"},"timeRange":{"kind":"all"},"query":"答应之后给我或者帮我完成某件事情","variants":["我给你","我发你","弄好给你"],"limit":20}'
+
+# 按会话和时间范围提取可供总结的证据
+curl -X POST -H "$AUTH" -H 'Content-Type: application/json' "$BASE/query/conversation-overview" \
+  -d '{"target":{"query":"BOBO"},"timeRange":{"kind":"previous_month"}}'
+```
+
+`query/messages` 的 `messageRef` 是服务端生成的不透明引用，可直接传给 `query/message-context` 获取前后文；不要自行构造 wxid、md5 或数据库路径。
+
+每条消息都会返回 `messageType`（`text`、`image`、`voice`、`video`、`file`、`link`、`sticker`、`system` 或 `other`）。非文本消息不会伪造 `text`；可识别的图片、视频、贴纸和文件会返回不含密钥或本地路径的 `attachment` 元数据。
+
+`conversation-overview` 同时返回 `sourceCoverage` 与 `selection`：前者描述时间范围内源消息是否完整及 `sourceMessageCount`，后者描述从源消息中选出的 Evidence 数量及是否抽样。`evidence` 最终按 `timestamp` 升序返回，`messageRef` 是唯一推荐的消息引用。
+`conversation-overview` 另有一个 `origin` 字段：`wcdb` 表示这次证据直接来自本机聊天数据库（会话概览的事实来源），`knowledge` 表示来自本地索引。
+
+### 搜索范围（scope）
+
+`query/messages`、`query/search`、`query/message-context` 和 `query/conversation-overview` 都接受一个可选的 `scope`，用来把检索限制在一个确定的语料边界内：
+
+| scope | 含义 |
+| ----- | ---- |
+| `{"kind":"all"}` | 所有可读会话（默认；省略 `scope` 等价于此） |
+| `{"kind":"groups"}` | 只搜群聊语料，**且包含群成员实际发送的消息**（不是群名称或群元数据） |
+| `{"kind":"contact","conversationId":"…"}` | 只搜该一对一会话 |
+| `{"kind":"current","conversationId":"…"}` | 只搜指定的那个会话（单聊或群聊） |
+
+`conversationId` 是会话标识，可用 `/api/v1/resolve` 或 `/api/v1/contact` 得到。`scope` 一旦给出就是**权威边界**：`target` 落在范围之外会被拒绝（`status: "invalid_tool_arguments"`、`constraint: "target_outside_scope"`），不会静默扩大范围；范围里包含多个会话时，`query/messages` 与 `query/conversation-overview` 必须显式指定 `target`（`constraint: "target_required_for_scope"`）。
+
+响应会回显实际生效的边界：
+
+```json
+{ "scope": { "kind": "groups", "conversationCount": 243 } }
+```
+
+跨会话检索时，`evidence` 的每一项都会带上它所属的会话，便于把结果归属到具体群 / 联系人与具体成员：
+
+```json
+{
+  "messageRef": "…",
+  "conversationName": "某个群",
+  "conversationType": "group",
+  "sender": "某成员",
+  "timestamp": 1789099069000,
+  "text": "…"
+}
+```
+
+### 索引新鲜度（freshness）
+
+`query/search` 依赖本地索引，而本地索引是异步建立的派生数据，可能落后于聊天数据库。因此它的响应会显式给出覆盖口径：
+
+| 字段 | 含义 |
+| ---- | ---- |
+| `indexLatestAt` | 索引目前覆盖到的源数据时间（epoch ms），`null` 表示无法判定 |
+| `sourceLatestAt` | 聊天数据库里最新的活跃时间（epoch ms），`null` 表示无法判定 |
+| `coverage.state` | `complete` 只在索引确实覆盖了所请求的时间范围时出现 |
+| `freshness.catchUp` | 本次为追赶索引做了什么：`none` / `reused` / `completed` / `pending` |
+
+调用方**必须**把 `coverage` 当真：`coverage.state` 不是 `complete` 且 `evidence` 为空时，只能说明"这段范围暂时无法确认"，**不能**下"没有找到"的结论。索引落后时服务端会自动请求一次追赶同步，但不会让请求无限等待；`freshness.catchUp` 为 `pending` 表示追赶仍在后台进行，稍后重试即可拿到更新的覆盖。
+
+`query/messages` 与 `query/conversation-overview` 直读聊天数据库，不受索引新鲜度影响。
@@ -28,12 +28,12 @@ AI 回答后，你可以继续查看它参考了哪些聊天内容、这些内

 来源覆盖受时间范围、会话范围、索引状态和可读媒体影响。例如：

- Knowledge 正在同步时，新的分析会被暂停；
+- Knowledge 还没追到最新时，跨会话检索只覆盖到索引当前的时间点，答案会标注这个范围；
 - 语音没有转写时，AI 可能只能看到消息类型；
 - 图片无法读取或未启用图片理解时，AI 不应声称知道图片内容；
 - 你只选择了一个群，答案不会自动代表所有聊天。

-看到“可能遗漏”或“部分覆盖”时，扩大范围、先完成同步或检查原始媒体后再问。
+Knowledge 在后台同步时**不会**暂停分析：你仍然可以提问，只是答案基于当前已可用的覆盖范围。看到“可能遗漏”或“部分覆盖”时，扩大范围、等同步追上或检查原始媒体后再问。

 ## 这不是事实保证

@@ -19,8 +19,45 @@ flowchart LR
  M[微信机器人消息] --> N[Agent Hub]
  N --> B
  N --> F
+  B --> O[Monitor / Snapshot]
+  O --> P[Proposed Action]
+  F --> P
+  P --> Q[Policy]
+  Q --> R[Action Gateway]
+  R --> S[Personal WeChat Send Capability]
+  S --> T[Action Audit / Logs]
 ```

+## Remember → Understand → Monitor → Act
+
+TraceMemo 的工作方式可以概括为：
+
+```text
+Remember → Understand → Monitor → Act
+```
+
+先读取和整理微信信息，再由 AI、Knowledge 或日报帮助理解；Monitor 负责发现成员变化，明确的业务动作再进入执行边界。回答和动作结果都应能回到来源或记录核对。
+
+## 退群监控
+
+退群监控使用成员快照判断变化：
+
+```text
+Current Membership → Snapshot Diff → Member Event
+```
+
+上一份有效快照（Last Good Snapshot）不会被不完整读取覆盖，因此重启后仍可继续监控通知。
+
+## 动作执行与审计
+
+自动发送和监控动作经过统一边界：
+
+```text
+Feature → Policy → Gateway → Capability → Execution → Audit
+```
+
+Policy blocked 表示策略不允许，Capability unavailable 表示当前发送能力不可用，Send failed 表示已经尝试但执行失败。Action Audit / Logs 会保留执行结果；定时日报即使发送失败，也会保留已生成的报告记录。
+
 ## 哪些步骤在本机

 - 微信数据库读取与解析；
@@ -6,47 +6,43 @@

 执行 `pnpm dev` 后，以下状态同时满足，说明本地开发环境已经可用：

- 控制台显示连接器已生成，例如 `resources/connectors/wechat/win32-x64/wechat-connector.exe`；
 - Electron 窗口已打开，或 `http://localhost:5173/` 返回 HTTP `200`；
 - 控制台显示 Local HTTP API 正在监听 `http://127.0.0.1:6131`。

 `6131` 是应用提供给本机集成使用的 API 端口，不是 Vite 的页面端口。

-## Go 命令找不到
+## WCDB 消息读取诊断

-如果 `pnpm dev` 在构建微信连接器时出现 `spawnSync go ENOENT`，先执行：
+`WCDB_DEBUG_LOGS` 默认关闭。需要排查消息读取链路时，可以在启动命令前设置为 `1`：

 ```bash
-go version
+WCDB_DEBUG_LOGS=1 pnpm dev
 ```

-命令不可用表示当前终端的 `PATH` 没有找到 Go。Windows 默认安装位置是 `C:\Program Files\Go\bin`。确认 Go 已安装并把该目录加入系统 `PATH` 后，关闭并重新打开终端或 IDE，再重新执行 `go version` 和 `pnpm dev`。
-
-如果 Go 刚完成安装，已经打开的终端不会自动继承新的环境变量；重开终端是必要步骤。不要绕过连接器构建直接启动 `electron-vite dev`，否则 Agent Hub 的微信连接器不会生成。
+开启后会输出 `GETMSG-xxx` 请求耗时和 native `WCDB-EXPLAIN` 执行计划，不记录聊天正文。取消该环境变量或设为 `0` 即可关闭。

 ## Electron 二进制缺失或下载失败

 `electron-vite dev` 报 `Electron uninstall`，或 Electron 安装器报 `fetch failed`，通常表示 `node_modules/electron/dist` 中的 Electron 二进制缺失或下载未完成。这不是应用业务代码的启动错误。

-项目的 [`.npmrc`](../../.npmrc) 已设置：
+**先看根因，别急着删 `node_modules` 重装。** `electron@43` 的 npm 包**不再声明 `postinstall`**（其 `package.json` 里 `scripts` 是空对象），下载改为「首次 `require('electron')` 时的懒加载」。因此：

-```ini
-electron_mirror=https://npmmirror.com/mirrors/electron/
-```
+- `package.json` 里的 `pnpm.onlyBuiltDependencies: ["electron"]` 对它不起作用——上游没有脚本可执行，pnpm 无从下手；
+- `pnpm install` 跑完不会有任何二进制被下载，**只重装依赖解决不了这个问题**。

-pnpm 会把该值传给 Electron 安装器，令其从镜像下载与 `package.json` 锁定版本匹配的二进制文件，避免默认 GitHub 下载源在受限网络中不可访问。
+项目已自动兜住这条路径：`scripts/ensure-electron-binary.cjs` 挂在 `postinstall` 与 `predev` 上，校验 `path.txt` 指向的可执行文件是否真的存在（只有 `path.txt` 而没有 `dist/` 同样算没装好），缺失时就地补下载。它读取 `.npmrc` 的 `electron_mirror`（当前为 `https://npmmirror.com/mirrors/electron/`），失败后再兜底重试一次该镜像。

-依赖安装被中断或 Electron 目录不完整时，删除不完整的 `node_modules` 后重新安装：
+正常情况下你不需要做任何事。只有当自动步骤没有执行时（例如安装时带了 `--ignore-scripts`），才需要手动补一次：

 ```bash
-pnpm install --frozen-lockfile
+node scripts/ensure-electron-binary.cjs
 ```

-单次安装需要使用其他镜像时，可以临时覆盖项目默认值。PowerShell 示例：
+要换用别的镜像时，显式设置环境变量（优先于 `.npmrc`）。PowerShell 示例：

 ```powershell
 $env:ELECTRON_MIRROR = 'https://your-electron-mirror.example/'
-pnpm install --frozen-lockfile
+node scripts/ensure-electron-binary.cjs
 ```

 该环境变量只影响当前终端，不会改写仓库中的 `.npmrc`。镜像地址必须保留末尾的 `/`，并提供与 Electron 版本对应的目录结构。
@@ -59,4 +55,4 @@ Vite 在某些 Windows 环境中只监听 IPv6 本机回环地址 `::1`。这时

 ## 仍无法启动时

-保留首次错误的完整输出，并同时记录操作系统、Node.js、pnpm 和 Go 版本，以及 `pnpm install --frozen-lockfile` 与 `pnpm dev` 的执行结果。不要提交数据库密钥、AI API Key、微信数据路径或聊天内容。
+保留首次错误的完整输出，并同时记录操作系统、Node.js 与 pnpm 版本，以及 `pnpm install --frozen-lockfile` 与 `pnpm dev` 的执行结果。不要提交数据库密钥、AI API Key、微信数据路径或聊天内容。
@@ -6,7 +6,6 @@

 - Electron + React + TypeScript；
 - pnpm 7+；
- Go（构建微信连接器）；
 - 平台对应的 Electron/native 构建环境。

 产品文档的事实来源优先级是：当前源码 → 当前 UI/Renderer → 测试 → package/config → README/docs → 历史资料。功能、API、版本、隐私和兼容性变更时，不要只改 README。
@@ -18,7 +17,7 @@ pnpm install
 pnpm dev
 ```

-本地依赖安装、Go 环境和 Electron 二进制下载异常，请查看[本地启动排障](./local-startup-troubleshooting.md)。
+本地依赖安装与 Electron 二进制下载异常，请查看[本地启动排障](./local-startup-troubleshooting.md)。

 常用检查：

@@ -30,21 +29,21 @@ pnpm test:integration
 pnpm test:e2e:build
 ```

-完整测试入口 `pnpm test` 还会运行 Skill 安装指令、微信连接器、构建和 Playwright 测试；需要对应平台环境。
+完整测试入口 `pnpm test` 还会运行 Skill 安装指令、构建和 Playwright 测试；需要对应平台环境。

 ## 代码变更对应文档

-| 代码区域                                                  | 需要同步检查的文档                                         |
-| --------------------------------------------------------- | ---------------------------------------------------------- |
-| `src/shared/ai-search.ts`、AI Search pipeline             | `user-guide/ai-search.md`、`concepts/answer-sources.md`    |
-| `src/shared/knowledge.ts`、`src/main/knowledge/`          | `user-guide/knowledge.md`、`concepts/how-it-works.md`      |
-| `src/shared/voice-recognition.ts`                         | `user-guide/voice.md`                                      |
-| `src/shared/group-report.ts`、报告 UI                     | `user-guide/report.md`、API/Agent 文档                     |
-| `src/shared/export.ts`、导出服务/UI                       | `user-guide/export.md`                                     |
-| `src/main/services/recall-archive-service.ts`、防撤回设置 | `user-guide/recall-protection.md`、`user-guide/privacy.md` |
-| `src/shared/local-api-test.ts`、`src/main/http-server.ts` | `agent/api.md`、`api-security.md`、打包 Skill              |
-| Agent Hub service/UI                                      | `agent/agent-hub.md`、`user-guide/privacy.md`              |
-| 设置导航、连接页面                                        | `user-guide/getting-started.md`、`docs/README.md`          |
+| 代码区域                                                  | 需要同步检查的文档                                      |
+| --------------------------------------------------------- | ------------------------------------------------------- |
+| `src/shared/ai-search.ts`、AI Search pipeline             | `user-guide/ai-search.md`、`concepts/answer-sources.md` |
+| `src/shared/knowledge.ts`、`src/main/knowledge/`          | `user-guide/knowledge.md`、`concepts/how-it-works.md`   |
+| `src/shared/voice-recognition.ts`                         | `user-guide/voice.md`                                   |
+| `src/shared/group-report.ts`、报告 UI                     | `user-guide/report.md`、API/Agent 文档                  |
+| `src/shared/export.ts`、导出服务/UI                       | `user-guide/export.md`                                  |
+| `src/main/services/recall-archive-service.ts`             | `user-guide/privacy.md`                                 |
+| `src/shared/local-api-test.ts`、`src/main/http-server.ts` | `agent/api.md`、`api-security.md`、打包 Skill           |
+| Agent Hub service/UI                                      | `agent/agent-hub.md`、`user-guide/privacy.md`           |
+| 设置导航、连接页面                                        | `user-guide/getting-started.md`、`docs/README.md`       |

 ## 文档检查

@@ -52,7 +51,7 @@ pnpm test:e2e:build

 ```bash
 git diff --check
-rg -n "v2\.1\.7|TraceMemo|迹忆|mcpServers|无鉴权" README.md docs --glob '*.md' --glob '!DOCUMENTATION_AUDIT.md' --glob '!development/overview.md'
+rg -n "v2\.1\.7|TraceMemo|迹忆|mcpServers|无鉴权" README.md docs --glob '*.md' --glob '!development/overview.md'
 ```

 历史迁移说明可以出现旧版本号；正式使用指南不要把过时版本写成当前版本。负向澄清“6131 不是 MCP Server”可以保留，以防用户照抄错误配置。
@@ -0,0 +1,84 @@
+# Query Agent POC
+
+这是独立的开发测试入口，不会修改生产“问问微信”执行链。
+
+先启动 TraceMemo，并在 API Center 开启 Local HTTP API。然后在仓库根目录运行：
+
+```bash
+pnpm poc:query-agent "我和BOBO第一次聊了什么"
+```
+
+## 两个入口
+
+| 命令 | 行为 | 何时用 |
+| --- | --- | --- |
+| `pnpm poc:query-agent "问题"` | 先执行完整构建，再运行 | 首次运行，或刚改过代码 |
+| `pnpm poc:query-agent:run "问题"` | 直接运行已有构建，**不构建** | 连续迭代测试 |
+
+`poc:query-agent:run` 在构建产物不存在时会明确提示先运行 `pnpm poc:query-agent`，**不会自动构建**。
+
+注意：`poc:query-agent` 内部走的是完整 `electron-vite build`（main + preload + renderer），
+即使 POC 只需要一个 main entry。连续测试请使用 `poc:query-agent:run` 以免每次都重建整个 renderer。
+
+## 传参
+
+参数按原样转发给入口，可以被 `--` 分隔（`pnpm run` 惯例）：
+
+```bash
+pnpm poc:query-agent -- "BOBO上个月有没有给我发过文件"
+pnpm poc:query-agent:run "BOBO上个月有没有给我发过文件"
+```
+
+入口只会移除参数列表**开头**的一个独立 `--`；问题正文中的 `--` 会原样保留。
+
+## Provider
+
+POC 使用设置页当前默认 AI Provider、模型、Base URL 和安全存储中的 API Key。Local Query API 仍使用现有 Bearer Token；POC 输出不会打印 Token、API Key、数据库路径或内部消息 ID。
+
+## 输出
+
+**stdout 是 JSON**（`poc:query-agent` 会在它前面混入构建日志，`poc:query-agent:run` 只多两行 pnpm 横幅）。
+需要机器解析时用 `--silent` 拿到纯 JSON：
+
+```bash
+pnpm --silent poc:query-agent:run "我和BOBO第一次聊了什么" > result.json
+```
+
+JSON 字段：
+
+- `question`、`provider`、`model`
+- `modelCallCount`、`toolCallCount`
+- `modelDurationsMs`（每次模型调用耗时，含失败的那次）
+- `modelDiagnostics`（每次模型调用的请求级诊断：HTTP status、content-type、是否返回 HTML、是否超时、耗时）
+- `firstModelMs`、`toolTotalMs`、`finalModelMs`、`totalMs`
+- 每次工具调用的名称、脱敏参数、耗时、状态和结果数量
+- 最终 `answer` 或错误信息
+
+**stderr 是人类可读摘要**（不参与 JSON 解析）：
+
+```text
+[Timing]
+Model #1         1315 ms
+TM Tools(1)       623 ms
+Model #2         1598 ms
+------------------------
+Total            3545 ms
+Model total   2913 ms (82.2%)
+TM tool total 623 ms (17.6%)
+
+[Provider]
+provider       DeepSeek
+model          DeepSeek Chat
+host           api.deepseek.com
+model calls    2
+tool calls     1
+attempt #1    elapsedMs=1298 status=200 contentType=application/json
+attempt #2    elapsedMs=1571 status=200 contentType=application/json
+```
+
+`elapsedMs` 是 TTFB（收到响应头），`modelDurationsMs` 是整次调用（含读 body）；502 时两者接近，
+说明等待发生在上游网关，不是本地读 body 慢。诊断只记录 host，不记录完整 URL 或任何凭据。非 2xx 响应会先记录 status / content-type / elapsedMs，再返回安全错误（例如“模型服务返回了网页而不是 JSON（HTTP 502 Bad Gateway）”），不会把 HTML 正文丢给 JSON 解析器。
+
+## 约束
+
+工具调用最多 5 次，只允许 `query_messages`、`search_messages`、`message_context`、`conversation_overview`。未配置 AI Provider、Local Query API 未启动或当前 Provider 协议不支持 tools 时，POC 会直接返回错误，不会回退到另一套模型配置。
@@ -0,0 +1,171 @@
+# 界面开发规范：按钮与主题色
+
+这份规范回答一件事：**为什么同一个产品里，有的按钮是主题色，有的还是浏览器默认的黑白方角。**
+
+先看一个真实案例 —— 同一屏里的两组按钮：
+
+```
+主界面：「更新图片文字索引」        ← 主题色（正确）
+弹窗里：「取消」「开始索引」        ← 浏览器默认样式（错误）
+```
+
+两者渲染出来完全不同，用户会以为是两个不同的产品。根因不是"设计没定颜色"，
+而是**组件在导出时把样式丢了**。下面写清楚怎么避免。
+
+---
+
+## 1. 永远不要写裸 `<button>`
+
+任何可点的按钮都必须来自 `components/ui/button`：
+
+```tsx
+import { Button } from '../ui'
+
+<Button variant="outline" onClick={handleCancel}>取消</Button>
+```
+
+**唯一的例外**：结构性控件（导航项、Tab、列表行、图标热区）——它们有自己
+成套的布局样式，用原生 `<button>` 是合理的，但**必须**带 `className`，
+且样式写在对应的 `.scss` 里，不要在 JSX 里临时拼颜色。
+
+```tsx
+// 可以：结构性控件，样式来自 .scss
+<button type="button" role="tab" className={active ? 'active' : ''} onClick={...}>
+  今日日报
+</button>
+```
+
+**判据**：如果这个按钮在别的界面也会以同样形态出现（"取消"、"保存"、"删除"），
+它就该是 `Button`；如果它只在某一个位置有意义（侧栏导航项），才考虑原生。
+
+---
+
+## 2. 三种角色，只有三个默认变体
+
+`Button` 提供 6 个变体，但**日常只用其中 3 个**：
+
+| 角色 | `variant` | 长什么样 | 用在哪 |
+| --- | --- | --- | --- |
+| 主要 | `default` | 主题色实底 | 这一步用户唯一该做的事 |
+| 次要 | `outline` / `ghost` | 描边 / 无底色 | 取消、返回、并列的辅助操作 |
+| 危险 | `destructive` | 红色实底 | 删除、清空、不可恢复的操作 |
+
+另外两个（`secondary` / `link`）按需用；`link` 只用于正文里的行内跳转。
+
+**一条硬约束：同一个界面（或同一个弹窗）里，`default` 最多出现一次。**
+两个主题色实底按钮并排，等于没有主次。
+
+---
+
+## 3. 弹窗按钮：组件已经带样式了，不要再包一层
+
+`AlertDialogCancel` 和 `AlertDialogAction` **自带**按钮样式（分别是 `outline`
+和 `default`），直接写文字即可：
+
+```tsx
+<AlertDialogFooter>
+  <AlertDialogCancel>取消</AlertDialogCancel>
+  <AlertDialogAction onClick={handleStart}>开始索引</AlertDialogAction>
+</AlertDialogFooter>
+```
+
+**不要**再套一层 `Button`：
+
+```tsx
+// 反面写法：外层已经有样式了，再包一层只会产生重复类名
+<AlertDialogCancel asChild>
+  <Button variant="outline">取消</Button>
+</AlertDialogCancel>
+```
+
+需要危险动作时，用 `className` 覆盖（`cn` 走 tailwind-merge，同族类后者生效）：
+
+```tsx
+<AlertDialogAction className="bg-destructive text-destructive-foreground">
+  删除
+</AlertDialogAction>
+```
+
+---
+
+## 4. 颜色只能用语义 token，禁止硬编码
+
+颜色全部走 Tailwind 的语义类，它们背后是 `--tm-*` 变量，换主题时自动跟随：
+
+```
+背景   bg-primary / bg-surface / bg-accent / bg-destructive
+文字   text-foreground / text-primary-foreground / text-muted-foreground
+描边   border-border / border-border-subtle / border-disabled-border
+```
+
+```tsx
+// 对
+<Button className="bg-primary text-primary-foreground">保存</Button>
+
+// 错 —— 换主题时这行不会跟着变
+<Button className="bg-[#247a63] text-white">保存</Button>
+```
+
+**判据**：JSX 里出现 `#` 开头的颜色、`rgb(...)`、或 Tailwind 的调色板名
+（`bg-green-600`、`text-slate-500`）—— 都是漏用 semantic token 的信号。
+
+---
+
+## 5. 「默认样式」的三个常见来源
+
+排查界面里冒出来的黑白方角按钮时，按这个顺序找：
+
+**① 组件导出时把样式丢了。** 最常见。把 Radix 的 primitive 原样导出：
+
+```tsx
+// 错：渲染出来就是浏览器默认按钮
+const AlertDialogCancel = AlertDialogPrimitive.Cancel
+```
+
+正确做法是 `forwardRef` 包一层，挂上 `buttonVariants`：
+
+```tsx
+const AlertDialogCancel = React.forwardRef<...>(({ className, ...props }, ref) => (
+  <AlertDialogPrimitive.Cancel
+    ref={ref}
+    className={cn(buttonVariants({ variant: 'outline' }), className)}
+    {...props}
+  />
+))
+```
+
+**判据**：`components/ui/` 里凡是导出 Radix primitive 的地方，都要确认它是
+"样式化的封装"还是"原样透传"。原样透传只对布局容器（`Root` / `Portal` /
+`Group`）成立，对**可点元素**（`Close` / `Action` / `Cancel` / `Item`）不成立。
+
+**② `asChild` 里重复包了一层。** 外层已经带样式、子元素又带一次，虽然因为
+同族类后生效而不会出错，但会产生冗余类名。**能去掉一层就去掉。**
+
+**③ 原生 `<button>` 忘写 `className`。** 见第 1 节的例外条款 —— 结构性控件也必须
+有样式来源。
+
+---
+
+## 6. 提交前检查清单
+
+- [ ] 新增的可点元素来自 `Button`，不是裸 `<button>`
+- [ ] 同一界面里 `default` 变体不超过一个
+- [ ] 危险操作走 `destructive`，不是红色硬编码
+- [ ] 弹窗按钮没有重复包 `Button`
+- [ ] JSX 里没有 `#` 开头的颜色、没有 Tailwind 调色板名
+- [ ] `components/ui/` 里新导出的可点 primitive 已经挂上 `buttonVariants`
+- [ ] 组件测试覆盖到按钮的可见性与点击行为（testid 用 `xxx-yyy` 连字符命名）
+
+---
+
+## 7. 一个反面案例的复盘
+
+弹窗里的「取消 / 开始索引」显示成浏览器默认样式，原因就是第 5 节第 ① 条：
+`alert-dialog.tsx` 把 `Cancel` / `Action` 两个 primitive 原样导出了。
+
+修复是给它们各加一个 `forwardRef` 封装，挂上 `buttonVariants`。**组件本身没坏**，
+所有调用方一行不用改，样式自动生效 —— 这正是把样式收在 `components/ui/` 里的价值：
+**修一处，全产品对齐。**
+
+如果你发现某个地方的按钮"没跟上主题"，先别去改那个界面 ——
+**先看它用的组件是不是漏了样式。**
@@ -0,0 +1,92 @@
+# 微信系统消息（sysmsg）解析与格式兼容
+
+微信的「系统消息」（入群、撤回、成员变动等）以 XML（`<sysmsg>`）存放在消息内容里，
+但**同一类提示的 XML 结构会随客户端版本变化**。本文说明 TraceMemo 的解析方式，
+以及在遇到新格式时应当怎么扩展。
+
+## 两类格式
+
+### 旧格式：正文直接放在 `<plain>`
+
+```xml
+<sysmsg type="delchatroommember">
+  <delchatroommember>
+    <plain><![CDATA["成员昵称"通过扫描你分享的二维码加入群聊]]></plain>
+    <text><![CDATA["成员昵称"通过扫描你分享的二维码加入群聊]]></text>
+    <link>
+      <scene>qrcode</scene>
+      <text><![CDATA[撤销]]></text>
+    </link>
+  </delchatroommember>
+</sysmsg>
+```
+
+解析：命中 `delchatroommember`，直接取 `<plain>`。
+
+### 新格式：正文在 `<template>`，用 `$名称$` 引用 link
+
+```xml
+<sysmsg type="sysmsgtemplate">
+  <sysmsgtemplate>
+    <content_template type="tmpl_type_profilewithrevokeqrcode">
+      <plain><![CDATA[]]></plain>
+      <template><![CDATA["$adder$"通过扫描你分享的二维码加入群聊  $revoke$]]></template>
+      <link_list>
+        <link name="adder" type="link_profile">
+          <memberlist><member>
+            <username><![CDATA[wxid_xxxxxxxx]]></username>
+            <nickname><![CDATA[成员昵称]]></nickname>
+          </member></memberlist>
+        </link>
+        <link name="revoke" type="link_revoke_qrcode" hidden="1">
+          <title><![CDATA[撤销]]></title>
+        </link>
+      </link_list>
+    </content_template>
+  </sysmsgtemplate>
+</sysmsg>
+```
+
+三个要点：
+
+- `<plain>` 变成**空 CDATA**，正文挪进 `<template>`；
+- 正文里的 `$名称$` 是占位符，按 `<link_list>` 中 `link[name]` 回填；
+- `hidden="1"` 的 link 在微信里是**可点击按钮**，纯文本展示时应省略其文案。
+
+## 解析流程
+
+`src/main/message-parser.ts` 的 `parseSystemMessage()` 按以下顺序尝试：
+
+| 顺序 | 分支 | 处理对象 |
+| --- | --- | --- |
+| 1 | `extractRecallMessage` | `<revokemsg>` 撤回通知 |
+| 2 | `extractSysmsgTemplateText` | `<sysmsgtemplate>` 模板消息 |
+| 3 | `extractDelChatroomMemberText` | `<delchatroommember>` 成员变动 |
+| 4 | 通用提取（`plain` → `text` → `title`），再退回 `fallbackSystemText` | 其余未覆盖类型 |
+
+第 4 步之前会先调用 `stripSysmsgLinkList()` 剥掉 `<link_list>`。
+
+## 为什么必须显式处理新格式
+
+通用提取链只在第 1～3 步全部落空时才执行，而新格式恰好让它落空：
+`<plain>` 是空 CDATA，又没有 `<text>`，于是取到 `<title>` ——
+那是 `hidden="1"` 按钮的标题。**结果是整条系统消息只剩一个按钮文案**，
+例如把「某某通过扫描你分享的二维码加入群聊」显示成「撤销」。
+
+因此三处约束缺一不可：
+
+1. 模板分支必须排在通用提取之前；
+2. 占位符回填必须尊重 `hidden="1"`；
+3. 通用提取前先剥 `<link_list>`，作为未知类型的防护。
+
+## 新增一类系统消息时
+
+1. 从真实消息中取出 `content`（`<sysmsg>` 原文），确认 `type` 与承载正文的标签；
+2. 在 `parseSystemMessage()` 里加一个**早于通用提取**的分支；
+3. 补 `tests/unit/message-parser.test.ts` 用例，**新旧两版各一条**，防止回归；
+4. 文档与代码注释只写结构，不粘贴真实会话内容、昵称、wxid 或二维码链接。
+
+## 相关位置
+
+- 解析实现：`src/main/message-parser.ts`
+- 单元测试：`tests/unit/message-parser.test.ts`
@@ -1,5 +1,62 @@
-# macOS 数据访问说明（兼容入口）
+# macOS 关闭 SIP 教程

-完整内容已移到[macOS 数据访问与系统权限](./platform/macos.md)。
+SIP（System Integrity Protection，系统完整性保护）是 macOS 的系统安全机制。关闭 SIP 会降低系统安全性，只建议在确实需要读取或调试本地微信数据时临时关闭；操作完成后，建议重新开启。

-保留此文件是为了兼容应用内已经发布的帮助链接。请不要把“关闭 SIP”当作默认安装步骤；只有当当前连接页面明确要求时才处理，并在完成后恢复系统安全设置。
+> 只在连接页面明确提示需要关闭 SIP 时才处理。首次连接失败时，先确认微信版本、账号目录和登录时机，再按本文操作。关闭 SIP 不是 TraceMemo 的常规安装步骤，也不应长期保持关闭。
+
+## 准备
+
+- 一台 Mac 电脑，Intel 芯片和 Apple Silicon 芯片均可。
+- 需要进入 macOS 恢复模式。
+- 请先保存正在编辑的文件，并预留一次重启时间。
+
+## 关闭 SIP
+
+### Intel Mac
+
+1. 关机。
+2. 按下开机键后，立刻按住 `Command + R`。
+3. 保持按住，直到进入 macOS 恢复模式。
+
+### Apple Silicon Mac（M1/M2/M3/M4/M5）
+
+1. 关机。
+2. 长按开机键不放。
+3. 直到出现启动选项界面后松开。
+4. 选择"选项"，进入 macOS 恢复模式。
+
+### 在恢复模式中执行命令
+
+1. 进入恢复模式后，点击顶部菜单栏的 **Utilities（实用工具）**。
+2. 选择 **Terminal（终端）**。
+3. 在终端中输入：
+
+```bash
+csrutil disable
+```
+
+4. 按回车执行。
+5. 看到关闭成功提示后，重启电脑。
+
+## 确认是否生效
+
+重启回到正常桌面后，打开"终端"，执行：
+
+```bash
+csrutil status
+```
+
+看到 `System Integrity Protection status: disabled.` 才算关闭成功。
+
+若仍显示 `enabled`，说明没有生效。常见原因是没在恢复模式里执行，或系统刚做过大版本更新——
+macOS 大版本更新会把 SIP 重置回开启状态，此前关过也会失效，需要重新按上面的步骤操作。
+
+## 重新开启 SIP
+
+拿到数据库密钥后，建议重新进入恢复模式，在终端中执行：
+
+```bash
+csrutil enable
+```
+
+然后重启电脑，恢复系统安全设置。
@@ -8,7 +8,7 @@ TraceMemo 需要读取微信本地数据。macOS 会根据系统版本、微信

 1. 先启动 TraceMemo，阅读连接页面显示的当前前置条件。
 2. 确认微信数据目录指向当前账号。
-3. 只在页面明确要求时处理系统授权或 SIP；按页面提示完成密钥获取后，恢复你平时使用的安全设置。
+3. 只在页面明确要求时处理系统授权或 SIP；关闭 SIP 的具体步骤见[关闭 SIP 教程](../mac-disable-sip.md)，按页面提示完成密钥获取后，恢复你平时使用的安全设置。
 4. 返回应用重新检测账号、数据库和图片资源状态。

 不要直接复制网上针对其他微信版本的命令。系统授权失败时，记录 macOS 版本、微信版本和页面错误，再按[排障文档](../user-guide/troubleshooting.md#连接微信失败)处理。
@@ -23,5 +23,16 @@ TraceMemo 需要读取微信本地数据。macOS 会根据系统版本、微信

 ## Intel 与 Apple Silicon

-从 Releases 选择与 Mac 处理器匹配的构建。不同架构、微信版本和系统授权状态可能导致连接结果不同；文档不对所有组合做兼容性保证。
+TraceMemo 同时支持两种 Mac 架构：

+- **Apple Silicon（M 系列、`arm64`）**
+- **Intel Mac（`x64`）**
+
+从 Releases 下载与你 Mac 处理器匹配的构建：
+
+- Apple Silicon：`tracememo-<版本号>-arm64.dmg`
+- Intel：`tracememo-<版本号>-x64.dmg`
+
+两种架构都可以通过应用内的连接流程自动获取微信数据库密钥。首次连接时，TraceMemo 会根据当前机器架构进入对应的流程，按连接页面提示操作即可。
+
+Apple Silicon 和 Intel 已适配微信 macOS `4.1.13`。不同架构、微信版本和系统授权状态可能导致连接结果不同；文档不对所有组合做兼容性保证。
@@ -1,6 +1,6 @@
 ---
 name: tracememo-reader
-description: 通过 TraceMemo 本地 HTTP API 按需读取用户有权访问的微信聊天数据。当用户要求查看微信消息、查找联系人或群聊、总结聊天、生成群聊总结时使用。此 Skill 由本机 TraceMemo 提供数据，不是 MCP Server。
+description: 通过 TraceMemo 本地 HTTP API 按需读取用户有权访问的微信聊天数据和图片媒体。当用户要求查看微信消息、查找联系人或群聊、总结聊天、查看或理解图片、生成群聊总结时使用。此 Skill 由本机 TraceMemo 提供数据，不是 MCP Server。
 ---

 # TraceMemo Reader
@@ -27,20 +27,70 @@ description: 通过 TraceMemo 本地 HTTP API 按需读取用户有权访问的

 ## 端点速查

-| 方法 | 路径                  | 用途                                              |
-| ---- | --------------------- | ------------------------------------------------- |
-| GET  | `/health`             | 健康和数据库状态                                  |
-| GET  | `/current_time`       | 本机时间与时区                                    |
-| GET  | `/contact`            | 联系人/群聊列表；可传 `filter`、`type`            |
-| GET  | `/chatroom`           | 群聊列表；可传 `keyword`                          |
-| GET  | `/recent_chat`        | 最近会话；可传 `limit`                            |
-| GET  | `/chatlog`            | 会话消息；必填 `talker`，可传 `time` 或时间戳范围 |
-| GET  | `/group_snapshot`     | 群成员快照；必填 `md5`                            |
-| GET  | `/resolve`            | 昵称、wxid、md5 解析；必填 `q`                    |
-| POST | `/report`             | 将已有日报结构渲染为 HTML/PNG                     |
-| GET  | `/agent/status`       | Agent Hub、连接器和数据库状态                     |
-| POST | `/agent/group-report` | 按群和 `today`/`yesterday`/`7days` 生成总结图片   |
-| POST | `/agent/send`         | 已连接机器人发送测试                              |
+| 方法   | 路径                                | 用途                                              |
+| ------ | ----------------------------------- | ------------------------------------------------- |
+| GET    | `/health`                           | 健康和数据库状态                                  |
+| GET    | `/current_time`                     | 本机时间与时区                                    |
+| GET    | `/contact`                          | 联系人/群聊列表；可传 `filter`、`type`            |
+| GET    | `/chatroom`                         | 群聊列表；可传 `keyword`                          |
+| GET    | `/recent_chat`                      | 最近会话；可传 `limit`                            |
+| GET    | `/chatlog`                          | 会话消息；必填 `talker`，可传 `time` 或时间戳范围 |
+| GET    | `/media/{mediaId}`                  | 按消息返回的 `media.url` 获取图片二进制资源       |
+| GET    | `/group_snapshot`                   | 群成员快照；必填 `md5`                            |
+| GET    | `/resolve`                          | 昵称、wxid、md5 解析；必填 `q`                    |
+| GET    | `/wechat-personal/send-capability`  | 个人微信图片发送能力状态                          |
+| GET    | `/scheduled-reports`                | 查询全部定时日报任务                              |
+| GET    | `/scheduled-reports/:id`            | 查询单个定时日报任务                              |
+| POST   | `/scheduled-reports`                | 创建定时日报任务                                  |
+| PATCH  | `/scheduled-reports/:id`            | 修改定时日报任务                                  |
+| DELETE | `/scheduled-reports/:id`            | 删除定时日报任务（执行前必须获得用户确认）        |
+| POST   | `/scheduled-reports/:id/enable`     | 启用定时日报任务                                  |
+| POST   | `/scheduled-reports/:id/disable`    | 暂停定时日报任务                                  |
+| POST   | `/scheduled-reports/:id/run`        | 立即执行一次并返回 execution                      |
+| GET    | `/scheduled-reports/:id/executions` | 查询执行记录                                      |
+| POST   | `/report`                           | 将已有日报结构渲染为 HTML/PNG                     |
+| GET    | `/agent/status`                     | Agent Hub、连接器和数据库状态                     |
+| POST   | `/agent/group-report`               | 按群和 `today`/`yesterday`/`7days` 生成总结图片   |
+| POST   | `/agent/send`                       | 已连接机器人发送测试                              |
+
+## 定时日报管理
+
+定时日报由 TraceMemo 自己持久化和调度。Agent 只负责理解自然语言、解析群聊和时间，再调用上述 API；不要创建 cron、维护任务文件、计算下一次执行时间或自行发送微信。
+
+### 创建任务
+
+用户提出“每天早上 9 点给技术交流群发昨天的日报”时，按以下顺序执行：
+
+1. 调用 `/health`，确认 TraceMemo 和数据库可用。
+2. 调用 `/wechat-personal/send-capability`，只有 `capability.status === "ready"` 且 `capability.capabilities.image === true` 才允许继续。
+3. 用户使用“今天”“昨天”等相对日期时调用 `/current_time`；日报任务的 `schedule.time` 使用 TraceMemo 本机时区的 `HH:mm`，不要转成 UTC。
+4. 调用 `/chatroom` 或 `/contact?type=group` 查找群聊。名称匹配多个结果时，必须把候选项展示给用户并要求选择；不能猜测。
+5. 使用唯一群聊的 `talker` 创建：
+
+```json
+{
+  "name": "技术交流群 · 每日日报",
+  "group": { "talker": "xxx@chatroom", "name": "技术交流群" },
+  "schedule": { "type": "daily", "time": "09:00" },
+  "reportRange": "yesterday",
+  "target": { "type": "wechat_group", "talker": "xxx@chatroom" },
+  "enabled": true
+}
+```
+
+如果 API 返回 `409` 且 `error === "duplicate"`，告诉用户相同任务已经存在，不要再次创建。能力状态为 `unsupported`、`unconfigured`、`needs_binding`、`needs_verification` 或 `error` 时，直接说明需要先在 TraceMemo 设置中完成个人微信绑定和消息能力检测。
+
+### 查看、修改和执行
+
+- “我现在有哪些定时日报”调用 `GET /scheduled-reports`，使用返回的 `tasks` 展示任务名称、群聊、每天的时间、范围、目标和启停状态。
+- 修改前先查询列表并确认唯一任务，再调用 `PATCH /scheduled-reports/:id`。只提交需要修改的字段，例如 `{"schedule":{"type":"daily","time":"10:00"}}`。
+- 暂停调用 `/scheduled-reports/:id/disable`，恢复调用 `/scheduled-reports/:id/enable`。
+- “现在执行一次”调用 `/scheduled-reports/:id/run`，不要改用 `/agent/group-report` 后自行发送微信；该接口和定时执行共用同一条链路。
+- 查询执行结果调用 `/scheduled-reports/:id/executions`，根据 `status`、`startedAt`、`finishedAt`、`message` 和 `error` 向用户解释结果。
+
+### 删除确认
+
+删除是不可逆操作。收到删除请求后，先用任务列表找到唯一任务，向用户展示任务名称、时间、日报范围和发送目标并明确询问确认；只有用户明确确认后，才调用 `DELETE /scheduled-reports/:id`。

 ## 时间与上下文规则

@@ -52,6 +102,29 @@ description: 通过 TraceMemo 本地 HTTP API 按需读取用户有权访问的
 - 根据多条消息整理出的总结；
 - 没有来源支持的推断。

+## 媒体消息
+
+当 `/chatlog` 返回图片消息时：
+
+1. 如果用户只是询问图片消息是否存在，不需要获取图片。
+2. 如果用户要求查看、识别、理解或分析图片，原样使用该消息 `media.url` 获取真实图片；不要用消息 `id` 自行拼接。媒体标识按数据库连接隔离，重启、重连或切换账号后须重新读取 `/chatlog` 获取地址。
+3. 不要根据 `[图片]`、消息文本或文件名猜测图片内容。
+4. 获取成功后，将图片交给当前 Agent 的视觉能力。
+5. 如果图片获取失败，明确说明无法读取图片。
+6. 不要声称看到了没有成功获取的图片。
+7. 不要向用户暴露 Token、本地文件路径或数据库路径。
+
+### 图片分析
+
+用户：“看看张三昨天发的那张截图。”
+
+1. 调用 `/health`；必要时调用 `/current_time`。
+2. 调用 `/resolve`，再调用 `/chatlog` 找到 `type` 为图片的消息。
+3. 请求该消息的 `media.url`，将返回的图片交给 Vision。
+4. 必要时读取图片消息前后若干条消息，结合聊天上下文回答。
+
+不要只根据 `[图片]` 猜测内容，不要把一次 OCR 当作完整图片理解，也不要直接读取任意本地图片路径。
+
 ## 隐私和安全

 只读取用户请求所需的会话和时间范围。不要把完整聊天数据库、密钥或 Token 暴露给用户。Reader API 本身不自动把聊天转发到外部服务器，但当前 Agent 可能会把工具结果交给其配置的模型；如有疑问，提醒用户检查 Agent 的数据策略。
@@ -60,6 +133,7 @@ description: 通过 TraceMemo 本地 HTTP API 按需读取用户有权访问的

 - `401`：Token 缺失、错误或被轮换；请用户回 API Center 复制最新 Token。
 - `403`：浏览器 Origin 不在 loopback 允许列表；CLI/Agent 通常不带 Origin。
- `404`：先用 `/resolve` 确认会话标识。
+- `404`：会话查询失败时先用 `/resolve` 确认会话标识；媒体请求表示标识未登记、已过期、有歧义，或图片文件不存在（`NOT_FOUND`）。先重新读取 `/chatlog` 并使用新的 `media.url`；若仍失败，再检查本地图片文件是否存在。
+- `422`：媒体标识格式错误，或消息不是可读取的图片（`NOT_IMAGE`）。
 - `503`：用户还没有完成数据库连接或对应服务未就绪。
 - 空结果：缩小/扩大时间范围，确认账号和会话，再检查媒体或语音是否可读。
@@ -0,0 +1,674 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2026 yincongcyincong
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
+
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Use with the GNU Affero General Public License.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+    <program>  Copyright (C) <year>  <name of author>
+    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+<https://www.gnu.org/licenses/>.
+
+  The GNU General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.  But first, please read
+<https://www.gnu.org/licenses/why-not-lgpl.html>.
@@ -0,0 +1,28 @@
+# wechat_chatter / OneBot 第三方组件说明
+
+TraceMemo 的 macOS 个人微信发送功能会按需使用以下第三方组件：
+
+- 项目：`yincongcyincong/wechat_chatter`
+- 上游仓库：https://github.com/yincongcyincong/wechat_chatter
+- 当前运行时版本：`v0.0.18`
+- 运行时文件：`onebot_mac_arm64.tar.gz`
+- 许可证：GNU General Public License version 3（GPL-3.0）
+- 上游版权：Copyright (C) 2026 yincongcyincong
+- TraceMemo 修改日期：2026-08-17
+
+## 集成方式
+
+OneBot 运行时不会随 TraceMemo 安装包一起分发。用户启用该实验性功能时，TraceMemo 会从上述上游项目的 GitHub Release 按需下载运行时，并将其安装到应用的用户数据目录。
+
+运行时作为独立进程启动，TraceMemo 通过本机 HTTP 接口与其通信。
+
+## 本地修改
+
+为适配连续发送、图片上传 Hook 状态检测以及微信核心模块基址定位，TraceMemo 会在用户设备上对上游 `onebot/script.js` 应用兼容性补丁。补丁逻辑位于：
+
+- `scripts/prepare-wechat-chatter-runtime.cjs`
+- `src/main/services/personal-wechat-runtime-manager.ts`
+
+补丁中源自或修改自上游 `script.js` 的部分，以及补丁应用后产生的修改版 `script.js`，继续按照 GPL-3.0 提供。本说明只针对该第三方组件及相关修改，不用于声明 TraceMemo 仓库其他部分的许可证。
+
+GPL-3.0 的完整文本见本目录下的 `LICENSE`。
@@ -41,6 +41,19 @@

 你可以点击来源回到档案中的原始消息。产品内部将这些信息称为 Evidence、Citation 和 Search Trace，用户可以把它们理解为“依据、来源标记和查找过程”。详见[如何核对 AI 的回答来源](../concepts/answer-sources.md)。

+## 查找过程和跳回原消息
+
+查找过程中，界面依次显示真实阶段：**理解问题 → 查找相关聊天 → 整理证据 → 生成回答**。跨会话、大范围检索更慢时，副提示会写明“正在搜索较大范围的聊天记录…”。阶段只在真正进入下一步时前进，不使用定时器或百分比伪造进度。
+
+查找结束后，界面给出耗时拆解：**总耗时**，以及其中分别花在 **AI 生成** 和 **本地查询** 上的时间。这样你能判断慢在哪——是模型在写答案，还是本机还在翻聊天记录。
+
+点击来源卡片的 **“跳转到原聊天”** 会真的打开对应会话并定位到那条消息：
+
+- 群聊来源打开的是那个群，而不是群里某个联系人；
+- 会加载该消息前后的上下文，并滚动到它、短暂高亮；
+- 只加载目标消息附近的一段，不会把整个会话历史全部读出来；
+- 如果这条消息已经不在本地（例如已被删除），界面会明确说明“已打开对应会话，但暂时无法定位原消息”，不会假装跳转成功。
+
 ## 什么时候不要直接相信答案

 - 来源很少，或时间范围与问题不一致；
@@ -4,7 +4,7 @@

 ## 选择要看的会话

-左侧会话列表可以浏览联系人、群聊、折叠群聊和公众号等已读取到的会话。选中会话后，右侧显示消息时间线；滚动到较早位置可以继续加载历史。
+左侧会话列表可以浏览已读取到的联系人、群聊和公众号。选中会话后，右侧显示消息时间线；滚动到较早位置可以继续加载历史。

 如果你从 AI 回答的来源进入档案，应用会自动切换到对应会话并尽量定位到消息时间。

@@ -19,6 +19,22 @@

 关键词搜索速度快、结果直观，但它不会理解“意思相近但没有相同词”的问题。

+## 怎么找到联系人
+
+档案搜索会综合多个身份字段匹配联系人或群聊，包括：
+
+- 通讯录备注（remark）；
+- 微信昵称；
+- 当前微信号；
+- wxid；
+- 拼音全拼和拼音首字母。
+
+因此可以直接输入备注、昵称、微信号或拼音查找。搜索联系人和搜索消息是两步：先确认目标会话，再在会话内查关键词；记得大意但不知道原话时，改用[AI Search](./ai-search.md)。
+
+## 文字转语音
+
+在档案中选择当前联系人或群聊，输入文字后生成语音，试听确认后发送。这个入口只处理明确的文字转语音动作，不是任意文本、图片或本地语音文件发送器。
+
 ## 消息和媒体

 根据微信数据中实际可用的资源，档案可以展示文本、图片、视频、语音、文件、链接、引用、小程序、表情和系统消息等类型。媒体是否能显示，取决于本机原始资源是否仍然存在、权限是否完整以及当前微信版本的存储方式。
@@ -27,11 +43,7 @@

 如果文字正常但图片无法打开，进入“设置 → 图片解密”查看当前状态。可以尝试自动获取，也可以在已经知道正确密钥时手动配置；原文件已经被微信清理时，仅配置密钥也无法恢复图片。

-## 可选保留撤回消息
-
-“设置 → 防撤回”提供一个默认关闭的可选功能。开启后，应用会尽量保留之后捕获到的撤回消息，并在气泡旁标记“消息已撤回”。它不能找回开启前已经消失或应用未捕获到的内容，也可能增加加载开销。
-
-该功能与普通只读浏览的数据边界不同。开启前请阅读[防撤回](./recall-protection.md)。
+联系人和群聊列表会尽量显示头像、备注和昵称。头像或资料缺失时不影响消息读取；这通常表示本机没有对应资源，或微信没有返回完整资料。

 ## 保护自己不被误导

@@ -8,12 +8,29 @@

 ## 1. 开始前准备

-| 系统    | 已测试的微信客户端                                                                                | 需要注意                                                                       |
-| ------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
-| macOS   | [微信 macOS `4.1.8.100`](https://github.com/zsbai/wechat-versions/releases/tag/4.1.8.100)         | 自动获取数据库密钥前，需要按连接页面提示完成授权；页面明确要求时还需要处理 SIP |
-| Windows | [微信 Windows `4.1.9.57`](https://github.com/iibob/wechat-win-archive/releases#release-v4.1.9.57) | 首次使用时请确认微信数据目录；Windows 不需要关闭 SIP                           |
+TraceMemo 需要读取微信本地数据库。首次使用前，请确认已安装受支持的微信客户端，并按照连接页面完成数据库密钥获取。

- 上表是当前实际测试过的客户端版本，不代表只有这些版本可以使用。其他微信 4.x 版本可能可以连接，但尚未逐一验证。
+| 系统    | 微信客户端                                                                                                                                                                                   | 首次连接说明                                                                                                                   |
+| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| macOS   | **微信 4.1.13 系列**（推荐 [4.1.13.8](https://github.com/zsbai/wechat-versions/releases/tag/4.1.13.8)）<br>备选 [4.1.8.100](https://github.com/zsbai/wechat-versions/releases/tag/4.1.8.100) | 支持 Apple Silicon（M 系列）和 Intel Mac 自动获取数据库密钥。首次连接时，请按照 TraceMemo 页面提示完成系统授权及微信登录操作。 |
+| Windows | **微信 4.x**（推荐 [4.1.9.57](https://github.com/iibob/wechat-win-archive/releases/tag/v4.1.9.57)）                                                                                          | 支持自动获取数据库密钥。首次使用时请确认微信数据目录正确，无需处理 macOS 的 SIP 设置。                                         |
+
+### macOS 用户
+
+TraceMemo 已支持两种 Mac 架构：
+
+- **Apple Silicon（M1 / M2 / M3 / M4 等）**
+- **Intel Mac（x64）**
+
+两种架构均支持自动获取微信数据库密钥，TraceMemo 会根据当前 Mac 自动选择对应的连接方式。
+
+Apple Silicon 和 Intel 均已适配微信 macOS `4.1.13` 系列。首次获取密钥时，请让微信停留在登录页面，并按照 TraceMemo 中显示的步骤操作。
+
+> 不同 Mac 架构的连接流程可能略有区别，请始终以应用内「第一次使用」页面显示的提示为准。
+
+### 关于微信版本
+
+- 上表中的版本是当前 TraceMemo 已适配或推荐使用的版本，并不代表只有这些版本可以运行。
 - TraceMemo 必须取得当前微信账号对应的数据库密钥，才能读取聊天记录。
 - 你需要有权访问要读取的微信账号和聊天数据。
 - 如果要使用 AI 问答、群聊日报或图片理解，还需要在应用中配置一个 AI 服务。
@@ -22,18 +39,20 @@

 ## 2. 安装并启动

-安装包统一从 [GitHub Releases](https://github.com/Wxw-Gu/WechatExplorer/releases) 下载。
+安装包统一从 [GitHub Releases](https://github.com/Wxw-Gu/TraceMemo/releases) 下载。

 ### Windows

-1. 从 Releases 下载 Windows x64 的 `TraceMemo-<版本号>-setup.exe` 安装包。
+1. 从 Releases 下载 Windows x64 的 `tracememo-<版本号>-setup.exe` 安装包。
 2. 双击安装包，按向导完成安装。
 3. 启动 TraceMemo。
 4. 如果安装完成后软件无法启动，请安装 Microsoft Visual C++ x64 运行库：[vc_redist.x64.exe](https://aka.ms/vc14/vc_redist.x64.exe)，安装完成后重新启动 TraceMemo。

 ### macOS

-1. 下载 Apple Silicon（M 系列、`arm64`）版本的 `.dmg`。当前版本不支持 Intel 芯片的 Mac。
+1. 从 Releases 下载与你 Mac 处理器架构匹配的 `.dmg`：
+   - Apple Silicon（M 系列、`arm64`）：`tracememo-<版本号>-arm64.dmg`
+   - Intel（`x64`）：`tracememo-<版本号>-x64.dmg`
 2. 打开 DMG，将 TraceMemo 拖入“应用程序”文件夹。
 3. 如果系统提示“无法打开，因为开发者无法验证”，前往“系统设置 → 隐私与安全性”，点击“仍要打开”。
 4. 如果系统提示应用已损坏，可在终端执行：
@@ -42,7 +61,16 @@
   xattr -cr "/Applications/TraceMemo.app"
   ```

-5. 启动 TraceMemo。首次自动获取数据库密钥时，按连接页面显示的授权要求操作；只有页面明确提示时才按[关闭 SIP 教程](../mac-disable-sip.md)处理。关闭 SIP 会降低系统安全性，完成密钥配置后应重新开启。
+5. 先让微信停在**未登录窗口**（如果微信已经登录，请退出当前账号，**只关闭窗口不算**），再启动 TraceMemo。
+   - 连接时会按提示自动获取数据库密钥；应用会根据当前架构进入对应流程，按连接页面显示的授权要求操作即可。
+   - **等第五步 明确提示可以登录后，再回到微信点击登录。** 在此之前不要先点登录，否则这次密钥获取会失败，需要重新开始。
+   - 只有页面明确提示时才按[关闭 SIP 教程](../mac-disable-sip.md)处理。关闭 SIP 会降低系统安全性，完成密钥配置后应重新开启。
+
+> **注意事项：取密钥时提示监听超时（`CAPTURE_TIMEOUT`，或相关失败）**
+>
+> 这说明「先让微信停在未登录窗口」这一步操作有误——常见原因是微信当时已经登录，或者还没等连接页面提示就先点了登录
+>
+> 请先退出微信账号、回到**未登录窗口**，然后按上面的第 5 步**重新来一遍**（等连接页面明确提示可以登录后，再回到微信点击登录）。

 更完整的权限和安全边界见 [macOS 数据访问说明](../platform/macos.md)。

@@ -106,7 +134,6 @@
 - [生成群聊日报或总结](./report.md)
 - [转写微信语音](./voice.md)
 - [导出聊天档案](./export.md)
- [可选开启防撤回](./recall-protection.md)
 - [在微信里向 TraceMemo 提问](../agent/agent-hub.md)
 - [让外部 Agent 查询微信历史](../agent/overview.md)

@@ -142,7 +169,6 @@ Agent Hub 是普通用户可以直接使用的入口，不需要安装 Reader Sk
 - 离线语音转写使用本地模型；它与在线 AI 请求是两条不同的数据路径。
 - 你主动开始并确认 AI 问答或日报后，完成任务所需的受控上下文才可能发送给你选择的 AI 服务；打开应用不会自动上传全部聊天。
 - 应用内 Local HTTP API 默认只监听 `127.0.0.1:6131`，受保护接口需要 Token。
- 防撤回默认关闭；首次开启会为微信消息数据库增加本地撤回日志/监听结构，详细边界见[防撤回](./recall-protection.md)。

 完整边界见[数据、隐私与安全](./privacy.md)。

@@ -0,0 +1,19 @@
+# Intel Mac 首次获取密钥
+
+请先备份微信本地数据。密钥获取和数据库验证都在本机完成，不要把密钥、日志或数据库发给他人。
+
+## 开始使用
+
+1. 启动 TraceMemo，在首次连接页面点击“重新检查环境”。
+2. 如果页面显示需要准备连接环境，点击“准备环境”，按页面提示完成。
+3. 打开微信，让微信停在未登录页面，不要先点击登录。
+4. 回到 TraceMemo，选择微信账号，点击“开始获取密钥”。
+5. 等待页面提示可以登录后，立即回到微信点击登录。
+6. 等待 TraceMemo 显示“获取成功，验证数据库连接”。
+
+获取成功后，请保存密钥。如果页面提示需要重新准备，按页面的“查看说明”操作，不要连续重试。
+
+## 注意
+
+- 密钥只保存在本机的安全存储中。
+- 请不要删除微信本地数据目录。
@@ -13,7 +13,30 @@ Knowledge 不会在第一次连接后自动悄悄建立。进入“问问微信
 - **建立本地知识库**：第一次读取当前账号的可检索聊天；
 - **同步最新记录**：已有索引时，只补充新增或变化的内容。

-同步会在后台运行，完成后页面显示已索引消息、知识片段和磁盘占用。同步期间暂不能开始新的 AI 分析；同步异常时，旧索引仍可能可以继续使用。
+同步在后台运行，**期间仍然可以正常提问和分析**，不会被禁用。索引还没追完时，答案会基于当前已经可用的部分给出，并在界面标注覆盖范围。
+
+知识库卡片同时显示两组互相独立的信息：
+
+- **规模**：已索引消息、知识片段、磁盘占用——说明索引有多大；
+- **状态与本轮进度**：说明索引现在处于什么状态、这一轮同步在做什么（扫了多少、真正新增了多少、处理到第几个会话）。
+
+`最新索引` 只表示索引已经覆盖到聊天记录的哪个时间点，**不等于**整库已经建完；进度里的计数是**本轮**的数字，不是全部历史的总数。
+
+### 状态怎么读
+
+| 状态 | 含义 |
+| ---- | ---- |
+| 可用 · 已追至最新 | 索引已覆盖到聊天记录的最新位置，可以直接用 |
+| 可用 · 正在追新 | 索引可用，正在后台补充最近新增的消息 |
+| 可用 · 正在补齐历史 | 索引可用，正在后台补齐较早的历史内容 |
+| 可用 · 同步已取消 | 索引仍然可用；上一轮同步被取消，已建立的部分保留 |
+| 可用 · 更新失败 | 索引仍然可用；上一轮同步出错，可以稍后重试 |
+
+只有确实追平、且没有待补齐内容时才会出现“已追至最新”。索引不可查询时不会显示“可用”。
+
+### 取消和继续
+
+同步过程中可以点击 **取消同步**（点击后显示“正在取消…”）。取消只结束当前这一轮，不会删除已经建立的索引，也不会回滚已完成的部分；下次同步会从上次停下的位置继续，不需要从头重扫。中断过的索引仍然可以正常搜索。

 ## 账号隔离

@@ -14,8 +14,6 @@ TraceMemo 的核心路径是本地优先，但“本地优先”不等于所有

 应用不会因为你打开 TraceMemo 就自动把整份微信数据库上传。

-防撤回默认关闭，并且和上面的普通读取路径不同。用户第一次明确开启时，当前实现会在微信消息数据库中安装本地撤回日志/监听结构，同时在 TraceMemo 用户数据目录保存必要的恢复记录。v2.1.9 的旧恢复记录会随首次启动迁移复制到 TraceMemo，旧目录仍保留。关闭开关不等于移除已经安装的结构或清空既有记录；当前 UI 没有对应的清理入口。详见[防撤回](./recall-protection.md)。
-
 ## 什么时候会请求外部服务

 当你主动使用 AI Search、群聊日报或图片理解，并配置了远程 Provider 时，完成任务所需的内容可能发送给该 Provider。当前设置页给出的边界是：
@@ -58,4 +56,3 @@ Token 由应用生成，使用 Electron `safeStorage` 加密保存在本机 `loc
 - 对需要外发的 AI 功能逐项确认 Provider；
 - 定期在“设置 → 缓存与清理”清理不再需要的检索、导出和索引缓存；
 - 在共享电脑上退出应用并保护系统账户。
- 在开启防撤回前确认你接受其数据库写入、性能和清理边界，并先用微信官方方式备份重要数据。
@@ -1,37 +0,0 @@
-# 防撤回
-
-防撤回是一个默认关闭的可选功能。开启后，TraceMemo 会尽量保留它能够捕获到的撤回消息，并在聊天气泡旁标记“消息已撤回”。
-
-它适合希望在本机档案中保留后续聊天上下文的用户，但不能保证找回每一条撤回消息。
-
-## 如何开启
-
-1. 先连接微信数据库，并确认“档案”可以正常读取聊天。
-2. 打开“设置 → 防撤回”。
-3. 阅读性能和数据提示后，开启“防撤回”。
-4. 保持 TraceMemo 与当前微信数据连接；之后捕获到的撤回消息会尽量保留并标记。
-
-防撤回不是第一次使用的必要步骤。只想浏览、搜索、提问或导出时，可以保持关闭。
-
-## 当前能做什么
-
- 监听应用能够识别到的后续撤回变化；
- 在本地保留必要的消息和撤回关系；
- 将已识别的原消息与撤回状态一起显示在档案中；
- 按微信账号隔离 TraceMemo 保存的恢复记录。
-
-## 当前限制
-
- 不能恢复开启前已经撤回、且应用从未保存到的消息；
- TraceMemo 未运行、数据库未连接或没有捕获到撤回变化时，消息可能无法保留；
- 微信版本、消息表结构和数据库事件变化都可能让部分消息无法恢复或正确匹配；
- 开启后需要为消息表增加监听，聊天很多或磁盘较慢时可能影响加载性能；
- “消息已撤回”只说明应用识别到了撤回关系，不保证恢复内容完整。
-
-## 数据写入与关闭边界
-
-普通浏览、搜索和 Knowledge 不会修改微信原始聊天数据库；防撤回是一个例外。用户第一次明确开启时，当前实现会在微信消息数据库中安装用于记录撤回的本地日志/监听结构，并在 TraceMemo 的用户数据目录保存必要的本地恢复记录。v2.1.9 的旧恢复记录会在用户确认迁移后复制到 TraceMemo，旧目录不会删除。
-
-关闭设置中的开关，不等同于删除已经安装的日志结构或清空此前保存的恢复记录。当前版本没有在 UI 中提供“移除防撤回日志结构”或“清空防撤回记录”的独立操作。对数据库写入、磁盘占用或完全回滚有要求时，应在开启前先确认这一边界，并使用微信官方方式备份重要数据。
-
-完整的数据边界见[数据、隐私与安全](./privacy.md)。
@@ -6,8 +6,8 @@

 典型场景包括：

- 整理今天工作群的讨论重点；
- 回顾昨天错过的决定和资源；
+- 整理今日工作群的讨论重点；
+- 回顾昨日错过的决定和资源；
 - 汇总近 7 天的项目进展、待办和未解决问题；
 - 把群里的图片、语音统计和重要消息放进一张长图或 HTML 页面。

@@ -16,7 +16,7 @@
 你可以从两个入口开始：打开一级导航“日报”后新建报告，或者在“档案”中选中一个群聊并点击“生成 AI 日报”。

 1. 选择一个群聊。当前日报入口只支持群聊，不支持单聊。
-2. 选择时间范围：今天、昨天或近 7 天。
+2. 选择时间范围：今日、昨日或近 7 天。
 3. 按需要选择参与总结的消息类型，先从文字开始最容易核对。
 4. 选择报告模板/内容模式并开始生成。
 5. 等待“整理输入 → AI 生成 → HTML/PNG 导出”完成。
@@ -33,10 +33,22 @@

 生成成功后会保存本地 HTML 与 PNG，并出现在日报历史中。你可以复制图片、打开文件位置或重新生成。删除历史日报只删除本地生成的报告文件，不会影响微信聊天数据库。

+## 定时日报
+
+在“日报 → 定时日报”中可以创建每天运行的任务。选择群聊、执行时间、日报范围、消息类型和模板后，TraceMemo 会按计划执行：
+
+```text
+定时触发 → 读取群聊 → 生成报告 → 保存 Report History → 尝试发送
+```
+
+生成和发送是两个阶段。当前微信发送能力不可用、未绑定或发送失败时，报告仍会保存，PNG 和执行记录也会保留；这类结果会显示为“已生成，但未发送”或“已生成，发送失败”。
+
+执行记录支持查看已生成的日报。对“等待发送”或“发送失败”的记录，可以直接重试发送，重试会复用已经生成的 PNG，不会重新调用 AI 生成整份报告；完整执行状态和发送边界见[如何把聊天变成可用的信息](../concepts/how-it-works.md#动作执行与审计)。
+
 ## 让报告更可靠

 - 先选正确的群和时间范围；
 - 不确定时先只选择文字消息；
- 群太活跃时分成“今天”和“近 7 天”两次生成；
+- 群太活跃时分成“今日”和“近 7 天”两次生成；
 - 看到待办和结论后回到原消息核对上下文；
 - AI Provider 不可用时先检查模型配置和网络/本地服务状态。
@@ -12,6 +12,7 @@

 ### macOS

+- 确认下载的构建与 Mac 处理器匹配：Apple Silicon（M 系列）用 `arm64`，Intel 用 `x64`。
 - 提示“无法打开，因为开发者无法验证”时，前往“系统设置 → 隐私与安全性”并点击“仍要打开”。
 - 提示应用已损坏时，确认应用位于“应用程序”目录，再执行 `xattr -cr "/Applications/TraceMemo.app"`。

@@ -25,10 +26,13 @@
 2. 微信版本是否属于当前代码面向的 4.x 数据结构；
 3. 微信是否处于页面要求的登录/退出状态；
 4. macOS 是否完成页面要求的授权；
-5. 连接页面的诊断项是否明确指出密钥、账号或数据库问题。
+5. 连接页面的诊断项是否明确指出密钥、账号或数据库问题；
+6. macOS 上 Apple Silicon 与 Intel 使用不同的连接流程，按连接页面提示操作；两者都可以自动获取数据库密钥。

 重新输入密钥或断开连接不会删除微信原始数据库。macOS 的 SIP 和授权说明见[平台说明](../platform/macos.md)。

+仍然失败时，记录 **macOS 版本、CPU 架构（Apple Silicon / Intel）、微信版本、TraceMemo 版本和页面错误提示**后 扫码 README 文档二维码进群提交消息, 或者提交 Issue。
+
 ## 连接成功但没有联系人或消息

 确认账号身份和数据目录匹配。返回“设置 → 账号与数据库”查看数据库连接状态，重新加载会话后再试。若仍为空，记录系统、微信版本和错误提示后提交 Issue。
@@ -88,7 +92,3 @@ Agent Hub 和外部 Agent 是两条路径。机器人异常时依次确认：
 5. 需要总结或自然语言理解时，AI Provider 是否可用。

 当前机器人不支持群发、定时任务或与文字同等的图片、语音、文件和视频理解。详细边界见[Agent Hub](../agent/agent-hub.md)。
-
-## 防撤回没有保留消息
-
-防撤回只能尽量保留开启后且应用成功捕获到的撤回变化。确认开启时数据库已经连接、TraceMemo 在撤回发生时保持运行，并检查聊天加载是否明显变慢。开启前已经消失、应用未捕获或微信结构无法识别的消息不能保证恢复；详见[防撤回](./recall-protection.md)。
@@ -0,0 +1,69 @@
+appId: com.tracememo.app
+productName: TraceMemo
+afterPack: scripts/after-pack.cjs
+directories:
+  buildResources: build
+files:
+  - out
+  - '!**/.vscode/*'
+  - '!src/*'
+  - '!electron.vite.config.{js,ts,mjs,cjs}'
+  - '!{.eslintcache,eslint.config.mjs,.prettierignore,.prettierrc.yaml,dev-app-update.yml,CHANGELOG.md,README.md}'
+  - '!{.env,.env.*,.npmrc,pnpm-lock.yaml}'
+  - '!{tsconfig.json,tsconfig.node.json,tsconfig.web.json}'
+extraMetadata:
+  main: out/main/index.js
+asarUnpack:
+  - resources/**
+  - node_modules/ffmpeg-static/**
+  - node_modules/silk-wasm/**
+  - node_modules/sherpa-onnx-node/**
+  - node_modules/sherpa-onnx-*/**
+  - node_modules/@napi-rs/system-ocr/**
+  - node_modules/@napi-rs/system-ocr-*/**
+extraResources:
+  # Keep the updater provider in every packaged Windows app. electron-builder also
+  # regenerates this file during publish, using the same release configuration.
+  - from: build/app-update.yml
+    to: app-update.yml
+  # Keep only resources required by the Windows x64 runtime.
+  - from: resources
+    to: resources
+    filter:
+      - icon.png
+      - daily_report_templates.html
+      - mobile_daily_report.html
+      - mobile_daily_report_v1.html
+      - mobile_daily_report_v2.html
+      - key/win32/x64/**
+      - runtime/win32/**
+      - wcdb/win32/x64/**
+  - from: docs/skill/tracememo-reader
+    to: skill/tracememo-reader
+    filter:
+      - '**/*'
+win:
+  icon: icon.ico
+  executableName: TraceMemo
+  target:
+    - target: nsis
+      arch:
+        - x64
+nsis:
+  oneClick: false
+  allowToChangeInstallationDirectory: true
+  artifactName: ${name}-${version}-setup.${ext}
+  shortcutName: ${productName}
+  uninstallDisplayName: ${productName}
+  createDesktopShortcut: always
+npmRebuild: false
+electronLanguages:
+  - zh-CN
+  - en-US
+publish:
+  provider: github
+  owner: Wxw-Gu
+  repo: TraceMemo
+  # 一律先上传为草稿 再到 GitHub 上手动 Publish。
+  # 需要预发布时用 `pnpm release:beta`（EP_PRE_RELEASE 会覆盖这里的 draft）。
+  releaseType: draft
@@ -19,22 +19,26 @@ asarUnpack:
  - node_modules/silk-wasm/**
  - node_modules/sherpa-onnx-node/**
  - node_modules/sherpa-onnx-*/**
+  # System OCR（@napi-rs/system-ocr）的 native binding 必须 unpacked，否则
+  # macOS 的系统 OCR 会在运行时 MODULE_NOT_FOUND。平台本机的 binding 由
+  # scripts/after-pack.cjs 校验，外架构的同级包在 afterPack 里被裁掉。
+  - node_modules/@napi-rs/system-ocr/**
+  - node_modules/@napi-rs/system-ocr-*/**
 extraResources:
+  # Keep the updater provider in every packaged macOS app. electron-builder also
+  # regenerates this file during publish, using the same release configuration.
+  - from: build/app-update.yml
+    to: app-update.yml
  # Includes the optional WeChat connector binary for the target platform.
  - from: resources
    to: resources
    filter:
      - '**/*'
+      - '!connectors/wechat-personal/**'
  - from: docs/skill/tracememo-reader
    to: skill/tracememo-reader
    filter:
      - '**/*'
-win:
-  icon: icon.ico
-  # WCDB's Windows runtime checks the host executable name. The dev runtime is
-  # electron.exe, so keep the packaged executable compatible while using
-  # TraceMemo as the product/shortcut name.
-  executableName: electron
 nsis:
  oneClick: false
  allowToChangeInstallationDirectory: true
@@ -44,11 +48,11 @@ nsis:
  createDesktopShortcut: always
 mac:
  icon: icon.icns
+  target:
+    - dmg
+    - zip
  entitlementsInherit: build/entitlements.mac.plist
  extendInfo:
-    # The bundled WCDB bridge still uses Electron as its internal executable
-    # compatibility name; the public product and bundle identity are TraceMemo.
-    CFBundleName: Electron
    CFBundleDisplayName: TraceMemo
    NSCameraUsageDescription: Application requests access to the device's camera.
    NSMicrophoneUsageDescription: Application requests access to the device's microphone.
@@ -71,5 +75,7 @@ npmRebuild: false
 publish:
  provider: github
  owner: Wxw-Gu
-  repo: WechatExplorer
-  releaseType: release
+  repo: TraceMemo
+  # 一律先上传为草稿 再到 GitHub 上手动 Publish。
+  # 需要预发布时用 `pnpm release:beta`（EP_PRE_RELEASE 会覆盖这里的 draft）。
+  releaseType: draft
@@ -8,13 +8,15 @@ export default defineConfig({
      rollupOptions: {
        input: {
          index: resolve('src/main/index.ts'),
+          reportTemplateTest: resolve('src/main/report-template-test-entry.ts'),
+          queryAgentPoc: resolve('src/main/query-agent-poc-entry.ts'),
          voiceRecognitionWorker: resolve('src/main/voice-pipeline/voice-recognition-worker.ts'),
          knowledgeWorker: resolve('src/main/knowledge/knowledge-worker.ts')
        },
        output: {
          entryFileNames: '[name].js'
        },
-        external: ['koffi', 'sherpa-onnx-node']
+        external: ['koffi', 'sherpa-onnx-node', '@napi-rs/system-ocr']
      }
    }
  },
@@ -24,6 +24,12 @@ export default defineConfig(
      'react-refresh': eslintPluginReactRefresh
    },
    rules: {
+      'prettier/prettier': [
+        'error',
+        {
+          endOfLine: 'auto'
+        }
+      ],
      ...eslintPluginReactHooks.configs.recommended.rules,
      ...eslintPluginReactRefresh.configs.vite.rules
    }
@@ -0,0 +1,9 @@
+# TraceMemo 日报模板示例
+
+此目录是可安装的最小日报模板源文件，使用全部虚构数据进行预览。运行 `node scripts/build-report-template-example.cjs` 会生成 `examples/report-template-basic.zip`。
+
+模板只能调整已有日报模块的 HTML/CSS 排版。作者不能加入 JavaScript、事件属性、外部网络资源、嵌套页面、数据库访问、AI Prompt 或新的业务分析。
+
+占位符分为三类：普通文本（会被 HTML 转义）、应用生成的 HTML 片段（只能作为元素内容使用）、受限样式类（只能放进 `class` 属性，并由应用输出合法 token）。`*_MORE_NOTE` 是 HTML 片段，不是样式类。
+
+允许的标签和属性由 `src/shared/report-template-package.ts` 统一定义；图片资源只能是包内 `assets/` 下的 PNG/JPEG/WebP。缺少可选模块时应用输出空字符串和 `*_EMPTY_CLASS`，模板应允许该模块隐藏。
@@ -0,0 +1,14 @@
+{
+  "protocolVersion": "1.0",
+  "kind": "daily-report",
+  "id": "community.github.example.basic-feed",
+  "name": "基础信息流",
+  "author": { "name": "example" },
+  "templateVersion": "1.0.0",
+  "interfaceVersion": "1",
+  "entry": "template.html",
+  "preview": "preview.png",
+  "capture": { "width": 430, "maxWidth": 430, "maxHeight": 20000 },
+  "license": { "spdx": "MIT" },
+  "platform": "mobile"
+}
@@ -0,0 +1,41 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1" />
+    <title>{{REPORT_TITLE}}</title>
+    <style>
+      * { box-sizing: border-box; }
+      html, body { margin: 0; width: 430px; background: #f3f5f7; color: #18202a; font-family: -apple-system, BlinkMacSystemFont, sans-serif; }
+      .report { padding: 18px 14px 32px; }
+      .hero, .section { margin-top: 10px; padding: 16px; border-radius: 14px; background: #fff; }
+      .hero { margin-top: 0; border-top: 4px solid #1769aa; }
+      h1 { margin: 0 0 8px; font-size: 23px; }
+      .meta, .muted { color: #64748b; font-size: 12px; line-height: 1.5; }
+      .section-title { margin: 0 0 8px; font-size: 14px; }
+      .topics-grid, .important-list { display: grid; gap: 8px; }
+      .topic-card, .important-card { padding: 10px; border: 1px solid #dbe4ee; border-radius: 10px; }
+      .empty-section { display: none !important; }
+    </style>
+  </head>
+  <body>
+    <main class="report {{REPORT_MODE_CLASS}}">
+      <section class="hero {{REPORT_MODE_CLASS}}">
+        <h1>{{REPORT_TITLE}}</h1>
+        <div class="meta">{{REPORT_DATE}} · {{DATE_RANGE}}</div>
+        <p>{{HERO_SUMMARY}}</p>
+        <div class="muted">{{HERO_STATUS_LINE}}</div>
+      </section>
+      <section class="section {{TOPICS_EMPTY_CLASS}}">
+        <h2 class="section-title">今日话题</h2>
+        <div class="topics-grid">{{TOPIC_CARDS}}</div>
+        {{TOPICS_MORE_NOTE}}
+      </section>
+      <section class="section {{MESSAGES_EMPTY_CLASS}}">
+        <h2 class="section-title">重要消息</h2>
+        <div class="important-list">{{IMPORTANT_MESSAGES}}</div>
+      </section>
+      <footer class="muted">{{FOOTER_NOTE}}</footer>
+    </main>
+  </body>
+</html>
@@ -1,8 +1,8 @@
 {
  "name": "tracememo",
-  "version": "2.2.2",
+  "version": "2.4.0",
  "packageManager": "pnpm@7.33.7",
-  "description": "TraceMemo（迹忆）是一款本地优先、可追溯的 AI 微信知识与分析工作台。 原名 WechatExplorer，支持聊天记录搜索、知识库、AI 总结和 Agent 助手。",
+  "description": "TraceMemo（迹忆）是一款本地优先、可追溯的 AI 微信知识与分析工作台。 原名 WechatExplorer，支持聊天记录搜索、知识库、微信群聊总结和 Agent 助手。",
  "keywords": [
    "wechat",
    "wechat chat",
@@ -11,6 +11,7 @@
    "windows微信",
    "微信聊天记录",
    "微信聊天记录搜索",
+    "微信群聊总结",
    "微信AI",
    "微信机器人",
    "AI聊天搜索",
@@ -24,19 +25,27 @@
  },
  "main": "./out/main/index.js",
  "scripts": {
-    "test": "pnpm typecheck && pnpm test:unit && pnpm test:component && pnpm test:integration && pnpm test:skill-install && pnpm test:wechat-connector && pnpm test:e2e:build && playwright test",
+    "test": "pnpm typecheck && pnpm test:unit && pnpm test:component && pnpm test:integration && pnpm test:skill-install && pnpm test:e2e:build && playwright test",
    "format": "prettier --write .",
    "lint": "eslint --cache .",
    "typecheck:node": "tsc --noEmit -p tsconfig.node.json --composite false",
    "typecheck:web": "tsc --noEmit -p tsconfig.web.json --composite false",
-    "typecheck": "npm run typecheck:node && npm run typecheck:web",
+    "typecheck": "npm run typecheck:node && npm run typecheck:web && npm run typecheck:test",
+    "typecheck:test": "node scripts/typecheck-tests.cjs",
    "test:skill-install": "node scripts/test-skill-install-instruction.cjs",
    "cp:env": "node scripts/ensure-env.cjs",
    "prepare:env": "node scripts/ensure-env.cjs",
    "prepare:ffmpeg:win": "node scripts/prepare-electron-runtime.cjs --platform win32 --arch x64",
+    "prepare:ffmpeg:mac:arm64": "node scripts/prepare-electron-runtime.cjs --platform darwin --arch arm64",
+    "prepare:ffmpeg:mac:x64": "node scripts/prepare-electron-runtime.cjs --platform darwin --arch x64",
+    "prepare:win-runtime": "node scripts/prepare-win-runtime.cjs && npm run prepare:ffmpeg:win",
+    "prepare:wechat-personal": "node scripts/prepare-wechat-chatter-runtime.cjs",
    "start": "electron-vite preview",
-    "dev": "node scripts/ensure-env.cjs && node scripts/build-wechat-connector.cjs && electron-vite dev",
-    "test:wechat-connector": "go -C services/wechat-connector test ./... && go -C services/wechat-connector vet ./...",
+    "predev": "node scripts/ensure-electron-binary.cjs",
+    "dev": "node scripts/ensure-env.cjs && electron-vite dev",
+    "dev:update": "cross-env TRACEMEMO_UPDATE_SIMULATION=true pnpm dev",
+    "poc:query-agent": "electron-vite build && node scripts/run-query-agent-poc.cjs",
+    "poc:query-agent:run": "node scripts/run-query-agent-poc.cjs",
    "test:unit": "vitest run --config vitest.unit.config.ts",
    "test:component": "vitest run --config vitest.component.config.ts",
    "test:integration": "vitest run --config vitest.integration.config.ts",
@@ -47,30 +56,47 @@
    "test:e2e": "pnpm test:e2e:build && playwright test --grep-invert @visual",
    "test:visual": "pnpm test:e2e:build && playwright test tests/e2e/visual.spec.ts",
    "test:smoke": "node --test tests/smoke/native-environment.test.mjs",
-    "build:wechat-connector": "node scripts/build-wechat-connector.cjs",
-    "build:wechat-connector:win": "node scripts/build-wechat-connector.cjs --platform win32 --arch x64,arm64",
-    "build:wechat-connector:mac": "node scripts/build-wechat-connector.cjs --platform darwin --arch arm64",
-    "build:native-services": "npm run build:wechat-connector",
-    "build": "npm run typecheck && npm run build:native-services && electron-vite build",
-    "postinstall": "electron-builder install-app-deps && node scripts/prepare-electron-runtime.cjs",
+    "build": "npm run typecheck && electron-vite build",
+    "postinstall": "electron-builder install-app-deps && node scripts/prepare-electron-runtime.cjs && node scripts/ensure-electron-binary.cjs",
    "build:unpack": "npm run build && electron-builder --config electron-builder.yml --dir",
-    "build:win": "npm run typecheck && npm run build:wechat-connector:win && npm run prepare:ffmpeg:win && electron-vite build && electron-builder --config electron-builder.yml --win --x64",
-    "build:mac:arm64": "npm run typecheck && node scripts/build-wechat-connector.cjs --platform darwin --arch arm64 && electron-vite build && electron-builder --config electron-builder.yml --mac --arm64",
+    "build:win": "npm run typecheck && npm run prepare:win-runtime && electron-vite build && electron-builder --config electron-builder.win.yml --win --x64",
+    "build:mac:arm64": "npm run typecheck && npm run prepare:ffmpeg:mac:arm64 && electron-vite build && electron-builder --config electron-builder.yml --mac --arm64",
+    "build:mac:x64": "npm run typecheck && npm run prepare:ffmpeg:mac:x64 && electron-vite build && electron-builder --config electron-builder.yml --mac --x64",
    "release": "npm run release:mac && npm run release:win",
-    "release:mac": "npm run typecheck && npm run build:wechat-connector:mac && electron-vite build && electron-builder --config electron-builder.yml --mac --arm64 --publish always",
-    "release:win": "npm run typecheck && npm run build:wechat-connector:win && npm run prepare:ffmpeg:win && electron-vite build && electron-builder --config electron-builder.yml --win --x64 --publish always",
-    "release:beta": "cross-env RELEASE_TYPE=prerelease npm run release",
-    "release:stable": "cross-env RELEASE_TYPE=release npm run release",
+    "release:mac": "npm run typecheck && electron-vite build && npm run release:mac:arm64 && npm run release:mac:x64",
+    "release:mac:arm64": "npm run prepare:ffmpeg:mac:arm64 && electron-builder --config electron-builder.yml --mac --arm64 --publish always",
+    "release:mac:x64": "npm run prepare:ffmpeg:mac:x64 && electron-builder --config electron-builder.yml --mac --x64 --publish always",
+    "release:win": "npm run typecheck && npm run prepare:win-runtime && electron-vite build && electron-builder --config electron-builder.win.yml --win --x64 --publish always",
+    "release:beta": "cross-env EP_PRE_RELEASE=true npm run release",
+    "release:stable": "npm run release",
    "build:linux": "electron-vite build && electron-builder --config electron-builder.yml --linux"
  },
  "dependencies": {
    "@electron-toolkit/preload": "^3.0.2",
    "@electron-toolkit/utils": "^4.0.0",
    "@koromix/koffi-win32-x64": "3.1.0",
+    "@napi-rs/system-ocr": "1.2.0",
+    "@napi-rs/system-ocr-win32-x64-msvc": "1.2.0",
+    "@radix-ui/react-alert-dialog": "^1.1.23",
+    "@radix-ui/react-checkbox": "^1.3.11",
+    "@radix-ui/react-dialog": "^1.1.23",
+    "@radix-ui/react-dropdown-menu": "^2.1.24",
    "@radix-ui/react-popover": "^1.1.23",
+    "@radix-ui/react-progress": "^1.1.16",
+    "@radix-ui/react-radio-group": "^1.4.7",
+    "@radix-ui/react-scroll-area": "^1.2.18",
+    "@radix-ui/react-select": "^2.3.7",
+    "@radix-ui/react-separator": "^1.1.15",
+    "@radix-ui/react-switch": "^1.3.7",
+    "@radix-ui/react-tabs": "^1.1.21",
+    "@radix-ui/react-toast": "^1.2.23",
+    "@radix-ui/react-tooltip": "^1.2.16",
    "@tanstack/react-virtual": "^3.14.6",
    "archiver": "^8.0.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
    "cross-env": "^10.1.0",
+    "css-tree": "^3.0.1",
    "electron-updater": "^6.6.2",
    "ffmpeg-static": "5.3.0",
    "fs-extra": "^11.3.2",
@@ -78,9 +104,13 @@
    "jsonrepair": "^3.15.0",
    "koffi": "^3.1.0",
    "openai": "^6.10.0",
+    "parse5": "^8.0.0",
+    "pinyin-pro": "^3.26.0",
    "qrcode": "^1.5.4",
    "sherpa-onnx-node": "1.13.3",
    "silk-wasm": "^3.7.1",
+    "tailwind-merge": "^3.6.0",
+    "unzipper": "^0.12.0",
    "wechat-emojis": "^1.0.2"
  },
  "devDependencies": {
@@ -101,6 +131,7 @@
    "@types/react-dom": "^19.2.3",
    "@vitejs/plugin-react": "^5.1.1",
    "@vitest/coverage-v8": "^4.1.10",
+    "autoprefixer": "^10.5.4",
    "electron": "^43.0.0",
    "electron-builder": "^26.0.12",
    "electron-vite": "^5.0.0",
@@ -109,10 +140,13 @@
    "eslint-plugin-react-hooks": "^7.0.1",
    "eslint-plugin-react-refresh": "^0.4.24",
    "jsdom": "^30.0.1",
+    "postcss": "^8.5.26",
    "prettier": "^3.7.4",
    "react": "^19.2.1",
    "react-dom": "^19.2.1",
    "sass": "^1.102.0",
+    "tailwindcss": "3.4.17",
+    "tailwindcss-animate": "^1.0.7",
    "typescript": "^5.9.3",
    "vite": "^7.2.6",
    "vitest": "^4.1.10",
@@ -0,0 +1,6 @@
+module.exports = {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {}
+  }
+}
@@ -68,21 +68,29 @@
      .overview {
        margin-top: 2px;
      }
+      /*
+       * hero 头像簇的几何必须由 contract 变量驱动，不能再写死容器尺寸。
+       *
+       * 生产导出会额外注入 `report-template-fragment-contract.ts`，其中
+       * `img.tm-avatar.tm-avatar--hero` 用 !important 把头像钉在
+       * clamp(28px, var(--tm-avatar-hero-size, 40px), 56px)。
+       * 旧版这里写死 58x58（单头像 28x28），两个权威打架：头像实际 40px，
+       * 2 列 x 40px + 3px gap = 83px 塞不进 58px 的盒子，于是头像向右向下溢出容器，
+       * 视觉上越过卡片内边距、压到卡片边缘之外。
+       *
+       * 现在容器尺寸由内容决定（列宽/行高都取同一个变量）：头像数 1..4 都不会溢出，
+       * 主题调整 --tm-avatar-hero-size 时容器与头像也不会分叉。
+       */
      .avatar-grid {
-        width: 58px;
-        height: 58px;
        display: grid;
-        grid-template-columns: 1fr 1fr;
+        grid-template-columns: repeat(2, var(--tm-avatar-hero-size, 40px));
+        grid-auto-rows: var(--tm-avatar-hero-size, 40px);
        gap: 3px;
        flex: 0 0 auto;
      }
+      /* 单头像时不保留空列，簇宽恰好等于一个头像。 */
      .avatar-grid.avatar-count-1 {
-        width: 28px;
-        height: 28px;
-        grid-template-columns: 1fr;
-      }
-      .avatar-grid.avatar-count-2 {
-        height: 28px;
+        grid-template-columns: var(--tm-avatar-hero-size, 40px);
      }
      .avatar-grid.empty-section {
        display: none;
@@ -61,21 +61,29 @@
        font-size: 13px;
        line-height: 1.55;
      }
+      /*
+       * hero 头像簇的几何必须由 contract 变量驱动，不能再写死容器尺寸。
+       *
+       * 生产导出会额外注入 `report-template-fragment-contract.ts`，其中
+       * `img.tm-avatar.tm-avatar--hero` 用 !important 把头像钉在
+       * clamp(28px, var(--tm-avatar-hero-size, 40px), 56px)。
+       * 旧版这里写死 58x58（单头像 28x28），两个权威打架：头像实际 40px，
+       * 2 列 x 40px + 3px gap = 83px 塞不进 58px 的盒子，于是头像向右向下溢出容器，
+       * 视觉上越过卡片内边距、压到卡片边缘之外。
+       *
+       * 现在容器尺寸由内容决定（列宽/行高都取同一个变量）：头像数 1..4 都不会溢出，
+       * 主题调整 --tm-avatar-hero-size 时容器与头像也不会分叉。
+       */
      .avatar-grid {
-        width: 58px;
-        height: 58px;
        display: grid;
-        grid-template-columns: 1fr 1fr;
+        grid-template-columns: repeat(2, var(--tm-avatar-hero-size, 40px));
+        grid-auto-rows: var(--tm-avatar-hero-size, 40px);
        gap: 3px;
        flex: 0 0 auto;
      }
+      /* 单头像时不保留空列，簇宽恰好等于一个头像。 */
      .avatar-grid.avatar-count-1 {
-        width: 28px;
-        height: 28px;
-        grid-template-columns: 1fr;
-      }
-      .avatar-grid.avatar-count-2 {
-        height: 28px;
+        grid-template-columns: var(--tm-avatar-hero-size, 40px);
      }
      .avatar-grid.empty-section {
        display: none;
@@ -0,0 +1 @@
+a35d3fa67387e049cc30bc073f9e65b077aa1db9c5c2b183125dec695fa013b9  xkey_helper_4_1_13
@@ -1,11 +1,10 @@
 /* eslint-disable @typescript-eslint/no-require-imports, @typescript-eslint/explicit-function-return-type */
-const { chmodSync, existsSync, renameSync } = require('node:fs')
+const { chmodSync, existsSync, readdirSync, rmSync } = require('node:fs')
 const { execFileSync } = require('node:child_process')
 const path = require('node:path')
 const asar = require('@electron/asar')
+const { readBinaryArchitectures } = require('./binary-arch.cjs')

-const COMPATIBILITY_NAME = 'Electron'
-const HELPER_SUFFIXES = ['', ' (Plugin)', ' (Renderer)', ' (GPU)']
 const REQUIRED_RUNTIME_PACKAGES = [
  '@electron-toolkit/preload',
  '@electron-toolkit/utils',
@@ -17,6 +16,15 @@ const REQUIRED_RUNTIME_PACKAGES = [
  'koffi'
 ]

+// electron-builder 26 skips macOS signing entirely when no Developer ID
+// identity is configured, so an unpacked bundle can ship without a usable
+// signature. macOS kills a helper whose code or signature is missing or
+// modified even when SIP is disabled, which is what customers hit on newer
+// macOS releases. Ad-hoc re-sign the runtime helpers and the outer bundle so
+// every Mach-O verifies strictly; spctl still rejects ad-hoc code, which is
+// acceptable for the SIP-disabled customer workflow.
+const MACOS_HELPER_NAMES = ['xkey_helper', 'xkey_helper_4_1_13']
+
 function getRuntimeResources(context) {
  const productName = context.packager.appInfo.productFilename
  return context.electronPlatformName === 'darwin'
@@ -79,11 +87,143 @@ function validateSherpaRuntime(runtimeResources, platform, arch) {
  }
 }

+/**
+ * System OCR 用 native package（@napi-rs/system-ocr）。它是 external + asarUnpack，
+ * 打包后必须以 unpacked 形式存在，否则运行时会 MODULE_NOT_FOUND / native binding missing。
+ * Windows 与 macOS 都是 supported target，都要做硬校验（Linux 不是）。
+ */
+function systemOcrTarget(platform, arch) {
+  return platform === 'win32' ? `${platform}-${arch}-msvc` : `${platform}-${arch}`
+}
+
+function validateSystemOcrRuntime(runtimeResources, platform, arch) {
+  if (platform !== 'win32' && platform !== 'darwin') return
+  const target = systemOcrTarget(platform, arch)
+  const basePath = path.join(
+    runtimeResources,
+    'app.asar.unpacked',
+    'node_modules',
+    '@napi-rs',
+    'system-ocr'
+  )
+  const nativePath = path.join(
+    runtimeResources,
+    'app.asar.unpacked',
+    'node_modules',
+    '@napi-rs',
+    `system-ocr-${target}`
+  )
+  const requiredFiles = [
+    path.join(basePath, 'package.json'),
+    path.join(basePath, 'index.js'),
+    path.join(nativePath, 'package.json'),
+    path.join(nativePath, `system-ocr.${target}.node`)
+  ]
+  const missingFiles = requiredFiles.filter((filePath) => !existsSync(filePath))
+  if (missingFiles.length > 0) {
+    throw new Error(`Missing unpacked System OCR runtime: ${missingFiles.join(', ')}`)
+  }
+}
+
 function normalizeBuilderArch(arch) {
  if (typeof arch === 'string') return arch
  return { 0: 'ia32', 1: 'x64', 2: 'armv7l', 3: 'arm64', 4: 'universal' }[arch] || String(arch)
 }

+function runCodesign(args) {
+  execFileSync('/usr/bin/codesign', args, { stdio: 'ignore' })
+}
+
+function isMacosCodeValid(targetPath, run = runCodesign) {
+  try {
+    run(['--verify', '--strict', targetPath])
+    return true
+  } catch {
+    return false
+  }
+}
+
+function findMacosHelperPaths(runtimeResources) {
+  return MACOS_HELPER_NAMES.map((name) => path.join(runtimeResources, 'resources', name)).filter(
+    (helperPath) => existsSync(helperPath)
+  )
+}
+
+function signMacosHelpers(runtimeResources, run = runCodesign) {
+  const helperPaths = findMacosHelperPaths(runtimeResources)
+  for (const helperPath of helperPaths) {
+    chmodSync(helperPath, 0o755)
+    if (!isMacosCodeValid(helperPath, run)) {
+      run(['--force', '--sign', '-', helperPath])
+    }
+    for (const arch of ['arm64', 'x86_64']) {
+      try {
+        run(['--verify', '--strict', '--arch', arch, helperPath])
+      } catch (error) {
+        throw new Error(
+          'macOS helper signature verification failed: ' +
+            path.basename(helperPath) +
+            ' (' +
+            arch +
+            ')',
+          { cause: error }
+        )
+      }
+    }
+  }
+  return helperPaths
+}
+
+function signMacosAppBundle(appBundlePath, run = runCodesign) {
+  if (isMacosCodeValid(appBundlePath, run)) return appBundlePath
+  run(['--force', '--sign', '-', appBundlePath])
+  try {
+    run(['--verify', '--strict', appBundlePath])
+  } catch (error) {
+    throw new Error('macOS app bundle signature verification failed: ' + appBundlePath, {
+      cause: error
+    })
+  }
+  return appBundlePath
+}
+
+/**
+ * A foreign-architecture binary only fails once the user touches the feature
+ * that needs it, so verify the ones whose filename is shared across
+ * architectures (ffmpeg-static keeps a single "ffmpeg" per platform) and fail
+ * the build instead of shipping a broken bundle.
+ */
+function validateRuntimeBinaryArchitecture(filePath, platform, arch, label) {
+  if (platform !== 'darwin' && platform !== 'win32') return
+  if (arch === 'universal') return
+  const architectures = readBinaryArchitectures(filePath)
+  if (!architectures.length || architectures.includes(arch)) return
+  throw new Error(
+    `${label} is ${architectures.join('/')} but this bundle targets ${arch}: ${filePath}`
+  )
+}
+
+/**
+ * The Intel Mac key helper is an x86_64 executable that only the x64 (or
+ * universal) macOS bundle can run. Every other target — Apple Silicon macOS,
+ * Windows, Linux — would otherwise ship a ~34MB binary it can never execute,
+ * so it is dropped from those bundles. x64/universal builds fail fast instead
+ * of silently shipping an Intel Mac app that cannot read keys.
+ */
+function pruneIntelMacKeyTool(runtimeResources, platform, arch) {
+  const keyToolDirectory = path.join(runtimeResources, 'resources', 'macos-key-tool')
+  const usable = platform === 'darwin' && (arch === 'x64' || arch === 'universal')
+  if (!usable) {
+    rmSync(keyToolDirectory, { recursive: true, force: true })
+    return null
+  }
+  const helperPath = path.join(keyToolDirectory, 'intel_mac_key_helper')
+  if (!existsSync(helperPath)) {
+    throw new Error(`Missing Intel Mac key helper in a ${arch} bundle: ${helperPath}`)
+  }
+  return helperPath
+}
+
 function validateAsarRuntimeDependencies(runtimeResources) {
  const asarPath = path.join(runtimeResources, 'app.asar')
  if (!existsSync(asarPath)) throw new Error(`Missing packaged application archive: ${asarPath}`)
@@ -101,10 +241,6 @@ function validateAsarRuntimeDependencies(runtimeResources) {
    )
  }
 }
-function setPlistValue(plistPath, key, value) {
-  execFileSync('/usr/libexec/PlistBuddy', ['-c', `Set :${key} ${value}`, plistPath])
-}
-
 function validateReaderSkillRuntime(runtimeResources) {
  const skillPath = path.join(runtimeResources, 'skill', 'tracememo-reader', 'SKILL.md')
  if (!existsSync(skillPath)) {
@@ -113,22 +249,108 @@ function validateReaderSkillRuntime(runtimeResources) {
  return skillPath
 }

+/**
+ * Native runtime packages are published once per platform-arch pair, and pnpm
+ * installs all of them, so every bundle ends up carrying the native libraries
+ * of every platform (measured: ~129MB of speech models plus ~16MB of koffi).
+ * The loaders pick their package from process.platform/arch, so the siblings
+ * are dead weight — drop them.
+ */
+// 每个条目返回 platform package 的**完整后缀**（不含 package 前缀与连字符）。
+const NATIVE_RUNTIME_PACKAGES = [
+  {
+    modules: [],
+    prefix: 'sherpa-onnx',
+    platformName: (platform, arch) => `${platform === 'win32' ? 'win' : platform}-${arch}`
+  },
+  {
+    modules: ['@koromix'],
+    prefix: 'koffi',
+    platformName: (platform, arch) => `${platform}-${arch}`
+  },
+  {
+    // @napi-rs 的 platform package 目录名带 -msvc 后缀（win32-x64-msvc）。
+    modules: ['@napi-rs'],
+    prefix: 'system-ocr',
+    platformName: (platform, arch) => systemOcrTarget(platform, arch),
+    foreignPattern: /^system-ocr-[a-z0-9]+-(arm64|x64|ia32|loong64|riscv64)(-msvc)?$/
+  }
+]
+
+function pruneForeignArchNativeRuntimes(runtimeResources, platform, arch) {
+  if (arch === 'universal') return []
+  const unpackedRoot = path.join(runtimeResources, 'app.asar.unpacked', 'node_modules')
+  if (!existsSync(unpackedRoot)) return []
+  const removed = []
+  for (const runtime of NATIVE_RUNTIME_PACKAGES) {
+    const modulesRoot = path.join(unpackedRoot, ...runtime.modules)
+    if (!existsSync(modulesRoot)) continue
+    const expected = `${runtime.prefix}-${runtime.platformName(platform, arch)}`
+    const foreign =
+      runtime.foreignPattern ||
+      new RegExp(`^${runtime.prefix}-[a-z0-9]+-(arm64|x64|ia32|loong64|riscv64)$`)
+    for (const entry of readdirSync(modulesRoot, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.name === expected || !foreign.test(entry.name)) continue
+      rmSync(path.join(modulesRoot, entry.name), { recursive: true, force: true })
+      removed.push(
+        runtime.modules.length ? `${runtime.modules.join('/')}/${entry.name}` : entry.name
+      )
+    }
+  }
+  return removed
+}
+
+/**
+ * Bundled native directories under resources/connectors are named
+ * "<platform>-<arch>". Cross-building both macOS architectures leaves both on
+ * disk, but a bundle can only execute its own, so drop the foreign ones
+ * instead of shipping every connector twice.
+ */
+function pruneForeignArchConnectors(runtimeResources, platform, arch) {
+  if (arch === 'universal') return []
+  const connectorsRoot = path.join(runtimeResources, 'resources', 'connectors')
+  if (!existsSync(connectorsRoot)) return []
+  const expected = `${platform}-${arch}`
+  const removed = []
+  for (const packageEntry of readdirSync(connectorsRoot, { withFileTypes: true })) {
+    if (!packageEntry.isDirectory()) continue
+    const packageRoot = path.join(connectorsRoot, packageEntry.name)
+    for (const targetEntry of readdirSync(packageRoot, { withFileTypes: true })) {
+      if (!targetEntry.isDirectory() || targetEntry.name === expected) continue
+      if (!/^[a-z0-9]+-(arm64|x64|ia32)$/.test(targetEntry.name)) continue
+      rmSync(path.join(packageRoot, targetEntry.name), { recursive: true, force: true })
+      removed.push(`${packageEntry.name}/${targetEntry.name}`)
+    }
+  }
+  return removed
+}
+
 exports.default = async function afterPack(context) {
  const runtimeResources = getRuntimeResources(context)
+  const arch = normalizeBuilderArch(context.arch)
  validateAsarRuntimeDependencies(runtimeResources)
  validateReaderSkillRuntime(runtimeResources)
  validateSilkWasmRuntime(runtimeResources)
  const ffmpegPath = validateFfmpegRuntime(runtimeResources, context.electronPlatformName)
-  validateSherpaRuntime(
-    runtimeResources,
+  validateRuntimeBinaryArchitecture(
+    ffmpegPath,
    context.electronPlatformName,
-    normalizeBuilderArch(context.arch)
+    arch,
+    'Bundled ffmpeg'
  )
+  validateSherpaRuntime(runtimeResources, context.electronPlatformName, arch)
+  validateSystemOcrRuntime(runtimeResources, context.electronPlatformName, arch)
+  pruneIntelMacKeyTool(runtimeResources, context.electronPlatformName, arch)
+  pruneForeignArchConnectors(runtimeResources, context.electronPlatformName, arch)
+  pruneForeignArchNativeRuntimes(runtimeResources, context.electronPlatformName, arch)

  if (context.electronPlatformName === 'darwin') {
    execFileSync('/usr/bin/codesign', ['--force', '--sign', '-', ffmpegPath], {
      stdio: 'ignore'
    })
+    signMacosHelpers(runtimeResources)
+    const productName = context.packager.appInfo.productFilename
+    signMacosAppBundle(path.join(context.appOutDir, productName + '.app'))
  }

  if (context.electronPlatformName === 'win32') {
@@ -147,48 +369,6 @@ exports.default = async function afterPack(context) {
    }
    return
  }
-
-  if (context.electronPlatformName !== 'darwin') return
-
-  const productName = context.packager.appInfo.productFilename
-  const appPath = path.join(context.appOutDir, `${productName}.app`)
-  const contentsPath = path.join(appPath, 'Contents')
-  const sourceExecutable = path.join(contentsPath, 'MacOS', productName)
-  const targetExecutable = path.join(contentsPath, 'MacOS', COMPATIBILITY_NAME)
-
-  if (existsSync(sourceExecutable)) renameSync(sourceExecutable, targetExecutable)
-  if (!existsSync(targetExecutable)) {
-    throw new Error(`Missing Electron main executable: ${sourceExecutable}`)
-  }
-
-  const appPlistPath = path.join(contentsPath, 'Info.plist')
-  setPlistValue(appPlistPath, 'CFBundleExecutable', COMPATIBILITY_NAME)
-  setPlistValue(appPlistPath, 'CFBundleName', COMPATIBILITY_NAME)
-
-  const frameworksPath = path.join(contentsPath, 'Frameworks')
-
-  for (const suffix of HELPER_SUFFIXES) {
-    const sourceName = `${productName} Helper${suffix}`
-    const targetName = `${COMPATIBILITY_NAME} Helper${suffix}`
-    const sourceBundle = path.join(frameworksPath, `${sourceName}.app`)
-    const targetBundle = path.join(frameworksPath, `${targetName}.app`)
-
-    if (existsSync(sourceBundle)) renameSync(sourceBundle, targetBundle)
-    if (!existsSync(targetBundle)) {
-      throw new Error(`Missing Electron helper bundle: ${sourceBundle}`)
-    }
-
-    const sourceExecutable = path.join(targetBundle, 'Contents', 'MacOS', sourceName)
-    const targetExecutable = path.join(targetBundle, 'Contents', 'MacOS', targetName)
-    if (existsSync(sourceExecutable)) renameSync(sourceExecutable, targetExecutable)
-    if (!existsSync(targetExecutable)) {
-      throw new Error(`Missing Electron helper executable: ${sourceExecutable}`)
-    }
-
-    const plistPath = path.join(targetBundle, 'Contents', 'Info.plist')
-    setPlistValue(plistPath, 'CFBundleExecutable', targetName)
-    setPlistValue(plistPath, 'CFBundleName', targetName)
-  }
 }

 exports.getRuntimeResources = getRuntimeResources
@@ -197,3 +377,12 @@ exports.validateReaderSkillRuntime = validateReaderSkillRuntime
 exports.validateFfmpegRuntime = validateFfmpegRuntime
 exports.validateSilkWasmRuntime = validateSilkWasmRuntime
 exports.validateSherpaRuntime = validateSherpaRuntime
+exports.validateSystemOcrRuntime = validateSystemOcrRuntime
+exports.pruneIntelMacKeyTool = pruneIntelMacKeyTool
+exports.pruneForeignArchConnectors = pruneForeignArchConnectors
+exports.pruneForeignArchNativeRuntimes = pruneForeignArchNativeRuntimes
+exports.validateRuntimeBinaryArchitecture = validateRuntimeBinaryArchitecture
+exports.findMacosHelperPaths = findMacosHelperPaths
+exports.isMacosCodeValid = isMacosCodeValid
+exports.signMacosHelpers = signMacosHelpers
+exports.signMacosAppBundle = signMacosAppBundle
@@ -0,0 +1,83 @@
+/* eslint-disable @typescript-eslint/no-require-imports */
+const fs = require('node:fs')
+
+const MACHO_MAGIC_32 = 0xfeedface
+const MACHO_MAGIC_64 = 0xfeedfacf
+const FAT_MAGIC = 0xcafebabe
+const FAT_MAGIC_64 = 0xcafebabf
+const PE_SIGNATURE = 0x00004550
+const PE_MACHINE_X64 = 0x8664
+const PE_MACHINE_ARM64 = 0xaa64
+
+const CPU_TYPE_IA32 = 0x00000007
+const CPU_TYPE_X86_64 = 0x01000007
+const CPU_TYPE_ARM64 = 0x0100000c
+
+/** Only the headers are needed; native binaries can be tens of megabytes. */
+const HEADER_BYTES = 64 * 1024
+
+function readHeader(filePath) {
+  const descriptor = fs.openSync(filePath, 'r')
+  try {
+    const buffer = Buffer.alloc(HEADER_BYTES)
+    const bytesRead = fs.readSync(descriptor, buffer, 0, HEADER_BYTES, 0)
+    return buffer.subarray(0, bytesRead)
+  } finally {
+    fs.closeSync(descriptor)
+  }
+}
+
+function normalizeMachoCpuType(cpuType) {
+  if (cpuType === CPU_TYPE_X86_64) return 'x64'
+  if (cpuType === CPU_TYPE_ARM64) return 'arm64'
+  if (cpuType === CPU_TYPE_IA32) return 'ia32'
+  return ''
+}
+
+/**
+ * Returns every architecture contained in a Mach-O or PE binary, as
+ * electron-builder arch names ("x64", "arm64"). Universal binaries report both.
+ * Returns an empty array for anything that is not a native executable (scripts,
+ * wasm), so callers can treat "unknown" separately from "wrong architecture".
+ */
+function readBinaryArchitectures(filePath) {
+  let buffer
+  try {
+    buffer = readHeader(filePath)
+  } catch {
+    return []
+  }
+  if (buffer.length < 8) return []
+
+  const fatMagic = buffer.readUInt32BE(0)
+  if (fatMagic === FAT_MAGIC || fatMagic === FAT_MAGIC_64) {
+    const entrySize = fatMagic === FAT_MAGIC_64 ? 32 : 20
+    const count = Math.min(buffer.readUInt32BE(4), 32)
+    const architectures = []
+    for (let index = 0; index < count; index += 1) {
+      const entryOffset = 8 + index * entrySize
+      if (entryOffset + 4 > buffer.length) break
+      const name = normalizeMachoCpuType(buffer.readUInt32BE(entryOffset))
+      if (name && !architectures.includes(name)) architectures.push(name)
+    }
+    return architectures
+  }
+
+  const thinMagic = buffer.readUInt32LE(0)
+  if (thinMagic === MACHO_MAGIC_32 || thinMagic === MACHO_MAGIC_64) {
+    const name = normalizeMachoCpuType(buffer.readUInt32LE(4))
+    return name ? [name] : []
+  }
+
+  if (buffer.readUInt16LE(0) === 0x5a4d) {
+    const peOffset = buffer.readUInt32LE(0x3c)
+    if (peOffset + 6 > buffer.length || buffer.readUInt32LE(peOffset) !== PE_SIGNATURE) return []
+    const machine = buffer.readUInt16LE(peOffset + 4)
+    if (machine === PE_MACHINE_X64) return ['x64']
+    if (machine === PE_MACHINE_ARM64) return ['arm64']
+  }
+
+  return []
+}
+
+module.exports = { readBinaryArchitectures }
@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+const fs = require('node:fs')
+const path = require('node:path')
+const { ZipArchive } = require('archiver')
+
+const root = path.resolve(__dirname, '..')
+const source = path.join(root, 'examples', 'report-template-basic')
+const outputPath = path.join(root, 'examples', 'report-template-basic.zip')
+const output = fs.createWriteStream(outputPath)
+const archive = new ZipArchive({ zlib: { level: 9 } })
+output.on('close', () => console.log(`wrote ${outputPath} (${archive.pointer()} bytes)`))
+archive.on('error', (error) => { throw error })
+archive.pipe(output)
+archive.file(path.join(source, 'manifest.json'), { name: 'manifest.json' })
+archive.file(path.join(source, 'template.html'), { name: 'template.html' })
+// 使用 1x1 PNG 作为虚构预览占位图，避免引入真实用户媒体。
+archive.append(Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=', 'base64'), { name: 'preview.png' })
+archive.finalize()
@@ -1,65 +0,0 @@
-/* eslint-disable @typescript-eslint/no-require-imports, @typescript-eslint/explicit-function-return-type */
-const { execFileSync } = require('node:child_process')
-const fs = require('node:fs')
-const path = require('node:path')
-
-const projectRoot = path.resolve(__dirname, '..')
-const sourceDir = path.join(projectRoot, 'services', 'wechat-connector')
-const outputRoot = path.join(projectRoot, 'resources', 'connectors', 'wechat')
-
-function normalizePlatform(value) {
-  if (value === 'win32' || value === 'windows') return 'windows'
-  if (value === 'darwin' || value === 'macos') return 'darwin'
-  if (value === 'linux') return 'linux'
-  throw new Error(`Unsupported connector platform: ${value}`)
-}
-
-function normalizeArch(value) {
-  if (value === 'x64' || value === 'amd64') return 'amd64'
-  if (value === 'arm64') return 'arm64'
-  throw new Error(`Unsupported connector architecture: ${value}`)
-}
-
-function detectHostArch() {
-  if (process.platform !== 'darwin') return process.arch
-  try {
-    const arm64Supported = execFileSync('sysctl', ['-n', 'hw.optional.arm64'], {
-      encoding: 'utf8'
-    }).trim()
-    return arm64Supported === '1' ? 'arm64' : process.arch
-  } catch {
-    return process.arch
-  }
-}
-
-function parseTargets() {
-  const platformArg = process.argv.indexOf('--platform')
-  const archArg = process.argv.indexOf('--arch')
-  const platforms = platformArg >= 0 ? process.argv[platformArg + 1].split(',') : [process.platform]
-  const arches = archArg >= 0 ? process.argv[archArg + 1].split(',') : [detectHostArch()]
-  return platforms.flatMap((platform) =>
-    arches.map((arch) => ({ goos: normalizePlatform(platform), goarch: normalizeArch(arch) }))
-  )
-}
-
-if (!fs.existsSync(path.join(sourceDir, 'go.mod'))) {
-  throw new Error(`Repository-local WeChat connector source is missing: ${sourceDir}`)
-}
-
-for (const target of parseTargets()) {
-  const directoryName = `${target.goos === 'windows' ? 'win32' : target.goos}-${target.goarch === 'amd64' ? 'x64' : target.goarch}`
-  const outputDir = path.join(outputRoot, directoryName)
-  const outputPath = path.join(
-    outputDir,
-    target.goos === 'windows' ? 'wechat-connector.exe' : 'wechat-connector'
-  )
-  fs.rmSync(outputDir, { recursive: true, force: true })
-  fs.mkdirSync(outputDir, { recursive: true })
-  execFileSync('go', ['build', '-trimpath', '-o', outputPath, '.'], {
-    cwd: sourceDir,
-    env: { ...process.env, GOOS: target.goos, GOARCH: target.goarch, CGO_ENABLED: '0' },
-    stdio: 'inherit'
-  })
-  if (target.goos !== 'windows') fs.chmodSync(outputPath, 0o755)
-  console.log(`[build-wechat-connector] built ${directoryName}: ${outputPath}`)
-}
@@ -0,0 +1,103 @@
+/* eslint-disable @typescript-eslint/no-require-imports */
+const fs = require('node:fs')
+const { execFileSync } = require('node:child_process')
+const path = require('node:path')
+
+/**
+ * electron@43 的 npm 包不再声明 postinstall（它自己的 package.json 里 scripts 是空的），
+ * 下载被改成「首次 require('electron') 时的懒加载」。后果是 `pnpm install` 之后
+ * node_modules/electron 里只有一个空壳：dist/ 与 path.txt 都不在，而
+ * package.json 里的 pnpm.onlyBuiltDependencies: ["electron"] 对着空气发号施令 ——
+ * 上游没有脚本可跑，pnpm 自然什么也不做。新 clone 于是直到 `pnpm dev` 才炸。
+ * 这里显式补上下载，并把它挂在 postinstall / predev 上。
+ */
+const MIRROR_FALLBACK = 'https://npmmirror.com/mirrors/electron/'
+const projectRoot = path.resolve(__dirname, '..')
+
+function resolveElectronPackageRoot() {
+  try {
+    return path.dirname(require.resolve('electron/package.json'))
+  } catch {
+    return ''
+  }
+}
+
+/**
+ * .npmrc 的 electron_mirror 只有在 npm/pnpm 执行脚本时才会变成 npm_config_* 环境变量；
+ * 直接 `node node_modules/electron/install.js` 时读不到，于是会绕开镜像去打 GitHub。
+ * 这里显式读出来当 ELECTRON_MIRROR 传下去。显式设置的环境变量优先。
+ */
+function resolveMirror() {
+  if (process.env.ELECTRON_MIRROR) return process.env.ELECTRON_MIRROR
+  try {
+    const npmrc = fs.readFileSync(path.join(projectRoot, '.npmrc'), 'utf8')
+    const match = npmrc.match(/^\s*electron_mirror\s*=\s*(\S+)\s*$/m)
+    return match ? match[1] : ''
+  } catch {
+    return ''
+  }
+}
+
+/**
+ * path.txt 只是 electron 写下的相对路径，光有它不算装好 —— 指向的可执行文件
+ * 必须真的存在，否则仍会在启动时报「Electron failed to install correctly」。
+ */
+function isElectronBinaryInstalled(packageRoot) {
+  if (!packageRoot) return false
+  try {
+    const executable = fs.readFileSync(path.join(packageRoot, 'path.txt'), 'utf8').trim()
+    return executable !== '' && fs.existsSync(path.join(packageRoot, 'dist', executable))
+  } catch {
+    return false
+  }
+}
+
+function runInstaller(packageRoot) {
+  const installer = path.join(packageRoot, 'install.js')
+  if (!fs.existsSync(installer)) {
+    throw new Error(`[ensure-electron] missing ${installer}; run pnpm install first`)
+  }
+  const mirror = resolveMirror()
+  const attempts = mirror
+    ? [{ label: mirror, env: { ELECTRON_MIRROR: mirror } }]
+    : [{ label: 'default source', env: {} }]
+  // 配的镜像本身不是 npmmirror 时，再兜一层：镜像挂掉时不至于完全没退路。
+  if (!mirror.includes('npmmirror.com')) {
+    attempts.push({ label: MIRROR_FALLBACK, env: { ELECTRON_MIRROR: MIRROR_FALLBACK } })
+  }
+  let lastError
+  for (let index = 0; index < attempts.length; index += 1) {
+    const attempt = attempts[index]
+    console.log(`[ensure-electron] downloading from ${attempt.label}`)
+    try {
+      execFileSync(process.execPath, [installer], {
+        stdio: 'inherit',
+        env: { ...process.env, ...attempt.env }
+      })
+      return
+    } catch (error) {
+      lastError = error
+      const next = attempts[index + 1]
+      if (next) {
+        console.warn(`[ensure-electron] download failed, retrying from ${next.label}`)
+      }
+    }
+  }
+  throw lastError
+}
+
+function ensureElectronBinary() {
+  const packageRoot = resolveElectronPackageRoot()
+  if (isElectronBinaryInstalled(packageRoot)) return false
+  console.log('[ensure-electron] Electron binary is missing; downloading it now')
+  runInstaller(packageRoot)
+  if (!isElectronBinaryInstalled(packageRoot)) {
+    throw new Error('[ensure-electron] Electron binary is still missing after installing')
+  }
+  console.log('[ensure-electron] Electron binary is ready')
+  return true
+}
+
+if (require.main === module) ensureElectronBinary()
+
+module.exports = { ensureElectronBinary, isElectronBinaryInstalled, resolveElectronPackageRoot }
@@ -98,7 +98,7 @@ const activityLine = Array.from(document.querySelectorAll('.analytics > .card'))
 const values = {
  REPORT_TITLE: title,
  REPORT_DATE: reportDate,
-  DATE_RANGE: '今天',
+  DATE_RANGE: '今日',
  TIME_SPAN: statValues[2] || dateTimeRange,
  HERO_SUMMARY: overview,
  HERO_TAKEAWAY: '',
@@ -0,0 +1,64 @@
+#!/bin/sh
+set -eu
+
+ANCHOR='com.tencent.wechat.update'
+ANCHOR_FILE='/etc/pf.anchors/wechat-update'
+PF_CONF='/etc/pf.conf'
+BACKUP_DIR='/etc/pf.conf.wechat-backups'
+CACHE_DIR="${HOME}/Library/Caches/com.tencent.xinWeChat"
+
+domains='dldir1.qq.com dldir2.qq.com dldir3.qq.com dldir1v6.qq.com'
+
+die() { printf '%s\n' "error: $*" >&2; exit 1; }
+need_root() { [ "$(id -u)" -eq 0 ] || die '请使用 sudo 执行此脚本'; }
+
+resolve_ips() {
+  command -v dig >/dev/null 2>&1 || die '需要 dig（macOS 通常已内置）'
+  for domain in $domains; do
+    dig +short A "$domain"
+    dig +short AAAA "$domain"
+  done | awk '/^[0-9]+(\.[0-9]+){3}$/ || /^[0-9A-Fa-f:]+:[0-9A-Fa-f:]+/' | sort -u
+}
+
+enable() {
+  need_root
+  ips="$(resolve_ips)"
+  [ -n "$ips" ] || die '域名解析没有返回 IP，未修改 PF'
+  mkdir -p /etc/pf.anchors "$BACKUP_DIR"
+  backup="$BACKUP_DIR/pf.conf.$(date +%Y%m%d-%H%M%S)"
+  cp -p "$PF_CONF" "$backup"
+  {
+    printf 'table <wechat_update> persist { '
+    printf '%s' "$ips" | tr '\n' ' '
+    printf '}\nblock drop out quick to <wechat_update>\n'
+  } > "$ANCHOR_FILE"
+  if ! grep -Fq 'anchor "com.tencent.wechat.update"' "$PF_CONF"; then
+    printf '\n# TraceMemo: block WeChat update endpoints\nanchor "com.tencent.wechat.update"\nload anchor "com.tencent.wechat.update" from "/etc/pf.anchors/wechat-update"\n' >> "$PF_CONF"
+  fi
+  pfctl -vnf "$PF_CONF"
+  pfctl -f "$PF_CONF"
+  pfctl -E >/dev/null 2>&1 || true
+  printf '已启用微信更新拦截，规则备份：%s\n' "$backup"
+  printf '当前 IP：\n%s\n' "$ips"
+}
+
+disable() {
+  need_root
+  pfctl -a "$ANCHOR" -F all >/dev/null 2>&1 || true
+  printf '已清空微信更新 PF anchor。要完全移除配置行，请从 /etc/pf.conf 删除 TraceMemo 标记的三行。\n'
+}
+
+status() {
+  pfctl -s info 2>&1 | head -20
+  printf '\n微信更新 anchor：\n'
+  pfctl -a "$ANCHOR" -sr 2>&1 || true
+  printf '\n缓存目录：\n%s\n' "$CACHE_DIR"
+  ls -ldO "$CACHE_DIR" 2>/dev/null || true
+}
+
+case "${1:-status}" in
+  enable) enable ;;
+  disable) disable ;;
+  status) status ;;
+  *) die "用法：sudo $0 {enable|disable|status}" ;;
+esac
@@ -1,6 +1,7 @@
 const fs = require('node:fs')
 const { execFileSync } = require('node:child_process')
 const path = require('node:path')
+const { readBinaryArchitectures } = require('./binary-arch.cjs')

 const runtimeNames = ['msvcp140.dll', 'msvcp140_1.dll', 'vcruntime140.dll', 'vcruntime140_1.dll']

@@ -24,6 +25,31 @@ function readOption(name, fallback) {
  return index >= 0 && process.argv[index + 1] ? process.argv[index + 1] : fallback
 }

+function ffmpegExecutableName(targetPlatform) {
+  return targetPlatform === 'win32' ? 'ffmpeg.exe' : 'ffmpeg'
+}
+
+/**
+ * ffmpeg-static keeps a single binary per platform ("ffmpeg" everywhere except
+ * Windows), so an arm64 and an x64 macOS checkout cannot coexist in
+ * node_modules. Its installer also exits early whenever the file already
+ * exists, so a binary left over from the other architecture would be packed
+ * silently. Check the real architecture and drop the file when it differs, so
+ * the caller re-downloads the requested one.
+ */
+function ensureFfmpegArchitecture(ffmpegPath, targetPlatform, targetArch) {
+  if (!fs.existsSync(ffmpegPath)) return 'missing'
+  const architectures = readBinaryArchitectures(ffmpegPath)
+  if (architectures.includes(targetArch)) return 'match'
+  console.log(
+    `[prepare-electron-runtime] ffmpeg-static is ${
+      architectures.join('/') || 'not a native binary'
+    } but ${targetPlatform}-${targetArch} was requested; replacing it`
+  )
+  fs.rmSync(ffmpegPath, { force: true })
+  return 'replaced'
+}
+
 function prepareFfmpegRuntime(targetPlatform = process.platform, targetArch = process.arch) {
  let packageRoot = ''
  try {
@@ -31,10 +57,11 @@ function prepareFfmpegRuntime(targetPlatform = process.platform, targetArch = pr
  } catch {
    return
  }
-  const executable = targetPlatform === 'win32' ? 'ffmpeg.exe' : 'ffmpeg'
+  const executable = ffmpegExecutableName(targetPlatform)
  const ffmpegPath = path.join(packageRoot, executable)
+  const architectureState = ensureFfmpegArchitecture(ffmpegPath, targetPlatform, targetArch)

-  if (!fs.existsSync(ffmpegPath)) {
+  if (architectureState !== 'match') {
    const installScript = path.join(packageRoot, 'install.js')
    console.log(
      `[prepare-electron-runtime] downloading ffmpeg-static for ${targetPlatform}-${targetArch}`
@@ -83,4 +110,6 @@ function main() {
  }
 }

-main()
+if (require.main === module) main()
+
+module.exports = { ensureFfmpegArchitecture, ffmpegExecutableName, prepareFfmpegRuntime }
@@ -0,0 +1,436 @@
+/*
+ * wechat_chatter runtime integration
+ *
+ * Upstream: https://github.com/yincongcyincong/wechat_chatter
+ * Runtime version: v0.0.18
+ * Upstream license: GNU General Public License version 3 (GPL-3.0)
+ *
+ * This file applies local compatibility patches to the upstream
+ * onebot/script.js. See docs/third-party/wechat-chatter/NOTICE.md.
+ */
+
+/* eslint-disable @typescript-eslint/explicit-function-return-type, @typescript-eslint/no-require-imports */
+const { execFileSync } = require('node:child_process')
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+
+const release = 'v0.0.18'
+const asset = 'onebot_mac_arm64.tar.gz'
+const url = `https://github.com/yincongcyincong/wechat_chatter/releases/download/${release}/${asset}`
+const projectRoot = path.resolve(__dirname, '..')
+const outputDir = path.join(
+  projectRoot,
+  'resources',
+  'connectors',
+  'wechat-personal',
+  'darwin-arm64'
+)
+const archive = path.join(os.tmpdir(), `wechat-chatter-${release}-${asset}`)
+const appleSilicon =
+  process.platform === 'darwin' &&
+  execFileSync('/usr/sbin/sysctl', ['-n', 'hw.optional.arm64'], { encoding: 'utf8' }).trim() === '1'
+
+if (!appleSilicon) {
+  throw new Error('个人微信发送运行时当前仅支持 macOS arm64')
+}
+
+fs.mkdirSync(outputDir, { recursive: true })
+let archiveReady = false
+if (fs.existsSync(archive)) {
+  try {
+    execFileSync('/usr/bin/tar', ['-tzf', archive], { stdio: 'ignore' })
+    archiveReady = true
+    console.log(`[wechat-personal] 复用已下载归档：${archive}`)
+  } catch {
+    // The archive is partial or invalid; curl will resume it below.
+  }
+}
+if (!archiveReady) {
+  console.log(`[wechat-personal] 下载 ${release}，支持断点续传：${archive}`)
+  execFileSync(
+    '/usr/bin/curl',
+    ['--http1.1', '-L', '--fail', '--retry', '3', '--continue-at', '-', '--output', archive, url],
+    { stdio: 'inherit' }
+  )
+}
+
+const extractionDir = fs.mkdtempSync(path.join(os.tmpdir(), 'wechat-chatter-extract-'))
+console.log(`[wechat-personal] 解压并原子安装到 ${outputDir}`)
+try {
+  execFileSync('/usr/bin/tar', ['-xzf', archive, '-C', extractionDir], { stdio: 'inherit' })
+  fs.mkdirSync(path.join(outputDir, 'onebot'), { recursive: true })
+  fs.mkdirSync(path.join(outputDir, 'wechat_version'), { recursive: true })
+  fs.copyFileSync(
+    path.join(extractionDir, 'onebot', 'script.js'),
+    path.join(outputDir, 'onebot', 'script.js')
+  )
+  fs.cpSync(path.join(extractionDir, 'wechat_version'), path.join(outputDir, 'wechat_version'), {
+    recursive: true,
+    force: true
+  })
+  const stagedExecutable = path.join(outputDir, 'onebot', `.onebot-${process.pid}.tmp`)
+  fs.copyFileSync(path.join(extractionDir, 'onebot', 'onebot'), stagedExecutable)
+  fs.chmodSync(stagedExecutable, 0o755)
+  fs.renameSync(stagedExecutable, path.join(outputDir, 'onebot', 'onebot'))
+} finally {
+  fs.rmSync(extractionDir, { recursive: true, force: true })
+}
+
+const executable = path.join(outputDir, 'onebot', 'onebot')
+const script = path.join(outputDir, 'onebot', 'script.js')
+const config = path.join(outputDir, 'wechat_version', '4_1_11_53_mac.json')
+for (const required of [executable, script, config]) {
+  if (!fs.existsSync(required)) throw new Error(`运行时文件缺失：${required}`)
+}
+
+function patchPerSendPayload(scriptPath) {
+  let source = fs.readFileSync(scriptPath, 'utf8')
+  if (!source.includes('var activeTriggerX1Payload = ptr(0);')) return
+
+  const activeSend = `    const payloadData = hexToByteArray(payloadHex);
+    activeTriggerX1Payload = Memory.alloc(payloadData.length);
+    activeTriggerX1Payload.writeByteArray(payloadData);
+    activeTriggerX1Payload.add(0x18).writePointer(info.cgiAddr);
+    activeTriggerX1Payload.add(0xb8).writePointer(activeTriggerX1Payload.add(0xc0));
+    activeTriggerX1Payload.add(0x190).writePointer(activeTriggerX1Payload.add(0x198));`
+  const upstreamSend = `    const payloadData = hexToByteArray(payloadHex);
+    triggerX1Payload.writeByteArray(payloadData);
+    triggerX1Payload.add(0x18).writePointer(info.cgiAddr);
+    triggerX1Payload.add(0xb8).writePointer(triggerX1Payload.add(0xc0));
+    triggerX1Payload.add(0x190).writePointer(triggerX1Payload.add(0x198));`
+  if (!source.includes(activeSend)) throw new Error('无法定位 wechat_chatter 连续发送补丁位置')
+  source = source
+    .replace(
+      'var triggerX1Payload;\nvar activeTriggerX1Payload = ptr(0);\nvar triggerX0;',
+      'var triggerX1Payload;\nvar triggerX0;'
+    )
+    .replace(activeSend, upstreamSend)
+    .replace(
+      '        MMStartTask(triggerX0, activeTriggerX1Payload);',
+      '        MMStartTask(triggerX0, triggerX1Payload);'
+    )
+    .replace(
+      '        activeTriggerX1Payload = ptr(0);\n        console.error("[!] Error trigger " + msgType + " MMStartTask: " + e);',
+      '        console.error("[!] Error trigger " + msgType + " MMStartTask: " + e);'
+    )
+    .replace(
+      '\t\t\t\tpendingSendMsgType = "";\n\t\t\t\tactiveTriggerX1Payload = ptr(0);\n\t\t\t\treturn',
+      '\t\t\t\tpendingSendMsgType = "";\n\t\t\t\treturn'
+    )
+  fs.writeFileSync(scriptPath, source)
+  console.log('[wechat-personal] 已恢复原生发送 payload 布局')
+}
+
+function patchSendContextCapture(scriptPath, strict = true) {
+  let source = fs.readFileSync(scriptPath, 'utf8')
+  if (source.includes('function isLikelySendContext(')) return
+  const original = `function AttachSendFunc() {
+    Interceptor.attach(sendFuncAddr.add(0x10), {
+        onEnter: function (args) {
+
+            if (triggerX1Payload) {
+                return
+            }
+
+            triggerX0 = this.context.x0;
+            triggerX1Payload = this.context.x1;
+            console.log(\`[+] 捕获到 StartTask 调用，X0：\${triggerX0}, Payload: \${triggerX1Payload}\`);
+        }
+    })
+}`
+  const patched = `function isLikelySendContext(candidateX0, candidateX1) {
+    try {
+        if (!isReadablePointer(candidateX0) || !isReadablePointer(candidateX1)) return false;
+        var manager = readPointerIfReadable(candidateX0.add(0x18));
+        var cgi = readUtf8StringIfReadable(readPointerIfReadable(candidateX1.add(0x18)));
+        console.log("[debug] StartTask candidate x0=" + candidateX0 + " x1=" + candidateX1 + " x0+0x18=" + manager + " cgi=" + cgi);
+        return !manager.equals(ptr(0));
+    } catch (e) {
+        console.error("[debug] StartTask candidate inspect failed: " + e);
+        return false;
+    }
+}
+
+function AttachSendFunc() {
+    Interceptor.attach(sendFuncAddr.add(0x10), {
+        onEnter: function (args) {
+            if (triggerX1Payload) return;
+            var candidateX0 = this.context.x0;
+            var candidateX1 = this.context.x1;
+            if (!isLikelySendContext(candidateX0, candidateX1)) return;
+            triggerX0 = candidateX0;
+            triggerX1Payload = candidateX1;
+            console.log(\`[+] 捕获到有效 StartTask 上下文，X0：\${triggerX0}, Payload: \${triggerX1Payload}\`);
+        }
+    })
+}`
+  if (!source.includes(original)) {
+    if (strict) throw new Error('无法定位 StartTask 上下文 Hook')
+    return
+  }
+  source = source.replace(original, patched)
+  fs.writeFileSync(scriptPath, source)
+}
+
+function patchVoiceAudioBuffer(scriptPath) {
+  let source = fs.readFileSync(scriptPath, 'utf8')
+  if (source.includes('voiceAudioDataAddr = Memory.alloc(audioLen + 1);')) return
+
+  const staticAllocation = 'voiceAudioDataAddr = Memory.alloc(5 * 1024 * 1024); // 预分配5MB'
+  if (!source.includes(staticAllocation)) {
+    throw new Error('无法定位 wechat_chatter 语音缓冲区')
+  }
+  source = source.replace(
+    staticAllocation,
+    'voiceAudioDataAddr = Memory.alloc(1); // 上传前按语音长度重新分配'
+  )
+  const audioLengthMarker = '    const audioLen = audioBytes.length;\n'
+  if (!source.includes(audioLengthMarker)) {
+    throw new Error('无法定位 wechat_chatter 语音上传逻辑')
+  }
+  source = source.replace(
+    audioLengthMarker,
+    `${audioLengthMarker}    voiceAudioDataAddr = Memory.alloc(audioLen + 1);\n`
+  )
+  fs.writeFileSync(scriptPath, source)
+  console.log('[wechat-personal] 已应用按语音长度分配上传缓冲区补丁')
+}
+
+function patchImageHookReadiness(scriptPath) {
+  let source = fs.readFileSync(scriptPath, 'utf8')
+  if (
+    source.includes('捕获到图片上传上下文，uploadGlobalX0') &&
+    source.includes('图片上传 Hook Setup Complete')
+  )
+    return
+  const original = `\t\t\tuploadGlobalX0 = this.context.x0;`
+  const patched = `\t\t\tconst capturedUploadX0 = this.context.x0;
+\t\t\tif (uploadGlobalX0.equals(ptr(0)) && !capturedUploadX0.equals(ptr(0))) {
+\t\t\t\tconsole.log("[+] 捕获到图片上传上下文，uploadGlobalX0：" + capturedUploadX0);
+\t\t\t}
+\t\t\tuploadGlobalX0 = capturedUploadX0;`
+  if (!source.includes(original)) throw new Error('无法定位 wechat_chatter 图片 Hook 状态补丁位置')
+  source = source.replace(original, patched)
+  source = source.replace(
+    '    })\n}\n\n\n\nfunction patchCdnOnComplete()',
+    '    })\n    console.log("[+] 图片上传 Hook Setup Complete.");\n}\n\n\n\nfunction patchCdnOnComplete()'
+  )
+  fs.writeFileSync(scriptPath, source)
+  console.log('[wechat-personal] 已应用图片 Hook 状态补丁')
+}
+
+// Backport of wechat_chatter PR #36 by @Leslielu:
+// https://github.com/yincongcyincong/wechat_chatter/pull/36
+// TraceMemo adds the verified macOS WeChat 4.1.11.53 addresses.
+// macOS WeChat 4.1.11.53, located and verified by TraceMemo
+function patchCdnColdStart(scriptPath) {
+  let source = fs.readFileSync(scriptPath, 'utf8')
+  if (source.includes('function resolveCdnManager()')) return
+
+  const initAddresses = `    uploadImageAddr = baseAddr.add({{.uploadImageAddr}});
+    cndOnCompleteAddr = baseAddr.add({{.cndOnCompleteAddr}});`
+  const patchedInitAddresses = `    uploadImageAddr = baseAddr.add({{.uploadImageAddr}});
+    cndOnCompleteAddr = baseAddr.add({{.cndOnCompleteAddr}});
+    // 冷启动 CdnManager 解析（旧版本缺少可选键时保持 hook 捕获行为）
+    {{if .cdnGetServiceAddr}}cdnGetServiceAddr = baseAddr.add({{.cdnGetServiceAddr}});{{end}}
+    {{if .cdnManagerGetterAddr}}cdnManagerGetterAddr = baseAddr.add({{.cdnManagerGetterAddr}});{{end}}`
+  if (!source.includes(initAddresses)) throw new Error('下载的微信版本配置与当前应用不兼容')
+  source = source.replace(initAddresses, patchedInitAddresses)
+
+  const downloadChunkEnd = `}
+
+function fillUploadX1AndStart`
+  const resolver = `}
+
+// 上传和下载共用同一个 mars::cdn::CdnManager。冷启动时通过服务定位器
+// 取得 [ctx + 0x40]，避免必须先手动发送图片才能让 Hook 捕获上下文。
+function resolveCdnManager() {
+    if (cdnGetServiceAddr.equals(ptr(0)) || cdnManagerGetterAddr.equals(ptr(0))) {
+        return ptr(0);
+    }
+    try {
+        // libc++ SSO 短字符串：数据在 +0，长度写在 +0x17。
+        var strDefault = Memory.alloc(24);
+        strDefault.writeUtf8String("default");
+        strDefault.add(0x17).writeU8(7);
+
+        var getService = new NativeFunction(cdnGetServiceAddr, 'pointer', ['pointer']);
+        var svc = getService(strDefault);
+        if (!isReadablePointer(svc)) {
+            console.error("[!] GetService(\\"default\\") 返回不可读: " + svc);
+            return ptr(0);
+        }
+        var getCtx = new NativeFunction(cdnManagerGetterAddr, 'pointer', ['pointer']);
+        var ctx = getCtx(svc);
+        if (!isReadablePointer(ctx)) {
+            console.error("[!] CdnManager getter 返回不可读: " + ctx);
+            return ptr(0);
+        }
+        var mgr = readPointerIfReadable(ctx.add(0x40));
+        if (!isReadablePointer(mgr)) {
+            console.error("[!] ctx+0x40 管理器指针不可读: ctx=" + ctx);
+            return ptr(0);
+        }
+        return mgr;
+    } catch (e) {
+        console.error("[!] resolveCdnManager 异常: " + e);
+        return ptr(0);
+    }
+}
+
+function ensureCdnManagerX0() {
+    if (uploadGlobalX0.equals(ptr(0)) && downloadGlobalX0 && !downloadGlobalX0.equals(ptr(0))) {
+        uploadGlobalX0 = downloadGlobalX0;
+        console.log("[+] downloadGlobalX0 回填 uploadGlobalX0: " + uploadGlobalX0);
+    }
+    if ((!downloadGlobalX0 || downloadGlobalX0.equals(ptr(0))) && !uploadGlobalX0.equals(ptr(0))) {
+        downloadGlobalX0 = uploadGlobalX0;
+        console.log("[+] uploadGlobalX0 回填 downloadGlobalX0: " + downloadGlobalX0);
+    }
+    if (uploadGlobalX0.equals(ptr(0))) {
+        var mgr = resolveCdnManager();
+        if (!mgr.equals(ptr(0))) {
+            uploadGlobalX0 = mgr;
+            if (!downloadGlobalX0 || downloadGlobalX0.equals(ptr(0))) {
+                downloadGlobalX0 = mgr;
+            }
+            console.log("[+] 冷启动服务定位器解析 CdnManager: " + mgr);
+        }
+    }
+    return !uploadGlobalX0.equals(ptr(0));
+}
+
+function fillUploadX1AndStart`
+  if (!source.includes(downloadChunkEnd)) throw new Error('无法定位 wechat_chatter 媒体上传逻辑')
+  source = source.replace(downloadChunkEnd, resolver)
+
+  const declarations = 'var uploadImageAddr;\n'
+  const patchedDeclarations =
+    'var uploadImageAddr;\nvar cdnGetServiceAddr = ptr(0);\nvar cdnManagerGetterAddr = ptr(0);\n'
+  if (!source.includes(declarations)) throw new Error('无法定位 wechat_chatter 媒体地址声明')
+  source = source.replace(declarations, patchedDeclarations)
+
+  const uploadGuard = `function fillUploadX1AndStart(idAddr, pathAddr, x1Buffer, receiver, md5, filePath, payloadHex) {
+    if (uploadGlobalX0.equals(ptr(0))) {`
+  const patchedUploadGuard = `function fillUploadX1AndStart(idAddr, pathAddr, x1Buffer, receiver, md5, filePath, payloadHex) {
+    if (uploadGlobalX0.equals(ptr(0))) {
+        ensureCdnManagerX0();
+    }
+    if (uploadGlobalX0.equals(ptr(0))) {`
+  if (!source.includes(uploadGuard)) throw new Error('无法定位 wechat_chatter 媒体上传入口')
+  source = source.replace(uploadGuard, patchedUploadGuard)
+
+  const voiceGuard = `function triggerUploadVoice(receiver, voicePath, payloadHex, audioDataHex, durationMs) {
+    if (uploadGlobalX0.equals(ptr(0))) {`
+  const patchedVoiceGuard = `function triggerUploadVoice(receiver, voicePath, payloadHex, audioDataHex, durationMs) {
+    if (uploadGlobalX0.equals(ptr(0))) {
+        ensureCdnManagerX0();
+    }
+    if (uploadGlobalX0.equals(ptr(0))) {`
+  if (!source.includes(voiceGuard)) throw new Error('无法定位 wechat_chatter 语音上传入口')
+  source = source.replace(voiceGuard, patchedVoiceGuard)
+
+  const uploadHook = `\t\t\tuploadGlobalX0 = capturedUploadX0;`
+  const patchedUploadHook = `\t\t\tuploadGlobalX0 = capturedUploadX0;
+            if ((!downloadGlobalX0 || downloadGlobalX0.equals(ptr(0))) && !capturedUploadX0.equals(ptr(0))) {
+                downloadGlobalX0 = capturedUploadX0;
+                console.log("[+] 上传hook回填 downloadGlobalX0: " + downloadGlobalX0);
+            }`
+  if (!source.includes(uploadHook)) throw new Error('无法定位 wechat_chatter 图片 Hook')
+  source = source.replace(uploadHook, patchedUploadHook)
+
+  const downloadHook = `            downloadGlobalX0 = this.context.x0;`
+  const patchedDownloadHook = `            downloadGlobalX0 = this.context.x0;
+            if (uploadGlobalX0.equals(ptr(0)) && !downloadGlobalX0.equals(ptr(0))) {
+                uploadGlobalX0 = downloadGlobalX0;
+                console.log("[+] 下载hook回填 uploadGlobalX0: " + uploadGlobalX0);
+            }`
+  if (!source.includes(downloadHook)) throw new Error('无法定位 wechat_chatter 下载 Hook')
+  source = source.replace(downloadHook, patchedDownloadHook)
+
+  const downloadGuard = `function triggerDownload(receiver, cdnUrl, aesKey, filePath, fileType) {
+    if (!downloadGlobalX0) {`
+  const patchedDownloadGuard = `function triggerDownload(receiver, cdnUrl, aesKey, filePath, fileType) {
+    if (!downloadGlobalX0 || downloadGlobalX0.equals(ptr(0))) {
+        ensureCdnManagerX0();
+    }
+    if (!downloadGlobalX0) {`
+  if (!source.includes(downloadGuard)) throw new Error('无法定位 wechat_chatter 媒体下载入口')
+  source = source.replace(downloadGuard, patchedDownloadGuard)
+
+  fs.writeFileSync(scriptPath, source)
+  console.log('[wechat-personal] 已应用 CdnManager 冷启动解析补丁')
+}
+
+function patchCdnColdStartConfig(configPath) {
+  const source = fs.readFileSync(configPath, 'utf8')
+  let config
+  try {
+    config = JSON.parse(source)
+  } catch {
+    throw new Error('4.1.11.53 版本配置不是有效 JSON')
+  }
+  config.cdnGetServiceAddr = '0x50a15d0'
+  config.cdnManagerGetterAddr = '0x5259290'
+  fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`)
+  console.log('[wechat-personal] 已写入 4.1.11.53 CdnManager 地址')
+}
+
+function patchWechatCoreModuleBase(scriptPath) {
+  let source = fs.readFileSync(scriptPath, 'utf8')
+  if (source.includes('WeChat core module base:')) return
+  const initMarker = 'function initAddresses() {'
+  const initIndex = source.indexOf(initMarker)
+  if (initIndex < 0 || !source.startsWith('var targetPath = ')) {
+    throw new Error('无法定位 wechat_chatter 基址扫描逻辑')
+  }
+  const patchedHeader = `var targetPath = "/Applications/WeChat.app/Contents/Resources/wechat.dylib";
+var module = Process.enumerateModules().find(function(m) {
+    return m.path === targetPath || m.path.endsWith("/Contents/Resources/wechat.dylib");
+});
+if (!module) {
+    throw new Error("[-] Cannot find WeChat core module: " + targetPath);
+}
+var moduleBase = module.base;
+var baseAddr = moduleBase;
+console.log("[+] WeChat core module base: " + baseAddr + " path=" + module.path);
+setImmediate(initAddresses);
+
+`
+  source = patchedHeader + source.slice(initIndex)
+  fs.writeFileSync(scriptPath, source)
+  console.log('[wechat-personal] 已应用微信核心模块基址补丁')
+}
+
+function addModifiedWorkNotice(scriptPath) {
+  let source = fs.readFileSync(scriptPath, 'utf8')
+  if (source.includes('TraceMemo wechat_chatter compatibility modifications')) return
+
+  const notice = `/*
+ * TraceMemo wechat_chatter compatibility modifications
+ * Modified: 2026-08-17
+ * Upstream: https://github.com/yincongcyincong/wechat_chatter
+ * Runtime version: v0.0.18
+ * License: GNU General Public License version 3 (GPL-3.0)
+ * Changes: WeChat module discovery, per-send payload isolation, dynamic voice upload buffers,
+ * CdnManager cold-start resolution, media hook backfill, and image Hook readiness logging.
+ * These modifications are not provided by the upstream author.
+ */
+
+`
+  source = notice + source
+  fs.writeFileSync(scriptPath, source)
+  console.log('[wechat-personal] 已写入 GPL 修改声明')
+}
+
+patchWechatCoreModuleBase(script)
+patchPerSendPayload(script)
+patchSendContextCapture(script)
+patchVoiceAudioBuffer(script)
+patchImageHookReadiness(script)
+patchCdnColdStartConfig(config)
+patchCdnColdStart(script)
+addModifiedWorkNotice(script)
+fs.chmodSync(executable, 0o755)
+console.log('[wechat-personal] 运行时准备完成')
@@ -0,0 +1,37 @@
+/* eslint-disable @typescript-eslint/no-require-imports, @typescript-eslint/explicit-function-return-type */
+const { execFileSync } = require('node:child_process')
+const fs = require('node:fs')
+const path = require('node:path')
+
+const projectRoot = path.resolve(__dirname, '..')
+const defaultRuntimeRoot = path.join(projectRoot, 'node_modules', 'sherpa-onnx-win-x64')
+const requiredFiles = ['package.json', 'sherpa-onnx.node']
+
+function hasWindowsSherpaRuntime(runtimeRoot = defaultRuntimeRoot) {
+  return requiredFiles.every((fileName) => fs.existsSync(path.join(runtimeRoot, fileName)))
+}
+
+function ensureWindowsSherpaRuntime() {
+  if (hasWindowsSherpaRuntime()) {
+    console.log('[prepare-win-runtime] sherpa-onnx-win-x64 is ready')
+    return
+  }
+
+  console.log('[prepare-win-runtime] installing cross-platform optional dependencies')
+  execFileSync(
+    process.platform === 'win32' ? 'pnpm.cmd' : 'pnpm',
+    ['install', '--force', '--ignore-scripts'],
+    {
+      cwd: projectRoot,
+      stdio: 'inherit'
+    }
+  )
+
+  if (!hasWindowsSherpaRuntime()) {
+    throw new Error(`Missing Windows sherpa runtime: ${defaultRuntimeRoot}`)
+  }
+}
+
+if (require.main === module) ensureWindowsSherpaRuntime()
+
+module.exports = { hasWindowsSherpaRuntime, ensureWindowsSherpaRuntime }
@@ -24,10 +24,17 @@ const avatarSvg = (label, color) =>
    `<svg xmlns="http://www.w3.org/2000/svg" width="96" height="96"><rect width="96" height="96" rx="18" fill="${color}"/><text x="48" y="58" text-anchor="middle" font-family="PingFang SC, sans-serif" font-size="36" fill="#0f172a">${label}</text></svg>`
  ).toString('base64')}`

-const localImagePath = '/Users/user/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files/fixture_account_1a2b/temp/RWTemp/2026-07/fixture-image-hash.png'
-const sampleImage = fs.existsSync(localImagePath)
-  ? `data:image/png;base64,${fs.readFileSync(localImagePath).toString('base64')}`
-  : avatarSvg('图', '#dbeafe')
+/**
+ * 可选的本地样例图（用于人工核对图片区块的排版）。
+ *
+ * 走环境变量传入，**不要在源码里写本机路径** —— 微信数据目录会连带暴露
+ * 系统用户名与账号目录名。不传就退回内置的 SVG 头像占位。
+ */
+const localImagePath = process.env.REPORT_FIXTURE_IMAGE || ''
+const sampleImage =
+  localImagePath && fs.existsSync(localImagePath)
+    ? `data:image/png;base64,${fs.readFileSync(localImagePath).toString('base64')}`
+    : avatarSvg('图', '#dbeafe')

 const avatars = {
  阿宇: avatarSvg('宇', '#dcfce7'),
@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+/**
+ * Query Agent POC 快速运行入口：直接执行已构建的 out/main/queryAgentPoc.js，不做任何构建。
+ *
+ * 与 `pnpm poc:query-agent` 的分工：
+ *   - poc:query-agent       : 先 electron-vite build，再运行（代码改动后使用）
+ *   - poc:query-agent:run   : 只运行现有构建产物（连续测试使用）
+ *
+ * 若构建产物不存在，给出明确提示；不会偷偷触发 full build，否则 fast-run 失去意义。
+ *
+ * 可选环境变量：
+ *   TRACEMEMO_POC_ELECTRON  指定 Electron 可执行文件（默认取 node_modules 中的 electron）
+ */
+const fs = require('fs')
+const path = require('path')
+const { spawnSync } = require('child_process')
+
+const repoRoot = path.resolve(__dirname, '..')
+const pocEntry = path.join(repoRoot, 'out', 'main', 'queryAgentPoc.js')
+
+if (!fs.existsSync(pocEntry)) {
+  process.stderr.write(
+    [
+      '',
+      '[poc] POC build 不存在，请先运行：',
+      '        pnpm poc:query-agent "你的问题"',
+      '',
+      `      预期构建产物：${path.relative(repoRoot, pocEntry)}`,
+      '      （本入口有意不自动构建，以免失去快速运行的意义）',
+      ''
+    ].join('\n')
+  )
+  process.exit(1)
+}
+
+// 该入口的目标就是启动 Electron 主进程，因此必须清掉会让 Electron 退化成纯 Node 的标记。
+// 部分 IDE 集成终端会注入 ELECTRON_RUN_AS_NODE=1。
+const env = { ...process.env }
+delete env.ELECTRON_RUN_AS_NODE
+
+// 在普通 Node 中 require('electron') 返回可执行文件路径。
+const electronBinary = env.TRACEMEMO_POC_ELECTRON || require('electron')
+
+const result = spawnSync(electronBinary, [pocEntry, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+  cwd: repoRoot,
+  env
+})
+
+if (result.error) {
+  process.stderr.write(`[poc] 启动 Electron 失败：${result.error.message}\n`)
+  process.exit(1)
+}
+process.exit(typeof result.status === 'number' ? result.status : 1)
@@ -0,0 +1,140 @@
+/*
+ * 测试文件的类型检查棘轮（ratchet）。
+ *
+ * 背景：`tsconfig.node.json` / `tsconfig.web.json` 的 include 都不含 `tests/`，
+ * 所以测试里的类型错误对 `pnpm typecheck` 与 CI 完全不可见——已经积累了一批历史债。
+ *
+ * 策略：**不阻塞既有债，但禁止新增**。
+ *  - 基线按「文件 → 错误数」记录，而不是只记总数：
+ *    否则在 A 文件修掉 1 条、同时在 B 文件新增 1 条会互相抵消，棘轮形同虚设。
+ *  - 某个文件的错误数超过基线即失败；新增了带类型错误的文件同样失败。
+ *  - 需要主动下调基线时用 `--update`（只在确实修好了错误之后）。
+ *
+ * 用法：
+ *   node scripts/typecheck-tests.cjs            # 校验
+ *   node scripts/typecheck-tests.cjs --update   # 用当前结果重写基线
+ */
+/* eslint-disable @typescript-eslint/explicit-function-return-type, @typescript-eslint/no-require-imports */
+const { spawnSync } = require('node:child_process')
+const fs = require('node:fs')
+const path = require('node:path')
+
+const projectRoot = path.resolve(__dirname, '..')
+const configPath = path.join(projectRoot, 'tsconfig.test.json')
+const baselinePath = path.join(projectRoot, 'tests', 'typecheck-baseline.json')
+const ERROR_LINE = /^(.+?)\((\d+),(\d+)\): error (TS\d+): (.*)$/
+const MAX_REPORTED = 20
+
+function runTypeScript() {
+  // 直接用本地 typescript 包，避免依赖 node_modules/.bin 在各平台的差异。
+  const tscPath = require.resolve('typescript/bin/tsc')
+  const result = spawnSync(
+    process.execPath,
+    [tscPath, '--noEmit', '--pretty', 'false', '-p', configPath],
+    { cwd: projectRoot, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 }
+  )
+  if (result.error) throw result.error
+  return `${result.stdout || ''}${result.stderr || ''}`
+}
+
+function relative(file) {
+  const rel = path.relative(projectRoot, path.resolve(projectRoot, file))
+  return rel.split(path.sep).join('/')
+}
+
+/** 解析出「文件 → 错误数」与「文件 → 错误信息列表」。 */
+function collectErrors(output) {
+  const counts = new Map()
+  const details = new Map()
+  for (const line of output.split('\n')) {
+    const match = ERROR_LINE.exec(line.trim())
+    if (!match) continue
+    const file = relative(match[1])
+    counts.set(file, (counts.get(file) ?? 0) + 1)
+    if (!details.has(file)) details.set(file, [])
+    if (details.get(file).length < 3) details.get(file).push(`${match[2]}:${match[3]} ${match[4]}`)
+  }
+  return { counts, details }
+}
+
+function readBaseline() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(baselinePath, 'utf8'))
+    if (parsed && typeof parsed.files === 'object' && parsed.files !== null) return parsed
+  } catch {
+    // 基线缺失或损坏时按「空基线」处理，会在下面明确报错提示。
+  }
+  return null
+}
+
+function total(counts) {
+  let sum = 0
+  for (const value of counts.values()) sum += value
+  return sum
+}
+
+function main() {
+  if (!fs.existsSync(configPath)) {
+    console.error(`[typecheck:test] 缺少 ${path.relative(projectRoot, configPath)}`)
+    process.exit(1)
+  }
+  const { counts, details } = collectErrors(runTypeScript())
+
+  if (process.argv.includes('--update')) {
+    const files = Object.fromEntries([...counts.entries()].sort(([a], [b]) => a.localeCompare(b)))
+    const payload = {
+      note: '测试文件类型检查基线：只允许下降，不允许上升。用 node scripts/typecheck-tests.cjs --update 下调。',
+      total: total(counts),
+      files
+    }
+    fs.mkdirSync(path.dirname(baselinePath), { recursive: true })
+    fs.writeFileSync(baselinePath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8')
+    console.log(
+      `[typecheck:test] 基线已更新：${payload.total} 个错误 / ${Object.keys(files).length} 个文件`
+    )
+    return
+  }
+
+  const baseline = readBaseline()
+  if (!baseline) {
+    console.error(
+      `[typecheck:test] 找不到基线 ${path.relative(projectRoot, baselinePath)}。\n` +
+        '  首次启用请运行：node scripts/typecheck-tests.cjs --update'
+    )
+    process.exit(1)
+  }
+
+  const regressions = []
+  for (const [file, count] of counts) {
+    const allowed = baseline.files[file] ?? 0
+    if (count > allowed) regressions.push({ file, count, allowed })
+  }
+
+  const now = total(counts)
+  const baselineTotal = Number(baseline.total) || 0
+  const improved = baselineTotal - now
+
+  if (regressions.length > 0) {
+    console.error('[typecheck:test] 测试文件出现新的类型错误 ❌')
+    console.error(`  基线 ${baselineTotal} → 当前 ${now}（+${now - baselineTotal}）\n`)
+    let printed = 0
+    for (const item of regressions) {
+      console.error(`  ${item.file}  ${item.allowed} → ${item.count}`)
+      for (const line of details.get(item.file) ?? []) {
+        if (printed >= MAX_REPORTED) break
+        console.error(`      ${line}`)
+        printed += 1
+      }
+    }
+    console.error('\n  修好之后用 --update 下调基线（不要为了过检查而放宽它）。')
+    process.exit(1)
+  }
+
+  console.log(
+    `[typecheck:test] PASS ✅ 当前 ${now} 个既有类型错误 / ${counts.size} 个文件` +
+      (improved > 0 ? `（比基线少 ${improved} 个，可运行 --update 下调）` : '')
+  )
+  console.log('  注意：这是棘轮，只保证「不新增」。修完历史债后可改为阻断式检查。')
+}
+
+main()
@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 fastclaw-ai
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
@@ -1,25 +0,0 @@
-# TraceMemo WeChat Connector
-
-This repository-local service provides the minimal WeChat bridge required by TraceMemo:
-
- QR-code login with a single persisted credential
- account discovery
- inbound long polling and authenticated webhook delivery
- local HTTP health and send endpoints
- text and local/remote media sending
-
-The executable is managed by the Electron main process. It is not a general-purpose agent runtime and does not load external AI command-line tools.
-
-## Commands
-
-```bash
-go run . login --json
-go run . accounts --json
-go run . start --foreground --api-addr 127.0.0.1:18011 --account-id <account-id>
-```
-
-Credential and synchronization state is stored under `~/.wechatexplorer/wechat-connector/accounts`. This legacy directory name is intentionally retained so upgrades can reuse existing accounts. A successful login is written before the older credential and synchronization state are removed, so an incomplete login cannot destroy the last working credential.
-
-## Attribution
-
-Low-level protocol and media transport portions are distributed under the MIT license in [LICENSE](LICENSE). TraceMemo-specific process management, webhook contract, product UI, and Agent Hub behavior live in the surrounding TraceMemo project.
@@ -1,135 +0,0 @@
-package api
-
-import (
-	"context"
-	"encoding/json"
-	"fmt"
-	"log"
-	"net/http"
-
-	"github.com/Wxw-Gu/WechatExplorer/services/wechat-connector/ilink"
-	"github.com/Wxw-Gu/WechatExplorer/services/wechat-connector/messaging"
-)
-
-// Server provides an HTTP API for sending messages.
-type Server struct {
-	clients []*ilink.Client
-	addr    string
-}
-
-// NewServer creates an API server.
-func NewServer(clients []*ilink.Client, addr string) *Server {
-	if addr == "" {
-		addr = "127.0.0.1:18011"
-	}
-	return &Server{clients: clients, addr: addr}
-}
-
-// SendRequest is the JSON body for POST /api/send.
-type SendRequest struct {
-	AccountID string `json:"account_id,omitempty"`
-	To        string `json:"to"`
-	Text      string `json:"text,omitempty"`
-	MediaURL  string `json:"media_url,omitempty"` // image/video/file URL
-}
-
-// Run starts the HTTP server. Blocks until ctx is cancelled.
-func (s *Server) Run(ctx context.Context) error {
-	mux := http.NewServeMux()
-	mux.HandleFunc("/api/send", s.handleSend)
-	mux.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
-		w.WriteHeader(http.StatusOK)
-		fmt.Fprintln(w, "ok")
-	})
-
-	srv := &http.Server{Addr: s.addr, Handler: mux}
-
-	go func() {
-		<-ctx.Done()
-		srv.Shutdown(context.Background())
-	}()
-
-	log.Printf("[api] listening on %s", s.addr)
-	if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
-		return err
-	}
-	return nil
-}
-
-func (s *Server) handleSend(w http.ResponseWriter, r *http.Request) {
-	if r.Method != http.MethodPost {
-		http.Error(w, "POST only", http.StatusMethodNotAllowed)
-		return
-	}
-
-	var req SendRequest
-	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
-		http.Error(w, "invalid JSON: "+err.Error(), http.StatusBadRequest)
-		return
-	}
-
-	if req.To == "" {
-		http.Error(w, `"to" is required`, http.StatusBadRequest)
-		return
-	}
-	if req.Text == "" && req.MediaURL == "" {
-		http.Error(w, `"text" or "media_url" is required`, http.StatusBadRequest)
-		return
-	}
-
-	if len(s.clients) == 0 {
-		http.Error(w, "no accounts configured", http.StatusServiceUnavailable)
-		return
-	}
-
-	client := s.clientForAccount(req.AccountID)
-	if client == nil {
-		http.Error(w, "requested account is not available", http.StatusNotFound)
-		return
-	}
-	ctx := r.Context()
-
-	// Send text if provided
-	if req.Text != "" {
-		if err := messaging.SendTextReply(ctx, client, req.To, req.Text, "", ""); err != nil {
-			log.Printf("[api] send text failed: %v", err)
-			http.Error(w, "send text failed: "+err.Error(), http.StatusInternalServerError)
-			return
-		}
-		log.Printf("[api] sent text to %s: %q", req.To, req.Text)
-
-		// Extract and send any markdown images embedded in text
-		for _, imgURL := range messaging.ExtractImageURLs(req.Text) {
-			if err := messaging.SendMediaFromURL(ctx, client, req.To, imgURL, ""); err != nil {
-				log.Printf("[api] send extracted image failed: %v", err)
-			} else {
-				log.Printf("[api] sent extracted image to %s: %s", req.To, imgURL)
-			}
-		}
-	}
-
-	// Send media if provided
-	if req.MediaURL != "" {
-		if err := messaging.SendMediaFromURL(ctx, client, req.To, req.MediaURL, ""); err != nil {
-			log.Printf("[api] send media failed: %v", err)
-			http.Error(w, "send media failed: "+err.Error(), http.StatusInternalServerError)
-			return
-		}
-		log.Printf("[api] sent media to %s: %s", req.To, req.MediaURL)
-	}
-
-	w.Header().Set("Content-Type", "application/json")
-	json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
-}
-
-func (s *Server) clientForAccount(accountID string) *ilink.Client {
-	if accountID == "" {
-		return s.clients[0]
-	}
-	for _, client := range s.clients {
-		if client.BotID() == accountID {
-			return client
-		}
-	}
-	return nil
-}
@@ -1,20 +0,0 @@
-package api
-
-import (
-	"testing"
-
-	"github.com/Wxw-Gu/WechatExplorer/services/wechat-connector/ilink"
-)
-
-func TestClientForAccountSelectsMatchingBot(t *testing.T) {
-	oldClient := ilink.NewClient(&ilink.Credentials{ILinkBotID: "bot-old"})
-	newClient := ilink.NewClient(&ilink.Credentials{ILinkBotID: "bot-new"})
-	server := NewServer([]*ilink.Client{oldClient, newClient}, "")
-
-	if got := server.clientForAccount("bot-new"); got != newClient {
-		t.Fatal("clientForAccount did not select the requested account")
-	}
-	if got := server.clientForAccount("missing"); got != nil {
-		t.Fatal("clientForAccount should reject an unknown account")
-	}
-}
@@ -1,8 +0,0 @@
-module github.com/Wxw-Gu/WechatExplorer/services/wechat-connector
-
-go 1.23.0
-
-require (
-	github.com/google/uuid v1.6.0
-	rsc.io/qr v0.2.0
-)
@@ -1,4 +0,0 @@
-github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
-github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
-rsc.io/qr v0.2.0 h1:6vBLea5/NRMVTz8V66gipeLycZMl/+UlFmk8DvqQ6WY=
-rsc.io/qr v0.2.0/go.mod h1:IF+uZjkb9fqyeF/4tlBoynqmQxUoPfWEKh921coOuXs=
@@ -1,236 +0,0 @@
-package ilink
-
-import (
-	"context"
-	"encoding/json"
-	"fmt"
-	"os"
-	"path/filepath"
-	"strings"
-	"time"
-)
-
-const (
-	qrCodeURL       = "https://ilinkai.weixin.qq.com/ilink/bot/get_bot_qrcode?bot_type=3"
-	qrStatusURL     = "https://ilinkai.weixin.qq.com/ilink/bot/get_qrcode_status?qrcode="
-	statusWait      = "wait"
-	statusScanned   = "scaned"
-	statusConfirmed = "confirmed"
-	statusExpired   = "expired"
-)
-
-// FetchQRCode retrieves a new QR code for login.
-func FetchQRCode(ctx context.Context) (*QRCodeResponse, error) {
-	c := NewUnauthenticatedClient()
-	var resp QRCodeResponse
-	if err := c.doGet(ctx, qrCodeURL, &resp); err != nil {
-		return nil, fmt.Errorf("fetch QR code: %w", err)
-	}
-	return &resp, nil
-}
-
-// PollQRStatus polls for QR code scan status until confirmed or expired.
-// It calls onStatus for each status change so the caller can display progress.
-func PollQRStatus(ctx context.Context, qrcode string, onStatus func(status string)) (*Credentials, error) {
-	c := NewUnauthenticatedClient()
-	url := qrStatusURL + qrcode
-
-	for {
-		select {
-		case <-ctx.Done():
-			return nil, ctx.Err()
-		default:
-		}
-
-		pollCtx, cancel := context.WithTimeout(ctx, 40*time.Second)
-		var resp QRStatusResponse
-		err := c.doGet(pollCtx, url, &resp)
-		cancel()
-
-		if err != nil {
-			// Timeout is normal for long-poll, retry
-			if ctx.Err() != nil {
-				return nil, ctx.Err()
-			}
-			continue
-		}
-
-		if onStatus != nil {
-			onStatus(resp.Status)
-		}
-
-		switch resp.Status {
-		case statusConfirmed:
-			creds := &Credentials{
-				BotToken:    resp.BotToken,
-				ILinkBotID:  resp.ILinkBotID,
-				BaseURL:     resp.BaseURL,
-				ILinkUserID: resp.ILinkUserID,
-			}
-			return creds, nil
-		case statusExpired:
-			return nil, fmt.Errorf("QR code expired")
-		case statusWait, statusScanned:
-			// Continue polling
-		default:
-			// Unknown status, continue
-		}
-	}
-}
-
-func accountsDir(rootName string) (string, error) {
-	home, err := os.UserHomeDir()
-	if err != nil {
-		return "", err
-	}
-	return filepath.Join(home, rootName, "wechat-connector", "accounts"), nil
-}
-
-// AccountsDir returns the TraceMemo directory where new credentials are stored.
-func AccountsDir() (string, error) {
-	return accountsDir(".tracememo")
-}
-
-// LegacyAccountsDir is read-only compatibility for v2.1.9 and earlier.
-func LegacyAccountsDir() (string, error) {
-	return accountsDir(".wechatexplorer")
-}
-
-func accountDirectoryForID(accountID string) (string, error) {
-	current, err := AccountsDir()
-	if err != nil {
-		return "", err
-	}
-	if _, err := os.Stat(filepath.Join(current, accountID+".json")); err == nil {
-		return current, nil
-	}
-	legacy, err := LegacyAccountsDir()
-	if err != nil {
-		return "", err
-	}
-	if _, err := os.Stat(filepath.Join(legacy, accountID+".json")); err == nil {
-		return legacy, nil
-	}
-	return current, nil
-}
-
-// NormalizeAccountID converts raw bot ID to filesystem-safe format.
-func NormalizeAccountID(raw string) string {
-	s := raw
-	for _, ch := range []string{"@", ".", ":"} {
-		s = filepath.Clean(s)
-		s = replaceAll(s, ch, "-")
-	}
-	return s
-}
-
-func replaceAll(s, old, new string) string {
-	for {
-		i := indexOf(s, old)
-		if i < 0 {
-			return s
-		}
-		s = s[:i] + new + s[i+len(old):]
-	}
-}
-
-func indexOf(s, sub string) int {
-	for i := range s {
-		if i+len(sub) <= len(s) && s[i:i+len(sub)] == sub {
-			return i
-		}
-	}
-	return -1
-}
-
-// SaveCredentials saves the latest credentials and removes older accounts.
-// The new credential is written first so a failed login never destroys the
-// previously working credential.
-func SaveCredentials(creds *Credentials) error {
-	dir, err := AccountsDir()
-	if err != nil {
-		return err
-	}
-	if err := os.MkdirAll(dir, 0o700); err != nil {
-		return fmt.Errorf("create accounts dir: %w", err)
-	}
-
-	id := NormalizeAccountID(creds.ILinkBotID)
-	path := filepath.Join(dir, id+".json")
-
-	data, err := json.MarshalIndent(creds, "", "  ")
-	if err != nil {
-		return fmt.Errorf("marshal credentials: %w", err)
-	}
-
-	if err := os.WriteFile(path, data, 0o600); err != nil {
-		return fmt.Errorf("write credentials: %w", err)
-	}
-
-	entries, err := os.ReadDir(dir)
-	if err != nil {
-		return fmt.Errorf("prune old credentials: %w", err)
-	}
-	keepPrefix := id + "."
-	for _, entry := range entries {
-		if entry.IsDir() || strings.HasPrefix(entry.Name(), keepPrefix) {
-			continue
-		}
-		if filepath.Ext(entry.Name()) != ".json" {
-			continue
-		}
-		if err := os.Remove(filepath.Join(dir, entry.Name())); err != nil && !os.IsNotExist(err) {
-			return fmt.Errorf("remove old credential %s: %w", entry.Name(), err)
-		}
-	}
-	return nil
-}
-
-func loadCredentialsFromDir(dir string) ([]*Credentials, error) {
-	entries, err := os.ReadDir(dir)
-	if err != nil {
-		if os.IsNotExist(err) {
-			return nil, nil
-		}
-		return nil, fmt.Errorf("read accounts dir: %w", err)
-	}
-
-	var result []*Credentials
-	for _, e := range entries {
-		if e.IsDir() || filepath.Ext(e.Name()) != ".json" {
-			continue
-		}
-		data, err := os.ReadFile(filepath.Join(dir, e.Name()))
-		if err != nil {
-			continue
-		}
-		var creds Credentials
-		if json.Unmarshal(data, &creds) == nil && creds.BotToken != "" {
-			result = append(result, &creds)
-		}
-	}
-	return result, nil
-}
-
-// LoadAllCredentials loads TraceMemo credentials first and falls back to the
-// untouched WechatExplorer directory for one-version upgrade compatibility.
-func LoadAllCredentials() ([]*Credentials, error) {
-	current, err := AccountsDir()
-	if err != nil {
-		return nil, err
-	}
-	credentials, err := loadCredentialsFromDir(current)
-	if err != nil || len(credentials) > 0 {
-		return credentials, err
-	}
-	legacy, err := LegacyAccountsDir()
-	if err != nil {
-		return nil, err
-	}
-	return loadCredentialsFromDir(legacy)
-}
-
-// CredentialsPath returns the path for display purposes.
-func CredentialsPath() (string, error) {
-	return AccountsDir()
-}
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
wuyouMaster	7ebd4b8376	fix: make packaging checks platform safe	2026-09-20 18:05:12 +08:00
wuyouMaster	5a54202383	fix: ad-hoc sign packaged macOS key helpers and app bundle electron-builder 26 skips macOS signing entirely when no Developer ID identity is configured, so the packaged key helpers can ship unsigned or with a broken signature and macOS kills them even with SIP disabled. afterPack now verifies and ad-hoc re-signs the packaged xkey helpers and the outer app bundle, failing the build when a signature cannot be repaired.	2026-09-20 17:52:38 +08:00
qingmao	c1224cb612	Merge pull request #45 from mmhh256/fix/query-agent-system-messages fix: 合并 Query Agent 的连续 system messages	2026-09-20 16:11:08 +08:00
Wxw-Gu	5036639aa1	test: 测试用例	2026-09-20 15:56:27 +08:00
Wxw-Gu	9593ca0f54	fix: 修复语音消息取错、时长精度与转写不刷新 - 时长解析：改取 <voicemsg voicelength>（毫秒），不再误取 length（SILK 字节数） - 时长显示：四舍五入对齐微信口径，有原生时长时不被解码时长覆盖 - 转写：重新识别改为强制重算，跳过身份级缓存短路（音频级缓存仍生效） - 日报：语音累计秒数显示取整，不再出现小数	2026-09-20 15:40:01 +08:00
mmhh256	b441287d54	fix: 合并 Query Agent 的连续 system messages	2026-09-19 14:01:39 +08:00
Wxw-Gu	9b82d29037	fix: 兼容微信新版系统消息模板格式，入群通知不再显示成「撤销」	2026-09-18 14:41:50 +08:00
Wxw-Gu	0f270366aa	feat: 图片文字索引按时间分段优先处理最近图片 - 首次索引先处理最近 7 天，再依次回溯 30 天 / 近一年 / 更早历史 - 完成后新到的图片单独补齐，不受历史回填影响 - 覆盖度增加时间维度，可区分「最近已完整」与「更早仍在补齐」	2026-09-18 14:39:05 +08:00
Wxw-Gu	12b8fb34c6	fix: 增加sip文案	2026-09-18 09:38:33 +08:00
Wxw-Gu	774346d503	fix: 日报头像补齐下载重试	2026-09-17 19:24:27 +08:00
Wxw-Gu	b97e1f4bc6	fix: 问问微信恢复引用编号，日报修复成员头像与 hero 溢出 - 问问微信：Host 分配稳定 citationId 并注入模型上下文，正文 [E#] 与证据按钮同号 - 问问微信：回答返回前校验引用，幻觉编号移除并提示，不再出现不可信的引用按钮 - Agent Hub：收紧「最近会话」快捷路由，内容查询交回 Query Agent	2026-09-17 18:56:32 +08:00
Wxw-Gu	4b2395a8d2	feat: 重写agent hub连接器，新增对话记录和微信输入状态 - 新增 Agent Hub 对话记录面板，按会话回看机器人与微信用户的完整收发内容 - 新增微信原生正在输入状态，长任务维持 typing，异常路径强制收尾	2026-09-17 17:32:37 +08:00
Wxw-Gu	1337bcb7de	feat: 新增mac ocr转文字，增加到问一问微信图片索引优化速度 - 图片文字索引性能与进度诚实化 - 问问微信：证据卡区分「消息类型」与「派生来源」，派生命中内容自报来源 - 问问微信：回答规则禁止未真实执行的多轮承诺 - 本地图片文字识别：支持 macOS 系统 OCR（Apple Vision）	2026-09-17 13:11:20 +08:00
电摇小子	b8f08d54c8	feat: 新增微信图片文字索引与问问微信图片检索能力	2026-09-16 10:42:52 +08:00
电摇小子	24399f1d70	feat: 新增 Windows 本地图片文字识别能力	2026-09-16 00:23:23 +08:00
Wxw-Gu	e6db4de711	chore: 提升版本号修改文案, 以及 macos 首次登录页面文案修改	2026-09-15 16:47:56 +08:00
Wxw-Gu	adff6021fc	test: 修改测试用例	2026-09-15 15:32:40 +08:00
qingmao	75004375df	Merge pull request #41 from Wxw-Gu/codex/develop-xkey-4-1-13 Codex/develop xkey 4 1 13	2026-09-15 15:23:47 +08:00
qingmao	75de616527	Merge pull request #42 from yimizilu/fix/http-image-media-identifiers fix: prevent HTTP image media ID collisions across conversations	2026-09-15 14:57:26 +08:00
Wxw-Gu	f5158fd3e4	feat: 完全支持 mac Intel 环境抽离 Intel 专用包、connector 与跨架构语音库修改 publish 脚本，发布先落草稿修复重装依赖后 Electron 二进制缺失	2026-09-15 14:12:00 +08:00
Wxw-Gu	ed4c21a68f	docs: 新增提交规范	2026-09-15 11:41:53 +08:00
Wxw-Gu	f35ca1778a	docs: 移除已下线的防撤回说明	2026-09-15 11:26:11 +08:00
Wxw-Gu	21b2b57d28	feat: 隐藏设置里的防撤回入口，历史开启强制收敛为 false	2026-09-15 11:26:06 +08:00
Wxw-Gu	67dc45819e	feat: 修改社区模板市场入口放到日报二级菜单下, 增加跳转github	2026-09-15 11:03:00 +08:00
Wxw-Gu	ff212d594c	fix: 增加手动复制退群信息以及设置页面文案	2026-09-15 10:36:09 +08:00
yimizilu	353df30ff8	fix: align media errors and serialize bigint server IDs	2026-09-15 08:28:19 +08:00
yimizilu	4f8435d0e2	fix: scope HTTP image media handles to database and conversation	2026-09-15 08:03:05 +08:00
Wxw-Gu	389a853560	fix: 日报截图窗口隐藏化、搜索缓存兼容读取与定时日报单测等待窗口	2026-09-14 22:25:55 +08:00
wuyouMaster	c437be349e	fix: preserve legacy macOS key capture	2026-09-14 18:44:15 +08:00
wuyouMaster	488966d771	fix: expose macOS login-time key detection	2026-09-14 18:20:20 +08:00
wuyouMaster	00095ae627	feat: add WeChat 4.1.13 macOS key capture	2026-09-14 18:20:11 +08:00
Wxw-Gu	ffbe78f74a	test: 测试用例	2026-09-14 18:09:43 +08:00
Wxw-Gu	7e9a79486e	test: 测试用例	2026-09-14 17:41:55 +08:00
Wxw-Gu	4191d4d5f5	test: 固定本地时间标签的测试时区	2026-09-14 17:17:23 +08:00
Wxw-Gu	29c1166eca	fix: 按本机时区和可变模板目录收口测试	2026-09-14 17:11:45 +08:00
Wxw-Gu	bf78055b69	fix: 收口发布候选版本的时间和配置问题	2026-09-14 16:58:53 +08:00
Wxw-Gu	550e3b104c	feat: 抽离保留进程功能到设置里	2026-09-14 16:44:53 +08:00
Wxw-Gu	cf9ea8a83b	feat: 优化 macOS 微信发送消息能力参考 wechat_chatter PR #36： https://github.com/yincongcyincong/wechat_chatter/pull/36 补充 WeChat 4.1.11.53 的 GetService / CdnManager 地址，并适配绑定后的发送能力检测逻辑。	2026-09-14 15:59:08 +08:00
qingmao	5efae86fcf	Merge pull request #35 from huangzhenhao90/fix/opencode-go-session-header fix(ai): 修复 OpenCode Go 缺少会话 header 导致日报生成失败	2026-09-14 10:05:18 +08:00
电摇小子	70c55442f3	feat: 支持Mac Intel获取密钥，提供完整支持	2026-09-13 20:08:40 +08:00
Wxw-Gu	9288256a5e	feat: 支持mac intel	2026-09-13 13:39:03 +08:00
Wxw-Gu	e5bd162a01	fix: 优化微信发送日志展示	2026-09-13 11:22:47 +08:00
Wxw-Gu	cef1ad493c	feat: 实时刷新档案会话列表收到新消息后增量更新会话摘要和时间自动按最新消息重新排序并保留当前选择状态	2026-09-13 11:15:30 +08:00
Wxw-Gu	add16885fe	fix: 修复导出日期、语音和联系人名字问题 - 导出的 HTML：点月份先看日期，选中日期后才跳到对应消息。 - 语音转文字：不同账号、不同聊天里的语音不会再串到一起。 - 联系人名字：正常昵称显示不变；昵称异常时使用可见的备注或账号，导出文件名也能正常使用。	2026-09-13 11:15:30 +08:00
Wxw-Gu	ab3b3731b7	feat: 重构问问微信并完善知识库增量检索统一问问微信与 Agent Hub 的查询链路完善查询覆盖度、新鲜度和部分结果表达，避免索引滞后产生错误结论基于会话实现真正的增量追新与历史补齐支持后台同步、取消恢复、重启续传以及同步期间继续查询优化知识库跨会话检索、同步状态、进度展示和侧栏布局	2026-09-11 17:44:48 +08:00
Wxw-Gu	0c4932d740	feat: 完善agent查询和检索	2026-09-11 10:32:21 +08:00
Wxw-Gu	fe8619d56d	fix: 完善查询agent时间与检索契约增加调试与诊断	2026-09-10 17:45:12 +08:00
Wxw-Gu	376ea79ff6	feat: 优化问问微信工具规划	2026-09-10 15:35:12 +08:00
Wxw-Gu	dc6d1eb6ac	fix: 修复查询工具消息引用与参数校验	2026-09-10 11:10:47 +08:00
Wxw-Gu	532e135406	chore: 更换main分支二维码	2026-09-10 09:38:54 +08:00
Wxw-Gu	7ae0d63a7f	feat: 新增本地查询模型调用	2026-09-10 09:35:42 +08:00
Wxw-Gu	c759bcd30e	feat: 退群监控增加重新发送功能	2026-09-09 17:58:14 +08:00
Wxw-Gu	0bad419150	feat: 新增本地微信查询工具 API	2026-09-09 16:52:39 +08:00
Wxw-Gu	facc292443	feat: 完善问问微信查询理解与检索链路	2026-09-09 16:51:31 +08:00
Wxw-Gu	7554de7d72	feat: 新增日报生产片段 UI 契约与视觉保护	2026-09-09 11:17:29 +08:00
Wxw-Gu	1bc66e33fd	docs: README	2026-09-08 17:58:30 +08:00
Wxw-Gu	976aac32c5	feat: 日报新增模板市场，支持社区模板安装与使用	2026-09-08 11:37:38 +08:00
zhenhao	3634f49a48	fix(ai): send stable session headers for OpenCode Go	2026-09-07 15:07:22 +08:00
Wxw-Gu	1156362c3c	test: 完善 2.3.0 跨平台测试与 CI 稳定性 - 修复 Windows 与 macOS 单元测试环境差异\n- 完善组件、集成与 Electron E2E 测试\n- 修复异步等待、平台路径和环境依赖问题\n- 统一 E2E 窗口尺寸与 Visual 测试策略\n- 提升 GitHub Actions 跨平台 CI 稳定性	2026-09-05 10:38:41 +08:00
Wxw-Gu	60528ffe53	Merge branch 'develop' of github.com:Wxw-Gu/TraceMemo into develop	2026-09-04 17:52:53 +08:00
Wxw-Gu	f28480ffbe	docs: 整理文档	2026-09-04 17:52:49 +08:00
qingmao	8e784d8125	Merge pull request #33 from Lazy-CZ/fix/export-audio-fix fix: 修复批量导出 wav 音频语速变快、音调升高（采样率不匹配）问题	2026-09-04 16:14:35 +08:00
yy2257	3489535750	test: 恢复表情导出保护并补充语音回归测试	2026-09-04 15:55:22 +08:00
$DESKTOP-QMBPBO5\Lazy$ DESKTOP-QMBPBO5\Lazy	5e268cd8f4	fix: 修复导出的音频文件变调、变速的问题	2026-09-04 15:09:06 +08:00
Wxw-Gu	454f449c41	feat: 统一手动发送入口为文字转语音 - 移除普通文本、图片和本地语音的手动发送入口 - 保留文字转语音的生成、试听和发送能力	2026-09-04 15:05:04 +08:00
电摇小子	517e650942	fix: 修复用户已加载的历史记录数量	2026-09-04 10:45:41 +08:00
电摇小子	21e299942b	refactor: 重构一下档案搜索功能支持拼音微信号等	2026-09-03 23:38:12 +08:00
Wxw-Gu	bde3bc537f	Merge branch 'develop' of github.com:Wxw-Gu/TraceMemo into develop	2026-09-03 18:12:34 +08:00
Wxw-Gu	719ffa0a24	feat: 优化档案搜索与头像新增退群监控开关发送限速	2026-09-03 18:12:29 +08:00
qingmao	8fa4dd50e7	Merge pull request #31 from njueeRay/fix/windows-v4-image-key-derivation fix: derive Windows image keys from local metadata	2026-09-03 17:53:15 +08:00
电摇小子	3462d49516	perf: 重构退群监控，持久化快照并降低 CPU 占用 - 持久化群成员 - 支持 TraceMemo 重启后恢复离线期间的退群检测 - 使用 Batch Membership 替代逐群成员查询 - 降低大量群聊监控时的 CPU 和数据库查询开销	2026-09-03 01:50:34 +08:00
Ray	7ef991aa67	fix: derive Windows image keys from local metadata	2026-09-03 01:00:37 +08:00
电摇小子	4d758b2aca	Merge branch 'main' into develop	2026-09-02 19:45:45 +08:00
Wxw-Gu	27f4108cf9	feat: 统一发送能力接入退群通知与定时日报	2026-09-02 19:43:30 +08:00
电摇小子	4075e52eec	Merge branch 'main' of https://github.com/Wxw-Gu/WechatExplorer	2026-09-02 19:42:24 +08:00
电摇小子	f7d619292b	chore: 更新二维码	2026-09-02 19:10:13 +08:00
Wxw-Gu	e1f4ec79dd	feat: 建立发送网关与动作审计	2026-09-02 18:00:39 +08:00
Wxw-Gu	76e9e683c4	chore: 统一日报时间逻辑	2026-09-02 16:02:05 +08:00
Wxw-Gu	7c8b45a24a	feat: 修复定时日报错误通知微信机器人功能增加定时日报debug 修复定时日报历史头像显示并区分定时日报标题	2026-09-02 15:01:03 +08:00
Wxw-Gu	1c8bbae1f0	fix: 增加thinking disabled 修改退群监控模板定时日报保存日报历史	2026-09-01 11:40:14 +08:00
电摇小子	25b72c3d76	feat: 定时日报支持Windows	2026-09-01 11:36:15 +08:00
Wxw-Gu	f65dc4ac32	feat: 刷新消息列表时间改为350ms	2026-08-31 23:27:22 +08:00
Wxw-Gu	e59332b514	feat: 增加退群监控功能	2026-08-31 21:06:53 +08:00
Wxw-Gu	6cbf9af662	feat: mac语音转换silk格式修复	2026-08-31 10:55:52 +08:00
电摇小子	5acfa14475	feat：增加windows发送能力抽离功能到设置页面抽离文字转语音功能	2026-08-31 02:44:24 +08:00
Wxw-Gu	698251796f	feat: 增加一个查找语音文件	2026-08-28 15:04:37 +08:00
Wxw-Gu	a007e110ac	feat: 扩展 Skill 支持定时日报操作	2026-08-27 20:27:51 +08:00
Wxw-Gu	7cf043e3c3	feat: 完善定时日报	2026-08-27 19:03:07 +08:00
Wxw-Gu	949e6bc868	feat: 新增定时日报与微信发送能力底座	2026-08-27 17:08:09 +08:00
Wxw-Gu	62abd872ee	Merge branch 'develop' of https://github.com/Wxw-Gu/WechatExplorer into develop	2026-08-27 14:45:48 +08:00
Wxw-Gu	0d68217dda	fix: 修复转换微信语音发送逻辑	2026-08-27 14:43:09 +08:00
qingmao	ee5f50db83	Merge pull request #25 from Wxw-Gu/nanin/develop 修复部分自定义表情导出后图裂的问题	2026-08-27 09:55:58 +08:00
Nanin	36e709d7a6	修复部分自定义表情导出后图裂的问题校验应用缓存、微信 Emoticon 缓存及 CDN 响应的真实图片格式，无效缓存自动回退下载。增量导出会识别并替换旧归档中的无效表情资源；刷新失败时移除破图引用并保留明确错误。补充 StickerService 单元测试和 HTML 媒体增量导出回归测试。	2026-08-26 22:17:25 +08:00
qingmao	b26d4dd1a7	Merge pull request #24 from ZipperWang/main 添加response API支持，添加流式传输支持	2026-08-26 17:29:54 +08:00
Zipper_Wang	8f9a0c44da	Merge upstream origin/main	2026-08-26 16:49:47 +08:00
Wxw-Gu	7016ca1237	chore: 提升版本	2026-08-26 15:34:46 +08:00
Wxw-Gu	fc42b18f4a	feat: 本地api增加图片理解	2026-08-26 15:21:05 +08:00
Wxw-Gu	1e25ae4065	feat: 修改发送消息流程	2026-08-26 11:23:45 +08:00
Wxw-Gu	d26af6462f	Merge branch 'main' into develop	2026-08-26 09:37:32 +08:00
Wxw-Gu	9dee0bbd3c	feat: 增加更新页	2026-08-25 21:07:25 +08:00
Zipper_Wang	5ff67edaef	feat: 支持 OpenAI Responses API	2026-08-25 17:15:07 +08:00
Wxw-Gu	eec6286a58	fix: 修复样式, 调用接口方法	2026-08-25 15:14:30 +08:00
Wxw-Gu	47e0d7cd1e	fix: 更新打包配置并修复群昵称刷新更新跨平台 WCDB 和运行时命名。优化消息获取速度修复群昵称刷新回退与消息发送者显示，并增加可控的消息读取诊断日志和有界查询优化。	2026-08-25 14:26:29 +08:00
电摇小子	fc54c3b946	chore: 优化windows打包	2026-08-25 11:52:52 +08:00
Wxw-Gu	a0c8696987	chore: 移除没用的包	2026-08-21 17:23:49 +08:00
Wxw-Gu	77e7e54949	Merge branch 'develop' of https://github.com/Wxw-Gu/WechatExplorer into develop	2026-08-21 17:00:41 +08:00
longhuan1999andqingmao	ce27829811	fix(ai): 让严格执行`max_tokens`的API恢复工作，如DeepSeek (#19 ) * fix(ai): 让严格执行`max_tokens`的API恢复工作，如DeepSeek - AI 请求优先使用当前模型配置的`Max Tokens`，并依次回退到供应商高级设置的`Max Tokens`和默认值 4096 - 透传`OpenAI-compatible`与`Anthropic`的结束原因，补充`preload`类型声明 - 群日报生成和修复遇到模型异常结束生成时终止处理，并针对token上限给出配置提示 - 优化 AI 未返回有效内容时的错误信息 - 统一行尾配置 Signed-off-by: longhuan1999 <2114467924@qq.com> * Update .gitignore --------- Signed-off-by: longhuan1999 <2114467924@qq.com> Co-authored-by: qingmao <84499436+Wxw-Gu@users.noreply.github.com>	2026-08-21 16:52:19 +08:00
Wxw-Gu	17e3b51629	fix: 加固退出清理退出应用时终止后台进程移除运行时动态安装 Python 依赖	2026-08-21 15:37:01 +08:00
Wxw-Gu	313d0afff7	feat: 优化全局 UI 交互与页面视觉体验统一按钮、输入框、选择控件和开关的交互状态优化日报、导出、设置、Agent Hub 和 API Center 的UI 完善组件、单元及 Electron E2E 测试	2026-08-21 15:05:06 +08:00
Wxw-Gu	c83d109a75	feat: 统一按钮	2026-08-21 00:07:00 +08:00
Wxw-Gu	72d2b17842	feat: 统一界面视觉规范并优化导出交互	2026-08-20 20:13:23 +08:00
Wxw-Gu	d93caa3539	refactor(ui): 统一迁移原生按钮、输入框及交互控件	2026-08-20 10:18:59 +08:00
Wxw-Gu	49d4e17d67	feat: 完成 UI 基础层与核心页面迁移	2026-08-19 17:43:07 +08:00
Wxw-Gu	c0b710e56f	refactor: 抽离 AI 搜索运行生命周期	2026-08-18 17:46:14 +08:00
Wxw-Gu	d23a83d066	fix: 优化windows多目录报错	2026-08-18 17:34:50 +08:00
Wxw-Gu	10ea43dc9f	refactor: 拆分 AI 搜索证据集合 Hook	2026-08-18 17:29:31 +08:00
Wxw-Gu	c7f2105495	refactor: 拆分 AI 搜索知识库与授权 Hook	2026-08-18 17:07:07 +08:00
Wxw-Gu	14f3b85865	feat: 拆分代码	2026-08-18 16:49:25 +08:00
Wxw-Gu	e75e2ebb5e	test: 添加AISearch测试回归	2026-08-18 15:49:49 +08:00
Wxw-Gu	316b8c7583	feat: 新增组件库	2026-08-18 15:29:13 +08:00
Wxw-Gu	c89c108098	fix: 修复 AI 检索 Evidence 覆盖与加载更多问题修复问一问微信查询遗漏群聊的问题区分会话覆盖与发送者覆盖策略新增问一问微信加载更多功能	2026-08-18 14:19:28 +08:00
Wxw-Gu	4058a817dd	feat: 新增MAC微信发送消息文字转语音功能	2026-08-17 18:16:14 +08:00
				`@@ -0,0 +1 @@`
				`a35d3fa67387e049cc30bc073f9e65b077aa1db9c5c2b183125dec695fa013b9 xkey_helper_4_1_13`