linco-connect 1.0.4 → 1.0.5

package/README.md

@@ -106,16 +106,51 @@ linco-connect init \
 
 ### Hermes Agent 初始化
 
-Hermes 是 HTTP 网关模式，除了 `init` 命令外，还需要启用 Hermes 的 `api_server` 平台：
+Hermes 使用本机 Hermes Gateway。默认情况下，`ddchat-connect` 会在第一次 Hermes 对话前自动检查 Gateway；如果未运行，会参考 Hermes Web UI 的方式自动补齐当前 Hermes profile 的 `platforms.api_server` 配置，生成本机 API key，并执行 `hermes gateway run --replace`。
 
-```bash
-hermes config set platforms.api_server.enabled true
-hermes config set platforms.api_server.host 127.0.0.1
-hermes config set platforms.api_server.port 8642
-hermes gateway restart
+最小配置只需要启用 Hermes：
+
+```json
+{
+  "agents": {
+    "hermes": {
+      "enabled": true
+    }
+  }
+}
+```
+
+如需覆盖默认值，可配置：
+
+```json
+{
+  "agents": {
+    "hermes": {
+      "enabled": true,
+      "gatewayUrl": "http://127.0.0.1:8642",
+      "autoStartGateway": true,
+      "hermesBin": "hermes",
+      "profile": "default"
+    }
+  }
+}
 ```
 
-可通过 `hermes gateway status` 确认 Gateway 是否运行，也可用 `linco-connect doctor` 检查 Hermes Gateway 连通性。
+如果已经有外部 Gateway，可关闭自动启动：
+
+```json
+{
+  "agents": {
+    "hermes": {
+      "enabled": true,
+      "gatewayUrl": "http://127.0.0.1:9000",
+      "autoStartGateway": false
+    }
+  }
+}
+```
+
+可通过 `linco-connect doctor` 检查 Hermes Gateway 状态；Gateway 未运行但自动启动开启时，发送 Hermes 消息会自动启动。
 
 #### 接口鉴权
 
@@ -138,7 +173,7 @@ hermes gateway restart
 export LINCO_HERMES_API_KEY=你的API_SERVER_KEY值
 ```
 
-如果连接时报 `401` 或 `fetch failed` 错误，请检查 Hermes 是否已启用 `api_server` 平台，以及是否正确配置了 API Key。
+如果连接时报 `401`，请检查 Hermes `api_server.key` 是否与 `LINCO_HERMES_API_KEY` / `agents.hermes.apiKey` 一致。自动启动会保留用户已有 key；如果 key 缺失，会生成新的本机 API key，当前和后续连接器进程会从 Hermes 配置中读取并使用。
 
 ## 配置文件
 
@@ -356,6 +391,11 @@ outbox 目录: .../outbox
 | `LINCO_CLAUDE_ENABLED` | 无配置文件时为启用 | 是否启用 Claude 连接器 |
 | `LINCO_CODEX_ENABLED` | `false` | 是否启用 Codex 连接器 |
 | `LINCO_HERMES_ENABLED` | `false` | 是否启用 Hermes 连接器 |
+| `LINCO_HERMES_GATEWAY_URL` | `http://127.0.0.1:8642` | Hermes Gateway 地址 |
+| `LINCO_HERMES_AUTO_START_GATEWAY` | `true` | Gateway 未运行时是否自动补齐配置并启动 |
+| `LINCO_HERMES_BIN` / `HERMES_BIN` | `hermes` | Hermes CLI 命令或路径 |
+| `LINCO_HERMES_PROFILE` | `default` | Hermes profile 名称 |
+| `LINCO_HERMES_HOME` / `HERMES_HOME` | 自动检测 | Hermes home 目录 |
 | `LINCO_HERMES_API_KEY` | 无 | Hermes Gateway 接口鉴权 Key |
 | `LINCO_CLAUDE_WS_URL` | `wss://chat.ddjf.info/socket/ai/claude` | Claude 端点覆盖 |
 | `LINCO_CODEX_WS_URL` | `wss://chat.ddjf.info/socket/ai/codex` | Codex 端点覆盖 |
