mn-docs-mcp 0.1.0

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

@@ -0,0 +1,76 @@
+---
+title: 脑图与选区
+description: 获取当前脑图、焦点笔记与文档选区，并高亮指定笔记。
+---
+
+通过 StudyController 可以访问当前窗口的脑图、焦点笔记和文档选区；还可以在脑图或文档中高亮指定笔记。
+
+## 获取学习控制器与脑图
+
+在已打开笔记本的窗口内（例如在工具栏按钮的回调或 `notebookWillOpen` 延迟后）：
+
+```javascript
+var studyController = Application.sharedInstance().studyController(self.window);
+if (!studyController) return;
+
+var notebookController = studyController.notebookController;
+var mindmapView = notebookController.mindmapView;
+var focusNote = notebookController.focusNote; // 当前脑图中聚焦的笔记
+```
+
+## 获取文档与选区
+
+当前显示的文档控制器与用户在 PDF 中的选区文本：
+
+```javascript
+var readerController = studyController.readerController;
+var docController = readerController.currentDocumentController;
+var document = docController.document;           // MbBook
+var selectionText = docController.selectionText; // 用户选中的文本
+```
+
+若用户未选中任何内容，`selectionText` 可能为 undefined 或空字符串。
+
+## 在脑图中高亮指定笔记
+
+若你已知某条笔记的 `noteId`，希望脑图滚动并高亮到该节点：
+
+```javascript
+studyController.focusNoteInMindMapById(noteId);
+```
+
+## 在文档中高亮指定笔记
+
+若希望文档视图滚动并高亮到某条笔记对应的摘录位置：
+
+```javascript
+studyController.focusNoteInDocumentById(noteId);
+```
+
+## 示例：将当前选区追加为评论
+
+当用户先在 PDF 中选中一段文字，再点击插件按钮时，可将选区文本追加到当前焦点笔记的评论中：
+
+```javascript
+var studyController = Application.sharedInstance().studyController(self.window);
+if (!studyController) return;
+var docController = studyController.readerController.currentDocumentController;
+var focusNote = studyController.notebookController.focusNote;
+var text = docController.selectionText;
+
+if (focusNote && text && text.length > 0) {
+  var topicid = focusNote.notebookId;
+  UndoManager.sharedInstance().undoGrouping("追加选区为评论", topicid, function () {
+    focusNote.appendTextComment(text);
+  });
+  Application.sharedInstance().refreshAfterDBChanged(topicid);
+  Application.sharedInstance().showHUD("已追加为评论", self.window, 2);
+} else {
+  Application.sharedInstance().alert("请先选中一条笔记并在文档中选中文字");
+}
+```
+
+## 相关
+
+- [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/)

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

