visual-plan

Agent-Native Plans

Agent-Native Plans 是一种面向编码 Agent 的结构化可视化规划模式。像平常一样用 Markdown 编写计划，但将其做成便于浏览的文档，并混合可编辑内容块：内嵌图表、代码片段、待解决问题，以及可选的顶部可视化评审区域（线框画布、实时原型，或通过标签页同时展示二者）。架构和后端计划仅采用文档形式；UI 和产品计划则从顶部画布／原型开始（此规则由 Visual Surface Choice 部分负责）。

/visual-plan 是打包好的命令，也是主要入口点。根据任务选择评审模式：如果工作主要围绕产品 UI，且评审应从界面开始，则选择 UI-first；如果评审应从可运行的实时原型开始，则选择 prototype-first；如果评审需要高保真品牌化界面，则选择 design-first；如果用户明确希望在规划前先填写问卷，则选择 visual-intake。如果已有 Codex、Claude Code、Markdown 或粘贴的计划，/visual-plan 会以该计划为起点，并据此构建评审界面，而不是从头开始。

适用场景

只要计划用可供评审的内容来呈现，比写成聊天段落更合适，就应创建或调整可视化计划。这既包括较小的工作，例如包含多种状态的单个 UI 界面、小型工作流、产品改动前后对比，或需要达成共识的组件／API／数据结构决策；也包括较大的多文件、含糊、耗时长、有风险或以 UI 为主的工作。当架构／数据流／UI 方向／选项／待解决问题适合用内嵌图表或结构化内容块呈现时，当用户需要在你开始实现前对方向提出意见时，或当现有文本计划需要更丰富的评审界面时，都可以使用它。

计划规范

• 审慎把关。 可视化计划提供了更丰富的评审界面，不只是大型项目的工具。只要用户需要在编写代码前查看、比较、评论或批准某个方向，即使只是适度调整 UI、状态或工作流，也应使用它。对于真正简单明确的工作——例如拼写错误、单行修复、需求明确的单个函数，或差异能用一句话描述的改动——则跳过计划，直接修改。切勿用无关内容填充计划，也切勿提交只有一个步骤的计划。
• 先调研，再起草。 先阅读实际文件、操作、架构和模式；使用真实的文件名、符号和数据结构，而不是凭空编造。提出端点前先检查现有的 actions/，并优先使用命名的客户端辅助函数，而不是直接调用 fetch。将大范围探索交给子 Agent。优先复用：对于每个步骤，先说明会复用哪些现有操作、架构、组件和辅助函数，再说明会新增什么，让计划阐明真正新增的内容，而不是重新描述已有内容。
• 先确定难以逆转的选择。 对于非简单的后端、数据或 API 工作，先概述功能的目标方向，再指出一旦数据或调用方依赖它们，就很难撤销的选择——传输格式、公开 ID、数据模型结构、身份验证和所有权边界——并在计划中妥善处理这些问题，即使大部分功能会稍后交付。然后将范围缩小到能验证方案、又不会堵死后续发展的最小首期版本，并明确说明纳入和明确延期的内容。
• 让示例保持合适的抽象层级。 当用户提出的是宽泛的框架、产品或运营模式变更时，不要把它缩减为用户提到的第一个具体示例、提供方或同步路径。将核心抽象与用于说明动机的示例以及应用／提供方适配器区分开。使用示例让计划更易理解，但除非示例就是全部需求范围，否则应将其标明为示例。
• 发布独立完整的计划。 如果用户粘贴、引用或已经有 Codex / Claude Code / Markdown 计划，应将其作为源材料，但将发布的计划重写为清晰、独立完整的提案。保留源计划中有用的意图和代码库事实，将推断出的视觉内容标明为推断，并避免使用诸如“保留先前计划”“不要丢弃旧想法”“与先前版本不同”或“本次修订更改了……”之类的表述。即使读者从未看过聊天记录或先前草稿，也应能理解计划。
• 开篇就讲具体内容。 如果计划要分享给聊天以外的人，或者概念较为抽象，应在靠前位置、模式表格、架构或路线图之前，先给出一个具体的产品示例。对于支持 UI 的概念，通常应在画布顶部呈现应用状态，用产品语言展示真实的用户工作流。不要依赖只有在对话中才有意义的说法，也不要将计划描述为“不是旧想法”；应直接说明正向方案。
• 规划阶段只读。 在制定或评审计划时不得修改源文件。只有用户批准方向后，才能开始编辑。
• 澄清还是假设。 不要询问如何实现；应在计划中探索并呈现方案和选项。只有当某项歧义会改变设计，且无法从代码中解决时，才提出澄清问题；使用宿主 Agent 的常规提问流程，并在定稿前一次性提出 2-4 个影响较大的问题。不要将 create-visual-questions 用于常规澄清或预检；只有用户明确要求视觉需求问卷时，才将其用于视觉需求收集模式。其他情况下，应明确说明假设并继续推进，并将所有未解决的问题放在计划底部唯一的 question-form「待解决问题」区块中。对于复杂计划，在交接前最后检查一次待解决问题：如果某项决策会影响架构、范围、UX、数据结构或发布流程，要么在计划中给出决策及理由，要么将其列入底部表单，并提供建议的默认选项。
• 计划就是审批关卡。 呈现计划后，在编写代码前请用户审阅并批准，同时说明工作会涉及哪些文件／区域。呈现计划并请求批准就是审批步骤；不要再单独询问“这样看起来可以吗？”。
• 以文档为准，而不是以聊天为准。 如果范围发生变化，应使用 update-visual-plan 更新计划，而不是只在聊天中改变方向，并确保更新后的文档独立完整。不要在计划中将更新描述为对早期草稿的纠正。在执行重大步骤前，重新阅读已批准的计划。

