linco-connect 1.0.2 → 1.0.4

package/README.md

@@ -104,6 +104,42 @@ linco-connect init \
 - 初始化不会询问或写入 `wsUrl`。
 - 多次执行 `init` 并传入不同 `--agent` 可在同一账号下启用多个 Agent。
 
+### Hermes Agent 初始化
+
+Hermes 是 HTTP 网关模式，除了 `init` 命令外，还需要启用 Hermes 的 `api_server` 平台：
+
+```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 gateway status` 确认 Gateway 是否运行，也可用 `linco-connect doctor` 检查 Hermes Gateway 连通性。
+
+#### 接口鉴权
+
+如果 Hermes 的 `api_server` 配置了 `key`（接口鉴权），需要在 `~/.linco/config.json` 中添加对应的 API Key：
+
+```json
+{
+  "agents": {
+    "hermes": {
+      "enabled": true,
+      "apiKey": "你的API_SERVER_KEY值"
+    }
+  }
+}
+```
+
+或设置环境变量：
+
+```bash
+export LINCO_HERMES_API_KEY=你的API_SERVER_KEY值
+```
+
+如果连接时报 `401` 或 `fetch failed` 错误，请检查 Hermes 是否已启用 `api_server` 平台，以及是否正确配置了 API Key。
+
 ## 配置文件
 
 配置统一保存在用户主目录下的 `.linco` 根目录：
@@ -319,6 +355,8 @@ outbox 目录: .../outbox
 | `CODEX_BIN` | `codex` | Codex CLI 命令或路径 |
 | `LINCO_CLAUDE_ENABLED` | 无配置文件时为启用 | 是否启用 Claude 连接器 |
 | `LINCO_CODEX_ENABLED` | `false` | 是否启用 Codex 连接器 |
