remnote-bridge 0.1.1 → 0.1.3

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/resources/separator-flashcard.js

@@ -1,30 +1,32 @@
 export const SEPARATOR_FLASHCARD_CONTENT = `
 # Separator & Flashcard Reference
 
-用户在 RemNote 中输入的分隔符决定了 Rem 的 type、backText 和默认 practiceDirection。理解分隔符是理解用户创建闪卡意图的关键。
+**重要**：分隔符（\\\`::\\\`、\\\`;;\\\`、\\\`>>\\\` 等）是 RemNote 编辑器的输入语法，**CLI 不使用分隔符**。通过 CLI 创建/修改闪卡，操作的是 \\\`type\\\`、\\\`backText\\\`、\\\`practiceDirection\\\` 字段和大纲箭头（\\\`→←↔↓↑↕\\\`）。本参考表用于理解用户意图——当用户提到分隔符时，映射到对应的 CLI 操作。
 
 ---
 
-## 分隔符完整映射表
-
-| 分隔符 | 用户输入示例 | type | backText | 默认 practiceDirection | 用途 |
-|:-------|:-------------|:-----|:---------|:-----------------------|:-----|
-| （无） | \\\`普通文本\\\` | \\\`default\\\` | \\\`null\\\` | — | 无闪卡行为 |
-| \\\`::\\\` | \\\`概念 :: 定义\\\` | \\\`concept\\\` | 后半部分 | \\\`both\\\` | 概念定义（CDF 框架） |
-| \\\`;;\\\` | \\\`属性 ;; 值\\\` | \\\`descriptor\\\` | 后半部分 | \\\`forward\\\` | 描述属性（CDF 框架） |
-| \\\`>>\\\` | \\\`问题 >> 答案\\\` | \\\`default\\\` | 后半部分 | \\\`forward\\\` | 正向问答 |
-| \\\`<<\\\` | \\\`问题 << 答案\\\` | \\\`default\\\` | 后半部分 | \\\`backward\\\` | 反向问答 |
-| \\\`<>\\\` | \\\`问题 <> 答案\\\` | \\\`default\\\` | 后半部分 | \\\`both\\\` | 双向问答 |
-| \\\`>>>\\\` | \\\`问题 >>>\\\` | \\\`default\\\` | \\\`null\\\` | \\\`forward\\\` | 多行答案（子 Rem 为答案） |
-| \\\`::>\\\` | \\\`概念 ::>\\\` | \\\`concept\\\` | \\\`null\\\` | \\\`both\\\` | 概念型多行答案 |
-| \\\`;;>\\\` | \\\`属性 ;;>\\\` | \\\`descriptor\\\` | \\\`null\\\` | \\\`forward\\\` | 描述型多行答案 |
-| \\\`{{}}\\\` | \\\`The {{capital}} of France is Paris\\\` | \\\`default\\\` | \\\`null\\\` | \\\`forward\\\` | 完形填空（Cloze） |
+## 1. 用户意图映射：编辑器分隔符 → CLI 操作
+
+当用户提到以下分隔符时，对应的 Rem 属性为：
+
+| 编辑器分隔符 | 用户输入示例 | type | backText | 默认 practiceDirection |
+|:-------------|:-------------|:-----|:---------|:-----------------------|
+| （无） | \\\`普通文本\\\` | \\\`default\\\` | \\\`null\\\` | — |
+| \\\`::\\\` | \\\`概念 :: 定义\\\` | \\\`concept\\\` | 后半部分 | \\\`both\\\` |
+| \\\`;;\\\` | \\\`属性 ;; 值\\\` | \\\`descriptor\\\` | 后半部分 | \\\`forward\\\` |
+| \\\`>>\\\` | \\\`问题 >> 答案\\\` | \\\`default\\\` | 后半部分 | \\\`forward\\\` |
+| \\\`<<\\\` | \\\`问题 << 答案\\\` | \\\`default\\\` | 后半部分 | \\\`backward\\\` |
+| \\\`<>\\\` | \\\`问题 <> 答案\\\` | \\\`default\\\` | 后半部分 | \\\`both\\\` |
+| \\\`>>>\\\` | \\\`问题 >>>\\\` | \\\`default\\\` | \\\`null\\\` | \\\`forward\\\`（多行） |
+| \\\`::>\\\` | \\\`概念 ::>\\\` | \\\`concept\\\` | \\\`null\\\` | \\\`both\\\`（多行） |
+| \\\`;;>\\\` | \\\`属性 ;;>\\\` | \\\`descriptor\\\` | \\\`null\\\` | \\\`forward\\\`（多行） |
+| \\\`{{}}\\\` | \\\`The {{capital}} of France\\\` | \\\`default\\\` | \\\`null\\\` | \\\`forward\\\`（完形填空） |
 
 ---
 
-## 大纲中的箭头分隔符
+## 2. CLI 操作方式：大纲箭头
 
-在 Markdown 大纲（read_tree / edit_tree）中，分隔符被编码为 Unicode 箭头：
+在 Markdown 大纲（read_tree / edit_tree）中，practiceDirection 编码为 Unicode 箭头：
 
 ### 单行箭头（有 backText）
 
@@ -46,7 +48,7 @@ export const SEPARATOR_FLASHCARD_CONTENT = `
 
 ---
 
