# AI 开发入口

> YoVision 的固定开工入口。硬性编码规则见 [`05-coding-rules.md`](05-coding-rules.md)。

## 一句话定位

YoVision 将 IP 摄像头和后续异构传感器统一接入，通过推理、规则、事件留证与 ack 升级链，把“看到异常”变成“有人确认处理”的闭环。

MVP 以默认 16 路跑通一个场景的端到端闭环；架构、数据和 UI 从第一版兼容单站点 128 路横向扩展，但不承诺一台服务器或一块 GPU 承载 128 路。

## 每轮开工

1. 确认位于仓库根目录并读取 [`../AGENTS.md`](../AGENTS.md)。
2. 读取 [`agent-context.json`](agent-context.json)、[`05-coding-rules.md`](05-coding-rules.md) 和 [`current-state.md`](current-state.md)。
3. 从 Gitea 读取当前分配的 Issue，并读取其映射的 `docs/tasks/T-<编号>.md`。
4. 记录默认分支头为 `context_ref`，按任务类型读取 `agent-context.json.routes`。
5. 查看 `git log --oneline -5` 与 `git status --short`，确认最近变更和工作区归属。
6. 运行 `./init.ps1`；非 Windows 环境运行 `./init.sh`。
7. 基线失败时先记录并修复基线，不在坏的起点上叠功能。
8. 仅在 Issue、任务文件、claim/工作分支和 `write_paths` 全部一致后开始修改。

没有已分配 Issue 时，不自行领取。由 dispatcher 按 [`gitea-collaboration.md`](gitea-collaboration.md) 串行检查依赖和写路径后分配。

## 首次完整上下文

首次接入、上下文清单缺失或校验失败时，依次完整读取：

1. [`01-vision.md`](01-vision.md)
2. [`02-requirements.md`](02-requirements.md)
3. [`03-tech-stack.md`](03-tech-stack.md)
4. [`04-architecture.md`](04-architecture.md)
5. [`05-coding-rules.md`](05-coding-rules.md)
6. [`06-tasks.md`](06-tasks.md)
7. [`tasks/README.md`](tasks/README.md)
8. [`current-state.md`](current-state.md)

涉及 UI 时再读 [`07-user-stories.md`](07-user-stories.md)、[`08-interaction-checklist.md`](08-interaction-checklist.md)、[`routes.md`](routes.md) 和关联的 `docs/design/` 原型。

需要追溯“为什么这样决定”时读取 `docs/raw/` 对应章节；不要把历史参考项目当作当前事实。

## 当前阶段

当前为 **M0 指定型号实机准入待执行，M1 Sense 无实机骨架已建立**。后续本地开发统一使用现有一台海康样机，多路软件闭环使用独立合成 RTSP 源补足；真实多设备证据延后到客户/借用/租赁条件具备时执行。

优先路径：

1. M0：一台真实样机完成首期指定“型号 + 硬件版本 + 固件”ONVIF/RTSP 准入；结论不外推为多品牌兼容。
2. M1：只在 `Sense/` 建立 MediaMTX 生产接入骨架，以 1 路准入实机 + 至少 4 路独立合成源完成五路自动建 path、探活和断线重建。
3. M2：对账、多租户、隧道和至少一个站点的 16 路全流程。
4. M3：Brain + Bell 起步，默认 16 路端到端事件、预警、ack 与误报反馈。
5. M4–M5：64/128 路分片、管理端和第二/第三场景包。

## 任务领取与状态

- Gitea Issue 是实时状态权威，状态标签为 `status/waiting`、`status/todo`、`status/doing`、`status/blocked`、`status/review`、`status/done`；`waiting` 表示尚未领取且因依赖或外部条件不可领取。
- 任务文件保存不可变规格、依赖、写路径、验证门禁和执行证据。
- 一个 agent 同时最多一个活跃任务；一个任务同时只有一个写入者。
- dispatcher 创建 `claims/T-<编号>` 和 `agent/<agent-id>/T-<编号>` 后，worker 必须读回确认。
- 任务完成前在任务文件记录实际命令和结果；PR 合并后再关闭 Issue。
- Gitea 断连时可继续已确认归属的本地工作，不可领取、释放或抢占任务。

完整协议见 [`gitea-collaboration.md`](gitea-collaboration.md)。

## 硬边界

- `site.max_video_channels` 默认 16、上限 128；不得把 16 写成业务上限。
- 128 路靠媒体分片和推理 worker 横向扩展，容量必须分别验收带宽、解码、推理和证据存储。
- M0 的 MiBeeNvr 仅为隔离实验室测试台；M1 生产数据面必须使用 MediaMTX，不把完整 MiBeeNvr 当生产基线。
- 事件与预警是独立实体；Brain 产出事件，Bell 校验、存储并派发预警。
- 人脸识别默认关闭且按租户授权；不可用或未命中时必须降级，不能漏报。
- 事件契约 v0.1 已冻结，字段变更必须走版本升级，不得私加字段。
- `_reference/` 只读且不入 Git；禁止提交真实视频、人脸、凭据或客户数据。

## 任务类型路由

- Sense/设备/媒体：`02-requirements.md` → `03-tech-stack.md` → `04-architecture.md` → `api.md`。
- Brain/推理/契约：上述文档 + `raw/07-事件契约比对-silver_pose.md` + `raw/contracts/`。
- Bell/规则/预警/租户：`02-requirements.md` → `04-architecture.md` → `api.md` → 用户故事和交互清单。
- UI：需求 → 用户故事 → 交互清单 → routes → architecture → 关联原型。
- Gitea/任务治理：`tasks/README.md` → `gitea-collaboration.md` → `clean-state-checklist.md`。

## 当前验证入口

```powershell
python scripts/validate_agent_context.py
python -m unittest discover -s tests -p "test_*.py"
python scripts/validate_harness_governance.py
go -C Sense generate ./internal/mtx
go -C Sense test ./...
go -C Sense vet ./...
go -C Sense build ./...
```

日常优先运行根目录 `./init.ps1` 或 `./init.sh`，它会执行上述治理、生成、测试、静态检查和构建门禁。Sense 本地启动为 `go -C Sense run ./cmd/sense-api`；默认只监听回环地址，具体配置、MediaMTX 版本与校验方法见 [`03-tech-stack.md`](03-tech-stack.md) 和 [`../Sense/README.md`](../Sense/README.md)。