dev-comp —— 组件库开发迭代工作流

定位：vue-amazing-ui 单组件开发迭代领域 SOP。 架构：轻量领域流程 + 软复用 dev-flow 能力模块。全程❌ 不产生 .flow 锁、❌ 不走 dev-flow 重型门控（.validated 物理检查点 / JSON 逐步校验 / 门控 subagent / post-step 脚本 / 工具门禁）；✅ 仅保留轻量交互式 Gate——每阶段完成后输出「阶段完成报告」并弹 ask_followup_question，等用户确认再进入下一阶段（详见「6 阶段 + Gate 流程总览」）；✅ 另配 2 个轻量校验脚本——scripts/validate-component.sh 承载 Gate 5 确定性检查（A/B/C/E/F/G 配置项 + S 提交红线，设计哲学「确定性用代码」，详见「能力复用索引」）+ scripts/lint-working-context-name.sh 工作上下文命名体检（L1-L5，调用点见 references/flow.md 阶段 0 新建后 / 阶段 5 收尾 / dc:status）。

⚙️ 个人化配置区（复用/分享时只改这一块）

本 skill 核心流程通用；下列配置换人换机时只需填 4 个本地路径，其余保持默认即可。

必填（首次使用前填写；ARTIFACTS_FALLBACK_DIR 可留空）

默认可用（无需修改）

本地 clone 不存在时：降级为仅用官网（web_fetch）参考，并提示用户可clone 以获得源码级复用。 脚本默认路径兜底：两个脚本内的硬编码默认值（validate-component.sh 的项目根 / 归档兜底目录、lint-working-context-name.sh 的工作上下文目录 / 项目根）可用环境变量 VAUI_PROJECT_ROOT / VAUI_ARTIFACTS_DIR / VAUI_WC_DIR 覆盖；主流程调用已显式传 {PROJECT_ROOT}，此处仅供换人换机兜底。

📋 项目规范权威源（必读 · 2026-09-15 新增）

项目内已有面向贡献者的设计规范（{PROJECT_ROOT}/development/），是组件实现的权威源；本 skill 只做「引用 + 增量补充」，禁止另起平行规则。 ⚠️ 本 skill 的 checklist / 模板 / 脚本与项目规范冲突时，以项目规范为准，并立即回填本 skill（单向断链是历史欠账的根因，见 rules/按需-Skill设计-跨文件协作.mdc §2.1）。映射表详见 references/project-map.md §项目规范权威源索引。

📦 产物存储设计原则（2026-08-18 固化 · 2026-08-19 补第 6 条 · 2026-08-21 第 6 条收敛为「统一运行时目录」）

决策背景：深入评估过「产物入仓库」方案，被开源仓库 git 污染 + dev-flow 生态路径硬绑定否决。产物一律留在 ~/.codebuddy/（第 1-5 条 2026-08-18 固化；第 6 条 2026-08-19 初版为「用户可选归档到 artifacts/」，2026-08-21 按用户决策收敛为「统一运行时目录 + 收尾告知位置」，不再弹归档决策）。artifacts/ 目录保留（skill 内置 skills/dev-comp/.gitignore 忽略其内容、仅保留 artifacts/README.md），但仅作为历史归档的读取兜底，不再接收新产物；⚠️ 换仓库分发本 skill 时须连同该 .gitignore 一起复制。本小节固化六条原则，防止后续迭代被顺手改回。

1. 产物不入仓库：vue-amazing-ui 是开源项目，工作上下文/对齐清单/决策记录/度量是个人私有开发过程，进 git 污染公开历史，进 .gitignore 污染所有 fork 者（历史归档到 ARTIFACTS_FALLBACK_DIR 的快照同样不入库，见第 6 条）
2. 软复用产物沿用固有约定：devlog（~/.codebuddy/dev-logs/{YYYYMMDD}_{类型}_{简述}/devlog.md，tech-doc 实际规范，目录名由 tech-doc 生成规则决定，禁止自拟 <项目>/<分支>/ 结构）、knowledge（~/.codebuddy/knowledge/vue-amazing-ui/）路径由被软复用的 tech-doc / knowledge-loop skill 硬编码，改不得也不该改（零硬依赖原则）
3. 自建产物物理隔离：工作上下文、metrics 放 dev-comp 专属根目录 ~/.codebuddy/dev-comp/（working-context/ + metrics/ + notes/ 子目录；notes/ 放跨分支移交 / 待办类一次性记录，非工作上下文，命名见 references/capability-reuse.md §命名规则）。不与 dev-flow 混放，避免被 dev-flow 的 lint 全量扫描 / dashboard 统计 / 度量闸门校验误伤
4. 命名前缀不变：vaui- 前缀保留，专属目录内按组件检索不受影响
5. 目录自举（写前必建）：~/.codebuddy/dev-comp/ 专属目录首次使用不存在，阶段 0 初始化与阶段 5 写 metrics 前必须 mkdir -p 兜底，禁止假设目录已存在
6. 产物归档（统一运行时目录 · 2026-08-19 固化 · 2026-08-21 修订）：产物一律留在 ~/.codebuddy/ 运行时目录（原位即归档，不搬移、不产生副本）；阶段 5 收尾不弹归档决策，只需在 Gate 5 报告中告知四项产物位置（working-context / metrics / devlog / knowledge）。ARTIFACTS_FALLBACK_DIR 仅保留为历史归档的读取兜底 —— 阶段 0 接续扫描按「运行时目录优先 → 兜底」两级顺序（详见 references/flow.md 阶段 0），命中历史归档时复制回运行时目录恢复活跃状态；该目录不再作为新产物的归档目标

