remnote-bridge 0.1.1 → 0.1.2

package/README.md

@@ -10,6 +10,35 @@ 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"]
+    }
+  }
+}
+```
+
+Once connected, the AI will guide you through connecting to RemNote, loading the plugin, and everything else.
+
+---
+
 ## Quick Start
 
 ```bash
@@ -70,7 +99,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 +118,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.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.1',
+        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.1",
+  "version": "0.1.2",
   "description": "RemNote 自动化桥接工具集：CLI + MCP Server + Plugin",
   "type": "module",
   "bin": {
@@ -23,8 +23,7 @@
     "remnote-plugin/tailwind.config.js",
     "remnote-plugin/webpack.config.js",
     "remnote-plugin/tsconfig.json",
-    "skill/",
-    "docs/instruction/"
+    "skills/"
   ],
   "scripts": {
     "build": "tsc",

package/{skill → skills/remnote-bridge}/SKILL.md

@@ -7,21 +7,21 @@ description: "RemNote 知识库操作指南。通过 remnote-bridge 命令行工
 
 本 skill 指导 AI Agent 通过 remnote-bridge 操作 RemNote 知识库。
 
-**详细命令文档**位于 `docs/instruction/` 目录下，执行具体命令前务必先读取对应文件：
+**详细命令文档**位于 `instructions/` 目录下，执行具体命令前务必先读取对应文件：
 
 | 命令 | 文档路径 |
 |:-----|:---------|
-| connect | `docs/instruction/connect.md` |
-| disconnect | `docs/instruction/disconnect.md` |
-| health | `docs/instruction/health.md` |
-| read-rem | `docs/instruction/read-rem.md` |
-| edit-rem | `docs/instruction/edit-rem.md` |
-| read-tree | `docs/instruction/read-tree.md` |
-| edit-tree | `docs/instruction/edit-tree.md` |
-| read-globe | `docs/instruction/read-globe.md` |
-| read-context | `docs/instruction/read-context.md` |
-| search | `docs/instruction/search.md` |
-| 全局概览 | `docs/instruction/overall.md` |
+| connect | `instructions/connect.md` |
+| disconnect | `instructions/disconnect.md` |
+| health | `instructions/health.md` |
+| read-rem | `instructions/read-rem.md` |
+| edit-rem | `instructions/edit-rem.md` |
+| read-tree | `instructions/read-tree.md` |
+| edit-tree | `instructions/edit-tree.md` |
+| read-globe | `instructions/read-globe.md` |
+| read-context | `instructions/read-context.md` |
+| search | `instructions/search.md` |
+| 全局概览 | `instructions/overall.md` |
 
 ---
 
@@ -42,7 +42,7 @@ RemNote 中所有内容的基本单元都是 **Rem**。文档、文件夹、闪
 
 两个独立维度：
 
-- **type**（闪卡语义）：`concept`（`::`，加粗）、`descriptor`（`;;`，斜体）、`default`（普通）、`portal`（只读）
+- **type**（闪卡语义）：`concept`（加粗）、`descriptor`（斜体）、`default`（普通）、`portal`（只读）
 - **isDocument**（页面语义）：与 type 完全独立
 
 ### CDF 框架（Concept-Descriptor Framework）
@@ -55,19 +55,30 @@ RemNote 推荐的知识结构化方法：
   损失函数 ;; 均方误差 (MSE)        ← Descriptor
 ```
 
-### 分隔符与闪卡方向
+### 闪卡的 CLI 操作方式
 
-| 分隔符 | type | 默认方向 | 用途 |
-|:-------|:-----|:---------|:-----|
-| `::` | concept | both | 概念定义 |
-| `;;` | descriptor | forward | 描述属性 |
-| `>>` | default | forward | 正向问答 |
-| `<<` | default | backward | 反向问答 |
-| `<>` | default | both | 双向问答 |
-| `>>>` | default | forward | 多行答案 |
-| `::>` | concept | both | 概念型多行答案 |
-| `;;>` | descriptor | forward | 描述型多行答案 |
-| `{{}}` | default | forward | 完形填空 |
+闪卡由 `type`、`backText`、`practiceDirection` 三个字段控制。通过 CLI 操作闪卡，修改的是这些**字段**。
+
+**禁止**：在文本中插入分隔符（`::`、`;;`、`>>`、`<<` 等）来创建闪卡。分隔符是 RemNote 编辑器的输入语法，CLI 无法识别。
+
+| 闪卡操作 | 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 | 多行（子 Rem 为答案） |
+| `{{}}` | default | forward（完形填空） |
 
 ### 三种链接机制
 
@@ -141,16 +152,35 @@ Rem 的属性（文本、类型、格式、标签）  → edit-rem   （前置
 
 ## 3. 标准工作流
 
+### ⚠️ 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），插件会自动重新连接
+
+**你必须**：执行 `connect` 后，**立即告知用户需要完成上述操作**，不要直接调用业务命令。引导用户完成后，用 `health` 确认三层就绪再继续。
+
+### 完整流程
+
 ```
 1. connect              -- 启动会话（幂等，重复调用安全）
-2. health               -- 确认三层就绪：daemon → Plugin → SDK（链式依赖）
-3. read-globe           -- 了解知识库结构（首次探索）
+2. ⚠️ 引导用户在 RemNote 中加载插件（首次填端口，非首次刷新页面）
+3. health               -- 确认三层就绪：daemon → Plugin → SDK（链式依赖）
+4. read-globe           -- 了解知识库结构（首次探索）
    或 read-context      -- 了解用户当前上下文
-4. search "关键词"       -- 定位目标 Rem（结果不进缓存！）
-5. read-tree <id>       -- 展开子树 → 写入缓存（edit-tree 的前置）
-6. read-rem <id>        -- 读取属性 → 写入缓存（edit-rem 的前置）
-7. edit-rem / edit-tree -- 执行修改
-8. disconnect           -- 结束会话（缓存全部清空，幂等）
+5. search "关键词"       -- 定位目标 Rem（结果不进缓存！）
+6. read-tree <id>       -- 展开子树 → 写入缓存（edit-tree 的前置）
+7. read-rem <id>        -- 读取属性 → 写入缓存（edit-rem 的前置）
+8. edit-rem / edit-tree -- 执行修改
+9. disconnect           -- 结束会话（缓存全部清空，幂等）
 ```
 
 **超时**：daemon 默认 30 分钟无 CLI 交互自动关闭，每次请求重置计时器。长时间操作间可用 health 保活。
@@ -299,12 +329,12 @@ read-tree / read-globe / read-context 输出 Markdown 大纲，edit-tree 基于
 
 ### 新增行格式
 
-新增行可用 Markdown 前缀和箭头分隔符：
+新增行可用 Markdown 前缀和箭头：
 
 ```markdown
   # 新标题
   新闪卡 → 答案
-  概念 :: 定义
+  问题 ↔ 回答
   - [ ] 新待办
   `代码块`
 ```

package/{docs/instruction → skills/remnote-bridge/instructions}/connect.md

@@ -18,6 +18,30 @@ daemon 启动后脱离父进程（detached），CLI 进程退出但 daemon 继
 
 ---
 
+## ⚠️ connect 后需要用户配合
+
+`connect` 成功只意味着 daemon 和 webpack-dev-server 已启动，**Plugin 并未自动连接**。用户必须在 RemNote 中完成以下操作：
+
+### 首次使用（RemNote 从未加载过此插件）
+
+1. 打开 RemNote 桌面端或网页端
+2. 点击左侧边栏底部的插件图标（拼图形状）
+3. 点击「开发你的插件」（Develop Your Plugin）
+4. 在输入框中填入 `http://localhost:8080`（即 connect 输出的 webpack-dev-server 地址）
+5. 等待插件加载完成
+
+### 非首次使用（之前已加载过此插件）
+
+只需**刷新 RemNote 页面**即可（浏览器 F5 或 Cmd+R），插件会自动重新连接到已启动的 daemon。
+
+### AI Agent 注意事项
+
+- 执行 `connect` 后，**必须立即告知用户完成上述操作**
+- **禁止在 connect 后直接调用业务命令**——此时 Plugin 尚未连接，命令会报 "Plugin 未连接" 错误
+- 引导用户完成操作后，用 `health` 确认三层就绪（daemon → Plugin → SDK），再执行业务命令
+
+---
+
 ## 用法
 
 ### 人类模式

package/{docs/instruction → skills/remnote-bridge/instructions}/overall.md

@@ -51,7 +51,7 @@ Agent 的核心任务是将用户的自然语言请求翻译为 CLI 命令。以
 | 用户表述 | 操作类型 | CLI 命令 |
 |:---------|:---------|:---------|
 | "改文本"、"改标题"、"改颜色"、"改类型" | 修改 Rem 属性 | `edit-rem` |
-| "创建一个概念定义 (::)" | 修改 type + backText | `edit-rem` |
+| "创建一个概念定义"、"做个 :: 卡" | 新增行（edit-tree 箭头）+ 改 type（edit-rem） | `edit-tree` + `edit-rem` |
 | "新增一个子节点"、"添加笔记" | 结构操作：新增 | `edit-tree` |
 | "删除这个"、"移除" | 结构操作：删除 | `edit-tree` |
 | "移动到…下面" | 结构操作：移动 | `edit-tree` |
@@ -66,42 +66,52 @@ Rem 有两个**独立维度**的类型：
 
 #### type 字段（闪卡语义）
 
-| type 值 | 触发分隔符 | 含义 | UI 表现 |
-|:--------|:----------|:-----|:--------|
-| `concept` | `::` 或 `::>` | 概念定义 | 文字**加粗** |
-| `descriptor` | `;;` 或 `;;>` | 描述/属性 | 文字*斜体* |
-| `default` | 无分隔符 / `>>` / `<<` / `<>` / `>>>` / `{{}}` | 普通 Rem | 正常字重 |
-| `portal` | — | 嵌入引用容器 | 紫色左边框（**只读**，不可通过 setType 设置） |
+| type 值 | 含义 | UI 表现 | CLI 设置方式 |
+|:--------|:-----|:--------|:-------------|
+| `concept` | 概念定义 | 文字**加粗** | `edit-rem` 设 `type: "concept"` |
+| `descriptor` | 描述/属性 | 文字*斜体* | `edit-rem` 设 `type: "descriptor"` |
+| `default` | 普通 Rem | 正常字重 | `edit-rem` 设 `type: "default"` |
+| `portal` | 嵌入引用容器 | 紫色左边框 | **只读**，不可通过 CLI 设置 |
 
 #### isDocument 字段（页面语义）
 
 `isDocument` 与 `type` 完全独立——一个 `concept` 类型的 Rem 可以同时是 Document。
 
-### 2.4 分隔符与闪卡
+### 2.4 闪卡的 CLI 操作方式
 
-用户输入的分隔符决定了 Rem 的 `type`、`backText` 和默认 `practiceDirection`。理解分隔符是理解用户创建闪卡意图的关键。
+闪卡由 `type`、`backText`、`practiceDirection` 三个字段控制。通过 CLI 操作闪卡，修改的是这些**字段**和大纲**箭头**。
 
-| 分隔符 | type | backText | 默认方向 | 用途 |
-|:-------|:-----|:---------|:---------|:-----|
-| （无） | `default` | `null` | — | 无闪卡行为 |
-| `::` | `concept` | 后半部分 | `both` | 概念定义（CDF 框架） |
-| `;;` | `descriptor` | 后半部分 | `forward` | 描述属性（CDF 框架） |
-| `>>` | `default` | 后半部分 | `forward` | 正向问答 |
-| `<<` | `default` | 后半部分 | `backward` | 反向问答 |
-| `<>` | `default` | 后半部分 | `both` | 双向问答 |
-| `>>>` | `default` | `null` | `forward` | 多行答案（子 Rem 为答案） |
-| `::>` | `concept` | `null` | `both` | 概念型多行答案 |
-| `;;>` | `descriptor` | `null` | `forward` | 描述型多行答案 |
-| `{{}}` | `default` | `null` | `forward` | 完形填空（Cloze） |
+**禁止**：在文本中插入分隔符（`::`、`;;`、`>>`、`<<` 等）来创建闪卡。分隔符是 RemNote 编辑器的输入语法，CLI 无法识别。
 
-**重要**：分隔符决定创建时的**默认**方向，用户可以事后独立修改 `practiceDirection`。`practiceDirection` 的取值：`forward`（正向）、`backward`（反向）、`both`（双向）、`none`（不练习）。
+| 闪卡操作 | CLI 方法 |
+|:---------|:---------|
+| 创建概念定义 | `edit-tree` 新增行 `概念 ↔ 定义`，再 `edit-rem` 设 `type: "concept"` |
+| 创建正向问答 | `edit-tree` 新增行 `问题 → 答案` |
+| 创建反向问答 | `edit-tree` 新增行 `问题 ← 答案` |
+| 创建双向问答 | `edit-tree` 新增行 `问题 ↔ 答案` |
+| 创建多行答案 | `edit-tree` 新增行 `问题 ↓`（子行自动成为答案） |
+| 改变闪卡类型/方向 | `edit-rem` 修改 `type`、`backText`、`practiceDirection` |
 
-**CDF（Concept-Descriptor Framework）**：RemNote 推荐的知识结构化方法——`Concept` 是需要理解的概念，`Descriptor` 是概念的属性/描述。典型结构：
+`practiceDirection` 的取值：`forward`（正向）、`backward`（反向）、`both`（双向）、`none`（不练习）。
+
+### 2.5 理解用户意图：编辑器分隔符映射
+
+用户在 RemNote 编辑器中通过分隔符创建闪卡。当用户提到这些分隔符时，理解其意图并映射到上述 CLI 操作：
+
+| 用户说 / 编辑器分隔符 | 对应 type | 对应 practiceDirection |
+|:----------------------|:----------|:----------------------|
+| `::` | concept | both |
+| `;;` | descriptor | forward |
+| `>>` / `<<` / `<>` | default | forward / backward / both |
+| `>>>` / `::>` / `;;>` | default / concept / descriptor | 多行（子 Rem 为答案） |
+| `{{}}` | default | forward（完形填空） |
+
+**CDF（Concept-Descriptor Framework）**：RemNote 推荐的知识结构化方法——`Concept`（type:concept）是需要理解的概念，`Descriptor`（type:descriptor）是概念的属性/描述。在 CLI 大纲中的表现：
 
 ```
-线性回归 :: 最基本的回归模型        ← Concept
-  假设 ;; 因变量与自变量呈线性关系   ← Descriptor
-  损失函数 ;; 均方误差 (MSE)        ← Descriptor
+线性回归 ↔ 最基本的回归模型 <!--id1 type:concept-->
+  假设 → 因变量与自变量呈线性关系 <!--id2 type:descriptor-->
+  损失函数 → 均方误差 (MSE) <!--id3 type:descriptor-->
 ```
 
 ### 2.5 三种链接机制
@@ -170,11 +180,17 @@ RemNote SDK → 知识库
 一次**会话（Session）= 守护进程的生命周期**。
 
 ```
-connect → daemon 启动 → 会话开始
+connect → daemon 启动
+  ↓
+⚠️ 用户在 RemNote 中加载插件（首次填端口，非首次刷新页面）
+  ↓
+health → 确认三层就绪 → 会话可用
   ↕ (业务命令：read-rem, edit-tree, search, ...)
 disconnect → daemon 关闭 → 会话结束，缓存清空
 ```
 
+> **重要**：`connect` 成功只意味着 daemon 已启动，Plugin 并未自动连接。首次使用需用户在 RemNote「开发你的插件」中填入 `http://localhost:8080`；非首次只需刷新 RemNote 页面。必须引导用户完成此步后再用 `health` 确认就绪。
+
 `connect` 启动三个服务：
 
 | 服务 | 默认端口 | 用途 |
@@ -322,18 +338,19 @@ Agent 需要根据用户意图选择正确的读取命令：
 
 ```
 1. connect              ← 启动会话
-2. health               ← 确认系统就绪
-3. read-globe           ← 了解知识库结构（首次探索）
+2. ⚠️ 引导用户在 RemNote 中加载插件（首次填端口，非首次刷新页面）
+3. health               ← 确认系统就绪（daemon → Plugin → SDK 三层全通过）
+4. read-globe           ← 了解知识库结构（首次探索）
    或 read-context      ← 了解用户当前上下文
-4. search "关键词"       ← 定位目标 Rem（中文搜索可能需单字策略，详见 search.md）
-5. read-tree <id>       ← 展开目标区域的子树
-6. read-rem <id>        ← 读取详细属性（编辑前必需）
-7. edit-rem <id> ...    ← 修改 Rem 属性
+5. search "关键词"       ← 定位目标 Rem（中文搜索可能需单字策略，详见 search.md）
+6. read-tree <id>       ← 展开目标区域的子树
+7. read-rem <id>        ← 读取详细属性（编辑前必需）
+8. edit-rem <id> ...    ← 修改 Rem 属性
    或 edit-tree <id> ...← 修改树结构
-8. disconnect           ← 结束会话
+9. disconnect           ← 结束会话
 ```
 
-**注意**：步骤 6 是 `edit-rem` 的强制前置条件，步骤 5 是 `edit-tree` 的强制前置条件。跳过会触发防线 1 错误。
+**注意**：步骤 7 是 `edit-rem` 的强制前置条件，步骤 6 是 `edit-tree` 的强制前置条件。跳过会触发防线 1 错误。步骤 2 是必须的——connect 后不引导用户加载插件就直接调用业务命令，会报"Plugin 未连接"错误。
 
 ---