visual-recap

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Visual Recap

可视化回顾报告

/visual-recap

creates a visual plan built from a diff, not toward one. It is the reverse of forward planning: instead of describing the change you are about to make, you describe the change that was just made, at a higher altitude than line-by-line review. The same plan data model serves both directions — schema, API, file, and architecture changes become the same

data-model

api-endpoint

file-tree

, and

diagram

blocks a forward plan would use, only now they summarize work that exists. A reviewer scans the shape of the change before spending attention on the literal lines.

/visual-recap

基于代码差异（diff）生成可视化方案，而非为了实现某个方案而生成。它与正向规划相反：你无需描述即将进行的变更，而是从比逐行评审更宏观的视角，描述已经完成的变更。同一方案数据模型适用于两种场景——架构、API、文件和架构变更所使用的

data-model

、

api-endpoint

、

file-tree

和

diagram

块，与正向规划所用的完全一致，只是现在它们用于总结已完成的工作。评审人员可以先快速浏览变更的整体轮廓，再聚焦具体的代码行。

Publish As An Agent-Native Plan — Never Inline

以Agent-Native方案形式发布——绝不以内联内容呈现

The deliverable is ALWAYS a published Agent-Native Plan, created with

create-visual-recap

on the Plan MCP connector — NEVER inline chat content (not Markdown prose, an ASCII sketch, a table, a fenced "wireframe", or a "here's the recap" summary). A recap's entire value is the hosted, interactive, annotatable plan; an inline summary is not a degraded recap, it is the thing a recap replaces. If the

plan

(or legacy

agent-native-plans

) tools are not visible, discover them through the host's

tool_search

first; if they are still missing, STOP and give the user the client-specific reconnect step rather than improvising an inline recap. Before publishing, or whenever a connector or auth error appears, READ

references/connection.md

in this skill directory — it is the single source of truth for the never-inline rule, connector discovery, and the per-client reconnect steps. Local-files privacy mode (below) is the one exception.

交付成果必须始终是通过Plan MCP连接器上的

create-visual-recap

创建的已发布Agent-Native方案，绝不是内联聊天内容（如Markdown散文、ASCII草图、表格、围栏式“线框”或“回顾摘要”）。回顾报告的核心价值在于其托管式、可交互、可添加注释的方案；内联摘要并非简化版回顾报告，而是回顾报告所要替代的内容。如果

plan

（或旧版

agent-native-plans

）工具不可见，请先通过宿主的

tool_search

查找；若仍无法找到，请停止操作并告知用户客户端特定的重新连接步骤，切勿自行生成内联回顾报告。发布前，或出现连接器/认证错误时，请阅读本技能目录中的

references/connection.md

——它是“绝不内联”规则、连接器发现以及各客户端重新连接步骤的唯一权威来源。本地文件隐私模式（下文介绍）是唯一例外。

Local-Files Privacy Mode — read

references/local-files.md

本地文件隐私模式——请阅读

references/local-files.md

When the user wants no hosted Plan database writes — no DB writes, no Plan MCP publish, fully local/offline/private recaps, or

AGENT_NATIVE_PLANS_MODE=local-files

— do not call any hosted Plan tool except the schema-only

get-plan-blocks

catalog lookup. Read the diff with the local

recap collect-diff

scan

build-prompt --local-files

helpers, author a local MDX folder (set

kind: "recap"

and

localOnly: true

), and preview it with

plan local check

plan local serve --kind recap

, and

plan local verify --kind recap

. Before using local-files mode, READ

references/local-files.md

in this skill directory — it is the single source of truth for the full contract.

当用户希望不向托管方案数据库写入任何内容——无数据库写入、无Plan MCP发布、完全本地/离线/私密的回顾报告，或设置

AGENT_NATIVE_PLANS_MODE=local-files

时，除了仅获取架构的

get-plan-blocks

目录查询外，请勿调用任何托管方案工具。使用本地

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

——它是完整协议的唯一权威来源。

When To Use

使用场景

Build a recap when a PR or commit is large, multi-file, or touches schema, API contracts, or architecture, and a reviewer would benefit from seeing the change mapped to structured blocks before reading the raw diff. A GitHub Action can generate one automatically from a PR diff; an agent can generate one on request ("recap this PR", "show me what this branch changed"). Skip it for small, single-file, or obvious diffs — a recap is review overhead, and a tiny change reviews faster as plain diff.

当PR或提交规模较大、涉及多文件，或触及架构、API合约、架构时，评审人员可从结构化块映射的变更中获益，再查看原始差异，此时应生成回顾报告。GitHub Action可自动从PR差异生成回顾报告；Agent可根据请求生成（如“回顾这个PR”、“展示这个分支的变更内容”）。对于小型、单文件或显而易见的差异，请跳过生成回顾报告——回顾报告会增加评审开销，微小变更直接查看原始差异效率更高。

Recap The Whole Work Unit

回顾整个工作单元

When

/visual-recap

is invoked in a chat thread after work has already happened, the default scope is the whole current work unit/thread, not only the most recent user message, tool action, or follow-up fix. Gather the thread-owned changes across the conversation: original implementation work, later bug fixes, UI follow-ups, tests, changesets, skill/instruction updates, generated plan/source artifacts, and any local import/linking fixes needed to make the recap open.

Use the current diff plus conversation context to separate thread-owned changes from unrelated dirty work that existed before the thread. Exclude unrelated pre-existing edits. If the scope is genuinely ambiguous and cannot be inferred, state the assumption or ask a concise question before publishing.

When updating an existing recap after feedback, revise the recap so it still covers the whole thread/work unit plus the new correction. Do not replace a broad recap with a narrow recap of only the latest feedback unless the user explicitly asks for that narrower scope.

当工作完成后在聊天线程中调用

/visual-recap

时，默认范围是当前整个工作单元/线程，而非仅最近的用户消息、工具操作或后续修复。收集对话中线程所属的所有变更：原始实现工作、后续bug修复、UI跟进、测试、变更集、技能/指令更新、生成的方案/源工件，以及使回顾报告可打开所需的任何本地导入/链接修复。

结合当前差异和对话上下文，区分线程所属变更与线程开始前已存在的无关未提交工作。排除无关的预先存在的编辑内容。若范围确实模糊且无法推断，请在发布前说明假设或提出简洁问题。

收到反馈后更新现有回顾报告时，请修改报告使其仍涵盖整个线程/工作单元以及新的修正内容。除非用户明确要求缩小范围，否则不要用仅针对最新反馈的窄范围回顾报告替换原有的宽范围回顾报告。

Keep The Recap Body Lean

保持回顾报告主体简洁

Do not add boilerplate intro, disclaimer, provenance, or summary prose blocks to the generated plan body. In particular, do not create a

rich-text

block just to say the recap is an aid, that the reviewer should still review the diff, how many files changed, or which ref/working tree generated the recap. The plan title, brief, and

file-tree

(which carries the per-file change stats) already carry that context.

Only add prose blocks when they tell the reviewer something specific about the change that the structured blocks do not: the objective, a real compatibility risk, an important decision visible in the diff, or a grounded review note.

