我给 QQ 机器人写了 10 个 AstrBot 插件,1277 行代码,把用到的 Python 知识全拆一遍

一个群友说:“你这机器人怎么像活人?”

我说因为它有记忆、有心情、会说废话、还会自己发 QQ 空间。

他说:“那你用了什么高深技术?”

我说:“字符串、字典、SQLite、定时任务。大二课本上的东西。”

这篇文章把源码摊开,一个一个讲清楚:这 10 个插件,到底用到了哪些编程知识。


目录

章节内容难度
〇先搞清楚:AstrBot 是什么,插件往哪儿插入门
一消息管线的五个节点(看懂了这节,后面全是套娃)入门
二字符串与正则:去掉句号那个插件★
三列表与字典:关键词触发与表情包分类★
四提示词工程:让大模型"听话"的四种注入★★
五异步、生成器、事件拦截:框架层的三个概念★★★
六SQLite:把"性格"存进数据库★★★
七定时与并发:cron 与 threading★★
八网络请求:用 urllib 直连大模型 API★★
九十个插件,二十个技术点:速查表—
十我踩过的七个坑—
十一想自己写一个?从这里开始—

〇、先搞清楚:AstrBot 是什么,插件往哪儿插

AstrBot 是一个开源的 LLM 聊天机器人框架(Python 写的),它负责三件事:

  1. 接消息——通过平台适配器(NapCat / aiocqhttp / Telegram / 飞书……)收到 QQ 消息;
  2. 调模型——把消息和上下文打包,发给大模型(OpenAI / DeepSeek / 智谱……);
  3. 发出去——把模型的回复转成 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()

逐段拆:

步骤代码说明
拼 URLapi_base.rstrip("/") + "/chat/completions"rstrip("/") 防止 base 末尾有斜杠变成 //chat
转 JSONjson.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去掉句号40str.replace、re.sub、getattr 防御式读取
2联网搜索提示44列表推导式、str.join、prompt 注入
3发语音54priority、前置复位、startswith 精确匹配
4定时发消息60Path 相对定位、文本协议 `split("
5表情包114字典分类、Path.iterdir、random.choice、yield、stop_event
6读转发消息124递归、模块级缓存、TTL 过期、isinstance 判断
7写日记198threading、urllib 发 POST、JSON 序列化、文件追加
8主动说话158cron 表达式、幂等注册、概率门、状态文件
9发QQ空间217sqlite3.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% 的想法都能归到上面五种。

第二步:从最小的开始

别一上来就写成长系统。先写个"去掉句号":

  1. 建文件夹 data/plugins/你的插件名/
  2. 写 metadata.yaml(四行)
  3. 写 main.py(30 行)
  4. 重启机器人,看 data/plugins/ 有没有加载日志

跑通一个再写下一个。 十个插件里,40 行那个和 268 行那个的框架知识是一样的,差别只在业务逻辑。

第三步:遇到状态就想清楚存哪

数据量要用条件查吗方案
一两个字段否纯文本
十来个字段、要能改否JSON
多条记录、要查要排是SQLite

第四步:写完问自己三个问题

  1. 重启之后还能用吗?(状态是否持久化)
  2. 报错之后还会继续跑吗?(异常是否兜住)
  3. 别人也部署时能跑吗?(路径是否用 __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 机器人加点"人性"——评论区聊聊你想让它做什么,我看看能不能出个续篇。

Logo

DAMO开发者矩阵,由阿里巴巴达摩院和中国互联网协会联合发起,致力于探讨最前沿的技术趋势与应用成果,搭建高质量的交流与分享平台,推动技术创新与产业应用链接,围绕“人工智能与新型计算”构建开放共享的开发者生态。

更多推荐