@agent-native/core 0.79.2 → 0.79.5

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

@@ -0,0 +1,155 @@
+---
+title: "CI 評估門"
+description: "編寫 *.eval.ts 測試用例，根據固定輸入執行真實代理，使用可組合評分器對輸出進行評分，並在閾值上控制 CI/部署。"
+---
+
+# CI 評估門
+
+評估是一流的測試原語：您聲明一個提示加上您期望的行為，執行程序**實際上針對該輸入執行代理循環**，使用可組合評分器對輸出進行評分，如果任何情況得分低於其閾值，則以非零值退出。這種非零退出使 `agent-native eval` 成為一個嵌入式 CI 部署入口。
+
+這是對 [Observability](/docs/observability) 中事後評分的補充：
+
+- **可觀測性評估** (`observability/evals.ts`) — _“這次實際執行效果如何？”_ 被動、采樣、緊鄰痕跡。
+- **`*.eval.ts`（此原語）** — _“代理在此固定輸入上執行正確的操作嗎？”_ 主動、確定性、通過 CLI 執行的 CI 門。
+
+執行程序從現有註冊表中解析與提供者無關的引擎/模型 - 沒有模型被硬編碼 - 因此相同的套件可以針對應用程式設定的任何引擎執行。
+
+```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}"
+}
+```
+
+## 編寫評估 {#writing}
+
+將 `*.eval.ts` 檔案拖放到應用程式中的任意位置（或 `evals/*.ts` 檔案）。每個檔案 `export default defineEval(...)` （或匯出它們的陣列）：
+
+```ts
+// evals/greeting.eval.ts
+import { defineEval, contains, llmJudge } from "@agent-native/core/eval";
+
+export default defineEval({
+  name: "greets the user by name",
+  input: { prompt: "Say hi to Ada." },
+  threshold: 0.7, // per-scorer pass bar; default 0.5
+  scorers: [
+    contains("Ada"),
+    llmJudge({ criteria: "friendliness", rubric: "1.0 = warm greeting" }),
+  ],
+});
+```
+
+只有當**每個**得分者都達到閾值時，評估才會通過。關鍵 `defineEval` 欄位：
+
+| 欄位        | 型別                  | 注釋                                             |
+| ----------- | --------------------- | ------------------------------------------------ |
+| `name`      | 字串                  | 必填。報告中顯示。                               |
+| `input`     | `{ prompt, history }` | 需要`prompt`；可選的先前 `{ role, text }` 轉彎。 |
+| `scorers`   | `Scorer[]`            | 必填，至少一個。                                 |
+| `threshold` | 數字`0..1`            | 每個得分手的傳球杆。預設`0.5`；可從 CLI 覆蓋。   |
+| `run`       | 功能                  | 自訂設定的可選覆蓋（種子資料、多輪）。           |
+
+交給記分員的代理執行很小並且與傳輸無關：
+
+```ts
+interface AgentRunOutput {
+  text: string; // concatenated assistant text
+  toolCalls: readonly string[]; // tool/action names, in call order
+  ok: boolean; // completed without a terminal error
+  error?: string;
+  runId: string;
+  durationMs: number;
+}
+```
+
+## 內置記分器 {#built-in}
+
+從 `@agent-native/core/eval` 匯入：
+
+| 得分手                   | 得分                                                  | 型號？ |
+| ------------------------ | ----------------------------------------------------- | ------ |
+| `exactMatch(expected)`   | `1.0` 如果文本等於 `expected`（已修剪，不區分大小寫） | 沒有   |
+| `contains(needles)`      | 存在所需子字串的分數（因此部分命中）                  | 不     |
+| `usesTool(toolName)`     | `1.0`（如果代理調用該工具/操作至少一次）              | 否     |
+| `llmJudge({ criteria })` | LLM 作為評委根據自然語言評分標準進行評分，→ `0..1`    | 是     |
+
+`exactMatch` 和 `contains` 采用可選的 `{ caseSensitive }`。 `llmJudge` 采用 `{ criteria, rubric?, name?, scoreRange? }` - 其輸出標準化為 `[0, 1]`，判斷模型是執行程序解析的任何內容（絕不是硬編碼的提供程序）。
+
+## 自訂評分器：4 步流程 {#custom}
+
+`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}"
+}
+```
+
+```text
+preprocess(run)     → x          transform the run/output (optional)
+analyze(x, ctx)     → analysis   plain JS OR an LLM judge (optional)
+generateScore(a)    → 0..1       REQUIRED, normalized
+generateReason(...) → string     human-readable why (optional)
+```
+
+`preprocess` 和 `analyze` 預設為身分（記分員看到原始 `AgentRunOutput`）。 `analyze` 步驟接收 `ctx` 以及與提供者無關的 `judge()` 幫助程序，用於 LLM 支持的評分：
+
+```ts
+import { createScorer, clamp01 } from "@agent-native/core/eval";
+
+// A scorer that rewards short, tool-using answers.
+const concise = createScorer({
+  name: "concise_with_tool",
+  analyze(run) {
+    return {
+      words: run.text.trim().split(/\s+/).length,
+      usedTool: run.toolCalls.length > 0,
+    };
+  },
+  generateScore({ words, usedTool }) {
+    if (!usedTool) return 0;
+    return clamp01(1 - Math.max(0, words - 40) / 200);
+  },
+  generateReason({ analysis }) {
+    return `${analysis.words} words, tool used: ${analysis.usedTool}`;
+  },
+});
+```
+
+## 執行大門 {#cli}
+
+```bash
+agent-native eval                    # run every *.eval.ts; non-zero exit on failure
+agent-native eval billing            # 僅路徑包含“billing”的檔案
+agent-native eval --json             # machine-readable report (for CI)
+agent-native eval --threshold 0.8    # override every eval's pass threshold (0..1)
+```
+
+該指令在目前應用程式下發現 `**/*.eval.ts` 和 `evals/*.ts`，為每個輸入執行代理，對其進行評分，列印可讀表格（或 JSON），並且**如果任何評估得分低於其閾值**則以非零值退出。
+
+退出程式碼：
+
+| 程式碼 | 含義                                                  |
+| ------ | ----------------------------------------------------- |
+| `0`    | 所有評估均已通過 - *或*未找到評估檔案（CI 友好）。    |
+| `1`    | 至少有一項評估得分低於閾值，或者套件出錯。            |
+| `2`    | 錯誤的參數（例如 `--threshold` 位於 `[0, 1]` 之外）。 |
+
+### 作為 CI 部署門 {#ci}
+
+將其新增到部署之前執行的管道：
+
+```yaml
+# .github/workflows/deploy.yml (excerpt)
+- run: npx agent-native eval --json
+```
+
+將任何評分器降低到閾值以下的回歸會導致該步驟失敗並阻止部署。沒有評估檔案的應用程式會退出 `0`，因此采用評估是每個應用程式的選取。
+
+## 下一步是什么
+
+- [**Observability**](/docs/observability) - 實際正式環境執行的事後評分（補充層）
+- [**Actions**](/docs/actions) — `toolCalls` 中顯示的工具/actions
+- [**Agent Teams**](/docs/agent-teams) — 評估可能執行的子代理

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

