mooncat-browser 0.1.0 → 0.2.1

package/dist/cli.js

@@ -1,39 +1,60 @@
+#!/usr/bin/env node
 // -*- coding: utf-8 -*-
 // cli.ts — mooncat-browser 命令行入口。
 //
-// 命令：
-//   mooncat-browser start [--port 17322] [--profile D:\p] [--chrome path] [--health-port 17440]
-//   mooncat-browser health [--port 17322]
-//   mooncat-browser stop [--port 17322]
-//   mooncat-browser open --url <url> [--port 17322]
-//   mooncat-browser install-extension
-//   mooncat-browser skills [--skill <name>] [--target <dir>] [--list]
+// mooncat-browser 是独立包:不写全局 appData,不假设 mooncat space 目录。
+// 所有运行数据由项目配置(config/browser.json 或 mooncat-browser.config.json)显式声明。
 //
-// --port 语义 = browserd RPC 端口（client 连这里，默认 17322）。
-// start 还会顺带起一个 wrapper health 端口（--health-port，默认 17440），供 stop/监控用。
+// 命令:
+//   mooncat-browser init [name]                    初始化项目配置 + 数据目录
+//   mooncat-browser start <name>                   启动实例(wrapper + browserd + Chrome)
+//   mooncat-browser start <name> --temp            临时实例(系统 temp,退出清理)
+//   mooncat-browser stop <name>                    graceful 停止实例
+//   mooncat-browser status <name>                  查实例运行状态
+//   mooncat-browser health <name>                  探测 browserd 是否就绪
+//   mooncat-browser open <name> --url <url>        打开/复用浏览器并导航
+//   mooncat-browser list                           列出配置里的实例 + 运行状态
+//   mooncat-browser install-extension              打印 WebPlater 扩展路径
+//   mooncat-browser skills [--skill <name>]        安装内置 skills
+//
+// <name> 是 config 里 instances 的 key(默认实例叫 default)。
+// --rpc-port / --health-port / --profile 等作为高级覆盖(覆盖配置文件值)。
 import { Command } from "commander";
 import { createRequire } from "node:module";
-import { resolveConfig } from "./config.js";
 import { BrowserClient } from "./client.js";
 import { startService, readServiceState, serviceStatePath, browserdScriptPath } from "./server.js";
+import { defaultInstanceEntry, findProjectConfig, InstanceNotFoundError, listInstanceNames, loadInstance, NotInitializedError, tempInstance, } from "./instance.js";
+import { prepareExtension, verifyInstanceExtension } from "./prepare-extension.js";
 import { fileURLToPath } from "node:url";
-import { homedir } from "node:os";
 import { join } from "node:path";