触发规则

优先级：issue-trace（告警硬触发）> 用户显式 dev-flow 命令 > dev-comp > 普通对话。 与 dev-flow 互斥：用户显式用 dev-flow 命令时走 dev-flow；用 dc: / dev-comp 或组件开发意图时走本 skill。二者不同时激活。

6 阶段 + Gate 流程总览

术语约定：antd = Ant Design Vue（官网 https://www.antdv.com/ ），非 React 版 ant.design；本文档中 antdv 与 antd 同义。 每阶段完成后插入一道 🚦 Gate：先输出「阶段完成报告」，再弹 ask_followup_question（✅ 继续 / ⏸️ 暂停 / ⬅️ 回退），未获用户确认不得进入下一阶段。 「一次性走完」仅指不分 P1-Pn（单轮交付），Gate 仍逐阶段必弹，不得跳过。

阶段 0  接续/初始化   → 读/建精简工作上下文 + todo plan + 分阶段决策
阶段 1  准备          → 分支 + 建目录/配置 + 注册占位（含 types/global-components.d.ts 登记）
阶段 2  组件本体      → 对照antdv/naive 源码开发（API 四维 + 渲染分支 + 先搜索复用项目资产）
阶段 3  演示用例      → 完整复制官网用例（顺序一致）+ 双组件对照（src/views/xxx/Index.vue + index.ts）（⚠️ 对照为验收期临时结构，阶段 5 收尾清除）
阶段 4  文档          → docs 复用演示页 + 周边文档联动
阶段 5  验收收尾      → 配置项终检 + 基线全量勾销 + lint+type-check+浏览器对照 → devlog+metrics+knowledge → **清除对照 + 交付前精修**（品牌清零/注释/Props 排序/用例布局/docs 对齐 + 复验）→ smart-commit → 引导发布（合入 main + 构建发布）

各阶段对应 Gate：Gate 0 确认组件名/分阶段计划/参考源/项目特有需求 · Gate 1 确认分支/目录/注册骨架（含全局类型声明登记）· Gate 2 确认功能 + API 四维/渲染分支/Demo 用例对齐清单 · Gate 3 确认演示页完整复制官网用例（顺序一致）+ 双组件对照 · Gate 4 确认文档完整 · Gate 5 配置项终检 + 基线全量勾销 + 交付前精修记录 + 确认验收结果 + 提交。

Gate 报告模板 + 交互式选项定义 → references/flow.md §Gate 门控机制 完整执行规范 → read_file("references/flow.md")

能力复用索引（软复用，零硬依赖 dev-flow）

⚠️ 上述被调 skill 缺失时优雅降级：跳过该环节并一句话提示用户，不阻断主流程。

按需加载索引

核心红线（继承项目规范）

