Yige 74184056c4 fix(mail-operations): 按现行邮件服务路由修正技能文档（1.0.6） (#194) ...

## 背景 / Background

发票整理 Agent 在隔离开发实例里真机整理 QQ 邮箱时，按内置技能 `mail-operations` 的写法调用 IMAP
附件下载，拿到 400 `Missing required parameters`：技能写的请求体是 `{email, uid, folder,
partId}`，而 `POST /imap/attachment` 从 2026-03 创建起就只认 `{email, messageId,
attachmentId, folder?}`。顺着这一处，对照 desirecore origin/dev（`c1e2c5ac0`）的
`lib/mail-service/` 与 `MailOperations` 工具把整份技能逐条核对了一遍。

While a real-mailbox run of the invoice agent was downloading QQ Mail
attachments, the builtin `mail-operations` skill's IMAP attachment body
(`{email, uid, folder, partId}`) returned 400; the route has always
taken `{email, messageId, attachmentId, folder?}`. This PR re-audits the
whole skill against the current mail service routes.

## 改动 / Changes

共修正 27 处不一致：会直接导致调用失败 9 处、会误导能力判断 10 处、措辞 8 处。主要有：

- **调用入口**：改为 `MailOperations`（path 带 `/api`，capability
由工具注入）；原文的固定端口、「无需认证」、`curl -k` 都不成立
- **附件**：body 字段更正；必须带 `save_to` 落盘（不带会被工具拒绝返回），回执给出路径、字节数、SHA-256
- **参数位置**：`messages/fetch`、`/sync`、IMAP 草稿发送的 `email`（以及 `/sync` 的
`provider`）放查询串；IMAP 草稿收件人是逗号分隔的 `to` / `cc`，更新草稿会换成新 uid
- **folder**：IMAP 单封操作要用 `GET /imap/folders` 返回的服务器路径，列表里的归一化值会 500
- **规则**：operator 是 `matches_regex`（未知 operator 恒为 false
且创建时不校验）；`archive` / `move_to_folder` / `forward_to` / `star` 是空操作
- **搜索**：三个 provider 都支持，只查本地缓存、`q` 只匹配主题；Gmail 全文检索改用 `messages/fetch`
的 `query`
- **IMAP 仅收信账户**：`allowUnverifiedSmtp`、`smtp_verification_failed`、409
`smtp_unverified`、`verify-smtp`（失败也返回 200）
- **离线队列**：不会自动入队或处理，只改本地，`processed` 计数不代表执行
- 响应字段名（`toRecipients`、`bodyPreview` 等）、同步状态文件、`/imap/test` 返回形态等措辞修正
- 版本 1.0.6；新增 `market.required_client_version: 10.0.148` 与 sidecar
`compatibility.requiredClientVersion`——`MailOperations`（10.0.95）、`save_to`
与 Outlook/IMAP search（10.0.146）、`imap:<uid>` / fetch `offset` / folder
归一化（10.0.148）分版本上线，旧客户端按新文档操作会静默失败，门控让它们保留旧版

## 验证 / Verification

- 写补丁与审查由两个独立子代理完成：审查方对 9 处致命项全部、另外 13 处抽查逐条对照代码行，均成立；审查意见（最低客户端版本、IMAP
更新草稿换 uid、`/sync` 参数、Gmail 远程检索、`verify-smtp` 返回形态、离线队列计数、响应示例矛盾）已全部采纳
- 各项最低版本用 `git tag --contains` 对照发布 tag 复核
- `translate.py --check`：en-US human-locked 且 hash 新鲜（`source_hash` 按
`compute_source_hash` 重算）
- `validate-i18n`：0 error，123 warning（与 main 基线相同）
- `validate_catalog_metadata --require-complete`：0 error
- `git diff --check` 通过；新增行只有 `example.com` 占位地址，无真实邮箱、姓名、公司名或长数字编号

🤖 Generated with [Claude Code](https://claude.com/claude-code)

2026-09-29 05:07:39 -04:00

..

offline-queue.md

fix(mail-operations): 按现行邮件服务路由修正技能文档（1.0.6） (#194)

2026-09-29 05:07:39 -04:00