remnote-bridge 0.1.12 → 0.1.14

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/rem-field-filter.js

@@ -0,0 +1,102 @@
+/**
+ * rem-field-filter — RemObject 字段过滤逻辑
+ *
+ * 从 ReadHandler 提取的共享模块，供 ReadHandler 和 TreeRemReadHandler 使用。
+ */
+/** R-F 字段（仅 --full 模式输出，默认不输出） */
+export const RF_FIELDS = new Set([
+    'children',
+    'isPowerup', 'isPowerupEnum', 'isPowerupProperty',
+    'isPowerupPropertyListItem', 'isPowerupSlot',
+    'deepRemsBeingReferenced',
+    'ancestorTagRem', 'descendantTagRem',
+    'portalsAndDocumentsIn', 'allRemInDocumentOrPortal', 'allRemInFolderQueue',
+    'timesSelectedInSearch', 'lastTimeMovedTo', 'schemaVersion',
+    'embeddedQueueViewMode',
+    'localUpdatedAt', 'lastPracticed',
+]);
+/** Token Slimming: 默认模式下，字段值匹配此表时省略输出。未列入的字段始终输出。 */
+export const REM_DEFAULTS = {
+    backText: null,
+    type: 'default',
+    isDocument: false,
+    fontSize: null,
+    highlightColor: null,
+    isTodo: false,
+    todoStatus: null,
+    isCode: false,
+    isQuote: false,
+    isListItem: false,
+    isCardItem: false,
+    isTable: false,
+    isSlot: false,
+    isProperty: false,
+    portalType: null,
+    portalDirectlyIncludedRem: [],
+    propertyType: null,
+    enablePractice: false,
+    practiceDirection: 'forward',
+    tags: [],
+    sources: [],
+    aliases: [],
+    remsBeingReferenced: [],
+    remsReferencingThis: [],
+    taggedRem: [],
+    descendants: [],
+    siblingRem: [],
+    positionAmongstSiblings: null,
+};
+export function matchesDefault(value, defaultValue) {
+    if (Array.isArray(defaultValue) && defaultValue.length === 0) {
+        return Array.isArray(value) && value.length === 0;
+    }
+    return value === defaultValue;
+}
+/** Portal 简化输出字段（type === 'portal' 时默认输出这 8 个字段） */
+export const PORTAL_FIELDS = [
+    'id', 'type', 'portalType', 'portalDirectlyIncludedRem',
+    'parent', 'positionAmongstSiblings',
+    'createdAt', 'updatedAt',
+];
+/**
+ * 过滤 RemObject 字段。
+ *
+ * @param remObject 完整 RemObject
+ * @param options.full 返回全部字段
+ * @param options.fields 返回指定字段子集
+ * @returns 过滤后的对象
+ */
+export function filterRemFields(remObject, options) {
+    const { full, fields } = options ?? {};
+    if (full) {
+        return { ...remObject };
+    }
+    if (fields) {
+        const result = { id: remObject.id };
+        for (const field of fields) {
+            if (field in remObject) {
+                result[field] = remObject[field];
+            }
+        }
+        return result;
+    }
+    if (remObject.type === 'portal') {
+        const result = {};
+        for (const field of PORTAL_FIELDS) {
+            if (field in remObject) {
+                result[field] = remObject[field];
+            }
+        }
+        return result;
+    }
+    // 默认模式：排除 R-F 字段 + Token Slimming
+    const result = {};
+    for (const [key, value] of Object.entries(remObject)) {
+        if (RF_FIELDS.has(key))
+            continue;
+        if (key in REM_DEFAULTS && matchesDefault(value, REM_DEFAULTS[key]))
+            continue;
+        result[key] = value;
+    }
+    return result;
+}

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

@@ -2,13 +2,64 @@
  * TreeEditHandler — edit-tree 请求的业务编排
  *
  * 职责：
- * 1. 三道防线（缓存存在、变更检测、str_replace 精确匹配）
- * 2. 解析新旧大纲并 diff
- * 3. 逐项执行操作（通过 forwardToPlugin 调用原子操作）
- * 4. 成功后重新 read-tree 更新缓存
+ * 1. 模板展开（{{remId}} → 缓存中对应行的完整内容）
+ * 2. 三道防线（缓存存在、变更检测、str_replace 精确匹配）
+ * 3. 解析新旧大纲并 diff
+ * 4. 逐项执行操作（通过 forwardToPlugin 调用原子操作）
+ * 5. 成功后重新 read-tree 更新缓存
  */
 import { DEFAULT_DEFAULTS } from '../config.js';
 import { parseOutline, diffTrees, parsePowerupPrefix } from './tree-parser.js';
