@agent-native/core 0.79.2 → 0.79.6

package/corpus/core/docs/content/locales/zh-TW/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="每次執行都會為循環提供動力" summary="一次代理執行會產生跟蹤、自動評分和意見回饋掛鉤 - 所有這些都存儲在應用程式自己的 SQL 中並顯示在儀表板上。實驗將流量分配給設定變體。"
+{
+  "html": "<div class=\"obs-loop\"><div class=\"diagram-node\">代理執行<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\">自動捕獲</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="一致哈希變體分配" summary="每個使用者散列到一個穩定的變體，循環應用該變體的設定覆蓋，並且結果以置信區間匯總每個變體。"
+{
+  "html": "<div class=\"exp\"><div class=\"diagram-node\">使用者 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\">設定覆蓋 A</small></div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">treatment &middot; 50%</span><small class=\"diagram-muted\">設定覆蓋 B</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">結果 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/corpus/core/docs/content/locales/zh-TW/observational-memory.md

@@ -0,0 +1,77 @@
+---
+title: "觀察記憶"
+description: "後台三層壓縮（最近的原始→觀察→反射），使長代理線程保持廉價且提示快取穩定，而無需觸及短對話。"
+---
+
+# 觀察記憶
+
+長時間執行的代理線程會積累巨大的紀錄：每條訊息、每個工具調用、每個結果。每回合將整個歷史紀錄重播到模型中的成本很高，並且最終會破壞上下文窗口。 **觀察記憶 (OM)** 將長線程的較舊部分壓縮為過時的分層摘要，因此模型仍然知道發生了什么 - 只需權杖成本的一小部分 - 而最近的回合則保持逐字紀錄。
+
+OM 是完全自動的且僅限於所有者範圍。 **短線程不受影響**：線上程跨越第一個壓縮閾值之前，OM 是無操作的，並且上下文是逐字節的，沒有它時的情況。
+
+## 三層 {#tiers}
+
+OM 將長線程表示為三層，從最精煉到最近：
+
+| 層級               | 它是什么                                                                    |
+| ------------------ | --------------------------------------------------------------------------- |
+| **思考**           | 最高級別，由觀察記錄變大後濃縮而成。長弧總結。                              |
+| **觀察**           | 密集、過時的條目將一段原始訊息折疊成所發生事件的緊湊紀錄。                  |
+| **最近的原始訊息** | 最後 N 個回合，**逐字**儲存 — 從未折疊 — 因此代理始終可以看到最新的上下文。 |
+
+```an-diagram title="三層，提煉到最近" summary="較舊的前綴折疊成過時的觀察結果和長弧反射；只有最近的輪次才保留原樣。"
+{
+  "html": "<div class=\"om\"><div class=\"diagram-card\"><span class=\"diagram-pill\">反思</span><small class=\"diagram-muted\">從觀察記錄濃縮出的長期摘要</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&uarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">觀察</span><small class=\"diagram-muted\">帶日期的密集條目，折疊多段原始訊息</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&uarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill ok\">最近的原始訊息</span><small class=\"diagram-muted\">last N turns, kept <strong>verbatim</strong> — 永不折疊</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="幹淨利落的轉彎後兩次盡力傳球" summary="每次傳遞都不會低於其閾值，因此每輪執行壓縮器都很便宜。故障會被吞掉，並且不會增加延遲。"
+{
+  "html": "<div class=\"om-pass\"><div class=\"diagram-node\">幹淨回合結束<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/corpus/core/docs/content/locales/zh-TW/onboarding.md

@@ -0,0 +1,216 @@
+---
+title: "入門和 API 金鑰"
+description: "首次執行設定的設定清單 - API 金鑰、OAuth 和提供者連線"
+---
+
+# 入職
+
+當您第一次開啟基於代理本機框架建置的應用程式時，您會看到
+代理側欄中的**設定**清單。它使首次執行設定保持關閉
+到代理聊天：連線人工智能引擎，可選取將應用程式指向共用
+基礎設施，僅在需要時新增提供程序。
+
+```an-diagram title="設定清單" summary="只需要連線一個AI引擎。該面板會跟蹤完成情況，並在完成所需的所有操作後自動隱藏。"
+{
+  "html": "<div class=\"ob\"><div class=\"diagram-card\"><span class=\"diagram-pill warn\">required</span><strong>連線 AI 引擎</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>郵件投遞</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="列出入職步驟"
+{
+  "method": "GET",
+  "path": "/_agent-native/onboarding/steps",
+  "summary": "列出所有已註冊的步驟及其完成狀態",
+  "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="註冊自訂入門步驟"
+{
+  "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": "自動安裝", "note": "從 Nitro 外掛註冊 - 該框架處理渲染、完成跟蹤和解除。" },
+    { "lines": "7", "label": "穩定ID", "note": "預設載入後使用相同的 `id` 重新註冊會覆蓋內置步驟。" },
+    { "lines": "12-19", "label": "主要方法", "note": "`primary: true` marks the big CTA. `kind: \"link\"` sends the user into the OAuth flow." },
+    { "lines": "20-26", "label": "委托路徑", "note": "`kind: \"agent-task\"` hands the setup to the agent chat with a prompt." },
+    { "lines": "28-31", "label": "竣工檢查", "note": "`isComplete` 在伺服器端執行。 OAuth 權杖位於 `oauth_tokens` 存儲中 - 檢查它，而不是 `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).