agent-bridge-hermes 0.0.0-stage → 1.0.2

package/README.md

@@ -1,3 +1,7 @@
-# Temporary Holding Version
+# Hermes Desktop 插件
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+通过官方 Python 客户端连接同用户的 Hermes 本地 Gateway，支持健康检查、文本及附件输入、新建与恢复会话。需要先安装官方 Hermes Desktop，并在相同用户下完成模型配置。插件复用 Hermes 的模型设置，不读取或另存模型 KEY。
+
+Windows 默认安装根目录为 `%LOCALAPPDATA%\hermes`，其他系统为 `~/.hermes`；自定义安装可配置 `hermesHome` 和 `pythonPath`。Python 入口通过官方依赖管理器加载当前环境。网关鉴权复用官方同用户私有管道票据，不开放远程网关端口。
+
+会话返回 Hermes 的真实 ID，保存该 ID 即可续聊；`newSession` 创建独立会话。支持文本文件等普通文件以及 PNG/JPEG/WebP 图片输入，文件经官方 `file.attach` 引用，图片经 `image.attach_bytes` 及 `prompt.submit` 提交；不把附件内容伪装成文本。单个附件最多 32 MiB、每条最多 8 个、合计最多 64 MiB，并受 Hermes 自身更严格的限制约束。附件暂存失败时不提交任务。暂未实现模型生成附件的回传。任务按调用顺序执行，不自动批准工具或交互确认；需要确认时请在桌面操作。取消、卸载与超时只停止等待，已经提交的桌面任务可能继续运行；请在桌面检查，避免盲目重发。

package/config.schema.json

@@ -0,0 +1,24 @@
+{
+  "type": "object",
+  "properties": {
+    "aid": {
+      "type": "string",
+      "description": "关联的 AID"
+    },
+    "hermesHome": {
+      "type": "string",
+      "description": "Hermes 安装根目录，默认使用当前用户官方安装目录"
+    },
+    "pythonPath": {
+      "type": "string",
+      "description": "Python 可执行文件，默认优先使用 Hermes 自带版本"
+    },
+    "timeoutMs": {
+      "type": "integer",
+      "minimum": 1,
+      "default": 1200000,
+      "description": "等待回复的毫秒数；超时不终止桌面任务"
+    }
+  },
+  "additionalProperties": false
+}

package/dist/src-ts/agent.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentOperationError = exports.AgentError = void 0;
+exports.abortable = abortable;
+exports.errorDetails = errorDetails;
+async function abortable(promise, signal) {
+    if (!signal)
+        return promise;
+    if (signal.aborted) {
+        // promise 已在调用方启动，先观察其拒绝，避免预取消时产生未处理拒绝。
+        void promise.catch(() => undefined);
+        signal.throwIfAborted();
+    }
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const cleanup = () => signal.removeEventListener("abort", abort);
+        const abort = () => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(signal.reason);
+        };
+        signal.addEventListener("abort", abort, { once: true });
+        promise.then((value) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve(value);
+        }, (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(error);
+        });
+    });
+}
+class AgentError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "AgentError";
+    }
+}
+exports.AgentError = AgentError;
+/** 保留底层错误码，避免只留下 fetch failed 或超时这类表层提示。 */
+function errorDetails(error) {
+    const parts = [];
+    const seen = new Set();
+    for (let current = error; current && !seen.has(current) && seen.size < 5;) {
+        seen.add(current);
+        const value = current;
+        const message = typeof value.message === "string" ? value.message : String(current);
+        parts.push(`${message}${value.code ? `（${String(value.code)}）` : ""}`);
+        current = value.cause;
+    }
+    return parts.join("；原因：") || String(error);
+}
+class AgentOperationError extends AgentError {
+    code;
+    stage;
+    constructor(code, stage, cause) {
+        super(`${code}：${stage}失败：${errorDetails(cause)}`, { cause });
+        this.code = code;
+        this.stage = stage;
+    }
+}
+exports.AgentOperationError = AgentOperationError;

