<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Project-Profile
wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Project-Profile.-
wiki_revision: 3ec1fe54504a9c5eabb76dc19f0e46eb6c58ba08
synchronized_at: 2026-08-29T12:37:08Z
<!-- gitea-wiki-mirror:end -->

# 项目档案

## 基本信息

| 项目 | 内容 |
|---|---|
| 名称 | YoVision |
| 仓库 | `ila/yovision` |
| 默认分支 | `main` |
| 一句话目标 | 将现有视频设备升级为能够自动形成异常证据并把预警追到人确认处置的安全基础设施 |
| 首期客户场景 | 民办寄宿学校，默认 16 路高风险点位 |
| 首期规则 | 越线、危险区域、聚集等匿名安全规则；不启用人脸 |
| 产品形态 | Sense 与 Bell 两个独立销售产品，Brain 为独立推理交付单元 |
| 当前阶段 | MVP #8 三项目首个独立纵切已于 2026-08-29 通过用户验收并合入 `dev`：Sense 完成摄像头接入到区域配置，Brain 完成合成输入到匿名本地事件，Bell 完成合成事件到 Alert ack/close；旧实现归档于 `explore`，`main` 仍为审核基线 |
| 历史来源 | `D:\OPC\yovision_old`，只读追溯 |

## DevHarness 来源与基线

| 项目 | 内容 |
|---|---|
| 上游仓库 | `https://git.ilapage.cn/OPC/dev_harness` |
| 本次升级前基线 | `f23c2cf81f9792495f696d49e88d79b16cf29810` |
| 当前目标基线 | `4bbacf4d7fb265984396bb5589c544105043fa0b` |
| 升级日期 | 2026-08-27 |
| 识别方式 | 初始导入文件 blob 与上游历史逐项对照；完整 commit 是基线标识 |

YoVision 采用 DevHarness 的共同工作流、统一 `harness.py` 命令、Gitea 工单/Wiki 事实源边界和模板；项目适配保留三项目并行与写路径所有权、`explore/main/dev` 分支治理、Sense/Bell GoAdmin 固定基线、UI 精简复用门禁和现有产品文档结构。升级不得整页覆盖项目事实，也不得复制 DevHarness 自身任务状态。

## 子项目与交付单元

| 单元 | 职责 | 技术栈目标 | 独立构建/测试/发布 | 规则入口 | 共享边界 |
|---|---|---|---|---|---|
| Sense | ONVIF/RTSP、设备台账、MediaMTX、实时监看、区域配置、运维与 Outbox | Go；Vue 3 + Element Plus；PostgreSQL | 是；可在没有 Bell 时独立运行 | `Sense/AGENTS.md` | 通过版本化源/事件/证据契约与 Brain、Bell 集成 |
| Brain | 解码、检测、姿态、跟踪、ReID、区域判定、事件 mapper | Python/CUDA | 是；无界面，默认随 Sense 交付 | `Brain/AGENTS.md` | 只消费媒体/配置契约并输出标准事件 |
| Bell | 外部事件接入、规则、Alert、ack/close、联系人、排班、升级、通知、审计 | Go；Vue 3 + Element Plus；PostgreSQL | 是；可用合成或第三方事件独立验收 | `Bell/AGENTS.md` | 发布事件接入与证据接口，不读取 Sense 内部状态 |
| contracts | 三端共享的 OpenAPI、JSON Schema、SQL 契约和兼容说明 | 版本化文档与契约测试 | 随受影响项目验证 | `contracts/AGENTS.md` | 唯一共享事实来源，不承载业务代码 |

三个项目允许不同版本和发布节奏。技术栈不同不是拆仓理由；若未来团队权限、发布责任或仓库性能长期分离，再以独立工单评估拆仓。

## 技术栈与运行环境