创建结构化的 Agent 原生计划 — 绝不以内联形式提供

交付内容始终必须是结构化的 Agent 原生计划，而不是仅限聊天的计划。 托管的 Plan MCP 连接器（plan 服务，或旧版 agent-native-plans）是默认的协作和评论界面；不能以它属于外部依赖或租用层为由拒绝采用这种规划模式。计划是可移植的源文件（plan.mdx、可选的 canvas.mdx / prototype.mdx、JSON 和 HTML 导出文件），对所有权敏感的工作流可以使用本地文件模式，或自托管／自定义 Plan 应用 URL，而不必放弃该技能的审核规范。不要因为默认界面是托管的，就建议用户跳过 /visual-plan；应根据用户对所有权、隐私、共享和品牌的需求，选择合适的 Plan 模式。

默认情况下，通过 Plan MCP 连接器创建计划，绝不将计划以聊天内联内容的形式交付——不得使用 Markdown 文本、ASCII 草图、表格或带围栏的线框图。如果看不到 plan（或旧版 agent-native-plans）工具，请先通过主机的 tool_search 查找；如果仍然找不到，请停止操作，并提供针对该客户端的重新连接步骤，不要临时改用内联计划。在发布之前，或每当出现连接器或身份验证错误时，请阅读此技能目录中的 references/connection.md——它是关于绝不以内联形式提供计划、发现连接器以及各客户端重新连接步骤的唯一准确信息来源。本地文件隐私模式（在工具指南之后）是例外。

核心工作流

本节介绍默认的托管 Plan MCP 工作流。如果设置了 AGENT_NATIVE_PLANS_MODE=local-files，或用户要求完全使用本地文件／不通过托管 Plan 写入，请改用本地文件隐私模式；此处仅保留代码研究和计划撰写指南。

