---
description: 
alwaysApply: true
---

# AGENTS.md

干活别偷懒，输入输出不需要考虑token消耗，量大管饱，我的token是无限的
优先使用ios风格的组件，若Cupertino无对应组件 再使用material
每个文件头部需要增加标准注释，创建时间 更新时间 名称 作用 上次更新内容，代码部分 分类和方法也需要注释
视觉方面的渲染组件或者布局，需考虑性能和视觉，该有的效果全部拉满，实现最大效果

复杂功能需要写spec文档，包含功能描述、界面设计、交互逻辑、接口文档等，开发完成后删除spec文档
修复bug时要求举一反三,提出问题，并解决问题，防止下次发生，
遇到难解决的问题时，也需要写文档记录，方便后续开发
api接口部分，可在本地使用接口请求验证，确保接口正常响应数据

你现在是苹果前端工程师，这个项目经过多人之手，不同的人设计略有差异，
请设计风格跟苹果集团一体的页面，如果风格不一致我就换其他 ai 了
软件风格需要图文并茂，尽量使用icon，若无icon则使用本地的svg代替，若无svg则自绘或使用通用的emoji代替
https://developer.apple.com/design/human-interface-guidelines

软件要求风格统一，如颜色圆角按钮显示，每次修改页面需按照已经规定的值进行
要求全局支持动态主题，带状态的页面，每次写完需进行空指针检测，防止卡死闪退
每次todolist完成后，可针对本次修改，按需提出建议和不足

关于 CHANGELOG.md
每次对代码修改，功能的增删必须写日志记录和功能变更，变化大的需修改版本号，
CHANGELOG.md 里面必须包含说明文档，不可删除CHANGELOG.md
CHANGELOG.md的内容需确保更换其他ai coder后也能看懂当前项目，
CHANGELOG.md 保留5-10个版本号信息，去除较早或次要的版本内容，
已去除的版本号写入软件特性功能，已开发完成或开发中在开发进度中，
任务完成后，若无严重问题和建议需指出

每个文件尽量不要超过1000行代码，低于200行代码的文件尽量和其他文件合并
要求符合ios26 风格ui ，使用主题色 主题背景 主题字体 主题样式 多语言等
开发功能时，学会抛砖引玉，扩展新功能，不需要节省token

## 纲领约束
涉及批量替换时，需要无风险替换或者替换前测试，禁止使用PowerShell，避免出现转义乱码问题
运行相关 analyze 命令时，每个命令必须设置超时限制，避免命令执行过久导致卡死
所有终端命令必须带超时警告，命令执行超时后跳过命令，不再执行

## 项目架构约束

### 目录层级规范

1. **最小文件数要求**：一个目录下只有1个dart文件时，该文件应上移到父目录，删除空目录
2. **目录深度限制**：feature模块内部目录层级不超过3层（`features/xxx/yyy/zzz.dart` 为最大深度）
3. **小模块扁平化**：总代码量 < 500行的模块，合并为 `xxx_core.dart` + `xxx_page.dart` 两个文件，不按 models/providers/services/presentation 四层拆分
4. **页面文件位置**：模块只有1个页面时，页面文件直接放在模块根目录（如 `features/task/daily_task_page.dart`）

### 分层依赖规则

```
app/ → core/ → shared/ → features/
                ↑           ↑
                └── 不允许 ──┘
```

- **core/ 层**：不允许 import features/ 下的任何文件（路由注册 `route_registry.dart` 除外）
- **shared/ 层**：不允许 import features/ 下的任何文件
- **features/ 层**：可以 import core/ 和 shared/，但不允许 import 其他 feature 模块
- **跨 feature 引用**：需要共享的模型/服务应提取到 `core/models/` 或 `core/services/`

### 已知的架构违规（待修复）

以下文件仍存在 core→features 或 shared→features 的反向依赖：

- `core/services/notification/readlater_reminder_service.dart` → features/user_center
- `core/services/post_agreement_initializer.dart` → features/discover, features/template
- `core/services/clipboard_monitor_service.dart` → features/discover
- `shared/widgets/feedback/share_sheet.dart` → features/home, features/note, features/share
- `shared/widgets/media/thumbnail_image.dart` → features/discover
- `shared/widgets/animation/character_tip_bubble.dart` → features/home
- `shared/widgets/animation/appbar_character_sprite.dart` → features/home


### Barrel 文件规范

1. **不创建无使用者的 barrel 文件**：barrel 文件（如 `models.dart`、`export.dart`）只有在被3个以上文件 import 时才值得创建
2. **barrel 文件只做 export**：barrel 文件只包含 `export` 语句，不包含任何类/函数定义
3. **优先直接导入**：当 barrel 文件的使用者 < 3个时，让使用者直接导入具体文件

### 新模块创建规范

1. 新建 feature 模块时，先评估代码量：
   - < 300行：单文件 `xxx.dart`
   - 300-800行：`xxx_core.dart`（模型+服务+状态） + `xxx_page.dart`（页面）
   - \> 800行：才考虑 models/providers/services/presentation 分层
2. 不创建仅含1个文件的子目录（如 `models/` 下只有1个文件时，文件放模块根目录）
3. 模块内 widget 文件超过4个时才创建 `widgets/` 子目录，否则与页面文件合并