@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,583 @@
+---
+title: "Actions"
+description: "defineAction - 成为代理工具、类型化前端挂钩、框架传输、MCP 工具和 CLI 命令的单一定义。"
+---
+
+# Actions
+
+Actions 是您的应用所做的任何事情的唯一事实来源。使用 `defineAction()` 定义一次操作，将其放入 `actions/` 中，然后立即可用：
+
+- **代理工具** — 代理通过 zod 派生的 JSON 架构查看它，并可以在聊天中调用它。
+- **类型安全 React 挂钩** - 前端的 `useActionQuery("name")` 和 `useActionMutation("name")`，从架构推断的类型。
+- **命令式客户端调用** — 当钩子不适合时 `callAction("name", params)`。
+- **框架传输** — 由这些钩子后面的框架自动安装，并可供外部 HTTP 客户端使用。
+- **MCP 工具** - 暴露给 Claude、ChatGPT 自定义 MCP 应用、Claude 桌面/代码、光标、Codex 和任何其他 MCP 客户端。
+- **A2A 工具** — 由其他代理本机应用通过 A2A 调用。
+- **CLI 命令** - `pnpm action <name>` 用于脚本和开发循环。
+
+一个定义，七个消费者。这是 [ladder](/docs/what-is-agent-native#the-ladder) 的第 3 级。
+如果您正在决定是否在聊天中、在聊天中无头公开操作
+嵌入式 sidecar，或作为完整的应用屏幕，请参阅 [Agent Surfaces](/docs/agent-surfaces)。
+
+```an-diagram title="One definition, seven consumers" summary="A single defineAction() fans out to every surface — agent, UI, HTTP, MCP, A2A, and CLI — with one validated schema and one run() body."
+{
+  "html": "<div class=\"diagram-fanout\"><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">defineAction()</span><small class=\"diagram-muted\">schema + run(), defined once</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-grid\"><div class=\"diagram-node\">Agent tool<br><small class=\"diagram-muted\">JSON Schema in context</small></div><div class=\"diagram-node\">React hooks<br><small class=\"diagram-muted\">useActionQuery/Mutation</small></div><div class=\"diagram-node\">callAction()<br><small class=\"diagram-muted\">imperative client</small></div><div class=\"diagram-node\">HTTP<br><small class=\"diagram-muted\">/_agent-native/actions/:name</small></div><div class=\"diagram-node\">MCP tool<br><small class=\"diagram-muted\">external hosts</small></div><div class=\"diagram-node\">A2A tool<br><small class=\"diagram-muted\">other agent-native apps</small></div><div class=\"diagram-node\">CLI<br><small class=\"diagram-muted\">pnpm action &lt;name&gt;</small></div></div></div>",
+  "css": ".diagram-fanout{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-fanout .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px 16px}.diagram-fanout .diagram-arrow{font-size:22px;line-height:1}.diagram-fanout .diagram-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:8px}"
+}
+```
+
+如果 UI 和代理都需要做某事，请采取行动 - 而不是自定义
+路线。对于何时路由型协议才是正确的调用，请参阅[首选 Actions
+对于应用程序操作](/docs/server#actions-first)。
+
+## 从一个动作开始 {#hello-action}
+
+原始优先入口是一个动作，而不是模板。在无头的情况下
+脚手架如`agent-native create my-agent --headless`，这个可以是
+整个第一个应用程序：
+
+```ts
+// actions/hello.ts
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+export default defineAction({
+  description: "从本地代理问好。",
+  schema: z.object({
+    name: z.string().default("world"),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async ({ name }) => {
+    return { message: `Hello, ${name}!` };
+  },
+});
+```
+
+从同一文件夹运行它：
+
+```bash
+pnpm action hello '{"name":"Steve"}'
+```
+
+CLI 接受 JSON 对象作为操作输入，它与结构化的匹配
+代理已进行工具调用。简单的标志仍然适用于快速手动运行：
+
+```bash
+pnpm action hello --name Steve
+```
+
+然后针对该文件夹运行应用程序代理循环：
+
+```bash
+pnpm agent "Call hello for Steve and explain the result"
+```
+
+这与您计划的作业、聊天 UI、外部 MCP 循环相同的应用程序代理
+工具，以及未来的屏幕将使用。聊天和域模板用于添加 UI
+大约 actions，不是操作本身的必需先决条件。
+
+## 定义操作 {#defining}
+
+```an-annotated-code title="Anatomy of an action"
+{
+  "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 in the user's voice.\",\n  schema: z.object({\n    emailId: z.string().describe(\"The id of the email to reply to.\"),\n    body: z.string().describe(\"The reply body, in markdown.\"),\n  }),\n  run: async ({ emailId, body }) => {\n    await db.insert(replies).values({ emailId, body });\n    return { ok: true, emailId };\n  },\n});",
+  "annotations": [
+    { "lines": "5", "label": "Tool surface", "note": "`description` is what the agent reads to decide when to call this. The per-field `.describe()` calls flow into the JSON Schema too." },
+    { "lines": "6-9", "label": "类型化契约", "note": "One schema validates input from **every** surface and is converted to JSON Schema for the model. Invalid inputs never reach `run`." },
+    { "lines": "10-13", "label": "One implementation", "note": "The `run` body is the single source of truth — the UI button and the agent tool both execute exactly this." }
+  ]
+}
+```
+
+就是这样。该框架会自动发现 `actions/` 中的每个文件并在启动时挂载它们。
+
+### 架构选项 {#schemas}
+
+`schema` 接受任何 [Standard Schema](https://standardschema.dev) 兼容库：
+
+- **Zod** (v4) — 最常见、最佳类型推断，自动转换为 JSON 架构。
+- **Valibot** — 最小捆绑包大小（如果重要的话）。
+- **ArkType** — 如果您喜欢语法。
+
+该架构将转换为 Claude API 工具定义的 JSON 架构，并在运行时用于在 `run()` 触发之前验证输入。无效输入永远不会到达您的处理程序。
+
+### 验证返回值 {#output-schema}
+
+`schema` 验证*输入*。要验证操作 **返回**，请传递 `outputSchema`（任何标准模式兼容模式 - Zod、Valibot、ArkType、与 `schema` 相同的表面）。框架在 `run()` 解析之后验证结果，并与输入验证组合：在 `run` 之前验证输入，在 `run` 之后验证输出。
+
+```ts
+export default defineAction({
+  description: "Summarize a thread.",
+  schema: z.object({ threadId: z.string() }),
+  outputSchema: z.object({
+    summary: z.string(),
+    messageCount: z.number(),
+  }),
+  outputErrorStrategy: "warn", // default
+  run: async ({ threadId }) => {
+    /* ...returns { summary, messageCount } ... */
+  },
+});
+```
+
+`outputErrorStrategy` 控制不匹配时发生的情况：
+
+| 策略         | 不匹配时的行为                                                 |
+| ------------ | -------------------------------------------------------------- |
+| `"warn"`     | **默认。** `console.warn` 问题并返回**原始**结果不变。不间断。 |
+| `"strict"`   | 抛出一个明显的错误，以便大声地浮现出有问题的操作。             |
+| `"fallback"` | 返回提供的 `outputFallback` 值来代替无效结果。                 |
+
+成功后，将返回 **validated** 值，因此 `outputSchema` 上定义的任何强制或默认值都会生效（镜像输入路径）。当没有提供 `outputSchema` 时，行为是逐字节不变的——没有包装。这是从 Mastra/Flue 结构化输出借来的，并且在操作层上保持无依赖性。
+
+### HTTP配置 {#http}
+
+默认情况下，每个操作都公开为 `POST /_agent-native/actions/<name>`。使用 `http` 选项覆盖：
+
+```ts
+export default defineAction({
+  description: "Get details for a lead.",
+  schema: z.object({ leadId: z.string() }),
+  http: { method: "GET" },
+  run: async ({ leadId }) => {
+    return await db.select().from(leads).where(eq(leads.id, leadId));
+  },
+});
+```
+
+对于 `GET` 操作，`leadId` 作为查询参数传递：`/_agent-native/actions/get-lead?leadId=abc`。
+
+```an-api title="The auto-mounted action endpoint" method="GET" path="/_agent-native/actions/get-lead"
+{
+  "method": "GET",
+  "path": "/_agent-native/actions/get-lead",
+  "summary": "Every action is mounted here automatically — the filename is the action name.",
+  "description": "POST by default; `http: { method: \"GET\" }` makes it a GET. The React hooks and `callAction` always call this path by name, regardless of any `http.path` override.",
+  "auth": "Session cookie; frontend calls carry `X-Agent-Native-Frontend: 1`",
+  "params": [
+    { "name": "leadId", "in": "query", "type": "string", "required": true, "description": "GET args arrive as query params; POST args arrive in the JSON body." }
+  ],
+  "responses": [
+    { "status": "200", "description": "The action's return value as JSON." },
+    { "status": "400", "description": "Input failed schema validation before run() fired." }
+  ]
+}
+```
+
+- **`http: { method: "GET" | "POST" | "PUT" | "DELETE" }`** — 默认 `POST`。 `GET` actions 会自动标记为 `readOnly`，因此成功的调用不会触发 UI 轮询刷新。
+- **`http: { path: "..." }`** — 覆盖 `/_agent-native/actions/` 下安装的 URL。默认为文件名。 **路径覆盖仅针对直接 HTTP 调用方更改 URL** — 无论此覆盖如何，`useActionQuery`、`useActionMutation` 和 `callAction` 始终调用 `/_agent-native/actions/<name>`，因此覆盖路径会使这些挂钩 404。仅对外部 HTTP 调用方使用路径覆盖。另请注意，覆盖路径中的 `:param` 路由段**不会**解析为 `run()` 参数 - 只有查询字符串参数和 JSON 正文字段。
+- **`http: false`** — 完全禁用 HTTP 端点。仅限代理 + CLI。
+- **`readOnly: true`** — 即使对于不变异的 POST actions 也显式跳过轮询刷新。
+- **`parallelSafe: true`** — 允许变异操作与其他同回合工具调用同时运行。仅当操作内部并发安全且与顺序无关时才设置此项；默认情况下改变 actions 序列化。
+
+### 保持操作面较小 {#small-surface}
+
+代理可以看到的每个动作都是模型上下文窗口中的一个工具，而长而重叠的工具列表会降低模型的工具选择质量。将操作界面设计为您维护的 API，而不是为每个 UI 功能提供一个操作：
+
+- 更喜欢**一个 CRUD 风格的 `update`**，它采用一个可选字段补丁，而不是 N 个每个字段 actions（`update-name`、`update-order`、`update-color`，...）。调用者仅发送更改的内容。
+- 在为每个查询/过滤器添加新的读取操作之前，请使用通用逃生口：用于提供程序数据的 [provider API trio](/docs/template-dispatch) (`provider-api-catalog` / `provider-api-docs` / `provider-api-request`) 或用于应用程序数据的 dev `db-query` 工具。
+- 标记仅 UI 或编程 actions [`agentTool: false`](#agent-tool)，以便它们保持前端/HTTP 可调用，而无需在模型的工具列表中占用一个位置。
+- 删除或隐藏 UI 不再使用的 actions，而不是将它们暴露给模型。
+
+回购级咨询助手 `node scripts/audit-template-actions.mjs [template ...]`（别名 `pnpm actions:audit`）静态扫描模板的 `actions/` 并标记可能的 UI 死 actions 和冗余的每字段集群。它仅是建议性的（始终退出 0，永远不会失败 CI）并使用保守的启发式方法，因此请查看其建议，而不是将其视为错误。
+
+### 曝光标志 {#exposure-flags}
+
+四个标志控制谁可以调用操作。所有默认值都为允许值，因此您只需设置一个即可收紧特定表面。该表是一目了然的摘要；这些小节添加了每个需要的细节。
+
+| 标记            | 默认         | 限制值→谁仍然可以调用                                          | 典型用途                                        |
+| --------------- | ------------ | -------------------------------------------------------------- | ----------------------------------------------- |
+| `agentTool`     | `true`       | `false` → 仅 UI、HTTP、CLI — **对模型隐藏**、MCP 和 A2A        | 仅 UI/程序化 actions，不应该花费工具槽          |
+| `toolCallable`  | `true`       | `false` → 一切**除了**沙盒扩展 iframe 桥 (403)                 | 授权相邻操作（删除帐户、更改组织成员资格/角色） |
+| `publicAgent`   | 关闭（私人） | `{ expose: true }` → 将操作添加到**公共** MCP/A2A/OpenAPI 表面 | 无需身份验证即可访问安全读取/摄取工具           |
+| `needsApproval` | `false`      | `true` → 特工**暂停**；人类必须批准特定的呼叫                  | 间接副作用（发送电子邮件、为卡充值、删除）      |
+
+这些是独立的：`agentTool` 控制模型的视图，`toolCallable` 仅控制扩展 iframe，`publicAgent` 添加选择加入的公共界面（公共 Web 路由绝不意味着公开工具暴露），而 `needsApproval` 在调用后控制执行 - 请参阅下面的 [Human-in-the-loop approval](#needs-approval)。
+
+#### `agentTool` — 隐藏模型 {#agent-tool}
+
+默认情况下，每个操作都是可调用的代理工具。设置 `agentTool: false` 以将其保留在框架的身份验证 + 操作界面后面，同时将其从每个代理工具列表中删除 - 它仍然可以从 UI (`useActionMutation` / `callAction`)、CLI 和 `/_agent-native/actions/<name>` 进行调用：
+
+```ts
+export default defineAction({
+  description: "Persist the user's sidebar width.",
+  agentTool: false, // UI-only — not a tool in the model's context window
+  schema: z.object({ widthPx: z.number() }),
+  http: { method: "PUT" },
+  run: async ({ widthPx }) => {
+    /* ... */
+  },
+});
+```
+
+当您添加仅 UI 或纯编程操作时，或者当 UI 停止使用您本来会暴露给模型的操作时，请使用它。
+
+#### `toolCallable` — 阻止扩展 iframe {#tool-callable}
+
+扩展程序 ([Alpine.js mini-apps in sandboxed iframes](/docs/extensions)) 通过 `appAction(name, params)` 调用 actions，以查看者的权限、机密和 SQL 范围运行。对于高爆炸半径的操作，默认情况下信任度过高。设置 `toolCallable: false` 以使扩展桥返回 403，同时保持可从 UI、代理、CLI、MCP 和 A2A 调用的操作：
+
+```ts
+export default defineAction({
+  description: "Delete the current user's account.",
+  toolCallable: false, // never callable from an extension iframe
+  schema: z.object({ confirm: z.literal("yes") }),
+  run: async () => {
+    /* ... */
+  },
+});
+```
+
+将其用于 actions，删除或转移帐户/组织、更改身份验证状态、修改组织成员资格或授予共享访问权限。该框架的内置 `share-resource`、`unshare-resource` 和 `set-resource-visibility` 已被选择退出。通过 iframe 调用上不可欺骗的主机集标头执行；常规 UI/agent/CLI/MCP/A2A 呼叫不受影响 - 详情请参阅 [Security](/docs/security)。
+
+### 运行上下文（第二个参数） {#run-context}
+
+`run` 接收可选的第二个参数 `ctx`，它携带解析的请求标识和调用操作的表面。读取它而不是手动调用`getRequestUserEmail()` / `getRequestOrgId()`，并将整个`ctx`传递给跟踪：
+
+```ts
+export default defineAction({
+  description: "Log an audit entry for the current request.",
+  schema: z.object({ event: z.string() }),
+  run: async (args, ctx) => {
+    // ctx is undefined-safe: a 1-arg `run(args)` is still valid.
+    const actor = ctx?.userEmail ?? "system";
+    if (ctx?.caller === "frontend") {
+      // tighter rules for browser-initiated calls, looser for "tool"/"cli"
+    }
+    await db.insert(audit).values({
+      actor,
+      orgId: ctx?.orgId ?? null,
+      source: ctx?.caller ?? "unknown",
+      event: args.event,
+    });
+    return { ok: true };
+  },
+});
+```
+
+`ActionRunContext` 字段：
+
+| 字段          | 类型                    | 注释                                                                                                                                                            |
+| ------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `userEmail`   | `string \| undefined`   | Resolved request user. **Never defaulted to a dev identity** — `undefined` when the request has no authenticated user. Apply your own fallback if you need one. |
+| `orgId`       | `string \| null`        | Resolved org id, or `null` when the request has no org.                                                                                                         |
+| `caller`      | `ActionCaller`          | 如何调用操作（见下文）。                                                                                                                                        |
+| `send`        | `(event) => void`       | 可选。向客户端发出 SSE 事件。仅存在于代理工具循环内部（`caller: "tool"`）； `undefined` 其他地方。                                                              |
+| `attachments` | `AgentChatAttachment[]` | 当前代理提交的文件、图像和粘贴的文本块。仅当`caller: "tool"`时才填充； `undefined` 在所有其他表面上。                                                           |
+
+`caller` 是并集 `"tool" | "http" | "frontend" | "cli" | "mcp" | "a2a"`：
+
+| `caller`     | 设置当...                                                                                                             |
+| ------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `"tool"`     | 应用内代理循环、子代理/代理团队或 A2A 请求（A2A 驱动相同的代理循环，因此其工具调用为 `"tool"`）。                     |
+| `"frontend"` | 通过 `useActionMutation` / `useActionQuery` / `callAction` 的浏览器调用（用 `X-Agent-Native-Frontend: 1` 标头标记）。 |
+| `"http"`     | 没有前端标记的裸编程 `POST` / `GET` 到 `/_agent-native/actions/<name>`。                                              |
+| `"cli"`      | `pnpm action <name>`（CLI 跑步者）。                                                                                  |
+| `"mcp"`      | MCP `tools/call` 端点上的外部代理。                                                                                   |
+| `"a2a"`      | 保留用于将来的直接 A2A 操作调度。今天 A2A 运行在代理循环中，因此这些调用是 `"tool"`。                                 |
+
+`run` 保持向后兼容：现有的 1 参数处理程序和仅解构 `{ send }` 的处理程序继续保持不变。
+
+### actions中的访问控制 {#access-control}
+
+用户拥有的表必须通过 `accessFilter` 进行读取，并通过 `assertAccess` 进行写入——框架的共享系统使用相同的帮助程序。这是一个完整的、可粘贴的示例：
+
+```ts
+// actions/create-lead.ts
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+import { getDb } from "../server/db/index.js";
+import * as schema from "../server/db/schema.js";
+
+export default defineAction({
+  description: "Create a lead in the CRM.",
+  schema: z.object({ name: z.string(), company: z.string() }),
+  run: async ({ name, company }, ctx) => {
+    const db = getDb();
+    await db.insert(schema.leads).values({
+      id: crypto.randomUUID(),
+      name,
+      company,
+      ownerEmail: ctx?.userEmail ?? "system",
+    });
+    return { ok: true };
+  },
+});
+```
+
+对于列出和读取 actions，请使用 `accessFilter` 将查询范围限定为当前用户和组织。对于更新或删除特定行的 actions，在写入之前使用 `assertAccess` 来确认调用者是否被允许。请参阅 [Security](/docs/security#access-guards) 和 [Sharing](/docs/sharing) 了解完整助手 API。
+
+### 人机交互批准 {#needs-approval}
+
+少数 actions 过于重要，无法让代理自主运行 - 发送电子邮件、为卡充值、删除帐户。对于这些，设置 `needsApproval` 暂停循环并要求人员在 `run()` 执行之前批准特定调用：
+
+```ts
+export default defineAction({
+  description: "Send an email via Gmail.",
+  schema: z.object({ to: z.string(), subject: z.string(), body: z.string() }),
+  needsApproval: true, // pause; a human must approve this specific send
+  run: async (args) => {
+    /* ...actually send... */
+  },
+});
+```
+
+`needsApproval` 还接受谓词 `(args, ctx) => boolean | Promise<boolean>` 进行有条件的门控（例如，仅外部接收者，仅高于阈值）；它**无法关闭**，因此抛出算作“需要批准”。当门为真且未经批准时，循环会停止回合，并且副作用永远不会触发，直到有人在聊天 UI 中批准为止。
+
+> [!WARNING]
+> 保持很少的批准。每个门控操作都是代理循环中的硬停止。默认值为**关闭**，几乎每个操作都应将其关闭。请参阅 [Human-in-the-Loop Approvals](/docs/human-approval) 了解谓词 API、`approval_required` 事件和完整流程。
+
+### 审核日志记录 {#audit}
+
+每个变异操作都会被**自动审核**——框架会记录谁运行它、何时运行、从哪个表面运行、以及（当它是代理时）哪个线程/轮次，以及经过凭据编辑的输入。只读 (`GET`) actions 被跳过。您无需为此编写任何代码；它发生在 `defineAction` 接缝处。
+
+仅将 `audit` 块添加到 _tune_ capture - 最有用的是声明操作更改的资源，以便更改显示在该资源所有者的跟踪中：
+
+```ts
+export default defineAction({
+  description: "Delete a recording.",
+  schema: z.object({ id: z.string() }),
+  audit: {
+    target: (args, result) => ({ type: "recording", id: args.id }),
+    summary: (args) => `Deleted recording ${args.id}`,
+  },
+  run: async (args, ctx) => {
+    /* ...delete... */
+  },
+});
+```
+
+其他旋钮：`audit: { onRead: true }` 审核敏感读取（秘密访问、批量导出）； `audit: { enabled: false }` 选择噪声写入； `audit: { recordInputs: false }` 跳过捕获参数。使用内置 `list-audit-events` / `get-audit-event` actions 读取轨迹。详细信息请参见 [Audit Log](/docs/audit-log)。
+
+## 从UI调用 {#ui}
+
+两个挂钩，均位于 `@agent-native/core/client` 中。类型是从您的 `defineAction` 架构中推断出来的 - 无需手动类型声明。
+
+### `useActionMutation` {#use-action-mutation}
+
+对于改变状态的actions：
+
+```tsx
+import { useActionMutation } from "@agent-native/core/client";
+
+const { mutate, isPending } = useActionMutation("reply-to-email");
+
+<Button
+  disabled={isPending}
+  onClick={() => mutate({ emailId, body: "Thanks!" })}
+>
+  Send Reply
+</Button>;
+```
+
+成功后，框架会发出 `source: "action"` 的更改事件，以便 `useActionQuery` 使用者和活动查询观察者自动重新获取。参见[Live Sync](/docs/key-concepts#polling-sync)。
+
+### `useActionQuery` {#use-action-query}
+
+对于只读 GET actions：
+
+```ts
+import { useActionQuery } from "@agent-native/core/client";
+
+const { data, isLoading } = useActionQuery("get-lead", { leadId });
+```
+
+查询缓存在 `["action", "get-lead", { leadId }]` 下，并在完成任何变异操作后自动失效。
+
+## 渲染原生聊天UI {#native-chat-ui}
+
+Actions 可以返回应用内聊天呈现的结构化小部件数据
+本地。这是可重用表格、图表、设置的第一方聊天路径
+摘要和见解卡；使用 [MCP Apps](/docs/mcp-apps) 进行内联 UI
+外部 MCP 主机。
+
+```ts
+import { defineAction } from "@agent-native/core/action";
+import { ACTION_CHAT_UI_DATA_INSIGHTS_RENDERER } from "@agent-native/core/action-ui";
+import {
+  createDataInsightsWidgetResult,
+  dataInsightsWidgetResultSchema,
+} from "@agent-native/core/data-widgets";
+
+export default defineAction({
+  description: "Summarize response trends.",
+  readOnly: true,
+  outputSchema: dataInsightsWidgetResultSchema,
+  chatUI: { renderer: ACTION_CHAT_UI_DATA_INSIGHTS_RENDERER },
+  run: async () =>
+    createDataInsightsWidgetResult({
+      title: "Response trends",
+      chartSeries: {
+        type: "line",
+        xKey: "day",
+        series: [{ key: "responses", label: "Responses" }],
+        data: [
+          { day: "Mon", responses: 12 },
+          { day: "Tue", responses: 18 },
+        ],
+      },
+      table: {
+        columns: [
+          { key: "day", label: "Day" },
+          { key: "responses", label: "Responses", align: "right" },
+        ],
+        rows: [
+          { day: "Mon", responses: 12 },
+          { day: "Tue", responses: 18 },
+        ],
+      },
+    }),
+});
+```
+
+内置判别式为 `"data-table"`、`"data-chart"` 和
+`"data-insights"`，具有服务器安全的构建器和架构
+`@agent-native/core/data-widgets`。见[Native Chat UI](/docs/native-chat-ui)
+获取完整结果合约和 BYO 运行时指南，或
+[Agent Surfaces](/docs/agent-surfaces) 了解如何保持相同的操作
+无头、在聊天中渲染或变成全屏。
+
+## 从CLI调用 {#cli}
+
+每个操作都可以通过 `pnpm action` 运行：
+
+```bash
+pnpm action reply-to-email '{"emailId":"thread-123","body":"Thanks!"}'
+```
+
+JSON 输入是代理和复杂对象的首选形状。标志是
+仍然解析为相同的模式形状，以进行简单的手动运行和现有
+脚本。对于代理开发循环、脚本和 cron 很有用。
+
+## 从另一个代理调用它（A2A） {#a2a}
+
+如果您的应用程序是 [A2A](/docs/a2a-protocol) 对等点，则其他代理本机应用程序会自动发现您的 actions 并可以通过名称调用它们。同源部署跳过JWT签名；跨域使用共享的`A2A_SECRET`。
+
+## 通过 MCP 公开它 {#mcp}
+
+启用 MCP 后，您的 actions 将显示在框架的 MCP 服务器中，位置为 `/_agent-native/mcp`。默认情况下，每个调用者都会获得一个紧凑的目录 - 面向应用程序的内置程序以及模板声明的应用程序 actions - 并且 `tool-search` 始终存在，因此任何其他工具都可以按需访问。完整的操作界面仅在明确选择加入（`--full-catalog` 代币或 `AGENT_NATIVE_MCP_FULL_CATALOG=1`）时提供，并且 `publicAgent.expose` 在公共界面上选择安全读取/摄取工具。请参阅 [MCP Protocol](/docs/mcp-protocol) 了解目录层、身份验证和 `mcpApp` 资源详细信息。
+
+对于支持 UI 的 MCP 主机，操作可以通过 `mcpApp` 字段（加上匹配的 `link`）声明可选的 MCP Apps 资源，以便有能力的主机内联渲染结果。当 `link` 和 `mcpApp` 应指向同一路线时，`embedRoute()` 从一个纯路径构建器构建两者：
+
+```ts
+import { embedRoute } from "@agent-native/core";
+
+export default defineAction({
+  description: "Create an email draft for review.",
+  schema: z.object({ body: z.string() }),
+  run: async ({ body }) => ({ body }),
+  ...embedRoute({
+    title: "Review draft",
+    openLabel: "Open in Mail",
+    path: ({ result }) => ({
+      label: "Open draft in Mail",
+      url: "/_agent-native/open?app=mail&view=inbox",
+    }),
+  }),
+});
+```
+
+保留 `link` 作为 CLI 和非 UI MCP 客户端的后备；这也是嵌入的启动目标。嵌入桥 - 已签名的嵌入启动会话、移植与受控帧渲染、`ui/*` 主桥、CSP 和高度限制 - 归 [External Agents](/docs/external-agents#mcp-app-bridge) 所有。
+
+## 标准actions {#standard-actions}
+
+对于 [context awareness](/docs/context-awareness)，每个模板都应包含这两个：
+
+### 查看屏幕 {#view-screen}
+
+读取当前导航状态，获取上下文数据，并返回用户所看到内容的快照。当代理需要重新查看屏幕时会调用此函数。
+
+```ts
+// actions/view-screen.ts
+import { defineAction } from "@agent-native/core/action";
+import { readAppState } from "@agent-native/core/application-state";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Read the current screen state for context.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  run: async () => {
+    const navigation = await readAppState("navigation");
+    const screen: Record<string, unknown> = { navigation };
+
+    if (navigation?.view === "inbox") {
+      screen.emailList = await listEmailsForLabel(navigation.label);
+    }
+
+    return screen;
+  },
+});
+```
+
+### 导航 {#navigate}
+
+将一次性导航命令写入应用程序状态。 UI 读取它、导航并删除该条目。
+
+```ts
+// actions/navigate.ts
+import { defineAction } from "@agent-native/core/action";
+import { writeAppState } from "@agent-native/core/application-state";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Navigate the user to a view.",
+  schema: z.object({
+    view: z.string(),
+    threadId: z.string().optional(),
+  }),
+  run: async (args) => {
+    await writeAppState("navigate", args);
+    return { ok: true };
+  },
+});
+```
+
+## 旧版 CLI 样式 actions {#legacy-cli-actions}
+
+该框架仍然支持未包含在 `defineAction` 中的较旧的 `export default async function(args)` actions - 对于不需要代理/HTTP 暴露的一次性开发脚本很有用。这些仅限 CLI；它们不会显示为代理工具，不会挂载 HTTP 端点，也不会获得类型安全的前端挂钩。
+
+```ts
+// actions/debug-dump.ts — CLI-only
+import { parseArgs } from "@agent-native/core";
+
+export default async function main(args: string[]) {
+  const { table } = parseArgs(args);
+  // one-off script you wouldn't want the agent to call
+}
+```
+
+新代码应该更喜欢 `defineAction()`。仅当您故意不希望操作暴露给代理或 UI 时，才采用此模式。
+
+### `parseArgs(args)` {#parseargs}
+
+旧式 actions 的帮助程序。解析 `--key value` 或 `--key=value` 格式的 CLI 参数：
+
+```ts
+import { parseArgs } from "@agent-native/core";
+
+const args = parseArgs(["--name", "Steve", "--verbose", "--count=3"]);
+// { name: "Steve", verbose: "true", count: "3" }
+```
+
+## 实用函数 {#utility-functions}
+
+| 功能                    | 退货      | 描述                                     |
+| ----------------------- | --------- | ---------------------------------------- |
+| `loadEnv(path?)`        | `void`    | 从项目根目录（或自定义路径）加载`.env`。 |
+| `camelCaseArgs(args)`   | `Record`  | 将短横线大小写键转换为驼峰式大小写。     |
+| `isValidPath(p)`        | `boolean` | 验证相对路径（无遍历，无绝对）。         |
+| `isValidProjectPath(p)` | `boolean` | 验证项目段（例如 `my-project`）。        |
+| `ensureDir(dir)`        | `void`    | `mkdir -p` 助手。                        |
+| `fail(message)`         | `never`   | 打印到stderr和`exit(1)`。                |
+
+## 下一步是什么
+
+- [**Audit Log**](/docs/audit-log) — 每个操作的自动谁更改了什么跟踪
+- [**Human-in-the-Loop Approvals**](/docs/human-approval) — `needsApproval` 门的深度
+- [**Drop-in Agent**](/docs/drop-in-agent) — React 中的 `useActionMutation` / `useActionQuery`
+- [**Context Awareness**](/docs/context-awareness) — `view-screen` + `navigate` 模式的深度
+- [**A2A Protocol**](/docs/a2a-protocol) — 其他代理如何发现并呼叫您的 actions
+- [**MCP Protocol**](/docs/mcp-protocol) — 在 MCP 上暴露 actions