@agent-native/core 0.79.1 → 0.79.5

package/docs/content/locales/zh-TW/native-chat-ui.md

@@ -0,0 +1,321 @@
+---
+title: "原生聊天 UI"
+description: "操作聲明的本機聊天渲染器、可重用的 DataTable/DataChart 輸出，以及 BYO 代理執行時應如何連線到 Agent-Native 聊天。"
+---
+
+# 原生聊天 UI
+
+本機聊天 UI 是第一方代理輸出的應用內渲染路徑。一個
+操作返回結構化JSON，聊天執行時識別顯式小部件
+判別式，`<AssistantChat>`在
+對話。您不會為
+正常的應用聊天。
+
+當使用者應該檢查代理所在位置的輸出時，使用本機聊天 UI
+已經講過：查詢結果、回應見解、設定摘要，
+批準/拒絕控制，或應用程式視圖的連結。使用[MCP Apps](/docs/mcp-apps)
+當外部主機（例如 Claude、ChatGPT、Copilot 或 Cursor）應該渲染時
+來自您的應用的內聯路由。
+
+```an-diagram title="原生渲染路徑" summary="操作返回 JSON；執行時匹配顯式小部件判別式或 chatUI.renderer； AssistantChat 安裝真實的 React 元件。沒有 iframe，沒有 HTML 執行。"
+{
+  "html": "<div class=\"diagram-render\"><div class=\"diagram-node\">Action 執行<br><small class=\"diagram-muted\">返回結構化 JSON</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">Match</span><small class=\"diagram-muted\">explicit widget &middot; chatUI.renderer</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">&lt;AssistantChat&gt;<br><small class=\"diagram-muted\">掛載 React widget</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card col\"><div class=\"diagram-pill ok\">DataTable</div><div class=\"diagram-pill ok\">DataChart</div><div class=\"diagram-pill ok\">DataInsights</div></div></div>",
+  "css": ".diagram-render{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-render .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px}.diagram-render .col{display:flex;flex-direction:column;gap:6px;padding:12px}.diagram-render .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## 動作聲明的小部件 {#action-declared-widgets}
+
+本機路徑有兩個顯式部分：
+
+- `outputSchema` 驗證操作的回應形狀。
+- `chatUI.renderer` 為驗證結果選取原生 React 渲染器。
+
+內置資料渲染器使用普通的 JSON 結果和 `widget` 加上
+匹配有效負載：
+
+| 小部件            | 所需的有效負載              | 渲染為                        |
+| ----------------- | --------------------------- | ----------------------------- |
+| `"data-table"`    | `table`                     | 原生的、可重用的資料表        |
+| `"data-chart"`    | `chartSeries`               | 原生條形圖、折線圖或面積圖    |
+| `"data-insights"` | `table` 和/或 `chartSeries` | 帶有圖表/表格輸出的組合洞察卡 |
+
+伺服器 actions 應從
+`@agent-native/core/data-widgets`；用戶端程式碼可以從
+`@agent-native/core/client/chat` 或 `@agent-native/core/client`。
+
+```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: "Analyze form responses.",
+  readOnly: true,
+  outputSchema: dataInsightsWidgetResultSchema,
+  chatUI: {
+    renderer: ACTION_CHAT_UI_DATA_INSIGHTS_RENDERER,
+    title: "Response insights",
+  },
+  run: async () =>
+    createDataInsightsWidgetResult({
+      title: "Response insights",
+      display: {
+        title: "42 responses",
+        description: "Completion rate rose this week.",
+        primaryAction: {
+          label: "Open response insights",
+          href: "/response-insights",
+        },
+      },
+      chartSeries: {
+        type: "bar",
+        title: "Responses by day",
+        xKey: "day",
+        series: [{ key: "responses", label: "Responses" }],
+        data: [
+          { day: "Mon", responses: 8 },
+          { day: "Tue", responses: 13 },
+        ],
+      },
+      table: {
+        title: "Top answers",
+        columns: [
+          { key: "answer", label: "Answer" },
+          { key: "count", label: "Count", align: "right" },
+        ],
+        rows: [
+          { answer: "Yes", count: 31 },
+          { answer: "No", count: 11 },
+        ],
+        totalRows: 2,
+      },
+    }),
+});
+```
+
+```an-callout
+{
+  "tone": "success",
+  "body": "僅當操作聲明 `chatUI`**或**結果攜帶顯式已知的 `widget` 判別式時，渲染器才會接管。它從不形​​狀推斷任意物件，也從不從工具結果執行 HTML 或 JavaScript - 因此本機小部件不能成為注入向量。"
+}
+```
+
+當使用者請求圖表、圖形、表格、趨勢或精簡報告時，應用代理
+應該更喜歡聲明這些本機渲染器之一的操作。決賽
+輔助文本應保持簡短並讓小部件攜帶資料；請勿複製
+除非使用者明確要求輸入文本，否則將相同的行放入 Markdown 表中
+匯出。
+
+當不存在域操作但代理已檢索緊湊時，
+真實的資料，它可以通過以下方式調用框架`render-data-widget`操作
+相同的 `data-table`、`data-chart` 或 `data-insights` JSON 形狀。僅此操作
+驗證並渲染小部件；它不是資料來源，不得使用
+發明預留位置指標。
+
+## 資料表輸出 {#data-table}
+
+`table` 故意簡單化，以便列出、SQL、分析和設定 actions 可以
+重複使用它：
+
+```ts
+{
+  title?: string;
+  columns: Array<{ key: string; label: string; align?: "left" | "right" }>;
+  rows: Array<Record<string, unknown>>;
+  totalRows?: number;
+  sampledRows?: number;
+  truncated?: boolean;
+}
+```
+
+更喜歡穩定的列鍵和 JSON 安全的行值。使用`totalRows`，
+當操作顯示較大切片時為 `sampledRows` 和 `truncated`
+結果集。
+
+## 資料圖表輸出 {#data-chart}
+
+`chartSeries` 支持座席答案中使用的常見圖表形狀，無需
+要求每個範本提供自己的聊天渲染器：
+
+```ts
+{
+  type: "bar" | "line" | "area";
+  title?: string;
+  xKey: string;
+  series: Array<{ key: string; label: string; color?: string }>;
+  data: Array<Record<string, unknown>>;
+  sampled?: boolean;
+}
+```
+
+保持圖表資料緊湊。對於大型資料集，在操作和連結中聚合
+到包含 `display.primaryAction` 或操作 `link` 元資料的完整應用視圖。
+
+## 本機小部件與 MCP 應用程式 {#native-vs-mcp-apps}
+
+本機聊天小部件和 MCP 應用程式是互補的：
+
+- **本機小部件**用於應用程式自己的聊天執行時。動作結果為
+  JSON，框架渲染內置的React小部件。
+- **MCP 應用程式**適用於外部主機。該操作聲明 `mcpApp` 並且通常
+  `link`，並且主機在支持時內聯渲染真實的應用程式路由。
+- **深層連結**仍然是通用的後備方案。使用操作 `link` 或
+  `display.primaryAction`、CLI 用戶端、較舊的 MCP 主機和純文本紀錄
+  讀者可以開啟完整的應用視圖。
+
+當本機小部件負載和 MCP 應用元資料都存在時，應用內
+聊天更喜歡本機小部件。外部主機使用 MCP Apps 資源或
+深層連結回退。
+
+## 自訂原生渲染器 {#custom-native-renderers}
+
+通過精確的渲染器 ID 註冊特定於產品的元件，然後聲明該 ID
+關於行動：
+
+```tsx
+import { registerActionChatRenderer } from "@agent-native/core/client/chat";
+
+registerActionChatRenderer({
+  id: "crm.deal-card",
+  renderer: "crm.deal-card",
+  Component: ({ context }) => <DealCard result={context.resultJson} />,
+});
+```
+
+```ts
+export default defineAction({
+  description: "Show a deal card.",
+  outputSchema: dealCardSchema,
+  chatUI: { renderer: "crm.deal-card" },
+  run: async () => ({ dealId: "deal_123", amount: 42000 }),
+});
+```
+
+將此用於第一方應用程式 UI。在`mcpApp`中保留跨主機iframe UI，並保留
+在聊天中鍵入讀取 actions 而不是原始 SQL 後執行任意查詢。
+
+## BYO 代理執行時 {#byo-agent-runtimes}
+
+`AgentChatRuntime` 是聊天 shell 的自帶代理合約，並且
+本節是其規範參考。它允許您在其他地方建置代理
+將標準化事件流式傳輸到 Agent-Native 的對話 UI 中，同時保持
+共用作曲家、腳本渲染、工具卡、批準、本機小部件，
+和週圍的應用程式布局。 [Drop-in Agent](/docs/drop-in-agent#custom-chat-ui)
+此處為執行時故事的教程點，以及 [Component API](/docs/components#agent-chat-ui)
+列出每個連線器和適配器及其匯入路徑；合約本身是
+如下所述。
+
+```an-diagram title="BYO 執行時保留 Agent-Native 聊天 shell" summary="您的外部代理通過連線器傳輸標準化事件； Agent-Native 保留作曲家、成績單、工具卡、批準和本機小部件。"
+{
+  "html": "<div class=\"diagram-byo\"><div class=\"diagram-box\" data-rough>你的代理<br><small class=\"diagram-muted\">OpenAI &middot; Claude &middot; Vercel AI &middot; AG-UI &middot; HTTP</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">connector</span><small class=\"diagram-muted\">標準化 message-* / tool-* 事件</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card col\"><div class=\"diagram-pill\">&lt;AssistantChat runtime=&hellip; /&gt;</div><small class=\"diagram-muted\">composer &middot; transcript &middot; tool cards</small><small class=\"diagram-muted\">approvals &middot; native widgets</small></div></div>",
+  "css": ".diagram-byo{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-byo .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px}.diagram-byo .col{display:flex;flex-direction:column;gap:6px;padding:14px}.diagram-byo .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+所有連線器均從 `@agent-native/core/client/chat` 匯出（以及根
+`@agent-native/core/client` 條目）。當您的代理使用通用 HTTP 執行時
+可以公開返回 SSE 或 NDJSON 執行時事件的 POST 端點：
+
+```tsx
+import {
+  AssistantChat,
+  createHttpAgentChatRuntime,
+} from "@agent-native/core/client/chat";
+
+const runtime = createHttpAgentChatRuntime({
+  id: "external:mastra",
+  label: "Mastra",
+  endpoint: "/api/mastra/chat",
+  headers: async () => ({
+    Authorization: `Bearer ${await getAgentToken()}`,
+  }),
+});
+
+export function SupportChat() {
+  return <AssistantChat runtime={runtime} threadId="support" />;
+}
+```
+
+如果您的端點已傳輸通用代理協議，請使用匹配的
+連線器並跳過編寫自訂對應器：
+
+```ts
+import {
+  createAgUiChatRuntime,
+  createClaudeAgentChatRuntime,
+  createOpenAIAgentsChatRuntime,
+  createOpenAIResponsesChatRuntime,
+  createVercelAiChatRuntime,
+} from "@agent-native/core/client/chat";
+
+const openAiAgentsRuntime = createOpenAIAgentsChatRuntime({
+  endpoint: "/api/openai-agents/chat",
+});
+
+const openAiResponsesRuntime = createOpenAIResponsesChatRuntime({
+  endpoint: "/api/openai-responses/chat",
+});
+
+const claudeAgentRuntime = createClaudeAgentChatRuntime({
+  endpoint: "/api/claude-agent/chat",
+});
+
+const vercelAiRuntime = createVercelAiChatRuntime({
+  endpoint: "/api/vercel-ai/chat",
+});
+
+const agUiRuntime = createAgUiChatRuntime({
+  endpoint: "/api/ag-ui/chat",
+});
+```
+
+端點可以直接傳輸標準化事件形狀：
+
+```text
+data: {"type":"message-start","message":{"id":"m1","role":"assistant","content":[]}}
+data: {"type":"message-delta","messageId":"m1","delta":{"type":"text","text":"Hello"}}
+data: {"type":"tool-start","toolCall":{"id":"t1","name":"query","input":{"q":"forms"}}}
+data: {"type":"tool-done","toolCallId":"t1","toolName":"query","status":"completed","resultText":"34 rows"}
+data: {"type":"done","reason":"complete"}
+```
+
+對於非常簡單的代理，接受 JSON 回應 `{ "text": "..." }` 並且
+轉換為單個助理訊息。對於更丰富的代理，請流式傳輸
+`message-*`, `tool-*`, `approval-request`, `status`, `artifact`, `file`,
+`usage`、`error` 和 `done` 事件。工具結果可以攜帶`mcpApp`或
+`chatUI` 元資料，因此操作聲明的本機小部件仍然會在沒有
+iframe。
+
+當您希望內置 Agent-Native 傳輸作為執行時物件時，請使用：
+
+```ts
+import { createAgentNativeChatRuntime } from "@agent-native/core/client/chat";
+
+const runtime = createAgentNativeChatRuntime({
+  threadId: "forms-chat",
+  mode: "act",
+});
+```
+
+僅在需要完整時才使用`<AssistantChat createAdapter={...} />`
+assist-ui 適配器控件。當您的產品時單獨使用`PromptComposer`
+擁有整個外部轉錄本並且只想要 Agent-Native 的作曲家
+欄位。
+
+OpenAI、AG-UI、Claude Agent SDK 和 Vercel AI SDK 流可以使用標準
+連線器助手。 ACP 保留編碼代理/編輯器互操作性，而不是
+最終使用者的通用應用程式聊天執行時。此處未聲明支持 A2UI；
+如果它成熟，它應該適應這個相同的顯式執行時/小部件契約。
+
+## 相關檔案 {#related-docs}
+
+- [Actions](/docs/actions) — 定義返回本機小部件資料的操作。
+- [Agent Surfaces](/docs/agent-surfaces) — 決定您是否需要無頭、聊天、邊車或完整應用程式。
+- [Drop-in Agent](/docs/drop-in-agent) — 安裝標準聊天執行時的教程。
+- [Component API](/docs/components) — 用於聊天層、執行時和工具渲染器的每次匯出 API 對應。
+- [MCP Apps](/docs/mcp-apps) — 用於外部 MCP 主機的內聯 UI。
+- [Key Concepts](/docs/key-concepts#protocols) — 協議狀態和定位。

package/docs/content/locales/zh-TW/notifications.md

@@ -0,0 +1,231 @@
+---
+title: "通知"
+description: "具有可插入通道的應用內通知 - 收件箱、Webhook 或自訂"
+---
+
+# 通知
+
+一個功能，多個目的地。從任何伺服器端程式碼（操作、自動化、外掛）調用 `notify()`，事件就會出現在使用者的應用內收件箱中，並分發到每個註冊的頻道。附帶一個響鈴下拉 UI 元件，主機範本將其放入其標頭中。
+
+通知是進入應用程式響鈴收件箱的單向警報（加上 Webhook 扇出）。要通過 Slack/電子郵件/Telegram/WhatsApp 與您的代理*交談*，請參閱 [Messaging](/docs/messaging)。
+
+```ts
+import { notify } from "@agent-native/core/notifications";
+
+await notify(
+  { severity: "info", title: "Booking confirmed", body: "Jane at 3pm" },
+  { owner: "steve@builder.io" },
+);
+```
+
+```an-diagram title="一個電話，多個目的地" summary="notify() 始終寫入所有者範圍的收件箱行，並行扇出到每個註冊通道（盡最大努力），然後在事件總線上發出 notification.sent。"
+{
+  "html": "<div class=\"diagram-notify\"><div class=\"diagram-node\">notify(input, { owner })<br><small class=\"diagram-muted\">any server code &middot; action, automation, plugin</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel fan\" data-rough><div class=\"fan-row\"><span class=\"diagram-pill accent\">inbox</span><div class=\"diagram-box\" data-rough>notifications table &rarr; bell UI<br><small class=\"diagram-muted\">always on &middot; owner-scoped</small></div></div><div class=\"fan-row\"><span class=\"diagram-pill\">webhook</span><div class=\"diagram-box\" data-rough>POST JSON to NOTIFICATIONS_WEBHOOK_URL<br><small class=\"diagram-muted\">best-effort</small></div></div><div class=\"fan-row\"><span class=\"diagram-pill\">custom</span><div class=\"diagram-box\" data-rough>registerNotificationChannel(...)<br><small class=\"diagram-muted\">best-effort &middot; runs in parallel</small></div></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill ok\">notification.sent</span><small class=\"diagram-muted\">event bus &middot; automations can chain</small></div></div>",
+  "css": ".diagram-notify{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-notify .fan{display:flex;flex-direction:column;gap:10px;padding:14px}.diagram-notify .fan-row{display:flex;align-items:center;gap:10px}.diagram-notify .diagram-card{display:flex;flex-direction:column;gap:6px;padding:12px 14px}.diagram-notify .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## 嚴重性 {#severities}
+
+| 嚴重性     | 用於                     |
+| ---------- | ------------------------ |
+| `info`     | 確認、進度裡程碑、FYI    |
+| `warning`  | 使用者應該盡快檢視的內容 |
+| `critical` | 需要立即關注             |
+
+嚴重性驅動下拉列表中的徽章樣式，並傳遞到渠道，以便它們可以根據緊急情況進行分支。
+
+## 內置頻道 {#channels}
+
+| 頻道      | 交付                                | 需要                                               |
+| --------- | ----------------------------------- | -------------------------------------------------- |
+| `inbox`   | 持久化到`notifications`表；驅動鈴UI | 始終開啟 - 原語的一部分。                          |
+| `webhook` | POST JSON 到已設定的 URL            | `NOTIFICATIONS_WEBHOOK_URL` 環境變數在啟動時設定。 |
+
+Webhook 通道根據所有者的臨時 [secrets](/docs/security) 解析 URL 和 `NOTIFICATIONS_WEBHOOK_AUTH` 中的 `${keys.NAME}` 引用，因此原始值永遠不會進入代理的上下文。強制執行每鍵 URL 允許列表 - 自動化 `web-request` 工具使用相同的規則。
+
+```an-diagram title="渠道和嚴重性" summary="收件箱始終開啟； webhook 需要一個環境變數；自訂頻道在啟動時註冊。嚴重性驅動徽章樣式並傳遞到每個渠道。"
+{
+  "html": "<div class=\"diagram-channels\"><div class=\"diagram-panel col\" data-rough><strong>Channels</strong><div class=\"diagram-box\" data-rough>inbox<br><small class=\"diagram-muted\">always on &mdash; part of the primitive</small></div><div class=\"diagram-box\" data-rough>webhook<br><small class=\"diagram-muted\">needs NOTIFICATIONS_WEBHOOK_URL</small></div><div class=\"diagram-box\" data-rough>custom<br><small class=\"diagram-muted\">registerNotificationChannel()</small></div></div><div class=\"diagram-panel col\" data-rough><strong>嚴重程度決定徽章</strong><div class=\"sev-row\"><span class=\"diagram-pill\">info</span><span class=\"diagram-muted\">確認和 FYI</span></div><div class=\"sev-row\"><span class=\"diagram-pill warn\">warning</span><span class=\"diagram-muted\">look at soon</span></div><div class=\"sev-row\"><span class=\"diagram-pill accent\">critical</span><span class=\"diagram-muted\">needs immediate attention</span></div></div></div>",
+  "css": ".diagram-channels{display:flex;gap:16px;flex-wrap:wrap;align-items:flex-start}.diagram-channels .col{display:flex;flex-direction:column;gap:10px;padding:14px;min-width:240px}.diagram-channels .sev-row{display:flex;align-items:center;gap:10px}"
+}
+```
+
+## API {#api}
+
+### `notify(input, meta)` {#notify}
+
+發出通知。除非明確排除，否則始終保留在收件箱中；其他註冊通道會盡力並行執行。
+
+```ts
+await notify(
+  {
+    severity: "critical",
+    title: "Database offline",
+    body: "Primary dropped connections",
+    metadata: { runbookUrl: "https://runbooks/db-offline" },
+    channels: ["inbox", "webhook"], // optional allowlist; omit to run all
+  },
+  { owner: "ops@company.com" },
+);
+```
+
+`meta.owner` 是必需的 - 限制通知的範圍，以便只有使用者在鈴聲中看到它。
+
+### `registerNotificationChannel(channel)` {#register}
+
+從任何伺服器外掛註冊自訂通道。
+
+```ts
+import { registerNotificationChannel } from "@agent-native/core/notifications";
+
+registerNotificationChannel({
+  name: "slack-ops",
+  async deliver(input, meta) {
+    await fetch(process.env.OPS_SLACK_WEBHOOK!, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        text: `*${input.severity.toUpperCase()}* — ${input.title}\n${input.body ?? ""}`,
+        owner: meta.owner,
+      }),
+    });
+  },
+});
+```
+
+頻道名稱是唯一的 - 重新註冊會替換之前的頻道。 `deliver()` 是盡力而為；拋出錯誤會紀錄錯誤，但不會阻止其他通道或收件箱行。
+
+### 列出和閱讀 {#read}
+
+```ts
+import {
+  listNotifications,
+  countUnread,
+  markNotificationRead,
+  markAllNotificationsRead,
+  deleteNotification,
+} from "@agent-native/core/notifications";
+
+const rows = await listNotifications("steve@builder.io", {
+  unreadOnly: true,
+  limit: 50,
+});
+const unread = await countUnread("steve@builder.io");
+await markNotificationRead(rows[0].id, "steve@builder.io");
+await markAllNotificationsRead("steve@builder.io");
+await deleteNotification(rows[0].id, "steve@builder.io");
+```
+
+每個函數都是所有者範圍的 - 沒有跨使用者讀取，沒有跨使用者寫入。
+
+## NotificationChannel 介面 {#channel-interface}
+
+```ts
+interface NotificationChannel {
+  name: string;
+  deliver(
+    input: NotificationInput,
+    meta: NotificationMeta,
+  ): void | Promise<void>;
+}
+
+interface NotificationInput {
+  severity: "info" | "warning" | "critical";
+  title: string;
+  body?: string;
+  metadata?: Record<string, unknown>;
+  channels?: string[];
+}
+
+interface NotificationMeta {
+  owner: string;
+}
+```
+
+## HTTP API {#http}
+
+通過 core-routes 外掛安裝在 `/_agent-native/notifications/*`。所有路由的範圍僅限於經過驗證的工作階段的電子郵件。
+
+| 方法     | 路徑                                                |
+| -------- | --------------------------------------------------- |
+| `GET`    | `/_agent-native/notifications?unread=true&limit=50` |
+| `GET`    | `/_agent-native/notifications/count`                |
+| `POST`   | `/_agent-native/notifications/:id/read`             |
+| `POST`   | `/_agent-native/notifications/read-all`             |
+| `DELETE` | `/_agent-native/notifications/:id`                  |
+
+```an-api title="列出通知" summary="The route behind listNotifications() — scoped to the authenticated session's email."
+{
+  "method": "GET",
+  "path": "/_agent-native/notifications?unread=true&limit=50",
+  "summary": "列出目前使用者的最近通知",
+  "auth": "Authenticated session; results are scoped to the session's email.",
+  "params": [
+    { "name": "unread", "in": "query", "type": "boolean", "required": false, "description": "When true, returns only unread notifications." },
+    { "name": "limit", "in": "query", "type": "number", "required": false, "description": "Max rows to return." }
+  ],
+  "responses": [
+    { "status": "200", "description": "Owner-scoped notification rows, newest first." }
+  ]
+}
+```
+
+## UI元件 {#ui}
+
+```tsx
+import { NotificationsBell } from "@agent-native/core/client/notifications";
+
+export function HeaderBar() {
+  return (
+    <header className="flex items-center gap-2">
+      {/* … */}
+      <NotificationsBell browserNotifications />
+    </header>
+  );
+}
+```
+
+帶有未讀徽章的響鈴圖標。點選可開啟最近通知的下拉列表。使用 shadcn 語義標記，適應主機範本的淺色/深色主題。
+
+傳遞 `browserNotifications` 來為每個新的未讀專案觸發系統 `new Notification(...)` 快顯窗口 - 當使用者的分頁位於後台時很有用。下拉選單會呈現“啟用”提示，直到使用者授予權限；通過通知 `tag` 欄位防止每個 ID 重複。
+
+## 代理工具 {#agent-tools}
+
+每個範本中都會註冊一個 `manage-notifications` 工具。 `action`參數選取操作：
+
+| 行動   | 參數                                                                    | 目的                               |
+| ------ | ----------------------------------------------------------------------- | ---------------------------------- |
+| `send` | `severity`（必填）、`title`（必填）、`body`、`metadataJson`、`channels` | 向使用者的收件箱和註冊頻道發送通知 |
+| `list` | `unreadOnly`、`limit`（最多 200 個，預設 20 個）                        | 列出上下文的最近通知               |
+
+自動化（請參閱 [Automations](/docs/automations)）可以通過其主體中的 `action=send` 調用 `manage-notifications` - 這是將外部事件轉變為使用者可見警報的規範模式。
+
+## 事件總線 {#event-bus}
+
+每次成功交付都會在 [event bus](/docs/automations#event-bus) 上發出 `notification.sent`：
+
+```json
+{
+  "notificationId": "n-123",
+  "severity": "critical",
+  "title": "DB offline",
+  "body": "Primary dropped connections",
+  "deliveredChannels": ["inbox", "webhook"]
+}
+```
+
+自動化可以將其串聯起來——例如*“如果觸發重要通知，也會立即尋呼。”*
+
+## 它是如何工作的 {#internals}
+
+- **所有者範圍** — 每行都有一個 `owner` 列；每個查詢都會對其進行過濾；每個路由都使用經過驗證的工作階段的電子郵件。使用者永遠不會看到彼此的通知。
+- **輪詢整合** - 每個突變都會調用 `recordChange()`，因此使用 [`useDbSync`](/docs/client) 的範本會自動失效，無需任何額外的接線。
+- **盡力扇出** — 捕獲並紀錄通道錯誤；一個失敗的通道不會阻止其他通道或收件箱寫入。
+- **即發即忘** — `notify()` 在收件箱寫入完成後返回；自訂通道在後台執行。
+
+## 下一步是什么
+
+- [**Automations**](/docs/automations) — `notify()` 最常見的調用者
+- [**Security**](/docs/security) — 為 Webhook 通道提供支持的 `${keys.NAME}` 替代
+- [**Server plugins**](/docs/server) — 啟動時註冊自訂通道