mn-docs-mcp 0.6.2 → 1.1.0

package/src/content/docs/{guides/contributing.md → contributing.md}

@@ -8,12 +8,12 @@ description: 文档贡献流程与格式规范（API 参考、教程、Markdown
 ## 贡献流程
 
 1. **Fork** 本仓库到你的 GitHub 账号。
-2. **创建分支**：从默认分支（如 `main`）拉取新分支，建议命名 `docs/xxx` 或 `fix/typo-xxx`。
+2. **创建分支**：从默认分支（如 `main`）拉取新分支，命名 `docs/xxx` 或 `fix/typo-xxx`。
 3. **修改**：在本地或 GitHub 网页编辑器中修改文档。
 4. **提交并推送**：提交到你的 Fork，推送到 GitHub。
 5. **发起 Pull Request**：在本仓库创建 PR，目标分支为默认分支（如 `main`）。
 
-**PR 描述建议包含**：修改类型（纠错 / 新增教程 / 新增或修订 API 页）、涉及文件或路径、简要说明。
+**PR 描述应包含**：修改类型（纠错 / 新增教程 / 新增或修订 API 页）、涉及文件或路径、简要说明。
 
 ## 文档结构约定
 
@@ -21,7 +21,7 @@ description: 文档贡献流程与格式规范（API 参考、教程、Markdown
   - `guides/`：教程与 Cookbook 配方；
   - `reference/`：API 参考，按 `global`、`marginnote`、`foundation`、`uikit`、`quartzcore`、`utility` 等子目录组织。
 - **新增页面**：参考同类型现有页面。若为 API 参考，需符合下述「API 参考格式」；若为教程或 Cookbook，需符合「教程与指南格式」。
-- **侧栏**：若新增的是 `reference/` 下且位于已配置 `autogenerate` 的目录（如 Foundation、UIKit），侧栏会自动出现；若为 `guides/` 新页或新目录，需在 `astro.config.mjs` 的 `sidebar` 中手动添加对应 `slug`。
+- **侧栏**：新增页面后按需要更新对应目录下的 `meta.json`，以固定Fumadocs侧栏标题与页面顺序。
 
 ## API 参考文档格式规范
 
@@ -36,7 +36,14 @@ description: 文档贡献流程与格式规范（API 参考、教程、Markdown
 
 ### 方法（方法单列）
 
-- 每个方法一个三级标题：`### \`methodName\``。
+- 每个方法一个三级标题，格式如下：
+  ```markdown
+  ### `methodName`
+  ```
+  例如：
+  ```markdown
+  ### `getUser`
+  ```
 - 可选：标题下方一行简短说明。
 - **签名代码块**：使用 ` ```javascript `，内容为方法签名，例如 `static sharedInstance(): Application` 或 `count(): number`，然后 ` ``` `。
 - **Parameters**（若有参数）：
@@ -56,6 +63,24 @@ description: 文档贡献流程与格式规范（API 参考、教程、Markdown
 - 二级标题：`## 类成员 (Class members)`、`## 实例成员 (Instance members)`。
 - 可按需用三级标题分组（如「创建」「查询」），再在其下按上述方法/属性格式书写。
 
+### 构造函数
+
+如有构造函数，需单独列出：
+
+````markdown
+## 构造函数
+
+```javascript
+new ClassName(parameter: Type)
+```
+
+构造函数说明。
+
+| 参数名 | 类型 | 说明 |
+| :----- | :--- | :--- |
+| `parameter` | `Type` | 参数说明 |
+````
+
 ### 相关链接
 
 页面末尾可使用 `## 相关` 列出与本页相关的其他 API 或教程链接（Markdown 链接，如 `[Application](/reference/global/application/)`）。
@@ -76,7 +101,7 @@ description: 文档贡献流程与格式规范（API 参考、教程、Markdown
 - **语言**：文档正文与说明统一使用**简体中文**；API 名称、代码、技术术语保留英文。
 - **标点**：中文句子使用中文标点；英文或代码片段内使用英文标点。
 - **专有名词**：MarginNote、API、JavaScript 等大小写保持一致；首次出现可加简短解释。
-- **链接**：避免裸 URL，使用 `[描述](url)` 或 `[描述](/path/)`；API 交叉引用建议用「相关」小节或正文内链接到对应 reference 页。
+- **链接**：避免裸 URL，使用 `[描述](url)` 或 `[描述](/path/)`；API 交叉引用用「相关」小节或正文内链接到对应 reference 页。
 - **代码块**：标注语言、保持缩进一致；长示例可省略无关部分并用注释说明。
 
-若对某条规范有疑问或建议，欢迎在 Issue 中提出。
+若对某条规范有疑问或改进意见，欢迎在 Issue 中提出。

