TDesign Flutter 仓库通用协作约定（AI 版）

本文档面向所有在本仓库工作的 AI 助手（通用 Codex / Cursor，以及 CNB 平台 NPC），提供平台无关的协作约定提炼。通用规范的唯一事实来源是 CONTRIBUTING.md 与 specs/README.md，本文只做面向 AI 的落地提炼。

Skills 按职责补充规范：本 skill 管通用协作与 CI 登记；tdesign-component-align-review 管 Demo、API、Theme 与验收证据。CNB 静态约定见 .cnb/CONTRIBUTING.md，按该文档的适用范围读取，不作为通用 skill 加载。遇到冲突先核对规范本体与用户当前要求，不通过叠加规则扩大任务范围。

一、何时创建 Spec / 何时写更新日志（核心判断规则）

「是否需要 Spec」与「是否需要更新日志」是两件独立的事，由两套不同标准触发，不能互相推导：

• 要不要 Spec → 看改动复杂度 / 是否碰公共契约（面向开发者 / 维护者）。
• 要不要写更新日志 → 看用户感不感知得到（面向用户，只写用户可感知的变更）。

两轴交叉即四种情况（完整细则见 CONTRIBUTING.md「PR 更新日志规范」）：

用户是否可感知 ↓	可感知	无感
复杂需求 / 公共契约变更 / 组件重构 / 跨目录改动（需 Spec）	两者都要	只要 Spec、不写日志
简单局部修复 / 文案 / 格式等（无需完整 Spec）	只要日志	两者都不需要

最容易出错：把"勾选「本条 PR 不需要纳入 Changelog」"等同于"不需要 Spec"——这是错误的。行为不变的纯内部重构（用户无感、不写日志）仍属于组件修改，需要 Spec（Review 结合实际改动判定，属于重构）。

二、提交 PR 与更新日志格式

• PR 标题遵循 Conventional Commits：type(scope): 描述；分支及平台约定按 AGENTS.md 的入口读取。

• PR 正文完整保留 .github/PULL_REQUEST_TEMPLATE.md 原模板结构（所有勾选项含未选 [ ]、所有 HTML 注释原样保留），只打勾 / 填写，不删减。

• 生成组件 PR 的 Changelog 时，组件与 Demo 同改只保留组件行为条目；Demo 配套改动写在「需求背景和解决方案」并勾选对应 PR 性质。完整边界及独立交付例外见 CONTRIBUTING.md「PR 更新日志规范」。

• 更新日志条目遵循 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 流程

第一节判定需要 Spec 后，按 specs/README.md 创建或更新对应 specs/<编号>-<短名称>/（spec / plan / tasks / acceptance）；提交代码须与 Spec 行为契约一致，方案变更先更新 Spec 再改代码，并在 PR 附对应目录链接。

四、Flutter 双版本兼容

同时兼容 flutter@3.32.0 与 flutter@latest（stable 最新版）。改动时确认所用 API 在两版本均可用且行为一致，避免 low 版不可用 / high 版已移除；结论中标注对两版本的兼容性影响。

五、组件变更的 breaking change 分析

• 改公开 API 签名 / 默认行为 / 删除能力 → breaking change，需重点提示并评估迁移策略。
• 仅新增可选参数且不改变既有行为，通常不算 breaking；新增必填参数或改变默认值需谨慎。
• 输出时明确：是 / 否 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 助手需要理解每个脚本具体做什么，以便在改动相关源文件时知道哪些产物是自动生成的、是否需要手动运行或校验：

1. API 文档：sh ./demo_tool/all_build.sh（等价 node tool/generate_api.mjs，manifest 驱动），从组件 API 生成 example/assets/api/<component>_api.md；新增 / 迁移组件时先更新 tool/components.json。改动设计 / 组件 API 时该产物会随之变化。
2. 示例代码片段：dart run tool/generate_example_code.dart，从带 @ExampleCode 注解的示例方法生成 example/assets/code/*.txt；CI 用 --check 校验片段与源码同步。改动示例方法时该产物会随之变化。
3. README 副本：node scripts/sync-readme.mjs，把根目录 README.md / README_zh_CN.md 同步到 tdesign-component/README*.md；站点 site/docs/migration-0.2.7-to-1.0.md 是迁移正文源，生成包内 MIGRATION.md。站点快速开始独立维护，不再由 README 生成；--check 只检查同步状态，不写文件。

自动生成与本地验收不是同一件事：贡献者无需手工维护产物；组件对齐任务需要核对示例时，按 Review skill 校验生成片段，变化只能来自源文件，不能直接修改产物。

跨仓库生成工具与 autofix

生成能力来自独立工具仓库时，工具改动与组件改动分别交付；消费仓库不得长期引用工具 PR 分支或临时提交。先让所需工具版本进入消费仓库声明的正式 ref，再在组件最终源码上重新解析依赖、生成并校验产物。工具合并前启动的 CI 仍可能解析到旧版本，不能用稍后发生的工具合并推定该次运行已经生效。

autofix 成功只表示自动修改流程执行成功，不表示提交前的生成产物正确或保持不变。每次 autofix 后读取最新 head 和自动提交 diff，确认没有删除公开 API、回退示例或引入范围外产物；若自动提交改变 head，后续 CI、Review 和合并结论均以新 head 为准。

八、组件测试与 CI 回归门禁

仓库使用集中式回归调度器，新增组件或为既有组件新增测试时，须按 CONTRIBUTING.md「组件测试与 CI 回归门禁」登记：

• 组件测试文件加入 tool/run_component_regression.dart 的 componentTestSuites；
• 生产源码范围加入 tool/check_component_coverage.dart 的 componentTargets，手写生产 Dart 行覆盖率 LH/LF >= 95%；
• Demo 结构、功能与交互测试登记到 GitHub / CNB 的双版本功能回归入口；纯 Golden 测试加入 tool/run_visual_regression.dart 的 visualTestSuites。执行环境与两类测试的分流要求见 Review skill 第 5 节；不得用视觉入口代替功能入口。
• 运行调度器自测，确认三个清单同步且登记文件存在。

测试文件存在、Golden 已提交或本地单独运行通过，不代表 CI 已执行；必须读取 CI 实际入口并确认测试已被调度。

九、代码质量 / lint 零告警

提交前运行 flutter analyze --fatal-infos，要求无诊断问题。能用 const 必须 const、优先 final、避免 lambda 替代 tear-off，并遵循当前 analysis_options.yaml；CI 配置仅证明已设门禁，是否通过需读取实际运行结果。

回答风格

• 回答使用与提问相同的语言（中文 / 英文）。
• 结论先行，给出明确判断，再附必要依据与可操作建议。
• 需要执行平台操作（建分支、提 PR、评论等）时，先核对仓库协作规范再动手。