vora-ai 0.1.0

package/docs/zh-CN/tools/diffs.md

@@ -0,0 +1,393 @@
+---
+title: Diffs
+summary: 为智能体提供的只读 diff 查看器和文件渲染器（可选插件工具）
+read_when:
+  - 你希望智能体将代码或 Markdown 编辑以 diff 形式展示
+  - 你需要可在画布中使用的查看器 URL 或渲染后的 diff 文件
+  - 你需要带安全默认值的受控临时 diff 制品
+x-i18n:
+  source_path: tools/diffs.md
+  source_hash: a9f0c2da0fe2729a7267a83037101901879a9687da58ad05cba6026145d54ae0
+  provider: openai
+  model: gpt-5.4
+  workflow: 15
+  generated_at: "2026-03-29T23:41:59Z"
+---
+
+# Diffs
+
+`diffs` 是一个可选插件工具，带有简短的内置系统引导和配套技能，可将变更内容转换为供智能体使用的只读 diff 制品。
+
+它接受以下两种输入之一：
+
+- `before` 和 `after` 文本
+- 统一格式的 `patch`
+
+可返回：
+
+- 用于画布展示的 Gateway 网关查看器 URL
+- 用于消息投递的渲染文件路径（PNG 或 PDF）
+- 在一次调用中同时返回两种输出
+
+启用后，插件会在系统提示空间中注入简洁的使用引导，同时还提供一个详细技能供智能体在需要更完整指令时使用。
+
+## 快速开始
+
+1. 启用插件。
+2. 使用 `diffs`，设置 `mode: "view"` 以走画布优先流程。
+3. 使用 `diffs`，设置 `mode: "file"` 以走聊天文件投递流程。
+4. 使用 `diffs`，设置 `mode: "both"` 以同时获取两种制品。
+
+## 启用插件
+
+```json5
+{
+  plugins: {
+    entries: {
+      diffs: {
+        enabled: true,
+      },
+    },
+  },
+}
+```
+
+## 禁用内置系统引导
+
+如果你想保留 `diffs` 工具但禁用其内置系统提示引导，将 `plugins.entries.diffs.hooks.allowPromptInjection` 设为 `false`：
+
+```json5
+{
+  plugins: {
+    entries: {
+      diffs: {
+        enabled: true,
+        hooks: {
+          allowPromptInjection: false,
+        },
+      },
+    },
+  },
+}
+```
+
+这会阻止 diffs 插件的 `before_prompt_build` 钩子，同时保留插件、工具和配套技能可用。
+
+如果你想同时禁用引导和工具，请直接禁用插件。
+
+## 典型智能体工作流
+
+1. 智能体调用 `diffs`。
+2. 智能体读取 `details` 字段。
+3. 智能体执行以下操作之一：
+   - 用 `canvas present` 打开 `details.viewerUrl`
+   - 用 `message` 工具通过 `path` 或 `filePath` 发送 `details.filePath`
+   - 两者都做
+
+## 输入示例
+
+前后文本：
+
+```json
+{
+  "before": "# Hello\n\nOne",
+  "after": "# Hello\n\nTwo",
+  "path": "docs/example.md",
+  "mode": "view"
+}
+```
+
+补丁：
+
+```json
+{
+  "patch": "diff --git a/src/example.ts b/src/example.ts\n--- a/src/example.ts\n+++ b/src/example.ts\n@@ -1 +1 @@\n-const x = 1;\n+const x = 2;\n",
+  "mode": "both"
+}
+```
+
+## 工具输入参考
+
+除特别说明外，所有字段均为可选：
+
+- `before`（`string`）：原始文本。省略 `patch` 时需与 `after` 一起提供。
+- `after`（`string`）：更新后文本。省略 `patch` 时需与 `before` 一起提供。
+- `patch`（`string`）：统一 diff 文本。与 `before` 和 `after` 互斥。
+- `path`（`string`）：前后对比模式下的显示文件名。
+- `lang`（`string`）：前后对比模式下的语言覆盖提示。
+- `title`（`string`）：查看器标题覆盖。
+- `mode`（`"view" | "file" | "both"`）：输出模式。默认为插件默认值 `defaults.mode`。
+  已弃用别名：`"image"` 的行为与 `"file"` 相同，出于向后兼容仍然接受。
+- `theme`（`"light" | "dark"`）：查看器主题。默认为插件默认值 `defaults.theme`。
+- `layout`（`"unified" | "split"`）：diff 布局。默认为插件默认值 `defaults.layout`。
+- `expandUnchanged`（`boolean`）：在有完整上下文时展开未变更部分。仅限单次调用选项，不是插件默认值键。
+- `fileFormat`（`"png" | "pdf"`）：渲染文件格式。默认为插件默认值 `defaults.fileFormat`。
+- `fileQuality`（`"standard" | "hq" | "print"`）：PNG 或 PDF 渲染的质量预设。
+- `fileScale`（`number`）：设备缩放覆盖（`1`-`4`）。
+- `fileMaxWidth`（`number`）：最大渲染宽度（CSS 像素，`640`-`2400`）。
+- `ttlSeconds`（`number`）：查看器制品 TTL（秒）。默认 1800，最大 21600。
+- `baseUrl`（`string`）：查看器 URL 来源覆盖。必须为 `http` 或 `https`，不含查询参数或哈希。
+
+验证和限制：
+
+- `before` 和 `after` 各最大 512 KiB。
+- `patch` 最大 2 MiB。
+- `path` 最大 2048 字节。
+- `lang` 最大 128 字节。
+- `title` 最大 1024 字节。
+- 补丁复杂度上限：最多 128 个文件，总计 120000 行。
+- `patch` 和 `before` 或 `after` 不能同时使用。
+- 渲染文件安全限制（适用于 PNG 和 PDF）：
+  - `fileQuality: "standard"`：最大 8 MP（8,000,000 渲染像素）。
+  - `fileQuality: "hq"`：最大 14 MP（14,000,000 渲染像素）。
+  - `fileQuality: "print"`：最大 24 MP（24,000,000 渲染像素）。
+  - PDF 还有最多 50 页的限制。
+
+## 输出详情约定
+
+工具在 `details` 下返回结构化元数据。
+
+创建查看器的模式共享字段：
+
+- `artifactId`
+- `viewerUrl`
+- `viewerPath`
+- `title`
+- `expiresAt`
+- `inputKind`
+- `fileCount`
+- `mode`
+- `context`（可用时包含 `agentId`、`sessionId`、`messageChannel`、`agentAccountId`）
+
+渲染 PNG 或 PDF 时的文件字段：
+
+- `artifactId`
+- `expiresAt`
+- `filePath`
+- `path`（与 `filePath` 相同，兼容 `message` 工具）
+- `fileBytes`
+- `fileFormat`
+- `fileQuality`
+- `fileScale`
+- `fileMaxWidth`
+
+模式行为汇总：
+
+- `mode: "view"`：仅查看器字段。
+- `mode: "file"`：仅文件字段，无查看器制品。
+- `mode: "both"`：查看器字段加文件字段。如果文件渲染失败，查看器仍然返回并附带 `fileError`。
+
+## 折叠的未变更部分
+
+- 查看器可以显示类似 `N unmodified lines` 的行。
+- 这些行上的展开控件是有条件的，并非每种输入都保证提供。
+- 当渲染的 diff 具有可展开的上下文数据时会出现展开控件，这在前后对比输入中很常见。
+- 对于许多统一补丁输入，省略的上下文主体在解析后的补丁块中不可用，因此该行可能没有展开控件。这是预期行为。
+- `expandUnchanged` 仅在存在可展开上下文时生效。
+
+## 插件默认值
+
+在 `~/.vora/vora.json` 中设置插件全局默认值：
+
+```json5
+{
+  plugins: {
+    entries: {
+      diffs: {
+        enabled: true,
+        config: {
+          defaults: {
+            fontFamily: "Fira Code",
+            fontSize: 15,
+            lineSpacing: 1.6,
+            layout: "unified",
+            showLineNumbers: true,
+            diffIndicators: "bars",
+            wordWrap: true,
+            background: true,
+            theme: "dark",
+            fileFormat: "png",
+            fileQuality: "standard",
+            fileScale: 2,
+            fileMaxWidth: 960,
+            mode: "both",
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+支持的默认值：
+
+- `fontFamily`
+- `fontSize`
+- `lineSpacing`
+- `layout`
+- `showLineNumbers`
+- `diffIndicators`
+- `wordWrap`
+- `background`
+- `theme`
+- `fileFormat`
+- `fileQuality`
+- `fileScale`
+- `fileMaxWidth`
+- `mode`
+
+显式工具参数会覆盖这些默认值。
+
+## 安全配置
+
+- `security.allowRemoteViewer`（`boolean`，默认 `false`）
+  - `false`：拒绝非本地回环请求访问查看器路由。
+  - `true`：如果令牌化路径有效，则允许远程查看器。
+
+示例：
+
+```json5
+{
+  plugins: {
+    entries: {
+      diffs: {
+        enabled: true,
+        config: {
+          security: {
+            allowRemoteViewer: false,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+## 制品生命周期和存储
+
+- 制品存储在临时子目录下：`$TMPDIR/vora-diffs`。
+- 查看器制品元数据包含：
+  - 随机制品 ID（20 个十六进制字符）
+  - 随机令牌（48 个十六进制字符）
+  - `createdAt` 和 `expiresAt`
+  - 存储的 `viewer.html` 路径
+- 未指定时默认查看器 TTL 为 30 分钟。
+- 可接受的最大查看器 TTL 为 6 小时。
+- 清理会在制品创建后择机运行。
+- 过期的制品会被删除。
+- 当元数据缺失时，回退清理会移除超过 24 小时的陈旧文件夹。
+
+## 查看器 URL 和网络行为
+
+查看器路由：
+
+- `/plugins/diffs/view/{artifactId}/{token}`
+
+查看器资源：
+
+- `/plugins/diffs/assets/viewer.js`
+- `/plugins/diffs/assets/viewer-runtime.js`
+
+URL 构建行为：
+
+- 如果提供了 `baseUrl`，会在严格校验后使用。
+- 没有 `baseUrl` 时，查看器 URL 默认使用本地回环 `127.0.0.1`。
+- 如果 Gateway 网关绑定模式为 `custom` 且设置了 `gateway.customBindHost`，则使用该主机。
+
+`baseUrl` 规则：
+
+- 必须以 `http://` 或 `https://` 开头。
+- 查询参数和哈希会被拒绝。
+- 允许使用来源加可选基础路径。
+
+## 安全模型
+
+查看器加固：
+
+- 默认仅限本地回环。
+- 带严格 ID 和令牌验证的令牌化查看器路径。
+- 查看器响应 CSP：
+  - `default-src 'none'`
+  - 脚本和资源仅来自 self
+  - 无出站 `connect-src`
+- 启用远程访问时的未命中节流：
+  - 60 秒内 40 次失败
+  - 60 秒锁定（`429 Too Many Requests`）
+
+文件渲染加固：
+
+- 截图浏览器请求路由默认拒绝。
+- 仅允许来自 `http://127.0.0.1/plugins/diffs/assets/*` 的本地查看器资源。
+- 外部网络请求被阻止。
+
+## 文件模式的浏览器要求
+
+`mode: "file"` 和 `mode: "both"` 需要兼容 Chromium 的浏览器。
+
+解析顺序：
+
+1. Vora 配置中的 `browser.executablePath`。
+2. 环境变量：
+   - `VORA_BROWSER_EXECUTABLE_PATH`
+   - `BROWSER_EXECUTABLE_PATH`
+   - `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH`
+3. 平台命令或路径发现回退。
+
+常见失败文本：
+
+- `Diff PNG/PDF rendering requires a Chromium-compatible browser...`
+
+通过安装 Chrome、Chromium、Edge 或 Brave 修复，或设置上述可执行路径选项之一。
+
+## 故障排除
+
+输入校验错误：
+
+- `Provide patch or both before and after text.`
+  - 同时提供 `before` 和 `after`，或提供 `patch`。
+- `Provide either patch or before/after input, not both.`
+  - 不要混用输入模式。
+- `Invalid baseUrl: ...`
+  - 使用带可选路径的 `http(s)` 来源，不含查询参数或哈希。
+- `{field} exceeds maximum size (...)`
+  - 减小有效负载大小。
+- 大型补丁被拒绝
+  - 减少补丁文件数或总行数。
+
+查看器访问问题：
+
+- 查看器 URL 默认解析到 `127.0.0.1`。
+- 对于远程访问场景，可以：
+  - 在每次工具调用时传入 `baseUrl`，或
+  - 使用 `gateway.bind=custom` 和 `gateway.customBindHost`
+- 仅在确实需要外部查看器访问时启用 `security.allowRemoteViewer`。
+
+未变更行没有展开按钮：
+
+- 当补丁输入未携带可展开上下文时可能出现此情况。
+- 这是预期行为，不表示查看器故障。
+
+制品未找到：
+
+- 制品因 TTL 过期。
+- 令牌或路径已更改。
+- 清理移除了陈旧数据。
+
+## 操作指南
+
+- 对于本地画布中的交互式审阅，优先使用 `mode: "view"`。
+- 对于需要附件的出站聊天渠道，优先使用 `mode: "file"`。
+- 除非你的部署需要远程查看器 URL，否则保持 `allowRemoteViewer` 禁用。
+- 对于敏感 diff，设置明确且较短的 `ttlSeconds`。
+- 在不需要时避免在 diff 输入中发送密钥。
+- 如果你的渠道会大幅压缩图片，例如 Telegram 或 WhatsApp，优先使用 PDF 输出（`fileFormat: "pdf"`）。
+
+Diff 渲染引擎：
+
+- 由 [Diffs](https://diffs.com) 提供支持。
+
+## 相关文档
+
+- [工具概览](/tools)
+- [插件](/tools/plugin)
+- [浏览器](/tools/browser)

package/docs/zh-CN/tools/elevated.md

@@ -0,0 +1,64 @@
+---
+read_when:
+  - 调整提升模式默认值、允许列表或斜杠命令行为
+summary: 提升的 exec 模式和 /elevated 指令
+title: 提升模式
+x-i18n:
+  generated_at: "2026-02-03T07:55:23Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 83767a01609304026d145feb0aa0b0533e8cf8b16cd200f724d9e3e8cf2920c3
+  source_path: tools/elevated.md
+  workflow: 15
+---
+
+# 提升模式（/elevated 指令）
+
+## 功能说明
+
+- `/elevated on` 在 Gateway 网关主机上运行并保留 exec 审批（与 `/elevated ask` 相同）。
+- `/elevated full` 在 Gateway 网关主机上运行**并**自动批准 exec（跳过 exec 审批）。
+- `/elevated ask` 在 Gateway 网关主机上运行但保留 exec 审批（与 `/elevated on` 相同）。
+- `on`/`ask` **不会**强制 `exec.security=full`；配置的安全/询问策略仍然适用。
+- 仅在智能体被**沙箱隔离**时改变行为（否则 exec 已经在主机上运行）。
+- 指令形式：`/elevated on|off|ask|full`、`/elev on|off|ask|full`。
+- 仅接受 `on|off|ask|full`；其他任何内容返回提示且不改变状态。
+
+## 它控制什么（以及不控制什么）
+
+- **可用性门控**：`tools.elevated` 是全局基线。`agents.list[].tools.elevated` 可以进一步限制每个智能体的提升（两者都必须允许）。
+- **每会话状态**：`/elevated on|off|ask|full` 为当前会话键设置提升级别。
+- **内联指令**：消息内的 `/elevated on|ask|full` 仅适用于该消息。
+- **群组**：在群聊中，仅当智能体被提及时才遵守提升指令。绕过提及要求的纯命令消息被视为已提及。
+- **主机执行**：elevated 强制 `exec` 到 Gateway 网关主机；`full` 还设置 `security=full`。
+- **审批**：`full` 跳过 exec 审批；`on`/`ask` 在允许列表/询问规则要求时遵守审批。
+- **非沙箱隔离智能体**：对位置无影响；仅影响门控、日志和状态。
+- **工具策略仍然适用**：如果 `exec` 被工具策略拒绝，则无法使用 elevated。
+- **与 `/exec` 分开**：`/exec` 为授权发送者调整每会话默认值，不需要 elevated。
+
+## 解析顺序
+
+1. 消息上的内联指令（仅适用于该消息）。
+2. 会话覆盖（通过发送仅含指令的消息设置）。
+3. 全局默认值（配置中的 `agents.defaults.elevatedDefault`）。
+
+## 设置会话默认值
+
+- 发送一条**仅**包含指令的消息（允许空白），例如 `/elevated full`。
+- 发送确认回复（`Elevated mode set to full...` / `Elevated mode disabled.`）。
+- 如果 elevated 访问被禁用或发送者不在批准的允许列表中，指令会回复一个可操作的错误且不改变会话状态。
+- 发送不带参数的 `/elevated`（或 `/elevated:`）以查看当前的 elevated 级别。
+
+## 可用性 + 允许列表
+
+- 功能门控：`tools.elevated.enabled`（即使代码支持，也可以通过配置将默认值设为关闭）。
+- 发送者允许列表：`tools.elevated.allowFrom`，带有每提供商允许列表（例如 `discord`、`whatsapp`）。
+- 每智能体门控：`agents.list[].tools.elevated.enabled`（可选；只能进一步限制）。
+- 每智能体允许列表：`agents.list[].tools.elevated.allowFrom`（可选；设置时，发送者必须同时匹配全局 + 每智能体允许列表）。
+- Discord 回退：如果省略 `tools.elevated.allowFrom.discord`，则使用 `channels.discord.dm.allowFrom` 列表作为回退。设置 `tools.elevated.allowFrom.discord`（即使是 `[]`）以覆盖。每智能体允许列表**不**使用回退。
+- 所有门控都必须通过；否则 elevated 被视为不可用。
+
+## 日志 + 状态
+
+- Elevated exec 调用以 info 级别记录。
+- 会话状态包括 elevated 模式（例如 `elevated=ask`、`elevated=full`）。

package/docs/zh-CN/tools/exec-approvals.md

@@ -0,0 +1,234 @@
+---
+read_when:
+  - 配置执行审批或允许列表
+  - 在 macOS 应用中实现执行审批用户体验
+  - 审查沙箱逃逸提示及其影响
+summary: 执行审批、允许列表和沙箱逃逸提示
+title: 执行审批
+x-i18n:
+  generated_at: "2026-02-03T08:19:51Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 97736427752eb905bb5d1f5b54bddbdea38eb5ac5824e2bf99258fcf44ee393c
+  source_path: tools/exec-approvals.md
+  workflow: 15
+---
+
+# 执行审批
+
+执行审批是**配套应用/节点主机的安全护栏**，用于允许沙箱隔离的智能体在真实主机（`gateway` 或 `node`）上运行命令。可以将其理解为安全联锁：只有当策略 + 允许列表 +（可选的）用户审批都同意时，命令才会被允许执行。
+执行审批是**附加于**工具策略和提权门控之上的（除非 elevated 设置为 `full`，这会跳过审批）。
+生效策略取 `tools.exec.*` 和审批默认值中**更严格**的一方；如果审批字段被省略，则使用 `tools.exec` 的值。
+
+如果配套应用 UI **不可用**，任何需要提示的请求都将由 **ask fallback**（默认：deny）决定。
+
+## 适用范围
+
+执行审批在执行主机上本地强制执行：
+
+- **gateway 主机** → gateway 机器上的 `vora` 进程
+- **node 主机** → 节点运行器（macOS 配套应用或无头节点主机）
+
+macOS 分工：
+
+- **node 主机服务**通过本地 IPC 将 `system.run` 转发给 **macOS 应用**。
+- **macOS 应用**执行审批并在 UI 上下文中执行命令。
+
+## 设置和存储
+
+审批信息存储在执行主机上的本地 JSON 文件中：
+
+`~/.vora/exec-approvals.json`
+
+示例结构：
+
+```json
+{
+  "version": 1,
+  "socket": {
+    "path": "~/.vora/exec-approvals.sock",
+    "token": "base64url-token"
+  },
+  "defaults": {
+    "security": "deny",
+    "ask": "on-miss",
+    "askFallback": "deny",
+    "autoAllowSkills": false
+  },
+  "agents": {
+    "main": {
+      "security": "allowlist",
+      "ask": "on-miss",
+      "askFallback": "deny",
+      "autoAllowSkills": true,
+      "allowlist": [
+        {
+          "id": "B0C8C0B3-2C2D-4F8A-9A3C-5A4B3C2D1E0F",
+          "pattern": "~/Projects/**/bin/rg",
+          "lastUsedAt": 1737150000000,
+          "lastUsedCommand": "rg -n TODO",
+          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"
+        }
+      ]
+    }
+  }
+}
+```
+
+## 策略选项
+
+### Security（`exec.security`）
+
+- **deny**：阻止所有主机执行请求。
+- **allowlist**：仅允许在允许列表中的命令。
+- **full**：允许所有命令（等同于提权模式）。
+
+### Ask（`exec.ask`）
+
+- **off**：从不提示。
+- **on-miss**：仅在允许列表未匹配时提示。
+- **always**：每次命令都提示。
+
+### Ask fallback（`askFallback`）
+
+如果需要提示但无法访问 UI，fallback 决定：
+
+- **deny**：阻止。
+- **allowlist**：仅在允许列表匹配时允许。
+- **full**：允许。
+
+## 允许列表（按智能体）
+
+允许列表是**按智能体**配置的。如果存在多个智能体，请在 macOS 应用中切换要编辑的智能体。模式匹配**不区分大小写**。
+模式应解析为**二进制路径**（仅包含基本名称的条目会被忽略）。
+旧版 `agents.default` 条目在加载时会迁移到 `agents.main`。
+
+示例：
+
+- `~/Projects/**/bin/bird`
+- `~/.local/bin/*`
+- `/opt/homebrew/bin/rg`
+
+每个允许列表条目会跟踪：
+
+- **id** 用于 UI 标识的稳定 UUID（可选）
+- **last used** 时间戳
+- **last used command**
+- **last resolved path**
+
+## 自动允许 skill CLI
+
+启用 **Auto-allow skill CLIs** 后，已知 Skills 引用的可执行文件在节点（macOS 节点或无头节点主机）上被视为已列入允许列表。这通过 Gateway RPC 的 `skills.bins` 获取 skill 二进制列表。如果你想要严格的手动允许列表，请禁用此选项。
+
+## 安全二进制（仅限标准输入）
+
+`tools.exec.safeBins` 定义了一小组**仅限标准输入**的二进制文件（例如 `jq`），这些文件可以在允许列表模式下运行，**无需**显式的允许列表条目。安全二进制会拒绝位置文件参数和类路径标记，因此它们只能操作传入的流。
+在允许列表模式下，shell 链式命令和重定向不会被自动允许。
+
+当每个顶级段都满足允许列表（包括安全二进制或 skill 自动允许）时，允许 shell 链式命令（`&&`、`||`、`;`）。重定向在允许列表模式下仍不受支持。
+命令替换（`$()` / 反引号）在允许列表解析期间会被拒绝，包括在双引号内；如果你需要字面的 `$()` 文本，请使用单引号。
+
+默认安全二进制：`jq`、`grep`、`cut`、`sort`、`uniq`、`head`、`tail`、`tr`、`wc`。
+
+## Control UI 编辑
+
+使用 **Control UI → Nodes → Exec approvals** 卡片来编辑默认值、按智能体的覆盖设置和允许列表。选择一个作用域（Defaults 或某个智能体），调整策略，添加/删除允许列表模式，然后点击 **Save**。UI 会显示每个模式的 **last used** 元数据，以便你保持列表整洁。
+
+目标选择器可选择 **Gateway**（本地审批）或 **Node**。节点必须通告 `system.execApprovals.get/set`（macOS 应用或无头节点主机）。
+如果节点尚未通告执行审批，请直接编辑其本地的 `~/.vora/exec-approvals.json`。
+
+CLI：`vora approvals` 支持 gateway 或 node 编辑（参见 [Approvals CLI](/cli/approvals)）。
+
+## 审批流程
+
+当需要提示时，gateway 向操作员客户端广播 `exec.approval.requested`。
+Control UI 和 macOS 应用通过 `exec.approval.resolve` 进行处理，然后 gateway 将已批准的请求转发给节点主机。
+
+当需要审批时，exec 工具会立即返回一个审批 id。使用该 id 来关联后续的系统事件（`Exec finished` / `Exec denied`）。如果在超时前没有收到决定，请求将被视为审批超时，并作为拒绝原因显示。
+
+确认对话框包括：
+
+- 命令 + 参数
+- cwd
+- 智能体 id
+- 解析后的可执行文件路径
+- 主机 + 策略元数据
+
+操作：
+
+- **Allow once** → 立即运行
+- **Always allow** → 添加到允许列表 + 运行
+- **Deny** → 阻止
+
+## 审批转发到聊天渠道
+
+你可以将执行审批提示转发到任何聊天渠道（包括插件渠道），并使用 `/approve` 进行批准。这使用正常的出站投递管道。
+
+配置：
+
+```json5
+{
+  approvals: {
+    exec: {
+      enabled: true,
+      mode: "session", // "session" | "targets" | "both"
+      agentFilter: ["main"],
+      sessionFilter: ["discord"], // substring or regex
+      targets: [
+        { channel: "slack", to: "U12345678" },
+        { channel: "telegram", to: "123456789" },
+      ],
+    },
+  },
+}
+```
+
+在聊天中回复：
+
+```
+/approve <id> allow-once
+/approve <id> allow-always
+/approve <id> deny
+```
+
+### macOS IPC 流程
+
+```
+Gateway -> Node Service (WS)
+                 |  IPC (UDS + token + HMAC + TTL)
+                 v
+             Mac App (UI + approvals + system.run)
+```
+
+安全注意事项：
+
+- Unix socket 模式 `0600`，token 存储在 `exec-approvals.json` 中。
+- 同 UID 对端检查。
+- 挑战/响应（nonce + HMAC token + 请求哈希）+ 短 TTL。
+
+## 系统事件
+
+执行生命周期以系统消息的形式呈现：
+
+- `Exec running`（仅当命令超过运行通知阈值时）
+- `Exec finished`
+- `Exec denied`
+
+这些消息在节点报告事件后发布到智能体的会话中。
+Gateway 主机执行审批在命令完成时（以及可选地在运行时间超过阈值时）发出相同的生命周期事件。
+经过审批门控的执行会复用审批 id 作为这些消息中的 `runId`，以便于关联。
+
+## 影响
+
+- **full** 权限很大；尽可能优先使用允许列表。
+- **ask** 让你保持知情，同时仍允许快速审批。
+- 按智能体的允许列表可防止一个智能体的审批泄漏到其他智能体。
+- 审批仅适用于来自**授权发送者**的主机执行请求。未授权的发送者无法发出 `/exec`。
+- `/exec security=full` 是为授权操作员提供的会话级便利功能，设计上会跳过审批。
+  要完全阻止主机执行，请将审批 security 设置为 `deny`，或通过工具策略拒绝 `exec` 工具。
+
+相关内容：
+
+- [Exec 工具](/tools/exec)
+- [提权模式](/tools/elevated)
+- [Skills](/tools/skills)