mn-docs-mcp 0.1.0

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

@@ -0,0 +1,28 @@
+---
+title: self
+description: 在 JSExtension 实例方法内指向当前插件实例的上下文。
+---
+
+在 `JSB.defineClass` 定义的**实例方法**内部，`self` 指向该插件类的当前实例。用于访问插件自身的 `window` 以及你在实例上挂载的属性（如自定义的 viewController、layout 函数等）。
+
+## 实例成员 (Instance members)
+
+### 属性
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `window` | `UIWindow` | 当前插件所在窗口。常与 `Application.sharedInstance().studyController(self.window)` 配合获取学习控制器。 |
+
+## 类成员 (Class members)
+
+`self` 是实例上下文变量，不以类成员形式存在。
+
+## 说明
+
+- 仅在**实例方法**中有效（如 `sceneWillConnect`、`notebookWillOpen`、`queryAddonCommandStatus`、`toggleSample:` 等）；在**类方法**（如 `addonDidConnect`）中无 `self`。
+- 工具栏按钮的 selector 若指向实例方法（如 `toggleSample:`），在该方法内可用 `self` 访问插件实例和 `self.window`。
+
+## 相关
+
+- [JSExtension](/reference/marginnote/jsextension/) — 插件生命周期
+- [Application](/reference/global/application/) — 常用 `studyController(self.window)`

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

@@ -0,0 +1,28 @@
+---
+title: JavaScript 原生环境
+description: MarginNote 插件运行时的 JavaScriptCore 能力边界与常见误区。
+---
+
+MarginNote 插件的 JS 运行环境是 **JavaScriptCore**（不是浏览器）。因此很多“浏览器 JS”里理所当然的能力，在插件里可能不存在或行为不同。
+
+## 你仍然拥有的标准能力
+
+- `Math` / `Date` / `JSON` / `RegExp`
+- 基本语法与原型链
+- 通过 JSB 导出的 Objective‑C 对象与方法（本项目的 API 参考主体）
+
+## 常见误区
+
+### 1) 没有原生 `fetch`
+
+插件环境里通常**没有**浏览器的 `fetch`。网络请求应使用已导出的 Objective‑C 网络类，完整用法见 [网络请求](/guides/network-requests/) 教程（`NSURLConnection`、`NSMutableURLRequest`、`NSOperationQueue` 等）。
+
+### 2) 可能没有 `setTimeout` / `setInterval`
+
+纯 JSCore 环境通常**不包含**这两个定时器函数（它们属于浏览器/宿主实现）。在插件里推荐使用 `NSTimer` 实现延时/轮询。
+
+## 相关
+
+- [NSTimer](/reference/foundation/ns-timer/)
+- [网络请求](/guides/network-requests/)
+

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

@@ -0,0 +1,45 @@
+---
+title: DocumentController
+description: 单个文档的控制器，提供当前文档与选区。
+---
+
+管理单个打开的文档，通过 `ReaderController.currentDocumentController` 获取当前显示的文档控制器。
+
+## 实例成员 (Instance members)
+
+### 属性（只读）
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `document` | `MbBook` \| undefined | 当前文档对象（getter 为 currBook）。 |
+| `docMd5` | `string` | 当前文档 MD5（getter 为 currentBookMd5）。 |
+| `notebookId` | `string` | 当前笔记本 ID（getter 为 currTopicId）。 |
+| `focusNote` | `MbBookNote` \| undefined | 当前焦点笔记。 |
+| `visibleFocusNote` | `MbBookNote` \| undefined | 当前可见的焦点笔记。 |
+| `lastFocusNote` | `MbBookNote` \| undefined | 上一次的焦点笔记（getter 为 lastFocusNote）。 |
+| `selectionText` | `string` \| undefined | 用户在 PDF 中当前选中的文本。 |
+| `currPageNo` | `number` | 当前页码（运行时定义，通常从 1 开始）。 |
+| `currPageIndex` | `number` | 当前页索引（运行时定义，通常从 0 开始）。 |
+| `isSelectionText` | `boolean` | 当前是否存在文本选区。 |
+
+### 方法
+
+| 方法 | 参数 | 返回值 | 说明 |
+|------|------|--------|------|
+| `imageFromSelection()` | — | `NSData` | 从当前选区导出图片数据（若可用）。 |
+| `imageFromFocusNote()` | — | `NSData` | 从当前焦点笔记导出图片数据（若可用）。 |
+| `setPageAtIndex(index)` | index: number | — | 跳转到指定页索引。 |
+| `indicesFromPageNo(pageNo)` | pageNo: number | `NSArray<number>` | 由页码得到可能的页索引列表。 |
+| `indexFromPageNo(pageNo)` | pageNo: number | number | 由页码得到页索引。 |
+| `pageNoFromIndex(index)` | index: number | number | 由页索引得到页码。 |
+| `highlightFromSelection()` | — | `any` | 从当前选区生成高亮对象（类型依赖运行时）。 |
+
+## 类成员 (Class members)
+
+当前运行时未额外暴露 `DocumentController` 的类成员。
+
+## 相关
+
+- [ReaderController](/reference/marginnote/reader-controller/)
+- [MbBook](/reference/marginnote/mb-book/)、[MbBookNote](/reference/marginnote/mb-book-note/)
+- [教程：脑图与选区](/guides/mindmap-and-selection/)

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

