remnote-bridge 0.1.5 → 0.1.7

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

@@ -45,10 +45,36 @@ newStr:
 | \\\` → \\\` | \\\`问题 → 答案\\\` | 创建 forward 闪卡（单行） |
 | \\\` ← \\\` | \\\`问题 ← 答案\\\` | 创建 backward 闪卡（单行） |
 | \\\` ↔ \\\` | \\\`问题 ↔ 答案\\\` | 创建 both 闪卡（单行） |
+| \\\` ↓ \\\` | \\\`问题 ↓ 答案\\\` | 创建 forward 多行闪卡（有 backText） |
+| \\\` ↑ \\\` | \\\`问题 ↑ 答案\\\` | 创建 backward 多行闪卡（有 backText） |
+| \\\` ↕ \\\` | \\\`问题 ↕ 答案\\\` | 创建 both 多行闪卡（有 backText） |
 | \\\` ↓\\\` | \\\`问题 ↓\\\` | 创建 forward 多行闪卡（子节点为答案） |
 | \\\` ↑\\\` | \\\`问题 ↑\\\` | 创建 backward 多行闪卡 |
 | \\\` ↕\\\` | \\\`问题 ↕\\\` | 创建 both 多行闪卡 |
 
+#### 新增行的元数据注释
+
+新增行可以在行尾添加 HTML 注释来指定元数据属性（注意：没有 remId，以 \\\`type:\\\`/\\\`doc\\\`/\\\`tag:\\\` 开头）：
+
+\\\`\\\`\\\`
+新概念 <!--type:concept-->
+新描述 <!--type:descriptor-->
+新文档 <!--doc-->
+带标签 <!--tag:TagName(tagRemId)-->
+组合使用 <!--type:concept doc tag:Physics(abc123)-->
+\\\`\\\`\\\`
+
+| 标记 | 效果 |
+|------|------|
+| \\\`type:concept\\\` | 设置 Rem 类型为 Concept |
+| \\\`type:descriptor\\\` | 设置 Rem 类型为 Descriptor |
+| \\\`doc\\\` | 将 Rem 标记为 Document |
+| \\\`tag:Name(remId)\\\` | 添加指定 remId 的 Tag（可多个） |
+
+与已有行行尾标记的区别：
+- 已有行：\\\`文本 <!--remId type:concept doc-->\\\`（以 remId 开头）
+- 新增行：\\\`文本 <!--type:concept doc-->\\\`（无 remId，直接以属性开头）
+
 #### 嵌套新增
 
 新增行下面可以再嵌套新增行，通过缩进表示父子关系：
@@ -63,6 +89,10 @@ newStr:
 
 嵌套新增行的父 ID 通过内部占位标记管理，创建顺序保证从浅到深。
 
+#### ⚠️ 插入位置
+
+新行**不能**插在一个有子节点的 Rem 和它的 children 之间，否则 children 会被新行"劫持"，触发 \\\`children_captured\\\` 错误。新行必须插在目标层级所有兄弟的**末尾**。
+
 ### 2. 删除行
 
 从 newStr 中移除带 remId 的行。**必须同时删除该行的所有可见子行**，否则报 orphan_detected 错误。
@@ -123,6 +153,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 之间 |
 
 ---
 
@@ -194,4 +225,33 @@ newStr:
 \\\`\\\`\\\`
 
 结果：创建一个多行 forward 闪卡，问题为"什么是线性回归？"，两个子行自动成为答案（isCardItem=true）。
+
+## 示例 4：创建 Portal
+
+Portal 新增行使用 \\\`<!--portal refs:id1,id2-->\\\` 语法（无文本内容，纯参数行）：
+
+\\\`\\\`\\\`
+oldStr:
+  子节点 A <!--idA-->
+
+newStr:
+  <!--portal refs:refId1,refId2-->
+  子节点 A <!--idA-->
+\\\`\\\`\\\`
+
+结果：创建一个 Portal，引用 refId1 和 refId2 两个 Rem。
+
+空 Portal（无引用）：
+
+\\\`\\\`\\\`
+  <!--portal-->
+\\\`\\\`\\\`
+
+Portal 新增行与已有 Portal 行的区别：
+- 已有 Portal：\\\`<!--remId type:portal refs:id1,id2-->\\\`（有 remId）
+- 新增 Portal：\\\`<!--portal refs:id1,id2-->\\\`（无 remId，以 \\\`portal\\\` 关键字开头）
+
+删除 Portal 与删除普通行相同——从 newStr 中移除该 Portal 行即可。
+
+**注意**：修改已有 Portal 的引用列表（增删引用的 Rem）请使用 \\\`edit_rem\\\`，通过 str_replace 修改简化 JSON 中的 \\\`portalDirectlyIncludedRem\\\` 数组。
 `;

