From 433770d28583b426ca22804e8f04ed26ad4002ed Mon Sep 17 00:00:00 2001
From: WaterRain <109326062+CATMIAOZHI@users.noreply.github.com>
Date: Mon, 20 Jul 2026 09:24:23 +0000
Subject: [PATCH] =?UTF-8?q?docs:=20AGENTS.md=20+=20README.md=20=E5=90=8C?=
 =?UTF-8?q?=E6=AD=A5=E6=B5=8B=E8=AF=95=E4=BD=93=E7=B3=BB=E3=80=81CI=20work?=
 =?UTF-8?q?flow=E3=80=81PR=20=E5=AE=A1=E8=AE=A1=E7=BA=A2=E7=BA=BF?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

AGENTS.md:
- 新增测试体系段落（5 文件 78 用例）
- 新增 CI workflow 段落（3 job 串行、签名 fallback、artifact 上传）
- 新增重大修改 PR 审计红线（构建/签名/CI/架构变更必须 PR 提交）
- 关键命令段补 testDebugUnitTest

README.md:
- 顶部加 CI badge
- 构建说明补 testDebugUnitTest 命令
---
 AGENTS.md | 31 +++++++++++++++++++++++++++++++
 README.md |  4 ++++
 2 files changed, 35 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index cd455be..b54bf67 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -165,6 +165,33 @@ Expanded（平板，≥840dp）：
 
 > `StackedBarChart` / `LineChart` 的 `tooltipBucket` 初始值为 `buckets.lastOrNull()`，进入图表页即可看到最新时段数值详情，暗示图表可交互。
 
+**测试体系**：
+
+- 纯 JVM 单元测试（`testDebugUnitTest`），无 Android 框架依赖，无网络
+- 5 个测试文件，78 个用例：
+  - `OllamaRepositoryTest`（16）— HTML 解析：plan/百分比/时间戳/模型次数/空输入
+  - `OpenCodeGoRepositoryTest`（10）— SSR hydration 解析：三窗口/嵌套/缺失字段
+  - `FormatUtilsTest`（18）— `formatAmount`/`formatResetInSec`/`formatResetForWidget`/`normalizeWindowLabel`
+  - `FormatCodexPrimaryLabelTest`（9）— `formatCodexPrimaryLabel`：null fallback/大小写/未知值
+  - `CodexRepositoryTest`（25）— `durationLabel` 阈值 + `parseUsageWindows` JsonNull 安全 + `parseSseResponse` SSE 解析
+- CodexRepository 中 `parseUsageWindows`/`durationLabel`/`UsageWindow` 为 `internal`（companion object），`parseSseResponse` 为 `internal` 顶层函数——不使用实例状态，便于测试直接调用
+
+**CI workflow（`.github/workflows/ci.yml`）**：
+
+- 触发：push main / 所有 PR
+- 3 个 job 串行（test 通过后才构建）：
+  1. `test`：`testDebugUnitTest` + `lintDebug`，上传 XML 测试报告 + lint 报告 artifact
+  2. `build-debug`：`assembleDebug`，上传 Debug APK artifact
+  3. `build-release`：`assembleRelease` + APK 完整性验证（`AndroidManifest.xml` + `resources.arsc` + `res/`），上传 Release APK artifact
+- Release 签名 fallback：CI 无 `release.jks`，`build.gradle.kts` 自动 fallback 到 `~/.android/debug.keystore`；CI 额外步骤确保 debug keystore 存在
+- artifact 保留 14 天
+
+**重大修改 PR 审计红线**：
+
+> ⚠️ 重大修改（构建配置、签名、CI、架构变更、新服务接入）必须通过 PR 提交，不能直接 push main。
+> PR 触发 CI 三 job 全部通过后才可合并：单元测试 + lint + Debug/Release APK 构建验证。
+> Release APK 完整性验证（manifest + arsc + res/）是防止 ARM64 Proot 构建问题再次发生的最后防线。
+
 ## RemoteViews 兼容性红线
 
 以下元素在 Widget 布局中**不可用**，会导致「载入出现问题」：
@@ -183,6 +210,10 @@ Expanded（平板，≥840dp）：
 cd /data/user/0/com.ai.assistance.operit/files/workspace/Rainytoken
 export ANDROID_HOME=$HOME/Android
 export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-arm64
+
+./gradlew testDebugUnitTest
+# 78 个单元测试，纯 JVM，无设备依赖
+
 ./gradlew assembleDebug
 # Debug APK: app/build/outputs/apk/debug/app-debug.apk
 
diff --git a/README.md b/README.md
index cdfb9d2..c7bb517 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,7 @@
 
 > *"AI 用量，尽在掌握 — AI Balance & Usage at a Glance"* 🐱✨
 
+[![CI](https://github.com/CATMIAOZHI/Rainytoken/actions/workflows/ci.yml/badge.svg)](https://github.com/CATMIAOZHI/Rainytoken/actions/workflows/ci.yml)
 [![Release](https://github.com/CATMIAOZHI/Rainytoken/actions/workflows/release.yml/badge.svg)](https://github.com/CATMIAOZHI/Rainytoken/actions)
 [![Version](https://img.shields.io/github/v/release/CATMIAOZHI/Rainytoken?color=ff85a2)](https://github.com/CATMIAOZHI/Rainytoken/releases)
 Android AI 余额与用量查询 APP —— 统一查看 DeepSeek、OpenCode Go、CommandCode Go、Codex / ChatGPT Plus、Ollama Pro 的余额与用量配额。粉色调品牌 UI，配套桌面小组件。
@@ -141,6 +142,9 @@ Rainytoken/
 
 ### 方式二：命令行
 ```bash
+# 运行单元测试
+./gradlew testDebugUnitTest
+
 # 构建 Debug APK
 ./gradlew assembleDebug
 # APK 输出：app/build/outputs/apk/debug/app-debug.apk