remnote-bridge 0.1.15 → 0.1.17

package/README.md

@@ -60,7 +60,7 @@ 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 read-context                  # Current page context 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
@@ -108,7 +108,7 @@ remnote-bridge search "machine learning"
 | Command | Description | Caches |
 |:--------|:------------|:-------|
 | `read-globe` | Global document-level overview | No |
-| `read-context` | Current focus/page context view | No |
+| `read-context` | Current page/focus context view | No |
 | `read-tree <remId>` | Subtree as Markdown outline | Yes |
 | `read-rem <remId>` | Single Rem's full JSON properties | Yes |
 | `read-rem-in-tree <remId>` | Subtree outline + all Rem objects in one call | Yes |
@@ -292,6 +292,17 @@ remnote-bridge addon uninstall remnote-rag --purge
 
 ## Changelog
 
+### 0.1.17 (2026-03-19)
+
+- **Defense-2 three-layer field classification** — `edit_rem` concurrency detection now classifies field differences into three tiers: semantic fields (text/type/tags etc.) → hard reject; parent → pass with `⚠️ parent has changed` warning; metadata (position/timestamps etc.) → pass with `ℹ️ Metadata fields changed` warning. This eliminates false positives after `edit_tree` move/reorder operations
+- **Documentation sync** — Updated defense-2 descriptions across all 5 doc surfaces (SKILL.md, edit-rem.md, overall.md, MCP tool description, SERVER_INSTRUCTIONS) with three-layer classification, warning text examples, and revised judgment tree
+
+### 0.1.16 (2026-03-19)
+
+- **Ordered list prefix tolerance** — `edit-tree` now accepts `2.`~`9.` prefixes for ordered lists, auto-normalizes to `isListItem=true`, and returns `templateWarnings` to remind agents to use `1.` (Lazy Numbering). `10.` and above are not matched (kept as plain text)
+- **templateWarnings passthrough fix** — CLI `edit-tree` command now correctly includes `templateWarnings` in JSON output (was silently dropped)
+- **Lazy Numbering documentation** — Added prominent warnings in MCP tool description, SERVER_INSTRUCTIONS, and Skill docs explaining RemNote's auto-numbering convention
+
 ### 0.1.15 (2026-03-18)
 
 - **Defense-2 false positive fix** — Removed `.sort()` from ID arrays in RemObject serialization that caused spurious concurrency conflicts in edit-rem

package/README.zh-CN.md

@@ -60,7 +60,7 @@ remnote-bridge health
 
 # 4. 浏览知识库
 remnote-bridge read-globe                    # 全局文档概览
-remnote-bridge read-context                  # 当前焦点/页面上下文
+remnote-bridge read-context                  # 当前页面/焦点上下文
 remnote-bridge search "machine learning"     # 全文搜索
 remnote-bridge read-tree <remId>             # 展开子树
 remnote-bridge read-rem <remId>              # 读取 Rem 属性
@@ -108,7 +108,7 @@ remnote-bridge search "machine learning"
 | 命令 | 说明 | 缓存 |
 |:-----|:-----|:-----|
 | `read-globe` | 全局文档级概览 | 否 |
-| `read-context` | 当前焦点/页面上下文视图 | 否 |
+| `read-context` | 当前页面/焦点上下文视图 | 否 |
 | `read-tree <remId>` | 子树序列化为 Markdown 大纲 | 是 |
 | `read-rem <remId>` | 单个 Rem 的完整 JSON 属性 | 是 |
 | `read-rem-in-tree <remId>` | 子树大纲 + 所有 Rem 对象，一次调用 | 是 |
@@ -292,6 +292,17 @@ remnote-bridge addon uninstall remnote-rag --purge
 
 ## Changelog
 
