remnote-bridge 0.1.16 → 0.1.18

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

@@ -1,6 +1,6 @@
 # edit-tree
 
-> 通过 str_replace 对 Markdown 大纲进行结构编辑（行级增/删/移/重排），禁止修改已有行内容。
+> 通过 str_replace 对 Markdown 大纲进行结构编辑（行级增/删/移/重排），新增行支持 `{{文本}}` 填空语法，禁止修改已有行内容。
 
 ---
 
@@ -9,14 +9,14 @@
 `edit-tree` 基于 `read-tree` 缓存的 Markdown 大纲，使用 str_replace 替换文本片段，解析新旧大纲的结构差异，自动生成并执行原子操作。
 
 核心能力：
-- **新增行**：在大纲中插入无 remId 的新行，支持 Markdown 前缀和箭头分隔符
+- **新增行**：在大纲中插入无 remId 的新行，支持 Markdown 前缀、箭头分隔符、`{{文本}}` 填空语法
 - **删除行**：从大纲中移除带 remId 的行（必须同时删除所有子行）
 - **移动行**：改变行的缩进层级或移到不同父节点下
 - **重排行**：调换同级行的顺序
 - 三道防线保障数据安全（缓存存在性、乐观并发检测、精确匹配）
 - SDK bug 自动修复（practiceDirection 保护）
 
-**核心限制**：仅支持结构操作，**禁止修改已有行的内容**——内容修改走 `edit-rem`。
+**核心限制**：**禁止修改已有行的内容**（内容修改走 `edit-rem`）。新增行的内容格式不受此限，支持 Markdown 前缀、箭头、`{{文本}}` 填空等。
 
 ---
 
@@ -204,7 +204,7 @@ newStr: "  新增行\n  {{idZ}}"
 - `{{remId}}` 展开为**不含缩进**的完整行内容，缩进由你控制
 - 只匹配纯字母数字（`[a-zA-Z0-9]+`），与 RemNote cloze 语法 `{{text}}` 不冲突
 - 匹配到但不在缓存大纲中的 `{{xxx}}` 原样保留（可能是 cloze），并输出 templateWarnings
-- 新增行没有 remId，不能用模板表示
+- 新增行不能用 `{{remId}}` 模板引用（没有 remId），但可以用 `{{文本}}` 创建填空卡片（两者不冲突：模板只匹配纯字母数字）
 
 ### 完整匹配模式（回退）
 
