remnote-bridge 0.1.13 → 0.1.15

package/dist/cli/handlers/patch-engine.js

@@ -0,0 +1,347 @@
+/**
+ * patch-engine.ts -- patch 解析器 + 应用器
+ *
+ * CLI handlers 层的纯函数。解析自定义 patch DSL 文本为结构化 hunk 列表，
+ * 供后续应用器匹配到缓存大纲并生成新大纲。
+ *
+ * 不依赖 server / commands / daemon（强约束）。
+ */
+/** 解析错误 */
+export class PatchParseError extends Error {
+    lineNumber;
+    rawLine;
+    constructor(message, lineNumber, rawLine) {
+        super(`Patch 解析错误 (行 ${lineNumber}): ${message}\n  > ${rawLine}`);
+        this.lineNumber = lineNumber;
+        this.rawLine = rawLine;
+        this.name = 'PatchParseError';
+    }
+}
+// ────────────────────────── 应用器错误类型 ──────────────────────────
+/** patch 应用错误（锚点不存在、缩进不匹配等） */
+export class PatchApplyError extends Error {
+    lineNumber;
+    constructor(message, lineNumber) {
+        super(`Patch 应用错误 (行 ${lineNumber}): ${message}`);
+        this.lineNumber = lineNumber;
+        this.name = 'PatchApplyError';
+    }
+}
+/** hunk 间 ID 引用冲突错误 */
+export class PatchConflictError extends Error {
+    conflictId;
+    constructor(message, conflictId) {
+        super(message);
+        this.conflictId = conflictId;
+        this.name = 'PatchConflictError';
+    }
+}
+// ────────────────────────── 应用器内部函数 ──────────────────────────
+/** 行尾标记正则（与 tree-parser.ts 的 LINE_MARKER_RE 一致） */
+const OUTLINE_LINE_MARKER_RE = /<!--(\S+)(?:\s+\S+)*-->$/;
+/**
+ * 预扫描缓存大纲，构建 Rem ID → 行索引的映射。
+ * 使用与 tree-parser.ts 一致的行尾标记正则提取 ID。
+ */
+function buildIdIndex(lines) {
+    const map = new Map();
+    for (let i = 0; i < lines.length; i++) {
+        const trimmed = lines[i].replace(/^ */, '');
+        const match = trimmed.match(OUTLINE_LINE_MARKER_RE);
+        if (match) {
+            map.set(match[1], i);
+        }
+    }
+    return map;
+}
+/**
+ * 计算缓存大纲行的缩进深度。
+ * 与 tree-parser.ts 的 parseLine 和解析器的 calcDepth 保持一致。
+ */
+function outlineLineDepth(line) {
+    const stripped = line.replace(/^ */, '');
+    const indentChars = line.length - stripped.length;
+    return Math.floor(indentChars / 2);
+}
+/**
+ * 预扫描所有 hunk，检测跨 hunk 的 ID 引用冲突。
+ *
+ * 规则：如果一个 hunk 删除了某 ID，而另一个 hunk 将该 ID 用作上下文锚点，
+ * 则存在冲突（同一 hunk 内允许先锚点后删除或先删除后锚点）。
+ */
+function validateCrossHunkConflicts(hunks) {
+    // 收集每个 hunk 的删除 ID 集合
+    const deletionsByHunk = new Map();
+    const allDeletedIds = new Set();
+    for (let h = 0; h < hunks.length; h++) {
+        const hunkDeleted = new Set();
+        for (const line of hunks[h].lines) {
+            if (line.type === 'deletion' && line.remId) {
+                hunkDeleted.add(line.remId);
+                allDeletedIds.add(line.remId);
+            }
+        }
+        deletionsByHunk.set(h, hunkDeleted);
+    }
+    // 检查每个 hunk 的锚点 ID 是否被其他 hunk 删除
+    for (let h = 0; h < hunks.length; h++) {
+        for (const line of hunks[h].lines) {
+            if (line.type === 'context' && line.remId) {
+                if (allDeletedIds.has(line.remId)) {
+                    // 检查删除和锚点是否在同一个 hunk
+                    const isDeletedInSameHunk = deletionsByHunk.get(h).has(line.remId);
+                    if (!isDeletedInSameHunk) {
+                        throw new PatchConflictError(`Hunk 间冲突：Rem ID "${line.remId}" 被一个 hunk 删除，` +
+                            `但在另一个 hunk（行 ${line.lineNumber}）中被用作锚点`, line.remId);
+                    }
+                }
+            }
+        }
+    }
+}
+/**
+ * 将单个 hunk 的操作标记到 deleted 和 insertions 中。
+ *
+ * 遍历 hunk 的每一行：
+ * - context：通过 ID 索引定位 + 缩进校验，更新 lastMatchedIndex
+ * - deletion：通过 ID 索引定位 + 缩进校验，标记删除，更新 lastMatchedIndex
+ * - addition：追加到 lastMatchedIndex 的插入列表
+ */
+function applyHunk(hunk, outlineLines, idIndex, deleted, insertions) {
+    let lastMatchedIndex = -1;
+    for (const patchLine of hunk.lines) {
+        if (patchLine.type === 'context') {
+            const idx = idIndex.get(patchLine.remId);
+            if (idx === undefined) {
+                throw new PatchApplyError(`锚点 <!--${patchLine.remId}--> 在缓存大纲中不存在`, patchLine.lineNumber);
+            }
+            // 校验缩进
+            const actualDepth = outlineLineDepth(outlineLines[idx]);
+            if (actualDepth !== patchLine.depth) {
+                throw new PatchApplyError(`锚点 <!--${patchLine.remId}--> 缩进不匹配：` +
+                    `缓存大纲中 depth=${actualDepth}，patch 中 depth=${patchLine.depth}`, patchLine.lineNumber);
+            }
+            lastMatchedIndex = idx;
+        }
+        else if (patchLine.type === 'deletion') {
+            const idx = idIndex.get(patchLine.remId);
+            if (idx === undefined) {
+                throw new PatchApplyError(`要删除的 <!--${patchLine.remId}--> 在缓存大纲中不存在`, patchLine.lineNumber);
+            }
+            // 校验缩进
+            const actualDepth = outlineLineDepth(outlineLines[idx]);
+            if (actualDepth !== patchLine.depth) {
+                throw new PatchApplyError(`要删除的 <!--${patchLine.remId}--> 缩进不匹配：` +
+                    `缓存大纲中 depth=${actualDepth}，patch 中 depth=${patchLine.depth}`, patchLine.lineNumber);
+            }
+            deleted.add(idx);
+            lastMatchedIndex = idx;
+        }
+        else if (patchLine.type === 'addition') {
+            // 新增行插入在 lastMatchedIndex 之后
+            if (!insertions.has(lastMatchedIndex)) {
+                insertions.set(lastMatchedIndex, []);
+            }
+            // patchLine.content 已是完整的大纲行（含缩进），直接使用
+            insertions.get(lastMatchedIndex).push(patchLine.content);
+        }
+    }
+}
+/**
+ * 一次性重建新大纲字符串。
+ *
+ * 遍历原始行，跳过被删除的行，在适当位置插入新行。
+ */
+function rebuild(lines, deleted, insertions) {
+    const result = [];
+    // 处理在第一行之前的插入（lastMatchedIndex = -1 时）
+    const prependLines = insertions.get(-1);
+    if (prependLines) {
+        result.push(...prependLines);
+    }
+    for (let i = 0; i < lines.length; i++) {
+        if (!deleted.has(i)) {
+            result.push(lines[i]);
+        }
+        // 在第 i 行之后插入新行（无论 i 是否被删除）
+        const toInsert = insertions.get(i);
+        if (toInsert) {
+            result.push(...toInsert);
+        }
+    }
+    return result.join('\n');
+}
+// ────────────────────────── 应用器 ──────────────────────────
+/**
+ * 将 patch 应用到缓存大纲，生成新大纲字符串。
+ *
+ * 策略：ID 索引 + 一次性标记-重建（mark-and-rebuild）。
+ * 1. 解析 patch 文本为结构化 hunk 列表
+ * 2. 预扫描缓存大纲构建 Rem ID → 行索引映射
+ * 3. 预检测 hunk 间 ID 引用冲突
+ * 4. 遍历 hunk，为每行标记操作（删除/插入）
+ * 5. 一次性重建新大纲字符串
+ *
+ * @param patchText patch 文本
+ * @param cachedOutline 缓存大纲字符串（read-tree 输出格式）
+ * @returns 新大纲字符串（可直接传入 parseOutline）
+ */
+export function applyPatch(patchText, cachedOutline) {
+    // 1. 解析 patch
+    const parsed = parsePatch(patchText);
+    // 2. 构建缓存大纲的行数组和 ID 索引
+    const lines = cachedOutline.split('\n');
+    const idIndex = buildIdIndex(lines);
+    // 3. 预检测 hunk 间冲突
+    validateCrossHunkConflicts(parsed.hunks);
+    // 4. 标记操作
+    const deleted = new Set();
+    const insertions = new Map();
+    for (const hunk of parsed.hunks) {
+        applyHunk(hunk, lines, idIndex, deleted, insertions);
+    }
+    // 5. 重建
+    return rebuild(lines, deleted, insertions);
+}
+// ────────────────────────── 正则常量 ──────────────────────────
+/** 合法锚点行：只包含缩进 + <!--remId--> */
+const ANCHOR_LINE_RE = /^( *)<!--(\S+)-->$/;
+/** 非法锚点行：包含内容文本 + <!--remId-->（用于报错提示） */
+const CONTENT_BEFORE_MARKER_RE = /^( *)\S.*<!--\S+-->$/;
+/** 从行文本中提取 Rem ID */
+const REM_ID_RE = /<!--(\S+)-->/;
+// ────────────────────────── 内部函数 ──────────────────────────
+/**
+ * 计算缩进深度：每 2 个空格一级（与 tree-parser.ts 的 parseLine 一致）。
+ */
+function calcDepth(text) {
+    const stripped = text.replace(/^ */, '');
+    const indentChars = text.length - stripped.length;
+    return Math.floor(indentChars / 2);
+}
+/**
+ * 解析 patch 文本中的单行。
+ *
+ * 行类型判定规则：
+ * - `+` 前缀 → addition（新增行）
+ * - `-` 前缀 → deletion（删除行，必须包含 Rem ID）
+ * - 无前缀 → context（锚点行，严格校验：只允许缩进 + Rem ID 注释）
+ */
+function parsePatchLine(rawLine, lineNumber) {
+    const trimmed = rawLine.trimEnd();
+    // +/- 前缀检测
+    if (trimmed.startsWith('+') || trimmed.startsWith('-')) {
+        const prefix = trimmed[0];
+        const rest = trimmed.slice(1); // 剥离前缀，保留完整缩进
+        const depth = calcDepth(rest);
+        if (prefix === '+') {
+            // 新增行：remId 为 null（不提取，交给下游 parseOutline 处理）
+            return {
+                type: 'addition',
+                depth,
+                remId: null,
+                content: rest,
+                rawLine,
+                lineNumber,
+            };
+        }
+        else {
+            // 删除行：必须包含 Rem ID
+            const stripped = rest.replace(/^ */, '');
+            const idMatch = stripped.match(REM_ID_RE);
+            if (!idMatch) {
+                throw new PatchParseError('删除行必须包含 Rem ID（格式：<!--remId-->），当前行缺少 ID', lineNumber, rawLine);
+            }
+            return {
+                type: 'deletion',
+                depth,
+                remId: idMatch[1],
+                content: '',
+                rawLine,
+                lineNumber,
+            };
+        }
+    }
+    // 上下文行（锚点行）
+    const anchorMatch = trimmed.match(ANCHOR_LINE_RE);
+    if (anchorMatch) {
+        const depth = Math.floor(anchorMatch[1].length / 2);
+        return {
+            type: 'context',
+            depth,
+            remId: anchorMatch[2],
+            content: '',
+            rawLine,
+            lineNumber,
+        };
+    }
+    // 检测包含内容文本的非法锚点行
+    if (CONTENT_BEFORE_MARKER_RE.test(trimmed)) {
+        throw new PatchParseError('上下文行只允许缩进 + Rem ID（如 "  <!--abc-->"），不得包含内容文本。' +
+            '请移除内容文本只保留 Rem ID。', lineNumber, rawLine);
+    }
+    // 无法识别的行格式
+    throw new PatchParseError('无法识别的行格式。期望格式：上下文行 "  <!--remId-->"、' +
+        '新增行 "+  内容" 或删除行 "-  <!--remId-->"', lineNumber, rawLine);
+}
+// ────────────────────────── 解析器 ──────────────────────────
+/**
+ * 解析 patch 文本为结构化的 ParsedPatch。
+ *
+ * - 按 `\n` 拆分行
+ * - 空行跳过但保留行号映射
+ * - `...` 行作为 hunk 分隔符
+ * - 每个非空行通过 parsePatchLine 解析为 PatchLine
+ */
+export function parsePatch(patchText) {
+    const rawLines = patchText.split('\n');
+    const hunks = [];
+    let currentLines = [];
+    let currentStartLine = -1;
+    let hasAnyContent = false;
+    for (let i = 0; i < rawLines.length; i++) {
+        const lineNumber = i + 1; // 1-based
+        const line = rawLines[i];
+        // 跳过空行（trim 后为空）
+        if (line.trim() === '') {
+            continue;
+        }
+        // hunk 分隔符
+        if (line.trim() === '...') {
+            // 关闭当前 hunk
+            if (currentLines.length > 0) {
+                hunks.push({ lines: currentLines, startLine: currentStartLine });
+                currentLines = [];
+                currentStartLine = -1;
+            }
+            else if (hasAnyContent) {
+                // 连续 ... 之间无内容 → 空 hunk
+                throw new PatchParseError('hunk 内容为空（连续的 ... 分隔符之间没有有效行）', lineNumber, line);
+            }
+            hasAnyContent = true;
+            continue;
+        }
+        // 解析行
+        const patchLine = parsePatchLine(line, lineNumber);
+        if (currentStartLine === -1) {
+            currentStartLine = lineNumber;
+        }
+        currentLines.push(patchLine);
+        hasAnyContent = true;
+    }
+    // 关闭最后一个 hunk
+    if (currentLines.length > 0) {
+        hunks.push({ lines: currentLines, startLine: currentStartLine });
+    }
+    // 校验：空 patch
+    if (hunks.length === 0) {
+        throw new PatchParseError('patch 为空，没有有效的 patch 行', 1, patchText.split('\n')[0] || '');
+    }
+    // 校验：任何 hunk 的 lines 为空不应发生（已在循环中处理），但做保底检查
+    for (const hunk of hunks) {
+        if (hunk.lines.length === 0) {
+            throw new PatchParseError('hunk 内容为空', hunk.startLine, '');
+        }
+    }
+    return { hunks };
+}

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