1. 遵循宿主 Agent 的常规规划流程：检查代码库，在有助于全面探索时委派任务，收集所需信息，并在生成计划前按需提出原生澄清问题。如果源计划已存在，请从用户粘贴的内容、引用的文件或近期可见的 Agent 上下文中获取其准确文本；不要编造源文本。
2. 调用 get-plan-blocks 获取权威区块目录——不要凭记忆编写标签。然后调用与模式匹配的创建工具：文档优先的计划（架构、后端、数据、重构、API）使用 create-visual-plan，UI 优先的计划使用 create-ui-plan，原型优先的计划使用 create-prototype-plan，设计优先的计划使用 create-plan-design，仅在用户明确要求视觉信息收集问卷时使用 create-visual-questions。如果源计划已存在，请将其作为 planText 传入，在生成独立计划文档时保留原计划有用的意图，而不是写成修订备忘录。
3. 对于 UI/产品计划，先构建顶部画布，放入主要线框图和带注释的状态，然后使用原生区块撰写文档（参见 references/canvas.md 和 references/document-quality.md）。对于具有面向用户影响的广泛产品架构计划，请在抽象架构或模式表之前，添加一个具体的“在应用中呈现的效果”视觉内容。文档应尽量接近 Agent 通常会输出的独立 Markdown 计划。如果提供了现有计划，应保留正确的事实和决策，不要提及先前的草稿，也不要解释此版本有何不同。对于非视觉计划，跳过顶部视觉区域（下文“视觉区域选择”对此规则另有规定），并将 diagram、data-model、api-endpoint、diff、file-tree、code 和 annotated-code 区块直接放在相关说明旁边。 宽版文档布局由渲染器控制，且有意采用白名单机制：只有字面意义上的代码审查区域（diff、annotated-code），以及采用纵向布局或包含类似 diff 子项的 tabs 区块，才会突破正文宽度。 除非区块自身的渲染器另有规定，否则应将 api-endpoint、openapi-spec、data-model、json-explorer、wireframe、问题和 custom-html 区块放在正常文档流中。
4. 展示返回的 Plans 链接或内嵌 MCP App，并请用户审阅。聊天中始终附上实际 URL，这样在 CLI 或其他纯文本宿主中，用户接下来只需点击即可。如果宿主提供嵌入式浏览器/预览面板，且工具可以在其中打开任意 URL，请自动打开返回的计划 URL，方便审阅——这只是便利功能和冒烟测试，绝不能成为唯一的交付方式或访问途径。计划应能在本地 Agent 和本地浏览器会话中开箱即用；如果已登录的嵌入式浏览器无法读取匿名访问或工具检查能够读取的本地计划，应修复应用/操作的归属或访问路径，而不是针对单个计划打补丁。对于高风险计划（架构、后端、数据、多文件或高风险计划），还应在用户阅读期间启动交付前自审流程，而不是等自审结束后再交付。
5. 对于托管计划，在编辑前、审阅后、任何长时间停顿后，以及最终回复前，都要调用 get-plan-feedback。以 anchorDetails、解析器意图、近期审阅事件以及浏览器交接时的聚焦截图为准，准确确定有哪些更改以及每条评论具体指向什么。
6. 对于托管计划，使用 update-visual-plan 应用更改，并优先使用定向的 contentPatches。 将顶层 content 负载视为完整替换，而不是合并；不要发送不完整的 content 对象来添加画布或单个区块。如果不可避免地要进行完整替换或使用 replace-blocks，请在写入前立即调用 get-visual-plan，传入其 plan.updatedAt 作为 expectedUpdatedAt，并保留所有现有区块和视觉区域。切勿复用之前读取或反馈负载中的版本。对于便于纳入源代码管理的编辑，请对 MDX 文件使用细粒度的 patch-visual-plan-source 操作，而不是重新生成计划；replace-file 同样具有破坏性，必须使用最新的 expectedUpdatedAt 进行防护。
7. 每次写入托管计划后，都要再次调用 get-visual-plan，并将持久化文本、区块 ID/数量、画布框架和原型与预期结果进行比较。成功的变更响应并不能证明无关内容都已保留。如果编辑处理了面向 Agent 的反馈，只有在完成此验证后，才调用 resolve-plan-comment 处理该讨论串，并调用 consume-plan-feedback 处理其评论；两者都要执行，确保已处理的反馈既不会继续显示为未解决，也不会作为待办事项再次返回。
8. 对于托管计划，仅在用户需要可分享的凭证或需要将产物检入代码库时，才使用 export-visual-plan。

交接前自我审查

这项对抗式自我审查是可选的，并非默认步骤：仅在高风险计划中执行，例如不可逆迁移、安全敏感工作，或用户明确要求更严格审查时；其他情况跳过。它大致会使计划生成成本翻倍，因此对于小型计划、纯 UI 计划、只涉及一个决策的计划或普通计划，默认应跳过，而非执行。执行时，应保持审查成本低且不阻塞流程：

