astrbot-operations

AstrBot 运营维护 — 进程管理、插件热重载、人格系统、知识库集成、常见故障排查

SKILL.md

GitHub

AstrBot 运维指南

进程管理

AstrBot 通过 systemd 管理(非用户手动启动):

sudo systemctl status astrbot      # 查看状态
sudo systemctl restart astrbot     # 重启
sudo systemctl stop astrbot        # 停止

日志输出到 systemd journal,非日志文件:

sudo journalctl -u astrbot --no-pager -n 100
sudo journalctl -u astrbot --no-pager --since "1:06"

⚠️ 用户说"查日志"时,先验证日志在不在写

常见坑:用户问"看一下 astrbot 日志"时,data/astrbot.log 经常是死文件。 三个根因:

  1. cmd_config.json 里 log_file_enable: false(默认)→ AstrBot 不写文件,只 stdout
  2. systemd unit (~/.config/systemd/user/astrbot.service) 没设 StandardOutput=append:<path> → stdout 默认进 journal,而不是 data/astrbot.log
  3. 用户以前手敲 astrbot run >> data/astrbot.log 2>&1 留下的旧文件,mtime 几个月前,跟当前进程完全无关

验证日志是不是活的(不要直接 grep):

# 1. 看文件 mtime
stat /home/po/astrbot/data/astrbot.log | grep Modify

# 2. 看当前 astrbot 进程的 stdout 实际指向哪
PID=$(pgrep -f 'astrbot run' | head -1)
ls -l /proc/$PID/fd/{1,2}
# 指向 socket 或 pipe → stdout 被 systemd 接管,data/astrbot.log 是死的
# 指向 /home/po/astrbot/data/astrbot.log → 真的在写

# 3. 进程是 systemd 直接拉起的还是手敲的?
ps -o pid,ppid,cmd -p $PID
# PPID=1 (systemd) → 父进程是 init
# PPID=bash 的 pid → 手敲启动

如果 data/astrbot.log mtime < 当前时间,直接看 journal:

journalctl --user -u astrbot -n 200 --no-pager
journalctl --user -u astrbot --since "30 min ago" --no-pager

修复 systemd unit 持久记录日志(推荐):

在 ~/.config/systemd/user/astrbot.service 加:

[Service]
# ... existing ...
StandardOutput=append:/home/po/astrbot/data/astrbot.log
StandardError=append:/home/po/astrbot/data/astrbot.log

然后 systemctl --user daemon-reload && systemctl --user restart astrbot,日志立刻开始写。append: 而不是 file: —— 避免 systemd 启动前清空文件,重启不会丢历史日志。

WebUI: http://localhost:6185,用户名 Publieople,密码 Fzj103415422。

版本升级

AstrBot 通过 uv 部署,不支持在 WebUI 里直接升级。WebUI 升级只更新前端 dist 文件,Core 版本不变会导致版本错配。

# 通过代理升级时需加大超时(默认 30s 不够),大包走清华镜像
env UV_HTTP_TIMEOUT=300 UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple uv tool upgrade astrbot --python 3.12

升级后如果 WebUI 和 Core 版本不一致:删除 data/dist 目录后重启。

sudo systemctl stop astrbot
rm -rf /home/po/astrbot/data/dist
sudo systemctl start astrbot

注意:升级后首次启动可能弹出 Install dashboard? [Y/n]: 交互式提示。先手动跑一次 echo "y" | astrbot run 让 dashboard 装完,然后再用 systemd 启动。

插件管理

AstrBot 热重载有两层含义,要分清:

  1. 新增插件 — 把新插件目录放到 data/plugins/,重启 AstrBot 后生效(启动时扫描一次)。不要手动 kill 进程。
  2. 修改已有插件代码 — 默认不会自动热重载。star_manager.py:210 写明 if os.getenv("ASTRBOT_RELOAD", "0") == "1": asyncio.create_task(self._watch_plugins_changes()),watcher 默认不启。当前 systemd service 没设这个 env,所以改了 main.py 或任何被 import 的子模块都要 sudo systemctl restart astrbot。即使启了 watcher,热重载也只重建插件主 class 实例,被主模块 import 的二级 .py(如 workflow_engine.py)不会重新 import(Python 模块缓存机制),改完还是要 restart。

插件目录: /home/po/astrbot/data/plugins/

通过 CLI 安装(推荐)

cd /home/po/astrbot
# 搜索插件
astrbot plug search bangumi
# 用 marketplace 名称安装(注意:可能与 GitHub repo 名不同)
astrbot plug install astrbot-plugin-bangumi-enhance
# 从 GitHub URL 安装
astrbot plug install https://github.com/united-pooh/astrbot_plugin_bangumi

注意:命令是 astrbot plug(不是 plugin)。marketplace 上的插件名用连字符(astrbot-plugin-bangumi-enhance),可能不同于 GitHub repo 名(astrbot_plugin_bangumi)。

手动 git clone

cd /home/po/astrbot/data/plugins
git clone <repo-url>  # 需要代理: export https_proxy=http://127.0.0.1:7890

插件加载失败

如果插件加载失败,通过 API 重载:

POST /api/plugin/reload-failed  {"dir_name": "astrbot_plugin_xxx"}

不要凭记忆说"X 插件已装":memory 里关于"哪些插件装了"的记录会过期(插件可能被禁用/卸载/重命名)。在断言某个插件存在之前先 ls ~/astrbot/data/plugins/ 确认目录在不在,再决定后续操作。错误信息: "meme_manager 已装"→目录不存在→给用户错误指引。

