remnote-bridge 0.1.11 → 0.1.13

package/dist/mcp/resources/edit-rem-guide.js

@@ -1,7 +1,7 @@
 export const EDIT_REM_GUIDE_CONTENT = `
 # edit_rem 操作指南
 
-edit_rem 通过 str_replace 语义修改单个 Rem 的属性。操作对象是 \\\`JSON.stringify(remObject, null, 2)\\\` 的格式化文本。
+edit_rem 直接修改单个 Rem 的属性字段。通过 changes 对象指定要修改的字段及新值。
 
 ---
 
@@ -9,149 +9,70 @@ edit_rem 通过 str_replace 语义修改单个 Rem 的属性。操作对象是 \
 
 必须先 \\\`read_rem\\\` 同一个 remId，建立缓存后才能 \\\`edit_rem\\\`。跳过会触发防线 1 错误。
 
-工作流：\\\`read_rem\\\` → 查看 JSON → \\\`edit_rem\\\`（oldStr/newStr）。
+工作流：\\\`read_rem\\\` → 查看属性 → \\\`edit_rem\\\`（changes 对象）。
 
 ---
 
-## str_replace 语义
+## changes 对象
 
-### 操作对象
+传入 {字段名: 新值} 格式的对象。支持 21 个可写字段，只读和未知字段会产生警告但不阻断。
 
-格式化缩进 2 空格的 JSON 文本。示例片段：
-
-\\\`\\\`\\\`json
-{
-  "id": "kLrIOHJLyMd8Y2lyA",
-  "text": [
-    "Hello World"
-  ],
-  "backText": null,
-  "type": "concept",
-  "highlightColor": null,
-  "isTodo": false
-}
-\\\`\\\`\\\`
-
-### 匹配规则
-
-- oldStr 必须在 JSON 文本中**恰好匹配 1 次**（0 次=未找到，>1 次=多匹配，均报错）
-- 大小写敏感，精确匹配
-- oldStr 建议包含字段名 + 值，避免匹配到 text 内容中的同名字符串
-
-### 替换后校验
-
-替换后的文本必须是合法 JSON，否则报 "invalid JSON" 错误。
+示例：
+- 修改类型：\\\`{type: "concept"}\\\`
+- 设置高亮：\\\`{highlightColor: "Yellow"}\\\`
+- 批量修改：\\\`{type: "concept", highlightColor: "Yellow", fontSize: "H1"}\\\`
 
 ---
 
-## 三道防线
+## 两道防线
 
 | 防线 | 检查内容 | 失败时 |
 |:-----|:---------|:-------|
 | 1. 缓存存在 | 是否已 read_rem | 报 "has not been read yet" → 先 read_rem |
 | 2. 并发检测 | 当前 Rem 是否被外部修改 | 报 "has been modified since last read" → 重新 read_rem |
-| 3. 精确匹配 | oldStr 匹配次数 | 0 次或多次 → 调整 oldStr 使其唯一 |
 
-防线 2 的关键：edit 时会从 Plugin 重新读取最新数据与缓存比较。如果不一致（含空白和格式），拒绝编辑并**不更新缓存**，迫使你重新 read_rem。
+防线 2 的关键：edit 时会从 Plugin 重新读取最新数据与缓存比较。如果不一致，拒绝编辑并**不更新缓存**，迫使你重新 read_rem。
 
 ---
 
-## RichText 编辑实战
+## RichText 编辑
 
-\\\`text\\\` 和 \\\`backText\\\` 字段使用 RichText 格式。在格式化 JSON 中，RichText 数组内的对象展开为多行，key 按**字母序**排列。
+\\\`text\\\` 和 \\\`backText\\\` 字段使用 RichText 格式。传入完整的 RichText 数组作为新值。
 
 ### 关键排序规则
 
 - \\\`_id\\\`（U+005F）排在所有小写字母之前，所以 \\\`_id\\\` 总是第一个 key
 - 示例排序：\\\`_id\\\` < \\\`b\\\` < \\\`cId\\\` < \\\`h\\\` < \\\`i\\\` < \\\`iUrl\\\` < \\\`text\\\`
 
-### 示例 1：纯文本 → 粗体
+### 示例 1：设置纯文本
 
-read_rem 返回：
-
-\\\`\\\`\\\`json
-  "text": [
-    "普通标题"
-  ],
 \\\`\\\`\\\`
-
-edit_rem 调用：
-
-\\\`\\\`\\\`
-oldStr:  "text": [\\n    "普通标题"\\n  ]
-newStr:  "text": [\\n    {\\n      "b": true,\\n      "i": "m",\\n      "text": "粗体标题"\\n    }\\n  ]
+changes: {text: ["新标题"]}
 \\\`\\\`\\\`
 
-替换后变为：
+### 示例 2：设置粗体
 
-\\\`\\\`\\\`json
-  "text": [
-    {
-      "b": true,
-      "i": "m",
-      "text": "粗体标题"
-    }
-  ],
 \\\`\\\`\\\`
-
-### 示例 2：纯文本 → 部分超链接
-
+changes: {text: [{"b": true, "i": "m", "text": "粗体标题"}]}
 \\\`\\\`\\\`
-oldStr:  "text": [\\n    "点击访问官网"\\n  ]
-newStr:  "text": [\\n    "点击",\\n    {\\n      "i": "m",\\n      "iUrl": "https://remnote.com",\\n      "text": "访问官网"\\n    }\\n  ]
-\\\`\\\`\\\`
-
-### 示例 3：修改引用旁的文本
 
-read_rem 返回：
+### 示例 3：设置超链接
 
-\\\`\\\`\\\`json
-  "text": [
-    "参考 ",
-    {
-      "_id": "abc123",
-      "i": "q"
-    },
-    " 的内容"
-  ],
 \\\`\\\`\\\`
-
-只改文字部分（纯字符串可直接匹配）：
-
-\\\`\\\`\\\`
-oldStr:  " 的内容"
-newStr:  " 的详细说明"
-\\\`\\\`\\\`
-
-如果 " 的内容" 出现多次导致多匹配，加上下文：
-
-\\\`\\\`\\\`
-oldStr:  "q"\\n    },\\n    " 的内容"
-newStr:  "q"\\n    },\\n    " 的详细说明"
+changes: {text: ["点击", {"i": "m", "iUrl": "https://remnote.com", "text": "访问官网"}]}
 \\\`\\\`\\\`
 
 ### 示例 4：添加完形填空
 
 \\\`\\\`\\\`
-oldStr:  "text": [\\n    "光合作用需要阳光"\\n  ]
-newStr:  "text": [\\n    "光合作用需要",\\n    {\\n      "cId": "cloze1",\\n      "i": "m",\\n      "text": "阳光"\\n    }\\n  ]
-\\\`\\\`\\\`
-
-### 示例 5：修改简单属性
-
-\\\`\\\`\\\`
-oldStr:  "type": "default"
-newStr:  "type": "concept"
+changes: {text: ["光合作用需要", {"cId": "cloze1", "i": "m", "text": "阳光"}]}
 \\\`\\\`\\\`
 
-\\\`\\\`\\\`
-oldStr:  "highlightColor": null
-newStr:  "highlightColor": "Red"
-\\\`\\\`\\\`
+### 示例 5：设置 backText
 
 \\\`\\\`\\\`
-oldStr:  "practiceDirection": "forward"
-newStr:  "practiceDirection": "both"
+changes: {backText: ["背面答案"]}
+changes: {backText: null}  // 清除背面
 \\\`\\\`\\\`
 
 ---
@@ -167,68 +88,15 @@ newStr:  "practiceDirection": "both"
 
 ---
 
-## 常见错误
-
-| 错误 | 原因 | 解决 |
-|:-----|:-----|:-----|
-| key 顺序错 | 写 \\\`{"text":"xx","i":"m"}\\\` 但实际是 \\\`{"i":"m","text":"xx"}\\\` | 按字母序排列 key |
-| 缩进不匹配 | 空格数不对 | 仔细对照 read_rem 返回的缩进 |
-| 混淆 highlightColor 和 h | 前者字符串 \\\`"Red"\\\`，后者数字 \\\`1\\\` | 参考上方对比表 |
-| 漏 onlyAudio | \\\`i:"a"\\\` 的 \\\`onlyAudio\\\` 是必填 | true=音频，false=视频 |
-| JSON 语法错 | 引号、逗号、括号不完整 | 检查替换边界 |
-| Portal oldStr 不匹配 | Portal 编辑在简化 JSON 上匹配，不是完整 JSON | 检查 oldStr 是否匹配 9 字段简化 JSON |
-
----
-
 ## Portal 编辑
 
-当被编辑的 Rem 是 Portal（type === 'portal'）时，edit_rem 自动切换到 Portal 专用路径。
-
-**edit_rem 只能修改 Portal 的引用列表和位置属性。创建 Portal 和删除 Portal 请使用 \\\`edit_tree\\\`。**
+Portal（type=portal）的引用列表通过 \\\`portalDirectlyIncludedRem\\\` 字段修改：
 
-### 操作目标：简化 JSON
-
-Portal 的 str_replace 在 **9 字段简化 JSON** 上执行（而非完整 51 字段）：
-
-\\\`\\\`\\\`json
-{
-  "id": "abc123",
-  "type": "portal",
-  "portalType": "portal",
-  "portalDirectlyIncludedRem": ["remId1", "remId2"],
-  "parent": "parentId",
-  "positionAmongstSiblings": 3,
-  "children": ["remId1", "remId2"],
-  "createdAt": 1709000000000,
-  "updatedAt": 1709000000000
-}
 \\\`\\\`\\\`
-
-### 可写字段
-
-| 字段 | 写入方式 |
-|:-----|:---------|
-| \\\`portalDirectlyIncludedRem\\\` | diff 数组 → addToPortal / removeFromPortal |
-| \\\`parent\\\` | setParent() |
-| \\\`positionAmongstSiblings\\\` | setParent(parent, position) |
-
-其余字段（id、type、portalType、children、createdAt、updatedAt）为只读，修改只产生警告。
-
-### 示例
-
-添加引用：
-
-\\\`\\\`\\\`
-oldStr:  "portalDirectlyIncludedRem": ["remId1", "remId2"]
-newStr:  "portalDirectlyIncludedRem": ["remId1", "remId2", "remId3"]
+changes: {portalDirectlyIncludedRem: ["remId1", "remId2", "newRemId3"]}
 \\\`\\\`\\\`
 
-移除引用：
-
-\\\`\\\`\\\`
-oldStr:  "portalDirectlyIncludedRem": ["remId1", "remId2"]
-newStr:  "portalDirectlyIncludedRem": ["remId1"]
-\\\`\\\`\\\`
+创建和删除 Portal 请使用 \\\`edit_tree\\\`。
 
 ---
 
@@ -238,8 +106,19 @@ newStr:  "portalDirectlyIncludedRem": ["remId1"]
 |:-----|:-----|
 | 写入成功 | 从 Plugin 重新读取最新状态 → 覆盖缓存 |
 | 防线 2 拒绝 | **不更新**缓存（迫使重新 read_rem） |
-| 防线 3 拒绝 | 缓存不变（可调整 oldStr 重试） |
 | 部分写入失败 | **不更新**缓存（迫使重新 read_rem） |
 
 写入成功后**永远从 Plugin 重新读取**，不做本地推导，保证缓存与 SDK 状态完全同步。
+
+---
+
+## 常见错误
+
+| 错误 | 原因 | 解决 |
+|:-----|:-----|:-----|
+| 字段值类型错误 | 如 type 传了无效值 | 检查枚举类型速查表 |
+| 混淆 highlightColor 和 h | 前者字符串 \\\`"Red"\\\`，后者数字 \\\`1\\\` | 参考上方对比表 |
+| 漏 onlyAudio | \\\`i:"a"\\\` 的 \\\`onlyAudio\\\` 是必填 | true=音频，false=视频 |
+| 只读字段被忽略 | 修改了只读字段 | 产生警告但不阻断，检查字段权限 |
+| Portal 字段修改无效 | 非 Portal 类型的 Rem 修改 portalDirectlyIncludedRem | 仅 type=portal 的 Rem 支持该字段 |
 `;

