remnote-bridge 0.1.14 → 0.1.16

package/remnote-plugin/dist/manifest.json

@@ -7,7 +7,7 @@
   "version": {
     "major": 0,
     "minor": 2,
-    "patch": 0
+    "patch": 1
   },
   "theme": [],
   "enableOnMobile": false,

package/remnote-plugin/package.json

@@ -1,7 +1,7 @@
 {
   "private": true,
   "name": "unofficial-remnote-bridge-plugin",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "license": "MIT",
   "description": "RemNote 桥接层：嵌入 RemNote 的 WebSocket 桥接插件",
   "scripts": {

package/remnote-plugin/public/manifest.json

@@ -7,7 +7,7 @@
   "version": {
     "major": 0,
     "minor": 2,
-    "patch": 0
+    "patch": 1
   },
   "theme": [],
   "enableOnMobile": false,

package/remnote-plugin/src/services/read-rem.ts

@@ -211,7 +211,7 @@ export async function buildRemObject(
     portalType: remTypeToString(rem.type as number) === 'portal'
       ? portalTypeToString(portalType as number)
       : null,
-    portalDirectlyIncludedRem: portalDirectlyIncludedRems.map(r => r._id),
+    portalDirectlyIncludedRem: portalDirectlyIncludedRems.map(r => r._id).sort(),
 
     // 属性类型
     propertyType: (propertyType as PropertyTypeValue | undefined) ?? null,
@@ -220,27 +220,27 @@ export async function buildRemObject(
     enablePractice,
     practiceDirection: practiceDirection as RemObject['practiceDirection'],
 
-    // 关联 — 直接关系
-    tags: filteredTagRems.map(r => r._id),
-    sources: sourceRems.map(r => r._id),
-    aliases: aliasRems.map(r => r._id),
+    // 关联 — 直接关系（排序保证确定性序列化）
+    tags: filteredTagRems.map(r => r._id).sort(),
+    sources: sourceRems.map(r => r._id).sort(),
+    aliases: aliasRems.map(r => r._id).sort(),
 
     // 关联 — 引用关系
-    remsBeingReferenced: refsBeingReferenced.map(r => r._id),
-    deepRemsBeingReferenced: deepRefsBeingReferenced.map(r => r._id),
-    remsReferencingThis: refsReferencingThis.map(r => r._id),
+    remsBeingReferenced: refsBeingReferenced.map(r => r._id).sort(),
+    deepRemsBeingReferenced: deepRefsBeingReferenced.map(r => r._id).sort(),
+    remsReferencingThis: refsReferencingThis.map(r => r._id).sort(),
 
     // 关联 — 标签体系
-    taggedRem: taggedRems.map(r => r._id),
-    ancestorTagRem: ancestorTagRems.map(r => r._id),
-    descendantTagRem: descendantTagRems.map(r => r._id),
+    taggedRem: taggedRems.map(r => r._id).sort(),
+    ancestorTagRem: ancestorTagRems.map(r => r._id).sort(),
+    descendantTagRem: descendantTagRems.map(r => r._id).sort(),
 
     // 关联 — 层级遍历
-    descendants: descendantRems.map(r => r._id),
-    siblingRem: siblingRems.map(r => r._id),
-    portalsAndDocumentsIn: portalsAndDocsIn.map(r => r._id),
-    allRemInDocumentOrPortal: allRemInDocOrPortal.map(r => r._id),
-    allRemInFolderQueue: allRemInFolderQ.map(r => r._id),
+    descendants: descendantRems.map(r => r._id).sort(),
+    siblingRem: siblingRems.map(r => r._id).sort(),
+    portalsAndDocumentsIn: portalsAndDocsIn.map(r => r._id).sort(),
+    allRemInDocumentOrPortal: allRemInDocOrPortal.map(r => r._id).sort(),
+    allRemInFolderQueue: allRemInFolderQ.map(r => r._id).sort(),
 
     // 位置 / 统计
     positionAmongstSiblings: position ?? null,

package/remnote-plugin/src/services/rem-builder.ts

@@ -7,7 +7,7 @@
  * 依赖方向：services/rem-builder → utils/tree-serializer（单向）
  */
 
-import type { ReactRNPlugin, PluginRem as Rem } from '@remnote/plugin-sdk';
+import type { ReactRNPlugin, PluginRem as Rem, RichTextInterface } from '@remnote/plugin-sdk';
 import type { SerializableRem } from '../utils/tree-serializer';
 import { filterNoisyTags } from './powerup-filter';
 
@@ -21,7 +21,7 @@ export async function safeToMarkdown(
   richText: unknown[],
 ): Promise<string> {
   try {
-    return await plugin.richText.toMarkdown(richText);
+    return await plugin.richText.toMarkdown(richText as RichTextInterface);
   } catch {
     return richTextFallback(richText);
   }
@@ -93,6 +93,8 @@ export async function buildFullSerializableRem(
     isTodo,
     todoStatus,
     isCode,
+    isQuote,
+    isListItem,
     hasDvPowerup,
     portalIncludedRems,
   ] = await Promise.all([
@@ -114,6 +116,8 @@ export async function buildFullSerializableRem(
     rem.isTodo(),
     rem.getTodoStatus(),
     rem.isCode(),
+    rem.isQuote(),
+    rem.isListItem(),
     rem.hasPowerup('dv'),
     rem.type === 6 ? rem.getPortalDirectlyIncludedRem() : Promise.resolve([]),
   ]);
@@ -151,6 +155,8 @@ export async function buildFullSerializableRem(
     isTodo,
     todoStatus: (todoStatus as 'Finished' | 'Unfinished' | null) ?? null,
     isCode,
+    isQuote,
+    isListItem,
     isDivider,
     isTopLevel: rem.parent === null,
   };

package/remnote-plugin/src/settings.ts

@@ -5,7 +5,7 @@
  * 多 daemon 连接：Plugin 同时连接 ALL_WS_PORTS 对应的 4 个槽位。
  */
 
-export const DEFAULT_PLUGIN_VERSION = '0.2.0';
+export const DEFAULT_PLUGIN_VERSION = '0.2.1';
 
 /** 4 个固定 WS 端口，对应 4 个 daemon 槽位 */
 export const ALL_WS_PORTS = [29100, 29110, 29120, 29130] as const;

package/remnote-plugin/src/utils/tree-serializer.ts

@@ -65,6 +65,8 @@ export interface SerializableRem {
   isTodo: boolean;
   todoStatus: 'Finished' | 'Unfinished' | null;
   isCode: boolean;
+  isQuote: boolean;
+  isListItem: boolean;
   isDivider: boolean;
   /** 是否为知识库顶级 Rem（无父节点） */
   isTopLevel?: boolean;
@@ -131,6 +133,12 @@ function buildLineContent(rem: SerializableRem): string {
   // Code 包裹（最内层）
   if (rem.isCode) baseContent = '`' + baseContent + '`';
 
+  // ListItem 前缀（有序列表）
+  if (rem.isListItem) baseContent = '1. ' + baseContent;
+
+  // Quote 前缀（引用块）
+  if (rem.isQuote) baseContent = '> ' + baseContent;
+
   // Todo 前缀
   if (rem.isTodo) {
     const cb = rem.todoStatus === 'Finished' ? '- [x] ' : '- [ ] ';
@@ -207,6 +215,8 @@ export function createMinimalSerializableRem(
     isTodo: false,
     todoStatus: null,
     isCode: false,
+    isQuote: false,
+    isListItem: false,
     isDivider: false,
     ...overrides,
   };

package/skills/remnote-bridge/SKILL.md

@@ -283,7 +283,9 @@ edit-tree --json '{"remId":"kLr...","oldStr":"...","newStr":"..."}'
 
 ## 3. 标准工作流
 
-### ⚠️ 标准模式：connect 后需要用户配合
+### ⚠️ 标准模式（推荐）：connect 后需要用户配合
+
+**标准模式是推荐的日常使用方式**。用户在自己的浏览器中操作 RemNote，Agent 可以通过 `read-context` 感知用户正在浏览的页面和焦点位置，实现真正的协作。
 
 `connect` 成功只意味着 daemon 和 Plugin 服务已启动，**Plugin 并未自动连接**。用户必须在 RemNote 中完成操作，Plugin 才能连接到 daemon：
 
@@ -299,11 +301,18 @@ edit-tree --json '{"remId":"kLr...","oldStr":"...","newStr":"..."}'
 
 **你必须**：执行 `connect` 后，**立即告知用户需要完成上述操作**，不要直接调用业务命令。引导用户完成后，用 `health` 确认三层就绪再继续。
 
-### Headless 模式：自动连接
+### Headless 模式（特殊场景，不推荐日常使用）
+
+通过 setup（一次性）+ headless Chrome 实现自动连接，后续 connect 无需用户介入。
+
+**⚠️ 不推荐日常使用**。Headless Chrome 是后台独立实例，**会丢失用户上下文**——`read-context` 返回的是 headless Chrome 的上下文，不是用户浏览器的。Agent 无法感知用户正在浏览和操作的页面，协作体验大打折扣。
 
-标准模式每次 connect 后都需要用户手动操作 RemNote。Headless 模式通过 setup（一次性）+ headless Chrome 实现自动连接，后续 connect 无需用户介入。
+**仅在以下场景使用 headless**：
+- 用户明确要求在**服务器/无 GUI 环境**中运行
+- 用户明确表示**不想参与操作**，希望全自动化（CI/CD、定时任务、批量处理等）
+- 用户自己不在 RemNote 前面，不需要与 Agent 协作浏览
 
-**⚠️ 模式选择建议**：日常使用推荐**标准模式**。Headless 模式下 Chrome 在后台运行，**无法感知用户正在 RemNote 中浏览和操作的界面**（`read-context` 返回的是 headless Chrome 的上下文，而非用户的浏览器）。只有在全自动化场景（CI/CD、定时任务、批量操作等无需与用户界面交互的场景）才建议使用 Headless 模式。
+**默认始终使用标准模式**，除非用户主动要求 headless。
 
 #### 首次使用（setup）
 
@@ -442,6 +451,8 @@ read-tree / read-globe / read-context 输出 Markdown 大纲，edit-tree 基于
 |:-----|:-----|
 | `# ` / `## ` / `### ` | H1/H2/H3 标题 |
 | `- [ ] ` / `- [x] ` | 未完成/已完成待办 |
+| `> ` | 引用块 |
+| `1. ` | 有序列表项 |
 | `` `...` `` | 代码块 |
 | `---` | 分隔线 |
 
@@ -512,6 +523,8 @@ read-tree / read-globe / read-context 输出 Markdown 大纲，edit-tree 基于
   新闪卡 → 答案
   问题 ↔ 回答
   - [ ] 新待办
+  > 引用内容
+  1. 列表项
   `代码块`
 ```
 

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

@@ -53,13 +53,20 @@ remnote-bridge --json connect --instance work
 
 ## 两种模式
 
-### 标准模式（默认）
+### 标准模式（默认，推荐）
 
-启动 daemon 后需要用户手动在 RemNote 中加载 Plugin。适用于用户已打开 RemNote 的场景。
+**标准模式是推荐的日常使用方式**。启动 daemon 后用户在自己的浏览器中加载 Plugin。优势：Agent 可以通过 `read-context` 感知用户正在浏览的页面和焦点位置，实现真正的协作。
 
-### Headless 模式（`--headless`）
+### Headless 模式（`--headless`，特殊场景）
 
-自动启动 headless Chrome 加载 Plugin，无需用户操作。适用于无 GUI 环境或全自动连接场景。
+自动启动 headless Chrome 加载 Plugin，无需用户操作。
+
+**⚠️ 不推荐日常使用**。Headless Chrome 是后台独立实例，**会丢失用户上下文**——`read-context` 返回的是 headless Chrome 的上下文，不是用户浏览器的。
+
+**仅在以下场景使用 headless**：
+- 用户明确要求在**服务器/无 GUI 环境**中运行
+- 用户明确表示**不想参与操作**，希望全自动化（CI/CD、定时任务、批量处理等）
+- 用户自己不在 RemNote 前面，不需要与 Agent 协作浏览
 
 **前置条件**：必须先执行 `setup` 完成 RemNote 登录。
 
@@ -93,12 +100,17 @@ remnote-bridge --headless disconnect # 结束
 
 `connect`（不传 `--headless`）成功只意味着 daemon 和 Plugin 服务已启动，**Plugin 并未自动连接**。用户必须在 RemNote 中完成以下操作：
 
+> **⚠️ 防幻觉红线**：本插件是**开发者插件**，通过「开发你的插件」功能加载本地 URL。
+> - **禁止**告诉用户"去插件市场/商店搜索安装"——本插件**不在 RemNote 插件市场中**
+> - **禁止**告诉用户"Settings → Plugins"——这个路径不存在
+> - **禁止**编造不存在的安装流程——严格按照下方步骤引导用户
+
 ### 首次使用（RemNote 从未加载过此插件）
 
 1. 打开 RemNote 桌面端或网页端
-2. 点击左侧边栏底部的插件图标（拼图形状）
-3. 点击「开发你的插件」（Develop Your Plugin）
-4. 在输入框中填入 connect 输出的 Plugin 服务地址（如 `http://localhost:29101`）
+2. 点击左侧边栏底部的**插件图标**（拼图形状）
+3. 点击「**开发你的插件**」（Develop Your Plugin）
+4. 在输入框中填入 connect 输出的 **Plugin 服务地址**（如 `http://localhost:29101`）
 5. 等待插件加载完成
 
 ### 非首次使用（之前已加载过此插件）

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

@@ -174,64 +174,56 @@ oldStr 必须在缓存大纲中恰好匹配 1 次
 
 ---
 
-## 行引用模板 `{{remId}}`
+## 两种写法：模板模式与完整匹配模式
 
-在 oldStr/newStr 中使用 `{{remId}}` 引用缓存大纲中已有行的完整内容（不含缩进）。系统在 str_replace 前自动展开。不含 `{{}}` 的传统写法完全兼容。
+已有行（带 `<!--remId-->` 注释的行）在 oldStr/newStr 中支持两种写法：
 
-### 动机
+### 模板模式（优先使用）
 
-AI 构造 oldStr/newStr 时需精确复制已有行（含 17+ 字符 Rem ID 和元数据标记），导致 token 浪费和复制错误。`{{remId}}` 让 AI 只写 ID，系统自动替换为完整行内容。
-
-### 展开规则
-
-| 输入 | 展开为 |
-|------|--------|
-| `{{remId}}` | 该 remId 对应行的去缩进完整内容（含 `<!--remId 元数据-->`） |
-| `    {{remId}}` | AI 写的缩进 + 展开后的完整内容 |
-| 不含 `{{}}` 的文本 | 原样不变 |
-
-### 示例
-
-**重排（对比传统写法）**
+用 `{{remId}}` 引用已有行，系统在 str_replace 前自动展开为完整行内容（不含缩进）。节省 token、减少复制错误。
 
 ```
-# 传统写法（~250 tokens）
-oldStr: "    动态数组 <!--id1_1 type:concept-->\n    静态数组 <!--id1_2 type:concept-->"
-newStr: "    静态数组 <!--id1_2 type:concept-->\n    动态数组 <!--id1_1 type:concept-->"
-
-# 模板写法（~50 tokens）
+# 重排
 oldStr: "    {{id1_1}}\n    {{id1_2}}"
 newStr: "    {{id1_2}}\n    {{id1_1}}"
-```
 
-**移动（改变缩进）**
-
-```
+# 移动（改变缩进 = 改变父节点）
 oldStr: "  {{idA}}\n    {{idT}}\n  {{idB}}"
 newStr: "  {{idA}}\n  {{idB}}\n    {{idT}}"
-```
-
-**删除（模板用于上下文定位）**
 
-```
+# 删除（必须同时删子行）
 oldStr: "    {{idA}}\n    {{idA1}}\n    {{idB}}"
 newStr: "    {{idB}}"
-```
-
-**新增 + 模板混用**
 
-```
+# 新增（新增行手动写，已有行用模板）
 oldStr: "  {{idZ}}"
 newStr: "  新增行\n  {{idZ}}"
 ```
 
-### 限制
-
-- 只匹配纯字母数字（`[a-zA-Z0-9]+`），与 RemNote cloze 语法 `{{text}}` 不冲突（cloze 含中文/空格/标点不会被匹配）
+**模板规则**：
+- `{{remId}}` 展开为**不含缩进**的完整行内容，缩进由你控制
+- 只匹配纯字母数字（`[a-zA-Z0-9]+`），与 RemNote cloze 语法 `{{text}}` 不冲突
 - 匹配到但不在缓存大纲中的 `{{xxx}}` 原样保留（可能是 cloze），并输出 templateWarnings
-- `{{remId}}` 不含缩进，缩进由 AI 控制（move 操作会改变缩进）
 - 新增行没有 remId，不能用模板表示
 
+### 完整匹配模式（回退）
+
+直接从大纲复制已有行的完整内容（含 `<!--remId 元数据-->`）。
+
+```
+# 重排
+oldStr: "    动态数组 <!--id1_1 type:concept-->\n    静态数组 <!--id1_2 type:concept-->"
+newStr: "    静态数组 <!--id1_2 type:concept-->\n    动态数组 <!--id1_1 type:concept-->"
+
+# 移动
+oldStr: "  子节点 A <!--idA-->\n    目标行 <!--idT-->\n  子节点 B <!--idB-->"
+newStr: "  子节点 A <!--idA-->\n  子节点 B <!--idB-->\n    目标行 <!--idT-->"
+```
+
+### ⚠️ 回退策略
+
+**优先使用模板模式**。但如果模板模式连续 2+ 次因 ID 错误导致 `old_str not found`，说明当前上下文不足以准确引用 ID——**立即切换到完整匹配模式**（重新 read_tree，从最新大纲复制完整行内容），不要反复重试模板。
+
 ---
 
 ## 支持的操作
@@ -241,12 +233,13 @@ newStr: "  新增行\n  {{idZ}}"
 在 newStr 中添加**无 remId 注释**的新行。新行可以使用 Markdown 前缀和箭头分隔符来设置属性。
 
 ```
-oldStr:
-  子节点 A <!--idA-->
+# 模板模式
+oldStr: "  {{idA}}"
+newStr: "  新增节点\n  {{idA}}"
 
-newStr:
-  新增节点
-  子节点 A <!--idA-->
+# 完整匹配模式
+oldStr: "  子节点 A <!--idA-->"
+newStr: "  新增节点\n  子节点 A <!--idA-->"
 ```
 
 #### 新增行的 Markdown 前缀
@@ -258,10 +251,20 @@ newStr:
 | `### text` | 创建 H3 标题 |
 | `- [ ] text` | 创建未完成待办 |
 | `- [x] text` | 创建已完成待办 |
+| `1. text` | 创建有序列表项 |
 | `` `text` `` | 创建代码块 |
 | `---` | 创建分隔线 |
 
-前缀可组合叠加，解析顺序为 Header → Todo → Code。例如 `## - [ ] text` 创建 H2 + 未完成待办。
+前缀可组合叠加，解析顺序为 Header → Todo → Quote → ListItem → Code。例如 `## - [ ] text` 创建 H2 + 未完成待办。
+
+> **⚠️ 有序列表必须用 `1. ` 前缀**
+>
+> RemNote 的有序列表采用 Lazy Numbering 风格——所有列表项统一写 `1. `，RemNote 按层级自动编号为 1./2./3./A./B./I./II. 等。
+>
+> - **正确**：`1. 第一项`、`1. 第二项`、`1. 第三项`（全部用 `1. `）
+> - **错误**：`2. 第二项`、`3. 第三项`（手动编号无意义，RemNote 会忽略）
+>
+> 系统会容错处理 `2. `~`9. ` 前缀（自动归一化为 `isListItem=true` 并返回 `templateWarnings` 警告），但 `10. ` 及以上不会被识别为有序列表，而是作为纯文本保留。
 
 #### 新增行的箭头分隔符
 
@@ -326,12 +329,13 @@ newStr:
 示例：
 
 ```
-oldStr:
-  子节点 A <!--idA-->
+# 模板模式
+oldStr: "  {{idA}}"
+newStr: "  <!--portal refs:refId1,refId2-->\n  {{idA}}"
 
-newStr:
-  <!--portal refs:refId1,refId2-->
-  子节点 A <!--idA-->
+# 完整匹配模式
+oldStr: "  子节点 A <!--idA-->"
+newStr: "  <!--portal refs:refId1,refId2-->\n  子节点 A <!--idA-->"
 ```
 
 #### 嵌套新增
@@ -339,11 +343,13 @@ newStr:
 新增行下面可以再嵌套新增行，通过缩进表示父子关系：
 
 ```
-newStr:
-  父节点 ↓
-    答案行 1
-    答案行 2
-  子节点 A <!--idA-->
+# 模板模式
+oldStr: "  {{idA}}"
+newStr: "  父节点 ↓\n    答案行 1\n    答案行 2\n  {{idA}}"
+
+# 完整匹配模式
+oldStr: "  子节点 A <!--idA-->"
+newStr: "  父节点 ↓\n    答案行 1\n    答案行 2\n  子节点 A <!--idA-->"
 ```
 
 嵌套新增行的父 ID 通过内部占位标记 `__new_N__` 管理，创建顺序保证从浅到深。
@@ -353,14 +359,13 @@ newStr:
 新行**不能**插在一个有子节点的 Rem 和它的 children 之间，否则 children 会被新行"劫持"，触发 `children_captured` 错误。
 
 ```
-❌ 错误：插在父 Rem 和 children 之间
-  水分子 ↓ <!--idA-->
-  新行                    ← children 被解析为新行的子节点！
-    化学式 → H₂O <!--idB role:card-item-->
+❌ 错误（模板）：
+oldStr: "  {{idA}}"   newStr: "  {{idA}}\n  新行"   ← idA 有子节点，新行劫持 children！
+❌ 错误（完整匹配）：
+oldStr: "  水分子 ↓ <!--idA-->"   newStr: "  水分子 ↓ <!--idA-->\n  新行"   ← 同理
 
-✅ 正确：插在所有兄弟末尾
-    极性 → ... <!--idZ role:card-item-->
-  新行                    ← 不影响任何已有节点
+✅ 正确：插在末尾
+oldStr: "  {{idZ}}"   newStr: "  {{idZ}}\n  新行"
 ```
 
 #### 两步操作：创建新节点并移入已有 children
@@ -377,13 +382,13 @@ newStr:
 从 newStr 中移除带 remId 的行。**必须同时删除该行的所有可见子行**，否则报 orphan_detected 错误。
 
 ```
-oldStr:
-  子节点 A <!--idA-->
-    孙节点 A1 <!--idA1-->
-  子节点 B <!--idB-->
+# 模板模式
+oldStr: "  {{idA}}\n    {{idA1}}\n  {{idB}}"
+newStr: "  {{idB}}"
 
-newStr:
-  子节点 B <!--idB-->
+# 完整匹配模式
+oldStr: "  子节点 A <!--idA-->\n    孙节点 A1 <!--idA1-->\n  子节点 B <!--idB-->"
+newStr: "  子节点 B <!--idB-->"
 ```
 
 删除操作按深度**从深到浅**执行（先删子后删父），确保 RemNote SDK 不会拒绝操作。
@@ -393,15 +398,13 @@ newStr:
 改变行的缩进级别或位置，使其移动到新的父节点下：
 
 ```
-oldStr:
-  子节点 A <!--idA-->
-    目标行 <!--idT-->
-  子节点 B <!--idB-->
+# 模板模式
+oldStr: "  {{idA}}\n    {{idT}}\n  {{idB}}"
+newStr: "  {{idA}}\n  {{idB}}\n    {{idT}}"
 
-newStr:
-  子节点 A <!--idA-->
-  子节点 B <!--idB-->
-    目标行 <!--idT-->
+# 完整匹配模式
+oldStr: "  子节点 A <!--idA-->\n    目标行 <!--idT-->\n  子节点 B <!--idB-->"
+newStr: "  子节点 A <!--idA-->\n  子节点 B <!--idB-->\n    目标行 <!--idT-->"
 ```
 
 ### 重排行
@@ -409,15 +412,13 @@ newStr:
 调换同级行的顺序：
 
 ```
-oldStr:
-  子节点 A <!--idA-->
-  子节点 B <!--idB-->
-  子节点 C <!--idC-->
+# 模板模式
+oldStr: "  {{idA}}\n  {{idB}}\n  {{idC}}"
+newStr: "  {{idC}}\n  {{idA}}\n  {{idB}}"
 
-newStr:
-  子节点 C <!--idC-->
-  子节点 A <!--idA-->
-  子节点 B <!--idB-->
+# 完整匹配模式
+oldStr: "  子节点 A <!--idA-->\n  子节点 B <!--idB-->\n  子节点 C <!--idC-->"
+newStr: "  子节点 C <!--idC-->\n  子节点 A <!--idA-->\n  子节点 B <!--idB-->"
 ```
 
 ---
@@ -543,36 +544,42 @@ RemNote SDK 存在已知 bug：
 
 ---
 
-## 常见使用模式
+## 常见使用模式（JSON 模式）
+
+> 优先使用模板模式；连续 2+ 次 `old_str not found` 则回退到完整匹配模式。
 
 ### 在指定位置插入新行
 
 ```bash
-remnote-bridge edit-tree kLr --old-str '  子节点 A <!--idA-->' --new-str '  新增行\n  子节点 A <!--idA-->'
+# 模板模式
+remnote-bridge edit-tree --json '{"remId":"kLr","oldStr":"  {{idA}}","newStr":"  新增行\n  {{idA}}"}'
+
+# 完整匹配模式
+remnote-bridge edit-tree --json '{"remId":"kLr","oldStr":"  子节点 A <!--idA-->","newStr":"  新增行\n  子节点 A <!--idA-->"}'
 ```
 
 ### 删除一个叶子节点
 
 ```bash
-remnote-bridge edit-tree kLr --old-str '    叶子节点 <!--leaf-->\n' --new-str ''
+remnote-bridge edit-tree --json '{"remId":"kLr","oldStr":"    {{leaf}}\n","newStr":""}'
 ```
 
 ### 调换两个兄弟的顺序
 
 ```bash
-# 传统写法
-remnote-bridge edit-tree kLr --old-str '  节点 A <!--idA-->\n  节点 B <!--idB-->' --new-str '  节点 B <!--idB-->\n  节点 A <!--idA-->'
-
-# 模板写法（JSON 模式）
+# 模板模式
 remnote-bridge edit-tree --json '{"remId":"kLr","oldStr":"  {{idA}}\n  {{idB}}","newStr":"  {{idB}}\n  {{idA}}"}'
+
+# 完整匹配模式
+remnote-bridge edit-tree --json '{"remId":"kLr","oldStr":"  节点 A <!--idA-->\n  节点 B <!--idB-->","newStr":"  节点 B <!--idB-->\n  节点 A <!--idA-->"}'
 ```
 
 ### 将节点移到另一个父节点下
 
 ```bash
-# 传统写法
-remnote-bridge edit-tree kLr --old-str '  旧父 <!--oldP-->\n    目标 <!--target-->\n  新父 <!--newP-->' --new-str '  旧父 <!--oldP-->\n  新父 <!--newP-->\n    目标 <!--target-->'
-
-# 模板写法（JSON 模式）
+# 模板模式
 remnote-bridge edit-tree --json '{"remId":"kLr","oldStr":"  {{oldP}}\n    {{target}}\n  {{newP}}","newStr":"  {{oldP}}\n  {{newP}}\n    {{target}}"}'
+
+# 完整匹配模式
+remnote-bridge edit-tree --json '{"remId":"kLr","oldStr":"  旧父 <!--oldP-->\n    目标 <!--target-->\n  新父 <!--newP-->","newStr":"  旧父 <!--oldP-->\n  新父 <!--newP-->\n    目标 <!--target-->"}'
 ```

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

@@ -190,6 +190,8 @@ RemNote SDK → 知识库
 
 一次**会话（Session）= 守护进程的生命周期**。
 
+**标准模式（推荐）**——用户在自己的浏览器中操作 RemNote，Agent 可感知用户上下文：
+
 ```
 connect → daemon 启动
   ↓
@@ -201,6 +203,10 @@ disconnect → daemon 关闭 → 会话结束，缓存清空
 ```
 
 > **重要**：`connect` 成功只意味着 daemon 已启动，Plugin 并未自动连接。首次使用需用户在 RemNote「开发你的插件」中填入对应的 Plugin 服务地址；非首次只需刷新 RemNote 页面。必须引导用户完成此步后再用 `health` 确认就绪。
+>
+> **⚠️ 防幻觉红线**：本插件是**开发者插件**，通过「开发你的插件」加载本地 URL。**禁止**告诉用户去插件市场/商店搜索安装（插件不在市场中）；**禁止**编造"Settings → Plugins"等不存在的路径。
+
+**Headless 模式（不推荐日常使用）**——通过后台 Chrome 自动连接，但**会丢失用户上下文**（`read-context` 返回 headless 实例的上下文，不是用户浏览器的）。仅在以下场景使用：用户明确要求在服务器/无 GUI 环境运行、用户明确不想参与操作（全自动化）、用户不在 RemNote 前面。详见 `connect.md`。
 
 `connect` 启动三个服务，端口由槽位自动分配：
 
@@ -636,9 +642,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 由元数据标记承载）。
@@ -805,6 +819,8 @@ edit-tree 使用 str_replace 对 Markdown 大纲进行结构编辑。详细文
   # 新标题 H1
   新闪卡 → 答案
   - [ ] 新待办
+  > 引用内容
+  1. 列表项
   `代码块内容`
 ```
 

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 的行为。
 
 #### 双接口策略