Communitygithub.com

工作简报

以可视化的HTML简报(流程图、应用前后对比截图、决策、文件地图、差异片段、验证证据)为用户讲解已完成的工作,同时保留聊天中的常规文字总结。适用于任何仓库。

工作简报 是什么?

工作简报(Work Brochure)技能旨在为开发者提供一份自包含的HTML页面,以可视化方式展示已完成的代码变更或拉取请求(PR)。它不替代聊天中的常规文字总结,而是补充图形化内容,例如流程图、前后对比截图、决策表、文件变更地图、差异代码片段和验证结果。该技能通过运行仓库根目录下的 `gather.sh` 脚本获取提交、差异统计、未暂存更改和PR信息,然后根据变更类型选择最适合的可视化形式(如Mermaid流程图用于逻辑变更,序列图用于API交互,截图用于UI变更)。简报生成后,会保存在 `.claude/work-briefs/` 目录下,并通过私密Artifact发布以确保持久性。该技能在PR创建、功能完成或用户明确要求(如调用 `/work-brochure`)时自动触发,对于一行代码的微调或纯问答场景则跳过。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lincolncrooks/work-brochure/tree/HEAD/skills/work-brochure

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

工作简报 是做什么的?

完成一项工作后,用户期望两件事:

  1. 聊天中的常规总结,与你平时写的完全一样(更改了什么、当前状态、未完成事项)。此技能从不替代或缩短它。
  2. 一份简报:一个自包含的HTML页面,以可视化方式展示同样的工作,用户可将其放在聊天窗口旁,通过图表、截图和带注释的代码(而非段落)来理解变更。

简报必须与代码精确一致。所有声明、数字、文件路径和截图都必须来源于实际的差异、你运行的命令以及你查看的应用。切勿编造未运行的测试或未见过的结果。

步骤

1. 先写聊天总结

像往常一样完成工作,包括常规的文字总结和 wrap_up(如果应用支持)。然后构建简报。如果用户仅要求对之前的工作做简报,直接跳到步骤2。

当PR打开后(插件的PostToolUse钩子,或你在设置中添加的钩子,在 gh pr create 之后会添加提醒),在同一轮中为那个PR构建简报:运行 gather.sh --pr <N>,并在你的结束消息中放入简报链接。除非用户要求,否则不要编辑PR正文来添加它。仅当PR是微不足道的一行改动(如拼写错误、版本号更新)时跳过。

2. 收集事实

从仓库根目录运行辅助脚本(它会打印提交、按文件夹分组的每个文件的差异统计、未暂存的更改和PR信息):

bash <skill-dir>/scripts/gather.sh            # 当前分支 vs main + 未暂存更改
bash <skill-dir>/scripts/gather.sh A..B       # 任何git范围(例如已合并的工作)
bash <skill-dir>/scripts/gather.sh --pr 51    # 一个GitHub PR

然后阅读差异中重要的部分(git diff <范围> -- <路径>),而不是全部。同时从本次对话中收集:

  • 原因:用户自己描述的问题或请求。
  • 决策:你权衡过的选项以及选择当前方案的原因。
  • 验证:运行的命令及其真实输出、已截取的屏幕截图、在浏览器或模拟器中检查的内容,以及你无法验证的内容。
  • 未尽事宜:后续工作、风险、任何未完成的事项。
  • 需要用户:只能由用户决定、目视检查或批准的内容。

3. 捕获真实应用(当变更可见时)

如果变更在UI中可见,简报应展示实际应用程序,而不是描述。

  • 变更后:使用预览工具(preview_start 配合项目的 launch.json 服务器,导航,computer {action: "screenshot"}),或iOS模拟器的 screenshot,对变更后的屏幕截图。当布局发生变化时,同时捕获桌面和手机宽度的截图。
  • 变更前:如果差异是关键,将基础版本签出到暂存区的临时工作树中(git worktree add <scratchpad>/before <base>),在不同的端口上提供服务,对同一视图截图,然后移除工作树(git worktree remove)。当变更是纯新增或“之前”状态无意义时,跳过此步骤。
  • 将截图保存为暂存区中的文件,缩小图片(sips -Z 1400 -s format jpeg -s formatOptions 78 in.png --out out.jpg),并以 data: URI 的形式嵌入。保持整个页面在约8 MB以下。
  • 对于视频/动画变更,嵌入几张静态帧(ffmpeg -ss <t> -i clip.mp4 -frames:v 1 -vf scale=900:-1 still.jpg)或一个帧条,以及测量到的数字。
  • 非视觉变更(脚本、数据、后端)使用图表和真实输出来代替截图。

4. 规划叙述顺序,然后选择可视化元素

按照用户期望的讲解顺序排列页面:先讲结果,再讲工作原理,最后讲细节。根据变更内容选择可视化元素。能用图片更快解释的地方优先使用图片;文字保持简短的标题和一至三句话的段落。

