问题的根源在于 LayoutInflater.inflate() 做的事情太重了：解析编译后的二进制 XML、通过反射逐个实例化 View、递归构建整棵 View 树、生成并应用 LayoutParams。这些步骤每次 inflate 都要完整走一遍，即使布局结构完全相同。

FastInflater 的核心思路很简单：既然同一个 layoutId 每次 inflate 出来的 View 树结构一样，那为什么不把用完的 View 清理干净放回池里，下次直接取出来用？池命中时，inflate 耗时从几十毫秒变成一次 ConcurrentLinkedDeque.poll() —— 本质上是零。

架构总览

FastInflater 由六个核心组件构成：

┌─────────────────────────────────────────────────────┐
│                   FastInflater                        │
│  (单例入口，生命周期监听，内存压力响应)                    │
├─────────────────────────────────────────────────────┤
│  ViewPool          │  InflateTracker   │  PoolStats  │
│  (池化存取/预热)    │  (耗时追踪)        │  (命中率)    │
├─────────────────────────────────────────────────────┤
│  ViewCleaner       │  ViewRecyclePolicy │ PoolableView│
│  (状态清理)         │  (自定义策略)       │ (自清理接口) │
└─────────────────────────────────────────────────────┘

调用链非常短：inflate() 先查池，命中直接返回；未命中走标准 LayoutInflater。recycle() 清理 View 状态后入队。预热在后台线程或主线程 IdleHandler 中提前创建 View 填池。

池键设计：一个 Long 搞定隔离

View 池的 key 是一个 Long，高 32 位是 layoutId，低 32 位是隔离 hash：

private fun keyFor(@LayoutRes layoutId: Int, context: Context): Long {
    val high = layoutId.toLong() shl 32
    if (!hostIsolation && !factoryIsolation) return high
    var low = 0
    if (hostIsolation) low = hostHash(context)
    if (factoryIsolation) low = low xor factoryHash(context)
    return high or (low.toLong() and 0xFFFFFFFFL)
}

这个设计有几个好处。默认情况下（两种隔离都关），低 32 位为 0，key 退化为纯 layoutId，所有 context 共享同一个桶——这是绝大多数项目的最优选择，因为全局 theme 一致。需要区分不同 Activity theme 时开启 hostIsolation，key 会包含 Activity 的 identityHashCode；需要区分不同 LayoutInflater.Factory2 时开启 factoryIsolation。用 Long 做 key 避免了每次 obtain/recycle 分配对象，对 GC 友好。

底层数据结构是 ConcurrentHashMap<Long, ConcurrentLinkedDeque<View>>。ConcurrentLinkedDeque 支持无锁并发读写，obtain 从头部 poll，recycle 从尾部 offer，天然适合池化场景。

LayoutParams 兼容性检查

池化复用有一个容易忽略的问题：同一个 layoutId 可能被 inflate 到不同类型的 parent 中。一个 item_feed.xml 的根节点如果带 layout_weight，它的 LayoutParams 是 LinearLayout.LayoutParams；但如果下次 obtain 时 parent 是 FrameLayout，直接 addView 会抛异常或布局错乱。

FastInflater 在 obtain 时做了兼容性检查：

private fun pollCompatible(key: Long, layoutId: Int, context: Context, parent: ViewGroup?): View? {
    val deque = pool[key] ?: return null
    val rejected = ArrayList<View>(4)
    var found: View? = null

    for (i in 0 until deque.size) {
        val view = deque.poll() ?: break
        if (ensureAttachableToParent(layoutId, context, parent, view)) {
            found = view
            break
        }
        rejected.add(view)
    }
    // 不兼容的 View 放回队尾
    for (view in rejected) deque.offerLast(view)
    return found
}

如果池中 View 的 LayoutParams 与当前 parent 不兼容，FastInflater 会重新解析布局 XML 的根节点属性，用 parent.generateLayoutParams() 生成正确的 LayoutParams。兼容性结果会被缓存到 layoutParamsCompatibility map 中，避免重复反射。

异步预热与自动降级

预热是 FastInflater 性能收益的关键——如果池里没有 View，第一次 inflate 还是要走标准路径。预热策略分两层：

后台线程预热：默认使用一个固定大小的线程池（availableProcessors - 1，最少 2 线程）在后台 inflate。这里有一个 Android 历史坑：Android 8.x 及以下的 Resources 不是线程安全的，所以 FastInflater 自身的 inflateAsync 用单线程 executor 避免并发问题，而 ViewPool 的预热用多线程是因为预热时 parent 为 null，不涉及 Resources 的并发读。

主线程 IdleHandler 降级：部分 View 不能在后台线程创建——ComposeView 内部依赖 LiveData，WebView/SurfaceView/TextureView 要求主线程，某些自定义 View 在构造函数里访问 Handler 或 Looper。FastInflater 的处理策略是：

1. 预热前先扫描布局 XML 的 tag，如果包含已知的主线程组件（WarmUpFallbackClassifier 维护了一个白名单），直接走主线程 IdleHandler
2. 未知组件仍尝试后台 inflate，如果抛出主线程依赖异常（通过异常消息模式匹配识别），自动标记该布局为 mainThreadOnly，剩余预热数量转移到主线程
3. 同时从异常堆栈中提取出问题 View 的类名，加入 mainThreadOnlyViewClasses 集合，后续其他布局如果包含同一个类也会直接走主线程

// WarmUpFallbackClassifier 的异常识别逻辑
fun isMainThreadDependencyFailure(error: Throwable): Boolean {
    return error.causeSequence().any { cause ->
        val message = cause.message ?: return@any false
        message.contains("Can't create handler inside thread") ||
            message.contains("has not called Looper.prepare()") ||
            message.contains("must be called on the main thread", ignoreCase = true)
    }
}

主线程 IdleHandler 每次 idle 只 inflate 1 个 View，避免长时间占用主线程影响用户交互。这是一个「宁可慢一点预热完，也不能卡用户」的设计取舍。

View 状态清理：复用的安全边界

池化复用最容易出 bug 的地方不是取和存，而是「清理不干净」。上一条数据的头像、文字、点击状态如果残留到下一条，就是肉眼可见的 UI 错乱。

ViewCleaner 在 View 入池时递归清理整棵 View 树：

private fun cleanSingle(view: View) {
    if (view is PoolableView) view.onRecycleForPool()

    view.setOnClickListener(null)
    view.setOnLongClickListener(null)
    view.setOnTouchListener(null)
    view.translationX = 0f; view.translationY = 0f; view.translationZ = 0f
    view.scaleX = 1f; view.scaleY = 1f
    view.alpha = 1f
    view.clearAnimation()
    view.visibility = View.VISIBLE
    view.isEnabled = true
    view.isSelected = false
    view.contentDescription = null

    if (view is TextView) view.text = null
    else if (view is ImageView) view.setImageDrawable(null)
}

注意几个设计决策：

不清除 tag：DataBinding 依赖 view.tag 存储 binding 信息，清除会导致 DataBindingUtil.bind() 返回 null。这是 FastDataBinding 能工作的前提。

归一化到「可见/可用」默认值：visibility 归为 VISIBLE，isEnabled 归为 true。这意味着如果布局 XML 中某个子 View 默认是 GONE（比如一个占位 View），复用后它会变成 VISIBLE——业务 bind 阶段必须显式设置。这是一个「宁可多设置一次，也不能漏清理」的策略。

PoolableView 接口：自定义 View 可以实现这个接口，ViewCleaner 递归时会调用 onRecycleForPool()，让 View 自己清理内部业务状态（展开/折叠标记、临时 Drawable 等）。这比全局 ViewRecyclePolicy 更内聚——状态归谁管，清理就归谁做。

生命周期安全模型

池化复用引入了一个微妙的生命周期问题：如果一个自定义 View 在构造或 attach 时注册了 EventBus、Lifecycle observer、Activity callback，进入池后这些注册关系可能继续存活。View 被另一个 Activity 取出复用时，旧的注册关系指向已销毁的 Activity，轻则收到无意义的事件，重则 NPE 崩溃。

FastInflater 提供了三层防护：

第一层：Activity 销毁时清池。通过 ActivityLifecycleCallbacks 监听 onActivityDestroyed，调用 viewPool.clearForHost(activity)。如果开启了 hostIsolation，只清除该 Activity 对应的桶；否则清空整个池。这保证池中不会长期持有已销毁 Activity 的 context。

第二层：按布局关闭池化。对于确实无法可靠解绑的布局，直接 setPoolingEnabled(layoutId, false)。关闭后该 layout 的 obtain 永远返回 null，recycle 直接丢弃，warmUp 跳过。布局仍然通过标准 LayoutInflater 创建，只是不参与池化。

第三层：内存压力响应。通过 ComponentCallbacks2 监听系统内存压力：TRIM_MEMORY_MODERATE 及以上清空池，TRIM_MEMORY_BACKGROUND 每个桶只保留 1 个。Configuration 变化（如旋转屏幕）也会清空池，因为旧 View 的尺寸/资源可能已失效。

自适应池大小

池太小，命中率低，预热白做；池太大，内存浪费，低频布局占着坑不用。FastInflater 的 autoTune 根据运行时统计数据自动调整：

