@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/zh-CN/template-plan.md

@@ -0,0 +1,814 @@
+---
+title: "视觉计划"
+description: "Agent-Native 计划将您的编码代理的计划转变为结构化的、可审阅的文档 - 图表、线框图、带注释的代码、注释和共享链接。从CLI安装一次；您与之共享的审阅者以访客身份进行编辑，登录后仅可保存或共享。"
+---
+
+# 视觉计划
+
+> **大多数人安装 Plan 作为一项技能，而不是支架式应用程序。** 一个 CLI 命令
+> 添加 `/visual-plan` 和 `/visual-recap` skills 以及托管计划
+> 连接到您的编码代理 - 请参阅 [Plan plugin & marketplace](/docs/plan-plugin)
+> 用于插件和市场路线。分叉计划模板（参见
+> [For developers](#for-developers)) 是辅助路径，用于自托管或
+> 建立在计划本身之上。
+
+Agent-Native 计划是编码代理的可视化计划模式。它变成了普通
+Codex、Claude 代码、Markdown 或将实施计划粘贴到结构化中
+使用富文本、图表、线框图、带注释的代码演练查看表面
+以及文件树、注释、评论和可共享链接。
+
+它归结为两个命令。 `/visual-plan` 在代理之前**制定计划
+编写代码。 `/visual-recap` 将**已经发生的变化变成了 PR，
+提交、分支或 git diff — 进入高海拔可视化代码审查。都打开
+相同的审阅界面，因此您可以注释、评论并将反馈返回给
+以同样的方式代理。
+
+```an-diagram title="Two commands, one review surface" summary="Both commands publish through the hosted Plan MCP connector into the same annotate-and-comment surface."
+{
+  "html": "<div class=\"diagram-plan\"><div class=\"diagram-col\"><div class=\"diagram-node\"><span class=\"diagram-pill accent\">/visual-plan</span><small class=\"diagram-muted\">before code — architecture, UI, refactor</small></div><div class=\"diagram-node\"><span class=\"diagram-pill\">/visual-recap</span><small class=\"diagram-muted\">after code — PR, commit, branch, diff</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\">Plan MCP connector<br><small class=\"diagram-muted\">plan.agent-native.com</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">Review surface<br><small class=\"diagram-muted\">diagrams · wireframes · annotated code · comments</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&harr;</div><div class=\"diagram-node\">Coding agent<br><small class=\"diagram-muted\">feedback handed back</small></div></div>",
+  "css": ".diagram-plan{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-plan .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-plan .diagram-arrow{font-size:22px;line-height:1}.diagram-plan .center{display:flex;flex-direction:column;align-items:center;gap:4px;text-align:center}"
+}
+```
+
+```an-wireframe
+{
+  "surface": "desktop",
+  "html": "<div style='display:grid;grid-template-columns:1fr 250px;gap:14px;padding:16px;min-height:520px;box-sizing:border-box'><main style='display:flex;flex-direction:column;gap:12px;min-width:0'><div style='display:flex;align-items:center;gap:10px'><h1 style='margin:0'>Checkout redesign plan</h1><div style='flex:1'></div><button>Share</button><button class='primary'>Approve</button></div><div class='wf-card' style='display:grid;grid-template-columns:1fr 1fr;gap:10px;min-height:150px'><div class='wf-box'>Current wireframe</div><div class='wf-box'>Proposed wireframe</div></div><div class='wf-card' style='flex:1;display:flex;flex-direction:column;gap:10px'><strong>Implementation plan</strong><div class='wf-box'>Decision: keep existing checkout shell</div><div class='wf-box'>Annotated code walkthrough</div><div class='wf-box'>Open questions</div></div></main><aside class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Comments</strong><div class='wf-box'>Pin on primary CTA</div><div class='wf-box'>Question for agent</div><div class='wf-box'>Resolved copy note</div><button class='primary'>Hand back feedback</button></aside></div>"
+}
+```
+
+有两种方式进入计划：
+
+- **来自您的编码代理 (CLI)** — 一个命令即可安装技能、注册
+  托管计划连接器，并对其进行身份验证。
+- **在浏览器中** - 您与之共享的任何人都可以打开编辑器并创建或
+  以**访客身份进行编辑，无需注册**。他们仅在想要保存时才登录
+  或分享。
+
+## 安装技能 {#install}
+
+使用 Agent-Native CLI。这是推荐的设置，因为它安装了
+计划技能说明，注册托管计划 MCP 连接器，**和**运行
+一步完成特定于客户端的身份验证/设置流程，因此您的第一个工具调用不会
+撞到 OAuth 墙：
+
+```bash
+npx @agent-native/core@latest skills add visual-plan
+```
+
+该命令安装两个命令：`/visual-plan` 和 `/visual-recap`。
+
+如果您使用的是直接接受 MCP 连接器 URL 的基于聊天的主机
+（而不是 CLI 配置的客户端），连接托管计划连接器
+`https://plan.agent-native.com/_agent-native/mcp` — 请参阅 [MCP Clients](/docs/mcp-clients) 以了解特定于客户端的设置。
+
+身份验证是在设置时进行一次性浏览器登录 - 这是有意为之的
+是让代理持续存在并共享其生成的计划的原因。授权是什么
+步骤取决于您的客户：
+
+- **支持 OAuth 的主机**（Claude 代码）获取仅 URL 的 MCP 条目以及提示
+  运行`/mcp`并选择**身份验证**。
+- **Codex / Cowork** 运行简短的浏览器设备代码流程：CLI 打印代码，
+  打开验证页面，并在批准后写入连接器。
+- 在 **非交互式 shell 或 CI** 中，会跳过身份验证步骤并执行准确的
+  为您打印稍后运行的命令。
+
+默认情况下，CLI 以它可以配置的每个受支持的本地客户端为目标。通过
+`--client codex`、`--client claude-code` 或其他特定客户端，当您
+想要将设置范围缩小到一台主机：
+
+```bash
+npx @agent-native/core@latest skills add visual-plan
+```
+
+通过`--no-connect`注册连接器而不进行身份验证，然后运行
+`npx @agent-native/core@latest connect https://plan.agent-native.com --client all`
+当您准备好时，或者选择较窄的 `--client`：
+
+```bash
+npx @agent-native/core@latest skills add visual-plan --no-connect
+```
+
+要自动生成**每个拉取请求**的回顾，请传递 `--with-github-action`。
+这会编写一个在每个 PR 上运行 `visual-recap` 技能的 GitHub 操作，并且
+发布了一个交互式回顾计划，其中包含内嵌屏幕截图作为置顶评论 -
+参见[PR Visual Recap](/docs/pr-visual-recap)。
+
+```bash
+npx @agent-native/core@latest skills add visual-plan --with-github-action
+```
+
+工作流程编写完成后，运行`npx @agent-native/core@latest recap setup`进行配置
+GitHub Actions 秘密/变量（如果可能）和 `npx @agent-native/core@latest recap doctor`
+验证存储库是否已准备就绪。
+
+如果您只想通过打开Skills CLI来移植指令文件，请使用：
+
+```bash
+npx skills@latest add BuilderIO/agent-native --skill visual-plan
+```
+
+这仅安装技能说明。它不注册托管的MCP
+连接器，因此当您需要单命令设置时请使用 Agent-Native CLI 路径。
+
+> **更喜欢一次性安装插件？** Claude 代码和 Codex 可以添加
+> `BuilderIO/agent-native` 直接作为插件市场，捆绑了
+> 在一次安装中规划 skills*and* 连接器并自动更新为 skills
+> 改进 — 参见 [Plan plugin & marketplace](/docs/plan-plugin)。
+
+### 在 VS Code 中打开计划 {#vscode-extension}
+
+如果您使用 VS Code，请安装
+[Agent Native Plans extension](https://marketplace.visualstudio.com/items?itemName=Builder.agent-native)
+在侧面板中打开相同的计划审核界面，而不是让您进入
+单独的浏览器选项卡。计划工具仍然返回正常的 Web 链接，并且 MCP
+元数据还包括 VS Code 切换 URL：
+
+```text
+vscode://builder.agent-native/open?url=<encoded-plan-url>
+```
+
+扩展处理 URI，在 VS Code Web 视图中打开解码后的计划 URL，
+并包含一个命令来运行 VS 的现有 Agent Native MCP 连接流程
+代码 / GitHub 副驾驶。这对于 Claude 代码或其他代码特别有用
+编码代理工作流程，其中计划应位于正在编辑的文件旁边。
+
+## 从您的编码代理中使用它
+
+安装后，向您的代理询问适合工作的命令：
+
+- `/visual-plan` **在**实施之前创建结构化计划 -
+  架构、后端、重构、UI 或混合产品工作 - 引入
+  图表、线框图、模型、可点击原型和带注释的代码
+  工作需要的演练和文件树。
+- `/visual-recap` 对已经发生的变更进行高空**审查**
+  发生 — PR、提交、分支或 git diff — 作为架构、API、文件和
+  之前/之后块而不是原始差异墙。
+
+代理应首先检查代码库，然后在出现问题时创建可视化计划
+错误的方向将会付出高昂的代价。返回的计划链接将在
+浏览器或 VS Code，以便您可以注释、更正、选择选项并询问
+在代码更改开始之前更新。
+
+当 Codex、Claude 代码、Markdown 或粘贴的计划已存在时，使用
+`/visual-plan`；代理保留源计划并构建更丰富的评论
+从它开始，而不是重新开始。
+
+如果第一遍仍有可回答的决策，代理可以放置
+**开放式问题**表格位于同一计划的底部。接听并发送
+它向代理启动针对现有计划的修订。
+
+## 你可以用它做什么
+
+- **实施前审查。** React 到图表、线框图、选项选项卡，
+  开放问题表格、风险说明、带注释的代码演练和代码
+  在代理编辑文件之前进行预览。
+- **直接对计划发表评论。**将反馈固定到文本、图像、线框或
+  画布位置；选择评论是针对代理还是针对人类
+  审稿人； @提及有内联筹码的队友；并将评论解决为
+  计划不断发展。
+- **清楚地将反馈反馈给客服人员。**文本评论附在最近的位置
+  散文块，视觉注释包括精确的目标元数据和浏览器
+  交接包括一小部分视觉/画布评论的重点屏幕截图
+  位置而不是一张难以阅读的巨型图像。
+- **导出结果。**保留计划的 HTML、Markdown 或 JSON 收据
+  当您需要源代码控制友好的切换时。
+
+## 以访客身份在浏览器中进行编辑 {#guest}
+
+与您共享计划的人不需要安装任何东西。他们打开计划
+编辑器和**无需注册即可创建和编辑** - 他们以访客身份工作。登录
+仅当有人想要**保存或共享**自己的作品时才需要。
+
+当访客登录时，他们作为访客创建的计划将被**认领**到
+他们的帐户，因此他们构建的任何内容都不会丢失。
+
+计划内联散文编辑：点击进入任何文本部分，输入丰富的格式
+编辑器工具栏或斜线菜单，并且计划自动保存基础降价。评论
+注释模式暂时将文本部分变为只读，以便点击可以固定
+反馈；离开审阅模式以继续编辑散文。
+
+## 分享和评论 {#sharing}
+
+分享和评论是需要帐户的工作流程：
+
+- **查看**公共或共享计划适用于知道链接的任何人 - 无需帐户
+  必需。
+- **对共享计划发表评论**需要代理本机帐户。
+- **共享**计划（将其发布到链接、私人共享、审阅者访问权限，
+  跨设备或团队审核）需要登录。Google 登录会在以下情况出现
+  标准 Google OAuth 环境变量已配置。
+
+托管计划连接器位于 `https://plan.agent-native.com/_agent-native/mcp`。
+切勿将共享机密放入技能文件中。
+
+## 本地文件隐私模式 {#local-files}
+
+对于注重隐私的工作，请要求使用本地文件模式：
+
+```text
+Use /visual-plan in local-files mode. Do not write this plan to the Plan DB.
+```
+
+或为您的代理环境设置约定：
+
+```bash
+export AGENT_NATIVE_PLANS_MODE=local-files
+```
+
+在此模式下，代理写入本地 MDX 文件夹，并且不得调用托管
+规划 MCP 工具。当您需要该计划时，请使用存储库文件夹，例如 `plans/<slug>/`
+已使用代码签入。使用临时或忽略的文件夹，例如
+`/tmp/agent-native-plans/<slug>/` 或 `.agent-native/plans/<slug>/`，当
+计划应该远离 git。该文件夹包含：
+
+- `plan.mdx`
+- 可选`canvas.mdx`
+- 可选`prototype.mdx`
+- 可选`.plan-state.json`
+
+写入文件夹后，代理启动一个小型本地主机桥并打开
+针对仅限本地的源托管计划 UI：
+
+```bash
+npx @agent-native/core@latest plan local check --dir plans/<slug>
+npx @agent-native/core@latest plan local serve --dir plans/<slug> --kind plan --open
+```
+
+桥梁 URL 看起来像
+`https://plan.agent-native.com/local-plans/<slug>?bridge=http://127.0.0.1:...`.
+该页面是普通的计划查看器，但浏览器获取 `plan.mdx`，
+`canvas.mdx`、`prototype.mdx`、`.plan-state.json` 以及来自
+本地主机桥。计划内容不会写入托管数据库，而是
+未通过托管计划 actions 发送。保持桥接进程运行
+审查； URL 是您计算机的本地链接，不是可共享的团队链接。
+serve命令默认将打开的URL写入`.plan-url`，因此编码代理可以
+捕获它而不抓取长时间运行的标准输出；将该文件视为仅本地文件
+因为URL包含桥接令牌，所以不要提交它。
+
+在 macOS 上，`--open` 更喜欢 Chrome/Chromium，因为 Safari 可以阻止托管
+HTTPS 通过获取 HTTP 本地主机桥来计划页面。对于无头
+故障排除，运行：
+
+```bash
+npx @agent-native/core@latest plan local verify --dir plans/<slug> --kind plan
+```
+
+`verify`启动网桥，检查私网预检和JSON
+有效负载，打印诊断信息，然后退出。
+
+如果您使用相同的 `PLAN_LOCAL_DIR` 在本地运行 Plan 应用，您还可以
+打开可编辑的应用程序路由：
+
+```text
+http://localhost:<port>/local-plans/<slug>
+```
+
+对于存储库支持的文件夹，直接本地路由可以携带存储库相对
+文件夹路径，以便浏览器编辑继续写入该文件夹：
+
+```text
+http://localhost:<port>/local-plans/<slug>?path=plans%2F<slug>
+```
+
+计划应用程序使用 `agent-native.json` 中的 `apps.plan.roots[0].path` 作为
+升级本地计划的默认存储库位置，回退到 `plans/`：
+
+```json
+{
+  "version": 1,
+  "apps": {
+    "plan": {
+      "mode": "local-files",
+      "roots": [{ "name": "Plans", "path": "plans", "kind": "plans" }]
+    }
+  }
+}
+```
+
+直接本地计划路线包括保存临时本地文件夹的菜单操作
+进入该存储库位置。升级后，页面重新打开，显示 `?path=...` 和
+继续将 MDX 编辑自动保存到存储库文件夹。
+
+本地文件模式可防止计划或回顾内容进入 Agent-Native
+计划数据库。它还禁用托管共享、浏览器评论、计划历史记录，
+并发布/导出收据，直到您明确选择发布。移动
+本地规划到托管数据库中，用本地调用`publish-visual-plan`
+MDX文件夹路径；这将上传计划，为其分配托管 ID，启用共享
+并评论，并返回托管的URL。本地文件模式没有
+自动使您的编码代理的 LLM 本地化；选择本地或批准的
+模型是否隐私边界也很重要。
+
+## 桌面本地文件同步 {#desktop-local-sync}
+
+Agent Native Desktop 还为托管计划提供了本机本地文件夹桥。这个
+与本地文件隐私模式不同：托管计划数据库仍然是
+共享、评论、历史记录和实时评论的真实来源，而桌面
+可以将当前计划的源文件镜像到您选择的文件夹。
+
+在 Agent Native 桌面中打开计划，使用计划菜单的**本地文件** actions，
+然后：
+
+- **链接本地文件夹** — 选择该计划的 MDX 源的文件夹。
+- **同步到本地文件夹** — 写入 `plan.mdx`，可选 `canvas.mdx`，
+  可选的 `prototype.mdx`、可选的 `.plan-state.json` 和图像资源。
+- **导入本地编辑** - 读取文件夹并通过
+  `import-visual-plan-source` 以及计划的当前更新时间戳。
+- **自动同步更改** — 之后继续导出托管计划的最新源
+  在应用程序中进行的编辑。
+
+此路径不需要克隆 Plan 应用程序或运行 CLI。这是为了
+围绕托管计划进行文件优先审查/编辑，而不是保留计划内容
+托管数据库。
+
+## 删除托管计划数据 {#delete-data}
+
+已登录的所有者可以从计划列表中删除其托管计划和摘要，或者
+计划操作菜单。
+
+- **软删除**将计划移至**已删除**选项卡，制作正常计划
+  视图/直接链接停止工作，并通过创建行来删除公共访问
+  私人。 SQL 行将被保留，以便所有者稍后可以恢复计划。
+- **恢复**可从软删除计划的**已删除**选项卡中获取。
+- **永久删除**删除托管计划行和计划范围的评论，
+  部分、活动事件、版本快照、共享授权、滥用报告和
+  SQL 资产记录。 UI 需要在决赛前输入 `DELETE <plan-id>`
+  按钮启用。
+
+永久删除会删除 Plan 应用的数据库记录和 SQL 支持的资产
+字节/引用。如果部署使用外部上传提供程序，则提供程序
+对象保留遵循该提供商的生命周期，因为共享上传
+抽象当前不公开对象删除。本地文件隐私模式
+将源代码保留在本地 MDX 文件夹中；删除托管数据不会
+触摸本地文件。
+
+## 有用的提示
+
+- “在更改身份验证流程之前使用 `/visual-plan`。”
+- “为具有移动和桌面状态的新入门屏幕创建 `/visual-plan`。”
+- “在下面的 Markdown 计划上使用 `/visual-plan`，更容易审核。”
+- “在此 PR 上运行 `/visual-recap`，以便我可以先查看更改的形状。”
+- “在 `main` 和此分支之间的差异上使用 `/visual-recap`。”
+- “在本地文件模式下使用 `/visual-recap`，因此不会将摘要内容写入计划数据库。”
+
+## 从身份验证错误中恢复 {#auth-errors}
+
+如果计划工具返回 `needs auth`、`Unauthorized` 或“会话”
+已终止`，不要继续重试。使用
+`npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex`对于 Codex，或在支持 OAuth 的主机中重新运行`/mcp` → **身份验证**。开始一个
+在等待该工具之前新建 Codex 线程或重新启动/重新加载相关客户端
+要更新的注册表。
+
+## 对于开发者
+
+本文档的其余部分适用于任何分叉或自行托管计划模板的人。
+大多数用户应该使用 CLI 安装该技能，而不是搭建应用程序。
+
+### 快速入门
+
+```bash
+npx @agent-native/core@latest create my-plans --standalone --template plan
+cd my-plans
+pnpm install
+pnpm dev
+```
+
+托管应用程序支持的技能使用：
+
+- 应用程序：`https://plan.agent-native.com`
+- MCP: `https://plan.agent-native.com/_agent-native/mcp`
+
+当您开发计划本身、测试本地持久性或运行完全自托管的审核界面时，本地模板非常有用。
+
+### 数据模型
+
+架构位于 `templates/plan/server/db/schema.ts` 中。核心表：
+
+| 表格               | 它包含什么                                                                                                                                                                        |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `plans`            | 每个计划或回顾 - `title`、`brief`、`kind`（计划/回顾）、`status`、`source`、`html`/`markdown`/`content`、`hosted_plan_id/url`、使用统计、`source_url`、 `deleted_at`/`deleted_by` |
+| `plan_sections`    | 计划中的有序部分 - `type`、`title`、`body`、`html`、`sort_order`、`created_by`                                                                                                    |
+| `plan_comments`    | 主题评论 - `kind`、`status`、`anchor`、`message`、`resolution_target`、`mentions_json`、`resolved_by`                                                                             |
+| `plan_events`      | 计划中代理/人工事件的审核日志                                                                                                                                                     |
+| `plan_versions`    | 版本历史记录的时间点快照                                                                                                                                                          |
+| `plan_shares`      | 每位主体的份额授予（查看者/编辑者/管理员）                                                                                                                                        |
+| `plan_guest_mints` | 访客会话发放限速记录                                                                                                                                                              |
+| `plan_assets`      | 内嵌图像资源存储为base64（没有上传提供商时的回退）                                                                                                                                |
+
+```an-schema title="Plan data model" summary="One plan row owns ordered sections plus comments, events, versions, shares, and inline assets."
+{
+  "entities": [
+    { "id": "plans", "name": "plans", "note": "each plan or recap", "fields": [
+      { "name": "id", "type": "text", "pk": true },
+      { "name": "title", "type": "text" },
+      { "name": "brief", "type": "text", "nullable": true },
+      { "name": "kind", "type": "enum", "note": "plan | recap" },
+      { "name": "status", "type": "text" },
+      { "name": "source", "type": "text", "nullable": true },
+      { "name": "hosted_plan_id", "type": "text", "nullable": true, "note": "hosted_plan_url paired" },
+      { "name": "source_url", "type": "text", "nullable": true },
+      { "name": "deleted_at", "type": "timestamp", "nullable": true, "note": "soft delete; deleted_by paired" }
+    ] },
+    { "id": "plan_sections", "name": "plan_sections", "note": "ordered sections within a plan", "fields": [
+      { "name": "id", "type": "text", "pk": true },
+      { "name": "plan_id", "type": "text", "fk": "plans.id" },
+      { "name": "type", "type": "text" },
+      { "name": "title", "type": "text", "nullable": true },
+      { "name": "body", "type": "text", "nullable": true },
+      { "name": "html", "type": "text", "nullable": true },
+      { "name": "sort_order", "type": "integer" },
+      { "name": "created_by", "type": "text", "nullable": true }
+    ] },
+    { "id": "plan_comments", "name": "plan_comments", "note": "threaded comments", "fields": [
+      { "name": "id", "type": "text", "pk": true },
+      { "name": "plan_id", "type": "text", "fk": "plans.id" },
+      { "name": "kind", "type": "text" },
+      { "name": "status", "type": "text" },
+      { "name": "anchor", "type": "json", "nullable": true },
+      { "name": "message", "type": "text" },
+      { "name": "resolution_target", "type": "text", "nullable": true, "note": "agent | human | null" },
+      { "name": "mentions_json", "type": "json", "nullable": true },
+      { "name": "resolved_by", "type": "text", "nullable": true }
+    ] },
+    { "id": "plan_events", "name": "plan_events", "note": "audit log of agent/human events", "fields": [
+      { "name": "id", "type": "text", "pk": true },
+      { "name": "plan_id", "type": "text", "fk": "plans.id" }
+    ] },
+    { "id": "plan_versions", "name": "plan_versions", "note": "point-in-time snapshots", "fields": [
+      { "name": "id", "type": "text", "pk": true },
+      { "name": "plan_id", "type": "text", "fk": "plans.id" }
+    ] },
+    { "id": "plan_shares", "name": "plan_shares", "note": "per-principal grants", "fields": [
+      { "name": "id", "type": "text", "pk": true },
+      { "name": "plan_id", "type": "text", "fk": "plans.id" },
+      { "name": "role", "type": "enum", "note": "viewer | editor | admin" }
+    ] },
+    { "id": "plan_guest_mints", "name": "plan_guest_mints", "note": "rate-limit records for guest session issuance", "fields": [
+      { "name": "id", "type": "text", "pk": true }
+    ] },
+    { "id": "plan_assets", "name": "plan_assets", "note": "inline image assets as base64", "fields": [
+      { "name": "id", "type": "text", "pk": true },
+      { "name": "plan_id", "type": "text", "fk": "plans.id" }
+    ] }
+  ],
+  "relations": [
+    { "from": "plans", "to": "plan_sections", "kind": "1-n", "label": "has sections" },
+    { "from": "plans", "to": "plan_comments", "kind": "1-n", "label": "has comments" },
+    { "from": "plans", "to": "plan_events", "kind": "1-n", "label": "has events" },
+    { "from": "plans", "to": "plan_versions", "kind": "1-n", "label": "has versions" },
+    { "from": "plans", "to": "plan_shares", "kind": "1-n", "label": "has shares" },
+    { "from": "plans", "to": "plan_assets", "kind": "1-n", "label": "has assets" }
+  ]
+}
+```
+
+### 密钥actions
+
+Actions 中的 `templates/plan/actions/`：
+
+- **创建** — `create-visual-plan`、`create-visual-recap`、`create-ui-plan`、`create-prototype-plan`、`create-plan-design`、`create-visual-questions`
+- **阅读和编辑** — `get-visual-plan`、`update-visual-plan`、`list-visual-plans`、`import-visual-plan-source`、`patch-visual-plan-source`、`read-visual-plan-source`、`export-visual-plan`
+- **生命周期** - `delete-visual-plan` 用于仅限所有者的软删除、恢复和键入确认永久删除
+- **发布与分享** — `publish-visual-plan`
+- **版本** — `list-plan-versions`、`get-plan-version`、`restore-plan-version`
+- **评论和反馈** — `get-plan-feedback`、`reply-to-plan-comment`、`resolve-plan-comment`、`consume-plan-feedback`、`delete-plan-comment`
+- **原型** — `convert-visual-plan-to-prototype`、`create-prototype-plan`
+- **上下文和导航** — `view-screen`、`navigate`
+
+### 自定义 MDX 块 {#custom-mdx-blocks}
+
+计划源文件为 MDX，但应用程序不会渲染任意导入的 JSX
+组件。自定义 MDX 标签必须注册为计划块，以便服务器可以
+解析并序列化它，浏览器可以渲染和编辑它，代理可以
+在`get-plan-blocks`返回的块词汇中查看它。
+
+注册块具有三个表面：
+
+- 无 React 的架构和 MDX 配置，对于服务器和代理代码来说是安全的。
+- `shared/plan-content.ts` 中的规范化运行时类型/架构条目。
+- 具有 `Read` 和可选 `Edit` React 组件的浏览器块规范。
+
+保持方块 `type` 和 MDX `tag` 稳定。 `type` 以标准化存储
+计划JSON； `tag` 是 `plan.mdx` 中的组件名称。注册表句柄
+基本 MDX 属性 `id`、`title`、`summary` 和 `editable`，因此不要
+在 `toAttrs` 中重复它们。
+
+1. 为数据形状和 MDX 往返添加共享配置。
+
+```ts
+// templates/plan/shared/risk-card.config.ts
+import { z } from "zod";
+import {
+  markdown,
+  type BlockMdxConfig,
+} from "@agent-native/core/blocks/server";
+
+export type RiskCardSeverity = "low" | "medium" | "high";
+
+export interface RiskCardData {
+  severity?: RiskCardSeverity;
+  body: string;
+}
+
+const severities = new Set(["low", "medium", "high"]);
+
+export const riskCardSchema = z.object({
+  severity: z.enum(["low", "medium", "high"]).optional(),
+  body: markdown(z.string().trim().min(1).max(10_000)),
+}) as z.ZodType<RiskCardData>;
+
+export const riskCardMdx: BlockMdxConfig<RiskCardData> = {
+  tag: "RiskCard",
+  childrenField: "body",
+  toAttrs: (data) => ({
+    severity: data.severity,
+  }),
+  fromAttrs: (attrs, children) => {
+    const severity = attrs.string("severity");
+
+    return {
+      severity: severities.has(severity ?? "")
+        ? (severity as RiskCardSeverity)
+        : undefined,
+      body: children,
+    };
+  },
+};
+```
+
+2. 扩展标准化计划内容模型
+   `templates/plan/shared/plan-content.ts`.
+
+将新的`type`添加到`PlanBlockType`，添加匹配的块接口
+`PlanBlock` 并集，并将相同的数据形状添加到 `planBlockSchema`。这保持了
+数据库保存、源导入和验证自定义的 `update-block` 补丁
+阻止而不是将其作为未知类型拒绝。
+
+3. 在
+   `templates/plan/shared/plan-block-registry.ts`.
+
+```ts
+import {
+  BlockRegistry,
+  defineBlock,
+  registerLibraryBlockConfigs,
+  registerBlocks,
+} from "@agent-native/core/blocks/server";
+import {
+  riskCardMdx,
+  riskCardSchema,
+  type RiskCardData,
+} from "./risk-card.config.js";
+
+const ServerReadStub = () => null;
+
+const riskCardServerBlock = defineBlock<RiskCardData>({
+  type: "risk-card",
+  schema: riskCardSchema,
+  mdx: riskCardMdx,
+  Read: ServerReadStub,
+  placement: ["block"],
+  label: "Risk card",
+  description: "A markdown risk note with a low, medium, or high severity.",
+});
+
+export function registerPlanBlocks(registry: BlockRegistry): void {
+  registerLibraryBlockConfigs(registry, {
+    overrides: PLAN_SERVER_LIBRARY_OVERRIDES,
+  });
+  registerBlocks(registry, [riskCardServerBlock]);
+}
+```
+
+4. 注册浏览器规范
+   `templates/plan/app/components/plan/planBlocks.tsx`.
+
+```tsx
+import {
+  defineBlock,
+  registerLibraryBlocks,
+  registerBlocks,
+  type BlockReadProps,
+} from "@agent-native/core/blocks";
+import {
+  riskCardMdx,
+  riskCardSchema,
+  type RiskCardData,
+} from "@shared/risk-card.config";
+
+function RiskCardBlock({ data, blockId, ctx }: BlockReadProps<RiskCardData>) {
+  return (
+    <section
+      className="rounded-md border border-border bg-card p-4"
+      data-block-id={blockId}
+      data-severity={data.severity}
+    >
+      <div className="mb-2 text-xs font-semibold uppercase text-muted-foreground">
+        {data.severity ?? "risk"}
+      </div>
+      {ctx.renderMarkdown?.(data.body) ?? (
+        <p className="whitespace-pre-wrap text-sm">{data.body}</p>
+      )}
+    </section>
+  );
+}
+
+const riskCardBlock = defineBlock<RiskCardData>({
+  type: "risk-card",
+  schema: riskCardSchema,
+  mdx: riskCardMdx,
+  Read: RiskCardBlock,
+  placement: ["block"],
+  editSurface: "panel",
+  label: "Risk card",
+  description: "A markdown risk note with a low, medium, or high severity.",
+  empty: () => ({ severity: "medium", body: "Describe the risk." }),
+});
+
+registerLibraryBlocks(planBlockRegistry, {
+  overrides: PLAN_LIBRARY_OVERRIDES,
+});
+registerBlocks(planBlockRegistry, [riskCardBlock]);
+```
+
+完成后，计划 MDX 可以使用：
+
+```mdx
+<RiskCard id="risk-auth" severity="high">
+
+Token refresh failures can strand active reviewer sessions.
+
+</RiskCard>
+```
+
+服务器注册表使该源可导入/可导出，而客户端
+注册表使其在 `PlanBlockView` 中呈现。如果该块应该由
+特工，保持`label`、`description`、`placement`和`empty`精确；那些
+字段流入实时块词汇表。
+
+当覆盖现有块时，在共享之后注册覆盖
+图书馆注册。 `type` 和 MDX `tag` 的最后注册均获胜。
+
+添加块后，运行重点计划测试：
+
+```bash
+pnpm --filter plan test -- plan-mdx plan-block-registry
+```
+
+### 路线图
+
+- `app/routes/plans.$id.tsx` — 计划编辑/审核界面
+- `app/routes/plans._index.tsx` — 计划列表
+- `app/routes/share.$token.tsx` — 公共/共享平面图
+- `app/routes/local-plans.$slug.tsx` — 本地文件模式预览
+
+### 本地模式（高级、离线） {#local-mode}
+
+对于完全离线、无帐户的使用，您可以在本地运行计划应用程序并将其指向本地 MDX 文件夹。对于更严格的无数据库路径，请使用 [local-files privacy mode](#local-files)，它从 MDX 文件夹读取而不是创建本地 SQL 行。本地模式是一个单独的高级路径 - 不是默认的托管流程。
+
+## 事件和通知 {#events}
+
+计划模板在框架事件总线上发出四个事件。任何自动化
+可以订阅它们——无需自定义集成代码。
+
+### 事件参考 {#event-reference}
+
+#### `plan.created`
+
+创建新的视觉计划或回顾时触发。
+
+| 字段        | 类型                  | 描述                                |
+| ----------- | --------------------- | ----------------------------------- |
+| `planId`    | 字符串                | 唯一计划标识符                      |
+| `title`     | 字符串                | 计划标题                            |
+| `kind`      | `"plan"` \| `"recap"` | 这是计划还是回顾                    |
+| `status`    | 字符串                | 初始状态（例如`"review"`）          |
+| `path`      | 字符串                | 应用相对路径（例如`/plans/plan-…`） |
+| `createdBy` | 字符串                | 创建计划时始终为 `"agent"`          |
+
+#### `plan.commented`
+
+当一条或多条评论添加到计划中时触发。
+
+| 字段               | 类型                             | 描述                                            |
+| ------------------ | -------------------------------- | ----------------------------------------------- |
+| `planId`           | 字符串                           | 计划标识符                                      |
+| `title`            | 字符串                           | 计划标题                                        |
+| `kind`             | `"plan"` \| `"recap"`            | 计划或回顾                                      |
+| `commentIds`       | 字符串[]                         | 新评论的ID                                      |
+| `commentCount`     | 数字                             | 本批次新评论数                                  |
+| `resolutionTarget` | `"agent"` \| `"human"` \| `null` | 主要目标 - 如果任何评论针对代理，则为 `"agent"` |
+| `excerpt`          | 字符串                           | 第一条评论的前 200 个字符                       |
+| `author`           | 字符串\| 空                      | 评论者的电子邮件（如果知道）                    |
+| `path`             | 字符串                           | 应用相对路径                                    |
+
+#### `plan.published`
+
+当本地计划发布（或重新发布）到托管可共享 URL 时触发。
+
+| 字段                  | 类型                  | 描述                      |
+| --------------------- | --------------------- | ------------------------- |
+| `planId`              | 字符串                | 本地计划标识符            |
+| `title`               | 字符串                | 计划标题                  |
+| `kind`                | `"plan"` \| `"recap"` | 计划或回顾                |
+| `hostedPlanId`        | 字符串                | 托管计划标识符            |
+| `url`                 | 字符串                | 托管计划的完全公开 URL    |
+| `requestedVisibility` | 字符串                | `"public"`、`"private"`等 |
+
+#### `plan.status.changed`
+
+当计划状态更改时触发（例如 `review` → `approved`）。
+
+| 字段        | 类型                  | 描述             |
+| ----------- | --------------------- | ---------------- |
+| `planId`    | 字符串                | 计划标识符       |
+| `title`     | 字符串                | 计划标题         |
+| `kind`      | `"plan"` \| `"recap"` | 计划或回顾       |
+| `oldStatus` | 字符串\| 空           | 之前的状态       |
+| `newStatus` | 字符串                | 新状态           |
+| `changedBy` | 字符串\| 空           | 更改者的电子邮件 |
+| `path`      | 字符串                | 应用相对路径     |
+
+### 自动化配方 {#automation-recipes}
+
+这些自动化是通过询问计划代理来创建的 - 无需更改代码。
+代理使用 `action=define` 调用 `manage-automations`，写入
+`jobs/<name>.md`资源，事件订阅立即开始。
+
+#### 当有人对计划发表评论时通过 Webhook 进行通知
+
+询问计划代理：
+
+> “当有人对计划添加人工评论时，POST 会向我的 webhook 发送一条消息。”
+
+代理创建这样的自动化：
+
+```yaml
+---
+triggerType: event
+event: plan.commented
+condition: "resolutionTarget is human or resolutionTarget is null"
+mode: agentic
+domain: plan
+enabled: true
+---
+Send a POST request to ${keys.NOTIFY_WEBHOOK} with a JSON body containing:
+  - "title": the plan title from the event payload
+  - "excerpt": the comment excerpt from the event payload
+  - "url": the base app URL concatenated with the path field from the event payload
+  - "author": the author field from the event payload (may be null)
+```
+
+在自动化启动之前，您需要将 Webhook URL 添加为临时密钥：
+
+1. 转到 **设置 → 密钥** 并使用您的名称添加名为 `NOTIFY_WEBHOOK` 的密钥
+   webhook URL（例如 Slack 传入 webhook、通用 HTTP 端点或任何
+   通知服务URL)。
+2. 可以选择在密钥上设置 URL 白名单，以限制其可以访问的来源
+   POST 至。
+
+`web-request`工具之前解析了`${keys.NOTIFY_WEBHOOK}`服务器端
+发送 - 原始 URL 永远不会出现在代理的上下文中。
+
+**要专门针对 Slack：** 将 `NOTIFY_WEBHOOK` 设置为您的 Slack 传入
+网络钩子 URL
+(`https://hooks.slack.com/services/…`)。上面的自动化主体已经
+生成一个有效负载 Slack 的传入 webhook 通过 `text` 或 `blocks` 接受
+字段 - 如果您想要更丰富，请代理将正文格式化为 Slack 消息
+格式化。
+
+#### 当反馈针对编码代理时唤醒编码代理
+
+对于针对编码代理 (`resolutionTarget === "agent"`) 的反馈，请询问：
+
+> “当计划注释针对代理时，使用该计划运行我的编码代理
+> 摘录作为上下文。"
+
+```yaml
+---
+triggerType: event
+event: plan.commented
+condition: "resolutionTarget is agent"
+mode: agentic
+domain: plan
+enabled: true
+---
+
+Use the manage-notifications action or web-request tool to alert the coding agent
+that new agent-targeted feedback has arrived on plan ${planId}: "${excerpt}".
+Include the plan path so the agent can navigate directly to it.
+```
+
+因为自动化运行完整的代理循环（`mode: agentic`），所以它可以调用
+`web-request`，发送通知或调用代理有权访问的任何操作。
+确切的传递机制取决于您拥有的通知渠道
+已配置 - 代理会选择最佳的可用选项。
+
+## 下一步是什么
+
+- [**PR Visual Recap**](/docs/pr-visual-recap) - 在每个拉取请求上自动运行 `/visual-recap`
+- [**Automations**](/docs/automations) — 事件触发和计划的自动化
+- [**Plan plugin & marketplace**](/docs/plan-plugin) — 将计划 skills 安装为 Claude 代码或 Codex 插件
+- [**Skills**](/docs/skills-guide) — Agent-Native 如何安装 skills
+- [**MCP Clients**](/docs/mcp-clients) — 配置托管 MCP 连接器
+- [**Templates**](/docs/cloneable-saas) — 克隆自有模型