package/dist/src-ts/attachments.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_TOTAL_ATTACHMENT_BYTES = exports.MAX_ATTACHMENTS = exports.MAX_ATTACHMENT_BYTES = void 0;
+exports.detectImageContentType = detectImageContentType;
+exports.attachmentFilename = attachmentFilename;
+exports.validateAttachment = validateAttachment;
+exports.validateAttachments = validateAttachments;
+exports.asAttachments = asAttachments;
+exports.MAX_ATTACHMENT_BYTES = 32 * 1024 * 1024;
+exports.MAX_ATTACHMENTS = 8;
+exports.MAX_TOTAL_ATTACHMENT_BYTES = 64 * 1024 * 1024;
+function detectImageContentType(data) {
+    if (data.length >= 8 && data.slice(0, 8).every((value, index) => value === [137, 80, 78, 71, 13, 10, 26, 10][index]))
+        return "image/png";
+    if (data.length >= 3 && data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff)
+        return "image/jpeg";
+    if (data.length >= 12 && String.fromCharCode(...data.slice(0, 4)) === "RIFF" && String.fromCharCode(...data.slice(8, 12)) === "WEBP")
+        return "image/webp";
+    return undefined;
+}
+function attachmentFilename(filename) {
+    if (typeof filename !== "string" || /[\u0000-\u001f\u007f]/.test(filename))
+        throw new Error("附件文件名无效");
+    const name = filename.split(/[\\/]/).pop() ?? "";
+    if (!name.trim() || name === "." || name === "..")
+        throw new Error("附件文件名无效");
+    return name;
+}
+function validateAttachment(item) {
+    if (!item || !(item.data instanceof Uint8Array) || item.data.byteLength === 0)
+        throw new Error("附件内容不能为空");
+    if (item.data.byteLength > exports.MAX_ATTACHMENT_BYTES)
+        throw new Error("单个附件不能超过 32 MiB");
+    attachmentFilename(item.filename);
+    if (item.kind !== "image" && item.kind !== "file")
+        throw new Error("附件类型无效");
+    if (typeof item.contentType !== "string" || !/^[A-Za-z0-9!#$&^_.+-]+\/[A-Za-z0-9!#$&^_.+-]+$/.test(item.contentType))
+        throw new Error("附件 MIME 类型无效");
+    if (item.kind === "image") {
+        const detected = detectImageContentType(item.data);
+        if (!detected || detected !== item.contentType.toLowerCase())
+            throw new Error("图片内容与 MIME 类型不一致");
+    }
+}
+function validateAttachments(items) {
+    if (!items)
+        return;
+    if (!Array.isArray(items))
+        throw new Error("附件列表无效");
+    if (items.length > exports.MAX_ATTACHMENTS)
+        throw new Error("单条消息最多包含 8 个附件");
+    let total = 0;
+    for (const item of items) {
+        validateAttachment(item);
+        total += item.data.byteLength;
+    }
+    if (total > exports.MAX_TOTAL_ATTACHMENT_BYTES)
+        throw new Error("单条消息附件总大小不能超过 64 MiB");
+}
+function asAttachments(images) {
+    return (images ?? []).map((image) => ({ ...image, kind: "image" }));
+}

package/dist/src-ts/plugin.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRuntimePort = resolveRuntimePort;
+function resolveRuntimePort(config, runtime, pluginId, envName, fallback) {
+    const injected = runtime?.ports?.[pluginId];
+    if (typeof injected === "number" && Number.isInteger(injected) && injected > 0)
+        return injected;
+    const configured = config.cdpPort;
+    if (typeof configured === "number" && Number.isInteger(configured) && configured > 0)
+        return configured;
+    const environment = Number(process.env[envName] ?? "");
+    return Number.isInteger(environment) && environment > 0 ? environment : fallback;
+}

package/dist/src-ts/plugins/agent-task-ability.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTaskAbility = createTaskAbility;
+const node_crypto_1 = require("node:crypto");
+const agent_1 = require("../agent");
+function createTaskAbility(handle) {
+    return {
+        definition: {
+            path: "agent/task/run",
+            name: "执行大模型任务",
+            summary: "在独立新会话中执行自然语言任务并返回文字；可能使用目标 Agent 的工具、读写文件及访问网络，须逐次确认。图片和文件不通过此接口交付。",
+            contract_revision: "1",
+            params_schema: { type: "object", required: ["task"], properties: { task: { type: "string", minLength: 1, maxLength: 20_000, pattern: "\\S" } }, additionalProperties: false },
+            result_schema: { type: "object", required: ["text"], properties: { text: { type: "string", minLength: 1, maxLength: 60_000 }, attachments_omitted: { type: "integer", minimum: 1 } }, additionalProperties: false },
+            effects: ["state.read", "state.write", "data.egress", "data.local_write", "credential.access", "code.execute", "system.interact"],
+            auth_required: true, require_confirm: true, idempotency: "keyed",
+            allowed_modes: ["explicit"], aggregation: "none", dedupe_retention_seconds: 3600,
+        },
+        handler: async (params, { signal }) => {
+            signal.throwIfAborted();
+            const task = params?.task;
+            if (!params || typeof params !== "object" || Array.isArray(params) || Object.keys(params).length !== 1 || typeof task !== "string" || !task.trim() || task.length > 20_000)
+                throw new Error("任务参数必须仅包含 1 至 20,000 字符的非空 task");
+            const response = await (0, agent_1.abortable)(handle({ task, sessionId: (0, node_crypto_1.randomUUID)(), newSession: true, signal, attachmentOutput: false }), signal);
+            const omitted = response.attachments?.length || response.images?.length || 0;
+            let text = response.text?.trim() ?? "";
+            if (omitted)
+                text += `${text ? "\n\n" : ""}附件尚未通过本次 Ability 交付（${omitted} 个）；请使用现有聊天附件入口获取。`;
+            if (!text)
+                throw new Error("任务未返回文字或附件，不能确认执行结果");
+            if (text.length > 60_000)
+                throw new Error("任务返回文字超过 60,000 字符，未截断或宣称交付完成");
+            return { text, ...(omitted ? { attachments_omitted: omitted } : {}) };
+        },
+    };
+}

package/dist/src-ts/plugins/hermes/client.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HermesGatewayClient = void 0;
+exports.sessionTitle = sessionTitle;
+const attachments_1 = require("../../attachments");
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const node_crypto_1 = require("node:crypto");
+const node_child_process_1 = require("node:child_process");
+function parseJsonLines(output) {
+    for (const line of output.split(/\r?\n/).reverse()) {
+        const text = line.trim();
+        if (!text || text.startsWith("<Objs"))
+            continue;
+        try {
+            return JSON.parse(text);
+        }
+        catch { /* 安装器的日志行不是协议响应，继续找最后一个 JSON。 */ }
+    }
+    throw new Error("Hermes Gateway 未返回 JSON 状态");
+}
+async function findPython(root, configured) {
+    if (configured)
+        return configured;
+    try {
+        for (const entry of (await (0, promises_1.readdir)((0, node_path_1.join)(root, "tools"))).sort().reverse()) {
+            if (!entry.startsWith("python-"))
+                continue;
+            const candidate = process.platform === "win32" ? (0, node_path_1.join)(root, "tools", entry, "python.exe") : (0, node_path_1.join)(root, "tools", entry, "bin", "python3");
+            if ((0, node_fs_1.existsSync)(candidate))
+                return candidate;
+        }
+    }
+    catch { /* 非引导安装使用 PATH 中的 Python。 */ }
+    return process.platform === "win32" ? "python.exe" : "python3";
+}
+class PythonHermesTransport {
+    connectedState = false;
+    pending = new Set();
+    root;
+    python;
+    timeoutMs;
+    helper;
+    constructor(options) {
+        this.root = (0, node_path_1.resolve)(options.hermesHome ?? process.env.HERMES_HOME ?? (process.platform === "win32" ? (0, node_path_1.join)(process.env.LOCALAPPDATA ?? (0, node_path_1.join)((0, node_os_1.homedir)(), "AppData", "Local"), "hermes") : (0, node_path_1.join)((0, node_os_1.homedir)(), ".hermes")));
+        this.python = options.pythonPath;
+        this.timeoutMs = options.timeoutMs ?? 1_200_000;
+        this.helper = (0, node_path_1.join)((0, node_path_1.dirname)(__filename), "gateway-client.py");
+    }
+    async connect() {
+        await this.run({ op: "health" });
+        this.connectedState = true;
+    }
+    close() { this.connectedState = false; for (const cancel of this.pending)
+        cancel(); }
+    async createSession(title) {
+        this.requireConnected();
+        const value = await this.run({ op: "create", title });
+        if (!value || typeof value.sessionId !== "string" || !value.sessionId)
+            throw new Error("Hermes Gateway 未返回会话 ID");
+        return value.sessionId;
+    }
+    async resumeSession(sessionId) {
+        this.requireConnected();
+        await this.run({ op: "resume", sessionId });
+    }
+    async complete(task, sessionId, timeoutMs = this.timeoutMs, signal, attachments) {
+        this.requireConnected();
+        (0, attachments_1.validateAttachments)(attachments);
+        const encoded = attachments?.map(item => ({ kind: item.kind, filename: (0, attachments_1.attachmentFilename)(item.filename), contentType: item.contentType, data: Buffer.from(item.data).toString("base64") }));
+        const value = await this.run({ op: "complete", task, sessionId, timeoutMs, attachments: encoded }, signal, timeoutMs + 15_000);
+        if (!value || typeof value.sessionId !== "string" || typeof value.text !== "string" || !value.text.trim())
+            throw new Error("Hermes Gateway 未返回文字");
+        return { sessionId: value.sessionId, text: value.text };
+    }
+    requireConnected() { if (!this.connectedState)
+        throw new Error("Hermes Gateway 客户端未连接"); }
+    requireActive(payload) { if (payload.op !== "health")
+        this.requireConnected(); }
+    run(payload, signal, timeoutMs = 30_000) {
+        return new Promise((resolvePromise, reject) => {
+            if (!(0, node_fs_1.existsSync)(this.helper))
+                return reject(new Error("Hermes 插件缺少 Gateway 通信入口"));
+            void findPython(this.root, this.python).then(python => {
+                signal?.throwIfAborted();
+                this.requireActive(payload);
+                const child = (0, node_child_process_1.spawn)(python, [this.helper], { env: { ...process.env, PYTHONIOENCODING: "utf-8", PYTHONUTF8: "1", HERMES_HOME: this.root, HERMES_AGENT_SOURCE: (0, node_path_1.join)(this.root, "hermes-agent") }, stdio: ["pipe", "pipe", "pipe"], windowsHide: true });
+                let stdout = "";
+                let settled = false;
+                const finish = (error, value) => { if (settled)
+                    return; settled = true; this.pending.delete(cancel); clearTimeout(timer); signal?.removeEventListener("abort", abort); error ? reject(error) : resolvePromise(value ?? {}); };
+                const cancel = () => { child.kill(); finish(new Error("Hermes 已停止等待，桌面任务可能仍在运行，请在桌面检查")); };
+                const abort = cancel;
+                this.pending.add(cancel);
+                const timer = setTimeout(() => { child.kill(); finish(new Error("Hermes Gateway 等待超时，桌面任务可能仍在运行，请在桌面检查")); }, Math.max(1_000, timeoutMs));
+                signal?.addEventListener("abort", abort, { once: true });
+                child.stdout.setEncoding("utf8");
+                child.stdout.on("data", chunk => { stdout += String(chunk); if (stdout.length > 8 * 1024 * 1024)
+                    cancel(); });
+                child.stderr.resume();
+                child.stdin.on("error", () => finish(new Error("Hermes Gateway 输入失败")));
+                child.on("error", () => finish(new Error("Hermes Python 启动失败，请检查 pythonPath")));
+                child.on("close", code => {
+                    if (settled)
+                        return;
+                    let value;
+                    try {
+                        value = parseJsonLines(stdout);
+                    }
+                    catch {
+                        finish(new Error(`Hermes Gateway 通信进程退出（${code ?? "unknown"}）`));
+                        return;
+                    }
+                    if (!value || typeof value !== "object" || value.ok !== true) {
+                        const message = (value?.error ?? "Hermes Gateway 通信失败") || "Hermes Gateway 通信失败";
+                        finish(new Error(String(message)));
+                        return;
+                    }
+                    finish(undefined, value);
+                });
+                child.stdin.end(JSON.stringify(payload), "utf8");
+            }).catch(error => reject(error));
+        });
+    }
+}
+class HermesGatewayClient {
+    transport;
+    isConnected = false;
+    constructor(options = {}) {
+        this.transport = options.transport ?? new PythonHermesTransport(options);
+    }
+    connected() { return this.isConnected; }
+    async connect() { await this.transport.connect(); this.isConnected = true; }
+    close() { this.transport.close(); this.isConnected = false; }
+    createSession(title) { return this.transport.createSession(title); }
+    resumeSession(sessionId) { return this.transport.resumeSession(sessionId); }
+    complete(task, sessionId, timeoutMs, signal, attachments) { return this.transport.complete(task, sessionId, timeoutMs, signal, attachments); }
+}
+exports.HermesGatewayClient = HermesGatewayClient;
+function sessionTitle(task) {
+    const text = task.trim().replace(/\s+/g, " ");
+    return `Agent Bridge：${text.slice(0, 80) || (0, node_crypto_1.randomUUID)()}`;
+}

package/dist/src-ts/plugins/hermes/gateway-client.py

@@ -0,0 +1,110 @@
+import asyncio
+from contextlib import suppress
+import json
+import os
+import sys
+import uuid
+
+
+def fail(message):
+    print(json.dumps({"ok": False, "error": str(message)[:500]}, ensure_ascii=False), flush=True)
+    raise SystemExit(1)
+
+
+async def main(request):
+    source = os.environ.get("HERMES_AGENT_SOURCE")
+    if not source:
+        fail("未找到 Hermes 源码目录")
+    sys.path.insert(0, source)
+    try:
+        from pathlib import Path
+        from pm.environments import activate_dependencies
+        activate_dependencies(Path(source))
+        from hermes_cli.gateway_client import connect_gateway
+    except Exception as exc:
+        fail("Hermes Gateway 客户端不可用，请检查官方安装及依赖")
+    os.environ.pop("HERMES_TUI_GATEWAY_URL", None)
+    os.environ.pop("HERMES_TUI_GATEWAY_TOKEN", None)
+    async with connect_gateway() as client:
+        async def drain_events():
+            while True:
+                await client.events.get()
+        # 事件队列必须持续消费，避免长回复阻塞官方客户端的 RPC 读取。
+        drain = asyncio.create_task(drain_events())
+        try:
+            return await operate(client, request)
+        finally:
+            drain.cancel()
+            with suppress(asyncio.CancelledError):
+                await drain
+
+
+async def operate(client, request):
+    operation = request.get("op")
+    if operation == "health":
+        await client.rpc("session.list", scope="live", limit=1)
+        return {"ok": True}
+    if operation == "create":
+        snapshot = await client.rpc("session.create", source="gui", request_id=str(uuid.uuid4()), title=str(request.get("title") or "Agent Bridge"))
+        return {"ok": True, "sessionId": snapshot["session_id"]}
+    session_id = str(request.get("sessionId") or "")
+    if not session_id:
+        fail("Hermes 会话 ID 不能为空")
+    await client.rpc("session.resume", session_id=session_id)
+    if operation == "resume":
+        return {"ok": True}
+    if operation != "complete":
+        fail("不支持的 Hermes 操作")
+    text = str(request.get("task") or "")
+    images = []
+    try:
+        for item in request.get("attachments") or []:
+            if item["kind"] == "image":
+                staged = await client.rpc("image.attach_bytes", session_id=session_id,
+                                          content_base64=item["data"], filename=item["filename"])
+                if staged.get("attached") is not True:
+                    raise ValueError("图片暂存未完成")
+                images.append({"path": staged["path"], "mime": staged["mime"]})
+            elif item["kind"] == "file":
+                staged = await client.rpc("file.attach", session_id=session_id,
+                                          data_url="data:" + item["contentType"] + ";base64," + item["data"],
+                                          name=item["filename"])
+                if staged.get("attached") is not True or not staged.get("ref_text"):
+                    raise ValueError("文件暂存未完成")
+                text += "\n" + staged["ref_text"]
+            else:
+                raise ValueError("附件类型无效")
+    except Exception:
+        fail("Hermes 附件暂存失败，未提交任务，请检查桌面附件限制")
+    params = {"session_id": session_id, "text": text, "submission_id": str(uuid.uuid4())}
+    if images:
+        params["attachments"] = images
+    admission = await client.rpc("prompt.submit", **params)
+    admission_id = admission.get("admission_id")
+    if not admission_id:
+        fail("Hermes Gateway 未返回 admission_id")
+    deadline = asyncio.get_running_loop().time() + max(1, int(request.get("timeoutMs") or 1200000)) / 1000
+    while asyncio.get_running_loop().time() < deadline:
+        receipt = await client.rpc("prompt.receipt", session_id=session_id, admission_id=admission_id, include_result=True)
+        if receipt.get("status") == "terminal":
+            result = receipt.get("result") or {}
+            if receipt.get("outcome") != "completed":
+                fail("Hermes Gateway 任务未完成，请在桌面检查")
+            text = result.get("final_response")
+            if not isinstance(text, str) or not text.strip():
+                fail("Hermes Gateway 未返回文字")
+            return {"ok": True, "sessionId": session_id, "text": text}
+        await asyncio.sleep(0.5)
+    fail("Hermes Gateway 等待超时，桌面任务可能仍在运行，请在桌面检查")
+
+
+try:
+    sys.stdin.reconfigure(encoding="utf-8")
+    sys.stdout.reconfigure(encoding="utf-8")
+    raw = sys.stdin.read()
+    request = json.loads(raw)
+    print(json.dumps(asyncio.run(main(request)), ensure_ascii=False), flush=True)
+except SystemExit:
+    raise
+except Exception as exc:
+    fail("Hermes Gateway 通信失败，请在桌面检查连接与任务状态")

package/dist/src-ts/plugins/hermes/index.js

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HermesPlugin = exports.hermesManifest = void 0;
+const attachments_1 = require("../../attachments");
+const agent_task_ability_1 = require("../agent-task-ability");
+const agent_1 = require("../../agent");
+const client_1 = require("./client");
+exports.hermesManifest = {
+    id: "hermes", version: "1.0.2", displayName: "Hermes Desktop", type: "agent",
+    entry: "dist/src-ts/plugins/hermes/index.js", apiVersion: "1", process: "in-process",
+    capabilities: ["chat", "health"], configSchema: "config.schema.json",
+};
+class HermesPlugin {
+    options;
+    manifest = exports.hermesManifest;
+    abilities = [createReadinessAbility(() => this.health()), (0, agent_task_ability_1.createTaskAbility)(request => this.handle(request))];
+    sessionOperations = ["new"];
+    attachmentInput = true;
+    client;
+    failure;
+    timeoutMs = 1_200_000;
+    queue = Promise.resolve();
+    lifetime = new AbortController();
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async activate(context) {
+        this.timeoutMs = typeof context.config.timeoutMs === "number" && context.config.timeoutMs > 0 ? context.config.timeoutMs : 1_200_000;
+        const options = {
+            hermesHome: typeof context.config.hermesHome === "string" ? context.config.hermesHome : this.options.hermesHome,
+            pythonPath: typeof context.config.pythonPath === "string" ? context.config.pythonPath : this.options.pythonPath,
+            timeoutMs: this.timeoutMs,
+            transport: this.options.transport,
+        };
+        this.failure = undefined;
+        this.lifetime = new AbortController();
+        this.client = this.options.client ?? new client_1.HermesGatewayClient(options);
+        try {
+            await this.client.connect();
+        }
+        catch (error) {
+            this.failure = error instanceof Error ? error.message : String(error);
+            context.logger.warn("Hermes Gateway 连接失败", { error: this.failure });
+            this.client = undefined;
+            throw error;
+        }
+    }
+    async deactivate(_reason, _options) {
+        this.lifetime.abort(new Error("Hermes 插件已停用"));
+        this.client?.close();
+        this.client = undefined;
+    }
+    async health() {
+        try {
+            if (this.client)
+                await this.client.connect();
+        }
+        catch {
+            return { status: "failed", message: "Hermes Gateway 健康检查失败" };
+        }
+        return this.client?.connected()
+            ? { status: "ready", details: { transport: "hermes-gateway" } }
+            : { status: "failed", message: this.failure ?? "Hermes Gateway 未连接", details: { transport: "hermes-gateway" } };
+    }
+    handle(request) {
+        const signal = request.signal ? AbortSignal.any([request.signal, this.lifetime.signal]) : this.lifetime.signal;
+        const result = this.queue.then(() => this.runTask({ ...request, signal }));
+        this.queue = result.catch(() => undefined);
+        return (0, agent_1.abortable)(result, request.signal);
+    }
+    async runTask(request) {
+        (0, attachments_1.validateAttachments)(request.attachments);
+        const task = request.task?.trim() || (request.attachments?.length ? "请处理附件" : "");
+        if (!task)
+            throw new Error("消息内容不能为空");
+        request.signal?.throwIfAborted();
+        const client = this.client;
+        if (!client?.connected())
+            throw new Error("Hermes 插件未连接 Gateway");
+        request.signal?.throwIfAborted();
+        const session = await this.resolveSession(client, request, task);
+        const result = await (0, agent_1.abortable)(client.complete(task, session, request.timeoutMs ?? this.timeoutMs, request.signal, request.attachments), request.signal);
+        return { text: result.text, sessionId: result.sessionId };
+    }
+    async controlSession(request) {
+        if (request.operation !== "new")
+            throw new Error(`Hermes 不支持会话操作：${String(request.operation)}`);
+        const sessionId = request.sessionId?.trim();
+        if (!sessionId)
+            throw new Error("Hermes 新会话缺少 sessionId");
+        const client = this.client;
+        if (!client?.connected())
+            throw new Error("Hermes 插件未连接 Gateway");
+        const backendId = await client.createSession((0, client_1.sessionTitle)(request.name ?? sessionId));
+        return { text: "Hermes 已创建新会话", sessionId: backendId };
+    }
+    async resolveSession(client, request, task) {
+        if (request.newSession || !request.sessionId) {
+            return client.createSession((0, client_1.sessionTitle)(task));
+        }
+        await client.resumeSession(request.sessionId);
+        return request.sessionId;
+    }
+}
+exports.HermesPlugin = HermesPlugin;
+function createReadinessAbility(health) {
+    return {
+        definition: {
+            path: "agent/status/readiness", name: "Agent 就绪状态", summary: "读取 Hermes Desktop 当前是否就绪。", contract_revision: "1",
+            params_schema: { type: "object", properties: {}, additionalProperties: false },
+            result_schema: { type: "object", required: ["status"], properties: { status: { type: "string", enum: ["ready", "degraded", "failed"] } }, additionalProperties: false },
+            effects: ["state.read"], auth_required: true, require_confirm: true, idempotency: "keyed", allowed_modes: ["explicit"], aggregation: "none", dedupe_retention_seconds: 3600,
+        },
+        handler: async (params) => {
+            if (!params || typeof params !== "object" || Array.isArray(params) || Object.keys(params).length)
+                throw new Error("readiness 参数必须为空对象");
+            const status = (await health()).status;
+            return { status: status === "ready" || status === "failed" ? status : "degraded" };
+        },
+    };
+}
+exports.default = HermesPlugin;

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "agent-bridge-hermes",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.2",
+  "description": "mu-agent-bridge 的 Hermes 桌面原生网关插件。",
+  "keywords": [
+    "mu-agent-bridge-plugin",
+    "mu-agent-bridge-agent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://codeup.aliyun.com/6808da56fb3da14b899afd54/agent_bridge.git",
+    "directory": "packages/hermes"
+  },
+  "main": "dist/src-ts/plugins/hermes/index.js",
+  "files": [
+    "dist/",
+    "plugin.json",
+    "config.schema.json",
+    "README.md"
+  ],
+  "agentBridge": {
+    "plugin": "./plugin.json",
+    "type": "agent"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/plugin.json

@@ -0,0 +1,14 @@
+{
+  "id": "hermes",
+  "version": "1.0.2",
+  "displayName": "Hermes Desktop",
+  "type": "agent",
+  "entry": "dist/src-ts/plugins/hermes/index.js",
+  "apiVersion": "1",
+  "process": "in-process",
+  "capabilities": [
+    "chat",
+    "health"
+  ],
+  "configSchema": "config.schema.json"
+}