visual-recap

可视化回顾

/visual-recap 基于差异创建可视化计划，而不是为差异制定计划。它与正向规划相反：不是描述你即将进行的更改，而是从更高层次概述刚刚完成的更改，而非逐行审查。两种方向使用相同的计划数据模型——架构、API、文件和架构变更都会转化为正向计划所用的相同 data-model、api-endpoint、file-tree 和 diagram 区块，只是现在这些区块概述的是已经完成的工作。审查者可以先快速了解更改的整体形态，再仔细查看具体代码行。

发布为 Agent 原生计划——绝不内联提供

交付内容始终是已发布的 Agent 原生计划，使用 Plan MCP 连接器上的 create-visual-recap 创建——绝不能以内联聊天内容的形式提供（无论是 Markdown 文本、ASCII 草图、表格、围栏代码块中的“线框图”，还是“以下是回顾”之类的摘要）。回顾的全部价值在于托管、可交互、可批注的计划；内联摘要并非简化版回顾，而是回顾所要取代的内容。如果看不到 plan（或旧版 agent-native-plans）工具，请先通过宿主的 tool_search 发现它们；如果仍找不到，请停止操作，并告知用户该客户端对应的重新连接步骤，不要临时改为内联回顾。发布之前，或出现连接器或身份验证错误时，请阅读此技能目录中的 references/connection.md——这是关于绝不内联规则、连接器发现方式和各客户端重新连接步骤的唯一权威来源。下文的本地文件隐私模式是唯一例外。

本地文件隐私模式——阅读 references/local-files.md

如果用户不希望写入托管的 Plan 数据库——不进行数据库写入、不通过 Plan MCP 发布，或要求完全本地、离线、私密地生成回顾，或设置了 AGENT_NATIVE_PLANS_MODE=local-files——除仅用于查询模式的 get-plan-blocks 外，不要调用任何托管 Plan 工具。使用本地 recap collect-diff / scan / build-prompt --local-files 辅助工具读取差异，创建本地 MDX 文件夹（设置 kind: "recap" 和 localOnly: true），并使用 plan local check、plan local serve --kind recap 和 plan local verify --kind recap 预览。在使用本地文件模式之前，请阅读此技能目录中的 references/local-files.md——这是完整规则的唯一权威来源。

适用场景

当 PR 或提交规模较大、涉及多个文件，或触及架构、API 契约或系统架构，且审查者在阅读原始差异前先查看结构化区块映射会有所帮助时，请创建回顾。GitHub Action 可以根据 PR 差异自动生成回顾；Agent 也可以根据请求生成（例如“回顾这个 PR”“告诉我这个分支改了什么”）。对于规模较小、只涉及单个文件或一目了然的差异，请跳过回顾——回顾会增加审查开销，小改动直接查看差异更快。

回顾整个工作单元

在工作完成后于聊天线程中调用 /visual-recap 时，默认范围是整个当前工作单元／线程，而不只是用户最近一条消息、最近一次工具操作或后续修复。收集整个对话中属于该线程的更改：最初的实现工作、之后的错误修复、UI 后续调整、测试、变更集、技能／指令更新、生成的计划／源文件，以及让回顾能够正常打开所需的任何本地导入／链接修复。

结合当前差异和对话上下文，将属于该线程的更改与线程开始前就存在的无关未提交更改区分开来。排除无关的既有编辑。如果确实无法判断范围，请在发布前说明所依据的假设，或简短提问确认。

根据反馈更新现有回顾时，应修订回顾，使其仍涵盖整个线程／工作单元，并纳入新的修正。除非用户明确要求缩小范围，否则不要将涵盖面广的回顾替换为仅涵盖最近反馈的狭窄回顾。

保持回顾正文精简

不要在生成的计划正文中加入套话式的开场、免责声明、来源说明或总结段落。尤其不要仅仅为了说明回顾只是辅助材料、评审者仍应审查差异、变更了多少个文件，或生成回顾时使用了哪个引用／工作树，就创建 rich-text 块。计划标题、简介和 file-tree（其中包含各文件的变更统计）已经提供了这些背景信息。

