jishushell 0.4.24 → 0.4.30

package/dist/services/runtime/mcp-shims/searxng-shim.js

@@ -0,0 +1,125 @@
+/**
+ * SearXNG MCP shim — exported as a string for runtime drop into the
+ * Hermes container's agent-home.
+ *
+ * Why a shim instead of upstream `mcp-searxng`?
+ *
+ * The upstream `mcp-searxng` npm package's tool description and parameter
+ * surface (`Performs a web search using the SearXNG API, ideal for general
+ * queries, news, articles, and online content. Use this for broad
+ * information gathering, recent events, or when you need diverse web
+ * sources.` + `time_range: day|month|year` + `language` slot) acts as a
+ * prompt injection that nudges some LLMs (observed: MiniMax-M2.7) to:
+ *   - inject the current date (or a hallucinated past date) into the query,
+ *   - translate the query to English,
+ *   - auto-fill `time_range=day`.
+ *
+ * OpenClaw's built-in `searxng` web-search tool exposes a deliberately
+ * minimal description (`Search the web using a self-hosted SearXNG
+ * instance. Returns titles, URLs, and snippets.`) and the same model
+ * leaves the user query untouched. We mirror OpenClaw's surface here so
+ * Hermes' MCP-bound search behaves identically to OpenClaw's plugin path.
+ *
+ * The shim is pure stdio MCP (JSON-RPC 2.0 over NDJSON) implemented
+ * against Node built-ins — no npm install needed inside the runtime.
+ */
+export const SEARXNG_MCP_SHIM_VERSION = "0.1.0";
+export const SEARXNG_MCP_SHIM_SOURCE = `#!/usr/bin/env node
+// jishushell-searxng-shim — generated, do not edit by hand.
+// Source: src/services/runtime/mcp-shims/searxng-shim.ts
+import { createInterface } from "node:readline";
+
+const SEARXNG_URL = (process.env.SEARXNG_URL || "").replace(/\\/+$/, "");
+
+const TOOL = {
+  name: "searxng_web_search",
+  description: "Search the web using a self-hosted SearXNG instance. Returns titles, URLs, and snippets.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "Search query string." },
+      count: { type: "number", description: "Number of results to return (1-10).", minimum: 1, maximum: 10 },
+      categories: { type: "string", description: "Optional comma-separated categories such as general, news, or science." },
+      language: { type: "string", description: "Optional language code such as en, de, or fr." }
+    },
+    required: ["query"]
+  }
+};
+
+function send(msg) { process.stdout.write(JSON.stringify(msg) + "\\n"); }
+function reply(id, result) { if (id != null) send({ jsonrpc: "2.0", id, result }); }
+function replyError(id, code, message) { if (id != null) send({ jsonrpc: "2.0", id, error: { code, message } }); }
+
+async function callSearch(args) {
+  if (!SEARXNG_URL) throw new Error("SEARXNG_URL env not set");
+  const query = String(args?.query ?? "").trim();
+  if (!query) throw new Error("query is required");
+  const count = Math.max(1, Math.min(10, Number(args?.count) || 5));
+  const url = new URL("/search", SEARXNG_URL);
+  url.searchParams.set("q", query);
+  url.searchParams.set("format", "json");
+  if (args?.categories) url.searchParams.set("categories", String(args.categories));
+  if (args?.language) url.searchParams.set("language", String(args.language));
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), 20000);
+  let resp;
+  try {
+    resp = await fetch(url.toString(), {
+      method: "GET",
+      headers: { Accept: "application/json" },
+      signal: ctrl.signal
+    });
+  } finally {
+    clearTimeout(t);
+  }
+  if (!resp.ok) throw new Error("SearXNG " + resp.status + " " + resp.statusText);
+  const body = await resp.json();
+  const raw = Array.isArray(body?.results) ? body.results : [];
+  const results = raw.slice(0, count).map((r) => ({
+    title: typeof r?.title === "string" ? r.title : "",
+    url: typeof r?.url === "string" ? r.url : "",
+    snippet: typeof r?.content === "string" ? r.content : ""
+  }));
+  return { query, count: results.length, results };
+}
+
+async function handle(req) {
+  const { id, method, params } = req || {};
+  try {
+    if (method === "initialize") {
+      reply(id, {
+        protocolVersion: "2024-11-05",
+        capabilities: { tools: {} },
+        serverInfo: { name: "jishushell-searxng-shim", version: "${SEARXNG_MCP_SHIM_VERSION}" }
+      });
+    } else if (method === "notifications/initialized") {
+      // notification, no reply
+    } else if (method === "tools/list") {
+      reply(id, { tools: [TOOL] });
+    } else if (method === "tools/call") {
+      if (params?.name !== TOOL.name) throw new Error("unknown tool: " + params?.name);
+      const data = await callSearch(params?.arguments ?? {});
+      reply(id, { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] });
+    } else if (method === "ping") {
+      reply(id, {});
+    } else {
+      replyError(id, -32601, "method not found: " + method);
+    }
+  } catch (e) {
+    replyError(id, -32000, (e && e.message) ? e.message : String(e));
+  }
+}
+
+const rl = createInterface({ input: process.stdin });
+rl.on("line", (line) => {
+  const t = line.trim();
+  if (!t) return;
+  let req;
+  try { req = JSON.parse(t); } catch { return; }
+  handle(req);
+});
+
+process.on("SIGTERM", () => process.exit(0));
+process.on("SIGINT", () => process.exit(0));
+`;
+//# sourceMappingURL=searxng-shim.js.map

