remnote-bridge 0.1.6 → 0.1.8

package/skills/remnote-bridge/instructions/edit-rem.md

@@ -198,6 +198,10 @@ remnote-bridge edit-rem --json '{"remId":"kLrIOHJLyMd8Y2lyA","oldStr":"\"concept
    │   ├─ 与缓存 JSON 严格比较
    │   └─ 不匹配 → 抛出错误（不更新缓存，迫使 AI re-read）
    │
+   ├─ Portal 检测：type === 'portal'？
+   │   ├─ 是 → 进入 Portal 专用路径（简化 JSON 上执行 str_replace）
+   │   └─ 否 → 继续普通 Rem 路径
+   │
    ├─ 防线 3: str_replace 精确匹配
    │   ├─ countOccurrences(cachedJson, oldStr)
    │   ├─ 0 次 → 抛出"未找到"错误
@@ -338,11 +342,68 @@ edit-rem(remId, oldStr, newStr)
 
 ---
 
+## Portal 编辑专用路径
+
+当 edit-rem 检测到被编辑的 Rem 是 Portal（`type === 'portal'`）时，自动切换到 Portal 专用编辑路径。
+
+### 简化 JSON 作为操作目标
+
+**问题**：缓存中存储完整 51 字段 JSON，但 AI 看到的是 9 字段简化 JSON。oldStr 来自简化输出，在完整 JSON 上匹配不到。
+
+**方案**：Portal 路径在**简化 JSON**（9 字段）上执行 str_replace：
+
+1. 防线 1 + 2：不变（完整 JSON 对比）
+2. **str_replace**：将缓存的完整 JSON 转换为简化 JSON，在简化 JSON 上执行 str_replace
+3. 解析 str_replace 后的简化 JSON，推导变更字段
+4. 调用写入
+
+### Portal 简化 JSON 格式
+
+```json
+{
+  "id": "abc123",
+  "type": "portal",
+  "portalType": "portal",
+  "portalDirectlyIncludedRem": ["remId1", "remId2"],
+  "parent": "parentId",
+  "positionAmongstSiblings": 3,
+  "children": ["remId1", "remId2"],
+  "createdAt": 1709000000000,
+  "updatedAt": 1709000000000
+}
+```
+
+### Portal 可写字段
+
+| 字段 | 写入方式 |
+|:-----|:---------|
+| `portalDirectlyIncludedRem` | diff 数组，新增调 `addToPortal()`，移除调 `removeFromPortal()` |
+| `parent` | 调 `setParent()` |
+| `positionAmongstSiblings` | 调 `setParent(parent, position)` |
+
+### Portal 只读字段
+
+id、type、portalType、children、createdAt、updatedAt — 修改只产生警告。
+
+### Portal 编辑示例
+
+```bash
+# 添加一个引用
+edit-rem abc123 --old-str '"portalDirectlyIncludedRem": ["remId1", "remId2"]' \
+                --new-str '"portalDirectlyIncludedRem": ["remId1", "remId2", "remId3"]'
+
+# 移除一个引用
+edit-rem abc123 --old-str '"portalDirectlyIncludedRem": ["remId1", "remId2"]' \
+                --new-str '"portalDirectlyIncludedRem": ["remId1"]'
+```
+
+---
+
 ## 可编辑字段约束表
 
-RemObject 51 个字段中，20 个可编辑（RW），31 个只读（R + R-F）。
+RemObject 51 个字段中，21 个可编辑（RW），30 个只读（R + R-F）。
 
-以下为 20 个可编辑字段及其写入约束：
+以下为 21 个可编辑字段及其写入约束：
 
 | 字段 | SDK setter | 值类型 | 约束 / 特殊处理 |
 |------|-----------|--------|-----------------|
@@ -366,6 +427,7 @@ RemObject 51 个字段中，20 个可编辑（RW），31 个只读（R + R-F）
 | `tags` | `rem.addTag()` / `rem.removeTag()` | string[] | **Diff 机制**：对比当前 vs 目标，增删差异项 |
 | `sources` | `rem.addSource()` / `rem.removeSource()` | string[] | **Diff 机制**：对比当前 vs 目标，增删差异项 |
 | `positionAmongstSiblings` | `rem.setParent(parent, position)` | number \| null | 与 `parent` 联动（见下方说明） |
