📄 本页由源文件
skills/dev-comp/SKILL.md自动投影生成（单一权威源）。请勿直接编辑本页。
dev-comp
定位：vue-amazing-ui 单组件开发迭代领域 SOP。 架构：轻量领域流程 + 软复用 dev-flow 能力模块。全程❌ 不产生
.flow锁、❌ 不走 dev-flow 重型门控（.validated物理检查点 / JSON 逐步校验 / 门控 subagent / post-step 脚本 / 工具门禁）；✅ 仅保留轻量交互式 Gate——每阶段完成后输出「阶段完成报告」并弹ask_followup_question，等用户确认再进入下一阶段（详见「6 阶段 + Gate 流程总览」）；✅ 另配 1 个轻量校验脚本scripts/validate-component.sh承载 Gate 5 确定性检查（A/B/C/E/F 配置项 + S 提交红线，设计哲学「确定性用代码」，详见「能力复用索引」）。
⚙️ 个人化配置区（复用/分享时只改这一块）
本 skill 核心流程通用；下列配置换人换机时只需填 4 个本地路径，其余保持默认即可。
必填（首次使用前填写；ARTIFACTS_FALLBACK_DIR 可留空）
| 配置项 | 填写你的本地路径 | 说明 |
|---|---|---|
PROJECT_ROOT | ~/myGithub/vue-amazing-ui | 组件库项目根 |
REF_ANTDV_LOCAL | ~/myGithub/ant-design-vue | Ant Design Vue 本地 clone 路径（留空则降级用官网） |
REF_NAIVE_LOCAL | ~/myGithub/naive-ui | Naive UI 本地 clone 路径（留空则降级用官网） |
ARTIFACTS_FALLBACK_DIR | ~/myGithub/ai-coding-kit/skills/dev-comp/artifacts/ | 产物归档兜底目录（用户将产物归档到 skill 下时使用；留空则仅扫 ~/.codebuddy/ 运行时目录） |
默认可用（无需修改）
| 配置项 | 当前值 | 说明 |
|---|---|---|
REF_ANTDV_GH | https://github.com/vueComponent/ant-design-vue | Ant Design Vue GitHub |
REF_NAIVE_GH | https://github.com/tusen-ai/naive-ui | Naive UI GitHub |
REF_ANTDV_DOC | https://www.antdv.com/components/overview-cn/ | antdv 官网 |
REF_NAIVE_DOC | https://www.naiveui.com/zh-CN/os-theme/docs/introduction | naive 官网 |
CAP_WORKING_CONTEXT_DIR | ~/.codebuddy/dev-comp/working-context/ | 工作上下文目录（dev-comp 专属） |
CAP_METRICS_DIR | ~/.codebuddy/dev-comp/metrics/ | 度量报告目录（dev-comp 专属） |
本地 clone 不存在时：降级为仅用官网（web_fetch）参考，并提示用户可clone 以获得源码级复用。
📋 项目规范权威源（必读 · 2026-09-15 新增）
项目内已有面向贡献者的设计规范（
{PROJECT_ROOT}/development/），是组件实现的权威源；本 skill 只做「引用 + 增量补充」，禁止另起平行规则。 ⚠️ 本 skill 的 checklist / 模板 / 脚本与项目规范冲突时，以项目规范为准，并立即回填本 skill（单向断链是历史欠账的根因，见rules/按需-Skill设计-跨文件协作.mdc§2.1）。映射表详见references/project-map.md§项目规范权威源索引。
| 必读文件 | 关键内容 | 对应阶段 |
|---|---|---|
development/component-design.md | SFC 三段式 / export interface Props / defineSlots + <组件名>Slots / 主题注入 / 样式与 CSS 变量 / 根类名 {组件名}-wrap | 1-2 |
development/import-export.md | 三层导出模型 / 组件 index.ts 三件套 / 新增组件「三步接线」Checklist / resolver 四张表 | 1 |
development/demo-doc-guide.md | 演示页结构 / 自动路由 / 组件文档模板 / 侧边栏维护 / 演示与文档必须一致 | 3-4 |
development/project-structure.md | 顶层目录职责 / 命名规范速查 | 1/3/4 |
development/build-system.md | 三产物构建（dist / es / lib）/ 别名与模块解析 | 5（发布） |
types/global-components.d.ts | 手工维护的自有组件全局类型声明 → 新增组件必登记（⚠️ 漏登记不报错、pnpm type-check 仍 PASS，见 linkage-map.md §⑮） | 1 |
📦 产物存储设计原则（2026-08-18 固化 · 2026-08-19 补充归档兜底）
决策背景：深入评估过「产物入仓库」方案，被开源仓库 git 污染 + dev-flow 生态路径硬绑定否决。产物默认留在
~/.codebuddy/（第 1-5 条，2026-08-18 固化）；2026-08-19 按用户决策补充第 6 条——用户可显式选择归档到 skill 下artifacts/目录（skill 内置skills/dev-comp/.gitignore忽略artifacts/内容、保留artifacts/README.md，私有产物不会污染仓库 git 历史；⚠️ 换仓库分发本 skill 时须连同该.gitignore一起复制，否则归档产物有入仓库风险），本小节固化六条原则，防止后续迭代被顺手改回。
- 产物不入仓库：vue-amazing-ui 是开源项目，工作上下文/对齐清单/决策记录/度量是个人私有开发过程，进 git 污染公开历史，进
.gitignore污染所有 fork 者（用户主动归档到ARTIFACTS_FALLBACK_DIR的快照除外，见第 6 条） - 软复用产物沿用固有约定：devlog（
~/.codebuddy/dev-logs/{YYYYMMDD}_{类型}_{简述}/devlog.md，tech-doc 实际规范，目录名由 tech-doc 生成规则决定，禁止自拟<项目>/<分支>/结构）、knowledge（~/.codebuddy/knowledge/vue-amazing-ui/）路径由被软复用的 tech-doc / knowledge-loop skill 硬编码，改不得也不该改（零硬依赖原则） - 自建产物物理隔离：工作上下文、metrics 放 dev-comp 专属根目录
~/.codebuddy/dev-comp/（working-context/+metrics/子目录）。不与 dev-flow 混放，避免被 dev-flow 的 lint 全量扫描 / dashboard 统计 / 度量闸门校验误伤 - 命名前缀不变：
vaui-前缀保留，专属目录内按组件检索不受影响 - 目录自举（写前必建）：
~/.codebuddy/dev-comp/专属目录首次使用不存在，阶段 0 初始化与阶段 5 写 metrics 前必须mkdir -p兜底，禁止假设目录已存在 - 产物归档与接续兜底（2026-08-19 固化 · 2026-08-20 修订为收尾固定步骤）：产物默认留在
~/.codebuddy/运行时目录（原位即归档，无需额外动作）；阶段 5 收尾时必弹ask_followup_question由用户决策归档目标（固定步骤，禁止跳过）——A 保留~/.codebuddy/运行时目录（默认）/ B 归档到ARTIFACTS_FALLBACK_DIR并删除运行时副本（禁止双份，归档保留为快照）。归档到 B 后，阶段 0 接续扫描按「运行时目录优先 →ARTIFACTS_FALLBACK_DIR兜底」两级顺序（详见references/flow.md阶段 0），命中归档时复制回运行时目录恢复活跃状态
触发规则
| 信号 | 行为 |
|---|---|
dc:（技能名 dev-comp 也生效） | 进入 dev-comp，提示指定组件名 |
dc: {组件名} / dc: 开发 Menu | 进入，开发指定组件 |
dc:status / dc:st | 查看当前组件进度 |
仅输入 dc:（无后续） | 提示补充组件名 |
组件开发 / 开发 {X} 组件 / 完善 {X} 组件 / 补全 {X} 组件 | 进入 dev-comp |
| 仅提及组件但无开发意图（如"看看 Menu 怎么实现的"） | 不触发，普通对话 |
优先级：incident-triage（告警硬触发）> 用户显式 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 → 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）
| 能力 | 复用方式 | 何时用 | 详见 |
|---|---|---|---|
| 工作上下文 | 自建精简版模板 | 阶段 0 建/接续 | templates/working-context-lite.tpl.md |
| plan | todo_write 工具 | 阶段 0 列计划 | — |
| 开发日志 | use_skill('tech-doc') | 阶段 5 收尾 | references/capability-reuse.md |
| 度量采集 | 自建精简 YAML | 阶段 5 收尾 | templates/metrics-lite.tpl.yaml |
| 知识沉淀 | use_skill('knowledge-loop') | 阶段 2 检索 / 阶段 5 沉淀 | references/capability-reuse.md |
| 提交 | use_skill('smart-commit') | 阶段 5 提交 | references/capability-reuse.md |
| 交互验收 e2e | use_skill('e2e-testing')（可选） | 阶段 5 关键交互用例 | references/checklists.md §交互操作清单 |
| 配置项终检 + 提交红线校验 | scripts/validate-component.sh（本 skill 自带） | 阶段 5 收尾必跑（Gate 5 数据源） | references/checklists.md §发布前配置项终检 |
⚠️ 上述被调 skill 缺失时优雅降级：跳过该环节并一句话提示用户，不阻断主流程。
按需加载索引
| 场景 | 加载文件 |
|---|---|
| 执行任一阶段 | references/flow.md |
| 项目规范权威源映射 / 项目结构/注册链路 | references/project-map.md |
| 参考源路径 + antdv/naive 取舍 + 渲染分支对齐 | references/reference-sources.md |
| 找可复用的项目已有资产 | references/reusable-assets.md |
| 全链路 checklist（含 F 类组件规范）+ 发布前配置项终检 | references/checklists.md |
| 新增组件联动配置地图（⭐易遗漏点全集，含 ⑮ 全局类型声明） | references/linkage-map.md |
| 用例标题/简介描述规范（权威源 + 同步） | references/demo-description.md |
| changelog 编写规范（版本号升级 + 双处同步 + 章节唯一性） | references/changelog-spec.md |
| 发布流程（合入 main + 构建发布 + 清理） | references/release-flow.md |
| 如何软复用 dev-flow 能力 + 降级 | references/capability-reuse.md |
核心红线（继承项目规范）
- ❌ 禁止自动
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 对照（本项目组件在左/上，官网组件在右/下）+ 用例顺序与官网一致 + 浏览器实测（⚠️ 对照仅为验收手段：阶段 3 引入 → 阶段 5 浏览器实测验收 → 验收完成后由阶段 5 第 5 步清除，演示页回归纯本库组件）
- ✅ 清单即验收基线：阶段 2 对齐清单（API 四维 + 渲染分支 + Demo 用例）+ naive 差异登记 + 阶段 0 项目特有需求 = 阶段 5 验收唯一对账标准，Gate 5 全量回显勾销，❌ 项必带处置码（
延后 P{n}/不覆盖（理由）/待用户确认），禁止摘要式报告 - ✅ 联动清单即注册基线：
references/linkage-map.md是「新增组件全量联动点」唯一权威源（含 ⭐ 易遗漏点：resolver 依赖映射 / 组件总数 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）的检查不能替代终检，发布前必须全量回检 - ✅ 验收完成 ≠ 任务结束：验收通过后按
references/release-flow.md引导「合入 main（GitHub PR）→ main 上构建发布（pnpm pub，执行前用户逐条确认）→ 发布后清理（删 feat 分支）」；❌ 严禁在 feat 分支上执行发布；用户本轮不发布则写入工作上下文接续指引 - ✅ 组件规范红线（权威源
development/component-design.md，脚本 F1-F3 拦截）：插槽类型export interface {组件名}Slots+defineSlots<{组件名}Slots>()；根类名 ={组件名}-wrap（❌ 禁m-/vui-等自拟前缀）；Props/Slots 注释禁写string | slot；useSlotsExist只传实际使用的插槽名 - ✅ 全局类型声明必登记（脚本 F5 拦截）：新增组件 / 复合子组件 / Provider 必须在
types/global-components.d.ts登记（linkage-map.md§⑮）——⚠️ 漏登记不报错、pnpm type-check仍 PASS，属静默失效，只能靠脚本兜底 - ✅ 对齐维度 = API 四维 + 渲染分支 + Demo 用例（三者缺一不可）：必须读参考库渲染实现逐分支核对（字符串/VNode/空值兜底/双源优先级/数组归一/falsy 边界），差异显式决策并登记（详见
reference-sources.md§渲染分支与兜底逻辑对齐） - ✅ 演示页红线（脚本 F7/F8 拦截）：分区按官网原序排列，但标题与 script 注释不带数字序号；本项目组件无需 import（全局注册，直接写
<Xxx>标签） - ✅ changelog 红线（脚本 F6 拦截）：版本章节唯一且严格递减；条目链接用站内相对路径 + 实测目录名（kebab）；
## future清单同步删除已落地组件；package.json与 changelog 双处一致（changelog-spec.md§3.4） - ✅ 文档红线（脚本 B5/B6/B7 拦截）：
## APIs必有且含### {组件名}子标题；## Events/## Methods按组件实际能力（有 emit /defineExpose才写）；类型列写真实 TS 类型（❌ 禁string | slot）