企微图解回复 · wecombot-show-me

当用户需要把「看图才讲得清」的内容变成图片发到企业微信时，按以下步骤执行。

核心原则：文字管结论，图片管详情。内容用文字能讲清的，不产图。

触发与串联（何时自动接管）

本技能自动接管两类场景，无需用户手动添加：

A. 直接触发 —— 用户表达「看图 / 发图」类意图：

• 发图 / 出图 / 图解 / 画图 / 示意图 / 信息图 / 卡片 / 数据卡 / 可视化回复；
• 「把 X 发到企微 / 微信 / 机器人」「发个 html」「这段复杂内容做成图」「太长了我看图」；
• 要产 mermaid（时序 / 流程 / 状态 / 类 / 甘特）、代码快照（伪代码 / 树 / diff）、数据卡（待办 / 审批 / 列表 / 行程）、对比看板 / 信息图。

B. 承接上游技能 —— 查询类技能拿到结构化结果后需要图示：

• qiqiao-api 查出的七巧 / 道一云业务数据（待办、审批、列表、行程、流程）→ 由本技能渲染回图；
• 典型链路：用户说「查询七巧待办」→ qiqiao-api 取数 → 本技能出数据卡 → 企微先发文字概要、再发图片；
• 上游把结构化 JSON / HTML 交过来时，直接进步骤 2 选管线，不必重新解释需求。

判定口径：只要结果适合图示且输出场景是企业微信 / 聊天会话，即使用户没明说「发图」，也按本技能处理（是否真的产图由步骤 0 决定）。

不接管：纯文字能讲清、要 PDF / 视频、要交互页面、要截取真实网页 URL（改用浏览器自动化）。

步骤 0 · 判断是否需要产图

不适用本技能：需要交互的页面、截取真实网页 URL（用浏览器自动化）、PDF/视频输出。

步骤 1 · 环境自检（首次使用必做）

node scripts/selfcheck.mjs

• 输出 structureOk: true 即技能包完好；envOk: false 表示依赖未装，执行下面这条一次性安装：

node scripts/setup.mjs --install     # 装进包内 scripts/node_modules
node scripts/setup.mjs --external    # 或装到共享 managed workspace

• 需要 Node ≥ 18。Node 缺失时先征得用户同意再安装，不要自行下载。
• 依赖：puppeteer-core / satori / @resvg/resvg-js / react / satori-html / mermaid。
• 渲染需系统浏览器（Chrome / Edge / Chromium）；缺失时设 WECOM_HTML2IMG_CHROME=<浏览器绝对路径>。

步骤 2 · 生成 HTML

按内容类型选一条管线，全部为 node scripts/*.mjs，参数见下。

2.1 mermaid 图（时序 / 流程 / 状态 / 类 / 甘特）

node scripts/gen-mermaid.mjs --src flow.mmd --out flow.html \
    --title "下单流程" --sub "sequenceDiagram" --meta "生成时间"
# 也可直接传字符串：--code "graph TD; A-->B"
# 或从标准输入：cat flow.mmd | node scripts/gen-mermaid.mjs --src - --out flow.html

2.2 代码快照（伪代码 / 调用树 / 文件树 / diff）

node scripts/gen-snap.mjs --src change.diff --out snap.html --title "重构变更"
node scripts/gen-snap.mjs --src tree.txt    --out snap.html --type tree
node scripts/gen-snap.mjs --src code.txt    --out snap.html --type code --chip PSEUDOCODE

--type 可省略，自动识别：含 @@ 与 +/- 判 diff；含 ├└│ 判 tree；否则 code。

2.3 数据卡（待办 / 审批 / 列表 / 行程）

node scripts/gen-card.mjs --type todo     --data todo.json  --out card.html \
    --stat "待审批|14|单" --sum "最紧急：0006 双节点流转中"
node scripts/gen-card.mjs --type overview --data rows.json  --out card.html
node scripts/gen-card.mjs --type schedule --data sched.json --out card.html --me 张三

--stat "label|num|unit|sub|emph" 可多次，emph 取 clear / alert。

承接 qiqiao-api 等上游结果时，把查回的记录直接映射成 --data 的 JSON 数组：title / initiator / status / node / time 分别对应卡片「标题 / 发起人 / 状态 / 当前节点 / 时间」，缺字段可省略。

2.4 发版申请单专属卡

node scripts/gen-data-card.mjs --data todo_data.json --out card.html

2.5 自定义 HTML 信息图

手写 HTML（内联 CSS、宽度 ≤680），或套用 templates/ 下现成骨架，然后进入步骤 3。

步骤 3 · 渲染 PNG

node scripts/render-cli.mjs <in.html> <out.png> [A|B] [--wait-sel <css选择器>]

• 路线 A（默认，浏览器截图）：保真，支持 mermaid 与任意 CSS。
• 路线 B（satori 轻量）：仅 flexbox 子集，需同时传 --height。
• 渲染 mermaid 必须传 --wait-sel '.mermaid svg'，否则可能截到空白。
• 输出为 JSON：{"file","route","width","height","ms"}。
• 渲染后请目检 PNG，确认无「解析失败」红字错误条再发送。

步骤 4 · 发到企业微信（两段式）

企微机器人单条消息只支持一种类型，因此先发文字概要，再发图片，两条连续消息即「概要 + 详情」。

# 4.1 先发 markdown 概要（3-6 行结论，≤200 字，数字精确）
wecom-cli message aibot send --json "{\"chat_id\":\"<会话id>\",\"msg_type\":\"markdown\",\"markdown\":{\"content\":\"待办共 **14** 条：审批中 9、我发起 5。明细见图\"}}"

# 4.2 上传图片（路径必须用正斜杠）
wecom-cli media upload --set type=image --json '{"file_path":"C:/Users/me/card.png"}' > up.json

# 4.3 解析 media_id，再发 image（用 Node 解析，不依赖 Python）
node -e "const j=JSON.parse(require('fs').readFileSync('up.json','utf8'));process.stdout.write(j.media_id||'')" > mid.txt
wecom-cli message aibot send --json "{\"chat_id\":\"<会话id>\",\"msg_type\":\"image\",\"image\":{\"media_id\":\"$(cat mid.txt)\"}}"

不支持发企微时，把 PNG 路径直接返回给用户即可。详见 @references/output-protocol.md

步骤 5 · 清理中间产物

发完只保留最终 PNG，删除中间 json / html / 回执 txt。图片随时可重生成。

风格规则

• 默认风格：步骤 4 的两段式 + 内置模板视觉（蓝橙活力卡）。
• 客户覆盖：客户表达过配色 / 版式 / 字体 / 语气偏好时，文字与图片一律按客户风格生成，并持续适用于本会话后续每次回复，直到客户说「正常模式」。

详细参考

• @references/pipelines.md —— 四条产图管线的完整参数、数据模型与模板清单
• @references/output-protocol.md —— 输出协议、企微消息类型与发送细节
• @references/troubleshooting.md —— 已知坑与排查步骤

一句话工作流

> 自检（selfcheck.mjs）→ 判断要不要图 → 要图则先写 3-6 行文字概要 → 选管线生成 HTML → 渲染 PNG → 目检 → 发概要 → 发 image → 清理。