图表生成

生成自包含的 HTML 架构图表。在创建 Pull Request、任务计划或架构解释的可视化图表时使用。

文件预览

3 个文件

SKILL.md

2.6 KB · 可预览

---
name: diagram-generation
description: Generate self-contained HTML architecture diagrams. Use when creating visual diagrams for PRs, task plans, or architectural explanations.
---

# Diagram Generation

Generate self-contained HTML diagrams that visualize code changes, data flows, and architecture decisions.

## When to Use

- Visualizing PR changes for code review
- Explaining architectural decisions
- Documenting data/request flows
- Illustrating before/after comparisons

## Output

- Self-contained HTML file at `{MAIN_REPO_ROOT}/diagrams/opik-{TICKET_NUMBER}-diagram.html` — always resolved against the main repo root (via `git rev-parse --git-common-dir`), even when the session runs inside a worktree, so the file outlives the worktree
- Includes "Copy as image" button for sharing in Slack, Jira, PR descriptions
- Dark GitHub theme, semantic color coding, responsive layout

## How to Generate

Follow the style guide in `style-guide.md` and use the HTML template in `template.md`.

### Required Sections (pick what applies)

1. **Request / Data Flow** — how data moves through layers
2. **Why This Approach** — problem vs solution comparison
3. **Files Changed by Layer** — grid of affected files grouped by component
4. **Key Design Decisions** — numbered guards, trade-offs, or constraints

### Section Selection

- **Bug fix**: Focus on before/after flow, root cause, safety guards
- **New feature**: Focus on data flow, architecture, files changed
- **Refactor**: Focus on before/after architecture, files changed
- **Cross-component**: Show all layers with connecting flows

## Reference Files

- [style-guide.md](style-guide.md) — Semantic colors, box themes, section labels, flow patterns, architecture trees
- [template.md](template.md) — Base HTML structure, copy-as-image script, section recipes

## Common Gotchas

- **SRI hash on CDN scripts**: The html2canvas `<script>` tag must include `integrity` and `crossorigin` attributes — see template.md for the current hash
- **Absolute paths for Playwright screenshots**: Playwright saves relative to its own CWD, not the repo root — always use absolute paths when calling `browser_take_screenshot`
- **Max 4 sections**: More than 4 sections makes diagrams too tall for screenshots and hard to scan visually
- **No raw diff content**: Diagrams show high-level summaries (component names, file names, flow descriptions) — never embed verbatim diff hunks or Jira comments
- **`toBlob` can return null**: The Canvas `toBlob` call in the copy-as-image script needs a null check — see template.md

SKILL.md

raw

元数据

name	diagram-generation
description	生成自包含的 HTML 架构图表。在创建 Pull Request、任务计划或架构解释的可视化图表时使用。

图表生成 生成自包含的 HTML 图表，用于可视化代码变更、数据流和架构决策。 使用场景 为代码评审可视化 PR 变更 解释架构决策 记录数据/请求流 展示前后对比 输出 自包含的 HTML 文件，位于 {MAIN_REPO_ROOT}/diagrams/opik-{TICKET_NUMBER}-diagram.html — 始终相对于主仓库根目录解析（通过 git rev-parse --git-common-dir），即使会话运行在工作树中，文件仍能在工作树之外持久存在 包含“复制为图片”按钮，便于在 Slack、Jira 和 PR 描述中分享 深色 GitHub 主题，语义色彩编码，响应式布局 如何生成 遵循 style-guide.md 中的样式指南，并使用 template.md 中的 HTML 模板。 必需的章节（根据需要选择） 请求/数据流 — 数据如何在各层之间流动 为什么采用这种方法 — 问题与解决方案的对比 按层划分的变更文件 — 按组件分组的受影响文件网格 关键设计决策 — 编号的防护点、权衡或约束 章节选择 Bug 修复：侧重于修复前后的流程、根本原因、安全防护 新功能：侧重于数据流、架构、变更的文件 重构：侧重于重构前后的架构、变更的文件 跨组件：展示所有层及其连接流 参考文件 style-guide.md — 语义颜色、盒子主题、章节标签、流式模式、架构树 template.md — 基础 HTML 结构、复制为图片脚本、章节配方 常见陷阱 CDN 脚本的 SRI 哈希：html2canvas 的 <script> 标签必须包含 integrity 和 crossorigin 属性 — 参考 template.md 获取当前哈希值 Playwright 截图的绝对路径：Playwright 相对于其自身的工作目录保存，而非仓库根目录 — 调用 browser_take_screenshot 时务必使用绝对路径 最多 4 个章节：超过 4 个章节会使图表过高，不利于截图，视觉上难以扫读 不要包含原始 diff 内容：图表展示高级摘要（组件名称、文件名、流程描述） — 切勿嵌入逐字 diff 片段或 Jira 评论 toBlob 可能返回 null：复制为图片脚本中的 Canvas toBlob 调用需要进行 null 检查 — 参考 template.md