AstrBot 插件标识：
tntexploding/astrbot_plugin_socialdatabase
这是一个独立的 AstrBot 插件。它通过
OneBot v11 aiocqhttp 适配器按需读取群成员，把每个群转换为一个版本化 JSON
批次，并通过 HTTP 上传给
SocialDatabase。
插件与服务端没有 Python 代码依赖：插件只负责采集、持久排队和 HTTP 发送；
SocialDatabase 只负责认证、校验、幂等导入、非破坏合并和查询。两者的唯一接口
是 POST /api/v1/imports/json。
- AstrBot
>=4.17,<5 - OneBot v11
aiocqhttp平台适配器 - 可访问的 SocialDatabase HTTP 服务；公网部署必须使用 HTTPS
插件被官方市场收录后，可在 AstrBot WebUI 插件市场中搜索 “SocialDatabase 数据同步”安装。
在 AstrBot WebUI 中使用仓库地址安装：
https://github.com/tntexploding/astrbot_plugin_socialdatabase
也可以在 AstrBot 根目录手动安装：
cd data/plugins
git clone https://github.com/tntexploding/astrbot_plugin_socialdatabase.git然后在 WebUI 重载插件。AstrBot 会依据仓库根目录的 requirements.txt 安装
aiohttp。不要只复制 main.py；辅助模块、配置 Schema 和依赖文件都必须保留。
插件通过 AstrBot WebUI 管理 _conf_schema.json 中的配置：
server_url：SocialDatabase 根地址，不要附加 API 路径。api_token：服务端 Bearer 令牌；留空时仍允许采集入队，但不会上传。allowed_group_ids：允许采集的群号；空列表拒绝所有群。collect_all_enabled：是否允许批量采集，默认关闭；开启后仍只处理白名单群。producer：稳定的数据生产方名称，默认astrbot-socialdatabase。request_timeout_seconds：OneBot 调用和 HTTP 请求总超时。retry_interval_seconds：首次重试及空闲轮询间隔。max_attempts_per_cycle：每轮最多处理的待发送批次数。no_cache：禁用 OneBot 群信息缓存，并为 HTTP 请求发送no-store。
令牌保存在 AstrBot 的插件配置中，不应写入本仓库、日志或问题报告。
/socialdb_collect：仅在当前群属于采集白名单时生成一个 JSON v1 批次。/socialdb_collect_all：需显式启用，只采集机器人已加入且位于白名单中的群。/socialdb_flush：忽略退避时间，立即尝试当前队列的一轮批次。/socialdb_status：显示 pending、rejected、令牌配置状态和最近上传结果；不显示令牌值。
插件不会自动定时采集。后台任务只重试已经持久化的批次。 全部管理员命令会显式截断当前消息事件，不继续进入 AstrBot 的 LLM 流程。
只有 AstrBot 管理员主动执行采集命令且目标群位于显式白名单时，插件才会通过当前
aiocqhttp 适配器读取群列表、群资料和群成员资料。采集结果仅发送到管理员
配置的 server_url；插件不连接第三方统计服务，也不会把 api_token 写入
批次、日志或命令响应。部署者应确认自己有权处理对应群成员数据。
采集命令返回成功前，会先把批次原子写入 AstrBot 官方约定的数据目录：
data/plugin_data/astrbot_plugin_socialdatabase/
├── pending/
└── rejected/
该目录不位于插件源码中，更新或重装插件不会覆盖待发送批次；部署时应把它纳入
AstrBot 备份。网络超时、401、403、429 和服务端故障会保留原始
producer + batch_id 并指数退避。HTTP 200/201 确认后删除 pending 文件；
400、409、413、415、422 会移入 rejected 并保存错误原因。
服务端导入历史是成功批次的权威记录。不要直接修改已经被服务端接受过的稳定 批次 ID 对应内容。
插件只提交本次 OneBot 返回的成员。批次没有出现某个历史成员，不表示该成员 退群；SocialDatabase 不会因此删除关系或清空最后已知资料。
本仓库的 contracts/import-batch-v1.schema.json 是开发和测试使用的 JSON v1
契约快照，权威说明由 SocialDatabase 的
数据格式文档
维护。插件运行时不导入或安装 SocialDatabase Python 包。
| 插件版本 | AstrBot | SocialDatabase 接口 |
|---|---|---|
| 0.8.x | >=4.17,<5 |
JSON v1，服务端 >=0.8.0 |
首次连接真实 AstrBot、OneBot 与服务端时，按 SocialDatabase v0.8.0 的
联合调试清单
验证热重载、离线队列、幂等导入和历史关系保留。
- 服务端同时接受新、旧令牌。
- 在插件配置中换成新令牌并重载插件。
- 执行
/socialdb_flush，确认 pending 归零。 - 服务端撤销旧令牌。
如果顺序操作失误，401 只触发持久重试，不会丢弃批次。
python -m venv .venv
python -m pip install -r requirements-dev.txt
python -m ruff format --check .
python -m ruff check .
python -m pytest纯模块测试不要求启动 AstrBot；发布前仍应按照 AstrBot 官方开发文档，在真实 AstrBot 与实际 OneBot 实现中完成插件加载、重载及命令联调。
维护者发布到官方插件市场时，请使用仓库内的 发布清单核对版本、身份和提交步骤。