-## practiceDirection 取值
+## 3. practiceDirection 取值
 
 | 值 | 含义 | 闪卡生成 |
 |:---|:-----|:---------|
@@ -57,28 +59,28 @@ export const SEPARATOR_FLASHCARD_CONTENT = `
 
 ---
 
-## CDF（Concept-Descriptor Framework）
+## 4. CDF（Concept-Descriptor Framework）
 
 RemNote 推荐的知识结构化方法：
 
-- **Concept**（\\\`::\\\`）：需要理解的核心概念——"X 是什么？"
-- **Descriptor**（\\\`;;\\\`）：概念的属性/描述——"X 的 Y 是什么？"
+- **Concept**（type:concept）：需要理解的核心概念——"X 是什么？"
+- **Descriptor**（type:descriptor）：概念的属性/描述——"X 的 Y 是什么？"
 
-典型结构：
+在 CLI 大纲中的表现（注意：用箭头和元数据标记，不用分隔符）：
 
 \\\`\\\`\\\`
-线性回归 :: 最基本的回归模型        ← Concept (type:concept, both)
-  假设 ;; 因变量与自变量呈线性关系   ← Descriptor (type:descriptor, forward)
-  损失函数 ;; 均方误差 (MSE)        ← Descriptor (type:descriptor, forward)
+线性回归 ↔ 最基本的回归模型 <!--id1 type:concept-->
+  假设 → 因变量与自变量呈线性关系 <!--id2 type:descriptor-->
+  损失函数 → 均方误差 (MSE) <!--id3 type:descriptor-->
 \\\`\\\`\\\`
 
 ---
 
-## 通过 CLI 创建闪卡
+## 5. 通过 CLI 创建闪卡
 
 ### 使用 edit_tree 新增行
 
-通过箭头分隔符创建：
+通过箭头创建（**禁止在文本中插入 \\\`::\\\`、\\\`;;\\\`、\\\`>>\\\` 等编辑器分隔符**）：
 
 | 要创建的闪卡类型 | edit_tree 新增行格式 | 额外步骤 |
 |:-----------------|:--------------------|:---------|
@@ -90,7 +92,7 @@ RemNote 推荐的知识结构化方法：
 | 多行正向 | \\\`问题 ↓\\\`（子行为答案） | — |
 | 多行双向 | \\\`问题 ↕\\\`（子行为答案） | — |
 
-### 使用 edit_rem 修改现有闪卡
+### 使用 edit_rem 修改现有 Rem 的闪卡行为
 
 修改闪卡行为的相关字段：
 
@@ -104,7 +106,7 @@ RemNote 推荐的知识结构化方法：
 
 ---
 
-## 完形填空（Cloze）
+## 6. 完形填空（Cloze）
 
 完形填空通过 RichText 中的 \\\`cId\\\` 标记实现：
 

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.1",
+  "version": "0.1.3",
   "description": "RemNote 自动化桥接工具集：CLI + MCP Server + Plugin",
   "type": "module",
   "bin": {
@@ -23,8 +23,7 @@
     "remnote-plugin/tailwind.config.js",
     "remnote-plugin/webpack.config.js",
     "remnote-plugin/tsconfig.json",
-    "skill/",
-    "docs/instruction/"
+    "skills/"
   ],
   "scripts": {
     "build": "tsc",

package/{skill → skills/remnote-bridge}/SKILL.md

@@ -7,21 +7,21 @@ description: "RemNote 知识库操作指南。通过 remnote-bridge 命令行工
 
 本 skill 指导 AI Agent 通过 remnote-bridge 操作 RemNote 知识库。
 
-**详细命令文档**位于 `docs/instruction/` 目录下，执行具体命令前务必先读取对应文件：
+**详细命令文档**位于 `instructions/` 目录下，执行具体命令前务必先读取对应文件：
 
 | 命令 | 文档路径 |
 |:-----|:---------|
-| connect | `docs/instruction/connect.md` |
-| disconnect | `docs/instruction/disconnect.md` |
-| health | `docs/instruction/health.md` |
-| read-rem | `docs/instruction/read-rem.md` |
-| edit-rem | `docs/instruction/edit-rem.md` |
-| read-tree | `docs/instruction/read-tree.md` |
-| edit-tree | `docs/instruction/edit-tree.md` |
-| read-globe | `docs/instruction/read-globe.md` |
-| read-context | `docs/instruction/read-context.md` |
-| search | `docs/instruction/search.md` |
-| 全局概览 | `docs/instruction/overall.md` |
+| connect | `instructions/connect.md` |
+| disconnect | `instructions/disconnect.md` |
+| health | `instructions/health.md` |
+| read-rem | `instructions/read-rem.md` |
+| edit-rem | `instructions/edit-rem.md` |
+| read-tree | `instructions/read-tree.md` |
+| edit-tree | `instructions/edit-tree.md` |
+| read-globe | `instructions/read-globe.md` |
+| read-context | `instructions/read-context.md` |
+| search | `instructions/search.md` |
+| 全局概览 | `instructions/overall.md` |
 
 ---
 
@@ -42,7 +42,7 @@ RemNote 中所有内容的基本单元都是 **Rem**。文档、文件夹、闪
 
 两个独立维度：
 
-- **type**（闪卡语义）：`concept`（`::`，加粗）、`descriptor`（`;;`，斜体）、`default`（普通）、`portal`（只读）
+- **type**（闪卡语义）：`concept`（加粗）、`descriptor`（正常字重）、`default`（普通）、`portal`（只读）
 - **isDocument**（页面语义）：与 type 完全独立
 
 ### CDF 框架（Concept-Descriptor Framework）
@@ -55,19 +55,30 @@ RemNote 推荐的知识结构化方法：
   损失函数 ;; 均方误差 (MSE)        ← Descriptor
 ```
 