fun autoTune(topN: Int = 20, minSize: Int = 2, maxSize: Int = 12) {
    val top = InflateTracker.topN(topN)
    if (top.isEmpty()) return
    val maxCount = top.first().second.count.get()

    top.forEach { (layoutId, stat) ->
        val count = stat.count.get()
        val suggested = (count.toFloat() / maxCount * (maxSize - minSize) + minSize)
            .toInt().coerceIn(minSize, maxSize)
        perLayoutMaxSize[layoutId] = suggested
    }
}

逻辑很直接：取 inflate 次数最多的前 N 个布局，按使用频率线性映射到 [minSize, maxSize] 区间。高频布局拿到更大的池，低频布局保持最小值。建议在应用运行 3~5 分钟后调用一次，此时统计数据已经能反映真实使用模式。

诊断体系：InflateTracker + PoolStats

FastInflater 不只是一个优化工具，它首先是一个诊断工具。InflateTracker 记录每次 inflate 的纳秒级耗时，按 layoutId 聚合：

inline fun <T> track(@LayoutRes layoutId: Int, block: () -> T): T {
    if (!enabled) return block()
    val start = System.nanoTime()
    val result = block()
    recordInflate(layoutId, System.nanoTime() - start)
    return result
}

PoolStats 记录全局和 per-layout 的 hit/miss 次数。两者配合使用：先用 InflateTracker 找到耗时最高的布局，再看 PoolStats 判断池化是否生效。命中率低于 50% 说明预热不足或池太小；高于 90% 说明池化充分发挥作用。

两个埋点默认开启，因为诊断数据本身就是这个库的核心价值。调优完成后可以一键关闭：

FastInflater.get().setMetricsEnabled(false)

关闭后热路径上的 System.nanoTime()、原子自增、HashMap 查询全部消除，inflate 只保留池查询和回退 inflate 的最小逻辑。

与 RecyclerView 的协作边界

RecyclerView 自己有一套完整的 ViewHolder 回收复用机制（Scrap → Cache → RecycledViewPool）。FastInflater 不试图替代它，而是只在「创建侧」发力：

RecyclerView 需要新 ViewHolder
    → RecycledViewPool 为空
        → Adapter.onCreateViewHolder()
            → FastInflater.get().inflate(parent, viewType)
                → 池命中？直接返回 : 标准 LayoutInflater

FastInflaterRecycler.install() 做两件事：设置一个 FastRecycledViewPool（实际上只是标记，回收逻辑完全交给 super），然后触发预热。预热的 View 进入 FastInflater 的池，当 onCreateViewHolder 调用 FastInflater.get().inflate() 时命中。ViewHolder 创建后的滑动复用完全由 RecyclerView 自己管理，两个池不会冲突。

这个设计的好处是侵入性极低：只需要在 onCreateViewHolder 里把 LayoutInflater.from(context).inflate(...) 换成 FastInflater.get().inflate(...)，其他代码不用动。

适用场景与局限

FastInflater 最适合这些场景：

• RecyclerView 密集列表的首屏加载（ViewHolder 首次创建是最大瓶颈）
• Tab 切换、ViewPager 页面切换中反复创建相同布局
• Dialog/BottomSheet 反复弹出关闭
• 任何「同一个 layoutId 被高频重复 inflate」的地方

不适合的场景：

• 已全面迁移到 Jetpack Compose 的项目（Compose 没有 inflate 概念）
• 布局极简（单个 TextView），inflate 本身只要 1~2ms，池化收益不明显
• 布局包含大量生命周期敏感组件且无法可靠解绑，关闭池化后等于没用

总结

FastInflater 的技术路线可以概括为：用空间换时间，用预热换首帧。它不是银弹——池化引入了状态清理的复杂度，异步预热引入了线程安全的考量，生命周期管理引入了额外的防护层。但在它适用的场景里（高频重复 inflate 的 XML 布局），收益是确定性的：池命中时 inflate 耗时为零。

对于仍在维护大量 XML 布局的 Android 项目，这可能是投入产出比最高的性能优化手段之一。

Font Metrics ≠ 你看到的字

Android 的 TextView 用 font metrics 定位文字。Font metrics 描述的是字体的”设计空间”，而不是某个具体字符的实际像素范围：

┌─────────────────────────────┐
│          leading             │  ← 行间距预留
├─────────────────────────────┤
│          ascent              │  ← 包含音调符号空间 (Ä, É)
│                             │
│      ┌───────────┐          │
│      │  visible  │          │  ← 实际墨水区域 (glyph bounds)
│      │   glyph   │          │
│      └───────────┘          │
│                             │
├─────────────────────────────┤
│          descent             │  ← 包含下挂字母空间 (g, y, p)
└─────────────────────────────┘

TextView 的”居中”是把 ascent 到 descent 这段区间居中在容器里。但对于数字 “1”~”9”：

• 实际墨水区域只占 ascent 的一部分（数字不需要音调符号的空间）
• descent 几乎为零（数字没有下挂部分）

结果就是：font metrics 的几何中心和字形的视觉中心不重合，文字看起来偏上。

容器越大，这个偏移占比越小，越不明显。但当容器只有 12dp 高时，1~2px 的偏移肉眼可见。

用 getTextBounds() 验证

用 Paint.getTextBounds() 可以拿到字符实际墨水区域的 Rect，和 FontMetrics 对比一下就能看出差距：

val paint = Paint().apply { textSize = 30f }

val metrics = paint.fontMetrics
// metrics.ascent = -28.0  (baseline 以上 28px)
// metrics.descent = 7.0   (baseline 以下 7px)
// 总高度 = 35px，中心在 baseline 上方 10.5px

val bounds = Rect()
paint.getTextBounds("3", 0, 1, bounds)
// bounds.top = -21  (baseline 以上 21px)
// bounds.bottom = 0 (刚好到 baseline)
// 总高度 = 21px，中心在 baseline 上方 10.5px

font metrics 认为文字占 35px，实际 “3” 只占 21px。两者的”中心”差了 (35 - 21) / 2 = 7px。在 12dp（约 36px @3x）的容器里，7px 的偏移非常明显。

解法：基于 glyph bounds 做测量和绘制

放弃 TextView，继承 View，自己用 getTextBounds() 做居中：

class GlyphCenteredTextView(context: Context, attrs: AttributeSet?) : View(context, attrs) {

    private val textBounds = Rect()
    private val textPaint = Paint(Paint.ANTI_ALIAS_FLAG)
    private var textString = ""

    override fun onMeasure(widthMeasureSpec: Int, heightMeasureSpec: Int) {
        if (textString.isNotEmpty()) {
            textPaint.getTextBounds(textString, 0, textString.length, textBounds)
        } else {
            textBounds.setEmpty()
        }
        val desiredWidth = paddingLeft + textBounds.width() + paddingRight
        val desiredHeight = paddingTop + textBounds.height() + paddingBottom
        setMeasuredDimension(
            resolveSize(desiredWidth, widthMeasureSpec),
            resolveSize(desiredHeight, heightMeasureSpec),
        )
    }

    override fun onDraw(canvas: Canvas) {
        if (textString.isEmpty()) return

        val contentLeft = paddingLeft
        val contentRight = width - paddingRight
        val contentTop = paddingTop
        val contentBottom = height - paddingBottom

        val x = contentLeft +
            (contentRight - contentLeft - textBounds.width()) / 2F -
            textBounds.left
        val baseline = contentTop +
            (contentBottom - contentTop - textBounds.height()) / 2F -
            textBounds.top

        canvas.drawText(textString, x, baseline, textPaint)
    }
}

几个关键点：

为什么要减 textBounds.left？

getTextBounds() 返回的 left 不一定是 0。斜体字或某些字形的左侧会有 bearing（留白或溢出）。减去 left 才能让字形的视觉左边缘对齐到我们计算的 x 位置。

为什么 -textBounds.top 就是 baseline 偏移？

getTextBounds() 的坐标系以 baseline 为原点，baseline 以上为负。所以 top 是负数（比如 -21），-top 就是”从字形顶部到 baseline 的距离”。我们先算出字形顶部应该在哪（居中后的位置），再加上这个距离，就得到了 baseline 的 y 坐标。

为什么 onMeasure 用 glyph bounds 而不是 font metrics？

如果用 font metrics 测量高度（ascent + descent = 35px），然后在 onDraw 里用 glyph bounds 居中（实际只有 21px），wrap_content 时容器会比内容大很多。对于角标这种紧凑场景，测量和绘制必须基于同一套数据。

什么时候该用这个方案

这不是一个通用方案。它适合的场景有明确的特征：

• 容器很小（≤ 16dp 高），像素级偏移肉眼可见
• 只显示数字或单个字符，不需要处理多行、省略号、Span
• 需要文字在背景图形中精确视觉居中（角标、徽章、头像上的数字）

正常的文本展示仍然应该用 TextView。font metrics 的”偏移”在常规尺寸下是正确的排版行为——它保证了多行文本的行间距一致，保证了不同字符（大写、小写、带音调）在同一行内对齐。只有当你把文字塞进一个极小的容器、且只关心单个字符的视觉中心时，font metrics 才会成为问题。

这类 Prompt 缺少审查边界，也缺少证据格式。AI 很容易停在截图观感、单个 margin、单个颜色值或局部控件上，漏掉页面背景、模块共边、列表空态、运行态图片圆角和分割线归属。

