yovision/AGENTS.md

AGENTS.md

YoVision 的仓库级 AI coding agent 入口。进入仓库后先读本文，再读 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：按任务类型选择最小上下文。
2. docs/00-ai-start-here.md：开工、领取、验证与收尾流程。
3. docs/05-coding-rules.md：不可绕过的编码和验证规则。
4. 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/其他项目的文档/ 推断 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/raw/08-三系统职责划分.md 为准。

Gitea 工单流程

项目已启用 Gitea，dispatcher 登录名为 ila。遵循 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 维护代码知识图谱。代码发现优先级：

1. search_graph
2. trace_path
3. get_code_snippet
4. query_graph
5. get_architecture

仅在搜索字符串、配置、非代码文件，或图工具结果不足时使用 rg。图工具不可用时如实说明并降级，不阻塞正常工作。

验证与提交

文档治理基线：

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，不要在文档或日志中写入凭据。