remnote-bridge 0.1.0

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

@@ -0,0 +1,133 @@
+/**
+ * EditHandler — edit-rem 命令的编排器
+ *
+ * 在 daemon 层实现三道防线 + str_replace + 后处理校验。
+ * Plugin 只负责原子写入（write_rem_fields）。
+ *
+ * 防线 1：缓存存在性检查（必须先 read 再 edit）
+ * 防线 2：乐观并发检测（当前 JSON 与缓存 JSON 比较）
+ * 防线 3：str_replace 精确匹配（old_str 必须唯一匹配）
+ */
+/** 只读字段集合 — 变更这些字段只产生警告，不执行写入 */
+const READ_ONLY_FIELDS = new Set([
+    'id',
+    'children',
+    'isTable',
+    'portalType', 'portalDirectlyIncludedRem',
+    'propertyType',
+    'aliases',
+    'remsBeingReferenced', 'deepRemsBeingReferenced', 'remsReferencingThis',
+    'taggedRem', 'ancestorTagRem', 'descendantTagRem',
+    'descendants', 'siblingRem',
+    'portalsAndDocumentsIn', 'allRemInDocumentOrPortal', 'allRemInFolderQueue',
+    'timesSelectedInSearch', 'lastTimeMovedTo', 'schemaVersion',
+    'embeddedQueueViewMode',
+    'createdAt', 'updatedAt', 'localUpdatedAt', 'lastPracticed',
+    'isPowerup', 'isPowerupEnum', 'isPowerupProperty',
+    'isPowerupPropertyListItem', 'isPowerupSlot',
+]);
+export class EditHandler {
+    cache;
+    forwardToPlugin;
+    constructor(cache, forwardToPlugin) {
+        this.cache = cache;
+        this.forwardToPlugin = forwardToPlugin;
+    }
+    async handleEditRem(payload) {
+        const { remId, oldStr, newStr } = payload;
+        // ── 防线 1: 缓存存在性检查 ──
+        const cachedJson = this.cache.get('rem:' + remId);
+        if (!cachedJson) {
+            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);
+        if (currentJson !== cachedJson) {
+            // 不更新缓存 — 迫使 AI re-read
+            throw new Error(`Rem ${remId} has been modified since last read. Please read it again before editing.`);
+        }
+        // ── 防线 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.');
+        }
+        const original = JSON.parse(cachedJson);
+        // 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];
+                }
+            }
+        }
+        // 3. 语义一致性校验
+        if ('todoStatus' in changes && changes.todoStatus !== null) {
+            const isTodo = modified.isTodo ?? original.isTodo;
+            if (!isTodo) {
+                warnings.push("Setting 'todoStatus' without 'isTodo: true' may have no effect");
+            }
+        }
+        // 4. 空变更检查
+        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) {
+            // 部分失败 — 不更新缓存（迫使 AI re-read）
+            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,
+        };
+    }
+}
+/** 统计 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/globe-read-handler.d.ts

@@ -0,0 +1,17 @@
+/**
+ * GlobeReadHandler — read-globe 请求的业务编排
+ *
+ * 职责：转发到 Plugin 获取知识库概览，返回结果。
+ * globe 是低频操作，不做缓存。
+ */
+import type { DefaultsConfig } from '../config.js';
+export interface GlobeReadResult {
+    nodeCount: number;
+    outline: string;
+}
+export declare class GlobeReadHandler {
+    private forwardToPlugin;
+    private defaults;
+    constructor(forwardToPlugin: (action: string, payload: Record<string, unknown>) => Promise<unknown>, defaults?: DefaultsConfig);
+    handleReadGlobe(payload: Record<string, unknown>): Promise<GlobeReadResult>;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * GlobeReadHandler — read-globe 请求的业务编排
+ *
+ * 职责：转发到 Plugin 获取知识库概览，返回结果。
+ * globe 是低频操作，不做缓存。
+ */
+import { DEFAULT_DEFAULTS } from '../config.js';
+export class GlobeReadHandler {
+    forwardToPlugin;
+    defaults;
+    constructor(forwardToPlugin, defaults) {
+        this.forwardToPlugin = forwardToPlugin;
+        this.defaults = defaults ?? DEFAULT_DEFAULTS;
+    }
+    async handleReadGlobe(payload) {
+        const depth = payload.depth ?? this.defaults.readGlobeDepth;
+        const maxNodes = payload.maxNodes ?? this.defaults.maxNodes;
+        const maxSiblings = payload.maxSiblings ?? this.defaults.maxSiblings;
+        return await this.forwardToPlugin('read_globe', {
+            depth, maxNodes, maxSiblings,
+        });
+    }
+}

package/dist/cli/handlers/read-handler.d.ts

@@ -0,0 +1,16 @@
+/**
+ * ReadHandler — read-rem 请求的业务编排
+ *
+ * 职责：
+ * 1. 转发到 Plugin 获取完整 RemObject
+ * 2. 序列化为 JSON 字符串并缓存（完整版本）
+ * 3. 根据 fields/full 参数过滤字段返回给 CLI
+ */
+import { RemCache } from './rem-cache.js';
+export declare class ReadHandler {
+    private cache;
+    private forwardToPlugin;
+    private onLog?;
+    constructor(cache: RemCache, forwardToPlugin: (action: string, payload: Record<string, unknown>) => Promise<unknown>, onLog?: ((message: string, level: "info" | "warn" | "error") => void) | undefined);
+    handleReadRem(payload: Record<string, unknown>): Promise<unknown>;
+}

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

@@ -0,0 +1,78 @@
+/**
+ * ReadHandler — read-rem 请求的业务编排
+ *
+ * 职责：
+ * 1. 转发到 Plugin 获取完整 RemObject
+ * 2. 序列化为 JSON 字符串并缓存（完整版本）
+ * 3. 根据 fields/full 参数过滤字段返回给 CLI
+ */
+/** R-F 字段（仅 --full 模式输出，默认不输出） */
+const RF_FIELDS = new Set([
+    'isPowerup', 'isPowerupEnum', 'isPowerupProperty',
+    'isPowerupPropertyListItem', 'isPowerupSlot',
+    'deepRemsBeingReferenced',
+    'ancestorTagRem', 'descendantTagRem',
+    'portalsAndDocumentsIn', 'allRemInDocumentOrPortal', 'allRemInFolderQueue',
+    'timesSelectedInSearch', 'lastTimeMovedTo', 'schemaVersion',
+    'embeddedQueueViewMode',
+    'localUpdatedAt', 'lastPracticed',
+]);
+export class ReadHandler {
+    cache;
+    forwardToPlugin;
+    onLog;
+    constructor(cache, forwardToPlugin, onLog) {
+        this.cache = cache;
+        this.forwardToPlugin = forwardToPlugin;
+        this.onLog = onLog;
+    }
+    async handleReadRem(payload) {
+        const remId = payload.remId;
+        if (!remId) {
+            throw new Error('缺少 remId 参数');
+        }
+        // 检查旧缓存
+        const cacheKey = 'rem:' + remId;
+        const previousCachedAt = this.cache.getCreatedAt(cacheKey);
+        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');
+        // 字段过滤
+        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 {
+            // 默认模式：排除 R-F 字段
+            const obj = remObject;
+            result = {};
+            for (const [key, value] of Object.entries(obj)) {
+                if (!RF_FIELDS.has(key)) {
+                    result[key] = value;
+                }
+            }
+        }
+        // 附加缓存覆盖提示
+        if (previousCachedAt) {
+            result._cacheOverridden = { id: remId, previousCachedAt };
+        }
+        return result;
+    }
+}

package/dist/cli/handlers/rem-cache.d.ts

@@ -0,0 +1,19 @@
+/**
+ * RemCache — LRU 缓存，存储 Rem 的序列化 JSON
+ *
+ * 缓存存储在 daemon 内存中，生命周期与 daemon 一致。
+ * disconnect 关闭 daemon → 缓存自然消失。
+ */
+export declare class RemCache {
+    private cache;
+    private maxSize;
+    constructor(maxSize?: number);
+    get(remId: string): string | null;
+    /** 获取缓存条目的创建时间（ISO 8601），不存在返回 null */
+    getCreatedAt(remId: string): string | null;
+    set(remId: string, json: string): void;
+    has(remId: string): boolean;
+    delete(remId: string): void;
+    clear(): void;
+    get size(): number;
+}

package/dist/cli/handlers/rem-cache.js

@@ -0,0 +1,63 @@
+/**
+ * RemCache — LRU 缓存，存储 Rem 的序列化 JSON
+ *
+ * 缓存存储在 daemon 内存中，生命周期与 daemon 一致。
+ * disconnect 关闭 daemon → 缓存自然消失。
+ */
+export class RemCache {
+    cache = new Map();
+    maxSize;
+    constructor(maxSize = 200) {
+        this.maxSize = maxSize;
+    }
+    get(remId) {
+        const entry = this.cache.get(remId);
+        if (!entry)
+            return null;
+        entry.lastAccess = Date.now();
+        return entry.json;
+    }
+    /** 获取缓存条目的创建时间（ISO 8601），不存在返回 null */
+    getCreatedAt(remId) {
+        const entry = this.cache.get(remId);
+        return entry ? entry.createdAt : null;
+    }
+    set(remId, json) {
+        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.lastAccess = now;
+            entry.createdAt = createdAt;
+            return;
+        }
+        // LRU 淘汰
+        if (this.cache.size >= this.maxSize) {
+            let oldestId = null;
+            let oldestTime = Infinity;
+            for (const [id, entry] of this.cache) {
+                if (entry.lastAccess < oldestTime) {
+                    oldestTime = entry.lastAccess;
+                    oldestId = id;
+                }
+            }
+            if (oldestId) {
+                this.cache.delete(oldestId);
+            }
+        }
+        this.cache.set(remId, { json, lastAccess: now, createdAt });
+    }
+    has(remId) {
+        return this.cache.has(remId);
+    }
+    delete(remId) {
+        this.cache.delete(remId);
+    }
+    clear() {
+        this.cache.clear();
+    }
+    get size() {
+        return this.cache.size;
+    }
+}

