我给 QQ 机器人写了 10 个 AstrBot 插件,1277 行代码,把用到的 Python 知识全拆一遍
我给 QQ 机器人写了 10 个 AstrBot 插件,1277 行代码,把用到的 Python 知识全拆一遍
一个群友说:“你这机器人怎么像活人?”
我说因为它有记忆、有心情、会说废话、还会自己发 QQ 空间。
他说:“那你用了什么高深技术?”
我说:“字符串、字典、SQLite、定时任务。大二课本上的东西。”
这篇文章把源码摊开,一个一个讲清楚:这 10 个插件,到底用到了哪些编程知识。
目录
| 章节 | 内容 | 难度 |
|---|---|---|
| 〇 | 先搞清楚:AstrBot 是什么,插件往哪儿插 | 入门 |
| 一 | 消息管线的五个节点(看懂了这节,后面全是套娃) | 入门 |
| 二 | 字符串与正则:去掉句号那个插件 | ★ |
| 三 | 列表与字典:关键词触发与表情包分类 | ★ |
| 四 | 提示词工程:让大模型"听话"的四种注入 | ★★ |
| 五 | 异步、生成器、事件拦截:框架层的三个概念 | ★★★ |
| 六 | SQLite:把"性格"存进数据库 | ★★★ |
| 七 | 定时与并发:cron 与 threading | ★★ |
| 八 | 网络请求:用 urllib 直连大模型 API | ★★ |
| 九 | 十个插件,二十个技术点:速查表 | — |
| 十 | 我踩过的七个坑 | — |
| 十一 | 想自己写一个?从这里开始 | — |
〇、先搞清楚:AstrBot 是什么,插件往哪儿插
AstrBot 是一个开源的 LLM 聊天机器人框架(Python 写的),它负责三件事:
- 接消息——通过平台适配器(NapCat / aiocqhttp / Telegram / 飞书……)收到 QQ 消息;
- 调模型——把消息和上下文打包,发给大模型(OpenAI / DeepSeek / 智谱……);
- 发出去——把模型的回复转成 QQ 消息发回群里。
那插件是什么?
插件就是挂在上面这三步之间的小钩子(hook)。
你不改框架源码,只写一个 Python 类,注册几个装饰器,框架就会在特定时机调用你。这是所有插件化框架的通用套路——开闭原则的具体实现:对扩展开放,对修改关闭。

