remnote-bridge 0.1.6 → 0.1.7

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

@@ -7,13 +7,17 @@
  * 防线 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',
     'children',
     'isTable',
-    'portalType', 'portalDirectlyIncludedRem',
+    'portalType',
     'propertyType',
     'aliases',
     'remsBeingReferenced', 'deepRemsBeingReferenced', 'remsReferencingThis',
@@ -26,6 +30,10 @@ 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',
+]);
 export class EditHandler {
     cache;
     forwardToPlugin;
@@ -47,6 +55,86 @@ export class EditHandler {
             // 不更新缓存 — 迫使 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 = {};
+        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];
+                }
+            }
+        }
+        // 空变更检查
+        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) {
@@ -57,7 +145,6 @@ export class EditHandler {
                 `Make old_str more specific to match exactly once.`);
         }
         const modifiedJson = cachedJson.replace(oldStr, newStr);
-        // ── 后处理校验 ──
         // 1. JSON 解析
         let modified;
         try {
@@ -66,7 +153,6 @@ export class EditHandler {
         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 = [];

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

@@ -17,6 +17,12 @@ const RF_FIELDS = new Set([
     'embeddedQueueViewMode',
     'localUpdatedAt', 'lastPracticed',
 ]);
+/** Portal 简化输出字段（type === 'portal' 时默认输出这 9 个字段） */
+export const PORTAL_FIELDS = [
+    'id', 'type', 'portalType', 'portalDirectlyIncludedRem',
+    'parent', 'positionAmongstSiblings', 'children',
+    'createdAt', 'updatedAt',
+];
 export class ReadHandler {
     cache;
     forwardToPlugin;
@@ -59,6 +65,16 @@ export class ReadHandler {
                 }
             }
         }
+        else if (remObject.type === 'portal') {
+            // Portal 简化模式：只输出 9 个关键字段
+            const obj = remObject;
+            result = {};
+            for (const field of PORTAL_FIELDS) {
+                if (field in obj) {
+                    result[field] = obj[field];
+                }
+            }
+        }
         else {
             // 默认模式：排除 R-F 字段
             const obj = remObject;

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

@@ -90,37 +90,68 @@ export class TreeEditHandler {
                         }
                         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 (op.isPortal) {
+                        // ── Portal 创建路径 ──
+                        // 1. 创建空 Portal 并设置父节点
+                        const portalResult = await this.forwardToPlugin('create_portal', {
+                            parentId,
+                            position: op.position,
+                        });
+                        // 2. 逐个添加引用
+                        if (op.portalRefs?.length) {
+                            for (const refId of op.portalRefs) {
+                                await this.forwardToPlugin('add_to_portal', {
+                                    portalId: portalResult.remId,
+                                    remId: refId,
+                                });
+                            }
+                        }
+                        // 记录新创建的 remId，供后续嵌套引用
+                        newRemIdMap.set(i, portalResult.remId);
                     }
-                    if (Object.keys(changes).length > 0) {
-                        await this.forwardToPlugin('write_rem_fields', {
-                            remId: createResult.remId,
-                            changes,
+                    else {
+                        // ── 普通 Rem 创建路径 ──
+                        // 解析 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' 覆盖掉副作用。
+                        // 合并 HTML 注释中的元数据（type、doc、tag）
+                        if (op.metadata) {
+                            if (op.metadata.type)
+                                changes.type = op.metadata.type;
+                            if (op.metadata.isDocument)
+                                changes.isDocument = op.metadata.isDocument;
+                            if (op.metadata.tags)
+                                changes.tags = op.metadata.tags;
+                        }
+                        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);
                     }
-                    // 记录新创建的 remId，供后续嵌套引用
-                    newRemIdMap.set(i, createResult.remId);
                     break;
                 }
                 case 'delete': {

package/dist/cli/handlers/tree-parser.js

@@ -14,7 +14,11 @@
 const LINE_MARKER_RE = /<!--(\S+)((?:\s+\S+)*)-->$/;
 /** 省略占位符正则 */
 const ELIDED_LINE_RE = /^<!--\.\.\.elided\s/;
-/** 解析单行，提取缩进、内容、remId */
+/** 纯元数据注释正则（不含 remId，仅匹配 type:xxx、doc、tag:xxx） */
+const METADATA_ONLY_RE = /<!--((?:type:\S+|doc|tag:\S+)(?:\s+(?:type:\S+|doc|tag:\S+))*)-->$/;
+/** Portal 新增行正则：<!--portal refs:id1,id2--> 或 <!--portal--> */
+const NEW_PORTAL_RE = /^<!--portal(?:\s+refs:(\S+))?-->$/;
+/** 解析单行，提取缩进、内容、remId，以及 Portal 新增行标记 */
 function parseLine(line) {
     // 计算缩进（每 2 空格一级）
     const stripped = line.replace(/^ */, '');
@@ -24,7 +28,21 @@ function parseLine(line) {
     if (ELIDED_LINE_RE.test(stripped)) {
         return { depth, rawContent: stripped, remId: null, metadata: '', isElided: true };
     }
-    // 匹配行尾标记
+    // 检测 Portal 新增行：<!--portal refs:id1,id2--> 或 <!--portal-->
+    const portalMatch = stripped.match(NEW_PORTAL_RE);
+    if (portalMatch) {
+        const refs = portalMatch[1] ? portalMatch[1].split(',') : [];
+        return { depth, rawContent: '', remId: null, metadata: '', isElided: false, isPortal: true, portalRefs: refs };
+    }
+    // 先检测纯元数据注释（不含 remId，新增行专用）
+    // 必须在 LINE_MARKER_RE 之前，否则 type:concept 等会被误认为 remId
+    const metaOnlyMatch = stripped.match(METADATA_ONLY_RE);
+    if (metaOnlyMatch) {
+        const metadata = metaOnlyMatch[1].trim();
+        const contentPart = stripped.slice(0, metaOnlyMatch.index).trimEnd();
+        return { depth, rawContent: contentPart, remId: null, metadata, isElided: false };
+    }
+    // 匹配行尾标记（含 remId）
     const match = stripped.match(LINE_MARKER_RE);
     if (match) {
         const remId = match[1];
@@ -50,7 +68,7 @@ export function parseOutline(text) {
     // stack[i] = depth 为 i 的最近节点
     const stack = [];
     for (const line of lines) {
-        const { depth, rawContent, remId, isElided } = parseLine(line);
+        const { depth, rawContent, remId, metadata, isElided, isPortal, portalRefs } = parseLine(line);
         const node = {
             remId,
             depth,
@@ -58,6 +76,9 @@ export function parseOutline(text) {
             rawLine: line,
             children: [],
             isElided,
+            metadata: metadata || undefined,
+            isPortal: isPortal || undefined,
+            portalRefs: portalRefs?.length ? portalRefs : undefined,
         };
         if (depth === 0) {
             roots.push(node);
@@ -78,6 +99,33 @@ export function parseOutline(text) {
     }
     return roots;
 }
+// ────────────────────────── 元数据解析 ──────────────────────────
+/**
+ * 解析 HTML 注释中的元数据字符串为结构化属性。
+ *
+ * 支持的标记：type:concept、type:descriptor、doc、tag:Name(id)
+ */
+export function parseMetadata(metadataStr) {
+    const result = {};
+    const tokens = metadataStr.split(/\s+/);
+    for (const token of tokens) {
+        if (token === 'type:concept')
+            result.type = 'concept';
+        else if (token === 'type:descriptor')
+            result.type = 'descriptor';
+        else if (token === 'doc')
+            result.isDocument = true;
+        else if (token.startsWith('tag:')) {
+            const idMatch = token.match(/\(([^)]+)\)$/);
+            if (idMatch) {
+                if (!result.tags)
+                    result.tags = [];
+                result.tags.push(idMatch[1]);
+            }
+        }
+    }
+    return result;
+}
 /**
  * 从新增行的 rawContent 中解析 Markdown 前缀和箭头分隔符，提取属性。
  *
@@ -249,6 +297,9 @@ function collectNewLines(roots) {
                     parentId,
                     position: childPos,
                     parentIsMultiline: isContentMultiline(node.rawContent),
+                    metadata: child.metadata ? parseMetadata(child.metadata) : undefined,
+                    isPortal: child.isPortal,
+                    portalRefs: child.portalRefs,
                 });
                 // 新增行也可能有子节点（嵌套新增）
                 collectNewLinesUnderNew(child, result, myIndex);
@@ -278,6 +329,9 @@ function collectNewLinesUnderNew(parent, result, parentIndex) {
             parentId: `__new_${parentIndex}__`,
             position: childPos,
             parentIsMultiline: isContentMultiline(parent.rawContent),
+            metadata: child.metadata ? parseMetadata(child.metadata) : undefined,
+            isPortal: child.isPortal,
+            portalRefs: child.portalRefs,
         });
         if (child.children.length > 0) {
             collectNewLinesUnderNew(child, result, myIndex);
@@ -285,6 +339,38 @@ function collectNewLinesUnderNew(parent, result, parentIndex) {
         childPos++;
     }
 }
+/**
+ * 检测新增行（无 remId）是否劫持了已有节点的 children。
+ * 遍历新树，找到无 remId 的节点，检查其 children 中是否包含旧树中已存在的 remId。
+ */
+function findCapturedChildren(roots, oldMap) {
+    function walk(node) {
+        if (node.remId === null && !node.isElided && !node.isPortal) {
+            // 新增行：检查它的 children 中是否有已存在的 remId
+            const captured = [];
+            for (const child of node.children) {
+                if (child.remId && oldMap.has(child.remId)) {
+                    captured.push(child.remId);
+                }
+            }
+            if (captured.length > 0) {
+                return { newNodeContent: node.rawContent || '(empty)', capturedIds: captured };
+            }
+        }
+        for (const child of node.children) {
+            const result = walk(child);
+            if (result)
+                return result;
+        }
+        return null;
+    }
+    for (const root of roots) {
+        const result = walk(root);
+        if (result)
+            return result;
+    }
+    return null;
+}
 /** 递归收集所有省略占位符行的 rawContent */
 function collectElidedLines(roots) {
     const result = new Set();
@@ -335,6 +421,24 @@ export function diffTrees(oldRoots, newRoots) {
             };
         }
     }
+    // ── 子节点劫持检测：新增行不应"抢走"已有节点的 children ──
+    // 典型场景：在有子节点的 Rem 和它的 children 之间插入同级新行，
+    // 导致 children 被解析为新行的子节点而非原父节点的子节点。
+    {
+        const captured = findCapturedChildren(newRoots, oldMap);
+        if (captured) {
+            return {
+                type: 'children_captured',
+                message: `New line "${captured.newNodeContent}" accidentally captured existing children (${captured.capturedIds.join(', ')}). ` +
+                    `Insert the new line after the last child, not between a parent Rem and its children.`,
+                details: {
+                    newNodeContent: captured.newNodeContent,
+                    capturedIds: captured.capturedIds,
+                    hint: 'Place the new line after all siblings of the target level, not right after a Rem that has children below it.',
+                },
+            };
+        }
+    }
     // ── 内容变更检测 ──
     const modifiedRems = [];
     for (const [remId, newInfo] of newMap) {
@@ -400,6 +504,9 @@ export function diffTrees(oldRoots, newRoots) {
             parentId: nl.parentId,
             position: nl.position,
             parentIsMultiline: nl.parentIsMultiline,
+            metadata: nl.metadata,
+            isPortal: nl.isPortal,
+            portalRefs: nl.portalRefs,
         });
     }
     // ── D4 步骤 2: 移动（父节点变化） ──

package/dist/mcp/instructions.js

@@ -3,6 +3,8 @@ export const SERVER_INSTRUCTIONS = `
 
 RemNote 知识库操作工具集。你可以通过这些工具读取、搜索、编辑用户的 RemNote 笔记和知识结构。不能操控闪卡（Card/Flashcard）本身——闪卡由 RemNote 根据 Rem 属性自动生成；也不能管理 Plugin 或系统配置。
 
+> **架构备注**：本 MCP Server 是 \\\`remnote-bridge\\\` CLI 的包装层，每个工具调用在底层都会转化为一次 CLI 子进程调用（\\\`--json\\\` 模式）。因此工具的参数、返回值、错误信息与 CLI 完全一致。如果你在错误消息中看到"守护进程"、"daemon"等字样，指的就是 CLI 的后台守护进程。
+
 ---
 
 ## 1. Core Concepts
@@ -29,13 +31,13 @@ Rem 有两个独立维度：**type**（闪卡语义）和 **isDocument**（页
 | \\\`default\\\` | 普通 Rem | 正常字重 |
 | \\\`portal\\\` | 嵌入引用容器 | 紫色边框（**只读**，不可设置） |
 
-### 闪卡的 CLI 操作方式
+### 闪卡的操作方式
 
-闪卡由 Rem 的 \\\`type\\\`、\\\`backText\\\`、\\\`practiceDirection\\\` 三个字段控制。通过 CLI 创建/修改闪卡，操作的是这些**字段**，而非分隔符。
+闪卡由 Rem 的 \\\`type\\\`、\\\`backText\\\`、\\\`practiceDirection\\\` 三个字段控制。创建/修改闪卡，操作的是这些**字段**，而非分隔符。
 
-**禁止**：在文本中插入分隔符（\\\`::\\\`、\\\`;;\\\`、\\\`>>\\\` 等）来创建闪卡。分隔符是 RemNote 编辑器的输入语法，CLI 无法识别。
+**禁止**：在文本中插入分隔符（\\\`::\\\`、\\\`;;\\\`、\\\`>>\\\` 等）来创建闪卡。分隔符是 RemNote 编辑器的输入语法，工具端无法识别。
 
-| 闪卡操作 | CLI 方法 |
+| 闪卡操作 | 方法 |
 |:---------|:---------|
 | 创建概念定义 | \\\`edit_tree\\\` 新增行 \\\`概念 ↔ 定义\\\`，再 \\\`edit_rem\\\` 设 \\\`type: "concept"\\\` |
 | 创建正向问答 | \\\`edit_tree\\\` 新增行 \\\`问题 → 答案\\\` |
@@ -44,7 +46,7 @@ Rem 有两个独立维度：**type**（闪卡语义）和 **isDocument**（页
 
 ### 理解用户意图：分隔符映射
 
-用户在 RemNote 编辑器中通过分隔符创建闪卡。当用户提到这些分隔符时，你需要理解其意图并映射到 CLI 操作：
+用户在 RemNote 编辑器中通过分隔符创建闪卡。当用户提到这些分隔符时，你需要理解其意图并映射到对应的工具操作：
 
 | 用户说 / 编辑器分隔符 | 对应的 type | 对应的 practiceDirection |
 |:----------------------|:-----------|:-----------------------|
@@ -63,6 +65,16 @@ Rem 有两个独立维度：**type**（闪卡语义）和 **isDocument**（页
 | Tag \\\`##\\\` | 附加标签 | 分类标记 |
 | Portal \\\`((\\\` | 嵌入实时视图 | 编辑同步，大纲中标为 \\\`type:portal\\\` |
 
+### Portal 操作速查
+
+| 操作 | 命令 | 方式 |
+|:-----|:-----|:-----|
+| 创建 Portal | \\\`edit_tree\\\` | 新增行 \\\`<!--portal refs:id1,id2-->\\\` |
+| 删除 Portal | \\\`edit_tree\\\` | 从大纲中移除 Portal 行（与删除普通行相同） |
+| 修改引用列表（增删引用的 Rem） | \\\`edit_rem\\\` | str_replace 简化 JSON 中的 \\\`portalDirectlyIncludedRem\\\` 数组 |
+| 移动 Portal（换父节点/位置） | \\\`edit_tree\\\` | 与移动普通行相同 |
+| 读取 Portal | \\\`read_rem\\\` | 自动输出 9 字段简化 JSON |
+
 ### Powerup 过滤
 
 RemNote 的格式设置（标题、高亮、代码等）会注入隐藏的系统 Tag 和子 Rem。这些噪音数据**默认自动过滤**，你通常无需关心。
@@ -91,6 +103,12 @@ disconnect → 关闭 daemon，清空所有缓存
 - \\\`disconnect\\\` 会销毁所有缓存，之前的 read 结果全部失效
 - daemon 默认 30 分钟无活动自动关闭
 
+### Windows 注意事项
+
+- **首次 connect 较慢**：daemon 启动时会自动安装 remnote-plugin 的依赖（约 600+ 个包），在 Windows 上可能需要 30-60 秒，connect 超时设为 60 秒
+- **依赖自动修复**：如果 webpack-dev-server 因依赖损坏而崩溃，daemon 会自动清洁重装依赖（删除 node_modules 后重新安装）并重试，最多重试 2 次
+- **端口残留**：多次 connect 失败后可能出现端口被占用（EADDRINUSE），用 \\\`remnote-bridge disconnect\\\` 或手动终止占用端口的进程后重试
+
 ### ⚠️ connect 后需要用户配合（重要）
 
 \\\`connect\\\` 成功只意味着 daemon 和 webpack-dev-server 已启动，**Plugin 并未自动连接**。用户必须在 RemNote 中完成以下操作，Plugin 才能连接到 daemon：
@@ -196,31 +214,50 @@ newStr:  "text": [\\n    "点击",\\n    {\\n      "i": "m",\\n      "iUrl": "ht
 
 1. \\\`read_tree\\\` 获取目标区域的 Markdown 大纲（建立缓存）
 2. 在大纲中用 str_replace 进行结构修改：
-   - **新增**：插入无 remId 注释的新行（通过缩进确定父子关系）
+   - **新增**：插入无 remId 注释的新行（通过缩进确定父子关系）。可在行尾加元数据注释指定属性：\\\`新行 <!--type:concept doc tag:Name(id)-->\\\`
    - **删除**：移除带 remId 的行（必须同时删除所有子行）
    - **移动**：改变行的缩进级别或位置
    - **重排**：调换同级行的顺序
 
 **红线**：edit_tree **禁止修改已有行的文字内容**——改内容必须用 edit_rem。edit_tree 只做结构操作。
 
+**⚠️ 新增行的插入位置**：新行必须插在目标层级所有兄弟的**末尾**，不能插在一个有子节点的 Rem 和它的 children 之间。否则 children 会被新行"劫持"，触发 \\\`children_captured\\\` 错误。
+
+\\\`\\\`\\\`
+❌ 错误：插在父 Rem 和 children 之间
+oldStr:   水分子 ↓ <!--idA-->
+newStr:   水分子 ↓ <!--idA-->
+          新行                    ← children 会变成新行的子节点！
+
+✅ 正确：插在末尾
+oldStr:   最后一个兄弟 <!--idZ-->
+newStr:   最后一个兄弟 <!--idZ-->
+          新行
+\\\`\\\`\\\`
+
+**需要"创建新节点并把已有 children 移过去"？** 分两步：
+1. 第一次 \\\`edit_tree\\\`：在末尾创建新节点（获得 remId）
+2. 第二次 \\\`edit_tree\\\`：把已有行移动到新节点下面（此时新节点已有 remId，走正常 move 逻辑）
+
 ### 场景 F：创建 / 修改闪卡
 
 > 用户说："创建一个概念定义"、"做个正向问答卡"、"把这个改成 concept"
 
 闪卡由 \\\`type\\\`、\\\`backText\\\`、\\\`practiceDirection\\\` 三个字段控制。操作方式：
 
-**创建新闪卡**（\\\`edit_tree\\\` 新增行 + 箭头）：
+**创建新闪卡**（\\\`edit_tree\\\` 新增行 + 箭头 + 可选元数据注释）：
 - 正向问答：\\\`问题 → 答案\\\`
 - 双向问答：\\\`问题 ↔ 答案\\\`
 - 多行答案：\\\`问题 ↓\\\`（子行自动成为答案）
-- 概念定义：\\\`概念 ↔ 定义\\\`，再用 \\\`edit_rem\\\` 设 \\\`type: "concept"\\\`
+- 概念定义：\\\`概念 ↔ 定义 <!--type:concept-->\\\`（一步完成，无需再 edit_rem）
+- 描述属性：\\\`属性 → 值 <!--type:descriptor-->\\\`
 
 **修改现有 Rem 的闪卡行为**（\\\`read_rem\\\` → \\\`edit_rem\\\`）：
 - 改类型：修改 \\\`type\\\` 字段（\\\`"default"\\\` → \\\`"concept"\\\`）
 - 改方向：修改 \\\`practiceDirection\\\`（\\\`"forward"\\\` / \\\`"backward"\\\` / \\\`"both"\\\` / \\\`"none"\\\`）
 - 加/改背面：修改 \\\`backText\\\` 字段
 
-**禁止**：在文本内容中插入 \\\`::\\\`、\\\`;;\\\`、\\\`>>\\\` 等分隔符——这些是 RemNote 编辑器语法，CLI 不识别。
+**禁止**：在文本内容中插入 \\\`::\\\`、\\\`;;\\\`、\\\`>>\\\` 等分隔符——这些是 RemNote 编辑器语法，工具端不识别。
 
 ### 场景 G：排查连接问题
 
@@ -317,6 +354,7 @@ newStr:  "text": [\\n    "点击",\\n    {\\n      "i": "m",\\n      "iUrl": "ht
 | Content modification not allowed | edit_tree 中修改了行内容 | 改用 \\\`edit_rem\\\` 修改内容 |
 | orphan_detected | 删了父行但保留了子行 | 同时删除所有子行 |
 | folded_delete | 删除有隐藏子节点的行 | 用更大 depth 重新 read_tree |
+| children_captured | 新行插在父 Rem 和它的 children 之间，劫持了已有子节点 | 把新行插到所有兄弟的**末尾**而非紧跟父 Rem 之后（见下方说明） |
 
 完整错误参考见 \\\`resource://error-reference\\\`。
 `;

package/dist/mcp/resources/edit-rem-guide.js

@@ -176,6 +176,59 @@ newStr:  "practiceDirection": "both"
 | 混淆 highlightColor 和 h | 前者字符串 \\\`"Red"\\\`，后者数字 \\\`1\\\` | 参考上方对比表 |
 | 漏 onlyAudio | \\\`i:"a"\\\` 的 \\\`onlyAudio\\\` 是必填 | true=音频，false=视频 |
 | JSON 语法错 | 引号、逗号、括号不完整 | 检查替换边界 |
+| Portal oldStr 不匹配 | Portal 编辑在简化 JSON 上匹配，不是完整 JSON | 检查 oldStr 是否匹配 9 字段简化 JSON |
+
+---
+
+## Portal 编辑
+
+当被编辑的 Rem 是 Portal（type === 'portal'）时，edit_rem 自动切换到 Portal 专用路径。
+
+**edit_rem 只能修改 Portal 的引用列表和位置属性。创建 Portal 和删除 Portal 请使用 \\\`edit_tree\\\`。**
+
+### 操作目标：简化 JSON
+
+Portal 的 str_replace 在 **9 字段简化 JSON** 上执行（而非完整 51 字段）：
+
+\\\`\\\`\\\`json
+{
+  "id": "abc123",
+  "type": "portal",
+  "portalType": "portal",
+  "portalDirectlyIncludedRem": ["remId1", "remId2"],
+  "parent": "parentId",
+  "positionAmongstSiblings": 3,
+  "children": ["remId1", "remId2"],
+  "createdAt": 1709000000000,
+  "updatedAt": 1709000000000
+}
+\\\`\\\`\\\`
+
+### 可写字段
+
+| 字段 | 写入方式 |
+|:-----|:---------|
+| \\\`portalDirectlyIncludedRem\\\` | diff 数组 → addToPortal / removeFromPortal |
+| \\\`parent\\\` | setParent() |
+| \\\`positionAmongstSiblings\\\` | setParent(parent, position) |
+
+其余字段（id、type、portalType、children、createdAt、updatedAt）为只读，修改只产生警告。
+
+### 示例
+
+添加引用：
+
+\\\`\\\`\\\`
+oldStr:  "portalDirectlyIncludedRem": ["remId1", "remId2"]
+newStr:  "portalDirectlyIncludedRem": ["remId1", "remId2", "remId3"]
+\\\`\\\`\\\`
+
+移除引用：
+
+\\\`\\\`\\\`
+oldStr:  "portalDirectlyIncludedRem": ["remId1", "remId2"]
+newStr:  "portalDirectlyIncludedRem": ["remId1"]
+\\\`\\\`\\\`
 
 ---