better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/reference/toolsets-reference.md

@@ -0,0 +1,162 @@
+---
+sidebar_position: 4
+title: "工具集参考"
+description: "Hermes 核心、复合、平台及动态工具集参考"
+---
+
+# 工具集参考
+
+工具集（Toolset）是工具的命名集合，用于控制 agent 可以执行的操作。它是按平台、按会话或按任务配置工具可用性的主要机制。
+
+## 工具集的工作原理
+
+每个工具恰好属于一个工具集。启用某个工具集后，该集合中的所有工具都将对 agent 可用。工具集分为三种类型：
+
+- **核心（Core）** — 一组相关工具的逻辑分组（例如，`file` 包含 `read_file`、`write_file`、`patch`、`search_files`）
+- **复合（Composite）** — 将多个核心工具集组合用于常见场景（例如，`debugging` 包含 file、terminal 和 web 工具）
+- **平台（Platform）** — 针对特定部署环境的完整工具配置（例如，`hermes-cli` 是交互式 CLI 会话的默认配置）
+
+## 配置工具集
+
+### 按会话（CLI）
+
+```bash
+hermes chat --toolsets web,file,terminal
+hermes chat --toolsets debugging        # composite — expands to file + terminal + web
+hermes chat --toolsets all              # everything
+```
+
+### 按平台（config.yaml）
+
+```yaml
+toolsets:
+  - hermes-cli          # default for CLI
+  # - hermes-telegram   # override for Telegram gateway
+```
+
+### 交互式管理
+
+```bash
+hermes tools                            # curses UI to enable/disable per platform
+```
+
+或在会话中：
+
+```
+/tools list
+/tools disable browser
+/tools enable homeassistant
+```
+
+## 核心工具集
+
+| 工具集 | 工具 | 用途 |
+|--------|------|------|
+| `browser` | `browser_back`, `browser_cdp`, `browser_click`, `browser_console`, `browser_dialog`, `browser_get_images`, `browser_navigate`, `browser_press`, `browser_scroll`, `browser_snapshot`, `browser_type`, `browser_vision`, `web_search` | 核心浏览器自动化。包含 `web_search` 作为快速查询的备用方案。`browser_cdp` 和 `browser_dialog` 在运行时受限——仅在会话启动时 CDP 端点可达（通过 `/browser connect`、`browser.cdp_url` 配置、Browserbase 或 Camofox）时才注册。`browser_dialog` 与 `browser_snapshot` 在附加 CDP supervisor 时添加的 `pending_dialogs` 和 `frame_tree` 字段配合使用。 |
+| `clarify` | `clarify` | 当 agent 需要澄清时向用户提问。 |
+| `code_execution` | `execute_code` | 运行以编程方式调用 Hermes 工具的 Python 脚本。 |
+| `cronjob` | `cronjob` | 调度和管理周期性任务。 |
+| `debugging` | 复合（`file` + `terminal` + `web`） | 调试套件——文件、进程/终端、网页提取/搜索。 |
+| `delegation` | `delegate_task` | 生成隔离的子 agent 实例以并行执行工作。 |
+| `discord` | `discord` | 核心 Discord 文本/嵌入/私信操作（仅限 gateway）。在 `hermes-discord` 工具集上激活。 |
+| `discord_admin` | `discord_admin` | Discord 管理操作（封禁、角色变更、频道管理）。在 `hermes-discord` 工具集上激活；需要 bot 持有相关 Discord 权限。 |
+| `feishu_doc` | `feishu_doc_read` | 读取飞书/Lark 文档内容。由飞书文档评论智能回复处理器使用。 |
+| `feishu_drive` | `feishu_drive_add_comment`, `feishu_drive_list_comments`, `feishu_drive_list_comment_replies`, `feishu_drive_reply_comment` | 飞书/Lark 云盘评论操作。仅限评论 agent 使用；不在 `hermes-cli` 或其他消息工具集上暴露。 |
+| `file` | `patch`, `read_file`, `search_files`, `write_file` | 文件读取、写入、搜索和编辑。 |
+| `homeassistant` | `ha_call_service`, `ha_get_state`, `ha_list_entities`, `ha_list_services` | 通过 Home Assistant 进行智能家居控制。仅在设置 `HASS_TOKEN` 时可用。 |
+| `computer_use` | `computer_use` | 通过 cua-driver 进行后台 macOS 桌面控制——不抢占光标/焦点。适用于任何支持工具调用的模型。仅限 macOS；需要 `cua-driver` 在 `$PATH` 中。 |
+| `image_gen` | `image_generate` | 通过 FAL.ai 进行文本生成图像（支持可选的 OpenAI / xAI 后端）。 |
+| `video_gen` | `video_generate` | 通过插件注册的后端（xAI Grok-Imagine、FAL.ai Veo 3.1 / Pixverse v6 / Kling O3）进行文本生成视频和图像生成视频。传入 `image_url` 可对图像进行动画化；省略则为文本生成视频。 |
+| `kanban` | `kanban_block`, `kanban_comment`, `kanban_complete`, `kanban_create`, `kanban_heartbeat`, `kanban_link`, `kanban_list`, `kanban_show`, `kanban_unblock` | 多 agent 协调工具。为调度器生成的任务工作者（`HERMES_KANBAN_TASK`）以及显式启用 `kanban` 工具集的 profile 注册。工作者可标记任务完成、阻塞、心跳、评论以及创建/关联后续任务；编排器 profile 还额外获得看板路由工具，如 list/unblock。 |
+| `memory` | `memory` | 持久化跨会话记忆管理。 |
+| `messaging` | `send_message` | 在会话中向其他平台（Telegram、Discord 等）发送消息。 |
+| `safe` | `image_generate`, `vision_analyze`, `web_extract`, `web_search`（通过 `includes`） | 只读研究 + 媒体生成。无文件写入、无终端、无代码执行。 |
+| `search` | `web_search` | 仅网页搜索（不含提取）。 |
+| `session_search` | `session_search` | 搜索历史会话记录。 |
+| `skills` | `skill_manage`, `skill_view`, `skills_list` | 技能的增删改查与浏览。 |
+| `spotify` | `spotify_albums`, `spotify_devices`, `spotify_library`, `spotify_playback`, `spotify_playlists`, `spotify_queue`, `spotify_search` | 原生 Spotify 控制（播放、队列、搜索、播放列表、专辑、音乐库）。由内置 `spotify` 插件注册。 |
+| `terminal` | `process`, `terminal` | Shell 命令执行和后台进程管理。 |
+| `todo` | `todo` | 会话内任务列表管理。 |
+| `tts` | `text_to_speech` | 文本转语音音频生成。 |
+| `vision` | `vision_analyze` | 通过视觉能力模型进行图像分析。 |
+| `video` | `video_analyze` | 视频分析与理解工具（需手动启用，不在默认工具集中——通过 `--toolsets` 显式添加）。 |
+| `web` | `web_extract`, `web_search` | 网页搜索和页面内容提取。 |
+| `x_search` | `x_search` | 通过 xAI 内置的 `x_search` Responses 工具搜索 X（Twitter）帖子和话题。默认关闭；通过 `hermes tools` 启用。仅在配置了 xAI 凭据（SuperGrok OAuth 或 `XAI_API_KEY`）时注册 schema。 |
+| `yuanbao` | `yb_query_group_info`, `yb_query_group_members`, `yb_search_sticker`, `yb_send_dm`, `yb_send_sticker` | 元宝私信/群组操作和表情包搜索。仅在 `hermes-yuanbao` 上注册。 |
+
+## 平台工具集
+
+平台工具集定义了部署目标的完整工具配置。大多数消息平台使用与 `hermes-cli` 相同的配置：
+
+| 工具集 | 与 `hermes-cli` 的差异 |
+|--------|------------------------|
+| `hermes-cli` | 完整工具集——交互式 CLI 会话的默认配置。包含 file、terminal、web、browser、memory、skills、vision、image_gen、todo、tts、delegation、code_execution、cronjob、session_search、clarify 和 `safe`（只读）套件，以及标准消息工具。 |
+| `hermes-acp` | 移除了 `clarify`、`cronjob`、`image_generate`、`send_message`、`text_to_speech` 以及全部四个 Home Assistant 工具。专注于 IDE 环境中的编码任务。 |
+| `hermes-api-server` | 移除了 `clarify`、`send_message` 和 `text_to_speech`。保留其他所有工具——适用于无法进行用户交互的程序化访问场景。 |
+| `hermes-cron` | 与 `hermes-cli` 相同。 |
+| `hermes-telegram` | 与 `hermes-cli` 相同。 |
+| `hermes-discord` | 在 `hermes-cli` 基础上添加了 `discord` 和 `discord_admin`。 |
+| `hermes-slack` | 与 `hermes-cli` 相同。 |
+| `hermes-whatsapp` | 与 `hermes-cli` 相同。 |
+| `hermes-signal` | 与 `hermes-cli` 相同。 |
+| `hermes-matrix` | 与 `hermes-cli` 相同。 |
+| `hermes-mattermost` | 与 `hermes-cli` 相同。 |
+| `hermes-email` | 与 `hermes-cli` 相同。 |
+| `hermes-sms` | 与 `hermes-cli` 相同。 |
+| `hermes-bluebubbles` | 与 `hermes-cli` 相同。 |
+| `hermes-dingtalk` | 与 `hermes-cli` 相同。 |
+| `hermes-feishu` | 添加了五个 `feishu_doc_*` / `feishu_drive_*` 工具（仅由文档评论处理器使用，不用于常规聊天适配器）。 |
+| `hermes-qqbot` | 与 `hermes-cli` 相同。 |
+| `hermes-wecom` | 与 `hermes-cli` 相同。 |
+| `hermes-wecom-callback` | 与 `hermes-cli` 相同。 |
+| `hermes-weixin` | 与 `hermes-cli` 相同。 |
+| `hermes-yuanbao` | 在 `hermes-cli` 基础上添加了五个 `yb_*` 工具（私信/群组/表情包）。 |
+| `hermes-homeassistant` | 与 `hermes-cli` 相同（Home Assistant 工具默认已存在，在设置 `HASS_TOKEN` 时激活）。 |
+| `hermes-webhook` | 与 `hermes-cli` 相同。 |
+| `hermes-gateway` | 内部 gateway 编排器工具集——所有 `hermes-<platform>` 工具集的并集；当 gateway 需要接受任意消息来源时使用。 |
+
+## 动态工具集
+
+### MCP server 工具集
+
+每个已配置的 MCP server 在运行时会生成一个 `mcp-<server>` 工具集。例如，若配置了 `github` MCP server，则会创建包含该 server 所有暴露工具的 `mcp-github` 工具集。
+
+```yaml
+# config.yaml
+mcp_servers:
+  github:
+    command: npx
+    args: ["-y", "@modelcontextprotocol/server-github"]
+```
+
+这将创建一个 `mcp-github` 工具集，可在 `--toolsets` 或平台配置中引用。
+
+### 插件工具集
+
+插件可在初始化期间通过 `ctx.register_tool()` 注册自己的工具集。这些工具集与内置工具集并列显示，可以用相同方式启用/禁用。
+
+### 自定义工具集
+
+在 `config.yaml` 中定义自定义工具集，以创建项目专属的工具集合：
+
+```yaml
+toolsets:
+  - hermes-cli
+custom_toolsets:
+  data-science:
+    - file
+    - terminal
+    - code_execution
+    - web
+    - vision
+```
+
+### 通配符
+
+- `all` 或 `*` — 展开为所有已注册的工具集（内置 + 动态 + 插件）
+
+## 与 `hermes tools` 的关系
+
+`hermes tools` 命令提供基于 curses 的 UI，用于按平台切换单个工具的启用/禁用状态。该操作在工具级别进行（比工具集更细粒度），并持久化到 `config.yaml`。即使工具集已启用，被禁用的工具也会被过滤掉。
+
+另请参阅：[工具参考](./tools-reference.md)，获取所有单个工具及其参数的完整列表。

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

