# Flutter星图

**Repository Path**: app_36/flutter-star-chart

## Basic Information

- **Project Name**: Flutter星图
- **Description**: Flutter星图是一套面向 Flutter 组件工程的智能测试与交付系统，支持自然语言驱动测试、自动回归与可行性交付报告。
- **Primary Language**: Unknown
- **License**: Unlicense
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-20
- **Last Updated**: 2026-06-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Flutter星图

`flutter_components` 是一套面向 Flutter 项目的自动化测试与交付系统，核心目标是：
**让你用更少命令跑通回归、拿到可读结论，并能在 CI 持续门禁。**

## 环境要求

- **Flutter SDK**: `>=3.8.0`（当前锁定 Dart `^3.8.0`，与 `pubspec.yaml` 一致）
- **Dart SDK**: `>=3.8.0 <4.0.0`
- **Android**: Gradle 8.x + AGP 8.x（见 `android/build.gradle`）
- **iOS**: Xcode 15+，CocoaPods 1.15+
- **Python**（后端/契约测试）: `>=3.10`
- **Node.js**（可选，部分工具链）: `>=18`

## 编译步骤

```bash
# 1. 获取依赖
flutter pub get

# 2. 运行代码生成（如有 freezed/json_serializable）
flutter pub run build_runner build --delete-conflicting-outputs

# 3. 编译检查（零 error 门禁）
make compile-check
# 或手动：flutter analyze --no-fatal-infos

# 4. 运行契约测试
make harness-contract

# 5. 运行全量背压（Lint + 契约 + 测试）
make harness
```

## 常见问题解决方案

### Q1: `flutter analyze` 报 `The argument type 'dynamic' can't be assigned to the parameter type 'X'`
- **根因**: 方法参数缺少显式类型声明，Dart 3.8 严格模式（`strict-casts: true`）下推断为 `dynamic`。
- **修复**: 为参数添加具体类型，如 `BuildContext context` 代替 `context`。
- **示例文件**: `lib/components/guide/hk_tip_widget.dart`

### Q2: `return_of_invalid_type_from_closure` — 闭包返回 `dynamic`
- **根因**: 静态工具方法缺少返回类型，导致 `Obx(() => ...)` 等 Widget 闭包推断返回 `dynamic`。
- **修复**: 为工具方法添加返回类型，如 `static Widget sliverGridWrapper(...)`。
- **示例文件**: `lib/utils/hk_layout.dart`

### Q3: `as DecorationImage?` 强制转换报错
- **根因**: `getDecorationImage` 返回类型未声明（推断为 `dynamic`），与 `BoxDecoration.image` 的 `DecorationImage?` 不匹配。
- **修复**: 
  1. 在 `plugins/hk_base/lib/utils.dart` 中给 `getDecorationImage` 添加返回类型 `DecorationImage`；
  2. 移除调用处的 `as DecorationImage?`。
- **示例文件**: `plugins/hk_base/lib/utils.dart`、`lib/pages/home/ranking_list/ranking_list_page.dart`

### Q4: `semanticIndexCallback` 类型不匹配
- **根因**: `SliverChildBuilderDelegate.semanticIndexCallback` 签名为 `int? Function(Widget, int)?`，使用 `_` 时参数类型推断为 `dynamic`。
- **修复**: 显式声明参数类型，如 `(Widget _, int index) => index`。
- **示例文件**: `lib/pages/cases/preload_data/sliver_grid/hk_preload_data_sliver_grid_list.dart`

## 核心功能与亮点

- **Flutter App 核心功能**：提供可复用组件与页面架构能力，支持分页、Sliver/Tab、状态管理与本地插件协作（`hk_base`、`hk_net`、`flutter_ui`）。
- **AI 治理能力**：基于 Rules + Skills + AGENTS 协议形成统一研发约束，覆盖架构规范、测试规范、CI 门禁、代码优化与协作流程。
- **自动化测试能力**：支持 Agentic `smoke/full/explore` 回归、结构化轨迹（`operation_trace.jsonl`）、真实截图/视频证据链、PyQt5 可视化工作台与 CI 同口径门禁。
- **Harness 评测机制**：SDD + TDD + Harness 三层质量闭环，28 条 Spec 约束（A/C/T/H/N）、7 个结构 Linter、5 个契约测试、Ralph 编排脚本，实现「Spec 先行 → 测试驱动 → 背压门禁」。

