首页/ 架构/ 维护优化

# 项目维护优化清单

从项目维护角度审视架构、流程和技术债务

1
已解决
3
必须做
3
强烈建议
2
锦上添花

## 已解决

#### 已解决 API 数量精简

从最初 180+ API 精简到 36 个 MCP Tool，用 exec 兜底低频操作。JSON Schema 自动校验。

## 必须做

#### P0 跨平台 UI 自动化

AI 应用操控需要 Accessibility API：Windows (UIAutomation)、Linux (AT-SPI2)、macOS (AX API)。三套 API，每个平台独立实现。

方案：① 定义 UIAdapter 接口，每平台一个实现；② Phase 1 只做 Windows；③ 优先用浏览器自动化（Playwright 跨平台一致）。

#### P0 缺少测试策略

36 MCP Tool × 多平台 × 多设备接入方式 = 测试矩阵。

方案：① 单元测试：每个 tool handler 独立测试；② 集成测试：客户端 MCP Server ↔ Gateway；③ E2E 测试：Telegram → AI → MCP Tool → 执行；④ CI：GitHub Actions。

#### P0 无错误恢复策略

网络断开、Gateway 重启、设备休眠。远程场景下错误是常态。

方案：① WS 自动重连（指数退避）；② 请求超时 + 重试；③ 幂等性设计（idempotency key）。

## 强烈建议

#### P1 无日志与可观测性

远程设备出问题时没有日志无法排查。

方案：① 结构化日志（pino/winston）；② 日志通过 WS 上报到 Gateway 集中查看；③ 健康心跳（30s 上报 CPU/内存/磁盘）。

#### P1 无配置管理方案

客户端需要配置（Gateway 地址、token、代理、服务开关）。

方案：① 本地 JSON 配置 + 系统 keychain 存凭据；② Gateway 可远程推送配置；③ JSON Schema 校验。

#### P1 无自动化构建发布

客户端要打包成 Windows .exe / Linux .deb / Android APK。手动打包耗时易错。

方案：① GitHub Actions CI；② tag push 自动构建所有平台；③ 自动更新机制（Tauri updater / Expo OTA）。

## 锦上添花

#### P2 文档迁移

当前手写 HTML，改一个样式要改多处。迁移到 VitePress 可用 Markdown 写内容。

#### P2 性能监控仪表盘

多设备运行后需要统一视图查看所有设备健康状态。