mediamtx/AGENTS.md

MediaMTX 定制版开发规则

本仓库是 MediaMTX 的长期定制分支。上游代码、官方 docs/、测试与发布流程继续有效；DevHarness 只管理 OPC 定制需求、长期维护事实和实施证据。

开始工作前阅读当前工单、相关 Wiki 镜像和任务涉及目录的规则。代码发现优先使用 codebase-memory MCP；不可用时再使用 rg。

事实来源

• Gitea 单元工单：单次需求、方案、实施、测试和验收。
• Gitea Wiki：定制版长期有效事实。
• docs/maintainer/：Wiki 的只读镜像，禁止直接编辑。
• Git：代码和版本绑定资料。
• MediaMTX 原有 docs/：上游产品文档，不由 DevHarness 覆盖。

永久规则

• 不提交摄像头 URL、用户名、密码、Token、Cookie、私钥、个人数据或生产数据。
• ip_camera.env 必须保持本地且被 Git 忽略；日志、测试和工单使用虚构数据。
• 不覆盖或顺手恢复用户已有的无关改动，包括上游文件的删除。
• 不执行未经明确授权的发布、删除数据、破坏性迁移或破坏性 Git 操作。
• 测试结果必须真实，未执行和未覆盖部分必须记录。
• Control API、认证、权限和公网暴露属于高风险，方案变化时先停止并等待确认。

上游边界

• origin 是 https://git.ilapage.cn/OPC/mediamtx.git。
• upstream 是 https://github.com/bluenviron/mediamtx.git。
• 当前建设基线记录在 docs/maintainer/1-project-profile.md。
• 定制实现应集中、命名清楚、测试独立，避免无关重构和上游合并冲突。
• 不用 DevHarness 替换 MediaMTX 原有 .github/、Go 测试、Makefile、release 或官方文档体系。

需求到实施

1. 先只读检查代码、工作区、工单和相关长期文档，区分事实与假设。
2. 给出目标、非目标、方案、影响、风险、回退、验证和文档影响。
3. 用户确认方案后建立一个可独立测试和回退的 Gitea 单元工单。
4. 检查工单前置依赖和工作区，只修改工单范围。
5. 执行与风险相称的测试，把关键结果和未验证内容写回工单。
6. 只有长期事实变化时更新 Wiki，回读 revision 后运行文档同步。
7. 完成实现后回写最终差异、测试、提交哈希和文档影响，保持“待验收”。
8. 只有用户明确验收通过后才能关闭工单。

新页面或重大交互必须先提供可审阅原型，确认页面、状态、权限、错误处理和验收范围后再实现。简单文案修改使用最低成本的审阅证据。

常用命令

git status --short --branch
python dev_scripts/harness.py check --strict
python dev_scripts/harness.py sync --check
python -m unittest discover -s tests -v
go test ./internal/api ./internal/core
go test ./...
go build ./...

只运行与当前风险和验收有关的检查；代码修改后必须重新运行受影响测试。

快捷指令

• 只分析：只读检查并给出方案，不建单、不修改。
• 建工单：创建已确认方案的单元工单，不修改代码。
• 执行工单 #N：实施、测试、提交并回写证据，停在待验收。
• 检查工单 #N：只读核对范围和证据，不自动修复。
• 同步文档：从 Wiki 单向更新 docs/maintainer/，不反向覆盖 Wiki。
• #N 验收通过：记录明确验收结论并关闭工单。

快捷指令不得绕过方案确认、安全边界、工单范围、必要测试或人工验收。

完成条件

• 当前工单验收项完成，必要测试通过。
• 无关工作区改动未被提交。
• 长期文档影响已更新 Wiki 并同步，或明确记录无影响。
• 最终证据已回写工单；用户尚未验收时工单保持开启。