docs: 新增项目各目录 AGENTS.md 文档

为各模块和子目录添加 AGENTS.md，便于 AI 助手理解项目结构。 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-20 13:26:19 +08:00 · 2026-05-20 13:26:19 +08:00 · 50a42be9bc
commit 50a42be9bc
parent 68e6748735
18 changed files with 726 additions and 0 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@ -0,0 +1,53 @@
+<!-- Generated: 2026-05-20 | Updated: 2026-05-20 -->
+
+# YaYa
+
+## Purpose
+YaYa 是一款基于 Kotlin Multiplatform + Compose Multiplatform 构建的日历应用，同时支持 Android 和 iOS 平台。应用功能包括农历显示、节气标注、节假日信息、个人班次排期（WORK/OFF 循环）以及月/周/年三种视图切换。
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `build.gradle.kts` | 根项目 Gradle 构建设置 |
+| `settings.gradle.kts` | Gradle 项目包含模块声明 |
+| `gradle.properties` | Gradle 构建设置与缓存配置 |
+| `gradle/libs.versions.toml` | 版本目录（依赖版本统一管理） |
+| `CLAUDE.md` | 项目开发指南与架构文档 |
+| `CHANGELOG.md` | 版本变更历史 |
+| `DEVELOPMENT.md` | 性能追踪与开发工具说明 |
+| `COMMENTS.md` | KDoc 注释规范 |
+
+## Subdirectories
+
+| Directory | Purpose |
+|-----------|---------|
+| `androidApp/` | Android 应用壳层模块（见 `androidApp/AGENTS.md`） |
+| `shared/` | KMP 共享模块：所有 UI、ViewModel 和业务逻辑（见 `shared/AGENTS.md`） |
+| `iosApp/` | iOS Xcode 项目（见 `iosApp/AGENTS.md`） |
+| `gradle/` | Gradle Wrapper 文件 |
+
+## For AI Agents
+
+### Working In This Directory
+- 所有依赖版本在 `gradle/libs.versions.toml` 中声明
+- 修改依赖后需同步 Gradle
+- 构建配置在根 `build.gradle.kts` 和各模块 `build.gradle.kts` 中
+
+### Testing Requirements
+- 共享模块测试：`./gradlew :shared:allTests` 或 `:shared:testAndroidHostTest`
+- Android 构建：`./gradlew :androidApp:assembleDebug`
+
+### Common Patterns
+- Kotlin 包名统一为 `plus.rua.project`
+- UI 组件在 `plus.rua.project.ui` 包下
+- 平台相关代码通过 `expect/actual` 机制隔离
+
+## Dependencies
+
+### External
+- Kotlin 2.3.21, Compose Multiplatform 1.11.0, Material 3 1.10.0-alpha05
+- `kotlinx-datetime` 0.8.0, `tyme4kt`（农历/节气）, `sketch` 4.4.0（GIF）
+- AGP 9.2.1, compileSdk/targetSdk 37, minSdk 24
+
+<!-- MANUAL: -->
--- a/androidApp/AGENTS.md
+++ b/androidApp/AGENTS.md
@ -0,0 +1,54 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-05-20 | Updated: 2026-05-20 -->
+
+# androidApp
+
+## Purpose
+Android 应用壳层模块，仅包含入口 `MainActivity` 和最小化的 Android 平台配置。所有 UI 和业务逻辑均来自 `:shared` 模块。
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `build.gradle.kts` | Android 应用模块构建配置 |
+| `src/main/kotlin/plus/rua/project/MainActivity.kt` | Android 入口 Activity，设置 `App()` Composable |
+| `src/main/AndroidManifest.xml` | Android 清单，声明 MainActivity 和主题 |
+| `src/main/res/values/themes.xml` | 应用主题配置（Material 3） |
+| `src/main/res/values-night/themes.xml` | 夜间模式主题 |
+| `src/main/res/values/strings.xml` | 应用名称字符串 |
+| `src/main/assets/app_icon.png` | 应用图标资源 |
+| `src/main/assets/gifs/` | GIF 动画资源目录 |
+
+## Subdirectories
+
+| Directory | Purpose |
+|-----------|---------|
+| `src/main/` | 主源码与资源（见 `src/main/AGENTS.md`） |
+| `src/debug/` | Debug 构建资源（如 debug 图标） |
+| `src/release/` | Release 构建资源 |
+
+## For AI Agents
+
+### Working In This Directory
+- 不要在此模块添加业务逻辑；所有代码应放在 `:shared` 模块
+- 仅修改 Android 特有的配置：Manifest、主题、权限、应用图标
+- `MainActivity.kt` 应保持简洁，仅负责调用 `App()`
+
+### Testing Requirements
+- 构建验证：`./gradlew :androidApp:assembleDebug`
+- 安装验证：`./gradlew :androidApp:installDebug`
+
+### Common Patterns
+- 使用 `enableEdgeToEdge()` 实现全屏边缘到边缘显示
+- 主题继承自 `Theme.AppCompat.DayNight.NoActionBar`
+
+## Dependencies
+
+### Internal
+- `:shared` 模块 — 提供所有 UI 和逻辑
+
+### External
+- Android Gradle Plugin 9.2.1
+- Material 3, Compose runtime
+
+<!-- MANUAL: -->
--- a/androidApp/src/main/AGENTS.md
+++ b/androidApp/src/main/AGENTS.md
@ -0,0 +1,40 @@
+<!-- Parent: ../../AGENTS.md -->
+<!-- Generated: 2026-05-20 | Updated: 2026-05-20 -->
+
+# main
+
+## Purpose
+Android 应用主 source set，包含入口 Activity、应用清单、主题资源和图标资源。
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `kotlin/plus/rua/project/MainActivity.kt` | Android 入口 Activity |
+| `AndroidManifest.xml` | Android 应用清单 |
+| `res/values/themes.xml` | Material 3 主题定义 |
+| `res/values-night/themes.xml` | 夜间模式主题 |
+| `res/values/strings.xml` | 应用名称等字符串 |
+| `assets/app_icon.png` | 应用图标 |
+
+## Subdirectories
+
+| Directory | Purpose |
+|-----------|---------|
+| `kotlin/plus/rua/project/` | Kotlin 源码（见 `kotlin/plus/rua/project/AGENTS.md`） |
+| `res/` | Android 资源文件（图标、主题、字符串） |
+| `assets/` | 原始资产文件（GIF 等） |
+
+## For AI Agents
+
+### Working In This Directory
+- 仅放置 Android 平台特有的配置和入口代码
+- 不要在此添加业务逻辑
+- 主题和颜色配置在 `res/values/` 中
+
+## Dependencies
+
+### Internal
+- `:shared` 模块 — `MainActivity` 调用 `App()` 入口
+
+<!-- MANUAL: -->
--- a/androidApp/src/main/kotlin/plus/rua/project/AGENTS.md
+++ b/androidApp/src/main/kotlin/plus/rua/project/AGENTS.md
@ -0,0 +1,29 @@
+<!-- Parent: ../../../../../../AGENTS.md -->
+<!-- Generated: 2026-05-20 | Updated: 2026-05-20 -->
+
+# project
+
+## Purpose
+Android 应用入口源码目录，仅包含 `MainActivity.kt`。
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `MainActivity.kt` | Android 入口 Activity，继承 `ComponentActivity`，调用 `setContent { App() }` |
+
+## Subdirectories
+无
+
+## For AI Agents
+
+### Working In This Directory
+- `MainActivity.kt` 应保持极简，不要添加额外逻辑
+- 所有 UI 和业务逻辑在 `:shared` 模块中
+
+## Dependencies
+
+### Internal
+- `shared/src/commonMain/kotlin/plus/rua/project/App.kt` — `App()` Composable 入口
+
+<!-- MANUAL: -->
--- a/iosApp/AGENTS.md
+++ b/iosApp/AGENTS.md
@ -0,0 +1,49 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-05-20 | Updated: 2026-05-20 -->
+
+# iosApp
+
+## Purpose
+iOS 应用入口，Xcode 项目结构。使用 SwiftUI 的 `ComposeUIViewController` 承载共享模块中的 Compose UI，共享模块通过 CocoaPods/SPM 集成为 framework。
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `iosApp.xcodeproj/project.pbxproj` | Xcode 项目配置 |
+| `iosApp/iOSApp.swift` | iOS 应用入口（`@main App`） |
+| `iosApp/ContentView.swift` | SwiftUI 视图，嵌入 `ComposeUIViewController` |
+| `iosApp/Info.plist` | iOS 应用信息配置 |
+| `Configuration/Config.xcconfig` | Xcode 构建设置 |
+
+## Subdirectories
+
+| Directory | Purpose |
+|-----------|---------|
+| `iosApp/` | Swift 源码和资源（见 `iosApp/iosApp/AGENTS.md`） |
+| `Configuration/` | Xcode 构建设置文件 |
+
+## For AI Agents
+
+### Working In This Directory
+- 不要在此目录添加业务逻辑；所有逻辑在 `:shared` 模块
+- 首次打开 Xcode 前需运行 `./gradlew :shared:generateDummyFramework`
+- 修改 `shared` 后需重新生成 framework
+
+### Testing Requirements
+- 打开 `iosApp/iosApp.xcworkspace` 在 Xcode 中运行
+- iOS 测试通过 Xcode 执行
+
+### Common Patterns
+- `ContentView` 使用 `UIViewControllerRepresentable` 包装 `ComposeUIViewController`
+- `MainViewController` 工厂在 `shared/src/iosMain/` 中定义
+
+## Dependencies
+
+### Internal
+- `:shared` 模块 — 作为 iOS framework 集成
+
+### External
+- SwiftUI, UIKit
+
+<!-- MANUAL: -->
--- a/iosApp/iosApp/AGENTS.md
+++ b/iosApp/iosApp/AGENTS.md
@ -0,0 +1,36 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-05-20 | Updated: 2026-05-20 -->
+
+# iosApp
+
+## Purpose
+iOS 应用的 Swift 源码和资源目录，包含 SwiftUI 入口和 Compose 嵌入视图。
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `iOSApp.swift` | iOS 应用入口，`@main struct iOSApp: App` |
+| `ContentView.swift` | SwiftUI 视图，通过 `UIViewControllerRepresentable` 嵌入 Compose |
+| `Info.plist` | iOS 应用配置 |
+| `Assets.xcassets/` | iOS 应用图标和颜色资源 |
+
+## Subdirectories
+
+| Directory | Purpose |
+|-----------|---------|
+| `Assets.xcassets/` | iOS 图标和颜色资源 |
+| `Preview Content/` | Xcode 预览资源 |
+
+## For AI Agents
+
+### Working In This Directory
+- 不要在此添加业务逻辑
+- `ContentView.swift` 中的 `MainViewController()` 来自 `:shared` 模块的 iOS 工厂
+
+## Dependencies
+
+### Internal
+- `:shared` 模块 — 通过 `MainViewController()` 提供 Compose UI
+
+<!-- MANUAL: -->
--- a/shared/AGENTS.md
+++ b/shared/AGENTS.md
@ -0,0 +1,49 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-05-20 | Updated: 2026-05-20 -->
+
+# shared
+
+## Purpose
+Kotlin Multiplatform 共享模块，包含所有 Compose UI、ViewModel 和业务逻辑。通过 `expect/actual` 机制为 Android 和 iOS 提供平台特定实现。这是项目的核心模块。
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `build.gradle.kts` | 共享模块构建配置（KMP 插件设置、source sets、依赖） |
+
+## Subdirectories
+
+| Directory | Purpose |
+|-----------|---------|
+| `src/androidMain/` | Android 平台特定实现（见 `src/androidMain/AGENTS.md`） |
+| `src/commonMain/` | 所有 Compose UI、ViewModel 和业务逻辑（见 `src/commonMain/AGENTS.md`） |
+| `src/commonTest/` | 共享测试套件（见 `src/commonTest/AGENTS.md`） |
+| `src/iosMain/` | iOS 平台特定实现（见 `src/iosMain/AGENTS.md`） |
+
+## For AI Agents
+
+### Working In This Directory
+- 所有功能代码应放在 `commonMain` 中以跨平台复用
+- 仅在 `androidMain` / `iosMain` 中放置平台特有实现
+- 修改 `commonMain` 后需运行 `:shared:allTests` 验证
+
+### Testing Requirements
+- 全部测试：`./gradlew :shared:allTests`
+- Android 主机测试：`./gradlew :shared:testAndroidHostTest`
+- 单类测试：`./gradlew :shared:testAndroidHostTest --tests "ClassName"`
+
+### Common Patterns
+- `expect` 声明在 `commonMain`，`actual` 实现在平台 source set
+- Compose 资源放在 `commonMain/composeResources/` 下
+- 包名：`plus.rua.project`（逻辑层）、`plus.rua.project.ui`（UI 层）
+
+## Dependencies
+
+### External
+- Compose Multiplatform 1.11.0, Material 3 1.10.0-alpha05
+- `kotlinx-datetime` 0.8.0, `kotlinx-coroutines`
+- `tyme4kt`（农历/节气）, `sketch` 4.4.0（GIF 显示）
+- `molecule`（测试用）
+
+<!-- MANUAL: -->
--- a/shared/src/androidMain/AGENTS.md
+++ b/shared/src/androidMain/AGENTS.md
@ -0,0 +1,37 @@
+<!-- Parent: ../../AGENTS.md -->
+<!-- Generated: 2026-05-20 | Updated: 2026-05-20 -->
+
+# androidMain
+
+## Purpose
+Android 平台特定实现 source set，包含 `expect/actual` 的 Android 端实现和预览工具。
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `kotlin/plus/rua/project/ComposeTrace.android.kt` | `composeTraceBeginSection` / `composeTraceEndSection` 的 Android 实现（路由到 `android.os.Trace`） |
+| `kotlin/plus/rua/project/Platform.android.kt` | `Platform` 接口的 Android 实现 |
+
+## Subdirectories
+
+| Directory | Purpose |
+|-----------|---------|
+| `kotlin/plus/rua/project/` | Android 平台实现源码（见 `kotlin/plus/rua/project/AGENTS.md`） |
+
+## For AI Agents
+
+### Working In This Directory
+- 仅放置 `commonMain` 中 `expect` 声明的 Android `actual` 实现
+- 不要在此添加业务逻辑
+
+## Dependencies
+
+### Internal
+- `shared/src/commonMain/kotlin/plus/rua/project/ComposeTrace.kt` — expect 声明
+- `shared/src/commonMain/kotlin/plus/rua/project/Platform.kt` — expect 声明
+
+### External
+- `android.os.Trace`
+
+<!-- MANUAL: -->
--- a/shared/src/androidMain/kotlin/plus/rua/project/AGENTS.md
+++ b/shared/src/androidMain/kotlin/plus/rua/project/AGENTS.md
@ -0,0 +1,25 @@
+<!-- Parent: ../../../../../../AGENTS.md -->
+<!-- Generated: 2026-05-20 | Updated: 2026-05-20 -->
+
+# project
+
+## Purpose
+Android 平台特定实现源码目录。
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `ComposeTrace.android.kt` | Trace 标记的 Android 实现 |
+| `Platform.android.kt` | 平台接口实现 |
+
+## Subdirectories
+无
+
+## Dependencies
+
+### Internal
+- `shared/src/commonMain/kotlin/plus/rua/project/ComposeTrace.kt`
+- `shared/src/commonMain/kotlin/plus/rua/project/Platform.kt`
+
+<!-- MANUAL: -->
--- a/shared/src/commonMain/AGENTS.md
+++ b/shared/src/commonMain/AGENTS.md
@ -0,0 +1,55 @@
+<!-- Parent: ../../AGENTS.md -->
+<!-- Generated: 2026-05-20 | Updated: 2026-05-20 -->
+
+# commonMain
+
+## Purpose
+KMP 共享核心模块，包含所有 Compose UI、ViewModel 状态管理、业务逻辑和跨平台接口声明。这是 YaYa 应用的主体代码所在。
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `kotlin/plus/rua/project/App.kt` | 应用根 Composable，提供 Material 主题和导航入口 |
+| `kotlin/plus/rua/project/AppInfo.kt` | 应用元数据（名称、版本、作者等） |
+| `kotlin/plus/rua/project/CalendarViewModel.kt` | 日历状态管理（选中日期、展开/折叠、月/周/年视图） |
+| `kotlin/plus/rua/project/ComposeTrace.kt` | `expect` 声明的 Trace 标记 API |
+| `kotlin/plus/rua/project/Platform.kt` | `expect` 声明的平台接口 |
+| `kotlin/plus/rua/project/ShiftPattern.kt` | 个人班次排期模型（WORK/OFF 循环） |
+
+## Subdirectories
+
+| Directory | Purpose |
+|-----------|---------|
+| `kotlin/plus/rua/project/` | 业务逻辑和根 Composable（见 `kotlin/plus/rua/project/AGENTS.md`） |
+| `kotlin/plus/rua/project/ui/` | UI 组件层（见 `kotlin/plus/rua/project/ui/AGENTS.md`） |
+| `composeResources/` | Compose 多平台资源（图片、文件）（见 `composeResources/AGENTS.md`） |
+
+## For AI Agents
+
+### Working In This Directory
+- 所有新功能代码优先放在 `commonMain` 以保持跨平台兼容
+- 仅在需要平台 API 时使用 `expect/actual` 模式
+- `CalendarViewModel.kt` 是核心状态枢纽，修改需谨慎
+
+### Testing Requirements
+- 修改后运行 `./gradlew :shared:allTests`
+- 状态逻辑测试在 `commonTest` 中
+
+### Common Patterns
+- `@Suppress("DEPRECATION")` 用于 `monthNumber` 访问时需加解释注释
+- 公共 `@Composable` 函数需要 KDoc（见 `COMMENTS.md`）
+- `Modifier` 参数始终放在签名最后
+- 回调参数使用 `on` 前缀（`onDateClick`、`onMonthChanged`）
+- UI 文本使用中文
+
+## Dependencies
+
+### External
+- Compose Multiplatform, Material 3
+- `kotlinx-datetime`, `kotlinx-coroutines`
+- `tyme4kt`（农历/节气/节日）
+- `sketch`（GIF 显示）
+- `androidx-lifecycle-viewmodel-compose`
+
+<!-- MANUAL: -->
--- a/shared/src/commonMain/composeResources/AGENTS.md
+++ b/shared/src/commonMain/composeResources/AGENTS.md
@ -0,0 +1,26 @@
+<!-- Parent: ../../../AGENTS.md -->
+<!-- Generated: 2026-05-20 | Updated: 2026-05-20 -->
+
+# composeResources
+
+## Purpose
+Compose Multiplatform 共享资源目录，存放跨平台可访问的图片和文件资源。
+
+## Key Files
+
+无（目录仅包含子目录）
+
+## Subdirectories
+
+| Directory | Purpose |
+|-----------|---------|
+| `drawable/` | 图片资源（图标、插图等） |
+| `files/` | 原始文件资源 |
+
+## For AI Agents
+
+### Working In This Directory
+- 资源通过 Compose 的 `Res` 对象访问（如 `Res.drawable.xxx`）
+- 添加新资源后需重新编译以生成访问代码
+
+<!-- MANUAL: -->
--- a/shared/src/commonMain/kotlin/plus/rua/project/AGENTS.md
+++ b/shared/src/commonMain/kotlin/plus/rua/project/AGENTS.md
@ -0,0 +1,47 @@
+<!-- Parent: ../../../../../../AGENTS.md -->
+<!-- Generated: 2026-05-20 | Updated: 2026-05-20 -->
+
+# project
+
+## Purpose
+共享模块的业务逻辑层，包含根 Composable、ViewModel、平台接口和班次模型。
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `App.kt` | 应用根 Composable，设置 Material 3 主题，管理月/年视图切换和关于页面导航 |
+| `AppInfo.kt` | 应用信息常量：名称、版本号、构建日期、作者、仓库地址、许可证 |
+| `CalendarViewModel.kt` | 日历核心状态管理：选中日期、折叠状态、月/周/年模式、ISO 周数计算 |
+| `ComposeTrace.kt` | `expect` 声明的 Trace 标记 API（Android 实现用 Systrace，iOS no-op） |
+| `Platform.kt` | `expect` 声明的平台接口 |
+| `ShiftPattern.kt` | 个人班次排期模型：基于锚定日期和周期长度的 WORK/OFF 状态计算 |
+
+## Subdirectories
+
+| Directory | Purpose |
+|-----------|---------|
+| `ui/` | 所有 UI 组件（见 `ui/AGENTS.md`） |
+
+## For AI Agents
+
+### Working In This Directory
+- `CalendarViewModel.kt` 是核心状态枢纽，包含 `selectedDate`、`isCollapsed`、`isYearView` 等 StateFlow
+- `ShiftPattern` 使用模运算：`(date - anchorDate) mod cycle.size`
+- 修改状态逻辑后务必运行 `commonTest` 中的测试
+
+### Testing Requirements
+- `ShiftPatternTest` — 班次计算验证
+- `CalendarViewModelTest` — ViewModel 状态流验证
+- `CalendarViewModelStateTest` — 状态转换验证
+
+## Dependencies
+
+### Internal
+- `ui/` 目录 — UI 组件消费 ViewModel 状态
+
+### External
+- `kotlinx-datetime`, `kotlinx-coroutines`
+- `tyme4kt`（农历日期转换）
+
+<!-- MANUAL: -->
--- a/shared/src/commonMain/kotlin/plus/rua/project/ui/AGENTS.md
+++ b/shared/src/commonMain/kotlin/plus/rua/project/ui/AGENTS.md
@ -0,0 +1,61 @@
+<!-- Parent: ../../../../../AGENTS.md -->
+<!-- Generated: 2026-05-20 | Updated: 2026-05-20 -->
+
+# ui
+
+## Purpose
+日历应用的所有 UI 组件层，基于 Compose Multiplatform + Material 3 构建。包含月视图、周视图、年视图、底部卡片、日期单元格、顶部标题栏以及关于/许可证页面。
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `CalendarMonthView.kt` | 月视图主屏幕：组合 MonthHeader + WeekdayHeader + CalendarPager + BottomCard，管理折叠/展开状态 |
+| `CalendarMonthPage.kt` | 单月页面：6×7 日期网格，带选中日期高亮和非选中周压缩动画 |
+| `CalendarPager.kt` | 月视图水平翻页器：`Int.MAX_VALUE` 页，映射到 yearMonth |
+| `WeekPager.kt` | 周视图水平翻页器：折叠状态下替代 CalendarPager，单周分页 |
+| `YearGridView.kt` | 年视图：4×3 迷你月网格，支持年份导航 |
+| `MonthHeader.kt` | 月视图标题栏：显示年份月份 + ISO 周数 |
+| `WeekdayHeader.kt` | 固定星期标题行：「一二三四五六日」 |
+| `DayCell.kt` | 单个日期单元格：支持选中/今天/班次状态样式 |
+| `BottomCard.kt` | 底部卡片：拖拽手柄，驱动折叠/展开手势，显示农历、节气、节假日和班次状态 |
+| `AboutScreen.kt` | 关于页面：应用信息、开源许可入口 |
+| `LicensesScreen.kt` | 许可证列表页面 |
+| `Licenses.kt` | 许可证数据（依赖项名称 + 许可证文本） |
+| `AnimatedGif.kt` | GIF 动画显示组件（基于 sketch） |
+| `CalendarUtils.kt` | 日历工具：pager 常量、页码↔日期转换算法 |
+
+## Subdirectories
+无
+
+## For AI Agents
+
+### Working In This Directory
+- 新增 UI 组件保持 `Modifier` 参数最后
+- 公共 `@Composable` 需要 KDoc（见 `COMMENTS.md`）
+- 所有 UI 文本使用中文
+- `CalendarMonthView` 是顶层屏幕组件，修改前理解折叠动画和 pager 交互
+
+### Testing Requirements
+- `CalendarUtilsTest` — 页码与日期转换验证
+- `CalendarUtilsExtraTest` — 边界情况测试
+
+### Common Patterns
+- Pager 使用 `Int.MAX_VALUE` 页，中心点为 `Int.MAX_VALUE / 2`
+- 折叠动画通过 `collapseProgress`（0f=月视图, 1f=周视图）驱动
+- `WeekPager` 仅在完全折叠时替换 `CalendarPager`
+- 日历网格为 6 行 × 7 列（ISO 周，周一为起始）
+
+## Dependencies
+
+### Internal
+- `shared/src/commonMain/kotlin/plus/rua/project/CalendarViewModel.kt` — 状态源
+- `shared/src/commonMain/kotlin/plus/rua/project/ShiftPattern.kt` — 班次数据
+
+### External
+- Compose Multiplatform, Material 3
+- `kotlinx-datetime`
+- `tyme4kt`（农历、节气、节日）
+- `sketch`（GIF）
+
+<!-- MANUAL: -->
--- a/shared/src/commonTest/AGENTS.md
+++ b/shared/src/commonTest/AGENTS.md
@ -0,0 +1,34 @@
+<!-- Parent: ../../AGENTS.md -->
+<!-- Generated: 2026-05-20 | Updated: 2026-05-20 -->
+
+# commonTest
+
+## Purpose
+共享模块的单元测试 source set，包含 ViewModel、班次模型和日历工具函数的测试。
+
+## Key Files
+
+无（目录仅包含子目录）
+
+## Subdirectories
+
+| Directory | Purpose |
+|-----------|---------|
+| `kotlin/plus/rua/project/` | 核心逻辑测试（见 `kotlin/plus/rua/project/AGENTS.md`） |
+| `kotlin/plus/rua/project/ui/` | UI 工具函数测试（见 `kotlin/plus/rua/project/ui/AGENTS.md`） |
+
+## For AI Agents
+
+### Working In This Directory
+- 测试使用 `kotlin.test` 和 molecule（Turbine）进行状态流断言
+- 新增测试后运行 `./gradlew :shared:allTests`
+- 测试类名遵循 `*Test.kt` 约定
+
+## Dependencies
+
+### External
+- `kotlin-test`
+- `kotlinx-coroutines-test`
+- `molecule`（Turbine 风格的状态流测试）
+
+<!-- MANUAL: -->
--- a/shared/src/commonTest/kotlin/plus/rua/project/AGENTS.md
+++ b/shared/src/commonTest/kotlin/plus/rua/project/AGENTS.md
@ -0,0 +1,35 @@
+<!-- Parent: ../../../../../../AGENTS.md -->
+<!-- Generated: 2026-05-20 | Updated: 2026-05-20 -->
+
+# project
+
+## Purpose
+核心逻辑层测试，覆盖 ViewModel 状态管理和班次模型计算。
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `ShiftPatternTest.kt` | `ShiftPattern` 班次状态计算测试 |
+| `CalendarViewModelTest.kt` | `CalendarViewModel` 状态流和行为测试 |
+| `CalendarViewModelStateTest.kt` | ViewModel 状态转换边界测试 |
+
+## Subdirectories
+
+| Directory | Purpose |
+|-----------|---------|
+| `ui/` | UI 工具函数测试（见 `ui/AGENTS.md`） |
+
+## For AI Agents
+
+### Working In This Directory
+- 修改 `CalendarViewModel` 或 `ShiftPattern` 后应更新对应测试
+- 测试使用 molecule 进行状态流断言
+
+## Dependencies
+
+### Internal
+- `shared/src/commonMain/kotlin/plus/rua/project/ShiftPattern.kt`
+- `shared/src/commonMain/kotlin/plus/rua/project/CalendarViewModel.kt`
+
+<!-- MANUAL: -->
--- a/shared/src/commonTest/kotlin/plus/rua/project/ui/AGENTS.md
+++ b/shared/src/commonTest/kotlin/plus/rua/project/ui/AGENTS.md
@ -0,0 +1,30 @@
+<!-- Parent: ../../../../../AGENTS.md -->
+<!-- Generated: 2026-05-20 | Updated: 2026-05-20 -->
+
+# ui
+
+## Purpose
+UI 工具函数测试，覆盖日历工具类 `CalendarUtils` 的日期转换算法。
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `CalendarUtilsTest.kt` | `CalendarUtils` 核心函数测试：页码↔年月、周起始计算 |
+| `CalendarUtilsExtraTest.kt` | `CalendarUtils` 边界情况和额外场景测试 |
+
+## Subdirectories
+无
+
+## For AI Agents
+
+### Working In This Directory
+- 修改 `CalendarUtils.kt` 中的转换算法后应更新测试
+- 测试覆盖 `pageToYearMonth`、`yearMonthToPage`、`pageToWeekMonday` 等函数
+
+## Dependencies
+
+### Internal
+- `shared/src/commonMain/kotlin/plus/rua/project/ui/CalendarUtils.kt`
+
+<!-- MANUAL: -->
--- a/shared/src/iosMain/AGENTS.md
+++ b/shared/src/iosMain/AGENTS.md
@ -0,0 +1,39 @@
+<!-- Parent: ../../AGENTS.md -->
+<!-- Generated: 2026-05-20 | Updated: 2026-05-20 -->
+
+# iosMain
+
+## Purpose
+iOS 平台特定实现 source set，包含 `ComposeUIViewController` 工厂和 `expect/actual` 的 iOS 端实现。
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `kotlin/plus/rua/project/MainViewController.kt` | `ComposeUIViewController` 工厂函数，iOS 应用通过此入口加载 Compose UI |
+| `kotlin/plus/rua/project/ComposeTrace.ios.kt` | Trace 标记的 iOS 实现（no-op） |
+| `kotlin/plus/rua/project/Platform.ios.kt` | `Platform` 接口的 iOS 实现 |
+
+## Subdirectories
+
+| Directory | Purpose |
+|-----------|---------|
+| `kotlin/plus/rua/project/` | iOS 平台实现源码（见 `kotlin/plus/rua/project/AGENTS.md`） |
+
+## For AI Agents
+
+### Working In This Directory
+- 仅放置 `commonMain` 中 `expect` 声明的 iOS `actual` 实现
+- `MainViewController.kt` 是 iOS 侧的 Compose 入口，保持简洁
+
+## Dependencies
+
+### Internal
+- `shared/src/commonMain/kotlin/plus/rua/project/App.kt` — Compose 根界面
+- `shared/src/commonMain/kotlin/plus/rua/project/ComposeTrace.kt` — expect 声明
+- `shared/src/commonMain/kotlin/plus/rua/project/Platform.kt` — expect 声明
+
+### External
+- `platform.UIKit`
+
+<!-- MANUAL: -->
--- a/shared/src/iosMain/kotlin/plus/rua/project/AGENTS.md
+++ b/shared/src/iosMain/kotlin/plus/rua/project/AGENTS.md
@ -0,0 +1,27 @@
+<!-- Parent: ../../../../../../AGENTS.md -->
+<!-- Generated: 2026-05-20 | Updated: 2026-05-20 -->
+
+# project
+
+## Purpose
+iOS 平台特定实现源码目录。
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `MainViewController.kt` | `ComposeUIViewController` 工厂，iOS 应用入口 |
+| `ComposeTrace.ios.kt` | Trace 标记的 iOS no-op 实现 |
+| `Platform.ios.kt` | 平台接口实现 |
+
+## Subdirectories
+无
+
+## Dependencies
+
+### Internal
+- `shared/src/commonMain/kotlin/plus/rua/project/App.kt`
+- `shared/src/commonMain/kotlin/plus/rua/project/ComposeTrace.kt`
+- `shared/src/commonMain/kotlin/plus/rua/project/Platform.kt`
+
+<!-- MANUAL: -->