# 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. 只有用户明确验收通过后才能关闭工单。

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

## 常用命令

```powershell
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 并同步，或明确记录无影响。
- 最终证据已回写工单；用户尚未验收时工单保持开启。