remnote-bridge 0.1.11 → 0.1.13

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

@@ -6,11 +6,19 @@
 
 ## 功能
 
-`health` 分两步检查系统状态：
+`health` 分两步检查指定实例的系统状态：
 
-1. **本地检查**：读取 PID 文件，确认 daemon 进程是否存活
+1. **本地检查**：通过注册表查找实例，确认 daemon 进程是否存活
 2. **远程检查**：通过 WS 连接 daemon，获取 Plugin 连接状态和 SDK 就绪状态
 
+### 多实例支持
+
+通过 `--instance <name>` 指定要检查的实例。不指定时检查 `default` 实例。
+
+```bash
+remnote-bridge health --instance work
+```
+
 ---
 
 ## 用法
@@ -24,7 +32,7 @@ remnote-bridge health
 输出示例（全部健康）：
 
 ```
-✅ 守护进程  运行中（PID: 12345，已运行 5 分钟）
+✅ 守护进程  运行中（PID: 12345，实例: default，槽位: 0，已运行 5 分钟）
 ✅ Plugin    已连接
 ✅ SDK       就绪
 
@@ -34,7 +42,7 @@ remnote-bridge health
 输出示例（部分不健康）：
 
 ```
-✅ 守护进程  运行中（PID: 12345，已运行 2 分钟）
+✅ 守护进程  运行中（PID: 12345，实例: work，槽位: 1，已运行 2 分钟）
 ❌ Plugin    未连接
 ❌ SDK       未就绪
 
@@ -80,11 +88,12 @@ remnote-bridge health --reload
   "ok": true,
   "command": "health",
   "exitCode": 0,
+  "instance": "default",
+  "slotIndex": 0,
   "daemon": { "running": true, "pid": 12345, "reachable": true, "uptime": 300 },
   "plugin": { "connected": true },
   "sdk": { "ready": true },
-  "timeoutRemaining": 1500,
-  "timestamp": "2026-03-06T10:00:00.000Z"
+  "timeoutRemaining": 1500
 }
 ```
 
@@ -95,11 +104,12 @@ remnote-bridge health --reload
   "ok": false,
   "command": "health",
   "exitCode": 1,
+  "instance": "work",
+  "slotIndex": 1,
   "daemon": { "running": true, "pid": 12345, "reachable": true, "uptime": 120 },
   "plugin": { "connected": false },
   "sdk": { "ready": false },
-  "timeoutRemaining": 1680,
-  "timestamp": "2026-03-06T10:00:00.000Z"
+  "timeoutRemaining": 1680
 }
 ```
 
@@ -110,10 +120,10 @@ remnote-bridge health --reload
   "ok": false,
   "command": "health",
   "exitCode": 2,
+  "instance": "default",
   "daemon": { "running": false },
   "plugin": { "connected": false },
