mn-docs-mcp 0.1.0

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

@@ -0,0 +1,395 @@
+---
+title: Database
+description: MarginNote 核心数据库访问对象（MbModelTool），用于获取/修改笔记、笔记本与文档。
+---
+
+`Database` 即底层类型 `MbModelTool` 的单例，用于访问 MarginNote 的笔记与文档数据。通过 `Database.sharedInstance()` 获取。修改数据后建议使用 [UndoManager](/reference/utility/undo-manager/) 的 `undoGrouping(title, topicid, fn)` 包裹，并调用 `Application.sharedInstance().refreshAfterDBChanged(topicid)` 刷新界面。
+
+## 类成员 (Class members)
+
+### `sharedInstance`
+
+获取全局唯一的数据库工具实例。
+
+```javascript
+static sharedInstance(): MbModelTool
+```
+
+**Return Value:**
+
+- `MbModelTool`: 数据库工具单例。
+
+## 实例成员 (Instance members)
+
+### 方法
+
+### `getNoteById`
+
+根据笔记 ID 获取笔记。
+
+```javascript
+getNoteById(noteId: string): MbBookNote | undefined
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+| :--- | :--- | :--- |
+| `noteId` | `string` | 笔记唯一 ID。 |
+
+**Return Value:**
+
+- `MbBookNote | undefined`: 对应的笔记对象，若不存在则返回 undefined。
+
+### `getNotebookById`
+
+根据笔记本 ID 获取笔记本。
+
+```javascript
+getNotebookById(topicId: string): MbTopic | undefined
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+| :--- | :--- | :--- |
+| `topicId` | `string` | 笔记本 ID。 |
+
+**Return Value:**
+
+- `MbTopic | undefined`: 对应的笔记本对象。
+
+### `getDocumentById`
+
+根据文档 MD5 获取文档。
+
+```javascript
+getDocumentById(docMd5: string): MbBook | undefined
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+| :--- | :--- | :--- |
+| `docMd5` | `string` | 文档 MD5。 |
+
+**Return Value:**
+
+- `MbBook | undefined`: 对应的文档对象。
+
+### `getMediaByHash`
+
+根据媒体哈希获取二进制数据。
+
+```javascript
+getMediaByHash(hash: string): NSData | undefined
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+| :--- | :--- | :--- |
+| `hash` | `string` | 媒体哈希字符串。 |
+
+**Return Value:**
+
+- `NSData | undefined`: 媒体数据。
+
+### `getFlashcardByNoteId`
+
+按 Evernote 笔记 ID 与笔记本获取闪卡（笔记）。
+
+```javascript
+getFlashcardByNoteId(noteId: string, topicId: string): MbBookNote | undefined
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+| :--- | :--- | :--- |
+| `noteId` | `string` | 原始笔记 ID (Evernote ID)。 |
+| `topicId` | `string` | 笔记本 ID。 |
+
+**Return Value:**
+
+- `MbBookNote | undefined`: 对应的闪卡笔记。
+
+### `getFlashcardsByNoteId`
+
+按 Evernote 笔记 ID 获取所有关联闪卡。
+
+```javascript
+getFlashcardsByNoteId(noteId: string): NSArray
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+| :--- | :--- | :--- |
+| `noteId` | `string` | 原始笔记 ID。 |
+
+**Return Value:**
+
+- `NSArray`: 包含 `MbBookNote` 的数组。
+
+### `hasFlashcardByNoteId`
+
+是否存在该 Evernote 笔记的闪卡。
+
+```javascript
+hasFlashcardByNoteId(noteId: string): boolean
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+| :--- | :--- | :--- |
+| `noteId` | `string` | 原始笔记 ID。 |
+
+**Return Value:**
+
+- `boolean`: 是否存在。
+
+### `allNotebooks`
+
+获取所有笔记本。
+
+```javascript
+allNotebooks(): NSArray
+```
+
+**Return Value:**
+
+- `NSArray`: 包含所有 `MbTopic` 的数组。
+
+### `allDocuments`
+
+获取所有文档。
+
+```javascript
+allDocuments(): NSArray
+```
+
+**Return Value:**
+
+- `NSArray`: 包含所有 `MbBook` 的数组。
+
+### `savedb`
+
+手动保存数据库到磁盘。慎用，通常由系统自动管理。
+
+```javascript
+savedb(): void
+```
+
+### `setNotebookSyncDirty`
+
+将笔记本标记为同步脏（需要同步）。
+
+```javascript
+setNotebookSyncDirty(topicid: string): void
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+| :--- | :--- | :--- |
+| `topicid` | `string` | 笔记本 ID。 |
+
+### `saveHistoryArchiveKey`
+
+保存历史归档。
+
+```javascript
+saveHistoryArchiveKey(topicid: string, key: string): NSArray
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+| :--- | :--- | :--- |
+| `topicid` | `string` | 笔记本 ID。 |
+| `key` | `string` | 归档键名。 |
+
+**Return Value:**
+
+- `NSArray`: 归档数据。
+
+### `loadHistoryArchiveKey`
+
+加载历史归档。
+
+```javascript
+loadHistoryArchiveKey(topicid: string, key: string): NSArray
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+| :--- | :--- | :--- |
+| `topicid` | `string` | 笔记本 ID。 |
+| `key` | `string` | 归档键名。 |
+
+**Return Value:**
+
+- `NSArray`: 归档数据。
+
+### `deleteBookNote`
+
+删除单条笔记（不删子节点）。
+
+```javascript
+deleteBookNote(noteId: string): void
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+| :--- | :--- | :--- |
+| `noteId` | `string` | 笔记 ID。 |
+
+### `deleteBookNoteTree`
+
+删除笔记及其所有后代。
+
+```javascript
+deleteBookNoteTree(noteId: string): void
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+| :--- | :--- | :--- |
+| `noteId` | `string` | 笔记 ID。 |
+
+### `cloneNotesToTopic`
+
+将笔记克隆到指定笔记本。
+
+```javascript
+cloneNotesToTopic(notes: NSArray, topicid: string): NSArray
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+| :--- | :--- | :--- |
+| `notes` | `NSArray` | `MbBookNote` 数组。 |
+| `topicid` | `string` | 目标笔记本 ID。 |
+
+**Return Value:**
+
+- `NSArray`: 克隆后的新笔记数组。
+
+### `cloneNotesToFlashcardsToTopic`
+
+将笔记克隆为闪卡到指定笔记本。
+
+```javascript
+cloneNotesToFlashcardsToTopic(notes: NSArray, topicid: string): NSArray
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+| :--- | :--- | :--- |
+| `notes` | `NSArray` | `MbBookNote` 数组。 |
+| `topicid` | `string` | 目标笔记本 ID。 |
+
+**Return Value:**
+
+- `NSArray`: 克隆后的新笔记数组。
+
+### `exportNotebookStorePath`
+
+导出笔记本。
+
+```javascript
+exportNotebookStorePath(topicid: string, storePath: string): boolean
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+| :--- | :--- | :--- |
+| `topicid` | `string` | 笔记本 ID。 |
+| `storePath` | `string` | 导出路径。 |
+
+**Return Value:**
+
+- `boolean`: 是否成功。
+
+### `importNotebookFromStorePathMerge`
+
+从路径导入笔记本。
+
+```javascript
+importNotebookFromStorePathMerge(storePath: string, merge: boolean): any
+```
+
+### `createNoteWithTitleTopicid`
+
+在指定笔记本创建新笔记。
+
+```javascript
+createNoteWithTitleTopicid(title: string, topicid: string): MbBookNote
+```
+
+### `getSketchNoteForMindMapFocusNoteId`
+
+获取脑图草稿笔记（Sketch）。
+
+```javascript
+getSketchNoteForMindMapFocusNoteId(topicid: string, focusNoteId: string): MbBookNote
+```
+
+### `getSketchNoteForDocumentMd5Page`
+
+获取指定文档页的草稿笔记（Sketch）。
+
+```javascript
+getSketchNoteForDocumentMd5Page(topicid: string, md5: string, page: number): MbBookNote
+```
+
+### `getSketchNotesForDocumentMd5Page`
+
+获取指定文档页的草稿笔记列表（Sketch）。
+
+```javascript
+getSketchNotesForDocumentMd5Page(topicid: string, md5: string, page: number): NSArray
+```
+
+### `getSketchNotesForMindMap`
+
+获取脑图草稿笔记列表（Sketch）。
+
+```javascript
+getSketchNotesForMindMap(topicid: string): NSArray
+```
+
+## 兼容性工具（类方法）
+
+### `transDictionaryToJSCompatible` / `transArrayToJSCompatible`
+
+将原生容器转换为更易于 JS 使用的结构（行为以运行时实现为准）。
+
+```javascript
+static transDictionaryToJSCompatible(dic: NSDictionary): NSDictionary
+static transArrayToJSCompatible(arr: NSArray): NSArray
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+| :--- | :--- | :--- |
+| `storePath` | `string` | 导入文件路径。 |
+| `merge` | `boolean` | 是否合并。 |
+
+**Return Value:**
+
+- `any`: 导入结果（通常为导入的笔记本对象或状态）。
+
+## 相关
+
+- [MbBookNote](/reference/marginnote/mb-book-note/)、[MbTopic](/reference/marginnote/mb-topic/)、[MbBook](/reference/marginnote/mb-book/)
+- [教程：笔记与数据库](/guides/notes-and-database/)