@@ -418,50 +458,41 @@ outbox 目录: .../outbox
 
 ### Hermes 模式报 "fetch failed" 错误
 
-如果选择 Hermes Agent 后发送消息报错 **"Hermes 错误: fetch failed"**，说明 Hermes Gateway 的 HTTP API 服务未启动。
-
-`ddchat-connect` 通过 HTTP 请求 `http://127.0.0.1:8642/v1/runs` 与 Hermes Gateway 通信，需要确保 `api_server` 平台已启用。
-
-**修复方法**：
+默认情况下，`ddchat-connect` 会在第一次 Hermes 对话前自动检查并启动 Hermes Gateway。如果仍然报 **"Hermes 错误: fetch failed"**，通常是 Hermes CLI 不可用、Hermes 自身模型配置异常、端口被占用，或配置了外部 Gateway 但未运行。
 
-方式一：使用 Hermes 命令行配置（推荐）
+先运行：
 
 ```bash
-hermes config set platforms.api_server.enabled true
-hermes config set platforms.api_server.host 127.0.0.1
-hermes config set platforms.api_server.port 8642
-hermes gateway stop
-hermes gateway run
+linco-connect doctor
 ```
 
-方式二：手动编辑配置文件
+排查方向：
+
+- 确认终端可执行 `hermes`，或通过 `agents.hermes.hermesBin` / `LINCO_HERMES_BIN` 配置 Hermes 可执行文件路径。
+- 确认 Hermes 自身模型、账号或 provider 配置可用。
+- 确认 `gatewayUrl` 对应端口未被其他程序占用。
+- 如果使用 hermes-web-ui 已启动的 Gateway，确认 `gatewayUrl` 和 `profile` 与 web-ui 当前 Gateway 一致。
+- 如果返回 `401`，确认 `agents.hermes.apiKey` / `LINCO_HERMES_API_KEY` 与 Hermes `api_server.key` 一致。
 
-编辑 Hermes 配置文件 `~/.hermes/config.yaml`，确保 `platforms` 中包含 `api_server`：
+高级排障时可手动检查 Hermes profile 的 `config.yaml`，Gateway 配置应使用 `extra.host` / `extra.port`：
 
 ```yaml
 platforms:
-  linco:
-    enabled: true
   api_server:
     enabled: true
-    host: 127.0.0.1
-    port: 8642
-```
-
-然后重启 Hermes Gateway：
-
-```bash
-hermes gateway stop
-hermes gateway run
+    key: '<本机 API key>'
+    cors_origins: 'http://127.0.0.1:*'
+    extra:
+      host: 127.0.0.1
+      port: 8642
 ```
 
-确认端口已监听：
+确认 Gateway 健康：
 
 ```bash
-netstat -ano | grep 8642
+curl http://127.0.0.1:8642/health
 ```
 
-输出应包含 `127.0.0.1:8642` 处于 LISTENING 状态。
 
 ## 安全注意事项
 

package/bin/linco-connect.js

@@ -15,6 +15,7 @@ const {
   saveUserConfig,
 } = require('../src/config');
 const { ensureLocalToken, localUrlWithToken } = require('../src/localAuth');
+const { checkGatewayHealth, resolveHermesGatewayOptions } = require('../src/hermesGateway');
 const pkg = require('../package.json');
 
 const rootDir = path.resolve(__dirname, '..');