只有当文字块能告诉评审者一些结构化块未涵盖的具体信息时，才添加文字块：变更目标、实际的兼容性风险、差异中可见的重要决策，或有依据的评审备注。

回顾必须内容充实

精简不等于单薄。回顾不能只有一个线框图和一句话——这对评审者帮助不够，正如套话式文字太多会造成干扰一样。除了视觉／结构概览（线框图、data-model、api-endpoint、diagram），内容充实的回顾还应提供实现依据：

• 撰写前简要盘点界面和状态：列出差异中可见的已变更路由、组件、弹出层／对话框、角色／访问状态、空状态／错误状态，以及共享抽象。最终回顾必须用块表示每一项有意义的内容；若有意省略某项，则应是因为它很小、重复冗余或对用户不可见。
• 列出变更文件的 file-tree，并为每个条目标明 change 标志，让评审者一眼看清工作范围。
• 将关键变更文件的差异拆分整理到一个水平 tabs 块中，并置于 ## 关键变更 rich-text 标题下（使用默认方向，每个文件一个标签页）；每个文件都附上一行 summary 和若干条 annotations，让评审者能从整体概览直接深入关键代码。使用水平文件标签页，不要使用垂直侧栏，这样选中的文件才能有足够宽度展示并排差异。

仅当变更确实非常小、以纯差异形式评审更快时，才跳过差异附录（参见“适用时机”）；任何值得撰写回顾的变更，都应在计划中包含 file-tree 和关键变更差异。

标准结构与篇幅限制

优秀的回顾自上而下遵循同一结构：

1. UI 影响概览——差异改变了渲染后的 UI 时，优先展示线框图。
2. 简短的结果叙述（rich-text）：说明变更内容及原因，写成 1-3 个段落。
3. 用于描述架构和契约变更的 data-model／api-endpoint 块。
4. 列出变更文件并标明 change 标志的 file-tree。
5. ## 关键变更——包含 diff／annotated-code 的单个水平 tabs 块。

以下篇幅限制有助于保持回顾易于评审：

• 关键变更标签页为 3-8 个。大型变更少于 3 个会让评审者难以全面了解；多于 8 个则不再像摘要。
• 每段差异／注释代码摘录都应聚焦——每个标签页最好少于约 150 行；长文件的其余部分应予以概述或链接，不要整份倾倒。
• 标题最多约 70 个字符；简介为 1-3 句话。

这些限制也是成本上限：不要为了追求全面而超出限制；完成初次顺序审阅后，不要重新阅读完整差异——应根据该过程中记录的笔记开展工作。

正确示例。 一个涉及 25 个文件的身份验证变更：登录界面前后线框图、两段叙述、体现差异的会话表 data-model、新刷新路由的 api-endpoint、带变更标志的 file-tree，以及包含五个重点标签页的 ## 关键变更；每个标签页都带有一行 summary 和若干条针对关键代码块的注释。

错误示例。 一份没有摘要或注释、未分段的超长差异转储；或者一份针对 40 个文件的内容稀少的三块式回顾（一个线框图、一句话、一个文件列表），迫使评审者不得不重新查看原始差异。

UI 变更需要线框图

当差异更改了渲染后的 UI、布局、密度、视觉状态、交互 affordance、导航、控件、菜单、对话框或设计令牌时，回顾内容 MUST 包含一张或多张线框图。文字说明和文件差异不能替代对视觉变化的展示。

选择线框图前，先根据差异检查 UI 覆盖范围：

• 确认变更出现的入口界面，例如页面标题栏、列表行、工具栏、路由外壳或菜单触发器。
• 确认会打开或发生变化的交互界面，例如弹出层、对话框、标签页、抽屉、下拉菜单、内联编辑器或 Toast。
• 确认变更后的目标界面或持久状态，例如公开页面、只读视图、空状态、错误状态、加载状态、权限被拒状态或已保存／已共享状态。
• 权限发生变化时，确认访问权限或角色的不同情况。所有者／管理员／编辑者与查看者／非管理者之间的差异属于视觉行为，需要用简明矩阵、成对线框图或明确标注的状态序列展示。