@@ -338,6 +338,22 @@ oldStr: "  子节点 A <!--idA-->"
 newStr: "  <!--portal refs:refId1,refId2-->\n  子节点 A <!--idA-->"
 ```
 
+#### 完形填空新增行
+
+在新增行内容中使用 `{{文本}}` 语法创建填空卡片。SDK 通过 `createSingleRemWithMarkdown` 自动生成唯一 cId，零碰撞风险。**这是创建填空的推荐方式**（优于 edit-rem 手动编造 cId）。
+
+```
+# 模板模式
+oldStr: "  {{idA}}"
+newStr: "  水的化学式是{{H2O}}\n  {{idA}}"
+
+# 完整匹配模式
+oldStr: "  子节点 A <!--idA-->"
+newStr: "  法国的首都是{{巴黎}}\n  子节点 A <!--idA-->"
+```
+
+> 注意：`{{文本}}` 与模板引用 `{{remId}}` 不冲突——模板只匹配纯字母数字（`[a-zA-Z0-9]+`），中文/空格/标点不会被误匹配。
+
 #### 嵌套新增
 
 新增行下面可以再嵌套新增行，通过缩进表示父子关系：
@@ -435,6 +451,8 @@ newStr: "  子节点 C <!--idC-->\n  子节点 A <!--idA-->\n  子节点 B <!--i
 | 缩进跳级 | `indent_skip` | 缩进跳级：行 ... 的缩进级别为 N，但找不到上一级的父节点。 | 检查缩进是否正确（每级 2 空格） |
 | 新行劫持已有子节点 | `children_captured` | New line "..." accidentally captured existing children (...). | 把新行插到兄弟末尾，不要插在父 Rem 和 children 之间 |
 
+> ⚠️ "修改已有行内容 → 使用 edit-rem"仅指**修改已存在 Rem 的文本**。创建含 `{{文本}}` 填空的**新行**应使用 edit-tree 的新增行功能，不要走 edit-rem 手动编造 cId。
+
 ---
 
 ## 操作执行顺序

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

@@ -91,6 +91,7 @@ Rem 有两个**独立维度**的类型：
 | 创建反向问答 | `edit-tree` 新增行 `问题 ← 答案` |
 | 创建双向问答 | `edit-tree` 新增行 `问题 ↔ 答案` |
 | 创建多行答案 | `edit-tree` 新增行 `问题 ↓`（子行自动成为答案） |
+| 创建完形填空 | `edit-tree` 新增行写 `水的化学式是{{H2O}}`（SDK 自动生成安全 cId，⚠️ **禁止**用 `edit-rem` 手动编造 cId） |
 | 改变闪卡类型/方向 | `edit-rem` 修改 `type`、`backText`、`practiceDirection` |
 
 `practiceDirection` 的取值：`forward`（正向）、`backward`（反向）、`both`（双向）、`none`（不练习）。
@@ -310,9 +311,10 @@ Agent 需要根据用户意图选择正确的读取命令：
 │   适合：首次探索、了解知识库组织
 │
 ├─ 用户当前在看什么 → read-context
-│   ├─ focus 模式（默认）：以用户聚焦的 Rem 为中心的鱼眼视图
-│   │   焦点本身展开 depth=3，siblings 浅层展开，祖先路径可见
-│   └─ page 模式：以当前打开页面为根展开子树
+│   ├─ page 模式（默认，推荐）：以当前打开页面为根展开子树
+│   │   只需有打开的页面即可，几乎总能成功
+│   └─ focus 模式（仅特定场景）：以用户光标所在 Rem 为中心的鱼眼视图
+│       需用户光标停在某个 Rem 上，否则报错；仅当需要定位光标位置时使用
 │
 ├─ 某个具体 Rem 的子树 → read-tree <remId>
 │   完整展开子树（支持深度/节点预算控制）
@@ -339,8 +341,8 @@ Agent 需要根据用户意图选择正确的读取命令：
 | 场景 | 命令 | 输出特点 |
 |:-----|:-----|:---------|
 | "看看知识库有什么" | `read-globe` | 仅 Document 层级，无内容 Rem |
-| "我现在在编辑什么" | `read-context --mode focus` | 鱼眼视图，焦点处详细 |
-| "当前页面的内容" | `read-context --mode page` | 以页面为根展开 |
+| "当前页面的内容" | `read-context` | 以页面为根展开（默认，推荐） |
+| "我光标在哪" / "我正在编辑的 Rem" | `read-context --mode focus` | 鱼眼视图（需光标在某 Rem 上，否则报错） |
 | "展开某个主题的细节" | `read-tree <id>` | 完整子树，可缓存供编辑 |
 | "展开子树并查看每个节点属性" | `read-rem-in-tree <id>` | 大纲 + RemObject，双重缓存 |
 
@@ -354,18 +356,25 @@ Agent 需要根据用户意图选择正确的读取命令：
 
 #### read-context 特性
 
-**focus 模式**（默认）：
-- 获取用户当前聚焦的 Rem（需要用户在 RemNote 中点击某个 Rem）
-- 鱼眼视图展开策略：焦点 depth=3，焦点的 siblings depth=1，叔伯节点 depth=0
-- 向上追溯 `ancestorLevels` 层（默认 2）
-- 焦点 Rem 前标记 `* ` 前缀
-- 输出头部含 path 和 focus 信息
+**模式选择指引**：
+- **绝大多数场景用 page（默认）**——用户通常只是打开页面浏览，不会特意点击某个 Rem 让光标停在上面。page 只需有打开的页面就能工作，几乎总能成功
+- **仅当需要定位用户光标时用 focus**——如用户说"我正在编辑的这个"、"光标所在的 Rem"。focus 要求光标停在某个 Rem 上，否则报错"当前没有聚焦的 Rem"
+- **不确定时用 page**——最坏情况只是展开整个页面；focus 的最坏情况是报错
 
-**page 模式**：
+**page 模式**（默认，推荐）：
 - 获取当前面板打开的页面 Rem
 - 以该页面为根展开子树
 - 参数：`depth`（默认 3）、`maxNodes`、`maxSiblings`
 - 输出头部含 page 名和 breadcrumb path
+- 前置条件宽松：只需有打开的页面
+
+**focus 模式**（仅特定场景）：
+- 获取用户当前聚焦的 Rem（需要用户在 RemNote 中点击某个 Rem）
+- 鱼眼视图展开策略：焦点 depth=3，焦点的 siblings depth=1，叔伯节点 depth=0
+- 向上追溯 `ancestorLevels` 层（默认 2）
+- 焦点 Rem 前标记 `* ` 前缀
+- 输出头部含 path 和 focus 信息
+- ⚠️ 前置条件严格：用户光标必须停在某个 Rem 上，否则报错
 
 两者共同点：不缓存、Portal 感知、Powerup 噪音过滤、返回 breadcrumb。
 
@@ -581,8 +590,8 @@ Portal：portalType [R], portalDirectlyIncludedRem [Portal-W]
 | `q` | `true` | 行内代码（红色等宽样式） |
 | `code` | `true` | 代码块（带语言标签和复制按钮） |
 | `language` | `string` | 代码块语言（如 `"javascript"`） |
-| `cId` | `string` | 完形填空 ID |
-| `hiddenCloze` | `true` | 完形填空隐藏状态 |
+| `cId` | `string` | 完形填空 ID（由 SDK 自动生成，禁止手动编造——创建填空用 `edit-tree` 的 `{{文本}}` 语法） |
+| `hiddenCloze` | `true` | 完形填空隐藏状态（只读，RemNote 自动管理） |
 | `iUrl` | `string` | 外部超链接 URL（`url` 字段已废弃，必须用 `iUrl`） |
 | `qId` | `string` | 行内引用链接的 Rem ID |
 
@@ -595,7 +604,7 @@ Portal：portalType [R], portalDirectlyIncludedRem [Portal-W]
 { "i": "m", "q": true, "text": "code" }        // 行内代码
 { "i": "m", "iUrl": "https://...", "text": "链接" } // 超链接
 { "b": true, "h": 1, "i": "m", "text": "重点" } // 粗体+红色高亮（h 是数字）
-{ "cId": "c1", "i": "m", "text": "答案" }       // 完形填空
+{ "cId": "4718093625140386", "i": "m", "text": "答案" } // 完形填空（cId 必须随机，禁止用 "c1" 等有语义命名）
 { "_id": "remId", "b": true, "i": "q" }         // Rem 引用加粗（_id 排最前）
 { "i": "x", "text": "E = mc^2" }                // LaTeX
 { "i": "a", "onlyAudio": false, "url": "..." }  // 视频（onlyAudio 必填！）
@@ -613,7 +622,7 @@ Portal：portalType [R], portalDirectlyIncludedRem [Portal-W]
 
 `h` 颜色值：0=无, 1=Red, 2=Orange, 3=Yellow, 4=Green, 5=Purple, 6=Blue, 7=Gray, 8=Brown, 9=Pink。
 
-**序列化确定性**：RichText 对象内部按 key 字母序排列（`sortRichTextKeys()`）。`_id` 的 `_`（U+005F）排在所有小写字母之前。这对乐观并发检测和 edit-tree 的 str_replace 至关重要。
+**序列化确定性**：RichText 对象内部按 key 字母序排列（`sortRichTextKeys()`）。`_id` 的 `_`（U+005F）排在所有小写字母之前。这对语义并发检测和 edit-tree 的 str_replace 至关重要。
 
 ---
 
@@ -749,13 +758,18 @@ read-tree / read-globe / read-context 的输出核心是 Markdown 大纲文本
 
 未缓存的 Rem 不允许编辑。确保 Agent 看到的数据和即将编辑的数据是同一份。
 
-#### 防线 2：乐观并发检测
+#### 防线 2：语义并发检测
 
 ```