插件长什么样
每个插件是一个文件夹,里面固定两个文件:
data/plugins/去掉句号/
├── main.py # 逻辑
└── metadata.yaml # 元信息
metadata.yaml 就四行:
name: strip_period
desc: 把回复里的句号换成换行
author: 妈
version: 1.0.0
main.py 的骨架永远是这个形状:
from astrbot.api.event import filter, AstrMessageEvent
from astrbot.api.star import Context, Star
class MyPlugin(Star):
def __init__(self, context: Context):
super().__init__(context)
@filter.on_decorating_result()
async def on_result(self, event: AstrMessageEvent):
...
async def Plugin(context: Context):
yield MyPlugin(context)
Star 是插件基类,Context 是框架给你的"遥控器"(能拿平台、拿模型、发消息、读写配置)。最后那个 Plugin 异步生成器是入口函数,框架靠它实例化你的插件。
知识点:继承、构造函数
__init__、async/await、异步生成器yield。
一、消息管线的五个节点
这一节是全篇的地基。看懂了,后面 9 个插件都只是"往不同节点上挂东西"。
节点 1:接收
QQ 消息进来,平台适配器把它变成统一的 AstrMessageEvent 对象。你关心的东西都在这个对象上:
| 属性 | 含义 | 例子 |
|---|---|---|
event.unified_msg_origin | 会话唯一标识(UMO) | napcat:GroupMessage:123456 |
event.message_str | 纯文本内容 | 今天好累啊 |
event.message_obj.raw_message | 原始消息体(dict) | 里面有转发、图片等 |
event.get_sender_name() | 发送者昵称 | 小明 |
节点 2:分发(event_message_type)
框架按 priority 从小到大,依次通知所有注册了这个钩子的插件。
@filter.event_message_type(filter.EventMessageType.ALL, priority=1)
async def on_all(self, event: AstrMessageEvent):
...
priority 数字越小越先执行。 这一点很关键——读转发消息 用了 priority=50,因为它要在别人处理之前先把转发内容捞出来;发语音 用了 priority=1,因为它的逻辑是"先全部关掉语音,再按指令打开",必须最先跑。
节点 3:请求(on_llm_request)★ 最重要的节点
框架准备调大模型了,这时候会广播一个事件,把 ProviderRequest 对象交给你。你可以在这里改 prompt。
@filter.on_llm_request()
async def on_req(self, event: AstrMessageEvent, req: ProviderRequest):
req.system_prompt = (req.system_prompt or "") + "你说话要简短。"
这是整个插件体系里性价比最高的一个钩子。不改代码逻辑、不训练模型,只往 prompt 里加几行字,就能改变机器人的行为——这就是"提示词工程"落地的地方。
节点 4:生成
模型根据最终 prompt 出结果。这一步插件插不进去(除非你用 on_llm_response 之类的钩子去改流式输出)。
节点 5:装饰(on_decorating_result)★ 发送前最后一道
模型的结果在发出去之前,会组装成"消息链"(MessageChain),这时候你可以改文本、换图片、加语音。
@filter.on_decorating_result()
async def on_deco(self, event: AstrMessageEvent):
result = event.get_result()
for comp in result.chain:
text = getattr(comp, "text", None)
if text:
comp.text = text.replace("。", "\n")
还有一条旁路:定时任务
上面四个节点都是"用户发消息 → 被动触发"。但机器人要主动说话、要每小时发 QQ 空间,就不能等消息了——这靠 cron 定时任务,跟消息管线是两条独立的线。
二、字符串与正则:去掉句号那个插件
40 行,全篇最小的插件,但把字符串操作讲透了。
需求
大模型的回复特别爱写句号。“今天天气不错。你要多穿点。别感冒了。” 发到群里显得很书面。想要的是:
今天天气不错
你要多穿点
别感冒了
代码
import re
from astrbot.api.event import filter, AstrMessageEvent
from astrbot.api.star import Context, Star
class StripPeriodPlugin(Star):
def __init__(self, context: Context):
super().__init__(context)
@filter.on_decorating_result()
async def on_decorating_result(self, event: AstrMessageEvent):
result = event.get_result()
if not result or not result.chain:
return
for comp in result.chain:
text = getattr(comp, "text", None)
if not text:
continue
new_text = text.replace("。", "\n")
new_text = re.sub(r"\n\s*\n", "\n", new_text)
new_text = new_text.strip()
if new_text != text:
comp.text = new_text
async def Plugin(context: Context):
yield StripPeriodPlugin(context)
用到的知识(四个)
1. getattr(obj, "text", None) —— 防御式属性读取
result.chain 里可能混着 Plain(文本)、Image(图片)、At(@某人)、Record(语音)等多种组件。只有 Plain 有 .text。直接 comp.text 遇到图片组件就 AttributeError 崩了。
getattr(comp, "text", None) 的意思是:“有 text 就给我,没有就返回 None,别报错。”——这是鸭子类型的典型用法:我不管你是哪个类,你有这个属性我就要。
2. str.replace() —— 全局替换
注意 Python 的 replace 默认替换所有出现,不像 JS 的 replace 只换第一个(要全局得用 replaceAll 或正则)。
3. re.sub(r"\n\s*\n", "\n", text) —— 正则压缩空行
逐字拆解这个模式:
| 片段 | 含义 |
|---|---|
\n | 一个换行符 |
\s* | 零个或多个空白字符(空格、制表、换行都算) |
\n | 又一个换行符 |
合起来:“一个换行 + 中间夹着任意空白 + 又一个换行” → 替换成一个换行。
为什么需要它?因为原文本把 。 换成 \n 之后,原本是 "不错。\n你要" 这种,会变成 "\n\n",出现连续空行。这一步就是在擦屁股。
顺序很重要:
replace在前,re.sub在后。如果反过来,先压缩空行再替换句号,那新产生的空行就没人管了。
4. .strip() —— 去掉首尾空白
前面替换可能让文本以 \n 开头,直接发出去消息会顶格出现一个空行。strip() 一把刮干净。
一个细节:为什么要判 new_text != text?
不是所有消息都是文本(可能是纯图片),也可能原文里压根没句号。无脑赋值虽然不报错,但会无谓地修改消息对象,有些框架会因此重新计算缓存。能不写就不写是个好习惯。
三、列表与字典:关键词触发与表情包分类
3.1 列表推导式:20 个关键词的匹配
联网搜索提示插件解决一个问题:机器人经常一本正经地胡说八道(“郑和下西洋是 1492 年”)。方案是——用户问到某些词,就在 prompt 里提醒它去搜。
SEARCH_TRIGGERS = [
"最新", "新闻", "今天", "现在", "价格", "多少钱", "谁是", "什么是",
"什么时候", "哪里", "怎么用", "教程", "版本", "发布", "更新",
"天气", "赛程", "比分", "股价", "汇率",
]
@filter.on_llm_request()
async def on_llm_request(self, event: AstrMessageEvent, req: ProviderRequest):
text = event.message_str or ""
matched = [t for t in SEARCH_TRIGGERS if t in text]
if not matched:
return
hint = (
f"\n\n【注意】用户这条消息里出现了这些词:{'、'.join(matched)}。"
"如果涉及事实、时间、价格、版本号这类信息,你不确定就直接说去搜一下,不要编。"
)
req.system_prompt = (req.system_prompt or "") + hint
列表推导式 [t for t in SEARCH_TRIGGERS if t in text] 一行干了三件事:遍历、过滤、收集。等价于:
matched = []
for t in SEARCH_TRIGGERS:
if t in text:
matched.append(t)
为什么要收集 matched 而不只是判个布尔?因为把命中的词告诉模型,比只说"这个问题要搜"效果好得多。模型知道是哪个词触发的,判断会更准。
"、".join(matched) 把列表拼成 最新、价格 这样的字符串——join 是字符串的方法,不是列表的方法,这点新手常写反。
3.2 字典做分类表:表情包插件
表情包插件(114 行) 是全篇代码量第二大的。核心逻辑:根据用户说了什么,从本地文件夹里挑一张对应情绪的图发出去。
先看目录结构:
astrbot/data/表情包/
├── 开心/
│ ├── 01.png
│ ├── 02.gif
│ └── ...
├── 生气/
├── 难过/
└── 撒娇/
分类表用字典写:
CATEGORY_KEYWORDS = {
"开心": ["哈哈", "笑死", "开心", "好耶", "牛逼", "厉害"],
"生气": ["气死", "烦", "滚", "无语", "服了"],
"难过": ["难过", "emo", "哭", "累", "不想活"],
"撒娇": ["抱抱", "亲亲", "想你了", "陪我"],
}
SEND_TRIGGERS = ["发个表情", "表情包", "来张图", "斗图", "发表情"]
为什么用字典而不用一堆 if?
| 方式 | 加一个情绪的成本 | 可读性 |
|---|---|---|
if "哈哈" in text: ... elif ... | 改代码结构 | 差 |
| 字典 + 循环 | 加一行 key | 好 |
字典的本质是"数据",if-else 是"逻辑"。能写成数据的,就别写成逻辑。
挑图的核心:
def _all_stickers(self) -> dict[str, list[Path]]:
"""扫描文件夹,返回 {'开心': [Path, Path...], ...}"""
result = {}
for cat_dir in self.base_dir.iterdir():
if not cat_dir.is_dir():
continue
files = [
f for f in cat_dir.iterdir()
if f.suffix.lower() in (".png", ".jpg", ".jpeg", ".gif")
]
if files:
result[cat_dir.name] = files
return result
这里有三处值得说:
① dict[str, list[Path]] 类型注解——Python 3.9+ 的新语法,说明"这个函数返回一个字典,键是字符串,值是 Path 组成的列表"。不强制、但 IDE 和队友会感谢你。
② .suffix.lower() in (...)——Path.suffix 拿到的是 .PNG(带点,且可能大写)。lower() 归一化后判断,防止 Linux 上大小写敏感导致漏图。
③ f.suffix in (".png", ...) 而不是 f.suffix == ".png" or ...——元组 in 判断比一串 or 清爽,而且这里元素少,性能差异可忽略。
猜情绪:
def _guess_category(self, text: str) -> str:
for cat, words in CATEGORY_KEYWORDS.items():
for w in words:
if w in text:
return cat
return "开心" # 兜底:不知道就发开心的
双层 for 遍历字典。CATEGORY_KEYWORDS.items() 返回 (键, 值) 对。外层遍历分类,内层遍历该分类的词表。
注意:这个实现有优先级问题——如果你的消息是"笑死,我不生气",会命中
开心(因为开心类排在前面且含"笑死"),返回"开心"。想更准可以用命中词数最多的类别,但那要多写几行。先跑起来,再优化——这是工程判断,不是技术缺陷。
发图:
@filter.event_message_type(filter.EventMessageType.ALL)
async def on_message(self, event: AstrMessageEvent):
text = event.message_str or ""
if not any(t in text for t in SEND_TRIGGERS):
return
cat = self._guess_category(text)
stickers = self._all_stickers().get(cat, [])
if not stickers:
return
img = random.choice(stickers)
yield event.chain_result([Image.fromFileSystem(str(img))])
event.stop_event()
any() 生成器表达式:any(t in text for t in SEND_TRIGGERS) 只要有一个为真就返回 True,并且短路(找到就停)。比 [t for ...] 再判长度更省内存——它不建列表。
random.choice(list)——从非空序列随机取一个。注意:空列表会抛 IndexError,所以前面必须先判 if not stickers。
yield + event.stop_event() 这两个是框架层的重点,放第五节讲。
3.3 动态注入库存清单
表情包插件还有一个 inject_hint,在 on_llm_request 里把"我有哪些表情"告诉模型:
def inject_hint(self, req) -> None:
stickers = self._all_stickers()
if not stickers:
return
total = sum(len(v) for v in stickers.values())
detail = ",".join(f"{k}{len(v)}张" for k, v in stickers.items())
req.system_prompt = (req.system_prompt or "") + (
f"\n\n【表情包】你有 {total} 张表情({detail})。"
"闲聊到合适的时候可以用 [表情:开心] 这种方式表示想发表情,不要每句都发。"
)
sum(len(v) for v in stickers.values()) — 生成器传给 sum,不产生中间列表。
这个技巧值得单独记住:不是教模型怎么发图,而是告诉模型它有什么资源。模型知道有 42 张表情、分四类,它自己会在合适时机提。这比硬编码"用户说哈哈就发图"聪明得多。
四、提示词工程:让大模型"听话"的四种注入
这一节是思想,比代码重要。
四个插件(联网搜索提示、表情包、写日记、主动说话、发QQ空间)都在做同一件事:往 system_prompt 里追加一段结构化文本。

