技术标准
总纲：适配器标准化指南 —— 标准化原则、标准地图、命名规则、差异处理模式与开发者 Checklist。新适配器/新能力请先读它。
本文档包含 ErisPulse 的技术标准规范，确保各组件间的一致性和兼容性。
标准文档列表
- 会话类型标准 - ErisPulse 会话类型定义和映射规范
- 事件转换标准 - 平台事件转换规范、扩展命名规范、消息段标准
- API 响应标准 - 适配器 API 响应格式标准及扩展要求
- 发送方法规范 - Send 类方法命名、参数规范及反向转换要求
- 请求操作规范 - 请求事件字段要求、HandleRequest DSL 及适配器实现要求
- API 动作标准 - OneBot12 标准 API 动作统一接口（用户/群组/频道/消息管理/文件含分片/元动作）
- 适配器标准化指南（总纲） - 标准化原则/工作流/命名规则 + 交互组件标准（按钮键盘/交互回调事件）与各平台映射
标准概述
ErisPulse 采用 OneBot12 作为核心事件标准，并在此基础上进行了扩展和细化。
核心原则
- 兼容性：所有标准都必须与 OneBot12 标准保持兼容
- 扩展性：平台特有功能通过前缀方式扩展，避免冲突
- 一致性：时间戳、ID 格式等关键字段需要统一处理
- 可追溯性：保留原始数据以便调试和问题排查
为什么需要标准？
1. 确保跨平台兼容
不同平台的事件格式各不相同，标准化的转换确保：
- 模块代码只需编写一次，即可在所有平台运行
- 事件处理逻辑保持一致
- 降低开发和维护成本
2. 规范 API 接口
统一的 API 响应格式确保：
- 模块可以一致地处理 API 错误
- 错误信息统一且易于理解
- 返回数据结构一致
3. 提高代码质量
标准规范帮助：
- 保持代码风格一致
- 减少命名冲突
- 提高代码可读性
遵循标准的好处
对适配器开发者
- 清晰的转换规则
- 统一的响应格式
- 易于调试和测试
对模块开发者
- 一致的事件接口
- 可预测的 API 行为
- 简化的跨平台开发
对最终用户
- 稳定的系统行为
- 统一的消息格式
- 良好的兼容性
标准遵循检查清单
事件转换
- 所有标准字段已正确映射
- 平台特有字段已添加前缀
- 时间戳已转换为10位秒级
- 原始数据保存在 {platform}_raw
- 原始事件类型保存在 {platform}_raw_type
- 消息段的 alt_message 已生成
- 请求事件包含 request_id 字段
API 响应
- 包含 status 字段
- 包含 retcode 字段
- 包含 data 字段
- 包含 message_id 字段
- 包含 message 字段
- 返回码遵循 OneBot12 规范
发送方法命名
- 使用大驼峰命名法（PascalCase）
- 返回 Task 对象
- 修饰方法返回 self
- 参数命名符合规范
媒体发送（Image / Voice / Video / File）
-
file参数必须形态全部支持：HTTP(S) URL / 本地路径 /bytes - 形态判定顺序符合规范（bytes → URL →
file://→ 路径） -
File的文件名按推导顺序生成（显式filename> URL basename > 路径 basename > 平台默认） - 平台媒体限制已在适配器文档声明
- 不支持的媒体类型按降级阶梯处理（近缘类型降级或
retcode=10002，不抛异常、不静默丢弃）
详细协议见 发送方法规范 §2.1
请求操作
- HandleRequest 类已实现 _do_accept / _do_reject
- 操作返回标准 API 响应格式
- 不支持的操作返回 retcode=10002