PicMe 代码拆分与架构重构计划

本文档基于 2026-06-07 的代码扫描结果，识别项目中超过 1000 行的大文件，分析架构问题，并给出拆分建议。 重点关注 Agent 模块的独立库提取可行性。

一、超大文件扫描结果（>1000 行）

500~1000 行文件（需关注）

二、逐文件拆分建议

2.1 BeautyRenderer.kt（1687 行）- beauty-engine 模块

问题分析： - 职责混杂：同时管理参数状态、多 Pass 渲染管线、Shader uniform 设置、错误处理、拍照离屏渲染 - 包含 4 个渲染 Pass 的逻辑（CopyPass / BeautyUnitPass / FaceMakeupPass / StyleEffectPass） - 两种渲染路径（预览 onRender / 拍照 renderBeautyMultiPass）耦合在一起 - 50+ 个 uniform location 字段堆积

拆分方案：

beauty-engine/src/main/java/com/picme/beauty/render/
├── BeautyRenderer.kt              # 保留：主入口 + 状态管理（~400 行）
├── pass/
│   ├── BeautyPassPipeline.kt      # 新增：多 Pass 管线编排（~350 行）
│   ├── CopyPassExecutor.kt        # 新增：Pass 0 执行器（~80 行）
│   ├── BeautyUnitPassExecutor.kt  # 新增：Pass 1 执行器（~120 行）
│   └── FaceMakeupPassExecutor.kt  # 新增：Pass 4 执行器（~200 行）
├── shader/
│   └── UniformBinder.kt           # 新增：uniform 绑定辅助类（~150 行）
└── photo/
    └── PhotoRenderPipeline.kt     # 新增：拍照离屏渲染（~300 行）

预期收益： - 每个文件控制在 400 行以内 - 渲染 Pass 可独立单元测试 - 新增 Pass 时无需修改主 Renderer

2.2 CameraScreen.kt（1505 行）- app 模块

问题分析： - 典型的 “God Composable”：包含权限管理、相机绑定、AI Agent 初始化、语音协调器、状态机、传感器监听、内存持久化等 - CameraContent 内部声明了 50+ 个 remember 状态 - AI Agent 相关逻辑（~400 行）与相机核心逻辑耦合 - 命令处理（BatchExecute / Delay）直接写在 Composable 中

拆分方案：

app/src/main/java/com/picme/features/camera/
├── CameraScreen.kt                # 保留：权限壳 + 路由（~150 行）
├── CameraContent.kt               # 已存在，需进一步瘦身
├── state/
│   └── CameraStateHolder.kt       # 新增：提取所有 remember 状态（~300 行）
├── agent/
│   ├── CameraAgentInitializer.kt  # 新增：AI Agent / UseCase / 语音初始化（~250 行）
│   └── CameraAgentCommandExecutor.kt # 新增：BatchExecute/Delay 执行逻辑（~120 行）
├── memory/
│   └── CameraMemoryManager.kt     # 新增：DataStore 读写 + 状态恢复（~150 行）
└── sensor/
    └── CameraSensorManager.kt     # 新增：加速度计监听 + 稳定状态（~80 行）

关键重构动作： 1. 将 CameraContent 中的状态提取为 CameraStateHolder（remember 聚合类） 2. AI Agent 初始化逻辑（aiAgentUseCase / voiceCoordinator / asrEngine）移至 CameraAgentInitializer 3. CameraAgentCommandHandler 已独立，但 Composable 中的命令执行逻辑仍需进一步剥离

2.3 LlmModelDownloadManager.kt（1326 行）- app 模块

问题分析： - 混合了多种职责：模型市场数据获取、本地模型配置解析、下载任务管理、断点续传、文件校验、Service 状态同步 - 包含 8 组硬编码的文件列表常量（LLM/ASR/TTS/人脸检测等） - 下载逻辑（downloadModel / resumeDownload）存在大量重复代码

拆分方案：

