remnote-bridge 0.1.15 → 0.1.17

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

@@ -310,9 +310,10 @@ Agent 需要根据用户意图选择正确的读取命令：
 │   适合：首次探索、了解知识库组织
 │
 ├─ 用户当前在看什么 → read-context
-│   ├─ focus 模式（默认）：以用户聚焦的 Rem 为中心的鱼眼视图
-│   │   焦点本身展开 depth=3，siblings 浅层展开，祖先路径可见
-│   └─ page 模式：以当前打开页面为根展开子树
+│   ├─ page 模式（默认，推荐）：以当前打开页面为根展开子树
+│   │   只需有打开的页面即可，几乎总能成功
+│   └─ focus 模式（仅特定场景）：以用户光标所在 Rem 为中心的鱼眼视图
+│       需用户光标停在某个 Rem 上，否则报错；仅当需要定位光标位置时使用
 │
 ├─ 某个具体 Rem 的子树 → read-tree <remId>
 │   完整展开子树（支持深度/节点预算控制）
@@ -339,8 +340,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 +355,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。
 
@@ -613,7 +621,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 至关重要。
 
 ---
 
@@ -642,9 +650,17 @@ read-tree / read-globe / read-context 的输出核心是 Markdown 大纲文本
 | `### ` | H3 标题 | `fontSize: 'H3'` |
 | `- [ ] ` | 未完成待办 | `isTodo: true, todoStatus: 'Unfinished'` |
 | `- [x] ` | 已完成待办 | `isTodo: true, todoStatus: 'Finished'` |
+| `> ` | 引用块 | `isQuote: true` |
+| `1. ` | 有序列表项（⚠️ 见下方说明） | `isListItem: true` |
 | `` `...` `` | 代码块 | `isCode: true` |
 | `---` | 分隔线 | Divider Powerup |
 
+> **⚠️ 有序列表必须用 `1. ` 前缀（Lazy Numbering）**
+>
+> RemNote 有序列表采用 Lazy Numbering——所有列表项统一写 `1. `，RemNote 按层级自动编号（1./2./3./A./B./I./II.）。不要手动编号。
+> - `2. `~`9. ` 会被容错处理（归一化为 `isListItem=true`，返回 `templateWarnings` 警告）
+> - `10. ` 及以上**不会**被识别为有序列表，而是作为纯文本内容保留
+
 ### 8.3 箭头分隔符
 
 箭头编码 `practiceDirection`（闪卡练习方向），不编码 type（type 由元数据标记承载）。
@@ -741,13 +757,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：字段白名单校验
 
@@ -773,7 +794,8 @@ oldStr 必须在目标文本中恰好匹配 1 次
 | 场景 | 缓存行为 |
 |:-----|:---------|
 | 写入全部成功 | 从 SDK 重新读取最新状态 → **更新缓存** |
-| 防线拒绝（缓存缺失 / 并发冲突） | **不更新缓存**（迫使 Agent 重新 read） |
+| 仅元数据变化（位置/时间戳等） | **静默刷新缓存并放行**（返回警告） |
+| 语义字段冲突（内容/类型/格式等） | **不更新缓存**（迫使 Agent 重新 read） |
 | 枚举值非法 | **报错拒绝**，不更新缓存 |
 | 部分写入失败 | **不更新缓存** |
 
@@ -811,6 +833,8 @@ edit-tree 使用 str_replace 对 Markdown 大纲进行结构编辑。详细文
   # 新标题 H1
   新闪卡 → 答案
   - [ ] 新待办
