@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/zh-CN/tracking.md

@@ -0,0 +1,236 @@
+---
+title: "跟踪和分析"
+description: "使用可插入提供程序进行服务器端分析 - PostHog、Mixpanel、Amplitude 或自定义 Webhook"
+---
+
+# 分析跟踪
+
+一个功能，多个目的地。从任何服务器端代码（actions、插件、服务器路由）调用 `track()`，事件就会分发到每个注册的分析提供商。没有 SDK 依赖性，没有客户端脚本，没有阻塞。相同的 `track()` 也可在 [browser/app code](#client) 中使用，并路由至相同的提供商。
+
+这是*product*分析——您的应用程序的事件流向PostHog/Mixpanel/Amplitude。有关存储在您自己的数据库中的*代理质量*指标（跟踪、成本、评估、反馈），请参阅 [Observability](/docs/observability)。
+
+```ts
+import { track } from "@agent-native/core/tracking";
+
+track(
+  "order.completed",
+  { total: 49.99, items: 3 },
+  { userId: "steve@builder.io" },
+);
+```
+
+```an-diagram title="One track() call, every provider" summary="Server and client callers hit the same registry, which fans every event out to all active providers in parallel."
+{
+  "html": "<div class=\"trk\"><div class=\"diagram-col\"><div class=\"diagram-node\">Server code<br><small class=\"diagram-muted\">actions &middot; plugins &middot; routes</small></div><div class=\"diagram-node\">Browser code<br><small class=\"diagram-muted\">POST /_agent-native/track</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Provider registry</span><small class=\"diagram-muted\">fan-out, fire-and-forget</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box\">PostHog</div><div class=\"diagram-box\">Mixpanel</div><div class=\"diagram-box\">Amplitude</div><div class=\"diagram-box\">Webhook</div></div></div>",
+  "css": ".trk{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.trk .diagram-col{display:flex;flex-direction:column;gap:8px}.trk .diagram-arrow{font-size:22px;line-height:1}.trk .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## 内置提供程序 {#built-in}
+
+设置环境变量，提供程序会在服务器启动时自动注册。无需更改代码。
+
+| 提供商   | 环境变量                                                                             |
+| -------- | ------------------------------------------------------------------------------------ |
+| PostHog  | `POSTHOG_API_KEY`（必填）、`POSTHOG_HOST`（可选，默认为`https://us.i.posthog.com`）  |
+| 混合面板 | `MIXPANEL_TOKEN`                                                                     |
+| 振幅     | `AMPLITUDE_API_KEY`                                                                  |
+| Webhook  | `TRACKING_WEBHOOK_URL`（必需）、`TRACKING_WEBHOOK_AUTH`（可选 `Authorization` 标头） |
+
+多个提供程序可以同时处于活动状态。每个事件都会发生在他们所有人身上。
+
+## API {#api}
+
+### `track(name, properties?, meta?)` {#track}
+
+触发分析事件。扇出到所有注册的提供商。
+
+```ts
+import { track } from "@agent-native/core/tracking";
+
+track(
+  "meal.logged",
+  { mealName: "Salad", calories: 350 },
+  { userId: "steve@builder.io" },
+);
+```
+
+### `identify(userId, traits?)` {#identify}
+
+识别具有特征的用户。转发给支持它的提供商（PostHog、Mixpanel、Amplitude、webhook）。
+
+```ts
+import { identify } from "@agent-native/core/tracking";
+
+identify("steve@builder.io", { plan: "pro", company: "Builder.io" });
+```
+
+需要自定义后端、提供程序注册表 API 或批处理/单例内部组件？见最后的[Advanced: custom providers & internals](#advanced)。
+
+## 在模板中使用 track() {#templates}
+
+从操作处理程序调用 `track()` 以记录用户或代理活动：
+
+```ts
+// actions/create-project.ts
+import { defineAction } from "@agent-native/core/action";
+import { track } from "@agent-native/core/tracking";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Create a new project.",
+  schema: z.object({
+    name: z.string(),
+    template: z.string().optional(),
+  }),
+  run: async ({ name, template }, ctx) => {
+    const project = await db
+      .insert(projects)
+      .values({ name, template })
+      .returning();
+
+    track("project.created", { name, template }, { userId: ctx.userEmail });
+
+    return { ok: true, projectId: project[0].id };
+  },
+});
+```
+
+跟踪调用是“即发即忘”的 — 它们会立即返回并且永远不会阻止操作响应。
+
+## 客户端跟踪 {#client}
+
+`track()` 也适用于浏览器/应用程序代码。从 `@agent-native/core/client` 导入客户端孪生并以相同的方式调用它 - 它将事件发布到 `POST /_agent-native/track` 的框架路由，后者将其转发到**相同**注册的服务器端提供程序（PostHog、Mixpanel、Amplitude、webhook）。没有分析 SDK 发送到浏览器，也没有提供者密钥暴露在客户端。
+
+```an-api title="The client tracking route"
+{
+  "method": "POST",
+  "path": "/_agent-native/track",
+  "summary": "Forward a browser event to the registered server-side providers",
+  "auth": "Session required + same-origin/CSRF marker (set automatically by the client helper). Not an open analytics relay.",
+  "params": [
+    { "name": "name", "in": "body", "type": "string", "required": true, "description": "Event name. Capped at 200 characters." },
+    { "name": "properties", "in": "body", "type": "object", "description": "Event properties (~16KB cap). `source: \"client\"` and the active `org_id` are added server-side." }
+  ],
+  "description": "Identity is resolved **server-side** from the session — browser code never passes a `userId`. Fire-and-forget: never blocks the UI, never throws, swallows network errors. Oversized or malformed payloads are rejected."
+}
+```
+
+```ts
+import { track } from "@agent-native/core/client";
+
+// e.g. inside a click handler or effect
+track("checkout.completed", { total: 49.99, items: 3 });
+```
+
+与 [server `track()`](#track) 的主要区别：
+
+- **无身份参数。** 该事件在服务器端归因于登录用户（以及活动组织，如 `properties` 中的 `org_id`）。浏览器代码永远不会传递 `userId`。
+- **`source: "client"`** 添加到每个事件的属性中，以便您可以区分客户端发起的事件和服务器事件。
+- **一劳永逸。**它永远不会阻塞 UI，永远不会抛出并吞掉网络错误。
+- **经过身份验证，仅限第一方。** 该路由需要会话和同源/CSRF 标记（由帮助程序自动设置），因此它不能用作开放分析中继。 `name` 的上限为 200 个字符，`properties` 的上限为 ~16KB；过大或格式错误的有效负载将被拒绝。
+
+这与框架的内部浏览器遥测（`trackEvent()` /自动页面浏览量 - 请参阅下面的 [Browser defaults](#browser-defaults)）不同，后者为 Agent Native 自己的产品分析提供支持。将 `track()` 用于您的应用自己的分析事件，这些事件应到达您配置的提供商。
+
+## 高级：自定义提供程序和内部结构 {#advanced}
+
+大多数应用程序只需要 `track()` / `identify()` 和内置提供程序。表面的其余部分 - 注册自定义提供程序、`TrackingProvider` 接口、批处理内部结构以及框架自己的浏览器遥测 - 如下。
+
+<details>
+<summary><strong>Provider-registry API、界面、内部结构和浏览器默认值</strong></summary>
+
+### `registerTrackingProvider(provider)` {#register}
+
+为任何分析后端注册自定义提供商。
+
+```ts
+import { registerTrackingProvider } from "@agent-native/core/tracking";
+
+registerTrackingProvider({
+  name: "my-analytics",
+  track(event) {
+    // Send event to your backend
+    fetch("https://analytics.example.com/events", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(event),
+    }).catch(() => {});
+  },
+  identify(userId, traits) {
+    // Optional — link user identity to future events
+  },
+  flush() {
+    // Optional — called on graceful shutdown
+  },
+});
+```
+
+### `flushTracking()` {#flush}
+
+刷新所有提供者。在进程退出之前调用以确保发送待处理事件。
+
+```ts
+import { flushTracking } from "@agent-native/core/tracking";
+
+await flushTracking();
+```
+
+### `unregisterTrackingProvider(name)` {#unregister}
+
+按名称删除提供商。如果找到并删除了提供者，则返回 `true`。
+
+### `listTrackingProviders()` {#list}
+
+返回所有已注册提供商的名称。
+
+### TrackingProvider 接口 {#provider-interface}
+
+```ts
+interface TrackingProvider {
+  name: string;
+  track(event: TrackingEvent): void | Promise<void>;
+  identify?(
+    userId: string,
+    traits?: Record<string, unknown>,
+  ): void | Promise<void>;
+  flush?(): void | Promise<void>;
+}
+
+interface TrackingEvent {
+  name: string;
+  properties?: Record<string, unknown>;
+  timestamp?: string;
+  userId?: string;
+}
+```
+
+仅需要 `name` 和 `track`。 `identify` 和 `flush` 是可选的 - 如果您的后端支持用户身份和批量交付，请实现它们。
+
+### 它是如何工作的 {#internals}
+
+- **批处理 HTTP** — 内置提供程序将事件排队并每 10 秒或累积 50 个事件时刷新（以先到者为准）。这可以最大限度地减少出站请求，而不会丢失数据。
+- **无 SDK 依赖项** — 所有内置提供程序都使用原始 `fetch()`。没有 PostHog SDK，没有 Mixpanel SDK，没有 Amplitude SDK。保持框架轻量级。
+- **尽力交付** - 捕获并记录提供者错误。失败的分析集成绝不会导致调用者崩溃或阻止请求处理。
+- **全局单例** - 注册表在 `globalThis` 上使用 `Symbol.for` 密钥，因此多个 ESM 图形实例（开发模式 Vite + Nitro、符号链接）共享一个提供程序集。
+
+### 浏览器默认值 {#browser-defaults}
+
+这涵盖了框架自己的内部遥测——主要与框架贡献者和高级模板作者相关。
+
+模板根在启动时调用 `configureTracking()` 一次。当应用程序可以解析它时，使用 `trackEvent()` 发送的浏览器事件会自动包含应用程序/模板上下文以及当前的 LLM 连接：
+
+- `llm_connection` — 标准化提供商标签，例如 `builder`、`anthropic`、`openai`、`google` 或 `none`
+- `llm_engine` — 引擎 ID，例如 `builder` 或 `ai-sdk:openai`
+- `llm_model` — 已知时选择/默认的模型
+- `llm_connection_source` — `app_secrets`、`settings` 或 `env`
+- `llm_connection_configured` — LLM 连接是否可用
+
+该框架还跟踪来自 Connect Builder CTA 的 `builder connect clicked`，服务器端 Builder 连接路由跟踪已启动/成功/失败的生命周期事件。 `configureTracking()`由框架自动调用；您不需要在自己的模板代码中调用它。
+
+</details>
+
+## 下一步是什么
+
+- [**Actions**](/docs/actions) — 大多数跟踪调用的发起位置
+- [**Server Plugins**](/docs/server) - `registerBuiltinProviders()` 在启动时在 core-routes 插件中运行
+- [**Secrets**](/docs/security) — 管理用于跟踪提供商的 API 密钥

package/docs/content/locales/zh-CN/using-your-agent.md

@@ -0,0 +1,71 @@
+---
+title: "使用您的代理"
+description: "与代理合作的日常循环：它看到您正在查看的内容，您指导它，嵌入它，使用 UI-light，并与它一起共同编辑。"
+---
+
+# 使用您的代理
+
+agent-native 背后的定义思想是，agent 和 UI 是**平等的伙伴** - 请参阅 [What Is Agent-Native?](/docs/what-is-agent-native) 了解原因。本节介绍该承诺的另一半：一旦代理停靠在您的应用旁边，实际使用该代理的感觉如何。
+
+有一条简单的直通线。代理**看到**您正在查看的内容，您**将其引导**到您想要的内容，您可以**嵌入**它在任何地方，您可以在更合适的情况下完全**UI-light**，并且您可以同时**共同编辑**相同的文档。其中每一个都是本节中的一个页面。
+
+```an-diagram title="The day-to-day loop" summary="Five ways of working with a docked agent — each is a page in this section."
+{
+  "html": "<div class=\"diagram-loop\"><div class=\"diagram-card\"><strong>Sees</strong><small class=\"diagram-muted\">your view &amp; selection</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><strong>Direct</strong><small class=\"diagram-muted\">@-mentions &amp; voice</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><strong>Embed</strong><small class=\"diagram-muted\">drop into any app</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><strong>UI-light</strong><small class=\"diagram-muted\">chat is the product</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card accent-card\"><span class=\"diagram-pill accent\">Co-edit</span><small class=\"diagram-muted\">live, side by side</small></div></div>",
+  "css": ".diagram-loop{display:flex;align-items:stretch;gap:10px;flex-wrap:wrap}.diagram-loop .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;min-width:130px;flex:1}.diagram-loop .diagram-arrow{align-self:center;font-size:22px;line-height:1}"
+}
+```
+
+## 它能看到你在看什么 {#it-sees}
+
+代理不会对您的屏幕视而不见。打开一封电子邮件，它就知道是哪个线程。选择一个图表，它就知道是哪个图表。突出显示一个段落，它可以只作用于该范围。这种共同的意识让您可以说“回复此内容”或“总结选择”，而无需每次都拼写出上下文。
+
+这是有效的，因为当前的导航和选择位于 `application_state` SQL 中，代理将其作为其上下文的一部分读取。代理还可以驱动相同的状态 - 打开视图，选择一行 - 这样你就可以看到它在真实的 UI 中而不是在脚本中工作。
+
+```an-callout
+{
+  "tone": "info",
+  "body": "**Shared awareness is two-way.** You and the agent both read and write `application_state`, so \"reply to this\" or \"summarize the selection\" just works — and when the agent navigates, the real UI moves with it."
+}
+```
+
+→ [**Context Awareness**](/docs/context-awareness) — 导航状态、视图屏幕、导航命令以及代理如何与您的屏幕保持同步。
+
+## 你指挥 {#you-direct-it}
+
+大多数时候，您通过在聊天中输入内容来引导代理。有两件事可以让速度更快。
+
+**提及。** 使用 `@` 标记自定义代理、连接的代理或文件，将其拉入对话中 — “让 `@analytics` 拉取上周的数据，然后起草摘要。”提及是您如何在不离开作曲家的情况下找到合适的专家或附加正确的上下文。
+
+**声音。**作曲家有麦克风。口述请求而不是键入请求，提供程序选项范围从 Builder 的托管转录到自带密钥到浏览器后备。
+
+→ [**Agent Mentions**](/docs/agent-mentions) - `@` - 在聊天中提及自定义代理、连接的代理和文件。
+→ [**Voice Input**](/docs/voice-input) — 聊天编辑器中的听写以及转录的路由方式。
+
+## 您嵌入它 {#you-embed-it}
+
+代理不是您通过 Tab 键切换到的单独应用程序。它以几个 React 组件的形式提供——一个侧边栏、一个原始面板和一个 `sendToAgentChat()` 调用——您可以将它们放入任何应用程序中。渲染 `<AgentSidebar>` 为每个屏幕提供一个可切换代理，或连接一个按钮将特定任务交给聊天，而不是运行一次性 LLM 调用。
+
+→ [**Drop-in Agent**](/docs/drop-in-agent) — 将 `<AgentPanel>`、`<AgentSidebar>` 和 `sendToAgentChat()` 安装到任何 React 应用程序中。
+→ [**Agent Surfaces**](/docs/agent-surfaces) — 选择工作流程是否应为无头、聊天优先、嵌入式或完整应用程序。
+
+## 你可以去UI-light {#ui-light}
+
+并非每个应用程序都需要完整的仪表板。当代理*是*产品时，您可以跳过大部分自定义UI：打开应用程序，询问您想要的内容，然后让代理完成其余的工作。代理仍然有其管理界面——历史记录、工作区、设置——但主要交互是对话而不是点击。
+
+→ [**Pure-Agent Apps**](/docs/pure-agent-apps) — 代理是整个产品的应用。
+
+## 您与它共同编辑 {#you-co-edit}
+
+当您和代理处理同一份文档时，你们不会轮流处理。通过实时协作，代理的编辑可以与您的编辑一起传输 - 实时光标，不会覆盖 - 与队友的编辑方式相同。您可以在它工作时继续输入，并且它会在发生更改时看到您的更改。
+
+→ [**Real-Time Collaboration**](/docs/real-time-collaboration) — 在同一文档中使用实时光标和代理编辑进行多用户协作编辑。
+
+## 下一步是什么 {#whats-next}
+
+- [**Context Awareness**](/docs/context-awareness) — 代理知道您在看什么
+- [**Agent Mentions**](/docs/agent-mentions) — 使用 `@` 提及来引导
+- [**Voice Input**](/docs/voice-input) — 通过说话进行指导
+- [**Drop-in Agent**](/docs/drop-in-agent) — 将其嵌入任何 React 应用
+- [**Pure-Agent Apps**](/docs/pure-agent-apps) — 当代理是产品时，采用 UI-light
+- [**Real-Time Collaboration**](/docs/real-time-collaboration) — 共同编辑同一文档

package/docs/content/locales/zh-CN/voice-input.md

@@ -0,0 +1,81 @@
+---
+title: "语音输入"
+description: "代理聊天编辑器中的语音听写 - Builder Gemini、BYOK 提供程序和浏览器 Web 语音后备。"
+---
+
+# 语音输入
+
+每个代理本机应用程序的聊天编辑器中都有一个麦克风。单击它，说话，您的话就会被转录到提示中。在移动设备上很有用，对于长提示很有用，当您的手放在其他东西上时很有用。
+
+框架会自动处理所有这些。 Builder连接的用户默认获得Builder托管的Gemini Flash-Lite；否则，用户可以携带自己的提供商密钥或退回到浏览器语音识别。
+
+## 它是如何工作的 {#how-it-works}
+
+作曲家的语音按钮在浏览器中录制音频，然后选择提供商：
+
+1. **Builder Gemini Flash-Lite（连接 Builder 时默认）。**浏览器将音频 POST 到 `/_agent-native/transcribe-voice`，`/_agent-native/transcribe-voice` 使用 Gemini Flash-Lite 通过 Builder.io 进行代理。无需 Google API 密钥。
+2. **BYOK 云提供商。** 用户可以从“设置”中选择 Google Gemini、Groq Whisper 或 OpenAI Whisper。该路由在共享部署凭据之前解析用户范围的加密机密。
+3. **浏览器网络语音 API（后备）。** 如果没有可用的服务器提供商，作曲家可以使用浏览器的内置语音识别。适用于基于 Chromium 的浏览器（Chrome、Edge、Arc）和 Safari。不太准确；直播。
+
+提供商选择存储在 `voice-transcription-prefs` 下的应用程序状态中，因此用户可以在侧边栏设置中强制使用 `"auto"`（默认 — 选择最佳的可用提供商）、`"builder-gemini"`、`"builder"`、`"gemini"`、`"groq"`、`"openai"` 或 `"browser"`。
+
+```an-diagram title="Voice transcription provider fallback" summary="The composer records audio, then walks server providers in order, dropping to the browser Web Speech API only when no server provider is available."
+{
+  "html": "<div class=\"diagram-voice\"><div class=\"diagram-node\">Mic button<br><small class=\"diagram-muted\">records webm/opus</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card col\"><div class=\"diagram-pill accent\">1 &middot; Builder Gemini</div><small class=\"diagram-muted\">default when Builder connected</small><div class=\"diagram-pill\">2 &middot; BYOK cloud</div><small class=\"diagram-muted\">Gemini &middot; Groq &middot; OpenAI Whisper</small></div><div class=\"diagram-arrow diagram-warn\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box diagram-warn\" data-rough>3 &middot; Browser Web Speech<br><small class=\"diagram-muted\">fallback on 400 &middot; streams live</small></div></div>",
+  "css": ".diagram-voice{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-voice .col{display:flex;flex-direction:column;gap:6px;padding:14px}.diagram-voice .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+该路由**仅限同源** - 跨站点 POST 被拒绝，因此攻击者无法从外部页面烧毁转录积分。
+
+## 启用提供商 {#enabling-providers}
+
+Builder 是最简单的路径：从“设置”连接 Builder.io，默认提供商变为 Builder Gemini Flash-Lite。对于 BYOK 提供商，请在“设置”→“API 密钥”中添加匹配的密钥。
+
+### 每用户（推荐用于 SaaS）
+
+用户通过代理侧边栏设置 UI 设置自己的密钥。它存储为用户范围的加密秘密（通过 `readAppSecret`）。每个用户为自己的转录付费；主机零成本。
+
+### 共享（用于内部工具）
+
+将 `GEMINI_API_KEY`、`GROQ_API_KEY` 或 `OPENAI_API_KEY` 设置为环境变量或在 `settings` 表中。每个用户的转录都会命中共享密钥。
+
+```an-callout
+{
+  "tone": "info",
+  "body": "**Credential resolution order:** the route checks the user's own encrypted secret first, then the shared deployment key. A power user with their own key always overrides the shared one. If neither exists, the route returns a 400 the composer recognizes and silently falls back to browser Web Speech."
+}
+```
+
+## 路线 {#route}
+
+```an-api title="Voice transcription route"
+{
+  "method": "POST",
+  "path": "/_agent-native/transcribe-voice",
+  "summary": "Transcribe a recorded audio clip into prompt text",
+  "auth": "Active session (Better Auth cookie). Same-origin only.",
+  "description": "The composer POSTs the recorded clip here; the route resolves a provider and returns the transcribed text. You should not call this directly.",
+  "params": [
+    { "name": "audio", "in": "body", "type": "file", "required": true, "description": "The recorded clip, webm/opus by default. Max 25 MB." },
+    { "name": "provider", "in": "body", "type": "string", "required": false, "description": "Optional override, e.g. gemini, groq, openai, builder." }
+  ],
+  "request": { "contentType": "multipart/form-data" },
+  "responses": [
+    { "status": "200", "description": "Transcription succeeded", "example": "{ \"text\": \"reply to Sara that I'll be there by 3\" }" },
+    { "status": "400", "description": "No server provider configured — the composer recognizes this and falls back to Web Speech", "example": "{ \"error\": \"no_provider\" }" }
+  ]
+}
+```
+
+您不需要直接调用它——作曲家会这样做。如果您正在构建自定义输入界面，请首先重用 `@agent-native/core/client` 中的共享作曲家/语音客户端片段。将此路由视为需要发送多部分音频的自定义助手的低级传输边界。
+
+## 自定义提供程序 {#customizing}
+
+提供者字段是一个普通的应用程序状态密钥，因此代理可以根据请求更改它（`"use the browser speech recognizer instead"`）。如果您正在构建具有不同要求的模板（例如，本地 Whisper 部署），请在框架安装默认路由之前通过注册您自己的 `transcribe-voice` 路由来交换路由处理程序。
+
+## 下一步是什么
+
+- [**Drop-in Agent**](/docs/drop-in-agent) — 公开语音按钮的作曲家
+- [**Onboarding**](/docs/onboarding) — 注册提供商密钥作为设置步骤
+- [**Security & Data Scoping**](/docs/security) — 每个用户如何存储加密秘密

package/docs/content/locales/zh-CN/what-is-agent-native.md

@@ -0,0 +1,202 @@
+---
+title: "Agent-Native是什么？"
+description: "为什么大多数人工智能应用感觉是半成品，是什么让应用真正成为代理原生的，以及最终的结果是你的日常体验。"
+---
+
+# Agent-Native是什么？
+
+原生代理是一种构建软件的方式，其中人工智能代理及其周围的产品表面是**平等的合作伙伴**。该表面可以是具有一个自定义操作的无头代理、丰富的聊天或完整的 UI。重要的是代理和人类共享相同的 actions、数据库和状态。
+
+如果您只记得本页中的一件事，请记住这一点：当今大多数人工智能应用程序都离实用性差一步，而这一差距是目前该领域最大的错误。
+
+## 作为一个用户是什么样的 {#what-it-looks-like}
+
+想象一个后台工作人员、收件箱、日历、表单生成器或分析仪表板。有时还没有自定义屏幕：您运行一项操作或一项无头应用程序代理提示。有时，第一个屏幕是聊天：您询问您想要什么，代理指导设置，显示表格或图表，并打开正确的应用程序视图。有时聊天会停靠在完整应用程序的右侧。通过这些形状，您可以：
+
+- **从实际操作开始。**一个持久操作可以从 CLI、HTTP、MCP、A2A、应用程序代理循环以及稍后的 UI 运行。
+- **单击存在 UI 时通常单击的任何内容。**所有按钮、列表、仪表板、键盘快捷键 - 它们都调用代理可以调用的相同操作。
+- **或者只是询问。** 在代理中输入“回复 Sara 的电子邮件，说我会在 3 点前到达”。它会打开正确的线程，起草回复，然后将其显示给您以供批准 - 就像您手动完成的一样。
+- **查看它看到的内容。** 打开一封电子邮件，代理就知道是哪一封。选择一个图表，代理就知道是哪个图表。突出显示一个段落并按 Cmd+I，代理将仅对该段落执行操作。
+- **观察它的工作。** 当代理执行操作（打开视图、编辑草稿、运行报告）时，UI 会实时更新。您可以随时停止它、重定向它或用鼠标接管。
+- **像队友一样引导它。**提供反馈、排队另一个任务、编辑其指令、审核它昨天做了什么。它会记住，并且随着时间的推移，它会更好地适应您的工作流程。
+
+这就是 agent-native 的设计初衷。这就是大多数产品无法实现这一目标的原因。
+
+## 为什么大多数“人工智能应用程序”都达不到要求（阶梯原理） {#the-ladder}
+
+大多数团队都在攀登，就像梯子一样，而且大多数人过早地停止了一级。
+
+### Rung 1 — 单个 LLM 调用（反模式） {#rung-one}
+
+文本框发送提示，AI 返回字符串，然后您显示它。也许用旋转器。用户无法纠正路线，人工智能无法采取行动，无法了解发生了什么或为什么。
+
+您随处可见：“AI 功能”基本上是固定在 SaaS 产品上的“总结”按钮。它们在演示中看起来令人印象深刻，并在现实变得混乱时打破了这一点。那不是一个产品；而是一个产品。那是一个玩具。
+
+### 梯级 2 — 使用工具聊天 {#rung-two}
+
+现在人工智能可以*做事*。它有工具——“电子邮件草稿”、“搜索联系人”、“运行查询”——以及一个聊天界面，它在你面前工作，显示工具调用和结果。这就是 Claude、ChatGPT 和 Cursor 在底层的样子。
+
+这是真正的进步。但就其本身而言，它仍然是一个聊天窗口。没有正确的 UI。没有仪表板、没有列表、没有表单、没有键盘快捷键、没有团队协作。如果人工智能感到困惑，你就会陷入重新输入的困境，而不仅仅是点击正确的按钮。非开发人员很难以这种格式完成真正的工作。
+
+### 第 3 级 — 代理人 + UI 作为平等合伙人 {#rung-three}
+
+这是代理原生的。您可以在代理周围添加一个真实的、功能齐全的应用程序 - 至关重要的是，代理可以执行的每个操作也是 UI 中的一个按钮，并且用户单击的每个按钮都运行代理使用的相同逻辑。一种实现，两种方式。
+
+当您到达第 3 级时，三件事会发生变化：
+
+- **您停止向聊天机器人添加按钮。您向应用程序添加了代理。** 这对双方来说都是质量更高的产品。
+- **代理具有真实的上下文。**它可以看到您正在查看的内容、您选择的内容以及您刚刚执行的操作。它写入 UI 读取的同一个数据库，因此它的工作会立即显示。
+- **外部代理也可以使用它。**其他代理本机应用程序可以通过 [A2A protocol](/docs/a2a-protocol) 调用此 actions。 Claude代码、Codex、ChatGPT自定义MCP应用程序、光标和其他MCP主机可以将其作为[MCP server](/docs/mcp-protocol)驱动。一个应用程序，多个入口点。
+
+这是第 3 级。这是代理本地的。
+
+```an-diagram title="The Ladder Principle" summary="Most teams stop at rung 1 or 2. Agent-native is rung 3 — a real app and a real agent over one shared action surface."
+{
+  "html": "<div class=\"diagram-ladder\"><div class=\"diagram-card rung rung-3\"><span class=\"diagram-pill accent\">Rung 3 · agent-native</span><strong>Agent + UI as equal partners</strong><small class=\"diagram-muted\">One action surface. Every agent tool is also a button; every button runs the same logic the agent uses.</small></div><div class=\"diagram-card rung rung-2\"><span class=\"diagram-pill\">Rung 2</span><strong>A chat with tools</strong><small class=\"diagram-muted\">The agent can act — but it is still just a chat window. No dashboards, lists, or shortcuts.</small></div><div class=\"diagram-card rung rung-1\"><span class=\"diagram-pill warn\">Rung 1</span><strong>A single LLM call</strong><small class=\"diagram-muted\">Prompt in, string out. Impressive in a demo; breaks the moment reality gets messy.</small></div></div>",
+  "css": ".diagram-ladder{display:flex;flex-direction:column;gap:14px}.diagram-ladder .rung{display:flex;flex-direction:column;gap:6px;padding:16px 18px}.diagram-ladder .rung-2{margin-inline-end:48px}.diagram-ladder .rung-1{margin-inline-end:96px}"
+}
+```
+
+请参阅 [Key Concepts — Protocols](/docs/key-concepts#protocols)，了解所有这些如何挂在同一操作定义上。
+
+## 为什么每个代理都需要 UI {#why-every-agent-needs-a-ui}
+
+即使代理完成了所有繁重的工作，人类仍然需要：
+
+- **看看它在做什么** - 进度、中间输出、它触及了什么
+- **引导它** — 提供反馈、中断、对下一个任务进行排队
+- **管理它** - 编辑其指令、skills、内存、计划作业、连接的帐户
+- **检查其工作**——审查草稿、审核历史记录、回滚错误
+- **分享其输出** - 仪表板、报告、表单、发送给队友的链接
+
+至少，“代理的 UI”是一个可观察性和管理仪表板。最多，它是一个完整的 SaaS 应用程序，其中嵌入了代理作为副驾驶。两端都算作原生代理，并且表面可以从一端增长而无需重写。
+
+您不必预先选择形状。代理可以无头运行，坐在丰富的聊天后面，或者住在围绕同一操作界面的完整应用程序中 - 请参阅 [Agent Surfaces](/docs/agent-surfaces) 了解具体形状和 API。
+
+## 为什么每个应用都受益于代理 {#why-every-app-benefits-from-an-agent}
+
+另一面也同样重要。现有的 SaaS 产品总是遇到同样的问题：80% 的产品你需要的效果很好，而 20% 的产品你就是无法改变。添加聊天侧边栏很少能解决这个问题——聊天通常无法真正\_做\_UI 可以做的事情。
+
+代理本机翻转了这一点。由于应用程序中的每个操作都定义一次，并作为按钮和代理工具公开，因此代理可以执行按钮可以执行的所有操作（甚至更多），而无需维护单独的“AI 世界”。自然语言与点击一起成为一流的输入。
+
+这个论点不是“代理取代 UI”。它是“**代理属于应用程序内部，顶部有 UI，作为平等的合作伙伴**。”即使代理是产品的应用程序仍然需要 UI 供人类监督、配置和引导 - 请参阅 [Agent Surfaces — Headless](/docs/agent-surfaces#headless)。
+
+## 代理+UI奇偶校验 {#agent-ui-parity}
+
+这是定义原则。
+
+> **来自 UI** — 单击按钮、填写表格、导航视图。 UI写入数据库；代理看到结果。
+>
+> **来自代理** — 自然语言，其他代理通过 A2A、Slack、Telegram。代理写入数据库； UI 自动更新。
+
+```an-diagram title="One system, two ways in" summary="The agent and the UI write to the same actions and the same database. Whatever one does, the other sees."
+{
+  "html": "<div class=\"diagram-parity\"><div class=\"diagram-col\"><div class=\"diagram-node\">Human<br><small class=\"diagram-muted\">clicks, forms, shortcuts</small></div><div class=\"diagram-node\">Agent<br><small class=\"diagram-muted\">natural language · A2A · Slack</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Actions</span><small class=\"diagram-muted\">defined once</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">SQL database</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</div><div class=\"diagram-box\">UI updates live</div></div>",
+  "css": ".diagram-parity{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-parity .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-parity .diagram-arrow{font-size:22px;line-height:1}.diagram-parity .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+当代理创建电子邮件草稿时，它会显示在 UI 中。当您单击“发送”时，代理就知道它已发送。没有单独的“代理世界”和“UI 世界”——它是一个系统。请参阅 [Key Concepts](/docs/key-concepts) 了解实现此功能的架构。
+
+## 通常为电动工具保留定制 {#workspace-customization}
+
+像 Claude Code 这样的工具之所以如此强大，并不是因为模型，而是**定制层**：每个项目的指令、skills、内存、子代理、连接的服务。您可以根据您的代码库、您的偏好、您的团队来塑造代理。
+
+Agent-native 为每个用户提供相同的自定义层 - 无需离开应用程序。每个应用程序都附带一个个人**工作区**，您（或团队中的任何人）可以：
+
+- 编辑每个代理都会读取的团队范围规则
+- 让代理在您更正时自动记住偏好
+- 将可重用的操作指南编写为 `/slash` 命令
+- 为特定任务保留自定义子代理（使用 `@mentions` 调用）
+- 安排作业在 cron 上运行（例如“每周一早上，总结上周”）
+- 通过每用户 MCP 服务器连接外部服务（Gmail、Stripe、Slack、内部 API）
+
+不同之处：它全部存储在数据库中，而不是文件系统中。没有需要启动的开发环境，每个用户没有容器。每个用户都可以获得自己的完整工作空间 - 个人内存、个人联系、个人 skills - 基本上免费，因为它是表中的所有行。这就是 Claude 代码级灵活性在真正的多租户 SaaS 产品中可行的原因。
+
+请参阅 [Workspace](/docs/workspace) 了解完整概念。
+
+## 有何不同 {#what-makes-it-different}
+
+| 方法                              | 描述                                                                                              |
+| --------------------------------- | ------------------------------------------------------------------------------------------------- |
+| **搭载人工智能的传统应用**        | 人工智能是事后的想法。仅限于自动完成、摘要或聊天侧边栏，实际上无法在应用程序中执行任何操作。      |
+| **纯聊天/代理界面**               | 强大但难以接近。没有仪表板，没有工作流程，没有持久性。非开发人员无法有效使用它们。                |
+| **Claude 代码 / Codex 用于 SaaS** | 非常适合开发者在自己的机器上使用。不会转化为多租户 SaaS — 开发盒上每个用户一个代码库无法扩展。    |
+| **代理本机应用**                  | 代理人是一等公民。它共享相同的数据库、相同的状态，并且可以执行 UI 可以执行的所有操作 - 反之亦然。 |
+
+## 整个团队的发展 {#whole-team-development}
+
+Agent-native 不仅仅适合开发人员。由于代理可以编辑应用程序自己的代码，因此开发应用程序不再是仅限开发人员的活动：
+
+- **设计师**通过代理直接在运行的应用程序中更新设计
+- **产品经理**通过描述来添加功能和更新流程
+- **QA** 测试应用并要求代理修复损坏的内容
+- **团队中的任何人**通过自然语言做出贡献
+
+愿景：减少交接，一个人完成小团队的工作。
+
+## 分叉并自定义 {#fork-and-customize}
+
+代理本机应用程序遵循分叉和自定义模型。您从**模板**开始 - 日历、内容、幻灯片、分析、邮件、剪辑、设计、表单、调度 - 并将其变成您的。每一个都是一个完整的、可工作的 SaaS 产品，您可以批量分叉，而不是一个空白的脚手架：
+
+1. 在[agent-native.com/templates](/templates)上选择模板
+2. 立即将其用作托管应用程序（例如 mail.agent-native.com）
+3. 当您想要自定义时分叉它 - “连接我们的 Stripe 帐户”、“添加同类图表”
+4. 代理修改代码以满足您的需求
+5. 将您的分叉部署到您自己的域 - 或留在agent-native.com
+
+因为它是*您的*应用程序，而不是共享基础设施，所以代理可以安全地改进代码。您的应用程序会随着您的使用而不断改进。完整故事请参见 [Templates](/docs/cloneable-saas)。
+
+尚未准备好分叉整个模板？您还可以通过向已使用的编码代理添加**技能**来尝试代理原生 - 使用 `npx @agent-native/core@latest skills add visual-plan` 安装计划技能。请参阅 [Skills Guide](/docs/skills-guide#app-backed-skills)。
+
+## 可组合代理 {#composable-agents}
+
+代理本机应用程序可以相互通信。在邮件应用程序内部，您可以标记分析代理以查询数据并将结果包含在草稿电子邮件中。代理会发现其他可用代理，在彼此之间移交工作，并在您已经所在的 UI 中显示结果。
+
+这由 [A2A](/docs/a2a-protocol) 和 [MCP](/docs/mcp-protocol) 提供支持 - 相同的定义，多个表面 - 但作为用户，您所需要知道的是“我可以向我的任何应用程序寻求任何他们可以做的事情的帮助。”
+
+## 这在代码中是什么样的？ {#what-does-it-look-like-in-code}
+
+如果您正在构建或扩展代理本机应用程序，那么中心模式如下：应用程序中的每个操作都是一个**操作** - 定义一次，可供代理和 UI 使用。
+
+```an-annotated-code title="One action, defined once"
+{
+  "filename": "actions/reply-to-email.ts",
+  "language": "ts",
+  "code": "import { defineAction } from \"@agent-native/core/action\";\nimport { z } from \"zod\";\n\nexport default defineAction({\n  description: \"Reply to an email thread\",\n  schema: z.object({ emailId: z.string(), body: z.string() }),\n  run: async ({ emailId, body }) => {\n    // db and schema come from your app's server/db setup\n    await db.insert(schema.replies).values({ emailId, body });\n  },\n});",
+  "annotations": [
+    { "lines": "5", "label": "Tool surface", "note": "The `description` is what the agent reads to decide when to call this as a tool." },
+    { "lines": "6", "label": "类型化契约", "note": "One zod `schema` validates input from **every** surface — agent, UI, HTTP, MCP, and A2A." },
+    { "lines": "7-10", "label": "One implementation", "note": "The `run` body is the single source of truth. The UI button and the agent tool both execute exactly this." }
+  ]
+}
+```
+
+```tsx
+// In any React component — same action, called from a button
+const { mutate } = useActionMutation("reply-to-email");
+
+<Button onClick={() => mutate({ emailId, body: "Thanks!" })}>
+  Send Reply
+</Button>;
+```
+
+```tsx
+// And the agent panel mounted anywhere in your app
+import { AgentSidebar } from "@agent-native/core/client";
+
+<AgentSidebar />;
+```
+
+一个操作，多个表面：代理将其称为工具，UI 将其称为类型安全突变，[native chat](/docs/native-chat-ui) 可以呈现显式小部件结果，外部代理通过 [A2A](/docs/a2a-protocol) 访问它，MCP 主机通过应用程序的 [MCP server](/docs/mcp-protocol) 调用它，可选地使用 MCP 应用程序 UI 资源和标准远程 MCP OAuth由框架处理。完整参考请参见 [Actions](/docs/actions)。
+
+## 下一步是什么 {#whats-next}
+
+- [**Getting Started**](/docs/getting-started) — 从一个操作开始，选择一个模板，或安装一项技能
+- [**Agent Surfaces**](/docs/agent-surfaces) — 选择无头、丰富的聊天、嵌入式边车或完整应用
+- [**Key Concepts**](/docs/key-concepts) — 架构：SQL、actions、轮询同步、上下文感知、可移植性
+- [**Templates**](/docs/cloneable-saas) — 模板作为您拥有的完整产品
+- [**Workspace**](/docs/workspace) - 由 SQL 支持的每用户自定义层（skills、内存、指令、MCP），而不是文件
+- [**Dispatch**](/docs/dispatch) — 工作区控制平面：秘密库、Slack/电子邮件收件箱、跨应用委派
+- [**Extensions**](/docs/extensions) - 代理立即创建的沙盒迷你应用程序，无需更改代码
+- [**Drop-in Agent**](/docs/drop-in-agent) — 将 `<AgentPanel>` 安装到任何 React 应用中