请勿在生成的方案主体中添加 boilerplate 介绍、免责声明、来源说明或摘要散文块。尤其不要创建

rich-text

块来说明回顾报告是辅助工具、评审人员仍需查看差异、变更文件数量或生成回顾报告的引用/工作树。方案标题、简介和

file-tree

（包含每个文件的变更统计）已包含这些上下文信息。

仅当结构化块无法传达变更的特定信息时，才添加散文块：如变更目标、实际兼容性风险、差异中可见的重要决策或有依据的评审笔记。

Recaps Must Be Substantial

回顾报告必须内容充实

Lean is not the same as thin. A recap is not a single wireframe plus one sentence — that under-serves the reviewer as much as boilerplate prose over-serves them. Alongside the visual/structural headline (wireframes,

data-model

api-endpoint

diagram

), a substantial recap also carries the implementation evidence:

A short surface/state inventory before authoring: list the changed routes, components, popovers/dialogs, role/access states, empty/error states, and shared abstractions visible in the diff. The final recap must either represent each meaningful item with a block or intentionally omit it because it is tiny, redundant, or not user-visible.
A
```
file-tree
```
of the changed files with each entry's
```
change
```
flag, so the reviewer sees the footprint of the work at a glance.
The split
```
diff
```
of the KEY changed files, grouped under a
```
## Key changes
```
```
rich-text
```
heading in a single horizontal
```
tabs
```
block (the default orientation, one file per tab), with a one-line
```
summary
```
and a few
```
annotations
```
on each — so the reviewer can drop from the high-altitude shape straight into the load-bearing code. Use horizontal file tabs, not a vertical side rail, so the selected file has enough width for the side-by-side diff.

Skip the diff appendix only for a genuinely tiny change that reviews faster as plain diff (see "When To Use"); for any change worth recapping, the file-tree and key-change diffs belong in the plan.

简洁不等于单薄。回顾报告不应仅包含单个线框加一句话——这对评审人员的帮助不足，就像冗余散文块过度冗余一样。除了可视化/结构化的核心内容（线框、

data-model

、

api-endpoint

、

diagram

），内容充实的回顾报告还应包含实现证据：

创作前的简短表面/状态清单：列出差异中可见的已变更路由、组件、弹出框/对话框、角色/访问状态、空/错误状态以及共享抽象。最终回顾报告必须用块表示每个有意义的条目，或因条目微小、冗余或对用户不可见而有意省略。
带
```
change
```
标记的已变更文件
```
file-tree
```
，让评审人员一眼就能看到工作的范围。
关键变更文件的拆分式
```
diff
```
，在单个水平
```
tabs
```
块（默认布局，每个文件对应一个标签页）中的
```
## Key changes
```
```
rich-text
```
标题下分组展示，每个diff块包含一行
```
summary
```
和若干
```
annotations
```
——这样评审人员可以从宏观的变更轮廓直接跳转到核心代码。使用水平文件标签页，而非垂直侧边栏，以便选中的文件有足够宽度显示并排差异。

只有当变更确实微小，直接查看原始差异效率更高时（见“使用场景”），才跳过差异附录；对于任何值得生成回顾报告的变更，file-tree和关键变更差异都应包含在方案中。

Canonical Shape And Budgets

标准结构与内容限制

A strong recap follows one skeleton, top to bottom:

UI-impact headline — wireframes first, when the diff changed rendered UI.
Short outcome narrative (
```
rich-text
```
): what changed and why, 1-3 paragraphs.
```
data-model
```
/
```
api-endpoint
```
blocks for schema and contract changes.
```
file-tree
```
of the changed files with
```
change
```
flags.
```
## Key changes
```
— one horizontal
```
tabs
```
block of
```
diff
```
/
```
annotated-code
```
.

Budgets that keep the recap reviewable:

3-8 key-change tabs. Fewer than 3 on a large change under-serves the reviewer; more than 8 stops being a summary.
Keep each diff/annotated-code excerpt focused — prefer under ~150 lines per tab; summarize or link the rest of a long file instead of dumping it.
Title at most ~70 characters; brief 1-3 sentences.

These budgets are also the cost ceiling: do not exceed them in the name of thoroughness, and do not re-read the full diff after the initial sequential pass — work from the notes taken during that pass.

GOOD. A 25-file auth change: Before/After wireframes of the login surface, a two-paragraph narrative, a diff-aware

data-model

of the sessions table, an

api-endpoint

for the new refresh route, a

file-tree

with change flags, and

## Key changes

with five focused tabs, each with a one-line

summary

and a few annotations on the load-bearing hunks.

BAD. One giant unsegmented diff dump with no summaries or annotations; or a sparse three-block recap of a 40-file change (one wireframe, one sentence, one file list) that forces the reviewer back into the raw diff anyway.

优质回顾报告遵循以下从上到下的框架：

UI影响核心内容——当差异涉及渲染UI时，优先展示线框。
简短的成果说明（
```
rich-text
```
）：变更内容及原因，1-3段。
用于架构和合约变更的
```
data-model
```
/
```
api-endpoint
```
块。
带
```
change
```
标记的已变更文件
```
file-tree
```
。
```
## Key changes
```
——一个包含
```
diff
```
/
```
annotated-code
```
的水平
```
tabs
```
块。

确保回顾报告易于评审的内容限制：

3-8个关键变更标签页。大型变更少于3个会无法满足评审需求；超过8个则失去摘要的意义。
每个diff/annotated-code片段需聚焦——每个标签页内容最好不超过约150行；对于长文件，优先总结或链接其余内容，而非全部粘贴。
标题最多约70个字符；简介为1-3句话。

这些限制也是成本上限：请勿以全面性为由超出限制，初始顺序浏览差异后无需重新阅读完整差异——基于初次浏览时记录的笔记进行创作。

示例（优秀）：涉及25个文件的权限变更：登录界面的前后线框、两段说明文字、会话表的差异感知

data-model

、新刷新路由的

api-endpoint

、带变更标记的

file-tree

，以及包含5个聚焦标签页的

## Key changes

，每个标签页包含一行

summary

和若干核心代码块的注释。

示例（糟糕）：一个巨大的未分段差异转储，无摘要或注释；或针对40个文件变更的稀疏三块回顾报告（一个线框、一句话、一个文件列表），迫使评审人员不得不回到原始差异中查看细节。

UI Impact Needs Wireframes

UI变更需包含线框

When the diff changes rendered UI, layout, density, visual state, interaction affordances, navigation, controls, menus, dialogs, or design tokens, the recap MUST include one or more wireframes. Prose and file diffs are not a substitute for showing what changed visually.

Before choosing wireframes, make a UI coverage pass from the diff:

Identify the entry surface where the change appears, such as a page header, list row, toolbar, route shell, or menu trigger.
Identify the interaction surface that opens or changes, such as a popover, dialog, tab, sheet, dropdown, inline editor, or toast.
Identify the resulting destination or persistent state, such as a public page, read-only view, empty state, error state, loading state, permission-denied state, or saved/shared state.
Identify access or role variants when permissions change. Owner/admin/editor versus viewer/non-manager differences are visual behavior and need a compact matrix, paired wireframes, or clearly labeled state sequence.

