# YoVision

YoVision 是面向居家养老、校园与社区物业等场景的智能视频事件平台。它统一接入 ONVIF/RTSP 摄像头与后续异构传感器，通过推理、规则、事件留证和分级预警形成闭环。

当前处于 M0（摄像头兼容性验证与需求定稿），仓库以需求、架构和已冻结的事件契约为主，生产代码尚未开始。默认交付 16 路，单站点支持按 32/64/128 路横向扩展。

## 开始工作

AI coding agent：先读 [`AGENTS.md`](AGENTS.md)，再进入 [`docs/00-ai-start-here.md`](docs/00-ai-start-here.md)。

当前文档基线验证：

```powershell
./init.ps1
```

或直接运行：

```powershell
python scripts/validate_agent_context.py
python -m unittest discover -s tests -p "test_*.py"
python scripts/validate_harness_governance.py
```

## 目录

- `Sense/`：感知系统（Go），M1 首先开始。
- `Brain/`：推理系统（Python/CUDA），M3 开始。
- `Bell/`：管理与预警系统（Go + Web），M3 最小版、M4 完整版。
- `docs/raw/`：原始需求、方案、三系统职责及事件契约来源。
- `docs/tasks/`：一任务一文件的版本化规格与执行证据；实时状态在 Gitea Issue。
- `_reference/`：本地只读参考源码，不进入 Git、不作为生产依赖。

## Harness 文档

- [`docs/README.md`](docs/README.md)：文档总导航。
- [`docs/00-ai-start-here.md`](docs/00-ai-start-here.md)：AI 开工入口。
- [`docs/01-vision.md`](docs/01-vision.md)：愿景、用户、产品原则与非目标。
- [`docs/02-requirements.md`](docs/02-requirements.md)：MVP 范围、容量约束与验收。
- [`docs/03-tech-stack.md`](docs/03-tech-stack.md)：技术栈和验证矩阵。
- [`docs/04-architecture.md`](docs/04-architecture.md)：Sense/Brain/Bell 边界与数据流。
- [`docs/05-coding-rules.md`](docs/05-coding-rules.md)：编码硬规则。
- [`docs/06-tasks.md`](docs/06-tasks.md)：只读阶段路线图。
- [`docs/07-user-stories.md`](docs/07-user-stories.md)：用户故事和验收场景。
- [`docs/08-interaction-checklist.md`](docs/08-interaction-checklist.md)：UI 交互与证据清单。
- [`docs/api.md`](docs/api.md)：已冻结与待冻结的接口合约。
- [`docs/routes.md`](docs/routes.md)：管理端/App 路由与边界。
- [`docs/current-state.md`](docs/current-state.md)：当前实现快照与 blocker。
- [`docs/agent-context.md`](docs/agent-context.md) / [`docs/agent-context.json`](docs/agent-context.json) / [`docs/agent-context.schema.json`](docs/agent-context.schema.json)：按任务类型路由上下文。
- [`docs/tasks/README.md`](docs/tasks/README.md)：任务文件与 Gitea Issue 映射规则。
- [`docs/gitea-mcp.md`](docs/gitea-mcp.md)：Gitea MCP 本机接入与降级。
- [`docs/gitea-collaboration.md`](docs/gitea-collaboration.md)：Issue/claim/分支/PR 协作协议。
- [`docs/clean-state-checklist.md`](docs/clean-state-checklist.md)：会话收尾清单。
- [`docs/design/README.md`](docs/design/README.md)：HTML 低保真原型约定。
- [`docs/method-map.md`](docs/method-map.md)：失败模式到治理工件的对照。
- [`docs/evaluator-rubric.md`](docs/evaluator-rubric.md)：单次 agent 输出评审表。
- [`docs/quality-document.md`](docs/quality-document.md)：代码库长期健康度记录。

## 任务与 Gitea

Gitea Issue 是任务实时状态权威，`docs/tasks/T-<编号>.md` 是版本化规格与长期证据。任务领取、写路径防撞、分支与 PR 规则见 [`docs/gitea-collaboration.md`](docs/gitea-collaboration.md)。

相关治理工件：

- `scripts/validate_agent_context.py`
- `scripts/setup_gitea_labels.py`
- `scripts/validate_harness_governance.py`
- `scripts/audit_gitea_coordination.py`
- `scripts/test_gitea_claim_race.py`
- `tests/test_governance.py`
- `.gitea/ISSUE_TEMPLATE/task.md`
- `.gitea/PULL_REQUEST_TEMPLATE.md`
- `.gitea/workflows/harness-governance.yml`

Gitea 私有配置只放在本机环境文件中，仓库仅保留 [`gitea.env.example`](gitea.env.example)。

## 事实边界

实现以 harness 摘要文档为入口，以 `docs/raw/` 追溯决策依据；事件字段与语义以 `docs/raw/contracts/` 的冻结契约为准。`docs/其他项目的文档/` 仅作历史参考，不是 YoVision 当前事实。