remnote-bridge 0.1.2 → 0.1.3

package/README.md

@@ -35,6 +35,8 @@ Add the following to your AI client's MCP settings:
 }
 ```
 
+**Tip: Install both for best results.** MCP documentation is kept concise (loaded all at once), while Skill documentation is detailed (loaded on demand). Together they complement each other. That said, either one works independently — you don't need both.
+
 Once connected, the AI will guide you through connecting to RemNote, loading the plugin, and everything else.
 
 ---

package/dist/cli/main.js

@@ -53,7 +53,7 @@ function parseJsonInput(command, jsonStr, requiredFields = []) {
 program
     .name('remnote-bridge')
     .description('RemNote Bridge — CLI + MCP Server + Plugin')
-    .version('0.1.2')
+    .version('0.1.3')
     .option('--json', '以 JSON 格式输出（适用于程序化调用）');
 program
     .command('connect')

package/dist/mcp/index.js

@@ -11,13 +11,14 @@ import { registerEditTools } from './tools/edit-tools.js';
 import { registerInfraTools } from './tools/infra-tools.js';
 import { OUTLINE_FORMAT_CONTENT } from './resources/outline-format.js';
 import { REM_OBJECT_FIELDS_CONTENT } from './resources/rem-object-fields.js';
+import { EDIT_REM_GUIDE_CONTENT } from './resources/edit-rem-guide.js';
 import { EDIT_TREE_GUIDE_CONTENT } from './resources/edit-tree-guide.js';
 import { ERROR_REFERENCE_CONTENT } from './resources/error-reference.js';
 import { SEPARATOR_FLASHCARD_CONTENT } from './resources/separator-flashcard.js';
 export async function startMcpServer() {
     const server = new FastMCP({
         name: 'remnote-bridge',
-        version: '0.1.2',
+        version: '0.1.3',
         instructions: SERVER_INSTRUCTIONS,
     });
     registerInfraTools(server);
@@ -40,6 +41,14 @@ export async function startMcpServer() {
             return { text: REM_OBJECT_FIELDS_CONTENT };
         },
     });
+    server.addResource({
+        uri: 'remnote://edit-rem-guide',
+        name: 'edit_rem 操作指南',
+        mimeType: 'text/markdown',
+        async load() {
+            return { text: EDIT_REM_GUIDE_CONTENT };
+        },
+    });
     server.addResource({
         uri: 'remnote://edit-tree-guide',
         name: 'edit_tree 操作指南',

package/dist/mcp/instructions.js

@@ -25,7 +25,7 @@ Rem 有两个独立维度：**type**（闪卡语义）和 **isDocument**（页
 | type | 含义 | UI 表现 |
 |:-----|:-----|:--------|
 | \\\`concept\\\` | 概念定义 | 文字**加粗** |
-| \\\`descriptor\\\` | 描述/属性 | 文字*斜体* |
+| \\\`descriptor\\\` | 描述/属性 | 正常字重（与 default 无视觉差异） |
 | \\\`default\\\` | 普通 Rem | 正常字重 |
 | \\\`portal\\\` | 嵌入引用容器 | 紫色边框（**只读**，不可设置） |
 
@@ -150,7 +150,35 @@ disconnect → 关闭 daemon，清空所有缓存
 2. 在返回的 JSON 文本中定位要修改的部分
 3. \\\`edit_rem\\\` 用 str_replace 替换：oldStr 精确匹配原文，newStr 是修改后的文本
 
-str_replace 操作的是格式化 JSON 文本（2 空格缩进）。oldStr 要包含足够上下文（如字段名 + 值），避免模糊匹配。替换后必须是合法 JSON。
+str_replace 操作的是 \\\`JSON.stringify(remObject, null, 2)\\\` 格式化文本。oldStr 要包含足够上下文（如字段名 + 值），避免模糊匹配。替换后必须是合法 JSON。
+
+**RichText 编辑要点**（\\\`text\\\` 和 \\\`backText\\\` 字段）：
+
+RichText 在格式化 JSON 中是多行结构，对象内 key 按**字母序**排列（\\\`_id\\\` 排最前，因为 \\\`_\\\` < \\\`a\\\`）。
+
+示例——将纯文本改为粗体：
+
+\\\`\\\`\\\`
+oldStr:  "text": [\\n    "普通标题"\\n  ]
+newStr:  "text": [\\n    {\\n      "b": true,\\n      "i": "m",\\n      "text": "粗体标题"\\n    }\\n  ]
+\\\`\\\`\\\`
+
+示例——给文本加超链接：
+
+\\\`\\\`\\\`
+oldStr:  "text": [\\n    "点击访问官网"\\n  ]
+newStr:  "text": [\\n    "点击",\\n    {\\n      "i": "m",\\n      "iUrl": "https://remnote.com",\\n      "text": "访问官网"\\n    }\\n  ]
+\\\`\\\`\\\`
+
+注意：\\\`highlightColor\\\`（Rem 顶层字段，字符串如 \\\`"Red"\\\`）和 RichText 的 \\\`h\\\`（行内格式标记，数字 0-9）是两个独立属性。详见 \\\`resource://rem-object-fields\\\`。
+
+### 缓存行为速查
+
+| 工具 | 缓存行为 | 用途 |
+|:-----|:---------|:-----|
+| \\\`read_rem\\\` | 写入缓存 | 供 \\\`edit_rem\\\` 使用 |
+| \\\`read_tree\\\` | 写入缓存 | 供 \\\`edit_tree\\\` 使用 |
+| \\\`search\\\` / \\\`read_globe\\\` / \\\`read_context\\\` | **不缓存** | 不能作为 edit 前置 |
 
 ### 场景 E：修改结构（新增/删除/移动/重排）
 

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

@@ -0,0 +1,192 @@
+export const EDIT_REM_GUIDE_CONTENT = `
+# edit_rem 操作指南
+
+edit_rem 通过 str_replace 语义修改单个 Rem 的属性。操作对象是 \\\`JSON.stringify(remObject, null, 2)\\\` 的格式化文本。
+
+---
+
+## 前置条件
+
+必须先 \\\`read_rem\\\` 同一个 remId，建立缓存后才能 \\\`edit_rem\\\`。跳过会触发防线 1 错误。
+
+工作流：\\\`read_rem\\\` → 查看 JSON → \\\`edit_rem\\\`（oldStr/newStr）。
+
+---
+
+## str_replace 语义
+
+### 操作对象
+
+格式化缩进 2 空格的 JSON 文本。示例片段：
+
+\\\`\\\`\\\`json
+{
+  "id": "kLrIOHJLyMd8Y2lyA",
+  "text": [
+    "Hello World"
+  ],
+  "backText": null,
+  "type": "concept",
+  "highlightColor": null,
+  "isTodo": false
+}
+\\\`\\\`\\\`
+
+### 匹配规则
+
+- oldStr 必须在 JSON 文本中**恰好匹配 1 次**（0 次=未找到，>1 次=多匹配，均报错）
+- 大小写敏感，精确匹配
+- oldStr 建议包含字段名 + 值，避免匹配到 text 内容中的同名字符串
+
+### 替换后校验
+
+替换后的文本必须是合法 JSON，否则报 "invalid JSON" 错误。
+
+---
+
+## 三道防线
+
+| 防线 | 检查内容 | 失败时 |
+|:-----|:---------|:-------|
+| 1. 缓存存在 | 是否已 read_rem | 报 "has not been read yet" → 先 read_rem |
+| 2. 并发检测 | 当前 Rem 是否被外部修改 | 报 "has been modified since last read" → 重新 read_rem |
+| 3. 精确匹配 | oldStr 匹配次数 | 0 次或多次 → 调整 oldStr 使其唯一 |
+
+防线 2 的关键：edit 时会从 Plugin 重新读取最新数据与缓存比较。如果不一致（含空白和格式），拒绝编辑并**不更新缓存**，迫使你重新 read_rem。
+
+---
+
+## RichText 编辑实战
+
+\\\`text\\\` 和 \\\`backText\\\` 字段使用 RichText 格式。在格式化 JSON 中，RichText 数组内的对象展开为多行，key 按**字母序**排列。
+
+### 关键排序规则
+
+- \\\`_id\\\`（U+005F）排在所有小写字母之前，所以 \\\`_id\\\` 总是第一个 key
+- 示例排序：\\\`_id\\\` < \\\`b\\\` < \\\`cId\\\` < \\\`h\\\` < \\\`i\\\` < \\\`iUrl\\\` < \\\`text\\\`
+
+### 示例 1：纯文本 → 粗体
+
+read_rem 返回：
+
+\\\`\\\`\\\`json
+  "text": [
+    "普通标题"
+  ],
+\\\`\\\`\\\`
+
+edit_rem 调用：
+
+\\\`\\\`\\\`
+oldStr:  "text": [\\n    "普通标题"\\n  ]
+newStr:  "text": [\\n    {\\n      "b": true,\\n      "i": "m",\\n      "text": "粗体标题"\\n    }\\n  ]
+\\\`\\\`\\\`
+
+替换后变为：
+
+\\\`\\\`\\\`json
+  "text": [
+    {
+      "b": true,
+      "i": "m",
+      "text": "粗体标题"
+    }
+  ],
+\\\`\\\`\\\`
+
+### 示例 2：纯文本 → 部分超链接
+
+\\\`\\\`\\\`
+oldStr:  "text": [\\n    "点击访问官网"\\n  ]
+newStr:  "text": [\\n    "点击",\\n    {\\n      "i": "m",\\n      "iUrl": "https://remnote.com",\\n      "text": "访问官网"\\n    }\\n  ]
+\\\`\\\`\\\`
+
+### 示例 3：修改引用旁的文本
+
+read_rem 返回：
+
+\\\`\\\`\\\`json
+  "text": [
+    "参考 ",
+    {
+      "_id": "abc123",
+      "i": "q"
+    },
+    " 的内容"
+  ],
+\\\`\\\`\\\`
+
+只改文字部分（纯字符串可直接匹配）：
+
+\\\`\\\`\\\`
+oldStr:  " 的内容"
+newStr:  " 的详细说明"
+\\\`\\\`\\\`
+
+如果 " 的内容" 出现多次导致多匹配，加上下文：
+
+\\\`\\\`\\\`
+oldStr:  "q"\\n    },\\n    " 的内容"
+newStr:  "q"\\n    },\\n    " 的详细说明"
+\\\`\\\`\\\`
+
+### 示例 4：添加完形填空
+
+\\\`\\\`\\\`
+oldStr:  "text": [\\n    "光合作用需要阳光"\\n  ]
+newStr:  "text": [\\n    "光合作用需要",\\n    {\\n      "cId": "cloze1",\\n      "i": "m",\\n      "text": "阳光"\\n    }\\n  ]
+\\\`\\\`\\\`
+
+### 示例 5：修改简单属性
+
+\\\`\\\`\\\`
+oldStr:  "type": "default"
+newStr:  "type": "concept"
+\\\`\\\`\\\`
+
+\\\`\\\`\\\`
+oldStr:  "highlightColor": null
+newStr:  "highlightColor": "Red"
+\\\`\\\`\\\`
+
+\\\`\\\`\\\`
+oldStr:  "practiceDirection": "forward"
+newStr:  "practiceDirection": "both"
+\\\`\\\`\\\`
+
+---
+
+## highlightColor vs h
+
+| 属性 | 位置 | 值类型 | 作用范围 |
+|:-----|:-----|:-------|:---------|
+| \\\`highlightColor\\\` | RemObject 顶层字段 | 字符串（\\\`"Red"\\\`, \\\`"Blue"\\\` 等）或 \\\`null\\\` | 整行背景色 |
+| \\\`h\\\` | RichText 元素内格式标记 | 数字 0-9（RemColor 枚举） | 行内文字片段 |
+
+两者完全独立。\\\`highlightColor\\\` 通过 \\\`setHighlightColor()\\\` 写入，\\\`h\\\` 通过 \\\`setText()\\\` 随 RichText 一起写入。
+
+---
+
+## 常见错误
+
+| 错误 | 原因 | 解决 |
+|:-----|:-----|:-----|
+| key 顺序错 | 写 \\\`{"text":"xx","i":"m"}\\\` 但实际是 \\\`{"i":"m","text":"xx"}\\\` | 按字母序排列 key |
+| 缩进不匹配 | 空格数不对 | 仔细对照 read_rem 返回的缩进 |
+| 混淆 highlightColor 和 h | 前者字符串 \\\`"Red"\\\`，后者数字 \\\`1\\\` | 参考上方对比表 |
+| 漏 onlyAudio | \\\`i:"a"\\\` 的 \\\`onlyAudio\\\` 是必填 | true=音频，false=视频 |
+| JSON 语法错 | 引号、逗号、括号不完整 | 检查替换边界 |
+
+---
+
+## 缓存更新行为
+
+| 场景 | 缓存 |
+|:-----|:-----|
+| 写入成功 | 从 Plugin 重新读取最新状态 → 覆盖缓存 |
+| 防线 2 拒绝 | **不更新**缓存（迫使重新 read_rem） |
+| 防线 3 拒绝 | 缓存不变（可调整 oldStr 重试） |
+| 部分写入失败 | **不更新**缓存（迫使重新 read_rem） |
+
+写入成功后**永远从 Plugin 重新读取**，不做本地推导，保证缓存与 SDK 状态完全同步。
+`;

