@agent-native/core 0.79.2 → 0.79.6

package/corpus/core/docs/content/locales/zh-TW/processors.md

@@ -0,0 +1,106 @@
+---
+title: "環內處理器"
+description: "循環內部觀察者/護欄掛鉤，用於監視模型的流輸出和工具在執行中調用並可以中止它 - 實時護欄和完成證明門的接縫。"
+---
+
+# 循環處理器
+
+`Processor` 是代理執行的循環內部**觀察者/護欄**。它監視模型的流式輸出，工具在執行過程中調用它的請求，保持其自己的臨時狀態，並且可以在聲明“完成”之前**中止**執行。這是實時護欄（阻止中流不允許的輸出）和完成證明/覆蓋門（檢查模型將要做什么並停止它）的結構先決條件。
+
+```an-diagram title="三個鉤子在奔跑中開火的地方" summary="processOutputStream 監視每個塊，processOutputStep 控制每個回應的工具調用，processOutputResult 在最後紀錄判決。任何鉤子都可以通過 TripWire 中止。"
+{
+  "html": "<div class=\"diagram-proc\"><div class=\"diagram-node\" data-rough>stream chunks<br><small class=\"diagram-muted\">processOutputStream</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\" data-rough>per model response<br><small class=\"diagram-muted\">processOutputStep — 攔截工具調用</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\" data-rough>run end<br><small class=\"diagram-muted\">processOutputResult — 判定</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-pill warn\">abort() &rarr; TripWire &rarr; tripwire event</div></div>",
+  "css": ".diagram-proc{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-proc .diagram-arrow{font-size:22px;line-height:1}.diagram-proc .diagram-pill{flex-basis:100%}"
+}
+```
+
+> [!WARNING]
+> 處理器是**設定**，不是工具，不是操作，也不是創作 DSL。處理器僅觀察、改變它們自己的流範圍狀態和 `abort()`。它們從不定義應用程式行為、替換 actions 或出現在模型中。應用程式操作屬於[actions](/docs/actions)。
+
+## 掛鉤 {#hooks}
+
+處理器實現三個可選生命週期掛鉤的任何子集（形狀借用自 Mastra 的輸出處理器）：
+
+| 鉤子                  | 著火了……                              | 用它來……                               |
+| --------------------- | ------------------------------------- | -------------------------------------- |
+| `processOutputStream` | 模型生成時的每個流塊（文本/思維增量） | 在整輪落地之前對輸出做出反應           |
+| `processOutputStep`   | 每個模型回應一次，圍繞工具執行        | 檢查模型即將執行的工具調用；給他們設門 |
+| `processOutputResult` | 在執行結束時，帶有最終的輔助文本      | 紀錄對已完成答案的判決/完成證明        |
+
+每個處理器都有自己的可變的、執行範圍的 `state` 物件，該物件在單次執行中的每個鉤子調用中持續存在，並且與其他處理器的狀態**隔離**。
+
+```ts
+import type { Processor } from "@agent-native/core";
+
+const noSecretsInOutput: Processor = {
+  name: "no-secrets",
+  processOutputStream({ part, abort }) {
+    if (part.type === "text" && /sk-live_/.test(part.text)) {
+      abort("Model attempted to emit a live secret token.", {
+        kind: "secret-leak",
+      });
+    }
+  },
+};
+
+const coverageGate: Processor = {
+  name: "proof-of-done",
+  processOutputStep({ toolCalls, state }) {
+    // Track what the model has actually done this run...
+    for (const call of toolCalls) {
+      (state.ran ??= new Set<string>()).add(call.name);
+    }
+  },
+  processOutputResult({ text, state }) {
+    // ...and record a verdict over the final answer.
+    const ran = state.ran as Set<string> | undefined;
+    state.verdict = ran?.has("run-tests") ? "verified" : "unverified";
+  },
+};
+```
+
+## 使用 `TripWire` 中止 {#tripwire}
+
+掛鉤通過調用 `abort(reason, meta?)` 來停止執行，這會拋出 **`TripWire`**。循環捕獲它，發出單個 **`tripwire` 事件**，幹淨地停止，並將原因顯示為最終的輔助訊息。
+
+```ts
+import { TripWire } from "@agent-native/core";
+```
+
+`tripwire` 事件攜帶：
+
+| 欄位        | 型別     | 注釋                               |
+| ----------- | -------- | ---------------------------------- |
+| `reason`    | `string` | 人類可讀的原因傳遞給 `abort`。     |
+| `processor` | `string` | 聲明 `name` 時中止的處理器的名稱。 |
+
+`TripWire` 還帶有可選的結構化 `meta` 和原始 `processor` 名稱，供 `instanceof` 檢查的程序化消費者使用。由於暫停是正常的，`processOutputResult` 仍然會在（暫停的）最終文本上觸發，因此即使執行被中止，完成證明處理器也可以紀錄其結論。
+
+## 連線處理器 {#wiring}
+
+處理器通過 `runAgentLoop` 上的 `processors` 陣列在程式碼中進行設定：
+
+```ts
+await runAgentLoop({
+  engine,
+  model,
+  systemPrompt,
+  tools,
+  messages,
+  actions,
+  send,
+  signal,
+  processors: [noSecretsInOutput, coverageGate],
+});
+```
+
+**未使用時零開銷。**僅當提供至少一個處理器時，循環才會建置處理器鏈；當 `processors` 被省略或為空時，沒有任何接縫程式碼執行，並且循環逐字節不變。掛鉤按註冊順序執行，可以是同步的，也可以是非同步的。
+
+> [!NOTE]
+> 循環級接縫是今天的可交付成果，可由子代理、A2A、MCP 和測試直接調用。通過 HTTP 聊天處理程序線程化 `processors`（因此每個請求解析器可以在不直接調用 `runAgentLoop` 的情況下設定它們）是尚未連線的便利管道 - 現在在 `runAgentLoop` 調用站點設定處理器。
+
+## 相關
+
+- [**Durable Resume**](/docs/durable-resume) — 循環如何在中斷中幸存下來而不重新執行已完成的副作用。
+- [**Custom Agents & Teams**](/docs/agent-teams) - 子代理執行相同的循環並可以攜帶自己的處理器。
+- [**Observability**](/docs/observability) — 紀錄處理器判決以及執行跟蹤。

