mn-docs-mcp 0.1.0

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

@@ -0,0 +1,158 @@
+---
+title: 在插件中嵌入 WebView 面板
+description: 从工具栏打开浮窗，浮窗内为 UIWebView，加载本地或内联 HTML，并与插件双向通信。
+---
+
+**场景**：用户点击插件工具栏按钮后，在主界面上显示一个浮窗面板，面板内为 [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/)。
+
+下文给出与 Samples/UIKit/WebView 同构的完整代码：main.js 中挂面板与切换显示，MyWebViewController.js 中创建 WebView、生命周期与 delegate。
+
+---
+
+## main.js 中挂载面板
+
+在 `JSB.newAddon` 内 **只** 在入口 require 一次 ViewController，在 `sceneWillConnect` 中创建实例并定义 `layoutViewController`，在 `notebookWillOpen` 中根据持久化 key 决定是否加 view，在 `toggleWebViewPanel` 中切换显示/隐藏；显示面板后可用 NSTimer 调用 `becomeFirstResponder` 便于在 iOS 上收起键盘。
+
+```javascript
+JSB.newAddon = function (mainPath) {
+  JSB.require('MyWebViewController');
+  var newAddonClass = JSB.defineClass('MyWebViewAddon : JSExtension', {
+    sceneWillConnect: function () {
+      var self = this;
+      self.layoutViewController = function () {
+        var frame = Application.sharedInstance().studyController(self.window).view.bounds;
+        var width = frame.width > 300 ? (300 + (frame.width - 300) / 2) : 300;
+        self.webViewController.view.frame = {
+          x: (frame.width - width) / 2,
+          y: frame.height - 500,
+          width: width,
+          height: 480
+        };
+      };
+      self.webViewController = MyWebViewController.new();
+      self.webViewController.mainPath = mainPath;
+    },
+    notebookWillOpen: function (topicid) {
+      var self = this;
+      NSTimer.scheduledTimerWithTimeInterval(0.2, false, function () {
+        var on = NSUserDefaults.standardUserDefaults().objectForKey('my_webview_panel_on');
+        if (on === true) {
+          Application.sharedInstance().studyController(self.window).view.addSubview(self.webViewController.view);
+          self.layoutViewController();
+          Application.sharedInstance().studyController(self.window).refreshAddonCommands();
+        }
+      });
+    },
+    controllerWillLayoutSubviews: function (controller) {
+      if (controller === Application.sharedInstance().studyController(self.window)) {
+        this.layoutViewController();
+      }
+    },
+    queryAddonCommandStatus: function () {
+      return {
+        image: 'icon.png',
+        object: this,
+        selector: 'toggleWebViewPanel:',
+        checked: this.webViewController.view.window ? true : false
+      };
+    },
+    toggleWebViewPanel: function (sender) {
+      var self = this;
+      if (self.webViewController.view.window) {
+        self.webViewController.view.removeFromSuperview();
+        NSUserDefaults.standardUserDefaults().setObjectForKey(false, 'my_webview_panel_on');
+      } else {
+        Application.sharedInstance().studyController(self.window).view.addSubview(self.webViewController.view);
+        self.layoutViewController();
+        NSUserDefaults.standardUserDefaults().setObjectForKey(true, 'my_webview_panel_on');
+        NSTimer.scheduledTimerWithTimeInterval(0.2, false, function () {
+          Application.sharedInstance().studyController(self.window).becomeFirstResponder();
+        });
+      }
+      Application.sharedInstance().studyController(self.window).refreshAddonCommands();
+    }
+  }, {});
+  return newAddonClass;
+};
+```
+
+---
+
+## MyWebViewController.js
+
+将以下代码保存为 `MyWebViewController.js`，在入口中通过 `JSB.require('MyWebViewController')` 加载（见上一节）。
+
+- **viewDidLoad**：创建 UIWebView，设置 `backgroundColor`、`scalesPageToFit`、`autoresizingMask`、`delegate`，`addSubview` 后 `loadRequest` 或 `loadHTMLStringBaseURL(html, null)`。
+- **viewWillAppear**：`self.webView.delegate = self`。
+- **viewWillDisappear**：`self.webView.stopLoading()`，`self.webView.delegate = null`。
+- **webViewDidStartLoad / webViewDidFinishLoad**：可按需开关 `UIApplication.sharedApplication().networkActivityIndicatorVisible`。
+- **webViewDidFailLoadWithError**：用 `error.localizedDescription` 替换错误页 HTML 中的占位符，`loadHTMLStringBaseURL(errorString, null)` 显示。
+- **webViewShouldStartLoadWithRequestNavigationType**：若需双向通信，在此判断 `request.URL` 的 scheme（如 `marginnote`），解析后执行插件逻辑并 **return false**；否则 **return true**。
+
+```javascript
+var MyWebViewController = JSB.defineClass('MyWebViewController : UIViewController <UIWebViewDelegate>', {
+  viewDidLoad: function () {
+    self.view.backgroundColor = UIColor.whiteColor();
+    self.view.layer.shadowOffset = { width: 0, height: 0 };
+    self.view.layer.shadowRadius = 10;
+    self.view.layer.shadowOpacity = 0.5;
+    self.view.layer.shadowColor = UIColor.colorWithWhiteAlpha(0.5, 1);
+
+    var webFrame = { x: 0, y: 0, width: self.view.bounds.width, height: self.view.bounds.height };
+    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);
+
+    var html = '<!DOCTYPE html><html><body><p id="text">Hello</p><button id="btn">通知插件</button><script>document.getElementById("btn").onclick=function(){ window.location.href="marginnote://notify?msg="+encodeURIComponent("from page"); };</script></body></html>';
+    self.webView.loadHTMLStringBaseURL(html, null);
+  },
+  viewWillAppear: function (animated) {
+    self.webView.delegate = self;
+  },
+  viewWillDisappear: function (animated) {
+    self.webView.stopLoading();
+    self.webView.delegate = null;
+    UIApplication.sharedApplication().networkActivityIndicatorVisible = false;
+  },
+  webViewDidStartLoad: function (webView) {
+    UIApplication.sharedApplication().networkActivityIndicatorVisible = true;
+  },
+  webViewDidFinishLoad: function (webView) {
+    UIApplication.sharedApplication().networkActivityIndicatorVisible = false;
+  },
+  webViewDidFailLoadWithError: function (webView, error) {
+    UIApplication.sharedApplication().networkActivityIndicatorVisible = false;
+    var tpl = "<!DOCTYPE html><html><head><meta charset='utf-8'></head><body><div style='text-align:center;color:red;'>Error: %@</div></body></html>";
+    var errorString = tpl.replace("%@", error.localizedDescription);
+    self.webView.loadHTMLStringBaseURL(errorString, null);
+  },
+  webViewShouldStartLoadWithRequestNavigationType: function (webView, request, type) {
+    var url = request.URL;
+    if (!url) return true;
+    if (url.scheme === 'marginnote') {
+      var host = url.host || '';
+      var query = url.query || '';
+      if (host === 'notify') {
+        var msg = query.replace(/^msg=/, '').replace(/\+/g, ' ');
+        try { msg = decodeURIComponent(msg); } catch (e) {}
+        Application.sharedInstance().showHUD(msg, self.window, 2);
+      }
+      return false;
+    }
+    return true;
+  }
+});
+```
+
+---
+
+## 相关
+
+- [工具栏与命令](/guides/toolbar-and-commands/)、[原生 UI：使用 WebView](/guides/native-ui/#使用-webview)
+- [WebView 内 JS 与插件 JS 双向通信](/guides/cookbook/webview-bidirectional-js/)、[UIWebView](/reference/uikit/uiwebview/)
+- [网络请求](/guides/network-requests/) —— 获取远程数据后注入 HTML 或通过 evaluateJavaScript 注入

package/src/content/docs/guides/cookbook/export-notebook.md

@@ -0,0 +1,48 @@
+---
+title: 导出当前笔记本
+description: 使用 Database.exportNotebook 导出当前笔记本并给出 HUD 提示。
+---
+
+**场景**：用户点击插件按钮后，将当前打开的笔记本导出到指定路径，并显示成功或失败提示。
+
+**步骤**：
+
+1. 获取当前笔记本 ID：`studyController.notebookController.notebookId`。
+2. 确定导出目标路径（如 `Application.sharedInstance().documentPath + "/Exports/" + 笔记本标题 + ".mnbk"`）；若目录不存在，用 NSFileManager 创建。
+3. 调用 `Database.sharedInstance().exportNotebook(topicid, storePath)`，返回 boolean 表示是否成功。
+4. 用 `Application.sharedInstance().showHUD(message, self.window, 2)` 提示用户。
+
+**完整示例**：
+
+```javascript
+function exportCurrentNotebook() {
+  var studyController = Application.sharedInstance().studyController(self.window);
+  if (!studyController) return;
+  var topicid = studyController.notebookController.notebookId;
+  if (!topicid) return;
+
+  var notebook = Database.sharedInstance().getNotebookById(topicid);
+  if (!notebook) return;
+
+  var app = Application.sharedInstance();
+  var baseDir = app.documentPath + "/NotebookExports";
+  var fileManager = NSFileManager.defaultManager();
+  if (!fileManager.fileExistsAtPath(baseDir)) {
+    fileManager.createDirectoryAtPathWithIntermediateDirectoriesAttributes(baseDir, true, null);
+  }
+
+  var safeTitle = (notebook.title || "未命名").replace(/[/\\:*?"<>|]/g, "_");
+  var storePath = baseDir + "/" + safeTitle + "_" + Date.now() + ".mnbk";
+
+  var ok = Database.sharedInstance().exportNotebook(topicid, storePath);
+  if (ok) {
+    app.showHUD("已导出到：" + storePath, self.window, 3);
+  } else {
+    app.alert("导出失败");
+  }
+}
+```
+
+可将 `exportCurrentNotebook` 绑定到工具栏按钮（如 `exportNotebook:`），在对应实例方法中调用即可。
+
+**相关**：[Database](/reference/global/database/)、[MbTopic](/reference/marginnote/mb-topic/)、[NSFileManager](/reference/foundation/ns-file-manager/)

package/src/content/docs/guides/cookbook/focus-note-in-mindmap.md

@@ -0,0 +1,34 @@
+---
+title: 在脑图中高亮指定笔记
+description: 使用 focusNoteInMindMapById 在脑图中滚动并高亮到指定笔记。
+---
+
+**场景**：已知一条笔记的 `noteId`，希望脑图视图滚动并高亮到该节点，方便用户定位。
+
+**步骤**：
+
+1. 获取当前窗口的 StudyController：`Application.sharedInstance().studyController(self.window)`。
+2. 调用 `studyController.focusNoteInMindMapById(noteId)`。
+
+**完整示例**：从当前焦点笔记获取 noteId，再在脑图中高亮（可用于「重新定位到当前笔记」）：
+
+```javascript
+function focusCurrentNoteInMindMap() {
+  var studyController = Application.sharedInstance().studyController(self.window);
+  if (!studyController) return;
+  var focusNote = studyController.notebookController.focusNote;
+  if (!focusNote) {
+    Application.sharedInstance().alert("请先选中一条笔记");
+    return;
+  }
+  studyController.focusNoteInMindMapById(focusNote.noteId);
+}
+```
+
+若 noteId 来自其他来源（如列表选择、搜索结果的某条笔记），直接传入该 noteId 即可：
+
+```javascript
+studyController.focusNoteInMindMapById(someNoteId);
+```
+
+**相关**：[StudyController](/reference/marginnote/study-controller/)、[脑图与选区](/guides/mindmap-and-selection/)

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

@@ -0,0 +1,135 @@
+---
+title: 调用远程 API
+description: 用户点击插件按钮后，用 MNNetwork 调用 REST API，将返回的 JSON 或文本展示或写入笔记。
+---
+
+**场景**：用户点击插件工具栏按钮后，调用某个 REST API（如公开接口），将返回的 JSON 或纯文本解析后通过 HUD/弹窗展示，或追加到当前焦点笔记的评论中。
+
+**前提**：已按 [网络请求](/guides/network-requests/) 在插件内加入完整的 `base64.js` 与 `network.js`，并在入口中先 `JSB.require('base64')` 再 `JSB.require('network')`。以下示例均使用其中的 `MNNetwork.fetch`、`res.json()`、`res.text()`。
+
+**步骤**：
+
+1. 在工具栏命令对应的 selector 中调用封装：`await MNNetwork.fetch(url, options)` 得到响应，在 try 中用 `res.json()`（JSON）或 `res.text()`（纯文本）取结果
+2. 将结果用 `showHUD` / `alert` 展示，或通过 `focusNote.appendTextComment` / `appendMarkdownComment` 写入笔记
+3. 在 catch 中处理错误（如 `alert("请求失败: " + err)`）
+
+---
+
+## 示例一：GET 并显示 HUD
+
+调用公开接口获取一句话，解析 JSON 后用 HUD 显示。使用 [网络请求](/guides/network-requests/) 中的 `MNNetwork` 与 `base64.js`。
+
+```javascript
+// 入口中已执行：JSB.require('base64'); JSB.require('network');
+
+async function fetchQuoteAndShow() {
+  try {
+    var res = await MNNetwork.fetch("https://api.quotable.io/random");
+    var obj = res.json();
+    if (!obj) {
+      Application.sharedInstance().showHUD("响应不是有效 JSON", self.window, 2);
+      return;
+    }
+    var text = (obj.content || obj.quote || JSON.stringify(obj)).substring(0, 80);
+    Application.sharedInstance().showHUD(text, self.window, 3);
+  } catch (err) {
+    Application.sharedInstance().alert("请求失败: " + err);
+  }
+}
+```
+
+将 `fetchQuoteAndShow` 绑定到工具栏按钮的 selector（如 `fetchQuote:`），在 `fetchQuote:` 中调用即可。
+
+---
+
+## 示例二：GET 后写入笔记评论
+
+将 API 返回的文本追加到当前焦点笔记的评论中，使用 `res.json()` 取内容后通过 UndoManager 写入。
+
+```javascript
+async function fetchAndAppendToNote() {
+  var studyController = Application.sharedInstance().studyController(self.window);
+  if (!studyController) return;
+  var focusNote = studyController.notebookController.focusNote;
+  if (!focusNote) {
+    Application.sharedInstance().alert("请先选中一条笔记");
+    return;
+  }
+
+  try {
+    var res = await MNNetwork.fetch("https://api.quotable.io/random");
+    var obj = res.json();
+    if (!obj) return;
+
+    var text = obj.content || obj.quote || JSON.stringify(obj);
+    var topicid = focusNote.notebookId;
+    UndoManager.sharedInstance().undoGrouping("追加 API 结果", topicid, function () {
+      focusNote.appendTextComment(text);
+    });
+    Application.sharedInstance().refreshAfterDBChanged(topicid);
+    Application.sharedInstance().showHUD("已追加到笔记", self.window, 2);
+  } catch (err) {
+    Application.sharedInstance().alert("请求失败: " + err);
+  }
+}
+```
+
+---
+
+## 示例三：带 API Key 的请求
+
+从 `NSUserDefaults` 读取保存的 API Key，通过 `options.headers` 传入。使用 [网络请求](/guides/network-requests/) 中的 `MNNetwork.fetch(url, { headers: { ... } })`。
+
+```javascript
+async function fetchWithAPIKey() {
+  var apiKey = NSUserDefaults.standardUserDefaults().objectForKey("my_addon_api_key");
+  if (!apiKey) {
+    Application.sharedInstance().alert("请先在设置中填写 API Key");
+    return;
+  }
+
+  try {
+    var res = await MNNetwork.fetch("https://api.example.com/data", {
+      headers: {
+        "Authorization": "Bearer " + apiKey,
+        "Accept": "application/json"
+      }
+    });
+    var obj = res.json();
+    if (NSJSONSerialization.isValidJSONObject(obj)) {
+      Application.sharedInstance().showHUD("获取成功", self.window, 2);
+      // 使用 obj...
+    }
+  } catch (err) {
+    Application.sharedInstance().alert("请求失败: " + err);
+  }
+}
+```
+
+API Key 的保存与读取见 [插件设置页](/guides/cookbook/addon-settings/)。保存后可选择调用简单 API 验证 Key 是否有效。
+
+---
+
+## 示例四：纯文本响应（res.text()）
+
+若接口返回的是纯文本（如 `text/plain`），用 `res.text()` 获取字符串。`text()` 依赖 [网络请求](/guides/network-requests/) 中的 `base64.js`（需已 `JSB.require('base64')`）。
+
+```javascript
+async function fetchPlainText() {
+  try {
+    var res = await MNNetwork.fetch("https://example.com/plain");
+    var str = res.text();
+    Application.sharedInstance().showHUD(str.substring(0, 100), self.window, 3);
+  } catch (err) {
+    Application.sharedInstance().alert("请求失败: " + err);
+  }
+}
+```
+
+---
+
+## 相关
+
+- [网络请求](/guides/network-requests/) —— Base64 与 MNNetwork 完整代码、data 转 JSON/文本说明
+- [插件设置页](/guides/cookbook/addon-settings/) —— 存储 API Key
+- [笔记与数据库](/guides/notes-and-database/) —— 修改笔记与 Undo

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

@@ -0,0 +1,112 @@
+---
+title: WebView 内 JS 与插件 JS 双向通信
+description: 通过 evaluateJavaScript 与自定义 URL Scheme 实现插件与 WebView 页面的双向调用。
+---
+
+**场景**：插件内嵌 UIWebView 加载本地或远程 HTML，需要（1）插件向页面注入数据或执行脚本；（2）页面内按钮/脚本触发插件逻辑（如 showHUD、写数据库）。**WebView 内 JS 不能直接访问插件全局对象**（如 JSB、Application），只能通过「插件执行 evaluateJavaScript」或「页面跳转自定义 URL 被 delegate 拦截」实现通信。
+
+**要点**：插件 → 页面用 `webView.evaluateJavaScript(script, completionHandler)`，直接对页面上下文执行 JS；页面 → 插件用自定义 URL（如 `marginnote://notify?msg=...`），在 `webViewShouldStartLoadWithRequestNavigationType` 中判断 `request.URL` 的 scheme，解析后执行插件逻辑并 **return false**。解析 URL 时注意：`marginnote://notify?msg=...` 中 `notify` 在 NSURL 里为 **host**，path 常为空，应使用 `url.host === "notify"` 或同时判断 path。
+
+---
+
+## 插件 → WebView 内 JS
+
+使用 `webView.evaluateJavaScript(javaScriptString, completionHandler)` 在页面上下文中执行 JS。加载完成后（如在 `webViewDidFinishLoad` 中）调用。
+
+**示例**：向页面注入数据并调用页面内全局函数。
+
+```javascript
+// 插件端（在 webViewDidFinishLoad 或用户点击后）
+var data = { title: "来自插件", count: 1 };
+var script = "window.receiveFromAddon && window.receiveFromAddon(" + JSON.stringify(JSON.stringify(data)) + ");";
+self.webView.evaluateJavaScript(script, null);
+
+// 或执行并取回结果
+self.webView.evaluateJavaScript("document.title", function (result) {
+  JSB.log("页面标题: %@", result);
+});
+```
+
+**页面内**（HTML 中）：定义 `window.receiveFromAddon = function(jsonStr) { var data = JSON.parse(jsonStr); ... }` 即可在插件调用时收到数据。
+
+---
+
+## WebView 内 JS → 插件
+
+通过**自定义 URL Scheme** 由插件拦截：页面内执行 `location.href = 'marginnote://notify?msg=...'` 或创建 iframe 的 `src` 为自定义 URL。在 delegate 的 `webViewShouldStartLoadWithRequestNavigationType(webView, request, type)` 中判断 `request.URL` 的 scheme（如 `marginnote`），解析参数并执行插件逻辑，**return false** 阻止实际加载该 URL。
+
+**HTML 片段**（内嵌或通过 `loadHTMLStringBaseURL` 加载）：
+
+```html
+<button id="btn">通知插件</button>
+<script>
+  document.getElementById("btn").onclick = function () {
+    var msg = "Hello from WebView";
+    window.location.href = "marginnote://notify?msg=" + encodeURIComponent(msg);
+  };
+</script>
+```
+
+**插件端**（ViewController 实例成员）：`marginnote://notify?msg=...` 中 `notify` 为 **host**，不要只判断 path。
+
+```javascript
+webViewShouldStartLoadWithRequestNavigationType: function (webView, request, type) {
+  var url = request.URL;
+  if (!url) return true;
+  if (url.scheme !== "marginnote") return true;
+
+  var host = url.host || "";
+  var isNotify = (host === "notify") || ((url.path || "").indexOf("notify") !== -1);
+  if (isNotify) {
+    var query = url.query || "";
+    var msg = query.replace(/^msg=/, "").replace(/\+/g, " ");
+    try { msg = decodeURIComponent(msg); } catch (e) {}
+    Application.sharedInstance().showHUD(msg, self.window, 2);
+    return false;
+  }
+  return false;
+}
+```
+
+---
+
+## 完整最小示例
+
+**1. 插件内创建 WebView 并加载内联 HTML**（在 ViewController 的 viewDidLoad 中）：
+
+```javascript
+var html = [
+  "<!DOCTYPE html><html><body>",
+  "<p id='text'>初始</p>",
+  "<button id='send'>发送到插件</button>",
+  "<script>",
+  "document.getElementById('send').onclick = function() {",
+  "  window.location.href = 'marginnote://notify?msg=' + encodeURIComponent('从页面发出');",
+  "};",
+  "</script>",
+  "</body></html>"
+].join("");
+self.webView = new UIWebView(frame);
+self.webView.delegate = self;
+self.view.addSubview(self.webView);
+self.webView.loadHTMLStringBaseURL(html, null);
+```
+
+**2. 实现 webViewShouldStartLoadWithRequestNavigationType**（见上一节，解析 `marginnote://notify?msg=...` 并 showHUD，return false）。
+
+**3. 插件向页面更新文字**（如在 webViewDidFinishLoad 后执行）：
+
+```javascript
+self.webView.evaluateJavaScript("document.getElementById('text').innerText = '已由插件更新';", null);
+```
+
+即形成「页面点击 → 自定义 URL → 插件拦截并 showHUD」与「插件 evaluateJavaScript 更新页面」的双向通信。
+
+**加载失败**：在 `webViewDidFailLoadWithError` 中用 `error.localizedDescription` 拼 HTML，再 `loadHTMLStringBaseURL(errorString, null)` 显示错误页。
+
+---
+
+## 相关
+
+- [UIWebView](/reference/uikit/uiwebview/)、[原生 UI：使用 WebView](/guides/native-ui/#使用-webview)
+- [Cookbook：在插件中嵌入 WebView 面板](/guides/cookbook/embed-webview-panel/)

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

@@ -0,0 +1,88 @@
+---
+title: 快速开始
+description: 从零运行你的第一个 MarginNote 插件（Hello World）。
+---
+
+本教程将带你创建一个最简插件：在插件窗口连接时显示一条 "Hello World" 的 HUD 提示，并了解 `mnaddon.json` 与入口函数。
+
+## 前提
+
+- 已安装 MarginNote 3 或 MarginNote 4（MN3 建议 3.6.11 及以上）。
+- 了解如何将 .mnaddon 包安装到 MarginNote 并在应用中启用插件。
+
+## 第一步：插件包结构
+
+创建一个文件夹作为插件包，至少包含：
+
+- `main.js`：入口脚本，MarginNote 会加载并执行它。
+- `mnaddon.json`：插件元数据，MarginNote 据此识别插件。
+
+## 第二步：mnaddon.json
+
+在插件包根目录创建 `mnaddon.json`，内容示例：
+
+```json
+{
+  "addonid": "marginnote.extension.samplehelloworld",
+  "author": "你的名字",
+  "title": "Hello World",
+  "version": "1.0",
+  "marginnote_version_min": "3.6.11",
+  "cert_key": ""
+}
+```
+
+- `addonid`：唯一 ID，建议用反向域名。
+- `title`：在 MarginNote 中显示的插件名称。
+- `marginnote_version_min`：最低支持的 MarginNote 版本。
+
+## 第三步：实现 main.js 入口
+
+MarginNote 加载插件时会调用全局函数 `JSB.newAddon(mainPath)`，你必须实现它并返回由 `JSB.defineClass` 创建的**类**（注意是类，不是实例；MarginNote 会自行实例化）。
+
+在 `main.js` 中写入：
+
+```javascript
+JSB.newAddon = function (mainPath) {
+  var newAddonClass = JSB.defineClass(
+    "SampleHelloWorld : JSExtension",
+    {
+      sceneWillConnect: function () {
+        Application.sharedInstance().showHUD("Hello World", self.window, 2);
+      },
+      sceneDidDisconnect: function () {},
+      sceneWillResignActive: function () {},
+      sceneDidBecomeActive: function () {},
+      notebookWillOpen: function (topicid) {},
+      notebookWillClose: function (topicid) {},
+      documentDidOpen: function (docmd5) {},
+      documentWillClose: function (docmd5) {},
+    },
+    {
+      addonDidConnect: function () {},
+      addonWillDisconnect: function () {},
+      applicationWillEnterForeground: function () {},
+      applicationDidEnterBackground: function () {},
+      applicationDidReceiveLocalNotification: function (notify) {},
+    }
+  );
+  return newAddonClass;
+};
+```
+
+说明：
+
+- `JSB.defineClass('类名 : JSExtension', 实例成员, 类成员)` 定义插件类；类名可自取，但必须继承 `JSExtension`。
+- `sceneWillConnect` 在插件窗口即将连接时调用，这里用 `Application.sharedInstance().showHUD(message, view, duration)` 在 `self.window` 上显示 2 秒 HUD。
+- `mainPath` 是插件包根目录路径，可用于加载包内资源。
+
+## 第四步：安装与验证
+
+1. 将包含 `main.js` 和 `mnaddon.json` 的文件夹打包成 `.mnaddon` 文件（本质为 zip：将上述文件放在 zip 根目录，扩展名改为 `.mnaddon`）。
+2. 将 `.mnaddon` 安装到 MarginNote（按应用内说明或文档操作），并在应用中启用该插件。
+3. 打开或切换到一个窗口，使插件窗口连接；应看到 "Hello World" 的 HUD。
+
+## 下一步
+
+- 了解各生命周期方法的调用时机：[生命周期与窗口](/guides/lifecycle-and-window/)。
+- 查阅 [JSB](/reference/global/jsb/)、[Application](/reference/global/application/)、[JSExtension](/reference/marginnote/jsextension/) 的完整 API。

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

@@ -0,0 +1,76 @@
+---
+title: 生命周期与窗口
+description: 理解 scene/notebook/document 生命周期及何时可安全使用 studyController。
+---
+
+插件通过 JSExtension 的生命周期方法感知「窗口」「笔记本」「文档」的创建与销毁。只有在合适的时机才能安全使用 `Application.sharedInstance().studyController(self.window)` 访问脑图与文档。
+
+## 生命周期概览
+
+### 窗口（Scene）
+
+| 方法 | 调用时机 |
+|------|----------|
+| `sceneWillConnect()` | 插件窗口即将创建，可在此做轻量初始化；此时可能还没有打开笔记本。 |
+| `sceneDidDisconnect()` | 插件窗口已断开。 |
+| `sceneWillResignActive()` | 窗口即将失去活跃。 |
+| `sceneDidBecomeActive()` | 窗口变为活跃。 |
+
+### 笔记本
+
+| 方法 | 调用时机 |
+|------|----------|
+| `notebookWillOpen(topicid)` | 某个笔记本即将打开；之后该窗口才会有 `studyController` 对应的学习界面。 |
+| `notebookWillClose(topicid)` | 某个笔记本即将关闭。 |
+
+### 文档
+
+| 方法 | 调用时机 |
+|------|----------|
+| `documentDidOpen(docmd5)` | 某文档已打开。 |
+| `documentWillClose(docmd5)` | 某文档即将关闭。 |
+
+## 何时可使用 studyController
+
+- `studyController(window)` 返回的是**当前窗口**的学习控制器；只有在该窗口已经打开过笔记本、学习界面已就绪时，返回值才可用。
+- 在 `sceneWillConnect` 中通常**还没有**打开笔记本，因此一般不要在这里依赖 `studyController(self.window)` 去访问脑图或文档。
+- 在 `notebookWillOpen(topicid)` 被调用后，该窗口即将或已经拥有学习界面；但若需在「打开笔记本」后立刻挂载 UI，建议用 `NSTimer.scheduledTimerWithTimeInterval(0.2, false, function () { ... })` 延迟约 0.2 秒再执行，以确保 studyController 与 view 已就绪。
+
+## 示例：在笔记本打开时打日志并延迟挂载 UI
+
+下面在 `notebookWillOpen` 中打日志，并在 0.2 秒后检查是否要显示之前保存的浮窗（用 NSUserDefaults 记住状态）：
+
+```javascript
+notebookWillOpen: function (topicid) {
+  JSB.log("MNLOG Open Notebook: %@", topicid);
+
+  NSTimer.scheduledTimerWithTimeInterval(0.2, false, function () {
+    var showPanel = NSUserDefaults.standardUserDefaults().objectForKey("my_addon_show_panel");
+    if (showPanel === true) {
+      var studyController = Application.sharedInstance().studyController(self.window);
+      if (studyController) {
+        studyController.view.addSubview(self.myPanelView);
+        self.layoutMyPanel();
+      }
+    }
+  });
+},
+```
+
+## 布局回调：controllerWillLayoutSubviews
+
+若你在学习界面上添加了自定义视图，窗口尺寸或布局变化时可能需要重新计算位置。实现 `controllerWillLayoutSubviews(controller)`，当传入的 controller 是当前窗口的 studyController 时，在其中更新你的面板 frame（例如根据 `controller.view.bounds` 计算）。
+
+```javascript
+controllerWillLayoutSubviews: function (controller) {
+  if (controller === Application.sharedInstance().studyController(self.window)) {
+    self.layoutMyPanel();
+  }
+},
+```
+
+## 相关
+
+- [JSExtension](/reference/marginnote/jsextension/) — 完整生命周期与可选方法
+- [StudyController](/reference/marginnote/study-controller/) — 通过 studyController 访问脑图与文档
+- [快速开始](/guides/getting-started/)