@agent-native/core 0.79.26 → 0.80.0

package/corpus/core/docs/content/locales/zh-TW/durable-background-runs.mdx

@@ -15,13 +15,64 @@ description: "長時間的代理聊天回合可以在獨立的 15 分鐘 Netlify
 
 已部署的應用正好有兩個伺服器函式，幾乎所有請求都會打到第一個。只有被分派的代理回合會在第二個函式上執行。
 
-```an-diagram title="server 處理所有事；只有被分派的代理回合在背景函式上執行" summary="同步 server 函式提供頁面、actions、API 和前景聊天 POST；它會用 HMAC 將長回合分派到有 15 分鐘預算的背景函式。"
-{
-  "html": "<div class=\"diagram-bg-runs\"><div class=\"diagram-panel\" data-rough><div class=\"diagram-pill\">server &middot; synchronous</div><div class=\"diagram-box\">頁面 / SSR</div><div class=\"diagram-box\">Actions</div><div class=\"diagram-box\">API + 框架路由</div><div class=\"diagram-box\">前景聊天 POST <small class=\"diagram-muted\">決定 + 分派</small></div><small class=\"diagram-muted\">約 10 秒逾時 &middot; 幾乎所有請求</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;<br><small>HMAC 202</small></div><div class=\"diagram-panel\" data-rough><div class=\"diagram-pill accent\">server-agent-background &middot; background:true</div><div class=\"diagram-box\">_process-run worker</div><div class=\"diagram-box\">代理回合：LLM + 工具呼叫</div><small class=\"diagram-ok\">15 分鐘預算 &middot; 僅限被分派的回合</small></div></div>",
-  "css": ".diagram-bg-runs{display:flex;align-items:stretch;gap:14px;flex-wrap:wrap}.diagram-bg-runs .diagram-panel{display:flex;flex-direction:column;gap:8px;padding:14px;flex:1;min-width:230px}.diagram-bg-runs .diagram-box{padding:8px 10px}.diagram-bg-runs .diagram-arrow{display:flex;flex-direction:column;justify-content:center;text-align:center;min-width:90px;font-size:20px}"
+<Diagram id="doc-block-1ighlhe" title={"server 處理所有事；只有被分派的代理回合在背景函式上執行"} summary={"同步 server 函式提供頁面、actions、API 和前景聊天 POST；它會用 HMAC 將長回合分派到有 15 分鐘預算的背景函式。"}>
+
+```html
+<div class="diagram-bg-runs">
+  <div class="diagram-panel" data-rough>
+    <div class="diagram-pill">server &middot; synchronous</div>
+    <div class="diagram-box">頁面 / SSR</div>
+    <div class="diagram-box">Actions</div>
+    <div class="diagram-box">API + 框架路由</div>
+    <div class="diagram-box">
+      前景聊天 POST <small class="diagram-muted">決定 + 分派</small>
+    </div>
+    <small class="diagram-muted">約 10 秒逾時 &middot; 幾乎所有請求</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">
+    &rarr;<br /><small>HMAC 202</small>
+  </div>
+  <div class="diagram-panel" data-rough>
+    <div class="diagram-pill accent">
+      server-agent-background &middot; background:true
+    </div>
+    <div class="diagram-box">_process-run worker</div>
+    <div class="diagram-box">代理回合：LLM + 工具呼叫</div>
+    <small class="diagram-ok">15 分鐘預算 &middot; 僅限被分派的回合</small>
+  </div>
+</div>
+```
+
+```css
+.diagram-bg-runs {
+  display: flex;
+  align-items: stretch;
+  gap: 14px;
+  flex-wrap: wrap;
+}
+.diagram-bg-runs .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 14px;
+  flex: 1;
+  min-width: 230px;
+}
+.diagram-bg-runs .diagram-box {
+  padding: 8px 10px;
+}
+.diagram-bg-runs .diagram-arrow {
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  text-align: center;
+  min-width: 90px;
+  font-size: 20px;
 }
 ```
 
+</Diagram>
+
 應用或範本程式碼中**沒有任何需要標記的地方**。當函式的 `export const config` 含有 `background: true`（或函式名稱以 `-background` 結尾）時，Netlify 就會把它視為背景函式。啟用此功能時，框架的建置步驟會自動產生 `server-agent-background` 包裝器；應用作者不需要自行宣告。
 
 ## 背景中會執行什麼，以及如何選擇 {#what-runs}
@@ -40,13 +91,42 @@ description: "長時間的代理聊天回合可以在獨立的 15 分鐘 Netlify
 
 Netlify async function 會在**排入**呼叫的瞬間回傳 `202`；這不代表 worker 已實際執行。因此前景不會盲目相信 `202`：分派後會短暫輪詢，確認 worker 是否真的**認領**該 run；若沒有認領，前景會在線上同步復原。
 
-```an-diagram title="前景一律回傳可運作的回合" summary="分派時，前景會等待一段寬限時間讓 worker 認領 run；若認領成功，前景會訂閱它；若未認領，前景會自行認領並在線上同步執行該回合。"
-{
-  "html": "<div class=\"diagram-bg-life\"><div class=\"diagram-box\" data-rough>前景 POST</div><div class=\"diagram-arrow diagram-muted\">&rarr;</div><div class=\"diagram-box\" data-rough>插入 run + HMAC 分派 &rarr; 202</div><div class=\"diagram-arrow diagram-muted\">&rarr;</div><div class=\"diagram-panel center\" data-rough><strong>Worker 是否在寬限時間內認領？</strong><small class=\"diagram-ok\">是 &rarr; 串流背景 worker（最多 15 分鐘）</small><small class=\"diagram-warn\">否 &rarr; 斷路器在線上同步復原該回合</small></div></div>",
-  "css": ".diagram-bg-life{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-bg-life .diagram-arrow{font-size:20px}.diagram-bg-life .center{display:flex;flex-direction:column;gap:4px;padding:12px}"
+<Diagram id="doc-block-n3furk" title={"前景一律回傳可運作的回合"} summary={"分派時，前景會等待一段寬限時間讓 worker 認領 run；若認領成功，前景會訂閱它；若未認領，前景會自行認領並在線上同步執行該回合。"}>
+
+```html
+<div class="diagram-bg-life">
+  <div class="diagram-box" data-rough>前景 POST</div>
+  <div class="diagram-arrow diagram-muted">&rarr;</div>
+  <div class="diagram-box" data-rough>插入 run + HMAC 分派 &rarr; 202</div>
+  <div class="diagram-arrow diagram-muted">&rarr;</div>
+  <div class="diagram-panel center" data-rough>
+    <strong>Worker 是否在寬限時間內認領？</strong
+    ><small class="diagram-ok">是 &rarr; 串流背景 worker（最多 15 分鐘）</small
+    ><small class="diagram-warn">否 &rarr; 斷路器在線上同步復原該回合</small>
+  </div>
+</div>
+```
+
+```css
+.diagram-bg-life {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.diagram-bg-life .diagram-arrow {
+  font-size: 20px;
+}
+.diagram-bg-life .center {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 12px;
 }
 ```
 
+</Diagram>
+
 認領會透過 `dispatch_mode` 從 `background` 變成 `background-processing` 來觀察（只有 worker 的原子認領會這樣做）。寬限時間必須涵蓋 worker 冷啟動；較重的應用曾觀察到需要比原本 8 秒更久，因此目前是 **15 秒**（仍在前景約 40 秒軟逾時內）。如果 worker 從未認領，無論是故障或只是啟動太慢，都會在寬限時間後回退到線上同步執行，所以該回合仍會完成；代價是先等待寬限時間所增加的延遲。
 
 <Callout id="doc-block-1xjyvdm" tone="success">

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

@@ -13,13 +13,54 @@ description: "當託管代理執行被中斷並恢復時，已完成的副作用
 
 持久的簡歷彌補了這一差距。恢復時，框架知道哪個副作用工具呼叫已經完成，並拒絕在兩層重新執行它們。
 
-```an-diagram title="兩層可阻止簡歷上重複的副作用" summary="記錄讀取持久帳本並對之前的呼叫進行分類；第 1 層告訴模型，第 2 層硬阻止與已完成條目匹配的重新分派寫入。"
-{
-  "html": "<div class=\"diagram-durable\"><div class=\"diagram-box\" data-rough>Run-event ledger<br><small class=\"diagram-muted\">tool_start / tool_done</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><strong>Tool-call journal</strong><small class=\"diagram-ok\">completed = start+done</small><small class=\"diagram-warn\">interrupted = start, no done</small></div><div class=\"diagram-col\"><div class=\"diagram-pill\">Layer 1 · prompt note &rarr; model</div><div class=\"diagram-pill accent\">第 2 層 · 硬阻塞重新派發寫入</div></div></div>",
-  "css": ".diagram-durable{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-durable .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-durable .diagram-arrow{font-size:22px;line-height:1}.diagram-durable .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+<Diagram id="doc-block-1stduqo" title={"兩層可阻止簡歷上重複的副作用"} summary={"記錄讀取持久帳本並對之前的呼叫進行分類；第 1 層告訴模型，第 2 層硬阻止與已完成條目匹配的重新分派寫入。"}>
+
+```html
+<div class="diagram-durable">
+  <div class="diagram-box" data-rough>
+    Run-event ledger<br /><small class="diagram-muted"
+      >tool_start / tool_done</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel center" data-rough>
+    <strong>Tool-call journal</strong
+    ><small class="diagram-ok">completed = start+done</small
+    ><small class="diagram-warn">interrupted = start, no done</small>
+  </div>
+  <div class="diagram-col">
+    <div class="diagram-pill">Layer 1 · prompt note &rarr; model</div>
+    <div class="diagram-pill accent">第 2 層 · 硬阻塞重新派發寫入</div>
+  </div>
+</div>
+```
+
+```css
+.diagram-durable {
+  display: flex;
+  align-items: center;
+  gap: 14px;
+  flex-wrap: wrap;
+}
+.diagram-durable .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+.diagram-durable .diagram-arrow {
+  font-size: 22px;
+  line-height: 1;
+}
+.diagram-durable .center {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
 }
 ```
 
+</Diagram>
+
 ## 工具呼叫記錄 {#journal}
 
 記錄是**對持久執行事件分類帳的純粹讀取** - 熱路徑中沒有新的紀錄掛鉤。它對目前回合已紀錄的工具呼叫進行分類：

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

@@ -11,13 +11,56 @@ description: "使用頁面脈絡和主機指令將 Agent-Native sidecar 嵌入
 嵌入式邊車，或完整的應用程式，從
 [Agent Surfaces](/docs/agent-surfaces).
 
-```an-diagram title="包埋膜" summary="主機應用程式提供伺服器端驗證和即時頁面脈絡； Agent-Native 執行持久 sidecar 並透過用戶端操作和主機指令到達開啟的分頁。"
-{
-  "html": "<div class=\"diagram-embed\"><div class=\"diagram-box\" data-rough><strong>主機 SaaS 應用</strong><small class=\"diagram-muted\">你的介面，你的認證</small></div><div class=\"diagram-col\"><div class=\"diagram-pill accent\">getContext &rarr;</div><div class=\"diagram-pill\">&larr; 用戶端操作</div><div class=\"diagram-pill\">&larr; 主機指令</div></div><div class=\"diagram-panel center\" data-rough><strong>Agent-Native sidecar</strong><small class=\"diagram-muted\">持久聊天 · 應用狀態 · 擴充功能</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>SQL<br><small class=\"diagram-muted\">框架表</small></div></div>",
-  "css": ".diagram-embed{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-embed .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-embed .diagram-arrow{font-size:22px;line-height:1}.diagram-embed .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+<Diagram id="doc-block-g4vq16" title={"包埋膜"} summary={"主機應用程式提供伺服器端驗證和即時頁面脈絡； Agent-Native 執行持久 sidecar 並透過用戶端操作和主機指令到達開啟的分頁。"}>
+
+```html
+<div class="diagram-embed">
+  <div class="diagram-box" data-rough>
+    <strong>主機 SaaS 應用</strong
+    ><small class="diagram-muted">你的介面，你的認證</small>
+  </div>
+  <div class="diagram-col">
+    <div class="diagram-pill accent">getContext &rarr;</div>
+    <div class="diagram-pill">&larr; 用戶端操作</div>
+    <div class="diagram-pill">&larr; 主機指令</div>
+  </div>
+  <div class="diagram-panel center" data-rough>
+    <strong>Agent-Native sidecar</strong
+    ><small class="diagram-muted">持久聊天 · 應用狀態 · 擴充功能</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box" data-rough>
+    SQL<br /><small class="diagram-muted">框架表</small>
+  </div>
+</div>
+```
+
+```css
+.diagram-embed {
+  display: flex;
+  align-items: center;
+  gap: 14px;
+  flex-wrap: wrap;
+}
+.diagram-embed .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+.diagram-embed .diagram-arrow {
+  font-size: 22px;
+  line-height: 1;
+}
+.diagram-embed .center {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
 }
 ```
 
+</Diagram>
+
 ## 從這裡開始：包含電池的外掛 {#batteries-included}
 
 對於大多數 SaaS 主機，**使用完整的嵌入式執行時** - 伺服器外掛
@@ -373,13 +416,45 @@ const hostTools = createAgentNativeHostTools({
 
 對於 CLAW 風格的同事，iframe 還可以向 sidecar 後端註冊其即時瀏覽器分頁。然後，代理取得正常的後端工具，將請求排入佇列，iframe 聲明它，主機頁面執行它，後端將結果返回給代理。
 
-```an-diagram title="伺服器介導的瀏覽器工作階段橋" summary="後端工具將工作排隊；註冊的分頁聲明它，在即時頁面上執行它，並將結果返回給代理 - 因此 backend/Slack/A2A 代理仍然可以觸摸開啟的分頁。"
-{
-  "html": "<div class=\"diagram-bridge\"><div class=\"diagram-node\" data-rough>後端代理<br><small class=\"diagram-muted\">聊天 · Slack · A2A</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>enqueue request<br><small class=\"diagram-muted\">/_agent-native/browser-sessions</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\" data-rough>活動標籤頁面接管它<br><small class=\"diagram-muted\">registered bridge</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill ok\">result &rarr; agent</div></div>",
-  "css": ".diagram-bridge{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-bridge .diagram-arrow{font-size:22px;line-height:1}"
+<Diagram id="doc-block-m1fbf9" title={"伺服器介導的瀏覽器工作階段橋"} summary={"後端工具將工作排隊；註冊的分頁聲明它，在即時頁面上執行它，並將結果返回給代理 - 因此 backend/Slack/A2A 代理仍然可以觸摸開啟的分頁。"}>
+
+```html
+<div class="diagram-bridge">
+  <div class="diagram-node" data-rough>
+    後端代理<br /><small class="diagram-muted">聊天 · Slack · A2A</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box" data-rough>
+    enqueue request<br /><small class="diagram-muted"
+      >/_agent-native/browser-sessions</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-node" data-rough>
+    活動標籤頁面接管它<br /><small class="diagram-muted"
+      >registered bridge</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-pill ok">result &rarr; agent</div>
+</div>
+```
+
+```css
+.diagram-bridge {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.diagram-bridge .diagram-arrow {
+  font-size: 22px;
+  line-height: 1;
 }
 ```
 
+</Diagram>
+
 在 sidecar 應用程式中，當 iframe 安裝時啟動一次瀏覽器工作階段橋：
 
 ```tsx

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

@@ -14,13 +14,59 @@ description: "編寫 *.eval.ts 測試用例，根據固定輸入執行真實代
 
 執行程式從現有註冊表中解析與提供者無關的引擎/模型 - 沒有模型被硬編碼 - 因此相同的套件可以針對應用程式設定的任何引擎執行。
 
-```an-diagram title="從固定輸入到部署門" summary="跑步者實際上在每種情況下執行代理迴圈，對輸出進行評分，如果任何評分者低於閾值，則以非零值退出——使其成為一個插入式 CI 門。"
-{
-  "html": "<div class=\"eval-flow\"><div class=\"diagram-node\">*.eval.ts<br><small class=\"diagram-muted\">prompt + expected behavior</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">執行代理迴圈<br><small class=\"diagram-muted\">real engine/model</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">Scorers<br><small class=\"diagram-muted\">every one must pass threshold</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box ok\">exit 0 &rarr; deploy</div><div class=\"diagram-box warn\">exit 1 &rarr; block</div></div></div>",
-  "css": ".eval-flow{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.eval-flow .diagram-node{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.eval-flow .diagram-col{display:flex;flex-direction:column;gap:8px}.eval-flow .diagram-arrow{font-size:22px;line-height:1}"
+<Diagram id="doc-block-11tr03g" title={"從固定輸入到部署門"} summary={"跑步者實際上在每種情況下執行代理迴圈，對輸出進行評分，如果任何評分者低於閾值，則以非零值退出——使其成為一個插入式 CI 門。"}>
+
+```html
+<div class="eval-flow">
+  <div class="diagram-node">
+    *.eval.ts<br /><small class="diagram-muted"
+      >prompt + expected behavior</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-node">
+    執行代理迴圈<br /><small class="diagram-muted">real engine/model</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-node">
+    Scorers<br /><small class="diagram-muted"
+      >every one must pass threshold</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-col">
+    <div class="diagram-box ok">exit 0 &rarr; deploy</div>
+    <div class="diagram-box warn">exit 1 &rarr; block</div>
+  </div>
+</div>
+```
+
+```css
+.eval-flow {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.eval-flow .diagram-node {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  padding: 10px 14px;
+}
+.eval-flow .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+.eval-flow .diagram-arrow {
+  font-size: 22px;
+  line-height: 1;
 }
 ```
 
+</Diagram>
+
 ## 編寫評估 {#writing}
 
 將 `*.eval.ts` 檔案拖放到應用程式中的任意位置（或 `evals/*.ts` 檔案）。每個檔案 `export default defineEval(...)` （或匯出它們的陣列）：
@@ -80,13 +126,59 @@ interface AgentRunOutput {
 
 `createScorer` 從 Mastra 風格的 4 步管道建置一個記分器。僅需要 `generateScore`：
 
-```an-diagram title="4 步評分管道" summary="預處理和分析預設身分；僅需要generateScore。 analyze 可以執行普通 JS 或透過 ctx 呼叫 LLM 判斷。"
-{
-  "html": "<div class=\"scorer\"><div class=\"diagram-card\"><span class=\"diagram-pill\">preprocess(run)</span><small class=\"diagram-muted\">transform the run/output &middot; optional</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">analyze(x, ctx)</span><small class=\"diagram-muted\">plain JS or LLM judge &middot; optional</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">generateScore(a)</span><small class=\"diagram-muted\">&rarr; 0..1 normalized &middot; <strong>required</strong></small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">generateReason</span><small class=\"diagram-muted\">human-readable why &middot; optional</small></div></div>",
-  "css": ".scorer{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.scorer .diagram-card{display:flex;flex-direction:column;gap:2px;padding:8px 12px}.scorer .diagram-arrow{font-size:20px;line-height:1}"
+<Diagram id="doc-block-y7b0ne" title={"4 步評分管道"} summary={"預處理和分析預設身分；僅需要generateScore。 analyze 可以執行普通 JS 或透過 ctx 呼叫 LLM 判斷。"}>
+
+```html
+<div class="scorer">
+  <div class="diagram-card">
+    <span class="diagram-pill">preprocess(run)</span
+    ><small class="diagram-muted"
+      >transform the run/output &middot; optional</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-card">
+    <span class="diagram-pill">analyze(x, ctx)</span
+    ><small class="diagram-muted"
+      >plain JS or LLM judge &middot; optional</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-card">
+    <span class="diagram-pill accent">generateScore(a)</span
+    ><small class="diagram-muted"
+      >&rarr; 0..1 normalized &middot; <strong>required</strong></small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-card">
+    <span class="diagram-pill">generateReason</span
+    ><small class="diagram-muted">human-readable why &middot; optional</small>
+  </div>
+</div>
+```
+
+```css
+.scorer {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  flex-wrap: wrap;
+}
+.scorer .diagram-card {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  padding: 8px 12px;
+}
+.scorer .diagram-arrow {
+  font-size: 20px;
+  line-height: 1;
 }
 ```
 
+</Diagram>
+
 ```text
 preprocess(run)     → x          transform the run/output (optional)
 analyze(x, ctx)     → analysis   plain JS OR an LLM judge (optional)

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

@@ -22,13 +22,75 @@ description: "使用者在範本內建置的迷你應用程式 - Analytics 中
 面向代理的分機 actions 和提示指導，同時留下其餘部分
 應用程式代理完好無損。
 
-```an-diagram title="沙盒橋" summary="擴充功能 HTML 在隔離的 iframe 中執行，僅透過一組固定的橋接助手到達主機 - 每個呼叫都經過範圍和存取檢查。"
-{
-  "html": "<div class=\"ext-bridge\"><div class=\"diagram-card sandbox\" data-rough><span class=\"diagram-pill warn\">Sandboxed iframe</span><small class=\"diagram-muted\">Alpine.js HTML &middot; no host cookies, session, or DOM</small><div class=\"ext-helpers\"><span class=\"diagram-pill\">appAction</span><span class=\"diagram-pill\">appFetch</span><span class=\"diagram-pill\">dbQuery / dbExec</span><span class=\"diagram-pill\">extensionData</span><span class=\"diagram-pill\">extensionFetch</span></div></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&harr;</div><div class=\"diagram-col\"><div class=\"diagram-box\">主機範本<br><small class=\"diagram-muted\">actions，自動限定作用域的 SQL</small></div><div class=\"diagram-box\">Secret proxy<br><small class=\"diagram-muted\"><code>${keys.NAME}</code>，鎖定域名</small></div><div class=\"diagram-box\">外部 API<br><small class=\"diagram-muted\">僅透過 extensionFetch</small></div></div></div>",
-  "css": ".ext-bridge{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.ext-bridge .sandbox{display:flex;flex-direction:column;gap:8px;padding:16px 18px;flex:1;min-width:240px}.ext-bridge .ext-helpers{display:flex;flex-wrap:wrap;gap:6px;margin-top:4px}.ext-bridge .diagram-col{display:flex;flex-direction:column;gap:8px}.ext-bridge .diagram-arrow{font-size:24px}"
+<Diagram id="doc-block-7osdxe" title={"沙盒橋"} summary={"擴充功能 HTML 在隔離的 iframe 中執行，僅透過一組固定的橋接助手到達主機 - 每個呼叫都經過範圍和存取檢查。"}>
+
+```html
+<div class="ext-bridge">
+  <div class="diagram-card sandbox" data-rough>
+    <span class="diagram-pill warn">Sandboxed iframe</span
+    ><small class="diagram-muted"
+      >Alpine.js HTML &middot; no host cookies, session, or DOM</small
+    >
+    <div class="ext-helpers">
+      <span class="diagram-pill">appAction</span
+      ><span class="diagram-pill">appFetch</span
+      ><span class="diagram-pill">dbQuery / dbExec</span
+      ><span class="diagram-pill">extensionData</span
+      ><span class="diagram-pill">extensionFetch</span>
+    </div>
+  </div>
+  <div class="diagram-arrow diagram-accent" aria-hidden="true">&harr;</div>
+  <div class="diagram-col">
+    <div class="diagram-box">
+      主機範本<br /><small class="diagram-muted"
+        >actions，自動限定作用域的 SQL</small
+      >
+    </div>
+    <div class="diagram-box">
+      Secret proxy<br /><small class="diagram-muted"
+        ><code>${keys.NAME}</code>，鎖定域名</small
+      >
+    </div>
+    <div class="diagram-box">
+      外部 API<br /><small class="diagram-muted">僅透過 extensionFetch</small>
+    </div>
+  </div>
+</div>
+```
+
+```css
+.ext-bridge {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  flex-wrap: wrap;
+}
+.ext-bridge .sandbox {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 16px 18px;
+  flex: 1;
+  min-width: 240px;
+}
+.ext-bridge .ext-helpers {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  margin-top: 4px;
+}
+.ext-bridge .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+.ext-bridge .diagram-arrow {
+  font-size: 24px;
 }
 ```
 
+</Diagram>
+
 擴充功能也可以**在本機檔案模式下由儲存庫支援**。在該工作流程中，
 `agent-native.json`聲明一個`extensions`資料夾，每個擴充功能都有一個
 `extension.json` 清單加上 HTML 條目檔案，應用程式渲染這些
@@ -220,14 +282,54 @@ description: "使用者在範本內建置的迷你應用程式 - Analytics 中
 
 當擴充功能**安裝到插槽中**時，主機會將相關脈絡（聯絡人的電子郵件、儀表板 ID、事件 ID）推送到 iframe 中。該擴充功能讀取 `window.slotContext` 來了解使用者正在看什麼。
 
-```an-diagram title="插槽將脈絡推送到小工具中" summary="主機範本擁有命名槽；將擴充功能安裝到其中，可以為使用者目前正在檢視的任何內容提供 window.slotContext 。"
-{
-"html": "<div class=\"slot\"><div class=\"diagram-card\"><span class=\"diagram-pill\">郵件對話串</span><small class=\"diagram-muted\">slot <code>mail.contact-sidebar.bottom</code></small></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box accent\"><code>window.slotContext</code><br><small class=\"diagram-muted\">{ contactEmail }</small></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">聯絡人備註</span><small class=\"diagram-muted\">loads notes for that contact &mdash; same widget, different context</small></div></div>",
-"css": ".slot{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.slot .diagram-card{display:flex;flex-direction:column;gap:4px;padding:14px 16px;min-width:180px}.slot .diagram-arrow{font-size:22px}"
-}
+<Diagram id="doc-block-1lwnufh" title={"插槽將脈絡推送到小工具中"} summary={"主機範本擁有命名槽；將擴充功能安裝到其中，可以為使用者目前正在檢視的任何內容提供 window.slotContext 。"}>
+
+```html
+<div class="slot">
+  <div class="diagram-card">
+    <span class="diagram-pill">郵件對話串</span
+    ><small class="diagram-muted"
+      >slot <code>mail.contact-sidebar.bottom</code></small
+    >
+  </div>
+  <div class="diagram-arrow diagram-accent" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box accent">
+    <code>window.slotContext</code><br /><small class="diagram-muted"
+      >{ contactEmail }</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-accent" aria-hidden="true">&rarr;</div>
+  <div class="diagram-card">
+    <span class="diagram-pill">聯絡人備註</span
+    ><small class="diagram-muted"
+      >loads notes for that contact &mdash; same widget, different
+      context</small
+    >
+  </div>
+</div>
+```
 
+```css
+.slot {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.slot .diagram-card {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 14px 16px;
+  min-width: 180px;
+}
+.slot .diagram-arrow {
+  font-size: 22px;
+}
 ```
 
+</Diagram>
+
 ### 具體範例
 
 想象一下圖庫中的聯絡人備註擴充功能。就其本身而言，它是一個獨立的小工具。要使其顯示在郵件聯絡人側邊欄中：