package/corpus/core/docs/content/locales/zh-TW/progress.md

@@ -0,0 +1,199 @@
+---
+title: "進度"
+description: "長時間執行的代理工作的實時進度信號 - 啟動、更新、完成"
+---
+
+# 進度
+
+長時間的代理工作不應隱藏在旋轉器後面。 `progress_runs` 為代理提供了一種方式來宣布 _“我正在處理此問題，已完成 45%，這是目前步驟”_ — UI 將其呈現為帶有百分比欄的浮動執行托盤。
+
+```ts
+import {
+  startRun,
+  updateRunProgress,
+  completeRun,
+} from "@agent-native/core/progress";
+
+const run = await startRun({
+  owner: "steve@builder.io",
+  title: "Triage 128 unread emails",
+  step: "Fetching inbox",
+});
+
+for (let i = 1; i <= total; i++) {
+  await updateRunProgress(run.id, run.owner, {
+    percent: Math.round((i / total) * 100),
+    step: `Classifying ${i}/${total}`,
+  });
+}
+
+await completeRun(run.id, run.owner, "succeeded");
+```
+
+與 [notifications](/docs/notifications) 不同的關注點：通知觸發一次（_“X 發生了”_），進度是連續狀態（_“X 已完成 45%”_）。這兩個組合 - `completeRun` 後跟 `notify(..., severity: "info")` 告訴使用者工作何時完成，即使他們沒有看托盤。
+
+## 生命週期 {#lifecycle}
+
+| 狀態        | 過渡                      |
+| ----------- | ------------------------- |
+| `running`   | 初始 — 由 `startRun` 設定 |
+| `succeeded` | 快樂路徑終端              |
+| `failed`    | 錯誤終端                  |
+| `cancelled` | 使用者中斷                |
+
+```an-diagram title="執行生命週期" summary="startRun 開啟一個執行行； updateRunProgress 修補它； completeRun 將其移至一種終端狀態並標記 completed_at。"
+{
+  "html": "<div class=\"diagram-run\"><div class=\"diagram-box\" data-rough>startRun()</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel running\" data-rough><span class=\"diagram-pill accent\">running</span><small class=\"diagram-muted\">updateRunProgress() &#8635; percent + step</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col terminal\"><span class=\"diagram-pill ok\">succeeded</span><span class=\"diagram-pill warn\">failed</span><span class=\"diagram-pill\">cancelled</span><small class=\"diagram-muted\">completeRun() &rarr; sets completed_at</small></div></div>",
+  "css": ".diagram-run{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-run .diagram-panel{display:flex;flex-direction:column;gap:6px;padding:12px 16px}.diagram-run .terminal{display:flex;flex-direction:column;gap:6px;align-items:flex-start}.diagram-run .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+終端狀態設定為 `completed_at`。 UI 托盤僅顯示 `running` 行；完成的行保留在資料庫中以供 `action=list` 查詢。
+
+## API {#api}
+
+### `startRun(input)` {#start}
+
+建立一個執行。返回帶有生成 ID 的完整 `AgentRun`。
+
+```ts
+const run = await startRun({
+  owner: "steve@builder.io",
+  title: "Ingest 1M rows",
+  step: "Opening CSV",
+  metadata: { jobId: "abc123", artifactPath: "s3://..." },
+});
+```
+
+在事件總線上發出 `run.progress.started`。
+
+### `updateRunProgress(id, owner, input)` {#update}
+
+修補正在執行的任何欄位。任何省略的欄位保持不變。
+
+```ts
+await updateRunProgress(run.id, run.owner, {
+  percent: 75,
+  step: "Writing to target DB",
+});
+```
+
+在事件總線上發出 `run.progress.updated`。返回更新的 `AgentRun`，如果執行不存在或不屬於調用者，則返回 `null`。
+
+### `completeRun(id, owner, status, extras?)` {#complete}
+
+轉換到終端狀態。 `succeeded` 隱式設定 `percent=100`。
+
+```ts
+await completeRun(run.id, run.owner, "succeeded", {
+  step: "All 1M rows ingested",
+  metadata: { totalDurationMs: 98_123 },
+});
+```
+
+還發出帶有終端狀態的 `run.progress.updated`。
+
+### 列表 {#list}
+
+```ts
+import { listRuns, getRun, deleteRun } from "@agent-native/core/progress";
+
+const active = await listRuns("steve@builder.io", { activeOnly: true });
+const run = await getRun("run-id", "steve@builder.io");
+await deleteRun("run-id", "steve@builder.io");
+```
+
+## HTTP API {#http}
+
+通過 core-routes 外掛安裝在 `/_agent-native/runs/*`。 **在 HTTP 上唯讀** — 寫入通過代理工具進行，因為代理是規範寫入者。所有路由都是所有者範圍內的。
+
+| 方法     | 路徑                              |
+| -------- | --------------------------------- |
+| `GET`    | `/_agent-native/runs?active=true` |
+| `GET`    | `/_agent-native/runs/:id`         |
+| `DELETE` | `/_agent-native/runs/:id`         |
+
+```an-api title="列出活動執行" method="GET" path="/_agent-native/runs"
+{
+  "method": "GET",
+  "path": "/_agent-native/runs",
+  "summary": "List the caller's runs. The RunsTray polls this with active=true.",
+  "description": "Read-only and owner-scoped — every row has an `owner` column and every query filters on it, so callers only ever see their own runs. Writes (start/update/complete) go through the agent's `manage-progress` tool, not HTTP.",
+  "auth": "Session cookie (owner-scoped)",
+  "params": [
+    { "name": "active", "in": "query", "type": "boolean", "required": false, "description": "When true, returns only `running` rows." }
+  ],
+  "responses": [
+    { "status": "200", "description": "Array of AgentRun rows owned by the caller." }
+  ]
+}
+```
+
+## UI元件 {#ui}
+
+```tsx
+import { RunsTray } from "@agent-native/core/client/progress";
+
+export function HeaderBar() {
+  return (
+    <header className="flex items-center gap-2">
+      {/* … */}
+      <RunsTray />
+    </header>
+  );
+}
+```
+
+內聯標題小部件 - 將其安裝在通知鈴旁邊。當跑步處於活動狀態時，顯示旋轉圖標 + 計數徽章；點選將開啟一個下拉選單，每次執行都會顯示一個實時百分比欄。當沒有活動執行時完全隱藏觸發器。每 `pollMs` 輪詢一次 `/_agent-native/runs?active=true`（預設 3 秒）。使用shadcn語義標記，適應淺色和深色主題。
+
+## 代理工具 {#agent-tool}
+
+每個範本中都會註冊一個 `manage-progress` 工具。 `action`參數選取操作：
+
+| 行動       | 目的                                             |
+| ---------- | ------------------------------------------------ |
+| `start`    | 在長工作的頂部調用。返回一個 runId。             |
+| `update`   | 在工作期間定期調用 `percent` 和/或 `step`。      |
+| `complete` | 終端 — `succeeded`、`failed`、`cancelled` 之一。 |
+| `list`     | 檢查最近的執行（按 `active=true` 過濾）。        |
+
+### 何時開始跑步 {#when-to-start}
+
+- 用於任何>~5秒的事情。沒有上下文的旋轉器感覺凍結。
+- 在自然檢查點更新，而不是每次迭代。每 5-10% 就足夠了。
+- **始終**使用 `action=complete` 調用 `manage-progress`，包括在錯誤路徑中。孤立的 `running` 行比沒有行更糟糕。
+- 完成後與 `notify` 配對，以便使用者在沒有主動觀看托盤時也能看到結果。
+
+## 事件總線 {#event-bus}
+
+[event bus](/docs/automations#event-bus) 上發出兩個事件：
+
+| 活動                   | 有效負載                           |
+| ---------------------- | ---------------------------------- |
+| `run.progress.started` | `{ runId, title, step? }`          |
+| `run.progress.updated` | `{ runId, percent, step, status }` |
+
+[Automations](/docs/automations) 可以訂閱這些內容 - 例如，_“如果跑步時間超過 5 分鐘，請通知我”_：
+
+```yaml
+---
+triggerType: event
+event: run.progress.updated
+condition: "status is failed"
+mode: agentic
+---
+通知 me that run {{runId}} has failed.
+```
+
+## 它是如何工作的 {#internals}
+
+- **所有者範圍** — 每行都有一個 `owner` 列；每個查詢都會對其進行過濾。使用者只能看到自己的跑步。
+- **輪詢整合** - 每個突變都會調用 `recordChange()`，因此使用 [`useDbSync`](/docs/client) 的範本會自動失效，無需任何額外的接線。
+- **表名稱** — 該框架還有一個 `agent_runs` 表，用於內部代理聊天回合生命週期跟蹤。進度原語使用 `progress_runs` 將兩個關注點分開。
+- **百分比限制** — 值被限制為 `[0, 100]` 並在寫入時四舍五入為整數。
+
+## 下一步是什么
+
+- [**Notifications**](/docs/notifications) — 與 `manage-progress` (`action=complete`) 配對，告訴使用者工作何時完成
+- [**Automations**](/docs/automations) — 看門狗通過 `run.progress.updated` 緩慢執行
+- [**Client**](/docs/client) — `useDbSync` 用於實時快取失效

package/corpus/core/docs/content/locales/zh-TW/pure-agent-apps.md

@@ -0,0 +1,39 @@
+---
+title: "純代理應用"
+description: "代理是整個產品的應用程式：應用程式代理循環是前門，僅在人們需要時才新增 UI。"
+---
+
+# 純代理應用
+
+純代理應用程式是代理本機的最小端：應用程式代理循環是
+產品，而不是儀表板。您從終端、Slack、電子郵件、
+預定的工作、另一個代理或聊天 - “總結我未讀的電子郵件”、“發布
+每日指標為 Slack” - 代理會在任何地方執行操作並返回結果
+屬於。它仍然是一個真實的應用程式：actions、工作階段、應用程式狀態、歷史紀錄，
+設定、憑證和共用紀錄均位於 SQL 中。
+
+```an-diagram title="應用程式代理循環是前門" summary="許多入口點通過 SQL-backed 操作和狀態到達一個代理循環；結果返回到請求來自的地方。僅當需要人類監督時才新增 UI。"
+{
+  "html": "<div class=\"diagram-pure\"><div class=\"diagram-col\"><div class=\"diagram-pill\">Terminal</div><div class=\"diagram-pill\">Slack · 郵件</div><div class=\"diagram-pill\">定時工作</div><div class=\"diagram-pill\">Another agent (A2A)</div><div class=\"diagram-pill\">Chat</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\">應用代理循環</span><small class=\"diagram-muted\">操作 · 工作階段 · SQL 中的應用狀態</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>結果返回<br><small class=\"diagram-muted\">to where it belongs</small></div></div>",
+  "css": ".diagram-pure{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-pure .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-pure .diagram-arrow{font-size:22px;line-height:1}.diagram-pure .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+當工作在後台執行時，達到此形狀，輸出離開
+應用程式，域是一次性的，或者您正在制作原型。代理仍然需要 UI —
+不是儀表板，而是人類監督、設定和引導它的地方 -
+這就是為什么即使是純代理應用程式通常也會安裝內置的 Chat shell。
+
+這是**無頭**產品形狀。完整的決策指南，包含哪些內容
+盒子、腳手架、儲存庫存取和執行共用現在位於一個地方：
+
+→ [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
+
+## 下一步是什么
+
+- [**Agent Surfaces — Headless**](/docs/agent-surfaces#headless) — 完整的無頭決策指南和 API
+- [**Getting Started**](/docs/getting-started) - 首先建立聊天應用程式或無頭代理
+- [**Dispatch**](/docs/template-dispatch) — 工作區範本是一個很好的純代理起點
+- [**Messaging the agent**](/docs/messaging) — 使用者如何通過網路、Slack、電報、電子郵件與代理交談
+- [**Recurring Jobs**](/docs/recurring-jobs) — 代理自行執行的預定提示
+- [**Actions**](/docs/actions) - 您的純代理將調用的工具