话题通信 + 全量溯源（强制架构约束）

本规则对所有涉及代码的项目生效。agent 在设计和实现模块时必须遵循以下架构约束。

作用域

本规则对所有涉及代码的项目生效，但根据项目类型有不同强度：

当项目为纯工具/配置类（如本模板项目本身），agent 不应强制要求话题通信架构，仅保持日志和 MD5 留痕即可。

模块间通信：话题（Topic / Pub-Sub）

所有模块间数据传递统一使用话题机制，禁止直接函数调用传数据（内部纯计算除外）。

话题模型

Publisher → Topic(name, schema) → Subscriber(s)

每条消息结构：
{
  topic: string,          // 话题名，如 "order.created", "sensor.imu"
  timestamp: ISO8601,     // 发布时间
  source: string,         // 发布者模块标识
  payload: any,           // 业务数据
  trace_id: string,       // 链路追踪 ID（贯穿整条调用链）
  seq: number             // 该话题上的序列号
}

实现选择（按项目需求选型）

无论哪种方案，必须满足：

• 话题可枚举（有 topic registry）
• 消息可回放（有持久化或日志）
• 订阅关系可查（运行时可 dump）

全量日志：一切留痕

必须记录的事件

日志格式

[timestamp] [level] [module] [trace_id] message {structured_data}

结构化数据为 JSON，至少包含：触发源、变更前后值、关联 trace_id。

MD5 完整性日志

对以下对象维护 MD5 校验记录：

• 所有配置文件 — 启动时计算 + 变更时重算
• 构建产物 — 构建完成时记录
• 数据文件 — 写入/导入时记录
• 部署包 — 发布时记录

MD5 日志格式（append-only）：

[timestamp] [event] [path] [md5] [operator]

存储位置：项目根目录 .trace/integrity.log

溯源基础设施

每个项目必须包含：

.trace/
├── topics.registry.json   # 话题注册表（名称 + schema + publisher + subscribers）
├── integrity.log          # MD5 完整性日志
└── events/                # 事件日志（按日期分文件）
    └── YYYY-MM-DD.jsonl

agent 实施要求

1. 新建项目时：自动创建 .trace/ 目录结构和 topic registry
2. 新增模块时：检查其对外通信是否走话题，不走则要求重构
3. 新增状态时：确保状态变更有日志记录
4. 修改文件时：更新 integrity.log 中的 MD5
5. 代码审查时：检查是否有"暗通道"（模块直接调用传数据绕过话题）

禁止行为

• 禁止模块间通过全局变量/单例共享状态（必须通过话题）
• 禁止状态变更不写日志
• 禁止文件操作不记录 MD5
• 禁止删除或截断 .trace/ 下的日志文件