@agent-native/core 0.79.2 → 0.79.5

package/docs/content/locales/zh-TW/recurring-jobs.md

@@ -0,0 +1,142 @@
+---
+title: "重複性工作"
+description: "Cron 調度提示代理自行執行 - 每日摘要、每週報告、每小時輪詢。"
+---
+
+# 重複性工作
+
+**重複作業**是按 cron 計畫執行的提示。這就是代理自己做事的方式：“每天早上 7 點總結我隔夜收到的電子郵件”，“每週一將上週的註冊號碼發布到 Slack”，“每小時清理陳舊的草稿並將其刪除。”
+
+重複性工作按時進行。要對*事件*（建立的預訂、收到的電子郵件）做出反應 - 相同的 `jobs/` 檔案格式加上條件 - 請參閱 [Automations](/docs/automations)。
+
+作業位於 `jobs/<name>.md` 的 [workspace](/docs/workspace) 中 — 只是一個帶有 YAML frontmatter 的 Markdown 檔案。無需註冊，無需接線。將檔案放入，框架就會拾取它。
+
+## 作業檔案 {#job-file}
+
+```an-annotated-code title="jobs/morning-digest.md"
+{
+  "filename": "jobs/morning-digest.md",
+  "language": "markdown",
+  "code": "---\nschedule: \"0 7 * * *\"\nenabled: true\nrunAs: creator\n---\n\n# 早間摘要\n\n總結隔夜收到的電子郵件。按發件人域分組。\n將今天看起來需要回複的前 3 個線程固定到\n\"Needs reply\" 標籤。對任何顯而易見的問題草擬答複。",
+  "annotations": [
+    { "lines": "2", "label": "當", "note": "標準 5 欄位 cron — `0 7 * * *` 是每天 07:00。" },
+    { "lines": "3", "label": "暫停開關", "note": "Flip to `false` to stop the job without deleting it." },
+    { "lines": "4", "label": "身分", "note": "`creator` runs with the owner's identity and `ANTHROPIC_API_KEY`; `shared` uses the org's key." },
+    { "lines": "7-12", "label": "提示", "note": "主體只是一個提示 - 代理在每次觸發時使用其所有常規工具和工作區上下文執行它。" }
+  ]
+}
+```
+
+就是這樣。內文是代理在每次計畫觸發時執行的提示。代理可以存取其在互動式聊天中擁有的所有相同工具和工作區上下文 - actions、skills、內存、連線的 MCP 伺服器、子代理。
+
+## 前線 {#frontmatter}
+
+| 欄位         | 型別                          | 預設        | 描述                                                                                    |
+| ------------ | ----------------------------- | ----------- | --------------------------------------------------------------------------------------- |
+| `schedule`   | cron 表達式                   | _（必填）_  | 標準 5 欄位 cron。 `"0 7 * * *"` = 每天 07:00； `"0 */4 * * *"` = 每 4 小時一次。       |
+| `enabled`    | 布爾值                        | `true`      | 翻轉到 `false` 以暫停而不刪除作業。                                                     |
+| `runAs`      | `"creator"` \| `"shared"`     | `"creator"` | `"creator"` 以作業所有者的身分和 `ANTHROPIC_API_KEY` 執行。 `"shared"` 使用組織的金鑰。 |
+| `createdBy`  | 電子郵件                      | _（自動）_  | 當通過工作區 UI 或代理建立作業時填充。                                                  |
+| `orgId`      | 字串                          | _（自動）_  | 組織範圍；從建立者的活動組織繼承。                                                      |
+| `lastRun`    | ISO時間戳                     | _（託管）_  | 由調度程序在每次執行後寫入。                                                            |
+| `lastStatus` | `"success"` \| `"error"` \| … | _（託管）_  | 最新結果。                                                                              |
+| `lastError`  | 字串                          | _（託管）_  | 如果上次執行失敗，則會出現錯誤訊息。                                                    |
+| `nextRun`    | ISO時間戳                     | _（託管）_  | 由`schedule`計算得出；由調度程序用來決定下次何時觸發。                                  |
+
+`last*` 和 `nextRun` 欄位由調度程序寫入。您可以閱讀它們以檢視歷史紀錄，但不要手動編輯它們 - 下次執行將覆蓋它們。
+
+## cron 語法 {#cron}
+
+標準 5 欄位 cron（分鐘、小時、月份、月份、星期幾）：
+
+| 定時工作       | 含義           |
+| -------------- | -------------- |
+| `*/5 * * * *`  | 每 5 分鐘      |
+| `0 * * * *`    | 每小時整點     |
+| `0 */4 * * *`  | 每 4 小時一次  |
+| `0 7 * * *`    | 每天 07:00     |
+| `0 9 * * 1`    | 每週一 09:00   |
+| `0 17 * * 1-5` | 工作日 17:00   |
+| `0 0 1 * *`    | 每個月的第一天 |
+
+該框架包括用於驗證和呈現 cron 字串的 cron 實用程序（`isValidCron()` 和 `describeCron()`），由資源層和調度程序層在內部使用。
+
+## 建立作業 {#creating}
+
+### 從“工作區”分頁
+
+`+` → **工作區面板中的計畫工作**。填寫提示和時間表。另存為 `jobs/<slug>.md` 並在下一個匹配的刻度處開始執行。
+
+### 通過詢問代理
+
+> “建立一個計畫工作，每天早上 7 點總結我未讀的電子郵件。”
+
+代理會為您寫入檔案。
+
+### 手動
+
+通過框架的資源APIs將Markdown檔案拖放到`jobs/`中：
+
+```ts
+import { resourcePut } from "@agent-native/core/resources";
+
+await resourcePut(
+  ownerEmail,
+  "jobs/morning-digest.md",
+  `---
+schedule: "0 7 * * *"
+enabled: true
+---
+Summarize overnight emails.`,
+);
+```
+
+## 調度程序如何執行 {#how-scheduler-runs}
+
+調度程序是一個在進程中執行的框架外掛（內部 `processRecurringJobs()` 例程）：無論伺服器在何處執行，代理聊天外掛內的 `setInterval` 每 60 秒觸發一次（有 10 秒的啟動延遲）。
+
+```an-diagram title="一個調度程序勾選" summary="每 60 秒，調度程序就會找到到期的作業，將每個作業作為新的代理線程執行，並將結果寫回作業檔案。"
+{
+  "html": "<div class=\"sched\"><div class=\"diagram-box accent\"><code>setInterval</code> &bull; 60s &#8635;</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">1 &middot; scan</span><small class=\"diagram-muted\">list every enabled <code>jobs/*.md</code> across all owners</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">2 &middot; due?</span><small class=\"diagram-muted\">compare <code>nextRun</code> to now</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card accent\"><span class=\"diagram-pill accent\">3 &middot; run</span><small class=\"diagram-muted\">fresh agent thread, job body as the user message &mdash; actions, SQL, A2A, email</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card ok\"><span class=\"diagram-pill ok\">4 &middot; record</span><small class=\"diagram-muted\">write <code>lastRun</code> / <code>lastStatus</code> / <code>lastError</code>, recompute <code>nextRun</code></small></div></div>",
+  "css": ".sched{display:flex;flex-direction:column;gap:6px;max-width:520px}.sched .diagram-card{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.sched .diagram-box{align-self:flex-start}.sched .diagram-arrow{font-size:18px;align-self:center}"
+}
+```
+
+```an-callout
+{ "tone": "risk", "body": "**Scale-to-zero caveat.** The scheduler is in-process, so on serverless hosts jobs only fire while an instance is warm. If reliable scheduling matters, keep an instance warm with keep-alive pings or use an always-on host (Fly, Render, a VPS)." }
+```
+
+## 偵錯作業 {#debugging}
+
+- 在工作區中開啟 `jobs/<name>.md` — frontmatter 顯示 `lastRun`、`lastStatus`、`lastError`、`nextRun`。
+- **無需等待即可測試：**沒有強制發射工具。要按需執行相同的工作，可以將作業的提示貼上到代理聊天中並讓它在那裡執行，或者暫時將計畫設定為下一分鐘，以便調度程序在下一個時間點上選取它（然後恢復真正的 cron）。
+- **暫停：**翻轉`enabled: false`。檔案保持不變，只是停止執行。
+
+## 代理工具 {#agent-tool}
+
+每個範本中都會註冊一個 `manage-jobs` 工具。 `action`參數選取操作：
+
+| 行動     | 參數                                                            | 目的                                              |
+| -------- | --------------------------------------------------------------- | ------------------------------------------------- |
+| `create` | `name`、`schedule`、`instructions`（必填）； `scope`、`runAs`   | 建立新的定期作業                                  |
+| `list`   | `scope`（`personal`、`shared` 或全部）                          | 列出所有作業的狀態（計畫、已啟用、上次/下次執行） |
+| `update` | `name`（必填）； `schedule`、`instructions`、`enabled`、`runAs` | 編輯現有作業                                      |
+| `delete` | `name`（必填）                                                  | 刪除作業 - 始終先與使用者確認                     |
+
+**個人與共用範圍。**每個作業都位於個人範圍（作為建立者執行且僅對建立者可見）或共用/組織範圍（代表建立者執行但對組織成員可見）。 `scope` 和 `runAs` 參數在建立時對此進行控制。組織管理員可以更新或刪除任何共用作業；非管理員成員只能管理自己的成員。
+
+## 與調度包不同 {#vs-scheduling-package}
+
+不要將重複性作業與 `@agent-native/scheduling` 混淆：
+
+- **重複作業（本頁面）** — cron 計畫*提示*代理在後台執行。框架級別。住在工作區。在任何代理本機應用程式上執行。
+- **`@agent-native/scheduling`** — 用於建置行事曆/預訂功能（事件型別、可用窗口、預訂）的可重用域包。為 `calendar` 範本和自訂調度介面提供支持。
+
+重複性工作是“如何讓代理自行行動？”日程安排包是“如何建置行事曆應用程式？”不同的關注點。
+
+## 下一步是什么
+
+- [**Automations**](/docs/automations) — 將事件觸發器和條件新增到相同的 `jobs/` 格式
+- [**Workspace**](/docs/workspace) — 作業與 skills、內存和自訂代理一起存在
+- [**Actions**](/docs/actions) — 工作調用的工具
+- [**Agent Teams**](/docs/agent-teams) - 作業通常會產生子代理來執行並行工作

