mn-docs-mcp 0.1.0

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

@@ -0,0 +1,105 @@
+---
+title: 快捷键
+description: 在JSExtension中注册快捷键，并用query/process稳定处理按键。
+---
+
+MarginNote插件提供了一套“扩展快捷键”机制：你可以在插件主类（继承`JSExtension`）中实现`additionalShortcutKeys()`返回快捷键声明，然后用`queryShortcutKeyWithKeyFlags(command,keyFlags)`与`processShortcutKeyWithKeyFlags(command,keyFlags)`完成“可用性判断”和“按下处理”。
+
+本页按标准教程结构介绍该机制：接口作用、注册方式、推荐实现范式、参数语义、组合键选择建议与常见坑。
+
+## 概述
+
+扩展快捷键适用于：
+
+- 快速触发插件动作（例如打开/关闭面板、执行一次批处理）。
+- 在不方便加按钮的场景提供入口。
+
+边界与限制：
+
+- 当用户正在编辑文本时（firstResponder在输入框/编辑器上），按键可能被输入控件优先消费，插件快捷键不一定触发。这是预期行为。
+- 组合键可能与系统或应用内建快捷键冲突，导致命中率不稳定；应优先选择冲突更少的组合键，并允许用户自定义（如你的插件有设置页）。
+
+## 接口一览
+
+在插件主类（`JSExtension`子类）中实现以下方法：
+
+| 方法 | 作用 |
+|---|---|
+| `additionalShortcutKeys()` | 声明插件提供的快捷键列表。 |
+| `queryShortcutKeyWithKeyFlags(command,keyFlags)` | 查询某条快捷键/命令在当前上下文是否可用（disabled）以及是否为勾选态（checked）。 |
+| `processShortcutKeyWithKeyFlags(command,keyFlags)` | 处理快捷键按下。真正的业务动作应放在这里。 |
+
+## 注册快捷键：additionalShortcutKeys
+
+`additionalShortcutKeys()`返回一个数组，数组元素为“字典项”（Dictionary）。系统会读取这些字典项并构造对应的键盘命令。
+
+目前已确认字典项的核心字段如下：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `input` | `string` | 按键输入，例如`"UIKeyInputLeftArrow"`、`"z"`、`"["`等。 |
+| `flags` | `number` | 修饰键位掩码（见下方keyFlags表）。 |
+| `title` | `string` | 用于显示的标题。 |
+
+示例（仅演示结构；请按你的插件风格调整）：
+
+```javascript
+additionalShortcutKeys: function () {
+  return [
+    { input: "[", flags: 1179648, title: "MyAddon: Do Something" }, // Command+Shift+[
+  ];
+},
+```
+
+说明：该接口不是直接返回`UIKeyCommand[]`。
+
+## 状态查询vs按下处理：query与process
+
+这两者的职责必须严格区分：
+
+- `queryShortcutKeyWithKeyFlags(...)`用于“查询状态”。系统可能会在可用性判断、快捷键列表重建、焦点变化等场景批量调用它，因此调用次数与传入参数都可能远超你的预期。为了保证性能与行为可控，建议在query中只做轻量判断并返回状态：避免任何IO操作、耗时计算、网络请求、文件读写，以及无差别日志输出；更不要在这里修改笔记/数据库或触发UI。
+- `processShortcutKeyWithKeyFlags(...)`用于“处理按下”。真正的业务动作应放在这里；如果会修改笔记/笔记本数据，建议使用`UndoManager.undoGrouping(...)`包裹，保证撤销/重做稳定。
+
+推荐写法：只匹配你关心的组合键，其余保持静默（例如直接`return null`）。
+
+## command与keyFlags
+
+### command
+
+`command`是系统传入的标识。已确认它可能是：
+
+- 内建命令名：例如`NewChildNote`、`ToggleExpand`、`EditAddTitle`等。
+- 输入常量/字符：例如`UIKeyInputLeftArrow`、`UIKeyInputUpArrow`，以及`z`这类字符输入。
+
+因此在你的实现里，应以“你在additionalShortcutKeys里声明的输入(input)+修饰键(flags)”为依据进行匹配，而不是假设`command`永远是某一种固定形式。
+
+### 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` |
+
+
+## 组合键选择建议
+
+- 优先选择不常被系统/应用占用的组合键。
+- 避免与“通用编辑快捷键”冲突（例如撤销/重做/复制粘贴等），除非你非常确定不会影响用户习惯。
+- 若某个组合键命中率不稳定，通常是冲突或编辑态吞键导致；建议提供替代键位或设置项。
+
+## 注意事项
+
+- 在query里做副作用：导致“未按下也触发动作”、撤销链异常、或出现难以定位的状态错乱。
+- 无差别打印日志：query可能被批量调用，导致刷屏，反而遮蔽真正有用的命中日志。
+- 忽略编辑态：用户在输入时快捷键不触发属于预期，需要在产品交互上规避或提示。
+
+## 相关
+
+- API参考：[JSExtension](/reference/marginnote/jsextension/)
+- 内建命令：[Application](/reference/global/application/)与[内建command清单](/reference/global/builtin-commands/)
+- 获取选中与焦点：[脑图与选区](/guides/mindmap-and-selection/)

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

