remnote-bridge 0.1.13 → 0.1.15

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

@@ -174,6 +174,58 @@ oldStr 必须在缓存大纲中恰好匹配 1 次
 
 ---
 
+## 两种写法：模板模式与完整匹配模式
+
+已有行（带 `<!--remId-->` 注释的行）在 oldStr/newStr 中支持两种写法：
+
+### 模板模式（优先使用）
+
+用 `{{remId}}` 引用已有行，系统在 str_replace 前自动展开为完整行内容（不含缩进）。节省 token、减少复制错误。
+
+```
+# 重排
+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}}"
+```
+
+**模板规则**：
+- `{{remId}}` 展开为**不含缩进**的完整行内容，缩进由你控制
+- 只匹配纯字母数字（`[a-zA-Z0-9]+`），与 RemNote cloze 语法 `{{text}}` 不冲突
+- 匹配到但不在缓存大纲中的 `{{xxx}}` 原样保留（可能是 cloze），并输出 templateWarnings
+- 新增行没有 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，从最新大纲复制完整行内容），不要反复重试模板。
+
+---
+
 ## 支持的操作
 
 ### 新增行
@@ -181,12 +233,13 @@ oldStr 必须在缓存大纲中恰好匹配 1 次
 在 newStr 中添加**无 remId 注释**的新行。新行可以使用 Markdown 前缀和箭头分隔符来设置属性。
 
 ```
-oldStr:
-  子节点 A <!--idA-->
+# 模板模式
+oldStr: "  {{idA}}"
+newStr: "  新增节点\n  {{idA}}"
 
-newStr:
-  新增节点
-  子节点 A <!--idA-->
+# 完整匹配模式
+oldStr: "  子节点 A <!--idA-->"
+newStr: "  新增节点\n  子节点 A <!--idA-->"
 ```
 
 #### 新增行的 Markdown 前缀
@@ -266,12 +319,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-->"
 ```
 
 #### 嵌套新增
@@ -279,11 +333,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__` 管理，创建顺序保证从浅到深。
@@ -293,14 +349,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
@@ -317,13 +372,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 不会拒绝操作。
@@ -333,15 +388,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-->"
 ```
 
 ### 重排行
@@ -349,15 +402,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-->"
 ```
 
 ---
@@ -458,8 +509,9 @@ RemNote SDK 存在已知 bug：
 4. daemon TreeEditHandler:
    ├─ 防线 1: cache.get('tree:' + remId) 存在？
    ├─ 防线 2: 用缓存的 depth/maxNodes/maxSiblings 重新 read-tree → 对比
-   ├─ 防线 3: countOccurrences(cachedOutline, oldStr) === 1？
-   ├─ modifiedOutline = cachedOutline.replace(oldStr, newStr)
+   ├─ 模板展开: {{remId}} → 缓存中对应行的完整内容（不含缩进）
+   ├─ 防线 3: countOccurrences(cachedOutline, expandedOldStr) === 1？
+   ├─ modifiedOutline = cachedOutline.replace(expandedOldStr, expandedNewStr)
    ├─ 解析新旧大纲为树（parseOutline）
    ├─ 对比差异（diffTrees）
    │   ├─ 根节点校验
@@ -482,28 +534,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-->'
+# 模板模式
+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-->'
+# 模板模式
+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/health.md

@@ -6,65 +6,64 @@
 
 ## 功能
 
-`health` 分两步检查指定实例的系统状态：
+`health` 检查系统状态，支持两种模式：
 
+1. **全量模式**（默认）：遍历注册表所有活跃实例，逐个查询三层状态
+2. **单实例模式**（`--instance` / `--headless`）：只查询指定实例
+
+每个实例的检查分两步：
 1. **本地检查**：通过注册表查找实例，确认 daemon 进程是否存活
 2. **远程检查**：通过 WS 连接 daemon，获取 Plugin 连接状态和 SDK 就绪状态
 
-### 多实例支持
+### 孪生连接
 
-通过 `--instance <name>` 指定要检查的实例。不指定时检查 `default` 实例。
-
-```bash
-remnote-bridge health --instance work
-```
+每个实例的 Plugin 连接会标记是否为**孪生连接**（`plugin.isTwin`）。孪生连接表示 Plugin 的 `twinSlotIndex` 与 daemon 的槽位索引匹配，优先级更高——孪生连接可以抢占非孪生连接。
 
 ---
 
 ## 用法
 