@@ -0,0 +1,119 @@
+---
+title: JSExtension
+description: 插件主类必须继承的基类，处理生命周期与工具栏命令。
+---
+
+你的插件主类必须通过 `JSB.defineClass('MyAddon : JSExtension', ...)` 继承 JSExtension，用于处理窗口/笔记本/文档的生命周期以及工具栏图标状态。
+
+## 实例成员 (Instance members)
+
+### 属性（只读）
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `window` | `UIWindow` | 当前插件所在窗口。在实例方法内也可用 `self.window`。 |
+
+### 实例方法（生命周期）
+
+| 方法 | 参数 | 说明 |
+|------|------|------|
+| `sceneWillConnect()` | — | 插件窗口即将创建时调用，可在此做 UI 初始化。 |
+| `sceneDidDisconnect()` | — | 插件窗口断开时调用。 |
+| `sceneWillResignActive()` | — | 窗口即将失去活跃时调用。 |
+| `sceneDidBecomeActive()` | — | 窗口变为活跃时调用。 |
+| `notebookWillOpen(topicid)` | `topicid`: string | 某个笔记本即将打开时调用。 |
+| `notebookWillClose(topicid)` | `topicid`: string | 某个笔记本即将关闭时调用。 |
+| `documentDidOpen(docmd5)` | `docmd5`: string | 某文档已打开时调用。 |
+| `documentWillClose(docmd5)` | `docmd5`: string | 某文档即将关闭时调用。 |
+
+### 实例方法（工具栏与扩展）
+
+| 方法 | 返回值/参数 | 说明 |
+|------|-------------|------|
+| `queryAddonCommandStatus()` | `NSDictionary` \| null | MarginNote 用来决定工具栏图标状态。必须返回包含 `image`、`object`、`selector`、`checked` 的对象；不显示图标可返回 null。 |
+| `additionalTitleLinksOfNotebook(topicid)` | `NSArray` | 为指定笔记本提供额外标题链接。 |
+| `viewControllerForTitleLink(titleLink)` | `UIViewController` | 根据标题链接返回对应视图控制器。 |
+| `controllerWillLayoutSubviews(controller)` | `controller`: UIViewController | 指定控制器即将布局子视图时调用，可在此调整插件面板位置。 |
+| `additionalShortcutKeys()` | `NSArray` | 返回插件提供的额外快捷键。 |
+| `queryShortcutKeyWithKeyFlags(command, keyFlags)` | `NSDictionary` | 查询某快捷键的状态。 |
+| `processShortcutKeyWithKeyFlags(command, keyFlags)` | — | 处理快捷键按下。 |
+
+## 快捷键（additionalShortcutKeys/query/process）
+
+### `additionalShortcutKeys()`返回值结构
+
+`additionalShortcutKeys()`应返回一个数组，数组元素为“字典项”（Dictionary）。系统会读取这些字典项并构造对应的键盘命令。
+
+目前已确认字典项的核心字段如下：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `input` | `string` | 按键输入，例如`"UIKeyInputLeftArrow"`、`"z"`、`"["`等。 |
+| `flags` | `number` | 修饰键位掩码（见下方keyFlags表）。 |
+| `title` | `string` | 用于显示的标题（例如出现在快捷键列表中）。 |
+
+说明：该接口不是直接返回`UIKeyCommand[]`。
+
+### `queryShortcutKeyWithKeyFlags(command,keyFlags)`语义
+
+`queryShortcutKeyWithKeyFlags(command,keyFlags)`用于“查询状态”，系统可能在以下场景批量调用它：
+
+- 判断当前上下文哪些快捷键可用（disabled/checked状态）。
+- 重建或刷新键盘命令列表（keyCommands）。
+- 某些焦点/编辑态变化引发的状态刷新。
+
+因此你可能“只按了一次Left”，但看到大量不同的`command`与`keyFlags`日志。这是正常现象。
+
+#### command的两类来源
+
+已确认`command`可能来自两条路径：
+
+- 内建命令名：例如`NewChildNote`、`ToggleExpand`、`EditAddTitle`等。
+- 输入常量/字符：例如`UIKeyInputLeftArrow`、`UIKeyInputUpArrow`，以及`z`这类字符输入。
+
+建议：在query里只匹配你关心的组合键，其余直接`return null`保持静默；不要在query里做任何数据库/笔记结构修改。
+
+返回值通常包含：
+
+- `disabled:boolean`：是否不可用。
+- `checked:boolean`：是否勾选态（用于UI状态展示）。
+
+### `processShortcutKeyWithKeyFlags(command,keyFlags)`语义
+
+`processShortcutKeyWithKeyFlags(command,keyFlags)`用于“处理按下”，真正的业务动作应放在这里（例如outdent/移动层级等）。建议遵循：
+
+- query只返回状态，不产生副作用。
+- process里执行操作，并用`UndoManager.undoGrouping(...)`包裹可撤销修改。
+
+### keyFlags常用位值
+
+以下为常用[修饰键位值](https://learn.microsoft.com/en-us/dotnet/api/uikit.uikeymodifierflags?view=net-ios-26.2-10.0)：
+
+| 修饰键 | 值 |
+|---|---:|
+| Shift | `131072` |
+| Control | `262144` |
+| Option(Alt) | `524288` |
+| Command | `1048576` |
+| Command+Shift | `1179648` |
+
+### 已知限制：编辑态会吞键
+
+当用户正在编辑文本（例如评论输入框等）时，当前firstResponder通常会优先消费按键，插件快捷键可能不触发。这是预期行为，建议将快捷键主要用于非编辑态操作。
+
+## 类成员 (Class members)
+
+### 类方法
+
+| 方法 | 说明 |
+|------|------|
+| `addonDidConnect()` | 插件被 MarginNote 加载后调用。 |
+| `addonWillDisconnect()` | 插件即将卸载时调用。 |
+| `applicationDidEnterBackground()` | 应用进入后台时调用。 |
+| `applicationWillEnterForeground()` | 应用即将进入前台时调用。 |
+| `applicationDidReceiveLocalNotification(notify)` | 收到本地通知时调用（仅在部分平台可用，例如非 xrOS 环境）。 |
+
+## 相关
+
+- [JSB](/reference/global/jsb/) — 使用 `defineClass('MyAddon : JSExtension', ...)`
+- [快速开始](/guides/getting-started/)、[生命周期与窗口](/guides/lifecycle-and-window/)、[工具栏与命令](/guides/toolbar-and-commands/)

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

@@ -0,0 +1,192 @@
+---
+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/) 包裹并刷新界面。
+
+## 实例成员 (Instance members)
+
+### 可读写属性
+
+| 属性 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `noteTitle` | `string` | 笔记标题。 |
+| `excerptText` | `string` | 摘录文本。 |
+| `excerptTextMarkdown` | `number` | 摘录文本是否为 Markdown（运行时字段，通常为 0/1）。 |
+| `colorIndex` | `number` | 颜色索引 (0–15)。 |
+| `fillIndex` | `number` | 填充类型。 |
+
+### 只读属性
+
+| 属性 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `noteId` | `string` | 笔记唯一 ID。 |
+| `docMd5` | `string` | 来源文档 MD5。 |
+| `notebookId` | `string` | 所属笔记本 ID。 |
+| `startPage` / `endPage` | `NSNumber` | 摘录起止页码。 |
+| `startPos` / `endPos` | `string` | 摘录起止位置。 |
+| `excerptPic` | `NSDictionary` | 摘录图片信息。 |
+| `createDate` / `modifiedDate` | `NSDate` | 创建/修改时间。 |
+| `mediaList` | `string` | 媒体列表。 |
+| `originNoteId` | `string` | 原始笔记 ID（如 Evernote）。 |
+| `mindmapBranchClose` | `NSNumber` | 脑图分支是否折叠。 |
+| `notesText` | `string` | 笔记文本聚合。 |
+| `groupNoteId` | `string` | 分组笔记 ID。 |
+| `comments` | `NSArray` | 评论数组，元素为 [NoteComment](/reference/marginnote/note-comment/) 结构。 |
+| `parentNote` | `MbBookNote` \| undefined | 父笔记。 |
+| `childMindMap` | `MbBookNote` \| undefined | 子脑图（getter 为 parentDraft）。 |
+| `linkedNotes` | `NSArray` | 链接的笔记。 |
+| `childNotes` | `NSArray` | 子笔记数组。 |
+| `summaryLinks` | `NSArray` | 摘要链接。 |
+| `zLevel` / `hidden` / `toc` / `annotation` / `textFirst` / `groupMode` / `flashcard` / `flagged` | `NSNumber` | 各类标志。 |
+| `summary` | `boolean` | 是否有摘要链接（getter hasSummaryLinks）。 |
+| `textHighlight` / `options` | `NSDictionary` | 文本高亮与选项。 |
+
+### 实例方法
+
+### `appendTextComment`
+
+添加一条文本评论。
+
+```javascript
+appendTextComment(text: string): void
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+| :--- | :--- | :--- |
+| `text` | `string` | 评论内容。 |
+
+### `appendMarkdownComment`
+
+添加一条 Markdown 格式评论。
+
+```javascript
+appendMarkdownComment(text: string): void
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+| :--- | :--- | :--- |
+| `text` | `string` | Markdown 格式的评论内容。 |
+
+### `appendNoteLink`
+
+添加指向另一条笔记的链接。
+
+```javascript
+appendNoteLink(note: MbBookNote): void
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+| :--- | :--- | :--- |
+| `note` | `MbBookNote` | 目标笔记对象。 |
+
+**说明**：会在 `comments` 数组中添加一条 `TextNote` 类型的评论，`text` 字段存储格式为 `marginnote4app://note/{noteId}`。
+
+### `merge`
+
+添加笔记链接（历史命名；等价于“把另一条笔记作为链接加入 comments”）。
+
+```javascript
+merge(note: MbBookNote): void
+```
+
+### `appendHtmlComment`
+
+添加 HTML 评论（已废弃，建议使用 `appendMarkdownComment`）。
+
+```javascript
+appendHtmlComment(html: string, text: string, size: CGSize, tag: string): void
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+| :--- | :--- | :--- |
+| `html` | `string` | HTML 内容。 |
+| `text` | `string` | 纯文本内容（用于搜索等）。 |
+| `size` | `CGSize` | 渲染尺寸。 |
+| `tag` | `string` | 标签标识。 |
+
+**说明**：此方法已废弃，HTML 评论不再单独存储，建议使用 `appendMarkdownComment` 替代。
+
+### `removeCommentByIndex`
+
+按索引删除一条评论。
+
+```javascript
+removeCommentByIndex(index: number): void
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+| :--- | :--- | :--- |
+| `index` | `number` | 评论在 `comments` 数组中的索引。 |
+
+### `clearFormat`
+
+清除笔记文本格式。
+
+```javascript
+clearFormat(): void
+```
+
+### `paste`
+
+粘贴（将剪贴板内容作为评论或摘录）。
+
+```javascript
+paste(): void
+```
+
+### `allNoteText`
+
+获取笔记全部文本（标题+摘录+评论）。
+
+```javascript
+allNoteText(): string
+```
+
+**Return Value:**
+
+- `string`: 聚合文本。
+
+## 类成员 (Class members)
+
+### `createWithTitleNotebookDocument`
+
+创建新笔记（类方法）。在 JS 侧通常通过全局注入的 `Note` 对象调用同名方法。
+
+```javascript
+static createWithTitleNotebookDocument(title: string, notebook: MbTopic, document: MbBook): MbBookNote
+```
+
+## 创建笔记
+
+创建新笔记的方法**不在** `MbBookNote` 类上，而是在全局注入的 `Note` 对象上：
+
+- [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/)
+- [教程：笔记与数据库](/guides/notes-and-database/)

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