app/src/main/java/com/picme/data/download/
├── LlmModelDownloadManager.kt     # 保留：对外 API + 任务调度（~350 行）
├── model/
│   ├── ModelFileRegistry.kt       # 新增：文件列表常量 + 模型类型判断（~150 行）
│   └── ModelMarketDataSource.kt   # 新增：市场数据获取 + 缓存（~200 行）
├── download/
│   ├── DownloadEngine.kt          # 新增：核心下载逻辑（~250 行）
│   └── ResumeDownloadEngine.kt    # 新增：断点续传逻辑（~200 行）
└── service/
    └── DownloadServiceBridge.kt   # 新增：ForegroundService 状态同步（~80 行）

2.4 CameraDebugOverlay.kt（1148 行）- app 模块

问题分析： - 纯 UI 绘制文件，包含 4 种完全不同的绘制逻辑： - 人脸关键点 overlay（106 点） - ROI 矩形框 - 瘦脸控制点 + 方向箭头 - 腮红椭圆区域 - 大量数学计算（椭圆、三角函数、几何变换）与 Compose Canvas 绘制混在一起

拆分方案：

app/src/main/java/com/picme/features/camera/debug/
├── CameraDebugOverlay.kt          # 保留：入口分发（~150 行）
├── draw/
│   ├── FaceLandmarkDrawer.kt      # 新增：106 点绘制（~200 行）
│   ├── RoiRectDrawer.kt           # 新增：ROI 矩形 + 角标（~120 行）
│   ├── ThinFaceDebugDrawer.kt     # 新增：瘦脸控制点（~250 行）
│   ├── BigEyeDebugDrawer.kt       # 新增：大眼控制点（~150 行）
│   └── BlushDebugDrawer.kt        # 新增：腮红椭圆（~200 行）
└── math/
    └── FaceGeometryUtils.kt       # 新增：几何计算工具（~100 行）

三、Agent 模块深度分析与独立库提取方案

3.1 当前 Agent 模块结构

app/src/main/java/com/picme/domain/agent/           # ~~~7939 行~~~ → 已迁移至 :agent-core（~5000 行），当前仅剩 Facade/AiAgentUseCase/CapabilityRegistry 等桥接层
agent-core/src/main/java/com/picme/agent/core/        # Agent Runtime 核心（从 domain/agent/ 迁移）
├── AgentCommandParser.kt       # 596 行 - 命令解析
├── AgentOrchestrator.kt        # 601 行 - 编排器（单例）
├── CapabilityRegistry.kt       # 768 行 - 能力注册表 + 队列
├── ExecutionEngine.kt          # 401 行 - 执行引擎
├── InferenceRouter.kt          # 153 行 - 推理路由
├── LocalLlmEngine.kt           # 391 行 - 本地 LLM 引擎
├── MemoryManager.kt            # 252 行 - 对话记忆
├── MnnResourceManager.kt       # 317 行 - MNN 资源管理
├── PrivacyGuard.kt             # 112 行 - 隐私守卫
├── PromptBuilder.kt            # 323 行 - 提示词构建
├── CapabilityHost.kt           # 172 行 - 能力宿主
├── model/                      # 数据模型
│   ├── AgentCommands.kt        # 345 行
│   ├── AgentModels.kt          # 280 行
│   ├── SceneManager.kt         # 150 行
│   └── ...
├── capability/                 # 能力实现
│   ├── Capability.kt           # 121 行
│   ├── CameraCapability.kt     # 286 行
│   ├── GalleryCapability.kt    # 278 行
│   ├── SettingsCapability.kt   # 248 行
│   └── NavigationCapability.kt # 172 行
└── remote/                     # 远程推理
    ├── RemoteOrchestrator.kt   # 481 行
    ├── RemoteInferenceEngine.kt # 392 行
    ├── (UnifiedRemoteClient 已移除，远程推理现使用 :agent-core OpenAiChatModel)
    ├── AdaptiveStrategySelector.kt # 182 行
    ├── IntentCache.kt          # 287 行
    └── ...

3.2 架构问题诊断

3.3 :agent-core 模块定位与边界

定位： :agent-core 是一个内聚的 Agent 运行时模块，不是过度抽象的框架，而是 PicMe Agent 系统的核心载体。