-  "sdk": { "ready": false },
-  "timestamp": "2026-03-06T10:00:00.000Z"
+  "sdk": { "ready": false }
 }
 ```
 
@@ -123,7 +133,7 @@ remnote-bridge health --reload
 
 | 检查项 | 检查方式 | 含义 |
 |--------|----------|------|
-| **daemon** | PID 文件 + `kill(pid, 0)` 探活 | 守护进程是否在运行且可达 |
+| **daemon** | 注册表查找 + `kill(pid, 0)` 探活 | 守护进程是否在运行且可达 |
 | **plugin** | daemon 内部的 `pluginConnected` 状态 | RemNote Plugin 是否已通过 WS 连接到 daemon |
 | **sdk** | Plugin 的 hello 握手中的 `sdkReady` 字段 | RemNote SDK 是否就绪（知识库已加载，可调用 API） |
 
@@ -179,7 +189,7 @@ headless 模式下 `health` 基础输出额外包含 `headless` 对象：
   "headless": {
     "status": "running",
     "chromeConnected": true,
-    "pageUrl": "http://localhost:8080",
+    "pageUrl": "http://localhost:29101",
     "reloadCount": 0,
     "lastError": null,
     "recentConsoleErrors": []
@@ -218,7 +228,7 @@ headless 模式下 `health` 基础输出额外包含 `headless` 对象：
 | 症状 | 可能原因 | 解决方案 |
 |------|----------|----------|
 | daemon 未运行 | 未执行 connect / 已超时关闭 | 执行 `connect` |
-| daemon 运行但不可达 | WS 端口被占用或配置不匹配 | 检查 `.remnote-bridge.json` 中的 `wsPort` |
+| daemon 运行但不可达 | WS 端口被占用或配置不匹配 | 检查 `~/.remnote-bridge/slots.json` 中的端口配置 |
 | Plugin 未连接（标准模式） | RemNote 未打开 / Plugin 未安装 / URL 不匹配 | 打开 RemNote，确认 Plugin 中的 WS URL 设置 |
 | Plugin 未连接（headless 模式） | Chrome 页面加载异常 | `health --diagnose` 查看截图和状态，`health --reload` 重载页面 |
 | SDK 未就绪 | 知识库加载中 / Plugin 异常 | 等待几秒后重试，或刷新 RemNote 页面 |

package/skills/remnote-bridge/instructions/install-skill.md

@@ -0,0 +1,58 @@
+# install-skill
+
+> 将 remnote-bridge Skill 安装到 AI Agent 环境中。
+
+---
+
+## 功能
+
+`install-skill` 将 Skill 文档（SKILL.md + instructions/*.md）安装到 AI Agent 可发现的位置。支持两种安装方式：
+
+| 方式 | 说明 |
+|:-----|:-----|
+| Vercel Skills CLI（默认） | 通过 `npx skills add` 安装，适用于支持 Vercel Skills 生态的 Agent |
+| Claude Code 直接复制（fallback） | 将文件复制到 `~/.claude/skills/remnote-bridge/`，仅适用于 Claude Code |
+
+---
+
+## 用法
+
+```bash
+# 通过 Vercel Skills CLI 安装（推荐）
+remnote-bridge install-skill
+
+# 直接复制到 Claude Code skills 目录
+remnote-bridge install-skill-copy
+```
+
+---
+
+## 安装逻辑
+
+### install-skill
+
+1. 检测 `npx` 是否可用
+2. 可用 → 执行 `npx skills add baobao700508/unofficial-remnote-bridge-cli -s remnote-bridge`
+3. 不可用或执行失败 → 自动 fallback 到文件复制模式
+
+### install-skill-copy
+
+直接将 Skill 文件从 npm 包内复制到 `~/.claude/skills/remnote-bridge/`：
+- `SKILL.md`
+- `instructions/*.md`（所有 Markdown 文件）
+
+---
+
+## 退出码
+
+| 退出码 | 含义 |
+|:-------|:-----|
+| 0 | 安装成功 |
+| 1 | 安装失败（找不到源文件、权限不足等） |
+
+---
+
+## AI Agent 注意事项
+
+- 此命令通常由用户在初始设置时手动执行，Agent 一般不需要调用
+- 安装完成后，Agent 即可通过 Skill 接口发现和使用 remnote-bridge 功能

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

@@ -128,9 +128,9 @@ 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` | 自动输出 9 字段简化 JSON |
+| 读取 Portal | `read-rem` | 自动输出 8 字段简化 JSON |
 
 ### 2.6 Powerup 机制简述
 
@@ -199,19 +199,53 @@ health → 确认三层就绪 → 会话可用
 disconnect → daemon 关闭 → 会话结束，缓存清空
 ```
 
-> **重要**：`connect` 成功只意味着 daemon 已启动，Plugin 并未自动连接。首次使用需用户在 RemNote「开发你的插件」中填入 `http://localhost:8080`；非首次只需刷新 RemNote 页面。必须引导用户完成此步后再用 `health` 确认就绪。
+> **重要**：`connect` 成功只意味着 daemon 已启动，Plugin 并未自动连接。首次使用需用户在 RemNote「开发你的插件」中填入对应的 Plugin 服务地址；非首次只需刷新 RemNote 页面。必须引导用户完成此步后再用 `health` 确认就绪。
 
-`connect` 启动三个服务：
+`connect` 启动三个服务，端口由槽位自动分配：
 
-| 服务 | 默认端口 | 用途 |
-|:-----|:---------|:-----|
-| WS Server | 3002 | CLI ↔ daemon ↔ Plugin 通信 |
-| Plugin 服务 | 8080 | 加载 Plugin 到 RemNote（默认静态服务器，`--dev` 时为 webpack-dev-server） |
-| ConfigServer | 3003 | HTTP 配置界面 |
+| 服务 | 槽位 0 端口 | 用途 |
+|:-----|:-----------|:-----|
+| WS Server | 29100 | CLI ↔ daemon ↔ Plugin 通信 |
+| Plugin 服务 | 29101 | 加载 Plugin 到 RemNote（默认静态服务器，`--dev` 时为 webpack-dev-server） |
+| ConfigServer | 29102 | HTTP 配置界面 |
 
 超时机制：daemon 默认 **30 分钟无活动**自动关闭。每次收到 CLI 请求时重置计时器。
 
-### 3.3 健康状态
+### 3.3 多实例支持
+
+系统支持最多 **4 个并发实例**，每个实例连接不同的 RemNote 知识库。
+
+```bash
+# 启动默认实例
+remnote-bridge connect
+
+# 启动额外实例
+remnote-bridge connect --instance work
+remnote-bridge connect --instance personal
+
+# 查看指定实例状态
+remnote-bridge health --instance work
+
+# 停止指定实例
+remnote-bridge disconnect --instance work
+```
+
+**槽位分配**：每个实例启动时自动占用第一个空闲槽位，端口固定分配：
+
+| 槽位 | WS 端口 | Plugin 服务端口 | 配置端口 |
+|:-----|:--------|:---------------|:---------|
+| 0 | 29100 | 29101 | 29102 |
+| 1 | 29110 | 29111 | 29112 |
+| 2 | 29120 | 29121 | 29122 |
+| 3 | 29130 | 29131 | 29132 |
+
+**实例名解析优先级**：CLI `--instance` > 环境变量 `REMNOTE_BRIDGE_INSTANCE` > 默认值 `default`。
+
+**Plugin 自动发现**：Plugin 启动后通过 `/api/discovery` 获取其孪生 daemon 的连接信息（WS 端口、槽位索引等），自动建立连接。一个 Plugin 可同时连接最多 4 个 daemon。
+
+**业务命令的实例选择**：`read-rem`、`edit-rem` 等业务命令自动路由到 `--instance` 指定的实例（默认 `default`）。各实例的缓存相互独立。
+
+### 3.4 健康状态
 
 `health` 命令检查三层状态：
 
@@ -233,9 +267,12 @@ disconnect → daemon 关闭 → 会话结束，缓存清空
 
 | 命令 | 功能 | 需要 Plugin | 详细文档 |
 |:-----|:-----|:------------|:---------|
-| `connect` | 启动守护进程 | 否 | `connect.md` |
-| `health` | 检查系统状态 | 否 | `health.md` |
-| `disconnect` | 停止守护进程 | 否 | `disconnect.md` |
+| `connect` | 启动守护进程（支持 `--instance`） | 否 | `connect.md` |
+| `health` | 检查系统状态（支持 `--instance`） | 否 | `health.md` |
+| `disconnect` | 停止守护进程（支持 `--instance`） | 否 | `disconnect.md` |
+| `addon` | 管理增强项目（list/install/uninstall） | 否 | `addon.md` |
+| `clean` | 清理所有进程、缓存和注册表 | 否 | `clean.md` |
+| `install-skill` | 安装 Skill 到 Agent 环境 | 否 | `install-skill.md` |
 
 #### 读取命令
 
@@ -251,7 +288,7 @@ disconnect → daemon 关闭 → 会话结束，缓存清空
 
 | 命令 | 功能 | 前置条件 | 安全机制 | 详细文档 |
 |:-----|:-----|:---------|:---------|:---------|
-| `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 探索决策指南
@@ -373,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 或关键词
@@ -385,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 对象中
@@ -454,8 +491,8 @@ RemObject 是本项目对 RemNote Rem 的标准化表示，包含 51 个字段
 | 标记 | 含义 | 数量 | 输出条件 |
 |:-----|:-----|:-----|:---------|
 | RW | 可读可写 | 20 | 默认输出 |
-| R | 只读 | 14 | 默认输出 |
-| R-F | 只读低频 | 17 | 仅 `--full` 输出 |
+| R | 只读 | 13 | 默认输出 |
+| R-F | 只读低频 | 18 | 仅 `--full` 输出 |
 
 ### 7.2 核心字段速览
 
@@ -463,7 +500,7 @@ RemObject 是本项目对 RemNote Rem 的标准化表示，包含 51 个字段
 标识：  id
 内容：  text [RW], backText [RW]
 类型：  type [RW], isDocument [RW]
-结构：  parent [RW], children [R]
+结构：  parent [RW], children [R-F]
 格式：  fontSize [RW], highlightColor [RW]
 状态：  isTodo [RW], todoStatus [RW], isCode [RW], isQuote [RW],
         isListItem [RW], isCardItem [RW], isSlot [RW], isProperty [RW]
@@ -534,11 +571,18 @@ 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 — 两种完全不同的高亮**：
+
+| 属性 | 位置 | 值类型 | 效果 |
+|:-----|:-----|:-------|:-----|
+| `highlightColor` | RemObject 顶层字段 | 字符串 `"Yellow"`/`"Red"` 等或 `null` | 整行背景色（左侧彩色竖条） |
+| `h` | RichText 元素内部 | 数字 0-9 | 文字片段荧光底色 |
 
-**highlightColor vs h**：`highlightColor` 是 RemObject 顶层字段（字符串如 `"Red"`），`h` 是 RichText 行内格式标记（数字 0-9）。两者独立。
+`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 至关重要。
 
 ---
 
@@ -646,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 |
 
@@ -654,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：缓存存在性检查
 
@@ -674,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 次
@@ -689,7 +742,8 @@ oldStr 必须在目标文本中恰好匹配 1 次
 | 场景 | 缓存行为 |
 |:-----|:---------|
 | 写入全部成功 | 从 SDK 重新读取最新状态 → **更新缓存** |
-| 防线拒绝 | **不更新缓存**（迫使 Agent 重新 read） |
+| 防线拒绝（缓存缺失 / 并发冲突） | **不更新缓存**（迫使 Agent 重新 read） |
+| 枚举值非法 | **报错拒绝**，不更新缓存 |
 | 部分写入失败 | **不更新缓存** |
 
 ---
@@ -751,13 +805,10 @@ RemNote 的格式设置通过 Powerup 机制实现，会向 Rem 注入隐藏的
 
 ## 12. 配置系统
 
-配置文件位于项目根目录：`.remnote-bridge.json`
+配置文件位于全局目录：`~/.remnote-bridge/config.json`（所有实例共享）。
 
 ```json
 {
-  "wsPort": 3002,
-  "devServerPort": 8080,
-  "configPort": 3003,
   "daemonTimeoutMinutes": 30,
   "defaults": {
     "maxNodes": 200,
@@ -776,7 +827,21 @@ RemNote 的格式设置通过 Powerup 机制实现，会向 Rem 注入隐藏的
 ```
 
 - 文件不存在时使用全部默认值
-- 三个端口不允许冲突
+- 端口由槽位自动分配（`~/.remnote-bridge/slots.json`），通常无需手动配置
+
+### 多实例文件布局
+
+```
+~/.remnote-bridge/
+  ├── config.json      — 全局配置（所有实例共享）
+  ├── slots.json       — 槽位端口定义（自动生成）
+  ├── registry.json    — 实例→槽位映射（运行时维护）
+  └── instances/
+      ├── 0.pid / 0.log   — 槽位 0 的 PID 和日志
+      ├── 1.pid / 1.log   — 槽位 1
+      ├── 2.pid / 2.log   — 槽位 2
+      └── 3.pid / 3.log   — 槽位 3
+```
 
 ---
 
@@ -799,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

@@ -9,7 +9,7 @@
 `read-rem` 通过 Rem ID 读取一个 Rem 的所有可获取属性，返回标准化的 RemObject。读取结果会被缓存在 daemon 内存中，供后续 `edit-rem` 使用。
 
 核心能力：
-- 返回 51 个字段的完整 Rem 数据（默认 34 个，Portal 简化 9 个，`--full` 时 51 个）
+- 返回 51 个字段的完整 Rem 数据（默认 33 个，Portal 简化 8 个，`--full` 时 51 个）
 - 支持 `--fields` 指定字段子集
 - 支持 Powerup 噪音过滤（默认过滤）
 - 自动缓存，为 `edit-rem` 建立编辑基础
@@ -76,12 +76,11 @@ remnote-bridge read-rem --json '{"remId":"kLrIOHJLyMd8Y2lyA"}'
     "type": "concept",
     "isDocument": false,
     "parent": "parentRemId",
-    "children": ["childId1", "childId2"],
     "fontSize": null,
     "highlightColor": null,
     "isTodo": false,
     "todoStatus": null,
-    "...": "（共 34 个字段，--full 时 51 个）"
+    "...": "（共 33 个字段，--full 时 51 个）"
   },
   "timestamp": "2026-03-06T10:00:00.000Z"
 }
@@ -159,8 +158,8 @@ remnote-bridge read-rem --json '{"remId":"kLrIOHJLyMd8Y2lyA"}'
    ├─ 字段过滤：
    │   ├─ --full → 返回全部 51 字段
    │   ├─ --fields → 返回指定字段 + id
-   │   ├─ type=portal → Portal 简化模式（返回 9 个关键字段）
-   │   └─ 默认 → 排除 R-F 字段（返回 34 字段）
+   │   ├─ type=portal → Portal 简化模式（返回 8 个关键字段）
+   │   └─ 默认 → 排除 R-F 字段（返回 33 字段）
    └─ 附加 _cacheOverridden 元数据（若之前有缓存）
 4. CLI 格式化输出（人类模式 pretty-print / JSON 模式单行）
 ```
@@ -172,8 +171,8 @@ remnote-bridge read-rem --json '{"remId":"kLrIOHJLyMd8Y2lyA"}'
 RemObject 共 51 个字段，按读写权限分为三类：
 
 - **RW**（20 个）：可读可写，SDK 有对应的 setter
-- **R**（14 个）：只读，默认输出
-- **R-F**（17 个）：只读，仅 `--full` 模式输出（低频 / 可由其他字段推导）
+- **R**（13 个）：只读，默认输出
+- **R-F**（18 个）：只读，仅 `--full` 模式输出（低频 / 可由其他字段推导）
 
 ### 核心标识
 
@@ -200,7 +199,7 @@ RemObject 共 51 个字段，按读写权限分为三类：
 | 字段 | 类型 | 权限 | 说明 |
 |------|------|:----:|------|
 | `parent` | `string \| null` | RW | 父 Rem ID。null=顶级。UI：Rem 从原位置消失，出现在新父级下 |
-| `children` | `string[]` | R | 子 Rem ID 有序数组 |
+| `children` | `string[]` | R-F | 子 Rem ID 有序数组 |
 
 ### 格式 / 显示
 
@@ -377,14 +376,15 @@ text | number | date | checkbox | single_select | multi_select | url | image | t
 
 | 模式 | 输出字段数 | 说明 |
 |------|:----------:|------|
-| 默认 | 34 | RW + R 字段，覆盖常用场景 |
-| Portal 简化 | 9 | type=portal 时自动使用（id、type、portalType、portalDirectlyIncludedRem、parent、positionAmongstSiblings、children、createdAt、updatedAt）。`--full` / `--fields` 可覆盖 |
+| 默认 | 33 | RW + R 字段，覆盖常用场景 |
+| Portal 简化 | 8 | type=portal 时自动使用（id、type、portalType、portalDirectlyIncludedRem、parent、positionAmongstSiblings、createdAt、updatedAt）。`--full` / `--fields` 可覆盖 |
 | `--full` | 51 | 全部字段（含 R-F 低频字段） |
 | `--fields` | 自选 + id | 仅返回指定字段（始终包含 id） |
 
 ### R-F 字段列表（默认不输出，`--full` 时输出）
 
 ```
+children,
 isPowerup, isPowerupEnum, isPowerupProperty, isPowerupPropertyListItem, isPowerupSlot,
 deepRemsBeingReferenced,
 ancestorTagRem, descendantTagRem,
@@ -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 的输出。
 
 ---