@agent-native/core 0.79.26 → 0.79.27

package/corpus/core/docs/content/locales/zh-CN/workspace-connections.mdx

@@ -16,13 +16,75 @@ description: "用于 connect-once-use-everywhere 集成的共享提供商元数
 - **credentialRef** — 指向保管库机密 (`{ key: "SLACK_BOT_TOKEN", scope: "org" }`) 的指针。连接表明令牌所在的位置；金库保存着价值。
 - **就绪** - 应用程序看到的组合状态：`connected`（已授予 + 存在凭据）、`needs_grant`、`needs_credentials`、`needs_attention` 或 `not_configured`。
 
-```an-diagram title="连接一次、授予应用程序、重复使用凭据" summary="连接保存提供者元数据（绝不是秘密）和指向保管库的 credentialRefs。每个应用程序授予解锁它。应用程序读取单个就绪状态。"
-{
-  "html": "<div class=\"diagram-conn\"><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill accent\">Connection</span><div class=\"diagram-box\" data-rough>named provider account<br><small class=\"diagram-muted\">provider, label, 状态、作用域、配置 &middot; never stores secret values</small></div><div class=\"diagram-muted\">credentialRef &rarr; pointer to a vault secret</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill\">Grant</span><div class=\"diagram-box\" data-rough>per-app permission<br><small class=\"diagram-muted\">no grant = no credential access</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill ok\">Readiness</span><small class=\"diagram-muted\">what the app sees</small><div class=\"sev-row\"><span class=\"diagram-pill ok\">connected</span><span class=\"diagram-pill warn\">needs_grant</span></div><div class=\"sev-row\"><span class=\"diagram-pill warn\">needs_credentials</span><span class=\"diagram-pill warn\">needs_attention</span></div><div class=\"sev-row\"><span class=\"diagram-pill\">not_configured</span></div></div></div>",
-  "css": ".diagram-conn{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-conn .col{display:flex;flex-direction:column;gap:8px;padding:14px;min-width:220px}.diagram-conn .diagram-arrow{font-size:22px;line-height:1}.diagram-conn .sev-row{display:flex;gap:8px;flex-wrap:wrap}"
+<Diagram id="doc-block-omeefw" title={"连接一次、授予应用程序、重复使用凭据"} summary={"连接保存提供者元数据（绝不是秘密）和指向保管库的 credentialRefs。每个应用程序授予解锁它。应用程序读取单个就绪状态。"}>
+
+```html
+<div class="diagram-conn">
+  <div class="diagram-panel col" data-rough>
+    <span class="diagram-pill accent">Connection</span>
+    <div class="diagram-box" data-rough>
+      named provider account<br /><small class="diagram-muted"
+        >provider, label, 状态、作用域、配置 &middot; never stores secret
+        values</small
+      >
+    </div>
+    <div class="diagram-muted">
+      credentialRef &rarr; pointer to a vault secret
+    </div>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel col" data-rough>
+    <span class="diagram-pill">Grant</span>
+    <div class="diagram-box" data-rough>
+      per-app permission<br /><small class="diagram-muted"
+        >no grant = no credential access</small
+      >
+    </div>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel col" data-rough>
+    <span class="diagram-pill ok">Readiness</span
+    ><small class="diagram-muted">what the app sees</small>
+    <div class="sev-row">
+      <span class="diagram-pill ok">connected</span
+      ><span class="diagram-pill warn">needs_grant</span>
+    </div>
+    <div class="sev-row">
+      <span class="diagram-pill warn">needs_credentials</span
+      ><span class="diagram-pill warn">needs_attention</span>
+    </div>
+    <div class="sev-row"><span class="diagram-pill">not_configured</span></div>
+  </div>
+</div>
+```
+
+```css
+.diagram-conn {
+  display: flex;
+  align-items: center;
+  gap: 14px;
+  flex-wrap: wrap;
+}
+.diagram-conn .col {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 14px;
+  min-width: 220px;
+}
+.diagram-conn .diagram-arrow {
+  font-size: 22px;
+  line-height: 1;
+}
+.diagram-conn .sev-row {
+  display: flex;
+  gap: 8px;
+  flex-wrap: wrap;
 }
 ```
 
+</Diagram>
+
 ### 工作示例：Slack
 
 连接 Slack 一次并将其授予 Brain and Analytics：
@@ -260,13 +322,69 @@ const brainCatalog = await listWorkspaceConnectionProviderCatalogForApp({
 
 工作区连接提供程序元数据回答：“这是哪个提供程序，它能做什么，可能需要什么凭据密钥，以及哪些模板应提供它？”
 
-```an-diagram title="连接存储与保管库" summary="金库拥有秘密价值。连接拥有提供者元数据和 credentialRefs（指针）。在执行时，应用程序通过授予的连接解析引用并从保管库读取值。"
-{
-  "html": "<div class=\"diagram-vault\"><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill accent\">连接存储</span><div class=\"diagram-box\" data-rough>provider account + metadata<br><small class=\"diagram-muted\">状态、作用域、配置</small></div><div class=\"diagram-box\" data-rough>credentialRef<br><small class=\"diagram-muted\">{ key: SLACK_BOT_TOKEN, scope: org }</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">应用 action</span><small class=\"diagram-muted\">resolves at execution time through a granted ref</small><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill ok\">Vault</span><div class=\"diagram-box\" data-rough>secret value<br><small class=\"diagram-muted\">绝不返回给代理或 UI</small></div></div></div>",
-  "css": ".diagram-vault{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-vault .col{display:flex;flex-direction:column;gap:8px;padding:14px;min-width:220px}.diagram-vault .diagram-card{display:flex;flex-direction:column;gap:6px;padding:12px 14px}.diagram-vault .diagram-arrow{font-size:22px;line-height:1}"
+<Diagram id="doc-block-giwhzq" title={"连接存储与保管库"} summary={"金库拥有秘密价值。连接拥有提供者元数据和 credentialRefs（指针）。在执行时，应用程序通过授予的连接解析引用并从保管库读取值。"}>
+
+```html
+<div class="diagram-vault">
+  <div class="diagram-panel col" data-rough>
+    <span class="diagram-pill accent">连接存储</span>
+    <div class="diagram-box" data-rough>
+      provider account + metadata<br /><small class="diagram-muted"
+        >状态、作用域、配置</small
+      >
+    </div>
+    <div class="diagram-box" data-rough>
+      credentialRef<br /><small class="diagram-muted"
+        >{ key: SLACK_BOT_TOKEN, scope: org }</small
+      >
+    </div>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-card">
+    <span class="diagram-pill">应用 action</span
+    ><small class="diagram-muted"
+      >resolves at execution time through a granted ref</small
+    >
+    <div class="diagram-arrow diagram-muted" aria-hidden="true">&darr;</div>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel col" data-rough>
+    <span class="diagram-pill ok">Vault</span>
+    <div class="diagram-box" data-rough>
+      secret value<br /><small class="diagram-muted">绝不返回给代理或 UI</small>
+    </div>
+  </div>
+</div>
+```
+
+```css
+.diagram-vault {
+  display: flex;
+  align-items: center;
+  gap: 14px;
+  flex-wrap: wrap;
+}
+.diagram-vault .col {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 14px;
+  min-width: 220px;
+}
+.diagram-vault .diagram-card {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 14px;
+}
+.diagram-vault .diagram-arrow {
+  font-size: 22px;
+  line-height: 1;
 }
 ```
 
+</Diagram>
+
 同时使用两者：
 
 1. Dispatch（或其他工作区设置流程）创建底层保管库机密或 OAuth 凭证引用。

package/corpus/core/docs/content/locales/zh-CN/workspace-management.mdx

@@ -9,13 +9,59 @@ description: "分支、CODEOWNERS、PR 审查以及 Dispatch 如何与 git 级
 
 本指南涵盖了运行代理本机工作区的操作方面 - 如何分支、谁审查什么、如何设置代码所有权以及 Dispatch 控制平面如何适应您的治理模型。
 
-```an-diagram title="两个治理平面" summary="Git 管理代码； Dispatch 控制运行时。它们是互补的——不要将一个复制到另一个中。"
-{
-  "html": "<div class=\"gov\"><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Git 和 GitHub</span><strong>代码治理</strong><div class=\"gov-list\"><span class=\"diagram-pill\">CODEOWNERS</span><span class=\"diagram-pill\">branch protection</span><span class=\"diagram-pill\">PR 评审</span><span class=\"diagram-pill\">git log / blame</span></div></div><div class=\"diagram-pill diagram-muted\">+</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Dispatch</span><strong>Runtime governance</strong><div class=\"gov-list\"><span class=\"diagram-pill\">vault secrets &amp; grants</span><span class=\"diagram-pill\">workspace resources</span><span class=\"diagram-pill\">agent profiles</span><span class=\"diagram-pill\">approvals &amp; audit</span></div></div></div>",
-  "css": ".gov{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.gov .diagram-card{display:flex;flex-direction:column;gap:8px;padding:16px 18px;flex:1;min-width:240px}.gov .gov-list{display:flex;flex-wrap:wrap;gap:6px;margin-top:4px}"
+<Diagram id="doc-block-1tiegxe" title={"两个治理平面"} summary={"Git 管理代码； Dispatch 控制运行时。它们是互补的——不要将一个复制到另一个中。"}>
+
+```html
+<div class="gov">
+  <div class="diagram-card">
+    <span class="diagram-pill accent">Git 和 GitHub</span
+    ><strong>代码治理</strong>
+    <div class="gov-list">
+      <span class="diagram-pill">CODEOWNERS</span
+      ><span class="diagram-pill">branch protection</span
+      ><span class="diagram-pill">PR 评审</span
+      ><span class="diagram-pill">git log / blame</span>
+    </div>
+  </div>
+  <div class="diagram-pill diagram-muted">+</div>
+  <div class="diagram-card">
+    <span class="diagram-pill accent">Dispatch</span
+    ><strong>Runtime governance</strong>
+    <div class="gov-list">
+      <span class="diagram-pill">vault secrets &amp; grants</span
+      ><span class="diagram-pill">workspace resources</span
+      ><span class="diagram-pill">agent profiles</span
+      ><span class="diagram-pill">approvals &amp; audit</span>
+    </div>
+  </div>
+</div>
+```
+
+```css
+.gov {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  flex-wrap: wrap;
+}
+.gov .diagram-card {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 16px 18px;
+  flex: 1;
+  min-width: 240px;
+}
+.gov .gov-list {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  margin-top: 4px;
 }
 ```
 
+</Diagram>
+
 ## 分支
 
 ### 功能分支

package/corpus/core/docs/content/locales/zh-CN/workspace.mdx

@@ -11,13 +11,67 @@ description: "Claude - 每个用户的代码级自定义 - skills、内存、指
 
 变化：**它是 SQL 行，而不是文件系统文件。**每个用户都将自己的工作区存储在数据库中。没有要启动的开发盒，没有每个用户的容器，没有要安装的文件。多租户 SaaS 可以为每个用户提供基本上免费的完全可定制的代理，因为所有这些都是行——个人内存、个人 MCP 服务器、个人 skills、个人子代理——并且共享代码库同时托管所有这些。
 
-```an-diagram title="Claude-Code 工作区，但存储在 SQL 中" summary="相同的定制层——指令、技能、内存、代理、作业、MCP——除了每个文件都是共享多租户数据库中的一行。"
-{
-  "html": "<div class=\"ws-map\"><div class=\"diagram-card cc\"><span class=\"diagram-pill warn\">Claude Code / Codex</span><small class=\"diagram-muted\">~/.claude/ on a local disk</small><div class=\"ws-files\"><span class=\"diagram-box\">CLAUDE.md</span><span class=\"diagram-box\">skills/</span><span class=\"diagram-box\">memory</span><span class=\"diagram-box\">mcp.json</span></div><small class=\"diagram-muted\">one codebase per developer</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card an\"><span class=\"diagram-pill accent\">Agent-native 工作区</span><small class=\"diagram-muted\">rows in one SQL 数据库</small><div class=\"ws-rows\"><span class=\"diagram-pill\">AGENTS.md</span><span class=\"diagram-pill\">skills/&hellip;</span><span class=\"diagram-pill\">memory/&hellip;</span><span class=\"diagram-pill\">mcp-servers/&hellip;</span></div><small class=\"diagram-muted\">一个代码库，多用户，有作用域 <code>u:&lt;email&gt;:&hellip;</code></small></div></div>",
-  "css": ".ws-map{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.ws-map .diagram-card{display:flex;flex-direction:column;gap:8px;padding:16px 18px;flex:1;min-width:220px}.ws-map .ws-files,.ws-map .ws-rows{display:flex;flex-wrap:wrap;gap:6px;margin:4px 0}.ws-map .diagram-arrow{font-size:24px}"
+<Diagram id="doc-block-1729nmr" title={"Claude-Code 工作区，但存储在 SQL 中"} summary={"相同的定制层——指令、技能、内存、代理、作业、MCP——除了每个文件都是共享多租户数据库中的一行。"}>
+
+```html
+<div class="ws-map">
+  <div class="diagram-card cc">
+    <span class="diagram-pill warn">Claude Code / Codex</span
+    ><small class="diagram-muted">~/.claude/ on a local disk</small>
+    <div class="ws-files">
+      <span class="diagram-box">CLAUDE.md</span
+      ><span class="diagram-box">skills/</span
+      ><span class="diagram-box">memory</span
+      ><span class="diagram-box">mcp.json</span>
+    </div>
+    <small class="diagram-muted">one codebase per developer</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-card an">
+    <span class="diagram-pill accent">Agent-native 工作区</span
+    ><small class="diagram-muted">rows in one SQL 数据库</small>
+    <div class="ws-rows">
+      <span class="diagram-pill">AGENTS.md</span
+      ><span class="diagram-pill">skills/&hellip;</span
+      ><span class="diagram-pill">memory/&hellip;</span
+      ><span class="diagram-pill">mcp-servers/&hellip;</span>
+    </div>
+    <small class="diagram-muted"
+      >一个代码库，多用户，有作用域 <code>u:&lt;email&gt;:&hellip;</code></small
+    >
+  </div>
+</div>
+```
+
+```css
+.ws-map {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  flex-wrap: wrap;
+}
+.ws-map .diagram-card {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 16px 18px;
+  flex: 1;
+  min-width: 220px;
+}
+.ws-map .ws-files,
+.ws-map .ws-rows {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  margin: 4px 0;
+}
+.ws-map .diagram-arrow {
+  font-size: 24px;
 }
 ```
 
+</Diagram>
+
 | Claude代码/Codex              | 代理本机工作区                          |
 | ----------------------------- | --------------------------------------- |
 | 本地磁盘上的文件              | 共享 SQL 数据库中的行                   |
@@ -51,13 +105,61 @@ description: "Claude - 每个用户的代码级自定义 - skills、内存、指
 
 这些路径适用于所有三个范围 - 工作空间、组织/应用程序和个人。当同一路径存在于多个级别时，后面的范围获胜。
 
-```an-diagram title="三个范围，一个有效文件" summary="运行时在读取时解析跨工作区、应用程序和个人范围的相同路径 - 最具体的范围获胜。"
-{
-  "html": "<div class=\"ws-stack\"><div class=\"diagram-card\"><span class=\"diagram-pill\">Workspace</span><small class=\"diagram-muted\">来自 Dispatch 的公司级默认值</small><code>context/brand.md</code></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">组织 / 应用</span><small class=\"diagram-muted\">team override for one app</small><code>context/brand.md</code></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Personal</span><small class=\"diagram-muted\">per-user override &mdash; wins</small><code>context/brand.md</code></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box ok\">Effective <code>context/brand.md</code></div></div>",
-  "css": ".ws-stack{display:flex;flex-direction:column;align-items:flex-start;gap:8px}.ws-stack .diagram-card{display:flex;flex-direction:column;gap:4px;padding:12px 16px;min-width:280px}.ws-stack .diagram-arrow{font-size:20px;align-self:center}.ws-stack code{font-size:.85em}.ws-stack .diagram-box{align-self:center;margin-top:4px}"
+<Diagram id="doc-block-kfdiio" title={"三个范围，一个有效文件"} summary={"运行时在读取时解析跨工作区、应用程序和个人范围的相同路径 - 最具体的范围获胜。"}>
+
+```html
+<div class="ws-stack">
+  <div class="diagram-card">
+    <span class="diagram-pill">Workspace</span
+    ><small class="diagram-muted">来自 Dispatch 的公司级默认值</small
+    ><code>context/brand.md</code>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&darr;</div>
+  <div class="diagram-card">
+    <span class="diagram-pill">组织 / 应用</span
+    ><small class="diagram-muted">team override for one app</small
+    ><code>context/brand.md</code>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&darr;</div>
+  <div class="diagram-card">
+    <span class="diagram-pill accent">Personal</span
+    ><small class="diagram-muted">per-user override &mdash; wins</small
+    ><code>context/brand.md</code>
+  </div>
+  <div class="diagram-arrow diagram-accent" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box ok">Effective <code>context/brand.md</code></div>
+</div>
+```
+
+```css
+.ws-stack {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 8px;
+}
+.ws-stack .diagram-card {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 12px 16px;
+  min-width: 280px;
+}
+.ws-stack .diagram-arrow {
+  font-size: 20px;
+  align-self: center;
+}
+.ws-stack code {
+  font-size: 0.85em;
+}
+.ws-stack .diagram-box {
+  align-self: center;
+  margin-top: 4px;
 }
 ```
 
+</Diagram>
+
 ## 入门：1 分钟演练 {#getting-started}
 
 在 60 秒内更改代理的行为方式。

package/corpus/core/docs/content/locales/zh-CN/writing-agent-instructions.mdx

@@ -7,13 +7,47 @@ description: "如何为代理原生应用或模板编写出色的代理指令：
 
 代理在代理本机应用程序中的行为仅与您给出的说明一样好。三个表面承载该指导：`AGENTS.md`（地图）、skills（深入研究）和操作/工具描述（代理如何选择正确的工具）。写下每一篇都是为了快速检索，而不是为了散文。
 
-```an-diagram title="三个创作表面 + 一个运行时表面" summary="AGENTS.md 和工具描述每回合都会加载；按需加载技能； application_state 由您的 UI 实时编写。"
-{
-  "html": "<div class=\"diagram-surfaces\"><div class=\"diagram-card always\" data-rough><span class=\"diagram-pill accent\">每一轮</span><strong>AGENTS.md</strong><small class=\"diagram-muted\">地图：用途、核心规则、状态键、action + skills 索引</small></div><div class=\"diagram-card always\" data-rough><span class=\"diagram-pill accent\">每一轮</span><strong>工具描述</strong><small class=\"diagram-muted\">驱动工具选择 — 每个工具一句精确说明</small></div><div class=\"diagram-card ondemand\" data-rough><span class=\"diagram-pill\">按需</span><strong>技能</strong><small class=\"diagram-muted\">深度指南，在描述匹配时加载</small></div><div class=\"diagram-card runtime\" data-rough><span class=\"diagram-pill ok\">Live</span><strong>application_state</strong><small class=\"diagram-muted\">由你的 UI 写入：导航、选择、焦点</small></div></div>",
-  "css": ".diagram-surfaces{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:12px}.diagram-surfaces .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px}"
+<Diagram id="doc-block-1xko9t5" title={"三个创作表面 + 一个运行时表面"} summary={"AGENTS.md 和工具描述每回合都会加载；按需加载技能； application_state 由您的 UI 实时编写。"}>
+
+```html
+<div class="diagram-surfaces">
+  <div class="diagram-card always" data-rough>
+    <span class="diagram-pill accent">每一轮</span><strong>AGENTS.md</strong
+    ><small class="diagram-muted"
+      >地图：用途、核心规则、状态键、action + skills 索引</small
+    >
+  </div>
+  <div class="diagram-card always" data-rough>
+    <span class="diagram-pill accent">每一轮</span><strong>工具描述</strong
+    ><small class="diagram-muted">驱动工具选择 — 每个工具一句精确说明</small>
+  </div>
+  <div class="diagram-card ondemand" data-rough>
+    <span class="diagram-pill">按需</span><strong>技能</strong
+    ><small class="diagram-muted">深度指南，在描述匹配时加载</small>
+  </div>
+  <div class="diagram-card runtime" data-rough>
+    <span class="diagram-pill ok">Live</span><strong>application_state</strong
+    ><small class="diagram-muted">由你的 UI 写入：导航、选择、焦点</small>
+  </div>
+</div>
+```
+
+```css
+.diagram-surfaces {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 12px;
+}
+.diagram-surfaces .diagram-card {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 14px 16px;
 }
 ```
 
+</Diagram>
+
 ## 保持 AGENTS.md 小且可浏览 {#small-agents-md}
 
 `AGENTS.md` 作为方向加载。它应该是让代理正确行动的最小事物，所有内容都深入到 skills 中。瞄准这些部分而不是其他部分：

package/corpus/core/docs/content/locales/zh-TW/a2a-protocol.mdx

@@ -20,13 +20,53 @@ A2A 是此框架中跨應用程式委派的基礎 - 最顯著的是 [Dispatch](/
 - **工作** - 每條訊息都會建立一個具有生命週期的工作（已提交、正在工作、已完成、失敗、已取消）
 - **JWT 承載驗證** - 正式環境 A2A 需要 `A2A_SECRET` 或顯式遺留 `apiKeyEnv`
 
-```an-diagram title="一名代理將工作交給另一名代理" summary="郵件代理發現分析代理的卡，傳送 JSON-RPC 訊息，並返回已完成的工作。"
-{
-  "html": "<div class=\"diagram-handoff\"><div class=\"diagram-card\"><strong>郵件 Agent</strong><small class=\"diagram-muted\">needs analytics</small></div><div class=\"diagram-col\"><div class=\"diagram-pill\">GET /.well-known/agent-card.json</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill accent\">POST /_agent-native/a2a<br><small class=\"diagram-muted\">message/send</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&larr;</div><div class=\"diagram-pill ok\">工作 · 已完成</div></div><div class=\"diagram-card\" data-rough><strong>分析 Agent</strong><small class=\"diagram-muted\">執行 run-query，返回結果</small></div></div>",
-  "css": ".diagram-handoff{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.diagram-handoff .diagram-col{display:flex;flex-direction:column;align-items:center;gap:6px}.diagram-handoff .diagram-arrow{font-size:20px;line-height:1}"
+<Diagram id="doc-block-15j0bdh" title={"一名代理將工作交給另一名代理"} summary={"郵件代理發現分析代理的卡，傳送 JSON-RPC 訊息，並返回已完成的工作。"}>
+
+```html
+<div class="diagram-handoff">
+  <div class="diagram-card">
+    <strong>郵件 Agent</strong
+    ><small class="diagram-muted">needs analytics</small>
+  </div>
+  <div class="diagram-col">
+    <div class="diagram-pill">GET /.well-known/agent-card.json</div>
+    <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+    <div class="diagram-pill accent">
+      POST /_agent-native/a2a<br /><small class="diagram-muted"
+        >message/send</small
+      >
+    </div>
+    <div class="diagram-arrow diagram-muted" aria-hidden="true">&larr;</div>
+    <div class="diagram-pill ok">工作 · 已完成</div>
+  </div>
+  <div class="diagram-card" data-rough>
+    <strong>分析 Agent</strong
+    ><small class="diagram-muted">執行 run-query，返回結果</small>
+  </div>
+</div>
+```
+
+```css
+.diagram-handoff {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  flex-wrap: wrap;
+}
+.diagram-handoff .diagram-col {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 6px;
+}
+.diagram-handoff .diagram-arrow {
+  font-size: 20px;
+  line-height: 1;
 }
 ```
 
+</Diagram>
+
 ## 伺服器設定 {#server-setup}
 
 大多數範本透過框架代理聊天外掛取得 A2A。如果您自己安裝它，請在伺服器外掛中呼叫 `mountA2A()`：
@@ -176,14 +216,62 @@ JSON-RPC 2.0 endpoint for `message/send`, `message/stream`, `tasks/get`, and `ta
 
 當使用 `async: true` 呼叫 `message/send` 時，JSON-RPC 處理常式會將工作排入佇列，並將 POST 自觸發到內部 `/_agent-native/a2a/_process-task` 路由，以便處理常式在具有自己的完全超時的新函式執行中執行。該路由使用綁定到工作 ID 的 HMAC 權杖進行驗證（5 分鐘生存期，使用 `A2A_SECRET` 簽名）。它安裝在 `/_agent-native/a2a` JSON-RPC 路由之前，因此 h3 的前綴匹配不會吞噬它。
 
-```an-diagram title="無伺服器上的非同步工作生命週期" summary="async:true 在幾毫秒內返回工作，然後在呼叫者輪詢時重新執行執行代理迴圈。"
-{
-  "html": "<div class=\"diagram-async\"><div class=\"diagram-box\" data-rough>message/send<br><small class=\"diagram-muted\">async: true</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel\"><span class=\"diagram-pill\">enqueue task</span><span class=\"diagram-pill warn\">return working</span><small class=\"diagram-muted\">約毫秒級</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>自觸發 POST /_agent-native/a2a/_process-task<br><small class=\"diagram-muted\">HMAC token · 全新執行 · 完整超時</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-pill\">tasks/get (poll)</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</div><div class=\"diagram-pill ok\">completed</div></div></div>",
-  "css": ".diagram-async{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-async .diagram-panel{display:flex;flex-direction:column;align-items:center;gap:6px}.diagram-async .diagram-col{display:flex;flex-direction:column;align-items:center;gap:6px}.diagram-async .diagram-arrow{font-size:20px;line-height:1}",
-  "caption": "A recurring sweeper re-claims any task left in flight if the function execution dies mid-run."
+<Diagram id="doc-block-1nmyyj6" title={"無伺服器上的非同步工作生命週期"} summary={"async:true 在幾毫秒內返回工作，然後在呼叫者輪詢時重新執行執行代理迴圈。"} caption="A recurring sweeper re-claims any task left in flight if the function execution dies mid-run.">
+
+```html
+<div class="diagram-async">
+  <div class="diagram-box" data-rough>
+    message/send<br /><small class="diagram-muted">async: true</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel">
+    <span class="diagram-pill">enqueue task</span
+    ><span class="diagram-pill warn">return working</span
+    ><small class="diagram-muted">約毫秒級</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&darr;</div>
+  <div class="diagram-box" data-rough>
+    自觸發 POST /_agent-native/a2a/_process-task<br /><small
+      class="diagram-muted"
+      >HMAC token · 全新執行 · 完整超時</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-col">
+    <div class="diagram-pill">tasks/get (poll)</div>
+    <div class="diagram-arrow diagram-muted" aria-hidden="true">&#8635;</div>
+    <div class="diagram-pill ok">completed</div>
+  </div>
+</div>
+```
+
+```css
+.diagram-async {
+  display: flex;
+  align-items: center;
+  gap: 14px;
+  flex-wrap: wrap;
+}
+.diagram-async .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 6px;
+}
+.diagram-async .diagram-col {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 6px;
+}
+.diagram-async .diagram-arrow {
+  font-size: 20px;
+  line-height: 1;
 }
 ```
 
+</Diagram>
+
 > [!IMPORTANT]
 > **無伺服器 Webhook 和閘道超時：**
 > 託管環境閘道（例如 Netlify、Vercel 或 Cloudflare Pages）對面向公眾的 HTTP 路由施加嚴格的執行限制（通常為 10 到 30 秒）。由於代理迴圈可能需要大量時間來執行查詢、取得脈絡和執行工具，因此在呼叫 A2A 端點或處理外部 webhooks 時，您**必須使用 `async: true`**。這會立即將 `working` 狀態返回到 API 閘道，僅保持連線開啟幾毫秒，而自觸發的 `/process-task` POST 在背景執行代理迴圈。不要阻止主 HTTP 請求等待代理迴圈完成。

package/corpus/core/docs/content/locales/zh-TW/actions.mdx

@@ -19,13 +19,72 @@ Actions 是您的應用所做的任何事情的唯一事實來源。使用 `defi
 如果您正在決定是否在聊天中、在聊天中無頭公開操作
 嵌入式 sidecar，或作為完整的應用螢幕，請參閱 [Agent Surfaces](/docs/agent-surfaces)。
 
-```an-diagram title="一個定義，七個消費者" summary="單一 defineAction() 扇出到每個表面 - 代理、UI、HTTP、MCP、A2A 和 CLI - 具有一個經過驗證的模式和一個 run() 主體。"
-{
-  "html": "<div class=\"diagram-fanout\"><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">defineAction()</span><small class=\"diagram-muted\">schema + run()，只定義一次</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-grid\"><div class=\"diagram-node\">Agent 工具<br><small class=\"diagram-muted\">脈絡中的 JSON Schema</small></div><div class=\"diagram-node\">React 鉤子<br><small class=\"diagram-muted\">useActionQuery/Mutation</small></div><div class=\"diagram-node\">callAction()<br><small class=\"diagram-muted\">指令式用戶端</small></div><div class=\"diagram-node\">HTTP<br><small class=\"diagram-muted\">/_agent-native/actions/:name</small></div><div class=\"diagram-node\">MCP 工具<br><small class=\"diagram-muted\">外部主機</small></div><div class=\"diagram-node\">A2A 工具<br><small class=\"diagram-muted\">其他 agent-native 應用</small></div><div class=\"diagram-node\">CLI<br><small class=\"diagram-muted\">pnpm action &lt;name&gt;</small></div></div></div>",
-  "css": ".diagram-fanout{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-fanout .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px 16px}.diagram-fanout .diagram-arrow{font-size:22px;line-height:1}.diagram-fanout .diagram-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:8px}"
+<Diagram id="doc-block-m5p95q" title={"一個定義，七個消費者"} summary={"單一 defineAction() 扇出到每個表面 - 代理、UI、HTTP、MCP、A2A 和 CLI - 具有一個經過驗證的模式和一個 run() 主體。"}>
+
+```html
+<div class="diagram-fanout">
+  <div class="diagram-panel center" data-rough>
+    <span class="diagram-pill accent">defineAction()</span
+    ><small class="diagram-muted">schema + run()，只定義一次</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-grid">
+    <div class="diagram-node">
+      Agent 工具<br /><small class="diagram-muted">脈絡中的 JSON Schema</small>
+    </div>
+    <div class="diagram-node">
+      React 鉤子<br /><small class="diagram-muted"
+        >useActionQuery/Mutation</small
+      >
+    </div>
+    <div class="diagram-node">
+      callAction()<br /><small class="diagram-muted">指令式用戶端</small>
+    </div>
+    <div class="diagram-node">
+      HTTP<br /><small class="diagram-muted"
+        >/_agent-native/actions/:name</small
+      >
+    </div>
+    <div class="diagram-node">
+      MCP 工具<br /><small class="diagram-muted">外部主機</small>
+    </div>
+    <div class="diagram-node">
+      A2A 工具<br /><small class="diagram-muted">其他 agent-native 應用</small>
+    </div>
+    <div class="diagram-node">
+      CLI<br /><small class="diagram-muted">pnpm action &lt;name&gt;</small>
+    </div>
+  </div>
+</div>
+```
+
+```css
+.diagram-fanout {
+  display: flex;
+  align-items: center;
+  gap: 14px;
+  flex-wrap: wrap;
+}
+.diagram-fanout .center {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+  padding: 14px 16px;
+}
+.diagram-fanout .diagram-arrow {
+  font-size: 22px;
+  line-height: 1;
+}
+.diagram-fanout .diagram-grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 8px;
 }
 ```
 
+</Diagram>
+
 如果 UI 和代理都需要做某事，請採取行動 - 而不是自訂
 路由。對於何時路由型協議才是正確的呼叫，請參閱[首選 Actions
 對於應用程式操作](/docs/server#actions-first)。