yovision/docs/tasks/T-017.md

id, title, phase, deps, status, created, issue, context_ref, claim_branch, work_branch, write_paths

id	title	phase	deps	status	created	issue	context_ref	claim_branch	work_branch	write_paths
T-017	建立 Brain 单路匿名区域事件可视化工程原型	3	T-016	TODO	2026-08-11	null	null	null	null	docs/tasks/T-017.md Brain/ docs/design/brain/ docs/00-ai-start-here.md docs/03-tech-stack.md docs/04-architecture.md docs/06-tasks.md docs/07-user-stories.md docs/08-interaction-checklist.md docs/routes.md docs/current-state.md init.ps1 init.sh

问题 / 背景

Sense 已能稳定提供 MediaMTX 路径，Bell 已有不可变事件存储，但 Brain/ 仍是目录占位，客户无法看到“画面 → 匿名检测 → 区域判定 → 事件候选”的直接效果。直接把 silver_pose 合并进来会破坏独立交付边界；未经授权引入 Ultralytics 生产依赖又有商用许可风险。首步需要一个可重复、可替换检测器、不会伪装算法效果的单路工程原型，为后续 Brain→Bell ingress 提供真实生产者。

关联需求与交互（如适用）

• 用户故事：新增 US-014；同时关联 US-005 的区域规则配置目标。
• 交互清单：新增 IX-024；几何编辑遵守 IX-017 的绘制、撤销、清空、键盘等效和待校准语义。
• 相关页面 / 路由：/brain-demo 仅为回环工程演示入口，不属于 Bell 公共业务路由；原型为 docs/design/brain/index.html。

方案

1. 冻结 T-017 工程原型栈：本机已验证的 Python 3.10.11、NumPy 1.26.4、OpenCV 4.9.0.80。OpenCV HOG 人员检测只作为可替换 Detector port 的演示适配器；不冻结 Savant/DeepStream、生产模型或 GPU 容量。
2. 建立单路 frame source、detector、轻量 track、归一化多边形 zone、进入/停留判定和内存事件候选流水线。默认合成回放携带明确的 fixture 标识，保证无摄像头/模型也能重复验收；真实流模式只从仓库外绝对路径文件读取 URL，并优先指向 Sense 管理的 MediaMTX path。
3. 提供仅监听回环地址的本地演示服务：画面、检测框、track、区域、命中状态、推理延迟和最近事件可观察；区域支持鼠标绘制、撤销、清空、保存，以及无需精确点击的归一化坐标表单。页面使用自包含 HTML/CSS/JS，不加载 CDN、字体或第三方脚本。
4. 本地演示 API 不是跨系统契约，不接受平台事件 id，不写数据库、不发送 Alert、不管理录像。T-018 再冻结 Brain→Bell transport、逻辑身份、Bell ULID、持久重试与幂等确认。
5. 单元测试覆盖几何边界、进入/停留只触发一次、track 过期、事件候选不含平台 ID、URL 文件校验、回环绑定、API 输入限制和敏感信息不回显；HTML 契约测试覆盖响应式、键盘、焦点、44px 操作目标、reduced-motion、状态文本和无外链资源。

不可变约束

• 阈值 / 数值边界：单路原型默认处理 2 FPS；区域点使用 [0,1] 归一化坐标，3～32 个顶点；最近事件仅保留 100 项内存环；HTTP body 不超过 64 KiB。任何值不得成为 16/128 路或生产 worker 的硬上限。
• 判定式 / 状态转换：仅 track 中心点从区域外进入区域内时产生一次 zone_entry 候选；持续位于区域内不重复产生；离开后再次进入才可重新产生。fixture 与真实检测结果必须显式区分，HOG 无检测不得伪造框。
• 安全边界：服务只允许回环监听；真实流 URL 只从仓库外绝对路径、单行、受限大小文件读取，响应、日志、页面和异常不得回显 URL/凭据。禁止提交真实视频、截图、模型权重、凭据或客户标识。
• 既有契约：Brain 只产生 source_event_id 和候选事实，平台 evt_ ULID 仍由 Bell 生成；本任务不修改冻结 event v0.1，不把本地 demo API 宣称为 Brain→Bell transport。silver_pose 保持独立仓库且不进入依赖/构建上下文。

验收要点

• 任务相关验证：python -m unittest discover -s Brain/tests -p "test_*.py" -v、python -m compileall -q Brain；启动合成模式后用回环 HTTP smoke 验证状态、画面、区域保存和事件候选；HTML 静态契约测试通过。
• 完整门禁：因首次建立 Brain 脚手架并更新标准入口，运行 ./init.ps1、三条 Python 治理命令以及 git diff --check；Sense/Bell 既有 test/vet/build 仍须由标准入口通过。
• 人工 / 设备验收：真实摄像头和目标 GPU 不作为本任务 DONE 门禁；合成回放验证工程闭环。真实流只做可选本机 smoke，结果不能外推为算法效果、GPU 容量或生产 SLA。UI 产品确认留给 Bell 业务闭环任务，工程演示页必须明确“非生产模型验收”。
• 构建产物：源码运行原型，无独立安装包；入口为 python -m Brain.yovision_brain --source synthetic，依赖清单和启动说明写入 Brain/README.md。

边界（不改什么）

• 不实现 Brain→Bell 网络投递、持久 Outbox、Bell ingress、规则/Alert/ack、证据切片、对象存储、反馈回流或公共认证。
• 不承诺检测召回率/误报率，不购买或引入 Ultralytics 生产许可，不冻结 Savant/DeepStream、CUDA、跟踪/ReID 或每 worker 路数。
• 不修改 Sense、Bell、_reference/ 或 D:\OPC\silver_pose；不直接连接摄像头管理端或绕过 MediaMTX 系统边界。

协作约束

• 责任 Agent：codex
• 唯一写入者：codex
• 委派：不启用。
• Gitea：Issue、context_ref、claim 与工作分支在双向映射及 dispatcher 分配后回填。

任何新增写路径先检查与其他活跃任务是否重叠；同一时刻只有一个 Agent 修改本任务的 write_paths。

执行记录

• 2026-08-11：按用户指定顺序建立 T-017；实现尚未开始。主分支 ./init.ps1 基线通过（68 项根测试，Sense/Bell test/vet/build 通过）。