package/dist/mcp/resources/error-reference.js

@@ -1,7 +1,7 @@
 export const ERROR_REFERENCE_CONTENT = `
 # Error Reference
 
-所有 CLI 命令错误的完整参考，按类别分组。
+所有工具错误的完整参考，按类别分组。
 
 ---
 
@@ -54,6 +54,8 @@ export const ERROR_REFERENCE_CONTENT = `
 | Failed to update field '{field}': ... | SDK setter 调用失败 | 检查字段值是否在允许范围内 |
 | Field '{fieldName}' is read-only and was ignored | 修改了只读字段 | **警告**（非阻断），该字段不可修改 |
 | Setting 'todoStatus' without 'isTodo: true' may have no effect | todoStatus 非 null 但 isTodo=false | 先将 isTodo 设为 true |
+| old_str not found in the simplified Portal JSON of rem {remId} | Portal 编辑时 oldStr 在 9 字段简化 JSON 中不匹配 | 检查 oldStr 是否匹配 Portal 简化 JSON 格式（9 字段：id、type、portalType、portalDirectlyIncludedRem、parent、positionAmongstSiblings、children、createdAt、updatedAt） |
+| old_str matches {N} locations in Portal rem {remId}. Make old_str more specific to match exactly once. | Portal 编辑时 oldStr 在简化 JSON 中匹配多处 | 扩大 oldStr 范围以唯一定位 |
 
 ---
 
@@ -67,6 +69,7 @@ export const ERROR_REFERENCE_CONTENT = `
 | Cannot delete {id} because it has children that were not removed. | \\\`orphan_detected\\\` | 删除了父行但保留了子行 | 必须同时删除所有子行 |
 | Cannot delete or modify elided region directly. | \\\`elided_modified\\\` | 删除或修改了省略占位符 | 用更大的 depth/maxSiblings 重新 \\\`read_tree\\\` 展开 |
 | 缩进跳级：行 ... 的缩进级别为 N，但找不到上一级的父节点。 | \\\`indent_skip\\\` | 新增行的缩进不正确 | 检查缩进（每级 2 空格） |
+| New line "..." accidentally captured existing children (...). Insert the new line after the last child, not between a parent Rem and its children. | \\\`children_captured\\\` | 新增行插在了一个有子节点的 Rem 和它的 children 之间，劫持了已有子节点 | 把新行插到目标层级所有兄弟的**末尾**，不要插在父 Rem 紧后面 |
 
 ---
 
@@ -106,6 +109,7 @@ export const ERROR_REFERENCE_CONTENT = `
 │
 ├─ "old_str not found"
 │   ├─ 检查空格、换行、引号是否精确匹配
+│   ├─ Portal Rem？检查是否匹配 9 字段简化 JSON（非完整 JSON）
 │   └─ 重新 read 确认当前内容
 │
 ├─ "old_str matches N locations"