@@ -0,0 +1,35 @@
+---
+title: MbBook
+description: 文档对象，代表一个 PDF/EPUB 文档。
+---
+
+代表一个已加入 MarginNote 的文档（如 PDF、EPUB）。通过 [Database.getDocumentById](/reference/global/database/)、[Database.allDocuments](/reference/global/database/)、或 [DocumentController.document](/reference/marginnote/document-controller/) 获取。
+
+## 实例成员 (Instance members)
+
+### 属性（只读）
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `docMd5` | `string` | 文档唯一 MD5（getter 为 md5real）。 |
+| `docTitle` | `string` | 文档标题（getter 为 bookTitle）。 |
+| `pathFile` | `string` | 文档在 MarginNote 存储中的相对路径。 |
+| `fullPathFileName` | `string` | 文档的完整路径（若环境可用）。 |
+| `currentTopicId` | `string` | 当前所属笔记本 ID（getter 为 currenttopicid）。 |
+| `lastVisit` | `NSDate` | 最后访问时间。 |
+| `pageCount` | `number` | 总页数。 |
+
+### 实例方法
+
+| 方法 | 参数 | 返回值 | 说明 |
+|------|------|--------|------|
+| `textContentsForPageNo(pageNo)` | pageNo: number | `NSArray` | 获取指定页的文本内容（实现/结构依赖运行时）。 |
+| `tocAll()` | — | `NSArray` | 获取文档目录（Table of Contents）。 |
+
+## 类成员 (Class members)
+
+当前运行时未额外暴露 `MbBook` 的类成员。
+
+## 相关
+
+- [Database](/reference/global/database/)、[DocumentController](/reference/marginnote/document-controller/)、[MbTopic](/reference/marginnote/mb-topic/)

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

