0. 使用前提

这个插件本身不内置任何大模型——它的"大脑"是你本地跑着的 Hermes Agent。装之前，确认下面四件事都满足，否则桌宠会出现但"大脑离线"。

前提 1：本机已装 DSH 并能跑 web GUI

dsh --profile web     # 能打开 http://127.0.0.1:3080 即可

前提 2：本机有 Hermes Agent 的 gateway 在运行

本插件只通过 HTTP 调 Hermes 的 API Server，不直接碰 Hermes 进程。参考 Hermes Agent。

API Server 是 Hermes gateway 的一个 platform adapter（gateway/platforms/api_server.py），不是独立进程。它只在 gateway 运行时才会监听端口——所以前提 2 实际要求"有一个正在跑的 Hermes gateway，且启用了 API Server"。只跑交互式 hermes CLI（不启 gateway）时，127.0.0.1:8642 上没有任何监听者，插件的 chat-status 会报 healthy:false。

前提 3（关键）：Hermes 的 API Server 网关已开启

Hermes 默认不开 API Server（API_SERVER_ENABLED 默认 false），而本插件只能通过这个网关对话。所以你必须先把 Hermes 的 API Server 网关配好。

Hermes API Server 网关的配置细节

Hermes 的 API Server 是一个 OpenAI 兼容的 HTTP 网关，由以下项控制（环境变量，或 ~/.hermes/config.yaml 的 gateway.api_server: 段，config.yaml 优先级更高——同名项以 config.yaml 为准）：

环境变量	默认值	说明	本插件要求
`API_SERVER_ENABLED`	`false`	是否开启 API Server	必须 `true`，否则插件连不上
`API_SERVER_PORT`	`8642`	HTTP 端口	插件默认连 `8642`；改端口要在插件 `endpoint` 同步改
`API_SERVER_HOST`	`127.0.0.1`	绑定地址（默认仅本机）	保持 `127.0.0.1`（插件强制 loopback，不接远程 Hermes）
`API_SERVER_KEY`	(必填)	Bearer 鉴权密钥	必须有值，且 ≥16 字符、不能是占位符（`hermes` / `example` / `sk-…` 之类会被启动守卫直接拒）；插件用它调 Hermes（见下）
`API_SERVER_CORS_ORIGINS`	(无)	允许的浏览器来源	本插件用不到（插件走 host 端转发，不是浏览器直连）
`API_SERVER_MODEL_NAME`	default profile → `hermes-agent`；命名 profile → 该 profile 名	`/v1/models` 里的 model 名	插件默认用 `hermes-agent`；若你用的是命名 profile 且没设 `API_SERVER_MODEL_NAME`，这里实际是 profile 名，插件 `model` 要改成它（`/v1/models` 可查）

开启步骤（二选一）

方式 A：环境变量 / .env 文件

两种方式，config.yaml 的 gateway.api_server: 段会覆盖环境变量（见方式 B），二者等价但 config.yaml 优先。

进程级 env（Hermes 启动前 export）：

export API_SERVER_ENABLED=true
export API_SERVER_PORT=8642
export API_SERVER_KEY=***   # ≥16 字符，非占位符

~/.hermes/.env 文件（推荐，跨重启持久）：在文件里加 API_SERVER_KEY=。Hermes 的 secret 读取链（hermes_cli/auth.py::has_usable_secret / _get_scoped_secret）会优先从 .env 读，避免被父进程遗留的旧 export 遮蔽——如果你既 export 过又写进 .env，以 .env 为准。

API_SERVER_ENABLED 这个 env 开关是最弱的启用路径：gateway 的 config loader（gateway/config.py）实际的主检查是"key 是否存在且够强"，key 一到位平台就会注册，enabled 只是显式标记。所以把 key 放对位置就够了，enabled: true 是双保险。

方式 B：配置文件 ~/.hermes/config.yaml

gateway:
  api_server:
    enabled: true
    port: 8642
    host: 127.0.0.1
    key:    # ≥16 字符，非占位符；与 .env 里的值一致

注意：

key 的读取位置：默认 profile 读 ~/.hermes/.env；命名 profile 读 ~/.hermes/profiles/ /.env。config.yaml 的 gateway.api_server.key 若设了，会覆盖 .env（api_server.py:1376 的 extra.get("key", ...) 优先）。

