remnote-bridge 0.1.12 → 0.1.14

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

@@ -174,6 +174,66 @@ oldStr 必须在缓存大纲中恰好匹配 1 次
 
 ---
 
+## 行引用模板 `{{remId}}`
+
+在 oldStr/newStr 中使用 `{{remId}}` 引用缓存大纲中已有行的完整内容（不含缩进）。系统在 str_replace 前自动展开。不含 `{{}}` 的传统写法完全兼容。
+
+### 动机
+
+AI 构造 oldStr/newStr 时需精确复制已有行（含 17+ 字符 Rem ID 和元数据标记），导致 token 浪费和复制错误。`{{remId}}` 让 AI 只写 ID，系统自动替换为完整行内容。
+
+### 展开规则
+
+| 输入 | 展开为 |
+|------|--------|
+| `{{remId}}` | 该 remId 对应行的去缩进完整内容（含 `<!--remId 元数据-->`） |
+| `    {{remId}}` | AI 写的缩进 + 展开后的完整内容 |
+| 不含 `{{}}` 的文本 | 原样不变 |
+
+### 示例
+
+**重排（对比传统写法）**
+
+```
+# 传统写法（~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 含中文/空格/标点不会被匹配）
+- 匹配到但不在缓存大纲中的 `{{xxx}}` 原样保留（可能是 cloze），并输出 templateWarnings
+- `{{remId}}` 不含缩进，缩进由 AI 控制（move 操作会改变缩进）
+- 新增行没有 remId，不能用模板表示
+
+---
+
 ## 支持的操作
 
 ### 新增行
@@ -458,8 +518,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）
    │   ├─ 根节点校验
@@ -499,11 +560,19 @@ remnote-bridge edit-tree kLr --old-str '    叶子节点 <!--leaf-->\n' --new-st
 ### 调换两个兄弟的顺序
 
 ```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}}"}'
 ```
 
 ### 将节点移到另一个父节点下
 
 ```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}}"}'
 ```

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>` |
 
 #### 修改 / 写入
@@ -128,7 +129,7 @@ Rem 有两个**独立维度**的类型：
 |:-----|:-----|:-----|
 | 创建 Portal | `edit-tree` | 新增行 `<!--portal refs:id1,id2-->` |
 | 删除 Portal | `edit-tree` | 从大纲中移除 Portal 行（与删除普通行相同） |
-| 修改引用列表（增删引用的 Rem） | `edit-rem` | str_replace 简化 JSON 中的 `portalDirectlyIncludedRem` 数组 |
+| 修改引用列表（增删引用的 Rem） | `edit-rem` | 直接修改 changes 中的 `portalDirectlyIncludedRem` 数组 |
 | 移动 Portal（换父节点/位置） | `edit-tree` | 与移动普通行相同 |
 | 读取 Portal | `read-rem` | 自动输出 8 字段简化 JSON |
 
@@ -239,7 +240,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,13 +283,14 @@ 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` |
 
 #### 写入命令
 
 | 命令 | 功能 | 前置条件 | 安全机制 | 详细文档 |
 |:-----|:-----|:---------|:---------|:---------|
-| `edit-rem` | str_replace 编辑 Rem JSON 字段 | 先 `read-rem` | 三道防线 | `edit-rem.md` |
+| `edit-rem` | 直接修改 Rem 属性字段 | 先 `read-rem` | 两道防线 + 字段白名单 | `edit-rem.md` |
 | `edit-tree` | str_replace 编辑树结构 | 先 `read-tree` | 三道防线 + diff | `edit-tree.md` |
 
 ### 4.2 探索决策指南
@@ -309,10 +311,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 +336,7 @@ Agent 需要根据用户意图选择正确的读取命令：
 | "我现在在编辑什么" | `read-context --mode focus` | 鱼眼视图，焦点处详细 |
 | "当前页面的内容" | `read-context --mode page` | 以页面为根展开 |
 | "展开某个主题的细节" | `read-tree <id>` | 完整子树，可缓存供编辑 |
+| "展开子树并查看每个节点属性" | `read-rem-in-tree <id>` | 大纲 + RemObject，双重缓存 |
 
 #### read-globe 特性
 
@@ -390,14 +400,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。
 
 ---
 
@@ -410,7 +434,7 @@ Agent 需要根据用户意图选择正确的读取命令：
 ```bash
 read-rem kLrIOHJLyMd8Y2lyA --fields text,type
 read-tree kLrIOHJLyMd8Y2lyA --depth 2