@@ -0,0 +1,91 @@
+---
+title: 存储与文件
+description: 使用 NSUserDefaults 持久化配置，使用 NSFileManager 与 NSData 读写文件。
+---
+
+插件需要保存设置或读写文件时，可使用 Foundation 提供的 NSUserDefaults、NSFileManager 和 NSData；路径可基于 `Application.sharedInstance().documentPath` 或 `tempPath`。
+
+## NSUserDefaults：简单键值存储
+
+适合保存开关、数字、字符串等少量配置。
+
+```javascript
+var defaults = NSUserDefaults.standardUserDefaults();
+
+// 写入
+defaults.setObjectForKey("enabled", "my_addon_setting");
+defaults.setIntegerForKey(10, "my_addon_counter");
+defaults.setBoolForKey(true, "my_addon_switch");
+
+// 读取
+var setting = defaults.objectForKey("my_addon_setting");
+var counter = defaults.integerForKey("my_addon_counter");
+var on = defaults.boolForKey("my_addon_switch");
+```
+
+键名建议加插件前缀，避免与其他插件冲突。
+
+## NSFileManager：目录与文件
+
+获取应用文稿目录并在其下创建插件专用目录：
+
+```javascript
+var app = Application.sharedInstance();
+var basePath = app.documentPath + "/MyAddonData";
+var fileManager = NSFileManager.defaultManager();
+
+if (!fileManager.fileExistsAtPath(basePath)) {
+  fileManager.createDirectoryAtPathWithIntermediateDirectoriesAttributes(basePath, true, null);
+}
+```
+
+写入文本文件（UTF-8 编码 4）：
+
+```javascript
+var filePath = basePath + "/config.txt";
+var textData = NSData.dataWithStringEncoding("Hello, World!", 4);
+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 解析。
+
+示例：从文件读取 JSON 并解析
+
+```javascript
+var data = NSData.dataWithContentsOfFile(filePath);
+if (data && data.length() > 0) {
+  var obj = NSJSONSerialization.JSONObjectWithDataOptions(data, 0);
+  if (NSJSONSerialization.isValidJSONObject(obj)) {
+    // obj 为 JS 对象，可直接使用
+  }
+}
+```
+
+## 路径说明
+
+- `Application.sharedInstance().documentPath`：文稿目录，适合存放用户数据。
+- `Application.sharedInstance().tempPath`：临时目录，系统可能清理。
+- 插件包根路径由 `JSB.newAddon(mainPath)` 的 `mainPath` 传入，可用于读取包内资源（如图标）。
+
+## 完整示例：保存与读取一个开关
+
+在插件中提供「是否显示面板」的开关，并持久化：
+
+```javascript
+// 读取
+var showPanel = NSUserDefaults.standardUserDefaults().boolForKey("my_addon_show_panel");
+
+// 用户点击开关后写入
+NSUserDefaults.standardUserDefaults().setBoolForKey(newValue, "my_addon_show_panel");
+```
+
+结合 [工具栏与命令](/guides/toolbar-and-commands/) 与 [生命周期与窗口](/guides/lifecycle-and-window/)，在 `notebookWillOpen` 延迟后根据该键决定是否 `addSubview` 面板。
+
+## 相关
+
+- [NSUserDefaults](/reference/foundation/ns-user-defaults/)、[NSFileManager](/reference/foundation/ns-file-manager/)、[NSData](/reference/foundation/ns-data/)
+- [Cookbook：插件设置页](/guides/cookbook/addon-settings/)
+- [网络请求](/guides/network-requests/) —— 网络响应 NSData 的 JSON 解析同理

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

@@ -0,0 +1,64 @@
+---
+title: 工具栏与命令
+description: 在 MarginNote 工具栏显示插件按钮并响应点击。
+---
+
+通过实现 `queryAddonCommandStatus()` 并在返回值中提供图标、target、selector 和 checked 状态，可以在 MarginNote 工具栏上显示一个插件按钮；用户点击时，会调用你指定的实例方法（如 `toggleSample:`）。
+
+## 返回格式
+
+MarginNote 会调用插件的 `queryAddonCommandStatus()`。若希望显示工具栏按钮，必须返回一个对象，包含：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `image` | string | 图标文件名（相对于插件包根目录，如 `'sample.png'`）。 |
+| `object` | object | 接收点击的对象，通常为 `self`（插件实例）。 |
+| `selector` | string | 点击时调用的方法名，**必须以冒号结尾**（如 `'toggleSample:'`）。 |
+| `checked` | boolean | 是否显示为「选中」状态（如面板是否已显示）。 |
+
+若不希望显示按钮，可返回 `null`。
+
+## 在实例方法中实现点击
+
+selector 对应的方法必须是 **JSB.defineClass 的实例方法**，且方法名带冒号（例如 `toggleSample:`）。这样在方法内可以使用 `self` 访问插件实例和 `self.window`。
+
+示例：切换一个浮窗的显示/隐藏，并记住状态到 NSUserDefaults，最后刷新工具栏状态：
+
+```javascript
+queryAddonCommandStatus: function () {
+  return {
+    image: "sample.png",
+    object: self,
+    selector: "toggleSample:",
+    checked: self.sampleController.view.window ? true : false,
+  };
+},
+toggleSample: function (sender) {
+  if (self.sampleController.view.window) {
+    self.sampleController.view.removeFromSuperview();
+    NSUserDefaults.standardUserDefaults().setObjectForKey(false, "my_addon_panel_on");
+  } else {
+    Application.sharedInstance().studyController(self.window).view.addSubview(self.sampleController.view);
+    self.layoutViewController();
+    NSUserDefaults.standardUserDefaults().setObjectForKey(true, "my_addon_panel_on");
+  }
+  Application.sharedInstance().studyController(self.window).refreshAddonCommands();
+},
+```
+
+## 刷新工具栏图标状态
+
+修改了「是否显示面板」等状态后，应调用当前窗口的 `studyController.refreshAddonCommands()`，这样工具栏图标的 checked 状态会更新。
+
+## 完整流程简述
+
+1. 在 `sceneWillConnect` 中创建你的 viewController 或视图，并定义 `layoutViewController`（在 `controllerWillLayoutSubviews` 中调用）。
+2. 在 `notebookWillOpen` 里用 NSTimer 延迟 0.2 秒后，若 NSUserDefaults 中为「显示面板」，则 `studyController.view.addSubview(...)` 并 `refreshAddonCommands()`。
+3. 实现 `queryAddonCommandStatus` 返回 `image / object / selector / checked`。
+4. 实现 `toggleSample:`（或你命名的 selector）切换面板显示并刷新。
+
+## 相关
+
+- [JSExtension](/reference/marginnote/jsextension/) — queryAddonCommandStatus
+- [StudyController](/reference/marginnote/study-controller/) — refreshAddonCommands
+- [原生 UI](/guides/native-ui/) — 创建面板视图

package/src/content/docs/index.mdx

@@ -0,0 +1,44 @@
+---
+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
+---
+
+import { Card, CardGrid } from '@astrojs/starlight/components';
+
+## 从这里开始
+
+<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>

package/src/content/docs/reference/black-box.md

@@ -0,0 +1,19 @@
+---
+title: 隐藏的边界（The Black Box）
+description: 只作为属性返回、但没有 JSExport 接口文件的对象与风险边界。
+---
+
+本节记录一些在 API 中可能“能拿到对象实例”，但由于**没有对应的 `JSB*.h`（JSExport）接口文件**，因此你无法在 JS 中安全地调用其独有方法的“黑盒对象”。
+
+典型表现：某个对象作为属性被返回，但你在文档/头文件清单里找不到它的 JSB 接口定义。
+
+## 例子
+
+- `NSLayoutManager`：常见于 `UITextView` 相关属性，但未见 `JSBNSLayoutManager.h`。
+- `NSTextContainer`：同上。
+- `UIFontDescriptor`：在头文件中被注释掉或未导出。
+
+## 建议
+
+- **不要**依赖 KVC/KVO 等高危手段“硬调用”黑盒对象。
+- 如果必须实现相关功能：优先寻找已导出对象提供的替代 API（例如通过 `UITextView`/`NSAttributedString` 侧可用方法绕开）。