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/curator.md

@@ -0,0 +1,248 @@
+---
+sidebar_position: 3
+title: "Curator"
+description: "Agent 创建的技能的后台维护——使用跟踪、过期检测、归档及 LLM 驱动的审查"
+---
+
+# Curator
+
+Curator 是针对 **agent 创建的技能**的后台维护流程。它跟踪每个技能被查看、使用和修补的频率，将长期未使用的技能经历 `active → stale → archived` 状态流转，并定期启动一个短暂的辅助模型审查，提出合并或修补漂移的建议。
+
+它的存在是为了防止通过[自我改进循环](/user-guide/features/skills#agent-managed-skills-skill_manage-tool)创建的技能无限堆积。每次 agent 解决新问题并保存技能时，该技能都会落入 `~/.hermes/skills/`。若没有维护，最终会出现数十个范围狭窄的近似重复项，污染技能目录并浪费 token（令牌）。
+
+默认情况下（`prune_builtins: true`），Curator 在 `archive_after_days` 天未使用后，可以归档**未使用的捆绑内置技能**（随仓库附带），与它主要管理的 agent 自创技能一并处理。通过 [agentskills.io](https://agentskills.io) 安装的 hub 技能始终不受影响。设置 `curator.prune_builtins: false` 可恢复旧的“仅 agent 自创”行为，此时捆绑技能绝不会被触碰。Curator 也**绝不自动删除**——最坏的结果是归档到 `~/.hermes/skills/.archive/`，这是可恢复的。
+
+跟踪 [issue #7816](https://github.com/NousResearch/hermes-agent/issues/7816)。
+
+## 运行方式
+
+Curator 由空闲检查触发，而非 cron 守护进程。在 CLI 会话启动时，以及 gateway 的 cron-ticker 线程内的周期性 tick 中，Hermes 会检查以下条件是否同时满足：
+
+1. 距上次 curator 运行已过去足够长的时间（`interval_hours`，默认 **7 天**），以及
+2. agent 已空闲足够长的时间（`min_idle_hours`，默认 **2 小时**）。
+
+若两个条件均满足，则会派生一个 `AIAgent` 的后台 fork——与内存/技能自我改进 nudge 使用的模式相同。该 fork 在自己的 prompt（提示词）缓存中运行，绝不触碰当前活跃的对话。
+
+:::info 首次运行行为
+在全新安装时（或 pre-curator 版本在 `hermes update` 后首次 tick 时），curator **不会立即运行**。首次观测会将 `last_run_at` 设为"当前时间"，并将第一次真正的运行推迟整整一个 `interval_hours`。这给了你一个完整的间隔时间来审查技能库、固定重要内容，或在 curator 真正触碰它之前完全退出。
+
+如果你想在 curator 真正运行之前查看它*会*做什么，请运行 `hermes curator run --dry-run`——它会生成相同的审查报告，但不会修改技能库。
+:::
+
+一次运行分为两个阶段：
+
+1. **自动状态转换**（确定性，无 LLM）。未使用时间超过 `stale_after_days`（14 天）的技能变为 `stale`；未使用时间超过 `archive_after_days`（30 天）的技能被移至 `~/.hermes/skills/.archive/`。
+2. **LLM 审查**（单次辅助模型 pass，`max_iterations=8`）。派生的 agent 审查 agent 创建的技能，可通过 `skill_view` 读取任意技能，并逐技能决定是保留、修补（通过 `skill_manage`）、合并重叠项，还是通过终端工具归档。
+
+已固定（pinned）的技能对 curator 的自动状态转换和 agent 自身的 `skill_manage` 工具均不可操作。详见下方[固定技能](#pinning-a-skill)。
+
+## 配置
+
+所有设置位于 `config.yaml` 的 `curator:` 下（不在 `.env` 中——这不是密钥）。默认值：
+
+```yaml
+curator:
+  enabled: true
+  interval_hours: 168          # 7 days
+  min_idle_hours: 2
+  stale_after_days: 14
+  archive_after_days: 30
+```
+
+若要完全禁用，设置 `curator.enabled: false`。
+
+### 在更便宜的辅助模型上运行审查
+
+Curator 的 LLM 审查 pass 是一个常规辅助任务槽——`auxiliary.curator`——与 Vision、Compression、Session Search 等并列。"Auto" 表示"使用我的主聊天模型"；可覆盖该槽以为审查 pass 指定特定的 provider + model。
+
+**最简单——`hermes model`：**
+
+```bash
+hermes model                   # → "Auxiliary models — side-task routing"
+                               # → pick "Curator" → pick provider → pick model
+```
+
+同样的选择器也可在 Web 控制台的 **Models** 标签页中使用。
+
+**直接编辑 config.yaml（等效）：**
+
+```yaml
+auxiliary:
+  curator:
+    provider: openrouter
+    model: google/gemini-3-flash-preview
+    timeout: 600               # generous — reviews can take several minutes
+```
+
+保持 `provider: auto`（默认值）会将审查 pass 路由到主聊天模型，与所有其他辅助任务的行为一致。
+
+:::note 旧版配置
+早期版本使用独立的 `curator.auxiliary.{provider,model}` 块。该路径仍然有效，但会输出一条弃用日志——请迁移到上方的 `auxiliary.curator`，使 curator 与其他所有辅助任务共享相同的管道（`hermes model`、控制台 Models 标签页、`base_url`、`api_key`、`timeout`、`extra_body`）。
+:::
+
+## CLI
+
+```bash
+hermes curator status         # last run, counts, pinned list, LRU top 5
+hermes curator run            # trigger a review now (blocks until the LLM pass finishes)
+hermes curator run --background  # fire-and-forget: start the LLM pass in a background thread
+hermes curator run --dry-run  # preview only — report without any mutations
+hermes curator backup         # take a manual snapshot of ~/.hermes/skills/
+hermes curator rollback       # restore from the newest snapshot
+hermes curator rollback --list     # list available snapshots
+hermes curator rollback --id <ts>  # restore a specific snapshot
+hermes curator rollback -y         # skip the confirmation prompt
+hermes curator pause          # stop runs until resumed
+hermes curator resume
+hermes curator pin <skill>    # never auto-transition this skill
+hermes curator unpin <skill>
+hermes curator restore <skill>  # move an archived skill back to active
+```
+
+## 备份与回滚
+
+在每次真正的 curator pass 之前，Hermes 会在 `~/.hermes/skills/.curator_backups/<utc-iso>/skills.tar.gz` 处对 `~/.hermes/skills/` 进行 tar.gz 快照。如果某次 pass 归档或合并了你不希望被触碰的内容，可以用一条命令撤销整次运行：
+
+```bash
+hermes curator rollback        # restore newest snapshot (with confirmation)
+hermes curator rollback -y     # skip the prompt
+hermes curator rollback --list # see all snapshots with reason + size
+```
+
+回滚本身也是可逆的：在替换技能树之前，Hermes 会再次创建一个标记为 `pre-rollback to <target-id>` 的快照，因此误操作的回滚可以通过 `--id` 滚动到该快照来撤销。
+
+你也可以随时通过 `hermes curator backup --reason "before-refactor"` 手动创建快照。`--reason` 字符串会写入快照的 `manifest.json`，并在 `--list` 中显示。
+
+快照会被裁剪至 `curator.backup.keep`（默认 5 个）以控制磁盘占用：
+
+```yaml
+curator:
+  backup:
+    enabled: true
+    keep: 5
+```
+
+设置 `curator.backup.enabled: false` 可禁用自动快照。手动 `hermes curator backup` 命令仅在 `enabled: true` 时才能工作——该标志对两条路径对称生效，因此不会在变更性运行中意外跳过 pre-run 快照。
+
+`hermes curator status` 还会列出五个最近最少使用的技能——快速查看哪些技能可能即将变为 stale。
+
+相同的子命令也可作为 `/curator` 斜杠命令在运行中的会话（CLI 或 gateway 平台）内使用。
+
+## "agent 创建"的含义
+
+若技能名称**不在**以下列表中，则视为 agent 创建：
+
+- `~/.hermes/skills/.bundled_manifest`（安装时从仓库复制的技能），以及
+- `~/.hermes/skills/.hub/lock.json`（通过 `hermes skills install` 安装的技能）。
+
+`~/.hermes/skills/` 中的其他所有内容均在 curator 的处理范围内，包括：
+
+- agent 在对话中通过 `skill_manage(action="create")` 保存的技能。
+- 你手动编写 `SKILL.md` 创建的技能。
+- 通过你指向 Hermes 的外部技能目录添加的技能。
+
+:::warning 你手写的技能与 agent 保存的技能看起来完全相同
+此处的来源判断是**二元的**（捆绑/hub 与其他所有内容）。Curator 无法区分你依赖于私有工作流的手写技能与自我改进循环在会话中途保存的技能。两者都落入"agent 创建"的桶中。
+
+在第一次真正运行之前（默认为安装后 7 天），请花时间：
+
+1. 运行 `hermes curator run --dry-run` 查看 curator 具体会提出什么建议。
+2. 使用 `hermes curator pin <name>` 保护任何你不希望被触碰的内容。
+3. 或者在 `config.yaml` 中设置 `curator.enabled: false`，如果你更愿意自己管理技能库。
+
+归档始终可通过 `hermes curator restore <name>` 恢复，但事先 pin 比事后追查合并结果要容易得多。
+:::
+
+如果你想保护某个特定技能不被触碰——例如你依赖的手写技能——请使用 `hermes curator pin <name>`。详见下一节。
+
+## 固定技能 {#pinning-a-skill}
+
+固定（pinning）可保护技能不被删除——包括 curator 的自动归档 pass 和 agent 的 `skill_manage(action="delete")` 工具调用。技能一旦被固定：
+
+- **Curator** 在自动状态转换（`active → stale → archived`）时跳过它，其 LLM 审查 pass 也被指示不予处理。
+- **Agent 的 `skill_manage` 工具**拒绝对其执行 `delete`，并提示用户使用 `hermes curator unpin <name>`。修补和编辑仍然可以进行，因此 agent 可以在遇到问题时改进已固定技能的内容，无需反复 pin/unpin/re-pin。
+
+使用以下命令固定和取消固定：
+
+```bash
+hermes curator pin <skill>
+hermes curator unpin <skill>
+```
+
+该标志以 `"pinned": true` 的形式存储在 `~/.hermes/skills/.usage.json` 中技能对应的条目上，因此跨会话持久有效。
+
+只有 **agent 创建**的技能才能被固定——捆绑和 hub 安装的技能本就不受 curator 变更，若你尝试固定它们，`hermes curator pin` 会拒绝并给出说明。
+
+如果你想要比"禁止删除"更强的保证——例如在 agent 仍可读取技能的同时完全冻结其内容——请直接用编辑器编辑 `~/.hermes/skills/<name>/SKILL.md`。pin 保护的是工具驱动的删除，而非你自己的文件系统访问。
+
+## 使用遥测
+
+Curator 在 `~/.hermes/skills/.usage.json` 维护一个附属文件，每个技能对应一条记录：
+
+```json
+{
+  "my-skill": {
+    "use_count": 12,
+    "view_count": 34,
+    "last_used_at": "2026-04-24T18:12:03Z",
+    "last_viewed_at": "2026-04-23T09:44:17Z",
+    "patch_count": 3,
+    "last_patched_at": "2026-04-20T22:01:55Z",
+    "created_at": "2026-03-01T14:20:00Z",
+    "state": "active",
+    "pinned": false,
+    "archived_at": null
+  }
+}
+```
+
+计数器在以下情况递增：
+
+- `view_count`：agent 对该技能调用 `skill_view`。
+- `use_count`：技能被加载到对话的 prompt 中。
+- `patch_count`：对该技能执行 `skill_manage patch/edit/write_file/remove_file`。
+
+捆绑和 hub 安装的技能被明确排除在遥测写入之外。
+
+## 每次运行的报告
+
+每次 curator 运行都会在 `~/.hermes/logs/curator/` 下写入一个带时间戳的目录：
+
+```
+~/.hermes/logs/curator/
+└── 20260429-111512/
+    ├── run.json      # machine-readable: full fidelity, stats, LLM output
+    └── REPORT.md     # human-readable summary
+```
+
+`REPORT.md` 是快速查看某次运行所做操作的方式——哪些技能发生了状态转换、LLM 审查者说了什么、修补了哪些技能。无需 grep `agent.log` 即可完成审计。
+
+### 摘要中的重命名映射
+
+如果某次运行将多个技能合并到一个总括技能下（或合并了近似重复项），运行结束时打印的用户可见摘要会包含一个明确的重命名映射，显示 curator 应用的每个 `旧名称 → 新名称` 对。这是对逐技能状态转换行的补充，因此当一批重命名落地时，你可以一眼发现，无需对比 JSON 报告。该提示也会在 `hermes curator pin` 下显示，以便你在需要时立即固定新标签。
+
+## 恢复已归档的技能
+
+如果 curator 归档了你仍需要的技能：
+
+```bash
+hermes curator restore <skill-name>
+```
+
+这会将技能从 `~/.hermes/skills/.archive/` 移回活跃树，并将其状态重置为 `active`。如果此后有同名的捆绑或 hub 安装技能（会遮蔽上游），则恢复操作会被拒绝。
+
+## 按环境禁用
+
+Curator 默认开启。若要关闭：
+
+- **仅针对某个 profile：** 编辑 `~/.hermes/config.yaml`（或当前活跃 profile 的配置），设置 `curator.enabled: false`。
+- **仅针对单次运行：** `hermes curator pause`——暂停跨会话持久有效；使用 `resume` 重新启用。
+
+Curator 在 `min_idle_hours` 未经过时也会拒绝运行，因此在活跃的开发机器上，它自然只会在安静时段运行。
+
+## 另请参阅
+
+- [技能系统](/user-guide/features/skills)——技能的总体工作原理及创建技能的自我改进循环
+- [内存](/user-guide/features/memory)——维护长期记忆的并行后台审查
+- [捆绑技能目录](/reference/skills-catalog)
+- [Issue #7816](https://github.com/NousResearch/hermes-agent/issues/7816)——原始提案与设计讨论

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

@@ -0,0 +1,355 @@
+---
+sidebar_position: 7
+title: "子智能体委派"
+description: "使用 delegate_task 为并行工作流生成隔离的子智能体"
+---
+
+# 子智能体委派
+
+`delegate_task` 工具会生成具有隔离上下文、继承工具访问权限和独立终端会话的子 AIAgent 实例。每个子智能体获得全新的对话并独立运行——只有其最终摘要会进入父智能体的上下文。
+
+顶层模型调用会自动在后台运行。Hermes 会立即返回句柄，使对话可以继续，并在任务完成后将结果作为新消息发送回来。编排者子智能体会等待自己的工作线程完成，以便在返回前综合结果。
+
+## 后台进程的生命周期
+
+后台终端进程属于启动它的智能体。委派结束并关闭子智能体时，系统会终止它仍在运行的进程，包括先前轮次启动的任务，但不会停止父智能体或其他子智能体拥有的进程。共享终端环境并不意味着共享进程所有权。
+
+子智能体应等待构建、测试等有明确结束条件的后台命令完成，再返回最终摘要。如果 CI 监视器或服务器需要在子智能体结束后继续运行，应由父会话启动；返回进程 ID 不会将所有权转移给父智能体。
+
+## 单任务
+
+```python
+delegate_task(
+    goal="Debug why tests fail",
+    context="Error: assertion in test_foo.py line 42"
+)
+```
+
+## 并行批处理
+
+默认最多 3 个并发子智能体（可配置，无硬性上限）：
+
+```python
+delegate_task(tasks=[
+    {"goal": "Research topic A", "context": "Focus on recent primary sources"},
+    {"goal": "Research topic B", "context": "Compare the leading explanations"},
+    {"goal": "Fix the build", "context": "Project root: /home/user/project"}
+])
+```
+
+## 子智能体上下文的工作方式
+
+:::warning 关键：子智能体一无所知
+子智能体以**全新对话**启动。它们对父智能体的对话历史、之前的工具调用或委派前讨论的任何内容一无所知。子智能体的唯一上下文来自父智能体调用 `delegate_task` 时填写的 `goal` 和 `context` 字段。
+:::
+
+唯一例外：当父智能体有已解析的工作区目录时，每个子智能体的系统提示都会嵌入该工作区的**项目上下文文件**（`.hermes.md` > AGENTS.md 链 > CLAUDE.md > `.cursorrules`——与主智能体系统提示相同的发现逻辑、优先级和大小上限；SOUL.md 除外）。在仓库中工作的子智能体无需重新发现即可遵循仓库自身的约定。
+
+这意味着父智能体必须在调用中传递子智能体所需的**一切**信息：
+
+```python
+# BAD - subagent has no idea what "the error" is
+delegate_task(goal="Fix the error")
+
+# GOOD - subagent has all context it needs
+delegate_task(
+    goal="Fix the TypeError in api/handlers.py",
+    context="""The file api/handlers.py has a TypeError on line 47:
+    'NoneType' object has no attribute 'get'.
+    The function process_request() receives a dict from parse_body(),
+    but parse_body() returns None when Content-Type is missing.
+    The project is at /home/user/myproject and uses Python 3.11."""
+)
+```
+
+子智能体会收到一个基于你的 goal 和 context 构建的专注系统 prompt（提示词），指示其完成任务并提供结构化摘要，包括所做的事情、发现的内容、修改的文件以及遇到的问题。
+
+## 实际示例
+
+### 并行研究
+
+同时研究多个主题并收集摘要：
+
+```python
+delegate_task(tasks=[
+    {
+        "goal": "Research the current state of WebAssembly in 2025",
+        "context": "Focus on: browser support, non-browser runtimes, language support"
+    },
+    {
+        "goal": "Research the current state of RISC-V adoption in 2025",
+        "context": "Focus on: server chips, embedded systems, software ecosystem"
+    },
+    {
+        "goal": "Research quantum computing progress in 2025",
+        "context": "Focus on: error correction breakthroughs, practical applications, key players"
+    }
+])
+```
+
+### 代码审查 + 修复
+
+将审查并修复的工作流委派给全新上下文：
+
+```python
+delegate_task(
+    goal="Review the authentication module for security issues and fix any found",
+    context="""Project at /home/user/webapp.
+    Auth module files: src/auth/login.py, src/auth/jwt.py, src/auth/middleware.py.
+    The project uses Flask, PyJWT, and bcrypt.
+    Focus on: SQL injection, JWT validation, password handling, session management.
+    Fix any issues found and run the test suite (pytest tests/auth/)."""
+)
+```
+
+### 多文件重构
+
+将会大量占用父智能体上下文的大型重构任务委派出去：
+
+```python
+delegate_task(
+    goal="Refactor all Python files in src/ to replace print() with proper logging",
+    context="""Project at /home/user/myproject.
+    Use the 'logging' module with logger = logging.getLogger(__name__).
+    Replace print() calls with appropriate log levels:
+    - print(f"Error: ...") -> logger.error(...)
+    - print(f"Warning: ...") -> logger.warning(...)
+    - print(f"Debug: ...") -> logger.debug(...)
+    - Other prints -> logger.info(...)
+    Don't change print() in test files or CLI output.
+    Run pytest after to verify nothing broke."""
+)
+```
+
+## 批处理模式详情
+
+当顶层智能体提供 `tasks` 数组时，Hermes 会返回一个后台句柄，并行运行所有子智能体，并在每个子智能体完成后发送一条汇总结果。编排者子智能体则会在当前轮次中等待批处理完成，以便综合结果。
+
+- **最大并发数：** 默认 3 个任务（可通过 `delegation.max_concurrent_children` 或环境变量 `DELEGATION_MAX_CONCURRENT_CHILDREN` 配置；最低为 1，无硬性上限）。超出限制的批次会返回工具错误，而不是被静默截断。
+- **线程池：** 使用 `ThreadPoolExecutor`，以配置的并发限制作为最大工作线程数
+- **进度显示：** 在 CLI 模式下，树形视图会实时显示每个子智能体的工具调用，并附带每个任务的完成行。在 gateway 模式下，进度会被批量汇总并转发给父智能体的进度回调
+- **结果排序：** 结果按任务索引排序，与输入顺序一致，不受完成顺序影响
+- **取消：** 后续消息不会取消顶层后台批处理。`/stop` 或关闭/重置所属会话会取消其活跃子智能体。同步编排者的子智能体仍会跟随其父智能体的中断状态
+
+编排者发起的同步单任务委派会直接运行，不会产生线程池开销。
+
+### 持久化后台完成事件
+
+后台委派完成后，Hermes 会先把完成事件写入当前 profile 的 `state.db`，再发布到正常的新轮次队列。如果 Hermes 在完成后、交付前重启，待处理事件会被恢复，并继续经过相同的所有权检查。多个消费者通过持久化 claim 竞争；只有成功接收合成轮次的消费者会确认交付，失败尝试会释放 claim 以便重试。
+
+这不会在崩溃后恢复子智能体执行。如果委派仍在运行时其所有者进程消失，Hermes 会将其记录为 `unknown`，因为无法证明外部副作用是否已经发生。待处理和已交付记录都有界，并按 profile 隔离。
+
+## 模型覆盖
+
+你可以通过 `config.yaml` 为子智能体配置不同的模型——适用于将简单任务委派给更便宜/更快的模型：
+
+```yaml
+# In ~/.hermes/config.yaml
+delegation:
+  model: "google/gemini-flash-2.0"    # Cheaper model for subagents
+  provider: "openrouter"              # Optional: route subagents to a different provider
+```
+
+如果省略，子智能体将使用与父智能体相同的模型。
+
+### 成本策略：前沿模型规划，低价模型执行
+
+将问题分解为规格清晰的子任务需要前沿模型级别的判断力；而执行一个已经带有明确目标、完整上下文和输出约定的子任务通常不需要。与此同时，token 消耗主要发生在子智能体身上——并行批量子智能体通常消耗一次运行中绝大多数的 token，因此成本真正落在 worker 模型上。将 `delegation.model` 固定为低价模型、同时主会话保持前沿模型，可以把规划质量留在最需要的地方，并在消耗量最大的地方削减开支：
+
+```yaml
+# ~/.hermes/config.yaml
+model:
+  default: "your-frontier-model"     # 父智能体（规划者）保持前沿模型
+delegation:
+  model: "your-inexpensive-model"    # 所有 delegate_task 子智能体运行此模型
+  provider: "openrouter"             # 可选：将子智能体路由到不同的提供商
+```
+
+解析顺序：`delegation.base_url`（直连端点）优先，其次是 `delegation.provider`（通过运行时提供商系统解析完整凭证包）；两者都未设置时，子智能体继承父智能体的提供商和凭证。`delegation.model` 在所有情况下生效，为空时子智能体继承父智能体的模型。
+
+注意此固定是全局的：`delegate_task` 没有按任务指定模型的参数，批处理中的每个子智能体都运行配置的委派模型。对于需要更强模型的质量敏感型子任务，可以在该会话中不设置 `delegation.model`，或者将任务交给[看板](kanban.md)——看板支持按任务覆盖模型。
+
+## `/review` 命令
+
+`/review` 会派生一个独立的、拥有完整工具权限的后台评审子智能体，专门评审对话刚刚产出的工作——PR、diff、代码、文档、设计。它在所有界面均可用：CLI、TUI、桌面应用以及所有网关消息平台。
+
+```
+/review                       # 评审最近 10 条消息中呈现的工作
+/review 重点关注安全性          # 为评审者附加额外指示
+```
+
+工作流程：
+
+1. 最近 10 条用户/助手消息被快照为评审者的起始证据（工具输出和系统消息被排除）。
+2. 评审子智能体在与 `delegate_task` 相同的后台委派通道上派发——它拥有完整的常规子智能体工具集（终端、网络、文件、浏览器等），因此会实际打开 PR、阅读 diff、运行代码，而不是仅凭摘录下判断。
+3. 评审者继承主智能体的工作上下文：主智能体已加载的技能（启动预加载或会话中通过 `skill_view` 加载）会列在其简报中，并指示其加载这些技能、以其约定为标准评判工作。与所有子智能体一样，其系统提示也会嵌入工作区的项目上下文文件（AGENTS.md / CLAUDE.md / .cursorrules）作为具有约束力的约定。
+4. 完成后，完整评审作为常规后台子智能体完成事件重新进入同一会话——你的主智能体可以看到并据此行动（修复问题、推送后续提交、回复你）。
+
+典型流程：主智能体开了一个 PR，你输入 `/review`，第二双眼睛在你继续工作的同时对其进行调查；评审结果回到聊天中，交给创建该 PR 的智能体。
+
+### 评审模型
+
+默认情况下评审者运行在你的主模型上。要固定专用评审模型，请在 `config.yaml` 中设置 `auxiliary.review`：
+
+```yaml
+auxiliary:
+  review:
+    provider: openrouter               # 或 nous、anthropic、直连 base_url 等
+    model: anthropic/claude-opus-4.6   # 一个强力的评审模型
+```
+
+凭证解析方式与 `delegation.provider` 固定完全相同（完整运行时提供商凭证包：base_url、API 密钥、api_mode）。`provider: auto` 加空 `model` 表示"继承主智能体的模型"——这是默认值。
+
+`/review` 与 `/refine` 刻意分开：`/refine` 评审对话本身以更新记忆和技能，`/review` 评审对话产出的*工作成果*。
+
+## 继承的工具访问权限
+
+`delegate_task` 不接受面向模型的 `toolsets` 参数。每个子智能体都会继承父智能体已启用的工具集，因此模型无法授予子智能体父智能体本身没有的能力。如果委派任务需要其他能力，请在开始对话前配置父智能体的工具。
+
+即使父智能体拥有某些工具，以下工具仍会对子智能体屏蔽：
+- `delegation` — 对叶子子智能体屏蔽（默认）。`role="orchestrator"` 的子智能体可保留，受 `max_spawn_depth` 约束——参见下方[深度限制与嵌套编排](#depth-limit-and-nested-orchestration)。
+- `clarify` — 子智能体无法与用户交互
+- `memory` — 不可写入共享持久内存
+- `code_execution` — 子智能体应逐步推理
+- `send_message` — 无跨平台副作用（例如发送 Telegram 消息）
+
+## 最大迭代次数
+
+每个子智能体都有迭代次数限制（默认：50），控制其可进行的工具调用轮次：
+
+```python
+delegate_task(
+    goal="Quick file check",
+    context="Check if /etc/nginx/nginx.conf exists and print its first 10 lines",
+    max_iterations=10  # Simple task, don't need many turns
+)
+```
+
+## 子智能体超时
+
+默认情况下，子智能体**没有挂钟超时限制**。子智能体只会因其实际执行的操作而失败——API 错误、工具错误或达到迭代预算上限——而不会被委派层面的计时器终止。早期版本曾设有硬性上限（300 秒，后为 600 秒），但这会在任务执行过程中误杀正常工作的子智能体：深度代码审查、大规模研究分发以及慢速推理模型经常需要超过 10 分钟，而它们全程都在稳定推进。
+
+真正卡死的子智能体仍会被检测到：当子智能体没有任何进展（无 API 调用、无工具启动）时，心跳陈旧度监控会停止刷新父智能体的活动状态，从而让网关的不活动超时机制对真正卡死的工作进程生效。
+
+如果仍需要硬性上限（例如对无人值守的 cron 驱动委派进行成本控制），可按安装实例选择启用：
+
+```yaml
+delegation:
+  child_timeout_seconds: 0     # 默认：0 = 无超时
+  # child_timeout_seconds: 1800  # 选择启用的硬性上限（下限 30 秒）
+```
+
+正值会对每个子智能体强制执行挂钟时间硬限制；`0` 或负值表示禁用。
+
+:::tip 零调用超时时的诊断转储
+在配置了硬性上限的情况下，如果子智能体在**零次** API 调用的情况下超时（通常原因：provider 不可达、认证失败或工具 schema 被拒绝），`delegate_task` 会将结构化诊断信息写入 `~/.hermes/logs/subagent-timeout-<session>-<timestamp>.log`，其中包含子智能体的配置快照、凭据解析追踪以及早期错误消息。比之前的静默超时行为更易于定位根因。
+:::
+
+## 监控运行中的子智能体（`/agents`）
+
+TUI 提供 `/agents` 浮层（别名 `/tasks`），将递归 `delegate_task` 扇出转化为一级审计界面：
+
+- 运行中和最近完成的子智能体的实时树形视图，按父智能体分组
+- 每个分支的费用、token 和已触及文件的汇总
+- 终止和暂停控制——可在不中断其兄弟智能体的情况下取消特定子智能体
+- 事后回顾：即使子智能体已返回父智能体，也可逐轮查看其历史记录
+
+经典 CLI、TUI 和 Desktop 会在输入框上方自动显示正在运行的子智能体，包括总数、任务名称、已运行时间和最近活动。终端根据屏幕高度限制可见行数，并显示隐藏数量；Desktop 最多预览三个工作者。
+
+- **经典 CLI：F6** 打开全屏实时列表；方向键选择，**Enter** 查看近期日志，**PgUp/PgDn** 滚动，**s** 输入引导，**x** 后按 **y** 确认停止。关闭后保留原有输入草稿。
+- **TUI：Ctrl+T** 或 `/agents` 打开完整树状列表；**Enter/t** 查看实时日志，**d** 查看详情（历史回放中 Enter 仍打开详情），**e** 输入引导，**x** 停止选中的工作者，**X** 停止其子树。
+- **Desktop：** 展开输入框上方的 **Subagents**，选择工作者查看详情并使用 **Steer** / **Stop**。
+
+引导的“已排队”确认不代表子智能体已经读取；它会在检查点接收。日志预览只包含有大小限制的近期内容。工作者结束后离开实时列表，完成消息和已有历史视图仍可用于回顾。
+
+在经典 CLI 和 TUI 中按 **F7**，可将实时栏折叠为单行摘要，再按一次恢复多行预览。单行保留运行数量和展开/恢复提示，空间允许时显示活动。输入和发送不受影响；关闭监视器后保留草稿及光标位置。此选项不写入配置。
+
+经典 CLI 的 `/agents` 和 `/tasks` 仍打印文本摘要；父智能体忙碌时可直接按 **F6** 打开交互式监视器。参见 [TUI — 斜杠命令](/user-guide/tui#slash-commands)。
+
+## 深度限制与嵌套编排 {#depth-limit-and-nested-orchestration}
+
+默认情况下，委派是**扁平的**：父智能体（深度 0）生成子智能体（深度 1），而这些子智能体无法进一步委派。这可防止失控的递归委派。
+
+对于多阶段工作流（研究 → 综合，或对子问题进行并行编排），父智能体可以生成**编排者**子智能体，这些子智能体*可以*委派自己的工作线程：
+
+```python
+delegate_task(
+    goal="Survey three code review approaches and recommend one",
+    role="orchestrator",  # Allows this child to spawn its own workers
+    context="...",
+)
+```
+
+- `role="leaf"`（默认）：子智能体无法进一步委派——与扁平委派行为相同。
+- `role="orchestrator"`：子智能体保留 `delegation` 工具集。受 `delegation.max_spawn_depth` 约束（默认 **1** = 扁平，因此在默认设置下 `role="orchestrator"` 无效）。将 `max_spawn_depth` 提高到 2 可允许编排者子智能体生成叶子孙智能体；设为 3 则允许三层（上限）。
+- `delegation.orchestrator_enabled: false`：全局开关，无论 `role` 参数如何，强制所有子智能体为 `leaf`。
+
+**费用警告：** 在 `max_spawn_depth: 3` 和 `max_concurrent_children: 3` 的情况下，树可达到 3×3×3 = 27 个并发叶子智能体。每增加一层都会成倍增加开销——请谨慎提高 `max_spawn_depth`。
+
+## 生命周期与持久性
+
+:::warning 后台完成事件持久化并不等于执行持久化
+在会话支持稍后交付结果时，顶层面向模型的 `delegate_task` 调用会自动在后台运行。Hermes 会立即返回句柄，并在子智能体或批处理完成后将结果重新发送到对话中。编排者子智能体会在当前轮次中等待自己的工作线程，因为它们必须在返回前综合这些结果。无法稍后交付分离结果的无状态请求/响应端点会回退到同步执行。
+
+- 普通后续消息不会取消后台子智能体。`/stop` 会取消运行中的后台委派，关闭或重置所属会话会丢弃其活跃子智能体。
+- 显式关闭或重置会话会中断该会话的后台子智能体。关闭由 TUI 查看、但由网关拥有的会话不会终止网关自己的后台工作。
+- Hermes 进程重启后不会恢复仍在运行的子智能体；该尝试会变为 `unknown`，因为 Hermes 无法证明哪些外部副作用已经发生。
+- 如果子智能体在重启前已经完成、但结果尚未交付，该完成事件会被恢复，并重新经过所属会话的正常路由检查。
+- 被取消的子智能体会返回结构化结果（`status="interrupted"`，`exit_reason="interrupted"`），但由于父智能体也被中断，该结果通常不会出现在用户可见的回复中。
+
+对于必须在会话关闭或进程重启后继续的**持久执行**，请使用：
+
+- `cronjob`（action=`create`）——调度独立的智能体运行；不受父智能体轮次中断影响。
+- `terminal(background=True, notify_on_complete=True)`——长时间运行的 shell 命令，在智能体执行其他操作时持续运行。
+:::
+
+## 关键特性
+
+- 每个子智能体获得其**独立的终端会话**（与父智能体分离）
+- 子智能体继承父智能体已启用的工具集；模型无法按调用选择或扩大这些工具集
+- **嵌套委派为可选项**——只有 `role="orchestrator"` 的子智能体可以进一步委派，且仅在 `max_spawn_depth` 从默认值 1（扁平）提高后才生效。可通过 `orchestrator_enabled: false` 全局禁用。
+- 叶子子智能体**不能**调用：`delegate_task`、`clarify`、`memory`、`send_message`、`execute_code`。编排者子智能体保留 `delegate_task`，但仍不能使用其他四个。
+- **取消遵循所有权**——`/stop` 或关闭/重置所属会话会取消其后台子智能体；编排者下的同步后代会跟随父智能体的中断状态
+- 只有最终摘要进入父智能体的上下文，保持 token 使用高效
+- 子智能体继承父智能体的 **API 密钥、provider 配置和凭据池**（支持在速率限制时轮换密钥）
+
+## delegate_task 与 execute_code 对比
+
+| 因素 | delegate_task | execute_code |
+|--------|--------------|-------------|
+| **推理** | 完整 LLM 推理循环 | 仅 Python 代码执行 |
+| **上下文** | 全新隔离对话 | 无对话，仅脚本 |
+| **工具访问** | 所有非屏蔽工具，具备推理能力 | 通过 RPC 访问 7 个工具，无推理 |
+| **并行性** | 默认 3 个并发子智能体（可配置） | 单脚本 |
+| **最适合** | 需要判断力的复杂任务 | 机械式多步骤流水线 |
+| **Token 费用** | 较高（完整 LLM 循环） | 较低（仅返回 stdout） |
+| **用户交互** | 无（子智能体无法澄清） | 无 |
+
+**经验法则：** 当子任务需要推理、判断或多步骤问题解决时，使用 `delegate_task`。当需要机械式数据处理或脚本化工作流时，使用 `execute_code`。
+
+## 配置
+
+```yaml
+# In ~/.hermes/config.yaml
+delegation:
+  max_iterations: 50                        # Max turns per child (default: 50)
+  # max_concurrent_children: 3              # Parallel children per batch (default: 3)
+  # max_spawn_depth: 1                      # Tree depth (1-3, default 1 = flat). Raise to 2 to allow orchestrator children to spawn leaves; 3 for three levels.
+  # orchestrator_enabled: true              # Disable to force all children to leaf role.
+  model: "google/gemini-3-flash-preview"             # Optional provider/model override
+  provider: "openrouter"                             # Optional built-in provider
+  api_mode: anthropic_messages                       # optional; auto-detected from base_url for anthropic_messages endpoints
+
+# Or use a direct custom endpoint instead of provider:
+delegation:
+  model: "qwen2.5-coder"
+  base_url: "http://localhost:1234/v1"
+  api_key: "local-key"
+  # api_mode: "anthropic_messages"  # Optional. Wire protocol override for base_url ("chat_completions", "codex_responses", or "anthropic_messages"). Empty = auto-detect from URL (e.g. /anthropic suffix). Set explicitly for endpoints the heuristic can't classify (Azure AI Foundry, MiniMax, Zhipu GLM, LiteLLM proxies, …).
+```
+
+当 `base_url` 指向 Anthropic 兼容端点时——例如路径以 `/anthropic` 结尾、Azure Foundry Claude 路由或 MiniMax `/anthropic` 代理——`api_mode` 会被自动检测为 `anthropic_messages`，子智能体无需任何配置即可使用正确的传输格式。当自动检测结果有误时（罕见），请显式设置 `api_mode`。
+
+:::tip
+智能体会根据任务复杂度自动处理委派。你无需明确要求它进行委派——它会在合适时自行决定。
+:::