mn-docs-mcp 0.6.2 → 1.1.0

package/src/content/docs/libmn/vendor-globals.md

@@ -0,0 +1,34 @@
+---
+title: LibMN Vendor Globals
+description: LibMN加载后可用的第三方全局对象与库内真实调用点。
+---
+
+LibMN会在启动阶段加载一组第三方库并把全局对象暴露到JSContext。这里的重点不是重复上游全部API，而是告诉你“LibMN当前实际依赖了哪些能力”。
+
+## 第三方全局对象清单
+
+| 全局对象 | 来源模块 | LibMN已使用能力 | 官方文档 |
+|:---|:---|:---|:---|
+| `CryptoJS` | `vendor/CryptoJS` | `AES.encrypt/decrypt`、`MD5`、`SHA256`、`enc.Base64`、`enc.Utf8`、`lib.WordArray.create` | [CryptoJS](https://github.com/brix/crypto-js) |
+| `marked` | `vendor/marked` | `marked.parse`、`marked.lexer` | [Marked](https://marked.js.org/) |
+| `mustache` | `vendor/mustache` | `mustache.render`、`mustache.parse` | [mustache.js](https://github.com/janl/mustache.js) |
+| `Segmentit` | `vendor/segmentit` | `Segmentit.useDefault`、`Segmentit.Segment` | [Segmentit](https://github.com/linonetwo/segmentit) |
+| `jsonrepair` | `vendor/jsonrepair` | `jsonrepair(...)` | [jsonrepair](https://github.com/josdejong/jsonrepair) |
+| `pako` | `vendor/pako` | `pako.gzip`、`pako.ungzip` | [pako](https://github.com/nodeca/pako) |
+| `LZString` | `vendor/lz-string` | `compressToBase64`、`decompressFromBase64` | [LZString](https://pieroxy.net/blog/pages/lz-string/index.html) |
+| `PDFTools` | `vendor/pdf-bridge-core` | `convertImageBase64ToPdfBase64`、`extractPage` | [AddonLib仓库](https://github.com/Temsys-Shen/marginnote-addon-docs) |
+
+## 依赖策略建议
+
+- 你的业务代码若直接调用这些全局对象，等于直接承担第三方升级风险。
+- 若LibMN中已有对应封装，优先走`MNUtil`或相关包装类，避免把业务和vendor细节绑死。
+- 只有在封装能力不足时再直接访问vendor全局，并在插件内注明版本假设。
+
+## 常见误区
+
+- 误区1:把vendor全局当成LibMN稳定API。
+  说明:它们的稳定性由上游库决定，不由LibMN承诺。
+- 误区2:忽略二进制和编码边界。
+  说明:涉及Base64、压缩、PDF转换时，优先复用`DataConverter`和`MNUtil`现成通路。
+- 误区3:只看单次调用成功就上线。
+  说明:应在不同文档类型、不同笔记本规模下做回归验证。

package/src/content/docs/meta.json

@@ -0,0 +1,11 @@
+{
+  "title": "MarginNote插件开发文档",
+  "pages": [
+    "index",
+    "guides",
+    "cookbook",
+    "reference",
+    "libmn",
+    "contributing"
+  ]
+}

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/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Foundation",
+  "pages": ["..."]
+}

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]`。

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

@@ -3,7 +3,7 @@ title: NSSet
 description: 不可变无序集合（集合/去重容器）。
 ---
 
-`NSSet` 是不可变集合，适合表示“去重后的元素集合”。在插件环境中，你会在很多 API 里见到它（例如返回一组对象、或用于 membership 判断）。
+`NSSet` 是不可变集合，适合表示“去重后的元素集合”。你会在很多 API 里见到它（例如返回一组对象、或用于 membership 判断）。
 
 ## 类成员 (Class members)
 

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

@@ -3,7 +3,7 @@ title: NSSimpleCString
 description: 内部字符串类型（可当作 NSString 使用）。
 ---
 
-`NSSimpleCString` 是一种内部字符串类型。在插件环境中你通常**不需要关心它本身**：它按“字符串”语义工作，可当作 `NSString`/JS 字符串的等价载体来使用。
+`NSSimpleCString` 是一种内部字符串类型。你默认**不需要关心它本身**：它按“字符串”语义工作，可当作 `NSString`/JS 字符串的等价载体来使用。
 
 ## 实例成员 (Instance members)
 
@@ -11,10 +11,9 @@ description: 内部字符串类型（可当作 NSString 使用）。
 
 ## 类成员 (Class members)
 
-当前运行时未额外暴露 `NSSimpleCString` 的类成员。
+当前接口未额外暴露 `NSSimpleCString` 的类成员。
 
 ## 说明
 
 - **没有额外可调用成员**：它不额外暴露独有方法/属性。
-- **使用建议**：把它当作普通字符串传递/拼接/比较即可。
-
+- **使用规范**：把它当作普通字符串传递/拼接/比较即可。

package/src/content/docs/reference/foundation/ns-time-zone.md

@@ -3,7 +3,7 @@ title: NSTimeZone
 description: 时区对象。
 ---
 
-`NSTimeZone` 表示时区信息，通常与 `NSDateFormatter` 配合使用。
+`NSTimeZone` 表示时区信息，默认与 `NSDateFormatter` 配合使用。
 
 ## 类成员 (Class members)
 

package/src/content/docs/reference/foundation/ns-ubiquitous-key-value-store.md

@@ -0,0 +1,61 @@
+---
+title: NSUbiquitousKeyValueStore
+description: iCloud键值存储对象。用于跨设备同步少量配置数据。
+---
+
+`NSUbiquitousKeyValueStore`用于iCloud键值同步。适合存放小体积配置，不适合大数据或强一致事务。
+
+## 类成员 (Class members)
+
+### `defaultStore`
+
+获取默认iCloud键值存储实例。
+
+```javascript
+static defaultStore(): NSUbiquitousKeyValueStore
+```
+
+## 实例成员 (Instance members)
+
+### 读取
+
+| 方法 | 参数 | 返回值 | 说明 |
+| --- | --- | --- | --- |
+| `objectForKey(key)` | key: string | any | 读取任意对象。 |
+| `stringForKey(key)` | key: string | string \| null | 读取字符串。 |
+| `arrayForKey(key)` | key: string | NSArray \| null | 读取数组。 |
+| `dictionaryForKey(key)` | key: string | NSDictionary \| null | 读取字典。 |
+| `dataForKey(key)` | key: string | NSData \| null | 读取二进制数据。 |
+| `longLongForKey(key)` | key: string | number | 读取long long。 |
+| `doubleForKey(key)` | key: string | number | 读取double。 |
+| `boolForKey(key)` | key: string | boolean | 读取布尔值。 |
+
+### 写入
+
+| 方法 | 参数 | 返回值 | 说明 |
+| --- | --- | --- | --- |
+| `setObjectForKey(value, key)` | value: any, key: string | void | 写入对象。 |
+| `setStringForKey(value, key)` | value: string, key: string | void | 写入字符串。 |
+| `setArrayForKey(value, key)` | value: NSArray, key: string | void | 写入数组。 |
+| `setDictionaryForKey(value, key)` | value: NSDictionary, key: string | void | 写入字典。 |
+| `setDataForKey(value, key)` | value: NSData, key: string | void | 写入二进制数据。 |
+| `setLongLongForKey(value, key)` | value: number, key: string | void | 写入long long。 |
+| `setDoubleForKey(value, key)` | value: number, key: string | void | 写入double。 |
+| `setBoolForKey(value, key)` | value: boolean, key: string | void | 写入布尔值。 |
+
+### 其他
+
+| 方法 | 参数 | 返回值 | 说明 |
+| --- | --- | --- | --- |
+| `removeObjectForKey(key)` | key: string | void | 删除键。 |
+| `dictionaryRepresentation()` | — | NSDictionary | 获取当前键值快照。 |
+| `synchronize()` | — | boolean | 触发同步。 |
+
+## 使用规范
+
+- 缺失key时，读取默认返回`nil/0/false`。
+- `synchronize()`不保证强一致即时成功，受iCloud账号、网络和系统同步时机影响。
+
+## 相关
+
+- [NSUserDefaults](/reference/foundation/ns-user-defaults/)

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

@@ -5,7 +5,7 @@ description: 插件环境中唯一导出的网络请求类（deprecated，但可
 
 完整用法见 [网络请求](/guides/network-requests/) 教程。
 
-`NSURLConnection` 是插件环境中导出的网络请求类（头文件标注为 deprecated，但在当前接口里仍可用）。它通常与 `NSURLRequest`/`NSMutableURLRequest`、`NSOperationQueue`、`NSData`、`NSError`、`NSHTTPURLResponse` 配合使用。
+`NSURLConnection` 是插件环境中导出的网络请求类（头文件标注为 deprecated，但在当前接口里仍可用）。它默认与 `NSURLRequest`/`NSMutableURLRequest`、`NSOperationQueue`、`NSData`、`NSError`、`NSHTTPURLResponse` 配合使用。
 
 ## 类成员 (Class members)
 
@@ -102,7 +102,7 @@ originalRequest(): NSURLRequest
 
 ### `currentRequest`
 
-当前请求（可能经重定向等变更）。
+当前请求（会经重定向等变更）。
 
 ```javascript
 currentRequest(): NSURLRequest

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

@@ -3,7 +3,7 @@ title: NSURLRequest
 description: 不可变 URL 请求对象，包含 URL、缓存策略、HTTP header/body 等只读访问。
 ---
 
-`NSURLRequest` 表示一个不可变的 URL 请求。通常在插件里用于读取请求信息，或作为 `NSMutableURLRequest` 的父接口使用。
+`NSURLRequest` 表示一个不可变的 URL 请求。默认在插件里用于读取请求信息，或作为 `NSMutableURLRequest` 的父接口使用。
 
 ## 类成员 (Class members)
 
@@ -221,4 +221,4 @@ HTTPShouldUsePipelining(): boolean
 
 - `boolean`: 是否使用。
 
-> 建议：需要设置 method/header/body 等可变字段时，直接使用 [NSMutableURLRequest](/reference/foundation/ns-mutable-url-request/)。
+> 要求：需要设置 method/header/body 等可变字段时，直接使用 [NSMutableURLRequest](/reference/foundation/ns-mutable-url-request/)。

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

@@ -1,9 +1,9 @@
 ---
 title: NSURLResponse
-description: URL 响应对象，包含 MIMEType、编码、建议文件名等元信息。
+description: URL 响应对象，包含 MIMEType、编码、期望文件名等元信息。
 ---
 
-`NSURLResponse` 是 URL 请求的响应对象基类。HTTP 响应通常会是其子类 `NSHTTPURLResponse`。
+`NSURLResponse` 是 URL 请求的响应对象基类。HTTP 响应默认会是其子类 `NSHTTPURLResponse`。
 
 ## 实例成员 (Instance members)
 
@@ -78,7 +78,7 @@ textEncodingName(): string
 
 ### `suggestedFilename`
 
-建议保存文件名。
+保存文件名。
 
 ```javascript
 suggestedFilename(): string
@@ -86,11 +86,11 @@ suggestedFilename(): string
 
 **Return Value:**
 
-- `string`: 建议文件名。
+- `string`: 期望文件名。
 
 ## 类成员 (Class members)
 
-当前运行时未额外暴露 `NSURLResponse` 的类成员。
+当前接口未额外暴露 `NSURLResponse` 的类成员。
 
 ## 相关
 

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

@@ -18,7 +18,7 @@ description: URL 对象，用于网页、文件路径与 Application.openURL。
 
 ## 实例成员 (Instance members)
 
-### 属性（常用）
+### 属性
 
 | 属性 | 类型 | 说明 |
 |------|------|------|

package/src/content/docs/reference/foundation/ns-user-defaults.md

@@ -25,7 +25,7 @@ static standardUserDefaults(): NSUserDefaults
 
 ### `setObjectForKey`
 
-存储任意对象（通常为字符串、数字、数组、字典等可序列化类型）。
+存储任意对象（为字符串、数字、数组、字典等可序列化类型）。
 
 ```javascript
 setObjectForKey(value: any, key: string): void
@@ -203,7 +203,7 @@ integerForKey(key: string): number
 
 **Return Value:**
 
-- `number`: 整数值（若不存在通常返回 0）。
+- `number`: 整数值（若不存在默认返回 0）。
 
 ### `floatForKey`
 
@@ -239,7 +239,7 @@ boolForKey(key: string): boolean
 
 **Return Value:**
 
-- `boolean`: 布尔值（若不存在通常返回 false）。
+- `boolean`: 布尔值（若不存在默认返回 false）。
 
 ### `URLForKey`
 
@@ -281,7 +281,7 @@ synchronize(): boolean
 
 - `boolean`: 是否写入成功。
 
-**Note:** 系统通常会自动保存，仅在需要立即持久化时调用。
+**Note:** 系统默认会自动保存，仅在需要立即持久化时调用。
 
 ### `registerDefaults`
 
@@ -299,4 +299,4 @@ registerDefaults(registrationDictionary: NSDictionary): void
 
 ## 相关
 
-- [教程：存储与文件](/guides/storage-and-files/)、[Cookbook：插件设置页](/guides/cookbook/addon-settings/)
+- [教程：存储与文件](/guides/storage-and-files/)、[Cookbook：插件设置页](/cookbook/addon-settings/)