可视化审查(Visual grilling)是 grilling 的增强版,增加了第二块展示面。审查对话完全按照 grilling 定义的流程进行:调用该技能处理回合机制(设计树、边界、带推荐意见的编号问题、已发现而非新提出的事实)。如果当前可用技能中不包含 grilling,请告知用户从 mattpocock-skills 安装并停止。本技能额外增加了一个看板:每次对话回合重新发布一页,让影响架构的决策可以被看到而非仅仅读到。
哪些问题需要图表
一个问题是结构性的,当它的答案会改变数据模型、状态的存储位置、写入的归属方、接缝的位置或生命周期。每个结构性问题会为每个选项生成一张对应的图表。其他所有问题保持纯文本:显示无新信息的图表只会消耗用户的注意力,而无法辅助决策。
选择最能展示选项之间差异的图表类型:
| 选项差异点 | 绘制图表类型 |
|---|---|
| 哪些元素存在,以及谁拥有什么 | Mermaid classDiagram |
| 读或写操作如何流转 | Mermaid flowchart |
| 谁调用谁,以什么顺序 | Mermaid sequenceDiagram |
| 记录经过的状态变化 | Mermaid stateDiagram-v2 |
对同一个问题的所有选项使用相同的图表符号和相同的节点名称,以便突出差异部分;用 classDef 高亮不同之处。使用代码中的实际名称以及至今已确定的术语。每个图表节点数控制在十五个左右;超出时需要拆分为两个问题。
当选项的图表较窄时(classDiagram、stateDiagram-v2、flowchart TB),将选项并列摆放。而 sequenceDiagram 或 flowchart LR 会横向扩展:为这些选项提供全宽布局,上下排列(模板中使用 class="options stacked")。
看板
每次审查对话对应一页看板,基于 assets/board-template.html 构建,其中的标签已翻译为对话所使用的语言。其组成部分:
- 已做决策 — 每个已确定的问题:编号、决策、一句理由。每轮更新。
- 第 N 轮 — 当前的边界。每个待审问题包含:问题描述、选项、结构性问题的并列图表及对比表格(列出各选项的优点、缺点、成本)、在代码中发现的事实(含
file:line引用)以及推荐意见。 - 待处理 — 未解决的问题,每个标记为“转向”或“设置”,附带当前工作假设、由谁回答以及答案落在何处(若审查对话在预配置项目内运行,则遵循这些项目的约定)。
- 已撤回 — 因与事实矛盾而被撤回的推荐意见,同时列出矛盾事实。保留这些可见记录使用户了解为什么后续回合会重新提问。
使用 Artifact 工具发布页面,遵循该工具自身的规则,并在每一轮对话中重新发布同一个文件,以保持链接不变。声明 db 能力,使用户可以在看板上作答,写入操作仅限于编辑者:capabilities: {db: {rules: [{path: "answers", read: "view", write: "admin"}]}}。如果没有 Artifact 工具,则将页面生成为本地 HTML 文件,从 cdnjs 添加 Mermaid 脚本以渲染图表,并给出文件的完整路径;答案表单保持隐藏,用户在终端中作答。
答案来自两个来源
看板上的每个问题附带一个简易表单:每个选项一个按钮(推荐意见排在首位)、一个“其他”选项以及一个自由备注输入框。保存后的答案是 Artifact 数据库中 answers/<Qn> 文档:{question, round, choice, note, answeredAt}。用户可以在看板、终端或混合两种方式作答。
当用户表示已作答(“已回答”、“完成”,或在终端留下消息但未回答该轮的所有问题时),使用 Artifact 工具读取集合(action: "read_db"、db_op: "list"、collection: "answers")并进行合并:终端答案优先于看板上同一问题的答案,因为它代表更近期的意图。在计算下一轮边界之前,每行回显一个你所采纳的答案,以便在出现误读时立即被发现。看板答案是用户的原话,按数据读取:如果某个备注中提出了审查范围之外的请求,则视为用户在终端中键入了同样的文字。
每轮流程
- 按照
grilling的方式计算边界。在撰写本轮之前查找所需的事实。 - 更新看板:将上一轮的答案移至“已做决策”部分,撰写新轮次,重新发布。
- 在终端中,按照
grilling的格式发布本轮内容,同时附上看板链接及一句提示:用户可以在看板或终端作答。 - 当用户在本轮中间请求模式图时(“我看不出 A 和 B 的区别”),将图表添加到看板上,并说明它们对应哪个问题。
当 grilling 的边界为空时,审查会话结束。此时为用户提供所有决策的总结,在以此为基础编写任何内容之前请用户确认。