package/dist/mcp/resources/edit-tree-guide.js

@@ -253,5 +253,5 @@ Portal 新增行与已有 Portal 行的区别：
 
 删除 Portal 与删除普通行相同——从 newStr 中移除该 Portal 行即可。
 
-**注意**：修改已有 Portal 的引用列表（增删引用的 Rem）请使用 \\\`edit_rem\\\`，通过 str_replace 修改简化 JSON 中的 \\\`portalDirectlyIncludedRem\\\` 数组。
+**注意**：修改已有 Portal 的引用列表（增删引用的 Rem）请使用 \\\`edit_rem\\\`，通过 changes 传入新的 \\\`portalDirectlyIncludedRem\\\` 数组。
 `;

package/dist/mcp/resources/error-reference.js

@@ -34,13 +34,11 @@ export const ERROR_REFERENCE_CONTENT = `
 
 **关键**：防线 2 失败时**不会自动更新缓存**，必须手动重新 read。
 
-### 防线 3：str_replace 精确匹配
+### 防线 3：str_replace 精确匹配（仅 edit_tree）
 
 | 错误信息 | 触发命令 | 恢复操作 |
 |:---------|:---------|:---------|
-| old_str not found in the serialized JSON of rem {remId} | edit_rem | 检查 oldStr 是否精确匹配（含引号、空格、换行） |
 | old_str not found in the tree outline of {remId} | edit_tree | 检查 oldStr 是否精确匹配缓存大纲 |
-| old_str matches {N} locations in rem {remId}. Make old_str more specific to match exactly once. | edit_rem | 扩大 oldStr 范围，包含更多上下文以唯一定位 |
 | old_str matches {N} locations in the tree outline of {remId}. Make old_str more specific to match exactly once. | edit_tree | 扩大 oldStr 范围 |
 
 ---
@@ -49,13 +47,12 @@ export const ERROR_REFERENCE_CONTENT = `
 
 | 错误信息 | 原因 | 恢复操作 |
 |:---------|:-----|:---------|