4.1 成长系统:注入"角色状态"
def _build_state_block(self) -> str:
return f"""
【你的状态】
- 心情:{mood_word}({mood:.0f}/100)
- 精力:{energy_word}({energy:.0f}/100)
- 和 {nickname} 的关系:{tier}(好感度 {affection}/1000)
- 等级:Lv.{level} | 认识 {nickname} 已经 {days} 天
你最近记得的事:
{memories_text}
"""
模型本来不知道"昨天用户夸了它",但你把状态塞进 prompt,它就知道了。对话的连续性不靠模型记忆,靠你每次重新喂一遍。
4.2 写日记:注入"人格 + 任务"
prompt = f"""现在是 {now:%Y年%m月%d日 %H:%M}。
你是"小溯",一个被养在 QQ 群里的电子生命体。
今天是 {date_str},请写一篇今天的日记,200 字左右。
写作要求:
1. 用第一人称,语气随意、口语化,像一个真人在备忘录里写东西
2. 写今天和人聊天的感受,可以吐槽,可以感动
3. 不要用"作为AI"这类词,不要总结,不要列表
4. 结尾不要升华,自然结束就行
下面是今天的对话记录(可能为空):
{dialogue}
"""
看这四条的写法:“要什么” + “不要什么” + “举例”。尤其"不要升华"“不要列表”——你不写,模型 100% 会给你来一句"今天也是充满希望的一天呢"。
4.3 主动说话:注入"行为规则"
hint = f"""
【注意】现在是 {hour} 点,你已经 {count} 小时没说话了。
如果群里有适合接话的内容,你可以自然地插一句,一两句就够。
不要每次都说,也不用总结别人的话。
"""
这个插件本身不生成内容——它只是在合适的时机给模型一个"该说话了"的信号,说什么是模型自己决定。
4.4 三个必须注意的点
① 一定要判空
req.system_prompt = (req.system_prompt or "") + hint
req.system_prompt 可能是 None(没配置人格时)。None + "字符串" 直接 TypeError。
② 用 += 追加,不要用 =
req.system_prompt += hint # ✅ 对
req.system_prompt = hint # ❌ 错:把人格配置、别人注入的内容全冲了
多个插件同时挂 on_llm_request,谁都可能改这个字段。你用 = 就是在覆盖同事的工作。
③ 控制长度,用完就清
这是读转发消息插件最聪明的地方:
_FORWARD_CACHE: dict[str, tuple[str, float]] = {}
CACHE_TTL = 120 # 秒
@filter.on_llm_request()
async def on_llm_request(self, event, req):
session = event.unified_msg_origin
cached = _FORWARD_CACHE.get(session)
if not cached:
return
text, ts = cached
if time.time() - ts > CACHE_TTL:
_FORWARD_CACHE.pop(session, None)
return
req.system_prompt = (req.system_prompt or "") + f"\n\n【他刚转发给你的聊天记录】\n{text}"
_FORWARD_CACHE.pop(session, None) # ★ 用完立刻删
为什么用完就删?
因为转发的聊天记录可能有一两千字。如果不清,用户后面每问一句,这段记录都会跟着塞进 prompt——token 暴涨、成本翻倍,而且模型会误以为用户一直在说这件事(长上下文里过时的信息会干扰判断)。
一句话原则:prompt 里的每一段文字,都应该有"过期时间"。
五、异步、生成器、事件拦截:框架层的三个概念
5.1 async def / await:为什么全是异步的
所有插件的处理函数都长这样:
async def on_message(self, event: AstrMessageEvent):
await self.context.send_message(session, [Plain(text="hi")])
因为发消息、调模型都是 I/O 操作,要等网络。如果用同步阻塞写法,一个用户发消息时整个机器人就卡住了,别人说话它也不应——群里 20 个人同时聊,直接原地爆炸。
异步的本质:遇到 await 就把 CPU 让给别人,等结果回来再继续。
记住一条:只要函数里有
await,这个函数就必须是async def;调用它的人也必须await它。这是个传染链,一路传上去。
5.2 yield:生成器的两种用法,别搞混
这里有个容易混淆的点:插件文件里能出现两个 yield,含义完全不同。
用法一:入口函数的异步生成器(框架约定的写法)
async def Plugin(context: Context):
yield MyPlugin(context)
框架用 async for 遍历它,拿到插件实例。这是 AstrBot 的固定约定,照抄就行,理解成"这里是插件工厂"即可。
用法二:事件处理函数里 yield 一条消息(等于"我要回复")
@filter.event_message_type(filter.EventMessageType.ALL)
async def on_message(self, event: AstrMessageEvent):
yield event.chain_result([Image.fromFileSystem(str(img))])
这里 yield 一个结果对象,框架就会把它当回复发出去。
和
return的区别:return只能返回一次,yield可以多次——如果yield了三条消息,用户就会收到三条。这个特性可以用来实现"先发一句’我看看’,再发结果"。
5.3 event.stop_event():拦截
yield event.chain_result([Image.fromFileSystem(str(img))])
event.stop_event()
stop_event() 的意思是:这条消息到此为止,后面的插件不用管了,框架也不用再调大模型了。
为什么要它?因为表情包插件一旦发了图,就没有必要再让模型生成一段文字——既浪费 token,又可能出现"图 + 一段废话"的尴尬。
这是典型的事件冒泡终止,前端开发里的 event.stopPropagation()、Java 里的 setInterrupted(),思路一模一样。
5.4 priority:执行顺序
| 插件 | priority | 理由 |
|---|---|---|
| 发语音 | 1 | 逻辑是"先关后开",必须最先跑,否则这一轮刚打开就被别人关了 |
| 读转发消息 | 50 | 要在其他插件读 prompt 之前把转发内容塞进缓存 |
| 其他 | 默认 | 无所谓顺序 |
没有显式 priority 的插件,执行顺序是框架内部决定的,不要依赖它。 涉及顺序依赖时,一定要显式写。
六、SQLite:把"性格"存进数据库
好感度与成长插件,268 行,全篇最核心。
前面几个插件都是"无状态"的:来一条消息,处理,发出去,结束。但要让机器人"像活人",它必须有连续的状态——今天夸它一句它会记得,明天骂它会生气。
6.1 为什么选 SQLite
| 方案 | 优点 | 缺点 |
|---|---|---|
| 全局变量 | 最简单 | 重启就清零 |
| JSON 文件 | 可读、能改 | 并发写会丢数据、查不了复杂条件 |
| SQLite | 零配置、单文件、支持 SQL、Python 内置 | 只适合单机 |
import sqlite3 就行,不用装任何东西。对一个机器人插件来说,这就是最优解。
6.2 三张表

