better-dsh 0.2.5 → 0.3.0

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

@@ -1,272 +0,0 @@
----
-sidebar_position: 2
----
-
-# Profiles：运行多个 Agent
-
-在同一台机器上运行多个独立的 Hermes agent——每个 agent 拥有各自的配置、API 密钥、记忆、会话、技能和 gateway 状态。
-
-## 什么是 profile？
-
-profile 是一个独立的 Hermes 主目录。每个 profile 拥有自己的目录，其中包含各自的 `config.yaml`、`.env`、`SOUL.md`、记忆、会话、技能、cron 任务和状态数据库。profile 让你可以为不同用途运行独立的 agent——编程助手、个人机器人、研究 agent——而不会混淆 Hermes 状态。
-
-创建 profile 后，它会自动成为独立的命令。创建名为 `coder` 的 profile，你立即就拥有了 `coder chat`、`coder setup`、`coder gateway start` 等命令。
-
-## 快速开始
-
-```bash
-hermes profile create coder       # 创建 profile + "coder" 命令别名
-coder setup                       # 配置 API 密钥和模型
-coder chat                        # 开始对话
-```
-
-就这些。`coder` 现在是拥有独立配置、记忆和状态的 Hermes profile。
-
-## 创建 profile
-
-### 空白 profile
-
-```bash
-hermes profile create mybot
-```
-
-创建一个预置了内置技能的全新 profile。运行 `mybot setup` 配置 API 密钥、模型和 gateway token。
-
-如果你计划将此 profile 用作 kanban（看板）工作节点（或希望 kanban 编排器将任务路由到它），在创建时传入 `--description "<角色>"` 以便编排器了解其能力：
-
-```bash
-hermes profile create researcher --description "Reads source code and external docs, writes findings."
-```
-
-你也可以稍后通过 `hermes profile describe` 设置或自动生成描述——完整路由模型请参阅 [Kanban 指南](./features/kanban#auto-vs-manual-orchestration)。
-
-### 仅克隆配置（`--clone`）
-
-```bash
-hermes profile create work --clone
-```
-
-将当前 profile 的 `config.yaml`、`.env`、`SOUL.md`、skills 以及精选记忆文件 `memories/MEMORY.md` 和 `memories/USER.md` 复制到新 profile——记忆与 `SOUL.md` 一样被视为 agent 身份的一部分。会话、`state.db`、cron 任务及其他内容均从空白开始。若也想要空白记忆，请不加 `--clone` 创建 profile，或在创建后删除这两个文件；文件不存在时 agent 不会回退读取其他 profile 的记忆。编辑 `~/.hermes/profiles/work/.env` 可使用不同的 API 密钥，编辑 `~/.hermes/profiles/work/SOUL.md` 可设置不同的人格。
-
-### 克隆全部内容（`--clone-all`）
-
-```bash
-hermes profile create backup --clone-all
-```
-
-复制**所有内容**——配置、API 密钥、人格、记忆、技能、cron 任务、插件。会排除每个 profile 自己的历史数据（会话历史、`state.db`、`backups/`、`state-snapshots/`、`checkpoints/`），这些数据属于源 profile 且可能达到数十 GB。若要包含历史的完整备份，请使用 `hermes profile export` 或 `hermes backup`。
-
-### 从指定 profile 克隆
-
-```bash
-hermes profile create work --clone-from coder
-```
-
-`--clone-from <source>` 会直接选择源 profile，并隐含执行 config/skills/SOUL 克隆。若要完整复制该源 profile，请与 `--clone-all` 组合使用：
-
-```bash
-hermes profile create work-backup --clone-from coder --clone-all
-```
-
-:::tip Honcho 记忆 + profiles
-启用 Honcho 后，克隆操作会自动为新 profile 创建专属 AI 对等体，同时共享同一用户工作区。每个 profile 构建各自的观察记录和身份标识。详见 [Honcho——多 agent / Profiles](./features/memory-providers.md#honcho)。
-:::
-
-## 使用 profile
-
-### 命令别名
-
-每个 profile 在 `~/.local/bin/<name>` 自动获得一个命令别名：
-
-```bash
-coder chat                    # 与 coder agent 对话
-coder setup                   # 配置 coder 的设置
-coder gateway start           # 启动 coder 的 gateway
-coder doctor                  # 检查 coder 的健康状态
-coder skills list             # 列出 coder 的技能
-coder config set model.default anthropic/claude-sonnet-4
-```
-
-别名支持所有 hermes 子命令——底层实际上是 `hermes -p <name>`。
-
-### `-p` 标志
-
-你也可以通过任意命令显式指定 profile：
-
-```bash
-hermes -p coder chat
-hermes --profile=coder doctor
-hermes chat -p coder -q "hello"    # 可在任意位置使用
-```
-
-### 粘性默认值（`hermes profile use`）
-
-```bash
-hermes profile use coder
-hermes chat                   # 现在指向 coder
-hermes tools                  # 配置 coder 的工具
-hermes profile use default    # 切换回默认
-```
-
-设置默认值后，普通 `hermes` 命令将指向该 profile。类似于 `kubectl config use-context`。
-
-### 了解当前所在 profile
-
-CLI 始终显示当前活跃的 profile：
-
-- **提示符**：显示 `coder ❯` 而非 `❯`
-- **启动横幅**：启动时显示 `Profile: coder`
-- **`hermes profile`**：显示当前 profile 名称、路径、模型、gateway 状态
-
-## Profile vs 工作区 vs 沙箱
-
-profile 常与工作区或沙箱混淆，但它们是不同的概念：
-
-- **profile** 为 Hermes 提供独立的状态目录：`config.yaml`、`.env`、`SOUL.md`、会话、记忆、日志、cron 任务和 gateway 状态。
-- **工作区**或**工作目录**是终端命令的起始位置，由 `terminal.cwd` 单独控制。
-- **沙箱**用于限制文件系统访问。profile **不**对 agent 进行沙箱隔离。
-
-在默认的 `local` 终端后端，agent 仍拥有与你的用户账户相同的文件系统访问权限。profile 不会阻止其访问 profile 目录之外的文件夹。
-
-如果你希望 profile 默认在特定项目文件夹中启动，请在该 profile 的 `config.yaml` 中设置绝对路径的 `terminal.cwd`：
-
-```yaml
-terminal:
-  backend: local
-  cwd: /absolute/path/to/project
-```
-
-在 local 后端使用 `cwd: "."` 表示"Hermes 启动时所在的目录"，而非"profile 目录"。
-
-另请注意：
-
-- `SOUL.md` 可以引导模型，但不能强制限定工作区边界。
-- `SOUL.md` 的更改在新会话中会生效。现有会话可能仍在使用旧的 prompt（提示词）状态。
-- 询问模型"你在哪个目录？"并不是可靠的隔离测试。如果你需要工具有可预测的起始目录，请显式设置 `terminal.cwd`。
-
-## 运行 gateway
-
-每个 profile 以独立进程运行各自的 gateway，使用各自的 bot token：
-
-```bash
-coder gateway start           # 启动 coder 的 gateway
-assistant gateway start       # 启动 assistant 的 gateway（独立进程）
-```
-
-### 不同的 bot token
-
-每个 profile 有各自的 `.env` 文件。在各文件中配置不同的 Telegram/Discord/Slack bot token：
-
-```bash
-# 编辑 coder 的 token
-nano ~/.hermes/profiles/coder/.env
-
-# 编辑 assistant 的 token
-nano ~/.hermes/profiles/assistant/.env
-```
-
-### 安全性：token 锁
-
-如果两个 profile 意外使用了相同的 bot token，第二个 gateway 将被阻止并显示明确的错误信息，指出冲突的 profile。支持 Telegram、Discord、Slack、WhatsApp 和 Signal。
-
-### 持久化服务
-
-```bash
-coder gateway install         # 创建 hermes-gateway-coder systemd/launchd 服务
-assistant gateway install     # 创建 hermes-gateway-assistant 服务
-```
-
-每个 profile 拥有独立的服务名称，各自独立运行。
-
-:::note 在官方 Docker 镜像中
-各 profile 的 gateway 由 [s6-overlay](https://github.com/just-containers/s6-overlay)（容器中的 PID 1）监管，因此 `hermes profile create <name>` 会自动在 `/run/service/gateway-<name>/` 注册 s6 服务槽。`hermes -p <name> gateway start/stop/restart` 会调度到 `s6-svc` 而非直接启动裸进程——崩溃后自动重启，`docker restart` 会保留之前运行的 gateway 集合。详见 [各 profile gateway 监管](/user-guide/docker#per-profile-gateway-supervision)。
-:::
-
-## 配置 profile
-
-每个 profile 拥有各自的：
-
-- **`config.yaml`** — 模型、提供商、工具集及所有设置
-- **`.env`** — API 密钥、bot token
-- **`SOUL.md`** — 人格与指令
-
-```bash
-coder config set model.default anthropic/claude-sonnet-4
-echo "You are a focused coding assistant." > ~/.hermes/profiles/coder/SOUL.md
-```
-
-如果你希望此 profile 默认在特定项目中工作，还需设置其 `terminal.cwd`：
-
-```bash
-coder config set terminal.cwd /absolute/path/to/project
-```
-
-## 更新
-
-`hermes update` 拉取一次代码（共享），并自动将新的内置技能同步到**所有** profile：
-
-```bash
-hermes update
-# → Code updated (12 commits)
-# → Skills synced: default (up to date), coder (+2 new), assistant (+2 new)
-```
-
-用户修改过的技能不会被覆盖。
-
-## 管理 profile
-
-```bash
-hermes profile list           # 显示所有 profile 及其状态
-hermes profile show coder     # 显示某个 profile 的详细信息
-hermes profile rename coder dev-bot   # 重命名（同步更新别名和服务）
-hermes profile export coder   # 导出为 coder.tar.gz
-hermes profile import coder.tar.gz   # 从归档文件导入
-```
-
-## 删除 profile
-
-```bash
-hermes profile delete coder
-```
-
-此操作将停止 gateway、移除 systemd/launchd 服务、移除命令别名并删除所有 profile 数据。系统会要求你输入 profile 名称以确认。
-
-使用 `--yes` 跳过确认：`hermes profile delete coder --yes`
-
-:::note
-你无法删除默认 profile（`~/.hermes`）。如需删除所有内容，请使用 `hermes uninstall`。
-:::
-
-## Tab 补全
-
-```bash
-# Bash
-eval "$(hermes completion bash)"
-
-# Zsh
-eval "$(hermes completion zsh)"
-```
-
-将该行添加到 `~/.bashrc` 或 `~/.zshrc` 以启用持久补全。支持补全 `-p` 后的 profile 名称、profile 子命令及顶级命令。
-
-## 工作原理
-
-profile 使用 `HERMES_HOME` 环境变量。运行 `coder chat` 时，包装脚本在启动 hermes 前将 `HERMES_HOME` 设置为 `~/.hermes/profiles/coder`。由于代码库中 119+ 个文件通过 `get_hermes_home()` 解析路径，Hermes 状态会自动限定在 profile 目录范围内——包括配置、会话、记忆、技能、状态数据库、gateway PID、日志和 cron 任务。
-
-这与终端工作目录是分开的。工具执行从 `terminal.cwd` 开始（或在 local 后端使用 `cwd: "."` 时从启动目录开始），而非自动从 `HERMES_HOME` 开始。
-
-默认 profile 就是 `~/.hermes` 本身。无需迁移——现有安装的工作方式完全不变。
-
-## 将 profile 作为发行版共享
-
-你在一台机器上构建的 profile 可以打包为 **git 仓库**，并通过一条命令安装到另一台机器——你自己的工作站、团队成员的笔记本，或社区用户的环境。共享包包含 SOUL、配置、技能、cron 任务和 MCP 连接。凭据、记忆和会话保持各机器独立。
-
-```bash
-# 从 git 仓库安装完整 agent
-hermes profile install github.com/you/research-bot --alias
-
-# 当作者发布新版本时更新（保留你的记忆和 .env）
-hermes profile update research-bot
-```
-
-完整指南请参阅 **[Profile 发行版：共享完整 Agent](./profile-distributions.md)**——包括编写、发布、更新语义、安全模型和使用场景。

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

@@ -1,143 +0,0 @@
-# Bitwarden Secrets Manager
-
-在进程启动时从 [Bitwarden Secrets Manager](https://bitwarden.com/products/secrets-manager/) 拉取 API 密钥，而不是以明文形式存储在 `~/.hermes/.env` 中。一个引导密钥（机器账户访问令牌）替代了 N 个提供商密钥，轮换凭据只需在 Bitwarden Web 应用中修改一次即可。
-
-## 工作原理
-
-1. 在 Bitwarden Secrets Manager 中创建一个**机器账户**，授予其对某个项目的读取权限，并生成一个**访问令牌**。
-2. Hermes 将该单一令牌以 `BWS_ACCESS_TOKEN` 的形式存储在 `~/.hermes/.env` 中。
-3. 每次 `hermes`（或 gateway，或 cron 任务）启动时，在加载 `~/.hermes/.env` 之后，Hermes 会调用 `bws secret list <project_id>` 并将返回的密钥写入 `os.environ`。
-4. 默认情况下，Hermes **覆盖**环境中已有的值，因此 Bitwarden 是唯一可信来源——在 Web 应用中轮换一次密钥，每个 Hermes 进程在下次启动时即可获取最新值。如果希望 `.env` 优先，可在配置中将 `override_existing: false`。
-
-`bws` 二进制文件在首次使用时会自动下载到 `~/.hermes/bin/`，无需 `apt`、`brew` 或 `sudo`。
-
-## 为什么使用机器账户（以及为什么没有双因素认证提示）
-
-Bitwarden Secrets Manager 专为非交互式工作负载设计：机器账户不能设置双因素认证（2FA）门控，因为流程中没有人工介入。访问令牌本身就是凭据。任何持有该令牌的人都可以读取机器账户有权访问的所有密钥，因此请将其视为高价值的 bearer token（持有者令牌）——将其存储在 `.env` 中（而非 `config.yaml`），如果泄露，请立即在 Bitwarden Web 应用中吊销并重新生成。
-
-机器账户在 *Web 应用中*设置，此时你的正常双因素认证仍然有效。之后令牌即可自主运行。
-
-## 设置
-
-### 1. 创建机器账户和访问令牌
-
-在 [Bitwarden Web 应用](https://vault.bitwarden.com)（欧盟账户请使用 [vault.bitwarden.eu](https://vault.bitwarden.eu)）中：
-
-1. 通过产品切换器切换到 **Secrets Manager**。
-2. 创建或选择一个**项目**（例如"Hermes keys"）。
-3. 将提供商密钥添加为 secret。secret 的**名称**将成为环境变量名——使用 `OPENROUTER_API_KEY`、`ANTHROPIC_API_KEY` 等。
-4. **Machine accounts → New machine account → My Hermes machine** → **Projects** 标签页 → 授予对你的项目的 Read 权限。
-5. **Access tokens** 标签页 → **Create access token** → 选择**永不**过期（或指定日期）→ 复制令牌（以 `0.` 开头）。Bitwarden 无法再次检索该令牌——请妥善保存副本。
-
-Secrets Manager 包含在 Bitwarden 免费套餐中（有使用限制）；无需付费计划即可试用。
-
-### 2. 运行向导
-
-```bash
-hermes secrets bitwarden setup
-```
-
-该命令将：
-
-1. 下载并验证 `bws v2.0.0`，存放至 `~/.hermes/bin/bws`。
-2. 提示输入访问令牌（输入内容隐藏）。以 `BWS_ACCESS_TOKEN` 形式存储在 `~/.hermes/.env` 中。
-3. 询问机器账户所属的 Bitwarden 区域——**US Cloud**、**EU Cloud** 或**自托管/自定义 URL**。以 `secrets.bitwarden.server_url` 形式存储在 `config.yaml` 中，并作为 `BWS_SERVER_URL` 传递给 `bws`。
-4. 列出机器账户可见的项目，选择其中一个。以 `secrets.bitwarden.project_id` 形式存储在 `config.yaml` 中。
-5. 测试拉取该项目的 secret，并显示将解析出哪些环境变量。
-6. 将 `secrets.bitwarden.enabled` 设置为 `true`。
-
-也支持通过参数进行非交互式设置：
-
-```bash
-hermes secrets bitwarden setup \
-  --access-token "$BWS_ACCESS_TOKEN" \
-  --server-url https://vault.bitwarden.eu \
-  --project-id <project-uuid>
-```
-
-### 3. 确认
-
-```bash
-hermes secrets bitwarden status
-```
-
-此后，每次调用 `hermes` 都会在启动时拉取最新 secret。进程中首次应用 secret 时，stderr 会显示一行摘要信息。
-
-## CLI
-
-| 命令 | 功能 |
-|---|---|
-| `hermes secrets bitwarden setup` | 交互式向导（安装二进制文件、提示输入令牌、选择项目、测试拉取） |
-| `hermes secrets bitwarden status` | 显示配置、二进制版本，以及令牌是否存在/是否通过校验 |
-| `hermes secrets bitwarden token` | 轮换访问令牌：先向 Bitwarden 验证新令牌，验证通过后再写入 `.env` |
-| `hermes secrets bitwarden sync` | 演习模式：立即拉取 secret 并显示将应用的内容 |
-| `hermes secrets bitwarden sync --apply` | 拉取并导出到当前 shell 的环境中 |
-| `hermes secrets bitwarden install` | 仅下载固定版本的 `bws` 二进制文件（无需认证） |
-| `hermes secrets bitwarden disable` | 将 `enabled` 设为 `false`；保留令牌和项目 ID |
-
-## 轮换已过期或已吊销的令牌
-
-当机器账户令牌过期、被吊销或账户被删除时，启动信息会显示令牌被拒绝的说明，并附带 `→` 修复提示。无需重新运行整个向导即可修复：
-
-```bash
-hermes secrets bitwarden token                     # 隐藏输入提示
-hermes secrets bitwarden token --access-token 0.…  # 非交互式
-```
-
-该命令会在写入任何内容**之前**用新令牌探测 Bitwarden——令牌被拒绝时不会改动现有 `.env`。成功后会存储令牌、清除拉取缓存，并在配置的项目对新机器账户不可见时发出警告。
-
-## 配置
-
-`~/.hermes/config.yaml` 中的默认值：
-
-```yaml
-secrets:
-  bitwarden:
-    enabled: false
-    access_token_env: BWS_ACCESS_TOKEN
-    project_id: ""
-    server_url: ""
-    cache_ttl_seconds: 300
-    override_existing: true
-    auto_install: true
-```
-
-| 键 | 默认值 | 功能 |
-|---|---|---|
-| `enabled` | `false` | 主开关。为 false 时，永不联系 Bitwarden。 |
-| `access_token_env` | `BWS_ACCESS_TOKEN` | 存储引导令牌的环境变量名。如果你已将 `BWS_ACCESS_TOKEN` 用于其他用途，可修改此项。 |
-| `project_id` | `""` | 要同步的项目 UUID。 |
-| `server_url` | `""` | Bitwarden 区域或自托管端点。为空时使用 `bws` 默认值（US Cloud，`https://vault.bitwarden.com`）。欧盟云设为 `https://vault.bitwarden.eu`，自托管则填写自己的 URL。以 `BWS_SERVER_URL` 形式传递给 `bws` 子进程。 |
-| `cache_ttl_seconds` | `300` | 进程内拉取结果的复用时长。设为 `0` 可禁用缓存。缓存按进程隔离；新的 `hermes` 调用从头开始。 |
-| `override_existing` | `true` | 为 true 时，Bitwarden 的值会覆盖环境中已有的任何值（使 Web 应用中的轮换真正生效）。如果希望本地 `.env` / shell 导出优先，设为 `false`。 |
-| `auto_install` | `true` | 为 true 时，首次使用时自动将 `bws` 下载到 `~/.hermes/bin/`。 |
-
-## 故障模式
-
-Bitwarden 永远不会阻塞 Hermes 启动。如果出现任何问题，stderr 会显示一行警告，Hermes 继续使用 `.env` 中已有的凭据：
-
-| 现象 | 原因 | 修复方法 |
-|---|---|---|
-| `BWS_ACCESS_TOKEN is not set` | 配置中已启用，但令牌已从 `.env` 中清除 | 重新运行 `hermes secrets bitwarden setup` |
-| `Bitwarden rejected the machine-account access token … invalid_client` | 令牌已吊销、过期、机器账户被删除——或令牌属于其他区域（例如欧盟令牌访问了美国 identity 端点） | 运行 `hermes secrets bitwarden token` 粘贴新令牌；区域不匹配时重新运行 setup 选择欧盟/自托管（或设置 `secrets.bitwarden.server_url`） |
-| `bws exited 1: invalid access token` | 令牌已吊销或有误 | 运行 `hermes secrets bitwarden token` 提供新令牌 |
-| `bws timed out` | 网络受阻或 Bitwarden API 响应缓慢 | 检查到 `api.bitwarden.com`（或你的 `server_url`）的连通性 |
-| `bws binary not available` | `auto_install: false` 且 `bws` 不在 PATH 中 | 从 [github.com/bitwarden/sdk-sm/releases](https://github.com/bitwarden/sdk-sm/releases) 手动安装，或重新开启 `auto_install` |
-| `Checksum mismatch` | 下载内容损坏或被篡改 | 重新运行，将自动重试；如持续出现，请提交 issue |
-
-启动警告现在会附带一行 `→` 修复提示，直接告诉你运行哪条命令即可修复。
-
-## 安全说明
-
-- 引导令牌（`BWS_ACCESS_TOKEN`）本身是敏感信息——任何持有它的人都可以读取机器账户有权访问的所有 secret。请与其他 API 密钥同等对待。
-- 即使 `override_existing: true`，Hermes 也会拒绝让 Bitwarden 覆盖引导令牌本身。如果你将 `BWS_ACCESS_TOKEN` 作为 secret 存储在项目中，应用时会静默跳过。
-- `bws` 二进制文件的下载会与同一 GitHub release 中发布的 SHA-256 校验和进行验证。不匹配时将中止安装。
-- 固定版本（撰写本文时为 `bws v2.0.0`）通过向本仓库提交 PR 的方式更新——Hermes 不会将 `bws` 自动升级到"最新版本"，因为上游 release 的结构可能发生变化。
-
-## 不适用场景
-
-- **单机个人使用**，`~/.hermes/.env` 已经够用。你只是用一个凭据换了另一个，并在启动时增加了网络依赖。
-- **无法访问 `api.bitwarden.com` 的隔离环境**。
-- **CI/CD** 场景，已有现成的 secret 注入机制（GitHub Actions secrets、Vault 等）——选择一种方式，不要两者并用。
-
-适合使用此功能的场景：多机器集群、共享开发机、gateway VPS，或任何需要跨多个 Hermes 安装进行集中轮换和吊销管理的场景。

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

@@ -1,9 +0,0 @@
-# Secrets
-
-Hermes 可以在进程启动时从外部密钥管理器拉取 API 密钥，而不是将其存储在 `~/.hermes/.env` 中。密钥管理器的引导令牌存放在 `.env` 中；其他所有提供商密钥（OpenAI、Anthropic、OpenRouter 等）可以保留在管理器中并集中轮换。
-
-支持的后端：
-
-- [Bitwarden Secrets Manager](./bitwarden) — 使用 `bws` CLI，懒加载安装，免费套餐可用。
-
-更多后端（Vault、AWS Secrets Manager、1Password CLI）可以轻松接入同一接口——只需在 `agent/secret_sources/` 中添加一个模块并实现一个 CLI 处理器。如有特定需求，欢迎提交请求。