package/dist/services/runtime/mcp-shims/searxng-shim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"searxng-shim.js","sourceRoot":"","sources":["../../../../src/services/runtime/mcp-shims/searxng-shim.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,MAAM,CAAC,MAAM,wBAAwB,GAAG,OAAO,CAAC;AAEhD,MAAM,CAAC,MAAM,uBAAuB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mEAkE4B,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+B1F,CAAC"}

package/dist/services/runtime/mcp-shims/write-mcp-entry.d.ts

@@ -0,0 +1,83 @@
+/**
+ * writeMcpEntry — adapter helper that materializes the MCP firewall
+ * (see firewall.ts) into an instance's agent-home and returns the
+ * `mcp_servers.<X>` block the adapter should write into its own config.
+ *
+ * Called by adapters from `applyConnectionEnv` (PR 8 / docs §17.3.3).
+ *
+ * Side effects on the host filesystem:
+ *   - <agentHomeDir>/__mcp_shims__/<capabilityId>/firewall.mjs
+ *   - <agentHomeDir>/__mcp_shims__/<capabilityId>/config.json
+ *   - chown both to serviceUser if provided (best-effort)
+ *
+ * Pure return value (the adapter applies it to its own config schema):
+ *   {
+ *     command: "node",
+ *     args: ["<containerHomeDir>/__mcp_shims__/<id>/firewall.mjs",
+ *            "--config",
+ *            "<containerHomeDir>/__mcp_shims__/<id>/config.json"],
+ *     env: {}     // upstream env is encoded in config.json — keep adapter env clean
+ *   }
+ *
+ * The adapter is responsible for:
+ *   - Adding `enabled: true` (or whatever flag its config schema needs).
+ *   - Picking the `mcp_servers` map key (typically capabilityId).
+ */
+import type { ToolSchema } from "../../../types.js";
+export interface WriteMcpEntryArgs {
+    /** Host-side path where the agent's home directory lives. */
+    agentHomeDir: string;
+    /**
+     * Container-side equivalent of agentHomeDir — used to compose the
+     * absolute path the agent process will exec. For Hermes that's
+     * `/opt/data` (HERMES_CONTAINER_HOME).
+     */
+    containerHomeDir: string;
+    /** Capability ID (e.g. "search-searxng"); also used as the on-disk subdir. */
+    capabilityId: string;
+    /** Canonical tool surface — copied into config.json verbatim. */
+    toolSchema: ToolSchema;
+    /**
+     * Resolved upstream env for this binding — values are already substituted
+     * from connection-resolver outputs (no `${...}` placeholders left).
+     */
+    upstreamEnv: Record<string, string>;
+    /** Best-effort chown so the in-container process can read the files. */
+    serviceUser?: {
+        uid: number;
+        gid: number;
+    };
+}
+export interface WriteMcpEntryResult {
+    /** Command to put under `mcp_servers.<key>.command`. */
+    command: string;
+    /** Args to put under `mcp_servers.<key>.args`. */
+    args: string[];
+    /**
+     * Env to put under `mcp_servers.<key>.env`. Always empty — upstream
+     * env is funneled through firewall config.json so adapter config
+     * stays minimal. Adapters should still write this key so any prior
+     * env entries get cleared on overwrite.
+     */
+    env: Record<string, string>;
+}
+export declare function writeMcpEntry(args: WriteMcpEntryArgs): WriteMcpEntryResult;
+/**
+ * Resolve `${SLOT}` placeholders in an `env_template` against a flat
+ * env map (typically the env that connection-resolver returned).
+ *
+ * Suffix forms:
+ *   ${NAME_ORIGIN}  → parsed URL with /search stripped, returns
+ *                     scheme://host:port (no path, no trailing slash).
+ *   ${NAME}         → verbatim env value.
+ *
+ * Note: this returns the host:port as the registry resolved at the time
+ * the consumer's PUT /connections was processed. To keep this fresh
+ * across host IP changes, the framework re-runs adapter.applyConnectionEnv
+ * before each instance start (see nomad-manager.phaseRefreshConnections,
+ * §17/PR 9). That re-render path passes a fresh env map here.
+ *
+ * Unresolved placeholders are left as-is (caller can decide whether to
+ * fail or pass through).
+ */
+export declare function resolveEnvTemplate(template: Record<string, string> | undefined, envSource: Record<string, string>): Record<string, string>;