+| `LINCO_HERMES_ENABLED` | `false` | 是否启用 Hermes 连接器 |
+| `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 端点覆盖 |
 | `LINCO_LOCAL_AGENT` | `claude` | 本地测试页默认使用的 Agent |
@@ -376,6 +414,55 @@ outbox 目录: .../outbox
 - `outbox/` 用于 Agent 生成文件并自动下发给前端。
 - Codex 默认使用系统安装时的认证和配置，不会创建项目托管的 `codex-home`。
 
+## 故障排查
+
+### 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` 平台已启用。
+
+**修复方法**：
+
+方式一：使用 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
+```
+
+方式二：手动编辑配置文件
+
+编辑 Hermes 配置文件 `~/.hermes/config.yaml`，确保 `platforms` 中包含 `api_server`：
+
+```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
+```
+
+确认端口已监听：
+
+```bash
+netstat -ano | grep 8642
+```
+
+输出应包含 `127.0.0.1:8642` 处于 LISTENING 状态。
+
 ## 安全注意事项
 
 - 默认只监听 `127.0.0.1`，不建议直接暴露到公网。

package/bin/linco-connect.js

@@ -50,7 +50,7 @@ async function main() {
       await stopCommand();
       break;
     case 'doctor':
-      doctorCommand();
+      await doctorCommand();
       break;
     default:
       throw new Error(`未知命令: ${command}\n运行 linco-connect --help 查看用法。`);
@@ -105,9 +105,12 @@ function initCommand(options) {
   const agentType = options.agent ? options.agent.trim().toLowerCase() : null;
 
   if (agentType) {
-    const agentBin = resolveCommand(agentType);
-    if (!agentBin || !commandExists(agentType)) {
-      throw new Error(`未检测到 ${agentType} CLI，请先安装 ${agentType} 再初始化。`);
+    // Hermes is an HTTP gateway service, not a CLI binary
+    if (agentType !== 'hermes') {
+      const agentBin = resolveCommand(agentType);
+      if (!agentBin || !commandExists(agentType)) {
+        throw new Error(`未检测到 ${agentType} CLI，请先安装 ${agentType} 再初始化。`);
+      }
     }
   }
 
@@ -393,7 +396,7 @@ function waitForDaemonStart(pid, pidFile, timeoutMs) {
   });
 }
 
-function doctorCommand() {
+async function doctorCommand() {
   const checks = [];
   const config = loadConfig(rootDir);
   ensureLocalToken(config);
@@ -408,7 +411,13 @@ function doctorCommand() {
   checks.push(['本地测试 token', Boolean(config.localWeb?.token), '已生成']);
   for (const [agentType, agent] of Object.entries(config.agents || {})) {
     checks.push([`${agentType} Agent`, true, agent.enabled ? `已启用 ${safeUrlForDisplay(agent.wsUrl)}` : `未启用 ${safeUrlForDisplay(agent.wsUrl)}`]);
-    checks.push([`${agentType} CLI`, !agent.enabled || (path.isAbsolute(agent.bin) ? fs.existsSync(agent.bin) : commandExists(agent.bin)), agent.bin]);
+    if (agentType === 'hermes') {
+      const gatewayUrl = agent.gatewayUrl || 'http://127.0.0.1:8642';
+      const reachable = await checkHermesGateway(gatewayUrl);
+      checks.push([`${agentType} Gateway`, reachable, gatewayUrl]);
+    } else {
+      checks.push([`${agentType} CLI`, !agent.enabled || (path.isAbsolute(agent.bin) ? fs.existsSync(agent.bin) : commandExists(agent.bin)), agent.bin]);
+    }
   }
   checks.push(['Git Bash', process.platform !== 'win32' || Boolean(findGitBash(readUserConfig(config.configFile))), process.platform === 'win32' ? (config.gitBashEnv || '未找到') : '非 Windows 不需要']);
   checks.push(['Linco Home', canEnsureWritable(config.lincoHome), config.lincoHome]);
@@ -425,6 +434,18 @@ 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);
@@ -455,7 +476,7 @@ function printHelp() {
 
 说明:
   init    初始化本地配置，不需要填写 wsUrl
-  start   启动本机 Agent 连接器和本地测试页
+  start   启动本机 Agent 连接器（本地测试页需加 --local-im 开启）
   stop    停止后台运行的 Linco Connect
   doctor  检查本地运行环境
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linco-connect",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "自研 IM 桥接多 Agent 服务",
   "main": "server.js",
   "bin": {

package/public/index.html

@@ -576,6 +576,7 @@
       <select id="agent-select" title="选择本地测试 Agent">
         <option value="claude">Claude Code</option>
         <option value="codex">Codex</option>
+        <option value="hermes">Hermes</option>
       </select>
     </div>
     <div id="messages"></div>
@@ -930,12 +931,21 @@
     }
 
     function addPermissionConfirm(data) {
+      const requestId = data.requestId || '';
+      const selector = requestId ? `.permission-confirm[data-request-id="${cssEscape(requestId)}"]` : '';
+      const existing = selector ? messagesEl.querySelector(selector) : null;
+      if (existing) {
+        scrollToBottom();
+        return;
+      }
+
       const container = document.createElement('div');
       container.className = 'danger-confirm permission-confirm';
+      container.dataset.requestId = requestId;
 
       const title = document.createElement('div');
       title.className = 'danger-text';
-      title.textContent = `Claude 请求使用工具：${data.toolName || 'tool'}`;
+      title.textContent = `${agentLabel(currentAgentType)} 请求使用工具：${data.toolName || 'tool'}`;
       container.appendChild(title);
 
       if (data.input) {
@@ -1170,11 +1180,11 @@
 
     function normalizeAgentType(value) {
       const type = String(value || 'claude').trim().toLowerCase();
-      return ['claude', 'codex'].includes(type) ? type : 'claude';
+      return ['claude', 'codex', 'hermes'].includes(type) ? type : 'claude';
     }
 
     function agentLabel(type) {
-      return type === 'codex' ? 'Codex' : 'Claude Code';
+      return type === 'codex' ? 'Codex' : type === 'hermes' ? 'Hermes' : 'Claude Code';
     }
 
     function setAgentSelection(agentType, options = {}) {

package/src/agentRunner.js

@@ -1,9 +1,11 @@
 const claude = require('./agents/claude');
 const codex = require('./agents/codex');
+const hermes = require('./agents/hermes');
 
 const providers = {
   claude,
   codex,
+  hermes,
 };
 
 function providerFor(session) {

package/src/agents/codex.js

@@ -319,12 +319,27 @@ function handleServerRequest(message, session) {
 
   // File change approval — auto-approve but notify user
   if (method === 'item/fileChange/requestApproval') {
+    const toolId = String(message.id);
+    const input = summarizeCodexParams(params);
     session._log?.info('codex auto-approving file change');
+    if (ws) {
+      send(ws, 'tool_call', {
+        id: toolId,
+        name: 'fileChange',
+        input,
+      });
+    }
     sendJsonRpc(session.codexAppServer, {
       jsonrpc: '2.0',
       id: message.id,
       result: { decision: 'accept' },
     });
+    if (ws) {
+      send(ws, 'tool_result', {
+        id: toolId,
+        output: 'approved',
+      });
+    }
     return;
   }
 
@@ -333,8 +348,11 @@ function handleServerRequest(message, session) {
     const cmd = params.command || params.tool || '';
     session._log?.info('codex command execution approval requested', { method, command: cmd });
 
+    if (session.pendingPermission?.requestId === String(message.id)) return;
+
     session.pendingPermission = {
       provider: 'codex',
+      requestId: String(message.id),
       toolName: 'exec',
       input: cmd,
       _codexMethod: method,
@@ -342,11 +360,6 @@ function handleServerRequest(message, session) {
     };
 
     if (ws) {
-      send(ws, 'tool_call', {
-        id: String(message.id),
-        name: 'exec',
-        input: cmd,
-      });
       send(ws, 'permission_request', {
         requestId: String(message.id),
         toolName: 'exec',
@@ -369,12 +382,27 @@ function handleServerRequest(message, session) {
 
   // Apply patch approval — auto-approve
   if (method === 'applyPatchApproval') {
+    const toolId = String(message.id);
+    const input = summarizeCodexParams(params);
     session._log?.info('codex auto-approving patch');
+    if (ws) {
+      send(ws, 'tool_call', {
+        id: toolId,
+        name: 'applyPatch',
+        input,
+      });
+    }
     sendJsonRpc(session.codexAppServer, {
       jsonrpc: '2.0',
       id: message.id,
       result: { decision: 'approved' },
     });
+    if (ws) {
+      send(ws, 'tool_result', {
+        id: toolId,
+        output: 'approved',
+      });
+    }
     return;
   }
 
@@ -477,6 +505,25 @@ function handleAppServerMessage(message, session) {
   }
 
   if (method === 'item/completed') {
+    const itemType = params.item?.type || '';
+    session._log?.info('codex item completed', { itemType, item: summarizeCodexItemForLog(params.item) });
+    if (itemType === 'toolCall' || itemType === 'commandExecution' || itemType === 'webSearch') {
+      const itemId = params.item?.id || params.itemId || '';
+      if (itemType === 'webSearch' && params.item?.query) {
+        send(ws, 'tool_call', {
+          id: itemId,
+          name: 'webSearch',
+          input: params.item.query,
+        });
+      }
+      const output = params.item?.output || params.item?.result || params.item?.results || params.output || params.result || '';
+      send(ws, 'tool_result', {
+        id: itemId,
+        output: typeof output === 'string' ? output : JSON.stringify(output).slice(0, 1000),
+      });
+      return;
+    }
+
     // final content fallback if no deltas were emitted
     const text = extractFinalText(params);
     if (text && !session.sawPartialAssistantText) {
@@ -549,10 +596,16 @@ function handleAppServerMessage(message, session) {
 
   if (method === 'item/started') {
     const itemType = params.item?.type || '';
-    session._log?.info('codex item started', { itemType });
-    if (itemType === 'toolCall' || itemType === 'commandExecution') {
-      const toolName = params.item?.name || params.item?.tool || params.item?.command || '';
-      const toolInput = params.item?.input || params.item?.arguments || {};
+    session._log?.info('codex item started', { itemType, item: summarizeCodexItemForLog(params.item) });
+    if (itemType === 'toolCall' || itemType === 'commandExecution' || itemType === 'webSearch') {
+      const isCommand = itemType === 'commandExecution';
+      const isWebSearch = itemType === 'webSearch';
+      const toolName = isCommand ? 'exec' : isWebSearch ? 'webSearch' : (params.item?.name || params.item?.tool || '');
+      const toolInput = isCommand
+        ? (params.item?.command || '')
+        : isWebSearch
+          ? (params.item?.query || params.item?.input || params.item?.arguments || {})
+          : (params.item?.input || params.item?.arguments || {});
       const itemId = params.item?.id || params.itemId || '';
       if (toolName) {
         send(ws, 'tool_call', {
@@ -595,6 +648,30 @@ function extractFinalText(params) {
   return '';
 }
 
+function summarizeCodexItemForLog(item) {
+  if (!item || typeof item !== 'object') return {};
+  const summary = {};
+  for (const key of Object.keys(item)) {
+    const value = item[key];
+    if (typeof value === 'string') {
+      summary[key] = value.slice(0, 200);
+    } else if (Array.isArray(value)) {
+      summary[key] = `[array:${value.length}]`;
+    } else if (value && typeof value === 'object') {
+      summary[key] = `[object:${Object.keys(value).slice(0, 10).join(',')}]`;
+    } else {
+      summary[key] = value;
+    }
+  }
+  return summary;
+}
+
+function summarizeCodexParams(params) {
+  if (!params || typeof params !== 'object') return '';
+  const input = params.path || params.file || params.filePath || params.command || params.patch || params.diff || params.input || params;
+  return typeof input === 'string' ? input.slice(0, 1000) : JSON.stringify(input).slice(0, 1000);
+}
+
 function buildCodexInput(input, workspace) {
   if (Array.isArray(input)) {
     const result = [];

package/src/agents/hermes.js

@@ -0,0 +1,470 @@
+const { isDangerousCommand } = require('../danger');
+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';
+
+function extractText(input) {
+  if (!Array.isArray(input)) return String(input || '');
+  return input
+    .filter(block => block?.type === 'text')
+    .map(block => block.text || '')
+    .join('\n');
+}
+
+function execute(input, ws, session, config) {
+  const textForCheck = stringifyInput(input);
+  if (isDangerousCommand(textForCheck)) {
+    const preview = textForCheck.slice(0, 200);
+    session.pendingDanger = { input };
+    send(ws, 'danger_warning', {
+      text: `⚠️ 检测到可能的危险操作，请确认是否继续执行：\n\n"${preview}${textForCheck.length > 200 ? '...' : ''}"`,
+    });
+    return;
+  }
+
+  if (session.isTurnActive) {
+    if (session.messageQueue.length >= config.maxMessageQueue) {
+      sendError(ws, '消息队列已满，请稍后再试');
+      return;
+    }
+    session.messageQueue.push(input);
+    sendSystem(ws, `Hermes 正在处理上一条消息，已加入队列（${session.messageQueue.length}）`);
+    return;
+  }
+
+  runHermesTurn(input, ws, session, config);
+}
+
+async function runHermesTurn(input, ws, session, config) {
+  session.isTurnActive = true;
+  session.currentInputForNoOutput = input;
+  session.sawPartialAssistantText = false;
+  session._lastWs = ws;
+  session._lastConfig = 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 run = await createRun(gatewayUrl, agentConfig, inputWithOutbox, hermesSessionId);
+    if (!run?.run_id) throw new Error('Hermes Gateway 未返回 run_id');
+    session.hermesRunId = run.run_id;
+    config.logger?.info('hermes run started', { runId: run.run_id, sessionId: hermesSessionId });
+    await streamRunEvents(gatewayUrl, agentConfig, run.run_id, ws, session, config);
+    if (session.isTurnActive) {
+      sendSystem(ws, 'Hermes 事件流已关闭。');
+      finishTurn(ws, session, config);
+    }
+  } catch (err) {
+    if (!isAbortError(err)) {
+      sendError(ws, `Hermes 错误: ${err.message}`);
+    }
+    finishTurn(ws, session, config, { drain: !isAbortError(err) });
+  }
+}
+
+async function createRun(gatewayUrl, agentConfig, input, sessionId) {
+  const body = {
+    input: buildHermesInput(input),
+    session_id: sessionId,
+  };
+  if (agentConfig.model) body.model = agentConfig.model;
+  if (agentConfig.instructions) body.instructions = agentConfig.instructions;
+
+  const response = await fetchJson(`${gatewayUrl}/v1/runs`, agentConfig, {
+    method: 'POST',
+    body: JSON.stringify(body),
+  });
+  return response;
+}
+
+async function streamRunEvents(gatewayUrl, agentConfig, runId, ws, session, config) {
+  const controller = new AbortController();
+  session.hermesAbortController = controller;
+  session.agentProcess = createHermesProcessHandle(gatewayUrl, agentConfig, runId, controller);
+
+  const response = await fetch(`${gatewayUrl}/v1/runs/${encodeURIComponent(runId)}/events`, {
+    method: 'GET',
+    headers: buildHeaders(agentConfig),
+    signal: controller.signal,
+  });
+
+  if (!response.ok) {
+    throw new Error(await responseErrorText(response));
+  }
+
+  let buffer = '';
+  const decoder = new TextDecoder();
+  for await (const chunk of response.body) {
+    buffer += decoder.decode(chunk, { stream: true });
+    const frames = buffer.split(/\r?\n\r?\n/);
+    buffer = frames.pop() || '';
+    for (const frame of frames) {
+      const event = parseSseFrame(frame);
+      if (event) handleHermesEvent(event, ws, session, config);
+      if (!session.isTurnActive) return;
+    }
+  }
+
+  if (buffer.trim()) {
+    const event = parseSseFrame(buffer);
+    if (event) handleHermesEvent(event, ws, session, config);
+  }
+}
+
+function parseSseFrame(frame) {
+  const data = frame
+    .split(/\r?\n/)
+    .filter(line => line.startsWith('data:'))
+    .map(line => line.slice(5).trimStart())
+    .join('\n')
+    .trim();
+  if (!data || data === '[DONE]') return null;
+  try {
+    return JSON.parse(data);
+  } catch {
+    return null;
+  }
+}
+
+function handleHermesEvent(event, ws, session, config) {
+  switch (event.event) {
+    case 'message.delta':
+      if (event.delta) appendHermesAssistantText(event.delta, ws, session);
+      return;
+    case 'tool.started':
+      send(ws, 'tool_call', {
+        id: toolId(event),
+        name: event.tool || 'Hermes Tool',
+        input: event.preview || '',
+      });
+      return;
+    case 'tool.completed':
+      send(ws, 'tool_result', {
+        toolUseId: toolId(event),
+        output: formatToolCompleted(event),
+        isError: event.error === true,
+      });
+      return;
+    case 'reasoning.available':
+      send(ws, 'thinking', { text: event.text || '' });
+      return;
+    case 'approval.request':
+      handleApprovalRequest(event, ws, session);
+      return;
+    case 'approval.responded':
+      sendSystem(ws, event.choice === 'deny' ? '🚫 已拒绝 Hermes 操作。' : '✅ 已批准 Hermes 操作。');
+      return;
+    case 'run.completed':
+      completeRun(event, ws, session, config);
+      return;
+    case 'run.failed':
+      sendError(ws, event.error || 'Hermes run 执行失败');
+      finishTurn(ws, session, config);
+      return;
+    case 'run.cancelled':
+      sendSystem(ws, 'Hermes run 已停止。');
+      finishTurn(ws, session, config);
+      return;
+    default:
+      return;
+  }
+}
+
+function handleApprovalRequest(event, ws, session) {
+  const requestId = `hermes-${event.run_id || session.hermesRunId}-${Date.now()}`;
+  const input = event.command || event.description || event.preview || '';
+  session.pendingPermission = {
+    provider: 'hermes',
+    requestId,
+    runId: event.run_id || session.hermesRunId,
+    toolName: 'exec',
+    input,
+    choices: event.choices || [],
+  };
+  send(ws, 'permission_request', {
+    requestId,
+    toolName: 'exec',
+    input,
+  });
+}
+
+function completeRun(event, ws, session, config) {
+  if (!session.streamState?.assistantStarted && event.output) {
+    appendHermesAssistantText(event.output, ws, session);
+  }
+  const hadOutput = session.streamState?.assistantStarted || Boolean(event.output);
+  flushHermesAssistantText(ws, session);
+  if (hadOutput) {
+    send(ws, 'assistant_end', {});
+  } else {
+    sendSystem(ws, 'Hermes 本次执行没有输出。');
+  }
+  updateHermesSessionStats(session, event.usage);
+  finishTurn(ws, session, config);
+}
+
+function finishTurn(ws, session, config, options = {}) {
+  const { drain = true } = options;
+  if (session.hermesAbortController) {
+    try {
+      session.hermesAbortController.abort();
+    } catch {}
+  }
+  session.hermesAbortController = null;
+  session.hermesRunId = null;
+  session.isTurnActive = false;
+  session.currentInputForNoOutput = null;
+  session.pendingPermission = null;
+  flushHermesAssistantText(ws, session);
+  resetHermesAssistantText(session);
+  if (drain) drainQueue(ws, session, config);
+}
+
+function ensureHermesSessionId(session) {
+  if (!session.agentSessionId) {
+    const newId = `hermes-${crypto.randomUUID().slice(0, 12)}`;
+    session.agentSessionId = newId;
+    session.claudeSessionId = newId;
+    // Capture the first message text from the turn input for /list display
+    const firstMsg = session.currentInputForNoOutput
+      ? extractText(session.currentInputForNoOutput).slice(0, 200)
+      : '';
+    if (!session.agentSessionHistory) session.agentSessionHistory = [];
+    for (const entry of session.agentSessionHistory) {
+      entry.isActive = false;
+    }
+    const entry = createAgentSessionEntry(session, newId, firstMsg);
+    entry.isActive = true;
+    session.agentSessionHistory.push(entry);
+    saveSessionMetadata(session);
+  }
+  return session.agentSessionId;
+}
+
+function updateHermesSessionStats(session, usage = {}) {
+  session.messageCount = (session.messageCount || 0) + 1;
+  if (!session.usage) {
+    session.usage = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0 };
+  }
+  session.usage.inputTokens += usage.input_tokens || usage.inputTokens || 0;
+  session.usage.outputTokens += usage.output_tokens || usage.outputTokens || 0;
+  updateAgentSessionHistory(session);
+}
+
+function buildHermesInput(input) {
+  if (!Array.isArray(input)) {
+    return [{ role: 'user', content: String(input || '') }];
+  }
+  const contentParts = [];
+  for (const block of input) {
+    if (typeof block === 'string') {
+      contentParts.push({ type: 'text', text: block });
+    } else if (block?.type === 'text') {
+      contentParts.push({ type: 'text', text: block.text || '' });
+    } else if (block?.type === 'image') {
+      const mediaType = block.source?.media_type || 'image/png';
+      const data = block.source?.data;
+      if (data) {
+        contentParts.push({ type: 'image_url', image_url: { url: `data:${mediaType};base64,${data}` } });
+      } else if (block.path) {
+        contentParts.push({ type: 'text', text: `用户发送了一张图片，文件路径：${block.path}` });
+      } else {
+        contentParts.push({ type: 'text', text: '[图片附件]' });
+      }
+    } else {
+      contentParts.push({ type: 'text', text: JSON.stringify(block) });
+    }
+  }
+  return [{ role: 'user', content: contentParts }];
+}
+
+function maybeAddImageDataUrls(input) {
+  if (!Array.isArray(input)) return String(input || '');
+  return input.map(block => {
+    if (typeof block === 'string') return block;
+    if (block?.type === 'text') return block.text || '';
+    if (block?.type === 'image') {
+      const mediaType = block.source?.media_type || 'image/png';
+      const data = block.source?.data;
+      if (data) return `用户发送了一张图片：data:${mediaType};base64,${data}`;
+      if (block.path) return `用户发送了一张图片，文件路径：${block.path}`;
+      return '[图片附件]';
+    }
+    return JSON.stringify(block);
+  }).filter(Boolean).join('\n');
+}
+
+function stringifyInput(input) {
+  return maybeAddImageDataUrls(input);
+}
+
+function maybeAddOutboxHint(input, session, config) {
+  const text = stringifyInput(input);
+  if (!/发送.*(文件|图片)|把.*(文件|图片).*发|发给我|发送给我|文件发送|发文件|下载文件/.test(text)) {
+    return input;
+  }
+  const hint = `系统提示：用户正在要求发送文件/图片。请将要发送给用户的最终文件保存或复制到以下 outbox 目录，系统只会自动发送这个目录中的新文件：\n${getOutboxDir(session, config)}`;
+  if (Array.isArray(input)) return [...input, { type: 'text', text: hint }];
+  return `${text}\n\n${hint}`;
+}
+
+function appendHermesAssistantText(text, ws, session) {
+  ensureHermesStreamState(session);
+  appendTextStream(text, ws, session.streamState);
+}
+
+function flushHermesAssistantText(ws, session) {
+  flushTextStream(ws, session.streamState);
+}
+
+function resetHermesAssistantText(session) {
+  ensureHermesStreamState(session);
+  resetTextStream(session.streamState);
+}
+
+function ensureHermesStreamState(session) {
+  if (!session.streamState) {
+    session.streamState = createTextStreamBuffer({ onStart: ws => send(ws, 'assistant_start', {}) });
+  }
+  session.streamState.onStart = ws => send(ws, 'assistant_start', {});
+}
+
+function toolId(event) {
+  return `${event.run_id || 'hermes'}:${event.tool || 'tool'}`;
+}
+
+function formatToolCompleted(event) {
+  const duration = typeof event.duration === 'number' ? `，耗时 ${event.duration}s` : '';
+  return `${event.tool || '工具'} ${event.error ? '执行失败' : '执行完成'}${duration}`;
+}
+
+async function resolvePendingDanger(confirmed, ws, session, config) {
+  const pending = session.pendingDanger;
+  if (!pending) return false;
+  session.pendingDanger = null;
+  if (!confirmed) {
+    sendSystem(ws, '已取消危险操作。');
+    return true;
+  }
+  execute(pending.input, ws, session, config);
+  return true;
+}
+
+async function resolvePendingPermission(approved, ws, session, config) {
+  const pending = session.pendingPermission;
+  if (!pending || pending.provider !== 'hermes') return false;
+
+  const agentConfig = config.agents?.hermes || {};
+  const gatewayUrl = normalizeGatewayUrl(agentConfig.gatewayUrl || agentConfig.baseUrl || DEFAULT_GATEWAY_URL);
+  const runId = pending.runId || session.hermesRunId;
+  session.pendingPermission = null;
+
+  try {
+    await fetchJson(`${gatewayUrl}/v1/runs/${encodeURIComponent(runId)}/approval`, agentConfig, {
+      method: 'POST',
+      body: JSON.stringify({ choice: approved ? 'once' : 'deny' }),
+    });
+    sendSystem(ws, approved ? '✅ 已批准 Hermes 操作。' : '🚫 已拒绝 Hermes 操作。');
+  } catch (err) {
+    sendError(ws, `Hermes 审批响应失败: ${err.message}`);
+  }
+  return true;
+}
+
+function stop(session, options = {}) {
+  const agentConfig = session._lastConfig?.agents?.hermes || {};
+  const runId = session.hermesRunId;
+  if (session.hermesAbortController) {
+    try {
+      session.hermesAbortController.abort();
+    } catch {}
+  }
+  if (runId) {
+    const gatewayUrl = normalizeGatewayUrl(agentConfig.gatewayUrl || agentConfig.baseUrl || DEFAULT_GATEWAY_URL);
+    fetchJson(`${gatewayUrl}/v1/runs/${encodeURIComponent(runId)}/stop`, agentConfig, { method: 'POST' }).catch(() => {});
+  }
+  session.hermesAbortController = null;
+  session.hermesRunId = null;
+  stopSessionProcess(session, options);
+}
+
+function createHermesProcessHandle(gatewayUrl, agentConfig, runId, controller) {
+  const handle = {
+    killed: false,
+    exitCode: null,
+    stdin: {
+      destroyed: false,
+      end() {
+        this.destroyed = true;
+        handle.kill();
+      },
+    },
+    kill() {
+      if (this.killed) return;
+      this.killed = true;
+      this.exitCode = 0;
+      try {
+        controller.abort();
+      } catch {}
+      fetchJson(`${gatewayUrl}/v1/runs/${encodeURIComponent(runId)}/stop`, agentConfig, { method: 'POST' }).catch(() => {});
+    },
+  };
+  return handle;
+}
+function drainQueue(ws, session, config) {
+  const next = session.messageQueue.shift();
+  if (!next) return;
+  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}`;
+  return headers;
+}
+
+async function fetchJson(url, agentConfig, options = {}) {
+  const response = await fetch(url, {
+    ...options,
+    headers: {
+      ...buildHeaders(agentConfig),
+      'Content-Type': 'application/json',
+      ...(options.headers || {}),
+    },
+  });
+  if (!response.ok) throw new Error(await responseErrorText(response));
+  return response.json();
+}
+
+async function responseErrorText(response) {
+  const text = await response.text().catch(() => '');
+  if (!text) return `${response.status} ${response.statusText}`;
+  try {
+    const parsed = JSON.parse(text);
+    return parsed.error?.message || text;
+  } catch {
+    return text;
+  }
+}
+
+function isAbortError(err) {
+  return err?.name === 'AbortError';
+}
+
+module.exports = {
+  execute,
+  resolvePendingDanger,
+  resolvePendingPermission,
+  stop,
+};

