@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/zh-CN/context-awareness.md

@@ -0,0 +1,373 @@
+---
+title: "情境意识"
+description: "代理如何知道用户正在查看的内容：导航状态、选择上下文、视图屏幕、sendToAgentChat 切换、导航命令和抖动预防。"
+---
+
+# 情境意识
+
+> **开发人员页面。** 此页面供开发人员连接应用程序的上下文层。对于最终用户体验 - 代理如何在对话中使用该上下文 - 请参阅 [Using Your Agent](/docs/using-your-agent)。
+
+代理如何知道用户正在看什么——以及代理如何控制用户看到的内容。
+
+## 概述 {#overview}
+
+如果没有上下文感知，代理就是盲目的。它询问“哪个电子邮件？”当用户盯着一个时。它无法作用于当前的选择，无法提供相关建议，也无法修改用户所看到的内容。借助上下文感知，用户可以单击一行、突出显示一个段落、选择一个幻灯片元素或按 Cmd+I，然后说“总结一下”，然后代理就已经知道“这个”的含义。
+
+要了解在哪个曲面中放置什么内容（AGENTS.md、skills、application_state），请参阅 [Writing Agent Instructions — The four surfaces the agent sees](/docs/writing-agent-instructions#four-surfaces)。
+
+六种模式解决了这个问题：
+
+1. **导航状态**——UI 在每次路线更改时将 `navigation` 密钥写入应用程序状态
+2. **当前 URL** - 框架写入 `__url__`，因此查询参数对代理可见且可编辑
+3. **选择状态**——当用户聚焦、选择或多选有意义的内容时，UI 会写入 `selection` 键
+4. **`view-screen`**——读取应用程序状态、获取上下文数据并返回用户所见内容的快照的操作
+5. **提示切换** -- 当点击应成为代理轮次时，UI 控件调用 `sendToAgentChat()`
+6. **`navigate`**——来自代理的一次性命令，告诉 UI 去哪里
+
+```an-diagram title="How the agent sees what you see" summary="The UI writes lightweight state keys; view-screen hydrates them into real records; the agent can write navigate back to move the UI."
+{
+  "html": "<div class=\"diagram-ctx\"><div class=\"diagram-card col\"><span class=\"diagram-pill\">UI writes</span><div class=\"diagram-node\">navigation<br><small class=\"diagram-muted\">view, open ids</small></div><div class=\"diagram-node\">__url__<br><small class=\"diagram-muted\">shareable filters</small></div><div class=\"diagram-node\">selection<br><small class=\"diagram-muted\">rows, blocks, shapes</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">view-screen</span><small class=\"diagram-muted\">reads state &middot; fetches records</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">Agent acts<br><small class=\"diagram-muted\">on the real object</small></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&#8635;</div><div class=\"diagram-box diagram-accent\">navigate<br><small class=\"diagram-muted\">agent moves the UI</small></div></div>",
+  "css": ".diagram-ctx{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-ctx .col{display:flex;flex-direction:column;gap:8px;padding:14px}.diagram-ctx .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px}.diagram-ctx .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## 上下文层 {#context-layers}
+
+针对不同的作业使用不同的上下文通道：
+
+| 层                                       | 所有者            | 用它来                                                       |
+| ---------------------------------------- | ----------------- | ------------------------------------------------------------ |
+| `navigation` 应用状态密钥                | UI                | 语义路由状态：当前视图、打开的记录、活动选项卡、稳定 ID      |
+| `__url__` 应用状态密钥                   | 框架UI            | 当前路径名、搜索字符串、哈希和解析的 URL 查询参数            |
+| `__set_url__` 应用状态密钥               | 代理/框架         | 对 `set-search-params` 和 `set-url-path` 进行一次性 URL 编辑 |
+| `selection` 应用状态密钥                 | UI                | 持久的语义选择：行、块、形状、资产、消息                     |
+| `pending-selection-context` 应用状态密钥 | UI / `AgentPanel` | 一次性选择的文本附加到下一个聊天回合，通常来自 Cmd+I         |
+| `view-screen` 动作                       | 代理              | 将应用状态键融入真实记录和屏幕摘要                           |
+| `sendToAgentChat()`                      | UI                | 将点击、命令、评论图钉或所选项目转变为聊天提示               |
+| `navigate` 应用状态密钥                  | 代理              | 要求UI移动到另一条路线或聚焦另一个物体                       |
+
+简短版本：URL 查询参数是可共享过滤器的真实来源，`navigation` 存储语义 ID 和视图名称，`view-screen` 将这些状态层转换为有用的数据，而当用户单击命令时，`sendToAgentChat()` 将 UI 意图转换为聊天消息。
+
+## 导航状态 {#navigation-state}
+
+UI 在每次路由更改时将 `navigation` 密钥写入应用程序状态。这告诉代理用户正在使用哪个视图、打开哪个项目以及哪个语义 UI 状态很重要。
+
+```json
+{
+  "view": "inbox",
+  "threadId": "thread-123",
+  "focusedEmailId": "msg-456",
+  "label": "important"
+}
+```
+
+导航状态中包含的内容：
+
+- `view` -- 当前页面/部分，例如“收件箱”、“表单构建器”或“仪表板”
+- 项目 ID -- 选定/打开的项目，例如 `threadId` 或 `formId`
+- 语义别名 - 活动选项卡、标签名称或其他有助于代理推理的稳定应用概念
+- 轻焦点状态 - 聚焦行、活动选项卡、当前面板
+
+保持 `navigation` 小且语义化。它应该识别当前屏幕，而不是复制整个记录或镜像每个查询参数。获取 `view-screen` 中的记录，以便代理始终获取最新数据。
+
+代理在行动前阅读以下内容：
+
+```ts
+import { readAppState } from "@agent-native/core/application-state";
+
+const navigation = await readAppState("navigation");
+// { view: "inbox", threadId: "thread-123", label: "important" }
+```
+
+## 当前URL和过滤器 {#current-url}
+
+`AgentPanel` 自动将当前 React 路由器 URL 同步到 `__url__` 应用程序状态密钥中。内置代理每次都会将其包含为 `<current-url>` 块：
+
+```text
+<current-url>
+pathname: /adhoc/revenue
+search: ?f_region=west&q=renewal
+searchParams:
+  f_region: west
+  q: renewal
+</current-url>
+```
+
+这是可共享过滤器状态的规范层。如果用户可以复制 URL 并返回到相同的过滤列表，则该过滤器属于查询字符串。代理可以使用内置的 `set-search-params` 工具更改这些过滤器：
+
+```text
+set-search-params({ "params": { "f_region": "east", "q": null } })
+```
+
+仅将 `navigation` 用于帮助 `view-screen` 获取或汇总正确数据的语义别名。仪表板可能保留 `navigation.dashboardId`，而 `__url__.searchParams` 拥有 `f_region`、`f_dateStart` 和 `q`。
+
+当`view-screen`返回更丰富的快照时，它可以将重要的URL过滤器复制到友好的`activeFilters`对象中：
+
+```ts
+const url = (await readAppState("__url__")) as {
+  searchParams?: Record<string, string>;
+} | null;
+
+if (url?.searchParams) {
+  screen.activeFilters = Object.fromEntries(
+    Object.entries(url.searchParams).filter(
+      ([key, value]) => key.startsWith("f_") && value,
+    ),
+  );
+}
+```
+
+## 选择状态 {#selection-state}
+
+选择是语义 UI 状态。这就是“我单击的图表”、“这三行”、“这张幻灯片标题”或“当前电子邮件草稿范围”如何成为模型可见上下文的方式。
+
+使用 `selection` 应用状态键进行持久选择，该选择应该在导航、空聊天建议或稍后的 `view-screen` 调用中保留下来：
+
+```json
+{
+  "kind": "slide.elements",
+  "deckId": "deck-123",
+  "slideId": "slide-4",
+  "items": [
+    {
+      "id": "hero-title",
+      "selector": "[data-block-id='hero-title']",
+      "label": "Hero title",
+      "text": "Q3 launch plan"
+    }
+  ],
+  "capturedAt": 1780332977027
+}
+```
+
+当用户选择、聚焦或多选有意义的对象时，从 UI 写入：
+
+```tsx
+import { setClientAppState } from "@agent-native/core/client";
+
+async function syncSelection(selection: unknown | null) {
+  await setClientAppState("selection", selection, { keepalive: true });
+}
+```
+
+良好的选择状态包括：
+
+- 代理可以在 actions 中使用的稳定 ID，例如 `threadId`、`slideId` 或 `assetId`
+- 简短的人工标签，以便提示和建议易于阅读
+- 足够的文本或元数据来消除对象的歧义
+- 可选的 UI 定位器，例如代理需要引用视觉元素时的选择器或坐标
+- `capturedAt` 当过时的选择有害时
+
+避免在 `selection` 中存储机密、完整文档、大型二进制有效负载或整个 API 响应。存储 ID 和简短摘录，然后让 `view-screen` 获取当前的事实来源。
+
+### 一次性选定文本 {#pending-selection-context}
+
+`AgentPanel` 已经处理常见的文本选择流程。当用户在页面上选择文本的情况下按 Cmd+I（或 Ctrl+I）时，它：
+
+1. 读取`window.getSelection()`
+2. 将 `{ text, capturedAt }` 写入 `pending-selection-context`
+3. 聚焦客服人员聊天
+
+生产代理将该密钥作为立即选择上下文注入下一回合，并在其过时后忽略它。这是使“选择文本，按 Cmd+I，询问‘使其更加有力’”工作的路径，而无需用户将选择内容复制到提示中。
+
+当自定义编辑器的选择不由本机浏览器选择表示时，可以编写相同的键：
+
+```tsx
+import { setClientAppState } from "@agent-native/core/client";
+
+await setClientAppState(
+  "pending-selection-context",
+  {
+    text: selectedMarkdown,
+    capturedAt: Date.now(),
+  },
+  { keepalive: true },
+);
+```
+
+使用 `pending-selection-context` 一次性“对这个精确突出显示的文本进行操作”流程。使用 `selection` 进行持久对象选择，`view-screen` 和动态建议应该不断看到。
+
+## 查看屏幕操作 {#view-screen-action}
+
+每个模板都应该有一个 `view-screen` 操作。它读取导航和选择状态，获取相关数据，并返回用户所看到内容的快照。这是特工的眼睛。
+
+```an-annotated-code title="view-screen — the agent's eyes"
+{
+  "filename": "actions/view-screen.ts",
+  "language": "ts",
+  "code": "import { defineAction } from \"@agent-native/core/action\";\nimport { readAppState } from \"@agent-native/core/application-state\";\nimport { eq, inArray } from \"drizzle-orm\";\nimport { z } from \"zod\";\nimport { getDb, schema } from \"../server/db/index.js\";\n\nexport default defineAction({\n  description:\n    \"See what the user is currently looking at on screen.\",\n  schema: z.object({}),\n  http: false,\n  run: async () => {\n    const navigation = (await readAppState(\"navigation\")) as any;\n    const selection = (await readAppState(\"selection\")) as any;\n    const screen: Record<string, unknown> = {};\n    if (navigation) screen.navigation = navigation;\n    if (selection) screen.selection = selection;\n\n    const db = getDb();\n\n    // Fetch data based on what the user is viewing\n    if (navigation?.view === \"inbox\") {\n      screen.emailList = await db\n        .select()\n        .from(schema.emails)\n        .where(eq(schema.emails.label, navigation.label));\n    }\n    if (navigation?.threadId) {\n      screen.thread = await db\n        .select()\n        .from(schema.threads)\n        .where(eq(schema.threads.id, navigation.threadId));\n    }\n    if (selection?.kind === \"email.messages\") {\n      screen.selectedMessages = await db\n        .select()\n        .from(schema.emails)\n        .where(inArray(schema.emails.id, selection.messageIds));\n    }\n\n    if (Object.keys(screen).length === 0) {\n      return \"No application state found. Is the app running?\";\n    }\n    return screen;\n  },\n});",
+  "annotations": [
+    { "lines": "10-11", "label": "Tool surface", "note": "The agent reads this description to know it can call `view-screen` to see the current UI." },
+    { "lines": "13", "label": "http: false", "note": "Internal action — not exposed over HTTP. The agent and `pnpm action` call it, not the browser." },
+    { "lines": "15-16", "label": "Read state", "note": "Pulls the lightweight `navigation` and `selection` keys the UI wrote." },
+    { "lines": "23-37", "label": "Hydrate", "note": "Turns those IDs into **fresh** records straight from SQL, so the agent verifies the live object before acting." }
+  ]
+}
+```
+
+代理应在对当前 UI 进行操作之前调用 `pnpm action view-screen`。这是所有模板的硬约定。添加新功能时，更新 `view-screen` 以返回新视图和任何新选择形状的数据。
+
+```an-callout
+{
+  "tone": "info",
+  "body": "**Keep `navigation` and `selection` small.** Store IDs plus short labels, not whole records. `view-screen` fetches the source of truth on demand, so stale or bulky state never reaches the agent."
+}
+```
+
+## 与 `sendToAgentChat()` 快速切换 {#send-to-agent-chat}
+
+有时上下文不应该仅仅处于应用程序状态。用户单击按钮、放下评论图钉、选择项目并选择“询问代理”，或者按下工具栏中的 AI 命令。那次点击是一个指令。在浏览器UI中，将其交给带有`sendToAgentChat()`的代理。
+
+```tsx
+import { sendToAgentChat } from "@agent-native/core/client";
+
+function askAgentAboutSelection(selection: {
+  documentId: string;
+  blockId: string;
+  label: string;
+  text: string;
+}) {
+  sendToAgentChat({
+    message: `Improve the selected block: ${selection.label}`,
+    context: [
+      `Document id: ${selection.documentId}`,
+      `Block id: ${selection.blockId}`,
+      "Current selected text:",
+      selection.text,
+    ].join("\n"),
+    submit: false,
+    openSidebar: true,
+  });
+}
+```
+
+有意使用这些字段：
+
+| 字段                | 含义                                                   |
+| ------------------- | ------------------------------------------------------ |
+| `message`           | 聊天中显示可见的提示文本                               |
+| `context`           | 隐藏的模型可见上下文，不显示为面向用户的聊天文本       |
+| `submit: true`      | 立即发送；适用于显式命令按钮，例如“修复布局”           |
+| `submit: false`     | 预填以供用户审核；适合“向代理询问此事”或模棱两可的选择 |
+| `openSidebar: true` | 即使面板折叠，代理响应也可见                           |
+| `newTab: true`      | 为更大的创建任务启动单独的聊天线程                     |
+| `type: "code"`      | 当请求涉及更改应用程序源时路由到代码编辑框架           |
+
+`sendToAgentChat()` 是提交的聊天路径受支持的浏览器包装器，有时在内部被视为 `agentNative.submitChat`。应用程序 UI 应调用包装器，而不是直接发布 `agentNative.submitChat`，因为包装器处理本地侧边栏、Builder/Frame 路由、MCP 应用程序主机路由、选项卡 ID 和代码请求路由。
+
+对于没有浏览器侧边栏的节点/脚本上下文，请使用 `agentChat.submit()` 或 `agentChat.prefill()`。服务器actions一般不应该调用仅浏览器的`sendToAgentChat()`；如果某个操作需要打开 UI 向代理询问某些内容，请将一个小请求写入 `application_state` 并让 UI 桥接器从浏览器发送它。
+
+### 点击提示中的项目 {#clicked-items-in-prompt}
+
+对于“单击 UI 中的项目，它们成为提示的一部分”体验，请将选择状态与提示切换相结合：
+
+1. 单击或多选时，写入语义 `selection` 状态，以便 `view-screen`、动态建议和未来回合可以看到它。
+2. 如果点击也是命令，则调用`sendToAgentChat()`，简洁的可见`message`和更丰富的隐藏`context`。
+3. 在 `view-screen` 中，将选定的 ID 合并到当前记录中，以便代理可以在改变对象之前验证该对象。
+4. 当对象不再被选择、删除或不再相关时，清除 `selection`。
+
+这为用户提供了神奇的“这就是我的意思”行为，而无需在每个提示中填充大量可见上下文。
+
+## 导航操作 {#navigate-action}
+
+`navigate` 是 `navigation` 的镜像。其中`navigation`是UI告诉代理用户在哪里，`navigate`是代理告诉UI去哪里。代理将一次性 `navigate` 命令写入应用程序状态； UI 读取它，执行导航，然后删除该条目。
+
+```ts
+// Agent side -- write a navigate command
+import { writeAppState } from "@agent-native/core/application-state";
+
+await writeAppState("navigate", { view: "inbox", threadId: "thread-123" });
+```
+
+在 UI 端，您永远不会手动轮询或删除此密钥。两个方向（在每次路由更改时写入 `navigation` 并使用代理的 `navigate` 命令）均由单个钩子 [`useNavigationState`](#use-navigation-state) 处理，下一节将对此进行介绍。
+
+`navigation`密钥属于UI；代理绝不能直接写入。代理写入 `navigate`，UI 执行移动，该移动更新 `navigation`。
+
+当目的地有真实的URL时，请在其上包含同源的`path`
+`navigate` 命令并让 UI 在回退到该路径之前选择该路径
+语义字段。保持应用程序导航单通道：不要同时写入
+`navigate` 和 `__set_url__` 相同的动作。 `__set_url__` 为
+框架URL工具（`set-url-path`、`set-search-params`）和仅URL过滤器
+改变。对于在聊天流式传输时可以到达的命令，请提交路由
+使用 `navigate(path, { replace: true, flushSync: true })` 而不是包装它
+在视图转换中，使地址栏和可见页面保持在一起。
+
+## useNavigationState 挂钩 {#use-navigation-state}
+
+`useNavigationState` 是 **您的应用程序的钩子，而不是框架导入。** 每个模板都在 `app/hooks/use-navigation-state.ts` 上发布一个，并从应用程序 shell (`root.tsx`) 调用它一次。这是连接两个方向导航的单一位置：
+
+- **出站（UI→代理）：**每当路线改变时写入`navigation`密钥，因此代理始终知道当前视图。
+- **入站（代理 → UI）：**轮询 `navigate` 命令、运行导航并删除命令。
+
+它很短，因为它是真实框架原语 `useAgentRouteState`（从 `@agent-native/core/client` 导出）的薄包装。您提供两个特定于应用程序的功能，框架将完成其余的工作：
+
+```tsx
+// app/hooks/use-navigation-state.ts -- this file lives in YOUR app
+import { useAgentRouteState } from "@agent-native/core/client";
+import { TAB_ID } from "@/lib/tab-id";
+
+interface NavigationState {
+  view: "inbox" | "thread";
+  threadId?: string;
+  path?: string;
+}
+
+export function useNavigationState() {
+  useAgentRouteState<NavigationState>({
+    browserTabId: TAB_ID,
+    requestSource: TAB_ID,
+
+    // UI → agent: derive semantic state from the current URL.
+    getNavigationState: ({ pathname }) => {
+      const match = pathname.match(/^\/thread\/([^/]+)/);
+      return match ? { view: "thread", threadId: match[1] } : { view: "inbox" };
+    },
+
+    // agent → UI: turn a `navigate` command into a route to push.
+    getCommandPath: (command) =>
+      command.path ??
+      (command.view === "thread" && command.threadId
+        ? `/thread/${command.threadId}`
+        : "/"),
+    navigateOptions: { replace: true, flushSync: true },
+  });
+}
+```
+
+| 你写                                            | 框架句柄                                     |
+| ----------------------------------------------- | -------------------------------------------- |
+| `getNavigationState` — 将 URL 映射到语义状态    | `navigation` 写入，制表符范围加上全局后备键  |
+| `getCommandPath` — 将 `navigate` 命令映射到路由 | 命令轮询、读后删除、重复命令保护、请求源标记 |
+
+`useAgentRouteState` 假定为 React 路由器。当导航不在 URL 中时（向导步骤、画布选择、非路由器 shell），而是下拉到较低级别的 `useSemanticNavigationState`：您将现成的 `state` 值加上 `navigationKeys`/`commandKeys` 和 `onCommand` 回调，并且它与 React 路由器完全无关。
+
+## 抖动预防 {#jitter-prevention}
+
+当代理写入应用程序状态时，同步系统可能会导致 UI 重新获取刚刚写入的数据。这会产生抖动。解决方案是源标记：
+
+使用 `@agent-native/core/client` 中的 `setClientAppState`、`writeClientAppState`、`readClientAppState` 和 `deleteClientAppState` 进行浏览器端应用程序状态访问。与`useDbSync({ ignoreSource: TAB_ID })`配对时通过`{ requestSource: TAB_ID }`对UI进行写入；通过 `{ keepalive: true }` 进行短期写入，例如卸载期间的选择清理。
+
+```ts
+// app/root.tsx
+import { TAB_ID } from "@/lib/tab-id";
+
+useDbSync({
+  queryClient,
+  ignoreSource: TAB_ID, // ignore events from this tab's own writes
+});
+```
+
+工作原理：
+
+- 代理写入标记为 `requestSource: "agent"`（操作助手自动执行此操作）
+- UI 写入通过 `X-Request-Source` 标头包含选项卡的唯一 ID
+- 服务器存储每个事件的源
+- 处理同步事件时，UI 会过滤掉与其自己的 `ignoreSource` 值匹配的事件 - 因此它不会重新获取刚刚写入的数据
+- 来自代理、其他选项卡和 actions 的事件仍然正常进行
+
+```an-diagram title="Source tagging stops self-refetch jitter" summary="A tab ignores sync events stamped with its own TAB_ID, but still reacts to agent and other-tab writes."
+{
+  "html": "<div class=\"diagram-jitter\"><div class=\"diagram-node\">This tab writes<br><small class=\"diagram-muted\">X-Request-Source: TAB_ID</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Server stores source<br>on the event</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card col\"><div class=\"diagram-pill warn\">source == TAB_ID &rarr; ignored</div><small class=\"diagram-muted\">no refetch, no flicker</small><div class=\"diagram-pill ok\">agent / other tab &rarr; applied</div><small class=\"diagram-muted\">UI updates live</small></div></div>",
+  "css": ".diagram-jitter{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-jitter .col{display:flex;flex-direction:column;gap:6px;padding:14px}.diagram-jitter .diagram-arrow{font-size:22px;line-height:1}"
+}
+```