目录

假设你向 AI 智能体询问实现某项功能的 3 种方法。它返回了一篇很长的 Markdown 回答：先是方法 A，接着是方法 B，然后是方法 C。为了确认哪个方案支持重试，你得向上滚动；为了比较复杂度，又得向下滚动。等到选定方案时，你很可能已经在脑中重新整理出了一张对比表。

不妨改为让它生成一个 HTML 文件。智能体可以把各个方案并排展示，将权衡取舍放在相关代码旁边，让差异在同一屏幕上一目了然。

这就是 HTML 的惊人实用性——实例集 ↗的基本思路。这个页面介绍了涵盖 9 类工作、共计 20 个示例，从实施计划到工单分类都有。每个示例都是无需构建的单文件页面。

真正有用的改变，只是稍微调整一下提问方式：不必每次都让智能体写一篇从头读到尾的文章，而是请它制作一个可供查看和操作的页面。

1. 探索与规划：确定方向前先做比较#

方向明确之后，Markdown 很好用。但在探索阶段，即使目的是比较，你仍然得按顺序阅读各个选项。

HTML 可以将这些选项放在同一屏幕上。这个页面提供了以下示例：

  • 3 种代码实现方案： 将 3 种解决方案并排展示，并为每种方案附上权衡取舍。
  • 视觉设计方向： 渲染不同的布局和配色方案，让你能够针对实际看到的效果提出意见。
  • 实施计划： 将里程碑、数据流图、界面模型、有风险的代码和风险清单整合成一份可用于实施的文档。

设计示例清楚地体现了这种优势。“配色低调、界面紧凑”这样的描述，仍然留有很大的解读空间。而实际渲染出的布局，可以让你具体判断是否采用。

比较代码时，请要求所有方案使用相同的小标题，例如依赖项、故障处理、预计工作范围和维护成本。否则，漂亮的卡片可能会掩盖比较标准不一致的问题。

先选定方向，再请智能体把这个选择转化为实施计划。

2. 代码审查与理解：把上下文放在代码旁边#

代码差异本身就是一种空间布局具有意义的文档。代码行的位置、相邻的修改、文件之间的关系都很重要。使用 Markdown 进行审查时，审查意见往往会与其所解释的代码分离。

HTML 可以把说明放在依据附近。

  • 带注释的拉取请求： 为差异添加页边注释、严重程度标签，以及指向相关位置的链接。
  • 面向审查者的 PR 说明： 解释修改动机、修改前后的行为、修改各个文件的原因，以及需要重点检查的位置。
  • 模块地图： 用方框和箭头描绘不熟悉的软件包，标出入口点和常用路径。

这些页面分别支持不同的阅读方式。带注释的差异有助于仔细检查修改，PR 说明有助于理解修改目的，模块地图则有助于在代码库中定位和浏览。

请要求智能体尽可能附上文件路径和行号。对于模块地图，请它区分已确认的调用关系和推测的关系。整齐的图表可能会让缺乏依据的假设也显得确凿可信。

让审查者能够从页面迅速找到原始代码。

3. 设计：查看实际效果#

在 Markdown 中列出颜色值，可以记录一套配色。但你无法据此看出这些颜色搭配在一起的效果。禁用状态的按钮也是如此，直接展示实物比文字描述更清楚。

HTML 可以利用浏览器，实际渲染正在讨论的内容。

  • 可实时查看的设计系统： 从代码仓库中提取颜色、字体排版和间距令牌，并将其展示为可复制的样例。
  • 组件变体： 将组件的尺寸、状态和预期用途集中展示在一个页面上。

审查组件时，请指定使用矩阵形式：列表示尺寸，行表示状态。在适用的情况下，还应包含加载中、禁用、聚焦和错误状态。

在浏览器中查看，更容易发现间距不一致或视觉区分不明显的问题。审查者之间也能有一个共同的参照。说“小尺寸、加载中的按钮”，比用一段文字描述按钮行为更能准确指出对象。

在将页面视为准确的参考资料之前，请将提取出的令牌与源文件核对。这是一个方便的快照，但是否持续更新，需要另行决定。

4. 原型设计：让人实际体验交互#

Markdown 可以描述页面切换的时长和缓动曲线，却无法让人感受到切换是否太慢。

HTML 可以制作小型交互实验。

  • 动画试验台： 单独提取一个过渡效果，添加用于调整时长和缓动的滑块。
  • 可点击的操作流程： 将 4 个页面连接起来，让人试用一整套操作。

这类原型应控制好范围。动画试验台用于回答有关动态效果的问题；可点击的操作流程用于确认用户是否知道下一步该做什么。

使用示例数据，并让重置操作足够简单。如果只是想检查页面之间的跳转，就不必添加身份验证、数据持久化或后端。

即使只连接 4 个页面，也能发现缺失的返回操作或令人困惑的确认步骤。这样就能在实现后修改成本上升之前发现问题。

5. 插图与图表：画出关系#

文字适合解释单个步骤。但当多条路径出现分支、汇合，或以不同方式失败时，就会变得难以追踪。

