# Moneybook Maintain

> 「记一笔」MoneyBook（com.andersonlin.moneybook）Android 本地记账应用的维护 Skill。覆盖工程结构与现状、构建出包、版本升级与 GitHub 发布、数据库迁移验证、README/文档/截图维护、历史踩坑排查。当用户需要继续开发、改版、修复、发布该应用，或回答关于 keystore、License、截图板块、软著文档等问题时使用。

- Skill: `andersonlin4/moneybook-maintain` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add andersonlin4/moneybook-maintain`
- Raw SKILL.md: https://api.skillmd.com/api/skills/andersonlin4/moneybook-maintain/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: AndersOnLin4 (https://skillmd.com/u/andersonlin4)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/andersonlin4/moneybook-maintain

---


# 记一笔 MoneyBook 维护 Skill

「记一笔」Android 记账应用（Kotlin + Jetpack Compose + Room + MVVM，零网络权限）的维护手册。所有路径、版本、约束均已固定，直接复用，避免重复踩坑。会话级笔记另见 `G:\文档\网络学习笔记\记账工具项目\`。

## 环境与路径（固定事实，不可变）

- **工程根目录**：`G:\Andersonlin4-design 记账工具`（唯一 workspace，一切产物放这里）
- **本地工具链**（`tools\`）：jdk17 ｜ android-sdk（platform 34 / build-tools 34.0.0）｜ gradle-8.9 ｜ gradle-home（GRADLE_USER_HOME）｜ mingit ｜ gh ｜ migtest（迁移测试）
- **文档来源**：`G:\文档\网络学习笔记\`（功能清单、项目档案、提示词积累）｜ `G:\文档\记账工具\`（截图板块、本 skill）
- **真机**：小米 HyperOS 3.0.5.0（Android 15）；minSdk 28 / targetSdk 34 / compileSdk 34
- **GitHub**：https://github.com/AndersOnLin4/moneybook（公开）

详见 [references/project.md](references/project.md)

## 关键约束（必须遵守）

1. **C 盘敏感**：工具链、依赖缓存、构建产物全部在 G 盘；gradle 用 tools 本地发行版，绝不装系统级环境。
2. **零网络权限**：应用不申请 INTERNET / ACCESS_NETWORK_STATE，新功能不得引入联网依赖，只能使用本地 Jetpack / 开源库。
3. **版本号联动**：只在 `app/build.gradle.kts` 改 versionCode / versionName；UI 三处显示统一读 `BuildConfig.VERSION_NAME`（需 buildConfig=true），禁止硬编码版本文案。
4. **迁移即验证**：任何 Room schema 变更必须同步 MIGRATION 并跑 `tools\migtest`（真实 SQLite 引擎，累计 33 项断言）通过后才能发布。
5. **Release 卫生**：补丁版替换前一版（删旧 release+tag）；**v1.7.1 为更名纪念版，永久保留**；发布前必须 aapt2 dump badging 校验。
6. **README 风格定版**：面向用户、功能全面、语气平实、emoji 适量、禁营销口吻与创作者自我宣传（详见 [references/docs.md](references/docs.md)）。
7. **签名安全**：`keystore\release.keystore` 与 `local.properties` 密码绝不提交 git（已 gitignore），提醒用户按《密钥库备份说明》另行备份。

## 调用方式

本 skill 为知识型 skill，无脚本。当用户提出该工程的开发 / 改版 / 发布 / 排查需求时：

1. 先读 [references/project.md](references/project.md) 确认工程现状与资产。
2. 按需求匹配下方功能域，读取对应 reference 执行。
3. 遇到报错 / 异常，先查 [references/pitfalls.md](references/pitfalls.md)，避免重复排查。

## 功能域

### 工程结构与现状

技术栈版本、数据库模型、目录结构、版本状态、文件资产、GitHub Releases 清单。详见 [references/project.md](references/project.md)

### 构建与发布

本地构建命令、aapt2 校验、版本号规则、签名说明、GitHub 发布全流程。详见 [references/build-release.md](references/build-release.md)

### 踩坑与排查

历史上全部 bug 的现象 / 根因 / 修复（requestCode、指纹、迁移、附件、锁屏豁免、图表导出等）。详见 [references/pitfalls.md](references/pitfalls.md)

### README / 文档 / 截图

README 风格定版结论、截图板块规范、docs/ 五文档同步规则、发布说明写法。详见 [references/docs.md](references/docs.md)

## 踩坑速查（最高频）

1. HyperOS 崩溃「Can only use lower 16 bits for requestCode」→ 权限请求与文件选择器用固定 requestCode（0x1111~0x5555）
2. 指纹「Activity 不可用」/ 闪退 → MainActivity 必须继承 FragmentActivity
3. 数据库迁移崩溃 → 重建表而非 ALTER 补列；改完跑 migtest
4. 附件变 `.bin` → safeExtension 查 DISPLAY_NAME，恢复按备份 JSON 的 image 类型
5. 导入 `.mbk` 灰色不可选 → 文件选择器取消 MIME 过滤（type="*/*"）
6. 从相册 / 文件选择器返回被要求重新解锁 → suppressNextLock 豁免系统跳转
7. 版本显示与安装包脱节 → 统一读 BuildConfig.VERSION_NAME（已修）
8. PowerShell 跑 gh：别用 `-q` 内嵌复杂 jq；git push 的 NativeCommandError 是 stderr 误报
9. 构建别设 ANDROID_USER_HOME / ANDROID_SDK_HOME（破坏 AGP）

## 注意事项

- **改动发布前先与用户确认**；不做用户未要求的重构或大改。
- **诚实告知利弊**：不夸大测试覆盖范围（迁移测试仅覆盖 schema 迁移；真机用例靠手工执行）。
- **回复风格**：中文、简洁；拒绝娱乐化与空话；用户对磁盘空间敏感，涉及安装包/缓存时主动说明落盘位置。
- **处理图片尽量不调用识图**（用户要求省 token），文字化处理路径与布局即可。