+// ────────────────────────── 模板展开 ──────────────────────────
+/**
+ * 匹配 {{remId}} 占位符。
+ * 限定纯字母数字，避免与 RemNote cloze 语法 {{text}} 冲突
+ * （cloze 内容可能含中文、空格、标点，不会被此正则匹配）。
+ */
+const TEMPLATE_RE = /\{\{([a-zA-Z0-9]+)\}\}/g;
+/** 行尾标记正则（与 tree-parser.ts 的 LINE_MARKER_RE 一致） */
+const LINE_MARKER_RE = /<!--(\S+)(?:\s+\S+)*-->$/;
+/** 省略占位符正则（与 tree-parser.ts 的 ELIDED_LINE_RE 一致） */
+const ELIDED_LINE_RE = /^<!--\.\.\.elided\s/;
+/**
+ * 从缓存大纲构建 remId → 去缩进完整行 的映射。
+ * 省略占位符行无 remId，自然不会进入映射。
+ */
+function buildLineMap(cachedOutline) {
+    const map = new Map();
+    for (const line of cachedOutline.split('\n')) {
+        const stripped = line.trimStart();
+        if (!stripped || ELIDED_LINE_RE.test(stripped))
+            continue;
+        const match = stripped.match(LINE_MARKER_RE);
+        if (match) {
+            map.set(match[1], stripped);
+        }
+    }
+    return map;
+}
+/**
+ * 展开 oldStr/newStr 中的 {{remId}} 占位符。
+ *
+ * {{remId}} 被替换为该 remId 在缓存大纲中对应行的完整内容（不含缩进）。
+ * 不含 {{}} 的文本原样返回（零开销，向后兼容）。
+ *
+ * 匹配到纯字母数字但不在 lineMap 中的 {{xxx}} 原样保留（可能是 cloze 内容），
+ * 不报错，避免与 RemNote 的 {{cloze}} 语法冲突。未展开的模板记录在 warnings 中。
+ */
+function expandTemplates(text, lineMap, warnings) {
+    if (!text.includes('{{'))
+        return text;
+    return text.replace(TEMPLATE_RE, (match, remId) => {
+        const content = lineMap.get(remId);
+        if (content === undefined) {
+            // 不在 lineMap 中：可能是 cloze 文本，原样保留并记录 warning
+            warnings.push(`{{${remId}}} 未在缓存大纲中找到，已原样保留（若为 cloze 可忽略；若为 remId 请检查拼写）`);
+            return match;
+        }
+        return content;
+    });
+}
 export class TreeEditHandler {
     cache;
     forwardToPlugin;
@@ -42,8 +93,17 @@ export class TreeEditHandler {
             // 不更新缓存 — 迫使 AI re-read
             throw new Error(`Tree rooted at ${remId} has been modified since last read-tree. Please read-tree again.`);
         }
+        // ── 模板展开：{{remId}} → 缓存中对应行的完整内容（不含缩进）──
+        const lineMap = buildLineMap(cachedOutline);
+        const templateWarnings = [];
+        const expandedOldStr = expandTemplates(oldStr, lineMap, templateWarnings);
+        const expandedNewStr = expandTemplates(newStr, lineMap, templateWarnings);
+        // 展开后 noop 检查（原始不等但展开后可能相等）
+        if (expandedOldStr === expandedNewStr) {
+            return { ok: true, operations: [], ...(templateWarnings.length > 0 && { templateWarnings }) };
+        }
         // ── 防线 3: str_replace 精确匹配 ──
-        const matchCount = countOccurrences(cachedOutline, oldStr);
+        const matchCount = countOccurrences(cachedOutline, expandedOldStr);
         if (matchCount === 0) {
             throw new Error(`old_str not found in the tree outline of ${remId}`);
         }
@@ -51,7 +111,7 @@ export class TreeEditHandler {
             throw new Error(`old_str matches ${matchCount} locations in the tree outline of ${remId}. ` +
                 `Make old_str more specific to match exactly once.`);
         }
-        const modifiedOutline = cachedOutline.replace(oldStr, newStr);
+        const modifiedOutline = cachedOutline.replace(expandedOldStr, expandedNewStr);
         // ── 解析新旧大纲 ──
         const oldTree = parseOutline(cachedOutline);
         const newTree = parseOutline(modifiedOutline);
@@ -201,7 +261,7 @@ export class TreeEditHandler {
         // ── D3: 成功后更新缓存（使用相同参数）──
         const updatedResult = await this.forwardToPlugin('read_tree', { remId, depth, maxNodes, maxSiblings });
         this.cache.set('tree:' + remId, updatedResult.outline);
-        return { ok: true, operations };
+        return { ok: true, operations, ...(templateWarnings.length > 0 && { templateWarnings }) };
     }
 }
 /** 统计 needle 在 haystack 中出现的次数 */

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