@@ -117,6 +121,9 @@ export const ERROR_REFERENCE_CONTENT = `
 ├─ "Content modification not allowed"
 │   └─ 改用 edit_rem 修改内容
 │
+├─ "children_captured"
+│   └─ 把新行插到所有兄弟末尾，不要插在父 Rem 和 children 之间
+│
 ├─ "orphan_detected"
 │   └─ 同时删除父行的所有子行
 │

package/dist/mcp/resources/outline-format.js

@@ -86,7 +86,35 @@ read_tree / read_globe / read_context 的输出核心是 Markdown 大纲文本
 
 ---
 
-## 6. 完整示例
+## 6. edit-tree 新增行的特殊格式
+
+### 新增 Portal 行
+
+在 edit-tree 的 newStr 中，用以下格式新增 Portal：
+
+\\\`\\\`\\\`
+<!--portal refs:id1,id2-->      新增 Portal 并引用 id1、id2
+<!--portal-->                   新增空 Portal（无引用）
+\\\`\\\`\\\`
+
+与已有 Portal 行（\\\`<!--remId type:portal refs:id1,id2-->\\\`）不同，新增 Portal 行没有 remId，以 \\\`<!--portal\\\` 开头。
+
+### 新增行的 metadata-only 注释
+
+新增行（无 remId）可在行尾用 HTML 注释指定类型、文档属性和标签，格式为仅包含元数据标记（不含 remId）：
+
+\\\`\\\`\\\`
+新概念 <!--type:concept-->
+新文档页 <!--type:concept doc-->
+带标签 <!--type:descriptor tag:数学(tag01)-->
+多标记组合 <!--type:concept doc tag:基础(tag02) tag:数学(tag01)-->
+\\\`\\\`\\\`
+
+支持的标记：\\\`type:concept\\\`、\\\`type:descriptor\\\`、\\\`doc\\\`、\\\`tag:Name(id)\\\`（可多个）。
+
+---
+
+## 7. 完整示例
 
 \\\`\\\`\\\`markdown
 # 数据结构 <!--kLr type:concept doc top-->

package/dist/mcp/resources/rem-object-fields.js

@@ -10,6 +10,7 @@ RemObject 是本项目对 RemNote Rem 的标准化表示，包含 51 个字段
 | 标记 | 含义 | 数量 | 输出条件 |
 |:-----|:-----|:-----|:---------|
 | RW | 可读可写 | 20 | 默认输出 |
+| Portal-W | Portal 专用可写 | 1 | 默认输出（Portal 简化模式） |
 | R | 只读 | 14 | 默认输出 |
 | R-F | 只读低频 | 17 | 仅 \\\`--full\\\` 输出 |
 
@@ -78,7 +79,7 @@ RemObject 是本项目对 RemNote Rem 的标准化表示，包含 51 个字段
 | 字段 | 类型 | 权限 | 说明 |
 |------|------|:----:|------|
 | \\\`portalType\\\` | \\\`PortalType \\| null\\\` | R | Portal 子类型。仅 type=portal 时有值 |
-| \\\`portalDirectlyIncludedRem\\\` | \\\`string[]\\\` | R | Portal 直接包含的 Rem ID |
+| \\\`portalDirectlyIncludedRem\\\` | \\\`string[]\\\` | Portal-W | Portal 直接包含的 Rem ID。仅 type=portal 时可通过 edit-rem 修改（Diff 机制：addToPortal/removeFromPortal） |
 
 ## 属性类型
 
@@ -155,7 +156,7 @@ RemObject 是本项目对 RemNote Rem 的标准化表示，包含 51 个字段
 
 ## 可编辑字段约束表
 
-以下为 20 个可编辑字段（RW）及其写入约束：
+以下为 21 个可编辑字段（RW + Portal-W）及其写入约束：
 
 | 字段 | SDK setter | 值类型 | 约束 / 特殊处理 |
 |------|-----------|--------|-----------------|
@@ -179,6 +180,7 @@ RemObject 是本项目对 RemNote Rem 的标准化表示，包含 51 个字段
 | \\\`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 联动
 
@@ -213,13 +215,13 @@ for id in currentSet:
 
 ## 只读字段列表
 
-以下 31 个字段在 str_replace 中被修改时，**只产生警告，不执行写入**：
+以下 30 个字段在 str_replace 中被修改时，**只产生警告，不执行写入**：
 
 \\\`\\\`\\\`
 id,
 children,
 isTable,
-portalType, portalDirectlyIncludedRem,
+portalType,
 propertyType,
 aliases,
 remsBeingReferenced, deepRemsBeingReferenced, remsReferencingThis,

package/dist/mcp/resources/separator-flashcard.js

@@ -1,11 +1,11 @@
 export const SEPARATOR_FLASHCARD_CONTENT = `
 # Separator & Flashcard Reference
 
