AI 协作规范

文档定位

本文档不是给 AI 工具做关键词提示的说明卡，而是给 Ez-UI 组件项目成员使用的内部协作规范。其目标是：

• 统一组件开发、示例维护、文档维护、评审、发版时的 AI 使用方式
• 降低组件实现、示例代码、文档描述之间的不一致风险
• 让每类任务都有明确输入、执行流程、输出格式和验收标准
• 避免 AI 生成“看起来完成，实际上不可发布”的结果

适用对象

本文档适用于以下角色：

• 组件开发人员
• 文档与示例维护人员
• Code Review 参与者
• 发版验收人员
• 使用 AI 辅助分析、修改、回归检查的协作成员

适用范围

• 组件源码维护
• 文档示例维护
• 文档与示例同步更新
• 发布前自检与评审

不适用于以下场景：

• 通用编程学习资料编写
• 与本仓库无关的 AI 使用建议整理
• 替代产品决策、交互决策或发布审批

基本原则

Ez-UI 项目内使用 AI 时，默认遵循以下原则：

• 先理解现有实现，再提出修改，不允许跳过上下文直接改代码
• 先保证行为正确，再考虑抽象收敛，不允许为了“更优雅”破坏既有稳定路径
• 先保证示例可运行，再补文档表述，不允许文档先行但示例失真
• 先做最小必要改动，再考虑结构优化，不允许借题发挥式重构
• 先给验证结果，再给结论，不允许只给方案不做检查
• 对外 API、示例路径、文档入口的变更必须显式说明影响范围

角色职责

组件开发人员

组件开发场景下，AI 输出至少要覆盖：

• 变更目标和问题根因
• 影响到的组件、类型、导出面、样式或插槽边界
• 最小可行实现，而不是额外捆绑无关重构
• 修改后的验证结果，包括错误检查、构建或关键行为回归

组件开发人员不能把以下事项交给 AI 直接替代：

• 未明确边界的 API 设计拍板
• 兼容性承诺判断
• 发布风险接受判断

文档与示例维护人员

文档或示例变更时，AI 输出必须覆盖：

• 示例是否仍可运行
• 文档描述是否与示例一致
• 中英文页面是否同步
• 目录、sidebar、引用链接是否同步更新

Code Review 参与者

AI 用于 review 时，必须优先输出问题，而不是优先输出实现建议。标准结构固定为：

1. Findings：按严重级别排序的问题列表
2. Open Questions：需要进一步确认的前提
3. Summary：变更摘要与潜在回归面

如果没有发现问题，必须明确写出“未发现明确问题”，并补充残余风险或验证盲区。

发版验收人员

AI 可以辅助发版检查，但不能替代最终放行决策。输出必须包括：

• 已执行检查项
• 仍未验证的范围
• 可发布结论及其前提

任务分类与标准流程

1. 修复组件问题

处理流程：

1. 先确认复现现象和触发条件
2. 再定位是组件内部问题、示例问题、文档误导还是组合使用问题
3. 优先修根因，不优先加临时补丁
4. 修改后验证关键回归路径

最小交付要求：

• 问题原因
• 修改点
• 回归风险
• 验证结果

2. 修改组件 API 或行为

处理流程：

1. 明确是增强、修复还是破坏性变更
2. 检查类型声明、组件导出、安装入口、Nuxt 集成、示例引用是否受影响
3. 同步修改文档描述和示例用法
4. 标注兼容性影响

最小交付要求：

• 变更影响说明
• 受影响文件列表
• 类型和文档同步结果
• 构建或错误检查结果

3. 修改文档或示例

处理流程：

1. 先确认示例是否是当前推荐路径
2. 再确认文档描述是否已经偏离真实实现
3. 以可运行示例为准回写文档
4. 同步处理中英文页面与导航入口

最小交付要求：

• 变更后的推荐用法
• 示例和文档是否同步
• 中英文是否同步
• 是否存在死链风险

4. 执行 Review

处理流程：

1. 先识别行为变化
2. 再检查类型、示例、文档、边界场景
3. 最后再讨论实现建议

禁止输出：

• 先讲方案，后找问题
• 只有总结，没有 findings
• 把风格偏好当成缺陷

5. 执行发版检查

处理流程：

