remnote-bridge 0.1.13 → 0.1.14

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>` |
 
 #### 修改 / 写入
@@ -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,6 +283,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 +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。
 
 ---
 
@@ -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() | 直接转发 |
@@ -690,9 +715,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 时缓存自动消失

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）

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

@@ -9,7 +9,8 @@
 `read-rem` 通过 Rem ID 读取一个 Rem 的所有可获取属性，返回标准化的 RemObject。读取结果会被缓存在 daemon 内存中，供后续 `edit-rem` 使用。
 
 核心能力：
-- 返回 51 个字段的完整 Rem 数据（默认 33 个，Portal 简化 8 个，`--full` 时 51 个）
+- **Token Slimming**（默认模式）：省略处于默认值的字段，典型普通 Rem 仅输出 5-6 个差异字段，大幅减少 AI token 消耗。未显示的字段即为默认值
+- Portal 简化 8 个字段，`--full` 时全部 51 个字段
 - 支持 `--fields` 指定字段子集
 - 支持 Powerup 噪音过滤（默认过滤）
 - 自动缓存，为 `edit-rem` 建立编辑基础
@@ -72,20 +73,17 @@ remnote-bridge read-rem --json '{"remId":"kLrIOHJLyMd8Y2lyA"}'
   "data": {
     "id": "kLrIOHJLyMd8Y2lyA",
     "text": [{ "i": "m", "text": "示例文本", "b": true }],
-    "backText": null,
     "type": "concept",
-    "isDocument": false,
     "parent": "parentRemId",
-    "fontSize": null,
-    "highlightColor": null,
-    "isTodo": false,
-    "todoStatus": null,
-    "...": "（共 33 个字段，--full 时 51 个）"
+    "createdAt": 1709712000000,
+    "updatedAt": 1709712000000
   },
   "timestamp": "2026-03-06T10:00:00.000Z"
 }
 ```
 
+> **Token Slimming**：默认模式省略了 backText(null)、isDocument(false)、fontSize(null) 等处于默认值的字段。未出现的字段即为默认值。`--full` 可输出全部 51 个字段。
+
 ### 成功（含缓存覆盖提示）
 
 当该 Rem 之前已有缓存时，输出中附加 `cacheOverridden` 字段：
@@ -159,7 +157,7 @@ remnote-bridge read-rem --json '{"remId":"kLrIOHJLyMd8Y2lyA"}'
    │   ├─ --full → 返回全部 51 字段
    │   ├─ --fields → 返回指定字段 + id
    │   ├─ type=portal → Portal 简化模式（返回 8 个关键字段）
-   │   └─ 默认 → 排除 R-F 字段（返回 33 字段）
+   │   └─ 默认 → 排除 R-F 字段 + Token Slimming（省略匹配默认值的字段）
    └─ 附加 _cacheOverridden 元数据（若之前有缓存）
 4. CLI 格式化输出（人类模式 pretty-print / JSON 模式单行）
 ```
@@ -376,11 +374,32 @@ text | number | date | checkbox | single_select | multi_select | url | image | t
 
 | 模式 | 输出字段数 | 说明 |
 |------|:----------:|------|
-| 默认 | 33 | RW + R 字段，覆盖常用场景 |
+| 默认（Token Slimming） | 5-6（典型） | 省略匹配默认值的字段，仅输出有差异的字段。始终输出：id、text、parent、createdAt、updatedAt |
 | Portal 简化 | 8 | type=portal 时自动使用（id、type、portalType、portalDirectlyIncludedRem、parent、positionAmongstSiblings、createdAt、updatedAt）。`--full` / `--fields` 可覆盖 |
-| `--full` | 51 | 全部字段（含 R-F 低频字段） |
+| `--full` | 51 | 全部字段（含 R-F 低频字段），不省略默认值 |
 | `--fields` | 自选 + id | 仅返回指定字段（始终包含 id） |
 
+### 默认值参考表
+
+默认模式下，以下字段在值匹配默认值时被省略。**未出现在输出中的字段即为默认值。**
+
+| 字段 | 默认值 | 字段 | 默认值 |
+|------|--------|------|--------|
+| `backText` | `null` | `type` | `"default"` |
+| `isDocument` | `false` | `fontSize` | `null` |
+| `highlightColor` | `null` | `isTodo` | `false` |
+| `todoStatus` | `null` | `isCode` | `false` |
+| `isQuote` | `false` | `isListItem` | `false` |
+| `isCardItem` | `false` | `isTable` | `false` |
+| `isSlot` | `false` | `isProperty` | `false` |
+| `portalType` | `null` | `portalDirectlyIncludedRem` | `[]` |
+| `propertyType` | `null` | `enablePractice` | `false` |
+| `practiceDirection` | `"forward"` | `tags` | `[]` |
+| `sources` | `[]` | `aliases` | `[]` |
+| `remsBeingReferenced` | `[]` | `remsReferencingThis` | `[]` |
+| `taggedRem` | `[]` | `descendants` | `[]` |
+| `siblingRem` | `[]` | `positionAmongstSiblings` | `null` |
+
 ### R-F 字段列表（默认不输出，`--full` 时输出）
 
 ```