remnote-bridge 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 remnote-bridge contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,229 @@
+# remnote-bridge
+
+[中文文档](./README_CN.md)
+
+Bridge toolkit that exposes your RemNote knowledge base to AI agents. Single package — CLI, MCP Server, and Plugin all in one.
+
+## Install
+
+```bash
+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"]
+    }
+  }
+}
+```
+
+Once connected, the AI will guide you through connecting to RemNote, loading the plugin, and everything else.
+
+---
+
+## Quick Start
+
+```bash
+# 1. Start the daemon (launches WS server + plugin dev server)
+remnote-bridge connect
+
+# 2. Load the plugin in RemNote
+#    Open RemNote → Settings → Plugins → Add Local Plugin
+#    Enter: http://localhost:8080
+
+# 3. Check system status
+remnote-bridge health
+
+# 4. Explore your knowledge base
+remnote-bridge read-globe                    # Global document overview
+remnote-bridge read-context                  # Current focus in RemNote
+remnote-bridge search "machine learning"     # Full-text search
+remnote-bridge read-tree <remId>             # Expand a subtree
+remnote-bridge read-rem <remId>              # Read Rem properties
+
+# 5. Edit content
+remnote-bridge edit-rem <remId> --old-str '"concept"' --new-str '"descriptor"'
+remnote-bridge edit-tree <remId> --old-str '  old line <!--id-->' --new-str '  new line\n  old line <!--id-->'
+
+# 6. Stop the daemon
+remnote-bridge disconnect
+```
+
+## Commands
+
+### Infrastructure
+
+| Command | Description |
+|:--------|:------------|
+| `connect` | Start the daemon process (WS server + plugin dev server) |
+| `health` | Check daemon, Plugin, and SDK status |
+| `disconnect` | Stop the daemon and release resources |
+
+### Read
+
+| Command | Description | Caches |
+|:--------|:------------|:-------|
+| `read-globe` | Global document-level overview | No |
+| `read-context` | Current focus/page context view | No |
+| `read-tree <remId>` | Subtree as Markdown outline | Yes |
+| `read-rem <remId>` | Single Rem's full JSON properties | Yes |
+| `search <query>` | Full-text search | No |
+
+### Write
+
+| Command | Description | Prerequisite |
+|:--------|:------------|:-------------|
+| `edit-rem <remId>` | Edit Rem JSON fields via str_replace | `read-rem` first |
+| `edit-tree <remId>` | Edit tree structure via str_replace | `read-tree` first |
+
+### Utilities
+
+| Command | Description |
+|:--------|:------------|
+| `mcp` | Start the MCP Server (stdio transport) |
+| `install skill` | Install AI agent skill (via [Vercel Skills](https://github.com/vercel-labs/skills)) |
+
+## MCP Server
+
+Use `remnote-bridge mcp` as an MCP server for AI clients:
+
+```json
+{
+  "mcpServers": {
+    "remnote-bridge": {
+      "command": "remnote-bridge",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+The MCP server exposes all CLI commands as tools, plus documentation resources.
+
+## 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
+```
+
+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
+
+All commands support `--json` for programmatic usage. In JSON mode, both input and output are JSON:
+
+```bash
+# Input: all parameters packed in a JSON string
+remnote-bridge --json read-rem '{"remId":"abc123","fields":["text","type"]}'
+
+# Output: single-line JSON
+# {"ok":true,"command":"read-rem","timestamp":"...","data":{...}}
+```
+
+## Architecture
+
+```
+AI Agent (Claude Code / MCP Client)
+    ↕  CLI commands (stateless short processes)
+remnote-bridge CLI
+    ↕  WebSocket IPC
+Daemon (long-lived process: WS server + handlers + cache)
+    ↕  WebSocket
+remnote-plugin (runs inside RemNote browser)
+    ↕
+RemNote SDK → Knowledge Base
+```
+
+- **CLI commands** are stateless — each invocation is an independent OS process
+- **Daemon** holds state: cache, WS connections, timeout timer
+- **Plugin** runs in the browser, calls RemNote SDK on behalf of the daemon
+- **Three safety guards** protect edits: cache existence check, optimistic concurrency detection, str_replace exact match
+
+## Configuration
+
+Optional config file: `.remnote-bridge.json` in project root.
+
+```json
+{
+  "wsPort": 3002,
+  "devServerPort": 8080,
+  "configPort": 3003,
+  "daemonTimeoutMinutes": 30,
+  "defaults": {
+    "maxNodes": 200,
+    "maxSiblings": 20,
+    "readTreeDepth": 3
+  }
+}
+```
+
+All values have sensible defaults — the config file is not required.
+
+## Acknowledgements
+
+This project was inspired by and learned from:
+
+- [remnote-mcp-bridge](https://github.com/quentintou/remnote-mcp-bridge) by [@quentintou](https://github.com/quentintou) — The original MCP bridge connecting RemNote to AI assistants. Pioneered the idea of bridging RemNote SDK to external tools via MCP.
+- [remnote-mcp-bridge (fork)](https://github.com/robert7/remnote-mcp-bridge) by [@robert7](https://github.com/robert7) — Extended the original with a generic, extensible WebSocket bridge architecture. Its Plugin ↔ WebSocket ↔ CLI layered design gave us valuable architectural insights.
+
+## Roadmap
+
+- **MCP tool decomposition** — Break the current 1:1 CLI-to-MCP mapping into finer-grained tools, giving AI agents more flexible and composable operations
+- **Improved agent instructions** — Refine Skill documentation and MCP server instructions for better AI agent comprehension
+- **RAG-powered search** — Research RemNote's local database structure to enable retrieval-augmented search, replacing the current SDK-based full-text search with more efficient semantic retrieval
+- **Multi-language support** — Internationalization for broader accessibility
+
+## License
+
+MIT

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.0')
+    .version('0.1.2')
     .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

@@ -17,7 +17,7 @@ import { SEPARATOR_FLASHCARD_CONTENT } from './resources/separator-flashcard.js'
 export async function startMcpServer() {
     const server = new FastMCP({
         name: 'remnote-bridge',
-        version: '0.1.0',
+        version: '0.1.2',
         instructions: SERVER_INSTRUCTIONS,
     });
     registerInfraTools(server);

package/dist/mcp/instructions.js

@@ -29,21 +29,31 @@ Rem 有两个独立维度：**type**（闪卡语义）和 **isDocument**（页
 | \\\`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
@@ -136,26 +167,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/separator-flashcard.js

@@ -1,30 +1,32 @@
 export const SEPARATOR_FLASHCARD_CONTENT = `
 # Separator & Flashcard Reference
 
-用户在 RemNote 中输入的分隔符决定了 Rem 的 type、backText 和默认 practiceDirection。理解分隔符是理解用户创建闪卡意图的关键。
+**重要**：分隔符（\\\`::\\\`、\\\`;;\\\`、\\\`>>\\\` 等）是 RemNote 编辑器的输入语法，**CLI 不使用分隔符**。通过 CLI 创建/修改闪卡，操作的是 \\\`type\\\`、\\\`backText\\\`、\\\`practiceDirection\\\` 字段和大纲箭头（\\\`→←↔↓↑↕\\\`）。本参考表用于理解用户意图——当用户提到分隔符时，映射到对应的 CLI 操作。
 
 ---
 
-## 分隔符完整映射表
-
-| 分隔符 | 用户输入示例 | type | backText | 默认 practiceDirection | 用途 |
-|:-------|:-------------|:-----|:---------|:-----------------------|:-----|
-| （无） | \\\`普通文本\\\` | \\\`default\\\` | \\\`null\\\` | — | 无闪卡行为 |
-| \\\`::\\\` | \\\`概念 :: 定义\\\` | \\\`concept\\\` | 后半部分 | \\\`both\\\` | 概念定义（CDF 框架） |
-| \\\`;;\\\` | \\\`属性 ;; 值\\\` | \\\`descriptor\\\` | 后半部分 | \\\`forward\\\` | 描述属性（CDF 框架） |
-| \\\`>>\\\` | \\\`问题 >> 答案\\\` | \\\`default\\\` | 后半部分 | \\\`forward\\\` | 正向问答 |
-| \\\`<<\\\` | \\\`问题 << 答案\\\` | \\\`default\\\` | 后半部分 | \\\`backward\\\` | 反向问答 |
-| \\\`<>\\\` | \\\`问题 <> 答案\\\` | \\\`default\\\` | 后半部分 | \\\`both\\\` | 双向问答 |
-| \\\`>>>\\\` | \\\`问题 >>>\\\` | \\\`default\\\` | \\\`null\\\` | \\\`forward\\\` | 多行答案（子 Rem 为答案） |
-| \\\`::>\\\` | \\\`概念 ::>\\\` | \\\`concept\\\` | \\\`null\\\` | \\\`both\\\` | 概念型多行答案 |
-| \\\`;;>\\\` | \\\`属性 ;;>\\\` | \\\`descriptor\\\` | \\\`null\\\` | \\\`forward\\\` | 描述型多行答案 |
-| \\\`{{}}\\\` | \\\`The {{capital}} of France is Paris\\\` | \\\`default\\\` | \\\`null\\\` | \\\`forward\\\` | 完形填空（Cloze） |
+## 1. 用户意图映射：编辑器分隔符 → CLI 操作
+
+当用户提到以下分隔符时，对应的 Rem 属性为：
+
+| 编辑器分隔符 | 用户输入示例 | type | backText | 默认 practiceDirection |
+|:-------------|:-------------|:-----|:---------|:-----------------------|
+| （无） | \\\`普通文本\\\` | \\\`default\\\` | \\\`null\\\` | — |
+| \\\`::\\\` | \\\`概念 :: 定义\\\` | \\\`concept\\\` | 后半部分 | \\\`both\\\` |
+| \\\`;;\\\` | \\\`属性 ;; 值\\\` | \\\`descriptor\\\` | 后半部分 | \\\`forward\\\` |
+| \\\`>>\\\` | \\\`问题 >> 答案\\\` | \\\`default\\\` | 后半部分 | \\\`forward\\\` |
+| \\\`<<\\\` | \\\`问题 << 答案\\\` | \\\`default\\\` | 后半部分 | \\\`backward\\\` |
+| \\\`<>\\\` | \\\`问题 <> 答案\\\` | \\\`default\\\` | 后半部分 | \\\`both\\\` |
+| \\\`>>>\\\` | \\\`问题 >>>\\\` | \\\`default\\\` | \\\`null\\\` | \\\`forward\\\`（多行） |
+| \\\`::>\\\` | \\\`概念 ::>\\\` | \\\`concept\\\` | \\\`null\\\` | \\\`both\\\`（多行） |
+| \\\`;;>\\\` | \\\`属性 ;;>\\\` | \\\`descriptor\\\` | \\\`null\\\` | \\\`forward\\\`（多行） |
+| \\\`{{}}\\\` | \\\`The {{capital}} of France\\\` | \\\`default\\\` | \\\`null\\\` | \\\`forward\\\`（完形填空） |
 
 ---
 
-## 大纲中的箭头分隔符
+## 2. CLI 操作方式：大纲箭头
 
-在 Markdown 大纲（read_tree / edit_tree）中，分隔符被编码为 Unicode 箭头：
+在 Markdown 大纲（read_tree / edit_tree）中，practiceDirection 编码为 Unicode 箭头：
 
 ### 单行箭头（有 backText）
 
@@ -46,7 +48,7 @@ export const SEPARATOR_FLASHCARD_CONTENT = `
 
 ---
 
-## practiceDirection 取值
+## 3. practiceDirection 取值
 
 | 值 | 含义 | 闪卡生成 |
 |:---|:-----|:---------|
@@ -57,28 +59,28 @@ export const SEPARATOR_FLASHCARD_CONTENT = `
 
 ---
 
-## CDF（Concept-Descriptor Framework）
+## 4. CDF（Concept-Descriptor Framework）
 
 RemNote 推荐的知识结构化方法：
 
-- **Concept**（\\\`::\\\`）：需要理解的核心概念——"X 是什么？"
-- **Descriptor**（\\\`;;\\\`）：概念的属性/描述——"X 的 Y 是什么？"
+- **Concept**（type:concept）：需要理解的核心概念——"X 是什么？"
+- **Descriptor**（type:descriptor）：概念的属性/描述——"X 的 Y 是什么？"
 
-典型结构：
+在 CLI 大纲中的表现（注意：用箭头和元数据标记，不用分隔符）：
 
 \\\`\\\`\\\`
-线性回归 :: 最基本的回归模型        ← Concept (type:concept, both)
-  假设 ;; 因变量与自变量呈线性关系   ← Descriptor (type:descriptor, forward)
-  损失函数 ;; 均方误差 (MSE)        ← Descriptor (type:descriptor, forward)
+线性回归 ↔ 最基本的回归模型 <!--id1 type:concept-->
+  假设 → 因变量与自变量呈线性关系 <!--id2 type:descriptor-->
+  损失函数 → 均方误差 (MSE) <!--id3 type:descriptor-->
 \\\`\\\`\\\`
 
 ---
 
-## 通过 CLI 创建闪卡
+## 5. 通过 CLI 创建闪卡
 
 ### 使用 edit_tree 新增行
 
-通过箭头分隔符创建：
+通过箭头创建（**禁止在文本中插入 \\\`::\\\`、\\\`;;\\\`、\\\`>>\\\` 等编辑器分隔符**）：
 
 | 要创建的闪卡类型 | edit_tree 新增行格式 | 额外步骤 |
 |:-----------------|:--------------------|:---------|
@@ -90,7 +92,7 @@ RemNote 推荐的知识结构化方法：
 | 多行正向 | \\\`问题 ↓\\\`（子行为答案） | — |
 | 多行双向 | \\\`问题 ↕\\\`（子行为答案） | — |
 
-### 使用 edit_rem 修改现有闪卡
+### 使用 edit_rem 修改现有 Rem 的闪卡行为
 
 修改闪卡行为的相关字段：
 
@@ -104,7 +106,7 @@ RemNote 推荐的知识结构化方法：
 
 ---
 
-## 完形填空（Cloze）
+## 6. 完形填空（Cloze）
 
 完形填空通过 RichText 中的 \\\`cId\\\` 标记实现：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remnote-bridge",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "RemNote 自动化桥接工具集：CLI + MCP Server + Plugin",
   "type": "module",
   "bin": {
@@ -8,16 +8,22 @@
     "unofficial-remnote-bridge": "./dist/cli/main.js"
   },
   "files": [
-    "dist/",
-    "remnote-plugin/src/",
+    "dist/**/*.js",
+    "remnote-plugin/src/bridge/",
+    "remnote-plugin/src/services/",
+    "remnote-plugin/src/utils/",
+    "remnote-plugin/src/widgets/",
+    "remnote-plugin/src/index.css",
+    "remnote-plugin/src/style.css",
+    "remnote-plugin/src/settings.ts",
+    "remnote-plugin/src/types.ts",
     "remnote-plugin/public/",
     "remnote-plugin/package.json",
     "remnote-plugin/postcss.config.js",
     "remnote-plugin/tailwind.config.js",
     "remnote-plugin/webpack.config.js",
     "remnote-plugin/tsconfig.json",
-    "skill/",
-    "docs/instruction/"
+    "skills/"
   ],
   "scripts": {
     "build": "tsc",
@@ -31,6 +37,7 @@
     "fastmcp": "latest",
     "zod": "^3.23.0"
   },
+  "license": "MIT",
   "devDependencies": {
     "typescript": "^5.4.0",
     "tsx": "^4.7.0",