更稳定的写法，是把蓝湖验收拆成一组可复用提示词。每段 Prompt 只负责一种证据：规格来源、页面盒模型、横向边界、绝对坐标、模块间距、列表契约、文字槽位、结构元素、运行态和补丁审查。

使用方式

先准备四类输入：

然后按顺序投喂 Prompt。不要一次要求 AI 同时修所有问题。先让 AI 产出台账，再根据台账做窄范围补丁。

Prompt 1：限定规格来源

这段 Prompt 用来防止 AI 用截图观感覆盖结构化规格。

角色：UI 还原审核代理。

任务：基于蓝湖结构化数据审查当前页面实现，不以截图观感覆盖结构化规格。

输入：
- 设计节点：{设计节点名称}
- 页面状态：{主题 / Tab / 空态 / 加载态 / 数据态}
- 设计规格：{HTML/CSS/tokens/layout/layers}
- 当前代码范围：{文件路径或组件入口}
- 平台：{Android View / Flutter / HarmonyOS ArkUI}

规则：
1. 以 HTML、CSS、tokens、layout、layers 作为规格。
2. 截图只用于复核，不用于推翻结构化数据。
3. 每个结论都要写出设计值、当前代码来源、当前渲染结果、差异归属。
4. 不允许只回答「看起来差不多」。

输出：
- 先列出本次审查范围。
- 再列出需要建立的台账。
- 最后说明暂不修改代码，先完成证据表。

适用场景：首次接入设计稿、换 Tab、换主题、设计节点不明确、截图和结构化数据看起来不一致。

Prompt 2：页面盒模型和背景归属

这段 Prompt 用来审查页面根、滚动容器、列表容器和空白区域。

任务：建立页面级盒模型和背景归属表。

必须检查：
1. 页面根容器宽度、高度、背景。
2. 从窗口根到模块根的背景归属：
   Activity/window root
   -> Fragment/page root
   -> Tab/page container
   -> refresh/layout parent
   -> RecyclerView/ListView/ScrollView
   -> item/module root
3. 短内容、空列表、加载态、模块隐藏、底部 padding、overscroll 暴露出的颜色。
4. 滚动容器是否应保持透明，页面底色是否应由父容器承担。

输出表格：
| 层级 | 蓝湖要求 | 当前代码 | 暴露状态 | 差异 | 处理建议 |
|---|---|---|---|---|---|

限制：
- 不允许只检查长列表满屏状态。
- 不允许通过给列表控件直接上背景来掩盖父容器背景问题，除非设计明确要求列表本身拥有底色。

适用场景：页面底色、空白区域、加载态、短列表、底部露色问题。

Prompt 3：横向边界台账

这段 Prompt 用来解决模块左右边界不一致的问题。

任务：建立同列模块的横向边界台账。

检查对象：
- 同一页面内上下相邻的模块、卡片、列表组、Banner、模块组。
- 任何被指出「宽度不一致」「左右边界不一致」「应该共边」的模块。

每行必须记录：
- 蓝湖横向几何：page width、left、width、right、推导出的左右边距。
- 当前代码来源：root width、margin、padding、父容器 padding、列表模型 margin、ItemDecoration。
- 当前几何结果。
- 模块之间是否应该共边。
- 哪一层负责横向边界。

输出表格：
| 模块 | 蓝湖横向几何 | 当前代码来源 | 当前几何 | 边界关系 | owner | 处理 |
|---|---|---|---|---|---|---|

限制：
- 不允许把内部 padding 当成模块外边界，除非设计背景显示同一视觉面跨过该 padding。
- 不允许只说单个模块 margin 正确，必须比较同列模块之间的关系。

适用场景：卡片左右边距、同列模块共边、列表组宽度、模块组和下方模块不一致。

Prompt 4：绝对纵向坐标台账

这段 Prompt 用来处理自定义状态栏、顶部工具栏、重叠模块和负向偏移。

任务：建立页面级绝对纵向坐标台账。

检查对象：
- 顶部状态区、导航区、工具栏、Header、首个内容模块。
- 使用 position:absolute、负向 top、嵌套 top、paddingTop 或重叠视觉层的节点。
- 固定底部操作区和内容区域之间的可见距离。

每个纵向锚点必须记录：
- 蓝湖节点路径：从页面根到目标节点的完整层级。
- 蓝湖 y 计算：祖先 top、子节点 top、paddingTop、负向偏移累加后的页面级 y。
- 当前代码 y 计算：root top、系统 inset、toolbar top、parent padding、constraint、margin、translationY。
- 派生关系：前一个模块 bottom 到后一个模块 top 的距离，允许出现负值。
- owner：状态栏策略、工具栏高度、Header 高度、模块 top margin、父容器 padding、子节点 padding 或固定底部容器。

输出表格：
| 锚点或模块 | 蓝湖 absolute y | 当前代码 absolute y | 派生关系 | owner | 处理 |
|---|---:|---:|---|---|---|

限制：
- 不允许把子节点 padding 或 margin 直接当成页面级 y。
- 不允许只看最近一层 XML margin。
- 如果存在重叠层，必须用 bottom -> top 计算重叠距离。

适用场景：状态栏透明、自定义工具栏、重叠卡片、吸顶 Header、固定底部按钮、负向偏移。

Prompt 5：模块间距台账

这段 Prompt 用来避免把一个蓝湖间距值机械改成某个 XML margin。

任务：建立模块间距台账，计算最终可见距离。

检查对象：
- Tab/Header -> 首个模块。
- 模块 -> 模块。
- 卡片 -> 卡片。
- 列表组 -> 底部导航或页面底部。
- 模块隐藏、加载态、空态后的相邻关系。

每行必须记录：
- 蓝湖 gap：从结构化 layout 推导，不用目测。
- 当前 gap 来源：上一个模块 bottom padding、下一个模块 top margin、列表 padding、item root margin、分割线、ItemDecoration、父容器 padding。
- 可见距离公式，例如：12 child bottom + 12 list padding + 8 module margin = 32dp。
- gap owner：最终应该由哪一层负责。

输出表格：
| 视觉关系 | 蓝湖 gap | 当前来源 | 当前可见距离 | owner | 处理 |
|---|---:|---|---:|---|---|

限制：
- 不允许只检查一个非零 margin。
- 不允许把多个 gap 平均成一个值。
- 不允许在台账仍有未知值时报告「整体间距正确」。

适用场景：模块间距偏大、Header 到首项距离不对、多个 padding 叠加、列表底部留白异常。

Prompt 6：列表完整契约

这段 Prompt 用于列表页，重点是不要只修用户指出的局部症状。

任务：在首次修改同一列表面之前，建立完整列表契约。

必须审查：
1. 顶部区域：Tab 高度、选中态、Header 文字槽位、Header 到首项距离。
2. 列表容器：root padding、首项间距、overscroll、底部 padding、空态背景。
3. 重复项：首项、普通项、末项的高度、宽度、背景、圆角、分割线。
4. Item 内容：标题、摘要、元信息、标签、图片、引用块的字体、行高、字重、槽位。
5. 分割线：左右缩进、高度、颜色、归属层级。

特别规则：
- 设计视觉模块和代码 item 不一定一一对应。
- 若设计把多个区域放在同一个视觉 block 中，而代码拆成多个 item，先重新划分 gap owner。
- 若设计上是两个模块，代码由同一个列表模型连续生成，也要按设计模块审查。

输出表格：
| 检查面 | 蓝湖规格 | 当前代码 | owner | 风险 | 后续补丁范围 |
|---|---|---|---|---|---|

限制：
- 不要求一次提交修完全部问题。
- 允许按视觉维度窄提交，但第一轮必须暴露完整列表契约。

适用场景：RecyclerView、ListView、Flutter ListView、瀑布流、搜索结果、消息列表、资讯列表。

Prompt 7：文字槽位台账

这段 Prompt 用来处理固定高度卡片中的文字垂直位置、行高和截断。

任务：建立固定高度卡片的文字槽位台账。

检查对象：
- 标题、副标题、数值、摘要、元信息、底部名称、标签文字。

每行必须记录：
- 蓝湖文字盒：font-size、line-height、font-weight、x/y、width/height、上下锚点。
- 当前代码：textSize、lineHeight、includeFontPadding、font weight、top/bottom constraint、gravity、maxLines、ellipsize。
- 槽位计算：slot height、line box height、top residual、bottom residual。
- 截断风险：最长运行态文案是否会被兄弟控件挤压。
- 有界行规则：若 Android `TextView` 位于固定高度行内，旁边有 icon、checkbox、switch 或按钮，先检查文本自身 `layout_height`、`lineHeight`、`includeFontPadding`、`android:gravity="center_vertical"`，不要移动相邻图标补偿文本未居中。
- 宽度规则：协议、富文本或正文 `TextView` 不应为了凑总宽度从 `wrap_content` 改成固定宽，除非设计或代码契约明确要求固定文本槽位。

输出表格：
| 文本角色 | 蓝湖文字盒 | 当前代码 | 槽位计算 | 截断风险 | 处理 |
|---|---|---|---|---|---|

限制：
- 不允许只看 layout_marginTop。
- 不允许通过缩小字体解决宽度分配问题，除非设计规格本身要求字体变小。

适用场景：文字上下不居中、固定高度卡片、标签文字偏下、标题提前省略、数值和名称互相挤压、行内图标和文本垂直位置不一致。

Prompt 8：颜色和 Token 映射

这段 Prompt 用来避免只按十六进制颜色做替换。