## 应用国际化与软重启（App）

- **默认语言**：`en_US`；**界面支持**：`zh_CN`（标签归一化见 `lib/utils/app_lang_tag.dart`，翻译入口 `TranslationService` / `lib/services/langs/`）。
- **全局控制器**：`AppLocaleController`（`lib/services/app_locale_controller.dart`）在 `Global.init` 内 `Get.put(..., permanent: true)`；启动时 `syncLocaleFromStorageToGetX`（`lib/services/app_locale_bootstrap.dart`）对齐持久化与 `Get.locale`。
- **切换语言（对齐 mall-app）**：设置页通过 `HKDialog.showBottomSelectListPicker` 单选 → `applyLanguage`（更新 locale、持久化、`localeRevision`、Dio 语言头）；非测试环境调用 **`AppRestartService.restart()`**：`Get.reset()` → `await Global.init()` → **`RestartWidget`** 重建根树（`lib/services/app_restart_service.dart`、`lib/components/common/restart_widget.dart`）。`main.dart` 使用 `AppRestartService.wrapApp` 包裹根组件。
- **依赖就绪**：`Global.areDependenciesReady` 在 `Global.init` 完整成功后为 `true`；`MyApp` 仅在未就绪时执行 `Global.init()`，避免软重启后重复初始化；`AppLocaleController` 同步 Dio 前亦依赖该标志。
- **首页商品 Tab**：通过 `localeRevision` 触发分类/列表刷新，避免对整页加 `KeyedSubtree` 导致同一 `RefreshController` 被两个 `SmartRefresher` 复用的问题。
- **首页一级 Tab 壳层**：顶栏渐变与子页背景锚点见 `lib/pages/home/home_shell_theme.dart`；`HKCommonTab` 字号与顶栏/产线布局约定见 [`doc/features/home/README.md`](doc/features/home/README.md) 第 6 节。
- **请求层 locale**：首页 Banner/热词等接口统一透传 `locale`；客户端未设置时回退 `en_US`，仅语言码为 `zh` 时回退 `zh_CN`，其余可按 `*_US` 规则拼接（与 Dio/工具层一致）。
- **国际化字符串常量管理**：所有国际化字符串常量统一管理在 `lib/values/app_strings.dart` 文件中，使用 `AppStrings.xxx.tr` 方式引用，确保多语言支持的一致性和可维护性。
- **点击命中增强组件**：新增 `HKHitTap`（`lib/components/common/hk_hit_tap.dart`），用于“扩大点击区域但不改变视觉尺寸”；案例入口见 `lib/pages/common/hk_hit_tap_case_page.dart`（Cases -> 常用 -> 扩大点击区域案例）。

## 仓库布局（App + 后端）

- **Flutter App**：`lib/`、`test/`、`ios/`、`android/` 等。
- **Python 后端**：`backend/`（与 App **同一 Git 仓库**，便于接口契约、联调与同步修改）。本地启动与测试见该目录下 `README.md`、`Makefile`。
- **CI**：后端变更触发 [`.github/workflows/backend-ci.yml`](.github/workflows/backend-ci.yml)（路径过滤 `backend/**`）。

## 测试快速入口

- 测试 1 分钟上手与产物说明：[`doc/zh/content/测试快速上手.md`](doc/zh/content/测试快速上手.md)
- CI 对应关系与本地命令映射：见 `测试快速上手.md` 的“CI 对应命令映射”

## 在 Cursor 中编译/调试运行（App）

本仓库已提供 `/.vscode/launch.json`，用于在 Cursor 的 **Run and Debug** 面板一键启动调试（非 flavor）。

- **启动方式**：
  - 打开左侧 **Run and Debug**
  - 顶部下拉选择一个配置（如 `develop (iOS Simulator)` / `staging (iOS Simulator)` / `prod (iOS Simulator)`）
  - 点击 **Start Debugging**（或按 `F5`）