对于 UI 内容较多的 PR，仅展示入口界面的变更前／变更后状态并不足够。展示发生变化的入口、主要变更的交互界面，以及变更后的目标状态。若差异新增了标签页、基于角色的控件、公开／私有可见性、邀请／管理流程、破坏性控件或空／错误分支，则增加相应状态。

选择能够清楚呈现变更的最小视觉界面：

• 当直接对比能帮助审阅者理解变更时，例如控件被移除或新增、状态变化、布局密度、顺序、导航或可见组件替换，使用 Before / After 线框图对。references/wireframe.md 规定了该线框图对的布局方式（根据几何形状选择分栏或纵向堆叠）。
• 当变更纯粹是增量新增，或「变更前」状态只会展示空缺、无法为审阅提供更多价值时，仅使用变更后的线框图。
• 当 UI 变更依赖流程、响应式布局或状态时，使用两张以上的线框图，按顺序展示有意义的状态，而不是强行使用单一的变更前／变更后线框图。
• 对于菜单、弹出层、对话框、Toast 或面板等小型界面，使用匹配的 surface（popover、panel 等），并展示聚焦的子界面。除非页面中的位置本身属于变更内容，否则不要重画整页。

根据变更后的 UI 行为、组件名称、文件路径以及差异中可见的标签／状态来绘制每张线框图。如果像素级细节是推断而非实测得出，请在线框图说明或简短注释中注明。对于本地／手动编写的回顾内容，导入或更新存有线框图的计划源文件，以便渲染后的回顾内容打开时即可看到 UI 视觉呈现。

线框图质量 — 阅读 references/wireframe.md

UI 回顾／计划中的线框图必须达到严格的质量标准：全宽框架、固定底栏、真实的产品内容、前后可比性、正确的 surface 预设、使用 --wf-* 令牌而非十六进制颜色，且不得包含 <html>／<style>／字体标签。在编写任何线框图／<Screen>／WireframeBlock 之前，必须阅读此技能目录中的 references/wireframe.md——它是 HTML 线框图质量的唯一事实来源，与 /visual-plan 和 /visual-recap 共用，内容完全一致。不要凭记忆编写线框图。

使用标准的 WireframeBlock／<Screen> 格式，让 Plan 查看器负责表面框架、主题以及草图／简洁切换。需要精确控制位置时，适合使用 HTML 线框图，尤其是弹出层、菜单、对话框和密集表单。对于 HTML 线框图，除非明确需要仅用于设计且可编辑的模型图，否则请将 renderMode 留空或设为 wireframe，因为 renderMode="design" 会禁用草图粗略叠加效果。

有可用的浏览器工具时，请在 Plan 查看器中渲染 UI 影响回顾，并在当前主题下进行视觉检查，然后再分享。如果任何标签、注释、工具栏或线框图内容与其他元素重叠，请修正 MDX 并重新导入，然后再提供链接。将此过程限制为一次渲染与检查，最多再进行一次修复并重新渲染；除非用户明确要求，否则不要继续迭代。仅凭文本匹配的截图并不足够；请对捕获的图像进行视觉检查。没有浏览器时（例如在无头 CI Agent 中），请在回顾交接说明中注明。

顶部画布回顾 — 阅读 ../visual-plan/references/canvas.md

如果回顾包含顶部画布、分镜或流程视图，请在编写 canvas.mdx 之前阅读 ../visual-plan/references/canvas.md。回顾画布中的画板必须使用与优质文档正文线框图相同的 HTML 线框图路径：<Screen surface="..." html={...} />，并搭配语义化 HTML 片段。不要在画布的 <Screen> 标签内创建新的套件树子组件，例如 <FrameScreen>、<Card>、<Row>、<Title> 或 <Btn>。这些组件是旧计划的兼容标记；在新的画布分镜中，即使行内正文线框图效果良好，它们也可能导致布局拥挤或重叠。如果画布模型图比下方折叠区域中的相同屏幕效果差，请假定它使用了旧版套件路径，并将其替换为 HTML 屏幕。

