remnote-bridge 0.1.6 → 0.1.8

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/cli/main.js

@@ -4,8 +4,10 @@
  *
  * 伞命令：CLI 命令 + mcp 子命令 + install 子命令。
  */
+import { createRequire } from 'module';
 import { Command } from 'commander';
 import { connectCommand } from './commands/connect.js';
+import { setupCommand } from './commands/setup.js';
 import { healthCommand } from './commands/health.js';
 import { disconnectCommand } from './commands/disconnect.js';
 import { readRemCommand } from './commands/read-rem.js';
@@ -17,6 +19,8 @@ import { readContextCommand } from './commands/read-context.js';
 import { searchCommand } from './commands/search.js';
 import { installSkillCommand, installSkillCopyCommand } from './commands/install-skill.js';
 import { cleanCommand } from './commands/clean.js';
+const require = createRequire(import.meta.url);
+const { version } = require('../../package.json');
 const program = new Command();
 /**
  * --json 模式下解析 JSON 输入参数。
@@ -54,21 +58,33 @@ function parseJsonInput(command, jsonStr, requiredFields = []) {
 program
     .name('remnote-bridge')
     .description('RemNote Bridge — CLI + MCP Server + Plugin')
-    .version('0.1.6')
+    .version(version)
     .option('--json', '以 JSON 格式输出（适用于程序化调用）');
 program
-    .command('connect')
-    .description('启动守护进程（WS Server + webpack-dev-server），等待 Plugin 连接')
+    .command('setup')
+    .description('启动 Chrome 让用户登录 RemNote（headless 模式前置步骤）')
     .action(async () => {
     const { json } = program.opts();
-    await connectCommand({ json });
+    await setupCommand({ json });
+});
+program
+    .command('connect')
+    .description('启动守护进程，等待 Plugin 连接')
+    .option('--dev', '开发模式：使用 webpack-dev-server（支持 HMR）')
+    .option('--headless', '无头模式：自动启动 headless Chrome 加载 Plugin（需先 setup）')
+    .option('--remote-debugging-port <port>', 'Chrome 远程调试端口（仅 --headless）', parseInt)
+    .action(async (cmdOpts) => {
+    const { json } = program.opts();
+    await connectCommand({ json, dev: cmdOpts.dev, headless: cmdOpts.headless, remoteDebuggingPort: cmdOpts.remoteDebuggingPort });
 });
 program
     .command('health')
     .description('检查守护进程、Plugin 连接和 SDK 状态')
-    .action(async () => {
+    .option('--diagnose', '诊断 headless Chrome（截图 + 状态 + console 错误）')
+    .option('--reload', '重载 headless Chrome 页面')
+    .action(async (cmdOpts) => {
     const { json } = program.opts();
-    await healthCommand({ json });
+    await healthCommand({ json, diagnose: cmdOpts.diagnose, reload: cmdOpts.reload });
 });
 program
     .command('disconnect')

package/dist/cli/server/ws-server.js

@@ -49,6 +49,9 @@ export class BridgeServer {
             pongTimeoutMs: config.pongTimeoutMs ?? 10_000,
             onLog: config.onLog,
             getTimeoutRemaining: config.getTimeoutRemaining,
+            getHeadlessStatus: config.getHeadlessStatus,
+            diagnoseHeadless: config.diagnoseHeadless,
+            reloadHeadless: config.reloadHeadless,
         };
         this.defaults = config.defaults ?? DEFAULT_DEFAULTS;
         const defaults = this.defaults;
@@ -200,6 +203,59 @@ export class BridgeServer {
             ws.send(JSON.stringify(response));
             return;
         }
+        // diagnose：headless 诊断（不需要 Plugin）
+        if (request.action === 'diagnose') {
+            if (!this.config.diagnoseHeadless) {
+                const response = {
+                    id: request.id,
+                    error: '非 headless 模式，不支持 diagnose',
+                };
+                ws.send(JSON.stringify(response));
+                return;
+            }
+            try {
+                const diagResult = await this.config.diagnoseHeadless();
+                if (diagResult) {
+                    // 补充 pluginConnected 和 sdkReady
+                    diagResult.pluginConnected = this.pluginSocket?.readyState === WebSocket.OPEN;
+                    diagResult.sdkReady = this.pluginSdkReady;
+                }
+                const response = { id: request.id, result: diagResult };
+                ws.send(JSON.stringify(response));
+            }
+            catch (err) {
+                const response = {
+                    id: request.id,
+                    error: err instanceof Error ? err.message : String(err),
+                };
+                ws.send(JSON.stringify(response));
+            }
+            return;
+        }
+        // headless_reload：重载 headless Chrome 页面（不需要 Plugin）
+        if (request.action === 'headless_reload') {
+            if (!this.config.reloadHeadless) {
+                const response = {
+                    id: request.id,
+                    error: '非 headless 模式，不支持 reload',
+                };
+                ws.send(JSON.stringify(response));
+                return;
+            }
+            try {
+                const reloadResult = await this.config.reloadHeadless();
+                const response = { id: request.id, result: reloadResult };
+                ws.send(JSON.stringify(response));
+            }
+            catch (err) {
+                const response = {
+                    id: request.id,
+                    error: err instanceof Error ? err.message : String(err),
+                };
+                ws.send(JSON.stringify(response));
+            }
+            return;
+        }
         // 以下 action 都需要 Plugin 连接
         if (!this.pluginSocket || this.pluginSocket.readyState !== WebSocket.OPEN) {
             const response = {
@@ -325,11 +381,16 @@ export class BridgeServer {
     }
     /** 获取当前状态（timeoutRemaining 通过构造时注入的回调获取） */
     getStatus() {
-        return {
+        const result = {
             pluginConnected: this.pluginSocket?.readyState === WebSocket.OPEN,
             sdkReady: this.pluginSdkReady,
             uptime: Math.floor((Date.now() - this.startTime) / 1000),
             timeoutRemaining: this.config.getTimeoutRemaining?.() ?? 0,
         };
+        const headlessStatus = this.config.getHeadlessStatus?.();
+        if (headlessStatus) {
+            result.headless = headlessStatus;
+        }
+        return result;
     }
 }

