# 技术栈

> 已决项必须遵守；标为“待定”的版本或组件不得由 agent 自行拍板，应先落 Gitea Issue 并更新本文。

## 1. 已定技术方向

| 范围 | 选择 | 状态与说明 |
| --- | --- | --- |
| 首期部署 | 客户侧私有化实例 | 保留 `tenant_id`、RBAC、schema 和 API 的 SaaS-ready 隔离边界 |
| M1–M3 视频接入 | ONVIF / RTSP | 售前盘点存量 NVR；GB/T 28181-2022 不进当前 MVP，按需另建适配任务 |
| Sense | Go | 设备、ONVIF、MediaMTX 控制与对账 |
| 媒体数据面 | MediaMTX 独立二进制 | MIT；M1 正式生产基线 |
| MediaMTX API | 从官方 OpenAPI 用 `oapi-codegen` 生成 + 薄封装 | 不依赖第三方非官方 SDK |
| Brain | Python / CUDA | 推理流水线与判定内核 |
| 推理框架主选 | Savant / NVIDIA DeepStream | M1–M3 只验证 NVIDIA x86/Jetson；具体版本与目标 GPU 待 M0/M1 压测冻结 |
| 推理框架/硬件逃生通道 | ONNX 接口 + 可替换框架适配层；Pipeless 候选 | 信创不在 M1–M3 承诺内，海光/鲲鹏/昇腾/寒武纪走独立硬件 POC 与报价 |
| 模型主选 | Ultralytics YOLO（含 pose） | 商用前必须购买 Enterprise License |
| 模型备选 | YOLOX + RTMPose | 主选授权未批或目标硬件不适配时启用 |
| 跟踪/同一性 | ByteTrack 或 BoT-SORT + ReID | 具体组合待基准测试；ReID 默认、人脸可选 |
| Bell 后端 | Go | 事件、规则、预警、租户与审计 |
| Bell 客户端 | 值班室 Web + 响应式移动 H5 | 前端框架仍须经 UI 原型和技术评审冻结；M3 不做独立原生 App |
| Bell 对外集成 | 版本化 OpenAPI / Webhook | Bell 持有事件、Alert、ack、升级链、租户与审计真相 |
| M1 本地存储 | SQLite | schema 与生产 PostgreSQL 保持一致，仅 Sense 初期使用 |
| 生产数据库 | PostgreSQL，一个实例、`sense`/`bell` schema 分离 | Brain 无业务 schema |
| 证据对象存储 | 客户侧 MinIO / S3 兼容 | 常态录像留在客户 NVR；事件片段技术默认 30 天，最终期限由客户/法务确认 |
| 通知投递 | Bell provider 接口 | 供应商待项目采购；试点使用本地声光/Web + 一条短信或语音，生产前两条独立路径并支持故障切换 |
| 边缘隧道 | WireGuard | 控制面管理 |
| 指标 | Prometheus + Grafana | 三系统统一可观测入口 |
| 追踪 | OpenTelemetry + Jaeger | 端到端事件链路 |

## 2. 外部项目边界

- MiBeeNvr：只用于 M0 隔离实验室、ONVIF兼容性和交互参考，不作为生产依赖。
- MediaMTX：生产媒体数据面，不提供 YoVision 业务管理 UI。
- silver_pose：独立可交付仓库，是 Brain 判定内核的来源；不改名、不合并。
- `_reference/`：只读、忽略、不进入模块依赖和生产镜像。

## 3. 待冻结项

- Go、Python、PostgreSQL、MediaMTX、Savant/DeepStream 的精确版本。
- Bell 前端框架和组件库。
- 事件投递 transport 从 HTTP 起步还是直接采用消息总线。
- 目标 GPU/边缘硬件、解码能力和每 worker 的 `max_sources`。
- MinIO/S3 的精确版本、加密实现，以及客户/法务确认后的最终生命周期策略。
- 短信/语音供应商及生产双路径组合；是否开发原生 App 最早在 M4 根据试点反馈决定。

这些选项必须在对应任务中记录基准、许可证、运维成本和退出路线。

## 4. 当前标准入口

仓库当前只有文档和契约，未产生可构建生产代码。根目录脚本执行文档治理验证：

```powershell
./init.ps1
```

WSL/Linux/macOS/Git Bash：

```bash
./init.sh
```

直接验证：

```powershell
python scripts/validate_agent_context.py
python -m unittest discover -s tests -p "test_*.py"
python scripts/validate_harness_governance.py
```

## 5. 验证矩阵

| 改动范围 | 每次必跑 | 完整门禁触发条件 | 人工/设备门禁 |
| --- | --- | --- | --- |
| Harness 文档/任务/Gitea 模板 | 上述三条 Python 命令 | 任一治理协议、清单或任务 schema 变化 | 不适用 |
| `docs/raw/contracts/` | JSON Schema 校验 + 契约代码断言（实现后补命令） | schema/示例/mapper 任一变化 | 生产者与消费者联合评审 |
| Sense Go | `go test ./...`、`go vet ./...`（代码出现后） | ONVIF、存储、MediaMTX、对账或公共 API 变化 | 命中设备任务时使用指定摄像头矩阵 |
| Brain Python | 单元测试、类型/格式检查（命令待项目脚手架冻结） | mapper、判定状态机、模型接口变化 | 命中模型任务时用冻结数据集和目标硬件 |
| Bell Go/Web | 后端测试 + 前端 lint/test/build（命令待脚手架冻结） | schema、RBAC、预警状态机或公共 UI 变化 | P0 流程由产品/值班角色验收 |
| 容量/分片 | 任务内基准脚本 | 16/64/128 路里程碑 | 目标网络、媒体和 GPU 硬件必需 |

代码脚手架落地时必须把真实命令同步到本文、`init.ps1`/`init.sh`、`00-ai-start-here.md` 和 `current-state.md`。