OBCX

OBCX 是面向 OneBot 11 与 Telegram 的 C++26 机器人运行时。当前版本采用单一 反射 actor 扩展模型：动态组件继承 ReflectedActor<Derived>，以类型化 handle 重载声明输入，并由原生 work-stealing scheduler 执行。异步 handler 可通过 ActorContext::await_asio 等待网络、计时器和其他 Boost.Asio 操作。

构建

推荐使用仓库提供的 Nix 开发环境：

nix develop
cmake --preset actor-dev
cmake --build --preset actor-dev --parallel
ctest --preset actor-dev

也可以在系统环境中构建；需要 Linux x86_64/arm64、CMake 3.30、GCC 16.1+ 和 -std=c++26 -freflection（__cpp_impl_reflection >= 202506L），以及 vcpkg-base.json 中列出的依赖。Linux 默认在检测到 liburing 时启用 Asio 的 io_uring reactor，可用 -DOBCX_ENABLE_IO_URING=OFF 关闭。

安装 SDK 与运行时：

cmake --install build/actor-dev --prefix "$HOME/.local/obcx"

选择 actor package

actors.toml 只负责选择参与构建的 package；package 自身的身份、ABI、依赖、 兼容范围与发布信息只来自 package 内唯一的 actor.toml。可复制 actors-example.toml 后按需选择本地 package：

schema_version = 1

[[actors]]
path = "local_actor/obcx-actor-message-store"
enabled = true

[[actors]]
path = "local_actor/obcx-actor-bridge"
enabled = true

远程 package 使用 repository 与 revision；revision 必须是不可变 tag 或完整 commit revision，不能依赖会移动的分支名。配置阶段会通过 OBCXActorLoader.cmake 加载所选 package。配置完成后，依照实际 preset 的 binary directory 合并 vcpkg 依赖：

python3 cmake/gen_vcpkg_manifest.py actors.toml --binary-dir build/actor-dev
python3 cmake/gen_vcpkg_manifest.py actors.toml --binary-dir build/actor-dev --list

仓库内四个固定版本的 standalone actor 源码可在无网络环境恢复：

sh packaging/actors/restore-sources.sh

运行配置

运行时配置由 bot、actor、数据库与 pipeline 四部分组成。Scheduler 没有引擎 选择项；policy 只控制原生 scheduler 的 work stealing/sharing 行为，workers = 0 表示由统一线程预算自动分配。

[bots.qq]
type = "qq"
enabled = true

[bots.qq.connection]
type = "websocket"
host = "127.0.0.1"
port = 3001
access_token = ""

[actor_runtime.scheduler]
policy = "stealing"
workers = 0
blocking_workers = 0
slow_resume_warning_ms = 10

[actor_runtime.routing]
hop_limit = 32

[db.instances.main]
type = "sqlite"
path = "data/obcx.sqlite3"

[actors.message_store]
library = "message_store"
enabled = true
partition = "source_platform:conversation_id"
db = "main"
db_namespace = "message_store"

[actors.bridge]
library = "bridge"
enabled = true
requires = ["message_store"]
partition = "source_platform:conversation_id"
db = "main"
db_namespace = "bridge"

[pipelines.message]
source = "obcx::core::events::RawMessageEvent"

[[pipelines.message.stages]]
name = "persist"
actor = "message_store"
input = "obcx::core::events::RawMessageEvent"
output = "obcx::message_store::events::MessageStored"
mode = "await"

[[pipelines.message.stages]]
name = "forward"
actor = "bridge"
input = "obcx::message_store::events::MessageStored"
output = ["bridge::events::MessageForwarded", "bridge::events::MessageForwardFailed"]
after = ["persist"]
mode = "await"

library = "message_store" 这类按名称发现会搜索当前 binary tree 的 actors/ 目录，也会搜索已安装可执行文件对应的 <prefix>/lib/obcx/actors（以及 lib64 变体），因此 preset 构建与安装后的运行时不需要改写为绝对路径。

启动：

./build/actor-dev/src/app/obcx --no-tui config.toml