package/src/content/docs/reference/global/global-variables.md

@@ -0,0 +1,32 @@
+---
+title: 全局入口对象（Global Variables）
+description: MarginNote 插件运行时直接注入到 JS 环境的全局变量清单与用法入口。
+---
+
+本页列出 **MarginNote 插件运行时可直接使用的全局变量名**（你在 JS 里直接输入即可访问）。这些全局名对应的对象通常是 **单例**、**工厂对象**、或 **系统级入口**。
+
+> 说明：本页仅做“可发现性索引”。每个对象的完整属性/方法请进入对应参考页。
+
+## 全局变量清单
+
+| 全局变量名 | 对应原生类/说明 | 核心用途 | 参考 |
+| :--- | :--- | :--- | :--- |
+| `JSB` | Bridge | 定义类、日志输出、require | [JSB](/reference/global/jsb/) |
+| `self` | `JSExtension` 实例 | 当前插件实例（仅实例方法内可用） | [self](/reference/global/self/) |
+| `Application` | `JSBApplication` | App 全局单例：路径、HUD、openURL、studyController | [Application](/reference/global/application/) |
+| `Database` | `MbModelTool` 单例 | 笔记/笔记本/文档数据库访问 | [Database](/reference/global/database/) |
+| `Note` | 笔记工厂（全局） | 创建新笔记：`Note.createWithTitleNotebookDocument(...)` | [Note](/reference/global/note/) |
+| `UndoManager` | `JSBUndoManager` 单例 | undoGrouping/撤销重做 | [UndoManager](/reference/utility/undo-manager/) |
+| `SpeechManager` | `JSBSpeechManager` 单例 | 语音朗读 | [SpeechManager](/reference/utility/speech-manager/) |
+| `ZipArchive` | `JSBZipArchive` | zip 压缩/解压 | [ZipArchive](/reference/utility/zip-archive/) |
+| `MenuController` | 菜单控制器（全局） | 表格化菜单视图 | [MenuController](/reference/utility/menu-controller/) |
+| `PopupMenu` | 弹出菜单（全局） | 轻量弹出菜单 | [PopupMenu](/reference/global/popup-menu/) |
+| `PopupMenuItem` | 弹出菜单项（全局） | 菜单项对象 | [PopupMenuItem](/reference/global/popup-menu-item/) |
+| `SQLiteDatabase` | `JSBSQLiteDatabase` | SQLite 连接器 | [SQLiteDatabase](/reference/utility/sqlite-database/) |
+| `NSFileManager` | `NSFileManager` 单例 | 文件管理 | [NSFileManager](/reference/foundation/ns-file-manager/)（待补齐：全量接口） |
+| `NSUserDefaults` | `NSUserDefaults` 单例 | 偏好设置存储 | [NSUserDefaults](/reference/foundation/ns-user-defaults/) |
+| `NSNotificationCenter` | `NSNotificationCenter` 单例 | 通知中心 | [NSNotificationCenter](/reference/foundation/ns-notification-center/) |
+| `UIApplication` | `UIApplication` 单例 | iOS 应用级入口（openURL 等） | [UIApplication](/reference/uikit/uiapplication/) |
+| `UIPasteboard` | `UIPasteboard` 单例 | 系统剪贴板 | [UIPasteboard](/reference/uikit/uipasteboard/) |
+| `UIDevice` | `UIDevice` 单例 | 设备信息 | [UIDevice](/reference/uikit/uidevice/) |
+| `UIScreen` | `UIScreen` 单例 | 屏幕信息 | [UIScreen](/reference/uikit/uiscreen/) |

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