打开并报告回顾

在本地文件隐私模式下，先运行 plan local check，然后报告本地桥接 URL。URL 可从 npx @agent-native/core@latest plan local serve --dir <plan-dir> --kind recap --open 或 <plan-dir>/.plan-url 获取。它会打开托管的 Plan UI，但读取的是本机上的 localhost 桥接，因此无法在不同机器间共享。如果 Plan 应用本身在本地运行，且使用相同的 PLAN_LOCAL_DIR，那么 /local-plans/<slug> 路由也有效。不要编造托管数据库 URL，也不要仅为获取绝对 Plan 链接而发布内容。

创建回顾后，应提供一个指向实际存储该计划的来源站点的绝对 URL，让审阅者查看渲染后的计划。该来源站点是你刚才用来创建回顾的 Plan MCP 服务，而不是你碰巧知道正在运行的任意开发服务器。创建工具会返回正确的链接；请报告该链接。绝不能将本地 plan.mdx 文件、本地镜像文件夹或 /plans/<id> 之类的相对路径作为主要链接。

将回顾发布到私有仓库的 PR 时，计划链接不是公开 URL。请在 PR 评论或交接说明中明确指出：链接加载前，审阅者可能需要使用有权访问所属组织的账号登录 Agent-Native Plans。可使用类似这样的措辞：“私有仓库回顾：如果计划无法打开，请使用有权访问此组织的账号登录。”如果访问权限受仓库或组织可见性限制，不要暗示链接已损坏或可以公开访问。

回顾只存在于创建它的 MCP 数据库中。单独运行的本地开发服务器（例如 http://localhost:8081）有自己的数据库，不会包含通过托管 MCP 创建的回顾，因此手动拼出的 localhost 链接会返回“Plan not found”。这是最常见的回顾错误——不要猜测未经确认与 MCP 共享数据的来源站点。

按以下顺序确定 URL：

1. 使用创建工具返回的绝对 URL：openLink.webUrl；否则使用返回的 plan.mdx frontmatter 中的 visualUrl；再否则，将 url/path 解析为相对于 MCP 服务自身来源站点的 URL（对于托管 MCP，该来源站点是 https://plan.agent-native.com）。这始终会指向包含该计划的数据库。
2. 仅当回顾是通过绑定到同一来源站点的 Plan MCP 创建时，才使用 localhost/开发环境来源站点，即该 MCP 的 URL 为 http://localhost:<port>/mcp。通过托管 MCP 创建回顾，却链接到 localhost，正是导致 404 的错误匹配。
3. 如果只有计划 ID，则构造 MCP 来源站点的绝对 URL（托管环境：https://plan.agent-native.com/plans/<id>），并说明该链接是推断得出的。

如果用户想在 localhost 上审阅，但回顾是通过托管 MCP 创建的，请明确说明：本地开发服务器无法查看该回顾。若要在 localhost 上查看回顾（例如测试尚未部署的本地渲染器更改），他们必须连接本地 Plan MCP（http://localhost:<port>/mcp），并通过该 MCP 重新创建回顾，使其存入本地数据库；请主动提出代为操作，而不是提供一个无法解析的 localhost URL。

在 Codex 中运行且可使用 Browser/应用内侧边浏览器工具时，创建回顾后应自动在那里打开返回的绝对 URL。最终回复中仍须包含相同的绝对 URL。本地镜像文件（如 plans/<slug>/plan.mdx）只能作为次要的源代码管理产物提及，不能作为打开回顾的主要方式。

Diff → Block 映射

根据实际 diff，以机械方式将每种更改映射到承载该更改的区块。下方名称是概念区块类型，而非 JSX 标签——编写内容前，请使用 get-plan-blocks 工具将每个概念名称解析为准确的标签和 prop 结构（见下文“区块参考”）。

