yovision/docs/tasks/T-017.md

---
id: T-017
title: 建立 Brain 单路匿名区域事件可视化工程原型
phase: 3
deps: [T-016]
status: DONE
created: 2026-08-11
issue: 59
context_ref: 2e047379228a30841da7ceed8cfb86275b3c330e
claim_branch: claims/T-017
work_branch: agent/codex/T-017
write_paths:
  - 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 通过）。
- 2026-08-11：建立 `FrameSource → Detector → Tracker → ZoneEntryEvaluator → EventCandidate` 单路流水线。默认合成 fixture 可重复运行；可选真实流只从仓库外绝对路径文件读取 RTSP(S) URL，OpenCV HOG 仅作为非生产演示 detector port。区域进入只在 `outside → inside` 时触发，候选不含 Bell 平台 `id`。
- 2026-08-11：实现只允许显式回环地址的工程服务和自包含 `/brain-demo` 页面；HTTP body 上限 64 KiB，区域写入使用进程级临时 token，响应带 CSP、拒绝 framing、禁止缓存且不记录请求路径。桌面截图已目检；Edge CDP 在 375×900 设备视口实测 `innerWidth=clientWidth=scrollWidth=375`，可见按钮最小高度 44 px，移动端工具栏单列且无横向溢出。截图仅在系统临时目录用于 QA，未提交。
- 2026-08-11：独立 CLI 合成模式回环 smoke 通过：`health/state/frame/page/zone PUT` 均为 HTTP 200，source 为 `synthetic`、`fixture=true`、JPEG 可读、区域版本由 v1 递增至 v2。使用标准入口 `./init.ps1` 通过 68 项根测试、19 项 Brain 测试、Brain compileall，以及 Sense/Bell generate/test/vet/build；`git diff --check` 通过。
- 边界：未连接真实摄像头或目标 GPU，未引入生产模型、Brain→Bell transport、持久 Outbox、规则/Alert 或客户产品 UI；这些结果只关闭匿名单路工程原型，不构成算法效果、真实多路或生产 SLA 验收。