CLAUDE.md

本文件为 Claude Code (claude.ai/code) 在此代码库中工作时提供指导。

项目概述

NewsReader 是一个使用 Kotlin 和 Jetpack Compose 构建的现代化 Android RSS 阅读器应用。它支持 RSS/Atom 订阅源、基于 CSS 选择器的自定义 HTML 解析，以及基于本地 SQLite 的离线阅读功能。

架构： MVVM + Repository 模式 | UI： Jetpack Compose (Material 3) | 数据库： Room (SQLite, v9) + KSP 2.0.21 | 异步： Coroutines + Flow | 构建： Gradle 8.13.2 + Kotlin 2.0.21

常用命令

./gradlew build                    # 构建所有变体
./gradlew assembleDebug            # 构建 Debug APK
./gradlew installDebug             # 安装 Debug APK 到设备
adb shell am start -n com.lengyuefenghua.newsreader/.MainActivity  # 启动应用
./gradlew test                     # 运行单元测试
./gradlew connectedAndroidTest      # 运行设备测试

重要： 完成功能或修复后务必执行

installDebug

并启动应用验证。

依赖管理： 核心版本在

gradle/libs.versions.toml

，部分库直接在

app/build.gradle.kts

指定。添加新依赖时优先检查版本目录。

架构模式

分层结构： UI (Compose) → ViewModel (StateFlow + Channel) → Repository (数据单一来源) → Data (Room + Network)

核心决策：

状态管理： ViewModels 使用私有
```
_state
```
+ 公共
```
state
```
模式，
```
Channel
```
处理一次性事件，UI 通过
```
collectAsState()
```
收集
Repository：
```
NewsRepository
```
处理所有数据操作，数据库是单一数据源，网络同步到 DB，所有 DB 操作使用
```
Dispatchers.IO
```
导航： 底部 3 标签页（Timeline、订阅、Profile），URL 参数用
```
URLEncoder.encode(url, "UTF-8")
```
编码
内容解析： 标准 RSS/Atom 或自定义 HTML 解析（CSS 选择器），WebView 集成支持动态内容，
```
AutoExtractor.kt
```
作为兜底方案

开发流程规范

重要：所有代码修改必须遵循以下流程

1. 需求确认 → 2. 方案设计 → 3. 用户确认 → 4. 执行修改

方案设计： 说明文件路径、修改内容、原因和预期效果，评估影响范围和风险

用户确认： 使用

AskUserQuestion

工具弹出 2-4 个选项（如"确认执行"、"调整方案"、"取消操作"），必须包含"其他"选项。未经明确确认不得执行修改。

适用场景： 新增功能、Bug 修复、代码重构、配置修改、文件结构变更需要先说明方案。文件读取、信息查询、git 查看、编译运行无需确认。

工作流程示例：

用户: "添加一个备份按钮"
我: "修改方案：文件 SourceManagerScreen.kt，在 TopAppBar 添加按钮调用 ViewModel.saveToFile()"
我: [弹出 AskUserQuestion 选项：确认执行/调整方案/取消操作/其他]
用户: [点击"确认执行"] → 我执行修改

注意事项： 选项标签简短（≤12字符），说明清晰，标记推荐选项，方案调整需重新确认。

代码规范

命名： 类名 PascalCase，函数/变量 camelCase，常量 UPPER_SNAKE_CASE，私有状态前缀

，可观察状态后缀

State

Flow

文件组织：

data/              # 实体类、DAOs、Repository
ui/screens/        # 屏幕级 Compose UI
ui/components/     # 可复用 UI 组件
viewmodel/         # ViewModels
utils/             # 解析器、工具类

关键文件：

data/AppDatabase.kt

（数据库配置）、

data/NewsRepository.kt

（数据操作）、

MainActivity.kt

（应用入口）、

utils/RssParser.kt

、

utils/HtmlParser.kt

、

utils/AutoExtractor.kt

、

gradle/libs.versions.toml

核心实现细节

Room 数据库： 版本 9 schema，实体

Article

（文章：id、title、content、sourceName、pubDate、url、isRead、isFavorite、imageUrl、readTimestamp、readDuration）和

Source

（订阅源：id、name、url、iconUrl、isCustom、requestMethod、enablePcUserAgent、rule* 字段、useAutoExtract）。DAOs 返回

