yokingma/flow-diagram

流程图

流程图是用于可执行系统和流程图表的创作技能：一次创作，即可播放、嵌入、检查并导出结果。

将描述和源材料转化为可视化解释：静态或动画图表，使结构、关系和流程清晰易懂。目标是保留源信息含义，帮助读者理解事物的组织方式、关联及随时间的变化。

选择任务

此技能生成图表资产；PPTX 文件和原生 PowerPoint 形状不在其范围内。

确定任务类型、要使用的输入，以及进入或恢复流程的起点。

请求	起点
新图表或需要创作或修订的 JSON 导入	完成偏好预检，然后遵循所有五个步骤。必要时保留未更改的导入字节。
用于导出或检查的未更改 JSON 导入	使用导出或诊断入口点；跳过偏好预检并保留输入设计。
修订已完成的图表	读取现有图表和最终报告。确定请求的更改和范围，完成偏好预检，然后遵循五步流程，重用仍然有效的设计决策。除非用户更改，否则保留请求的格式。
仅添加导出格式	在步骤 3 进入，保持现有图表不变。跳过草稿、样式、测量和布局更改，然后检查并生成请求的文件。
继续未完成的任务	读取任务记录并选择已保存的修订版以继续。从未完成的步骤或受更改影响的步骤恢复。
仅验证或诊断	使用 validate 进行结构检查。如果请求视觉诊断，请遵循步骤 4 中适用的检查工作流程。报告执行的检查、其限制以及发现的问题，然后停止。

对于独立的保存、更改或重置请求，请遵循项目偏好并报告操作，而不创建图表。

对于现有图表的导入、修订或导出，请阅读输入和父级选择。在创建任务文件之前，请阅读任务工作区要求；对于验证命令和报告状态，请阅读运行时和结果合约。

在输入、授权更改和流程入口点明确后继续。

流程

0. 初始化设计偏好

对于新草稿和修订草稿，在步骤 1 之前遵循项目偏好。通过解决相关的视觉选择并记录其来源来完成其预检；完成任何请求的保存或报告其失败。独立的偏好管理请求使用该参考，并在报告操作后停止。纯导出、验证和诊断任务保持其现有入口点。恢复未完成的任务，使用其记录的决定，仅在相关选择发生变化时重新访问预检。

1. 定义解释目标

从读者的问题开始：读者在查看图表后应该理解什么？使用此问题指导后续的内容、布局和动画决策。

• 定义问题。 确定主题以及读者应从用户的请求中理解什么。

• 确定事实。 在授权范围内阅读用户指定的源或现有图表。识别相关的对象、关系、流程和状态变化。区分已知事实和需要澄清的信息，并通过源元数据记录来源。

  对于广泛的调查，例如探索代码仓库，生成一个子代理来调查与读者问题相关的部分。向子代理提供问题和授权源范围。请求相关的对象、关系、流程和状态变化，并附上源位置和未解决的问题。使用这些发现来建立解释所需的事实。

  对于少数文章、一小套参考资料或简短请求（例如“用流程图解释 RAG 工作流程”），在当前会话中确定事实。

• 记录要求。 捕获用户已指定的受众、使用上下文和交付要求。遵循缺失的交付上下文以重用已知选择，一次性收集相关差距，并在选择几何形状之前记录采用的假设。

在能够用一句话陈述读者问题并确定支持答案的事实后继续。在草稿之前澄清会改变图表含义的信息空白。如果 SDK 无法忠实地表达请求，请解释限制并等待用户选择。

2. 设计可视化解释

选择如何呈现主题，使读者能够回答步骤 1 中定义的问题。

对于新草稿或修订草稿，在选择画布和密度之前阅读交付上下文，包括当目的未知时。对于能力清单、职责、资源状态、请求和响应、状态转换、数据处理或架构，请使用读者问题选择表。

• 选择内容。 选择解释所需的对象、关系、流程和状态。在省略或聚合内容，或决定如何呈现未知源信息之前，请阅读源保真度和信息选择。在这些选择中保留源含义。
• 将内容分配到其表面。 在图表几何形状之前，遵循内容放置以分配页面介绍、图表绑定标签、标题和支持性散文。记录分配以及每种请求格式所需的上下文。
• 组织结构。 定义组、层次结构和阅读顺序，以便读者能够识别要点并理解它们之间的关系。
• 设置视觉方向。 遵循视觉设计为使用上下文选择方向。对于带有侧边栏的分层结构、带有分支或返回的流程，或带有较长内容的重复卡片，请选择一个适用的构图配方。记录生产所需的具体选择。
• 选择静态图表或动画。 使用静态布局解释结构和关系。对于动画，区分持久关系流、注意力和阶段性变化；对流动线条的请求可以保持整个图表可见。
• 规划动画叙事。 在使用动画时，遵循动画节奏和视觉连续性来定义每个阶段的解释目标、状态变化、过渡和阅读暂停。