package/dist/services/runtime/mcp-shims/write-mcp-entry.js

@@ -0,0 +1,127 @@
+/**
+ * writeMcpEntry — adapter helper that materializes the MCP firewall
+ * (see firewall.ts) into an instance's agent-home and returns the
+ * `mcp_servers.<X>` block the adapter should write into its own config.
+ *
+ * Called by adapters from `applyConnectionEnv` (PR 8 / docs §17.3.3).
+ *
+ * Side effects on the host filesystem:
+ *   - <agentHomeDir>/__mcp_shims__/<capabilityId>/firewall.mjs
+ *   - <agentHomeDir>/__mcp_shims__/<capabilityId>/config.json
+ *   - chown both to serviceUser if provided (best-effort)
+ *
+ * Pure return value (the adapter applies it to its own config schema):
+ *   {
+ *     command: "node",
+ *     args: ["<containerHomeDir>/__mcp_shims__/<id>/firewall.mjs",
+ *            "--config",
+ *            "<containerHomeDir>/__mcp_shims__/<id>/config.json"],
+ *     env: {}     // upstream env is encoded in config.json — keep adapter env clean
+ *   }
+ *
+ * The adapter is responsible for:
+ *   - Adding `enabled: true` (or whatever flag its config schema needs).
+ *   - Picking the `mcp_servers` map key (typically capabilityId).
+ */
+import { chownSync, mkdirSync, writeFileSync } from "fs";
+import { dirname, join, posix } from "path";
+import { MCP_FIREWALL_SOURCE } from "./firewall.js";
+const SHIM_ROOT = "__mcp_shims__";
+const FIREWALL_FILENAME = "firewall.mjs";
+const CONFIG_FILENAME = "config.json";
+export function writeMcpEntry(args) {
+    const { agentHomeDir, containerHomeDir, capabilityId, toolSchema, upstreamEnv, serviceUser, } = args;
+    const hostShimDir = join(agentHomeDir, SHIM_ROOT, capabilityId);
+    const hostFirewall = join(hostShimDir, FIREWALL_FILENAME);
+    const hostConfig = join(hostShimDir, CONFIG_FILENAME);
+    mkdirSync(hostShimDir, { recursive: true });
+    // Drop firewall source. Mode 0o755 so the in-container service user
+    // (which may not match host UID via every chown path) can still read+exec.
+    writeFileSync(hostFirewall, MCP_FIREWALL_SOURCE, { mode: 0o755 });
+    // Build firewall config
+    const config = {
+        capability_id: capabilityId,
+        tool_schema: {
+            name: toolSchema.name,
+            description: toolSchema.description,
+            // Stored under `inputSchema` so firewall doesn't have to alias.
+            inputSchema: toolSchema.parameters,
+        },
+        upstream: {
+            command: toolSchema.upstream.command,
+            args: toolSchema.upstream.args ?? [],
+            env: upstreamEnv,
+        },
+        wrap_outputs: toolSchema.wrap_outputs !== false,
+    };
+    writeFileSync(hostConfig, JSON.stringify(config, null, 2), { mode: 0o644 });
+    if (serviceUser) {
+        try {
+            chownSync(dirname(hostFirewall), serviceUser.uid, serviceUser.gid);
+            chownSync(hostFirewall, serviceUser.uid, serviceUser.gid);
+            chownSync(hostConfig, serviceUser.uid, serviceUser.gid);
+        }
+        catch {
+            /* best-effort — files are world-readable */
+        }
+    }
+    // Build container-side absolute path. Always POSIX-style — container
+    // OSes are Linux even when host is not.
+    const containerShimDir = posix.join(containerHomeDir, SHIM_ROOT, capabilityId);
+    return {
+        command: "node",
+        args: [
+            posix.join(containerShimDir, FIREWALL_FILENAME),
+            "--config",
+            posix.join(containerShimDir, CONFIG_FILENAME),
+        ],
+        env: {},
+    };
+}
+/**
+ * Resolve `${SLOT}` placeholders in an `env_template` against a flat
+ * env map (typically the env that connection-resolver returned).
+ *
+ * Suffix forms:
+ *   ${NAME_ORIGIN}  → parsed URL with /search stripped, returns
+ *                     scheme://host:port (no path, no trailing slash).
+ *   ${NAME}         → verbatim env value.
+ *
+ * Note: this returns the host:port as the registry resolved at the time
+ * the consumer's PUT /connections was processed. To keep this fresh
+ * across host IP changes, the framework re-runs adapter.applyConnectionEnv
+ * before each instance start (see nomad-manager.phaseRefreshConnections,
+ * §17/PR 9). That re-render path passes a fresh env map here.
+ *
+ * Unresolved placeholders are left as-is (caller can decide whether to
+ * fail or pass through).
+ */
+export function resolveEnvTemplate(template, envSource) {
+    if (!template)
+        return {};
+    const out = {};
+    for (const [key, raw] of Object.entries(template)) {
+        out[key] = raw.replace(/\$\{([A-Z0-9_]+)\}/g, (_m, name) => {
+            if (name.endsWith("_ORIGIN")) {
+                const baseName = name.slice(0, -"_ORIGIN".length);
+                const baseVal = envSource[baseName];
+                if (typeof baseVal === "string" && baseVal) {
+                    try {
+                        const u = new URL(baseVal);
+                        if (u.pathname === "/search" || u.pathname === "/search/")
+                            u.pathname = "";
+                        return u.toString().replace(/\/$/, "");
+                    }
+                    catch {
+                        return baseVal;
+                    }
+                }
+                return _m;
+            }
+            const val = envSource[name];
+            return typeof val === "string" ? val : _m;
+        });
+    }
+    return out;
+}
+//# sourceMappingURL=write-mcp-entry.js.map

