brainwave/docs/environment.md

本地开发环境基线

状态：已从当前主机实测 最后核验：2026-08-19 适用范围：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
Node.js / npm	22.22.1 / 11.12.1
Google Chrome	150.0.7871.188，C:\Program Files\Google\Chrome\Application\chrome.exe

首次环境审计时仓库没有 Gradle Wrapper、build.gradle*、settings.gradle* 或根 AGENTS.md。当前这些入口和可安装的 Android application 已建立；正式应用名为“灵机”，application ID 为 net.opcapp.flash。

Windows 路径可能较长；如果后续依赖缓存或生成代码触发路径长度错误，应优先缩短包/生成目录或评估仓库级长路径配置，并把实际决定写入决策记录。

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 均已设置为：

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
缓存的 Kotlin Gradle Plugin	1.9.20
缓存的 JUnit	4.13.2
用户级 ~/.gradle/gradle.properties	不存在

仓库已提交 gradlew、gradlew.bat、gradle/wrapper/gradle-wrapper.jar 和固定 Gradle 8.2 及 SHA-256 的 gradle-wrapper.properties。所有项目命令使用：

.\gradlew.bat <task>

不要要求用户安装全局 Gradle。当前缓存已实际证明 Gradle 8.2、AGP 8.2.0、Kotlin 1.9.20、Compose、Hilt、Room、DataStore、Navigation 与 JUnit 可完成 Android debug 构建、lint、单元测试和测试 APK 编译；首次解析已经联网完成，后续离线可用性仍以实际命令为准。

7. 已连接 Android 真机

2026-08-07 本轮曾检测到 1 台已授权的物理设备。为避免持久化设备标识，本文件不记录序列号。

项目	实测值
厂商/型号	Samsung SM-G9700
Android	12
API Level	31
物理分辨率	1080 × 2280
物理密度	480 dpi

该设备满足 minSdk=26，可用于 adb 安装、手工验收和仪器测试。测试脚本不得硬编码序列号；设备可能随时断开，环境独立门禁必须单独可运行。本机 PATH 中的 D:\Portable\adb\adb.exe 为 ADB 1.0.32，SDK Platform Tools 37.0.0 提供 ADB 1.0.41；两者会争用 5037 端口并互相重启 server。本轮三星设备只在便携 ADB server 下稳定枚举，SDK ADB 重启后设备接口消失，因此真机门禁通过 run-connected-tests.ps1 -AdbPath 显式选择单一 ADB。不要同时启动两个 server，也不要把“Windows 能看到 USB 复合设备”误当作 ADB 已连接。

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 31 三星真机；不假设 Emulator/AVD 或固定设备存在。
6. 不自动安装系统级工具、SDK 平台或模拟器；确需新增环境能力时，先说明影响。
7. 发布时的 targetSdk 和商店要求是独立发布门禁，不能因为本机只有 Platform 34 就永久锁定；工具链升级后必须更新本文件和相关 ADR。
8. P-1 原型截图使用现有 Node.js 与 Chrome DevTools 协议生成，不额外安装前端依赖；命令见移动端交互原型。

10. 已知缺口

• Android Studio 未安装。
• Android Emulator、system image 和 AVD 不可用。
• 本机只确认安装了 Android Platform 34 / Build Tools 34.0.0。
• PATH 中 ADB 1.0.32 与 SDK ADB 1.0.41 会争用 server；当前三星设备的可重复门禁需要显式选择便携 ADB，后续应评估统一驱动和 Platform Tools。
• 代理已配置；本轮 Maven 依赖下载成功，但不能据此保证未来网络始终可用。

已解除的缺口：Gradle Wrapper、Version Catalog、根 AGENTS.md、CI、正式 Android 身份和 application 壳均已建立。2026-08-19，verifyLocal 通过（含 debug 单元测试、lintDebug 与 debug APK，已校验 zh-Hans-2026.1 内容包）；便携 ADB 下 Samsung API 31 真机 run-connected-tests.ps1 得到 OK (4 tests)，覆盖方法说明、保存设置、夹具「复 24 → 坤 2、初爻动」本机保存/当次删除（结果页已展示原文/白话），以及 Room 会话读写。未发现应用崩溃日志。飞行模式人工走查、无障碍抽测和内容负责人签核仍未做。

这些缺口分别由实施计划的 P0 和质量门禁处理。环境缺口不是跳过验证的理由；无法运行的门禁必须在交付报告中准确说明。

11. 复核命令

以下命令用于更新本文件时复核，输出必须人工脱敏后才能写入仓库：

Get-CimInstance Win32_OperatingSystem
$PSVersionTable
git --version
node --version
npm --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 私钥或未经筛选的系统信息原样提交。