@@ -0,0 +1,360 @@
+---
+title: "擴充功能"
+description: "使用者在範本內建置的迷你應用程式 - Analytics 中的自訂 KPI 磁貼、行事曆中的會議準備清單、郵件中的聯系人 CRM 小部件。無需部署，無需編輯程式碼，無需更改架構。"
+---
+
+# 擴充功能
+
+擴充功能是**使用者在範本內建置的迷你應用程式**。
+
+如果您使用過 QuickBooks Online，您就會看到該模型：QBO 提供核心會計產品，使用者可以使用小型自訂小部件（自訂報告、工資計算器、稅收規則檢查器），這些小部件位於同一個應用程式內並使用相同的資料。擴充功能是該想法的代理本機版本，只不過您的使用者不編寫任何程式碼。他們描述他們想要什么，然後代理建置它。
+
+框架很重要：擴充功能不是通用的“做你想做的”沙箱。它是一個**迷你應用程式，擴充功能了特定範本**（郵件、分析、行事曆、剪輯、設計）並使用該範本的 actions 和資料。郵件擴充功能可以讀取電子郵件。 Analytics 擴充功能讀取儀表板的指標。行事曆擴充功能作用於開啟的事件。它們感覺像是主機產品的一部分，因為它們*是*主機產品的一部分。
+
+使擴充功能發揮作用的三件事：
+
+- **無需程式碼，無需部署。** 代理編寫它們並且它們在幾秒鐘內即可生效。存儲在資料庫中，而不是儲存庫中。
+- **對範本資料的完全存取權限。**擴充功能可以調用代理調用的相同 actions - 郵件中的 `list-emails`、幻燈片中的 `list-decks`、剪輯中的 `list-recordings` - 因此它們擁有主機應用程式擁有的一切。
+- **內置存儲。**每個擴充功能都有自己的每使用者/每組織鍵值存儲，因此它可以儲存狀態，而無需新增新的 SQL 表。
+
+如果範本不應公開使用者編寫的擴充功能，請設定
+`extensionTools: false` 在 `createAgentChatPlugin()` 上。這刪除了
+面向客服人員的分機 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}"
+}
+```
+
+擴充功能也可以**在本機檔案模式下由儲存庫支持**。在該工作流程中，
+`agent-native.json`聲明一個`extensions`資料夾，每個擴充功能都有一個
+`extension.json` 清單加上 HTML 條目檔案，應用程式渲染這些
+檔案通過相同的沙箱。檔案支持的擴充功能通過更改來編輯
+儲存庫檔案；資料庫支持的擴充功能保持執行時建立/編輯/共用
+經驗如下所述。
+
+## 快速圖庫 {#gallery}
+
+人們實際建置的真實擴充功能，按他們所使用的範本分組。每個擴充功能都是一個專注的東西 - 而不是一把瑞士軍刀。
+
+### 郵件
+
+使用者正在閱讀來自 `priya@acme.com` 的電子郵件。什么樣的小部件可以提供幫助？
+
+- **聯系人備注** — 貼上到使用者正在向其發送電子郵件的任何人的便簽本。載入該聯系人的注釋，讓使用者記下更多內容。
+- **與此人最近的話題** - 與開放聯系人的最後五個話題的小列表，與收件箱視圖分開。
+- **CRM 丰富** — 從您的 CRM 中提取聯系人的公司規模、上次會議日期或未結交易。
+- **會議安排程序快捷方式** — 將“下週找個時間”變成一鍵式“發送這些時段”小部件。
+
+草圖 - 聯系人備注（儲存與您的電子郵件發送者相關的備注）：
+
+```html
+<div
+  class="p-4"
+  x-data="{
+    contactEmail: window.slotContext?.contactEmail,
+    note: '',
+    async init() {
+      if (!this.contactEmail) return;
+      const saved = await extensionData.get('notes', this.contactEmail);
+      if (saved) this.note = JSON.parse(saved.data).text;
+    },
+    async save() {
+      await extensionData.set('notes', this.contactEmail, { text: this.note });
+    }
+  }"
+>
+  <p class="text-xs text-muted-foreground mb-2" x-text="contactEmail"></p>
+  <textarea
+    x-model="note"
+    @blur="save()"
+    class="w-full rounded-md border bg-background p-2 text-sm"
+    rows="4"
+    placeholder="Notes about this contact..."
+  ></textarea>
+</div>
+```
+
+### 分析
+
+使用者正在盯著儀表板。缺少的圖塊是什么？
+
+- **自訂 KPI 框** — 非內置面板的指標的單個大數字。 “試驗本週開始”，“MRR 與上個月相比的增量。”
+- **目標跟蹤器** — 提取使用者選取的指標並顯示針對使用者輸入的目標的進度。
+- **熱門客戶排行榜** — 將指標與客戶表連線起來，排名前 10 名。
+
+草圖 - 自訂 KPI 框（調用分析範本的 `appAction` 查詢之一）：
+
+```html
+<div
+  class="p-4"
+  x-data="{
+  value: null,
+  async init() {
+    const result = await appAction('query-agent-native-analytics', {
+      metric: 'trials_started',
+      range: '7d'
+    });
+    this.value = result?.total ?? 0;
+  }
+}"
+>
+  <p class="text-xs uppercase tracking-wider text-muted-foreground">
+    Trials this week
+  </p>
+  <p class="text-3xl font-bold mt-1" x-text="value ?? '—'"></p>
+</div>
+```
+
+### 行事曆
+
+使用者有一個未完成的活動。那一刻什么會有幫助？
+
+- **會議準備清單** — 自動載入開放活動的議程專案、與會者和之前的話題摘要。
+- **旅行時間** — “距離工作地點的下一次會議還有 35 分鐘。”
+- **時區助手** — 以每位與會者當地時間一目了然地顯示會議時間。
+
+### 剪輯
+
+使用者正在檢視螢幕錄製內容。是什么增強了這種觀點？
+
+- **操作項提取器** — 讀取剪輯紀錄（代理通過 `appAction` 獲取它），列出待辦事項。
+- **自動共用** — 一鍵“將此剪輯的連結發布到我的#recordings Slack 頻道。”
+- **亮點卷軸** — 提取代理生成的章節並將其轉變為快速導覽選單。
+
+### 設計
+
+使用者開啟了草稿 Alpine/Tailwind 頁面。什么可以平滑原型設計循環？
+
+- **品牌色樣** - 從使用者的品牌設定中提取調色板，點選可將顏色複製到編輯器中。
+- **資產選取器** — 列出使用者已上傳的圖片，點擊時刪除 URL。
+- **間距檢查器** — 顯示活動頁面使用的間隙/填充/邊距標記，以便使用者可以保持一致。
+
+所有這些的模式：擴充功能是關於使用者位於主機範本內的**那一刻**。客服人員已經知道哪個聯系人、哪個儀表板、哪個事件、哪個剪輯——擴充功能使用該上下文。
+
+## 使用者如何建置 {#building}
+
+簡單路徑：
+
+1. **點擊側邊欄中的“新擴充功能”**（或僅在聊天中詢問）。
+2. **用一句話描述您想要的內容。**“我正在向聯系人發送電子郵件的便簽本。” “本週開始試用 KPI 盒子。”
+3. **代理將其寫入並顯示在您的擴充功能列表中，可供使用。**
+
+沒有要編輯的檔案，無需部署。代理選取正確的助手（`appAction`、`extensionData`、`extensionFetch`）並編寫 Alpine.js HTML。
+
+如果擴充功能需要 API 金鑰（CRM 權杖、天氣 API），代理會告訴您要新增什么以及在哪裡新增。金鑰經過加密存儲並鎖定到特定域。
+
+如果您想稍後更改某些內容，只需說：“在我的聯系人備注中新增搜尋框。”代理就地編輯 HTML — 無需重新生成整個內容。
+
+每個更改都有版本控制。開啟擴充功能檢視器的歷史紀錄控件即可檢視
+儲存的版本，檢查與先前版本的差異，並恢復
+舊名稱/描述/圖標/內容快照而不更改所有權或
+分享。
+
+## 擴充功能可以做什么 {#capabilities}
+
+在 iframe 沙箱內，每個擴充功能在 `window` 上都有這些幫助程序：
+
+| 幫手                                             | 目的                                      | 範例                                                      |
+| ------------------------------------------------ | ----------------------------------------- | --------------------------------------------------------- |
+| `appAction(name, params)`                        | 調用任意主機範本的actions                 | `appAction('list-emails', { view: 'inbox' })`             |
+| `appFetch(path, options)`                        | 調用`/_agent-native/*`下允許的框架端點    | `appFetch('/_agent-native/application-state/navigation')` |
+| `dbQuery(sql, args)`                             | 從 SQL 讀取（自動調整範圍給使用者）       | `dbQuery('SELECT id, name FROM tools')`                   |
+| `dbExec(sql, args)`                              | 寫入SQL                                   | `dbExec('INSERT INTO ...')`                               |
+| `extensionFetch(url, options)`                   | 通過帶有秘密的安全代理攻擊外部 API        | `extensionFetch('https://api.github.com/user')`           |
+| `extensionData.set(collection, id, data, opts?)` | 保留每個擴充功能的資料（使用者/組織範圍） | `extensionData.set('notes', id, { text: '...' })`         |
+| `extensionData.list(collection, opts?)`          | 列出持久化專案                            | `extensionData.list('notes', { scope: 'all' })`           |
+| `extensionData.get(collection, id, opts?)`       | 獲取單個專案                              | `extensionData.get('notes', 'note-1')`                    |
+| `extensionData.remove(collection, id, opts?)`    | 刪除持久化專案                            | `extensionData.remove('notes', 'note-1')`                 |
+
+三個經驗法則：
+
+- **優先選取 `appAction` 而不是 `dbQuery`。** Actions 是範本的官方介面 — 它們為您處理存取控制、範圍界定和驗證。僅當沒有合適的操作時才獲取原始 SQL。
+- **使用 `appAction` 作為範本資料。**擴充功能 `appFetch` 僅限於框架 `/_agent-native/*` 端點；範本 `/api/*` 路由被 iframe 網橋阻止。
+- **優先選取 `extensionData` 而不是建立新表。** 每個擴充功能都有自己獨立的鍵值存儲。沒有架構，就沒有遷移。設定 `{ scope: 'org' }` 與使用者的組織共用，`'user'`（預設）設定為私人。
+
+```html
+<script>
+  // Private to me
+  await extensionData.set('notes', 'note-1', { title: 'My note' });
+
+  // Shared with my org
+  await extensionData.set('notes', 'team-note', { title: 'Team note' }, { scope: 'org' });
+
+  // List everything visible to me (mine + org)
+  const all = await extensionData.list('notes', { scope: 'all' });
+</script>
+```
+
+外部 API 通過 `extensionFetch`，它代理呼叫伺服器端並通過 `${keys.NAME}` 範本替換機密：
+
+```html
+<script>
+  const res = await extensionFetch('https://api.github.com/user', {
+    headers: { Authorization: 'Bearer ${keys.GITHUB_TOKEN}' },
+  });
+</script>
+```
+
+實際金鑰永遠不會到達瀏覽器。每個金鑰都被鎖定到域允許清單，因此泄露的擴充功能無法將其滲透到其他地方。
+
+## 插槽 - 在主機 UI 內放置擴充功能 {#slots}
+
+上面的圖庫描述了擴充功能的用途。槽位描述了它出現的*位置*。
+
+預設情況下，擴充功能位於擴充功能列表中自己的頁面上 - 像開啟小應用程式一樣開啟它。這對於儀表板、計算器和獨立小部件來說很好。
+
+但最 QBO 形狀的用例是不同的：使用者希望將其小部件固定在範本的 UI 內部 - 在郵件側邊欄中的聯系資訊下方、分析儀表板的一角、行事曆事件的右側。這就是**老虎機**的用途。
+
+插槽是範本附帶的命名小部件區域：
+
+| 範本       | 插槽範例                       | 它出現的地方                       |
+| ---------- | ------------------------------ | ---------------------------------- |
+| **郵件**   | `mail.contact-sidebar.bottom`  | 位於每個電子郵件線程的聯系資訊下方 |
+| **分析**   | `analytics.dashboard.tiles`    | 儀表板的內置面板旁邊               |
+| **行事曆** | `calendar.event-detail.bottom` | 在開放事件下方                     |
+| **剪輯**   | `clips.right-panel.tabs`       | 剪輯審閱面板中的新分頁             |
+
+當擴充功能**安裝到插槽中**時，主機會將相關上下文（聯系人的電子郵件、儀表板 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}"
+}
+
+```
+
+### 具體範例
+
+想象一下圖庫中的聯系人備注擴充功能。就其本身而言，它是一個獨立的小部件。要使其顯示在郵件聯系人側邊欄中：
+
+1. 建置一次擴充功能。使用 `window.slotContext.contactEmail` 以便它知道使用者所在的聯系人。
+2. 告訴它它可以填充的槽位：`add-extension-slot-target { extensionId, slotId: "mail.contact-sidebar.bottom" }`。
+3. 安裝它：`install-extension { extensionId, slotId: "mail.contact-sidebar.bottom" }`。
+
+下次您開啟電子郵件線程時，便簽本就位於聯系資訊下方 — 填充了您要向其發送電子郵件的人員的注釋。切換到不同的線程，為*that*接觸載入注釋。相同的擴充功能，不同的上下文，沒有重寫。
+
+實際上，您不會手動執行這三個指令。只需說“將此小部件固定到我的聯系人側邊欄”，代理就會為您處理目標 + 安裝。
+
+> **插槽是一種*附加*功能，而不是先決條件。** 許多有用的擴充功能永遠不會安裝到插槽中 - 它們快樂地生活在自己的頁面上。當小部件需要位於使用者在主機範本中檢視的內容的“旁邊”時，請使用插槽。
+
+有關插槽的更深入詳細資訊 - 如何在範本中聲明它們、上下文合約如何工作、如何確定安裝範圍 - 請參閱 `extension-points` 技能。 Skills 裝在 `.agents/skills/` 下的每個腳手架範本內；請參閱 [Skills Guide](/docs/skills-guide) 了解它們的工作原理。
+
+## 本機檔案擴充功能名 {#local-file-extensions}
+
+本機檔案模式允許工作區將擴充功能保留在儲存庫中：
+
+```text
+extensions/
+  doc-status/
+    extension.json
+    index.html
+```
+
+```json
+{
+  "id": "doc-status",
+  "name": "Doc Status",
+  "description": "Shows metadata for the selected Content file.",
+  "entry": "index.html",
+  "slots": ["content.sidebar.bottom"],
+  "permissions": {
+    "appActions": ["list-documents"],
+    "extensionData": true
+  }
+}
+```
+
+將資料夾新增到`agent-native.json`中的相關應用程式中：
+
+```json
+{
+  "apps": {
+    "content": {
+      "mode": "local-files",
+      "roots": [{ "name": "Docs", "path": "docs", "extensions": [".mdx"] }],
+      "components": "components",
+      "extensions": "extensions"
+    }
+  }
+}
+```
+
+該應用程式列出了檔案支持的擴充功能以及資料庫支持的擴充功能並呈現
+它們通過普通的沙箱 iframe 進行。 `extension.json` 中的槽聲明
+自動將擴充功能安裝到匹配的 `ExtensionSlot` 中；沒有每個使用者
+SQL 本機擴充功能安裝行。
+
+本機擴充功能具有更嚴格的 v1 權限模型：
+
+- 除非停用，否則 `extensionData` 可用於小型執行時狀態。
+- `appAction` 調用必須在 `permissions.appActions` 中顯式列出。
+- `dbQuery`、`dbExec` 和 `extensionFetch` 暫時被屏蔽。
+- SQL 支持的更新、刪除、共用和歷史紀錄 actions 返回一條訊息
+  指向本機入口檔案。
+
+當使用者應在以下位置建立/共用/編輯小部件時，請使用資料庫支持的擴充功能
+執行時。當擴充功能名是 repo-first 的一部分時使用本機檔案擴充功能名
+工作區，並且應該是可審查的、可修補的，並且與其餘部分一起進行版本控制
+檔案。
+
+## 分享 {#sharing}
+
+預設情況下，擴充功能對於建立它們的使用者來說是私人的。分享：
+
+- **組織可見** — 組織中的每個人都可以檢視和使用它。
+- **每使用者授權** — 邀請特定人員作為檢視者/編輯者/管理員。
+
+共用擴充功能有自己的 URL，並插入與檔案、平台和儀表板相同的共用對話框中。插槽安裝始終是個人的 - 共用擴充功能意味著其他人*可以*安裝它；它不會自動將其固定到他們的 UI 上。
+
+## 擴充功能與編輯應用程式碼 {#vs-app-code}
+
+該框架允許代理直接編輯應用程式的來源程式碼——元件、路由、樣式。那么您什么時候應該尋求延期呢？
+
+|              | 擴充功能                                 | 應用程式碼編輯             |
+| ------------ | ---------------------------------------- | -------------------------- |
+| **建立者**   | 執行時的代理（或使用者）                 | 代理編輯來源檔案           |
+| **存儲在**   | 資料庫                                   | git 儲存庫                 |
+| **需要建置** | 否                                       | 是的                       |
+| **需要部署** | 沒有                                     | 是                         |
+| **範圍**     | 一個使用者（或與組織共用）               | 整個產品，每個使用者       |
+| **最適合**   | 個人小部件、自訂 KPI、每個團隊的實用程序 | 向所有使用者提供的核心功能 |
+
+經驗法則：**如果它適用於一個使用者或一個團隊，那么它就是一個擴充功能。**如果範本的每個使用者都應該獲得它，請將其作為一項真正的功能提供。
+
+## 安全 {#security}
+
+```an-callout
+{ "tone": "success", "body": "**The raw secret never reaches the browser.** `extensionFetch` substitutes `${keys.NAME}` server-side and each key is locked to a URL allowlist, so even a leaked extension can't exfiltrate it elsewhere." }
+```
+
+擴充功能在沙盒 iframe 中執行：
+
+- **與父應用程式的 cookie、工作階段和 DOM 隔離**。
+- **伺服器端秘密注入**通過 `${keys.NAME}` 範本 - 實際的金鑰值永遠不會到達瀏覽器。
+- **域鎖定的秘密** — 每個金鑰都綁定到 URL 允許清單；代理拒絕對其他主機的請求。
+- **專用網路保護** - 擴充功能無法到達內部地址。
+- **需要驗證** - 擴充功能僅針對登入使用者執行，並且 `dbQuery` / `dbExec` 調用是自動範圍的。
+
+## 有關命名的一些知識 {#naming-back-compat}
+
+如果您瀏覽 SQL 或來源程式碼，您會看到“擴充功能”和“工具”名稱的混合。快速解碼器：
+
+- 面向使用者的原語過去被稱為“工具”。現在是**擴充功能**。
+- 物理 SQL 表（`tools`、`tool_data`、`tool_shares`、`tool_slots`、`tool_slot_installs`）保留其原始名稱 - 重命名表是破壞性遷移，框架不會提供破壞性遷移。
+- Drizzle / TypeScript 匯出使用新名稱：`extensions`、`extensionData`、`extensionShares`、`extensionSlots`、`extensionSlotInstalls`。
+- 在擴充功能的 iframe 內，規範助手是 `extensionFetch` 和 `extensionData`。舊名稱 `toolFetch` 和 `toolData` 仍然可以解析，因此較舊的擴充功能 HTML 可以繼續工作。
+
+在正常使用中您也不會看到這一點，但代理有第三個相關概念，稱為“LLM 工具”——模型轉彎上的函數調用表面積（通過 `defineAction`、MCP 等定義）。這些是函數調用原語，而不是面向使用者的小部件。當此頁面顯示“擴充功能”時，它指的是面向使用者的小部件；當其他檔案在 `defineAction` 旁邊提到“工具”時，這就是 LLM 的概念。
+
+## 下一步是什么
+
+- [**Templates**](/docs/cloneable-saas) - 主機應用擴充功能擴充功能
+- [**Actions**](/docs/actions) — 擴充功能通過 `appAction` 調用的操作
+- [**Sharing & Privacy**](/docs/sharing) — 擴充功能可見性、組織共用和每使用者授權如何工作
+- [**Onboarding & API Keys**](/docs/onboarding) — 秘密如何在設定 UI 中顯現
+- [**Security**](/docs/security) — 框架的資料範圍和存取模型