-**重要**：分隔符（\\\`::\\\`、\\\`;;\\\`、\\\`>>\\\` 等）是 RemNote 编辑器的输入语法，**CLI 不使用分隔符**。通过 CLI 创建/修改闪卡，操作的是 \\\`type\\\`、\\\`backText\\\`、\\\`practiceDirection\\\` 字段和大纲箭头（\\\`→←↔↓↑↕\\\`）。本参考表用于理解用户意图——当用户提到分隔符时，映射到对应的 CLI 操作。
+**重要**：分隔符（\\\`::\\\`、\\\`;;\\\`、\\\`>>\\\` 等）是 RemNote 编辑器的输入语法，**工具端不使用分隔符**。创建/修改闪卡，操作的是 \\\`type\\\`、\\\`backText\\\`、\\\`practiceDirection\\\` 字段和大纲箭头（\\\`→←↔↓↑↕\\\`）。本参考表用于理解用户意图——当用户提到分隔符时，映射到对应的工具操作。
 
 ---
 
-## 1. 用户意图映射：编辑器分隔符 → CLI 操作
+## 1. 用户意图映射：编辑器分隔符 → 工具操作
 
 当用户提到以下分隔符时，对应的 Rem 属性为：
 
@@ -24,7 +24,7 @@ export const SEPARATOR_FLASHCARD_CONTENT = `
 
 ---
 
-## 2. CLI 操作方式：大纲箭头
+## 2. 操作方式：大纲箭头
 
 在 Markdown 大纲（read_tree / edit_tree）中，practiceDirection 编码为 Unicode 箭头：
 
@@ -66,7 +66,7 @@ RemNote 推荐的知识结构化方法：
 - **Concept**（type:concept）：需要理解的核心概念——"X 是什么？"
 - **Descriptor**（type:descriptor）：概念的属性/描述——"X 的 Y 是什么？"
 