@@ -0,0 +1,89 @@
+---
+title: JSB
+description: JavaScript 桥接核心，连接插件 JS 与运行时对象的入口对象。
+---
+
+JSB（JavaScript Bridge）是插件运行时的桥接核心对象：类定义、插件入口、日志与包内脚本加载都通过它完成。
+
+## 实例成员 (Instance members)
+
+`JSB` 是全局对象，通常不以“实例化”的方式使用。
+
+## 类成员 (Class members)
+
+### 方法
+
+### `defineClass`
+
+定义一个可被运行时识别并回调的类，**所有插件的入口**。
+
+```javascript
+defineClass(declaration: string, instanceMembers: object, classMembers?: object): any
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+| :--- | :--- | :--- |
+| `declaration` | `string` | 类声明，例如 `'MyAddon : JSExtension'`。 |
+| `instanceMembers` | `object` | 实例方法与属性的集合。在此对象中定义的方法/属性在**实例**上调用（如 `sceneWillConnect`、`notebookWillOpen`、`queryAddonCommandStatus` 等）。 |
+| `classMembers` | `object?` | 类方法与属性的集合。在此对象中定义的方法在**类**上调用（如 `addonDidConnect`）。 |
+
+**Return Value:**
+
+- `any`: 类构造器。
+
+### `newAddon`
+
+**插件入口函数**。MarginNote 加载插件时调用，你必须实现并返回插件类。
+
+```javascript
+newAddon(mainPath: string): any
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+| :--- | :--- | :--- |
+| `mainPath` | `string` | 插件包根目录路径。 |
+
+**Return Value:**
+
+- `any`: 必须返回由 `defineClass` 创建的类（构造器）。注意：是类本身，不是实例。
+
+### `log`
+
+向 MarginNote 控制台输出日志，类似 `console.log`。
+
+```javascript
+log(format: string, ...args: any[]): void
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+| :--- | :--- | :--- |
+| `format` | `string` | 格式化字符串，支持 `%@`、`%d` 等 Objective-C 格式。 |
+| `...args` | `any[]` | 对应格式化字符串的参数。 |
+
+### `require`
+
+加载插件包内其他 JS 文件。
+
+```javascript
+require(name: string): void
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+| :--- | :--- | :--- |
+| `name` | `string` | 插件包内 JS 文件路径/文件名。 |
+
+**Note:**
+无模块作用域，所有文件共享全局作用域；推荐使用 Webpack 等打包工具。
+
+## 说明
+
+- 插件主类必须通过 `JSB.defineClass('MyAddon : JSExtension', instanceMembers, classMembers)` 定义，并在全局实现 `JSB.newAddon = function(mainPath) { return MyAddon; }`（或等价形式）。
+- 参见 [JSExtension](/reference/marginnote/jsextension/) 了解生命周期方法，[快速开始](/guides/getting-started/) 了解完整示例。

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

