工具库 API 总览

插件能用的 API 分三层，各自独立成篇：工具库（obsession-shared：宿主桥 / 数据 / 媒体 / 中转，就是本页）、UI组件（hualuo-compose-ui：组件与主题）、插件框架（com.hualuo.plugin.framework：BasePluginActivity 与生命周期）。本页按包列出工具库的公开 API，方法签名与源码一致；UI组件与插件框架是宿主发的 AAR，完整清单以它们自己的源码为准。

工具库有什么

工具库就是 obsession-shared 这一个模块，插件写 implementation(project(":obsession-shared")) 引入。它干四件事：

块	包	解决什么问题
宿主桥	...box.common.host	拿登录态、跳登录页、统一域名、主题、激励广告、宿主设置
数据	...box.common.data	存键值、存记录列表、建自己的表 —— 都按插件隔离
媒体	...box.common.mediaexport	把图片 / GIF / 视频写进系统媒体库（含 API 24~28 分支）
中转	...box.common.relay	读后端接口的公开配置，据此判断「这次要不要花执念币」

除此之外它还用 api 暴露了一整套基础依赖栈，插件不用自己声明版本：Compose（含 Material3）、AndroidX core/lifecycle/activity、OkHttp、Coil、kotlinx-coroutines，以及 UI组件库 hualuo-compose-ui。所以插件里可以直接 import okhttp3.*、import coil.compose.AsyncImage。

什么场景用哪个

你要做的事	用这个	在哪页
界面外层套主题（必用）	PluginTheme	宿主桥
判断登没登录、拿 token	UserManager.getUserToken()	宿主桥
让用户去登录	UserManager.toLogin(activity)	宿主桥
拼后端地址（禁止写死域名）	ZhinianHost.BASE_URL	宿主桥
看激励广告换奖励	RewardAdManager.requestAndShowAd(...)	宿主桥
存开关 / 小配置	PluginKv	键值存储
存一串同类记录（历史、草稿、收藏）	PluginRecords	记录列表
结构固定的表装不下，要自己的表	PluginDb / PluginDbs	自定义表
把生成结果落盘到系统媒体库	MediaExporter	保存媒体
调后端中转接口	OkHttp + ZhinianHost.BASE_URL	网络请求
显示「消耗多少执念币 / 还剩几次」	RelayConfigClient + BenefitCard	中转配置与权益

三条容易踩的线

域名、主题、权益，这三处别自己造

• 域名：一律用 ZhinianHost.BASE_URL。写死 https://obsession.yihualuo.cn 的插件，换域名后会整体失联。
• 主题：界面外层必须是 PluginTheme。不要自己调 HuaLuoTheme，也不要自己读宿主设置算深浅色 —— 那正是 PluginTheme 在做的折算。
• 权益文案：币数和次数一律先从 RelayConfigClient 拉到配置再渲染，不要写死「消耗 8 执念币」。后台改策略时插件要自动跟着变。

这一层不管什么

• 没有状态管理 / 依赖注入：ViewModel 还是普通类，插件自己定，工具库不介入。
• 没有路由：插件入口是 BasePluginActivity，界面内部怎么切由你自己用 Compose 状态控制。
• 没有图片加载封装：Coil 已在基础栈里，直接用 AsyncImage（ListItem 的 iconUrl 就是这么实现的）。
• 没有统一的 OkHttp 单例：MediaExporter 内部有一个自己的 client，插件发请求请自建（见网络请求），避免共用连接池带来的超时互相影响。