+| `portalDirectlyIncludedRem` | `rem.addToPortal()` / `rem.removeFromPortal()` | string[] | **Portal-W Diff 机制**：仅 type=portal 时可修改。对比当前 vs 目标数组，逐项增删 |
 
 ### parent + positionAmongstSiblings 联动
 
@@ -400,13 +462,13 @@ for id in currentSet:
 
 ## 只读字段列表
 
-以下 31 个字段在 str_replace 中被修改时，**只产生警告，不执行写入**：
+以下 30 个字段在 str_replace 中被修改时，**只产生警告，不执行写入**：
 
 ```
 id,
 children,
 isTable,
-portalType, portalDirectlyIncludedRem,
+portalType,
 propertyType,
 aliases,
 remsBeingReferenced, deepRemsBeingReferenced, remsReferencingThis,
@@ -652,4 +714,5 @@ newStr:  "\"text\": [\n    \"光合作用需要\",\n    {\n      \"cId\": \"cloz
 | `invalid JSON` | 替换后的文本不是合法 JSON | 检查 newStr 的引号、逗号、括号完整性 |
 | `Failed to update field` | SDK setter 调用失败 | 检查字段值是否在允许范围内（如 type 不能设为 portal） |
 | `Field '...' is read-only and was ignored` | 修改了只读字段 | 该字段只能读取，不可通过 edit-rem 修改 |
+| `old_str not found in the simplified Portal JSON` | Portal 编辑时 oldStr 在简化 JSON 中不匹配 | 检查 oldStr 是否匹配 9 字段简化 JSON 格式（而非完整 51 字段 JSON） |
 | `守护进程未运行` | daemon 未启动 | 执行 `remnote-bridge connect` |

package/skills/remnote-bridge/instructions/edit-tree.md

@@ -201,16 +201,78 @@ newStr:
 | `` `text` `` | 创建代码块 |
 | `---` | 创建分隔线 |
 
+前缀可组合叠加，解析顺序为 Header → Todo → Code。例如 `## - [ ] text` 创建 H2 + 未完成待办。
+
 #### 新增行的箭头分隔符
 
-| 箭头 | 格式 | 效果 |
-|------|------|------|
-| ` → ` | `问题 → 答案` | 创建 forward 闪卡（单行） |
-| ` ← ` | `问题 ← 答案` | 创建 backward 闪卡（单行） |
-| ` ↔ ` | `问题 ↔ 答案` | 创建 both 闪卡（单行） |
-| ` ↓` | `问题 ↓` | 创建 forward 多行闪卡（子节点为答案） |
-| ` ↑` | `问题 ↑` | 创建 backward 多行闪卡 |
-| ` ↕` | `问题 ↕` | 创建 both 多行闪卡 |
+箭头分隔符分为两类：**中间箭头**（有 backText）和**尾部箭头**（无 backText，子节点为答案）。
+
+**中间箭头**（格式：`问题 {箭头} 答案`）：
+
+| 箭头 | 效果 |
+|------|------|
+| ` → ` | forward 闪卡（单行） |
+| ` ← ` | backward 闪卡（单行） |
+| ` ↔ ` | both 闪卡（单行） |
+| ` ↓ ` | forward 多行闪卡（带 backText） |
+| ` ↑ ` | backward 多行闪卡（带 backText） |
+| ` ↕ ` | both 多行闪卡（带 backText） |
+
+**尾部箭头**（格式：`问题 {箭头}`，子节点为答案）：
+
+| 箭头 | 效果 |
+|------|------|
+| ` ↓` | forward 多行闪卡 |
+| ` ↑` | backward 多行闪卡 |
+| ` ↕` | both 多行闪卡 |
+
+> 已知限制：使用 indexOf 匹配第一个箭头，如果新增行内容本身包含箭头字符（如 `A → B → C`），会被误切割为 text + backText。
+
+#### 新增行的元数据注释
+
+在新增行末尾添加 HTML 注释可设置 Rem 属性（type、isDocument、tag）。注意：这是**不含 remId 的纯元数据注释**，与已有行的行尾标记（`<!--remId metadata-->`）格式不同。
+
+语法：`<!--token1 token2 ...-->`
+
+| token | 效果 |
+|-------|------|
+| `type:concept` | 设置 Rem 类型为 concept |
+| `type:descriptor` | 设置 Rem 类型为 descriptor |
+| `doc` | 设置 isDocument = true |
+| `tag:Name(tagRemId)` | 添加标签（括号内为标签 Rem 的 ID） |
+
+示例：
+
+```
+  新概念节点 <!--type:concept doc-->
+  新描述节点 <!--type:descriptor tag:MyTag(tagId123)-->
+```
+
+多个 token 之间用空格分隔，可任意组合。
+
+#### Portal 新增行
+
+在 newStr 中使用 Portal 专用注释创建新的 Portal：
+
+```
+<!--portal refs:remId1,remId2-->
+<!--portal-->
+```
+
+- `refs:` 后面跟逗号分隔的 Rem ID 列表，指定 Portal 引用的目标 Rem
+- 不带 `refs:` 则创建空 Portal
+- Portal 创建分两步执行：先调用 `create_portal` 创建空 Portal 并设置父节点/位置，再逐个调用 `add_to_portal` 添加引用
+
+示例：
+
+```
+oldStr:
+  子节点 A <!--idA-->
+
+newStr:
+  <!--portal refs:refId1,refId2-->
+  子节点 A <!--idA-->
+```
 
 #### 嵌套新增
 
