Brainwave 项目文档
文档状态：方案基线 最后核验：2026-08-04 当前阶段：P-1 核心原型已确认；首页、问卦簿与默认本机保存 v0.3 已实现并待视觉复核；Android 工程尚未初始化
本目录是 Brainwave 的项目知识事实源。产品决策、领域算法、架构边界、验收标准和已知失败模式必须写入仓库；聊天记录、口头约定和临时提示不构成项目规范。
项目一句话
Brainwave 是一个以《易经》三枚铜币法为文化背景的 Android 个人反思工具：用户亲手投掷并录入六次结果，应用在本地确定本卦、之卦和动爻；用户主动点击「解」后，本地内容或 AI 才把既有结果翻译成现代语言，并收束到一项低风险、可撤销的现实行动。
文档地图
| 文档 | 何时阅读 | 权威内容 |
|---|---|---|
| 原始需求 | 核对产品最初意图时 | 用户提供的原始需求，不在此文件中扩写 |
| 本地开发环境 | 初始化工程、构建、测试或安装工具前 | 当前主机已实测的 JDK、SDK、Gradle 与设备能力 |
| 产品规格 | 判断功能范围和验收结果时 | 目标、非目标、需求编号、MVP 边界 |
| 领域规则 | 修改投币、六爻、卦象映射时 | 唯一允许的起卦算法与不变量 |
| UX 与东方视觉 | 修改页面、文案、动画和主题时 | 用户流程、文化表达、无障碍标准 |
| 移动端交互原型 | 评审流程、视觉或开始 Compose 页面前 | 可点击原型、截图入口、确认清单和 Android 映射 |
| 系统架构 | 新增包、依赖、数据源或网络能力时 | 分层、依赖方向、运行时数据流 |
| 数据与内容 | 修改卦库、历史记录或内容来源时 | 数据契约、授权、隐私和迁移规则 |
| AI 解释与安全 | 修改提示词、模型调用或解释结果时 | AI 调用门、输入输出契约和安全边界 |
| 质量门禁 | 实现、评审、发布前 | 自动化验证、需求追踪和完成定义 |
| 实施计划 | 领取任务或判断下一步时 | 阶段、依赖、交付物和退出条件 |
| 决策记录 | 遇到架构分歧或未决问题时 | 已接受决定、默认假设和 TBD |
| 代理工作手册 | 任何编码代理开始工作前 | 检索、修改、验证和交付流程 |
| 失败记忆 | 排障、复盘或添加防回归规则时 | 已知风险、症状、护栏和验证方式 |
推荐阅读路径
- 实现起卦：本页 → 领域规则 → 系统架构 → 质量门禁
- 实现界面：本页 → 产品规格 → UX 与东方视觉 → 移动端交互原型 → 系统架构
- 接入 AI：本页 → AI 解释与安全 → 数据与内容 → 质量门禁
- 初始化/构建：本页 → 本地开发环境 → 系统架构 → 实施计划
- 修复缺陷：本页 → 失败记忆 → 对应领域文档 → 质量门禁
- 引入依赖或调整结构：本页 → 系统架构 → 决策记录
规范优先级
发生冲突时按以下顺序处理：
不能自行消解的冲突必须记入决策记录，并在继续实现前请求产品决定。
Harness Engineering 原则
本项目采用以下仓库约束：
- 仓库是事实源：影响实现的信息必须进入版本化文档、代码、测试或脚本。
- 入口是地图：本页只负责导航，细节放在专题文档，避免单个巨型说明吞噬上下文。
- 边界优先：用明确的领域类型、接口、依赖方向和测试表达不变量。
- 验证闭环：每个需求必须能映射到自动化测试或明确的人工验收步骤。
- 失败可积累：重复错误进入失败记忆，随后转化为测试、静态检查或更清楚的契约。
- 文档随代码演进：改变行为的提交必须同步更新对应文档；不能让实现与事实源分叉。
这些原则来自 Harness Engineering 的核心实践：让代理可读取仓库知识、机械执行架构约束，并通过反馈循环验证工作，而不是依赖一次性提示。参考：OpenAI Harness Engineering。
当前已确认与未确认
已确认：
- 目标平台为原生 Android。
- 使用 Kotlin、Jetpack Compose 和单 Activity 架构。
- 起卦完全在本地完成，AI 不得参与或更改起卦结果。
- 用户真实投币并录入；MVP 不提供随机起卦按钮。
- 东方文化表达采用“纸、墨、朱砂、留白”的内容优先风格。
- AI 仅在用户主动点击「解」之后调用。
- 完整起卦、问题、解读与行动记录默认保存在 App 私有本机存储，首页明确告知，用户可在设置全局关闭或对当次退出。
- 本地历史默认排除系统/设备迁移/云备份；自动保存与 AI 数据发送授权完全独立。
仍需产品确认的事项记录在决策记录。任何代理不得把 TBD 悄悄变成产品事实。
文档维护规则
每份专题文档必须包含状态或适用范围。发生下列变化时必须更新文档：
- 用户可见行为改变；
- 领域算法、数据结构或内容版本改变；
- 新增网络、存储或第三方依赖；
- 测试命令、构建方式或发布门禁改变；
- 出现可能再次发生的缺陷。
文档链接、需求编号和验证命令将随工程骨架一起接入 CI 检查。当前尚无 Gradle 工程，不能声称任何构建或测试已经通过。