插件开发(fork + 改造 vs 从零写)

先调研后开工(用户偏好:spec-first,先搜现成方案再集成)。完整开发流程、文档坑、装饰器陷阱、验证模式见 references/plugin-dev.md。

核心规则

  1. 先搜现成 — GitHub + AstrBot 官方 marketplace,能 fork 不要从零写。gh repo fork <upstream> 自动加 upstream remote
  2. 写不熟悉的框架/工具代码前必须先查文档 — AstrBot 文档站 docs.astrbot.app 大量路径 404,真实路径是 /dev/star/guides/xxx.html 不是 /dev/star/xxx.html
  3. 本地直写 — 放 data/plugins/<name>/ 后 sudo systemctl restart astrbot 加载;不要走 WebUI 安装
  4. 改完 metadata.yaml 的 name/author/version,fork 仓时改 author 标注上游 X / publieople
  5. 每次改动写 ad-hoc 验证 — 详见下方验证模式

关键装饰器(from astrbot.api.event.filter import)

from astrbot.api.star import Context, Star, register
from astrbot.api.event import filter, AstrMessageEvent, MessageEventResult
from astrbot.api.event.filter import (
    event_message_type, EventMessageType,  # 全消息钩子
    command,                                # 命令: @command("xxx")
    llm_tool,                               # LLM 工具: @llm_tool(name="x")
)

@register("plugin_id", "Author", "description", "v1.0.0", "https://github.com/...")
class MyPlugin(Star):
    def __init__(self, context: Context, config=None): super().__init__(context)

    @command("看图")                                              # 命令
    async def cmd(self, event: AstrMessageEvent, arg: str = ""):  # 空格分隔参数
        yield event.plain_result("...")

    @llm_tool(name="my_tool")                                      # LLM 工具
    async def my_tool(self, event: AstrMessageEvent, query: str):
        '''工具描述。

        Args:
            query(string): 检索词
        '''
        return "结果"  # str 加入 LLM 上下文

    @event_message_type(EventMessageType.ALL)                       # 消息钩子
    async def on_msg(self, event: AstrMessageEvent):
        if "触发词" in event.message_str:
            ...

常见坑:

  • @llm_tool(name="x") 的 name= 是 keyword arg 不是 positional(AST 检查时必须查 keywords 而不是 args)
  • 命令带空格参数时 AstrBot 框架自动 split 给 arg: str 形参
  • 命令函数 return 一次就行(yield event.plain_result(...) 或 return event.plain_result(...));event.image_result(url) 是图片助手

_conf_schema.json 字段类型速查

  • string + options:[...]+labels:[...] → 下拉单选
  • list + items.type=string + options+labels → 复选多选(list 的 items 也支持 options/labels)
  • int/float + slider:{min,max,step} → 滑块
  • _special: "select_provider" / "select_persona" → WebUI 下拉选已注册的 provider/persona

验证模式(ad-hoc 脚本 + journal)

每次代码改动后必须做 3 件事:

# 1. 语法
python3 -c 'import ast; ast.parse(open("main.py").read()) && print("OK")'

# 2. 重启 + journal 确认(Loading plugin + Added llm tool 出现,无 error)
sudo systemctl restart astrbot
sleep 4
sudo journalctl -u astrbot --since "30 seconds ago" --no-pager | \
  grep -E "Loading plugin <name>|Added llm tool: <tool>|error|exception"

journal 没看到 plugin 行时等更久(AstrBot 顺序加载多插件,timing 不固定),再 grep 一次。

ad-hoc 验证脚本(推荐):用 ast 模块走 AST 提取装饰器、参数、数据结构,写到 /tmp/hermes-verify-<name>.py 跑完删。验证项示例:

  • 装饰器是否存在、参数 keyword 还是 positional
  • 数据结构正确性(dict 长度、list 元素类型、keys ⊆ 某集合)
  • 业务逻辑模拟(解析函数、过滤函数)
  • 配置字段保留(schema 改后其他字段不变)

→ 完整开发流程、fork 工作流、_conf_schema.json 字段细节、LLM tool 文档路径、栗次元/figment 等外部 API 集成的具体配方见 references/plugin-dev.md

人格系统(Persona)

生效链路:

  1. 用户在 WebUI 保存人格 → 存入 AstrBot DB
  2. 群消息到达 → self_learning 插件 get_persona_id() 选择人格
  3. MemoryProcessor 加载人格提示词 → 注入 LLM system prompt
  4. LLM 按人格生成回复

关键坑:self_learning 插件有自己的人格选择逻辑,可能会覆盖 WebUI 中手动切换的人格。日志中看到 最终使用人格: XXX 才是实际生效的人格。如果切换了人格但群里没变,检查 self_learning 覆盖。

限定 Skill/Tool 到指定群

Persona 的 tools 和 skills 字段控制哪些 Tool/Skill 对该人格可用:

  • null / 不填 → 使用所有 Tool/Skill
  • [](空数组)→ 不使用任何 Tool/Skill(空白名单)
  • ["name1", "name2"] → 只使用列出的 Tool/Skill

结合会话规则(Session Rules)可以将一个绑定指定 Tool/Skill 白名单的人格绑定到某个群,实现「这个 Skill 只在 A 群可用」:

