@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/zh-CN/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="add prints a recipe; your coding agent applies it" summary="agent-native emits a Markdown blueprint to stdout (diagnostics to stderr); you pipe it into Claude Code or Codex, which edits your live repo with full context."
+{
+  "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 blueprint<br><small class=\"diagram-muted\">stdout · files to touch · rules · Verify</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough>Coding 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…>   # research-and-integrate from a 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/docs/content/locales/zh-CN/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 adapter → registry → action surface" summary="ShellCliAdapter wraps a binary; CliRegistry collects adapters for discovery; defineAction exposes one call on the agent + UI action surface."
+{
+  "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/docs/content/locales/zh-CN/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="The browser data loop" summary="Hooks read and write through actions; useDbSync watches the database so agent and background writes refetch the same caches automatically."
+{
+  "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 database</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="Two paths to a refetch" summary="A local mutation invalidates its own caches instantly; a remote write reaches this tab over SSE, or the polling tick as a fallback."
+{
+  "html": "<div class=\"diagram-latency\"><div class=\"diagram-col\"><div class=\"diagram-card\" data-rough><span class=\"diagram-pill ok\">This tab</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\">Agent · webhook · other tab</span><strong>Remote write</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
+)} />
+```