package/dist/mcp/resources/rem-object-fields.js

@@ -25,21 +25,21 @@ RemObject 是本项目对 RemNote Rem 的标准化表示，包含 51 个字段
 
 | 字段 | 类型 | 权限 | 说明 |
 |------|------|:----:|------|
-| \\\`text\\\` | \\\`RichText\\\` | RW | 正面文本（RichText 数组） |
-| \\\`backText\\\` | \\\`RichText \\| null\\\` | RW | 背面文本。null=无背面；设值即产生闪卡正反面结构 |
+| \\\`text\\\` | \\\`RichText\\\` | RW | 正面文本（RichText 数组）。UI：文本内容立即更新显示 |
+| \\\`backText\\\` | \\\`RichText \\| null\\\` | RW | 背面文本。null=无背面；设值即产生闪卡正反面结构。UI：显示为"正面 → 背面"箭头分隔格式 |
 
 ## 类型系统
 
 | 字段 | 类型 | 权限 | 说明 |
 |------|------|:----:|------|
 | \\\`type\\\` | \\\`RemTypeValue\\\` | RW | \\\`concept\\\` / \\\`descriptor\\\` / \\\`default\\\` / \\\`portal\\\` |
-| \\\`isDocument\\\` | \\\`boolean\\\` | RW | 是否作为独立文档页面。独立于 type |
+| \\\`isDocument\\\` | \\\`boolean\\\` | RW | 是否作为独立文档页面。独立于 type。UI：bullet(•)变为文档图标，可独立打开 |
 
 ## 结构
 
 | 字段 | 类型 | 权限 | 说明 |
 |------|------|:----:|------|
-| \\\`parent\\\` | \\\`string \\| null\\\` | RW | 父 Rem ID。null=顶级 |
+| \\\`parent\\\` | \\\`string \\| null\\\` | RW | 父 Rem ID。null=顶级。UI：Rem 从原位置消失，出现在新父级下 |
 | \\\`children\\\` | \\\`string[]\\\` | R | 子 Rem ID 有序数组 |
 
 ## 格式 / 显示
@@ -47,21 +47,21 @@ RemObject 是本项目对 RemNote Rem 的标准化表示，包含 51 个字段
 | 字段 | 类型 | 权限 | 说明 |
 |------|------|:----:|------|
 | \\\`fontSize\\\` | \\\`FontSize \\| null\\\` | RW | 标题大小：\\\`H1\\\` / \\\`H2\\\` / \\\`H3\\\`。null=普通 |
-| \\\`highlightColor\\\` | \\\`HighlightColor \\| null\\\` | RW | 高亮颜色（9 种）。null=无高亮 |
+| \\\`highlightColor\\\` | \\\`HighlightColor \\| null\\\` | RW | 高亮颜色（9 种）。null=无高亮。UI：整行背景变为对应颜色，bullet 也着色 |
 
 ## 状态标记
 
 | 字段 | 类型 | 权限 | 说明 |
 |------|------|:----:|------|
-| \\\`isTodo\\\` | \\\`boolean\\\` | RW | 是否待办。设为 true 时自动初始化 todoStatus |
-| \\\`todoStatus\\\` | \\\`TodoStatus \\| null\\\` | RW | \\\`Finished\\\` / \\\`Unfinished\\\`。需先 isTodo=true |
-| \\\`isCode\\\` | \\\`boolean\\\` | RW | 是否代码块 |
-| \\\`isQuote\\\` | \\\`boolean\\\` | RW | 是否引用块 |
-| \\\`isListItem\\\` | \\\`boolean\\\` | RW | 是否列表项（有序列表样式） |
-| \\\`isCardItem\\\` | \\\`boolean\\\` | RW | 是否卡片项（多行答案行标记） |
+| \\\`isTodo\\\` | \\\`boolean\\\` | RW | 是否待办。设为 true 时自动初始化 todoStatus。UI：文本前出现空心 checkbox（☐） |
+| \\\`todoStatus\\\` | \\\`TodoStatus \\| null\\\` | RW | \\\`Finished\\\` / \\\`Unfinished\\\`。需先 isTodo=true。UI：Finished=蓝色已勾选（☑）+文本删除线 |
+| \\\`isCode\\\` | \\\`boolean\\\` | RW | 是否代码块。UI：等宽字体、灰色背景、块级缩进 |
+| \\\`isQuote\\\` | \\\`boolean\\\` | RW | 是否引用块。UI：左侧灰色竖线+背景浅灰（blockquote 样式） |
+| \\\`isListItem\\\` | \\\`boolean\\\` | RW | 是否列表项。UI：bullet(•)变为数字编号"1."（有序列表） |
+| \\\`isCardItem\\\` | \\\`boolean\\\` | RW | 是否卡片项（多行答案行标记）。UI：无明显变化，在 Card View 中生效 |
 | \\\`isTable\\\` | \\\`boolean\\\` | R | 是否表格（只读） |
-| \\\`isSlot\\\` | \\\`boolean\\\` | RW | 是否 Powerup 插槽。与 isProperty 底层相同 |
-| \\\`isProperty\\\` | \\\`boolean\\\` | RW | 是否 Tag 属性（表格列）。与 isSlot 底层相同 |
+| \\\`isSlot\\\` | \\\`boolean\\\` | RW | 是否 Powerup 插槽。与 isProperty 底层相同。UI：bullet(•)变为方形图标（☐） |
+| \\\`isProperty\\\` | \\\`boolean\\\` | RW | 是否 Tag 属性（表格列）。与 isSlot 底层相同。UI：bullet(•)变为方形图标（☐） |
 
 ## Powerup 系统标识
 
@@ -90,15 +90,15 @@ RemObject 是本项目对 RemNote Rem 的标准化表示，包含 51 个字段
 
 | 字段 | 类型 | 权限 | 说明 |
 |------|------|:----:|------|
-| \\\`enablePractice\\\` | \\\`boolean\\\` | RW | 是否启用间隔重复练习 |
-| \\\`practiceDirection\\\` | \\\`PracticeDirection\\\` | RW | 练习方向：\\\`forward\\\` / \\\`backward\\\` / \\\`both\\\` / \\\`none\\\` |
+| \\\`enablePractice\\\` | \\\`boolean\\\` | RW | 是否启用间隔重复练习。UI：无明显变化 |
+| \\\`practiceDirection\\\` | \\\`PracticeDirection\\\` | RW | 练习方向：\\\`forward\\\` / \\\`backward\\\` / \\\`both\\\` / \\\`none\\\`。UI：无明显变化 |
 
 ## 关联 — 直接关系
 
 | 字段 | 类型 | 权限 | 说明 |
 |------|------|:----:|------|
-| \\\`tags\\\` | \\\`string[]\\\` | RW | 标签 Rem ID 数组。写入时使用 diff 机制（add/remove） |
-| \\\`sources\\\` | \\\`string[]\\\` | RW | 来源 Rem ID 数组。写入时使用 diff 机制 |
+| \\\`tags\\\` | \\\`string[]\\\` | RW | 标签 Rem ID 数组。写入时使用 diff 机制（add/remove）。UI：行右侧出现标签徽章 |
+| \\\`sources\\\` | \\\`string[]\\\` | RW | 来源 Rem ID 数组。写入时使用 diff 机制。UI：Rem 下方出现灰色来源引用框 |
 | \\\`aliases\\\` | \\\`string[]\\\` | R | 别名 Rem ID 数组 |
 
 ## 关联 — 引用关系
@@ -131,7 +131,7 @@ RemObject 是本项目对 RemNote Rem 的标准化表示，包含 51 个字段
 
 | 字段 | 类型 | 权限 | 说明 |
 |------|------|:----:|------|
-| \\\`positionAmongstSiblings\\\` | \\\`number \\| null\\\` | RW | 在兄弟间的位置（0 起始） |
+| \\\`positionAmongstSiblings\\\` | \\\`number \\| null\\\` | RW | 在兄弟间的位置（0 起始）。UI：Rem 在父级子列表中的显示位置改变 |
 | \\\`timesSelectedInSearch\\\` | \\\`number\\\` | R-F | 搜索中被选次数 |
 | \\\`lastTimeMovedTo\\\` | \\\`number\\\` | R-F | 上次移动时间（毫秒时间戳） |
 | \\\`schemaVersion\\\` | \\\`number\\\` | R-F | Schema 版本号 |
@@ -303,29 +303,71 @@ RemObject 中的 \\\`text\\\` 和 \\\`backText\\\` 字段使用 RichText 格式
 
 ### 元素类型
 
-| \\\`i\\\` 值 | 含义 | 核心字段 |
-|--------|------|----------|
-| （纯 string） | 纯文本片段 | — |
-| \\\`"m"\\\` | 带格式文本 | \\\`text\\\` + 格式标记 |
-| \\\`"q"\\\` | Rem 引用 | \\\`_id\\\`（被引用 Rem ID） |
-| \\\`"i"\\\` | 图片 | \\\`url\\\`, \\\`width\\\`, \\\`height\\\` |
-| \\\`"x"\\\` | LaTeX | \\\`text\\\` |
-| \\\`"a"\\\` | 音频 | \\\`url\\\` |
+| \\\`i\\\` 值 | 含义 | 必填字段 | 可选字段 |
+|--------|------|----------|----------|
+| （纯 string） | 纯文本片段 | — | — |
+| \\\`"m"\\\` | 带格式文本 | \\\`text\\\` | 格式标记（见下表） |
+| \\\`"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:"a"\\\` 的 \\\`onlyAudio\\\` 是**必填**字段（\\\`true\\\`=音频，\\\`false\\\`=视频），缺少会导致 SDK 拒绝写入。
+
+### 格式标记（主要用于 \\\`i:"m"\\\`，但 \\\`i:"q"\\\` 等元素也支持）
 
 | 字段 | 类型 | 含义 |
 |------|------|------|
 | \\\`b\\\` | \\\`true\\\` | 加粗 |
-| \\\`l\\\` | \\\`true\\\` | 斜体 |
+| \\\`l\\\` | \\\`true\\\` | 斜体（小写字母 L，不是 I） |
 | \\\`u\\\` | \\\`true\\\` | 下划线 |
-| \\\`h\\\` | \\\`number\\\` | 高亮颜色（1=红, 2=橙, 3=黄, 4=绿, 5=蓝, 6=紫） |
-| \\\`tc\\\` | \\\`number\\\` | 文字颜色 |
-| \\\`code\\\` | \\\`true\\\` | 行内代码 |
+| \\\`h\\\` | \\\`number\\\` | 高亮颜色（RemColor 枚举：1=Red, 2=Orange, 3=Yellow, 4=Green, 5=Purple, 6=Blue, 7=Gray, 8=Brown, 9=Pink） |
+| \\\`tc\\\` | \\\`number\\\` | 文字颜色（同 RemColor 枚举） |
+| \\\`q\\\` | \\\`true\\\` | 行内代码（红色等宽样式） |
+| \\\`code\\\` | \\\`true\\\` | 代码块（带语言标签和复制按钮） |
+| \\\`language\\\` | \\\`string\\\` | 代码块语言（如 \\\`"javascript"\\\`、\\\`"python"\\\`） |
 | \\\`cId\\\` | \\\`string\\\` | 完形填空 ID |
-| \\\`iUrl\\\` | \\\`string\\\` | 外部链接 URL |
+| \\\`hiddenCloze\\\` | \\\`true\\\` | 完形填空隐藏状态 |
+| \\\`revealedCloze\\\` | \\\`true\\\` | 完形填空已揭示状态 |
+| \\\`iUrl\\\` | \\\`string\\\` | 外部超链接 URL（\\\`url\\\` 字段已废弃，必须用 \\\`iUrl\\\`） |
+| \\\`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": "粗体" }        // 粗体（key 序：b < i < text）
+{ "i": "m", "q": true, "text": "code" }        // 行内代码
+{ "i": "m", "iUrl": "https://...", "text": "链接" } // 超链接（iUrl 不是 url！）
+{ "b": true, "h": 1, "i": "m", "text": "重点" } // 粗体+红色高亮（h 是数字 0-9）
+{ "cId": "c1", "i": "m", "text": "答案" }       // 完形填空
+{ "_id": "remId", "b": true, "i": "q" }         // Rem 引用加粗（_id 排最前）
+{ "i": "x", "text": "E = mc^2" }                // LaTeX
+{ "i": "a", "onlyAudio": false, "url": "..." }  // 视频（onlyAudio 必填！）
+{ "i": "a", "onlyAudio": true, "url": "..." }   // 音频
+\\\`\\\`\\\`
+
+> 在 RemObject 格式化 JSON 中，数组内对象会展开为多行（每个 key 一行）。构造 \\\`edit_rem\\\` 的 oldStr/newStr 时必须使用实际的多行格式。
+
+### highlightColor（Rem 级别）vs h（RichText 行内）
+
+- \\\`highlightColor\\\`：RemObject 顶层字段，值为字符串（\\\`"Red"\\\`, \\\`"Blue"\\\` 等）或 \\\`null\\\`，整行背景色
+- \\\`h\\\`：RichText 元素内格式标记，值为数字 0-9（RemColor 枚举），行内文字片段高亮
+
+两者完全独立，互不影响。
 
 ### 序列化确定性
 
-RichText 对象元素内部按 **key 字母序排列**（Plugin 端 \\\`sortRichTextKeys()\\\` 处理），确保同一内容的序列化 JSON 始终一致。这对 \\\`edit_rem\\\` 的 str_replace 和乐观并发检测至关重要。
+RichText 对象元素内部按 **key 字母序排列**（Plugin 端 \\\`sortRichTextKeys()\\\` 处理），确保同一内容的序列化 JSON 始终一致。\\\`_id\\\` 中的 \\\`_\\\`（U+005F）排在所有小写字母（\\\`a\\\`=U+0061）之前，所以 \\\`_id\\\` 总是第一个 key。这对 \\\`edit_rem\\\` 的 str_replace 和乐观并发检测至关重要。
 `;

