visualize

可视化

概述

根据仓库文档、Markdown 文件、标准化计划文件夹和任意用户上下文，创建与源文件相邻的 HTML 可视化内容。此技能的工作流程规范借鉴了 Huashu，但专注于文档：将真实源材料转化为易读的地图、时间线、流程、风险区块和建议图表。

范围

在以下场景中使用此技能：

• 文档和 Markdown 可视化
• 标准化计划文件夹可视化
• 流程图、图表、Mermaid、上下文地图和建议图表请求
• 帮助用户检查结构、风险、决策和后续步骤的源文件相邻 HTML 摘要

请勿在以下场景中使用此技能：

• 品牌网站或营销页面
• 产品原型或生产级 Web 应用
• 幻灯片、长篇动态演示或广泛的视觉设计系统

输出约定

• 计划文件夹：在计划文件夹内创建 visualize.html 和 visualize-assets/。
• 头脑风暴文件夹：在头脑风暴文件夹内创建 visualize.html 和 visualize-assets/。
• 与活动计划或头脑风暴工件文件夹关联的当前上下文：在该工件文件夹内创建 visualize.html 和 visualize-assets/。
• Markdown 或文档文件：在源文件旁创建 <source-base>.visualize.html 和 <source-base>.visualize-assets/。
• 没有关联工件文件夹的源文件缺失上下文：创建 docs/.visualizations/<slug>-YYMMDD-HHmm/visualize.html 和 docs/.visualizations/<slug>-YYMMDD-HHmm/visualize-assets/，除非用户指定了目标位置。使用 date +%y%m%d-%H%M 生成时间戳。

始终将 references/templates/visualize-theme.css 复制到相邻的 assets 文件夹，并在生成的 HTML 中链接复制后的本地 CSS。图表可以使用 Mermaid CDN。

工作流

1. 可视化仓库文件时，加载项目上下文（如果当前会话尚未加载）。
   • 如果存在 docs/SUMMARY.md，先阅读。
   • 仅加载与任务相关的详细文档。
   • 实现约定优先参考 Code Standard 文档。
   • 如果文档与代码或用户意图冲突，请使用可用的输入/提问工具，再进行大范围更改。
2. 加载源材料。
   • 对于计划文件夹，阅读 SUMMARY.md 和相关的 phase-XX-*.md 文件。
   • 对于头脑风暴文件夹，阅读 SUMMARY.md 和相关的 section-XX-*.md 文件。
   • 对于 Markdown 或文档文件，直接阅读指定源文件。
   • 对于与当前计划或头脑风暴产物文件夹相关的当前上下文，将对话/请求内容与产物文件夹一并用作输出目标。
   • 对于没有关联产物文件夹的无源文件用户上下文，仅使用提供的对话/请求内容。
3. 确定可视化意图。
   • 判断用户需要的是计划地图、文档地图、流程图、决策视图、建议视图，还是混合可视化。
   • 仅当无法安全判断源内容、目标或输出时，才使用输入/提问工具询问。
4. 选择布局前，先构建精简的源内容清单。
   • 使用 references/workflow.md 和 references/content-patterns.md。
   • 梳理源内容的层级、实体或文件、阶段或任务、依赖项、决策、风险、阻塞事项、建议、验证步骤，以及存在时的缺失证据。
   • 将模板视为框架。只有在某个区块能概括源内容、厘清关系或指出重要缺口时，才将其纳入输出。
5. 使用 references/router.md 选择模板。
   • 计划文件夹使用 references/templates/plan.html。
   • 头脑风暴文件夹使用 references/templates/context.html。
   • 单篇文档使用 references/templates/document.html。
   • 无源文件上下文使用 references/templates/context.html。
6. 将事实和假设提取到选定的区块集合中。
   • 保留源内容中的事实、文件路径、状态、风险、决策、验证步骤和建议。
   • 如果源内容存在缺口，清楚标明假设。
7. 编写 HTML。
   • 从选定的模板开始。
   • 将 VISUALIZE: 标记区域替换为有源内容依据的内容，并移除无必要的区块。
   • 将源内容衍生的文本插入 HTML 前进行转义，除非该文本是有意编写的生成标记。
   • 在链接前，将 visualize-theme.css 复制到输出文件旁。
8. 在能帮助说明结构时添加 Mermaid 图表。
   • 使用 references/mermaid-recipes.md。
   • 优先采用多个小图表，避免使用一个密集的大图表。
   • 如果图表只是重复标题或附近的文字说明，则不使用 Mermaid。
   • 如果无法确定 Mermaid 语法，请使用易读的 HTML/CSS 备用区块。
9. 使用 references/verification.md 验证输出。

规则

• 不得编造事实、虚假指标、虚假决策、虚假用户、无依据的约束或建议。
• 不得掩盖源内容缺失。应添加假设或警告区块。
• 保持可视化内容客观、贴近源内容且易于检查。
• 模板和生成的 HTML 应专注于文档可视化，而非宽泛的设计/原型工作。
• 避免使用大型内联样式区块；应使用复制的固定主题 CSS。
• 写入 HTML 前，对源内容衍生的文本进行转义，除非它是由 Agent 有意编写的生成标记。
• 保留有助于用户追溯内容来源的源链接和路径。