@@ -0,0 +1,66 @@
+---
+title: MbModelTool
+description: 数据库工具协议，Database 单例的实现类型，提供笔记/笔记本/文档的增删改查与导入导出。
+---
+
+`Database.sharedInstance()` 返回的对象即实现 `MbModelTool` 协议的单例。API 与 [Database](/reference/global/database/) 一致，本页列出完整方法签名便于对照原生接口。
+
+## 实例成员 (Instance members)
+
+### 查询与列表
+
+| 方法 | 说明 |
+|------|------|
+| `getNoteById(noteId)` | 根据笔记 ID 获取 `MbBookNote`。 |
+| `getNotebookById(topicId)` | 根据笔记本 ID 获取 `MbTopic`。 |
+| `getDocumentById(docMd5)` | 根据文档 MD5 获取 `MbBook`。 |
+| `getMediaByHash(hash)` | 根据媒体哈希获取 `NSData`。 |
+| `getFlashcardByNoteId(noteId, topicId)` / `getFlashcardsByNoteId(noteId)` / `hasFlashcardByNoteId(noteId)` | 闪卡相关查询。 |
+| `allNotebooks()` / `allDocuments()` | 获取所有笔记本/文档。 |
+
+### 持久化、同步与归档
+
+| 方法 | 说明 |
+|------|------|
+| `savedb()` | 手动保存数据库。 |
+| `setNotebookSyncDirty(topicid)` | 将笔记本标记为同步脏。 |
+| `saveHistoryArchiveKey(topicid, key)` / `loadHistoryArchiveKey(topicid, key)` | 历史归档。 |
+
+### 删除、创建与克隆
+
+| 方法 | 说明 |
+|------|------|
+| `deleteBookNote(noteId)` | 删除单条笔记（不删子节点）。 |
+| `deleteBookNoteTree(noteId)` | 删除笔记及其所有后代。 |
+| `createNoteWithTitleTopicid(title, topicid)` | 在指定笔记本创建新笔记。 |
+| `cloneNotesToTopic(notes, topicid)` | 将笔记克隆到指定笔记本。 |
+| `cloneNotesToFlashcardsToTopic(notes, topicid)` | 将笔记克隆为闪卡到指定笔记本。 |
+
+### 导入导出
+
+| 方法 | 说明 |
+|------|------|
+| `exportNotebookStorePath(topicid, storePath)` | 导出笔记本到路径。 |
+| `importNotebookFromStorePathMerge(storePath, merge)` | 从路径导入笔记本（可选择合并）。 |
+
+### 草稿/手写（Sketch）
+
+| 方法 | 说明 |
+|------|------|
+| `getSketchNoteForMindMapFocusNoteId(topicid, focusNoteId)` | 获取脑图草稿笔记。 |
+| `getSketchNoteForDocumentMd5Page(topicid, md5, page)` | 获取指定文档页的草稿笔记。 |
+| `getSketchNotesForDocumentMd5Page(topicid, md5, page)` | 获取指定文档页的草稿笔记列表。 |
+| `getSketchNotesForMindMap(topicid)` | 获取脑图草稿笔记列表。 |
+
+## 类成员 (Class members)
+
+### 类方法
+
+| 方法 | 说明 |
+|------|------|
+| `sharedInstance()` | 获取单例（通常通过全局对象 [Database](/reference/global/database/) 使用）。 |
+| `transDictionaryToJSCompatible(dic)` / `transArrayToJSCompatible(arr)` | 将原生容器转换为更易于 JS 使用的结构（按运行时实现）。 |
+
+## 相关
+
+- [Database](/reference/global/database/) — 使用同一单例的入口文档

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

