@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/zh-CN/agent-mentions.md

@@ -0,0 +1,164 @@
+---
+title: "代理提及"
+description: "使用@提及在聊天中标记自定义代理、连接的代理和文件。"
+---
+
+# 代理提及
+
+在聊天编辑器中键入 `@` 以提及自定义代理、连接的代理、文件和资源。
+
+## 概述 {#overview}
+
+`@` 提及系统将聊天编辑器连接到更广泛的代理生态系统。当您键入 `@` 时，会出现一个弹出窗口，列出可用的自定义代理、连接的代理、代码库文件和资源。
+
+这是您通过单个聊天协调多代理工作流程的方式。要求您当地的 `@design` 代理评论布局，`@analytics` 从另一个应用程序中提取最新数据，主要代理可以将两者合并到一个对话中。
+
+## 提及代理 {#mentioning-agents}
+
+要在聊天编辑器中提及代理：
+
+1. 输入 `@` 打开提及弹出窗口
+2. 浏览或搜索可用代理列表
+3. 选择一个代理 - 它在您的消息中显示为标签
+4. 发送消息 - 服务器解析提及并将该代理的响应包含在对话上下文中
+
+有两条代理路径：
+
+- **自定义代理** — `agents/*.md` 中的本地工作区代理配置文件。它们使用代理配置文件的指令和可选模型覆盖在当前应用程序/运行时内运行。
+- **连接的代理** — 远程 A2A 对等点。这些是通过 [A2A protocol](/docs/a2a-protocol) 调用的。
+
+在这两种情况下，您的主要代理都会看到响应并可以引用或构建它。
+
+```an-diagram title="Where an @-mention routes" summary="The server splits each mention by type: custom agents run locally, connected agents go over A2A — both responses fold back into the main agent's context."
+{
+  "html": "<div class=\"diagram-mention\"><div class=\"diagram-node\">@-mention<br><small class=\"diagram-muted\">in the composer</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">Server resolves</span><small class=\"diagram-muted\">extract refs by type</small></div><div class=\"diagram-col\"><div class=\"row\"><span class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</span><div class=\"diagram-box\">Custom agent<br><small class=\"diagram-muted\">agents/*.md &middot; runs local</small></div></div><div class=\"row\"><span class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</span><div class=\"diagram-box\">Connected agent<br><small class=\"diagram-muted\">A2A peer &middot; remote call</small></div></div></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box diagram-accent\">&lt;agent-response&gt;<br><small class=\"diagram-muted\">injected into main agent</small></div></div>",
+  "css": ".diagram-mention{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-mention .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px}.diagram-mention .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-mention .row{display:flex;align-items:center;gap:8px}.diagram-mention .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## 它是如何工作的 {#how-it-works}
+
+当发送包含 `@` 提及的消息时，服务器上会发生以下情况：
+
+1. 服务器从消息中提取提及引用
+2. 对于每个提到的代理：
+   - 自定义代理按照其配置文件说明在本地运行
+   - 通过 A2A 调用连接的代理
+3. 代理的响应被包装在 `<agent-response>` XML 块中并注入到对话上下文中
+4. 主代理处理丰富的消息，查看用户的文本和提到的代理的响应
+
+主代理在其上下文中看到的内容：
+
+```text
+User: Draft an email with the latest signup numbers. @analytics
+
+<agent-response agent="analytics">
+Last week's signups: 1,247 total
+  - Organic: 623
+  - Paid: 412
+  - Referral: 212
+</agent-response>
+```
+
+然后，主代理可以在其响应中自然地使用这些数据 - 例如，将这些数字合并到电子邮件草稿中。
+
+```an-callout
+{
+  "tone": "info",
+  "body": "Mentioned-agent output arrives as an `<agent-response agent=\"…\">` block in the **main agent's** context — not as separate chat bubbles. The main agent decides how to weave it into the reply."
+}
+```
+
+## 添加代理 {#adding-agents}
+
+可以通过多种机制提及代理：
+
+- **自定义工作区代理** — 在“工作区”选项卡中创建代理配置文件为 `agents/*.md`
+- **自动发现** - 框架自动发现在已知端口或配置的 URL 上运行的连接代理
+- **远程清单** — 添加连接代理清单为 `remote-agents/*.json`
+
+### 自定义工作区代理
+
+自定义代理是存储在工作区中的 Markdown 文件：
+
+```markdown
+---
+name: Design
+description: Reviews layouts, product UX, and visual direction.
+model: inherit
+---
+
+You are a focused design agent.
+```
+
+请参阅 [Workspace — Custom Agents](/docs/workspace#custom-agents) 了解完整格式（包括 `tools`、`delegate-default` 和模型覆盖）。
+
+您可以使用以下方法从“工作区”选项卡创建它们：
+
+- `Create Agent` -> `Describe It`
+- `Create Agent` -> `Fill Form`
+
+### 连接代理清单
+
+远程 A2A 代理仍然使用 JSON 清单：
+
+```json
+// remote-agents/analytics.json
+{
+  "name": "Analytics Agent",
+  "url": "https://analytics.example.com",
+  "apiKey": "env:ANALYTICS_A2A_KEY",
+  "description": "Runs analytics queries and returns data",
+  "skills": ["run-query", "generate-chart"]
+}
+```
+
+---
+
+## 对于开发者：扩展提及 {#extending-mentions}
+
+模板可以注册自定义提及提供程序，以添加代理和文件之外的特定于域的可提及项目。提及提供者实现了 `MentionProvider` 接口：
+
+```an-annotated-code title="A custom MentionProvider"
+{
+  "filename": "server/mentions/contacts.ts",
+  "language": "ts",
+  "code": "import type { MentionProvider } from \"@agent-native/core/server\";\n\nconst contactsProvider: MentionProvider = {\n  id: \"contacts\",\n  label: \"Contacts\",\n\n  // Search for mentionable items\n  async search(query: string) {\n    const contacts = await db.query.contacts.findMany({\n      where: like(contacts.name, `%${query}%`),\n      limit: 10,\n    });\n    return contacts.map((c) => ({\n      id: c.id,\n      label: c.name,\n      description: c.email,\n      type: \"contact\",\n    }));\n  },\n\n  // Resolve a mention into context for the agent\n  async resolve(id: string) {\n    const contact = await db.query.contacts.findFirst({\n      where: eq(contacts.id, id),\n    });\n    return {\n      type: \"context\",\n      text: `Contact: ${contact.name} (${contact.email})`,\n    };\n  },\n};",
+  "annotations": [
+    { "lines": "4-5", "label": "Identity", "note": "`id` namespaces the provider; `label` is the section heading shown in the `@` popover." },
+    { "lines": "8-9", "label": "search", "note": "Runs as the user types after `@`. Return up to a handful of matches as `{ id, label, description, type }`." },
+    { "lines": "23-24", "label": "resolve", "note": "Called when the message is sent. Turns a picked id into `{ type: \"context\", text }` that is injected into the agent's context." }
+  ]
+}
+```
+
+在代理聊天插件配置中注册提供商：
+
+```ts
+// server/plugins/agent-chat.ts
+import { createAgentChatPlugin } from "@agent-native/core/server";
+
+export default createAgentChatPlugin({
+  actions: scriptRegistry,
+  systemPrompt: "You are a helpful assistant...",
+  mentionProviders: { contacts: contactsProvider },
+});
+```
+
+自定义提及提供程序与内置代理和文件提供程序一起显示在提及弹出窗口中。
+
+## 引用文件 {#referencing-files}
+
+`@` 弹出窗口不仅限于代理。您还可以参考：
+
+- **代码库文件** — 输入 `@` 并搜索文件名。文件内容包含在代理的上下文中，因此它可以读取、分析或修改文件。
+- **工作空间资源** — 在“工作空间”选项卡中定义的参考文件。这些可以是数据文件、配置或任何其他结构化内容。
+- **Skills** — 输入 `/` 来引用技能。 Skills 提供结构化指令来指导代理如何处理任务。
+
+所有引用类型都遵循相同的模式：从弹出窗口中进行选择，发送消息时引用的内容将被解析并注入到代理的上下文中。
+
+## 子代理选择 {#sub-agent-selection}
+
+当使用 `agent-teams` 生成子代理时，主代理还可以使用自定义代理（操作：“spawn”）。
+
+传递`agent`参数以从`agents/*.md`中选择配置文件。该配置文件的指令将添加到委托运行中，并且其 `model` frontmatter 可以覆盖该子代理的默认模型。

package/corpus/core/docs/content/locales/zh-CN/agent-surfaces.md

@@ -0,0 +1,397 @@
+---
+title: "特工表面"
+description: "将 Agent-Native 无头使用，作为丰富的聊天，在现有应用程序中，或作为完整的代理本机应用程序。"
+search: "无头代理丰富聊天完整应用程序 BYO 代理运行时 AgentChatRuntime 嵌入 actions MCP A2A HTTP CLI"
+---
+
+# 特工表面
+
+Agent-Native 是故意可组合的。不用太多就可以使用代理UI，
+在没有内置代理运行时的情况下使用 UI，或者将两者一起用作完整的
+应用程序。
+
+有用的选择方法不是先按协议。选择产品表面
+你想要，然后使用匹配的原语。
+
+| 表面                          | 什么时候使用它                                                                   | 开始于                                                                                      |
+| ----------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| **无头代理**                  | 代码、作业、脚本、另一个应用程序或另一个代理应直接调用该工作。                   | `agent-native create --headless`, `defineAction`, `agent-native agent`, HTTP, CLI, MCP, A2A |
+| **Agent-Native 上的丰富聊天** | 您想要由内置代理循环支持的独立或嵌入式聊天。                                     | [Chat template](/docs/template-chat), `<AgentChatSurface>`, `<AssistantChat>`               |
+| **与您的代理进行丰富的聊天**  | 您在其他地方构建了代理，并想要 Agent-Native 的编写器、脚本、工具卡和本机小部件。 | `AgentChatRuntime`, `<AssistantChat runtime={runtime}>`                                     |
+| **嵌入式边车**                | 您已经有一个 SaaS 应用程序，并希望在其旁边有一个具有页面上下文和主机命令的代理。 | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded`                                  |
+| **完整应用程序**              | 人类和代理应该共享持久的屏幕、数据、导航和协作。                                 | 模板、actions、SQL 状态、上下文感知                                                         |
+
+这些是阶段，而不是单独的产品。工作流程可以以无头方式启动
+代理只需执行一个操作，就会以表格或图表的形式出现在聊天中，然后成为
+应用程序中的全屏，而不更改代理调用的操作。
+
+```an-diagram title="The surface spectrum" summary="One action surface, four product shapes — each adds UI without changing the operation underneath."
+{
+  "html": "<div class=\"diagram-spectrum\"><div class=\"diagram-card\"><strong>Headless</strong><small class=\"diagram-muted\">actions, jobs, scripts, other agents</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><strong>Rich chat</strong><small class=\"diagram-muted\">composer, transcript, tool cards</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><strong>Embedded sidecar</strong><small class=\"diagram-muted\">agent beside an existing app</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card accent-card\"><span class=\"diagram-pill accent\">most UI</span><strong>Full application</strong><small class=\"diagram-muted\">durable screens, data, collaboration</small></div></div><div class=\"diagram-base\" data-rough><span class=\"diagram-muted\">same actions · same SQL · same agent loop</span></div>",
+  "css": ".diagram-spectrum{display:flex;align-items:stretch;gap:10px;flex-wrap:wrap}.diagram-spectrum .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;min-width:150px;flex:1}.diagram-spectrum .diagram-arrow{align-self:center;font-size:22px;line-height:1}.diagram-base{margin-top:12px;padding:10px 14px;text-align:center}"
+}
+```
+
+## 无头代理 {#headless}
+
+当没有人需要盯着自定义应用屏幕时，请使用无头路径
+工作运行：计划作业、集成、后端工作流程、CLI 循环，
+另一个代理或调用 Agent-Native 的现有产品。
+
+这也是当**代理*是*产品**时要达到的形状 -
+app-agent 循环是前门，而不是仪表板。您从
+终端、Slack、电子邮件、预定工作、其他代理或聊天 —“总结我的
+未读电子邮件，”“将每日指标发布到 Slack，”“查找符合以下条件的候选人
+上周回复”——代理执行操作并返回结果
+属于。它仍然是一个真正的应用程序，而不是无状态提示：actions，身份验证会话，
+应用程序状态、线程/运行历史记录、设置、凭据和共享记录全部实时
+在SQL。
+
+在以下情况下选择此模式：
+
+- **工作在后台进行。**大部分价值是在用户不注意的时候创造的 - 分类代理、每日报告代理、待命响应人员。
+- **输出离开应用程序。**代理发布到 Slack、发送电子邮件或更新第三方系统；应用内没有任何内容可供浏览。
+- **该域是一次性的。**研究机器人、摘要生成器、报告编写器 - 没有需要列表视图的持久对象。
+- **您正在制作原型。**立即发送代理；如果用户想要的话，稍后添加更丰富的 UI。
+
+如果您的产品是围绕持久对象构建的，用户会浏览、透视和
+分享 — 电子邮件、事件、文档、图表 — 选择 [full application](#full-application)
+或 [template](/docs/cloneable-saas) 代替；这些添加了完整的 UI _plus_ 代理。
+
+### 盒子里装的是什么 {#in-the-box}
+
+无头应用程序会跳过数周的仪表板工作，并且从一天开始就与渠道无关
+一个 - 同一代理从网络、Slack、Telegram、电子邮件和其他代理运行
+因为一切都通过代理，而不是 UI。权衡是有的
+没有“一目了然地浏览所有内容”视图；如果用户需要，请混合模式和
+添加小型状态页面或列表视图。
+
+当添加内置的Chat shell时，框架提供了五种管理
+您不必构建的界面：**聊天**（主要输入）、**工作区**
+（skills、内存、指令、子代理、连接的 MCP 服务器、已调度
+jobs）、**作业历史记录**、**线程历史记录**和**设置**。这些通常是
+足够了——与它交谈，看看它做了什么，配置它的行为方式。伸手去拿
+[Chat](/docs/template-chat) 当您准备好添加浏览器 UI 时，或
+[Dispatch template](/docs/template-dispatch) 工作空间式启动
+使用 Slack/Telegram、计划作业和开箱即用的共享机密。
+
+最小的本地路径是无头代理脚手架加上一个操作：
+
+```bash
+npx @agent-native/core@latest create my-agent --headless
+cd my-agent
+pnpm install
+```
+
+然后定义持久操作：
+
+```ts
+// actions/summarize-week.ts
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Summarize this week's submissions.",
+  readOnly: true,
+  schema: z.object({ formId: z.string() }),
+  run: async ({ formId }) => {
+    return { formId, summary: "34 submissions, up 18% from last week." };
+  },
+});
+```
+
+然后可以调用一个操作：
+
+- **HTTP** — `POST /_agent-native/actions/summarize-week`
+- **CLI** — `pnpm action summarize-week --formId form_123`
+- **应用程序代理 CLI** — `pnpm agent "Summarize form_123"`
+- **MCP** — 来自 Claude、ChatGPT、Codex、Cursor、OpenCode、Copilot 和其他 MCP 主机
+- **A2A** - 来自另一个代理本机应用程序或代理对等点
+- **UI** — 通过 `useActionQuery`、`useActionMutation` 或 `callAction`
+- **代理工具** - 来自内置聊天循环
+
+```an-api title="Calling an action over HTTP"
+{
+  "method": "POST",
+  "path": "/_agent-native/actions/summarize-week",
+  "summary": "Invoke any action by name over HTTP",
+  "description": "Every `defineAction` is auto-mounted at `/_agent-native/actions/<name>`. The JSON body is validated against the action's zod schema before `run` executes.",
+  "request": {
+    "contentType": "application/json",
+    "example": "{ \"formId\": \"form_123\" }"
+  },
+  "responses": [
+    { "status": "200", "description": "The action's return value as JSON", "example": "{ \"formId\": \"form_123\", \"summary\": \"34 submissions, up 18% from last week.\" }" },
+    { "status": "400", "description": "Input failed schema validation" }
+  ]
+}
+```
+
+这不是无数据库或无状态模式。应用程序代理循环存储会话，
+线程、运行、设置、凭据、应用程序状态和共享记录
+SQL。本地开发默认为SQLite；托管无头应用程序应使用
+持久 SQL 数据库。
+
+如果您需要从项目文件夹中无头地执行整个代理循环，请使用：
+
+```bash
+pnpm agent "Summarize this week's forms."
+```
+
+如果另一个应用程序或脚本需要调用整个代理，请使用
+`agentNative.invoke("analytics", "...")` 或 `agent-native invoke` CLI。那
+将跨应用工作保留在 A2A 路径上，而本地工作保留在 actions 上。
+
+工作人员、作业、集成 webhooks 和自定义主机可以驱动代理循环
+直接通过服务器API。这比 actions 级别低 - 您提供
+您自己的引擎、模型、消息、actions 和事件接收器：
+
+```ts
+import { runAgentLoop } from "@agent-native/core/server";
+
+await runAgentLoop({ engine, model, systemPrompt, actions, messages, send });
+```
+
+对于大多数应用程序，计划的提示和集成 webhooks 已经调用此循环
+给你。仅在构建自定义无头主机时直接获取它，eval
+运行程序，或服务器端编排表面 - 请参阅[服务器 - 生产代理
+handler](/docs/server#agent-handler) 获取完整签名。
+
+### 针对文件夹运行 {#folder-loop}
+
+如果您的目标是“针对此文件夹运行代理”，请从应用程序代理开始
+在该文件夹中循环：构建无头应用程序，添加 actions/指令，运行
+`pnpm agent "..."`。这使工作保持在相同的操作/运行时/状态内
+应用程序将在生产中使用的合同。
+
+外部编码线束是用于嵌入 Claude 的独立产品表面
+Agent-Native 应用内的代码、Codex、Pi、Cursor、Mastra 或类似运行时。
+在构建编码代理产品时使用它们，而不是作为默认方式
+启动本地代理本机工作流程。
+
+### 云存储库访问 {#cloud-repo-access}
+
+对于需要存储库访问的云无头应用程序，请使用 GitHub 连接器
+加上代币CRUD模型：列出存储库、搜索文件、读取文件、创建或
+通过提供商范围编辑文件、删除文件和撤销访问权限
+凭证。在本地开发中，明确设置目标存储库：
+
+```bash
+GITHUB_REPOSITORY=owner/repo pnpm agent "Read README.md and suggest the next action."
+```
+
+不要将虚拟机克隆或长期沙箱签出视为主要云
+存储库访问模型。沙箱对于隔离代码执行仍然很重要，但是
+存储库访问应该是明确的、经过许可的、可审核的和可撤销的
+通过连接器层。
+
+### 共享会话和运行 {#sharing-runs}
+
+无头会话和运行是持久对象。共享性应该分阶段进行：
+首先阅读/共享链接，以便队友可以检查经过清理的提示、输出
+和运行状态；稍后授予可写协作权限，因此继续运行，
+批准 actions、编辑计划或更改配置已完成
+显式访问检查。
+
+## Agent-Native 上的丰富聊天 {#rich-chat}
+
+当用户应该与代理交谈时使用内置聊天，查看工具调用，
+批准工作、检查本机结果并保留持久的线程历史记录。
+
+要获得完整的应用程序起点，请使用 [Chat template](/docs/template-chat)：
+
+```bash
+npx @agent-native/core@latest create my-chat-app --template chat
+```
+
+最简单的全页聊天：
+
+```tsx
+import { AgentChatSurface } from "@agent-native/core/client/chat";
+
+export default function ChatRoute() {
+  return <AgentChatSurface mode="page" className="h-screen" />;
+}
+```
+
+当应用同时具有全页聊天选项卡和 `AgentSidebar` 时，请使用相同的
+在两个表面上安装`storageKey`，启用`chatViewTransition`，并安装
+布局中的聊天主页切换助手。聊天之外的普通应用内链接
+页面可以将完整的聊天内容转变为侧边栏，同时保持活动状态
+线程：
+
+```tsx
+import {
+  AgentChatSurface,
+  AgentSidebar,
+  useAgentChatHomeHandoff,
+  useAgentChatHomeHandoffLinks,
+} from "@agent-native/core/client/chat";
+import { useLocation } from "react-router";
+
+function ChatRoute() {
+  return (
+    <AgentChatSurface mode="page" storageKey="my-app" chatViewTransition />
+  );
+}
+
+function AppLayout({ children }: { children: React.ReactNode }) {
+  const location = useLocation();
+  const handoffActive = useAgentChatHomeHandoff({
+    storageKey: "my-app",
+    activePath: location.pathname,
+    enabled: location.pathname !== "/chat",
+  });
+  useAgentChatHomeHandoffLinks({ storageKey: "my-app", chatPath: "/chat" });
+
+  return (
+    <AgentSidebar
+      storageKey="my-app"
+      chatViewTransition
+      openOnChatRunning={handoffActive}
+    >
+      {children}
+    </AgentSidebar>
+  );
+}
+```
+
+使用您自己的 chrome 进行最简单的嵌入式聊天：
+
+```tsx
+import { AssistantChat } from "@agent-native/core/client/chat";
+
+export function ProjectChat({ threadId }: { threadId: string }) {
+  return <AssistantChat threadId={threadId} />;
+}
+```
+
+Actions 可以返回显式的本机小部件结果，因此聊天输出不仅仅是
+文本。表格、图表和键入的产品卡呈现为第一方 React
+聊天中的组件，没有 iframe。参见[Native Chat UI](/docs/native-chat-ui)。
+
+## 与您的代理进行丰富的聊天 {#byo-agent}
+
+当您的代理已使用其他框架构建时，请使用此路径
+运行时，你想要 Agent-Native 的聊天 UI 围绕它。 `AgentChatRuntime` 是
+边界：您的运行时流规范化事件，Agent-Native 呈现
+作曲家、脚本、工具调用、批准、本机小部件和应用布局。
+
+```tsx
+import {
+  AssistantChat,
+  createHttpAgentChatRuntime,
+} from "@agent-native/core/client/chat";
+
+const runtime = createHttpAgentChatRuntime({
+  endpoint: "/api/support-agent/chat",
+});
+
+export function SupportAgentChat() {
+  return <AssistantChat runtime={runtime} threadId="support" />;
+}
+```
+
+针对 OpenAI 代理、OpenAI 响应、Claude 存在现成的运行时助手
+Agent SDK、Vercel AI SDK 和 AG-UI，以及上面的标准化 HTTP 运行时
+对于任何其他代理（Mastra、Flue、Eve、LangGraph 或自定义服务）。 ACP 是
+不是最终用户应用聊天或 A2A 传输，并且 Agent-Native 目前没有
+要求 A2UI 支持。 ACP 在一个特定位置受支持 - 驾驶本地
+编码代理（Gemini CLI，Claude代码，...）通过
+[harness layer](/docs/harness-agents#acp)，这里不作为聊天运行时。
+
+[Native Chat UI — BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes)
+是事件形状、运行时助手和 `chatUI` 的规范主页
+工具结果元数据。将外部代理连接到聊天中时从这里开始。
+
+## 嵌入式边车 {#embedded-sidecar}
+
+当主产品已经存在并且您想要一个时，请使用嵌入式 sidecar
+代理在旁边。
+
+服务器插件将 Agent-Native 路由安装到您的主机应用程序中并解析
+主机身份服务器端：
+
+```ts
+import { createAgentNativeEmbeddedPlugin } from "@agent-native/core/server";
+
+export default createAgentNativeEmbeddedPlugin({
+  databaseUrl: process.env.AGENT_NATIVE_DATABASE_URL,
+  auth: getHostSession,
+  actions: hostActions,
+});
+```
+
+React sidecar 传递页面上下文和主机命令：
+
+```tsx
+import { AgentNativeEmbedded } from "@agent-native/core/client";
+
+export function AppShell({ children }) {
+  return (
+    <AgentNativeEmbedded
+      getContext={() => ({
+        route: { pathname: window.location.pathname },
+        selection: { text: window.getSelection()?.toString() || undefined },
+      })}
+      onNavigate={(payload) =>
+        router.navigate((payload as { path: string }).path)
+      }
+      onRefresh={() => queryClient.invalidateQueries()}
+    >
+      {children}
+    </AgentNativeEmbedded>
+  );
+}
+```
+
+```an-diagram title="How the sidecar bridges to a host app" summary="The plugin mounts Agent-Native routes server-side; the React sidecar streams page context in and host commands out."
+{
+  "html": "<div class=\"diagram-sidecar\"><div class=\"diagram-panel\"><strong>Host app</strong><small class=\"diagram-muted\">your existing SaaS</small><div class=\"diagram-node\">getContext()<br><small class=\"diagram-muted\">route · selection</small></div><div class=\"diagram-node\">onNavigate / onRefresh<br><small class=\"diagram-muted\">host commands</small></div></div><div class=\"diagram-col-arrows\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&larr;</div></div><div class=\"diagram-panel accent-panel\"><span class=\"diagram-pill accent\">AgentNativeEmbedded</span><small class=\"diagram-muted\">agent + workspace</small><div class=\"diagram-box\" data-rough>Agent-Native routes<br><small class=\"diagram-muted\">mounted by the server plugin</small></div></div></div>",
+  "css": ".diagram-sidecar{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-sidecar .diagram-panel{display:flex;flex-direction:column;gap:8px;padding:14px 16px;min-width:200px}.diagram-sidecar .diagram-col-arrows{display:flex;flex-direction:column;gap:6px}.diagram-sidecar .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+请参阅 [Embedding SDK](/docs/embedding-sdk) 以了解主机身份验证、数据库隔离，
+iframe/picker 模式，以及较低级别的桥 APIs。
+
+## 完整应用程序 {#full-application}
+
+当用户需要持久对象和工作流程时使用完整的应用路径：表单，
+仪表板、日历、收件箱、编辑器、文档、资产或报告。
+
+完整应用程序围绕相同的操作和代理合同添加产品 UI：
+
+- **SQL 状态** — 应用数据、导航、设置和聊天历史记录是持久的。
+- **上下文感知** - 代理知道当前路线、选择和聚焦对象。
+- **实时同步** - 代理更改会更新 UI，UI 更改会更新代理的上下文。
+- **深层链接** — 操作结果可以打开正确的应用视图。
+- **本机聊天小部件** — 表格、图表、卡片、批准和键入的结果内联显示。
+
+当您想要一个最小的应用程序时，请从 [Chat template](/docs/template-chat) 开始
+您的 actions 周围，或来自域 [template](/docs/cloneable-saas)，当您
+想要一个完整的产品形状。
+
+## 如何选择 {#how-to-choose}
+
+| 如果您在想...                                        | 选择                      |
+| ---------------------------------------------------- | ------------------------- |
+| “我只需要一个可调用的工具或工作流程。”               | 无头代理                  |
+| “我想要框架的代理，但是聊天应该是主要的UI。”         | Agent-Native 上的丰富聊天 |
+| “我已经有一个代理；我需要一个完美的聊天 UI。”        | 与您的代理进行丰富的聊天  |
+| “我已经有一个 SaaS 应用程序；在它旁边添加一个代理。” | 嵌入式边车                |
+| “代理和 UI 应该作为产品一起进化。”                   | 完整应用程序              |
+
+保持合约较小：将持久操作定义为 actions，显式返回
+聊天需要丰富UI时的小部件结果，并且仅在用户时添加全屏
+需要浏览、比较、配置或协作持久对象。
+
+## 相关文档 {#related-docs}
+
+- [Actions](/docs/actions) — 定义一次无头操作。
+- [Native Chat UI](/docs/native-chat-ui) — 在聊天中呈现键入的操作结果。
+- [Drop-in Agent](/docs/drop-in-agent) — 安装聊天、侧边栏或面板表面。
+- [Component API](/docs/components) — 较低级别的 React 聊天/作曲片段。
+- [Embedding SDK](/docs/embedding-sdk) — 将 Agent-Native 添加到现有应用。
+- [External Agents](/docs/external-agents) — 将 MCP 兼容主机连接到应用。
+- [A2A Protocol](/docs/a2a-protocol) — 从其他座席呼叫座席。