水域哨兵

AI 水域安全智能体 —— 面向浙江杭州、舟山等典型水上运动场景的公共安全治理平台

融合固定摄像头、计算机视觉、多模态大模型、气象水文数据与救援资源信息，实现 视觉巡检 → 风险预测 → 智能预警 → 应急决策 → 人工确认 → 协同救援的闭环。

四项核心能力

1. AI 视觉巡检 —— 看现场：人数、区域分布、危险区域进入、疑似异常人员、救生衣状态
2. 水域风险预测 —— 看现在、看未来：当前风险 + 未来 15/30 分钟风险，含原因与建议
3. AI 应急协同 —— 事件创建 → 资源与 ETA 查询 → Agent 生成方案 → 人工确认 → 执行 → 复盘
4. AI 安全助手 —— 问数、问因、问策，经后端工具查询真实数据

技术栈

| 层 | 选型 | | --- | --- | | 后端 | Python 3.12 · FastAPI · SQLAlchemy 2.0 (async) · Pydantic v2 | | 前端 | Vue 3 · TypeScript · Vite 6 · Pinia · Vue Router 4 | | 决策 Agent | DeepSeek-V4-Flash（Tool Calling） | | 多模态复核 | Qwen3.5-Flash | | 视觉感知 | YOLO + ByteTrack | | 测试 | pytest · vitest | | 规范 | ruff · mypy(strict) · eslint · vue-tsc |

快速开始

后端

cd backend
py -3.12 -m venv .venv                                     # 需要 Python 3.12
./.venv/Scripts/python.exe -m pip install -e ".[dev]"      # Linux/macOS: ./.venv/bin/python
cp .env.example .env                                       # 按需填写模型密钥
./.venv/Scripts/python.exe -m uvicorn app.main:app --reload

接口文档：http://127.0.0.1:8000/docs

前端

cd frontend
npm install
npm run dev

访问 http://localhost:5173，/api 已代理至后端。

质量校验

# 后端
cd backend && ./.venv/Scripts/python.exe -m pytest && ./.venv/Scripts/python.exe -m ruff check . && ./.venv/Scripts/python.exe -m mypy

# 前端
cd frontend && npm test && npm run type-check && npm run lint

项目结构

backend/app/
  api/v1/       接口层：路由、请求响应模型
  services/     逻辑层：业务编排
  domain/       领域层：风险模型与算法（纯 Python，无框架依赖）
  repositories/ 数据层：数据库查询
  agent/        Agent 工具注册表与护栏
  perception/   YOLO / Qwen 感知适配
  integrations/ 气象、水文外部数据
  core/         配置、日志、异常

frontend/src/
  features/     按页面切分的功能模块（驾驶舱 / 风险分析 / 应急事件 / AI 助手）
  components/   跨功能复用组件
  api/ stores/ composables/ types/ router/ layouts/ styles/ utils/

docs/           赛题需求、资料包、开发过程记录
deploy/         部署编排

依赖方向严格单向：api → services → repositories → db，domain 不依赖任何层。

文档

• 需求说明书（当前版本）：docs/赛题/水域哨兵——AI水域安全智能体决赛版系统需求-v2.md
• 需求说明书 v1（已被取代，仅供参考）：docs/赛题/《水域哨兵》多模态水域安全治理智能体——系统需求说明书-v1.md
• 技术选型分析：docs/赛题/分析.md
• 开发过程记录：docs/开发过程/
• 开发约定（面向人与 AI 代理）：AGENTS.md