Project Instructions

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

Completion Workflow

完成每项修改后运行最相关的验证，至少检查 flutter analyze；有测试时运行 flutter test。
修改代码时同步更新相关文档。
检查 Git 工作区，只提交本次任务的改动，并在最终回复中报告提交哈希。
如果修改需要重启正在运行的应用才能生效，明确告知用户。
遇到兼容性问题时，先询问是否需要兼容支持，再进行相关工作。
Codex Windows 环境的 Java Selector.open() 曾因 Unix socket 临时目录问题报 Unable to establish loopback connection，导致 Gradle 在编译前失败。2026-10-22 已验证以下绕法可成功构建 APK：后续需要运行 Gradle 或 flutter build apk 时，直接先设置此配置，不再因该历史故障默认跳过打包或重复询问是否重试。
- 在项目根目录执行以下 PowerShell 命令，然后运行需要的构建命令；保留已有 Java 参数，仅设置当前进程及其子进程的环境，不修改全局 Java 配置。
```
$socketDir = Join-Path (Get-Location) 'build/java-sockets'
New-Item -ItemType Directory -Force -Path $socketDir | Out-Null
$env:JAVA_TOOL_OPTIONS = ($env:JAVA_TOOL_OPTIONS + ' -Djdk.net.unixdomain.tmpdir="' + $socketDir + '"').Trim()
flutter build apk --debug --target-platform android-arm64
```
- flutter clean 会删除构建目录；清理后须重新创建 build/java-sockets。
- 若使用此配置后仍失败，保留并报告实际错误；照常完成 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。