f91be94e9c
- 清理大量废弃的 barrel 导出文件，移除冗余的中间导出层 - 修复所有相对路径导入错误，统一调整为扁平化模块引用 - 更新多平台 pubspec 版本号与依赖库版本 - 补充后端功能问题管理后台与脚本工具 - 调整部分页面的快捷方式文案适配新功能 - 更新部分翻译覆盖率与API文档
93 lines
5.3 KiB
Markdown
93 lines
5.3 KiB
Markdown
---
|
||
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/` 子目录，否则与页面文件合并
|