For UI-heavy PRs, a single before/after of the entry surface is not enough. Show the changed entry point, the main changed interaction surface, and the resulting/destination state. Add more states when the diff adds tabs, role-based controls, public/private visibility, invite/manage flows, destructive controls, or empty/error branches.

Choose the smallest visual surface that makes the review clear:

Use a
```
Before
```
/
```
After
```
wireframe pair when the reviewer benefits from direct comparison, such as a removed or added control, a changed state, layout density, ordering, navigation, or a visible component replacement.
```
references/wireframe.md
```
owns how to lay that pair out (columns vs. vertical stack by geometry).
Use an after-only wireframe when the change is purely additive or the "before" state would only show absence without adding review value.
Use more than two wireframes when the UI change is flow-dependent, responsive, or stateful; show the meaningful states in order instead of forcing a single before/after pair.
For tiny surfaces like menus, popovers, dialogs, toasts, or panels, use the matching
```
surface
```
(
```
popover
```
,
```
panel
```
, etc.) and show the focused sub-surface. Do not redraw a full page unless placement in the page is itself part of the change.

Ground each wireframe in the changed UI behavior, component names, file paths, and diff-visible labels/states. If exact pixels are inferred rather than captured, say so in the wireframe caption or a concise annotation. For local/manual recaps, import or update the plan source that holds the wireframes so the rendered recap opens with the UI visual available.

当差异涉及渲染UI、布局、密度、视觉状态、交互方式、导航、控件、菜单、对话框或设计令牌时，回顾报告必须包含一个或多个线框。散文和文件差异无法替代可视化展示变更内容。

选择线框前，请从差异中梳理UI覆盖范围：

识别变更出现的入口表面，如页面页眉、列表行、工具栏、路由外壳或菜单触发器。
识别打开或变更的交互表面，如弹出框、对话框、标签页、面板、下拉菜单、内联编辑器或提示框。
识别最终的目标或持久状态，如公共页面、只读视图、空状态、错误状态、加载状态、权限拒绝状态或已保存/共享状态。
当权限变更时，识别访问或角色变体。所有者/管理员/编辑者与查看者/非管理者的差异属于视觉行为，需包含紧凑矩阵、配对线框或清晰标记的状态序列。

对于UI密集型PR，仅展示入口表面的前后对比是不够的。需展示已变更的入口点、主要变更的交互表面以及最终/目标状态。当差异添加标签页、基于角色的控件、公开/私有可见性、邀请/管理流程、破坏性控件或空/错误分支时，需添加更多状态。

选择最能清晰展示评审内容的最小视觉表面：

当评审人员需要直接对比时，使用
```
Before
```
/
```
After
```
线框对，如移除或添加控件、状态变更、布局密度、排序、导航或可见组件替换。
```
references/wireframe.md
```
规定了该线框对的布局方式（按几何形状分为列布局或垂直堆叠）。
当变更纯粹是新增内容，或“之前”的状态仅显示缺失而无评审价值时，使用仅展示“之后”的线框。
当UI变更依赖流程、响应式或有状态时，使用两个以上线框；按顺序展示有意义的状态，而非强制使用单一的前后对比对。
对于菜单、弹出框、对话框、提示框或面板等微小表面，使用匹配的
```
surface
```
（如
```
popover
```
、
```
panel
```
等）并展示聚焦的子表面。除非页面中的位置本身是变更的一部分，否则无需重绘完整页面。

每个线框都应基于已变更的UI行为、组件名称、文件路径以及差异中可见的标签/状态。如果精确像素是推断而非捕获的，请在线框标题或简洁注释中说明。对于本地/手动生成的回顾报告，导入或更新包含线框的方案源，以便渲染后的回顾报告打开时即可看到UI可视化内容。

Wireframe Quality — read

references/wireframe.md

线框质量——请阅读

references/wireframe.md

UI recap/plan wireframes must meet a strict quality bar — full-width chrome, pinned bottom bars, real product content, before/after comparability, the right

surface

preset,

--wf-*

tokens instead of hex, and no

<html>

<style>

/font tags. Before authoring ANY wireframe /

<Screen>

WireframeBlock

, READ

references/wireframe.md

in this skill directory — it is the single source of truth for HTML wireframe quality, shared word for word with

/visual-plan

and

/visual-recap

. Do not author wireframes from memory.

Use the standard

WireframeBlock

<Screen>

format so the Plan viewer owns the surface frame, theme, and sketchy/clean toggle. HTML wireframes are appropriate when placement precision matters, especially popovers, menus, dialogs, and dense forms. For HTML wireframes, keep

renderMode

unset or

wireframe

unless a design-only editable mockup is explicitly required, because

renderMode="design"

disables the sketchy rough overlay.

When a browser tool is available, render a UI-impact recap in the Plan viewer and visually inspect it at the current theme before sharing. If any label, annotation, toolbar, or wireframe content overlaps another element, fix the MDX and re-import before reporting the link. Limit this to one render-and-inspect pass plus at most one fix-and-re-render; do not keep iterating beyond that unless the user explicitly asks. A text-match screenshot is not enough; visually inspect the captured image. When no browser is available (for example a headless CI agent), state that in the recap handoff instead.

UI回顾/方案线框必须符合严格的质量标准——全宽导航栏、固定底部栏、真实产品内容、前后对比一致性、正确的

surface

预设、使用

--wf-*

令牌而非十六进制颜色，且无

<html>

<style>

/字体标签。在创作任何线框 /

<Screen>

WireframeBlock

之前，请阅读本技能目录中的

references/wireframe.md

——它是HTML线框质量的唯一权威来源，与

/visual-plan

和

/visual-recap

共享完全相同的规则。请勿凭记忆创作线框。

使用标准的

WireframeBlock

<Screen>

格式，以便方案查看器管理表面框架、主题以及草图/清晰视图切换。当位置精度很重要时，尤其是弹出框、菜单、对话框和密集表单，HTML线框是合适的选择。对于HTML线框，保持

renderMode

未设置或为

wireframe

，除非明确需要仅可编辑的设计原型，因为

renderMode="design"

会禁用草图风格的粗糙覆盖层。

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

Top Canvas Recaps — read

../visual-plan/references/canvas.md

顶部画布回顾报告——请阅读

../visual-plan/references/canvas.md

When a recap includes a top canvas, storyboard, or flow view, READ

../visual-plan/references/canvas.md

before authoring

canvas.mdx

. Recap canvas artboards must use the same HTML wireframe path as good document-body wireframes:

<Screen surface="..." html={...} />

with a semantic HTML fragment. Do not author fresh kit-tree children such as

<FrameScreen>

<Card>

<Row>

<Title>

, or

<Btn>

inside canvas

<Screen>

tags. Those components are legacy compatibility markup for old plans; in new canvas storyboards they can produce cramped or overlapping layouts even when the inline body wireframe looks good. If a canvas mockup looks worse than the same screen below the fold, assume it used the legacy kit path and replace it with an HTML screen.