@@ -0,0 +1,36 @@
+---
+title: MbTopic
+description: 笔记本（主题）对象，包含根笔记列表与关联文档。
+---
+
+代表一个笔记本（主题）。通过 [Database.getNotebookById](/reference/global/database/)、[Database.allNotebooks](/reference/global/database/)、或控制器上下文获取。
+
+## 实例成员 (Instance members)
+
+### 属性
+
+| 属性 | 类型 | R/W | 说明 |
+|------|------|-----|------|
+| `topicId` | `string` | R | 笔记本唯一 ID。 |
+| `title` | `string` | R/W | 笔记本标题（setter 为 setTopicTitle）。 |
+| `lastVisit` | `NSDate` | R | 最后访问时间。 |
+| `mainDocMd5` | `string` | R | 主文档 MD5（getter 为 localbookmd5）。 |
+| `historyDate` | `NSDate` | R | 历史日期。 |
+| `syncMode` | `NSNumber` | R | 同步模式。 |
+| `categoryList` | `string` | R | 分类列表（getter 为 taglist）。 |
+| `hashtags` | `string` | R | 标签。 |
+| `docList` | `string` | R | 文档列表（getter 为 booklist）。 |
+| `options` | `NSDictionary` | R | 选项。 |
+| `documents` | `NSArray` | R | 关联文档数组（getter 为 books）。 |
+| `notes` | `NSArray` | R | 笔记本中所有**根节点**笔记。 |
+| `hideLinksInMindMapNode` | `boolean` | R/W | 是否在脑图节点中隐藏链接。 |
+| `flags` | `NSNumber` | R | 标志位。 |
+| `type` | `NSNumber` | R | 笔记本类型（例如卡片/脑图/文档等，具体枚举以运行时为准）。 |
+
+## 类成员 (Class members)
+
+当前运行时未额外暴露 `MbTopic` 的类成员。
+
+## 相关
+
+- [Database](/reference/global/database/)、[MbBookNote](/reference/marginnote/mb-book-note/)、[MbBook](/reference/marginnote/mb-book/)

