feat(sense): establish M1 offline intake skeleton
This commit is contained in:
QiuSW
@@ -40,7 +40,7 @@ MVP 以默认 16 路跑通一个场景的端到端闭环；架构、数据和 UI
|
||||
|
||||
## 当前阶段
|
||||
|
||||
当前为 **M0：兼容性验证 + 需求定稿**。
|
||||
当前为 **M0 实机验证暂缓、M1 Sense 无实机骨架并行推进**。无实机测试不能替代 M0 白名单或 M1 五路实机出口。
|
||||
|
||||
优先路径：
|
||||
|
||||
@@ -85,6 +85,10 @@ MVP 以默认 16 路跑通一个场景的端到端闭环；架构、数据和 UI
|
||||
python scripts/validate_agent_context.py
|
||||
python -m unittest discover -s tests -p "test_*.py"
|
||||
python scripts/validate_harness_governance.py
|
||||
go -C Sense generate ./internal/mtx
|
||||
go -C Sense test ./...
|
||||
go -C Sense vet ./...
|
||||
go -C Sense build ./...
|
||||
```
|
||||
|
||||
当前没有生产代码构建命令。代码出现后，以 [`03-tech-stack.md`](03-tech-stack.md) 的验证矩阵和当前任务门禁为准。
|
||||
日常优先运行根目录 `./init.ps1` 或 `./init.sh`，它会执行上述治理、生成、测试、静态检查和构建门禁。Sense 本地启动为 `go -C Sense run ./cmd/sense-api`；默认只监听回环地址，具体配置、MediaMTX 版本与校验方法见 [`03-tech-stack.md`](03-tech-stack.md) 和 [`../Sense/README.md`](../Sense/README.md)。
|
||||
|
||||
+26
-3
@@ -28,6 +28,18 @@
|
||||
| 指标 | Prometheus + Grafana | 三系统统一可观测入口 |
|
||||
| 追踪 | OpenTelemetry + Jaeger | 端到端事件链路 |
|
||||
|
||||
### 1.1 Sense M1 冻结版本（T-003）
|
||||
|
||||
| 组件 | 冻结版本 | 许可证 / 校验 | 升级与退出路线 |
|
||||
| --- | --- | --- | --- |
|
||||
| Go | `1.26.5`（`go 1.26.0` + `toolchain go1.26.5`） | BSD-3-Clause；从 `go.dev/dl` 校验，Windows amd64 ZIP SHA-256 `97e6b2a833b6d89f9ff17d25419ac0a7e3b482a044e9ab18cdef834bd834fd38` | 跟随仍受支持的 Go 小版本，先在 CI/目标平台跑全量测试再升级；标准 Go module，无私有运行时绑定 |
|
||||
| SQLite driver | `modernc.org/sqlite v1.54.0` | BSD-3-Clause；module sum `h1:JCxR4qwkJvOaqAoYcgDoO25Nc+ROg6EJ2LfBVzdrgog=`，go.mod sum `h1:4ntCLuNmnH8+GNqjka1wNg7KJd5/Hi5FYp8K+XQ7GZw=` | 选择无 CGO driver 以简化 Windows/边缘部署；只经 `database/sql` 与 repository 使用，可替换 driver；生产仍迁移到 PostgreSQL `sense` schema |
|
||||
| MediaMTX | `v1.19.3` | MIT；官方 release `checksums.sha256`：Windows amd64 `5d82148d1032a6a190d9909a2997d9989457aaadf49af87dd02cd4512d31bebe`、Linux amd64 `a7ba21268fccda3ebc43fdad76b87fddb85ce77e725b5cb637bca724b5394fbe`、Linux arm64 `9e5b38a5b5fcab1916341b024031b2fc5dc6a2059baed9ba3f3b0d3768d231a8` | 独立进程，不链接到 Sense；升级时先更新 vendored OpenAPI、重新生成并跑假服务契约测试；可通过 `mtx` port 更换媒体数据面 |
|
||||
| oapi-codegen | `v2.8.0` | Apache-2.0；module sum `h1:s4hxMxuqtR8jPzXkBTtFwY/SBuj3gEAYikmbBSdtLMM=`，go.mod sum `h1:yae2TI9IYB5vxQ35gFrpXh9L5H1eJv4MAUK1jumGMTo=` | 仅为构建工具；版本锁在 module tool dependency，生成文件与薄封装分离；升级后必须重新生成并检查 diff |
|
||||
| oapi-codegen runtime | `v1.6.0` | Apache-2.0；module sum `h1:7Xx+GlueD6nRuyKoCPzL434Jfi3BetbiJOrzCHp/VPU=`，go.mod sum `h1:GwV7hC2hviaMzj+ITfHVRESK5J2W/GefVwIND/bMGvU=` | 生成客户端的最小运行时；与生成器一起升级并跑假 HTTP 契约测试，退出时随生成客户端一并替换 |
|
||||
|
||||
MediaMTX 官方 `v1.19.3` OpenAPI 固定保存于 `Sense/api/vendor/mediamtx-v1.19.3.openapi.yaml`，SHA-256 为 `a2b58195f1ec76541e124b5de4ee54645e5a3e25f70c4a73acc4a44d6f2b9c52`。下载二进制后必须对照上表或官方同版 `checksums.sha256`，不得使用浮动 `latest` URL。SQLite `v1.56.0` 在本决策日刚发布，T-003 不追新；后续依赖升级单独评审。
|
||||
|
||||
## 2. 外部项目边界
|
||||
|
||||
- MiBeeNvr：只用于 M0 隔离实验室、ONVIF兼容性和交互参考，不作为生产依赖。
|
||||
@@ -37,7 +49,7 @@
|
||||
|
||||
## 3. 待冻结项
|
||||
|
||||
- Go、Python、PostgreSQL、MediaMTX、Savant/DeepStream 的精确版本。
|
||||
- Python、PostgreSQL、Savant/DeepStream 的精确版本；Go 与 MediaMTX 已为 Sense M1 冻结，后续阶段可按升级流程调整。
|
||||
- Bell 前端框架和组件库。
|
||||
- 事件投递 transport 从 HTTP 起步还是直接采用消息总线。
|
||||
- 目标 GPU/边缘硬件、解码能力和每 worker 的 `max_sources`。
|
||||
@@ -48,7 +60,7 @@
|
||||
|
||||
## 4. 当前标准入口
|
||||
|
||||
仓库当前只有文档和契约，未产生可构建生产代码。根目录脚本执行文档治理验证：
|
||||
Sense M1 骨架建立后，根目录脚本同步 Go 依赖并执行治理与 Sense 验证：
|
||||
|
||||
```powershell
|
||||
./init.ps1
|
||||
@@ -60,6 +72,17 @@ WSL/Linux/macOS/Git Bash：
|
||||
./init.sh
|
||||
```
|
||||
|
||||
Sense 单独执行：
|
||||
|
||||
```powershell
|
||||
go -C Sense mod download
|
||||
go -C Sense generate ./internal/mtx
|
||||
go -C Sense test ./...
|
||||
go -C Sense vet ./...
|
||||
go -C Sense build ./...
|
||||
go -C Sense run ./cmd/sense-api
|
||||
```
|
||||
|
||||
直接验证：
|
||||
|
||||
```powershell
|
||||
@@ -74,7 +97,7 @@ python scripts/validate_harness_governance.py
|
||||
| --- | --- | --- | --- |
|
||||
| Harness 文档/任务/Gitea 模板 | 上述三条 Python 命令 | 任一治理协议、清单或任务 schema 变化 | 不适用 |
|
||||
| `docs/raw/contracts/` | JSON Schema 校验 + 契约代码断言（实现后补命令） | schema/示例/mapper 任一变化 | 生产者与消费者联合评审 |
|
||||
| Sense Go | `go test ./...`、`go vet ./...`（代码出现后） | ONVIF、存储、MediaMTX、对账或公共 API 变化 | 命中设备任务时使用指定摄像头矩阵 |
|
||||
| Sense Go | `go -C Sense generate ./internal/mtx`、`go -C Sense test ./...`、`go -C Sense vet ./...`、`go -C Sense build ./...` | ONVIF、存储、MediaMTX、对账或公共 API 变化 | T-003 为无实机；命中 T-006 等设备任务时使用指定摄像头矩阵 |
|
||||
| Brain Python | 单元测试、类型/格式检查（命令待项目脚手架冻结） | mapper、判定状态机、模型接口变化 | 命中模型任务时用冻结数据集和目标硬件 |
|
||||
| Bell Go/Web | 后端测试 + 前端 lint/test/build（命令待脚手架冻结） | schema、RBAC、预警状态机或公共 UI 变化 | P0 流程由产品/值班角色验收 |
|
||||
| 容量/分片 | 任务内基准脚本 | 16/64/128 路里程碑 | 目标网络、媒体和 GPU 硬件必需 |
|
||||
|
||||
@@ -14,6 +14,7 @@
|
||||
出口：5 路自动建 path、探活、断线重建；使用 MediaMTX 生产数据面，完整 MiBeeNvr 不替代生产基线。
|
||||
|
||||
- T-003：建立无需真实摄像头即可验证的 Sense Go 脚手架、设备台账、ONVIF port/fake、MediaMTX 生成客户端与薄封装；完成不代表 M0/M1 出口。
|
||||
- T-003 只冻结 `/healthz`、`/readyz` 运维探针，设备管理公共 API 留给后续契约任务；真实 ONVIF adapter 不用 fake 冒充。
|
||||
- T-006：在 T-001 白名单与 T-003 骨架之上完成真实摄像头 5 路自动建 path、探活、断线恢复和 MediaMTX 集成验收。
|
||||
- T-001 暂缓期间可推进 T-003，但 T-006 和 M1 出口继续受真实设备证据阻塞。
|
||||
|
||||
|
||||
+23
@@ -42,6 +42,29 @@
|
||||
|
||||
Sense 使用 MediaMTX 官方 OpenAPI 生成客户端并加薄封装。业务代码不得散落硬编码 path API；生成代码不可手改。MediaMTX path 不是租户/站点/设备的业务真相源。
|
||||
|
||||
### 4.1 T-003 已实现的内部适配契约
|
||||
|
||||
以下是 Sense 内部 Go port，不是 Bell 或第三方可依赖的公共 HTTP API：
|
||||
|
||||
| Port | 操作 | 数据所有者 / 失败语义 |
|
||||
| --- | --- | --- |
|
||||
| ONVIF adapter | `Probe(target)`、`SetSystemDateAndTime(target, time)` | 设备是外部来源；`target` 只含 endpoint ref 与不透明 credential ref。错误稳定映射为认证失败、超时、不可用、响应无效，不记录凭据或完整流地址 |
|
||||
| MediaMTX paths | `CreatePath`、`GetPath`、`EnsurePath`、`DeletePath`、`PathReady` | SQLite 设备台账持有期望态，MediaMTX 只持有运行配置；`EnsurePath` 相同 source 不写、不同 source patch、缺失时 add；当前调和器绝不枚举或删除孤儿 |
|
||||
| Device repository | 站点、设备、期望态、实际态、调和进度 | SQLite 是 M1 期望态真相源；调和失败次数与下次时间持久化，进程重启不清空退避；配额读取/写入失败时拒绝新增或启用，不关闭已有流 |
|
||||
|
||||
MediaMTX 薄封装调用同版官方 OpenAPI 的 `/v3/config/paths/get|add|patch|delete/{name}` 与 `/v3/paths/get/{name}`。生成源、版本和 SHA-256 见 `docs/03-tech-stack.md`；业务包不得直接 import 生成包。
|
||||
|
||||
### 4.2 设备台账语义
|
||||
|
||||
- 设备类型由 `modality` 表达物理类别，由多值 `capabilities` 表达视频采集、音频、空间规则或遥测能力，避免把“摄像头”固化为唯一设备模型。
|
||||
- 视频配额只统计 `desired_state=enabled` 且具有 `video_capture` capability 的设备；站点默认 16、可配置 1～128。禁用设备和非视频传感器不占视频路数。
|
||||
- SQLite 表使用 `sense_` 前缀对应未来 PostgreSQL `sense` schema：`sense_sites`、`sense_devices`、`sense_device_capabilities`、`sense_reconcile_state`。标识、唯一性、状态与时间字段语义保持一致；本地表名前缀不是跨系统公共契约。
|
||||
- 摄像头密码不进入设备普通字段。`credential_ref` 只保存外部密钥引用；ONVIF 返回的 stream URI 只在内存中传给 MediaMTX，不写入设备台账或日志。
|
||||
|
||||
### 4.3 Sense 进程 HTTP 面
|
||||
|
||||
T-003 只提供运维探针：`GET /healthz` 表示进程存活，`GET /readyz` 表示配置、SQLite 打开及 migration 已完成。两者返回 JSON，均不等价于摄像头、MediaMTX path 或 M1 里程碑健康。设备管理、认证、分页、幂等键与并发控制尚未冻结，因此本任务不暴露 `/api/v1/devices` 等临时接口。
|
||||
|
||||
## 5. 变更流程
|
||||
|
||||
1. 在对应任务文件写清调用方、提供方、数据所有者、失败语义、幂等与兼容策略。
|
||||
|
||||
+14
-5
@@ -5,12 +5,15 @@
|
||||
## 当前阶段
|
||||
|
||||
- 阶段：M0 摄像头兼容性验证尚未完成；已批准并行推进不依赖真实摄像头的 M1 Sense 软件骨架，但不得提前宣称 M0/M1 出口完成。
|
||||
- 生产代码：尚未开始。
|
||||
- 生产代码：Sense M1 无实机骨架已建立，包含可构建进程、SQLite 台账、ONVIF port/fake、MediaMTX 生成客户端、最小对账与探活；真实 ONVIF adapter 和五路设备验收仍未开始。
|
||||
- 默认容量：16 路；单站点本阶段上限 128 路，必须横向分片。
|
||||
|
||||
## 仓库现实
|
||||
|
||||
- `Sense/`、`Brain/`、`Bell/` 只有目录占位。
|
||||
- `Sense/` 已有 Go module 与 `cmd/sense-api`；`Brain/`、`Bell/` 仍只有目录占位。
|
||||
- Sense 设备模型使用 `modality + capabilities`，SQLite 执行 v1 migration；视频配额默认 16、允许 1～128，17/128/129、新增/启用和“降低配额不关闭已有流”均有测试。
|
||||
- MediaMTX 固定为独立二进制 `v1.19.3`，官方 OpenAPI 已按 SHA-256 vendoring，并由固定 `oapi-codegen v2.8.0` 生成客户端；手写薄封装有 create/read/delete、幂等 ensure 与探活假 HTTP 测试。
|
||||
- T-003 对账进度与指数退避持久化，覆盖取消和 SQLite 重启恢复；当前不枚举/删除孤儿，也不包含真实摄像头 adapter。
|
||||
- `docs/raw/01`～`08` 已记录需求、分析、方案、客户场景、事件比对和三系统职责。
|
||||
- `docs/raw/contracts/event-v0.1.schema.json` 已冻结，并有多份示例与语义说明。
|
||||
- harness coding 文档、上下文清单、Gitea Issue/PR 模板和治理脚本已接入。
|
||||
@@ -27,6 +30,12 @@ Windows：
|
||||
./init.ps1
|
||||
```
|
||||
|
||||
该入口会下载锁定 Go module，运行三条治理验证、MediaMTX 客户端生成漂移检查、`go test`、`go vet` 和 `go build`。只启动 Sense：
|
||||
|
||||
```powershell
|
||||
go -C Sense run ./cmd/sense-api
|
||||
```
|
||||
|
||||
跨平台直接验证：
|
||||
|
||||
```powershell
|
||||
@@ -35,7 +44,7 @@ python -m unittest discover -s tests -p "test_*.py"
|
||||
python scripts/validate_harness_governance.py
|
||||
```
|
||||
|
||||
当前没有 Go/Python 业务依赖安装、生产服务启动或端到端命令。M1 脚手架创建时必须同步更新标准入口。
|
||||
Sense 默认监听 `127.0.0.1:8080`，提供 `/healthz` 与 `/readyz` 运维探针；它们不代表摄像头或 M1 里程碑健康。MediaMTX 获取、校验和独立启动方法见 `Sense/README.md`。
|
||||
|
||||
## 当前 blocker / 待确认
|
||||
|
||||
@@ -43,12 +52,12 @@ python scripts/validate_harness_governance.py
|
||||
- S2 真实生产试点的未成年人影像、公共安全视频法规适用性和最终留存政策仍需客户/法务确认，阻塞 M3 上线但不阻塞 M1 实验室骨架。
|
||||
- 人脸方向已延后至 M5 的 S4 成人园区候选试点；必要性/PIP 影响评估、单独同意与替代方式、合法底库来源和删除流程未完成，阻塞人脸能力上线。
|
||||
- 短信/语音具体供应商未选；生产前必须选定两条独立投递路径并验证故障切换。
|
||||
- Go/Python/PostgreSQL/MediaMTX/Savant 的精确版本、目标硬件和 Bell 前端栈尚未冻结。
|
||||
- Python/PostgreSQL/Savant 的精确版本、目标硬件和 Bell 前端栈尚未冻结；Sense M1 的 Go、SQLite driver、MediaMTX、生成器及生成运行时版本已在 T-003 冻结。
|
||||
- 代码知识图谱在无业务代码阶段可能为空；工具不可用时使用 `rg` 处理文档与配置。
|
||||
|
||||
## 下一步
|
||||
|
||||
从 Gitea 的 `status/todo` 工单中由 dispatcher 分配依赖已满足、编号最靠前且写路径不冲突的任务。当前建议领取重构后的 T-003，先完成无实机 Sense 骨架；T-001 恢复后完成兼容性白名单，T-006 再执行真实摄像头 5 路集成验收。不要仅凭本文宣称领取成功。
|
||||
T-003 合入后仍不能宣称 M0/M1 出口完成。恢复 T-001 后先形成摄像头兼容性白名单，再领取依赖 T-001 与 T-003 的 T-006，完成真实摄像头 5 路自动建 path、探活、断线恢复和 MediaMTX 证据。实时领取状态仍以 Gitea 为准。
|
||||
|
||||
## 已知风险
|
||||
|
||||
|
||||
+22
-1
@@ -3,7 +3,7 @@ id: T-003
|
||||
title: 建立 Sense M1 无实机接入骨架
|
||||
phase: 1
|
||||
deps: [T-002]
|
||||
status: DOING
|
||||
status: DONE
|
||||
created: 2026-08-03
|
||||
issue: 3
|
||||
context_ref: e28070dd035cef3ff3e4a2dad879a482c41dac3a
|
||||
@@ -12,6 +12,7 @@ work_branch: agent/codex/T-003
|
||||
write_paths:
|
||||
- docs/tasks/T-003.md
|
||||
- Sense/
|
||||
- docs/00-ai-start-here.md
|
||||
- docs/03-tech-stack.md
|
||||
- docs/api.md
|
||||
- docs/06-tasks.md
|
||||
@@ -81,3 +82,23 @@ write_paths:
|
||||
- 本任务收敛为 fake ONVIF、MediaMTX 假服务、SQLite 和可选合成 RTSP 可验证的生产骨架；不得用 mock 测试宣称 M0 或 M1 里程碑完成。
|
||||
- 真实设备、5 路自动建 path、探活、断线恢复和 MediaMTX 证据拆到 T-006，依赖 T-001 与 T-003。
|
||||
- 任务尚未领取；Issue #3 在本次规格合入默认分支前不进入 `status/todo`。
|
||||
|
||||
### 2026-08-04 版本与实现决策
|
||||
|
||||
- 冻结 Go `1.26.5`、MediaMTX `v1.19.3`、`oapi-codegen v2.8.0` 与 `modernc.org/sqlite v1.54.0`；许可证、module sum、MediaMTX 二进制 SHA-256、OpenAPI SHA-256、升级策略与退出路线已写入 `docs/03-tech-stack.md`。
|
||||
- SQLite driver 使用无 CGO 的 `modernc.org/sqlite`，但业务代码只依赖 `database/sql` repository；migration 避免 SQLite 专有业务语义，后续映射到 PostgreSQL `sense` schema。
|
||||
- 设备模型使用 `modality + capabilities`；视频配额只统计期望启用且具备视频采集能力的设备。站点默认 16、配置允许 1～128，超出时拒绝新增/启用，已有流不受影响。
|
||||
- 数据库持有期望态；ONVIF、MediaMTX 均由 port/adapter 隔离。T-003 实现确定性 fake 与假 HTTP 契约测试，不提供真实厂商兼容结论；对账只创建/修正应有 path，不做孤儿删除。
|
||||
- MediaMTX 官方 OpenAPI 按 tag vendoring，生成代码不可手改；薄封装负责状态码、幂等与领域错误映射。服务默认只监听 `127.0.0.1`，非回环监听必须显式开启。
|
||||
- 实现中发现标准 AI 入口仍会宣称“没有生产代码”。dispatcher 串行读回 Gitea 后确认只有 T-003 处于活跃状态、无路径冲突，并以完整 `CLAIM RENEWAL` 将 `docs/00-ai-start-here.md` 加入写入范围；worker 已同步本文件后才修改该入口。
|
||||
|
||||
### 2026-08-04 实现与验证证据
|
||||
|
||||
- 建立 `Sense/go.mod`、`cmd/sense-api`、SQLite v1 migration 与 device/store/onvif/mtx/reconcile/probe 包。进程默认回环监听，只提供 `/healthz`、`/readyz`；真实 ONVIF adapter 显式返回 unavailable，避免把 fake 冒充生产兼容实现。
|
||||
- vendoring MediaMTX `v1.19.3` 官方 OpenAPI，输入 SHA-256 为 `a2b58195f1ec76541e124b5de4ee54645e5a3e25f70c4a73acc4a44d6f2b9c52`；`go generate ./internal/mtx` 生成文件 SHA-256 在重复生成前后均为 `9e10d96eac1b332783d7cbfaba5872fede62a16ef6ccc1062cdb246607db7dac`。
|
||||
- SQLite 测试覆盖默认第 17 路拒绝、配置 128 路成功、第 129 路拒绝、禁用第 17 路重新启用拒绝、非视频设备不占额度，以及下调配额不关闭已有流。migration、唯一性、期望态 generation 和持久化退避由同一 repository 测试链路执行。
|
||||
- ONVIF fixture 覆盖 profile、脱敏 stream URI、校时、认证失败和取消/超时；MediaMTX 假 HTTP 服务覆盖官方生成客户端的 create/read/delete、ensure 幂等/patch、runtime path 探活和错误脱敏。
|
||||
- 对账测试覆盖成功收敛后不重复、指数退避、取消不消耗重试预算和关闭/重开 SQLite 后恢复；探活测试覆盖 online/offline 映射。对账器不调用 `DeletePath`，没有孤儿删除旁路。
|
||||
- `go test -race ./...` 全部通过；`go test ./... -count=2` 连续两轮通过；`go vet ./...`、`go build ./...` 通过。实际构建 `sense-api` 后在随机回环端口用绕过系统代理的 curl 验证 `health=ok`、`ready=ready`，临时 EXE、SQLite 和日志随后逐项删除。
|
||||
- 根标准入口 `./init.ps1` 通过：agent-context 校验、18 项治理测试、harness 治理校验、生成漂移检查、Sense 全量测试、vet 与 build 均成功。人工核对生成头为 `oapi-codegen v2.8.0`、OpenAPI/二进制下载使用固定 `v1.19.3` URL 和 SHA-256、MediaMTX/Sense 管理端默认只绑定回环地址。
|
||||
- 设备人工验收不适用：未连接摄像头，未宣称 T-001 白名单、真实 5 路或 M0/M1 出口完成；这些证据仍由 T-006 在 T-001 恢复后提供。
|
||||
|
||||
Reference in New Issue
Block a user