jishushell 0.6.18 → 0.7.3

package/dist/services/integrations/openclaw/integration.js

@@ -40,7 +40,7 @@ import { accessSync, chmodSync, chownSync, copyFileSync, cpSync, constants, exis
 import { createHash, randomBytes } from "crypto";
 import { homedir, userInfo } from "os";
 import { delimiter, dirname, join, resolve as pathResolve } from "path";
-import { getNomadDriver, getOpenclawDockerImage, JISHUSHELL_HOME, getCoreLanHost, getCorePort, } from "../../../config.js";
+import { getNomadDriver, getOpenclawDockerImage, JISHUSHELL_HOME, getCoreLanHost, getCorePort, getInternalMcpToken, } from "../../../config.js";
 import { ensureDirContainer, ensureDirHost, writeConfigFile } from "../../../utils/fs.js";
 import { safeWriteJson } from "../../../utils/safe-json.js";
 import { chownToServiceUser, getInstance, getRuntimeEnvFiles, listInstances, normalizePath, notifyConfigChange, resolveServiceUser, updateInstanceMeta, updateEnvFile, } from "../../instances/manager.js";
@@ -57,7 +57,8 @@ import { resolveNomadJobId } from "../../runtime/job-id.js";
 import { DEFINITION_FILENAME, MANIFEST_FILENAME, RESOLVED_SPEC_FILENAME, } from "../../app-common/paths.js";
 import { registerIntegration } from "../registry.js";
 import { isOwnedByInstance, writeOwnershipMarker } from "../../runtime/ownership-marker.js";
-import { mcporterPath, mergeMcporterServers, removeMcporterServers } from "./mcporter.js";
+import { mcporterPath, removeMcporterServers } from "./mcporter.js";
+import { removeOpenclawMcpServers, upsertOpenclawMcpServer, } from "./native-mcp.js";
 // ── Constants physically migrated from the Nomad driver ───────────────
 //
 // These used to live as module-scope constants in the Nomad driver and were
@@ -243,12 +244,6 @@ function listMountedHostPaths(runtime) {
     }
     return list;
 }
-function listJishukbUploadRoots(runtime, openclawHome) {
-    return Array.from(new Set([
-        ...listMountedHostPaths(runtime),
-        join(openclawHome, ".openclaw", "media", "inbound"),
-    ]));
-}
 // ── Path helpers (physically migrated from instance-manager.ts) ───────
 const INSTANCE_OPENCLAW_HOME_DIRNAME = "openclaw-home";
 const INSTANCE_MODEL_ENV_FILENAME = "model.env";
@@ -1259,16 +1254,22 @@ export function clearBrowserlessConnectionFromConfig(configPath) {
  *                  surface.
  *   2026.6.12.1 — Browserless site-side anti-bot classification rule:
  *                  site WAF/captcha blocks are not Browser Allowlist misses.
+ *   2026.6.24.1 — Immich MCP routing rule in TOOLS.md: photo-library
+ *                  requests must use the injected immich.* tools instead of
+ *                  probing docker, ports, or host directories from inside
+ *                  the OpenClaw container.
  *
  * Format: YYYY.M.D.N (date + same-day bump counter). Compare as strings;
  * any difference means rotate. Stored per-instance at
  *   `<instanceDir>/runtime-contract.txt`
  */
-const RUNTIME_CONTRACT_VERSION = "2026.6.12.1";
+const RUNTIME_CONTRACT_VERSION = "2026.6.24.1";
 const JISHUSHELL_DRIVE_HINT_BEGIN = "<!-- jishushell-drive: BEGIN auto-generated -->";
 const JISHUSHELL_DRIVE_HINT_END = "<!-- jishushell-drive: END -->";
 const JISHUSHELL_KB_HINT_BEGIN = "<!-- jishushell-kb: BEGIN auto-generated -->";
 const JISHUSHELL_KB_HINT_END = "<!-- jishushell-kb: END -->";
+const JISHUSHELL_IMMICH_HINT_BEGIN = "<!-- jishushell-immich: BEGIN auto-generated -->";
+const JISHUSHELL_IMMICH_HINT_END = "<!-- jishushell-immich: END -->";
 const JISHUSHELL_BROWSERLESS_HINT_BEGIN = "<!-- jishushell-browserless: BEGIN auto-generated -->";
 const JISHUSHELL_BROWSERLESS_HINT_END = "<!-- jishushell-browserless: END -->";
 /**
@@ -1652,6 +1653,21 @@ export async function resolveJishukbDefaultKbIdForOpenClaw(baseUrl, configuredKb
         return "";
     }
 }
+function rewriteJishukbMcpUrlForOpenClawRuntime(url, runtime) {
+    if (!runtime?.image)
+        return url;
+    try {
+        const parsed = new URL(url);
+        if (["127.0.0.1", "localhost", "0.0.0.0", "::1", "[::1]"].includes(parsed.hostname)) {
+            parsed.hostname = "host.docker.internal";
+            return parsed.toString();
+        }
+    }
+    catch {
+        return url;
+    }
+    return url;
+}
 /**
  * Per-provider kb-shim residue cleanup. Wipes the shim source (replacing
  * the bytes with a removal marker rather than `unlink`-ing — the latter
@@ -1696,7 +1712,7 @@ export function wipeKbShimDir(integrationHome, which) {
         catch { /* best effort */ }
     }
 }
