plannotator-visual-explainer

Plannotator Visual Explainer

根据内容类型选择三种路径。每种路径都有自己的参考资料和结构。

按内容类型选择路径

实现计划、设计文档或提案 → 遵循 计划路径。阅读 references/design-system.md 和 references/svg-patterns.md。采用规范化结构。

PR 说明、差异审查或代码变更演练 → 遵循 PR 路径。阅读 references/design-system.md 和 references/pr-components.md。采用规范化结构。

其他所有内容（架构图、数据表、幻灯片、项目回顾、一般性视觉说明）→ 遵循 视觉说明路径。委托给 nicobailon/visual-explainer，并使用 Plannotator 主题令牌。

交付

始终通过 Plannotator 的批注界面交付。不要使用 open 或 xdg-open。

对于任何使用 Mermaid 的交付内容，在打开批注界面前，必须先使用 Mermaid 12 分别在浅色和深色主题中渲染每张图。渲染是硬性门槛：出现异常、空 SVG，或 aria-roledescription="error"、Syntax error in text 等错误输出，都意味着说明内容不可交付。修复图表或主题配置，然后重新渲染两种主题，直到每个 SVG 都通过检查。

对于可缩放的图表外壳，还需在两种主题中分别缩放至最大并平移到所有极限位置，然后再交付：整个过程中，图注必须始终清晰可读（参见 references/diagram-shell.md）。

计划/提案（用户应批准或拒绝）：

plannotator annotate <file> --gate

其他所有内容（信息性）：

plannotator annotate <file>

---

计划路径

适用于实现计划、设计文档、功能规格、迁移指南和提案。

生成前请阅读：

1. references/design-system.md — Plannotator 主题令牌、排版和组件模式
2. references/svg-patterns.md — 用于架构图、流程图和数据流的内嵌 SVG 构件

文档结构（按顺序，按需选择）：

1. 页眉 — 眉题标签（等宽字体、大写）、标题（大号衬线字体）、提示框（原始需求说明）
2. 摘要栏 — 3-5 张统计卡片，一目了然地展示关键数字（组件、端点、表等）
3. 里程碑/时间线 — 垂直时间线，展示各阶段，但不提供时间估算。阶段展示顺序和依赖关系，而非持续时间。
4. 架构/数据流 — 内嵌 SVG 图。适用于 3 个及以上组件交互的场景。新组件使用高亮框，异步路径使用虚线箭头。
5. 模拟图 — 直接用 HTML/CSS 构建 UI 模拟图，而不是用文字描述
6. 关键代码 — 使用深色主题并带语法高亮的代码块。仅包含架构上重要的接口/架构，不必涵盖每个函数。
7. 风险与缓解措施 — 带严重性徽标（HIGH/MED/LOW）的表格
8. 待解决问题 — 附带决策负责人说明的提示卡片（“与以下人员共同决定：后端团队”）

并非每个计划都需要包含所有部分。跳过不适用于内容的部分。绝不包含时间估算、套话式章节或详尽的文件列表。

根据任务调整： 后端 → 以数据流为主。前端 → 以模拟图为主。重构 → 以改造前后对比图为主。基础设施 → 以架构为主。

质量标准： 计划应让读者在 30 秒内读懂“做什么、为什么做以及怎么做”。留白也是设计的一部分——每个视口只呈现一个要点。

PR 路径

适用于 PR 演练、差异审查、代码变更说明和审查者指南。

生成前，请阅读：

1. references/design-system.md — Plannotator 主题令牌、字体排印、组件模式
2. references/pr-components.md — 差异渲染、审查评论气泡、风险标签、文件卡片、前后对比面板

文档结构（按顺序选择合适内容）：

1. 标题 — PR 标题、元信息栏（文件数、增减行数、分支、作者）
2. TL;DR — 左侧带主强调色边框的卡片。用 2-3 句话概述。即使读者不看其他内容，也应能了解要点。
3. 原因 — 动机及前后对比（两栏网格）
4. 文件导览 — 每个文件使用可折叠卡片。每张卡片包含：文件路径和徽标（NEW/MOD/DEL）+ 行数统计、一段“原因”说明，以及重要的差异块。高风险文件展开，安全文件折叠。
5. 风险图 — 使用可视化标签标出哪些文件需要仔细审查，哪些属于机械性变更。分为三个等级：注意（破坏性）、中等（警告）、安全（成功）。
6. 重点关注 — 使用编号的提示卡片。每张卡片指出文件/函数，并描述相关问题。
7. 测试计划 — 复选框样式的验证清单
8. 部署（如适用）— 分阶段部署及功能标志

使用来自 CDN 的 Pierre 差异来呈现带语法高亮的内联差异 — 模式参见 references/pr-components.md。

---

可视化说明路径

适用于架构图、数据表、幻灯片、项目回顾、比较，以及其他任何可视化说明。

生成前：

1. 确保已安装 visual-explainer：
   • 检查：~/.claude/skills/visual-explainer/SKILL.md 或 ~/.agents/skills/visual-explainer/SKILL.md
   • 如果未找到：不要自行安装。请停下来询问对方是否要安装，并展示完整命令： npx skills add nicobailon/visual-explainer -g --yes 只有在对方同意后才运行（对方的“同意”即为授权；如果没有 --yes，安装程序会等待输入，而你的 Shell 无法提供输入）。如果对方愿意，也可以自行运行该命令。如果对方拒绝，请说明此路径需要 visual-explainer，然后停止。Plan 和 PR 路径不需要它，无需安装也能使用。
2. 阅读 visual-explainer 的 SKILL.md（工作流、图表类型、反低质规则）
3. 阅读适用于内容类型的 visual-explainer 参考资料和模板
4. 阅读 references/theme-override.md — 用 Plannotator 令牌替换 Nico 的调色板
5. 对于带控件和说明文字、可缩放的 Mermaid 图表：阅读 references/diagram-shell.md 并复制其中的外壳 — 不要自行编写视口、画布或说明文字标记

遵循 visual-explainer 的结构、组件类（.ve-card、.kpi-card、.pipeline）和反低质规则。覆盖内容是颜色/字体排印层 — 使用 Plannotator 令牌替代 Nico 的自定义调色板 — 如果交付内容包含可缩放图表，还需使用 references/diagram-shell.md 中的图表外壳。

---

设计理念（适用于所有路径）

• 留白是一项特性。 使用宽裕的内边距和较大的区块间距。如果显得拥挤，就增加空间 — 不要缩小文字。
• 每个视口只呈现一个想法。 先是主视觉区，然后是图表，再是详细网格 — 不要把所有内容都塞在一起。
• 展示，而非描述。 用时间线展示顺序，用图表展示关系，用代码块展示接口。
• 不要估算时间。 时间线展示阶段和依赖关系。绝不附上小时/天数估算。