任务：建立颜色语义角色表，并映射到项目资源。

检查对象：
- 页面背景、卡片背景、模块标题、正文、元信息、禁用态、右侧操作文字、右侧箭头、分割线。

规则：
1. 若蓝湖提供命名 Token，优先按 Token 语义映射资源。
2. 当前十六进制值相同，不代表语义一致。
3. 同一行中的标题、正文、右侧操作文字、箭头、分割线必须分开记录。
4. 检查日夜模式或皮肤资源，不只看当前主题。

输出表格：
| 视图身份 | 语义角色 | 蓝湖 Token 或颜色 | 当前代码资源 | 主题变体 | 处理 |
|---|---|---|---|---|---|

限制：
- 不允许在共享布局里做宽泛颜色替换。
- 修右侧操作颜色时，不得顺带修改标题或正文。

适用场景：颜色接近但语义不对、深色模式异常、右侧文字和箭头颜色不一致。

Prompt 9：结构元素和运行态图片

这段 Prompt 用来检查容易被当成装饰的小元素。

任务：审查结构元素和运行态图片，不只检查静态布局。

必须检查：
1. 标题左图标、右侧操作文字、右侧箭头、清除按钮、徽标、分割线是否存在。
2. 卡片内排名角标、NEW 标识、状态标签、业务标签、覆盖标签是否存在。
3. 服务端图片或图标的 ImageView 尺寸、scaleType、placeholder、圆角变换、裁剪策略。
4. 头像或图片边框的绘制顺序：兄弟节点顺序、foreground、elevation、translationZ、父容器裁剪、自定义容器测量锚点。

输出表格：
| 元素 | 蓝湖是否存在 | 当前代码 | 运行态来源 | 绘制或加载风险 | 处理 |
|---|---|---|---|---|---|

限制：
- 不允许把服务端图片只当成 XML 背景检查。
- 父容器有圆角，不代表图片本体已裁剪。
- 边框宽度正确，不代表绘制顺序正确。

适用场景：旧图标残留、角标缺失、服务端图片圆角无效、头像边框压住图片。

Prompt 10：补丁前目标清单

这段 Prompt 用来控制 AI 修改范围。

任务：在修改代码前，生成补丁目标清单。

每个目标必须包含：
- 文件路径。
- 视图 ID、组件名或绑定名。
- 属性名。
- 当前值。
- 目标值。
- 语义角色。
- 来自哪张台账。

输出表格：
| 文件 | 视图或组件 | 属性 | 当前值 | 目标值 | 语义角色 | 证据来源 |
|---|---|---|---|---|---|---|

限制：
- 不允许先改代码再补证据。
- 不允许跨语义角色做批量替换。
- 不允许把无关重构混入视觉修复。

适用场景：准备让 AI 自动改代码、需要控制补丁范围、同一资源名被多个角色复用。

Prompt 11：补丁后审查

这段 Prompt 用来在构建前先读 diff。

任务：审查本次 diff 是否只修改目标层级。

必须检查：
1. diff 是否只包含补丁目标清单中的文件、视图、属性。
2. 是否误改同一行中的标题、正文、元信息、右侧操作、箭头或分割线。
3. 间距修复是否只调整台账中确认的 owner。
4. 成对元素是否一起处理，例如右侧操作文字和右侧箭头。
5. 是否混入无关重构、格式化或未请求的依赖变更。
6. 如果本轮是在修正上一轮被指出的问题，必须先验证渲染症状；未验证前不要提交，只保留未提交补丁或继续补验证证据。

输出：
- 通过项。
- 风险项。
- 必须回退的误改。
- 可继续运行的验证命令。

适用场景：AI 已经改完代码、准备构建或截图复核之前。

一段完整总 Prompt

实际使用时，也可以把上面的要求合并成一段总 Prompt。适合第一次审查某个页面。

角色：UI 还原审核代理。

目标：基于蓝湖结构化规格审查当前页面实现，先产出台账，再做窄范围修复建议。

输入：
- 设计节点：{设计节点}
- 页面状态：{主题 / Tab / 数据态 / 空态 / 加载态}
- 设计规格：{HTML/CSS/tokens/layout/layers}
- 当前代码范围：{页面入口、布局、组件、列表模型、图片加载代码}
- 平台：{Android View / Flutter / HarmonyOS ArkUI}
- 当前问题：{问题描述}

执行顺序：
1. 确认规格来源，禁止用截图覆盖结构化数据。
2. 建立页面盒模型和背景归属表。
3. 建立同列模块横向边界台账。
4. 若页面存在自定义状态栏、工具栏、重叠层或固定底部区域，建立绝对纵向坐标台账。
5. 建立模块间距台账，计算最终可见距离。
6. 如果目标是列表页，建立完整列表契约。
7. 如果存在固定高度卡片或有界文本行，建立文字槽位台账。
8. 建立颜色语义角色表和 Token 映射。
9. 审查结构元素、运行态图片和图片边框绘制顺序。
10. 生成补丁目标清单。
11. 暂不修改代码，等待补丁目标确认或继续执行指令。

输出格式：
- 审查范围。
- 台账列表。
- 发现的问题，按风险排序。
- 补丁目标清单。
- 需要验证的状态和命令。

收尾检查 Prompt

提交前可以用下面这段做最后一轮检查。

任务：判断本次蓝湖还原修复是否可以收尾。

必须确认：
- 页面级左右边界已经检查。
- 同列模块横向边界台账已经完成。
- 自定义状态栏、工具栏、重叠层或固定底部区域涉及的绝对纵向坐标已经检查。
- 相邻模块间距台账已经完成，且每个可见模块对都有 owner。
- 列表页已经审查完整列表契约。
- 分割线、ItemDecoration、列表模型 spacer 已经检查。
- 固定高度卡片已经检查文字槽位。
- 有界行内 `TextView` 已经先检查自身 line box 和垂直居中策略，没有用移动相邻图标补偿文本问题。
- 标题左图标、右侧操作、箭头、角标、标签、分割线已经检查。
- 运行态图片、圆角、placeholder、边框绘制顺序已经检查。
- 颜色改动按语义角色分开，未做宽泛替换。
- diff 已经审查，没有误改相邻角色。
- 若本轮修正上一轮被指出的问题，渲染症状已经验证；未验证则不提交。

输出：
- 可以收尾 / 不能收尾。
- 不能收尾时列出缺失证据。
- 可以收尾时列出验证命令和截图状态。

总结

蓝湖验收 Prompt 的核心，不是让 AI「看图更细」，而是让 AI 按固定证据格式工作。

好的 Prompt 至少要规定三件事：

• 规格来源：结构化设计数据优先，截图只做复核。
• 审查台账：边界、绝对坐标、间距、列表契约、文字槽位、颜色角色、运行态图片分别成表。
• 修改边界：先生成补丁目标清单，再改代码，改完先审 diff。

只要 Prompt 能持续产出这些证据，AI 就不再只是给出视觉判断，而是在执行一套可复查的 UI 审核流程。

一次 AndroidX 依赖升级后，低版本设备开始在兼容测试中稳定崩溃。崩溃只出现在 Android 11 及以下系统，高版本设备没有异常。

表面入口是 Guava EventBus 的 register()：

com.google.common.util.concurrent.ExecutionError:
  java.lang.NoClassDefFoundError: Failed resolution of: Landroid/app/PictureInPictureUiState;
    at com.google.common.eventbus.EventBus.register(EventBus.java)
    at cn.example.utils.EventBusCenter.register(EventBusCenter.kt:7)
    at cn.example.ui.SomeActivity.onCreate(SomeActivity.kt)

业务代码没有直接使用 PictureInPictureUiState，也没有主动调用画中画相关 API。问题出在三个条件叠加：

• AndroidX Activity 的父类方法签名里出现了 Android 12 才存在的 framework 类型。
• Guava EventBus 注册订阅者时会反射扫描订阅者的完整继承链。
• 业务代码把 Activity 本身注册成了 EventBus subscriber。

结论先放前面：不要把 Activity、Fragment、View 这类 framework 组件对象直接传给 Guava EventBus 做 subscriber。把订阅方法移到一个独立 subscriber 对象里，让 EventBus 扫描的类继承链停在业务小对象上。

现场代码

EventBusCenter 本身只是一个薄封装：

object EventBusCenter {
    val instance = EventBus()

    fun register(obj: Any?) {
        instance.register(obj)
    }

    fun unregister(obj: Any?) {
        instance.unregister(obj)
    }
}

原始写法是把 @Subscribe 方法直接放在 Activity 上，然后注册 this：

class SomeActivity : AppCompatActivity() {

    @Subscribe
    fun onMessageEvent(event: String) {
        // 处理事件
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        EventBusCenter.register(this)
    }

    override fun onDestroy() {
        EventBusCenter.unregister(this)
        super.onDestroy()
    }
}

这段代码看起来没有引用 Android 12 的 API，但它把一个复杂的 framework 组件暴露给了 Guava EventBus 的反射扫描逻辑。

触发条件

1. 缺失类来自 Android 12

android.app.PictureInPictureUiState 是 Android 12（API 31）新增类。低版本系统镜像里没有这个类。

只要运行时尝试解析这个类型，就可能抛出：

java.lang.NoClassDefFoundError: Failed resolution of: Landroid/app/PictureInPictureUiState;