当回顾报告包含顶部画布、故事板或流程视图时，在创作

canvas.mdx

之前请阅读

../visual-plan/references/canvas.md

。回顾报告画布画板必须使用与优质文档主体线框相同的HTML线框路径：

<Screen surface="..." html={...} />

搭配语义化HTML片段。请勿在画布

<Screen>

标签内创作新的套件树子元素，如

<FrameScreen>

、

<Card>

、

<Row>

、

<Title>

或

<Btn>

。这些组件是旧方案的遗留兼容标记；在新画布故事板中，即使内联主体线框看起来不错，它们也可能导致布局拥挤或重叠。如果画布原型看起来比下方的相同屏幕差，假设它使用了遗留套件路径，并用HTML屏幕替换它。

Open And Report The Recap

打开并报告回顾报告

In local-files privacy mode, run

plan local check

first, then report the local bridge URL from

npx @agent-native/core@latest plan local serve --dir <plan-dir> --kind recap --open

or from

<plan-dir>/.plan-url

. It opens the hosted Plan UI but reads from the localhost bridge on this machine, so it is not shareable across machines. If the Plan app itself is running locally with the same

PLAN_LOCAL_DIR

, the

/local-plans/<slug>

route is also valid. Do not invent a hosted database URL and do not publish just to get an absolute Plan link.

After creating the recap, link the reviewer to the rendered plan with an absolute URL on the origin whose database actually holds the plan. That origin is the Plan MCP server you just created the recap through — NOT whatever dev server you happen to know is running. The create tool returns the correct link; report THAT. Never make the primary link a local

plan.mdx

file, a local mirror folder, or a relative path such as

/plans/<id>

When the recap is posted to a PR for a private repo, the plan link is not a public URL. Make the PR comment/handoff copy explicit: reviewers may need to sign in to Agent-Native Plans with an account that has access to the owning organization before the link loads. Use wording like: "Private repo recap: sign in with access to this org if the plan does not open." Do not imply the link is broken or public when access is gated by repo/org visibility.

A recap lives only in the database of the MCP that created it. A separately running local dev server (e.g.

http://localhost:8081

) has its OWN database and will NOT contain a recap created through the hosted MCP, so a hand-built

localhost

link returns "Plan not found". This is the most common recap mistake — do not guess an origin you have not confirmed shares the MCP's data.

Resolve the URL in this order:

Use the absolute URL the create tool RETURNS —
```
openLink.webUrl
```
, else the
```
visualUrl
```
in the returned
```
plan.mdx
```
frontmatter, else
```
url
```
/
```
path
```
resolved against the MCP server's own origin (for the hosted MCP that is
```
https://plan.agent-native.com
```
). This always points at the database that has the plan.
Use a
```
localhost
```
/dev origin ONLY when the recap was created through a Plan MCP bound to that same origin — i.e. that MCP's url is
```
http://localhost:<port>/mcp
```
. Creating through the hosted MCP and linking to localhost is the exact mismatch that 404s.
If only a plan id is available, build the MCP origin's absolute URL (hosted:
```
https://plan.agent-native.com/plans/<id>
```
) and say it was inferred.

If the user wants to review on localhost but the recap was created through the hosted MCP, say so plainly: the local dev server cannot see it. To view a recap on localhost (e.g. to exercise un-deployed local renderer changes), they must connect a LOCAL Plan MCP (

http://localhost:<port>/mcp

) and re-create the recap through it so it lands in the local database; offer to do that rather than handing over a localhost URL that will not resolve.

When running in Codex and the Browser/in-app side browser tools are available, open the returned absolute recap URL there automatically after creation. Still include the same absolute URL in the final response. Local mirror files like

plans/<slug>/plan.mdx

may be mentioned only as secondary source-control artifacts, not as the main way to open the recap.

在本地文件隐私模式下，先运行

plan local check

，然后报告来自

npx @agent-native/core@latest plan local serve --dir <plan-dir> --kind recap --open

或

<plan-dir>/.plan-url

的本地桥接URL。它会打开托管方案UI，但从本机的localhost桥接读取内容，因此无法跨机器共享。如果Plan应用本身在本地运行且使用相同的

PLAN_LOCAL_DIR

，则

/local-plans/<slug>

路由也有效。请勿编造托管数据库URL，也不要仅为获取绝对方案链接而发布。

创建回顾报告后，将评审人员链接到渲染后的方案，链接必须是实际存储方案的源站的绝对URL。该源站是你刚刚创建回顾报告所用的Plan MCP服务器——而非你碰巧知道正在运行的任何开发服务器。创建工具会返回正确的链接；请报告该链接。切勿将本地

plan.mdx

文件、本地镜像文件夹或相对路径（如

/plans/<id>

）作为主要链接。

当回顾报告发布到私有仓库的PR时，方案链接不是公共URL。PR评论/交接文案需明确：评审人员可能需要使用拥有该组织访问权限的账号登录Agent-Native Plans，链接才能加载。使用类似措辞：“私有仓库回顾报告：如果方案无法打开，请使用拥有该组织访问权限的账号登录。”当访问受仓库/组织可见性限制时，请勿暗示链接已损坏或为公共链接。

回顾报告仅存在于创建它的MCP数据库中。单独运行的本地开发服务器（如

http://localhost:8081

）有自己的数据库，不会包含通过托管MCP创建的回顾报告，因此手动构建的

localhost

链接会返回“方案未找到”。这是最常见的回顾报告错误——请勿猜测未确认与MCP数据共享的源站。

按以下顺序解析URL：

使用创建工具返回的绝对URL——
```
openLink.webUrl
```
，否则返回
```
plan.mdx
```
前置元数据中的
```
visualUrl
```
，否则返回基于MCP服务器自身源站解析的
```
url
```
/
```
path
```
（托管MCP的源站为
```
https://plan.agent-native.com
```
）。该URL始终指向存储方案的数据库。
仅当回顾报告是通过绑定到该源站的Plan MCP创建时，才使用
```
localhost
```
/开发源站——即该MCP的URL为
```
http://localhost:<port>/mcp
```
。通过托管MCP创建并链接到localhost是导致404的典型不匹配情况。
如果仅提供方案ID，请构建MCP源站的绝对URL（托管：
```
https://plan.agent-native.com/plans/<id>
```
）并说明该URL是推断得出的。

如果用户希望在localhost上评审，但回顾报告是通过托管MCP创建的，请明确说明：本地开发服务器无法看到它。要在localhost上查看回顾报告（如测试未部署的本地渲染器变更），他们必须连接本地Plan MCP（

http://localhost:<port>/mcp

）并通过它重新创建回顾报告，使其进入本地数据库；请主动提出协助完成此操作，而非提供无法解析的localhost链接。

在Codex中运行且浏览器/应用内侧边浏览器工具可用时，创建完成后自动打开返回的绝对回顾报告URL。最终响应中仍需包含该绝对URL。本地镜像文件如

plans/<slug>/plan.mdx

仅可作为次要的源代码控制工件提及，而非打开回顾报告的主要方式。

Diff → Block Mapping

差异→块映射

