wot-ui 组件文档迁移技能
本技能用于将组件文档迁移到统一新规范，覆盖 API 对齐、Demo 结构统一、Attributes/Options 表结构迁移与最低版本标记迁移。
默认遵循 wot-ui-component-baseline 中的共享约束。
何时使用
- 用户要求“迁移某组件文档到新规范”。
- 用户要求“按 Demo 规则整理文档中的示例章节”。
- 用户要求“将最低版本并入参数列、合并说明与可选值列”。
何时不要使用
- 用户只要求核对 props、events、slots、methods 是否准确，且未要求改文档结构。
以上场景应优先使用 check-doc-component-consistency。
目标输出
- 文档 API 与组件实现一致：Attributes / Events(Emits) / Slots / Methods。
- Demo 章节与演示页组织顺序一致，满足
create-demo-page规则。 - Attributes/Options 表结构迁移完成，版本标记迁移到参数列。
- 产出差异清单、修改说明与验证结果。
核心规则
1) API 一致性核对
- 组件源码核对范围：
- props：
types.ts、defineProps、默认值 - emits：
defineEmits与模板事件转发 - slots：模板
<slot>与具名插槽 - methods：
defineExpose暴露方法
- props：
- 文档核对范围：
## Attributes## Events## Slots## Methods（若无对外方法可省略）
- 差异处理原则：
- 文档缺失：补齐
- 文档冗余：删除
- 命名不一致：统一为组件真实 API 命名
2) Demo 顺序与分组规范
- Demo 内容来源必须以“对应组件 demo 页面 + 组件源码能力”为准，不凭主观补充或删减。
- 先对齐
src/subPages/<component>/Index.vue的示例能力，再与组件 props/slots/events/methods 交叉校验覆盖面。 - 使用
create-demo-page作为默认基线顺序与命名规则，但允许按组件语义做自适应调整。 - 若文档存在介绍性章节（如适用场景、使用前说明、平台差异、注意事项），应保留在 Demo 分组之前，不强制重排。
- 当进入 Demo 能力展示区时，章节顺序、标题口径、可选分组启用方式均复用
create-demo-page，不要重复定义另一套规则。 - 若组件存在强语义能力分组（如“异步流程”“平台能力”“业务模式”），可插入到最贴近语义的位置，并在迁移说明中记录原因。
- 同类顺序保持稳定：
primary -> success -> info -> warning -> danger。
3) Attributes / Options 表迁移
- 目标列结构：
参数 | 说明 | 类型 | 默认值。 - 迁移规则：
- 合并“说明 + 可选值”到说明列。
- “最低版本”迁移到参数列后缀。
- 支持识别版本标记语法
^(x.y.z)并在构建时转换为 Badge。
- 文档编写要求：
- 不手写
<Badge />或<el-tag />。 - 使用约定标记，由文档插件统一转换。
- 可选值统一写法：在说明列使用“可选值为
a、b、c”，不使用a / b / c斜杠串写。 - 示例代码尽量同时提供
vue/html与ts两段，保证可直接复现。 - 多段示例优先使用
::: code-group组织（如“模板/脚本”分组），提升可读性。 - 当示例非常长、影响阅读体验时，使用
::: details折叠长代码。
- 不手写
执行步骤
- 识别目标组件与文档文件路径。
- 核对源码 API（props/emits/slots/methods）与文档章节差异。
- 以对应 demo 页面与组件源码能力为基准抽取示例，再保留组件介绍性章节，按
create-demo-page基线与组件语义重排 Demo 章节顺序与命名，并按“vue/html + ts”成对补齐示例。 - 迁移 Attributes/Options 表：列合并、最低版本迁移到参数列。
- 应用版本标记约定（例如
^(1.3.6)）。 - 运行诊断与文档构建验证，输出剩余问题。
验收清单
- API 四要素核对完成且文档与源码一致。
- Demo 示例均可追溯到对应 demo 页面与组件真实能力。
- Demo 分组顺序符合“create-demo-page 基线 + 组件语义自适应”规则。
- Attributes/Options 已完成列合并与最低版本迁移。
- 未手写组件标签，版本标签由约定格式生成。
- 当前改动无新增语法或构建错误。
示例触发语句
- “帮我把 button 文档迁移到新规范并对齐源码”
- “按 demo 规范整理 calendar 文档示例顺序”
- “把最低版本并到参数列，说明和可选值合并”