阶段一交付物之三。十一卷 · 144 篇 · 预估总字数 70 万+。默认口径:全部组件独立成篇(72 个 manifest 组件 + form-item 因协议独立成篇,故基础组件篇为 73 篇);若采纳合并方案(见决策点),第六/七卷及增强卷的对应篇目将按标注合并。
每篇固定深度骨架:① 定位与全量 API 面 → ② 源码结构剖析 → ③ 核心机制 mermaid 图 → ④ 数据流/控制模型 → ⑤ 业界对比 → ⑥ 样式与令牌消费 → ⑦ 边界与陷阱 → ⑧ 测试解读 → ⑨ 总结 + 源码索引。基础设施篇采用等价骨架。单组件篇 ≥4000 字、合并篇 ≥6000 字、基础设施篇 ≥5000 字。
| 篇目 | 篇名 | 核心问题(一句话) | 承载知识点 | 字数 | 依赖 |
|---|---|---|---|---|---|
| 1-01 | 开篇:一个 AI 协作组件库的自白 | 用 AI 写组件库,如何保证质量不是空中楼阁? | A1 | 4500 | — |
| 1-02 | Monorepo 分层:六包两应用的架构地图 | 为什么拆成 6 个包,而不是一个大包? | A2 | 5000 | 1-01 |
| 篇目 | 篇名 | 核心问题 | 承载知识点 | 字数 | 依赖 |
|---|---|---|---|---|---|
| 2-01 | workspace 组织与一套 alias 服务四条工具链 | 四条工具链(构建/测试/文档/联调)如何共享同一份路径映射而不漂移? | B1 B2 | 5000 | 1-02 |
| 2-02 | 构建体系:ES-only 与 createLibraryConfig 工厂 | 为什么放弃 CJS?三个包如何做到零自有构建配置? | B3 B4 | 5500 | 2-01 |
| 2-03 | prepare-package:808 行 d.ts 后处理管线 | vite-plugin-dts 的产物离"可发布"还差多远? | B5 B6 | 5500 | 2-02 |
| 2-04 | Changesets 发布流水线与门禁兜底 | 从一条 changeset 到 npm publish,中间有几道闸门? | B7 B8 | 5000 | 2-03 |
| 2-05 | CI 门禁编排与两条真实踩坑 | CI OOM 与 typecheck 工程拆分是如何被治理的? | B9 B10 B18 | 5000 | 2-04 |
| 2-06 | 文档站架构(上):manifest 驱动的 VitePress | 侧边栏为什么不能手写?暗色开关如何打通组件库令牌? | B11 | 5000 | 1-02 |
| 2-07 | 文档站架构(下):demo 三件套 | 「运行的代码 = 展示的代码」是怎么实现的? | B12 B13 | 5500 | 2-06 |
| 2-08 | Playground:源码级联调 | 改一行组件源码,为什么 playground 能即时热更? | B14 | 4000 | 2-01 |
| 2-09 | llms 文档与 MCP Server:组件库的 AI 生态 | 让 AI 用对你的组件库,需要哪四层数据设施? | B15 B16 | 5500 | 2-07 |
| 篇目 | 篇名 | 核心问题 | 承载知识点 | 字数 | 依赖 |
|---|---|---|---|---|---|
| 3-01 | 令牌三层架构总览 | 基元/语义/刻度三层各管什么,为什么不能合并? | C1 | 5000 | 1-02 |
| 3-02 | 色板与角色:Stripe 锚定的取值体系 | 209 个变量如何做到每个值都可追溯? | C2 C3 C4 | 5500 | 3-01 |
| 3-03 | 双主题机制:data-theme 协议与 --xy-mix-light | 85 行暗色覆写如何换掉整个库的皮肤? | C5 C6 | 5500 | 3-01 |
| 3-04 | Stripe 蓝本对照:设计决策的可追溯性 | 抄设计语言,怎么"抄"得系统而非像素级照搬? | C7 | 4500 | 3-02 |
| 3-05 | generate:tokens:CSS 唯一事实源到 TS 常量层 | 为什么 TS 层必须是生成物而不能手写? | C8 | 5000 | 3-01 |
| 3-06 | theme 包:BEM、命名空间与四级定制纵深 | 用户改一个颜色,到底有多少种改法? | C9 C10 C11 C12 | 5500 | 3-03 |
| 篇目 | 篇名 | 核心问题 | 承载知识点 | 字数 | 依赖 |
|---|---|---|---|---|---|
| 4-01 | component-manifest:一份 JSON 管六处一致性 | 组件库规模化后,"漏注册"如何变成 lint 错误? | D1 D2 | 5500 | 1-02 |
| 4-02 | 安装器体系:withInstall、Context 捕获与幂等锁 | $message 在组件树外为什么还能吃到全局配置? | D3 D4 D5 | 5500 | 4-01 |
| 4-03 | 标准组件解剖:类型层/视图层/逻辑层三件套 | 一个组件目录为什么长这样? | D6 D7 D8 | 5500 | 4-02 |
| 4-04 | 受控/非受控双模的现状与考古 | 8 行的 useControlled 为什么没人用? | D9 | 4500 | 4-03 |
| 4-05 | 浮层体系(上):三态状态机与全局浮层栈 | visible/rendered/isAnimating 为什么必须正交? | D10 D11 | 5500 | 4-03 |
| 4-06 | 浮层体系(下):定位管道与关闭语义 | 点触发器算"外部点击"吗? | D12 D13 | 5500 | 4-05 |
| 4-07 | 焦点治理:焦点陷阱与滚动锁 | 焦点逃逸、Tab 循环、焦点还原如何同时成立? | D14 D15 | 5500 | 4-05 |
| 4-08 | 表单联动与全局配置链 | form-item 的错误态是怎么"传"进 input 的? | D16 D17 | 5500 | 4-03 |
| 4-09 | group 复合模式:属性下发与汇总收口 | radio-group 如何只做协调不渲染子项? | D18a | 5000 | 4-08 |
| 4-10 | 泛型组件全链路:以 select 为样本 | generic="T" 如何贯穿 props/事件/插槽/实例? | D18b | 5000 | 4-05 |
| 4-11 | 命令式服务(上):message 治理术 | 消息轰炸、重复消息、页面隐藏时的暂停如何设计? | D18c | 5500 | 4-02 |
| 4-12 | 命令式服务(下):dialog 队列与 loading 双形态 | alert/confirm/prompt 如何串行排队并支持中途 update? | D18d | 5500 | 4-11 |
| 篇目 | 篇名(组件) | 核心问题 | 专属知识点 | 依赖 |
|---|---|---|---|---|
| 5-01 | Icon:全库图标基座 | 图标如何做到按需加载且测试可断言? | E1 | 4-03 |
| 5-02 | Button:最标准的解剖样本 | 一个"简单"按钮里藏了多少防御? | E2 | 4-03 |
| 5-03 | Link:链接与按钮的边界 | 什么时候该是 a 标签,什么时候该是 button? | E3 | 5-02 |
| 5-04 | Breadcrumb:父收集子的注册模式 | 子组件如何把自己"登记"进父组件? | E4 | 4-09 |
| 5-05 | Text:排版令牌的消费范本 | 文本组件的语义分层(heading/正文/辅助)如何映射令牌? | E5 | 3-02 |
| 5-06 | Badge:依附与独立双形态 | 徽标的位置协商怎么实现? | E6 | 5-02 |
| 5-07 | Avatar 与头像组 | 头像溢出折叠(+N)的计数策略 | E7 | 4-09 |
| 5-08 | Image 与图片预览 | 从懒加载占位到全屏 viewer 的完整链路 | E8 | 4-07 |
| 5-09 | Watermark:canvas 水印 | 水印如何铺满且抗删除? | E9 | 5-02 |
| 5-10 | Card:容器类组件的 slot 约定 | header/body/footer 的结构化插槽设计 | E10 | 5-02 |
| 5-11 | CheckCard:卡片化选择 | 卡片视觉与受控语义如何合体? | E11 | 4-09 |
| 5-12 | Carousel:轮播状态机 | item 注册、循环与自动播放的定时器治理 | E12 | 4-09 |
| 5-13 | Affix:固钉的几何计算 | 从文档流到固定定位的切换时机 | E13 | 5-02 |
| 5-14 | Anchor:锚点与滚动联动 | 高亮当前章节的判定算法 | E14 | 5-13 |
| 5-15 | Menu:层级注册与子菜单浮层 | SubMenu 如何复用通用浮层体系? | E15 | 4-06 |
| 5-16 | Row:栅格的 provide 侧 | gutter 如何跨层下发? | E16 | 4-08 |
| 5-17 | Col:响应式断点矩阵 | 3020 行 CSS 是怎么来的、该不该这么来? | E17 | 5-16 |
| 5-18 | Scrollbar:原生能力的封装度 | 什么时候自己写滚动条,什么时候交给浏览器? | E18 | 5-02 |
| 5-19 | Splitter:拖拽分栏 | 拖拽几何与键盘可达的双输入 | E19 | 5-13 |
| 5-20 | Divider:最小组件的完整规范 | 一个 50 行组件如何做到教科书级规范? | E20 | 4-03 |
| 5-21 | Tag:通用状态类型的消费 | ComponentStatus 如何跨 20 个组件复用? | E21 | 3-02 |
| 5-22 | Space:间距的运行时方案 | margin 方案 vs gap 方案的取舍 | E22 | 5-02 |
| 5-23 | Tabs:激活态管理 | 受控 tabs 的事件时序与面板联动 | E23 | 4-10 |
| 篇目 | 篇名(组件) | 核心问题 | 专属知识点 | 依赖 |
|---|---|---|---|---|
| 6-01 | ConfigProvider:全局配置源头 | 八项配置的注入与降级链路 | F1 | 4-08 |
| 6-02 | Input:受控输入的工程化 | 597 行里藏着多少边界(IME/组合输入/格式化)? | F2 | 4-08 |
| 6-03 | AutoComplete:三合一组合 | input + 浮层 + 键盘导航的编排 | F3 | 6-02 |
| 6-04 | Cascader:级联面板 | 多级懒加载与选中路径回显 | F4 | 6-15 |
| 6-05 | Radio:三形态一个 context | button 形态的视觉特化如何不碰逻辑? | F5 | 4-09 |
| 6-06 | Checkbox:min/max 约束 | options 配置化与受控数组值 | F6 | 6-05 |
| 6-07 | Switch:最小受控范本 | 双模 props 的最简正确实现 | F7 | 4-04 |
| 6-08 | InputTag:复合输入态 | 标签流 + 文本输入的状态机 | F8 | 6-02 |
| 6-09 | InputNumber:精度与边界 | 步进、小数位与超界回弹 | F9 | 6-02 |
| 6-10 | Rate:评分与可达性 | hover 预览态与键盘操作的统一模型 | F10 | 6-07 |
| 6-11 | Slider:拖拽几何 | pointer 事件与 step 吸附的计算 | F11 | 6-10 |
| 6-12 | DatePicker:日历面板状态机 | dayjs 封装边界与面板切换 | F12 | 6-15 |
| 6-13 | TimePicker:时间面板 | 列表滚动选择与格式约束 | F13 | 6-12 |
| 6-14 | TimeSelect:select 的特化 | 用枚举生成替代自由输入的取舍 | F14 | 6-15 |
| 6-15 | Select:泛型浮层受控组件 | 拍平选项模型与巨型键盘 switch | F15 | 4-10 |
| 6-16 | TreeSelect:树与多选映射 | 树形数据到扁平值的桥接 | F16 | 6-15 |
| 6-17 | Form:校验编排 | async-validator 集成与 validate 生命周期 | F17 | 4-08 |
| 6-18 | FormItem:消息与 aria 链路 | 错误态如何同时作用于样式与无障碍树 | F18 | 6-17 |
| 6-19 | Upload:文件队列 | 自定义请求与进度回调的协议设计 | F19 | 6-02 |
| 6-20 | Editor:富文本桥接 | vditor 的受控桥接与双主题适配 | F20 | 6-02 |
注:manifest 中 editor 属 form 组,故第六卷为 20 篇(F1~F20);form-item 无独立 manifest 条目但协议独立成篇(6-18),第四卷通用篇不计入。
| 篇目 | 篇名(组件) | 核心问题 | 专属知识点 | 依赖 |
|---|---|---|---|---|
| 7-01 | Alert:语义色派生 | 组件变量头的标准写法 | G1 | 3-06 |
| 7-02 | Message:命令式消息治理 | 670 行的实现里每一段在防什么? | G2 | 4-11 |
| 7-03 | Notification:双形态并存 | 组件式与服务式如何共享实现? | G3 | 7-02 |
| 7-04 | Backtop:滚动目标解析 | 滚动容器的判定与可见性阈值 | G4 | 5-13 |
| 7-05 | Collapse:手风琴模式 | 多开与互斥的状态收口 | G5 | 4-09 |
| 7-06 | CollapseTransition:过渡 hook | height 过渡为何必须 JS 参与 | G6 | 7-05 |
| 7-07 | Empty:无逻辑组件的规范 | 纯展示组件的 API 纪律 | G7 | 5-10 |
| 7-08 | Loading:指令与服务双注册 | v-loading 的元素级生命周期 | G8 | 4-02 |
| 7-09 | Skeleton:节流防闪烁 | leading/trailing 节流解决什么问题 | G9 | 4-04 |
| 7-10 | Result:预设场景组合 | 枚举预设 vs 自由组合的边界 | G10 | 7-07 |
| 7-11 | Tooltip:浮层四件套最小样本 | 一个最简浮层的完整装配 | G11 | 4-06 |
| 7-12 | Popover:触发策略全集 | hover/click/focus/contextmenu 的守卫差异 | G12 | 7-11 |
| 7-13 | Popconfirm:确认语义 | 气泡里的动作按钮与事件拦截 | G13 | 7-12 |
| 7-14 | Dropdown:键盘导航 | roving focus 与菜单语义 | G14 | 4-10 |
| 7-15 | Transfer:双栏数据流 | 左右两栏如何共享一份真相? | G15 | 6-06 |
| 7-16 | Dialog:模态全解 | 从 v-model 到服务式调用的完整实现 | G16 | 4-07 |
| 7-17 | Drawer:容器变体 | 与 dialog 共享什么、差异在哪 | G17 | 7-16 |
| 篇目 | 篇名(组件) | 核心问题 | 专属知识点 | 依赖 |
|---|---|---|---|---|
| 8-01 | Statistic:数值呈现 | 格式化管道与动画取舍 | H1 | 5-05 |
| 8-02 | Countdown:定时器治理 | 暂停/恢复与页面隐藏 | H2 | 8-01 |
| 8-03 | Progress:SVG 描边 | line/circle 双形态的几何 | H3 | 5-21 |
| 8-04 | Steps:状态派生 | 步骤序列的当前态计算 | H4 | 5-23 |
| 8-05 | Timeline:slot 扫描与 vnode 注入 | item/group 的"最后一项"判定 | H5 | 5-04 |
| 8-06 | Scheduler:fullcalendar 集成 | 第三方库的组件化封装边界 | H6 | 6-12 |
| 8-07 | Descriptions:schema 化渲染 | 数据驱动的描述列表 | H7 | 6-17 |
| 8-08 | Tree:tree-store 状态管理 | 扁平化存储与树形渲染的互转 | H8 | 4-03 |
| 8-09 | Table:列模型与固定列 | DOM 镜像的代价与替代方案 | H9 | 6-15 |
| 8-10 | Pagination:页码窗口 | 椭圆省略的窗口算法 | H10 | 5-23 |
| 8-11 | Charts:echarts 封装 | 主题令牌如何喂给 canvas | H11 | 3-05 |
| 8-12 | AudioPlayer:howler 封装 | 播放器状态的组件化 | H12 | 8-02 |
| 8-13 | VideoPlayer:video.js 封装 | 皮肤令牌化与第三方 CSS 隔离 | H13 | 8-12 |
| 篇目 | 篇名 | 核心问题 | 专属知识点 | 依赖 |
|---|---|---|---|---|
| 9-01 | 增强层总览:导出边界与双重守卫 | 为什么 2.0 要做一次 API 面大收口? | I1 | 4-01 |
| 9-02 | core.ts 协议层 | 增强层内部的"宪法"有哪些条款? | I2 | 9-01 |
| 9-03 | field-schema:一份 schema 三形态 | 23 个内建组件如何被字符串引用? | I3 | 9-02 |
| 9-04 | SearchForm:查询语义 | 查询/重置与折叠的字段布局 | I4 | 9-03 |
| 9-05 | ProForm:schema 驱动表单 | Grid 布局与只读态整表切换 | I5 | 9-03 |
| 9-06 | OverlayForm:多态容器 | drawer/modal 一个 prop 切换的实现 | I6 | 9-05 |
| 9-07 | DialogForm:特化薄壳 | Omit 派生类型的封装范式 | I7 | 9-06 |
| 9-08 | DrawerForm:对称特化 | 与 dialog-form 的镜像关系 | I8 | 9-07 |
| 9-09 | StepsForm:分步表单 | 跨步骤模型共享与分步校验 | I9 | 9-05 |
| 9-10 | RequestForm:请求表单 | 初始加载与提交的异步协议 | I10 | 9-05 |
| 9-11 | LoginForm:登录预设 | 业务预设组件的配置面设计 | I11 | 9-04 |
| 9-12 | FilterPanel:筛选面板 | 卡片化筛选的组合方式 | I12 | 9-04 |
| 9-13 | PageToolbar:工具条 | 纯布局件的设计纪律 | I13 | 9-01 |
| 9-14 | PageHeader:页头 | meta 区与动作区的结构 | I14 | 9-13 |
| 9-15 | PageContainer:页面容器 | loading 视觉的内聚 | I15 | 9-14 |
| 9-16 | AvatarMenu:头像菜单 | 基础组件的高层组合样本 | I16 | 7-14 |
| 9-17 | HeaderTabs:头部页签 | 页签 + 动作下拉的组合 | I17 | 5-23 |
| 9-18 | NoticeCenter:消息中心 | 多 tab 列表的状态组织 | I18 | 7-03 |
| 9-19 | StatCard:指标卡 | 趋势展示与骨架态 | I19 | 8-01 |
| 9-20 | AsyncStateContainer:三态容器 | loading/empty/error 的统一协议 | I20 | 7-07 |
| 9-21 | ListPage:薄预设封装 | 127 行如何完整透传所有插槽? | I21 | 9-24 |
| 9-22 | CrudPage:整页 CRUD | 三级金字塔的顶层如何组装? | I22 | 9-21 |
| 9-23 | SplitLayoutPage:分栏页面 | Splitter 的页面级封装 | I23 | 5-19 |
| 9-24 | ProTable(上):配置模型 | 一份列配置如何声明 14 种渲染与编辑器? | I24 | 9-03 |
| 9-25 | ProTable(下):运行时引擎 | 竞态防护、导出打印、拖拽与全屏的实现 | I25 | 9-24 |
| 9-26 | ColumnSettingPanel:列设置 | 列显隐/固定/排序的状态同步 | I26 | 9-24 |
| 9-27 | SavedViewTabs:保存视图 | 视图持久化的 key 设计 | I27 | 9-24 |
| 9-28 | TableFilterDrawer:筛选抽屉 | schema 驱动的复杂筛选 | I28 | 9-03 |
| 9-29 | ImportResultTable:导入回显 | 结果表格的成功/失败汇总 | I29 | 9-24 |
| 9-30 | AuditTimeline:审计流 | 时间线的业务特化 | I30 | 8-05 |
| 9-31 | DetailPanel:详情浮层 | schema → descriptions 的转换 | I31 | 9-03 |
| 9-32 | DetailPage:详情页 | 异步态 + 描述 + 审计的组装 | I32 | 9-31 |
| 9-33 | ApprovalFlowPanel:审批流 | 节点面板的状态映射 | I33 | 8-04 |
| 9-34 | ImportWizard:导入向导 | 分步上传/校验/结果的编排 | I34 | 9-09 |
| 9-35 | ExportTaskPanel:导出任务 | 异步任务的进度呈现 | I35 | 8-03 |
| 篇目 | 篇名 | 核心问题 | 承载知识点 | 字数 | 依赖 |
|---|---|---|---|---|---|
| 10-01 | 单测策略:111 个 spec 如何组织 | 组件库单测到底在测什么? | J1 | 5000 | 4-03 |
| 10-02 | 类型夹具:@ts-expect-error 负向断言 | 类型怎么变成可回归的资产? | J2 | 5000 | 4-01 |
| 10-03 | 视觉巡检:双主题像素 diff | 0.5% 阈值与基线机制的设计 | J3 | 5500 | 3-03 |
| 10-04 | e2e 与六道发布门禁全景 | 以文档站为宿主的 e2e 是聪明还是妥协? | J4 B17 | 5500 | 2-05 |
| 篇目 | 篇名 | 核心问题 | 承载知识点 | 字数 | 依赖 |
|---|---|---|---|---|---|
| 11-01 | AI 协作研发组件库方法论复盘 | 全 AI 编写为什么没有失控? | K1 | 5500 | 全部 |
| 11-02 | 约定驱动开发:AGENTS.md 即规范 | 如何把工程约定写成机器可执行? | K2 | 5000 | 11-01 |
| 11-03 | 组件库的 AI 生态闭环 | 组件库服务 AI 消费的完整数据流 | K3 | 5000 | 2-09 11-02 |