ErisPulse ErisPulse
在交互式文档中心打开 →
本页章节
本文为静态镜像,内容以交互版为准 在交互式文档中心打开 →

技术标准

Tip

什么时候需要读这篇:当你在开发或修改适配器,需要确认事件转换、API 响应、发送方法等是否符合 ErisPulse 跨平台标准时,从本目录找对应规范对照。不确定从哪篇开始时,先读下方总纲。

总纲:适配器标准化指南 —— 标准化原则、标准地图、命名规则、差异处理模式与开发者 Checklist。新适配器/新能力请先读它。

本文档包含 ErisPulse 的技术标准规范,确保各组件间的一致性和兼容性。

标准文档列表

  1. 会话类型标准 - ErisPulse 会话类型定义和映射规范
  2. 事件转换标准 - 平台事件转换规范、扩展命名规范、消息段标准
  3. API 响应标准 - 适配器 API 响应格式标准及扩展要求
  4. 发送方法规范 - Send 类方法命名、参数规范及反向转换要求
  5. 请求操作规范 - 请求事件字段要求、Request DSL(approve/reject)、异构端点的请求类型上下文留存及适配器实现要求
  6. API 动作标准 - OneBot12 标准 API 动作统一接口(用户/群组/频道/消息管理/文件含分片/元动作)
  7. 适配器标准化指南(总纲) - 标准化原则/工作流/命名规则 + 交互组件标准(按钮键盘/交互回调事件)与各平台映射

标准概述

ErisPulse 采用 OneBot12 作为核心事件标准,并在此基础上进行了扩展和细化。

核心原则

  1. 兼容性:所有标准都必须与 OneBot12 标准保持兼容
  2. 扩展性:平台特有功能通过前缀方式扩展,避免冲突
  3. 一致性:时间戳、ID 格式等关键字段需要统一处理
  4. 可追溯性:保留原始数据以便调试和问题排查

为什么需要标准?

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
  • file 参数应当形态尽量支持:file:// URI / Base64 / Data URI(无法支持时按降级阶梯返回 retcode=10002)
  • 形态判定顺序符合规范(bytes → URL → file:// → 路径)
  • File 的文件名按推导顺序生成(显式 filename > URL basename > 路径 basename > 平台默认)
  • 平台媒体限制已在适配器文档声明
  • 不支持的媒体类型按降级阶梯处理(近缘类型降级或 retcode=10002,不抛异常、不静默丢弃)

详细协议见 发送方法规范 §2.1

请求操作

  • Request 内部类已重写 _do_accept / _do_reject(公开入口 accept()/reject() 勿重写)
  • 操作返回标准 API 响应格式
  • 不支持的操作返回 retcode=10002

相关文档