本文是给插件作者的规范:怎么写一个能被 Stella 完整用起来的插件,以及为什么某些写法必须这样写。设计过程与取舍记录见 design_docs/插件接入规范落地方案 v1.0.md;运行期机制见 能力系统与架构说明。
一句话概括:Stella 插件 = AstrBot 插件 + 一个可选的 capability.toml。你不需要学一套新框架,也不需要为 Stella 单独维护一份代码。
Stella 通过 astrbot_compat/ 把 AstrBot 的插件 API 伪装进 sys.modules,所以插件里的 from astrbot.api.star import Star 这类导入在 Stella 里照常成立。这层的兼容声称版本是 ASTRBOT_COMPAT_VERSION(默认 4.27.0)。
三条承诺:
- 加法,不是分叉。 本规范只增加可选文件(
capability.toml)与可选字段(metadata.yaml里的stella段)。不新增基类、不新增装饰器、不新增加载器。 - 双向可跑。 按本规范写的插件放回 AstrBot 也能原样运行——AstrBot 不读
capability.toml,多一个文件不影响它。 - 不保证全量可用。 兼容层是重新实现,不是移植;AstrBot 的部分 API 在 Stella 里没有对应物(见 §11 兼容性矩阵)。碰到这些 API 会抛
StellaCompatNotSupported,异常信息里带 API 全名,不会静默降级成错误行为。
如果你只想让现成的 AstrBot 插件在 Stella 上跑起来,README 的「装插件」三步就够了;本规范面向的是「想让插件在 Stella 上完整发挥」的情况——差别集中在 §6 工具通路。
# data/plugins/astrbot_plugin_hello/main.py
from astrbot.api.event import AstrMessageEvent, filter
from astrbot.api.star import Context, Star
class HelloPlugin(Star):
def __init__(self, context: Context, config=None) -> None:
super().__init__(context, config)
@filter.command("你好")
async def hello(self, event: AstrMessageEvent):
yield event.plain_result(f"你好,{event.get_sender_name()}")放进 data/plugins/astrbot_plugin_hello/,重启,群里 @机器人 /你好 即可。到这一步不需要任何附加文件。
一份可以直接拷走的完整模板在 docs/examples/astrbot_plugin_stella_template/——它同时是本规范的可执行脚注(plugin-check 对它断言零 error、零 warn)。
| 文件 | 必需性 | 作用 | AstrBot 是否也读 |
|---|---|---|---|
main.py |
必需 | 入口。必须有 Star 子类;没有这个文件的目录直接被跳过 |
是 |
metadata.yaml |
建议 | name / desc / version / author / repo;缺失时回退到 @register 参数,再回退到目录名 |
是 |
capability.toml |
有 @llm_tool 就必需 |
能力声明。缺了工具照常注册,但永远不会被聊天触发(§6.2) | 否(Stella 扩展) |
_conf_schema.json |
可选 | 用户可配项的 schema,展开后经 self.config 读取 |
是 |
requirements.txt |
可选 | 依赖。默认不自动装(ASTRBOT_AUTO_INSTALL_REQUIREMENTS=false),只在日志里点名 |
是 |
README.md |
建议 | 也是 plugin-scaffold 生成 examples 时最好的语料来源 |
— |
目录名不必是合法的 Python 标识符:GitHub「Download ZIP」解出来的 xxx-master / xxx-main 会被自动挂到一个合法包名下(日志里会写明挂成了什么)。但压缩包本身必须先解压——data/plugins/ 下的 .zip 不会被加载,启动诊断会单独把它列出来。
以 . 或 _ 开头的目录被忽略,可以用来临时停用一个插件。
Stella 有两条完全不同的触发路径,选错的代价不对称:
用户消息
├─ 唤醒前缀 + @ 机器人 ──→ 指令通路(@filter.command)确定性触发
└─ 普通对话 ──→ Router 判定 ──→ Comes 执行 ──→ 工具通路(@filter.llm_tool)语义触发
决策树:
- 这个功能会发消息、下单、改外部状态、花钱、删东西吗?
→ 必须走
@filter.command。不要做成可路由工具。 - 这个功能是只读、幂等的查询(查天气、查番剧、算字数)吗?
→ 做成
@filter.llm_tool并写capability.toml,用户可以用自然语言问。 - 两者都想要? → 两个都写,共用一个内部实现函数。模板插件就是这个形态。
第 1 条是硬要求,理由是Comes 调工具时不会向用户确认。Router 判定「需要工具」之后,Comes 会在一个隔离的受限 agent 里直接调用,中间没有人类确认环节,也没有「你是不是想……」的追问。所以可路由工具的语义必须是「问一下」,不能是「去做」。
判错一次的代价对比:漏调一次只读工具,用户最多再问一遍;凭空调一次写操作工具,可能真的发出了消息或改了外部状态。规范按后者的代价来定。
bot.py 启动
↓
install_shim() 伪装 astrbot.* 模块
↓
load_all_plugins() 逐目录 import main.py,实例化 Star 子类
↓ (此时事件循环已在运行)
initialize_plugins() 逐个 await plugin.initialize()
↓
capability bootstrap() 读三层声明 → 自动派生 → 打装配日志
三个钩子:
| 钩子 | 何时调用 | 约束 |
|---|---|---|
__init__(self, context, config=None) |
import 后立即 | 在事件循环内,所以起 task 是允许的;但不要做慢 IO |
async initialize(self) |
全部插件实例化之后 | 起后台任务的推荐位置 |
async terminate(self) |
禁用 / 重载 / 退出时 | 超时 5 秒,别在这里做慢 IO 或等网络 |
后台任务必须走 self.context.register_task(coro, desc),不要裸调 asyncio.create_task(...):
async def initialize(self) -> None:
self.context.register_task(self._poll(), "my_poller") # ✅
# asyncio.create_task(self._poll()) # ❌ 卸载时收不回只有登记过的任务在插件卸载与热重载时会被取消。裸 task 在重载后会残留并继续跑,而这不报错——表现是「改了代码重载了,旧行为还在」,或者两份轮询同时打同一个 API。plugin-check 的第 ⑮ 项会扫这个写法并报 warn。
config 参数要允许为 None:没有 _conf_schema.json 的插件、单元测试里直接实例化的插件都会传 None。默认值写在代码里,不要假定 schema 一定被读到了。
@filter.command("名字") 注册的指令,触发条件是唤醒前缀 + 被唤醒两者都满足:
- 唤醒前缀由
ASTRBOT_WAKE_PREFIXES配置,默认/(逗号分隔可配多个); - 群聊里必须 @ 机器人,私聊由
ASTRBOT_COMPAT_ALLOW_PRIVATE控制(默认true)。
所以群里的实际用法是 @Stella /你好。
哪些平台事件会进插件管道,由 astrbot_compat.pipeline.should_dispatch() 把关,它有三道:
- 自身回显不进——机器人自己发的消息不会触发插件;
- 群白名单——只有
ALLOWED_GROUPS里的群会分发,私聊看ASTRBOT_COMPAT_ALLOW_PRIVATE; - 消息必须有内容——判据是「消息段数量 > 0」而不是纯文本非空。
第 3 条的写法有实测理由:QQ 的小程序卡片、图片、纯 @ 这些消息的 get_plaintext() 是空串,用纯文本判据会把它们整批挡在插件之外(2026-08-25 实测),而这类消息恰恰是图片处理、卡片解析类插件唯一的输入。
插件命中后(priority=2)Stella 的主聊天链路(priority=3)就不再介入这条消息,不会再叠一层 LLM 回复。
其他不受唤醒前缀约束的监听器(@filter.regex、@filter.event_message_type)照常可用,但要清楚它们会看到白名单群里的所有消息——在群聊里做全量正则匹配很容易误触发。
这一章是 Stella 与 AstrBot 差别最大的地方。AstrBot 把全部工具的 schema 塞进每次对话请求,让主模型自己挑;Stella 不这么做(理由见 §7),而是先用 embedding 判断「要不要用工具、用哪个」,再把选中的工具交给一个隔离的受限 agent 执行。
后果是:工具能不能被聊天触发,取决于你有没有提供合适的语义原型语料,而不是取决于工具注册成功没有。
@filter.llm_tool("get_weather")
async def get_weather(self, event: AstrMessageEvent, city: str, days: int = 1):
"""查询指定城市未来几天的天气。
Args:
city(string): 城市名,如「杭州」
days(number): 查询天数,默认 1
"""- 签名固定为
async def tool(self, event, <参数...>); - 参数类型只从 docstring 的
Args段读取,不看类型注解。parse_tool_docstring()只认上面这一种格式(名字(类型): 说明,缩进在Args:之下);写错格式的结果是参数静默丢失,模型调用时不传值; - 类型写法支持
string/number/int/boolean/object/array/list[string]这一类; - 在函数签名里给了 Python 默认值不代表参数可选——docstring
Args段里列出的参数一律登记为必填。参数是否必填会影响keywords该不该写(§6.4); - 工具名取
@filter.llm_tool("名字")的参数,省略时取函数名。这个名字就是capability.toml里providers要填的东西,拼错的后果是这条能力整条不进路由——不报错,但python -m deploy capabilities会把它列在「不参与路由」表里、原因写「声明指向的工具不存在」(plugin-check第 ⑤ 项在装之前就能查出来)。
声明文件放在插件根目录,格式与 config/capabilities/*.toml 完全一致:
reviewed = true # 人审闸门,见下
[[capability]]
id = "weather.query"
domain = "information" # 插件自带声明缺省落在 plugin 域,建议显式写
description = "查询天气信息"
examples = [ # Level 1 语义原型语料:写「用户会怎么问」
"明天天气怎么样",
"会不会下雨",
"杭州这几天热不热",
"帮我看下天气",
]
# keywords = ["天气预报"] # Level 0 字面词,可以不写;有必填参数时**不要**写
providers = ["get_weather"] # llm_tools 里的工具名,不是插件名一种格式管三个位置,优先级从高到低:
| 层 | 位置 | 谁维护 |
|---|---|---|
| 用户 | <数据目录>/config/capabilities/*.toml |
部署者 |
| 出厂 | <程序目录>/config/capabilities/*.toml |
Stella 仓库 |
| 插件自带 | <插件目录>/capability.toml |
插件作者 |
| (自动派生) | 无文件,启动时按工具名生成 tool.<name> |
— |
同一个工具被高优先层认领后,低优先层里对应的那条整条跳过(不是跳过单个 provider——半条能力的 examples 与 providers 不再自洽,比缺一条更糟),日志里会写明被哪一层顶掉。所以用户想改插件写歪的 examples,只要在自己的 config/capabilities/ 里放一条同 id 或同工具名的声明即可覆盖,不必改插件源码。
插件层可以整体关掉:ASTRBOT_PLUGIN_CAPABILITIES_ENABLED=false。默认 true——零配置是本规范的意义所在;留这个开关是因为「谁决定我的机器人会调什么」应当能被部署者收回。
只有加载成功的插件的声明会被读取。 import 失败的插件没有登记任何工具,它的声明会造出指向不存在工具的能力——那种能力会照常参与路由竞争、抢走判定间距,最后在 Comes 里必然失败。
reviewed 闸门:reviewed = false 的文件、以及 capability.toml.draft 这种带 .draft 后缀的文件,一律不载入,只在启动日志里记一条「有草稿待审」。这个键缺省视为已审(手写声明不必写它)。它存在的意义见 §12:机器生成的语料在进入路由之前必须有人过目一遍。
没有声明会怎样:工具照常注册、照常可以被显式执行,但不进 registry.routable(),于是三级路由都看不到它——现象是「插件装了、日志说注册成功了、可就是从来不被调用」。启动时会打一条 WARNING 点名这些工具。plugin-check 把这种情况判为 error。
examples 是 Level 1 的语义原型语料。写用户会怎么问,不是写给决策器的指令句。
这是整套设计里最容易写错、也最要紧的一条。对比:
| 写给谁看 | 要求的形态 | |
|---|---|---|
AstrBot 的工具 description |
一个看着全部工具做选择的决策器 | 指令句 + 边界条件:「当用户询问今天更新什么动画时调用」 |
Stella 的 examples |
与用户问句算余弦相似度 | 用户会怎么问:「今天更新什么动画」 |
12 条用例、真实 embedding 的对照实测:
| 原型语料 | 工具假阳 | 首位选错 | 无关工具被执行 | 负样本阈值余量 |
|---|---|---|---|---|
| 工具描述(不写声明时的现状) | 1 | 2 / 5 | 13 次 | −0.024 |
中文问句 examples |
0 | 0 | 0 次 | +0.141 |
负样本余量为负意味着:一句与本工具无关的话,得分比置信线还高——凭空调工具只是时间问题。
写法要点:
- 4~6 句,每句覆盖一种不同的问法(不同措辞、不同句式、有的带地名有的不带)。少于 3 条
plugin-check报 warn; - 全部写成用户的口语问句。出现「当用户」「时调用」「本工具」「用于」这类词的,基本可以确定写成了指令句(第 ⑧ 项 warn);
- 别把同一句话换个标点重复四遍。原型向量是全部 examples 编码后的均值,重复不增加信息,只会让这个能力的中心更偏;
- 同域的能力之间要能区分开。原型彼此差不到 0.06 时,路由基本是在掷骰子——这个数会被
plugin-check第 ⑫ 项算出来。
写不动的时候可以让 plugin-scaffold 生成第一版再自己改(§12)。
keywords 是 Level 0 的确定性字面词:命中即拍板执行,没有二次判定。所以它的取舍原则是宁缺勿滥。
四条规则:
- 写名词短语,至少 3 个字。「新番」不如「番剧推荐」——短词会串进无关句子;
- 绝不从
examples里切词。中文没有词边界,从「会不会下雨」里切出来的候选既有「下雨」也有「不会」,后者会命中几乎任何句子(「我不会用这个软件」→ 去查天气)。滑窗切词能切出好词,但一定同时切出坏词,而坏词的代价是凭空调一次工具; - 不要与别的能力的
examples串味。一个泄漏的关键词就是一次高代价的工具假阳; - 工具有必填参数时不要写
keywords。Level 0 只做字面命中、不抽取参数,拍板执行只会让 Comes 去猜那个必填值。
出厂声明里正反两例都有:anime.search(必填 keyword)不给 keywords;video.dynamics 破例给了,因为它的参数有合理默认值。按这个标准取舍。
不写 keywords 完全没问题——Level 1 照样能路由到,只是多花一次 embedding。
工具返回值不会原样进入 Stella 的人格 prompt。链路是:
工具 return → 受限 agent 的 8192 窗口 → summarizer 摘要(≤ COMES_SUMMARY_MAX_CHARS,默认 300 字符) → Stella 的 prompt
两个后果:
- 别甩几千字 JSON。 它先要挤进受限 agent 自己的 8192 token 窗口,超了就是截断,截断处之后的内容等于没返回;
- 返回值要写成人话。 最终进 prompt 的是那 300 字符的摘要,摘一段结构化数据的效果远不如摘一句「杭州明天多云,18~26℃」。
返回 None 表示「没有返回值或已经直接回复用户了」。
失败要抛异常,不要 return "查询失败:……"。
# ✅
if resp.status_code != 200:
raise RuntimeError(f"天气 API 返回 {resp.status_code}")
# ❌
if resp.status_code != 200:
return "查询失败:接口超时了"为什么这条不是风格问题:抛出的异常会被 agent.execute_tool 包成 f"error: {e}",summarizer.is_error() 靠开头的 error: 判定失败。返回一串普通文字的话,三件事同时发生——
- 那串字不以
error:开头 → 被当成成功输出; - 于是它被贴上「刚刚查到的信息(真实数据,回答时以此为准)」进 Stella 的 prompt → Stella 把失败文案当事实转述给用户;
- provider 健康度记不到这次失败 → 连续失败退避(
COMES_PROVIDER_FAILURE_THRESHOLD次后退避COMES_PROVIDER_RECOVER_SECONDS秒)永远不触发,一个坏掉的工具会被反复调用。
异常信息会进日志,所以写清楚是什么坏了:raise RuntimeError("和风天气 403,API key 可能过期") 比 raise RuntimeError("失败") 有用得多。
工具执行超时是 COMES_TOOL_TIMEOUT,默认 60 秒;整个任务是 COMES_TASK_TIMEOUT,默认 90 秒。
这条链路挂在聊天主链路上——用户正在群里等回复。60 秒是上限不是预算,一个体感正常的工具应该在 5 秒内返回。要做长任务,用「立刻返回一句『在查了』+ 后台 register_task + 完成后 StarTools.send_message 主动发」的形态,别把用户挂在同步等待上。
没有必填参数的工具会跳过一次模型往返,由 Comes 直接调用(COMES_DIRECT_CALL_NO_ARGS=true,默认开),省一次 LLM 调用与它的延迟。
这意味着无参工具的副作用会更早发生,进一步说明 §3 那条「写操作不做成工具」的必要性。
本文所说的“无模型”特指聊天生成、Agent/Comes 生成和 Level 2 Router fallback 不可用,不包括 embedding 模型。只要 embedding 服务仍可用,Level 1 语义路由仍会运行;Level 0 关键词规则始终不需要模型。Level 2 不能在生成模型缺席时强行启用。
要让有参查询(例如“查东京明天天气”)在无聊天模型时自动完成,能力声明需要提供确定性输入契约。input_schema 会与工具的 JSON schema 合并,支持 regex/pattern、enum、default 和基础类型转换:
[[capability]]
id = "weather.query"
providers = ["get_weather"]
[capability.input_schema]
required = ["city", "date"]
[capability.input_schema.properties.city]
type = "string"
regex = "查(?P<city>[^,。??]+?)(?:今天|明天|后天)?天气"
[capability.input_schema.properties.date]
type = "string"
regex = "(今天|明天|后天)"
default = "今天"只有在能力已确定、provider/tool 唯一、必填输入完整且校验通过时,Comes 才会直接调用工具并把安全摘要直接回复给用户,不经过聊天生成。缺参、歧义或校验失败时不会让 Agent 猜参数,而是回复需要补充的信息;工具内部失败只会回复通用不可用提示,不会泄漏原始 JSON、异常栈或模型内部文本。
一条 capability 可以有多个 providers(比如两个不同的天气插件)。选择顺序按 priority,失败的 provider 会被记账并短暂退避,期间自动切到下一个。
所以多写一个 provider 是真的有容错价值的;但前提是 §6.6——失败必须抛异常,否则退避永远不触发,容错等于没有。
Stella 的工作窗口是 8192 token,这个数字决定了整套工具设计。
| AstrBot | Stella | |
|---|---|---|
| 工具怎么被选中 | 全部工具 schema 进每次对话请求,主模型自己挑 | embedding 比对原型向量,只把选中的交给受限 agent |
| N 个工具的上下文成本 | 每次请求 N × 60~120 token,线性涨 | N 个原型向量,一次性编码 + 按注册表版本落盘缓存,对话窗口不涨 |
| N 变大时的代价 | 装满插件后正常对话挤不进窗口 | 同域工具混淆概率上升 |
两个必须记住的结论:
- 工具描述与原始返回值都不进人格 prompt。 你写在
description里的话不会影响 Stella 的说话方式,也别指望通过描述给 Stella 传达指令; - 代价换了形态,没有消失。 装得越多,同一语域里的能力越容易互相抢——所以 §6.3 的区分度要求不是洁癖,它是这套设计的成本所在。
Star.html_render(tmpl, data) / text_to_image(text) / t2i(...) 由本地 Chromium 出图,首次需要出图时会在后台下载约 270MB 的浏览器内核,期间渲染不可用。
两条与上游不同的地方,插件必须适配:
- 返回本地文件路径,不是 URL。
return_url=True被刻意忽略——上游那个分支返回的是远程 t2i 服务的 URL,而 Stella 不把聊天内容发出去。拿到路径后用event.image_result(path)或chain.file_image(path)都正常。不要用url_image(path),那个函数收到本地路径时会抛ValueError(plugin-check第 ⑭ 项会扫源码里的url_image(); - 不可用时返回空串,不抛异常。 没装浏览器、正在后台下载、模板报错,都返回
""。所以插件必须有降级分支:
img = await self.html_render(TMPL, data)
if img:
yield event.image_result(img)
else:
yield event.plain_result(self._render_as_text(data)) # 必须有选择返回空串而不是抛异常,是因为插件普遍会把渲染包在 try 里再重试,抛异常只会被吞掉然后重试三次都失败;空串能让 if img: 这种最常见的写法自然走进降级分支。
用户可配项:_conf_schema.json 声明,self.config 读取。
{
"max_items": {"description": "max_items", "type": "int", "hint": "一次最多返回几条", "default": 10}
}limit = 10 if self.config is None else int(self.config.get("max_items", 10))始终用 .get(键, 默认值) 并处理 self.config is None——单元测试与没装 schema 的场景都会传 None。
数据落盘:
| 用途 | API | 位置 |
|---|---|---|
| 任意文件 | StarTools.get_data_dir() |
<数据目录>/data/plugin_data/<插件名>/ |
| 小 KV(异步) | await self.put_kv_data(k, v) / get_kv_data / delete_kv_data |
同目录下的 kv.json |
| 小 KV(同步) | self.set_data / get_data + self.save_data() |
同上(set_data 只改内存,必须显式 save_data) |
不要往插件自己的安装目录里写数据——升级会整个替换那个目录。
群与空间的分界:Stella 有「共享空间」概念(多个群共用一份记忆与人格),但插件拿不到 group_shared_space。插件视野里只有 event.get_group_id()。要按群隔离数据,就自己拿 group_id 拼键:
await self.put_kv_data(f"subscriptions:{event.get_group_id()}", items)这是刻意的:空间归属是记忆系统的语义,插件按它分组会在管理员合并 / 拆分空间时产生一堆无主数据。
Stella 的默认姿态是不把聊天内容发出去:判断该不该用工具、压缩工具结果、渲染卡片全在本地完成。插件是唯一被允许出网的环节,所以出网的插件必须自己说清去哪儿、干什么:
# metadata.yaml
stella:
egress:
- host: api.weatherapi.com
purpose: 查询公开天气数据,只发送用户提到的城市名这是披露契约,不是沙箱。 我们不拦未声明的请求,规范里必须把这句写明白——stella.egress 的作用是让部署者在装插件之前能看见「这个插件会把什么发到哪里」,靠的是社区约定与 plugin-check(第 ⑯ 项:import 了 httpx/aiohttp/requests 却没写 egress → warn),不是技术强制。
两条附带要求:
purpose写发送什么,不只写「查询数据」。「只发送城市名」和「发送用户原话」对部署者是两回事;- 不要把群聊原文、用户 ID、消息 ID 发给第三方服务。需要这么做的功能应当在
purpose里明确写出来,让部署者自己决定装不装。
兼容层是重新实现。三种状态:
① 已实现,行为对齐上游
Star的全部生命周期钩子、指令参数解析、KV 存储@filter.command/command_group/regex/llm_tool/event_message_type/permission_type/platform_adapter_type/custom_filter与全部on_*钩子、GreedyStrAstrMessageEvent的取值方法(get_sender_id/get_sender_name/get_group_id/get_messages/get_message_str/is_admin/is_private_chat…)与结果构造(plain_result/image_result/chain_result/make_result)MessageChain的链式构造、MessageEventResult的stop_event/continue_event- 消息组件:
Plain/Image/Record/Video/File/Face/At/AtAll/Reply/Poke/Json/Music/Share/Location/Dice/RPS/Shake/Contact/Forward/Unknown Context:get_registered_star/get_all_stars/send_message/register_task/get_platform/activate_llm_tool系列 / provider 系列 /conversation_manager/persona_manager/register_llm_toolStarTools:send_message/get_data_dir/activate_llm_tool系列AstrBotConfig、sp(偏好存储)、FunctionTool/ToolSet
② 降级实现,行为与上游不同
| API | 差别 | 详见 |
|---|---|---|
html_render / text_to_image / t2i |
忽略 return_url,返回本地路径;不可用时返回空串 |
§8 |
@filter.llm_tool 注册的工具 |
注册成功 ≠ 能被聊天触发,需要 capability.toml |
§6.2 |
metadata.yaml 的 astrbot_version |
不匹配只告警,仍然加载 | §15 |
requirements.txt |
默认不自动 pip install,只在日志点名 |
§2 |
Context.llm_generate / tool_loop_agent / get_current_chat_provider_id |
生成模型不可用时抛 StellaCompatModelUnavailable;普通 command/regex/event 插件仍可运行 |
— |
③ 抛 StellaCompatNotSupported
| API | 为什么没有 |
|---|---|
StarTools.get_db / Context.get_db |
Stella 的库是记忆系统的私有 schema,不对插件开放 |
StarTools.get_event_queue / Context.get_event_queue |
事件分发走 NoneBot,没有上游那条队列 |
StarTools.get_config |
没有上游那份全局配置对象 |
StarTools.register_web_api / Context.register_web_api |
Stella 没有对外 HTTP 服务(状态接口只回环、只读) |
Context.kb_manager / subagent_orchestrator / knowledge_db_manager |
知识库与子 agent 编排未实现 |
astrbot.api.platform.Platform / register_platform_adapter |
只支持 OneBot V11 一个平台 |
astrbot.api.html_renderer / astrbot.api.agent |
用 Star.html_render / Comes 代替 |
Node / Nodes 作为普通消息段发送 |
合并转发要走 send_group_forward_msg,不是消息段 |
组件的 convert_to_file_path()(来源无法解析时) |
拿不到源文件就没有路径可返回 |
第 ③ 类里 Context 的三个属性抛的是 StellaCompatUnsupportedAttribute,它同时是 AttributeError 的子类——所以插件用 hasattr(ctx, "kb_manager") 做特性探测会得到 False 并优雅降级,而直接访问仍然抛出可识别的异常。这个双重继承是刻意的。
完整流水:
python -m deploy plugin-scaffold <插件目录> # 生成 capability.toml.draft 并量化(可选)
# → 人审:改 examples、按需取用注释里的候选 keywords、reviewed = true、去掉 .draft 后缀
python -m deploy plugin-check <插件目录> # 16 项检查,有 error 时退出码非零
python -m capability.router.benchmark # 路由基准,确认四类路由错误没变差plugin-check 会 import 并实例化你的插件(和启动时做的事同类),输出里会明确写「已执行该插件代码」。--json 供 GUI 使用:报告走 stdout、日志走 stderr。
16 项检查:
| # | 检查项 | 级别 |
|---|---|---|
| ① | 缺 main.py / 目录里是未解压的压缩包 |
error |
| ② | import 失败 / 没有 Star 子类 / initialize() 抛异常 |
error |
| ③ | requirements.txt 里的包在当前环境缺失 |
error |
| ④ | 有 @llm_tool 工具未被任何声明的 providers 认领 |
error |
| ⑤ | 声明的 providers 出现不存在的工具名 |
error |
| ⑥ | 只有 .draft / reviewed = false |
error |
| ⑦ | examples 少于 3 条 |
warn |
| ⑧ | examples 疑似指令句 |
warn |
| ⑨ | keywords 串进了别的能力的 examples |
warn |
| ⑩ | keywords 出现短于 3 字的词 |
warn |
| ⑪ | 工具有必填参数却给了 keywords |
warn |
| ⑫ | 同域能力原型分离度不足 / 负样本余量为负 | warn |
| ⑬ | 能力 id 或工具与用户 / 出厂层撞名 | info |
| ⑭ | 源码出现 url_image( |
warn |
| ⑮ | 裸 asyncio.create_task( 而未走 context.register_task |
warn |
| ⑯ | import 了 httpx/aiohttp/requests 但未声明 stella.egress |
warn |
发布前的最低要求是零 error。warn 是「请复核」而不是「必须改」——第 ⑩ 项在出厂声明里就有一个经实测确认的破例(anime.schedule 的「放送」只有两个字,靠它把一句 0.641 分的问句从 0.70 置信线下救回来)。判断的是你,不是检查器。
plugin-scaffold 的开关:--endpoint <槽> 换模型槽(默认走 ROLE_EXTRACT 那一档,见 core/llm/registry.py)、--dry-run 只打印不落盘、--force 覆盖已有草稿、--measure 跳过生成、只对现成的声明(capability.toml 或 .draft)重算一遍量化报告——人审时改完 examples 拿它复算,不必再花一次模型调用。它和 plugin-check 一样会 import 并实例化你的插件:枚举 @llm_tool 只有这一个办法。
关于生成:离线生成一份草稿、人审之后才生效是被支持的;运行期无声地从工具描述生成 examples 灌进内存不被支持(那正是 ROUTER_ROUTE_AUTO_CAPABILITIES 默认关闭的原因)。差别在于有没有文件、有没有人过目、有没有量化基准,reviewed 闸门就是这条分界的实现。
生成器的输入按信息量排序:插件 README.md → @command 的指令名与说明 → @llm_tool 的 docstring Args → 工具 description 与工具名 → metadata.yaml。只喂工具描述正是 −0.024 那一行的成因。生成后会直接用真实 embedding 打一份报告(同域分离度、每条 example 与本能力原型的余弦、负样本余量),所以「生成质量无法验证」在有文件、有审阅、有基准的前提下不成立。
看日志。 插件相关的启动信息全在 logs/boot_debug.log:发现了哪些目录、加载成功还是失败、失败原因、能力装配的分层计数、哪些工具没有声明。路由判定与工具结果在 logs/stella_thought_logs.md。
「插件装了但从来不被调用」 的排查顺序:
boot_debug.log里有没有这个插件?没有 → 目录名以./_开头,或者压缩包没解压;- 加载失败?→ 看失败原因,多数是缺依赖(
requirements.txt默认不自动装); - 加载成功但工具从不触发 → 十有八九是缺
capability.toml,日志里那条 WARNING 会点名; - 有声明但还是不触发 →
providers里的工具名拼错了,或者被高优先层顶掉了。plugin-check第 ⑤ / ⑬ 项直接给答案;已经装上跑起来的话,python -m deploy capabilities会把拼错的那条写成「声明指向的工具不存在」。
热重载由 ASTRBOT_PLUGIN_HOT_RELOAD_ENABLED 控制,默认关闭——它会重新 import 并执行插件代码,比只读查询大一档,不该在没人明确打开时可用。打开后由群内管理员触发:
@Stella 重载插件 astrbot_plugin_bilibili
权限沿用主动发言开关那套(PROACTIVE_TOGGLE_ADMINS 白名单,或群主/管理员);非管理员发这句不会有任何反应。选群内命令而不是给状态接口开一个 POST,是因为那个端点是只读的,加一条能触发任意插件 re-import 的写入口是比只读端点大一档的安全步骤。
它做的事:跑 terminate()(5 秒超时)→ 取消该插件经 register_task 登记的后台任务 → 摘掉它的 handler(含定义在子模块里的)、函数工具、能力声明与工具归属 → 清掉 sys.modules 里的插件包与磁盘上的 __pycache__ → 重新加载 + initialize() → 重跑三层声明与自动派生,并在后台重算 Router 的原型向量。
__pycache__ 那步不是顺手打扫:.pyc 的有效性只按「源文件 mtime 整秒 + 字节数」判定,所以「同一秒内改了一个字符」这种编辑(调试时改常量、改开关,恰恰最常见)会命中旧字节码——重载报成功,跑的还是旧代码。
清不掉的是这些:
- 裸
asyncio.create_task()起的后台任务(这就是 §4 要求走register_task的原因) - 插件起的线程、注册的全局钩子、monkeypatch、第三方库的模块级状态
- 已经被别处持有的旧实例引用
所以热重载的定位是调试便利,不等于重启。怀疑状态不干净就重启——这句话也会跟在每一条重载成功的回复后面。
新代码 import 失败时重载返回失败并把原因报回群里,不回滚:旧模块已经从 sys.modules 里摘掉了,没有可回滚的东西。改完再重载一次即可。
ASTRBOT_PLUGIN_HOT_RELOAD_WATCH(默认关闭,需与主开关同时打开)会监视已加载插件目录里 *.py 与 capability.toml 的 mtime,改完存盘就自动重载。调试最省事,但「自动」在生产上危险:一次误存盘就会在群里跑一遍重新 import。轮询间隔由 ASTRBOT_PLUGIN_HOT_RELOAD_WATCH_INTERVAL(默认 5 秒)控制。
三个入口、同一份数据源:
- 群里问「你能做什么」「有什么功能」——按域分组列出可路由的能力,末尾一行说明有多少插件工具因为没配声明而不会被自动触发。普通群友可查;来源层、provider 健康度、未声明工具的具体名单属于排查信息,只对管理员显示;
python -m deploy capabilities [--json]——表格形式:哪些能被聊天触发、哪些不能、各自来自哪一层、哪个 provider 正在退避;- GUI「插件」页——按插件重新索引的同一份 payload:左边列出装了哪些插件(每项一个圆点与一句结论:加载失败 / 已停用 / N 个工具未声明 / 正常),点进去才看这个插件的指令与工具。工具那一列直接回答「有没有被能力声明认领」——绿点=已认领、聊天里会自动触发,灰点=没有任何声明认领它,只能显式调用;工具不存在 / 已停用 / 正在退避也标在同一行。没解压的压缩包、只有
capability.draft.toml、reviewed = false都会在对应插件上点名。「运行状态」页的「复制诊断信息」仍会带上「可路由 N / 共 M / 未声明工具」这三个数。
payload 只放结构化字段(id、domain、来源层、是否可路由、provider 工具名、工具是否真的存在、退避状态、examples 条数),不含 description 与 examples 原文——状态接口有「响应体不含凭据与聊天内容」的硬约束,而自由文本是唯一可能夹带 URL 或密钥的字段。原文在本地直接读那三层 TOML 就有。
metadata.yaml的astrbot_version约束只告警不拦。兼容层的声称版本是ASTRBOT_COMPAT_VERSION(默认4.27.0),它表达的是「API 表面对齐到哪个上游版本」,而不是「行为逐字等价」——按它硬拦会把大量实际可用的插件挡在外面;version字段沿用上游惯例,可以带v前缀(version: v1.6.4);缺失时按0.0.0处理;- 本规范的版本是 v1.0。 后续版本只以加法方式演进:新增可选字段、新增检查项。已有字段的语义不会在小版本里改变。
capability.toml的格式与config/capabilities/*.toml保持一致这一点是承诺而不是巧合——它意味着三层里任何一层的写法都能直接搬到另一层。
| 文档 | 内容 |
|---|---|
| 能力系统 | Router 三级级联、Comes 执行层、注册表分层的运行期细节 |
| 架构说明 | 目录结构、消息处理流程、AstrBot 兼容层在整体里的位置 |
| 配置参考 | 本文提到的全部配置项 |
| 模板插件 | 可以直接拷走的完整示例 |
插件可收到群与私聊事件;需要群号的功能先按事件类型检查,不把私聊的 storage_session_id 当作真实群号。不要从昵称、正文或模型返回值推导用户身份/收件人。能力工具仍应只读幂等, 命令副作用走显式命令权限链;长任务委派交给 Cometa 的受理与回投合同。 验证范例见 模板插件。