-### 人类模式
+### 全量模式（默认）
 
 ```bash
 remnote-bridge health
 ```
 
-输出示例（全部健康）：
+输出所有活跃实例的状态：
 
 ```
-✅ 守护进程  运行中（PID: 12345，实例: default，槽位: 0，已运行 5 分钟）
-✅ Plugin    已连接
+=== 实例: default（槽位 0）===
+✅ 守护进程  运行中（PID: 12345，已运行 5 分钟）
+✅ Plugin    已连接（孪生）
 ✅ SDK       就绪
-
 超时: 25 分钟后自动关闭
-```
-
-输出示例（部分不健康）：
-
-```
-✅ 守护进程  运行中（PID: 12345，实例: work，槽位: 1，已运行 2 分钟）
-❌ Plugin    未连接
-❌ SDK       未就绪
 
+=== 实例: headless（槽位 1）===
+✅ 守护进程  运行中（PID: 12346，已运行 2 分钟）
+✅ Plugin    已连接（非孪生）
+✅ SDK       就绪
+✅ Chrome     running
 超时: 28 分钟后自动关闭
 ```
 
-输出示例（daemon 未运行）：
+无活跃实例时：
 
 ```
-❌ 守护进程  未运行
-❌ Plugin    未连接
-❌ SDK       不可用
-
-提示: 执行 `remnote-bridge connect` 启动守护进程
+没有活跃的实例。执行 `remnote-bridge connect` 启动守护进程。
 ```
 
-### JSON 模式
+### 单实例模式
 
 ```bash
-remnote-bridge --json health
+# 指定实例
+remnote-bridge --instance work health
+
+# 检查 headless 实例
+remnote-bridge --headless health
 ```
 