package/dist/mcp/daemon-client.js

@@ -46,8 +46,11 @@ export class CliError extends Error {
  */
 export async function callCli(command, payload, options) {
     const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-    // 构造参数列表：--json <command> [jsonStr]
+    // 构造参数列表：--json <command> [flags...] [jsonStr]
     const args = ['--json', command];
+    if (options?.flags) {
+        args.push(...options.flags);
+    }
     if (payload !== undefined) {
         args.push(JSON.stringify(payload));
     }

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。这些噪音数据**默认自动过滤**，你通常无需关心。
@@ -73,6 +85,8 @@ RemNote 的格式设置（标题、高亮、代码等）会注入隐藏的系统
 
 所有操作都依赖一个活跃的会话。会话 = 守护进程的生命周期。
 
+### 标准模式（需要用户配合）
+
 \\\`\\\`\\\`
 connect → 启动 daemon（幂等，重复调用安全）
   ↓
@@ -85,21 +99,72 @@ health → 确认三层就绪（daemon / Plugin / SDK）
 disconnect → 关闭 daemon，清空所有缓存
 \\\`\\\`\\\`
 
+### Headless 模式（自动连接）
+
+标准模式每次 connect 后都需要用户手动操作 RemNote。Headless 模式通过 setup（一次性）+ headless Chrome 实现自动连接，后续 connect 无需用户介入。
+
+#### 首次使用（setup）
+
+\\\`setup\\\` 会弹出 Chrome 窗口，用户需要完成两件事：
+1. **登录 RemNote**
+2. **配置 dev plugin**：插件图标 → 开发你的插件 → 填入 \\\`http://localhost:8080\\\`
+
+完成后**彻底退出 Chrome**（macOS 必须 Cmd+Q，仅关窗口不够）。
+
+**你必须这样与用户交互**：
+1. 调用 \\\`setup\\\`
+2. 立即告知用户：
+   "已打开 Chrome 浏览器。请完成以下操作：
+    1. 登录 RemNote
+    2. 在 RemNote 中配置开发插件：点击左下角插件图标 → 开发你的插件 → 输入 http://localhost:8080
+    3. 完成后彻底退出 Chrome（macOS 请按 Cmd+Q）"
+3. 等待 \\\`setup\\\` 返回（阻塞，最长 10 分钟）
+4. 成功 → 进入下一步 \\\`connect(headless=true)\\\`
+
+setup 只需执行一次。之后每次连接直接用 \\\`connect(headless=true)\\\`。
+
+#### 后续使用
+
+\\\`\\\`\\\`
+connect(headless=true) → 启动 daemon + headless Chrome 自动加载 RemNote 和 Plugin
+  ↓
+health → 等待三层就绪（Plugin 需要 10-30 秒连接，可多次轮询）
+  ↓
+业务操作（read / search / edit）
+  ↓
+disconnect → 关闭 daemon + headless Chrome，清空所有缓存
+\\\`\\\`\\\`
+
+**无需任何用户操作**——headless Chrome 在后台自动完成登录和 Plugin 加载。
+
+#### 排查
+
+- \\\`health(diagnose=true)\\\`：截图 + Chrome 状态 + console 错误（确认页面是否正常加载）
+- \\\`health(reload=true)\\\`：重载 headless Chrome 页面（Plugin 未连接时尝试）
+- 如果 Plugin 始终不连接，可能是 RemNote 登录 session 过期，需重新 setup
+
 **关键要点**：
 - \\\`connect\\\` 是所有业务操作的前提，未 connect 时任何命令都会报"守护进程未运行"
 - \\\`health\\\` 检查三层状态：daemon 运行 → Plugin 已连接 → SDK 就绪，三者全部通过才能执行业务命令
 - \\\`disconnect\\\` 会销毁所有缓存，之前的 read 结果全部失效
 - daemon 默认 30 分钟无活动自动关闭
 
-### ⚠️ connect 后需要用户配合（重要）
+### Windows 注意事项
 
-\\\`connect\\\` 成功只意味着 daemon 和 webpack-dev-server 已启动，**Plugin 并未自动连接**。用户必须在 RemNote 中完成以下操作，Plugin 才能连接到 daemon：
+- **默认模式秒级启动**：使用预构建 plugin，无需安装依赖
+- **\`--dev\` 模式首次较慢**：会自动安装 remnote-plugin 的依赖（约 600+ 个包），在 Windows 上可能需要 30-60 秒，connect 超时设为 60 秒
+- **\`--dev\` 依赖自动修复**：如果 webpack-dev-server 因依赖损坏而崩溃，daemon 会自动清洁重装依赖（删除 node_modules 后重新安装）并重试，最多重试 2 次
+- **端口残留**：多次 connect 失败后可能出现端口被占用（EADDRINUSE），用 \\\`remnote-bridge disconnect\\\` 或手动终止占用端口的进程后重试
+
+### ⚠️ 标准模式：connect 后需要用户配合（重要）
+
+\\\`connect\\\`（不传 headless）成功只意味着 daemon 和 Plugin 服务已启动，**Plugin 并未自动连接**。用户必须在 RemNote 中完成以下操作，Plugin 才能连接到 daemon：
 
 **首次使用**（RemNote 从未加载过此插件）：
 1. 打开 RemNote 桌面端或网页端
 2. 点击左侧边栏底部的插件图标（拼图形状）
 3. 点击「开发你的插件」（Develop Your Plugin）
-4. 在输入框中填入 \\\`http://localhost:8080\\\`（即 connect 输出的 webpack-dev-server 地址）
+4. 在输入框中填入 \\\`http://localhost:8080\\\`（即 connect 输出的 Plugin 服务地址）
 5. 等待插件加载完成
 
 **非首次使用**（之前已加载过此插件）：
@@ -196,31 +261,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 +401,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"]
+\\\`\\\`\\\`
 
 ---