better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/features/built-in-plugins.md

@@ -0,0 +1,269 @@
+---
+sidebar_position: 12
+sidebar_label: "内置插件"
+title: "内置插件"
+description: "随 Hermes Agent 附带并通过生命周期 hook 自动运行的插件——disk-cleanup 等"
+---
+
+# 内置插件
+
+Hermes 随仓库附带了一小组插件。它们位于 `<repo>/plugins/<name>/`，与用户安装在 `~/.hermes/plugins/` 中的插件一同自动加载。它们使用与第三方插件相同的插件接口——hook、工具、斜杠命令——只是在仓库内维护。
+
+请参阅 [插件](/user-guide/features/plugins) 页面了解通用插件系统，以及 [构建 Hermes 插件](/developer-guide/plugins) 了解如何编写自己的插件。
+
+## 发现机制
+
+`PluginManager` 按顺序扫描四个来源：
+
+1. **内置（Bundled）** — `<repo>/plugins/<name>/`（本页所记录的内容）
+2. **用户（User）** — `~/.hermes/plugins/<name>/`
+3. **项目（Project）** — `./.hermes/plugins/<name>/`（需要 `HERMES_ENABLE_PROJECT_PLUGINS=1`）
+4. **Pip 入口点（Entry points）** — `hermes_agent.plugins`
+
+名称冲突时，后面的来源优先——名为 `disk-cleanup` 的用户插件会替换内置版本。
+
+`plugins/memory/` 和 `plugins/context_engine/` 被刻意排除在内置扫描之外。这两个目录使用各自的发现路径，因为内存提供者和上下文引擎是通过 `hermes memory setup` / 配置中的 `context.engine` 进行单选配置的提供者。
+
+## 内置插件默认不启用
+
+内置插件随附时处于禁用状态。发现机制会找到它们（它们会出现在 `hermes plugins list` 和交互式 `hermes plugins` UI 中），但在你明确启用之前不会加载：
+
+```bash
+hermes plugins enable disk-cleanup
+```
+
+或通过 `~/.hermes/config.yaml`：
+
+```yaml
+plugins:
+  enabled:
+    - disk-cleanup
+```
+
+这与用户安装的插件使用的机制相同。内置插件永远不会自动启用——无论是全新安装，还是现有用户升级到更新版本的 Hermes，都需要你明确选择启用。
+
+要再次关闭内置插件：
+
+```bash
+hermes plugins disable disk-cleanup
+# 或：从 config.yaml 的 plugins.enabled 中移除它
+```
+
+## 当前附带的插件
+
+仓库在 `plugins/` 下附带了以下内置插件。所有插件均需手动启用——通过 `hermes plugins enable <name>` 启用。
+
+| 插件 | 类型 | 用途 |
+|---|---|---|
+| `disk-cleanup` | hook + 斜杠命令 | 自动追踪临时文件并在会话结束时清理 |
+| `observability/langfuse` | hook | 将轮次 / LLM 调用 / 工具追踪到 [Langfuse](https://langfuse.com) |
+| `spotify` | 后端（7 个工具） | 原生 Spotify 播放、队列、搜索、播放列表、专辑、曲库 |
+| `google_meet` | 独立插件 | 加入 Meet 通话、实时字幕转录、可选实时双工音频 |
+| `image_gen/openai` | 图像后端 | OpenAI `gpt-image-2` 图像生成后端（FAL 的替代方案） |
+| `image_gen/openai-codex` | 图像后端 | 通过 Codex OAuth 使用 OpenAI 图像生成 |
+| `image_gen/xai` | 图像后端 | xAI `grok-2-image` 后端 |
+| `hermes-achievements` | 仪表盘标签页 | Steam 风格的可收集徽章，根据你真实的 Hermes 会话历史生成 |
+| `kanban/dashboard` | 仪表盘标签页 | 多智能体调度器的看板（Kanban）UI——任务、评论、扇出、切换看板。参见 [Kanban 多智能体](./kanban.md)。 |
+
+内存提供者（`plugins/memory/*`）和上下文引擎（`plugins/context_engine/*`）在 [内存提供者](./memory-providers.md) 中单独列出——它们分别通过 `hermes memory` 和 `hermes plugins` 管理。以下是两个长期运行的基于 hook 的插件的详细说明。
+
+### disk-cleanup
+
+自动追踪并删除会话期间创建的临时文件——测试脚本、临时输出、cron 日志、过期的 Chrome 配置文件——无需 agent 记住调用工具。
+
+**工作原理：**
+
+| Hook | 行为 |
+|---|---|
+| `post_tool_call` | 当 `write_file` / `terminal` / `patch` 在 `HERMES_HOME` 或 `/tmp/hermes-*` 内创建匹配 `test_*`、`tmp_*` 或 `*.test.*` 的文件时，静默追踪为 `test` / `temp` / `cron-output`。 |
+| `on_session_end` | 如果本轮中有任何测试文件被自动追踪，则执行安全的 `quick` 清理并记录一行摘要。否则保持静默。 |
+
+**删除规则：**
+
+| 类别 | 阈值 | 确认 |
+|---|---|---|
+| `test` | 每次会话结束 | 从不 |
+| `temp` | 追踪后超过 7 天 | 从不 |
+| `cron-output` | 追踪后超过 14 天 | 从不 |
+| HERMES_HOME 下的空目录 | 始终 | 从不 |
+| `research` | 超过 30 天，且超出最新 10 个 | 始终（仅 deep 模式） |
+| `chrome-profile` | 追踪后超过 14 天 | 始终（仅 deep 模式） |
+| 超过 500 MB 的文件 | 从不自动删除 | 始终（仅 deep 模式） |
+
+**斜杠命令** — `/disk-cleanup` 在 CLI 和 gateway 会话中均可用：
+
+```
+/disk-cleanup status                     # 分类明细 + 最大的 10 个文件
+/disk-cleanup dry-run                    # 预览，不实际删除
+/disk-cleanup quick                      # 立即执行安全清理
+/disk-cleanup deep                       # quick + 列出需要确认的项目
+/disk-cleanup track <path> <category>    # 手动追踪
+/disk-cleanup forget <path>              # 停止追踪（不删除）
+```
+
+**状态** — 所有内容存储在 `$HERMES_HOME/disk-cleanup/`：
+
+| 文件 | 内容 |
+|---|---|
+| `tracked.json` | 已追踪路径，包含类别、大小和时间戳 |
+| `tracked.json.bak` | 上述文件的原子写入备份 |
+| `cleanup.log` | 每次追踪 / 跳过 / 拒绝 / 删除操作的仅追加审计日志 |
+
+**安全性** — 清理操作仅涉及 `HERMES_HOME` 或 `/tmp/hermes-*` 下的路径。Windows 挂载点（`/mnt/c/...`）会被拒绝。已知的顶级状态目录（`logs/`、`memories/`、`sessions/`、`cron/`、`cache/`、`skills/`、`plugins/`、`disk-cleanup/` 本身）即使为空也不会被删除——全新安装不会在第一次会话结束时被清空。
+
+**启用：** `hermes plugins enable disk-cleanup`（或在 `hermes plugins` 中勾选复选框）。
+
+**再次禁用：** `hermes plugins disable disk-cleanup`。
+
+### observability/langfuse
+
+将 Hermes 的轮次、LLM 调用和工具调用追踪到 [Langfuse](https://langfuse.com)——一个开源 LLM 可观测性平台。每轮一个 span，每次 API 调用一个 generation，每次工具调用一个 tool observation。用量总计、各类型 token 数量和成本估算来自 Hermes 的标准 `agent.usage_pricing` 数据，因此 Langfuse 仪表盘看到的分类（input / output / `cache_read_input_tokens` / `cache_creation_input_tokens` / `reasoning_tokens`）与 `hermes logs` 中显示的一致。
+
+该插件采用失败开放（fail-open）策略：未安装 SDK、无凭据或 Langfuse 出现瞬时错误——所有情况都会在 hook 中静默处理为无操作。agent 循环不受任何影响。
+
+**设置：**
+
+```bash
+pip install langfuse
+hermes plugins enable observability/langfuse
+```
+
+或在交互式 `hermes plugins` UI 中勾选复选框。然后将凭据写入 `~/.hermes/.env`：
+
+```bash
+HERMES_LANGFUSE_PUBLIC_KEY=pk-lf-...
+HERMES_LANGFUSE_SECRET_KEY=sk-lf-...
+HERMES_LANGFUSE_BASE_URL=https://cloud.langfuse.com   # 或你的自托管 URL
+```
+
+**工作原理：**
+
+| Hook | 行为 |
+|---|---|
+| `pre_api_request` / `pre_llm_call` | 打开（或复用）每轮的根 span "Hermes turn"。为本次 API 调用启动一个 `generation` 子 observation，将最近的消息序列化为输入。 |
+| `post_api_request` / `post_llm_call` | 关闭 generation，附加 `usage_details`、`cost_details`、`finish_reason`、助手输出和工具调用。如果没有工具调用且内容非空，则关闭本轮。 |
+| `pre_tool_call` | 启动一个带有经过清理的 `args` 的 `tool` 子 observation。 |
+| `post_tool_call` | 关闭 tool observation，附加经过清理的 `result`。`read_file` 的内容会被摘要化（头部 + 尾部 + 省略行数），以使大文件读取保持在 `HERMES_LANGFUSE_MAX_CHARS` 以内。 |
+
+会话分组基于 Hermes 会话 ID（或子 agent 的任务 ID），通过 `langfuse.propagate_attributes` 实现，因此单次 `hermes chat` 会话中的所有内容都归属于同一个 Langfuse session。
+
+**验证：**
+
+```bash
+hermes plugins list                 # observability/langfuse 应显示 "enabled"
+hermes chat -q "hello"              # 在 Langfuse UI 中检查是否有 "Hermes turn" trace
+```
+
+**可选调优**（在 `.env` 中）：
+
+| 变量 | 默认值 | 用途 |
+|---|---|---|
+| `HERMES_LANGFUSE_ENV` | — | trace 上的环境标签（`production`、`staging` 等） |
+| `HERMES_LANGFUSE_RELEASE` | — | 发布/版本标签 |
+| `HERMES_LANGFUSE_SAMPLE_RATE` | `1.0` | 传递给 SDK 的采样率（0.0–1.0） |
+| `HERMES_LANGFUSE_MAX_CHARS` | `12000` | 消息内容 / 工具参数 / 工具结果的单字段截断长度 |
+| `HERMES_LANGFUSE_DEBUG` | `false` | 向 `agent.log` 输出详细插件日志 |
+
+Hermes 前缀的环境变量和标准 SDK 环境变量（`LANGFUSE_PUBLIC_KEY`、`LANGFUSE_SECRET_KEY`、`LANGFUSE_BASE_URL`）均被接受——两者同时设置时，Hermes 前缀的优先。
+
+**性能：** Langfuse 客户端在第一次 hook 调用后被缓存。如果凭据或 SDK 缺失，该决定也会被缓存——后续 hook 会快速返回，不再重新检查环境变量或重新加载配置。
+
+**禁用：** `hermes plugins disable observability/langfuse`。插件模块仍会被发现，但在你重新启用之前不会运行任何模块代码。
+
+### google_meet
+
+让 agent **加入、转录并参与 Google Meet 通话**——记录会议笔记、事后总结对话内容、跟进特定要点，并可选择通过 TTS 将回复发回通话中。
+
+**新增功能：**
+
+- 使用浏览器自动化加入 Meet URL 的无头虚拟参与者
+- 通过配置的 STT 提供者对会议音频进行实时转录
+- agent 调用的 `meet_summarize` / `meet_speak` / `meet_followup` 工具集，用于对所听内容采取行动
+- 会后产物（转录、带发言人归属的笔记、行动项）保存在 `~/.hermes/cache/google_meet/<meeting_id>/`
+
+**设置：**
+
+```bash
+hermes plugins enable google_meet
+# 首次使用时会提示你通过插件的 OAuth 流程登录——
+# 需要有 Meet 访问权限的 Google 账号。如果会议强制要求
+# "仅受邀参与者可加入"，可能需要主持人批准。
+```
+
+在聊天中使用：
+
+> "加入 meet.google.com/abc-defg-hij 并记录笔记。通话结束后，给我发一份包含行动项的摘要。"
+
+agent 会启动会议加入流程，在通话进行时将转录内容流式传输到其上下文中，并在会议结束（或你告知停止）时生成结构化摘要。
+
+**适用场景：** 需要机器人转录并为异步参与者总结的定期站会；需要结构化笔记的访谈式会议；任何原本需要 Fireflies / Otter / Grain 的场景。如果你不希望有 AI 在旁监听——请勿启用。
+
+**禁用：** `hermes plugins disable google_meet`。已缓存的转录和录音保留在 `~/.hermes/cache/google_meet/`，直到你手动删除。
+
+### hermes-achievements
+
+在仪表盘中添加一个 **Steam 风格的成就标签页**——60 多个可收集的分级徽章，根据你真实的 Hermes 会话历史生成。工具链成就、调试模式、vibe-coding 连击、技能/内存使用、模型/提供者多样性、生活方式特征（周末和夜间会话）。最初由 [@PCinkusz](https://github.com/PCinkusz) 作为外部插件编写；已并入仓库，以便与 Hermes 功能变更保持同步。
+
+**工作原理：**
+
+- 在仪表盘后端扫描你的整个 `~/.hermes/state.db` 会话历史
+- 每个会话的统计数据按 `(started_at, last_active)` 指纹缓存，因此后续扫描只重新分析新增或变更的会话
+- 首次扫描在后台线程中运行——即使数据库有数千个会话，仪表盘也不会阻塞等待
+- 解锁状态持久化到 `$HERMES_HOME/plugins/hermes-achievements/state.json`
+
+**等级进阶：** 铜 → 银 → 金 → 钻石 → 奥林匹斯。每张卡片都有"计算方式"部分，列出所追踪的确切指标。
+
+**成就状态：**
+
+| 状态 | 含义 |
+|---|---|
+| 已解锁 | 至少达到一个等级 |
+| 已发现 | 已知成就，进度可见，尚未获得 |
+| 隐藏 | 在 Hermes 检测到你历史中的第一个相关信号之前保持隐藏 |
+
+**API** — 路由挂载在 `/api/plugins/hermes-achievements/` 下：
+
+| 端点 | 用途 |
+|---|---|
+| `GET /achievements` | 完整目录，包含每个徽章的解锁状态（首次冷扫描运行期间返回待处理占位符） |
+| `GET /scan-status` | 后台扫描器状态：`idle` / `running` / `failed`，上次耗时，运行次数 |
+| `GET /recent-unlocks` | 最近解锁的 20 个徽章，最新的在前 |
+| `GET /sessions/{id}/badges` | 主要在某个特定会话中获得的徽章 |
+| `POST /rescan` | 手动同步重新扫描（阻塞；在用户点击重新扫描按钮时使用） |
+| `POST /reset-state` | 清除解锁历史和缓存快照 |
+
+**状态文件** — 位于 `$HERMES_HOME/plugins/hermes-achievements/`：
+
+| 文件 | 内容 |
+|---|---|
+| `state.json` | 解锁历史：你获得了哪些徽章以及获得时间。在 Hermes 更新间保持稳定。 |
+| `scan_snapshot.json` | 上次完成的扫描载荷（在仪表盘加载时立即提供） |
+| `scan_checkpoint.json` | 按指纹键控的每会话统计缓存（使热重扫描更快） |
+
+**性能说明：**
+
+- 约 8,000 个会话的冷扫描需要几分钟。它在首次仪表盘请求时在后台线程中运行；UI 显示待处理占位符并轮询 `/scan-status`。
+- **冷扫描期间的增量结果** — 扫描器每约 250 个会话发布一次部分快照，因此每次仪表盘刷新都会显示更多已解锁的徽章。不会出现盯着零数字等待一分钟的情况。
+- 热重扫描对每个 `started_at` + `last_active` 指纹与检查点匹配的会话复用每会话统计——即使在大型历史记录上也能在几秒内完成。
+- 内存快照 TTL 为 120 秒；过期请求立即提供旧快照并触发后台刷新。不会因为 TTL 过期就让你等待加载动画。
+
+**启用：** 无需启用——`hermes-achievements` 是一个仅限仪表盘的插件（无生命周期 hook，无模型可见工具）。它在 `hermes dashboard` 首次启动时自动注册为标签页。`plugins.enabled` 配置仅控制生命周期/工具插件；仪表盘插件完全通过其 `dashboard/manifest.json` 发现。
+
+**退出：** 删除或重命名 `plugins/hermes-achievements/dashboard/manifest.json`，或在 `~/.hermes/plugins/hermes-achievements/` 中用同名用户插件覆盖它（该插件不包含仪表盘）。`$HERMES_HOME/plugins/hermes-achievements/` 下的插件状态文件会保留——重新安装后你的解锁历史依然存在。
+
+## 添加内置插件
+
+内置插件的编写方式与其他 Hermes 插件完全相同——参见 [构建 Hermes 插件](/developer-guide/plugins)。唯一的区别是：
+
+- 目录位于 `<repo>/plugins/<name>/`，而非 `~/.hermes/plugins/<name>/`
+- 在 `hermes plugins list` 中，manifest 来源显示为 `bundled`
+- 同名用户插件会覆盖内置版本
+
+以下情况适合将插件纳入内置：
+
+- 没有可选依赖项（或它们已经是 `pip install .[all]` 的依赖）
+- 该行为对大多数用户有益，且是默认启用、需要主动关闭的
+- 逻辑与生命周期 hook 紧密结合，否则 agent 需要记住手动调用
+- 在不扩展模型可见工具接口的前提下补充核心能力
+
+反例——应作为用户可安装插件而非内置插件的情况：需要 API 密钥的第三方集成、小众工作流、大型依赖树、任何会默认改变 agent 行为的内容。

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/features/code-execution.md

@@ -0,0 +1,240 @@
+---
+sidebar_position: 8
+title: "代码执行"
+description: "通过 RPC 工具访问实现程序化 Python 执行——将多步骤工作流压缩至单次对话轮次"
+---
+
+# 代码执行（程序化工具调用）
+
+`execute_code` 工具允许 agent 编写调用 Hermes 工具的 Python 脚本，将多步骤工作流压缩至单次 LLM 对话轮次。脚本在 agent 宿主机的子进程中运行，通过 Unix 域套接字 RPC 与 Hermes 通信。
+
+## 工作原理
+
+1. Agent 编写使用 `from hermes_tools import ...` 的 Python 脚本
+2. Hermes 生成带有 RPC 函数的 `hermes_tools.py` 存根模块
+3. Hermes 打开 Unix 域套接字并启动 RPC 监听线程
+4. 脚本在子进程中运行——工具调用通过套接字传回 Hermes
+5. 只有脚本的 `print()` 输出会返回给 LLM；中间工具结果不会进入上下文窗口
+
+```python
+# The agent can write scripts like:
+from hermes_tools import web_search, web_extract
+
+results = web_search("Python 3.13 features", limit=5)
+for r in results["data"]["web"]:
+    content = web_extract([r["url"]])
+    # ... filter and process ...
+print(summary)
+```
+
+**脚本内可用工具：** `web_search`、`web_extract`、`read_file`、`write_file`、`search_files`、`patch`、`terminal`（仅前台模式）。
+
+## Agent 何时使用此功能
+
+当存在以下情况时，agent 会使用 `execute_code`：
+
+- **3 次及以上工具调用**，且调用之间包含处理逻辑
+- 批量数据过滤或条件分支
+- 对结果进行循环处理
+
+核心优势：中间工具结果不会进入上下文窗口——只有最终的 `print()` 输出会返回，大幅降低 token 用量。
+
+## 实际示例
+
+### 数据处理流水线
+
+```python
+from hermes_tools import search_files, read_file
+import json
+
+# Find all config files and extract database settings
+matches = search_files("database", path=".", file_glob="*.yaml", limit=20)
+configs = []
+for match in matches.get("matches", []):
+    content = read_file(match["path"])
+    configs.append({"file": match["path"], "preview": content["content"][:200]})
+
+print(json.dumps(configs, indent=2))
+```
+
+### 多步骤网络调研
+
+```python
+from hermes_tools import web_search, web_extract
+import json
+
+# Search, extract, and summarize in one turn
+results = web_search("Rust async runtime comparison 2025", limit=5)
+summaries = []
+for r in results["data"]["web"]:
+    page = web_extract([r["url"]])
+    for p in page.get("results", []):
+        if p.get("content"):
+            summaries.append({
+                "title": r["title"],
+                "url": r["url"],
+                "excerpt": p["content"][:500]
+            })
+
+print(json.dumps(summaries, indent=2))
+```
+
+### 批量文件重构
+
+```python
+from hermes_tools import search_files, read_file, patch
+
+# Find all Python files using deprecated API and fix them
+matches = search_files("old_api_call", path="src/", file_glob="*.py")
+fixed = 0
+for match in matches.get("matches", []):
+    result = patch(
+        path=match["path"],
+        old_string="old_api_call(",
+        new_string="new_api_call(",
+        replace_all=True
+    )
+    if "error" not in str(result):
+        fixed += 1
+
+print(f"Fixed {fixed} files out of {len(matches.get('matches', []))} matches")
+```
+
+### 构建与测试流水线
+
+```python
+from hermes_tools import terminal, read_file
+import json
+
+# Run tests, parse results, and report
+result = terminal("cd /project && python -m pytest --tb=short -q 2>&1", timeout=120)
+output = result.get("output", "")
+
+# Parse test output
+passed = output.count(" passed")
+failed = output.count(" failed")
+errors = output.count(" error")
+
+report = {
+    "passed": passed,
+    "failed": failed,
+    "errors": errors,
+    "exit_code": result.get("exit_code", -1),
+    "summary": output[-500:] if len(output) > 500 else output
+}
+
+print(json.dumps(report, indent=2))
+```
+
+## 执行模式
+
+`execute_code` 有两种执行模式，通过 `~/.hermes/config.yaml` 中的 `code_execution.mode` 控制：
+
+| 模式 | 工作目录 | Python 解释器 |
+|------|----------|---------------|
+| **`project`**（默认） | 会话的工作目录（与 `terminal()` 相同） | 活跃的 `VIRTUAL_ENV` / `CONDA_PREFIX` python，回退至 Hermes 自身的 python |
+| `strict` | 与用户项目隔离的临时暂存目录 | `sys.executable`（Hermes 自身的 python） |
+
+**何时保持 `project` 模式：** 当你希望 `import pandas`、`from my_project import foo` 或 `open(".env")` 等相对路径与 `terminal()` 中的行为一致时。这几乎是你始终想要的模式。
+
+**何时切换至 `strict` 模式：** 当你需要最大可复现性时——希望无论用户激活哪个 venv，每次会话都使用相同的解释器，并且希望脚本与项目目录隔离（避免通过相对路径意外读取项目文件）。
+
+```yaml
+# ~/.hermes/config.yaml
+code_execution:
+  mode: project   # or "strict"
+```
+
+`project` 模式的回退行为：若 `VIRTUAL_ENV` / `CONDA_PREFIX` 未设置、已损坏或指向低于 3.8 的 Python，解析器会干净地回退至 `sys.executable`——agent 始终有可用的解释器。
+
+两种模式的安全关键不变量完全相同：
+
+- 环境变量清理（API key、token、凭据默认被剥离）
+- 工具白名单（脚本不能递归调用 `execute_code`、`delegate_task` 或 MCP 工具）
+- 资源限制（超时、stdout 上限、工具调用上限）
+
+切换模式只改变脚本的运行位置和使用的解释器，不改变脚本可见的凭据或可调用的工具。
+
+## 资源限制
+
+| 资源 | 限制 | 说明 |
+|------|------|------|
+| **超时** | 5 分钟（300 秒） | 脚本先收到 SIGTERM，5 秒宽限期后收到 SIGKILL |
+| **Stdout** | 50 KB | 输出截断并附加 `[output truncated at 50KB]` 提示 |
+| **Stderr** | 10 KB | 非零退出时包含在输出中，用于调试 |
+| **工具调用** | 每次执行 50 次 | 达到上限时返回错误 |
+
+所有限制均可通过 `config.yaml` 配置：
+
+```yaml
+# In ~/.hermes/config.yaml
+code_execution:
+  mode: project      # project (default) | strict
+  timeout: 300       # Max seconds per script (default: 300)
+  max_tool_calls: 50 # Max tool calls per execution (default: 50)
+```
+
+## 脚本内工具调用的工作方式
+
+当脚本调用 `web_search("query")` 等函数时：
+
+1. 调用被序列化为 JSON，通过 Unix 域套接字发送至父进程
+2. 父进程通过标准 `handle_function_call` 处理器进行分发
+3. 结果通过套接字发回
+4. 函数返回解析后的结果
+
+这意味着脚本内的工具调用与普通工具调用行为完全一致——相同的速率限制、相同的错误处理、相同的能力。唯一的限制是 `terminal()` 仅支持前台模式（不支持 `background` 或 `pty` 参数）。
+
+## 错误处理
+
+脚本失败时，agent 会收到结构化的错误信息：
+
+- **非零退出码**：stderr 包含在输出中，agent 可看到完整的 traceback
+- **超时**：脚本被终止，agent 看到 `"Script timed out after 300s and was killed."`
+- **中断**：若用户在执行期间发送新消息，脚本被终止，agent 看到 `[execution interrupted — user sent a new message]`
+- **工具调用上限**：达到 50 次调用上限后，后续工具调用返回错误消息
+
+响应始终包含 `status`（success/error/timeout/interrupted）、`output`、`tool_calls_made` 和 `duration_seconds`。
+
+## 安全性
+
+:::danger 安全模型
+子进程在**最小化环境**中运行。API key、token 和凭据默认被剥离。脚本只能通过 RPC 通道访问工具——除非显式允许，否则无法从环境变量中读取密钥。
+:::
+
+名称中包含 `KEY`、`TOKEN`、`SECRET`、`PASSWORD`、`CREDENTIAL`、`PASSWD` 或 `AUTH` 的环境变量会被排除。只有安全的系统变量（`PATH`、`HOME`、`LANG`、`SHELL`、`PYTHONPATH`、`VIRTUAL_ENV` 等）会被传递。
+
+### Skill 环境变量透传
+
+当 skill 在其 frontmatter 中声明 `required_environment_variables` 时，这些变量会在 skill 加载后**自动透传**至 `execute_code` 和 `terminal` 子进程。这使 skill 可以使用其声明的 API key，而不会削弱任意代码的安全态势。
+
+对于非 skill 场景，可在 `config.yaml` 中显式添加变量白名单：
+
+```yaml
+terminal:
+  env_passthrough:
+    - MY_CUSTOM_KEY
+    - ANOTHER_TOKEN
+```
+
+详情参见[安全指南](/user-guide/security#environment-variable-passthrough)。
+
+Hermes 始终将脚本和自动生成的 `hermes_tools.py` RPC 存根写入临时暂存目录，执行完成后清理。在 `strict` 模式下，脚本也在该目录中*运行*；在 `project` 模式下，脚本在会话的工作目录中运行（暂存目录保留在 `PYTHONPATH` 中以确保导入正常解析）。子进程在独立的进程组中运行，以便在超时或中断时干净地终止。
+
+## execute_code 与 terminal 对比
+
+| 使用场景 | execute_code | terminal |
+|----------|-------------|----------|
+| 调用之间含逻辑的多步骤工作流 | ✅ | ❌ |
+| 简单 shell 命令 | ❌ | ✅ |
+| 过滤/处理大量工具输出 | ✅ | ❌ |
+| 运行构建或测试套件 | ❌ | ✅ |
+| 对搜索结果进行循环处理 | ✅ | ❌ |
+| 交互式/后台进程 | ❌ | ✅ |
+| 需要环境变量中的 API key | ⚠️ 仅通过[透传](/user-guide/security#environment-variable-passthrough) | ✅（大多数可透传） |
+
+**经验法则：** 需要在调用之间含逻辑地程序化调用 Hermes 工具时，使用 `execute_code`。运行 shell 命令、构建和进程时，使用 `terminal`。
+
+## 平台支持
+
+代码执行依赖 Unix 域套接字，仅在 **Linux 和 macOS** 上可用。在 Windows 上会自动禁用——agent 回退至常规的顺序工具调用。