mn-docs-mcp 0.6.2 → 1.0.0

package/src/content/docs/reference/marginnote/study-controller.md

@@ -3,7 +3,7 @@ title: StudyController
 description: 学习场景主视图控制器，访问脑图与文档的入口。
 ---
 
-学习场景的主视图控制器，通过 `Application.sharedInstance().studyController(window)` 获取（通常传入 `self.window`）。是访问脑图、文档、当前笔记本等的根对象。
+学习场景的主视图控制器，通过 `Application.sharedInstance().studyController(window)` 获取（默认传入 `self.window`）。是访问脑图、文档、当前笔记本等的根对象。
 
 ## 实例成员 (Instance members)
 
@@ -92,7 +92,7 @@ toggleExtensionPanel(): void
 
 ## 类成员 (Class members)
 
-当前运行时未额外暴露 `StudyController` 的类成员。
+当前接口未额外暴露 `StudyController` 的类成员。
 
 ## 相关
 

package/src/content/docs/reference/quartzcore/caanimation-group.md

@@ -1,6 +1,6 @@
 ---
 title: CAAnimationGroup
-description: 动画组。可组合多段动画，并配置 timingFunction、keyPath、from/to/by 等常见字段。
+description: 动画组。可组合多段动画，并配置 timingFunction、keyPath、from/to/by 等字段定义。
 ---
 
 `CAAnimationGroup` 继承自 [CAAnimation](/reference/quartzcore/caanimation/)，用于把多段动画组合为一个整体并一起添加到 `CALayer` 上。
@@ -14,7 +14,7 @@ description: 动画组。可组合多段动画，并配置 timingFunction、keyP
 | `animations` | NSArray | 子动画数组。 |
 | `keyPath` | string \| null | keyPath（若该组被用作属性动画时）。 |
 | `fromValue` / `toValue` / `byValue` | any | 起始/结束/增量值。 |
-| `values` | NSArray | 关键帧 values（若运行时复用字段）。 |
+| `values` | NSArray | 关键帧 values（复用字段）。 |
 | `keyTimes` | NSArray | 关键时间点数组。 |
 | `timingFunction` | CAMediaTimingFunction \| null | timingFunction。 |
 | `timingFunctions` | NSArray | 多段 timingFunctions。 |
@@ -34,7 +34,7 @@ description: 动画组。可组合多段动画，并配置 timingFunction、keyP
 
 ## 类成员 (Class members)
 
-当前运行时未额外暴露 `CAAnimationGroup` 的类成员。
+当前接口未额外暴露 `CAAnimationGroup` 的类成员。
 
 ## 相关
 

package/src/content/docs/reference/quartzcore/cabasic-animation.md

@@ -1,17 +1,17 @@
 ---
 title: CABasicAnimation
-description: 基础属性动画。通常用于对 keyPath 做 from/to/by 的插值动画。
+description: 基础属性动画。默认用于对 keyPath 做 from/to/by 的插值动画。
 ---
 
 `CABasicAnimation` 继承自 [CAPropertyAnimation](/reference/quartzcore/caproperty-animation/)，用于最常见的“起始值 → 结束值”插值动画。它本身没有额外新增成员，主要使用父类暴露的 `keyPath`、`fromValue`、`toValue`、`byValue`、`timingFunction` 等字段。
 
 ## 实例成员 (Instance members)
 
-当前运行时未额外暴露 `CABasicAnimation` 的专属实例成员。
+当前接口未额外暴露 `CABasicAnimation` 的专属实例成员。
 
 ## 类成员 (Class members)
 
-当前运行时未额外暴露 `CABasicAnimation` 的专属类成员。
+当前接口未额外暴露 `CABasicAnimation` 的专属类成员。
 
 ## 相关
 

package/src/content/docs/reference/quartzcore/caemitter-layer.md

