Project Instructions

本项目遵循 ../mynote-client/AGENTS.md 的通用约定。以下规则将其应用到 Flutter 移动端。

Completion Workflow

• 完成每项修改后运行最相关的验证，至少检查 flutter analyze；有测试时运行 flutter test。
• 修改代码时同步更新相关文档。
• 检查 Git 工作区，只提交本次任务的改动，并在最终回复中报告提交哈希。
• 如果修改需要重启正在运行的应用才能生效，明确告知用户。
• 遇到兼容性问题时，先询问是否需要兼容支持，再进行相关工作。
• 当前 Codex Windows 执行环境已确认 Java Selector.open() 报 Unable to establish loopback connection，导致 Gradle 在编译前失败。环境未变化且用户未明确要求重试时，跳过 flutter build apk 等 Gradle 打包命令；照常运行 flutter analyze 和 flutter test，并报告打包未验证。环境更新或用户要求重试后再检查。

Code Preservation

• 未经明确要求，不删除现有注释、调试代码、日志或类似开发产物。
• 提取模块时尽量保留原代码，不做无关修改或优化。
• 单个文件尽量控制在 600 行以内；超过时考虑提取内聚模块，保持行为不变。
• 能保持行为且不增加无谓复杂度时，优先按需加载。

Code Comments

• 为复杂逻辑、非显而易见的行为、边界情况和重要设计决策写注释。
• 简单代码的注释保持简洁，避免复述代码。

UI

• 使用 Flutter 的布局组件处理动态尺寸，并遵守基本无障碍要求。
• UI 优先保持紧凑，把有限的屏幕高度和宽度留给笔记编辑与阅读；新增控件或间距前，先检查是否能复用现有工具栏或收入菜单。
• 顶栏、标签栏和编辑工具栏控制纵向高度；横屏打开笔记后，仓库入口、标签导航和编辑工具合并为顶部一行，空间不足时省略名称。
• 常用模式和保存操作使用图标、背景高亮和应用内提示表达状态与名称；工具栏按钮保持紧凑内边距，不增加重复文字或勾选图标。
• 模式与功能开关的图标展示当前状态，不展示点击后将切换到的状态；使用两种图标区分状态时，两种状态均使用普通背景；仅使用一种图标表示两种状态时，启用状态使用高亮背景及高对比图标，未启用状态使用普通背景。长按提示说明当前模式或开关状态，同类控件使用一致图标。
  • 展开箭头保持既有惯例；一次性命令、纯状态指示、原生开关及已有模式选择组件保留既有表达。
• 标签与导航按钮保持紧凑且一致的尺寸和间距；横屏中将次要操作收入对应菜单，竖屏保留必要的快捷入口。具体交互和尺寸以 FEATURES.md 为准。
• 用户确认或提示使用应用内 Flutter 组件，避免直接调用平台原生模态对话框。
• 快捷键提示中的修饰键名称应与当前平台一致，不显示跨平台组合占位文字。

Documentation

• 重组文档时尽量保留原有内容与含义。
• 使用层级一致的 Markdown 标题，将长段落拆成短段落或列表。
• 不同内容分别成行，相关细节使用嵌套列表。

File Format

• 所有文本文件使用 UTF-8 编码和 Unix 风格 LF 换行。
• 编辑现有文件时保留 UTF-8 和 LF。