remnote-bridge 0.1.12 → 0.1.14

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` 时输出）
 
 ```
@@ -422,7 +441,7 @@ localUpdatedAt, lastPracticed
 | `tags` | `rem.addTag()` / `rem.removeTag()` | **Diff 机制**：对比当前 vs 目标，增删差异项。必须列出完整目标数组，缺少的会被删除 |
 | `sources` | `rem.addSource()` / `rem.removeSource()` | **Diff 机制**：同 tags |
 | `positionAmongstSiblings` | `rem.setParent(parent, position)` | 与 `parent` 联动（见下方说明） |
-| `portalDirectlyIncludedRem` | `rem.addToPortal()` / `rem.removeFromPortal()` | string[] | **Portal-W Diff 机制**：仅 type=portal 时可修改。对比当前 vs 目标数组，逐项增删。调用方向：在被引用 Rem 上调用，参数是 Portal Rem |
+| `portalDirectlyIncludedRem` | `rem.addToPortal()` / `rem.removeFromPortal()` | **Portal-W Diff 机制**：仅 type=portal 时可修改。对比当前 vs 目标数组，逐项增删 |
 
 ### parent + positionAmongstSiblings 联动
 
@@ -434,7 +453,7 @@ localUpdatedAt, lastPracticed
 | 只有 `parent` 变更 | `setParent(newParent)` 不带 position（保持末尾） |
 | 只有 `positionAmongstSiblings` 变更 | 获取当前 parent → `setParent(currentParent, newPosition)` |
 
-**应在同一次 str_replace 中同时修改这两个字段。**
+**应在同一次 edit-rem 的 changes 中同时传入这两个字段。**
 
 ---
 
@@ -561,7 +580,7 @@ RemObject 中的 `text` 和 `backText` 字段使用 RichText 格式——一个
 
 ### 序列化确定性
 
-RichText 对象元素内部按 **key 字母序排列**（Plugin 端 `sortRichTextKeys()` 处理），确保同一内容的序列化 JSON 始终一致。这对 `edit-rem` 的 str_replace 和乐观并发检测至关重要。
+RichText 对象元素内部按 **key 字母序排列**（Plugin 端 `sortRichTextKeys()` 处理），确保同一内容的序列化 JSON 始终一致。这对乐观并发检测至关重要。
 
 - `_`（下划线）在 Unicode 中排在所有小写字母之前（`_` = U+005F，`a` = U+0061），所以 `_id` 总是排在第一位
 - 排序由 `Object.keys().sort()` 决定，即 JavaScript 默认的 Unicode 字典序
@@ -589,11 +608,11 @@ RichText 对象元素内部按 **key 字母序排列**（Plugin 端 `sortRichTex
 |------|------|
 | 读取成功 | 完整 JSON 写入缓存 `cache.set('rem:' + remId, fullJson)` |
 | 已有缓存 | 覆盖旧缓存，返回 `cacheOverridden` 元数据 |
-| 缓存用途 | 供 `edit-rem` 的三道防线使用（存在性检查 + 乐观并发检测 + str_replace） |
+| 缓存用途 | 供 `edit-rem` 的防线检查使用（存在性检查 + 乐观并发检测） |
 | 缓存存储 | daemon 内存中的 LRU 缓存（最大 200 条目） |
 | 缓存清空 | daemon 关闭时自动消失 |
 
-**重要**：缓存存储的是 **完整 RemObject**（含 R-F 字段），不受 `--fields` / `--full` 选项影响。字段过滤仅作用于返回给 CLI 的输出。
+**重要**：缓存存储的是 **完整 RemObject 对象**（含 R-F 字段），不受 `--fields` / `--full` 选项影响。字段过滤仅作用于返回给 CLI 的输出。
 
 ---
 

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

@@ -56,7 +56,7 @@ remnote-bridge search <query> [--limit <N>]
 ### JSON 模式
 
 ```bash
-remnote-bridge search --json '{"query":"机器学习","numResults":10}'
+remnote-bridge search --json '{"query":"机器学习","limit":10}'
 ```
 
 ---
@@ -66,7 +66,7 @@ remnote-bridge search --json '{"query":"机器学习","numResults":10}'
 | 字段 | 类型 | 必需 | 说明 |
 |------|------|:----:|------|
 | `query` | string | 是 | 搜索关键词（不能为空） |
-| `numResults` | number | 否 | 结果数量上限（默认 20） |
+| `limit` | number | 否 | 结果数量上限（默认 20） |
 
 ---
 
@@ -159,7 +159,7 @@ remnote-bridge search --json '{"query":"机器学习","numResults":10}'
 ## 内部流程
 
 ```
-1. CLI 解析参数（query, numResults）
+1. CLI 解析参数（query, limit）
 2. 检查配置：addons.remnote-rag.enabled
    ├─ 未启用 → 跳到步骤 4
    └─ 已启用 → 继续步骤 3
@@ -250,6 +250,6 @@ RemNote 的 Web 版搜索索引按单字符拆分非空格语言的文本。搜
 ## 注意事项
 
 - 搜索结果的 `text` 字段是 Markdown 格式的单行文本（多行换行符已替换为空格）
-- `totalFound` 等于 `results.length`，即实际返回的数量（受 `numResults` 限制）
+- `totalFound` 等于 `results.length`，即实际返回的数量（受 `limit` 限制）
 - 搜索不会触发缓存写入——search 结果不进入 RemCache
 - 如需获取某个搜索结果的完整属性，需对其 `remId` 执行 `read-rem`

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

@@ -83,22 +83,21 @@ remnote-bridge --json setup
 
 ## AI Agent 使用流程
 
-setup 会弹出 Chrome 窗口，用户需要完成两件事：登录 RemNote + 配置 dev plugin。
+setup 会弹出 Chrome 窗口，用户只需**登录 RemNote**，然后彻底退出 Chrome。
+
+setup 只负责保存登录凭证——配置 dev plugin 是 connect 之后的事（见 `connect.md` 标准模式说明）。
 
 ### 交互步骤
 
 1. 调用 `setup`
 2. **立即告知用户**：
-   > 已打开 Chrome 浏览器。请完成以下操作：
-   > 1. 登录 RemNote
-   > 2. 在 RemNote 中配置开发插件：点击左下角插件图标 → 开发你的插件 → 输入 connect 输出的 Plugin 服务地址（如 `http://localhost:29101`）
-   > 3. 完成后彻底退出 Chrome（macOS 请按 Cmd+Q，仅关窗口不够）
+   > 已打开 Chrome 浏览器。请登录 RemNote，完成后彻底退出 Chrome（macOS 请按 Cmd+Q，仅关窗口不够）
 3. 等待 `setup` 命令返回（阻塞式，超时 600 秒）
 4. 收到成功 → 继续执行 `connect --headless`
 
 ### setup 之后
 
-`setup` 只需执行一次。登录凭证和 plugin 配置都已保存，之后每次只需 `connect --headless` 即可自动连接，无需用户操作。
+`setup` 只需执行一次。登录凭证已保存，之后每次只需 `connect --headless` 即可自动连接，无需用户操作。
 
 如果后续 headless 模式下 Plugin 始终不连接，可能是 RemNote 登录 session 过期，需重新 setup（删除 `~/.remnote-bridge/chrome-profile/.setup-done` 后重新执行）。