package/dist/mcp/tools/edit-tools.js

@@ -9,7 +9,7 @@ export function registerEditTools(server) {
     // -------------------------------------------------------------------------
     server.addTool({
         name: 'edit_rem',
-        description: '通过 str_replace 语义修改单个 Rem 的属性字段。\n\n操作对象是 Rem 序列化后的 JSON 文本（JSON.stringify 2 空格缩进），\n在其中将 oldStr 精确替换为 newStr，自动推导变更字段并写入。\n\n适用场景：修改文本、类型、标题级别、practiceDirection、高亮色、Todo 状态等属性；\n修改分隔符以改变闪卡类型。不适合修改子树结构（用 edit_tree）。\n\n前置条件：必须先 read_rem 建立缓存，否则被防线拒绝。\n工作流：read_rem → 查看 JSON → edit_rem 替换。\n\n三道防线：缓存存在 → 并发检测 → 精确匹配（恰好 1 次）。\nstr_replace 要点：oldStr 建议包含字段名避免歧义（如 "text": "旧值"）。替换后须是合法 JSON。\n关联工具：read_rem（前置）、edit_tree（结构编辑）',
+        description: '通过 str_replace 语义修改单个 Rem 的属性字段。\n\n操作对象是 Rem 序列化后的 JSON 文本（JSON.stringify 2 空格缩进），\n在其中将 oldStr 精确替换为 newStr，自动推导变更字段并写入。\n\n适用场景：修改文本、类型、标题级别、practiceDirection、高亮色、Todo 状态等属性；\n修改分隔符以改变闪卡类型。不适合修改子树结构（用 edit_tree）。\n\n前置条件：必须先 read_rem 建立缓存，否则被防线拒绝。\n工作流：read_rem → 查看 JSON → edit_rem 替换。\n\n三道防线：缓存存在 → 并发检测 → 精确匹配（恰好 1 次）。\nstr_replace 要点：oldStr 建议包含字段名避免歧义（如 "text": "旧值"）。替换后须是合法 JSON。\n详细操作指南（含 RichText 编辑实战示例）见 resource://edit-rem-guide。\n关联工具：read_rem（前置）、edit_tree（结构编辑）',
         parameters: z.object({
             remId: z.string().describe('目标 Rem 的 ID'),
             oldStr: z.string().describe('要替换的原始文本（必须精确匹配缓存中的内容，且恰好匹配 1 次）'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remnote-bridge",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "RemNote 自动化桥接工具集：CLI + MCP Server + Plugin",
   "type": "module",
   "bin": {

package/skills/remnote-bridge/SKILL.md

@@ -42,7 +42,7 @@ RemNote 中所有内容的基本单元都是 **Rem**。文档、文件夹、闪
 
 两个独立维度：
 
-- **type**（闪卡语义）：`concept`（加粗）、`descriptor`（斜体）、`default`（普通）、`portal`（只读）
+- **type**（闪卡语义）：`concept`（加粗）、`descriptor`（正常字重）、`default`（普通）、`portal`（只读）
 - **isDocument**（页面语义）：与 type 完全独立
 
 ### CDF 框架（Concept-Descriptor Framework）
@@ -98,16 +98,90 @@ Portal 的编辑同步意味着修改一处会影响另一处。Portal 引用的
 ["纯文本", {"i":"m","b":true,"text":"粗体"}, {"i":"q","_id":"remId"}]
 ```
 
-| `i` 值 | 类型 | 核心字段 |
-|:-------|:-----|:---------|
-| 纯 string | 纯文本 | — |
-| `"m"` | 带格式文本 | `text` + `b`/`l`/`u`/`h`/`tc`/`code`/`cId`/`iUrl` |
-| `"q"` | Rem 引用 | `_id` |
-| `"i"` | 图片 | `url`, `width`, `height` |
-| `"x"` | LaTeX | `text` |
-| `"a"` | 音频 | `url` |
+#### 元素类型
 
-**序列化确定性**：RichText 对象内部按 **key 字母序排列**（如 `{"b":true,"i":"m","text":"粗体"}`），确保 JSON 始终一致。构造 edit-rem 的 oldStr 时必须保持相同的 key 顺序，否则匹配失败。
+| `i` 值 | 类型 | 必填字段 | 可选字段 |
+|:-------|:-----|:---------|:---------|
+| 纯 string | 纯文本 | — | — |
+| `"m"` | 带格式文本 | `text` | 格式标记（见下表） |
+| `"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:"a"` 的 `onlyAudio` 是**必填**字段（`true`=音频，`false`=视频），缺少会导致 SDK 拒绝写入。
+
+#### 格式标记（主要用于 `i:"m"`，但 `i:"q"` 等也支持）
+
+| 字段 | 类型 | 含义 |
+|:-----|:-----|:-----|
+| `b` | `true` | 加粗 |
+| `l` | `true` | 斜体（小写字母 L，不是 I） |
+| `u` | `true` | 下划线 |
+| `h` | `number` | 高亮颜色（见 RemColor 枚举） |
+| `tc` | `number` | 文字颜色（见 RemColor 枚举） |
+| `q` | `true` | 行内代码（红色等宽样式） |
+| `code` | `true` | 代码块（带语言标签和复制按钮） |
+| `language` | `string` | 代码块语言（如 `"javascript"`、`"python"`） |
+| `cId` | `string` | 完形填空 ID |
+| `hiddenCloze` | `true` | 完形填空隐藏状态 |
+| `revealedCloze` | `true` | 完形填空已揭示状态 |
+| `iUrl` | `string` | 外部超链接 URL |
+| `qId` | `string` | 行内引用链接的 Rem ID |
+
+**注意**：`url` 字段已废弃无效，超链接必须用 `iUrl`。
+
+#### RemColor 颜色枚举（`h` 和 `tc` 共用）
+
+| 值 | 颜色 | 值 | 颜色 | 值 | 颜色 |
+|:---|:-----|:---|:-----|:---|:-----|
+| 0 | 无颜色/默认 | 4 | Green | 7 | Gray |
+| 1 | Red | 5 | Purple | 8 | Brown |
+| 2 | Orange | 6 | Blue | 9 | Pink |
+| 3 | Yellow | — | — | — | — |
+
+#### 常用构造示例
+
+以下为 `JSON.stringify(null, 2)` 格式化后的实际样式（key 按字母序）：
+
+```jsonc
+// 粗体（注意 key 顺序：b < i < text）
+{ "b": true, "i": "m", "text": "粗体" }
+// 行内代码
+{ "i": "m", "q": true, "text": "console.log()" }
+// 超链接（iUrl 不是 url！）
+{ "i": "m", "iUrl": "https://example.com", "text": "点击访问" }
+// 红色高亮 + 粗体（h 是数字，不是字符串）
+{ "b": true, "h": 1, "i": "m", "text": "重点" }
+// 完形填空
+{ "cId": "cloze1", "i": "m", "text": "答案内容" }
+// Rem 引用（_id 排在所有小写 key 之前）
+{ "_id": "remId", "i": "q" }
+// Rem 引用加粗
+{ "_id": "remId", "b": true, "i": "q" }
+// LaTeX 公式
+{ "i": "x", "text": "E = mc^2" }
+// 图片
+{ "i": "i", "url": "https://...", "width": 200, "height": 100 }
+// 视频（onlyAudio 必填！）
+{ "i": "a", "onlyAudio": false, "url": "https://youtube.com/watch?v=xxx" }
+// 音频
+{ "i": "a", "onlyAudio": true, "url": "https://example.com/audio.mp3" }
+```
+
+> **注意**：在 RemObject 的格式化 JSON 中，数组内的对象会展开为多行（每个 key 一行，缩进 4+2 空格）。以上为简写——构造 edit-rem 的 oldStr/newStr 时必须使用实际的多行格式。
+
+#### highlightColor（Rem 级别）vs h（RichText 行内）
+
+- `highlightColor`：RemObject 顶层字段，值为字符串（`"Red"`, `"Blue"` 等）或 `null`，作用于整行背景
+- `h`：RichText 元素内格式标记，值为数字 0-9（RemColor 枚举），作用于行内文字片段
+
+两者完全独立，互不影响。
+
+#### 序列化确定性
+
+RichText 对象内部按 **key 字母序排列**（`sortRichTextKeys()`），确保 JSON 始终一致。`_id` 中的 `_`（U+005F）排在所有小写字母（`a`=U+0061）之前。构造 edit-rem 的 oldStr 时必须保持相同的 key 顺序，否则匹配失败。
 
 ### Powerup 机制与噪音过滤
 

package/skills/remnote-bridge/instructions/edit-rem.md

@@ -461,12 +461,158 @@ str_replace 操作的对象是 `JSON.stringify(remObject, null, 2)` 的文本—
 
 2. **替换后必须是合法 JSON**：检查引号、逗号、括号的完整性
 
-3. **修改 RichText 字段**：直接操作 JSON 数组结构
+3. **修改 RichText 字段**：直接操作 JSON 数组结构（见下方完整示例）
 
-   ```
-   oldStr: "\"text\": [\n    \"Hello\"\n  ]"
-   newStr: "\"text\": [\n    \"World\"\n  ]"
-   ```
+---
+
+## RichText 编辑实战指南
+
+### 理解格式化 JSON 中的 RichText
+
+`edit-rem` 的 str_replace 操作对象是 `JSON.stringify(remObject, null, 2)` 的格式化文本。RichText 数组在格式化后是多行缩进结构，**不是**紧凑的单行 JSON。
+
+以下是一个包含 RichText 的 RemObject **实际输出片段**：
+
+```json
+{
+  "id": "kLrIOHJLyMd8Y2lyA",
+  "text": [
+    "这是",
+    {
+      "b": true,
+      "i": "m",
+      "text": "粗体"
+    },
+    "普通文本"
+  ],
+  "backText": null,
+  "type": "concept",
+  "highlightColor": null,
+  "isTodo": false
+}
+```
+
+**关键要点**：
+- RichText 对象内部的 key 按**字母序**排列（`b` < `i` < `text`），由 Plugin 端 `sortRichTextKeys()` 保证
+- `_id` 中的 `_` 在 Unicode 中排在小写字母之前，所以 `_id` 排在所有小写 key 的最前面
+- 每个 key-value 对占一行，缩进 4 空格（对象在数组中时嵌套 2+2）
+- 纯字符串元素直接是 `"字符串"`，对象元素展开为多行
+
+### 示例 1：将纯文本改为粗体
+
+**read-rem 返回**（部分）：
+
+```json
+  "text": [
+    "普通标题"
+  ],
+```
+
+**edit-rem 调用**：
+
+```
+oldStr:  "\"text\": [\n    \"普通标题\"\n  ]"
+
+newStr:  "\"text\": [\n    {\n      \"b\": true,\n      \"i\": \"m\",\n      \"text\": \"粗体标题\"\n    }\n  ]"
+```
+
+替换后 JSON 变为：
+
+```json
+  "text": [
+    {
+      "b": true,
+      "i": "m",
+      "text": "粗体标题"
+    }
+  ],
+```
+
+### 示例 2：修改 Rem 引用旁的文本
+
+**read-rem 返回**（部分）：
+
+```json
+  "text": [
+    "参考 ",
+    {
+      "_id": "abc123",
+      "i": "q"
+    },
+    " 的内容"
+  ],
+```
+
+将 " 的内容" 替换为 " 的详细说明"：
+
+```
+oldStr:  " 的内容"
+newStr:  " 的详细说明"
+```
+
+> 注意：纯字符串可以直接匹配，不需要包含数组结构。但如果 " 的内容" 在 JSON 中出现多次，需要加上下文：
+> `oldStr: "    \" 的内容\"\n  ]"`
+
+### 示例 3：给文本添加超链接
+
+**read-rem 返回**（部分）：
+
+```json
+  "text": [
+    "点击访问官网"
+  ],
+```
+
+**edit-rem 调用**：
+
+```
+oldStr:  "\"text\": [\n    \"点击访问官网\"\n  ]"
+
+newStr:  "\"text\": [\n    \"点击\",\n    {\n      \"i\": \"m\",\n      \"iUrl\": \"https://remnote.com\",\n      \"text\": \"访问官网\"\n    }\n  ]"
+```
+
+### 示例 4：修改高亮颜色（Rem 级别 vs RichText 级别）
+
+**Rem 级别的 `highlightColor`**（整行背景色，值为英文字符串）：
+
+```
+oldStr:  "\"highlightColor\": null"
+newStr:  "\"highlightColor\": \"Red\""
+```
+
+**RichText 级别的 `h`**（行内文字高亮，值为数字 0-9）：
+
+```
+oldStr:  "\"text\": [\n    \"普通文本\"\n  ]"
+newStr:  "\"text\": [\n    {\n      \"h\": 1,\n      \"i\": \"m\",\n      \"text\": \"红色高亮文本\"\n    }\n  ]"
+```
+
+> **区分**：`highlightColor` 是 RemObject 顶层字段，值为字符串（`"Red"`, `"Blue"` 等）；RichText 的 `h` 是行内格式标记，值为数字（1=Red, 2=Orange 等，见 RemColor 枚举）。
+
+### 示例 5：添加完形填空
+
+**read-rem 返回**（部分）：
+
+```json
+  "text": [
+    "光合作用需要阳光"
+  ],
+```
+
+将 "阳光" 变成完形填空：
+
+```
+oldStr:  "\"text\": [\n    \"光合作用需要阳光\"\n  ]"
+
+newStr:  "\"text\": [\n    \"光合作用需要\",\n    {\n      \"cId\": \"cloze1\",\n      \"i\": \"m\",\n      \"text\": \"阳光\"\n    }\n  ]"
+```
+
+### 常见错误
+
+1. **忘记 key 字母序**：写 `{"text":"xx","i":"m","b":true}` 不会被匹配——实际存储为 `{"b":true,"i":"m","text":"xx"}`
+2. **缩进不匹配**：格式化 JSON 使用 2 空格缩进，数组内对象的 key 缩进 6 空格（顶层 2 + 数组 2 + 对象 2），但在 `JSON.stringify(obj, null, 2)` 中数组元素的对象缩进 4 空格（数组 2 + 对象内 2）
+3. **混淆 highlightColor 和 h**：前者是字符串 `"Red"`，后者是数字 `1`
+4. **忘记 `i:"a"` 的 `onlyAudio` 必填**：缺少此字段 SDK 拒绝写入
 
 ---
 

package/skills/remnote-bridge/instructions/overall.md

@@ -474,16 +474,58 @@ Portal：portalType [R], portalDirectlyIncludedRem [R]
 ]
 ```
 
-| `i` 值 | 类型 | 核心字段 |
-|:-------|:-----|:---------|
-| （纯 string） | 纯文本 | — |
-| `"m"` | 带格式文本 | `text` + `b`/`l`/`u`/`h`/`code`/`cId`/`iUrl` |
-| `"q"` | Rem 引用 | `_id`（被引用 Rem ID） |
-| `"i"` | 图片 | `url`, `width`, `height` |
-| `"x"` | LaTeX | `text` |
-| `"a"` | 音频 | `url` |
-
-**序列化确定性**：RichText 对象内部按 key 字母序排列（`sortRichTextKeys()`），确保同一内容的 JSON 始终一致。这对 edit-rem 的 str_replace 和并发检测至关重要。
+#### 元素类型
+
+| `i` 值 | 类型 | 必填字段 | 可选字段 |
+|:-------|:-----|:---------|:---------|
+| （纯 string） | 纯文本 | — | — |
+| `"m"` | 带格式文本 | `text` | 格式标记（见下表） |
+| `"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:"a"` 的 `onlyAudio` 是必填字段（`true`=音频，`false`=视频），缺少会导致 SDK 拒绝写入。
+
+#### 格式标记（主要用于 `i:"m"`，但 `i:"q"` 等也支持）
+
+| 字段 | 类型 | 含义 |
+|:-----|:-----|:-----|
+| `b` | `true` | 加粗 |
+| `l` | `true` | 斜体（小写字母 L） |
+| `u` | `true` | 下划线 |
+| `h` | `number` | 高亮颜色（RemColor 枚举：1=Red, 2=Orange, 3=Yellow, 4=Green, 5=Purple, 6=Blue, 7=Gray, 8=Brown, 9=Pink） |
+| `tc` | `number` | 文字颜色（同 RemColor 枚举） |
+| `q` | `true` | 行内代码（红色等宽样式） |
+| `code` | `true` | 代码块（带语言标签和复制按钮） |
+| `language` | `string` | 代码块语言（如 `"javascript"`） |
+| `cId` | `string` | 完形填空 ID |
+| `hiddenCloze` | `true` | 完形填空隐藏状态 |
+| `iUrl` | `string` | 外部超链接 URL（`url` 字段已废弃，必须用 `iUrl`） |
+| `qId` | `string` | 行内引用链接的 Rem ID |
+
+#### 常用构造示例
+
+以下为 `JSON.stringify(null, 2)` 格式化后的 key 字母序排列：
+
+```jsonc
+{ "b": true, "i": "m", "text": "粗体" }        // 粗体
+{ "i": "m", "q": true, "text": "code" }        // 行内代码
+{ "i": "m", "iUrl": "https://...", "text": "链接" } // 超链接
+{ "b": true, "h": 1, "i": "m", "text": "重点" } // 粗体+红色高亮（h 是数字）
+{ "cId": "c1", "i": "m", "text": "答案" }       // 完形填空
+{ "_id": "remId", "b": true, "i": "q" }         // Rem 引用加粗（_id 排最前）
+{ "i": "x", "text": "E = mc^2" }                // LaTeX
+{ "i": "a", "onlyAudio": false, "url": "..." }  // 视频（onlyAudio 必填！）
+{ "i": "a", "onlyAudio": true, "url": "..." }   // 音频
+```
+
+> 在 RemObject 格式化 JSON 中，数组内对象展开为多行。构造 edit-rem 的 oldStr/newStr 必须用多行格式。
+
+**highlightColor vs h**：`highlightColor` 是 RemObject 顶层字段（字符串如 `"Red"`），`h` 是 RichText 行内格式标记（数字 0-9）。两者独立。
+
+**序列化确定性**：RichText 对象内部按 key 字母序排列（`sortRichTextKeys()`）。`_id` 的 `_`（U+005F）排在所有小写字母之前。这对 edit-rem 的 str_replace 和并发检测至关重要。
 
 ---
 

package/skills/remnote-bridge/instructions/read-rem.md

@@ -184,21 +184,21 @@ RemObject 共 51 个字段，按读写权限分为三类：
 
 | 字段 | 类型 | 权限 | 说明 |
 |------|------|:----:|------|
-| `text` | `RichText` | RW | 正面文本（RichText 数组） |
-| `backText` | `RichText \| null` | RW | 背面文本。null=无背面；设值即产生闪卡正反面结构 |
+| `text` | `RichText` | RW | 正面文本（RichText 数组）。UI：文本内容立即更新显示 |
+| `backText` | `RichText \| null` | RW | 背面文本。null=无背面；设值即产生闪卡正反面结构。UI：显示为"正面 → 背面"箭头分隔格式 |
 
 ### 类型系统
 
 | 字段 | 类型 | 权限 | 说明 |
 |------|------|:----:|------|
 | `type` | `RemTypeValue` | RW | `concept` / `descriptor` / `default` / `portal` |
-| `isDocument` | `boolean` | RW | 是否作为独立文档页面。独立于 type |
+| `isDocument` | `boolean` | RW | 是否作为独立文档页面。独立于 type。UI：bullet(•)变为文档图标，可独立打开 |
 
 ### 结构
 
 | 字段 | 类型 | 权限 | 说明 |
 |------|------|:----:|------|
-| `parent` | `string \| null` | RW | 父 Rem ID。null=顶级 |
+| `parent` | `string \| null` | RW | 父 Rem ID。null=顶级。UI：Rem 从原位置消失，出现在新父级下 |
 | `children` | `string[]` | R | 子 Rem ID 有序数组 |
 
 ### 格式 / 显示
@@ -206,21 +206,21 @@ RemObject 共 51 个字段，按读写权限分为三类：
 | 字段 | 类型 | 权限 | 说明 |
 |------|------|:----:|------|
 | `fontSize` | `FontSize \| null` | RW | 标题大小：`H1` / `H2` / `H3`。null=普通 |
-| `highlightColor` | `HighlightColor \| null` | RW | 高亮颜色（9 种）。null=无高亮 |
+| `highlightColor` | `HighlightColor \| null` | RW | 高亮颜色（9 种）。null=无高亮。UI：整行背景变为对应颜色，bullet 也着色 |
 
 ### 状态标记
 
 | 字段 | 类型 | 权限 | 说明 |
 |------|------|:----:|------|
-| `isTodo` | `boolean` | RW | 是否待办。设为 true 时自动初始化 todoStatus |
-| `todoStatus` | `TodoStatus \| null` | RW | `Finished` / `Unfinished`。需先 isTodo=true |
-| `isCode` | `boolean` | RW | 是否代码块 |
-| `isQuote` | `boolean` | RW | 是否引用块 |
-| `isListItem` | `boolean` | RW | 是否列表项（有序列表样式） |
-| `isCardItem` | `boolean` | RW | 是否卡片项（多行答案行标记） |
+| `isTodo` | `boolean` | RW | 是否待办。设为 true 时自动初始化 todoStatus。UI：文本前出现空心 checkbox（☐） |
+| `todoStatus` | `TodoStatus \| null` | RW | `Finished` / `Unfinished`。需先 isTodo=true。UI：Finished=蓝色已勾选（☑）+文本删除线 |
+| `isCode` | `boolean` | RW | 是否代码块。UI：等宽字体、灰色背景、块级缩进 |
+| `isQuote` | `boolean` | RW | 是否引用块。UI：左侧灰色竖线+背景浅灰（blockquote 样式） |
+| `isListItem` | `boolean` | RW | 是否列表项。UI：bullet(•)变为数字编号"1."（有序列表） |
+| `isCardItem` | `boolean` | RW | 是否卡片项（多行答案行标记）。UI：无明显变化，在 Card View 中生效 |
 | `isTable` | `boolean` | R | 是否表格（只读） |
-| `isSlot` | `boolean` | RW | 是否 Powerup 插槽。与 isProperty 底层相同 |
-| `isProperty` | `boolean` | RW | 是否 Tag 属性（表格列）。与 isSlot 底层相同 |
+| `isSlot` | `boolean` | RW | 是否 Powerup 插槽。与 isProperty 底层相同。UI：bullet(•)变为方形图标（☐） |
+| `isProperty` | `boolean` | RW | 是否 Tag 属性（表格列）。与 isSlot 底层相同。UI：bullet(•)变为方形图标（☐） |
 
 ### Powerup 系统标识
 
@@ -249,15 +249,15 @@ RemObject 共 51 个字段，按读写权限分为三类：
 
 | 字段 | 类型 | 权限 | 说明 |
 |------|------|:----:|------|
-| `enablePractice` | `boolean` | RW | 是否启用间隔重复练习 |
-| `practiceDirection` | `PracticeDirection` | RW | 练习方向：`forward` / `backward` / `both` / `none` |
+| `enablePractice` | `boolean` | RW | 是否启用间隔重复练习。UI：无明显变化 |
+| `practiceDirection` | `PracticeDirection` | RW | 练习方向：`forward` / `backward` / `both` / `none`。UI：无明显变化 |
 
 ### 关联 — 直接关系
 
 | 字段 | 类型 | 权限 | 说明 |
 |------|------|:----:|------|
-| `tags` | `string[]` | RW | 标签 Rem ID 数组。写入时使用 diff 机制（add/remove） |
-| `sources` | `string[]` | RW | 来源 Rem ID 数组。写入时使用 diff 机制 |
+| `tags` | `string[]` | RW | 标签 Rem ID 数组。写入时使用 diff 机制（add/remove）。UI：行右侧出现标签徽章 |
+| `sources` | `string[]` | RW | 来源 Rem ID 数组。写入时使用 diff 机制。UI：Rem 下方出现灰色来源引用框 |
 | `aliases` | `string[]` | R | 别名 Rem ID 数组 |
 
 ### 关联 — 引用关系
@@ -290,7 +290,7 @@ RemObject 共 51 个字段，按读写权限分为三类：
 
 | 字段 | 类型 | 权限 | 说明 |
 |------|------|:----:|------|
-| `positionAmongstSiblings` | `number \| null` | RW | 在兄弟间的位置（0 起始） |
+| `positionAmongstSiblings` | `number \| null` | RW | 在兄弟间的位置（0 起始）。UI：Rem 在父级子列表中的显示位置改变 |
 | `timesSelectedInSearch` | `number` | R-F | 搜索中被选次数 |
 | `lastTimeMovedTo` | `number` | R-F | 上次移动时间（毫秒时间戳） |
 | `schemaVersion` | `number` | R-F | Schema 版本号 |
@@ -394,38 +394,175 @@ localUpdatedAt, lastPracticed
 
 ---
 
+## 可编辑字段约束表
+
+以下为 20 个可编辑字段（RW）的写入约束：
+
+| 字段 | SDK setter | 约束 / 特殊处理 |
+|------|-----------|-----------------|
+| `text` | `rem.setText()` | RichText 数组 |
+| `backText` | `rem.setBackText()` | `null` → `setBackText([])`（清除背面）；裸字符串自动包装为 `[string]` |
+| `type` | `rem.setType()` | `portal` 不可设置（只能通过 `createPortal()` 创建） |
+| `isDocument` | `rem.setIsDocument()` | — |
+| `parent` | `rem.setParent(parentId, position?)` | 与 `positionAmongstSiblings` 联动（见下方说明） |
+| `fontSize` | `rem.setFontSize()` | `null` → `setFontSize(undefined)`（恢复普通大小） |
+| `highlightColor` | `rem.setHighlightColor()` / `rem.removePowerup('h')` | `null` → `removePowerup('h')`（SDK 不接受 null） |
+| `isTodo` | `rem.setIsTodo()` | 设为 true 时自动初始化 todoStatus |
+| `todoStatus` | `rem.setTodoStatus()` | `null` → 跳过（清除 todo 应通过 `isTodo=false`） |
+| `isCode` | `rem.setIsCode()` | — |
+| `isQuote` | `rem.setIsQuote()` | — |
+| `isListItem` | `rem.setIsListItem()` | — |
+| `isCardItem` | `rem.setIsCardItem()` | — |
+| `isSlot` | `rem.setIsSlot()` | 与 `isProperty` 底层相同 |
+| `isProperty` | `rem.setIsProperty()` | 与 `isSlot` 底层相同 |
+| `enablePractice` | `rem.setEnablePractice()` | — |
+| `practiceDirection` | `rem.setPracticeDirection()` | `forward` / `backward` / `both` / `none` |
+| `tags` | `rem.addTag()` / `rem.removeTag()` | **Diff 机制**：对比当前 vs 目标，增删差异项。必须列出完整目标数组，缺少的会被删除 |
+| `sources` | `rem.addSource()` / `rem.removeSource()` | **Diff 机制**：同 tags |
+| `positionAmongstSiblings` | `rem.setParent(parent, position)` | 与 `parent` 联动（见下方说明） |
+
+### parent + positionAmongstSiblings 联动
+
+这两个字段通过同一个 SDK 调用 `rem.setParent(parentId, position)` 写入：
+
+| 场景 | 行为 |
+|------|------|
+| 两个字段都变更 | 合并为一次 `setParent(newParent, newPosition)` 调用 |
+| 只有 `parent` 变更 | `setParent(newParent)` 不带 position（保持末尾） |
+| 只有 `positionAmongstSiblings` 变更 | 获取当前 parent → `setParent(currentParent, newPosition)` |
+
+**应在同一次 str_replace 中同时修改这两个字段。**
+
+---
+
 ## RichText 格式
 
 RemObject 中的 `text` 和 `backText` 字段使用 RichText 格式——一个 JSON 数组，每个元素为纯字符串或带 `i` 字段的格式化对象。
 
 ### 元素类型
 
-| `i` 值 | 含义 | 核心字段 |
-|--------|------|----------|
-| （纯 string） | 纯文本片段 | — |
-| `"m"` | 带格式文本 | `text` + 格式标记 |
-| `"q"` | Rem 引用 | `_id`（被引用 Rem ID） |
-| `"i"` | 图片 | `url`, `width`, `height` |
-| `"x"` | LaTeX | `text` |
-| `"a"` | 音频 | `url` |
+| `i` 值 | 含义 | 必填字段 | 可选字段 |
+|--------|------|----------|----------|
+| （纯 string） | 纯文本片段 | — | — |
+| `"m"` | 带格式文本 | `text` | 格式标记（见下表） |
+| `"q"` | Rem 引用 | `_id`（被引用 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:"a"` 的 `onlyAudio` 是**必填**字段（`true`=音频，`false`=视频），缺少会导致 SDK 拒绝写入（`Invalid input`）。
+
+### 格式标记（主要用于 `i:"m"`，但 `i:"q"` 等元素也支持）
 
 | 字段 | 类型 | 含义 |
 |------|------|------|
 | `b` | `true` | 加粗 |
-| `l` | `true` | 斜体 |
+| `l` | `true` | 斜体（小写字母 L，不是 I） |
 | `u` | `true` | 下划线 |
-| `h` | `number` | 高亮颜色（1=红, 2=橙, 3=黄, 4=绿, 5=蓝, 6=紫） |
-| `tc` | `number` | 文字颜色 |
-| `code` | `true` | 行内代码 |
+| `h` | `number` | 高亮颜色（见 RemColor 枚举） |
+| `tc` | `number` | 文字颜色（见 RemColor 枚举） |
+| `q` | `true` | 行内代码（红色等宽样式） |
+| `code` | `true` | 代码块（带语言标签和复制按钮） |
+| `language` | `string` | 代码块语言（如 `"javascript"`、`"python"`） |
 | `cId` | `string` | 完形填空 ID |
-| `iUrl` | `string` | 外部链接 URL |
+| `hiddenCloze` | `true` | 完形填空隐藏状态 |
+| `revealedCloze` | `true` | 完形填空已揭示状态 |
+| `iUrl` | `string` | 外部超链接 URL（**注意**：`url` 字段已废弃无效，必须用 `iUrl`） |
+| `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 | — | — | — | — |
+
+### 常用构造示例
+
+以下示例展示实际 `JSON.stringify(null, 2)` 格式化后的样子（key 按字母序排列）：
+
+```jsonc
+// 粗体
+{
+  "b": true,
+  "i": "m",
+  "text": "粗体"
+}
+// 行内代码
+{
+  "i": "m",
+  "q": true,
+  "text": "console.log()"
+}
+// 超链接
+{
+  "i": "m",
+  "iUrl": "https://example.com",
+  "text": "点击访问"
+}
+// 红色高亮 + 粗体（h 是 RichText 行内格式标记，值为数字）
+{
+  "b": true,
+  "h": 1,
+  "i": "m",
+  "text": "重点"
+}
+// 完形填空
+{
+  "cId": "cloze1",
+  "i": "m",
+  "text": "答案内容"
+}
+// Rem 引用（_id 排在小写字母之前）
+{
+  "_id": "remId",
+  "i": "q"
+}
+// Rem 引用 + 加粗
+{
+  "_id": "remId",
+  "b": true,
+  "i": "q"
+}
+// LaTeX 块级公式
+{
+  "block": true,
+  "i": "x",
+  "text": "\\frac{a}{b}"
+}
+// 视频（onlyAudio 必填！）
+{
+  "i": "a",
+  "onlyAudio": false,
+  "url": "https://youtube.com/watch?v=xxx"
+}
+// 音频
+{
+  "i": "a",
+  "onlyAudio": true,
+  "url": "https://example.com/audio.mp3"
+}
+```
+
+### highlightColor（Rem 级别）vs h（RichText 行内格式）
+
+| 属性 | 位置 | 值类型 | 作用范围 | 示例 |
+|------|------|--------|----------|------|
+| `highlightColor` | RemObject 顶层字段 | 字符串（`"Red"`, `"Blue"` 等）或 `null` | 整个 Rem（整行背景色） | `"highlightColor": "Red"` |
+| `h` | RichText 元素内的格式标记 | 数字（0-9，见 RemColor 枚举） | 行内文字片段 | `{"h": 1, "i": "m", "text": "高亮"}` |
+
+两者完全独立。`highlightColor` 通过 `rem.setHighlightColor()` / `rem.removePowerup('h')` 写入；`h` 是 RichText JSON 内的字段，通过 `rem.setText()` 写入。
 
 ### 序列化确定性
 
 RichText 对象元素内部按 **key 字母序排列**（Plugin 端 `sortRichTextKeys()` 处理），确保同一内容的序列化 JSON 始终一致。这对 `edit-rem` 的 str_replace 和乐观并发检测至关重要。
 
+- `_`（下划线）在 Unicode 中排在所有小写字母之前（`_` = U+005F，`a` = U+0061），所以 `_id` 总是排在第一位
+- 排序由 `Object.keys().sort()` 决定，即 JavaScript 默认的 Unicode 字典序
+
 ---
 
 ## Powerup 过滤