@jesonliu/lark-claudecode-bridge 1.3.7 → 1.4.0

package/dist/memory-installer.js

@@ -0,0 +1,1035 @@
+// B3 嵌入式安装器（生命周期方案 §6.7 一键流水线）：五步——runtime（uv）→ service（openviking）
+// → config（ov.conf 渲染）→ start（受管子进程）→ plugin（记忆插件）。每步「检测就绪则跳过 /
+// 失败可重试」，本机已有部件（uv / 服务 / 插件 / 现有服务探活通过）全部自动复用——安装器对
+// 已部署环境是幂等升级器而非重复安装。零新依赖：zip/tar.gz 解压用系统自带 tar（Win10+
+// bsdtar 支持 zip），下载用原生 fetch，子进程 node:child_process。
+//
+// 事实依据（2026-10-13 本机探源）：
+// - uv 官方单文件：github.com/astral-sh/uv/releases/latest/download/<平台包>（win=.zip / mac-linux=.tar.gz）
+// - 服务安装：`uv tool install openviking==<pin>` → bin 里出现 openviking-server；`--config/--host/--port` 全自管
+// - ov.conf schema（本机蓝本）：storage.workspace / embedding.dense{provider:"openai",model,api_key,api_base}
+//   / vlm{provider("glm"|"openai"),model,api_base,api_key} / server{host,port,root_api_key}
+// - 插件源：codeload.github.com/volcengine/OpenViking/<zip|tar.gz>/refs/<ref> → examples/claude-code-memory-plugin
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync, copyFileSync, constants as FS_CONSTANTS } from 'node:fs';
+import { access } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { parseDocument } from 'yaml';
+import { probeMemoryHealth, MEMORY_PLUGIN_NAME, memoryEndpoint } from './memory.js';
+/** 服务默认 pin 版本（实测环境；memory.version 可覆盖） */
+export const DEFAULT_OPENVIKING_PIN = '0.5.0';
+/** 插件源（市场清单 git-subdir 事实）：主仓库 examples 子目录 */
+const PLUGIN_REPO_ZIP = (ref) => `https://codeload.github.com/volcengine/OpenViking/zip/refs/heads/${ref}`;
+const PLUGIN_REPO_TGZ = (ref) => `https://codeload.github.com/volcengine/OpenViking/tar.gz/refs/heads/${ref}`;
+const PLUGIN_SUBDIR = 'examples/claude-code-memory-plugin';
+/** CLI 市场渠道（真实安装：插件页可见、enable/disable/update 全套 CLI 语义可用）。
+ *  市场名与上游 .claude-plugin/marketplace.json 一致（name: "openviking"）。
+ *  注册源按序尝试（实测教训：CLI 内部 fetch 对 raw.githubusercontent 直链只有 10s 超时，
+ *  国内网络易撞；github 简写走 git clone 稳得多）：github 简写优先，清单直链兜底 */
+const MARKETPLACE_NAME = 'openviking';
+const MARKETPLACE_ADD_SOURCES = [
+    'volcengine/OpenViking',
+    'https://raw.githubusercontent.com/volcengine/OpenViking/main/.claude-plugin/marketplace.json',
+];
+const MARKETPLACE_KEY = `${MEMORY_PLUGIN_NAME}@${MARKETPLACE_NAME}`;
+const FRESH_STEPS = () => [
+    { id: 'runtime', title: '运行时（uv）', status: 'pending' },
+    { id: 'service', title: '安装 OpenViking 服务', status: 'pending' },
+    { id: 'config', title: '生成服务配置（ov.conf）', status: 'pending' },
+    { id: 'start', title: '拉起受管服务', status: 'pending' },
+    { id: 'plugin', title: '接入记忆插件', status: 'pending' },
+];
+/** 「启动服务」流水线步骤（§6.8 启动接管）：与安装同款 stepper 展示，启动 ≠ 只拉进程 */
+const START_STEPS = () => [
+    { id: 'locate', title: '检查服务与配置', status: 'pending' },
+    { id: 'launch', title: '拉起并探活', status: 'pending' },
+    { id: 'plugin', title: '接入记忆插件', status: 'pending' },
+];
+let installState = { kind: 'install', running: false, steps: FRESH_STEPS() };
+export function getInstallState() { return installState; }
+let managed;
+/** 停受管实例（页面 stop / LCB shutdown / 重装前）：幂等，未运行为 no-op */
+export function stopManagedServer() {
+    if (!managed)
+        return;
+    managed.stopped = true;
+    try {
+        managed.proc.kill();
+    }
+    catch { /* 已退出 */ }
+    managed = undefined;
+}
+/** LCB 优雅关闭钩子注册点（index.ts shutdown 调用） */
+export function isManagedRunning() { return managed !== undefined; }
+/** 受管实例本次拉起时间（ISO；崩溃自动重启会重置）——status 页「运行时间」展示源，仅受管时有值 */
+export function managedStartedAt() { return managed?.startedAt; }
+// ============ 小工具 ============
+/** 跑命令收 stdout（trim）；非零退出抛带 stderr 摘要的 Error */
+function run(cmd, args, opts = {}) {
+    return new Promise((resolveP, rejectP) => {
+        const p = spawn(cmd, args, {
+            windowsHide: true,
+            env: { ...process.env, ...(opts.env ?? {}) },
+        });
+        let out = '';
+        let err = '';
+        const timer = setTimeout(() => {
+            p.kill();
+            rejectP(new Error(`${cmd} 超时（>${opts.timeoutMs ?? 120_000}ms）`));
+        }, opts.timeoutMs ?? 120_000);
+        p.stdout.on('data', (d) => { out += String(d); });
+        p.stderr.on('data', (d) => { err += String(d); });
+        p.on('error', (e) => { clearTimeout(timer); rejectP(e); });
+        p.on('close', (code) => {
+            clearTimeout(timer);
+            if (code === 0)
+                resolveP(out.trim());
+            else
+                rejectP(new Error(`${cmd} ${args.join(' ')} 退出码 ${code}${err ? `：${err.trim().slice(0, 300)}` : ''}`));
+        });
+    });
+}
+async function canExec(p) {
+    try {
+        await access(p, FS_CONSTANTS.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** 解压命令定位（实测教训：Windows PATH 里 Git Bash 的 GNU tar 常排在 System32 之前，
+ *  GNU tar 不认 zip → 解压失败。Windows 显式用系统自带 bsdtar（Win10 1803+ 必有），
+ *  缺失时回退 PATH tar（mac/linux 均系统自带）。返回 [cmd, 前置参数]。 */
+function tarCommand() {
+    if (process.platform === 'win32') {
+        const bsdtar = join(process.env.SystemRoot ?? 'C:\\Windows', 'System32', 'tar.exe');
+        if (existsSync(bsdtar))
+            return { cmd: bsdtar, args: [] };
+        console.warn('[memory-installer] 未找到系统 bsdtar（System32\\tar.exe），回退 PATH tar（若为 Git Bash GNU tar 将无法解 zip）');
+    }
+    return { cmd: 'tar', args: [] };
+}
+/** 下载到临时文件返回路径（fetch 流式写盘；root key 等不涉密，普通下载） */
+async function downloadTo(url, dest) {
+    const res = await fetch(url, { redirect: 'follow' });
+    if (!res.ok || !res.body)
+        throw new Error(`下载失败：HTTP ${res.status}（${url}）`);
+    const buf = Buffer.from(await res.arrayBuffer());
+    writeFileSync(dest, buf);
+}
+// ============ 步骤 1：uv ============
+const UV_INSTALL_DIR = join(process.env.LCB_CONFIG_DIR ?? String(process.env.USERPROFILE ?? process.env.HOME ?? ''), '.lark-claudecode-bridge', 'bin');
+/** 检测 uv：PATH → 常见安装位 → LCB 管理域。返回可执行路径或 null */
+export async function detectUv() {
+    const candidates = [
+        'uv', // PATH
+        join(String(process.env.USERPROFILE ?? process.env.HOME ?? ''), '.local', 'bin', process.platform === 'win32' ? 'uv.exe' : 'uv'),
+        join(UV_INSTALL_DIR, process.platform === 'win32' ? 'uv.exe' : 'uv'),
+    ];
+    if (process.platform === 'win32') {
+        candidates.splice(2, 0, join(String(process.env.LOCALAPPDATA ?? ''), 'hermes', 'bin', 'uv.exe'));
+    }
+    for (const c of candidates) {
+        if (c === 'uv') {
+            try {
+                await run('uv', ['--version'], { timeoutMs: 10_000 });
+                return 'uv';
+            }
+            catch {
+                continue;
+            }
+        }
+        if (existsSync(c)) {
+            try {
+                await run(c, ['--version'], { timeoutMs: 10_000 });
+                return c;
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    return null;
+}
+/** uv 官方单文件包名（win 用 zip / mac-linux 用 tar.gz——后者保证 GNU tar 也能解） */
+function uvAssetName() {
+    const arch = process.arch === 'arm64' ? 'aarch64' : 'x86_64';
+    if (process.platform === 'win32')
+        return { file: `uv-${arch}-pc-windows-msvc.zip`, extract: 'zip' };
+    if (process.platform === 'darwin')
+        return { file: `uv-${arch}-apple-darwin.tar.gz`, extract: 'tgz' };
+    return { file: `uv-${arch}-unknown-linux-gnu.tar.gz`, extract: 'tgz' };
+}
+async function installUv() {
+    const { file, extract } = uvAssetName();
+    mkdirSync(UV_INSTALL_DIR, { recursive: true });
+    const tmp = mkdtempSync(join(tmpdir(), 'lcb-uv-'));
+    try {
+        const archive = join(tmp, file);
+        await downloadTo(`https://github.com/astral-sh/uv/releases/latest/download/${file}`, archive);
+        // 系统 bsdtar/GNU tar 解压（Windows 显式 System32 bsdtar——PATH 里的 Git Bash tar 不认 zip）
+        const t = tarCommand();
+        await run(t.cmd, [...t.args, '-xf', archive, '-C', tmp], { timeoutMs: 60_000 });
+        // 解包结构：uv-<target>/uv(.exe) —— 遍历两层的候选路径直接定位
+        const exe = process.platform === 'win32' ? 'uv.exe' : 'uv';
+        const candidates = [
+            join(tmp, exe),
+            ...existsSync(join(tmp, 'uv-' + file.replace(extract === 'zip' ? '.zip' : '.tar.gz', '')))
+                ? [join(tmp, 'uv-' + file.replace(extract === 'zip' ? '.zip' : '.tar.gz', ''), exe)]
+                : [],
+        ];
+        const src = candidates.find((p) => existsSync(p));
+        if (!src)
+            throw new Error('解包后未找到 uv 可执行文件（归档结构可能已变化）');
+        const dest = join(UV_INSTALL_DIR, exe);
+        copyFileSync(src, dest);
+        await run(dest, ['--version'], { timeoutMs: 15_000 });
+        return dest;
+    }
+    finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+}
+// ============ 步骤 2：openviking 服务 ============
+/** uv tool 安装的 openviking server 可执行路径（uv tool dir/openviking/{Scripts|bin}/openviking-server[.exe]） */
+export async function resolveServerBin(uv) {
+    try {
+        const toolDir = (await run(uv, ['tool', 'dir'], { timeoutMs: 15_000 })).trim();
+        const exe = process.platform === 'win32' ? 'openviking-server.exe' : 'openviking-server';
+        const candidates = [
+            join(toolDir, 'openviking', process.platform === 'win32' ? 'Scripts' : 'bin', exe),
+            join(String(process.env.USERPROFILE ?? process.env.HOME ?? ''), '.local', 'bin', exe),
+        ];
+        for (const c of candidates)
+            if (existsSync(c))
+                return c;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+async function stepService(uv, pin) {
+    const existing = await resolveServerBin(uv);
+    if (existing) {
+        let ver = '';
+        try {
+            ver = (await run(existing, ['--version'], { timeoutMs: 15_000 })).replace(/^[^0-9]*/, '');
+        }
+        catch { /* 版本查询失败不阻塞（二进制在即视为可用） */ }
+        return { skipped: true, detail: `已安装${ver ? `（v${ver}）` : ''}：${existing}`, bin: existing };
+    }
+    // 尊重 pip/uv 镜像配置（UV_INDEX_URL / UV_DEFAULT_INDEX / PIP_INDEX_URL 经 process.env 自动透传）
+    await run(uv, ['tool', 'install', `openviking==${pin}`], { timeoutMs: 300_000 });
+    const bin = await resolveServerBin(uv);
+    if (!bin)
+        throw new Error(`安装完成但未定位到 openviking-server（uv tool dir 下无产物，请反馈）`);
+    return { skipped: false, detail: `已安装 openviking==${pin}：${bin}`, bin };
+}
+// ============ 步骤 3：ov.conf 渲染 ============
+/** LCB 记忆管理域（嵌入式数据全收敛于此：卸载即整目录删） */
+export const MEMORY_MANAGED_DIR = join(process.env.LCB_CONFIG_DIR ?? String(process.env.USERPROFILE ?? process.env.HOME ?? ''), '.lark-claudecode-bridge', 'openviking');
+export const MANAGED_OV_CONF = join(MEMORY_MANAGED_DIR, 'ov.conf');
+/** vlm provider 映射：glm 预设用服务端原生 "glm"，其余 OpenAI 协议端点统一 "openai"（本机蓝本口径） */
+function vlmProvider(p) {
+    return p === 'glm' ? 'glm' : 'openai';
+}
+/** 渲染 ov.conf（纯函数 exported 便于单测）。rootKey 已有则复用（重装不换 key，否则插件侧缓存/用户侧配置全部失效） */
+export function renderOvConf(model, opts) {
+    const rootApiKey = opts.rootApiKey ?? randomBytes(24).toString('hex');
+    const conf = {
+        storage: { workspace: opts.workspaceDir },
+        embedding: {
+            dense: {
+                provider: 'openai',
+                model: model.embeddingModel ?? '',
+                api_key: model.apiKey ?? '',
+                api_base: model.apiBase ?? '',
+            },
+        },
+        vlm: {
+            provider: vlmProvider(model.provider),
+            model: model.vlmModel ?? '',
+            api_base: model.apiBase ?? '',
+            temperature: 0.0,
+            max_retries: 2,
+            api_key: model.apiKey ?? '',
+        },
+        server: {
+            host: '127.0.0.1',
+            port: opts.port,
+            root_api_key: rootApiKey,
+        },
+    };
+    return { conf, rootApiKey };
+}
+/** 读现有受管 conf 的 root_api_key（存在时复用） */
+function existingRootKey() {
+    try {
+        const doc = JSON.parse(readFileSync(MANAGED_OV_CONF, 'utf8'));
+        return doc.server?.root_api_key;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 外部（用户手动 init，如 `openviking-server init`）ov.conf 的默认位置——已装未跑时
+ *  「启动服务」按钮的兜底配置源（LCB 只代为拉起，不改写其内容） */
+export const EXTERNAL_OV_CONF = join(String(process.env.USERPROFILE ?? process.env.HOME ?? ''), '.openviking', 'ov.conf');
+/** 读 conf 的 server.port（JSON；读取失败按缺省 1933 兜底，不让状态展示路径抛错） */
+function readConfPort(confPath) {
+    try {
+        return JSON.parse(readFileSync(confPath, 'utf8')).server?.port ?? 1933;
+    }
+    catch {
+        return 1933;
+    }
+}
+// ============ 客户端接入配置（ovcli.conf，§6.7 第 4 步落地） ============
+// 插件 isPluginEnabled() 的第 3 优先级判据 + 连接信息兜底层（env > ovcli.conf > ov.conf，
+// 插件 scripts/shared/credentials.mjs 实测口径）。LCB 只写「无 key 骨架」：key 永远走 env
+// 下发（§6.6），绝不落盘到 ~/.openviking/ 域。全新机器一键安装后即启用插件，用户零手工。
+/** 客户端配置文件位置（与 EXTERNAL_OV_CONF 同款 home 解析口径） */
+export const OVCLI_CONF = join(String(process.env.USERPROFILE ?? process.env.HOME ?? ''), '.openviking', 'ovcli.conf');
+/** LCB 骨架形状签名：恰好 {url, account, user} 三个 string 键。这是「文件归 LCB 所有」的判定
+ *  依据——插件 setup 向导 / `ov login` 恒写 api_key（含 api_key 的文件永不与本形状同形），
+ *  且形状判定与端点/账号现值解耦：重装 findFreePort 换端口后旧骨架仍被识别为 LCB 所有
+ *  （这是 ensure 能刷新、cleanup 能删中的关键；勿改成内容比对，否则端口漂移后清理永不触发） */
+function isLcbClientConfShape(v) {
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        return false;
+    const o = v;
+    const keys = Object.keys(o);
+    return keys.length === 3 && ['url', 'account', 'user'].every((k) => typeof o[k] === 'string')
+        && keys.every((k) => ['url', 'account', 'user'].includes(k));
+}
+/** 渲染 ovcli.conf（纯函数 exported 便于单测）。刻意不含 api_key / plugin 段；user 取 account
+ *  值：保证直连场景 identity 非空 → 插件判 trusted header 身份（dev 模式服务可用）；留空会被
+ *  判成 api_key 模式而 401 */
+export function renderOvcliConf(memory) {
+    return { url: memoryEndpoint(memory), account: memory.account ?? 'lcb', user: memory.account ?? 'lcb' };
+}
+/** 写/刷新客户端配置（幂等可重跑）。决策表：
+ *  ① EXTERNAL_OV_CONF 存在 → 'skipped-external'（~/.openviking 域归用户自管，整体不碰；
+ *     外部 ov.conf 本身就满足插件启用判定，LCB 会话另有 env 通道兜底）
+ *  ② 文件缺失 → mkdir recursive + writeAtomic(渲染值) → 'written'
+ *  ③ 文件存在且为 LCB 骨架：内容与渲染值全等 → 'kept'（幂等零写）；否则重写 → 'updated'
+ *     （端口漂移/账号改名/remote↔embedded 切换后的自愈路径）
+ *  ④ 其余（含 api_key 的用户手配、plugin 段、损坏 JSON）→ 'skipped-foreign'（尊重不动）
+ *  dirOverride 供单测注入临时目录（ov.conf/ovcli.conf 一并重定向，摆脱模块常量的 home 依赖） */
+export function ensureClientCliConf(memory, dirOverride) {
+    const ovConf = dirOverride ? join(dirOverride, 'ov.conf') : EXTERNAL_OV_CONF;
+    const ovcli = dirOverride ? join(dirOverride, 'ovcli.conf') : OVCLI_CONF;
+    if (existsSync(ovConf))
+        return 'skipped-external';
+    const next = renderOvcliConf(memory);
+    let cur;
+    try {
+        cur = JSON.parse(readFileSync(ovcli, 'utf8'));
+    }
+    catch {
+        cur = undefined;
+    }
+    if (cur === undefined && !existsSync(ovcli)) {
+        writeAtomic(ovcli, JSON.stringify(next, null, 2));
+        return 'written';
+    }
+    if (isLcbClientConfShape(cur)) {
+        if (JSON.stringify(cur) === JSON.stringify(next))
+            return 'kept';
+        writeAtomic(ovcli, JSON.stringify(next, null, 2));
+        return 'updated';
+    }
+    return 'skipped-foreign';
+}
+/** 关记忆的对称清理：仅当解析后命中 LCB 骨架形状才删（返回是否删除）。刻意不做内容匹配
+ *  （见 isLcbClientConfShape 注释）；损坏/手配文件一律保留 */
+export function cleanupClientCliConf(dirOverride) {
+    const ovcli = dirOverride ? join(dirOverride, 'ovcli.conf') : OVCLI_CONF;
+    let cur;
+    try {
+        cur = JSON.parse(readFileSync(ovcli, 'utf8'));
+    }
+    catch {
+        return false;
+    }
+    if (!isLcbClientConfShape(cur))
+        return false;
+    rmSync(ovcli, { force: true });
+    return true;
+}
+/** 状态页分类（exported 便于 memory-api 与单测复用；路径入参可注入摆脱 home 依赖）。
+ *  external 优先：外部 ov.conf 存在即整个 ~/.openviking 域归用户（与 ensure 的守卫口径一致） */
+export function classifyClientConf(paths) {
+    if (existsSync(paths.ovConf))
+        return { state: 'external', path: paths.ovConf };
+    let cur;
+    try {
+        cur = JSON.parse(readFileSync(paths.ovcli, 'utf8'));
+    }
+    catch {
+        cur = undefined;
+    }
+    if (isLcbClientConfShape(cur))
+        return { state: 'lcb-managed', path: paths.ovcli };
+    if (existsSync(paths.ovcli))
+        return { state: 'user-managed', path: paths.ovcli };
+    return { state: 'missing', path: paths.ovcli };
+}
+// ============ 步骤 4：受管拉起 ============
+/** 找空闲端口：从 1933 起「net 试探 + HTTP 探活」双重确认（Windows SO_REUSEADDR 允许抢绑，
+ *  net listen 成功 ≠ 端口空闲——已有 OpenViking 服务在监听时 listen 可能误报空闲；探活有
+ *  响应 = 确定被占）。候选端口同时两者皆过才采用。 */
+export async function findFreePort(startPort = 1933, tries = 20) {
+    const { createServer } = await import('node:net');
+    for (let p = startPort; p < startPort + tries; p++) {
+        const netOk = await new Promise((res) => {
+            const s = createServer();
+            s.once('error', () => res(false));
+            s.listen(p, '127.0.0.1', () => s.close(() => res(true)));
+        });
+        if (!netOk)
+            continue;
+        const health = await probeMemoryHealth(`http://127.0.0.1:${p}`, 800);
+        if (health.healthy)
+            continue; // 有活服务：占用
+        return p;
+    }
+    throw new Error(`${startPort}-${startPort + tries - 1} 端口段均被占用`);
+}
+/** 拉起受管实例并探活等待就绪（安装流水线第 4 步与「启动服务」按钮共用）。
+ *  探活轮询给 30s（服务冷启含依赖加载）；启动即崩/超时统一抛带指引的 Error（调用方决定展示）。 */
+async function launchManagedAndWait(bin, confPath, port, external = false) {
+    spawnManaged(bin, confPath, port);
+    for (let i = 0; i < 30; i++) {
+        await new Promise((r) => setTimeout(r, 1000));
+        const h = await probeMemoryHealth(`http://127.0.0.1:${port}`, 1500);
+        if (h.healthy) {
+            return { detail: `服务已就绪：http://127.0.0.1:${port}${external ? '（外部配置 ~/.openviking/ov.conf，LCB 仅代为拉起、不改写）' : ''}`, port };
+        }
+        if (!managed)
+            break; // 启动即崩（config 错等）
+    }
+    const hint = `服务启动后探活失败（127.0.0.1:${port}）——请检查 ov.conf 的模型配置（api_base/key/模型名）${external ? '，或改用「一键安装」生成 LCB 受管配置' : ''}`;
+    stopManagedServer();
+    throw new Error(hint);
+}
+async function stepStart(bin, confPath) {
+    const port = readConfPort(confPath);
+    // 已有受管实例：探活通即跳过（幂等重跑）
+    if (managed && !managed.stopped) {
+        const h = await probeMemoryHealth(`http://127.0.0.1:${managed.port}`, 2000);
+        if (h.healthy)
+            return { skipped: true, detail: `受管实例已在运行（127.0.0.1:${managed.port}）`, port: managed.port };
+        stopManagedServer();
+    }
+    const r = await launchManagedAndWait(bin, confPath, port);
+    return { skipped: false, detail: r.detail, port: r.port };
+}
+// ============ 单独启动（「启动服务」按钮 → LCB 接管式启动流水线） ============
+/**
+ * 启动流水线（kind='start'，后台执行 + 与安装同款 stepper 轮询展示）：LCB 已接管 OpenViking，
+ * 「启动」就应当是接管的启动——不只拉进程，还要把记忆链路整段拉就绪：
+ * ① 检查服务与配置（bin / ov.conf 定位，缺失即 failed + 指引改走「检查修复 / 一键安装」）
+ * ② 拉起并探活（受管拉起 + 最长 30s 探活；已在运行则 skipped，幂等重跑）
+ * ③ 接入记忆插件（CLI 市场渠道真实安装：已登记启用 → skipped；缺失 → marketplace add/install/enable
+ *  三步幂等安装，插件页可见可管理；CLI 失败回退 zip 下载自管副本）
+ * 完成后无须再点「检查修复」——启动结束即完整接管态。任何一步失败即停（同安装流水线语义）。
+ */
+export async function runStartPipeline(opts) {
+    if (installState.running)
+        return installState;
+    installState = { kind: 'start', running: true, startedAt: new Date().toISOString(), steps: START_STEPS() };
+    const steps = installState.steps;
+    const set = (id, status, detail) => {
+        const s = steps.find((x) => x.id === id);
+        s.status = status;
+        if (detail !== undefined)
+            s.detail = detail;
+    };
+    try {
+        // ① 定位 bin + conf（受管 conf 优先 → 外部 conf 兜底；缺失即挡下并给改道指引）
+        set('locate', 'running');
+        const uv = await detectUv();
+        const bin = uv ? await resolveServerBin(uv) : null;
+        if (!bin)
+            throw new Error('未检测到已安装的 OpenViking 服务（openviking-server）——请点「检查修复」自动补齐运行时与服务');
+        const confPath = existsSync(MANAGED_OV_CONF) ? MANAGED_OV_CONF
+            : existsSync(EXTERNAL_OV_CONF) ? EXTERNAL_OV_CONF : undefined;
+        if (!confPath)
+            throw new Error('未找到服务配置（ov.conf）——请点「检查修复」自动生成（需先在「模型配置」卡填好并保存）');
+        const external = confPath === EXTERNAL_OV_CONF;
+        set('locate', 'done', `服务：${bin}${external ? `；配置：${confPath}（外部，LCB 仅代为拉起、不改写）` : '；配置：受管 ov.conf'}`);
+        // ② 拉起 + 探活（已有受管实例且探活通过 → skipped）
+        set('launch', 'running');
+        let port = managed?.port;
+        let needLaunch = true;
+        if (managed && !managed.stopped) {
+            const h = await probeMemoryHealth(`http://127.0.0.1:${managed.port}`, 2000);
+            if (h.healthy) {
+                set('launch', 'skipped', `受管实例已在运行（127.0.0.1:${managed.port}）`);
+                needLaunch = false;
+            }
+            else {
+                stopManagedServer();
+            }
+        }
+        if (needLaunch) {
+            const r = await launchManagedAndWait(bin, confPath, readConfPort(confPath), external);
+            port = r.port;
+            set('launch', 'done', r.detail);
+        }
+        // ③ 插件接入（启动完整性的另一半：插件缺失时记忆照样不工作——补齐并回写显式引用；
+        //    client 传 endpoint/account：顺带落客户端接入配置 ovcli.conf，外部模式由 ensure 自守卫跳过）
+        set('plugin', 'running');
+        const pl = await stepPlugin({
+            endpoint: `http://127.0.0.1:${port ?? 1933}`,
+            account: await memoryAccount(opts.configPath),
+        });
+        set('plugin', pl.skipped ? 'skipped' : 'done', pl.detail);
+        if (pl.writeback) {
+            // 插件新装/调和才回写：受管场景顺带对齐 endpoint/mode；外部场景不动用户配置（只补插件引用）
+            writeBackConfig(opts.configPath, external ? {} : { endpoint: `http://127.0.0.1:${port ?? 1933}`, mode: 'embedded' }, pl.writeback.pluginPath, pl.writeback.opts);
+        }
+        installState.running = false;
+        installState.finishedAt = new Date().toISOString();
+        return installState;
+    }
+    catch (e) {
+        installState.running = false;
+        installState.finishedAt = new Date().toISOString();
+        const failed = steps.find((x) => x.status === 'running');
+        if (failed) {
+            failed.status = 'failed';
+            failed.detail = e instanceof Error ? e.message : String(e);
+        }
+        return installState;
+    }
+}
+function spawnManaged(bin, confPath, port) {
+    const proc = spawn(bin, ['--config', confPath, '--host', '127.0.0.1', '--port', String(port)], {
+        windowsHide: true,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    managed = { proc, port, restarts: 0, stopped: false, confPath, startedAt: new Date().toISOString() };
+    proc.on('exit', () => {
+        if (!managed || managed.proc !== proc)
+            return;
+        if (managed.stopped) {
+            managed = undefined;
+            return;
+        }
+        // 崩溃自动重启（上限 3 次，防坏配置循环拉起刷屏）
+        if (managed.restarts < 3) {
+            managed.restarts += 1;
+            console.warn(`[memory] 受管服务退出，${2}s 后自动重启（第 ${managed.restarts}/3 次）：${bin}`);
+            setTimeout(() => {
+                if (managed && !managed.stopped && managed.restarts <= 3) {
+                    try {
+                        spawnManaged(bin, confPath, port);
+                    }
+                    catch (e) {
+                        console.error('[memory] 重启失败：', e);
+                    }
+                }
+            }, 2000);
+        }
+        else {
+            console.error('[memory] 受管服务连续崩溃 3 次，已停止自动重启——请检查 ov.conf 后在页面重新拉起');
+            managed = undefined;
+        }
+    });
+    proc.stderr?.on('data', (d) => {
+        const line = String(d).trim();
+        if (line)
+            console.warn('[memory-server]', line.slice(0, 300));
+    });
+}
+// ============ 步骤 5：插件 ============
+/** LCB 自管插件目录：zip 下载兜底路径的落点（CLI 市场渠道失败时；正常安装走 marketplace 登记，
+ *  插件页可见可管理），<根>/<版本>/ 版本目录化可并存 */
+const MANAGED_PLUGIN_ROOT = join(process.env.LCB_CONFIG_DIR ?? String(process.env.USERPROFILE ?? process.env.HOME ?? ''), '.lark-claudecode-bridge', 'plugins', MEMORY_PLUGIN_NAME);
+/** 自管目录最新合法副本：扫 MANAGED_PLUGIN_ROOT 下一层版本目录，取语义化版本最高且
+ *  plugin.json 在的（字符串比较会把 0.7.6 排在 0.7.11 后——按数字段比较）。目录缺失/无合法副本返回 null */
+function latestManagedCopy() {
+    let entries;
+    try {
+        entries = readdirSync(MANAGED_PLUGIN_ROOT, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    } // 目录不存在 = 从未下载过，正常态
+    const candidates = [];
+    for (const e of entries) {
+        if (!e.isDirectory())
+            continue;
+        const marker = join(MANAGED_PLUGIN_ROOT, e.name, '.claude-plugin', 'plugin.json');
+        if (!existsSync(marker))
+            continue;
+        let version = e.name;
+        try {
+            version = JSON.parse(readFileSync(marker, 'utf8')).version ?? e.name;
+        }
+        catch { /* 清单损坏按目录名 */ }
+        candidates.push({ path: join(MANAGED_PLUGIN_ROOT, e.name), version, parts: version.split('.').map((n) => parseInt(n, 10) || 0) });
+    }
+    if (candidates.length === 0)
+        return null;
+    candidates.sort((a, b) => {
+        for (let i = 0; i < 3; i++) {
+            const d = (a.parts[i] ?? 0) - (b.parts[i] ?? 0);
+            if (d)
+                return d;
+        }
+        return 0;
+    });
+    return candidates[candidates.length - 1];
+}
+/**
+ * 记忆插件三渠道定位（状态页与安装流水线的共用口径，取代「只看 marketplace」的旧探测——
+ * CLI 卸载只清 installed_plugins.json/enabledPlugins 登记，config.yaml 显式引用与自管副本
+ * 依旧在工作的场景曾被误报「未安装」）。探测顺序对齐 resolvePluginPaths 的装配语义
+ * （同名显式优先）：运行时实际加载谁，状态就报谁。
+ * ① config.yaml apps[].plugins 显式引用（任意 bot 命中即可；路径须 plugin.json 在——SDK 对
+ *    无效路径静默跳过，死路径按未装处理，交给修复流水线改指）；
+ * ② marketplace 自动发现（与 executeTask 同款双目录口径）；
+ * ③ LCB 自管副本（仅 opts.includeManaged=true 时计入——未被引用的副本运行时不会加载，
+ *    状态页不算已装；修复流水线算，据其免重装并回写补引用）。
+ * 全程容错：单渠道异常按未命中继续，全 miss 返回 null。
+ */
+export async function locateMemoryPlugin(config, opts = {}) {
+    for (const app of config.apps ?? []) {
+        const ref = (app.plugins ?? []).find((p) => p.name === MEMORY_PLUGIN_NAME);
+        if (ref?.path && existsSync(join(ref.path, '.claude-plugin', 'plugin.json'))) {
+            return { path: ref.path, where: 'explicit' };
+        }
+    }
+    try {
+        const { discoverPlugins } = await import('./executor/plugin-discovery.js');
+        const { DEFAULT_CLAUDE_DIR, resolveClaudeDir } = await import('./claude-config.js');
+        const claudeDir = resolveClaudeDir(config);
+        const dirs = claudeDir === DEFAULT_CLAUDE_DIR ? [claudeDir] : [claudeDir, DEFAULT_CLAUDE_DIR];
+        for (const d of dirs) {
+            const found = discoverPlugins(d).find((p) => p.name === MEMORY_PLUGIN_NAME);
+            if (found) {
+                return {
+                    path: found.path, where: 'marketplace',
+                    ...(found.version ? { version: found.version } : {}),
+                    ...(found.marketplace ? { marketplace: found.marketplace } : {}),
+                };
+            }
+        }
+    }
+    catch { /* 插件发现容错契约（配置损坏等）：本渠道按未命中继续 */ }
+    if (opts.includeManaged) {
+        const managed = latestManagedCopy();
+        if (managed)
+            return { path: managed.path, where: 'managed', version: managed.version };
+    }
+    return null;
+}
+/** installed_plugins.json（v2）合并登记：保留既有插件条目，仅 upsert 本插件（scope=user）。
+ *  文件缺失/损坏重建为最小合法文档；installedAt 沿用旧值（重装不洗安装时间）。
+ *  exported 便于单测验证合并语义 */
+export function registerInstalledPlugin(claudeDir, key, item) {
+    const path = join(claudeDir, 'plugins', 'installed_plugins.json');
+    const doc = (() => {
+        try {
+            const parsed = JSON.parse(readFileSync(path, 'utf8'));
+            if (parsed.version === 2 && parsed.plugins && typeof parsed.plugins === 'object') {
+                return { version: 2, plugins: parsed.plugins };
+            }
+        }
+        catch { /* 缺失/损坏 → 重建 */ }
+        return { version: 2, plugins: {} };
+    })();
+    const prev = Array.isArray(doc.plugins[key]) ? doc.plugins[key].find((e) => e.scope === 'user') : undefined;
+    const now = new Date().toISOString();
+    doc.plugins[key] = [{
+            scope: 'user',
+            installPath: item.installPath,
+            ...(item.version ? { version: item.version } : {}),
+            installedAt: prev?.installedAt ?? now,
+            lastUpdated: now,
+        }];
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(doc, null, 2), 'utf8');
+}
+/** settings.json enabledPlugins 启用（整体读改写保留其余键；文件缺失/损坏建最小对象）。
+ *  exported 便于单测验证保留语义 */
+export function enablePluginInSettings(claudeDir, key) {
+    const path = join(claudeDir, 'settings.json');
+    let doc = {};
+    try {
+        doc = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch { /* 缺失/损坏 → 新建 */ }
+    const ep = (doc.enabledPlugins && typeof doc.enabledPlugins === 'object' && !Array.isArray(doc.enabledPlugins))
+        ? doc.enabledPlugins : {};
+    ep[key] = true;
+    doc.enabledPlugins = ep;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(doc, null, 2), 'utf8');
+}
+/** 已登记市场名集合（known_marketplaces.json 键；url/github 源市场不物化清单副本，登记表即事实源） */
+function knownMarketplaceNames(claudeDir) {
+    try {
+        const doc = JSON.parse(readFileSync(join(claudeDir, 'plugins', 'known_marketplaces.json'), 'utf8'));
+        return new Set(Object.keys(doc));
+    }
+    catch {
+        return new Set();
+    } // 从未添加过任何市场
+}
+/**
+ * CLI 市场渠道真实安装：marketplace add（缺登记时）→ plugin install（缺装/产物失效时）
+ * → plugin enable（未启用时）→ discoverPlugins 终验（双登记 + 路径有效 = 任务装配可加载）。
+ * 三步各自幂等可重跑；产物路径从安装清单回读（installPath 供调和回写）。
+ * 任何一步失败返回 { detail } 不抛出——调用方回退 zip 下载兜底。
+ */
+async function cliInstallViaMarketplace(claudeDir, dirs) {
+    const { runPluginCli } = await import('./executor/plugin-manager.js');
+    const { discoverPlugins, listInstalledPlugins } = await import('./executor/plugin-discovery.js');
+    if (!knownMarketplaceNames(claudeDir).has(MARKETPLACE_NAME)) {
+        let lastErr = '';
+        for (const src of MARKETPLACE_ADD_SOURCES) {
+            const r = await runPluginCli(['marketplace', 'add', src], { claudeConfigDir: claudeDir });
+            if (r.ok && knownMarketplaceNames(claudeDir).has(MARKETPLACE_NAME)) {
+                lastErr = '';
+                break;
+            }
+            lastErr = r.text;
+        }
+        if (lastErr || !knownMarketplaceNames(claudeDir).has(MARKETPLACE_NAME)) {
+            return { detail: `注册市场 ${MARKETPLACE_NAME} 失败：${lastErr || '登记表未见该市场'}` };
+        }
+    }
+    // 安装（已装且产物在位则跳过；install 自带 -y 非交互确认）
+    const entry = listInstalledPlugins(claudeDir).find((p) => p.key === MARKETPLACE_KEY || p.name === MEMORY_PLUGIN_NAME);
+    if (!entry?.path || !existsSync(entry.path)) {
+        const r = await runPluginCli(['install', MARKETPLACE_KEY], { claudeConfigDir: claudeDir });
+        if (!r.ok)
+            return { detail: `安装 ${MARKETPLACE_KEY} 失败：${r.text}` };
+    }
+    // 启用（install 不保证 enabledPlugins 落 true；enable 对已启用为幂等 no-op）
+    const discoverHit = () => {
+        for (const d of dirs) {
+            const hit = discoverPlugins(d).find((p) => p.name === MEMORY_PLUGIN_NAME);
+            if (hit)
+                return hit.path;
+        }
+        return undefined;
+    };
+    if (!discoverHit()) {
+        const r = await runPluginCli(['enable', MARKETPLACE_KEY], { claudeConfigDir: claudeDir });
+        if (!r.ok)
+            return { detail: `启用 ${MARKETPLACE_KEY} 失败：${r.text}` };
+    }
+    const installPath = discoverHit();
+    return installPath
+        ? { detail: `已安装并启用：${installPath}`, installPath }
+        : { detail: `安装动作已完成但未能自动发现 ${MARKETPLACE_KEY}（installed_plugins/enabledPlugins 未生效，请反馈）` };
+}
+/** 接入记忆插件（安装流水线第 5 步/启动流水线第 3 步共用；exported 便于运维脚本与单测直调）：
+ *  ① CLI marketplace 双登记命中 → skipped；② CLI 真实安装（幂等）；③ zip 兜底 + CLI 同构登记。
+ *  client 传入时（endpoint/account）同时落客户端接入配置 ovcli.conf（§6.7 第 4 步：插件启用判定
+ *  的文件兜底层；写入失败只 warn 不阻塞插件接入——LCB 会话另有 env 通道兜底） */
+export async function stepPlugin(client) {
+    // 客户端配置先落（三个 return 分支都要携带：①分支是高频提前 return——「已装但无文件」的
+    // 存量机器最常见形态，放函数体后段会漏掉）
+    let clientConf;
+    if (client) {
+        try {
+            clientConf = ensureClientCliConf(client);
+        }
+        catch (e) {
+            console.warn('[memory-installer] ovcli.conf 写入失败（不阻塞插件接入）：', e instanceof Error ? e.message : e);
+        }
+    }
+    const detailSuffix = clientConf ? `；客户端配置 ${clientConf}` : '';
+    const { loadConfig } = await import('./config.js');
+    const { DEFAULT_CLAUDE_DIR, resolveClaudeDir } = await import('./claude-config.js');
+    let claudeDir = DEFAULT_CLAUDE_DIR;
+    try {
+        claudeDir = resolveClaudeDir(loadConfig());
+    }
+    catch { /* 配置损坏按默认目录装配口径 */ }
+    const dirs = claudeDir === DEFAULT_CLAUDE_DIR ? [claudeDir] : [claudeDir, DEFAULT_CLAUDE_DIR];
+    // ① CLI marketplace 双登记命中 = 完整安装态（插件页可见、可启停可更新）。仍携带调和回写：
+    //    把产物域旧显式引用对齐当前登记版本（writeBackConfig 值一致时零写盘，幂等）——否则
+    //    CLI update 装新版后旧引用仍钉死旧版本目录，运行时与插件页版本错位
+    try {
+        const { discoverPlugins } = await import('./executor/plugin-discovery.js');
+        for (const d of dirs) {
+            const hit = discoverPlugins(d).find((p) => p.name === MEMORY_PLUGIN_NAME);
+            if (hit)
+                return {
+                    skipped: true,
+                    detail: `已安装（CLI marketplace 已启用）：${hit.path}${detailSuffix}`,
+                    clientConf,
+                    writeback: {
+                        pluginPath: hit.path,
+                        opts: { reconcileOnly: true, artifactRoots: [...dirs.map((x) => join(x, 'plugins', 'cache')), MANAGED_PLUGIN_ROOT] },
+                    },
+                };
+        }
+    }
+    catch { /* 发现容错契约：继续走安装 */ }
+    // ② CLI 市场渠道真实安装（幂等可重跑）。成功即调和 config.yaml：把指向旧安装产物
+    //    （plugins/cache / 自管副本域）或已失效路径的显式引用就地改指新 installPath——
+    //    不新增引用（发现渠道已覆盖加载），用户显式指的 dev 目录不动（reconcileOnly 语义）
+    const cli = await cliInstallViaMarketplace(claudeDir, dirs);
+    if (cli.installPath) {
+        return {
+            skipped: false,
+            detail: `${cli.detail}（插件页可见，可启停/更新）${detailSuffix}`,
+            clientConf,
+            writeback: {
+                pluginPath: cli.installPath,
+                opts: { reconcileOnly: true, artifactRoots: [...dirs.map((d) => join(d, 'plugins', 'cache')), MANAGED_PLUGIN_ROOT] },
+            },
+        };
+    }
+    console.warn(`[memory-installer] CLI 市场安装未成功，回退自管下载：${cli.detail}`);
+    // ③ 兜底：CLI 市场安装不可用（partial-clone blob 拉取被网络掐断等）→ 仍以 CLI 同构状态落地：
+    //    codeload 全量归档（实测比 partial-clone 稳定）→ 解出插件子目录 → 物化到 CLI 缓存布局
+    //    plugins/cache/<市场>/<插件>/<版本>/ → 合并登记（installed_plugins.json v2 + enabledPlugins）
+    //    → 插件页可见、CLI enable/disable/uninstall 均原生可用，与 ② 成功态完全等价
+    // 下载主仓库归档 → 取 examples/claude-code-memory-plugin → 校验 plugin.json → 拷入缓存布局
+    const isWin = process.platform === 'win32';
+    const ref = 'main'; // pin 到 tag 的能力随 memory.version 演进（版本受控，风险 8.4）
+    const tmp = mkdtempSync(join(tmpdir(), 'lcb-ovp-'));
+    try {
+        const archive = join(tmp, isWin ? 'repo.zip' : 'repo.tgz');
+        await downloadTo(isWin ? PLUGIN_REPO_ZIP(ref) : PLUGIN_REPO_TGZ(ref), archive);
+        // 只提取需要的子目录成员（实测教训：整仓解压时无关条目会触发 bsdtar 的 \\?\ 长路径 bug
+        // 报错退出；且只取子目录比解 60MB 全仓快得多）。成员名与 codeload 解包根一致
+        const member = `OpenViking-${ref}/${PLUGIN_SUBDIR}`;
+        const t = tarCommand();
+        await run(t.cmd, [...t.args, '-xf', archive, '-C', tmp, member], { timeoutMs: 180_000 });
+        const srcRoot = join(tmp, `OpenViking-${ref}`, ...PLUGIN_SUBDIR.split('/'));
+        const marker = join(srcRoot, '.claude-plugin', 'plugin.json');
+        if (!existsSync(marker))
+            throw new Error('归档中未找到 examples/claude-code-memory-plugin/.claude-plugin/plugin.json（上游结构可能已变化）');
+        // 版本目录化（升级可并存）：读 plugin.json 的 version
+        const pkg = JSON.parse(readFileSync(marker, 'utf8'));
+        const version = pkg.version ?? '0.0.0';
+        const dest = join(claudeDir, 'plugins', 'cache', MARKETPLACE_NAME, MEMORY_PLUGIN_NAME, version);
+        mkdirSync(dirname(dest), { recursive: true });
+        rmSync(dest, { recursive: true, force: true });
+        await run(process.platform === 'win32' ? 'xcopy' : 'cp', process.platform === 'win32'
+            ? [srcRoot, dest, '/E', '/I', '/Q', '/Y']
+            : ['-r', srcRoot, dest], { timeoutMs: 60_000 });
+        if (!existsSync(join(dest, '.claude-plugin', 'plugin.json')))
+            throw new Error('插件拷贝后校验失败');
+        // CLI 同构登记 + 启用（幂等合并写，保留既有条目/其余键），清发现缓存让本进程立即可见
+        registerInstalledPlugin(claudeDir, MARKETPLACE_KEY, { installPath: dest, version });
+        enablePluginInSettings(claudeDir, MARKETPLACE_KEY);
+        const { invalidatePluginCache } = await import('./executor/plugin-discovery.js');
+        invalidatePluginCache(claudeDir);
+        return {
+            skipped: false,
+            detail: `已安装 v${version}（CLI 同构登记）→ ${dest}（插件页可见，可启停/更新）${detailSuffix}`,
+            clientConf,
+            writeback: {
+                pluginPath: dest,
+                opts: { reconcileOnly: true, artifactRoots: [...dirs.map((d) => join(d, 'plugins', 'cache')), MANAGED_PLUGIN_ROOT] },
+            },
+        };
+    }
+    finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+}
+// ============ config.yaml 定向写（保注释，YAML AST set） ============
+/** 原子写（tmp + rename）：与 web/server.ts / claude-profile.ts 的 writeAtomic 同款实现，独立内联避免反向依赖 */
+function writeAtomic(path, text) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp-${Date.now()}`;
+    writeFileSync(tmp, text, 'utf8');
+    renameSync(tmp, path);
+}
+/** 只写 memory 段的指定键（endpoint/mode/api_key，仅写提供的键）与 apps[].plugins 显式引用；值未变跳过不重写。
+ *  exported 便于单测直接验证（YAML AST 保注释 / 幂等重写行为） */
+export function writeBackConfig(configPath, wb, pluginPath, opts = {}) {
+    const raw = readFileSync(configPath, 'utf8');
+    const doc = parseDocument(raw);
+    let changed = false;
+    const mem = doc.get('memory');
+    const ensureSet = (node, key, val) => {
+        if (val !== undefined && JSON.stringify(node.get(key)) !== JSON.stringify(val)) {
+            node.set(key, val);
+            changed = true;
+        }
+    };
+    if (mem && typeof mem === 'object') {
+        ensureSet(mem, 'endpoint', wb.endpoint);
+        ensureSet(mem, 'mode', wb.mode);
+        if (wb.apiKey)
+            ensureSet(mem, 'api_key', wb.apiKey);
+    }
+    else if (wb.endpoint) {
+        doc.set('memory', { enabled: true, mode: wb.mode ?? 'embedded', endpoint: wb.endpoint, ...(wb.apiKey ? { api_key: wb.apiKey } : {}) });
+        changed = true;
+    }
+    if (pluginPath) {
+        // YAMLSeq 非原生 Array（Array.isArray 恒 false）——统一经 .items 访问成员；追加节点用
+        // doc.createNode 包装（官方 API，普通对象 → YAML 节点），避免裸对象进 AST 的序列化歧义
+        const apps = doc.get('apps');
+        for (const app of apps?.items ?? []) {
+            const appNode = app;
+            if (!appNode || typeof appNode.get !== 'function')
+                continue;
+            const plugins = appNode.get('plugins');
+            // 同名条目就地更新而非整跳过（实测缺陷：CLI 卸载后旧引用指向已失效路径，按名去重
+            // 恒跳过 → 修复装好的新副本永远接不进配置）：路径一致 = 幂等不写；不同 = 改指新路径
+            const existing = (plugins?.items ?? []).find((p) => p?.get?.('name') === MEMORY_PLUGIN_NAME);
+            if (existing) {
+                const cur = existing.get('path');
+                if (cur === pluginPath)
+                    continue;
+                if (opts.reconcileOnly) {
+                    // 调和口径：旧路径属产物域（cache/自管根）或已不存在/为空 → 改指；其余（用户显式
+                    // 指的 dev 源码目录等）不动——CLI 安装后运行时经发现渠道取新版，显式 dev 引用照旧生效
+                    const curStr = typeof cur === 'string' ? cur : '';
+                    const artifact = !curStr || !existsSync(curStr)
+                        || (opts.artifactRoots ?? []).some((root) => curStr.startsWith(root));
+                    if (!artifact)
+                        continue;
+                }
+                existing.set('path', pluginPath);
+                changed = true;
+                continue;
+            }
+            if (opts.reconcileOnly)
+                continue; // 调和模式不新增引用（发现渠道已覆盖，新增反而钉死版本路径）
+            if (plugins && Array.isArray(plugins.items)) {
+                plugins.items.push(doc.createNode({ name: MEMORY_PLUGIN_NAME, path: pluginPath }));
+            }
+            else {
+                appNode.set('plugins', doc.createNode([{ name: MEMORY_PLUGIN_NAME, path: pluginPath }]));
+            }
+            changed = true;
+        }
+    }
+    if (!changed)
+        return;
+    writeAtomic(configPath, doc.toString({ lineWidth: 0 }));
+}
+// ============ 主流水线 ============
+/** 读 config.yaml 的 memory.account（懒加载；损坏配置降级 undefined → 渲染取缺省 'lcb'）。
+ *  两条流水线原本不读 config.yaml（只有 configPath），stepPlugin 落 ovcli.conf 时需要它 */
+async function memoryAccount(configPath) {
+    try {
+        const { loadConfig } = await import('./config.js');
+        return loadConfig(configPath).memory?.account;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 一键安装流水线（幂等锁：running 中重复调用直接返回当前状态）。
+ * 任何一步失败即停（状态留 failed + detail），页面可整链重跑——已就绪步骤自动 skipped。
+ */
+export async function runInstall(opts) {
+    if (installState.running)
+        return installState;
+    installState = { kind: 'install', running: true, startedAt: new Date().toISOString(), steps: FRESH_STEPS() };
+    const steps = installState.steps;
+    const set = (id, status, detail) => {
+        const s = steps.find((x) => x.id === id);
+        s.status = status;
+        if (detail !== undefined)
+            s.detail = detail;
+    };
+    try {
+        // 首装生成的 root_api_key（conf 步骤产出，⑥ 回写消费；重装/沿用场景为 undefined）
+        let firstInstallKey;
+        // ① uv
+        set('runtime', 'running');
+        let uv = await detectUv();
+        if (uv)
+            set('runtime', 'skipped', `已检测到 uv：${uv === 'uv' ? 'PATH' : uv}`);
+        else {
+            uv = await installUv();
+            set('runtime', 'done', `已安装到 ${uv}`);
+        }
+        // ② 服务
+        set('service', 'running');
+        const svc = await stepService(uv, opts.pin ?? DEFAULT_OPENVIKING_PIN);
+        set('service', svc.skipped ? 'skipped' : 'done', svc.detail);
+        // ③ ov.conf（模型缺失 + conf 已存在 = 重跑：沿用现值；端口沿用已分配值，避免每次重跑漂移）
+        set('config', 'running');
+        // 首装前置校验（实测教训：空模型 conf 会让服务启动即崩、反复重启后才暴露——在生成配置
+        // 这一步就把缺件挡下并给出指引，而不是让坏 conf 落盘）。conf 已存在（重跑/升级）则放行：
+        // 现值来自上次有效安装
+        const confExists = existsSync(MANAGED_OV_CONF);
+        const m = opts.model;
+        if (!confExists && (!m || !m.apiBase || !m.vlmModel || !m.embeddingModel)) {
+            throw new Error('首装需要记忆模型三件套：api_base / vlm_model（提炼）/ embedding_model（向量）——请先在「记忆模型配置」卡填表并保存（可先 [测试连接] 验证），再点一键开启');
+        }
+        if (confExists && !m) {
+            // 重跑且未传模型：沿用现有 conf 原文（不重渲染——重渲染空模型会生成坏 conf 且更换 root_api_key）
+            set('config', 'skipped', `沿用现有配置：${MANAGED_OV_CONF}`);
+        }
+        else {
+            const model = m;
+            const prevRootKey = existingRootKey();
+            const prevPort = (() => { try {
+                return JSON.parse(readFileSync(MANAGED_OV_CONF, 'utf8')).server?.port;
+            }
+            catch {
+                return undefined;
+            } })();
+            const port = prevPort ?? await findFreePort();
+            const { conf, rootApiKey } = renderOvConf(model, {
+                workspaceDir: join(MEMORY_MANAGED_DIR, 'data'),
+                port,
+                rootApiKey: prevRootKey,
+            });
+            mkdirSync(MEMORY_MANAGED_DIR, { recursive: true });
+            mkdirSync(join(MEMORY_MANAGED_DIR, 'data'), { recursive: true });
+            writeFileSync(MANAGED_OV_CONF, JSON.stringify(conf, null, 2), 'utf8');
+            // 首装（此前无 root_api_key）→ 本次生成的 key 需回写 memory.api_key；重装沿用则不写
+            firstInstallKey = prevRootKey ? undefined : rootApiKey;
+            set('config', 'done', `配置已生成：${MANAGED_OV_CONF}（端口 ${port}）`);
+        }
+        // ④ 拉起
+        set('start', 'running');
+        const st = await stepStart(svc.bin, MANAGED_OV_CONF);
+        set('start', st.skipped ? 'skipped' : 'done', st.detail);
+        // ⑤ 插件（client 传 endpoint/account：顺带落客户端接入配置 ovcli.conf，§6.7 第 4 步）
+        set('plugin', 'running');
+        const pl = await stepPlugin({
+            endpoint: `http://127.0.0.1:${st.port}`,
+            account: await memoryAccount(opts.configPath),
+        });
+        set('plugin', pl.skipped ? 'skipped' : 'done', pl.detail);
+        // ⑥ 回写 config.yaml——全链成功才落盘（半成品不污染用户配置）：endpoint / mode=embedded /
+        // 首装生成的 root_api_key 回写 memory.api_key（复用已有 key 不写）+ 插件引用回写（CLI 渠道为
+        // 调和模式、zip 兜底为补齐模式，选项由 stepPlugin 携带）
+        writeBackConfig(opts.configPath, {
+            endpoint: `http://127.0.0.1:${st.port}`,
+            mode: 'embedded',
+            ...(firstInstallKey ? { apiKey: firstInstallKey } : {}),
+        }, pl.writeback?.pluginPath, pl.writeback?.opts);
+        installState.running = false;
+        installState.finishedAt = new Date().toISOString();
+        return installState;
+    }
+    catch (e) {
+        installState.running = false;
+        installState.finishedAt = new Date().toISOString();
+        const failed = steps.find((x) => x.status === 'running');
+        if (failed) {
+            failed.status = 'failed';
+            failed.detail = e instanceof Error ? e.message : String(e);
+        }
+        return installState;
+    }
+}
+//# sourceMappingURL=memory-installer.js.map