+  > 引用内容
+  1. 列表项
   `代码块内容`
 ```
 
@@ -849,7 +873,7 @@ RemNote 的格式设置通过 Powerup 机制实现，会向 Rem 注入隐藏的
     "readTreeAncestorLevels": 0,
     "readTreeIncludePowerup": false,
     "readGlobeDepth": -1,
-    "readContextMode": "focus",
+    "readContextMode": "page",
     "readContextAncestorLevels": 2,
     "readContextDepth": 3,
     "searchNumResults": 20
@@ -893,7 +917,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-test/SKILL.md

@@ -140,6 +140,9 @@ Skill 接口加 `s` 后缀（**s** = Skill）。这样两个 subagent 创建的
 ### Step 2：构造 subagent 并执行
 
 使用 haiku subagent 执行测试。
+严禁只使用单个 sub-agent 进行测试。
+除非测试用例有特别说明，否则必须同时启用 MCP 和 Skill 两个 sub-agent 进行测试。根据测试要求，动态决定是否并行。
+严禁只测一个 sub-agent 的行为。
 
 #### 双接口策略
 

package/skills/remnote-bridge-test/references/regression-suite.md

@@ -270,6 +270,70 @@
 
 ---
 
+### L2-05: Markdown 前缀转换（有序列表 + 引用块）
+
+**task_description**:
+```
+测试 Markdown 前缀（有序列表 `1. ` 和引用块 `> `）的双向转换能力。
+
+1. 确认连接正常
+2. 读取测试页面的子树（read_tree）
+3. 在测试页面下创建以下结构（edit_tree），包含有序列表和引用块，层级嵌套到 4 层：
+
+   {prefix} Markdown 前缀测试
+     ## 有序列表测试
+       1. 第一层列表项A
+         1. 第二层列表项A-1
+           1. 第三层列表项A-1-a
+             1. 第四层列表项A-1-a-i
+             1. 第四层列表项A-1-a-ii
+           1. 第三层列表项A-1-b
+         1. 第二层列表项A-2
+       1. 第一层列表项B
+         1. 第二层列表项B-1
+         1. 第二层列表项B-2
+           1. 第三层列表项B-2-a
+     ## 引用块测试
+       > 这是一段引用文本
+       > 这是另一段引用
+       普通文本（不是引用）
+     ## 混合格式测试
+       1. 有序列表项带闪卡 → 答案内容
+       > 引用块带闪卡 → 引用中的答案
+       - [ ] 待办事项
+       `代码块内容`
+
+4. 重新读取子树（read_tree，depth=5），验证：
+   - 有序列表项都有 `1. ` 前缀
+   - 引用块都有 `> ` 前缀
+   - 4 层嵌套的有序列表层级正确
+   - 普通文本没有 `1. ` 或 `> ` 前缀
+   - 混合格式中各前缀正确（`1. `、`> `、`- [ ] `、反引号）
+
+5. 对任意 2 个有序列表节点和 1 个引用块节点执行 read_rem，验证：
+   - 有序列表节点 isListItem=true
+   - 引用块节点 isQuote=true
+   - 普通文本节点 isListItem=false, isQuote=false
+```
+
+**Chrome 验证**：
+- ⬜ "{prefix} Markdown 前缀测试" 存在
+- ⬜ "有序列表测试" 下的节点显示为数字编号（1. 2. 3...），而非 bullet
+- ⬜ 有序列表嵌套到 4 层，每层都有数字编号
+- ⬜ "引用块测试" 下有灰色引用样式（左侧竖线 + 浅灰背景）
+- ⬜ "普通文本（不是引用）" 是正常样式，没有引用标记
+- ⬜ 混合格式区域各格式正确（有序列表、引用、待办、代码块共存）
+
+**断言**：
+- [ ] edit_tree 成功创建包含 `1. ` 和 `> ` 前缀的结构
+- [ ] read_tree 输出中有序列表项带 `1. ` 前缀
+- [ ] read_tree 输出中引用块带 `> ` 前缀
+- [ ] 4 层嵌套有序列表结构完整
+- [ ] read_rem 确认 isListItem=true / isQuote=true
+- [ ] 混合格式互不干扰
+
+---
+
 ## L3 多步工作流
 
 > 多步骤组合链路，模拟真实的知识整理流程。