Map each kind of change to the block that carries it, derived mechanically from the actual diff. The names below are the CONCEPTUAL block types, not the JSX tags — resolve every conceptual name to its exact tag + prop schema with the

get-plan-blocks

tool (see "Block reference" below) before authoring.

Schema / migration change →
```
data-model
```
for the resulting entities, fields, and relations. Flag what moved per field/entity with
```
change: "added" | "modified" | "removed" | "renamed"
```
, and for a changed type set
```
was
```
to the prior value (e.g. the old column type) — grounded in the real migration diff. That diff-aware
```
data-model
```
is the headline; reach for a split
```
diff
```
of the literal SQL only when the exact statement still matters, not by default.
API / action / route change →
```
api-endpoint
```
with the method, path, params, request, and responses as they are after the change. Flag each changed param/response with
```
change
```
(and
```
was
```
on a param whose type/shape changed), and set
```
change
```
on the endpoint root for a wholly added or removed route. Mark removed endpoints with
```
deprecated: true
```
and explain in prose. Keep multiple API endpoints in the normal single-column document flow unless they are an explicit before/after contract comparison. Author each request/response example as a SINGLE valid JSON value — one top-level object or array, parseable on its own — so it renders in the collapsible JSON explorer. Do not put
```
//
```
or
```
/* */
```
comments, prose, trailing commas, or two or more concatenated top-level objects inside one example; a non-parseable body falls back to flat text and loses the explorer. When an endpoint has several distinct message shapes (for example separate websocket frame types, or a success body versus an error body), give each its OWN example with its own label rather than cramming them into one body.
Compatibility-sensitive change → short
```
rich-text
```
notes beside the relevant
```
data-model
```
/
```
api-endpoint
```
block. Name the changed field, endpoint, or behavior and mark whether it is breaking, risky, or non-breaking; pair that note with a split
```
diff
```
for the literal lines.
Any meaningful code hunk →
```
diff
```
with
```
mode: "split"
```
, carrying the real
```
before
```
/
```
after
```
text and the
```
filename
```
/
```
language
```
. Split mode is the default for recap code review because before/after legibility is the point; use
```
mode: "unified"
```
only for a genuinely narrow standalone hunk where side-by-side would hide the code. Give every
```
diff
```
a one-line
```
summary
```
saying what the hunk changes and why; it renders as a description above the code so the reviewer reads intent first. Never leave a diff unlabeled. For the KEY changed files, attach
```
annotations
```
to the
```
diff
```
so the recap calls out what each important hunk does — this is the headline affordance for annotating the key files updated. Each annotation anchors to the AFTER-side line numbers by default (set
```
side: "before"
```
to point at removed lines). Keep it to a few high-signal notes per file, not one per line. When several key files each need a substantial diff, introduce the group with a
```
rich-text
```
heading block whose markdown is
```
## Key changes
```
, then place the
```
diff
```
blocks under it in a reusable
```
tabs
```
block with horizontal orientation (the default — omit
```
orientation
```
) so the selected file's split diff gets the full document width. Let that heading label the section — do NOT also set a
```
title
```
on the
```
tabs
```
block. Keep each tab label to the file path or a short basename plus directory hint. The renderer's wide document layout is intentionally allowlisted:
```
diff
```
,
```
annotated-code
```
, vertical
```
tabs
```
, and
```
tabs
```
containing diff-like children break out wider than prose. Do not put API endpoints, OpenAPI specs, data models, JSON explorers, wireframes, question forms, or custom HTML into tabs merely to make them wide. If the recap ends with more than one supporting diff, that trailing diff appendix should be one horizontal
```
tabs
```
block under its own
```
## Key changes
```
heading, not a stack of separate
```
diff
```
blocks.
Brand-new file or a substantial added block with no meaningful "before" →
```
annotated-code
```
rather than a one-sided split
```
diff
```
. Carry the real new code with its
```
filename
```
/
```
language
```
and anchor a few high-signal notes to the lines that matter so the reviewer reads what the new code does, not code for code's sake. Keep split
```
diff
```
for true before/after hunks where the removed lines still carry meaning, and group several annotated walkthroughs in a horizontal
```
tabs
```
block the same way diffs are grouped.
Files added / removed / renamed →
```
file-tree
```
with each entry's
```
change
```
flag (
```
added
```
,
```
removed
```
,
```
modified
```
,
```
renamed
```
) and a short
```
note
```
; attach a
```
snippet
```
only when one tells the reviewer something the path does not.
Rendered UI / interaction change → one or more wireframes showing the visible UI delta before the reviewer reads code. Use
```
Before
```
/
```
After
```
wireframes when the comparison clarifies the change; otherwise use after-only or a short state/flow sequence. Use realistic UI surfaces: for a popover change, show a popover with its title row, top-right actions, options/fields, tabs, selected/disabled states, people/lists/rows, and any opened prompt/menu anchored to the correct trigger. If a route was added, show the route body and the unavailable/empty state when the diff implements one. If permissions changed, show what managers can do and what viewers/non-managers see instead. Keep the body lean: the wireframe carries the UI story, while the file tree and
```
diff
```
blocks carry implementation evidence.
Architecture or data-flow shift →
```
diagram
```
with
```
data.html
```
/
```
data.css
```
as a two-panel before/after, layered, or swimlane layout, or
```
mermaid
```
for a quick graph. Use two-dimensional layouts; do not reduce a structural change to a left-to-right chain. Do not use
```
diagram
```
as a stand-in for rendered UI controls; UI changes need
```
wireframe
```
blocks. Author diagram HTML/CSS with the renderer-owned
```
.diagram-*
```
primitives (
```
.diagram-panel
```
,
```
.diagram-node
```
,
```
.diagram-pill
```
,
```
[data-rough]
```
, …) and the same
```
--wf-*
```
theme tokens
```
references/wireframe.md
```
defines — never
```
font-family
```
, hex, rgb/hsl literals, or one-off dark/light palettes. Choose the outer
```
frame
```
intentionally: recap diagrams usually benefit from
```
frame: "show"
```
when they stand alone, but use
```
frame: "hide"
```
when columns, tabs, a card, or the diagram's own panels already provide the boundary.
Outcome-first narrative →
```
rich-text
```
for the "what changed and why" prose: the objective the diff served, the key decisions visible in it, and the risks a reviewer should weigh. This is the only place the model writes freely.

将每种变更类型映射到对应的块，该映射需从实际差异中机械推导得出。以下名称是概念性块类型，而非JSX标签——创作前请通过

get-plan-blocks

工具（见下文“块参考”）将每个概念名称解析为其确切的标签+属性架构。

