From fedff4439850a8bd038c0a09e183b8a1862ad911 Mon Sep 17 00:00:00 2001 From: QiuSW <105186638@qq.com> Date: Tue, 4 Aug 2026 17:20:08 +0800 Subject: [PATCH] docs: record local Android environment baseline --- docs/README.md | 2 + docs/agent-playbook.md | 10 +- docs/environment.md | 178 ++++++++++++++++++++++++++++++++++++ docs/implementation-plan.md | 1 + 4 files changed, 187 insertions(+), 4 deletions(-) create mode 100644 docs/environment.md diff --git a/docs/README.md b/docs/README.md index 9577c03..479004c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -15,6 +15,7 @@ Brainwave 是一个以《易经》三枚铜币法为文化背景的 Android 个 | 文档 | 何时阅读 | 权威内容 | |---|---|---| | [原始需求](原始需求.txt) | 核对产品最初意图时 | 用户提供的原始需求，不在此文件中扩写 | +| [本地开发环境](environment.md) | 初始化工程、构建、测试或安装工具前 | 当前主机已实测的 JDK、SDK、Gradle 与设备能力 | | [产品规格](product-spec.md) | 判断功能范围和验收结果时 | 目标、非目标、需求编号、MVP 边界 | | [领域规则](domain-rules.md) | 修改投币、六爻、卦象映射时 | 唯一允许的起卦算法与不变量 | | [UX 与东方视觉](ux-design.md) | 修改页面、文案、动画和主题时 | 用户流程、文化表达、无障碍标准 | @@ -32,6 +33,7 @@ Brainwave 是一个以《易经》三枚铜币法为文化背景的 Android 个 - 实现起卦：本页 → [领域规则](domain-rules.md) → [系统架构](architecture.md) → [质量门禁](quality-gates.md) - 实现界面：本页 → [产品规格](product-spec.md) → [UX 与东方视觉](ux-design.md) → [系统架构](architecture.md) - 接入 AI：本页 → [AI 解释与安全](ai-safety.md) → [数据与内容](data-content.md) → [质量门禁](quality-gates.md) +- 初始化/构建：本页 → [本地开发环境](environment.md) → [系统架构](architecture.md) → [实施计划](implementation-plan.md) - 修复缺陷：本页 → [失败记忆](failure-memory.md) → 对应领域文档 → [质量门禁](quality-gates.md) - 引入依赖或调整结构：本页 → [系统架构](architecture.md) → [决策记录](decisions.md) diff --git a/docs/agent-playbook.md b/docs/agent-playbook.md index 337ca63..28fe866 100644 --- a/docs/agent-playbook.md +++ b/docs/agent-playbook.md @@ -6,10 +6,11 @@ ## 1. 开始任务 1. 阅读 [文档地图](README.md)，再按任务类型读取专题文档。 -2. 检查工作树、已有实现和测试；不要假设方案文档已经被编码。 -3. 找到关联需求编号、架构边界和完成标准。 -4. 把目标拆成可独立验证的小改动，明确不在范围的内容。 -5. 只有必要产品选择无法从仓库确定且错误假设风险较高时，才请求用户决定。 +2. 构建、初始化或设备任务先阅读[本地开发环境](environment.md)，不要假设 Android Studio、模拟器或全局 Gradle 存在。 +3. 检查工作树、已有实现和测试；不要假设方案文档已经被编码。 +4. 找到关联需求编号、架构边界和完成标准。 +5. 把目标拆成可独立验证的小改动，明确不在范围的内容。 +6. 只有必要产品选择无法从仓库确定且错误假设风险较高时，才请求用户决定。 根 `AGENTS.md` 创建后应保持为短入口，只包含仓库导航、常用命令和不可违反的不变量，并指向本手册；不要复制全部专题文档。 @@ -82,6 +83,7 @@ - schema、来源、隐私 → [数据与内容](data-content.md) - 提示词/模型行为 → [AI 安全](ai-safety.md) - 命令/门禁 → [质量门禁](quality-gates.md) +- JDK、SDK、Gradle、IDE、设备或代理能力 → [本地开发环境](environment.md) - 架构取舍 → [决策记录](decisions.md) - 可复现失败 → [失败记忆](failure-memory.md) diff --git a/docs/environment.md b/docs/environment.md new file mode 100644 index 0000000..e45ae85 --- /dev/null +++ b/docs/environment.md @@ -0,0 +1,178 @@ +# 本地开发环境基线 + +> 状态：已从当前主机实测 +> 最后核验：2026-08-04 +> 适用范围：`D:\OPC\brainwave` 的 Android 开发、构建和设备验证 + +本文件记录项目当前可用的本地工具链，不是期望环境清单。后续实现必须先使用这里已经确认的能力；需要升级或安装新工具时，应说明原因并在完成后更新本文件。 + +为避免泄密，本文件不记录主机名、设备序列号、Git 用户邮箱、完整 `PATH`、代理地址、密钥、令牌或用户级配置内容。 + +## 1. 主机环境 + +| 项目 | 实测值 | +|---|---| +| 操作系统 | Microsoft Windows 10 专业版，10.0.19045，Build 19045 | +| 架构 | 64 位 / amd64 | +| PowerShell | 7.3.12，Core Edition | +| 区域 | `zh-CN` | +| 时区 | `China Standard Time` | +| CPU | Intel Core i7-14650HX | +| 逻辑处理器 | 24 | +| 内存 | 15.8 GiB | +| Hypervisor | 已检测到（`HypervisorPresent=True`） | +| 工作区磁盘 | `D:`，检测时可用约 49.9 GiB | + +环境结论：硬件和 Hypervisor 能满足 Android 构建；当前没有 Android Emulator 包，因此 Hypervisor 暂时不构成可用模拟器环境。 + +## 2. 仓库与终端工具 + +| 项目 | 实测值 | +|---|---| +| 仓库路径 | `D:\OPC\brainwave` | +| Git | `2.49.0.windows.1` | +| 默认分支 | `main`，跟踪 `origin/main` | +| 检测起点提交 | `fdb20b8` | +| `core.autocrlf` | `true` | +| `core.longpaths` | 未显式设置 | +| Python | `3.10.11`，`C:\Python310\python.exe` | + +环境文件写入前，仓库没有 Gradle Wrapper、`build.gradle*`、`settings.gradle*` 或根 `AGENTS.md`。这些属于 Android 工程初始化阶段的交付物，不应被误认为已存在。 + +Windows 路径可能较长；如果后续依赖缓存或生成代码触发路径长度错误，应优先缩短包/生成目录或评估仓库级长路径配置，并把实际决定写入[决策记录](decisions.md)。 + +## 3. Java + +| 项目 | 实测值 | +|---|---| +| `JAVA_HOME` | `D:\jdk17` | +| Java | Eclipse Temurin OpenJDK `17.0.13+11` | +| `java.exe` | `D:\jdk17\bin\java.exe` | +| `javac` | `17.0.13` | + +当前 Android 构建必须优先使用该 JDK 17。不要在项目脚本中硬编码个人绝对路径；Wrapper/Gradle 应读取 `JAVA_HOME`，CI 则独立配置同一主版本。 + +## 4. Android SDK + +`ANDROID_HOME` 和 `ANDROID_SDK_ROOT` 均已设置为： + +```text +C:\Users\ila20\AppData\Local\Android\Sdk +``` + +已确认组件： + +| 组件 | 版本/状态 | +|---|---| +| Android SDK Platform | Android 14，API 34，Revision 3 | +| Build Tools | `34.0.0` | +| Platform Tools | `37.0.0` | +| ADB | `1.0.41`，Version `37.0.0-14910828` | +| Command-line Tools | `22.0` | +| Android CLI | `1.0.15985488` | +| Android Emulator | 未安装 | +| AVD | 不可用；没有 Emulator 包 | + +SDK 许可证目录存在，包含 Android SDK 相关许可证文件。这里只记录文件名存在，不复制许可证哈希或用户配置。 + +首次环境检测运行 Android CLI 时，该工具完成了自身嵌入式组件解包，并尝试发送匿名指标；指标请求因连接超时失败。没有通过该命令安装新的 Android platform、build-tools、system image 或项目依赖。以后调用 Android CLI 应使用关闭指标的选项，并且不能把这次结果视为外网稳定可用的证据。 + +## 5. Android Studio 与命令行开发 + +| 项目 | 实测值 | +|---|---| +| Android Studio | 标准安装位置、注册表和开始菜单均未发现 | +| JetBrains Toolbox | `3.6.3.86383` 已安装 | +| Toolbox 中 Android Studio | 未发现 | +| 全局 `gradle` | 未在 `PATH` 中发现 | +| 全局 `kotlinc` | 未在 `PATH` 中发现 | + +Android Studio 不是当前环境的可用前提。项目必须先支持 PowerShell + Gradle Wrapper 的命令行构建、测试和安装；以后安装 IDE 只能作为开发体验增强，不能成为 CI 或代理验证的隐式依赖。 + +## 6. Gradle 本地缓存 + +虽然没有全局 Gradle，本机已有可运行的 Wrapper 分发缓存： + +| 项目 | 实测值 | +|---|---| +| 缓存的 Gradle 分发 | `gradle-8.2-bin` | +| 已验证 Gradle | `8.2` | +| Gradle 使用的 JVM | Temurin `17.0.13` | +| 缓存的 Android Gradle Plugin | `8.2.0` | +| 用户级 `~/.gradle/gradle.properties` | 不存在 | + +项目初始化应提交 `gradlew`、`gradlew.bat`、`gradle/wrapper/gradle-wrapper.jar` 和版本明确的 `gradle-wrapper.properties`。所有项目命令使用： + +```powershell +.\gradlew.bat +``` + +不要要求用户安装全局 Gradle。当前缓存能证明 Gradle 8.2 本体可运行，但不能证明 Compose、Kotlin、Hilt、Room 等全部 Maven 依赖已离线缓存；第一次构建仍需实际验证。 + +## 7. 已连接 Android 真机 + +检测时存在 1 台已授权的物理设备。为避免持久化设备标识，本文件不记录序列号。 + +| 项目 | 实测值 | +|---|---| +| 厂商/型号 | OnePlus `PKG110` | +| Android | 16 | +| API Level | 36 | +| ABI | `arm64-v8a` | +| 物理分辨率 | `1264 × 2780` | +| 当前覆盖分辨率 | `1080 × 2376` | +| 物理/覆盖密度 | `560 / 480 dpi` | + +当前设备可用于 `adb` 安装、手工验收和 `connectedDebugAndroidTest`。测试脚本不得硬编码序列号；设备可能随时断开，纯 JVM 门禁必须独立可运行。 + +## 8. 网络与代理状态 + +- `HTTP_PROXY`：已设置，值未记录。 +- `HTTPS_PROXY`：已设置，值未记录。 +- `NO_PROXY`：未设置。 +- Android CLI 指标请求曾连接超时。 + +结论：任何需要下载 Gradle、Maven 依赖或 SDK 组件的步骤都必须以实际命令结果为准。不得因为代理变量存在就宣称网络可用，也不得把代理地址写入仓库。 + +## 9. 当前实现基线 + +在环境发生变化前，Android 工程应遵守： + +1. 使用现有 Temurin JDK 17。 +2. 使用项目自带 Gradle Wrapper，不依赖全局 `gradle` 或 `kotlinc`。 +3. 首次可构建配置只能依赖已安装的 SDK Platform 34 和 Build Tools 34.0.0；若模板要求更高版本，应先记录差异，再决定调整模板或安装 SDK。 +4. 命令行构建是必须能力，不假设 Android Studio 存在。 +5. 仪器测试优先使用已连接的 API 36、arm64 真机；不假设 Emulator/AVD 存在。 +6. 不自动安装系统级工具、SDK 平台或模拟器；确需新增环境能力时，先说明影响。 +7. 发布时的 `targetSdk` 和商店要求是独立发布门禁，不能因为本机只有 Platform 34 就永久锁定；工具链升级后必须更新本文件和相关 ADR。 + +## 10. 已知缺口 + +- Android 工程和 Gradle Wrapper 尚未创建。 +- Android Studio 未安装。 +- Android Emulator、system image 和 AVD 不可用。 +- 本机只确认安装了 Android Platform 34 / Build Tools 34.0.0。 +- Maven 依赖能否完整离线解析尚未验证。 +- 代理已配置，但外部仓库和 Android CLI 网络连通性尚未验证。 +- 没有根 `AGENTS.md` 和可执行的 `verifyLocal` 聚合任务。 + +这些缺口分别由[实施计划](implementation-plan.md)的 P0 和[质量门禁](quality-gates.md)处理。环境缺口不是跳过验证的理由；无法运行的门禁必须在交付报告中准确说明。 + +## 11. 复核命令 + +以下命令用于更新本文件时复核，输出必须人工脱敏后才能写入仓库： + +```powershell +Get-CimInstance Win32_OperatingSystem +$PSVersionTable +git --version +java -version +javac -version +Get-ChildItem $env:ANDROID_HOME\platforms -Directory +Get-ChildItem $env:ANDROID_HOME\build-tools -Directory +& "$env:ANDROID_HOME\platform-tools\adb.exe" version +& "$env:ANDROID_HOME\platform-tools\adb.exe" devices -l +.\gradlew.bat --version # Wrapper 创建后 +``` + +禁止把 `Get-ChildItem Env:`、用户级 Gradle 属性、ADB 私钥或未经筛选的系统信息原样提交。 diff --git a/docs/implementation-plan.md b/docs/implementation-plan.md index 8f0946a..35f090c 100644 --- a/docs/implementation-plan.md +++ b/docs/implementation-plan.md @@ -22,6 +22,7 @@ P1 与 P2 可并行，但 P3 不能在领域与内容契约未稳定时复制临 任务： +- 读取并遵守[本地开发环境](environment.md)：JDK 17、SDK 34、命令行优先、Gradle Wrapper、真机验证。 - 基于 Google `android/architecture-templates` 的 `base` 分支初始化。 - 确认正式应用名称、package/application ID、minSdk。 - 配置 Kotlin、Compose、Material 3、Hilt、Room、DataStore、Navigation 和 Version Catalog。