-在 CLI 大纲中的表现（注意：用箭头和元数据标记，不用分隔符）：
+在大纲中的表现（注意：用箭头和元数据标记，不用分隔符）：
 
 \\\`\\\`\\\`
 线性回归 ↔ 最基本的回归模型 <!--id1 type:concept-->
@@ -76,7 +76,7 @@ RemNote 推荐的知识结构化方法：
 
 ---
 
-## 5. 通过 CLI 创建闪卡
+## 5. 创建闪卡
 
 ### 使用 edit_tree 新增行
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remnote-bridge",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "RemNote 自动化桥接工具集：CLI + MCP Server + Plugin",
   "type": "module",
   "bin": {

package/remnote-plugin/src/bridge/message-router.ts

@@ -19,6 +19,9 @@ import { deleteRem } from '../services/delete-rem';
 import { moveRem } from '../services/move-rem';
 import { reorderChildren } from '../services/reorder-children';
 import { search } from '../services/search';
+import { createPortal } from '../services/create-portal';
+import { addToPortal } from '../services/add-to-portal';
+import { removeFromPortal } from '../services/remove-from-portal';
 
 /**
  * 创建消息路由处理器
@@ -50,6 +53,14 @@ export function createMessageRouter(plugin: ReactRNPlugin): (request: BridgeRequ
       case 'search':
         return search(plugin, request.payload as { query: string; numResults?: number });
 
+      // Portal 操作
+      case 'create_portal':
+        return createPortal(plugin, request.payload as { parentId: string; position?: number });
+      case 'add_to_portal':
+        return addToPortal(plugin, request.payload as { portalId: string; remId: string });
+      case 'remove_from_portal':
+        return removeFromPortal(plugin, request.payload as { portalId: string; remId: string });
+
       default:
         throw new Error(`未实现的 action: ${request.action}`);
     }

package/remnote-plugin/src/services/add-to-portal.ts

@@ -0,0 +1,40 @@
+/**
+ * add-to-portal service — 向 Portal 添加引用
+ *
+ * 同态命名：add_to_portal (action) → add-to-portal.ts (文件) → addToPortal (函数)
+ *
+ * 注意调用方向：addToPortal() 是在被引用的 Rem 上调用，参数是 Portal Rem。
+ */
+
+import type { ReactRNPlugin } from '@remnote/plugin-sdk';
+
+export interface AddToPortalPayload {
+  /** Portal Rem ID */
+  portalId: string;
+  /** 要添加到 Portal 的 Rem ID */
+  remId: string;
+}
+
+/**
+ * 将指定 Rem 添加到 Portal 的引用列表。
+ *
+ * @throws Error — Portal 不存在、Rem 不存在
+ */
+export async function addToPortal(
+  plugin: ReactRNPlugin,
+  payload: AddToPortalPayload,
+): Promise<void> {
+  const { portalId, remId } = payload;
+
+  const portal = await plugin.rem.findOne(portalId);
+  if (!portal) {
+    throw new Error(`Portal not found: ${portalId}`);
+  }
+
+  const rem = await plugin.rem.findOne(remId);
+  if (!rem) {
+    throw new Error(`Rem not found: ${remId}`);
+  }
+
+  await rem.addToPortal(portal);
+}

package/remnote-plugin/src/services/create-portal.ts

@@ -0,0 +1,47 @@
+/**
+ * create-portal service — 创建 Portal Rem
+ *
+ * 同态命名：create_portal (action) → create-portal.ts (文件) → createPortal (函数)
+ *
+ * Portal 只能通过 plugin.rem.createPortal() 创建，不能通过 setType() 将已有 Rem 转为 Portal。
+ */
+
+import type { ReactRNPlugin } from '@remnote/plugin-sdk';
+
+export interface CreatePortalPayload {
+  /** 父节点 Rem ID */
+  parentId: string;
+  /** 在兄弟中的位置（0-based），可选 */
+  position?: number;
+}
+
+export interface CreatePortalResult {
+  remId: string;
+}
+
+/**
+ * 创建空 Portal 并设置父节点。
+ *
+ * @throws Error — 创建失败、父节点不存在
+ */
+export async function createPortal(
+  plugin: ReactRNPlugin,
+  payload: CreatePortalPayload,
+): Promise<CreatePortalResult> {
+  const { parentId, position } = payload;
+
+  // 创建空 Portal
+  const portal = await plugin.rem.createPortal();
+  if (!portal) {
+    throw new Error('Failed to create portal');
+  }
+
+  // 设置父节点和位置
+  const parent = await plugin.rem.findOne(parentId);
+  if (!parent) {
+    throw new Error(`Parent Rem not found: ${parentId}`);
+  }
+  await portal.setParent(parent, position);
+
+  return { remId: portal._id };
+}

package/remnote-plugin/src/services/remove-from-portal.ts

@@ -0,0 +1,40 @@
+/**
+ * remove-from-portal service — 从 Portal 移除引用
+ *
+ * 同态命名：remove_from_portal (action) → remove-from-portal.ts (文件) → removeFromPortal (函数)
+ *
+ * 注意调用方向：removeFromPortal() 是在被引用的 Rem 上调用，参数是 Portal Rem。
+ */
+
+import type { ReactRNPlugin } from '@remnote/plugin-sdk';
+
+export interface RemoveFromPortalPayload {
+  /** Portal Rem ID */
+  portalId: string;
+  /** 要从 Portal 移除的 Rem ID */
+  remId: string;
+}
+
+/**
+ * 将指定 Rem 从 Portal 的引用列表中移除。
+ *
+ * @throws Error — Portal 不存在、Rem 不存在
+ */
+export async function removeFromPortal(
+  plugin: ReactRNPlugin,
+  payload: RemoveFromPortalPayload,
+): Promise<void> {
+  const { portalId, remId } = payload;
+
+  const portal = await plugin.rem.findOne(portalId);
+  if (!portal) {
+    throw new Error(`Portal not found: ${portalId}`);
+  }
+
+  const rem = await plugin.rem.findOne(remId);
+  if (!rem) {
+    throw new Error(`Rem not found: ${remId}`);
+  }
+
+  await rem.removeFromPortal(portal);
+}

package/remnote-plugin/src/services/write-rem-fields.ts

@@ -194,6 +194,11 @@ async function applyField(
       await applySourcesDiff(rem, value as string[]);
       break;
 
+    // Portal 引用（diff based）
+    case 'portalDirectlyIncludedRem':
+      await applyPortalRefsDiff(rem, plugin, value as string[]);
+      break;
+
     // Powerup 操作
     case 'addPowerup':
       await rem.addPowerup(value as string);
@@ -242,6 +247,40 @@ async function applySourcesDiff(rem: Rem, targetIds: string[]): Promise<void> {
   }
 }
 
+/**
+ * portalDirectlyIncludedRem diff: 对比当前和目标，通过 addToPortal/removeFromPortal 增删。
+ * 注意调用方向：addToPortal/removeFromPortal 是在被引用 Rem 上调用，参数是 Portal Rem。
+ */
+async function applyPortalRefsDiff(portalRem: Rem, plugin: ReactRNPlugin, targetIds: string[]): Promise<void> {
+  // 防御：非 Portal Rem 不可修改此字段
+  // 使用 rem.type === 6（portal 类型的枚举值），而非 getPortalType()
+  // 因为 getPortalType() 可能对新创建的 Portal 返回 undefined
+  if ((portalRem as unknown as { type: number }).type !== 6) {
+    throw new Error('portalDirectlyIncludedRem can only be modified on Portal Rem');
+  }
+
+  const currentRefs = await portalRem.getPortalDirectlyIncludedRem();
+  const currentIds = new Set(currentRefs.map((r: Rem) => r._id));
+  const targetSet = new Set(targetIds);
+
+  // 添加缺少的
+  for (const id of targetIds) {
+    if (!currentIds.has(id)) {
+      const remToAdd = await plugin.rem.findOne(id);
+      if (!remToAdd) throw new Error(`Rem not found: ${id}`);
+      await remToAdd.addToPortal(portalRem);
+    }
+  }
+  // 删除多余的
+  for (const id of currentIds) {
+    if (!targetSet.has(id as string)) {
+      const remToRemove = await plugin.rem.findOne(id as string);
+      if (!remToRemove) throw new Error(`Rem not found: ${id}`);
+      await remToRemove.removeFromPortal(portalRem);
+    }
+  }
+}
+
 /** 字符串类型值 → SDK SetRemType 枚举数值。Portal 不可通过 setType() 设置。 */
 function remTypeStringToEnum(type: string): 1 | 2 | 'DEFAULT_TYPE' {
   switch (type) {

package/remnote-plugin/src/types.ts

@@ -21,13 +21,16 @@
  * 以下每个 [RW] 字段的注释标注了其底层是 Powerup 机制还是纯字段修改
  *
  * 读写标注：
- * - [RW]   = 可读可写（SDK 有对应的 setter/add/remove 方法）
- * - [R]    = 只读，默认输出（SDK 仅有 getter）
- * - [R-F]  = 只读，仅 --full 模式输出（低频 / 细粒度 / 可由其他字段推导）
+ * - [RW]       = 可读可写（SDK 有对应的 setter/add/remove 方法）
+ * - [Portal-W] = Portal 专用可写（仅 Portal Rem 可通过 addToPortal/removeFromPortal 修改）
+ * - [R]        = 只读，默认输出（SDK 仅有 getter）
+ * - [R-F]      = 只读，仅 --full 模式输出（低频 / 细粒度 / 可由其他字段推导）
  *
  * 输出模式（CLI --full 选项）：
  * - 默认模式：输出 [RW] + [R] 字段（34 个），覆盖 Agent 常用场景
  * - --full 模式：额外输出 [R-F] 字段（+17 个），用于调试或深度分析
+ * - Portal 模式：type === 'portal' 时自动输出 9 个关键字段（id、type、portalType、
+ *   portalDirectlyIncludedRem、parent、positionAmongstSiblings、children、createdAt、updatedAt）
  *
  * 实测标注（2026-03-03 在 RemNote UI 中逐字段截图观察）：
  * - ✅ 已实测 = 在真实 RemNote 环境中创建独立 Rem 并截图观察视觉行为
@@ -254,7 +257,7 @@ export interface RemObject {
 
   /** [R] Portal 子类型。仅 type === 'portal' 时有值。SDK: getPortalType() */
   portalType: PortalType | null;
-  /** [R] Portal 直接包含的 Rem ID 数组。SDK: getPortalDirectlyIncludedRem() */
+  /** [Portal-W] Portal 直接包含的 Rem ID 数组。SDK: getPortalDirectlyIncludedRem() / addToPortal() / removeFromPortal()。写入时使用 diff 机制。仅 type === 'portal' 时可修改 */
   portalDirectlyIncludedRem: string[];
 
   // ══════════════════════════════════════════════════════════

package/skills/remnote-bridge/SKILL.md

@@ -42,7 +42,7 @@ RemNote 中所有内容的基本单元都是 **Rem**。文档、文件夹、闪
 
 两个独立维度：
 
-- **type**（闪卡语义）：`concept`（加粗）、`descriptor`（正常字重）、`default`（普通）、`portal`（只读）
+- **type**（闪卡语义）：`concept`（加粗）、`descriptor`（正常字重）、`default`（普通）、`portal`（嵌入引用容器）
 - **isDocument**（页面语义）：与 type 完全独立
 
 ### CDF 框架（Concept-Descriptor Framework）
@@ -88,7 +88,17 @@ RemNote 推荐的知识结构化方法：
 | **Tag** | `##` | Rem 的 tags 数组 | read-rem 的 `tags` 字段 |
 | **Portal** | `((` | 嵌入实时视图（**编辑同步**） | read-tree 标记 `type:portal refs:id1,id2` |
 
