@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/zh-CN/key-concepts.md

@@ -0,0 +1,312 @@
+---
+title: "关键概念"
+description: "代理本机应用程序的工作原理：首先是 actions、SQL 数据库、应用程序代理循环、可选的 UI、轮询同步、外部代理入口点、上下文感知和可移植性。"
+---
+
+# 关键概念
+
+代理本机应用程序如何在幕后工作 - 原则和架构。此页为合同；有关以这种方式构建的愿景和案例，请参阅 [What Is Agent-Native?](/docs/what-is-agent-native)。
+
+## 架构 {#the-architecture}
+
+每个代理本机应用程序都由三部分协同工作：
+
+> **代理** — 读取数据、写入数据、运行 actions 和修改代码的自主 AI。可使用 skills 和说明进行定制。
+>
+> **应用** — 试剂周围的产品表面。一开始这可能只是操作、丰富的聊天、小型控制平面或带有仪表板、流程和可视化的完整 React UI。
+>
+> **计算机** — 数据库、浏览器、代码执行。代理直接使用SQL和内置工具进行工作； MCP 服务器是可选的附加组件，而不是基础。
+
+```an-diagram title="Agent, application, and computer" summary="Three layers working together over one shared SQL store. The agent and the application both read and write the same data."
+{
+  "html": "<div class=\"diagram-arch\"><div class=\"diagram-row\"><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Agent</span><small class=\"diagram-muted\">reads + writes data, runs actions, modifies code</small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">Application</span><small class=\"diagram-muted\">action-only, chat, control plane, or full React UI</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;&nbsp;&uarr;</div><div class=\"diagram-box\" data-rough>Computer<br><small class=\"diagram-muted\">SQL database · browser · code execution</small></div></div>",
+  "css": ".diagram-arch{display:flex;flex-direction:column;align-items:center;gap:10px}.diagram-arch .diagram-row{display:flex;gap:12px;flex-wrap:wrap;justify-content:center}.diagram-arch .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;min-width:220px}.diagram-arch .diagram-arrow{font-size:20px;line-height:1}.diagram-arch .diagram-box{text-align:center;padding:12px 18px}"
+}
+```
+
+无头应用程序可以使用 `pnpm agent` 从文件夹运行相同的生产应用程序代理循环，而 UI 应用程序则安装嵌入式代理面板并使用 `pnpm dev` 在本地运行。在云中，Builder.io 提供了一个托管框架（在您的应用旁边托管代理的环境），为团队提供协作、可视化编辑和托管基础架构。
+
+## 代理构建块 {#agent-building-blocks}
+
+每个代理本机应用程序都具有相同的代理构建块，无论是否
+产品表面是无头的、聊天优先的或完整的 UI：
+
+```an-file-tree title="Guidance and behavior"
+{
+  "entries": [
+    { "path": "AGENTS.md", "note": "always-on instructions: purpose, core rules, state keys, action index, skills index" },
+    { "path": ".agents/skills/<name>/SKILL.md", "note": "reusable behavior: workflow steps, policies, examples, references, and do/don't lists" },
+    { "path": "actions/<name>.ts", "note": "executable capability: typed operation exposed to the agent, UI, CLI, HTTP, MCP, A2A, jobs, and webhooks" }
+  ]
+}
+```
+
+| 构建块      | 使用它                                                                 | 加载时间                         |
+| ----------- | ---------------------------------------------------------------------- | -------------------------------- |
+| **说明**    | 代理应在每项任务中进行稳定的指导：应用程序是什么、不变量、语气、索引   | 每个回合                         |
+| **Skills**  | 可重用行为：如何遵循工作流程、应用策略、检查证据或验证输出             | 当技能描述与任务匹配时按需       |
+| **Actions** | 实际操作：读取或写入数据、调用 API、发送消息、运行审批、生成类型化结果 | 每次都被列为工具；仅在调用时执行 |
+
+Skills 和 actions 一起工作。一项技能教代理如何做一类
+工作；操作是它在执行该工作时可以调用的代码路径。例如，
+`customer-research` 技能可能会告诉代理要检查哪些来源
+如何在 `search-crm` 和 `create-brief` actions 获取的同时总结证据
+并写入实际数据。
+
+管理架构的六项规则：
+
+1. **数据存在于 SQL** - 所有应用程序状态都通过 Drizzle ORM 存在于数据库中
+2. **所有 AI 都通过代理** - 无内联 LLM 调用
+3. **Actions 用于代理操作** — 复杂的工作作为 actions 运行
+4. **实时同步使 UI 保持同步** — 通过 SSE 进行数据库更改流，并以轮询作为通用回退
+5. **代理可以修改代码** - 应用程序会随着您的使用而不断发展
+6. **SQL 中的应用程序状态** — 临时 UI 状态存在于数据库中，代理和 UI 都可读
+
+## 四个区域清单 {#four-area-checklist}
+
+每个面向用户的功能都应该更新所有适用的区域。跳过适用区域会破坏代理与本地合约；将 UI 强制到仅动作原语上也是一种气味。
+
+| 区域                | 描述                                     |
+| ------------------- | ---------------------------------------- |
+| **1. UI**           | 用户与之交互的页面、组件或对话框         |
+| **2。行动**         | actions/中的代理可调用操作用于相同操作   |
+| **3. Skills**       | 更新 AGENTS.md 和/或创建记录该模式的技能 |
+| **4。应用程序状态** | 导航状态、视图屏幕数据和导航命令         |
+
+只有 UI 的功能对于代理来说是不可见的。仅包含 actions 的完整 UI 功能对用户来说是不可见的。没有应用程序状态的功能意味着代理对用户正在做的事情一无所知。无头操作可以合法地从操作 + 指令开始，并在稍后当人们需要浏览、批准、配置或共享时添加 UI/应用程序状态。
+
+## SQL中的数据 {#data-in-sql}
+
+所有应用程序状态都通过 Drizzle ORM 存储在 SQL 数据库中。模式与提供者无关；支持的数据库、`DATABASE_URL` 配置和可移植性规则位于 [Database](/docs/database) 中。
+
+核心 SQL 商店是自动创建的，并且在每个模板中都可用：
+
+- `application_state` - 短暂的 UI 状态（导航、草稿、选择）
+- `settings` — 持久键值配置
+- `oauth_tokens` — OAuth 凭证
+- `sessions` — 身份验证会话
+
+```an-schema title="Core SQL stores" summary="Auto-created in every template — the agent and UI both read and write these."
+{
+  "entities": [
+    { "id": "application_state", "name": "application_state", "note": "Ephemeral UI state the agent reads for context", "fields": [
+      { "name": "key", "type": "text", "pk": true, "note": "e.g. 'navigation'" },
+      { "name": "value", "type": "json", "note": "view, selection, drafts" }
+    ] },
+    { "id": "settings", "name": "settings", "note": "Persistent key-value config", "fields": [
+      { "name": "key", "type": "text", "pk": true },
+      { "name": "value", "type": "json" }
+    ] },
+    { "id": "oauth_tokens", "name": "oauth_tokens", "note": "OAuth credentials", "fields": [
+      { "name": "provider", "type": "text", "pk": true },
+      { "name": "token", "type": "text" }
+    ] },
+    { "id": "sessions", "name": "sessions", "note": "Auth sessions", "fields": [
+      { "name": "id", "type": "text", "pk": true },
+      { "name": "userId", "type": "text" }
+    ] }
+  ]
+}
+```
+
+```ts
+// Drizzle schema for domain data
+import { table, text, integer } from "@agent-native/core/db/schema";
+
+export const forms = table("forms", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  schema: text("schema").notNull(), // JSON
+  ownerEmail: text("owner_email"),
+  createdAt: integer("created_at").notNull(),
+});
+```
+
+```bash
+# Core actions for quick database inspection and one-off maintenance
+pnpm action db-schema                                       # show all tables
+pnpm action db-query --sql "SELECT * FROM forms"
+pnpm action db-exec --sql "UPDATE forms SET status = ? WHERE id = ?" --args '["closed","form-1"]'
+# Surgical find/replace on a large text column — sends a diff, not the whole value
+pnpm action db-patch --table documents --column content \
+  --where "id='doc-1'" --find "old heading" --replace "new heading"
+```
+
+生产代理聊天插件默认启用原始数据库写入
+(`databaseTools: "write"`)，以便代理可以修复应用程序拥有的数据，而无需等待
+新类型的动作。这些写入的范围仅限于经过身份验证的用户/组织。设置
+`databaseTools: "read"` 仅保留 `db-schema` / `db-query` 检查，或
+`databaseTools: "off"` / `false` 要求类型化应用程序 actions 获取所有数据
+访问。
+
+## 代理聊天桥 {#agent-chat-bridge}
+
+UI 从不直接调用 LLM。当用户点击“生成图表”或“写入摘要”时，UI 通过 `postMessage` 向代理发送消息。代理完成工作 - 具有完整的对话历史记录、skills、指令和迭代能力。
+
+```ts
+// In a React component — delegate AI work to the agent
+import { sendToAgentChat } from "@agent-native/core/client";
+
+sendToAgentChat({
+  message: "Generate a chart showing signups by source",
+  context: "Dashboard ID: main, date range: last 30 days",
+  submit: true,
+});
+```
+
+为什么不调用 LLM 内联？
+
+- **人工智能是不确定的。**您需要对话流来提供反馈和迭代——而不是一次性按钮。
+- **上下文很重要。**代理拥有您的完整代码库、说明、skills 和历史记录。内联调用则没有这些。
+- **代理可以做更多事情。**它可以运行 actions、浏览网页、修改代码以及将多个步骤链接在一起。
+- **无头执行。**因为一切都通过代理进行，所以任何应用程序都可以完全由 Slack、Telegram 或其他代理通过 [A2A](/docs/a2a-protocol) 驱动。
+
+## Actions系统 {#actions-system}
+
+当代理需要做一些复杂的事情时——调用 API、处理数据、查询数据库——它会运行一个**操作**。 Actions 是 `actions/` 中的 TypeScript 文件，导出默认的 `defineAction()`：
+
+```ts
+// actions/fetch-data.ts
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Fetch data from a source API.",
+  schema: z.object({
+    source: z.string().describe("Data source key, e.g. 'signups'"),
+  }),
+  run: async ({ source }) => {
+    const res = await fetch(`https://api.example.com/${source}`);
+    return await res.json();
+  },
+});
+```
+
+一次 `defineAction()` 调用将为您提供：
+
+- **代理工具** — 代理通过 zod 派生的 JSON 架构看到它并可以调用它。
+- **前端钩子** - `useActionMutation("fetch-data")` 具有完整的 TypeScript 推理。
+- **框架传输** - 自动安装在客户端挂钩后面。
+- **CLI** — `pnpm action fetch-data --source=signups` 用于脚本和代理开发循环。
+- **MCP 工具/A2A 工具** — 当启用 MCP 服务器或 A2A 时，也会显示相同的操作。
+
+相同的逻辑，一个定义，自动连接到每个消费者。请参阅 [Actions](/docs/actions) 获取完整参考。
+
+## 实时同步 {#polling-sync}
+
+数据库更改通过`useDbSync()`同步到UI。同进程通过`/_agent-native/events`写流； `/_agent-native/poll` 仍然是跨进程和无服务器的后备方案。当代理写入数据库（应用程序状态、设置或域数据）时，版本计数器会递增，并且客户端会使相关的 React 查询缓存无效。
+
+```ts
+// Client: subscribe to agent/UI data changes once near the app shell
+import { useDbSync } from "@agent-native/core/client";
+
+useDbSync({ queryClient });
+```
+
+流程是：
+
+1. 代理运行写入数据库的操作
+2. 服务器使用 `"action"` 或 `"settings"` 等源发出更改事件
+3. `useDbSync` 通过 SSE 或轮询回退接收它
+4. `useActionQuery` 挂钩和源版本 `useQuery` 挂钩重新获取
+5. 组件无需重新加载页面即可呈现新数据
+
+```an-diagram title="Live sync flow" summary="An agent write becomes a UI render with no manual refresh — SSE first, polling as the universal fallback."
+{
+  "html": "<div class=\"diagram-sync\"><div class=\"diagram-node\">Agent action<br><small class=\"diagram-muted\">writes to DB</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">Change event<br><small class=\"diagram-muted\">source: action / settings</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">useDbSync</span><small class=\"diagram-muted\">SSE &middot; poll fallback</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">Query refetch<br><small class=\"diagram-muted\">render, no reload</small></div></div>",
+  "css": ".diagram-sync{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.diagram-sync .diagram-arrow{font-size:22px;line-height:1}.diagram-sync .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:10px 14px}"
+}
+```
+
+这适用于所有部署环境（包括无服务器和边缘），因为它使用数据库，而不是内存状态或文件系统观察器。
+
+## 框架 {#frames}
+
+_frame_ 是在您的应用程序旁边托管代理的环境 - 在本地是嵌入式面板；在云端，它是 Builder.io 的托管表面。参见[Frames](/docs/frames)。
+
+代理本机应用程序包括一个嵌入式代理面板，该面板与应用程序 UI 一起提供 AI 代理。这就是架构发挥作用的原因：代理需要计算机（数据库、浏览器、代码执行），而应用程序需要代理来进行 AI 工作。
+
+> **嵌入式代理面板** - 每个应用程序中内置聊天和可选的 CLI 终端。支持 Claude 代码、Codex、Gemini、OpenCode 和 Builder.io。在本地运行。免费且开源。
+>
+> **云** — 通过实时协作、可视化编辑、角色和权限部署到任何云。最适合团队。
+
+## 情境感知 {#context-awareness}
+
+代理始终知道用户在看什么。 UI 在每次路由更改时将 `navigation` 密钥写入应用程序状态。代理在执行操作之前通过 `view-screen` 操作读取它。
+
+例如，当您打开电子邮件线程时，UI 会插入一行，例如：
+
+```json
+{ "key": "navigation", "value": { "view": "thread", "threadId": "th_abc123" } }
+```
+
+UI 在路线变更时写入此信息；代理在采取任何操作之前都会读取它（通过 `view-screen`），因此它始终知道您关注的是哪个线程 - 或图表或幻灯片。
+
+请参阅 [Context Awareness](/docs/context-awareness) 了解完整模式：导航状态、视图屏幕、导航命令和抖动预防。
+
+## 一个动作，多个表面 {#protocols}
+
+将一个域操作作为一个动作执行一次；该框架将其暴露给每个消费者。相同的 `defineAction()` 成为代理工具、类型安全 UI 挂钩、HTTP 端点、CLI 命令、MCP 工具和 A2A 工具，并且仅在表面需要时添加可选的 `link`、`mcpApp` 或显式本机小部件元数据。 Skills 和说明涵盖行为。
+
+有关完整的协议/表面矩阵（MCP 服务器和 OAuth、MCP 应用程序、A2A、深层链接、本机聊天小部件、AgentChatRuntime 连接器、Agent Web 以及 ACP 和 A2UI 的适配器范围），以及选择产品形状（无头、丰富聊天、嵌入式边车或完整应用程序），请参阅[Agent Surfaces](/docs/agent-surfaces)。
+
+## 代理修改代码 {#agent-modifies-code}
+
+这是一个功能，而不是一个错误。代理可以安全地编辑应用程序的源代码：组件、路由、样式、actions。
+
+没有需要破坏的共享代码库。您拥有该应用程序，代理会随着时间的推移为您改进它：
+
+1. 分叉模板（例如分析模板）
+2. 通过询问代理进行定制
+3. “为同期群分析添加新的图表类型”——代理构建它
+4. “连接到我们的 Stripe 帐户”- 代理编写集成
+5. 您的应用无需手动开发即可不断改进
+
+## 默认为便携式 {#hosting-agnostic}
+
+两条架构规则使应用程序可以跨数据库和主机移植：
+
+- **与数据库无关。** 使用 `@agent-native/core/db/schema` 写入模式并使用 Drizzle 的可移植查询 DSL 进行读/写，因此相同的代码可以在任何支持的提供程序上运行。仅将原始 SQL 用于附加迁移或一次性维护，保持参数化且与方言无关。参见[Database](/docs/database)。
+- **与主机无关。** 服务器在 Nitro 上运行并编译为任何部署目标。切勿在服务器路由或插件中使用特定于节点的 API（`fs`、`child_process`、`path`），并且切勿假设持久服务器进程 - 无服务器和边缘是无状态的，因此将所有状态保留在 SQL 中。参见[Deployment](/docs/deployment)。
+
+## 工作区 {#workspace}
+
+每个用户都会获得一个个人**工作空间** - 指令、skills、内存、自定义子代理、计划作业和连接的 MCP 服务器 - 全部存储在 SQL 而不是文件中。这使得 Claude 代码级定制可以在多租户 SaaS 中实现，而无需为每个用户启动一个容器。参见[Workspace](/docs/workspace)。
+
+## 相关构建块 {#building-blocks}
+
+这些位于同一个合约之上，并且有自己的深入研究：
+
+- **[Dispatch](/docs/dispatch)** — 工作区控制平面：共享收件箱、机密库、计划作业以及通过 A2A 委托给专业应用程序的编排器。
+- **[Extensions](/docs/extensions)** — 代理在运行时创建的沙盒 Alpine.js 迷你应用，无需更改源或迁移。
+- **[A2A Protocol](/docs/a2a-protocol)** — 同一工作区中的应用如何通过 JSON-RPC 发现并相互调用。
+
+## 您免费获得的东西 {#what-you-get-for-free}
+
+采用该框架很有价值，主要是因为您不再需要构建什么。一旦您的应用遵循这六个规则，您就继承了：
+
+- **一个操作 = 每个表面。** 使用 `defineAction()` 定义的每个操作同时是一个代理工具、类型安全前端挂钩 (`useActionQuery` / `useActionMutation`)、框架拥有的 HTTP 传输、CLI 命令、用于外部客户端的 MCP 工具以及用于其他代理本机应用程序的 A2A 工具。可选的 `link` 和 `mcpApp` 元数据添加深层链接和 MCP 应用 UI，无需第二次实现。
+- **每个用户一个完整的工作区。** Skills、共享 `LEARNINGS.md`、个人 `memory/MEMORY.md`、`AGENTS.md`、自定义子代理、计划作业、连接的 MCP 服务器 — 所有 SQL 支持，无需开发盒。参见[Workspace](/docs/workspace)。
+- **插入 React 组件。** `<AgentPanel />` 和 `<AgentSidebar />` 在应用程序中的任何位置呈现聊天 + 工作区。参见[Drop-in Agent](/docs/drop-in-agent)。
+- **BYO 代理聊天运行时。** 相同的聊天 UI 可以位于 OpenAI 代理、OpenAI 响应、Claude 代理 SDK、Vercel AI SDK、AG-UI 或您自己的规范化 HTTP 流之上。参见[Native Chat UI](/docs/native-chat-ui#byo-agent-runtimes)。
+- **代理和 UI 之间的实时同步。**同一进程立即通过 `/_agent-native/events` 写入流；轻量级轮询使无服务器、cron 和跨进程写入保持收敛。改变 actions 会自动使操作支持的查询失效，因此无需手动刷新即可显示代理创建的记录。请参阅下面的 [Live Sync](#polling-sync)。
+- **Auth、orgs、RBAC。** 每个模板都内置了带有 orgs/members/roles 的更好的身份验证。参见[Authentication](/docs/authentication)。
+- **上下文感知。**代理始终通过 `navigation` 应用状态键了解用户正在查看的内容。参见[Context Awareness](/docs/context-awareness)。
+- **MCP 客户端 + 服务器，双向。** 应用程序摄取 MCP 服务器（本地、远程、集线器共享）*并且*将其自己的 actions 公开为 MCP 服务器。请参阅 [MCP Clients](/docs/mcp-clients) 和 [MCP Protocol](/docs/mcp-protocol)。
+- **应用程序间委托。**不同应用程序中的代理通过 [A2A](/docs/a2a-protocol) 进行通信。同源部署跳过JWT；跨域使用共享的`A2A_SECRET`。
+- **子代理团队。** 生成一个具有自己的线程和工具的子代理，以聊天中内联的芯片形式出现。参见[Agent Teams](/docs/agent-teams)。
+- **可移植性。**任何 Drizzle 支持的 SQL 数据库、任何 Nitro 兼容的主机（Node、Workers、Netlify、Vercel、Deno、Lambda、Bun）。
+
+这就是“以及其他所有东西”，否则你需要自己将它们粘合在一起。
+
+## 深入研究 {#deep-dives}
+
+有关特定模式的详细指导：
+
+- [What Is Agent-Native?](/docs/what-is-agent-native) — 愿景和理念
+- [Context Awareness](/docs/context-awareness) — 导航状态、视图屏幕、导航命令
+- [Skills Guide](/docs/skills-guide) — 框架 skills，域 skills，创建自定义 skills
+- [Native Chat UI](/docs/native-chat-ui) — 操作声明的表格、图表和 BYO 运行时状态
+- [Agent Surfaces](/docs/agent-surfaces) — 无头、丰富的聊天、嵌入式 sidecar 和完整应用路径
+- [A2A Protocol](/docs/a2a-protocol) — 代理间通信
+- [Multi-App Workspace](/docs/multi-app-workspace) — 在一个单一存储库中托管多个应用程序，并具有共享身份验证、skills、组件和凭据