key 的强度是硬门槛：启动守卫（api_server.py::_api_key_passes_startup_guard）要求 API_SERVER_KEY ≥16 字符且非占位符，否则拒绝启动——不是警告，是 fail-closed，监听器根本不会起来，gateway 日志会打 Refusing to start: API_SERVER_KEY ...。弱 key 不会"降级运行"，只会让 8642 端口没有服务。

即使 loopback 绑定也强制要 key：API_SERVER_HOST=127.0.0.1 不是免鉴权，所有部署（含仅本机）都必须有可用 key。

验证 Hermes 网关已就绪


# 备份原 profile 配置（含 cordis.patch.yml）
$web = "$env:USERPROFILE\.dsh\profiles\web"
Copy-Item "$web\cordis.patch.yml" "$web\cordis.patch.yml.bak-pet-hermes"

## 5. 配置

对话桥的配置在 **host 侧**（`src/chat.ts`），有默认值，**开箱即用**——指向本地 Hermes 默认端点、默认 token 文件。

### 5.1 通过 GUI 设置卡配置（推荐）

插件在 DSH Web 的**设置 → Hermes 桌宠**提供了一级设置页（和原 `@linxin666/dsh-pet` 的"宠物"页并列）。点进去可改：

| 字段 | 说明 |
|---|---|
| 启用桌宠 | **持久总开关**。关 = 整个入口（精灵 + 召唤按钮）完全不渲染，唯一恢复方式是在这里改回"开"；开 = 精灵按 `visible` 状态显示 |
| Hermes API 地址 | Hermes 的 OpenAI 兼容网关基址（如 `http://127.0.0.1:8642`）。**必须 loopback** |
| 模型名 | `/v1/models` 里的 model id（如 `hermes-agent`） |
| 人设 | system prompt，留空用内置鲸鱼娘人设 |
| 历史轮数上限 | 每轮转发给 Hermes 的最大消息数（1–200） |
| 请求超时（毫秒） | 单次对话超时上限（1000–600000） |

**保存后行为**：
- 改 **启用桌宠** → 立即生效（关 = 精灵和按钮全消失；开 = 精灵出现），**重启 DSH 后保持**（写进 `~/.dsh/settings.yaml` 的 `pet-hermes:` 段）
- 改 **Hermes API 地址** → 保存后立即重新探测 Hermes 状态（"大脑在线/离线"标签更新）
- 改其他字段 → 保存后立即生效（host 每次请求时从 settings 读最新值）

> **与精灵右上角 × 按钮的区别**：× 是**临时隐藏**（`visible` 状态，关后显示"🐋 召唤鲸鱼娘"按钮，点按钮可临时召唤回来）；设置卡的"启用桌宠"是**持久开关**（`enabled`，关后完全消失、无召唤按钮，只能在设置里重新开）。两者独立：`enabled=false` 时 × 按钮和召唤按钮都不渲染。

### 5.2 通过 settings.yaml 直接配置

设置卡的字段持久化到 `~/.dsh/settings.yaml` 的 `pet-hermes:` 段（由 `@deepseek-ai/dsh-settings-file` provider 管理）。你也可以直接编辑这个文件。

**只写显式 override 的字段**：`pet-hermes:` 段里**只出现你在设置卡里改过（或手动加过）的字段**，没改过的字段不写文件——它们走 5.3 的 schema 默认值。所以首次只改过"启用桌宠"时，文件里通常只有一行：

```yaml
pet-hermes:
  enabled: true

改过 endpoint、model 等字段后才会逐行追加，例如：

pet-hermes:
  enabled: true
  endpoint: http://127.0.0.1:8642
  model: hermes-agent

"恢复默认"：设置卡里点某字段的"恢复默认"（或手动删掉文件里那行）= 把该字段从 user 层移除，回退到 schema 默认值。字段不存在 ≠ 错误，就是"用默认"。

外部编辑热生效：dsh-settings-file 用 chokidar 监听文件变化，你在编辑器里改 settings.yaml 的 pet-hermes: 段并保存，DSH 会不重启地重新解析并生效（和设置卡保存等效）。

5.3 配置项（host 侧 `src/chat.ts` 默认值）

所有字段都有默认值，开箱即用。settings 段里的字段会覆盖这些默认值（resolution 层叠：schema 默认 → composition base → user 段）。

项	默认值	说明
`endpoint`	`http://127.0.0.1:8642`	Hermes API Server 地址，必须 loopback
`model`	`hermes-agent`	Hermes 暴露的 model id（`GET /v1/models` 可查）
`token`	—（见下）	Bearer 密钥，优先级最高
`tokenFile`	插件根目录的 `token.txt`（留空即此默认）	密钥文件路径（一行一个 token）。首次安装把你的 key 放进这里，或填绝对路径指向别处
`persona`	内置鲸鱼娘人设	每轮 prepend 的 system prompt
`maxHistory`	`20`	每轮转发给 Hermes 的最大历史消息数（超出截断最旧）
`timeoutMs`	`120000`	单轮超时（ms），超时中止流式
`enabled`	`true`	持久总开关，false 时整个入口不渲染（chat 路由仍返回 409）