-import { cpSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 const require = createRequire(import.meta.url);
 const __dirname = fileURLToPath(new URL(".", import.meta.url));
-/** webplater 扩展已构建产物目录（install-extension 指向这里）。 */
+/** webplater 扩展已构建产物目录(install-extension 指向这里)。 */
 function extensionDistDir() {
     return process.env.MOONCAT_BROWSER_EXTENSION || join(__dirname, "..", "browser-op", "webplater", "dist", "chrome-mv3");
 }
 function printHeader(title) {
     console.log(`\n[mooncat-browser] ${title}`);
 }
-/** 构造 client（按 --port / env / default）。 */
-function makeClient(port) {
-    return new BrowserClient({ port });
+/** 把 commander 解析的 opts 转成 CliOverrides(只取高级覆盖字段)。 */
+function optsToOverrides(opts) {
+    const num = (v) => (typeof v === "number" ? v : undefined);
+    const str = (v) => (typeof v === "string" ? v : undefined);
+    return {
+        rpcPort: num(opts.rpcPort) ?? num(opts.port),
+        port: num(opts.port) ?? num(opts.rpcPort),
+        healthPort: num(opts.healthPort),
+        extensionPort: num(opts.extensionPort),
+        profileDir: str(opts.profile),
+        stateDir: str(opts.stateDir),
+        logsDir: str(opts.logsDir),
+        extensionDir: str(opts.extensionDir),
+        chromePath: str(opts.chrome),
+        routeMode: str(opts.routeMode),
+    };
 }
-/** 轮询 rpcPort，直到连不上（browserd 已退）或超时。返回 true 表示已退出。 */
+/** 轮询 rpcPort,直到连不上(browserd 已退)或超时。返回 true 表示已退出。 */
 async function waitForExit(rpcPort, timeoutMs) {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
@@ -41,7 +62,7 @@ async function waitForExit(rpcPort, timeoutMs) {
             await fetch(`http://127.0.0.1:${rpcPort}/health`, {
                 signal: AbortSignal.timeout(1000),
             });
-            // 还活着，继续等
+            // 还活着,继续等
         }
         catch {
             return true; // 连不上 = 已退
@@ -50,72 +71,243 @@ async function waitForExit(rpcPort, timeoutMs) {
     }
     return false;
 }
+/** 友好处理 NotInitializedError / InstanceNotFoundError,其它原样抛。 */
+function handleConfigError(e) {
+    if (e instanceof NotInitializedError || e instanceof InstanceNotFoundError) {
+        console.error(`\n[mooncat-browser] ${e.message}`);
+        process.exit(1);
+    }
+    throw e;
+}
+/**
+ * 判断实例是否真在跑且 state 与响应进程对得上。
+ * 只 curl 到 health 端口不够——可能是上一个僵尸 wrapper 占着端口。
+ * 必须校验响应里的 wrapperPid == state.pid,才是这个 state 对应的进程在响应。
+ * 返回: "running" | "stale"(state 有但进程不对/没响应)| "stopped"(无 state)。
+ */
+async function realInstanceStatus(cfg) {
+    const state = readServiceState(cfg);
+    if (!state)
+        return "stopped";
+    try {
+        const resp = await fetch(`http://127.0.0.1:${state.healthPort}/health`, {
+            signal: AbortSignal.timeout(1000),
+        });
+        if (!resp.ok)
+            return "stale";
+        const body = (await resp.json());
+        // wrapperPid 对得上 state.pid = 这个 state 的进程还活着
+        if (typeof body.wrapperPid === "number" && body.wrapperPid === state.pid)
+            return "running";
+        // 端口响应了但 pid 不是 state 记录的 = 僵尸/被占用
+        return "stale";
+    }
+    catch {
+        return "stale";
+    }
+}
 async function run() {
     const program = new Command();
     program
         .name("mooncat-browser")
-        .description("浏览器自动化工具包：可独立启动的本地服务 + JS/TS client")
+        .description("浏览器自动化工具包:可独立启动的本地服务 + JS/TS client (实例化、项目级配置)")
         .version(getVersion());
+    // ─── init ───────────────────────────────────────────────────────────────
+    program
+        .command("init [name]")
+        .description("初始化项目配置 + 数据目录(默认实例名 default)")
+        .option("--dir <path>", "数据根目录(默认 .browser)")
+        .action((name, opts) => {
+        const instName = name || "default";
+        const dataRoot = opts.dir || ".browser";
+        const cwd = process.cwd();
+        // 选 config/browser.json 作为默认配置文件(config/ 目录更直观)
+        const cfgDir = join(cwd, "config");
+        const cfgPath = join(cfgDir, "browser.json");
+        if (existsSync(cfgPath)) {
+            console.error(`\n[mooncat-browser] config already exists: ${cfgPath}`);
+            console.error(`  to add an instance, edit it manually or remove it first`);
+            process.exit(1);
+        }
+        mkdirSync(cfgDir, { recursive: true });
+        const entry = {
+            ...defaultInstanceEntry(instName),
+            profileDir: `${dataRoot}/${instName}/profile`,
+            stateDir: `${dataRoot}/${instName}/state`,
+            logsDir: `${dataRoot}/${instName}/logs`,
+            extensionDir: `${dataRoot}/${instName}/extension`,
+        };
+        const file = { instances: { [instName]: entry } };
+        writeFileSync(cfgPath, JSON.stringify(file, null, 2) + "\n", "utf8");
+        // 预创建数据目录(加 .gitkeep,方便进版本库)。extension 目录不预创建——
+        // 它由 prepare-extension 命令显式生成(含占位符替换),不该手动建空壳。
+        for (const sub of ["profile", "state", "logs"]) {
+            const d = join(cwd, dataRoot, instName, sub);
+            mkdirSync(d, { recursive: true });
+            writeFileSync(join(d, ".gitkeep"), "", "utf8");
+        }
+        printHeader(`initialized`);
+        console.log(`  config   : ${cfgPath}`);
+        console.log(`  instance : ${instName}`);
+        console.log(`  data     : ${dataRoot}/${instName}/{profile,state,logs}`);
+        console.log(`\n  next:`);
+        console.log(`    mooncat-browser start ${instName}            # CDP 路直跑`);
+        console.log(`    mooncat-browser prepare-extension ${instName} # extension 路需先生成扩展目录`);
+    });
+    // ─── prepare-extension ──────────────────────────────────────────────────
+    program
+        .command("prepare-extension <name>")
+        .description("为实例生成 unpacked 扩展目录(替换 WS 端口占位符;然后手动 load unpacked 到 profileDir)")
+        .action((name, opts) => {
+        let cfg;
+        try {
+            const handle = findProjectConfig(process.cwd());
+            cfg = loadInstance(name, handle, optsToOverrides(opts));
+        }
+        catch (e) {
+            handleConfigError(e);
+            return;
+        }
+        printHeader(`prepare extension for instance "${name}"`);
+        try {
+            const { replacedFiles, metadata, templateDir } = prepareExtension(cfg);
+            console.log(`  template      : ${templateDir}`);
+            console.log(`  target        : ${cfg.extensionDir}`);
+            console.log(`  extensionPort : ${cfg.extensionPort}`);
+            console.log(`  hostWsUrl     : ${metadata.hostWsUrl}`);
+            console.log(`  replaced files: ${replacedFiles}`);
+            console.log(`  build version : ${metadata.sourceBuildVersion}`);
+            console.log(`\n  next: 手动 load unpacked 到本实例的 Chrome profile`);
+            console.log(`    1. mooncat-browser start ${name} --route-mode extension`);
+            console.log(`    2. Chrome -> chrome://extensions -> 开发者模式 -> 加载已解压的扩展程序`);
+            console.log(`    3. 选择目录: ${cfg.extensionDir}`);
+            console.log(`    4. 重启浏览器(close + open)走 extension 路`);
+        }
+        catch (e) {
+            console.error(`\n  [ERROR] prepare failed: ${e.message}`);
+            process.exit(1);
+        }
+    });
     // ─── start ──────────────────────────────────────────────────────────────
     program
-        .command("start")
-        .description("启动 browser 服务（wrapper + browserd 常驻）")
-        .option("-p, --port <port>", "browserd RPC 端口（client 连这里，默认 17322）", (v) => Number(v))
+        .command("start <name>")
+        .description("启动实例(wrapper + browserd 常驻 + Chrome)")
+        .option("-p, --port <port>", "高级覆盖:browserd RPC 端口", (v) => Number(v))
         .option("--rpc-port <port>", "同 --port", (v) => Number(v))
-        .option("--health-port <port>", "wrapper health 端口（默认 17440）", (v) => Number(v))
-        .option("--profile <path>", "Chrome user-data-dir（默认 %LOCALAPPDATA%\\mooncat-browser\\profile）")
-        .option("--chrome <path>", "Chrome 可执行文件路径（不传则自动探测）")
-        .action(async (opts) => {
-        const cfg = resolveConfig({
-            port: opts.port ?? opts.rpcPort,
-            healthPort: opts.healthPort,
-            profile: opts.profile,
-            chromePath: opts.chrome,
-        });
-        printHeader(`starting service`);
-        console.log(`  rpc port    : ${cfg.rpcPort}  (clients connect here)`);
-        console.log(`  health port : ${cfg.healthPort}`);
-        console.log(`  profile     : ${cfg.profile}`);
-        console.log(`  chrome      : ${cfg.chromePath || "(auto-detect)"}`);
-        console.log(`  logs        : ${cfg.logsDir}`);
-        console.log(`  browserd    : ${browserdScriptPath()}`);
+        .option("--health-port <port>", "高级覆盖:wrapper health 端口", (v) => Number(v))
+        .option("--extension-port <port>", "高级覆盖:extension WS 端口(第一版不消费)", (v) => Number(v))
+        .option("--profile <path>", "高级覆盖:Chrome user-data-dir")
+        .option("--state-dir <path>", "高级覆盖:wrapper/browserd 状态目录")
+        .option("--logs-dir <path>", "高级覆盖:日志目录")
+        .option("--chrome <path>", "高级覆盖:Chrome 可执行文件路径")
+        .option("--route-mode <mode>", "高级覆盖:路由模式(auto|cdp|extension)")
+        .option("--temp", "临时实例(系统 temp,退出清理,不读项目配置)")
+        .action(async (name, opts) => {
+        let cfg;
+        let cleanup = null;
+        try {
+            if (opts.temp) {
+                const t = tempInstance(name, optsToOverrides(opts));
+                cfg = t.cfg;
+                cleanup = t.cleanup;
+            }
+            else {
+                const handle = findProjectConfig(process.cwd());
+                cfg = loadInstance(name, handle, optsToOverrides(opts));
+            }
+        }
+        catch (e) {
+            handleConfigError(e);
+            return;
+        }
+        printHeader(`starting instance "${cfg.name}"`);
+        console.log(`  rpc port      : ${cfg.rpcPort}  (clients connect here)`);
+        console.log(`  health port   : ${cfg.healthPort}`);
+        console.log(`  extension port: ${cfg.extensionPort}  (WS port for WebPlater extension)`);
+        console.log(`  profile       : ${cfg.profileDir}`);
+        console.log(`  state         : ${cfg.stateDir}`);
+        console.log(`  logs          : ${cfg.logsDir}`);
+        console.log(`  extension dir : ${cfg.extensionDir}`);
+        console.log(`  chrome        : ${cfg.chromePath || "(auto-detect)"}`);
+        console.log(`  browserd      : ${browserdScriptPath()}`);
+        if (opts.temp)
+            console.log(`  mode          : TEMP (cleaned on exit)`);
+        // route=extension 前置检查:实例 extensionDir 必须先 prepare。
+        // route=cdp/auto 不需要(temp 也不需要)。
+        const wantExtension = cfg.routeMode === "extension";
+        if (wantExtension && !opts.temp) {
+            const issue = verifyInstanceExtension(cfg);
+            if (issue) {
+                console.error(`\n  [ERROR] extension 目录未就绪: ${issue}`);
+                console.error(`  run: mooncat-browser prepare-extension ${cfg.name}`);
+                if (cleanup)
+                    cleanup();
+                process.exit(1);
+            }
+        }
         try {
             await startService(cfg);
-            console.log(`\n  service running. Ctrl+C to stop, or: mooncat-browser stop --port ${cfg.rpcPort}`);
+            console.log(`\n  service running. Ctrl+C to stop, or: mooncat-browser stop ${cfg.name}`);
         }
         catch (e) {
+            if (cleanup)
+                cleanup();
+            // 失败时清理 state 文件:BrowserService.start() 在 spawn 前就写了 service.json,
+            // 启动失败(EADDRINUSE 等)后若不删,残留 state 会误导 list/status 误报 running。
+            try {
+                unlinkSyncSafe(serviceStatePath(cfg));
+            }
+            catch { /* ignore */ }
             console.error(`\n  [ERROR] failed to start: ${e.message}`);
             process.exit(1);
         }
+        // temp 模式:wrapper 退出时清理(SIGINT/SIGTERM 走 stop(),process.exit 前也清)
+        if (cleanup) {
+            process.on("exit", () => cleanup());
+        }
     });
     // ─── health ─────────────────────────────────────────────────────────────
     program
-        .command("health")
-        .description("探测 browserd 是否就绪 + 是否已 open")
-        .option("-p, --port <port>", "browserd RPC 端口（默认 17322）", (v) => Number(v))
-        .action(async (opts) => {
-        const client = makeClient(opts.port);
+        .command("health <name>")
+        .description("探测实例的 browserd 是否就绪 + 是否已 open")
+        .action(async (name, opts) => {
+        let cfg;
+        try {
+            const handle = findProjectConfig(process.cwd());
+            cfg = loadInstance(name, handle, optsToOverrides(opts));
+        }
+        catch (e) {
+            handleConfigError(e);
+            return;
+        }
+        const client = new BrowserClient({ port: cfg.rpcPort });
         const h = await client.health();
         if (!h) {
             console.error(`\n[mooncat-browser] browserd not reachable at ${client.baseUrl}`);
-            console.error(`  hint: run \`mooncat-browser start\` first`);
+            console.error(`  hint: run \`mooncat-browser start ${name}\` first`);
             process.exit(1);
         }
-        printHeader(`health @ ${client.baseUrl}`);
+        printHeader(`health @ ${client.baseUrl} (instance ${name})`);
         console.log(JSON.stringify(h, null, 2));
     });
     // ─── stop ───────────────────────────────────────────────────────────────
     program
-        .command("stop")
-        .description("graceful 停止服务（关闭 Chrome + 退出 wrapper，不重启）")
-        .option("-p, --port <port>", "browserd RPC 端口（默认 17322）", (v) => Number(v))
-        .action(async (opts) => {
-        const cfg = resolveConfig({ port: opts.port });
-        const state = readServiceState(cfg.rpcPort);
+        .command("stop <name>")
+        .description("graceful 停止实例(关闭 Chrome + 退出 wrapper,不重启)")
+        .action(async (name, opts) => {
+        let cfg;
+        try {
+            const handle = findProjectConfig(process.cwd());
+            cfg = loadInstance(name, handle, optsToOverrides(opts));
+        }
+        catch (e) {
+            handleConfigError(e);
+            return;
+        }
+        const state = readServiceState(cfg);
         const healthPort = state?.healthPort ?? cfg.healthPort;
-        printHeader(`stopping service (rpc :${cfg.rpcPort})`);
-        // 1) 优先走 wrapper /shutdown（wrapper 协调 graceful 关闭 + 不重启）
-        //    healthPort 从 start 时持久化的状态文件读，避免 CLI 覆盖不一致。
+        printHeader(`stopping instance "${name}" (rpc :${cfg.rpcPort})`);
+        // 1) 优先走 wrapper /shutdown(wrapper 协调 graceful 关闭 + 不重启)
         let viaWrapper = false;
         try {
             const resp = await fetch(`http://127.0.0.1:${healthPort}/shutdown`, { method: "POST" });
@@ -125,7 +317,7 @@ async function run() {
             }
         }
         catch {
-            /* wrapper 不在，回落到直接关 browserd */
+            /* wrapper 不在,回落到直接关 browserd */
         }
         // 2) wrapper 不在 → 直接发 close 给 browserd
         if (!viaWrapper) {
@@ -138,14 +330,13 @@ async function run() {
                 console.error(`  [WARN] direct close failed: ${e.message}`);
             }
         }
-        // 3) 等 browserd 退出（最多 ~12s）
+        // 3) 等 browserd 退出(最多 ~12s)
         const gone = await waitForExit(cfg.rpcPort, 12000);
         console.log(`  browserd ${gone ? "stopped" : "still alive (may be restarting or stuck)"}`);
         // 4) 清理可能残留的状态文件
         try {
-            if (existsSync(serviceStatePath(cfg.rpcPort))) {
-                const { unlinkSync } = await import("node:fs");
-                unlinkSync(serviceStatePath(cfg.rpcPort));
+            if (existsSync(serviceStatePath(cfg))) {
+                unlinkSyncSafe(serviceStatePath(cfg));
                 console.log(`  removed stale state file`);
             }
         }
@@ -154,30 +345,110 @@ async function run() {
         }
         console.log(`  done. (Chrome closed gracefully, login state preserved)`);
     });
+    // ─── status ─────────────────────────────────────────────────────────────
+    program
+        .command("status <name>")
+        .description("查实例运行状态(走 wrapper /health,含 browserd/chrome pid)")
+        .action(async (name, opts) => {
+        let cfg;
+        try {
+            const handle = findProjectConfig(process.cwd());
+            cfg = loadInstance(name, handle, optsToOverrides(opts));
+        }
+        catch (e) {
+            handleConfigError(e);
+            return;
+        }
+        const state = readServiceState(cfg);
+        const healthPort = state?.healthPort ?? cfg.healthPort;
+        printHeader(`status of instance "${name}"`);
+        try {
+            const resp = await fetch(`http://127.0.0.1:${healthPort}/health`, {
+                signal: AbortSignal.timeout(2000),
+            });
+            if (!resp.ok)
+                throw new Error(`HTTP ${resp.status}`);
+            const s = (await resp.json());
+            // 校验响应来自 state 记录的同一进程,否则是僵尸/被占用
+            if (state && typeof s.wrapperPid === "number" && s.wrapperPid !== state.pid) {
+                console.log(`  [STALE] health 端口 ${healthPort} 响应了,但 wrapperPid=${s.wrapperPid} ≠ state.pid=${state.pid}`);
+                console.log(`  说明:state 记录的 wrapper(pid=${state.pid})已死,端口被别的进程占用(僵尸或冲突)。`);
+                console.log(`  修复:确认无重要进程后,手动清理端口占用 + 删 state 文件,再 start。`);
+                process.exit(1);
+            }
+            console.log(JSON.stringify(s, null, 2));
+        }
+        catch (e) {
+            console.log(`  not running (${e.message})`);
+            if (state)
+                console.log(`  (stale state file: pid=${state.pid}, started ${state.startedAt})`);
+            process.exit(1);
+        }
+    });
     // ─── open ───────────────────────────────────────────────────────────────
     program
-        .command("open")
-        .description("连接已运行的服务，打开/复用浏览器并导航到 URL")
+        .command("open <name>")
+        .description("连接已运行实例,打开/复用浏览器并导航到 URL")
         .requiredOption("-u, --url <url>", "要打开的 URL")
-        .option("-p, --port <port>", "browserd RPC 端口（默认 17322）", (v) => Number(v))
-        .option("--headless", "无头模式（仅 CDP 路生效）")
-        .action(async (opts) => {
-        const client = makeClient(opts.port);
+        .option("--headless", "无头模式(仅 CDP 路生效)")
+        .option("--route-mode <mode>", "路由模式(auto|cdp|extension)。高危平台用 extension")
+        .action(async (name, opts) => {
+        let cfg;
+        try {
+            const handle = findProjectConfig(process.cwd());
+            cfg = loadInstance(name, handle, optsToOverrides(opts));
+        }
+        catch (e) {
+            handleConfigError(e);
+            return;
+        }
+        const client = new BrowserClient({ port: cfg.rpcPort });
         const h = await client.health();
         if (!h) {
             console.error(`\n[mooncat-browser] browserd not reachable at ${client.baseUrl}`);
-            console.error(`  hint: run \`mooncat-browser start\` first`);
+            console.error(`  hint: run \`mooncat-browser start ${name}\` first`);
             process.exit(1);
         }
         if (!h.open && !h.browserOpen) {
-            await client.open({ headless: !!opts.headless });
-            console.log(`  browser opened`);
+            // routeMode:CLI 显式给 > 实例配置 routeMode > 不传(browsed 用 auto 默认)
+            const openOpts = { headless: !!opts.headless };
+            const rm = opts.routeMode || cfg.routeMode;
+            if (rm)
+                openOpts.routeMode = rm;
+            await client.open(openOpts);
+            console.log(`  browser opened${rm ? ` (routeMode=${rm})` : ""}`);
         }
         const tab = await client.newTab({ url: opts.url });
         printHeader(`opened`);
-        console.log(`  url         : ${opts.url}`);
-        console.log(`  pageHandle  : ${JSON.stringify(tab.pageHandle)}`);
-        console.log(`  reused      : ${tab.reused ?? false}`);
+        console.log(`  instance   : ${name}`);
+        console.log(`  url        : ${opts.url}`);
+        console.log(`  pageHandle : ${JSON.stringify(tab.pageHandle)}`);
+        console.log(`  reused     : ${tab.reused ?? false}`);
+    });
+    // ─── list ───────────────────────────────────────────────────────────────
+    program
+        .command("list")
+        .description("列出项目配置里所有实例 + 运行状态")
+        .action(async () => {
+        let handle;
+        try {
+            handle = findProjectConfig(process.cwd());
+        }
+        catch (e) {
+            handleConfigError(e);
+            return;
+        }
+        const names = listInstanceNames(handle);
+        printHeader(`instances in ${handle.configPath}`);
+        if (!names.length) {
+            console.log(`  (no instances defined)`);
+            return;
+        }
+        for (const n of names) {
+            const cfg = loadInstance(n, handle);
+            const flag = await realInstanceStatus(cfg);
+            console.log(`  ${n.padEnd(16)} rpc:${cfg.rpcPort}  health:${cfg.healthPort}  [${flag}]`);
+        }
     });
     // ─── install-extension ──────────────────────────────────────────────────
     program
@@ -196,15 +467,16 @@ async function run() {
         console.log(`  1. enable "Developer mode" (top right)`);
         console.log(`  2. click "Load unpacked"`);
         console.log(`  3. select the directory above`);
-        console.log(`\n  装扩展后，重启浏览器（close + open）才会切到 extension 路由。`);
+        console.log(`\n  装扩展后,重启浏览器(close + open)才会切到 extension 路由。`);
+        console.log(`  注意:第一版 extension 路是单实例(WS 端口固定)。多实例请走 CDP 路。`);
     });
     // ─── skills ─────────────────────────────────────────────────────────────
     program
         .command("skills")
-        .description("安装/更新内置 skills 到 ~/.agents/skills（覆盖同名，幂等可重复执行）")
-        .option("-s, --skill <name>", "只安装指定 skill（默认全部）")
-        .option("-t, --target <dir>", "自定义目标目录（默认 ~/.agents/skills）")
-        .option("--list", "只列出包内的 skills，不拷贝")
+        .description("安装/更新内置 skills 到项目本地 .agents/skills(覆盖同名,幂等可重复执行)")
+        .option("-s, --skill <name>", "只安装指定 skill(默认全部)")
+        .option("-t, --target <dir>", "自定义目标目录(默认 .agents/skills)")
+        .option("--list", "只列出包内的 skills,不拷贝")
         .action((opts) => {
         const srcRoot = skillsSourceDir();
         if (!existsSync(srcRoot)) {
@@ -212,7 +484,6 @@ async function run() {
             console.error(`  hint: 包发布时可能漏了 skills/ 目录`);
             process.exit(1);
         }
-        // 列出源里的 skill 子目录（每个含 SKILL.md）
         const names = readdirSync(srcRoot, { withFileTypes: true })
             .filter((d) => d.isDirectory())
             .filter((d) => existsSync(join(srcRoot, d.name, "SKILL.md")))
@@ -236,7 +507,6 @@ async function run() {
         for (const n of requested) {
             const src = join(srcRoot, n);
             const dest = join(destRoot, n);
-            // 先清空目标 skill 目录再拷贝，保证与源完全一致（删除源里已移除的旧文件，如重命名后的残留）
             rmSync(dest, { recursive: true, force: true });
             cpSync(src, dest, { recursive: true, force: true });
             console.log(`  [ok] ${n} -> ${dest}`);
@@ -245,17 +515,25 @@ async function run() {
     });
     await program.parseAsync(process.argv);
 }
-/** 包内 skills 源目录：dist/cli.js -> ../skills；源码运行 -> ../../skills。 */
+/** 安全 unlink(独立函数,方便 stop 里 import 前已可用)。 */
+function unlinkSyncSafe(p) {
+    try {
+        rmSync(p, { force: true });
+    }
+    catch {
+        /* ignore */
+    }
+}
+/** 包内 skills 源目录:dist/cli.js -> ../skills;源码运行 -> ../../skills。 */
 function skillsSourceDir() {
     return process.env.MOONCAT_BROWSER_SKILLS_SRC || join(__dirname, "..", "skills");
 }
-/** skills 安装默认目标：~/.agents/skills（跨平台 homedir()）。 */
+/** skills 安装默认目标:项目本地 .agents/skills(cwd 下)。
+ * 与 mooncat-browser "项目级、不写全局" 的定位一致——skills 跟着项目走,不污染全局。 */
 function defaultSkillsTarget() {
-    return join(homedir(), ".agents", "skills");
+    return join(process.cwd(), ".agents", "skills");
 }
 function getVersion() {
-    // 编译后 dist/cli.js 读 ../package.json；源码运行时读 ../../package.json
-    // 统一用相对包根查找（容忍 dist/ 与 src/ 两种位置）
     const candidates = [
         join(__dirname, "..", "package.json"),
         join(__dirname, "..", "..", "package.json"),