-edit-rem kLrIOHJLyMd8Y2lyA --old-str '"concept"' --new-str '"descriptor"'
+edit-rem kLrIOHJLyMd8Y2lyA --changes '{"type":"descriptor"}'
 ```
 
 - 位置参数 = remId 或关键词
@@ -422,7 +446,7 @@ edit-rem kLrIOHJLyMd8Y2lyA --old-str '"concept"' --new-str '"descriptor"'
 ```bash
 read-rem --json '{"remId":"kLrIOHJLyMd8Y2lyA","fields":["text","type"]}'
 read-tree --json '{"remId":"kLrIOHJLyMd8Y2lyA","depth":2}'
-edit-rem --json '{"remId":"kLrIOHJLyMd8Y2lyA","oldStr":"\"concept\"","newStr":"\"descriptor\""}'
+edit-rem --json '{"remId":"kLrIOHJLyMd8Y2lyA","changes":{"type":"descriptor"}}'
 ```
 
 - **位置参数 = JSON 字符串**，所有参数打包在 JSON 对象中
@@ -465,6 +489,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() | 直接转发 |
@@ -571,7 +596,7 @@ Portal：portalType [R], portalDirectlyIncludedRem [Portal-W]
 { "i": "a", "onlyAudio": true, "url": "..." }   // 音频
 ```
 
-> 在 RemObject 格式化 JSON 中，数组内对象展开为多行。构造 edit-rem 的 oldStr/newStr 必须用多行格式。
+> 在 RemObject 格式化 JSON 中，数组内对象展开为多行。构造 edit-tree 的 oldStr/newStr 或 edit-rem 的 changes 中 RichText 值时，需注意多行格式。
 
 **⚠️ highlightColor vs h — 两种完全不同的高亮**：
 
@@ -582,7 +607,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-rem 的 str_replace 和并发检测至关重要。
+**序列化确定性**：RichText 对象内部按 key 字母序排列（`sortRichTextKeys()`）。`_id` 的 `_`（U+005F）排在所有小写字母之前。这对乐观并发检测和 edit-tree 的 str_replace 至关重要。
 
 ---
 
@@ -690,17 +715,17 @@ read-tree / read-globe / read-context 的输出核心是 Markdown 大纲文本
 
 | 前缀 | 用途 | 写入命令 |
 |:-----|:-----|:---------|
-| `rem:{remId}` | RemObject JSON | 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 时缓存自动消失
 - **没有 TTL**——三道防线的并发检测已能捕获所有陈旧数据
 
-### 9.2 三道防线
+### 9.2 安全防线
 
-`edit-rem` 和 `edit-tree` 使用 str_replace 语义编辑数据。为防止数据损坏，实施三道防线：
+`edit-rem` 和 `edit-tree` 编辑数据时，实施多道防线防止数据损坏：
 
 #### 防线 1：缓存存在性检查
 
@@ -718,7 +743,16 @@ edit 时重新从 SDK 读取最新数据 → 与缓存严格比较
 
 如果 Rem 在 read 之后被外部修改（用户在 RemNote UI 中编辑、其他 Agent 修改等），数据不一致时拒绝编辑，**且不更新缓存**——迫使 Agent 重新 read。
 
