mn-docs-mcp 0.6.2 → 1.0.0

package/astro.config.mjs

@@ -58,7 +58,10 @@ export default defineConfig({
 								{ label: 'Application', slug: 'reference/global/application' },
 								{ label: 'SearchManager', slug: 'reference/global/search-manager' },
 								{ label: 'Database', slug: 'reference/global/database' },
+								{ label: 'Document', slug: 'reference/global/document' },
+								{ label: 'Notebook', slug: 'reference/global/notebook' },
 								{ label: 'Note', slug: 'reference/global/note' },
+								{ label: 'AgentTools', slug: 'reference/global/agent-tools' },
 								{ label: 'PopupMenu', slug: 'reference/global/popup-menu' },
 								{ label: 'PopupMenuItem', slug: 'reference/global/popup-menu-item' },
 								{ label: 'self', slug: 'reference/global/self' },
@@ -102,6 +105,7 @@ export default defineConfig({
 							label: '运行时边界',
 							items: [
 								{ label: 'JavaScript 原生环境', slug: 'reference/js-runtime' },
+								{ label: 'Value Sturct', slug: 'reference/value-sturct' },
 								{ label: '隐藏的边界（The Black Box）', slug: 'reference/black-box' },
 							],
 						},

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mn-docs-mcp",
   "type": "module",
-  "version": "0.6.2",
+  "version": "1.0.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/Temsys-Shen/marginnote-addon-docs.git"

package/src/content/docs/guides/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 页）、涉及文件或路径、简要说明。
 
 ## 文档结构约定
 
@@ -76,7 +76,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/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/mindmap-and-selection.md

@@ -29,7 +29,7 @@ var document = docController.document;           // MbBook
 var selectionText = docController.selectionText; // 用户选中的文本
 ```
 
-若用户未选中任何内容，`selectionText` 可能为 undefined 或空字符串。
+若用户未选中任何内容，`selectionText` 为 undefined 或空字符串。
 
 ## 在脑图中高亮指定笔记
 

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` 的第二个参数中定义：
 

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,7 +297,7 @@ 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 与纯文本。
 

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();

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` 传入，可用于读取包内资源（如图标）。
 
 ## 完整示例：保存与读取一个开关

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/reference/black-box.md

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

package/src/content/docs/reference/foundation/ns-attributed-string.md

@@ -3,7 +3,7 @@ title: NSAttributedString
 description: 富文本字符串（只读）。
 ---
 
-`NSAttributedString` 表示带属性（字体、颜色、段落样式等）的只读富文本。你可能会在 UI 文本渲染、富文本评论/编辑等场景中遇到它。
+`NSAttributedString` 表示带属性（字体、颜色、段落样式等）的只读富文本。你会在 UI 文本渲染、富文本评论/编辑等场景中遇到它。
 
 ## 实例成员 (Instance members)
 

package/src/content/docs/reference/foundation/ns-counted-set.md

@@ -75,4 +75,4 @@ removeObject(object: any): void
 
 ## 类成员 (Class members)
 
-当前运行时未额外暴露 `NSCountedSet` 的类成员。
+当前接口未额外暴露 `NSCountedSet` 的类成员。

package/src/content/docs/reference/foundation/ns-date-components.md

@@ -3,7 +3,7 @@ title: NSDateComponents
 description: 日期组成部分（年/月/日/时/分/秒等）。
 ---
 
-`NSDateComponents` 用于表示日期的组成部分（年/月/日/时/分/秒等）。通常与 `NSCalendar`（如可用）配合用于构造/分解日期。
+`NSDateComponents` 用于表示日期的组成部分（年/月/日/时/分/秒等）。默认与 `NSCalendar`（如可用）配合用于构造/分解日期。
 
 ## 实例成员 (Instance members)
 
@@ -16,7 +16,7 @@ description: 日期组成部分（年/月/日/时/分/秒等）。
 
 ## 类成员 (Class members)
 
-当前运行时未额外暴露 `NSDateComponents` 的类成员。
+当前接口未额外暴露 `NSDateComponents` 的类成员。
 
 ## 相关
 

package/src/content/docs/reference/foundation/ns-date-formatter.md

@@ -9,13 +9,11 @@ description: 日期格式化与解析。
 
 ### 创建
 
-通过 `new()` 或 `alloc().init()` 创建（视环境可用方式）。
+通过 `new NSDateFormatter()` 创建。
 
 ```javascript
 // 示例
 var formatter = new NSDateFormatter();
-// 或
-var formatter = NSDateFormatter.alloc().init();
 ```
 
 ## 实例成员 (Instance members)

package/src/content/docs/reference/foundation/ns-decimal-number.md

@@ -434,4 +434,4 @@ descriptionWithLocale(locale: any): string
 
 ### isEqualToNumber（未导出）
 
-`isEqualToNumber(...)` 在最新头文件导出清单中未暴露；如需比较请使用 `compare(...)` 或先转为标量后比较（以运行时行为为准）。
+`isEqualToNumber(...)` 在最新头文件导出清单中未暴露；如需比较请使用 `compare(...)` 或先转为标量后比较（由接口行为定义）。

package/src/content/docs/reference/foundation/ns-enumerator.md

@@ -33,4 +33,4 @@ allObjects(): NSArray
 
 ## 类成员 (Class members)
 
-当前运行时未额外暴露 `NSEnumerator` 的类成员。
+当前接口未额外暴露 `NSEnumerator` 的类成员。

package/src/content/docs/reference/foundation/ns-error.md

@@ -3,7 +3,7 @@ title: NSError
 description: 错误对象，包含 domain/code/userInfo 与本地化描述信息。
 ---
 
-`NSError` 用于表示错误信息。网络请求（如 `NSURLConnection`）或文件API可能通过`NSError **`返回错误对象，JS侧通常作为回调参数或返回值的一部分出现。
+`NSError` 用于表示错误信息。网络请求（如 `NSURLConnection`）或文件API会通过`NSError **`返回错误对象，JS侧默认作为回调参数或返回值的一部分出现。
 
 ## 类成员 (Class members)
 
@@ -44,7 +44,7 @@ static errorWithDomainCodeUserInfo(domain: string, code: number, userInfo: NSDic
 
 ### `initWithDomainCodeUserInfo`
 
-初始化错误实例（通常由工厂方法创建，较少直接调用）。
+初始化错误实例（默认由工厂方法创建，较少直接调用）。
 
 ```javascript
 initWithDomainCodeUserInfo(domain: string, code: number, userInfo: NSDictionary): void

package/src/content/docs/reference/foundation/ns-file-manager.md

@@ -65,7 +65,7 @@ createDirectoryAtPathWithIntermediateDirectoriesAttributes(path: string, withInt
 | :--- | :--- | :--- |
 | `path` | `string` | 目录路径。 |
 | `withIntermediateDirectories` | `boolean` | 是否创建中间目录。 |
-| `attributes` | `NSDictionary \| null` | 目录属性（通常传 null）。 |
+| `attributes` | `NSDictionary \| null` | 目录属性（默认传 null）。 |
 
 ### `createDirectoryAtPathAttributes` (简易版)
 

package/src/content/docs/reference/foundation/ns-formatter.md

@@ -5,7 +5,7 @@ description: 格式化基类（对象↔字符串转换）。
 
 `NSFormatter` 是格式化器基类，用于把对象转换成字符串、或从字符串解析回对象。
 
-在插件环境里更常用的是其具体子类（例如 `NSDateFormatter`、`NSNumberFormatter`）。
+常用的是其具体子类（例如 `NSDateFormatter`、`NSNumberFormatter`）。
 
 ## 实例成员 (Instance members)
 
@@ -128,4 +128,4 @@ isPartialStringValidProposedSelectedRangeOriginalStringOriginalSelectedRangeErro
 
 ## 类成员 (Class members)
 
-当前运行时未额外暴露 `NSFormatter` 的类成员。
+当前接口未额外暴露 `NSFormatter` 的类成员。

package/src/content/docs/reference/foundation/ns-json-serialization.md

@@ -7,7 +7,7 @@ description: JSON 与 Foundation 对象之间的序列化与反序列化。
 
 ## 实例成员 (Instance members)
 
-当前运行时未额外暴露 `NSJSONSerialization` 的实例成员；通常直接使用其类成员完成序列化/反序列化。
+当前接口未额外暴露 `NSJSONSerialization` 的实例成员；默认直接使用其类成员完成序列化/反序列化。
 
 ## 类成员 (Class members)
 
@@ -17,7 +17,15 @@ description: JSON 与 Foundation 对象之间的序列化与反序列化。
 | `dataWithJSONObjectOptions(obj, options)` | obj, options: number | NSData | 将对象/数组序列化为 NSData。 |
 | `JSONObjectWithDataOptions(data, options)` | data: NSData, options: number | any | 将 NSData 解析为对象/数组。 |
 
-options 通常传 0。最新导出接口不包含 error 参数；若解析/序列化失败，通常以返回值/异常表现为准（建议在控制台打印并做兼容处理）。
+`options`默认传`0`。最新导出接口不包含`error`参数。
+
+### 已确认行为
+
+- `JSONObjectWithDataOptions(data, 0)`解析非法JSON时返回`undefined`，不抛桥接层错误。
+- `dataWithJSONObjectOptions(obj, 0)`在传入包含函数成员的对象时，插件环境仍会返回`NSData`。
+- `isValidJSONObject(obj)`对包含函数成员的对象返回`true`。
+
+要求：不要只依赖`isValidJSONObject`判断可序列化性，序列化后仍应检查返回值并记录日志。
 
 ## 相关
 

package/src/content/docs/reference/foundation/ns-mutable-attributed-string.md

@@ -333,4 +333,4 @@ readFromDataOptionsDocumentAttributesError(data: NSData, opts: NSDictionary, dic
 
 ## 类成员 (Class members)
 
-当前运行时未额外暴露 `NSMutableAttributedString` 的类成员。
+当前接口未额外暴露 `NSMutableAttributedString` 的类成员。

package/src/content/docs/reference/foundation/ns-mutable-character-set.md

@@ -129,4 +129,4 @@ formIntersectionWithCharacterSet(otherSet: NSCharacterSet): void
 
 ## 类成员 (Class members)
 
-当前运行时未额外暴露 `NSMutableCharacterSet` 的类成员。
+当前接口未额外暴露 `NSMutableCharacterSet` 的类成员。

package/src/content/docs/reference/foundation/ns-mutable-dictionary.md

@@ -41,7 +41,7 @@ static dictionaryWithSharedKeySet(sharedKeySet: any): NSMutableDictionary
 static sharedKeySetForKeys(keys: NSArray): any
 ```
 
-> 注：`NSMutableDictionary` 的工厂方法在插件运行时的导出范围较小；请以本页底部的「头文件 API 清单」为准。
+> 注：`NSMutableDictionary` 的工厂方法在插件环境的导出范围较小；请以本页底部的「头文件 API 清单」为准。
 
 ## 实例成员 (Instance members)
 

package/src/content/docs/reference/foundation/ns-mutable-index-set.md

@@ -148,7 +148,7 @@ shiftIndexesStartingAtIndexBy(index: number, delta: number): void
 
 ## 类成员 (Class members)
 
-当前运行时未额外暴露 `NSMutableIndexSet` 的类成员。
+当前接口未额外暴露 `NSMutableIndexSet` 的类成员。
 
 ## 相关
 

package/src/content/docs/reference/foundation/ns-mutable-set.md

@@ -3,7 +3,7 @@ title: NSMutableSet
 description: 可变无序集合（可增删的去重容器）。
 ---
 
-`NSMutableSet` 是可变集合，适合在运行时构造或更新一个“去重集合”。
+`NSMutableSet` 是可变集合，适合构造或更新一个“去重集合”。
 
 ## 类成员 (Class members)
 

package/src/content/docs/reference/foundation/ns-mutable-string.md

@@ -133,7 +133,7 @@ setString(aString: string): void
 
 ### `initWithCapacity`
 
-用容量初始化（通常由工厂方法创建）。
+用容量初始化（默认由工厂方法创建）。
 
 ```javascript
 initWithCapacity(capacity: number): void

package/src/content/docs/reference/foundation/ns-mutable-url-request.md

@@ -5,7 +5,7 @@ description: 可变 URL 请求对象（NSURLRequest 子类），用于设置 met
 
 完整用法见 [网络请求](/guides/network-requests/) 教程。
 
-`NSMutableURLRequest` 继承自 `NSURLRequest`，用于构造可变的 HTTP 请求（设置 method/header/body 等）。在插件的网络请求里（例如 `NSURLConnection`）通常用它来构造请求。
+`NSMutableURLRequest` 继承自 `NSURLRequest`，用于构造可变的 HTTP 请求（设置 method/header/body 等）。在插件的网络请求里（例如 `NSURLConnection`）默认用它来构造请求。
 
 ## 实例成员 (Instance members)
 
@@ -20,7 +20,6 @@ req.setHTTPBody(NSData.dataWithStringEncoding("{}", 4));
 
 ## 类成员 (Class members)
 
-当前运行时未额外在本文列出 `NSMutableURLRequest` 的类成员；通常通过 `requestWithURL(...)` 等工厂方法创建（以你的运行时实际暴露为准，站内搜索即可定位）。
+`NSMutableURLRequest` 通过 `requestWithURL(...)` 工厂方法创建。
 
 相关：[网络请求](/guides/network-requests/) 教程含完整请求构建示例。
-

package/src/content/docs/reference/foundation/ns-null.md

@@ -21,4 +21,4 @@ static null(): NSNull
 
 ## 实例成员 (Instance members)
 
-`NSNull` 的实例通常只作为“占位空值”使用，不需要调用其上的成员。
+`NSNull` 的实例默认只作为“占位空值”使用，不需要调用其上的成员。

package/src/content/docs/reference/foundation/ns-number-formatter.md

@@ -117,7 +117,7 @@ getObjectValueForStringRangeError(obj: any, string: string, rangep: any, error:
 
 - `boolean`: 是否解析成功。
 
-### 常用配置（属性/方法）
+### 配置（属性/方法）
 
 | 方法/属性 | 说明 |
 | :--- | :--- |

package/src/content/docs/reference/foundation/ns-operation.md

@@ -5,7 +5,7 @@ description: 可调度的任务单元，常与 NSOperationQueue 配合使用。
 
 `NSOperation` 表示一个可调度任务。常与 `NSOperationQueue` 搭配，用于异步调度（例如 `NSURLConnection.sendAsynchronousRequest...` 的 queue 参数）。
 
-> 注意：在插件环境里通常直接使用 `NSOperationQueue.mainQueue()` / `currentQueue()` 即可，不一定需要手动构造自定义 operation。
+> 注意：默认直接使用 `NSOperationQueue.mainQueue()` / `currentQueue()` 即可，不会稳定需要手动构造自定义 operation。
 
 ## 实例成员 (Instance members)
 
@@ -245,4 +245,4 @@ setThreadPriority(p: number): void
 
 ## 类成员 (Class members)
 
-当前运行时未额外暴露 `NSOperation` 的类成员。
+当前接口未额外暴露 `NSOperation` 的类成员。

package/src/content/docs/reference/foundation/ns-pointer-array.md

@@ -3,7 +3,7 @@ title: NSPointerArray
 description: 指针数组（可配置强/弱引用语义）。
 ---
 
-`NSPointerArray` 是“指针数组”容器，允许存放对象指针或空洞，并支持强/弱语义（例如 `weakObjectsPointerArray()`）。在插件里通常把它当成“特殊数组”来用。
+`NSPointerArray` 是“指针数组”容器，允许存放对象指针或空洞，并支持强/弱语义（例如 `weakObjectsPointerArray()`）。在插件里默认把它当成“特殊数组”来用。
 
 ## 类成员 (Class members)
 

package/src/content/docs/reference/foundation/ns-proxy.md

@@ -3,10 +3,12 @@ title: NSProxy
 description: 代理基类（消息转发基础设施）。
 ---
 
-`NSProxy`是系统代理基类，提供消息转发相关能力。在插件环境中，你一般不会直接创建它，但可能会在调试/反射/桥接场景里遇到它的基础方法。
+`NSProxy`是系统代理基类，提供消息转发相关能力。你直接不会直接创建它，但会在调试/反射/桥接场景里遇到它的基础方法。
 
 ## 类成员 (Class members)
 
+> 注意：插件业务代码不建议调用`alloc/allocWithZone`，推荐使用`.new()`或工厂方法。
+
 ### `alloc`
 
 分配实例。
@@ -107,7 +109,7 @@ forwardInvocation(invocation: any): void
 
 ### `dealloc`
 
-析构（通常不直接调用）。
+析构。
 
 ```javascript
 dealloc(): void
@@ -119,7 +121,7 @@ dealloc(): void
 
 ### `finalize`
 
-终结（通常不直接调用）。
+终结。
 
 ```javascript
 finalize(): void

package/src/content/docs/reference/foundation/ns-scanner.md

@@ -445,4 +445,10 @@ isAtEnd(): boolean
 
 - `boolean`: 是否到末尾。
 
-> 注：`scanUpToEndOfStringIntoString(...)` 在最新头文件导出清单中未暴露；可结合 `isAtEnd()` 与 `scanUpToStringIntoString(...)` / `scanUpToCharactersFromSetIntoString(...)` 实现类似效果（以运行时行为为准）。
+> 注：`scanUpToEndOfStringIntoString(...)`在最新头文件导出清单中未暴露；可结合`isAtEnd()`与`scanUpToStringIntoString(...)`/`scanUpToCharactersFromSetIntoString(...)`实现类似效果。
+>
+> 已确认边界行为：
+>
+> - 空字符串时`isAtEnd()`为`true`。
+> - 全空白字符串在默认跳过规则下`isAtEnd()`为`true`。
+> - `setScanLocation(pos)`传入越界值有崩溃风险，先把`pos`钳制到`[0, string.length]`。