-export function patchToolsMdKbHint(workspaceDir, mode, provider, mcporterCommand = "mcporter", instanceId, mediaInboundRoot) {
+export function patchToolsMdKbHint(workspaceDir, mode, provider, mcporterCommand = "mcporter", instanceId, mediaInboundRoot, unavailableReason) {
     try {
         const toolsPath = join(workspaceDir, "TOOLS.md");
         let original = "";
@@ -1721,6 +1737,30 @@ export function patchToolsMdKbHint(workspaceDir, mode, provider, mcporterCommand
                 return;
             next = stripped;
         }
+        else if (mode === "unavailable") {
+            const reason = typeof unavailableReason === "string" && unavailableReason.trim()
+                ? unavailableReason.trim().replace(/\s+/g, " ").slice(0, 500)
+                : "native MCP is not registered";
+            const section = [
+                JISHUSHELL_KB_HINT_BEGIN,
+                "",
+                "### 📚 知识库（JishuShell-KB）暂不可用",
+                "",
+                "OpenClaw 已绑定 **JishuShell-KB**，但 JishuShell 当前没有检测到可用的 **native MCP** 服务，所以本轮不能调用 `kb.*` 工具。",
+                "",
+                `**检测原因**：${reason}`,
+                "",
+                "**必须这样处理**：",
+                "- 不要声称已经检索过知识库，也不要尝试使用旧 shim、mcporter 或自己拼 HTTP 请求。",
+                "- 如果用户要查询、上传或管理知识库，直接提醒用户：需要升级 JishuShell-KB 到包含 remote MCP 的版本，并确认 `JISHU_KB_MCP_HTTP` / MCP auth 已配置后重启 OpenClaw。",
+                "- 在 native MCP 恢复前，知识库能力视为不可用。",
+                "",
+                JISHUSHELL_KB_HINT_END,
+                "",
+            ].join("\n");
+            const sep = stripped && !stripped.endsWith("\n") ? "\n\n" : "\n";
+            next = (stripped ? stripped + sep : "") + section;
+        }
         else {
             if (!provider) {
                 throw new Error("provider is required when installing KB hint");
@@ -1730,43 +1770,62 @@ export function patchToolsMdKbHint(workspaceDir, mode, provider, mcporterCommand
                 ? `agent-data/${instanceId}/outbox/report.md`
                 : "agent-data/<instance>/outbox/report.md";
             const attachmentInboxPath = mediaInboundRoot || "<openclawHome>/.openclaw/media/inbound";
+            const nativeKbTool = (name) => `kb__${name}`;
             const section = provider === "jishukb"
                 ? [
                     JISHUSHELL_KB_HINT_BEGIN,
                     "",
                     "### 📚 知识库（JishuShell-KB）",
                     "",
-                    "用户长期投递并已经导入到 **JishuShell-KB** 的文档（手册、PDF、内部笔记、会议纪要等）可以检索；你也可以列知识库、创建知识库、把 drive 文件上传入库、查看已索引文档、查看 handbook、读取**脱敏后的**当前配置，以及在用户明确确认时删除文档/知识库。",
+                    "用户长期投递并已经导入到 **JishuShell-KB** 的文档（手册、PDF、内部笔记、会议纪要等）可以检索；你也可以列知识库、创建知识库、把 drive 文件或 URL 上传入库、查看已索引文档/分块/原文/FAQ、查看 ingest job、查看 handbook、读取**脱敏后的**当前配置，以及在用户明确确认时执行删除/重索引/取消任务。",
+                    "",
+                    "这些能力由 OpenClaw native MCP 暴露；直接调用 `kb__*` 工具，不要通过 shell、mcporter 或手写 HTTP 请求访问 KB。",
                     "",
                     "**当前 provider 暴露的工具**：",
                     "",
-                    `- \`${cli} call kb.kb_list\` — 列出所有知识库（拿 id / name / chunks 数）`,
-                    `- \`${cli} call kb.kb_create name="产品文档" description="可选"\` — 新建知识库`,
-                    `- \`${cli} call kb.kb_search query="<用户原话>" kbId=<可选> topK=<可选>\` — 检索指定或默认知识库`,
-                    `- \`${cli} call kb.kb_upload path="<drive_resolve_local_path 返回的绝对路径>" kbId="<目标知识库 id>"\` — 上传并索引文件到指定知识库`,
-                    `- \`${cli} call kb.kb_list_documents kbId=<可选>\` — 列出指定或默认知识库里的已索引文档`,
-                    `- \`${cli} call kb.kb_read_handbook section="设置 → 知识库"\` — 读取 handbook 全文或指定章节`,
-                    `- \`${cli} call kb.kb_get_config\` — 读取当前**脱敏后的**知识库配置摘要`,
-                    `- \`${cli} call kb.kb_delete_document kbId="<知识库 id>" documentId="<文档 id>" confirmDocumentId="<同一个文档 id>"\` — 删除文档（危险操作，必须显式确认）`,
-                    `- \`${cli} call kb.kb_delete_kb kbId="<知识库 id>" confirmKbId="<同一个知识库 id>"\` — 删除知识库（危险操作，必须显式确认）`,
+                    `- \`${nativeKbTool("kb_list")}\` — 列出所有知识库（拿 id / name / documents 文件数 / chunks 分块数；用户问“几个文件”时看 documents，不要用 chunks）`,
+                    `- \`${nativeKbTool("kb_get_capabilities")}\` — 查看 KB 当前支持的外部控制能力、上传格式和限制（不含密钥）`,
+                    `- \`${nativeKbTool("kb_create")}\` — 新建知识库`,
+                    `- \`${nativeKbTool("kb_get")}\` — 查看某个知识库的元数据、文件数、分块数、任务数和安全配置摘要`,
+                    `- \`${nativeKbTool("kb_search")}\` — 检索指定或默认知识库`,
+                    `- \`${nativeKbTool("kb_upload")}\` — 上传并索引文件到指定知识库`,
+                    `- \`${nativeKbTool("kb_import_url")}\` — 抓取可读 URL 并入库，默认异步返回 job`,
+                    `- \`${nativeKbTool("kb_list_documents")}\` — 列出指定或默认知识库里的已索引文档`,
+                    `- \`${nativeKbTool("kb_get_document")}\` — 查看单个文档的元数据和派生计数`,
+                    `- \`${nativeKbTool("kb_list_document_chunks")}\` — 查看某个文档的索引分块（文本会截断）`,
+                    `- \`${nativeKbTool("kb_read_document_raw")}\` — 读取某个文档的原始存储文本（仅在用户要看原文时用，输出会截断）`,
+                    `- \`${nativeKbTool("kb_list_document_faq")}\` — 查看某个文档生成的 FAQ 建议`,
+                    `- \`${nativeKbTool("kb_reindex_document")}\` — 重建文档索引（写操作，必须显式确认）`,
+                    `- \`${nativeKbTool("kb_list_jobs")}\` — 查看导入/索引任务`,
+                    `- \`${nativeKbTool("kb_get_job")}\` — 查看单个任务状态`,
+                    `- \`${nativeKbTool("kb_retry_job")}\` — 重试失败/取消的任务（仅在用户要求时用）`,
+                    `- \`${nativeKbTool("kb_cancel_job")}\` — 取消任务（必须显式确认）`,
+                    `- \`${nativeKbTool("kb_read_handbook")}\` — 读取 handbook 全文或指定章节`,
+                    `- \`${nativeKbTool("kb_get_config")}\` — 读取当前**脱敏后的**知识库配置摘要`,
+                    `- \`${nativeKbTool("kb_delete_document")}\` — 删除文档（危险操作，必须显式确认）`,
+                    `- \`${nativeKbTool("kb_delete_kb")}\` — 删除知识库（危险操作，必须显式确认）`,
                     "",
                     "**推荐调用顺序**：",
-                    "1. 用户提到“某个指定知识库 / 某个库里”但你不知道 id → 先 `kb_list`。",
-                    "2. 用户要把 drive 里的文件加入知识库 → 先 `drive_resolve_local_path`，再 `kb_upload path=<abs_path> kbId=<显式 id>`。",
-                    `3. 用户当前消息已经附了文件，而且消息里给了宿主机绝对路径（通常在 \`${attachmentInboxPath}/...\`）→ 直接把这个绝对路径传给 \`kb_upload\`；不要先把内容重写到 \`files/\` 根目录，也不要自己猜 \`agent-data/agent1/...\` 这种路径。`,
-                    `4. 用户要上传你**新生成**的文件 → 先 \`drive_write_text\` / \`drive_write_binary\` 到 \`${generatedOutboxPath}\`，再 \`drive_resolve_local_path\` → \`kb_upload\`。`,
-                    "5. 用户要新建库并马上上传 → `kb_create` → 记住返回的 id → `kb_upload`。",
-                    "6. 用户要解释某个设置项怎么用 → 先 `kb_read_handbook`，必要时再 `kb_get_config` 看当前值。",
+                    `1. 用户问“知识库里有几个文件 / 包含哪些文件” → 先 \`${nativeKbTool("kb_list_documents")}\`；如果不知道 kbId，先 \`${nativeKbTool("kb_list")}\`，再对目标库调用 \`${nativeKbTool("kb_list_documents")}\`。文件数按 documents 或 list_documents 返回数组长度计算，不要按 chunks 计算。`,
+                    `2. 用户提到“某个指定知识库 / 某个库里”但你不知道 id → 先 \`${nativeKbTool("kb_list")}\`。`,
+                    `3. 用户要把 drive 里的文件加入知识库 → 先解析本地路径，再调用 \`${nativeKbTool("kb_upload")}\`，并显式传目标 kbId。`,
+                    `4. 用户当前消息已经附了文件，而且消息里给了宿主机绝对路径（通常在 \`${attachmentInboxPath}/...\`）→ 直接把这个绝对路径传给 \`${nativeKbTool("kb_upload")}\`；不要先把内容重写到 \`files/\` 根目录，也不要自己猜 \`agent-data/agent1/...\` 这种路径。`,
+                    `5. 用户要把网页/文章 URL 加入知识库 → 先确认目标 kbId，再调用 \`${nativeKbTool("kb_import_url")}\`；返回 job 后用 \`${nativeKbTool("kb_get_job")}\` 或 \`${nativeKbTool("kb_list_jobs")}\` 看进度。`,
+                    `6. 用户要上传你**新生成**的文件 → 先写到 \`${generatedOutboxPath}\`，再解析本地路径，最后调用 \`${nativeKbTool("kb_upload")}\`。`,
+                    `7. 用户要新建库并马上上传 → \`${nativeKbTool("kb_create")}\` → 记住返回的 id → \`${nativeKbTool("kb_upload")}\` / \`${nativeKbTool("kb_import_url")}\`。`,
+                    `8. 用户要查看某个命中文档的细节 → 先 \`${nativeKbTool("kb_list_documents")}\` 找 documentId，再 \`${nativeKbTool("kb_get_document")}\`；需要解释命中原因用 \`${nativeKbTool("kb_list_document_chunks")}\`，只有用户明确要看原文时才用 \`${nativeKbTool("kb_read_document_raw")}\`。`,
+                    `9. 用户要修复索引/重跑失败导入 → 先 \`${nativeKbTool("kb_list_jobs")}\` / \`${nativeKbTool("kb_get_job")}\` 看状态；重试用 \`${nativeKbTool("kb_retry_job")}\`，重索引用 \`${nativeKbTool("kb_reindex_document")}\`。`,
+                    `10. 用户要解释某个设置项怎么用 → 先 \`${nativeKbTool("kb_read_handbook")}\`，必要时再 \`${nativeKbTool("kb_get_config")}\` 看当前值。`,
                     "",
-                    `**安全规则**：写操作和删除操作不要猜目标知识库；拿不准就先 \`kb_list\`。删除必须是用户明确要求，且把 confirm 字段原样填成同一个 id。 \`kb_get_config\` 只返回脱敏摘要，不会给你密钥。 \`kb_upload\` 只接受来自当前实例已挂载文件目录，或当前实例附件 inbox（\`${attachmentInboxPath}/...\`）的绝对路径。**`,
+                    `**安全规则**：写操作、删除操作、重索引、取消任务都不要猜目标知识库；拿不准就先 \`${nativeKbTool("kb_list")}\`。删除/重索引/取消必须是用户明确要求，且把 confirm 字段原样填成同一个 id。 \`${nativeKbTool("kb_get_config")}\` 和 \`${nativeKbTool("kb_get_capabilities")}\` 不会给你密钥。 \`${nativeKbTool("kb_upload")}\` 只接受来自当前实例已挂载文件目录，或当前实例附件 inbox（\`${attachmentInboxPath}/...\`）的绝对路径；如果 remote MCP capabilities 显示 path upload 关闭，就只能使用内容/URL 上传。 \`${nativeKbTool("kb_read_document_raw")}\` 只在用户要看原文时使用。**`,
                     "",
                     "**与 drive 的分工**：",
                     "- `drive.*` = 文件系统 facade（列目录、读字节、拿绝对路径）—— 要的是**文件本体**用 drive",
-                    "- `kb.*` = 知识库检索/管理/上传 —— 要的是**知识库里的内容和状态**用 kb",
+                    "- `kb__*` = 知识库检索/管理/上传 —— 要的是**知识库里的内容和状态**用 kb",
                     "",
                     "两者数据不共享：drive 里有文件 ≠ 某个知识库已经索引了它。",
                     "",
-                    "**搜不到时的标准回复**：如果 `kb_search` 没结果，就直接说「我在当前知识库里没找到相关内容」。如果用户问的是 drive 里已有文件，可进一步建议「要我把它上传到某个知识库吗？」—— 但上传前先确认目标 kbId，不要自己猜默认库。",
+                    `**搜不到时的标准回复**：如果 \`${nativeKbTool("kb_search")}\` 没结果，就直接说「我在当前知识库里没找到相关内容」。如果用户问的是 drive 里已有文件，可进一步建议「要我把它上传到某个知识库吗？」—— 但上传前先确认目标 kbId，不要自己猜默认库。`,
                     "",
                     JISHUSHELL_KB_HINT_END,
                     "",
@@ -1815,6 +1874,96 @@ export function patchToolsMdKbHint(workspaceDir, mode, provider, mcporterCommand
         console.warn(`[openclaw] Failed to ${mode} TOOLS.md kb hint: ${e.message}`);
     }
 }
+export function patchToolsMdKbUnavailableHint(workspaceDir, reason) {
+    patchToolsMdKbHint(workspaceDir, "unavailable", undefined, "mcporter", undefined, undefined, reason);
+}
+/**
+ * Inject or remove the Immich MCP usage contract in TOOLS.md.
+ *
+ * Immich is registered through OpenClaw's native `mcp.servers` config, so the
+ * model receives standard tool schemas and calls them directly. This section
+ * only supplies product behavior and safety guidance; it must not teach the
+ * model to shell out through mcporter.
+ */
+export function patchToolsMdImmichHint(workspaceDir, mode, serverName = "immich") {
+    try {
+        const toolsPath = join(workspaceDir, "TOOLS.md");
+        let original = "";
+        try {
+            original = readFileSync(toolsPath, "utf-8");
+        }
+        catch (e) {
+            if (e?.code !== "ENOENT")
+                throw e;
+            if (mode === "remove")
+                return;
+        }
+        const stripRe = /\n*<!-- jishushell-immich: BEGIN[^>]*-->[\s\S]*?<!-- jishushell-immich: END[^>]*-->\n*/g;
+        const stripped = original.replace(stripRe, "\n");
+        let next;
+        if (mode === "remove") {
+            if (stripped === original)
+                return;
+            next = stripped;
+        }
+        else {
+            const tool = (name) => `${serverName}__${name}`;
+            const section = [
+                JISHUSHELL_IMMICH_HINT_BEGIN,
+                "",
+                "### 🖼️ Immich 照片库",
+                "",
+                `Immich 已通过 OpenClaw 原生 MCP 接入。用户询问照片、视频、图库状态、相册、标签、人物、人脸、地图位置或重复照片时，必须调用 \`${serverName}__*\` 工具，并严格按照工具提供的参数 Schema 传参。`,
+                "",
+                `⚠️ **不要用 shell 探测 Immich 是否安装**：OpenClaw 运行在自己的容器里；容器内没有 \`docker\` 命令、没有宿主机监听端口或 Immich 数据目录，并不代表宿主机没有运行 Immich。禁止用 \`docker ps\`、\`ss\`、\`find /\`、\`ls /opt\` 等结果判断 Immich 状态。连接状态只以 \`${tool("get_library_summary")}\` / \`${tool("ping")}\` 的结果为准。`,
+                "",
+                "**主要工具**：",
+                "",
+                `- \`${tool("get_library_summary")}\` — 首选健康检查；返回连接、版本和图库统计`,
+                `- \`${tool("get_photo_library_status")}\` — 查看 AI Box 默认照片目录是否已接入及已扫描数量`,
+                `- \`${tool("scan_photo_library")}\` — 扫描 AI Box 默认照片目录；首次调用会自动创建 External Library`,
+                `- \`${tool("create_photo_upload_session")}\` — 创建短期网页上传链接；照片和视频由浏览器直接传到 AI Box；同一页面在过期前可完成并扫描多个上传批次`,
+                `- \`${tool("list_assets")}\` — 列出照片/视频`,
+                `- \`${tool("search_metadata")}\` — 按结构化元数据搜索`,
+                `- \`${tool("search_smart")}\` — 用自然语言或相似图片获取 Immich Smart Search / CLIP 相似候选排序`,
+                `- \`${tool("get_asset_info")}\` — 查看单个资源`,
+                `- \`${tool("list_albums")}\` / \`${tool("get_album")}\` / \`${tool("delete_album")}\` — 相册`,
+                `- \`${tool("list_tags")}\` / \`${tool("get_tag")}\` / \`${tool("delete_tag")}\` — 标签`,
+                `- \`${tool("list_people")}\` / \`${tool("search_people")}\` — 人物`,
+                `- \`${tool("get_duplicates")}\` — 重复项`,
+                `- \`${tool("generate_review_gallery")}\` — 创建用户自选照片的 review 页面；确认后 Core 直接执行`,
+                "",
+                "**标准工具策略**：",
+                `1. 先按用户意图选择工具，不要用 shell、mcporter 或 memory_search 代替 Immich MCP。健康检查用 \`${tool("get_library_summary")}\` / \`${tool("ping")}\`；扫描用 \`${tool("scan_photo_library")}\`，返回 \`scan_queued\` 时只说明扫描已开始，不要声称所有照片已经导入完成；上传用 \`${tool("create_photo_upload_session")}\`，上传页面可在过期前连续完成多个批次。`,
+                `2. 读取和搜索只负责收集候选资源：普通列表用 \`${tool("list_assets")}\`，结构化条件搜索用 \`${tool("search_metadata")}\`，自然语言视觉语义或“找相似照片”用 \`${tool("search_smart")}\`，相册内容用 \`${tool("get_album")}\`，重复项用 \`${tool("get_duplicates")}\`。工具返回短 JSON 和 asset id；不要把 thumbnail base64、文件内容或大量 asset id 展示给用户。`,
+                `   \`${tool("search_smart")}\` 的实际语义是 Immich 返回一页按语义相似度排序的候选，默认 \`size=50\`、最大 \`100\`；它不是二分类器，也不保证返回“所有符合条件”的照片。小图库里可能几乎所有照片都会出现在第一页。向用户表述时使用“相似候选 / 候选结果 / 排序结果”，不要说“已经找到了所有 X 照片”或“这些全都是 X”。`,
+                `3. 相册和标签是目标容器。用户要求把照片加入某个新相册或新标签时，先用 \`${tool("create_album")}\` 或 \`${tool("create_tag")}\` 创建目标；如果目标是否存在或应复用不明确，先查列表或向用户确认。`,
+                `4. 删除相册或标签前，必须先用 \`${tool("get_album")}\` / \`${tool("get_tag")}\` 或列表结果核对资源名称和 id，并在对话里明确询问用户确认。调用 \`${tool("delete_album")}\` 不会删除照片；调用 \`${tool("delete_tag")}\` 不会删除照片，但会把该标签从所有关联照片上移除。`,
+                `5. 所有需要用户从候选照片中确认子集、确认批量修改、或决定哪些重复项应处理的操作，都必须通过 \`${tool("generate_review_gallery")}\` 创建 review interaction。适用动作包括加入/移出相册、打标签/取消标签、移入回收站、处理重复项。`,
+                `6. 对搜索驱动的批量操作采用通用的 human-in-the-loop 候选审核流程：先用读取/搜索工具得到候选集，把需要用户可见审核的候选放入 \`asset_ids\`；只有能解释清楚依据的高置信项才放入 \`preselected_asset_ids\`，让 review UI 默认勾选。最终执行仍以用户在页面中的确认和修改为准。`,
+                `7. 不要把所有 CLIP 命中无条件当作推荐项。Smart Search 结果只能直接作为候选，推荐项应基于多信号判断：分数 score（如果工具返回）、搜索排名、文件名、相册/标签/人物、地点、日期、资源类型等。精确结构化条件、明确 asset id、或用户给出的确定集合可以默认全选；纯视觉搜索且缺少可靠阈值或存在歧义时，只预选高置信项，不能判断的保持未选，必要时先请用户缩小条件。`,
+                `8. 用户表达“所有/全部/帮我找并加入/自动整理”时，不要把筛选工作完全丢给用户；应创建 review 页面给出候选，并在有高置信推荐项时默认选中。若候选只来自 Smart Search 且无法可靠区分，应明确说明这是相似候选排序，需要用户在页面中最终确认，而不是假装已经自动识别全部。用户表达“我来选、从图库挑、让我自己选择、选择几张”时，省略 \`preselected_asset_ids\`，让用户手动选择。`,
+                `9. 调用 \`${tool("generate_review_gallery")}\` 时，\`action\` 必须使用工具 schema 中的枚举原值：\`add_assets_to_album\`、\`remove_assets_from_album\`、\`tag_assets\`、\`untag_assets\`、\`delete_assets_to_trash\`、\`resolve_duplicates\`。不要自造 \`add-to-album\`、\`select-assets\`、\`manage-album\` 等动作名。`,
+                `10. 创建 review interaction 后，只把返回的 \`urls.web\` 和简短说明发给用户。如果提供了 \`preselected_asset_ids\`，说明“已默认选中推荐项，可直接确认或取消误选”；如果没有预选项，说明“这是候选页面，需要你确认哪些要处理”。用户在页面点击确认后，Core 会直接执行；不要要求用户回到对话框继续确认，也不要自行声称已经执行，除非工具返回的执行状态明确表示完成。`,
+                "11. 如果候选集过大或用户意图不足以确定候选范围，先请用户用时间、地点、收藏、文件名、相册、标签、人物或其他结构化条件缩小范围；不要为了避免使用 review UI 而先列编号让用户在对话里挑。",
+                "12. 删除照片只表示移入 Immich 回收站。永久删除和清空回收站不可用，不要声称已经永久删除。",
+                "13. MCP 调用失败时，原样说明工具错误；不要改用 shell 猜测工具参数，也不要据此断言 Immich 未安装。",
+                "",
+                JISHUSHELL_IMMICH_HINT_END,
+                "",
+            ].join("\n");
+            const sep = stripped && !stripped.endsWith("\n") ? "\n\n" : "\n";
+            next = (stripped ? stripped + sep : "") + section;
+        }
+        if (next === original)
+            return;
+        writeConfigFile(toolsPath, next);
+        console.log(`[openclaw] ${mode === "remove" ? "Removed" : "Patched"} immich hint in ${toolsPath}`);
+    }
+    catch (e) {
+        console.warn(`[openclaw] Failed to ${mode} TOOLS.md immich hint: ${e.message}`);
+    }
+}
 /**
  * Pre-seed the per-instance npm global prefix with a symlink to the image's
  * baked openclaw package so OpenClaw's in-gateway "Update now" handler can
@@ -2302,6 +2451,75 @@ function assertSafeTemplateId(id) {
 async function lazyIm() {
     return await import("../../instances/manager.js");
 }
+async function resolveCoreConnectionForOpenclaw(instanceId) {
+    const corePort = getCorePort();
+    let coreHost = "host.docker.internal";
+    try {
+        const im = await lazyIm();
+        const runtime = im.getInstanceRuntime(instanceId);
+        if (!runtime?.image)
+            coreHost = getCoreLanHost();
+    }
+    catch (error) {
+        console.warn(`[openclaw] core URL runtime detection failed for ${instanceId}; using container-reachable host:`, error);
+    }
+    return {
+        coreUrl: `http://${coreHost}:${corePort}`,
+        internalToken: getInternalMcpToken(),
+    };
+}
+async function syncImmichMcpForOpenclawInstance(instanceId) {
+    const home = openclawIntegration.resolveAgentHome(instanceId);
+    const configPath = openclawConfigPath(instanceId, home);
+    const { resolveImmichConfig, } = await import("../immich/config.js");
+    const config = await resolveImmichConfig();
+    const source = {
+        kind: "connection",
+        slot: "photos",
+        consumerInstanceId: instanceId,
+    };
+    const shimDir = join(home, "__mcp_shims__", "immich");
+    const shimPath = join(shimDir, "immich-shim.js");
+    const secretPath = join(shimDir, "secret.json");
+    const wsDir = join(home, ".openclaw", "workspace");
+    if (config?.baseUrl && config.apiKey) {
+        const { IMMICH_SHIM_SECRET_FILENAME, substituteImmichShimPlaceholders, } = await import("../immich/immich-shim.js");
+        ensureDirContainer(shimDir);
+        const { coreUrl, internalToken, } = await resolveCoreConnectionForOpenclaw(instanceId);
+        writeFileSync(shimPath, substituteImmichShimPlaceholders({
+            baseUrl: config.baseUrl,
+            photoLibraryEnabled: config.mode === "managed",
+            coreUrl,
+            instanceId,
+        }), { mode: 0o644 });
+        writeFileSync(join(shimDir, IMMICH_SHIM_SECRET_FILENAME), JSON.stringify({ apiKey: config.apiKey, internalToken }) + "\n", { mode: 0o600 });
+        try {
+            chmodSync(secretPath, 0o600);
+        }
+        catch { /* best effort */ }
+        const nativeServerName = upsertOpenclawMcpServer(configPath, "immich", {
+            command: "node",
+            args: [shimPath],
+            __source: source,
+        });
+        if (!nativeServerName)
+            return "missing-config";
+        removeMcporterServers(instanceId, { source });
+        patchToolsMdImmichHint(wsDir, "install", nativeServerName);
+        notifyConfigChange(instanceId);
+        return "installed";
+    }
+    removeOpenclawMcpServers(configPath, { source });
+    removeMcporterServers(instanceId, { source });
+    rmSync(shimDir, { recursive: true, force: true });
+    patchToolsMdImmichHint(wsDir, "remove");
+    notifyConfigChange(instanceId);
+    return "removed";
+}
+function isOpenclawInstanceMetadata(instance) {
+    return Array.isArray(instance.integrations)
+        && instance.integrations.some((entry) => entry?.kind === "openclaw");
+}
 // ── Docker image build helpers (physically migrated from setup-manager) ─
 //
 // All OpenClaw-specific docker image build knowledge lives here. setup-manager
@@ -2482,71 +2700,6 @@ async function pullOrBuildOpenclawImageWithTask(task, tag) {
         };
     }
 }
-function sanitizeConnectionMcpName(name) {
-    return name.replace(/[^a-zA-Z0-9_-]/g, "-").slice(0, 64);
-}
-function connectionMcpTransport(protocol) {
-    switch ((protocol || "").toLowerCase()) {
-        case "http":
-        case "https":
-            return "http";
-        case "sse":
-        case "ws":
-        case "wss":
-            return "sse";
-        default:
-            return undefined;
-    }
-}
-function isIPv6Host(host) {
-    return /:.*:/.test(host) && !host.startsWith("[");
-}
-function bracketIPv6Host(host) {
-    return isIPv6Host(host) ? `[${host}]` : host;
-}
-function buildConnectionHttpBaseUrl(entry) {
-    const protocol = entry.protocol === "https" ? "https" : "http";
-    const url = new URL(`${protocol}://${bracketIPv6Host(entry.host)}:${entry.hostPort}`);
-    if (entry.path && entry.path !== "/")
-        url.pathname = entry.path;
-    return url.toString().replace(/\/$/, "");
-}
-function applyOpenClawMcpBinding(args) {
-    const { instanceId, binding } = args;
-    if (binding.category !== "mcp" || binding.entries.length === 0)
-        return;
-    const source = {
-        kind: "connection",
-        slot: binding.slot,
-        consumerInstanceId: instanceId,
-    };
-    // Replace-style: drop prior connection-managed entries for this
-    // (slot, consumer) pair, then merge the currently resolved providers.
-    removeMcporterServers(instanceId, { source });
-    const servers = {};
-    for (const entry of binding.entries) {
-        const name = sanitizeConnectionMcpName(`${entry.capability}-${entry.instanceId}`);
-        const transport = connectionMcpTransport(entry.protocol);
-        const url = transport === "stdio" ? undefined : buildConnectionHttpBaseUrl(entry);
-        servers[name] = {
-            ...(transport ? { transport } : {}),
-            ...(url ? { url } : {}),
-            __source: source,
-        };
-    }
-    mergeMcporterServers(instanceId, servers);
-}
-function unapplyOpenClawMcpBinding(args) {
-    if (args.category !== "mcp")
-        return;
-    removeMcporterServers(args.instanceId, {
-        source: {
-            kind: "connection",
-            slot: args.slot,
-            consumerInstanceId: args.instanceId,
-        },
-    });
-}
 // ── OpenClawIntegration class ─────────────────────────────────────────────
 class OpenClawIntegration {
     kind = "openclaw";
@@ -2765,7 +2918,6 @@ class OpenClawIntegration {
                 if (home) {
                     const { substituteDriveShimPlaceholders } = await import("./drive-shim.js");
                     const { mergeMcporterServers } = await import("./mcporter.js");
-                    const { getInternalMcpToken } = await import("../../../config.js");
                     // Pick the core URL based on how THIS instance will actually run.
                     // For a containerized instance (raw_exec/docker via Nomad with a
                     // docker image), `host.docker.internal:<corePort>` resolves through
@@ -2776,18 +2928,7 @@ class OpenClawIntegration {
                     // Detected via the instance's resolved runtime: container tasks
                     // carry `runtime.image`, binary tasks carry only `runtime.command`.
                     const corePort = getCorePort();
-                    let driveCoreHost = "host.docker.internal";
-                    try {
-                        const im2 = await lazyIm();
-                        const rt = im2.getInstanceRuntime(instanceId);
-                        if (!rt?.image) {
-                            driveCoreHost = getCoreLanHost();
-                        }
-                    }
-                    catch (e) {
-                        console.warn(`[openclaw] drive shim runtime detection failed for ${instanceId}; using container-reachable core host:`, e);
-                    }
-                    const driveCoreUrl = `http://${driveCoreHost}:${corePort}`;
+                    const { coreUrl: driveCoreUrl, internalToken, } = await resolveCoreConnectionForOpenclaw(instanceId);
                     const shimDir = join(home, "__mcp_shims__", "drive");
                     ensureDirContainer(shimDir);
                     const shimPath = join(shimDir, "drive-shim.mjs");
@@ -2795,7 +2936,6 @@ class OpenClawIntegration {
                     // even when OpenClaw scrubs env on MCP subprocess spawn (verified
                     // 2026-05-11 on pi2: env scrub made the shim default to the
                     // unreachable host.docker.internal and surface as "fetch failed").
-                    const internalToken = getInternalMcpToken();
                     const shimSource = substituteDriveShimPlaceholders({
                         coreUrl: driveCoreUrl,
                         token: internalToken,
@@ -2853,7 +2993,8 @@ class OpenClawIntegration {
             //          the API key lives in a sibling `secret.json` (0o600).
             //        - mcporter.json (0o644) env carries only non-secret hints
             //          for hand-running. Production shim reads the secret file.
-            //      jishu-kb v1 ships without auth, so no secret.json.
+            //      JishuKB remote MCP auth is stored on the managed KB runtime and
+            //      provider credentials, not in the legacy shim directory.
             try {
                 const home = openclawIntegration.resolveAgentHome(instanceId);
                 if (home) {
@@ -2864,9 +3005,22 @@ class OpenClawIntegration {
                     const anyllmShimDir = join(home, "__mcp_shims__", "anythingllm");
                     const anyllmShimPath = join(anyllmShimDir, "anythingllm-shim.js");
                     const anyllmSecretPath = join(anyllmShimDir, "secret.json");
-                    const jishukbShimDir = join(home, "__mcp_shims__", "jishukb");
-                    const jishukbShimPath = join(jishukbShimDir, "jishukb-shim.js");
                     const { mergeMcporterServers, removeMcporterServers } = await import("./mcporter.js");
+                    const { removeOpenclawMcpServers, upsertFixedOpenclawMcpServer } = await import("./native-mcp.js");
+                    const kbSource = { kind: "connection", slot: "knowledge", consumerInstanceId: instanceId };
+                    const openclawCfgPath = openclawConfigPath(instanceId, home);
+                    const cleanupManagedKb = (unavailableReason) => {
+                        removeMcporterServers(instanceId, { source: kbSource });
+                        removeOpenclawMcpServers(openclawCfgPath, { source: kbSource });
+                        notifyConfigChange(instanceId);
+                        if (unavailableReason) {
+                            patchToolsMdKbUnavailableHint(wsDir, unavailableReason);
+                        }
+                        else {
+                            patchToolsMdKbHint(wsDir, "remove");
+                        }
+                        wipeKbShimDir(home, "jishukb");
+                    };
                     if (provider === "jishukb") {
                         // Wipe the OTHER provider's residue first (including its
                         // 0o600 secret.json). Security smell to leave it on disk.
@@ -2882,50 +3036,80 @@ class OpenClawIntegration {
                             }
                         }
                         if (creds?.baseUrl) {
-                            const kbId = await resolveJishukbDefaultKbIdForOpenClaw(creds.baseUrl, creds.kbId);
-                            const { substituteJishukbShimPlaceholders } = await import("./jishukb-shim.js");
-                            ensureDirContainer(jishukbShimDir);
-                            const shimSource = substituteJishukbShimPlaceholders({
+                            const mediaInbound = join(home, ".openclaw", "media", "inbound");
+                            ensureDirContainer(mediaInbound);
+                            const authToken = typeof creds.mcpAuthToken === "string" ? creds.mcpAuthToken.trim() : "";
+                            const { discoverJishukbRemoteMcp, preflightJishukbRemoteMcp } = await import("./jishukb-native-mcp.js");
+                            const discovery = await discoverJishukbRemoteMcp({
                                 baseUrl: creds.baseUrl,
-                                kbId,
-                                allowedUploadRoots: listJishukbUploadRoots(instMeta?.runtime ?? {}, home),
+                                authToken,
+                                expectedProfile: "openclaw",
                             });
-                            writeFileSync(jishukbShimPath, shimSource, { mode: 0o644 });
-                            mergeMcporterServers(instanceId, {
-                                kb: {
-                                    command: "node",
-                                    args: [jishukbShimPath],
-                                    env: {
-                                        // Belt-and-suspenders fallback for hand-running.
-                                        // Baked values in the shim source are the production
-                                        // source of truth. No secret in v1.
-                                        JISHUKB_BASE_URL: creds.baseUrl,
-                                        JISHUKB_KB_ID: kbId,
-                                    },
-                                    __source: {
-                                        kind: "connection",
-                                        slot: "knowledge",
-                                        consumerInstanceId: instanceId,
-                                    },
-                                },
-                            });
-                            patchToolsMdKbHint(wsDir, "install", "jishukb", mcporterCommand, instanceId, join(home, ".openclaw", "media", "inbound"));
+                            if (!discovery.ok || !discovery.url) {
+                                const reason = `remote jishu-kb MCP discovery failed: ${discovery.reason || "no endpoint"}`;
+                                console.warn(`[openclaw] kb: ${reason}`);
+                                cleanupManagedKb(reason);
+                            }
+                            else {
+                                if (discovery.authRequired && !authToken) {
+                                    const reason = "remote jishu-kb MCP requires bearer auth but credentials are missing mcpAuthToken";
+                                    console.warn(`[openclaw] kb: ${reason}`);
+                                    cleanupManagedKb(reason);
+                                }
+                                else {
+                                    const preflight = await preflightJishukbRemoteMcp({
+                                        url: discovery.url,
+                                        authToken,
+                                        expectedProfile: "openclaw",
+                                    });
+                                    if (!preflight.ok) {
+                                        const reason = `remote jishu-kb MCP preflight failed: ${preflight.reason}`;
+                                        console.warn(`[openclaw] kb: ${reason}`);
+                                        cleanupManagedKb(reason);
+                                    }
+                                    else {
+                                        const registeredUrl = rewriteJishukbMcpUrlForOpenClawRuntime(discovery.url, instMeta?.runtime ?? {});
+                                        const entry = {
+                                            url: registeredUrl,
+                                            transport: "streamable-http",
+                                            connectionTimeoutMs: 8_000,
+                                            __source: kbSource,
+                                        };
+                                        if (authToken) {
+                                            entry.headers = { Authorization: `Bearer ${authToken}` };
+                                        }
+                                        wipeKbShimDir(home, "jishukb");
+                                        removeMcporterServers(instanceId, { source: kbSource });
+                                        const result = upsertFixedOpenclawMcpServer(openclawCfgPath, "kb", entry);
+                                        if (!result.ok) {
+                                            const reason = result.reason === "name-conflict"
+                                                ? "user-managed native MCP server 'kb' blocks managed JishuKB registration"
+                                                : "OpenClaw native config is missing; managed JishuKB registration skipped";
+                                            console.warn(`[openclaw] kb: ${reason}`);
+                                            cleanupManagedKb(reason);
+                                        }
+                                        else {
+                                            notifyConfigChange(instanceId);
+                                            patchToolsMdKbHint(wsDir, "install", "jishukb", "native", instanceId, mediaInbound);
+                                        }
+                                    }
+                                }
+                            }
                         }
                         else {
                             // jishu-kb bound but baseUrl not yet ready / credentials missing.
                             // Remove any prior kb registration so the agent doesn't
                             // call a stale shim, and wipe our own shim dir for hygiene.
-                            console.warn(`[openclaw] kb: jishu-kb bound but baseUrl missing at ${credPath} — skipping shim install`);
-                            removeMcporterServers(instanceId, {
-                                source: { kind: "connection", slot: "knowledge", consumerInstanceId: instanceId },
-                            });
-                            patchToolsMdKbHint(wsDir, "remove");
-                            wipeKbShimDir(home, "jishukb");
+                            const reason = `jishu-kb bound but baseUrl missing at ${credPath}; native MCP registration skipped`;
+                            console.warn(`[openclaw] kb: ${reason}`);
+                            cleanupManagedKb(reason);
                         }
                     }
                     else if (provider === "anythingllm") {
                         // Wipe the OTHER provider's residue first.
                         wipeKbShimDir(home, "jishukb");
+                        removeOpenclawMcpServers(openclawCfgPath, { source: kbSource });
+                        notifyConfigChange(instanceId);
                         const credPath = resolveProviderCredentialsPath("anythingllm-container");
                         let kbCreds = null;
                         if (existsSync(credPath)) {
@@ -2986,18 +3170,26 @@ class OpenClawIntegration {
                         // provider === null → user explicitly unbound, or bound to
                         // an unknown/unsupported provider. Strip kb server and wipe
                         // both shim dirs.
-                        removeMcporterServers(instanceId, {
-                            source: { kind: "connection", slot: "knowledge", consumerInstanceId: instanceId },
-                        });
-                        patchToolsMdKbHint(wsDir, "remove");
+                        cleanupManagedKb();
                         wipeKbShimDir(home, "anythingllm");
-                        wipeKbShimDir(home, "jishukb");
                     }
                 }
             }
             catch (e) {
                 console.warn(`[openclaw] kb shim wiring skipped: ${e?.message ?? e}`);
             }
+            // 4c-quinquies. Auto-wire Immich MCP when the Immich integration has
+            // endpoint credentials. The endpoint can be external or a managed
+            // immich-container instance. OpenClaw receives the stdio shim through
+            // its native `mcp.servers` config, the API key and Core internal token
+            // stay in a 0o600 sibling secret file, and user review interactions are
+            // created through Core-owned Immich routes.
+            try {
+                await syncImmichMcpForOpenclawInstance(instanceId);
+            }
+            catch (e) {
+                console.warn(`[openclaw] immich shim wiring skipped: ${e?.message ?? e}`);
+            }
             // 4c-bis. Self-heal MCPORTER_CONFIG env on existing instances. Without
             //      this, mcporter can't find its config when invoked from the
             //      gateway's CWD (openclaw-home/) or from the workspace symlink
@@ -3523,9 +3715,8 @@ class OpenClawIntegration {
      * it the `web_search` tool defaults to Brave and fails with
      * `missing_brave_api_key` even when the searxng plugin is fully configured.
      *
-     * Browser / LLM / MCP wiring lands in PR 9b — they need their own
-     * config-shape mapping (browser → tools.browser, llm → models.providers,
-     * mcp already wired via the OpenClaw mcporter helper).
+     * Browser / LLM wiring needs its own config-shape mapping
+     * (browser → tools.browser, llm → models.providers).
      *
      * The write goes through `saveNativeConfig` which preserves relevant fields
      * from the existing canonical on-disk config, so user-managed plugin entries (e.g.
@@ -3604,12 +3795,6 @@ class OpenClawIntegration {
             // write a URL OpenClaw can't dial.
         }
     }
-    async applyConnectionBinding(args) {
-        applyOpenClawMcpBinding(args);
-    }
-    async unapplyConnectionBinding(args) {
-        unapplyOpenClawMcpBinding(args);
-    }
     listConnectionSideEffectFiles(args) {
         const home = openclawHomeFromMetadata(getInstance(args.instanceId), args.instanceId);
         const envFile = getRuntimeEnvFiles(args.instanceId)[0] ?? defaultOpenclawModelEnvFile(args.instanceId);
@@ -3638,6 +3823,25 @@ class OpenClawIntegration {
     summarizeRecentBrowserSession(instanceId) {
         return summarizeRecentOpenclawBrowserSession(instanceId);
     }
+    async syncImmichMcpForAllInstances() {
+        const updated = [];
+        const skipped = [];
+        for (const instance of listInstances()) {
+            const instanceId = typeof instance.id === "string" ? instance.id : "";
+            if (!instanceId)
+                continue;
+            try {
+                if (!isOpenclawInstanceMetadata(instance))
+                    continue;
+                await syncImmichMcpForOpenclawInstance(instanceId);
+                updated.push(instanceId);
+            }
+            catch (error) {
+                skipped.push({ instanceId, error: error?.message ?? String(error) });
+            }
+        }
+        return { updated, skipped };
+    }
     /** Env vars OpenClaw's CLI needs when backup-manager runs it as a subprocess. */
     buildCliEnv(instanceId) {
         return { OPENCLAW_HOME: this.resolveAgentHome(instanceId) };
@@ -3906,7 +4110,6 @@ class OpenClawIntegration {
     getInstallStatus() {
         // OPENCLAW_MODULES may be undefined when config is partially mocked in tests.
         const pkgInstalled = OPENCLAW_MODULES ? existsSync(join(OPENCLAW_MODULES, "openclaw")) : false;
-        const version = pkgInstalled ? readInstalledOpenclawVersion() : undefined;
         const imageTag = getOpenclawDockerImage?.() ?? "";
         let imageReady = false;
         try {
@@ -3920,6 +4123,14 @@ class OpenClawIntegration {
             }
         }
         catch { /* image absent */ }
+        // Prefer the version pinned into the docker image tag — that is what
+        // instances actually run in the default docker deployment. The host-npm
+        // package.json (readInstalledOpenclawVersion) is unrelated to the running
+        // container, so reporting it made the UI show "latest" while the container
+        // still ran the old build after an update. Fall back to host-npm only when
+        // no image is ready (legacy npm path).
+        const imageVersion = imageReady ? versionFromImageTag(imageTag) : "";
+        const version = imageVersion || (pkgInstalled ? readInstalledOpenclawVersion() : "");
         return {
             installed: imageReady || pkgInstalled,
             imageReady,
@@ -3940,6 +4151,22 @@ function readInstalledOpenclawVersion() {
     }
     return "";
 }
+/**
+ * Extract a semver-ish version from a pinned image tag, e.g.
+ * `ghcr.io/x-aijishu/openclaw-runtime:2026.6.10` -> `2026.6.10`. Returns "" when
+ * the tag carries no version (mutable `:latest`/`:slim`, or the only colon is a
+ * registry port).
+ */
+function versionFromImageTag(imageTag) {
+    if (!imageTag)
+        return "";
+    const colonIdx = imageTag.lastIndexOf(":");
+    const slashIdx = imageTag.lastIndexOf("/");
+    if (colonIdx <= slashIdx)
+        return "";
+    const tag = imageTag.slice(colonIdx + 1);
+    return /^\d+\.\d+\.\d+/.test(tag) ? tag : "";
+}
 // Feishu app IDs issued by the open platform follow `cli_<hex/alnum>`.
 const FEISHU_APP_ID_RE = /^cli_[a-zA-Z0-9]{8,64}$/;
 const SAFE_ACCOUNT_ID_RE = /^[a-zA-Z0-9@._-]{1,128}$/;