remnote-bridge 0.1.13 → 0.1.14

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

@@ -0,0 +1,73 @@
+/**
+ * TreeRemReadHandler — read-rem-in-tree 请求的业务编排
+ *
+ * 职责：
+ * 1. 转发到 Plugin 获取 outline + remObjects
+ * 2. 缓存 tree:{remId} + 参数（供 edit_tree 使用）
+ * 3. 缓存 rem:{nodeRemId}（供 edit_rem 使用）
+ * 4. 对每个 RemObject 应用字段过滤
+ */
+import { DEFAULT_DEFAULTS } from '../config.js';
+import { filterRemFields } from './rem-field-filter.js';
+export class TreeRemReadHandler {
+    cache;
+    forwardToPlugin;
+    onLog;
+    defaults;
+    constructor(cache, forwardToPlugin, onLog, defaults) {
+        this.cache = cache;
+        this.forwardToPlugin = forwardToPlugin;
+        this.onLog = onLog;
+        this.defaults = defaults ?? DEFAULT_DEFAULTS;
+    }
+    async handleReadRemInTree(payload) {
+        const remId = payload.remId;
+        if (!remId) {
+            throw new Error('缺少 remId 参数');
+        }
+        const depth = payload.depth ?? this.defaults.readTreeDepth;
+        const maxNodes = payload.maxNodes ?? this.defaults.readRemInTreeMaxNodes;
+        const maxSiblings = payload.maxSiblings ?? this.defaults.maxSiblings;
+        const ancestorLevels = payload.ancestorLevels ?? this.defaults.readTreeAncestorLevels;
+        const includePowerup = payload.includePowerup ?? this.defaults.readTreeIncludePowerup;
+        // 检查旧缓存
+        const treeCacheKey = 'tree:' + remId;
+        const previousTreeCachedAt = this.cache.getCreatedAt(treeCacheKey);
+        // 转发到 Plugin
+        const result = await this.forwardToPlugin('read_rem_in_tree', {
+            remId, depth, maxNodes, maxSiblings, ancestorLevels, includePowerup,
+        });
+        // 剥离内部字段 nodeRemIds（不暴露给 CLI 输出）
+        delete result.nodeRemIds;
+        // 缓存 tree outline + 参数（供 edit_tree 使用）
+        this.cache.set(treeCacheKey, result.outline);
+        this.cache.set('tree-depth:' + remId, String(depth));
+        this.cache.set('tree-maxNodes:' + remId, String(maxNodes));
+        this.cache.set('tree-maxSiblings:' + remId, String(maxSiblings));
+        this.onLog?.(`缓存树 ${remId.slice(0, 8)}... (${result.nodeCount} 节点, ${result.outline.length} bytes)`, 'info');
+        // 缓存每个 RemObject（供 edit_rem 使用）
+        const remObjects = result.remObjects ?? {};
+        let remCachedCount = 0;
+        for (const [nodeId, remObj] of Object.entries(remObjects)) {
+            this.cache.set('rem:' + nodeId, remObj);
+            remCachedCount++;
+        }
+        this.onLog?.(`缓存 ${remCachedCount} 个 RemObject`, 'info');
+        // 字段过滤
+        const fields = payload.fields;
+        const full = payload.full;
+        const filteredRemObjects = {};
+        for (const [nodeId, remObj] of Object.entries(remObjects)) {
+            filteredRemObjects[nodeId] = filterRemFields(remObj, { full, fields });
+        }
+        // 附加缓存覆盖提示
+        const finalResult = {
+            ...result,
+            remObjects: filteredRemObjects,
+        };
+        if (previousTreeCachedAt) {
+            finalResult._cacheOverridden = { id: remId, previousCachedAt: previousTreeCachedAt };
+        }
+        return finalResult;
+    }
+}

package/dist/cli/main.js

@@ -13,6 +13,7 @@ import { disconnectCommand } from './commands/disconnect.js';
 import { readRemCommand } from './commands/read-rem.js';
 import { editRemCommand } from './commands/edit-rem.js';
 import { readTreeCommand } from './commands/read-tree.js';
+import { readRemInTreeCommand } from './commands/read-rem-in-tree.js';
 import { editTreeCommand } from './commands/edit-tree.js';
 import { readGlobeCommand } from './commands/read-globe.js';
 import { readContextCommand } from './commands/read-context.js';
@@ -61,13 +62,27 @@ program
     .description('RemNote Bridge — CLI + MCP Server + Plugin')
     .version(version)
     .option('--json', '以 JSON 格式输出（适用于程序化调用）')
