@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/zh-CN/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="The native render path" summary="An action returns JSON; the runtime matches an explicit widget discriminant or chatUI.renderer; AssistantChat mounts a real React component. No iframe, no HTML execution."
+{
+  "html": "<div class=\"diagram-render\"><div class=\"diagram-node\">Action runs<br><small class=\"diagram-muted\">returns structured 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\">mounts a 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": "The renderer only takes over when the action declares `chatUI` **or** the result carries an explicit known `widget` discriminant. It never shape-infers arbitrary objects and never executes HTML or JavaScript from tool results — so a native widget can't become an injection vector."
+}
+```
+
+当用户请求图表、图形、表格、趋势或精简报告时，应用代理
+应该更喜欢声明这些本机渲染器之一的操作。决赛
+辅助文本应保持简短并让小部件携带数据；请勿复制
+除非用户明确要求输入文本，否则将相同的行放入 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 runtime keeps the Agent-Native chat shell" summary="Your external agent streams normalized events through a connector; Agent-Native keeps the composer, transcript, tool cards, approvals, and native widgets."
+{
+  "html": "<div class=\"diagram-byo\"><div class=\"diagram-box\" data-rough>Your agent<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\">normalized message-* / tool-* events</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/corpus/core/docs/content/locales/zh-CN/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="One call, many destinations" summary="notify() always writes the owner-scoped inbox row, fans out to every registered channel in parallel (best-effort), then emits notification.sent on the event bus."
+{
+  "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="Channels and severity" summary="inbox is always on; webhook needs an env var; custom channels register at startup. Severity drives badge styling and is passed through to every channel."
+{
+  "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>Severity drives the badge</strong><div class=\"sev-row\"><span class=\"diagram-pill\">info</span><span class=\"diagram-muted\">confirmations, 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="List notifications" summary="The route behind listNotifications() — scoped to the authenticated session's email."
+{
+  "method": "GET",
+  "path": "/_agent-native/notifications?unread=true&limit=50",
+  "summary": "List recent notifications for the current user",
+  "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) — 启动时注册自定义通道