remnote-bridge 0.1.1 → 0.1.3

package/{docs/instruction → 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/{docs/instruction → skills/remnote-bridge/instructions}/overall.md

@@ -51,7 +51,7 @@ Agent 的核心任务是将用户的自然语言请求翻译为 CLI 命令。以
 | 用户表述 | 操作类型 | CLI 命令 |
 |:---------|:---------|:---------|
 | "改文本"、"改标题"、"改颜色"、"改类型" | 修改 Rem 属性 | `edit-rem` |
-| "创建一个概念定义 (::)" | 修改 type + backText | `edit-rem` |
+| "创建一个概念定义"、"做个 :: 卡" | 新增行（edit-tree 箭头）+ 改 type（edit-rem） | `edit-tree` + `edit-rem` |
 | "新增一个子节点"、"添加笔记" | 结构操作：新增 | `edit-tree` |
 | "删除这个"、"移除" | 结构操作：删除 | `edit-tree` |
 | "移动到…下面" | 结构操作：移动 | `edit-tree` |
@@ -66,42 +66,52 @@ Rem 有两个**独立维度**的类型：
 
 #### type 字段（闪卡语义）
 
-| type 值 | 触发分隔符 | 含义 | UI 表现 |
-|:--------|:----------|:-----|:--------|
-| `concept` | `::` 或 `::>` | 概念定义 | 文字**加粗** |
-| `descriptor` | `;;` 或 `;;>` | 描述/属性 | 文字*斜体* |
-| `default` | 无分隔符 / `>>` / `<<` / `<>` / `>>>` / `{{}}` | 普通 Rem | 正常字重 |
-| `portal` | — | 嵌入引用容器 | 紫色左边框（**只读**，不可通过 setType 设置） |
+| type 值 | 含义 | UI 表现 | CLI 设置方式 |
+|:--------|:-----|:--------|:-------------|
+| `concept` | 概念定义 | 文字**加粗** | `edit-rem` 设 `type: "concept"` |
+| `descriptor` | 描述/属性 | 文字*斜体* | `edit-rem` 设 `type: "descriptor"` |
+| `default` | 普通 Rem | 正常字重 | `edit-rem` 设 `type: "default"` |
+| `portal` | 嵌入引用容器 | 紫色左边框 | **只读**，不可通过 CLI 设置 |
 
 #### isDocument 字段（页面语义）
 
 `isDocument` 与 `type` 完全独立——一个 `concept` 类型的 Rem 可以同时是 Document。
 
-### 2.4 分隔符与闪卡
+### 2.4 闪卡的 CLI 操作方式
 
-用户输入的分隔符决定了 Rem 的 `type`、`backText` 和默认 `practiceDirection`。理解分隔符是理解用户创建闪卡意图的关键。
+闪卡由 `type`、`backText`、`practiceDirection` 三个字段控制。通过 CLI 操作闪卡，修改的是这些**字段**和大纲**箭头**。
 
-| 分隔符 | type | backText | 默认方向 | 用途 |
-|:-------|:-----|:---------|:---------|:-----|
-| （无） | `default` | `null` | — | 无闪卡行为 |
-| `::` | `concept` | 后半部分 | `both` | 概念定义（CDF 框架） |
-| `;;` | `descriptor` | 后半部分 | `forward` | 描述属性（CDF 框架） |
-| `>>` | `default` | 后半部分 | `forward` | 正向问答 |
-| `<<` | `default` | 后半部分 | `backward` | 反向问答 |
-| `<>` | `default` | 后半部分 | `both` | 双向问答 |
-| `>>>` | `default` | `null` | `forward` | 多行答案（子 Rem 为答案） |
-| `::>` | `concept` | `null` | `both` | 概念型多行答案 |
-| `;;>` | `descriptor` | `null` | `forward` | 描述型多行答案 |
-| `{{}}` | `default` | `null` | `forward` | 完形填空（Cloze） |
+**禁止**：在文本中插入分隔符（`::`、`;;`、`>>`、`<<` 等）来创建闪卡。分隔符是 RemNote 编辑器的输入语法，CLI 无法识别。
 
-**重要**：分隔符决定创建时的**默认**方向，用户可以事后独立修改 `practiceDirection`。`practiceDirection` 的取值：`forward`（正向）、`backward`（反向）、`both`（双向）、`none`（不练习）。
+| 闪卡操作 | CLI 方法 |
+|:---------|:---------|
+| 创建概念定义 | `edit-tree` 新增行 `概念 ↔ 定义`，再 `edit-rem` 设 `type: "concept"` |
+| 创建正向问答 | `edit-tree` 新增行 `问题 → 答案` |
+| 创建反向问答 | `edit-tree` 新增行 `问题 ← 答案` |
+| 创建双向问答 | `edit-tree` 新增行 `问题 ↔ 答案` |
+| 创建多行答案 | `edit-tree` 新增行 `问题 ↓`（子行自动成为答案） |
+| 改变闪卡类型/方向 | `edit-rem` 修改 `type`、`backText`、`practiceDirection` |
 
-**CDF（Concept-Descriptor Framework）**：RemNote 推荐的知识结构化方法——`Concept` 是需要理解的概念，`Descriptor` 是概念的属性/描述。典型结构：
+`practiceDirection` 的取值：`forward`（正向）、`backward`（反向）、`both`（双向）、`none`（不练习）。
+
+### 2.5 理解用户意图：编辑器分隔符映射
+
+用户在 RemNote 编辑器中通过分隔符创建闪卡。当用户提到这些分隔符时，理解其意图并映射到上述 CLI 操作：
+
+| 用户说 / 编辑器分隔符 | 对应 type | 对应 practiceDirection |
+|:----------------------|:----------|:----------------------|
+| `::` | concept | both |
+| `;;` | descriptor | forward |
+| `>>` / `<<` / `<>` | default | forward / backward / both |
+| `>>>` / `::>` / `;;>` | default / concept / descriptor | 多行（子 Rem 为答案） |
+| `{{}}` | default | forward（完形填空） |
+
+**CDF（Concept-Descriptor Framework）**：RemNote 推荐的知识结构化方法——`Concept`（type:concept）是需要理解的概念，`Descriptor`（type:descriptor）是概念的属性/描述。在 CLI 大纲中的表现：
 
 ```
-线性回归 :: 最基本的回归模型        ← Concept
-  假设 ;; 因变量与自变量呈线性关系   ← Descriptor
-  损失函数 ;; 均方误差 (MSE)        ← Descriptor
+线性回归 ↔ 最基本的回归模型 <!--id1 type:concept-->
+  假设 → 因变量与自变量呈线性关系 <!--id2 type:descriptor-->
+  损失函数 → 均方误差 (MSE) <!--id3 type:descriptor-->
 ```
 
 ### 2.5 三种链接机制
@@ -170,11 +180,17 @@ RemNote SDK → 知识库
 一次**会话（Session）= 守护进程的生命周期**。
 
 ```
-connect → daemon 启动 → 会话开始
+connect → daemon 启动
+  ↓
+⚠️ 用户在 RemNote 中加载插件（首次填端口，非首次刷新页面）
+  ↓
+health → 确认三层就绪 → 会话可用
   ↕ (业务命令：read-rem, edit-tree, search, ...)
 disconnect → daemon 关闭 → 会话结束，缓存清空
 ```
 
+> **重要**：`connect` 成功只意味着 daemon 已启动，Plugin 并未自动连接。首次使用需用户在 RemNote「开发你的插件」中填入 `http://localhost:8080`；非首次只需刷新 RemNote 页面。必须引导用户完成此步后再用 `health` 确认就绪。
+
 `connect` 启动三个服务：
 
 | 服务 | 默认端口 | 用途 |
@@ -322,18 +338,19 @@ Agent 需要根据用户意图选择正确的读取命令：
 
 ```
 1. connect              ← 启动会话
-2. health               ← 确认系统就绪
-3. read-globe           ← 了解知识库结构（首次探索）
+2. ⚠️ 引导用户在 RemNote 中加载插件（首次填端口，非首次刷新页面）
+3. health               ← 确认系统就绪（daemon → Plugin → SDK 三层全通过）
+4. read-globe           ← 了解知识库结构（首次探索）
    或 read-context      ← 了解用户当前上下文
-4. search "关键词"       ← 定位目标 Rem（中文搜索可能需单字策略，详见 search.md）
-5. read-tree <id>       ← 展开目标区域的子树
-6. read-rem <id>        ← 读取详细属性（编辑前必需）
-7. edit-rem <id> ...    ← 修改 Rem 属性
+5. search "关键词"       ← 定位目标 Rem（中文搜索可能需单字策略，详见 search.md）
+6. read-tree <id>       ← 展开目标区域的子树
+7. read-rem <id>        ← 读取详细属性（编辑前必需）
+8. edit-rem <id> ...    ← 修改 Rem 属性
    或 edit-tree <id> ...← 修改树结构
-8. disconnect           ← 结束会话
+9. disconnect           ← 结束会话
 ```
 
-**注意**：步骤 6 是 `edit-rem` 的强制前置条件，步骤 5 是 `edit-tree` 的强制前置条件。跳过会触发防线 1 错误。
+**注意**：步骤 7 是 `edit-rem` 的强制前置条件，步骤 6 是 `edit-tree` 的强制前置条件。跳过会触发防线 1 错误。步骤 2 是必须的——connect 后不引导用户加载插件就直接调用业务命令，会报"Plugin 未连接"错误。
 
 ---
 
@@ -457,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` |
+#### 元素类型
+
+| `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()`），确保同一内容的 JSON 始终一致。这对 edit-rem 的 str_replace 和并发检测至关重要。
+**序列化确定性**：RichText 对象内部按 key 字母序排列（`sortRichTextKeys()`）。`_id` 的 `_`（U+005F）排在所有小写字母之前。这对 edit-rem 的 str_replace 和并发检测至关重要。
 
 ---
 

package/{docs/instruction → 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 过滤