@@ -0,0 +1,136 @@
+---
+title: 原生 UI
+description: 使用 UIView、UILabel、UIButton、UIAlertView 等构建简单界面。
+---
+
+插件可以使用 MarginNote 暴露的 UIKit 接口创建原生界面，例如浮窗、按钮、标签和弹窗。将视图添加到 `Application.sharedInstance().studyController(self.window).view` 即可显示在主学习界面上。
+
+## 创建并添加一个视图
+
+```javascript
+var frame = { x: 0, y: 0, width: 100, height: 50 };
+var myView = new UIView(frame);
+myView.backgroundColor = UIColor.colorWithHexString("#FF0000"); // 红色，若支持 hex
+
+Application.sharedInstance().studyController(self.window).view.addSubview(myView);
+```
+
+若没有 `colorWithHexString`，可用 `UIColor.colorWithRedGreenBlueAlpha(1, 0, 0, 1)`。
+
+## 添加标签（UILabel）
+
+```javascript
+var label = new UILabel({ x: 10, y: 10, width: 80, height: 30 });
+label.text = "Hello!";
+label.textColor = UIColor.whiteColor();
+myView.addSubview(label);
+```
+
+## 添加按钮并响应点击
+
+按钮的点击必须通过 **addTargetActionForControlEvents** 绑定到 **JSB.defineClass 的实例方法**，且该方法名**必须以冒号结尾**（如 `myButtonTapped:`）。
+
+```javascript
+var btn = UIButton.buttonWithType(0);
+btn.frame = { x: 10, y: 60, width: 80, height: 40 };
+btn.setTitleForState("Click Me", 0);
+btn.addTargetActionForControlEvents(self, "myButtonTapped:", 1 << 6); // 1<<6 = TouchUpInside
+myView.addSubview(btn);
+
+// 在实例方法中定义：
+// myButtonTapped: function (sender) {
+//   Application.sharedInstance().alert("Button was tapped!");
+// }
+```
+
+## 弹窗（UIAlertView）
+
+带回调的确认框可这样写：
+
+```javascript
+UIAlertView.showWithTitleMessageStyleCancelButtonTitleOtherButtonTitlesTapBlock(
+  "确认",
+  "是否执行该操作？",
+  0,
+  "取消",
+  ["确定"],
+  function (alert, buttonIndex) {
+    if (buttonIndex === 0) {
+      JSB.log("用户点击了确定");
+    } else {
+      JSB.log("用户取消");
+    }
+  }
+);
+```
+
+`buttonIndex` 为 0 表示第一个「其他」按钮，-1 表示取消。
+
+## 使用 WebView
+
+在插件中嵌入网页或本地 HTML 可使用 [UIWebView](/reference/uikit/uiwebview/)。创建 WebView、设置 frame 与 delegate，在承载它的 ViewController 的**实例成员**中实现 UIWebViewDelegate 回调（webViewDidStartLoad、webViewDidFinishLoad、webViewDidFailLoadWithError、webViewShouldStartLoadWithRequestNavigationType）。
+
+### 创建并加载远程 URL
+
+```javascript
+var webFrame = { x: 0, y: 40, width: self.view.bounds.width, height: self.view.bounds.height - 40 };
+self.webView = new UIWebView(webFrame);
+self.webView.backgroundColor = UIColor.whiteColor();
+self.webView.scalesPageToFit = true;
+self.webView.autoresizingMask = (1 << 1 | 1 << 4 | 1 << 5);
+self.webView.delegate = self;
+self.view.addSubview(self.webView);
+self.webView.loadRequest(NSURLRequest.requestWithURL(NSURL.URLWithString("http://www.apple.com/")));
+// 若需设置 User-Agent 等，可用 NSMutableURLRequest 构建请求，再 loadRequest(req)
+```
+
+### 加载本地 HTML 字符串
+
+```javascript
+var html = "<html><body><h1>Hello</h1></body></html>";
+self.webView.loadHTMLStringBaseURL(html, null);  // 以示例为准，JS 中方法名为 loadHTMLStringBaseURL(string, baseURL)；若环境不同则可能为 loadHTMLString
+```
+
+### Delegate 回调（实例成员）
+
+建议在 **viewWillAppear** 中设置 `self.webView.delegate = self`（确保每次显示时 delegate 有效），在 **viewWillDisappear** 中调用 `self.webView.stopLoading()` 并设置 `self.webView.delegate = null`，避免视图消失后仍收到回调。
+
+在 `JSB.defineClass` 的第二个参数中定义：
+
+```javascript
+webViewDidStartLoad: function (webView) {
+  // 开始加载，可显示 loading
+},
+webViewDidFinishLoad: function (webView) {
+  // 加载完成
+},
+webViewDidFailLoadWithError: function (webView, error) {
+  // 加载失败；可用 error.localizedDescription 获取错误信息，拼接 HTML 后用 loadHTMLStringBaseURL 显示错误页
+},
+webViewShouldStartLoadWithRequestNavigationType: function (webView, request, type) {
+  return true;  // 若拦截自定义 URL Scheme 则解析后 return false
+}
+```
+
+### 插件向页面注入 JS
+
+加载完成后可用 `evaluateJavaScript` 在页面上下文中执行脚本：
+
+```javascript
+self.webView.evaluateJavaScript("document.title", function (result) {
+  JSB.log("页面标题: %@", result);
+});
+```
+
+WebView 内 JS 与插件 JS 的双向通信（自定义 URL Scheme 拦截 + evaluateJavaScript）见 [Cookbook：WebView 内 JS 与插件 JS 双向通信](/guides/cookbook/webview-bidirectional-js/)。
+
+## 布局与圆角
+
+- 通过设置 `view.frame` 控制位置和大小；在 `controllerWillLayoutSubviews` 中根据 `studyController.view.bounds` 重新计算 frame，可适配窗口变化。
+- 使用 `view.layer.cornerRadius`、`view.layer.borderWidth`、`view.layer.borderColor` 设置圆角与边框。
+
+## 相关
+
+- [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/)

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

