refactor: split android overlay out of storyforge

2026-03-26 10:41:33 +08:00
parent dd619448e7
commit 8d62da7e91
44 changed files with 279 additions and 9541 deletions
--- a/docs/STORYFORGE_SPLIT_ASSESSMENT_2026-03-26.md
+++ b/docs/STORYFORGE_SPLIT_ASSESSMENT_2026-03-26.md
@@ -0,0 +1,252 @@
+# StoryForge / AI Glasses 拆分评估方案
+
+执行状态（2026-03-26）：
+
+- 已确认独立仓库存在：`https://git.hyzq.site/krisolo/ai-glasses`
+- 已确认本机独立工作区存在：`/Users/kris/code/AI-glasses`
+- 当前评估方案已进入执行阶段：`StoryForge-gitea` 将移除混入的 `android-app/`
+
+## 1. 结论摘要
+
+当前仓库的问题更像是“项目导入时发生了目录叠加”，而不是后续开发过程中出现了随机数据错乱。
+
+明确证据如下：
+
+- Gitea 现有历史只有一个根提交：`acb1103`，日期为 `2026-03-14`。
+- 这个根提交从一开始就包含完整的 `android-app/` 子树。
+- 该 `android-app/` 子树内同时存在：
+  - `StoryForge` 相关界面与接口代码；
+  - 明显属于 `AI Glasses` 的包名、BLE、Baidu 实时能力、硬件依赖和 AAR。
+
+因此，当前更合理的判断是：
+
+- `StoryForge` 与 `AI Glasses` 原本是两个独立项目；
+- 在 `StoryForge-gitea` 建库或导入时，把一个带 `AI Glasses` Android 子项目的目录整体叠加进来了；
+- 后续又在这个混合目录上继续写入了一部分 `StoryForge` Android 代码，导致边界越来越模糊。
+
+## 2. 现状诊断
+
+### 2.1 明显属于 StoryForge 的主干目录
+
+这些目录整体上是当前 StoryForge 的核心交付面：
+
+- `collector-service/`
+- `web/storyforge-web-v4/`
+- `scripts/douyin-browser-capture/`
+- `n8n/`
+- `deploy/`
+- `docs/`
+- `Common/`
+- `docker-compose.yml`
+- `.env.example`
+
+### 2.2 明显带有 AI Glasses 叠加痕迹的区域
+
+`android-app/` 是本仓库最明显的混合区，内部包含三类内容：
+
+1. 明显偏 AI Glasses / 硬件链路的内容：
+
+- `android-app/app/src/main/java/com/aiglasses/app/ble/BleManager.kt`
+- `android-app/app/src/main/java/com/aiglasses/app/software/BaiduConversationAgent.kt`
+- `android-app/app/src/main/java/com/aiglasses/app/software/BaiduRealtimeWsClient.kt`
+- `android-app/app/src/main/java/com/aiglasses/app/software/BaiduVisualUploader.kt`
+- `android-app/app/src/main/java/com/aiglasses/app/software/SoftwareConversationController.kt`
+- `android-app/app/src/main/java/com/aiglasses/app/ui/MainViewModel.kt`
+- `android-app/app/libs/lib_agent-1.0.1.4.aar`
+- `android-app/app/libs/brtc-3.5.0.1a.aar`
+
+2. 明显是 StoryForge 业务，但写在旧命名空间里的内容：
+
+- `android-app/app/src/main/java/com/aiglasses/app/storyforge/StoryForgeApiService.kt`
+- `android-app/app/src/main/java/com/aiglasses/app/storyforge/StoryForgeModels.kt`
+- `android-app/app/src/main/java/com/aiglasses/app/storyforge/StoryForgeRepository.kt`
+- `android-app/app/src/main/java/com/aiglasses/app/storyforge/StoryForgeScreen.kt`
+- `android-app/app/src/main/java/com/aiglasses/app/storyforge/StoryForgeSessionStore.kt`
+- `android-app/app/src/main/java/com/aiglasses/app/storyforge/StoryForgeViewModel.kt`
+- `android-app/app/src/main/java/com/aiglasses/app/MainActivity.kt`
+
+3. 明显属于旧项目命名残留的工程设置：
+
+- `android-app/settings.gradle.kts` 中的 `rootProject.name = "AIGlassesApp"`
+- `android-app/app/build.gradle.kts` 中的 `namespace = "com.aiglasses.app"`
+- `android-app/app/src/main/res/values/themes.xml` 中的 `Theme.AIGlasses`
+- `android-app/app/src/main/AndroidManifest.xml` 当前仍引用 `Theme.AIGlasses`
+
+### 2.3 Git 历史上的关键时间点
+
+- `2026-03-14` `acb1103`
+  - Gitea 根提交。
+  - 从第一天就已带入 `android-app/` 和 `com.aiglasses.*`。
+- `2026-03-20 14:10` `ac6a8a8`
+  - 开始明显向 StoryForge Android UI / 交互继续推进。
+- `2026-03-20 14:17` `7070c3a`
+  - 提交信息直接是 `restore android build path`，说明 Android 构建链被重新激活。
+- `2026-03-22` `fe07a5f`
+  - 明确进入 `storyforge mobile v4 shell` 阶段。
+
+结论是：Gitea 历史里没有“完全纯净、完全不含 Android 叠加痕迹”的版本，但存在“尚未明显进入 APK 推进阶段”的较早切点。
+
+## 3. 目标定义
+
+基于当前产品节奏，推荐把拆分目标定义成：
+
+- `StoryForge-gitea` 只保留 StoryForge 当前实际在推进的主线：
+  - Web
+  - Backend
+  - n8n orchestration
+  - Douyin browser capture
+  - deploy / docs / ops
+- `AI Glasses` 相关 Android / BLE / Baidu / AAR / OTA 旧链路，移出当前仓库边界。
+- 如果未来要做 StoryForge Mobile，重新在一个干净边界内启动，而不是继续沿用 `com.aiglasses.*` 的混合目录。
+
+## 4. 拆分策略选项
+
+### 方案 A：按目录硬拆，StoryForge 先回到 Web 主线
+
+做法：
+
+- 从当前 StoryForge 仓库中移除整个 `android-app/` 目录。
+- 同步清理 README、docs、脚本中所有 Android/APK 主线描述。
+- 保留 Web、Backend、n8n、browser capture、deploy、docs 作为 StoryForge 正式主干。
+
+优点：
+
+- 边界最清楚，最符合“此前一直在做 Web 版本”的项目认知。
+- 能最快结束当前“两个项目目录叠加”的混乱状态。
+- 后续所有开发决策都会更简单。
+
+缺点：
+
+- 当前 `android-app/storyforge/*` 里写过的一些 StoryForge 业务代码会一起被移出，需要单独存档。
+
+适用判断：
+
+- 如果当前项目目标就是 Web 优先、暂不做 APK，这是最推荐方案。
+
+### 方案 B：保留 StoryForge Android 子集，拆掉 AI Glasses 硬件链
+
+做法：
+
+- 在 `android-app/` 中只保留 `storyforge/*`、`MainActivity.kt`、必要的网络与 OTA 文件；
+- 删除 `ble/`、`software/`、旧 `ui/MainViewModel.kt`、AAR、旧权限与旧命名；
+- 后续再把包名重构到 `com.storyforge.*`。
+
+优点：
+
+- 保留了已写过的 StoryForge 移动端业务界面。
+
+缺点：
+
+- 仍要处理大量命名空间和依赖残留。
+- 会继续占用当前 StoryForge 项目的精力。
+- 和“你之前并没有打算做 APK”的事实不完全一致。
+
+适用判断：
+
+- 只有在你确认近期确实要保留 StoryForge Android 端时才值得做。
+
+### 方案 C：直接回滚到较早基线
+
+候选点：
+
+- `acb1103`：最早基线，但已经带着 Android 叠加目录。
+- `1c539ab`：仍未明显进入 Android 壳推进，但已有少量 Android 接口同步。
+
+优点：
+
+- 操作简单。
+
+缺点：
+
+- 无法真正解决“根提交就已经叠加”的结构问题。
+- 会回退掉后续大量有价值的 Web / backend / deploy 进展。
+
+适用判断：
+
+- 只适合做参考，不适合作为主方案。
+
+## 5. 推荐方案
+
+推荐采用 `方案 A：按目录硬拆，StoryForge 先回到 Web 主线`。
+
+原因：
+
+- 它最符合当前产品事实：你确认之前的实际推进重点一直是 Web，而不是 APK。
+- 它最符合现有目录证据：`android-app/` 是混合最严重的区域，且根提交就已叠加。
+- 它最符合后续治理成本：先把 StoryForge 主仓库边界收干净，后面要不要重建移动端，再单独决定。
+
+## 6. 实施步骤
+
+### 第 0 阶段：安全快照
+
+- 基于当前 Gitea 状态打一个拆分前快照分支。
+- 导出 `android-app/` 的完整目录快照，作为独立归档或后续 AI Glasses 仓库恢复源。
+- 记录关键参考提交：
+  - `acb1103`
+  - `1c539ab`
+  - `ac6a8a8`
+  - `7070c3a`
+  - `fe07a5f`
+
+### 第 1 阶段：StoryForge 主仓库边界清理
+
+- 从 StoryForge 仓库中移除整个 `android-app/`。
+- 清理以下入口中的 Android/APK 主线描述：
+  - `README.md`
+  - `docs/AUDIT_2026-03-18.md`
+  - `docs/MVP_STATUS_2026-03-18.md`
+  - `docs/LAN_E2E_GUIDE_2026-03-18.md`
+  - 其他出现 `compileDebugKotlin`、`assembleDebug`、`APK`、`com.aiglasses` 的说明文档
+- 调整基线检查脚本，不再把 Android 编译当成 StoryForge 主仓库必检项。
+
+### 第 2 阶段：AI Glasses 资产外置
+
+- 将 `android-app/` 单独落到 AI Glasses 仓库或归档仓库。
+- 在那个仓库中保留 `com.aiglasses.*`、BLE、Baidu、AAR、OTA 等原始工程语义。
+
+### 第 3 阶段：StoryForge 后续演进
+
+- 当前仓库继续只推进：
+  - `collector-service/`
+  - `web/storyforge-web-v4/`
+  - `scripts/douyin-browser-capture/`
+  - `n8n/`
+  - `deploy/`
+  - `docs/`
+- 若未来确实需要 StoryForge Mobile，再开一个全新、干净的移动端工程，不复用当前混合 Android 目录。
+
+## 7. 风险与控制
+
+### 风险 1：误删仍有参考价值的 StoryForge Android 代码
+
+控制：
+
+- 在删除前先对 `android-app/` 做完整快照导出。
+- 如果担心未来要参考 `storyforge/*` 子目录，可以单独保留一份只读归档。
+
+### 风险 2：文档和状态记录出现历史断层
+
+控制：
+
+- 不改历史提交。
+- 仅在当前分支上明确标记“自本次拆分起，StoryForge 主仓库不再承载 Android 主线”。
+
+### 风险 3：脚本和检查项仍假设存在 Android
+
+控制：
+
+- 统一核对：
+  - `README.md`
+  - `scripts/check_repo_baseline.sh`
+  - 任何引用 `./gradlew` 的脚本或文档
+
+## 8. 最终建议
+
+不要先回滚历史，也不要先做大规模重命名。
+
+更稳妥的动作顺序应当是：
+
+1. 先承认当前问题是“目录叠加”而不是“功能开发方向变化”。
+2. 先把 `android-app/` 整体从 StoryForge 主仓库边界中拆出去。
+3. 把 StoryForge 主仓库重新收敛成 Web / Backend / Orchestration 主线。
+4. 最后再决定是否需要单独保留一个 StoryForge Mobile 项目。