# 雪色的陪伴插件-聊天侧
雪色的陪伴插件-聊天侧
面向 AstrBot 的持续陪伴编排插件。它把人格、生活状态、日程、私聊关系、群聊观察、主动消息、图片与语音、长期创作、外部能力和运行诊断组织到同一条长期体验中。 | 项目 | 当前信息 | | --- | --- | | 插件名 | astrbot_plugin_private_companion | | 显示名 | 雪色的陪伴插件-聊天侧 | | 版本 | 5.10.6 | | AstrBot | >= 4.22.0 | | 官方声明平台 | aiocqhttp、qq_official | | 管理入口 | AstrBot 插件拓展页中的“陪伴面板” | | 数据存储 | JSON,或可选 SQLite | > 这不是一个只会定时说早安、晚安的主动私聊插件。它更像 AstrBot 之上的“陪伴编排层”:Bot 先在自己的状态、日程、关系和见闻中形成想法,再判断此刻是否适合说、应该对谁说、用什么方式说。 详细版本变化见 [CHANGELOG.md](./CHANGELOG.md)。 ## 社区与支持 - 开发者:menglimi - 仓库:[menglimi/astrbot_plugin_private_companion](https://github.com/menglimi/astrbot_plugin_private_companion) - 问题反馈:[GitHub Issues](https://github.com/menglimi/astrbot_plugin_private_companion/issues) - 交流群:QQ 群 1097283005 - 自愿支持:[爱发电](https://ifdian.net/a/xuhaun) 捐款完全自愿,不影响任何功能。除上面的爱发电地址和群内作者本人外,不要向其他声称代表本插件的渠道付款。 ## 写在前面 **发版狂魔也是发到4.0了,遂决定写点什么** - 你好,我要一个有记忆、有生活、有自己的小秘密和想法、有喜怒哀乐和健康的bot。 - 这得装不少插件,先生。 - 我知道,再让它们之间能够互相影响。 怎么让bot更像人?在此之前已经有很多优秀的插件给出了自己的答卷,各类心理学应用、人格特质、复杂的理论…… 虽然开发者自身也是应用心理学专业毕业,但我觉得bot拟人只需要做好一件事,像人一样活着。听上去像是废话,但我做的只是进行自我观察。我的一天中,我会做什么,bot也应该会做什么。 对于一个拟人的bot而言,用户又何尝不是一个聊天bot?所以它应该会在自己的世界里生活,在生活里获取想和用户说话的“想法”,再在生活的空隙里把想法变为行动。 于是用户不止可以看到bot的早安和晚安,还能看到bot因为偶尔向窗外一瞥而专门为你记录下的照片、能看到bot因为好奇而自己私下搜索你在意的东西、能看到bot因为你昨天的提议而安排好周末的约会…… 在没和你聊天时,它可能在上学、在刷视频、在看报纸、在水群,甚至在偷看你的屏幕或者遵循世界观正在某个奇异世界中一边刷怪练级,一边想着等闲下来该和你分享点什么。 它会记得你,不只是你,还有哪些在私聊/群聊中的人,会记得他们的名字、他们的行为、他们的习惯、他们的联系,哪怕他们改了名字和头像,甚至在其他平台再次相遇。 它会看、会说、会创作、会成长、会睡觉、会做梦、会生情绪、会饿,还会偷吃你的token去看些涩涩的漫画。 这就是它,这就是我,若它足够像我,它便成了我。 ## 它解决什么 普通聊天以“当前这一轮”为中心;持续陪伴更关心“这个角色是否一直是同一个人”。 本插件围绕以下目标工作: - 让 Bot 拥有连续的生活状态、日程、位置、天气背景、梦境、日记、技能和个人目标。 - 让主动消息来自真实上下文,而不是随机问候模板。 - 在私聊、群聊、图片、语音、转发、QQ 空间和外部插件之间保持同一套身份与关系边界。 - 记录候选、拦截、改写、发送结果和 Token 消耗,便于解释“为什么发了”或“为什么没发”。 - 将高成本、强侵入或依赖外部服务的能力保持为可选项,缺失时局部降级。 它不会替代 AstrBot 的主回复人格。AstrBot 人格决定 Bot 是谁、如何说话;本插件提供当前生活、关系、记忆线索、动作能力和发送时机。 它也不是完整长期记忆数据库。本地包含轻量画像、片段、习惯、关系和自我时间线;需要大规模长期记忆、历史导入、知识图谱和权限化召回时,推荐联动“我会牢牢记住你”。 ## 能力全景 | 方向 | 主要能力 | | --- | --- | | 生活连续性 | 每日状态、日程、临近时段细化、位置连续性、天气、节假日、农历节气、睡眠、健康、饥饿、可选周期模拟 | | 私聊陪伴 | 主要用户/次要用户边界、称呼与语气、意图情绪、未完话题、轻量画像、主动触达和未回应降速 | | 主动行为 | 文字、图片、语音、戳一戳、识屏、外部能力、分段发送、引用触发消息、QQ 状态同步 | | 群聊理解 | 观察入口、群气氛、群友、黑话、话题线、片段记忆、关系网、自然续接、兴趣唤醒、主动插话 | | 多模态 | 私聊图片、GIF 抽帧、引用图片、合并转发、参考图生图、今日穿搭、TTS、撤回消息短期转述 | | 内容生活 | 新闻、AI 日报、主动搜索、B 站见闻、QQ 空间、梦境、日记、私下创作、书柜和备忘便签 | | 成长与记忆 | 技能成长、非创作型个人目标、表达学习与审核、重要日期、关系观察、Bot 自我时间线 | | 管理与诊断 | 14 个面板页、模型分流、在线生图端点测试、Token/余额、配置迁移、主动审计和插件专家答疑 | 多数真实外部动作默认关闭。建议先跑通文字、状态、日程和私聊关系,再逐项开启图片、语音、识屏、QQ 空间等能力。 ## 安装 ### 插件市场 在 AstrBot WebUI 的插件市场搜索: ~~~text astrbot_plugin_private_companion ~~~ 安装后重启 AstrBot。 ### Git 安装 在 AstrBot 插件管理中选择从 Git 安装,填写: ~~~text https://github.com/menglimi/astrbot_plugin_private_companion ~~~ ### 手动安装 将仓库目录放入 AstrBot 插件目录,并确保目录名为: ~~~text astrbot_plugin_private_companion ~~~ Windows 常见位置: ~~~text C:\Users\你的用户名\.astrbot\data\plugins\astrbot_plugin_private_companion ~~~ 插件启停由 AstrBot 官方插件开关负责。旧版配置中的 enabled 字段已经废弃。 ## 10 分钟完成首次配置 第一次使用建议打开“陪伴面板”,点击右上角“配置引导”,然后按下面顺序配置。 1. 在“总览”确认插件已加载,没有明显错误。 2. 在“世界知识”确认主回复人格来源。只补充角色资料、世界观资料和关系背景,不要把 AstrBot 主人格原样复制一遍。 3. 在“模型”先使用快速配置:选择快速模型、复杂模型、创作模型和视觉模型。暂时不需要逐任务分流。 4. 在“配置”填写 Bot 名称、时区、免打扰时间和目标私聊用户。 5. 在“私聊”检查目标用户,把真正的管理员/核心陪伴对象设为“主要用户”。 6. 私聊发送 陪伴 状态。能看到状态、日程、关系角色和下次主动候选,说明基础链路已通。 7. 需要群聊时,在“配置”开启群聊观察,并在“群聊”把目标群加入白名单。然后在群里发送 陪伴群 状态。 8. 最后逐项开启 TTS、生图、识屏、戳一戳、新闻、搜索、QQ 空间或外部记忆。 不要第一次就打开全部开关。主动、图片、语音和后台整理都可能增加模型调用量,也会扩大排障面。 ### OneBot 与 QQ 官方身份 - OneBot/aiocqhttp 私聊目标通常填写数字 QQ。 - QQ 官方机器人填写 openid/平台用户 ID,不要把数字 QQ 当作 openid。 - 多 Bot 环境建议把 /sid 返回的完整 UMO 写入“私聊主动发送目标映射”,例如: ~~~text 主用户ID=qq_official:FriendMessage:openid ~~~ - 同一用户跨平台共用陪伴资料时,使用“私聊身份别名归并”明确映射,例如: ~~~text openid=主用户ID ~~~ - 插件不会仅凭昵称自动合并身份。 - “主要用户”会获得插件管理权限,但权限只认真实发送者 ID;身份别名不会把另一个发送者一并提升为管理员。 ## 核心工作方式 ### 被动回复 收到普通消息后,插件按需要组装以下上下文: 1. 稳定层:AstrBot 人格、回复风格、身份和关系边界。 2. 当前层:时间、平台、会话类型、Bot 状态、日程、位置、天气和正在进行的活动。 3. 关系层:当前用户角色、固定称呼、关系阶段、可靠画像和未完话题。 4. 内容层:图片摘要、引用归属、合并转发、群聊场景、记忆包和外部能力结果。 5. 发送前层:重复检查、事实归属、隐私边界、异常文本保护、TTS 与分段处理。 稳定内容尽量保持在提示词前部,动态内容后置,以减少对 Provider prompt cache 的破坏。 开启“仅保留主动能力”后,插件会放行普通被动链路,只保留自己的主动调度;需要临时排障时,可在面板按功能短时解锁被动能力。 ### 主动消息 主动消息不是一个随机定时器,而是候选生命周期: ~~~mermaid flowchart LR A[生活与外部事件] --> B[形成主动候选] B --> C[时间窗与价值评分] C --> D[用户/关系/免打扰/休息/繁忙/未回应边界] D --> E[人格判断与动作选择] E --> F[生成正文或执行动作] F --> G[发送前复核] G --> H[平台发送] H --> I[审计、记忆与下一次排程] ~~~ 主要候选来源包括: - 当前日程和细化模型生成的生活事件。 - Bot 实际醒来后的早间问候、午间/晚间锚点和低频饭点关心。 - 用户明确约定、AstrBot future_task、到期便签和临时提醒。 - 当前状态、情绪余波、未完话题、关系变化和用户习惯。 - 重要日期、技能成长和非创作型个人目标进度。 - 群聊公开话题、主要用户群聊活动和晚安后再次活跃。 - 及时天气突变。 - 新闻、AI 日报、B 站见闻、主动搜索和 QQ 空间事件。 - 梦境、日记、私下创作和作品阶段性进展。 - 其他插件注册的外部主动能力。 候选还需要通过每日上限、最小间隔、免打扰、用户休息、Bot 休息、繁忙日程、未回应降速、Token 硬限额、关系边界和发送前复核。面板“主动”页会保留来源、时间窗、状态、拦截原因和发送诊断。 “主动强度预设”只覆盖运行时有效频率,不改写手动参数。即使使用最高档,也不会绕过免打扰、用户拒绝、隐私边界、休息状态和 Token 硬限额。 ### 日程、状态与位置 - 每日状态描述精力、情绪、睡眠、健康、饥饿、周期和状态余波。 - 每日日程提供当天框架;临近某一段时,细化模型补充具体活动、地点、状态变化、可分享碎片和主动契机。 - 细化地点包含依据与置信度,并优先于旧剧情或关键词推断。 - 地点切换应写出移动过程,避免同一时刻同时位于宿舍和工作地点。 - 用户本轮明确指定的自拍场景优先于旧日程地点。 - 睡眠回复闸门和繁忙回复闸门默认关闭。繁忙闸门只延迟普通回复,不丢消息;临时提醒、到期便签、环境突变和排障保持及时。 - 可选六阶段周期策略只柔性影响 Bot 的状态与表达,不生成医学结论,也不把周期状态套到用户身上。 ### 私聊用户角色 每个私聊对象可以是: - 主要用户:核心陪伴对象,同时视为本插件管理员。可使用主要用户专属关系、书柜夹层、私密阅读、独立生图、识屏和跨群转述等能力。 - 次要用户:普通朋友边界。不会继承主要用户或恋人称呼,不会读取主要用户专属隐私,主动消息默认更低频。 用户还可以单独设置称呼、语气、每日主动额度、主动开关和精确投递会话。 ### 群聊 群聊能力由“观察”“唤醒”“续接”和“主动插话”四层组成: - 观察:记录允许群内的文本及图片、语音、视频、分享卡片、文件等可读占位;可选开启“群聊图片理解”,在后台生成带内容缓存的视觉摘要。 - 理解:维护群气氛、成员观察、黑话、话题线、群聊片段和互动关系。 - 唤醒:识别 @、Bot 名称、强唤醒词、主要用户专属词、问题信号、兴趣词和冷群信号。 - 续接:用户叫过 Bot 后,判断后续未继续 @ 的消息是否仍在对 Bot 说话,并限制连续轮数。 - 插话:按概率、冷却、每日上限、场景和关系边界选择是否主动加入。 白名单模式下,白名单为空表示观察范围为零。其他插件提前停止回复或本群关闭 LLM 回复时,群聊观察入口仍可记录消息,但不会强行恢复回复。 “群聊图片理解”默认关闭。开启后只处理已允许观察的群,普通群消息不会等待视觉模型;仅当该消息确实触发回复时,主链才有限等待摘要,超时后仍会继续回复且后台识图不会取消。摘要单独保存在群观察的视觉字段,不会覆盖原始发言,也不会作为表达、黑话或关系事实学习素材。相同图片按内容缓存复用,插件只保留摘要和压缩预览,不长期保存原始群图。建议关闭 AstrBot 官方“自动理解图片”,避免同一张图重复识别。 群友身份以稳定 QQ/平台 ID 为主,昵称、群名片、别名和自称只作辅助,避免改名或玩笑自称导致串人。 ### 记忆、关系与表达学习 - 本地轻量记忆:用户画像、偏好、习惯、对话片段、未完话题、关系状态和 Bot 自我时间线。 - 关系网:维护稳定身份、别名、群资料、重要记忆、边界备注和待确认观察。 - 表达学习:从允许的私聊和群聊归纳短表达、句法和情境风格;昵称、账号、关系事实、秘密和长句不会作为表达规则照搬。 - 表达审核:待审核规则不会进入回复,审核与表达库在学习页内分开切换;待审核和已启用规则都可编辑名称、情境、表达模板、句法、召回标签与适用边界,证据和使用统计保持只读。 - 技能成长:模拟 Bot 对技能的熟悉程度,并可影响日程安排。 - 个人目标:用于非创作型长期目标,只按真实完成的日程推进,不凭空宣告完成。 关系事实与表达风格是两类数据:关系事实进入关系网或记忆,表达学习只保存“怎么说”。 ## 陪伴面板 | 页面 | 用途 | | --- | --- | | 总览 | 今日状态、当前活动、日程时间轴、近期动向、记忆概况、新闻和主动搜索 | | 世界知识 | 主人格来源、角色/世界/用户资料、AstrBot 知识库引用和世界观转写 | | 私聊 | 私聊对象、主要用户角色、称呼、主动额度、投递会话和用户级诊断 | | 群聊 | 观察名单、群气氛、群友、黑话、话题、片段、插话反馈和 LLM 状态 | | 学习 | 三个主导航:技能、表达、关系;表达库和审核队列可单独切换 | | 观察 | 梦境、当前扮演状态、原始状态、日记碎片、状态变化和记忆构成 | | 主动 | 候选统计、来源分布、状态分布、任务记录、拦截与发送诊断 | | 书柜 | 创作、日记、私密阅读、封面/批注、阅读状态和备忘便签 | | QQ 空间 | Cookie 状态、说说、评论、发布与联动诊断;QQ 官方通道不可用 | | Token | 插件任务、Provider、缓存命中、主链会话、余额和外部插件消耗 | | 排障 | 运行检查、最近注入、主动测试、图片链路、SQLite 状态和常见问题 | | 配置 | 常用配置、名单、迁移备份、存储、页面设置、运行设置和功能开关 | | 模型 | 快速/精准模型分流、生图端点队列、端点测试、超时与回退关系 | | 实验 | 人格标准化问卷、情绪/动机等明确标记为实验性的能力 | 配置页带未保存更改保护。离开页面、返回功能列表或刷新前会提示;功能开关详情和列表中的修改会一起保存。 ## 模型与成本 ### 快速配置 快速模式用少量基础模型覆盖大多数任务: - 快速模型:轻量判断、TTS 文本转换、回复复核、智能沉默等低延迟任务。 - 复杂模型:日程、细化、关系、记忆、合并转发、答疑等推理任务。 - 创作模型:梦境、日记、作品正文、大纲和审校。 - 视觉模型:私聊图片、合并转发图片、群图安全判断和私密阅读。 ### 精准配置 精准模式可以分别指定日程、细化、梦境/日记、创作正文、大纲、审校、主动人格判断、回复复核、关系分析、情绪判断、长期画像、对话片段、群聊插话、群片段、黑话、合并转发、新闻、主动搜索和视觉任务。 留空的任务会沿回退关系使用基础模型或 AstrBot 默认 Provider。面板模型页会显示实际回退来源。 ### DeepSeek 峰时替换 可开启 DeepSeek 峰时替换,在配置的高价时区窗口内,把命中的 DeepSeek 任务临时路由到“峰时替换模型”。该功能只改运行时选模,不改写原 Provider 配置。 ### Token 限额 - 硬限额达到后,插件停止新增内部 LLM 任务;填 0 表示不限制。 - 软限额达到后,优先保留用户当前触发的回复和关键处理,暂缓新闻、搜索、创作、群聊整理、复核和生图提示词等低优先级后台任务。 - Token 页单独展示 AstrBot 主链、记忆插件和“一起房间”等外部来源;外部插件统计不并入本插件限额。 - 实际成本取决于群数量、消息活跃度、细化频率、复核策略、图片与创作能力,不建议依据固定日耗估算。 ## 图片能力 ### 输入理解 插件可处理私聊单图、带文字图片、引用图片、GIF 抽帧和合并转发中的图片。视觉摘要会记录画面、文字、情绪、用途和图片归属线索,避免把 Bot 主动发送的图片误认成用户作品。 ### 生图入口 - 主动生活图片、自拍和作品分享。 - 每日穿搭图。 - 主要用户明确提出的自然语言生图或改图。 - LLM 工具 pc_generate_photo。 - QQ 空间配图和创作封面。 ### 额度 - “每日主动生图最多次数”只限制 Bot 自己发起的主动图片,0 表示不限量。 - “用户请求生图/改图每日上限”同时限制陪伴生图/自拍/改图指令与 pc_generate_photo 工具,默认 0 表示不限量。 - “规则快判生图/改图每日上限”只作用于 rule_fast 前置接管,0 表示关闭规则快判生图。 - 三套额度独立计数;每日穿搭、QQ 空间配图和创作封面仍按各自开关与冷却运行。 ### 后端 | 后端 | 说明 | | --- | --- | | 自动 | 在线图片 API 失败后回退 ComfyUI,再回退 SDGen | | 在线图片 API | 支持 OpenAI 兼容、Agnes、SenseNova 日日新、百炼、魔搭、豆包/火山方舟和 Gemini | | ComfyUI | 文生图和自拍工作流分开配置;参考图能力取决于工作流 | | SDGen | 复用运行中的 SDGen/Stable Diffusion WebUI;当前按纯文生图使用 | | 函数工具 | 调用其他 AstrBot 插件注册的图片工具 | 在线 API 可以配置多端点队列、顺序、超时、自定义请求头、下载代理和单卡测试。测试当前端点时不会自动切换到其他后端。 ### 参考图 - 参考图一致性默认关闭。 - 可配置基础人设图和最多 24 张带用途注释的参考图库。 - 注释建议写明服装、地点和适用场景,例如“米白睡衣,在家、卧室、睡前使用”。 - 用户本轮发送或引用的改图图片优先级最高。 - 明确的服装与场景请求高于今日穿搭连续性。 - 今日穿搭只在外出、通勤、上学、逛街或明确展示当日穿搭时优先。 - OpenAI edits、Agnes、Gemini 和正确配置的 ComfyUI 工作流可用于参考图;SenseNova U1 Fast、SDGen、魔搭和豆包当前按纯文生图使用。其他平台以模型页实测结果为准。 常用命令: ~~~text 陪伴 生图 <画面描述> 陪伴 自拍 [画面要求] 陪伴 改图 <修改要求> # 同时带图或回复图片 陪伴 今日穿搭图 陪伴 生成穿搭图 陪伴 参考图 <路径|URL|查看|清空> 陪伴 参考图库 添加 <用途注释> 陪伴 参考图库 列表 陪伴 参考图库 预览 <编号> 陪伴 参考图库 删除 <编号> 陪伴 参考图库 清空 陪伴 查看生图API 陪伴 切换生图API ~~~ ## TTS 与语音 TTS 强化负责文本和语音块的编排,真正合成音频仍需要 AstrBot 当前会话有可用 TTS Provider。 可配置: - 语音替换文字,或语音与文字都发送。 - 外语语音后保留原文,或补中文释义。 - 局部转换,或朗读整条回复的全部有效内容。 - 快速标签模式,或发送前后处理模式。 - 私聊/群聊独立触发概率和最小间隔。 - 自动语音、主要用户语音偏好和提及关键词。 - Fish Audio S2.1/S2/S1 模型与情绪控制策略。 - 可选联动 `MiMo TTS Voice Clone for AstrBot`:由本插件决定语音内容和发送形态,克隆参考音频、音色与默认风格继续由 MiMo 插件管理;主动语音以及“我会和你在一起”的电话/共同观影实时语音会复用同一后端。 - 本机播放与直播打字机字幕同步。 TTS 标签会在发送前清理,模型内部判断、控制标签和工具回执不会直接显示。定时任务通过 send_message_to_user 发送时,普通文本走 AstrBot 原始工具,TTS 文本由插件处理后直接投递。 使用 MiMo Voice Clone 联动时,建议关闭 MiMo 插件自身的普通回复自动转语音,让陪伴插件统一负责触发、文本转换和发送,MiMo 只负责克隆合成,避免同一回复出现两条语音。`mimo_tts_speak` 需要保留注册供桥接发现,但不必开放给主模型直接调用。 ## 书柜、日记与便签 - 日记由当天状态、日程、梦境、交互、见闻和创作进展整理,可选择体裁、长度、创作度和自定义方向。 - 私下创作可从梦境、生活小事或日记碎片立项,支持小说、诗、随笔、短剧、分镜、角色设定和世界观片段。 - creative_direction_prompt 可自定义每日创作方向。 - 作品维护大纲、角色、记忆池、审校结果、修改记录、封面和阶段性分享。 - 书柜收纳创作、日记和可选私密阅读内容。 - 备忘便签支持新增、查看、修改、完成、恢复、置顶、删除、到期提醒和日/周/月/年重复。 “便签/备忘/待办”和“临时提醒”是两条路线:明确便签请求使用 pc_manage_memo;普通“半小时后提醒我”优先使用 AstrBot future_task。同一请求不会同时创建两份提醒。 ## 可选联动 基础文字陪伴可以独立运行,下面的插件和服务都不是硬依赖。联动生效通常需要同时满足三件事:外部插件已经安装并启用、本插件中的对应开关已开启、当前平台支持这项动作。任一条件不满足时,只跳过相关能力,不应阻塞普通聊天。 不建议为了“功能齐全”一次安装全部联动。按实际需求选择即可: | 需求 | 建议组合 | | --- | --- | | 先跑通基础陪伴 | 只安装本插件,配置人格、主要用户和模型 | | 加强跨会话连续性 | 增加“我会牢牢记住你” | | 打电话、共同观影 | 增加“我会和你在一起” | | 识屏、天气与昨日活动背景 | 增加“我会一直看着你” | | 获得更多视频见闻 | 增加 Bilibili AI Bot | | 已在使用另一套主动调度 | 开启 Proactive Chat 联动,统一防撞和发送结算 | ### 系列插件 | 插件 | 接入内容 | 启用与边界 | | --- | --- | --- | | [我会牢牢记住你](https://github.com/menglimi/astrbot_plugin_memory_companion) | 长期记忆、历史聊天导入、权限召回、情绪连续性、梦境碎片和未完成话题 | 推荐的记忆中枢;在“外部记忆插件协同”中统一控制。本插件仍负责即时状态、日程、关系和群聊气氛 | | [我会和你在一起](https://github.com/menglimi/astrbot_plugin_together_companion) | 浏览器语音/可视通话、共同观影和实时语音 | 通过扩展 API 读取稳定 Bot 身份、QQ 头像、场景和 TTS;共同活动期间会协调无关主动消息 | | [我会一直看着你](https://github.com/menglimi/astrbot_plugin_screen_companion) | 主动看屏幕、天气回退和昨日观察日记 | 三项能力分别控制。实时识屏默认关闭;昨日摘要会脱敏、限长,不会读取当天实时屏幕作为日程事实 | | [我会直播圈米养你](https://github.com/menglimi/astrbot_plugin_live_stream_companion) | 直播共处、开播/下播主动行为和字幕协同 | 由直播插件注册外部主动能力;本机播放与直播打字机字幕需要在语音配置中单独开启 | ### 第三方插件桥接 | 插件 | 接入内容 | 启用与边界 | | --- | --- | --- | | astrbot_plugin_proactive_chat | 复用其即时主动调度 | 联动开关默认开启;深度桥接会在生成前共享关系与状态并防撞,生成后统一复核和发送结算,不修改对方源码,也不创建第二套定时任务 | | [Bilibili AI Bot](https://github.com/chenluQwQ/astrbot_plugin_bilibili_ai_bot) | 观看日志、视频记忆和无聊时刷视频 | 读取正式插件公开的日志/API;是否触发观看、分享以及最低间隔由“B 站联动”配置控制 | | [智能图片对话](https://github.com/QingchenWait/astrbot_plugin_smart_imagechat_hub) | 已有表情包和反应图检索 | 可向模型提供 pc_find_reaction_image;不会把本插件生成的私密图片自动导入图库 | | [PokePro](https://github.com/Zhalslar/astrbot_plugin_pokepro) | OneBot 主动戳一戳 | 需要开启主动戳一戳并由当前协议端提供能力;QQ 官方机器人会跳过 | | [LivingMemory](https://github.com/lxfight-s-Astrbot-Plugins/astrbot_plugin_livingmemory) | 长期记忆工具召回 | 保留兼容;工具名默认是 recall_long_term_memory。若同时检测到“我会牢牢记住你”,优先使用系列插件桥接 | | [JM-Cosmos II](https://github.com/GEMILUXVII/astrbot_plugin_jm_cosmos) | 私密阅读素材和书柜夹层 | 仅主要用户可用,默认关闭;没有可读素材时不会虚构阅读行为 | ### 生图后端 生图后端属于可替换的执行层,不会改变人格、主动调度或图片归属判断。在线图片 API 不要求额外安装 AstrBot 插件;本地后端可选 [AstrBot ComfyUI](https://github.com/cjxzdzh/astrbot_plugin_comfyui) 或 astrbot_plugin_SDGen,[NAI Image](https://github.com/woakato/astrbot_plugin_nai_image) 可作为 OpenAI Images 兼容代理。端点顺序、参考图能力和失败回退统一在“模型”页配置,具体差异见上文[图片能力](#图片能力)。 ### 外部服务与平台能力 - 天气:优先使用本插件配置的 OpenWeatherMap;没有独立 Key 和地点时,可回退到“我会一直看着你”。城市优先于经纬度,天气不可用时只缺少环境背景。 - QQ 空间:这是本插件内置的 OneBot 能力,不要求另装 QQ 空间插件,但需要有效 Cookie 和可用的 aiocqhttp/OneBot 实例。 - QQ 官方机器人:不支持 QQ 空间、戳一戳、原生撤回、指定消息引用和合并转发。插件按每条事件自动降级,不需要手动选择平台模式。 ### 功能重叠 以下插件可以共存,但同时开启同类功能会造成重复上下文或重复工具: | 已安装插件 | 与本插件重叠的能力 | 建议 | | --- | --- | --- | | [LLMPerception](https://github.com/miaoxutao123/astrbot_plugin_LLMPerception) | 环境感知 | 二选一作为主要环境上下文来源 | | [Context Aware](https://github.com/muyouzhi6/astrbot_plugin_context_aware) | 群聊场景感知 | 避免两边同时注入完整群聊场景 | | [AT Relay](https://github.com/Alien-Star/astrbot_plugin_atrelay) | 跨群转述和 @ 群友工具 | 保留一套同名用途工具,减少模型误选 | 安装或更新联动插件后,可在陪伴面板“配置”页打开对应功能卡,查看“依赖”“当前使用”和开关状态;外部记忆状态可在“观察”页确认,主动联动与失败原因可在“主动”和“排障”页查看。只检测到目录并不代表联动已经可用,外部插件本身还必须成功加载并暴露相应接口或工具。 ## 常用命令 ### 私聊管理 ~~~text 陪伴 状态 陪伴 查看主动判定 陪伴 能力列表 陪伴 昵称 <称呼> 陪伴 语气 <简短描述> 陪伴 TTS语种 日语|中文|英语|默认 陪伴 撤回消息 陪伴 清空记忆 陪伴 重置插件 ~~~ 重置插件会清空插件状态并重建当天数据;不要把裸“重置”当作该命令。 ### 日程、状态与内容 ~~~text 陪伴 生成状态 陪伴 增添状态 <状态描述>[|持续小时] 陪伴 查看今日日程 陪伴 重置日程 陪伴 重置日程 <时间|序号|活动名> 陪伴 删除日程 <时间|序号|活动名> 陪伴 当前细化 陪伴 重置细化 陪伴 梦境 陪伴 梦境碎片 陪伴 日记 陪伴 生成日记 陪伴 日期列表 陪伴 日期添加 <标题> [备注] 陪伴 日期删除 <关键词> 陪伴 可做事项 陪伴 新闻 陪伴 AI日报 ~~~ ### 记忆与诊断 ~~~text 陪伴 画像 陪伴 记忆 陪伴 表达学习 陪伴 气氛 陪伴 片段 陪伴 删除话头 <关键词|全部> 陪伴 长期记忆 陪伴 查看提示词 日程|细化|主动|回复注入 陪伴 答疑 <问题> 陪伴 答疑确认 陪伴 答疑取消 陪伴 答疑设置 <配置项|中文名> <值> ~~~ 答疑建议使用“发生位置 + 实际行为 + 大概时间”,例如: ~~~text 陪伴 答疑 今天上午为什么没有主动消息 陪伴 答疑 刚才群里 @ 了 Bot,为什么没有回复 陪伴 答疑 私聊发图后一直没有进入识图 ~~~ 只有明确询问开关、配置或参数时,答疑才会生成待确认的修改建议。 ### 群聊命令 ~~~text 陪伴群 状态 陪伴群 黑话 陪伴群 群友 陪伴群 话题 陪伴群 片段 陪伴群 插话反馈 陪伴群 关系网 陪伴群 撤回消息 陪伴群 LLM状态 陪伴群 关闭LLM 陪伴群 开启LLM 陪伴群 开启 陪伴群 关闭 ~~~ 群聊 LLM 开关和群聊观察开关是两件事。关闭本群 LLM 回复后,允许范围内的观察数据仍可继续记录。 ## 数据、权限与安全 ### 存储 - JSON 是默认兼容模式,保存到插件数据目录。 - SQLite 按 section 保存主数据,适合数据量较大或希望数据库化管理的场景;首次切换前建议先导出配置。 - 插件会为可识别 SQLite 数据库尝试启用 WAL、busy timeout 和常用并发参数。 - 启动维护会清理过时格式、无效控制标签、低质量旧记录和超期临时缓存,不会无条件删除正常对话数据。 ### 配置迁移 “配置 → 配置迁移”支持: - 按模块导出可迁移配置。 - 校验备份完整性。 - 导入前预览差异。 - 合并或覆盖冲突。 - 导入前自动备份。 - 查看并恢复最近自动备份。 默认迁移包不包含 API Key、Provider 密钥、Token 统计、图片缓存、最近消息、审计日志和临时队列。 ### 边界 - 插件管理命令只允许 AstrBot 管理员或真实 ID 标记为“主要用户”的发送者。 - 群聊资料、私聊资料和 Bot 自我状态分开处理。 - 次要用户不会获得主要用户专属私密上下文。 - 昨日屏幕日记会移除窗口标题、账号和具体聊天内容。 - 出站文本会脱敏常见密钥、清理内部控制标签并阻止框架错误摘要直接进入聊天。 - 群聊关系网的待确认观察不会自动写入长期记忆。 - 公开 QQ 空间内容不会使用私聊隐私、关系网内部备注或原始状态数值。 ## 排障 先打开“陪伴面板 → 排障”,再看 AstrBot 日志。高价值检查顺序: 1. 插件是否加载、版本是否为预期版本。 2. 当前用户/群是否在允许范围,角色和真实 UMO 是否正确。 3. 对应功能是否开启,子配置是否因父开关关闭而未生效。 4. 任务实际使用哪个 Provider,是否超时、进入回退或被 Token 限额跳过。 5. 主动候选是否存在,时间窗、免打扰、休息、繁忙、未回应和复核状态分别是什么。 6. 平台是否支持目标动作。 7. 外部插件是否只存在于磁盘,还是已经加载并暴露运行接口。 常见现象: | 现象 | 优先检查 | | --- | --- | | 完全没有主动消息 | 私聊用户启用状态、主要/次要角色、下次候选、免打扰、未回应降速、每日上限 | | 群聊收不到观察 | 群聊总开关、白名单是否为空、目标群是否启用 | | 配置刷新后恢复旧值 | 页面是否显示未保存更改、是否点击悬浮保存栏、AstrBot 配置是否持久化成功 | | TTS 只有文字 | 当前会话 TTS Provider、TTS 强化开关、触发概率和最小间隔 | | 生图没有参考一致性 | 参考图开关、最终选图日志、后端是否真正支持参考图 | | 在线生图 401/403 | 平台类型、官方 Model ID、API Key 权限、套餐/Token Plan、请求地址 | | QQ 官方主动失败 | 完整 UMO、openid、最近可用路由和平台额度/时间窗 | | Bot 把图片作者认反 | 图片来源、上一条 Bot 主动图片记录、引用链和视觉摘要中的归属字段 | | 主动候选很多但不发送 | 候选状态、有效窗口、重复合并、发送前复核和平台发送诊断 | ## 开发者接入 插件导出轻量扩展 API: ~~~python from data.plugins.astrbot_plugin_private_companion.main import get_private_companion_api api = get_private_companion_api() ~~~ API 提供: - 注册、取消和列出外部主动能力。 - 读取当前 TTS 语种与实时语音配置。 - 复用陪伴 TTS 规则合成实时语音。 - 获取稳定 Bot 身份、QQ 头像候选和多 Bot 歧义状态。 - 获取结构化场景:状态、日程、位置、天气、穿搭、关系和共同活动。 - 登记通话、共同观影等外部活动,临时协调普通主动消息。 - 为 Proactive Chat 执行预检、复核、发送结算和取消。 - 为历史聊天导入解析稳定身份,并暂存/回滚关系观察。 注册外部主动能力示例: ~~~python async def my_executor(ctx): return { "ok": True, "context": "外部插件完成了一次适合分享的动作。", "summary": "外部动作", "memory": "这次动作留下的内部印象。", } if api: api.register_proactive_ability({ "name": "example_ability", "module": "示例插件", "label": "示例主动能力", "description": "在合适时机执行一项外部动作。", "when": "Bot 空闲且当前日程适合时", "use_for": "形成生活素材或内部印象", "avoid": "不要向用户暴露插件名和执行过程", "share_probability": 0.12, "min_interval_hours": 12, "default_enabled": False, "default_config": {"keyword": ""}, "config_schema": { "keyword": { "label": "默认关键词", "description": "执行器可读取的自定义关键词", } }, "executor": my_executor, }) ~~~ 执行器可以返回字符串,也可以返回字典。字典可使用 ok/success、context、summary、text、image_path、extra_components、memory 和 status。 内置 LLM 工具包括 QQ 空间查看/发布、生图、反应图检索、便签、日程管理、书柜读取、关系查询、群成员查询、跨群/跨私聊转述和定时群转述。工具会按当前用户角色、会话类型、平台能力和功能开关动态加入,不会在所有会话中无条件暴露。 ## 项目结构 ~~~text main.py 插件注册、生命周期、事件钩子、命令和扩展 API daily_state.py 状态、日程、细化、天气、日记、技能和目标 proactive.py 私聊主动排程与会话路由 proactive_engine.py 候选、评分、时间窗、生命周期和动作选择 proactive_message.py 主动生成、图片、动作执行和发送 group_observation.py 群聊观察、群友、黑话、话题和片段 group_wakeup.py 群聊唤醒、续接和高强度模式 user_memory.py 用户画像、表达、关系状态和对话片段 worldbook.py 关系网、身份、群资料和待确认观察 tts_enhancement.py TTS 提示、转换、合成前处理和发送编排 private_image.py 私聊图片理解、缓存与归属 creative.py 私下创作、审校、封面和分享 news_exploration.py 新闻、AI 日报、B 站和主动搜索 page_api.py 陪伴面板后端 API pages/陪伴面板/ 陪伴面板前端 _conf_schema.json AstrBot 原生配置 Schema metadata.yaml 插件元数据 tests/ 回归测试 ~~~ ## 致谢 本插件参考或兼容了以下项目的部分产品思路与能力边界: - [MaiBot](https://github.com/MaiM-with-u/MaiBot) - [astrbot_plugin_LLMPerception](https://github.com/miaoxutao123/astrbot_plugin_LLMPerception) - [astrbot_plugin_context_aware](https://github.com/muyouzhi6/astrbot_plugin_context_aware) - [astrbot_plugin_atrelay](https://github.com/Alien-Star/astrbot_plugin_atrelay) - [astrbot_plugin_qzone](https://github.com/Zhalslar/astrbot_plugin_qzone) - [yupi-hot-monitor](https://github.com/liyupi/yupi-hot-monitor) ## Star History Star History Chart