@@ -0,0 +1,309 @@
+---
+title: 网络请求
+description: 使用 NSURLConnection 发起 HTTP 请求；含 Base64 解码与 Response 封装完整代码，解析 JSON 与纯文本。
+---
+
+插件运行在 JavaScriptCore 环境中，**没有浏览器的 `fetch`**，也**没有内置的 Base64 解码**。网络请求需使用系统导出的 `NSURLConnection`，配合 `NSMutableURLRequest`、`NSOperationQueue`、`NSData`、`NSJSONSerialization` 等完成。响应体在回调的 **data**（NSData）里；**data 转 JSON 与 data 转纯文本方式不同**：JSON 用 `NSJSONSerialization` 直接对 data 解析，纯文本需先用 `data.base64Encoding()` 再经 Base64 解码得字符串（需自行提供 Base64 解码实现）。下文给出完整可用的 Base64 解码与网络封装代码，照抄即用。
+
+## 核心要点
+
+- **读 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 解码，需在插件内实现（见下一节完整代码）。
+
+---
+
+## Base64 解码
+
+环境中没有 Base64 的 decode，需在插件中自备。将以下代码保存为 `base64.js`，放在插件包内，在入口（如 main.js）中先 `JSB.require('base64')` 再使用依赖它的网络封装。
+
+```javascript
+// base64.js —— Base64 解码工具，供 NSData 转纯文本使用
+var Base64 = {
+  _keyStr: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=",
+
+  decode: function (input) {
+    var output = "";
+    var i = 0;
+    var chr1, chr2, chr3, enc1, enc2, enc3, enc4;
+
+    while (i < input.length) {
+      enc1 = this._keyStr.indexOf(input.charAt(i++));
+      enc2 = this._keyStr.indexOf(input.charAt(i++));
+      enc3 = this._keyStr.indexOf(input.charAt(i++));
+      enc4 = this._keyStr.indexOf(input.charAt(i++));
+
+      chr1 = (enc1 << 2) | (enc2 >> 4);
+      chr2 = ((enc2 & 15) << 4) | (enc3 >> 2);
+      chr3 = ((enc3 & 3) << 6) | enc4;
+
+      output = output + String.fromCharCode(chr1);
+      if (enc3 != 64) {
+        output = output + String.fromCharCode(chr2);
+      }
+      if (enc4 != 64) {
+        output = output + String.fromCharCode(chr3);
+      }
+    }
+
+    return output;
+  }
+};
+```
+
+---
+
+## 网络封装：Response + MNNetwork
+
+以下封装提供 `Response#text()`（data → 纯文本，依赖 Base64）和 `Response#json()`（data → JS 对象，直接对 NSData 用 NSJSONSerialization）。将代码保存为 `network.js`，在入口中先 `JSB.require('base64')` 再 `JSB.require('network')`，然后使用 `MNNetwork.fetch(url, options)`。
+
+```javascript
+// network.js —— Response#text() 依赖 Base64，由入口加载 base64.js 后可用
+
+class Response {
+  constructor(data, nsResponse) {
+    this.data = data;
+    this.nsResponse = nsResponse;
+    this.status = nsResponse ? nsResponse.statusCode() : 0;
+  }
+
+  static isNil(obj) {
+    return obj === null || typeof obj === 'undefined' || obj instanceof NSNull;
+  }
+
+  text() {
+    if (Response.isNil(this.data) || this.data.length() === 0) return "";
+
+    var encoding = this.data.base64Encoding();
+    var decoding = Base64.decode(encoding);
+    return decoding;
+  }
+
+  json() {
+    if (Response.isNil(this.data) || this.data.length() === 0) return {};
+
+    try {
+      return NSJSONSerialization.JSONObjectWithDataOptions(this.data, 1);
+    } catch (e) {
+      return null;
+    }
+  }
+}
+
+class MNNetwork {
+  static isNil(obj) {
+    return obj === null || typeof obj === 'undefined' || obj instanceof NSNull;
+  }
+
+  static _initRequest(url, options) {
+    var fullUrl = url.trim();
+    if (fullUrl.indexOf("://") === -1) fullUrl = "https://" + fullUrl;
+
+    var request = NSMutableURLRequest.requestWithURL(NSURL.URLWithString(fullUrl));
+    request.setHTTPMethod(options.method || "GET");
+    request.setTimeoutInterval(options.timeout || 10);
+
+    var headers = {
+      "User-Agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 15_0 like Mac OS X)",
+      "Content-Type": "application/json",
+      "Accept": "application/json"
+    };
+    if (options.headers) {
+      for (var k in options.headers) headers[k] = options.headers[k];
+    }
+    request.setAllHTTPHeaderFields(headers);
+
+    if (options.json) {
+      request.setHTTPBody(NSJSONSerialization.dataWithJSONObjectOptions(options.json, 1));
+    } else if (options.body) {
+      request.setHTTPBody(NSData.dataWithStringEncoding(String(options.body), 4));
+    }
+
+    if (options.search) {
+      var components = NSURLComponents.componentsWithString(fullUrl);
+      var qs = Object.keys(options.search).map(function (k) {
+        return encodeURIComponent(k) + "=" + encodeURIComponent(options.search[k]);
+      }).join("&");
+      components.query = qs;
+      request.setURL(components.URL());
+    }
+
+    return request;
+  }
+
+  static fetch(url, options) {
+    var req = this._initRequest(url, options || {});
+
+    return new Promise(function (resolve, reject) {
+      NSURLConnection.sendAsynchronousRequestQueueCompletionHandler(
+        req,
+        NSOperationQueue.mainQueue(),
+        function (res, data, err) {
+          if (!MNNetwork.isNil(err)) {
+            reject(err.localizedDescription ? err.localizedDescription() : "Network Error");
+          } else {
+            var response = new Response(data, res);
+            resolve(response);
+          }
+        }
+      );
+    });
+  }
+}
+```
+
+**说明**：
+
+- `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()`，封装里已按「有则调用」处理。
+
+---
+
+## 使用封装发起请求
+
+在 main.js（或入口）中的使用示例：
+
+```javascript
+JSB.require('base64');
+JSB.require('network');
+
+// GET JSON
+async function fetchQuote() {
+  try {
+    var res = await MNNetwork.fetch("https://api.quotable.io/random");
+    var obj = res.json();
+    if (obj && obj.content) {
+      Application.sharedInstance().showHUD(obj.content, self.window, 3);
+    }
+  } catch (err) {
+    Application.sharedInstance().alert("请求失败: " + err);
+  }
+}
+
+// GET 纯文本（如某接口返回 text/plain）
+async function fetchPlain() {
+  try {
+    var res = await MNNetwork.fetch("https://example.com/plain");
+    var str = res.text();
+    Application.sharedInstance().showHUD(str.substring(0, 80), self.window, 2);
+  } catch (err) {
+    Application.sharedInstance().alert("请求失败: " + err);
+  }
+}
+
+// POST JSON
+async function postEcho() {
+  try {
+    var res = await MNNetwork.fetch("https://api.example.com/echo", {
+      method: "POST",
+      json: { key: "value" }
+    });
+    var obj = res.json();
+    // 使用 obj...
+  } catch (err) {
+    Application.sharedInstance().alert("请求失败: " + err);
+  }
+}
+
+// 自定义 Headers（如 Authorization）
+async function fetchWithAuth() {
+  try {
+    var res = await MNNetwork.fetch("https://api.example.com/data", {
+      headers: {
+        "Authorization": "Bearer YOUR_API_KEY",
+        "Accept": "application/json"
+      }
+    });
+    var obj = res.json();  // 或 res.text()
+    // 使用 obj...
+  } catch (err) {
+    Application.sharedInstance().alert("请求失败: " + err);
+  }
+}
+```
+
+---
+
+## 不使用封装时的原始写法
+
+若不引入上述封装，直接使用系统 API 时要点如下。
+
+- **回调**：`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`（若运行时支持）。
+- **纯文本**：无 Base64 解码时无法从 NSData 得到字符串；必须先按上文提供 `base64.js`，再 `var str = Base64.decode(data.base64Encoding());`。
+- **错误**：`error.localizedDescription` 可能是属性或方法，建议统一写成：`var msg = (typeof error.localizedDescription === "function" ? error.localizedDescription() : error.localizedDescription) || "未知错误";`。
+
+**原始 GET + JSON 示例**：
+
+```javascript
+var req = NSMutableURLRequest.requestWithURL(NSURL.URLWithString("https://api.quotable.io/random"));
+req.setTimeoutInterval(10);
+
+NSURLConnection.sendAsynchronousRequestQueueCompletionHandler(
+  req,
+  NSOperationQueue.mainQueue(),
+  function (response, data, error) {
+    if (error) {
+      var msg = (typeof error.localizedDescription === "function" ? error.localizedDescription() : error.localizedDescription) || "未知错误";
+      Application.sharedInstance().alert("请求失败: " + msg);
+      return;
+    }
+    if (!data || data.length() === 0) {
+      Application.sharedInstance().alert("无响应数据");
+      return;
+    }
+    var obj = NSJSONSerialization.JSONObjectWithDataOptions(data, 0);
+    if (NSJSONSerialization.isValidJSONObject(obj)) {
+      Application.sharedInstance().showHUD(obj.content || JSON.stringify(obj), self.window, 3);
+    } else {
+      Application.sharedInstance().alert("响应不是有效 JSON");
+    }
+  }
+);
+```
+
+**原始 POST JSON 示例**：
+
+```javascript
+var req = NSMutableURLRequest.requestWithURL(NSURL.URLWithString(url));
+req.setHTTPMethod("POST");
+req.setTimeoutInterval(10);
+req.setValueForHTTPHeaderField("application/json", "Content-Type");
+req.setHTTPBody(NSJSONSerialization.dataWithJSONObjectOptions(jsonBody, 0));
+
+NSURLConnection.sendAsynchronousRequestQueueCompletionHandler(
+  req,
+  NSOperationQueue.mainQueue(),
+  function (response, data, error) {
+    if (error) {
+      var msg = (typeof error.localizedDescription === "function" ? error.localizedDescription() : error.localizedDescription) || "未知错误";
+      Application.sharedInstance().alert("请求失败: " + msg);
+      return;
+    }
+    if (!data || data.length() === 0) return;
+    var obj = NSJSONSerialization.JSONObjectWithDataOptions(data, 0);
+    // 使用 obj...
+  }
+);
+```
+
+---
+
+## 小结
+
+| 目的 | 做法 |
+|------|------|
+| 响应体 | 使用回调中的 **data**（NSData），不必依赖 response 的其他字段 |
+| data → JSON | `NSJSONSerialization.JSONObjectWithDataOptions(data, 0)` 或 `1`，直接对 data |
+| data → 纯文本 | `data.base64Encoding()` 得到 base64 串，再 **Base64.decode**（需自备 base64.js） |
+| 错误信息 | `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 结果展示或写入笔记
+- [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

@@ -0,0 +1,99 @@
+---
+title: 笔记与数据库
+description: 通过 Database 获取与修改笔记，并正确使用 Undo 与刷新。
+---
+
+插件的核心能力之一是对笔记与笔记本进行读写。通过 `Database.sharedInstance()` 获取数据库单例；**修改笔记或笔记本数据时，应使用 UndoManager 的 `undoGrouping` 包裹**，以支持撤销并在执行后刷新界面。
+
+## 获取数据库与笔记
+
+```javascript
+var db = Database.sharedInstance();
+var note = db.getNoteById("某个笔记 ID");
+var notebook = db.getNotebookById("某个笔记本 ID");
+var doc = db.getDocumentById("某个文档 MD5");
+```
+
+- `getNoteById(noteId)`：返回 `MbBookNote` 或 undefined。
+- `getNotebookById(topicId)`：返回 `MbTopic` 或 undefined。
+- `getDocumentById(docMd5)`：返回 `MbBook` 或 undefined。
+
+获取列表：
+
+```javascript
+var allNotebooks = db.allNotebooks();
+var allDocuments = db.allDocuments();
+```
+
+## 修改笔记与 Undo
+
+修改笔记属性后，应放在 **UndoManager 的 undoGrouping** 中执行。常用属性：`noteTitle`（笔记标题）、`excerptText`（摘录/高亮文本）、`colorIndex`（颜色索引），并传入**当前笔记本 ID**（可从 `note.notebookId` 取）。这样用户可撤销，且界面会正确刷新。
+
+```javascript
+var noteId = "要修改的笔记 ID";
+var note = Database.sharedInstance().getNoteById(noteId);
+if (note) {
+  var topicid = note.notebookId;
+  UndoManager.sharedInstance().undoGrouping(
+    "修改笔记标题",
+    topicid,
+    function () {
+      note.noteTitle = "新标题";  // 或修改 excerptText、colorIndex 等
+    }
+  );
+  Application.sharedInstance().refreshAfterDBChanged(topicid);
+}
+```
+
+## 创建新笔记
+
+使用全局 `Note` 对象创建新笔记：`Note.createWithTitleNotebookDocument(title, notebook, doc)`（`notebook` 为 `MbTopic`，`doc` 为 `MbBook`）。创建后同样建议放在 undoGrouping 中并刷新。
+
+```javascript
+var db = Database.sharedInstance();
+var notebook = db.getNotebookById("某个笔记本 ID");
+var doc = db.getDocumentById("某个文档 MD5");
+
+if (notebook && doc) {
+  var topicid = notebook.topicId || notebook.topicid;
+  UndoManager.sharedInstance().undoGrouping(
+    "创建笔记",
+    topicid,
+    function () {
+      var note = Note.createWithTitleNotebookDocument("新笔记", notebook, doc);
+      // note 为 MbBookNote
+    }
+  );
+  Application.sharedInstance().refreshAfterDBChanged(topicid);
+}
+```
+
+## 删除笔记
+
+- `Database.sharedInstance().deleteBookNote(noteId)`：只删除该条笔记，不删子节点。
+- `Database.sharedInstance().deleteBookNoteTree(noteId)`：删除该笔记及其所有后代。
+
+删除后也应调用 `Application.sharedInstance().refreshAfterDBChanged(topicid)` 刷新对应笔记本界面。
+
+## 示例：根据 noteId 修改标题并刷新
+
+```javascript
+var noteId = "A_VALID_NOTE_ID";
+var note = Database.sharedInstance().getNoteById(noteId);
+if (note) {
+  var topicid = note.notebookId;
+  UndoManager.sharedInstance().undoGrouping(
+    "修改标题",
+    topicid,
+    function () {
+      note.noteTitle = "由插件修改后的标题";
+    }
+  );
+  Application.sharedInstance().refreshAfterDBChanged(topicid);
+}
+```
+
+## 相关
+
+- [Database](/reference/global/database/)、[MbBookNote](/reference/marginnote/mb-book-note/)、[UndoManager](/reference/utility/undo-manager/)
+- [Cookbook：批量修改笔记标题](/guides/cookbook/batch-rename-notes/)