- **环境切换**：
  - 通过 `--dart-define=ENV=...` 与 `--dart-define=CHANNEL=...` 控制（已内置到 launch 配置中）
- **Web 支持说明**：
  - 当前 `launch.json` **不提供 Web(Chrome) 启动项**（避免引入 Web 侧不兼容依赖链导致无法编译调试）。

## 最常用入口

- **Harness 评测机制**：[`harness/README.md`](harness/README.md) — 完整背压：`make harness`
- Flutter App 核心功能：[`plugins/hk_base/README.md`](plugins/hk_base/README.md)
- 首页 App/admin 边界与接口契约：
  - [`doc/features/home/BOUNDARY.md`](doc/features/home/BOUNDARY.md)
  - [`doc/features/home/API_CONTRACT.md`](doc/features/home/API_CONTRACT.md)
  - [`doc/features/home/FIELD_DICTIONARY.md`](doc/features/home/FIELD_DICTIONARY.md)
- Flutter App 接入指南：[`doc/zh/content/FlutterApp自动化测试功能接入指南.md`](doc/zh/content/FlutterApp自动化测试功能接入指南.md)
- AI 入口（Test Agent）：[`tool/test_agent/README.md`](tool/test_agent/README.md) — 快捷启动：`bash tool/test_agent/run_webui.sh`（默认 <http://127.0.0.1:8030/>）
- **Flutter Dev Agent（智能开发助手）**：[`tool/flutter_agent/README.md`](tool/flutter_agent/README.md) — **快速开始**：`bash tool/flutter_agent/flutter_agent_wrapper.sh demo`；**手动启动**：`bash tool/flutter_agent/run_index.sh` → `bash tool/test_agent/run_webui.sh`；**文档入口**：[`doc/features/flutter_dev_agent/INDEX.md`](doc/features/flutter_dev_agent/INDEX.md)
- 多 Agent（Agentic 测试端到端示例）：[`doc/features/agentic_multi_agent/README.md`](doc/features/agentic_multi_agent/README.md)
- 登录模块（多流程 + refresh token）：[`doc/features/login/INDEX.md`](doc/features/login/INDEX.md)
- 登录模块技术文档：[`doc/features/login/TECHNICAL_DOCUMENT.md`](doc/features/login/TECHNICAL_DOCUMENT.md)
- 供应商店铺模块：[`lib/pages/home/goods/suppliers_store/`](lib/pages/home/goods/suppliers_store/) — 包含公司详情页面、公司介绍、展会信息、联系方式和主要客户等功能
- 展会信息页面：[`lib/pages/home/goods/exhibition/exhibition_page.dart`](lib/pages/home/goods/exhibition/exhibition_page.dart) — 展示展会信息列表，支持点击查看详情，已优化代码结构、样式实现和国际化支持
- RAG 知识库（长期记忆 + 检索）：[`rag/README.md`](rag/README.md) — 初始化：`dart run tool/rag/rag_cli.dart init`
- 自动化测试总入口：[`doc/zh/content/测试快速上手.md`](doc/zh/content/测试快速上手.md)
- 自动化测试交付指南：[`doc/zh/content/自动化测试交付指南.md`](doc/zh/content/自动化测试交付指南.md)
- 测试工具链说明：[`tool/testing/README.md`](tool/testing/README.md)
- GUI（Flutter 测试工作台）：[`tool/gui_pyqt5/README.md`](tool/gui_pyqt5/README.md)

## `doc/zh` 中文文档中心

- 总览与上手：
  - 项目概述：[`doc/zh/content/项目概述.md`](doc/zh/content/项目概述.md)
  - 快速开始：[`doc/zh/content/快速开始.md`](doc/zh/content/快速开始.md)
  - 部署指南：[`doc/zh/content/部署指南.md`](doc/zh/content/部署指南.md)
- 测试与交付：
  - 测试快速上手：[`doc/zh/content/测试快速上手.md`](doc/zh/content/测试快速上手.md)
  - 自动化测试交付指南：[`doc/zh/content/自动化测试交付指南.md`](doc/zh/content/自动化测试交付指南.md)
  - Flutter App 接入指南：[`doc/zh/content/FlutterApp自动化测试功能接入指南.md`](doc/zh/content/FlutterApp自动化测试功能接入指南.md)
  - 测试策略：[`doc/zh/content/测试策略.md`](doc/zh/content/测试策略.md)
