better-dsh 0.2.4 → 0.2.5

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

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

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

@@ -0,0 +1,9 @@
+# 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 处理器。如有特定需求，欢迎提交请求。