• 先展示计划，再并行审查。 发布链接，让用户开始阅读，然后并行开展审查——绝不要让用户等待审查完成。
• 审查书面计划；不要重新调研。 评议计划文本及其自身的内容块。起草时已完成事实核实，因此审查应检查产出，而不是重新探索代码库。
• 安排一位持怀疑态度的审查者，唯一职责是找出薄弱、缺失或错误之处，而不是称赞计划。请其重点检查：隐含作出或完全未作出的难以撤销的决策（线格式、公有 ID、数据模型结构、身份验证、所有权）；未锚定到真实文件或符号的步骤；本应明确选定一种方案却列出多个选项的情况；明显遗漏的决策（“X 发生时会怎样？”、“为什么不选 Y？”）；以及填充内容或单步凑数内容。
• 修复还是询问。 使用 update-visual-plan 的 contentPatches 自行修复明确的问题，例如含糊的非目标、缺乏依据的说法、明显遗漏的决策。真正需要判断的事项则交还用户：将其添加到末尾 question-form 的“开放问题”区块，或汇总到常规的 ask-user-question 流程中。不要擅自决定。
• 不要在用户阅读时让他们措手不及。 对于大型计划，应在编辑器加载前应用补丁；否则，简要说明自我审查正在进行，让用户知道计划可能会发生变化。下次回复时，概述审查改动的内容，以及发现的、需要用户决定的事项。

视觉呈现方式的选择

在创建计划之前或阅读源计划之后，选择呈现方式。默认情况下不要添加视觉装饰：

对于 UI/产品计划，顶部画布通常是主要的审阅区域。应将第一个有意义的线框放在那里，而不是埋在文档正文块中。当不同状态很重要时，使用多个画布画板，例如默认视图、溢出菜单或弹出框、侧边面板、加载状态或错误状态。将简短注释放在画框旁，并使用 targetId 和 placement；实现细节、权衡、文件映射、数据契约、风险和验证内容则放在画布下方的文档正文中。

当用户要求流程、故事板、旅程、线框、画布或“展示一下是什么样子”时，应将其视为画布优先的请求。每个用户可见状态对应一个画板，只连接相邻状态之间的转换，并使用简短的画布注释记录产品说明。不要仅仅因为 HTML 图表写起来更快，就用文档正文中的 diagram 块替代用户要求的故事板；图表应放在画布下方，用于说明后端机制、架构或数据流。

将产品线框与说明性／元图表分开。首先展示纯粹的界面，让它看起来像正在讨论的应用状态；不要在 UI 中嵌入说明性文字或架构备注。箭头、标签、契约、数据流和模式说明应放在单独的注释、单独的画布图表或文档正文中。

如果计划涉及现有应用，绘制之前先检查当前外壳和组件。第一个画板应与真实应用的界面密度一致：现有侧边栏、工具栏位置、溢出菜单、应用外框以及框架 Agent 外框都应放在实际位置。将次要界面建模为独立状态，例如右上角溢出弹出框、抽屉、面板、加载状态或单独的 AgentSidebar，而不是凭空设计一个常驻检查器，也不要把框架外框并入产品 UI。

• 不使用可视化画布：适用于纯架构、纯后端、数据迁移、纯文案或其他非视觉方案。不要使用顶部画布展示架构图、依赖关系图、文件规划、API 契约或仅限数据流的评审。应使用内容扎实的文档，仅在需要直观说明关系时插入局部图示；通常每项建议或决策配一张空间关系图。除非关系确实是顺序式的，否则优先使用分组区域、分层、象限、矩阵或前后对比面板，而不是单轴流程链。
• 仅使用画布：适用于单个静态屏幕、前后对比、组件状态、小型弹出层，或无需点击交互的视觉方向。将线框图放入 content.canvas，省略 content.prototype。
• 画布 + 原型：适用于多步骤 UI 流程、引导流程、向导、评审／审批流程、导航更改，或任何评审者需要实际操作的行为。将静态线框图放入 content.canvas，添加与其对应的功能原型到 content.prototype，并通过顶部的可视化选项卡在两者间切换。当两种呈现形式都存在时，默认打开 Wireframes 选项卡；原型仍可作为交互式后续视图使用。
• 默认使用线框图。 简洁、精简的 UI、高 UX 标准，或提及 Linear/Vercel，描述的是内容和信息密度标准；这并不意味着需要高保真设计模式。除非用户明确要求品牌化、像素级精确、接近生产环境或完整视觉设计，否则使用渲染器生成的线框图。这样可以确保画布中的每个屏幕都便于检查，且完整内容清晰可见。
• 优先使用原型：当用户要求操作 UI，或交互是主要问题时。使用 create-prototype-plan，在适用时仍保留静态稿。

