Skip to content

Latest commit

 

History

History
86 lines (77 loc) · 5.56 KB

计划.md

File metadata and controls

86 lines (77 loc) · 5.56 KB

OpenOmniOperator 全量技术评估与改进计划（v1）

摘要

基于当前仓库扫描，我建议把后续工作分成三条主线并行推进：

  1. 稳定性与安全基线（先做，1-2周）
  2. 架构解耦与可测试性（核心技术债，2-4周）
  3. 能力增强与生态扩展（功能增长，持续迭代）

当前最明显风险点是：OmniDevServer 过大且反射路由集中、缺少自动化测试、Socket 协程与生命周期管理偏弱、网络安全默认偏宽松。

1) 技术上可升级的地方

  1. 服务端与协议层升级
    将 app/src/main/java/cn/com/omnimind/omnibot/OmniDevServer.kt 从单文件 792 行拆分为路由层/鉴权层/命令层/OpenAPI层；把“全部 GET+query”逐步升级为 POST + JSON body（保留旧接口兼容期）。
  2. 协程与并发模型升级
    替换 GlobalScope.launch（app/src/main/java/cn/com/omnimind/omnibot/util/SocketHandler.kt:299）为受控 CoroutineScope(SupervisorJob)，在连接关闭时统一 cancel。
  3. 依赖与构建升级治理
    建立依赖更新策略（AGP/Kotlin/Compose BOM/Flutter deps）+ 锁版本与变更日志；修复 Kotlin 版本分叉（gradle/libs.versions.toml 里 kotlin=2.0.21 与 kotlin-reflect=2.1.0）。
  4. 安全配置升级
    AndroidManifest.xml 中 usesCleartextTraffic="true" 建议切到 networkSecurityConfig 按环境控制；QUERY_ALL_PACKAGES 仅在必要能力下保留并补充合规说明。
  5. 可观测性升级
    OmniLog 增加结构化字段（requestId, endpoint, duration, errorCode），并增加 DevServer 指标端点（成功率/失败率/耗时分位）。

2) 潜在技术债（按优先级）

  1. P0: 自动化测试几乎缺失
    目前不存在标准 app/src/test 与 app/src/androidTest，CI（.github/workflows/android-ci.yml）也未执行单测/UI测。
  2. P0: 服务入口阻塞/异常风险
    runBlocking 出现在 OmniDevServer.serve（app/src/main/java/cn/com/omnimind/omnibot/OmniDevServer.kt:461），高并发下吞吐和超时行为不可控。
  3. P1: 生命周期与资源管理债
    SocketHandler 使用全局状态+全局协程，连接事件多、退出路径复杂，易出现泄漏或状态错乱。
  4. P1: 单体文件与反射耦合债
    路由、鉴权、OpenAPI 生成、静态资源分发耦合在 OmniDevServer.kt，维护成本高。
  5. P1: 前端状态管理可维护性债
    flutter_module/lib/pages/home_page.dart 体量大、UI与业务逻辑耦合，建议引入状态管理分层（Riverpod/Bloc 二选一）。
  6. P2: 产物体积与资产管理债
    app/src/main/assets/static 约 18MB，集成 Monaco/xterm/redoc/jquery/tailwind 全量资源，APK体积与加载时延可优化。
  7. P2: 构建可重复性风险
    本地构建对外网拉取 Gradle wrapper 强依赖，本次环境中无法下载 services.gradle.org，建议缓存镜像与离线构建方案。

3) 可新增功能/可改进方向

  1. 会话录制与回放
    新增“操作脚本录制->回放->导出”，提升调试复现效率。
  2. 元素定位增强
    在 captureScreenshotXml 基础上新增 selector 能力（text/content-desc/bounds）与稳定 nodeId 映射。
  3. 批处理动作 API
    新增 batchExecute（原子或半原子策略可选），减少网络往返和中间状态失败。
  4. 安全能力增强
    支持 API key 轮换、过期时间、设备白名单、审计日志导出。
  5. 多设备管理
    在 Flutter 设置页增加设备列表、在线状态、一键切换 defaultDevice。
  6. 插件生态增强
    为 integrations/clawdbot/omni-operator 增加重试策略、typed error、契约测试与示例工作流。
  7. 端到端开发体验
    新增“健康检查页 + 权限诊断 + 一键修复引导”（Accessibility/电池优化/网络连通性）。

公共 API/接口变更（建议）

  1. 新增 POST /v2/actions/* 与 POST /v2/batchExecute，请求体 JSON。
  2. 保留 /v1/* 旧 GET 接口一个过渡版本周期，响应头加 Deprecation。
  3. 新增 GET /metrics（基础运行指标）。
  4. 鉴权头统一为 Authorization: Bearer <token>，补充错误码体系（401/403/429/5xx + machine-readable code）。

测试方案与验收场景

  1. 单元测试
    覆盖命令参数校验、结果封装、鉴权中间件、Socket 状态机。
  2. 仪器化测试
    覆盖 Accessibility 开/关、截图链路、点击/滑动/输入关键路径。
  3. 契约测试
    对 OpenAPI 生成结果做 schema snapshot，防止接口回归。
  4. 端到端测试
    从 Flutter 发起到 Native 执行再到回包的全链路用例。
  5. 性能回归
    截图接口 p95、批处理吞吐、冷启动时间、APK 体积对比。
  6. 安全回归
    未授权访问、错误 token、重放请求、明文流量策略验证。

实施节奏（默认）

  1. 第 1-2 周：补测试骨架、引入 CI test job、治理 runBlocking 与 GlobalScope。
  2. 第 3-4 周：拆分 OmniDevServer、落地 v2 API 骨架、增加兼容层。
  3. 第 5-6 周：Flutter 状态分层、设置页与连接流程重构。
  4. 第 7-8 周：批处理 API + 会话录制回放 + 插件契约测试。
  5. 第 9+ 周：指标、审计、安全增强与性能优化。

默认假设与选择

  1. 默认优先级按“线上稳定性 > 安全 > 可维护性 > 新功能”。
  2. 默认继续兼容现有 Clawdbot 接入，不做破坏式 API 切换。
  3. 默认最小支持 Android API 30 不变。
  4. 默认先做可观测性与测试基线，再推进大功能。