@@ -32,9 +32,12 @@ export class TreeReadHandler {
         const cacheKey = 'tree:' + remId;
         const previousCachedAt = this.cache.getCreatedAt(cacheKey);
         // 转发到 Plugin 的 read_tree service
-        const result = await this.forwardToPlugin('read_tree', {
+        const rawResult = await this.forwardToPlugin('read_tree', {
             remId, depth, maxNodes, maxSiblings, ancestorLevels, includePowerup,
         });
+        // 剥离内部字段 nodeRemIds（不暴露给 CLI 输出）
+        delete rawResult.nodeRemIds;
+        const result = rawResult;
         // 缓存大纲文本 + 读取参数（供 edit-tree 乐观并发检测时复现相同查询）
         this.cache.set(cacheKey, result.outline);
         this.cache.set('tree-depth:' + remId, String(depth));

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';
@@ -121,7 +136,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) {
@@ -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 层级）')
@@ -282,7 +333,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) {
@@ -295,16 +346,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) {
@@ -312,12 +362,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;
+        }
+        let changes;
+        try {
+            changes = JSON.parse(cmdOpts.changes);
+        }
+        catch {
+            console.error('错误: --changes 不是合法的 JSON');
             process.exitCode = 1;
             return;
         }
-        await editRemCommand(remIdOrJson, { json, oldStr: cmdOpts.oldStr, newStr: cmdOpts.newStr });
+        await editRemCommand(remIdOrJson, { json, changes });
     }
 });
 // mcp 子命令

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/format.js

@@ -0,0 +1,43 @@
+/**
+ * MCP 返回值格式化工具
+ *
+ * 两种模式：
+ * - formatFrontmatter：YAML frontmatter + body（read 类工具）
+ * - formatDataJson：剥离 wrapper 的 JSON（action/infra 工具）
+ */
+// ---------------------------------------------------------------------------
+// 模式 A：Frontmatter + Body
+// ---------------------------------------------------------------------------
+/**
+ * 将元数据序列化为 YAML frontmatter，拼接 body 内容。
+ *
+ * - null/undefined 的值自动跳过
+ * - 数字/布尔：裸值（`nodeCount: 42`）
+ * - 字符串：JSON 引号（`mode: "focus"`）
+ * - 数组/对象：JSON 内联（`ancestors: [{"id":"x"}]`）
+ * - 无元数据时省略 `---` 分隔符，直接返回 body
+ */
+export function formatFrontmatter(meta, body) {
+    const entries = Object.entries(meta).filter(([, v]) => v !== undefined && v !== null);
+    if (entries.length === 0)
+        return body;
+    const lines = entries.map(([k, v]) => {
+        if (typeof v === 'number' || typeof v === 'boolean')
+            return `${k}: ${v}`;
+        return `${k}: ${JSON.stringify(v)}`;
+    });
+    return `---\n${lines.join('\n')}\n---\n\n${body}`;
+}
+// ---------------------------------------------------------------------------
+// 模式 B：Data JSON（剥离 ok/command/timestamp wrapper）
+// ---------------------------------------------------------------------------
+/**
+ * 从 CLI 响应中剥离 ok/command/timestamp，返回剩余字段的 JSON。
+ *
+ * 用于 action/infra 工具——AI 不需要看到冗余的 wrapper 字段。
+ * callCli 已在 ok===false 时抛出 CliError，成功路径 ok 始终为 true。
+ */
+export function formatDataJson(response) {
+    const { ok: _ok, command: _cmd, timestamp: _ts, ...rest } = response;
+    return JSON.stringify(rest, null, 2);
+}