@@ -226,6 +288,30 @@ newStr:
 
 嵌套新增行的父 ID 通过内部占位标记 `__new_N__` 管理，创建顺序保证从浅到深。
 
+#### ⚠️ 插入位置：必须在兄弟末尾
+
+新行**不能**插在一个有子节点的 Rem 和它的 children 之间，否则 children 会被新行"劫持"，触发 `children_captured` 错误。
+
+```
+❌ 错误：插在父 Rem 和 children 之间
+  水分子 ↓ <!--idA-->
+  新行                    ← children 被解析为新行的子节点！
+    化学式 → H₂O <!--idB role:card-item-->
+
+✅ 正确：插在所有兄弟末尾
+    极性 → ... <!--idZ role:card-item-->
+  新行                    ← 不影响任何已有节点
+```
+
+#### 两步操作：创建新节点并移入已有 children
+
+如果需要"创建一个新父节点，把已有的 children 移到它下面"，必须分两步完成：
+
+1. **第一次 edit-tree**：在兄弟末尾创建新节点
+2. **第二次 edit-tree**：新节点已获得 remId，将已有行的缩进改到新节点下（走正常 move 逻辑）
+
+这是因为新增行没有 remId，diff 算法无法区分"移动到新父节点"和"重新创建"。
+
 ### 删除行
 
 从 newStr 中移除带 remId 的行。**必须同时删除该行的所有可见子行**，否则报 orphan_detected 错误。
@@ -286,6 +372,7 @@ newStr:
 | 删除行但保留子节点 | `orphan_detected` | Cannot delete {id} because it has children that were not removed. | 同时删除所有子行 |
 | 删除/修改省略占位符 | `elided_modified` | Cannot delete or modify elided region directly. | 用更大的 depth/maxSiblings 重新 read-tree 展开 |
 | 缩进跳级 | `indent_skip` | 缩进跳级：行 ... 的缩进级别为 N，但找不到上一级的父节点。 | 检查缩进是否正确（每级 2 空格） |
+| 新行劫持已有子节点 | `children_captured` | New line "..." accidentally captured existing children (...). | 把新行插到兄弟末尾，不要插在父 Rem 和 children 之间 |
 
 ---
 
@@ -304,7 +391,8 @@ diff 算法生成的操作按以下顺序排列并执行（在 `diffTrees` 中
 
 | 操作 | Plugin action | payload |
 |------|---------------|---------|
-| create | `create_rem` + `write_rem_fields` | content, parentId, position + Markdown 属性 |
+| create（普通 Rem） | `create_rem` + `write_rem_fields` | content, parentId, position + Markdown 属性 + 元数据（type/doc/tag） |
+| create（Portal） | `create_portal` + 逐个 `add_to_portal` | parentId, position + portalRefs |
 | delete | `delete_rem` | remId |
 | move | `move_rem` + 条件性 `write_rem_fields` | remId, newParentId, position |
 | reorder | `reorder_children` | parentId, order[] |
@@ -376,12 +464,14 @@ RemNote SDK 存在已知 bug：
    ├─ 对比差异（diffTrees）
    │   ├─ 根节点校验
    │   ├─ 省略行防线