-    .option('--instance <name>', '指定 daemon 实例名（也可用 REMNOTE_BRIDGE_INSTANCE 环境变量）')
-    .option('--headless', '使用 headless 实例（覆盖 --instance，也可用 REMNOTE_HEADLESS=1 环境变量）');
+    .option('--instance <name>', '指定 daemon 实例名（"headless" 是保留名，不可使用）')
+    .option('--headless', '使用 headless 模式（固定实例名为 headless，也可用 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';
+    // 禁止 --instance headless，必须使用 --headless
+    if (!isHeadless && opts.instance === 'headless') {
+        const msg = '错误: --instance headless 不是合法用法。请使用 --headless 全局选项连接 headless 实例。\n'
+            + '用法: remnote-bridge --headless connect（启动）→ remnote-bridge --headless <命令>（后续操作）';
+        if (opts.json) {
+            console.log(JSON.stringify({ ok: false, command: 'unknown', error: msg }));
+        }
+        else {
+            console.error(msg);
+        }
+        process.exitCode = 1;
+        // 阻止后续命令执行
+        process.exit(1);
+    }
     if (isHeadless) {
         // headless 覆盖 instance，固定实例名
         process.env.REMNOTE_HEADLESS = '1';
@@ -164,6 +179,42 @@ program
         await readTreeCommand(remIdOrJson, { json, ...cmdOpts });
     }
 });
+program
+    .command('read-rem-in-tree [remIdOrJson]')
+    .description('读取 Rem 子树大纲 + 每个节点的完整 RemObject（read-tree + read-rem 合体）')
+    .option('--depth <depth>', '展开深度（默认 3，-1 = 全部展开）')
+    .option('--max-nodes <maxNodes>', '全局节点上限（默认 50）')
+    .option('--max-siblings <maxSiblings>', '每个父节点下展示的 children 上限（默认 20）')
+    .option('--ancestor-levels <ancestorLevels>', '向上追溯祖先层数（默认 0，上限 10）')
+    .option('--fields <fields>', '只返回 RemObject 中指定字段（逗号分隔）')
+    .option('--full', '输出全部 51 个字段（含 R-F 低频字段）')
+    .option('--includePowerup', '包含 Powerup 系统数据（默认过滤）')
+    .action(async (remIdOrJson, cmdOpts) => {
+    const { json } = program.opts();
+    if (json) {
+        const input = parseJsonInput('read-rem-in-tree', remIdOrJson);
+        if (!input)
+            return;
+        await readRemInTreeCommand(input.remId, {
+            json,
+            depth: input.depth?.toString(),
+            maxNodes: input.maxNodes?.toString(),
+            maxSiblings: input.maxSiblings?.toString(),
+            ancestorLevels: input.ancestorLevels?.toString(),
+            fields: input.fields,
+            full: input.full,
+            includePowerup: input.includePowerup,
+        });
+    }
+    else {
+        if (!remIdOrJson) {
+            console.error('错误: 缺少 remId');
+            process.exitCode = 1;
+            return;
+        }
+        await readRemInTreeCommand(remIdOrJson, { json, ...cmdOpts });
+    }
+});
 program
     .command('read-globe [jsonStr]')
     .description('读取知识库全局概览（仅 Document 层级）')

package/dist/cli/server/ws-server.js

@@ -19,6 +19,7 @@ import { TreeReadHandler } from '../handlers/tree-read-handler.js';
 import { TreeEditHandler } from '../handlers/tree-edit-handler.js';
 import { GlobeReadHandler } from '../handlers/globe-read-handler.js';
 import { ContextReadHandler } from '../handlers/context-read-handler.js';
