# YoVision

YoVision 是一个单仓多项目的智能视频事件平台，包含三个可独立开发和交付的子项目：

- `Sense/`：设备、ONVIF/RTSP、MediaMTX、实时监看和边缘运维；
- `Brain/`：解码、推理、跟踪、区域判定和标准事件生成；
- `Bell/`：事件接入、规则、Alert、ack/close、升级和通知。

Sense 与 Bell 是账户、数据、部署和发布边界完全独立的两个销售产品；Brain 是无界面的独立推理交付单元，默认随 Sense 部署。跨项目协作只通过 `contracts/` 中的版本化契约。

开始工作前阅读 [AGENTS.md](AGENTS.md) 和 [文档中心](docs/README.md)。本仓库采用 DevHarness：Gitea 工单是单次任务唯一事实来源，Gitea Wiki 保存长期文档，`docs/` 默认保存核心 Wiki 的只读镜像。

## 工作闭环

```text
讨论需求或缺陷
  -> 阅读代码并提出方案
  -> 人工确认方案
  -> 创建 Epic / MVP / 单元任务工单
  -> Agent 实现并测试
  -> 提交代码并集中回写工单证据
  -> 人工验收后记录结论并关闭工单
  -> 长期事实变化时才同步 Wiki
```

默认不创建任务归档；`docs/task/` 只保存人工明确要求的专项或历史兼容快照。

## 首次初始化顺序

1. 创建 Gitea 远端仓库并推送当前引导提交，启用工单和 Wiki。
2. 配置 `wiki-docs.json` 和安全访问方式；优先使用已配置的 Gitea MCP，MCP 不可用时才使用 Gitea API并记录原因。
3. 查询线上 Wiki；`Home` 不存在时先创建并回读 `Home`，取得 revision 后再创建其他核心页面。
4. 本地 `docs/` 的存在不能证明线上 Wiki 已初始化。
5. 开始产品编码前运行：

   ```powershell
   python dev_scripts/harness.py sync --verify
   ```

YoVision 已完成远端与 Wiki 初始化，上述步骤用于维护者理解门禁和以后建立新仓库。

## 常用命令

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

只有明确要求时才运行 `python dev_scripts/harness.py archive <编号> "<标题>"`、`export` 或 `export --all`。

## 分支模型

- `explore`：2026-08-14 前实现的只读聚合快照，用于迁移对照和回退。
- `main`：用户审核通过的基线，禁止直接开发。
- `dev`：集成开发与测试分支；任务分支从 `dev` 创建并通过 PR 返回 `dev`。
- 只有用户明确审核通过，才能将 `dev` 合入 `main`。

Sense 与 Bell 的新实现必须从根 `goadmin-baseline.json` 冻结的 go-admin 和 go-admin-ui 完整提交派生，开发时必须核对对应 commit 的 go-admin-doc。仅参考 GoAdmin 的技术栈、布局或视觉不属于本项目认可的二次开发。

## Harness 目录

```text
AGENTS.md                         Agent 通用规则与 YoVision 专用门禁
CLAUDE.md                         Claude Code 入口和三项目角色路由
.gitea/issue_template/            Epic、MVP、单元任务模板
docs/                             核心 Wiki 只读镜像及可选历史快照
wiki-docs.json                    核心 Wiki 页面显式映射
dev_scripts/harness.py            check / sync / archive / export 单一入口
dev_scripts/wiki_docs.py          Gitea Wiki 客户端与镜像生成库
```