Files

T

qzl e161ca22c4 refactor(chat): 重构聊天模块并集成历史消息加载功能

- 删除冗余的 chat_history_repository 和 home_mock_data
- 简化 ag_ui_event fromJson 使用工厂映射表
- 提取 ChatBloc 事件处理方法，添加 loadHistory/loadMoreHistory
- HomeScreen 集成 ChatBloc 实现历史消息加载和下拉刷新
- 更新 AGENTS.md 文档约束

2026-03-02 15:05:10 +08:00

3.4 KiB

Raw Blame History

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

3.4 KiB Raw Blame History