- 治理与优化：
  - AI 治理规则使用说明：[`doc/zh/content/AI治理规则使用说明.md`](doc/zh/content/AI治理规则使用说明.md)
  - 优化类任务关键词触发建议清单：[`doc/zh/content/优化类任务关键词触发建议清单.md`](doc/zh/content/优化类任务关键词触发建议清单.md)
  - 首页性能优化指南：[`doc/zh/content/首页性能优化指南.md`](doc/zh/content/首页性能优化指南.md)
- 架构与组件（按模块深入）：
  - 架构设计总览：[`doc/zh/content/架构设计/架构设计.md`](doc/zh/content/架构设计/架构设计.md)
  - 核心组件库：[`doc/zh/content/核心组件库/核心组件库.md`](doc/zh/content/核心组件库/核心组件库.md)
  - 页面功能模块：[`doc/zh/content/页面功能模块/页面功能模块.md`](doc/zh/content/页面功能模块/页面功能模块.md)
  - hk_base 模块文档：[`plugins/hk_base/README.md`](plugins/hk_base/README.md)
- Repowiki（IDE 内索引，与 `backend/` 同仓说明）：[`.qoder/repowiki/zh/content/架构设计/仓库布局与Python后端.md`](.qoder/repowiki/zh/content/架构设计/仓库布局与Python后端.md)

## AI 治理与协作

### 规则体系（Rules）
- 架构与编码规范：[`.cursor/rules/flutter-stack.mdc`](.cursor/rules/flutter-stack.mdc)
- 自动化测试规范：[`.cursor/rules/automated-tests.mdc`](.cursor/rules/automated-tests.mdc)
- CI/CD 规范：[`.cursor/rules/ci-cd.mdc`](.cursor/rules/ci-cd.mdc)
- 代码审查规范：[`.cursor/rules/code-review.mdc`](.cursor/rules/code-review.mdc)
- Bug 修复与 RAG：[`.cursor/rules/bug-fix-rag.mdc`](.cursor/rules/bug-fix-rag.mdc)
- Agent 行为规范：[`.cursor/rules/agents-guidelines.mdc`](.cursor/rules/agents-guidelines.mdc)
- 代码优化 Rules 入口（仅优化类任务触发）：[`.cursor/rules/flutter-code-optimization.mdc`](.cursor/rules/flutter-code-optimization.mdc)
- 优化类任务关键词触发建议清单：[`doc/zh/content/优化类任务关键词触发建议清单.md`](doc/zh/content/优化类任务关键词触发建议清单.md)
- 优化类任务提示词模板（四个示例）：[`doc/zh/content/优化类任务提示词模板（四个示例）.md`](doc/zh/content/优化类任务提示词模板（四个示例）.md)
- 任务场景提示词模板（五个示例）：[`doc/zh/content/任务场景提示词模板（五个示例）.md`](doc/zh/content/任务场景提示词模板（五个示例）.md)
- 规则使用说明与示例：[`doc/zh/content/AI治理规则使用说明.md`](doc/zh/content/AI治理规则使用说明.md)

### 代码优化 Rules 快速入口
- Rules 文件：[`/.cursor/rules/flutter-code-optimization.mdc`](.cursor/rules/flutter-code-optimization.mdc)
- 触发判定：[`doc/zh/content/优化类任务关键词触发建议清单.md`](doc/zh/content/优化类任务关键词触发建议清单.md)
- 提示词模板（模块专项）：[`doc/zh/content/优化类任务提示词模板（四个示例）.md`](doc/zh/content/优化类任务提示词模板（四个示例）.md)
- 提示词模板（通用场景）：[`doc/zh/content/任务场景提示词模板（五个示例）.md`](doc/zh/content/任务场景提示词模板（五个示例）.md)

