refactor(chat): 重构聊天模块并集成历史消息加载功能
- 删除冗余的 chat_history_repository 和 home_mock_data - 简化 ag_ui_event fromJson 使用工厂映射表 - 提取 ChatBloc 事件处理方法，添加 loadHistory/loadMoreHistory - HomeScreen 集成 ChatBloc 实现历史消息加载和下拉刷新 - 更新 AGENTS.md 文档约束
This commit is contained in:
qzl
+51
-155
@@ -1,174 +1,70 @@
|
||||
# Flutter Mobile Development Rules
|
||||
# Flutter Mobile Development Constraints
|
||||
|
||||
This document defines Flutter mobile development constraints.
|
||||
This document defines **hard constraints** for Flutter mobile development. Treat all items as **non-negotiable** unless explicitly overridden.
|
||||
|
||||
## Design System
|
||||
## 1) Design Tokens (MUST)
|
||||
|
||||
### Design Tokens
|
||||
- **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)`.
|
||||
|
||||
All UI styling must use design tokens from `apps/lib/core/theme/design_tokens.dart`:
|
||||
## 2) Component Reuse (MUST)
|
||||
|
||||
| Type | Usage |
|
||||
|------|-------|
|
||||
| Colors | `AppColors.primary`, `AppColors.slate500`, `AppColors.background` |
|
||||
| Spacing | `AppSpacing.xs`, `AppSpacing.sm`, `AppSpacing.md` |
|
||||
| Radius | `AppRadius.sm`, `AppRadius.md`, `AppRadius.lg` |
|
||||
- **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.
|
||||
|
||||
**NEVER hardcode colors, sizes, or spacing values.**
|
||||
## 3) Layout Mapping & Alignment (MUST)
|
||||
|
||||
### Reuse Existing Components
|
||||
- **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.
|
||||
|
||||
Use pre-built components instead of creating custom ones:
|
||||
- Buttons: Use `AppButton` widget from `apps/lib/shared/widgets/app_button.dart`
|
||||
- Input fields: Use standard Flutter `TextField` with `InputDecoration`
|
||||
- Loading states: Use built-in loading indicators
|
||||
## 4) Centering & Visual Balance (MUST)
|
||||
|
||||
## New Page Design Workflow
|
||||
- **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.
|
||||
|
||||
1. **Analyze existing pages**: Study login, register, home screens for:
|
||||
- Layout structure (centered form, padding, spacing)
|
||||
- Typography hierarchy (title 28px bold, label 13px, hint 14px)
|
||||
- Component usage (AppButton, TextField style)
|
||||
- Color and spacing tokens
|
||||
## 5) Quality Gate for Important Screens (MUST)
|
||||
|
||||
2. **Use frontend-design skill for mockups**:
|
||||
```
|
||||
Use the `frontend-design` skill to create HTML/CSS mockups for review
|
||||
Match colors to `apps/lib/core/theme/design_tokens.dart`
|
||||
Match spacing to `AppSpacing` values
|
||||
Match radius to `AppRadius` values
|
||||
```
|
||||
For important screens:
|
||||
|
||||
3. **Verify design tokens**:
|
||||
- All colors from `AppColors`
|
||||
- All spacing from `AppSpacing`
|
||||
- All radius from `AppRadius`
|
||||
- NO hardcoded values
|
||||
- **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).
|
||||
|
||||
4. **Code review checklist**:
|
||||
- [ ] All colors/spacing/radius use design tokens
|
||||
- [ ] Reuses existing components (AppButton)
|
||||
- [ ] Consistent with existing page patterns
|
||||
- [ ] No magic numbers
|
||||
## 6) UI Feedback System (MUST)
|
||||
|
||||
## Layout Mapping Rules
|
||||
- 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.
|
||||
|
||||
Map design layout properties to Flutter explicitly:
|
||||
## 7) Agent Chat (AG-UI Protocol) (MUST)
|
||||
|
||||
1. **Always set `crossAxisAlignment` on `Row`/`Column`**:
|
||||
- `alignItems: center` -> `CrossAxisAlignment.center`
|
||||
- `alignItems: start` -> `CrossAxisAlignment.start`
|
||||
- `alignItems: stretch` -> `CrossAxisAlignment.stretch`
|
||||
2. **Map full container chain**: From root to leaf, ensure each `alignItems` and `justifyContent` has a Flutter equivalent.
|
||||
3. **Analyze before coding**: Verify each container's alignment settings.
|
||||
Agent chat functionality **MUST** follow the AG-UI protocol: `docs/knowledges/ag-ui-llms-full.txt`.
|
||||
|
||||
## Centering and Visual Balance
|
||||
- **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).
|
||||
|
||||
1. Centering must be evaluated inside **`SafeArea`** bounds, not full-screen bounds.
|
||||
2. Avoid relying on proportional `Spacer` values as the only centering mechanism for critical content.
|
||||
3. For layouts with persistent top/bottom regions (e.g., headers or footers), center the primary content in the remaining available region.
|
||||
4. Distinguish geometric centering from visual centering; validate final visual balance with screenshot review.
|
||||
## 8) Debugging Behavior (MUST)
|
||||
|
||||
## Quality Gate
|
||||
|
||||
For important screens, add widget tests that reduce layout-regression risk:
|
||||
|
||||
1. Verify primary content remains centered relative to the usable viewport.
|
||||
2. Add at least one constrained viewport scenario (small height or large text scale).
|
||||
|
||||
## Prohibitions
|
||||
|
||||
- DO NOT use colors not defined in design tokens
|
||||
- DO NOT skip design container layers
|
||||
- DO NOT start implementation before retrieving design variables
|
||||
- DO NOT hardcode colors; use design variables
|
||||
|
||||
## UI Feedback System
|
||||
|
||||
**MUST use the Toast system for all user feedback messages.**
|
||||
|
||||
### Components
|
||||
|
||||
| Component | Use Case | Example |
|
||||
|-----------|----------|---------|
|
||||
| `Toast.show()` | Global temporary notifications | Success/error feedback after action |
|
||||
| `AppBanner` | Inline form validation errors | Login form error message |
|
||||
|
||||
### Toast Types
|
||||
|
||||
```dart
|
||||
enum ToastType { info, success, warning, error }
|
||||
```
|
||||
|
||||
### Usage Examples
|
||||
|
||||
**Global Toast (auto-dismiss):**
|
||||
```dart
|
||||
Toast.show(context, '保存成功', type: ToastType.success);
|
||||
Toast.show(context, '网络错误', type: ToastType.error);
|
||||
Toast.show(context, '正在加载...', type: ToastType.info, duration: Duration(seconds: 3));
|
||||
```
|
||||
|
||||
**Inline Banner (persistent):**
|
||||
```dart
|
||||
AppBanner(message: '邮箱或密码错误', type: ToastType.error)
|
||||
AppBanner(message: '请检查输入', type: ToastType.warning)
|
||||
```
|
||||
|
||||
### Rules
|
||||
|
||||
- Use `Toast` for transient feedback that auto-dismisses
|
||||
- Use `AppBanner` for persistent inline messages (form errors)
|
||||
- DO NOT create custom SnackBar, Dialog, or Banner components
|
||||
- DO NOT use raw `ScaffoldMessenger`
|
||||
|
||||
## Agent Chat (AG-UI Protocol)
|
||||
|
||||
**Agent chat functionality MUST follow the AG-UI protocol**, reference `docs/knowledges/ag-ui-llms-full.txt`.
|
||||
|
||||
### Core Requirements
|
||||
|
||||
1. **Event-Driven Architecture**: Implement event-driven streaming responses
|
||||
2. **Event Types**: Must support the 16 standard event types:
|
||||
- **Lifecycle**: `RUN_STARTED`, `RUN_FINISHED`, `RUN_ERROR`, `STEP_STARTED`, `STEP_FINISHED`
|
||||
- **Text Message**: `TEXT_MESSAGE_START`, `TEXT_MESSAGE_CONTENT`, `TEXT_MESSAGE_END`
|
||||
- **Tool Call**: `TOOL_CALL_START`, `TOOL_CALL_ARGS`, `TOOL_CALL_END`, `TOOL_CALL_RESULT`
|
||||
- **State Management**: `STATE_SNAPSHOT`, `STATE_DELTA`, `MESSAGES_SNAPSHOT`
|
||||
- **Special**: `RAW`, `CUSTOM`
|
||||
|
||||
3. **Transport**: Use Server-Sent Events (SSE) for streaming
|
||||
|
||||
4. **Event Flow**: Follow the standard pattern:
|
||||
- `RUN_STARTED` (required) → [optional events] → `RUN_FINISHED` or `RUN_ERROR` (required)
|
||||
- Text messages: `TEXT_MESSAGE_START` → `TEXT_MESSAGE_CONTENT` (delta) → `TEXT_MESSAGE_END`
|
||||
|
||||
5. **Frontend Integration**: Use AG-UI compatible client libraries
|
||||
|
||||
### Event Reference
|
||||
|
||||
| Event | Description |
|
||||
|-------|-------------|
|
||||
| `RUN_STARTED` | Signals the start of an agent run |
|
||||
| `RUN_FINISHED` | Signals successful completion |
|
||||
| `RUN_ERROR` | Signals an error during execution |
|
||||
| `TEXT_MESSAGE_START` | Initializes a new text message with unique messageId |
|
||||
| `TEXT_MESSAGE_CONTENT` | Delivers incremental text chunks (delta) |
|
||||
| `TEXT_MESSAGE_END` | Marks message completion |
|
||||
|
||||
### Prohibitions
|
||||
|
||||
- DO NOT return non-streaming responses for agent chat
|
||||
- DO NOT skip required lifecycle events (RUN_STARTED, RUN_FINISHED/RUN_ERROR)
|
||||
- DO NOT use custom event formats outside of AG-UI specification
|
||||
|
||||
|
||||
## App Debugging
|
||||
|
||||
**DO NOT automatically start Flutter app debugging.**
|
||||
|
||||
After completing code changes, inform the user to manually run:
|
||||
```bash
|
||||
flutter run --dart-define=MOCK_API=true -d emulator-5554
|
||||
```
|
||||
|
||||
Let the user control when to launch the app for testing.
|
||||
- **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`
|
||||
|
||||
Reference in New Issue
Block a user