-Portal 的编辑同步意味着修改一处会影响另一处。Portal 引用的 Rem 不会被 read-tree 自动展开，需要对 refs 中的 ID 单独 read-tree。
+Portal 的编辑同步意味着修改一处会影响另一处。Portal 引用的 Rem 不会被 read-tree 自动展开，需要对 refs 中的 ID 单独 read-tree。Portal 引用列表可通过 `edit-rem` 修改（str_replace 简化 JSON 中的 `portalDirectlyIncludedRem` 数组）。
+
+#### 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 |
 
 ### RichText 格式
 
@@ -423,6 +433,30 @@ read-tree / read-globe / read-context 输出 Markdown 大纲，edit-tree 基于
   `代码块`
 ```
 
+### 新增行指定类型/属性（metadata-only 注释）
+
+新增行可在行尾添加 HTML 注释来指定 type、isDocument、tag，格式中不含 remId：
+
+```markdown
+  新概念 <!--type:concept-->
+  新文档页 <!--type:concept doc-->
+  带标签的描述 <!--type:descriptor tag:数学(tag01)-->
+  多标记组合 <!--type:concept doc tag:基础(tag02) tag:数学(tag01)-->
+```
+
+支持的标记：`type:concept`、`type:descriptor`、`doc`、`tag:Name(id)`（可多个，空格分隔）。
+
+### 新增 Portal
+
+在 newStr 中用特殊格式创建 Portal：
+
+```markdown
+  <!--portal refs:id1,id2-->      创建 Portal 并引用 id1、id2
+  <!--portal-->                   创建空 Portal
+```
+
+注意：与已有 Portal 行（`<!--remId type:portal refs:id1,id2-->`）不同，新增 Portal 以 `<!--portal` 开头，无 remId。Portal 不能通过 `edit-rem` 设 `type: "portal"` 创建，只能用此格式或 SDK `createPortal()`。
+
 ### 嵌套新增（一次创建父+子结构）
 
 新增行下面可以再嵌套新增行，缩进表示父子关系：
@@ -474,14 +508,14 @@ oldStr: "\"text\": [\n    \"Hello\"\n  ]"
 newStr: "\"text\": [\n    \"World\"\n  ]"
 ```
 