这类错误不要求业务代码显式调用相关方法。方法签名、字段签名、注解、泛型桥接方法、反射枚举方法列表，都可能让运行时去解析一个当前系统不存在的类型。

2. 依赖升级把新方法带进了父类

依赖升级后，AndroidX Activity / ComponentActivity 的类定义里可能包含类似方法：

public void onPictureInPictureUiStateChanged(PictureInPictureUiState pipState) {
}

这段代码在高版本设备上没有问题，因为系统存在 PictureInPictureUiState。

在 Android 11 及以下设备上，单纯安装 APK 通常也不会立刻崩溃。风险来自运行时是否触发该方法签名的解析。只要某段代码反射枚举到这个方法，ART 就可能尝试解析参数类型，然后发现 framework 类不存在。

3. EventBus 注册会扫描父类链

Guava EventBus 不是只看当前类上有没有 @Subscribe。它会通过 SubscriberRegistry 找出订阅者类型及其父类型，然后反射读取方法：

Set<Class<?>> supertypes = TypeToken.of(clazz).getTypes().rawTypes();
for (Class<?> supertype : supertypes) {
    for (Method method : supertype.getDeclaredMethods()) {
        // 查找 @Subscribe 方法
    }
}

当注册对象是 SomeActivity 时，扫描范围不是：

SomeActivity

而是接近：

SomeActivity
  -> AppCompatActivity
  -> FragmentActivity
  -> ComponentActivity
  -> Activity
  -> ...

@Subscribe 只写在 SomeActivity 上，但 EventBus 为了支持继承场景，仍然会遍历父类链。问题就出在 ComponentActivity.getDeclaredMethods()。

崩溃调用路径

完整调用路径可以压缩成下面几步：

SomeActivity.onCreate()
  -> EventBusCenter.register(this)
    -> EventBus.register(SomeActivity)
      -> SubscriberRegistry 扫描 SomeActivity 的所有父类型
        -> ComponentActivity.getDeclaredMethods()
          -> 解析方法签名 PictureInPictureUiState
            -> Android 11 及以下系统不存在该 framework 类
              -> NoClassDefFoundError

这里有一个容易误判的点：崩溃不是因为调用了 onPictureInPictureUiStateChanged()，而是因为反射枚举方法时触发了方法签名解析。

因此，加上版本判断也不一定能解决问题：

if (Build.VERSION.SDK_INT >= 31) {
    // ...
}

如果 EventBus.register(this) 仍然发生在低版本设备上，反射扫描仍然可能先于业务分支执行，崩溃仍然存在。

为什么高版本正常，低版本崩溃

高版本设备存在 android.app.PictureInPictureUiState，所以 ComponentActivity 方法签名可以被解析。

低版本设备不存在这个 framework 类。AndroidX 可以在编译期引用它，是因为应用使用了高版本 compileSdk；但运行期类是否存在，取决于设备系统版本。

这也是 Android 兼容性问题里很常见的一类分裂：

换句话说，compileSdk 能让代码编译通过，但不能把新系统类带到旧设备上。

修复目标

修复不是「避开 PictureInPictureUiState」这么简单。业务代码本来就没有直接引用它。

真正要做的是缩小 EventBus 的反射扫描边界：

不要让 EventBus 扫描 Activity 继承链。

把 subscriber 从 Activity 本身移出去，让注册对象变成一个小而独立的对象：

EventBus.register(Activity)              // 风险：扫描 Activity 父类链
EventBus.register(EventBusSubscriber)    // 安全：只扫描 subscriber 自身及 Object

推荐修复：独立 subscriber 对象

可以把订阅方法提取到一个顶层类、普通 Kotlin 嵌套类，或者 companion object 内的嵌套类中。关键点不是必须放在 companion object，而是这个类不能是 Activity 的子类，也不能把 Activity 放进 EventBus 的扫描继承链里。

示例写法：

class SomeActivity : AppCompatActivity() {

    private val eventBusSubscriber = EventBusSubscriber(
        onMessage = { event ->
            handleEvent(event)
        }
    )

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        EventBusCenter.register(eventBusSubscriber)
    }

    override fun onDestroy() {
        EventBusCenter.unregister(eventBusSubscriber)
        super.onDestroy()
    }

    private fun handleEvent(event: String) {
        // 处理事件
    }

    private class EventBusSubscriber(
        private val onMessage: (String) -> Unit
    ) {
        @Subscribe
        fun onMessageEvent(event: String) {
            onMessage(event)
        }
    }
}

Kotlin 的嵌套类默认不持有外部类引用，只有显式标记为 inner 的类才会持有外部类实例。

因此，下面这个类是可以作为独立 subscriber 的：

private class EventBusSubscriber(...)

下面这个则不建议作为默认方案：

private inner class EventBusSubscriber(...)

inner 会引入外部 Activity 引用。虽然 EventBus 主要扫描的是 subscriber 的继承链，不是字段类型，但这种写法会增加生命周期引用风险，也让问题边界变得不清晰。

匿名对象是否可以

如果只是为了切断 EventBus 对 Activity 父类链的扫描，注册一个匿名对象通常也能做到：

private val eventBusSubscriber = object {
    @Subscribe
    fun onMessageEvent(event: String) {
        handleEvent(event)
    }
}

此时 EventBus 扫描的是匿名对象的类，而不是 SomeActivity。

但匿名对象会自然捕获外部 Activity 的方法或字段，代码审查时也不如命名类清楚。对于生命周期长、事件来源复杂、容易遗漏 unregister() 的项目，命名的独立 subscriber 更容易维护。

所以这里推荐的规则是：

• 只看崩溃规避：不要注册 Activity 本身。
• 看长期维护：优先使用命名的独立 subscriber。
• 如果 subscriber 会持有 Activity 行为，必须保证和 Activity 生命周期成对注册与注销。

修复前后对比

为什么不建议直接注册 framework 组件

这次问题由 PictureInPictureUiState 引发，但根因不是这个类本身。

Activity、Fragment、View 这类对象的继承链很长，父类来自 Android framework 和 AndroidX。它们的方法签名会随着依赖升级、compileSdk 提升、AndroidX 实现变化而变化。

把它们直接交给反射框架，相当于把整个父类链暴露给框架扫描。只要父类链上出现一个低版本设备无法解析的类型，就可能在业务代码之外崩溃。

高风险写法包括：

EventBusCenter.register(this)        // this 是 Activity
EventBusCenter.register(fragment)    // fragment 是 Fragment

更稳的写法是：

EventBusCenter.register(subscriber)

其中 subscriber 是专门为事件订阅准备的小对象，只暴露必要的 @Subscribe 方法。

类似风险场景

只要框架会反射枚举类方法，就可能遇到类似问题：

• Guava EventBus 的 EventBus.register()
• Otto EventBus 的 Bus.register()
• 自定义注解扫描逻辑里的 getDeclaredMethods() / getMethods()
• 运行期路由、插件、埋点框架中对宿主类的反射扫描

排查时可以按下面顺序收敛：

1. 找到 NoClassDefFoundError 里真正缺失的类。
2. 确认该类从哪个 API 级别开始存在。
3. 查找崩溃栈里第一个反射入口。
4. 看传入反射框架的对象是否是 Activity、Fragment、View 或其他复杂 framework 类型。
5. 把反射扫描对象替换成独立小对象，再在低版本设备上验证。

总结

这个崩溃的本质不是「画中画 API 不能在低版本用」，而是「反射框架扫描了不该扫描的类继承链」。

PictureInPictureUiState 只是第一个暴露问题的缺失类型。真正脆弱的写法是把 Activity 本身注册到 Guava EventBus，让 EventBus 在低版本设备上扫描 ComponentActivity 的方法列表。

修复原则很简单：

• EventBus subscriber 应该是小对象，不应该是 Activity 本身。
• 低版本兼容问题不能只看业务代码是否显式调用新 API，还要看反射、注解扫描、方法枚举是否会解析新 API 类型。
• AndroidX 升级后，如果出现旧系统才有的 NoClassDefFoundError，需要重点检查父类方法签名和反射扫描入口。

这一类问题的排查重点不在「哪里调用了缺失类」，而在「谁触发了缺失类的解析」。

某个 Android 模块在少量场景下出现崩溃，日志核心信息如下：

java.lang.IllegalArgumentException

Wrong state class, expecting View State but received class androidx.appcompat.widget.Toolbar$SavedState instead.
This usually happens when two views of different type have the same id in the same hierarchy.
This view's id is id/toolbar.

崩溃并不发生在页面首次打开时，而是集中出现在以下时机：

• 页面重建
• 配置变更后恢复界面状态
• 进程被系统回收后重新进入页面

这类问题的特点是：普通功能验证往往正常，但一旦触发状态恢复，系统会在 onRestoreInstanceState 阶段直接抛异常。

现象

从异常文本可以直接得到两个关键信息：

1. 系统正在恢复一个 id=toolbar 的视图状态。
2. 当前接收方期望的是普通 View 的状态对象，但实际收到的是 Toolbar$SavedState。

这意味着同一个 ID 对应到了两种不同类型的视图。更具体一点说，状态是在一个 Toolbar 上保存的，却被恢复到了一个非 Toolbar 的视图上。

这类崩溃常见于布局复用场景，尤其是 include、merge、Data Binding 和多层容器叠加后的最终视图树。

根因分析

