mn-docs-mcp 0.6.1 → 1.0.0

package/src/content/docs/reference/global/jsb.md

@@ -1,12 +1,12 @@
 ---
 title: JSB
-description: JavaScript 桥接核心，连接插件 JS 与运行时对象的入口对象。
+description: JavaScript 桥接核心，连接插件 JS 与宿主对象的入口对象。
 ---
-JSB（JavaScript Bridge）是插件运行时的桥接核心对象：类定义、插件入口、日志与包内脚本加载都通过它完成。
+JSB（JavaScript Bridge）是插件环境的桥接核心对象：类定义、插件入口、日志与包内脚本加载都通过它完成。
 
 ## 实例成员 (Instance members)
 
-`JSB` 是全局对象，通常不以“实例化”的方式使用。
+`JSB` 是全局对象，默认不以“实例化”的方式使用。
 
 ## 类成员 (Class members)
 
@@ -14,7 +14,9 @@ JSB（JavaScript Bridge）是插件运行时的桥接核心对象：类定义、
 
 ### `defineClass`
 
-定义一个可被运行时识别并回调的类，**所有插件的入口**。
+定义一个可被插件环境识别并回调的类，只在插件入口处使用。
+
+注意：该方法定义的类非js的类，this并不会指向该类的实例，而应使用[self](/reference/global/self/) 替代
 
 ```javascript
 defineClass(declaration: string, instanceMembers: object, classMembers?: object): any
@@ -62,7 +64,7 @@ log(format: string, ...args: any[]): void
 
 | Name        | Type       | Description                                             |
 | :---------- | :--------- | :------------------------------------------------------ |
-| `format`  | `string` | 格式化字符串，支持 `%@`、`%d` 等 Objective-C 格式。 |
+| `format`  | `string` | 格式化字符串，支持`%@`、`%d`等占位符。 |
 | `...args` | `any[]`  | 对应格式化字符串的参数。                                |
 
 ### `require`

package/src/content/docs/reference/global/note.md

@@ -3,13 +3,13 @@ title: Note
 description: 全局注入的笔记工厂对象，用于创建新笔记（MbBookNote）。
 ---
 
-`Note` 是 MarginNote 运行时注入到 JavaScript 环境中的**全局对象**之一，用于创建新笔记。
+`Note` 是 MarginNote 宿主注入到 JavaScript 环境中的**全局对象**之一，用于创建新笔记。
 
 需要特别注意：创建笔记的方法**不在** `MbBookNote` 类上，而是在全局 `Note` 对象上（这是由 MarginNote 的 JSExport 导出方式决定的）。
 
 ## 实例成员 (Instance members)
 
-`Note` 是全局对象，通常不以实例形式使用。
+`Note` 是全局对象，默认不以实例形式使用。
 
 ## 类成员 (Class members)
 
@@ -43,16 +43,16 @@ var notebook = db.getNotebookById("NOTEBOOK_ID");
 var doc = db.getDocumentById("DOC_MD5");
 
 if (notebook && doc) {
-  var topicid = notebook.topicId || notebook.topicid; // 兼容不同 getter 命名
+  var topicId = notebook.topicId;
   UndoManager.sharedInstance().undoGrouping(
     "创建笔记",
-    topicid,
+    topicId,
     function () {
       var note = Note.createWithTitleNotebookDocument("新笔记", notebook, doc);
       // note 为 MbBookNote
     }
   );
-  Application.sharedInstance().refreshAfterDBChanged(topicid);
+  Application.sharedInstance().refreshAfterDBChanged(topicId);
 }
 ```
 

package/src/content/docs/reference/global/notebook.md

@@ -0,0 +1,21 @@
+---
+title: Notebook
+description: 全局别名对象。语义上等同于MbTopic。
+---
+
+`Notebook`是插件环境的全局导出别名，语义上等同于[MbTopic](/reference/marginnote/mb-topic/)。
+
+## 关系说明
+
+- `Notebook`与`MbTopic`是同一类主题对象在全局入口层的别名语义，不是两套模型。
+- 主键语义为`topicId/topicid`。
+- 对象生命周期由宿主数据层管理，不把`documents/notes`当强一致缓存长期持有。
+
+## 用法
+
+完整属性与方法请直接参考[MbTopic](/reference/marginnote/mb-topic/)。
+
+## 相关
+
+- [MbTopic](/reference/marginnote/mb-topic/)
+- [Database](/reference/global/database/)