package/dist/cli/handlers/tree-edit-handler.d.ts

@@ -0,0 +1,30 @@
+/**
+ * TreeEditHandler — edit-tree 请求的业务编排
+ *
+ * 职责：
+ * 1. 三道防线（缓存存在、变更检测、str_replace 精确匹配）
+ * 2. 解析新旧大纲并 diff
+ * 3. 逐项执行操作（通过 forwardToPlugin 调用原子操作）
+ * 4. 成功后重新 read-tree 更新缓存
+ */
+import type { DefaultsConfig } from '../config.js';
+import { RemCache } from './rem-cache.js';
+import { type TreeOp } from './tree-parser.js';
+export interface TreeEditPayload {
+    remId: string;
+    oldStr: string;
+    newStr: string;
+}
+export interface TreeEditResult {
+    ok: boolean;
+    operations: TreeOp[];
+    error?: string;
+    details?: Record<string, unknown>;
+}
+export declare class TreeEditHandler {
+    private cache;
+    private forwardToPlugin;
+    private defaults;
+    constructor(cache: RemCache, forwardToPlugin: (action: string, payload: Record<string, unknown>) => Promise<unknown>, defaults?: DefaultsConfig);
+    handleEditTree(payload: TreeEditPayload): Promise<TreeEditResult>;
+}

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