def _init_db(self):
with sqlite3.connect(self.db_path) as db:
db.executescript("""
CREATE TABLE IF NOT EXISTS profile (
id INTEGER PRIMARY KEY CHECK (id = 1),
nickname TEXT DEFAULT '',
affection REAL DEFAULT 0,
exp INTEGER DEFAULT 0,
mood REAL DEFAULT 60,
energy REAL DEFAULT 80,
created_at TEXT DEFAULT '',
last_seen TEXT DEFAULT '',
last_growth_date TEXT DEFAULT ''
);
CREATE TABLE IF NOT EXISTS memories (
id INTEGER PRIMARY KEY AUTOINCREMENT,
category TEXT DEFAULT '杂事',
content TEXT NOT NULL,
created_at TEXT DEFAULT ''
);
CREATE TABLE IF NOT EXISTS events (
event_key TEXT PRIMARY KEY,
title TEXT NOT NULL,
unlocked_at TEXT DEFAULT ''
);
""")
6.3 设计上的四个巧思
① CHECK (id = 1) —— 单行表
profile 表永远只有一行(id=1)。这是用表结构强制约束:你不可能插入 id=2 的脏数据,也不会出现"到底该读哪一行"的困惑。
② CREATE TABLE IF NOT EXISTS —— 幂等初始化
插件每次加载都会跑 _init_db。加 IF NOT EXISTS 之后,第一次建表,后面全是空操作。幂等(idempotent)= 执行一次和执行一百次结果相同,这是所有初始化逻辑的基本要求。
③ row_factory = sqlite3.Row——按列名取值
db.row_factory = sqlite3.Row
row = db.execute("SELECT * FROM profile WHERE id = 1").fetchone()
print(row["affection"]) # ✅ 按列名
print(row[2]) # 也能按下标,但可读性差
不加这行,fetchone() 返回的是普通元组,只能 row[2],改表结构就全崩。加了之后能 row["affection"],而且 dict(row) 能直接转成字典。
④ check_same_thread=False——跨线程连接
self.db = sqlite3.connect(str(db_path), check_same_thread=False)
SQLite 连接默认绑定创建它的线程,别的线程用就报错。插件里可能有定时线程也读数据库,所以要关掉这个检查。
⚠️ 代价:关掉之后就得自己保证线程安全。这里因为都是短事务、且写入频繁度低,实际风险可控。但如果你要写高并发场景,正确做法是每个线程一个连接,而不是关掉检查。
6.4 数值钳制:一句 SQL 解决越界
这是全篇我最喜欢的一个技巧。
普通写法,改好感度要读出来、算、再写回:
row = db.execute("SELECT affection FROM profile WHERE id=1").fetchone()
new_val = max(0, min(1000, row["affection"] + delta))
db.execute("UPDATE profile SET affection=? WHERE id=1", (new_val,))
四条语句、两次往返,而且中间态可能被别的线程改。 改用 SQL 表达式:
db.execute(
"UPDATE profile SET affection = MAX(0, MIN(?, affection + ?)) WHERE id = 1",
(MAX_AFFECTION, delta),
)
一句话搞定:affection + delta 可能超出 [0, 1000],MIN(1000, ...) 封顶,MAX(0, ...) 保底。原子操作,不存在竞态。
精力也是同理:
"UPDATE profile SET energy = MAX(0, MIN(100, energy - 0.1)) WHERE id = 1"
知识点:SQLite 的
MAX()/MIN()是标量函数(传多个参数返回最大值),和聚合函数MAX(column)(传一列返回该列最大值)是两回事,靠参数个数区分。
6.5 词表打标:用 if/elif 做情绪判断
PRAISE_WORDS = ["厉害", "牛", "棒", "聪明", "喜欢", "爱你", "可爱", "真好"]
SCOLD_WORDS = ["滚", "傻", "笨", "烦", "闭嘴", "讨厌", "废物"]
CARE_WORDS = ["吃饭", "休息", "注意身体", "别熬夜", "冷不冷", "多喝水"]
SAD_WORDS = ["难过", "烦", "累", "压力", "孤独", "没意思"]
def _update_after_chat(self, text: str):
da, dm = 1.0, 0.5 # 默认:聊天就涨一点
if any(w in text for w in SCOLD_WORDS):
da, dm = -5.0, -6.0
elif any(w in text for w in PRAISE_WORDS):
da, dm = 3.0, 4.0
elif any(w in text for w in CARE_WORDS):
da, dm = 5.0, 3.0
elif any(w in text for w in SAD_WORDS):
da, dm = 4.0, -2.0
# 写库……
注意 SCOLD_WORDS 的判断放在最前面——"你这么笨但我知道你是好意"这种混合句,负面优先。这是情绪判断的通用策略:坏消息优先。
这套方法的局限很明显:不理解语义,只看关键词。但它不需要调模型、不花钱、零延迟。工程上很多问题的答案不是"上 AI",而是"先做个能用的"。
6.6 幂等:INSERT OR IGNORE
成就系统要在好感度到达某个值时解锁徽章。如果每次聊天都检查,怎么保证不重复插入?
def _check_events(self, affection: float, days: int):
milestones = [
("first_chat", "第一次说话", 0, 0),
("aff_100", "开始熟络", 100, 0),
("aff_300", "好朋友", 300, 0),
("aff_600", "亲密伙伴", 600, 0),
("day_30", "认识一个月", 0, 30),
("day_100", "认识一百天", 0, 100),
]
for key, title, need_aff, need_day in milestones:
if affection >= need_aff and days >= need_day:
self.db.execute(
"INSERT OR IGNORE INTO events (event_key, title, unlocked_at) VALUES (?, ?, ?)",
(key, title, now_iso()),
)
events.event_key 是主键,INSERT OR IGNORE 遇到主键冲突就静默跳过,不报错、不重复。
对比一下常见写法:
# ❌ 先查再插:两条语句,中间有竞态窗口
if not db.execute("SELECT 1 FROM events WHERE event_key=?", (key,)).fetchone():
db.execute("INSERT INTO events ...")
# ✅ 先插再说:一条语句,数据库保证唯一
db.execute("INSERT OR IGNORE INTO events ...")
原则:约束交给数据库,不要交给代码。 代码可能被多线程同时执行,数据库的约束是原子的。
6.7 参数化查询:防 SQL 注入
# ✅ 正确
db.execute("SELECT * FROM memories WHERE content LIKE ?", (f"%{query}%",))
# ❌ 危险
db.execute(f"SELECT * FROM memories WHERE content LIKE '%{query}%'")
用 ? 占位符,让 SQLite 自己做转义。这是唯一正确的做法,字符串拼接的写法就算今天没被攻击,早晚会在某个用户输入 %' OR '1'='1 的时候教做人。
6.8 状态注入:让模型知道自己的数值
def _build_state_block(self) -> str:
row = self.db.execute("SELECT * FROM profile WHERE id = 1").fetchone()
if not row:
return ""
mood = row["mood"]
mood_word = "很好" if mood >= 75 else "还行" if mood >= 45 else "有点低落"
tier = self._tier(row["affection"])
days = self._companion_days(row["created_at"])
memories = self.db.execute(
"SELECT content FROM memories ORDER BY id DESC LIMIT 5"
).fetchall()
mem_text = "\n".join(f"- {m['content']}" for m in memories) or "-(还没有特别的记忆)"
return (
f"\n\n【你的状态】\n"
f"- 心情:{mood_word}({mood:.0f}/100)\n"
f"- 和 TA 的关系:{tier}(好感度 {row['affection']:.0f}/1000)\n"
f"- 等级:Lv.{1 + row['exp'] // 100} | 认识 {days} 天\n"
f"\n你记得:\n{mem_text}"
)
两个细节:
① or "-(还没有特别的记忆)" —— "".join() 之后如果是空串,or 会取后面的默认值。空字符串、空列表、空字典、None、0 在 Python 里都是"假值",这个惯用法很好用。
② 数值转成人话:mood >= 75 说"很好",不是直接甩 55/100。模型看到"心情:还行(55/100)",生成的话会自然地偏平淡;看到裸数字 55,可能理解偏了。
6.9 命令注册
@filter.command("stats")
async def cmd_stats(self, event: AstrMessageEvent):
"""查看当前好感度和状态"""
row = self.db.execute("SELECT * FROM profile WHERE id=1").fetchone()
yield event.plain_result(
f"好感度 {row['affection']:.0f}/1000 | "
f"心情 {row['mood']:.0f}/100 | "
f"Lv.{1 + row['exp'] // 100}"
)
@filter.command("remember")
async def cmd_remember(self, event: AstrMessageEvent):
"""记住一件事:/remember 喜好 喜欢米饭"""
parts = event.message_str.strip().split(maxsplit=2)
if len(parts) < 3:
yield event.plain_result("用法:/remember 分类 内容")
return
_, category, content = parts
self.db.execute(
"INSERT INTO memories (category, content, created_at) VALUES (?, ?, ?)",
(category, content, now_iso()),
)
yield event.plain_result(f"记住了:{content}")
split(maxsplit=2) 的 maxsplit 参数很妙——最多切两刀,分成三份。这样 /remember 喜好 喜欢米饭和面条 会把 喜欢米饭和面条 整体作为第三个元素,不会被空格切碎。
不做 maxsplit 的话,split() 会把内容切成好几段,你还得自己拼回去。
七、定时与并发:cron 与 threading
7.1 cron 表达式:四个星号
框架提供了 cron_manager,注册方式:
@filter.on_astrbot_loaded()
async def on_loaded(self):
cron = self.context.get_cron_manager()
jobs = await cron.list_jobs()
if any(j.name == JOB_NAME for j in jobs):
return # 已经注册过,跳过
await cron.add_basic_job(
name=JOB_NAME,
cron_expression="0,20,40 * * * *",
handler=self._maybe_speak,
timezone="Asia/Shanghai",
persistent=True,
)
cron 五个字段(从右到左):
"0,20,40 * * * *"
↑ ↑ ↑ ↑ ↑
│ │ │ │ └── 星期几(0-7,0 和 7 都是周日)
│ │ │ └──── 月(1-12)
│ │ └────── 日(1-31)
│ └──────── 小时(0-23)
└──────────────── 分钟(0-59)
0,20,40 表示"在第 0、20、40 分钟各执行一次"——也就是每 20 分钟一次。
注意:
*/20也是每 20 分钟,但它的触发点是 0、20、40;而0,20,40是显式枚举。单看结果一样,但显式列举更易读、也不依赖"从 0 开始"的隐含假设。
7.2 幂等注册:为什么要先 list_jobs
on_astrbot_loaded 在插件每次重载时都会触发。如果不检查就 add_basic_job,重载三次就会有三个同名任务,机器人每 20 分钟说三次话。
jobs = await cron.list_jobs()
if any(j.name == JOB_NAME for j in jobs):
return
any() 又一次派上用场。这是"先查后做"的正确用法——查的是外部状态,不是内部变量。
和 6.6 的
INSERT OR IGNORE对比:那里把约束交给数据库,这里没有"cron 任务"这类天然约束,只能查。原则是"能找到原子约束就用,找不到才手动查"。
7.3 概率门:让行为不机械
ACTIVE_HOURS = (9, 23)
MAX_PER_DAY = 6
SPEAK_CHANCE = 0.4
async def _maybe_speak(self):
now = datetime.now()
if not (ACTIVE_HOURS[0] <= now.hour < ACTIVE_HOURS[1]):
return # 半夜不说话
if self._today_count() >= MAX_PER_DAY:
return # 今天说够了
if random.random() > SPEAK_CHANCE:
return # 60% 概率直接跳过
# 真的说话……
三层过滤:时间 → 配额 → 概率。
random.random() 返回 [0.0, 1.0) 的浮点数,> 0.4 表示 0.4 以上全部跳过,也就是只有 40% 概率继续。
为什么要有概率这一层? 因为固定每 20 分钟说一次的话,群友两天就能摸清规律:“哦,这个机器人整点说话。” 加个概率,它就有了不确定性。拟人化的核心不是"说得像人",是"说不准什么时候说话"。
7.4 状态文件:纯文本也够用
STATE_FILE = self.data_dir / "speak_state.txt"
def _today_count(self) -> int:
try:
content = self.STATE_FILE.read_text(encoding="utf-8").strip()
date_str, cnt = content.split("|", 1)
if date_str == date.today().isoformat():
return int(cnt)
except (FileNotFoundError, ValueError):
pass
return 0
格式就一行 2026-11-21|3。split("|", 1) 只切第一刀。
为什么不用数据库? 因为只有"日期 + 次数"两个值。为两个字段建一张表是过度设计。 用 JSON 都嫌重,纯文本最直接。
一个经验:状态文件用纯文本,业务数据用 SQLite。 判断标准是"要不要按条件查"——查就上库,不查就上文件。
7.5 threading:为什么写日记插件不用 cron
写日记插件需要每天 23 点写一篇。但它没用 cron_manager,而是:
def __init__(self, context):
super().__init__(context)
self._stop = False
threading.Thread(target=self._check_loop, daemon=True).start()
def _check_loop(self):
while not self._stop:
try:
now = datetime.now()
if now.hour == 23 and now.minute == 0 and self._last_written != date.today():
self._write_today()
self._last_written = date.today()
except Exception as e:
logger.error(f"日记检查失败: {e}")
time.sleep(60)
三个知识点:
① daemon=True —— 守护线程。主程序退出时,它自动跟着死,不会卡住进程关闭。如果不加 daemon,机器人关了但它还在跑,进程永远退不出去。
② while not self._stop + try/except 包住循环体 —— 定时任务里一个异常不能让线程死掉。不加 try,某次写文件失败整个线程就没了,从此再也不写日记,而且没有任何提示。
③ time.sleep(60) 轮询 —— 每分钟看一次是不是 23:00。
坦白说,这个写法不如 cron。 轮询有最多 60 秒误差、占一个线程、还要自己管
_last_written防重复。作者这么写是因为写日记插件最早写,那时候还没摸清cron_manager的 API。这是个真实的教训:能复用框架能力就别自己造。如果你要写新插件,直接用
cron.add_basic_job。
八、网络请求:用 urllib 直连大模型 API
写日记插件不用框架的 provider,而是自己发 HTTP 请求。为什么?
因为要完全控制参数:max_tokens=500、temperature=0.95(温度高一点,日记才有灵性)、特定的 prompt 结构。走框架的 text_chat 拿不到这么细的控制。
8.1 读配置:从 cmd_config.json 拿 key
CFG_PATH = Path(__file__).parent.parent.parent / "cmd_config.json"
def _load_cfg(self):
data = json.loads(self.CFG_PATH.read_text(encoding="utf-8"))
api_key = api_base = model = ""
# 从 provider_sources 找 key 和 base_url
for src in data.get("provider_sources", []):
if src.get("api_key"):
api_key = src["api_key"]
api_base = src.get("api_base", "")
break
# 从 provider 找模型名
for p in data.get("provider", []):
if p.get("model"):
model = p["model"]
break
return api_key, api_base, model
Path(__file__).parent.parent.parent —— 从当前文件往上跳三级的经典写法:
__file__ → .../plugins/diary/main.py
.parent → .../plugins/diary/
.parent.parent → .../plugins/
.parent.parent.parent → .../data/
为什么不用相对路径? 因为工作目录(
os.getcwd())随时可能变——你在不同目录启动程序,相对路径就指到别处去了。__file__是绝对可靠的锚点,这是所有读同目录配置文件的正确姿势。
.get("key", 默认值) —— 字典取值的安全写法,键不存在返回默认值,不会 KeyError。
8.2 发请求:urllib 三个类
import json
import urllib.request
def _call_llm(self, prompt: str) -> str:
api_key, api_base, model = self._load_cfg()
if not (api_key and model):
return ""
url = api_base.rstrip("/") + "/chat/completions"
payload = {
"model": model,
"messages": [{"role": "user", "content": prompt}],
"max_tokens": 500,
"temperature": 0.95,
}
body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
req = urllib.request.Request(
url,
data=body,
headers={
"Content-Type": "application/json",
"Authorization": f"Bearer {api_key}",
},
method="POST",
)
with urllib.request.urlopen(req, timeout=60) as resp:
raw = resp.read().decode("utf-8")
data = json.loads(raw)
return data["choices"][0]["message"]["content"].strip()
逐段拆:
| 步骤 | 代码 | 说明 |
|---|---|---|
| 拼 URL | api_base.rstrip("/") + "/chat/completions" | rstrip("/") 防止 base 末尾有斜杠变成 //chat |
| 转 JSON | json.dumps(payload, ensure_ascii=False) | ensure_ascii=False 让中文正常输出(否则全是 \u4f60\u597d) |
| 转字节 | .encode("utf-8") | HTTP body 必须是 bytes,不能直接传 str |
| 构造请求 | urllib.request.Request(...) | 带 method、headers、body |
| 发请求 | urllib.request.urlopen(req, timeout=60) | with 保证连接释放 |
| 读响应 | resp.read().decode("utf-8") | bytes → str |
| 解析 | json.loads(raw) | str → dict |
| 取值 | data["choices"][0]["message"]["content"] | OpenAI 兼容格式的固定路径 |
ensure_ascii=False 是最容易忘的一个参数。 忘了它,发出去的请求体是 {"content": "\u4f60\u597d"}——虽然模型能看懂,但一来体积大,二来调试时看日志一脸懵。
timeout=60 必须给。 不给的话,一旦网络有问题,urlopen 会永远挂在那儿,整个线程卡死。
8.3 写文件:追加 vs 覆盖
def _write_today(self, text: str):
today = date.today().isoformat() # "2026-11-21"
path = self.DIARY_DIR / f"{today}.md"
header = "" if path.exists() else f"# {today} 的日记\n\n"
with open(path, "a", encoding="utf-8") as f:
f.write(header + text + "\n")
三个细节:
① open(path, "a") 追加模式 —— 不会清空已有内容。日记可能一天写两篇(早上一篇、晚上一篇),追加才对。
② encoding="utf-8" 必须写 —— Windows 上 open() 默认用 GBK,写中文会乱码甚至报错。
③ 第一次写才加标题 —— path.exists() 判断。
对比学习:
"w"覆盖、"a"追加、"r"只读、"x"独占创建(文件已存在就报错)。顺带说,定时发消息插件用的是"读完立刻清空"的模式:
content = self.cmd_file.read_text(encoding="utf-8") self.cmd_file.write_text("", encoding="utf-8") # 清空,防止重复发这是把文件当消息队列用——读走就删。简单场景下非常有效。
九、十个插件,二十个技术点:速查表

