remnote-bridge 0.1.0

package/skill/SKILL.md

@@ -0,0 +1,428 @@
+---
+name: remnote-bridge
+description: "RemNote 知识库操作指南。通过 remnote-bridge 命令行工具读取、编辑、搜索 RemNote 知识库中的内容。当用户需要操作 RemNote 知识库时使用此 skill——包括读取笔记、编辑内容、搜索、浏览知识库结构、创建闪卡、修改文档属性等。触发关键词包括：RemNote、知识库、笔记、Rem、闪卡、文档、read-rem、edit-rem、read-tree、edit-tree、search、read-globe、read-context。即使用户没有明确提到 CLI 命令，只要意图是操作 RemNote 中的数据，都应触发此 skill。"
+---
+
+# RemNote CLI 操作指南
+
+本 skill 指导 AI Agent 通过 remnote-bridge 操作 RemNote 知识库。
+
+**详细命令文档**位于 `docs/instruction/` 目录下，执行具体命令前务必先读取对应文件：
+
+| 命令 | 文档路径 |
+|:-----|:---------|
+| 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` |
+
+---
+
+## 1. 核心概念
+
+### 一切皆 Rem
+
+RemNote 中所有内容的基本单元都是 **Rem**。文档、文件夹、闪卡、标签——本质上都是 Rem 的不同形态。
+
+| 用户说的 | 实际上是 |
+|:---------|:---------|
+| 笔记 / 条目 | Rem |
+| 文档 / 页面 | Rem（`isDocument=true`） |
+| 文件夹 | Rem（Document 且子节点全是 Document） |
+| 闪卡 / 卡片 | Card——由 RemNote 根据 Rem 属性自动生成，**不可直接操控** |
+
+### Rem 类型系统
+
+两个独立维度：
+
+- **type**（闪卡语义）：`concept`（`::`，加粗）、`descriptor`（`;;`，斜体）、`default`（普通）、`portal`（只读）
+- **isDocument**（页面语义）：与 type 完全独立
+
+### CDF 框架（Concept-Descriptor Framework）
+
+RemNote 推荐的知识结构化方法：
+
+```
+线性回归 :: 最基本的回归模型        ← Concept（type:concept，加粗）
+  假设 ;; 因变量与自变量呈线性关系   ← Descriptor（type:descriptor，斜体）
+  损失函数 ;; 均方误差 (MSE)        ← Descriptor
+```
+
+### 分隔符与闪卡方向
+
+| 分隔符 | type | 默认方向 | 用途 |
+|:-------|:-----|:---------|:-----|
+| `::` | concept | both | 概念定义 |
+| `;;` | descriptor | forward | 描述属性 |
+| `>>` | default | forward | 正向问答 |
+| `<<` | default | backward | 反向问答 |
+| `<>` | default | both | 双向问答 |
+| `>>>` | default | forward | 多行答案 |
+| `::>` | concept | both | 概念型多行答案 |
+| `;;>` | descriptor | forward | 描述型多行答案 |
+| `{{}}` | default | forward | 完形填空 |
+
+### 三种链接机制
+
+| 机制 | 用户操作 | 本质 | CLI 可见性 |
+|:-----|:---------|:-----|:-----------|
+| **Reference** | `[[` | RichText 中的 `{"i":"q","_id":"remId"}` | read-rem 的 text 数组 |
+| **Tag** | `##` | Rem 的 tags 数组 | read-rem 的 `tags` 字段 |
+| **Portal** | `((` | 嵌入实时视图（**编辑同步**） | read-tree 标记 `type:portal refs:id1,id2` |
+
+Portal 的编辑同步意味着修改一处会影响另一处。Portal 引用的 Rem 不会被 read-tree 自动展开，需要对 refs 中的 ID 单独 read-tree。
+
+### RichText 格式
+
+`text` 和 `backText` 字段是 JSON 数组，元素为纯字符串或格式化对象：
+
+```json
+["纯文本", {"i":"m","b":true,"text":"粗体"}, {"i":"q","_id":"remId"}]
+```
+
+| `i` 值 | 类型 | 核心字段 |
+|:-------|:-----|:---------|
+| 纯 string | 纯文本 | — |
+| `"m"` | 带格式文本 | `text` + `b`/`l`/`u`/`h`/`tc`/`code`/`cId`/`iUrl` |
+| `"q"` | Rem 引用 | `_id` |
+| `"i"` | 图片 | `url`, `width`, `height` |
+| `"x"` | LaTeX | `text` |
+| `"a"` | 音频 | `url` |
+
+**序列化确定性**：RichText 对象内部按 **key 字母序排列**（如 `{"b":true,"i":"m","text":"粗体"}`），确保 JSON 始终一致。构造 edit-rem 的 oldStr 时必须保持相同的 key 顺序，否则匹配失败。
+
+### Powerup 机制与噪音过滤
+
+RemNote 格式设置（fontSize、highlightColor 等）底层通过 Powerup 机制实现，会注入隐藏 Tag 和子 Rem。默认自动过滤（`includePowerup=false`）。read-tree 支持 `--includePowerup` 恢复完整数据，read-globe 和 read-context 硬编码过滤无选项。
+
+---
+
+## 2. 命令决策
+
+### 读取：用户想了解什么？
+
+```
+知识库整体结构（"有哪些文档"）       → read-globe
+用户当前在看什么（"当前页面"）        → read-context
+某个 Rem 的子树（"展开这个主题"）     → read-tree <remId>
+某个 Rem 的详细属性（"详细信息"）     → read-rem <remId>
+按关键词搜索（"搜索 X"）            → search <query>（中文搜索有限制，见下方说明）
+```
+
+#### read-globe vs read-context vs read-tree
+
+| 场景 | 命令 | 特点 |
+|:-----|:-----|:-----|
+| 知识库有什么 | `read-globe` | 仅 Document 层级，**无缓存**，最小序列化（无 backText/箭头） |
+| 我在编辑什么 | `read-context --mode focus` | 鱼眼视图（焦点 depth=3，siblings depth=1，叔伯 depth=0），**无缓存** |
+| 当前页面内容 | `read-context --mode page` | 均匀展开，**无缓存** |
+| 展开某主题细节 | `read-tree <id>` | 完整子树，**有缓存**供 edit-tree |
+
+**重要**：read-globe、read-context、search 都**不写入缓存**，不能替代 read-tree/read-rem 作为 edit 的前置条件。read-context 需要用户在 RemNote 中有焦点（focus 模式）或打开页面（page 模式）。
+
+### 修改：用户想改什么？
+
+```
+Rem 的属性（文本、类型、格式、标签）  → edit-rem   （前置：先 read-rem）
+树的结构（新增、删除、移动、重排）    → edit-tree  （前置：先 read-tree）
+某行的文字内容                       → edit-rem   （不是 edit-tree！）
+```
+
+**关键区分**：`edit-rem` 修改 Rem 的**属性**，`edit-tree` 修改 Rem 之间的**结构关系**。`edit-tree` **禁止修改行内容**。
+
+---
+
+## 3. 标准工作流
+
+```
+1. connect              -- 启动会话（幂等，重复调用安全）
+2. health               -- 确认三层就绪：daemon → Plugin → SDK（链式依赖）
+3. 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           -- 结束会话（缓存全部清空，幂等）
+```
+
+**超时**：daemon 默认 30 分钟无 CLI 交互自动关闭，每次请求重置计时器。长时间操作间可用 health 保活。
+
+---
+
+## 4. 双模式 I/O（`--json`）
+
+Agent 应始终使用 JSON 模式调用命令。
+
+```bash
+# 正确：位置参数 = JSON 字符串
+remnote-bridge read-rem --json '{"remId":"kLrIOHJLyMd8Y2lyA","fields":["text","type"]}'
+remnote-bridge search --json '{"query":"机器学习","numResults":10}'
+
+# 错误：禁止混用裸 remId + --json
+remnote-bridge read-rem kLrIOHJLyMd8Y2lyA --json   # 会失败！
+```
+
+注意：search 的 JSON 参数名是 `numResults`（不是 `limit`）。
+
+### 中文搜索限制（重要）
+
+search 调用 RemNote SDK 官方搜索方法，其分词基于空格分割。**中文、日文、韩文等无空格分词的语言搜索效果差**——SDK 将多字词拆为单字符 token 匹配，导致返回 0 结果或不相关结果。RemNote 本地桌面版已优化此问题，Web 版未优化。
+
+**应对策略**：
+1. 先用完整关键词搜索
+2. 若返回 0 结果且关键词为中文等非空格语言：用**单个最具区分度的字**重试（如搜 "键" 而非 "共价键"）
+3. 若仍无结果：改用 `read-globe` → `read-tree` 浏览定位
+4. 搜索持续不佳时，询问用户："您使用的是 RemNote Web 版还是本地桌面版？Web 版中文搜索存在已知限制。"
+
+### JSON 输出结构
+
+```jsonc
+{ "ok": true,  "command": "read-rem", ... }   // 成功
+{ "ok": false, "command": "read-rem", "error": "..." }  // 失败
+```
+
+---
+
+## 5. 安全机制：三道防线
+
+### 防线 1：缓存存在性
+
+必须先 read 再 edit。未缓存的 Rem 不允许编辑。
+
+### 防线 2：乐观并发检测
+
+edit 时从 SDK 重新读取最新数据，与缓存严格比较。被外部修改则拒绝编辑且**不更新缓存**——迫使 Agent 重新 read。
+
+### 防线 3：str_replace 精确匹配
+
+`oldStr` 必须在目标文本中恰好匹配 1 次。
+
+### 缓存更新规则
+
+| 场景 | 缓存行为 | Agent 操作 |
+|:-----|:---------|:-----------|
+| 写入成功 | 从 SDK 重新读取 → 更新缓存 | 可继续编辑 |
+| 防线 2 拒绝 / 部分写入失败 | **不更新缓存** | 必须重新 read |
+| 防线 3 拒绝 / JSON 语法错误 | 缓存保持不变 | 调整 oldStr/newStr 后**直接重试** |
+| 操作执行中异常（edit-tree） | 已执行的操作保留（**无回滚**），不更新缓存 | 必须重新 read-tree |
+
+---
+
+## 6. Markdown 大纲格式
+
+read-tree / read-globe / read-context 输出 Markdown 大纲，edit-tree 基于此大纲编辑。
+
+### 缩进规则
+
+**每级缩进 2 个空格**。根节点 0 空格，直接子节点 2 空格，孙节点 4 空格。缩进不可跳级（如从 0 直跳 4 空格会报 `indent_skip` 错误）。
+
+### 行结构
+
+```
+{缩进}{前缀}{内容}{箭头}{backText} <!-- {remId} {元数据} -->
+```
+
+### 前缀
+
+| 前缀 | 含义 |
+|:-----|:-----|
+| `# ` / `## ` / `### ` | H1/H2/H3 标题 |
+| `- [ ] ` / `- [x] ` | 未完成/已完成待办 |
+| `` `...` `` | 代码块 |
+| `---` | 分隔线 |
+
+### 箭头（编码 practiceDirection）
+
+| 箭头 | 方向 | 格式 |
+|:-----|:-----|:-----|
+| ` → ` | forward | `text → backText` |
+| ` ← ` | backward | `text ← backText` |
+| ` ↔ ` | both | `text ↔ backText` |
+| ` ↓ ` / ` ↓` | forward 多行 | 有 backText: `text ↓ backText`；无: `text ↓` |
+| ` ↑ ` / ` ↑` | backward 多行 | 同上 |
+| ` ↕ ` / ` ↕` | both 多行 | 同上 |
+
+### 元数据标记
+
+| 标记 | 含义 |
+|:-----|:-----|
+| `type:concept` / `type:descriptor` / `type:portal` | Rem 类型 |
+| `doc` | isDocument = true |
+| `top` | 知识库顶层 Rem |
+| `children:N` | 折叠的子节点数（深度超限） |
+| `role:card-item` | 多行闪卡答案行 |
+| `tag:Name(id)` | 标签 |
+| `refs:id1,id2` | Portal 引用 |
+
+### 省略占位符（两种类型）
+
+```
+<!--...elided 3 siblings (parent:id range:2-4 total:5)-->     精确省略：maxSiblings 超限，调大 maxSiblings
+<!--...elided >=10 nodes (parent:id range:5-14 total:20)-->   非精确省略：maxNodes 耗尽，调大 maxNodes
+```
+
+精确省略保留前 70% + 后 30%，中间插入省略行。**省略占位符不可删除或修改**，否则报 `elided_modified` 错误。
+
+---
+
+## 7. edit-tree 结构编辑
+
+### 支持的操作
+
+| 操作 | 方式 | 执行顺序 |
+|:-----|:-----|:---------|
+| 新增 | 在 newStr 中添加无 remId 的新行 | 1（从浅到深） |
+| 移动 | 改变行的缩进/位置 | 2 |
+| 重排 | 调换同级行顺序 | 3 |
+| 删除 | 从 newStr 中移除带 remId 的行 | 4（从深到浅） |
+
+一次 edit-tree 可组合多种操作。
+
+### 禁止的操作
+
+| 操作 | 错误类型 | 替代方案 |
+|:-----|:---------|:---------|
+| 修改已有行内容 | `content_modified` | 使用 `edit-rem` |
+| 删除/修改/移动根节点 | `root_modified` | — |
+| 删除有隐藏子节点的行 | `folded_delete` | 用更大 depth 重新 read-tree |
+| 删除行但保留子节点 | `orphan_detected` | 必须同时删除所有子行 |
+| 删除/修改省略占位符 | `elided_modified` | 用更大参数重新 read-tree |
+| 缩进跳级 | `indent_skip` | 每级 2 空格，不可跳级 |
+
+### 新增行格式
+
+新增行可用 Markdown 前缀和箭头分隔符：
+
+```markdown
+  # 新标题
+  新闪卡 → 答案
+  概念 :: 定义
+  - [ ] 新待办
+  `代码块`
+```
+
+### 嵌套新增（一次创建父+子结构）
+
+新增行下面可以再嵌套新增行，缩进表示父子关系：
+
+```
+newStr:
+  父节点 ↓
+    答案行 1
+    答案行 2
+  子节点 A <!--idA-->
+```
+
+创建顺序从浅到深，嵌套的子行会自动成为新创建父节点的 children。
+
+### practiceDirection 保护
+
+SDK bug 自动修复：移动行进入多行闪卡父节点时自动设 `isCardItem=true` 并修正 practiceDirection；移出时自动清除。Rem 自身的合法 practiceDirection 会被保留。
+
+### str_replace 构造示例
+
+```bash
+# 在 idA 前插入新行
+--old-str '  子节点 A <!--idA-->'
+--new-str '  新增行\n  子节点 A <!--idA-->'
+
+# 删除叶子节点（注意尾部换行）
+--old-str '    叶子节点 <!--leaf-->\n'
+--new-str ''
+
+# 调换两个兄弟顺序
+--old-str '  节点 A <!--idA-->\n  节点 B <!--idB-->'
+--new-str '  节点 B <!--idB-->\n  节点 A <!--idA-->'
+```
+
+---
+
+## 8. edit-rem str_replace 要点
+
+操作对象是 `JSON.stringify(remObject, null, 2)` 的文本（缩进 2 空格的 JSON）。
+
+### 使用技巧
+
+1. **包含字段名**避免模糊匹配：`"\"type\": \"concept\""` 而非 `"concept"`
+2. 替换后必须是合法 JSON
+3. 修改 RichText 时注意 key 字母序：
+
+```
+oldStr: "\"text\": [\n    \"Hello\"\n  ]"
+newStr: "\"text\": [\n    \"World\"\n  ]"
+```
+
+### 20 个可编辑字段
+
+```
+text, backText, type, isDocument, parent,
+fontSize, highlightColor,
+isTodo, todoStatus, isCode, isQuote, isListItem, isCardItem, isSlot, isProperty,
+enablePractice, practiceDirection,
+tags, sources, positionAmongstSiblings
+```
+
+### 特殊字段处理规则
+
+| 字段 | 特殊行为 |
+|:-----|:---------|
+| `backText` | `null` → 调用 `setBackText([])`（清除背面）；裸字符串自动包装为 `[string]` |
+| `highlightColor` | `null` → 调用 `removePowerup('h')`（SDK 不接受 null） |
+| `fontSize` | `null` → 调用 `setFontSize(undefined)`（恢复普通大小） |
+| `todoStatus` | 依赖 `isTodo=true` 才生效；`null` 被跳过（清除 todo 应设 `isTodo=false`） |
+| `type` | 不可设为 `portal`（只能通过 SDK `createPortal()` 创建） |
+| `parent` + `positionAmongstSiblings` | 共享同一 SDK 调用 `setParent(parentId, position)`，**应在同一次 str_replace 中同时修改** |
+| `tags` / `sources` | **Diff 机制**：对比当前 vs 目标数组，逐项 add/remove。必须列出完整目标数组，缺少的会被删除 |
+
+### 常用只读字段（修改只产生警告，不生效）
+
+```
+id, children, createdAt, updatedAt, remsReferencingThis, remsBeingReferenced,
+aliases, descendants, siblingRem, isTable, portalType, propertyType
+```
+
+### read-rem 输出模式
+
+| 模式 | 字段数 | 用法 |
+|:-----|:-------|:-----|
+| 默认 | 34（RW + R） | 常用场景 |
+| `--full` | 51（含低频 R-F） | 需要 Powerup 标识、时间戳等 |
+| `--fields` | 自选 + id | 精确获取特定字段 |
+
+缓存始终存储完整 51 字段 RemObject，字段过滤仅影响输出。
+
+---
+
+## 9. 错误诊断速查
+
+| 错误 | 原因 | 恢复 |
+|:-----|:-----|:-----|
+| 守护进程未运行 | 未 connect 或已超时 | `connect` |
+| Plugin 未连接 | RemNote 未打开 | 打开 RemNote（health 三层：daemon→Plugin→SDK 链式依赖） |
+| has not been read yet | 未先 read | 执行对应 read 命令（search 结果不算 read！） |
+| has been modified since last read | 被外部修改 | 重新 read（必须，不可直接重试） |
+| old_str not found | oldStr 不精确 | 检查引号、空格、换行、RichText key 顺序 |
+| old_str matches N locations | oldStr 不够具体 | 扩大 oldStr 范围，包含更多上下文 |
+| invalid JSON | newStr 破坏了 JSON 结构 | 检查引号、逗号、括号完整性（可直接重试） |
+| content_modified | edit-tree 中改了行内容 | 用 edit-rem |
+| orphan_detected | 删了父但留了子 | 同时删除所有子行 |
+| folded_delete | 删了有隐藏子节点的行 | 用更大 depth 重新 read-tree |
+| elided_modified | 删/改了省略占位符 | 用更大 depth/maxSiblings 重新 read-tree |
+| indent_skip | 缩进跳级（如 0→4 空格） | 每级 2 空格，不可跳级 |
+| Rem not found | remId 无效或已删除 | 用 search 重新定位 |
+
+---
+
+## 10. 配置
+
+配置文件：`.remnote-bridge.json`（项目根目录）
+
+关键默认值：WS 端口 3002、dev-server 8080、config 3003、超时 30 分钟、maxNodes 200、maxSiblings 20、readTreeDepth 3、readGlobeDepth -1（无限）、缓存上限 200 条。