@@ -0,0 +1,251 @@
+---
+sidebar_position: 8
+sidebar_label: "Checkpoints & Rollback"
+title: "检查点与 /rollback"
+description: "使用影子 git 仓库和自动快照为破坏性操作提供文件系统安全保障"
+---
+
+# 检查点与 `/rollback`
+
+Hermes Agent 可以在**破坏性操作**之前自动为你的项目创建快照，并通过单条命令恢复。检查点在 v2 中为**按需启用**——大多数用户从不使用 `/rollback`，且影子存储（shadow-store）随时间增长不可忽视，因此默认关闭。
+
+在会话中通过 `--checkpoints` 启用检查点：
+
+```bash
+hermes chat --checkpoints
+```
+
+或在 `~/.hermes/config.yaml` 中全局启用：
+
+```yaml
+checkpoints:
+  enabled: true
+```
+
+此安全机制由内部**检查点管理器（Checkpoint Manager）**驱动，它在 `~/.hermes/checkpoints/store/` 下维护一个共享的影子 git 仓库——你真实项目的 `.git` 永远不会被触碰。Agent 操作的所有项目共享同一个存储，因此 git 的内容寻址对象数据库可以跨项目、跨轮次去重。
+
+## 触发检查点的条件
+
+检查点在以下操作之前自动创建：
+
+- **文件工具** — `write_file` 和 `patch`
+- **破坏性终端命令** — `rm`、`rmdir`、`cp`、`install`、`mv`、`sed -i`、`truncate`、`dd`、`shred`、输出重定向（`>`），以及 `git reset`/`clean`/`checkout`
+
+Agent 每个目录每轮**最多创建一个检查点**，因此长时间运行的会话不会产生大量快照。
+
+## 快速参考
+
+会话内斜杠命令：
+
+| 命令 | 说明 |
+|---------|-------------|
+| `/rollback` | 列出所有检查点及变更统计 |
+| `/rollback <N>` | 恢复到检查点 N（同时撤销最后一轮对话） |
+| `/rollback diff <N>` | 预览检查点 N 与当前状态的差异 |
+| `/rollback <N> <file>` | 从检查点 N 恢复单个文件 |
+
+在会话外检查和管理存储的 CLI 命令：
+
+| 命令 | 说明 |
+|---------|-------------|
+| `hermes checkpoints` | 显示总大小、项目数量及各项目明细 |
+| `hermes checkpoints status` | 与裸 `checkpoints` 相同 |
+| `hermes checkpoints list` | `status` 的别名 |
+| `hermes checkpoints prune` | 强制执行清理：删除孤立/过期条目、GC、强制大小上限 |
+| `hermes checkpoints clear` | 清除整个检查点库（会先询问确认） |
+| `hermes checkpoints clear-legacy` | 仅删除 v1 迁移留下的 `legacy-*` 归档 |
+
+## 检查点的工作原理
+
+概要流程：
+
+- Hermes 检测到工具即将**修改**工作树中的文件。
+- 每轮对话（每个目录）执行一次：
+  - 为该文件解析合理的项目根目录。
+  - 初始化或复用位于 `~/.hermes/checkpoints/store/` 的**单一共享影子存储**。
+  - 写入每个项目的索引，构建树对象，并提交到每个项目的引用（`refs/hermes/<project-hash>`）。
+- 这些每项目引用构成可通过 `/rollback` 检查和恢复的检查点历史。
+
+```mermaid
+flowchart LR
+  user["User command\n(hermes, gateway)"]
+  agent["AIAgent\n(run_agent.py)"]
+  tools["File & terminal tools"]
+  cpMgr["CheckpointManager"]
+  store["Shared shadow store\n~/.hermes/checkpoints/store/"]
+
+  user --> agent
+  agent -->|"tool call"| tools
+  tools -->|"before mutate\nensure_checkpoint()"| cpMgr
+  cpMgr -->|"git add/commit-tree/update-ref"| store
+  cpMgr -->|"OK / skipped"| tools
+  tools -->|"apply changes"| agent
+```
+
+## 配置
+
+在 `~/.hermes/config.yaml` 中配置：
+
+```yaml
+checkpoints:
+  enabled: false              # 主开关（默认：false — 按需启用）
+  max_snapshots: 20           # 每个项目的最大检查点数（通过引用重写 + gc 强制执行）
+  max_total_size_mb: 500      # 存储总大小硬上限；超出时丢弃最旧的提交
+  max_file_size_mb: 10        # 跳过大于此值的单个文件
+
+  # 自动维护（默认开启）：启动时扫描 ~/.hermes/checkpoints/，
+  # 删除 last_touch 超过 retention_days 的条目。通过 .last_prune
+  # 标记控制，最多每 min_interval_hours 运行一次。此扫描不会删除
+  # “孤立”条目（工作目录未找到）——启动时工作目录缺失含义模糊
+  # （项目被删除，还是外部卷/网络共享/VPN 尚未挂载），因此孤立项
+  # 清理只能通过下方的 `hermes checkpoints prune` 命令显式触发，
+  # 并会要求确认。
+  auto_prune: true
+  retention_days: 7
+  min_interval_hours: 24
+```
+
+完全禁用：
+
+```yaml
+checkpoints:
+  enabled: false
+  auto_prune: false
+```
+
+当 `enabled: false` 时，检查点管理器为空操作，不会尝试任何 git 操作。当 `auto_prune: false` 时，存储持续增长，直到你手动运行 `hermes checkpoints prune`。
+
+## 列出检查点
+
+在 CLI 会话中：
+
+```
+/rollback
+```
+
+Hermes 返回带有变更统计的格式化列表：
+
+```text
+📸 Checkpoints for /path/to/project:
+
+  1. 4270a8c  2026-03-16 04:36  before patch  (1 file, +1/-0)
+  2. eaf4c1f  2026-03-16 04:35  before write_file
+  3. b3f9d2e  2026-03-16 04:34  before terminal: sed -i s/old/new/ config.py  (1 file, +1/-1)
+
+  /rollback <N>             restore to checkpoint N
+  /rollback diff <N>        preview changes since checkpoint N
+  /rollback <N> <file>      restore a single file from checkpoint N
+```
+
+## 从 Shell 检查存储
+
+```bash
+hermes checkpoints
+```
+
+示例输出：
+
+```text
+Checkpoint base: /home/you/.hermes/checkpoints
+Total size:      142.3 MB
+  store/         138.1 MB
+  legacy-*       4.2 MB
+Projects:        12
+
+  WORKDIR                                                       COMMITS    LAST TOUCH  STATE
+  /home/you/code/hermes-agent                                        20       2h ago  live
+  /home/you/code/experiments/rl-runner                                8       1d ago  live
+  /home/you/code/old-prototype                                        3       9d ago  orphan
+  ...
+
+Legacy archives (1):
+  legacy-20260506-050616                           4.2 MB
+
+Clear with: hermes checkpoints clear-legacy
+```
+
+强制执行完整清理（忽略 24h 幂等性标记）：
+
+```bash
+hermes checkpoints prune --retention-days 3 --max-size-mb 200
+```
+
+## 使用 `/rollback diff` 预览变更
+
+在执行恢复之前，预览自某个检查点以来的变更：
+
+```
+/rollback diff 1
+```
+
+此命令显示 git diff 统计摘要，随后是完整差异内容。
+
+## 使用 `/rollback` 恢复
+
+```
+/rollback 1
+```
+
+Hermes 在后台执行：
+
+1. 验证目标提交存在于影子存储中。
+2. 对当前状态创建**回滚前快照**，以便之后可以"撤销撤销"。
+3. 恢复工作目录中被跟踪的文件。
+4. **撤销最后一轮对话**，使 Agent 的上下文与恢复后的文件系统状态一致。
+
+## 单文件恢复
+
+从检查点恢复单个文件，不影响目录中的其他内容：
+
+```
+/rollback 1 src/broken_file.py
+```
+
+## 安全与性能保障
+
+- **Git 可用性** — 若 `PATH` 中找不到 `git`，检查点功能将透明地禁用。
+- **目录范围** — Hermes 跳过过于宽泛的目录（根目录 `/`、家目录 `$HOME`）。
+- **仓库大小** — 超过 50,000 个文件的目录将被跳过。
+- **单文件大小上限** — 大于 `max_file_size_mb`（默认 10 MB）的文件不纳入快照，防止意外将数据集、模型权重或生成的媒体文件纳入存储。
+- **存储总大小上限** — 当存储超过 `max_total_size_mb`（默认 500 MB）时，按轮询方式丢弃每个项目最旧的提交，直到低于上限。
+- **真实剪枝** — `max_snapshots` 通过重写每项目引用并随后运行 `git gc --prune=now` 来强制执行，避免松散对象积累。
+- **无变更快照** — 若自上次快照以来没有变更，则跳过本次检查点。
+- **非致命错误** — 检查点管理器内部的所有错误均以 debug 级别记录；工具继续正常运行。
+
+## 检查点的存储位置
+
+```text
+~/.hermes/checkpoints/
+  ├── store/                 # 单一共享裸 git 仓库
+  │   ├── HEAD, objects/     # git 内部结构（跨项目共享）
+  │   ├── refs/hermes/<hash> # 每项目分支尖端
+  │   ├── indexes/<hash>     # 每项目 git 索引
+  │   ├── projects/<hash>.json  # workdir + created_at + last_touch
+  │   └── info/exclude
+  ├── .last_prune            # 自动剪枝幂等性标记
+  └── legacy-<ts>/           # 归档的 v2 之前每项目影子仓库
+```
+
+每个 `<hash>` 由工作目录的绝对路径派生。通常无需手动操作这些文件——使用 `hermes checkpoints status` / `prune` / `clear` 即可。
+
+### 从 v1 迁移
+
+在 v2 重写之前，每个工作目录在 `~/.hermes/checkpoints/<hash>/` 下拥有独立的完整影子 git 仓库。该布局无法跨项目去重对象，且剪枝器有已知的空操作问题——存储会无限增长。
+
+首次运行 v2 时，所有 v2 之前的影子仓库将被移入 `~/.hermes/checkpoints/legacy-<timestamp>/`，使新的单存储布局从干净状态开始。旧的 `/rollback` 历史仍可通过 `git` 手动检查 legacy 归档访问；确认不再需要后，运行：
+
+```bash
+hermes checkpoints clear-legacy
+```
+
+以回收空间。Legacy 归档也会在 `retention_days` 到期后由 `auto_prune` 清理。
+
+## 最佳实践
+
+- **仅在需要时启用检查点** — 使用 `hermes chat --checkpoints` 或在配置文件中设置 `enabled: true`。
+- **恢复前使用 `/rollback diff` 预览** — 查看将发生的变更，选择正确的检查点。
+- **使用 `/rollback` 而非 `git reset`** 来撤销 Agent 驱动的变更。
+- **定期检查 `hermes checkpoints status`**（如果你经常使用检查点）——显示哪些项目处于活跃状态以及存储占用情况。
+- **结合 Git worktree 使用以获得最高安全性** — 将每个 Hermes 会话保持在独立的 worktree/分支中，以检查点作为额外保障层。
+
+关于在同一仓库中并行运行多个 Agent，请参阅 [Git worktrees](./git-worktrees.md) 指南。