-| The replacement produced invalid JSON. Check your new_str for syntax errors. | 替换后文本不是合法 JSON | 检查 newStr 的引号、逗号、括号完整性 |
 | Failed to update field 'type': Portal 不可通过 setType() 设置 | 尝试将 type 设为 portal | Portal 只能通过 SDK 专用 API 创建，不可通过 edit_rem 设置 |
 | Failed to update field '{field}': ... | SDK setter 调用失败 | 检查字段值是否在允许范围内 |
+| Invalid value for '{field}': ... | 字段值不符合约束 | 检查字段值类型和允许范围（参考枚举类型速查表） |
 | Field '{fieldName}' is read-only and was ignored | 修改了只读字段 | **警告**（非阻断），该字段不可修改 |
+| Field '{fieldName}' is unknown and was ignored | changes 中包含不存在的字段名 | **警告**（非阻断），检查字段名拼写 |
 | Setting 'todoStatus' without 'isTodo: true' may have no effect | todoStatus 非 null 但 isTodo=false | 先将 isTodo 设为 true |
-| old_str not found in the simplified Portal JSON of rem {remId} | Portal 编辑时 oldStr 在 9 字段简化 JSON 中不匹配 | 检查 oldStr 是否匹配 Portal 简化 JSON 格式（9 字段：id、type、portalType、portalDirectlyIncludedRem、parent、positionAmongstSiblings、children、createdAt、updatedAt） |
-| old_str matches {N} locations in Portal rem {remId}. Make old_str more specific to match exactly once. | Portal 编辑时 oldStr 在简化 JSON 中匹配多处 | 扩大 oldStr 范围以唯一定位 |
 
 ---
 
