docs: 更新文档

2026-08-17 03:27:00 +08:00 · 2026-08-07 22:52:56 +08:00
parent a73af3b5ad
commit cd2c3cfaee
24 changed files with 1175 additions and 992 deletions
@@ -1,372 +1,64 @@
 ---
 name: wechatexplorer-reader
-description: 通过本地 HTTP API 读取 WechatExplorer 解锁后的微信聊天数据(本地服务由 WechatExplorer.app 提供)。当用户提到微信聊天记录、群消息、看看群里说了什么、查一下微信、分析微信对话、总结群聊等场景时,使用此技能。注意:此技能的数据源是用户本机 WechatExplorer app。
+description: 通过 WechatExplorer 本地 HTTP API 按需读取用户有权访问的微信聊天数据。当用户要求查看微信消息、查找联系人或群聊、总结聊天、生成群聊总结时使用。此 Skill 由本机 WechatExplorer 提供数据，不是 MCP Server。
 ---

 # WechatExplorer Reader

-通过本地 HTTP API(`http://127.0.0.1:6131`)读取 WechatExplorer 已经解锁的微信数据库内容。
+你是一个通过本机 WechatExplorer 读取微信历史的 Agent。先确认用户已经在 WechatExplorer 中完成数据库连接，再按需调用 API；不要假设数据库已就绪，也不要声称读取了没有调用过的消息。

-## 数据源
+## 连接信息

- **本服务由 WechatExplorer.app 提供**,数据完全在本地处理,不会上传任何服务器
- 用户必须在 WechatExplorer 主窗口完成**首次密钥配置**(解锁 WCDB 数据库)
- 默认监听 `127.0.0.1:6131`,仅本机可访问
- 除 health 外的 API 均要求 Bearer Token。Token 获取路径:WeChatExplorer → API Center → API Token → 显示/复制 Token
+- Base URL 默认是 `http://127.0.0.1:6131/api/v1`。
+- `GET /health` 不需要 Token。
+- 其他端点必须带 `Authorization: Bearer $WECHATEXPLORER_API_TOKEN`。
+- Token 由用户在 WechatExplorer → API Center 显示/复制，并放在 Agent 自己的本地环境中。
+- 不要把 Token 放到 URL、回答、日志、Skill 文件或仓库。
+- 6131 是普通 Local HTTP API，不是 MCP Server；不要生成 `mcpServers` 配置。

-## 前置条件
+## 每次任务前

-1. **安装并启动 WechatExplorer.app**(从项目 release 页面下载)
-2. **首次启动时完成密钥配置**:在主界面第一步输入微信数据库密钥(64 位 hex),完成 WCDB 初始化
-3. **如需 7×24 提供 API**:用 `WXE_TRAY=1` 或 `--tray` 参数启动 app,启用菜单栏常驻模式(主窗口关闭后服务仍在)
+1. 调用 `/health`，确认服务和数据库状态。
+2. 用户说“今天”“昨天”“本周”等相对时间时，先调用 `/current_time`，按返回的本机时区换算日期。
+3. 用 `/resolve`、`/contact` 或 `/chatroom` 确认会话标识。
+4. 用 `/chatlog` 读取最小必要的时间范围。
+5. 对重要结论读取关键消息前后文；不要只凭一次宽范围粗查回答。

-## Authentication
+## 端点速查

