| name | tdesign-flutter-general |
| description | TDesign Flutter 仓库面向所有 AI 助手（通用 Codex / Cursor 等）的通用协作约定，重点给出「何时创建 Spec」与「何时写更新日志」的判断规则（含每次组件修改 / 简单外部改动 / 用户可感知行为的四种情况），以及 Flutter 3.32.0 与 latest 双版本兼容、组件 breaking change 分析、文档来源与注释规范、代码质量 / lint 零告警等平台无关约定。平台无关规范以 CONTRIBUTING.md / specs/README.md 为唯一事实来源，本文档只做面向 AI 的落地提炼；CNB 平台专属执行细则见 .agents/skills/tdesign-flutter-conventions/SKILL.md。 |
TDesign Flutter 仓库通用协作约定（AI 版）
本文档面向所有在本仓库工作的 AI 助手（通用 Codex / Cursor，以及 CNB 平台 NPC），提供平台无关的协作约定提炼。通用规范的唯一事实来源是 CONTRIBUTING.md 与 specs/README.md，本文档只做面向 AI 的落地提炼，不重复维护权威内容；CNB 平台专属细则（分支命名 cnb-issue-<issue.number>、PR 不携带 Issue 编号等）见 .agents/skills/tdesign-flutter-conventions/SKILL.md。
一、何时创建 Spec / 何时写更新日志（核心判断规则）
「是否需要 Spec」与「是否需要更新日志」是两件独立的事，由两套不同标准触发，不能互相推导：
- 要不要 Spec → 看改动复杂度 / 是否碰公共契约（面向开发者 / 维护者）。
- 要不要写更新日志 → 看用户感不感知得到（面向用户，只写用户可感知的变更）。
两轴交叉即四种情况（完整细则见 CONTRIBUTING.md「PR 更新日志规范」）：
| 用户是否可感知 ↓ | 可感知 | 无感 |
|---|
| 碰组件 / 公共契约（要 Spec） | 两者都要 | 只要 Spec、不写日志（纯内部重构） |
| 不碰组件（纯文档 / 依赖 / CI） | （罕见）只要日志 | 两者都不需要 |
最容易出错：把"勾选「本条 PR 不需要纳入 Changelog」"等同于"不需要 Spec"——这是错误的。行为不变的纯内部重构（用户无感、不写日志）仍属于组件修改，需要 Spec（Review 结合实际改动判定，属于重构）。
一句话记忆：Spec 看"改动复不复杂 / 碰不碰公共契约"，更新日志看"用户感不感知得到"。
二、提交 PR 与更新日志格式
-
PR 正文完整保留 .github/PULL_REQUEST_TEMPLATE.md 原模板结构（所有勾选项含未选 [ ]、所有 HTML 注释原样保留），只打勾 / 填写，不删减。
-
更新日志条目遵循 Conventional Commits 的 commit type，与最终分组固定对应（完整见 CONTRIBUTING.md）：
| commit type | 最终分组 | 示例 |
|---|
breaking | Breaking Changes | breaking(toast): 调整 xxx 默认行为 |
feat | Features | feat(TButton): 新增渐变背景能力 |
fix | Bug Fixes | fix(TInput): 修复密文模式下无法粘贴的问题 |
perf、refactor | Performance | refactor(toast): 优化 xxx |
docs | Documentation | docs: 更新主题生成器文档 |
其他（chore 等） | Others | chore: 升级依赖 |
-
Breaking change 一律用 breaking commit type（如 - breaking(toast): 调整 xxx 默认行为），自动归入 Breaking Changes 分组。
-
tdesign-component/CHANGELOG.md 由 CLI 自动生成，无需人工维护。
三、Spec 流程
复杂需求 / 公共 API 变更 / 组件重构 / 跨目录改动，按 specs/README.md 创建 specs/<编号>-<短名称>/（spec / plan / tasks / acceptance）；提交代码须与 Spec 行为契约一致，方案变更先更新 Spec 再改代码。单行文案、格式调整、简单局部修复不要求。
四、Flutter 双版本兼容
同时兼容 flutter@3.32.0 与 flutter@latest（stable 最新版）。改动时确认所用 API 在两版本均可用且行为一致，避免 low 版不可用 / high 版已移除；结论中标注对两版本的兼容性影响。
五、组件变更的 breaking change 分析
- 改公开 API 签名 / 默认行为 / 删除能力 → breaking change，需重点提示并评估迁移策略。
- 仅新增可选参数且不改变既有行为，通常不算 breaking；新增必填参数或改变默认值需谨慎。
- 涉及公共 API 变更 / 组件重构时按规范创建 Spec。
- 输出时明确：是 / 否 breaking change、影响范围、受影响 API、迁移建议。
六、文档来源与注释规范（注释即文档）
| 文档载体 | 职责 | 何时维护 |
|---|
dartdoc 注释（///） | 组件公开 API 的用户文档 | 新增 / 修改公开 API 时必须同步 |
| Spec | 复杂需求 / 重构的设计文档 | 见「何时创建 Spec / 何时写更新日志」一节，先 Spec 后代码 |
| PR 更新日志 | 面向使用方用户的变更说明 | 见「何时创建 Spec / 何时写更新日志」一节，只写用户可感知的变更 |
| CHANGELOG.md | 由 CLI 自动生成 | 不手动编辑 |
| CONTRIBUTING.md / specs/README.md | 规范唯一事实来源 | 需引用时统一指向 |
公开字段 / 参数 / 回调 / 枚举 / 类的 /// 注释要写清"是什么、默认值、生效条件、三态语义、与相关字段关系"，注释必须与实现一致。
七、脚本生成的产物（供 AI 理解，贡献者无需关注）
本仓库的 API 文档、示例代码片段、README 副本 均由脚本从源码生成，.github/workflows/autofix.yml 会在 PR 时自动运行这些脚本并提交修正，因此贡献者（人类）无需手动关注 / 运行它们。但 AI 助手需要理解每个脚本具体做什么，以便在改动相关源文件时知道哪些产物是自动生成的、是否需要手动运行或校验：
- API 文档：
sh ./demo_tool/all_build.sh（等价 node tool/generate_api.mjs，manifest 驱动），从组件 API 生成 example/assets/api/<component>_api.md；新增 / 迁移组件时先更新 tool/components.json。改动设计 / 组件 API 时该产物会随之变化。
- 示例代码片段：
dart run tool/generate_example_code.dart，从带 @ExampleCode 注解的示例方法生成 example/assets/code/*.txt；CI 用 --check 校验片段与源码同步。改动示例方法时该产物会随之变化。
- README 副本：
node scripts/sync-readme.mjs，把根目录 README.md / README_zh_CN.md 同步到 tdesign-component/README*.md 与 tdesign-site/site/docs/getting-started.md。改动根目录 README 时副本会随之同步。
这些脚本由 CI 自动兜底，不要把它们当作面向贡献者的提交要求；若 AI 在改动相关源文件后需要产物立即可用或校验同步，可手动运行对应脚本，产物与源码一并提交即可。
八、组件测试与 CI 回归门禁
仓库使用集中式回归调度器，新增组件或为既有组件新增测试时，须按 CONTRIBUTING.md「组件测试与 CI 回归门禁」登记：
- 组件测试文件加入
tool/run_component_regression.dart 的 componentTestSuites；
- 生产源码范围加入
tool/check_component_coverage.dart 的 componentTargets，手写生产 Dart 行覆盖率 LH/LF >= 95%；
- Demo 结构与 Golden 测试加入
tool/run_visual_regression.dart 的 visualTestSuites；
- 运行调度器自测，确认三个清单同步且登记文件存在。
测试文件存在、Golden 已提交或本地单独运行通过，不代表 CI 已执行；必须读取 CI 实际入口并确认测试已被调度。
九、代码质量 / lint 零告警
提交前过 flutter analyze，目标 0 error / 0 warning。能用 const 必须 const、优先 final、避免 lambda 代替 tear-off、遵循 directives_ordering、统一单引号、优先集合字面量、用 .isEmpty/.isNotEmpty 判空、统一 ${param} 插值，全部对齐 tdesign-component/analysis_options.yaml；CI 的 .cnb.yml 已加 analyze 兜底。
回答风格
- 回答使用与提问相同的语言（中文 / 英文）。
- 结论先行，给出明确判断，再附必要依据与可操作建议。
- 需要执行平台操作（建分支、提 PR、评论等）时，先核对仓库协作规范再动手。