架构/迁移变更 →
```
data-model
```
，用于展示最终的实体、字段和关系。使用
```
change: "added" | "modified" | "removed" | "renamed"
```
标记每个字段/实体的变更类型，对于类型变更，设置
```
was
```
为先前值（如旧列类型）——基于真实的迁移差异。这种差异感知的
```
data-model
```
是核心内容；仅当确切语句仍重要时，才使用拆分式
```
diff
```
展示字面SQL，而非默认如此。
API/操作/路由变更 →
```
api-endpoint
```
，包含变更后的方法、路径、参数、请求和响应。使用
```
change
```
标记每个已变更的参数/响应（参数类型/形状变更时设置
```
was
```
），对于完全新增或移除的路由，在端点根节点设置
```
change
```
。将已移除的端点标记为
```
deprecated: true
```
并在散文中说明。除非是明确的前后合约对比，否则将多个API端点保持在正常的单列文档流中。每个请求/响应示例需为单个有效的JSON值——一个顶级对象或数组，可独立解析——以便在可折叠的JSON浏览器中渲染。请勿在示例中添加
```
//
```
或
```
/* */
```
注释、散文、尾随逗号或两个以上的顶级对象；不可解析的主体会回退为纯文本并失去浏览器功能。当端点有多个不同的消息形状（如不同的WebSocket帧类型，或成功主体与错误主体）时，为每个形状创建单独的示例并添加标签，而非将它们塞进一个主体中。
兼容性敏感变更 → 在相关的
```
data-model
```
/
```
api-endpoint
```
块旁添加简短的
```
rich-text
```
注释。指明已变更的字段、端点或行为，并标记其是否为破坏性、有风险或非破坏性；将该注释与拆分式
```
diff
```
搭配展示字面代码行。
任何有意义的代码块 →
```
diff
```
，设置
```
mode: "split"
```
，包含真实的
```
before
```
/
```
after
```
文本以及
```
filename
```
/
```
language
```
。拆分模式是回顾报告代码评审的默认模式，因为前后对比的可读性是核心；仅当真正狭窄的独立代码块使用并排布局会隐藏代码时，才使用
```
mode: "unified"
```
。每个
```
diff
```
需包含一行
```
summary
```
，说明该代码块的变更内容及原因；它会渲染在代码上方作为描述，以便评审人员先了解意图。切勿让diff无标签。对于关键变更文件，为
```
diff
```
添加
```
annotations
```
，以便回顾报告突出显示每个重要代码块的作用——这是标记已更新关键文件的核心功能。每个注释默认锚定到“之后”侧的行号（设置
```
side: "before"
```
可指向已移除的行）。每个文件仅保留几个高信号注释，而非每行一个。当多个关键文件都需要大量diff时，使用markdown为
```
## Key changes
```
的
```
rich-text
```
标题块引入该组，然后将
```
diff
```
块放在可重用的水平
```
tabs
```
块中（默认布局——省略
```
orientation
```
），以便选中文件的拆分diff获得完整文档宽度。让该标题标记该部分——不要为
```
tabs
```
块设置
```
title
```
。每个标签页标签保持为文件路径或简短的基名加目录提示。渲染器的宽文档布局是特意允许的：
```
diff
```
、
```
annotated-code
```
、垂直
```
tabs
```
以及包含类diff子元素的
```
tabs
```
会比散文更宽。请勿将API端点、OpenAPI规范、数据模型、JSON浏览器、线框、问题表单或自定义HTML放入标签页中仅仅为了使其变宽。如果回顾报告末尾有多个支持性diff，该末尾diff附录应放在其自己的
```
## Key changes
```
标题下的一个水平
```
tabs
```
块中，而非多个单独的
```
diff
```
块堆叠。
全新文件或无意义“之前”版本的大量新增块 → 使用
```
annotated-code
```
而非单边拆分
```
diff
```
。包含真实的新代码及其
```
filename
```
/
```
language
```
，并为重要代码行添加几个高信号注释，以便评审人员了解新代码的作用，而非仅看代码本身。仅当已移除的行仍有意义时，才使用拆分
```
diff
```
展示真实的前后代码块；多个注释式讲解也按diff的方式分组在水平
```
tabs
```
块中。
文件新增/移除/重命名 →
```
file-tree
```
，每个条目包含
```
change
```
标记（
```
added
```
、
```
removed
```
、
```
modified
```
、
```
renamed
```
）和简短的
```
note
```
；仅当代码片段能为评审人员提供路径之外的信息时，才添加
```
snippet
```
。
渲染UI/交互变更 → 一个或多个线框，在评审人员阅读代码前展示可见的UI差异。当对比有助于澄清变更时，使用
```
Before
```
/
```
After
```
线框；否则使用仅展示“之后”的线框或简短的状态/流程序列。使用真实的UI表面：对于弹出框变更，展示弹出框及其标题行、右上角操作、选项/字段、标签页、选中/禁用状态、人员/列表/行以及锚定到正确触发器的任何打开的提示/菜单。如果新增了路由，展示路由主体以及差异实现的不可用/空状态。如果权限变更，展示管理员可执行的操作以及查看者/非管理者看到的内容。保持主体简洁：线框承载UI故事，而file-tree和
```
diff
```
块承载实现证据。
架构或数据流转变 →
```
diagram
```
，使用
```
data.html
```
/
```
data.css
```
作为双面板前后对比、分层或泳道布局，或使用
```
mermaid
```
快速生成图表。使用二维布局；切勿将结构变更简化为左右链状。请勿将
```
diagram
```
作为渲染UI控件的替代品；UI变更需要
```
wireframe
```
块。使用渲染器自带的
```
.diagram-*
```
原语（
```
.diagram-panel
```
、
```
.diagram-node
```
、
```
.diagram-pill
```
、
```
[data-rough]
```
等）和
```
references/wireframe.md
```
定义的相同
```
--wf-*
```
主题令牌创作图表HTML/CSS——切勿使用
```
font-family
```
、十六进制、rgb/hsl字面量或一次性深色/浅色调色板。有意选择外部
```
frame
```
：当回顾报告图表单独存在时，通常受益于
```
frame: "show"
```
；但当列、标签页、卡片或图表自身的面板已提供边界时，使用
```
frame: "hide"
```
。
成果优先说明 →
```
rich-text
```
，用于“变更内容及原因”的散文：差异所服务的目标、差异中可见的关键决策以及评审人员应权衡的风险。这是模型可自由创作的唯一部分。

Block reference — call

get-plan-blocks

, do not memorize tags

块参考——调用

get-plan-blocks

，切勿凭记忆使用标签

The conceptual block names above (

api-endpoint

data-model

json-explorer

tabs

, …) are NOT the JSX tags you author with, and the exact tags, required fields, and prop shapes change as the block library evolves. Do not author from memorized tags — they drift and silently produce a wrong tag (

ApiEndpoint

instead of

Endpoint

JsonExplorer

instead of

Json

Tabs

instead of

TabsBlock

) that errors on import.

Before writing any structured plan content, fetch/read the block catalog. In hosted or self-hosted mode, call

get-plan-blocks

on the Plan MCP connector (

plan

or legacy

agent-native-plans

). If no Plan tools are visible yet in a lazy-loading client, search/load them through the host's tool discovery surface first (

tool_search

when available). In local-files mode, or when the skill was installed as plain text and no MCP tools are registered after discovery, run

npx @agent-native/core@latest plan blocks --out plan-blocks.md

and read that file first. The CLI command calls the public no-auth

get-plan-blocks

route and sends no plan/recap content. If network access is unavailable, use the bundled references and validate with

