brainwave/docs/README.md

# Brainwave 项目文档

> 文档状态：方案基线
> 最后核验：2026-08-19
> 当前阶段：正式产品名“灵机”；P0/P1 已完成；P3 离线主流程（方法说明、起念、手录、卦名/动爻结果）已可走通；P4 仅完成会话级本机保存与设置，问卦簿与本地解释未开始；P2 已接入维基文库《易经》原文与项目自撰白话草稿，待内容负责人审校；P-1 v0.3 待视觉复核；P5 未开始

本目录是 Brainwave 的项目知识事实源。产品决策、领域算法、架构边界、验收标准和已知失败模式必须写入仓库；聊天记录、口头约定和临时提示不构成项目规范。

## 项目一句话

灵机（仓库代号 Brainwave）是一个以《易经》三枚铜币法为文化背景的 Android 个人反思工具：用户亲手投掷并录入六次结果，应用在本地确定本卦、之卦和动爻；用户主动点击「解」后，本地内容或 AI 才把既有结果翻译成现代语言，并收束到一项低风险、可撤销的现实行动。

## 文档地图

| 文档 | 何时阅读 | 权威内容 |
|---|---|---|
| [原始需求](原始需求.txt) | 核对产品最初意图时 | 用户提供的原始需求，不在此文件中扩写 |
| [本地开发环境](environment.md) | 初始化工程、构建、测试或安装工具前 | 当前主机已实测的 JDK、SDK、Gradle 与设备能力 |
| [产品规格](product-spec.md) | 判断功能范围和验收结果时 | 目标、非目标、需求编号、MVP 边界 |
| [领域规则](domain-rules.md) | 修改投币、六爻、卦象映射时 | 唯一允许的起卦算法与不变量 |
| [UX 与东方视觉](ux-design.md) | 修改页面、文案、动画和主题时 | 用户流程、文化表达、无障碍标准 |
| [移动端交互原型](prototype.md) | 评审流程、视觉或开始 Compose 页面前 | 可点击原型、截图入口、确认清单和 Android 映射 |
| [系统架构](architecture.md) | 新增包、依赖、数据源或网络能力时 | 分层、依赖方向、运行时数据流 |
| [数据与内容](data-content.md) | 修改卦库、历史记录或内容来源时 | 数据契约、授权、隐私和迁移规则 |
| [内容审校](content-review.md) | 审校卦辞来源或准备发布时 | 来源、异文和签核状态 |
| [AI 解释与安全](ai-safety.md) | 修改提示词、模型调用或解释结果时 | AI 调用门、输入输出契约和安全边界 |
| [质量门禁](quality-gates.md) | 实现、评审、发布前 | 自动化验证、需求追踪和完成定义 |
| [依赖与许可证](dependency-licenses.md) | 新增/升级依赖或准备分发时 | 当前解析依赖、SPDX 与权威许可来源 |
| [实施计划](implementation-plan.md) | 领取任务或判断下一步时 | 阶段、依赖、交付物和退出条件 |
| [决策记录](decisions.md) | 遇到架构分歧或未决问题时 | 已接受决定、默认假设和 TBD |
| [代理工作手册](agent-playbook.md) | 任何编码代理开始工作前 | 检索、修改、验证和交付流程 |
| [失败记忆](failure-memory.md) | 排障、复盘或添加防回归规则时 | 已知风险、症状、护栏和验证方式 |

## 推荐阅读路径

- 实现起卦：本页 → [领域规则](domain-rules.md) → [系统架构](architecture.md) → [质量门禁](quality-gates.md)
- 实现界面：本页 → [产品规格](product-spec.md) → [UX 与东方视觉](ux-design.md) → [移动端交互原型](prototype.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)

## 规范优先级

发生冲突时按以下顺序处理：

1. 用户最新明确决定。
2. [产品规格](product-spec.md)中的验收标准与非目标。
3. [领域规则](domain-rules.md)和[AI 解释与安全](ai-safety.md)中的不变量。
4. [系统架构](architecture.md)中的依赖约束。
5. [UX 与东方视觉](ux-design.md)及其他实施建议。

不能自行消解的冲突必须记入[决策记录](decisions.md)，并在继续实现前请求产品决定。

## Harness Engineering 原则

本项目采用以下仓库约束：

- **仓库是事实源**：影响实现的信息必须进入版本化文档、代码、测试或脚本。
- **入口是地图**：本页只负责导航，细节放在专题文档，避免单个巨型说明吞噬上下文。
- **边界优先**：用明确的领域类型、接口、依赖方向和测试表达不变量。
- **验证闭环**：每个需求必须能映射到自动化测试或明确的人工验收步骤。
- **失败可积累**：重复错误进入[失败记忆](failure-memory.md)，随后转化为测试、静态检查或更清楚的契约。
- **文档随代码演进**：改变行为的提交必须同步更新对应文档；不能让实现与事实源分叉。

这些原则来自 Harness Engineering 的核心实践：让代理可读取仓库知识、机械执行架构约束，并通过反馈循环验证工作，而不是依赖一次性提示。参考：[OpenAI Harness Engineering](https://openai.com/index/harness-engineering/)。

## 当前已确认与未确认

已确认：

- 目标平台为原生 Android。
- 正式产品名为“灵机”，namespace/application ID 为 `net.opcapp.flash`，`minSdk=26`。
- 使用 Kotlin、Jetpack Compose 和单 Activity 架构。
- 起卦完全在本地完成，AI 不得参与或更改起卦结果。
- 用户真实投币并录入；MVP 不提供随机起卦按钮。
- 东方文化表达采用“纸、墨、朱砂、留白”的内容优先风格。
- AI 仅在用户主动点击「解」之后调用。
- 完整起卦、问题、解读与行动记录默认保存在 App 私有本机存储，首页明确告知，用户可在设置全局关闭或对当次退出。
- 本地历史默认排除系统/设备迁移/云备份；自动保存与 AI 数据发送授权完全独立。

仍需产品确认的事项记录在[决策记录](decisions.md#未决问题)。任何代理不得把 `TBD` 悄悄变成产品事实。

## 文档维护规则

每份专题文档必须包含状态或适用范围。发生下列变化时必须更新文档：

- 用户可见行为改变；
- 领域算法、数据结构或内容版本改变；
- 新增网络、存储或第三方依赖；
- 测试命令、构建方式或发布门禁改变；
- 出现可能再次发生的缺陷。

文档链接、需求编号和验证命令由 `verifyLocal` 机械检查。授权真机存在时另跑设备仪器测试；未运行的门禁不得写成已经通过。