对于画布 + 原型混合方案，复用标签和 ID；除非明确要求仅更新单一呈现形式，否则应同时更新两种呈现形式。进行输出审计时，请阅读 observability 技能：支持单应用和工作区表格，保留应用预览，并确保审计、综合分析、差异对比和应用更改均需管理员授权。

即使请求中也提到“样稿”，也应将“更高保真度”“像素级精确”“精致样稿”“接近生产环境”“真实设计”和“不是草图／线框图”视为优先设计的表述。新建方案时，使用 create-plan-design。对于现有方案，保留相同的方案 ID，并调用 update-visual-plan，在同一次更新中使用 renderMode: "design" 的 set-visual-render-mode 补丁，并提供升级后的屏幕 HTML/CSS。结果应基于真实应用外壳、设计令牌、排版、间距和状态，并添加稳定的 data-design-id 目标。将作用域样式放在每个屏幕的 css 字段中，绝不要放入 <style> 标签。查看器本地的 Clean 切换只会更改一个浏览器的线框图偏好，并不会提升保真度。不要为了处理保真度后续需求而创建重复方案。

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

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

Canvas — 阅读 references/canvas.md

Canvas 是静态 UI 模拟稿的唯一事实来源：surface 锁定每个画板的占用空间，混合 surface 会按泳道排布， 标注是通过 targetId/placement 锚定的纯文本设计备注， 编辑则使用精确的 contentPatches。在编写或编辑任何 Canvas、画板或标注之前，请先阅读此技能目录中的 references/canvas.md——它是 Canvas/画板机制的唯一事实来源。 请勿凭记忆编写 Canvas 布局。 Canvas 画板使用与文档正文 WireframeBlock 屏幕相同的 HTML 线框路径：使用语义化 HTML 片段编写 <Screen surface="..." html={...} />。请勿在 Canvas 的 <Screen> 标签中创建新的套件树子元素，例如 <FrameScreen>、<Card>、<Row> 或 <Btn>；这些是旧计划的兼容标记，会生成脆弱的 Canvas 布局。

文档质量 — 阅读 references/document-quality.md

这份文档是严肃的技术计划，而非营销材料：以成果为先、以正文为主、内容自足、使用恰当的原生区块，将未决问题集中放在文末的 question-form 中，并在交接前进行视觉检查。在编写计划文档之前，请先阅读此技能目录中的 references/document-quality.md——它是文档质量标准的唯一事实来源。 请勿凭记忆编写文档。

优秀与糟糕示例 — 阅读 references/exemplar.md

如需查看标准示例——优秀的 UI 优先计划和 /visual-plan，以及应避免的反模式——请在编写计划之前阅读此技能目录中的 references/exemplar.md。

编写约束

请将以下内容视为数据完整性检查，而非可选的润色：

• content 是完整替换内容。请传入 content，或传入模式对应的便捷数组（screens/transitions 或 states/components），不可同时传入。创建操作会拒绝混合来源，避免第二个负载悄悄丢弃 CSS、框架或文档区块。
• 设计屏幕的作用域 css 是产物的一部分。请在原型屏幕及其对应的 Canvas 画板中都保留它，并使用渲染器自有的 --wf-* 令牌，确保颜色和排版具有可移植性。
• 富文本 data.markdown 必须包含实际的运行时换行。请勿将包含字面量 \n 转义文本的单行 Markdown 值交给计划，否则整个区段会被渲染成一个标题。在代码示例中使用转义换行没问题，前提是周围的 Markdown 仍包含实际换行。
• Canvas 画板不会滚动。请让线框 HTML 按自然流排列；当屏幕超出 surface 预设尺寸时，请设置更大的画板 height；保留 surface 宽度，并在交接前以默认缩放比例检查底部边缘。
• 每次托管写入后，请重新读取结构化内容，并检查实时 Plan surface。有效的 JSON 负载并不能证明 CSS 已加载，也不能证明 Markdown 已按预期渲染为标题、段落和列表结构。

