功能宣贯 Skill

一句话定位

读取功能设计源 Markdown，产出一份可直接打开演示的 HTML 宣贯页面，供产品/研发在团队会议中讲解功能边界与核心逻辑。

触发场景

• 用户说"生成功能宣贯"、"出一份宣贯"、"给团队讲这个功能"
• 用户说"帮我做流程图"、"宣贯材料"、"讲解页"
• 用户说"对这个功能做一次宣贯"
• 用户提到"要给团队讲解功能边界/核心逻辑"

前置条件

必须已有对应的功能设计源 Markdown 文档（由「智能体需求文档生成skill」或手工编写均可）。若用户未指定文档路径，主动询问。

产出规格

• 格式：单文件 HTML，浏览器直接打开，无需服务器
• 文件名：{功能名称}-功能宣贯.html，与源 MD 文档放同一目录
• 图表渲染：Mermaid.js v10（CDN），所有图支持全屏 + 缩放 + 拖拽
• 共用资源：引用 briefing-ui.css + briefing-ui.js（与 HTML 同级或上级目录）
• 页面结构：Header → 粘性导航 → 5 个章节 Section → Footer

工作流

1. 读取用户指定的功能设计 MD 文档
2. 提取关键信息（见"信息提取规则"）
3. 生成各章节 Mermaid 图表代码（见"图表生成规范"）
4. 基于 assets/briefing-template.html 模板填充内容，生成完整 HTML 文件
5. 写入目标路径
6. 用 preview_url 或 open_result_view 展示给用户

信息提取规则

从源 MD 中提取以下内容，用于填充各章节：

页面章节规范（5章节，必须全部包含）

第一章：功能边界

布局：左右两栏卡片组

• 左列：做什么（绿色边框）、不做什么（红色边框）
• 右列：外部依赖（蓝色边框）、角色权限（灰色边框）
• 下方：操作可用性速查表（表格，行=操作，列=角色，✓/✗/—）

第二章：功能流程图

图表类型：flowchart TD（标准 UML 活动图风格）

内容：描述主线业务流程，从"进入列表页"出发，覆盖核心操作分支

要点：

• 不使用泳道分区，保持简洁
• 用 classDef 对关键节点着色（入口蓝色，判断橙色，成功绿色，危险红色）
• 只画主线流程，不画每个字段的详细校验逻辑
• 判断分支用菱形节点 {"条件?"}

第三章：状态流转图

图表类型：stateDiagram-v2（标准 UML 状态机图）

内容：核心业务资源的完整生命周期（每个状态 + 所有跃迁条件）

注意：

• transition label 不换行，长说明用括号补充
• 用 note 标注关键状态的业务规则

第四章：外部系统业务交互

图表类型：sequenceDiagram（UML 时序图）

内容：本功能与外部系统之间的业务交互时序

要点：

• 只写业务交互，不写技术细节（不写数据库表、API路径、字段校验）
• 按场景拆分多张时序图（如：首次签发、多次下载、吊销、启用/禁用）
• 用 rect 色块标注关键步骤组
• 用 Note 标注步骤说明
• 参与者只写业务角色/系统名称，不写技术组件

第五章：核心要点

布局：2-3 列彩色卡片，每张卡片一条关键规则

颜色分配：蓝色=数据规则，绿色=状态规则，橙色=操作规则，紫色=系统集成规则，红色=异常处理，黄色=权限规则

内容：从文档中提炼 6-10 条"团队必须记住"的业务规则，每条一句话

图表生成规范

详细的 Mermaid 语法约定见 references/图表编写规范.md，生成图表前必须读取并遵循。

快速记忆要点：

• node label 换行：用
不用 \n
• subgraph id：用英文字母，不用中文
• stateDiagram transition：label 不换行
• style 引用 id 必须与节点定义 id 一致
• 长标签文字超过 20 字时截短或换行
• sequenceDiagram 参与者命名简洁，用中文业务名称

HTML 模板使用方式

参考 assets/briefing-template.html，该文件包含：

• 完整 CSS 变量系统和样式（或引用 briefing-ui.css）
• Mermaid.js CDN 引入和初始化配置
• 图表全屏 + 缩放 + 拖拽 JS 交互（或引用 briefing-ui.js）
• 5 个章节的骨架结构（含注释标注填充位置）

生成流程：读取模板 → 替换占位符（标题、各章节内容）→ 写入目标文件

质量检查

生成文件前自检：

1. 每张 Mermaid 图的语法是否正确（无嵌套引号、无中文 subgraph id、无非法字符）
2. stateDiagram 中是否有 \n 未替换
3. 所有 style 引用的节点 id 是否与定义一致
4. 外部系统交互时序图是否只写业务交互、不写技术细节
5. 核心要点卡片是否有 6 条以上

图表交互规范

生成的 HTML 页面中，每张 Mermaid 图表必须支持以下交互：

缩放

• 鼠标悬浮图表 → 右上角出现「－」「＋」「1:1」按钮
• 点击「＋/－」缩放，范围 0.4x ～ 3.0x，步进 0.15
• 点击「1:1」重置为原始比例
• 鼠标滚轮缩放：在图表区域滚动鼠标滚轮也可缩放（步进 0.1）

拖拽移动

• 缩放后图表超出容器时，支持鼠标拖拽移动查看（按住左键拖动）
• 移动端支持触摸拖拽（单指滑动）和双指缩放
• 拖拽时光标变为 grabbing，释放后恢复 grab
• 拖拽范围不限，用户可自由平移查看任意区域

全屏

• 点击「⛶ 全屏」按钮 → 图表铺满整个视口（100vw × 100vh），黑色背景
• 全屏模式下同样支持缩放和拖拽移动
• 关闭方式：按 ESC / 点击右上角 ✕ / 点击黑色背景
• 全屏提示文字：「滚轮缩放 · 拖拽移动 · ESC 退出」

通用性与分享

本 Skill 完全通用，无任何本地依赖：

• 唯一外部依赖：Mermaid.js v10（CDN: https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js），需公网访问
• 无后端服务、无本地脚本、无系统环境要求
• 生成的 HTML 引用 briefing-ui.css + briefing-ui.js 共用资源

分享方式

1. 手动分享：将 ~/.workbuddy/skills/feature-briefing/ 目录打包为 zip，对方解压到 ~/.workbuddy/skills/ 即可使用
2. SkillHub 上传：使用 skill-creator/scripts/package_skill.py 打包后上传（如 WorkBuddy 支持）

交付标准

• 文件已写入目标路径
• 用 preview_url（若本地有 HTTP 服务）或 deliver_attachments 交付给用户
• 告知用户：图表支持滚轮缩放、拖拽移动、全屏查看