项目：react-ui ｜ 版本：v1.2 ｜ 生成日期：2026-10-06 ｜ 依据：源码分析
本篇是文档集的最后一篇，承担三件收束工作：先把散落在 00-19 各篇里的项目专有术语集中定义（每个术语给出处，展开细节以「见《0X-xxx》」引用）；再给一张「源码文件 ↔ 篇目」的反向索引——拿着任何一个文件路径都能查到哪一篇讲过它；最后按四类高频任务给出阅读路径，让「该读哪几篇的哪几节」变成一条直线。术语按主题分组排列；英文术语保留原文，中文释义以本仓库的实际语义为准（同一术语在社区里可能有别的含义，本表以源码用法为唯一标准）。
这一组的术语回答「仓库为什么是这个形状」：三层包架构与发布顺序是全局骨架，workspace 协议与 peer 下限是骨架上的两处精密咬合，preserveModules、外部化与 ESM banner 是构建产物侧的三项补偿性设计，纯 CSR 则是一条对外承诺的边界。它们共同的特点是「在源码里各有一个明确的落点」——读到相关文件时回头查这组术语，比单独记忆定义更有效。
| 术语 | 释义 | 首要出处 |
|---|---|---|
| 三层包架构 | hooks（零依赖原语）→ ui（组件 + core 内核）→ pro（页面模式）的发布包分层，依赖严格单向 | 《01-系统架构》第 2 节；《16-决策记录》ADR-001 |
| 发布顺序 hooks → ui → pro | 被依赖者先发的固定发布序列，否则 peer 短暂指向注册表不存在的版本 | 《06-部署运行》第 4 节；根 README |
| workspace 协议 | workspace:*/workspace:^ 的 pnpm 本地引用协议，仅 pnpm publish 会重写为真实版本区间 | 《06-部署运行》第 4.4 节；《17-依赖全景》第 5 节 |
| peer 下限 | peerDependencies 的最低版本必须对齐产物真实消费的导出（attachMediaListener 案例：ui 锁 hooks ^1.4.0） | 《03-接口设计》第 7 节；《16-决策记录》ADR-011 |
| preserveModules | 构建时不合并模块边界的产物策略，保住下游摇树（单文件曾致 import Button 12KB→327KB gzip） | 《10-性能设计与优化》第 1 节；《16-决策记录》ADR-004 |
| 外部化 | 运行时依赖与 peer 不打进产物，防止双实例（dayjs/locale、@emotion/cache 插入点是全局状态） | 《01-系统架构》第 2.3 节 |
| ESM banner | 用 output.banner 给 ESM 产物补回被 rollup 丢弃的 'use client' 指令序言；CJS 不加（保护 'use strict'） | 《16-决策记录》ADR-009；根 README「发布相关的坑」 |
| 纯 CSR 定位 | 不支持服务端渲染的显式承诺（ADMIN-ROADMAP 决策 4），实现可自由使用浏览器 API | 《16-决策记录》ADR-010 |
这一组术语围绕 core/factory/ 与组件的「出生流程」展开，是全库术语里概念密度最高的一组：工厂、载荷、静态件、多态四个词互相定义，单独抽出一个都会失真。阅读顺序建议按表格排列走——先理解「组件从工厂出生」，再理解「静态件是组件的另一半公共面」，最后理解 compound 与 renderRoot 这两个「例外形态」。
| 术语 | 释义 | 首要出处 |
|---|---|---|
| 多态组件（Polymorphic Component） | 经 component prop 动态切换渲染元素/组件并继承其原生属性的组件（类型层见 create-polymorphic-component.ts） | 《01-系统架构》第 3.2 节；《03-接口设计》第 2 节 |
| 工厂（Factory / polymorphicFactory） | 组件的统一出生流程：forwardRef 包装 + 静态件挂载；polymorphic 版支持多态与 withProps 双泛型 | 《18-代码走读实录》第 1 节；《07-模块详解》第 3.1 节 |
| Factory Payload | 描述组件工厂的类型载荷：props/ctx/ref/stylesNames/vars/variant/staticComponents/compound/signature | 《07-模块详解》第 3.1 节 |
| 静态件（Statics） | 组件函数对象上的静态成员四件套：withProps/extend/classes/varsResolver；withProps 产物必须透传 | 《18-代码走读实录》第 1.4 节；《16-决策记录》ADR-005 |
| withProps | 高阶封装固定 props 的工厂静态方法；展开顺序 fixedProps 在前（预置而非劫持） | 《02-组件设计》第 1 节；《18-代码走读实录》第 1.4 节 |
| extend | 恒等函数形式的类型级扩展口：运行时原样返回，类型层收窄出 theme.components 的合法配置面 | 《01-系统架构》第 3.2 节 |
| 复合组件（compound） | compound: true 的组件：不允许在 UIProvider 主题上配置 classNames/styles/vars，只能 extend | 《01-系统架构》第 5 节 |
| 静态子组件 | 挂在组件函数对象上的子组件（Button.Group、Tabs.List），经 staticComponents 并入类型 | 《02-组件设计》第 2.3 节 |
| displayName 规范 | 组件 displayName 统一为 @xiaoye-react/ui/Xxx；withProps 产物为 WithProps(...) | 《02-组件设计》第 3 节 |
| renderRoot | 完全接管根元素渲染的 props 钩子（多态体系的逃生口） | 《03-接口设计》第 2.1 节 |
| mod | Box 的 data 属性描述符（对象/数组/字符串，假值剔除），把状态翻译成 data-* 供 CSS 属性选择器消费 | 《00-项目总览》第 8 节；《05-核心实现流程》主题四 |
| style props | Box 的白名单样式简写属性（m/p/bd/bg 等），由 extract-style-props 拆出并解析 | 《05-核心实现流程》主题四 |
这一组是消费侧最高频的术语——任何「样式定制不生效」类问题最终都会落在这里的某个词上。核心记忆锚点是那句表达铁律（差异进变量、状态进 data 属性）：StylesNames 与白名单定义了「能改什么」，varsResolver 与按选择器缓存定义了「改了之后怎么生效」，headless 与 stylesTransform 则是整条管线的两个总开关。
| 术语 | 释义 | 首要出处 |
|---|---|---|
| StylesApi | 按组件内部选择器注入 classNames/styles/vars/attributes 的定制接口体系 | 《01-系统架构》第 3.3 节；《16-决策记录》ADR-006 |
| StylesNames | 组件声明的内部选择器清单（Button 5 个、DataTable 12+ 个），即 StylesApi 的合法键位 | 《02-组件设计》第 3 节 |
| varsResolver | 组件静态的 CSS 变量解析器：读 theme+props 产出 --组件-* 局部变量 | 《00-项目总览》第 8 节；《18-代码走读实录》第 3.3 节 |
| CSS 变量白名单 | 组件用 XxxCssVariables 联合类型声明的可覆盖变量集合，白名单外编译期报错 | 《01-系统架构》第 3.5 节 |
| 静态类名 | ui-Button-root 形态的调试/探测类名，可经 UIProvider 的 withStaticClasses 整体关断 | 《01-系统架构》第 3.3 节 |
| 按选择器缓存 | useStyles 对不带 options 的 getStyles 调用做渲染内 Map 缓存（DataTable 虚拟滚动每帧上百次解析的对策） | 《10-性能设计与优化》第 2 节；《18-代码走读实录》第 3.3 节 |
| 差异进变量、状态进 data 属性 | 样式变体的表达铁律：variant 差异落在 CSS 变量，交互状态用 data-* 选择器 | 《07-模块详解》第 6 节 |
| stylesTransform | UIProvider 的样式转换通道；Emotion 可选层（src/emotion/）经它注入，默认关闭 | 《01-系统架构》第 4 节；《17-依赖全景》第 7.3 节 |
| headless | UIProvider 的去样式模式：关掉全部基础样式只留行为 | 《01-系统架构》第 3.3 节 |
| 虚拟色（virtual color） | 亮暗两套模式下分别取色的颜色定义（colors 数组十阶） | 《00-项目总览》第 8 节 |
| variantColorResolver | variant→颜色解析策略（filled/light/outline/gradient 等到背景/边框/文字色的映射），可整体替换 | 《01-系统架构》第 3.4 节 |
| classNamesPrefix | 静态类名与 CSS 变量的前缀，默认 'ui' | 《00-项目总览》第 8 节 |
这一组描述「值在组件边界上的形状与流向」。最重要的三条主线：受控双模及其纪律（双 onChange 陷阱、finalValue、唯一出口）、三级默认值合并与引用稳定（useProps 快路径是一切的性能前提）、以及「值形态按语义选型」的惯例（null 表示未选中、字符串日期、数组表示集合）。把这组术语读透，全库组件的状态行为就只剩细节差异。
| 术语 | 释义 | 首要出处 |
|---|---|---|
| 受控双模（useUncontrolled） | value 存在即受控（渲染期短路）、否则走内部 state 的统一状态模型；setter 是 onChange 唯一出口 | 《04-数据模型》第 2 节；《16-决策记录》ADR-007 |
| 双 onChange 陷阱 | 组件把 onChange 交给 useUncontrolled 又显式调用的双触发缺陷；历史审计（9347c9fd）发现 5 处 | 《04-数据模型》第 2 节 |
| finalValue | value 与 defaultValue 都未提供时的兜底值（DataTable 的 hiddenColumnKeys 用 []） | 《04-数据模型》第 2 节 |
| 外部 store | createStore + useSyncExternalStore 的闭包 store（core/store），承载命令式跨组件状态 | 《16-决策记录》ADR-008；《04-数据模型》第 1 节 |
| 三级默认值合并 | useProps 的优先级契约：传入 props > 主题 defaultProps > 组件 defaultProps；无默认值走快路径原样返回 | 《10-性能设计与优化》第 3 节；《18-代码走读实录》第 2 节 |
| 引用稳定优先 | 全库性能纪律：稳定 setter/useMemo 索引/零分配快路径，防「每帧新对象击穿 memo 链」 | 《10-性能设计与优化》第 3 节 |
| Set/Map 化热路径 | 用 Set/Map 索引替换 includes/findIndex 的 O(n²)（selectedKeysSet、optionIndexMap 等） | 《04-数据模型》第 7 节 |
| 注册表驱动 | 复合组件范式：子件挂载时向根注册自身，根维护索引（Combobox/Menu/Spotlight） | 《02-组件设计》第 2.9 节 |
| copy-on-write 路径克隆 | form/paths 的 setPath 优化：只克隆路径祖先链，替代整表深克隆（klona 因此成为死依赖） | 《17-依赖全景》第 9 节 |
| null 值语义 | Select 家族用 string | null 表达「未选中」（'' 是合法选项值） | 《02-组件设计》第 2.4 节；《19-数据契约与示例集》第 3 节 |
| 子树重建重置 | form uncontrolled 模式的 reset 机制：值存 ref，setValues/reset 经 formKey 递增重建表单子树 | 《04-数据模型》第 3 节 |
| Standard Schema | 表单校验的库无关接口（@standard-schema/spec），zod/valibot 均可接入 | 《04-数据模型》第 3.2 节 |
| DateStringValue | dates 模块的统一值货币：YYYY-MM-DD 字符串（避免时区歧义） | 《02-组件设计》第 2.10 节 |
这一组术语多数不在源码里而在流程与配置文件里——棘轮、债务政策、文档即测试、门禁全绿，描述的都是「这个仓库如何防止自己变坏」。它们的特殊之处是带有裁决语义：读贡献指南或提交代码被门禁拦下时，回来查这组词能迅速分清「这是规则」还是「这是规则的历史理由」。
| 术语 | 释义 | 首要出处 |
|---|---|---|
| 棘轮（ratchet） | 只许调低不许回涨的质量阈值：lint 警告 --max-warnings=57、exhaustive-deps 台账 | 《00-项目总览》第 8 节；《16-决策记录》ADR-012 |
| 债务政策 | CONTRIBUTING 成文的治理规则：豁免必须留注释、争议写「待裁决」、测试显式编码的行为 > 审查者直觉 | 《13-技术债务与演进建议》第 1 节 |
| 文档即测试 | docs:lint 三脚本逐行核对 API 表/demo 控制项，check:exports 校验导出真实性的机制合称 | 《09-测试与质量保障》第 4 节 |
| 消费者侧 ESM 复验 | 发布第 4 步：纯 Node ESM 环境具名导入三包（能拦住 vitest/webpack 挑 module 字段而漏掉的互操作回归） | 《06-部署运行》第 4.3 节 |
| harness | e2e 交互测试的 Vite 宿主页（端口 4175，assert-harness 校验 title 防端口被占） | 《00-项目总览》第 8 节；《09-测试与质量保障》第 3 节 |
| 补丁依赖 | patches/ 下经 pnpm.patchedDependencies 登记的上游补丁（当前仅 dumi@2.4.47：DumiDemo 的 React.memo bailout 修复） | 《17-依赖全景》第 8 节 |
| barrel 退出编译图 | 文档站启动优化事件：phosphor/react-icons 的图标 barrel 改写 438 文件，入口包 20.6→13.7MB | 《00-项目总览》第 7 节 |
| 双入口依赖 | main 与 module 指向不同构建的第三方包（rrule 案例）：消费需命名空间优先 + 计算键 default | 《06-部署运行》第 4.4 节 |
| 门禁全绿 | 提交前必须通过的命令清单（lint/typecheck/build/check:exports/docs:lint/test/e2e），与 CI 完全一致 | 《06-部署运行》第 6 节 |
| 源码级 paths 对齐 | tsconfig.json 的 paths 与 .dumirc.ts 的 alias 必须指回 src，防「本地有旧 es/ 产物才绿」的假阳性 | 《06-部署运行》第 4.4 节；《14-配置与环境详解》 |
用法说明：左列是仓库内的真实路径（省略仓库前缀），右列给出讲解该文件（或其所在目录）最深入的篇目与节号。索引按「hooks → ui core → ui 组件与垂直域 → pro → 工程配置与脚本 → 测试与文档」分组，共 60 个条目；未列出的文件按「就近原则」查所属目录的条目。这张表的维护规则与第 1 节术语表一致：当某篇文档新增了对某个文件的逐段走读，应在本表补一行；当文件被重构改名，删除或更正对应行——反向索引的价值取决于它的失效率，宁缺勿错。使用场景上，它主要服务两类人：接手仓库的贡献者（拿到一个文件想知道「有没有现成的讲解」）与本仓库的 AI 协作者（把本表当作「文档检索的倒排表」使用，避免在 21 篇文档里全文搜索）。
| 源码文件/目录 | 讲解出处 |
|---|---|
| packages/hooks/src/use-uncontrolled/use-uncontrolled.ts | 《04-数据模型》第 2 节；《16-决策记录》ADR-007 |
| packages/hooks/src/use-disclosure/ | 《04-数据模型》第 2.2 节；《19-数据契约与示例集》第 5 节 |
| packages/hooks/src/use-media-query/（attachMediaListener） | 《03-接口设计》第 7 节；《07-模块详解》第 2.2 节；《16-决策记录》ADR-011 |
| packages/hooks/src/use-hotkeys/ | 《07-模块详解》第 2.2 节（含 getHotkeyHandler 副产物） |
| packages/hooks/src/use-move/、use-radial-move/ | 《07-模块详解》第 2.2 节（Slider/Rating 几何底座） |
| packages/hooks/src/use-splitter/ | 《07-模块详解》第 2.2 节；《02-组件设计》第 2.9 节 |
| packages/hooks/src/use-id/ | 《07-模块详解》第 2.2 节（SSR 安全双实现） |
| packages/hooks/src/use-merged-ref/、use-callback-ref/ | 《07-模块详解》第 2.2 节 |
| packages/hooks/src/use-resize-observer/ | 《07-模块详解》第 2.2 节；《05-核心实现流程》通用手法 |
| packages/hooks/src/use-local-storage/（create-storage） | 《07-模块详解》第 2.2 节 |
| packages/hooks/src/index.ts | 《07-模块详解》第 2.1 节（导出面） |
| packages/hooks/vite.config.ts | 《01-系统架构》第 2.3 节；《16-决策记录》ADR-004/009 |
| packages/ui/src/core/factory/polymorphic-factory.tsx | 《18-代码走读实录》第 1 节；《01-系统架构》第 3.2 节 |
| packages/ui/src/core/factory/create-polymorphic-component.ts | 《03-接口设计》第 2.1 节；《18-代码走读实录》第 1 节 |
| packages/ui/src/core/factory/factory.tsx | 《07-模块详解》第 3.1 节；《18-代码走读实录》第 1.3 节 |
| packages/ui/src/core/Box/Box.tsx | 《05-核心实现流程》主题四；《07-模块详解》第 3.2 节 |
| packages/ui/src/core/Box/style-props/ | 《05-核心实现流程》主题四（style props 管线） |
| packages/ui/src/core/Box/get-box-mod/ | 《00-项目总览》第 8 节（mod 术语） |
| packages/ui/src/core/styles-api/use-styles/use-styles.ts | 《18-代码走读实录》第 3 节；《10-性能设计与优化》第 2 节 |
| packages/ui/src/core/styles-api/use-styles/get-class-name/ | 《07-模块详解》第 3.3 节（8 个辅助函数链） |
| packages/ui/src/core/styles-api/use-styles/get-style/ | 《07-模块详解》第 3.3 节 |
| packages/ui/src/core/styles-api/styles-api.types.ts | 《03-接口设计》第 2 节（StylesApiProps 六件套） |
| packages/ui/src/core/styles-api/create-vars-resolver/ | 《00-项目总览》第 8 节；《07-模块详解》第 3.3 节 |
| packages/ui/src/core/styles-api/use-resolved-styles-api/ | 《07-模块详解》第 3.3 节（复合子件复用 getStyles） |
| packages/ui/src/core/UIProvider/UIProvider.tsx | 《01-系统架构》第 3.4 节；《04-数据模型》第 5 节 |
| packages/ui/src/core/UIProvider/UI.context.ts | 《04-数据模型》第 5 节（Context 总表） |
| packages/ui/src/core/UIProvider/use-props/use-props.ts | 《18-代码走读实录》第 2 节；《10-性能设计与优化》第 3 节 |
| packages/ui/src/core/UIProvider/UIThemeProvider/ | 《01-系统架构》第 3.4 节（mergeUITheme/双读法） |
| packages/ui/src/core/UIProvider/default-theme.ts | 《01-系统架构》第 3.4 节（DEFAULT_THEME 全量键位） |
| packages/ui/src/core/UIProvider/UICssVariables/default-css-variables-resolver.ts | 《01-系统架构》第 3.4 节；《19-数据契约与示例集》第 8 节 |
| packages/ui/src/core/UIProvider/UICssVariables/virtual-color/ | 《00-项目总览》第 8 节；《07-模块详解》第 3.4 节 |
| packages/ui/src/core/UIProvider/ColorSchemeScript/ | 《00-项目总览》第 10 节（防 FOUC）；《07-模块详解》第 3.4 节 |
| packages/ui/src/core/UIProvider/color-functions/ | 《01-系统架构》第 3.4 节（variantColorResolver） |
| packages/ui/src/core/store/store.ts | 《16-决策记录》ADR-008；《04-数据模型》第 1 节 |
| packages/ui/src/core/utils/create-safe-context/ | 《04-数据模型》第 5 节（中文错误即调试入口） |
| packages/ui/src/core/utils/Activity/ | 《01-系统架构》第 3.6 节；《16-决策记录》ADR-002 |
| packages/ui/src/core/DirectionProvider/ | 《01-系统架构》第 3.6 节（DIR_MUTATION_OPTIONS） |
| packages/ui/src/core/InlineStyles/ | 《01-系统架构》第 3.6 节；《07-模块详解》第 6 节 |
| packages/ui/src/components/Button/Button.tsx | 《02-组件设计》第 2.1 节；《19-数据契约与示例集》第 1 节；《18-代码走读实录》 |
| packages/ui/src/components/Button/Button.module.css | 《19-数据契约与示例集》第 1 节（变量消费范例） |
| packages/ui/src/components/DataTable/DataTable.tsx | 《02-组件设计》第 2.2 节；《05-核心实现流程》主题二/五；《19-数据契约与示例集》第 6 节 |
| packages/ui/src/components/Tabs/Tabs.tsx（+ Tabs.context.ts） | 《02-组件设计》第 2.3 节；《19-数据契约与示例集》第 4 节 |
| packages/ui/src/components/Combobox/（Combobox.tsx、use-combobox、context） | 《02-组件设计》第 2.4 节；《04-数据模型》第 4 节；《05-核心实现流程》主题三 |
| packages/ui/src/components/ModalBase/ModalBase.tsx | 《02-组件设计》第 2.5 节；《05-核心实现流程》主题一 |
| packages/ui/src/components/Modal/modal-stack.ts | 《02-组件设计》第 2.5 节（栈顶仲裁） |
| packages/ui/src/components/Notifications/notifications.store.ts | 《02-组件设计》第 2.7 节；《19-数据契约与示例集》第 7 节 |
| packages/ui/src/form/use-form.ts | 《04-数据模型》第 3 节；《09-测试与质量保障》第 5 节 |
| packages/ui/src/form/paths/（set-path.ts） | 《17-依赖全景》第 9 节（copy-on-write 与 klona 退役） |
| packages/ui/src/form/schema-resolver.ts | 《04-数据模型》第 3.2 节；《17-依赖全景》第 4.1 节 |
| packages/ui/src/emotion/（emotion-transform.ts、ssr.tsx） | 《01-系统架构》第 4 节；《17-依赖全景》第 7.3 节 |
| packages/ui/src/colors-generator/generate-colors.ts | 《17-依赖全景》第 4.1 节（chroma-js） |
| packages/ui/src/index.ts | 《03-接口设计》第 1 节（入口与消歧导出） |
| packages/ui/vite.config.ts | 《14-配置与环境详解》第 3 节；《16-决策记录》ADR-004/009 |
| packages/@xiaoye-react/pro/src/pro-table/ProTable.tsx | 《02-组件设计》第 2.8 节（requestIdRef 竞态保护） |
| packages/@xiaoye-react/pro/src/search-filter/SearchFilter.tsx | 《07-模块详解》第 5 节 |
| package.json（根） | 《14-配置与环境详解》第 1 节；《16-决策记录》ADR-012；《17-依赖全景》第 2 节 |
| eslint.config.mjs | 《09-测试与质量保障》第 6 节；《13-技术债务》D5/D6 |
| scripts/release.mjs | 《06-部署运行》第 4.2 节（三档命令） |
| scripts/validate-package-exports.mjs | 《06-部署运行》第 6 节；《09-测试与质量保障》第 4 节 |
| patches/dumi@2.4.47.patch | 《17-依赖全景》第 8 节；《08-安全与权限设计》第 2.2 节 |
| e2e/harness/、e2e/interactions/ | 《09-测试与质量保障》第 3 节（双配置双宿主） |
| apps/docs/scripts/docgen.ts | 《09-测试与质量保障》第 4 节；《13-技术债务》D4 |
四类高频任务覆盖了本仓库 90% 以上的日常工作场景；每条路径都按「先手册、再机制、后验收」组织——先读操作清单知道要做什么，再读机制篇知道为什么这么做，最后按验收标准确认做完了。执行中遇到具体报错，随时切到任务二/任务四的排查路径。
目标是从零把一个新组件带到发布面。第 1 步读《11-扩展开发指南》SOP 一拿到全流程清单，同时读 CONTRIBUTING.md 的「新增一个组件」节确认门禁清单；第 2 步读《18-代码走读实录》第 1、2、3 节——工厂、useProps、useStyles 正是新组件要依次调用的三个内核件，理解它们可以避免「照抄模板但不知其所以然」；第 3 步对照《02-组件设计》第 1 节的五层结构与第 3 节的共性约定表（displayName、StylesNames、CSS 变量白名单、状态双模、单测随组件），以 packages/ui/src/components/Button/Button.tsx 为范本落码；第 4 步样式按《07-模块详解》第 6 节的「差异进变量、状态进 data 属性」铁律写 module.css；第 5 步导出与文档——《03-接口设计》第 1 节理解入口导出与 check:exports，《09-测试与质量保障》第 4 节理解 docs:lint 对 API 表的逐行核对。最后用《06-部署运行》第 7 节的常见任务速查做一次自查。这条路径的验收标准很明确：新组件目录在形状上与 Button 同构、pnpm check:exports 与 pnpm docs:lint 全绿、同目录有一个能表达核心状态语义的测试文件——三者齐备才算走完，缺一项都会在下一次发布预检时回来找你。
这是一个四层管线（《07-模块详解》第 6 节）上的定位问题。先读《12-FAQ与故障排查》第 1 节与第 5 节的排查决策树，确认是否为高频已知问题（忘引 style.css、Provider 未包裹、多个受控 Provider 互覆盖）；再读《01-系统架构》第 4 节建立链路认知：主题变量（UICssVariables）→ varsResolver 局部变量 → module.css 消费 → StylesApi 实例覆盖；然后按链路逐层排查——变量没生效查 XxxCssVariables 白名单（白名单外 vars 静默忽略？不，类型层会报错，运行时手工注入才会静默），类名没生效查《18-代码走读实录》第 3 节的 8 级类名合成顺序（ classNamesPrefix → 全局 → 主题 → 变体 → 静态 → 选择器 → 根 → options），带 options 的 getStyles 调用不走缓存（《10-性能设计与优化》第 2 节的边界）；最后确认样式优先级语义：styles 内联样式永远压过 module.css 规则，主题级 classNames 与实例级 classNames 是叠加而非替换（《03-接口设计》第 3 节的三层定制接口）。
主线读《06-部署运行》第 4 节：三档命令（preflight/check/publish）、断点续跑 --from、消费者侧 ESM 复验的原理（为什么 vitest 全绿还会坏）；配合《16-决策记录》ADR-001（为什么顺序固定 hooks → ui → pro）与 ADR-011（peer 下限对齐真实消费面——release 预检会核对它）；**根 README「发布相关的坑」**逐条过一遍（workspace: 协议、rrule 双入口、'use client' banner、72 小时 unpublish 窗口）；版本策略见《06-部署运行》第 4.1 节与《03-接口设计》第 7 节（版本与兼容性约定：手工改版本号、不用 changesets）；发布前把《11-扩展开发指南》SOP 四的检查单走完。若发布中遇到 ESM 复验失败，回读《17-依赖全景》第 7.4 节的 rrule 案例与第 9 节的健康度评估。
先定位层级：消费侧类型报错读《12-FAQ与故障排查》第 2 节与《03-接口设计》第 2 节（公共类型体系——多态 props、StylesNames、CssVariables 三类泛型最容易出「看不懂」的报错）；开发侧（仓库内）报错先读《14-配置与环境详解》的三套 typecheck 配置（ui/hooks/demos 各有 tsconfig），确认是哪一套抓到的。高频场景对应：泛型多态报错（component prop 相关）回读《18-代码走读实录》第 1.2 节的交叉类型装配与 StaticComponents 的 {} 回退注释；StylesApi 键位报错（classNames/styles/vars 的键不在白名单）查《01-系统架构》第 3.5 节与对应组件的 XxxCssVariables；跨包继承报错（TS2307 级、干净克隆才复现）是 paths/alias 未对齐（README 坑清单第 5 条）；dts 产物报错读《14-配置与环境详解》第 3 节的 vite-plugin-dts 两个行为补丁与 check:published-types 的作用。若报错源于升级 TypeScript，先确认四处 5.5.2 对齐（《17-依赖全景》第 2 节）。
读《10-性能设计与优化》全文建立三条链路（产物/渲染/主题）的心智，再按症状定点：打包体积异常回读 ADR-004 的 preserveModules 事故记录与《17-依赖全景》的外部化论证；列表卡顿查《05-核心实现流程》主题二（虚拟滚动与测量）与《04-数据模型》第 7 节的 Set 化纪律；换肤卡顿确认是否绕开了 CSS 变量链（《10》第 4 节的零重渲染机制）；优化立项按《13-技术债务与演进建议》第三阶段的标准（实测数据、替代方案、回滚方案）写记录——源码注释里 12KB→327KB 与 copy-on-write 两则先例是范本。
五条路径共享同一个使用原则：路径是「阅读顺序」而不是「替代阅读」——每一步都指向对应篇目里最短必读的节，跳过中间步骤直接看结论，往往会在具体报错面前失去定位能力。若时间只够读一篇，按任务对号入座：改代码读 11，查问题读 12，看机制读 18，对 API 读 19，查术语与文件读本篇。
至此 21 篇文档（00-20）成套：00-06 建立全景与机制认知，07-10 做包级深读与横切面（测试/性能/安全），11-12 是操作与排查手册，13-15 是治理与参考，16-20（本批新增）补齐决策考古、依赖全景、代码走读、示例契约与术语索引。所有篇目共享同一条纪律：结论必须能回溯到源码路径，无法确认的写「⚠️ 待确认」而不是含糊其辞；重复内容一律「见《0X-xxx》」而不是抄写。当仓库演进使某篇结论过时时，维护方式与《13-技术债务与演进建议》第 4 节的台账机制一致：先改源码旁的注释（就地归档），再同步对应篇目，让文档与 archive/audit/ 的审计节奏对齐滚动。