后台系统使用指南生成（6 步 SOP）
跑完这套流程，交付三样东西：
| 产出 | 说明 |
|---|---|
| 单文件 HTML 使用指南 | 内嵌真实截图、流程图、FAQ，浏览器直接打开，无外部依赖 |
| 白底高清流程图 | SVG 源文件 + @4x PNG，可复用到 PPT / wiki / 培训材料 |
| 模块功能梳理清单 | 每个模块的用途、关键操作、字段、联动、注意事项 |
全程约 1 个工作日的工作量，大部分由你（agent）完成；用户只在第 1 步做三个决定、第 3 步可能协助扫码登录、最后验收。
流程总览
| 阶段 | 做什么 | 产出 | 依赖 |
|---|---|---|---|
| 1. 需求澄清 | 问用户三个问题 | 三个决定 | — |
| 2. 调研梳理 | 通读代码，梳理每个模块 | 模块功能清单 | explore 探索代理 |
| 3. 实测截屏 | 逐页截取列表、弹窗、详情 | 截图素材包 | ego-browser |
| 4. 绘制流程图 | 总览图 + 关键机制图 | SVG + @4x PNG | baoyu-diagram |
| 5. 编写指南 | 按固定结构产出 HTML | 指南初稿 | — |
| 6. 校验交付 | 渲染查、敏感信息查、仓库状态查 | 定稿 | ego-browser |
开始前：环境预检（一次性）
本 skill 依赖三个外部能力。开工前先逐项检查，缺什么装什么——避免跑到第 3 步才发现环境不可用，白做前两步：
| 依赖 | 用途 | 检查方式 | 缺失时 |
|---|---|---|---|
| explore 探索代理 | 第 2 步代码调研 | 内置子代理（Task 工具的 explore 类型），无需安装 | 当前环境没有 explore 子代理时，由你直接通读代码完成调研，产出同样的 5 维报告 |
| ego-browser | 第 3、6 步截屏与校验 | command -v ego-browser |
按下方「安装 ego-browser」执行 |
| baoyu-diagram | 第 4 步流程图 | skill 目录存在 + bun/npx 可用 | 按下方「准备 baoyu-diagram」执行 |
安装 ego-browser（macOS）
ego-browser 命令由 ego lite 应用提供，安装分两段：脚本装 App，用户在 GUI 完成首次引导。
- 运行 ego-browser skill 内的安装脚本（按实际 skill 目录调整路径）：
bash
sh ~/.agents/skills/ego-browser/scripts/install.sh
脚本会按 CPU 架构下载 DMG、装入 /Applications 并去除隔离属性，最后自动打开 ego lite；
2. 等用户在 App 里完成首次引导（可从 Chrome 导入数据；引导会把 ego-browser 命令注册到 PATH，通常在 ~/.local/bin）——这是 GUI 操作，必须等用户确认完成后才能继续；
3. 验证就绪：
bash
command -v ego-browser || export PATH="$HOME/.local/bin:$PATH"
ego-browser nodejs <<'EOF'
console.log('ego-browser ready')
EOF
打印 ego-browser ready 即就绪。
非 macOS、下载失败或 Gatekeeper 拦截：让用户从官网 https://lite.ego.app/ 手动安装，或在「系统设置 → 隐私与安全性」里放行。
准备 baoyu-diagram
baoyu-diagram 是纯脚本型 skill（scripts/main.ts）：SVG 由你在对话中按其设计规范直接产出，脚本只负责把 SVG 转成 @2x 高清 PNG。准备动作：
- 确认 skill 目录存在（本仓库
.agents/skills/baoyu-diagram/或全局~/.agents/skills/baoyu-diagram/）； - 确认运行时：装了
bun就直接用；没有则用npx -y bun（无需预装 bun，有 Node/npx 即可）； - 需要安装依赖时用淘宝镜像加速：
npx -y bun install --registry https://registry.npmmirror.com。
运行方式：${BUN_X} <baoyu-diagram目录>/scripts/main.ts <svg路径>（BUN_X = bun 或 npx -y bun）。
预检全部通过（或确认走降级路径）后，再进入第 1 步。
第 1 步：需求澄清（先问三个问题，再动手）
开工前向用户确认三件事——它们决定全文风格、存放路径与素材来源，跳过极易返工：
- 给谁看？ 新人上手向（场景化、步骤化、带注意事项）还是功能速查向（紧凑罗列）——决定全文风格；
- 放在哪里？ 项目
docs/目录、系统内的指南页、还是独立文件——决定引用路径与图片方式； - 截图从哪来？ ① 实测截屏（效果最好，需要环境可用）② 用户已有截图 ③ 先留占位区后补图。
用户在触发时已说明的部分不要重复问；需要环境地址、代码仓库路径时一并向用户要。
第 2 步：调研梳理（explore 探索代理）
目标：为每个模块回答 5 个问题，形成模块功能清单。
- 用途一句话：这个模块解决什么问题（写在指南每节的开头）；
- 关键操作：页面上的按钮/入口各干什么（读页面组件文件与弹窗组件）；
- 关键字段：表格列、表单字段的含义（重点读 tooltip 与常量定义）；
- 模块联动：数据从哪个模块来、到哪个模块去（串出主线流程）；
- 注意事项：前置条件、不可恢复操作、易误解点（读确认弹窗文案与表单校验）。
执行方式：用 Task 工具启动 explore 只读子代理，按下面模板下任务（替换 <项目路径>、模块清单与主线流程名）：
这是一个只读研究任务，不要写任何代码或文件。
项目：<项目绝对路径>
请深入阅读以下 N 个模块的页面代码与相关文档，为每个模块输出：
1. 模块用途（一句话 + 详细说明）
2. 页面上的关键操作/按钮及各自作用
3. 关键字段/表格列含义
4. 与其他模块的联动关系
5. 适合在使用指南中强调的注意事项/前置条件
另外梳理 <主线流程 A/B> 的完整链路，每一步标注「页面 → 操作」。
返回结构化中文报告，信息以代码为准。
调研要点：
- 先找路由/页面清单：约定式路由看页面目录结构；菜单在配置平台里就先向用户要一份菜单截图或配置导出；
- 项目
docs/目录与既有 wiki 交叉验证，信息以代码为准，文档作补充； - 子代理返回后，自己抽查 2~3 个关键结论（按钮行为、校验文案）再写进指南，防止幻觉。
第 3 步：实测截屏（ego-browser）
加载 ego-browser 技能执行。动手前先列截图清单：每个模块的列表页 + 创建/编辑弹窗 + 1~2 个详情页 + 调研中标记的关键交互（开关、抽屉、二次确认等）。清单式推进不会漏页。
脚本骨架（每个阶段一个 heredoc，脚本间用任务空间名字续接）：
ego-browser nodejs <<'EOF'
// 1. 建任务空间（后续轮次复用同一个名字）
const task = await useOrCreateTaskSpace('<系统名>-screenshots')
// 2. 统一视口（高清截图基线）
await cdp('Emulation.setDeviceMetricsOverride', { width: 1600, height: 900, deviceScaleFactor: 2, mobile: false })
// 3. 打开页面并等待数据
await openOrReuseTab('http://<本地或测试域名>/<路由>', { wait: true, timeout: 60 })
await waitForNetworkIdle(10)
// 4. 交互（点按钮/选下拉）——用 snapshotText 拿到元素 ref 后 click('@ref')
// 5. 截屏并落到素材目录
const p = await captureScreenshot()
const fs = await import('node:fs')
fs.copyFileSync(p, '<素材目录>/01-list.png')
EOF
硬规则（都是实战踩出来的，直接照做）：
- 选有数据的账号/租户：列表页全是空态的截图没有说服力。可先调后端分页接口找出数据最多的租户/业务 ID，再在页面上下拉选中重截；
- 统一视口：1600×900、2 倍像素比，所有截图尺寸一致；
- 弹窗先验证再截：用
js()确认弹窗容器display非none，弹窗不在视口时先scrollIntoView； - 敏感信息：token、手机号等入镜时，切换 tab（如改看请求参数）或打码后重截；
- 扫码登录：
handOffTaskSpace(id)交接给用户操作，完成后takeOverTaskSpace(id)接管；会话过期 / 页面空白 / 截图白帧 → 重启浏览器进程后新建任务空间重开页面； - 收尾：
completeTaskSpace(id, { keep: false })关闭任务空间。
环境不可用或无法登录时走降级路径：改用用户已有截图，或先建占位区后补图——不要卡死在截屏上，其余步骤照常推进。
第 4 步：绘制流程图（baoyu-diagram）
加载 baoyu-diagram 技能执行。数量控制：一张全景总览图（放「平台是什么」一节，让读者 10 秒看懂原理）+ 每个关键机制一张（如某模式的分支逻辑、某主流程的分步）；模块很少时可只画主线流程图。
团队视觉规范（保证图嵌入白底文档不违和）：
- 白色背景、浅色系配色、中文字体用系统字体栈；
- 横向左→右表达「数据怎么流」；决策用菱形；不同链路不同颜色（蓝=基准链路、绿=被测链路、橙=平台动作）；
- 模块分组用虚线区域框 + 左上角标签；图上放「图例 + 底部一句话原理总结」；
- SVG 源文件与 @4x PNG 一起归档到素材目录——系统改版后只改文字重出图即可。
第 5 步：编写指南
单文件 HTML，截图用相对路径引用（guide-assets/），按「新手上手向」固定结构组织：
1. 平台是什么 ← 一段话 + 原理总览图 + N 个模块协作关系表
2. 核心概念速查 ← 系统里的新术语（租户、审批单、灰度环境……）一表看懂
3. 主线流程（A/B/C） ← 每条主流程按「页面 → 操作」分步，标注前置条件
4. 模块详解 × N ← 每个模块：用途一句话 / 页面路由 / 关键操作表 /
重点字段表 / 实测截图 / 注意事项（tip 块）
5. 常见问题 FAQ ← 从确认弹窗文案、校验提示、群里的高频问题里提炼
写作要点：
- 每个模块开头用「用途一句话」+ 蓝底引导块，读者扫一眼就知道这节要不要细读；
- 操作用表格（操作名 → 作用），注意事项用带色 tip 块（普通提示 / 危险操作红色）；
- 所有结论以代码为准：tooltip 原文、确认弹窗文案直接引用，比转述准确；
- 有对比性的概念（如 模式 A vs 模式 B、旧版 vs 新版）用对比表，层次立刻清晰。
第 6 步：校验与交付（三查）
三查全过才算交付：
- 渲染查：用 ego-browser 打开指南，执行脚本统计
document.images中naturalWidth === 0的数量（应为 0），并确认锚点可跳转； - 敏感信息查：全量翻一遍截图，重点看请求头、日志、用户信息；
- 仓库状态查：
git status/git diff确认没有夹带无关改动，环境相关的临时修改（配置、hosts、端口转发）全部还原，只留下指南相关文件。
最后向用户交付：指南文件路径 + 流程图位置 + 模块功能清单，并说明「SVG 源文件已归档，系统改版后改字重出图即可」。