@@ -0,0 +1,64 @@
+---
+title: Note
+description: 全局注入的笔记工厂对象，用于创建新笔记（MbBookNote）。
+---
+
+`Note` 是 MarginNote 运行时注入到 JavaScript 环境中的**全局对象**之一，用于创建新笔记。
+
+需要特别注意：创建笔记的方法**不在** `MbBookNote` 类上，而是在全局 `Note` 对象上（这是由 MarginNote 的 JSExport 导出方式决定的）。
+
+## 实例成员 (Instance members)
+
+`Note` 是全局对象，通常不以实例形式使用。
+
+## 类成员 (Class members)
+
+### 方法
+
+### `createWithTitleNotebookDocument`
+
+在指定笔记本与文档下创建一条新笔记。
+
+```javascript
+createWithTitleNotebookDocument(title: string, notebook: MbTopic, doc: MbBook): MbBookNote
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+| :--- | :--- | :--- |
+| `title` | `string` | 笔记标题。 |
+| `notebook` | `MbTopic` | 所属笔记本（Topic）。 |
+| `doc` | `MbBook` | 来源文档（Book）。 |
+
+**Return Value:**
+
+- `MbBookNote`: 创建成功的新笔记对象。
+
+### 示例
+
+```javascript
+var db = Database.sharedInstance();
+var notebook = db.getNotebookById("NOTEBOOK_ID");
+var doc = db.getDocumentById("DOC_MD5");
+
+if (notebook && doc) {
+  var topicid = notebook.topicId || notebook.topicid; // 兼容不同 getter 命名
+  UndoManager.sharedInstance().undoGrouping(
+    "创建笔记",
+    topicid,
+    function () {
+      var note = Note.createWithTitleNotebookDocument("新笔记", notebook, doc);
+      // note 为 MbBookNote
+    }
+  );
+  Application.sharedInstance().refreshAfterDBChanged(topicid);
+}
+```
+
+## 相关
+
+- [Database](/reference/global/database/) — 获取 notebook/doc
+- [MbTopic](/reference/marginnote/mb-topic/)、[MbBook](/reference/marginnote/mb-book/)
+- [MbBookNote](/reference/marginnote/mb-book-note/) — 创建结果类型
+- [UndoManager](/reference/utility/undo-manager/)

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

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

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

@@ -0,0 +1,38 @@
+---
+title: PopupMenu
+description: 轻量弹出菜单视图（全局注入），用于展示一组 PopupMenuItem。
+---
+
+`PopupMenu` 是运行时注入的全局类（对应原生 QBPopupMenu）。常用于在指定 rect 附近弹出一组菜单项。
+
+## 类成员 (Class members)
+
+| 方法 | 参数 | 返回值 | 说明 |
+|---|---|---|---|
+| `currentMenu()` | — | `PopupMenu \| null` | 获取当前显示的菜单（若有）。 |
+| `popupMenuWithItems(items)` | items: `NSArray` | `PopupMenu` | 用 items 创建菜单实例。 |
+
+## 实例成员 (Instance members)
+
+### 属性
+
+| 属性 | 类型 | 说明 |
+|---|---|---|
+| `visible` | `boolean` | 是否可见。 |
+| `items` | `NSArray` | 菜单项列表。 |
+| `arrowDirection` | `number` | 箭头方向（枚举值以运行时为准）。 |
+| `targetWinRect` | `CGRect` | 目标窗口 rect（只读）。 |
+
+### 方法
+
+| 方法 | 参数 | 返回值 | 说明 |
+|---|---|---|---|
+| `showInViewTargetRectAnimated(view, targetRect, animated)` | view: `UIView`, targetRect: `CGRect`, animated: boolean | — | 在 view 中显示。 |
+| `updateWithTargetRect(targetRect)` | targetRect: `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