问题布局可以抽象成下面这种形式。

页面布局：

<androidx.constraintlayout.widget.ConstraintLayout
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <include
        android:id="@+id/toolbar"
        layout="@layout/include_toolbar" />

</androidx.constraintlayout.widget.ConstraintLayout>

被复用的 toolbar 布局：

<layout>
    <androidx.constraintlayout.widget.ConstraintLayout
        android:layout_width="match_parent"
        android:layout_height="wrap_content">

        <androidx.appcompat.widget.Toolbar
            android:id="@+id/toolbar"
            android:layout_width="match_parent"
            android:layout_height="wrap_content" />

    </androidx.constraintlayout.widget.ConstraintLayout>
</layout>

这里的问题不在于 include 本身，而在于 外层 include 节点和内层真正的 Toolbar 使用了同一个 ID。

最终运行时，视图树里会同时出现两个概念上都叫 toolbar 的节点：

• 一个是 include 落地后的外层容器，例如 ConstraintLayout
• 一个是容器内部真正可保存 Toolbar$SavedState 的 Toolbar

当系统保存状态时，Toolbar 会以 id=toolbar 存入自己的 SavedState。等到恢复状态时，系统按照 ID 回填，结果外层容器也占用了同一个 ID。这时恢复逻辑命中了错误的目标视图：

• 保存阶段：状态来自 Toolbar
• 恢复阶段：状态被分发给 ConstraintLayout

于是系统发现：

• 目标视图只接受普通 View.BaseSavedState
• 实际收到的是 Toolbar$SavedState

最终抛出 IllegalArgumentException。

为什么不是所有页面都会崩溃

这个问题虽然是布局层面的，但并不是所有使用了公共 toolbar 的页面都会稳定触发，原因通常有三个：

1. 只有触发状态恢复时才会暴露

如果页面只经历「打开 -> 使用 -> 退出」，可能完全看不到问题。只有系统真正走到视图状态保存与恢复流程时，冲突才会变成异常。

2. 只有重复 ID 对应的视图类型不同才会出错

如果两个同名节点碰巧都是普通容器，未必会立刻崩。真正危险的是像这次这样，一个是 Toolbar，另一个是普通 ViewGroup。

3. 复用布局会放大影响范围

一旦问题存在于公共 toolbar 布局中，所有通过 include 复用它、并且外层继续命名为 toolbar 的页面，都可能在相同条件下中招。

修复方案

最小修复方式很简单：保证外层 include 节点与内层真正的 Toolbar 不使用同一个 ID。

例如，将内层 Toolbar 的 ID 改成 toolbar_view：

<layout>
    <androidx.constraintlayout.widget.ConstraintLayout
        android:layout_width="match_parent"
        android:layout_height="wrap_content">

        <androidx.appcompat.widget.Toolbar
            android:id="@+id/toolbar_view"
            android:layout_width="match_parent"
            android:layout_height="wrap_content" />

    </androidx.constraintlayout.widget.ConstraintLayout>
</layout>

对应代码侧也改为引用新的字段：

setSupportActionBar(binding.toolbar.toolbarView)

这样处理有两个好处：

• 页面层不需要重做整体布局结构
• 公共布局只改一处，受影响页面统一切换引用即可

如果页面本身并不需要对 include 节点使用 android:id="@+id/toolbar"，另一种做法是直接移除外层这个 ID。本质都是同一个原则：一个状态型控件在最终视图树中只能占用一个确定的 ID。

排查这类问题的有效方法

如果后续再遇到类似的 Wrong state class 崩溃，排查顺序可以直接固定为下面几步：

1. 先读异常文案

异常里通常已经给出了最关键的信息：

• 期望的状态类型
• 实际收到的状态类型
• 对应视图的 ID

这一步往往比先看业务代码更快。

2. 全局搜索对应 ID

例如直接搜索：

rg -n '@\+id/toolbar|@id/toolbar' .

重点看以下几类位置：

• include
• 公共布局
• Data Binding 布局根节点
• 自定义 View 容器

3. 看最终层级，而不是只看单个 XML

单独看某一个布局文件，可能只看到一个 toolbar。但一旦 include 展开、Data Binding 包裹、容器合并后，最终视图树里可能已经出现两个同名节点。

4. 优先修公共布局

如果重复 ID 来自公共组件，优先在公共层修正，再统一替换调用侧引用。这样比逐页修改更稳。

总结

这次问题可以压缩成一句话：

状态恢复阶段的崩溃，很多时候不是业务逻辑问题，而是最终视图树中存在重复 ID，并且重复节点的视图类型不同。

对于 Toolbar、RecyclerView、FragmentContainerView 这类自带状态恢复逻辑的控件，这个问题尤其容易放大。

一条简单但很有效的约束是：

• 公共布局内部的状态型控件，ID 要保持唯一
• 外层 include 如果只是为了拿 binding root，不要继续复用同名 ID
• 只要异常里出现 Wrong state class，优先检查最终视图树中的重复 ID

这类问题的修复代码通常不多，但前提是先把「状态是谁保存的，恢复时又落到了谁身上」这件事看清楚。

我们维护了一套面向第三方提供的 Android SDK。在一次构建链升级中，工程的 Android Gradle Plugin（AGP）升级到了 7.1.3，协议运行库同步升级至 Protobuf 4.x Lite Runtime。

SDK 交付给第三方合作方后，对方反馈：在 Android 10 及以下设备上会产生稳定崩溃，而在 Android 11 及以上设备上运行正常。 本地编译通过，高版本设备无异常，问题只在第三方真实接入的低版本设备上复现。

现象

崩溃日志如下：

java.lang.NullPointerException: Attempt to invoke virtual method 'void com.google.protobuf.ProtobufArrayList.ensureIsMutable()' on a null object reference
    at com.google.protobuf.ProtobufArrayList.add(ProtobufArrayList.java:80)
    at com.google.protobuf.MessageSchema.reflectField(MessageSchema.java:599)
    at com.google.protobuf.MessageSchema.newSchemaForRawMessageInfo(MessageSchema.java:506)
    at com.google.protobuf.MessageSchema.newSchema(MessageSchema.java:225)
    at com.google.protobuf.ManifestSchemaFactory.createSchema(ManifestSchemaFactory.java:48)
    at com.google.protobuf.Protobuf.schemaFor(Protobuf.java:54)
    at com.google.protobuf.GeneratedMessageLite.makeImmutable(GeneratedMessageLite.java:209)
    at com.google.protobuf.GeneratedMessageLite$Builder.build(GeneratedMessageLite.java:488)

触发路径是普通的消息构建：

SomeMessage.newBuilder()
    .addItems(...)
    .build();

崩溃并不发生在业务赋值阶段，而是发生在 build() 调用触发的 makeImmutable() 内部 —— 即 Protobuf Lite Runtime 根据消息类的内部元数据重建 Schema、冻结 repeated/list 字段的阶段。

原因分析

1. Protobuf 4.x 的元数据编码方式

Protobuf Lite 为了压缩包体，不保留完整的 Java 反射描述，而是将消息的结构信息（字段类型、字段偏移量等）高度压缩，编码为一个 String 常量写入生成类中：

return newMessageInfo(DEFAULT_INSTANCE, info, objects);

info 字符串并非普通文本，而是包含了大量二进制位，其中充斥着非标准的 UTF-16 字节流、不可见控制符以及残缺的代理对（Surrogate pairs）。运行时依赖解析这段字符串来重建消息的内部 Schema。

2. 旧版 D8 的字符串转码缺陷

本工程使用的 AGP 7.1.3 内置的旧版 D8 编译器，在执行 .class → .dex 转换过程中，对字符串常量存在一套转码优化流程。当遭遇 Protobuf 这段包含非标准 UTF-16 字节流的特殊字符串时，D8 会误触编码规则，将其中部分字节截断或转义（String Corruption）。

这一步发生在编译期，产物外观上一切正常，但 Dex 文件中实际携带的元数据字符串已经被破坏，偏移量信息出现偏差。

3. Unsafe 快路径放大了问题

Protobuf 4.x Lite Runtime 大量使用 sun.misc.Unsafe 进行字段读写，典型模式如下：

Object value = UnsafeUtil.getObject(message, fieldOffset);

运行时先根据 Schema 中的元数据算出字段在对象内存中的偏移量 fieldOffset，再通过 Unsafe 直接按偏移量读取内容，跳过了 Field.get() 的类型检查开销。

这种方式性能极高，但对元数据的正确性有绝对依赖。一旦偏移量因第 2 步中 D8 的转码缺陷而出现偏差，Unsafe 会按错误地址读取内存，得到 null 或无效对象，最终在 ProtobufArrayList.ensureIsMutable() 处抛出 NPE。

4. 为什么只在 Android 10 及以下复现

同一份损坏的 Dex 文件被安装到不同系统版本的设备上，行为却截然不同，原因在于 Protobuf 内部 UnsafeUtil 的初始化策略与 Android Hidden API 限制的交互：

Android 11 及以上： 系统对 Hidden API 的管控趋于严格，UnsafeUtil 在通过反射尝试获取 sun.misc.Unsafe 实例时会被拦截并抛出异常。Protobuf 捕获异常后触发内部的安全降级（Fallback）机制，将 Unsafe 快路径标志置为不可用，转而使用基于字段名称的标准反射路径（Field.get）。标准反射不依赖偏移量，因此规避了损坏元数据带来的问题。

