@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/zh-CN/dispatch.md

@@ -0,0 +1,146 @@
+---
+title: "调度"
+description: "工作区控制平面：秘密库、集成中心、跨应用程序委托以及 Slack、电子邮件、Telegram、WhatsApp 的中央收件箱。"
+---
+
+# 调度
+
+Dispatch 是中央应用程序，位于工作区中所有其他应用程序的前面，负责处理机密、集成、消息传递和跨应用程序委派。它是**工作区控制平面** - 您的团队与之交谈的单一代理、实时的单一位置凭证以及决定哪个专业应用程序应处理给定请求的单一路由器。
+
+> **调度模板与 `@agent-native/dispatch` 包。** 此页面介绍调度应用程序/模板概念 - 它的作用以及您为什么需要它。 `@agent-native/dispatch` npm 包是单独发布的运行时，它将 Dispatch 模板的服务器逻辑（保管库、集成、目标、计划作业和跨应用程序委派）捆绑为扩展它的工作区的嵌入式包。对于脚手架应用程序本身（路线、屏幕、代理指南），请参阅 [Dispatch template](/docs/template-dispatch)。
+
+如果没有 Dispatch，多应用工作区中的每个应用最终都会重新实现相同的管道：自己的 Slack 机器人、自己的秘密存储、自己的计划作业、自己的工作区指令副本。旋转一把 API 钥匙会变成十次重新部署。添加一个新策略会变成十次复制粘贴。 Dispatch 将所有这些都集中在一个应用程序中，以便其他应用程序能够专注于自己的领域。
+
+```an-diagram title="Dispatch as the workspace control plane" summary="One inbox, one vault, one MCP gateway, and shared resources sit in front of the domain apps, which Dispatch reaches as A2A peers."
+{
+  "html": "<div class=\"dsp-hub\"><div class=\"diagram-node\">Users &amp; external agents<br><small class=\"diagram-muted\">Slack · email · Telegram · WhatsApp · MCP</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-panel dsp-control\" data-rough><span class=\"diagram-pill accent\">Dispatch &mdash; control plane</span><div class=\"dsp-caps\"><span class=\"diagram-pill\">Central inbox</span><span class=\"diagram-pill\">Secret vault</span><span class=\"diagram-pill\">Cross-app delegation</span><span class=\"diagram-pill\">MCP gateway</span><span class=\"diagram-pill\">Workspace resources</span></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"dsp-peers\"><div class=\"diagram-box\" data-rough>Mail</div><div class=\"diagram-box\" data-rough>Calendar</div><div class=\"diagram-box\" data-rough>Analytics</div></div><small class=\"diagram-muted\">domain apps &mdash; A2A peers</small></div>",
+  "css": ".dsp-hub{display:flex;flex-direction:column;align-items:center;gap:10px}.dsp-hub .dsp-control{display:flex;flex-direction:column;align-items:center;gap:10px;width:100%}.dsp-hub .dsp-caps{display:flex;gap:8px;flex-wrap:wrap;justify-content:center}.dsp-hub .dsp-peers{display:flex;gap:10px;flex-wrap:wrap;justify-content:center}"
+}
+```
+
+## 当您需要调度时 {#when}
+
+满足以下任一条件时进行调度：
+
+- 您正在运行 [multi-app workspace](/docs/multi-app-workspace) — 邮件、日历、分析、内容 — 并且您不希望每个应用有一个 Slack 机器人。
+- 您希望 **为“代理”提供一个收件箱**，以便用户通过 DM 发送单个机器人，然后由正确的专业应用程序接手幕后的工作。
+- 您拥有多个应用程序需要的**工作区范围的秘密**（Stripe 密钥、OpenAI 密钥、第三方 API 令牌），并且您需要一个保管库，而不是将值复制到每个 `.env` 中。
+- 您希望在敏感更改（保存的目标、策略编辑）之前有一个**运行时审批流程**，以便非管理员可以请求，而管理员可以在不部署代码的情况下退出。
+- 您需要工作区中的应用程序继承的**共享 skills、说明、代理配置文件和 MCP 服务器** - 更改一次，覆盖所有。
+
+如果您独立运行单个模板，则不需要 Dispatch — 每个模板都可以直接连接自己的消息传递集成。有关独立设置，请参阅 [Messaging](/docs/messaging)。
+
+## Dispatch 的作用 {#what-it-does}
+
+七种功能，全部位于其他应用程序使用的同一工作区数据库之上：
+
+| 能力            | 它给你什么                                                            | 设置                                                      |
+| --------------- | --------------------------------------------------------------------- | --------------------------------------------------------- |
+| **中央收件箱**  | Slack、电子邮件、Telegram、WhatsApp 均通过共享内存 + 工具到达一个代理 | **设置 → 消息传送** ([Messaging](/docs/messaging))        |
+| **秘密金库**    | 将每个凭证存储一次；在每个应用程序的一处轮换                          | **保管库** + 访问模式（所有应用程序或手动）               |
+| **跨应用委托**  | 通过 A2A 将请求路由到正确的专业应用并在线程内回复                     | 自动（[A2A](/docs/a2a-protocol)）                         |
+| **统一MCP网关** | 用于外部代理的一个 MCP 连接器可到达每个授权的工作区应用               | [External Agents](/docs/external-agents)                  |
+| **工作区资源**  | 作者 skills/说明/配置文件一次；应用程序在运行时继承它们               | **资源**（[Workspace](/docs/workspace#global-resources)） |
+| **梦想**        | 审查过去的运行/反馈并提出持久的改进建议供您批准                       | **梦想**选项卡                                            |
+| **审批流程**    | 控制内联管理审核背后的敏感运行时更改                                  | **调度审批政策**                                          |
+
+下面详细介绍了每项内容。
+
+### 中央收件箱
+
+Slack、电子邮件、Telegram 和 WhatsApp 都流入 Dispatch 的代理循环。在**设置 → 消息传送**中连接每个平台一次，每个渠道都会使用相同的内存和工具到达相同的代理。 Slack DM 和发送给 `agent@yourcompany.com` 的电子邮件最终会成为一个对话历史记录中的两个表面，而不是两个断开连接的机器人。请参阅 [Messaging](/docs/messaging) 以获取凭证和 Webhook URL。
+
+### 秘密金库
+
+将凭证存储在 Dispatch 的保管库中一次。默认情况下，保管库访问权限是**所有应用程序**：每个保存的密钥均可用于每个工作区应用程序，并且 `sync-vault-to-app` 将完整保管库推送到目标应用程序。需要更严格分离的工作空间可以将保管库切换到**手动**模式，在同步之前需要明确的每个应用程序授权。非管理员可以**请求**应用程序的秘密；管理员**批准**，这会创建秘密，并在手动工作流程中创建授权。每次读取、授予、同步和轮换都会记录在审核日志中。这使得“旋转 OpenAI 键”成为跨十个应用而不是十个 PR 的一键操作。
+
+### 跨应用委托
+
+Dispatch 自动发现工作区中的其他应用程序作为 A2A 对等体 - 无需手动注册，无需每个应用程序配置。当用户在 Slack 中询问“汇总上周的注册情况”时，Dispatch 会将其识别为分析请求，并通过 [A2A](/docs/a2a-protocol) 调用分析应用程序。当他们询问“起草给 Alice 的回复”时，它会路由到邮件应用程序。 Dispatch 将最终答案发布回原始线程中。行为规则存在于调度代理的指令中：域工作属于域应用程序。 Dispatch 是协调者，而不是专家。
+
+### 统一MCP网关
+
+Dispatch 可以是外部代理的单个 MCP 连接器：在 Claude、ChatGPT、Codex 或 Cursor 中添加一次 `https://dispatch.agent-native.com/_agent-native/mcp`，一次授权可到达每个授予的工作区应用程序，而不是每个应用程序一个连接器。请参阅 [External Agents](/docs/external-agents) 了解完整的连接流程、应用程序授权、OAuth 和内联 MCP 应用程序预览。
+
+```an-api
+{
+  "method": "POST",
+  "path": "/_agent-native/mcp",
+  "summary": "Unified MCP gateway endpoint",
+  "description": "The single MCP connector URL external agents add (e.g. `https://dispatch.agent-native.com/_agent-native/mcp`). One authorization here reaches every **granted** workspace app instead of wiring one connector per app. App grants, OAuth, and inline MCP App previews are covered in [External Agents](/docs/external-agents).",
+  "auth": "Standard remote MCP OAuth, handled by the framework. The granted-app set scopes which workspace apps the connector can reach.",
+  "responses": [
+    { "status": "200", "description": "MCP JSON-RPC response — tools, resources, and MCP App UI resources aggregated across granted workspace apps." }
+  ]
+}
+```
+
+### 工作区资源
+
+Skills、护栏指令、代理配置文件和参考资源可以在 Dispatch 中创作一次，并由工作区的其余部分继承。 **所有应用程序**范围的资源是全局的：Dispatch 在工作区范围内存储它们一次，每个应用程序代理在运行时读取它们。它们不会复制到每个应用程序中，并且没有手动工作区资源同步步骤。应用共享资源和个人资源可以在本地覆盖或缩小工作区默认值。
+
+请参阅 [Workspace — Global resources](/docs/workspace#global-resources) 了解规范路径表、入门包和覆盖模型。
+
+MCP 服务器资源使用 JSON，并且有意仅限于 HTTP。将令牌存储在
+调度 Vault，将这些密钥授予或同步到目标应用程序，并引用它们
+来自带有 `${keys.NAME}` 的标头，因此原始凭证永远不会存在于
+资源主体。
+
+**资源**页面突出显示推荐的入门包，以便管理员可以快速查看存在哪些文件、恢复丢失的入门文件而不覆盖现有文件，以及编辑其内容。展开任何资源以预览所选应用程序/用户的有效运行时堆栈。每个应用程序卡还有一个**上下文**视图，准确显示该应用程序接收到的内容。
+
+### 梦想
+
+Dispatch Dreams 会审查之前的代理运行、反馈、评估和重复的失败，以提出持久的改进建议。梦想报告是一个审查表面，而不是无声重写：它可以建议个人内存更新、陈旧内存清理、共享 `LEARNINGS.md` 编辑、工作区指令/技能/知识/代理资源或重复作业，并且每个建议都链接回证明其合理性的运行。共享指令和团队范围的资源在应用之前需要进行审查，特别是当证据来自入站 Slack、电子邮件、Telegram、WhatsApp 或网络内容时。
+
+在提出写入之前，Dreams 将证据与个人记忆指数、现有的 `memory/*.md` 笔记和共享的 `LEARNINGS.md` 进行比较。如果已捕获课程，则报告会记录该课程已被跳过；如果相关的个人记忆看起来陈旧，提案会针对现有笔记而不是创建副本。
+
+从 Dispatch 中的 **Dreams** 选项卡开始。首先运行手动传递，打开提案审核表以将当前目标与提案内容和源证据进行比较，然后仅应用您想要保留的更改。一旦报告始终有用，Dispatch 就可以创建一个重复的理想工作，不断生成提案，而无需自动应用共享或指令级更改。
+
+### 审批流程
+
+Dispatch 可以在管理员审核后控制敏感的运行时更改。如今，这涵盖了**保存的目的地**（代理可以主动发送到的 Slack 渠道和电子邮件地址）、共享/团队**梦想提案**、所有应用程序**工作空间资源**创建/更新/删除以及**调度审批策略**本身。启用策略后，更改将排队，并且客服人员直接在聊天中显示内联批准预览 - 管理员无需离开对话即可批准或拒绝。
+
+## Slack消息如何流经Dispatch {#flow}
+
+端到端地演练一个示例。用户向机器人发送私信：_“总结上周的注册情况。”_
+
+1. **Slack → webhook。** Dispatch 应用程序上的 Slack `POST` 到 `/_agent-native/integrations/slack/webhook`。处理程序验证签名并**将一行插入 `integration_pending_tasks`**，然后将自定位的 `POST` 触发到其自己的处理器并立即返回 `200`，以便 Slack 不会重试。
+2. **新处理器执行。**处理器端点在全新的函数执行中运行，具有自己的完全超时。它以原子方式声明任务并启动代理循环。
+3. **调度代理决定。**代理读取消息，将“注册”识别为分析意图，并针对分析应用程序的 [A2A endpoint](/docs/a2a-protocol) 调用 `call-agent`。实际的 SQL 工作在那里运行。
+4. **在线程中发布回复。**分析代理返回结果。 Dispatch 将其格式化并回发到用户写入的同一个 Slack 线程中，如果存在链接身份，则使用链接身份（因此代理根据请求者的权限进行操作，而不是工作区所有者的权限）。
+5. **如果出现任何问题则进行恢复。**如果处理器在运行中崩溃 — A2A 超时、下游代理错误、功能冻结 — 重试作业每 60 秒清除卡住的任务并重新启动处理器。在任务被标记为 `failed` 之前最多尝试 3 次。
+
+```an-diagram title="A Slack message through Dispatch" summary="Slack enqueues into SQL, a fresh execution drains it, the Dispatch agent delegates the domain work over A2A, and the reply lands back in the originating thread. A 60s retry job recovers anything that dies mid-flight."
+{
+  "html": "<div class=\"dsp-flow\"><div class=\"dsp-row\"><div class=\"diagram-node\">Slack DM<br><small class=\"diagram-muted\">\"summarize last week's signups\"</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough><strong>/slack/webhook</strong><br><small class=\"diagram-muted\">verify + INSERT pending task</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill ok\">200</div></div><div class=\"dsp-row\"><div class=\"diagram-box\" data-rough><strong>fresh processor</strong><br><small class=\"diagram-muted\">claim task · start agent loop</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\">Dispatch agent decides</span><small class=\"diagram-muted\">analytics intent &rarr; call-agent</small></div></div><div class=\"dsp-row\"><div class=\"diagram-box\" data-rough>Analytics app<br><small class=\"diagram-muted\">A2A peer · runs the SQL work</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill ok\">reply posted in thread</div></div><div class=\"diagram-panel dsp-retry\" data-rough><span class=\"diagram-pill warn\">recovery</span> <span class=\"diagram-muted\">if the processor crashes &mdash; A2A timeout, downstream error, freeze &mdash; the 60s retry job re-fires it (&le;3 attempts) so the Slack reply still arrives</span> <span class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</span></div></div>",
+  "css": ".dsp-flow{display:flex;flex-direction:column;gap:12px}.dsp-flow .dsp-row{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.dsp-flow .center{display:flex;flex-direction:column;align-items:center;gap:4px}.dsp-flow .dsp-retry{display:flex;align-items:center;gap:8px;flex-wrap:wrap}"
+}
+```
+
+相同的流程适用于电子邮件、Telegram 和 WhatsApp — 只是适配器发生了变化。
+
+## 可靠性故事 {#reliability}
+
+整个管道的构建是为了在每个无服务器主机（Netlify、Vercel、Cloudflare Workers）上生存，而不依赖于特定于平台的后台执行 API。
+
+- **Webhook → SQL 队列 → 新执行处理器。** 代理循环永远不会在 Webhook 处理程序内运行。处理程序的唯一工作是验证、入队并返回 200。单独的新执行会耗尽队列，因此缓慢的代理运行永远不会占用入站 Webhook 或导致平台重试。
+- **A2A 连续轮询。** 当 Dispatch 委托给另一个应用程序时，它会在有限的超时时间内轮询下游任务。如果下游代理花费太长时间或崩溃，Dispatch 会记录延续，并且重试作业会拾取它 - 用户的 Slack 回复仍然到达。
+- **自动签名的跨应用程序 A2A。** 托管多应用程序工作区在部署时自动生成每个应用程序 A2A 凭据，因此同一工作区中的应用程序可以相互调用，而无需粘贴 JWT 密钥。 Dispatch 的代理发现层从工作区数据库中读取这些信用，因此新添加的应用程序会自动显示为可调用对等点。
+
+## 设置 {#setup}
+
+三个简短步骤：
+
+1. **搭建一个包含 Dispatch 的工作区。**运行 `npx @agent-native/core@latest create my-company-platform` 并选择 `dispatch` 以及您想要的任何域模板。 Dispatch 位于 `apps/dispatch`，其余应用程序位于它旁边。参见[Multi-App Workspace](/docs/multi-app-workspace)。
+2. **连接消息传递。** 在 Dispatch 中打开 **设置 → 消息传递**，然后单击连接 Slack、电子邮件、电报或 WhatsApp。表单字段与 [Messaging](/docs/messaging) 文档中的环境变量相匹配 - 请参阅那里了解每个平台的需求。
+3. **添加其他应用程序。**从每个域应用程序的工作区根运行 `npx @agent-native/core@latest add-app`。它们在 Dispatch 的 `list-workspace-apps` 中自动显示为 A2A 对等体 — 无需手动注册，无需编辑代理卡。一旦可以联系到他们的代理卡，Dispatch 就会开始委派给他们。
+
+然后将凭据添加到保管库并（可选）在**资源**下创作全局工作区资源。保管库密钥仍然可以根据访问模式同步或授予；所有应用程序工作区资源都会自动继承。如果您需要每个应用程序的秘密隔离，请在授予单个应用程序之前将保管库访问设置切换为手动。
+
+## 另请参阅 {#see-also}
+
+- [Dispatch template](/docs/template-dispatch) - 实际的脚手架应用程序，带有完整的操作目录和代理指南
+- [Messaging](/docs/messaging) — 连接 Slack、电子邮件、Telegram、WhatsApp
+- [A2A Protocol](/docs/a2a-protocol) — 跨应用委派在幕后如何工作
+- [Multi-App Workspace](/docs/multi-app-workspace) - Dispatch 的部署形状
+- [Workspace Governance](/docs/workspace-management) - 与 Dispatch 的运行时治理配对的 git/GitHub 治理

package/docs/content/locales/zh-CN/drop-in-agent.md

@@ -0,0 +1,260 @@
+---
+title: "临时代理"
+description: "使用 <AgentPanel>、<AgentSidebar> 和 sendToAgentChat() 将代理聊天 + 工作区安装到任何 React 应用中。"
+---
+
+# 临时代理
+
+> **开发人员页面。** 此页面供开发人员将代理嵌入到 React 应用程序中。有关使用代理的最终用户体验，请参阅 [Using Your Agent](/docs/using-your-agent)。
+
+您不需要从头开始构建原生代理。代理聊天、工作区选项卡、CLI 终端、语音输入和所有相关基础设施都作为少数 React 组件提供给您放入任何应用程序中。
+
+> **先决条件：** 服务器必须运行 `agent-chat-plugin`（它会自动安装在每个模板中）。如果您是从头开始，请参阅 [Server](/docs/server)。
+>
+> 需要公共 API 地图而不是教程？参见[Component API](/docs/components)。
+
+## 组件一览 {#components}
+
+| 组件                  | 它是什么                                           | 什么时候使用它                           |
+| --------------------- | -------------------------------------------------- | ---------------------------------------- |
+| `<AgentSidebar>`      | 包装您的根应用布局并添加包含完整代理的可切换侧面板 | 您希望代理在每个屏幕上与您的应用一起使用 |
+| `<AgentToggleButton>` | 打开/关闭 `<AgentSidebar>`（将其放入标头中）       | 与 `<AgentSidebar>` 配对                 |
+| `<AgentPanel>`        | 原始面板本身 - 聊天 + CLI + 工作区选项卡           | 您想要完全控制布局或专用代理页面         |
+| `<AgentChatSurface>`  | 预接线面板/页面聊天界面                            | 您想要在没有侧边栏包装器的情况下进行聊天 |
+| `<AssistantChat>`     | 具有作曲家/历史挂钩的低级聊天渲染器                | 您需要围绕标准对话 UI 进行自定义镶边     |
+| `sendToAgentChat()`   | 以编程方式向聊天发送消息                           | 将工作交给代理而不是内联运行的按钮       |
+| `useActionMutation()` | 围绕操作的类型安全前端包装                         | UI 需要运行代理工具运行的相同操作        |
+
+所有这些都是从`@agent-native/core/client`导出的。
+
+```an-diagram title="The mount model" summary="<AgentSidebar> wraps your existing layout. Your routes render in the main area; the agent panel mounts beside them. <AgentPanel> is the same panel without the wrapper."
+{
+  "html": "<div class=\"diagram-mount\"><div class=\"diagram-box sidebar\" data-rough><span class=\"diagram-pill accent\">&lt;AgentSidebar&gt;</span><div class=\"inner\"><div class=\"diagram-node main\">Your app<br><small class=\"diagram-muted\">children: header + &lt;Outlet/&gt;</small></div><div class=\"diagram-node panel\">Agent panel<br><small class=\"diagram-muted\">chat &middot; CLI &middot; workspace</small></div></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&harr;</div><div class=\"diagram-card alt\"><span class=\"diagram-pill\">&lt;AgentPanel&gt;</span><small class=\"diagram-muted\">same panel, no wrapper &mdash; you own the layout</small></div></div>",
+  "css": ".diagram-mount{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-mount .sidebar{display:flex;flex-direction:column;gap:8px;padding:14px}.diagram-mount .inner{display:flex;gap:10px}.diagram-mount .main{flex:2}.diagram-mount .panel{flex:1}.diagram-mount .alt{display:flex;flex-direction:column;gap:6px;padding:14px}.diagram-mount .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## 80%的情况：`<AgentSidebar>` {#sidebar}
+
+最常见的设置是在任何屏幕上从右侧打开侧边栏。
+用 `<AgentSidebar>` 包裹现有的根布局；无论你传递什么
+孩子们留在主应用程序区域。代理聊天位于侧面板。
+
+```an-annotated-code title="Wrapping the root layout with <AgentSidebar>"
+{
+  "filename": "app/root.tsx",
+  "language": "tsx",
+  "code": "import { Outlet } from \"react-router\";\nimport { AgentSidebar, AgentToggleButton } from \"@agent-native/core/client\";\n\nexport default function Root() {\n  return (\n    <AgentSidebar\n      emptyStateText=\"How can I help?\"\n      suggestions={[\n        \"Summarize my inbox\",\n        \"Draft a reply to the latest email\",\n        \"Show me yesterday's signup numbers\",\n      ]}\n      dynamicSuggestions\n      defaultSidebarWidth={420}\n      position=\"right\"\n    >\n      <header>\n        <AgentToggleButton />\n      </header>\n\n      <main>\n        <Outlet />\n      </main>\n    </AgentSidebar>\n  );\n}",
+  "annotations": [
+    { "lines": "6", "label": "Wrapper", "note": "`<AgentSidebar>` wraps your whole layout. It adds the toggleable side panel; everything you pass as children stays in the main app area." },
+    { "lines": "8-12", "label": "Starter prompts", "note": "`suggestions` render as clickable chips on the empty chat." },
+    { "lines": "13", "label": "Context-aware chips", "note": "`dynamicSuggestions` merges screen-aware prompts (e.g. \"Summarize this selection\") with your static ones. On by default." },
+    { "lines": "18-20", "label": "Toggle button", "note": "Put `<AgentToggleButton />` anywhere in your header to open and close the panel." },
+    { "lines": "22-24", "label": "Your app", "note": "`<Outlet/>` (your routes) renders in the main area, untouched." }
+  ]
+}
+```
+
+就是这样。用户现在在每个页面上都有一个可切换代理 - 具有聊天历史记录、工作区选项卡、CLI 终端、语音输入和全屏模式。通过 `localStorage` 重新加载，状态仍然存在。
+
+### 道具
+
+- **`children`** — 您的应用程序的正常布局和路线。在主区域渲染；代理面板在桌面上安装在其旁边，在移动/全屏上安装在其上方。
+- **`emptyStateText`** — 聊天没有消息时显示的问候语。默认值：`"How can I help you?"`。
+- **`suggestions`** — 启动提示在空时呈现为可点击的筹码。
+- **`dynamicSuggestions`** — 上下文感知提示芯片与 `suggestions` 合并。默认启用；传递 `false` 仅显示静态建议，或传递 `{ max, includeStatic, getSuggestions }` 进行自定义。
+- **`defaultSidebarWidth`** — 初始像素宽度（仅安装；用户调整大小并覆盖保存的值）。默认值：`380`。
+- **`position`** — `"left"` 或 `"right"`。默认值：`"right"`。
+- **`defaultOpen`** — 侧边栏是否开始打开（仅限桌面）。默认值：`false`。
+
+## 另外20%：`<AgentPanel>` {#panel}
+
+当您需要完全控制布局时 - 专用的 `/chat` 路线、您管理的侧栏中的嵌入式面板或弹出窗口 - 直接渲染 `<AgentPanel>`：
+
+```tsx
+// app/routes/agent.tsx
+import { AgentPanel } from "@agent-native/core/client";
+
+export default function AgentRoute() {
+  return (
+    <div className="h-screen">
+      <AgentPanel defaultMode="chat" className="h-full" />
+    </div>
+  );
+}
+```
+
+`<AgentPanel>` 为您提供原始选项卡（聊天/CLI/工作区），无需侧边栏包装、折叠按钮或任何状态持久性。把它放在你想要的任何地方；您负责布局。
+
+### 选定的道具
+
+- **`defaultMode`** — `"chat"` 或 `"cli"`。默认值：`"chat"`。
+- **`className`** — 外部容器的 CSS 类。
+- **`onCollapse`** — 如果提供，标题中会出现折叠按钮。
+- **`isFullscreen`** / **`onToggleFullscreen`** — 如果您想要 Claude 样式的居中列，请连接外部全屏状态。
+- **`storageKey`** — `localStorage` 密钥的命名空间。当您在同一页面中渲染多个面板（不同的应用程序实例或工作区）时很有用。
+
+完整道具：`@agent-native/core/client` 中的 `AgentPanelProps`。
+
+## 编程消息：`sendToAgentChat()` {#send}
+
+将工作交给代理的按钮（而不是运行内联 `llm()` 调用 - [ladder](/docs/what-is-agent-native#the-ladder) 的反模式）：
+
+```tsx
+import { sendToAgentChat } from "@agent-native/core/client";
+
+<Button
+  onClick={() =>
+    sendToAgentChat({
+      message: "Generate a chart showing signups by source",
+      context: `Dashboard ID: ${dashboardId}, date range: last 30 days`,
+      submit: true,
+    })
+  }
+>
+  Generate chart
+</Button>;
+```
+
+### 选项
+
+- **`message`** — 聊天中显示的可见提示。
+- **`context`** - 附加到提示的隐藏上下文（选定的文本、光标位置、当前实体 ID - 代理应该知道但用户不应看到两次的任何内容）。
+- **`submit`** — `true` 自动运行，`false` 预填充但等待。省略使用项目默认值。
+- **`newTab`** — 为此提示创建一个单独的聊天线程。
+- **`background`** — 使用 `newTab`，运行时无需聚焦新线程。隐藏运行在 `RunsTray` 中进行跟踪。
+- **`openSidebar`** — 设置为 `false` 以进行后台/静默发送。默认打开侧边栏，以便用户看到响应。
+- **`type`** — `"content"`（默认）将工作保留在嵌入式应用程序代理中。 `"code"` 路由到代码编辑框架（对于代理编写的代码更改，请参阅 [Frames](/docs/frames)）。
+
+`sendToAgentChat` 返回一个稳定的 `tabId`，您可以使用它来跟踪聊天运行。
+
+要实现静音工作，请将 `newTab`、`background` 和 `openSidebar: false` 配对：
+
+```ts
+sendToAgentChat({
+  message: "Summarize the selected thread and save the summary",
+  context: `Thread id: ${threadId}`,
+  submit: true,
+  newTab: true,
+  background: true,
+  openSidebar: false,
+});
+```
+
+这仍然是一个使用工具、actions、线程状态和运行运行的完整代理
+跟踪。它根本不会从用户当前的侧边栏状态中窃取焦点。
+
+当嵌入相同的路由作为MCP App时，提交
+`sendToAgentChat()` 呼叫将转发至支持的聊天主机；参见
+[Client](/docs/client#sendtoagentchat) 用于 MCP 应用桥接行为。
+
+如果您想要加载状态，请使用 `useSendToAgentChat()` 钩子 - 它返回 `send` 和 `isGenerating`：
+
+```ts
+import { useSendToAgentChat } from "@agent-native/core/client";
+
+const { send, isGenerating } = useSendToAgentChat();
+```
+
+## 当常用侧边栏不合适时 {#custom-chat-ui}
+
+`<AgentSidebar>`和`<AgentPanel>`涵盖了大多数应用程序。当您需要拥有
+围绕代理进行布局，或者您想要与代理进行对话
+您在其他地方构建，放下一层 - 但继续让框架拥有
+运行时、actions 和 SQL 支持的状态：
+
+- **在标准运行时拥有 chrome。**使用 `<AgentChatSurface>`
+  专用聊天路由，或者当您需要自定义标题时为 `<AssistantChat>`，
+  选项卡，以及标准对话周围的空白状态。完整图层图 —
+  每个组件、钩子、编写器和适配器，以及导入路径 - 都位于
+  [Component API](/docs/components#agent-chat-ui).
+- **自带代理运行时。**如果您在其他地方构建的代理应该
+  在 Agent-Native 保留作曲家、文字记录和工具的同时推动对话
+  卡片、批准和本机小部件，将 `AgentChatRuntime` 传递给
+  `<AssistantChat runtime={...} />`。连接器
+  （`createHttpAgentChatRuntime()` 和 OpenAI / Claude / Vercel AI / AG-UI
+  helpers）和事件契约记录在
+  [Native Chat UI — BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes).
+
+无论您选择哪一层，都将 actions 和 SQL 支持的应用程序状态保留为合约，
+并避免从产品 UI 直接发布到 `/_agent-native/agent-chat`。如果一个
+真正的自定义表面缺少指定的助手，请先添加该助手
+客户端代码不会学习第二个临时传输。
+
+## 来自 UI 的类型安全 actions：`useActionMutation()` {#use-action-mutation}
+
+当 UI 需要运行代理工具将运行的相同操作（[ladder](/docs/what-is-agent-native#rung-three) 的梯级 3）时，请使用 `useActionMutation`：
+
+```tsx
+import { useActionMutation } from "@agent-native/core/client";
+
+const { mutate, isPending } = useActionMutation("reply-to-email");
+
+<Button onClick={() => mutate({ emailId, body: "Thanks!" })}>
+  Send Reply
+</Button>;
+```
+
+类型安全参数来自 `defineAction()` 中的 zod 模式。完整的动作系统请参见 [Actions](/docs/actions)。
+
+```an-callout
+{
+  "tone": "decision",
+  "body": "**`useActionMutation` vs `sendToAgentChat`.** Run the operation directly with `useActionMutation` when the user clicked a deterministic button (\"Send reply\"). Hand it to `sendToAgentChat` when the work needs the agent's reasoning, tools, or multi-step planning. Never call an inline `llm()` from UI — that is rung 1 of the [ladder](/docs/what-is-agent-native#the-ladder)."
+}
+```
+
+## 选择+光标感知 {#selection}
+
+代理可以在应用程序状态下通过 `navigation` 和 `selection` 键查看用户选择的内容 - 文本、单元格、幻灯片、联系人。当当前屏幕使它们相关时，空聊天还使用这些键提供动态建议，例如“总结此选择”或“改进此幻灯片”。如果您希望使用 Cmd-I（或类似键）将选定的范围作为上下文发送到聊天中，请参阅 [Context Awareness](/docs/context-awareness)。
+
+## 将它们放在一起 {#putting-it-together}
+
+典型的嵌入式设置：
+
+```tsx
+// app/root.tsx
+import {
+  AgentSidebar,
+  AgentToggleButton,
+  sendToAgentChat,
+} from "@agent-native/core/client";
+
+export default function Root() {
+  return (
+    <AgentSidebar suggestions={["Draft a reply", "Summarize selection"]}>
+      <Header>
+        <AgentToggleButton />
+      </Header>
+
+      <Main>
+        <YourRoutes />
+      </Main>
+    </AgentSidebar>
+  );
+}
+```
+
+```tsx
+// Anywhere else in the app
+<Button
+  onClick={() =>
+    sendToAgentChat({
+      message: "Summarize this thread",
+      context: `Thread id: ${threadId}`,
+      submit: true,
+    })
+  }
+>
+  Summarize
+</Button>
+```
+
+用户在标题中看到一个聊天按钮，可以打开它，并可以与客服人员交谈。您的按钮将工作交给同一个代理，而不是运行一次性 LLM 调用。
+
+## 下一步是什么
+
+- [**Actions**](/docs/actions) — `defineAction()` 和 `useActionMutation()`
+- [**Context Awareness**](/docs/context-awareness) — 选择、导航、查看屏幕
+- [**Workspace**](/docs/workspace) —“工作空间”选项卡包含的内容（skills、内存、MCP 服务器、计划作业）
+- [**Voice Input**](/docs/voice-input) — 聊天编辑器中的麦克风

package/docs/content/locales/zh-CN/durable-resume.md

@@ -0,0 +1,65 @@
+---
+title: "持久的简历"
+description: "当托管代理运行被中断并恢复时，已完成的副作用工具调用不会重新运行 - 从持久账本派生的工具调用日志会阻止重复发送、收费和票证。"
+---
+
+# 持久的简历
+
+> **这是谁的：**任何想要了解框架如何运行的人
+> 恢复可避免重复的副作用。这是内置行为——有
+> 无需连接。
+
+托管代理运行被中断：无服务器函数在中途遇到硬超时，网关在 45 秒时断开连接，套接字挂起，平台冷启动。该框架已经通过保存对话前缀并重新运行 LLM 调用（“从上次中断的地方继续”）来恢复。但仅恢复就有一个明显的优势：如果被中断的尝试**已经发送了一封电子邮件或创建了一个票证**，那么天真的简历可以再次做到这一点。
+
+持久的简历弥补了这一差距。恢复时，框架知道哪个副作用工具调用已经完成，并拒绝在两层重新运行它们。
+
+```an-diagram title="Two layers block duplicate side effects on resume" summary="The journal reads the durable ledger and classifies prior calls; layer 1 tells the model, layer 2 hard-blocks a re-dispatched write that matches a completed entry."
+{
+  "html": "<div class=\"diagram-durable\"><div class=\"diagram-box\" data-rough>Run-event ledger<br><small class=\"diagram-muted\">tool_start / tool_done</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><strong>Tool-call journal</strong><small class=\"diagram-ok\">completed = start+done</small><small class=\"diagram-warn\">interrupted = start, no done</small></div><div class=\"diagram-col\"><div class=\"diagram-pill\">Layer 1 · prompt note &rarr; model</div><div class=\"diagram-pill accent\">Layer 2 · hard-block re-dispatched write</div></div></div>",
+  "css": ".diagram-durable{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-durable .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-durable .diagram-arrow{font-size:22px;line-height:1}.diagram-durable .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## 工具调用日志 {#journal}
+
+日志是**对持久运行事件分类帐的纯粹读取** - 热路径中没有新的记录挂钩。它对当前回合已记录的工具调用进行分类：
+
+- **已完成** — `tool_start` 与匹配的 `tool_done`。调用运行，它的副作用发生，并且它的结果被记录。 **不要重新运行。**
+- **中断** — `tool_start`，**没有**匹配 `tool_done`。通话开始了，它的副作用可能已经发生，也可能没有发生，而中断则吞噬了结果。结果未知。
+
+匹配反映了如何在其他地方重建耐用转弯：`tool_done` 与最旧的仍打开的 `tool_start` 配对，使用相同的工具名称（每个工具 FIFO）。 `clear` 事件（废弃的部分输出）会重置每轮计数，因此废弃的部分输出不会留下虚拟的开放调用。
+
+## 第1层：提示级日记笔记 {#prompt-note}
+
+当运行恢复时（软超时、网关超时或任何可恢复的传输错误），框架会在“从上次停止的地方继续”轻推之后，将**结构化日志注释**附加到恢复提示中。该注释以纯文本形式告诉模型：
+
+- 哪个工具调用**已经完成**（结果很短），因此它会重用它们并且**不会**重新运行它们，并且
+- 哪个工具调用被**因未知结果而中断**，因此它会在假设成功或失败之前验证状态。
+
+当日志为空时（没有工具活动的回合，或干净的延续），不会附加任何额外内容，并且恢复行为与之前的情况相同。该注释是尽力而为的：失败的账本读取永远不会阻止本来会成功的恢复。
+
+## 第2层：工具层硬块 {#hard-block}
+
+提示信息是建议性的 - 一个表现良好的模型会注意到它，但模型并不能保证。因此循环也在工具层强制执行它。
+
+在循环在恢复的块中运行之前，它会对日志进行一次快照（仅捕获此逻辑回合的**之前**块）。当模型重新分派工具名称**和输入**与已完成的日记条目匹配的**写入**工具时，循环会短路：它返回日记结果而不是执行操作，并注意该调用已在之前中断的尝试中完成，并且不会重新运行以避免重复的副作用。
+
+关键属性：
+
+- **仅限写入工具。**只读 (`readOnly` / GET) actions 永远不会被阻止 - 重新读取是安全且幂等的。
+- **内容寻址。** 匹配基于工具名称 + 输入签名，因此轮流中位于不同位置的恢复调用仍然匹配； _ different_ 调用（不同的参数）被视为新鲜调用并正常运行。
+- **消费一次。**每个已完成的条目在匹配时都会被声明，因此同一轮中两个真正不同的相同的新调用不会在一个日志完成时同时短路。
+- **新呼叫未受影响。**首轮呼叫会看到空日志；正常运行没有任何变化。
+
+```an-callout
+{
+  "tone": "success",
+  "body": "Together the two layers mean an interrupted run that already had a real side effect resumes **without repeating it** — no duplicate emails, charges, or tickets — while genuinely new work still runs. Read-only actions are never blocked; re-reading is always safe."
+}
+```
+
+## 相关
+
+- [**Real-Time Sync**](/docs/real-time-collaboration) — 持久运行账本如何流式传输到客户端并在重新连接时重播。
+- [**Actions**](/docs/actions) — `readOnly` 将读取标记为可以安全地重新运行；其他一切都被视为副作用。
+- [**In-Loop Processors**](/docs/processors) — 另一个循环内部硬化接缝。