القائمة
TDesign Flutter 仓库面向 CNB 平台 NPC 的执行约定（基于 Issue 创建分支的 cnb-issue-<issue.number> 命名、PR 模板填写、close
يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.
اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.
npx skills add https://github.com/Tencent/tdesign-flutter --skill tdesign-flutter-conventionsيبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
عرض SKILL.md
| name | tdesign-flutter-conventions |
| description | TDesign Flutter 仓库面向 CNB 平台 NPC 的执行约定（基于 Issue 创建分支的 cnb-issue-<issue.number> 命名、PR 模板填写、close |
本 skill 是 CNB 平台 NPC 在本仓库执行任务时遵循的执行约定。通用开发 / 协作 / Spec 规范以 CONTRIBUTING.md 与 specs/README.md 为准，平台无关的落地提炼见通用 skill ../tdesign-flutter-general/SKILL.md（含「何时建 Spec / 何时写更新日志」四种情况、Flutter 双版本、breaking change、文档注释、lint 等），本文档只补充 CNB 平台 NPC 特有的细则、不重复通用规则。
在创建 PR / 分支时，必须严格遵守以下分支命名约定。
与 AGENTS.md 的区别：本 skill 是 CNB 平台专属约定，能获取到 CNB 平台的 Issue 编号，因此基于 Issue 创建时使用
cnb-issue-<issue.number>格式；而 AGENTS.md 面向无法获取 CNB Issue 编号的通用 AI 工具（Codex / Cursor 等），故统一使用不携带 Issue 编号的通用格式<cnb.username/>/<types>/<功能需求>。两者不冲突：CNB 平台上的 NPC 以本 skill 为准，通用工具以 AGENTS.md 为准。
<cnb.username/>/cnb-issue-<issue.number>/<types>/<功能需求>
<cnb.username/>：当前操作者的 CNB 用户名（不要猜测，通过环境变量或平台信息获取）。cnb-issue-<issue.number>：固定前缀 cnb-issue- + 所关联 Issue 的编号，用于把分支 / PR 与具体需求绑定、便于回溯，并明确标识该需求来源于 CNB Issue。<types>：改动类型，从以下取值中选择一个最贴切的：
feat：新特性 / 新组件fix：缺陷修复docs：文档改进refactor：重构（不改变行为）chore：构建、工具、依赖等杂项ci：CI/CD 相关改动test：测试用例style：样式 / 交互改进release：版本发布<功能需求>：用简短、小写、以连字符分隔的英文短语描述本次改动要解决的功能需求。rss1102/cnb-issue-31/fix/branch-auto-close-issue、rss1102/cnb-issue-22/feat/add-badge-component<cnb.username/>/<types>/<功能需求>
rss1102/chore/update-ci-config。type(scope): 修改描述，scope 可填写组件、文档或 CI 模块，例如 fix(TButton): 修复按钮溢出问题。提交 PR 时，必须遵守当前项目预设的 PR 模板 .github/PULL_REQUEST_TEMPLATE.md，并逐项补充完整内容：
[ ]）与所有 HTML 注释（<!-- ... -->）一律原样保留在正文内，填写内容写在对应位置；各小节标题与勾选规则说明不得省略。详细规则见 CONTRIBUTING.md 的「PR 描述模板」小节。[x]、未选中的 [ ]）。tdesign-component/CHANGELOG.md 由 CLI 自动生成，无需人工维护。PR 描述「更新日志」小节面向实际使用方的用户（目标受众是用户，而非开发者 / 维护者），只记录用户可感知的变更；纯内部实现、CI/CD 配置、文档结构调整、重构（行为不变）等用户无需感知的改动，不要凭空生成更新日志，直接勾选「本条 PR 不需要纳入 Changelog」。一个 PR 含多个用户可感知变更时按条分开列写，完整格式规则（含 commit type 与最终分组对应表）见 CONTRIBUTING.md 的「PR 更新日志规范」。breaking commit type（如 - breaking(toast): 调整 xxx 默认行为），自动归入 CHANGELOG 的 Breaking Changes 分组。其余 type 的对应关系见 CONTRIBUTING.md「PR 更新日志规范」或通用 skill「提交 PR 与更新日志格式」一节。CNB 平台生成的 PR 不携带任何 Issue 编号（CNB 的 Issue 与 GitHub Issue 是两套体系，关联可能不一致 / 冲突），且不写任何差异 / 关联提示，正文内容仅按 .github/PULL_REQUEST_TEMPLATE.md 原始模板填写：
close #CNB_ISSUE_NUMBER，也不在正文任何小节写明 CNB Issue 编号，避免与 GitHub 侧冲突、造成两边状态不同步。close #xx 指向 GitHub Issue 的关联在 GitHub 对应的 PR 中填写，合并后由 GitHub 自动关闭对应 Issue；该关联与 CNB 侧无关。涉及组件 API 变更、重构、跨目录改动时，须与 specs/ 保持一致，完整流程见 specs/README.md 与 CONTRIBUTING.md 的 Spec 贡献流程。要点：
specs/<编号>-<短名称>/；单行文案、格式调整、简单局部修复不要求。spec.md 定义的行为契约与验收标准；Review 时同时核对实现与 Spec 是否相符。「是否需要 Spec」与「是否需要更新日志」由两套不同标准触发，不能互相推导：Spec 看「改动复杂度 / 碰公共契约」，更新日志看「用户感不感知」。四种情况的完整判断见通用 skill ../tdesign-flutter-general/SKILL.md「何时创建 Spec / 何时写更新日志」一节，此处不重复。
最容易出错：把"勾选「本条 PR 不需要纳入 Changelog」"等同于"不需要 Spec"。行为不变的纯内部重构（用户无感、不写日志）仍可能需要 Spec（属于重构，Review 结合实际改动判定）。
tdesign-flutter 需同时兼容 flutter@3.32.0 与 flutter@latest（stable 通道最新版），通用判断规则见通用 skill ../tdesign-flutter-general/SKILL.md「Flutter 双版本兼容」一节。CNB 平台落地要点：
flutter@3.32.0：项目基线版本，pubspec.yaml 声明 flutter: ">=3.32.0"，.fvmrc 固定为 3.32.0。flutter@latest：stable 通道最新版本，用于前瞻性兼容。通用判断规则（是否改公开 API 签名 / 默认行为 / 删除能力、迁移策略等）见通用 skill「组件变更的 breaking change 分析」一节。CNB 平台落地时：涉及公共 API 变更或组件重构须创建对应 Spec，并在 PR 自查清单勾选「已添加对应的 Spec 链接」；若为 breaking change，更新日志用 breaking commit type（见第二节）。
本仓库的"文档"有明确来源与分工，改动组件时须先弄清楚每条文档该写在哪，避免重复维护与分叉（通用规则见通用 skill「文档来源与注释规范」一节，此处列 CNB 平台落地时的速查）：
| 文档载体 | 职责 | CNB 平台何时维护 |
|---|---|---|
dartdoc 注释（///） | 组件公开 API 的用户文档 | 新增 / 修改公开 API 时必须同步，与代码同一次提交 |
Spec（specs/<编号>-<短名称>/） | 复杂需求 / 重构 / 公共 API 变更的设计文档 | 见第四节，先 Spec 后代码，方案变更时同步更新 |
| PR 更新日志 | 面向使用方用户的变更说明 | 见第二节，只记录用户可感知的变更 |
| CHANGELOG.md | 由 CLI 自动生成 | 不手动编辑 |
| CONTRIBUTING.md / specs/README.md | 规范唯一事实来源 | 需引用时统一指向，避免重复维护 |
API 文档、示例代码片段、README 副本 均由脚本从源码生成，.github/workflows/autofix.yml 会在 PR 时自动运行并提交修正，贡献者（人类）无需关注。各脚本具体做什么见通用 skill「脚本生成的产物」一节，此处不重复。
CNB 平台落地要点：AI 需理解这些脚本的用途（改动 API / 示例 / README 后相关产物会由 CI 自动重新生成）；若需要产物立即可用或校验同步，可手动运行对应脚本并把产物与源码一并提交，但不要当作面向贡献者的提交要求。
通用自查清单（const/final、tear-off、directives_ordering、单引号、集合字面量、字符串插值等，对齐 tdesign-component/analysis_options.yaml）见通用 skill「代码质量 / lint 零告警」一节。CNB 平台落地要点：lint 零告警是硬性门槛，skill / 约定属软约束，只有 CI 的 flutter analyze（.cnb.yml，--fatal-infos）才是机器硬门槛；提交前在本地跑 cd tdesign-component && flutter analyze 确认无告警再提交。