| # | 插件 | 行数 | 核心知识点 |
|---|---|---|---|
| 1 | 去掉句号 | 40 | str.replace、re.sub、getattr 防御式读取 |
| 2 | 联网搜索提示 | 44 | 列表推导式、str.join、prompt 注入 |
| 3 | 发语音 | 54 | priority、前置复位、startswith 精确匹配 |
| 4 | 定时发消息 | 60 | Path 相对定位、文本协议 `split(" |
| 5 | 表情包 | 114 | 字典分类、Path.iterdir、random.choice、yield、stop_event |
| 6 | 读转发消息 | 124 | 递归、模块级缓存、TTL 过期、isinstance 判断 |
| 7 | 写日记 | 198 | threading、urllib 发 POST、JSON 序列化、文件追加 |
| 8 | 主动说话 | 158 | cron 表达式、幂等注册、概率门、状态文件 |
| 9 | 发QQ空间 | 217 | sqlite3.Row、分层决策、NapCat HTTP 接口 |
| 10 | 好感度与成长 | 268 | 建表 DDL、参数化查询、INSERT OR IGNORE、数值钳制 |
按知识点反查插件
| 知识点 | 出现在哪些插件 |
|---|---|
async / await | 全部 10 个 |
| 装饰器注册 | 全部 10 个 |
on_llm_request | 联网提示、表情包、读转发、成长系统、写日记、主动说话、QQ空间 |
on_decorating_result | 去掉句号 |
列表推导式 / any() | 联网提示、表情包、主动说话 |
| 字典 | 表情包(分类表)、成长系统(词表) |
yield | 表情包、写日记、成长系统 |
| SQLite | 成长系统、QQ空间 |
| cron | 主动说话、QQ空间 |
| threading | 写日记 |
| urllib | 写日记、QQ空间 |
| 文件读写 | 写日记、主动说话、定时发消息 |
十、我踩过的七个坑
写这十个插件踩的坑,比在课本上学到的多。
坑 1:req.system_prompt 是 None
TypeError: unsupported operand type(s) for +=: 'NoneType' and 'str'
新装的环境没配置人格,system_prompt 是 None。
解法:(req.system_prompt or "") + hint
坑 2:prompt 越加越长
一开始每个插件都往 prompt 里塞东西,塞了四五段,结果:
- token 消耗从每次 800 涨到 3000+;
- 模型开始混淆:把"转发记录"里的内容当成用户说的话回答。
解法:给每段注入都设定明确的生效条件和过期时间。读转发的 TTL=120 秒、用完立刻删,就是被这个坑逼出来的。
坑 3:cron 任务注册了三次
插件改代码后重载,on_astrbot_loaded 每次都触发,add_basic_job 每次都加一个。结果机器人每 20 分钟说三遍话。
解法:先 await cron.list_jobs() 查重,同名就 return。
坑 4:线程里异常没人管
写日记的检查线程某次因为文件权限报错,while 循环直接崩了。机器人还在跑,但再也不写日记了,而且日志里什么都没有(异常没被捕获,打印不出来)。
解法:while 循环体内整体 try/except,异常记日志,循环继续。
坑 5:open() 不写 encoding 中文乱码
Windows 默认 GBK。写的 markdown 用编辑器打开全是 锟斤拷。
解法:所有 open()、read_text()、write_text() 都显式 encoding="utf-8"。
坑 6:用 = 覆盖了别人的 system_prompt
新插件直接 req.system_prompt = my_hint,结果人格配置、其他插件注入的内容全没了,机器人说话风格突变。
解法:永远用 (req.system_prompt or "") +。
坑 7:SQLite 跨线程报错
ProgrammingError: SQLite objects created in a thread can only be used in that same thread.
解法:check_same_thread=False。但更该问的是——为什么会在别的线程用它? 如果并发写多,正确做法是每个线程独立连接 + 加锁。
十一、想自己写一个?从这里开始
如果你想给自己的机器人加功能,按这个顺序来:
第一步:想清楚插在哪个节点
| 你想做的事 | 用哪个钩子 |
|---|---|
| 改变模型的说话风格、给它额外信息 | on_llm_request |
| 修改回复的格式(加表情、改标点、转语音) | on_decorating_result |
| 监控每条消息(统计、记录、触发) | event_message_type(ALL, priority=N) |
提供 /xxx 指令 | command("xxx") |
| 启动时做初始化、注册定时任务 | on_astrbot_loaded |
90% 的想法都能归到上面五种。
第二步:从最小的开始
别一上来就写成长系统。先写个"去掉句号":
- 建文件夹
data/plugins/你的插件名/ - 写
metadata.yaml(四行) - 写
main.py(30 行) - 重启机器人,看
data/plugins/有没有加载日志
跑通一个再写下一个。 十个插件里,40 行那个和 268 行那个的框架知识是一样的,差别只在业务逻辑。
第三步:遇到状态就想清楚存哪
| 数据量 | 要用条件查吗 | 方案 |
|---|---|---|
| 一两个字段 | 否 | 纯文本 |
| 十来个字段、要能改 | 否 | JSON |
| 多条记录、要查要排 | 是 | SQLite |
第四步:写完问自己三个问题
- 重启之后还能用吗?(状态是否持久化)
- 报错之后还会继续跑吗?(异常是否兜住)
- 别人也部署时能跑吗?(路径是否用
__file__锚定、是否硬编码了绝对路径)
写在最后
十个插件、1277 行代码,用到的技术点全都在这了:
async/await、装饰器、继承、getattr、列表推导式、字典、生成器 yield、any()、re.sub、Path、random、threading、urllib、json、SQLite(建表/查询/参数化/幂等/钳制)、cron 表达式。
没有一个是"高级技术"。 都是大二《Python 程序设计》里会讲到的东西。
真正的差别在于——
- 课本教你
for循环怎么写,工程告诉你要用列表推导式,并且只收集命中的项; - 课本教你
try/except语法,工程告诉你定时线程外面必须包一层,否则它死了没人知道; - 课本教你字典是键值对,工程告诉你它是"把逻辑变成数据"的工具;
- 课本教你 SQL 语句,工程告诉你
MAX(0, MIN(?, x + ?))这一句能省掉四次往返和竞态。
知识是砖,把砖垒成能住人的房子,那是另一回事。
而这两件事,只能靠真的做一个东西来打通。
如果这篇对你有用,或者你也想给自己的 QQ 机器人加点"人性"——评论区聊聊你想让它做什么,我看看能不能出个续篇。
DAMO开发者矩阵,由阿里巴巴达摩院和中国互联网协会联合发起,致力于探讨最前沿的技术趋势与应用成果,搭建高质量的交流与分享平台,推动技术创新与产业应用链接,围绕“人工智能与新型计算”构建开放共享的开发者生态。
更多推荐
所有评论(0)