phoenix1803/vektor-ecosystem

# Vektor 生态系统 Vektor 是一个由两个相互协作的代码库组成的应急响应生态系统： - `Vektor-app`，原生的 Android 客户端，负责处理本地配置文件存储、传感器驱动的紧急检测、设备端 AI 推理以及用户体验。 - `Vektor-core`，VectorGo 代理引擎，负责接收紧急 payload、对数据进行规范化和分类、选择医院、计算路线、持久化事件以及发布实时更新。 该仓库还包含一个预构建的 Android 构件 `app-release.apk`，以便可以直接安装和测试移动客户端，而无需立即重新构建。 ## 系统概述 该设计有意在本地优先的移动层和确定性的后端编排层之间进行了分离。 1. Android 应用将私密数据保留在设备上，监控传感器，并使用 Cactus 和 Gemma 运行本地 AI 以进行离线应急分析。 2. 当事件必须被上报时，应用会向 VectorGo 端点发送单个紧急 payload。 3. 后端验证请求，运行决策 pipeline，选择医院，计算路线并存储结果。 4. 实时事件状态会同步到操作屏幕和后续工作流中。 此工作空间中的当前文档描述了后端两个重要的持久化路径：用于审计存储的 PostgreSQL 和用于操作实时状态的 Firebase Realtime Database。 ## 仓库布局 | 路径 | 用途 | |---|---| | `Vektor-app/` | Android 应用源码、产品需求以及内嵌的 Cactus SDK 材料 | | `Vektor-app/prd.md` | 移动应用的产品需求 | | `Vektor-app/cactus.md` | 高层 Cactus 集成参考 | | `Vektor-app/cactus/` | Cactus SDK 源码、文档和平台封装 | | `Vektor-core/` | VectorGo 后端和操作文档 | | `Vektor-core/prd.md` | 后端决策引擎的产品需求 | | `Vektor-core/README.md` | 后端用法、API 接口和运行时说明 | | `app-release.apk` | 保存在仓库根目录的预构建 Android APK 构件 | ## Vektor-App `Vektor-app` 是一个使用 Kotlin 编写的原生 Android 项目。产品文档将其定义为一张紧急身份卡、一位健康伴侣和一个沉默的守护者，旨在即使设备离线也能继续工作。 ### 核心职责 - 使用加密的设备端存储来本地保存配置文件数据。 - 监控运动、位置和传感器状况以进行紧急检测。 - 通过 Cactus SDK 和 Gemma 运行设备端推理。 - 构建紧急 payload 并将其排入队列，以确保重试安全的送达。 - 使用 Jetpack Compose 呈现用户体验。 ### 来自 PRD 的架构说明 移动端 PRD 将该应用描述为一个分层系统： - 数据层，用于处理加密偏好设置、Room 和内部文件存储。 - 传感器层，用于处理加速度计、陀螺仪、气压计和位置监控。 - AI 层，由 Cactus SDK 提供支持。 - 紧急层，用于处理倒计时、payload 创建和重试逻辑。 - 通信层，用于处理 VectorGo 客户端和 SMS 备用方案。 - UI 层，使用 Jetpack Compose 构建。 ### Cactus 集成 该应用依赖于 Cactus 进行本地 AI 推理。`Vektor-app/cactus/` 中的 Cactus 文档解释了引擎、图 API、平台封装以及特定于 SDK 的快速入门指南。实用的入口点包括： - `Vektor-app/cactus/README.md` - `Vektor-app/cactus/docs/quickstart.md` - `Vektor-app/cactus/docs/cactus_engine.md` - `Vektor-app/cactus/docs/cactus_graph.md` - `Vektor-app/cactus/android/README.md` - `Vektor-app/cactus/flutter/README.md` - `Vektor-app/cactus/python/README.md` - `Vektor-app/cactus/rust/README.md` `Vektor-app/cactus.md` 和 `Vektor-app/prd.md` 中的应用级概述阐明了预期的约定：Cactus 负责离线的大脑，而 VectorGo 是外部的编排层。 ## Vektor-Core `Vektor-core` 是 VectorGo 代理引擎。后端 PRD 将其定位为一个实时决策系统，负责处理紧急信号、对严重程度进行分类、选择医院、编排响应，并在网络连接恢复时同步离线决策。 ### 核心职责 - 接受来自应用或其他来源的紧急 payload。 - 对传入数据进行规范化和验证。 - 使用确定性逻辑对严重程度进行分类，并在配置了云端备用方案时进行回退。 - 使用实时或备用数据选择最佳医院和路线。 - 持久化紧急事件并发出实时更新。 - 在同步期间比较离线和在线决策。 ### 已记录的端点 后端 README 描述了主要的 API 接口： - `GET /health` 用于存活检查。 - `GET /api/ping` 用于正常运行时间监控。 - `GET /ready` 用于就绪检查。 - `POST /api/emergency` 用于主要的紧急接收路径。 - `POST /api/offline-sync` 用于协调离线决策与在线结果。 - `GET /api/incidents/:incidentId` 和 `POST /api/incidents/:incidentId/discharge` 用于事件工作流。 ### 运行时行为 后端文档强调了几个重要约束： - 接入过程应是确定性的，并且绝不能在常规验证路径上失败。 - 当未配置外部服务时，分类和路由应回退到基于规则的逻辑。 - 使用幂等性使得重试安全的写入变得切实可行。 - 总响应预算被设计为保持在紧急延迟目标之下。 ## 入门指南 该工作空间分为两个可独立运行的项目。确切的命令可能因本地工具链而异，但以下是文档中记录的默认值。 ### 后端 ``` cd Vektor-core npm install copy .env.example .env npm run dev ``` 使用以下命令运行测试： ``` cd Vektor-core npm test ``` ### Android 应用 在 Android Studio 中打开 `Vektor-app`，或者在该项目根目录下使用 Gradle wrapper。 典型的 Android 构建流程： ``` cd Vektor-app ./gradlew assembleDebug ``` 仓库根目录还包含 `app-release.apk`，用于即时安装和冒烟测试。 ## 构建和打包说明 Android 目录树包含主应用项目以及 Cactus SDK 子树。如果您要重新构建 SDK 绑定或原生组件，相关的支持脚本和构建文件位于 `Vektor-app/cactus/` 和 `Vektor-app/` 目录下。 需要了解的重要文件： - `Vektor-app/build.gradle.kts` - `Vektor-app/app/build.gradle.kts` - `Vektor-app/build_cactus_android.sh` - `Vektor-app/cactus/android/build.sh` - `Vektor-app/cactus/android/CMakeLists.txt` - `Vektor-core/package.json` - `Vektor-core/src/` ## 文档导航 如果您想在修改代码之前先了解系统，请按以下顺序阅读这些文档： 1. `Vektor-app/prd.md`，了解移动产品的定义和架构。 2. `Vektor-core/prd.md`，了解后端代理引擎的需求。 3. `Vektor-core/README.md`，了解当前的后端 API 和运行时行为。 4. `Vektor-app/cactus/README.md`，了解 Cactus SDK 概述和基准测试。 5. `Vektor-app/cactus/docs/quickstart.md`，了解特定于平台的 SDK 入门点。 6. `Vektor-app/cactus/docs/cactus_engine.md` 和 `Vektor-app/cactus/docs/cactus_graph.md`，了解原生引擎 API。 ## 贡献者注意事项 - 保持 `Vektor-app` 中移动优先的行为与 PRD 保持一致，特别是本地优先和仅限紧急情况的网络连接预期。 - 尽可能保持后端具有确定性，特别是在接收、验证和路由回退方面。 - 除非分发策略发生变化，否则不要移除 `app-release.apk`。 - 避免添加新的外部依赖，除非有文档说明为何需要它们以及它们在架构中的位置。

标签：Android原生开发, Cactus SDK, Firebase Realtime Database, Gemma, HTTP工具, MITM代理, PostgreSQL, VectorGo, 事件管理系统, 传感器监测, 低连通性方案, 医疗急救调度, 医院选择算法, 安卓应用, 实时响应系统, 实时数据同步, 客户端加密, 应急响应平台, 数据持久化, 智能交通调度, 智能后端引擎, 服务端决策管线, 本地优先, 测试用例, 物联网传感器, 离线AI推断, 离线检测, 移动端开发, 端侧AI, 紧急救援系统, 路径规划, 边缘计算