@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,142 @@
+---
+title: "FAQ"
+description: "有关原生代理的常见问题 - 它是什么、它的用途、您可以构建什么以及它如何工作。"
+---
+
+# FAQ
+
+有关代理原生的常见问题，从“我只是在寻找”到“我现在正在连接身份验证”。
+
+## 基础知识 {#general}
+
+### 什么是代理原生？ {#what-is-agent-native}
+
+Agent-native 是一个用于构建应用程序的框架，其中 AI 代理及其周围的产品表面是平等的合作伙伴。该界面可以从一个无头代理开始，通过一个自定义操作，发展成为丰富的聊天，或者成为一个完整的 UI。不变的是智能体和人类共享相同的 actions、数据库和状态。完整解释请参见 [What Is Agent-Native?](/docs/what-is-agent-native)。
+
+### 这是给谁的？ {#who-is-this-for}
+
+Agent-native 适合那些想要真正的应用程序和 AI 代理使用相同数据和 actions 工作的人。常见的路径是：
+
+- **如果您需要邮件、日历、表单、计划或其他无需设置的成品模板，请使用托管应用程序** - 从 [template gallery](/templates) 开始。
+- **从聊天开始**如果您想要一个用户可以立即交谈的基本应用程序，然后使用 actions 和屏幕进行扩展 - 从 [Getting Started](/docs/getting-started) 或 [Chat](/docs/template-chat) 开始。
+- **如果您想要在提交到 UI 之前执行一个操作和一个无头应用程序代理循环，请先启动原语优先** — 从 [Getting Started](/docs/getting-started) 开始。
+- **分叉并自定义模板**如果您想要自己的 SaaS 产品，并且已连接身份验证、数据库、UI 和代理 actions — 请参阅 [Templates](/docs/cloneable-saas)。
+- **从头开始构建**如果您想要新的代理驱动产品的框架原语 - 从 [Getting Started](/docs/getting-started) 开始。
+- **如果您希望 Claude、ChatGPT、Codex、Cursor 或 GitHub Copilot / VS Code 使用代理本机应用程序，请连接另一个代理或代码工具** - 请参阅 [External Agents](/docs/external-agents) 和 [Skills Guide](/docs/skills-guide)。
+
+### 这与向现有应用添加 AI 有何不同？ {#how-is-this-different}
+
+大多数应用程序将人工智能作为事后的想法，实际上无法在应用程序中*做*事情。在代理原生应用程序中，代理是一等公民，与 UI 共享相同的 actions、数据库和状态，因此它可以执行按钮可以执行的任何操作 - 并修改应用程序自己的代码。参见[What Is Agent-Native?](/docs/what-is-agent-native#the-ladder)。
+
+```an-diagram title="Bolted-on AI vs. agent-native" summary="A bolted-on chat sidebar lives in its own world. An agent-native agent shares the same actions, database, and state as the UI."
+{
+  "html": "<div class=\"diagram-vs\"><div class=\"diagram-col\"><span class=\"diagram-pill warn\">Bolted-on AI</span><div class=\"diagram-node\">Chat sidebar</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>separate AI world<br><small class=\"diagram-muted\">can't touch the app</small></div><div class=\"diagram-box diagram-muted\">App UI &amp; data</div></div><div class=\"diagram-divider\" aria-hidden=\"true\"></div><div class=\"diagram-col\"><span class=\"diagram-pill ok\">Agent-native</span><div class=\"diagram-row2\"><div class=\"diagram-node\">UI</div><div class=\"diagram-node\">Agent</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>shared actions, DB &amp; state</div></div></div>",
+  "css": ".diagram-vs{display:flex;align-items:stretch;gap:18px;flex-wrap:wrap}.diagram-vs .diagram-col{display:flex;flex-direction:column;gap:8px;align-items:center;flex:1;min-width:200px}.diagram-vs .diagram-row2{display:flex;gap:8px}.diagram-vs .diagram-arrow{font-size:20px;line-height:1}.diagram-vs .diagram-divider{width:1px;align-self:stretch;background:currentColor;opacity:.15}"
+}
+```
+
+### 它是开源的吗？ {#is-this-open-source}
+
+是的。该框架和所有模板都是开源的。您可以在本地运行所有内容、自行托管或使用 Builder.io 的云来实现托管、协作和团队功能。
+
+### 需要多少钱？ {#how-much}
+
+框架本身是免费的。您在实践中会看到的两种成本：
+
+- **AI 使用。** 您携带自己的 API 密钥（Anthropic、OpenAI 等）并直接向模型提供商付款。我们没有加价。
+- **托管。** 无论您的主机收费多少。对于小型工作负载，大多数模板都可以在免费套餐（Netlify、Vercel、Cloudflare）上正常运行。
+
+如果您不想管理其中任何内容，`agent-native.com` 上的托管版本（由 Builder.io 运营）可将推理和托管捆绑到每席位计划中。
+
+### 我可以自己主持吗？ {#can-i-self-host}
+
+是的。选择运行 Node 的任何主机 — Netlify、Vercel、Cloudflare、AWS、Deno Deploy、您自己的服务器 — 以及任何 SQL 数据库（Postgres、SQLite、Turso、D1）。该框架是为了可移植而构建的。参见[Deployment](/docs/deployment)。
+
+### 支持哪些AI模型？ {#what-models}
+
+Anthropic Claude、OpenAI（GPT-5 系列）、Google Gemini 以及使用 OpenAI API 形状的任何提供商（包括通过 Ollama 的本地模型）。您可以在设置中配置模型；切换是配置更改，而不是代码重写。该框架最重的测试路径是 Claude，因此这是默认推荐。
+
+### 我需要了解人工智能/机器学习吗？ {#do-i-need-to-know-ai}
+
+没有。您不需要训练模型、微调或处理嵌入。您构建了一个常规的 Web 应用程序 - 在托管版本上，您几乎不需要构建任何东西。该框架处理代理集成：路由消息、运行 actions、同步状态。
+
+### 我可以将现有应用迁移到代理原生吗？ {#can-i-use-existing-code}
+
+可以，但是从头开始构建原生代理效果最好。架构——共享数据库、轮询同步、actions、应用程序状态——需要始终集成。从模板开始并自定义它是推荐的路径。可以把它想象成从桌面优先到移动优先的转变：你*可以*改造，但构建原生更好。
+
+## 模板以及您可以构建的内容 {#templates}
+
+### 有哪些模板可用？ {#what-templates-are-available}
+
+该框架附带了可用于生产的模板，包括 [Chat](/docs/template-chat)、[Mail](/docs/template-mail)、[Calendar](/docs/template-calendar)、[Forms](/docs/template-forms)、[Plan](/docs/template-plan)（视觉计划和 PR 回顾）、[Analytics](/docs/template-analytics)、[Dispatch](/docs/template-dispatch) 等。每个都是一个完整的应用程序，包含 UI、代理 actions、数据库架构和 AI 指令。完整目录请参见 [Templates](/docs/cloneable-saas)。
+
+### 我可以自定义模板吗？ {#can-i-customize-templates}
+
+这就是重点。分叉一个模板并通过询问代理来自定义它。 “向表单添加优先级字段。” “连接到我们的 Salesforce 实例。” “更改配色方案以匹配我们的品牌。”代理修改代码，您的应用程序会随着时间的推移而发展。
+
+### 我可以构建模板未涵盖的内容吗？ {#build-from-scratch}
+
+是的。如果你想要一个基本的聊天应用程序，请运行`npx @agent-native/core@latest create my-chat-app --template chat`；您可以获得持久的聊天线程、actions、身份验证、SQL 支持的运行时状态以及添加您自己的屏幕的空间。如果您想要没有 UI 的最小操作优先应用程序，请运行 `npx @agent-native/core@latest create my-agent --headless`。请参阅 [Getting Started](/docs/getting-started)、[Pure-Agent Apps](/docs/pure-agent-apps) 和 [Chat](/docs/template-chat)。
+
+### 我可以在不分叉模板的情况下尝试它吗？ {#try-with-a-skill}
+
+是的——通过一个命令将一项技能安装到您已经使用的编码代理中，不需要脚手架。请参阅 [Skills Guide](/docs/skills-guide#app-backed-skills) 了解演练。
+
+## 代理能力 {#agent-capabilities}
+
+### 代理真的可以修改应用程序自己的代码吗？ {#can-the-agent-modify-code}
+
+是的，这是一个功能。代理可以安全地编辑组件、路线、样式和 actions。您要求“添加群组分析图表”，代理就会构建它。您询问“连接到我们的 Stripe 帐户”，然后代理会编写集成。一切都是正常的 Git 跟踪代码，因此不良更改很容易恢复。
+
+### 用户可以从应用程序外部与代理交谈吗？ {#external-channels}
+
+是的。相同的代理在您的网络 UI、Slack、Telegram、通过电子邮件以及其他代理（通过 [A2A](/docs/a2a-protocol)）中运行。这是同一个特工，具有相同的内存和相同的 actions，只是通过不同的渠道到达。参见[Messaging the agent](/docs/messaging)。
+
+### 代理可以互相交谈吗？ {#can-agents-talk-to-each-other}
+
+是的，通过 [A2A (Agent-to-Agent) protocol](/docs/a2a-protocol)。每个代理本机应用程序都会自动获取 A2A 端点。从邮件应用程序中，您可以标记分析代理以查询数据。代理发现其他可用代理，通过协议调用它们，并在 UI 中显示结果。无需配置 - 代理卡是根据模板的 actions 自动生成的。
+
+### 客服人员可以在应用程序中看到什么？ {#what-can-the-agent-see}
+
+代理始终知道用户当前正在查看的内容。 UI 在每次路线更改时将导航状态写入数据库 - 打开哪个视图、选择哪个项目。代理在采取行动之前会阅读此内容。如果电子邮件已打开，代理就知道是哪封电子邮件。如果选择了一张幻灯片，代理就知道是哪张幻灯片。参见[Context Awareness](/docs/context-awareness)。
+
+## 开发问题 {#development}
+
+### 哪些人工智能编码工具可与代理原生配合使用？ {#which-ai-tools-work}
+
+任何读取项目指令的人工智能编码工具。该框架使用 AGENTS.md 作为通用标准，并自动为特定工具创建符号链接：
+
+- **Claude 代码** — 读取 CLAUDE.md（通过 CLI 设置从 AGENTS.md 进行符号链接）
+- **光标** - 直接读取 AGENTS.md，或者如果项目中存在 `.cursorrules`（光标的旧位置）
+- **Windsurf** — 读取 .windsurfrules（通过 CLI 设置从 AGENTS.md 进行符号链接）
+- **Codex、Gemini 等** — 通过嵌入式代理面板工作
+- **Builder.io** — 具有可视化编辑和协作功能的云托管代理
+
+### 我可以使用自己的数据库吗？ {#can-i-use-my-own-database}
+
+是的。设置 `DATABASE_URL` ，框架会自动检测它。支持的数据库包括 SQLite、Postgres（Neon、Supabase、plain）、Turso (libSQL) 和 Cloudflare D1。所有 SQL 通过 Drizzle ORM 都是与方言无关的 - 相同的代码在任何地方都可以工作。
+
+### 我可以在哪里部署？ {#where-can-i-deploy}
+
+任何地方。服务器在 Nitro 上运行，可编译为任何部署目标：Node.js、Cloudflare Workers/Pages、Netlify、Vercel、Deno Deploy、AWS Lambda 和 Bun。您还可以使用 Builder.io 的托管进行托管部署。请参阅 [Deployment guide](/docs/deployment)。
+
+## 架构 {#architecture}
+
+### 为什么是 SSE 加轮询而不是 WebSocket？ {#why-polling-not-websockets}
+
+SSE 为同进程写入提供了到浏览器的直接路径，而轻量级版本计数器轮询仍然是后备方案，因为它适用于每个部署环境 - 包括无服务器和边缘，其中持久套接字可能不可用。参见[Key Concepts — Live sync](/docs/key-concepts#polling-sync)。
+
+```an-diagram title="SSE first, polling fallback" summary="Same-process writes stream instantly; a version-counter poll keeps serverless, edge, and cross-process writes convergent."
+{
+  "html": "<div class=\"diagram-transport\"><div class=\"diagram-box\" data-rough>DB write</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-node\">SSE<br><small class=\"diagram-muted\">/_agent-native/events &middot; instant</small></div><div class=\"diagram-node\">Poll<br><small class=\"diagram-muted\">/_agent-native/poll &middot; universal fallback</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Browser refetch</div></div>",
+  "css": ".diagram-transport{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-transport .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-transport .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+### 为什么UI不能直接调用LLM？ {#why-no-inline-llm-calls}
+
+人工智能是非确定性的，因此您需要对话流来提供反馈和迭代 - 而不是一次性按钮 - 并且代理已经拥有内联调用所缺乏的代码库、指令、skills 和历史记录。通过代理路由所有内容还可以让应用程序从 Slack、Telegram 或其他代理驱动。参见[Key Concepts — Agent chat bridge](/docs/key-concepts#agent-chat-bridge)。
+
+### 为什么这是一个框架而不是一个库？ {#why-framework-not-library}
+
+共享数据库、实时同步、actions 系统和应用程序状态之所以有效，是因为它们从头开始连接在一起 - UI 立即对代理更改做出反应，代理进行通信，并且代理了解用户正在查看的内容。图书馆为你提供作品；这是一个架构。参见[Key Concepts](/docs/key-concepts)。

package/corpus/core/docs/content/locales/zh-CN/file-uploads.md

@@ -0,0 +1,122 @@
+---
+title: "文件上传"
+description: "配置文件上传存储 - 用于开发的 SQL 后备、Builder.io 或用于生产的自定义提供程序。"
+---
+
+# 文件上传
+
+该框架提供了一个文件上传抽象，可通过可配置的提供程序路由上传。模板调用 `uploadFile()` 并返回 URL — 存储后端可交换，无需更改应用程序代码。
+
+## 它是如何工作的 {#how-it-works}
+
+上传请求发送至 `POST /_agent-native/file-upload`，后者分派至活动提供者。您可以在`GET /_agent-native/file-upload/status`处查看配置了哪个提供商。
+
+提供者解析顺序是：
+
+1. **用户注册的提供程序** — 通过 `registerFileUploadProvider()` 注册的自定义提供程序
+2. **Builder.io 提供程序** — 内置，连接 Builder.io 时自动激活
+3. **SQL 后备** - 将文件作为 base64 存储在数据库中（适合开发，不适用于生产）
+
+```an-diagram title="Provider resolution order" summary="uploadFile() picks the first configured provider in order. The SQL fallback always exists so uploads work with zero setup."
+{
+  "html": "<div class=\"diagram-upload\"><div class=\"diagram-box\" data-rough>uploadFile()<br><small class=\"diagram-muted\">POST /_agent-native/file-upload</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-step\"><span class=\"diagram-pill accent\">1</span><div class=\"diagram-node\">User-registered<br><small class=\"diagram-muted\">registerFileUploadProvider() — S3, R2, GCS…</small></div></div><div class=\"diagram-step\"><span class=\"diagram-pill\">2</span><div class=\"diagram-node\">Builder.io<br><small class=\"diagram-muted\">auto when connected — CDN-served</small></div></div><div class=\"diagram-step\"><span class=\"diagram-pill warn\">3</span><div class=\"diagram-node\">SQL fallback<br><small class=\"diagram-muted\">base64 in DB — dev only</small></div></div></div></div>",
+  "css": ".diagram-upload{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-upload .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-upload .diagram-step{display:flex;align-items:center;gap:8px}.diagram-upload .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+```an-api title="The upload endpoint" method="POST" path="/_agent-native/file-upload"
+{
+  "method": "POST",
+  "path": "/_agent-native/file-upload",
+  "summary": "Upload a file through the active provider and get back a public URL.",
+  "description": "Dispatches to the first configured provider in resolution order. Check the active provider at `GET /_agent-native/file-upload/status`.",
+  "request": { "contentType": "multipart/form-data" },
+  "responses": [
+    { "status": "200", "description": "{ url, id?, provider } — the public URL and which provider handled it." }
+  ]
+}
+```
+
+## 默认：SQL 后备 {#sql-fallback}
+
+当没有配置提供者时，文件通过资源系统以base64数据存储在SQL数据库中。这对于本地开发来说是开箱即用的，但不建议用于生产——大文件会使数据库膨胀，而且没有 CDN。
+
+使用后备时会记录一次性警告。
+
+## Builder.io 托管 {#builder-hosting}
+
+当您的应用连接到 Builder.io 时，文件上传会自动路由到 Builder 的资产托管。文件由 CDN 提供，无需配置。这是推荐的生产设置。
+
+## 自定义提供商 {#custom-providers}
+
+在服务器插件中注册自定义提供程序以使用任何存储后端（S3、Cloudflare R2、GCS 等）：
+
+```ts
+// server/plugins/file-upload.ts
+import { registerFileUploadProvider } from "@agent-native/core/file-upload";
+
+export default defineNitroPlugin(() => {
+  registerFileUploadProvider({
+    id: "s3",
+    name: "Amazon S3",
+    isConfigured: () => !!process.env.S3_BUCKET,
+    upload: async ({ data, filename, mimeType }) => {
+      const key = `uploads/${Date.now()}-${filename}`;
+      await s3Client.putObject({
+        Bucket: process.env.S3_BUCKET!,
+        Key: key,
+        Body: data,
+        ContentType: mimeType,
+      });
+      return {
+        url: `https://${process.env.S3_BUCKET}.s3.amazonaws.com/${key}`,
+        provider: "s3",
+      };
+    },
+  });
+});
+```
+
+## 上传API {#upload-api}
+
+`FileUploadProvider`接口：
+
+```ts
+interface FileUploadProvider {
+  id: string; // Unique id, e.g. "s3"
+  name: string; // Human-readable name
+  isConfigured: () => boolean; // True when ready (env vars set, etc.)
+  upload: (input: FileUploadInput) => Promise<FileUploadResult>;
+}
+
+interface FileUploadInput {
+  data: Uint8Array | Buffer; // File contents
+  filename?: string; // Original filename
+  mimeType?: string; // MIME type, e.g. "image/png"
+  ownerEmail?: string; // For per-user scoping in fallback
+}
+
+interface FileUploadResult {
+  url: string; // Public URL for the uploaded file
+  id?: string; // Provider-specific id
+  provider: string; // Which provider handled it
+}
+```
+
+在 actions 或服务器代码中使用 `@agent-native/core/file-upload` 中的 `uploadFile()`：
+
+```ts
+import { uploadFile } from "@agent-native/core/file-upload";
+
+const result = await uploadFile({
+  data: fileBuffer,
+  filename: "photo.jpg",
+  mimeType: "image/jpeg",
+});
+
+if (result) {
+  // Provider handled it — result.url is the public URL
+} else {
+  // No provider configured — handle SQL fallback yourself, or skip
+}
+```

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

@@ -0,0 +1,153 @@
+---
+title: "框架"
+description: "本地开发框架、嵌入式代理面板和云框架 - AI 代理与您的应用程序一起运行的方式。"
+---
+
+# 框架
+
+每个代理本机应用程序都与应用程序 UI 旁边的 AI 代理一起运行。 **框架**是
+承载两者的包装器：它显示您的应用程序并为代理提供一个地方
+聊天、运行和（在开发中）编辑代码。一共有三个框架，共享一个运行时：
+
+- **嵌入式代理面板** - 内置于 `@agent-native/core` 的每个应用程序中。
+  这是您的应用在开发和生产过程中自行呈现的侧边栏。
+- **本地开发框架** - 在 iframe 中加载正在运行的应用程序的薄包装器
+  并添加相同的代理面板以及旁边的集成 CLI 终端。使用过
+  用于此存储库中模板的本地开发。
+- **Builder.io 云框架** — 具有协作功能的托管托管框架，
+  可视化编辑，并行代理运行。
+
+无论托管哪个框架，您的应用代码都是相同的。代理说话
+在每种情况下都通过相同的 actions 和应用程序状态连接到您的应用程序。
+
+```an-diagram title="Three frames, one runtime" summary="Your app and the agent panel are the same in every frame; only the wrapper around them changes."
+{
+  "html": "<div class=\"diagram-frames\"><div class=\"diagram-card\" data-rough><span class=\"diagram-pill accent\">Embedded panel</span><small class=\"diagram-muted\">ships in every app · dev + prod</small></div><div class=\"diagram-card\" data-rough><span class=\"diagram-pill\">Local dev frame</span><small class=\"diagram-muted\">app in an iframe + panel + CLI terminal</small></div><div class=\"diagram-card\" data-rough><span class=\"diagram-pill\">Builder.io cloud frame</span><small class=\"diagram-muted\">hosted: collaboration · visual edit · parallel runs</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>Same runtime<br><small class=\"diagram-muted\">your app · actions · application state</small></div></div>",
+  "css": ".diagram-frames{display:flex;flex-direction:column;gap:10px;align-items:stretch}.diagram-frames .diagram-card{display:flex;flex-direction:column;gap:4px;padding:12px 16px}.diagram-frames .diagram-arrow{font-size:22px;line-height:1;align-self:center}"
+}
+```
+
+## 嵌入式代理面板 {#embedded-agent}
+
+嵌入式面板是您的应用程序呈现的代理侧边栏。它附带
+`@agent-native/core` - 没有单独的软件包需要安装 - 并且是相同的
+开发和生产中的组件。
+
+- 从 `@agent-native/core/client` 导出为 `AgentPanel`，带有
+  仅限生产的变体 `ProductionAgentPanel`。
+- 提供完整的聊天/CLI/工作空间界面，因此座席输入保持开启
+  框架中其他地方使用的共享 Composer 堆栈。
+- 每回合都会读取 `application_state.navigation`，因此它已经知道是哪个
+  查看您所在的位置以及选择的内容 - 您无需重新解释“此”。
+
+### 应用程序与代码工具模式 {#tool-modes}
+
+面板以两种工具模式之一运行：
+
+- **应用程序模式** - 代理只有您的应用程序自己的工具：您的 actions
+  使用 `defineAction` 定义，加上导航和上下文。没有文件系统或
+  外壳访问。这就是最终用户得到的。
+- **代码模式** — 添加共享编码工具（`bash`、`read`、`edit`、`write`）
+  以及应用程序工具之上的数据库访问，因此代理可以更改应用程序的
+  自己的来源。代码请求被门控：当消息需要代码时
+  (`type: "code"`)并且没有连接支持代码的框架，面板显示
+  解释代码更改需要 Agent Native Desktop 或 Builder 的对话框；
+  当连接框架时，请求将路由到它和代码代理
+  工作时指示灯显示 (`useSendToAgentChat`)。对于规范
+  编码工具列表和共享UI合约，参见
+  [Agent-Native Code UI](/docs/code-agents-ui).
+
+```an-diagram title="Code-request gating" summary="A code-typed message needs a code-capable frame. With one connected, the request routes there; without one, the panel explains code changes need Desktop or Builder."
+{
+  "html": "<div class=\"diagram-gate\"><div class=\"diagram-node\" data-rough>message<br><small class=\"diagram-muted\">type: \\\"code\\\"</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough>code-capable frame connected?</div><div class=\"diagram-col\"><div class=\"diagram-pill ok\">yes &rarr; route to frame, show code-agent indicator</div><div class=\"diagram-pill warn\">no &rarr; dialog: needs Desktop or Builder</div></div></div>",
+  "css": ".diagram-gate{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-gate .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-gate .diagram-arrow{font-size:22px;line-height:1}.diagram-gate .center{text-align:center}"
+}
+```
+
+“代码模式”是代理功能切换 - 与环境开发模式不同
+（`NODE_ENV` / Vite）。客户端钩子是`useCodeMode()`。 （参见
+[Compatibility notes](#compatibility) 用于向后兼容别名。）
+
+在本地开发框架中，设置齿轮在这些模式之间切换。切换
+关闭代码模式隐藏框架自己的侧边栏并显示应用程序的应用内代理
+侧边栏位于 iframe 内，因此您可以准确预览最终用户所看到的内容。
+
+## 集成终端和CLI切换 {#cli-terminal}
+
+正在开发中，面板包括一个嵌入式终端（`AgentTerminal`，也
+来自 `@agent-native/core/client`），由 PTY 服务器支持。你可以运行一个真正的
+在应用程序旁边编码 CLI 并在它们之间切换；终端重新启动
+与选定的 CLI。
+
+支持的 CLI 来自核心 CLI 注册表
+(`packages/core/src/terminal/cli-registry.ts`)。仅允许这些命令
+生成 - PTY 服务器根据注册表验证请求的命令
+允许列表以防止注入：
+
+| CLI        | 命令       | 安装包                      |
+| ---------- | ---------- | --------------------------- |
+| Claude代码 | `claude`   | `@anthropic-ai/claude-code` |
+| Builder.io | `builder`  | （内置）                    |
+| Codex      | `codex`    | `@openai/codex`             |
+| 双子座CLI  | `gemini`   | `@google/gemini-cli`        |
+| 开放代码   | `opencode` | `opencode-ai`               |
+
+如果在 `PATH` 上找不到所选的 CLI，终端将回退到运行它
+通过 `npx --yes <install-package>@latest`（存在安装包的地方）。
+默认命令是`claude`。随时从代理面板设置切换 CLI
+时间。
+
+## Builder.io云框 {#cloud-frame}
+
+[Builder.io](https://www.builder.io) 提供托管框架
+相同的应用程序和相同的代理面板，在云端：
+
+- 实时协作 - 多个用户可以同时观看和互动。
+- 可视化编辑、角色和权限。
+- 并行代理执行以加快迭代速度。
+- 适合团队使用，每个人共享一个托管环境。
+
+来自嵌入式面板的代码请求以相同的方式路由到 Builder 框架
+它们路由到本地开发框架，因此上面的 dev-vs-prod 行为是
+两者一致。
+
+## 运行时 APIs {#runtime-apis}
+
+这些随 `@agent-native/core` 一起提供，是您的应用用来与
+代理，无论哪个框架托管它：
+
+1. **发送消息** — `sendToAgentChat()` 向代理发送消息。
+   `useSendToAgentChat()` 钩子用描述的代码请求门控包装它
+   并返回一个 `codeRequiredDialog` 元素进行渲染。参见
+   [Drop-in Agent](/docs/drop-in-agent) 的完整用法和选项。
+2. **生成状态** - `useAgentChatGenerating()` 跟踪代理何时
+   正在运行，因此 UI 可以显示进度，而无需直接轮询代理。
+3. **轮询同步** - 数据库支持的同步在代理时保持 UI 缓存最新
+   更改数据或应用程序状态。
+4. **操作系统** - `pnpm action <name>` 分派到相同的可调用
+   actions 代理作为工具调用，因此代理能做的任何事情，您都可以
+   脚本。
+
+## 运行它 {#running}
+
+嵌入式代理面板是每个应用程序的一部分 - 搭建一个模板，它是
+已经在那里：
+
+```bash
+npx @agent-native/core@latest create my-app --template mail --standalone
+cd my-app
+pnpm dev
+```
+
+本地开发框架（框架存储库中的私有 `@agent-native/frame` 包）是未发布到 npm 的内部工具包。它将活动应用程序的开发服务器加载到 iframe 中，并在其旁边安装嵌入式面板，通过 `app` 查询参数选择应用程序。集成CLI终端需要Agent Native Desktop，提供终端所需的本地代码和PTY访问；如果没有它，面板将显示聊天界面并提示您打开桌面以使用 CLI。
+
+## 兼容性说明 {#compatibility}
+
+“代码模式”概念以前被称为“开发模式”，因此有一些向后兼容
+名称仍然存在。您可以忽略这些，除非您正在维护旧的集成
+代码：
+
+- 底层 `AGENT_MODE` 环境变量，`/_agent-native/agent-chat/mode`
+  端点（其负载密钥仍然是`devMode`），以及`agent-chat.mode`
+  设置键未更改。
+- `useDevMode()` 仍然是 `useCodeMode()` 的已弃用别名。

package/corpus/core/docs/content/locales/zh-CN/getting-started.md

@@ -0,0 +1,199 @@
+---
+title: "开始使用"
+description: "创建代理应用，了解说明、skills 和 actions，然后观看代理调用其第一个操作。"
+---
+
+# 开始使用
+
+Agent-Native 应用程序为 AI 代理和您的 UI 提供相同的 actions、数据和
+状态。基本代理是由指导它的指令（skills 进行教学）组成的
+可重复的行为，以及让它做实际工作的 actions。
+
+**想要一个完整的应用程序开始吗？**克隆我们丰富的模板之一 -
+[Chat](/docs/template-chat), [Mail](/docs/template-mail),
+[Calendar](/docs/template-calendar), [Content](/docs/template-content),
+[Analytics](/docs/template-analytics) 和 [many more](/docs/cloneable-saas) —
+每个都是您自定义的全功能应用程序。
+
+从头开始构建？唯一的选择是您是否想要 UI —
+之后的一切（编写指令、添加 skills、定义 actions、运行
+代理）无论哪种方式都是相同的。
+
+```an-file-tree title="A basic Agent-Native agent"
+{
+  "entries": [
+    { "path": "AGENTS.md", "note": "always-on instructions: purpose, rules, tone, and the map of what the agent can do" },
+    { "path": ".agents/skills/customer-research/SKILL.md", "note": "a reusable playbook the agent loads when the task matches" },
+    { "path": "actions/summarize-week.ts", "note": "typed code the agent, UI, CLI, HTTP, MCP, A2A, jobs, and webhooks can run" }
+  ]
+}
+```
+
+无论您是从聊天 UI、无头代理还是完整应用程序开始，都是如此。
+UI改变表面；指令、skills 和 actions 为代理提供
+指导和行为。
+
+## 1。创建您的应用
+
+您需要 [Node.js 22+](https://nodejs.org) 和 [pnpm](https://pnpm.io)。
+
+在没有标志的情况下运行 `create`，它会询问您要如何开始（完整的模板，
+聊天，或无头）先于其他：
+
+```bash
+npx @agent-native/core@latest create my-app
+```
+
+或者传递一个标志来跳过提示：
+
+**想要 UI？** 从聊天模板开始。您将获得一名工作代理人以及
+可自定义的聊天UI，您添加的每个操作都会自动显示在其中：
+
+```bash
+npx @agent-native/core@latest create my-app --template chat
+```
+
+**只是无头原语？**开始无头 - 相同的 actions 和代理
+循环，无 UI shell：
+
+```bash
+npx @agent-native/core@latest create my-agent --headless
+```
+
+然后从您创建的文件夹安装：
+
+```bash
+cd my-agent # or my-app if you chose the Chat template
+pnpm install
+```
+
+从现在开始，两者是相同的。
+
+## 2。添加操作
+
+操作是您的代理（以及您的 UI）可以调用的一项操作。两个脚手架
+附带此示例：
+
+```an-annotated-code title="你的第一个 action"
+{
+  "filename": "actions/hello.ts",
+  "language": "ts",
+  "code": "import { defineAction } from \"@agent-native/core/action\";\nimport { z } from \"zod\";\n\nexport default defineAction({\n  description: \"从本地代理问好。\",\n  schema: z.object({\n    name: z.string().default(\"world\"),\n  }),\n  http: { method: \"GET\" },\n  readOnly: true,\n  run: async ({ name }) => {\n    return { message: `Hello, ${name}!` };\n  },\n});",
+  "annotations": [
+    { "lines": "5", "label": "工具描述", "note": "代理会读取 `description`，判断何时把它作为工具调用。" },
+    { "lines": "6-8", "label": "类型化契约", "note": "一个 zod `schema` 会校验来自每个入口的输入：代理、UI、HTTP、MCP 和 A2A。" },
+    { "lines": "9", "label": "HTTP verb", "note": "Opt this action into an auto-mounted HTTP endpoint." },
+    { "lines": "10", "label": "Read-only", "note": "`readOnly` marks the action as safe to call without approval and cacheable for queries." },
+    { "lines": "11-13", "label": "One implementation", "note": "The `run` body is the single source of truth that every surface executes." }
+  ]
+}
+```
+
+将 `hello` 替换为您域中的第一个实际操作。您定义一次；
+每个表面都会吸收它。
+
+使用 `AGENTS.md` 作为每回合都适用的指导。使用技能时
+代理需要可重用的工作流程或域过程。在以下情况下使用操作
+代理需要一种类型化、可测试的方式来读取数据、写入数据、调用 API 或
+执行批准。
+
+## 3。运行它
+
+直接调用操作：
+
+```bash
+pnpm action hello --name Steve
+```
+
+或请代理为您致电：
+
+```bash
+pnpm agent "Call the hello action for Steve and explain what happened."
+```
+
+如果您从聊天模板开始，请运行该应用并在
+浏览器 - 它已经可以调用您定义的每个操作：
+
+```bash
+pnpm dev
+```
+
+现在可以通过聊天 UI、CLI、HTTP、MCP、A2A 访问该操作
+计划作业和 webhooks。定义一次，从任何地方调用。
+
+```an-diagram title="One action, every surface" summary="A single defineAction file fans out to every consumer with no extra wiring."
+{
+  "html": "<div class=\"diagram-fan\"><div class=\"diagram-box\" data-rough>defineAction</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-surfaces\"><span class=\"diagram-pill\">Chat UI</span><span class=\"diagram-pill\">CLI</span><span class=\"diagram-pill\">HTTP</span><span class=\"diagram-pill\">MCP</span><span class=\"diagram-pill\">A2A</span><span class=\"diagram-pill\">Scheduled jobs</span><span class=\"diagram-pill\">Webhooks</span></div></div>",
+  "css": ".diagram-fan{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-fan .diagram-surfaces{display:flex;flex-wrap:wrap;gap:8px;max-width:420px}.diagram-fan .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## 状态是内置的
+
+无头并不意味着无状态。 Actions，会话，应用程序状态，线程，
+运行历史记录和凭据均位于 SQL 中。本地地址为 SQLite
+`data/app.db`；在生产中您设置 `DATABASE_URL`。请参阅
+[Deployment](/docs/deployment).
+
+```an-callout
+{
+  "tone": "info",
+  "body": "**Headless is still a real app.** The app-agent loop persists sessions, threads, runs, settings, and credentials in SQL — it is not a stateless prompt. You can add a UI later without touching your actions or state."
+}
+```
+
+## 自定义UI
+
+如果您从聊天模板开始，则可以编辑 UI。聊天本身
+是基于 `<AgentChatSurface>` 组件构建的一条小路线：
+
+```tsx
+// app/routes/_index.tsx
+import { AgentChatSurface } from "@agent-native/core/client";
+
+export default function ChatRoute() {
+  return <AgentChatSurface mode="page" className="h-full" />;
+}
+```
+
+- **`app/routes/_index.tsx`** — 聊天页面。更改建议，空
+  状态和布局。
+- **`app/root.tsx`** — 应用程序外壳。在周围添加您自己的路线和屏幕
+  代理。
+- 使用 `<AgentSidebar>` 将代理放入任何屏幕，从 a 手动操作它
+  使用 `sendToAgentChat()` 按钮，或直接使用
+  `useActionMutation()`.
+
+请参阅 [Drop-in Agent](/docs/drop-in-agent) 了解完整的组件集，并且
+[Native Chat UI](/docs/native-chat-ui) 将操作结果呈现为表格，
+图表和打字卡片而不是纯文本。
+
+**开始无头，稍后想要 UI？** 聊天模板*是* UI 入口 -
+它的`app/`层（React Router + Vite）正是无头脚手架
+省略。最干净的举动是从聊天开始（或重新搭建支架）
+模板；您的 `actions/`、代理和 SQL 状态保持不变。请参阅
+[Agent Surfaces](/docs/agent-surfaces) 代表其间的每个表面。
+
+## 项目结构
+
+```text
+my-app/
+  actions/         # Agent-callable actions
+  app/             # React frontend (UI templates only; omitted when headless)
+  server/          # Nitro API server (routes, plugins)
+  AGENTS.md        # Always-on agent instructions
+  .agents/         # Skills the agent can pull in when relevant
+  data/app.db      # Local SQLite state when DATABASE_URL is unset
+```
+
+## 下一步去哪里
+
+- **[Key Concepts](/docs/key-concepts)** — 核心架构：SQL、actions，
+  同步和上下文感知。
+- **[Actions](/docs/actions)** — 完整操作 API：架构、HTTP、身份验证和
+  批准。
+- **[Agent Surfaces](/docs/agent-surfaces)** — 无头、聊天、嵌入式 sidecar，
+  和完整的应用程序。
+- **[Drop-in Agent](/docs/drop-in-agent)** — 将代理聊天添加到任何 React 应用程序。
+- **[Deployment](/docs/deployment)** — 将您的应用放在您自己的域中。
+- **[FAQ](/docs/faq)** — 设置和产品问题。