Flow

或

suspend

函数，修改 schema 需递增版本并提供迁移。

Compose UI： 可选参数最后带默认值，Modifier 顺序（尺寸→布局→视觉→交互），参数顺序（必需→可选→modifier）

Coroutines & Flow：

viewModelScope.launch {
    withContext(Dispatchers.IO) { repository.operation() }
}
combine(flow1, flow2) { data1, data2 -> /* combine */ }
    .stateIn(viewModelScope, SharingStarted.Lazily, initialValue)

网络与解析： OkHttp 4.12.0 + Jsoup 1.17.2 + Gson 2.10.1 + Coil 2.6.0。

try-catch

处理解析，

Log.d()

Log.e()

记录日志，优先用

?.

和

?:

而非

!!

调试系统

内置调试控制台（

DebugConsoleScreen.kt

）：从 Profile 界面访问，显示树形结构解析日志、字符计数和内容预览。使用

DebugHelper.kt

格式化日志，通过

LogUtils.kt

支持 Logcat 输出。

常见问题

主线程数据库操作： Room 务必使用
```
Dispatchers.IO
```
URL 编码： 导航参数需要
```
URLEncoder.encode(url, "UTF-8")
```
中文文本： 将
```
\u00a0
```
替换为标准空格
WebView 切换： 检查
```
about:blank
```
状态提升： 状态保存在 ViewModels
内容提取：
```
useAutoExtract = true
```
优先级高于
```
ruleContent
```
User-Agent： 默认
```
UA_ANDROID
```
，阻止移动端时设置
```
enablePcUserAgent = true
```
KSP： Room 需要 KSP 插件，版本必须匹配 Kotlin（2.0.21）

测试策略

单元测试在

app/src/test/

（业务逻辑、解析器），设备测试在

app/src/androidTest/

（UI、数据库、集成）。使用

TestDispatcher

测试 ViewModels，

ComposeTestRule

测试 Compose UI。

版本信息

SDK： compileSdk 36，minSdk 28，targetSdk 36 | 版本： versionCode 1，versionName "1.0" | Application ID： com.lengyuefenghua.newsreader

CLAUDE.md

本文件为 Claude Code (claude.ai/code) 在此代码库中工作时提供指导。

项目概述

常用命令

./gradlew build                    # 构建所有变体
./gradlew assembleDebug            # 构建 Debug APK
./gradlew installDebug             # 安装 Debug APK 到设备
adb shell am start -n com.lengyuefenghua.newsreader/.MainActivity  # 启动应用
./gradlew test                     # 运行单元测试
./gradlew connectedAndroidTest      # 运行设备测试

重要： 完成功能或修复后务必执行

installDebug

并启动应用验证。

依赖管理： 核心版本在

gradle/libs.versions.toml

，部分库直接在

app/build.gradle.kts

指定。添加新依赖时优先检查版本目录。

架构模式

分层结构： UI (Compose) → ViewModel (StateFlow + Channel) → Repository (数据单一来源) → Data (Room + Network)

核心决策：

状态管理： ViewModels 使用私有
```
_state
```
+ 公共
```
state
```
模式，
```
Channel
```
处理一次性事件，UI 通过
```
collectAsState()
```
收集
Repository：
```
NewsRepository
```
处理所有数据操作，数据库是单一数据源，网络同步到 DB，所有 DB 操作使用
```
Dispatchers.IO
```
导航： 底部 3 标签页（Timeline、订阅、Profile），URL 参数用
```
URLEncoder.encode(url, "UTF-8")
```
编码
内容解析： 标准 RSS/Atom 或自定义 HTML 解析（CSS 选择器），WebView 集成支持动态内容，
```
AutoExtractor.kt
```
作为兜底方案

开发流程规范

重要：所有代码修改必须遵循以下流程

1. 需求确认 → 2. 方案设计 → 3. 用户确认 → 4. 执行修改

方案设计： 说明文件路径、修改内容、原因和预期效果，评估影响范围和风险

用户确认： 使用

AskUserQuestion

工具弹出 2-4 个选项（如"确认执行"、"调整方案"、"取消操作"），必须包含"其他"选项。未经明确确认不得执行修改。

适用场景： 新增功能、Bug 修复、代码重构、配置修改、文件结构变更需要先说明方案。文件读取、信息查询、git 查看、编译运行无需确认。