package/docs/content/locales/zh-TW/routing.md

@@ -0,0 +1,79 @@
+---
+title: "路由"
+description: "使用 React Router v8 為代理本機應用程式提供基於檔案的路由 - 頁面、動態參數和導覽。"
+---
+
+# 路由
+
+代理本機應用程式使用 **React Router v8** 以及通過來自 `@react-router/fs-routes` 的 `flatRoutes()` 的基於檔案的路由。 `app/routes/` 中的每個檔案都會變成 URL。範本使用點符號約定 - 點在單個檔案名內分隔 URL 段。
+
+## 基於檔案的路由 {#file-based-routing}
+
+### 檔案→URL對應
+
+| 檔案                  | URL                | 注釋                          |
+| --------------------- | ------------------ | ----------------------------- |
+| `_index.tsx`          | `/`                | 索引路線                      |
+| `settings.tsx`        | `/settings`        | 簡單頁面                      |
+| `inbox.$threadId.tsx` | `/inbox/:threadId` | 點 = `/`，`$` = 動態參數      |
+| `_app.tsx`            | （無 URL 段）      | 無路徑布局 - 前綴為 `_`       |
+| `inbox/route.tsx`     | `/inbox`           | 資料夾形式——`route.tsx`為索引 |
+
+為動態參數新增 `$` 前綴。以 `_` 為前綴，使其成為無路徑布局路線（無 URL 段）。範本使用 `flatRoutes()` — 上面的點符號檔案是主要的；嵌套資料夾形式 `inbox/route.tsx` 也適用。
+
+```an-diagram title="無路徑布局包裹頁面" summary="_app.tsx 布局（無 URL 段）渲染共用 shell 一次；匹配的頁面在其 <Outlet/> 內呈現，因此代理側邊欄永遠不會在導覽時重新安裝。"
+{
+"html": "<div class=\"diagram-layout\" data-rough><div class=\"diagram-shell\"><span class=\"diagram-pill accent\">_app.tsx</span><small class=\"diagram-muted\">無路徑布局 · 持久外殼 + Agent 側邊欄</small><div class=\"diagram-outlet\" data-rough><small class=\"diagram-muted\">&lt;Outlet/&gt; — the matched page</small><div class=\"diagram-row\"><span class=\"diagram-pill\">_index.tsx &rarr; /</span><span class=\"diagram-pill\">settings.tsx &rarr; /settings</span><span class=\"diagram-pill\">inbox.$threadId.tsx &rarr; /inbox/:threadId</span></div></div></div></div>",
+"css": ".diagram-layout .diagram-shell{display:flex;flex-direction:column;gap:8px;padding:16px}.diagram-layout .diagram-outlet{display:flex;flex-direction:column;gap:8px;padding:14px;margin-top:6px}.diagram-layout .diagram-row{display:flex;flex-wrap:wrap;gap:8px;margin-top:4px}"
+}
+
+```
+
+## 新增新頁面 {#adding-a-page}
+
+建立檔案並匯出預設元件：
+
+```tsx
+// app/routes/settings.tsx
+export function meta() {
+  return [{ title: "Settings" }];
+}
+
+export default function SettingsPage() {
+  return <div>Settings</div>;
+}
+```
+
+就是這樣 - React 路由器會自動選取它，無需註冊。
+
+## 動態參數 {#dynamic-params}
+
+```tsx
+// app/routes/inbox/$threadId.tsx
+import { useParams } from "react-router";
+
+export default function ThreadPage() {
+  const { threadId } = useParams();
+  return <div>Thread: {threadId}</div>;
+}
+```
+
+## 導覽 {#navigation}
+
+使用 `<Link>` 進行用戶端導覽，使用 `useNavigate()` 進行編程導覽：
+
+```tsx
+import { Link, useNavigate } from "react-router";
+
+// In JSX
+<Link to="/settings">Settings</Link>;
+
+// Programmatic
+const navigate = useNavigate();
+navigate(`/inbox/${threadId}`);
+```
+
+## 下一步是什么
+
+- [**Client**](/docs/client) - 代理本機瀏覽器掛鉤和實用程序
+- [**Server**](/docs/server) — 基於檔案的伺服器路由和 `/_agent-native/` 命名空間