-### 分隔符与闪卡方向
+### 闪卡的 CLI 操作方式
 
-| 分隔符 | type | 默认方向 | 用途 |
-|:-------|:-----|:---------|:-----|
-| `::` | concept | both | 概念定义 |
-| `;;` | descriptor | forward | 描述属性 |
-| `>>` | default | forward | 正向问答 |
-| `<<` | default | backward | 反向问答 |
-| `<>` | default | both | 双向问答 |
-| `>>>` | default | forward | 多行答案 |
-| `::>` | concept | both | 概念型多行答案 |
-| `;;>` | descriptor | forward | 描述型多行答案 |
-| `{{}}` | default | forward | 完形填空 |
+闪卡由 `type`、`backText`、`practiceDirection` 三个字段控制。通过 CLI 操作闪卡，修改的是这些**字段**。
+
+**禁止**：在文本中插入分隔符（`::`、`;;`、`>>`、`<<` 等）来创建闪卡。分隔符是 RemNote 编辑器的输入语法，CLI 无法识别。
+
+| 闪卡操作 | CLI 方法 |
+|:---------|:---------|
+| 创建概念定义 | `edit-tree` 新增行 `概念 ↔ 定义`，再 `edit-rem` 设 `type: "concept"` |
+| 创建正向问答 | `edit-tree` 新增行 `问题 → 答案` |
+| 创建多行答案 | `edit-tree` 新增行 `问题 ↓`（子行自动成为答案） |
+| 改变闪卡类型 | `edit-rem` 修改 `type`、`backText`、`practiceDirection` |
+
+### 理解用户意图：分隔符映射
+
+用户在 RemNote 编辑器中通过分隔符创建闪卡。当用户提到这些分隔符时，理解其意图并映射到上述 CLI 操作：
+
+| 用户说 / 编辑器分隔符 | 对应 type | 对应 practiceDirection |
+|:----------------------|:----------|:----------------------|
+| `::` | concept | both |
+| `;;` | descriptor | forward |
+| `>>` / `<<` / `<>` | default | forward / backward / both |
+| `>>>` / `::>` / `;;>` | default / concept / descriptor | 多行（子 Rem 为答案） |
+| `{{}}` | default | forward（完形填空） |
 
 ### 三种链接机制
 
@@ -87,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` |
+#### 元素类型
+
+| `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` |
 
-**序列化确定性**：RichText 对象内部按 **key 字母序排列**（如 `{"b":true,"i":"m","text":"粗体"}`），确保 JSON 始终一致。构造 edit-rem 的 oldStr 时必须保持相同的 key 顺序，否则匹配失败。
+**注意**：`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 机制与噪音过滤
 
