remnote-bridge 0.1.12 → 0.1.14

package/dist/mcp/instructions.js

@@ -1,9 +1,9 @@
 export const SERVER_INSTRUCTIONS = `
 # RemNote Bridge MCP Server — Agent 操作手册
 
-RemNote 知识库操作工具集。你可以通过这些工具读取、搜索、编辑用户的 RemNote 笔记和知识结构。不能操控闪卡（Card/Flashcard）本身——闪卡由 RemNote 根据 Rem 属性自动生成；也不能管理 Plugin 或系统配置。
+RemNote 知识库操作工具集。通过这些工具读取、搜索、编辑用户的 RemNote 笔记和知识结构。不能操控闪卡（Card/Flashcard）本身——闪卡由 RemNote 根据 Rem 属性自动生成。
 
-> **架构备注**：本 MCP Server 是 \\\`remnote-bridge\\\` CLI 的包装层，每个工具调用在底层都会转化为一次 CLI 子进程调用（\\\`--json\\\` 模式）。因此工具的参数、返回值、错误信息与 CLI 完全一致。如果你在错误消息中看到"守护进程"、"daemon"等字样，指的就是 CLI 的后台守护进程。
+> **架构备注**：本 MCP Server 是 \`remnote-bridge\` CLI 的包装层，每个工具调用在底层都会转化为一次 CLI 子进程调用（\`--json\` 模式）。错误消息中的"守护进程"/"daemon"指 CLI 的后台守护进程。
 
 ---
 
@@ -11,12 +11,10 @@ RemNote 知识库操作工具集。你可以通过这些工具读取、搜索、
 
 ### Everything is Rem
 
-用户说的"笔记"、"文档"、"文件夹"、"闪卡"，底层都是 **Rem**。不同形态通过属性区分：
-
 | 用户说的 | 实际上是 | 区分方式 |
 |:---------|:---------|:---------|
 | 笔记 / 条目 | Rem | 最基本的数据单元 |
-| 文档 / 页面 | Rem（\\\`isDocument=true\\\`） | 可独立打开的页面 |
+| 文档 / 页面 | Rem（\`isDocument=true\`） | 可独立打开的页面 |
 | 文件夹 | Rem（Document + 子节点全是 Document） | UI 概念，无独立标记 |
 | 闪卡 | Card——由 Rem 属性自动生成 | **不可直接操控** |
 
@@ -26,79 +24,105 @@ Rem 有两个独立维度：**type**（闪卡语义）和 **isDocument**（页
 
 | type | 含义 | UI 表现 |
 |:-----|:-----|:--------|
-| \\\`concept\\\` | 概念定义 | 文字**加粗** |
-| \\\`descriptor\\\` | 描述/属性 | 正常字重（与 default 无视觉差异） |
-| \\\`default\\\` | 普通 Rem | 正常字重 |
-| \\\`portal\\\` | 嵌入引用容器 | 紫色边框（**只读**，不可设置） |
+| \`concept\` | 概念定义 | 文字**加粗** |
+| \`descriptor\` | 描述/属性 | 正常字重 |
+| \`default\` | 普通 Rem | 正常字重 |
+| \`portal\` | 嵌入引用容器 | 紫色边框（**不可通过 setType 创建**） |
+
+### 闪卡机制
 
-### 闪卡的操作方式
+闪卡由 Rem 的 \`type\`、\`backText\`、\`practiceDirection\` 三个字段控制。
 
-闪卡由 Rem 的 \\\`type\\\`、\\\`backText\\\`、\\\`practiceDirection\\\` 三个字段控制。创建/修改闪卡，操作的是这些**字段**，而非分隔符。
+**禁止**：在文本中插入分隔符（\`::\`、\`;;\`、\`>>\` 等）来创建闪卡。分隔符是 RemNote 编辑器语法，工具端无法识别。
 
-**禁止**：在文本中插入分隔符（\\\`::\\\`、\\\`;;\\\`、\\\`>>\\\` 等）来创建闪卡。分隔符是 RemNote 编辑器的输入语法，工具端无法识别。
+#### 创建/修改闪卡
 
 | 闪卡操作 | 方法 |
-|:---------|:---------|
-| 创建概念定义 | \\\`edit_tree\\\` 新增行 \\\`概念 ↔ 定义\\\`，再 \\\`edit_rem\\\` 设 \\\`type: "concept"\\\` |
-| 创建正向问答 | \\\`edit_tree\\\` 新增行 \\\`问题 → 答案\\\` |
-| 创建多行答案 | \\\`edit_tree\\\` 新增行 \\\`问题 ↓\\\`（子行自动成为答案） |
-| 改变闪卡类型 | \\\`edit_rem\\\` 修改 \\\`type\\\`、\\\`backText\\\`、\\\`practiceDirection\\\` |
+|:---------|:-----|
+| 创建概念定义 | \`edit_tree\` 新增行 \`概念 ↔ 定义 <!--type:concept-->\` |
+| 创建正向问答 | \`edit_tree\` 新增行 \`问题 → 答案\` |
+| 创建反向问答 | \`edit_tree\` 新增行 \`问题 ← 答案\` |
+| 创建多行答案 | \`edit_tree\` 新增行 \`问题 ↓\`（子行自动成为答案） |
+| 改变闪卡类型/方向 | \`edit_rem\` 修改 \`type\`、\`backText\`、\`practiceDirection\` |
+
+\`practiceDirection\` 取值：\`forward\`、\`backward\`、\`both\`、\`none\`。
+
+#### 分隔符映射（理解用户意图）
+
+用户在编辑器中用分隔符创建闪卡，提到时需映射到工具操作：
+
+| 用户说 / 编辑器分隔符 | 对应 type | 对应 practiceDirection |
+|:----------------------|:----------|:----------------------|
+| \`::\` | concept | both |
+| \`;;\` | descriptor | forward |
+| \`>>\` / \`<<\` / \`<>\` | default | forward / backward / both |
+| \`>>>\` / \`::>\` / \`;;>\` | default / concept / descriptor | 多行（子 Rem 为答案） |
+| \`{{}}\` | default | forward（完形填空） |
+
+### CDF（Concept-Descriptor Framework）
+
+RemNote 推荐的知识结构化方法——用 Concept 和 Descriptor 构建可自动生成闪卡的知识网络：
+
+- **Concept**（type:concept）：核心概念——回答"X 是什么？"，文字加粗显示
+- **Descriptor**（type:descriptor）：概念的属性——回答"X 的 Y 是什么？"
 
-### 理解用户意图：分隔符映射
+在 CLI 大纲中的表现：
+\`\`\`
+线性回归 ↔ 最基本的回归模型 <!--id1 type:concept-->
+  假设 → 因变量与自变量呈线性关系 <!--id2 type:descriptor-->
+  损失函数 → 均方误差 (MSE) <!--id3 type:descriptor-->
+\`\`\`
 
-用户在 RemNote 编辑器中通过分隔符创建闪卡。当用户提到这些分隔符时，你需要理解其意图并映射到对应的工具操作：
+CDF 的核心优势：Concept 自动生成双向闪卡（"什么是线性回归？"↔"最基本的回归模型"），Descriptor 自动生成正向闪卡（"线性回归的假设？"→"因变量与自变量呈线性关系"），层级关系自动维护上下文。
 
-| 用户说 / 编辑器分隔符 | 对应的 type | 对应的 practiceDirection |
-|:----------------------|:-----------|:-----------------------|
-| \\\`::\\\` | concept | both |
-| \\\`;;\\\` | descriptor | forward |
-| \\\`>>\\\` / \\\`<<\\\` / \\\`<>\\\` | default | forward / backward / both |
-| \\\`>>>\\\` / \\\`::>\\\` / \\\`;;>\\\` | default / concept / descriptor | forward / both / forward（多行） |
+### 完形填空（Cloze）
 
-完整映射表见 \\\`resource://separator-flashcard\\\`。
+通过 RichText 中的 \`cId\` 标记实现（不是分隔符），练习时 \`cId\` 标记的文本被遮盖：
+
+\`\`\`json
+["The ", {"cId": "cloze1", "i": "m", "text": "capital"}, " of France is Paris"]
+\`\`\`
+
+通过 \`edit_rem\` 操作 RichText 来创建/修改完形填空——在 \`changes.text\` 数组中为目标文字片段添加 \`cId\` 字段。每个 cloze 需要唯一的 \`cId\` 值。
 
 ### 链接机制
 
 | 机制 | 用户操作 | 说明 |
 |:-----|:---------|:-----|
-| Reference \\\`[[\\\` | 文本内引用 | 只是指针，不同步编辑 |
-| Tag \\\`##\\\` | 附加标签 | 分类标记 |
-| Portal \\\`((\\\` | 嵌入实时视图 | 编辑同步，大纲中标为 \\\`type:portal\\\` |
+| Reference \`[[\` | 文本内引用 | 只是指针，不同步编辑 |
+| Tag \`##\` | 附加标签 | 分类标记 |
+| Portal \`((\` | 嵌入实时视图 | **编辑同步**，大纲中标为 \`type:portal\` |
 
-### 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\\\` | 自动输出 8 字段简化 JSON |
+| 创建 Portal | \`edit_tree\` | 新增行 \`<!--portal refs:id1,id2-->\` |
+| 删除 Portal | \`edit_tree\` | 从大纲中移除 Portal 行 |
+| 修改引用列表 | \`edit_rem\` | 修改 \`portalDirectlyIncludedRem\` 数组 |
+| 移动 Portal | \`edit_tree\` | 与移动普通行相同 |
+| 读取 Portal | \`read_rem\` | 自动输出 8 字段简化 JSON |
 
 ### Powerup 过滤
 
-RemNote 的格式设置（标题、高亮、代码等）会注入隐藏的系统 Tag 和子 Rem。这些噪音数据**默认自动过滤**，你通常无需关心。
+RemNote 格式设置（标题、高亮、代码等）底层通过 Powerup 机制实现，会向 Rem 注入隐藏的系统 Tag（\`isPowerup===true\`）和子 Rem（\`isPowerupProperty\`/\`isPowerupSlot\`）。
 
----
-
-## 2. Session Lifecycle
+**默认自动过滤**（\`includePowerup=false\`），返回值中 \`powerupFiltered\` 字段统计被过滤的数量（如 \`{tags: 2, children: 3}\`）。
 
-所有操作都依赖一个活跃的会话。会话 = 守护进程的生命周期。
+\`includePowerup=true\` 参数可恢复完整数据（调试用）。\`read_tree\` 支持此参数，\`read_globe\` 和 \`read_context\` 硬编码过滤。
 
-### 多实例支持
+通常无需关心 Powerup 过滤，除非你需要理解某个 Rem 为什么有额外的 children 或 tags。
 
-系统支持最多 **4 个并发实例**，每个实例连接不同的 RemNote 知识库。通过 \\\`instance\\\` 参数指定实例名：
+---
 
-- \\\`connect(instance="work")\\\` — 启动 "work" 实例
-- \\\`health(instance="work")\\\` — 检查 "work" 实例状态
-- \\\`disconnect(instance="work")\\\` — 停止 "work" 实例
+## 2. Session Lifecycle
 
-不指定 instance 时默认为 \\\`"default"\\\`。每个实例独占一个槽位（固定端口组），槽位自动分配。各实例的缓存相互独立。
+所有操作都依赖一个活跃的会话（= 守护进程的生命周期）。
 
 ### 标准模式（需要用户配合）
 
-\\\`\\\`\\\`
-connect → 启动 daemon（幂等，重复调用安全）
+\`\`\`
+connect → 启动 daemon（幂等）
   ↓
 ⚠️ 用户操作：确保 RemNote 中已加载插件（见下方说明）
   ↓
@@ -107,85 +131,70 @@ health → 确认三层就绪（daemon / Plugin / SDK）
 业务操作（read / search / edit）
   ↓
 disconnect → 关闭 daemon，清空所有缓存
-\\\`\\\`\\\`
+\`\`\`
 
 ### Headless 模式（自动连接）
 
-标准模式每次 connect 后都需要用户手动操作 RemNote。Headless 模式通过 setup（一次性）+ headless Chrome 实现自动连接，后续 connect 无需用户介入。
+通过 setup（一次性）+ headless Chrome 实现自动连接，后续 connect 无需用户介入。
 
-**⚠️ 模式选择建议**：日常使用推荐**标准模式**。Headless 模式下 Chrome 在后台运行，**无法感知用户正在 RemNote 中浏览和操作的界面**（\\\`read_context\\\` 返回的是 headless Chrome 的上下文，而非用户的浏览器）。只有在全自动化场景（CI/CD、定时任务、批量操作等无需与用户界面交互的场景）才建议使用 Headless 模式。
+**⚠️ 模式选择建议**：日常使用推荐**标准模式**。Headless 模式下 Chrome 在后台运行，**无法感知用户正在 RemNote 中浏览和操作的界面**（\`read_context\` 返回的是 headless Chrome 的上下文，而非用户的浏览器）。只有在全自动化场景才建议使用 Headless 模式。
 
 #### 首次使用（setup）
 
-\\\`setup\\\` 会弹出 Chrome 窗口，用户需要完成两件事：
-1. **登录 RemNote**
-2. **配置 dev plugin**：插件图标 → 开发你的插件 → 填入 connect 输出的 Plugin 服务地址（如 \\\`http://localhost:29101\\\`）
-
-完成后**彻底退出 Chrome**（macOS 必须 Cmd+Q，仅关窗口不够）。
+\`setup\` 会弹出 Chrome 窗口，用户只需 **登录 RemNote**，然后**彻底退出 Chrome**（macOS 必须 Cmd+Q，仅关窗口不够）。setup 只负责保存登录凭证。
 
 **你必须这样与用户交互**：
-1. 调用 \\\`setup\\\`
-2. 立即告知用户：
-   "已打开 Chrome 浏览器。请完成以下操作：
-    1. 登录 RemNote
-    2. 在 RemNote 中配置开发插件：点击左下角插件图标 → 开发你的插件 → 输入 connect 输出的 Plugin 服务地址
-    3. 完成后彻底退出 Chrome（macOS 请按 Cmd+Q）"
-3. 等待 \\\`setup\\\` 返回（阻塞，最长 10 分钟）
-4. 成功 → 进入下一步 \\\`connect(headless=true)\\\`
+1. 调用 \`setup\`
+2. 立即告知用户："已打开 Chrome 浏览器。请登录 RemNote，完成后彻底退出 Chrome（macOS 请按 Cmd+Q）"
+3. 等待 \`setup\` 返回（阻塞，最长 10 分钟）
+4. 成功 → 进入下一步 \`connect(headless=true)\`
 
-setup 只需执行一次。之后每次连接直接用 \\\`connect(headless=true)\\\`。
+setup 只需执行一次。之后每次连接直接用 \`connect(headless=true)\`。
 
 #### 后续使用
 
-\\\`\\\`\\\`
+\`\`\`
 connect(headless=true) → 启动 daemon + headless Chrome 自动加载 RemNote 和 Plugin
-  ↓
+  ↓                        MCP Server 自动记住 headless 状态
 health → 等待三层就绪（Plugin 需要 10-30 秒连接，可多次轮询）
-  ↓
+  ↓                        后续所有工具自动路由到 headless 实例
 业务操作（read / search / edit）
   ↓
-disconnect → 关闭 daemon + headless Chrome，清空所有缓存
-\\\`\\\`\\\`
-
-**无需任何用户操作**——headless Chrome 在后台自动完成登录和 Plugin 加载。
+disconnect → 关闭 daemon + headless Chrome，清空所有缓存，清除 headless 状态
+\`\`\`
 
 #### 排查
 
-- \\\`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 分钟无活动自动关闭
-
-### Windows 注意事项
-
-- **默认模式秒级启动**：使用预构建 plugin，无需安装依赖
-- **\`--dev\` 模式首次较慢**：会自动安装 remnote-plugin 的依赖（约 600+ 个包），在 Windows 上可能需要 30-60 秒，connect 超时设为 60 秒
-- **\`--dev\` 依赖自动修复**：如果 webpack-dev-server 因依赖损坏而崩溃，daemon 会自动清洁重装依赖（删除 node_modules 后重新安装）并重试，最多重试 2 次
-- **端口残留**：多次 connect 失败后可能出现端口被占用（EADDRINUSE），用 \\\`remnote-bridge disconnect\\\` 或手动终止占用端口的进程后重试
+- \`health(diagnose=true)\`：截图 + Chrome 状态 + console 错误
+- \`health(reload=true)\`：重载 headless Chrome 页面
+- Plugin 始终不连接 → 可能登录 session 过期，需重新 setup
 
 ### ⚠️ 标准模式：connect 后需要用户配合（重要）
 
-\\\`connect\\\`（不传 headless）成功只意味着 daemon 和 Plugin 服务已启动，**Plugin 并未自动连接**。用户必须在 RemNote 中完成以下操作，Plugin 才能连接到 daemon：
+\`connect\`（不传 headless）成功只意味着 daemon 和 Plugin 服务已启动，**Plugin 并未自动连接**。
 
 **首次使用**（RemNote 从未加载过此插件）：
 1. 打开 RemNote 桌面端或网页端
 2. 点击左侧边栏底部的插件图标（拼图形状）
 3. 点击「开发你的插件」（Develop Your Plugin）
-4. 在输入框中填入 connect 输出的 Plugin 服务地址（如 \\\`http://localhost:29101\\\`）
+4. 在输入框中填入 connect 输出的 Plugin 服务地址（如 \`http://localhost:29101\`）
 5. 等待插件加载完成
 
 **非首次使用**（之前已加载过此插件）：
-- 只需**刷新 RemNote 页面**即可（浏览器 F5 或 Cmd+R），插件会自动重新连接
+- 只需**刷新 RemNote 页面**即可（浏览器 F5 或 Cmd+R）
+
+**你必须**：执行 \`connect\` 后，**立即告知用户需要完成上述操作**，不要直接调用业务命令。引导用户完成后，用 \`health\` 确认三层就绪再继续。
+
+### Windows 注意事项
 
-**你必须这样做**：
-1. 执行 \\\`connect\\\` 后，**立即告知用户需要完成上述操作**
-2. **不要在 connect 后直接调用业务命令**——此时 Plugin 尚未连接，命令会失败
-3. 引导用户完成操作后，用 \\\`health\\\` 确认三层就绪，再执行业务命令
+- 默认模式秒级启动（预构建 plugin）
+- 端口残留：多次 connect 失败后可能 EADDRINUSE，用 \`disconnect\` 或手动终止进程后重试
+
+### 关键要点
+
+- daemon 默认 **30 分钟**无活动自动关闭，每次请求重置计时器
+- \`disconnect\` 会销毁所有缓存，之前的 read 结果全部失效
+- \`health\` 检查 daemon → Plugin → SDK 链式依赖，三者全通过才能执行业务命令
 
 ---
 
@@ -193,161 +202,191 @@ disconnect → 关闭 daemon + headless Chrome，清空所有缓存
 
 ### 场景 A：探索知识库
 
-> 用户说："帮我看看知识库里有什么"、"有哪些文档"
+> "帮我看看知识库里有什么"、"有哪些文档"
 
-使用 \\\`read_globe\\\`。它返回知识库中所有 Document 的层级结构鸟瞰图，非 Document 内容不展开。这是了解知识库整体组织的起点。拿到感兴趣的 remId 后，可以用 \\\`read_tree\\\` 深入。
+\`read_globe\` → 返回所有 Document 的层级鸟瞰图 → 拿到感兴趣的 remId 后用 \`read_tree\` 深入。
 
 ### 场景 B：搜索并深入
 
-> 用户说："搜一下关于 X 的笔记"、"找找 X 在哪里"
-
-先用 \\\`search\\\` 搜索关键词，获得匹配的 Rem 列表（含 remId）。返回结果中的 \\\`source\\\` 字段标识搜索来源：\\\`"rag"\\\` 为语义搜索（配置中启用 remnote-rag addon 时），\\\`"sdk"\\\` 为 SDK 全文搜索。RAG 模式额外返回 backText、ancestorPath、type、tags、score。然后根据需要：
-- 用 \\\`read_rem\\\` 查看某条结果的详细属性
-- 用 \\\`read_tree\\\` 展开某条结果的子树结构
+> "搜一下关于 X 的笔记"
 
-**注意**：SDK 模式下中文等无空格语言搜索效果较差。如果完整词搜索无结果，尝试用单个最具区分度的字搜索；如果仍然无果，改用 \\\`read_globe\\\` → \\\`read_tree\\\` 手动定位。RAG 模式对中文支持更好。
+\`search\` → 获得匹配 Rem 列表 → \`read_rem\`/\`read_tree\` 查看详情。
 
-### 场景 C：了解当前上下文（⚠️ 高优先级）
+**中文搜索限制**：SDK 全文搜索基于空格分词，中文等无空格语言效果差。策略：先用完整词搜索 → 无结果则用单个最具区分度的字重试 → 仍无结果则改用 \`read_globe\` → \`read_tree\` 手动定位。RAG 模式（启用 remnote-rag addon）对中文支持更好。
 
-> 用户说："我现在在看什么"、"当前页面是什么"
+### 场景 C：了解当前上下文（⚠️ 主动调用时机）
 
-**重要：用户正在看的页面对你来说是不可见的。** 用户在跟你沟通时，往往默认你也能看到他正在浏览的 RemNote 页面，但实际上你们的信息是不对等的。当你发现以下情况时，**必须主动调用 \\\`read_context\\\` 来对齐信息**：
-- 用户提到了你没有上下文的内容（如"这个"、"当前页面"、"这里"）
-- 用户的描述与你已知的信息对不上
-- 你搜索不到用户提到的某些内容
-- 用户似乎在引用他正在查看的界面
+> "我现在在看什么"、"当前页面"
 
-先用 \\\`read_context\\\` 看到用户所看到的，再做决策，沟通才能顺畅。
+**用户正在看的页面对你不可见。** 当你发现以下情况时，**必须主动调用 \`read_context\`**：
+- 用户提到"这个"、"当前页面"、"这里"等无上下文的指代
+- 用户的描述与你已知信息对不上
+- 搜索不到用户提到的内容
 
-使用 \\\`read_context\\\`：
-- **focus 模式**（默认）：以用户当前光标所在的 Rem 为中心，构建鱼眼视图——焦点处完全展开，周围递减。焦点行以 \\\`* \\\` 前缀标记。需要用户在 RemNote 中已点击某个 Rem。可通过 \\\`focusRemId\\\` 指定任意 Rem 作为鱼眼中心，此时不依赖用户焦点。
-- **page 模式**：以当前打开的页面为根，均匀展开子树。
-
-两种模式都会返回面包屑路径，帮助你理解当前位置在知识库中的层级。
+\`read_context\`：focus 模式（默认）以用户焦点为中心构建鱼眼视图；page 模式以当前页面为根展开。两者都返回面包屑路径。
 
 ### 场景 D：修改文本或属性
 
-> 用户说："把这个标题改成..."、"把类型改成概念"、"加个高亮"
-
-工作流程：**必须先 read 再 edit**。
-
-1. \\\`read_rem\\\` 获取目标 Rem 的 JSON 属性（建立缓存）
-2. 在返回的 JSON 文本中定位要修改的部分
-3. \\\`edit_rem\\\` 用 str_replace 替换：oldStr 精确匹配原文，newStr 是修改后的文本
-
-str_replace 操作的是 \\\`JSON.stringify(remObject, null, 2)\\\` 格式化文本。oldStr 要包含足够上下文（如字段名 + 值），避免模糊匹配。替换后必须是合法 JSON。
-
-**RichText 编辑要点**（\\\`text\\\` 和 \\\`backText\\\` 字段）：
-
-RichText 在格式化 JSON 中是多行结构，对象内 key 按**字母序**排列（\\\`_id\\\` 排最前，因为 \\\`_\\\` < \\\`a\\\`）。
+> "把标题改成..."、"改成概念"、"加个高亮"
 
-示例——将纯文本改为粗体：
+\`read_rem\` → 确认当前属性 → \`edit_rem\` 传入 changes 对象。只需包含要修改的字段，未提及字段保持不变。
 
-\\\`\\\`\\\`
-oldStr:  "text": [\\n    "普通标题"\\n  ]
-newStr:  "text": [\\n    {\\n      "b": true,\\n      "i": "m",\\n      "text": "粗体标题"\\n    }\\n  ]
-\\\`\\\`\\\`
+**注意**：\`read_rem\` 默认模式启用 Token Slimming——省略处于默认值的字段，未返回的字段即默认值（如 type 未显示 = "default"，isTodo 未显示 = false，tags 未显示 = []）。需要完整字段用 \`full=true\`。
 
-示例——给文本加超链接：
+> **批量修改多个节点时**：改用 \`read_rem_in_tree\` 一次性获取全部节点属性，避免逐个 read_rem。详见场景 D2。
 
-\\\`\\\`\\\`
-oldStr:  "text": [\\n    "点击访问官网"\\n  ]
-newStr:  "text": [\\n    "点击",\\n    {\\n      "i": "m",\\n      "iUrl": "https://remnote.com",\\n      "text": "访问官网"\\n    }\\n  ]
-\\\`\\\`\\\`
+#### edit_rem changes 示例
 
-### ⚠️ highlightColor vs h — 两种完全不同的高亮
+\`\`\`jsonc
+// 修改类型
+changes: { "type": "concept" }
+// 设置整行高亮背景色
+changes: { "highlightColor": "Yellow" }
+// 粗体文本（RichText 数组）
+changes: { "text": [{"b": true, "i": "m", "text": "粗体标题"}] }
+// 超链接（注意用 iUrl 不是 url）
+changes: { "text": ["点击", {"i": "m", "iUrl": "https://remnote.com", "text": "访问官网"}] }
+// 文字颜色（tc 是数字，RemColor 枚举）
+changes: { "text": [{"i": "m", "tc": 1, "text": "红色文字"}] }
+// 批量修改多个字段
+changes: { "type": "concept", "highlightColor": "Yellow", "fontSize": "H1" }
+\`\`\`
 
-这是最常见的混淆点，必须区分：
+#### highlightColor（Rem 级别）vs h（RichText 行内）
 
 | 属性 | 位置 | 值类型 | 效果 | 修改方式 |
 |:-----|:-----|:-------|:-----|:---------|
-| \\\`highlightColor\\\` | RemObject 顶层字段 | 字符串 \\\`"Red"\\\`/\\\`"Yellow"\\\` 等，或 \\\`null\\\` | 整行背景色（左侧彩色竖条） | str_replace 顶层字段 |
-| \\\`h\\\` | RichText 元素内部 | 数字 0-9 | 文字片段的荧光底色 | str_replace text 数组内的对象 |
+| \`highlightColor\` | RemObject 顶层 | 字符串 \`"Red"\`/\`"Yellow"\` 等或 \`null\` | 整行背景色 | changes 直接设置 |
+| \`h\` | RichText 元素内 | 数字 0-9（RemColor 枚举） | 文字片段荧光底色 | changes.text 整体替换 |
 
-**RichText \\\`h\\\` 颜色值对照表**（必须用数字，不是字符串）：
+两者完全独立，互不影响。
+
+#### RichText h 颜色值对照表
 
 | 值 | 颜色 | 值 | 颜色 | 值 | 颜色 |
 |:---|:-----|:---|:-----|:---|:-----|
-| 0 | 无（默认） | 4 | Green | 7 | Gray |
+| 0 | 无/默认 | 4 | Green | 7 | Gray |
 | 1 | Red | 5 | Purple | 8 | Brown |
 | 2 | Orange | 6 | Blue | 9 | Pink |
 | 3 | Yellow | — | — | — | — |
 
-### 常见属性修改速查（edit_rem str_replace 模板）
+#### 特殊字段处理规则
 
-以下模板基于 \\\`JSON.stringify(obj, null, 2)\\\` 的缩进格式。**oldStr/newStr 必须包含精确的缩进空格**。
+- **tags / sources**：传入**目标 ID 数组**，系统自动计算 diff（逐项 add/remove），不是整体替换。必须列出完整目标数组，缺少的 ID 会被删除
+- **backText**：\`null\` → 清除背面（调用 \`setBackText([])\`）；传 RichText 数组设置背面内容；裸字符串自动包装为 \`[string]\`
+- **parent + positionAmongstSiblings**：共享同一 SDK 调用 \`setParent(parentId, position)\`，应在同一次 changes 中同时修改
+- **portalDirectlyIncludedRem**：仅 type=portal 的 Rem 可修改，传目标 ID 数组，系统自动 diff（逐项 addToPortal/removeFromPortal）
+- **highlightColor**：\`null\` → 调用 \`removePowerup('h')\`（SDK 不接受 null）
+- **fontSize**：\`null\` → 调用 \`setFontSize(undefined)\`（恢复普通大小）
+- **todoStatus**：依赖 \`isTodo=true\` 才生效；清除 todo 应设 \`isTodo=false\`
+- **type**：不可设为 \`portal\`（Portal 只能通过 SDK \`createPortal()\` 或 edit_tree \`<!--portal-->\` 创建）
 
-**① 设置/清除整行背景色（highlightColor）**
+### 场景 D2：批量读取 + 标注（课本划重点）
 
-\\\`\\\`\\\`
-// 设置为黄色背景
-oldStr:  "highlightColor": null
-newStr:  "highlightColor": "Yellow"
+> "帮我标注这些笔记的重点"、"给关键词加高亮"、"批量修改格式"
 
-// 清除背景色
-oldStr:  "highlightColor": "Yellow"
-newStr:  "highlightColor": null
-\\\`\\\`\\\`
+当需要读取一棵子树并对**多个节点**进行属性或富文本修改时，使用 \`read_rem_in_tree\` 一次性获取全部信息：
 
-**② 给文字加荧光底色（RichText h 字段）**
+\`read_rem_in_tree\` → 同时获取大纲 + 每个节点的 RemObject（含完整 RichText）
+  ↓
+对目标节点直接调用 \`edit_rem\`（rem 缓存已就绪，无需再逐个 read_rem）
+  +
+如需结构变更，直接调用 \`edit_tree\`（tree 缓存已就绪，无需再 read_tree）
 
-先 read_rem 找到 text 数组中目标文字对象的精确格式，然后替换 h 值。
+**为什么不用 read_tree + N×read_rem？** \`read_rem_in_tree\` 一次调用建立双重缓存，省去 N+1 次网络往返。对 30+ 节点的子树，差异是 1 次调用 vs 31+ 次调用。
 
-\\\`\\\`\\\`
-// "Todo List" 文字加黄色荧光（h: 0 → 3）
-// ⚠️ 只替换包含目标文字的那一行 h 值，用上下文确保唯一匹配
-oldStr:       "h": 0,\\n      "i": "m",\\n      "text": "Todo List "
-newStr:       "h": 3,\\n      "i": "m",\\n      "text": "Todo List "
+**注意**：\`read_rem_in_tree\` 默认 maxNodes=50（每节点需 40+ SDK 调用），大子树需显式设置 maxNodes。
 
-// 去掉荧光（h: 3 → 0）
-oldStr:       "h": 3,\\n      "i": "m",\\n      "text": "Todo List "
-newStr:       "h": 0,\\n      "i": "m",\\n      "text": "Todo List "
-\\\`\\\`\\\`
+### 场景 E：修改结构（新增/删除/移动/重排）
 
-**⚠️ 关键要点**：oldStr 中必须包含足够的上下文（如 \\\`"i": "m"\\\` 和 \\\`"text": "..."\\\`）来唯一定位。不能只写 \\\`"h": 0\\\` — 可能匹配到多处。
+> "在这下面加几个子项"、"删掉这个"
 
-**③ 修改 Rem 类型**
+\`read_tree\` → 查看大纲 → \`edit_tree\` 用 str_replace 修改。
 
-\\\`\\\`\\\`
-// 普通 → 概念
-oldStr:  "type": "default"
-newStr:  "type": "concept"
-\\\`\\\`\\\`
+**关键红线**：
+- edit_tree **禁止修改行内容**（改内容用 edit_rem）
+- 新增行必须插在兄弟**末尾**，不能插在有子节点的 Rem 和其 children 之间（否则触发 \`children_captured\`）
 
-**④ 修改文字颜色（RichText tc 字段）**
+#### 新增行格式说明
 
-\\\`\\\`\\\`
-// 加红色文字颜色（与 h 类似，tc 也是数字 0-9）
-oldStr:       "i": "m",\\n      "text": "重要内容"
-newStr:       "i": "m",\\n      "tc": 1,\\n      "text": "重要内容"
-\\\`\\\`\\\`
+新增行（无 remId 注释的行）支持以下格式：
 
-### 缓存行为速查
+**Markdown 前缀**：\`# \` \`## \` \`### \` \`- [ ] \` \`- [x] \` \\\`code\\\` \`---\`
 
-| 工具 | 缓存行为 | 用途 |
-|:-----|:---------|:-----|
-| \\\`read_rem\\\` | 写入缓存 | 供 \\\`edit_rem\\\` 使用 |
-| \\\`read_tree\\\` | 写入缓存 | 供 \\\`edit_tree\\\` 使用 |
-| \\\`search\\\` / \\\`read_globe\\\` / \\\`read_context\\\` | **不缓存** | 不能作为 edit 前置 |
+**箭头分隔符**：
+- 单行：\`→\`（forward）\`←\`（backward）\`↔\`（both）——格式 \`text → backText\`
+- 多行：\`↓\`（forward）\`↑\`（backward）\`↕\`（both）——子行自动成为答案
 
-### 场景 E：修改结构（新增/删除/移动/重排）
+**元数据注释**（可选，行尾追加）：
+- \`<!--type:concept-->\` \`<!--type:descriptor-->\` \`<!--doc-->\`
+- \`<!--tag:标签名(tagId)-->\`（可多个，空格分隔）
+- 可组合：\`<!--type:concept doc tag:数学(tag01)-->\`
+
+**Portal 新增**：
+- \`<!--portal refs:id1,id2-->\`（创建并引用指定 Rem）
+- \`<!--portal-->\`（创建空 Portal）
+
+#### str_replace 构造示例
+
+**示例 1：在末尾新增行**
+\`\`\`
+oldStr:
+  最后一个兄弟 <!--idZ-->
+newStr:
+  最后一个兄弟 <!--idZ-->
+  新增行
+\`\`\`
+
+**示例 2：删除一个带子节点的行（必须一起删）**
+\`\`\`
+oldStr:
+  子节点 A <!--idA-->
+    孙节点 A1 <!--idA1-->
+  子节点 B <!--idB-->
+newStr:
+  子节点 B <!--idB-->
+\`\`\`
 
-> 用户说："在这下面加几个子项"、"删掉这个"、"把这个移到那下面"
+**示例 3：创建多行闪卡**
+\`\`\`
+oldStr:
+  子节点 A <!--idA-->
+newStr:
+  什么是线性回归？ ↓
+    一种基本的回归分析方法
+    假设因变量与自变量呈线性关系
+  子节点 A <!--idA-->
+\`\`\`
 
-工作流程：**必须先 read_tree 再 edit_tree**。
+#### 行引用模板 \`{{remId}}\`
 
-1. \\\`read_tree\\\` 获取目标区域的 Markdown 大纲（建立缓存）
-2. 在大纲中用 str_replace 进行结构修改：
-   - **新增**：插入无 remId 注释的新行（通过缩进确定父子关系）。可在行尾加元数据注释指定属性：\\\`新行 <!--type:concept doc tag:Name(id)-->\\\`
-   - **删除**：移除带 remId 的行（必须同时删除所有子行）
-   - **移动**：改变行的缩进级别或位置
-   - **重排**：调换同级行的顺序
+在 oldStr/newStr 中使用 \`{{remId}}\` 引用缓存大纲中已有行的完整内容（不含缩进）。系统在 str_replace 前自动展开。
 
-**红线**：edit_tree **禁止修改已有行的文字内容**——改内容必须用 edit_rem。edit_tree 只做结构操作。
+**优势**：避免抄写完整行内容（remId、元数据标记），减少 token 浪费和复制错误。
 
-**⚠️ 新增行的插入位置**：新行必须插在目标层级所有兄弟的**末尾**，不能插在一个有子节点的 Rem 和它的 children 之间。否则 children 会被新行"劫持"，触发 \\\`children_captured\\\` 错误。
+**示例：重排两个节点**
+\`\`\`
+// 不用模板：
+oldStr: "    动态数组 <!--id1_1 type:concept-->\\n    静态数组 <!--id1_2 type:concept-->"
+newStr: "    静态数组 <!--id1_2 type:concept-->\\n    动态数组 <!--id1_1 type:concept-->"
 
-\\\`\\\`\\\`
+// 用模板：
+oldStr: "    {{id1_1}}\\n    {{id1_2}}"
+newStr: "    {{id1_2}}\\n    {{id1_1}}"
+\`\`\`
+
+**规则**：
+- \`{{remId}}\` 展开为**不含缩进**的完整行内容，缩进由你控制
+- 只匹配纯字母数字（\`[a-zA-Z0-9]+\`），与 RemNote cloze 语法 \`{{text}}\` 不冲突（cloze 含中文/空格/标点，不会被匹配）
+- 匹配到但不在缓存大纲中的 \`{{xxx}}\` 原样保留（可能是 cloze），并输出 warning
+- 新增行不能用 \`{{}}\`（新增行没有 remId）
+- 可以混用：部分行用 \`{{id}}\`，部分行手动写
+
+#### ⚠️ children_captured 详解
+
+在有子节点的 Rem 和其 children 之间插入新行，会导致新行"劫持"已有 children：
+
+\`\`\`
 ❌ 错误：插在父 Rem 和 children 之间
 oldStr:   水分子 ↓ <!--idA-->
 newStr:   水分子 ↓ <!--idA-->
@@ -357,57 +396,46 @@ newStr:   水分子 ↓ <!--idA-->
 oldStr:   最后一个兄弟 <!--idZ-->
 newStr:   最后一个兄弟 <!--idZ-->
           新行
-\\\`\\\`\\\`
+\`\`\`
+
+#### 创建新节点并移动已有 children
 
-**需要"创建新节点并把已有 children 移过去"？** 分两步：
-1. 第一次 \\\`edit_tree\\\`：在末尾创建新节点（获得 remId）
-2. 第二次 \\\`edit_tree\\\`：把已有行移动到新节点下面（此时新节点已有 remId，走正常 move 逻辑）
+当需要在已有 children 的 Rem 下插入一个新的中间层时，不能一步完成（否则触发 children_captured）。正确做法是**两步**：
 
-### 场景 F：创建 / 修改闪卡
+1. 先在大纲**末尾**新增节点（避免劫持）
+2. 再发一次 \`edit_tree\`，将已有 children 移动到新节点下（通过调整缩进实现移动）
 
-> 用户说："创建一个概念定义"、"做个正向问答卡"、"把这个改成 concept"
+### 场景 F：创建/修改闪卡
 
-闪卡由 \\\`type\\\`、\\\`backText\\\`、\\\`practiceDirection\\\` 三个字段控制。操作方式：
+> "创建概念定义"、"做个正向问答卡"
 
-**创建新闪卡**（\\\`edit_tree\\\` 新增行 + 箭头 + 可选元数据注释）：
-- 正向问答：\\\`问题 → 答案\\\`
-- 双向问答：\\\`问题 ↔ 答案\\\`
-- 多行答案：\\\`问题 ↓\\\`（子行自动成为答案）
-- 概念定义：\\\`概念 ↔ 定义 <!--type:concept-->\\\`（一步完成，无需再 edit_rem）
-- 描述属性：\\\`属性 → 值 <!--type:descriptor-->\\\`
+**创建新闪卡**（\`edit_tree\` 新增行 + 箭头 + 可选元数据注释）：
+- 正向：\`问题 → 答案\`
+- 双向：\`问题 ↔ 答案\`
+- 多行：\`问题 ↓\`（子行自动成为答案）
+- 概念定义：\`概念 ↔ 定义 <!--type:concept-->\`（一步完成）
+- 描述属性：\`属性 → 值 <!--type:descriptor-->\`（与 Concept 配合使用）
 
-**修改现有 Rem 的闪卡行为**（\\\`read_rem\\\` → \\\`edit_rem\\\`）：
-- 改类型：修改 \\\`type\\\` 字段（\\\`"default"\\\` → \\\`"concept"\\\`）
-- 改方向：修改 \\\`practiceDirection\\\`（\\\`"forward"\\\` / \\\`"backward"\\\` / \\\`"both"\\\` / \\\`"none"\\\`）
-- 加/改背面：修改 \\\`backText\\\` 字段
+**Concept vs Descriptor 使用场景**：
+- Concept（概念定义）：独立的核心概念，回答"X 是什么？"——如"线性回归 ↔ 最基本的回归模型"
+- Descriptor（描述属性）：作为某个 Concept 的子 Rem，回答"X 的 Y 是什么？"——如"假设 → 因变量与自变量呈线性关系"
+- 通常 Descriptor 是 Concept 的直接子节点，二者配合构成完整的 CDF 知识结构
 
-**禁止**：在文本内容中插入 \\\`::\\\`、\\\`;;\\\`、\\\`>>\\\` 等分隔符——这些是 RemNote 编辑器语法，工具端不识别。
+**修改现有 Rem 的闪卡行为**（\`read_rem\` → \`edit_rem\`）：修改 \`type\`、\`practiceDirection\`、\`backText\` 字段。
 
 ### 场景 G：排查连接问题
 
-> 用户说："连不上"、"命令报错了"
+\`health\` 默认查询所有活跃实例的三层状态（daemon / Plugin / SDK），返回 \`instances\` 数组。有 \`--instance\` 或 \`--headless\` 时只查询指定实例。每个实例的 \`plugin.isTwin\` 标记是否为孪生连接。
 
-使用 \\\`health\\\` 检查三层状态（多实例时指定 instance），然后对症处理：
-- daemon 未运行 → 执行 \\\`connect\\\`，然后引导用户在 RemNote 中加载插件
-- Plugin 未连接 → 提醒用户：首次使用需在 RemNote 的「开发你的插件」中填入对应 Plugin 服务地址（如 \\\`http://localhost:29101\\\`）；非首次使用只需刷新 RemNote 页面
-- SDK 未就绪 → 等待几秒后重试 health
+故障定位：无活跃实例 → \`connect\`；Plugin 未连接 → 引导用户操作 RemNote（或使用 headless 模式）；SDK 未就绪 → 等待重试。
 
 ### 场景 H：管理增强项目
 
-> 用户说："安装语义搜索"、"配置 RAG"
-
-使用 \\\`addon\\\` 工具管理增强项目：
-- \\\`addon(action="list")\\\` — 查看所有可用增强项目及状态
-- \\\`addon(action="install", name="remnote-rag")\\\` — 安装指定增强项目
-- \\\`addon(action="uninstall", name="remnote-rag")\\\` — 卸载指定增强项目
-
-安装后需在配置页面中填写必需的配置项（如 API Key）。
+\`addon\`：\`action="list"\` 查看状态、\`action="install"\` 安装、\`action="uninstall"\` 卸载。
 
 ### 场景 I：重置环境
 
-> 用户说："全部清理"、"重新开始"
-
-使用 \\\`clean\\\` 工具彻底清理所有 daemon 进程、PID 文件、注册表和 addon 数据。清理后需重新 \\\`connect\\\`。
+\`clean\` 彻底清理所有 daemon 进程、PID 文件、注册表和 addon 数据。清理后需重新 \`connect\`。
 
 ---
 
@@ -415,88 +443,223 @@ newStr:   最后一个兄弟 <!--idZ-->
 
 ### 黄金法则：先 read 再 edit
 
-- \\\`edit_rem\\\` 前必须先 \\\`read_rem\\\` 同一个 remId
-- \\\`edit_tree\\\` 前必须先 \\\`read_tree\\\` 同一个 remId
+- \`edit_rem\` 前必须先 \`read_rem\` 或 \`read_rem_in_tree\` 同一个 remId
+- \`edit_tree\` 前必须先 \`read_tree\` 或 \`read_rem_in_tree\` 同一个 remId
+- \`read_rem_in_tree\` 同时建立两种缓存，调用后可直接 \`edit_tree\` 和 \`edit_rem\`
+- \`search\`/\`read_globe\`/\`read_context\` **不写入缓存**，不能作为 edit 前置
 
-跳过 read 直接 edit 会被拒绝。这不是建议，是硬性要求。
+跳过 read 直接 edit 会被拒绝（硬性要求）。
 
-### 三道防线
+### 两道防线
 
-每次 edit 操作都经过三重安全检查：
 1. **缓存存在**：必须有对应的 read 缓存
-2. **并发检测**：edit 时重新读取最新数据，与缓存比较。如果 Rem 在 read 之后被外部修改，拒绝编辑——你必须重新 read
-3. **精确匹配**：oldStr 必须在目标文本中恰好匹配 1 次
+2. **并发检测**：edit 时重新读取最新数据与缓存比较，Rem 被外部修改则拒绝——必须重新 read
 
 ### edit_tree 禁止事项
 
-- 禁止修改已有行的文字内容（改内容用 edit_rem）
-- 禁止删除根节点
-- 禁止删除有隐藏子节点的行（先用更大 depth 重新 read_tree）
-- 禁止删除父行但保留子行（必须一起删）
-- 禁止修改或删除省略占位符（先用更大参数重新 read_tree 展开）
-
-详细规则见各工具的 description。
+- \`content_modified\`：修改已有行内容 → 用 edit_rem
+- \`root_modified\`：删除/修改根节点
+- \`folded_delete\`：删除有隐藏子节点的行 → 更大 depth 重新 read_tree
+- \`orphan_detected\`：删父留子 → 必须一起删
+- \`elided_modified\`：修改/删除省略占位符 → 更大参数重新 read_tree
+- \`children_captured\`：新行劫持已有子节点 → 插在兄弟末尾
+- \`indent_skip\`：缩进跳级 → 每级 2 空格
+
+### 缓存行为速查表
+
+| 场景 | 缓存行为 | 重试策略 |
+|:-----|:---------|:---------|
+| edit_rem 写入成功 | 从 Plugin 重新读取 → 更新缓存 | 可继续编辑 |
+| edit_rem 防线拒绝/部分失败 | 不更新缓存 | 必须重新 read_rem |
+| edit_tree 成功 | 自动 re-read → 更新缓存 | 可连续 edit |
+| edit_tree 防线 3 拒绝（str_replace 不匹配等） | 缓存保持不变 | 调整 oldStr/newStr 后直接重试 |
+| edit_tree 执行中异常 | 已执行操作保留（**无回滚**），不更新缓存 | 必须重新 read_tree |
+| 枚举值非法（edit_rem） | 报错拒绝，缓存不变 | 检查允许的值范围后重试 |
+
+### 可写字段列表（21 个）
+
+\`\`\`
+text, backText, type, isDocument, parent,
+fontSize, highlightColor,
+isTodo, todoStatus, isCode, isQuote, isListItem, isCardItem, isSlot, isProperty,
+enablePractice, practiceDirection,
+tags, sources, positionAmongstSiblings, portalDirectlyIncludedRem
+\`\`\`
+
+### 枚举约束速查
+
+| 字段 | 允许的值 |
+|:-----|:---------|
+| \`type\` | \`concept\` / \`descriptor\` / \`default\`（\`portal\` 不可设置） |
+| \`practiceDirection\` | \`forward\` / \`backward\` / \`both\` / \`none\` |
+| \`highlightColor\` | \`Red\` / \`Orange\` / \`Yellow\` / \`Green\` / \`Blue\` / \`Purple\` / \`Gray\` / \`Brown\` / \`Pink\` / \`null\` |
+| \`fontSize\` | \`H1\` / \`H2\` / \`H3\` / \`null\` |
+| \`todoStatus\` | \`Finished\` / \`Unfinished\` / \`null\`（需先 \`isTodo=true\`） |
 
 ---
 
 ## 5. Output Format Quick Reference
 
-\\\`read_tree\\\`、\\\`read_globe\\\`、\\\`read_context\\\` 返回 Markdown 大纲格式。
+\`read_tree\`、\`read_globe\`、\`read_context\` 返回 Markdown 大纲。
 
 ### 行结构
 
-\\\`\\\`\\\`
-{缩进}{Markdown 前缀}{内容}{箭头}{backText} <!-- {remId} {标记} -->
-\\\`\\\`\\\`
+\`\`\`
+{缩进}{前缀}{内容}{箭头}{backText} <!-- {remId} {标记} -->
+\`\`\`
 
 - 缩进：每级 2 空格
-- Markdown 前缀：\\\`# \\\`(H1)、\\\`## \\\`(H2)、\\\`### \\\`(H3)、\\\`- [ ] \\\`(待办)、\\\`- [x] \\\`(已完成)、\\\`\\\\\\\`\\\`(代码)
+- 前缀：\`# \`(H1)、\`## \`(H2)、\`### \`(H3)、\`- [ ] \`(待办)、\`- [x] \`(已完成)、\\\`...\\\`(代码)、\`---\`(分隔线)
 
-### 关键元数据标记
+### 元数据标记
 
 | 标记 | 含义 |
 |:-----|:-----|
-| \\\`type:concept\\\` / \\\`type:descriptor\\\` / \\\`type:portal\\\` | Rem 类型（default 不标记） |
-| \\\`doc\\\` | 是文档页面 |
-| \\\`children:N\\\` | 有 N 个未展开的子节点 |
-| \\\`tag:Name(id)\\\` | 已附加的标签 |
-| \\\`role:card-item\\\` | 多行闪卡的答案行 |
-| \\\`top\\\` | 知识库顶层 Rem |
+| \`type:concept\` / \`type:descriptor\` / \`type:portal\` | Rem 类型（default 不标记） |
+| \`doc\` | 是文档页面 |
+| \`top\` | 知识库顶层 Rem |
+| \`children:N\` | 有 N 个未展开的子节点 |
+| \`role:card-item\` | 多行闪卡答案行 |
+| \`tag:Name(id)\` | 已附加的标签 |
+| \`refs:id1,id2\` | Portal 引用的 Rem ID |
 
 ### 箭头含义
 
-- **单行箭头** \\\`→\\\` \\\`←\\\` \\\`↔\\\`：text 与 backText 之间的分隔，方向为 practiceDirection
-- **多行箭头** \\\`↓\\\` \\\`↑\\\` \\\`↕\\\`：表示子节点为答案的多行闪卡
+| 箭头 | practiceDirection | 格式 |
+|:-----|:------------------|:-----|
+| \`→\` \`←\` \`↔\` | forward / backward / both | \`text → backText\`（单行） |
+| \`↓\` \`↑\` \`↕\` | forward / backward / both | \`text ↓\` 或 \`text ↓ backText\`（多行，子行为答案） |
 
 ### 省略占位符
 
-\\\`\\\`\\\`
-<!--...elided 3 siblings (parent:remIdB range:2-4 total:5)-->
-<!--...elided >=10 nodes (parent:remIdB range:5-14 total:20)-->
-\\\`\\\`\\\`
+\`\`\`
+<!--...elided 3 siblings (parent:id range:2-4 total:5)-->       精确省略（超 maxSiblings）
+<!--...elided >=10 nodes (parent:id range:5-14 total:20)-->     非精确省略（maxNodes 耗尽）
+\`\`\`
+
+精确省略保留前 70% + 后 30%。**省略占位符不可删除或修改**。
+
+### edit_tree 新增行格式
+
+新增行（无 remId 注释的行）在 newStr 中出现时，会被创建为新的 Rem。格式选项：
+
+- 纯文本行：\`新内容\`
+- 带前缀：\`# 新标题\`、\`- [ ] 新待办\`
+- 带箭头：\`问题 → 答案\`、\`概念 ↔ 定义\`、\`题目 ↓\`
+- 带元数据注释（metadata-only，无 remId）：\`新行 <!--type:concept doc-->\`
+- Portal 行：\`<!--portal refs:id1,id2-->\`
+- 嵌套新增（父+子一起创建）：
+  \`\`\`
+  新父节点 ↓
+    新子行 1
+    新子行 2
+  \`\`\`
+
+### 完整示例大纲
+
+\`\`\`markdown
+# 数据结构 <!--kLr type:concept doc top-->
+  ## 线性结构 <!--ABC type:concept-->
+    数组 → Array <!--DEF-->
+    链表 ↓ <!--GHI type:concept-->
+      单向链表 <!--JKL role:card-item-->
+      双向链表 <!--MNO role:card-item-->
+    - [x] 复习完成 <!--PQR-->
+  ## 树结构 <!--VWX type:concept children:8-->
+  <!--...elided 3 siblings (parent:kLr range:3-5 total:6)-->
+  嵌入视图 <!--p01 type:portal refs:ref1,ref2-->
+  重要概念 <!--QRS tag:数学(tag01) tag:基础(tag02)-->
+\`\`\`
+
+---
+
+## 6. RichText 格式参考
+
+\`text\` 和 \`backText\` 字段是 JSON 数组（RichText），元素为纯字符串或格式化对象。
+
+### 元素类型表
+
+| \`i\` 值 | 含义 | 必填字段 | 可选字段 |
+|:---------|:-----|:---------|:---------|
+| （纯 string） | 纯文本片段 | — | — |
+| \`"m"\` | 带格式文本 | \`text\` | \`b\`, \`l\`, \`u\`, \`h\`, \`tc\`, \`q\`, \`code\`, \`language\`, \`cId\`, \`iUrl\` |
+| \`"q"\` | Rem 引用 | \`_id\` | \`content\`, \`showFullName\`, \`aliasId\` |
+| \`"i"\` | 图片 | \`url\` | \`width\`, \`height\`, \`percent\`(25/50/100) |
+| \`"x"\` | LaTeX | \`text\` | \`block\`(true=块级公式) |
+| \`"a"\` | 音频/视频 | \`url\`, \`onlyAudio\`(**必填**) | \`width\`, \`height\` |
+| \`"s"\` | 卡片分隔符 | — | \`delimiterCharacterForSerialization\` |
+
+### 格式标记表（\`i:"m"\` 主要，但 \`i:"q"\` 等也支持部分标记）
+
+| 字段 | 类型 | 含义 |
+|:-----|:-----|:-----|
+| \`b\` | \`true\` | 加粗 |
+| \`l\` | \`true\` | 斜体（小写 L，不是大写 I） |
+| \`u\` | \`true\` | 下划线 |
+| \`h\` | number | 高亮颜色（RemColor 0-9） |
+| \`tc\` | number | 文字颜色（RemColor 0-9） |
+| \`q\` | \`true\` | 行内代码（红色等宽样式） |
+| \`code\` | \`true\` | 代码块（带语言标签和复制按钮） |
+| \`language\` | string | 代码语言（如 \`"python"\`） |
+| \`cId\` | string | 完形填空 ID |
+| \`hiddenCloze\` | \`true\` | 完形填空隐藏状态 |
+| \`iUrl\` | string | 超链接 URL（**不是 \`url\`！**） |
+| \`qId\` | string | 行内引用的 Rem ID |
+
+### RemColor 颜色枚举（\`h\` 和 \`tc\` 共用）
+
+| 值 | 颜色 | 值 | 颜色 | 值 | 颜色 |
+|:---|:-----|:---|:-----|:---|:-----|
+| 0 | 无/默认 | 4 | Green | 7 | Gray |
+| 1 | Red | 5 | Purple | 8 | Brown |
+| 2 | Orange | 6 | Blue | 9 | Pink |
+| 3 | Yellow | — | — | — | — |
+
+### 常用构造示例（key 字母序排列）
+
+\`\`\`jsonc
+{"b": true, "i": "m", "text": "粗体"}                    // 粗体
+{"i": "m", "q": true, "text": "code"}                    // 行内代码
+{"i": "m", "iUrl": "https://...", "text": "链接"}         // 超链接（iUrl 不是 url！）
+{"b": true, "h": 1, "i": "m", "text": "重点"}            // 粗体+红色高亮
+{"cId": "c1", "i": "m", "text": "答案"}                   // 完形填空
+{"_id": "remId", "b": true, "i": "q"}                    // Rem 引用加粗
+{"i": "x", "text": "E = mc^2"}                           // LaTeX
+{"i": "a", "onlyAudio": false, "url": "..."}             // 视频（onlyAudio 必填！）
+{"i": "a", "onlyAudio": true, "url": "..."}              // 音频
+\`\`\`
 
-\\\`siblings\\\` 为精确省略（超 maxSiblings），\\\`>=N nodes\\\` 为预算耗尽的非精确省略。
+### ⚠️ 关键陷阱
 
-详细格式规范见 \\\`resource://outline-format\\\`。
+- \`i:"a"\` 的 \`onlyAudio\` 是**必填**字段（\`true\`=音频，\`false\`=视频），缺少会导致 SDK 拒绝写入
+- 超链接必须用 \`iUrl\`，\`url\` 字段已废弃无效
+- RichText 对象内部按 **key 字母序排列**（\`_id\` < \`b\` < \`cId\` < \`h\` < \`i\` < \`iUrl\` < \`text\`），确保序列化一致性
+- \`highlightColor\`（RemObject 顶层，字符串 \`"Red"\`）与 \`h\`（RichText 内部，数字 \`1\`）完全独立——前者是整行背景色，后者是文字片段荧光底色
+- 防线 2（乐观并发检测）依赖 key 字母序的确定性序列化来比较缓存与最新数据
 
 ---
 
-## 6. Error Quick Reference
-
-| 错误信息 | 原因 | 恢复操作 |
-|:---------|:-----|:---------|
-| 守护进程未运行 | 未 connect 或 daemon 已超时 | 执行 \\\`connect\\\` |
-| Plugin 未连接 | RemNote 未打开或插件未加载 | 提醒用户打开 RemNote |
-| has not been read yet | 未先执行 read | 先 read 同一个 remId，再重试 edit |
-| has been modified since last read | Rem 在 read 后被外部修改 | 重新 read 获取最新状态，再重试 |
-| old_str not found | oldStr 在文本中不存在 | 检查是否精确匹配（含引号、空格、换行） |
-| old_str matches N locations | oldStr 匹配多处 | 扩大 oldStr 范围，包含更多上下文以唯一定位 |
-| invalid JSON | edit_rem 替换后不是合法 JSON | 检查 newStr 的引号、逗号、括号 |
-| Content modification not allowed | edit_tree 中修改了行内容 | 改用 \\\`edit_rem\\\` 修改内容 |
-| orphan_detected | 删了父行但保留了子行 | 同时删除所有子行 |
-| folded_delete | 删除有隐藏子节点的行 | 用更大 depth 重新 read_tree |
-| children_captured | 新行插在父 Rem 和它的 children 之间，劫持了已有子节点 | 把新行插到所有兄弟的**末尾**而非紧跟父 Rem 之后（见下方说明） |
-| focusRemId 仅在 focus 模式下有效 | page 模式下不应传 focusRemId | 去掉 focusRemId 参数，或改用 focus 模式 |
-
-完整错误参考见 \\\`resource://error-reference\\\`。
+## 7. Error Quick Reference
+
+### 诊断决策树
+
+\`\`\`
+命令报错
+├─ "守护进程未运行" → connect 未执行或 daemon 已超时 → 执行 connect
+├─ "Plugin 未连接" → RemNote 未打开或插件未加载 → 引导用户操作 RemNote
+├─ "SDK 未就绪" → 知识库尚未加载 → 等待并重试 health
+├─ "has not been read yet" → 未先 read → 执行对应 read 后重试
+├─ "has been modified since last read" → 被外部修改 → 必须重新 read（不可直接重试）
+├─ "Invalid value" → 枚举字段值不合法 → 检查允许的值范围
+├─ "old_str not found" → oldStr 不精确 → 检查缩进、空格、换行
+├─ "old_str matches N locations" → oldStr 不够具体 → 扩大范围包含更多上下文
+├─ "content_modified" → edit_tree 中改了行内容 → 用 edit_rem
+├─ "orphan_detected" → 删了父但留了子 → 同时删除所有子行
+├─ "folded_delete" → 删了有隐藏子节点的行 → 更大 depth 重新 read_tree
+├─ "elided_modified" → 删/改了省略占位符 → 更大参数重新 read_tree
+├─ "children_captured" → 新行劫持已有子节点 → 新行插到兄弟末尾
+├─ "indent_skip" → 缩进跳级 → 每级 2 空格不可跳级
+├─ "Rem not found" → remId 无效或已删除 → 用 search 重新定位
+└─ "focusRemId 仅在 focus 模式下有效" → page 模式不支持 → 去掉参数或改用 focus 模式
+\`\`\`
 `;