From c9251daadf665bfe2fd723715edfccab17977d89 Mon Sep 17 00:00:00 2001 From: QiuSW <105186638@qq.com> Date: Wed, 5 Aug 2026 17:38:54 +0800 Subject: [PATCH] docs(camera): approve single Hikvision baseline --- .gitignore | 3 + docs/00-ai-start-here.md | 4 +- docs/06-tasks.md | 2 +- docs/current-state.md | 4 +- docs/quality-document.md | 2 +- docs/research/camera-compatibility.md | 109 ++++++++++++++++++++++++++ docs/tasks/T-001.md | 25 +++++- docs/tasks/T-006.md | 5 ++ 8 files changed, 144 insertions(+), 10 deletions(-) create mode 100644 docs/research/camera-compatibility.md diff --git a/.gitignore b/.gitignore index 5803dfb..c2711ac 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,9 @@ agent_sessions.txt gitea.env gitea.env.* !gitea.env.example +ip_camera.env +ip_camera.env.* +!ip_camera.env.example # 常见构建与测试缓存 __pycache__/ diff --git a/docs/00-ai-start-here.md b/docs/00-ai-start-here.md index 908982d..1fa19b7 100644 --- a/docs/00-ai-start-here.md +++ b/docs/00-ai-start-here.md @@ -40,11 +40,11 @@ MVP 以默认 16 路跑通一个场景的端到端闭环；架构、数据和 UI ## 当前阶段 -当前为 **M0 指定型号实机准入待执行，M1 Sense 无实机骨架已建立**。后续本地开发统一使用现有一台海康样机，多路软件闭环使用独立合成 RTSP 源补足；真实多设备证据延后到客户/借用/租赁条件具备时执行。 +当前为 **M0 指定型号实机准入已完成，M1 Sense 五路混合源集成待执行**。后续本地开发统一使用已准入的一台海康样机，多路软件闭环使用独立合成 RTSP 源补足；真实多设备证据延后到客户/借用/租赁条件具备时执行。 优先路径： -1. M0：一台真实样机完成首期指定“型号 + 硬件版本 + 固件”ONVIF/RTSP 准入；结论不外推为多品牌兼容。 +1. M0：已用一台真实样机完成首期指定“型号 + 硬件版本 + 固件”ONVIF/RTSP 准入；结论不外推为多品牌兼容，真实断网恢复证据按负责人豁免留痕。 2. M1：只在 `Sense/` 建立 MediaMTX 生产接入骨架，以 1 路准入实机 + 至少 4 路独立合成源完成五路自动建 path、探活和断线重建。 3. M2：对账、多租户、隧道和至少一个站点的 16 路全流程。 4. M3：Brain + Bell 起步，默认 16 路端到端事件、预警、ack 与误报反馈。 diff --git a/docs/06-tasks.md b/docs/06-tasks.md index 40abd24..096e69a 100644 --- a/docs/06-tasks.md +++ b/docs/06-tasks.md @@ -16,7 +16,7 @@ - T-003：建立无需真实摄像头即可验证的 Sense Go 脚手架、设备台账、ONVIF port/fake、MediaMTX 生成客户端与薄封装；完成不代表 M0/M1 出口。 - T-003 只冻结 `/healthz`、`/readyz` 运维探针，设备管理公共 API 留给后续契约任务；真实 ONVIF adapter 不用 fake 冒充。 - T-006：在 T-001 指定准入基线与 T-003 骨架之上，以 1 路海康实机 + 至少 4 路可独立启停的合成 RTSP 源完成五路自动建 path、探活、恢复和 MediaMTX 实验室集成验收。 -- T-003 已完成；T-006 只等待 T-001 指定实机证据及合成源准备，不要求当前购买更多摄像头。 +- T-001 与 T-003 已完成；T-006 可领取实施，只需准备至少 4 条可独立启停的合成源，不要求当前购买更多摄像头。 ## M2：对账、多租户投影与 16 路全流程 diff --git a/docs/current-state.md b/docs/current-state.md index 377067c..1a0af9c 100644 --- a/docs/current-state.md +++ b/docs/current-state.md @@ -48,7 +48,7 @@ Sense 默认监听 `127.0.0.1:8080`，提供 `/healthz` 与 `/readyz` 运维探 ## 当前 blocker / 待确认 -- 项目负责人已将 T-001 重构为一个指定型号/固件基线、至少一台真实样机的 ONVIF/RTSP 准入；数量条件已满足，但实物身份、隔离网络、ONVIF 账号和原始证据仍须在领取后核验。单样机结论不代表批次或多品牌兼容。 +- T-001 已完成一台 HIKVISION `DS-2CD3321FD-IW1-T`、硬件 `0x0`、固件 `V5.5.61 build 180929` 的 ONVIF/RTSP 指定基线准入；主/子码流、错误鉴权、三个 ONVIF 核心操作和时间漂移均有脱敏证据。项目负责人豁免了无法现场执行的三次真实断网恢复，该项没有原始时间线，单样机结论也不代表批次或多品牌兼容。 - 后续本地开发统一使用现有一台 Hikvision IP Camera；T-006 以该实机 + 至少 4 条独立合成 RTSP 源完成五路软件闭环，不要求当前购买更多摄像头。合成 publisher 的具体工具和版本在 T-006 领取后冻结。 - T-007 保留至少 5 条独立真实上游的客户现场门禁，可使用客户授权、借用或租赁设备；它不阻塞本地开发/M1 实验室出口，但继续阻塞生产试点和真实多路 SLA。 - S2 真实生产试点的未成年人影像、公共安全视频法规适用性和最终留存政策仍需客户/法务确认，阻塞 M3 上线但不阻塞 M1 实验室骨架。 @@ -59,7 +59,7 @@ Sense 默认监听 `127.0.0.1:8080`，提供 `/healthz` 与 `/readyz` 运维探 ## 下一步 -先领取并完成 T-001 海康指定型号准入；随后 T-006 使用该一台实机和至少 4 条独立合成 RTSP 上游完成五路软件闭环，无需采购额外摄像头。客户/借用/租赁条件具备后再执行 T-007 真实多路现场门禁。实时领取状态仍以 Gitea 为准。 +下一步领取 T-006，使用 T-001 已准入的一台实机和至少 4 条独立合成 RTSP 上游完成五路软件闭环，无需采购额外摄像头。客户/借用/租赁条件具备后再执行 T-007 真实多路现场门禁。实时领取状态仍以 Gitea 为准。 ## 已知风险 diff --git a/docs/quality-document.md b/docs/quality-document.md index 28cac26..5c19915 100644 --- a/docs/quality-document.md +++ b/docs/quality-document.md @@ -25,7 +25,7 @@ | 领域 | 评级 | 验证状态 | Agent 可读性 | 测试稳定性 | 关键缺口 | 上次更新 | |------|------|---------|-------------|-----------|---------|---------| | Harness 文档与任务治理 | A | 三条治理命令通过 | A | A | 需观察真实多轮任务是否顺畅 | 2026-08-03 | -| 摄像头接入与媒体 | N/A | M0/M1 未完成 | B（设计清楚） | N/A | T-001 单海康准入、Sense 代码、T-006 单实机混合五路 smoke；生产前补 T-007 真实多路现场证据 | 2026-08-04 | +| 摄像头接入与媒体 | C | M0 单海康指定基线已准入，M1 未完成 | B（设计与单实机证据清楚） | B（单次 605 秒双码流） | T-006 单实机混合五路 smoke、真实断网恢复；生产前补 T-007 真实多路现场证据 | 2026-08-05 | | 推理与事件契约 | C | 契约已冻结，生产者未实现 | A | N/A | Brain mapper、契约测试和硬件基准 | 2026-08-03 | | 规则、预警与处置 | N/A | M3 未开始 | B（设计清楚） | N/A | Bell、ack/升级、投递与 UI | 2026-08-03 | | 多租户、RBAC 与审计 | N/A | M3 未开始 | B（设计清楚） | N/A | schema、鉴权和隔离测试 | 2026-08-03 | diff --git a/docs/research/camera-compatibility.md b/docs/research/camera-compatibility.md new file mode 100644 index 0000000..76f29c0 --- /dev/null +++ b/docs/research/camera-compatibility.md @@ -0,0 +1,109 @@ +# 指定摄像头型号准入记录 + +## 1. 结论 + +- 准入状态：`approved`，包含项目负责人对“三次真实网络断开恢复”的一次性证据豁免。 +- 准入范围：仅限本记录冻结的一台 HIKVISION `DS-2CD3321FD-IW1-T`、硬件版本 `0x0`、固件 `V5.5.61 build 180929`。 +- 不适用范围：其他型号、硬件版本、固件、生产批次、厂商、多台真实设备故障隔离、16/64/128 路容量和生产 SLA。 +- 测试日期：2026-08-04 至 2026-08-05（Asia/Shanghai）。 + +## 2. 脱敏设备与网络基线 + +| 项目 | 冻结值 | +|---|---| +| 厂商 | HIKVISION | +| 型号 | `DS-2CD3321FD-IW1-T` | +| 设备类型 | `IPCamera` | +| 硬件版本 | `0x0`；ONVIF HardwareId 为 `88` | +| 固件 | `V5.5.61 build 180929` | +| 编码器 | `V7.1 build 180929` | +| 样机标识 | 序列号 SHA-256 前 12 位：`e9ed6a555ae0`；不保存原始序列号 | +| 网络 | 公网 DDNS + NAT 端口映射；不记录主机名、内网地址或完整 URI | +| RTSP | TCP 传输；外部端口 554 | +| ONVIF | SOAP 1.2 + WS-Security UsernameToken PasswordDigest；外部端口 8008 | +| 凭据 | RTSP 与 ONVIF 使用独立配置项；只存在本机私有 `ip_camera.env`，不得提交仓库 | + +摄像头通过 ONVIF 返回内网 XAddr 和内网 RTSP 地址。公网/NAT 接入时，Sense 必须保留服务路径并把主机与端口重写为部署配置；不得把本次私有地址或海康域名写死在业务代码中。 + +## 3. 可重复测试步骤 + +1. 在仓库外或被 Git 忽略的 `ip_camera.env` 中配置主机、RTSP/ONVIF 端口以及两组独立凭据。 +2. 通过 ONVIF `GetDeviceInformation` 与海康 ISAPI `GET /ISAPI/System/deviceInfo` 交叉核对型号、硬件和固件；序列号只生成摘要，不保存原值。 +3. 依次调用 `GetProfiles`、`GetStreamUri`、`GetSystemDateAndTime` 与 `SetSystemDateAndTime`。时间设置测试先读取模式、时区和夏令时，再原样写回；手动模式只校准 UTC。 +4. 使用一次性不存在的用户名分别请求 RTSP 与 ONVIF，确认被拒绝；随后立即使用正确凭据请求，确认没有误锁定。 +5. 使用 FFmpeg 通过 RTSP over TCP 同时解码主、子码流，不保存视频： + + ```text + ffmpeg -hide_banner -loglevel warning -nostats -progress pipe:1 \ + -rtsp_transport tcp -i "rtsp://:@:/" \ + -map 0:v:0 -an -t 605 -f null - + ``` + +6. 在持续测试前后分别读取摄像头 UTC，记录相对测试机 UTC 的偏差。 +7. 原规格要求真实断网并恢复至少三次；本轮因项目负责人不在摄像头现场未执行，按第 6 节的负责人裁决处理。 + +命令行示例只使用占位符。实际账号、密码、主机名、完整 RTSP URI、ONVIF XAddr、可复用 token 和视频画面均未写入本记录。 + +## 4. 实测结果 + +### 4.1 ONVIF 与设备身份 + +| 检查项 | 结果 | 脱敏证据摘要 | +|---|---|---| +| `GetDeviceInformation` | PASS | HTTP 200；厂商/型号/固件与 ISAPI 一致 | +| `GetProfiles` | PASS | HTTP 200；返回 `mainStream`、`subStream` 两个 Profile | +| `GetStreamUri` | PASS | HTTP 200；分别指向通道 `101`、`102`，URI 不内嵌凭据 | +| `SetSystemDateAndTime` | PASS | HTTP 200；写后读取成功，Manual、`CST-8:00:00`、关闭夏令时均保持不变 | +| NAT 地址处理 | OBSERVED | 返回地址需要重写主机与端口；服务路径和通道路径可保留 | + +### 4.2 RTSP 主/子码流 + +| 通道 | 媒体属性 | 连续媒体时长 | 解码帧数 | 退出码 | 警告/错误 | +|---|---|---:|---:|---:|---:| +| 主码流 `101` | H.264，1920×1080，18 fps；AAC 16 kHz 单声道 | 605.0 秒 | 10,890 | 0 | 0 | +| 子码流 `102` | H.264，704×576，15 fps | 605.0 秒 | 9,076 | 0 | 0 | + +两路同时运行，墙钟时长约 607 秒。测试只解码并丢弃输出，没有保存人物画面或媒体文件。 + +### 4.3 认证失败与恢复 + +| 协议 | 错误凭据 | 随后正确凭据 | +|---|---|---| +| RTSP | `401 Unauthorized`，PASS | 主码流探测成功，PASS | +| ONVIF | SOAP 未授权，HTTP 400，PASS | `GetDeviceInformation` HTTP 200，PASS | + +每个协议只执行一次无效身份请求，并使用不存在的临时用户名，避免连续错误触发真实账号锁定。 + +### 4.4 时间漂移 + +| 采样点 | 摄像头相对测试机 UTC 偏差 | +|---|---:| +| 605 秒双码流测试前 | 2.3 秒 | +| 测试后 | 2.8 秒 | +| 偏差增长 | 0.5 秒 | + +摄像头时间接口只提供整秒精度，网络往返也计入样本；本结果证明本次观察窗口未出现明显漂移，不构成长周期时钟稳定性承诺。 + +## 5. 失败与工具兼容记录 + +- 首次 605 秒测试在打开输入前失败：本机 FFmpeg 不支持 `-rw_timeout` 参数，两路均未连接摄像头。删除不兼容参数后重新从零执行完整 605 秒测试并通过；失败记录不计为摄像头故障，也不删除。 +- ONVIF 初次启用时，设备曾返回“ONVIF integrate function is disabled”；启用集成协议后服务可发现。独立 ONVIF 用户初次权限不足，后续调整后设备信息、媒体读取和时间设置均通过。 + +## 6. 断网恢复负责人豁免 + +- 原门禁：真实网络断开与恢复至少三次，并保留每次时间线。 +- 实际情况：项目负责人不在摄像头旁边，2026-08-05 明确要求“第 4 点当作已完成”。本轮没有执行摄像头断电、物理断网或端口映射中断，也没有三次恢复原始时间线。 +- 治理处理：该项标记为 `WAIVED`，由项目负责人承担验收裁决；T-001 可关闭，但证据不得表述为 `PASS` 或“已验证自动恢复”。 +- 下游约束：T-006 仍须独立验证真实摄像头/网络短时离线、合成 publisher、Sense 和 MediaMTX 四类恢复；本豁免不能被 T-006、T-007 或生产 SLA 继承。 + +## 7. 安全与局限 + +- `ip_camera.env` 已加入 `.gitignore`；仓库只记录字段语义，不记录实际凭据。 +- 本次通过公网/NAT 测试，不能替代隔离局域网、客户现场弱网或跨 VLAN 发现测试。 +- 单台旧固件样机只能证明这一精确基线可接入，不能证明同型号其他批次或更新固件兼容。 +- 本记录没有评估画质、码率上限、夜视、音频质量、存储、AI 检出率或多路容量。 +- 公网不应长期裸露 RTSP/ONVIF；生产部署需要 VPN、专网或来源 IP 白名单。 + +## 8. 最终准入裁决 + +精确基线 HIKVISION `DS-2CD3321FD-IW1-T` / 硬件 `0x0` / 固件 `V5.5.61 build 180929` 标记为 `approved`。该裁决包含第 6 节的负责人证据豁免；任何型号、硬件或固件变化均恢复为未验证状态，并至少重跑受影响矩阵。 diff --git a/docs/tasks/T-001.md b/docs/tasks/T-001.md index 31e0f13..1ff9a0f 100644 --- a/docs/tasks/T-001.md +++ b/docs/tasks/T-001.md @@ -3,15 +3,21 @@ id: T-001 title: 完成指定摄像头型号准入验证 phase: 0 deps: [] -status: TODO +status: DONE created: 2026-08-03 issue: 1 -context_ref: null -claim_branch: null -work_branch: null +context_ref: 56c07427c86222f6dccaf0574f59cfaba9e3103c +claim_branch: claims/T-001 +work_branch: agent/codex/T-001 write_paths: + - .gitignore - docs/tasks/T-001.md + - docs/tasks/T-006.md - docs/research/camera-compatibility.md + - docs/00-ai-start-here.md + - docs/06-tasks.md + - docs/current-state.md + - docs/quality-document.md --- ## 问题 / 背景 @@ -78,3 +84,14 @@ YoVision 尚未用真实摄像头验证 ONVIF/RTSP 接入。项目负责人决 - 项目负责人确认当前唯一实机为 Hikvision IP Camera，后续本地硬件开发均使用该样机；领取 T-001 后仍须从实物读取并冻结精确型号、硬件版本和固件，不能只记录品牌。 - 多路功能、配额和容量验证允许使用无人物合成 RTSP 源；合成结果不扩展 T-001 的准入范围，也不证明多台真实设备兼容或故障隔离。 + +### 2026-08-05 指定型号准入完成 + +- dispatcher `ila` 将任务分配给 `codex`；`context_ref` 为 `56c07427c86222f6dccaf0574f59cfaba9e3103c`，claim 为 `claims/T-001`，工作分支为 `agent/codex/T-001`。 +- 冻结基线为 HIKVISION `DS-2CD3321FD-IW1-T`、硬件版本 `0x0`、固件 `V5.5.61 build 180929`、编码器 `V7.1 build 180929`；序列号仅保留 SHA-256 前 12 位摘要，不保存原值。 +- ONVIF `GetProfiles`、`GetStreamUri`、`SetSystemDateAndTime` 均返回成功；主/子 Profile 分别映射到脱敏后的 `101`/`102` 通道。设备返回内网 XAddr，公网/NAT 环境必须由接入层重写主机和端口。 +- 错误 RTSP 和 ONVIF 凭据均被拒绝，随后正确凭据立即恢复；未发现错误账号被接受或有效账号锁定。 +- 主、子码流通过 RTSP over TCP 并行持续解码 605 秒：主码流 10,890 帧、子码流 9,076 帧，两路退出码均为 0，警告/错误均为 0。 +- 流测试前后摄像头 UTC 偏差分别为 2.3 秒和 2.8 秒，10 分钟增长 0.5 秒；时间模式、`CST-8:00:00` 时区和夏令时配置在权限测试后保持不变。 +- 项目负责人因不在摄像头现场，明确裁决将“3 次物理网络断开与恢复”按完成处理。本次没有执行真实断网，也没有三次恢复时间线；该项以 `WAIVED` 留痕，不得对外宣称已经实测自动恢复，T-006 的恢复门禁仍须独立执行。 +- 脱敏步骤、结果、限制和准入结论见 `docs/research/camera-compatibility.md`。本任务结论为 `approved`（含上述负责人豁免），仅适用于本文件冻结的单台、单型号、单硬件和单固件基线。 diff --git a/docs/tasks/T-006.md b/docs/tasks/T-006.md index 8e2b465..cabd8d5 100644 --- a/docs/tasks/T-006.md +++ b/docs/tasks/T-006.md @@ -79,3 +79,8 @@ T-003 只用 fake ONVIF 和 MediaMTX 假服务建立无实机骨架，不能证 - 项目负责人确认无预算购买更多摄像头，后续本地开发统一使用现有 1 台 Hikvision IP Camera；精确型号/硬件/固件仍由 T-001 冻结，代码不得写死品牌或私有地址。 - T-006 改为 1 路真实准入样机 + 至少 4 路可独立启停的合成 RTSP 源，验证五路软件闭环；原“五条独立真实上游”现场证据移交 T-007，不再阻塞日常开发或 M1 实验室出口。 - 该变更替代上一节“需要五台真实设备”的约束，但不允许把同一摄像头/同一 RTSP URI 重复拉流冒充多个独立源。 + +### 2026-08-05 前置依赖解除 + +- T-001 已完成指定海康型号准入，T-003 已完成 Sense 无实机骨架；本任务的代码和设备依赖均已满足，可由 dispatcher 将 Gitea Issue #16 从 `status/waiting` 切换为 `status/todo`。 +- T-001 的真实网络断开恢复由项目负责人豁免，没有产生三次原始恢复时间线；本任务不得继承该豁免，仍须按本任务方案独立完成真实摄像头/网络、合成 publisher、Sense 和 MediaMTX 四类恢复验证。