@@ -141,16 +226,35 @@ Rem 的属性（文本、类型、格式、标签）  → edit-rem   （前置
 
 ## 3. 标准工作流
 
+### ⚠️ connect 后需要用户配合（重要）
+
+`connect` 成功只意味着 daemon 和 webpack-dev-server 已启动，**Plugin 并未自动连接**。用户必须在 RemNote 中完成操作，Plugin 才能连接到 daemon：
+
+**首次使用**（RemNote 从未加载过此插件）：
+1. 打开 RemNote 桌面端或网页端
+2. 点击左侧边栏底部的插件图标（拼图形状）
+3. 点击「开发你的插件」（Develop Your Plugin）
+4. 在输入框中填入 `http://localhost:8080`（即 connect 输出的 webpack-dev-server 地址）
+5. 等待插件加载完成
+
+**非首次使用**（之前已加载过此插件）：
+- 只需**刷新 RemNote 页面**即可（浏览器 F5 或 Cmd+R），插件会自动重新连接
+
+**你必须**：执行 `connect` 后，**立即告知用户需要完成上述操作**，不要直接调用业务命令。引导用户完成后，用 `health` 确认三层就绪再继续。
+
+### 完整流程
+
 ```
 1. connect              -- 启动会话（幂等，重复调用安全）
-2. health               -- 确认三层就绪：daemon → Plugin → SDK（链式依赖）
-3. read-globe           -- 了解知识库结构（首次探索）
+2. ⚠️ 引导用户在 RemNote 中加载插件（首次填端口，非首次刷新页面）
+3. health               -- 确认三层就绪：daemon → Plugin → SDK（链式依赖）
+4. read-globe           -- 了解知识库结构（首次探索）
    或 read-context      -- 了解用户当前上下文
-4. search "关键词"       -- 定位目标 Rem（结果不进缓存！）
-5. read-tree <id>       -- 展开子树 → 写入缓存（edit-tree 的前置）
-6. read-rem <id>        -- 读取属性 → 写入缓存（edit-rem 的前置）
-7. edit-rem / edit-tree -- 执行修改
-8. disconnect           -- 结束会话（缓存全部清空，幂等）
+5. search "关键词"       -- 定位目标 Rem（结果不进缓存！）
+6. read-tree <id>       -- 展开子树 → 写入缓存（edit-tree 的前置）
+7. read-rem <id>        -- 读取属性 → 写入缓存（edit-rem 的前置）
+8. edit-rem / edit-tree -- 执行修改
+9. disconnect           -- 结束会话（缓存全部清空，幂等）
 ```
 
 **超时**：daemon 默认 30 分钟无 CLI 交互自动关闭，每次请求重置计时器。长时间操作间可用 health 保活。
@@ -299,12 +403,12 @@ read-tree / read-globe / read-context 输出 Markdown 大纲，edit-tree 基于
 
 ### 新增行格式
 
-新增行可用 Markdown 前缀和箭头分隔符：
+新增行可用 Markdown 前缀和箭头：
 
 ```markdown
   # 新标题
   新闪卡 → 答案
-  概念 :: 定义
+  问题 ↔ 回答
   - [ ] 新待办
   `代码块`
 ```

package/{docs/instruction → skills/remnote-bridge/instructions}/connect.md

@@ -18,6 +18,30 @@ daemon 启动后脱离父进程（detached），CLI 进程退出但 daemon 继
 
 ---
 
+## ⚠️ connect 后需要用户配合
+
+`connect` 成功只意味着 daemon 和 webpack-dev-server 已启动，**Plugin 并未自动连接**。用户必须在 RemNote 中完成以下操作：
+
+### 首次使用（RemNote 从未加载过此插件）
+
+1. 打开 RemNote 桌面端或网页端
+2. 点击左侧边栏底部的插件图标（拼图形状）
+3. 点击「开发你的插件」（Develop Your Plugin）
+4. 在输入框中填入 `http://localhost:8080`（即 connect 输出的 webpack-dev-server 地址）
+5. 等待插件加载完成
+
+### 非首次使用（之前已加载过此插件）
+
+只需**刷新 RemNote 页面**即可（浏览器 F5 或 Cmd+R），插件会自动重新连接到已启动的 daemon。
+
+### AI Agent 注意事项
+
+- 执行 `connect` 后，**必须立即告知用户完成上述操作**
+- **禁止在 connect 后直接调用业务命令**——此时 Plugin 尚未连接，命令会报 "Plugin 未连接" 错误
+- 引导用户完成操作后，用 `health` 确认三层就绪（daemon → Plugin → SDK），再执行业务命令
+
+---
+
 ## 用法
 
 ### 人类模式