工具指南

• create-visual-plan：每个 Agent 任务/运行启动一个结构化视觉计划，或通过传入 planText 导入现有文本计划；content 可以不包含任何视觉界面、仅包含画布，或同时包含画布和原型。
• create-ui-plan：当工作主要围绕产品 UI 时，启动一个 UI 优先的计划。
• create-prototype-plan：启动一个原型优先的计划，并提供功能完备的顶部审查界面。如果交互本身也必须达到高保真，请将每个屏幕的 renderMode 设为 design，并通过 css 传入限定范围的样式；否则，请使用 create-plan-design 进行设计优先的审查。
• create-plan-design：启动一个全保真、带品牌风格的 Design 选项卡计划，可选配匹配的 Prototype 选项卡。
• convert-visual-plan-to-prototype：将现有 HTML 线框画布转换为原型计划。
• create-visual-questions：仅当用户明确要求视觉需求问卷时使用，不要将其用作 /visual-plan 的预检。
• update-visual-plan：使用有针对性的 contentPatches 修订内容、状态或评论（参见核心工作流步骤 6-7）。将现有计划提升为高保真时，请使用 set-visual-render-mode 并设置 renderMode: "design"，同时提供精心设计的屏幕 HTML/CSS；仅设置渲染模式只会移除草图样式。replace-blocks 和完整的 content 替换都需要从最新的 get-visual-plan 调用中获取 expectedUpdatedAt。
• read-visual-plan-source：以 plan.mdx、可选的 canvas.mdx、可选的 .plan-state.json 和 JSON 格式读取规范化后的计划。
• patch-visual-plan-source：通过稳定的区块、画板、注释、组件或线框节点 ID 应用细粒度 MDX AST 补丁。优先使用这些定向操作；replace-file 需要从最新的 get-visual-plan 调用中获取 expectedUpdatedAt。
• import-visual-plan-source：从 MDX 文件夹创建或替换计划。
• get-visual-plan：读取当前结构化计划、导出的 HTML、注释和 plan.updatedAt；它还会返回用于源文件工作流的 MDX 文件夹。进行破坏性写入前应立即重新读取，以获取并发保护令牌；每次写入后也应重新读取，以验证持久化状态。
• get-plan-feedback：读取尚未处理的人工反馈。请经常使用；它会返回分组讨论串、精确的锚点详情、预期处理者和近期审查事件负载，以便 Agent 只处理分配给自己的评论。
• get-plan-blocks：创作前解析区块标签——不要记忆标签；先调用此工具，从实时区块注册表获取权威的标签名称、必填字段和属性形状。
• export-visual-plan：导出 HTML、Markdown 回退版本、结构化 JSON 和用于提交到代码仓库的 MDX 文件。

当用户批评计划的外观或结构时，应修复渲染器或此技能——绝不要手动编辑已存储的计划。将反馈转化为更完善的指导。

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

当用户要求不写入托管 Plan 数据库——不写入数据库、不通过 Plan MCP 发布、完全在本地/离线/私密地规划、使用由代码仓库管理且纳入版本控制的产物，或设置了 AGENT_NATIVE_PLANS_MODE=local-files——除仅用于查询架构的 get-plan-blocks 目录查找外，不要调用任何托管 Plan 工具。编写本地 MDX 文件夹，并使用 plan local check / plan local serve / plan local verify 进行预览。 使用本地文件模式前，请阅读此技能目录中的 references/local-files.md——它是完整约定（目录查找、MDX 文件夹布局、本地桥接命令，以及禁止调用的托管工具）的唯一事实来源。仅沿用核心工作流中的代码研究和计划编写指导；所有托管操作都由本地桥接替代。

解读评论锚点

本节适用于使用 get-plan-feedback / update-visual-plan 的托管方案。在本地文件模式下，不要调用托管反馈或更新工具；应直接解读文件或聊天反馈，编辑 MDX 文件，重新运行本地桥接检查/服务/验证命令，并报告新的本地 URL。

get-plan-feedback 会返回丰富的锚点信息——在处理任何评论前，请先阅读。