-### 20 个可编辑字段
+### 21 个可编辑字段
 
 ```
 text, backText, type, isDocument, parent,
 fontSize, highlightColor,
 isTodo, todoStatus, isCode, isQuote, isListItem, isCardItem, isSlot, isProperty,
 enablePractice, practiceDirection,
-tags, sources, positionAmongstSiblings
+tags, sources, positionAmongstSiblings, portalDirectlyIncludedRem
 ```
 
 ### 特殊字段处理规则
@@ -495,6 +529,7 @@ tags, sources, positionAmongstSiblings
 | `type` | 不可设为 `portal`（只能通过 SDK `createPortal()` 创建） |
 | `parent` + `positionAmongstSiblings` | 共享同一 SDK 调用 `setParent(parentId, position)`，**应在同一次 str_replace 中同时修改** |
 | `tags` / `sources` | **Diff 机制**：对比当前 vs 目标数组，逐项 add/remove。必须列出完整目标数组，缺少的会被删除 |
+| `portalDirectlyIncludedRem` | Portal 专用可写。**Diff 机制**：对比当前 vs 目标数组，逐项 addToPortal/removeFromPortal。仅 type=portal 时可修改。edit-rem 对 Portal 使用 9 字段简化 JSON |
 
 ### 常用只读字段（修改只产生警告，不生效）
 