+### 0.1.17 (2026-03-19)
+
+- **防线 2 三层字段分类** — `edit_rem` 并发检测现在将字段差异分为三层：语义字段（text/type/tags 等）→ 硬拒绝；parent → 放行并返回 `⚠️ parent has changed` 警告；元数据（位置/时间戳等）→ 放行并返回 `ℹ️ Metadata fields changed` 警告。消除 `edit_tree` 移动/重排后的误报
+- **文档同步** — 在全部 5 个文档面（SKILL.md、edit-rem.md、overall.md、MCP 工具描述、SERVER_INSTRUCTIONS）更新防线 2 描述：三层分类机制、警告文本示例、修订判断树
+
+### 0.1.16 (2026-03-19)
+
+- **有序列表前缀容错** — `edit-tree` 新增行现在接受 `2.`~`9.` 前缀，自动归一化为 `isListItem=true`，并返回 `templateWarnings` 提醒使用 `1.`（Lazy Numbering 风格）。`10.` 及以上不匹配（保留为纯文本）
+- **templateWarnings 透传修复** — CLI `edit-tree` 命令现在正确包含 `templateWarnings` 到 JSON 输出中（之前被静默丢弃）
+- **Lazy Numbering 文档** — 在 MCP 工具描述、SERVER_INSTRUCTIONS 和 Skill 文档中添加醒目的有序列表使用规范说明
+
 ### 0.1.15 (2026-03-18)
 
 - **防线 2 误判修复** — 移除 RemObject 序列化中 ID 数组的 `.sort()`，消除 edit-rem 并发检测的假阳性

package/dist/cli/commands/edit-tree.js

@@ -33,7 +33,12 @@ export async function editTreeCommand(remId, options) {
         return;
     }
     if (json) {
-        jsonOutput({ ok: true, command: 'edit-tree', operations: data.operations });
+        jsonOutput({
+            ok: true,
+            command: 'edit-tree',
+            operations: data.operations,
+            ...(data.templateWarnings?.length && { templateWarnings: data.templateWarnings }),
+        });
     }
     else {
         if (data.operations.length === 0) {
@@ -46,5 +51,11 @@ export async function editTreeCommand(remId, options) {
                 console.log(`  - ${o.type}: ${JSON.stringify(o)}`);
             }
         }
+        if (data.templateWarnings?.length) {
+            console.log('⚠ 模板/前缀警告：');
+            for (const w of data.templateWarnings) {
+                console.log(`  - ${w}`);
+            }
+        }
     }
 }

package/dist/cli/commands/read-context.js

@@ -2,7 +2,7 @@
  * read-context 命令
  *
  * 读取当前上下文视图。
- * - --mode focus|page（默认 focus）
+ * - --mode focus|page（默认 page）
  * - --ancestor-levels N 向上追溯几层祖先（默认 2，仅 focus 模式）
  * - --depth N 展开深度（默认 3，仅 page 模式）
  * - --max-nodes N 全局节点上限（默认 200）