package/docs/content/locales/zh-TW/sandbox-adapters.md

@@ -0,0 +1,227 @@
+---
+title: "適配器"
+description: "框架的兩個適配器接縫：沙箱適配器交換執行代理執行程式碼工具的後端，CLI適配器為代理提供對指令行工具的結構化存取。"
+search: "適配器沙箱適配器cli適配器執行程式碼SandboxAdapter CliAdapter ShellCliAdapter持久執行器遠端沙箱邊缘無伺服器child_process"
+---
+
+# 適配器
+
+> **這是誰的：**擴充功能執行時的主機作者。應用程式開發人員很少
+> 需要這個——預設值開箱即用。
+
+Agent-Native 有兩個適配器接縫，可消除狹窄後面的問題，
+可交換介面：
+
+- **沙盒適配器**交換執行代理的 `run-code` 工具的後端 -
+  預設為本機子進程，或 Docker/遠端/持久執行程序。
+- **CLI 適配器**為代理提供對指令行工具的結構化存取
+  （`gh`、`ffmpeg`、`stripe`），具有發現、可用性檢查和
+  一致的結果形狀。
+
+兩者共用一個執行時約束：它們依賴於 Node.js 系統綁定並執行
+不在邊缘/工作執行時上執行 - 請參閱 [Edge and serverless](#edge-serverless)。
+
+## 我需要哪個編碼檔案？ {#which-doc}
+
+| 你想要……                                                 | 使用                                         |
+| -------------------------------------------------------- | -------------------------------------------- |
+| 交換執行代理 **`run-code` 工具**的後端                   | **沙盒適配器**（本頁面）                     |
+| 封裝一個CLI工具（`gh`、`ffmpeg`）供代理調用              | **CLI 適配器**（本頁面）                     |
+| 渲染 Claude-Code/Codex-style **編碼工作區 UI**           | [Agent-Native Code UI](/docs/code-agents-ui) |
+| 使用自己的循環+工具**作為代理**執行Claude程式碼/Codex/Pi | [Harness Agents](/docs/harness-agents)       |
+
+# 沙盒適配器
+
+`run-code` 工具在隔離環境中執行代理提供的 JavaScript。 **沙箱適配器**將 _execution_ 問題從該工具中剔除，以便可以交換後端（預設情況下為本機子進程，或 Docker/遠端/持久執行程序），而無需觸及代理循環、`run-code.ts`、本機主機橋、環境清理或輸出格式。
+
+## 為什么要接縫 {#why}
+
+預設後端會生成一個鎖定的本機 Node 子進程。這受到託管進程的限制：在託管平台上，它共用代理循環的軟執行上限（超時/繼續衝擊之前約 40 秒）。遠端或持久適配器是超越該上限的杠杆 - 它獨立於請求生命週期執行大型資料作業直至完成。
+
+保持契約範圍窄意味著遠端適配器繼承相同的安全狀態。父進程保留所有秘密的所有權：它建置沙箱模塊，執行本機主機橋（它儲存請求上下文並應用主機允許列表+ SSRF 防護），清理環境並格式化輸出。適配器僅接收已準備好的、**非秘密**模塊來源加上資源限制 - 它僅負責*執行*它並捕獲 stdout/stderr/exit 狀態。
+
+```an-diagram title="父母保守秘密；適配器僅執行程式碼" summary="run-code 建置模塊並執行環回橋；適配器接收非秘密模塊+限制並返回stdout/stderr/exit。"
+{
+  "html": "<div class=\"diagram-sandbox\"><div class=\"diagram-box\" data-rough><strong>父進程</strong><small class=\"diagram-muted\">建置模塊 · loopback 橋 · 環境清理 · 輸出格式</small></div><div class=\"diagram-col\"><div class=\"diagram-pill accent\">non-secret module + limits &rarr;</div><div class=\"diagram-pill ok\">&larr; stdout / stderr / exitCode</div><div class=\"diagram-pill\">&harr; bridge calls (127.0.0.1)</div></div><div class=\"diagram-panel center\" data-rough><strong>SandboxAdapter.run</strong><small class=\"diagram-muted\">本機子進程 · Docker · 遠端 · 持久</small></div></div>",
+  "css": ".diagram-sandbox{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-sandbox .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-sandbox .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## 介面 {#interface}
+
+接縫位於 `packages/core/src/coding-tools/sandbox/` 的核心 - `adapter.ts`（合約）、`index.ts`（選取：`getSandboxAdapter()` / `registerSandboxAdapter()`）和 `local-child-process-adapter.ts`（預設）。采用`run-code.ts`封裝內接線；主機通過 `index.ts` 註冊助手插入不同的後端（或者，對於 Docker 後端，通過直接編輯這些檔案的 [blueprint](/docs/blueprint-installer)）。
+
+```an-file-tree title="core 中的 sandbox 接縫"
+{
+  "title": "packages/core/src/coding-tools/sandbox/",
+  "entries": [
+    { "path": "adapter.ts", "note": "SandboxAdapter 合約（SandboxRunRequest / SandboxRunResult）" },
+    { "path": "index.ts", "note": "選取：getSandboxAdapter() / registerSandboxAdapter()" },
+    { "path": "local-child-process-adapter.ts", "note": "預設後端：受限的 Node 子進程" },
+    { "path": "../run-code.ts", "note": "連線這個接縫；替換 backend 時永遠不變" }
+  ]
+}
+```
+
+每個後端都實現 `SandboxAdapter`：
+
+```ts
+interface SandboxAdapter {
+  /** Stable id, surfaced for diagnostics and adapter selection. */
+  readonly id: string;
+  /** Execute one prepared sandbox module and capture its output. */
+  run(request: SandboxRunRequest): Promise<SandboxRunResult>;
+}
+```
+
+請求和結果故意很小且不透明：
+
+```ts
+interface SandboxRunRequest {
+  /**
+   * The complete ESM module source to execute. Already wraps the user's code
+   * and embeds the loopback bridge URL/token; the adapter does NOT parse or
+   * rewrite it.
+   */
+  moduleSource: string;
+  /**
+   * Scrubbed environment — only safe POSIX vars (PATH/HOME/TMPDIR/…), never app
+   * secrets. Adapters must not augment this with the parent's own environment.
+   */
+  env: Record<string, string>;
+  /** Hard wall-clock timeout in milliseconds. The adapter must enforce it. */
+  timeoutMs: number;
+  /**
+   * Loopback port of the parent's bridge server (reachable over 127.0.0.1). A
+   * remote adapter that can't reach the parent's loopback must tunnel or proxy
+   * this to support bridge-backed globals (`appAction`, `providerFetch`, …).
+   */
+  bridgePort: number;
+}
+
+interface SandboxRunResult {
+  stdout: string;
+  stderr: string;
+  /** `0` on clean exit, non-zero on failure, `null` when killed by a signal. */
+  exitCode: number | null;
+  /** True when the run was killed for exceeding `timeoutMs`. */
+  timedOut: boolean;
+}
+```
+
+## 預設：`LocalChildProcessAdapter` {#default}
+
+開箱即用，`getSandboxAdapter()` 返回 `LocalChildProcessAdapter` (`id: "local-child-process"`)。它逐字節保留歷史 `run-code` 行為：
+
+- 準備好的模塊來源被寫入新的臨時目錄。
+- 子進程使用清理後的環境（沒有秘密）執行，`TMPDIR`/`TEMP`/`TMP` 指向沙箱目錄內。
+- 當節點權限模型可用（節點 20 上的 `--permission` 或 `--experimental-permission`）時，子進程將被拒絕存取其臨時目錄之外的檔案系統，以及子進程、工作進程和本機外掛。出站網路不會被權限模型阻止，但環境清理意味著此類請求不攜帶憑證，並且所有經過驗證的調用都會通過父級的環回橋。
+- 超時發送 `SIGTERM`，然後在 2 秒寬限期後發送 `SIGKILL`。
+- 執行後會盡力清理臨時檔案。
+
+> [!WARNING]
+> 預設適配器使用 `node:child_process`，該適配器在邊缘/工作執行時上不存在。在標準 Node.js 環境中執行 `run-code`，或註冊遠端適配器 - 請參閱 [Edge and serverless](#edge-serverless)。
+
+## 選取適配器 {#selection}
+
+解決順序——顯式註冊的適配器獲勝；否則環境變數選取內置的；否則使用本機預設值：
+
+```text
+registerSandboxAdapter(adapter)  →  AGENT_NATIVE_SANDBOX  →  local default
+```
+
+### `AGENT_NATIVE_SANDBOX` 環境變數 {#env}
+
+通過 id 選取內置適配器。目前僅有線`local`（預設）；未知值回退到本機而不是執行失敗。
+
+```bash
+AGENT_NATIVE_SANDBOX=local   # 預設值——顯式
+```
+
+### `registerSandboxAdapter()` {#register}
+
+主機進程通過接縫的 `index.ts` 覆蓋所有後續 `run-code` 調用的後端 - 例如，執行遠端容器中的每個調用：
+
+```ts
+import {
+  registerSandboxAdapter,
+  type SandboxAdapter,
+} from "./coding-tools/sandbox/index.js";
+
+class RemoteSandboxAdapter implements SandboxAdapter {
+  readonly id = "remote";
+  async run(request) {
+    // Ship request.moduleSource to the durable runner, enforce request.timeoutMs,
+    // proxy bridge calls back to request.bridgePort, and return stdout/stderr/exitCode.
+  }
+}
+
+registerSandboxAdapter(new RemoteSandboxAdapter());
+// Pass `null` to clear the override and fall back to env-var / default resolution.
+```
+
+## 耐用跑鞋的接縫 {#durable}
+
+這個介面是特意為未來的遠端/持久沙箱做的接縫。遠端或持久適配器（Docker、Vercel-Sandbox 式執行程序或排隊後台工作程序）將：
+
+1. 針對進程外執行時實現 `SandboxAdapter.run`。
+2. 通過隧道環回網橋（或代理網橋回調至父級）。
+3. 讓大資料作業獨立於請求生命週期執行直至完成 - 超過限制本機子進程適配器的託管約 40 秒程式碼執行上限。
+
+將其註冊為新的 `AGENT_NATIVE_SANDBOX` 值（例如 `remote`）和/或通過 `registerSandboxAdapter()`。代理循環和 `run-code.ts` 永遠不會改變。
+
+> [!TIP]
+> `agent-native add sandbox docker` 藍圖發出了一個完整的、獨立的配方，用於針對此接縫實現 Docker 適配器。參見[Blueprint Installer](/docs/blueprint-installer)。
+
+# CLI 適配器
+
+另一個適配器接縫包裝單個指令行工具（`gh`、`ffmpeg`、`stripe`、`aws`），以便代理可以發現它，檢查它是否已安裝，並以一致的 stdout/stderr/exit-code 結果執行它。每個 CLI 適配器都實現 `CliAdapter`：
+
+```ts
+import type { CliAdapter, CliResult } from "@agent-native/core/adapters/cli";
+
+interface CliAdapter {
+  name: string; // "gh", "stripe", "ffmpeg"
+  description: string; // What the agent sees during discovery
+  isAvailable(): Promise<boolean>;
+  execute(args: string[]): Promise<CliResult>;
+}
+
+interface CliResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+```
+
+對於大多數 CLI，`ShellCliAdapter` 使用合理的預設值包裝任何二進制檔案，而 `CliRegistry` 收集適配器以進行執行時發現：
+
+```ts
+import { CliRegistry, ShellCliAdapter } from "@agent-native/core/adapters/cli";
+
+const cliRegistry = new CliRegistry();
+cliRegistry.register(
+  new ShellCliAdapter({
+    command: "gh",
+    description: "GitHub CLI — manage repos, PRs, issues, and releases",
+  }),
+);
+
+await cliRegistry.describe(); // [{ name, description, available }] for discovery
+const gh = cliRegistry.get("gh");
+const result = await gh?.execute(["pr", "list", "--json", "title,url"]);
+```
+
+將 CLI 調用包裝在 `defineAction` 中以將其公開在操作介面上。請參閱 [CLI Adapters](/docs/cli-adapters) 快速參考，了解 `ShellCliAdapter` 選項、自訂適配器和操作包裝模式。
+
+## 邊缘和無伺服器 {#edge-serverless}
+
+> [!WARNING]
+> 兩個適配器接縫均依賴於 Node.js 系統綁定。沙箱 `LocalChildProcessAdapter` 和 CLI 適配器（`ShellCliAdapter` 和自訂適配器）使用 `node:child_process` (`execFile` / `spawn`)，這在 Cloudflare Workers 或 Netlify Edge Functions 等邊缘/工作線程執行時上**不存在**。如果將伺服器路由部署到這些邊缘預設，則執行這些適配器會引發執行時異常。在標準 Node.js 環境（傳統伺服器容器或無伺服器節點功能）中執行適配器端點和工作 - 或者，對於沙箱接縫，註冊一個在進程外傳送工作的遠端適配器。
+
+## 下一步是什么
+
+- [**CLI Adapters**](/docs/cli-adapters) — CLI 接縫的快速參考
+- [**Blueprint Installer**](/docs/blueprint-installer) - `agent-native add sandbox docker` 列印 Docker 適配器配方
+- [**Agent Teams**](/docs/agent-teams) — 將繁重的工作委派給子代理
+- [**Security**](/docs/security) — env 清理和橋允許名單姿勢