package/src/content/docs/{guides/cookbook → cookbook}/addon-settings.md

@@ -40,7 +40,7 @@ NSUserDefaults.standardUserDefaults().setObjectForKey(newKey, "my_addon_api_key"
 Application.sharedInstance().showHUD("已保存", self.window, 2);
 ```
 
-若需用该 Key 发起网络请求，可参考 [调用远程 API](/guides/cookbook/network-api-call/) 和 [网络请求](/guides/network-requests/)。保存后可选择调用简单 API 验证 Key 是否有效。
+若需用该 Key 发起网络请求，可参考 [调用远程 API](/cookbook/network-api-call/) 和 [网络请求](/guides/network-requests/)。保存后可选择调用简单 API 验证 Key 是否有效。
 
 **完整流程简述**：
 
@@ -50,4 +50,4 @@ Application.sharedInstance().showHUD("已保存", self.window, 2);
 4. 插件主逻辑（如是否显示面板）在需要时从 NSUserDefaults 读取。
 5. （可选）保存 API Key 后调用简单接口验证是否有效。
 
-**相关**：[存储与文件](/guides/storage-and-files/)、[NSUserDefaults](/reference/foundation/ns-user-defaults/)、[原生 UI](/guides/native-ui/)、[调用远程 API](/guides/cookbook/network-api-call/)
+**相关**：[存储与文件](/guides/storage-and-files/)、[NSUserDefaults](/reference/foundation/ns-user-defaults/)、[原生 UI](/guides/native-ui/)、[调用远程 API](/cookbook/network-api-call/)

package/src/content/docs/{guides/cookbook → cookbook}/embed-webview-panel.md

@@ -5,7 +5,7 @@ description: 从工具栏打开浮窗，浮窗内为 UIWebView，加载本地或
 
 **场景**：用户点击插件工具栏按钮后，在主界面上显示一个浮窗面板，面板内为 [UIWebView](/reference/uikit/uiwebview/)，加载本地或内联 HTML；面板内可通过自定义 URL 触发插件逻辑（如 showHUD），插件也可通过 `evaluateJavaScript` 更新页面内容。
 
-**要点**：浮窗为自定义 ViewController 的 view，在入口中 `JSB.require` 该 ViewController **一次**，在 `sceneWillConnect` 中创建实例；在 ViewController 的 **viewWillAppear** 中设置 `webView.delegate = self`，在 **viewWillDisappear** 中 `webView.stopLoading()` 并 `webView.delegate = null`。加载 HTML 用 `loadHTMLStringBaseURL(html, null)`，加载失败时在 `webViewDidFailLoadWithError` 中用 `error.localizedDescription` 拼 HTML 后用 `loadHTMLStringBaseURL` 显示错误页。双向通信写法见 [WebView 内 JS 与插件 JS 双向通信](/guides/cookbook/webview-bidirectional-js/)。
+**要点**：浮窗为自定义 ViewController 的 view，在入口中 `JSB.require` 该 ViewController **一次**，在 `sceneWillConnect` 中创建实例；在 ViewController 的 **viewWillAppear** 中设置 `webView.delegate = self`，在 **viewWillDisappear** 中 `webView.stopLoading()` 并 `webView.delegate = null`。加载 HTML 用 `loadHTMLStringBaseURL(html, null)`，加载失败时在 `webViewDidFailLoadWithError` 中用 `error.localizedDescription` 拼 HTML 后用 `loadHTMLStringBaseURL` 显示错误页。双向通信写法见 [WebView 内 JS 与插件 JS 双向通信](/cookbook/webview-bidirectional-js/)。
 
 下文给出与 Samples/UIKit/WebView 同构的完整代码：main.js 中挂面板与切换显示，MyWebViewController.js 中创建 WebView、生命周期与 delegate。
 
@@ -154,5 +154,5 @@ var MyWebViewController = JSB.defineClass('MyWebViewController : UIViewControlle
 ## 相关
 
 - [工具栏与命令](/guides/toolbar-and-commands/)、[原生 UI：使用 WebView](/guides/native-ui/#使用-webview)
-- [WebView 内 JS 与插件 JS 双向通信](/guides/cookbook/webview-bidirectional-js/)、[UIWebView](/reference/uikit/uiwebview/)
+- [WebView 内 JS 与插件 JS 双向通信](/cookbook/webview-bidirectional-js/)、[UIWebView](/reference/uikit/uiwebview/)
 - [网络请求](/guides/network-requests/) —— 获取远程数据后注入 HTML 或通过 evaluateJavaScript 注入

package/src/content/docs/cookbook/meta.json

@@ -0,0 +1,13 @@
+{
+  "title": "Cookbook配方",
+  "pages": [
+    "batch-rename-notes",
+    "network-api-call",
+    "export-notebook",
+    "focus-note-in-mindmap",
+    "append-selection-as-comment",
+    "addon-settings",
+    "embed-webview-panel",
+    "webview-bidirectional-js"
+  ]
+}

package/src/content/docs/{guides/cookbook → cookbook}/network-api-call.md

@@ -106,7 +106,7 @@ async function fetchWithAPIKey() {
 }
 ```
 
-API Key 的保存与读取见 [插件设置页](/guides/cookbook/addon-settings/)。保存后可选择调用简单 API 验证 Key 是否有效。
+API Key 的保存与读取见 [插件设置页](/cookbook/addon-settings/)。保存后可选择调用简单 API 验证 Key 是否有效。
 
 ---
 
@@ -131,5 +131,5 @@ async function fetchPlainText() {
 ## 相关
 
 - [网络请求](/guides/network-requests/) —— Base64 与 MNNetwork 完整代码、data 转 JSON/文本说明
-- [插件设置页](/guides/cookbook/addon-settings/) —— 存储 API Key
+- [插件设置页](/cookbook/addon-settings/) —— 存储 API Key
 - [笔记与数据库](/guides/notes-and-database/) —— 修改笔记与 Undo

package/src/content/docs/{guides/cookbook → cookbook}/webview-bidirectional-js.md

@@ -109,4 +109,4 @@ self.webView.evaluateJavaScript("document.getElementById('text').innerText = '
 ## 相关
 
 - [UIWebView](/reference/uikit/uiwebview/)、[原生 UI：使用 WebView](/guides/native-ui/#使用-webview)
-- [Cookbook：在插件中嵌入 WebView 面板](/guides/cookbook/embed-webview-panel/)
+- [Cookbook：在插件中嵌入 WebView 面板](/cookbook/embed-webview-panel/)

package/src/content/docs/guides/getting-started.md

@@ -7,7 +7,7 @@ description: 从零运行你的第一个 MarginNote 插件（Hello World）。
 
 ## 前提
 
-- 已安装 MarginNote 3 或 MarginNote 4（MN3 建议 3.6.11 及以上）。
+- 已安装 MarginNote 3 或 MarginNote 4（MN3使用 3.6.11 及以上）。
 - 了解如何将 .mnaddon 包安装到 MarginNote 并在应用中启用插件。
 
 ## 第一步：插件包结构
@@ -32,7 +32,7 @@ description: 从零运行你的第一个 MarginNote 插件（Hello World）。
 }
 ```
 
-- `addonid`：唯一 ID，建议用反向域名。
+- `addonid`：唯一 ID，用反向域名。
 - `title`：在 MarginNote 中显示的插件名称。
 - `marginnote_version_min`：最低支持的 MarginNote 版本。
 

package/src/content/docs/guides/lifecycle-and-window.md

@@ -11,7 +11,7 @@ description: 理解 scene/notebook/document 生命周期及何时可安全使用
 
 | 方法 | 调用时机 |
 |------|----------|
-| `sceneWillConnect()` | 插件窗口即将创建，可在此做轻量初始化；此时可能还没有打开笔记本。 |
+| `sceneWillConnect()` | 插件窗口即将创建，可在此做轻量初始化；此时会还没有打开笔记本。 |
 | `sceneDidDisconnect()` | 插件窗口已断开。 |
 | `sceneWillResignActive()` | 窗口即将失去活跃。 |
 | `sceneDidBecomeActive()` | 窗口变为活跃。 |
@@ -33,8 +33,8 @@ description: 理解 scene/notebook/document 生命周期及何时可安全使用
 ## 何时可使用 studyController
 
 - `studyController(window)` 返回的是**当前窗口**的学习控制器；只有在该窗口已经打开过笔记本、学习界面已就绪时，返回值才可用。
-- 在 `sceneWillConnect` 中通常**还没有**打开笔记本，因此一般不要在这里依赖 `studyController(self.window)` 去访问脑图或文档。
-- 在 `notebookWillOpen(topicid)` 被调用后，该窗口即将或已经拥有学习界面；但若需在「打开笔记本」后立刻挂载 UI，建议用 `NSTimer.scheduledTimerWithTimeInterval(0.2, false, function () { ... })` 延迟约 0.2 秒再执行，以确保 studyController 与 view 已就绪。
+- 在 `sceneWillConnect` 中默认**还没有**打开笔记本，因此直接不要在这里依赖 `studyController(self.window)` 去访问脑图或文档。
+- 在 `notebookWillOpen(topicid)` 被调用后，该窗口即将或已经拥有学习界面；但若需在「打开笔记本」后立刻挂载 UI，用 `NSTimer.scheduledTimerWithTimeInterval(0.2, false, function () { ... })` 延迟约 0.2 秒再执行，以确保 studyController 与 view 已就绪。
 
 ## 示例：在笔记本打开时打日志并延迟挂载 UI
 
@@ -59,7 +59,7 @@ notebookWillOpen: function (topicid) {
 
 ## 布局回调：controllerWillLayoutSubviews
 
-若你在学习界面上添加了自定义视图，窗口尺寸或布局变化时可能需要重新计算位置。实现 `controllerWillLayoutSubviews(controller)`，当传入的 controller 是当前窗口的 studyController 时，在其中更新你的面板 frame（例如根据 `controller.view.bounds` 计算）。
+若你在学习界面上添加了自定义视图，窗口尺寸或布局变化时会需要重新计算位置。实现 `controllerWillLayoutSubviews(controller)`，当传入的 controller 是当前窗口的 studyController 时，在其中更新你的面板 frame（例如根据 `controller.view.bounds` 计算）。
 
 ```javascript
 controllerWillLayoutSubviews: function (controller) {

package/src/content/docs/guides/meta.json

@@ -0,0 +1,14 @@
+{
+  "title": "教程",
+  "pages": [
+    "getting-started",
+    "lifecycle-and-window",
+    "notes-and-database",
+    "mindmap-and-selection",
+    "toolbar-and-commands",
+    "shortcut-keys",
+    "native-ui",
+    "storage-and-files",
+    "network-requests"
+  ]
+}

package/src/content/docs/guides/mindmap-and-selection.md

@@ -29,7 +29,7 @@ var document = docController.document;           // MbBook
 var selectionText = docController.selectionText; // 用户选中的文本
 ```
 
-若用户未选中任何内容，`selectionText` 可能为 undefined 或空字符串。
+若用户未选中任何内容，`selectionText` 为 undefined 或空字符串。
 
 ## 在脑图中高亮指定笔记
 
@@ -73,4 +73,4 @@ if (focusNote && text && text.length > 0) {
 ## 相关
 
 - [StudyController](/reference/marginnote/study-controller/)、[NotebookController](/reference/marginnote/notebook-controller/)、[DocumentController](/reference/marginnote/document-controller/)
-- [Cookbook：将选区追加为评论](/guides/cookbook/append-selection-as-comment/)、[在脑图中高亮指定笔记](/guides/cookbook/focus-note-in-mindmap/)
+- [Cookbook：将选区追加为评论](/cookbook/append-selection-as-comment/)、[在脑图中高亮指定笔记](/cookbook/focus-note-in-mindmap/)

package/src/content/docs/guides/native-ui.md

@@ -88,12 +88,12 @@ self.webView.loadRequest(NSURLRequest.requestWithURL(NSURL.URLWithString("http:/
 
 ```javascript
 var html = "<html><body><h1>Hello</h1></body></html>";
-self.webView.loadHTMLStringBaseURL(html, null);  // 以示例为准，JS 中方法名为 loadHTMLStringBaseURL(string, baseURL)；若环境不同则可能为 loadHTMLString
+self.webView.loadHTMLStringBaseURL(html, null);  // JS 中方法名为 loadHTMLStringBaseURL(string, baseURL)；
 ```
 
 ### Delegate 回调（实例成员）
 
-建议在 **viewWillAppear** 中设置 `self.webView.delegate = self`（确保每次显示时 delegate 有效），在 **viewWillDisappear** 中调用 `self.webView.stopLoading()` 并设置 `self.webView.delegate = null`，避免视图消失后仍收到回调。
+在 **viewWillAppear** 中设置 `self.webView.delegate = self`（确保每次显示时 delegate 有效），在 **viewWillDisappear** 中调用 `self.webView.stopLoading()` 并设置 `self.webView.delegate = null`，避免视图消失后仍收到回调。
 
 在 `JSB.defineClass` 的第二个参数中定义：
 
@@ -122,7 +122,7 @@ self.webView.evaluateJavaScript("document.title", function (result) {
 });
 ```
 
-WebView 内 JS 与插件 JS 的双向通信（自定义 URL Scheme 拦截 + evaluateJavaScript）见 [Cookbook：WebView 内 JS 与插件 JS 双向通信](/guides/cookbook/webview-bidirectional-js/)。
+WebView 内 JS 与插件 JS 的双向通信（自定义 URL Scheme 拦截 + evaluateJavaScript）见 [Cookbook：WebView 内 JS 与插件 JS 双向通信](/cookbook/webview-bidirectional-js/)。
 
 ## 布局与圆角
 
@@ -133,4 +133,4 @@ WebView 内 JS 与插件 JS 的双向通信（自定义 URL Scheme 拦截 + eval
 
 - [UIView](/reference/uikit/uiview/)、[UIButton](/reference/uikit/uibutton/)、[UIAlertView](/reference/uikit/uialertview/)、[UIWebView](/reference/uikit/uiwebview/)、[UIColor](/reference/uikit/uicolor/)
 - [工具栏与命令](/guides/toolbar-and-commands/) — 将面板与工具栏按钮联动
-- [Cookbook：WebView 内 JS 与插件 JS 双向通信](/guides/cookbook/webview-bidirectional-js/)
+- [Cookbook：WebView 内 JS 与插件 JS 双向通信](/cookbook/webview-bidirectional-js/)

package/src/content/docs/guides/network-requests.md

@@ -9,7 +9,7 @@ description: 使用 NSURLConnection 发起 HTTP 请求；含 Base64 解码与 Re
 
 - **读 data**：异步回调形参为 `(response, data, error)`。响应体在 **data**（NSData）里，处理结果以 data 为主；`response` 用于取 `statusCode()`，`error` 用于判断失败，不必用到所有参数。
 - **data → JSON**：直接对 **NSData** 调用 `NSJSONSerialization.JSONObjectWithDataOptions(data, 0 或 1)`，得到 JS 对象；**不要**先转成字符串再 `JSON.parse`。
-- **data → 纯文本**：环境中无现成「NSData → 字符串」API 时，用 `data.base64Encoding()` 得到 base64 字符串，再用 **Base64 解码**得到 JS 字符串。运行时不提供 Base64 解码，需在插件内实现（见下一节完整代码）。
+- **data → 纯文本**：环境中无「NSData → 字符串」API ，用 `data.base64Encoding()` 得到 base64 字符串，再用 **Base64 解码**得到 JS 字符串。插件环境不提供 Base64 解码，需在插件内实现（见下一节完整代码）。
 
 ---
 
@@ -140,7 +140,7 @@ class MNNetwork {
         NSOperationQueue.mainQueue(),
         function (res, data, err) {
           if (!MNNetwork.isNil(err)) {
-            reject(err.localizedDescription ? err.localizedDescription() : "Network Error");
+            reject(err.localizedDescription);
           } else {
             var response = new Response(data, res);
             resolve(response);
@@ -156,7 +156,7 @@ class MNNetwork {
 
 - `Response#text()`：用 `data.base64Encoding()` 得到 base64 串，再 `Base64.decode(encoding)` 得到 JS 字符串；环境无 Base64 解码，故依赖上面的 `base64.js`。
 - `Response#json()`：直接对 **NSData** 调用 `NSJSONSerialization.JSONObjectWithDataOptions(this.data, 1)`，不经过 base64 或字符串。
-- 错误信息：`error.localizedDescription` 在部分运行时为方法，需 `error.localizedDescription()`，封装里已按「有则调用」处理。
+- 错误信息：`error.localizedDescription` 为方法，需 `error.localizedDescription`，封装里已按「有则调用」处理。
 
 ---
 
@@ -231,9 +231,8 @@ async function fetchWithAuth() {
 
 - **回调**：`NSURLConnection.sendAsynchronousRequestQueueCompletionHandler(request, NSOperationQueue.mainQueue(), function (response, data, error) { ... })`。有用的是 **data**（响应体）、可选的 `response.statusCode()`、以及 **error**（失败时）。
 - **JSON**：直接对 **data**（NSData）解析，不要先转字符串再 `JSON.parse`：
-  - `var obj = NSJSONSerialization.JSONObjectWithDataOptions(data, 0);` 或选项 `1`（若运行时支持）。
+  - `var obj = NSJSONSerialization.JSONObjectWithDataOptions(data, 0);` 或选项 `1`（环境支持）。
 - **纯文本**：无 Base64 解码时无法从 NSData 得到字符串；必须先按上文提供 `base64.js`，再 `var str = Base64.decode(data.base64Encoding());`。
-- **错误**：`error.localizedDescription` 可能是属性或方法，建议统一写成：`var msg = (typeof error.localizedDescription === "function" ? error.localizedDescription() : error.localizedDescription) || "未知错误";`。
 
 **原始 GET + JSON 示例**：
 
@@ -246,7 +245,7 @@ NSURLConnection.sendAsynchronousRequestQueueCompletionHandler(
   NSOperationQueue.mainQueue(),
   function (response, data, error) {
     if (error) {
-      var msg = (typeof error.localizedDescription === "function" ? error.localizedDescription() : error.localizedDescription) || "未知错误";
+      var msg = error.localizedDescription;
       Application.sharedInstance().alert("请求失败: " + msg);
       return;
     }
@@ -278,7 +277,7 @@ NSURLConnection.sendAsynchronousRequestQueueCompletionHandler(
   NSOperationQueue.mainQueue(),
   function (response, data, error) {
     if (error) {
-      var msg = (typeof error.localizedDescription === "function" ? error.localizedDescription() : error.localizedDescription) || "未知错误";
+      var msg = error.localizedDescription;
       Application.sharedInstance().alert("请求失败: " + msg);
       return;
     }
@@ -298,12 +297,12 @@ NSURLConnection.sendAsynchronousRequestQueueCompletionHandler(
 | 响应体 | 使用回调中的 **data**（NSData），不必依赖 response 的其他字段 |
 | data → JSON | `NSJSONSerialization.JSONObjectWithDataOptions(data, 0)` 或 `1`，直接对 data |
 | data → 纯文本 | `data.base64Encoding()` 得到 base64 串，再 **Base64.decode**（需自备 base64.js） |
-| 错误信息 | `error.localizedDescription` 或 `error.localizedDescription()`，依运行时而定 |
+| 错误信息 | `error.localizedDescription` |
 
 推荐在插件内包含完整的 `base64.js` 与 `network.js`（如上），先 `JSB.require('base64')` 再 `JSB.require('network')`，然后用 `MNNetwork.fetch` 发起请求，在 try/catch 中用 `res.json()` 或 `res.text()` 处理 JSON 与纯文本。
 
 ## 相关
 
-- [Cookbook：调用远程 API](/guides/cookbook/network-api-call/) —— 将 API 结果展示或写入笔记
+- [Cookbook：调用远程 API](/cookbook/network-api-call/) —— 将 API 结果展示或写入笔记
 - [JavaScript 原生环境](/reference/js-runtime/) —— 为何没有 fetch
 - [NSURLConnection](/reference/foundation/ns-url-connection/)、[NSMutableURLRequest](/reference/foundation/ns-mutable-url-request/)

package/src/content/docs/guides/notes-and-database.md

@@ -47,7 +47,7 @@ if (note) {
 
 ## 创建新笔记
 
-使用全局 `Note` 对象创建新笔记：`Note.createWithTitleNotebookDocument(title, notebook, doc)`（`notebook` 为 `MbTopic`，`doc` 为 `MbBook`）。创建后同样建议放在 undoGrouping 中并刷新。
+使用全局 `Note` 对象创建新笔记：`Note.createWithTitleNotebookDocument(title, notebook, doc)`（`notebook` 为 `MbTopic`，`doc` 为 `MbBook`）。创建后同样放在 undoGrouping 中并刷新。
 
 ```javascript
 var db = Database.sharedInstance();
@@ -96,4 +96,4 @@ if (note) {
 ## 相关
 
 - [Database](/reference/global/database/)、[MbBookNote](/reference/marginnote/mb-book-note/)、[UndoManager](/reference/utility/undo-manager/)
-- [Cookbook：批量修改笔记标题](/guides/cookbook/batch-rename-notes/)
+- [Cookbook：批量修改笔记标题](/cookbook/batch-rename-notes/)

package/src/content/docs/guides/shortcut-keys.md

@@ -5,7 +5,7 @@ description: 在JSExtension中注册快捷键，并用query/process稳定处理
 
 MarginNote插件提供了一套“扩展快捷键”机制：你可以在插件主类（继承`JSExtension`）中实现`additionalShortcutKeys()`返回快捷键声明，然后用`queryShortcutKeyWithKeyFlags(command,keyFlags)`与`processShortcutKeyWithKeyFlags(command,keyFlags)`完成“可用性判断”和“按下处理”。
 
-本页按标准教程结构介绍该机制：接口作用、注册方式、推荐实现范式、参数语义、组合键选择建议与常见坑。
+本页按标准教程结构介绍该机制：接口作用、注册方式、推荐实现范式、参数语义、组合键选择规范与常见问题。
 
 ## 概述
 
@@ -16,8 +16,8 @@ MarginNote插件提供了一套“扩展快捷键”机制：你可以在插件
 
 边界与限制：
 
-- 当用户正在编辑文本时（firstResponder在输入框/编辑器上），按键可能被输入控件优先消费，插件快捷键不一定触发。这是预期行为。
-- 组合键可能与系统或应用内建快捷键冲突，导致命中率不稳定；应优先选择冲突更少的组合键，并允许用户自定义（如你的插件有设置页）。
+- 当用户正在编辑文本时（firstResponder在输入框/编辑器上），按键会被输入控件优先消费，插件快捷键不会稳定触发。这是预期行为。
+- 组合键会与系统或应用内建快捷键冲突，导致命中率不稳定；应优先选择冲突更少的组合键，并允许用户自定义（如你的插件有设置页）。
 
 ## 接口一览
 
@@ -57,8 +57,8 @@ additionalShortcutKeys: function () {
 
 这两者的职责必须严格区分：
 
-- `queryShortcutKeyWithKeyFlags(...)`用于“查询状态”。系统可能会在可用性判断、快捷键列表重建、焦点变化等场景批量调用它，因此调用次数与传入参数都可能远超你的预期。为了保证性能与行为可控，建议在query中只做轻量判断并返回状态：避免任何IO操作、耗时计算、网络请求、文件读写，以及无差别日志输出；更不要在这里修改笔记/数据库或触发UI。
-- `processShortcutKeyWithKeyFlags(...)`用于“处理按下”。真正的业务动作应放在这里；如果会修改笔记/笔记本数据，建议使用`UndoManager.undoGrouping(...)`包裹，保证撤销/重做稳定。
+- `queryShortcutKeyWithKeyFlags(...)`用于“查询状态”。系统会在可用性判断、快捷键列表重建、焦点变化等场景批量调用它，因此调用次数与传入参数都会远超你的预期。为了保证性能与行为可控，在query中只做轻量判断并返回状态：避免任何IO操作、耗时计算、网络请求、文件读写，以及无差别日志输出；更不要在这里修改笔记/数据库或触发UI。
+- `processShortcutKeyWithKeyFlags(...)`用于“处理按下”。真正的业务动作应放在这里；如果会修改笔记/笔记本数据，使用`UndoManager.undoGrouping(...)`包裹，保证撤销/重做稳定。
 
 推荐写法：只匹配你关心的组合键，其余保持静默（例如直接`return null`）。
 
@@ -66,7 +66,7 @@ additionalShortcutKeys: function () {
 
 ### command
 
-`command`是系统传入的标识。已确认它可能是：
+`command`是系统传入的标识。已确认它是：
 
 - 内建命令名：例如`NewChildNote`、`ToggleExpand`、`EditAddTitle`等。
 - 输入常量/字符：例如`UIKeyInputLeftArrow`、`UIKeyInputUpArrow`，以及`z`这类字符输入。
@@ -86,16 +86,16 @@ additionalShortcutKeys: function () {
 | Command+Shift | `1179648` |
 
 
-## 组合键选择建议
+## 组合键选择规范
 
 - 优先选择不常被系统/应用占用的组合键。
 - 避免与“通用编辑快捷键”冲突（例如撤销/重做/复制粘贴等），除非你非常确定不会影响用户习惯。
-- 若某个组合键命中率不稳定，通常是冲突或编辑态吞键导致；建议提供替代键位或设置项。
+- 若某个组合键命中率不稳定，默认是冲突或编辑态吞键导致；提供替代键位或设置项。
 
 ## 注意事项
 
 - 在query里做副作用：导致“未按下也触发动作”、撤销链异常、或出现难以定位的状态错乱。
-- 无差别打印日志：query可能被批量调用，导致刷屏，反而遮蔽真正有用的命中日志。
+- 无差别打印日志：query会被批量调用，导致刷屏，反而遮蔽真正有用的命中日志。
 - 忽略编辑态：用户在输入时快捷键不触发属于预期，需要在产品交互上规避或提示。
 
 ## 相关

package/src/content/docs/guides/storage-and-files.md

@@ -23,7 +23,7 @@ var counter = defaults.integerForKey("my_addon_counter");
 var on = defaults.boolForKey("my_addon_switch");
 ```
 
-键名建议加插件前缀，避免与其他插件冲突。
+键名加插件前缀，避免与其他插件冲突。
 
 ## NSFileManager：目录与文件
 
@@ -50,7 +50,7 @@ textData.writeToFileAtomically(filePath, true);
 读取文件为 NSData 后，若需转为 JS 可用的形式：
 
 - **若文件为 JSON**：用 `NSJSONSerialization.JSONObjectWithDataOptions(data, 0)` 解析为对象/数组；解析前可用 `data.length() === 0` 判断是否为空。
-- **若需纯文本字符串**：若运行时导出了 `NSString`，可用 `NSString.alloc().initWithDataEncoding(data, 4)`（4 为 UTF-8）再取字符串；若无 NSString，可先尝试上述 JSON 解析。
+- **若需纯文本字符串**：使用 `NSString.stringWithContentsOfData(data)` 将 `NSData` 转为字符串。
 
 示例：从文件读取 JSON 并解析
 
@@ -67,7 +67,7 @@ if (data && data.length() > 0) {
 ## 路径说明
 
 - `Application.sharedInstance().documentPath`：文稿目录，适合存放用户数据。
-- `Application.sharedInstance().tempPath`：临时目录，系统可能清理。
+- `Application.sharedInstance().tempPath`：临时目录，系统会清理。
 - 插件包根路径由 `JSB.newAddon(mainPath)` 的 `mainPath` 传入，可用于读取包内资源（如图标）。
 
 ## 完整示例：保存与读取一个开关
@@ -87,5 +87,5 @@ NSUserDefaults.standardUserDefaults().setBoolForKey(newValue, "my_addon_show_pan
 ## 相关
 
 - [NSUserDefaults](/reference/foundation/ns-user-defaults/)、[NSFileManager](/reference/foundation/ns-file-manager/)、[NSData](/reference/foundation/ns-data/)
-- [Cookbook：插件设置页](/guides/cookbook/addon-settings/)
+- [Cookbook：插件设置页](/cookbook/addon-settings/)
 - [网络请求](/guides/network-requests/) —— 网络响应 NSData 的 JSON 解析同理

package/src/content/docs/guides/toolbar-and-commands.md

@@ -12,7 +12,7 @@ MarginNote 会调用插件的 `queryAddonCommandStatus()`。若希望显示工
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | `image` | string | 图标文件名（相对于插件包根目录，如 `'sample.png'`）。 |
-| `object` | object | 接收点击的对象，通常为 `self`（插件实例）。 |
+| `object` | object | 接收点击的对象，为 `self`（插件实例）。 |
 | `selector` | string | 点击时调用的方法名，**必须以冒号结尾**（如 `'toggleSample:'`）。 |
 | `checked` | boolean | 是否显示为「选中」状态（如面板是否已显示）。 |
 

package/src/content/docs/index.mdx

@@ -1,44 +1,19 @@
 ---
 title: MarginNote 插件开发文档
-description: MarginNote 插件开发的完整 API 参考与渐进式教程（含 Cookbook 配方）。
-template: splash
-hero:
-  tagline: 为 MarginNote 编写插件的官方/社区参考文档
-  image:
-    file: ../../assets/houston.webp
-  actions:
-    - text: 快速开始
-      link: /guides/getting-started/
-      icon: right-arrow
-    - text: API 参考
-      link: /reference/global/jsb/
-      icon: document
-      variant: minimal
+description: MarginNote 插件开发的完整 API 参考与渐进式教程。
 ---
 
-import { Card, CardGrid } from '@astrojs/starlight/components';
+import { Card, Cards } from 'fumadocs-ui/components/card';
 
-## 从这里开始
+# MarginNote 插件开发文档
 
-<CardGrid stagger>
-	<Card title="快速开始" icon="rocket">
-		从零运行你的第一个插件（Hello World），了解 mnaddon.json 与入口函数。
-		[进入快速开始](/guides/getting-started/)
-	</Card>
-	<Card title="教程" icon="pencil">
-		按学习路径掌握生命周期、笔记与数据库、脑图与选区、工具栏与原生 UI。
-		[浏览教程](/guides/lifecycle-and-window/)
-	</Card>
-	<Card title="Cookbook 配方" icon="add-document">
-		按任务查找完整可运行代码：批量改标题、导出笔记本、高亮笔记、设置页等。
-		[查看配方](/guides/cookbook/batch-rename-notes/)
-	</Card>
-	<Card title="API 参考" icon="open-book">
-		全局对象、MarginNote 核心、Foundation、UIKit、Utility 的完整 API 说明。
-		[进入 API](/reference/global/jsb/)
-	</Card>
-	<Card title="贡献指南" icon="heart">
-		参与文档改进：贡献流程、API 参考与教程的格式规范、Markdown 约定等。
-		[查看贡献指南](/guides/contributing/)
-	</Card>
-</CardGrid>
+为 MarginNote 编写插件的 API 参考、渐进式教程与 Cookbook 配方。
+
+<Cards>
+	<Card title="快速开始" href="/guides/getting-started/" description="从零运行你的第一个插件，了解开发流程。" />
+	<Card title="教程" href="/guides/lifecycle-and-window/" description="按学习路径掌握生命周期、笔记与数据库等核心概念。" />
+	<Card title="Cookbook" href="/cookbook/batch-rename-notes/" description="按任务查找完整可运行代码。" />
+	<Card title="API 参考" href="/reference/global/jsb/" description="全局对象与核心 API 的完整说明。" />
+	<Card title="LibMN" href="/libmn/" description="LibMN 运行时与插件开发核心模块。" />
+	<Card title="贡献指南" href="/contributing/" description="参与文档改进，了解格式规范。" />
+</Cards>