### 30 秒模板选择
- 如果是“新增分页页面/修复线上崩溃/新增 CI 门禁/新增登录模块/通用优化任务”，直接用：[`doc/zh/content/任务场景提示词模板（五个示例）.md`](doc/zh/content/任务场景提示词模板（五个示例）.md)
- 如果是“模块专项优化（`hk_base` / `hk_net` / `lib/components` / `lib/base`）”，直接用：[`doc/zh/content/优化类任务提示词模板（四个示例）.md`](doc/zh/content/优化类任务提示词模板（四个示例）.md)
- 如果不确定是否触发优化规则，先看：[`doc/zh/content/优化类任务关键词触发建议清单.md`](doc/zh/content/优化类任务关键词触发建议清单.md)

### 一眼判定流程图（文字版）
1. 先判“任务主目标”：
   - 功能新增 / 缺陷修复 / CI 治理 -> 走“五个示例”对应场景。
   - 优化治理主目标 -> 进入第 2 步。
2. 再判“优化类型”：
   - 通用优化任务 -> 用“五个示例”示例 5。
   - 模块专项优化（`hk_base` / `hk_net` / `lib/components` / `lib/base`）-> 用“四个示例”对应模板。
3. 最后判“是否触发优化规则”：
   - 不确定时先看 `优化类任务关键词触发建议清单`，再填写 Issue/PR 优化触发证据。

### 常见误选纠偏
- 把“修复线上崩溃”误用成“优化类任务” -> 应改用“五个示例”的示例 2；否则会遗漏根因证据链与回归闭环。
- 把“新增登录模块/分页页面”误用成“优化模板” -> 应改用“五个示例”的示例 1/4；否则容易弱化功能验收与测试覆盖。
- 把“模块专项优化（如 `hk_base`）”误用成“通用五个示例” -> 应改用“四个示例”专项模板；否则优化范围与红线不够聚焦。

### 技能模板（Skills）
- Flutter 核心开发：[`SKILLS/flutter-core.skill.md`](SKILLS/flutter-core.skill.md)
- 分页专项开发：[`SKILLS/flutter-pagination.skill.md`](SKILLS/flutter-pagination.skill.md)
- 测试生成：[`SKILLS/test-generator.skill.md`](SKILLS/test-generator.skill.md)
- CI/CD 流程：[`SKILLS/ci-cd-workflow.skill.md`](SKILLS/ci-cd-workflow.skill.md)
- 代码审查：[`SKILLS/code-review.skill.md`](SKILLS/code-review.skill.md)
- 缺陷修复：[`SKILLS/bug-fix-assistant.skill.md`](SKILLS/bug-fix-assistant.skill.md)

### 多 Agent 协作入口
- 协作协议文档：[`AGENTS.md`](AGENTS.md)
- 推荐流程：Meta Architect 规划 -> Flutter Dev 实现 -> Test Agent 验证 -> Code Review 审查 -> Bug Fix 闭环。
- 优化类任务 Issue 模板： [`.github/ISSUE_TEMPLATE/optimization-task.yml`](.github/ISSUE_TEMPLATE/optimization-task.yml)
- Issue 模板配置（禁用空白 Issue）： [`.github/ISSUE_TEMPLATE/config.yml`](.github/ISSUE_TEMPLATE/config.yml)

### Harness 评测机制

Harness 是项目的三层质量保障体系，实现「Spec 先行 → 测试驱动 → 背压门禁」闭环。

**三支柱架构**：
- **Inform 告知**：`AGENTS.md` 导航 + `spec/flutter_components_spec.md`（28 条约束：A1~A7 架构、C1~C6 组件、T1~T6 测试、H1~H6 Harness、N1~N3 网络）
- **Constrain 约束**：7 个结构 Linter（`linters/check_*.py`）+ `analysis_options.yaml`
- **Verify 验证**：5 个契约测试（`tests/harness/`）+ Flutter 测试 + CI 门禁

**核心产物**：
| 类别 | 数量 | 路径 |
|------|------|------|
| Spec 文档 | 1 | `spec/flutter_components_spec.md` |
| Linter 脚本 | 7 | `linters/check_*.py` |
| 契约测试 | 5 | `tests/harness/test_*.py` |
| CI 工作流 | 1 | `.github/workflows/harness.yml` |
| Ralph 脚本 | 1 | `scripts/ralph_harness.py` |
| Makefile | 1 | `Makefile` |