package/src/content/docs/reference/global/popup-menu-item.md

@@ -3,14 +3,14 @@ title: PopupMenuItem
 description: PopupMenu 的菜单项对象（全局注入）。
 ---
 
-`PopupMenuItem` 是运行时注入的全局类型（对应原生 QBPopupMenuItem）。通常由运行时创建并用于渲染；可读属性包含标题与动作标识。
+`PopupMenuItem` 是宿主注入的全局类型（对应原生 QBPopupMenuItem）。默认由插件环境创建并用于渲染；可读属性包含标题与动作标识。
 
 ## 实例成员 (Instance members)
 
 | 属性 | 类型 | 说明 |
 |---|---|---|
 | `title` | `string` | 显示标题。 |
-| `actionString` | `string` | 动作标识字符串（用途依赖运行时）。 |
+| `actionString` | `string` | 动作标识字符串（用途依赖插件环境）。 |
 
 ## 相关
 

package/src/content/docs/reference/global/popup-menu.md

@@ -3,7 +3,7 @@ title: PopupMenu
 description: 轻量弹出菜单视图（全局注入），用于展示一组 PopupMenuItem。
 ---
 
-`PopupMenu` 是运行时注入的全局类（对应原生 QBPopupMenu）。常用于在指定 rect 附近弹出一组菜单项。
+`PopupMenu` 是宿主注入的全局类（对应原生 QBPopupMenu）。常用于在指定 rect 附近弹出一组菜单项。
 
 ## 类成员 (Class members)
 
@@ -20,19 +20,18 @@ description: 轻量弹出菜单视图（全局注入），用于展示一组 Pop
 |---|---|---|
 | `visible` | `boolean` | 是否可见。 |
 | `items` | `NSArray` | 菜单项列表。 |
