remnote-bridge 0.1.13 → 0.1.15

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` 时输出）
 
 ```