• 架构 / 迁移变更 → 用 data-model 描述变更后的实体、字段和关系。通过 change: "added" | "modified" | "removed" | "renamed" 标记每个字段 / 实体的变更；对于类型变更，将先前的值设为 was（例如旧列类型），并以真实的迁移差异为依据。这个能体现差异的 data-model 是重点；只有在确切的语句仍然重要时，才考虑将字面 SQL 拆分到 diff 中，而不是默认这样做。
• API / 操作 / 路由变更 → 用 api-endpoint 描述变更后的方法、路径、参数、请求和响应。通过 change 标记每个变更的参数 / 响应（类型 / 形状发生变化的参数还要设置 was）；对于完全新增或移除的路由，在端点根节点设置 change。为已移除的端点设置 deprecated: true，并在正文中说明。 除非是明确的变更前后契约对比，否则多个 API 端点应按常规放在单列文档流中。 每个请求 / 响应示例都必须是一个单独的有效 JSON 值——一个可独立解析的顶层对象或数组——以便在可折叠的 JSON 浏览器中渲染。不要在一个示例中加入 // 或 /* */ 注释、正文、尾随逗号，或两个及以上串接的顶层对象；无法解析的内容会退回纯文本显示，并失去浏览器功能。 如果一个端点有多种不同的消息形状（例如不同的 websocket 帧类型，或成功响应体与错误响应体），请分别为每种形状提供自己的示例，并单独标注，而不是把它们塞进一个响应体。
• 对兼容性敏感的变更 → 在相关的 data-model / api-endpoint 块旁添加简短的 rich-text 说明。指出变更的字段、端点或行为，并标明其属于破坏性、有风险还是非破坏性变更；同时为字面代码行添加拆分模式的 diff。
• 任何有意义的代码块变更 → 使用 mode: "split" 的 diff，包含真实的 before / after 文本以及 filename / language。回顾代码审查默认使用拆分模式，因为前后对照的可读性是重点；只有对于确实很短、独立且并排显示会掩盖代码的代码块，才使用 mode: "unified"。每个 diff 都要附上一行 summary，说明代码块改了什么、为什么改；它会作为代码上方的说明渲染，帮助审查者先了解意图。切勿留下没有说明的 diff。 对于关键变更文件，在 diff 中添加 annotations，以突出说明回顾中每个重要代码块的作用——这是对已更新关键文件添加注释的主要方式。默认情况下，每条注释都锚定到 AFTER 侧的行号（如需指向已移除的行，请设置 side: "before"）。每个文件只保留少量高价值说明，而非逐行注释。 如果多个关键文件都需要大量差异说明，请先用 markdown 为 rich-text 标题块设置 ## Key changes，然后将 diff 块放在一个采用水平布局的可复用 tabs 块中（这是默认布局——省略 orientation），以便所选文件的拆分差异占据完整文档宽度。让该标题标记此部分——不要再为 tabs 块设置 title。每个标签应使用文件路径，或简短文件名加目录提示。 渲染器的宽文档布局采用明确的白名单：diff、annotated-code、垂直 tabs，以及包含类 diff 子项的 tabs 块，都可以使用比正文更宽的布局。不要为了加宽版面，就把 API 端点、OpenAPI 规范、数据模型、JSON 浏览器、线框图、问题表单或自定义 HTML 放进标签页。 如果回顾内容以多个辅助 diff 收尾，应将这些尾部差异附录放在一个独立 ## Key changes 标题下的水平 tabs 块中，而不是将多个 diff 块逐个堆叠。
• 全新文件，或没有有意义「变更前」内容的大型新增代码块 → 使用 annotated-code，而不是只有单侧内容的拆分 diff。保留真实新增代码及其 filename / language，并将少量高价值说明锚定到关键行，让审查者了解新增代码的作用，而不是只看代码本身。对于确实存在前后变化、且已移除的代码仍有意义的代码块，继续使用拆分 diff；多个注释式代码讲解也应像多个 diff 一样，放在水平 tabs 块中分组。
• 新增 / 移除 / 重命名文件 → 使用 file-tree，并通过每个条目的 change 标记（added、removed、modified、renamed），再附上简短的 note。只有当 snippet 能提供路径本身没有传达的信息时，才添加它。
• 渲染界面 / 交互变更 → 使用一个或多个线框图，在审查者阅读代码前展示可见界面的差异。如果对比有助于理解变更，请使用 Before / After 线框图；否则仅展示变更后的界面，或展示简短的状态 / 流程序列。使用逼真的 UI 界面：对于弹出层变更，应展示弹出层的标题栏、右上角操作、选项 / 字段、标签页、选中 / 禁用状态、人员 / 列表 / 行，以及锚定在正确触发控件上的已打开提示词 / 菜单。如果新增了路由，应展示路由正文，以及差异中实现的不可用 / 空状态。如果权限发生变化，应展示管理员可以执行的操作，以及查看者 / 非管理员看到的替代内容。 正文应保持精简：线框图负责呈现 UI 变化，文件树和 diff 块负责提供实现证据。
• 架构或数据流变化 → 使用 diagram，通过 data.html / data.css 构建双栏前后对比、分层布局或泳道布局；也可以用 mermaid 绘制简明图表。采用二维布局；不要把结构性变化简化成从左到右的链条。不要用 diagram 代替渲染后的 UI 控件；UI 变更应使用 wireframe 块。 编写图表 HTML / CSS 时，使用渲染器提供的 .diagram-* 原语（.diagram-panel、.diagram-node、.diagram-pill、[data-rough] 等），以及 references/wireframe.md 定义的相同 --wf-* 主题令牌——切勿使用 font-family、十六进制、rgb/hsl 字面值或仅用于特定明暗主题的配色方案。审慎选择外层 frame：独立的回顾图表通常适合设置 frame: "show"；如果列、标签页、卡片或图表自身的面板已提供边界，则使用 frame: "hide"。
• 结果优先的叙述 → 用 rich-text 撰写「变更内容及原因」：差异所服务的目标、其中体现的关键决策，以及审查者应权衡的风险。这是模型自由撰写正文的唯一位置。