Android 10 及以下： 系统对私有 API 尚未完全封禁，UnsafeUtil 顺利获取到了 Unsafe 实例并启用快路径。随后运行时按照被 D8 损坏的偏移量读取内存，触发崩溃。

这也解释了为什么高版本系统正常、低版本系统崩溃：高版本系统是因为被系统限制而”被动”走了安全路径，并非 Protobuf 4.x 在高版本上没有这个 bug。

验证

为确认问题根源在构建链而非业务代码，我们做了一个对照实验：不改任何业务代码、协议定义和调用方式，仅在 AGP 7.1.3 工程中覆盖升级 R8 版本。

结果：Android 10 上的崩溃消失，Android 11+ 继续正常。

修复方案

对于暂时不能整体升级 AGP 大版本的工程，可以在维持 AGP 7.1.3 不变的前提下，单独覆盖其内置的 R8/D8 内核版本。

在根目录 build.gradle 中添加：

buildscript {
    repositories {
        mavenCentral()
        google()
    }
    dependencies {
        classpath "com.android.tools.build:gradle:7.1.3"

        // 覆盖旧版 AGP 内置的 R8 / D8，3.3.75+ 已修复该字符串转码问题
        classpath "com.android.tools:r8:3.3.75"
    }
}

添加后重新编译，Protobuf 元数据字符串将被正确保留，Android 10 及以下设备的崩溃问题消除。

总结

这个问题的特殊之处在于：代码本身没有逻辑错误，也能正常编译，错误发生在构建链处理产物的阶段，且只在特定系统版本下暴露。 对于 SDK 对外发布场景，构建工具链的版本兼容性同样属于需要纳入质量保障的环节。

本文基于 智能分包开发文档 V3.0，记录在 Android 项目中接入 vivo 智能分包的完整流程。

什么是智能分包

vivo 应用商店的「智能分包」功能，本质上是 Install Referrer 机制——当用户通过 vivo 广告投放渠道下载安装应用后，应用可以读取到这次安装对应的广告归因参数（渠道号、广告任务 ID、创意 ID 等），用于广告效果归因和 oCPX 回传。

核心特性： 智能分包参数在安装后不会变化，读取一次缓存即可。

接入方案选择

vivo 提供了两种读取方式：

ContentProvider 方案代码更简洁，无需管理 ServiceConnection 生命周期，本文采用此方案。

数据流转全景

vivo 应用商店
    │
    ▼ ContentProvider.call("read_channel")
    │
channelValue = {"code": 0, "value": "{...}"}
    │
    ▼ code == 0 → 取 "value" 字段
    │
value = {
    "referrer_click_timestamp_seconds": "1658541060088",
    "install_referrer": "task_id%3Dxxx%26channel_id%3Dxxx%26...",
    "package_name": "com.example.app",
    "vivo_ext_referrer": "BdAwWkj..."
}
    │
    ▼ 直接回传完整 JSON 给服务端（无需额外处理）

核心实现（Kotlin）

object VivoChannelDetector {

    private const val PROVIDER_URI = "content://com.bbk.appstore.provider.appstatus"

    /**
     * 读取 vivo 智能分包参数
     * @return 智能分包 value JSON 字符串，失败返回 null
     */
    fun readChannel(context: Context, packageName: String): String? {
        // 优先从本地缓存读取（智能分包安装后不会变化）
        val cached = readFromCache(context)
        if (!cached.isNullOrEmpty()) return cached

        try {
            val inputBundle = Bundle().apply {
                putString("package_name", packageName)
            }
            val bundle = context.contentResolver.call(
                Uri.parse(PROVIDER_URI),
                "read_channel",
                null,
                inputBundle
            )
            if (bundle != null) {
                val channelValue = bundle.getString("channelValue")
                if (!channelValue.isNullOrEmpty()) {
                    val json = JSONObject(channelValue)
                    val code = json.optInt("code")
                    if (code == 0) {
                        val value = json.optString("value")
                        // 读取成功，存入本地缓存
                        saveToCache(context, value)
                        return value
                    } else {
                        Log.w(TAG, "code=$code, message=${json.optString("message")}")
                    }
                }
            }
        } catch (e: Exception) {
            Log.e(TAG, "readChannel failed", e)
        }
        return null
    }
}

调用示例

获取到的 value 是完整的智能分包参数 JSON，可以直接回传给服务端，不需要额外处理：

val value = VivoChannelDetector.readChannel(context, context.packageName)
if (value != null) {
    // 直接回传完整 JSON 给服务端
    api.uploadReferrer(value)
}

如果客户端需要提取特定字段（如渠道号），可以进一步解析 install_referrer——它是 URL 编码的 query string：

val json = JSONObject(value)
val referrer = URLDecoder.decode(json.optString("install_referrer"), "UTF-8")
// 解码后: task_id=xxx&channel_id=appstore_001&request_id=xxx&ad_id=xxx&ext_info=xxx

val params = referrer.split("&")
    .mapNotNull { it.split("=", limit = 2).takeIf { kv -> kv.size == 2 } }
    .associate { it[0] to it[1] }

val channelId = params["channel_id"]  // 渠道号
val taskId = params["task_id"]        // 任务 ID
val extInfo = params["ext_info"]      // oCPX 回传参数

返回字段说明

readChannel 返回的 value 是一个 JSON 字符串，包含以下字段：

install_referrer URL 解码后包含以下子字段：

参考资料

• vivo 营销平台 - 帮助中心
• 智能分包开发文档 V3.0（PDF）

在处理数万行的项目上下文时，如何防止 AI “迷路”？如何在并发分析多个模块时，保持逻辑的强一致性？Claude Code 的答案并非仅仅依靠强大的模型，而是一套严密、物理隔离的多智能体（Multi-Agent）协同架构。它在上下文边界、结果回流和副作用隔离上做得极其彻底，确保了协同工作从“表面并行”升级为“工程级可扩展”。

1. 物理隔离：零初始上下文与任务动态路由

graph TD
    A[主控节点 Coordinator] --> B{任务分型决策}
    B -- 封闭式任务/高安全性 --> C[Fresh Agent 零上下文]
    B -- 开放式任务/高性能要求 --> D[Fork Subagent 侧链继承]
    C --> E[执行独立闭环]
    D -- 命中 --> F[Prompt Cache 缓存指针]
    F --> G[执行快速冷启动]
    E --> H[XML 通知回传]
    G --> H
    H --> I[主控语义综合]

在 Claude Code 中，隔离不是一种建议，而是一种动态分析策略。系统会根据任务的确定性（Determinism）自动选择起步路径。

封闭式任务：强制 Fresh Agent

对于目标极度明确的执行或验证任务（如校验一段生成的代码），系统强制使用“零上下文”的全新代理。

// 路径决策：丢弃历史，换取纯粹视角
const contextMessages: Message[] = [] // 物理截断：上下文强制为空
const initialMessages: Message[] = [...contextMessages, ...promptMessages]

架构洞察：这种“Fresh Agent”模式虽牺牲了缓存，但阻断了主会话噪音的遗传。模型只需专注于当前的自包含指令，从而消除了“Lost in the Middle”效应，换取了执行视角的纯粹性。

2. 分支补偿：Fork 机制下的缓存经济学

虽然“隔离”保证了稳定性，但其代价是破坏了 LLM 底层的 Prompt Cache（提示词缓存），导致极高的冷启动延迟。Fork 机制正是为了对冲这一架构冲突而生的性能补丁。

UUID 侧链与缓存指针穿透

Fork 操作本质上是对对话状态（基于追加写入日志 JSONL）的侧链（Side-chain）化。

• 共享前缀：子代理继承父节点的 UUID 前缀，发起请求时能精确命中已有的 Prompt Cache 指针。
• 物理隔离：子代理产生的工具调用、思考过程会被写入独立的侧链文件，物理上与主对话隔离，主上下文不会被子节点的执行噪音污染。

// Fork 机制的核心：在保持字节级对齐的同时，由于 UUID 共享，实现了缓存指针穿透
export function buildForkedMessages(assistantMessage: AssistantMessage): MessageType[] {
  const toolResultBlocks = assistantMessage.message.content.map(block => ({
    type: 'tool_result',
    tool_use_id: block.id,
    content: [{ type: 'text', text: FORK_PLACEHOLDER_RESULT }], // 固定长度占位
  }))
  // 保持消息序列同构且字节级对齐，换取冷启动成本的指数级压降
}

3. 动态路由：隔离与成本的权衡矩阵

系统并不盲目使用隔离，而是根据任务性质实施动态路由策略：

4. 副作用闸门：解析器、通知封装与“防偷窥”契约

多智能体系统真正困难的地方在于：如何带回结论，却不带回执行副作用。

• 透明的 Query Loop：Fork 出来的子代理拥有独立的异步查询循环（Query Loop）和预算池，其运行或崩溃不会引发全局熔断。
• “Don’t peek” (防偷窥) 契约：除了物理隔离，系统施加了硬性纪律——主控节点被严禁在子代理运行中途去读取其日志文件。这种“契约式隔离”确保了主控仅获取最终的结构化输出。
• XML 分流网关：回流必须经过结构化的 XML 封装，主控作为唯一的语义总线，过滤子代理的工具链噪音。