**快速开始**：
```bash
# 完整背压验证（Lint + 契约 + 测试）
make harness

# 仅结构 Lint
make harness-lint

# 仅契约测试
make harness-contract

# Ralph 验证环
python3 scripts/ralph_harness.py --verify
```

详细说明见 [`harness/README.md`](harness/README.md)，Stage Report 见 [`doc/features/harness_evaluation/STAGE_REPORT.md`](doc/features/harness_evaluation/STAGE_REPORT.md)。

### 与 CI 的对应关系
- **Harness 门禁**： [`.github/workflows/harness.yml`](.github/workflows/harness.yml) — 3 个 Job：结构 Lint、契约测试、Flutter 测试+覆盖率；触发条件：PR 或 push 到 main/master 且涉及 `lib/`、`test/`、`spec/`、`linters/`、`tests/harness/`。
- Python 后端（同仓 `backend/`）： [`.github/workflows/backend-ci.yml`](.github/workflows/backend-ci.yml) — 仅 `backend/**` 变更触发；本地对齐：`cd backend && ./tool/testing/run_backend_tests.sh`
- PR/Push 基础验证： [`.github/workflows/verify-testing-toolchain.yml`](.github/workflows/verify-testing-toolchain.yml)
- 门禁策略（`verify-testing-toolchain.yml`）：
  - `Feature docs gate`：PR 为 warn 模式（`check_feature_docs.sh`），main/master 为 strict 模式（`check_feature_docs.sh --strict`）。
  - `Reuse hygiene check`：PR 为 warn 模式（`check_reuse_hygiene.sh`），main/master 为 strict 模式（`check_reuse_hygiene.sh --strict`）。
  - `Optimization trigger check`：PR 为 warn 模式（`check_optimization_trigger.sh`），main/master 为 strict 模式（`check_optimization_trigger.sh --strict`，非 PR 事件自动跳过；优先识别 PR 模板勾选，再关键词兜底）。
  - 规则配置入口：`tool/testing/config/reuse_hygiene_rules.txt`（`group|scope|severity|pattern|message`），豁免入口：`tool/testing/config/reuse_hygiene_ignore.txt`。
- PR 冒烟回归： [`.github/workflows/agentic-smoke-android.yml`](.github/workflows/agentic-smoke-android.yml)
- Nightly 全量回归： [`.github/workflows/agentic-full-android-nightly.yml`](.github/workflows/agentic-full-android-nightly.yml)

### 直接给 AI 的任务模板（登录模块）

```text
请按生产级标准完成登录模块任务，严格遵循 Clean Architecture + GetX，并满足以下约束：
1) 明确任务类型（新增/修复/重构）与影响范围（登录/注册/找回/401刷新/回跳）；
2) UI 不直连网络，Controller 依赖 Repository 抽象注入，禁止吞异常；
3) 校验逻辑统一收敛到 `LoginValidators`，错误文案统一收敛到 `LoginErrorMessages`；
4) 覆盖 loading/disabled/error 状态、防重复提交、键盘焦点处理；
5) 补齐并执行 unit + widget + integration（核心链路：未登录 -> 登录 -> 回跳 -> 动作回放）；
6) 同步更新 `doc/features/login/` 文档并输出变更清单、测试结果、风险与回归建议。

完整精准模板见：`doc/features/login/LOGIN_PROMPT_TEMPLATE.md`
```

## 快捷命令

以下示例中的目录请替换为你本机项目根（本仓库常见为 `/Users/hujintao/Desktop/python/ai/flutter_components`）。

### 启动 Test Agent（可选）

```bash
cd "/Users/hujintao/Desktop/python/ai/flutter_components"
bash tool/test_agent/run_webui.sh
```

### 初始化 RAG 知识库（工程化长期记忆）

```bash
cd "/Users/hujintao/Desktop/python/ai/flutter_components"
dart run tool/rag/rag_cli.dart init
dart run tool/rag/rag_cli.dart query 首页 分页 异常 根因
```

### 启动 GUI（Flutter 测试工作台）

```bash
cd "/Users/hujintao/Desktop/python/ai/flutter_components"
bash tool/gui_pyqt5/run_gui.sh
```

