102 lines
7.3 KiB
Markdown
102 lines
7.3 KiB
Markdown
# 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 五路混合源集成和 M2 本地 16 路软件基线均已完成，M3 已建立 Bell 不可变事件存储、Sense→Bell 全局审计 relay、Brain 单路可视化工程原型、Sense 回环 NVR 管理面纵切、Brain→Bell 可靠事件 ingress 和 Bell 规则→Alert→ack/close 回环工程纵切**。后续本地开发统一使用已准入的一台海康样机，多路软件闭环使用独立合成 RTSP 源补足；真实多设备证据延后到客户/借用/租赁条件具备时执行。客户网络尚未提供，T-013 WireGuard 继续后置；下一项建议独立建立 Bell→Sense 异步证据/pre-roll 切片。
|
||
|
||
优先路径：
|
||
|
||
1. M0：已用一台真实样机完成首期指定“型号 + 硬件版本 + 固件”ONVIF/RTSP 准入；结论不外推为多品牌兼容，真实断网恢复证据按负责人豁免留痕。
|
||
2. M1：只在 `Sense/` 建立 MediaMTX 生产接入骨架，以 1 路准入实机 + 至少 4 路独立合成源完成五路自动建 path、探活和断线重建。
|
||
3. M2：Control API、多租户投影、调和 fencing、孤儿安全闸和本地 16 路批量收敛/30 分钟稳定基线已完成；WireGuard 等客户网络条件具备后补验。
|
||
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 ./internal/controlapi
|
||
go -C Sense test ./...
|
||
go -C Sense vet ./...
|
||
go -C Sense build ./...
|
||
go -C Bell test ./...
|
||
go -C Bell vet ./...
|
||
go -C Bell build ./...
|
||
python -m unittest discover -s Brain/tests -p "test_*.py" -v
|
||
python -m compileall -q Brain
|
||
```
|
||
|
||
日常优先运行根目录 `./init.ps1` 或 `./init.sh`，它会执行上述治理、Brain 单元/编译、生成、测试、静态检查和构建门禁。Sense 本地启动为 `go -C Sense run ./cmd/sense-api`；T-018 控制台必须在完成 PostgreSQL/Control API 外部安全配置后显式设置 `SENSE_CONSOLE_ENABLED=true`，再访问回环 `/sense-console/`。Brain 合成工程原型启动为 `python -m Brain.yovision_brain --source synthetic`。T-020 在 Bell migration/外部规则与 token 上下文就绪后显式开启 `BELL_ALERTS_ENABLED=true` 与 `BELL_ALERT_CONSOLE_ENABLED=true`，访问 `/bell-console/`；完整变量见 [`../Bell/README.md`](../Bell/README.md)。工程页面默认只允许回环，具体配置、版本与校验方法见 [`03-tech-stack.md`](03-tech-stack.md)、[`../Sense/README.md`](../Sense/README.md)、[`../Brain/README.md`](../Brain/README.md) 和 [`../Bell/README.md`](../Bell/README.md)。
|
||
|
||
本机 16 路软件容量基线使用 `./Sense/scripts/t014-capacity.ps1 -PgRoot D:\pgsql17`；正式证据必须使用默认 30 分钟窗口，且只证明固定低码率合成负载。结果与限制见 [`research/sense-16-stream-capacity.md`](research/sense-16-stream-capacity.md)。
|