区块参考 — 调用 get-plan-blocks，不要记忆标签

上面的概念性区块名称（api-endpoint、data-model、json-explorer、 tabs，……）不是你要编写的 JSX 标签；随着区块库的发展，确切的标签、必填字段 和属性形状都会变化。不要凭记忆编写标签——它们会发生变化，并悄无声息地生成错误 标签（例如，使用 ApiEndpoint 而不是 Endpoint、JsonExplorer 而不是 Json、 Tabs 而不是 TabsBlock），导致导入时报错。

编写任何结构化计划内容之前，先获取或读取区块目录。 在托管模式或可自托管模式下， 调用 Plan MCP 连接器（plan 或旧版 agent-native-plans）上的 get-plan-blocks。 如果延迟加载的客户端尚未显示任何 Plan 工具，请先通过宿主的工具发现界面搜索或加载 这些工具（如有 tool_search，请使用）。在本地文件模式下，或者技能以纯文本形式安装 且发现后仍未注册 MCP 工具时，运行 npx @agent-native/core@latest plan blocks --out plan-blocks.md， 并先读取该文件。此 CLI 命令会调用公开的无身份验证 get-plan-blocks 路由，且不会发送 任何计划或回顾内容。如果无法访问网络，请使用随附的参考资料并通过 plan local check 进行验证；仅当托管 Plan UI 可访问或本地 Plan 应用已在运行时，才运行 plan local serve。

该目录会从应用自身的区块注册表实时生成权威且始终最新的区块词汇表——渲染器和 MDX 往返转换使用的也是同一份配置——因此即使此 SKILL.md 是较旧的已安装副本，目录也不会过时：