启动后若已有 `test-artifacts/**/result.json`，工作台会自动加载最近一份；界面分区与配图说明见 [`tool/gui_pyqt5/README.md`](tool/gui_pyqt5/README.md)。

### 一键：后端 + Flutter（iOS，macOS）

```bash
cd "/Users/hujintao/Desktop/python/ai/flutter_components"
bash tool/dev/run_backend_and_flutter_ios.sh
```

后台启动 `backend`（默认 `http://127.0.0.1:8000`），再 `flutter run` 到本机 **第一个可用 iOS 设备**；若无 iOS 设备则 **boot 并打开 `iPhone 16 Plus` 模拟器**（可用环境变量 `IOS_SIMULATOR_NAME` 改名）。退出 Flutter 后默认结束后台 uvicorn，保留后端请设 `KEEP_BACKEND=1`。详见脚本头部注释。

### 生成交付报告（基于某次 result.json）

```bash
cd "/Users/hujintao/Desktop/python/ai/flutter_components"
dart run tool/testing/generate_delivery_reports.dart test-artifacts/<date>/run_<id>/result.json
```

## 设备准备（Android）

- 启动模拟器：`flutter emulators --launch <emulator_id>`
- 确认在线：`flutter devices`
- `--device-id` 请填 `flutter devices` 里看到的设备序列号（如 `emulator-5554`）

## 说明

- 本 README 保留“小白可用”主路径；深度排障、字段说明、CI 细节请看上面的专项文档。
- 系统边界声明：本仓库主线为 Flutter App 与自动化测试能力；admin 后台属于独立配置端能力，首页联调时请以 `doc/features/home/BOUNDARY.md` 的边界定义为准。
- 应用侧语言与软重启的代码入口与行为说明见上文 **「应用国际化与软重启（App）」**；接口 `locale` 回退规则与同节“请求层 locale”一致。
- **测试模块标注**：与自动化测试/集成测试相关的依赖与入口文件会用“**测试模块需要**”显式标注（如 `pubspec.yaml` 的 `dev_dependencies`、`integration_test/`、`tool/testing/` wrapper、`packages/agentic_integration_support`），避免被误当业务依赖清理或挪入 `lib/`。
- **生成物不入库**：`delivery/` 与 `tool/testing/delivery/` 下的报告/评论/检查结果等默认作为生成物落盘（便于本地查看与 CI artifact），但不会被纳入 git 变更，避免无意义 diff。

## Flutter Dev Agent 快速上手

Flutter Dev Agent 是基于 **analyzer 索引 + Ollama 大模型** 的智能开发助手，提供代码理解、缺陷修复、功能开发、测试生成等能力。

### 🚀 一键启动
```bash
# 完整演示（推荐首次使用）
bash tool/flutter_agent/flutter_agent_wrapper.sh demo

# 或分步执行
bash tool/flutter_agent/flutter_agent_wrapper.sh index  # 生成索引
bash tool/flutter_agent/flutter_agent_wrapper.sh start  # 启动 WebUI
```

### 📋 主要功能
- **代码理解**：分析项目结构、Widget 统计、路由配置
- **缺陷修复**：布局溢出、空安全、导航问题等
- **功能开发**：新页面开发、状态管理优化、重构建议
- **测试辅助**：单元测试生成、集成测试设计
- **文档生成**：四段式中文注释、API 文档

### 🔧 环境要求
- Flutter SDK (3.8+)
- Ollama 服务（可选，用于本地模型）
- 同级目录 `test_platform`（Test Agent 后端）

### 📚 更多资源
- **详细文档**：[`doc/features/flutter_dev_agent/INDEX.md`](doc/features/flutter_dev_agent/INDEX.md)
- **真实示例**：[`doc/features/flutter_dev_agent/REAL_EXAMPLES.md`](doc/features/flutter_dev_agent/REAL_EXAMPLES.md)
- **示例命令**：[`tool/flutter_agent/example_commands.md`](tool/flutter_agent/example_commands.md)
- **快速设置**：`python3 tool/flutter_agent/quick_setup.py`
- **项目计划**：[`flutter_dev_agent_系统_17517c2e.plan.md`](flutter_dev_agent_系统_17517c2e.plan.md)