@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,294 @@
+---
+title: "可观察性"
+description: "代理跟踪、评估、反馈、A/B 实验和内置仪表板 - 全部为零配置。"
+---
+
+# 代理可观察性
+
+每个代理本机应用程序都具有开箱即用的可观察性。跟踪、自动评估、用户反馈和 A/B 实验可在零配置下运行 - 所有数据都存储在应用自己的 SQL 数据库中。
+
+此页面涵盖*代理质量*指标：存储在数据库中的跟踪、成本、评估和反馈。对于*product*分析（您的应用程序的事件流向PostHog/Mixpanel/Amplitude），请参阅[Tracking](/docs/tracking)。
+
+## 三样东西叫做“评估”/“可观察性”——我想要哪一个？ {#which}
+
+这三个页面很容易混淆。根据您要问的问题进行选择：
+
+| 页面                                                   | 它回答的问题                           | 当它运行时                       | 关注      |
+| ------------------------------------------------------ | -------------------------------------- | -------------------------------- | --------- |
+| **可观测性评估**（此页面，_Evals_ 选项卡）             | “我的实际生产情况如何？”               | 被动，每次运行后（LLM-判断采样） | 质量      |
+| **[CI Eval Gate](/docs/evals)** (`*.eval.ts`)          | “代理在此固定输入上执行正确的操作吗？” | 主动、确定性、CI/部署门          | 质量      |
+| **[Observational Memory](/docs/observational-memory)** | “这条长线是否便宜且位于窗户内？”       | 长线程上的后台压缩               | 成本/环境 |
+
+可观察性和 CI 评估门都对质量进行评分，但两端不同——对实际流量进行被动事后评分，与对固定输入进行主动通过/失败检查。观察记忆与质量无关；这与代币成本和上下文窗口压力有关。
+
+## 自动捕获的内容 {#captured}
+
+当用户发送消息时，框架会自动记录：
+
+- **令牌使用** — 输入、输出、缓存读取、缓存写入
+- **成本** — 根据代币数量和模型定价计算
+- **延迟** — 每次工具调用的总持续时间和时间
+- **工具调用** — 调用了哪些 actions、成功/错误状态、持续时间
+- **自动评估** - 每次运行后计算 5 个质量分数
+
+无需更改代码。仪器透明地挂接到 `production-agent.ts`。
+
+```an-diagram title="Every run feeds the loop" summary="One agent run produces a trace, automated scores, and a feedback hook — all stored in the app's own SQL and surfaced on the dashboard. Experiments split traffic across config variants."
+{
+  "html": "<div class=\"obs-loop\"><div class=\"diagram-node\">Agent run<br><small class=\"diagram-muted\">production-agent.ts</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Captured automatically</span><small class=\"diagram-muted\">tokens &middot; cost &middot; latency &middot; tool calls</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box\">Traces &amp; spans</div><div class=\"diagram-box\">Evals (5 scorers + LLM judge)</div><div class=\"diagram-box\">Feedback &amp; frustration index</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node ok\">Dashboard<br><small class=\"diagram-muted\">scoped to the signed-in user</small></div></div>",
+  "css": ".obs-loop{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.obs-loop .diagram-col{display:flex;flex-direction:column;gap:8px}.obs-loop .diagram-arrow{font-size:22px;line-height:1}.obs-loop .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## 仪表板 {#dashboard}
+
+将仪表板添加到具有单个路由的任何模板：
+
+```tsx
+// app/routes/observability.tsx
+import { ObservabilityDashboard } from "@agent-native/core/client";
+
+export default function ObservabilityPage() {
+  return (
+    <div className="min-h-screen bg-background p-6">
+      <ObservabilityDashboard />
+    </div>
+  );
+}
+```
+
+所有数据的范围仅限于登录用户；今天没有跨用户管理视图。
+
+仪表板有 5 个选项卡：
+
+| 选项卡   | 它显示了什么                                                 |
+| -------- | ------------------------------------------------------------ |
+| **概述** | 关键指标 - 运行、成本、延迟、工具成功率、满意度、评估分数    |
+| **对话** | 跟踪列表，可深入到各个范围（agent_run、llm_call、tool_call） |
+| **评估** | 按标准自动评估分数、随时间变化的趋势                         |
+| **实验** | 带有状态徽章的 A/B 测试列表、带有置信区间的变量结果          |
+| **反馈** | 赞成/反对、类别细分、挫败感分数                              |
+
+## 用户反馈 {#feedback}
+
+### 明确反馈
+
+“竖起大拇指”/“竖起大拇指”按钮在聊天 UI 中的每条代理消息上呈现内联。拇指朝下会打开一个类别弹出窗口（不准确、没有帮助、工具错误、太慢）。这会自动连接到 `AssistantChat.tsx`。
+
+### 隐性反馈（挫败指数）
+
+框架根据对话信号计算挫败指数（0-100）：
+
+| 信号     | 重量 | 它检测到什么           |
+| -------- | ---- | ---------------------- |
+| 改写     | 30%  | 用户重复类似的消息     |
+| 重试模式 | 20%  | “再试一次”，“不，错了” |
+| 放弃     | 20%  | 会话在响应后不久结束   |
+| 情绪     | 15%  | 负面语言模式           |
+| 长度趋势 | 15%  | 消息长度减少           |
+
+分数解释：0-20 = 健康，20-40 = 摩擦，40-60 = 不满意，60+ = 中断的训练。
+
+## 自动评估 {#evals}
+
+每次代理运行后都会运行五个确定性记分器：
+
+| 标准                | 它测量什么                              | 分数范围 |
+| ------------------- | --------------------------------------- | -------- |
+| `tool_success_rate` | 没有错误的工具调用百分比                | 0-1      |
+| `step_efficiency`   | 对使用工具的运行进行过多的 LLM 迭代惩罚 | 0-1      |
+| `latency_score`     | 根据 10 秒/工具基线进行归一化           | 0-1      |
+| `cost_efficiency`   | 根据成本基线标准化                      | 0-1      |
+| `error_recovery`    | 代理是否从工具错误中恢复？              | 0 或 1   |
+
+### LLM作为法官（可选）
+
+通过设置 `evalSampleRate` 启用基于采样 LLM 的评估：
+
+```ts
+import { putSetting } from "@agent-native/core/settings";
+
+await putSetting("observability-config", {
+  enabled: true,
+  evalSampleRate: 0.05, // 5% of runs
+});
+```
+
+自定义标准使用自然语言规则：
+
+```ts
+const criteria = {
+  name: "helpfulness",
+  description: "Was the response helpful and complete?",
+  rubric: "0.0 = unhelpful, 0.5 = partially helpful, 1.0 = fully resolved",
+};
+```
+
+## A/B 实验 {#experiments}
+
+测试不同的型号、温度或代理配置：
+
+```ts
+// Create via API
+POST /_agent-native/observability/experiments
+{
+  "name": "model-a-vs-b",
+  "variants": [
+    { "id": "control", "weight": 50, "config": { "model": "<your-model-id>" } },
+    { "id": "treatment", "weight": 50, "config": { "model": "<other-model-id>" } }
+  ],
+  "metrics": ["cost", "latency", "satisfaction"]
+}
+
+// Start the experiment
+PUT /_agent-native/observability/experiments/:id
+{ "status": "running" }
+```
+
+使用您的引擎接受的真实模型标识符来代替 `<your-model-id>` / `<other-model-id>`（模型名称经常更改 - 检查您的提供商/引擎的当前 ID）。代理循环自动解析用户的变体并应用配置覆盖。分配使用一致的散列——同一用户总是得到相同的变体。
+
+```an-diagram title="Consistent-hash variant assignment" summary="Each user hashes to a stable variant, the loop applies that variant's config override, and results roll up per variant with confidence intervals."
+{
+  "html": "<div class=\"exp\"><div class=\"diagram-node\">User id<br><small class=\"diagram-muted\">consistent hash</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-card\"><span class=\"diagram-pill\">control &middot; 50%</span><small class=\"diagram-muted\">config override A</small></div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">treatment &middot; 50%</span><small class=\"diagram-muted\">config override B</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">Results per variant<br><small class=\"diagram-muted\">cost &middot; latency &middot; satisfaction</small></div></div>",
+  "css": ".exp{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.exp .diagram-col{display:flex;flex-direction:column;gap:8px}.exp .diagram-card{display:flex;flex-direction:column;gap:2px;padding:8px 12px}.exp .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## 配置 {#config}
+
+所有设置都存储在 `observability-config` 密钥中：
+
+```ts
+{
+  enabled: true,           // Master switch
+  capturePrompts: false,   // Store prompt content in traces
+  captureToolArgs: false,  // Store action input arguments
+  captureToolResults: false, // Store action results
+  evalSampleRate: 0,       // 0-1, fraction of runs to LLM-judge
+  exporters: []            // OTLP export targets
+}
+```
+
+```an-callout
+{
+  "tone": "info",
+  "body": "Content is **redacted by default** — only token counts, costs, and timing are stored. `capturePrompts`, `captureToolArgs`, and `captureToolResults` are opt-in; turn them on only when you need prompt/argument content for debugging."
+}
+```
+
+## API端点 {#api}
+
+全部自动安装在`/_agent-native/observability/`：
+
+| 方法 | 路径                       | 目的                      |
+| ---- | -------------------------- | ------------------------- |
+| GET  | `/`                        | 统计概览                  |
+| GET  | `/traces`                  | 列出跟踪摘要              |
+| GET  | `/traces/:runId`           | 跟踪详细信息（摘要+跨度） |
+| GET  | `/traces/:runId/evals`     | 运行评估                  |
+| POST | `/feedback`                | 提交反馈                  |
+| GET  | `/feedback`                | 列出反馈                  |
+| GET  | `/feedback/stats`          | 反馈聚合                  |
+| GET  | `/satisfaction`            | 满意度分数                |
+| GET  | `/evals/stats`             | 评估统计                  |
+| POST | `/experiments`             | 创建实验                  |
+| GET  | `/experiments`             | 列出实验                  |
+| GET  | `/experiments/:id`         | 获取实验详细信息          |
+| PUT  | `/experiments/:id`         | 更新实验                  |
+| POST | `/experiments/:id/results` | 计算结果                  |
+| GET  | `/experiments/:id/results` | 获取结果                  |
+
+所有端点均支持`?since=N`（毫秒时间戳）和`?limit=N`查询参数。
+
+## 导出到外部平台 {#export}
+
+将跟踪发送到 Langfuse、Datadog、Grafana 或任何 OTel 兼容后端：
+
+```ts
+await putSetting("observability-config", {
+  enabled: true,
+  exporters: [
+    {
+      type: "otlp",
+      endpoint: "https://cloud.langfuse.com/api/public/otel",
+      headers: { Authorization: "Bearer sk-..." },
+    },
+  ],
+});
+```
+
+该框架发出与 OpenTelemetry GenAI 规范兼容的 `gen_ai.*` 语义约定范围。
+
+## OpenTelemetry 跨度 {#otel}
+
+与上面的 `exporters` 配置（将内部跟踪发送到 OTLP 端点）不同，代理循环还可以为每次运行、模型调用和工具调用发出**实时 OpenTelemetry 范围**，因此已经运行 OTel 收集器的主机可以看到代理活动以及其分布式跟踪的其余部分。
+
+该层是**可选且默认情况下无操作**：
+
+- `@opentelemetry/api` 是**可选依赖项**。如果未安装，帮助程序将降级为静默无操作 - 这里不会将任何内容放入代理循环中。
+- 即使 api 包存在，它也会提供默认的无操作跟踪器。只有当**主机注册了 `TracerProvider`**（通过 `@opentelemetry/sdk-node` 或类似的）时，跨度才变得真实。该框架故意**不**依赖于繁重的 SDK/exporter 包或本身注册提供程序 - 检测是由嵌入应用程序选择加入的。
+
+因此，当您未连接 OTel 时，成本是每次调用都会读取几次缓存的属性。要打开它，请安装 api 包和 SDK，并在服务器启动时注册提供程序，就像任何其他 Node 服务一样。
+
+代理循环发出三种跨度类型：
+
+| 跨度        | 何时             | 属性                                                              |
+| ----------- | ---------------- | ----------------------------------------------------------------- |
+| `agent.run` | 每个代理运行一次 | `agent.run_id`, `agent.thread_id`, `agent.user_id`, `agent.model` |
+| `tool.call` | 每次操作调用一次 | `tool.name`，加上成功/错误状态                                    |
+| `llm.call`  | 每个模型调用     | 计时+正常/错误状态                                                |
+
+跨度以 OK/ERROR 状态完成，并记录失败时的错误消息。零/哨兵属性值被修剪，因此跨度不会因噪音而混乱。该 OTel 层纯粹是对内部 `agent_trace_spans` / `agent_trace_summaries` 表的补充，这些表为上面的仪表板提供支持 - 两者都是由相同的运行事件生成的。
+
+## 错误报告（Sentry） {#sentry}
+
+配置 DSN 时，转义 Nitro 路由处理程序的服务器端错误将报告给 Sentry。如果没有它，SDK 会默默地无操作，因此可以安全地在开发中保留环境变量未设置。浏览器和服务器事件可以去同一个Sentry项目；仅当您希望所有权、数量、配额或警报路由的操作分离时，才将它们拆分为单独的项目。
+
+| 表面               | SDK               | 环境变量                                                      | 注释                                                  |
+| ------------------ | ----------------- | ------------------------------------------------------------- | ----------------------------------------------------- |
+| 浏览器/SPA         | `@sentry/browser` | `VITE_SENTRY_CLIENT_DSN`、`SENTRY_CLIENT_DSN` 或 `SENTRY_DSN` | 捕获客户端中未处理的错误和路由更改面包屑。            |
+| Nitro服务器        | `@sentry/node`    | `SENTRY_SERVER_DSN`或`SENTRY_DSN`                             | 捕获 5xx 响应和 Nitro 生命周期错误。每个请求的用户。  |
+| `agent-native` CLI | `@sentry/node`    | _硬编码_                                                      | 来自已发布的 CLI 二进制文件的崩溃报告；用户不可配置。 |
+
+### 服务器端配置 {#sentry-config}
+
+在部署环境（Netlify 仪表板、Cloudflare 机密等）中设置 `SENTRY_SERVER_DSN` 或共享 `SENTRY_DSN`。该框架自动安装 Nitro 插件：
+
+1. 启动时调用 `Sentry.init` 一次（幂等 - 可以安全地从多个插件调用）。
+2. 通过 `getSession(event)` 对每个 API/框架请求解析用户，并将 `id` / `email` / `username` 加上 `orgId` 标签附加到 Sentry 的每个请求隔离范围。跳过静态资产路径以避免额外的数据库命中。
+3. 使用可搜索的 `route`、`method` 和 `userAgent` 标签捕获每个框架路由 5xx。
+
+可选旋钮：
+
+- `SENTRY_SERVER_TRACES_SAMPLE_RATE`（浮点 `0`–`1`）— 选择加入性能跟踪。默认为 `0`（仅限错误）。无效值限制为 `0`。
+- `AGENT_NATIVE_RELEASE` — 覆盖 `release` 标签。默认为 `agent-native-server@<core-version>`。
+
+### 模板
+
+每个模板都会自动继承它——无需导入任何内容。对于 SSR 应用程序，当 `SENTRY_CLIENT_DSN`、`VITE_SENTRY_CLIENT_DSN` 或共享 `SENTRY_DSN` 在运行时可用时，服务器会注入一个小型浏览器配置脚本，因此浏览器捕获不限于 Vite 构建时环境。想要自定义行为的模板（额外标签、每个模板不同的 DSN、硬禁用 Sentry）可以通过从 `server/plugins/sentry.ts` 导出自己的插件来覆盖：
+
+```ts
+// server/plugins/sentry.ts
+import { createSentryPlugin } from "@agent-native/core/server";
+export default createSentryPlugin();
+```
+
+CLI 的硬编码 DSN 是有意为之的 - 发布的二进制文件需要通知家庭崩溃，无论运行它的环境如何。服务器模块从不硬编码 DSN，因为它在客户环境中运行，操作员决定错误是否应该到达 Sentry。
+
+### 隐私和 PII {#privacy}
+
+服务器和 CLI 都使用 `sendDefaultPii: false` 和剥离的 `beforeSend` 钩子进行初始化：
+
+- `request.headers.authorization`, `cookie`, `set-cookie`, `proxy-authorization`
+- `request.cookies`
+- `user.ip_address`（未经同意自动收集）
+- `contexts.runtime_env`（进程环境快照）
+- 顶级异常类型为 `ValidationError` 的任何事件（被视为预期的用户输入拒绝，而不是错误）。
+
+通过 `setUser({ id, email, username })` 显式设置的身份字段将被保留。
+
+## 下一步是什么
+
+- [**Tracking**](/docs/tracking) - 针对您的应用自身事件的产品分析（PostHog、Mixpanel、Amplitude）
+- [**Actions**](/docs/actions) - 在跟踪中显示为工具调用的操作
+- [**Security**](/docs/security) — 数据范围和凭证处理

package/docs/content/locales/zh-CN/observational-memory.md

@@ -0,0 +1,77 @@
+---
+title: "观察记忆"
+description: "后台三层压缩（最近的原始→观察→反射），使长代理线程保持廉价且提示缓存稳定，而无需触及短对话。"
+---
+
+# 观察记忆
+
+长时间运行的代理线程会积累巨大的记录：每条消息、每个工具调用、每个结果。每回合将整个历史记录重播到模型中的成本很高，并且最终会破坏上下文窗口。 **观察记忆 (OM)** 将长线程的较旧部分压缩为过时的分层摘要，因此模型仍然知道发生了什么 - 只需令牌成本的一小部分 - 而最近的回合则保持逐字记录。
+
+OM 是完全自动的且仅限于所有者范围。 **短线程不受影响**：在线程跨越第一个压缩阈值之前，OM 是无操作的，并且上下文是逐字节的，没有它时的情况。
+
+## 三层 {#tiers}
+
+OM 将长线程表示为三层，从最精炼到最近：
+
+| 层级               | 它是什么                                                                    |
+| ------------------ | --------------------------------------------------------------------------- |
+| **思考**           | 最高级别，由观察日志变大后浓缩而成。长弧总结。                              |
+| **观察**           | 密集、过时的条目将一段原始消息折叠成所发生事件的紧凑记录。                  |
+| **最近的原始消息** | 最后 N 个回合，**逐字**保存 — 从未折叠 — 因此代理始终可以看到最新的上下文。 |
+
+```an-diagram title="Three tiers, distilled to recent" summary="The older prefix folds into dated observations and a long-arc reflection; only the most recent turns stay verbatim."
+{
+  "html": "<div class=\"om\"><div class=\"diagram-card\"><span class=\"diagram-pill\">Reflections</span><small class=\"diagram-muted\">long-arc summary, condensed from the observation log</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&uarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Observations</span><small class=\"diagram-muted\">dense, dated entries folding stretches of raw messages</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&uarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill ok\">Recent raw messages</span><small class=\"diagram-muted\">last N turns, kept <strong>verbatim</strong> — never folded</small></div></div>",
+  "css": ".om{display:flex;flex-direction:column-reverse;align-items:stretch;gap:8px}.om .diagram-card{display:flex;flex-direction:column;gap:4px;padding:12px 16px}.om .diagram-arrow{text-align:center;font-size:20px;line-height:1}"
+}
+```
+
+在每一轮中，读取端将它们组装成一个自标记的 `[Observational Memory]` 块，该块替换原始的较旧前缀，保持最近原始窗口完整，并告诉模型将压缩记录视为权威（不要重做已完成的工作，信任记录的决策、名称、日期和状态）。
+
+## 压缩如何运行 {#compaction}
+
+两次传递以“即发即忘、尽力而为”的方式运行，在一次干净的转弯之后，因此它们不会给用户可见的响应增加延迟，并且任何失败都会被吞掉：
+
+1. **观察者** - 一旦线程的*unobserved*消息超过观察标记阈值，将它们折叠成单个密集观察条目。
+2. **Reflector** — 一旦持久观察日志本身超过反射令牌阈值，就会将观察结果压缩为更高级别的反射。
+
+```an-diagram title="Two best-effort passes after a clean turn" summary="Each pass no-ops below its threshold, so running the compactor every turn is cheap. Failures are swallowed and never add latency."
+{
+  "html": "<div class=\"om-pass\"><div class=\"diagram-node\">Clean turn ends<br><small class=\"diagram-muted\">fire-and-forget</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Observer</span><small class=\"diagram-muted\">unobserved tokens &gt; 30k? &rarr; fold into one observation</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Reflector</span><small class=\"diagram-muted\">observation log &gt; 40k? &rarr; condense into a reflection</small></div></div>",
+  "css": ".om-pass{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.om-pass .diagram-node,.om-pass .diagram-card{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.om-pass .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+两者都通过低于其阈值的无操作，因此在每轮之后调用压缩器是便宜的。由于 OM 用稳定的压缩文本替换了易失的原始前缀，因此它还可以在长线程的轮流中保持提示**缓存稳定**。
+
+OM 数据存在于应用程序自己的 SQL 数据库中，其范围仅限于所有者（以及存在的组织）——与框架的其余部分具有相同的范围模型。它永远不会在用户之间共享。
+
+## 配置 {#config}
+
+默认值是保守的。操作员可以在部署时使用 `AGENT_NATIVE_OM_*` 环境变量进行压缩（无需重新部署应用程序代码）；无效或缺失的值始终会回退到指定的默认值。
+
+| 环境变量                                      | 默认    | 它控制什么                                           |
+| --------------------------------------------- | ------- | ---------------------------------------------------- |
+| `AGENT_NATIVE_OM_OBSERVATION_TOKEN_THRESHOLD` | `30000` | 未观察到的消息标记，触发观察者将它们折叠成一个观察。 |
+| `AGENT_NATIVE_OM_REFLECTION_TOKEN_THRESHOLD`  | `40000` | 触发反射器凝结成反射的观察日志标记。                 |
+| `AGENT_NATIVE_OM_RECENT_RAW_MESSAGE_COUNT`    | `12`    | 有多少最新消息会逐字保留（从未合并到观察中）。       |
+
+观察者和反射器输出上限（4000 / 2000 代币）可防止单次压缩传递超出预算；它们可以通过 `resolveObservationalMemoryConfig({ ... })` 在代码中进行调整，但不能暴露在环境中。
+
+> [!TIP]
+> 降低阈值以更快地压缩（更便宜的长线程，稍微更多的摘要）；在压缩之前提高它们以在上下文中保留更多原始历史记录。如果您的工作流程需要更长的逐字尾部，请将 `AGENT_NATIVE_OM_RECENT_RAW_MESSAGE_COUNT` 设置得更高。
+
+## 当它开始时 {#when}
+
+OM 仅更改足够长的线程的行为，以产生至少一个观察或反射。具体来说：
+
+- 一个全新的或短的线程：还没有 OM 条目 → 上下文是纯文本，未更改。
+- 长线程已超过观察阈值：较旧的前缀被压缩的 `[Observational Memory]` 块替换，最近的原始尾部保持原样，并且令牌使用量大幅下降。
+
+注入是尽力而为且边界安全的 - 如果找不到安全调整点（例如，待处理的工具使用/结果对位于窗口边缘），OM 将*附加*注入内存块而不进行调整，而不是冒险丢弃待处理的工具结果。
+
+## 相关
+
+- [**Using Your Agent**](/docs/using-your-agent) — 与停靠在您的应用旁边的代理一起工作的日常循环。
+- [**Observability**](/docs/observability) — 每次运行的令牌和成本指标，其中显示 OM 的节省。
+- [**Custom Agents & Teams**](/docs/agent-teams) - 长子代理运行受益于相同的压缩。

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

@@ -0,0 +1,216 @@
+---
+title: "入门和 API 密钥"
+description: "首次运行配置的设置清单 - API 密钥、OAuth 和提供商连接"
+---
+
+# 入职
+
+当您第一次打开基于代理本机框架构建的应用程序时，您会看到
+代理侧栏中的**设置**清单。它使首次运行配置保持关闭
+到代理聊天：连接人工智能引擎，可选择将应用程序指向共享
+基础设施，仅在需要时添加提供程序。
+
+```an-diagram title="The setup checklist" summary="Only Connect an AI engine is required. The panel tracks completion and auto-hides once everything required is done."
+{
+  "html": "<div class=\"ob\"><div class=\"diagram-card\"><span class=\"diagram-pill warn\">required</span><strong>Connect an AI engine</strong><small class=\"diagram-muted\">Connect Builder (one click) or paste an LLM key</small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">optional</span><strong>Database</strong><small class=\"diagram-muted\">set <code>DATABASE_URL</code></small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">optional</span><strong>Authentication</strong><small class=\"diagram-muted\">OAuth / access token</small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">optional</span><strong>Email delivery</strong><small class=\"diagram-muted\">Resend / SendGrid</small></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box ok\">all required done &rarr; panel auto-hides</div></div>",
+  "css": ".ob{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.ob .diagram-card{display:flex;flex-direction:column;gap:3px;padding:12px 14px}.ob .diagram-arrow{font-size:22px}"
+}
+```
+
+## 对于最终用户
+
+### 您将看到什么
+
+- 代理聊天上方的 **设置** 面板，其中包含“连接 AI”等清单
+  引擎”、“电子邮件传送”等
+- 顶部的计数器（例如“1 of 4”）显示已准备好多少步。
+- 当前步骤已展开；完成的步骤显示绿色勾号并停留
+  打开它们即可读取。
+- 所需步骤显示一个红色的**所需**小药丸。面板保持可见
+  直到完成所有必需的步骤。
+- 完成所需的所有操作后，面板会自动隐藏。
+- 整个面板可以折叠，并带有右上角的 V 形图标，或者
+  通过底部的**隐藏设置**完全隐藏。
+
+### 如何完成每个步骤
+
+步骤提供一种或多种**方法** - 满足相同要求的不同方法
+要求。首先显示主要路径；辅助路径保持紧凑
+当一个步骤有多个等效提供者时，在选择器或披露后面。
+
+- **连接服务（一键点击）** — 例如*连接 Builder* 进行托管
+  人工智能网关。单击按钮，打开一个窗口，您登录，窗口关闭，
+  并且该步骤被标记为完成。没有要复制的密钥。
+- **粘贴 API 密钥或填写表格** - 例如选择 LLM 提供商、数据库，
+  OAuth 提供商或电子邮件提供商，粘贴值，然后单击 **保存**。
+  秘密字段使用密码输入，因此该值不会显示在屏幕上。已保存
+  值进入您的本地 `.env`（或工作区设置） - 请参阅
+  [Security](/docs/security) 表示他们居住的地方。
+- **打开链接** — 某些步骤指向登录页面或文档。点击
+  **继续**并在新选项卡中完成流程。
+- **询问代理** — 只需几个步骤即可提供“让代理进行设置”选项。
+  点击它，客服人员会在聊天中接听，引导您完成任何操作
+  外部设置（创建 OAuth 凭证等）。
+
+### 您通常会看到的内置步骤
+
+- **连接人工智能引擎**（必需）——唯一的强制步骤。连接
+  Builder 用于一键托管网关，或打开辅助提供商密钥
+  选择并粘贴您自己的 LLM 密钥。
+- **数据库**（可选）- 当您想使用特定时设置 `DATABASE_URL`
+  SQL 数据库连接字符串。
+- **身份验证**（可选）- 内置电子邮件/密码帐户的工作方式
+  默认。仅当您需要这些路径时才添加 OAuth 或访问令牌登录。
+- **电子邮件传送**（可选）- 在部署之前用于密码重置很有用，
+  团队邀请和共享通知。使用您已经使用的提供商；
+  本地开发可以在没有它的情况下运行。
+
+模板可以在这些之上添加自己的步骤 - 例如CRM 模板可能
+添加“连接 Gmail”，文档模板可能会添加“选择默认工作区”。请参阅
+[Authentication](/docs/authentication) 用于登录设置详细信息。
+
+### 回到清单
+
+如果您点击**隐藏设置**，该浏览器会话的面板就会消失。
+尚未完成的所需步骤将在下次加载时再次出现。一次
+所需的一切都已完成，面板会自动隐藏 - 什么也没有
+剩下要做的事。
+
+## 对于开发者
+
+如果您正在构建模板，则需要注册入门步骤，以便它们显示在
+用户的侧边栏清单。框架处理渲染、完成
+跟踪和解雇 - 您只需声明步骤是什么以及如何进行
+满意。
+
+系统是**自动安装**的。模板不需要连接任何东西即可获取
+四个内置步骤（LLM、数据库、身份验证、电子邮件）。添加特定于应用程序的
+steps (Gmail, Slack, Notion, etc.), call `registerOnboardingStep()` from a
+服务器插件。
+
+### 自动安装路线
+
+所有路线均位于 `/_agent-native/onboarding/` 下：
+
+| 路线                                                | 目的                      |
+| --------------------------------------------------- | ------------------------- |
+| `GET /_agent-native/onboarding/steps`               | 列出步骤及完成状态        |
+| `POST /_agent-native/onboarding/steps/:id/complete` | 标记步骤完成（覆盖）      |
+| `POST /_agent-native/onboarding/dismiss`            | 关闭入门横幅              |
+| `POST /_agent-native/onboarding/reopen`             | 明确解雇（重新显示面板）  |
+| `GET /_agent-native/onboarding/dismissed`           | 读取解雇+ allComplete标志 |
+
+```an-api title="List onboarding steps"
+{
+  "method": "GET",
+  "path": "/_agent-native/onboarding/steps",
+  "summary": "List all registered steps with their completion status",
+  "description": "Drives the sidebar checklist — returns each step's id, title, methods, required flag, and whether `isComplete` currently passes.",
+  "responses": [
+    { "status": "200", "description": "Array of steps with completion status for the current user/app." }
+  ]
+}
+```
+
+### 从模板添加步骤
+
+```an-annotated-code title="Registering a custom onboarding step"
+{
+  "filename": "server/plugins/my-onboarding.ts",
+  "language": "ts",
+  "code": "import { defineNitroPlugin } from \"@agent-native/core/server\";\nimport { registerOnboardingStep } from \"@agent-native/core/onboarding\";\nimport { listOAuthAccounts } from \"@agent-native/core/oauth-tokens\";\n\nexport default defineNitroPlugin(() => {\n  registerOnboardingStep({\n    id: \"gmail\",\n    order: 100,\n    title: \"Connect Gmail\",\n    description: \"Grant read/send access so the agent can work with email.\",\n    methods: [\n      {\n        id: \"oauth\",\n        kind: \"link\",\n        primary: true,\n        label: \"Sign in with Google\",\n        payload: { url: \"/_agent-native/google/auth-url?scope=mail\", external: false },\n      },\n      {\n        id: \"delegate\",\n        kind: \"agent-task\",\n        label: \"Let the agent set it up\",\n        badge: \"beta\",\n        payload: { prompt: \"Walk me through connecting Gmail. Set env vars as needed.\" },\n      },\n    ],\n    isComplete: async () => {\n      const accounts = await listOAuthAccounts(\"google\");\n      return accounts.length > 0;\n    },\n  });\n});",
+  "annotations": [
+    { "lines": "5", "label": "Auto-mounted", "note": "Register from a Nitro plugin — the framework handles rendering, completion tracking, and dismissal." },
+    { "lines": "7", "label": "Stable id", "note": "Re-registering with the same `id` after defaults load overrides a built-in step." },
+    { "lines": "12-19", "label": "Primary method", "note": "`primary: true` marks the big CTA. `kind: \"link\"` sends the user into the OAuth flow." },
+    { "lines": "20-26", "label": "Delegate path", "note": "`kind: \"agent-task\"` hands the setup to the agent chat with a prompt." },
+    { "lines": "28-31", "label": "Completion check", "note": "`isComplete` runs server-side. OAuth tokens live in the `oauth_tokens` store — check it, not `process.env.GMAIL_REFRESH_TOKEN`." }
+  ]
+}
+```
+
+### 在入职检查中检查工作区连接
+
+构建与外部服务（例如 Slack、Google Workspace、GitHub 或 HubSpot）交互的模板时，您应该检查工作区是否已连接并授予该提供商与您的应用的连接。当存在中央托管连接时，这可以防止用户在本地环境变量中复制凭据（例如 API 密钥或刷新令牌）。
+
+您可以使用连接目录 APIs 在 `isComplete` 回调中检查连接准备情况：
+
+```ts
+import { listWorkspaceConnectionProviderCatalogForApp } from "@agent-native/core/workspace-connections";
+
+// Inside registerOnboardingStep:
+isComplete: async () => {
+  // Check if a managed workspace connection exists and is ready
+  const catalog = await listWorkspaceConnectionProviderCatalogForApp({
+    appId: "mail",
+    templateUse: "mail",
+    provider: "gmail",
+  });
+  const connection = catalog.providers[0];
+
+  if (
+    connection?.readiness.status === "ready" &&
+    connection.workspaceConnection.grantState === "granted"
+  ) {
+    return true;
+  }
+
+  // Fall back to local environment variable check
+  return !!process.env.GMAIL_REFRESH_TOKEN;
+};
+```
+
+请参阅 [Workspace Connections](/docs/workspace-connections) 文档，了解连接提供程序目录方法的完整列表。
+
+### 方法种类
+
+| 种类               | 有效负载                                              | 用于                                   |
+| ------------------ | ----------------------------------------------------- | -------------------------------------- |
+| `link`             | `{ url, external? }`                                  | 将用户发送到 OAuth 流程或文档页面      |
+| `form`             | `{ fields, writeScope? }`                             | 收集环境变量（密钥、秘密、URL）        |
+| `builder-cli-auth` | `{ scope: "llm" \| "browser" \| "image-generation" }` | Connect Builder (unlocks shared infra) |
+| `agent-task`       | `{ prompt }`                                          | 向客服聊天发送提示进行处理             |
+
+`primary: true` 标志将方法标记为其步骤的大 CTA。
+当设置路径应该可见时，使用 `badge: "soon"` 和 `disabled: true`
+在可用之前。
+
+### 内置步骤
+
+| ID         | 必填 | 描述                                 |
+| ---------- | ---- | ------------------------------------ |
+| `llm`      | 是的 | Builder 连接或提供商 LLM 密钥        |
+| `database` | 没有 | 默认数据库或任何SQL `DATABASE_URL`   |
+| `auth`     | 没有 | 内置帐户，可选 OAuth 或访问令牌      |
+| `email`    | 不   | 重新发送或 SendGrid 用于交易电子邮件 |
+
+任何这些都可以通过在之后使用相同的 `id` 重新注册来覆盖
+默认加载。
+
+### 客户端使用
+
+面板已位于 `<AgentPanel>` 内部。要构建自定义布局：
+
+```tsx
+import {
+  OnboardingPanel,
+  OnboardingBanner,
+  useOnboarding,
+} from "@agent-native/core/client/onboarding";
+
+function MySidebar() {
+  const { allComplete, dismissed, currentStepId } = useOnboarding();
+  if (allComplete || dismissed) return <Chat />;
+  return (
+    <>
+      <OnboardingPanel />
+      <Chat />
+    </>
+  );
+}
+```
+
+有关步骤值存储位置以及如何处理机密的背景信息，
+参见 [Security](/docs/security)。对于最终用户消息传递接触点（邀请，
+密码重置）取决于**电子邮件传送**步骤，请参阅
+[Messaging](/docs/messaging).