• get-plan-blocks（默认 format: "reference"）→ 提供紧凑表格，列出每个区块的运行时 type、确切的 MDX <Tag>、放置位置和关键数据字段。这是将上面每个概念名称映射到 实际标签和属性的指南。
• get-plan-blocks 配合 format: "schema" → 提供每个区块完整的 JSON Schema，并为每个 区块附带一个完整示例；当你需要确切的字段类型、枚举值或嵌套结构时使用（例如 Diff.annotations、Endpoint.params[].in、DataModel.entities[].fields[]）。

根据调用返回的标签和架构编写回顾内容。有效的区块级标签，以 get-plan-blocks 列出的 为准；导入时，任何其他区块级大写标签都会被拒绝，并报出“Unknown plan block” / “did you mean”错误。rich-text/Markdown 正文中的小写 HTML 标签（<div>、<span>、 <code>、<br>，……）始终有效——只有大写的组件式区块标签会经过验证。

注册表表格无法涵盖以下几条特定于回顾内容的编写规则：

• 每个结构化区块都必须包含一个 id（在整个计划中唯一）， 以及共享的可选 summary / editable 封装。普通的顶层 Markdown 文本会自动导入为富文本；只有在文本需要显式元数据或保留被引用的区块 ID 时，才使用 <RichText id="...">。
• 每个首字母大写的区块组件都必须自闭合（<Diagram ... />），或在包含子内容时显式闭合（<RichText ...>...</RichText>）。绝不要在段落中留下类似 <RichText ...> 的裸开始标签；MDX 会将其视为未闭合的 JSX，导致导入在摘要渲染前失败。
• 包含代码的区块（Code、AnnotatedCode 和 Diff）对空白字符敏感。优先采用 get-plan-blocks 示例 / 源导出器中的确切 MDX 格式，其中多行代码会编码为 JSON 字符串属性，例如 code={"const x =\n y"}。只有不含 ${...} 插值的静态字符串才可使用静态模板字面量。
• Endpoint：说明性文字 description 是 MDX 子内容（标签之间的正文），而不是属性；对于 WebSocket 升级，请使用 method="GET"。每个请求 / 响应 example 都是 JSON 字符串（渲染器会将其解析到 JSON 浏览器中），因此请确保它是单个可解析的 JSON 值。
• TabsBlock：整个 tabs 数组（包括嵌套的子区块）都是一个 JSON tabs={[…]} 属性——没有嵌套的 <Tab> 元素。
• WireframeBlock：其正文是单个 <Screen surface ... html=… /> 子树（嵌套 MDX，而不是扁平属性）；html 必须是单引号字符串或静态模板字面量，绝不能是动态的 html={someVar} 表达式。HTML 规则请参阅 references/wireframe.md。
• Diagram：整个载荷是一个 data={{ html?, css?, nodes?, edges?, … }} 属性，且必须包含 html 或至少一个节点；Mermaid 是独立的区块（source 文本），不是 Diagram 属性。

Before / After 就是重点

回顾内容的核心是 Before / After 对比。对于文档正文对比，有两种基本块，配合使用即可满足全部需求：

• columns — 并排展示的容器，适用于结构化对比。使用标注为 Before 和 After 的两列，每列放入一个块（通常是 data-model、api-endpoint 或 rich-text），让审阅者一眼就能对照旧结构和新结构。这是展示“架构从 X 变成 Y”或“接口契约发生了这样的变化”的合适方式。不要仅仅为了压缩或分组 API 端点列表而使用 columns。
• diff — 用于代码。它会呈现实际删除和新增的行。用它展示具体差异片段。代码回顾中默认使用拆分模式；只有在真正狭窄的独立差异片段中，并排展示会遮挡代码时，才使用 mode: "unified"。关键文件的 diff 分组应使用水平标签页，让拆分 diff 占据完整文档宽度。

