@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/zh-CN/agent-teams.md

@@ -0,0 +1,171 @@
+---
+title: "代理团队"
+description: "主代理代表向在自己的线程中运行的子代理工作，并在聊天中显示为内嵌的实时预览芯片。"
+---
+
+# 代理团队
+
+代理聊天是一个**协调器**，而不是一个整体。当主代理完成一项更适合由专家负责的任务时——“用我的声音写这封电子邮件”、“运行 BigQuery 分析”、“查看此 PR”——它会在自己的线程、工具和上下文中生成一个子代理。子代理在主聊天中显示为实时预览**芯片**；单击它以选项卡形式打开完整对话。
+
+这可以保持主线程集中，让子代理并行运行，并为您提供任何委派工作的清晰审计跟踪。
+
+Agent Teams 在核心运行管理器上运行：事件流并持续，中止通过 SQL 传播，任务在无服务器冷启动中幸存。
+
+## 心智模型 {#mental-model}
+
+- **主聊天** — 协调器。代表们，请阅读您的请求。繁重的工作本身很少。
+- **子代理** — 使用自己的线程、自己的系统提示符、自己的工具集运行。每个映射到 [workspace](/docs/workspace) 中的“自定义代理”配置文件。
+- **Chips** — 主聊天中内联显示的丰富预览卡，显示子代理的当前步骤、流输出和最终摘要。默认折叠；点击即可展开完整对话。
+- **双向消息传递** - 主代理可以向正在运行的子代理发送后续消息；当子代理遇到模糊点时可以回复消息。
+
+子代理状态保留在 `application_state` SQL 表（在 `agent-task:<taskId>` 下）中，因此任务可以在无服务器冷启动中幸存并跨多个进程工作。
+
+```an-diagram title="Orchestrator and specialists" summary="The main chat delegates to sub-agents that run in their own threads and report back as inline chips."
+{
+  "html": "<div class=\"at-orc\"><div class=\"diagram-card main\"><span class=\"diagram-pill accent\">Main chat</span><small class=\"diagram-muted\">orchestrator &mdash; reads your request, delegates</small></div><div class=\"at-fan\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"at-subs\"><div class=\"diagram-box\">Code review<br><small class=\"diagram-muted\">own thread &amp; prompt</small></div><div class=\"diagram-box\">BigQuery analysis<br><small class=\"diagram-muted\">own tools</small></div><div class=\"diagram-box\">Email in voice<br><small class=\"diagram-muted\">own context</small></div></div></div><div class=\"diagram-pill\">each appears inline as a live chip &#8635;</div></div>",
+  "css": ".at-orc{display:flex;flex-direction:column;align-items:center;gap:12px}.at-orc .diagram-card{padding:14px 18px;display:flex;flex-direction:column;gap:4px;align-items:center}.at-orc .at-fan{display:flex;flex-direction:column;align-items:center;gap:8px}.at-orc .diagram-arrow{font-size:22px}.at-orc .at-subs{display:flex;gap:12px;flex-wrap:wrap;justify-content:center}.at-orc .diagram-box{text-align:center}"
+}
+```
+
+## 何时生成子代理 {#when-to-spawn}
+
+任务出现时：
+
+- 需要不同的**系统提示**（专业的声音或语气，例如“代码审查”）。
+- 拥有一个**长时间运行**的工具链，会污染主要上下文。
+- 可以与主代理正在执行的其他工作**并行**运行。
+- 由一个**不同的团队**拥有，该团队已经拥有自定义代理配置文件。
+
+不要为了琐碎的一次性工作而生成 - 直接调用操作。
+
+## 调用子代理 {#invoking}
+
+启动子代理的三种方法，从最简单到最明确：
+
+### 1。 `@mention` 自定义代理 {#mention}
+
+用户在聊天编辑器中键入 `@agent-name`。将出现工作区子代理的下拉列表。选择其中一个插入芯片；提交后，主代理将消息委托给该子代理。
+
+自定义代理位于 `agents/<slug>.md` 的工作区中 — 一个带有 YAML frontmatter 的 Markdown 文件。格式请参见[Custom Agents](/docs/workspace#custom-agents)。
+
+### 2。主代理自动委托 {#auto-delegate}
+
+该框架为主代理提供了一个 `agent-teams` 工具。当模型确定任务适合已注册的子代理配置文件时，它会使用 `action: "spawn"` 和可选的 `agent` 参数调用该工具，该参数从 `agents/*.md` 命名配置文件。出现一个芯片；子代理运行。主代理等待（或并行移动）并在子代理完成时合并结果。
+
+完整的 `agent-teams` 操作集是：
+
+| 行动          | 目的                       |
+| ------------- | -------------------------- |
+| `spawn`       | 启动新的子代理任务         |
+| `status`      | 检查正在运行的子代理的进度 |
+| `read-result` | 获取完成的子代理的输出     |
+| `send`        | 向正在运行的子代理发送消息 |
+| `list`        | 查看当前用户的所有任务     |
+
+### 3。程序化生成 {#programmatic-spawn}
+
+对于框架级集成，请使用 `@agent-native/core/server` 中的 `spawnTask()`：
+
+```ts
+import { spawnTask } from "@agent-native/core/server";
+
+const task = await spawnTask({
+  description: "Draft an outreach email to this lead",
+  instructions: "Match Steve's voice from memory/MEMORY.md.",
+  ownerEmail: user.email,
+  systemPrompt: mailAgentSystemPrompt,
+  actions: mailActions,
+  // Pass either apiKey or engine — engine takes precedence.
+  apiKey: process.env.ANTHROPIC_API_KEY, // optional if engine is provided
+  parentSend: emit, // streaming sender for the parent chat response
+});
+```
+
+大多数应用程序代码不会直接调用它 - 框架在 `@mentions` 和 `agent-teams` 工具的后台执行此操作。仅当您连接新的入口点（例如，启动作为子代理运行的后台作业的按钮）时，才需要使用 `spawnTask()`。
+
+## 任务生命周期 {#lifecycle}
+
+```an-diagram title="What spawnTask() does" summary="Each spawn creates a thread, persists state to SQL, and streams chip events through to completion."
+{
+  "html": "<div class=\"at-life\"><div class=\"diagram-box\"><code>spawnTask()</code></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">create thread</span><small class=\"diagram-muted\">new row in <code>chat_threads</code>, description as first message</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">persist state</span><small class=\"diagram-muted\"><code>agent-task:&lt;id&gt;</code> &rarr; <code>application_state</code>, status=running</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">stream</span><small class=\"diagram-muted\"><code>agent_task_started</code> &rarr; chip appears; <code>agent_task_step</code> &rarr; chip updates live</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card ok\"><span class=\"diagram-pill ok\">complete</span><small class=\"diagram-muted\">status=completed, write summary + preview, emit <code>agent_task_done</code></small></div></div>",
+  "css": ".at-life{display:flex;flex-direction:column;align-items:stretch;gap:6px;max-width:560px}.at-life .diagram-card{display:flex;flex-direction:column;gap:3px;padding:10px 14px}.at-life .diagram-box{align-self:flex-start}.at-life .diagram-arrow{font-size:18px;align-self:center}"
+}
+```
+
+父代理可以随时通过 `sendToTask(taskId, message)` 恢复子代理并进行后续操作。如果子代理发生错误，`markTaskErrored(taskId, reason)` 会记录失败并将其呈现给用户。
+
+双向消息传递是持久的。运行子代理的父级后续操作是
+通过任务生命周期交付；如果子代理无法在
+当前步骤，它们应该保持排队并在安全的地方应用
+延续点。子代理也可以在需要澄清时回复消息
+而不是无形地阻塞。
+
+## 读取任务状态 {#reading-state}
+
+来自服务器代码或其他actions：
+
+```ts
+import { getTask, listTasks } from "@agent-native/core/server";
+
+const task = await getTask(taskId); // single task
+const tasks = await listTasks(); // all tasks for the user (sorted newest first)
+```
+
+`AgentTask` 关键字段：
+
+```ts
+interface AgentTask {
+  taskId: string;
+  threadId: string;
+  description: string;
+  status: "running" | "completed" | "errored";
+  preview: string; // short one-liner for the chip
+  summary: string; // full summary once completed
+  currentStep: string; // latest step label (updated while running)
+  createdAt: number;
+  // Additional fields: parentThreadId, name, updatedAt, startedAt,
+  // completedAt, runId, error
+}
+```
+
+## 自定义代理配置文件 {#profiles}
+
+子代理映射到自定义代理配置文件 - 工作区中 `agents/<slug>.md` 处的 Markdown 文件，这些文件显示在 `@mention` 下拉列表中并用作委派目标。 [Workspace — Custom Agents](/docs/workspace#custom-agents) 拥有完整格式（frontmatter、`tools`、`delegate-default`、模型覆盖）。
+
+## 委托深度防护 {#depth-guard}
+
+子代理可以产生子代理，这是一种失控/成本风险：无限的委托链可能会无限期地散开。该框架在服务器端强制执行**委托深度**的硬上限，独立于任何工具级防护。
+
+顶级聊天深度为`0`。它生成的子代理深度为 `1`；该子代理可能会再次生成（深度 `2`）；会创建深度 `3` 子代理的生成被 **拒绝**。默认上限为 **2**。
+
+```an-diagram title="Delegation depth guard (default cap 2)" summary="Each level may spawn one deeper until the cap; a spawn past it is refused server-side."
+{
+  "html": "<div class=\"at-depth\"><div class=\"diagram-card ok\"><span class=\"diagram-pill\">depth 0</span><strong>Top-level chat</strong><small class=\"diagram-muted ok\">may spawn &darr;</small></div><div class=\"diagram-card ok\"><span class=\"diagram-pill\">depth 1</span><strong>Sub-agent</strong><small class=\"diagram-muted ok\">may spawn &darr;</small></div><div class=\"diagram-card warn\"><span class=\"diagram-pill warn\">depth 2</span><strong>Sub-agent's sub-agent</strong><small class=\"diagram-muted\">at the cap &mdash; may NOT spawn</small></div><div class=\"diagram-card\"><span class=\"diagram-pill warn\">depth 3</span><strong>Refused</strong><small class=\"diagram-muted\">server-side error</small></div></div>",
+  "css": ".at-depth{display:flex;flex-direction:column;gap:8px}.at-depth .diagram-card{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.at-depth .rung-1,.at-depth .diagram-card:nth-child(2){margin-inline-start:24px}.at-depth .diagram-card:nth-child(3){margin-inline-start:48px}.at-depth .diagram-card:nth-child(4){margin-inline-start:72px}"
+}
+```
+
+执行是环境性的：每个子代理在记录其自身深度的 `AsyncLocalStorage` 内运行，因此从该运行传递到达的任何 `spawnTask` 都会读取其父代的深度，并在达到上限后拒绝 - 即使 `agent-teams` 工具被交给不应该拥有它的子代理。该决定被公开为纯粹的、可单元测试的 `evaluateSubagentDepth(parentDepth)`。被拒绝的生成会返回一个明确的错误：_“已达到委派深度限制（最大 N）；无法生成另一个子代理。”_
+
+### 配置上限 {#depth-guard-config}
+
+使用 `AGENT_NATIVE_MAX_SUBAGENT_DEPTH` 覆盖部署时的默认设置：
+
+| 值           | 效果                                                                                                |
+| ------------ | --------------------------------------------------------------------------------------------------- |
+| _（未设置）_ | `2`的默认上限。                                                                                     |
+| `0`          | **不能生成任何子代理** - 顶级代理完成所有工作。                                                     |
+| `1`…`16`     | 这么多级别的委派。                                                                                  |
+| 无效/`>16`   | 非整数/负/NaN值回退到`2`； `16` 以上的任何内容都会被固定到 `16`，因此拼写错误永远不会禁用防护装置。 |
+
+```bash
+AGENT_NATIVE_MAX_SUBAGENT_DEPTH=1   # sub-agents allowed, but they can't sub-delegate
+```
+
+当子代理达到或低于上限时，框架会在其运行时上下文中注入一行，告诉它它的位置有多深以及是否可以进一步委托，以便模型适当地花费其预算。
+
+## 下一步是什么
+
+- [**Workspace — Custom Agents**](/docs/workspace#custom-agents) — 配置文件格式
+- [**A2A Protocol**](/docs/a2a-protocol) - 当“子代理”完全位于不同的应用程序中时
+- [**Actions**](/docs/actions) — 子代理调用的工具

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

@@ -0,0 +1,161 @@
+---
+title: "公共代理网络"
+description: "使公共路线可爬行、可读、可引用，并可选择由代理调用 - robots.txt、llms.txt、markdown 镜像、JSON-LD 和公共 MCP 表面。"
+---
+
+# 公共代理网络
+
+公共代理网络使公共 Agent-Native 路由易于代理抓取、阅读、引用和调用。目标不是公开每个应用程序端点。目标是为已经公开的页面发布一个干净的公共界面，同时将私有数据和工具访问保留在显式控制之下。
+
+文档站点是参考实现。今天发货：
+
+- `/robots.txt` 的爬虫策略默认允许检索但不允许训练。
+- 当源文件公开它时，`/sitemap.xml` 具有绝对规范的 URL 和 `lastmod`。
+- `/llms.txt` 和 `/llms-full.txt` 用于代理友好的内容发现。
+- Markdown 镜像，例如 `/docs/getting-started.md`。
+- 生产构建后公共文档页面的 `Accept: text/markdown` 响应。
+- JSON-LD 用于基础组织、网站和页面元数据。
+- 审核 CLI (`npx @agent-native/core@latest audit-agent-web`)，检查上述所有内容。
+
+设置 `publicMcp: true` 还会将选择加入的 actions 公开为公共 MCP 端点，允许外部代理直接调用它们（请参阅 [MCP Protocol](/docs/mcp-protocol)）。
+
+```an-diagram title="What a public route publishes" summary="A public route fans out into agent-friendly representations. Reading the route is separate from calling tools — tool access stays opt-in."
+{
+  "html": "<div class=\"diagram-web\"><div class=\"diagram-box\" data-rough>Public route<br><small class=\"diagram-muted\">derived from route access settings</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-grid\"><span class=\"diagram-pill\">robots.txt</span><span class=\"diagram-pill\">sitemap.xml</span><span class=\"diagram-pill\">llms.txt</span><span class=\"diagram-pill\">.md mirror</span><span class=\"diagram-pill\">JSON-LD</span><span class=\"diagram-pill\">text/markdown</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col gate\"><span class=\"diagram-pill warn\">Tools stay private</span><small class=\"diagram-muted\">publicMcp + publicAgent.expose required</small></div></div>",
+  "css": ".diagram-web{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-web .diagram-arrow{font-size:22px;line-height:1}.diagram-web .diagram-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:8px}.diagram-web .gate{display:flex;flex-direction:column;gap:4px;align-items:flex-start}"
+}
+```
+
+## 配置 {#config}
+
+在现有工作区应用配置下添加 `agentWeb`（在应用的 `package.json` 中的 `agent-native` 键下 — 或等效的 `workspace.agentWeb`、`agentWeb` 或 `root.agentWeb`）。公共路由列表仍然来源于应用程序的路由访问设置； `agentWeb` 控制公共表面如何呈现给代理。
+
+```json
+{
+  "agent-native": {
+    "workspaceApp": {
+      "audience": "public",
+      "protectedPaths": ["/admin/*"],
+      "agentWeb": {
+        "discoverable": true,
+        "markdownTwins": true,
+        "llmsTxt": true,
+        "jsonLd": true,
+        "publicAgentCard": true,
+        "publicMcp": false,
+        "crawlerPolicy": "discoverable-no-training",
+        "crawlers": {
+          "training": "disallow",
+          "search": "allow",
+          "userTriggered": "allow",
+          "codingAgents": "allow",
+          "autonomousAgents": "allow"
+        }
+      }
+    }
+  }
+}
+```
+
+对于大多数应用程序，请保留默认值。如果应用有公共路由，则默认开启`discoverable`。默认的爬虫策略是“可发现，不可训练”：允许搜索、用户触发检索、编码代理、自主浏览代理；不允许训练爬虫。
+
+## 路由真相来源 {#route-source}
+
+代理 Web 发现遵循路由访问模型：
+
+- 公共应用程序公开除 `protectedPaths` 之外的所有路线。
+- 内部应用仅公开 `publicPaths`。
+- 代理可以读取公共共享和表单页面。
+- 提交的私人数据、经过身份验证的仪表板和用户/组织状态永远不会仅仅因为附近的页面是公开的而包含在内。
+
+这使混合应用程序保持自然。表单应用程序可以公开公共表单页面并保持提交的私密性。内容应用程序可以公开已发布的帖子并保持编辑者的私密性。文档网站可以公开除管理工具之外的所有内容。
+
+## 公共页面不是公共工具 {#public-tools}
+
+公共页面访问和公共工具访问是分开的。路线仅公开意味着代理可以将该路线读取为 HTML、Markdown、站点地图条目、llms 条目和结构化数据。
+
+```an-callout
+{
+  "tone": "warning",
+  "body": "**A public page is not a public tool.** Making a route crawlable never exposes an action. Tool access requires an explicit `publicAgent.expose` opt-in on the action *and* `publicMcp: true` on the app."
+}
+```
+
+要通过公共代理协议公开操作，该操作必须选择加入：
+
+```an-annotated-code title="Opting one safe action onto the public surface"
+{
+  "filename": "actions/search-docs.ts",
+  "language": "ts",
+  "code": "export default defineAction({\n  description: \"Search published docs\",\n  readOnly: true,\n  publicAgent: {\n    expose: true,\n    readOnly: true,\n    requiresAuth: false,\n    isConsequential: false,\n    title: \"Search published docs\",\n  },\n  run: async (args) => {\n    // ...\n  },\n});",
+  "annotations": [
+    { "lines": "4", "label": "Explicit opt-in", "note": "Without `publicAgent.expose === true`, the action never appears on any public agent surface — no matter how public its routes are." },
+    { "lines": "5-7", "label": "Self-describe safety", "note": "Mark it read-only, declare whether it needs auth, and flag whether it is consequential. Public MCP excludes consequential/write actions unless policy explicitly allows them." }
+  ]
+}
+```
+
+`agentWeb.publicMcp` 默认情况下保持 `false`。启用公共 MCP 时，服务器应仅公开 actions 和 `publicAgent.expose === true`，并且仍应排除后续或写入 actions，除非操作和身份验证策略明确允许它们。
+
+## 构建时文件 {#build-time}
+
+`@agent-native/core/agent-web` 中的框架实用程序从一页列表生成通用文件：
+
+```ts
+import {
+  buildAgentWebStaticFiles,
+  normalizeAgentWebConfig,
+} from "@agent-native/core/agent-web";
+
+const config = normalizeAgentWebConfig(
+  { crawlerPolicy: "discoverable-no-training" },
+  { hasPublicRoutes: true },
+);
+
+const files = buildAgentWebStaticFiles({
+  siteName: "My Agent-Native App",
+  siteUrl: "https://example.com",
+  description: "Public docs for my app.",
+  config,
+  pages: [
+    {
+      path: "/docs",
+      title: "Docs",
+      description: "Start here.",
+      markdown: "# Docs\n\nStart here.\n",
+      markdownPath: "/docs/getting-started.md",
+      lastmod: new Date(),
+    },
+  ],
+});
+```
+
+Vite 应用可以在生产构建期间使用 `@agent-native/core/vite` 中的 `createAgentWebVitePlugin` 将这些文件写入 `public`、`dist`、`dist/client`、`dist/server/public` 或 `build/client`。
+
+## 审核网站 {#audit}
+
+对已部署站点或本地生产服务器使用 CLI 审核：
+
+```bash
+npx @agent-native/core@latest audit-agent-web --url https://www.agent-native.com
+```
+
+审核检查：
+
+- SSR-可见HTML。
+- 规范 URL。
+- JSON-LD。
+- `robots.txt` 政策和绝对站点地图 URL。
+- 绝对站点地图条目。
+- `/llms.txt` 和 `/llms-full.txt`。
+- Markdown 镜子。
+- `Accept: text/markdown`.
+- 公共代理检索用户代理不会出现意外的 401/403 阻塞。
+
+如果缺少所需的公共表面，审核将以非零值退出。
+
+## 下一步是什么
+
+- [**Actions**](/docs/actions) — 如何选择 actions 加入公共代理协议
+- [**MCP Protocol**](/docs/mcp-protocol) — `publicMcp: true` 启用的 MCP 表面
+- [**Deployment**](/docs/deployment) - 这些静态文件在构建期间写入的位置

package/docs/content/locales/zh-CN/audit-log.md

@@ -0,0 +1,111 @@
+---
+title: "审核日志"
+description: "持久的、仅附加的记录，记录谁更改了哪些应用数据、何时以及是您还是代理 - 在操作接缝处自动捕获。"
+---
+
+# 审核日志
+
+每个代理本机应用程序都会获得开箱即用的审核日志：一个持久的、完整的、访问范围的、仅附加的记录，记录**谁改变了哪些应用程序数据、何时、从哪里以及（何时是代理）在哪个运行中。** 捕获在操作接缝处自动进行；您无需为其编写任何代码。
+
+由于代理可以代表您更改数据，因此审核日志在这里回答的标题问题不仅仅是“谁编辑了此记录”，而是 **“是我还是代理，以及哪个轮次导致了它？”** 框架中没有其他系统可以回答这个问题。
+
+## 审计与可观察性与跟踪 {#which}
+
+三个系统出于三个不同的原因记录“发生了什么”。根据您要问的问题进行选择：
+
+| 系统                                     | 它回答的问题                           | 保真度                 | 观众                   |
+| ---------------------------------------- | -------------------------------------- | ---------------------- | ---------------------- |
+| **审核日志**（本页）                     | “谁更改了此记录，何时更改，是代理吗？” | **完整、耐用、有范围** | 用户、管理员、代理本身 |
+| **[Observability](/docs/observability)** | “代理为什么要这样做，花费了多少？”     | 采样跨度遥测           | 开发人员               |
+| **[Tracking](/docs/tracking)**           | “人们如何使用该产品？”                 | 即发即忘外部 SaaS      | PM/增长                |
+
+采样或发送给分析提供商的审核日志是无用的 - 重点是它是完整的、本地的且可查询的。所以它是它自己的子系统，而不是其他两个的模式。
+
+## 自动捕获的内容 {#captured}
+
+当任何 **mutating** 操作运行时（任何不是只读 `GET` 的操作），框架都会向 `agent_audit_log` 追加一行：
+
+- **操作** — 操作名称（例如 `delete-recording`）。
+- **演员** - `agent`、`human` 或 `system`，加上演员的电子邮件 - 填充**即使是代理呼叫**，因此您会得到“代理，代表 alice@，...”。
+- **运行链接** - 触发调用（工具调用）的代理 `threadId` / `turnId`，因此突变可以追溯到确切的代理回合。
+- **Surface** — `tool`（代理）、`frontend`、`http`、`cli`、`mcp` 或 `a2a`。
+- **结果** — `success`、`error`（带有错误代码）或 `denied`（被人工审批门阻止）。
+- **输入** — 调用参数，具有凭证形状的值 [redacted](#privacy)。
+- **目标和所有者** — 操作更改的资源，用于 [scope reads](#reading)。
+
+无需接线 - 捕获透明地连接到 `defineAction`。只读的actions会被跳过，并且默认会跳过一些高频框架actions（app-statesync、context-xray、navigation）以避免日志泛滥。
+
+## 声明操作更改了什么 {#target}
+
+默认情况下，事件的范围仅限于 **参与者** - 您可以看到自己的更改以及代理代表您所做的更改。要对*shared*资源进行更改也出现在**所有者的**跟踪中，并按资源标记事件，请声明`target`：
+
+```ts
+export default defineAction({
+  description: "Delete a recording.",
+  schema: z.object({ id: z.string() }),
+  audit: {
+    target: (args, result) => ({
+      type: "recording",
+      id: args.id,
+      // Optional — defaults to the actor. Set when editing someone else's resource.
+      ownerEmail: result?.ownerEmail,
+      visibility: "org",
+    }),
+    summary: (args) => `Deleted recording ${args.id}`,
+  },
+  run: async (args, ctx) => {
+    /* ...delete... */
+  },
+});
+```
+
+`audit` 中的所有内容都是可选的。最小有用的添加是 `target: () => ({ type, id })`。
+
+### 调整捕获 {#tuning}
+
+| 选项                 | 效果                                         |
+| -------------------- | -------------------------------------------- |
+| `audit.target`       | 使用向其所有者读取的资源和范围来标记事件。   |
+| `audit.summary`      | 该事件的人类可读的简短行。                   |
+| `audit.onRead`       | 审核敏感的**读取**（秘密访问、批量导出）。   |
+| `audit.enabled`      | `true` 强制捕获； `false` 选择排除噪声突变。 |
+| `audit.recordInputs` | `false` 跳过捕获（已编辑的）参数。           |
+
+## 阅读踪迹 {#reading}
+
+每个应用程序中的代理**和**前端都可以使用两个读取的actions，调用者的范围在SQL中 - 它们永远不会返回其他租户的行：
+
+- **`list-audit-events`** — 按 `targetType` / `targetId`、`actorKind` (`agent` | `human` | `system`)、`status`、`threadId` / `turnId`、`action` 过滤， `sinceMs`、`limit`。
+- **`get-audit-event`** — 按 id 的一个事件，包括其经过编辑的输入负载。
+
+通过使用 `useActionQuery` 从 UI 调用 `list-audit-events` 来构建活动源或“谁更改了此”行 - 切勿手写对审核表的提取：
+
+```tsx
+import { useActionQuery } from "@agent-native/core/client";
+
+const { data } = useActionQuery("list-audit-events", {
+  targetType: "recording",
+  targetId: recordingId,
+});
+// data.events → [{ action, actorKind, actorEmail, turnId, status, summary, createdAt }, …]
+```
+
+代理可以调用​​相同的操作 - 询问它“你对此录音做了什么更改？”它会从踪迹中回答。
+
+## 隐私和保留 {#privacy}
+
+- **编辑** - 在存储任何输入之前，凭证形状的密钥和值（令牌、秘密、密码、承载字符串）将被剥离，并截断超大的有效负载。审核日志永远不会成为秘密的辅助存储。也不要让 `summary` 文本包含敏感数据。
+- **仅追加** — 审核行没有更新或删除操作。唯一的删除是保留清除，这使得日志作为审计跟踪值得信赖。
+- **租户隔离** — 读取范围仅限于调用者的身份和组织；没有身份，没有任何匹配。
+
+通过环境配置：
+
+- `AGENT_NATIVE_AUDIT_RETENTION_DAYS` — 行保留多长时间（默认 `365`；`0` = 永远保留）。
+- `AGENT_NATIVE_AUDIT_ENABLED=false` — 全局终止开关。
+
+## 下一步是什么
+
+- [**Actions**](/docs/actions) — 捕获发生的 `defineAction` 接缝
+- [**Human-in-the-Loop Approvals**](/docs/human-approval) — 门控 actions，记录为 `denied`
+- [**Security & Data Scoping**](/docs/security) — 所有权模型审核读取重用
+- [**Observability**](/docs/observability) - 代理运行的遥测（另一个“发生了什么”）