docs: 重写 AGENTS.md，精简为模块概览、命令、规范等核心信息
This commit is contained in:
parent
aeb147c6a7
commit
23a7db1057
125
AGENTS.md
125
AGENTS.md
@ -1,56 +1,97 @@
|
|||||||
<!-- Generated: 2026-05-20 | Updated: 2026-05-20 -->
|
<!-- Generated: 2026-06-01 -->
|
||||||
|
|
||||||
# YaYa
|
# YaYa
|
||||||
|
|
||||||
## Purpose
|
纯 Android + Jetpack Compose 日历应用。功能：农历/节气/节日、个人班次排期（WORK/OFF 循环）、月/周/年三视图。
|
||||||
YaYa 是一款基于纯 Android + Jetpack Compose 构建的日历应用。应用功能包括农历显示、节气标注、节假日信息、个人班次排期（WORK/OFF 循环）以及月/周/年三种视图切换。
|
|
||||||
|
|
||||||
## Key Files
|
> 注意：README 中提及的 "Kotlin Multiplatform / iOS" 与当前代码不符。实际为纯 Android 项目，模块名为 `:core` 和 `:app`，无 `:shared` 或 `:androidApp`。
|
||||||
|
|
||||||
| File | Description |
|
## 模块结构
|
||||||
|------|-------------|
|
|
||||||
| `build.gradle.kts` | 根项目 Gradle 构建设置 |
|
|
||||||
| `settings.gradle.kts` | Gradle 项目包含模块声明（`:app`, `:core`） |
|
|
||||||
| `gradle.properties` | Gradle 构建设置与缓存配置 |
|
|
||||||
| `gradle/libs.versions.toml` | 版本目录（依赖版本统一管理） |
|
|
||||||
| `CLAUDE.md` | 项目开发指南与架构文档 |
|
|
||||||
| `CHANGELOG.md` | 版本变更历史 |
|
|
||||||
| `DEVELOPMENT.md` | 性能追踪与开发工具说明 |
|
|
||||||
| `COMMENTS.md` | KDoc 注释规范 |
|
|
||||||
|
|
||||||
## Subdirectories
|
| 模块 | 类型 | 职责 |
|
||||||
|
|------|------|------|
|
||||||
|
| `:core` | `com.android.library` | 所有 Compose UI、ViewModel、业务逻辑 |
|
||||||
|
| `:app` | `com.android.application` | 薄壳：MainActivity + Manifest + 主题 |
|
||||||
|
| `:macrobenchmark` | `com.android.test` | Baseline Profile 生成 |
|
||||||
|
|
||||||
| Directory | Purpose |
|
**铁律**：`:app` 不添加业务逻辑，所有代码写在 `:core`。
|
||||||
|-----------|---------|
|
|
||||||
| `app/` | Android 应用壳层模块（见 `app/AGENTS.md`） |
|
|
||||||
| `core/` | Android Library 核心模块：所有 Compose UI、ViewModel 和业务逻辑（见 `core/AGENTS.md`） |
|
|
||||||
| `macrobenchmark/` | 宏基准测试模块，Baseline Profile 生成（见 `macrobenchmark/AGENTS.md`） |
|
|
||||||
| `gradle/` | Gradle Wrapper 文件（见 `gradle/wrapper/AGENTS.md`） |
|
|
||||||
| `scripts/` | 性能追踪脚本（见 `scripts/AGENTS.md`） |
|
|
||||||
| `logs/` | 性能追踪日志输出目录（见 `logs/AGENTS.md`） |
|
|
||||||
|
|
||||||
## For AI Agents
|
## 常用命令
|
||||||
|
|
||||||
### Working In This Directory
|
```bash
|
||||||
- 所有依赖版本在 `gradle/libs.versions.toml` 中声明
|
# 构建与安装
|
||||||
- 修改依赖后需同步 Gradle
|
./gradlew :app:assembleDebug
|
||||||
- 构建配置在根 `build.gradle.kts` 和各模块 `build.gradle.kts` 中
|
./gradlew :app:installDebug
|
||||||
|
|
||||||
### Testing Requirements
|
# 测试（仅 :core 有单元测试）
|
||||||
- 核心模块测试：`./gradlew :core:test`
|
./gradlew :core:test
|
||||||
- Android 构建：`./gradlew :app:assembleDebug`
|
./gradlew :core:test --tests "plus.rua.project.ui.CalendarUtilsTest"
|
||||||
- 安装验证：`./gradlew :app:installDebug`
|
|
||||||
|
|
||||||
### Common Patterns
|
# 代码格式化
|
||||||
- Kotlin 包名统一为 `plus.rua.project`
|
./gradlew spotlessApply
|
||||||
- UI 组件在 `plus.rua.project.ui` 包下
|
|
||||||
- `:app` 模块仅包含入口 Activity，所有 UI 和逻辑在 `:core` 模块
|
|
||||||
|
|
||||||
## Dependencies
|
# Baseline Profile（需连接设备/模拟器）
|
||||||
|
./gradlew :macrobenchmark:updateBaselineProfile # 生成 + 自动复制到 core/src/main/baseline-prof.txt
|
||||||
|
./gradlew :macrobenchmark:connectedBenchmarkAndroidTest
|
||||||
|
|
||||||
### External
|
# 性能追踪（需连接设备）
|
||||||
- Kotlin 2.3.21, Jetpack Compose BOM, Material 3
|
./scripts/profile.sh # 默认 8 秒
|
||||||
- `kotlinx-datetime` 0.8.0, `tyme4kt`（农历/节气）, `sketch` 4.4.0（GIF）
|
./scripts/profile.sh 15 # 自定义时长
|
||||||
- AGP 9.2.1, compileSdk/targetSdk 37, minSdk 24
|
./scripts/profile.sh --no-launch
|
||||||
|
```
|
||||||
|
|
||||||
<!-- MANUAL: -->
|
输出：`logs/trace_*.perfetto-trace`、`logs/framestats_*.txt`、`logs/meminfo_*.txt`、`logs/report_*.md`。
|
||||||
|
|
||||||
|
## 构建配置要点
|
||||||
|
|
||||||
|
- **AGP** 9.2.1 · **Kotlin** 2.3.21 · **JVM target** 17
|
||||||
|
- **compileSdk/targetSdk** 37 · **minSdk** 24
|
||||||
|
- **版本目录**：`gradle/libs.versions.toml` — 所有依赖版本统一在此声明
|
||||||
|
- **构建类型**：`debug`（默认）、`release`（R8 混淆 + 资源压缩）、`trace`（release + trace 标记保留）、`benchmark`（macrobenchmark 专用）
|
||||||
|
- **R8**：`android.enableR8.fullMode=true`（`gradle.properties`）
|
||||||
|
- **缓存**：configuration cache + build cache 已启用（`gradle.properties`）
|
||||||
|
- **版本号**：动态生成格式 `baseVersion_gitHash_buildDate`（例：`1.0.0_a1b2c_010626`）
|
||||||
|
|
||||||
|
## 包名约定
|
||||||
|
|
||||||
|
- `:core` 逻辑层：`plus.rua.project`
|
||||||
|
- `:core` UI 层：`plus.rua.project.ui`
|
||||||
|
- `:app`：`plus.rua.project`
|
||||||
|
|
||||||
|
## 代码规范（关键差异项）
|
||||||
|
|
||||||
|
- 公共 `@Composable` 函数必须有 KDoc（参数说明 + 回调触发时机），见 `COMMENTS.md`
|
||||||
|
- `Modifier` 参数始终放签名最后
|
||||||
|
- 回调参数用 `on` 前缀（`onDateClick`）
|
||||||
|
- 可点击列表项用 `Card(onClick = ...)` + `CardDefaults.cardElevation(defaultElevation = 0.dp)`，不要用 `Modifier.clickable()` 裸包
|
||||||
|
- `@Suppress("DEPRECATION")` 必须附带行内注释说明原因（当前主要用于 `monthNumber`）
|
||||||
|
- UI 文本使用中文
|
||||||
|
- Spotless 在根 `build.gradle.kts` 配置，覆盖 `src/**/*.kt` 和 `*.gradle.kts`
|
||||||
|
|
||||||
|
## 关键依赖
|
||||||
|
|
||||||
|
- **Compose BOM** `2026.05.01` + **Material 3**
|
||||||
|
- **`kotlinx-datetime`** 0.8.0 — 所有日期逻辑（禁止 `java.util.Calendar`）
|
||||||
|
- **`tyme4kt`** 1.4.5 — 农历、节气、传统节日
|
||||||
|
- **`sketch`** 4.4.0 — GIF 显示（`sketch-compose` + `sketch-animated-webp`）
|
||||||
|
|
||||||
|
## 性能追踪标记
|
||||||
|
|
||||||
|
`ComposeTrace.kt` 提供自定义 Perfetto/Systrace 标记，关键标记名：
|
||||||
|
- `MonthView:Compose` / `YearView:Compose`
|
||||||
|
- `CalendarPager:Page:*` / `WeekPager:Page`
|
||||||
|
- `VM:collapseProgress:*`
|
||||||
|
- `YearGridView:*`
|
||||||
|
|
||||||
|
详见 `DEVELOPMENT.md`。
|
||||||
|
|
||||||
|
## 参考文档
|
||||||
|
|
||||||
|
| 文件 | 内容 |
|
||||||
|
|------|------|
|
||||||
|
| `CLAUDE.md` | 完整架构说明、组件树、动画机制、Pager 映射逻辑 |
|
||||||
|
| `DEVELOPMENT.md` | 性能追踪、Baseline Profile、模拟器启动参数 |
|
||||||
|
| `COMMENTS.md` | KDoc 规范、注释原则、反模式清单 |
|
||||||
|
| `app/AGENTS.md` | `:app` 模块细则 |
|
||||||
|
| `core/AGENTS.md` | `:core` 模块细则 |
|
||||||
|
| `macrobenchmark/AGENTS.md` | Baseline Profile 模块细则 |
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user