在计划记录了所选内容、其承载表面、组、阅读顺序、视觉选择以及静态或动画呈现后继续。对于动画，包括阶段计划。

3. 创建图表

实现步骤 2 中的设计，并生成步骤 4 检查所需的人工制品。

使用 Node 20+ 和 npm。从用户选择的工作目录运行 node <skill-directory>/scripts/flowsvg.mjs，必要时使用引号路径。在此已安装的技能内解析工具和任务资源。CLI 准备其自己固定的 SDK 运行时，而无需更改应用程序依赖项。

• 阅读相关的创作指南。 对于新草稿或修订草稿，阅读文档模型和布局指南，并实现所选设计配方。在安排几何形状之前，检查渲染陷阱，了解带有长标签的短路径、侧边栏、无边框文本、窄卡片或任何语言中的换行风险、短标签光学对齐、共享阅读边或更改的内容大小。对于动画，还需阅读场景、继承状态和时间。对于请求的 SVG、PNG 或 GIF 文件，阅读导出选项和限制。
• 构建图表文档。 对于新草稿或修订草稿，实现计划的对象、组、连接、文本和动画阶段。保留源语言和选定的视觉方向。对于没有指定方向的新图表，从浅色主题和圆角组开始。在完整草稿上测量文本，并遵循布局计划工作流程当重复的几何形状需要计划时。将每个对象、关系方向、父边界和状态变化与源进行比较。在新的工作区草稿中保存授权的更改；对于未更改的导入或导出，直接使用选定的输入字节。
• 验证和更正。 在迭代期间使用只读 validate 并读取每个诊断。它返回确切的输入身份和有限检查，而不创建图表修订版；保留工作草稿。在当前授权内应用更正，遵循诊断和修订决策。向用户澄清会改变解释含义的更正。
• 编写 HTML 页面。 对于新或修订的 HTML 解释，为分配到图表之外的内容编写页面 HTML/CSS，并通过可编辑 HTML 页面提交。对于现有结果，遵循页面延续以保留其设计并明确同步预期的图表更改。在有用时重用已安装的起始页用于新页面；保留托管的播放器区域，并将完整页面保留在任务工作区中。
• 生成检查人工制品。 在浏览器捕获或选择预览样本数量之前，阅读浏览器准备和采样。使用 author 生成所需的离线 HTML、所需预览和请求的导出文件。当仅需要中间 HTML 时，使用 author --browser none。对于几个命名的静态状态，遵循命名批量导出；在绑定清单之前，与用户确认从实际编译节拍中选择的时间。遵循运行时和结果合约进行设置、SDK 兼容性和报告字段；使用 CLI --help 获取命令选项。

在草稿实现了计划，或保留了未更改的输入，阻止错误已解决，剩余诊断已记录处理决策，并且检查所需的所有文件完整后继续。导出失败时，遵循下面的恢复规则并分别报告已完成和未完成的文件。

4. 检查结果

对于已交付的 SVG/PNG，遵循按需工件证据：对明确的已保存主题运行 evidence，然后查看并独立审查其图像。现有有效条件被重用；新条件在检查前保持未查看状态。

查看生成的图表并确认其准确、清晰地解释了主题。

• 检查语义准确性。 将对象、关系方向、组边界和状态变化与源进行比较。确认省略和聚合保留了源含义。
• 检查视觉可读性。 以预期的显示尺寸查看实际渲染的图像。检查文本、间距、遮挡和阅读顺序。跟踪每个相关连接从源头经过弯曲和交叉点到箭头；检查端口、标签以及与无关节点的间距。
• 评估视觉设计。 遵循视觉设计检查以识别可见缺陷并记录观察结果供用户最终设计判断。
• 检查动画解释。 对于动画，根据阶段计划检查初始状态、关键变化和最终状态。遵循已采样状态的预览检查。在评估节奏时使用实际播放；将仅样本检查报告为仅限于所查看状态。
• 检查交付的文件。 让工具打开实际保存的离线 HTML，并检查其初始暂停状态、控件、离线请求和相关播放状态。通过HTML 检查工作流程查看其捕获的图像。检查交付的请求导出文件；对最终 SVG/PNG 文件使用目标大小工件检查。

在提交审查之前，阅读完整的审查输入合同和模板工作流程。使用 review-template 从明确的图表主题生成未查看的表单，对于单独的正式证据，使用 --evidence-from，然后使用独立的 review 对 HTML、预览和正式 SVG/PNG 进行观察，并仅记录实际查看的图像 ID、哈希、观察和问题。重复提交审查不需要另一个图表版本。当浏览器或图像查看器不可用时，明确记录未执行的检查及其影响。

对于发现的问题，返回步骤 3 应用授权的更正，重新生成工件，并再次检查受影响的文件和状态。在记录问题或澄清含义时，遵循诊断和修订决策。