+   │   ├─ 子节点劫持检测（children_captured）
    │   ├─ 内容变更检测
    │   ├─ 折叠删除防线
    │   ├─ 孤儿检测
    │   └─ 生成操作列表（create → move → reorder → delete）
    ├─ 逐项执行操作（forwardToPlugin 调用原子操作）
-   │   ├─ create: create_rem + write_rem_fields
+   │   ├─ create（普通）: create_rem + write_rem_fields（Markdown 属性 + 元数据）
+   │   ├─ create（Portal）: create_portal + 逐个 add_to_portal
    │   ├─ move: move_rem + isCardItem 同步
    │   ├─ reorder: reorder_children
    │   └─ delete: delete_rem

package/skills/remnote-bridge/instructions/health.md

@@ -57,6 +57,18 @@ remnote-bridge health
 remnote-bridge --json health
 ```
 
+### Headless 诊断模式
+
+```bash
+# 截图 + 详细状态 + console 错误 + 排查建议
+remnote-bridge health --diagnose
+
+# 重载 headless Chrome 页面
+remnote-bridge health --reload
+```
+
+`--diagnose` 和 `--reload` 不能同时使用，仅在 headless 模式下可用。
+
 ---
 
 ## JSON 输出
@@ -149,11 +161,65 @@ daemon 运行 → Plugin 连接 → SDK 就绪
 
 ---
 
+## Headless 模式附加输出
+
+### health 基础输出（headless 模式下额外字段）
+
+headless 模式下 `health` 基础输出额外包含 `headless` 对象：
+
+```json
+{
+  "ok": true,
+  "command": "health",
+  "exitCode": 0,
+  "daemon": { "running": true, "pid": 12345, "reachable": true, "uptime": 300 },
+  "plugin": { "connected": true },
+  "sdk": { "ready": true },
+  "timeoutRemaining": 1500,
+  "headless": {
+    "status": "running",
+    "chromeConnected": true,
+    "pageUrl": "http://localhost:8080",
+    "reloadCount": 0,
+    "lastError": null,
+    "recentConsoleErrors": []
+  }
+}
+```
+
+### --diagnose 输出
+
+```json
+{
+  "ok": true,
+  "command": "health",
+  "mode": "diagnose",
+  "headless": { "status": "running", "chromeConnected": true, "pageUrl": "...", "reloadCount": 0, "lastError": null, "recentConsoleErrors": [] },
+  "screenshotPath": "/Users/xxx/.remnote-bridge/headless-screenshot-1234567890.png",
+  "pluginConnected": true,
+  "sdkReady": true
+}
+```
+
+### --reload 输出
+
+```json
+{
+  "ok": true,
+  "command": "health",
+  "mode": "reload"
+}
+```
+
+---
+
 ## 常见问题诊断
 
 | 症状 | 可能原因 | 解决方案 |
 |------|----------|----------|
 | daemon 未运行 | 未执行 connect / 已超时关闭 | 执行 `connect` |
 | daemon 运行但不可达 | WS 端口被占用或配置不匹配 | 检查 `.remnote-bridge.json` 中的 `wsPort` |
-| Plugin 未连接 | RemNote 未打开 / Plugin 未安装 / URL 不匹配 | 打开 RemNote，确认 Plugin 中的 WS URL 设置 |
+| Plugin 未连接（标准模式） | RemNote 未打开 / Plugin 未安装 / URL 不匹配 | 打开 RemNote，确认 Plugin 中的 WS URL 设置 |
+| Plugin 未连接（headless 模式） | Chrome 页面加载异常 | `health --diagnose` 查看截图和状态，`health --reload` 重载页面 |
 | SDK 未就绪 | 知识库加载中 / Plugin 异常 | 等待几秒后重试，或刷新 RemNote 页面 |
+| Chrome 状态 crashed | headless Chrome 崩溃或断开 | `health --reload` 尝试恢复，或 disconnect + connect --headless 重启 |

package/skills/remnote-bridge/instructions/overall.md

@@ -71,7 +71,7 @@ Rem 有两个**独立维度**的类型：
 | `concept` | 概念定义 | 文字**加粗** | `edit-rem` 设 `type: "concept"` |
 | `descriptor` | 描述/属性 | 文字*斜体* | `edit-rem` 设 `type: "descriptor"` |
 | `default` | 普通 Rem | 正常字重 | `edit-rem` 设 `type: "default"` |
-| `portal` | 嵌入引用容器 | 紫色左边框 | **只读**，不可通过 CLI 设置 |
+| `portal` | 嵌入引用容器 | 紫色左边框 | 不可通过 setType 创建（只能通过 createPortal），但引用列表可通过 edit-rem 修改 |
 
 #### isDocument 字段（页面语义）
 
@@ -120,7 +120,17 @@ Rem 有两个**独立维度**的类型：
 |:-----|:---------|:-----|:---------|:-----------|
 | **Reference** | `[[` | RichText 中的引用元素 | 否（只是指针） | read-rem/read-tree 中显示为 `[[文本]]` |
 | **Tag** | `##` | 将 Rem 作为标签附加 | 否（分类标记） | read-rem 的 `tags` 数组 |
-| **Portal** | `((` | 嵌入 Rem 的实时视图 | 是（编辑同步） | read-tree 标记为 `type:portal` |
+| **Portal** | `((` | 嵌入 Rem 的实时视图 | 是（编辑同步） | read-tree 标记为 `type:portal`；引用列表可通过 edit-rem 修改 |
+
+#### Portal 操作速查
+
+| 操作 | 命令 | 方式 |
+|:-----|:-----|:-----|
+| 创建 Portal | `edit-tree` | 新增行 `<!--portal refs:id1,id2-->` |
+| 删除 Portal | `edit-tree` | 从大纲中移除 Portal 行（与删除普通行相同） |
+| 修改引用列表（增删引用的 Rem） | `edit-rem` | str_replace 简化 JSON 中的 `portalDirectlyIncludedRem` 数组 |
+| 移动 Portal（换父节点/位置） | `edit-tree` | 与移动普通行相同 |
+| 读取 Portal | `read-rem` | 自动输出 9 字段简化 JSON |
 
 ### 2.6 Powerup 机制简述
 
@@ -196,7 +206,7 @@ disconnect → daemon 关闭 → 会话结束，缓存清空
 | 服务 | 默认端口 | 用途 |
 |:-----|:---------|:-----|
 | WS Server | 3002 | CLI ↔ daemon ↔ Plugin 通信 |
-| webpack-dev-server | 8080 | 热加载 Plugin 到 RemNote |
+| Plugin 服务 | 8080 | 加载 Plugin 到 RemNote（默认静态服务器，`--dev` 时为 webpack-dev-server） |
 | ConfigServer | 3003 | HTTP 配置界面 |
 
 超时机制：daemon 默认 **30 分钟无活动**自动关闭。每次收到 CLI 请求时重置计时器。
@@ -427,6 +437,9 @@ daemon → CLI 响应：
 | `delete_rem` | —（内部） | deleteRem() | edit-tree 的原子删除 |
 | `move_rem` | —（内部） | moveRem() | edit-tree 的原子移动 |
 | `reorder_children` | —（内部） | reorderChildren() | edit-tree 的原子重排 |
+| `create_portal` | —（内部） | createPortal() | edit-tree Portal 创建 |
+| `add_to_portal` | —（内部） | addToPortal() | Portal 引用管理 |
+| `remove_from_portal` | —（内部） | removeFromPortal() | Portal 引用管理 |
 
 `edit_rem` 和 `edit_tree` 在 daemon handler 中编排完成后，调用 `write_rem_fields`、`create_rem` 等原子操作。
 
@@ -458,7 +471,7 @@ RemObject 是本项目对 RemNote Rem 的标准化表示，包含 51 个字段
 关联：  tags [RW], sources [RW], aliases [R], remsReferencingThis [R]
 位置：  positionAmongstSiblings [RW]
 时间：  createdAt [R], updatedAt [R]
-Portal：portalType [R], portalDirectlyIncludedRem [R]
+Portal：portalType [R], portalDirectlyIncludedRem [Portal-W]
 ```
 
 ### 7.3 RichText 格式
@@ -703,6 +716,7 @@ edit-tree 使用 str_replace 对 Markdown 大纲进行结构编辑。详细文
 | 删除有隐藏子节点的行 | `folded_delete` | 用更大的 depth 重新 read-tree |
 | 删除节点但保留子节点 | `orphan_detected` | 必须同时删除所有子行 |
 | 删除/修改省略占位符 | `elided_modified` | 用更大参数重新 read-tree 展开 |
+| 新行劫持已有子节点 | `children_captured` | 把新行插到兄弟末尾，不要插在父 Rem 和 children 之间 |
 
 ### 10.3 新增行格式
 
@@ -800,6 +814,7 @@ Agent 遇到错误时的诊断和恢复指南：
 | Content modification not allowed | edit-tree 中修改了已有行内容 | 使用 `edit-rem` 修改内容 |
 | orphan_detected | 删除了父节点但保留了子节点 | 同时删除所有子行 |
 | folded_delete | 删除了有隐藏子节点的行 | 用更大 depth 重新 read-tree |
+| children_captured | 新行插在父 Rem 和子节点之间，劫持了已有 children | 把新行插到兄弟末尾 |
 
 ### 数据问题
 

package/skills/remnote-bridge/instructions/read-rem.md

@@ -9,7 +9,7 @@
 `read-rem` 通过 Rem ID 读取一个 Rem 的所有可获取属性，返回标准化的 RemObject。读取结果会被缓存在 daemon 内存中，供后续 `edit-rem` 使用。
 
 核心能力：
-- 返回 51 个字段的完整 Rem 数据（默认 34 个，`--full` 时 51 个）
+- 返回 51 个字段的完整 Rem 数据（默认 34 个，Portal 简化 9 个，`--full` 时 51 个）
 - 支持 `--fields` 指定字段子集
 - 支持 Powerup 噪音过滤（默认过滤）
 - 自动缓存，为 `edit-rem` 建立编辑基础
@@ -159,6 +159,7 @@ remnote-bridge read-rem --json '{"remId":"kLrIOHJLyMd8Y2lyA"}'
    ├─ 字段过滤：
    │   ├─ --full → 返回全部 51 字段
    │   ├─ --fields → 返回指定字段 + id
+   │   ├─ type=portal → Portal 简化模式（返回 9 个关键字段）
    │   └─ 默认 → 排除 R-F 字段（返回 34 字段）
    └─ 附加 _cacheOverridden 元数据（若之前有缓存）
 4. CLI 格式化输出（人类模式 pretty-print / JSON 模式单行）
@@ -237,7 +238,7 @@ RemObject 共 51 个字段，按读写权限分为三类：
 | 字段 | 类型 | 权限 | 说明 |
 |------|------|:----:|------|
 | `portalType` | `PortalType \| null` | R | Portal 子类型。仅 type=portal 时有值 |
-| `portalDirectlyIncludedRem` | `string[]` | R | Portal 直接包含的 Rem ID |
+| `portalDirectlyIncludedRem` | `string[]` | Portal-W | Portal 直接包含的 Rem ID。**Portal 专用可写**：仅 type=portal 时可通过 edit-rem 修改（Diff 机制：addToPortal/removeFromPortal） |
 
 ### 属性类型
 
@@ -377,6 +378,7 @@ text | number | date | checkbox | single_select | multi_select | url | image | t
 | 模式 | 输出字段数 | 说明 |
 |------|:----------:|------|
 | 默认 | 34 | RW + R 字段，覆盖常用场景 |
+| Portal 简化 | 9 | type=portal 时自动使用（id、type、portalType、portalDirectlyIncludedRem、parent、positionAmongstSiblings、children、createdAt、updatedAt）。`--full` / `--fields` 可覆盖 |
 | `--full` | 51 | 全部字段（含 R-F 低频字段） |
 | `--fields` | 自选 + id | 仅返回指定字段（始终包含 id） |
 
@@ -420,6 +422,7 @@ localUpdatedAt, lastPracticed
 | `tags` | `rem.addTag()` / `rem.removeTag()` | **Diff 机制**：对比当前 vs 目标，增删差异项。必须列出完整目标数组，缺少的会被删除 |
 | `sources` | `rem.addSource()` / `rem.removeSource()` | **Diff 机制**：同 tags |
 | `positionAmongstSiblings` | `rem.setParent(parent, position)` | 与 `parent` 联动（见下方说明） |
+| `portalDirectlyIncludedRem` | `rem.addToPortal()` / `rem.removeFromPortal()` | string[] | **Portal-W Diff 机制**：仅 type=portal 时可修改。对比当前 vs 目标数组，逐项增删。调用方向：在被引用 Rem 上调用，参数是 Portal Rem |
 
 ### parent + positionAmongstSiblings 联动
 

package/skills/remnote-bridge/instructions/setup.md

@@ -0,0 +1,130 @@
+# setup
+
+> 启动 Chrome 浏览器让用户登录 RemNote，保存登录凭证到本地 profile。这是 headless 模式（`connect --headless`）的前置步骤。
+
+---
+
+## 功能
+
+`setup` 启动一个有界面的 Chrome 窗口（使用独立 profile 目录 `~/.remnote-bridge/chrome-profile`），打开 RemNote 登录页面。用户在浏览器中完成登录后关闭 Chrome，命令写入 `.setup-done` 标记并返回。
+
+后续 `connect --headless` 使用相同 profile 目录，复用已保存的登录凭证，实现免登录的 headless 连接。
+
+---
+
+## 前置条件
+
+- 需要**桌面环境（GUI）**，无 GUI 环境会报错
+- 需要系统安装 Chrome/Chromium
+
+---
+
+## 用法
+
+### 人类模式
+
+```bash
+remnote-bridge setup
+```
+
+输出示例：
+
+```
+正在启动 Chrome...
+请在浏览器中登录 RemNote，完成后关闭浏览器窗口。
+setup 完成！
+  profile 目录: /Users/xxx/.remnote-bridge/chrome-profile
+现在可以使用 `remnote-bridge connect --headless` 启动无头连接。
+```
+
+### JSON 模式
+
+```bash
+remnote-bridge --json setup
+```
+
+---
+
+## JSON 输出
+
+### 首次 setup
+
+```json
+{
+  "ok": true,
+  "command": "setup",
+  "profileDir": "/Users/xxx/.remnote-bridge/chrome-profile",
+  "alreadyDone": false
+}
+```
+
+### 已完成 setup
+
+```json
+{
+  "ok": true,
+  "command": "setup",
+  "profileDir": "/Users/xxx/.remnote-bridge/chrome-profile",
+  "alreadyDone": true
+}
+```
+
+### 失败
+
+```json
+{
+  "ok": false,
+  "command": "setup",
+  "error": "未检测到桌面环境（无 DISPLAY/WAYLAND_DISPLAY），setup 需要 GUI 才能登录"
+}
+```
+
+---
+
+## AI Agent 使用流程
+
+setup 会弹出 Chrome 窗口，用户需要完成两件事：登录 RemNote + 配置 dev plugin。
+
+### 交互步骤
+
+1. 调用 `setup`
+2. **立即告知用户**：
+   > 已打开 Chrome 浏览器。请完成以下操作：
+   > 1. 登录 RemNote
+   > 2. 在 RemNote 中配置开发插件：点击左下角插件图标 → 开发你的插件 → 输入 `http://localhost:8080`
+   > 3. 完成后彻底退出 Chrome（macOS 请按 Cmd+Q，仅关窗口不够）
+3. 等待 `setup` 命令返回（阻塞式，超时 600 秒）
+4. 收到成功 → 继续执行 `connect --headless`
+
+### setup 之后
+
+`setup` 只需执行一次。登录凭证和 plugin 配置都已保存，之后每次只需 `connect --headless` 即可自动连接，无需用户操作。
+
+如果后续 headless 模式下 Plugin 始终不连接，可能是 RemNote 登录 session 过期，需重新 setup（删除 `~/.remnote-bridge/chrome-profile/.setup-done` 后重新执行）。
+
+---
+
+## 幂等性
+
+已完成 setup 后重复调用返回 `ok: true, alreadyDone: true`，不会再次打开 Chrome。
+
+如需重新登录（切换账号），删除 `~/.remnote-bridge/chrome-profile/.setup-done` 文件后重新执行。
+
+---
+
+## 退出码
+
+| 退出码 | 含义 |
+|--------|------|
+| 0 | 成功（首次完成或已完成） |
+| 1 | 失败（无 GUI、无 Chrome、超时等） |
+
+---
+
+## 产生的文件
+
+| 文件 | 位置 | 说明 |
+|------|------|------|
+| Chrome profile | `~/.remnote-bridge/chrome-profile/` | Chrome 用户数据（含登录凭证） |
+| `.setup-done` | `~/.remnote-bridge/chrome-profile/.setup-done` | setup 完成标记（JSON，含时间戳） |
+