-edit 时重新从 SDK 读取最新数据 → 与缓存严格比较
+edit 时重新从 SDK 读取最新数据 → 只比较语义字段（内容、类型、格式、标签等）
 ```
 
-如果 Rem 在 read 之后被外部修改（用户在 RemNote UI 中编辑、其他 Agent 修改等），数据不一致时拒绝编辑，**且不更新缓存**——迫使 Agent 重新 read。
+将 RemObject 字段分为三层：
+- **语义字段**（text, backText, type, tags, highlightColor, fontSize 等）：变化 → 硬拒绝，迫使 Agent 重新 read
+- **敏感元数据**（parent）：变化 → 放行 + `"⚠️ parent has changed (was: oldId, now: newId). The Rem has been moved to a different parent since last read. Proceeding with edit."`
+- **普通元数据**（positionAmongstSiblings, updatedAt, siblingRem, children, descendants 等）：变化 → 放行 + `"ℹ️ Metadata fields changed since last read: {fields}. This is expected after structural operations. Proceeding with edit."`
+
+这意味着 `edit-tree` 移动/重排 Rem 后，可以直接 `edit-rem` 修改受影响节点的文本格式，无需逐个重新 `read-rem`。只有真正的内容/属性并发冲突才会被拦截。
 
 #### edit-rem 防线 3：字段白名单校验
 
@@ -781,7 +795,8 @@ oldStr 必须在目标文本中恰好匹配 1 次
 | 场景 | 缓存行为 |
 |:-----|:---------|
 | 写入全部成功 | 从 SDK 重新读取最新状态 → **更新缓存** |
-| 防线拒绝（缓存缺失 / 并发冲突） | **不更新缓存**（迫使 Agent 重新 read） |
+| 仅元数据变化（位置/时间戳等） | **静默刷新缓存并放行**（返回警告） |
+| 语义字段冲突（内容/类型/格式等） | **不更新缓存**（迫使 Agent 重新 read） |
 | 枚举值非法 | **报错拒绝**，不更新缓存 |
 | 部分写入失败 | **不更新缓存** |
 
@@ -859,7 +874,7 @@ RemNote 的格式设置通过 Powerup 机制实现，会向 Rem 注入隐藏的
     "readTreeAncestorLevels": 0,
     "readTreeIncludePowerup": false,
     "readGlobeDepth": -1,
-    "readContextMode": "focus",
+    "readContextMode": "page",
     "readContextAncestorLevels": 2,
     "readContextDepth": 3,
     "searchNumResults": 20
@@ -903,7 +918,7 @@ Agent 遇到错误时的诊断和恢复指南：
 | 错误 | 原因 | 恢复 |
 |:-----|:-----|:-----|
 | has not been read yet | 未先执行 read-rem / read-tree | 执行对应 read 命令后重试 |
-| has been modified since last read | Rem 在 read 和 edit 之间被外部修改 | 重新执行 read 获取最新状态后重试 |
+| has been modified since last read | Rem 的语义字段在 read 和 edit 之间被外部修改 | 重新执行 read 获取最新状态后重试 |
 
 ### edit-tree str_replace 错误
 

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

@@ -8,8 +8,13 @@
 
 `read-context` 根据用户在 RemNote 中的当前位置，生成上下文感知的 Markdown 大纲。两种模式适用于不同场景：
 
-- **focus 模式**（默认）：以当前焦点 Rem 为中心，向上追溯祖先，构建鱼眼视图——焦点完全展开，周围递减
-- **page 模式**：以当前打开的页面 Rem 为根，均匀展开子树
+- **page 模式**（默认，推荐）：以当前打开的页面 Rem 为根，均匀展开子树。只需有打开的页面即可，几乎总能成功
+- **focus 模式**（仅特定场景）：以当前焦点 Rem 为中心，向上追溯祖先，构建鱼眼视图——焦点完全展开，周围递减。需用户光标停在某个 Rem 上，否则报错
+
+**何时用哪个模式**：
+- 绝大多数场景用 page（默认）——用户通常只是打开页面浏览，不会特意让光标停在某个 Rem 上
+- 仅当需要知道用户光标具体在哪个 Rem 上时才用 focus——如用户说"我正在编辑的这个"、"光标所在位置"
+- 不确定时用 page——最坏情况只是展开整个页面；focus 的最坏情况是报错"当前没有聚焦的 Rem"
 
 核心能力：
 - 鱼眼深度梯度（focus 模式）：焦点 depth=3、siblings depth=1、叔伯 depth=0
@@ -32,7 +37,7 @@ remnote-bridge read-context [--mode <mode>] [--ancestor-levels <N>] [--depth <N>
 
 | 参数/选项 | 类型 | 必需 | 说明 |
 |-----------|------|:----:|------|
-| `--mode <mode>` | string | 否 | 模式：`focus`（默认）或 `page` |
+| `--mode <mode>` | string | 否 | 模式：`page`（默认）或 `focus` |
 | `--ancestor-levels <N>` | integer | 否 | 向上追溯几层祖先（默认 2，仅 focus 模式） |
 | `--depth <N>` | integer | 否 | 展开深度（默认 3，仅 page 模式） |
 | `--max-nodes <N>` | integer | 否 | 全局节点上限（默认 200） |
@@ -84,7 +89,7 @@ remnote-bridge read-context --json '{"mode":"page","depth":5,"maxSiblings":10}'
 
 | 字段 | 类型 | 必需 | 说明 |
 |------|------|:----:|------|
-| `mode` | string | 否 | 模式：`"focus"` 或 `"page"`（默认 `"focus"`） |
+| `mode` | string | 否 | 模式：`"page"` 或 `"focus"`（默认 `"page"`） |
 | `ancestorLevels` | number | 否 | 向上追溯几层祖先（默认 2，仅 focus 模式） |
 | `depth` | number | 否 | 展开深度（默认 3，仅 page 模式） |
 | `maxNodes` | number | 否 | 全局节点上限（默认 200） |
@@ -359,7 +364,7 @@ focus 模式的核心特点是**渐进式展开**——离焦点越近，展开
 
 | 配置项 | 默认值 | 说明 |
 |--------|--------|------|
-| `defaults.readContextMode` | `"focus"` | 默认模式 |
+| `defaults.readContextMode` | `"page"` | 默认模式 |
 | `defaults.readContextAncestorLevels` | 2 | focus 模式默认祖先层数 |
 | `defaults.readContextDepth` | 3 | page 模式默认展开深度 |
 | `defaults.maxNodes` | 200 | 默认全局节点上限 |

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

@@ -182,7 +182,7 @@ RemObject 共 51 个字段，按读写权限分为三类：
 
 | 字段 | 类型 | 权限 | 说明 |
 |------|------|:----:|------|
-| `text` | `RichText` | RW | 正面文本（RichText 数组）。UI：文本内容立即更新显示 |
+| `text` | `RichText` | RW | 正面文本（RichText 数组）。UI：文本内容立即更新显示。⚠️ 若含 cId 元素（完形填空），edit-rem 写回时须原样保留 cId 值 |
 | `backText` | `RichText \| null` | RW | 背面文本。null=无背面；设值即产生闪卡正反面结构。UI：显示为"正面 → 背面"箭头分隔格式 |
 
 ### 类型系统
@@ -487,9 +487,9 @@ RemObject 中的 `text` 和 `backText` 字段使用 RichText 格式——一个
 | `q` | `true` | 行内代码（红色等宽样式） |
 | `code` | `true` | 代码块（带语言标签和复制按钮） |
 | `language` | `string` | 代码块语言（如 `"javascript"`、`"python"`） |
-| `cId` | `string` | 完形填空 ID |
-| `hiddenCloze` | `true` | 完形填空隐藏状态 |
-| `revealedCloze` | `true` | 完形填空已揭示状态 |
+| `cId` | `string` | 完形填空 ID（由 SDK 自动生成，禁止手动编造——创建填空用 `edit-tree` 的 `{{文本}}` 语法。修改已有 cloze 时必须保留原 cId） |
+| `hiddenCloze` | `true` | 完形填空隐藏状态（只读，RemNote 自动管理，禁止通过 edit-rem 写入） |
+| `revealedCloze` | `true` | 完形填空已揭示状态（只读，RemNote 自动管理，禁止通过 edit-rem 写入） |
 | `iUrl` | `string` | 外部超链接 URL（**注意**：`url` 字段已废弃无效，必须用 `iUrl`） |
 | `qId` | `string` | 行内引用链接的 Rem ID |
 
@@ -532,9 +532,9 @@ RemObject 中的 `text` 和 `backText` 字段使用 RichText 格式——一个
   "i": "m",
   "text": "重点"
 }
-// 完形填空
+// 完形填空（⚠️ cId 由 SDK 自动生成。创建填空用 edit-tree {{文本}} 语法；edit-rem 仅修改已有 cloze，必须保留原 cId，禁止手动编造）
 {
-  "cId": "cloze1",
+  "cId": "8291740362058173",
   "i": "m",
   "text": "答案内容"
 }

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

@@ -43,6 +43,7 @@ remnote-bridge read-tree <remId> [--depth N] [--max-nodes N] [--max-siblings N]
   第一部分 <!--id1-->
     小节 1.1 <!--id1_1-->
     小节 1.2 → 答案 <!--id1_2-->
+    法国的首都是{{巴黎}} <!--id1_3-->
   第二部分 <!--id2 children:5-->
 ```
 