plan local check

; run

plan local serve

only when the hosted Plan UI is reachable or a local Plan app is already running.

The catalog returns the authoritative, always-current block vocabulary generated live from the app's own block registry — the same config the renderer and MDX round-trip use — so it can never be stale even if this SKILL.md is an old installed copy:

```
get-plan-blocks
```
(default
```
format: "reference"
```
) → a compact table of every block's runtime
```
type
```
, exact MDX
```
<Tag>
```
, placement, and key data fields. This is your map from each conceptual name above to its real tag and props.
```
get-plan-blocks
```
with
```
format: "schema"
```
→ the full per-block JSON Schema plus a worked example for each block, when you need exact field types, enums, or nesting (e.g.
```
Diff.annotations
```
,
```
Endpoint.params[].in
```
,
```
DataModel.entities[].fields[]
```
).

Author the recap source against the tags and schemas that call returns. The complete set of valid block-level tags is whatever

get-plan-blocks

lists; any other capitalized tag at the block level is rejected on import with an "Unknown plan block" / "did you mean" error. Lowercase HTML tags inside

rich-text

/markdown prose (

<div>

<span>

<code>

<br>

, …) are always fine — only capitalized component-style block tags are validated.

A few recap-specific authoring rules the registry table cannot encode:

Every structured block takes a REQUIRED
```
id
```
(unique across the whole plan) plus the shared optional
```
summary
```
/
```
editable
```
envelope. Ordinary top-level Markdown prose imports as rich-text automatically; use
```
<RichText id="...">
```
only when prose needs explicit metadata or a preserved referenced block id.
Every capitalized block component must be self-closing (
```
<Diagram ... />
```
) or explicitly closed around children (
```
<RichText ...>...</RichText>
```
). Never leave a bare opening tag like
```
<RichText ...>
```
in a paragraph; MDX treats it as unclosed JSX and import fails before the recap can render.
Code-bearing blocks (
```
Code
```
,
```
AnnotatedCode
```
, and
```
Diff
```
) are whitespace-sensitive. Prefer the exact MDX form from the
```
get-plan-blocks
```
examples / source exporter, where multiline code is encoded as JSON string attributes such as
```
code={"const x =\n  y"}
```
. Static template literals are accepted only when they are static strings with no
```
${...}
```
interpolation.
```
Endpoint
```
: prose
```
description
```
is the MDX children (body between the tags), not an attribute; for a WebSocket upgrade use
```
method="GET"
```
. Each request/response
```
example
```
is a JSON string (the renderer parses it into the JSON explorer), so keep it a single parseable JSON value.
```
TabsBlock
```
: the whole
```
tabs
```
array (including nested child blocks) is ONE JSON
```
tabs={[…]}
```
prop — there is NO nested
```
<Tab>
```
element.
```
WireframeBlock
```
: its body is a single
```
<Screen surface ... html=… />
```
subtree (nested MDX, not a flat prop);
```
html
```
must be a single-quoted string or static template literal, never a dynamic
```
html={someVar}
```
expression. See
```
references/wireframe.md
```
for the HTML rules.
```
Diagram
```
: the whole payload is one
```
data={{ html?, css?, nodes?, edges?, … }}
```
attribute and requires either
```
html
```
or at least one node;
```
Mermaid
```
is its own separate block (
```
source
```
text), not a
```
Diagram
```
prop.

上述概念性块名称（

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散文会自动导入为rich-text；仅当散文需要显式元数据或保留引用块id时，才使用
```
<RichText id="...">
```
。
每个大写的块组件必须自闭合（
```
<Diagram ... />
```
）或显式闭合包裹子元素（
```
<RichText ...>...</RichText>
```
）。切勿在段落中留下未闭合的开始标签，如
```
<RichText ...>
```
；MDX会将其视为未闭合的JSX，导致导入失败，回顾报告无法渲染。
承载代码的块（
```
Code
```
、
```
AnnotatedCode
```
和
```
Diff
```
）对空格敏感。优先使用
```
get-plan-blocks
```
示例/源导出器中的精确MDX形式，其中多行代码编码为JSON字符串属性，如
```
code={"const x =\ 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
```
：整个 payload 是一个
```
data={{ html?, css?, nodes?, edges?, … }}
```
属性，且需要
```
html
```
或至少一个节点；
```
Mermaid
```
是单独的块（
```
source
```
文本），而非
```
Diagram
```
的属性。

Before / After Is The Headline

前后对比是核心内容

The recap's center of gravity is the before/after comparison. For document-body comparisons there are two primitives, and they cover the whole need together:

columns
— the side-by-side container, for structured comparisons. Use two columns labeled
```
Before
```
and
```
After
```
, each holding a block (commonly a
```
data-model
```
,
```
api-endpoint
```
, or
```
rich-text
```
), so the reviewer reads the old shape against the new shape in one glance. This is the right primitive for "the schema went from X to Y" or "the endpoint contract changed like this." Do not use
```
columns
```
simply to compact or group a list of API endpoints.
diff
— for code. It renders the literal removed and added lines. Use it for the actual hunks. Use split mode by default for recap code review; reserve
```
mode: "unified"
```
for genuinely narrow standalone hunks where side-by-side would hide the code. Key-file diff groups should use horizontal tabs so split diffs get the full document width.

For UI diffs, wireframes are the visual comparison primitive. Use before/after wireframes when the comparison clarifies the change; use after-only or a state sequence when that better matches the change. The visual headline must show exact placement, realistic chrome, and adequate padding before any abstract explanation. Do not stop at the first visible affordance when the diff adds a flow; show the entry point, the opened surface, and the resulting state or page so the reviewer can trace the actual user path.

references/wireframe.md

owns the before/after layout choice — the

columns

renderer keeps narrow surfaces side by side and auto-stacks wide

desktop

browser

frames vertically; never hand-build a side-by-side wireframe layout in

custom-html

. For document-body comparisons, there is no other multi-column primitive —

columns

plus the

diff

block are the whole comparison vocabulary. Do not hand-build side-by-side layouts in

custom-html

, and do not stack two

data-model

blocks vertically and call it a comparison when

columns

exists to put them side by side.

回顾报告的核心是前后对比。对于文档主体对比，有两个原语，它们共同满足所有需求：

columns
——并排容器，用于结构化对比。使用两个标记为
```
Before
```
和
```
After
```
的列，每个列包含一个块（通常是
```
data-model
```
、
```
api-endpoint
```
或
```
rich-text
```
），以便评审人员一眼就能看到旧形状与新形状的对比。这是“架构从X变为Y”或“端点合约如此变更”的正确原语。请勿仅为压缩或分组API端点列表而使用
```
columns
```
。
diff
——用于代码对比。它渲染已移除和新增的字面代码行。用于展示实际的代码块。回顾报告代码评审默认使用拆分模式；仅当真正狭窄的独立代码块使用并排布局会隐藏代码时，才保留
```
mode: "unified"
```
。关键文件diff组应使用水平标签页，以便拆分diff获得完整文档宽度。