- Sense/Bell：目标采用固定上游版本的 GoAdmin server 与 go-admin-ui，首阶段保持 Vue 3 + Element Plus + Vue CLI，不同时迁移 TypeScript/Vite。
- Brain：Python、CUDA/NVIDIA 主路径；模型许可必须在商用前确认。
- 正式数据库：PostgreSQL；Sense 与 Bell 使用独立数据库角色和数据边界。
- 媒体：MediaMTX 独立二进制，由 Sense 管理配置和生命周期。
- 证据：客户侧 MinIO/S3 兼容对象存储；常态录像优先留在客户已有 NVR。
- 首期验证平台：NVIDIA x86/Jetson；M1-M3 不承诺 GB/T 28181、信创或原生 App。

2026-08-14 起，原 Sense、Bell 实现只在 `explore` 和原功能分支中作为迁移参考，不再作为新开发基础。当前 `dev` 中的 Sense、Bell 已分别从下述冻结 go-admin/go-admin-ui 完整提交派生；实施时仍必须核对冻结 go-admin-doc。Brain 已在独立 Python/PyTorch 包骨架上完成合成/本地输入、解码、匿名检测与单路跟踪、区域/方向越线判定和项目内匿名事件输出；真实 GPU、生产模型和跨项目契约仍属后续范围。

## 阅读入口

- 新维护者：Home → Product-Requirements → Architecture-and-Code-Map。
- Sense agent：根 `AGENTS.md` → `Sense/AGENTS.md` → 当前工单。
- Brain agent：根 `AGENTS.md` → `Brain/AGENTS.md` → 事件契约 → 当前工单。
- Bell agent：根 `AGENTS.md` → `Bell/AGENTS.md` → 当前工单。
- 协调 agent：Multi-Agent-Collaboration → `contracts/AGENTS.md` → 所有受影响工单。

## 常用命令

仓库级检查可执行：

```powershell
python dev_scripts/harness.py check --strict
python -m unittest discover -s tests -v
python dev_scripts/harness.py sync --check
git diff --check
```

Sense、Brain、Bell 的当前构建、运行和测试命令已分别记录在各自 README 与 `Local-Development-and-Verification`；不得以旧仓库命令替代。

## 环境、配置与凭据

- Gitea 凭据仅通过 MCP 安全配置或进程环境提供。
- 摄像头密码、JWT secret、数据库连接、对象存储和通知供应商凭据不得提交。
- Sense 与 Bell 必须使用不同用户库、JWT/会话密钥、Cookie、Casbin 策略和数据库角色。
- Brain 不接收交互式用户会话；机器身份按调用方和实例独立分配。
- `.env.example` 只能放变量名和无敏感示例，不放真实地址、客户名或 token。

## 负责人确认的边界

- 单仓包含 Sense、Brain、Bell 三个开发项目。
- 计划由三名主 agent 尽量并行处理各自独立工单；需要跨项目协作时再建立协调工单并启用新 agent。
- 旧仓库在新纵切验收前保留，不删除、不覆盖。

## Sense/Bell GoAdmin 固定技术基线

Sense、Bell 共用的可复现技术基线记录在仓库根 `goadmin-baseline.json`。正式版本标识是上游 URL 与完整 commit 的组合；本机目录、分支名、最近 tag 和 `package.json` version 只作辅助信息。

| 参考源 | 用途 | 冻结提交 | 描述版本 | 本机只读位置 |
|---|---|---|---|---|
| go-admin | 后端骨架 | `f06540883b41d03782bb6b2c4150f298f328c6b6` | `v2.2.0-25-gf065408` | `D:\github\goadmin\go-admin` |
| go-admin-ui | 前端骨架 | `67d393d713877572fab0b897296a4c1d525fc81d` | `v2.0.9-170-g67d393d` | `D:\github\goadmin\go-admin-ui` |
| go-admin-doc | 只读用法参考 | `424855aacf6905f3fde860c3331385cb25529a0d` | 无精确 tag | `D:\github\goadmin\go-admin-doc` |