• ❌ 禁止自动 git commit：commit message仅生成，用户明确选择才提交（用 smart-commit）
• ❌ commit 格式：<type>: <description>（无 scope，项目 commitlint scope-empty）
• ❌ 提交前 git 身份实测：git config user.name/email 实测值必须与工作上下文 git_identity 一致，不符拦截、用户决策后继续；提交后 git log -1 --format='%h' 实测 hash 回填（详见 references/flow.md 阶段 5 第 4 步）
• ❌ 先搜索后编码：新增能力前先查项目已有资产（references/reusable-assets.md）
• ✅ 实现方式复用优先级：项目已有组件/功能/样式/布局/逻辑 > antdv 源码实现 > naive 源码实现 > 自研；组件库已有的功能/样式/布局/逻辑优先复用，禁止重新开发（详见 references/reference-sources.md）
• ✅ 主题 light/dark 双份；链式访问用可选链 ?.；禁 any；SSR 安全（禁裸用 window/document）
• ✅ 大组件分阶段交付（P1-Pn），避免半成品
• ✅ 验收标准：演示页与antdv/naive 真身并排 1:1 对照（本项目组件在左/上，官网组件在右/下）+ 用例顺序符合已确认排序锚点（默认官网序，见 refine-spec.md §4.1）+ 浏览器实测（⚠️ 对照仅为验收手段：阶段 3 引入 → 阶段 5 浏览器实测验收 → 验收完成后由阶段 5 第 5 步清除，演示页回归纯本库组件）
• ✅ 清单即验收基线：阶段 2 对齐清单（API 四维 + 渲染分支 + Demo 用例）+ naive 差异登记 + 阶段 0 项目特有需求 = 阶段 5 验收唯一对账标准，Gate 5 全量回显勾销，❌ 项必带处置码（延后 P{n} / 不覆盖（理由） / 待用户确认），禁止摘要式报告
• ✅ 联动清单即注册基线：references/linkage-map.md 是「新增组件全量联动点」唯一权威源（含 ⭐ 易遗漏点：style-deps.ts 四张表（D 方案单一数据源，含复合组件逐子组件登记）/ 组件总数 4 处 / components.d.ts 幽灵声明 / App.vue 孤儿变量 / ⑮ types/global-components.d.ts 全局类型声明登记）。阶段 1/4/5 逐项勾销，禁止靠记忆「顺手补几处」；确定性 grep 自检已收拢于 scripts/validate-component.sh（Gate 5 必跑），宣告完成前必须实测
• ✅ 配置项终检即发布基线：references/checklists.md §发布前配置项终检 是阶段 5 验收时固定配置项（代码注册/文档联动/残留清理/一致性/组件规范/交付前精修）的唯一权威源，Gate 5 必须全量逐项回显勾销 + grep 自检实测；埋入阶段（1/4）的检查不能替代终检，发布前必须全量回检
• ✅ 品牌信息 0 残留红线（脚本 C5 拦截）：交付物不得残留 antdv / naive 的品牌内容与信息——库名（antdv/antd/ant-design-vue/Ant Design Vue/naive/naive-ui）、<a-xxx> 真身标签、avalue*·aoptions*·antdTheme 等残留，以及注释里的来源标注——含一切「不点名」的指代（参考实现 / 参考库 / 参考源码 / 真身 / 官网、「与参考实现同口径」等，2026-10-10 补充）；处置只有「删除」或「改为本项目自身口径陈述」两种，「改中性表述」不属合规做法；范围含 docs 全部内容（组件文档 + changelog/features/index）、组件源码、演示页、单测、根级 README。两段口径（⚠️ 兼容分批开发/分批提交）=「①本分支净改动新增行（git diff <base> 基点→当前工作区，一次覆盖已提交的每一批 + 未提交改动）②未跟踪新增文件全文」（存量不追溯）——只查工作区会漏掉已提交的批次，base 取 --base / 工作上下文 base_ref / merge-base 主干（指定或登记的 ref 无法解析时脚本给「C5 判定不完整」WARN 并回显该 ref——此 WARN ≠ 通过，须核对 ref 后重跑）；净改动为 0 但已提交批次仍有残留时会 WARN「删除须随本次 commit 提交，否则复活」。处置：品牌对比/差异说明类内容（docs「与 XX 的差异」段落、changelog「对齐 XX」说明）整段直接删除、不保留。例外：@ant-design/* 基础包（图标/色板）不清除。详见 references/refine-spec.md §1
• ✅ 交付前精修必做（阶段 5 第 5 步，红线）：范围 = 四来源（refine-spec.md §0.1）——组件源码 / 演示页 / docs / git 已提交批次；起手先取范围清单：git diff --name-only <base> + git ls-files --others --exclude-standard（脚本 G0 已按三载体分类输出），一次覆盖「已提交的每一批 + 未提交改动」；❌ 只看工作区 git diff 在分批提交场景会整段漏检已提交批次，❌ 范围与本轮改动面无关（本轮没改的载体也要逐项过）。每次组件开发收尾都要①组件源码注释与空行精修（三层结构 / 删复述与过期注释 / 删品牌来源标注 / 删 Props·Slots·类型对象·withDefaults 内空行与连续空行，见 refine-spec.md §2.4）②Props 排序（六段式分组 → 双向绑定→内容数据→形态外观→状态反馈→行为交互→进阶透传，段内语义相邻；增量属性插入所属段、❌ 禁追末尾；源码顺序 ≡ docs ## APIs 表顺序）③演示用例排序与布局（排序锚点先确认，见 refine-spec.md §4.1：A 官网保序＝默认，官网用例保序 / 新增插回原序 / 特有用例归末尾；B 合理性优先＝用户明确「无需对齐官网」时启用，主题聚簇 + 由浅入深 / 特有用例就近插入；单例整块 / 多例并排 / 交互类全宽，同类型布局一致）④docs ↔ views 用例对齐（数量/顺序/标题逐字）+ 三方一致性对照（源码↔docs↔views 全维度）。⚠️ 结论为「无需改动」也必须附逐载体核对证据（逐层 / 逐区结论），grep 抽检 ≠ 精修。精修属实质改动 → 必须复验（lint + type-check + 浏览器实测）。权威源 references/refine-spec.md，脚本 G0/C5/G2/G4 拦截
• ✅ 验收完成 ≠ 任务结束：验收通过后按 references/release-flow.md 引导「合入 main（GitHub PR）→ main 上构建发布（pnpm pub，执行前用户逐条确认）→ 发布后清理（删 feat 分支）」；❌ 严禁在 feat 分支上执行发布；用户本轮不发布则写入工作上下文接续指引
• ✅ 组件规范红线（权威源 development/component-design.md，脚本 F1-F3 / F9 拦截）：插槽类型 export interface {组件名}Slots + defineSlots<{组件名}Slots>()（⚠️ 无插槽组件豁免——内部渲染内核等无 <slot/useSlotsExist/$slots 的 .vue 不强制声明；复合组件逐 .vue 校验）；根类名 = {组件名}-wrap（❌ 禁 m- / vui- 等自拟前缀）；Props/Slots 注释禁写 string | slot；useSlotsExist 只传实际使用的插槽名；源码不留多余空行——interface Props / {组件名}Slots / 类型对象 / withDefaults 内部字段紧邻排列（❌ 不用空行分段），全文件无连续空行（refine-spec.md §2.4 / §3.2.4）
• ✅ 全局类型声明必登记（脚本 F5 拦截）：新增组件 / 复合子组件 / Provider 必须在 types/global-components.d.ts 登记（linkage-map.md §⑮）——⚠️ 漏登记不报错、pnpm type-check 仍 PASS，属静默失效，只能靠脚本兜底
• ✅ 对齐维度 = API 四维 + 渲染分支 + Demo 用例（三者缺一不可）：必须读参考库渲染实现逐分支核对（字符串/VNode/空值兜底/双源优先级/数组归一/falsy 边界），差异显式决策并登记（详见 reference-sources.md §渲染分支与兜底逻辑对齐）
• ✅ 演示页红线（脚本 F7/F8 拦截）：分区按已确认排序锚点排列（默认官网原序，锚点定义见 refine-spec.md §4.1），但标题与 script 注释不带数字序号；本项目组件无需 import（全局注册，直接写 <Xxx> 标签）
• ✅ changelog 红线（脚本 F6 拦截）：版本章节唯一且严格递减；条目链接用站内相对路径 + 实测目录名（kebab）；## future 清单同步删除已落地组件；package.json 与 changelog 双处一致（changelog-spec.md §3.4）
• ✅ 文档红线（脚本 B5/B6/B7/B8/B9/B10 拦截）：## APIs 必有且含 ### {组件名} Props 子标题；## Events / ## Methods 按组件实际能力（有 emit / defineExpose 才写）；尾部章节顺序固定 APIs → Slots → Events → Methods → CSS 变量 → 在 setup 外使用（章节可缺省、相对顺序不可变，Methods 恒在 Events 之后收尾；项目侧 pnpm verify:docs-order 同口径）；类型列写真实 TS 类型（❌ 禁 string | slot）；## Slots 表列头「名称 | 说明 | 用法」+ 用法列 v-slot:xxx；pnpm verify:docs 第 ③ 项机械校验 Show Code 自包含（块内引用标识符必须有定义）与跨分节 v-model 绑定独立
• ✅ docs 表格红线（权威源 references/doc-tables-spec.md，脚本 B9 拦截）：全部表格首列统一「名称」（❌ 禁「参数 / 字段 / 属性名」）；组件 Props 表标题 ### {组件名} Props（复合组件逐子组件）；类型章节标题 = 属性表引用的公开导出名 + Type（### TabsItem Type，❌ 不再用 SFC 内部名 ### Item Type），改名须同步页内锚点；列数按结构分流——类型表只有两种（2026-10-23 修订二取消 4 列）：有字段（接口 / 回调 / 实例信息）3 列（名称/说明/类型）、无字段（别名/联合/枚举）2 列（名称/值），❌ 类型表不用「默认值」列；必填标记：Props 表用 <Tag color="red">required</Tag> 标签（与 v-model 标签同款，并存时 v-model 在前）+ 默认值列 — 双标记，❌ 不用 ?；类型表 3 列才用 ?（与源码 interface 逐字段一致，含 extends 继承字段）；默认值列（仅 Props / Params 表）—（em dash）表示必填/无缺省、undefined 表示可选未传，❌ 禁 ASCII -；联合类型统一 |；表格带首尾管道（修订旧「紧凑写法」约定，存量不追溯）；类型表紧跟唯一引用它的表格所在章节（只被 Methods 引用的放 ## Methods 下）；## CSS 变量 表固定 3 列「名称 / 说明 / 默认值」