@@ -0,0 +1,44 @@
+---
+title: CAEmitterLayer
+description: 粒子发射图层。用于粒子特效渲染。
+---
+
+`CAEmitterLayer`是QuartzCore粒子发射图层，用于配置发射位置、形状、速率与粒子单元集合。
+
+## 实例成员 (Instance members)
+
+### 属性
+
+| 属性 | 类型 | 说明 |
+| --- | --- | --- |
+| `emitterPosition` | [`CGPoint`](/reference/value-sturct/#cgpoint) | 发射器位置。 |
+| `emitterSize` | [`CGSize`](/reference/value-sturct/#cgsize) | 发射器尺寸。 |
+| `emitterShape` | string | 发射形状。 |
+| `emitterMode` | string | 发射模式。 |
+| `emitterDepth` | number | 发射深度。 |
+| `birthRate` | number | 出生速率。 |
+| `lifetime` | number | 生命周期。 |
+| `velocity` | number | 速度。 |
+| `scale` | number | 缩放。 |
+| `spin` | number | 旋转速度。 |
+| `emitterCells` | NSArray | 粒子单元数组。 |
+| `preservesDepth` | boolean | 是否保留深度。 |
+| `renderMode` | string | 渲染模式。 |
+| `seed` | number | 随机种子。 |
+
+## 类成员 (Class members)
+
+| 方法 | 参数 | 返回值 | 说明 |
+| --- | --- | --- | --- |
+| `layer()` | — | id | 创建图层实例。 |
+| `defaultValueForKey(key)` | key: string | any | 返回属性默认值。 |
+| `needsDisplayForKey(key)` | key: string | boolean | 判断属性变化是否触发重绘。 |
+
+## 使用规范
+
+- 需要把图层挂到可见layer树才会看到效果。
+- `emitterCells`配置不兼容时常见“无效果不报错”，先用最小配置验证链路。
+
+## 相关
+
+- [CALayer](/reference/quartzcore/calayer/)

package/src/content/docs/reference/quartzcore/cagradient-layer.md

@@ -19,7 +19,7 @@ description: 渐变图层。可配置 colors/locations 与 startPoint/endPoint
 
 ## 类成员 (Class members)
 
-当前运行时未额外暴露 `CAGradientLayer` 的类成员。
+当前接口未额外暴露 `CAGradientLayer` 的类成员。
 
 ## 相关
 

package/src/content/docs/reference/quartzcore/cakeyframe-animation.md

@@ -1,17 +1,17 @@
 ---
 title: CAKeyframeAnimation
-description: 关键帧属性动画。通常通过 values/keyTimes 等字段描述多段变化。
+description: 关键帧属性动画。默认通过 values/keyTimes 等字段描述多段变化。
 ---
 
 `CAKeyframeAnimation` 继承自 [CAPropertyAnimation](/reference/quartzcore/caproperty-animation/)，用于关键帧动画。它本身没有额外新增成员，主要使用父类暴露的 `values`、`keyTimes`、`timingFunctions`、`path`、`calculationMode` 等字段来描述关键帧序列。
 
 ## 实例成员 (Instance members)
 
-当前运行时未额外暴露 `CAKeyframeAnimation` 的专属实例成员。
+当前接口未额外暴露 `CAKeyframeAnimation` 的专属实例成员。
 
 ## 类成员 (Class members)
 
-当前运行时未额外暴露 `CAKeyframeAnimation` 的专属类成员。
+当前接口未额外暴露 `CAKeyframeAnimation` 的专属类成员。
 
 ## 相关
 

package/src/content/docs/reference/quartzcore/calayer.md

@@ -3,7 +3,7 @@ title: CALayer
 description: Core Animation 图层。提供几何/内容/阴影/圆角/边框等属性，并支持子图层管理、坐标转换与动画添加。
 ---
 
-`CALayer` 是 Core Animation 的核心图层类型。它在插件运行时中通常作为 `UIView.layer` 的类型出现，也可以独立创建并组合为图层树。
+`CALayer` 是 Core Animation 的核心图层类型。它默认作为 `UIView.layer` 的类型出现，也可以独立创建并组合为图层树。
 
 ## 实例成员 (Instance members)
 

package/src/content/docs/reference/quartzcore/camedia-timing-function.md

@@ -10,7 +10,7 @@ description: 动画时间函数。支持按名称创建或用四个控制点创
 | 方法 | 参数 | 返回值 | 说明 |
 | --- | --- | --- | --- |
 | `initWithControlPoints(c1x, c1y, c2x, c2y)` | c1x: number, c1y: number, c2x: number, c2y: number | CAMediaTimingFunction | 以四个控制点初始化。 |
-| `getControlPointAtIndexValues(idx, ptr)` | idx: number, ptr: any | void | 读取指定索引的控制点值（运行时以指针形式暴露；通常无需直接调用）。 |
+| `getControlPointAtIndexValues(idx, ptr)` | idx: number, ptr: any | void | 读取指定索引的控制点值（插件环境以指针形式暴露；默认无需直接调用）。 |
 
 ## 类成员 (Class members)
 

package/src/content/docs/reference/quartzcore/caproperty-animation.md

@@ -30,7 +30,7 @@ description: 属性动画基类。支持按 keyPath 创建，并暴露 timingFun
 | `additive` | boolean | 是否 additive。 |
 | `cumulative` | boolean | 是否 cumulative。 |
 | `removedOnCompletion` | boolean | 是否在完成后移除。 |
-| `animations` | NSArray | 子动画数组（在部分运行时复用字段）。 |
+| `animations` | NSArray | 子动画数组。 |
 
 ## 类成员 (Class members)
 

package/src/content/docs/reference/quartzcore/careplicator-layer.md

@@ -15,12 +15,12 @@ description: 复制图层。可设置 instanceCount、instanceTransform、instan
 | `instanceDelay` | number | 每个实例的时间延迟（秒）。 |
 | `instanceTransform` | object | 实例变换。 |
 | `preservesDepth` | boolean | 是否保持深度。 |
-| `instanceColor` | any | 实例颜色（运行时类型为 id）。 |
+| `instanceColor` | any | 实例颜色id。 |
 | `instanceRedOffset` / `instanceGreenOffset` / `instanceBlueOffset` / `instanceAlphaOffset` | number | 颜色分量偏移。 |
 
 ## 类成员 (Class members)
 
-当前运行时未额外暴露 `CAReplicatorLayer` 的类成员。
+当前接口未额外暴露 `CAReplicatorLayer` 的类成员。
 
 ## 相关
 

package/src/content/docs/reference/quartzcore/cascroll-layer.md

@@ -14,7 +14,7 @@ description: 可滚动图层。提供 scrollToPoint/scrollToRect 方法。
 
 ## 类成员 (Class members)
 
-当前运行时未额外暴露 `CAScrollLayer` 的类成员。
+当前接口未额外暴露 `CAScrollLayer` 的类成员。
 
 ## 相关
 

package/src/content/docs/reference/quartzcore/cashape-layer.md

@@ -3,7 +3,7 @@ title: CAShapeLayer
 description: 形状图层。支持 path、fill/stroke、线宽/线帽/连接样式、虚线与 strokeStart/strokeEnd。
 ---
 
-`CAShapeLayer` 继承自 [CALayer](/reference/quartzcore/calayer/)，用于渲染矢量路径的描边与填充。插件运行时的 `path`/`fillColor`/`strokeColor` 等字段以“运行时对象”形式暴露，你可以把它们当作可传递的值来设置与读取。
+`CAShapeLayer` 继承自 [CALayer](/reference/quartzcore/calayer/)，用于渲染矢量路径的描边与填充。插件环境的 `path`/`fillColor`/`strokeColor` 等字段以“宿主对象”形式暴露，你可以把它们当作可传递的值来设置与读取。
 
 ## 实例成员 (Instance members)
 
@@ -26,7 +26,7 @@ description: 形状图层。支持 path、fill/stroke、线宽/线帽/连接样
 
 ## 类成员 (Class members)
 
-当前运行时未额外暴露 `CAShapeLayer` 的类成员。
+当前接口未额外暴露 `CAShapeLayer` 的类成员。
 
 ## 相关
 

package/src/content/docs/reference/quartzcore/catext-layer.md

@@ -3,7 +3,7 @@ title: CATextLayer
 description: 文本图层。支持 string/font/fontSize、alignmentMode、foregroundColor 与 wrapped。
 ---
 
-`CATextLayer` 继承自 [CALayer](/reference/quartzcore/calayer/)，用于在图层中渲染文本。插件运行时的 `string` 可为字符串或富文本等运行时对象。
+`CATextLayer` 继承自 [CALayer](/reference/quartzcore/calayer/)，用于在图层中渲染文本。插件环境的 `string` 可为字符串或富文本等宿主对象。
 
 ## 实例成员 (Instance members)
 
@@ -12,16 +12,16 @@ description: 文本图层。支持 string/font/fontSize、alignmentMode、foregr
 | 属性 | 类型 | 说明 |
 | --- | --- | --- |
 | `string` | any | 文本内容（可为字符串或富文本对象）。 |
-| `font` | any | 字体对象（运行时类型为 id）。 |
+| `font` | any | 字体对象id。 |
 | `fontSize` | number | 字号。 |
-| `foregroundColor` | any | 前景色（运行时类型为 id）。 |
+| `foregroundColor` | any | 前景色id。 |
 | `alignmentMode` | string \| null | 对齐方式。 |
 | `truncationMode` | string \| null | 截断模式。 |
 | `wrapped` | boolean | 是否自动换行。 |
 
 ## 类成员 (Class members)
 
-当前运行时未额外暴露 `CATextLayer` 的类成员。
+当前接口未额外暴露 `CATextLayer` 的类成员。
 
 ## 相关
 

package/src/content/docs/reference/quartzcore/catransaction.md

@@ -5,9 +5,11 @@ description: Core Animation 事务。支持 begin/commit、设置动画时长/
 
 `CATransaction` 用于把多个图层属性变更包装成一次事务，并统一控制该事务的动画参数（时长、时间函数、是否禁用隐式动画等）。
 
+本文非完整定义，完整版见[CATransaction](https://developer.apple.com/documentation/quartzcore/catransaction?language=objc)。
+
 ## 实例成员 (Instance members)
 
-当前运行时未暴露 `CATransaction` 的实例成员；通常直接使用其类成员 API。
+当前接口未暴露 `CATransaction` 的实例成员；默认直接使用其类成员 API。
 
 ## 类成员 (Class members)
 
@@ -17,8 +19,8 @@ description: Core Animation 事务。支持 begin/commit、设置动画时长/
 | --- | --- | --- | --- |
 | `begin()` | — | void | 开始事务。 |
 | `commit()` | — | void | 提交事务。 |
-| `flush()` | — | void | 立即提交/刷新（取决于运行时实现）。 |
-| `lock()` / `unlock()` | — | void | 事务锁（一般不常用）。 |
+| `flush()` | — | void | 立即提交/刷新。 |
+| `lock()` / `unlock()` | — | void | 事务锁。 |
 
 ### 动画参数
 

package/src/content/docs/reference/quartzcore/catransform-layer.md

@@ -3,15 +3,15 @@ title: CATransformLayer
 description: 3D 变换容器图层。用于在图层树中保留 3D 变换效果。
 ---
 
-`CATransformLayer` 继承自 [CALayer](/reference/quartzcore/calayer/)。它通常作为 3D 变换的容器使用，以便其子图层的 3D 变换能正确合成。
+`CATransformLayer` 继承自 [CALayer](/reference/quartzcore/calayer/)。它默认作为 3D 变换的容器使用，以便其子图层的 3D 变换能正确合成。
 
 ## 实例成员 (Instance members)
 
-当前运行时未额外暴露 `CATransformLayer` 的专属实例成员；可直接使用 `CALayer` 的通用属性与方法来管理图层树与动画。
+当前接口未额外暴露 `CATransformLayer` 的专属实例成员；可直接使用 `CALayer` 的通用属性与方法来管理图层树与动画。
 
 ## 类成员 (Class members)
 
-当前运行时未额外暴露 `CATransformLayer` 的专属类成员。
+当前接口未额外暴露 `CATransformLayer` 的专属类成员。
 
 ## 相关
 

package/src/content/docs/reference/quartzcore/catransition.md

@@ -3,7 +3,11 @@ title: CATransition
 description: 转场动画。通过 type/subtype 等字段描述转场类型，并支持 timingFunction、removedOnCompletion 等。
 ---
 
-`CATransition` 继承自 [CAAnimation](/reference/quartzcore/caanimation/)，用于描述层的转场动画（例如淡入淡出、推入等）。插件运行时暴露了常见动画配置字段。
+`CATransition` 继承自 [CAAnimation](/reference/quartzcore/caanimation/)，用于描述层的转场动画（例如淡入淡出、推入等）。插件环境暴露了常见动画配置字段。
+
+## 接口状态
+
+`CATransition`按`CATransition.animation()`创建。
 
 ## 实例成员 (Instance members)
 
@@ -16,9 +20,9 @@ description: 转场动画。通过 type/subtype 等字段描述转场类型，
 | `timingFunction` | CAMediaTimingFunction \| null | timingFunction。 |
 | `delegate` | id | delegate 对象。 |
 | `filter` | id | filter。 |
-| `keyPath` | string \| null | keyPath（若运行时复用字段）。 |
-| `fromValue` / `toValue` / `byValue` | any | 起始/结束/增量值（若运行时复用字段）。 |
-| `values` | NSArray | values（若运行时复用字段）。 |
+| `keyPath` | string \| null | keyPath（复用字段）。 |
+| `fromValue` / `toValue` / `byValue` | any | 起始/结束/增量值（复用字段）。 |
+| `values` | NSArray | values（复用字段）。 |
 | `keyTimes` | NSArray | keyTimes。 |
 | `timingFunctions` | NSArray | timingFunctions。 |
 | `calculationMode` | string \| null | 计算模式。 |
@@ -30,11 +34,11 @@ description: 转场动画。通过 type/subtype 等字段描述转场类型，
 | `additive` | boolean | 是否 additive。 |
 | `cumulative` | boolean | 是否 cumulative。 |
 | `removedOnCompletion` | boolean | 是否在完成后移除。 |
-| `animations` | NSArray | 子动画数组（若运行时复用字段）。 |
+| `animations` | NSArray | 子动画数组（复用字段）。 |
 
 ## 类成员 (Class members)
 
-当前运行时未额外暴露 `CATransition` 的类成员。
+当前接口未额外暴露 `CATransition` 的类成员。
 
 ## 相关
 

package/src/content/docs/reference/quartzcore/cavalue-function.md

@@ -3,7 +3,7 @@ title: CAValueFunction
 description: 值函数。可按名称创建，并可读取 name。
 ---
 
-`CAValueFunction` 用于描述某些动画/变换相关的值函数。它通常作为 `CAPropertyAnimation.valueFunction` 或若干动画对象的 `valueFunction` 字段出现。
+`CAValueFunction` 用于描述某些动画/变换相关的值函数。它默认作为 `CAPropertyAnimation.valueFunction` 或若干动画对象的 `valueFunction` 字段出现。
 
 ## 实例成员 (Instance members)
 

package/src/content/docs/reference/uikit/ns-mutable-paragraph-style.md

@@ -7,14 +7,14 @@ description: 可变段落样式（可用于构造/修改富文本段落属性）
 
 ## 实例成员 (Instance members)
 
-`NSMutableParagraphStyle` 用法上通常是：创建一个实例 → 设置段落相关属性 → 作为富文本属性（例如 `paragraphStyle`）写入到 `NSAttributedString`/`NSTextStorage`/`UITextView` 等。
+`NSMutableParagraphStyle` 用法上默认是：创建一个实例 → 设置段落相关属性 → 作为富文本属性（例如 `paragraphStyle`）写入到 `NSAttributedString`/`NSTextStorage`/`UITextView` 等。
 
 ## 类成员 (Class members)
 
-当前运行时未额外暴露 `NSMutableParagraphStyle` 的类成员。
+当前接口未额外暴露 `NSMutableParagraphStyle` 的类成员。
 
 ## 提示
 
 - 用于作为 `NSAttributedString` 的属性值（例如 paragraphStyle）。
-- 具体可用成员建议用站内搜索成员名（或结合系统 UIKit 文档理解）。
+- 具体可用成员用站内搜索成员名（或结合系统 UIKit 文档理解）。
 

package/src/content/docs/reference/uikit/ns-paragraph-style.md

@@ -7,14 +7,13 @@ description: 段落样式（只读，富文本排版属性）。
 
 ## 实例成员 (Instance members)
 
-`NSParagraphStyle` 在插件运行时中主要作为“富文本属性对象”被读取，属性较多，建议直接用站内搜索定位你关心的属性名。
+`NSParagraphStyle` 主要作为“富文本属性对象”被读取，属性较多，直接用站内搜索定位你关心的属性名。
 
 ## 类成员 (Class members)
 
-当前运行时未额外暴露 `NSParagraphStyle` 的类成员。
+当前接口未额外暴露 `NSParagraphStyle` 的类成员。
 
 ## 提示
 
-- 该类型的属性较多，通常作为富文本属性对象被读取。
+- 该类型的属性较多，默认作为富文本属性对象被读取。
 - 需要修改段落样式时使用 `NSMutableParagraphStyle`。
-

package/src/content/docs/reference/uikit/ns-text-storage.md

@@ -7,14 +7,13 @@ description: 富文本存储（可变 attributed string 的存储与通知层）
 
 ## 实例成员 (Instance members)
 
-`NSTextStorage` 在插件环境中通常由 `UITextView.textStorage` 获取并间接使用。若需要定位某个成员名，建议用站内搜索。
+`NSTextStorage` 默认由 `UITextView.textStorage` 获取并间接使用。若需要定位某个成员名，用站内搜索。
 
 ## 类成员 (Class members)
 
-当前运行时未额外暴露 `NSTextStorage` 的类成员。
+当前接口未额外暴露 `NSTextStorage` 的类成员。
 
 ## 提示
 
-- 在插件中通常通过 `UITextView` 等组件间接使用。
-- 具体可用成员建议使用站内搜索成员名。
-
+- 在插件中默认通过 `UITextView` 等组件间接使用。
+- 具体可用成员使用站内搜索成员名。

package/src/content/docs/reference/uikit/uiactivity-indicator-view.md

@@ -7,11 +7,11 @@ description: 加载指示器（菊花）。
 
 ## 实例成员 (Instance members)
 
-`UIActivityIndicatorView` 的成员用于控制“是否在转/是否隐藏/样式”等。若你需要具体成员名，建议用站内搜索定位。
+`UIActivityIndicatorView` 的成员用于控制“是否在转/是否隐藏/样式”等。若你需要具体成员名，用站内搜索定位。
 
 ## 类成员 (Class members)
 
-当前运行时未额外暴露 `UIActivityIndicatorView` 的类成员。
+当前接口未额外暴露 `UIActivityIndicatorView` 的类成员。
 
 ## 提示
 

package/src/content/docs/reference/uikit/uiapplication.md

@@ -3,7 +3,7 @@ title: UIApplication
 description: iOS 应用级入口对象（单例），用于打开 URL、管理本地通知等。
 ---
 
-`UIApplication` 是 iOS 应用级入口对象。在插件环境中常用于打开 URL、判断 URL 是否可打开，以及（旧式）本地通知调度。
+`UIApplication` 是 iOS 应用级入口对象。常用于打开 URL、判断 URL 是否可打开，以及（旧式）本地通知调度。
 
 ## 类成员 (Class members)
 

package/src/content/docs/reference/uikit/uibar-button-item.md

@@ -7,14 +7,13 @@ description: 条形按钮项（导航栏/工具栏按钮）。
 
 ## 实例成员 (Instance members)
 
-`UIBarButtonItem` 在插件运行时暴露的属性/方法较多。你可以按需通过站内搜索定位具体成员（例如 `title`、`image`、`enabled`、`customView`、`target`、`action` 等）。
+`UIBarButtonItem` 暴露的属性/方法较多。你可以按需通过站内搜索定位具体成员（例如 `title`、`image`、`enabled`、`customView`、`target`、`action` 等）。
 
 ## 类成员 (Class members)
 
-当前运行时未额外暴露 `UIBarButtonItem` 的类成员。
+当前接口未额外暴露 `UIBarButtonItem` 的类成员。
 
 ## 提示
 
 - 典型用法是配置 `target` + `action` 来响应点击。
-- 具体属性/方法建议用站内搜索成员名。
-
+- 具体属性/方法用站内搜索成员名。

package/src/content/docs/reference/uikit/uibar-item.md

@@ -7,14 +7,13 @@ description: 工具条/导航条条目基类（title/image 等）。
 
 ## 实例成员 (Instance members)
 
-`UIBarItem` 在插件运行时中通常作为基类被间接使用（例如 `UIBarButtonItem`、`UITabBarItem`）。若你需要定位某个通用成员（如 `title`/`image`/`enabled`），建议直接站内搜索成员名。
+`UIBarItem` 默认作为基类被间接使用（例如 `UIBarButtonItem`、`UITabBarItem`）。若你需要定位某个通用成员（如 `title`/`image`/`enabled`），直接站内搜索成员名。
 
 ## 类成员 (Class members)
 
-当前运行时未额外暴露 `UIBarItem` 的类成员。
+当前接口未额外暴露 `UIBarItem` 的类成员。
 
 ## 提示
 
 - 常见子类：`UIBarButtonItem`、`UITabBarItem`、`UINavigationItem`（语义不同）。
 - 具体成员可用站内搜索成员名定位。
-

package/src/content/docs/reference/uikit/uibezier-path.md

@@ -136,8 +136,8 @@ static bezierPathWithCGPath(CGPath: any): UIBezierPath
 
 ## 实例成员 (Instance members)
 
-`UIBezierPath` 的实例方法（如 moveTo/lineTo/append/closePath、fill/stroke、变换、命中测试等）较多，且组合方式灵活。建议通过站内搜索你关心的方法名来快速定位。
+`UIBezierPath` 的实例方法（如 moveTo/lineTo/append/closePath、fill/stroke、变换、命中测试等）较多，且组合方式灵活。通过站内搜索你关心的方法名来快速定位。
 
 ## 提示
 
-- 具体绘制/变换/填充/描边等方法较多，建议用站内搜索成员名。
+- 具体绘制/变换/填充/描边等方法较多，用站内搜索成员名。

package/src/content/docs/reference/uikit/uibutton.md

@@ -19,7 +19,7 @@ description: 按钮控件，需通过 addTargetActionForControlEvents 绑定点
 | `setTitleColorForState(color, state)` | 设置标题颜色。 |
 | `setImageForState(image, state)` | 设置图片。 |
 | `setBackgroundImageForState(image, state)` | 设置背景图。 |
-| `addTargetActionForControlEvents(target, action, event)` | target 通常为 self，action 为 'methodName:'，event 1<<6 为点击。 |
+| `addTargetActionForControlEvents(target, action, event)` | target 为 self，action 为 'methodName:'，event 1<<6 为点击。 |
 
 ## 相关
 

package/src/content/docs/reference/uikit/uicollection-view-cell.md

@@ -1,22 +1,22 @@
 ---
 title: UICollectionViewCell
-description: UICollectionView 的基础单元格类型。在插件运行时主要作为参数/返回值类型出现。
+description: UICollectionView 的基础单元格类型。主要作为参数/返回值类型出现。
 ---
 
-`UICollectionViewCell` 是 `UICollectionView` 的单元格类型，通常由 `UICollectionView` 通过复用机制创建并返回。
+`UICollectionViewCell` 是 `UICollectionView` 的单元格类型，默认由 `UICollectionView` 通过复用机制创建并返回。
 
-在当前插件运行时环境中，`UICollectionViewCell` **没有额外暴露专属的可调用成员**（即不提供区别于其父类/通用视图的新增属性或方法）。因此它更多用于：
+在当前插件环境中，`UICollectionViewCell` **没有额外暴露专属的可调用成员**（即不提供区别于其父类/通用视图的新增属性或方法）。因此它更多用于：
 
 - 作为 `UICollectionView.cellForItemAtIndexPath(...)` 等方法的返回值类型
 - 作为 `indexPathForCell(cell)` 等查询方法的入参类型
 
 ## 实例成员 (Instance members)
 
-当前运行时未额外暴露 `UICollectionViewCell` 的实例成员。
+当前接口未额外暴露 `UICollectionViewCell` 的实例成员。
 
 ## 类成员 (Class members)
 
-当前运行时未额外暴露 `UICollectionViewCell` 的类成员。
+当前接口未额外暴露 `UICollectionViewCell` 的类成员。
 
 ## 相关
 

package/src/content/docs/reference/uikit/uicollection-view-controller.md

@@ -5,6 +5,16 @@ description: 承载 UICollectionView 的控制器。可通过布局初始化并
 
 `UICollectionViewController` 继承自 [UIViewController](/reference/uikit/uiview-controller/)，用于管理一个 `UICollectionView` 实例与其布局对象，适合在插件中以“控制器 + view”的方式复用界面逻辑。
 
+## 推荐创建路径
+
+当前插件环境下，更稳定的路径是：
+
+1. 创建`UICollectionViewFlowLayout`并先设置固定参数，如`itemSize`、`sectionInset`、`minimumLineSpacing`。
+2. 使用`initWithCollectionViewLayout(layout)`创建`UICollectionViewController`。
+3. 通过`controller.collectionView`取得实例，完成`registerClass...`、`dataSource/delegate`绑定与`reloadData()`。
+
+相比之下，直接走`UICollectionView`的`initWithFrame:collectionViewLayout:`路径在当前桥接里不稳定，不建议作为主路径。
+
 ## 实例成员 (Instance members)
 
 ### 属性
@@ -22,11 +32,21 @@ description: 承载 UICollectionView 的控制器。可通过布局初始化并
 | --- | --- | --- | --- |
 | `initWithCollectionViewLayout(layout)` | layout: UICollectionViewLayout | id | 以指定布局初始化。 |
 
+### 数据源最小实现
+
+至少实现以下方法：
+
+- `numberOfSectionsInCollectionView`
+- `collectionView:numberOfItemsInSection:`
+- `collectionView:cellForItemAtIndexPath:`
+
+`dataSource/delegate`使用`JSB.defineClass`导出的实例对象承载，以确保selector映射稳定。
+
 ## 类成员 (Class members)
 
-当前运行时未额外暴露 `UICollectionViewController` 的类成员。
+当前接口未额外暴露 `UICollectionViewController` 的类成员。
 
 ## 相关
 
 - [UIViewController](/reference/uikit/uiview-controller/)
-- [UICollectionView](/reference/uikit/uicollection-view/)、[UICollectionViewLayout](/reference/uikit/uicollection-view-layout/)
+- [UICollectionView](/reference/uikit/uicollection-view/)、[UICollectionViewLayout](/reference/uikit/uicollection-view-layout/)、[UICollectionViewFlowLayout](/reference/uikit/uicollection-view-flow-layout/)

package/src/content/docs/reference/uikit/uicollection-view-flow-layout.md

@@ -0,0 +1,54 @@
+---
+title: UICollectionViewFlowLayout
+description: UICollectionView的流式布局。常用于固定网格参数配置。
+---
+
+`UICollectionViewFlowLayout`是`UICollectionViewLayout`的常用子类，用于按行列流式排布cell。插件场景优先使用固定`itemSize/sectionInset/minimumLineSpacing`方案。
+
+## 使用规范
+
+- 更稳定的创建路径是：先创建`UICollectionViewFlowLayout`，再用`UICollectionViewController.initWithCollectionViewLayout(layout)`拿到`collectionView`。
+- `initWithFrame:collectionViewLayout:`在当前桥接里不稳定，不建议作为主路径。
+- 动态尺寸回调例如`sizeForItemAtIndexPath`在JS桥接里风险较高，后置。
+
+## 实例成员 (Instance members)
+
+### 属性
+
+| 属性 | 类型 | 说明 |
+| --- | --- | --- |
+| `itemSize` | [`CGSize`](/reference/value-sturct/#cgsize) | 单个item尺寸。 |
+| `sectionInset` | [`UIEdgeInsets`](/reference/value-sturct/#uiedgeinsets) | section内边距。 |
+| `minimumLineSpacing` | number | 最小行间距。 |
+| `minimumInteritemSpacing` | number | 最小item间距。 |
+| `headerReferenceSize` | [`CGSize`](/reference/value-sturct/#cgsize) | 头部参考尺寸。 |
+| `footerReferenceSize` | [`CGSize`](/reference/value-sturct/#cgsize) | 尾部参考尺寸。 |
+| `invalidateFlowLayoutAttributes` | boolean | 只读。布局属性是否失效。 |
+| `invalidateFlowLayoutDelegateMetrics` | boolean | 只读。delegate度量是否失效。 |
+
+### 方法
+
+| 方法 | 参数 | 返回值 | 说明 |
+| --- | --- | --- | --- |
+| `invalidateLayout()` | — | void | 标记布局失效并触发重算。 |
+| `prepareLayout()` | — | void | 布局准备阶段。 |
+| `layoutAttributesForElementsInRect(rect)` | rect: [`CGRect`](/reference/value-sturct/#cgrect) | NSArray | 返回区域内元素布局属性。 |
+| `collectionViewContentSize()` | — | [`CGSize`](/reference/value-sturct/#cgsize) | 返回内容尺寸。 |
+
+## 类成员 (Class members)
+
+| 成员 | 返回值 | 说明 |
+| --- | --- | --- |
+| `layoutAttributesClass()` | Class | 返回布局属性类。 |
+| `invalidationContextClass()` | Class | 返回失效上下文类。 |
+
+## 问题排查
+
+- 创建成功但不显示时，优先检查`frame/bounds`是否为0、`itemSize`是否为0、是否已挂到可见view层级。
+- `registerClass...`缺失或`reuseId`不一致会导致`dequeue`失败。
+
+## 相关
+
+- [UICollectionView](/reference/uikit/uicollection-view/)
+- [UICollectionViewController](/reference/uikit/uicollection-view-controller/)
+- [UICollectionViewLayout](/reference/uikit/uicollection-view-layout/)