@@ -6,24 +6,7 @@
  * 2. 序列化为 JSON 字符串并缓存（完整版本）
  * 3. 根据 fields/full 参数过滤字段返回给 CLI
  */
-/** R-F 字段（仅 --full 模式输出，默认不输出） */
-const RF_FIELDS = new Set([
-    'children',
-    'isPowerup', 'isPowerupEnum', 'isPowerupProperty',
-    'isPowerupPropertyListItem', 'isPowerupSlot',
-    'deepRemsBeingReferenced',
-    'ancestorTagRem', 'descendantTagRem',
-    'portalsAndDocumentsIn', 'allRemInDocumentOrPortal', 'allRemInFolderQueue',
-    'timesSelectedInSearch', 'lastTimeMovedTo', 'schemaVersion',
-    'embeddedQueueViewMode',
-    'localUpdatedAt', 'lastPracticed',
-]);
-/** Portal 简化输出字段（type === 'portal' 时默认输出这 8 个字段） */
-export const PORTAL_FIELDS = [
-    'id', 'type', 'portalType', 'portalDirectlyIncludedRem',
-    'parent', 'positionAmongstSiblings',
-    'createdAt', 'updatedAt',
-];
+import { filterRemFields } from './rem-field-filter.js';
 export class ReadHandler {
     cache;
     forwardToPlugin;
@@ -50,41 +33,7 @@ export class ReadHandler {
         // 字段过滤
         const fields = payload.fields;
         const full = payload.full;
-        let result;
-        if (full) {
-            // --full → 返回完整对象（含 R-F 字段）。浅拷贝避免污染缓存对象。
-            result = { ...remObject };
-        }
-        else if (fields) {
-            // --fields 过滤：只返回指定字段 + id
-            const obj = remObject;
-            result = { id: obj.id };
-            for (const field of fields) {
-                if (field in obj) {
-                    result[field] = obj[field];
-                }
-            }
-        }
-        else if (remObject.type === 'portal') {
-            // Portal 简化模式：只输出 8 个关键字段
-            const obj = remObject;
-            result = {};
-            for (const field of PORTAL_FIELDS) {
-                if (field in obj) {
-                    result[field] = obj[field];
-                }
-            }
-        }
-        else {
-            // 默认模式：排除 R-F 字段
-            const obj = remObject;
-            result = {};
-            for (const [key, value] of Object.entries(obj)) {
-                if (!RF_FIELDS.has(key)) {
-                    result[key] = value;
-                }
-            }
-        }
+        let result = filterRemFields(remObject, { full, fields });
         // 附加缓存覆盖提示
         if (previousCachedAt) {
             result._cacheOverridden = { id: remId, previousCachedAt };

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));