• 坐标系。 targetX/targetY 是相对于 targetSelector/targetKind 所指元素的百分比。单独的 x/y 是整个计划文档的百分比。canvasX/canvasY 是设计画布上的原始画板世界坐标像素（如有，会提供画板尺寸）。
• 线框图图钉。 线框图上的锚点包含 targetNodeId 和 targetNodePath（例如 card > list > listItem "Acme Inc"），用于标识确切的套件节点。将 targetNodeId 直接用于线框图节点补丁操作；将设计画板中的 data-design-id 值用于 update-design-element-style。优先使用节点 ID/路径，而非原始坐标；仅当不存在节点 ID 时，才使用坐标和聚焦截图（红圈标记确切位置）作为后备。
• 文本引文。 使用 contextBefore/contextAfter，在当前正文中定位 textQuote，以消除歧义。如果 ambiguous: true，请询问用户——不要猜测指的是哪一处。
• 脱离上下文的评论。 对于引用文本已不存在的评论线程，get-plan-feedback 会将其标记为 detached（在 detachedThreads 中）。请根据改写后的内容协调处理这些评论——绝不要悄悄丢弃。
• 路由。 resolutionTarget 是唯一的路由信号：处理发给 agent 的评论，将 human 仅作为上下文。@mentions 是需要通知的人，绝不是路由信号。
• 双轴状态。 将每条已读取的评论标记为已消费（在 update-visual-plan 中设置 consumedCommentIds）。仅对你实际处理的、发给 Agent 的评论设置 status=resolved；发给 human 的评论应保持未关闭状态。编辑处理反馈后，先重新读取已持久化的计划并确认所请求的更改。只有在此之后，才调用 resolve-plan-comment 处理已回复的线程，并调用 consume-plan-feedback 处理其评论；绝不要只沿一个轴标记已处理的反馈。

可见性与共享

使用 set-resource-visibility 更改谁可以查看计划（例如公开、登录后可见或限定组织范围）。使用 share-resource 按邮箱或角色向特定用户或角色授予访问权限。共享涉及尚未发布或私密工作的计划前，请先设置可见性——默认采用满足审核需求的最窄范围。

设置与身份验证

使用 Plans 有两种方式。

编码 Agent（CLI）。 使用 Agent-Native CLI 安装一次即可。该命令会安装 Plans 技能、注册托管的 Plans MCP 连接器，并在同一步骤中为选定的本地客户端运行身份验证和设置（设置时需一次性在浏览器中登录，这是预期行为），因此在该客户端中首次调用工具时不会遇到 OAuth 阻碍：

npx @agent-native/core@latest skills add visual-plans

之后，/visual-plan、/visual-recap 和 /visualize-repo 就是已安装的斜杠命令。如果只需要其中一个命令，请改用 skills add visual-plan、skills add visual-recap 或 skills add visualize-repo。其他规划模式（create-ui-plan、create-prototype-plan、create-plan-design、create-visual-questions）是可从 /visual-plan 访问的 MCP 工具，不是独立的斜杠命令。添加 --no-connect 可在不进行身份验证的情况下注册连接器；准备就绪后，再运行 npx @agent-native/core@latest connect https://plan.agent-native.com --client all ，也可以选择范围更小的 --client。身份验证和 MCP 工具加载按客户端配置／会话进行。

浏览器（与您共享的人）。 打开 Plans 编辑器，无需注册即可创建和编辑——您可以访客身份使用。只有在需要保存或共享时才登录；登录后，您以访客身份创建的计划会归入您的账户。

共享和评论需要账户：任何人都可以通过链接查看公开／已共享的计划，但要对此类计划发表评论则需要 agent-native 账户。

如需完全离线且无需账户的使用方式，请在本地运行 Plans 应用，并将计划以 MDX 格式同步到您的代码仓库。此本地模式是单独的高级用法，并非默认的托管流程。

如需为整个代码仓库创建可视化文档，请运行 npx @agent-native/core@latest visualize-repo --open，以创建／更新 agent-native.json、初始化 .agent-native/visual-docs/repo-overview，并打开本地桥接程序。

如果 Plans 工具返回 needs auth、Unauthorized 或 Session terminated，请勿继续重试——停止操作，并向用户提供 references/connection.md 中针对各客户端的重新连接步骤；连接器可用后再继续。

托管版默认配置：连接 https://plan.agent-native.com/mcp。请勿将共享密钥放入技能文件中。