agent.md

BLExpert Agent 协作说明

当前基线（最后核对：2026-08-22）：BLE 调试闭环、工作区、标准协议封包/解帧、设备默认连接配置、导入脚本信任边界、会话记录、UI 第二轮改造和 AI 协议助手 P0/P1 基础链路已实现。后续开发规范见 Flutter 开发规范，功能状态与优先级只看 开发路线图。

角色定位

本仓库是 BLExpert 的 Flutter 工程。BLExpert 是一款跨平台蓝牙调试与分析工具，目标平台包括 Android、iOS、Windows、macOS 和 Web。

在本项目中工作的 Agent 应优先做到：

• 优先使用中文沟通、中文文档和中文界面文案。
• 优先保证跨平台兼容性。
• 变更范围保持清晰、克制，避免无关重构。
• 代码结构要方便后续扩展 BLE、工作区管理和脚本引擎。
• 对协议处理、数据解析、平台差异等不直观逻辑添加必要注释。

产品背景

BLExpert 面向物联网和嵌入式开发场景，用于解决设备协议差异大、调试过程分散、团队协作难的问题。

应用后续应具备：

• 工作区化的设备配置。
• BLE Central 通信。
• 围绕原始 HEX 数据的 JavaScript 脚本处理。
• 结构化数据解析和字段映射。
• 完整工作区导入 / 导出。
• 实时数据日志与可视化。

实现优先级

新增功能时，优先按以下顺序推进：

1. 公共模型与数据契约。
2. 工作区持久化。
3. 蓝牙抽象层与平台适配层。
4. 扫描、连接、断开流程。
5. 数据日志与 HEX / ASCII / JSON 格式化工具。
6. 脚本引擎集成。
7. 数据解析、映射、导入导出。

架构约定

• 平台特定能力必须放在服务层或适配层，UI 不应直接依赖具体蓝牙插件。
• 接入真实插件前，优先保持 Mock 服务可用，方便桌面和 Web 预览。
• 蓝牙能力要优雅处理不支持的平台，尤其是 Web 和桌面平台。
• 数据模型要天然支持 JSON 序列化。
• 工作区导出格式应稳定、可读、便于版本升级。

UI 约定

• 界面文案优先使用中文，界面要支持国际化。
• 支持亮色、暗色和跟随系统三种主题模式。
• 默认主题模式为跟随系统。
• 首页直接呈现工具能力，不做营销页。
• 设备列表、数据日志、字段映射等界面应紧凑、专业、便于扫描。
• UI 新增和精细化调整先对照 UI 设计规范 的“当前 UI 精细化基线”，以首页工作区选择、设备选择、扫描按钮和设备发送策略弹窗为首批验收样例。
• 所有移动端和桌面端布局都要避免文字溢出和控件重叠。
• 尽量少用弹窗。

编码约定

• 目录职责、依赖方向、组件粒度、part 使用条件和提交门槛统一遵循 Flutter 开发规范。
• main.dart 仅负责应用启动；禁止重新放入页面、服务或业务状态。
• 新增页面组件按 feature 归档，普通 import 优先；仅紧密共享私有类型的同一 feature library 可以使用 part。
• shadcn_flutter 是唯一 UI 组件体系；业务界面、应用骨架、导航、弹层、选择控件和图标体系已完成迁移，后续不得重新引入应用层 Material 可见控件或交互表面。
• 代码标识符沿用 Dart / Flutter 常规英文命名。
• 注释优先使用中文，除非引用第三方 API 或协议原文。
• 默认使用 ASCII；中文文档、中文界面文案、中文注释可以使用 UTF-8。
• 仅在真正降低复杂度或贴合现有模式时新增抽象。
• 依赖保持克制，等功能需要明确后再引入。
• 不要考虑旧数据兼容，我们还没发布版本

当前开发重点

优先完成：

• Android、iOS、Windows、macOS、Linux 的脚本 runtime 能力审计与真实设备安全回归。
• AI 协议助手的文件输入、可观察会话、本地证据索引、定向修复与有限重试。
• 更细粒度的设备协议/会话能力建模、批量发送保护和日志导出脱敏。
• Android、iOS、Windows、macOS、Linux、Web 的真实设备回归、发布清单、示例工作区和故障排查文档。

标准协议收发、连接默认配置、导入脚本信任边界、会话持久化/筛选/导出和 UI 第二轮改造已经具备实现；不要将它们重新列为待开发项。