WebUI 操作步骤:

  1. 创建专用人格: WebUI → 侧边栏 人格 → 新建人格 → 在高级设置中设置 skills / tools 白名单(只勾选你要限定的 Skill)
  2. 确保默认人格不加这个 Skill: 默认人格的 skills 保持 null(全开)或 [](关闭),这样其他群看不到它
  3. 绑定到目标群: WebUI → 配置 → 会话管理(Session Rules)→ 找到目标群的 UMO(格式如 aiocqhttp:GroupMessage:群号)→ 编辑 session_service_config → 设置 persona_id 为人格名

查看当前群的 UMO: 在群里发 /sid,返回的 UMO 字符串就是该群的唯一标识。也可以用 /name <别名> 给群设别名方便在 WebUI 里检索。

生效链路:

消息到达 → persona_mgr.resolve_selected_persona() 检查 UMO 的 session_service_config.persona_id → 强制使用该 Persona → 只加载 Persona 配置的 skills 列表 → LLM 只能调这些 Skill

验证方法:

sudo journalctl -u astrbot --since "1 minute ago" --no-pager | grep -i "persona.*最终使用"

日志显示 最终使用人格: <你绑定的人格> + LLM 的 tools/skills 列表被过滤到只含白名单项。

源码确认(Persona 模型 /home/po/.local/share/uv/tools/astrbot/lib/python3.12/site-packages/astrbot/core/db/po.py):

class Persona(SQLModel, table=True):
    tools: list | None = Field(default=None, sa_type=JSON)
    """None means use ALL tools, empty list means no tools, otherwise a list of tool names."""
    skills: list | None = Field(default=None, sa_type=JSON)
    """None means use ALL skills, empty list means no skills, otherwise a list of skill names."""

通过 API 查看人格列表:

GET /api/persona/list  (Authorization: Bearer <token>)

人格存储位置:存在 SQLite DB(data_v4.db)里,不是文件系统 yaml/json。AstrBot 默认配置在 cmd_config.json 里只有两个相关字段:

  • provider_settings.default_personality: "..." — 默认人格名
  • provider_settings.persona_pool: ["..."] — 可用人格池

编辑入口:WebUI 侧边栏 → 人格(不是插件配置页)。要新建/编辑/切换默认人格都从这里进,不是写配置文件。Angel Heart 插件的 personality.ai_self_identity 是插件追加给 LLM 的补充系统提示,叠加在人格系统提示之上——两者都填才完整(人格 = 身份,插件 personality = 行为约束)。

知识库集成

配置在 /home/po/astrbot/data/cmd_config.json:

  • kb_names: ["盒武器"] — 使用的知识库列表
  • kb_agentic_mode: true — 让 LLM 可主动调用 KB 工具(推荐)
  • kb_fusion_top_k: 20 / kb_final_top_k: 5 — 检索参数

盒武器知识库: kb_id=c0ca81b9-f1f0-4479-9ce8-f6c3017958cf,Embedding: SiliconFlow BAAI/bge-m3。

注意:embedding_dimensions 对 bge-m3 应设为 0(硅基流动不支持该参数)。

添加 OpenAI 兼容模型提供商

AstrBot 支持通过 OpenAI 兼容 API 接入自定义模型(如 OpenCode Zen 免费模型)。

配置方式

在 WebUI 设置 → 大语言模型 → 添加模型源,或直接编辑 data/config/abconf_*.json:

provider_sources 添加源

{
  "provider": "opencode",
  "type": "openai_chat_completion",
  "api_base": "https://opencode.ai/zen/v1",
  "key": [""],       // ⚠️ OPENCODE 免费模型特例:见下方 Auth 坑章节,正确配置是 key: [](空数组)
  "id": "opencode",
  "enable": true
}

provider 添加模型(可选,预览模型时自动创建)

{
  "id": "opencode/deepseek-v4-flash-free",
  "enable": true,
  "provider_source_id": "opencode",
  "model": "deepseek-v4-flash-free",
  "modalities": ["text"],
  "custom_extra_body": {},
  "max_context_tokens": 20000,  // 免费模型通常20k
  "reasoning": false
}

OpenCode Zen 免费模型

模型名 上下文 说明
deepseek-v4-flash-free ~20K 通用编程
big-pickle ~20K OpenCode 官方免费
minimax-m2.5-free ~32K 科大讯飞
mimo-v2.5-free ~20K 小米开源
nemotron-3-ultra-free ~20K NVIDIA
north-mini-code-free ~20K 知乎开源

Auth 关键行为

