| name | issue-fix-entry |
| description | 一键启动 Tencent/tdesign-flutter 的 GitHub issue 修复流程。适用于用户提供 issue 链接或编号并说「按 harness 修 issue」「一键 issue」「开始修 issue」等场景；串联贡献指南、requirements 模板初始化、强制检查与 PR 收尾。 |
Issue 修复一键入口
收到 issue 链接或编号后，不要先写代码。按下面顺序执行；详细步骤与规范说明见同目录下的 issue-fix-workflow/SKILL.md。
0. 前置检查（必做）
- 若工作区有与当前 issue 无关的未提交改动，先向用户确认是暂存、另分支还是继续。
- 确认可执行：
gh、git、node；能访问 GitHub（gh issue view 成功）。
1. 加载贡献指南（必做）
2. 拉取 issue 并定分支名（必做）
gh issue view <ISSUE_NUMBER> --repo Tencent/tdesign-flutter
从标题提炼 slug（小写、连字符），分支名建议：
fix/issue-<ISSUE_NUMBER>-<slug>
创建并切换分支：
git fetch origin develop
git checkout -b fix/issue-<ISSUE_NUMBER>-<slug> origin/develop
（若团队约定从其他分支拉取，以用户或仓库约定为准。）
3. 初始化 requirements 骨架（必做）
将占位符换成实际值后执行：
node scripts/issue-workflow/init-issue-fix.mjs \
--issue-number <ISSUE_NUMBER> \
--issue-url "https://github.com/Tencent/tdesign-flutter/issues/<ISSUE_NUMBER>" \
--issue-title "<从 gh issue view 复制的标题>" \
--slug "<slug>" \
--component "<组件名或主题，如 TFab>"
若目录已存在且需覆盖，加 --force。
4. 执行完整修复流程（必做）
从这一步起，严格按 issue-fix-workflow/SKILL.md 执行，包括：
- 在
TaskContract.md、test-cases.md 中写清根因、方案与用例后再改代码。
- 实现与验证分两条：单元/集成测试（
tdesign-component/test/ 等，保证逻辑与回归）与 示例验收（ExamplePage(..., test: [...]) 中的 ExampleItem，便于人工走查；后者不替代前者）；另有 API 与文档源时一并处理；不要手改 tdesign-site/src/**/README.md。
- 按需委托子代理：
issue-analyst、flutter-issue-reviewer、code-review、acceptance-writer（见 .harness/cursor/agents/）。建议：check-issue-fix.mjs 通过后再委托 code-review 做 checklist 复审。
5. 强制检查（必做，未通过不得收尾）
按实际路径传入 --requirements-dir 与 --component-file 等：
node scripts/issue-workflow/check-issue-fix.mjs \
--requirements-dir requirements/issue-<ISSUE_NUMBER>-<slug> \
--component-file tdesign-component/lib/src/components/<path>/<file>.dart \
--class-name <ClassName> \
--all-build tdesign-component/demo_tool/all_build.sh \
--require-all-build-class
说明：若本次未新增需在 all_build.sh 中登记的类，可去掉 --require-all-build-class（以贡献指南 5.3 为准）。
检查失败则修代码或文档后重新运行，直至通过。
5.1 Checklist 复审（强烈建议）
强制检查通过后，委托 code-review 子代理（.harness/cursor/agents/code-review.md）对照贡献指南与 workflow 全量 checklist 复审，并把结论写入 requirements/issue-*/code-review-report.md。脚本不会校验 ExamplePage.test 等项。
6. 同步 harness 到 Cursor（若刚改过 .harness）
node scripts/init-cursor-harness.mjs
7. 提交与 PR（必做）
- 提交信息建议：
fix(<scope>): <简述> (fixes #<ISSUE_NUMBER>) 或团队约定格式。
- PR 目标分支默认
develop；正文使用 requirements/issue-*/pr-body.md，结构与 .harness/templates/issue-fix/pr-body.md.tpl 一致，并遵守 rules/core/github-pr.mdc：按实际勾选 PR 性质、补全后删除 <!-- --> 说明注释、提 PR 前完成自查清单全部勾选。
- PR 中关联 issue（链接或
fixes #xxx）。
- 不要手工修改
tdesign-site/src/**/README.md（站点打包生成物），见 rules/site/site-docs.mdc。
7.1 优先自动发起 PR
在 commit 已就绪的前提下，应先尝试 git push -u origin <修复分支>，再 gh pr create --base develop --head <修复分支> --title "..." --body-file requirements/issue-*/pr-body.md（分支已有 PR 时用 gh pr view 取链接即可）。仅当 push 或 gh pr create 失败时，再在回复中说明原因并给出用户需在本地完成的步骤（登录 gh、配置 fork、网页创建 PR 等）。成功时必须向用户交付 PR 链接。
7.2 PR 提交后的下一步建议
成功发起 PR 并给出链接后，收尾时务必向用户补充：等待该 PR 流水线构建 demo APK（或仓库文档中的等价产物）完成 → 下载安装做走查验收 → 若有问题在 PR / issue 反馈并继续修改迭代。详细表述见 issue-fix-workflow/SKILL.md 中的「PR 提交后的下一步建议」。
一键记忆口诀
读 issue → 开分支 → init requirements → 按 workflow 改 → check 通过 → code-review checklist → 提交并尽量自动开 PR（失败再提示本地操作）→ 提醒等待 demo APK 安装验收与反馈闭环。