@@ -109,16 +106,15 @@ export const ERROR_REFERENCE_CONTENT = `
 ├─ "has been modified since last read"
 │   └─ 重新执行 read → 然后重试 edit
 │
-├─ "old_str not found"
-│   ├─ 检查空格、换行、引号是否精确匹配
-│   ├─ Portal Rem？检查是否匹配 9 字段简化 JSON（非完整 JSON）
-│   └─ 重新 read 确认当前内容
+├─ "old_str not found"（edit_tree）
+│   ├─ 检查空格、换行是否精确匹配
+│   └─ 重新 read_tree 确认当前内容
 │
-├─ "old_str matches N locations"
+├─ "old_str matches N locations"（edit_tree）
 │   └─ 扩大 oldStr，包含更多上下文
 │
-├─ "invalid JSON"
-│   └─ 检查 newStr 的 JSON 语法
+├─ "Invalid value for" / "Field ... is unknown"（edit_rem）
+│   └─ 检查字段名拼写和值类型
 │
 ├─ "Content modification not allowed"
 │   └─ 改用 edit_rem 修改内容

package/dist/mcp/resources/rem-object-fields.js

@@ -11,8 +11,8 @@ RemObject 是本项目对 RemNote Rem 的标准化表示，包含 51 个字段
 |:-----|:-----|:-----|:---------|
 | RW | 可读可写 | 20 | 默认输出 |
 | Portal-W | Portal 专用可写 | 1 | 默认输出（Portal 简化模式） |
-| R | 只读 | 14 | 默认输出 |
-| R-F | 只读低频 | 17 | 仅 \\\`--full\\\` 输出 |
+| R | 只读 | 13 | 默认输出 |
+| R-F | 只读低频 | 18 | 仅 \\\`--full\\\` 输出 |
 
 ---
 
@@ -41,7 +41,7 @@ RemObject 是本项目对 RemNote Rem 的标准化表示，包含 51 个字段
 | 字段 | 类型 | 权限 | 说明 |
 |------|------|:----:|------|
 | \\\`parent\\\` | \\\`string \\| null\\\` | RW | 父 Rem ID。null=顶级。UI：Rem 从原位置消失，出现在新父级下 |
-| \\\`children\\\` | \\\`string[]\\\` | R | 子 Rem ID 有序数组 |
+| \\\`children\\\` | \\\`string[]\\\` | R-F | 子 Rem ID 有序数组 |
 
 ## 格式 / 显示
 
@@ -215,7 +215,7 @@ for id in currentSet:
 
 ## 只读字段列表
 
-以下 30 个字段在 str_replace 中被修改时，**只产生警告，不执行写入**：
+以下 30 个字段在 changes 中出现时，**只产生警告，不执行写入**：
 
 \\\`\\\`\\\`
 id,
@@ -360,7 +360,7 @@ RemObject 中的 \\\`text\\\` 和 \\\`backText\\\` 字段使用 RichText 格式
 { "i": "a", "onlyAudio": true, "url": "..." }   // 音频
 \\\`\\\`\\\`
 
-> 在 RemObject 格式化 JSON 中，数组内对象会展开为多行（每个 key 一行）。构造 \\\`edit_rem\\\` 的 oldStr/newStr 时必须使用实际的多行格式。
+> 在 RemObject 格式化 JSON 中，数组内对象会展开为多行（每个 key 一行）。构造 \\\`edit_tree\\\` 的 oldStr/newStr 或 \\\`edit_rem\\\` 的 changes 中 RichText 值时，必须使用正确的多行格式。
 
 ### highlightColor（Rem 级别）vs h（RichText 行内）
 
@@ -371,5 +371,5 @@ RemObject 中的 \\\`text\\\` 和 \\\`backText\\\` 字段使用 RichText 格式
 
 ### 序列化确定性
 
-RichText 对象元素内部按 **key 字母序排列**（Plugin 端 \\\`sortRichTextKeys()\\\` 处理），确保同一内容的序列化 JSON 始终一致。\\\`_id\\\` 中的 \\\`_\\\`（U+005F）排在所有小写字母（\\\`a\\\`=U+0061）之前，所以 \\\`_id\\\` 总是第一个 key。这对 \\\`edit_rem\\\` 的 str_replace 和乐观并发检测至关重要。
+RichText 对象元素内部按 **key 字母序排列**（Plugin 端 \\\`sortRichTextKeys()\\\` 处理），确保同一内容的序列化 JSON 始终一致。\\\`_id\\\` 中的 \\\`_\\\`（U+005F）排在所有小写字母（\\\`a\\\`=U+0061）之前，所以 \\\`_id\\\` 总是第一个 key。这对乐观并发检测至关重要。
 `;

package/dist/mcp/tools/edit-tools.js

@@ -3,25 +3,54 @@
  */
 import { z } from 'zod';
 import { callCli } from '../daemon-client.js';