package/src/config.js

@@ -9,6 +9,7 @@ const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
 const DEFAULT_AGENT_WS_URLS = {
   claude: 'wss://chat.ddjf.info/socket/ai/claude',
   codex: 'wss://chat.ddjf.info/socket/ai/codex',
+  hermes: 'wss://chat.ddjf.info/socket/ai/hermes',
 };
 const DEFAULT_LINCO_WS_URL = DEFAULT_AGENT_WS_URLS.claude;
 function getConfigDir() {
@@ -220,6 +221,11 @@ function localImEnabled(userConfig) {
   return booleanFromEnv('LINCO_LOCAL_IM_ENABLED', userConfig.localWeb?.imEnabled === true);
 }
 
+function localWebEnabled(userConfig) {
+  // 本地测试页跟随本地模拟IM的开关，--local-im 时一并启用
+  return booleanFromEnv('LINCO_LOCAL_WEB_ENABLED', userConfig.localWeb?.enabled === true || localImEnabled(userConfig));
+}
+
 function hasOwn(object, key) {
   return Object.prototype.hasOwnProperty.call(object || {}, key);
 }
@@ -245,6 +251,9 @@ function agentConfig(userConfig, imConfig, agentType, defaults = {}) {
     ? selectedImEnabled(userConfig, imConfig)
     : false;
   const channelAgentConfig = agentConfigFromChannels(userConfig, agentType);
+  const channelAccount = channelAgentConfig
+    ? channelAgentConfig.accounts?.[channelAgentConfig.defaultAccount || 'default']
+    : null;
   const channelAccountEnabled = channelAgentConfig && Object.values(channelAgentConfig.accounts || {}).some(
     account => account.enabled === true
   );
@@ -253,6 +262,11 @@ function agentConfig(userConfig, imConfig, agentType, defaults = {}) {
   const enabled = booleanFromEnv(`LINCO_${agentType.toUpperCase()}_ENABLED`, enabledFallback);
   const binEnv = `LINCO_${agentType.toUpperCase()}_BIN`;
   const wsEnv = `LINCO_${agentType.toUpperCase()}_WS_URL`;
+  const gatewayEnv = `LINCO_${agentType.toUpperCase()}_GATEWAY_URL`;
+  const apiKeyEnv = `LINCO_${agentType.toUpperCase()}_API_KEY`;
+  const instructionsEnv = `LINCO_${agentType.toUpperCase()}_INSTRUCTIONS`;
+  const appIdEnv = `LINCO_${agentType.toUpperCase()}_APP_ID`;
+  const appSecretEnv = `LINCO_${agentType.toUpperCase()}_APP_SECRET`;
 
   return {
     type: agentType,
@@ -261,6 +275,11 @@ 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),
+    apiKey: stringFromEnv(apiKeyEnv, configured.apiKey || defaults.apiKey),
+    instructions: stringFromEnv(instructionsEnv, configured.instructions || defaults.instructions),
+    appId: stringFromEnv(appIdEnv, channelAccount?.appId || configured.appId),
+    appSecret: stringFromEnv(appSecretEnv, channelAccount?.appSecret || configured.appSecret),
   };
 }
 
@@ -288,6 +307,7 @@ function loadConfig(rootDir) {
   const sessionsDir = stringFromEnv('LINCO_SESSIONS_DIR', userConfig.sessionsDir || path.join(lincoHome, 'sessions'));
   const accountAgentType = imConfig.agentType;
   const codexAccountConfig = defaultAccountFromChannels(userConfig, 'codex');
+  const hermesAccountConfig = defaultAccountFromChannels(userConfig, 'hermes');
   const agents = {
     claude: agentConfig(userConfig, imConfig, 'claude', {
       bin: stringFromEnv('CLAUDE_BIN', userConfig.claudeBin || 'claude'),
@@ -297,6 +317,10 @@ function loadConfig(rootDir) {
       bin: stringFromEnv('CODEX_BIN', userConfig.codexBin || codexAccountConfig.bin || 'codex'),
       wsUrl: codexAccountConfig.wsUrl || DEFAULT_AGENT_WS_URLS.codex,
     }),
+    hermes: agentConfig(userConfig, imConfig, 'hermes', {
+      wsUrl: hermesAccountConfig.wsUrl || DEFAULT_AGENT_WS_URLS.hermes,
+      gatewayUrl: 'http://127.0.0.1:8642',
+    }),
   };
   const accountAgent = agents[accountAgentType];
   const imEnabled = selectedImEnabled(userConfig, imConfig) || (accountAgent && accountAgent.enabled);
@@ -330,6 +354,7 @@ function loadConfig(rootDir) {
     configFile,
     localWeb: {
       ...(userConfig.localWeb || {}),
+      enabled: localWebEnabled(userConfig),
       imEnabled: localImEnabled(userConfig),
     },
     logsDir: path.join(lincoHome, 'logs'),

package/src/httpStatic.js

@@ -101,11 +101,11 @@ function buildClientWebSocketUrl(req, config) {
 
 function localAgentOptions(config) {
   const agents = config.agents || {};
-  return ['claude', 'codex']
+  return ['claude', 'codex', 'hermes']
     .filter(type => agents[type])
     .map(type => ({
       type,
-      label: type === 'claude' ? 'Claude Code' : type === 'codex' ? 'Codex' : type,
+      label: type === 'claude' ? 'Claude Code' : type === 'codex' ? 'Codex' : type === 'hermes' ? 'Hermes' : type,
       enabled: agents[type]?.enabled === true,
     }));
 }

package/src/imConnector.js

@@ -49,7 +49,9 @@ class ImConnector {
   }
 
   start() {
-    if (!this.config.im?.appId || !this.config.im?.appSecret) {
+    const appId = this.agentConfig.appId || this.config.im.appId;
+    const appSecret = this.agentConfig.appSecret || this.config.im.appSecret;
+    if (!appId || !appSecret) {
       console.log(`[IM:${this.agentType}] 远端 IM 已启用，但缺少 Linco token，已跳过连接。`);
       return;
     }
@@ -149,7 +151,9 @@ class ImConnector {
     }
     url.searchParams.delete('appId');
     url.searchParams.delete('appSecret');
-    url.searchParams.set('token', `${this.config.im.appId}:${this.config.im.appSecret}`);
+    const appId = this.agentConfig.appId || this.config.im.appId;
+    const appSecret = this.agentConfig.appSecret || this.config.im.appSecret;
+    url.searchParams.set('token', `${appId}:${appSecret}`);
     return url.toString();
   }
 
@@ -438,7 +442,7 @@ function sendSessionInfo(ws, session, config) {
     },
     capabilities: {
       incomingAttachments: true,
-      multimodalImages: session.agentType === 'claude',
+      multimodalImages: ['claude', 'hermes'].includes(session.agentType),
       outgoingAttachments: true,
       remoteIm: true,
       agentType: session.agentType,

package/src/lincoProtocol.js

@@ -36,7 +36,7 @@ function createLincoAdapter(rawWs, session, config) {
       }
       const payload = mapLocalEventToLinco(event, session, config, linco);
       if (!payload || closed.current) return;
-      const wrapped = wrapLincoEnvelope(payload, config);
+      const wrapped = wrapLincoEnvelope(payload, config, session);
       if (Array.isArray(wrapped)) {
         for (const item of wrapped) rawWs.send(JSON.stringify(item));
         return;
@@ -55,11 +55,11 @@ function createLincoAdapter(rawWs, session, config) {
   };
 }
 
-function wrapLincoEnvelope(payload, config) {
+function wrapLincoEnvelope(payload, config, session) {
   const meta = lincoMetaDefaults(config, {});
   return pruneUndefined({
     ...payload,
-    from: payload.from || (config.agents ? Object.keys(config.agents)[0] : 'claude'),
+    from: payload.from || session?.agentType || (config.agents ? Object.keys(config.agents)[0] : 'claude'),
     to: payload.to || 'robot',
     source: payload.source || 'ws',
     ts: payload.ts || Date.now(),

package/src/serverApp.js

@@ -15,33 +15,58 @@ function startServer(rootDir, options = {}) {
     log.info('git bash detected', { path: config.gitBashEnv });
   }
 
-  const server = createStaticServer(config);
-  attachWebSocketServer(server, config);
   const imConnectors = startImConnectors(config);
 
-  server.on('close', () => {
-    log.info('server closing');
-    for (const connector of imConnectors) connector.stop();
-    options.onClose?.(server, config);
-  });
+  if (config.localWeb?.enabled) {
+    const server = createStaticServer(config);
+    attachWebSocketServer(server, config);
 
-  server.listen(config.port, config.host, () => {
+    server.on('close', () => {
+      log.info('server closing');
+      for (const connector of imConnectors) connector.stop();
+      options.onClose?.(server, config);
+    });
+
+    server.listen(config.port, config.host, () => {
+      ensureDir(config.lincoHome);
+      ensureDir(config.sessionsDir);
+      ensureDir(config.logsDir);
+      const localUrl = localUrlWithToken(config);
+      log.info('server started', {
+        host: config.host,
+        port: config.port,
+        lincoHome: config.lincoHome,
+        sessionsDir: config.sessionsDir,
+        imEnabled: !!config.im?.enabled,
+        agents: Object.entries(config.agents || {}).filter(([, agent]) => agent.enabled).map(([type]) => type),
+      });
+      console.log('🚀 IM + Agent 桥接服务已启动');
+      console.log('');
+      console.log('📋 请复制下面的完整地址到浏览器打开本地测试页：');
+      console.log(localUrl);
+      console.log('');
+      console.log(`   Linco 运行目录: ${config.lincoHome}`);
+      console.log(`   会话目录: ${config.sessionsDir}`);
+      console.log(`   日志级别: ${config.logLevel}`);
+      if (config.im?.enabled) {
+        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'})`);
+      }
+      options.onListening?.(server, config);
+    });
+
+    return server;
+  } else {
     ensureDir(config.lincoHome);
     ensureDir(config.sessionsDir);
     ensureDir(config.logsDir);
-    const localUrl = localUrlWithToken(config);
-    log.info('server started', {
-      host: config.host,
-      port: config.port,
+    log.info('server started (no local web)', {
       lincoHome: config.lincoHome,
       sessionsDir: config.sessionsDir,
       imEnabled: !!config.im?.enabled,
       agents: Object.entries(config.agents || {}).filter(([, agent]) => agent.enabled).map(([type]) => type),
     });
-    console.log('🚀 IM + Agent 桥接服务已启动');
-    console.log('');
-    console.log('📋 请复制下面的完整地址到浏览器打开本地测试页：');
-    console.log(localUrl);
+    console.log('🚀 IM + Agent 桥接服务已启动（本地测试页未启用）');
     console.log('');
     console.log(`   Linco 运行目录: ${config.lincoHome}`);
     console.log(`   会话目录: ${config.sessionsDir}`);
@@ -50,10 +75,11 @@ 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'})`);
     }
-    options.onListening?.(server, config);
-  });
-
-  return server;
+    console.log('');
+    console.log('💡 如需开启本地测试页，请运行 linco-connect start --local-im');
+    options.onListening?.(null, config);
+    return null;
+  }
 }
 
 module.exports = {

package/src/slashCommands.js

@@ -2,7 +2,8 @@ const fs = require('fs');
 const path = require('path');
 const { resetOutgoingAttachments, startOutboxWatcher, stopOutboxWatcher } = require('./outgoingAttachmentHandler');
 const { sendError, sendSystem } = require('./protocol');
-const { removeAgentSessionFromHistory, saveSessionMetadata, stopAgentProcess } = require('./session');
+const { removeAgentSessionFromHistory, saveSessionMetadata } = require('./session');
+const { stopAgentProcess } = require('./agentRunner');
 
 function localCommandsHelp() {
   return `📋 Linco 本地命令：
@@ -48,10 +49,18 @@ function handleSlashCommand(text, ws, session, config) {
       return true;
 
     case '/pwd':
+      if (isHermesSession(session)) {
+        sendHermesWorkspaceNotice(ws);
+        return true;
+      }
       sendSystem(ws, `📂 ${session.workspace}`);
       return true;
 
     case '/cd':
+      if (isHermesSession(session)) {
+        sendHermesWorkspaceNotice(ws);
+        return true;
+      }
       handleCd(parts[1], ws, session, config);
       return true;
 
@@ -120,6 +129,14 @@ Agent 进程: ${processRunning ? '运行中' : '未运行'}
 待确认: ${session.pendingPermission ? '工具权限' : session.pendingDanger ? '危险操作' : '无'}`);
 }
 
+function isHermesSession(session) {
+  return (session.agentType || 'claude') === 'hermes';
+}
+
+function sendHermesWorkspaceNotice(ws) {
+  sendSystem(ws, 'Hermes 模式下工作目录由 Hermes Gateway/Agent 自身决定，/pwd 与 /cd 不在插件侧处理。');
+}
+
 function handleCd(targetPath, ws, session, config) {
   if (!targetPath) {
     try {

package/src/wsServer.js

@@ -134,7 +134,7 @@ function sendSessionInfo(ws, session, config) {
     },
     capabilities: {
       incomingAttachments: true,
-      multimodalImages: session.agentType === 'claude',
+      multimodalImages: ['claude', 'hermes'].includes(session.agentType),
       outgoingAttachments: true,
     },
   });