85 lines
4.5 KiB
Markdown
85 lines
4.5 KiB
Markdown
# 编码规则
|
||
|
||
## 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`](03-tech-stack.md) 的任务相关验证和所有被触发的完整门禁。
|
||
4. 在任务文件 `## 执行记录` 记录真实命令、结果、失败与关键决策。
|
||
5. 必需的人工、现场、摄像头或 GPU 验收未完成时保持 DOING/BLOCKED，不标 DONE。
|
||
|
||
文档治理至少运行：
|
||
|
||
```powershell
|
||
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 提出具体问题、选项、影响与建议，不用猜测推进。
|