-WechatExplorer Reader 使用的是 **WechatExplorer Local HTTP API**,不是 MCP Server。
+| 方法 | 路径 | 用途 |
+| --- | --- | --- |
+| 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` | 已连接机器人发送测试 |

-1. 在 WechatExplorer 中打开 **API Center**。
-2. 在 **API Token** 区域点击“复制 Token”。
-3. 把 Token 保存到 Agent 自己的本地环境配置中:
+## 时间与上下文规则

-```bash
-export WECHATEXPLORER_API_TOKEN="<YOUR_API_TOKEN>"
-```
+`/chatlog` 的 `time` 支持 `YYYY-MM-DD`、日期闭区间和分钟范围；也可以使用 Unix 秒级 `startTime`/`endTime`。时间按 WechatExplorer 所在机器的本机时区解释。

-health 可以不带 Token:
+当用户问“某个话题是谁说的、后来结论是什么”时，先定位会话和时间，再读取关键消息前后文。回答时区分：

-```bash
-curl http://127.0.0.1:6131/api/v1/health
-```
+- 原消息明确写出的内容；
+- 根据多条消息整理出的总结；
+- 没有来源支持的推断。

-除 health 外,所有请求必须使用标准 Bearer header:
+## 隐私和安全

-```bash
-curl -H "Authorization: Bearer $WECHATEXPLORER_API_TOKEN" \
-  http://127.0.0.1:6131/api/v1/recent_chat
-```
+只读取用户请求所需的会话和时间范围。不要把完整聊天数据库、密钥或 Token 暴露给用户。Reader API 本身不自动把聊天转发到外部服务器，但当前 Agent 可能会把工具结果交给其配置的模型；如有疑问，提醒用户检查 Agent 的数据策略。

-本文件后续写出的所有 `GET` / `POST` 数据请求都默认包含上述 Authorization header。禁止把 Token 放入 URL query、路径、Skill 文件或仓库。
+## 常见错误

-## API 列表
-
-GET 用于读取数据,`POST /api/v1/report` 用于生成群日报(HTML + 长图)。所有端点返回 JSON。
-
-| 端点                         | 用途                                  | 关键参数                                                          |
-| ---------------------------- | ------------------------------------- | ----------------------------------------------------------------- |
-| `GET /api/v1/health`         | 健康检查 + 是否已初始化               | —                                                                 |
-| `GET /api/v1/current_time`   | 获取当前本地时间(用于"今天/昨天"换算) | —                                                                 |
-| `GET /api/v1/contact`        | 联系人 / 群聊列表                     | `filter`(昵称模糊)、`type`(`user` \| `group`)                     |
-| `GET /api/v1/chatroom`       | 群聊列表(等同 contact?type=group)     | `keyword`                                                         |
-| `GET /api/v1/recent_chat`    | 最近会话                              | `limit`(默认 50)                                                  |
-| `GET /api/v1/chatlog`        | 聊天记录                              | `talker`、`time` 或 `startTime`/`endTime`                         |
-| `GET /api/v1/group_snapshot` | 群成员快照                            | `md5`                                                             |
-| `GET /api/v1/resolve`        | 把昵称/wxid/md5 解析成 md5            | `q`                                                               |
-| `POST /api/v1/report`        | 生成群聊日报 HTML + 长图 PNG          | JSON body(见下文,推荐传 `metadata.talker` 让服务端自动反推真头像) |
-
-### `talker` 参数可接受的值
-
-`chatlog` 和 `recent_chat` 的 `talker` / 列表项 ID 支持以下三种形式,服务端会按 `nickname → wxid → md5` 顺序匹配:
-
-1. **群昵称 / 好友备注**(模糊匹配,如 `技术交流`、`摸鱼群`)
-2. **微信 wxid**(如 `wxid_abc123`、`gh_xxxxx@chatroom`)
-3. **会话 md5**(如 `49023470180@chatroom` 的 md5 哈希,可在 `contact` 接口里看到)
-
-不确定时先调 `GET /api/v1/resolve?q=<输入>` 校验,返回 `{ md5, m_nsUsrName, m_nsNickName, type, ... }`。
-
-### `chatroom` 与 `contact?type=group` 字段一致性
-
-`/chatroom` 和 `/contact?type=group` 返回的是**同一个集合**(都是 `listContacts().filter(type==='group')`),字段也完全一致:
-
-```json
-{
-  "m_nsUsrName": "49023470180@chatroom", // wxid, 用作 chatlog 的 talker
-  "m_nsNickName": { "buffer": "...", "type": "Buffer" }, // nickname 原 buffer
-  "type": "group",
-  "md5": "..."
-}
-```
-
-需要 `displayName` 时从 `m_nsNickName` 里解析;需要拉消息就传 `m_nsUsrName` 当 talker。
-
-## 时间范围格式(`time` 参数)
-
-支持以下格式:
-
-| 输入                                | 含义                         |
-| ----------------------------------- | ---------------------------- |
-| `2026-07-03`                        | 单日 00:00:00 ~ 23:59:59     |
-| `2026-07-01~2026-07-03`             | 日期范围(闭区间)             |
-| `2026-07-03/14:30`                  | 单分钟(从 14:30:00 起 60 秒) |
-| `2026-07-03/14:30~2026-07-03/15:30` | 精确到分钟的范围             |
-
-也可以直接传 unix 秒级时间戳作为 `startTime` 和 `endTime`。
-
-### "今天 / 昨天 / 本周" 的时区语义
-
-所有 `time` / `startTime` / `endTime` 都按**用户本机时区**解析(由 `current_time` 里的 `timezone` 字段给出,典型为 `Asia/Shanghai`)。含义如下:
-
- "今天 2026-07-03" → 本机 2026-07-03 00:00:00 ~ 23:59:59(北京时间 24 小时),**不是** UTC 当天
- "昨天" → 本机昨天 0 点 ~ 23:59:59
- "本周" → 本周一 0 点 ~ 当前时刻(按本机时区所在周的周一)
-
-跨时区时(如用户在国外):仍以本机时区为准,需要按 UTC 处理时显式传 unix 时间戳。
-
-## 时间预检工作流(Time-Aware Workflow)
-
-**重要**:只要用户请求中包含"今天"、"昨天"、"本周"、"刚才"等相对时间概念,**禁止**直接生成日期字符串。
-
-**步骤 1**:先调用 `current_time` 工具获取本地 RFC3339 时间。
-**步骤 2**:根据返回的时间计算对应的 `time` 参数。
-**步骤 3**:用计算后的参数调 `chatlog`。
-
-示例:
-
- 用户: "今天 摸鱼交流群 聊了啥?"
- AI: 先 `GET /api/v1/current_time` → 得到 `2026-07-03T14:30:00+08:00` → 计算 `time=2026-07-03` → `GET /api/v1/chatlog?talker=摸鱼交流群&time=2026-07-03`
-
-## 多步上下文检索(强制)
-
-当查询特定话题或特定发送者发言时,**必须**按以下流程操作:
-
-1. **初步定位**:用 `contact` 或 `chatroom` 端点确定群聊 md5 / wxid
-2. **粗查**:用 `chatlog` + 较宽时间范围找到相关消息时间点
-3. **精查**:对每个关键时间点分别查前后 15-30 分钟(不带任何 keyword 过滤),用完整上下文分析
-
-**禁止**:仅凭一次粗查结果直接回答用户。
-
-## 生成群日报(POST /api/v1/report)
-
-当用户希望输出**可视化群日报**(长图 PNG + HTML 邮件版)时,用这个端点。WechatExplorer 内置 `mobile_daily_report.html` 模板,渲染后会同时落盘 `htmlPath` 和 `pngPath`,并返回 `imageDataUrl` 可直接预览。
-
-### 请求体(`GroupReportExportRequest`)
-
-```json
-{
-  "report": {
-    "overview": "一句话总览,20-80 字",
-    "topics": [
-      {
-        "title": "话题标题",
-        "timeRange": "10:00-12:30",
-        "heat": "高", // "高" | "中" | "低"
-        "participants": ["张三", "李四"],
-        "summary": "本话题讨论了什么",
-        "conclusion": "可选,达成的结论",
-        "keywords": ["关键词1", "关键词2"]
-      }
-    ],
-    "resources": [{ "title": "链接/文件标题", "description": "为什么重要", "sender": "张三" }],
-    "importantMessages": [
-      { "sender": "张三", "time": "10:23", "content": "原消息文本", "note": "为什么重要" }
-    ],
-    "quotes": [
-      {
-        "messages": [
-          { "sender": "李四", "content": "原话1" },
-          { "sender": "王五", "content": "原话2" }
-        ],
-        "note": "为什么这些话值得引用"
-      }
-    ],
-    "qa": [{ "question": "Q", "answer": "A", "answerer": "解答人(可选)" }],
-    "unresolved": [
-      {
-        "question": "待跟进问题",
-        "owner": "相关人(可选)",
-        "status": "待跟进",
-        "note": "为什么还没结束"
-      }
-    ],
-    "storylines": [
-      {
-        "title": "剧情线",
-        "stages": [{ "time": "10:12", "event": "提出问题" }],
-        "result": "可选结果"
-      }
-    ],
-    "reversals": [
-      { "topic": "某话题", "initialView": "最初判断", "finalView": "最终判断", "note": "可选说明" }
-    ],
-    "participantChains": [
-      { "topic": "某话题", "chain": ["A 提出", "B 补充", "C 收尾"], "note": "可选说明" }
-    ],
-    "analytics": {
-      "topicHeat": [{ "topic": "话题1", "score": 9.5 }],
-      "activeTimeline": "10:00-12:00 为最活跃时段",
-      "topSpeakers": [{ "name": "张三", "count": 58 }],
-      "voiceLeaderboard": [{ "sender": "张三", "count": 3, "durationSec": 97 }]
-    },
-    "keywords": ["高频词1", "高频词2"],
-    "hero": {
-      "headline": "一句抓重点的日报标题",
-      "summary": "一句概览",
-      "keyTakeaway": "最重要结论",
-      "pendingNote": "待跟进事项"
-    }
-  },
-  "metadata": {
-    "groupName": "技术交流",
-    "reportDate": "2026-07-03",
-    "dateRange": "2026-07-03 全天",
-    "messageCount": 1234,
-    "activeUsers": 56,
-    "timeSpan": "00:00-23:59",
-    "generatedAt": "2026-07-03 22:00",
-    "recordNote": "本日报由 WechatExplorer 自动生成",
-    "footerNote": "底部附加说明",
-    "heroParticipants": ["张三", "李四"],
-    "avatars": {},
-    "talker": "技术交流",
-    "timeRange": "2026-07-03"
-  }
-}
-```
-
-### 响应(`GroupReportExportResult`)
-
-```json
-{
-  "success": true,
-  "htmlPath": "/Users/.../Desktop/技术交流_日报_2026-07-03.html",
-  "pngPath": "/Users/.../Desktop/技术交流_日报_2026-07-03.png",
-  "imageDataUrl": "data:image/png;base64,iVBORw0K..."
-}
-```
-
-成功返回 200;失败返回 500 + `{ success: false, error: "..." }`。HTML 和 PNG 用 `mobile_daily_report.html` 模板渲染,长图宽度自适应移动端预览。
-
-### 典型工作流
-
-1. 调 `current_time` + `chatlog` 拉取当天/目标时间段消息
-2. LLM 总结生成 `report` + `metadata`(直接走 AI 总结即可,无需自己造数据)
-3. POST 到 `/api/v1/report` 拿到 `htmlPath` / `pngPath`,把文件路径告诉用户即可在 Finder 打开
-4. **不要**自己拼 HTML/PNG,模板已内置,只需组织好 report/metadata 字段
-
-### 必填字段与隐式约束(踩坑提示)
-
-`metadata` 的以下字段**必填**,缺一返回 500:
-
- `groupName`、`reportDate`、`dateRange`、`generatedAt`
- `heroParticipants`:数组,模板会把每个名字当 key 去 `metadata.avatars[name]` 取头像图
- `avatars`:对象,**每个 `heroParticipants` 里的名字都必须有这个 key**(没有就传 `""`,**不要省略整段**),否则模板渲染会抛 `Cannot read properties of undefined (reading '<名字>')` 报 500
-
-`report` 的以下字段**必须存在**(空就传 `[]`,**不能省略**),否则模板遍历时会抛 `Cannot read properties of undefined (reading 'map')` 报 500:
-
- `report.topics`(至少 1 个,完全没话题就改用纯文本总结,不要硬生成空日报)
- `report.resources`
- `report.importantMessages`
- `report.quotes`
- `report.qa`
- `report.analytics.topicHeat`
- `report.analytics.topSpeakers`(至少 1 个)
- `report.keywords`
-
-最小安全示例:
-
-```json
-{
-  "report": {
-    "overview": "...",
-    "topics": [],
-    "resources": [],
-    "importantMessages": [],
-    "quotes": [],
-    "qa": [],
-    "analytics": { "topicHeat": [], "activeTimeline": "", "topSpeakers": [] },
-    "keywords": []
-  },
-  "metadata": {
-    "groupName": "技术交流",
-    "reportDate": "2026-07-07",
-    "dateRange": "2026-07-07 全天",
-    "heroParticipants": ["张三", "李四"],
-    "avatars": { "张三": "", "李四": "" }
-  }
-}
-```
-
-`report.importantMessages[].time` 用 `HH:mm` 格式(不要 ISO 时间戳);`report.analytics.topicHeat[].score` 数字 0-10。
-
-### 4 个数字格子的内容必须紧凑(避免塌陷)
-
-模板顶部的 4 个统计格(`消息数 / 活跃人数 / 时间跨度 / 主要话题`)宽度均分,内容过长会被截断或换行:
-
-| 字段                     | 推荐格式                                            | 反例(会撑爆格子)                       |
-| ------------------------ | --------------------------------------------------- | -------------------------------------- |
-| `metadata.messageCount`  | 纯数字 `"1234"`                                     | `"约 1.2k 条"`                         |
-| `metadata.activeUsers`   | 纯数字 `"56"`                                       | `"大约 50 多人"`                       |
-| `metadata.timeSpan`      | **持续时长紧凑半角** `"1 h"` / `"30 min"` / `"2 d"` | `"1 小时"` / `"7 小时"` / `"1天3小时"` |
-| `metadata.topicCount` 等 | 数字 / 短中文                                       | 长句子                                 |
-
-`timeSpan` 是**首条到末条消息的持续时长**,不是时间区间。**单位用半角空格分隔**:
-
- `< 1 h` → `"30 min"`
- `1~24 h` → `"1 h"` / `"7 h"`(整数,向上取整)
- `> 24 h` → `"2 d"`(整数,向上取整)
-
-**首末条消息的具体时间点**:`dateRange` 字段会显示完整日期 + 起止时间(无长度限制),模板里 dateRange 是 hero 区的副标题,跟 stat 格子分开。
-
-**区间叙事**(如"主要集中在上午 10 点-12 点")放 `report.analytics.activeTimeline`,那是模板里单独一段的描述,不被 stat 格子限制。
-
-**不传 timeSpan**:服务端会用空字符串渲染(stat 格会空),subagent 应当总是算好时长填进来,或者 renderer 端会自动算(见 renderer 源码)。
-
-### 头像:服务端自动反推(推荐)
-
-**v1.4 起无需手动拼 `avatars` 字典**。在 `metadata` 里加 `talker`(群昵称/wxid/md5 都行),服务端会用 `getGroupSnapshot` 拉全量群成员,按 `nickname → avatar` 自动反推填进 `metadata.avatars`。LLM 总结里出现的 `heroParticipants` / `topics[].participants` / `topSpeakers[].name` 等所有名字都会被覆盖。
-
-**优先级**:客户端传的 `avatars[name]`(非空字符串) > 服务端反推 > 占位 SVG(姓名首字母 + 随机色块)。
-
-**回退**:不传 `talker` 时按 `metadata.avatars` 字典取;还取不到则生成 SVG 占位(`fallbackAvatar`),**不会变空白方块**(v1.4 修了 data URL 正则,SVG 占位能正常嵌入)。
-
-**手动覆盖**:仍可传 `avatars` 字典强制使用自定义头像,例如 `{"张三": "data:image/jpeg;base64,..."}`。
-
-**P2 风险**:群里有两人同名(如"杨伟")时,服务端只取首条;客户端可手动覆盖。
-
-## 隐私安全原则
-
-1. **最小化原则**:只返回用户明确请求的内容,不过度展开无关聊天
-2. **本地处理**:所有数据来自用户本机,API 不缓存、不转发
-3. **摘要优先**:对于大量聊天记录,先提供摘要而非完整 dump
-4. **用户确认**:涉及敏感内容时,先展示摘要,让用户决定是否继续深入
-
-## 典型工作流示例
-
-**示例 1:今日群聊总结(纯文本)**
-
-1. `GET /api/v1/current_time` → 获取今天日期
-2. `GET /api/v1/chatroom?keyword=技术交流` → 找到目标群 md5
-3. `GET /api/v1/chatlog?talker=技术交流&time=2026-07-03` → 拉取今天的聊天
-4. AI 用 LLM 生成总结报告(话题 TOP N、最活跃发言者等)
-
-**示例 2:搜索特定消息上下文**
-
-1. `GET /api/v1/chatlog?talker=摸鱼群&time=2026-07-01~2026-07-03` → 粗查近 3 天
-2. 在返回的消息中定位关键词出现的时间点 T1, T2, ...
-3. 对每个 Ti 分别查 `chatlog?talker=摸鱼群&time=Ti-15min~Ti+15min`,分析上下文
-
-**示例 3:群日报(可视化长图)**
-
-1. `GET /api/v1/chatlog?talker=技术交流&time=2026-07-03` → 拉今天聊天
-2. LLM 按上方 `GroupDailyReport` schema 总结出 `report` + `metadata`
-3. `POST /api/v1/report` body = 上述 JSON → 拿到 `htmlPath` / `pngPath` / `imageDataUrl`
-4. 把 `imageDataUrl` 给用户预览,把 `pngPath` 路径告诉用户用 Finder 打开
-
-## 错误处理
-
- `401 unauthorized` → Token 缺失、格式错误、已被重新生成或配置不正确;请回到 API Center 复制当前 Token
- `503` → WechatExplorer 未初始化(密钥未配置),提示用户在主窗口完成配置
- `404 talker not found` → talker 不存在,先调 `contact` 或 `resolve` 确认 md5/wxid
- `400 missing required parameter` → 检查必填参数(talker / md5 / q)
- `200` 但 `result.warnings: ['enrich skipped: talker "X" not found']` → `/report` 的 `metadata.talker` 解析失败,头像走 SVG fallback(不阻断生成)
- `200` 但 `result.warnings: ['enriched N member avatars from snapshot (M members)']` → enrich 成功(诊断用)
- `400 请求体为空 / 需包含 report 和 metadata` → 调用 `/report` 时 body 必须是非空 JSON,且有这两个顶层字段
- `500 success=false` → 模板渲染失败,通常因 `report` 字段缺失或 `metadata.groupName/reportDate` 为空,检查后重试
-
-## 配置 Codex / Claude Code / OpenClaw
-
- **Codex**:安装本 Skill,并在启动 Codex 的本地 shell 或项目私有环境中设置 `WECHATEXPLORER_API_TOKEN`。
- **Claude Code**:安装本 Skill,并在启动 Claude Code 的本地 shell 或私有环境配置中设置 `WECHATEXPLORER_API_TOKEN`。
- **OpenClaw**:安装本 Skill,把 `WECHATEXPLORER_API_TOKEN` 放入 OpenClaw 自己的本地 secret / environment 配置。
- **其他 Agent**:确保执行 HTTP 请求的本地进程能读取 `WECHATEXPLORER_API_TOKEN`。
-
-不要把 `http://127.0.0.1:6131` 配置成 `mcpServers.url`;6131 提供的是 Local HTTP API,不是 MCP Server。
+- `401`：Token 缺失、错误或被轮换；请用户回 API Center 复制最新 Token。
+- `403`：浏览器 Origin 不在 loopback 允许列表；CLI/Agent 通常不带 Origin。
+- `404`：先用 `/resolve` 确认会话标识。
+- `503`：用户还没有完成数据库连接或对应服务未就绪。
+- 空结果：缩小/扩大时间范围，确认账号和会话，再检查媒体或语音是否可读。