@agent-native/core 0.79.1 → 0.79.5

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

@@ -0,0 +1,83 @@
+---
+title: "藍圖安裝程序"
+description: "agent-native add 將精心策劃的 Markdown 整合配方列印到標準輸出 - 將其通過管道傳輸到您的編碼代理，該代理將針對您的實時儲存庫應用更改。"
+---
+
+# 藍圖安裝程序
+
+> **這是誰的：** 新增提供者、渠道的主機作者和整合商，
+> 沙箱後端，或通過將配方傳輸到其編碼代理中來對儲存庫進行操作。
+
+`agent-native add` 不是\*\*一個為你編寫檔案的愚蠢的腳手架。它將精心策劃的 Markdown _整合藍圖_ 發送到標準輸出。您可以將該藍圖傳輸到您自己的編碼代理（Claude 程式碼、Codex 等）中，該代理將針對具有完整上下文的實時儲存庫應用更改。
+
+這符合代理應用更改、檔案系統優先的風格：框架提供配方（要接觸的規範檔案、要遵守的規則、驗證步驟），編碼代理進行編輯。
+
+```bash
+agent-native add provider stripe | claude
+agent-native add channel discord  | codex
+```
+
+```an-diagram title="新增列印菜譜；您的編碼代理應用它" summary="agent-native 向 stdout 發出 Markdown 藍圖（對 stderr 進行診斷）；您可以將其通過管道傳輸到 Claude Code 或 Codex，這將使用完整的上下文編輯您的實時儲存庫。"
+{
+  "html": "<div class=\"diagram-bp\"><div class=\"diagram-node\" data-rough>agent-native add<br><small class=\"diagram-muted\">&lt;kind&gt; &lt;name|URL&gt;</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Markdown 藍圖<br><small class=\"diagram-muted\">stdout · 要觸碰的檔案 · 規則 · 驗證</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough>編碼 Agent<br><small class=\"diagram-muted\">claude · codex</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill ok\">edits your live repo</div></div>",
+  "css": ".diagram-bp{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-bp .diagram-arrow{font-size:22px;line-height:1}.diagram-bp .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## 用法 {#usage}
+
+```bash
+agent-native add <kind> <name>            # print a curated blueprint
+agent-native add <kind> <https://docs…>   # 從 URL 進行研究和整合
+agent-native add --list                   # list available kinds and blueprints
+```
+
+- 一個赤裸裸的**名字**就能解析出`blueprints/<kind>/<name>.md`精心策劃的藍圖。
+- **URL**（而不是名稱）會發出此類的通用*研究和整合*藍圖，其中嵌入 URL 作為研究起點（URL 是研究種子，而不是已知配方）。
+- 藍圖轉到 **stdout**；診斷會發送到 stderr，因此 `… | claude` 只會收到藍圖。
+
+## 播種藍圖 {#seeded}
+
+`agent-native add --list` 顯示包裝盒中的物品：
+
+| 種類       | 姓名      | 它設定什么                                                             |
+| ---------- | --------- | ---------------------------------------------------------------------- |
+| `provider` | `stripe`  | 將提供程序連線到 `provider-api` 基板（目錄/檔案/請求三重奏）。         |
+| `channel`  | `discord` | 實現 `PlatformAdapter` 入站 Webhook 通道並註冊它。                     |
+| `sandbox`  | `docker`  | 實現 `SandboxAdapter` 接縫以在 Docker 容器中執行 `run-code`。          |
+| `action`   | `crud`    | 新增具有 Zod 架構的單個多表面 `defineAction`（一個 `update` 超過 N）。 |
+
+每個藍圖都是獨立的：讀取它的編碼代理獲取要接觸的檔案、要遵守的框架規則（actions 是單一事實來源、從不硬編碼秘密、範圍可擁有的資料、為 `packages/*` 來源新增變更集）以及具體的 **驗證** 部分。
+
+## URL → 研究藍圖 {#url}
+
+當您傳遞 URL 時，該型別沒有策劃的配方（或想要新的整合），`add` 會發出一個通用的“研究和整合”藍圖，以 URL 作為種子：
+
+```bash
+agent-native add provider https://docs.example.com/api | claude
+```
+
+生成的藍圖告訴編碼代理獲取真實端點的 URL（及其連結到的頁面）、驗證模型、有效負載形狀和簽名/驗證要求（而不是從訓練資料中猜測），然後實施和驗證。它還帶有特定型別的指導（例如，`provider` URL 轉向 `provider-api` 基板；`channel` URL 轉向 `PlatformAdapter`）。
+
+## 新增您自己的藍圖 {#authoring}
+
+將 Markdown 檔案拖放到 `packages/core/blueprints/<kind>/<name>.md` 中。 kind 是子目錄；該名稱是不帶 `.md` 的檔案名。它是自動拾取的 - `--list`、名稱解析和目錄都在執行時讀取目錄。無需更改程式碼即可註冊。
+
+藍圖 `.md` 檔案通過 `package.json` `files` 中的 `blueprints` 條目發送到已發布的包中，因此最終使用者可以在 `node_modules/@agent-native/core/blueprints/**` 上進行解析。
+
+將每個藍圖編寫為編碼代理的指令集，沒有其他上下文。一個好的藍圖具有：
+
+1. **一行目標**和“您是代理本機應用程式中的編碼代理，將這些作為真正的來源更改應用”框架。
+2. **首先閱讀** - *是*合約的確切檔案。
+3. **要接觸的檔案** - 具體路徑以及每個更改的作用。
+4. **要遵守的框架規則** - actions-first，無硬編碼秘密，範圍可擁有的資料，新增可發布包來源的變更集。
+5. **驗證** — 型別檢查、重點 `*.spec.ts` 和端對端檢查。
+
+> [!TIP]
+> 現有型別下的新策劃藍圖不需要程式碼 - 但如果您建立一個全新的型別目錄，該型別也會自動顯示在 `--list` 中。
+
+## 下一步是什么
+
+- [**Sandbox Adapters**](/docs/sandbox-adapters) — `add sandbox docker` 藍圖目標的接縫
+- [**Actions**](/docs/actions) - 每個藍圖建置的單一事實來源
+- [**External Agents**](/docs/external-agents) — 連線將藍圖通過管道傳輸到的編碼代理

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

@@ -0,0 +1,129 @@
+---
+title: "CLI 適配器"
+description: "通過標準適配器介面（適配器指南中介紹的兩個適配器接縫之一）為代理提供對任何 CLI 工具（gh、ffmpeg、stripe）的結構化存取。"
+---
+
+# CLI 適配器
+
+> **適合的位置：** CLI 適配器是
+> 框架。規範指南是 [Adapters](/docs/sandbox-adapters)，
+> 覆蓋此接縫和 `run-code` 沙箱接縫 - 包括共用
+> 邊缘/無伺服器約束。本頁面是CLI端的快速參考。
+
+CLI 適配器包裝單個指令行工具（`gh`、`ffmpeg`、`stripe`、`aws`），以便代理可以發現它，檢查它是否已安裝，並使用一致的 stdout/stderr/exit-code 結果執行它。如果沒有這個接縫，每個腳本都會重新發明如何調用 CLI 並解析其輸出。
+
+```an-diagram title="CLI 適配器 → 註冊表 → 操作面" summary="ShellCliAdapter 包裝二進制檔案； CliRegistry 收集適配器以供發現； defineAction 在代理 + UI 操作介面上公開一個調用。"
+{
+  "html": "<div class=\"diagram-cli\"><div class=\"diagram-node\" data-rough>gh · ffmpeg · stripe<br><small class=\"diagram-muted\">command-line tools</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>ShellCliAdapter<br><small class=\"diagram-muted\">isAvailable · execute</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough>CliRegistry<br><small class=\"diagram-muted\">describe() for discovery</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill accent\">defineAction</div></div>",
+  "css": ".diagram-cli{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-cli .diagram-arrow{font-size:22px;line-height:1}.diagram-cli .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## 介面 {#the-interface}
+
+每個 CLI 適配器都實現 `CliAdapter`：
+
+```ts
+import type { CliAdapter, CliResult } from "@agent-native/core/adapters/cli";
+
+interface CliAdapter {
+  name: string; // "gh", "stripe", "ffmpeg"
+  description: string; // What the agent sees during discovery
+  isAvailable(): Promise<boolean>;
+  execute(args: string[]): Promise<CliResult>;
+}
+
+interface CliResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+```
+
+## ShellCli適配器 {#shell-adapter}
+
+對於大多數 CLI，您不需要自訂類 - `ShellCliAdapter` 使用合理的預設值包裝任何二進制檔案：
+
+```ts
+import { ShellCliAdapter } from "@agent-native/core/adapters/cli";
+
+const gh = new ShellCliAdapter({
+  command: "gh",
+  description: "GitHub CLI — manage repos, PRs, issues, and releases",
+});
+
+const ffmpeg = new ShellCliAdapter({
+  command: "ffmpeg",
+  description: "Audio/video processing and transcoding",
+  timeoutMs: 120_000, // 2 min for long encodes
+  env: { STRIPE_API_KEY: process.env.STRIPE_SECRET_KEY! },
+});
+```
+
+選項：`command`（必填）、`description`（必填）、`name`（預設為 `command`）、`env`（與 `process.env` 合並）、`cwd`（預設為 `process.cwd()`）和 `timeoutMs`（預設） `30000`）。
+
+對於自訂驗證、輸出解析或前/後處理，請直接實現 `CliAdapter`，而不是使用 `ShellCliAdapter`。
+
+## 註冊表 {#registry}
+
+`CliRegistry` 收集適配器，以便代理可以發現執行時可用的內容：
+
+```ts
+import { CliRegistry, ShellCliAdapter } from "@agent-native/core/adapters/cli";
+
+const cliRegistry = new CliRegistry();
+cliRegistry.register(
+  new ShellCliAdapter({ command: "gh", description: "GitHub CLI" }),
+);
+
+cliRegistry.list(); // all registered
+await cliRegistry.listAvailable(); // only installed
+await cliRegistry.describe(); // [{ name, description, available }] for discovery
+
+const gh = cliRegistry.get("gh");
+const result = await gh?.execute(["pr", "list", "--json", "title,url"]);
+```
+
+## 從actions使用 {#from-actions}
+
+將 CLI 調用包裝在 `defineAction` 中以將其公開在操作介面上 - 當程式碼在伺服器操作介面內執行時需要 `defineAction`；否則直接在 `scripts/` 檔案中使用適配器。切勿在動作中調用 `process.exit`；相反，會拋出錯誤。
+
+```ts
+// actions/list-prs.ts
+import { defineAction } from "@agent-native/core/action";
+import { ShellCliAdapter } from "@agent-native/core/adapters/cli";
+import { z } from "zod";
+
+const gh = new ShellCliAdapter({ command: "gh", description: "GitHub CLI" });
+
+export default defineAction({
+  description: "List open pull requests via the GitHub CLI.",
+  schema: z.object({}),
+  async run() {
+    if (!(await gh.isAvailable())) {
+      throw new Error("GitHub CLI not installed. Run: brew install gh");
+    }
+    const result = await gh.execute([
+      "pr",
+      "list",
+      "--json",
+      "title,url,state",
+      "--limit",
+      "10",
+    ]);
+    if (result.exitCode !== 0) {
+      throw new Error(result.stderr || "gh pr list failed");
+    }
+    return JSON.parse(result.stdout);
+  },
+});
+```
+
+## 邊缘和無伺服器 {#edge-serverless}
+
+CLI 適配器使用 `node:child_process`，它在邊缘/工作線程執行時（Cloudflare Workers、Netlify Edge Functions）上不存在。在標準 Node.js 環境中執行 CLI 適配器端點和工作。此約束與沙箱接縫共用 - 請參閱 [Adapters](/docs/sandbox-adapters#edge-serverless) 中的完整討論。
+
+## 下一步是什么
+
+- [**Adapters**](/docs/sandbox-adapters) — 兩個適配器接縫的規範指南。
+- [**Actions**](/docs/actions) — 操作面 CLI 適配器通常被包裹在其中。

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

@@ -0,0 +1,398 @@
+---
+title: "用戶端"
+description: "用於代理本機應用程式的 React 掛鉤和實用程序：sendToAgentChat、可選代理聊天上下文狀態、useDbSync、useAgentChatGenerate 和 cn。"
+---
+
+# 用戶端
+
+`@agent-native/core` 為代理本機應用程式的瀏覽器端提供 React 掛鉤和實用程序。
+
+這些用戶端/React API 是從 `@agent-native/core` 和 `@agent-native/core/client` 匯出的。為了清晰和正確的捆綁，從 `@agent-native/core/client`（瀏覽器條目）匯入它們，因為預設情況下裸 `@agent-native/core` 根解析為 Node 建置。
+
+對於基於檔案的路由 - 新增頁面、動態參數和導覽 - 請參閱 [Routing](/docs/routing)。
+
+## 獲取和修改資料 {#fetching-mutating}
+
+從瀏覽器讀取和寫入應用程式資料的主要方式是通過操作掛鉤。切勿手寫 `fetch` 調用 `/_agent-native/*` 路由 - 請改用命名助手（請參閱 [Actions](/docs/actions)）。
+
+```an-diagram title="瀏覽器資料循環" summary="鉤子通過動作進行讀寫； useDbSync 監視資料庫，以便代理和後台寫入自動重新獲取相同的快取。"
+{
+  "html": "<div class=\"diagram-client\"><div class=\"diagram-col\"><div class=\"diagram-node\">useActionQuery<br><small class=\"diagram-muted\">cached read</small></div><div class=\"diagram-node\">useActionMutation<br><small class=\"diagram-muted\">write + invalidate</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&harr;</div><div class=\"diagram-box\" data-rough>Actions<br><small class=\"diagram-muted\">/_agent-native/actions/*</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&harr;</div><div class=\"diagram-panel\" data-rough><strong>SQL 資料庫</strong></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</div><div class=\"diagram-pill ok\">useDbSync &rarr; refetch on change</div></div>",
+  "css": ".diagram-client{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-client .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-client .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+```tsx
+import {
+  useActionQuery,
+  useActionMutation,
+  callAction,
+} from "@agent-native/core/client";
+
+// Read: auto-cached, auto-invalidated on mutations
+const { data, isLoading } = useActionQuery("get-lead", { leadId });
+
+// Mutate: emits a change event so query caches refetch
+const { mutate, isPending } = useActionMutation("create-lead");
+mutate({ name: "Alice", company: "Acme" });
+
+// Imperative: for one-off calls outside a component
+await callAction("archive-lead", { leadId });
+```
+
+## sendToAgentChat（選取） {#sendtoagentchat}
+
+通過 postMessage 向代理聊天發送訊息——這是從 UI 互動中委派 AI 工作的常用方法。傳遞 `context` 來隱藏模型上下文，傳遞 `submit: true` 來立即發送，或者傳遞 `submit: false` 來預先填寫使用者首先審閱的草稿。
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client";
+
+// Auto-submit a prompt with hidden context
+sendToAgentChat({
+  message: "Generate alt text for this image",
+  context: "Image path: /api/projects/hero.jpg",
+  submit: true,
+});
+
+// Prefill without submitting (user reviews first)
+sendToAgentChat({
+  message: "Rewrite this in a conversational tone",
+  context: selectedText,
+  submit: false,
+});
+```
+
+在使用 `embedApp()` 建立的 MCP 應用嵌入中，自動提交訊息
+（`submit`省略或`true`）被轉發到MCP應用程式主橋，這
+要求包含主機新增隱藏上下文並發送可見使用者回合。
+`context` 保持模型可見，而不發布為面向使用者的聊天。
+`submit: false` 保留本機預填充/審核行為，因為 MCP 應用不會
+定義標準草稿預填充 API。在內部，這是提交的聊天路徑
+有時會以 `agentNative.submitChat` 的形式出現；應用程式碼應該調用
+`sendToAgentChat()` 而不是直接發布該事件。
+
+### 後台靜默發送 {#background-send}
+
+當 UI 操作應該啟動真正的代理工作時，請使用 `background: true`
+開啟或聚焦側邊欄。這仍然會建立一個正常的聊天線程/執行，
+使用代理的工具/actions/context，並通過以下方式保持工作可觀察
+執行托盤；它不是原始的一次性模型調用。
+
+```ts
+const tabId = sendToAgentChat({
+  message: "Analyze this import and create any missing records",
+  context: `Import batch id: ${batchId}`,
+  submit: true,
+  newTab: true,
+  background: true,
+  openSidebar: false,
+});
+```
+
+`background` 旨在與 `newTab` 配對，因此隱藏的工作不會
+overwrite the user's active conversation. Use the returned `tabId` if the UI
+需要將後續狀態或深層連結關聯到稍後的執行。
+
+### 代理聊天訊息 {#agentchatmessage}
+
+| 選項                  | 型別        | 描述                                                              |
+| --------------------- | ----------- | ----------------------------------------------------------------- |
+| `message`             | `string`    | 發送到聊天的可見提示                                              |
+| `context`             | `string?`   | 附加隱藏上下文（聊天UI中未顯示）                                  |
+| `submit`              | `boolean?`  | true = 自動提交，false = 僅預填充                                 |
+| `newTab`              | `boolean?`  | 為此提示建立單獨的聊天線程                                        |
+| `background`          | `boolean?`  | 使用 `newTab`，在不聚焦分頁的情況下執行並在 `RunsTray` 中顯示執行 |
+| `openSidebar`         | `boolean?`  | 設定 false 來提交/預填充而不開啟側邊欄                            |
+| `projectSlug`         | `string?`   | 結構化上下文的可選專案段                                          |
+| `preset`              | `string?`   | 下游消費者的可選預設名稱                                          |
+| `referenceImagePaths` | `string[]?` | 可選的參考圖片路徑                                                |
+
+## 客服人員聊天上下文狀態（高級） {#agent-chat-context-state}
+
+上下文狀態 API 是 UI 的可選管道，需要雙向同步
+暫存上下文芯片：在編輯器之外渲染目前暫存專案，
+反映某個專案是否已附加，或提供明確的
+刪除/清除控件。
+
+不要為了簡單的“將其發送給代理”而聯系這些助手，或者
+“預填寫此草稿以供審核”流程。將 `sendToAgentChat()` 與 `context` 結合使用
+還有 `submit`。
+
+| API                               | 何時使用                                        |
+| --------------------------------- | ----------------------------------------------- |
+| `useAgentChatContext()`           | React 元件需要實時暫存上下文列表                |
+| `setAgentChatContextItem(item)`   | 指令式程式碼應暫存或替換一個鍵控上下文項        |
+| `listAgentChatContext()`          | 非 React 程式碼需要暫存上下文的一次性快照       |
+| `removeAgentChatContextItem(key)` | UI 應通過其穩定的 `key` 刪除一個暫存上下文項    |
+| `clearAgentChatContext()`         | UI 應清除所有暫存上下文，例如在視圖或模式重置後 |
+| `refreshAgentChatContext()`       | 指令程式碼應該重新讀取最新的持久上下文快照      |
+
+`useAgentChatContext()` 返回 `{ items, set, remove, clear, refresh }`。
+
+## openAgentSettings（部分？） {#openagentsettings}
+
+當應用設定頁面或設定卡開啟時使用 `openAgentSettings()`
+代理側邊欄的“設定”分頁。傳遞一個部分id，例如`"llm"`，`"secrets"`，
+`"automations"`、`"voice"` 或 `"limits"` 開啟特定部分。
+
+```ts
+import { openAgentSettings } from "@agent-native/core/client";
+
+openAgentSettings();
+openAgentSettings("secrets");
+```
+
+更喜歡這個助手而不是直接調度 `agent-panel:open-settings`。
+
+```tsx
+import { useAgentChatContext } from "@agent-native/core/client";
+
+function SelectionContextButton({ record }: { record: { id: string } }) {
+  const chatContext = useAgentChatContext();
+  const contextKey = `selected-record:${record.id}`;
+  const isAttached = chatContext.items.some((item) => item.key === contextKey);
+
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        if (isAttached) {
+          chatContext.remove(contextKey);
+          return;
+        }
+
+        chatContext.set({
+          key: contextKey,
+          title: "Selected Record",
+          context: JSON.stringify(record, null, 2),
+          openSidebar: false,
+        });
+      }}
+    >
+      {isAttached ? "Remove from prompt context" : "Add to prompt context"}
+    </button>
+  );
+}
+```
+
+`listAgentChatContext()` 用於僅需要檢查的指令式程式碼
+目前暫存專案一次。 `clearAgentChatContext()` 故意寬泛；使用
+僅更改一項選取時為 `removeAgentChatContextItem(key)`。
+
+### AgentChatContextSetOptions {#agentchatcontextsetoptions}
+
+| 選項          | 型別       | 描述                                        |
+| ------------- | ---------- | ------------------------------------------- |
+| `key`         | `string`   | 用於替換現有塊的穩定標識符                  |
+| `title`       | `string`   | 作曲家芯片中顯示的短標籤                    |
+| `context`     | `string`   | 下一個提交的提示中包含隱藏上下文            |
+| `openSidebar` | `boolean?` | 預設為true；靜默地將 false 傳遞給舞台上下文 |
+
+## 詢問使用者問題（選取） {#ask-user-question}
+
+通過應用程式碼向使用者提出多項選取問題，並將其內聯呈現
+代理小組，並**等待他們的答複**。它是用戶端的孿生
+代理的內置`ask-question`工具：它將`GuidedQuestionPayload`寫入
+`"guided-questions"` 應用程式狀態金鑰（已安裝的位置
+`GuidedQuestionFlow` 渲染它）並顯示代理面板，所以問題是
+可見。與代理工具不同——其答案會返回給代理——
+`askUserQuestion()` **解析調用者的答案**，因此 UI 可以
+在上面分支。
+
+當 UI 之前需要做出一個小決定（2-4 個選項）時使用它
+開始代理工作——而不是建置自訂模式。到達
+用於自由形式細節的組合器，以及用於多欄位輸入的表單/快顯框。
+
+```tsx
+import { askUserQuestion, sendToAgentChat } from "@agent-native/core/client";
+
+const length = await askUserQuestion({
+  question: "How long should this deck be?",
+  header: "Deck length", // optional short chip/heading (≈12 chars)
+  options: [
+    { label: "Short (3–5 slides)", value: "short" },
+    { label: "Medium (6–10 slides)", value: "medium", recommended: true },
+    { label: "Long (11+ slides)", value: "long" },
+  ],
+  allowFreeText: false, // omit the "Other" free-text option (default adds it)
+  allowMultiple: false, // single-select (default)
+});
+
+if (length) {
+  sendToAgentChat({ message: `Generate a ${length} deck.`, submit: true });
+}
+```
+
+每個選項都是`{ label, value?, description?, preview?, recommended? }`； `value`
+預設為`label`，`preview`在
+選項。承諾以選定的 `value`（或 `value[]` 時）解析
+`allowMultiple`)，使用者選取“其他”時的自由文本字串，或 `null`
+如果他們跳過——它將保持待定狀態，直到使用者回答。需要代理面板
+要安裝（每個範本中都有）。
+
+代理通過其 `ask-question` 工具到達相同的 UI：更願意讓
+當 _it_ 遇到一個無法從上下文解析的真正分叉時，代理會詢問；使用
+`askUserQuestion()`，當 _UI_ 需要對選取進行操作時。
+
+## MCP應用程式主橋 {#mcp-app-host-bridge}
+
+作為 MCP 應用嵌入的路由應該是 URL-first：載入目前工件
+路徑/查詢參數，渲染真實的React路由或聚焦的共用元件，
+並且僅將主機橋用於主機擁有的行為。 `@agent-native/core/client`
+匯出助手嵌入的路由調用：
+
+```ts
+import {
+  getMcpAppHostContext,
+  openMcpAppHostLink,
+  requestMcpAppDisplayMode,
+  updateMcpAppModelContext,
+  useMcpAppHostContext,
+} from "@agent-native/core/client";
+```
+
+`getMcpAppHostContext()`讀取最新推送的主機上下文快照；
+`useMcpAppHostContext()` 訂閱 React 元件的更改。請求
+助手（`openMcpAppHostLink`、`requestMcpAppDisplayMode`，
+`updateMcpAppModelContext`) 在嵌入式 MCP 應用框架之外返回 `false`，或
+`Promise<boolean>` 在框架內。 `sendToAgentChat()` 使用相同的橋
+從嵌入式路由自動提交提示。
+
+橋本身 - `ui/*` JSON-RPC 訊息、`agentNative.mcpHost.*`
+包裝器中繼、移植與受控幀渲染、主機上下文以及
+顯示模式請求 — 屬於
+[External Agents](/docs/external-agents#mcp-app-bridge).
+
+## 動態建議 {#dynamic-suggestions}
+
+`<AgentSidebar>`、`<AgentPanel>` 和 `<AssistantChat>` 預設將靜態 `suggestions` 與上下文感知建議合並。當可見空聊天時，框架從應用程式狀態中讀取 `navigation`、`selection`、`pending-selection-context` 和目前 URL，然後提供與目前螢幕匹配的提示芯片。
+
+```tsx
+<AgentSidebar
+  suggestions={["Summarize my inbox"]}
+  dynamicSuggestions={{ max: 4 }}
+>
+  <App />
+</AgentSidebar>
+```
+
+設定 `dynamicSuggestions={false}` 僅保留靜態芯片。當應用程式需要來自同一應用程式狀態上下文的確定性特定於域的芯片時，傳遞 `getSuggestions`。
+
+## useAgentChatGenerate() {#useagentchatgenerating}
+
+React 鉤子，通過載入狀態跟蹤包裝 sendToAgentChat：
+
+```ts
+import { useAgentChatGenerating } from "@agent-native/core/client";
+
+function GenerateButton() {
+  const [isGenerating, send] = useAgentChatGenerating();
+
+  return (
+    <button
+      disabled={isGenerating}
+      onClick={() => send({
+        message: "Generate a summary",
+        context: documentContent,
+        submit: true,
+      })}
+    >
+      {isGenerating ? "Generating..." : "Generate"}
+    </button>
+  );
+}
+```
+
+當您調用 `send()` 時，`isGenerating` 變為 true，並在代理完成生成時自動重置為 false。
+
+## useDbSync（選項？） {#usedbsync}
+
+React 掛鉤（以前稱為 `useFileWatcher`），用於偵听 SSE 上的資料庫更改，回退到輪詢，並使保持 UI 與代理寫入保持一致的框架查詢快取無效：
+
+```ts
+import { useDbSync } from "@agent-native/core/client";
+import { useQueryClient } from "@tanstack/react-query";
+
+function App() {
+  const queryClient = useQueryClient();
+
+  useDbSync({
+    queryClient,
+    pollUrl: "/_agent-native/poll",
+    onEvent: (data) => console.log("Data changed:", data),
+  });
+
+  return <div>...</div>;
+}
+```
+
+### 選項 {#usedbsync-options}
+
+| 選項               | 型別               | 描述                                                                                   |
+| ------------------ | ------------------ | -------------------------------------------------------------------------------------- |
+| `queryClient`      | `QueryClient?`     | React-查詢用戶端快取失效                                                               |
+| `queryKeys`        | `string[]?`        | 已棄用並被忽略；為舊的調用站點保留                                                     |
+| `pollUrl`          | `string?`          | 輪詢端點 URL。預設值：`"/_agent-native/poll"`                                          |
+| `sseUrl`           | `string \| false?` | SSE endpoint URL. Default: `"/_agent-native/events"`; pass `false` to use polling only |
+| `interval`         | `number?`          | 輪詢間隔（以毫秒為單位）。預設值：`2000`                                               |
+| `fallbackInterval` | `number?`          | SSE 不可用時的回退輪詢間隔。預設值：`15000`                                            |
+| `pauseWhenHidden`  | `boolean?`         | 當瀏覽器分頁隱藏時暫停輪詢。預設值：`true`                                             |
+| `ignoreSource`     | `string?`          | 要忽略的每個分頁請求來源，以便分頁不會從其自己的寫入中重新獲取                         |
+| `onEvent`          | `(data) => void`   | SSE/polling 收到更改事件時的可選回調                                                   |
+
+對於普通CRUD，優先選取`useActionQuery`和`useActionMutation`；變異 actions 會發出 `source: "action"` 並且這些鉤子會自動重新獲取。
+
+## useChangeVersion / useChangeVersions {#use-change-version}
+
+框架使用更改版本將 React 查詢快取與後台代理、cron 作業或其他使用者所做的更改同步。
+
+當任何伺服器端資料庫發生突變時，伺服器都會使用特定的 `source` 金鑰紀錄更改事件。用戶端的 `useDbSync` 偵听器接收這些事件並增加該來源的本機更改版本計數器。通過將版本計數器折疊到 React 查詢鍵中，每當後端通知用戶端新活動時，查詢就會自動重新獲取。
+
+- **`useChangeVersion(source: string): number`** — 返回一個計數器，每當指定的 `source` 發生突變時該計數器就會遞增。
+- **`useChangeVersions(sources: readonly string[]): number`** — 返回多個來源的版本計數器之和。
+
+### 範例：將原始查詢與資料庫同步
+
+```tsx
+import { useQuery } from "@tanstack/react-query";
+import { useChangeVersion } from "@agent-native/core/client";
+
+function DashboardView({ id }) {
+  // Get version for dashboards domain source
+  const v = useChangeVersion("dashboards");
+
+  const { data } = useQuery({
+    queryKey: ["dashboard", id, v], // Invalidate automatically when version bumps
+    queryFn: () => fetchDashboard(id),
+    placeholderData: (prev) => prev, // Prevent layout flicker during refetch
+  });
+
+  return <div>{data?.title}</div>;
+}
+```
+
+### 延遲模型和失效行為
+
+- **UI-發起的突變：**當您使用 `useActionMutation` 從 UI 執行操作時，突變會在成功時立即觸發 `source: "action"` 本機事件。這會根據該操作觸發所有查詢鍵的**即時、樂觀的重新獲取**，從而避免視覺延遲。
+- **後台或代理突變：** 當 AI 代理、Webhook 或後台工作人員突變資料時，更新會廣播到用戶端。用戶端的 `useDbSync` 可以立即通過 SSE（伺服器發送的事件）捕獲此資訊，也可以回退到 **2 秒輪詢滴答**。然後查詢金鑰版本會發生變化，從而觸發後台重新獲取。
+
+```an-diagram title="重新獲取的兩條路徑" summary="本機突變會立即使自己的快取失效；遠端寫入通過 SSE 到達此分頁，或作為後備的輪詢標記。"
+{
+  "html": "<div class=\"diagram-latency\"><div class=\"diagram-col\"><div class=\"diagram-card\" data-rough><span class=\"diagram-pill ok\">此標籤頁面</span><strong>useActionMutation</strong><small class=\"diagram-muted\">fires source: \"action\" on success &rarr; instant local refetch</small></div><div class=\"diagram-card\" data-rough><span class=\"diagram-pill accent\">代理 · webhook · 其他標籤頁面</span><strong>遠端寫入</strong><small class=\"diagram-muted\">SSE push, or the ~2s polling tick as fallback &rarr; version bumps &rarr; background refetch</small></div></div></div>",
+  "css": ".diagram-latency .diagram-col{display:flex;flex-direction:column;gap:12px}.diagram-latency .diagram-card{display:flex;flex-direction:column;gap:4px;padding:14px 16px}"
+}
+```
+
+## cn（...輸入） {#cn}
+
+合並類名的實用程序（clsx + tailwind-merge）：
+
+```ts
+import { cn } from "@agent-native/core/client";
+
+<div className={cn(
+  "px-4 py-2 rounded",
+  isActive && "bg-primary text-primary-foreground",
+  className
+)} />
+```