package/src/content/docs/reference/marginnote/mindmap-node.md

@@ -0,0 +1,27 @@
+---
+title: MindMapNode
+description: 脑图中的单个节点，关联一条 MbBookNote 与父子节点、位置。
+---
+
+代表脑图中的一个节点，与一条 [MbBookNote](/reference/marginnote/mb-book-note/) 一一对应。通过 `MindMapView.mindmapNodes` 或选中列表 `selViewLst` 中的项获取。
+
+## 实例成员 (Instance members)
+
+### 属性（只读）
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `note` | `MbBookNote` | 该节点关联的笔记对象。 |
+| `parentNode` | `MindMapNode` \| undefined | 父节点（getter 为 parentNote，类型为 MindMapNote）。 |
+| `childNodes` | `NSArray` | 子节点数组（getter 为 childNotes）。 |
+| `summaryLinks` | `NSArray` | 摘要链接。 |
+| `frame` | `CGRect` | 节点在脑图视图中的位置与大小。 |
+
+## 类成员 (Class members)
+
+当前运行时未额外暴露 `MindMapNode` 的类成员。
+
+## 相关
+
+- [MindMapView](/reference/marginnote/mindmap-view/)
+- [MbBookNote](/reference/marginnote/mb-book-note/)

package/src/content/docs/reference/marginnote/mindmap-view.md