-#### 防线 3：str_replace 精确匹配
+#### edit-rem 防线 3：字段白名单校验
+
+```
+changes 中的字段必须在 RW 白名单内，枚举值必须合法
+```
+
+- 只读字段（R / R-F）写入时**警告跳过**，不阻断其他字段
+- 枚举值非法时**报错拒绝**（如 `type: "invalid"`）
+
+#### edit-tree 防线 3：str_replace 精确匹配
 
 ```
 oldStr 必须在目标文本中恰好匹配 1 次
@@ -733,7 +767,8 @@ oldStr 必须在目标文本中恰好匹配 1 次
 | 场景 | 缓存行为 |
 |:-----|:---------|
 | 写入全部成功 | 从 SDK 重新读取最新状态 → **更新缓存** |
-| 防线拒绝 | **不更新缓存**（迫使 Agent 重新 read） |
+| 防线拒绝（缓存缺失 / 并发冲突） | **不更新缓存**（迫使 Agent 重新 read） |
+| 枚举值非法 | **报错拒绝**，不更新缓存 |
 | 部分写入失败 | **不更新缓存** |
 
 ---
@@ -854,13 +889,12 @@ Agent 遇到错误时的诊断和恢复指南：
 | has not been read yet | 未先执行 read-rem / read-tree | 执行对应 read 命令后重试 |
 | has been modified since last read | Rem 在 read 和 edit 之间被外部修改 | 重新执行 read 获取最新状态后重试 |
 
-### str_replace 错误
+### edit-tree str_replace 错误
 
 | 错误 | 原因 | 恢复 |
 |:-----|:-----|:-----|
-| old_str not found | oldStr 在目标文本中不存在 | 检查 oldStr 是否精确匹配（含引号、空格、换行） |
+| old_str not found | oldStr 在目标文本中不存在 | 检查 oldStr 是否精确匹配（含空格、换行、缩进） |
 | old_str matches N locations | oldStr 匹配到多个位置 | 扩大 oldStr 范围，包含更多上下文以唯一定位 |
-| invalid JSON | 替换后的文本不是合法 JSON | 检查 newStr 的引号、逗号、括号完整性 |
 
 ### edit-tree 专用错误
 

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

@@ -0,0 +1,100 @@
+# read-rem-in-tree — 子树大纲 + 节点属性一次获取
+
+> `read_tree` + `read_rem` 的完美结合体。一次调用同时获取 Markdown 大纲和每个节点的完整 RemObject JSON，建立双重缓存。
+
+---
+
+## 适用场景
+
+- 需要同时查看子树结构和节点详细属性（如批量编辑前的全量读取）
+- 一次调用建立 tree 缓存（供 `edit_tree`）和 rem 缓存（供 `edit_rem`）
+- 替代连续调用 `read_tree` + 多次 `read_rem` 的场景
+
+## 不适用场景
+
+- 只需大纲不需属性 → 用 `read_tree`（更轻量）
+- 只需单个 Rem 属性 → 用 `read_rem`
+- 大规模子树（>50 节点） → 每节点 40+ SDK 调用，性能开销大
+
+---
+
+## 命令格式
+
+```bash
+# 人类模式
+remnote-bridge read-rem-in-tree <remId> [options]
+
+# JSON 模式
+remnote-bridge --json read-rem-in-tree '{"remId":"...","depth":3,"maxNodes":50}'
+```
+
+## 参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|:-----|:-----|:-------|:-----|
+| `remId` | string | **必需** | 子树根节点的 Rem ID |
+| `depth` | number | 3 | 递归展开深度（-1 = 无限） |
+| `maxNodes` | number | **50** | 全局节点总预算（注意比 read_tree 的 200 低） |
+| `maxSiblings` | number | 20 | 单个父节点下最大可见子节点数 |
+| `ancestorLevels` | number | 0 | 向上追溯祖先层数（上限 10） |
+| `fields` | string[] | - | RemObject 字段过滤（只返回指定子集） |
+| `full` | boolean | false | 返回全部 51 个 RemObject 字段 |
+| `includePowerup` | boolean | false | 包含 Powerup 系统数据 |
+
+## 输出
+
+### JSON 模式
+
+```jsonc
+{
+  "ok": true,
+  "command": "read-rem-in-tree",
+  "data": {
+    "rootId": "kLr...",
+    "depth": 3,
+    "nodeCount": 15,
+    "outline": "# 数据结构 <!--kLr type:concept doc-->\n  ...",
+    "remObjects": {
+      "kLr": { "id": "kLr", "text": [...], "type": "concept", ... },
+      "ABC": { "id": "ABC", "text": [...], ... }
+    }
+  },
+  "ancestors": [...],          // 可选
+  "cacheOverridden": {...},    // 可选
+  "powerupFiltered": {...}     // 可选
+}
+```
+
+### 核心字段
+
+- `outline`：Markdown 大纲文本，与 `read_tree` 输出格式完全一致
+- `remObjects`：扁平 map `{ remId → RemObject }`，每个 RemObject 与 `read_rem` 输出一致
+  - 默认启用 Token Slimming（省略默认值字段）
+  - `fields` / `full` 参数控制过滤行为
+
+## 缓存行为
+
+| 缓存 Key | 内容 | 用途 |
+|:---------|:-----|:-----|
+| `tree:{remId}` | outline 大纲文本 | `edit_tree` 前置缓存 |
+| `tree-depth:{remId}` 等 | 读取参数 | `edit_tree` 乐观并发检测 |
+| `rem:{nodeRemId}` | 完整 RemObject（N 个） | `edit_rem` 前置缓存 |
+
+总缓存条目：1(tree) + 3(参数) + N(rem) ≈ N+4。注意 LRU 上限 200。
+
+## 典型工作流
+
+```
+read_rem_in_tree → 一次获取全部信息
+  ↓
+edit_tree 结构编辑（tree 缓存已就绪）
+  +
+edit_rem 属性编辑（rem 缓存已就绪）
+```
+
+## 关联工具
+
+- `read_tree`：只需大纲，更轻量
+- `read_rem`：只需单个 Rem 属性
+- `edit_tree`：结构编辑（需先 read_tree 或 read_rem_in_tree）
+- `edit_rem`：属性编辑（需先 read_rem 或 read_rem_in_tree）