HTML 可以包含内联 SVG，因此智能体能够制作可编辑的插图和可交互的图表。

  • SVG 插图合集： 将文章所需的插图集中在一个页面上，方便逐一修改或提取。
  • 带注释的流程图： 展示部署流程，点击每个步骤即可查看执行内容、所需时间及失败后的处理方式。

对于部署图，请明确要求包含正常路径和失败路径。只展示成功步骤的图表，看起来可能很完整，却可能遗漏运维人员需要的信息。

重要标签应始终可见。不要隐藏基本流程，而应让补充信息在点击后展开。

需要修改标签或箭头时，内联 SVG 尤其方便。图形保留在文件中，无需重新生成单独的图片。

6. 幻灯片：把简短讲解做成浏览器页面#

Markdown 标题可以构成提纲，但会议也需要控制讲解节奏。应让参会者无需滚动整篇文档，就能看到当前正在讲解的要点。

用方向键操作的幻灯片示例，将单个 HTML 文件变成一份简短的演示文稿。每个章节成为一张幻灯片，通过少量 JavaScript 控制切换。你可以在幻灯片示例 ↗中查看这种做法。

有效的请求应包含受众、需要做出的决定，以及篇幅上限。例如：“请为一次 10 分钟的架构评审制作 6 张幻灯片，最后列出需要决定的事项。”

请提前在会议要使用的浏览器中打开文件，检查键盘操作是否正常。如果需要离线使用，请明确要求将所有样式、脚本和资源都包含在文件内。

7. 调研与学习：让读者自行调整讲解方式#

在冗长的 Markdown 说明中，即使读者各自带着不同的问题，也基本只能按相同的顺序阅读。

HTML 则允许读者展开细节、切换示例，或操作模型。

  • 功能原理： 通过摘要框、可折叠的处理阶段、标签页切换的配置示例和常见问题，解释代码仓库中的限流机制。
  • 概念讲解： 用一个允许读者添加和删除节点的环来讲解一致性哈希，再辅以对比表和带链接的术语表。

交互的价值在于让因果关系可见。从哈希环中删除一个节点时，应该展示哪些键会迁移，并说明原因。

解释代码仓库时，请要求提供相关代码的链接或引用。对于概念模型，请让智能体明确标出简化了哪些部分。可交互演示不必复现实际生产环境中的每个细节，也能解释清楚原理。

8. 报告：让定期信息一目了然#

周报和事故报告往往会重复使用相同的结构。Markdown 也能传达事实，但读者必须从段落中寻找延期、变更和未完成的工作。

HTML 可以让反复出现的信息每次都位于相同的位置。

  • 每周进度报告： 将已发布的工作与延期的工作分开，有数据时附上小型图表。
  • 事故时间线： 按分钟排列事件，并附上日志摘录和防止复发的检查清单。

每周使用相同的布局，读者就知道该看哪里。将报告周期放在顶部，为图表标注单位，并明确标出缺失的数据。

对于事故报告，应区分观测到的事件和事后的解释。带时间戳的日志与推测的原因，不应被同等对待。

格式能够帮助读者找到依据，却无法补足从未收集过的依据。

9. 专用编辑界面：将结果带回日常工作#

有些判断很难在文本框中表达，例如给 30 张工单重新排序。使用支持拖放的看板，就能直接调整顺序。

这个页面提供了以下编辑工具：

  • 工单分流看板： 将工单移到“现在做”“接下来做”“以后做”“不在范围内”，并将结果复制为 Markdown。
  • 功能开关编辑器： 按领域归类开关项，在前置条件关闭时发出警告，并仅复制已修改的键。
  • 提示词调试工具： 并排展示突出显示变量的模板和 3 组示例输入，根据输入更新生成结果的显示。

最重要的要求是导出按钮。没有它，做出的决定就会被困在页面里。

在请求制作界面之前，请先指定输出格式：计划文档用 Markdown，结构化数据用 JSON，配置修改用差异格式。同时明确重置行为，并要求清楚提示存在尚未保存的编辑。

编辑工具只有在能返回可粘贴到与智能体的对话中、或提交到代码仓库的结果时，才真正有用。

明天就试试：从这 3 项中选一项#

从能够立即检验结果的工作开始。

1. 比较一个实际决策的选项。 请智能体生成 3 种代码实现方案，统一比较标准，并将前提条件清单放在显眼的位置。 2. 改进定期报告。 使用现有报告和已核实的数据，请智能体生成一份每周进度报告。 3. 整理现有待办事项。 请智能体制作一个保留工单 ID、可将分类结果导出为 Markdown 的工单分流看板。

无论选择哪一项，都请加上以下指令：

> 请返回一个自包含的 HTML 文件，内联包含 CSS 和 JavaScript。仅使用已提供的事实，明确标出未知之处，并添加导出按钮，以便导出在页面上做出的决定。

对于需要编辑、搜索和版本管理的文字，Markdown 依然合适。对于需要比较、呈现空间关系、展示动态效果或直接操作的工作，HTML 值得一用。

打开实例库 ↗，选一个适合明天工作的页面，再请智能体使用你自己的资料制作一个版本。

目录