OA 邮件简报
> v1.2.0 — 融合 email-daily-summary v3.0.7（68 pitfall + xlsx 解密 + 4 段分类）与 baoanmobile-tdhl v2.1.0（AskUserQuestion 4 Phase 渐进式引导）。专门适配 WorkBuddy 与 Hermes 两个智能体平台；IM 投递锁定 飞书 与 微信 Clawbot；Obsidian 入库为可选扩展（默认关闭）。
交互规范 — AskUserQuestion（Agent 必须遵守）
> 融合自 baoanmobile-tdhl v2.1.0。详见 references/tdhl-askuserquestion-pattern.md。
每个 Phase 需用户选择时，Agent 必须用 AskUserQuestion 工具弹选项框，禁止让用户回复编号或提示词。
每个问题必须包含：
- 预设选项 2~4 个，label 标明含义
- 一个 [其他] 选项（label="其他（自定义）"），配自由输入框，multiSelect=false
- 等待用户选择后再推进，不得自动代填或猜测
选项超 4 个时：取 TOP3 + [其他（自定义）]。
5 个核心原则（融合自 tdhl）
- 零代码修改 — 所有差异集中在
config.json，切换用户/邮箱/渠道只改此文件 - 展示而非描述 — 配置筛选项时先读取实际值让用户看，不让用户背字段号
- 渐进式引导 — Phase 0 自检 → Phase 1 配置 → Phase 2 试运行 → Phase 3 定时，不跳步
- 平台聚焦 — 专门适配 WorkBuddy 与 Hermes，其他平台不在范围内
- 不可协商的约束 — Pre-flight 5 项必过、xlsx 解密失败绝不伪造数据、IM 分段 ≤195 字符（飞书）
快速启动（3 步开跑，适合首次用户）
如果用户是首次使用，跳过完整 Phase 1，走快速路径：
Step 1（环境自检）：
python scripts/check_deps.py
任何 fail 项由 Agent 自动修复（不抛命令给用户）。
Step 2（3 个关键配置，AskUserQuestion 一次问完）：
1. 邮箱账号：已配置的 himalaya 账号 / agent-mail connector / 其他
2. 投递渠道：飞书 IM / 微信 Clawbot / Markdown 文件 / 其他
3. 时间范围：最近 24 小时 / 最近 12 小时 / 最近 7 天 / 其他
Step 3（试运行）：
python scripts/daily_pipeline.py # v1.3 规划
# 或 Agent 直接执行 Phase 2 工作流
试运行成功后，AskUserQuestion 询问是否设置每日定时（Phase 3）。
> 完整 5 步配置向导（含 xlsx 解密、KB 入库等高级选项）见下方 Phase 1。
模式判断
| 触发源 | 模式 | AskUserQuestion | 输出 |
|---|---|---|---|
| 用户说"扫一下今天邮件" / "生成简报" | 手动（Phase 0→3） | ✅ 全程交互 | 长报告或 IM 分段 |
| 用户说"设置早报 cron" / "每天 8 点自动跑" | 定时设置（Phase 3） | ✅ 设置时交互 | automation_update / Hermes trigger |
| Automation 定时触发 | cron 运行 | ❌ 无人工 | IM 分段（≤195 字符/段） |
模式不清时用 AskUserQuestion 询问。
Phase 0: 环境自检
python scripts/check_deps.py
脚本输出 JSON 给 Agent 读取。Agent 根据 fail_count 决定下一步：
| 检查项 | fail 时 Agent 动作（不抛命令给用户） |
|---|---|
| Python 3.10+ | 自动安装 Python 3.10+ |
| config.json | 进入 Phase 1 配置向导 |
| Python pkg (openpyxl/xlrd/msoffcrypto) | 自动 pip install（xlrd 必须 ==1.2.0） |
| himalaya CLI | macOS: brew install himalaya / Linux: cargo install himalaya / Windows: 下载 release |
| himalaya config.toml | Agent 用 assets/himalaya-config.template.toml 自动创建，需用户提供 IMAP host + 授权码 |
| 输出渠道 | Phase 1 步骤 1.4 时配置 |
fail = Agent 必须自动修复，不给用户抛命令行。
warn = 不阻断，记录在后续步骤提示即可。
fail_count=0 → 进入 Phase 1（首次）或 Phase 2（已配置）。
Phase 1: 配置向导（5 步，每步必用 AskUserQuestion）
> 铁律：每个步骤必须使用 AskUserQuestion，等待用户选择后再推进。
步骤 1.1: 邮箱账号选择（展示而非描述）
Agent 先尝试读取已配置的 himalaya 账号列表（himalaya account list）。AskUserQuestion 弹出：
- 已配置的账号（最多 3 个）
- [其他（自定义）]
如果未配置任何账号 → 直接询问：
1. 用 himalaya + IMAP（推荐，跨平台）
2. 用 WorkBuddy agent-mail connector（原生集成，免配置）
3. 其他（自定义）
中国移动OA邮箱 IMAP 配置（实测验证 ✅）：
- IMAP host: imap.<province>.chinamobile.com（按你所在省份替换 <province>，如 gd / bj / sh）
- SMTP host: smtp.<province>.chinamobile.com
- 端口 993/465 + encryption.type = "tls"（隐式 TLS，不是 start-tls）
- 授权码：登录 PC 端内部系统邮箱 → 点"授权码" → 开启 POP3/IMAP → 手机验证生成（有效期 90 天，非登录密码）
- 注意：imap.139.com 是 139 免费邮箱的，OA邮箱（@<province>.chinamobile.com）不用这个
- 完整配置模板见 assets/himalaya-config.template.toml
步骤 1.2: 时间范围与扫描参数
AskUserQuestion 询问时间范围：
1. 最近 24 小时（默认，适合早报）
2. 最近 12 小时（适合晚报）
3. 最近 7 天（适合周报）
4. 其他（自定义）
用户选择后写入 config.json 的 scan.time_range_hours。
步骤 1.3: xlsx 解密配置
AskUserQuestion 询问是否启用 xlsx 解密：
1. 启用 + 自动试密码表（推荐，OA 邮件常有加密附件）
2. 启用 + 我提供密码候选
3. 不启用（跳过所有加密附件）
4. 其他（自定义）
选 2 → Agent 等待用户粘贴密码候选列表，写入 config.json 的 xlsx.password_candidates。
步骤 1.4: 输出渠道配置
AskUserQuestion 问主渠道（单选）：
1. 飞书 IM（推荐，分段投递 ≤195 字符）
2. 微信 Clawbot（webhook 投递，≤500 字符/段）
3. Markdown 文件（兜底，无限制）
4. 其他（自定义）
第二轮：根据第一轮选择，AskUserQuestion 问具体参数：
- 飞书 → 问 chat_id（用户粘贴 oc_xxx）
- Clawbot → 问 webhook URL（用户粘贴 https://...）+ 可选 chat_id
- Markdown → 问输出目录（默认 output/）
步骤 1.5: 写入并校验
Agent 写入 config.json，用 AskUserQuestion 展示确认摘要并询问：
1. 确认无误，进入试运行
2. 修改配置（返回步骤 1.1）
3. 其他（自定义）
> KB 入库是低频可选功能，不在配置向导里主动问。想用的用户自行在 config.json 设 kb_ingest.enabled=true，详见下文"Obsidian 知识库入库"章节。
进入 Phase 2 前置校验：
- email_account.login 非空（himalaya 模式）
- output.channel 已配置且对应参数非空
- scan.time_range_hours > 0
- 以上任一为空 → 拒绝进入 Phase 2，返回 Phase 1 补填
Phase 2: 试运行（手动模式核心工作流）
Step 1: 扫描收件箱
# himalaya 路线（跨平台）
himalaya envelope list --page-size 50 --page 1 --folder INBOX --output json > /tmp/oa_p1.json
himalaya envelope list --page-size 50 --page 2 --folder INBOX --output json > /tmp/oa_p2.json
himalaya envelope list --page-size 50 --page 3 --folder INBOX --output json > /tmp/oa_p3.json
--output json返回单行 JSON（不是 JSONL），用json.loads整体解析- OA IMAP 慢，
--page-size 100+--output json可能 >60s，用 50 × 3 页更稳 - WorkBuddy agent-mail connector 路线：用
mcp__agent-mail__ListMessages，limit=50每次
Step 2: 关键词过滤
业务关键词（命中即候选）：考核 / 营销 / 渠道 / 产品 / 酬金 / 流程 / 系统 / 合规 / 商机 / 欠费 / 管理办法 / 规范 / 制度 / 实名制 / 反诈 / 稽核 / 通报 / 宽带 / 网格 / 异常 / 扣罚 / 评价 / 评优 / 重点 / 攻坚
非业务关键词（命中即跳过）：福利 / 生日 / 工会 / 餐厅 / 实物兑换 / 端午节 / 体检 / 慰问 / 团建
规则：
- 主题同时含业务 + 非业务 → 仍按业务处理
- 主题只有非业务 → 跳过
- 主题模糊 → 进 Step 3 读全文判断
> 关键词列表可在 config.json 的 filter 段自定义，按业务实际增减。
Step 3: 读全文
himalaya message read <ID> # 单 ID 调用，~30s/封
- 批量调用必超时（>60s），每个 ID 一次独立调用
himalaya message read会同时显示多层转发历史，对溯源政策依据有用
Step 4: xlsx 附件处理（含分支决策）
决策树：
- 邮件正文说"详见附件 xlsx"且附件是
.xlsx→ 下载并解析 - 邮件正文已含完整数据表 → 跳过附件
- 附件是
.xls（不是.xlsx）→ 用xlrd==1.2.0，不用 openpyxl - 附件是 OLE2 加密 → 按密码候选表试，最多 40 次
OLE2 解密失败时（手动模式触发 AskUserQuestion 分支决策）：
1. 跳过此附件，从邮件正文补充事实
2. 试更多密码（用户提供候选）
3. 阻塞报告，标注"加密无法解密"
4. 其他（自定义）
cron 模式：跳过 + 标注"加密无法解密" + 从正文补充 + 写入"明日待查"段。
绝不伪造数据——解不开就解不开，不用估计值凑数。详见 references/xlsx-decryption-cookbook.md。
Step 5: 分类与摘要
4 段式分类（内容过多触发 5/6 段升级）：
| 段 | 标记 | 内容 |
|---|---|---|
| 1 | 🟥 今晚必办 | 今晚截止项，时间倒序，已过期红字 |
| 2 | 🟧 明天必办 | 明天截止项，含时间锚点 |
| 3 | 🟨 周末前必办 | 周末前必办项 |
| 4 | 📊 数据 | 数据快照、排名、环比 |
5 段触发：数据段 > 195 字符 或 中期节点 > 3 项
6 段触发：今天 ≥ 4 项 + 7 天内 ≥ 5 项 + 月末 ≥ 3 项 + xlsx 解析 ≥ 5 项
Step 6: 出口确认（手动模式 AskUserQuestion）
分段完成后，AskUserQuestion 展示并询问：
- 段数 + 每段字符数 + 总字符数 vs 渠道上限
- 每段前 50 字预览
1. 按现状投递
2. 修改分段
3. 重新排序
4. 其他（自定义）
cron 模式：跳过此步，直接投递。
Step 7: 投递
| 渠道 | 工具 | 限制 |
|---|---|---|
| 飞书 IM | WorkBuddy 飞书 connector / Hermes send_im_safe.py | ≤195 字符 / 30 行/段 |
| 飞书 DM | 同上 | ≤400 字符 / 50 行/段 |
| 微信 Clawbot | WorkBuddy Clawbot connector / Hermes webhook 适配器 | ≤500 字符/段 |
| Markdown | Write 工具 | 无限 |
投递前自检（所有渠道）：
1. wc -m 每段（飞书群 ≤195，Clawbot ≤500）
2. 无 Variation Selector emoji（⚠️/✅/❌ 等触发安全扫描）
3. 无内部 slang（业务术语外的随意缩写）
详见 references/im-delivery-protocol.md。
Step 8: 试运行结果处理
成功：
- 展示统计摘要：扫描封数 / 业务命中数 / xlsx 解析数 / 投递段数
- 展示输出文件路径（如有 Markdown 落地）
- AskUserQuestion 询问：进入 Phase 3 定时设置 / 完成 / 重新跑
失败：
- 按步骤定位失败环节
- 每次重试最多 2 次
- 明确告知用户失败原因和修复建议
Phase 3: 定时设置（可选）
试运行成功后，AskUserQuestion 询问是否设置自动运行：
1. 每天早 8:00 早报 + 晚 18:00 晚报（推荐）
2. 仅每天早 8:00 早报
3. 自定义时间
4. 暂不设定时
WorkBuddy 平台
Agent 用 automation_update 工具创建定时任务：
- scheduleType: recurring
- rrule: 根据用户选择生成 RFC 5545 规则
- prompt: 执行管线的完整指令
- cwds: 技能根目录路径
三个默认 schedule：
| Schedule | RRULE | 内容 |
|---|---|---|
| 早报 | FREQ=DAILY;BYHOUR=8;BYMINUTE=0 |
今天截止 + 数据快照 |
| 晚报 | FREQ=DAILY;BYHOUR=18;BYMINUTE=0 |
今晚已过期 + 明天 + 周末 + 数据 |
| KB 入库（可选） | FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=12;BYMINUTE=5 |
9 步流水线写 Obsidian（仅 kb_ingest.enabled=true 时） |
Hermes 平台
Agent 使用 Hermes 自身的定时触发器配置：
- 创建 cron trigger 指向 skill
- deliver 字段配置 IM 渠道（feishu:oc_xxx 或 clawbot:<webhook_url>）
- 与 WorkBuddy 等价的 3 个默认 schedule
Obsidian 知识库入库（低频可选，默认关闭）
> 基本没人用这个功能。仅当需要把邮件知识长期沉淀到 Obsidian 笔记库时才启用。默认 kb_ingest.enabled=false，不启用时 skill 完全可用。日报简报和 KB 入库是两个独立功能——日报看"今天有什么重要的"，KB 入库看"这条知识要不要长期存"。大多数人只需要日报。
启用：config.json 设 kb_ingest.enabled=true + 填 vault_path。9 步流水线详见 references/kb-ingest-workflow.md。
什么邮件该入库（举例）：
- ✅ 新制度/新流程（如"加盟厅考核办法 V3"）→ 新建笔记
- ✅ 定期通报（如"月度渠道份额通报"）→ 追加到已有笔记的历史记录段
- ⏭ 单点操作（如"XX 小区扩容申请"）→ 跳过，不入库
入库后笔记长什么样：见 assets/optional/obsidian-schema.template.md（含 frontmatter 模板 + 正文 4 段结构 + tag 分类表）。
Pitfall Library（15 条精选）
> 从 v3.0.7 的 68 条中精选通用部分。详见 references/pitfall-library.md。
| # | Pitfall | Fix |
|---|---|---|
| 1 | himalaya --page-size 100 --output json 超 60s |
用 --page-size 50 × 3 页 |
| 2 | himalaya message read 批量必超时 |
单 ID 一次，串行不并行 |
| 3 | --output json 返回单行 JSON |
json.loads 整体解析 |
| 4 | 主题含业务+非业务关键词 | 仍按业务处理 |
| 5 | .xls 文件 openpyxl 打不开 |
用 xlrd==1.2.0 |
| 6 | OLE2 加密 xlsx 密码未知 | 试 40+ 候选；全失败标注"加密无法解密"，绝不伪造 |
| 7 | wc -m 与 send_im_safe 实际计数差 +5~50 |
飞书群 ≤195 字符/段（不是 295/300） |
| 8 | Variation Selector emoji 触发安全扫描 | 用 🟥🟧🟨🟦🟪🔥📊📋📅⏰📌 |
| 9 | 同主题同日多封 = 系统重发 | 只取最早 1 封 |
| 10 | 同日 V4→V5→V6 多版本 | 取最后版本，旧版入 dedupe 不入笔记 |
| 11 | 内部 slang（业务术语外的随意缩写） | 用纯业务术语 |
| 12 | openpyxl 返回缓存公式值 | 用 data_only=True |
| 13 | 不同 xlsx "金额"列位置不同 | 必读前 3 行表头确认列号 |
| 14 | --check-only 实际会发送 |
auto-delivery cron 接受 4-6 段投递 |
| 15 | "归属"列为空 ≠ 不存在 | 区分"归属明确" vs "归属待定" |
资源索引
references/
tdhl-askuserquestion-pattern.md— tdhl v2.1.0 的 AskUserQuestion 模式精华implementation-analysis.md— v3.0.7 深度解读 + GitHub 对标 + 设计决策xlsx-decryption-cookbook.md— OLE2 解密代码模式 + 密码候选表模板 + 失败协议im-delivery-protocol.md— 飞书 + Clawbot + Markdown 分段规则 + 字符自检 + emoji 黑名单kb-ingest-workflow.md— 可选模块。9 步 Obsidian 入库流水线（仅kb_ingest.enabled=true时加载）pitfall-library.md— 15 条 pitfall 详细症状 + 修复 + 代码示例preflight-cross-platform.md— 平台特定 preflight 命令（macOS/Linux/Windows）
scripts/
check_deps.py— 环境自检脚本，输出 JSON 给 Agent 读取preflight_check.py— 5 项诊断（跨平台）xlsx_decrypt.py— 通用 OLE2 xlsx 解密im_segment.py— 分段写文件 +wc -m自检 + Variation Selector emoji 扫描
assets/
himalaya-config.template.toml— 跨平台 himalaya 配置模板optional/obsidian-schema.template.md— 可选模块。Obsidian 笔记 frontmatter schema（仅启用 KB 入库时使用）
config.json
所有配置集中（邮箱账号 / 扫描参数 / 过滤关键词 / xlsx 密码 / 输出渠道 / 分类规则 / KB 入库开关 / 定时）。切换用户/邮箱/渠道只改此文件，不改代码。
何时使用此技能
✅ 使用：
- 用户想要 OA 邮件日报 / 摘要 / 简报
- 用户说"扫一下今天邮件" / "看看今天有什么重要的"
- 用户想设置自动早晚报 cron
- 用户有 OA 邮件 xlsx 附件需要解密解析
- 用户想把邮件知识沉淀到 Obsidian（可选）
❌ 不使用：
- 用户要发 / 回复 / 转发邮件（直接用 mcp__agent-mail__SendMessage）
- 用户需要实时交互式邮件通信
- 邮箱高度敏感，禁止 IMAP 自动化
- 用户要管理日历 / 联系人（其他技能）
平台适配说明
WorkBuddy
- 邮件接入：
agent-mailconnector（推荐）或 himalaya CLI - IM 投递：飞书 connector / Clawbot connector
- 定时：
automation_update工具创建 recurring 任务 - KB 入库：Write 工具写 Obsidian vault（如启用）
Hermes
- 邮件接入：himalaya CLI（原生）
- IM 投递：
send_im_safe.py飞书 / Clawbot webhook 适配器 - 定时：Hermes 自身 cron trigger
- KB 入库：terminal 写 vault（如启用）
其他平台（Claude Code / Cursor / OpenClaw 等）不在 v1.2.0 适配范围内。
升级路径
v1.0.0 → v1.1.0
- 新增 tdhl AskUserQuestion 4 Phase 渐进式引导
- 新增
config.json集中配置 - 新增
scripts/check_deps.py环境自检
v1.1.0 → v1.2.0
- 改名
email-daily-summary-pro→oa-mail-briefing（更通用） - 角色模糊化（删除业务专属词，适配多行业）
- KB 入库标注为可选扩展模块（默认关闭，移到
assets/optional/） - 平台锁定 WorkBuddy + Hermes（删除 claude-code/cursor/openclaw/qclaw）
- IM 渠道锁定飞书 + 微信 Clawbot + Markdown（删除钉钉/SMTP/企微）
- 新增"快速启动"3 步路径
- 新增 Clawbot webhook 投递支持
v1.2.0 → v1.3.0（规划）
- 新增
scripts/daily_pipeline.py一键管线（输出 JSON 给 Agent 读取） - 新增多用户/多邮箱部署支持
- Clawbot 投递脚本独立化
Attribution
- v3.0.7 source: email-daily-summary v3.0.7 (Hermes CLI skill, 68 pitfall, xlsx 解密, IM 分段)
- tdhl source: baoanmobile-tdhl v2.1.0 (SkillHub, AskUserQuestion 4 Phase, config.json 集中配置)
- GitHub benchmarks: Thysrael/Horizon (3.9k★), openclaw/skills, Mao2973464622/lumapost, gyChen-3725/github-trending-email
- AskUserQuestion 工具: WorkBuddy 原生 AskUserQuestion（1-4 问题 × 2-4 选项 + Other）
- License:
agent_created: true, MIT-equivalent internal use, distributable via WorkBuddy Skillhub team edition