OpenCode Zen 免费模型 POST /v1/chat/completions 的行为:

  • 不传 Authorization header → 200 OK(返回 cost":"0")
  • 传了任何非空 Authorization header → 401 Invalid API key. 或 403 error code: 1010
  • 免费的 /v1/models 列表不需要 auth(可以用来确认模型存在)

AstrBot 的 openai_source.py(第 360 行,v4.26.2):

self.chosen_api_key = self.api_keys[0] if len(self.api_keys) > 0 else None
  • key: [] → chosen_api_key = None → SDK 不发 Authorization header → ✅
  • key: ["***"] → chosen_api_key = "***" → SDK 发 Bearer *** → ❌ 401
  • key: [""] → chosen_api_key = "" → 新版 OpenAI SDK 不接受空字符串,抛错

新版 OpenAI SDK 不允许 api_key=None 或 api_key="",会直接报 Missing credentials 错误。需要在 ~/.config/astrbot/ 或系统层面设 OPENAI_API_KEY 环境变量为任意值绕过去。详见 references/opencode-auth-debug.md。

注意事项

  • api_base 必须 /v1 结尾:https://opencode.ai/zen/v1(不是 zen)
  • 免费模型上下文窗口小(20K-32K),日常对话够用但长文本会截断
  • 无速率保证:免费 tier 有隐式限速,超限等待即可
  • 可用模型列表:curl https://opencode.ai/zen/v1/models
  • 不传敏感代码:免费 tier 数据可能用于改进服务

常见故障

WSL PYTHONPATH 污染

Hermes Agent 设置 PYTHONPATH=/home/po/.hermes/hermes-agent 全局环境变量, WSL 中每个 Python 进程都继承此路径。症状:

  • pip install 产生 hermes-agent requires xxx 版本冲突警告
  • uv pip install --python 安装到错误位置
  • Python 进程加载 hermes-agent 依赖导致版本冲突

修复:启动任何 Python 命令前 unset PYTHONPATH。 在 systemd service 或启动脚本中也应主动 unset。

详见 references: 配置文件陷阱 | 人格系统详解 | Persona Skill 限域源码细节 | 音乐插件坑 | Bangumi 番剧订阅 | Whisper STT 配置 | IndexTTS/CosyVoice2 部署 | CosyVoice2 部署 | TTS 模型选型 | GPT-SoVITS Docker 部署 | 记忆/认知插件栈选型 | NVIDIA Rerank Provider 配置 | 远程服务隧道 | ComfyUI promax 插件 | LLM Provider 故障排查

  • 调试 / 配置 / 查询命令的参数应该接受自然语言输入,不要强制技术 ID — 用户在群里看到的是中文番剧名、用户别名,不是 subject_id=622206。第一版 /放送测试 描绘 报"未找到"是因为只接受 ID。修法:参数解析层先试 get_<thing>_name(target_id),miss 时 fallback 到 find_<thing>_candidates(group_id, target_id, limit=3):单候选自动取 ID,多候选列出来让用户选,零候选报"未找到"。复用已有的 fuzzy match 函数,0 行新逻辑。适用范围:任何 /<plugin>X <Y> 命令,凡是用户大概率输入中文/自由文本的,都该如此。

LLM/Provider 端故障排查("bot 不回我"、"bot 调了 tool 但没执行")

排查路径:QQ 网关 → AngelHeart 决策 → LLM 调用 → promax → ComfyUI。每层都有具体的 journal 特征和修复方式,详见 references/llm-provider-debugging.md。最常见的五个根因(按频率排序):

  1. /provider 是 session 级 — 在群 A 切到 M3 成功,群 B 仍走 free 档 5 次 429。修 cmd_config.json:233 default_provider_id 改全局默认

  2. antipromptinjector 静默封禁 admin — bot 完全不回你(antipromptinjector.main:1673 黑名单用户 ... 封禁已到期 是解封信号)。等 1 小时 / /unban / 加白名单

  3. AngelHeart "被呼唤"路径二次压制 tool 调用 — AngelHeart 决策"参与"但 LLM 只回文字不调 tool,bot 回"行吧给你画任务丢进去了"但 ComfyUI 0 got prompt。修复:promax 加 @filter.custom_filter(DrawCommandFilter) 装饰器,匹配 text.startswith("画"/"/画"/"t2i"/"复刻"/...) 直接走 submit_task,bypass LLM 整条决策链。50 行内,不动 AngelHeart,不动 LLM provider。 完整 patch 在 references/comfyui-promax-plugin.md 末尾"Command 路由绕过 LLM"段(2026-07-08 实测生效)

  4. M3 模型 docstring 服从性弱 — comfyui_txt2img docstring 写"You MUST translate"+ 中英对照 + tags 列表,M3 仍多次幻觉回文不调 tool。Prose 指令对 M3 不够用,必须 code-level 强制路由(@filter.command)。M3 会在回包时诚实承认:"我没法直接调 curl,我能用的是 comfyui_txt2img",然后还是不调 — 它嘴说"会调"和手发 tool_use 块是分开的两个决策

  5. SKILL.md 写"调 curl/terminal"没用 — AstrBot skills_like tool schema 模式下,LLM 只能看到 LLM-registered tools(comfyui_txt2img 这种),看不到 terminal/curl tool。M3 自描述:"我没法直接调用那个文件里的 curl 命令啊,我能用的是 comfyui_txt2img 这个 tool"。SKILL.md 的"调 curl POST /prompt"是写给自己看的提示词,不是工具。真要走 SKILL 路径,skill 必须注册成 @llm_tool 才有 LLM 可见的 tool schema

  6. SKILL.md 还需 _meta.json 才被 AstrBot sandbox 识别 — 只放 SKILL.md 在 data/skills/<name>/,AstrBot skills.json 不识别,LLM 看不到。{"ownerId":"local","slug":"<name>","version":"1.0.0","publishedAt":<unix_ms>} 最小 meta。少了 slug 字段就不出现 active=true

  7. ComfyUI Anima 不内嵌 CLIP/VAE — comfyui_txt2img 走 _build_comfyui_prompt 标准路径,Anima ckpt 加载后 clip=null,立即报 clip input is invalid: None。修法:检测 eng.workflow_prefixes["anima"],有就走 anima workflow(三节点 CLIPLoader+VAELoader+CheckpointLoaderSimple)。详见 comfyui-api skill 的 Anima 集成 pitfall 段

  8. promax @llm_tool + @filter.command 是两套路径 — @llm_tool(name="comfyui_txt2img") 走 LLM tool schema,被 LLM 调;@filter.custom_filter(DrawCommandFilter) 走 plugin filter,绕过 LLM。两条路径互不冲突,但 prompt 注入策略不同:tool path 需要 LLM 写 Danbooru 标签,command path 由用户直接写英文 prompt。同一 plugin 装两套后,aimg 抽烟白毛猫娘 走 tool path,"画 1girl, white_hair, cat_girl" 走 command path,后者成功率 100%(实测 0 幻觉)

排查路径(完整):QQ 网关 → AngelHeart 决策 → LLM 调用 → promax 内部 task_queue → submit_task → ComfyUI server POST /prompt。每层都有具体的 journal 特征:AngelHeart 决策日志在 [Plug] [INFO] [roles.front_desk:566] 决策为'参与' 行;LLM tool 调用见 [Core] [INFO] [provider.func_tool_manager:388] Added llm tool: <name> 启动行;promax submit_task 见 [Plug] [INFO] [ModComfyUI.*] 内部(注意 log_file_enable=false 时这些行不会进 journal);ComfyUI 端见 ssh server 'sudo journalctl -u comfyui --since "5 min ago" --no-pager | grep "got prompt\|clip input\|Prompt executed"'

M3 模型特性观察(2026-07-08 复刻白毛猫娘 session):

  • M3 在 AngelHeart "被呼唤回复"路径下,3 次都口头承诺"调 tool 给你跑"但实际 0 tool call
  • M3 在 skills_like 模式下会自描述 tool schema 限制("我没法直接调 curl"),不会硬编"调 curl 了"
  • 翻译中文 prompt:M3 不像 deepseek-v4-flash 会写英文,M3 直接编"我按 Danbooru 风格写"但实际可能传中文

远程服务隧道(SSH + systemd)

AstrBot 需要访问内网/无公网 IP 的远程服务(如实验室 ComfyUI 服务器)时,优先用 WSL systemd 管理 SSH 隧道,不要用 Windows 任务计划程序或 WSL 登录脚本。

原则

  • WSL 里跑 — ssh 客户端在 WSL 内,systemd 管理生命周期
  • Type=simple — 不加 -f(SSH fork 标志),让 systemd 直接控制进程
  • Restart=on-failure — 网络闪断自动重建
  • After=network-online.target — 确保网络就绪再连,避免开机时 SSH 隧道跑在网卡未就绪前

service 模板

[Unit]
Description=SSH Tunnel to <服务名>
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=po
ExecStart=/usr/bin/ssh -p <端口> -N -L <本地端口>:127.0.0.1:<远程端口> -o ServerAliveInterval=30 -o ExitOnForwardFailure=yes <user>@<host>
ExecStop=/usr/bin/pkill -f "ssh.*<host>.*<本地端口>"
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

关键参数:

  • -N:不执行远程命令(纯隧道)
  • -L <A>:<B>:<C> :本地端口转发,A:B:C = 本地监听端口:目标主机:目标端口
  • ServerAliveInterval=30:每 30s 发心跳保活 SSH 连接
  • ExitOnForwardFailure=yes:转发失败时退出(让 systemd 重启),避免 SSH 进程挂起

安装

sudo tee /etc/systemd/system/<name>.service << 'EOF'
...service content...
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now <name>

前提:SSH 密钥已配置且无密码。验证方法:

ssh -o BatchMode=yes -p <port> <user>@<host> "echo OK"

验证

curl -s http://127.0.0.1:<本地端口>/system_stats | head -c 200

cjxzdzh/astrbot_plugin_comfyui 配置

插件通过文件名约定将任意 ComfyUI 工作流封装为 LLM 可调用工具。详见 references/remote-tunnel.md。

记忆/认知插件选型

AstrBot 生态里有 livingmemory / self_learning / angel_heart + angel_memory / portrayal 等多套记忆/认知插件。多套并存会互相污染上下文(同条消息被记 N 次,召回时上下文打架)。当前推荐组合:Angel Heart + Angel Memory,把前两个禁用。

详细选型、provider 配置、rerank 选型、与人格系统的关系见 references/memory-plugin-stack.md。

1. LLM API 挂死导致 bot 不回复 症状:进程在跑但日志不再更新,10+ 分钟无新消息。 原因:LLM API 连接进入 CLOSE-WAIT 阻塞消息处理管线。 修复:sudo systemctl restart astrbot

2. 插件热加载后不生效 症状:插件目录有文件但未出现在已安装列表。 修复:调用 POST /api/plugin/reload-failed {"dir_name":"xxx"}

3. systemd 下插件文件修改不生效 症状:手动改了 plugins 目录下的 .py 文件,WebUI 也点了热重载但行为不变。 原因:systemd 管理的 AstrBot 进程跑的是内存中的代码。热重载通知运行中的进程重新加载模块,但 @filter.command generator 可能不会重新绑定。 修复:sudo systemctl restart astrbot。验证:看日志是否有对应代码路径的新日志行。

特例——修改 workflow_engine.py 等二级模块:AstrBot 热重载只重建插件实例(main.py 的 class),不会重新导入被主模块 import 的二级 .py 文件(Python 模块缓存机制)。修改任何 main.py 以外的插件文件后,必须 sudo systemctl restart astrbot 才能生效。

推送失败 'group' is not a valid MessageType 或 未找到匹配平台:这是 AstrBot v4 session 字符串构造错误。格式必须是 {cmd_config.json platform.id}:{GroupMessage|FriendMessage|OtherMessage}:{群号或用户ID} —— platform_id 是用户在配置里给 platform 起的名字(公仆这里是 default),不是 adapter 类名 aiocqhttp。枚举 context.platform_manager.platform_insts 找真 id 而不是猜。完整解剖 + 诊断流程见 astrbot-plugin-development/references/session-string-format.md。

3.5 验证代码改动是否真进了运行进程(不是改了文件就以为生效)

改完代码 → 怀疑没生效 → 不要凭印象走。先三步确诊:

# 1. 确认文件确实改过(避免编辑器没保存、buffer 同步错)
grep -n "aiocqhttp:GroupMessage" ~/astrbot/data/plugins/<plugin>/src/app/subscription_service.py

# 2. 确认 watcher 是否启动
PID=$(pgrep -f 'astrbot run' | head -1)
tr '\0' '\n' < /proc/$PID/cmdline | head
# 看不到 --reload → ASTRBOT_RELOAD 默认未启 → watcher 没启动
cat /proc/$PID/environ | tr '\0' '\n' | grep ASTRBOT_RELOAD
# 无输出 = env 没设,watcher 必然没起

# 3. 跑触发路径,journal 看新代码有没有出现
sudo journalctl -u astrbot --since "30 sec ago" --no-pager | \
  grep -E "<新代码路径的日志特征>"

永久开启 watcher(dev-only 推荐,生产保持关闭):sudo systemctl edit astrbot 加:

[Service]
Environment="ASTRBOT_RELOAD=1"

sudo systemctl daemon-reload && sudo systemctl restart astrbot。之后改 main.py 会自动重建 class 实例,但子模块仍要手动 restart(Python import 缓存)。生产前关掉 — 开发期 reload 频率高时撞 15min 轮询点会触发 session-closed traceback(详见 astrbot-plugin-development SKILL "Plugin reload 与 cron 触发撞点的 race" pitfall)。

dashboard API 手动 reload 单个插件(需要鉴权):

POST http://localhost:6185/api/plugins/reload
Header: Authorization: Bearer <dashboard token>
Body: {"name": "astrbot_plugin_xxx"}  # 用 metadata.yaml 里的 name 字段

等价于 sudo systemctl restart astrbot 但只动一个插件,代价是 plugin scope 鉴权;token 在 data_v4.db 表 api_keys 里查 key_hash 不便,可改 system unit 加 Environment="ASTRBOT_RELOAD=1" 走 watcher 路线。

3.6 fork → 上游 PR 的 CI 必坑(plugin-dev 也讲,2026-07-10 实测)

适用:自己有 fork (publieople/<repo>),改完 PR 回上游 (<upstream-owner>/<repo>)。

push 前自检(一次性跑完避免多轮 force-push):

cd ~/astrbot_plugin_bangumi
uvx ruff check . && uvx ruff format --check .   # 失败 → uvx ruff format . + commit amend
uvx --with mypy --with types-PyYAML mypy src main.py
uvx --with pyyaml --with pytest python -m pytest tests/test_project_manifest.py -q
git status --short                                # M 必须 add+amend, ?? 允许
git push --force-with-lease origin feat/xxx

CI 失败三件套:

  1. ruff format --check . 报 Would reformat — 本地 uvx ruff format . 后再 amend + force-push。坑:force-push 后还要再 amend 一次才能把 working tree 的格式化 diff add 进去(amend 经常漏掉 working tree 改动)
  2. pytest 红灯 + test 写死旧值 — 修复代码时同步改 dead test(tests/app/test_subscription_service.py:176 写死 aiocqhttp:group:group 这种)
  3. tests/test_project_manifest.py 报新命令未在 README 登记 — 用 AST 扫 main.py 的 @command,要求 README.md 指令表登记

完整 PR 提交 + force-push amend + 等 CI 循环详见 references/bangumi-plugin.md §5.3。

4. 人格切换不生效

症状:WebUI 切了人格但群内语气未变。 原因:self_learning 动态覆盖了选择。查看日志确认实际人格。

5. B站 API 412 — aiohttp TLS 指纹被拦截 / IP 风控

B站风控会检测 HTTP 客户端 TLS 指纹或封禁出口 IP。aiohttp(以及 Python urllib、requests)的 TLS 指纹与原生 curl 不同,导致搜索/用户信息等 API 返回 412 + HTML 风控页,即使 cookies 有效。

症状:

[Plug] [WARN] [BiliVideo/HTTP] HTTP GET https://api.bilibili.com/x/web-interface/search/type attempt 1 failed: bad JSON from ...

日志显示 bad JSON(API 返回 HTML 而非 JSON),但用 curl 带相同 cookies 能正常返回 JSON。

诊断:

curl -s --cookie "SESSDATA=xxx; bili_jct=xxx" \
  "https://api.bilibili.com/x/web-interface/search/type?page=1&search_type=bili_user&keyword=test" \
  | head -c 200

如果 curl 返回 JSON({"code":0,...})而插件报错,就是 TLS 指纹问题。

解决方案(按优先级):

  1. 切换 Clash 节点换 IP — B站搜索 API search/type 经常被整个出口 IP 封禁。切节点可能绕过
  2. 重新扫码登录 — 新 buvid3 能暂时绕过风控
  3. 将搜索端点从 search/type 换到 search/all/v2 — 实测 search/all/v2 风控力度更低
    • 两个 endpoint 要一起换:ENDPOINT_SEARCH_TYPE 和 ENDPOINT_SEARCH_TYPE_WBI
    • 新端点返回格式不同:data.result 是分类的结果列表([{"result_type":"bili_user","data":[...]}]),不是直接的用户列表
    • 需要改响应解析:遍历 data.result 找到 result_type == "bili_user" 的 sect,取 sect.data
    • 去掉 search_type=bili_user 参数(新端点不需要过滤参数)
    • 如果 aiohttp 仍被拦截,Python 插件中用 subprocess.run(["curl", ...]) + urllib.parse.quote() 兜底(curl 的 TLS 指纹不被 B站拦截)。注意 import urllib.parse 不要只写 import urllib,否则 urllib.parse.quote() 会抛 NameError
    1. curl_cffi 在 WSL 上不稳定,不推荐
  4. 终极方案 — 改用 RSS 轮询+OpenCC 订阅而非 B站 API 搜索

5. openpyxl 兼容性 Python 3.12+/3.14 上 Fill() 报错。用 zipfile + xml.etree 直接解析 xlsx。

6. STT 语音转文字(Whisper 自托管)

详见 references/stt-whisper-setup.md。

典型故障:WebUI 测试显示 "Provider xxx not found" → openai-whisper 未安装在 AstrBot 的 Python 环境。provider 源码顶部 import whisper 失败时静默跳过注册,日志无报错。

诊断:

~/.local/share/uv/tools/astrbot/bin/python3 -c "import whisper"

修复(用 AstrBot 工具自身的 pip,不要用 uv pip install --python):

unset PYTHONPATH
~/.local/share/uv/tools/astrbot/bin/python3 -m pip install openai-whisper \
  -i https://pypi.tuna.tsinghua.edu.cn/simple

⚠️ uv pip install --python <path> 会把包装到 uv 的内部 CPython base (~/.local/share/uv/python/),不进入工具的 site-packages (~/.local/share/uv/tools/astrbot/)。运行时 import whisper 仍会失败。

torch 约 532MB,网络慢时用清华镜像 + 600s 超时。安装后需 sudo systemctl restart astrbot。 日志应有 下载或者加载 Whisper 模型中 + Whisper 模型加载完成。device=...。

⚠️ device=cpu 陷阱: whisper_device: "cuda" 配置后,日志可能出现 device=cpu。这是 _resolve_device() 源码只处理 mps/cpu,"cuda" 被归类为 未知值回退到 CPU。见 reference 中的 patch workaround。

7. TTS 语音合成(本地 GPU 模式)

详见 references/indextts-setup.md 和 references/cosyvoice2-setup.md。

部署原则:

  • TTS 模型以独立 FastAPI 服务运行,AstrBot 插件只做 HTTP 客户端
  • 模型依赖复杂时,优先用 Docker 或 conda,不要死磕 uv/pip 环境
  • 遇到依赖卡住时,先评估替代方案的总成本(换模型、换部署方式),不要在一棵树上反复试

8. 升级后 dashboard 交互提示

v4.25→v4.26 升级后,首次 astrbot run 可能弹出 Install dashboard? [Y/n]: 交互式提示。 systemd 环境下无法交互,导致反复崩溃(auto-restart 死循环)。

修复:先手动跑一次 echo "y" | astrbot run 让 dashboard 装完,然后 sudo systemctl restart astrbot。

TTS 语音合成提供商配置

AstrBot WebUI 内置多个 TTS 提供商。选型前先查文档/源代码,不凭记忆猜 API。

内置提供商速查

提供商 本地/API 日语 声音克隆 费用 适用场景
GSV TTS(本地) 本地 ✅ ✅ 免费 7z整合包一键部署,GPU~4GB
FishAudio TTS(API) 云端 ✅ ✅ 免费额度 零部署,注册就有额度
Edge TTS 免费 ✅ ❌ 免费 不需要克隆时首选
阿里云百炼 TTS(API) 云端 ✅ ✅ 免费额度 CosyVoice/Qwen3-TTS
MiniMax TTS(API) 云端 ✅ ✅ 付费 商业级
火山引擎 TTS(API) 云端 ✅ ✅ 付费 字节跳动模型
Azure TTS 云端 ✅ ❌ 付费 微软标准
ElevenLabs TTS(API) 云端 ✅ ✅ 💰贵 效果最好但最贵

GSV TTS(本地) — GPT-SoVITS 部署

AstrBot 的 GSV TTS(本地) 连接到 GPT-SoVITS 标准 API(GET /tts 端点),默认 http://127.0.0.1:9880。

部署前必须查官方文档(README + api.py 参数),不凭记忆猜命令。

Docker 部署(推荐): 镜像内置模型,免模型下载和依赖安装。详见 GPT-SoVITS Docker 部署。

关键坑:

  • 镜像预装模型在 /workspace/models/pretrained_models/,但 config 指向的 GPT_SoVITS/pretrained_models/ 是空目录——需删目录后 ln -s 建立软链
  • ref_audio_path 是容器内路径,用 -v 挂载宿主机目录到容器
  • Docker compose 有多个 service 定义(含 Lite 版多了 ASR/UVR5 目录挂载),docker compose up 会校验全部 service 的 volume 是否存在——用 docker run 绕过

AstrBot 源码路径(排查参数时查阅):

/home/po/.local/share/uv/tools/astrbot/lib/python3.12/site-packages/astrbot/core/provider/sources/gsv_selfhosted_source.py

关键配置字段:api_base(默认 http://127.0.0.1:9880)、gpt_weights_path、sovits_weights_path、gsv_default_parms(传给 /tts 的额外参数,键名自动去掉 gsv_ 前缀)。

GSV TTS 配置参数详解

AstrBot 的 GSV TTS(本地) 提供商源码路径:

/home/po/.local/share/uv/tools/astrbot/lib/python3.12/site-packages/astrbot/core/provider/sources/gsv_selfhosted_source.py

API 端点: GET /tts(标准 GPT-SoVITS API)。

已知坑:

  1. .lower() 问题:GSV 提供商会把 default_params 的所有值 str(value).lower(),所以 ref_audio_path 中的路径会被转小写。容器内的路径必须兼容小写,或建立小写软链。

    • 例如:Docker 内实际路径 /workspace/GPT-SoVITS/reference_audio/xxx.wav
    • 被 .lower() 变成 /workspace/gpt-sovits/reference_audio/xxx.wav
    • 解决:容器内 ln -s /workspace/GPT-SoVITS /workspace/gpt-sovits
  2. 参考音频时长:GPT-SoVITS API 要求参考音频 3~10 秒。超出会返回 "Reference audio is outside the 3-10 second range"。

  3. 参考音频文本:prompt_text 越准确,声音克隆效果越好。不确定内容时用 whisper 转写:

    python3 -c "
    import whisper
    m = whisper.load_model('small')
    r = m.transcribe('path/to/audio.wav', language='ja')
    print(r['text'].strip())
    "
    
  4. 跨语言合成:日语参考音频 + text_lang=zh 可输出中文,反之亦然。GPT-SoVITS 支持跨语言零样本克隆。

GSV 默认参数(在 WebUI 中填写):

{
  "ref_audio_path": "/workspace/gpt-sovits/reference_audio/千早爱音.wav",
  "prompt_text": "あのー、もう始まってる?んっ、じゃあ改めてこんにちは、アノンです",
  "prompt_lang": "ja",
  "text_lang": "zh",
  "text_split_method": "cut0",
  "media_type": "wav"
}

注意: 参数字段在 WebUI 中显示为带 gsv_ 前缀(如 gsv_ref_audio_path),但源码中会自动去掉前缀。填不带前缀的键名。

GSV TTS 上下文配置项说明

WebUI 显示字段 实际 key 说明
参考音频文件路径 ref_audio_path 容器内绝对路径(会被 .lower())
参考音频文本 prompt_text 参考音频的台词内容
参考音频文本语言 prompt_lang zh / ja / en
文本语言 text_lang 要合成的输出语言
切分文本的方法 text_split_method cut0 不切(短句用)
输出媒体的类型 media_type wav / ogg / aac
语音播放速度 speed_factor 1.0 = 原速
生成语音的多样性 top_k 默认 15
核采样的阈值 top_p 默认 1
生成语音的随机性 temperature 默认 1

部署前查文档铁律

用户对此要求严格:任何不熟悉的工具/框架/部署流程,必须先查阅官方文档再给用户命令。

这是用户在对话中多次纠正的行为("你查一下文档再说"、"你看完完整文档再说")。正确的流程:

  1. 用户问「怎么配置X」→ 先找 X 的官方文档/README → 理解后再给出步骤
  2. 不要凭记忆或猜测写配置文件路径、API 参数、命令行参数
  3. 不确定的直接查文档或 man page,不要"我觉得应该是这样"
  4. 如果文档不完整,先读源码确认

本地 TTS 部署原则

  • 模型以独立 FastAPI 服务运行,AstrBot 插件只做 HTTP 客户端
  • 依赖复杂时优先 Docker 或 conda,不在 venv/pip 上死磕
  • 遇依赖卡住先评估替代方案——换模型/换部署方式比修依赖更快
  • 网络慢时用镜像(pypi.tuna.tsinghua.edu.cn)+ 设 UV_HTTP_TIMEOUT=300
  • WSL 的 PYTHONPATH 污染全局,启动任何 Python 前 unset PYTHONPATH

插件页面(Plugin Pages)开发

AstrBot 支持在 WebUI 中内嵌自定义页面。HTML 文件放入 pages/<page_name>/index.html,WebUI 自动扫描。

开发铁律:先读官方文档 https://docs.astrbot.app/dev/star/guides/plugin-pages.html,不猜 API。

API 存在的坑

以下 API 在 v4.x 中不存在,不要用:

  • filter.on_message() — 用 @filter.event_message_type(EventMessageType.ALL) 代替
  • filter.on_llm_response() — 不存在
  • EventMessageType 的导入路径:from astrbot.api.event.filter import EventMessageType,不是 astrbot.api.event
  • 语音消息没有独立事件类型,通过检查 message_obj.message 中的 Record component 识别
  • 新增 pages/ 目录后必须重启 AstrBot(热重载扫描不到新目录)
  • 插件页面在 iframe 中运行,不支持文件上传

注册 Web API 的正确格式

register_web_api 的 route 参数格式是 f"/{PLUGIN_NAME}/endpoint",不是 /plugin-page/{PLUGIN_NAME}/xxx。

from astrbot.api.web import json_response, error_response, request
PLUGIN_NAME = "astrbot_plugin_xxx"
context.register_web_api(f"/{PLUGIN_NAME}/voices", handler, ["GET"], "List")
# request.query.get("limit", 20, type=int)  — query 参数
# await request.json(default={})             — POST body
# json_response({"data": ...}) / error_response("message")

前端(pages/xxx/index.html)用 bridge SDK:

const bridge = window.AstrBotPluginPage;  // 自动注入,no import needed
const data = await bridge.apiGet("endpoint", { limit: 20 });
const result = await bridge.apiPost("endpoint", { key: "val" });

注意:Bridge 侧的 endpoint 不带插件名前缀——bridge 自动加。后端注册了 /{PLUGIN_NAME}/voices,前端调 bridge.apiGet("voices")。