SuperAPI AI 工具集

visualize

通用与其它

查看项目

更新于 10-17 16:13

技能介绍

Visualize 是一个用于生成独立 HTML 视图的技能(skill),其核心目的是把 Markdown 文档或用户请求转换成一个自包含的、可离线打开的 HTML 页面。整个技能强调保持 Markdown 源的权威性,不修改源文件,也不构建转换器、应用或运行时服务。

用途与两种模式

该技能支持两种工作模式:

  • Markdown 模式:当用户提供或指定了 Markdown 源时,将该 Markdown 呈现为派生的 HTML 视图。Markdown 仍是权威来源,HTML 只是其派生展示。
  • 直接模式:当没有提供或指定 Markdown 源时,直接从用户的请求和可用上下文中构建 HTML。此模式不需要也不创建中间 Markdown 文件。仅当请求缺少构建有用视图所需信息时才要求澄清。如果已指定的源缺失或不可读,不能静默切换到直接模式。

两种模式都不会创建新的需求、审批或验证生命周期。

主要能力

  • 读取完整的 Markdown 源,包括 front matter、表格、代码围栏、附录以及源要求读者使用的关联本地证据。
  • 按照请求的输出路径生成 HTML;若未指定,Markdown 模式下使用同目录同基名的 .html 文件,直接模式下在工作目录中使用简短的、基于主题的 .html 文件名。
  • 默认展示完整源内容,包括影响含义的每个章节、标识符、决策、审批记录、验证结果、限制和引用。仅当用户明确指定范围时才生成较窄的视图,并在 HTML 中说明包含与省略的章节。
  • 在 Markdown 模式下记录源路径、精确的 SHA-256 哈希以及当前 UTC 时间,使用 sha256sum 或 Python 标准库 hashlib,不得编造哈希或时间。生成后再次对源进行哈希校验;若源已变化,重新读取并重新构建视图。
  • 从 references/recipes.md 中选择配方(recipe),并在 HTML 中说明配方与覆盖范围。
  • 使用 assets/document-shell.html、assets/styles.css 以及 assets/blocks/ 中的适用片段组装页面,以 assets/gallery.html 作为视觉参考。
  • 保持支持性事实与提案、推断、未知项和示例之间的区分。在 Markdown 模式下,不创建源不支持的代码、差异、测试结果或图表边。在直接模式下,可以编写解释、提案、说明性代码和图表,但必须清晰标注,不得将其呈现为已提供的需求、现有实现、已验证的差异、执行结果或已批准的决策。
  • 对所有输入和生成的文本进行 HTML 上下文转义。代码和差异文本作为文本节点转义。源文本不得放入可执行上下文、事件处理器或 URL 属性中。
  • 所有页面样式放入一个内联 <style> 元素。图表使用内联 SVG,每个 SVG 拥有唯一 ID 前缀、<title>、<desc>、role="img" 和 aria-labelledby。图表事实保留在附近的可读文本中。若源包含图表文本(如 Mermaid 代码),以可见的转义文本块保留在 SVG 旁边,不执行它。
  • 不使用脚本、CDN 链接、外部样式表、网络字体、图片、嵌入内容或运行时资源,输出必须作为一个 HTML 文件离线工作。
  • 写入前检查输出文件是否已存在;若存在,不覆盖,先询问用户。用户不批准替换时保留现有文件。
  • 保持 HTML 与源分离,不将生成的标记写入 Markdown 文件。
  • 在 Markdown 模式下,每个生成的页面顶部附近显示源路径、源字节的 SHA-256 哈希、最终源哈希校验时间(UTC)、配方与覆盖范围(完整或明确的省略范围),以及仅在源中声明时的源审批或验证状态。说明哈希是在生成时校验的;静态 HTML 文件无法检测后续源变化,未经再次校验不得称视图为最新。
  • 在直接模式下,顶部附近说明“Direct HTML — no Markdown source supplied”,总结请求依据,展示配方与范围,列出使用的相关证据引用。不显示源路径、源哈希或源新鲜度声明。调整 document-shell.html:将 DERIVED VIEW 替换为 DIRECT HTML,使用基于请求的摘要,用直接模式记录替换源路径/哈希/校验时间面板,将 Markdown 权威页脚替换为说明页面直接基于请求构建、提案与示例不是审批或验证证据的注释。

使用方式

用户提供 Markdown 源或直接请求,并可选指定输出路径。技能首先确定模式与输出路径,在 Markdown 模式下还确定源路径并确认两者不同,然后读取完整源。接着记录源路径、SHA-256 哈希和 UTC 时间(直接模式记录请求依据与范围)。之后从 recipes.md 选择配方,用 document-shell.html、styles.css 和 blocks 片段组装页面。写入前检查输出是否已存在并询问替换。写入后检查 HTML 结构、内部链接、唯一 ID、SVG 标签、转义代码、模式特定元数据和运行时资源的缺失;在 Markdown 模式下再次哈希源并确认未变化。最后报告输出路径、模式、配方、覆盖范围、覆盖决策和已执行的检查;Markdown 模式还报告源路径与哈希,直接模式说明未提供 Markdown 源且未创建中间 Markdown。

适用场景

  • 需要将 Markdown 文档(如需求、决策记录、里程碑计划)展示为可离线分发的独立 HTML 页面。
  • 需要保留源文档的权威性、审批与验证证据,并明确区分派生视图与源。
  • 在没有 Markdown 源时,需要根据请求快速构建一个自包含的说明性 HTML 页面。
  • 需要生成无脚本、无外部依赖、可存档的单文件 HTML 输出。

限制

  • 不修改 Markdown 源,不更改其他技能、项目配置或依赖。
  • 不构建转换器、应用或运行时服务。
  • 不创建需求、审批或验证生命周期。
  • 不使用脚本、CDN、外部样式表、网络字体、图片、嵌入或运行时资源。
  • 不覆盖已存在的输出文件,除非用户批准。
  • 在 Markdown 模式下,不创建源不支持的代码、进度、任务状态、差异、测试结果或图表边。
  • 静态 HTML 无法检测生成后的源变化;未经再次哈希校验不得声称视图是最新的。
  • 具体配方列表、assets 内部结构等细节在提供的资料中未完全展开,暂未提供进一步说明。