+输出格式与之前相同，但只显示一个实例。
+
 ### Headless 诊断模式
 
 ```bash
@@ -81,7 +80,43 @@ remnote-bridge health --reload
 
 ## JSON 输出
 
-### 全部健康
+### 全量模式
+
+```json
+{
+  "ok": true,
+  "command": "health",
+  "exitCode": 0,
+  "instances": [
+    {
+      "instance": "default",
+      "slotIndex": 0,
+      "daemon": { "running": true, "pid": 12345, "reachable": true, "uptime": 300 },
+      "plugin": { "connected": true, "isTwin": true },
+      "sdk": { "ready": true },
+      "timeoutRemaining": 1500
+    },
+    {
+      "instance": "headless",
+      "slotIndex": 1,
+      "daemon": { "running": true, "pid": 12346, "reachable": true, "uptime": 120 },
+      "plugin": { "connected": true, "isTwin": true },
+      "sdk": { "ready": true },
+      "timeoutRemaining": 1680,
+      "headless": {
+        "status": "running",
+        "chromeConnected": true,
+        "pageUrl": "http://localhost:29111",
+        "reloadCount": 0,
+        "lastError": null,
+        "recentConsoleErrors": []
+      }
+    }
+  ]
+}
+```
+
+### 单实例模式 — 全部健康
 
 ```json
 {
@@ -91,39 +126,36 @@ remnote-bridge health --reload
   "instance": "default",
   "slotIndex": 0,
   "daemon": { "running": true, "pid": 12345, "reachable": true, "uptime": 300 },
-  "plugin": { "connected": true },
+  "plugin": { "connected": true, "isTwin": true },
   "sdk": { "ready": true },
   "timeoutRemaining": 1500
 }
 ```
 
-### Plugin 未连接
+### 单实例模式 — daemon 未运行
 
 ```json
 {
   "ok": false,
   "command": "health",
-  "exitCode": 1,
-  "instance": "work",
-  "slotIndex": 1,
-  "daemon": { "running": true, "pid": 12345, "reachable": true, "uptime": 120 },
+  "exitCode": 2,
+  "instance": "default",
+  "daemon": { "running": false },
   "plugin": { "connected": false },
   "sdk": { "ready": false },
-  "timeoutRemaining": 1680
+  "error": "守护进程未运行（实例: default），请先执行 remnote-bridge connect"
 }
 ```
 
-### daemon 未运行
+### 全量模式 — 无活跃实例
 
 ```json
 {
   "ok": false,
   "command": "health",
   "exitCode": 2,
-  "instance": "default",
-  "daemon": { "running": false },
-  "plugin": { "connected": false },
-  "sdk": { "ready": false }
+  "instances": [],
+  "error": "没有活跃的实例，请执行 remnote-bridge connect 启动守护进程"
 }
 ```
 
@@ -135,6 +167,7 @@ remnote-bridge health --reload
 |--------|----------|------|
 | **daemon** | 注册表查找 + `kill(pid, 0)` 探活 | 守护进程是否在运行且可达 |
 | **plugin** | daemon 内部的 `pluginConnected` 状态 | RemNote Plugin 是否已通过 WS 连接到 daemon |
+| **plugin.isTwin** | Plugin hello 握手中的 `twinSlotIndex` | 是否为孪生连接（匹配 daemon 槽位索引） |
 | **sdk** | Plugin 的 hello 握手中的 `sdkReady` 字段 | RemNote SDK 是否就绪（知识库已加载，可调用 API） |
 
 ### 三层关系
@@ -151,9 +184,9 @@ daemon 运行 → Plugin 连接 → SDK 就绪
 
 | 退出码 | 含义 | 触发条件 |
 |--------|------|----------|
-| 0 | 全部健康 | daemon 运行 + Plugin 已连接 + SDK 就绪 |
+| 0 | 全部健康 | 所有实例三层均通过 |
 | 1 | 部分不健康 | daemon 运行但 Plugin 未连接或 SDK 未就绪 |
-| 2 | 不可达 | daemon 未运行，或运行但 WS 连接失败 |
+| 2 | 不可达 | 无活跃实例，或 daemon 不可达 |
 
 ---
 
@@ -161,11 +194,13 @@ daemon 运行 → Plugin 连接 → SDK 就绪
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
+| `instances` | array | 全量模式下所有实例的状态数组 |
 | `daemon.running` | boolean | 进程是否存活 |
 | `daemon.pid` | number | 进程 ID（仅运行时） |
 | `daemon.reachable` | boolean | WS 连接是否成功（仅运行时） |
 | `daemon.uptime` | number | 运行秒数（仅可达时） |
 | `plugin.connected` | boolean | Plugin WS 连接是否建立 |
+| `plugin.isTwin` | boolean | 是否为孪生连接 |
 | `sdk.ready` | boolean | RemNote SDK 是否就绪 |
 | `timeoutRemaining` | number | 距自动关闭的剩余秒数（仅可达时） |
 
@@ -173,19 +208,12 @@ daemon 运行 → Plugin 连接 → SDK 就绪
 
 ## Headless 模式附加输出
 
-### health 基础输出（headless 模式下额外字段）
+### health 基础输出（headless 实例额外字段）
 
-headless 模式下 `health` 基础输出额外包含 `headless` 对象：
+headless 实例额外包含 `headless` 对象：
 
 ```json
 {
-  "ok": true,
-  "command": "health",
-  "exitCode": 0,
-  "daemon": { "running": true, "pid": 12345, "reachable": true, "uptime": 300 },
-  "plugin": { "connected": true },
-  "sdk": { "ready": true },
-  "timeoutRemaining": 1500,
   "headless": {
     "status": "running",
     "chromeConnected": true,
@@ -227,7 +255,7 @@ headless 模式下 `health` 基础输出额外包含 `headless` 对象：
 
 | 症状 | 可能原因 | 解决方案 |
 |------|----------|----------|
-| daemon 未运行 | 未执行 connect / 已超时关闭 | 执行 `connect` |
+| 无活跃实例 | 未执行 connect / 已超时关闭 | 执行 `connect` |
 | daemon 运行但不可达 | WS 端口被占用或配置不匹配 | 检查 `~/.remnote-bridge/slots.json` 中的端口配置 |
 | Plugin 未连接（标准模式） | RemNote 未打开 / Plugin 未安装 / URL 不匹配 | 打开 RemNote，确认 Plugin 中的 WS URL 设置 |
 | Plugin 未连接（headless 模式） | Chrome 页面加载异常 | `health --diagnose` 查看截图和状态，`health --reload` 重载页面 |

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

@@ -44,6 +44,7 @@ Agent 的核心任务是将用户的自然语言请求翻译为 CLI 命令。以
 | "我现在在看什么"、"当前页面" | 用户当前焦点/页面 | `read-context` |
 | "展开这个主题"、"看看下面有什么" | Rem 子树 | `read-tree <remId>` |
 | "这个笔记的详细信息" | Rem 的完整属性 | `read-rem <remId>` |
+| "展开子树并获取所有属性" | 子树大纲 + 节点属性 | `read-rem-in-tree <remId>` |
 | "搜索 X"、"查找关于 X 的内容" | 全文搜索 | `search <query>` |
 
 #### 修改 / 写入
@@ -189,6 +190,8 @@ RemNote SDK → 知识库
 
 一次**会话（Session）= 守护进程的生命周期**。
 
+**标准模式（推荐）**——用户在自己的浏览器中操作 RemNote，Agent 可感知用户上下文：
+
 ```
 connect → daemon 启动
   ↓
@@ -200,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` 启动三个服务，端口由槽位自动分配：
 
@@ -239,7 +246,7 @@ remnote-bridge disconnect --instance work
 | 2 | 29120 | 29121 | 29122 |
 | 3 | 29130 | 29131 | 29132 |
 
-**实例名解析优先级**：CLI `--instance` > 环境变量 `REMNOTE_BRIDGE_INSTANCE` > 默认值 `default`。
+**实例名解析优先级**：CLI `--instance` > 环境变量 `REMNOTE_BRIDGE_INSTANCE` > 默认值 `default`。`headless` 是保留实例名，不可用于 `--instance`（会报错），必须使用 `--headless` 全局选项。
 
 **Plugin 自动发现**：Plugin 启动后通过 `/api/discovery` 获取其孪生 daemon 的连接信息（WS 端口、槽位索引等），自动建立连接。一个 Plugin 可同时连接最多 4 个 daemon。
 
@@ -282,6 +289,7 @@ remnote-bridge disconnect --instance work
 | `read-context` | 当前上下文视图 | mode + 参数 | 否 | `read-context.md` |
 | `read-tree` | 读取子树为 Markdown 大纲 | remId + 展开参数 | 是（`tree:`） | `read-tree.md` |
 | `read-rem` | 读取单个 Rem 的 JSON 属性 | remId | 是（`rem:`） | `read-rem.md` |
+| `read-rem-in-tree` | 子树大纲 + 节点属性一次获取 | remId + 展开参数 + 过滤参数 | 是（`tree:` + `rem:`） | `read-rem-in-tree.md` |
 | `search` | 全文搜索 | query | 否 | `search.md` |
 
 #### 写入命令
@@ -309,10 +317,17 @@ Agent 需要根据用户意图选择正确的读取命令：
 ├─ 某个具体 Rem 的子树 → read-tree <remId>
 │   完整展开子树（支持深度/节点预算控制）
 │   结果缓存，供 edit-tree 使用
+│   ⚠️ 如果需要读取子树后对其中多个节点执行 edit-rem，请改用 read-rem-in-tree
 │
 ├─ 某个 Rem 的详细属性 → read-rem <remId>
 │   返回 51 字段的 RemObject JSON
 │   结果缓存，供 edit-rem 使用
+│   ⚠️ 如果需要读取多个 Rem 属性（≥3 个）且在同一子树下，请改用 read-rem-in-tree
+│
+├─ 子树结构 + 每个节点的详细属性 → read-rem-in-tree <remId>
+│   read-tree + read-rem 的合体，一次调用同时获取大纲和 RemObject
+│   同时建立 tree 和 rem 双重缓存，供 edit-tree 和 edit-rem 使用
+│   默认 maxNodes=50（比 read-tree 的 200 低，因每节点开销大）
 │
 └─ 按关键词搜索 → search <query>
     全文搜索，返回匹配的 Rem 列表
@@ -327,6 +342,7 @@ Agent 需要根据用户意图选择正确的读取命令：
 | "我现在在编辑什么" | `read-context --mode focus` | 鱼眼视图，焦点处详细 |
 | "当前页面的内容" | `read-context --mode page` | 以页面为根展开 |
 | "展开某个主题的细节" | `read-tree <id>` | 完整子树，可缓存供编辑 |
+| "展开子树并查看每个节点属性" | `read-rem-in-tree <id>` | 大纲 + RemObject，双重缓存 |
 
 #### read-globe 特性
 
@@ -390,14 +406,28 @@ Agent 需要根据用户意图选择正确的读取命令：
 4. read-globe           ← 了解知识库结构（首次探索）
    或 read-context      ← 了解用户当前上下文
 5. search "关键词"       ← 定位目标 Rem（中文搜索可能需单字策略，详见 search.md）
-6. read-tree <id>       ← 展开目标区域的子树
-7. read-rem <id>        ← 读取详细属性（编辑前必需）
-8. edit-rem <id> ...    ← 修改 Rem 属性
+6a. [单节点] read-tree <id> + read-rem <id>  ← 各自建立缓存
+6b. [多节点] read-rem-in-tree <id>            ← 一次建立双重缓存（推荐 ≥3 个节点需修改时）
+7. edit-rem <id> ...    ← 修改 Rem 属性
    或 edit-tree <id> ...← 修改树结构
 9. disconnect           ← 结束会话
 ```
 
-**注意**：步骤 7 是 `edit-rem` 的强制前置条件，步骤 6 是 `edit-tree` 的强制前置条件。跳过会触发防线 1 错误。步骤 2 是必须的——connect 后不引导用户加载插件就直接调用业务命令，会报"Plugin 未连接"错误。
+**注意**：步骤 6a/6b 是 edit-rem / edit-tree 的强制前置条件。跳过会触发防线 1 错误。步骤 2 是必须的——connect 后不引导用户加载插件就直接调用业务命令，会报"Plugin 未连接"错误。
+
+### 4.5 批量标注工作流（课本划重点场景）
+
+当需要对一棵子树中的多个节点进行富文本标注（行级高亮、行内荧光、粗体等）时：
+
+1. read-rem-in-tree <id> --maxNodes 50    -- 一次获取大纲 + 所有 RemObject
+2. 从 remObjects 中定位需要标注的节点
+3. 对每个目标节点 edit-rem 设置格式：
+   - 行级高亮：changes.highlightColor = "Yellow"/"Red"/...
+   - 行内荧光：changes.text = [..., {"h": 3, "i": "m", "text": "关键词"}, ...]
+   - 粗体：changes.text = [..., {"b": true, "i": "m", "text": "核心概念"}, ...]
+4. 如需结构变更（如新增/移动节点），直接 edit-tree（tree 缓存已就绪）
+
+关键：read-rem-in-tree 同时建立了 tree 和 rem 两种缓存，后续 edit-tree 和 edit-rem 都无需再单独 read。
 
 ---
 
@@ -465,6 +495,7 @@ daemon → CLI 响应：
 | `read_rem` | read-rem | readRem() | 直接转发 |
 | `edit_rem` | edit-rem | — | daemon handler 编排 |
 | `read_tree` | read-tree | readTree() | 直接转发 |
+| `read_rem_in_tree` | read-rem-in-tree | readRemInTree() | daemon handler 编排 + Plugin 转发 |
 | `edit_tree` | edit-tree | — | daemon handler 编排 |
 | `read_globe` | read-globe | readGlobe() | 直接转发 |
 | `read_context` | read-context | readContext() | 直接转发 |
@@ -690,9 +721,9 @@ read-tree / read-globe / read-context 的输出核心是 Markdown 大纲文本
 
 | 前缀 | 用途 | 写入命令 |
 |:-----|:-----|:---------|
-| `rem:{remId}` | RemObject 对象 | read-rem |
-| `tree:{remId}` | Markdown 大纲 | read-tree |
-| `tree-depth:{remId}` 等 | read-tree 参数 | read-tree |
+| `rem:{remId}` | RemObject 对象 | read-rem, read-rem-in-tree |
+| `tree:{remId}` | Markdown 大纲 | read-tree, read-rem-in-tree |
+| `tree-depth:{remId}` 等 | read-tree 参数 | read-tree, read-rem-in-tree |
 
 - LRU 淘汰：上限 200 条目
 - disconnect 关闭 daemon 时缓存自动消失