工作流程示例：

用户: "添加一个备份按钮"
我: "修改方案：文件 SourceManagerScreen.kt，在 TopAppBar 添加按钮调用 ViewModel.saveToFile()"
我: [弹出 AskUserQuestion 选项：确认执行/调整方案/取消操作/其他]
用户: [点击"确认执行"] → 我执行修改

注意事项： 选项标签简短（≤12字符），说明清晰，标记推荐选项，方案调整需重新确认。

代码规范

命名： 类名 PascalCase，函数/变量 camelCase，常量 UPPER_SNAKE_CASE，私有状态前缀

，可观察状态后缀

State

Flow

文件组织：

data/              # 实体类、DAOs、Repository
ui/screens/        # 屏幕级 Compose UI
ui/components/     # 可复用 UI 组件
viewmodel/         # ViewModels
utils/             # 解析器、工具类

关键文件：

data/AppDatabase.kt

（数据库配置）、

data/NewsRepository.kt

（数据操作）、

MainActivity.kt

（应用入口）、

utils/RssParser.kt

、

utils/HtmlParser.kt

、

utils/AutoExtractor.kt

、

gradle/libs.versions.toml

核心实现细节

Room 数据库： 版本 9 schema，实体

Article

（文章：id、title、content、sourceName、pubDate、url、isRead、isFavorite、imageUrl、readTimestamp、readDuration）和

Source

（订阅源：id、name、url、iconUrl、isCustom、requestMethod、enablePcUserAgent、rule* 字段、useAutoExtract）。DAOs 返回

Flow

或

suspend

函数，修改 schema 需递增版本并提供迁移。

Compose UI： 可选参数最后带默认值，Modifier 顺序（尺寸→布局→视觉→交互），参数顺序（必需→可选→modifier）

Coroutines & Flow：

viewModelScope.launch {
    withContext(Dispatchers.IO) { repository.operation() }
}
combine(flow1, flow2) { data1, data2 -> /* combine */ }
    .stateIn(viewModelScope, SharingStarted.Lazily, initialValue)

网络与解析： OkHttp 4.12.0 + Jsoup 1.17.2 + Gson 2.10.1 + Coil 2.6.0。

try-catch

处理解析，

Log.d()

Log.e()

记录日志，优先用

?.

和

?:

而非

!!

调试系统

内置调试控制台（

DebugConsoleScreen.kt

）：从 Profile 界面访问，显示树形结构解析日志、字符计数和内容预览。使用

DebugHelper.kt

格式化日志，通过

LogUtils.kt

支持 Logcat 输出。

常见问题

主线程数据库操作： Room 务必使用
```
Dispatchers.IO
```
URL 编码： 导航参数需要
```
URLEncoder.encode(url, "UTF-8")
```
中文文本： 将
```
\u00a0
```
替换为标准空格
WebView 切换： 检查
```
about:blank
```
状态提升： 状态保存在 ViewModels
内容提取：
```
useAutoExtract = true
```
优先级高于
```
ruleContent
```
User-Agent： 默认
```
UA_ANDROID
```
，阻止移动端时设置
```
enablePcUserAgent = true
```
KSP： Room 需要 KSP 插件，版本必须匹配 Kotlin（2.0.21）

测试策略

单元测试在

app/src/test/

（业务逻辑、解析器），设备测试在

app/src/androidTest/

（UI、数据库、集成）。使用

TestDispatcher

测试 ViewModels，

ComposeTestRule

测试 Compose UI。

版本信息

SDK： compileSdk 36，minSdk 28，targetSdk 36 | 版本： versionCode 1，versionName "1.0" | Application ID： com.lengyuefenghua.newsreader

CLAUDE.md

CLAUDE.md

项目概述

常用命令

架构模式

开发流程规范

1. 需求确认 → 2. 方案设计 → 3. 用户确认 → 4. 执行修改

代码规范

核心实现细节

调试系统

常见问题

测试策略

版本信息

相关文档

Related Skills

Markdown Converter

Nano Banana Pro

1password

CLAUDE.md

项目概述

常用命令

架构模式

开发流程规范

1. 需求确认 → 2. 方案设计 → 3. 用户确认 → 4. 执行修改

代码规范

核心实现细节

调试系统

常见问题

测试策略

版本信息

相关文档