对于 UI 差异，线框图是可视化对比的基本方式。当 Before / After 对比能清晰说明变化时，就使用这种方式；如果仅展示 After 或按状态顺序展示更符合变化情况，则使用对应方式。可视化重点必须先展示精确的位置、真实的界面框架和充足的留白，再进行抽象说明。如果 diff 增加了一个流程，不要只展示第一个可见操作入口；还要展示入口、打开后的界面，以及最终状态或页面，让审阅者能追踪实际的用户操作路径。references/wireframe.md 负责决定 Before / After 的布局方式—— columns 渲染器会让窄界面并排展示，并自动将宽屏 desktop/browser 画面改为纵向堆叠；绝不要在 custom-html 中手动构建并排线框图布局。对于文档正文对比，没有其他多列基本块——columns 加上 diff 块就是完整的对比表达方式。不要在 custom-html 中手动构建并排布局；也不要在 columns 可以将两个 data-model 块并排展示时，却将它们纵向堆叠并称之为对比。

基于事实的规则

只有从实际变更行推导出的结构化块，才能确保准确。diff、data-model、api-endpoint 和 file-tree 块都必须根据真实 diff 机械生成——使用真实路径、真实字段、真实方法/路径以及真实 Before / After 文本，绝不可推断、取整或编造。模型只负责撰写文字说明：“原因”、叙述内容和风险判断。在审查场景中，自信但错误的回顾内容很危险，因为相信摘要的审阅者可能会跳过摘要弄错的那一行。如果 diff 中没有某项事实，就不要猜测，直接省略；凡是模型推断而非提取的信息，都要在说明文字中标明为推断。

安全

• 限制可见范围。 私有仓库的回顾内容应受组织/登录权限限制——将计划的可见范围设置为所属组织或登录用户，绝不要自动公开。回顾内容可能暴露尚未发布的架构、内部端点和系统架构；应像对待其所总结的源代码一样谨慎处理。如果 PR 评论或交接内容中包含回顾链接，而该链接无法加载，则必须说明访问私有仓库回顾内容需要登录并拥有所属组织的访问权限。
• 绝不抄录秘密。 diff 中可能包含 API 密钥、令牌、Webhook URL、签名密钥、.env 值或看起来像凭证的字面内容。不要将这些内容复制到 diff、file-tree 片段、api-endpoint 或说明文字中——应将其脱敏（sk-•••、<redacted>）。这与仓库中关于硬编码秘密的规则一致：任何块、说明文字或备注中，只能使用明显是虚构的占位符，绝不可使用真实值。

双向循环

在托管模式下，由于回顾是真实且可编辑的计划，因此适用与正向计划相同的审查循环：审查者可以批注任意区块，编码 Agent 会读取 get-plan-feedback，将修复反馈回代码中——批注 → Agent → 差异，这与正向计划采用的是同一套闭环流程。审查者批注区块后，调用 get-plan-feedback 读取结构化反馈，然后通过 create-visual-recap 更新回顾（传入现有的 planId，即可就地替换），或通过 update-visual-plan 应用有针对性的更改。该循环已启用并接通。在本地文件隐私模式下，不要调用这些托管工具；请从聊天记录或本地文件中读取审查备注，直接编辑 <plan-dir>/*.mdx，然后针对 <plan-dir> 重新运行 plan local check、serve 或 verify。目前唯一尚未自动化的是由 PR 评论触发的重新运行：GitHub Action 会为每个 PR 创建初始回顾，但尚不会在 GitHub 上发布新的审查反馈时自动重新运行——这就是剩下的后续快速迭代项。

相关技能

• visual-plan — 规范命令，也是共享线框图与画布核心及文档质量核心的来源；回顾遵循相同的区块规范，只是方向相反。
• comment anchors — 回顾评论使用与正向计划相同的锚点规则；坐标系、线框图节点 ID、文本引文解析、分离的讨论串、通过 resolutionTarget 路由，以及已消费/已解决的双轴状态，请参见 visual-plan 技能中的“解读评论锚点”。
• security — 数据范围限定、密钥处理，以及硬编码密钥规则；回顾的脱敏和可见性控制遵循相同规则。
• sharing — 对包含回顾的计划进行组织/登录门控的可见性控制。