固定工具链为 Go 1.26.5、Node.js 22.22.1、pnpm 9.15.1。go-admin-ui 的 `package.json` version 仍为 2.0.9，但冻结提交位于 `v2.0.9` 后 170 个提交，因此不得只用“2.0.9”代表当前基线。

三个上游仓库均使用 MIT 许可证。派生代码必须保留许可证和版权声明。Sense、Bell 使用同一上游基线，但分别维护代码、配置、构建、测试、版本和发布。任何上游或工具链升级必须建立影响 Sense/Bell 的协同工单。

<!-- sense-runtime:start -->
## Sense 重建状态

Sense 已从冻结 go-admin/go-admin-ui 源码独立派生，并完成设备、视频接入、MediaMTX、单路监看、区域配置与 Windows 交付的独立纵切。工单 #71 已从当前源码重新打包并通过隔离 PostgreSQL 17、Digest ONVIF/合成 RTSP、独立 MediaMTX、Chrome 外壳和冷启动回归；#145 又修复默认验收入口的受控源码复制、UDP 端口探测、临时清理和脱敏诊断。当前成果已合入 `dev`，并随 MVP #8 于 2026-08-29 通过三项目独立纵切验收。现场真机、16 路长稳和跨项目链路不在本轮结论内。
<!-- sense-runtime:end -->


<!-- bell-runtime:start -->
## Bell 重建状态

Bell 已从与 Sense 相同的冻结 go-admin/go-admin-ui 基线独立派生到 `Bell/server/` 与 `Bell/ui/`，保留来源和 MIT 许可证证据，以及独立 PostgreSQL、JWT、token key 和首次管理员边界。#131–#134 已完成 Event/Receipt、合成事件、规则匹配、Alert ack/close、审计时间线、Windows 交付和独立 E2E；生产验证码、最小菜单和 GoAdmin 外壳缺陷也已闭环。当前成果已合入 `dev`，并随 MVP #8 于 2026-08-29 通过三项目独立纵切验收。
<!-- bell-runtime:end -->

<!-- brain-runtime:start -->
## Brain 初始化状态

Brain 已在 CPython 3.11.15 / PyTorch 2.12.1 无界面包骨架上完成合成与本地视频输入、可替换解码、匿名检测与单路跟踪、危险区域与方向越线判定，以及项目内匿名事件输出。独立验收中 43 项测试通过，CLI 合成输入实际生成 `brain.internal.event-candidate/v1` 匿名事件；当前成果已合入 `dev`，并随 MVP #8 于 2026-08-29 通过用户验收。CUDA wheel、真实 GPU、生产模型、容量和跨项目事件契约仍未验证。
<!-- brain-runtime:end -->

## 分支治理

- `explore`：2026-08-14 前实现的只读聚合快照；不接受新功能。
- `main`：用户审核通过的最小/发布基线；禁止直接开发和未经用户明确审核的合并。
- `dev`：集成开发与测试分支；功能分支从 `dev` 派生，并通过 PR 合回 `dev`。
- 只有用户明确审核通过，才能把 `dev` 合入 `main`。

<!-- sense-root-launcher:start -->
## Sense Windows 项目目录启动入口

工单 #90 在 `Sense/start_sense.bat` 提供项目目录快捷入口。它只使用脚本自身路径定位 `Sense/dist/sense-windows-amd64/start-sense.bat`，透传 production、demo 和其他包内启动参数，并保留包内脚本退出码；不读取配置、不自动构建，也不直接启动 Go 或 Node 开发服务。

使用前必须先按 Windows 交付流程生成 `Sense/dist/sense-windows-amd64`。从仓库根目录可运行 `Sense\start_sense.bat`，进入 Sense 目录后可运行 `start_sense.bat` 或 `start_sense.bat demo`。交付包不存在时脚本返回非零并提示执行 `Sense\scripts\build\build-windows.bat`。
<!-- sense-root-launcher:end -->