设计原则： - 不为了抽象而抽象：直接使用具体类型（AgentCommand、AgentContext 等），而非泛型接口 - 允许业务依赖：可以依赖 beauty-engine，可以定义相机/美颜相关的数据结构 - 允许平台依赖：可以包含 MNN-LLM、Android 导航等特定平台内容 - 代码简单明了：优先可读性和可维护性，而非极致解耦

模块边界：

:agent-core                    # android-library，依赖 beauty-engine
├── Capability.kt              # Capability 接口 + BaseCapability 基类
├── CommandExecutor.kt         # 命令执行器（超时 + 异常处理）
├── CrossPageCommandQueue.kt   # 跨页面命令队列（TTL + 重试）
├── SceneManager.kt            # 场景管理单例
├── AgentLogger.kt             # 日志抽象接口
├── model/                     # Agent 核心数据模型
│   ├── AgentCommands.kt       # AgentCommand 密封类
│   ├── AgentModels.kt         # AgentContext / AgentAction / PageContext
│   ├── ExecutionState.kt      # 执行状态
│   ├── InferenceResult.kt     # 推理结果
│   ├── MediaAsset.kt          # 媒体资源模型
│   ├── PageContext.kt         # 页面上下文
│   └── SceneContext.kt        # 场景上下文
└── remote/                    # 远程推理相关
    └── ExecutionPlan.kt       # 执行计划

已迁移文件（从 app 模块下沉）：

留在 app 模块的文件：

迁移状态（2026-06 审计）：以上迁移均已落地。Capability.kt, CommandExecutor.kt, CrossPageCommandQueue.kt, AgentCommands.kt, AgentModels.kt, ExecutionState.kt, InferenceResult.kt, MediaAsset.kt, PageContext.kt, SceneContext.kt, ExecutionPlan.kt 均已在 agent-core/ 中。CapabilityRegistry.kt, AgentOrchestrator.kt, AgentConfigurator.kt 仍在 app/ 中（Facade/策略路由层）。

CapabilityRegistry.kt | app/.../domain/agent/ | 使用 :agent-core 的 CommandExecutor + CrossPageCommandQueue |
AgentOrchestrator.kt | app/.../domain/agent/ | 使用 :agent-core 的模型和接口 |
AgentConfigurator.kt | app/.../domain/agent/ | 平台特定组件配置 |
CameraCapability.kt | app/.../features/camera/capability/ | 业务 Capability |
GalleryCapability.kt | app/.../features/gallery/capability/ | 业务 Capability |
SettingsCapability.kt | app/.../features/settings/capability/ | 业务 Capability |
NavigationCapability.kt | app/.../domain/agent/capability/ | 通用导航 Capability |

依赖关系：

:app
├── :agent-core                 # Agent 运行时核心（已包含模型 + 基础设施）
├── :beauty-engine              # 美颜引擎（已有）
└── app-features/
    ├── camera/                 # CameraCapability + 相机页面
    ├── gallery/                # GalleryCapability + 图库页面
    └── settings/               # SettingsCapability + 设置页面

四、其他值得关注的问题

4.1 包结构不合理

4.2 重复代码

五、实施优先级与阶段规划

Phase 1：Agent 核心重构（已完成 ✅）

Phase 1 关键成果： - :agent-core 模块已激活，包含 Agent 核心运行时（接口 + 模型 + 基础设施） - Capability 接口统一在 :agent-core，app 模块直接复用 - CommandExecutor + CrossPageCommandQueue 统一在 :agent-core，删除 app 重复实现 - 业务 Capability（Camera/Gallery/Settings）已下放到 features 层 - 所有模块编译通过

Phase 2：大文件拆分（待执行）

Phase 2：大文件拆分

Phase 3：架构清理

六、验收标准

• 所有文件行数控制在 500 行以内（除数据模型/常量定义文件）
• :agent-core 模块可独立编译，不依赖 :app 任何代码
• :agent-core 单元测试覆盖率 > 60%
• 原有功能零回归（通过 Agent Test V2 自动化测试验证）
• 文档同步更新（AGENTS.md / 模块 AGENTS.md）

维护者：CO Agent 最后更新：2026-06-07 状态：Phase 1 已完成，Phase 2 待启动