remnote-bridge 0.1.11 → 0.1.13

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

@@ -1,17 +1,12 @@
 /**
  * EditHandler — edit-rem 命令的编排器
  *
- * 在 daemon 层实现三道防线 + str_replace + 后处理校验。
+ * 在 daemon 层实现两道防线 + 字段白名单校验 + 直接转发 changes。
  * Plugin 只负责原子写入（write_rem_fields）。
  *
  * 防线 1：缓存存在性检查（必须先 read 再 edit）
  * 防线 2：乐观并发检测（当前 JSON 与缓存 JSON 比较）
- * 防线 3：str_replace 精确匹配（old_str 必须唯一匹配）
- *
- * Portal 专用路径：type === 'portal' 时，在简化 JSON（9 字段）上执行 str_replace，
- * 推导变更后调用专用写入逻辑。
  */
-import { PORTAL_FIELDS } from './read-handler.js';
 /** 只读字段集合 — 变更这些字段只产生警告，不执行写入 */
 const READ_ONLY_FIELDS = new Set([
     'id',
@@ -30,10 +25,22 @@ const READ_ONLY_FIELDS = new Set([
     'isPowerup', 'isPowerupEnum', 'isPowerupProperty',
     'isPowerupPropertyListItem', 'isPowerupSlot',
 ]);
-/** Portal 简化 JSON 中的只读字段 */
-const PORTAL_READONLY_FIELDS = new Set([
-    'id', 'type', 'portalType', 'children', 'createdAt', 'updatedAt',
+/** 可写字段白名单 — 21 个可写字段 */
+const WRITABLE_FIELDS = new Set([
+    'text', 'backText', 'type', 'isDocument', 'parent',
+    'fontSize', 'highlightColor',
+    'isTodo', 'todoStatus', 'isCode', 'isQuote', 'isListItem', 'isCardItem', 'isSlot', 'isProperty',
+    'enablePractice', 'practiceDirection',
+    'tags', 'sources', 'positionAmongstSiblings', 'portalDirectlyIncludedRem',
 ]);
+/** 枚举字段的合法值 */
+const ENUM_VALUES = {
+    type: new Set(['concept', 'descriptor', 'default']),
+    practiceDirection: new Set(['forward', 'backward', 'both', 'none']),
+    highlightColor: new Set(['Red', 'Orange', 'Yellow', 'Green', 'Blue', 'Purple', 'Gray', 'Brown', 'Pink', null]),
+    fontSize: new Set(['H1', 'H2', 'H3', null]),
+    todoStatus: new Set(['Finished', 'Unfinished', null]),
+};
 export class EditHandler {
     cache;
     forwardToPlugin;
@@ -42,145 +49,61 @@ export class EditHandler {
         this.forwardToPlugin = forwardToPlugin;
     }
     async handleEditRem(payload) {
-        const { remId, oldStr, newStr } = payload;
+        const { remId, changes } = payload;
+        if (!changes || typeof changes !== 'object' || Object.keys(changes).length === 0) {
+            return { ok: true, changes: [], warnings: [] };
+        }
         // ── 防线 1: 缓存存在性检查 ──
-        const cachedJson = this.cache.get('rem:' + remId);
-        if (!cachedJson) {
+        const cachedObj = this.cache.get('rem:' + remId);
+        if (!cachedObj) {
             throw new Error(`Rem ${remId} has not been read yet. Read it first before editing.`);
         }
         // ── 防线 2: 乐观并发检测 ──
         const currentRemObject = await this.forwardToPlugin('read_rem', { remId });
         const currentJson = JSON.stringify(currentRemObject, null, 2);
+        const cachedJson = JSON.stringify(cachedObj, null, 2);
         if (currentJson !== cachedJson) {
             // 不更新缓存 — 迫使 AI re-read
             throw new Error(`Rem ${remId} has been modified since last read. Please read it again before editing.`);
         }
-        // ── 检测 Portal 类型，分流到专用路径 ──
-        const cachedObj = JSON.parse(cachedJson);
-        if (cachedObj.type === 'portal') {
-            return this.handlePortalEdit(remId, cachedJson, cachedObj, oldStr, newStr);
-        }
-        // ── 普通 Rem 路径 ──
-        return this.handleNormalEdit(remId, cachedJson, cachedObj, oldStr, newStr);
-    }
-    /** Portal 专用编辑路径：在简化 JSON 上执行 str_replace */
-    async handlePortalEdit(remId, cachedJson, fullObj, oldStr, newStr) {
-        // 从完整对象提取简化 JSON
-        const simplified = {};
-        for (const field of PORTAL_FIELDS) {
-            if (field in fullObj) {
-                simplified[field] = fullObj[field];
-            }
-        }
-        const simplifiedJson = JSON.stringify(simplified, null, 2);
-        // ── 防线 3: str_replace 在简化 JSON 上精确匹配 ──
-        const matchCount = countOccurrences(simplifiedJson, oldStr);
-        if (matchCount === 0) {
-            throw new Error(`old_str not found in the simplified Portal JSON of rem ${remId}`);
-        }
-        if (matchCount > 1) {
-            throw new Error(`old_str matches ${matchCount} locations in Portal rem ${remId}. ` +
-                `Make old_str more specific to match exactly once.`);
-        }
-        const modifiedSimplifiedJson = simplifiedJson.replace(oldStr, newStr);
-        // JSON 解析
-        let modified;
-        try {
-            modified = JSON.parse(modifiedSimplifiedJson);
-        }
-        catch {
-            throw new Error('The replacement produced invalid JSON. Check your new_str for syntax errors.');
-        }
-        // 推导变更字段
-        const changes = {};
+        // ── 遍历 changes keys：分类过滤 ──
         const warnings = [];
-        for (const key of Object.keys(modified)) {
-            if (JSON.stringify(modified[key]) !== JSON.stringify(simplified[key])) {
-                if (PORTAL_READONLY_FIELDS.has(key)) {
-                    warnings.push(`Field '${key}' is read-only and was ignored`);
-                }
-                else {
-                    changes[key] = modified[key];
-                }
+        const writableChanges = {};
+        for (const key of Object.keys(changes)) {
+            if (READ_ONLY_FIELDS.has(key)) {
+                warnings.push(`Field '${key}' is read-only and was ignored`);
+            }
+            else if (!WRITABLE_FIELDS.has(key)) {
+                warnings.push(`Field '${key}' is unknown and was ignored`);
+            }
+            else {
+                writableChanges[key] = changes[key];
             }
         }
-        // 空变更检查
-        if (Object.keys(changes).length === 0) {
-            return { ok: true, changes: [], warnings };
-        }
-        // ── 发送变更到 Plugin ──
-        const writeResult = (await this.forwardToPlugin('write_rem_fields', {
-            remId,
-            changes,
-        }));
-        if (writeResult.failed) {
-            return {
-                ok: false,
-                changes: [],
-                warnings,
-                error: `Failed to update field '${writeResult.failed.field}': ${writeResult.failed.error}`,
-                appliedChanges: writeResult.applied,
-                failedField: writeResult.failed.field,
-            };
-        }
-        // ── 写入成功 → 从 Plugin 重新获取完整 Rem 并更新缓存（D5）──
-        const freshRemObject = await this.forwardToPlugin('read_rem', { remId });
-        const freshJson = JSON.stringify(freshRemObject, null, 2);
-        this.cache.set('rem:' + remId, freshJson);
-        return {
-            ok: true,
-            changes: Object.keys(changes),
-            warnings,
-        };
-    }
-    /** 普通 Rem 编辑路径：在完整 JSON 上执行 str_replace */
-    async handleNormalEdit(remId, cachedJson, original, oldStr, newStr) {
-        // ── 防线 3: str_replace 精确匹配 ──
-        const matchCount = countOccurrences(cachedJson, oldStr);
-        if (matchCount === 0) {
-            throw new Error(`old_str not found in the serialized JSON of rem ${remId}`);
-        }
-        if (matchCount > 1) {
-            throw new Error(`old_str matches ${matchCount} locations in rem ${remId}. ` +
-                `Make old_str more specific to match exactly once.`);
-        }
-        const modifiedJson = cachedJson.replace(oldStr, newStr);
-        // 1. JSON 解析
-        let modified;
-        try {
-            modified = JSON.parse(modifiedJson);
-        }
-        catch {
-            throw new Error('The replacement produced invalid JSON. Check your new_str for syntax errors.');
-        }
-        // 2. 推导变更字段
-        const changes = {};
-        const warnings = [];
-        for (const key of Object.keys(modified)) {
-            if (JSON.stringify(modified[key]) !== JSON.stringify(original[key])) {
-                if (READ_ONLY_FIELDS.has(key)) {
-                    warnings.push(`Field '${key}' is read-only and was ignored`);
-                }
-                else {
-                    changes[key] = modified[key];
+        // ── 枚举值范围校验 ──
+        for (const [field, allowedValues] of Object.entries(ENUM_VALUES)) {
+            if (field in writableChanges) {
+                const value = writableChanges[field];
+                if (!allowedValues.has(value)) {
+                    throw new Error(`Invalid value for '${field}': ${JSON.stringify(value)}. Allowed: ${[...allowedValues].map(v => JSON.stringify(v)).join(', ')}`);
                 }
             }
         }
-        // 3. 语义一致性校验
-        if ('todoStatus' in changes && changes.todoStatus !== null) {
-            const isTodo = modified.isTodo ?? original.isTodo;
+        // ── 语义校验：todoStatus 非 null 但 isTodo 未启用 ──
+        if ('todoStatus' in writableChanges && writableChanges.todoStatus !== null) {
+            const isTodo = writableChanges.isTodo ?? cachedObj.isTodo;
             if (!isTodo) {
                 warnings.push("Setting 'todoStatus' without 'isTodo: true' may have no effect");
             }
         }
-        // 4. 空变更检查
-        if (Object.keys(changes).length === 0) {
+        // ── 空变更检查 ──
+        if (Object.keys(writableChanges).length === 0) {
             return { ok: true, changes: [], warnings };
         }
         // ── 发送变更到 Plugin ──
         const writeResult = (await this.forwardToPlugin('write_rem_fields', {
             remId,
-            changes,
+            changes: writableChanges,
         }));
         if (writeResult.failed) {
             // 部分失败 — 不更新缓存（迫使 AI re-read）
@@ -193,27 +116,13 @@ export class EditHandler {
                 failedField: writeResult.failed.field,
             };
         }
-        // ── 写入成功 → 从 Plugin 重新获取完整 Rem 并更新缓存（D5）──
+        // ── 写入成功 → 从 Plugin 重新获取完整 Rem 并更新缓存 ──
         const freshRemObject = await this.forwardToPlugin('read_rem', { remId });
-        const freshJson = JSON.stringify(freshRemObject, null, 2);
-        this.cache.set('rem:' + remId, freshJson);
+        this.cache.set('rem:' + remId, freshRemObject);
         return {
             ok: true,
-            changes: Object.keys(changes),
+            changes: Object.keys(writableChanges),
             warnings,
         };
     }
 }
-/** 统计 needle 在 haystack 中出现的次数 */
-function countOccurrences(haystack, needle) {
-    let count = 0;
-    let pos = 0;
-    while (true) {
-        pos = haystack.indexOf(needle, pos);
-        if (pos === -1)
-            break;
-        count++;
-        pos += needle.length; // 非重叠匹配，与 String.replace 行为一致
-    }
-    return count;
-}

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 {
@@ -43,17 +44,16 @@ export class ReadHandler {
         const includePowerup = payload.includePowerup ?? false;
         // 转发到 Plugin
         const remObject = await this.forwardToPlugin('read_rem', { remId, includePowerup });
-        // 缓存完整 JSON
-        const fullJson = JSON.stringify(remObject, null, 2);
-        this.cache.set(cacheKey, fullJson);
-        this.onLog?.(`缓存 Rem ${remId.slice(0, 8)}... (${fullJson.length} bytes)`, 'info');
+        // 缓存完整 RemObject 对象
+        this.cache.set(cacheKey, remObject);
+        this.onLog?.(`缓存 Rem ${remId.slice(0, 8)}...`, 'info');
         // 字段过滤
         const fields = payload.fields;
         const full = payload.full;
         let result;
         if (full) {
-            // --full → 返回完整对象（含 R-F 字段）
-            result = remObject;
+            // --full → 返回完整对象（含 R-F 字段）。浅拷贝避免污染缓存对象。
+            result = { ...remObject };
         }
         else if (fields) {
             // --fields 过滤：只返回指定字段 + id
@@ -66,7 +66,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/rem-cache.js

@@ -1,8 +1,13 @@
 /**
- * RemCache — LRU 缓存，存储 Rem 的序列化 JSON
+ * RemCache — LRU 缓存，存储 Rem 数据
  *
  * 缓存存储在 daemon 内存中，生命周期与 daemon 一致。
  * disconnect 关闭 daemon → 缓存自然消失。
+ *
+ * 泛化值类型：不同 key 前缀存储不同类型的数据：
+ * - rem:{remId} → RemObject 对象
+ * - tree:{remId} → Markdown outline 字符串
+ * - tree-depth:{remId} 等 → 参数值字符串
  */
 export class RemCache {
     cache = new Map();
@@ -15,19 +20,19 @@ export class RemCache {
         if (!entry)
             return null;
         entry.lastAccess = Date.now();
-        return entry.json;
+        return entry.data;
     }
     /** 获取缓存条目的创建时间（ISO 8601），不存在返回 null */
     getCreatedAt(remId) {
         const entry = this.cache.get(remId);
         return entry ? entry.createdAt : null;
     }
-    set(remId, json) {
+    set(remId, data) {
         const now = Date.now();
         const createdAt = new Date(now).toISOString();
         if (this.cache.has(remId)) {
             const entry = this.cache.get(remId);
-            entry.json = json;
+            entry.data = data;
             entry.lastAccess = now;
             entry.createdAt = createdAt;
             return;
@@ -46,7 +51,7 @@ export class RemCache {
                 this.cache.delete(oldestId);
             }
         }
-        this.cache.set(remId, { json, lastAccess: now, createdAt });
+        this.cache.set(remId, { data, lastAccess: now, createdAt });
     }
     has(remId) {
         return this.cache.has(remId);

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]')
@@ -105,7 +121,7 @@ program
         const input = parseJsonInput('read-rem', remIdOrJson);
         if (!input)
             return;
-        await readRemCommand(input.remId, { json, fields: input.fields?.join(','), full: input.full, includePowerup: input.includePowerup });
+        await readRemCommand(input.remId, { json, fields: input.fields, full: input.full, includePowerup: input.includePowerup });
     }
     else {
         if (!remIdOrJson) {
@@ -266,7 +282,7 @@ program
             process.exitCode = 1;
             return;
         }
-        await searchCommand(input.query, { json, limit: input.numResults?.toString() });
+        await searchCommand(input.query, { json, limit: (input.limit ?? input.numResults)?.toString() });
     }
     else {
         if (!queryOrJson) {
@@ -279,16 +295,15 @@ program
 });
 program
     .command('edit-rem [remIdOrJson]')
-    .description('通过 str_replace 编辑 Rem 的 JSON 字段')
-    .option('--old-str <oldStr>', '要替换的原始文本片段')
-    .option('--new-str <newStr>', '替换后的新文本片段')
+    .description('直接修改 Rem 的属性字段')
+    .option('--changes <changesJson>', '要修改的字段及新值（JSON 字符串）')
     .action(async (remIdOrJson, cmdOpts) => {
     const { json } = program.opts();
     if (json) {
-        const input = parseJsonInput('edit-rem', remIdOrJson, ['oldStr', 'newStr']);
+        const input = parseJsonInput('edit-rem', remIdOrJson, ['changes']);
         if (!input)
             return;
-        await editRemCommand(input.remId, { json, oldStr: input.oldStr, newStr: input.newStr });
+        await editRemCommand(input.remId, { json, changes: input.changes });
     }
     else {
         if (!remIdOrJson) {
@@ -296,12 +311,21 @@ program
             process.exitCode = 1;
             return;
         }
-        if (!cmdOpts.oldStr || cmdOpts.newStr === undefined) {
-            console.error('错误: --old-str 和 --new-str 是必需的');
+        if (!cmdOpts.changes) {
+            console.error('错误: --changes 是必需的');
             process.exitCode = 1;
             return;
         }
-        await editRemCommand(remIdOrJson, { json, oldStr: cmdOpts.oldStr, newStr: cmdOpts.newStr });
+        let changes;
+        try {
+            changes = JSON.parse(cmdOpts.changes);
+        }
+        catch {
+            console.error('错误: --changes 不是合法的 JSON');
+            process.exitCode = 1;
+            return;
+        }
+        await editRemCommand(remIdOrJson, { json, changes });
     }
 });
 // mcp 子命令
@@ -331,4 +355,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();

package/dist/cli/protocol.js

@@ -6,10 +6,15 @@
  */
 // ── 消息类型判断辅助 ──
 export function isHelloMessage(msg) {
-    return (typeof msg === 'object' &&
-        msg !== null &&
-        msg.type === 'hello' &&
-        typeof msg.version === 'string');
+    if (typeof msg !== 'object' || msg === null)
+        return false;
+    const obj = msg;
+    return (obj.type === 'hello' &&
+        typeof obj.version === 'string' &&
+        typeof obj.twinSlotIndex === 'number' &&
+        Number.isInteger(obj.twinSlotIndex) &&
+        obj.twinSlotIndex >= 0 &&
+        obj.twinSlotIndex <= 3);
 }
 export function isPingMessage(msg) {
     return (typeof msg === 'object' &&
@@ -33,3 +38,12 @@ export function isBridgeResponse(msg) {
         typeof msg.id === 'string' &&
         !('action' in msg));
 }
+// ── WS Close Codes ──
+/** 已有其他 Plugin 连接（非孪生），拒绝 */
+export const WS_CLOSE_OTHER_CONNECTED = 4000;
+/** 心跳超时，断开连接 */
+export const WS_CLOSE_PONG_TIMEOUT = 4001;
+/** 被孪生 Plugin 抢占（daemon 主动断开非孪生连接） */
+export const WS_CLOSE_PREEMPTED = 4002;
+/** 孪生已连，拒绝非孪生 */
+export const WS_CLOSE_TWIN_EXISTS = 4003;