better-dsh 0.2.5 → 0.3.0-a

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

@@ -1,162 +0,0 @@
----
-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

@@ -1,251 +0,0 @@
----
-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) 指南。