WechatExplorer/docs/skill/tracememo-reader/SKILL.md

---
name: tracememo-reader
description: 通过 TraceMemo 本地 HTTP API 按需读取用户有权访问的微信聊天数据和图片媒体，并管理定时日报任务。当用户要求查看微信消息、查找联系人或群聊、总结聊天、查看或理解图片、生成群聊总结、查询或修改定时日报时使用。此 Skill 由本机 TraceMemo 提供数据，不是 MCP Server。
---

# TraceMemo Reader

你是一个通过本机 TraceMemo 读取微信历史的 Agent。先确认用户已经在 TraceMemo 中完成数据库连接，再按需调用 API；不要假设数据库已就绪，也不要声称读取了没有调用过的消息。

## 连接信息

- Base URL 默认是 `http://127.0.0.1:6131/api/v1`。
- `GET /health` 不需要 Token。
- 其他端点必须带 `Authorization: Bearer $TRACEMEMO_API_TOKEN`。
- 新配置优先读取 `TRACEMEMO_API_TOKEN`；为兼容已安装的旧 Reader，可在新变量缺失时回退到 `WECHATEXPLORER_API_TOKEN`。
- Token 由用户在 TraceMemo → API Center 显示/复制，并放在 Agent 自己的本地环境中。
- 不要把 Token 放到 URL、回答、日志、Skill 文件或仓库。
- 6131 是普通 Local HTTP API，不是 MCP Server；不要生成 `mcpServers` 配置。

## 每次任务前

1. 调用 `/health`，确认服务和数据库状态。
2. 用户说“今天”“昨天”“本周”等相对时间时，先调用 `/current_time`，按返回的本机时区换算日期。
3. 用 `/resolve`、`/contact` 或 `/chatroom` 确认会话标识。
4. 用 `/chatlog` 读取最小必要的时间范围。
5. 对重要结论读取关键消息前后文；不要只凭一次宽范围粗查回答。

## 端点速查

| 方法   | 路径                                                    | 用途                                              |
| ------ | ------------------------------------------------------- | ------------------------------------------------- |
| 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`                    |
| POST   | `/query/messages`                                       | 按目标与时间范围取消息（结构化，不调用 AI）       |
| POST   | `/query/search`                                         | 受限语义关键词检索（依赖本地索引，见 freshness）  |
| POST   | `/query/message-context`                                | 用 `messageRef` 取某条消息的前后文                |
| POST   | `/query/conversation-overview`                          | 按会话与时间范围提取可总结的证据                  |
| GET    | `/query/capabilities`                                   | Query 端点能力目录                                |
| 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   | `/scheduled-reports/executions/:executionId/retry-send` | 复用已有 PNG 重试发送                             |
| POST   | `/report`                                               | 将已有日报结构渲染为 HTML/PNG                     |
| GET    | `/agent/status`                                         | Agent Hub、连接器和数据库状态                     |
| POST   | `/agent/group-report`                                   | 按群和 `today`/`yesterday`/`7days` 生成总结图片   |
| POST   | `/agent/send`                                           | 已连接机器人发送测试（文字或本地图片）            |

这个 API **不只是只读的**：`/report` 会渲染并写文件，`/agent/send` 会真的发出微信消息，`/scheduled-reports*` 会创建、修改、删除或立刻执行定时任务。这些调用都要先确认用户意图；`DELETE` 与 `/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"`，告诉用户相同任务已经存在，不要再次创建。能力状态不是 `ready` 时（`unsupported`、`unconfigured`、`needs_binding`、`initializing` 或 `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`。

## 时间与上下文规则

`/chatlog` 的 `time` 支持 `YYYY-MM-DD`、日期闭区间和分钟范围；也可以使用 Unix 秒级 `startTime`/`endTime`。时间按 TraceMemo 所在机器的本机时区解释。

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

- 原消息明确写出的内容；
- 根据多条消息整理出的总结；
- 没有来源支持的推断。

## 结构化查询（query/\*）

需要按目标 + 时间范围稳定取数时，优先使用 `query/*`，而不是自己拼 `chatlog`：

- `query/messages`：按 `target`、`timeRange`、`direction`、`messageTypes` 取消息；
- `query/search`：受限语义关键词检索，依赖本地索引；
- `query/message-context`：用返回的 `messageRef` 取前后文；
- `query/conversation-overview`：按会话与时间范围提取可总结的证据。

两个要点：

- `messageRef` 是服务端生成的不透明引用，**不要**自行构造 wxid、md5 或数据库路径；
- `query/search` 依赖异步建立的本地索引。`coverage.state` 不是 `complete` 且 `evidence` 为空时，只能说“这段范围暂时无法确认”，**不能**下“没有找到”的结论。

## 媒体消息

当 `/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 的数据策略。

## 常见错误

- `401`：Token 缺失、错误或被轮换；请用户回 API Center 复制最新 Token。
- `403`：浏览器 Origin 不在 loopback 允许列表；CLI/Agent 通常不带 Origin。
- `404`：会话查询失败时先用 `/resolve` 确认会话标识；媒体请求表示标识未登记、已过期、有歧义，或图片文件不存在（`NOT_FOUND`）。先重新读取 `/chatlog` 并使用新的 `media.url`；若仍失败，再检查本地图片文件是否存在。
- `422`：媒体标识格式错误，或消息不是可读取的图片（`NOT_IMAGE`）。
- `503`：用户还没有完成数据库连接或对应服务未就绪。
- 空结果：缩小/扩大时间范围，确认账号和会话，再检查媒体或语音是否可读。