-| `arrowDirection` | `number` | 箭头方向（枚举值以运行时为准）。 |
-| `targetWinRect` | `CGRect` | 目标窗口 rect（只读）。 |
+| `arrowDirection` | `number` | 箭头方向Default/Up/Down/Left/Right，数值 0/1/2/3/4。 |
+| `targetWinRect` | [`CGRect`](/reference/value-sturct/#cgrect) | 目标窗口 rect（只读）。 |
 
 ### 方法
 
 | 方法 | 参数 | 返回值 | 说明 |
 |---|---|---|---|
-| `showInViewTargetRectAnimated(view, targetRect, animated)` | view: `UIView`, targetRect: `CGRect`, animated: boolean | — | 在 view 中显示。 |
-| `updateWithTargetRect(targetRect)` | targetRect: `CGRect` | — | 更新目标 rect。 |
+| `showInViewTargetRectAnimated(view, targetRect, animated)` | view: `UIView`, targetRect: [`CGRect`](/reference/value-sturct/#cgrect), animated: boolean | — | 在 view 中显示。 |
+| `updateWithTargetRect(targetRect)` | targetRect: [`CGRect`](/reference/value-sturct/#cgrect) | — | 更新目标 rect。 |
 | `dismissAnimated(animated)` | animated: boolean | — | 关闭菜单。 |
 
 ## 相关
 
 - [PopupMenuItem](/reference/global/popup-menu-item/)
 - [UIView](/reference/uikit/uiview/)
-

package/src/content/docs/reference/global/search-manager.md

@@ -3,7 +3,7 @@ title: SearchManager
 description: 搜索与索引管理器（全文检索、URL 搜索、相似笔记检索等）。
 ---
 
-`SearchManager` 通过 `Application.sharedInstance().searchManager` 获取。其返回结构与索引能力会随版本变化；建议先在控制台打印返回值结构再做兼容处理。
+`SearchManager` 通过 `Application.sharedInstance().searchManager` 获取。其返回结构与索引能力会随版本变化；先在控制台打印返回值结构再做兼容处理。
 
 ## 实例成员 (Instance members)
 
@@ -22,9 +22,9 @@ description: 搜索与索引管理器（全文检索、URL 搜索、相似笔记
 | `searchText(query, titleOnly, topicid, beginsWith, limit)` | 文本搜索。 |
 | `searchTextNoteOnly(query, titleOnly, topicid, beginsWith, limit, noteOnly)` | 文本搜索（可限定只搜笔记）。 |
 | `searchTextWordList(textWordLst, titleOnly, topicid, beginsWith, limit)` | 使用分词列表进行搜索。 |
-| `searchFts3Text(query, titleOnly, topicid, limit, noteOnly)` | 通过 FTS3 搜索（实现依赖运行时）。 |
-| `searchURLs(urls, topicid)` | 按 URL 列表搜索。 |
-| `searchPage(query, beginsWith, limit)` | 页内搜索（实现依赖运行时）。 |
+| `searchFts3Text(query, titleOnly, topicid, limit, noteOnly)` | 通过 FTS3 搜索。 |
+| `searchURLs(urls, topicid)` | 按 URL 列表搜索。插件环境`urls`必须为`NSArray`，传原始字符串会报`TypeError: Cannot convert primitive to NSArray`。`topicid`可传`string`或`NSArray`。 |
+| `searchPage(query, beginsWith, limit)` | 页内搜索。 |
 | `snippetForFts3RowId(rowid)` / `snippetForPageRowId(rowid)` | 获取 snippet（结果摘要）。 |
 
 ### 同步与索引
@@ -43,9 +43,15 @@ description: 搜索与索引管理器（全文检索、URL 搜索、相似笔记
 | `findSimilarNotes(queryVector, topicId, k)` | 向量相似笔记检索。 |
 | `batchFindSimilarNotes(queryVectors, topicId, k)` | 批量向量相似检索。 |
 | `findSimilarNotesHybrid(queryVector, queryText, topicId, k, semanticWeight, bm25Weight)` | 语义+BM25 混合检索。 |
-| `loadVectorCacheForTopic(topicId)` / `syncTopicVectorsForceCompletion(topicId, force, completion)` / `invalidateVectorCacheForTopics(topicIds)` | 向量缓存相关（实现依赖运行时）。 |
+| `loadVectorCacheForTopic(topicId)` / `syncTopicVectorsForceCompletion(topicId, force, completion)` / `invalidateVectorCacheForTopics(topicIds)` | 向量缓存相关。 |
+
+### 已确认行为
+
+- `searchPage(...)`有命中时返回数组对象，无命中时返回空数组。
+- `searchPage("", ...)`返回`undefined`，不是空数组。
+- 当前样本中`searchFts3Text(...)`有命中与无命中都会返回空数组，结果受索引状态影响较大。
+- `snippetForFts3RowId(rowid)`与`snippetForPageRowId(rowid)`在当前样本中返回`undefined`。
 
 ## 相关
 
 - [Application](/reference/global/application/) — `Application.sharedInstance().searchManager`
-

package/src/content/docs/reference/global/self.md

@@ -3,19 +3,7 @@ title: self
 description: 在 JSExtension 实例方法内指向当前插件实例的上下文。
 ---
 
-在 `JSB.defineClass` 定义的**实例方法**内部，`self` 指向该插件类的当前实例。用于访问插件自身的 `window` 以及你在实例上挂载的属性（如自定义的 viewController、layout 函数等）。
-
-## 实例成员 (Instance members)
-
-### 属性
-
-| 属性 | 类型 | 说明 |
-|------|------|------|
-| `window` | `UIWindow` | 当前插件所在窗口。常与 `Application.sharedInstance().studyController(self.window)` 配合获取学习控制器。 |
-
-## 类成员 (Class members)
-
-`self` 是实例上下文变量，不以类成员形式存在。
+在 `JSB.defineClass` 定义的**实例方法**内部，`self` 指向该类的当前实例，用于访问定义的类实例属性。
 
 ## 说明
 

package/src/content/docs/reference/js-runtime.md

@@ -1,8 +1,8 @@
 ---
 title: JavaScript原生环境
-description: MarginNote插件运行时的JavaScriptCore能力边界、内置对象与常见误区。
+description: MarginNote插件环境的JavaScriptCore能力边界、内置对象与常见问题。
 ---
-MarginNote插件运行在JavaScriptCore中，而不是浏览器环境。这意味着标准JavaScript内置对象可用，但浏览器相关API通常不存在，且宿主会额外注入自己的对象与能力。
+MarginNote插件运行在JavaScriptCore中，而不是浏览器环境。这意味着标准JavaScript内置对象可用，但浏览器相关API默认不存在，且宿主会额外注入自己的对象与能力。
 
 ## 内置对象一览
 
@@ -73,12 +73,13 @@ MarginNote插件运行在JavaScriptCore中，而不是浏览器环境。这意
 | [NaN](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/NaN)                                   | 非数值常量                  |
 | [undefined](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined)                       | 未定义常量                  |
 
-## 环境差异与建议
+## 环境差异与规范
 
-- 插件环境没有原生fetch。需要网络请求时，请使用已导出的Objective‑C网络类。
-- 插件环境没有setTimeout/setInterval。建议使用NSTimer完成延时与轮询。
+- 插件环境没有原生fetch。需要网络请求时，请使用文档提供的网络请求API。
+- 插件环境没有setTimeout/setInterval。使用NSTimer完成延时与轮询。
 
 ## 相关
 
 - [NSTimer](/reference/foundation/ns-timer/)
 - [网络请求](/guides/network-requests/)
+- [Value Sturct](/reference/value-sturct/)

package/src/content/docs/reference/marginnote/document-controller.md

@@ -11,15 +11,15 @@ description: 单个文档的控制器，提供当前文档与选区。
 
 | 属性 | 类型 | 说明 |
 |------|------|------|
-| `document` | `MbBook` \| undefined | 当前文档对象（getter 为 currBook）。 |
-| `docMd5` | `string` | 当前文档 MD5（getter 为 currentBookMd5）。 |
-| `notebookId` | `string` | 当前笔记本 ID（getter 为 currTopicId）。 |
+| `document` | `MbBook` \| undefined | 当前文档对象。 |
+| `docMd5` | `string` | 当前文档MD5。 |
+| `notebookId` | `string` | 当前笔记本ID。 |
 | `focusNote` | `MbBookNote` \| undefined | 当前焦点笔记。 |
 | `visibleFocusNote` | `MbBookNote` \| undefined | 当前可见的焦点笔记。 |
-| `lastFocusNote` | `MbBookNote` \| undefined | 上一次的焦点笔记（getter 为 lastFocusNote）。 |
+| `lastFocusNote` | `MbBookNote` \| undefined | 上一次的焦点笔记。 |
 | `selectionText` | `string` \| undefined | 用户在 PDF 中当前选中的文本。 |
-| `currPageNo` | `number` | 当前页码（运行时定义，通常从 1 开始）。 |
-| `currPageIndex` | `number` | 当前页索引（运行时定义，通常从 0 开始）。 |
+| `currPageNo` | `number` | 当前页码（默认从 1 开始）。 |
+| `currPageIndex` | `number` | 当前页索引（默认从 0 开始）。 |
 | `isSelectionText` | `boolean` | 当前是否存在文本选区。 |
 
 ### 方法
@@ -29,14 +29,46 @@ description: 单个文档的控制器，提供当前文档与选区。
 | `imageFromSelection()` | — | `NSData` | 从当前选区导出图片数据（若可用）。 |
 | `imageFromFocusNote()` | — | `NSData` | 从当前焦点笔记导出图片数据（若可用）。 |
 | `setPageAtIndex(index)` | index: number | — | 跳转到指定页索引。 |
-| `indicesFromPageNo(pageNo)` | pageNo: number | `NSArray<number>` | 由页码得到可能的页索引列表。 |
+| `indicesFromPageNo(pageNo)` | pageNo: number | `NSArray<number>` | 由页码得到会的页索引列表。 |
 | `indexFromPageNo(pageNo)` | pageNo: number | number | 由页码得到页索引。 |
 | `pageNoFromIndex(index)` | index: number | number | 由页索引得到页码。 |
-| `highlightFromSelection()` | — | `any` | 从当前选区生成高亮对象（类型依赖运行时）。 |
+| `highlightFromSelection()` | — | `MbBookNote \| undefined` | 从当前选区创建或定位高亮笔记并返回该笔记。 |
+
+### `highlightFromSelection`
+
+```javascript
+highlightFromSelection(): MbBookNote | undefined
+```
+
+**定义：**
+
+从当前文档选区创建或定位一条高亮笔记并返回。
+
+**返回：**
+
+- 有有效选区时返回`MbBookNote`。
+- 无选区时返回`undefined`。
+
+**行为：**
+
+- 调用前可通过`selectionText`与`isSelectionText`读取当前选区状态。
+- 调用后可直接读取返回对象的`noteId`确认结果。
+
+**副作用：**
+
+- 会更新当前焦点笔记或当前笔记状态。
+- 会刷新与选区相关的界面状态。
+
+**最小验证：**
+
+1. 读取`selectionText`与`isSelectionText`。
+2. 调用`highlightFromSelection()`。
+3. 检查返回对象是否存在且包含`noteId`。
+4. 清空选区后重复调用，确认返回`undefined`。
 
 ## 类成员 (Class members)
 
-当前运行时未额外暴露 `DocumentController` 的类成员。
+当前接口未额外暴露 `DocumentController` 的类成员。
 
 ## 相关
 

package/src/content/docs/reference/marginnote/jsextension.md

@@ -56,31 +56,31 @@ description: 插件主类必须继承的基类，处理生命周期与工具栏
 
 ### `queryShortcutKeyWithKeyFlags(command,keyFlags)`语义
 
-`queryShortcutKeyWithKeyFlags(command,keyFlags)`用于“查询状态”，系统可能在以下场景批量调用它：
+`queryShortcutKeyWithKeyFlags(command,keyFlags)`用于“查询状态”，系统会在以下场景批量调用它：
 
 - 判断当前上下文哪些快捷键可用（disabled/checked状态）。
 - 重建或刷新键盘命令列表（keyCommands）。
 - 某些焦点/编辑态变化引发的状态刷新。
 
-因此你可能“只按了一次Left”，但看到大量不同的`command`与`keyFlags`日志。这是正常现象。
+因此你会“只按了一次Left”，但看到大量不同的`command`与`keyFlags`日志。这是正常现象。
 
 #### command的两类来源
 
-已确认`command`可能来自两条路径：
+已确认`command`会来自两条路径：
 
 - 内建命令名：例如`NewChildNote`、`ToggleExpand`、`EditAddTitle`等。
 - 输入常量/字符：例如`UIKeyInputLeftArrow`、`UIKeyInputUpArrow`，以及`z`这类字符输入。
 
-建议：在query里只匹配你关心的组合键，其余直接`return null`保持静默；不要在query里做任何数据库/笔记结构修改。
+要求：在query里只匹配你关心的组合键，其余直接`return null`保持静默；不要在query里做任何数据库/笔记结构修改。
 
-返回值通常包含：
+返回值默认包含：
 
 - `disabled:boolean`：是否不可用。
 - `checked:boolean`：是否勾选态（用于UI状态展示）。
 
 ### `processShortcutKeyWithKeyFlags(command,keyFlags)`语义
 
-`processShortcutKeyWithKeyFlags(command,keyFlags)`用于“处理按下”，真正的业务动作应放在这里（例如outdent/移动层级等）。建议遵循：
+`processShortcutKeyWithKeyFlags(command,keyFlags)`用于“处理按下”，真正的业务动作应放在这里（例如outdent/移动层级等）。遵循：
 
 - query只返回状态，不产生副作用。
 - process里执行操作，并用`UndoManager.undoGrouping(...)`包裹可撤销修改。
@@ -99,7 +99,7 @@ description: 插件主类必须继承的基类，处理生命周期与工具栏
 
 ### 已知限制：编辑态会吞键
 
-当用户正在编辑文本（例如评论输入框等）时，当前firstResponder通常会优先消费按键，插件快捷键可能不触发。这是预期行为，建议将快捷键主要用于非编辑态操作。
+当用户正在编辑文本（例如评论输入框等）时，当前firstResponder默认会优先消费按键，插件快捷键会不触发。这是预期行为，将快捷键主要用于非编辑态操作。
 
 ## 类成员 (Class members)
 

package/src/content/docs/reference/marginnote/mb-book-note.md

@@ -3,7 +3,7 @@ title: MbBookNote
 description: 笔记核心对象，代表脑图中的一条笔记及其摘录、评论、链接与层级。
 ---
 
-插件开发中最核心的数据对象，代表一条笔记（脑图节点）。可通过 [Database.getNoteById](/reference/global/database/)、[NotebookController.focusNote](/reference/marginnote/notebook-controller/)、[MindMapNode.note](/reference/marginnote/mindmap-node/) 等获取。修改后建议使用 [UndoManager.undoGrouping](/reference/utility/undo-manager/) 包裹并刷新界面。
+插件开发中最核心的数据对象，代表一条笔记（脑图节点）。可通过 [Database.getNoteById](/reference/global/database/)、[NotebookController.focusNote](/reference/marginnote/notebook-controller/)、[MindMapNode.note](/reference/marginnote/mindmap-node/) 等获取。修改后使用 [UndoManager.undoGrouping](/reference/utility/undo-manager/) 包裹并刷新界面。
 
 ## 实例成员 (Instance members)
 
@@ -13,7 +13,7 @@ description: 笔记核心对象，代表脑图中的一条笔记及其摘录、
 | :--- | :--- | :--- |
 | `noteTitle` | `string` | 笔记标题。 |
 | `excerptText` | `string` | 摘录文本。 |
-| `excerptTextMarkdown` | `number` | 摘录文本是否为 Markdown（运行时字段，通常为 0/1）。 |
+| `excerptTextMarkdown` | `number` | 摘录文本是否为 Markdown（接口字段，为 0/1）。 |
 | `colorIndex` | `number` | 颜色索引 (0–15)。 |
 | `fillIndex` | `number` | 填充类型。 |
 
@@ -35,17 +35,17 @@ description: 笔记核心对象，代表脑图中的一条笔记及其摘录、
 | `groupNoteId` | `string` | 分组笔记 ID。 |
 | `comments` | `NSArray` | 评论数组，元素为 [NoteComment](/reference/marginnote/note-comment/) 结构。 |
 | `parentNote` | `MbBookNote` \| undefined | 父笔记。 |
-| `childMindMap` | `MbBookNote` \| undefined | 子脑图（getter 为 parentDraft）。 |
+| `childMindMap` | `MbBookNote` \| undefined | 子脑图。 |
 | `linkedNotes` | `NSArray` | 链接的笔记。 |
 | `childNotes` | `NSArray` | 子笔记数组。 |
 | `summaryLinks` | `NSArray` | 摘要链接。 |
 | `zLevel` / `hidden` / `toc` / `annotation` / `textFirst` / `groupMode` / `flashcard` / `flagged` | `NSNumber` | 各类标志。 |
-| `summary` | `boolean` | 是否有摘要链接（getter hasSummaryLinks）。 |
+| `summary` | `boolean` | 是否有摘要链接。 |
 | `textHighlight` / `options` | `NSDictionary` | 文本高亮与选项。 |
 
 ### 实例方法
 
-### `appendTextComment`
+#### `appendTextComment`
 
 添加一条文本评论。
 
@@ -59,7 +59,7 @@ appendTextComment(text: string): void
 | :--- | :--- | :--- |
 | `text` | `string` | 评论内容。 |
 
-### `appendMarkdownComment`
+#### `appendMarkdownComment`
 
 添加一条 Markdown 格式评论。
 
@@ -73,7 +73,7 @@ appendMarkdownComment(text: string): void
 | :--- | :--- | :--- |
 | `text` | `string` | Markdown 格式的评论内容。 |
 
-### `appendNoteLink`
+#### `appendNoteLink`
 
 添加指向另一条笔记的链接。
 
@@ -89,7 +89,7 @@ appendNoteLink(note: MbBookNote): void
 
 **说明**：会在 `comments` 数组中添加一条 `TextNote` 类型的评论，`text` 字段存储格式为 `marginnote4app://note/{noteId}`。
 
-### `merge`
+#### `merge`
 
 添加笔记链接（历史命名；等价于“把另一条笔记作为链接加入 comments”）。
 
@@ -97,26 +97,28 @@ appendNoteLink(note: MbBookNote): void
 merge(note: MbBookNote): void
 ```
 
-### `appendHtmlComment`
+#### `appendHtmlComment`
 
-添加 HTML 评论（已废弃，建议使用 `appendMarkdownComment`）。
+添加 HTML 评论。
 
 ```javascript
-appendHtmlComment(html: string, text: string, size: CGSize, tag: string): void
+appendHtmlComment(html: string, text: string, size: [CGSize](/reference/value-sturct/#cgsize), tag: string): void
 ```
 
+其中`size`类型见[`CGSize`](/reference/value-sturct/#cgsize)。
+
 **Parameters:**
 
 | Name | Type | Description |
 | :--- | :--- | :--- |
 | `html` | `string` | HTML 内容。 |
 | `text` | `string` | 纯文本内容（用于搜索等）。 |
-| `size` | `CGSize` | 渲染尺寸。 |
+| `size` | [`CGSize`](/reference/value-sturct/#cgsize) | 渲染尺寸。 |
 | `tag` | `string` | 标签标识。 |
 
-**说明**：此方法已废弃，HTML 评论不再单独存储，建议使用 `appendMarkdownComment` 替代。
+**说明**：此方法已废弃，HTML 评论不再单独存储，使用 `appendMarkdownComment` 替代。
 
-### `removeCommentByIndex`
+#### `removeCommentByIndex`
 
 按索引删除一条评论。
 
@@ -130,7 +132,7 @@ removeCommentByIndex(index: number): void
 | :--- | :--- | :--- |
 | `index` | `number` | 评论在 `comments` 数组中的索引。 |
 
-### `clearFormat`
+#### `clearFormat`
 
 清除笔记文本格式。
 
@@ -138,7 +140,7 @@ removeCommentByIndex(index: number): void
 clearFormat(): void
 ```
 
-### `paste`
+#### `paste`
 
 粘贴（将剪贴板内容作为评论或摘录）。
 
@@ -146,7 +148,7 @@ clearFormat(): void
 paste(): void
 ```
 
-### `allNoteText`
+#### `allNoteText`
 
 获取笔记全部文本（标题+摘录+评论）。
 
@@ -158,11 +160,114 @@ allNoteText(): string
 
 - `string`: 聚合文本。
 
+#### `removeFromParent`
+
+从父节点移除当前笔记。
+
+```javascript
+removeFromParent(): void
+```
+
+#### `insertChildBefore`
+
+在指定子节点前插入一条子笔记。
+
+```javascript
+insertChildBefore(note: MbBookNote, beforeNote: MbBookNote): void
+```
+
+#### `addChild`
+
+添加一条子笔记。
+
+```javascript
+addChild(note: MbBookNote): void
+```
+
+#### `sortCommentsByNewIndices`
+
+按新索引数组重排`comments`。
+
+```javascript
+sortCommentsByNewIndices(newIndices: NSArray): void
+```
+
+#### `realGroupNoteIdForTopicId`
+
+获取分组笔记在指定笔记本下的真实ID。
+
+```javascript
+realGroupNoteIdForTopicId(topicid: string): string
+```
+
+#### `processMarkdownBase64Images`
+
+```javascript
+processMarkdownBase64Images(): boolean
+```
+
+**定义：**
+
+处理当前笔记中符合条件的Markdown文本里的`data:image...base64`图片引用。
+
+**返回：**
+
+- `true`表示发生了实际改写。
+- `false`表示未发生改写。
+
+**行为：**
+
+- 仅处理满足条件的Markdown文本。
+- 命中base64图片引用时会转存媒体并替换引用。
+
+**副作用：**
+
+- 会改写笔记内容相关字段。
+- 会更新`mediaList`。
+- 会更新笔记修改时间。
+
+**最小验证：**
+
+1. 短文本+无base64。
+2. 短文本+有base64。
+3. 长文本+无base64。
+4. 长文本+有base64。
+
+分别记录调用前后内容与返回值。
+
+#### `getDrawingSize`
+
+```javascript
+getDrawingSize(): NSNumber
+```
+
+**定义：**
+
+返回该笔记绘图相关媒体的二进制总字节数。
+
+**返回：**
+
+- `NSNumber`，值为字节总数。
+
+#### `getStrokesCount`
+
+```javascript
+getStrokesCount(): NSInteger
+```
+
+**定义：**
+
+返回该笔记绘图笔画总数。
+
+**返回：**
+
+- `NSInteger`，值为笔画数量。
+
 ## 类成员 (Class members)
 
 ### `createWithTitleNotebookDocument`
 
-创建新笔记（类方法）。在 JS 侧通常通过全局注入的 `Note` 对象调用同名方法。
+创建新笔记类方法。在JS侧默认通过全局注入的`Note`对象调用同名方法。
 
 ```javascript
 static createWithTitleNotebookDocument(title: string, notebook: MbTopic, document: MbBook): MbBookNote
@@ -174,18 +279,6 @@ static createWithTitleNotebookDocument(title: string, notebook: MbTopic, documen
 
 - [Note](/reference/global/note/) — `Note.createWithTitleNotebookDocument(title, notebook, doc)`
 
-## 其他常用实例方法
-
-| 方法 | 说明 |
-|------|------|
-| `removeFromParent()` | 从父节点移除。 |
-| `insertChildBefore(note, beforeNote)` | 在指定子节点前插入。 |
-| `addChild(note)` | 添加子节点。 |
-| `processMarkdownBase64Images()` | 处理 Markdown 中的 base64 图片（按运行时实现）。 |
-| `sortCommentsByNewIndices(newIndices)` | 按新索引数组重排 comments。 |
-| `getDrawingSize()` / `getStrokesCount()` | 绘制相关信息（按运行时实现）。 |
-| `realGroupNoteIdForTopicId(topicid)` | 获取分组笔记在指定笔记本下的真实 ID。 |
-
 ## 相关
 
 - [NoteComment](/reference/marginnote/note-comment/)、[MbTopic](/reference/marginnote/mb-topic/)、[MbBook](/reference/marginnote/mb-book/)

package/src/content/docs/reference/marginnote/mb-book.md

@@ -11,11 +11,11 @@ description: 文档对象，代表一个 PDF/EPUB 文档。
 
 | 属性 | 类型 | 说明 |
 |------|------|------|
-| `docMd5` | `string` | 文档唯一 MD5（getter 为 md5real）。 |
-| `docTitle` | `string` | 文档标题（getter 为 bookTitle）。 |
+| `docMd5` | `string` | 文档唯一MD5。 |
+| `docTitle` | `string` | 文档标题。 |
 | `pathFile` | `string` | 文档在 MarginNote 存储中的相对路径。 |
-| `fullPathFileName` | `string` | 文档的完整路径（若环境可用）。 |
-| `currentTopicId` | `string` | 当前所属笔记本 ID（getter 为 currenttopicid）。 |
+| `fullPathFileName` | `string` | 文档的完整路径。 |
+| `currentTopicId` | `string` | 当前所属笔记本ID。 |
 | `lastVisit` | `NSDate` | 最后访问时间。 |
 | `pageCount` | `number` | 总页数。 |
 
@@ -23,12 +23,12 @@ description: 文档对象，代表一个 PDF/EPUB 文档。
 
 | 方法 | 参数 | 返回值 | 说明 |
 |------|------|--------|------|
-| `textContentsForPageNo(pageNo)` | pageNo: number | `NSArray` | 获取指定页的文本内容（实现/结构依赖运行时）。 |
+| `textContentsForPageNo(pageNo)` | pageNo: number | `NSArray` | 获取指定页文本内容。已确认返回二维数组结构，外层为行/段集合，内层元素为对象；键结构不稳定，先打印后使用。 |
 | `tocAll()` | — | `NSArray` | 获取文档目录（Table of Contents）。 |
 
 ## 类成员 (Class members)
 
-当前运行时未额外暴露 `MbBook` 的类成员。
+当前接口未额外暴露 `MbBook` 的类成员。
 
 ## 相关
 

package/src/content/docs/reference/marginnote/mb-model-tool.md

@@ -58,8 +58,8 @@ description: 数据库工具协议，Database 单例的实现类型，提供笔
 
 | 方法 | 说明 |
 |------|------|
-| `sharedInstance()` | 获取单例（通常通过全局对象 [Database](/reference/global/database/) 使用）。 |
-| `transDictionaryToJSCompatible(dic)` / `transArrayToJSCompatible(arr)` | 将原生容器转换为更易于 JS 使用的结构（按运行时实现）。 |
+| `sharedInstance()` | 获取单例（默认通过全局对象 [Database](/reference/global/database/) 使用）。 |
+| `transDictionaryToJSCompatible(dic)` / `transArrayToJSCompatible(arr)` | 将原生容器转换为更易于 JS 使用的结构。 |
 
 ## 相关