qzl
e161ca22c4
- 删除冗余的 chat_history_repository 和 home_mock_data - 简化 ag_ui_event fromJson 使用工厂映射表 - 提取 ChatBloc 事件处理方法，添加 loadHistory/loadMoreHistory - HomeScreen 集成 ChatBloc 实现历史消息加载和下拉刷新 - 更新 AGENTS.md 文档约束
71 lines
3.4 KiB
Markdown
71 lines
3.4 KiB
Markdown
# Flutter Mobile Development Constraints
|
|
|
|
This document defines **hard constraints** for Flutter mobile development. Treat all items as **non-negotiable** unless explicitly overridden.
|
|
|
|
## 1) Design Tokens (MUST)
|
|
|
|
- **MUST** use design tokens from `apps/lib/core/theme/design_tokens.dart`:
|
|
- Colors: `AppColors.*`
|
|
- Spacing: `AppSpacing.*`
|
|
- Radius: `AppRadius.*`
|
|
- **MUST NOT** hardcode any visual values, including (but not limited to): colors, font sizes, spacing, padding/margins, widths/heights, radii, shadows, opacity, or “magic numbers”.
|
|
- Examples that are **NOT allowed**: `Color(0xFF...)`, `SizedBox(height: 12)`, `EdgeInsets.all(16)`, `Radius.circular(8)`.
|
|
|
|
## 2) Component Reuse (MUST)
|
|
|
|
- **MUST** prefer existing components and established page patterns over creating new UI components.
|
|
- **MUST** use:
|
|
- Buttons: `AppButton` from `apps/lib/shared/widgets/app_button.dart`
|
|
- **MUST NOT** introduce parallel UI systems (custom buttons, custom loading systems, custom input wrappers) unless explicitly required and approved.
|
|
|
|
## 3) Layout Mapping & Alignment (MUST)
|
|
|
|
- **MUST** explicitly set `crossAxisAlignment` for every `Row` / `Column` (do not rely on defaults).
|
|
- **MUST** preserve layout semantics from root to leaf:
|
|
- alignment/justification intent must be explicitly represented in Flutter widgets.
|
|
- **MUST NOT** skip necessary container layers if doing so loses layout meaning or makes mapping non-traceable.
|
|
|
|
## 4) Centering & Visual Balance (MUST)
|
|
|
|
- **MUST** evaluate centering within `SafeArea` usable bounds (not full-screen bounds).
|
|
- **MUST NOT** rely on `Spacer` / proportional flex as the only centering mechanism for critical content.
|
|
- If persistent header/footer regions exist, **MUST** center primary content within the remaining usable region.
|
|
- **MUST** prioritize *visual centering* over purely geometric centering when they differ.
|
|
|
|
## 5) Quality Gate for Important Screens (MUST)
|
|
|
|
For important screens:
|
|
|
|
- **MUST** add widget tests to reduce layout regression risk:
|
|
- Verify primary content stays centered relative to the usable viewport.
|
|
- Include at least one constrained scenario (e.g., small height **or** large text scale).
|
|
|
|
## 6) UI Feedback System (MUST)
|
|
|
|
- All user-facing feedback **MUST** use the Toast system.
|
|
- Transient notifications: `Toast.show(...)`
|
|
- Persistent inline form errors: `AppBanner`
|
|
- **MUST NOT** create custom SnackBar/Dialog/Banner feedback components.
|
|
- **MUST NOT** use raw `ScaffoldMessenger` for feedback messaging.
|
|
|
|
## 7) Agent Chat (AG-UI Protocol) (MUST)
|
|
|
|
Agent chat functionality **MUST** follow the AG-UI protocol: `docs/knowledges/ag-ui-llms-full.txt`.
|
|
|
|
- **MUST** use Server-Sent Events (SSE) for streaming.
|
|
- **MUST** emit required lifecycle events:
|
|
- `RUN_STARTED` is required for every run
|
|
- End with exactly one of: `RUN_FINISHED` or `RUN_ERROR`
|
|
- **MUST** follow standard text streaming flow:
|
|
- `TEXT_MESSAGE_START` → `TEXT_MESSAGE_CONTENT` (delta) → `TEXT_MESSAGE_END`
|
|
- **MUST** support the standard AG-UI event type set as defined in the spec.
|
|
- **MUST NOT** return non-streaming responses for agent chat.
|
|
- **MUST NOT** omit required lifecycle events.
|
|
- **MUST NOT** use non-AG-UI event formats (except where the spec explicitly allows).
|
|
|
|
## 8) Debugging Behavior (MUST)
|
|
|
|
- **MUST NOT** automatically start Flutter app debugging or running.
|
|
- After code changes, **MUST** instruct the user to run manually (user-controlled):
|
|
- `flutter run --dart-define=MOCK_API=true -d emulator-5554`
|