一键生成带截图标注的客户操作指南

要解决什么问题

给客户写操作说明时，纯文字很难对齐真实界面：按钮在哪、先点哪一步，读者要在脑子里把描述和截图自己对上号。若只靠未标注的全页截图，关键控件又容易被背景信息淹没。本技能把可交互的浏览器操作流程固化成一份可交付物：带红框/编号/箭头的步骤图，以及面向客户语气的 guide.md。

技能如何工作

整体链路是「按真实用户路径走一遍 → 记录每步画面与目标区域 → 用清单驱动构建脚本出稿」。

1. 界定范围（仅在必要时）：目标 URL/页面、读者、业务目标、要覆盖的主流程。
2. 浏览器自动化复现流程，每个有意义的交互后截一张图，避免 UI 状态未变时的重复截图。
3. 为每步记录 bounding box：优先用自动化拿到的按钮、输入框、菜单、对话框边界；否则在截图上估算。
4. 按 references/manifest-format.md 编写 manifest，执行 scripts/build_guide.py --output . 生成标注 SVG 与 Markdown。
5. 审阅 guide.md 与标注图：动词开头、无实现细节与内部调试信息。

标注约定简要记：红色框标主点击/输入目标；同屏多目标用编号；箭头仅在框不足以指明时使用。说明写在步骤正文，图上文字保持简短。构建默认 embedded image mode（截图以 base64 嵌在 SVG 内），对各类 Markdown 预览与文档转换更稳；仅在明确需要更小 SVG 且渲染器支持本地引用时再用 --image-mode linked。

产出目录通常包含：guide.md、assets/step-XX.svg、assets/originals/step-XX-original.*。若需要 Word/PDF，先完成 Markdown 与标注图，再用本地工具转换。

适用边界与注意点

• 截图应反映客户所见界面，不要暴露实现内部结构；裁剪只在能提升可读性时使用。
• 一步一个主红框通常比满屏标注更清晰；风险与前置条件放在 notes，不要挤在图上。
• 本地 Web 应用若环境提供 Codex 应用内 Browser，优先用它完成采集，再走同一套 manifest 与构建脚本。