remnote-bridge 0.1.12 → 0.1.13

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

@@ -128,7 +128,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 |
 
@@ -288,7 +288,7 @@ remnote-bridge disconnect --instance work
 
 | 命令 | 功能 | 前置条件 | 安全机制 | 详细文档 |
 |:-----|:-----|:---------|:---------|:---------|
-| `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 探索决策指南
@@ -410,7 +410,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 +422,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 对象中
@@ -571,7 +571,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 +582,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,7 +690,7 @@ read-tree / read-globe / read-context 的输出核心是 Markdown 大纲文本
 
 | 前缀 | 用途 | 写入命令 |
 |:-----|:-----|:---------|
-| `rem:{remId}` | RemObject JSON | read-rem |
+| `rem:{remId}` | RemObject 对象 | read-rem |
 | `tree:{remId}` | Markdown 大纲 | read-tree |
 | `tree-depth:{remId}` 等 | read-tree 参数 | read-tree |
 
@@ -698,9 +698,9 @@ read-tree / read-globe / read-context 的输出核心是 Markdown 大纲文本
 - disconnect 关闭 daemon 时缓存自动消失
 - **没有 TTL**——三道防线的并发检测已能捕获所有陈旧数据
 
-### 9.2 三道防线
+### 9.2 安全防线
 
-`edit-rem` 和 `edit-tree` 使用 str_replace 语义编辑数据。为防止数据损坏，实施三道防线：
+`edit-rem` 和 `edit-tree` 编辑数据时，实施多道防线防止数据损坏：
 
 #### 防线 1：缓存存在性检查
 
@@ -718,7 +718,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 +742,8 @@ oldStr 必须在目标文本中恰好匹配 1 次
 | 场景 | 缓存行为 |
 |:-----|:---------|
 | 写入全部成功 | 从 SDK 重新读取最新状态 → **更新缓存** |
-| 防线拒绝 | **不更新缓存**（迫使 Agent 重新 read） |
+| 防线拒绝（缓存缺失 / 并发冲突） | **不更新缓存**（迫使 Agent 重新 read） |
+| 枚举值非法 | **报错拒绝**，不更新缓存 |
 | 部分写入失败 | **不更新缓存** |
 
 ---
@@ -854,13 +864,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.md

@@ -422,7 +422,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 +434,7 @@ localUpdatedAt, lastPracticed
 | 只有 `parent` 变更 | `setParent(newParent)` 不带 position（保持末尾） |
 | 只有 `positionAmongstSiblings` 变更 | 获取当前 parent → `setParent(currentParent, newPosition)` |
 
-**应在同一次 str_replace 中同时修改这两个字段。**
+**应在同一次 edit-rem 的 changes 中同时传入这两个字段。**
 
 ---
 
@@ -561,7 +561,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 +589,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` 后重新执行）。