remnote-bridge 0.1.1 → 0.1.3

package/README.md

@@ -10,6 +10,37 @@ Bridge toolkit that exposes your RemNote knowledge base to AI agents. Single pac
 npm install -g remnote-bridge
 ```
 
+## Super Quick Start (with AI)
+
+One step to connect, then let AI guide you through the rest.
+
+### Option A: Install Skill (works with Claude Code, Cursor, Windsurf, and 40+ tools)
+
+```bash
+npx skills add baobao700508/unofficial-remnote-bridge-cli -s remnote-bridge
+```
+
+### Option B: Configure MCP Server (for any MCP-compatible AI client)
+
+Add the following to your AI client's MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "remnote-bridge": {
+      "command": "remnote-bridge",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+**Tip: Install both for best results.** MCP documentation is kept concise (loaded all at once), while Skill documentation is detailed (loaded on demand). Together they complement each other. That said, either one works independently — you don't need both.
+
+Once connected, the AI will guide you through connecting to RemNote, loading the plugin, and everything else.
+
+---
+
 ## Quick Start
 
 ```bash
@@ -70,7 +101,7 @@ remnote-bridge disconnect
 | Command | Description |
 |:--------|:------------|
 | `mcp` | Start the MCP Server (stdio transport) |
-| `install skill` | Install Claude Code skill to `~/.claude/skills/remnote-bridge/` |
+| `install skill` | Install AI agent skill (via [Vercel Skills](https://github.com/vercel-labs/skills)) |
 
 ## MCP Server
 
@@ -89,13 +120,46 @@ Use `remnote-bridge mcp` as an MCP server for AI clients:
 
 The MCP server exposes all CLI commands as tools, plus documentation resources.
 
-## Claude Code Skill
+## AI Agent Skill
+
+The Skill provides detailed instructions (SKILL.md + 11 command docs) that teach AI agents how to use remnote-bridge — including command selection, workflows, safety rules, and flashcard operations.
+
+### Install via Vercel Skills (recommended)
+
+Powered by the [Vercel Skills](https://github.com/vercel-labs/skills) ecosystem. Supports **40+ AI coding tools** including Claude Code, Cursor, Windsurf, GitHub Copilot, Cline, and more.
 
 ```bash
+# Direct — interactive agent selection
+npx skills add baobao700508/unofficial-remnote-bridge-cli -s remnote-bridge
+
+# Or through the built-in wrapper (same interactive experience)
 remnote-bridge install skill
 ```
 
-Installs the skill to `~/.claude/skills/remnote-bridge/`, enabling Claude Code to operate your RemNote knowledge base through natural language.
+The interactive installer will detect your installed AI tools and let you choose which ones to install the skill for.
+
+### Fallback: Claude Code only
+
+If `npx` is not available, or you prefer manual installation:
+
+```bash
+remnote-bridge install skill --copy
+```
+
+This copies the skill files directly to `~/.claude/skills/remnote-bridge/`.
+
+### What gets installed
+
+```
+<agent-skills-dir>/remnote-bridge/
+├── SKILL.md              # Core skill — command decisions, workflows, safety rules
+└── instructions/         # Detailed per-command documentation
+    ├── overall.md        # Global overview
+    ├── connect.md        # connect command
+    ├── read-tree.md      # read-tree command
+    ├── edit-tree.md      # edit-tree command
+    └── ...               # 8 more command docs
+```
 
 ## JSON Mode
 

package/dist/cli/commands/install-skill.js

@@ -1,16 +1,57 @@
 /**
  * install skill 命令
  *
- * 将 SKILL.md 和 docs/instruction/*.md 安装到 ~/.claude/skills/remnote-bridge/
+ * 薄层封装 Vercel Skills CLI（npx skills add），利用其交互式选择让用户适配不同 AI 编程工具。
+ * npx 不可用时 fallback 到直接复制（仅 Claude Code）。
  */
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
+import { spawn, execSync } from 'child_process';
+const GITHUB_REPO = 'baobao700508/unofficial-remnote-bridge-cli';
+const SKILL_NAME = 'remnote-bridge';
 export async function installSkillCommand() {
+    // 检测 npx 是否可用
+    let hasNpx = false;
+    try {
+        execSync('npx --version', { stdio: 'pipe', timeout: 5000 });
+        hasNpx = true;
+    }
+    catch {
+        // npx 不可用
+    }
+    if (!hasNpx) {
+        console.log('未检测到 npx，使用内置方式安装到 Claude Code...\n');
+        copySkillFiles();
+        return;
+    }
+    // 直接调用 npx skills add，继承 stdio 让用户看到交互式选择界面
+    console.log(`通过 Vercel Skills CLI 安装 ${SKILL_NAME}...\n`);
+    const child = spawn('npx', ['skills', 'add', GITHUB_REPO, '-s', SKILL_NAME], {
+        stdio: 'inherit',
+        shell: true,
+    });
+    await new Promise((resolve) => {
+        child.on('close', (code) => {
+            if (code !== 0) {
+                console.log(`\nVercel Skills CLI 退出码: ${code}`);
+                console.log('如需使用内置方式安装（仅 Claude Code），请运行：');
+                console.log('  remnote-bridge install skill --copy\n');
+                process.exitCode = 1;
+            }
+            resolve();
+        });
+    });
+}
+export async function installSkillCopyCommand() {
+    copySkillFiles();
+}
+function copySkillFiles() {
     // 从包安装路径计算包根（dist/cli/commands/install-skill.js → 包根）
     const packageRoot = path.resolve(import.meta.dirname, '..', '..', '..');
-    const skillSource = path.join(packageRoot, 'skill', 'SKILL.md');
-    const instructionDir = path.join(packageRoot, 'docs', 'instruction');
+    const skillDir = path.join(packageRoot, 'skills', 'remnote-bridge');
+    const skillSource = path.join(skillDir, 'SKILL.md');
+    const instructionDir = path.join(skillDir, 'instructions');
     if (!fs.existsSync(skillSource)) {
         console.error(`错误: 找不到 SKILL.md: ${skillSource}`);
         process.exitCode = 1;
@@ -19,15 +60,12 @@ export async function installSkillCommand() {
     // 目标目录
     const targetDir = path.join(os.homedir(), '.claude', 'skills', 'remnote-bridge');
     fs.mkdirSync(targetDir, { recursive: true });
-    // 复制 SKILL.md，更新 instruction 路径引用
-    let skillContent = fs.readFileSync(skillSource, 'utf-8');
-    const targetInstructionDir = path.join(targetDir, 'instruction');
-    // 替换相对路径 docs/instruction/ 为安装后的绝对路径
-    skillContent = skillContent.replace(/docs\/instruction\//g, targetInstructionDir + '/');
-    fs.writeFileSync(path.join(targetDir, 'SKILL.md'), skillContent, 'utf-8');
+    // 复制 SKILL.md
+    fs.copyFileSync(skillSource, path.join(targetDir, 'SKILL.md'));
     console.log(`  SKILL.md → ${targetDir}/SKILL.md`);
-    // 复制 docs/instruction/*.md
+    // 复制 instructions/*.md
     if (fs.existsSync(instructionDir)) {
+        const targetInstructionDir = path.join(targetDir, 'instructions');
         fs.mkdirSync(targetInstructionDir, { recursive: true });
         const files = fs.readdirSync(instructionDir).filter(f => f.endsWith('.md'));
         for (const file of files) {
@@ -35,5 +73,7 @@ export async function installSkillCommand() {
             console.log(`  ${file} → ${targetInstructionDir}/${file}`);
         }
     }
-    console.log(`\nSkill 已安装到 ${targetDir}`);
+    console.log(`\nSkill 已安装到 ${targetDir}（仅 Claude Code）`);
+    console.log('如需安装到其他 AI 工具，请运行：');
+    console.log(`  npx skills add ${GITHUB_REPO} -s ${SKILL_NAME}\n`);
 }

package/dist/cli/main.js

@@ -15,7 +15,7 @@ import { editTreeCommand } from './commands/edit-tree.js';
 import { readGlobeCommand } from './commands/read-globe.js';
 import { readContextCommand } from './commands/read-context.js';
 import { searchCommand } from './commands/search.js';
-import { installSkillCommand } from './commands/install-skill.js';
+import { installSkillCommand, installSkillCopyCommand } from './commands/install-skill.js';
 const program = new Command();
 /**
  * --json 模式下解析 JSON 输入参数。
@@ -53,7 +53,7 @@ function parseJsonInput(command, jsonStr, requiredFields = []) {
 program
     .name('remnote-bridge')
     .description('RemNote Bridge — CLI + MCP Server + Plugin')
-    .version('0.1.1')
+    .version('0.1.3')
     .option('--json', '以 JSON 格式输出（适用于程序化调用）');
 program
     .command('connect')
@@ -295,6 +295,14 @@ program.command('mcp')
 // install 子命令组
 const installCmd = program.command('install').description('安装组件');
 installCmd.command('skill')
-    .description('安装 Skill 到 ~/.claude/skills/remnote-bridge/')
-    .action(async () => { await installSkillCommand(); });
+    .description('安装 Skill（推荐使用 npx skills add，或 --copy 直接复制）')
+    .option('--copy', '直接复制到 ~/.claude/skills/（不使用 Vercel Skills CLI）')
+    .action(async (opts) => {
+    if (opts.copy) {
+        await installSkillCopyCommand();
+    }
+    else {
+        await installSkillCommand();
+    }
+});
 program.parse();

package/dist/mcp/index.js

@@ -11,13 +11,14 @@ import { registerEditTools } from './tools/edit-tools.js';
 import { registerInfraTools } from './tools/infra-tools.js';
 import { OUTLINE_FORMAT_CONTENT } from './resources/outline-format.js';
 import { REM_OBJECT_FIELDS_CONTENT } from './resources/rem-object-fields.js';
+import { EDIT_REM_GUIDE_CONTENT } from './resources/edit-rem-guide.js';
 import { EDIT_TREE_GUIDE_CONTENT } from './resources/edit-tree-guide.js';
 import { ERROR_REFERENCE_CONTENT } from './resources/error-reference.js';
 import { SEPARATOR_FLASHCARD_CONTENT } from './resources/separator-flashcard.js';
 export async function startMcpServer() {
     const server = new FastMCP({
         name: 'remnote-bridge',
-        version: '0.1.1',
+        version: '0.1.3',
         instructions: SERVER_INSTRUCTIONS,
     });
     registerInfraTools(server);
@@ -40,6 +41,14 @@ export async function startMcpServer() {
             return { text: REM_OBJECT_FIELDS_CONTENT };
         },
     });
+    server.addResource({
+        uri: 'remnote://edit-rem-guide',
+        name: 'edit_rem 操作指南',
+        mimeType: 'text/markdown',
+        async load() {
+            return { text: EDIT_REM_GUIDE_CONTENT };
+        },
+    });
     server.addResource({
         uri: 'remnote://edit-tree-guide',
         name: 'edit_tree 操作指南',

package/dist/mcp/instructions.js

@@ -25,25 +25,35 @@ Rem 有两个独立维度：**type**（闪卡语义）和 **isDocument**（页
 | type | 含义 | UI 表现 |
 |:-----|:-----|:--------|
 | \\\`concept\\\` | 概念定义 | 文字**加粗** |
-| \\\`descriptor\\\` | 描述/属性 | 文字*斜体* |
+| \\\`descriptor\\\` | 描述/属性 | 正常字重（与 default 无视觉差异） |
 | \\\`default\\\` | 普通 Rem | 正常字重 |
 | \\\`portal\\\` | 嵌入引用容器 | 紫色边框（**只读**，不可设置） |
 
-### Separator 与闪卡创建
+### 闪卡的 CLI 操作方式
 
-分隔符决定 Rem 的 type、backText 和练习方向。创建闪卡的本质是设置正确的分隔符：
+闪卡由 Rem 的 \\\`type\\\`、\\\`backText\\\`、\\\`practiceDirection\\\` 三个字段控制。通过 CLI 创建/修改闪卡，操作的是这些**字段**，而非分隔符。
 
-| 分隔符 | type | 用途 |
-|:-------|:-----|:-----|
-| \\\`::\\\` | concept | 概念定义（双向） |
-| \\\`;;\\\` | descriptor | 描述属性（正向） |
-| \\\`>>\\\` | default | 正向问答 |
-| \\\`<<\\\` | default | 反向问答 |
-| \\\`<>\\\` | default | 双向问答 |
-| \\\`>>>\\\` | default | 多行答案（子 Rem 为答案） |
-| \\\`{{}}\\\` | default | 完形填空 |
+**禁止**：在文本中插入分隔符（\\\`::\\\`、\\\`;;\\\`、\\\`>>\\\` 等）来创建闪卡。分隔符是 RemNote 编辑器的输入语法，CLI 无法识别。
 
-完整分隔符-闪卡映射表见 \\\`resource://separator-flashcard\\\`。
+| 闪卡操作 | CLI 方法 |
+|:---------|:---------|
+| 创建概念定义 | \\\`edit_tree\\\` 新增行 \\\`概念 ↔ 定义\\\`，再 \\\`edit_rem\\\` 设 \\\`type: "concept"\\\` |
+| 创建正向问答 | \\\`edit_tree\\\` 新增行 \\\`问题 → 答案\\\` |
+| 创建多行答案 | \\\`edit_tree\\\` 新增行 \\\`问题 ↓\\\`（子行自动成为答案） |
+| 改变闪卡类型 | \\\`edit_rem\\\` 修改 \\\`type\\\`、\\\`backText\\\`、\\\`practiceDirection\\\` |
+
+### 理解用户意图：分隔符映射
+
+用户在 RemNote 编辑器中通过分隔符创建闪卡。当用户提到这些分隔符时，你需要理解其意图并映射到 CLI 操作：
+
+| 用户说 / 编辑器分隔符 | 对应的 type | 对应的 practiceDirection |
+|:----------------------|:-----------|:-----------------------|
+| \\\`::\\\` | concept | both |
+| \\\`;;\\\` | descriptor | forward |
+| \\\`>>\\\` / \\\`<<\\\` / \\\`<>\\\` | default | forward / backward / both |
+| \\\`>>>\\\` / \\\`::>\\\` / \\\`;;>\\\` | default / concept / descriptor | forward / both / forward（多行） |
+
+完整映射表见 \\\`resource://separator-flashcard\\\`。
 
 ### 链接机制
 
@@ -66,6 +76,8 @@ RemNote 的格式设置（标题、高亮、代码等）会注入隐藏的系统
 \\\`\\\`\\\`
 connect → 启动 daemon（幂等，重复调用安全）
   ↓
+⚠️ 用户操作：确保 RemNote 中已加载插件（见下方说明）
+  ↓
 health → 确认三层就绪（daemon / Plugin / SDK）
   ↓
 业务操作（read / search / edit）
@@ -79,6 +91,25 @@ disconnect → 关闭 daemon，清空所有缓存
 - \\\`disconnect\\\` 会销毁所有缓存，之前的 read 结果全部失效
 - daemon 默认 30 分钟无活动自动关闭
 
+### ⚠️ connect 后需要用户配合（重要）
+
+\\\`connect\\\` 成功只意味着 daemon 和 webpack-dev-server 已启动，**Plugin 并未自动连接**。用户必须在 RemNote 中完成以下操作，Plugin 才能连接到 daemon：
+
+**首次使用**（RemNote 从未加载过此插件）：
+1. 打开 RemNote 桌面端或网页端
+2. 点击左侧边栏底部的插件图标（拼图形状）
+3. 点击「开发你的插件」（Develop Your Plugin）
+4. 在输入框中填入 \\\`http://localhost:8080\\\`（即 connect 输出的 webpack-dev-server 地址）
+5. 等待插件加载完成
+
+**非首次使用**（之前已加载过此插件）：
+- 只需**刷新 RemNote 页面**即可（浏览器 F5 或 Cmd+R），插件会自动重新连接
+
+**你必须这样做**：
+1. 执行 \\\`connect\\\` 后，**立即告知用户需要完成上述操作**
+2. **不要在 connect 后直接调用业务命令**——此时 Plugin 尚未连接，命令会失败
+3. 引导用户完成操作后，用 \\\`health\\\` 确认三层就绪，再执行业务命令
+
 ---
 
 ## 3. Common Scenarios
@@ -119,7 +150,35 @@ disconnect → 关闭 daemon，清空所有缓存
 2. 在返回的 JSON 文本中定位要修改的部分
 3. \\\`edit_rem\\\` 用 str_replace 替换：oldStr 精确匹配原文，newStr 是修改后的文本
 
-str_replace 操作的是格式化 JSON 文本（2 空格缩进）。oldStr 要包含足够上下文（如字段名 + 值），避免模糊匹配。替换后必须是合法 JSON。
+str_replace 操作的是 \\\`JSON.stringify(remObject, null, 2)\\\` 格式化文本。oldStr 要包含足够上下文（如字段名 + 值），避免模糊匹配。替换后必须是合法 JSON。
+
+**RichText 编辑要点**（\\\`text\\\` 和 \\\`backText\\\` 字段）：
+
+RichText 在格式化 JSON 中是多行结构，对象内 key 按**字母序**排列（\\\`_id\\\` 排最前，因为 \\\`_\\\` < \\\`a\\\`）。
+
+示例——将纯文本改为粗体：
+
+\\\`\\\`\\\`
+oldStr:  "text": [\\n    "普通标题"\\n  ]
+newStr:  "text": [\\n    {\\n      "b": true,\\n      "i": "m",\\n      "text": "粗体标题"\\n    }\\n  ]
+\\\`\\\`\\\`
+
+示例——给文本加超链接：
+
+\\\`\\\`\\\`
+oldStr:  "text": [\\n    "点击访问官网"\\n  ]
+newStr:  "text": [\\n    "点击",\\n    {\\n      "i": "m",\\n      "iUrl": "https://remnote.com",\\n      "text": "访问官网"\\n    }\\n  ]
+\\\`\\\`\\\`
+
+注意：\\\`highlightColor\\\`（Rem 顶层字段，字符串如 \\\`"Red"\\\`）和 RichText 的 \\\`h\\\`（行内格式标记，数字 0-9）是两个独立属性。详见 \\\`resource://rem-object-fields\\\`。
+
+### 缓存行为速查
+
+| 工具 | 缓存行为 | 用途 |
+|:-----|:---------|:-----|
+| \\\`read_rem\\\` | 写入缓存 | 供 \\\`edit_rem\\\` 使用 |
+| \\\`read_tree\\\` | 写入缓存 | 供 \\\`edit_tree\\\` 使用 |
+| \\\`search\\\` / \\\`read_globe\\\` / \\\`read_context\\\` | **不缓存** | 不能作为 edit 前置 |
 
 ### 场景 E：修改结构（新增/删除/移动/重排）
 
@@ -136,26 +195,32 @@ str_replace 操作的是格式化 JSON 文本（2 空格缩进）。oldStr 要
 
 **红线**：edit_tree **禁止修改已有行的文字内容**——改内容必须用 edit_rem。edit_tree 只做结构操作。
 
-### 场景 F：创建闪卡
+### 场景 F：创建 / 修改闪卡
 
-> 用户说："创建一个概念定义"、"做个正向问答卡"
+> 用户说："创建一个概念定义"、"做个正向问答卡"、"把这个改成 concept"
 
-创建闪卡的本质是创建带正确分隔符的 Rem。通过 \\\`edit_tree\\\` 新增行时使用箭头分隔符：
+闪卡由 \\\`type\\\`、\\\`backText\\\`、\\\`practiceDirection\\\` 三个字段控制。操作方式：
 
-- 概念定义：\\\`新概念 → 定义内容\\\`（然后用 edit_rem 将 type 改为 concept）
+**创建新闪卡**（\\\`edit_tree\\\` 新增行 + 箭头）：
 - 正向问答：\\\`问题 → 答案\\\`
-- 多行答案：\\\`问题 ↓\\\`（子行自动成为答案）
 - 双向问答：\\\`问题 ↔ 答案\\\`
+- 多行答案：\\\`问题 ↓\\\`（子行自动成为答案）
+- 概念定义：\\\`概念 ↔ 定义\\\`，再用 \\\`edit_rem\\\` 设 \\\`type: "concept"\\\`
+
+**修改现有 Rem 的闪卡行为**（\\\`read_rem\\\` → \\\`edit_rem\\\`）：
+- 改类型：修改 \\\`type\\\` 字段（\\\`"default"\\\` → \\\`"concept"\\\`）
+- 改方向：修改 \\\`practiceDirection\\\`（\\\`"forward"\\\` / \\\`"backward"\\\` / \\\`"both"\\\` / \\\`"none"\\\`）
+- 加/改背面：修改 \\\`backText\\\` 字段
 
-如果要修改现有 Rem 的闪卡行为（改分隔符类型），使用 \\\`read_rem\\\` → \\\`edit_rem\\\` 修改 type、backText、practiceDirection 等字段。
+**禁止**：在文本内容中插入 \\\`::\\\`、\\\`;;\\\`、\\\`>>\\\` 等分隔符——这些是 RemNote 编辑器语法，CLI 不识别。
 
 ### 场景 G：排查连接问题
 
 > 用户说："连不上"、"命令报错了"
 
 使用 \\\`health\\\` 检查三层状态，然后对症处理：
-- daemon 未运行 → 执行 \\\`connect\\\`
-- Plugin 未连接 → 提醒用户打开 RemNote 并确认插件已加载
+- daemon 未运行 → 执行 \\\`connect\\\`，然后引导用户在 RemNote 中加载插件
+- Plugin 未连接 → 提醒用户：首次使用需在 RemNote 的「开发你的插件」中填入 \\\`http://localhost:8080\\\`；非首次使用只需刷新 RemNote 页面
 - SDK 未就绪 → 等待几秒后重试 health
 
 ---

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

@@ -0,0 +1,192 @@
+export const EDIT_REM_GUIDE_CONTENT = `
+# edit_rem 操作指南
+
+edit_rem 通过 str_replace 语义修改单个 Rem 的属性。操作对象是 \\\`JSON.stringify(remObject, null, 2)\\\` 的格式化文本。
+
+---
+
+## 前置条件
+
+必须先 \\\`read_rem\\\` 同一个 remId，建立缓存后才能 \\\`edit_rem\\\`。跳过会触发防线 1 错误。
+
+工作流：\\\`read_rem\\\` → 查看 JSON → \\\`edit_rem\\\`（oldStr/newStr）。
+
+---
+
+## str_replace 语义
+
+### 操作对象
+
+格式化缩进 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" 错误。
+
+---
+
+## 三道防线
+
+| 防线 | 检查内容 | 失败时 |
+|:-----|:---------|:-------|
+| 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。
+
+---
+
+## RichText 编辑实战
+
+\\\`text\\\` 和 \\\`backText\\\` 字段使用 RichText 格式。在格式化 JSON 中，RichText 数组内的对象展开为多行，key 按**字母序**排列。
+
+### 关键排序规则
+
+- \\\`_id\\\`（U+005F）排在所有小写字母之前，所以 \\\`_id\\\` 总是第一个 key
+- 示例排序：\\\`_id\\\` < \\\`b\\\` < \\\`cId\\\` < \\\`h\\\` < \\\`i\\\` < \\\`iUrl\\\` < \\\`text\\\`
+
+### 示例 1：纯文本 → 粗体
+
+read_rem 返回：
+
+\\\`\\\`\\\`json
+  "text": [
+    "普通标题"
+  ],
+\\\`\\\`\\\`
+
+edit_rem 调用：
+
+\\\`\\\`\\\`
+oldStr:  "text": [\\n    "普通标题"\\n  ]
+newStr:  "text": [\\n    {\\n      "b": true,\\n      "i": "m",\\n      "text": "粗体标题"\\n    }\\n  ]
+\\\`\\\`\\\`
+
+替换后变为：
+
+\\\`\\\`\\\`json
+  "text": [
+    {
+      "b": true,
+      "i": "m",
+      "text": "粗体标题"
+    }
+  ],
+\\\`\\\`\\\`
+
+### 示例 2：纯文本 → 部分超链接
+
+\\\`\\\`\\\`
+oldStr:  "text": [\\n    "点击访问官网"\\n  ]
+newStr:  "text": [\\n    "点击",\\n    {\\n      "i": "m",\\n      "iUrl": "https://remnote.com",\\n      "text": "访问官网"\\n    }\\n  ]
+\\\`\\\`\\\`
+
+### 示例 3：修改引用旁的文本
+
+read_rem 返回：
+
+\\\`\\\`\\\`json
+  "text": [
+    "参考 ",
+    {
+      "_id": "abc123",
+      "i": "q"
+    },
+    " 的内容"
+  ],
+\\\`\\\`\\\`
+
+只改文字部分（纯字符串可直接匹配）：
+
+\\\`\\\`\\\`
+oldStr:  " 的内容"
+newStr:  " 的详细说明"
+\\\`\\\`\\\`
+
+如果 " 的内容" 出现多次导致多匹配，加上下文：
+
+\\\`\\\`\\\`
+oldStr:  "q"\\n    },\\n    " 的内容"
+newStr:  "q"\\n    },\\n    " 的详细说明"
+\\\`\\\`\\\`
+
+### 示例 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"
+\\\`\\\`\\\`
+
+\\\`\\\`\\\`
+oldStr:  "highlightColor": null
+newStr:  "highlightColor": "Red"
+\\\`\\\`\\\`
+
+\\\`\\\`\\\`
+oldStr:  "practiceDirection": "forward"
+newStr:  "practiceDirection": "both"
+\\\`\\\`\\\`
+
+---
+
+## highlightColor vs h
+
+| 属性 | 位置 | 值类型 | 作用范围 |
+|:-----|:-----|:-------|:---------|
+| \\\`highlightColor\\\` | RemObject 顶层字段 | 字符串（\\\`"Red"\\\`, \\\`"Blue"\\\` 等）或 \\\`null\\\` | 整行背景色 |
+| \\\`h\\\` | RichText 元素内格式标记 | 数字 0-9（RemColor 枚举） | 行内文字片段 |
+
+两者完全独立。\\\`highlightColor\\\` 通过 \\\`setHighlightColor()\\\` 写入，\\\`h\\\` 通过 \\\`setText()\\\` 随 RichText 一起写入。
+
+---
+
+## 常见错误
+
+| 错误 | 原因 | 解决 |
+|:-----|:-----|:-----|
+| key 顺序错 | 写 \\\`{"text":"xx","i":"m"}\\\` 但实际是 \\\`{"i":"m","text":"xx"}\\\` | 按字母序排列 key |
+| 缩进不匹配 | 空格数不对 | 仔细对照 read_rem 返回的缩进 |
+| 混淆 highlightColor 和 h | 前者字符串 \\\`"Red"\\\`，后者数字 \\\`1\\\` | 参考上方对比表 |
+| 漏 onlyAudio | \\\`i:"a"\\\` 的 \\\`onlyAudio\\\` 是必填 | true=音频，false=视频 |
+| JSON 语法错 | 引号、逗号、括号不完整 | 检查替换边界 |
+
+---
+
+## 缓存更新行为
+
+| 场景 | 缓存 |
+|:-----|:-----|
+| 写入成功 | 从 Plugin 重新读取最新状态 → 覆盖缓存 |
+| 防线 2 拒绝 | **不更新**缓存（迫使重新 read_rem） |
+| 防线 3 拒绝 | 缓存不变（可调整 oldStr 重试） |
+| 部分写入失败 | **不更新**缓存（迫使重新 read_rem） |
+
+写入成功后**永远从 Plugin 重新读取**，不做本地推导，保证缓存与 SDK 状态完全同步。
+`;