remnote-bridge 0.1.10 → 0.1.12

package/dist/cli/daemon/dev-server.js

@@ -61,7 +61,15 @@ export class DevServerManager {
         // shell: true 确保 Windows 上能找到 npm.cmd
         this.child = spawn('npm', ['run', 'dev'], {
             cwd: pluginDir,
-            env: { ...process.env, PORT: String(port) },
+            env: {
+                ...process.env,
+                PORT: String(port),
+                // 供 webpack devServer.setupMiddlewares 劫持 /api/discovery
+                DISCOVERY_WS_PORT: process.env.SLOT_WS_PORT ?? '',
+                DISCOVERY_CONFIG_PORT: process.env.SLOT_CONFIG_PORT ?? '',
+                DISCOVERY_INSTANCE: process.env.REMNOTE_BRIDGE_INSTANCE ?? '',
+                DISCOVERY_SLOT_INDEX: process.env.SLOT_INDEX ?? '',
+            },
             stdio: 'pipe',
             shell: true,
         });

package/dist/cli/daemon/pid.js

@@ -1,23 +1,28 @@
 /**
  * PID 文件管理
  *
- * 写入、读取、stale 检测、清理。
+ * PID 文件为 JSON 格式，包含 pid、slotIndex、instance 和端口信息。
+ * 路径：~/.remnote-bridge/instances/N.pid
  */
 import fs from 'fs';
+import { execFileSync } from 'child_process';
 /**
- * 写入 PID 文件
+ * 写入 PID 文件（JSON 格式）
  */
-export function writePid(filePath, pid) {
-    fs.writeFileSync(filePath, String(pid), 'utf-8');
+export function writePid(filePath, info) {
+    fs.writeFileSync(filePath, JSON.stringify(info, null, 2) + '\n', 'utf-8');
 }
 /**
- * 读取 PID 文件。文件不存在返回 null。
+ * 读取 PID 文件。文件不存在或格式错误返回 null。
  */
-export function readPid(filePath) {
+export function readPidInfo(filePath) {
     try {
-        const content = fs.readFileSync(filePath, 'utf-8').trim();
-        const pid = parseInt(content, 10);
-        return isNaN(pid) ? null : pid;
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const parsed = JSON.parse(content);
+        if (typeof parsed.pid === 'number' && typeof parsed.slotIndex === 'number') {
+            return parsed;
+        }
+        return null;
     }
     catch {
         return null;
@@ -47,21 +52,30 @@ export function isProcessAlive(pid) {
     }
 }
 /**
- * 检查守护进程状态。返回：
- * - { running: true, pid } — 守护进程正在运行
- * - { running: false } — 守护进程未运行（无 PID 文件或 stale）
+ * 检查进程是否是我们的 daemon。
  *
- * 若 PID 文件存在但进程已死（stale），自动清理 PID 文件。
+ * 仅 kill -0 无法防止 PID recycling：OS 可能把同一 PID 分配给无关进程，
+ * 导致 cleanStaleSlots 误判槽位为"存活"而不清理。
+ * 此函数额外校验进程命令行是否包含 daemon 关键字。
  */
-export function checkDaemon(pidPath) {
-    const pid = readPid(pidPath);
-    if (pid === null) {
-        return { running: false };
+export function isDaemonAlive(pid) {
+    // PID 0 是 allocateSlot 的占位值，不是有效的 daemon PID
+    // process.kill(0, 0) 发信号给进程组，会误返回 true
+    if (pid <= 0)
+        return false;
+    if (!isProcessAlive(pid))
+        return false;
+    try {
+        const cmd = execFileSync('ps', ['-p', String(pid), '-o', 'command='], {
+            encoding: 'utf-8',
+            timeout: 3000,
+        }).trim();
+        // daemon.ts 编译后路径包含 "daemon/daemon"（dist/cli/daemon/daemon.js）
+        // 使用更精确的匹配避免误匹配 dockerd 等含 "daemon" 的无关进程
+        return cmd.includes('daemon/daemon') || cmd.includes('daemon.js');
     }
-    if (isProcessAlive(pid)) {
-        return { running: true, pid };
+    catch {
+        // ps 失败时回退到基本检查（kill -0 已通过）
+        return true;
     }
-    // stale PID 文件，清理
-    removePid(pidPath);
-    return { running: false };
 }

package/dist/cli/daemon/registry.js

@@ -0,0 +1,160 @@
+/**
+ * 多实例注册表
+ *
+ * 管理最多 4 个 daemon 实例的端口槽位分配。
+ * 所有运行时文件存放在 ~/.remnote-bridge/：
+ *   config.json    — 全局配置
+ *   slots.json     — 4 组端口定义
+ *   registry.json  — instance → slot 映射
+ *   instances/N.pid — 槽位 PID 文件（JSON）
+ *   instances/N.log — 槽位日志
+ */
+import fs from 'fs';
+import path from 'path';
+import { isDaemonAlive } from './pid.js';
+import { GLOBAL_DIR, ensureGlobalDir } from '../config.js';
+// ── 常量 ──
+export const MAX_SLOTS = 4;
+const SLOTS_FILE = path.join(GLOBAL_DIR, 'slots.json');
+const REGISTRY_FILE = path.join(GLOBAL_DIR, 'registry.json');
+const INSTANCES_DIR = path.join(GLOBAL_DIR, 'instances');
+/** 默认 4 组端口槽位（29100 段，高位端口避免冲突） */
+export const DEFAULT_SLOTS = [
+    { wsPort: 29100, devServerPort: 29101, configPort: 29102 },
+    { wsPort: 29110, devServerPort: 29111, configPort: 29112 },
+    { wsPort: 29120, devServerPort: 29121, configPort: 29122 },
+    { wsPort: 29130, devServerPort: 29131, configPort: 29132 },
+];
+// ── slots.json ──
+export function loadSlots() {
+    try {
+        const raw = fs.readFileSync(SLOTS_FILE, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed) && parsed.length === MAX_SLOTS) {
+            return parsed;
+        }
+    }
+    catch {
+        // 不存在或损坏
+    }
+    // 自动生成默认
+    ensureGlobalDir();
+    const slots = [...DEFAULT_SLOTS];
+    fs.writeFileSync(SLOTS_FILE, JSON.stringify(slots, null, 2) + '\n', 'utf-8');
+    return slots;
+}
+// ── registry.json ──
+export function loadRegistry() {
+    try {
+        const raw = fs.readFileSync(REGISTRY_FILE, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed && parsed.version === 1 && Array.isArray(parsed.slots)) {
+            // 确保 slots 数组长度正确
+            while (parsed.slots.length < MAX_SLOTS)
+                parsed.slots.push(null);
+            return parsed;
+        }
+    }
+    catch {
+        // 不存在或损坏
+    }
+    return { version: 1, slots: new Array(MAX_SLOTS).fill(null) };
+}
+export function saveRegistry(registry) {
+    ensureGlobalDir();
+    const tmpPath = REGISTRY_FILE + '.tmp.' + process.pid;
+    fs.writeFileSync(tmpPath, JSON.stringify(registry, null, 2) + '\n', 'utf-8');
+    fs.renameSync(tmpPath, REGISTRY_FILE);
+}
+// ── 槽位操作 ──
+/** 清理 stale 槽位（进程已死但注册表未更新） */
+export function cleanStaleSlots(registry) {
+    let changed = false;
+    for (let i = 0; i < registry.slots.length; i++) {
+        const entry = registry.slots[i];
+        if (entry && !isDaemonAlive(entry.pid)) {
+            registry.slots[i] = null;
+            // 清理对应的 PID 文件
+            try {
+                fs.unlinkSync(instancePidPath(i));
+            }
+            catch { /* ignore */ }
+            changed = true;
+        }
+    }
+    if (changed) {
+        saveRegistry(registry);
+    }
+    return changed;
+}
+/** 根据 instance 名查找已分配的槽位 */
+export function findSlotByInstance(registry, instanceId) {
+    return registry.slots.find((e) => e?.instance === instanceId) ?? null;
+}
+/** 分配一个空闲槽位，返回槽位索引；无空闲返回 null */
+export function allocateSlot(registry, instanceId, pid) {
+    const slots = loadSlots();
+    const freeIndex = registry.slots.findIndex((e) => e === null);
+    if (freeIndex === -1)
+        return null;
+    const ports = slots[freeIndex];
+    const entry = {
+        index: freeIndex,
+        instance: instanceId,
+        pid,
+        wsPort: ports.wsPort,
+        devServerPort: ports.devServerPort,
+        configPort: ports.configPort,
+        startedAt: new Date().toISOString(),
+    };
+    registry.slots[freeIndex] = entry;
+    saveRegistry(registry);
+    return entry;
+}
+/** 释放指定 instance 的槽位 */
+export function releaseSlot(registry, instanceId) {
+    for (let i = 0; i < registry.slots.length; i++) {
+        if (registry.slots[i]?.instance === instanceId) {
+            registry.slots[i] = null;
+            break;
+        }
+    }
+    saveRegistry(registry);
+}
+// ── 实例路径 ──
+/** 槽位 PID 文件路径 */
+export function instancePidPath(slotIndex) {
+    return path.join(INSTANCES_DIR, `${slotIndex}.pid`);
+}
+/** 槽位日志文件路径 */
+export function instanceLogPath(slotIndex) {
+    return path.join(INSTANCES_DIR, `${slotIndex}.log`);
+}
+// ── 实例标识解析 ──
+/**
+ * 解析实例标识。
+ *
+ * 优先级：REMNOTE_HEADLESS（最高，覆盖一切）> cliArg > REMNOTE_BRIDGE_INSTANCE > "default"
+ */
+export function resolveInstanceId(cliArg) {
+    // headless 模式覆盖 --instance，固定实例名
+    if (process.env.REMNOTE_HEADLESS === '1')
+        return 'headless';
+    if (cliArg)
+        return cliArg;
+    const fromEnv = process.env.REMNOTE_BRIDGE_INSTANCE;
+    if (fromEnv)
+        return fromEnv;
+    return 'default';
+}
+// ── 满载报错信息 ──
+export function formatSlotsFullError(registry) {
+    const lines = [`错误: 已达最大实例数上限（${MAX_SLOTS}），无可用槽位。`, '', '运行中的实例:'];
+    for (const entry of registry.slots) {
+        if (entry) {
+            lines.push(`  槽位 ${entry.index}: ${entry.instance} (PID: ${entry.pid})`);
+        }
+    }
+    lines.push('', '请先执行 `remnote-bridge --instance <name> disconnect` 释放槽位。');
+    return lines.join('\n');
+}

package/dist/cli/daemon/send-request.js

@@ -3,11 +3,12 @@
  *
  * 封装 WS 连接建立、请求发送、响应等待、超时处理的完整流程。
  * 所有业务命令（health、read-rem、edit-rem 等）均通过此函数与 daemon 通信。
+ *
+ * 端口发现：通过 registry.json 查找当前 instance 对应的槽位端口。
  */
 import WebSocket from 'ws';
 import crypto from 'crypto';
-import { loadConfig, pidFilePath, findProjectRoot } from '../config.js';
-import { checkDaemon } from './pid.js';
+import { resolveInstanceId, loadRegistry, cleanStaleSlots, findSlotByInstance } from './registry.js';
 import { isBridgeResponse } from '../protocol.js';
 const CONNECT_TIMEOUT_MS = 5_000;
 const DEFAULT_RESPONSE_TIMEOUT_MS = 30_000;
@@ -26,24 +27,23 @@ export class DaemonUnreachableError extends Error {
 /**
  * 向守护进程发送请求并等待响应。
  *
- * 流程：读取 PID 文件 → 建立 WS 连接 → 发送 BridgeRequest → 等待 BridgeResponse → 关闭连接
+ * 流程：解析 instance → 查 registry → 建立 WS 连接 → 发送请求 → 等待响应 → 关闭连接
  *
- * @throws DaemonNotRunningError — PID 文件不存在或进程已死
+ * @throws DaemonNotRunningError — registry 中找不到当前 instance 或进程已死
  * @throws DaemonUnreachableError — WS 连接失败
  * @throws Error — daemon 返回 error 字段或响应超时
  */
 export async function sendDaemonRequest(action, payload = {}, options) {
-    const projectRoot = findProjectRoot();
-    const config = loadConfig(projectRoot);
-    const pidPath = pidFilePath(projectRoot);
-    // 检查 daemon 是否运行
-    const daemonStatus = checkDaemon(pidPath);
-    if (!daemonStatus.running) {
+    const instanceId = resolveInstanceId(options?.instance);
+    const registry = loadRegistry();
+    cleanStaleSlots(registry);
+    const entry = findSlotByInstance(registry, instanceId);
+    if (!entry) {
         throw new DaemonNotRunningError();
     }
     const responseTimeout = options?.timeout ?? DEFAULT_RESPONSE_TIMEOUT_MS;
     return new Promise((resolve, reject) => {
-        const ws = new WebSocket(`ws://127.0.0.1:${config.wsPort}`);
+        const ws = new WebSocket(`ws://127.0.0.1:${entry.wsPort}`);
         const requestId = crypto.randomUUID();
         let responseTimer = null;
         const connectTimer = setTimeout(() => {

package/dist/cli/daemon/static-server.js

@@ -18,55 +18,118 @@ const MIME_TYPES = {
 };
 export class StaticServer {
     server = null;
+    _actualPort = 0;
     options;
+    _discovery = null;
+    /** 实际监听的端口（可能与 options.port 不同，若原端口被占用则 OS 自动分配） */
+    get actualPort() { return this._actualPort; }
     constructor(options) {
         this.options = options;
     }
+    /** 动态更新 discovery 数据（daemon 启动后设置实际端口） */
+    setDiscovery(data) {
+        this._discovery = data;
+    }
     start() {
         const { distDir, port, onLog } = this.options;
-        return new Promise((resolve, reject) => {
-            this.server = http.createServer((req, res) => {
-                // CORS headers（与 webpack.config.js 一致）
-                res.setHeader('Access-Control-Allow-Origin', '*');
-                res.setHeader('Access-Control-Allow-Headers', 'baggage, sentry-trace');
-                // OPTIONS preflight
-                if (req.method === 'OPTIONS') {
-                    res.writeHead(204);
-                    res.end();
-                    return;
+        const createHttpServer = () => http.createServer((req, res) => {
+            // CORS headers（与 webpack.config.js 一致）
+            res.setHeader('Access-Control-Allow-Origin', '*');
+            res.setHeader('Access-Control-Allow-Headers', 'baggage, sentry-trace');
+            // OPTIONS preflight
+            if (req.method === 'OPTIONS') {
+                res.writeHead(204);
+                res.end();
+                return;
+            }
+            const urlPath = req.url?.split('?')[0] || '/';
+            // /api/discovery 端点：返回 daemon 端口信息，供 Plugin 自动发现
+            if (urlPath === '/api/discovery') {
+                if (this._discovery) {
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify(this._discovery));
                 }
-                const urlPath = req.url?.split('?')[0] || '/';
-                const filePath = path.resolve(distDir, urlPath === '/' ? 'index.html' : '.' + urlPath);
-                // 防止目录遍历（resolve 规范化后，确保仍在 distDir + sep 下）
-                const safePrefix = distDir.endsWith(path.sep) ? distDir : distDir + path.sep;
-                if (!filePath.startsWith(safePrefix) && filePath !== distDir) {
-                    res.writeHead(403);
-                    res.end('Forbidden');
-                    return;
+                else {
+                    res.writeHead(503, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'discovery not ready' }));
                 }
-                fs.readFile(filePath, (err, data) => {
+                return;
+            }
+            // 多实例支持：非 default 实例动态修改 manifest.json 的 id 和 name，
+            // 使 RemNote 能同时加载多个同源 Plugin（RemNote 按 id 去重）
+            if (urlPath === '/manifest.json' && this._discovery && this._discovery.instance !== 'default') {
+                const manifestPath = path.resolve(distDir, 'manifest.json');
+                fs.readFile(manifestPath, 'utf-8', (err, raw) => {
                     if (err) {
                         res.writeHead(404);
                         res.end('Not Found');
                         return;
                     }
-                    const ext = path.extname(filePath);
-                    const contentType = MIME_TYPES[ext] || 'application/octet-stream';
-                    res.writeHead(200, {
-                        'Content-Type': contentType,
-                        'Cache-Control': 'no-cache, no-store, must-revalidate',
-                    });
-                    res.end(data);
+                    try {
+                        const manifest = JSON.parse(raw);
+                        const suffix = this._discovery.instance;
+                        manifest.id = `${manifest.id}_${suffix}`;
+                        manifest.name = `${manifest.name} (${suffix})`;
+                        res.writeHead(200, {
+                            'Content-Type': 'application/json',
+                            'Cache-Control': 'no-cache, no-store, must-revalidate',
+                        });
+                        res.end(JSON.stringify(manifest, null, 2));
+                    }
+                    catch {
+                        res.writeHead(500);
+                        res.end('manifest parse error');
+                    }
                 });
+                return;
+            }
+            const filePath = path.resolve(distDir, urlPath === '/' ? 'index.html' : '.' + urlPath);
+            // 防止目录遍历（resolve 规范化后，确保仍在 distDir + sep 下）
+            const safePrefix = distDir.endsWith(path.sep) ? distDir : distDir + path.sep;
+            if (!filePath.startsWith(safePrefix) && filePath !== distDir) {
+                res.writeHead(403);
+                res.end('Forbidden');
+                return;
+            }
+            fs.readFile(filePath, (err, data) => {
+                if (err) {
+                    res.writeHead(404);
+                    res.end('Not Found');
+                    return;
+                }
+                const ext = path.extname(filePath);
+                const contentType = MIME_TYPES[ext] || 'application/octet-stream';
+                res.writeHead(200, {
+                    'Content-Type': contentType,
+                    'Cache-Control': 'no-cache, no-store, must-revalidate',
+                });
+                res.end(data);
             });
-            this.server.on('error', (err) => {
-                onLog?.(`[static-server] 启动失败: ${err.message}`, 'error');
-                reject(err);
-            });
-            this.server.listen(port, '127.0.0.1', () => {
-                onLog?.(`[static-server] 已启动 http://127.0.0.1:${port} (serving ${distDir})`, 'info');
-                resolve();
-            });
+        });
+        return new Promise((resolve, reject) => {
+            const tryListen = (listenPort) => {
+                this.server = createHttpServer();
+                this.server.on('error', (err) => {
+                    if (err.code === 'EADDRINUSE' && listenPort !== 0) {
+                        onLog?.(`[static-server] 端口 ${listenPort} 被占用，尝试自动分配...`, 'warn');
+                        this.server = null;
+                        tryListen(0);
+                    }
+                    else {
+                        onLog?.(`[static-server] 启动失败: ${err.message}`, 'error');
+                        reject(err);
+                    }
+                });
+                this.server.listen(listenPort, '127.0.0.1', () => {
+                    this._actualPort = this.server.address().port;
+                    if (this._actualPort !== port) {
+                        onLog?.(`[static-server] 端口 ${port} 被占用，自动分配到 ${this._actualPort}`, 'warn');
+                    }
+                    onLog?.(`[static-server] 已启动 http://127.0.0.1:${this._actualPort} (serving ${distDir})`, 'info');
+                    resolve();
+                });
+            };
+            tryListen(port);
         });
     }
     stop() {

package/dist/cli/handlers/context-read-handler.js

@@ -17,8 +17,10 @@ export class ContextReadHandler {
         const depth = payload.depth ?? this.defaults.readContextDepth;
         const maxNodes = payload.maxNodes ?? this.defaults.maxNodes;
         const maxSiblings = payload.maxSiblings ?? this.defaults.maxSiblings;
-        return await this.forwardToPlugin('read_context', {
-            mode, ancestorLevels, depth, maxNodes, maxSiblings,
-        });
+        const focusRemId = payload.focusRemId;
+        const pluginPayload = { mode, ancestorLevels, depth, maxNodes, maxSiblings };
+        if (focusRemId)
+            pluginPayload.focusRemId = focusRemId;
+        return await this.forwardToPlugin('read_context', pluginPayload);
     }
 }

package/dist/cli/handlers/read-handler.js

@@ -8,6 +8,7 @@
  */
 /** R-F 字段（仅 --full 模式输出，默认不输出） */
 const RF_FIELDS = new Set([
+    'children',
     'isPowerup', 'isPowerupEnum', 'isPowerupProperty',
     'isPowerupPropertyListItem', 'isPowerupSlot',
     'deepRemsBeingReferenced',
@@ -17,10 +18,10 @@ const RF_FIELDS = new Set([
     'embeddedQueueViewMode',
     'localUpdatedAt', 'lastPracticed',
 ]);
-/** Portal 简化输出字段（type === 'portal' 时默认输出这 9 个字段） */
+/** Portal 简化输出字段（type === 'portal' 时默认输出这 8 个字段） */
 export const PORTAL_FIELDS = [
     'id', 'type', 'portalType', 'portalDirectlyIncludedRem',
-    'parent', 'positionAmongstSiblings', 'children',
+    'parent', 'positionAmongstSiblings',
     'createdAt', 'updatedAt',
 ];
 export class ReadHandler {
@@ -66,7 +67,7 @@ export class ReadHandler {
             }
         }
         else if (remObject.type === 'portal') {
-            // Portal 简化模式：只输出 9 个关键字段
+            // Portal 简化模式：只输出 8 个关键字段
             const obj = remObject;
             result = {};
             for (const field of PORTAL_FIELDS) {

package/dist/cli/handlers/tree-parser.js

@@ -197,15 +197,22 @@ export function parsePowerupPrefix(rawContent) {
         }
     }
     // 尾部箭头（无 backText，multiline）
+    // 支持有空格 ` ↓` 和无空格 `）↓` 两种写法（模型常漏空格）
     if (backText === undefined) {
-        const tailArrows = [
-            [' ↕', 'both'],
-            [' ↓', 'forward'],
-            [' ↑', 'backward'],
+        const tailArrowChars = [
+            ['↕', 'both'],
+            ['↓', 'forward'],
+            ['↑', 'backward'],
         ];
-        for (const [arrow, dir] of tailArrows) {
-            if (content.endsWith(arrow)) {
-                content = content.slice(0, -arrow.length);
+        for (const [ch, dir] of tailArrowChars) {
+            if (content.endsWith(` ${ch}`)) {
+                content = content.slice(0, -(ch.length + 1)); // 去掉 ` ↓`
+                practiceDirection = dir;
+                isMultiline = true;
+                break;
+            }
+            if (content.endsWith(ch)) {
+                content = content.slice(0, -ch.length); // 去掉 `↓`（无空格）
                 practiceDirection = dir;
                 isMultiline = true;
                 break;
@@ -227,9 +234,9 @@ export function parsePowerupPrefix(rawContent) {
     return result;
 }
 // ────────────────────────── Multiline 检测 ──────────────────────────
-/** multiline 箭头正则：中间箭头 ↓↑↕ 或尾部箭头 ↓↑↕ */
+/** multiline 箭头正则：中间箭头 ↓↑↕ 或尾部箭头 ↓↑↕（允许有无空格） */
 const MULTILINE_MID_RE = / [↓↑↕] /;
-const MULTILINE_TAIL_RE = / [↓↑↕]$/;
+const MULTILINE_TAIL_RE = /[↓↑↕]$/;
 /** 从行内容判断是否为 multiline 父节点（内容包含 ↓↑↕ 箭头） */
 export function isContentMultiline(rawContent) {
     return MULTILINE_MID_RE.test(rawContent) || MULTILINE_TAIL_RE.test(rawContent);

package/dist/cli/main.js

@@ -19,6 +19,7 @@ import { readContextCommand } from './commands/read-context.js';
 import { searchCommand } from './commands/search.js';
 import { installSkillCommand, installSkillCopyCommand } from './commands/install-skill.js';
 import { cleanCommand } from './commands/clean.js';
+import { addonListCommand, addonInstallCommand, addonUninstallCommand } from './commands/addon.js';
 const require = createRequire(import.meta.url);
 const { version } = require('../../package.json');
 const program = new Command();
@@ -59,7 +60,23 @@ program
     .name('remnote-bridge')
     .description('RemNote Bridge — CLI + MCP Server + Plugin')
     .version(version)
-    .option('--json', '以 JSON 格式输出（适用于程序化调用）');
+    .option('--json', '以 JSON 格式输出（适用于程序化调用）')
+    .option('--instance <name>', '指定 daemon 实例名（也可用 REMNOTE_BRIDGE_INSTANCE 环境变量）')
+    .option('--headless', '使用 headless 实例（覆盖 --instance，也可用 REMNOTE_HEADLESS=1 环境变量）');
+// 全局参数同步到环境变量，使所有命令中的 resolveInstanceId() 自动生效
+program.hook('preAction', () => {
+    const opts = program.opts();
+    const headlessEnv = process.env.REMNOTE_HEADLESS;
+    const isHeadless = opts.headless || headlessEnv === '1' || headlessEnv === 'true';
+    if (isHeadless) {
+        // headless 覆盖 instance，固定实例名
+        process.env.REMNOTE_HEADLESS = '1';
+        process.env.REMNOTE_BRIDGE_INSTANCE = 'headless';
+    }
+    else if (opts.instance) {
+        process.env.REMNOTE_BRIDGE_INSTANCE = opts.instance;
+    }
+});
 program
     .command('setup')
     .description('启动 Chrome 让用户登录 RemNote（headless 模式前置步骤）')
@@ -71,11 +88,10 @@ program
     .command('connect')
     .description('启动守护进程，等待 Plugin 连接')
     .option('--dev', '开发模式：使用 webpack-dev-server（支持 HMR）')
-    .option('--headless', '无头模式：自动启动 headless Chrome 加载 Plugin（需先 setup）')
-    .option('--remote-debugging-port <port>', 'Chrome 远程调试端口（仅 --headless）', parseInt)
+    .option('--remote-debugging-port <port>', 'Chrome 远程调试端口（仅 headless 模式）', parseInt)
     .action(async (cmdOpts) => {
-    const { json } = program.opts();
-    await connectCommand({ json, dev: cmdOpts.dev, headless: cmdOpts.headless, remoteDebuggingPort: cmdOpts.remoteDebuggingPort });
+    const { json, instance } = program.opts();
+    await connectCommand({ json, instance, dev: cmdOpts.dev, remoteDebuggingPort: cmdOpts.remoteDebuggingPort });
 });
 program
     .command('health')
@@ -83,15 +99,15 @@ program
     .option('--diagnose', '诊断 headless Chrome（截图 + 状态 + console 错误）')
     .option('--reload', '重载 headless Chrome 页面')
     .action(async (cmdOpts) => {
-    const { json } = program.opts();
-    await healthCommand({ json, diagnose: cmdOpts.diagnose, reload: cmdOpts.reload });
+    const { json, instance } = program.opts();
+    await healthCommand({ json, instance, diagnose: cmdOpts.diagnose, reload: cmdOpts.reload });
 });
 program
     .command('disconnect')
     .description('停止守护进程，释放端口和资源')
     .action(async () => {
-    const { json } = program.opts();
-    await disconnectCommand({ json });
+    const { json, instance } = program.opts();
+    await disconnectCommand({ json, instance });
 });
 program
     .command('read-rem [remIdOrJson]')
@@ -187,6 +203,7 @@ program
     .option('--depth <depth>', '展开深度（默认 3，仅 page 模式）')
     .option('--max-nodes <maxNodes>', '全局节点上限（默认 200）')
     .option('--max-siblings <maxSiblings>', '每个父节点下展示的 children 上限（默认 20）')
+    .option('--focus-rem-id <remId>', '指定鱼眼中心 Rem ID（仅 focus 模式，默认使用当前焦点）')
     .action(async (jsonStr, cmdOpts) => {
     const { json } = program.opts();
     if (json) {
@@ -208,6 +225,7 @@ program
             depth: input.depth?.toString(),
             maxNodes: input.maxNodes?.toString(),
             maxSiblings: input.maxSiblings?.toString(),
+            focusRemId: input.focusRemId ? String(input.focusRemId) : undefined,
         });
     }
     else {
@@ -329,4 +347,28 @@ program
     const { json } = program.opts();
     await cleanCommand({ json });
 });
+// addon 子命令组
+const addonCmd = program.command('addon').description('管理增强项目（addon）');
+addonCmd
+    .command('list')
+    .description('查看所有增强项目状态')
+    .action(async () => {
+    const { json } = program.opts();
+    await addonListCommand({ json });
+});
+addonCmd
+    .command('install <name>')
+    .description('安装指定增强项目')
+    .action(async (name) => {
+    const { json } = program.opts();
+    await addonInstallCommand(name, { json });
+});
+addonCmd
+    .command('uninstall <name>')
+    .description('卸载指定增强项目')
+    .option('--purge', '同时删除数据目录')
+    .action(async (name, cmdOpts) => {
+    const { json } = program.opts();
+    await addonUninstallCommand(name, { json, purge: cmdOpts.purge });
+});
 program.parse();