@@ -14,8 +14,8 @@ import { sendDaemonRequest } from '../daemon/send-request.js';
 import { jsonOutput, handleCommandError } from '../utils/output.js';
 export async function readContextCommand(options = {}) {
     const { json } = options;
-    const mode = options.mode || 'focus';
-    if (mode !== 'focus' && mode !== 'page') {
+    const mode = options.mode;
+    if (mode !== undefined && mode !== 'focus' && mode !== 'page') {
         const errMsg = '--mode must be "focus" or "page"';
         if (json) {
             jsonOutput({ ok: false, command: 'read-context', error: errMsg });
@@ -43,7 +43,9 @@ export async function readContextCommand(options = {}) {
     }
     let result;
     try {
-        const reqPayload = { mode, ancestorLevels, depth, maxNodes, maxSiblings };
+        const reqPayload = { ancestorLevels, depth, maxNodes, maxSiblings };
+        if (mode)
+            reqPayload.mode = mode;
         if (options.focusRemId)
             reqPayload.focusRemId = options.focusRemId;
         result = await sendDaemonRequest('read_context', reqPayload);

package/dist/cli/config.js

@@ -26,7 +26,7 @@ export const DEFAULT_DEFAULTS = {
     readTreeIncludePowerup: false,
     readRemInTreeMaxNodes: 50,
     readGlobeDepth: -1,
-    readContextMode: 'focus',
+    readContextMode: 'page',
     readContextAncestorLevels: 2,
     readContextDepth: 3,
     searchNumResults: 20,

package/dist/cli/handlers/edit-handler.js

@@ -5,7 +5,7 @@
  * Plugin 只负责原子写入（write_rem_fields）。
  *
  * 防线 1：缓存存在性检查（必须先 read 再 edit）
- * 防线 2：乐观并发检测（当前 JSON 与缓存 JSON 比较）
+ * 防线 2：语义并发检测（三层字段比较：语义字段硬拒绝，元数据放行+警告）
  */
 /** 只读字段集合 — 变更这些字段只产生警告，不执行写入 */
 const READ_ONLY_FIELDS = new Set([
@@ -25,6 +25,28 @@ const READ_ONLY_FIELDS = new Set([
     'isPowerup', 'isPowerupEnum', 'isPowerupProperty',
     'isPowerupPropertyListItem', 'isPowerupSlot',
 ]);
+// ── 防线 2 三层字段分类 ──────────────────────────────────────
+// 不在以下两个集合中的字段 = 第1层语义字段（硬拒绝）
+/** 第2层：敏感元数据字段——放行但输出专门警告。扩展时须同步更新 handleEditRem 中的 warned 警告生成逻辑 */
+const DEFENSE2_WARN_FIELDS = new Set([
+    'parent',
+]);
+/** 第3层：普通元数据字段——放行，有变化时输出统一警告 */
+const DEFENSE2_IGNORE_FIELDS = new Set([
+    'id',
+    // 位置/时间
+    'positionAmongstSiblings', 'updatedAt', 'localUpdatedAt', 'createdAt',
+    'lastPracticed', 'lastTimeMovedTo', 'timesSelectedInSearch',
+    // 级联关联
+    'children', 'siblingRem', 'descendants',
+    'deepRemsBeingReferenced', 'remsReferencingThis',
+    'taggedRem', 'ancestorTagRem', 'descendantTagRem',
+    'portalsAndDocumentsIn', 'allRemInDocumentOrPortal', 'allRemInFolderQueue',
+    // 系统
+    'schemaVersion', 'embeddedQueueViewMode',
+    'isPowerup', 'isPowerupEnum', 'isPowerupProperty',
+    'isPowerupPropertyListItem', 'isPowerupSlot',
+]);
 /** 可写字段白名单 — 21 个可写字段 */
 const WRITABLE_FIELDS = new Set([
     'text', 'backText', 'type', 'isDocument', 'parent',
@@ -58,19 +80,34 @@ export class EditHandler {
         if (!cachedObj) {
             throw new Error(`Rem ${remId} has not been read yet. Read it first before editing.`);
         }
-        // ── 防线 2: 乐观并发检测 ──
+        // ── 防线 2: 乐观并发检测（三层字段比较） ──
         const currentRemObject = await this.forwardToPlugin('read_rem', { remId });
-        const currentJson = JSON.stringify(currentRemObject, null, 2);
-        const cachedJson = JSON.stringify(cachedObj, null, 2);
-        if (currentJson !== cachedJson) {
-            // 诊断日志：打出具体哪些字段不同，帮助定位并发误判
-            const diff = diffFields(cachedObj, currentRemObject);
-            console.error(`[defense-2] Rem ${remId} conflict detected. Changed fields: ${diff.join(', ') || '(JSON differs but no top-level field diff — possible nested change)'}`);
-            // 不更新缓存 — 迫使 AI re-read
+        const { semantic, warned, ignored } = classifyDiff(cachedObj, currentRemObject);
+        // 第1层：语义字段冲突 → 硬拒绝
+        if (semantic.length > 0) {
+            console.error(`[defense-2] Rem ${remId} conflict. Changed semantic fields: ${semantic.join(', ')}`);
             throw new Error(`Rem ${remId} has been modified since last read. Please read it again before editing.`);
         }
+        // 第2层+第3层：元数据变化 → 放行，收集警告
+        const defense2Warnings = [];
+        if (warned.length > 0) {
+            const cachedParent = cachedObj.parent;
+            const currentParent = currentRemObject.parent;
+            defense2Warnings.push(`⚠️ parent has changed (was: ${cachedParent}, now: ${currentParent}). ` +
+                `The Rem has been moved to a different parent since last read. Proceeding with edit.`);
+            console.error(`[defense-2] Rem ${remId} parent changed: ${cachedParent} → ${currentParent}`);
+        }
+        if (ignored.length > 0) {
+            defense2Warnings.push(`ℹ️ Metadata fields changed since last read: ${ignored.join(', ')}. ` +
+                `This is expected after structural operations. Proceeding with edit.`);
+            console.error(`[defense-2] Rem ${remId} metadata drift: ${ignored.join(', ')}`);
+        }
+        // 静默刷新缓存（保持新鲜度）
+        if (warned.length > 0 || ignored.length > 0) {
+            this.cache.set('rem:' + remId, currentRemObject);
+        }
         // ── 遍历 changes keys：分类过滤 ──
-        const warnings = [];
+        const warnings = [...defense2Warnings];
         const writableChanges = {};
         for (const key of Object.keys(changes)) {
             if (READ_ONLY_FIELDS.has(key)) {
@@ -129,14 +166,24 @@ export class EditHandler {
         };
     }
 }
-/** 比较两个 RemObject 的顶层字段，返回值不同的 key 列表 */
-function diffFields(cached, current) {
+/** 三层字段分类比较 — 防线2核心逻辑 */
+function classifyDiff(cached, current) {
     const allKeys = new Set([...Object.keys(cached), ...Object.keys(current)]);
-    const changed = [];
+    const semantic = [];
+    const warned = [];
+    const ignored = [];
     for (const key of allKeys) {
-        if (JSON.stringify(cached[key]) !== JSON.stringify(current[key])) {
-            changed.push(key);
+        if (JSON.stringify(cached[key]) === JSON.stringify(current[key]))
+            continue;
+        if (DEFENSE2_WARN_FIELDS.has(key)) {
+            warned.push(key);
+        }
+        else if (DEFENSE2_IGNORE_FIELDS.has(key)) {
+            ignored.push(key);
+        }
+        else {
+            semantic.push(key);
         }
     }
-    return changed;
+    return { semantic, warned, ignored };
 }

package/dist/cli/handlers/tree-edit-handler.js

@@ -172,7 +172,9 @@ export class TreeEditHandler {
                     else {
                         // ── 普通 Rem 创建路径 ──
                         // 解析 Markdown 前缀 + 箭头分隔符 → 属性
-                        const { cleanContent, powerups, backText, practiceDirection } = parsePowerupPrefix(op.content);
+                        const { cleanContent, powerups, backText, practiceDirection, warnings: prefixWarnings } = parsePowerupPrefix(op.content);
+                        if (prefixWarnings?.length)
+                            templateWarnings.push(...prefixWarnings);
                         const createResult = await this.forwardToPlugin('create_rem', {
                             content: cleanContent,
                             parentId,

package/dist/cli/handlers/tree-parser.js

@@ -141,6 +141,7 @@ export function parseMetadata(metadataStr) {
  */
 export function parsePowerupPrefix(rawContent) {
     const powerups = {};
+    const warnings = [];
     if (rawContent === '---') {
         return { cleanContent: '', powerups: { addPowerup: 'dv' } };
     }
@@ -168,6 +169,20 @@ export function parsePowerupPrefix(rawContent) {
         powerups.isTodo = true;
         content = content.slice(6);
     }
+    // Quote（引用块）
+    if (content.startsWith('> ')) {
+        powerups.isQuote = true;
+        content = content.slice(2);
+    }
+    // ListItem（有序列表）— 容错 1-9 开头，归一化为 isListItem
+    const listItemMatch = content.match(/^([1-9])\. /);
+    if (listItemMatch) {
+        powerups.isListItem = true;
+        content = content.slice(listItemMatch[0].length);
+        if (listItemMatch[1] !== '1') {
+            warnings.push(`有序列表前缀 "${listItemMatch[0]}" 已归一化为 isListItem（RemNote 自动编号，请统一使用 "1. "）`);
+        }
+    }
     // Code
     if (content.startsWith('`') && content.endsWith('`') && content.length >= 2) {
         powerups.isCode = true;
@@ -231,6 +246,8 @@ export function parsePowerupPrefix(rawContent) {
         result.practiceDirection = practiceDirection;
     if (isMultiline !== undefined)
         result.isMultiline = isMultiline;
+    if (warnings.length > 0)
+        result.warnings = warnings;
     return result;
 }
 // ────────────────────────── Multiline 检测 ──────────────────────────

package/dist/cli/main.js

@@ -249,7 +249,7 @@ program
 program
     .command('read-context [jsonStr]')
     .description('读取当前上下文视图（focus 鱼眼 / page 页面）')
-    .option('--mode <mode>', '模式：focus（默认）或 page')
+    .option('--mode <mode>', '模式：page（默认）或 focus')
     .option('--ancestor-levels <levels>', '向上追溯几层祖先（默认 2，仅 focus 模式）')
     .option('--depth <depth>', '展开深度（默认 3，仅 page 模式）')
     .option('--max-nodes <maxNodes>', '全局节点上限（默认 200）')

package/dist/cli/server/config-server.js

@@ -281,8 +281,8 @@ export class ConfigServer {
     <div class="field">
       <label>模式 (readContextMode)</label>
       <select id="readContextMode">
-        <option value="focus">focus</option>
         <option value="page">page</option>
+        <option value="focus">focus</option>
       </select>
     </div>
     <div class="field">

package/dist/mcp/instructions.js

@@ -238,7 +238,7 @@ disconnect → 关闭 daemon + headless Chrome，清空所有缓存，清除 hea
 - 用户的描述与你已知信息对不上
 - 搜索不到用户提到的内容
 
-\`read_context\`：focus 模式（默认）以用户焦点为中心构建鱼眼视图；page 模式以当前页面为根展开。两者都返回面包屑路径。
+\`read_context\`：默认使用 **page 模式**——只需有打开的页面即可，几乎总能成功。仅当需要知道用户光标具体在哪个 Rem 上时，才显式传 \`mode="focus"\`（focus 模式要求用户光标停在某个 Rem 上，否则报错"当前没有聚焦的 Rem"）。两者都返回面包屑路径。
 
 ### 场景 D：修改文本或属性
 
@@ -326,7 +326,9 @@ changes: { "type": "concept", "highlightColor": "Yellow", "fontSize": "H1" }
 
 新增行（无 remId 注释的行）支持以下格式：
 
-**Markdown 前缀**：\`# \` \`## \` \`### \` \`- [ ] \` \`- [x] \` \\\`code\\\` \`---\`
+**Markdown 前缀**：\`# \` \`## \` \`### \` \`- [ ] \` \`- [x] \` \`> \`(引用块) \`1. \`(有序列表) \\\`code\\\` \`---\`
+
+> **⚠️ 有序列表必须用 \`1. \` 前缀（Lazy Numbering）**：RemNote 有序列表采用 Lazy Numbering——所有列表项统一写 \`1. \`，RemNote 按层级自动编号（1./2./3./A./B./I./II.）。不要手动编号（如 \`2. \` \`3. \`）。\`2. \`~\`9. \` 会被容错处理（归一化为 isListItem 并返回 templateWarnings 警告），\`10. \` 及以上不会被识别为有序列表。
 
 **箭头分隔符**：
 - 单行：\`→\`（forward）\`←\`（backward）\`↔\`（both）——格式 \`text → backText\`
@@ -446,7 +448,7 @@ oldStr: "  {{idZ}}"   newStr: "  {{idZ}}\\n  新行"
 ### 两道防线
 
 1. **缓存存在**：必须有对应的 read 缓存
-2. **并发检测**：edit 时重新读取最新数据与缓存比较，Rem 被外部修改则拒绝——必须重新 read
+2. **语义并发检测**（三层字段分类）：edit 时重新读取最新数据并逐字段比较——语义字段（text/type/tags 等）变化 → 硬拒绝；parent 变化 → 放行 + warnings 返回 \`"⚠️ parent has changed (was: X, now: Y)..."\`；普通元数据（positionAmongstSiblings/updatedAt 等）变化 → 放行 + warnings 返回 \`"ℹ️ Metadata fields changed since last read: ..."\`。这意味着 \`edit_tree\` 移动/重排 Rem 后，可以直接 \`edit_rem\` 修改受影响节点，无需重新 read
 
 ### edit_tree 禁止事项
 
@@ -463,7 +465,9 @@ oldStr: "  {{idZ}}"   newStr: "  {{idZ}}\\n  新行"
 | 场景 | 缓存行为 | 重试策略 |
 |:-----|:---------|:---------|
 | edit_rem 写入成功 | 从 Plugin 重新读取 → 更新缓存 | 可继续编辑 |
-| edit_rem 防线拒绝/部分失败 | 不更新缓存 | 必须重新 read_rem |
+| edit_rem 仅元数据变化 | 静默刷新缓存并放行 | 可继续编辑（返回警告） |
+| edit_rem 语义字段冲突 | 不更新缓存 | 必须重新 read_rem |
+| edit_rem 部分写入失败 | 不更新缓存 | 必须重新 read_rem |
 | edit_tree 成功 | 自动 re-read → 更新缓存 | 可连续 edit |
 | edit_tree 防线 3 拒绝（str_replace 不匹配等） | 缓存保持不变 | 调整 oldStr/newStr 后直接重试 |
 | edit_tree 执行中异常 | 已执行操作保留（**无回滚**），不更新缓存 | 必须重新 read_tree |
@@ -502,7 +506,7 @@ tags, sources, positionAmongstSiblings, portalDirectlyIncludedRem
 \`\`\`
 
 - 缩进：每级 2 空格
-- 前缀：\`# \`(H1)、\`## \`(H2)、\`### \`(H3)、\`- [ ] \`(待办)、\`- [x] \`(已完成)、\\\`...\\\`(代码)、\`---\`(分隔线)
+- 前缀：\`# \`(H1)、\`## \`(H2)、\`### \`(H3)、\`- [ ] \`(待办)、\`- [x] \`(已完成)、\`> \`(引用块)、\`1. \`(有序列表)、\\\`...\\\`(代码)、\`---\`(分隔线)
 
 ### 元数据标记
 
@@ -537,7 +541,7 @@ tags, sources, positionAmongstSiblings, portalDirectlyIncludedRem
 新增行（无 remId 注释的行）在 newStr 中出现时，会被创建为新的 Rem。格式选项：
 
 - 纯文本行：\`新内容\`
-- 带前缀：\`# 新标题\`、\`- [ ] 新待办\`
+- 带前缀：\`# 新标题\`、\`- [ ] 新待办\`、\`> 引用内容\`、\`1. 列表项\`
 - 带箭头：\`问题 → 答案\`、\`概念 ↔ 定义\`、\`题目 ↓\`
 - 带元数据注释（metadata-only，无 remId）：\`新行 <!--type:concept doc-->\`
 - Portal 行：\`<!--portal refs:id1,id2-->\`
@@ -628,7 +632,7 @@ tags, sources, positionAmongstSiblings, portalDirectlyIncludedRem
 - 超链接必须用 \`iUrl\`，\`url\` 字段已废弃无效
 - RichText 对象内部按 **key 字母序排列**（\`_id\` < \`b\` < \`cId\` < \`h\` < \`i\` < \`iUrl\` < \`text\`），确保序列化一致性
 - \`highlightColor\`（RemObject 顶层，字符串 \`"Red"\`）与 \`h\`（RichText 内部，数字 \`1\`）完全独立——前者是整行背景色，后者是文字片段荧光底色
-- 防线 2（乐观并发检测）依赖 key 字母序的确定性序列化来比较缓存与最新数据
+- 防线 2（语义并发检测）依赖 key 字母序的确定性序列化来比较语义字段
 
 ---
 
@@ -643,7 +647,7 @@ tags, sources, positionAmongstSiblings, portalDirectlyIncludedRem
 ├─ "Plugin 未连接" → RemNote 未打开或插件未加载 → 引导用户操作 RemNote
 ├─ "SDK 未就绪" → 知识库尚未加载 → 等待并重试 health
 ├─ "has not been read yet" → 未先 read → 执行对应 read 后重试
-├─ "has been modified since last read" → 被外部修改 → 必须重新 read（不可直接重试）
+├─ "has been modified since last read" → 语义字段被外部修改 → 必须重新 read（不可直接重试）
 ├─ "Invalid value" → 枚举字段值不合法 → 检查允许的值范围
 ├─ "old_str not found" → oldStr 不精确 → 检查缩进、空格、换行
 ├─ "old_str matches N locations" → oldStr 不够具体 → 扩大范围包含更多上下文

package/dist/mcp/tools/edit-tools.js

@@ -28,13 +28,17 @@ export function registerEditTools(server) {
             '\\n- fontSize: H1 / H2 / H3 / null（恢复普通）' +
             '\\n- todoStatus: Finished / Unfinished / null（需先 isTodo=true）' +
             '\\n\\nhighlightColor vs RichText h 字段：两者完全独立。highlightColor 是整行背景色（字符串如 "Red"）；h 是 RichText 元素内部的行内荧光底色（数字：1=Red, 2=Orange, 3=Yellow, 4=Green, 5=Purple, 6=Blue, 7=Gray, 8=Brown, 9=Pink）。' +
-            '\\n\\n输出格式：JSON 对象，包含 changes（已写入的字段名数组）和 warnings（只读/未知字段警告数组）。' +
+            '\\n\\n输出格式：JSON 对象，包含 changes（已写入的字段名数组）和 warnings（警告数组，可能包含防线2元数据警告和字段校验警告）。' +
             '\\n\\n两道防线：' +
             '\\n1. 缓存存在检查——未先 read_rem 则报 "has not been read yet"' +
-            '\\n2. 并发检测——edit 时重新从 Plugin 读取并对比缓存，不一致则报 "has been modified since last read"。防线拒绝/部分失败时不更新缓存，迫使重新 read_rem' +
+            '\\n2. 语义并发检测（三层字段分类）——edit 时重新读取并逐字段比较：' +
+            '\\n   - 语义字段（text/type/tags 等）变化 → 硬拒绝 "has been modified since last read"' +
+            '\\n   - parent 变化 → 放行 + warnings 返回 "⚠️ parent has changed (was: X, now: Y)..."' +
+            '\\n   - 普通元数据（positionAmongstSiblings/updatedAt 等）变化 → 放行 + warnings 返回 "ℹ️ Metadata fields changed since last read: ..."' +
+            '\\n   这意味着 edit_tree 移动/重排后可直接 edit_rem，无需重新 read' +
             '\\n\\n常见错误：' +
             '\\n- "has not been read yet" → 先 read_rem' +
-            '\\n- "has been modified since last read" → 重新 read_rem' +
+            '\\n- "has been modified since last read" → 语义字段被外部修改，重新 read_rem' +
             '\\n- "Invalid value for \'field\'" → 检查枚举合法值' +
             '\\n- "Field \'...\' is read-only/unknown and was ignored" → 警告不阻断' +
             '\\n\\n关联工具：read_rem（前置读取）、edit_tree（子树结构编辑）',
@@ -71,7 +75,8 @@ export function registerEditTools(server) {
             '\\n4. 重排：调换同级行的顺序' +
             '\\n执行顺序：Create → Move → Reorder → Delete' +
             '\\n\\n新增行格式：' +
-            '\\n- Markdown 前缀：# / ## / ### / - [ ] / - [x] / `代码` / ---' +
+            '\\n- Markdown 前缀：# / ## / ### / - [ ] / - [x] / > / 1. / `代码` / ---' +
+            '\\n  ⚠️ 有序列表必须用 `1. `（Lazy Numbering）：RemNote 自动编号，不要写 `2. ` `3. ` 等。`2.`~`9.` 会被容错归一化并返回 templateWarnings 警告，`10.` 及以上不识别为列表。' +
             '\\n- 箭头分隔符（闪卡）：→ ← ↔（单行）、↓ ↑ ↕（多行，带 backText 或子节点为答案）' +
             '\\n- 元数据注释（可选）：<!--type:concept--> <!--doc--> <!--tag:Name(id)--> 可组合' +
             '\\n- Portal 创建：<!--portal refs:id1,id2--> 或 <!--portal-->（空 Portal）' +

package/dist/mcp/tools/read-tools.js

@@ -329,11 +329,15 @@ export function registerReadTools(server) {
             '\\n\\n重要：用户正在看的页面对 AI 不可见。当用户说"这个"、"当前页面"、"这里"，或描述与已知信息对不上时，必须主动调用 read_context 对齐信息。' +
             '\\n\\n适用场景：了解用户当前焦点位置或打开的页面；用户说"我现在在看什么"、"当前页面是什么"时使用；需要上下文才能理解用户指代时使用。' +
             '\\n不适用场景：查看特定 Rem（已知 remId 用 read_tree）；搜索内容（用 search）。' +
-            '\\n\\n前置条件：daemon 已连接。focus 模式需用户在 RemNote 中有焦点 Rem（光标在某个 Rem 上）或指定 focusRemId；page 模式需有打开的页面。' +
+            '\\n\\n前置条件：daemon 已连接。page 模式只需有打开的页面（几乎总满足）；focus 模式需用户光标停在某个 Rem 上或指定 focusRemId（否则报错"当前没有聚焦的 Rem"）。' +
+            '\\n\\n模式选择指引：' +
+            '\\n- 绝大多数场景用 page（默认）——用户通常只是打开页面浏览，不会特意点击某个 Rem，page 更可靠' +
+            '\\n- 仅当需要知道用户光标具体在哪个 Rem 上时才用 focus——如用户说"我正在编辑的这个"、"光标所在的 Rem"' +
+            '\\n- 不确定时用 page——最坏情况只是展开整个页面；focus 的最坏情况是报错' +
             '\\n\\n参数说明：' +
-            '\\n- mode（可选，默认 "focus"）：视图模式' +
+            '\\n- mode（可选，默认 "page"）：视图模式' +
+            '\\n  - page：以当前打开的页面为根，均匀展开子树（推荐，可靠性高）' +
             '\\n  - focus：以焦点 Rem 为中心的鱼眼视图。焦点完全展开(depth=3)，siblings 浅层预览(depth=1，前3个children可见)，叔伯不展开。焦点行以 * 前缀标记' +
-            '\\n  - page：以当前打开的页面为根，均匀展开子树' +
             '\\n- focusRemId（可选，仅 focus 模式）：指定任意 Rem 作为鱼眼中心，此时不依赖用户实际焦点。page 模式下传入会报错' +
             '\\n- ancestorLevels（可选，默认 2，仅 focus 模式生效）：从焦点向上追溯几层祖先作为上下文起点' +
             '\\n- depth（可选，默认 3，仅 page 模式生效）：向下展开深度（-1 无限）' +
@@ -352,7 +356,7 @@ export function registerReadTools(server) {
             mode: z
                 .enum(['focus', 'page'])
                 .optional()
-                .describe('视图模式：focus（聚焦）或 page（页面），默认 focus'),
+                .describe('视图模式：page（页面）或 focus（聚焦），默认 page'),
             ancestorLevels: z
                 .number()
                 .optional()

package/package.json

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