yovision/docs/05-coding-rules.md

编码规则

0. 黄金法则

1. 不臆造字段、接口、设备行为、依赖或容量数据；不确定就查证或标记待定。
2. 只做当前 Gitea Issue 与任务文件范围，不顺手实现后续里程碑。
3. 遵守 Sense/Brain/Bell 边界和 M0–M6 开发顺序。
4. 先写可观察验收，再做最小改动；每次交付可构建、可测试、可恢复。
5. 真实验证证据写进任务文件，不用 agent 自报或聊天记录代替。

1. 动手前

• 读 Issue、任务文件和 write_paths，确认 claim/工作分支属于自己。
• 按 agent-context.json 读取需求、技术栈、架构与合约。
• 代码发现优先使用仓库规则指定的知识图谱工具；不可用时再用 rg。
• 复杂任务先在任务文件写明方案、不可变约束、任务相关/完整/人工三层门禁。
• 新依赖、版本、公共接口、schema 或路由必须先更新对应文档。
• 基线失败先处理基线或标记 blocker，不叠加功能。

2. 项目硬约束

• 16 只能是默认配额；所有容量逻辑支持配置到 128，禁止魔法数字控制业务上限。
• 128 路通过 MediaMTX 与推理 worker 分片，不把负载堆在单进程/单 GPU。
• M1 生产媒体面使用 MediaMTX；MiBeeNvr 仅限 M0 隔离实验和白名单借鉴。
• _reference/ 只读，不提交、不修改、不加入 go.mod/镜像/构建上下文。
• Event 与 Alert 分离；平台 ULID 由 Bell 生成。
• Brain 不拥有设备或告警业务状态；Sense 不写 Bell schema；Bell 不直接操作模型和媒体内核。
• 人脸默认关闭、按租户授权、API/UI 不可见；不可用时降级，不能阻断基础规则。
• 场景包保持纯配置；新场景不得复制 L1–L4 代码。

3. 契约与数据

• 事件 v0.1 已冻结。改 raw/contracts/ 时必须评估版本升级、同步生产者/消费者和示例，并记录兼容性。
• Schema 通过不代表契约通过；必须实现 README 规定的跨字段和隐私断言。
• 数据库迁移必须可回滚或有明确恢复方案；SQLite 与 PostgreSQL schema 语义保持一致。
• 凭据不得写入数据库普通字段、日志、证据文件名、Issue 或测试快照。
• 测试数据使用合成/脱敏样本，不提交真实住户、学生、人脸或摄像头视频。

4. 代码质量

• 标识符和公共契约使用英文；用户文案与项目文档默认中文。
• 错误必须分类、传播或记录，不吞错；重试必须有预算、退避和可观察指标。
• 注释解释原因、边界和风险，不复述代码。
• 使用项目已冻结的格式化、lint 和生成工具；生成代码与手写薄封装分离。
• 并发 goroutine/任务必须有生命周期、取消、超时和资源上限。
• 列表/API 默认分页；批量操作要有限流、部分失败结果和幂等设计。

5. 安全与不可逆动作

• 自动化默认 dry-run；批量删除、禁用设备、踢流、数据迁移和远端合并必须有边界与恢复说明。
• MediaMTX、临时看流页和调试端口默认不暴露到非可信网络。
• 删除孤儿资源必须通过比例安全闸；异常规模停止自动删除并告警。
• 静默最长 4 小时且自动恢复，不提供永久静默。
• 不绕过认证、RBAC、租户隔离、合规开关或平台审批。

6. 验证责任

任务所有者必须亲自：

1. 检查 git status --short、git diff、git diff --cached 与 git diff --check。
2. 对照 Issue/任务文件核对实际修改没有越过 write_paths。
3. 运行 03-tech-stack.md 的任务相关验证和所有被触发的完整门禁。
4. 在任务文件 ## 执行记录 记录真实命令、结果、失败与关键决策。
5. 必需的人工、现场、摄像头或 GPU 验收未完成时保持 DOING/BLOCKED，不标 DONE。

文档治理至少运行：

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

7. 完成清单

• 验收标准全部可观察且满足。
• 相关单元/集成/构建通过。
• 需要的设备、容量、安全或人工门禁已完成。
• 未越过任务、里程碑和系统边界。
• 文档、schema、API、路由和当前状态已按事实同步。
• 未提交敏感信息、真实视频或参考仓库内容。
• 任务文件含执行证据，PR 只映射一个 Issue。

拿不准时先在 Issue 提出具体问题、选项、影响与建议，不用猜测推进。