变更内容使用的可视化元素
逻辑、流程、决策规则新流程的Mermaid flowchart;使用 classDef changed 高亮新增/变更的节点
各部分之间的请求(UI → API → 存储)Mermaid sequenceDiagram
结构(模块、文件、数据形状)带有 +/− 条的文件地图;展示各部分连接方式的Mermaid graph;变更前后字段对比表
UI变更前后截图对比对;在图片上放置带编号的标注点
数字(时间、大小、数量、性能)按比例绘制的内联SVG柱状图,变更前 vs 变更后
状态或生命周期Mermaid stateDiagram-v2
工作序列(迁移、多步骤变更)编号的操作步骤(仅在顺序真实存在时使用)
关键代码短小的差异片段(5–25行),标记重要行,放在 <details> 内以免占据过多空间

对于特性大小的变更,至少设计三个不同的可视化元素;对于较小的变更,至少一个。图表必须描述真实的机制(真实的函数名、文件名、值),而非泛泛的方框。

5. 从模板构建页面

复制 <skill-dir>/template.html 并填充内容。它已包含速写本风格(刻意使用一种亮色主题:方格纸背景、手写风格标题、铅笔素描卡片、手绘图表)、布局和上述所有组件。除非用户要求,否则不要添加暗色模式或改换风格。规则:

  • 保留 <style> 块和Mermaid加载脚本;替换示例内容。删除不适用的部分,而非留空(例如,纯重构情况下不要保留“变更前 → 变更后”)。
  • <title>:特性的名称,两到四个词(例如“结账重试逻辑”),而非“工作总结:……”。
  • Hero区:一句话说明结果,元信息行(分支、PR链接、日期),以及统计条(文件数、行数 +/−、提交数、检查通过数)。数字从 gather.sh 计算得出,不要估算。
  • 需要你的输入(Hero下方的便签):仅列出等待用户的真实请求,每行一个,说明在哪里查看。最多三项。没有时删除整个便签;切勿填充它。
  • 为何选择此方案(决策表):本次会话中实际权衡的两到四个选项,其中一个标记为“已选”,每个选项一行利弊。不要为了填充而编造备选方案;如果没有真正的决策,删除该部分。
  • 保持页面精简:上述两个部分加上确实需要的部分。不要添加模板之外的区域。
  • 文件地图:每个有意义的文件占一行(将生成的文件/二进制文件合并为一行),+/- 条宽度按最大文件总行数的百分比显示,外加一行通俗解释为什么该文件有变更。
  • 差异片段:转义 <、>、&。使用 class="add"、class="del" 或 class="hl"(重要的未变更行)标记行。
  • Mermaid 放在 <pre class="mermaid"> 中,在标签后直接跟上模板中的配置块(--- / config: / look: handDrawn / theme: neutral / ---),以确保无论是在本地文件还是 claude.ai 上,它都呈现为手绘风格。保留模板的 classDef changed fill:#dfe7ff,stroke:#1f4fd1,stroke-width:2px 行。在标签内转义 </> 为 &lt;/&gt;,对本次工作新增或变更的节点使用 class <ids> changed。保持每个图表约5–9个节点,以便一屏显示:将连续步骤合并到一个节点中,用 <br/> 显示详情行;较长的流程拆分为两个图表。短流程使用 flowchart LR,分支流程使用 TD。
  • 验证:列出每次检查,附上通过/失败/未检查的状态标签及其证据(输出片段或截图)。当存在“未检查”项时,需要列出来。
  • 简明写作:短句,使用用户的术语,无废话。

将其保存为 <repo-root>/.claude/work-briefs/<YYYY-MM-DD>-<slug>.html。确保该文件夹不被git跟踪(无需修改其 .gitignore),通过一次性地将其添加到本地排除文件中:

mkdir -p .claude/work-briefs && x="$(git rev-parse --git-common-dir)/info/exclude" && (grep -qxF '.claude/work-briefs/' "$x" 2>/dev/null || echo '.claude/work-briefs/' >> "$x")

6. 检查一次,然后交付

  1. 在浏览器面板中打开一次(preview_start 使用 url: file://<路径>,或项目的静态服务器),并截一张图确认图表正确渲染且无溢出。修复这次查看发现的问题;不要循环。
  2. 在侧面板中展示:SendUserFile 使用 display: "render"。
  3. 将其发布为私密Artifact(Artifact 发布,使用文件路径、icon: "document",和一句描述),以便在工作树被清理后仍保留。这是持久副本;Artifact默认私密。如果没有可用的Artifact工具(例如纯终端会话),跳过此步骤并提供本地路径。
  4. 在聊天中,在你常规的总结之后,添加一行包含简报链接和本地文件路径的信息。

更新:如果用户要求修改,编辑同一文件并重新发布到同一路径,以便链接保持不变。

一份好的简报应具备的特点

  • 未参与会话的人能在滚动两分钟内理解发生了什么变更以及为什么。
  • 第一屏无需滚动就能回答“现在有什么不同?”。
  • 每个图表、表格和截图都来自本次变更。
  • 真实状态一目了然:哪些已验证,哪些未验证,还有哪些待办。

相关技能