remnote-bridge 0.1.12 → 0.1.14

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

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

package/dist/cli/handlers/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;
@@ -44,48 +27,13 @@ export class ReadHandler {
         const includePowerup = payload.includePowerup ?? false;
         // 转发到 Plugin
         const remObject = await this.forwardToPlugin('read_rem', { remId, includePowerup });
-        // 缓存完整 JSON
-        const fullJson = JSON.stringify(remObject, null, 2);
-        this.cache.set(cacheKey, fullJson);
-        this.onLog?.(`缓存 Rem ${remId.slice(0, 8)}... (${fullJson.length} bytes)`, 'info');
+        // 缓存完整 RemObject 对象
+        this.cache.set(cacheKey, remObject);
+        this.onLog?.(`缓存 Rem ${remId.slice(0, 8)}...`, 'info');
         // 字段过滤
         const fields = payload.fields;
         const full = payload.full;
-        let result;
-        if (full) {
-            // --full → 返回完整对象（含 R-F 字段）
-            result = remObject;
-        }
-        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 };