+import { TreeRemReadHandler } from '../handlers/tree-rem-read-handler.js';
 import crypto from 'crypto';
 const PLUGIN_REQUEST_TIMEOUT_MS = 15_000;
 export class BridgeServer {
@@ -40,6 +41,7 @@ export class BridgeServer {
     treeEditHandler;
     globeReadHandler;
     contextReadHandler;
+    treeRemReadHandler;
     defaults;
     config;
     /** 实际监听的端口（可能与 config.port 不同，若原端口被占用则 OS 自动分配） */
@@ -69,6 +71,7 @@ export class BridgeServer {
         this.treeEditHandler = new TreeEditHandler(remCache, forwardFn, defaults);
         this.globeReadHandler = new GlobeReadHandler(forwardFn, defaults);
         this.contextReadHandler = new ContextReadHandler(forwardFn, defaults);
+        this.treeRemReadHandler = new TreeRemReadHandler(remCache, forwardFn, config.onLog, defaults);
     }
     log(message, level = 'info') {
         this.config.onLog?.(message, level);
@@ -322,6 +325,9 @@ export class BridgeServer {
             if (request.action === 'read_rem') {
                 result = await this.readHandler.handleReadRem(request.payload);
             }
+            else if (request.action === 'read_rem_in_tree') {
+                result = await this.treeRemReadHandler.handleReadRemInTree(request.payload);
+            }
             else if (request.action === 'read_tree') {
                 result = await this.treeReadHandler.handleReadTree(request.payload);
             }
@@ -430,8 +436,10 @@ export class BridgeServer {
     }
     /** 获取当前状态（timeoutRemaining 通过构造时注入的回调获取） */
     getStatus() {
+        const connected = this.pluginSocket?.readyState === WebSocket.OPEN;
         const result = {
-            pluginConnected: this.pluginSocket?.readyState === WebSocket.OPEN,
+            pluginConnected: connected,
+            pluginIsTwin: connected ? this.pluginIsTwin : false,
             sdkReady: this.pluginSdkReady,
             uptime: Math.floor((Date.now() - this.startTime) / 1000),
             timeoutRemaining: this.config.getTimeoutRemaining?.() ?? 0,

package/dist/mcp/daemon-client.js

@@ -18,6 +18,23 @@ const CLI_BIN = 'remnote-bridge';
 /** 子进程默认超时（毫秒） */
 const DEFAULT_TIMEOUT_MS = 30_000;
 // ---------------------------------------------------------------------------
+// Headless 模式状态
+// ---------------------------------------------------------------------------
+/**
+ * 记住当前会话是否为 headless 模式。
+ * connect(headless=true) 后设为 true，disconnect/clean 后清除。
+ * callCli 会自动为所有 CLI 调用注入 --headless 全局选项。
+ */
+let _headlessMode = false;
+/** 设置 headless 模式状态（由 infra-tools 的 connect/disconnect/clean 调用） */
+export function setHeadlessMode(enabled) {
+    _headlessMode = enabled;
+}
+/** 查询当前是否为 headless 模式 */
+export function isHeadlessMode() {
+    return _headlessMode;
+}
+// ---------------------------------------------------------------------------
 // 错误类
 // ---------------------------------------------------------------------------
 export class CliError extends Error {
@@ -46,8 +63,11 @@ export class CliError extends Error {
  */
 export async function callCli(command, payload, options) {
     const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-    // 构造参数列表：--json <command> [flags...] [jsonStr]
-    const args = ['--json', command];
+    // 构造参数列表：--json [--headless] <command> [flags...] [jsonStr]
+    const args = ['--json'];
+    if (_headlessMode)
+        args.push('--headless');
+    args.push(command);
     if (options?.flags) {
         args.push(...options.flags);
     }

package/dist/mcp/instructions.js

@@ -155,12 +155,12 @@ setup 只需执行一次。之后每次连接直接用 \`connect(headless=true)\
 
 \`\`\`
 connect(headless=true) → 启动 daemon + headless Chrome 自动加载 RemNote 和 Plugin
-  ↓
+  ↓                        MCP Server 自动记住 headless 状态
 health → 等待三层就绪（Plugin 需要 10-30 秒连接，可多次轮询）
+  ↓                        后续所有工具自动路由到 headless 实例
+业务操作（read / search / edit）
   ↓
-业务操作
-  ↓
-disconnect → 关闭 daemon + headless Chrome，清空所有缓存
+disconnect → 关闭 daemon + headless Chrome，清空所有缓存，清除 headless 状态
 \`\`\`
 
 #### 排查
@@ -231,6 +231,10 @@ disconnect → 关闭 daemon + headless Chrome，清空所有缓存
 
 \`read_rem\` → 确认当前属性 → \`edit_rem\` 传入 changes 对象。只需包含要修改的字段，未提及字段保持不变。
 
+**注意**：\`read_rem\` 默认模式启用 Token Slimming——省略处于默认值的字段，未返回的字段即默认值（如 type 未显示 = "default"，isTodo 未显示 = false，tags 未显示 = []）。需要完整字段用 \`full=true\`。
+
+> **批量修改多个节点时**：改用 \`read_rem_in_tree\` 一次性获取全部节点属性，避免逐个 read_rem。详见场景 D2。
+
 #### edit_rem changes 示例
 
 \`\`\`jsonc
@@ -277,6 +281,22 @@ changes: { "type": "concept", "highlightColor": "Yellow", "fontSize": "H1" }
 - **todoStatus**：依赖 \`isTodo=true\` 才生效；清除 todo 应设 \`isTodo=false\`
 - **type**：不可设为 \`portal\`（Portal 只能通过 SDK \`createPortal()\` 或 edit_tree \`<!--portal-->\` 创建）
 
+### 场景 D2：批量读取 + 标注（课本划重点）
+
+> "帮我标注这些笔记的重点"、"给关键词加高亮"、"批量修改格式"
+
+当需要读取一棵子树并对**多个节点**进行属性或富文本修改时，使用 \`read_rem_in_tree\` 一次性获取全部信息：
+
+\`read_rem_in_tree\` → 同时获取大纲 + 每个节点的 RemObject（含完整 RichText）
+  ↓
+对目标节点直接调用 \`edit_rem\`（rem 缓存已就绪，无需再逐个 read_rem）
+  +
+如需结构变更，直接调用 \`edit_tree\`（tree 缓存已就绪，无需再 read_tree）
+
+**为什么不用 read_tree + N×read_rem？** \`read_rem_in_tree\` 一次调用建立双重缓存，省去 N+1 次网络往返。对 30+ 节点的子树，差异是 1 次调用 vs 31+ 次调用。
+
+**注意**：\`read_rem_in_tree\` 默认 maxNodes=50（每节点需 40+ SDK 调用），大子树需显式设置 maxNodes。
+
 ### 场景 E：修改结构（新增/删除/移动/重排）
 
 > "在这下面加几个子项"、"删掉这个"
@@ -338,6 +358,30 @@ newStr:
   子节点 A <!--idA-->
 \`\`\`
 
+#### 行引用模板 \`{{remId}}\`
+
+在 oldStr/newStr 中使用 \`{{remId}}\` 引用缓存大纲中已有行的完整内容（不含缩进）。系统在 str_replace 前自动展开。
+
+**优势**：避免抄写完整行内容（remId、元数据标记），减少 token 浪费和复制错误。
+
+**示例：重排两个节点**
+\`\`\`
+// 不用模板：
+oldStr: "    动态数组 <!--id1_1 type:concept-->\\n    静态数组 <!--id1_2 type:concept-->"
+newStr: "    静态数组 <!--id1_2 type:concept-->\\n    动态数组 <!--id1_1 type:concept-->"
+
+// 用模板：
+oldStr: "    {{id1_1}}\\n    {{id1_2}}"
+newStr: "    {{id1_2}}\\n    {{id1_1}}"
+\`\`\`
+
+**规则**：
+- \`{{remId}}\` 展开为**不含缩进**的完整行内容，缩进由你控制
+- 只匹配纯字母数字（\`[a-zA-Z0-9]+\`），与 RemNote cloze 语法 \`{{text}}\` 不冲突（cloze 含中文/空格/标点，不会被匹配）
+- 匹配到但不在缓存大纲中的 \`{{xxx}}\` 原样保留（可能是 cloze），并输出 warning
+- 新增行不能用 \`{{}}\`（新增行没有 remId）
+- 可以混用：部分行用 \`{{id}}\`，部分行手动写
+
 #### ⚠️ children_captured 详解
 
 在有子节点的 Rem 和其 children 之间插入新行，会导致新行"劫持"已有 children：
@@ -381,7 +425,9 @@ newStr:   最后一个兄弟 <!--idZ-->
 
 ### 场景 G：排查连接问题
 
-\`health\` 检查三层状态：daemon 未运行 → \`connect\`；Plugin 未连接 → 引导用户操作 RemNote；SDK 未就绪 → 等待重试。
+\`health\` 默认查询所有活跃实例的三层状态（daemon / Plugin / SDK），返回 \`instances\` 数组。有 \`--instance\` 或 \`--headless\` 时只查询指定实例。每个实例的 \`plugin.isTwin\` 标记是否为孪生连接。
+
+故障定位：无活跃实例 → \`connect\`；Plugin 未连接 → 引导用户操作 RemNote（或使用 headless 模式）；SDK 未就绪 → 等待重试。
 
 ### 场景 H：管理增强项目
 
@@ -397,8 +443,9 @@ newStr:   最后一个兄弟 <!--idZ-->
 
 ### 黄金法则：先 read 再 edit
 
-- \`edit_rem\` 前必须先 \`read_rem\` 同一个 remId
-- \`edit_tree\` 前必须先 \`read_tree\` 同一个 remId
+- \`edit_rem\` 前必须先 \`read_rem\` 或 \`read_rem_in_tree\` 同一个 remId
+- \`edit_tree\` 前必须先 \`read_tree\` 或 \`read_rem_in_tree\` 同一个 remId
+- \`read_rem_in_tree\` 同时建立两种缓存，调用后可直接 \`edit_tree\` 和 \`edit_rem\`
 - \`search\`/\`read_globe\`/\`read_context\` **不写入缓存**，不能作为 edit 前置
 
 跳过 read 直接 edit 会被拒绝（硬性要求）。

package/dist/mcp/tools/edit-tools.js

@@ -75,6 +75,11 @@ export function registerEditTools(server) {
             '\\n- 箭头分隔符（闪卡）：→ ← ↔（单行）、↓ ↑ ↕（多行，带 backText 或子节点为答案）' +
             '\\n- 元数据注释（可选）：<!--type:concept--> <!--doc--> <!--tag:Name(id)--> 可组合' +
             '\\n- Portal 创建：<!--portal refs:id1,id2--> 或 <!--portal-->（空 Portal）' +
+            '\\n\\n行引用模板 {{remId}}：' +
+            '\\n在 oldStr/newStr 中使用 {{remId}} 引用缓存大纲中已有行的完整内容（不含缩进），系统在 str_replace 前自动展开。缩进仍由你控制。' +
+            '\\n优势：避免反复抄写行内容（含 remId 和元数据标记），减少 token 开销和复制错误。' +
+            '\\n示例 reorder：oldStr="    {{id1}}\\n    {{id2}}"  newStr="    {{id2}}\\n    {{id1}}"' +
+            '\\n规则：只匹配纯字母数字（与 RemNote cloze {{text}} 不冲突）；未找到的 {{xxx}} 原样保留并输出 templateWarnings；新增行不能使用 {{}}；可混用模板和手写内容。' +
             '\\n\\n⚠️ 插入位置红线：新行必须插在目标层级所有兄弟的末尾，不能插在父 Rem 和它的 children 之间，否则触发 children_captured 错误。如需"创建新父节点并移入已有 children"，必须分两次 edit_tree 完成。' +
             '\\n\\n六种禁止操作：' +
             '\\n- content_modified：修改已有行内容 → 改用 edit_rem' +
@@ -93,8 +98,8 @@ export function registerEditTools(server) {
             '\\n\\n关联工具：read_tree（前置读取大纲）、edit_rem（修改单个 Rem 属性/内容）',
         parameters: z.object({
             remId: z.string().describe('根 Rem 的 ID（与 read_tree 时相同）'),
-            oldStr: z.string().describe('要替换的大纲片段（必须精确匹配缓存中的内容，且恰好匹配 1 次）'),
-            newStr: z.string().describe('替换后的大纲片段（可新增/删除/移动/重排行，但禁止修改已有行内容）'),
+            oldStr: z.string().describe('要替换的大纲片段（必须精确匹配缓存中的内容，且恰好匹配 1 次）。支持 {{remId}} 引用已有行内容（不含缩进），系统自动展开'),
+            newStr: z.string().describe('替换后的大纲片段（可新增/删除/移动/重排行，但禁止修改已有行内容）。支持 {{remId}} 引用已有行内容（不含缩进），系统自动展开'),
         }),
         execute: async (args) => {
             const response = await callCli('edit-tree', {

package/dist/mcp/tools/infra-tools.js

@@ -2,7 +2,7 @@
  * 基础设施工具：setup、connect、disconnect、health
  */
 import { z } from 'zod';
-import { callCli } from '../daemon-client.js';
+import { callCli, setHeadlessMode } from '../daemon-client.js';
 import { formatDataJson } from '../format.js';
 export function registerInfraTools(server) {
     // -------------------------------------------------------------------------
@@ -22,19 +22,26 @@ export function registerInfraTools(server) {
     // -------------------------------------------------------------------------
     server.addTool({
         name: 'connect',
-        description: '启动守护进程（daemon），建立 CLI 与 RemNote Plugin 之间的通信通道。这是所有业务命令（read_rem、edit_rem、search 等）的前置步骤。\n\n适用场景：\n- 开始一次 RemNote 操作会话前，必须先调用此工具\n- 不确定 daemon 是否在运行时，也可安全调用（幂等）\n\n两种模式：\n- 标准模式（默认）：启动 daemon 后需要用户在 RemNote 中手动加载 Plugin\n- Headless 模式（headless=true）：自动启动 headless Chrome 加载 Plugin，无需用户操作。需先完成 setup（保存登录凭证）\n\n输出：返回 JSON，关键字段 ok、alreadyRunning、instance、slotIndex、pid、wsPort、headless。\n幂等：重复调用不会启动多个 daemon。daemon 默认 30 分钟无活动自动关闭。\n关联工具：setup（headless 前置）、disconnect（结束会话）、health（检查状态）',
+        description: '启动守护进程（daemon），建立 CLI 与 RemNote Plugin 之间的通信通道。这是所有业务命令（read_rem、edit_rem、search 等）的前置步骤。\n\n适用场景：\n- 开始一次 RemNote 操作会话前，必须先调用此工具\n- 不确定 daemon 是否在运行时，也可安全调用（幂等）\n\n两种模式：\n- 标准模式（默认）：启动 daemon 后需要用户在 RemNote 中手动加载 Plugin\n- Headless 模式（headless=true）：自动启动 headless Chrome 加载 Plugin，无需用户操作。需先完成 setup（保存登录凭证）\n\nHeadless 模式会话持久化：connect(headless=true) 后，MCP Server 自动记住 headless 状态，后续所有工具调用（health、read_rem、edit_rem 等）自动路由到 headless 实例，无需额外参数。disconnect 或 clean 后自动清除。\n\n输出：返回 JSON，关键字段 ok、alreadyRunning、instance、slotIndex、pid、wsPort、headless。\n幂等：重复调用不会启动多个 daemon。daemon 默认 30 分钟无活动自动关闭。\n关联工具：setup（headless 前置）、disconnect（结束会话）、health（检查状态）',
         parameters: z.object({
             headless: z.boolean().optional().describe('启用 headless 模式：自动启动 Chrome 加载 Plugin（需先 setup）'),
         }),
         execute: async (args) => {
-            const flags = [];
+            // headless 模式：connect 前先设置，确保 callCli 注入 --headless
             if (args.headless)
-                flags.push('--headless');
-            const response = await callCli('connect', undefined, {
-                timeoutMs: 90_000,
-                flags: flags.length > 0 ? flags : undefined,
-            });
-            return formatDataJson(response);
+                setHeadlessMode(true);
+            try {
+                const response = await callCli('connect', undefined, {
+                    timeoutMs: 90_000,
+                });
+                return formatDataJson(response);
+            }
+            catch (e) {
+                // connect 失败时清除 headless 状态
+                if (args.headless)
+                    setHeadlessMode(false);
+                throw e;
+            }
         },
     });
     // -------------------------------------------------------------------------
@@ -42,10 +49,11 @@ export function registerInfraTools(server) {
     // -------------------------------------------------------------------------
     server.addTool({
         name: 'disconnect',
-        description: '停止守护进程，释放所有端口、清空内存缓存、结束当前会话。\n\n适用场景：\n- 操作完成后主动释放资源\n- 需要重置连接状态（例如排查问题时先 disconnect 再 connect）\n\n输出：返回 JSON，关键字段 ok、wasRunning（之前是否在运行）、instance、pid。\n幂等：daemon 未运行时调用也返回 ok: true。\n所有缓存随 daemon 退出清空，下次 connect 后需重新 read。\n关联工具：connect（启动会话）、health（检查状态）',
+        description: '停止守护进程，释放所有端口、清空内存缓存、结束当前会话。自动清除 headless 模式状态。\n\n适用场景：\n- 操作完成后主动释放资源\n- 需要重置连接状态（例如排查问题时先 disconnect 再 connect）\n\n输出：返回 JSON，关键字段 ok、wasRunning（之前是否在运行）、instance、pid。\n幂等：daemon 未运行时调用也返回 ok: true。\n所有缓存随 daemon 退出清空，下次 connect 后需重新 read。\n关联工具：connect（启动会话）、health（检查状态）',
         parameters: z.object({}),
         execute: async () => {
             const response = await callCli('disconnect');
+            setHeadlessMode(false);
             return formatDataJson(response);
         },
     });
@@ -54,7 +62,7 @@ export function registerInfraTools(server) {
     // -------------------------------------------------------------------------
     server.addTool({
         name: 'health',
-        description: '检查系统三层状态（daemon 守护进程 / Plugin 连接 / SDK 就绪），用于诊断连接问题。\n\n适用场景：\n- 业务命令失败时，首先调用 health 定位故障层级\n- 执行 connect 后确认通道是否完全就绪\n- 长时间未操作后，检查 daemon 是否仍在运行\n\n输出：返回 JSON，关键字段 ok（三层是否全部健康）、instance、slotIndex、daemon.running、plugin.connected、sdk.ready、timeoutRemaining。headless 模式下额外包含 headless 对象。\n三层有严格依赖：daemon 运行 → Plugin 连接 → SDK 就绪。\nok 为 false 时：daemon 未运行则 connect；Plugin 未连接则确认 RemNote 已打开（或使用 headless 模式）；SDK 未就绪则等待重试。\n\n--diagnose 模式（headless 专用）：截图 + 详细状态 + console 错误 + 排查建议。\n--reload 模式（headless 专用）：重载 headless Chrome 页面。\n\n只读不写，不改变任何状态（--reload 除外）。\n关联工具：connect（启动）、disconnect（结束）',
+        description: '检查系统三层状态（daemon 守护进程 / Plugin 连接 / SDK 就绪），用于诊断连接问题。\n\n两种模式：\n- 全量模式（默认）：返回所有活跃实例的状态，字段 instances 是数组，每个元素包含 instance、slotIndex、daemon、plugin（含 isTwin 孪生标记）、sdk、timeoutRemaining\n- 单实例模式（headless 会话中自动触发）：返回当前实例的状态，结构与之前相同但 plugin 多了 isTwin 字段\n\nplugin.isTwin 表示 Plugin 连接是否为"孪生连接"——即 Plugin 的 twinSlotIndex 与 daemon 的槽位索引匹配。孪生连接优先级更高，可抢占非孪生连接。\n\n三层有严格依赖：daemon 运行 → Plugin 连接 → SDK 就绪。\nok 为 false 时：无活跃实例则 connect；Plugin 未连接则确认 RemNote 已打开（或使用 headless 模式）；SDK 未就绪则等待重试。\n\n--diagnose 模式（headless 专用）：截图 + 详细状态 + console 错误 + 排查建议。\n--reload 模式（headless 专用）：重载 headless Chrome 页面。\n\n只读不写，不改变任何状态（--reload 除外）。\n关联工具：connect（启动）、disconnect（结束）',
         parameters: z.object({
             diagnose: z.boolean().optional().describe('诊断 headless Chrome（截图 + 状态 + console 错误）'),
             reload: z.boolean().optional().describe('重载 headless Chrome 页面'),
@@ -103,6 +111,7 @@ export function registerInfraTools(server) {
         parameters: z.object({}),
         execute: async () => {
             const response = await callCli('clean');
+            setHeadlessMode(false);
             return formatDataJson(response);
         },
     });

package/dist/mcp/tools/read-tools.js

@@ -62,14 +62,16 @@ export function registerReadTools(server) {
             '\\n- full（可选，默认 false）：返回全部 51 个字段（含低频 R-F 字段，如 children、isPowerup 系列、deepRemsBeingReferenced 等）' +
             '\\n- includePowerup（可选，默认 false）：包含 Powerup 系统数据（默认过滤噪音）' +
             '\\n\\n输出格式：Data JSON，核心为 RemObject 对象。' +
-            '\\n- 默认 33 个常用字段（RW + R），full=true 时 51 个，Portal 类型自动简化为 8 个关键字段' +
-            '\\n- 关键字段：id, text, backText, type(concept/descriptor/default/portal), parent, isDocument, tags, fontSize(H1/H2/H3/null), highlightColor(Red/Orange/Yellow/Green/Blue/Purple/Gray/Brown/Pink/null), practiceDirection(forward/backward/both/none), isTodo, todoStatus(Finished/Unfinished/null)' +
+            '\\n- 默认模式（Token Slimming）：省略处于默认值的字段，典型普通 Rem 仅输出 5-6 个差异字段。未显示的字段即为默认值（如 type 未显示 = "default"，isTodo 未显示 = false，tags 未显示 = []）。始终输出的字段：id, text, parent, createdAt, updatedAt' +
+            '\\n- full=true 时返回全部 51 个字段，Portal 类型自动简化为 8 个关键字段' +
+            '\\n- 关键字段：id, text, backText(null), type(concept/descriptor/default/portal), parent, isDocument(false), tags([]), fontSize(H1/H2/H3/null), highlightColor(Red/.../Pink/null), practiceDirection(forward/backward/both/none), isTodo(false), todoStatus(Finished/Unfinished/null)——括号内为默认值' +
             '\\n- children 字段属于 R-F 层级，默认不输出，需 full=true 或 fields 指定' +
             '\\n- text/backText 是 RichText JSON 数组，元素为纯字符串或带 i 字段的对象（i:"m" 格式化文本, i:"q" Rem 引用, i:"x" LaTeX, i:"i" 图片, i:"a" 音视频）' +
             '\\n- 可能附加 cacheOverridden（覆盖旧缓存时）和 powerupFiltered（过滤统计）元数据' +
             '\\n\\n关键约束：' +
             '\\n- 结果自动写入缓存供 edit_rem 使用。缓存存储完整 RemObject，不受 fields/full 选项影响' +
             '\\n- 默认过滤 Powerup 噪音（系统 Tag 和隐藏子 Rem），includePowerup=true 可恢复' +
+            '\\n\\n⚠️ 如果你需要读取多个 Rem 的属性（≥3 个），且它们在同一棵子树下，请改用 read_rem_in_tree（一次调用批量读取，省去逐个 read_rem 的开销）。' +
             '\\n\\n典型工作流：search 定位 remId → read_rem 获取详情并建立缓存 → edit_rem 编辑属性。' +
             '\\n关联工具：search（定位 remId）、edit_rem（编辑属性，需先 read_rem）、read_tree（查看子树大纲）',
         parameters: z.object({
@@ -129,6 +131,7 @@ export function registerReadTools(server) {
             '\\n- 结果自动写入缓存供 edit_tree 使用。edit_tree 的 oldStr 必须精确匹配此大纲中的文本' +
             '\\n- 默认过滤 Powerup 噪音，includePowerup=true 可恢复' +
             '\\n- Portal 感知：Portal 类型 Rem 标注 type:portal 和 refs:id1,id2（引用的 Rem ID）' +
+            '\\n\\n⚠️ 如果你需要读取子树后对其中多个节点执行 edit_rem，请改用 read_rem_in_tree（一次调用同时建立 tree 和 rem 双重缓存，省去逐个 read_rem 的开销）。' +
             '\\n\\n典型工作流：search 定位 remId → read_tree 展开子树并建立缓存 → edit_tree 结构编辑。' +
             '\\n关联工具：search（定位 remId）、edit_tree（结构编辑，需先 read_tree）、read_rem（单 Rem JSON 详情）、read_globe（全局鸟瞰）',
         parameters: z.object({
@@ -182,6 +185,89 @@ export function registerReadTools(server) {
         },
     });
     // -------------------------------------------------------------------------
+    // read_rem_in_tree
+    // -------------------------------------------------------------------------
+    server.addTool({
+        name: 'read_rem_in_tree',
+        description: '⭐ 批量编辑场景的首选工具。当你需要读取子树并修改其中多个节点的属性/富文本时，优先使用此工具而非 read_tree + N×read_rem。' +
+            '\\nread_tree + read_rem 的完美结合体：一次调用同时获取子树 Markdown 大纲和每个节点的完整 RemObject JSON。' +
+            '\\n\\n适用场景：需要同时查看子树结构和节点详细属性时（如批量编辑前的全量读取）；一次调用同时建立 tree 缓存（供 edit_tree）和 rem 缓存（供 edit_rem）。' +
+            '\\n不适用场景：只需大纲不需属性（用 read_tree，更轻量）；只需单个 Rem 属性（用 read_rem）。' +
+            '\\n\\n前置条件：daemon 已连接；需要有效的 remId。' +
+            '\\n\\n参数说明：' +
+            '\\n- remId（必需）：子树根节点的 Rem ID' +
+            '\\n- depth（可选，默认 3，-1 无限）：递归展开深度' +
+            '\\n- maxNodes（可选，默认 50）：全局节点总预算。注意默认值比 read_tree 的 200 低，因为每节点需 40+ SDK 调用' +
+            '\\n- maxSiblings（可选，默认 20）：单个父节点下最大可见子节点数' +
+            '\\n- ancestorLevels（可选，默认 0，上限 10）：向上追溯祖先层数' +
+            '\\n- fields（可选）：RemObject 字段过滤，只返回指定字段子集' +
+            '\\n- full（可选，默认 false）：返回全部 51 个 RemObject 字段' +
+            '\\n- includePowerup（可选，默认 false）：包含 Powerup 系统数据' +
+            '\\n\\n输出格式：Data JSON，包含：' +
+            '\\n- outline：Markdown 大纲文本（与 read_tree 输出格式完全一致）' +
+            '\\n- remObjects：扁平 map { remId → RemObject }，每个 RemObject 与 read_rem 输出一致（受 fields/full 参数影响）' +
+            '\\n- rootId, depth, nodeCount 等元数据' +
+            '\\n\\n关键约束：' +
+            '\\n- 同时建立双重缓存：tree:{remId} 供 edit_tree 使用，rem:{nodeRemId} 供 edit_rem 使用' +
+            '\\n- 缓存条目约 N+4（1 tree + 3 参数 + N rem），注意 LRU 上限 200' +
+            '\\n- RemObject 默认启用 Token Slimming（与 read_rem 一致）' +
+            '\\n\\n典型工作流：read_rem_in_tree 一次获取全部信息 → edit_tree 结构编辑 + edit_rem 属性编辑。' +
+            '\\n关联工具：read_tree（只需大纲）、read_rem（只需单 Rem）、edit_tree（结构编辑）、edit_rem（属性编辑）',
+        parameters: z.object({
+            remId: z.string().describe('根 Rem 的 ID'),
+            depth: z
+                .number()
+                .optional()
+                .describe('展开深度（默认 3）'),
+            maxNodes: z
+                .number()
+                .optional()
+                .describe('节点总数上限（默认 50）'),
+            maxSiblings: z
+                .number()
+                .optional()
+                .describe('同级节点显示上限'),
+            ancestorLevels: z
+                .number()
+                .optional()
+                .describe('向上展示的祖先层级数'),
+            fields: z
+                .array(z.string())
+                .optional()
+                .describe('RemObject 字段过滤'),
+            full: z
+                .boolean()
+                .optional()
+                .describe('返回全部 RemObject 字段'),
+            includePowerup: z
+                .boolean()
+                .optional()
+                .describe('是否包含 Powerup 元信息'),
+        }),
+        execute: async (args) => {
+            const payload = { remId: args.remId };
+            if (args.depth !== undefined)
+                payload.depth = args.depth;
+            if (args.maxNodes !== undefined)
+                payload.maxNodes = args.maxNodes;
+            if (args.maxSiblings !== undefined)
+                payload.maxSiblings = args.maxSiblings;
+            if (args.ancestorLevels !== undefined)
+                payload.ancestorLevels = args.ancestorLevels;
+            if (args.fields !== undefined)
+                payload.fields = args.fields;
+            if (args.full !== undefined)
+                payload.full = args.full;
+            if (args.includePowerup !== undefined)
+                payload.includePowerup = args.includePowerup;
+            const response = await callCli('read-rem-in-tree', payload, { timeoutMs: 60_000 });
+            if (!response.data) {
+                return `read_rem_in_tree 返回了空的 data，remId: ${args.remId}。请检查该 Rem 是否存在。`;
+            }
+            return formatDataJson(response);
+        },
+    });
+    // -------------------------------------------------------------------------
     // read_globe
     // -------------------------------------------------------------------------
     server.addTool({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remnote-bridge",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "description": "RemNote 自动化桥接工具集：CLI + MCP Server + Plugin",
   "type": "module",
   "bin": {