运行中可在 TUI 命令框或 --no-tui 的标准输入中输入 reload。命令接收后立即 返回；运行时会在后台构建完整候选 actor generation，关闭根 ingress、等待旧代已 接收的路由完成、原子切换并重新开放 ingress。切换不会重连 bot。仅 actor 条目、 actor 自有配置、pipeline 与路由策略可热更新；bot 定义、数据库实例或解析后的线程 预算变化会返回 reload_restart_required，必须重启进程。--no-tui 模式下按 Ctrl-C 会立即开始关闭，不需要再按 Enter 来结束标准输入行。

[actor_runtime.reload]
drain_timeout_ms = 5000 # 100..300000

若返回 reload_drain_timeout，运行时已回到旧 generation，候选已丢弃。若切换 成功但业务行为错误，恢复上一组不可变 actor 产物及其匹配配置后再次执行 reload。完整错误码与回滚流程见 Actor operations。

在不创建 scheduler worker、服务、bot 或 ingress 的情况下执行同一套生产校验：

./build/actor-dev/src/app/obcx --validate-config config.toml

--validate-config 会校验数据库 provider、actor contract 与依赖，以及 pipeline source、stage 依赖和 await/async mode，但不会创建 scheduler worker、服务、bot 或 ingress。

Bridge 的 bot、媒体与群组映射选项可参考 actor-config.example.toml； actor 依赖与数据库选择以本页的当前运行配置为准。

编写 standalone actor

推荐从 obcx-actor-template 开始。Package 的 actor.toml 是唯一 metadata 来源，必须声明 identity、ABI 2、artifact、依赖、 兼容范围、发布信息，以及确实完成构建和验证的 artifact.platforms。registry 不会 为未声明的平台虚构下载。最小 CMake 入口如下：

cmake_minimum_required(VERSION 3.30)
project(example_actor LANGUAGES CXX)

find_package(obcx-sdk CONFIG REQUIRED)
include(OBCXActor)

obcx_add_actor(example
  SOURCES src/example_actor.cpp
  OUTPUT_NAME example)

Actor library 继承 ReflectedActor<Derived>，公开精确的同步或异步 handle 重载，并使用 OBCX_ACTOR_EXPORT_V2 导出工厂、析构、名称、版本、数值 ABI 和 强制的 schema-1 输入 contract。ActorManager 在构造 actor 前校验 contract； 旧二进制、短消息名和缺少 contract 的 library 会被拒绝。

Actor 命令同样使用 typed message：actor contract 只声明命令名、说明和 request message type，配置再按 platform/bot scope 激活路由；平台适配器不调用 actor 函数。完整的 CommandCompleted、Continue/Consume、fallback、聚合 catalog 和迁移约束见 Actor command routing。

干净安装 SDK 的外部 package 验证：

ctest --preset actor-dev -R '^actor_sdk_v2_smoke$'
sh packaging/actors/restore-sources.sh
cmake --preset actor-conformance
cmake --build --preset actor-conformance --parallel
ctest --preset actor-conformance -R '^standalone_actor_v2_repositories$'

第二项会从干净 SDK 分别构建、安装并测试三个 standalone package；随后通过 ActorManager 动态加载安装后的 message-store 与 bridge 产物，执行 obcx::core::events::RawMessageEvent -> obcx::message_store::events::MessageStored -> bridge::events::MessageForwarded 管线并核对 数据库副作用和关闭流程；同时还会在保持同一组运行中 bot 实例的前提下修改 bridge 群组映射并执行 reload，验证切换后的消息只使用新映射。

Actor registry

actor-registry/ 保存 actor-only entry schema、确定性索引生成器与 bridge、 message-store 发布项：

python3 actor-registry/generate_actor_index.py validate
python3 actor-registry/generate_actor_index.py generate --check
python3 actor-registry/generate_actor_index.py resolve \
  --id vollate.bridge --version 0.1.0 --platform linux-x86_64

验证与文档

ctest --preset actor-dev
python3 scripts/generate_api_docs.py

当前架构与运维说明：

• Actor runtime ADR
• Actor operations
• Actor author guide
• Actor package registry

本次不兼容边界与升级后的唯一受支持配置见 actor-only breaking change。历史基准与路线图 不代表当前运行时选项。

License

项目按仓库中的 LICENSE 发布。