@agent-native/core 0.79.1 → 0.79.5

package/docs/content/locales/zh-TW/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="協調員和專家" summary="主聊天委托給在自己的線程中執行並作為內聯芯片報告的子代理。"
+{
+  "html": "<div class=\"at-orc\"><div class=\"diagram-card main\"><span class=\"diagram-pill accent\">主聊天</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\">程式碼評審<br><small class=\"diagram-muted\">own thread &amp; prompt</small></div><div class=\"diagram-box\">BigQuery 分析<br><small class=\"diagram-muted\">own tools</small></div><div class=\"diagram-box\">語音郵件<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="spawnTask() 的作用" summary="每個spawn都會建立一個線程，將狀態儲存到SQL，並將芯片事件流式傳輸直至完成。"
+{
+  "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="委派深度保護（預設上限 2）" summary="每一層都可能產生更深的一層，直到達到上限；超過它的生成將被伺服器端拒絕。"
+{
+  "html": "<div class=\"at-depth\"><div class=\"diagram-card ok\"><span class=\"diagram-pill\">depth 0</span><strong>頂層聊天</strong><small class=\"diagram-muted ok\">may spawn &darr;</small></div><div class=\"diagram-card ok\"><span class=\"diagram-pill\">depth 1</span><strong>子代理</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>子代理'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   # 允許分代理，但不能分代理
+```
+
+當子代理達到或低於上限時，框架會在其執行時上下文中注入一行，告訴它它的位置有多深以及是否可以進一步委托，以便模型適當地花費其預算。
+
+## 下一步是什么
+
+- [**Workspace — Custom Agents**](/docs/workspace#custom-agents) — 設定檔案格式
+- [**A2A Protocol**](/docs/a2a-protocol) - 當“子代理”完全位於不同的應用程式中時
+- [**Actions**](/docs/actions) — 子代理調用的工具

package/docs/content/locales/zh-TW/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="公開路由發布什么" summary="一條公開路線呈扇形展開，形成對代理人友好的代表。讀取路線與調用工具是分開的——工具存取保持選取加入。"
+{
+  "html": "<div class=\"diagram-web\"><div class=\"diagram-box\" data-rough>公開路由<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\">工具保持私人</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="在公開表面上選取一項安全行動"
+{
+  "filename": "actions/search-docs.ts",
+  "language": "ts",
+  "code": "export default defineAction({\n  description: \"搜尋 published docs\",\n  readOnly: true,\n  publicAgent: {\n    expose: true,\n    readOnly: true,\n    requiresAuth: false,\n    isConsequential: false,\n    title: \"搜尋 published docs\",\n  },\n  run: async (args) => {\n    // ...\n  },\n});",
+  "annotations": [
+    { "lines": "4", "label": "明確選取加入", "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": "自我描述安全性", "note": "將其標記為唯讀，聲明它是否需要驗證，並標記它是否是重要的。除非策略明確允許，否則公開 MCP 排除 consequential/write 操作。" }
+  ]
+}
+```
+
+`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: "# 檔案\n\n從這裡開始。\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-TW/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) - 代理執行的遙測（另一個“發生了什么”）