test(release): 补充迁移主题与 Token 消费验证

.agents/skills/tdesign-flutter-general/SKILL.md

@@ -76,7 +76,7 @@ Skills 按职责补充规范：本 skill 管通用协作与 CI 登记；[`tdesig
 
 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` 与 `tdesign-site/site/docs/getting-started.md`。改动根目录 README 时副本会随之同步。
+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 校验生成片段，变化只能来自源文件，不能直接修改产物。
 

AGENTS.md

@@ -23,7 +23,7 @@
 4. **Spec 规范对齐**：组件 API 变更 / 重构 / 跨目录改动按 [`specs/README.md`](./specs/README.md) 创建 Spec，提交代码须与 Spec 行为契约一致并同步更新。注意**「是否需要 Spec」与「是否需要更新日志」是两件独立的事**：Spec 看改动复杂度 / 是否碰公共契约，更新日志看用户是否感知。**最容易出错**：行为不变的纯内部重构**要 Spec**（属于重构）但**不写更新日志**。四种情况详见 `.agents/skills/tdesign-flutter-general/SKILL.md`「何时创建 Spec / 何时写更新日志」一节。
 5. **Flutter 双版本兼容**：同时兼容 `flutter@3.32.0` 与 `flutter@latest`。
 6. **breaking change 分析**：组件改动时判断是否改变公开 API 签名 / 默认行为 / 删除能力。
-7. **脚本生成的产物（供 AI 理解，贡献者无需关注）**：`API 文档`（`sh ./demo_tool/all_build.sh` → `example/assets/api/*.md`）、`示例代码片段`（`dart run tool/generate_example_code.dart` → `example/assets/code/*.txt`）、`README 副本`（`node scripts/sync-readme.mjs` → `tdesign-component/README*.md` 与 `tdesign-site/site/docs/getting-started.md`）均由脚本从源码生成，`.github/workflows/autofix.yml` 会在 PR 时自动运行并修正，**贡献者无需关注**；AI 需理解这些脚本做什么，改动相关源文件后产物会由 CI 自动重新生成，必要时可手动运行并一并提交（详见 `.agents/skills/tdesign-flutter-general/SKILL.md`「脚本生成的产物」一节）。
+7. **脚本生成的产物（供 AI 理解，贡献者无需关注）**：`API 文档`（`sh ./demo_tool/all_build.sh` → `example/assets/api/*.md`）、`示例代码片段`（`dart run tool/generate_example_code.dart` → `example/assets/code/*.txt`）、`README 副本`（`node scripts/sync-readme.mjs` → `tdesign-component/README*.md` 和 `tdesign-component/MIGRATION.md`（用户指南源在 `tdesign-site/site/docs/`））均由脚本从源码生成，`.github/workflows/autofix.yml` 会在 PR 时自动运行并修正，**贡献者无需关注**；AI 需理解这些脚本做什么，改动相关源文件后产物会由 CI 自动重新生成，必要时可手动运行并一并提交（详见 `.agents/skills/tdesign-flutter-general/SKILL.md`「脚本生成的产物」一节）。
 8. **文档与注释**：组件公开 API 的 `///` dartdoc 注释就是用户文档，改动公开 API 时须随代码同步更新注释；复杂需求 / 重构按 Spec 记录设计；PR「更新日志」只写用户可感知的变更；`CHANGELOG.md` 由 CLI 生成勿手动编辑（详见 `.agents/skills/tdesign-flutter-general/SKILL.md`「文档来源与注释规范」一节）。
 9. **代码质量 / lint 零告警**：提交前须过 `flutter analyze`（0 error / 0 warning），能用 `const`/`final` 的地方必须用、避免 lambda 替代 tear-off、遵循 `directives_ordering` 等，全部对齐 `analysis_options.yaml`；CI 的 `.cnb.yml` 已加 analyze 兜底（详见 `.agents/skills/tdesign-flutter-general/SKILL.md`「代码质量 / lint 零告警」一节）。
 

CONTRIBUTING.md

@@ -1,8 +1,8 @@
-# CONTRIBUTING
+# 贡献指南
 
-> **本文档是 `tdesign-flutter` 仓库开发 / 协作 / PR / 更新日志规范的唯一事实来源**。
-> 其他文档（`AGENTS.md` 入口索引、`.agents/skills/.../SKILL.md`、`specs/README.md`）如需引用，统一指向本文档，避免重复维护。
-> - Spec 专项规范 → [`specs/README.md`](./specs/README.md)
+感谢参与 TDesign Flutter。本文介绍本地开发、编码规范、问题反馈、Pull Request 提交和验收流程。
+
+涉及公共 API、组件行为或跨目录改动时，请先阅读[设计方案与验收记录规范](./specs/README.md)，并随实现维护相应记录。
 
 ## 目录结构
 
@@ -16,6 +16,20 @@ tdesign-component/
 tdesign-site/       // tdesign flutter 站点
 ```
 
+## 本地开发
+
+同时兼容 Flutter 3.32.0 与当前稳定版本。先安装目标 SDK，在仓库根目录执行：
+
+```bash
+cd tdesign-component
+flutter pub get
+cd example
+flutter pub get
+flutter run
+```
+
+在目标 Android/iOS 设备、模拟器或适用的 Web 环境运行。站点开发与右侧 Flutter Web 预览统一见[站点开发说明](./tdesign-site/README.md)，避免在此重复维护命令和端口配置。
+
 ## 开发规范
 
 - TD 内置视觉和行为只接受受支持的组件实例配置、TD ThemeExtension 与 Token；外部 Material/M2/M3 默认及显式主题不作为隐式入口。内部原生能力可以使用，但其视觉、反馈、触发和选择配置由 TD 明确。保留 TD 显式定制、调用方自定义内容的主题、文本选择和原生编辑、反馈、触发、焦点、键盘与无障碍能力。内部原生控件局部隔离视觉，不重置用户内容树，不因防范样式干扰删除原生能力。
@@ -41,6 +55,27 @@ tdesign-site/       // tdesign flutter 站点
 
 即 PR 正文形态为「完整模板 + 打勾 + 填写」，与模板逐行对应、无删减、无缺漏。
 
+## 领取 Issue
+
+### 一个 Issue 的完整流程
+
+- 用户发现功能不满足，查看 API 文档确认不支持，然后提 Issue。[常见问题](https://tdesign.tencent.com/flutter/faq)
+- 提了 Issue 后，在群里发出 Issue 链接，方便后续直接沟通，确认详细需求。然后将最终确认结果贴到 GitHub 的 Issue 上。
+- 负责人评估开发工作量，打 `help want` 和 `issueShoot` 标签。
+- 贡献者确认要领取，在 Issue 下评论领取，并通知负责人。负责人打上 `Received` 标签，讨论确认实现方案。
+- 贡献者参考开发规范开发完功能，按照文档自检，然后提 PR，并同步负责人验收。
+- PR 自动构建测试包。【自动构建流水线】
+- 负责人拉设计一起视觉走查（如果需要的话），走查完成后，合并 PR。Issue 打上下一个版本的标签。
+- 版本发布后，Issue 关闭。
+
+### 标签管理
+
+- 无标签：未评估
+- `issueShoot`：已评工作量，可领取
+- `Received`：已领取
+- `pre_x.x.x`：预计某个版本发布
+- `x.x.x`：某个版本已发布
+
 ## PR 关联 Issue
 
 Issue 的**主阵地是 GitHub**。CNB 是镜像平台，其 Issue 与 GitHub Issue 是两套体系、编号 / 状态不同步，因此：
@@ -57,14 +92,14 @@ PR 描述「更新日志」小节是**面向实际使用方的用户**的本次
 1. **只记录用户可感知的变更**：仅当本次改动会改变用户在使用组件 / 库时能观察到的行为（如 API、样式、交互、性能、体验等）时才写入更新日志；从用户角度描述具体变化，标注可能的 breaking change。
 2. **内部 / CI 改动不写日志**：纯内部实现、CI/CD 配置、文档结构调整、重构（行为不变）等**用户无需感知**的改动，**不应凭空生成更新日志**，而是勾选「本条 PR 不需要纳入 Changelog」，避免产生无用日志。判断标准是：**这个用户在使用产品时能否感知到这次变化？** 感知不到就不写。
 3. **组件 PR 不单列 Demo 配套改动**：组件 PR 的更新日志只描述组件 / 库使用方在实际接入中可感知的行为变化。Demo 页面布局、示例文案、示例代码、Golden 和测试等配套改动，即使在示例中可见，也不单独写入 Changelog；应写在「需求背景和解决方案」中，并按实际情况勾选「演示代码改进」或「测试用例」。同一 PR 同时修改组件与其 Demo 时，更新日志只保留组件行为条目。此规则不影响以文档、站点或示例应用本身为交付目标的独立 PR 按实际受众判断更新日志。
-4. **「不写更新日志」≠「不需要 Spec」**：二者由两套独立标准触发，不能互相推导（详见 [`specs/README.md`](./specs/README.md)）。**判断口诀**：要不要 **Spec** 看「改动复杂度 / 碰不碰公共契约」（面向开发者）；要不要**更新日志**看「用户感不感知」（面向用户）。两轴交叉即四种情况：
+4. **分别判断 Spec 与更新日志的要求**：两者用途不同，应独立评估。
 
-   | 用户是否可感知 ↓ | 可感知 | 无感 |
-   | --- | --- | --- |
-   | 碰组件 / 公共契约（要 Spec） | **两者都要** | **只要 Spec**、不写日志（纯内部重构） |
-   | 不碰组件（纯文档 / 依赖 / CI） | （罕见）只要日志 | **两者都不需要** |
+   **Spec 用于说明设计与验收。** 公共 API 或行为契约变更、复杂需求、组件重构及跨目录改动，应按 [Spec 规范](./specs/README.md)创建或更新设计与验收记录。简单文案、格式调整和单文件局部修改通常不需要完整 Spec，具体由 Review 结合改动范围确认。
+
+   **更新日志用于说明用户可感知的变化。** 公开接口、行为、样式等变化应记录；行为不变的内部重构、CI 配置和文档结构整理无需单列更新日志，在 PR 中说明即可。
+
+   例如，组件内部重构可能需要 Spec，但无需更新日志；公开 API 变更通常两者都需要。勾选“本条 PR 不需要纳入 Changelog”仅说明无需更新日志，不影响 Spec 的要求。
 
-   **最容易出错**：把"勾选「本条 PR 不需要纳入 Changelog」"等同于"不需要 Spec"。行为不变的纯内部重构（用户无感、不写日志）仍属于组件修改，**需要 Spec**（Review 结合实际改动判定）但**不写更新日志**。
 5. **一个 PR 含多个功能 / 修复时，必须按条目分开列写**，不能合并成一条笼统描述。
 6. 每条遵循 Conventional Commits 的 commit type，**与最终分组（CHANGELOG 章节）固定对应**，写日志按实际 type 归入对应分组：
 
@@ -122,12 +157,6 @@ dart run tool/run_visual_regression.dart
 
 调度器自测会检查组件名唯一、各类测试能力完整、登记文件存在，以及 GitHub/CNB 使用公共 runner。CI job 成功仅代表数组中已登记的测试通过；测试文件存在、Golden 已提交或本地单独运行通过，均不能替代 CI 回归登记。
 
-## 贡献指南
-
-请参考：[贡献指南](https://tdesign.tencent.com/flutter/develop)
-
-复杂需求、公共 API 变更、组件重构和跨目录改动请先阅读并创建对应的 [Spec](./specs/README.md)；是否可以不创建 Spec，由 Review 根据实际改动判断。
-
 ## Spec 贡献流程
 
 复杂需求、公共 API 变更、组件重构和跨目录改动，请按 [`specs/README.md`](./specs/README.md) 的完整流程创建并维护 Spec：
@@ -138,3 +167,28 @@ dart run tool/run_visual_regression.dart
 4. 提交 PR 时，在正文附上 Spec 目录链接；PR 描述「更新日志」须与 Spec 描述一致（格式见上文「PR 更新日志规范」）。
 
 简单文案、格式调整和单文件局部修改不要求创建完整 Spec。Spec 只描述设计和验收，不替代代码、测试或生成文档。
+
+## 人工验收与合并
+
+- 检查真实操作、布局溢出、明暗主题、英文环境、文字缩放和适用的焦点/键盘/无障碍能力。
+- 在 Example App 检查对应API和代码查看入口；文档有误时修复源码注释、组件清单或示例源码，再重新生成，勿手工修改产物。
+- 测试包或预览构建成功后，根据PR中的构建结果完成适用的Android/iOS验收；构建失败应先检查实际日志。
+- 视觉改动由负责人协调设计走查，并附目标、状态、平台与版本证据。Golden要求见[组件Review规范](./.agents/skills/tdesign-component-align-review/SKILL.md)。
+- Issue验收完成后由负责人合并PR；更新发布版本标签，正式发布后关闭对应Issue。
+
+## 文档维护
+
+| 内容 | 唯一来源 | 使用与生成方式 |
+|---|---|---|
+| 项目介绍和最短示例 | 根README.md、README_zh_CN.md | 中英文分别维护，包内副本生成 |
+| 安装、主题（含明暗模式）、国际化、FAQ、迁移 | tdesign-site/site/docs/ | 站点直接读取，迁移另生成包内MIGRATION.md |
+| 贡献规范 | 本文件 | 站点直接读取并适配页面元信息与相对链接 |
+| 站点开发方式 | [tdesign-site/README.md](./tdesign-site/README.md) | 其他说明链接到此处 |
+| API | lib中的公开dartdoc注释 | 生成example/assets/api，站点和示例App共用 |
+| 示例 | example/lib中的标注源码 | 生成example/assets/code，站点和示例App共用 |
+| 设计决策与验收 | specs/ | 保留历史证据，现行用户用法写入用户指南 |
+| 发布流程与记录 | PUBLISH.md及既有CHANGELOG生成入口 | 发布步骤与历史记录分开维护 |
+
+执行 `node scripts/sync-readme.mjs` 更新迁移、主题及国际化指南中的可运行示例片段和包内副本；执行 `node scripts/sync-readme.mjs --check` 只检查，不改文件。包内副本顶部标注来源，不手工修改。站点普通指南使用小写连字符命名，迁移文件名写清起止版本。
+
+新增指南后在站点导航登记；内部文档链接使用相对路径，站点渲染时转换为既有路由，包内副本转换为可访问的线上入口。完整文档来源和边界见[整理记录](./specs/062-documentation-source-consolidation/spec.md)。