@@ -0,0 +1,188 @@
+/**
+ * TreeEditHandler — edit-tree 请求的业务编排
+ *
+ * 职责：
+ * 1. 三道防线（缓存存在、变更检测、str_replace 精确匹配）
+ * 2. 解析新旧大纲并 diff
+ * 3. 逐项执行操作（通过 forwardToPlugin 调用原子操作）
+ * 4. 成功后重新 read-tree 更新缓存
+ */
+import { DEFAULT_DEFAULTS } from '../config.js';
+import { parseOutline, diffTrees, parsePowerupPrefix } from './tree-parser.js';
+export class TreeEditHandler {
+    cache;
+    forwardToPlugin;
+    defaults;
+    constructor(cache, forwardToPlugin, defaults) {
+        this.cache = cache;
+        this.forwardToPlugin = forwardToPlugin;
+        this.defaults = defaults ?? DEFAULT_DEFAULTS;
+    }
+    async handleEditTree(payload) {
+        const { remId, oldStr, newStr } = payload;
+        // ── noop 检查 ──
+        if (oldStr === newStr) {
+            return { ok: true, operations: [] };
+        }
+        // ── 防线 1: 缓存存在性检查 ──
+        const cachedOutline = this.cache.get('tree:' + remId);
+        if (!cachedOutline) {
+            throw new Error(`Tree rooted at ${remId} has not been read yet. Use read-tree first.`);
+        }
+        // ── 防线 2: 乐观并发检测 ──
+        // 用与 read-tree 相同的参数重新获取最新大纲
+        const cachedDepthStr = this.cache.get('tree-depth:' + remId);
+        const cachedMaxNodesStr = this.cache.get('tree-maxNodes:' + remId);
+        const cachedMaxSiblingsStr = this.cache.get('tree-maxSiblings:' + remId);
+        const depth = cachedDepthStr ? Number(cachedDepthStr) : this.defaults.readTreeDepth;
+        const maxNodes = cachedMaxNodesStr ? Number(cachedMaxNodesStr) : this.defaults.maxNodes;
+        const maxSiblings = cachedMaxSiblingsStr ? Number(cachedMaxSiblingsStr) : this.defaults.maxSiblings;
+        const freshResult = await this.forwardToPlugin('read_tree', { remId, depth, maxNodes, maxSiblings });
+        if (freshResult.outline !== cachedOutline) {
+            // 不更新缓存 — 迫使 AI re-read
+            throw new Error(`Tree rooted at ${remId} has been modified since last read-tree. Please read-tree again.`);
+        }
+        // ── 防线 3: str_replace 精确匹配 ──
+        const matchCount = countOccurrences(cachedOutline, oldStr);
+        if (matchCount === 0) {
+            throw new Error(`old_str not found in the tree outline of ${remId}`);
+        }
+        if (matchCount > 1) {
+            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 oldTree = parseOutline(cachedOutline);
+        const newTree = parseOutline(modifiedOutline);
+        // ── diff ──
+        const diffResult = diffTrees(oldTree, newTree);
+        // 检查是否是错误
+        if ('type' in diffResult) {
+            const err = diffResult;
+            return {
+                ok: false,
+                operations: [],
+                error: err.message,
+                details: err.details,
+            };
+        }
+        const { operations } = diffResult;
+        // 空操作（结构无变化，可能只是元数据变化被 D9 忽略了）
+        if (operations.length === 0) {
+            return { ok: true, operations: [] };
+        }
+        // ── 执行操作（D4 操作顺序已在 diffTrees 中排好）──
+        // newRemIdMap: 映射新增行的占位 ID → 实际创建的 remId
+        const newRemIdMap = new Map();
+        for (let i = 0; i < operations.length; i++) {
+            const op = operations[i];
+            switch (op.type) {
+                case 'create': {
+                    // 解析父节点 ID（可能是占位标记 __new_N__）
+                    let parentId = op.parentId;
+                    const placeholderMatch = parentId.match(/^__new_(\d+)__$/);
+                    if (placeholderMatch) {
+                        const refIndex = parseInt(placeholderMatch[1], 10);
+                        const actualId = newRemIdMap.get(refIndex);
+                        if (!actualId) {
+                            throw new Error(`内部错误：新增行的父节点（占位 ${refIndex}）尚未创建`);
+                        }
+                        parentId = actualId;
+                    }
+                    // 解析 Markdown 前缀 + 箭头分隔符 → 属性
+                    const { cleanContent, powerups, backText, practiceDirection } = parsePowerupPrefix(op.content);
+                    const createResult = await this.forwardToPlugin('create_rem', {
+                        content: cleanContent,
+                        parentId,
+                        position: op.position,
+                    });
+                    // 合并所有需要写入的属性（Powerup + 箭头分隔符推导的字段）
+                    const changes = { ...powerups };
+                    if (backText !== undefined)
+                        changes.backText = backText;
+                    if (practiceDirection !== undefined)
+                        changes.practiceDirection = practiceDirection;
+                    // 父节点为 multiline 时，子行标记 isCardItem
+                    // ⚠ SDK bug: setIsCardItem(true) 会偷偷设 practiceDirection: "forward"
+                    // 但 practiceDirection 应该只存在于父行（问题行），card-item（答案行）上不应该有。
+                    // 如果 card-item 带着 practiceDirection: "forward" 且有子行，会被 RemNote 错误渲染成 multiline 卡片。
+                    // 对策：setIsCardItem(true) 后立即用 practiceDirection: 'none' 覆盖掉副作用。
+                    if (op.parentIsMultiline) {
+                        changes.isCardItem = true;
+                        if (!changes.practiceDirection)
+                            changes.practiceDirection = 'none';
+                    }
+                    if (Object.keys(changes).length > 0) {
+                        await this.forwardToPlugin('write_rem_fields', {
+                            remId: createResult.remId,
+                            changes,
+                        });
+                    }
+                    // 记录新创建的 remId，供后续嵌套引用
+                    newRemIdMap.set(i, createResult.remId);
+                    break;
+                }
+                case 'delete': {
+                    await this.forwardToPlugin('delete_rem', { remId: op.remId });
+                    break;
+                }
+                case 'move': {
+                    await this.forwardToPlugin('move_rem', {
+                        remId: op.remId,
+                        newParentId: op.toParentId,
+                        position: op.position,
+                    });
+                    // 同步 isCardItem：移入 multiline 父节点 → true，移出 → false
+                    if (op.toParentIsMultiline && !op.fromParentIsMultiline) {
+                        // ⚠ SDK bug: setIsCardItem(true) 会偷设 practiceDirection: "forward"
+                        // 对策：覆盖为 'none'，但如果 Rem 自身有合法的 practiceDirection（如 ↔ 闪卡）则保留
+                        const changes = { isCardItem: true };
+                        if (!op.selfHasPracticeDirection)
+                            changes.practiceDirection = 'none';
+                        await this.forwardToPlugin('write_rem_fields', {
+                            remId: op.remId,
+                            changes,
+                        });
+                    }
+                    else if (!op.toParentIsMultiline && op.fromParentIsMultiline) {
+                        // ⚠ SDK bug: setIsCardItem(false) 不会清 practiceDirection（不对称行为）
+                        // 移出时清掉 SDK 副作用残留，但如果 Rem 自身有合法的 practiceDirection 则保留
+                        const changes = { isCardItem: false };
+                        if (!op.selfHasPracticeDirection)
+                            changes.practiceDirection = 'none';
+                        await this.forwardToPlugin('write_rem_fields', {
+                            remId: op.remId,
+                            changes,
+                        });
+                    }
+                    break;
+                }
+                case 'reorder': {
+                    await this.forwardToPlugin('reorder_children', {
+                        parentId: op.parentId,
+                        order: op.order,
+                    });
+                    break;
+                }
+            }
+        }
+        // ── D3: 成功后更新缓存（使用相同参数）──
+        const updatedResult = await this.forwardToPlugin('read_tree', { remId, depth, maxNodes, maxSiblings });
+        this.cache.set('tree:' + remId, updatedResult.outline);
+        return { ok: true, operations };
+    }
+}
+/** 统计 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;
+    }
+    return count;
+}

package/dist/cli/handlers/tree-parser.d.ts

@@ -0,0 +1,95 @@
+/**
+ * tree-parser.ts — 大纲解析 + diff 算法
+ *
+ * CLI handlers 层的纯函数。解析 Markdown 大纲文本为树结构，
+ * 对比新旧两棵树生成增量操作列表。
+ *
+ * 不依赖 server / commands / daemon（强约束）。
+ */
+/** 大纲中解析出的节点 */
+export interface OutlineNode {
+    /** Rem ID，null = 新增行 */
+    remId: string | null;
+    /** 缩进级别（0 = 根节点） */
+    depth: number;
+    /** 去除缩进和行尾标记后的纯内容 */
+    rawContent: string;
+    /** 原始行文本 */
+    rawLine: string;
+    /** 子节点 */
+    children: OutlineNode[];
+    /** 是否为省略占位符行 */
+    isElided?: boolean;
+}
+/** diff 操作类型 */
+export type TreeOp = {
+    type: 'create';
+    content: string;
+    parentId: string;
+    position: number;
+    parentIsMultiline?: boolean;
+} | {
+    type: 'delete';
+    remId: string;
+} | {
+    type: 'move';
+    remId: string;
+    fromParentId: string;
+    toParentId: string;
+    position: number;
+    fromParentIsMultiline?: boolean;
+    toParentIsMultiline?: boolean;
+    selfHasPracticeDirection?: boolean;
+} | {
+    type: 'reorder';
+    parentId: string;
+    order: string[];
+};
+export interface TreeDiffResult {
+    operations: TreeOp[];
+}
+export interface TreeDiffError {
+    type: 'content_modified' | 'orphan_detected' | 'folded_delete' | 'root_modified' | 'indent_skip' | 'elided_modified';
+    message: string;
+    details: Record<string, unknown>;
+}
+/**
+ * 解析 Markdown 大纲文本为树结构。
+ *
+ * 使用栈追踪当前路径，根据缩进级别确定父子关系。
+ */
+export declare function parseOutline(text: string): OutlineNode[];
+export interface PowerupPrefixResult {
+    cleanContent: string;
+    powerups: Record<string, unknown>;
+    /** 箭头分隔符后的 backText（有 backText 时） */
+    backText?: string;
+    /** 箭头分隔符推导的 practiceDirection */
+    practiceDirection?: string;
+    /** 是否为 multiline（↓ ↑ ↕） */
+    isMultiline?: boolean;
+}
+/**
+ * 从新增行的 rawContent 中解析 Markdown 前缀和箭头分隔符，提取属性。
+ *
+ * 解析顺序与 read-tree 输出的嵌套顺序对称：Header → Todo → Code → 箭头分隔符。
+ *
+ * 箭头分隔符（v2 格式）：
+ *   中间箭头（有 backText）：` → ` ` ← ` ` ↔ ` ` ↓ ` ` ↑ ` ` ↕ `
+ *   尾部箭头（无 backText，multiline）：` ↓` ` ↑` ` ↕`
+ *
+ * ⚠️ 已知限制：使用 indexOf 匹配第一个箭头，如果用户新增行的内容本身包含
+ *   箭头字符（如 `A → B → C`），会被误切割为 text + backText。
+ *   对于 read→edit 往返的已有行不受影响（序列化/反序列化对称）。
+ */
+export declare function parsePowerupPrefix(rawContent: string): PowerupPrefixResult;
+/** 从行内容判断是否为 multiline 父节点（内容包含 ↓↑↕ 箭头） */
+export declare function isContentMultiline(rawContent: string): boolean;
+/**
+ * 对比新旧大纲树，生成操作列表或报错。
+ *
+ * @param oldRoots 旧大纲解析结果
+ * @param newRoots 新大纲解析结果（str_replace 后）
+ * @returns 操作列表或错误
+ */
+export declare function diffTrees(oldRoots: OutlineNode[], newRoots: OutlineNode[]): TreeDiffResult | TreeDiffError;