Merge pull request #248 from modelstudioai/fix/hermes-home-env

fix(config): resolve Hermes home via HERMES_HOME and platform default (prepare 2.2.1)

Author: lishengzxc

CHANGELOG.md

@@ -6,6 +6,12 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 [中文版](CHANGELOG.zh.md) · [README](README.md) · [Contributing](CONTRIBUTING.md)
 
+## [2.2.1] - 2026-10-12
+
+### Fixed
+
+- **Hermes agent config path** — `bl config agent --agent hermes` now writes to the location Hermes actually reads (`$HERMES_HOME/config.yaml`, or the platform-native default: `%LOCALAPPDATA%\hermes` on Windows, `~/.hermes` elsewhere) instead of always `~/.hermes/config.yaml`. Previously on Windows or with a custom `HERMES_HOME`, config landed where Hermes never read it and the change silently took no effect; agent detection could also falsely report Hermes as unconfigured.
+
 ## [2.2.0] - 2026-10-12
 
 ### Changed

CHANGELOG.zh.md

@@ -6,6 +6,12 @@
 
 [English](CHANGELOG.md) · [README](README.zh.md) · [参与贡献](CONTRIBUTING.zh.md)
 
+## [2.2.1] - 2026-10-12
+
+### 修复
+
+- **Hermes Agent 配置路径** —— `bl config agent --agent hermes` 现在会写入 Hermes 实际读取的位置（`$HERMES_HOME/config.yaml`，或平台原生默认路径：Windows 为 `%LOCALAPPDATA%\hermes`，其它平台为 `~/.hermes`），不再固定写 `~/.hermes/config.yaml`。此前在 Windows 或自定义 `HERMES_HOME` 环境下，配置被写到 Hermes 不读取的文件、变更静默失效，Agent 探测也可能误报 Hermes 为「未配置」。
+
 ## [2.2.0] - 2026-10-12
 
 ### 变更

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bailian-cli",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "CLI for Aliyun Model Studio (DashScope) AI Platform.",
   "keywords": [
     "agent",

packages/commands/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bailian-cli-commands",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "Command library for bailian-cli products (knowledge, memory, media, …). See https://www.npmjs.com/package/bailian-cli for usage.",
   "homepage": "https://bailian.console.aliyun.com/cli",
   "bugs": {

packages/commands/src/commands/config/agent/writers/hermes.ts

@@ -1,13 +1,15 @@
-import { homedir } from "os";
 import { join } from "path";
 import { existsSync, readFileSync } from "fs";
 import yaml from "yaml";
+import { getHermesHome } from "bailian-cli-core";
 import { backup, writeTextAtomic, isAnthropicEndpoint, type AgentDef } from "./utils.ts";
 
 export default {
   label: "Hermes Agent",
   write({ baseUrl, apiKey, model }) {
-    const configPath = join(homedir(), ".hermes", "config.yaml");
+    // Honor HERMES_HOME / the platform-native default so the config lands where
+    // Hermes actually reads it (see core getHermesHome); never hard-code ~/.hermes.
+    const configPath = join(getHermesHome(), "config.yaml");
 
     backup(configPath);
 

packages/commands/src/commands/config/inventory.ts

@@ -19,6 +19,7 @@ import {
 import { inflateRawSync } from "node:zlib";
 import yaml from "yaml";
 import { parse as parseToml } from "smol-toml";
+import { getHermesHome } from "bailian-cli-core";
 import { qwenworkMcpPath, workbuddyMcpPaths } from "../mcp/agent-config.ts";
 
 /**
@@ -143,7 +144,7 @@ function skillRoots(home: string): Array<{ source: string; dir: string }> {
     { source: "opencode", dir: join(home, ".config", "opencode", "skills") },
     { source: "openclaw", dir: join(home, ".openclaw", "skills") },
     { source: "openclaw", dir: join(home, ".openclaw", "workspace", "skills") },
-    { source: "hermes", dir: join(home, ".hermes", "skills") },
+    { source: "hermes", dir: join(getHermesHome(home), "skills") },
     { source: "gemini", dir: join(home, ".gemini", "skills") },
     {
       source: "antigravity",
@@ -857,9 +858,9 @@ const AGENT_PROBES: AgentProbe[] = [
   {
     id: "hermes",
     label: "Hermes Agent",
-    paths: (h) => [join(h, ".hermes", "config.yaml")],
+    paths: (h) => [join(getHermesHome(h), "config.yaml")],
     detect: (h) => {
-      const text = readText(join(h, ".hermes", "config.yaml"));
+      const text = readText(join(getHermesHome(h), "config.yaml"));
       if (!text) return { configured: false };
       let config: Record<string, unknown> | undefined;
       try {
@@ -1000,7 +1001,7 @@ function agentDetailFields(id: string, home: string): AgentField[] {
     pushField(out, "API", bailian?.api);
     pushField(out, "API Key", bailian?.apiKey, true);
   } else if (id === "hermes") {
-    const text = readText(join(home, ".hermes", "config.yaml"));
+    const text = readText(join(getHermesHome(home), "config.yaml"));
     let config: Record<string, unknown> | undefined;
     if (text) {
       try {

packages/commands/tests/config-agent-writers.test.ts

@@ -1,4 +1,12 @@
-import { mkdtempSync, rmSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from "fs";
+import {
+  mkdtempSync,
+  rmSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  readdirSync,
+  existsSync,
+} from "fs";
 import { tmpdir, homedir } from "os";
 import { join } from "path";
 import { afterEach, beforeEach, describe, expect, test } from "vite-plus/test";
@@ -500,6 +508,34 @@ describe("config agent writers", () => {
     });
   });
 
+  test("hermes 尊重 HERMES_HOME 环境变量，写入自定义 home 而非 ~/.hermes", () => {
+    const customHome = join(home, "custom-hermes-home");
+    mkdirSync(customHome, { recursive: true });
+    const prevHermesHome = process.env.HERMES_HOME;
+    process.env.HERMES_HOME = customHome;
+    try {
+      const summary = hermes.write({
+        baseUrl: OAI_URL,
+        apiKey: "sk-h",
+        model: "qwen3-coder-plus",
+      });
+      const expectedPath = join(customHome, "config.yaml");
+      // 写入位置与返回的 paths 都必须是 $HERMES_HOME/config.yaml
+      expect(summary.paths).toEqual([expectedPath]);
+      const config = yaml.parse(readFileSync(expectedPath, "utf8"));
+      expect(config.model).toMatchObject({
+        default: "qwen3-coder-plus",
+        provider: "custom",
+        base_url: OAI_URL,
+      });
+      // 不再写入硬编码的 ~/.hermes/config.yaml（否则 Hermes 读不到，静默失效）
+      expect(existsSync(join(home, ".hermes", "config.yaml"))).toBe(false);
+    } finally {
+      if (prevHermesHome === undefined) delete process.env.HERMES_HOME;
+      else process.env.HERMES_HOME = prevHermesHome;
+    }
+  });
+
   test("codex 写入 config.toml 与 auth.json（官方 env_key 结构，合并保留）", () => {
     // 预置 config.toml 无关顶层键与另一个 provider，验证非破坏性合并
     mkdirSync(join(home, ".codex"), { recursive: true });

packages/commands/tests/inventory.test.ts

@@ -240,3 +240,35 @@ test("listAgents 报告安装与已连接 bailian-cli 的状态", () => {
     expect(agents).toHaveLength(6);
   });
 });
+
+test("listAgents 通过 HERMES_HOME 探测 relocated 的 hermes 配置", () => {
+  const prevHermesHome = process.env.HERMES_HOME;
+  withHome((home) => {
+    // Hermes home relocated away from ~/.hermes via HERMES_HOME.
+    const hermesHome = join(home, "relocated-hermes");
+    process.env.HERMES_HOME = hermesHome;
+    write(
+      hermesHome,
+      "config.yaml",
+      [
+        "model:",
+        "  default: qwen3-max",
+        "  provider: custom",
+        "  base_url: https://dashscope.aliyuncs.com/compatible-mode/v1",
+        "  api_key: sk-test",
+      ].join("\n"),
+    );
+    try {
+      const byId = Object.fromEntries(listAgents(home).map((a) => [a.id, a]));
+      // Probe must follow HERMES_HOME, not the hard-coded ~/.hermes (issue #131).
+      expect(byId.hermes).toMatchObject({
+        installed: true,
+        configured: true,
+        model: "qwen3-max",
+      });
+    } finally {
+      if (prevHermesHome === undefined) delete process.env.HERMES_HOME;
+      else process.env.HERMES_HOME = prevHermesHome;
+    }
+  });
+});

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bailian-cli-core",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "Core SDK for bailian-cli. See https://www.npmjs.com/package/bailian-cli for usage.",
   "homepage": "https://bailian.console.aliyun.com/cli",
   "bugs": {

packages/core/src/skills/agents.ts

@@ -10,6 +10,7 @@ import {
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { getSkillsDir } from "./lock.ts";
+import { getHermesHome } from "../utils/agent-home.ts";
 
 /**
  * Agent fan-out: after a skill lands in the canonical dir (~/.bailian/skills/<name>),
@@ -164,7 +165,9 @@ export function getAgentTargets(): AgentTarget[] {
       detectDirs: [join(xdgConfig, "goose")],
     },
     fromBase("grok", "Grok Build", envBase(process.env.GROK_HOME, ".grok")),
-    fromBase("hermes", "Hermes Agent", envBase(process.env.HERMES_HOME, ".hermes")),
+    // Hermes resolves its home via HERMES_HOME → platform-native default; share the
+    // canonical resolver so skill fan-out, the config writer and the inventory probe agree.
+    fromBase("hermes", "Hermes Agent", getHermesHome(home)),
     simple("iflow-cli", "iFlow CLI", ".iflow"),
     simple("inference-sh", "inference.sh", ".inferencesh"),
     {