mn-docs-mcp 0.6.2 → 1.1.0

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

@@ -1,15 +1,15 @@
 ---
 title: NSValue
-description: 通用值对象封装（CGRect/CGPoint/CGSize/NSRange 等）。
+description: 通用值对象封装（[CGRect](/reference/value-sturct/#cgrect)/[CGPoint](/reference/value-sturct/#cgpoint)/[CGSize](/reference/value-sturct/#cgsize)/[NSRange](/reference/value-sturct/#nsrange)/[CGAffineTransform](/reference/value-sturct/#cgaffinetransform)/[CATransform3D](/reference/value-sturct/#catransform3d)等）。
 ---
 
-`NSValue` 用于封装非对象类型的值（例如 `CGPoint`、`CGRect`、`CGSize`、`NSRange`、`CGAffineTransform`、`CATransform3D` 等），以便在集合中传递或作为返回值使用。
+`NSValue`用于封装非对象类型的值，例如[`CGPoint`](/reference/value-sturct/#cgpoint)、[`CGRect`](/reference/value-sturct/#cgrect)、[`CGSize`](/reference/value-sturct/#cgsize)、[`NSRange`](/reference/value-sturct/#nsrange)、[`CGAffineTransform`](/reference/value-sturct/#cgaffinetransform)、[`CATransform3D`](/reference/value-sturct/#catransform3d)等，以便在集合中传递或作为返回值使用。
 
 ## 类成员 (Class members)
 
 ### `valueWithCGPoint`
 
-从 CGPoint 创建。
+从[CGPoint](/reference/value-sturct/#cgpoint)创建。
 
 ```javascript
 static valueWithCGPoint(point: any): NSValue
@@ -27,7 +27,7 @@ static valueWithCGPoint(point: any): NSValue
 
 ### `valueWithCGSize`
 
-从 CGSize 创建。
+从[CGSize](/reference/value-sturct/#cgsize)创建。
 
 ```javascript
 static valueWithCGSize(size: any): NSValue
@@ -45,7 +45,7 @@ static valueWithCGSize(size: any): NSValue
 
 ### `valueWithCGRect`
 
-从 CGRect 创建。
+从[CGRect](/reference/value-sturct/#cgrect)创建。
 
 ```javascript
 static valueWithCGRect(rect: any): NSValue
@@ -63,7 +63,7 @@ static valueWithCGRect(rect: any): NSValue
 
 ### `valueWithCGAffineTransform`
 
-从 CGAffineTransform 创建。
+从[CGAffineTransform](/reference/value-sturct/#cgaffinetransform)创建。
 
 ```javascript
 static valueWithCGAffineTransform(transform: any): NSValue
@@ -81,7 +81,7 @@ static valueWithCGAffineTransform(transform: any): NSValue
 
 ### `valueWithRange`
 
-从 NSRange 创建。
+从[NSRange](/reference/value-sturct/#nsrange)创建。
 
 ```javascript
 static valueWithRange(range: any): NSValue
@@ -99,7 +99,7 @@ static valueWithRange(range: any): NSValue
 
 ### `valueWithCATransform3D`
 
-从 CATransform3D 创建（若环境中提供）。
+从[CATransform3D](/reference/value-sturct/#catransform3d)创建。
 
 ```javascript
 static valueWithCATransform3D(transform3d: any): NSValue
@@ -119,7 +119,7 @@ static valueWithCATransform3D(transform3d: any): NSValue
 
 ### `CGPointValue`
 
-取 CGPoint 值。
+取[CGPoint](/reference/value-sturct/#cgpoint)值。
 
 ```javascript
 CGPointValue(): any
@@ -131,7 +131,7 @@ CGPointValue(): any
 
 ### `CGSizeValue`
 
-取 CGSize 值。
+取[CGSize](/reference/value-sturct/#cgsize)值。
 
 ```javascript
 CGSizeValue(): any
@@ -143,7 +143,7 @@ CGSizeValue(): any
 
 ### `CGRectValue`
 
-取 CGRect 值。
+取[CGRect](/reference/value-sturct/#cgrect)值。
 
 ```javascript
 CGRectValue(): any
@@ -155,7 +155,7 @@ CGRectValue(): any
 
 ### `CGAffineTransformValue`
 
-取 CGAffineTransform 值。
+取[CGAffineTransform](/reference/value-sturct/#cgaffinetransform)值。
 
 ```javascript
 CGAffineTransformValue(): any
@@ -167,7 +167,7 @@ CGAffineTransformValue(): any
 
 ### `rangeValue`
 
-取 NSRange 值。
+取[NSRange](/reference/value-sturct/#nsrange)值。
 
 ```javascript
 rangeValue(): any
@@ -179,7 +179,7 @@ rangeValue(): any
 
 ### `CATransform3DValue`
 
-取 CATransform3D 值。
+取[CATransform3D](/reference/value-sturct/#catransform3d)值。
 
 ```javascript
 CATransform3DValue(): any
@@ -191,4 +191,4 @@ CATransform3DValue(): any
 
 ## 相关
 
-- `CGPoint` / `CGRect` / `CGSize` / `NSRange`（作为值类型）
+- [`CGPoint`](/reference/value-sturct/#cgpoint) / [`CGRect`](/reference/value-sturct/#cgrect) / [`CGSize`](/reference/value-sturct/#cgsize) / [`NSRange`](/reference/value-sturct/#nsrange) / [`CGAffineTransform`](/reference/value-sturct/#cgaffinetransform) / [`CATransform3D`](/reference/value-sturct/#catransform3d)作为值类型

package/src/content/docs/reference/global/agent-tools.md

@@ -0,0 +1,91 @@
+---
+title: AgentTools
+description: 全局工具对象。用于注册、获取、列举与执行工具。
+---
+
+**[Deprecated]** `AgentTools`是全局对象，不是原生类。用于注册工具并统一调用。
+
+已被弃用，不建议使用。
+
+## 实例成员 (Instance members)
+
+`AgentTools`是全局对象，默认不以实例化方式使用。
+
+## 类成员 (Class members)
+
+### 方法
+
+### `register`
+
+注册工具对象。
+
+```javascript
+register(tool: object): void
+```
+
+<details>
+<summary>目前内置的mn.search工具的注册源代码</summary>
+
+```javascript
+register({
+      name: 'mn.search',
+      info: {name:'mn.search', kind:'search', scopes:['topic','all','page'], description:'Search notes or pages via SearchManager'},
+      run: function(input){
+        input = input || {};
+        var app2 = null;
+        try { app2 = Application.sharedInstance(); } catch (e2) {}
+        var mgr2 = app2 && app2.searchManager ? app2.searchManager : null;
+        if (!mgr2) { throw new Error('search_manager_unavailable'); }
+        var q = normalizeString(input.query, '');
+        var scope = normalizeString(input.scope, 'topic').toLowerCase();
+        if (scope !== 'topic' && scope !== 'all' && scope !== 'page') { scope = 'topic'; }
+        var titleOnly = !!input.titleOnly;
+        var beginsWith = !!input.beginsWith;
+        var limit = (input.limit != null) ? input.limit : 50;
+        var noteOnly = (input.noteOnly != null) ? !!input.noteOnly : false;
+        var topicid = normalizeNullable(input.topicid);
+        if (scope === 'page') {
+          return mgr2.searchPage(q, beginsWith, limit);
+        }
+        if (input.useFts) {
+          return mgr2.searchFts3Text(q, titleOnly, topicid, limit, noteOnly);
+        }
+        return mgr2.searchText(q, titleOnly, topicid, beginsWith, limit);
+      }
+});
+```
+</details>
+
+### `get`
+
+按名称获取工具。
+
+```javascript
+get(name: string): object | null
+```
+
+### `list`
+
+列出已注册工具。
+
+```javascript
+list(): object[]
+```
+
+### `run`
+
+执行指定工具。
+
+```javascript
+run(name: string, input: any): Promise<any>
+```
+
+## 使用规范
+
+- `register`时缺少名称会被忽略，同名注册会覆盖。
+- `run`找不到工具时会抛错；工具对象没有`run`实现时常见返回`null`。
+- 目前会内建工具`mn.search`，执行前可先`list/get`检查。
+
+## 相关
+
+- [SearchManager](/reference/global/search-manager/)

package/src/content/docs/reference/global/application.md

@@ -58,7 +58,7 @@ studyController(window: UIWindow): StudyController
 
 | Name | Type | Description |
 | :--- | :--- | :--- |
-| `window` | `UIWindow` | 目标窗口（通常传 `self.window`）。 |
+| `window` | `UIWindow` | 目标窗口（默认传 `self.window`）。 |
 
 **Return Value:**
 
@@ -163,7 +163,7 @@ queryCommandWithKeyFlagsInWindow(command: string, keyFlags: any, window: UIWindo
 
 该接口用于查询某个内建command在“当前窗口+修饰键(keyFlags)”上下文里是否可用，以及是否处于勾选态。你可以用它来：
 
-- 判断某个command当前是否能执行（例如编辑态/无焦点时可能禁用）。
+- 判断某个command当前是否能执行（例如编辑态/无焦点时会禁用）。
 - 在调用`processCommandWithKeyFlagsInWindow(...)`之前做保护性判断。
 
 已确认返回值至少包含：
@@ -193,7 +193,7 @@ processCommandWithKeyFlagsInWindow(command: string, keyFlags: any, window: UIWin
 
 这里的command同样是MarginNote内建命令的字符串标识（可理解为某个菜单动作/操作的ID）。只要command字符串是系统可识别的命令标识，就可以直接调用执行（例如已确认`ZoomToFit`可执行）。
 
-可用的command列表没有单一集中枚举，建议参考内建command清单页，并在运行时用`queryCommandWithKeyFlagsInWindow`确认`disabled:false`后再执行：
+可用的command列表没有单一集中枚举，参考内建command清单页，并用`queryCommandWithKeyFlagsInWindow`确认`disabled:false`后再执行：
 
 - [内建command清单](/reference/global/builtin-commands/)
 
@@ -288,7 +288,7 @@ unregsiterHtmlCommentEditor(commentTag: string): void
 
 ### `importDocument`
 
-导入文档（由运行时实现决定入库位置与返回值含义）。
+导入文档，使得在MN可访问到的范围内的文档在文档库中可见。
 
 ```javascript
 importDocument(fileUrl: string): string

package/src/content/docs/reference/global/builtin-commands.md

@@ -3,12 +3,12 @@ title: 内建command清单
 description: MarginNote内建command字符串速查表（用于query/processCommand调用）。
 ---
 
-本页汇总一些常见内建command字符串。它们通常用于：
+本页汇总一些常见内建command字符串。它们默认用于：
 
 - `Application.queryCommandWithKeyFlagsInWindow(command,keyFlags,window)`查询可用性与checked状态。
 - `Application.processCommandWithKeyFlagsInWindow(command,keyFlags,window)`执行内建命令。
 
-注意：该清单可能随版本变化；当某个command在运行时表现为`disabled:true`，可能是当前上下文不可用，也可能是版本差异导致不存在。
+注意：该清单会随版本变化；当某个command表现为`disabled:true`，是当前上下文不可用，也是版本差异导致不存在。
 
 ## Root（全局分发）
 

package/src/content/docs/reference/global/database.md

@@ -3,7 +3,7 @@ title: Database
 description: MarginNote 核心数据库访问对象（MbModelTool），用于获取/修改笔记、笔记本与文档。
 ---
 
-`Database` 即底层类型 `MbModelTool` 的单例，用于访问 MarginNote 的笔记与文档数据。通过 `Database.sharedInstance()` 获取。修改数据后建议使用 [UndoManager](/reference/utility/undo-manager/) 的 `undoGrouping(title, topicid, fn)` 包裹，并调用 `Application.sharedInstance().refreshAfterDBChanged(topicid)` 刷新界面。
+`Database` 即底层类型 `MbModelTool` 的单例，用于访问 MarginNote 的笔记与文档数据。通过 `Database.sharedInstance()` 获取。修改数据后使用 [UndoManager](/reference/utility/undo-manager/) 的 `undoGrouping(title, topicid, fn)` 包裹，并调用 `Application.sharedInstance().refreshAfterDBChanged(topicid)` 刷新界面。
 
 ## 类成员 (Class members)
 
@@ -176,7 +176,7 @@ allDocuments(): NSArray
 
 ### `savedb`
 
-手动保存数据库到磁盘。慎用，通常由系统自动管理。
+手动保存数据库到磁盘。慎用，默认由系统自动管理。
 
 ```javascript
 savedb(): void
@@ -371,7 +371,7 @@ getSketchNotesForMindMap(topicid: string): NSArray
 
 ### `transDictionaryToJSCompatible` / `transArrayToJSCompatible`
 
-将原生容器转换为更易于 JS 使用的结构（行为以运行时实现为准）。
+将原生容器转换为更易于 JS 使用的结构。
 
 ```javascript
 static transDictionaryToJSCompatible(dic: NSDictionary): NSDictionary
@@ -387,7 +387,7 @@ static transArrayToJSCompatible(arr: NSArray): NSArray
 
 **Return Value:**
 
-- `any`: 导入结果（通常为导入的笔记本对象或状态）。
+- `any`: 导入结果（为导入的笔记本对象或状态）。
 
 ## 相关
 

package/src/content/docs/reference/global/document.md

@@ -0,0 +1,21 @@
+---
+title: Document
+description: 全局别名对象。语义上等同于MbBook。
+---
+
+`Document`是插件环境的全局导出别名，语义上等同于[MbBook](/reference/marginnote/mb-book/)。
+
+## 关系说明
+
+- `Document`与`MbBook`是同一文档对象在全局入口层的别名语义，不是两套模型。
+- 主键语义为`docMd5`。
+- 对象生命周期由宿主数据层管理，不把投影字段当强一致缓存长期持有。
+
+## 用法
+
+完整属性与方法请直接参考[MbBook](/reference/marginnote/mb-book/)。
+
+## 相关
+
+- [MbBook](/reference/marginnote/mb-book/)
+- [Database](/reference/global/database/)

package/src/content/docs/reference/global/global-variables.md

@@ -1,8 +1,8 @@
 ---
 title: 全局入口对象（Global Variables）
-description: MarginNote插件运行时直接注入到JS环境的全局变量清单与用法入口。
+description: MarginNote插件环境直接注入到JS环境的全局变量清单与用法入口。
 ---
-本页列出MarginNote插件运行时可直接使用的全局变量名。这些全局名对应的对象通常是单例、工厂对象、或系统级入口。
+本页列出MarginNote插件环境可直接使用的全局变量名。这些全局名对应的对象默认是单例、工厂对象、或系统级入口。
 
 > 说明：本页仅做索引。每个对象的完整属性/方法请进入对应参考页。
 
@@ -42,6 +42,16 @@ description: MarginNote插件运行时直接注入到JS环境的全局变量清
       <td>数据库访问</td>
       <td><a href="/reference/global/database/">Database</a></td>
     </tr>
+    <tr>
+      <td><code>Document</code></td>
+      <td>文档入口别名（等同MbBook）</td>
+      <td><a href="/reference/global/document/">Document</a></td>
+    </tr>
+    <tr>
+      <td><code>Notebook</code></td>
+      <td>笔记本入口别名（等同MbTopic）</td>
+      <td><a href="/reference/global/notebook/">Notebook</a></td>
+    </tr>
     <tr>
       <td><code>Note</code></td>
       <td>创建笔记</td>
@@ -59,9 +69,14 @@ description: MarginNote插件运行时直接注入到JS环境的全局变量清
     </tr>
     <tr>
       <td><code>SearchManager</code></td>
-      <td>搜索与索引（<code>Application.sharedInstance().searchManager</code>）</td>
+      <td>搜索与索引</td>
       <td><a href="/reference/global/search-manager/">SearchManager</a></td>
     </tr>
+    <tr>
+      <td><code>AgentTools</code></td>
+      <td>工具注册与执行</td>
+      <td><a href="/reference/global/agent-tools/">AgentTools</a></td>
+    </tr>
   </tbody>
 </table>
 
@@ -207,15 +222,16 @@ description: MarginNote插件运行时直接注入到JS环境的全局变量清
 
 ## 其它对象
 
-本页不再列出Foundation/UIKit/QuartzCore与JavaScript原生环境的全量对象清单；它们的参考条目请在侧边栏对应分组中查阅。下面仅给出常见入口与例子。
+MarginNote插件环境还可用绝大部分的Foundation/UIKit/QuartzCore与JavaScript原生环境，它们的参考条目请在侧边栏对应分组中查阅，下面仅给出常见入口与例子。
 
 ### Foundation
 
-多数Foundation类可直接使用（通常以类/单例形式导出）。例：
+多数Foundation类可直接使用（默认以类/单例形式导出）。例：
 
 - [NSFileManager](/reference/foundation/ns-file-manager/)
 - [NSData](/reference/foundation/ns-data/)
 - [NSTimer](/reference/foundation/ns-timer/)
+- [NSUbiquitousKeyValueStore](/reference/foundation/ns-ubiquitous-key-value-store/)
 
 ### UIKit
 
@@ -232,6 +248,7 @@ description: MarginNote插件运行时直接注入到JS环境的全局变量清
 - [CALayer](/reference/quartzcore/calayer/)
 - [CAShapeLayer](/reference/quartzcore/cashape-layer/)
 - [CATransaction](/reference/quartzcore/catransaction/)
+- [CAEmitterLayer](/reference/quartzcore/caemitter-layer/)
 
 ### JavaScript原生环境
 

package/src/content/docs/reference/global/jsb.md

@@ -1,12 +1,12 @@
 ---
 title: JSB
-description: JavaScript 桥接核心，连接插件 JS 与运行时对象的入口对象。
+description: JavaScript 桥接核心，连接插件 JS 与宿主对象的入口对象。
 ---
-JSB（JavaScript Bridge）是插件运行时的桥接核心对象：类定义、插件入口、日志与包内脚本加载都通过它完成。
+JSB（JavaScript Bridge）是插件环境的桥接核心对象：类定义、插件入口、日志与包内脚本加载都通过它完成。
 
 ## 实例成员 (Instance members)
 
-`JSB` 是全局对象，通常不以“实例化”的方式使用。
+`JSB` 是全局对象，默认不以“实例化”的方式使用。
 
 ## 类成员 (Class members)
 
@@ -14,7 +14,9 @@ JSB（JavaScript Bridge）是插件运行时的桥接核心对象：类定义、
 
 ### `defineClass`
 
-定义一个可被运行时识别并回调的类，**所有插件的入口**。
+定义一个可被插件环境识别并回调的类，只在插件入口处使用。
+
+注意：该方法定义的类非js的类，this并不会指向该类的实例，而应使用[self](/reference/global/self/) 替代
 
 ```javascript
 defineClass(declaration: string, instanceMembers: object, classMembers?: object): any

package/src/content/docs/reference/global/meta.json

@@ -0,0 +1,18 @@
+{
+  "title": "全局与入口",
+  "pages": [
+    "global-variables",
+    "jsb",
+    "application",
+    "search-manager",
+    "database",
+    "document",
+    "notebook",
+    "note",
+    "agent-tools",
+    "popup-menu",
+    "popup-menu-item",
+    "self",
+    "builtin-commands"
+  ]
+}

package/src/content/docs/reference/global/note.md

@@ -3,13 +3,13 @@ title: Note
 description: 全局注入的笔记工厂对象，用于创建新笔记（MbBookNote）。
 ---
 
-`Note` 是 MarginNote 运行时注入到 JavaScript 环境中的**全局对象**之一，用于创建新笔记。
+`Note` 是 MarginNote 宿主注入到 JavaScript 环境中的**全局对象**之一，用于创建新笔记。
 
 需要特别注意：创建笔记的方法**不在** `MbBookNote` 类上，而是在全局 `Note` 对象上（这是由 MarginNote 的 JSExport 导出方式决定的）。
 
 ## 实例成员 (Instance members)
 
-`Note` 是全局对象，通常不以实例形式使用。
+`Note` 是全局对象，默认不以实例形式使用。
 
 ## 类成员 (Class members)
 

package/src/content/docs/reference/global/notebook.md

@@ -0,0 +1,21 @@
+---
+title: Notebook
+description: 全局别名对象。语义上等同于MbTopic。
+---
+
+`Notebook`是插件环境的全局导出别名，语义上等同于[MbTopic](/reference/marginnote/mb-topic/)。
+
+## 关系说明
+
+- `Notebook`与`MbTopic`是同一类主题对象在全局入口层的别名语义，不是两套模型。
+- 主键语义为`topicId/topicid`。
+- 对象生命周期由宿主数据层管理，不把`documents/notes`当强一致缓存长期持有。
+
+## 用法
+
+完整属性与方法请直接参考[MbTopic](/reference/marginnote/mb-topic/)。
+
+## 相关
+
+- [MbTopic](/reference/marginnote/mb-topic/)
+- [Database](/reference/global/database/)

package/src/content/docs/reference/global/popup-menu-item.md

@@ -3,14 +3,14 @@ title: PopupMenuItem
 description: PopupMenu 的菜单项对象（全局注入）。
 ---
 
-`PopupMenuItem` 是运行时注入的全局类型（对应原生 QBPopupMenuItem）。通常由运行时创建并用于渲染；可读属性包含标题与动作标识。
+`PopupMenuItem` 是宿主注入的全局类型（对应原生 QBPopupMenuItem）。默认由插件环境创建并用于渲染；可读属性包含标题与动作标识。
 
 ## 实例成员 (Instance members)
 
 | 属性 | 类型 | 说明 |
 |---|---|---|
 | `title` | `string` | 显示标题。 |
-| `actionString` | `string` | 动作标识字符串（用途依赖运行时）。 |
+| `actionString` | `string` | 动作标识字符串（用途依赖插件环境）。 |
 
 ## 相关
 

package/src/content/docs/reference/global/popup-menu.md

@@ -3,7 +3,7 @@ title: PopupMenu
 description: 轻量弹出菜单视图（全局注入），用于展示一组 PopupMenuItem。
 ---
 
-`PopupMenu` 是运行时注入的全局类（对应原生 QBPopupMenu）。常用于在指定 rect 附近弹出一组菜单项。
+`PopupMenu` 是宿主注入的全局类（对应原生 QBPopupMenu）。常用于在指定 rect 附近弹出一组菜单项。
 
 ## 类成员 (Class members)
 
@@ -20,19 +20,18 @@ description: 轻量弹出菜单视图（全局注入），用于展示一组 Pop
 |---|---|---|
 | `visible` | `boolean` | 是否可见。 |
 | `items` | `NSArray` | 菜单项列表。 |
-| `arrowDirection` | `number` | 箭头方向（枚举值以运行时为准）。 |
-| `targetWinRect` | `CGRect` | 目标窗口 rect（只读）。 |
+| `arrowDirection` | `number` | 箭头方向Default/Up/Down/Left/Right，数值 0/1/2/3/4。 |
+| `targetWinRect` | [`CGRect`](/reference/value-sturct/#cgrect) | 目标窗口 rect（只读）。 |
 
 ### 方法
 
 | 方法 | 参数 | 返回值 | 说明 |
 |---|---|---|---|
-| `showInViewTargetRectAnimated(view, targetRect, animated)` | view: `UIView`, targetRect: `CGRect`, animated: boolean | — | 在 view 中显示。 |
-| `updateWithTargetRect(targetRect)` | targetRect: `CGRect` | — | 更新目标 rect。 |
+| `showInViewTargetRectAnimated(view, targetRect, animated)` | view: `UIView`, targetRect: [`CGRect`](/reference/value-sturct/#cgrect), animated: boolean | — | 在 view 中显示。 |
+| `updateWithTargetRect(targetRect)` | targetRect: [`CGRect`](/reference/value-sturct/#cgrect) | — | 更新目标 rect。 |
 | `dismissAnimated(animated)` | animated: boolean | — | 关闭菜单。 |
 
 ## 相关
 
 - [PopupMenuItem](/reference/global/popup-menu-item/)
 - [UIView](/reference/uikit/uiview/)
-

package/src/content/docs/reference/global/search-manager.md

@@ -3,7 +3,7 @@ title: SearchManager
 description: 搜索与索引管理器（全文检索、URL 搜索、相似笔记检索等）。
 ---
 
-`SearchManager` 通过 `Application.sharedInstance().searchManager` 获取。其返回结构与索引能力会随版本变化；建议先在控制台打印返回值结构再做兼容处理。
+`SearchManager` 通过 `Application.sharedInstance().searchManager` 获取。其返回结构与索引能力会随版本变化；先在控制台打印返回值结构再做兼容处理。
 
 ## 实例成员 (Instance members)
 
@@ -22,9 +22,9 @@ description: 搜索与索引管理器（全文检索、URL 搜索、相似笔记
 | `searchText(query, titleOnly, topicid, beginsWith, limit)` | 文本搜索。 |
 | `searchTextNoteOnly(query, titleOnly, topicid, beginsWith, limit, noteOnly)` | 文本搜索（可限定只搜笔记）。 |
 | `searchTextWordList(textWordLst, titleOnly, topicid, beginsWith, limit)` | 使用分词列表进行搜索。 |
-| `searchFts3Text(query, titleOnly, topicid, limit, noteOnly)` | 通过 FTS3 搜索（实现依赖运行时）。 |
-| `searchURLs(urls, topicid)` | 按 URL 列表搜索。 |
-| `searchPage(query, beginsWith, limit)` | 页内搜索（实现依赖运行时）。 |
+| `searchFts3Text(query, titleOnly, topicid, limit, noteOnly)` | 通过 FTS3 搜索。 |
+| `searchURLs(urls, topicid)` | 按 URL 列表搜索。插件环境`urls`必须为`NSArray`，传原始字符串会报`TypeError: Cannot convert primitive to NSArray`。`topicid`可传`string`或`NSArray`。 |
+| `searchPage(query, beginsWith, limit)` | 页内搜索。 |
 | `snippetForFts3RowId(rowid)` / `snippetForPageRowId(rowid)` | 获取 snippet（结果摘要）。 |
 
 ### 同步与索引
@@ -43,9 +43,15 @@ description: 搜索与索引管理器（全文检索、URL 搜索、相似笔记
 | `findSimilarNotes(queryVector, topicId, k)` | 向量相似笔记检索。 |
 | `batchFindSimilarNotes(queryVectors, topicId, k)` | 批量向量相似检索。 |
 | `findSimilarNotesHybrid(queryVector, queryText, topicId, k, semanticWeight, bm25Weight)` | 语义+BM25 混合检索。 |
-| `loadVectorCacheForTopic(topicId)` / `syncTopicVectorsForceCompletion(topicId, force, completion)` / `invalidateVectorCacheForTopics(topicIds)` | 向量缓存相关（实现依赖运行时）。 |
+| `loadVectorCacheForTopic(topicId)` / `syncTopicVectorsForceCompletion(topicId, force, completion)` / `invalidateVectorCacheForTopics(topicIds)` | 向量缓存相关。 |
+
+### 已确认行为
+
+- `searchPage(...)`有命中时返回数组对象，无命中时返回空数组。
+- `searchPage("", ...)`返回`undefined`，不是空数组。
+- 当前样本中`searchFts3Text(...)`有命中与无命中都会返回空数组，结果受索引状态影响较大。
+- `snippetForFts3RowId(rowid)`与`snippetForPageRowId(rowid)`在当前样本中返回`undefined`。
 
 ## 相关
 
 - [Application](/reference/global/application/) — `Application.sharedInstance().searchManager`
-

package/src/content/docs/reference/global/self.md

@@ -3,19 +3,7 @@ title: self
 description: 在 JSExtension 实例方法内指向当前插件实例的上下文。
 ---
 
-在 `JSB.defineClass` 定义的**实例方法**内部，`self` 指向该插件类的当前实例。用于访问插件自身的 `window` 以及你在实例上挂载的属性（如自定义的 viewController、layout 函数等）。
-
-## 实例成员 (Instance members)
-
-### 属性
-
-| 属性 | 类型 | 说明 |
-|------|------|------|
-| `window` | `UIWindow` | 当前插件所在窗口。常与 `Application.sharedInstance().studyController(self.window)` 配合获取学习控制器。 |
-
-## 类成员 (Class members)
-
-`self` 是实例上下文变量，不以类成员形式存在。
+在 `JSB.defineClass` 定义的**实例方法**内部，`self` 指向该类的当前实例，用于访问定义的类实例属性。
 
 ## 说明
 

package/src/content/docs/reference/js-runtime.md

@@ -1,8 +1,8 @@
 ---
 title: JavaScript原生环境
-description: MarginNote插件运行时的JavaScriptCore能力边界、内置对象与常见误区。
+description: MarginNote插件环境的JavaScriptCore能力边界、内置对象与常见问题。
 ---
-MarginNote插件运行在JavaScriptCore中，而不是浏览器环境。这意味着标准JavaScript内置对象可用，但浏览器相关API通常不存在，且宿主会额外注入自己的对象与能力。
+MarginNote插件运行在JavaScriptCore中，而不是浏览器环境。这意味着标准JavaScript内置对象可用，但浏览器相关API默认不存在，且宿主会额外注入自己的对象与能力。
 
 ## 内置对象一览
 
@@ -73,12 +73,13 @@ MarginNote插件运行在JavaScriptCore中，而不是浏览器环境。这意
 | [NaN](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/NaN)                                   | 非数值常量                  |
 | [undefined](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined)                       | 未定义常量                  |
 
-## 环境差异与建议
+## 环境差异与规范
 
 - 插件环境没有原生fetch。需要网络请求时，请使用文档提供的网络请求API。
-- 插件环境没有setTimeout/setInterval。建议使用NSTimer完成延时与轮询。
+- 插件环境没有setTimeout/setInterval。使用NSTimer完成延时与轮询。
 
 ## 相关
 
 - [NSTimer](/reference/foundation/ns-timer/)
 - [网络请求](/guides/network-requests/)
+- [Value Sturct](/reference/value-sturct/)