OrbisLumen

先把消息接起来#

这个项目的基础是 AstrBot 和 NapCatQQ，部署由 Docker Compose 管理。

AstrBotDevs/AstrBot

NapNeko/NapCatQQ

在当前项目里，NapCat 负责 QQ 侧的消息连接，通过 OneBot 接口与 AstrBot 通信；AstrBot 处理会话、模型调用和插件，模型侧接入 DeepSeek。这样一条消息从 QQ 进来，经过机器人框架处理，再把生成的回复送回聊天窗口。

这几个部分各自承担不同的事情，排查问题时也就有了方向。网页后台能打开，不代表 QQ 已经登录；QQ 在线，不代表消息连接正常；消息进了框架，也不代表模型配置已经能用。只有整条链路走通，聊天窗口里才会真的出现回复。

本机最初是在 Apple Silicon Mac 上部署，项目也保留了迁移到 Linux 的说明。Compose 把服务、网络和数据挂载组织起来，让启动和恢复有了比较固定的入口。

角色感需要一点确定性#

最开始当然是想让它好玩一点。给机器人一个设定，让它用特定的语气说话，这种反馈很直接，也很容易让人继续加需求。

但接进真实会话之后，就会碰到提示词以外的问题：谁能执行指令，群聊什么时候应该回复，不同账号应该怎样区分，以及哪些消息应该直接忽略。

所以项目里加了访问控制插件。管理员身份由框架配置决定，群聊需要直接 @ 才触发，普通聊天和管理指令也有明确的权限区分。对于需要稳定区分身份的关系设定，会把当前账号的信息交给系统提示；部分明确的身份问答则由规则处理。

这个过程挺有意思：原本是为了让机器人更有角色感，最后却写起了很普通的权限逻辑。因为如果它连正在和谁说话都不稳定，再生动的语气也很容易出戏。

模型适合生成表达，账号身份和操作权限则需要可靠的依据。把这些基础关系处理清楚，角色才更容易在不同会话里保持一致。

从会聊天，到能接入日常应用#

后来项目开始接入独立应用，QQ 也多了一种用途：作为任务结果和状态通知的入口。

这里保留了两种扩展方式。需要参与聊天上下文和消息处理的逻辑，放在 AstrBot 插件里；有自己调度、依赖和运行状态的应用，独立部署，再通过 NapCat HTTP 接口发送消息。它们可以共用 QQ 连接，同时分别启动、停止和维护。

这样做之后，关注点也跟着变了。除了回复内容，还要考虑网络超时、通知失败、重试和重复消息。一次请求发出去了，并不能直接说明对方已经收到；程序重启之后，也需要知道哪些事情已经做过。

这些问题没有聊天效果那么显眼，却会直接决定一个功能能不能放心留在那里运行。项目从“试试能不能做出来”，慢慢走到了“下次出问题时，能不能知道发生了什么”。

留着运行，比演示一次更麻烦#

现在源码、配置模板和运行数据是分开管理的。登录状态、聊天记录、密钥与备份有自己的存放位置，升级和迁移也需要照顾这些状态，不能只搬走一份代码。

Docker 让部署更容易重复，但本机休眠、QQ 登录失效、外部服务异常，依然会影响机器人。所谓“跑起来了”，其实只是后续维护的开始。

这次折腾让我对应用开发多了一点具体的认识。大模型让一个机器人很快就能说话，开源框架也提供了很好的起点；要让它在日常聊天里合适地出现、在需要的时候可靠地工作，还需要把很多普通的软件工程细节补齐。

不过，看着自己搭出来的机器人真的在 QQ 里回复，还是挺开心的。起点只是想做一个好玩的 Bot，最后顺带学了一点部署、接口和状态管理，也算没有白折腾。