npm - better-dsh - Versions diffs - 0.2.5 → 0.3.0-c - Mend

better-dsh 0.2.5 → 0.3.0-c

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1002) hide show

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/features/codex-app-server-runtime.md DELETED Viewed

@@ -1,441 +0,0 @@
----
-title: Codex App-Server 运行时（可选）
-sidebar_label: Codex App-Server 运行时
----
-# Codex App-Server 运行时
-Hermes 可以选择将 `openai/*` 和 `openai-codex/*` 的轮次交由 [Codex CLI app-server](https://github.com/openai/codex) 处理，而不是运行自己的工具循环。启用后，终端命令、文件编辑、沙箱隔离以及 MCP 工具调用均在 Codex 的运行时内执行——Hermes 成为其外层 shell（会话数据库、斜杠命令、gateway、记忆与技能审查）。
-此功能**仅限手动启用**。除非你主动切换该标志，否则 Hermes 的默认行为不变。Hermes 不会自动将你路由到此运行时。
-## 为什么使用
-- 通过 Codex CLI 使用的相同认证流程，使用你的 **ChatGPT 订阅**运行 OpenAI agent 轮次（无需 API 密钥）。
-- 使用 **Codex 自带的工具集和沙箱**——`shell` 用于终端/读/写/搜索，`apply_patch` 用于结构化编辑，`update_plan` 用于规划，全部在 seatbelt/landlock 沙箱内运行。
-- **原生 Codex 插件**——Linear、GitHub、Gmail、Calendar、Canva 等——通过 `codex plugin` 安装后，会自动迁移并在你的 Hermes 会话中激活。
-- **Hermes 的丰富工具一并可用**——web_search、web_extract、浏览器自动化、视觉、图像生成、技能和 TTS 通过 MCP 回调提供。Codex 会回调 Hermes 获取其自身没有内置的工具。
-- **记忆与技能提示持续生效**——Codex 的事件被投影为 Hermes 的消息格式，使自我改进循环看到正常的对话记录。
-## 模型实际拥有哪些工具
-这是大多数用户最想提前了解的部分。当此运行时开启时，执行你的轮次的模型拥有三个独立的工具来源：
-### 1. Codex 内置工具集（始终开启）
-这些工具随 `codex app-server` 本身一起提供——无需 Hermes 介入，无需 MCP，无需插件。运行时启动后，以下五个工具立即可用：
-- **`shell`** — 在沙箱内运行任意 shell 命令。模型通过此工具读取文件（`cat`、`head`、`tail`）、写入文件（`echo > foo`、heredoc）、搜索文件（`find`、`rg`、`grep`）、浏览目录（`ls`、`cd`）、运行构建、管理进程，以及其他任何你在 bash 中能做的事。
-- **`apply_patch`** — 以 Codex 的 patch 格式应用结构化的多文件差异。模型将此工具用于非简单的代码编辑（添加函数、跨文件重构）；单次写入仍可使用 shell heredoc。
-- **`update_plan`** — Codex 的内部待办/计划跟踪器。等同于 Hermes 的 `todo` 工具，但完全在 Codex 运行时内部管理。
-- **`view_image`** — 将本地图像文件加载到对话中，使模型能够查看它。
-- **`web_search`** — 配置后 Codex 拥有自己的内置网络搜索。Hermes 也通过下方的回调暴露 `web_search`（基于 Firecrawl）；模型会选择其偏好的那个。
-因此，**任何你通过终端完成的操作——读/写/搜索/查找/运行——Codex 都能原生处理**。沙箱配置文件（启用运行时时默认为 `:workspace`）控制可写范围。
-### 2. 原生 Codex 插件（从你的 `codex plugin` 安装中自动迁移）
-启用运行时时，Hermes 会查询 Codex 的 `plugin/list` RPC，并为你已安装的每个插件写入一条 `[plugins."<name>@openai-curated"]` 配置项。插件本身由 Codex 管理，并通过 Codex 自己的 UI 完成一次性授权。
-示例（OpenClaw 帖子中被称为"值得录制视频"的那些）：
-- **Linear** — 查找/更新 issue
-- **GitHub** — 搜索代码、查看 PR、评论
-- **Gmail** — 读取/发送邮件
-- **Google Calendar** — 创建/查找日程
-- **Outlook 日历/邮件** — 通过 Microsoft 连接器提供相同功能
-- **Canva** — 设计生成
-- ……以及其他你通过 `codex plugin marketplace add openai-curated` + `codex plugin install ...` 安装的插件
-**未迁移的内容：**
-- 你尚未安装的插件——请先在 Codex 中安装。
-- ChatGPT 应用市场条目（`app/list`）——这些已通过你的账户认证在 Codex 内部启用。
-### 3. Hermes 工具回调（MCP server，注册在 `~/.codex/config.toml` 中）
-Hermes 将自身注册为 MCP server，以便 Codex 能够回调获取 Codex 自身未内置的工具。通过回调可用的工具：
-- **`web_search`** / **`web_extract`** — 基于 Firecrawl；对于结构化内容，通常比直接抓取更干净。
-- **`browser_navigate` / `browser_click` / `browser_type` / `browser_press` / `browser_snapshot` / `browser_scroll` / `browser_back` / `browser_get_images` / `browser_console` / `browser_vision`** — 通过 Camofox 或 Browserbase 实现完整的浏览器自动化。
-- **`vision_analyze`** — 调用独立的视觉模型检查图像（与 Codex 的 `view_image` 不同，后者是将图像加载到对话中）。
-- **`image_generate`** — 通过 Hermes 的 image_gen 插件链生成图像。
-- **`skill_view` / `skills_list`** — 读取 Hermes 的技能库。
-- **`text_to_speech`** — 通过 Hermes 配置的提供商进行 TTS。
-当模型需要其中某个工具时，Codex 通过 stdio MCP 生成 `hermes_tools_mcp_server` 子进程，调用通过 `model_tools.handle_function_call()` 分发（与 Hermes 默认运行时的代码路径相同），结果像其他 MCP 响应一样返回给 Codex。
-### 此运行时上不可用的工具
-以下四个 Hermes 工具需要运行中的 AIAgent 上下文（循环中间状态）才能分发，无状态的 MCP 回调无法驱动它们。需要这些工具时，请切换回默认运行时（`/codex-runtime auto`）：
-- **`delegate_task`** — 生成子 agent
-- **`memory`** — Hermes 的持久记忆存储
-- **`session_search`** — 跨会话搜索
-- **`todo`** — Hermes 的待办存储（Codex 的 `update_plan` 是运行时内的等效工具）
-## 工作流功能（`/goal`、kanban、cron）
-### `/goal`（Ralph 循环）
-**在此运行时上可用。** 目标以会话 id 为键持久化在 `state_meta` 中，续接提示通过 `run_conversation()` 作为普通用户消息回传，Codex 原生执行下一轮次。目标判断器通过辅助客户端运行（在 config.yaml 中通过 `auxiliary.goal_judge` 配置），与当前活跃的运行时无关。判断器的"受阻，需要用户输入"裁决是 Codex 卡在审批时的干净退出路径。
-**需要注意的一点：** 每个续接提示都是一次全新的 Codex 轮次，这意味着 Codex 会从头重新评估命令审批策略。如果你在执行包含大量写操作的长期目标，预期会看到比单次会话内任务更多的审批提示。设置 `default_permissions = ":workspace"`（启用运行时时 Hermes 会自动设置）可避免简单的工作区写操作触发提示。
-### Kanban（多 agent 工作树分发）
-**在此运行时上可用，但有一个细微依赖。** Kanban 分发器将每个 worker 生成为独立的 `hermes chat -q` 子进程，该子进程读取用户配置——这意味着如果全局设置了 `model.openai_runtime: codex_app_server`，worker 也会在 Codex 运行时上启动。
-Codex 运行时 worker 内可用的功能：
-- Codex 完整工具集（shell、apply_patch、update_plan、view_image、web_search）——worker 原生完成实际任务
-- 已迁移的 Codex 插件——Linear、GitHub 等
-- 用于 browser_*、vision、image_gen、技能、TTS 的 Hermes 工具回调
-通过 MCP 回调同样可用的功能：
-- **`kanban_complete` / `kanban_block` / `kanban_comment` / `kanban_heartbeat`** — worker 交接工具。这些工具从环境变量中读取 `HERMES_KANBAN_TASK`（由分发器设置），正确进行访问控制，并写入由 `HERMES_KANBAN_DB` 固定的每个看板 SQLite 数据库。若回调中没有这些工具，此运行时上的 worker 可以完成任务但无法汇报，会一直挂起直到分发器超时。
-- **`kanban_show` / `kanban_list`** — 只读看板查询，供 worker 检查自身上下文。
-- **`kanban_create` / `kanban_unblock` / `kanban_link`** — 仅限编排器的操作。供运行在 Codex 运行时上、需要分发新任务的编排器 agent 使用。
-Kanban 工具通过分发器设置的 `HERMES_KANBAN_TASK` 环境变量进行访问控制——该变量会传播到 Codex 子进程（Codex 继承环境变量），再从那里传播到生成的 `hermes-tools` MCP server 子进程。因此工具能看到正确的任务 id 并正确进行访问控制。对于 Codex app-server worker，当 `HERMES_KANBAN_TASK` 存在时，Hermes 还会传入精细的 app-server 沙箱覆盖配置：保持 `workspace-write` 沙箱，将**看板数据库目录以及分发器固定的所有 Kanban 路径**作为额外可写根目录添加（`HERMES_KANBAN_WORKSPACES_ROOT`、`HERMES_KANBAN_WORKSPACE`、旧版 `HERMES_KANBAN_ROOT`——去重，数据库目录优先），并默认禁用网络。这避免了脆弱的 `:danger-no-sandbox` 变通方案，同时允许 `kanban_complete` / `kanban_block` 更新看板数据库，**并且**允许 worker 在数据库目录之外的工作区挂载点下写入报告/产物（例如独立驱动器上的 `/media/.../kanban-workspaces/...`——[issue #27941](https://github.com/NousResearch/hermes-agent/issues/27941)）。
-### Cron 任务
-**尚未经过专项测试。** Cron 任务通过 `cronjob` → `AIAgent.run_conversation` 运行，与 CLI 的代码路径相同。如果 cron 任务的配置中有 `openai_runtime: codex_app_server`，它将在 Codex 上运行。相同的工具可用性规则适用——Codex 内置工具 + 插件 + MCP 回调可用，agent 循环工具（delegate_task、memory、session_search、todo）不可用。如果你的 cron 任务依赖这些工具，请将 cron 限定在使用默认运行时的配置文件中。
-## 权衡对比
-|  | Hermes 默认运行时 | Codex app-server（可选启用） |
-|---|---|---|
-| `delegate_task` 子 agent | 是 | 不可用——需要 agent 循环上下文 |
-| `memory`、`session_search`、`todo` | 是 | 不可用——需要 agent 循环上下文 |
-| `web_search`、`web_extract` | 是 | 是（通过 MCP 回调） |
-| 浏览器自动化（Camofox/Browserbase） | 是 | 是（通过 MCP 回调） |
-| `vision_analyze`、`image_generate` | 是 | 是（通过 MCP 回调） |
-| `skill_view`、`skills_list` | 是 | 是（通过 MCP 回调） |
-| `text_to_speech` | 是 | 是（通过 MCP 回调） |
-| Codex `shell`（终端/读/写/搜索/查找/运行） | — | 是（Codex 内置） |
-| Codex `apply_patch`（结构化多文件编辑） | — | 是（Codex 内置） |
-| Codex `update_plan`（运行时内待办） | — | 是（Codex 内置） |
-| Codex `view_image`（将图像加载到对话） | — | 是（Codex 内置） |
-| Codex 沙箱（seatbelt/landlock，配置文件） | — | 是（Codex 内置） |
-| ChatGPT 订阅认证 | — | 是（通过 `openai-codex` 提供商） |
-| 原生 Codex 插件（Linear、GitHub 等） | — | 是（自动迁移） |
-| 用户 MCP server | 是 | 是（自动迁移到 Codex） |
-| 记忆 + 技能审查（后台） | 是 | 是（通过事件投影） |
-| 多轮对话 | 是 | 是 |
-| `/goal`（Ralph 循环） | 是 | 是 |
-| Kanban worker 分发 | 是 | 是（通过回调） |
-| Kanban 编排器工具 | 是 | 是（通过回调） |
-| 所有 gateway 平台 | 是 | 是 |
-| 非 OpenAI 提供商 | 是 | 不适用——仅限 OpenAI/Codex |
-## 前提条件
-1. **已安装 Codex CLI：**
-   ```bash
-   npm i -g @openai/codex
-   codex --version   # 0.130.0 或更新版本
-   ```
-2. **Codex OAuth 登录。** Codex 子进程读取 `~/.codex/auth.json`。有两种方式填充它：
-   ```bash
-   codex login                  # 将 token 写入 ~/.codex/auth.json
-   ```
-   Hermes 自己的 `hermes auth login codex` 写入 `~/.hermes/auth.json`——那是独立的会话。**如果你还没有运行过 `codex login`，请单独运行它。**
-3. **（可选）安装你想要的 Codex 插件。** 启用运行时时，Hermes 会自动迁移你已通过 Codex CLI 安装的所有精选插件：
-   ```bash
-   codex plugin marketplace add openai-curated
-   # 然后通过 Codex 的 TUI 安装 Linear / GitHub / Gmail 等
-   ```
-   Hermes 会自动发现它们并将 `[plugins."<name>@openai-curated"]` 条目写入 `~/.codex/config.toml`。
-## 启用
-在 Hermes 会话中：
-```
-/codex-runtime codex_app_server
-```
-该命令会：
-- 验证 `codex` CLI 是否已安装（若未安装则阻止并提示安装方法）。
-- 将 `model.openai_runtime: codex_app_server` 持久化到你的 config.yaml。
-- 将用户 MCP server 从 `~/.hermes/config.yaml` 迁移到 `~/.codex/config.toml`。
-- **发现并迁移已安装的原生 Codex 插件**（Linear、GitHub、Gmail、Calendar、Canva 等），通过查询 Codex 的 `plugin/list` RPC 实现。
-- **将 Hermes 自身的工具注册为 MCP server**，以便 Codex 子进程能够回调获取 Codex 未内置的工具。
-- **写入 `default_permissions = ":workspace"`**，使沙箱允许在工作区内写入，无需对每次操作进行提示。
-- 告知你迁移了哪些内容。在**下一个**会话生效——当前缓存的 agent 保持之前的运行时，以保持 prompt 缓存有效。
-同义命令：`/codex-runtime on`、`/codex-runtime off`、`/codex-runtime auto`。
-查看当前状态而不做任何更改：
-```
-/codex-runtime
-```
-你也可以在 `~/.hermes/config.yaml` 中手动设置：
-```yaml
-model:
-  openai_runtime: codex_app_server   # 默认值为 "auto"（= Hermes 运行时）
-```
-## 自我改进循环（记忆 + 技能提示）
-Hermes 的后台自我改进在计数器达到阈值时触发：
-- 每 10 个用户 prompt（提示词）→ 一个分叉的审查 agent 查看对话，决定是否有内容应保存到记忆中。
-- 单次轮次内每 10 次工具迭代 → 同样的逻辑，但针对技能（`skill_manage` 写入）。
-**两者在 Codex 运行时上均持续生效。** Codex 路径将每个已完成的 `commandExecution` / `fileChange` / `mcpToolCall` / `dynamicToolCall` 事件项投影为合成的 `assistant tool_call` + `tool` 结果消息，因此审查运行时看到的格式与在默认 Hermes 运行时上看到的相同。
-连接方式保持等效：
-| | 默认运行时 | Codex 运行时 |
-|---|---|---|
-| `_turns_since_memory` 递增 | 每个用户 prompt，在 run_conversation 预循环中 | 相同代码路径，在提前返回之前 |
-| `_iters_since_skill` 递增 | 在聊天补全循环的每次工具迭代中 | 通过 Codex 轮次返回后的 `turn.tool_iterations` |
-| 记忆触发（`_turns_since_memory >= _memory_nudge_interval`） | 在预循环中计算，响应后触发 | 在预循环中计算，传递给 Codex 辅助函数 |
-| 技能触发（`_iters_since_skill >= _skill_nudge_interval`） | 在循环结束后计算 | 在 Codex 轮次结束后计算 |
-| `_spawn_background_review(messages_snapshot=..., review_memory=..., review_skills=...)` | 任一触发器触发时调用 | 任一触发器触发时以相同方式调用 |
-一个细节：审查分叉本身需要调用 Hermes 的 agent 循环工具（`memory`、`skill_manage`），这需要 Hermes 自身的分发。因此，当父 agent 处于 `codex_app_server` 时，审查分叉会**降级为 `codex_responses`**——相同的 OAuth 凭据，相同的 `openai-codex` 提供商，但直接与 OpenAI 的 Responses API 通信，使 Hermes 拥有循环控制权，agent 循环工具得以正常工作。这对用户不可见。
-最终效果：启用 Codex 运行时后，你的记忆 + 技能提示计数器与之前完全一样持续触发。
-## 审批流程
-Codex 在执行命令或应用 patch 之前会请求审批。这些请求会被转换为 Hermes 标准的"危险命令"提示：
-```
-╭───────────────────────────────────────╮
-│ Dangerous Command                     │
-│                                       │
-│ /bin/bash -lc 'echo hello > foo.txt'  │
-│                                       │
-│ ❯ 1. Allow once                       │
-│   2. Allow for this session           │
-│   3. Deny                             │
-│                                       │
-│ Codex requests exec in /your/cwd      │
-╰───────────────────────────────────────╯
-```
-- **Allow once** → 批准此单次命令。
-- **Allow for this session** → Codex 不会再对类似命令重复提示。
-- **Deny** → 命令被拒绝；Codex 以只读模式继续运行。
-对于 `apply_patch`（文件编辑）审批，当 Codex 通过对应的 `fileChange` 事件项提供数据时，Hermes 会显示变更摘要（`1 add, 1 update: /tmp/new.py, /tmp/old.py`）。
-## 权限配置文件
-Codex 有三个内置权限配置文件：
-- `:read-only` — 禁止写入；每条 shell 命令都需要审批
-- `:workspace` — 允许在当前工作区内写入而无需提示（启用运行时时 Hermes 的默认值）
-- `:danger-no-sandbox` — 完全不使用沙箱（除非你清楚其含义，否则不要使用）
-你可以在 Hermes 管理块之外的 `~/.codex/config.toml` 中覆盖默认值：
-```toml
-default_permissions = ":read-only"
-```
-（只要你的覆盖配置位于 `# managed by hermes-agent` 标记之外，Hermes 在重新迁移时会保留它。）
-## 辅助任务与 ChatGPT 订阅 token 消耗
-当此运行时与 `openai-codex` 提供商一起开启时，**辅助任务（标题生成、上下文压缩、视觉自动检测、后台自我改进审查分叉）默认也会通过你的 ChatGPT 订阅流转**，因为 Hermes 的辅助客户端在没有设置每任务覆盖时使用主提供商/模型。
-这并非 `codex_app_server` 特有——现有的 `codex_responses` 路径也是如此——但在这里更为明显，因为你是在明确选择订阅计费。
-要将特定辅助任务路由到更便宜/不同的模型，请在 `~/.hermes/config.yaml` 中设置显式覆盖：
-```yaml
-auxiliary:
-  title_generation:
-    provider: openrouter
-    model: google/gemini-3-flash-preview
-  compression:
-    provider: openrouter
-    model: google/gemini-3-flash-preview
-  vision:
-    provider: openrouter
-    model: google/gemini-3-flash-preview
-  goal_judge:
-    provider: openrouter
-    model: google/gemini-3-flash-preview
-```
-自我改进审查分叉通过 `_current_main_runtime()` 继承主运行时，Hermes 会自动将其从 `codex_app_server` 降级为 `codex_responses`（以便分叉能够实际调用 `memory` 和 `skill_manage`——Hermes 自身的 agent 循环工具）。除非你已将辅助任务路由到其他地方，否则该分叉仍使用你的订阅认证。
-## 安全编辑 `~/.codex/config.toml`
-Hermes 将其管理的所有内容包裹在两个标记注释之间：
-```toml
-# managed by hermes-agent — `hermes codex-runtime migrate` regenerates this section
-default_permissions = ":workspace"
-[mcp_servers.filesystem]
-...
-[plugins."github@openai-curated"]
-...
-# end hermes-agent managed section
-```
-该块**之外**的内容归你所有。重新运行迁移（通过 `/codex-runtime codex_app_server` 或每次切换运行时时）会原地替换管理块，但完整保留其上下方的用户内容。这意味着你可以：
-- 添加 Hermes 不知道的自定义 MCP server
-- 将 `default_permissions` 覆盖为 `:read-only`（如果你希望被提示）
-- 配置仅 Codex 使用的选项（model、providers、otel 等）
-- 在 `[permissions.<name>]` 表中添加用户自定义权限配置文件
-你在管理块**内部**添加的任何内容都会在下次迁移时被覆盖。如果你需要修改管理块中的某项配置，请提交 issue，我们会添加相应的开关。
-## 多配置文件 / 多租户设置
-默认情况下，无论哪个 Hermes 配置文件处于活跃状态，Hermes 都将 Codex 子进程指向 `~/.codex/`。这意味着 `hermes -p work` 和 `hermes -p personal` 共享相同的 Codex 认证、插件和配置。对大多数用户来说这是正确的行为——与直接运行 `codex` CLI 的效果一致。
-如果你需要按配置文件隔离 Codex（独立的认证、独立的已安装插件、独立的配置），请为每个配置文件显式设置 `CODEX_HOME`。最简洁的方式是指向你 `HERMES_HOME` 下的某个目录：
-```bash
-# 在 work 配置文件中，你可以这样包装 hermes：
-CODEX_HOME=~/.hermes/profiles/work/codex hermes chat
-```
-你需要在设置了该 `CODEX_HOME` 的情况下重新运行一次 `codex login`，以便 OAuth token 落入配置文件范围的位置。之后，`hermes -p work` 将在隔离的 Codex 状态下运行。
-我们不自动限定此范围，因为移动现有用户的 `~/.codex/` 会静默地使其 Codex CLI 认证失效——任何已运行过 `codex login` 的用户都需要重新认证。选择加入比给用户带来意外更安全。
-## HOME 环境变量透传
-Hermes 在生成 Codex app-server 子进程时**不会**重写 `HOME`（我们使用 `os.environ.copy()`，仅覆盖 `CODEX_HOME` 和 `RUST_LOG`）。这意味着：
-- Codex 通过其 `shell` 工具运行的命令能看到真实的用户 `HOME`，并能正确找到 `~/.gitconfig`、`~/.gh/`、`~/.aws/`、`~/.npmrc` 等。
-- Codex 的内部状态通过 `CODEX_HOME` 保持隔离（默认指向 `~/.codex/`）。
-这与 OpenClaw 在早期实验后得出的边界一致：隔离 Codex 的状态，保持用户主目录不变。（参见 openclaw/openclaw#81562。）
-## MCP server 迁移
-Hermes 的 `mcp_servers` 配置会自动转换为 Codex 所需的 TOML 格式。迁移在每次启用运行时时运行，且是幂等的——重新运行会替换管理块，但保留用户编辑的 Codex 配置。
-转换内容：
-| Hermes（`config.yaml`） | Codex（`config.toml`） |
-|---|---|
-| `command` + `args` + `env` | stdio transport |
-| `url` + `headers` | streamable_http transport |
-| `timeout` | `tool_timeout_sec` |
-| `connect_timeout` | `startup_timeout_sec` |
-| `enabled: false` | `enabled = false` |
-未迁移的内容：
-- Hermes 特有的键，如 `sampling`（Codex 的 MCP 客户端没有等效项——这些会被丢弃并附带每个 server 的警告）。
-## 原生 Codex 插件迁移
-通过 `codex plugin` 安装的插件（Linear、GitHub、Gmail、Calendar、Canva 等）通过 Codex 的 `plugin/list` RPC 被发现。对于每个 `installed: true` 的插件，Hermes 会写入一个 `[plugins."<name>@openai-curated"]` 块，在你的 Hermes 会话中启用它。
-这意味着：当你的朋友说"我在 Codex CLI 中设置了 Calendar 和 GitHub"，他们启用 Hermes 的 Codex 运行时后，Hermes 会自动激活这些插件。无需重新配置。
-**未迁移的内容：**
-- 你尚未安装的插件——请先在 Codex 中安装。
-- Codex 报告 `availability != AVAILABLE` 的插件（安装损坏、OAuth 过期、已从市场下架等）。这些会被跳过，以避免写入激活时会失败的配置。
-- ChatGPT 应用市场条目（每账户的 `app/list` 结果——这些已通过你的账户认证在 Codex 内部启用）。
-- 插件 OAuth——你在 Codex 本身中对每个插件授权一次；Hermes 不接触凭据。
-## Hermes 工具回调（新 MCP server）
-Codex 的内置工具集涵盖 shell/文件操作/patch，但没有网络搜索、浏览器自动化、视觉、图像生成等功能。为了在 Codex 轮次中保持这些工具可用，Hermes 在 `~/.codex/config.toml` 中将自身注册为 MCP server：
-```toml
-[mcp_servers.hermes-tools]
-command = "/path/to/python"
-args = ["-m", "agent.transports.hermes_tools_mcp_server"]
-env = { HERMES_HOME = "/your/.hermes", PYTHONPATH = "...", HERMES_QUIET = "1" }
-startup_timeout_sec = 30.0
-tool_timeout_sec = 600.0
-```
-当模型调用 `web_search`（或其他暴露的 Hermes 工具）时，Codex 通过 stdio 生成 `hermes_tools_mcp_server` 子进程，请求通过 `model_tools.handle_function_call()` 分发，结果像其他 MCP 响应一样投影回 Codex。
-**通过回调可用的工具：** `web_search`、`web_extract`、`browser_navigate`、`browser_click`、`browser_type`、`browser_press`、`browser_snapshot`、`browser_scroll`、`browser_back`、`browser_get_images`、`browser_console`、`browser_vision`、`vision_analyze`、`image_generate`、`skill_view`、`skills_list`、`text_to_speech`。
-**不可用的工具：** `delegate_task`、`memory`、`session_search`、`todo`。这些工具需要运行中的 AIAgent 上下文（循环中间状态）才能分发，无状态的 MCP 回调无法驱动它们。需要这些工具时，请使用默认 Hermes 运行时（`/codex-runtime auto`）。
-## 禁用
-随时切换回来：
-```
-/codex-runtime auto
-```
-在下一个会话生效。Codex 管理块保留在 `~/.codex/config.toml` 中，以便你之后重新启用时不会丢失配置——如果你希望，也可以手动删除它。
-## 限制
-此运行时为**可选启用的 beta 功能**。以下功能在 Hermes Agent 2026.5 + Codex CLI 0.130.0 上已验证可用：
-- 多轮对话
-- 通过 Hermes UI 进行 `commandExecution` 和 `fileChange`（apply_patch）审批
-- MCP 工具调用（已针对 `@modelcontextprotocol/server-filesystem` 和新的 `hermes-tools` 回调验证）
-- 原生 Codex 插件迁移（已针对 Linear / GitHub / Calendar 清单验证）
-- 拒绝/取消路径
-- 开关切换循环
-- 记忆和技能提示计数器（已通过集成测试实时验证）
-- 通过 Codex 使用 Hermes web_search（已实时验证："OpenAI Codex CLI – Getting Started" 端到端返回结果）
-已知限制：
-- **Hermes 认证和 Codex 认证是独立的会话。** 为获得最佳体验，你需要同时运行 `codex login` 和 `hermes auth login codex`（运行时使用 Codex 的会话进行 LLM 调用）。这是 Hermes `_import_codex_cli_tokens` 中的有意设计——Hermes 不会与 Codex CLI 共享 OAuth 状态，以避免在 token 刷新时相互覆盖。
-- **`delegate_task`、`memory`、`session_search`、`todo` 在此运行时上不可用。** 它们需要运行中的 AIAgent 上下文，无状态的 MCP 回调无法提供。需要这些工具时，请使用 `/codex-runtime auto`。
-- **当 Codex 未跟踪变更集时，审批提示中没有内联 patch 预览。** Codex 的 `fileChange` 审批参数并不总是携带变更集。Hermes 会尽可能从对应的 `item/started` 通知中缓存数据，但如果审批在事件项流式传输完成之前到达，提示会回退到 Codex 提供的 `reason`。
-- **亚秒级取消无法保证。** 流式传输中途的中断（Codex 响应时按 Ctrl+C）通过 `turn/interrupt` 发送，但如果 Codex 已经刷新了最终消息，你仍会收到该响应。
-如果你发现 bug，请[提交 issue](https://github.com/NousResearch/hermes-agent/issues)，附上 `hermes logs --since 5m` 的输出。在标题中注明 `codex-runtime` 以便于分类处理。
-## 架构
-```
-                ┌─── Hermes shell (CLI / TUI / gateway) ───┐
-                │  sessions DB · slash commands · memory   │
-                │  & skill review · cron · session pickers │
-                └──┬──────────────────────────────────────┬┘
-                   │ user_message               final     │
-                   ▼                            text +    │
-        ┌──────────────────────────────────┐   projected  │
-        │  AIAgent.run_conversation()       │   messages   │
-        │   if api_mode == codex_app_server │              │
-        │     → CodexAppServerSession       │              │
-        │   else: chat_completions / codex_responses (default)
-        └────┬─────────────────────────────┘              │
-             │ JSON-RPC over stdio                        │
-             ▼                                            │
-        ┌──────────────────────────────────┐              │
-        │  codex app-server (subprocess)    │──────────────┘
-        │   thread/start, turn/start        │
-        │   item/* notifications            │
-        │   shell + apply_patch + update_plan│
-        │   view_image + sandbox            │
-        │   ┌─────────────────────────┐     │
-        │   │  MCP client             │     │
-        │   │  ├─ user MCP servers    │     │
-        │   │  ├─ native plugins      │     │
-        │   │  │   (linear, github,   │     │
-        │   │  │    gmail, calendar,  │     │
-        │   │  │    canva, ...)       │     │
-        │   │  └─ hermes-tools ───────┼─────────────────┐
-        │   │       (callback to     │     │           │
-        │   │        Hermes' richer  │     │           │
-        │   │        tools)          │     │           │
-        │   └─────────────────────────┘     │           │
-        └──────────────────────────────────┘           │
-                                                        │
-                                                        ▼
-        ┌──────────────────────────────────────────────────────────┐
-        │  hermes_tools_mcp_server.py (subprocess on demand)        │
-        │   web_search, web_extract, browser_*, vision_analyze,    │
-        │   image_generate, skill_view, skills_list, text_to_speech│
-        └──────────────────────────────────────────────────────────┘
-```
-有关实现细节，请参阅 [PR #24182](https://github.com/NousResearch/hermes-agent/pull/24182) 和 [Codex app-server 协议 README](https://github.com/openai/codex/blob/main/codex-rs/app-server/README.md)。

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/features/computer-use.md DELETED Viewed

@@ -1,144 +0,0 @@
----
-title: 电脑操控
-sidebar_position: 16
----
-# 电脑操控（macOS）
-Hermes Agent 可以在**后台**驱动你的 Mac 桌面——点击、输入、滚动、拖拽。你的光标不会移动，键盘焦点不会改变，macOS 也不会切换 Spaces。你和 Agent 可以在同一台机器上协同工作。
-与大多数电脑操控集成不同，这适用于**任何支持工具调用的模型**——Claude、GPT、Gemini，或本地 vLLM 端点上的开源模型。无需关心 Anthropic 原生 schema。
-## 工作原理
-`computer_use` 工具集通过 stdio 以 MCP 协议与 [`cua-driver`](https://github.com/trycua/cua) 通信。`cua-driver` 是一个 macOS 驱动，使用 SkyLight 私有 SPI（`SLEventPostToPid`、`SLPSPostEventRecordTo`）以及 `_AXObserverAddNotificationAndCheckRemote` 无障碍 SPI，实现以下功能：
-- 直接向目标进程投递合成事件——无需 HID 事件 tap，无需光标跳转。
-- 在不提升窗口的情况下切换 AppKit 激活状态——不触发 Space 切换。
-- 在窗口被遮挡时保持 Chromium/Electron 无障碍树存活。
-这一组合正是 OpenAI Codex「后台电脑操控」所采用的方案。cua-driver 是其开源等价实现。
-## 启用
-选择最方便的方式——两种方式运行的是同一个上游安装程序：
-**方式一：使用专用 CLI 命令（最直接）。**
-```
-hermes computer-use install
-```
-此命令会获取并运行上游 cua-driver 安装脚本：
-`curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.sh`。
-使用 `hermes computer-use status` 验证安装结果。
-**方式二：通过交互式界面启用工具集。**
-1. 运行 `hermes tools`，选择 `🖱️ Computer Use (macOS)` → `cua-driver (background)`。
-2. 安装程序将运行上游安装脚本（与方式一相同）。
-安装完成后，无论采用哪种方式，继续执行以下步骤：
-3. 在提示时授予 macOS 权限：
-   - **系统设置 → 隐私与安全性 → 辅助功能** → 允许终端（或 Hermes 应用）。
-   - **系统设置 → 隐私与安全性 → 屏幕录制** → 允许同一应用。
-4. 启动启用了该工具集的会话：
-   ```
-   hermes -t computer_use chat
-   ```
-   或在 `~/.hermes/config.yaml` 中将 `computer_use` 添加到已启用的工具集列表。
-## 保持 cua-driver 最新
-cua-driver 项目会定期发布修复（例如 v0.1.6 修复了 UTM 工作流中的 Safari 窗口焦点问题）。Hermes 在两处刷新二进制文件，避免你停留在过时版本：
-- **`hermes update`** — 更新 Hermes 本身时，如果 `cua-driver` 在 PATH 中，更新结束时会重新运行上游安装程序。对非 macOS 用户及未安装 cua-driver 的用户无操作。
-- **`hermes computer-use install --upgrade`** — 手动强制刷新。无论 cua-driver 是否已安装，都会重新运行上游安装程序。在不等待下次 Agent 更新的情况下获取最新修复时使用此命令。
-`hermes computer-use status` 会在二进制路径旁显示已安装的版本号。
-## 快速示例
-用户 prompt（提示词）：*「找到我最近一封来自 Stripe 的邮件，总结他们希望我做什么。」*
-Agent 的执行计划：
-1. `computer_use(action="capture", mode="som", app="Mail")` — 获取 Mail 的截图，其中每个侧边栏项目、工具栏按钮和邮件行均已编号。
-2. `computer_use(action="click", element=14)` — 点击搜索框（来自截图的第 #14 号元素）。
-3. `computer_use(action="type", text="from:stripe")`
-4. `computer_use(action="key", keys="return", capture_after=True)` — 提交并获取新截图。
-5. 点击最顶部的结果，读取正文，进行总结。
-整个过程中，你的光标保持原位，Mail 窗口始终不会切换到前台。
-## 提供商兼容性
-| 提供商 | 支持视觉？ | 可用？ | 备注 |
-|---|---|---|---|
-| Anthropic（Claude Sonnet/Opus 3+） | ✅ | ✅ | 综合表现最佳；支持 SOM 与原始坐标。 |
-| OpenRouter（任意视觉模型） | ✅ | ✅ | 支持多部分工具消息。 |
-| OpenAI（GPT-4+、GPT-5） | ✅ | ✅ | 同上。 |
-| 本地 vLLM / LM Studio（视觉模型） | ✅ | ✅ | 需模型支持多部分工具内容。 |
-| 纯文本模型 | ❌ | ✅（降级） | 使用 `mode="ax"` 仅通过无障碍树操作。 |
-截图以 OpenAI 风格的 `image_url` 部分内联在工具结果中发送。对于 Anthropic，适配器会将其转换为原生 `tool_result` 图像块。
-## 安全性
-Hermes 应用多层防护机制：
-- 破坏性操作（click、type、drag、scroll、key、focus_app）需要审批——通过 CLI 对话框交互确认，或通过消息平台审批按钮确认。
-- 工具层面硬性屏蔽的按键组合：清空废纸篓、强制删除、锁定屏幕、注销、强制注销。
-- 硬性屏蔽的输入模式：`curl | bash`、`sudo rm -rf /`、fork bomb 等。
-- Agent 的系统 prompt 明确规定：不得点击权限对话框，不得输入密码，不得执行截图中嵌入的指令。
-如需对每个操作进行确认，可在 `~/.hermes/config.yaml` 中配置 `approvals.mode: manual`。
-## Token 效率
-截图开销较大。Hermes 应用四层优化措施：
-- **截图淘汰** — Anthropic 适配器在上下文中仅保留最近 3 张截图；较旧的截图替换为 `[screenshot removed to save context]` 占位符。
-- **客户端压缩裁剪** — 上下文压缩器检测多模态工具结果，并从旧结果中剥离图像部分。
-- **图像感知 token 估算** — 每张图像计为约 1500 个 token（Anthropic 的固定费率），而非其 base64 字符长度。
-- **服务端上下文编辑（仅限 Anthropic）** — 激活后，适配器通过 `context_management` 启用 `clear_tool_uses_20250919`，由 Anthropic API 在服务端清除旧工具结果。
-在 1568×900 分辨率下执行 20 个操作的会话，截图上下文通常消耗约 3 万个 token，而非约 60 万个。
-## 限制
-- **仅限 macOS。** cua-driver 使用的私有 Apple SPI 在 Linux 或 Windows 上不存在。跨平台 GUI 自动化请使用 `browser` 工具集。
-- **私有 SPI 风险。** Apple 可能在任何 OS 更新中更改 SkyLight 的符号接口。Hermes 始终安装最新版 cua-driver，并在已安装的二进制文件低于其测试基线版本（按操作系统分别设定）时发出警告。没有版本固定开关——如需可复现的版本，请将 `HERMES_CUA_DRIVER_CMD` 指向特定的二进制文件。
-- **性能。** 后台模式比前台模式慢——SkyLight 路由事件耗时约 5–20ms，而直接 HID 投递更快。对于 Agent 速度的点击操作无明显影响；若尝试录制速通视频则会有感知。
-- **不支持键盘输入密码。** `type` 对命令行 payload 有硬性屏蔽模式；密码请使用系统自动填充功能。
-## 配置
-覆盖驱动二进制路径（用于测试 / CI）：
-```
-HERMES_CUA_DRIVER_CMD=/opt/homebrew/bin/cua-driver
-```
-完全替换后端（用于测试）：
-```
-HERMES_COMPUTER_USE_BACKEND=noop   # records calls, no side effects
-```
-## 故障排查
-**`computer_use backend unavailable: cua-driver is not installed`** — 运行 `hermes computer-use install` 获取 cua-driver 二进制文件，或运行 `hermes tools` 并启用 Computer Use 工具集。
-**点击似乎没有效果** — 截图并验证。可能有一个你未注意到的模态框正在阻止输入。使用 `escape` 或关闭按钮将其关闭。
-**元素索引已过期** — SOM 索引仅在下次 `capture` 之前有效。任何改变状态的操作后请重新截图。
-**「blocked pattern in type text」** — 你尝试 `type` 的文本匹配了危险 shell 模式列表。请拆分命令或重新考虑操作方式。
-## 另请参阅
-- [通用技能：`macos-computer-use`](https://github.com/NousResearch/hermes-agent/blob/main/skills/apple/macos-computer-use/SKILL.md)
-- [cua-driver 源码（trycua/cua）](https://github.com/trycua/cua)
-- 跨平台 Web 任务请参阅[浏览器自动化](./browser.md)。