@@ -412,9 +413,18 @@ async function doctorCommand() {
   for (const [agentType, agent] of Object.entries(config.agents || {})) {
     checks.push([`${agentType} Agent`, true, agent.enabled ? `已启用 ${safeUrlForDisplay(agent.wsUrl)}` : `未启用 ${safeUrlForDisplay(agent.wsUrl)}`]);
     if (agentType === 'hermes') {
-      const gatewayUrl = agent.gatewayUrl || 'http://127.0.0.1:8642';
-      const reachable = await checkHermesGateway(gatewayUrl);
-      checks.push([`${agentType} Gateway`, reachable, gatewayUrl]);
+      const options = resolveHermesGatewayOptions(agent);
+      const health = await checkGatewayHealth(options.gatewayUrl, agent, { timeoutMs: 3000 });
+      if (health.ok) {
+        checks.push([`${agentType} Gateway`, true, `${options.gatewayUrl}/health`]);
+      } else if (agent.autoStartGateway !== false) {
+        const hasCli = !agent.enabled || (path.isAbsolute(options.hermesBin) ? fs.existsSync(options.hermesBin) : commandExists(options.hermesBin));
+        checks.push([`${agentType} Gateway`, true, `未运行，发送 Hermes 消息时将自动启动 ${options.gatewayUrl}`]);
+        checks.push([`${agentType} CLI`, hasCli, options.hermesBin]);
+        checks.push([`${agentType} Profile`, true, options.profileDir]);
+      } else {
+        checks.push([`${agentType} Gateway`, false, `未运行，且 autoStartGateway=false ${options.gatewayUrl}`]);
+      }
     } else {
       checks.push([`${agentType} CLI`, !agent.enabled || (path.isAbsolute(agent.bin) ? fs.existsSync(agent.bin) : commandExists(agent.bin)), agent.bin]);
     }
@@ -434,18 +444,6 @@ async function doctorCommand() {
   if (!ok) process.exitCode = 1;
 }
 
-async function checkHermesGateway(gatewayUrl) {
-  try {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), 3000);
-    const response = await fetch(gatewayUrl, { signal: controller.signal });
-    clearTimeout(timer);
-    return response.ok || response.status === 404;
-  } catch {
-    return false;
-  }
-}
-
 function safeUrlForDisplay(value) {
   try {
     const url = new URL(value);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linco-connect",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "自研 IM 桥接多 Agent 服务",
   "main": "server.js",
   "bin": {
@@ -20,6 +20,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "ws": "^8.16.0"
+    "ws": "^8.16.0",
+    "yaml": "^2.9.0"
   }
 }

package/src/agents/hermes.js

@@ -3,8 +3,7 @@ const { send, sendError, sendSystem } = require('../protocol');
 const { persistAgentSessionId, stopAgentProcess: stopSessionProcess, updateAgentSessionHistory, createAgentSessionEntry, saveSessionMetadata } = require('../session');
 const { getOutboxDir } = require('../outgoingAttachmentHandler');
 const { createTextStreamBuffer, appendTextStream, flushTextStream, resetTextStream } = require('../streamBuffer');
-
-const DEFAULT_GATEWAY_URL = 'http://127.0.0.1:8642';
+const { DEFAULT_GATEWAY_URL, ensureHermesGateway, normalizeGatewayUrl } = require('../hermesGateway');
 
 function extractText(input) {
   if (!Array.isArray(input)) return String(input || '');
@@ -47,11 +46,12 @@ async function runHermesTurn(input, ws, session, config) {
   resetHermesAssistantText(session);
 
   const agentConfig = config.agents?.hermes || {};
-  const gatewayUrl = normalizeGatewayUrl(agentConfig.gatewayUrl || agentConfig.baseUrl || DEFAULT_GATEWAY_URL);
   const hermesSessionId = ensureHermesSessionId(session);
   const inputWithOutbox = maybeAddOutboxHint(input, session, config);
 
   try {
+    const gatewayUrl = await ensureHermesGateway(agentConfig, config.logger);
+    session.hermesGatewayUrl = gatewayUrl;
     const run = await createRun(gatewayUrl, agentConfig, inputWithOutbox, hermesSessionId);
     if (!run?.run_id) throw new Error('Hermes Gateway 未返回 run_id');
     session.hermesRunId = run.run_id;
@@ -219,6 +219,7 @@ function finishTurn(ws, session, config, options = {}) {
   }
   session.hermesAbortController = null;
   session.hermesRunId = null;
+  session.hermesGatewayUrl = null;
   session.isTurnActive = false;
   session.currentInputForNoOutput = null;
   session.pendingPermission = null;
@@ -362,7 +363,7 @@ async function resolvePendingPermission(approved, ws, session, config) {
   if (!pending || pending.provider !== 'hermes') return false;
 
   const agentConfig = config.agents?.hermes || {};
-  const gatewayUrl = normalizeGatewayUrl(agentConfig.gatewayUrl || agentConfig.baseUrl || DEFAULT_GATEWAY_URL);
+  const gatewayUrl = session.hermesGatewayUrl || normalizeGatewayUrl(agentConfig.gatewayUrl || agentConfig.baseUrl || DEFAULT_GATEWAY_URL);
   const runId = pending.runId || session.hermesRunId;
   session.pendingPermission = null;
 
@@ -387,7 +388,7 @@ function stop(session, options = {}) {
     } catch {}
   }
   if (runId) {
-    const gatewayUrl = normalizeGatewayUrl(agentConfig.gatewayUrl || agentConfig.baseUrl || DEFAULT_GATEWAY_URL);
+    const gatewayUrl = session.hermesGatewayUrl || normalizeGatewayUrl(agentConfig.gatewayUrl || agentConfig.baseUrl || DEFAULT_GATEWAY_URL);
     fetchJson(`${gatewayUrl}/v1/runs/${encodeURIComponent(runId)}/stop`, agentConfig, { method: 'POST' }).catch(() => {});
   }
   session.hermesAbortController = null;
@@ -424,10 +425,6 @@ function drainQueue(ws, session, config) {
   setImmediate(() => execute(next, ws, session, config));
 }
 
-function normalizeGatewayUrl(value) {
-  return String(value || DEFAULT_GATEWAY_URL).replace(/\/+$/, '');
-}
-
 function buildHeaders(agentConfig) {
   const headers = { Accept: 'application/json' };
   if (agentConfig.apiKey) headers.Authorization = `Bearer ${agentConfig.apiKey}`;

package/src/config.js

@@ -267,6 +267,9 @@ function agentConfig(userConfig, imConfig, agentType, defaults = {}) {
   const instructionsEnv = `LINCO_${agentType.toUpperCase()}_INSTRUCTIONS`;
   const appIdEnv = `LINCO_${agentType.toUpperCase()}_APP_ID`;
   const appSecretEnv = `LINCO_${agentType.toUpperCase()}_APP_SECRET`;
+  const hermesBin = agentType === 'hermes'
+    ? resolveCommand(stringFromEnv('LINCO_HERMES_BIN', process.env.HERMES_BIN || configured.hermesBin || configured.bin || defaults.hermesBin || defaults.bin || 'hermes'))
+    : undefined;
 
   return {
     type: agentType,
@@ -275,9 +278,16 @@ function agentConfig(userConfig, imConfig, agentType, defaults = {}) {
     wsUrl: stringFromEnv(wsEnv, configured.wsUrl || defaults.wsUrl),
     mode: stringFromEnv(`LINCO_${agentType.toUpperCase()}_MODE`, configured.mode || defaults.mode),
     model: stringFromEnv(`LINCO_${agentType.toUpperCase()}_MODEL`, configured.model || defaults.model),
-    gatewayUrl: stringFromEnv(gatewayEnv, configured.gatewayUrl || defaults.gatewayUrl),
+    gatewayUrl: stringFromEnv(gatewayEnv, configured.gatewayUrl || configured.baseUrl || defaults.gatewayUrl),
     apiKey: stringFromEnv(apiKeyEnv, configured.apiKey || defaults.apiKey),
     instructions: stringFromEnv(instructionsEnv, configured.instructions || defaults.instructions),
+    ...(agentType === 'hermes' ? {
+      autoStartGateway: booleanFromEnv('LINCO_HERMES_AUTO_START_GATEWAY', configured.autoStartGateway ?? defaults.autoStartGateway ?? true),
+      hermesBin,
+      profile: stringFromEnv('LINCO_HERMES_PROFILE', configured.profile || defaults.profile || 'default'),
+      hermesHome: stringFromEnv('LINCO_HERMES_HOME', process.env.HERMES_HOME || configured.hermesHome || defaults.hermesHome),
+      gatewayStartTimeoutMs: numberFromEnv('LINCO_HERMES_GATEWAY_START_TIMEOUT_MS', configured.gatewayStartTimeoutMs || defaults.gatewayStartTimeoutMs || 15000),
+    } : {}),
     appId: stringFromEnv(appIdEnv, channelAccount?.appId || configured.appId),
     appSecret: stringFromEnv(appSecretEnv, channelAccount?.appSecret || configured.appSecret),
   };
@@ -320,6 +330,9 @@ function loadConfig(rootDir) {
     hermes: agentConfig(userConfig, imConfig, 'hermes', {
       wsUrl: hermesAccountConfig.wsUrl || DEFAULT_AGENT_WS_URLS.hermes,
       gatewayUrl: 'http://127.0.0.1:8642',
+      autoStartGateway: true,
+      hermesBin: 'hermes',
+      profile: 'default',
     }),
   };
   const accountAgent = agents[accountAgentType];

package/src/hermesGateway.js

@@ -0,0 +1,342 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { spawn } = require('child_process');
+const YAML = require('yaml');
+
+const DEFAULT_GATEWAY_URL = 'http://127.0.0.1:8642';
+const DEFAULT_GATEWAY_HOST = '127.0.0.1';
+const DEFAULT_GATEWAY_PORT = 8642;
+const DEFAULT_START_TIMEOUT_MS = 30000;
+const DEFAULT_HEALTH_TIMEOUT_MS = 1500;
+const DEFAULT_POLL_INTERVAL_MS = 500;
+
+const bootstrapPromises = new Map();
+const ownedGateways = new Map();
+let cleanupRegistered = false;
+
+function normalizeGatewayUrl(value) {
+  const raw = String(value || DEFAULT_GATEWAY_URL).trim() || DEFAULT_GATEWAY_URL;
+  let parsed;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw new Error(`Hermes Gateway 地址无效：${raw}`);
+  }
+  if (!['http:', 'https:'].includes(parsed.protocol)) {
+    throw new Error(`Hermes Gateway 地址无效：${raw}`);
+  }
+  return parsed.toString().replace(/\/+$/, '');
+}
+
+function resolveHermesGatewayOptions(agentConfig = {}) {
+  const gatewayUrl = normalizeGatewayUrl(agentConfig.gatewayUrl || agentConfig.baseUrl || DEFAULT_GATEWAY_URL);
+  const url = new URL(gatewayUrl);
+  const host = url.hostname || DEFAULT_GATEWAY_HOST;
+  const port = Number(url.port || (url.protocol === 'https:' ? 443 : DEFAULT_GATEWAY_PORT));
+  const profile = agentConfig.profile || process.env.LINCO_HERMES_PROFILE || 'default';
+  const profileDir = resolveHermesProfileDir({ ...agentConfig, profile });
+  const hermesBin = resolveHermesBin(agentConfig);
+  const autoStartGateway = agentConfig.autoStartGateway !== false;
+  const startTimeoutMs = Number(agentConfig.gatewayStartTimeoutMs) > 0
+    ? Number(agentConfig.gatewayStartTimeoutMs)
+    : DEFAULT_START_TIMEOUT_MS;
+
+  return { gatewayUrl, host, port, profile, profileDir, hermesBin, autoStartGateway, startTimeoutMs };
+}
+
+function resolveHermesBin(agentConfig = {}) {
+  return process.env.LINCO_HERMES_BIN
+    || process.env.HERMES_BIN
+    || agentConfig.hermesBin
+    || agentConfig.bin
+    || 'hermes';
+}
+
+function resolveHermesProfileDir(agentConfig = {}) {
+  const baseHome = path.resolve(
+    agentConfig.hermesHome
+    || process.env.LINCO_HERMES_HOME
+    || process.env.HERMES_HOME
+    || defaultHermesHome()
+  );
+  const profile = agentConfig.profile || process.env.LINCO_HERMES_PROFILE || 'default';
+  if (!profile || profile === 'default') return baseHome;
+  return path.join(baseHome, 'profiles', profile);
+}
+
+function defaultHermesHome() {
+  return path.join(os.homedir(), '.hermes');
+}
+
+async function ensureHermesGateway(agentConfig = {}, logger) {
+  const options = resolveHermesGatewayOptions(agentConfig);
+  let health = await checkGatewayHealth(options.gatewayUrl, agentConfig);
+  if (health.authFailed && !agentConfig.apiKey) {
+    const configKey = readApiServerKey(options.profileDir);
+    if (configKey) {
+      agentConfig.apiKey = configKey;
+      health = await checkGatewayHealth(options.gatewayUrl, agentConfig);
+    }
+  }
+  if (health.ok) return options.gatewayUrl;
+  if (health.authFailed) throw authError();
+  if (!options.autoStartGateway) {
+    throw new Error(`Hermes Gateway 未运行：${options.gatewayUrl}。当前 autoStartGateway=false，请启动外部 Gateway 或启用自动启动。`);
+  }
+  if (!isLoopbackHost(options.host)) {
+    throw new Error(`Hermes Gateway 自动启动仅支持本机地址：${options.gatewayUrl}。请使用 127.0.0.1/localhost，或设置 autoStartGateway=false 使用外部 Gateway。`);
+  }
+
+  const key = `${options.gatewayUrl}:${options.profileDir}`;
+  if (!bootstrapPromises.has(key)) {
+    bootstrapPromises.set(key, bootstrapGateway(options, agentConfig, logger).finally(() => {
+      bootstrapPromises.delete(key);
+    }));
+  }
+  await bootstrapPromises.get(key);
+  return options.gatewayUrl;
+}
+
+async function bootstrapGateway(options, agentConfig, logger) {
+  logger?.info?.('hermes gateway bootstrap starting', {
+    gatewayUrl: options.gatewayUrl,
+    profile: options.profile,
+    profileDir: options.profileDir,
+  });
+
+  const apiKey = ensureApiServerConfig({ profileDir: options.profileDir, host: options.host, port: options.port, apiKey: agentConfig.apiKey });
+  const gatewayAgentConfig = { ...agentConfig, apiKey };
+  if (!agentConfig.apiKey) agentConfig.apiKey = apiKey;
+  cleanStaleGatewayLock(options.profileDir, logger);
+  const child = startGateway({ hermesBin: options.hermesBin, profileDir: options.profileDir, gatewayUrl: options.gatewayUrl, logger });
+  await waitForGatewayReady(options.gatewayUrl, gatewayAgentConfig, {
+    timeoutMs: options.startTimeoutMs,
+    child,
+  });
+  logger?.info?.('hermes gateway bootstrap ready', { gatewayUrl: options.gatewayUrl });
+}
+
+async function checkGatewayHealth(gatewayUrl, agentConfig = {}, options = {}) {
+  const normalized = normalizeGatewayUrl(gatewayUrl);
+  const timeoutMs = options.timeoutMs || DEFAULT_HEALTH_TIMEOUT_MS;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(`${normalized}/health`, {
+      method: 'GET',
+      headers: buildHealthHeaders(agentConfig),
+      signal: controller.signal,
+    });
+    return {
+      ok: response.ok,
+      status: response.status,
+      authFailed: response.status === 401,
+      error: null,
+    };
+  } catch (err) {
+    return { ok: false, status: null, authFailed: false, error: err };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function buildHealthHeaders(agentConfig) {
+  const headers = { Accept: 'application/json' };
+  if (agentConfig.apiKey) headers.Authorization = `Bearer ${agentConfig.apiKey}`;
+  return headers;
+}
+
+function ensureApiServerConfig({ profileDir, host, port, apiKey }) {
+  fs.mkdirSync(profileDir, { recursive: true });
+  const configFile = path.join(profileDir, 'config.yaml');
+  let cfg = {};
+  if (fs.existsSync(configFile)) {
+    try {
+      cfg = YAML.parse(fs.readFileSync(configFile, 'utf8')) || {};
+    } catch (err) {
+      throw new Error(`无法读取 Hermes 配置文件：${configFile}。${err.message}`);
+    }
+  }
+
+  if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg)) cfg = {};
+  cfg.platforms = objectValue(cfg.platforms);
+  cfg.platforms.api_server = objectValue(cfg.platforms.api_server);
+  const apiServer = cfg.platforms.api_server;
+  apiServer.extra = objectValue(apiServer.extra);
+
+  apiServer.enabled = true;
+  if (apiServer.key == null || apiServer.key === '') apiServer.key = apiKey || crypto.randomBytes(24).toString('hex');
+  apiServer.cors_origins = apiServer.cors_origins || 'http://127.0.0.1:*';
+  apiServer.extra.host = host;
+  apiServer.extra.port = port;
+  delete apiServer.host;
+  delete apiServer.port;
+
+  try {
+    fs.writeFileSync(configFile, YAML.stringify(cfg, { lineWidth: 0 }));
+  } catch (err) {
+    throw new Error(`无法写入 Hermes 配置文件：${configFile}。请检查文件权限。${err.message}`);
+  }
+  return apiServer.key;
+}
+
+function readApiServerKey(profileDir) {
+  const configFile = path.join(profileDir, 'config.yaml');
+  if (!fs.existsSync(configFile)) return '';
+  try {
+    const cfg = YAML.parse(fs.readFileSync(configFile, 'utf8')) || {};
+    return cfg.platforms?.api_server?.key || '';
+  } catch {
+    return '';
+  }
+}
+
+function objectValue(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+function cleanStaleGatewayLock(profileDir, logger) {
+  if (process.platform !== 'win32') return;
+  const lockFile = path.join(profileDir, 'gateway.lock');
+  if (!fs.existsSync(lockFile)) return;
+  try {
+    const raw = fs.readFileSync(lockFile, 'utf8');
+    const lock = JSON.parse(raw || '{}');
+    const pid = Number(lock.pid);
+    if (pid && isProcessAlive(pid)) return;
+    fs.unlinkSync(lockFile);
+  } catch (err) {
+    logger?.warn?.('failed to clean stale hermes gateway lock', { lockFile, error: err.message });
+  }
+}
+
+function startGateway({ hermesBin, profileDir, gatewayUrl, logger }) {
+  let child;
+  try {
+    child = spawn(hermesBin, ['gateway', 'run', '--replace'], {
+      stdio: 'ignore',
+      windowsHide: true,
+      env: {
+        ...process.env,
+        HERMES_HOME: profileDir,
+      },
+    });
+  } catch (err) {
+    if (err.code === 'ENOENT') throw hermesBinError(hermesBin);
+    throw err;
+  }
+
+  if (!child.pid) throw hermesBinError(hermesBin);
+  const record = { child, gatewayUrl, profileDir, ready: false, earlyExit: null };
+  ownedGateways.set(`${gatewayUrl}:${profileDir}`, record);
+  registerCleanup();
+
+  child.once('error', err => {
+    record.earlyExit = err;
+    if (err.code === 'ENOENT') {
+      logger?.error?.('hermes gateway command not found', { hermesBin });
+    } else {
+      logger?.error?.('hermes gateway process error', { error: err.message });
+    }
+  });
+  child.once('exit', (code, signal) => {
+    if (!record.ready) record.earlyExit = new Error(`exit ${code ?? signal ?? 'unknown'}`);
+    logger?.info?.('hermes gateway process exited', { code, signal });
+  });
+
+  return child;
+}
+
+async function waitForGatewayReady(gatewayUrl, agentConfig = {}, options = {}) {
+  const timeoutMs = options.timeoutMs || DEFAULT_START_TIMEOUT_MS;
+  const pollIntervalMs = options.pollIntervalMs || DEFAULT_POLL_INTERVAL_MS;
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const ownedRecord = getOwnedGatewayRecord(gatewayUrl);
+    if (ownedRecord?.earlyExit) {
+      if (ownedRecord.earlyExit.code === 'ENOENT') throw hermesBinError(options.child?.spawnfile || 'hermes');
+      throw new Error('Hermes Gateway 启动失败：hermes gateway run --replace 进程提前退出。');
+    }
+    if (options.child?.exitCode != null || options.child?.signalCode) {
+      throw new Error('Hermes Gateway 启动失败：hermes gateway run --replace 进程提前退出。');
+    }
+    const health = await checkGatewayHealth(gatewayUrl, agentConfig, { timeoutMs: options.healthTimeoutMs || DEFAULT_HEALTH_TIMEOUT_MS });
+    if (health.ok) {
+      markOwnedGatewayReady(gatewayUrl);
+      return;
+    }
+    if (health.authFailed) throw authError();
+    await delay(pollIntervalMs);
+  }
+  throw new Error(`Hermes Gateway 启动超时：${normalizeGatewayUrl(gatewayUrl)}/health 未就绪。已尝试启用 api_server 并执行 hermes gateway run --replace，请检查 Hermes 配置、模型配置或端口占用。`);
+}
+
+function getOwnedGatewayRecord(gatewayUrl) {
+  const normalized = normalizeGatewayUrl(gatewayUrl);
+  for (const record of ownedGateways.values()) {
+    if (record.gatewayUrl === normalized) return record;
+  }
+  return null;
+}
+
+function markOwnedGatewayReady(gatewayUrl) {
+  const record = getOwnedGatewayRecord(gatewayUrl);
+  if (record) record.ready = true;
+}
+
+function hermesBinError(hermesBin) {
+  return new Error(`未找到 ${hermesBin} 命令。请先安装 Hermes Agent，或在 agents.hermes.hermesBin / LINCO_HERMES_BIN 中配置 Hermes 可执行文件路径。`);
+}
+
+function isLoopbackHost(host) {
+  const value = String(host || '').toLowerCase();
+  return value === 'localhost' || value === '127.0.0.1' || value === '::1' || value === '[::1]';
+}
+
+function authError() {
+  return new Error('Hermes Gateway 返回 401。请检查 agents.hermes.apiKey / LINCO_HERMES_API_KEY 是否与 Hermes api_server.key 一致。');
+}
+
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function registerCleanup() {
+  if (cleanupRegistered) return;
+  cleanupRegistered = true;
+  const cleanup = () => {
+    for (const record of ownedGateways.values()) {
+      try {
+        if (record.child && !record.child.killed) record.child.kill();
+      } catch {}
+    }
+  };
+  process.once('exit', cleanup);
+  for (const signal of ['SIGINT', 'SIGTERM']) {
+    process.once(signal, () => {
+      cleanup();
+      process.kill(process.pid, signal);
+    });
+  }
+}
+
+function delay(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+module.exports = {
+  DEFAULT_GATEWAY_URL,
+  checkGatewayHealth,
+  ensureApiServerConfig,
+  ensureHermesGateway,
+  normalizeGatewayUrl,
+  resolveHermesGatewayOptions,
+  resolveHermesProfileDir,
+};

package/src/serverApp.js

@@ -5,6 +5,18 @@ const { startImConnectors } = require('./imConnector');
 const { createLogger } = require('./logger');
 const { attachWebSocketServer } = require('./wsServer');
 
+async function prewarmHermesGateway(config) {
+  const hermes = config.agents?.hermes;
+  if (!hermes?.enabled || hermes.autoStartGateway === false) return;
+  try {
+    const { ensureHermesGateway } = require('./hermesGateway');
+    await ensureHermesGateway(hermes, config.logger);
+    config.logger?.info('hermes gateway pre-warmed', { gatewayUrl: hermes.gatewayUrl || 'http://127.0.0.1:8642' });
+  } catch (err) {
+    config.logger?.warn('hermes gateway pre-warm failed', { error: err.message });
+  }
+}
+
 function startServer(rootDir, options = {}) {
   const config = options.config || loadConfig(rootDir);
   config.logger = options.logger || config.logger || createLogger(config);
@@ -52,6 +64,7 @@ function startServer(rootDir, options = {}) {
         const enabledAgents = Object.entries(config.agents || {}).filter(([, agent]) => agent.enabled).map(([type]) => type).join(', ');
         console.log(`   远端 IM: 已启用 (${config.im.channel}/${config.im.account}; agents: ${enabledAgents || 'none'})`);
       }
+      prewarmHermesGateway(config);
       options.onListening?.(server, config);
     });
 
@@ -77,6 +90,7 @@ function startServer(rootDir, options = {}) {
     }
     console.log('');
     console.log('💡 如需开启本地测试页，请运行 linco-connect start --local-im');
+    prewarmHermesGateway(config);
     options.onListening?.(null, config);
     return null;
   }