@@ -0,0 +1,24 @@
+---
+title: MindMapView
+description: 脑图视图，继承自 UIScrollView，展示脑图节点列表与选中项。
+---
+
+脑图视图，通过 `NotebookController.mindmapView` 获取。它的行为与 `UIScrollView` 接近（可滚动/缩放），但额外暴露了脑图节点列表与选中项。
+
+## 实例成员 (Instance members)
+
+### 属性（只读）
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `mindmapNodes` | `NSArray` | 脑图中所有节点（MindMapNode 或等价类型）。 |
+| `selViewLst` | `NSArray` | 当前选中的节点视图列表，每项通常包含 `note`（MindMapNode）与 `view`（UIView）。 |
+
+## 类成员 (Class members)
+
+当前运行时未额外暴露 `MindMapView` 的类成员。
+
+## 相关
+
+- [NotebookController](/reference/marginnote/notebook-controller/)
+- [MindMapNode](/reference/marginnote/mindmap-node/)

package/src/content/docs/reference/marginnote/note-comment.md

@@ -0,0 +1,29 @@
+---
+title: NoteComment
+description: 笔记评论条目的类型说明，comments 数组中的元素结构。
+---
+
+`MbBookNote.comments` 是评论数组，每项为具有 `type` 属性的对象，根据类型不同包含不同字段。
+
+## 实例成员 (Instance members)
+
+### 类型与结构
+
+| type | 说明 | 其他字段 |
+|------|------|----------|
+| `TextNote` | 文本评论（包括纯文本、Markdown、链接笔记） | `text`: string，`markdown`: boolean（可选，是否为 Markdown 格式） |
+| `PaintNote` | 手写/图片评论 | `paint`: string（媒体哈希，可用 Database.getMediaByHash 取数据） |
+
+**说明**：
+- 所有文本类评论（纯文本、Markdown、链接笔记）现在统一为 `TextNote` 类型
+- Markdown 评论通过 `markdown: true` 字段标识
+- 链接笔记的 `text` 字段存储格式为 `marginnote4app://note/{noteId}`
+
+## 类成员 (Class members)
+
+`NoteComment` 是数据结构说明，不以类成员形式使用。
+
+## 相关
+
+- [MbBookNote](/reference/marginnote/mb-book-note/) — `comments`、`appendTextComment`、`appendNoteLink`、`removeCommentByIndex`
+- [Database.getMediaByHash](/reference/global/database/) — 用于 PaintNote 的图片数据

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

@@ -0,0 +1,36 @@
+---
+title: NotebookController
+description: 脑图与大纲的控制器，提供当前笔记本与焦点笔记。
+---
+
+管理脑图和大纲的控制器，通过 `StudyController.notebookController` 获取。
+
+## 实例成员 (Instance members)
+
+### 属性（只读）
+
+| 属性 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `mindmapView` | `MindMapView` | 脑图视图（getter 为 noteMindMap）。 |
+| `outlineView` | `OutlineView` | 大纲视图。 |
+| `notebookId` | `string` | 当前笔记本 ID（getter 为 currTopic）。 |
+| `focusNote` | `MbBookNote` \| undefined | 当前在脑图中聚焦的笔记。 |
+| `visibleFocusNote` | `MbBookNote` \| undefined | 当前可见的焦点笔记。 |
+| `view` | `UIView` | 控制器视图（继承自 UIViewController）。 |
+
+说明：该对象具备 `UIViewController` 的基础能力，并额外提供“脑图视图/大纲视图/当前笔记本”等状态入口。
+
+### 方法
+
+| 方法 | 参数 | 返回值 | 说明 |
+|------|------|--------|------|
+| `changeFocusToNote(note)` | note: `MbBookNote` | — | 将焦点切换到指定笔记。 |
+
+## 类成员 (Class members)
+
+当前运行时未额外暴露 `NotebookController` 的类成员。
+
+## 相关
+
+- [StudyController](/reference/marginnote/study-controller/)
+- [MindMapView](/reference/marginnote/mindmap-view/)、[MindMapNode](/reference/marginnote/mindmap-node/)