// 结果回传：XML 结构化通知解析
if (command.mode === 'task-notification') {
  /* ...通过 XML 标签提取 taskId 和 Summary，实现定向分流... */
  // 共享队列通过 agentId 门禁过滤，防止子任务通知泄漏进主控上下文
}

5. 结语：工业级源码阅读系统的三个约束面

通过复盘 Claude Code 的工程实践，我们可以提炼出 Agent 系统架构演进的三个核心约束面：

1. 上下文向心性：上下文靠零初始隔离与动态路由策略。任务性质决定隔离强度。
2. 状态原子性：结果回传靠通知封装与“防偷窥”契约。主控作为唯一的语义总线，负责熵减。
3. 副作用独立性：副作用管理靠物理侧链隔离与独立执行循环。

这正是 Claude Code 最具价值的地方：它不追求单一教条，而是在隔离强度、执行成本和语义纯度之间做出了架构级的取舍。这才是真正的“架构之美”。

通过重构，原本依赖 Python 虚拟环境（venv）及其底层 C 扩展库的守护脚本，被精简为一个 8MB 大小的静态链接单体二进制可执行文件。

本文将复盘此次迁移过程的核心技术点：系统零依赖架构的设计、Go 编译机制及其跨平台特性，以及基于 GitHub Workflows 的自动化分发部署。

1. 架构重构：零依赖设计

许多 AI 相关的服务端工具通常选择 Python 作为主要开发语言。即使计算任务已解耦至云端（如免除本地部署 PyTorch 的需求），在使用 Python 开发终端分发或系统守护进程时，仍面临以下基础设施层面的挑战：

• 运行时环境依赖：业务运行的目标主机环境必须预装特定版本的 Python 解释器。
• 依赖冲突与编译异常：每次部署都需要构建并安装依赖包，部分涉及系统底层级的 C 语言扩展（如向量数据库 SDK 常附带的 gRPC 核心层）极易因宿主机环境差异引发编译或运行报错。

迁移至 Go 语言时，在架构层面采用了严格的零第三方依赖（Zero-Dependency）方案：

• 避免引入外部 SDK 依赖：放弃使用封装了复杂底层绑定的高级客户端库（如 pymilvus），转而通过 Go 标准库提供的 net/http 原生实现，构建对云端向量数据库（如 Zilliz Cloud）的 RESTful API 请求协议。
• 解析器功能自实现：为贯彻零外部库调用的设计，我们在项目底层基于文件读写标准库自研实现了类似于 python-dotenv 的环境变量配置解析逻辑。

2. 编译机制：Go 的跨平台编译

Go 的跨平台编译特性在于其编译产物为特定平台的机器码，而非依赖虚拟机的字节码。开发者可以在本机直接进行交叉编译，无需搭建复杂的 C/C++ 交叉工具链。

只需配置以下两个环境变量即可：GOOS (目标系统) 和 GOARCH (目标架构)。

例如，在 MacOS (ARM64) 主机上进行跨平台编译：

GOOS=linux GOARCH=amd64 go build    # 编译 Linux x86 版本
GOOS=windows GOARCH=amd64 go build  # 编译 Windows x86 版本
GOOS=darwin GOARCH=arm64 go build   # 编译 MacOS ARM 版本

减少系统依赖：CGO_ENABLED=0

部分 Go 库默认会依赖宿主机的 C 动态链接库（如 libc），这可能导致跨平台部署时出现动态库缺失的错误。

在编译发布产物时，可以强制设置环境变量 CGO_ENABLED=0。 该参数将全面禁用 CGO，使得编译器将系统调用、网络解析等功能硬编码静态链接到二进制文件中。生成的静态二进制文件可以直接在无附加依赖的 scratch 基础 Docker 镜像中独立运行，显著增强了二次分发的兼容性。

3. GitHub Workflows：自动化构建与分发

结合 GitHub Actions 的 Matrix 策略，可以实现多平台产物的自动化编译与打包发布。以下是 Workflow 配置中的定义片段：

strategy:
  matrix:
    include:
      - goos: linux
        goarch: amd64
        suffix: linux-amd64
      - goos: darwin
        goarch: arm64
        suffix: darwin-arm64
      - goos: windows
        goarch: amd64
        suffix: windows-amd64
        ext: .exe

配置特定 Tag 的触发条件：

on:
  push:
    tags:
      - 'v*'

在开发测试完成，并在本地执行类似于 git tag v1.0.0 && git push --tags 的操作后，GitHub Actions 会根据 Matrix 策略并发启动系统的虚拟机，分别执行各个目标组合的构建任务。这包括编译 Linux、MacOS 和 Windows 版本的产物，计算文件的 SHA256 校验值，最后自动将所有产物上传发布至项目的 Release 页面。

整个流水线无需维护额外的构建服务器，即可完成跨平台软件产物的自动化构建与极简分发。

解法是向量数据库：不再全量注入，而是根据当前对话内容做语义检索，只取 Top-K 条相关记忆。

方案选型

Embedding 模型：BAAI/bge-m3

选它的原因：

• 单模型同时输出 Dense（语义）+ Sparse（词频权重）两种向量，天然支持混合搜索
• 中文支持好，个人记忆场景多为中文
• 本地运行，无 API 费用，离线可用

向量数据库：Zilliz Cloud（托管 Milvus）

• 免费层够个人使用（1 Cluster，1GB 存储）
• 原生支持 BGE-M3 的 Dense + Sparse 混合搜索（hybrid_search + RRFRanker）
• 零运维

原理

记忆写入：文本 → BGE-M3 → dense+sparse 向量 → Zilliz
记忆读取：用户输入 → BGE-M3 → 混合检索 → Top-K 相关记忆 → 注入 Prompt

混合搜索（Hybrid Search）= Dense ANN 语义召回 + Sparse BM25 关键词召回，两路结果经 RRF（Reciprocal Rank Fusion） 融合排序。核心优势：语义相近但用词不同的记忆，和精确包含关键词的记忆，都能被召回。

实现

项目地址：openclaw-vector-memory

结构也很简单：

.
├── requirements.txt
├── .env.example
├── main.py              # CLI 入口
└── memory/
    ├── embedder.py      # Embedding 后端（local / remote）
    ├── store.py         # Zilliz Cloud 读写核心
    └── migrate.py       # 从 MEMORY.md 迁移

一键集成到 OpenClaw

本项目提供了一键安装脚本，能直接把代码、依赖和配置自动注入到你的 OpenClaw 项目中：

# 假设你的 OpenClaw 项目路径是 ~/workspace/openclaw
./install.sh ~/workspace/openclaw

执行后，脚本会自动在目标项目的 AGENTS.md 中追加下面这段系统提示词，引导主 Agent 自动使用：

# 🧠 长期向量记忆库 (自动注入)
**核心指令**：不要直接读取或写入传统的 `MEMORY.md` 文件。对于用户的偏好、长期记忆、以及背景上下文，请使用以下向量搜索工具：
1. **检索记忆**：当你需要回忆关于用户的信息时，使用终端执行：
   `python3 vector_memory.py --search "你要检索的关键语义"`
2. **保存记忆**：当用户告知你全新的偏好或长期有效的事实，使用终端执行：
   `python3 vector_memory.py --save "清晰且完整的记忆内容"`

未来你的 Agent 将会自动通过执行 CLI 命令来调取或保存精准记忆，而不再是死板地把全篇记忆塞进上下文窗口！

CLI 用法

除了集成到代码，项目也提供了方便的命令行工具。首先安装依赖：

pip3 install -r requirements.txt
cp .env.example .env

然后可以执行：

# 写入一条记忆
python3 main.py --save "用户喜欢用 Python，讨厌 Java"

# 语义搜索
python3 main.py --search "这个用户有什么编程习惯"

# 从 MEMORY.md 迁移已有记忆
python3 main.py --migrate /path/to/MEMORY.md

# 查看记忆总条数
python3 main.py --count

--migrate 会按段落分块（\n\n 切割）已有记忆，批量写入向量库。

没有本地 GPU 怎么办

embedder.py 支持多种后端，通过 .env 灵活切换。

用本地模型（体验最佳，默认使用 BGE-M3）：

EMBEDDING_PROVIDER=local

首次运行会自动下载模型（约 2GB），之后离线可用，原生支持 Dense + Sparse 双路召回。

用远程 API（无需本地算力）：

可以配置使用市面上任意提供 Embedding 接口的服务（硅基流动、OpenAI，甚至你的本地 Ollama 服务）：

# 远程 Embedding API（以硅基流动为例）
EMBEDDING_PROVIDER=remote
EMBEDDING_API_BASE=https://api.siliconflow.cn/v1
EMBEDDING_API_KEY=sk-xxx
EMBEDDING_MODEL=BAAI/bge-m3
EMBEDDING_DIM=1024

常见服务配置对照：

需要注意的是，通常远程 API 只返回 Dense 向量，此时 store.py 会检测到空 Sparse 自动降级为纯语义搜索，无需手动修改代码。对个人记忆场景影响不大。

效果

从”全量 MEMORY.md 塞 Prompt”改为”语义 Top-5 检索”之后：

• Token 消耗大幅下降（记忆越多效果越明显）
• 相关性更高——不相关的历史记忆不再干扰当前对话
• 可以无限堆积记忆，不用担心 Context 溢出

代价：首次运行需要下载 BGE-M3 模型（约 2GB），以及一个 Zilliz Cloud 账号。