@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/zh-CN/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# Morning digest\n\nSummarize the emails received overnight. Group by sender domain.\nPin the top 3 threads that look like they need a reply today to the\n\"Needs reply\" label. Draft replies for any that are obvious.",
+  "annotations": [
+    { "lines": "2", "label": "When", "note": "Standard 5-field cron — `0 7 * * *` is every day at 07:00." },
+    { "lines": "3", "label": "Pause switch", "note": "Flip to `false` to stop the job without deleting it." },
+    { "lines": "4", "label": "Identity", "note": "`creator` runs with the owner's identity and `ANTHROPIC_API_KEY`; `shared` uses the org's key." },
+    { "lines": "7-12", "label": "The prompt", "note": "The body is just a prompt — the agent runs it at each firing with all its normal tools and workspace context." }
+  ]
+}
+```
+
+就是这样。正文是代理在每次计划触发时运行的提示。代理可以访问其在交互式聊天中拥有的所有相同工具和工作区上下文 - 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="One scheduler tick" summary="Every 60s the scheduler finds due jobs, runs each as a fresh agent thread, and writes the outcome back to the job file."
+{
+  "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/corpus/core/docs/content/locales/zh-CN/routing.md

@@ -0,0 +1,79 @@
+---
+title: "路由"
+description: "使用 React Router v7 为代理本机应用程序提供基于文件的路由 - 页面、动态参数和导航。"
+---
+
+# 路由
+
+代理本机应用程序使用 **React Router v7** 以及通过来自 `@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="Pathless layout wraps the pages" summary="A _app.tsx layout (no URL segment) renders the shared shell once; matched pages render inside its <Outlet/>, so the agent sidebar never remounts on navigation."
+{
+"html": "<div class=\"diagram-layout\" data-rough><div class=\"diagram-shell\"><span class=\"diagram-pill accent\">_app.tsx</span><small class=\"diagram-muted\">pathless layout · persistent shell + agent sidebar</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/corpus/core/docs/content/locales/zh-CN/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="The parent keeps the secrets; the adapter only runs code" summary="run-code builds the module and runs the loopback bridge; the adapter receives a non-secret module + limits and returns stdout/stderr/exit."
+{
+  "html": "<div class=\"diagram-sandbox\"><div class=\"diagram-box\" data-rough><strong>Parent process</strong><small class=\"diagram-muted\">builds module · loopback bridge · env scrub · output format</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\">local child · Docker · remote · durable</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="The sandbox seam in core"
+{
+  "title": "packages/core/src/coding-tools/sandbox/",
+  "entries": [
+    { "path": "adapter.ts", "note": "the SandboxAdapter contract (SandboxRunRequest / SandboxRunResult)" },
+    { "path": "index.ts", "note": "selection: getSandboxAdapter() / registerSandboxAdapter()" },
+    { "path": "local-child-process-adapter.ts", "note": "the default backend — locked-down Node child process" },
+    { "path": "../run-code.ts", "note": "wires the seam; never changes when you swap backends" }
+  ]
+}
+```
+
+每个后端都实现 `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   # the default — explicit
+```
+
+### `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 清理和桥允许名单姿势