package/dist/services/runtime/mcp-shims/write-mcp-entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-mcp-entry.js","sourceRoot":"","sources":["../../../../src/services/runtime/mcp-shims/write-mcp-entry.ts"],"names":[],"mappings":"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"}

package/dist/services/runtime/migrations.d.ts

@@ -12,4 +12,12 @@
  *
  * This file is framework-level and must never import adapter code.
  */
+import type { AppSpec } from "../../types.js";
 export declare function backfillInstanceMeta<T extends Record<string, any>>(raw: T | null | undefined): T | null;
+/**
+ * Return a synthetic capability-only spec for a legacy instance based on
+ * its agentType. Returns null when the agent type has no known template
+ * (e.g. raw `custom` agents). Cached per-agentType — templates ship with
+ * the panel and don't change at runtime.
+ */
+export declare function loadCapabilitySpecForLegacyInstance(meta: Record<string, any> | null): AppSpec | null;

package/dist/services/runtime/migrations.js

@@ -12,6 +12,10 @@
  *
  * This file is framework-level and must never import adapter code.
  */
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { fileURLToPath } from "url";
+import { parse } from "yaml";
 import { resolveAgentType } from "./instance.js";
 export function backfillInstanceMeta(raw) {
     if (!raw)
@@ -22,4 +26,100 @@ export function backfillInstanceMeta(raw) {
         mut.agentType = agentType;
     return raw;
 }
+// ── Capability discovery for legacy instances ──────────────────────────────
+//
+// PR 1+2 introduced the capability registry / app-spec contract. Legacy
+// hermes/openclaw instances created via the old "新建实例" flow only carry
+// `instance.json` — they have no `app-spec.yaml`, no `manifest.json`, and
+// no `app_id`. The Connections endpoint then early-returns
+// `{requires:[], connections:{}, pending:[]}` and the UI shows "此应用没
+// 有需要绑定的能力。" even though every hermes/openclaw runtime *should*
+// expose the standard llm/search/browser/mcp slots.
+//
+// We deliberately do NOT write any files for these instances:
+//
+//   - The shipped templates (`apps/openclaw-container.yaml`,
+//     `apps/hermes-container.yaml`) describe a *container* runtime
+//     (image / args / ports). Legacy instances may run as raw_exec on a
+//     local binary instead, with their real runtime in
+//     `instance.json#runtime`. Persisting the container spec would
+//     cause `nomad-manager.startAppJob(spec, ...)` to rebuild the job
+//     from the wrong runtime shape on next start, losing volume mounts
+//     and per-instance customisation.
+//
+//   - The Connections feature only needs `spec.requires` (and a stable
+//     `spec.id`) to populate the UI. We can synthesize that in-memory
+//     from the matching template every time the Connections route is
+//     hit. There is no state to drift, nothing to migrate, nothing to
+//     undo.
+//
+// The synthetic spec returned by `loadCapabilitySpecForLegacyInstance`
+// is therefore pruned to capability metadata only. Service routes
+// (start / stop / restart) keep going through the legacy
+// `svc.startInstance` path because `meta.app_id` stays unset — the
+// runtime continues to come from `instance.json`.
+const TEMPLATE_BY_AGENT_TYPE = {
+    hermes: "hermes-container.yaml",
+    openclaw: "openclaw-container.yaml",
+};
+function resolveTemplatePath(templateName) {
+    const candidates = [
+        fileURLToPath(new URL(`../../../apps/${templateName}`, import.meta.url)),
+        join(process.cwd(), "apps", templateName),
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+const specCache = new Map();
+/**
+ * Return a synthetic capability-only spec for a legacy instance based on
+ * its agentType. Returns null when the agent type has no known template
+ * (e.g. raw `custom` agents). Cached per-agentType — templates ship with
+ * the panel and don't change at runtime.
+ */
+export function loadCapabilitySpecForLegacyInstance(meta) {
+    if (!meta)
+        return null;
+    const agentType = typeof meta.agentType === "string" && meta.agentType
+        ? meta.agentType
+        : resolveAgentType(meta);
+    const templateName = TEMPLATE_BY_AGENT_TYPE[agentType];
+    if (!templateName)
+        return null;
+    if (specCache.has(agentType)) {
+        return specCache.get(agentType) ?? null;
+    }
+    const templatePath = resolveTemplatePath(templateName);
+    if (!templatePath) {
+        specCache.set(agentType, null);
+        return null;
+    }
+    try {
+        const raw = parse(readFileSync(templatePath, "utf-8"));
+        // Strip runtime — Connections only needs id/name/requires/provides.
+        // Leaving `tasks` in would tempt callers to (re)build a nomad job
+        // from a spec that doesn't match the instance's actual runtime.
+        const synthetic = {
+            id: raw.id,
+            name: raw.name,
+            version: raw.version,
+            agentType: raw.agentType,
+            description: raw.description,
+            singleInstance: raw.singleInstance,
+            tasks: [],
+            provides: raw.provides ?? [],
+            requires: raw.requires ?? [],
+        };
+        specCache.set(agentType, synthetic);
+        return synthetic;
+    }
+    catch (e) {
+        console.warn(`[migration] cannot load capability template '${templateName}': ${e.message}`);
+        specCache.set(agentType, null);
+        return null;
+    }
+}
 //# sourceMappingURL=migrations.js.map

package/dist/services/runtime/migrations.js.map

@@ -1 +1 @@
-{"version":3,"file":"migrations.js","sourceRoot":"","sources":["../../../src/services/runtime/migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjD,MAAM,UAAU,oBAAoB,CAClC,GAAyB;IAEzB,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,MAAM,SAAS,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACxC,MAAM,GAAG,GAAG,GAA0B,CAAC;IACvC,IAAI,GAAG,CAAC,SAAS,KAAK,SAAS;QAAE,GAAG,CAAC,SAAS,GAAG,SAAS,CAAC;IAC3D,OAAO,GAAG,CAAC;AACb,CAAC"}
+{"version":3,"file":"migrations.js","sourceRoot":"","sources":["../../../src/services/runtime/migrations.ts"],"names":[],"mappings":"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"}

package/dist/services/runtime/types.d.ts

@@ -354,6 +354,21 @@ export interface RuntimeAdapter {
     }>;
     /** Return the list of other instance IDs that share this one's agent-home. */
     findInstancesSharingHome?(instanceId: string): string[];
+    /**
+     * Translate a flat env map (`{SEARCH_API_BASE_URL, OPENAI_API_BASE_URL,
+     * MCP_SERVERS, ...}`) — produced by `connection-resolver` from the
+     * user's persisted bindings — into adapter-native config writes
+     * (Hermes' `mcp_servers` in config.yaml, OpenClaw's
+     * `plugins.entries.searxng.config.webSearch.baseUrl` in openclaw.json,
+     * etc.). Called both at PUT /connections time AND on every instance
+     * start (PR 9 phaseRefreshConnections), so host IP changes /
+     * provider redeployments propagate without a manual re-bind.
+     *
+     * Adapters are free to no-op for env keys they don't recognize.
+     * Failures should be logged but NOT thrown — start should proceed
+     * with whatever config is on disk.
+     */
+    applyConnectionEnv?(instanceId: string, env: Record<string, string>): Promise<void>;
     /** Resolve the canonical agent binary path (OpenClaw only). */
     resolveBin?(): string;
     /** Resolve the instance's on-disk config file path. */

package/dist/services/setup-manager.js

@@ -579,7 +579,7 @@ async function installDockerWithTask(task) {
     try {
         emitTask(task, { type: "progress", message: "开始安装 Docker...", progress: 0 });
         const user = execSync("whoami", { encoding: "utf-8", timeout: 5000 }).trim();
-        // ── 尝试 get.docker.com 便捷脚本 ──────────────────────────────
+        // ── Try the get.docker.com convenience script ─────────────────
         emitTask(task, { type: "log", message: "下载 Docker 安装脚本..." });
         emitTask(task, { type: "progress", message: "下载中...", progress: 5 });
         // Unique temp path prevents TOCTOU: another user can't swap a fixed /tmp/get-docker.sh
@@ -617,10 +617,10 @@ async function installDockerWithTask(task) {
         else {
             emitTask(task, { type: "log", message: "下载便捷脚本失败，尝试 apt 仓库方式..." });
         }
-        // ── 回退: apt 仓库手动安装 (兼容 Debian trixie 等预发行版) ────
+        // ── Fallback: apt-repo manual install (handles Debian trixie pre-releases) ─
         if (!scriptOk) {
             emitTask(task, { type: "progress", message: "通过 apt 仓库安装 Docker...", progress: 15 });
-            // 检测系统 ID 和版本代号，对 trixie/sid 等降级至 bookworm
+            // Detect system ID + codename; downgrade trixie/sid to bookworm.
             let codename = "bookworm";
             let repoOs = "debian";
             try {
@@ -629,7 +629,7 @@ async function installDockerWithTask(task) {
                 const distroId = (osRelease.match(/^ID=(.+)$/m)?.[1] || "debian").trim();
                 const raw = (codenameMatch?.[1] || "").trim();
                 repoOs = (distroId === "ubuntu") ? "ubuntu" : "debian";
-                // Debian testing/unstable: trixie, sid → 使用上一个稳定版仓库
+                // Debian testing/unstable (trixie, sid) → use the previous stable repo.
                 const unstableCodenames = new Set(["trixie", "forky", "sid", "unstable", "testing"]);
                 const ubuntuFallback = "noble";
                 if (distroId === "ubuntu" && unstableCodenames.has(raw)) {
@@ -671,7 +671,7 @@ async function installDockerWithTask(task) {
                 }
             }
         }
-        // ── 收尾 ───────────────────────────────────────────────────────
+        // ── Wrap up ────────────────────────────────────────────────────
         emitTask(task, { type: "progress", message: "配置用户权限...", progress: 90 });
         try {
             execFileSync("sudo", ["groupadd", "docker"], { timeout: 10000 });
@@ -693,7 +693,7 @@ async function installDockerWithTask(task) {
             emitTask(task, { type: "log", message: "已启用内存 cgroup（需要重启生效，Docker 内存统计才会正常）" });
         }
         const version = getDockerVersionLine(10000);
-        // 用 sudo docker 验证 daemon（当前用户还未加入 docker 组时需要 sudo）
+        // Verify the daemon via `sudo docker` (needed when the current user is not in the docker group yet).
         const daemonOk = canAccessDockerDaemon(10000);
         if (daemonOk) {
             const doneMsg = needsReboot