1. 检查组件构建
2. 检查文档构建
3. 检查关键示例
4. 检查错误面板或静态错误
5. 检查文档导航和中英文入口

如果任一关键检查未完成，结论只能写“暂不建议发版”或“有条件可发版”，不能直接给出稳定结论。

仓库特定规则

以下规则来自 Ez-UI 当前仓库的真实约束，优先级高于泛化建议。

表格与布局

• 涉及 fixed 列时，其余数据列应显式声明 width 或 min-width
• 不要把 doLayout 当成默认补救手段，只有确认布局时机问题时才考虑
• 表格错位问题必须同时检查列配置、父容器布局、固定列和内容宽度

类型与示例

• 示例优先使用强类型写法，避免不必要的 as unknown as 断言
• FastTable 相关示例若出现模板推断退化，优先检查 createTypedFastTable 之类的类型绑定方式
• 示例不是演示草稿，必须代表当前推荐用法

查询、分页与行为语义

• 涉及分页、查询、排序时，行为语义应与 search/query/reset/changePage 文档保持一致
• Query/Reset 的行为边界必须在示例和文档中一致，不允许一个重置参数、另一个只重置 UI
• 对于 CRUD 查询区，优先保持真实常见用法，不用少见抽象替代主路径

组件封装边界

• 组件封装遵循默认透传、最小拦截，不重复封装底层完整 API
• 如果一个封装只是把底层 API 再包一层但没有稳定收益，应谨慎新增
• 不要为了单个示例成立，就把不常见组合抬升为默认推荐架构

文档同步

• 组件行为变更时，必须同步更新中英文文档
• 示例代码与文档描述不一致时，以可运行示例为准并回写文档
• 删除页面时必须同步修改 sidebar，避免产生死链
• 文档新增策略优先写成可验收规则，避免纯口号描述

AI 输出要求

实现类任务输出

至少包含以下信息：

• 修改了什么
• 为什么这样改
• 影响了哪些文件或模块
• 做了哪些验证
• 还有哪些未验证项

Review 类任务输出

必须按以下顺序：

1. Findings
2. Open Questions
3. Summary

发版类任务输出

至少包含：

• 已执行检查项
• 未执行检查项
• 当前阻塞项
• 是否建议发版

禁止事项与常见反例

以下做法在本项目中默认不被接受：

• 没有先看上下文就直接修改组件
• 只改中文文档，不改英文文档
• 只改示例，不改说明文档
• fixed 列存在时不给其他列补宽度
• 只给实现方案，不做任何验证
• 为了暂时通过展示效果加入没有边界说明的 hack
• 把一次性场景包装成长期默认 API
• 评审时只做概述，不给具体问题定位

发版前门槛

满足以下条件，才能进入发布流程：

1. 组件库构建通过
2. 文档构建通过
3. 关键示例可运行且无明显 UI 错位
4. 全量错误检查为 0，或已有明确可接受说明
5. 中英文文档入口无失效链接
6. 破坏性变更已在文档或变更说明中明确指出

如果存在未验证范围，必须在发版结论中显式列出，不能以“理论上没问题”替代验证结果。

文档维护机制

当出现以下情况时，应同步更新本规范：

• 仓库新增一类高频任务模式
• 组件架构边界发生变化
• 发布流程或验收门槛变化
• 团队在多个任务中反复踩到同类问题

维护原则：

• 优先补充可执行规则，不优先追加口号
• 优先沉淀已验证经验，不优先写推测性建议
• 中英文页面应在同一轮修改中保持一致

快速识别关键词

以下关键词可作为任务路由提示，但不能替代完整上下文分析：

• 文档错位 表格错位 fixed 列 列宽：优先检查列配置、fixed 列、容器布局与 doLayout 触发时机
• 类型报错 slot row TableColumn createTypedFastTable：优先检查泛型绑定与模板推断是否退化
• 发版 可发布 稳定性：优先执行构建检查、文档构建和关键示例回归
• 回归 review 验收：优先输出按严重级别排序的问题列表，而不是先给方案

与仓库级规则的关系

当前文档属于 docs 范围的项目协作规范，用于团队内部知识对齐与执行约束。

若后续需要让 AI 工具在仓库级自动优先命中，可新增仓库级规则入口文件，并与本文档保持互链，但不应以仓库级规则替代本页的项目执行细则。