94 lines
5.6 KiB
Markdown
94 lines
5.6 KiB
Markdown
# AGENTS.md
|
||
|
||
> YoVision 的仓库级 AI coding agent 入口。进入仓库后先读本文，再读 [`docs/00-ai-start-here.md`](docs/00-ai-start-here.md)。
|
||
|
||
## 项目定位
|
||
|
||
YoVision 是智能视频事件平台：统一接入 ONVIF/RTSP 摄像头与后续异构传感器，完成检测、规则判定、事件留证和分级预警。
|
||
|
||
当前已完成 M0、M1 和 M2 的本地基线，进入 **M3：Bell/Brain 最小事件闭环**。默认交付 16 路，单站点按 32/64/128 路横向扩展；16 只能是默认配额，不能成为代码、数据库、数组、分页或批量操作的硬上限。
|
||
|
||
## 固定阅读顺序
|
||
|
||
1. [`docs/agent-context.json`](docs/agent-context.json)：按任务类型选择最小上下文。
|
||
2. [`docs/00-ai-start-here.md`](docs/00-ai-start-here.md)：开工、领取、验证与收尾流程。
|
||
3. [`docs/05-coding-rules.md`](docs/05-coding-rules.md)：不可绕过的编码和验证规则。
|
||
4. [`docs/current-state.md`](docs/current-state.md)：当前仓库现实、可运行命令与 blocker。
|
||
5. 当前 Gitea Issue 与其对应的 `docs/tasks/T-<编号>.md`。
|
||
6. 按 `agent-context.json.routes` 读取本轮需要的需求、架构、API 或 UI 文档。
|
||
|
||
首次接入或清单失效时，再完整读取 `docs/01-vision.md` 至 `docs/06-tasks.md`。原始决策依据保留在 [`docs/raw/`](docs/raw/)；不要用 `docs/其他项目的文档/` 推断 YoVision 当前事实。
|
||
|
||
## 事实与权威来源
|
||
|
||
- 产品范围和实现约束：`docs/01-vision.md`、`docs/02-requirements.md`。
|
||
- 技术选型和架构边界：`docs/03-tech-stack.md`、`docs/04-architecture.md`。
|
||
- 事件字段与语义：`docs/raw/contracts/event-v0.1.schema.json` 和 `docs/raw/contracts/README.md`，二者为已冻结契约。
|
||
- 实时任务状态：Gitea Issue；版本化规格与长期证据：`docs/tasks/T-<编号>.md`。
|
||
- 当前代码现实：代码、测试结果与 `docs/current-state.md`。
|
||
|
||
若摘要文档与 `docs/raw/` 冲突，先停止实现并修正文档，不得静默任选其一。需求或架构决策变化时，同步更新摘要层、相关原始决策文档和任务验收。
|
||
|
||
## 三系统边界
|
||
|
||
- `Sense/`（Go）：设备、ONVIF、MediaMTX 控制、对账、探活、隧道、设备型触发源。
|
||
- `Brain/`（Python/CUDA）：解码与推理流水线、检测/姿态/跟踪/ReID、判定内核、事件 mapper；业务上无状态。
|
||
- `Bell/`（Go + Web）：事件校验与存储、规则、预警/ack/升级、投递、多租户/RBAC、审计和管理端。
|
||
- MediaMTX 是独立二进制，由 Sense 管理配置与生命周期；不把媒体内核写进任一业务系统。
|
||
- `_reference/` 是只读参考区。MiBeeNvr 只可用于 M0 隔离实验室和白名单能力借鉴，不得整仓复制、加入生产依赖或替代 M1 的 MediaMTX 数据面。
|
||
|
||
详细职责以 [`docs/04-architecture.md`](docs/04-architecture.md) 和 [`docs/raw/08-三系统职责划分.md`](docs/raw/08-三系统职责划分.md) 为准。
|
||
|
||
## Gitea 工单流程
|
||
|
||
项目已启用 Gitea，dispatcher 登录名为 `ila`。遵循 [`docs/gitea-collaboration.md`](docs/gitea-collaboration.md)：
|
||
|
||
- 一个任务对应一个任务文件、一个主 Issue、一个工作分支和一个 PR。
|
||
- Issue 是 TODO/DOING/BLOCKED/REVIEW/DONE 的实时状态权威；任务文件保存规格、依赖、`write_paths` 和可审计证据。
|
||
- 每个 agent 同时最多一个活跃任务。领取前由 dispatcher 串行检查依赖和活跃任务写路径。
|
||
- 工作分支使用 `agent/<agent-id>/T-<编号>`；claim 标记使用 `claims/T-<编号>`。
|
||
- 同一路径或父子目录视为冲突。发现需要修改 `write_paths` 外的文件时先停下，由 dispatcher 复查并更新 Issue 与任务文件。
|
||
- PR 合并且默认分支任务文件为 `DONE` 后，Issue 才能关闭。
|
||
|
||
Gitea 不可用时，只能继续已经确认属于自己的任务；不得领取新任务或猜测远端状态。
|
||
|
||
## 工作规则
|
||
|
||
- 当前任务范围以 Issue 和任务文件为准；一次只完成一个任务，不夹带后续功能。
|
||
- 复杂任务先把方案、不可变约束、写路径和验证门禁写入任务文件，再编码。
|
||
- 默认单任务、单责任 agent、单写入者。任务内委派默认关闭；只有用户或项目规则明确允许时才启用。
|
||
- M0 可直接运行 MiBeeNvr 做实验，但不改 `_reference/`；M1 生产骨架只动 `Sense/`。
|
||
- 新依赖和版本必须先写进 `docs/03-tech-stack.md`。未定的前端框架、消息总线和硬件型号不得由 agent 自行拍板。
|
||
- 不提交 token、密码、摄像头凭据、客户信息、真实人脸/视频或私有 Gitea 配置。
|
||
|
||
## 代码发现
|
||
|
||
<!-- codebase-memory-mcp:start -->
|
||
本项目使用 codebase-memory-mcp 维护代码知识图谱。代码发现优先级：
|
||
|
||
1. `search_graph`
|
||
2. `trace_path`
|
||
3. `get_code_snippet`
|
||
4. `query_graph`
|
||
5. `get_architecture`
|
||
|
||
仅在搜索字符串、配置、非代码文件，或图工具结果不足时使用 `rg`。图工具不可用时如实说明并降级，不阻塞正常工作。
|
||
<!-- codebase-memory-mcp:end -->
|
||
|
||
## 验证与提交
|
||
|
||
文档治理基线：
|
||
|
||
```powershell
|
||
python scripts/validate_agent_context.py
|
||
python -m unittest discover -s tests -p "test_*.py"
|
||
python scripts/validate_harness_governance.py
|
||
go -C Bell test ./...
|
||
go -C Bell vet ./...
|
||
go -C Bell build ./...
|
||
```
|
||
|
||
代码出现后，还必须执行 `docs/03-tech-stack.md` 中与本任务命中的模块测试；完整门禁、设备验收和容量验收按任务文件触发。提交前检查 `git status --short`、`git diff`、`git diff --cached` 与 `git diff --check`。
|
||
|
||
默认分支为 `main`。每次只提交当前任务相关文件；推送到已配置的 `origin`，不要在文档或日志中写入凭据。
|