@@ -508,6 +543,7 @@ aliases, descendants, siblingRem, isTable, portalType, propertyType
 | 模式 | 字段数 | 用法 |
 |:-----|:-------|:-----|
 | 默认 | 34（RW + R） | 常用场景 |
+| Portal 简化 | 9（id, type, portalType, portalDirectlyIncludedRem, parent, positionAmongstSiblings, children, createdAt, updatedAt） | type=portal 时自动切换，`--full` 和 `--fields` 可覆盖 |
 | `--full` | 51（含低频 R-F） | 需要 Powerup 标识、时间戳等 |
 | `--fields` | 自选 + id | 精确获取特定字段 |
 
@@ -531,6 +567,8 @@ aliases, descendants, siblingRem, isTable, portalType, propertyType
 | folded_delete | 删了有隐藏子节点的行 | 用更大 depth 重新 read-tree |
 | elided_modified | 删/改了省略占位符 | 用更大 depth/maxSiblings 重新 read-tree |
 | indent_skip | 缩进跳级（如 0→4 空格） | 每级 2 空格，不可跳级 |
+| children_captured | 新行劫持已有子节点 | 把新行插到兄弟末尾 |
+| old_str not found in simplified Portal JSON | Portal 编辑时 oldStr 不匹配简化 JSON | 检查 Portal 简化 JSON 格式 |
 | Rem not found | remId 无效或已删除 | 用 search 重新定位 |
 
 ---

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

@@ -106,7 +106,7 @@ remnote-bridge --json connect
 {
   "ok": false,
   "command": "connect",
-  "error": "守护进程启动超时（10 秒）",
+  "error": "守护进程启动超时（60 秒）",
   "timestamp": "2026-03-06T10:00:00.000Z"
 }
 ```
@@ -125,19 +125,27 @@ remnote-bridge --json connect
 3. daemon 内部按顺序启动：
    ├─ WS Server（必须成功，否则 daemon 退出）
    ├─ ConfigServer（非关键，失败不阻塞）
-   └─ webpack-dev-server（必须成功，否则 daemon 退出）
+   └─ webpack-dev-server（含依赖自动安装 + 崩溃重试）
 
 4. daemon 写入 PID 文件
 
 5. daemon 通过 IPC 发送 ready 信号给父进程
 
 6. 父进程（CLI）收到 ready → 输出结果 → 退出
-   ├─ 10 秒内未收到 → 超时失败
+   ├─ 60 秒内未收到 → 超时失败
    └─ 收到 error → 启动失败
 ```
 
 ---
 
+## Windows 注意事项
+
+- **首次 connect 较慢**：daemon 启动时会自动安装 remnote-plugin 的依赖（约 600+ 个包），在 Windows 上可能需要 30-60 秒。connect 命令的超时为 60 秒
+- **依赖自动修复**：如果 webpack-dev-server 因依赖损坏而崩溃，daemon 会自动执行清洁重装（删除 node_modules + package-lock.json 后重新安装）并重试，最多重试 2 次，无需手动干预
+- **端口残留**：多次 connect 失败后可能出现端口被占用（`EADDRINUSE`），先执行 `remnote-bridge disconnect`，如仍有残留可通过 `netstat -ano | findstr 3002` 定位 PID 后 `taskkill /F /PID <pid>` 强制终止
+
+---
+
 ## 超时机制
 
 daemon 启动后开始计时，默认 **30 分钟无 CLI 交互**自动关闭（执行优雅 shutdown）。每次收到 CLI 请求时重置计时器。