UniBind - 跨平台用户身份绑定

UniBind 是一个基于 ErisPulse 框架的跨平台用户身份绑定模块，通过验证码将不同平台的同一用户关联到统一身份，并可选通过适配器中间件对下游模块透明地替换事件中的用户身份。

功能特性

• 统一身份管理：跨平台用户身份绑定，一个身份关联多个平台账号
• 验证码机制：6位数字验证码，5分钟有效，安全可靠
• 强制替换：适配器中间件级事件改写，对下游模块完全透明
• 自定义显示身份：每个绑定可独立指定替换后的平台和用户ID
• 扩展字段：通过 extra JSON 存储自定义用户属性
• 对外 API：提供完整的编程接口供其他模块调用

安装

epsdk install UniBind

配置

在 config.toml 中可自定义以下配置（均有默认值，无需手动添加）：

[UniBind]
verify_code_expire = 300     # 验证码有效期（秒）
verify_code_length = 6       # 验证码长度
max_accounts_per_user = 10   # 每个统一用户最大绑定账号数

使用方法

创建身份

在任意平台发送：

/bind

自动创建统一身份并生成验证码，返回验证码用于在其他平台绑定。

跨平台绑定

在另一个平台发送：

/bind 384729

输入验证码后选择显示身份，完成绑定。

查看绑定信息

/bind.info

列出所有绑定账号

/bind.accounts

设置扩展字段

/bind.set name 新名称
/bind.set email user@example.com

强制替换

开启后，中间件会将事件中的用户身份替换为指定的显示身份，对下游模块透明：

/bind.force

选择显示身份后开启。再次发送可关闭。

解绑

/bind.unbind

解绑当前平台账号。如果是最后一个绑定，统一身份将被删除。

命令列表

命令	说明
/bind	创建身份或生成验证码（已绑定时显示信息）
/bind <验证码>	通过验证码绑定到已有身份
/bind.info	查看当前绑定信息
/bind.accounts	列出统一身份下所有平台账号
/bind.set <key> <value>	设置扩展字段
/bind.force	开启/关闭强制替换
/bind.unbind	解绑当前平台账号

强制替换（中间件）

当用户通过 /bind.force 开启强制替换后，适配器中间件会自动改写事件数据：

原始事件 (telegram, tg456) → 强制替换为 (yunhu, U1001)

改写后事件:
  platform: "yunhu"
  user_id: "U1001"
  unibind_original: { platform: "telegram", user_id: "tg456" }

下游模块无需感知 UniBind 的存在，直接使用改写后的身份即可。

对外 API

其他模块可通过 sdk.UniBind 访问以下接口：

# 通过平台账号解析统一身份
aid = sdk.UniBind.resolve("yunhu", "U1001")      # → "uuid-xxx" 或 None

# 获取统一用户信息
user = sdk.UniBind.get_user("uuid-xxx")            # → {"aid", "name", "avatar", "extra", ...}

# 获取所有绑定账号
accounts = sdk.UniBind.get_accounts("uuid-xxx")    # → [{"platform", "user_id", "name", ...}, ...]

# 获取扩展字段
extra = sdk.UniBind.get_extra("uuid-xxx")          # → {"email": "...", ...}

# 批量查询
mapping = sdk.UniBind.resolve_batch([
    ("yunhu", "U1001"),
    ("telegram", "tg456"),
])
# → {"yunhu:U1001": "uuid-xxx", "telegram:tg456": "uuid-xxx"}

# 检查是否开启强制替换
is_force = sdk.UniBind.is_force_enabled("yunhu", "U1001")

# 获取替换后的显示身份
display = sdk.UniBind.get_display_identity("yunhu", "U1001")
# → {"platform": "yunhu", "user_id": "U1001"} 或 None

项目结构

ErisPulse-UniBind/
├── pyproject.toml
├── README.md
├── LICENSE
└── ErisPulse_UniBind/
    ├── __init__.py
    └── Core.py

许可证

MIT License