token 不是 settings 字段（密钥不进 settings.yaml，避免被共享/提交）。token 的读取见下节。

Token 读取优先级

显式 token 配置值
环境变量 DSH_PET_HERMES_TOKEN
tokenFile 文件内容 —— tokenFile 留空（settings.yaml 默认）时，回退到插件根目录的 token.txt

安全：token 永远只在 host 进程里读取，不会出现在浏览器、网络响应或日志里。不要把密钥值写进任何前端可见的地方；token.txt 建议加入你的 .gitignore（如果这个目录在版本库里）。

首次安装：把你的 Hermes 接上

这是首次安装者唯一必须做的事——告诉插件"你的 Hermes 在哪、key 在哪"。

确认你的 Hermes 在跑且开了 API Server：
```
curl http://127.0.0.1:8642/health -UseBasicParsing
# 应返回 {"status":"ok","platform":"hermes-agent",...}
```
- 端口不是 8642？记下实际端口，下面 endpoint 要改。
- 没开 API Server？先去 Hermes 那边开（见 Hermes 文档的 api-server 功能）。
把你的 Hermes API key 放进插件根目录的 token.txt（最省事）：
- 插件根 = ~/.dsh/profiles/web/node_modules/dsh-pet-hermes/（部署后的位置）
- 新建 token.txt，内容就是一整行你的 Hermes API key（无引号、无多余空格/换行）：
```
你的hermes-api-key-贴这一行
```
- 不想放默认位置？在 settings.yaml 里给 tokenFile 填你自己的绝对路径即可（见下）。

（可选）改 endpoint / persona 等：在 ~/.dsh/settings.yaml 加块（只有改过才会写入，不改就走默认）：

pet-hermes:
  endpoint: http://127.0.0.1:8642     # 你的 Hermes 端口
  model: hermes-agent                  # 一般不用改
  tokenFile: ""                        # 留空=用插件根/token.txt；或填你的 key 路径
  persona: ""                          # 留空=内置鲸鱼娘人设
  maxHistory: 20
  timeoutMs: 120000

重启 DSH + 验证：

dsh --profile web
curl http://127.0.0.1:3080/api/pet-hermes/chat-status -UseBasicParsing
# 应返回 {"ok":true,"enabled":true,"healthy":true,...}

healthy: true = 连上了。去 GUI 点桌宠试对话。

首次配置错误对照

`chat-status` / 对话现象	原因	解决
`healthy: false`	Hermes 没起 / 端口不对	`curl /health` 确认通；改 `endpoint`
`chat-token-missing` (409)	token.txt 没放 / 路径错	把 key 放进插件根 `token.txt`；或 settings.yaml 填 `tokenFile`；或设 env
对话 401	key 值不对	token.txt 要纯 token，无空格/引号/换行残留
`chat-endpoint-not-loopback` (400)	endpoint 不是 127.0.0.1/localhost	Hermes 必须本机；改 `endpoint` 为 `http://127.0.0.1:端口`

改 Hermes 端点/密钥（不改代码）

最省事的方式是环境变量（在启动 DSH 前设置）：

$env:DSH_PET_HERMES_TOKEN = "你的hermes密钥"
dsh --profile web

或改 src/chat.ts 顶部的 DEFAULT_CHAT_* 常量后重新构建（见构建）。

改人设（persona）

默认 persona 在 src/chat.ts 的 DEFAULT_CHAT_PERSONA：

你是用户的桌面鲸鱼娘伙伴，住在他的电脑右下角。用轻松、俏皮、简短的中文陪他聊天，
像会说话的小宠物：有温度、偶尔撒娇、记得他告诉你的事。回答尽量控制在两三句内，
除非他要求详细。不要自称 AI 助手或模型。

改它 → 重新构建。这是控制"她说话什么口吻"的地方。

5.1 通过 GUI 设置卡配置（推荐）

插件在 DSH Web 的设置 → Hermes 桌宠提供了一级设置页（和原 @linxin666/dsh-pet 的"宠物"页并列）。点进去可改：

