当 PR、分支、提交或 git diff 较大且涉及多文件…

把已完成的 PR、分支、提交或 git diff 转成托管的 Agent-Native 可视化回顾，供审查者高效浏览和批注。

适用场景

解决思路

1. 交付物始终是通过 Plan MCP connector 上的 create-visual-recap 发布的 Agent-Native Plan；不要用内联聊天内容替代，包括 Markdown 散文、ASCII 草图、表格、围栏 wireframe 或 here's the recap 摘要。
2. 如果 plan 或旧 agent-native-plans 工具不可见，先用宿主的 tool_search 发现；仍不可用时 STOP，并给用户对应客户端的重连步骤，而不是临时做内联回顾。
3. 发布前或出现 connector/auth 错误时，READ references/connection.md，它是 never-inline 规则、connector 发现和各客户端重连步骤的唯一事实来源。
4. 当用户要求 no hosted Plan database writes、无 DB 写入、无 Plan MCP 发布、完全本地/离线/私有回顾，或 AGENT_NATIVE_PLANS_MODE=local-files 时，除 schema-only 的 get-plan-blocks catalog lookup 外不要调用任何 hosted Plan 工具。
5. 在 local-files privacy mode，用本地 recap collect-diff / scan / build-prompt --local-files helpers 读取 diff，编写本地 MDX folder，设置 kind 为 recap、localOnly 为 true，并用 plan local check、plan local serve --kind recap、plan local verify --kind recap 预览。
6. 使用 local-files mode 前，READ references/local-files.md，它是完整契约的唯一事实来源。
7. 当 PR 或 commit 很大、多文件，或触及 schema、API contracts、architecture，且审查者能从结构化 blocks 映射变更受益时，生成 recap。
8. 可由 GitHub Action 从 PR diff 自动生成 recap；代理也可在请求如 recap this PR、show me what this branch changed 时生成。
9. 在聊天线程中已发生后调用 /visual-recap 时，默认范围是整个当前 work unit/thread，而不只是最新用户消息、工具动作或后续修复。
10. 收集线程内跨对话的变更：原始实现工作、后续 bug fixes、UI follow-ups、tests、changesets、skill/instruction updates、生成的 plan/source artifacts，以及让 recap 可打开所需的本地 import/linking fixes。
11. 使用当前 diff 加对话上下文，区分线程拥有的变更和线程前已存在的无关 dirty work。
12. 排除无关的既有编辑；如果范围确实模糊且无法推断，发布前陈述假设或问一个简短问题。
13. 更新已有 recap after feedback 时，修订后仍覆盖整个 thread/work unit 加新修正；不要用只覆盖最新反馈的窄 recap 替换宽 recap，除非用户明确要求更窄范围。
14. 不要向生成的 plan body 添加 boilerplate intro、disclaimer、provenance 或 summary prose blocks。
15. 特别不要创建 rich-text block 仅为了说明 recap 是辅助、审查者仍应审查 diff、多少文件变更、或哪个 ref/working tree 生成 recap；plan title、brief 和 file-tree 已承载这些上下文。
16. 仅当 prose blocks 告诉审查者结构化块没有的具体变更信息时才添加：目标、真实兼容风险、diff 中可见的重要决策、有依据的 review note。
17. Lean 不等于 thin；不要只放一个 wireframe 加一句话，那和 boilerplate prose 一样不能充分服务审查者。
18. 在视觉/结构头条之外，substantial recap 还要承载 implementation evidence。
19. 编写前做短 surface/state inventory：列出 diff 中可见的 changed routes、components、popovers/dialogs、role/access states、empty/error states、shared abstractions。
20. 最终 recap 必须为每个有意义项用 block 表示，或因为 tiny、redundant、not user-visible 而有意省略。
21. 包含 changed files 的 file-tree，每个条目带 change flag，让审查者一眼看到工作足迹。
22. 包含 KEY changed files 的 split diff，分组在 ## Key changes rich-text heading 下的单个 horizontal tabs block，默认 orientation，每个文件一个 tab，每个有一行 summary 和几个 annotations。
23. 使用 horizontal file tabs，而不是 vertical side rail，这样选中文件有足够宽度显示 side-by-side diff。
24. 仅对确实很小的变更跳过 diff 附录；任何值得 recap 的变更都应在 plan 中包含 file-tree 和 key-change diffs。
25. 按骨架 top to bottom 组织：UI-impact headline 在 diff 改变 rendered UI 时先放 wireframes。
26. 接着放 short outcome narrative rich-text：改了什么和为什么，1-3 段。
27. schema 和 contract changes 用 data-model / api-endpoint blocks。
28. 放 changed files 的 file-tree 并带 change flags。
29. 最后放 ## Key changes：一个 horizontal tabs block，包含 diff / annotated-code。
30. 保持 3-8 个 key-change tabs；大变更少于 3 个 under-serves reviewer，多于 8 个不再是 summary。
31. 每个 diff/annotated-code 摘录保持聚焦，每个 tab 尽量少于约 150 行；长文件其余部分 summarize 或 link，不要 dump。
32. Title 最多约 70 字符；brief 1-3 句。
33. 这些预算是 cost ceiling；不要以彻底为名超出，也不要在初次顺序通读后重读完整 diff，使用那次通读时记的 notes。
34. 用 GOOD 模式校验：25 文件 auth 变更应包含 Before/After wireframes、两段叙事、diff-aware data-model、api-endpoint、file-tree、## Key changes 五个聚焦 tabs，每个有一行 summary 和 load-bearing hunks annotations。
35. 避免 BAD：巨大未分段 diff dump 无 summaries/annotations；或 40 文件变更只给三个块，如一个 wireframe、一句话、一个 file list，迫使审查者回到 raw diff。
36. 当 diff 改变 rendered UI、layout、density、visual state、interaction affordances、navigation、controls、menus、dialogs 或 design tokens 时，recap 必须包含一个或多个 wireframes；prose 和 file diffs 不是替代。
37. 选择 wireframes 前，从 diff 做 UI coverage pass：识别 change 出现的 entry surface，如 page header、list row、toolbar、route shell、menu trigger。
38. 识别会打开或变化的 interaction surface，如 popover、dialog、tab、sheet、dropdown、inline editor、toast。
39. 识别 resulting destination 或 persistent state，如 public page、read-only view、empty state、error state、loading state、permission-denied state、saved/shared state。
40. 权限变化时识别 access 或 role variants；owner/admin/editor 与 viewer/non-manager 差异需要 compact matrix、paired wireframes 或 clearly labeled state sequence。
41. UI-heavy PR 不能只给 entry surface 的单个 before/after；展示 changed entry point、main changed interaction surface、resulting/destination state。
42. 当 diff 增加 tabs、role-based controls、public/private visibility、invite/manage flows、destructive controls、empty/error branches 时增加更多状态。
43. 选择最小视觉表面：直接比较有益时用 Before/After wireframe pair，如 removed/added control、changed state、layout density、ordering、navigation、visible component replacement；references/wireframe.md 决定 columns vs vertical stack by geometry。
44. 纯新增或 before 只显示缺失且无审查价值时用 after-only wireframe。
45. UI 变更依赖流程、响应式或有状态时用多于两个 wireframes；按顺序展示有意义状态，不要强行一个 before/after pair。
46. 对 menus、popovers、dialogs、toasts、panels 等 tiny surfaces，用匹配的 surface，如 popover、panel 等，并展示聚焦子表面；除非页面中的 placement 本身是变更一部分，不要重画整页。
47. 每个 wireframe 基于 changed UI behavior、component names、file paths、diff-visible labels/states；如果像素是推断而非捕获，在 wireframe caption 或 concise annotation 说明。
48. 对 local/manual recaps，import 或 update 保存 wireframes 的 plan source，使 rendered recap 打开时 UI visual 可用。
49. UI recap/plan wireframes 必须满足严格质量：full-width chrome、pinned bottom bars、real product content、before/after comparability、正确 surface preset、--wf-* tokens 而不是 hex、无 <html>/<style>/font tags。
50. 在编写任何 wireframe、<Screen>、WireframeBlock 前，READ references/wireframe.md；不要凭记忆编写。
51. 使用标准 WireframeBlock / <Screen> 格式，让 Plan viewer 负责 surface frame、theme、sketchy/clean toggle。
52. 当 placement precision 重要时，尤其 popovers、menus、dialogs、dense forms，使用 HTML wireframes。
53. 对 HTML wireframes，保持 renderMode 未设置或 wireframe，除非明确要求 design-only editable mockup，因为 renderMode=design 会禁用 sketchy rough overlay。
54. 有 browser tool 时，在分享前把 UI-impact recap 渲染到 Plan viewer，并在当前 theme 下视觉检查。
55. 如果任何 label、annotation、toolbar、wireframe content 与其他元素重叠，修复 MDX 并在报告链接前 re-import。
56. 限制为一次 render-and-inspect 加至多一次 fix-and-re-render；除非用户明确要求，不要继续迭代。
57. text-match screenshot 不够；要视觉检查 captured image。无 browser 可用时，如 headless CI agent，在 recap handoff 中说明。
58. 当 recap 包含 top canvas、storyboard 或 flow view 时，在编写 canvas.mdx 前 READ ../visual-plan/references/canvas.md。
59. Recap canvas artboards 必须使用与好的 document-body wireframes 相同的 HTML wireframe 路径：<Screen surface=... html={...} /> 加 semantic HTML fragment。
60. 不要在 canvas <Screen> tags 内编写新的 kit-tree children，如 <FrameScreen>、<Card>、<Row>、<Title>、<Btn>；这些是旧 plans 的 legacy compatibility markup，在新 canvas storyboards 中即使 inline body wireframe 好看也可能 cramped 或 overlapping。
61. 如果 canvas mockup 看起来比 below the fold 的同一 screen 更差，假设用了 legacy kit path 并替换为 HTML screen。
62. 在 local-files privacy mode，先运行 plan local check，然后报告来自 npx @agent-native/core@latest plan local serve --dir <plan-dir> --kind recap --open 或 <plan-dir>/.plan-url 的 local bridge URL。
63. local bridge 会打开 hosted Plan UI 但读取本机 localhost bridge，所以不可跨机器分享；如果 Plan app 本地运行且 PLAN_LOCAL_DIR 相同，/local-plans/<slug> 路由也有效。
64. 不要发明 hosted database URL，也不要仅为获得绝对 Plan link 而发布。
65. 创建 recap 后，用其数据库实际持有该 plan 的 origin 上的绝对 URL 链接审查者；该 origin 是你刚刚用来创建 recap 的 Plan MCP server，不是你碰巧知道的 dev server；create tool 返回正确 link，报告它。
66. 绝不要把 local plan.mdx 文件、本地 mirror folder 或相对路径 /plans/<id> 作为主链接。
67. recap 发布到 private repo 的 PR 时，plan link 不是公开 URL；在 PR comment/handoff copy 中明确：reviewers 可能需要用有权访问 owning organization 的账号 sign in to Agent-Native Plans 后链接才会加载。
68. 使用类似措辞：Private repo recap: sign in with access to this org if the plan does not open。不要暗示链接坏了或公开。
69. recap 只存在于创建它的 MCP 的数据库中；单独运行的 local dev server，如 http://localhost:8081，有自己的数据库，不会包含通过 hosted MCP 创建的 recap，所以手工拼的 localhost link 会返回 Plan not found；不要猜未确认共享 MCP 数据的 origin。
70. 按顺序解析 URL：使用 create tool RETURNS 的 absolute URL，openLink.webUrl，否则返回的 plan.mdx frontmatter 中的 visualUrl，否则用 url/path 相对 MCP server 自己的 origin 解析；hosted 为 https://plan.agent-native.com；这总是指向持有 plan 的数据库。
71. 仅当 recap 通过绑定到同一 origin 的 Plan MCP 创建时才用 localhost/dev origin，即该 MCP 的 url 是 http://localhost:<port>/mcp；通过 hosted MCP 创建却链接 localhost 正是会 404 的错配。
72. 如果只有 plan id，构建 MCP origin 的 absolute URL，hosted 为 https://plan.agent-native.com/plans/<id>，并说明这是 inferred。
73. 如果用户想在 localhost 审查但 recap 是通过 hosted MCP 创建的，明确说 local dev server 看不到它。
74. 要在 localhost 查看 recap，例如测试未部署本地 renderer 变更，用户必须连接 LOCAL Plan MCP，即 http://localhost:<port>/mcp，并通过它重新创建 recap，使其落入本地数据库；提供这个方案，而不是给不会解析的 localhost URL。
75. 在 Codex 且 Browser/in-app side browser tools 可用时，创建后自动在那里打开返回的 absolute recap URL；最终响应仍包含同一 absolute URL。
76. 本地 mirror 文件如 plans/<slug>/plan.mdx 只能作为次要 source-control artifacts 提及，不作为打开 recap 的主要方式。
77. 将每种变更映射到承载它的 block，且从实际 diff 机械派生；下面的名称是概念 block 类型，不是 JSX tags；编写前用 get-plan-blocks 把每个概念名解析为确切 tag 加 prop schema。
78. Schema / migration change 用 data-model 表示 resulting entities、fields、relations；对每个 field/entity 用 change 设为 added、modified、removed、renamed 标记移动；对 changed type 设置 was 为之前值，如旧 column type，基于真实 migration diff；diff-aware data-model 是 headline，只有确切 SQL 语句仍重要时才用 split diff 呈现 literal SQL，不要默认。
79. API / action / route change 用 api-endpoint，包含变更后的 method、path、params、request、responses；对每个 changed param/response 标记 change，对 type/shape 变化的 param 设置 was，对完全新增或移除的路由在 endpoint root 设置 change；用 deprecated 设为 true 标记移除的 endpoints 并在 prose 解释。
80. 除非是明确的 before/after contract comparison，多个 API endpoints 保持普通 single-column document flow。
81. 将每个 request/response example 编写为单个有效 JSON 值，一个顶层 object 或 array，可单独解析，以便渲染到 collapsible JSON explorer。
82. 不要在同一个 example 内放 // 或 /* */ comments、prose、trailing commas 或两个以上拼接的顶层 objects；不可解析 body 会退回 flat text 并丢失 explorer。
83. 当一个 endpoint 有多个不同 message shapes，如 websocket frame types、success body 与 error body，给每个自己的 example 和 label，不要塞进一个 body。
84. Compatibility-sensitive change 在相关 data-model / api-endpoint 旁放短 rich-text notes；命名 changed field、endpoint 或 behavior，并标记 breaking、risky 或 non-breaking；配 split diff 显示 literal lines。
85. 任何 meaningful code hunk 用 diff，使用 mode 设为 split，携带真实 before / after 文本和 filename / language；split 是 recap code review 默认，因为 before/after 可读性是重点；仅在 genuinely narrow standalone hunk 且 side-by-side 会隐藏代码时用 mode 设为 unified。
86. 给每个 diff 一行 summary，说明该 hunk 改了什么和为什么；它渲染为代码上方描述，让审查者先读意图；绝不让 diff 无标签。
87. 对 KEY changed files，给 diff 附加 annotations，让 recap 指出每个重要 hunk 做什么；这是标注关键文件更新的 headline affordance。
88. 每个 annotation 默认锚定 AFTER-side line numbers，用 side 设为 before 指向 removed lines；每文件保留少量 high-signal notes，不要逐行。
89. 当多个 key files 各自需要 substantial diff 时，用 rich-text heading block 引入，markdown 为 ## Key changes，然后把这些 diff blocks 放入可复用 tabs block 且 horizontal orientation，默认省略 orientation，使选中文件的 split diff 获得 full document width；让 heading 标记该 section，不要同时给 tabs block 设置 title；每个 tab label 保持 file path 或短 basename 加 directory hint。
90. 渲染器 wide document layout 是有意 allowlist：diff、annotated-code、vertical tabs、和包含 diff-like children 的 tabs 会比 prose 更宽；不要仅仅为了变宽而把 API endpoints、OpenAPI specs、data models、JSON explorers、wireframes、question forms、custom HTML 放入 tabs。
91. 如果 recap 结尾有多个 supporting diff，尾部 diff appendix 应是 own ## Key changes heading 下的一个 horizontal tabs block，而不是多个单独 diff blocks 堆叠。
92. Brand-new file 或没有 meaningful before 的 substantial added block 用 annotated-code 而不是 one-sided split diff；携带真实新代码和 filename / language，并在重要行锚定少量 high-signal notes，让审查者读新代码做什么，而不是为代码而代码；对 removed lines 仍有意义的 true before/after hunks 保留 split diff，并按 diff 的分组方式把多个 annotated walkthroughs 放进 horizontal tabs block。
93. Files added / removed / renamed 用 file-tree，每个 entry 带 change flag，如 added、removed、modified、renamed，和短 note；仅当 snippet 能告诉审查者 path 没有的信息时才附加 snippet。
94. Rendered UI / interaction change 在审查者读代码前，用一个或多个 wireframes 展示 visible UI delta；比较能澄清变更时用 Before/After wireframes，否则用 after-only 或短 state/flow sequence。
95. 使用真实 UI surfaces：popover 变更就展示带 title row、top-right actions、options/fields、tabs、selected/disabled states、people/lists/rows 的 popover，以及锚定正确 trigger 的 opened prompt/menu；如果新增 route，展示 route body 和 diff 实现时的 unavailable/empty state；如果权限变化，展示 managers 能做什么以及 viewers/non-managers 看到什么；保持 body lean：wireframe 承载 UI story，file tree 和 diff blocks 承载 implementation evidence。
96. Architecture or data-flow shift 用 diagram，使用 data.html / data.css 作为 two-panel before/after、layered 或 swimlane layout，或用 mermaid 做 quick graph；使用二维布局；不要把结构变化简化为 left-to-right chain；不要把 diagram 当成 rendered UI controls 的替代，UI 变更需要 wireframe blocks。
97. 编写 diagram HTML/CSS 时使用渲染器拥有的 .diagram-* primitives，如 .diagram-panel、.diagram-node、.diagram-pill、[data-rough] 等，和 references/wireframe.md 定义的同一 --wf-* theme tokens；绝不要 font-family、hex、rgb/hsl literals 或一次性 dark/light palettes。
98. 有意选择 outer frame：recap diagrams 通常 standalone 时受益于 frame 设为 show，但当 columns、tabs、card 或 diagram 自己的 panels 已提供边界时用 frame 设为 hide。
99. Outcome-first narrative 用 rich-text 写 what changed and why prose：diff 服务的目标、其中可见的关键决策、审查者应权衡的风险；这是模型唯一自由写作的地方。
100. 在写任何结构化 plan 内容前，fetch/read block catalog。
101. 在 hosted 或 self-hosted mode，调用 Plan MCP connector，plan 或 legacy agent-native-plans，上的 get-plan-blocks。
102. 如果 lazy-loading client 中尚无 Plan tools，先通过宿主的 tool discovery surface，可用时 tool_search，search/load。
103. 在 local-files mode，或 skill 作为纯文本安装且 discovery 后 no MCP tools registered 时，运行 npx @agent-native/core@latest plan blocks --out plan-blocks.md 并先读取该文件。
104. 该 CLI command 调用 public no-auth get-plan-blocks route 且不发送 plan/recap content。
105. 如果 network access 不可用，使用 bundled references 并用 plan local check 验证；仅当 hosted Plan UI 可达或 local Plan app 已运行时运行 plan local serve。
106. 使用 get-plan-blocks 默认 format 为 reference 获取 compact table：每个 block 的 runtime type、确切 MDX <Tag>、placement、key data fields。
107. 当需要 exact field types、enums、nesting，如 Diff.annotations、Endpoint.params[].in、DataModel.entities[].fields[] 时，调用 get-plan-blocks 且 format 为 schema。
108. 根据该调用返回的 tags 和 schemas 编写 recap source；有效 block-level tags 是 get-plan-blocks 列出的集合；任何其他 capitalized tag at block level 会 import 时被拒，报 Unknown plan block 或 did you mean。
109. rich-text/markdown prose 内的小写 HTML tags，如 <div>、<span>、<code>、<br> 等，总是可以；只有 capitalized component-style block tags 会被校验。
110. 每个结构化 block 必须有 REQUIRED id，whole plan 唯一，以及 shared optional summary / editable envelope。
111. 普通 top-level Markdown prose 自动 import 为 rich-text；仅当 prose 需要 explicit metadata 或 preserved referenced block id 时使用 <RichText id=...>。
112. 每个 capitalized block component 必须 self-closing，如 <Diagram ... />，或在 children 外显式关闭，如 <RichText ...>...</RichText>；绝不要在一个段落里留下裸 opening tag 如 <RichText ...>，MDX 会视作 unclosed JSX 且 import 失败。
113. Code-bearing blocks，Code、AnnotatedCode、Diff，对 whitespace 敏感；优先使用 get-plan-blocks examples / source exporter 的确切 MDX 形式，其中 multiline code 编码为 JSON string attributes；static template literals 仅当 static strings 且无 ${...} interpolation 时可接受。
114. Endpoint：prose description 是 MDX children，即 tags 之间的 body，不是 attribute；WebSocket upgrade 使用 method=GET；每个 request/response example 是 JSON string，renderer 解析进 JSON explorer，保持单个 parseable JSON value。
115. TabsBlock：整个 tabs array，包括 nested child blocks，是一个 JSON tabs={…} prop；没有 nested <Tab> element。
116. WireframeBlock：其 body 是 single <Screen surface ... html=… /> subtree，nested MDX，不是 flat prop；html 必须是 single-quoted string 或 static template literal，绝不能是 dynamic html={someVar} expression。
117. Diagram：整个 payload 是一个 data={{ html?, css?, nodes?, edges?, … }} attribute，且要求 html 或至少一个 node；Mermaid 是独立 block，source text，不是 Diagram prop。
118. Recap 重心是 before/after comparison。
119. Document-body comparisons 用两个 primitives：columns 和 diff。
120. columns 是 side-by-side container，用于 structured comparisons；使用两列 labeled Before 和 After，每列持有一个 block，常用 data-model、api-endpoint、rich-text，让审查者一眼读旧形状与新形状；适合 schema went from X to Y 或 endpoint contract changed like this；不要仅为了压缩或分组 list of API endpoints 使用 columns。
121. diff 用于 code；渲染 literal removed/added lines；用于 actual hunks；recap code review 默认 split mode；reserve unified for genuinely narrow standalone hunks where side-by-side would hide code；key-file diff groups 用 horizontal tabs。
122. UI diffs 用 wireframes 作为 visual comparison primitive；比较能澄清时用 before/after，否则 after-only 或 state sequence。
123. 视觉头条必须在任何抽象解释前展示 exact placement、realistic chrome、adequate padding。
124. 当 diff 增加 flow 时，不要停在第一个可见 affordance；展示 entry point、opened surface、resulting state/page，让审查者追踪实际 user path。
125. references/wireframe.md 决定 before/after layout 选择；columns renderer 保持 narrow surfaces side by side，并自动将 wide desktop/browser frames 垂直堆叠；绝不要在 custom-html 中手工构建 side-by-side wireframe layout。
126. 对 document-body comparisons，没有其他 multi-column primitive；columns 加 diff 是全部 comparison vocabulary。
127. 不要手工在 custom-html 中构建 side-by-side layouts。
128. 当 columns 存在时，不要把两个 data-model blocks 垂直堆叠并称之为 comparison。
129. Structured blocks 只有从 actual changed lines 派生时才是 true by construction。
130. diff、data-model、api-endpoint、file-tree blocks 必须从 real diff 机械构建：real paths、real fields、real method/path、real before/after text；绝不 inferred、rounded、invented。
131. 模型只写 prose：why、narrative、risk read。
132. 自信但错误的 recap 在 review context 危险，因为信任 summary 的审查者可能跳过 summary 搞错的那一行。
133. 当 diff 不包含某事实时，省略而不是猜；任何模型 inferred，而非 extracted 的内容在 prose 中标记为 inferred。
134. Gate visibility：private repo 的 recaps 是 org/login-gated；把 plan visibility 设为 owning org 或 login，绝不 auto-public；recap 可能暴露未发布 schema、内部 endpoints、architecture，因此像对待其总结的 source 一样对待。
135. 任何链接到 recap 的 PR comment 或 handoff 必须说明：private-repo recaps 如果链接未加载，需要 sign in with access to owning org。
136. Never transcribe secrets：diff 可能含 API keys、tokens、webhook URLs、signing secrets、.env values 或 credential-looking literals。
137. 不要把任何这些复制进 diff、file-tree snippet、api-endpoint 或 prose block；redact 它们为 sk-•••、<redacted>；这映射 repo 的 hardcoded-secret rule：任何 block、caption、note 中只用明显 fake placeholders，绝不用真实值。
138. Hosted mode 中，recap 是真实可编辑 plan，review loop 与 forward plans 相同：reviewer 可 annotate 任意 block，coding agent 读取 get-plan-feedback 把修复驱动回代码，即 annotation 到 agent 到 diff。
139. Reviewer annotate block 后，调用 get-plan-feedback 读取 structured feedback，然后要么用 create-visual-recap 更新 recap，传 existing planId 以原地替换，要么用 update-visual-plan 应用 targeted changes。
140. Local-files privacy mode 中，不要调用这些 hosted tools；从 chat 或 local files 读 review notes，直接编辑 <plan-dir>/*.mdx，并重新运行 plan local check、serve 或 verify for <plan-dir>。
141. 唯一尚未自动的是 PR-comment-triggered re-runs：GitHub Action 为每个 PR 创建 initial recap，但尚未在新 review feedback 发到 GitHub 时自动 re-run，这是 remaining fast-follow。
142. visual-plan 是 canonical command 和共享 Wireframe & Canvas 与 Document Quality cores 的来源；recap 反向遵循相同 block discipline。
143. comment anchors：recap comments 使用与 forward plans 相同的 anchor rules；参见 visual-plan skill 的 Interpreting comment anchors，了解 coordinate frames、wireframe node ids、text-quote resolution、detached threads、routing via resolutionTarget、two-axis consumed/resolved state。
144. security：data scoping、secret handling、hardcoded-secret rule，recap 的 redaction 和 visibility gating 映射它。
145. sharing：为持有 recap 的 plan 设置 org/login-gated visibility。

适用边界 · 注意事项

• 小、单文件或显而易见的 diff 不要用 visual-recap；它带来 review overhead，直接看 plain diff 更快。
• 不要用 inline Markdown 散文、ASCII 草图、表格、围栏 wireframe 或 here's the recap 摘要替代发布的 Agent-Native Plan；若 Plan MCP 工具不可用且无法重连，不要临时内联。
• 用户要求 no hosted Plan database writes、完全本地/离线/私有，或 AGENT_NATIVE_PLANS_MODE=local-files 时，不要走 hosted 发布流程，改用 local-files privacy mode。