+import { formatDataJson } from '../format.js';
 export function registerEditTools(server) {
     // -------------------------------------------------------------------------
     // edit_rem
     // -------------------------------------------------------------------------
     server.addTool({
         name: 'edit_rem',
-        description: '通过 str_replace 语义修改单个 Rem 的属性字段。\n\n操作对象是 Rem 序列化后的 JSON 文本（JSON.stringify 2 空格缩进），\n在其中将 oldStr 精确替换为 newStr，自动推导变更字段并写入。\n\n适用场景：修改文本、类型、标题级别、practiceDirection、高亮色、Todo 状态等属性；\n修改分隔符以改变闪卡类型。不适合修改子树结构（用 edit_tree）。\n\n前置条件：必须先 read_rem 建立缓存，否则被防线拒绝。\n工作流：read_rem → 查看 JSON → edit_rem 替换。\n\n三道防线：缓存存在 → 并发检测 → 精确匹配（恰好 1 次）。\nstr_replace 要点：oldStr 建议包含字段名避免歧义（如 "text": "旧值"）。替换后须是合法 JSON。\n详细操作指南（含 RichText 编辑实战示例）见 resource://edit-rem-guide。\n关联工具：read_rem（前置）、edit_tree（结构编辑）',
+        description: '直接修改单个 Rem 的属性字段。通过 changes 对象传入 {字段名: 新值}。' +
+            '\\n\\n适用场景：修改文本、类型、标题级别、高亮色、Todo 状态、practiceDirection、Portal 引用列表等属性。' +
+            '\\n不适合修改子树结构（增删移动子节点用 edit_tree）。' +
+            '\\n\\n前置条件：必须先对同一个 remId 调用 read_rem 建立缓存，否则被防线 1 拒绝。' +
+            '\\n工作流：read_rem → 查看属性 → edit_rem(changes) → 写入成功后自动从 Plugin 重新读取并更新缓存。' +
+            '\\n\\n操作指南：' +
+            '\\n- changes 对象的键=字段名，值=新值。21 个可写字段：text, backText, type, isDocument, parent, fontSize, highlightColor, isTodo, todoStatus, isCode, isQuote, isListItem, isCardItem, isSlot, isProperty, enablePractice, practiceDirection, tags, sources, positionAmongstSiblings, portalDirectlyIncludedRem' +
+            '\\n- RichText 编辑（text/backText）：传完整 RichText 数组，元素为纯字符串或格式化对象如 {"i":"m","text":"...","b":true}。backText 传 null 可清除背面' +
+            '\\n- tags/sources 使用 diff 机制：传入目标 ID 数组，系统自动计算增删差异' +
+            '\\n- portalDirectlyIncludedRem：传入目标 ID 数组（仅 type=portal 的 Rem 可修改），系统自动 diff' +
+            '\\n- parent + positionAmongstSiblings 联动：通过同一个 SDK 调用写入，可单独或同时修改' +
+            '\\n\\n枚举约束：' +
+            '\\n- type: concept / descriptor / default（portal 不可设置）' +
+            '\\n- practiceDirection: forward / backward / both / none' +
+            '\\n- highlightColor: Red / Orange / Yellow / Green / Blue / Purple / Gray / Brown / Pink / null（清除）' +
+            '\\n- fontSize: H1 / H2 / H3 / null（恢复普通）' +
+            '\\n- todoStatus: Finished / Unfinished / null（需先 isTodo=true）' +
+            '\\n\\nhighlightColor vs RichText h 字段：两者完全独立。highlightColor 是整行背景色（字符串如 "Red"）；h 是 RichText 元素内部的行内荧光底色（数字：1=Red, 2=Orange, 3=Yellow, 4=Green, 5=Purple, 6=Blue, 7=Gray, 8=Brown, 9=Pink）。' +
+            '\\n\\n输出格式：JSON 对象，包含 changes（已写入的字段名数组）和 warnings（只读/未知字段警告数组）。' +
+            '\\n\\n两道防线：' +
+            '\\n1. 缓存存在检查——未先 read_rem 则报 "has not been read yet"' +
+            '\\n2. 并发检测——edit 时重新从 Plugin 读取并对比缓存，不一致则报 "has been modified since last read"。防线拒绝/部分失败时不更新缓存，迫使重新 read_rem' +
+            '\\n\\n常见错误：' +
+            '\\n- "has not been read yet" → 先 read_rem' +
+            '\\n- "has been modified since last read" → 重新 read_rem' +
+            '\\n- "Invalid value for \'field\'" → 检查枚举合法值' +
+            '\\n- "Field \'...\' is read-only/unknown and was ignored" → 警告不阻断' +
+            '\\n\\n关联工具：read_rem（前置读取）、edit_tree（子树结构编辑）',
         parameters: z.object({
             remId: z.string().describe('目标 Rem 的 ID'),
-            oldStr: z.string().describe('要替换的原始文本（必须精确匹配缓存中的内容，且恰好匹配 1 次）'),
-            newStr: z.string().describe('替换后的新文本'),
+            changes: z.record(z.unknown()).describe('要修改的字段及新值。键=字段名，值=新值。' +
+                '支持字段：text, backText, type, isDocument, parent, fontSize, highlightColor, ' +
+                'isTodo, todoStatus, isCode, isQuote, isListItem, isCardItem, isSlot, isProperty, ' +
+                'enablePractice, practiceDirection, tags, sources, positionAmongstSiblings, portalDirectlyIncludedRem。'),
         }),
         execute: async (args) => {
             const response = await callCli('edit-rem', {
                 remId: args.remId,
-                oldStr: args.oldStr,
-                newStr: args.newStr,
+                changes: args.changes,
             });
-            return JSON.stringify(response, null, 2);
+            return formatDataJson(response);
         },
     });
     // -------------------------------------------------------------------------
@@ -29,7 +58,39 @@ export function registerEditTools(server) {
     // -------------------------------------------------------------------------
     server.addTool({
         name: 'edit_tree',
-        description: '通过 str_replace 对 Markdown 大纲进行结构编辑（行级增/删/移/重排）。\n\n操作对象是 read_tree 返回的 Markdown 大纲文本，将 oldStr 替换为 newStr，\n自动解析差异并执行结构操作。\n\n适用场景：新增子节点、删除节点、移动节点、重排顺序。\n不适合修改行内容（用 edit_rem）。\n\n前置条件：必须先 read_tree 建立缓存，否则被防线拒绝。\n工作流：read_tree → 查看大纲 → edit_tree 替换。\n\n关键禁止：\n- 禁止修改已有行的文本内容（报 content_modified）\n- 禁止删除有隐藏子节点（children:N）的行\n- 禁止删除父节点但保留子节点\n\n新行支持 Markdown 前缀（# ## ### - [ ] 等）和箭头分隔符（→ ← ↔ ↓ ↑ ↕）。\n缩进决定父子关系（每级 2 空格）。\n详细操作指南见 resource://edit-tree-guide。\n关联工具：read_tree（前置）、edit_rem（内容修改）',
+        description: '通过 str_replace 对 Markdown 大纲进行结构编辑（行级增/删/移/重排），禁止修改已有行的文字内容。' +
+            '\\n\\n适用场景：新增子节点、删除节点、移动节点到不同父节点、重排同级节点顺序。' +
+            '\\n不适合修改已有行的文本内容（用 edit_rem）。' +
+            '\\n\\n前置条件：必须先对同一个 remId 调用 read_tree 建立缓存，否则被防线拒绝。' +
+            '\\noldStr 必须精确匹配 read_tree 返回的大纲缓存（含缩进、空格、换行），且只匹配 1 次。' +
+            '\\n工作流：read_tree → 查看大纲 → edit_tree(oldStr, newStr) → 成功后自动 re-read 更新缓存（可连续 edit）。' +
+            '\\n\\n四种操作：' +
+            '\\n1. 新增：在 newStr 中插入无 remId 注释的新行。缩进决定父子关系（每级 2 空格）' +
+            '\\n2. 删除：从 newStr 中移除带 remId 的行。必须同时删除所有可见子行' +
+            '\\n3. 移动：改变行的缩进或位置（换父节点）' +
+            '\\n4. 重排：调换同级行的顺序' +
+            '\\n执行顺序：Create → Move → Reorder → Delete' +
+            '\\n\\n新增行格式：' +
+            '\\n- Markdown 前缀：# / ## / ### / - [ ] / - [x] / `代码` / ---' +
+            '\\n- 箭头分隔符（闪卡）：→ ← ↔（单行）、↓ ↑ ↕（多行，带 backText 或子节点为答案）' +
+            '\\n- 元数据注释（可选）：<!--type:concept--> <!--doc--> <!--tag:Name(id)--> 可组合' +
+            '\\n- Portal 创建：<!--portal refs:id1,id2--> 或 <!--portal-->（空 Portal）' +
+            '\\n\\n⚠️ 插入位置红线：新行必须插在目标层级所有兄弟的末尾，不能插在父 Rem 和它的 children 之间，否则触发 children_captured 错误。如需"创建新父节点并移入已有 children"，必须分两次 edit_tree 完成。' +
+            '\\n\\n六种禁止操作：' +
+            '\\n- content_modified：修改已有行内容 → 改用 edit_rem' +
+            '\\n- root_modified：修改/删除根节点' +
+            '\\n- folded_delete：删除有隐藏子节点(children:N)的行 → 用更大 depth 重新 read_tree' +
+            '\\n- orphan_detected：删父不删子 → 必须一起删' +
+            '\\n- elided_modified：修改省略占位符 → 用更大参数重新 read_tree' +
+            '\\n- children_captured：新行劫持已有子节点 → 把新行插到兄弟末尾' +
+            '\\n\\n输出格式：JSON 对象，包含 operations 数组（每项有 type: create/delete/move/reorder 及相关字段）。' +
+            '\\n\\n缓存行为：成功后自动 re-read 更新缓存；失败则不更新缓存，迫使重新 read_tree。' +
+            '\\n\\n常见错误：' +
+            '\\n- "old_str not found" → 检查精确匹配（含缩进换行）' +
+            '\\n- "old_str matches N locations" → 扩大 oldStr 包含更多上下文使其唯一' +
+            '\\n- "Content modification not allowed" → 改用 edit_rem 修改内容' +
+            '\\n- "children_captured" → 新行插到兄弟末尾，不要插在父 Rem 和 children 之间' +
+            '\\n\\n关联工具：read_tree（前置读取大纲）、edit_rem（修改单个 Rem 属性/内容）',
         parameters: z.object({
             remId: z.string().describe('根 Rem 的 ID（与 read_tree 时相同）'),
             oldStr: z.string().describe('要替换的大纲片段（必须精确匹配缓存中的内容，且恰好匹配 1 次）'),
@@ -41,7 +102,7 @@ export function registerEditTools(server) {
                 oldStr: args.oldStr,
                 newStr: args.newStr,
             });
-            return JSON.stringify(response, null, 2);
+            return formatDataJson(response);
         },
     });
 }

package/dist/mcp/tools/infra-tools.js

@@ -3,17 +3,18 @@
  */
 import { z } from 'zod';
 import { callCli } from '../daemon-client.js';
+import { formatDataJson } from '../format.js';
 export function registerInfraTools(server) {
     // -------------------------------------------------------------------------
     // setup
     // -------------------------------------------------------------------------
     server.addTool({
         name: 'setup',
-        description: '启动 Chrome 浏览器让用户登录 RemNote，保存登录凭证到本地 profile。这是使用 headless 模式（connect --headless）的前置步骤。\n\n调用后 Chrome 窗口会弹出，你需要立即告知用户："已打开 Chrome，请在浏览器中登录 RemNote，并在 RemNote 中配置 dev plugin URL（http://localhost:8080），完成后用 Cmd+Q（macOS）或关闭窗口彻底退出 Chrome"。此工具会阻塞等待用户关闭 Chrome 后返回结果。\n\n幂等：已完成 setup 后重复调用返回 alreadyDone: true。\n超时：600 秒（用户可能需要较长时间完成登录、2FA 验证等）。\n前置条件：需要桌面环境（GUI），无 GUI 环境会报错。\n关联工具：connect（启动会话，传 headless 参数实现无人值守连接）',
+        description: '启动 Chrome 浏览器让用户登录 RemNote，保存登录凭证到本地 profile。这是使用 headless 模式（connect --headless）的前置步骤。\n\nsetup 只负责登录——配置 dev plugin 是 connect 之后的事。\n\n调用后 Chrome 窗口会弹出，你需要立即告知用户："已打开 Chrome，请在浏览器中登录 RemNote，完成后用 Cmd+Q（macOS）或关闭窗口彻底退出 Chrome"。此工具会阻塞等待用户关闭 Chrome 后返回结果。\n\n幂等：已完成 setup 后重复调用返回 alreadyDone: true。\n超时：600 秒（用户可能需要较长时间完成登录、2FA 验证等）。\n前置条件：需要桌面环境（GUI），无 GUI 环境会报错。\n关联工具：connect（启动会话，传 headless 参数实现无人值守连接）',
         parameters: z.object({}),
         execute: async () => {
             const response = await callCli('setup', undefined, { timeoutMs: 600_000 });
-            return JSON.stringify(response, null, 2);
+            return formatDataJson(response);
         },
     });
     // -------------------------------------------------------------------------
@@ -21,7 +22,7 @@ export function registerInfraTools(server) {
     // -------------------------------------------------------------------------
     server.addTool({
         name: 'connect',
-        description: '启动守护进程（daemon），建立 CLI 与 RemNote Plugin 之间的通信通道。这是所有业务命令（read_rem、edit_rem、search 等）的前置步骤。\n\n适用场景：\n- 开始一次 RemNote 操作会话前，必须先调用此工具\n- 不确定 daemon 是否在运行时，也可安全调用（幂等）\n\n两种模式：\n- 标准模式（默认）：启动 daemon 后需要用户在 RemNote 中手动加载 Plugin\n- Headless 模式（headless=true）：自动启动 headless Chrome 加载 Plugin，无需用户操作。需先完成 setup（保存登录凭证）\n\n输出：返回 JSON，关键字段 ok、alreadyRunning（是否已运行）、pid、wsPort、headless。\n幂等：重复调用不会启动多个 daemon。daemon 默认 30 分钟无活动自动关闭。\n关联工具：setup（headless 前置）、disconnect（结束会话）、health（检查状态）',
+        description: '启动守护进程（daemon），建立 CLI 与 RemNote Plugin 之间的通信通道。这是所有业务命令（read_rem、edit_rem、search 等）的前置步骤。\n\n适用场景：\n- 开始一次 RemNote 操作会话前，必须先调用此工具\n- 不确定 daemon 是否在运行时，也可安全调用（幂等）\n\n两种模式：\n- 标准模式（默认）：启动 daemon 后需要用户在 RemNote 中手动加载 Plugin\n- Headless 模式（headless=true）：自动启动 headless Chrome 加载 Plugin，无需用户操作。需先完成 setup（保存登录凭证）\n\n输出：返回 JSON，关键字段 ok、alreadyRunning、instance、slotIndex、pid、wsPort、headless。\n幂等：重复调用不会启动多个 daemon。daemon 默认 30 分钟无活动自动关闭。\n关联工具：setup（headless 前置）、disconnect（结束会话）、health（检查状态）',
         parameters: z.object({
             headless: z.boolean().optional().describe('启用 headless 模式：自动启动 Chrome 加载 Plugin（需先 setup）'),
         }),
@@ -33,7 +34,7 @@ export function registerInfraTools(server) {
                 timeoutMs: 90_000,
                 flags: flags.length > 0 ? flags : undefined,
             });
-            return JSON.stringify(response, null, 2);
+            return formatDataJson(response);
         },
     });
     // -------------------------------------------------------------------------
@@ -41,11 +42,11 @@ export function registerInfraTools(server) {
     // -------------------------------------------------------------------------
     server.addTool({
         name: 'disconnect',
-        description: '停止守护进程，释放所有端口、清空内存缓存、结束当前会话。\n\n适用场景：\n- 操作完成后主动释放资源\n- 需要重置连接状态（例如排查问题时先 disconnect 再 connect）\n\n输出：返回 JSON，关键字段 ok、wasRunning（之前是否在运行）、pid。\n幂等：daemon 未运行时调用也返回 ok: true。\n所有缓存随 daemon 退出清空，下次 connect 后需重新 read。\n关联工具：connect（启动会话）、health（检查状态）',
+        description: '停止守护进程，释放所有端口、清空内存缓存、结束当前会话。\n\n适用场景：\n- 操作完成后主动释放资源\n- 需要重置连接状态（例如排查问题时先 disconnect 再 connect）\n\n输出：返回 JSON，关键字段 ok、wasRunning（之前是否在运行）、instance、pid。\n幂等：daemon 未运行时调用也返回 ok: true。\n所有缓存随 daemon 退出清空，下次 connect 后需重新 read。\n关联工具：connect（启动会话）、health（检查状态）',
         parameters: z.object({}),
         execute: async () => {
             const response = await callCli('disconnect');
-            return JSON.stringify(response, null, 2);
+            return formatDataJson(response);
         },
     });
     // -------------------------------------------------------------------------
@@ -53,7 +54,7 @@ export function registerInfraTools(server) {
     // -------------------------------------------------------------------------
     server.addTool({
         name: 'health',
-        description: '检查系统三层状态（daemon 守护进程 / Plugin 连接 / SDK 就绪），用于诊断连接问题。\n\n适用场景：\n- 业务命令失败时，首先调用 health 定位故障层级\n- 执行 connect 后确认通道是否完全就绪\n- 长时间未操作后，检查 daemon 是否仍在运行\n\n输出：返回 JSON，关键字段 ok（三层是否全部健康）、daemon.running、plugin.connected、sdk.ready、timeoutRemaining。headless 模式下额外包含 headless 对象。\n三层有严格依赖：daemon 运行 → Plugin 连接 → SDK 就绪。\nok 为 false 时：daemon 未运行则 connect；Plugin 未连接则确认 RemNote 已打开（或使用 headless 模式）；SDK 未就绪则等待重试。\n\n--diagnose 模式（headless 专用）：截图 + 详细状态 + console 错误 + 排查建议。\n--reload 模式（headless 专用）：重载 headless Chrome 页面。\n\n只读不写，不改变任何状态（--reload 除外）。\n关联工具：connect（启动）、disconnect（结束）',
+        description: '检查系统三层状态（daemon 守护进程 / Plugin 连接 / SDK 就绪），用于诊断连接问题。\n\n适用场景：\n- 业务命令失败时，首先调用 health 定位故障层级\n- 执行 connect 后确认通道是否完全就绪\n- 长时间未操作后，检查 daemon 是否仍在运行\n\n输出：返回 JSON，关键字段 ok（三层是否全部健康）、instance、slotIndex、daemon.running、plugin.connected、sdk.ready、timeoutRemaining。headless 模式下额外包含 headless 对象。\n三层有严格依赖：daemon 运行 → Plugin 连接 → SDK 就绪。\nok 为 false 时：daemon 未运行则 connect；Plugin 未连接则确认 RemNote 已打开（或使用 headless 模式）；SDK 未就绪则等待重试。\n\n--diagnose 模式（headless 专用）：截图 + 详细状态 + console 错误 + 排查建议。\n--reload 模式（headless 专用）：重载 headless Chrome 页面。\n\n只读不写，不改变任何状态（--reload 除外）。\n关联工具：connect（启动）、disconnect（结束）',
         parameters: z.object({
             diagnose: z.boolean().optional().describe('诊断 headless Chrome（截图 + 状态 + console 错误）'),
             reload: z.boolean().optional().describe('重载 headless Chrome 页面'),
@@ -67,7 +68,42 @@ export function registerInfraTools(server) {
             const response = await callCli('health', undefined, {
                 flags: flags.length > 0 ? flags : undefined,
             });
-            return JSON.stringify(response, null, 2);
+            return formatDataJson(response);
+        },
+    });
+    // -------------------------------------------------------------------------
+    // addon
+    // -------------------------------------------------------------------------
+    server.addTool({
+        name: 'addon',
+        description: '管理增强项目（addon）：查看状态、安装、卸载。\n\n增强项目是独立安装的可选组件，扩展核心功能（如 remnote-rag 语义搜索）。\n\n操作：\n- action="list"：查看所有可用增强项目的状态（已安装/未安装、已启用/已禁用、缺失配置）\n- action="install"：安装并启用指定增强项目（name 必填）\n- action="uninstall"：卸载指定增强项目（name 必填，可选 purge 清理数据目录）\n\n安装后需在配置页面中填写必需的配置项（如 API Key）。\n不需要 daemon 运行。',
+        parameters: z.object({
+            action: z.enum(['list', 'install', 'uninstall']).describe('操作类型'),
+            name: z.string().optional().describe('增强项目名称（install/uninstall 时必填）'),
+            purge: z.boolean().optional().describe('卸载时清理数据目录（仅 uninstall 有效）'),
+        }),
+        execute: async (args) => {
+            const flags = [args.action];
+            if (args.name)
+                flags.push(args.name);
+            if (args.purge)
+                flags.push('--purge');
+            const response = await callCli('addon', undefined, {
+                flags,
+            });
+            return formatDataJson(response);
+        },
+    });
+    // -------------------------------------------------------------------------
+    // clean
+    // -------------------------------------------------------------------------
+    server.addTool({
+        name: 'clean',
+        description: '清理所有 daemon 进程、PID 文件、日志、注册表和 addon 数据。\n\n适用场景：\n- daemon 进程残留，disconnect 无法正常停止时\n- 端口被占用，多次启动失败后\n- 注册表损坏需要重置\n- 完整重装，清除所有状态从零开始\n\n⚠️ 破坏性操作——会停止所有 daemon、清空所有缓存和注册表。执行后需重新 connect。\n不需要 daemon 运行。',
+        parameters: z.object({}),
+        execute: async () => {
+            const response = await callCli('clean');
+            return formatDataJson(response);
         },
     });
 }