storyforge/docs/STORYFORGE_SPLIT_ASSESSMENT_2026-03-26.md

# 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 项目。