编码规范
R3el 应易于导航、理解和维护。每个组件都应有清晰的职责、合理的归属位置及明确的接口。本指南说明设计目标；已有模块仍可能需要进一步调整以符合这些目标。
代码应尽可能精简。只为当前已存在的需求与行为构建，不为假设的未来情况开发。优先采用能够清楚支持当前流程的最简单设计，使运行行为可观察，并根据真实使用发现下一步改进。没有明确需求就不要添加抽象层、兜底路径、兼容层、配置开关或防御性复杂度。真正出现新需求时，再依据实际证据扩展或重构。
按职责分类
R3el 采用定制的 Common Unified Development Process 作为开发风格。各类按照职责分为：
| 类别 | 职责 | 示例 |
|---|---|---|
| Interface | 桥接技术、API 或协议，负责通信机制。 | MariaDB 的 DbMgr、文件系统的 FileMgr、ZeroMQ 传输类。 |
| Activity | 对数据进行转换、计算和应用操作。 | 规范化媒体元数据或匹配媒体目录记录。 |
| Entity | 保存数据，可以持久化或仅驻留内存。 | 媒体记录或内存中的处理结果。 |
职责必须分开，避免巨型单体类。Activity 操作 Entity，需要读写或通信时使用 Interface。表示持久数据的 Entity 不应同时管理数据库连接和持久化机制。
如果一个类同时包含技术访问、数据转换与存储，应将它拆成专注的协作者，以组合连接，而不是不断发展继承树。分类只说明角色，不要求公共基类或某种继承层次。
这里的“interface class”指技术适配类。在其他地方，“接口”也可能指组件的公开契约；仅有公共方法并不意味着是 Interface 类。
按职责组织代码
把相关组件置于 r3el/ 下：
| 包 | 职责 |
|---|---|
app/ |
应用逻辑与工作流。 |
activity/ |
公共活动，例如建表和事件准备。 |
entity/ |
MediaFile、MediaFileBatch、Identification 等数据对象。 |
server/ |
服务器入口与编排。 |
interface/ |
外部服务及应用组件的技术接口。 |
constants/ |
应用共享常量。 |
zmq/ |
ZeroMQ 传输组件。 |
只有某种职责确实需要独立归属时才增加包，结构应聚焦 R3el 实际功能。
主要类各自放在以类名命名的模块中。小型辅助类型或私有工具可以与所属组件放在一起。优先使用从归属模块显式导入的方式，例如：
from r3el.constants.DR3el import DR3el
展示代码及资源放在一起，与应用逻辑分开。包初始化文件保持简短；需要可执行入口时使用 __main__.py。重构时保持已有文档所声明的入口可以使用。
把应用含义和底层机制分开
应用代码应调用表达其业务意图的接口，接口将请求翻译为底层辅助组件的操作。调用方不应绕过接口直接访问辅助组件内部资源。
通用辅助模块必须独立于 R3el 的业务规则与数据库结构。应用层决策留在理解 R3el 的层中，用组合明确连接两者。
信任内部契约
给 LLM 的任务数据使用 JSON，并与提示指令分开。发送前先整理数据：排序文件列表、分配连续数字 ID，在服务器内部保留精确路径和 ID 映射。账务与状态管理交给确定性代码，只让 LLM 做解释性判断。
R3el 内部模块由同一系统开发与维护。使用清晰的接口、类型注解和测试定义其契约。不要仅仅担心其他内部模块被错误使用，就在运行时重复检查类型、属性是否存在、反复验证，或增加备用路径。
在外部输入边界进行验证，例如配置文件、传入消息及数据库解码结果。验证并转换为内部应用对象后，内部调用方直接依赖这些对象，无须在每层重复验证。
内部程序错误应清楚暴露，即使导致应用停止。修复根因并新增回归测试。不要用宽泛异常处理、静默默认值、强制类型转换或臆测的恢复逻辑隐藏缺陷。
资源清理和事务回滚应可靠，但仍允许错误继续传播。由负责边界处理预期的外部故障，并保留其原因。这不等于需要围绕可信的内部调用堆积防御框架。
采用共享数据访问层
访问 MariaDB 的应用组件应使用统一的数据访问层，将业务操作与数据库机制分开。
应用接口负责：
- R3el 表名、字段映射与业务查询。
- 在应用对象和持久化表示之间转换。
- 决定哪些操作必须在同一事务中共同成功。
数据库辅助层负责：
- MariaDB 连接建立、凭据、超时和连接清理。
- 游标的创建、使用与关闭；游标不得逃逸出这一层。
- SQL 构建、标识符验证和引用，以及参数绑定。
- 事务开始、提交、回滚和只读事务。
- 一致的结果处理及保留原始原因的数据库错误。
必须让数据库错误离开事务代码块，以便辅助层回滚并报告。在事务块外处理错误；不要吞掉错误后继续向同一事务执行 SQL。依靠 MariaDB 的行锁与约束，而不是添加重复一致性检查。
数据库辅助层不应理解 R3el 的业务规则。应用组件不应自行实现另一套连接或 SQL 执行机制。副作用应明确；建立数据库连接不能顺带执行无关应用操作。
将配置验证封装在一个接口之后
所有外部配置通过一个应用接口解析，之后才交给内部组件。此接口拥有业务规则，要么返回完整配置，要么抛出明确错误。内部组件直接使用解析后的配置，不再二次验证。
如果需要通用的模式校验工具，使其独立于 R3el 规则，并隐藏在配置接口之后。解析配置不能修改调用者的数据，也不能在不同调用之间共享可变的默认对象。错误必须能指出具体配置字段。
分步重构以便审查
一次只进行一项连贯的结构变更。移动或重命名组件时保留原行为，把行为修改作为独立工作。
每次移动都要更新导入、相关测试引用、资源路径及部署文件列表和复制规则。在源码检出中有效的模块也必须包含在安装产物里。
执行与改动相关的测试。修改层次边界时，应检查事务原子性、回滚、资源清理、错误转换以及对共享接口的使用。将模块改为包后，检查入口点与资源加载。
区分新故障和既有故障。明确报告验证限制，包括未运行真实数据库集成测试的情况。
有选择地使用 BMForge 流程
在有帮助时采用 BMForge 工程与流程指南。R3el 保留原有架构、编码规范、依赖、分支、安装工具与发布流程。不要把它当作全新 BMForge 项目来初始化、安装 greenfield 基线，或为形式上符合规范而重写现有代码。仅阅读规范不代表应用符合它，也不意味着授权迁移。
根据任务需要应用以下流程：
- 实现前明确预期结果和可观察的验收检查。直接要求实现某项功能意味着可以完成该范围，无需逐文件征求批准。重大范围变化、新依赖或架构改变需要额外授权。
- 用与改动规模相称的检查验证受影响行为。报告完成的验证、既有失败和验证限制。修改涉及安装清单时同步更新相关文档与清单。
- 生产故障调查遵循 BMForge RCA：仅从授权主机只读采集证据，然后在本地复现、分析并修复。
- 已授权的部署操作执行前，应审查相关服务、文件、配置和数据，保留用户设置及持久化数据，验证安装行为。继续使用 R3el 自身工具；发布和生产部署是分开的操作。
- 发布时使用
scripts/new-release.sh和现有分支流程。提交、推送、发布及部署各自需要明确授权；实现权限不自动包含这些动作。
在一次工作会话中首次进行 BMForge 相关编辑前，在仓库根目录运行只读本地检查：
python3 .agents/bmforge/manage.py check --project .
报告可用更新或检查不可用。该检查使用本地快照，不从上游拉取。继续遵循锁定版本的技能；更新或安装其他技能必须另获授权。
维护 CHANGELOG.md
每项完成的逻辑变更都遵循 BMForge 变更日志流程：
- 在同一任务中立即更新
CHANGELOG.md，在宣布完成或提交前写好。小修复、测试、文档、配置、依赖、维护也必须记录，而不仅是功能代码。 - 将已完成的结果写在唯一的
## [Unreleased]标题下，解释做了什么以及有什么意义。相关文件修改合并为一个简洁条目；不要记录放弃的尝试或尚未完成的计划。 - 重要改进应在
## [Unreleased]下直接增加或刷新一个### Summary，用一两句通俗语言概括收益。仅改正拼写等小改动可以只写一条项目符号。 - 每个未发布或已发布章节最多一个 Summary。新增改动时更新现有 Summary。可按需要使用
### Added、### Changed、### Fixed、### Removed，但不要保留空标题。 - 交付前检查每项已完成的逻辑改动都有记录，摘要是最新的，先前未发布内容和已发布历史保持完整。
- 版本号、时间戳及元素代号由 R3el 现有发布流程处理。发布脚本将未发布内容移动到新版本标题下，并为后续工作留下空的 Unreleased。