字段	说明
启用桌宠	持久总开关。关 = 整个入口（精灵 + 召唤按钮）完全不渲染，唯一恢复方式是在这里改回"开"；开 = 精灵按 `visible` 状态显示
Hermes API 地址	Hermes 的 OpenAI 兼容网关基址（如 `http://127.0.0.1:8642`）。必须 loopback
模型名	`/v1/models` 里的 model id（如 `hermes-agent`）
人设	system prompt，留空用内置鲸鱼娘人设
历史轮数上限	每轮转发给 Hermes 的最大消息数（1–200）
请求超时（毫秒）	单次对话超时上限（1000–600000）

保存后行为：

改 启用桌宠 → 立即生效（关 = 精灵和按钮全消失；开 = 精灵出现），重启 DSH 后保持（写进 ~/.dsh/settings.yaml 的 pet-hermes: 段）
改 Hermes API 地址 → 保存后立即重新探测 Hermes 状态（"大脑在线/离线"标签更新）
改其他字段 → 保存后立即生效（host 每次请求时从 settings 读最新值）

与精灵右上角 × 按钮的区别：× 是临时隐藏（visible 状态，关后显示"🐋 召唤鲸鱼娘"按钮，点按钮可临时召唤回来）；设置卡的"启用桌宠"是持久开关（enabled，关后完全消失、无召唤按钮，只能在设置里重新开）。两者独立：enabled=false 时 × 按钮和召唤按钮都不渲染。

5.2 通过 settings.yaml 直接配置

设置卡的字段持久化到 ~/.dsh/settings.yaml 的 pet-hermes: 段（由 @deepseek-ai/dsh-settings-file provider 管理）。你也可以直接编辑这个文件。

只写显式 override 的字段：pet-hermes: 段里只出现你在设置卡里改过（或手动加过）的字段，没改过的字段不写文件——它们走 5.3 的 schema 默认值。所以首次只改过"启用桌宠"时，文件里通常只有一行：

pet-hermes:
  enabled: true

改过 endpoint、model 等字段后才会逐行追加，例如：

pet-hermes:
  enabled: true
  endpoint: http://127.0.0.1:8642
  model: hermes-agent

5.3 配置项（host 侧 `src/chat.ts` 默认值）

所有字段都有默认值，开箱即用。settings 段里的字段会覆盖这些默认值（resolution 层叠：schema 默认 → composition base → user 段）。

项	默认值	说明
`endpoint`	`http://127.0.0.1:8642`	Hermes API Server 地址，必须 loopback
`model`	`hermes-agent`	Hermes 暴露的 model id（`GET /v1/models` 可查）
`token`	—（见下）	Bearer 密钥，优先级最高
`tokenFile`	插件根目录的 `token.txt`（留空即此默认）	密钥文件路径（一行一个 token）。首次安装把你的 key 放进这里，或填绝对路径指向别处
`persona`	内置鲸鱼娘人设	每轮 prepend 的 system prompt
`maxHistory`	`20`	每轮转发给 Hermes 的最大历史消息数（超出截断最旧）
`timeoutMs`	`120000`	单轮超时（ms），超时中止流式
`enabled`	`true`	持久总开关，false 时整个入口不渲染（chat 路由仍返回 409）

token 不是 settings 字段（密钥不进 settings.yaml，避免被共享/提交）。token 的读取见下节。

2. 还原 profile 配置

Copy-Item "$web\cordis.patch.yml.bak-pet-hermes" "$web\cordis.patch.yml" -Force

安装

说明文档

0. 使用前提

前提 1：本机已装 DSH 并能跑 web GUI

前提 2：本机有 Hermes Agent 的 gateway 在运行

前提 3（关键）：Hermes 的 API Server 网关已开启

Hermes API Server 网关的配置细节

开启步骤（二选一）

验证 Hermes 网关已就绪

5.3 配置项（host 侧 src/chat.ts 默认值）

Token 读取优先级

首次安装：把你的 Hermes 接上

首次配置错误对照

改 Hermes 端点/密钥（不改代码）

改人设（persona）

5.1 通过 GUI 设置卡配置（推荐）

5.2 通过 settings.yaml 直接配置

5.3 配置项（host 侧 src/chat.ts 默认值）

2. 还原 profile 配置

5.3 配置项（host 侧 `src/chat.ts` 默认值）

5.3 配置项（host 侧 `src/chat.ts` 默认值）