WXIMA — 微信群聊归档到 IMA 知识库
通用对话式归档技能。把散落在不同微信群/个微对话里的信息，通过"邮件中转"集中存进 IMA 知识库，便于日后搜索整理。
功能使用说明
这个 skill 做什么
你在微信群里收到重要信息（通知、会议纪要、合同、聊天记录……），用微信自带的「多选 → 邮件转发」把它们发到你的 Agent Mail 归档邮箱（@agent.qq.com）。WXIMA 会自动读取这些邮件，根据你设定的暗号（邮件主题里的关键词）把内容归档到 IMA 知识库对应的文件夹里。
⚠️ 附件大小限制
单封邮件中，每个附件和所有附件总和均不能超过 20MB。 这是 Agent Mail API 的硬性限制（max_attachment_size_bytes = 20971520）。超过此限制的附件将无法自动下载入库，需要你手动拖入 IMA 知识库。请在微信转发邮件时注意附件大小。
核心能力
| 能力 | 说明 |
|---|---|
| 暗号路由 | 邮件主题里写一个暗号（如 XZRK），自动归档到对应知识库 |
| 智能文件夹匹配 | 自动分析邮件正文和附件内容，匹配到最合适的文件夹；匹配规则在配置时由 skill 生成、用户审定后生效；判断不确定时才归到默认文件夹 |
| 附件文件名保留 | Agent Mail API 返回原始附件文件名（含中文），归档后文件名清晰可辨 |
| 每日定时自动归档 | 设定一个时间（如 23:59），每天到点自动扫描邮箱并执行归档，跑完发结果通知 |
| 手动归档 | 随时说"归档"，立即扫描并处理未归档的邮件 |
| 周报/月报 | 可选：每周或每月自动生成入库报告，发到你指定邮箱 |
| 多知识库 | 一个暗号对应一个知识库；想归档到新库，再调 skill 加一条规则即可 |
| 幂等去重 | 每封邮件只处理一次，绝不重复入库 |
日常使用方式（配置完成后）
- 在微信群里：多选消息 → 右下角 邮件图标 → 收件人填你的 Agent Mail 归档邮箱地址
- 邮件主题写：
暗号 自由描述
- 例：XZRK 8月行政例会通知
- 只需要写暗号 + 简短描述，不需要手动指定文件夹——WXIMA 会自动分析邮件正文和附件内容，智能匹配到对应文件夹 - 注意附件大小：单个附件和附件总和均不超过 20MB
- 发送
- 等每日自动归档时间到了自动处理；或随时对我说"归档"立即处理
配置流程说明
首次使用时，对 WorkBuddy 说 "配置归档" 或 "教我怎么用 WXIMA"，启动设置向导。向导分 11 步（Step 0~10），每步确认后再进入下一步：
| 步骤 | 做什么 | 你需要做什么 |
|---|---|---|
| Step 0 | 检查三项依赖（agently-cli / ima-skill / IMA 凭证） | 缺哪个补哪个，向导会给引导 |
| Step 1 | 确认邮箱连通性 | 通常 Step 0 已验证，直接展示邮箱地址 |
| Step 2 | 确认 IMA 知识库 | 告诉向导知识库名称（需在 IMA 客户端提前建好） |
| Step 3 | 文件夹方案讨论 | 和向导讨论要建哪几个文件夹、每个文件夹存什么内容、边界是什么 |
| Step 4 | 文件夹审核与定位 | 在 IMA 客户端建好文件夹后回复"建好了"，向导自动审核验证 |
| Step 5 | 智能匹配规则生成与审定 | 向导基于讨论自动生成每个文件夹的匹配关键词和匹配说明，你审定后定稿 |
| Step 6 | 确认入库规则 | 确认标题格式、附件策略、链接处理等 |
| Step 7 | 设定暗号 | 向导生成候选暗号，你确认即可 |
| Step 8 | 设定自动归档时间 | 选一个每天自动跑的时间（如 23:59），或选"只手动" |
| Step 9 | 设置报告（可选） | 选每周/每月报告，给一个收件邮箱；或跳过 |
| Step 10 | 落盘确认 | 看配置摘要（含匹配规则），确认无误后写入配置文件 |
> 配置完成后可以随时说"查看规则"、"改暗号"、"改自动归档时间"、"加知识库"等管理配置。
核心链路
微信群聊 多选消息 → 发送邮件到 Agent Mail 归档邮箱（@agent.qq.com）→ agently-cli 读取邮件 → subject 暗号路由 → AI 分析内容智能匹配文件夹 → IMA 知识库对应文件夹
↑ 每日定时自动触发（如 23:59）
依赖（向导 Step 0 会逐项检查并引导安装）
| 依赖 | 作用 | 缺失时引导 |
|---|---|---|
| agently-cli（Agent Mail CLI） | 读写邮件（收信 + 附件下载 + 发通知/报告），返回原始附件文件名（含中文） | agently-cli +me 验证。未安装则引导：npm install -g @tencent-qqmail/agently-cli + agently-cli auth login 完成 OAuth 授权（https://agent.qq.com 扫码创建邮箱）。详见 Agent Mail CLI 文档 |
| ima-skill | 调用 IMA OpenAPI（笔记/文件/网页入库、搜索定位） | 已装则跳过；未装提示用户安装该用户级 skill |
| IMA 凭证 | ima-skill 调 API 所需 Client ID / API Key | 按 ima-skill Credential Check 引导（https://ima.qq.com/agent-interface 获取） |
> agently-cli 与 ima-skill 是独立技能/工具，本 skill 不重复实现其能力，只做编排。
> agently-cli 命令格式：
> - agently-cli +me — 验证授权，返回邮箱地址
> - agently-cli message +list --dir inbox --limit N — 列出邮件
> - agently-cli message +read --id msg_xxx — 读取邮件详情（含附件元数据，filename 为原始中文名）
> - agently-cli attachment +download --msg msg_xxx --att att_xxx --output ./dir — 下载附件（保留原始文件名）
> - agently-cli message +send --to xxx --subject xxx --body xxx --confirmed — 发送邮件
邮件 Subject 约定格式（与用户确认后写入 config）
暗号 自由描述
例：XZRK 8月行政例会通知
- 暗号：4~6 位字母/数字（大小写不敏感），每个知识库一个，全局唯一（如 XZRK=行政入库）；config 中统一存大写
- 自由描述：简短描述邮件内容即可，不需要手动指定文件夹
- 暗号提取规则：subject 中首个匹配
^[A-Za-z0-9]{2,10}$的独立 token，匹配后统一转大写再与 config 中的 code 比对（用户写Xzrk、xzrk均能识别为XZRK） - 文件夹自动匹配：归档时 AI 分析邮件正文 + 附件名 + 附件内容，与 config 中该知识库的文件夹列表智能匹配，选最合适的文件夹入库；判断不确定时归到
default_folder
配置与状态文件
- 配置：
~/.workbuddy/WXIMA/config.json— schema 见 references/config.md - 状态：
~/.workbuddy/WXIMA/state.json— 已处理 message id + 入库日志（追加，不覆盖） - 两个文件都不存在 → 视为首次使用，进入设置向导
意图路由
| 用户说 | 执行 |
|---|---|
| 首次设置 / 教我怎么用 / 配置归档 | references/workflows.md § 设置向导（首次） |
| 新建知识库规则 / 再加一个归档库 | 同上 § 设置向导（增量模式） |
| 归档 / 处理邮件 / 我从微信发了邮件 | 同上 § 执行归档 |
| 自动归档 / 改自动归档时间 / 关闭自动归档 / 开启自动归档 | 同上 § 管理规则 |
| 入库报告 / 这周归档了什么 | 同上 § 报告 |
| 查看规则 / 改暗号 / 改文件夹 / 改报告 | 同上 § 管理规则 |
硬约束（不可违反）
- IMA API 无法新建知识库/文件夹 — 必须用户在 IMA 客户端（App/桌面）预先创建；本 skill 只负责定位（
search_knowledge_base/search_knowledge/get_knowledge_list）并把 kb_id / folder_id 缓存进 config - 归档执行前必须先加载 ima-skill（Skill 调用）：写笔记读其
notes/SKILL.md（UTF-8 强制校验），上传文件读其knowledge-base/SKILL.md（4 道安全门：类型检查 / title=file_name / 重名检查 / 上传失败即停） - 邮箱读写统一使用 agently-cli —
agently-cli message +list/message +read/attachment +download/message +send命令操作。连通性验证用agently-cli +me。CLI 路径：which agently-cli或用户 Node.js 安装路径下的全局 bin - 幂等：message id 已存在于 state.json → 跳过，绝不重复入库
- 隐藏内部 ID：对用户展示时永远不出现 kb_id / folder_id / media_id / note_id
- config.json 中不含任何密码/授权码；邮箱凭证由 agently-cli OAuth 托管，IMA 凭证由 ima-skill 自己管理
- 附件大小限制 — Agent Mail API 限制：单个附件不超过 20MB，单封邮件所有附件合计不超过 20MB（
max_attachment_size_bytes = 20971520）。所有附件均尝试自动下载并入库，不设预判阈值。下载失败（超过 20MB）时记录失败并通知用户具体文件名和大小，不静默跳过、不中断其他附件处理。归档的核心价值是全自动——宁可报错让用户知情，也不要主动放弃让用户手动处理 - 附件文件名直接使用原始名 — agently-cli
message +read返回的attachments[].filename就是原始文件名（含中文，已实测确认），如会议纪要8月.docx。attachment +download保存时也保留原始文件名。直接使用，无需还原或构造。此名称用于 IMA 入库时的 title、本地保存文件名、check_repeated_names检查、create_media的 file_name 参数