对于UI差异，线框是视觉对比原语。当对比有助于澄清变更时，使用前后线框；当更符合变更情况时，使用仅展示“之后”的线框或状态序列。视觉核心内容必须在任何抽象说明之前展示精确的位置、真实的导航栏和足够的内边距。当差异添加流程时，不要停留在第一个可见的交互元素；展示入口点、打开的表面以及最终状态或页面，以便评审人员可以追踪实际的用户路径。

references/wireframe.md

规定了前后布局的选择——

columns

渲染器将狭窄表面并排展示，自动将宽

desktop

browser

框架垂直堆叠；切勿在

custom-html

中手动构建并排线框布局。对于文档主体对比，没有其他多列原语——

columns

加

diff

块是完整的对比词汇表。请勿在

custom-html

中手动构建并排布局，也不要将两个

data-model

块垂直堆叠并称之为对比，因为

columns

可以将它们并排展示。

Grounding Rule

真实性规则

Structured blocks are true by construction only if they are derived from the actual changed lines. The

diff

data-model

api-endpoint

, and

file-tree

blocks MUST be built mechanically from the real diff — real paths, real fields, real method/path, real before/after text — never inferred, rounded, or invented. The model writes only the prose: the "why", the narrative, the risk read. A confidently wrong recap is dangerous in a review context, because a reviewer who trusts the summary may skip the very line the summary got wrong. When the diff does not contain a fact, leave it out rather than guess; mark anything the model inferred (not extracted) as inferred in prose.

结构化块只有从实际变更行中推导出来才是构建真实的。

diff

、

data-model

、

api-endpoint

和

file-tree

块必须从真实差异中机械构建——真实路径、真实字段、真实方法/路径、真实前后文本——切勿推断、简化或编造。模型仅创作散文：“原因”、说明、风险评估。在评审场景中，自信的错误回顾报告是危险的，因为信任摘要的评审人员可能会跳过摘要出错的那一行代码。当差异中不包含某个事实时，请省略它而非猜测；将模型推断（而非提取）的任何内容在散文中标记为推断内容。

Security

安全

Gate visibility. Recaps of a private repo are org/login-gated — set the plan's visibility to the owning org or login, never auto-public. A recap can expose unreleased schema, internal endpoints, and architecture; treat it like the source it summarizes. Any PR comment or handoff that links to the recap must say that private-repo recaps require signing in with access to the owning org if the link does not load.
Never transcribe secrets. A diff can contain API keys, tokens, webhook URLs, signing secrets,
```
.env
```
values, or credential-looking literals. Do not copy any of these into a
```
diff
```
,
```
file-tree
```
snippet,
```
api-endpoint
```
, or prose block — redact them (
```
sk-•••
```
,
```
<redacted>
```
). This mirrors the repo's hardcoded-secret rule: obviously fake placeholders only, never the real value, in any block, caption, or note.

访问权限控制：私有仓库的回顾报告受组织/登录权限限制——将方案的可见性设置为所属组织或登录用户，切勿自动设为公开。回顾报告可能暴露未发布的架构、内部端点和架构；请像对待它所总结的源代码一样对待它。任何链接到回顾报告的PR评论或交接文案必须说明，如果链接无法加载，私有仓库回顾报告需要使用拥有所属组织访问权限的账号登录。
切勿转录机密信息：差异中可能包含API密钥、令牌、Webhook URL、签名密钥、
```
.env
```
值或类似凭证的字面量。请勿将任何此类内容复制到
```
diff
```
、
```
file-tree
```
片段、
```
api-endpoint
```
或散文块中——请编辑掉（如
```
sk-•••
```
、
```
<redacted>
```
）。这与仓库的硬编码机密规则一致：任何块、标题或注释中仅允许使用明显的假占位符，绝不允许使用真实值。

Bidirectional Loop

双向循环

In hosted mode, because a recap is a real, editable plan, the same review loop as forward plans applies: a reviewer can annotate any block, and the coding agent reads

get-plan-feedback

to drive fixes back into the code — annotation → agent → diff, the same close-the-loop flow forward plans use. After a reviewer annotates a block, call

get-plan-feedback

to read the structured feedback, then either update the recap with

create-visual-recap

(passing the existing

planId

to replace it in place) or apply targeted changes with

update-visual-plan

. The loop is live and wired. In local-files privacy mode, do not call those hosted tools; read review notes from chat or local files, edit

<plan-dir>/*.mdx

directly, and rerun

plan local check

serve

, or

verify

for

<plan-dir>

. The one thing not yet automatic is PR-comment-triggered re-runs: the GitHub Action creates an initial recap per PR, but it does not yet re-run automatically when new review feedback is posted in GitHub — that auto-re-run is the remaining fast-follow.

在托管模式下，由于回顾报告是真实的可编辑方案，正向方案的评审循环同样适用：评审人员可以为任何块添加注释，编码Agent读取

get-plan-feedback

以驱动代码修复——注释→Agent→差异，与正向方案使用的闭环流程相同。评审人员为块添加注释后，调用

get-plan-feedback

读取结构化反馈，然后要么使用

create-visual-recap

更新回顾报告（传入现有

planId

以就地替换），要么使用

update-visual-plan

应用针对性变更。该循环是实时且连通的。在本地文件隐私模式下，请勿调用这些托管工具；从聊天或本地文件中读取评审笔记，直接编辑

<plan-dir>/*.mdx

，并重新运行

plan local check

、

serve

或

verify

以处理

<plan-dir>

。目前尚未自动化的一件事是PR评论触发的重新运行：GitHub Action会为每个PR创建初始回顾报告，但当新的评审反馈发布到GitHub时，它尚未自动重新运行——自动重新运行是后续的优化方向。

visual-recap

Original

Translation

Visual Recap

可视化回顾报告

Publish As An Agent-Native Plan — Never Inline

以Agent-Native方案形式发布——绝不以内联内容呈现

Local-Files Privacy Mode — read references/local-files.md

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

When To Use

使用场景

Recap The Whole Work Unit

回顾整个工作单元

Keep The Recap Body Lean

保持回顾报告主体简洁

Recaps Must Be Substantial

回顾报告必须内容充实

Canonical Shape And Budgets

标准结构与内容限制

UI Impact Needs Wireframes

UI变更需包含线框

Wireframe Quality — read references/wireframe.md

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

Top Canvas Recaps — read ../visual-plan/references/canvas.md

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

Open And Report The Recap

打开并报告回顾报告

Diff → Block Mapping

差异→块映射

Block reference — call get-plan-blocks, do not memorize tags

块参考——调用 get-plan-blocks，切勿凭记忆使用标签

Before / After Is The Headline

前后对比是核心内容

Grounding Rule

真实性规则

Security

安全

Bidirectional Loop

双向循环

Related Skills

相关技能

Local-Files Privacy Mode — read
`references/local-files.md`

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

Wireframe Quality — read
`references/wireframe.md`

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

Top Canvas Recaps — read
`../visual-plan/references/canvas.md`

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

Block reference — call
`get-plan-blocks`
, do not memorize tags

块参考——调用
`get-plan-blocks`
，切勿凭记忆使用标签