@@ -0,0 +1,51 @@
+---
+title: SearchManager
+description: 搜索与索引管理器（全文检索、URL 搜索、相似笔记检索等）。
+---
+
+`SearchManager` 通过 `Application.sharedInstance().searchManager` 获取。其返回结构与索引能力会随版本变化；建议先在控制台打印返回值结构再做兼容处理。
+
+## 实例成员 (Instance members)
+
+### 属性（只读）
+
+| 属性 | 类型 | 说明 |
+|---|---|---|
+| `ftsIndexing` | `boolean` | FTS 索引是否正在构建/工作中。 |
+| `propIndexing` | `boolean` | 属性索引是否正在构建/工作中。 |
+| `vectorIndexing` | `boolean` | 向量索引是否正在构建/工作中。 |
+
+### 常用搜索
+
+| 方法 | 说明 |
+|---|---|
+| `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)` | 页内搜索（实现依赖运行时）。 |
+| `snippetForFts3RowId(rowid)` / `snippetForPageRowId(rowid)` | 获取 snippet（结果摘要）。 |
+
+### 同步与索引
+
+| 方法 | 说明 |
+|---|---|
+| `syncTopicForceBlock(topicid, force, block)` | 同步/构建指定笔记本的索引（block 为回调）。 |
+| `syncDB()` / `syncDBAfterMigration()` | 同步索引数据库。 |
+| `hasTopicIndex(topicid)` / `hasVectorIndex(topicid)` / `hasBookIndex(md5)` | 检查索引是否存在。 |
+| `resetBookIndex()` | 重置文档索引（慎用）。 |
+
+### 相似检索（向量）
+
+| 方法 | 说明 |
+|---|---|
+| `findSimilarNotes(queryVector, topicId, k)` | 向量相似笔记检索。 |
+| `batchFindSimilarNotes(queryVectors, topicId, k)` | 批量向量相似检索。 |
+| `findSimilarNotesHybrid(queryVector, queryText, topicId, k, semanticWeight, bm25Weight)` | 语义+BM25 混合检索。 |
+| `loadVectorCacheForTopic(topicId)` / `syncTopicVectorsForceCompletion(topicId, force, completion)` / `invalidateVectorCacheForTopics(topicIds)` | 向量缓存相关（实现依赖运行时）。 |
+
+## 相关
+
+- [Application](/reference/global/application/) — `Application.sharedInstance().searchManager`
+