@@ -159,7 +160,7 @@ read-tree 的核心输出是 Markdown 大纲文本。每一行对应一个 Rem
 
 - **缩进**：每级 2 个空格（根节点 0 个空格）
 - **Markdown 前缀**：映射 Rem 的格式属性
-- **内容**：Rem 的 text 字段（已通过 SDK 转为 Markdown）
+- **内容**：Rem 的 text 字段（已通过 SDK 转为 Markdown）。RichText 中的完形填空（cloze）元素渲染为 `{{文本}}`（如 `学习 {{Python}} 语言`）。cId 不在大纲中显示；创建新 cloze 用 `edit-tree` 新增行的 `{{文本}}` 语法（SDK 自动生成 cId）
 - **箭头分隔符**：表示 practiceDirection（闪卡方向）
 - **remId**：该行对应的 Rem ID
 - **元数据标记**：空格分隔的属性标记
@@ -225,6 +226,7 @@ read-tree 的核心输出是 Markdown 大纲文本。每一行对应一个 Rem
 # 数据结构 <!--kLr type:concept doc top-->
   ## 线性结构 <!--ABC type:concept-->
     数组 → Array <!--DEF-->
+    {{二分查找}}的时间复杂度是 O(log n) <!--EFG-->
     链表 ↓ <!--GHI type:concept-->
       单向链表 <!--JKL role:card-item-->
       双向链表 <!--MNO role:card-item-->