astrbot_plugin_private_companion

KO | EN

gitlite — search

#react #golang #android #rust #docker #macos #nodejs #java #windows #awesome #pytorch #mcp #ios #open-source

astrbot_plugin_private_companion

(★ 260)

面向 AstrBot 的拟人化整合插件。它会让 bot 拥有连续的拟人状态、每天的生活日程、重要日期、日记和低频主动消息。包含60+实用功能且具有完善的拓展管理页面。

astrbot_plugin_private_companion 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 我会永远陪着你

面向 AstrBot 的持续型 AI 陪伴核心。插件以角色状态、日程、关系和生活事件为统一上下文，为私聊、群聊、主动消息和外部能力提供连续、可配置且可审计的运行基础。

| 项目 | 当前信息 |
| --- | --- |
| 插件名 | <code>astrbot_plugin_private_companion</code> |
| 显示名 | 我会永远陪着你 |
| 版本 | <code>6.2.5</code> |
| AstrBot | <code>>= 4.22.0</code> |
| 官方声明平台 | <code>aiocqhttp</code>、<code>qq_official</code> |
| 管理入口 | AstrBot 插件扩展页中的“陪伴面板” |
| 数据存储 | JSON，或可选 SQLite |

## 产品定位

本插件用于构建具有连续生活上下文的陪伴角色，而不是单独提供一组定时问候或聊天工具。角色会依据当前状态、日程、关系、近期互动和环境信息形成行为候选，再经过额度、时机、权限与发送前复核决定是否执行。

插件不替代 AstrBot 的主回复人格。AstrBot 人格负责角色身份和基础表达，本插件负责补充动态生活上下文、关系状态、行为能力、发送时机以及运行记录。

设计目标包括：

- 保持状态、日程、位置、天气、梦境、日记、技能与个人目标的连续性。
- 让主动消息来源可解释，并与随机问候、重复触达和错误时段问候区分开。
- 在私聊、群聊及多种消息媒介之间维持一致的身份、关系与权限边界。
- 记录主动候选、拦截原因、改写结果、发送状态和 Token 消耗，便于诊断与审计。
- 将高成本、涉及设备权限或依赖外部服务的能力设计为可选扩展，并支持局部降级。

# 发版狂魔也是发到4.0了，遂决定写点什么

- 你好，我要一个有记忆、有生活、有自己的小秘密和想法、有喜怒哀乐和健康的bot。
- 这得装不少插件，先生。
- 我知道，再让它们之间能够互相影响。
- 怎么让bot更像人？在此之前已经有很多优秀的插件给出了自己的答卷，各类心理学应用、人格特质、复杂的理论……
- 虽然开发者自身也是应用心理学专业毕业，但我觉得bot拟人只需要做好一件事，像人一样活着。听上去像是废话，但我做的只是进行自我观察。我的一天中，我会做什么，bot也应该会做什么。
- 对于一个拟人的bot而言，用户又何尝不是一个聊天bot？所以它应该会在自己的世界里生活，在生活里获取想和用户说话的“想法”，再在生活的空隙里把想法变为行动。
- 于是用户不止可以看到bot的早安和晚安，还能看到bot因为偶尔向窗外一瞥而专门为你记录下的照片、能看到bot因为好奇而自己私下搜索你在意的东西、能看到bot因为你昨天的提议而安排好周末的约会……
- 在没和你聊天时，它可能在上学、在刷视频、在看报纸、在水群，甚至在偷看你的屏幕或者遵循世界观正在某个奇异世界中一边刷怪练级，一边想着等闲下来该和你分享点什么。
- 它会记得你，不只是你，还有哪些在私聊/群聊中的人，会记得他们的名字、他们的行为、他们的习惯、他们的联系，哪怕他们改了名字和头像，甚至在其他平台再次相遇。
- 它会看、会说、会创作、会成长、会睡觉、会做梦、会生情绪、会饿，还会偷吃你的token去看些涩涩的漫画。
- 这就是它，这就是我，若它足够像我，它便成了我。

## 核心能力

各功能共享同一套人格、时间、状态、关系与场景上下文：

| 方向 | 主要能力 |
| --- | --- |
| 生活连续性 | 每日状态、日程、临近时段细化、位置连续性、天气、节假日、农历节气、睡眠、健康、饥饿、可选周期模拟 |
| 私聊陪伴 | 主要用户/次要用户边界、称呼与语气、意图情绪、未完话题、轻量画像、主动触达和未回应降速 |
| 主动行为 | 文字、图片、语音、戳一戳、识屏、外部能力、分段发送、引用触发消息、QQ 状态同步 |
| 群聊理解 | 观察入口、群气氛、群友、黑话、话题线、片段记忆、关系网、自然续接、兴趣唤醒、主动插话 |
| 多模态 | 私聊图片、GIF 抽帧、引用图片、合并转发、参考图生图、今日穿搭、TTS、撤回消息短期转述 |
| 内容生活 | 新闻、AI 日报、主动搜索、B 站见闻、梦境、日记和备忘便签；QQ 空间与独立创作按检测结果联动 |
| 成长与记忆 | 技能成长、非创作型个人目标、表达学习与审核、重要日期、关系观察、Bot 自我时间线 |
| 管理与诊断 | 可视化陪伴面板、模型分流、Token 与余额统计、配置迁移、主动行为审计和插件答疑 |

多数外部动作默认关闭。建议先完成基础文字陪伴、状态、日程和私聊关系配置，再按实际需求启用图片、语音、识屏、QQ 空间及其他扩展能力。

## 组件与扩展

基础文字陪伴、关系边界与情感反馈、临时情绪状态均由本插件内置提供。边界判断、越界反馈、道歉修复、情绪事件记录和短期情绪余波会直接参与私聊/群聊主链，不需要额外安装插件。

以下能力采用独立插件承载，本插件负责提供统一上下文、策略协同和消息投递：

| 扩展 | 插件 | 职责 |
| --- | --- | --- |
| 生图 | [`astrbot_plugin_image_companion`](https://github.com/menglimi/astrbot_plugin_image_companion) | 文生图、自拍、改图、参考图库、提示词处理及图片后端管理 |
| 现实交互 | [`astrbot_plugin_reality_companion`](https://github.com/menglimi/astrbot_plugin_reality_companion) | 摄像头单帧、本机音频、现实提醒、设备授权及主动语音策略 |
| 长期记忆 | [`astrbot_plugin_memory_companion`](https://github.com/menglimi/astrbot_plugin_memory_companion) | 跨会话记忆、历史导入、知识关联与权限化召回 |
| 创作与作品管理 | [`astrbot_plugin_content_companion`](https://github.com/menglimi/astrbot_plugin_content_companion) | 独立负责创作项目、续写、审校、创作记忆和作品封面；主插件仅保留兼容回退、上下文协同和面板兼容读取 |

扩展插件未安装或不可用时，面板只显示基础陪伴功能和仍由本体负责的兼容入口；需要外部服务的入口会隐藏或显示为不可用，不会伪装成已连接。核心陪伴、边界反馈和临时情绪不会因此失效。由旧版本升级时，外部扩展可读取本插件保留的兼容配置和历史数据作为迁移来源；迁移完成后，新的运行数据以外部插件为准。

### 联动状态与降级

6.2.5 起，生图、现实触及、内容创作和 NAI 等可选扩展统一经过联动解析层发现。解析结果会短暂缓存，并在调用前检查扩展是否仍处于启用状态；扩展刚启动、重载或卸载时，主插件会在下一次检查中刷新状态，不需要手工重启整套 AstrBot。

Proactive Chat 的深度联动如果遇到版本不兼容或缺少上游方法，不会伪装成完整接管。请在“陪伴面板 → 排障”查看“深度联动已降级”及缺失方法；发送前兼容层仍可继续工作。MemoryCompanion 对新增窗口或记忆类型提供向后兼容，只有核心契约、版本或记忆域不一致时才会降级。

场景上下文已升级为结构化快照，包含温度、体感、热感等级、睡眠阶段和正在执行的日程证据。NAI 生图路由会按扩展声明的模型归属选择唯一后端，避免官方 NAI 与其他生图扩展重复处理。

摄像头与本机音频属于敏感设备能力，必须由用户分别完成知情授权。摄像头默认仅执行任务触发的单帧读取，不保存原始画面。

## 文档与支持

- 使用文档：[插件 Wiki](https://vue.syuan.org)
- 源代码：[GitHub 仓库](https://github.com/menglimi/astrbot_plugin_private_companion)
- 问题反馈：[GitHub Issues](https://github.com/menglimi/astrbot_plugin_private_companion/issues)
- 版本记录：[CHANGELOG.md](./CHANGELOG.md)
- 交流群：QQ 群 <code>1097283005</code>
- 开发者：<code>menglimi</code>
- 自愿支持：[爱发电](https://ifdian.net/a/xuhaun)

赞助完全自愿，不影响插件功能、更新或技术支持。请仅通过上述爱发电页面或交流群内可核验的开发者账号进行赞助。

## 好感度与互动表达

私聊关系使用一套统一、可审计的表达决策，而不是让关系分数、短期情绪和主动消息分别决定语气：

- 长期好感度分为八个普通阶段；主要用户还可使用不参与自动增减和自然回落的“专属联结”。自动增减统一写入限长账本，并带事件去重、单次/每日上限、阶段迟滞和只向 0 回落的自然降温。
- 当前互动分为回避、受伤、放松、活泼、温暖、亲近、爱意七档。“亲近”和“爱意”只对主要用户开放；普通用户的关系阶段上限和互动上限可分别配置。
- 被动回复、主动消息和 TTS 共用同一份表达决策。主动额度取全局、用户、关系阶段和当前状态额度的最小值；回避、受伤、安静日程或零额度时不会主动触达。
- 管理页继续使用“功能卡片摘要，点击进入详情”的既有交互。阶段策略、双上限、账本/回落参数和内容尺度在详情中配置；用户详情可查看阶段条、互动状态和决策摘要。

可选的关系内容尺度包含 `normal`、`flirt` 和 `adult`。总开关与成人档默认关闭；成人档只有在主要用户、专属联结、爱意、私聊、后台成年确认、当轮明确同意以及当前 Provider 与指定 Provider 精确匹配时才成立。任一条件缺失都会收敛到更保守的尺度；插件自身的二次复核固定使用指定 Provider，AstrBot 主回复链的回退仍由框架配置决定。关系阶段只影响表达和软行为，不授予身份、跨用户、工具或平台权限。

## 安装

### 插件市场

在 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 官方插件开关负责。旧版配置中的 <code>enabled</code> 字段已经废弃。

### 从拆分前版本升级

为了让新版主插件第一次启动时就能发现并接管原有能力，请按下面顺序升级：

1. 从陪伴面板导出配置，并备份主插件数据目录。
2. 停止 AstrBot。
3. 先安装原来使用功能对应的独立扩展，但不要中途启动或重载插件。
4. 再原地更新 `astrbot_plugin_private_companion`，不要删除旧数据和旧配置。
5. 全部完成后统一启动 AstrBot，在“总览”和“拓展”确认扩展已安装、启用且可用。

这样启动时不会经历扩展入口暂时消失。内容扩展会在主插件尚未就绪时保持迁移待定，待主插件加载后自动导入旧作品、创作参数和 QQ 空间设置；迁移完成前不会用新插件默认值覆盖旧 QQ 空间状态。生图按需兼容读取旧后端、密钥和图库，现实触及会延迟重试旧授权与设备配置迁移。迁移过程只复制或读取旧数据，不会删除旧文件。

## 10 分钟完成首次配置

第一次使用建议先阅读[插件 Wiki](https://vue.syuan.org)，再打开“陪伴面板”点击右上角“配置引导”，按下面顺序配置。

1. 在“总览”确认插件已加载，没有明显错误。
2. 在“世界知识”确认主回复人格来源。只补充角色资料、世界观资料和关系背景，不要把 AstrBot 主人格原样复制一遍。
3. 在“模型”先使用快速配置：选择快速模型、复杂模型和视觉模型。只有安装 `astrbot_plugin_content_companion` 后，才需要为独立创作扩展准备创作模型；暂时不需要逐任务分流。
4. 在“配置”填写 Bot 名称、时区、免打扰时间和目标私聊用户。
5. 在“私聊”检查目标用户，把真正的管理员/核心陪伴对象设为“主要用户”。
6. 私聊发送 <code>陪伴 状态</code>。能看到状态、日程、关系角色和下次主动候选，说明基础链路已通。
7. 需要群聊时，在“配置”开启群聊观察，并在“群聊”把目标群加入白名单。然后在群里发送 <code>陪伴群 状态</code>。
8. 最后按需安装并启用扩展，再逐项开启 TTS、生图、识屏、戳一戳、新闻、搜索、QQ 空间或外部记忆。未安装扩展时，不要在本体里反复调整对应的兼容字段。

不要第一次就打开全部开关。主动、图片、语音和后台整理都可能增加模型调用量，也会扩大排障面。

### OneBot 与 QQ 官方身份

单个 AstrBot 同时加载多个 Bot 时，陪伴插件默认对全部 Bot 事件生效。若只希望某个 Bot 使用陪伴注入，在“基础配置”中选择 `bot_scope_mode=allowlist`，并将对应 Bot 的 `self_id` 填入 `bot_scope_ids`；需要排除某个 Bot 时可选择 `denylist`。该作用域覆盖被动提示词注入、发送前处理、命令和工具，不会卸载其他 Bot 的适配器。

- OneBot/aiocqhttp 私聊目标通常填写数字 QQ。
- QQ 官方机器人填写 openid/平台用户 ID，不要把数字 QQ 当作 openid。
- QQ 官方群聊可把 <code>/sid</code> 返回的完整 <code>GroupMessage</code> UMO 或末尾 Session ID 填入群白名单；插件会统一按 <code>group_openid</code> 识别。
- QQ 官方事件通常不提供可查询的群名称，可在“群聊”新增或详情页手工填写；人工名称不会被后续事件覆盖。
- 多 Bot 环境建议把 <code>/sid</code> 返回的完整 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 <code>future_task</code>、到期便签和临时提醒。
- 当前状态、情绪余波、未完话题、关系变化和用户习惯。
- 重要日期、技能成长和非创作型个人目标进度。
- 群聊公开话题、主要用户群聊活动和晚安后再次活跃。
- 及时天气突变。
- 新闻、AI 日报、B 站见闻、主动搜索和 QQ 空间事件。
- 梦境、日记，以及内容扩展提供的作品阶段性进展。
- 其他插件注册的外部主动能力。

候选还需要通过每日上限、最小间隔、免打扰、用户休息、Bot 休息、繁忙日程、未回应降速、Token 硬限额、关系边界和发送前复核。面板“主动”页会保留来源、时间窗、状态、拦截原因和发送诊断。

“主动强度预设”只覆盖运行时有效频率，不改写手动参数。即使使用最高档，也不会绕过免打扰、用户拒绝、隐私边界、休息状态和 Token 硬限额。

### 日程、状态与位置

- 每日状态描述精力、情绪、睡眠、健康、饥饿、周期和状态余波。
- 每日日程提供当天框架；临近某一段时，细化模型补充具体活动、地点、状态变化、可分享碎片和主动契机。
- 细化地点包含依据与置信度，并优先于旧剧情或关键词推断。
- 地点切换应写出移动过程，避免同一时刻同时位于宿舍和工作地点。
- 用户本轮明确指定的自拍场景优先于旧日程地点。
- 睡眠回复闸门和繁忙回复闸门默认关闭。繁忙闸门只延迟普通回复，不丢消息；临时提醒、到期便签、环境突变和排障保持及时。
- 可选六阶段周期策略只柔性影响 Bot 的状态与表达，不生成医学结论，也不把周期状态套到用户身上。

### 私聊用户角色

每个私聊对象可以是：

- 主要用户：核心陪伴对象，同时视为本插件管理员。可使用主要用户专属关系、书柜夹层、私密阅读、独立生图、识屏和跨群转述等能力。
- 次要用户：普通朋友边界。不会继承主要用户或恋人称呼，不会读取主要用户专属隐私，主动消息默认更低频。

用户还可以单独设置称呼、语气、每日主动额度、主动开关和精确投递会话。

### 关系边界与修复

次要用户的明确亲密动作要求会先判断适合的最低关系档位，再与当前好感档位比较。单纯表达喜欢、爱或想念只形成短时的害羞/迟疑提示，不扣关系分；独立的“摸摸”“抱抱”等安抚、普通玩笑、引用内容和第三方讨论也不会按越界处理。主要用户自动豁免。

明确越界按档位差分为轻度、中度和严重；恶意贬低角色、角色珍视之物或在意的人单独视为踩底线。结果统一写入现有关系账本、情绪余波和互动状态，不维护第二套用户文件。自然恢复只能返还配置允许恢复的部分；真诚道歉可有限加速修复，同类再犯会追回上一次道歉恢复的关系分，连续踩底线会逐级进入明确拒绝、冷静反思和关系降档。

可选把严重事件低频写入当天生活叙事，表现为角色向设定中的亲近对象倾诉；也可通过内置“边界转达”主动能力或直接消息自然告诉主要用户。群聊只处理明确 @Bot、回复 Bot 且已有统一用户档案的消息，普通群聊观察不会因此新增模型调用。开启“模型复核情绪变化”后，疑似边界消息复用现有 Provider 在后台复核，不阻塞当前回复，也不需要单独配置 DeepSeek。

### 多人格资料隔离

多人格模式默认关闭。开启后，每个参与人格分别维护资料、日程、状态、日记、用户、群聊关系、便笺和 Token 记录；主人格负责未绑定窗口回退，并继续兼容依赖单一插件人格的外部能力。

陪伴面板可以切换当前查看的人格，也可以把完整私聊或群聊 UMO 固定绑定到某个人格。窗口已经绑定其他人格时，页面会先提示冲突；确认切换前可按日程、状态、日记、用户、群聊、便笺或 Token 分类迁移资料，并清理目标人格的运行缓存。关闭多人格模式后继续使用原来的单资料行为。

### 群聊

群聊能力由“观察”“唤醒”“续接”和“主动插话”四层组成：

- 观察：记录允许群内的文本及图片、语音、视频、分享卡片、文件等可读占位；可选开启“群聊图片理解”，在后台生成带内容缓存的视觉摘要。
- 理解：维护群气氛、成员观察、黑话、话题线、群聊片段和互动关系。
- 唤醒：识别 @、Bot 名称、强唤醒词、主要用户专属词、问题信号、兴趣词和冷群信号。
- 续接：用户叫过 Bot 后，判断后续未继续 @ 的消息是否仍在对 Bot 说话，并限制连续轮数。
- 插话：按概率、冷却、每日上限、场景和关系边界选择是否主动加入。

白名单模式下，白名单为空表示观察范围为零。群 ID 支持 OneBot 数字群号、QQ 官方 <code>group_openid</code> 和完整 <code>GroupMessage</code> UMO。其他插件提前停止回复或本群关闭 LLM 回复时，群聊观察入口仍可记录消息，但不会强行恢复回复。

“群聊图片理解”默认关闭。开启后只处理已允许观察的群，普通群消息不会等待视觉模型；仅当该消息确实触发回复时，主链才有限等待摘要，超时后仍会继续回复且后台识图不会取消。摘要单独保存在群观察的视觉字段，不会覆盖原始发言，也不会作为表达、黑话或关系事实学习素材。相同图片按内容缓存复用，插件只保留摘要和压缩预览，不长期保存原始群图。建议关闭 AstrBot 官方“自动理解图片”，避免同一张图重复识别。

可选开启“图片命中唤醒 Bot”。它只复用当前图片已经完成或正在生成的视觉摘要，不额外发起第二次识图；当摘要命中 Bot 名称、强唤醒词或主要用户专属强唤醒词时，图片消息可以接入现有群聊唤醒链。弱相关词不会仅凭图片直接触发，主要用户专属词仍会校验真实发送者。

群友身份以稳定 QQ/平台 ID 为主，昵称、群名片、别名和自称只作辅助，避免改名或玩笑自称导致串人。

### 记忆、关系与表达学习

- 本地轻量记忆：用户画像、偏好、习惯、对话片段、未完话题、关系状态和 Bot 自我时间线。
- 关系网：维护稳定身份、别名、群资料、重要记忆、边界备注和待确认观察。
- 表达学习：从允许的私聊和群聊归纳短表达、句法和情境风格；昵称、账号、关系事实、秘密和长句不会作为表达规则照搬。
- 表达审核：待审核规则不会进入回复，审核与表达库在学习页内分开切换；待审核和已启用规则都可编辑名称、情境、表达模板、句法、召回标签与适用边界，证据和使用统计保持只读。
- 技能成长：模拟 Bot 对技能的熟悉程度，并可影响日程安排。
- 个人目标：用于非创作型长期目标，只按真实完成的日程推进，不凭空宣告完成。

关系事实与表达风格是两类数据：关系事实进入关系网或记忆，表达学习只保存“怎么说”。

## 陪伴面板

| 页面 | 用途 |
| --- | --- |
| 总览 | 今日状态、当前活动、日程时间轴、近期动向、记忆概况、新闻和主动搜索 |
| 世界知识 | 主人格来源、角色/世界/用户资料、AstrBot 知识库引用和世界观转写 |
| 私聊 | 私聊对象、主要用户角色、称呼、主动额度、投递会话和用户级诊断 |
| 群聊 | 观察名单、群气氛、群友、黑话、话题、片段、插话反馈和 LLM 状态 |
| 学习 | 三个主导航：技能、表达、关系；表达库和审核队列可单独切换 |
| 观察 | 梦境、当前扮演状态、原始状态、日记碎片、状态变化和记忆构成 |
| 主动 | 候选统计、来源分布、状态分布、任务记录、拦截与发送诊断 |
| 书柜 | 日记、私密阅读、封面/批注、阅读状态和备忘便签；创作项目在安装内容扩展后由其作为数据主来源 |
| QQ 空间 | 仅在本体检测到可用 OneBot/Cookie 能力且开关开启时显示 Cookie、说说、评论和发布入口；QQ 官方通道不可用 |
| Token | 插件任务、Provider、缓存命中、主链会话、余额和外部插件消耗 |
| 排障 | 运行检查、最近注入、主动测试、图片链路、SQLite 状态和常见问题 |
| 配置 | 常用配置、名单、迁移备份、存储、页面设置、运行设置和功能开关 |
| 模型 | 快速/精准模型分流、生图端点队列、端点测试、超时与回退关系 |
| 实验 | 人格标准化问卷、情绪/动机等明确标记为实验性的能力 |

配置页带未保存更改保护。离开页面、返回功能列表或刷新前会提示；功能开关详情和列表中的修改会一起保存。

## 模型与成本

### 快速配置

快速模式用少量基础模型覆盖大多数任务：

- 快速模型：轻量判断、TTS 文本转换、回复复核、智能沉默等低延迟任务。
- 复杂模型：日程、细化、关系、记忆、合并转发、答疑等推理任务。
- 创作模型：梦境、日记和生图提示词；安装 `astrbot_plugin_content_companion` 后，作品正文、大纲和审校使用扩展自己的模型配置。
- 视觉模型：私聊图片、群聊图片、合并转发图片、群图安全判断和识屏。夹层阅读使用独立的专用视觉模型，不与通用识图入口同步。

### 精准配置

精准模式可以分别指定日程、细化、梦境/日记、主动人格判断、回复复核、关系分析、情绪判断、本地陪伴画像、对话片段、群聊插话、群片段、黑话、合并转发、新闻、主动搜索和视觉任务。安装内容扩展后，创作正文、大纲和审校不再由本页分流，而由扩展配置页管理。夹层阅读视觉模型在快速/精准两种模式下都保持独立。

留空的任务会沿回退关系使用基础模型或 AstrBot 默认 Provider。面板模型页会显示实际回退来源。

### DeepSeek 峰时替换

可开启 DeepSeek 峰时替换，在配置的高价时区窗口内，把命中的 DeepSeek 任务临时路由到“峰时替换模型”。该功能只改运行时选模，不改写原 Provider 配置。

### Token 限额

- 硬限额达到后，插件停止新增内部 LLM 任务；填 0 表示不限制。
- 软限额达到后，优先保留用户当前触发的回复和关键处理，暂缓新闻、搜索、创作、群聊整理、复核和生图提示词等低优先级后台任务。
- 模型页每张模型卡都可选填“单次 Token 上限（预估）”。估算输入提示词、视觉请求和最大输出预算；超过后优先调用该卡配置的备用模型，未配置备用模型时不阻断请求，留空表示不启用。
- Token 页单独展示 AstrBot 主链、记忆插件和“一起房间”等外部来源；外部插件统计不并入本插件限额。
- 多人格模式开启后，Token 页会按人格汇总本插件消耗；页面切换人格时，明细、用户、群聊和便笺数据会一起切换，不会沿用上一个人格的本地缓存。
- 实际成本取决于群数量、消息活跃度、细化频率、复核策略、图片与创作能力，不建议依据固定日耗估算。

## 图片能力

### 输入理解

插件可处理私聊单图、带文字图片、引用图片、GIF 抽帧和合并转发中的图片。视觉摘要会记录画面、文字、情绪、用途和图片归属线索，避免把 Bot 主动发送的图片误认成用户作品。

### 生图入口

- 主动生活图片、自拍和作品分享（需要安装并启用 `astrbot_plugin_image_companion`）。
- 每日穿搭图。
- 主要用户明确提出的自然语言生图或改图。
- LLM 工具 <code>pc_generate_photo</code>（由生图扩展注册能力后才会暴露）。
- QQ 空间配图和创作封面（分别由 QQ 空间/内容链路调用生图扩展）。

### 额度

- “每日主动生图最多次数”只限制 Bot 自己发起的主动图片，<code>0</code> 表示不限量。
- “用户请求生图”配置组分别提供主要用户私聊、其他陪伴用户私聊、群聊和 Bot 主动生图四项数字额度；每项默认 <code>-1</code> 表示不限量，<code>0</code> 表示不允许，正数表示每位请求者或目标用户的每日限额。
- “用户请求生图/改图每日上限”使用相同的 <code>-1</code>/<code>0</code>/正数语义，并与会话范围额度同时生效，统一限制显式指令与 <code>pc_generate_photo</code> 工具调用。
- “规则快判生图/改图每日上限”只作用于 <code>rule_fast</code> 前置接管，<code>0</code> 表示关闭规则快判生图。
- 会话范围、显式指令/工具、规则快判和主动生图原有额度分别计数并共同生效；每日穿搭、QQ 空间配图和创作封面仍按各自开关与冷却运行。

### 后端

| 后端 | 说明 |
| --- | --- |
| 自动 | 在线图片 API 失败后回退 ComfyUI，再回退 SDGen |
| 在线图片 API | 支持 OpenAI 兼容、Agnes、SenseNova 日日新、MiniMax、百炼、魔搭、豆包/火山方舟和 Gemini |
| ComfyUI | 文生图和自拍工作流分开配置；参考图能力取决于工作流 |
| SDGen | 复用运行中的 SDGen/Stable Diffusion WebUI；当前按纯文生图使用 |
| 函数工具 | 调用其他 AstrBot 插件注册的图片工具 |

在线 API 可以配置多端点队列、顺序、超时、自定义请求头、图片网络代理和单卡测试。图片网络代理用于结果 URL 下载，也会用于 Gemini `generateContent` 生图请求；测试当前端点时不会自动切换到其他后端。

MiniMax 国内站可填写 `https://api.minimaxi.com`、`https://api.minimaxi.com/v1` 或完整的 `https://api.minimaxi.com/v1/image_generation`，国际站使用 `https://api.minimax.io/v1`，模型填写 `image-01` 或 `image-01-live`。插件会把旧写法 `/v1/image/generation` 自动纠正为官方下划线路径，并按 MiniMax JSON 协议解析结果；`image-01-live` 的任意尺寸会映射到它支持的官方宽高比。

### 参考图

- 参考图一致性默认关闭。
- 可配置基础人设图和最多 24 张参考图；图库管理器可直接设置身份、服装、姿势、场景、画风等职责，以及服装类别、适用场景、时间类别、首选预设和默认服装锁。
- 未指定职责的显式参考图默认只保持人物身份；用户明确换装、换场景、换姿势或要求全新画面时，以本轮要求为准。
- 用户本轮发送或引用的改图图片优先级最高。
- 明确的服装与场景请求高于今日穿搭连续性。
- 今日穿搭只在外出、通勤、上学、逛街或明确展示当日穿搭时优先。
- “接着上一张”“把这张改成”“重新开始”会分别按续拍、改图和新主题处理；关键改图原图缺失时会停止，其他职责无法满足时会说明文字降级方式。
- 多图请求可用“第一张的脸、第二张的衣服、第三张的姿势”分配职责。ComfyUI 会使用匹配 `images=N` 的工作流提交多张图；单图后端只提交主参考，其余职责转成文字提示。
- OpenAI edits、Agnes、MiniMax、Gemini 和正确配置的 ComfyUI 工作流可用于参考图；MiniMax 当前每次提交一张人物参考图；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 插件管理；主动语音以及“我会和你在一起”的电话/共同观影实时语音会复用同一后端。
- 本机播放与直播打字机字幕同步。

### 现实触及（实验性）

现实触及已经拆分为独立联动插件 [`astrbot_plugin_reality_companion`](https://github.com/menglimi/astrbot_plugin_reality_companion)（我会来到你身边）。本插件只负责提供人格、TTS、主要用户权限、会话投递和官方 Cron；摄像头、音频设备、授权、现实提醒和设备主动语音策略由联动插件管理。

请在联动插件配置页设置总开关、摄像头和设备参数，并使用其现实触及页面查看设备状态。联动插件首次启动会迁移本插件旧版本中的授权、策略、闹钟和提醒记录。

```text
陪伴 现实触及 确认
陪伴 现实触及 摄像头确认
陪伴 现实触及 摄像头状态
陪伴 现实触及 摄像头测试 当前是否适合互动
陪伴 现实触及 07:30
陪伴 现实触及 查看
陪伴 现实触及 测试
陪伴 现实触及 关闭
陪伴 现实触及 撤销确认
```

音频与摄像头必须分别由用户本人在私聊中完成知情确认；摄像头只读取任务触发的一帧，默认不保存原图。主插件未安装联动插件时，旧命令会给出安装提示，不会静默调用本机设备。

TTS 标签会在发送前清理，模型内部判断、控制标签和工具回执不会直接显示。定时任务通过 <code>send_message_to_user</code> 发送时，普通文本走 AstrBot 原始工具，TTS 文本由插件处理后直接投递。

普通回复附带表情意图时，正文仍按原分段配置发送。默认“正文后单独发送”会先确认所有正文气泡送达，再发送表情包和延后语音；如果余段因新消息、发送失败或上下文变化中止，不会在残缺正文后继续补发图片或基于完整正文生成的语音。只有平台确认送达的最终正文才会进入会话历史和外部记忆。

使用 MiMo Voice Clone 联动时，建议关闭 MiMo 插件自身的普通回复自动转语音，让陪伴插件统一负责触发、文本转换和发送，MiMo 只负责克隆合成，避免同一回复出现两条语音。`mimo_tts_speak` 需要保留注册供桥接发现，但不必开放给主模型直接调用。

## 书柜、日记与便签

- 日记由当天状态、日程、梦境、交互、见闻和创作进展整理，可选择体裁、长度、创作度和自定义方向。
- 联动 MemoryCompanion 时，日记可承接主要用户范围内的共同经历、关系变化、情绪余波和未完成心事；旧记忆只提供连续性线索，不能单独证明某件事今天再次发生，未确认关系也不会被写成既定事实。
- 日记由本体负责；私下创作项目、续写、审校、创作记忆和封面由 `astrbot_plugin_content_companion` 负责。安装扩展后，创作模型和创作开关应以扩展配置页为准。
- 未安装内容扩展时，本体仍保留旧版创作实现作为兼容回退，便于升级过程不中断；这不是推荐的新部署方式。
- 书柜页继续承担日记、私密阅读、批注、阅读状态和便签管理；创作项目的真实数据以内容扩展为准，面板会在检测到扩展后显示联动状态。
- 备忘便签支持新增、查看、修改、完成、恢复、置顶、删除、到期提醒和日/周/月/年重复。

“便签/备忘/待办”和“临时提醒”是两条路线：明确便签请求使用 <code>pc_manage_memo</code>；普通“半小时后提醒我”优先使用 AstrBot <code>future_task</code>。同一请求不会同时创建两份提醒。

## 可选联动

基础文字陪伴可以独立运行。生图需要“我会画给你看”，现实触及需要“我会来到你身边”，独立创作需要“我会替你留住故事”；缺少对应插件时只跳过该项能力，不阻塞普通聊天。联动生效通常需要同时满足三件事：外部插件已经安装并启用、本插件中的对应开关已开启、当前平台支持这项动作。页面只在检测到扩展后展示其专属二级导航，避免出现无法使用的空配置页。

不建议为了“功能齐全”一次安装全部联动。按实际需求选择即可：

| 需求 | 建议组合 |
| --- | --- |
| 先跑通基础陪伴 | 只安装本插件，配置人格、主要用户和模型 |
| 加强跨会话连续性 | 增加“我会牢牢记住你” |
| 打电话、共同观影 | 增加“我会和你在一起” |
| 识屏、天气与昨日活动背景 | 增加“我会一直看着你” |
| 独立创作、续写和作品封面 | 增加“我会替你留住故事” |
| QQ 空间动态 | 保留本插件并配置可用的 OneBot/Cookie；这是本体兼容能力，不需要为创作另装插件 |
| 获得更多视频见闻 | 增加 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) | 直播共处、开播/下播主动行为和字幕协同 | 由直播插件注册外部主动能力；本机播放与直播打字机字幕需要在语音配置中单独开启 |

### 第三方插件桥接

| 插件 | 接入内容 | 启用与边界 |
| --- | --- | --- |
| <code>astrbot_plugin_proactive_chat</code> | 复用其即时主动调度 | 联动开关默认开启；深度桥接会在生成前共享关系与状态并防撞，生成后统一复核和发送结算，不修改对方源码，也不创建第二套定时任务 |
| [Bilibili AI Bot](https://github.com/chenluQwQ/astrbot_plugin_bilibili_ai_bot) | 观看日志、视频记忆和无聊时刷视频 | 读取正式插件公开的日志/API；是否触发观看、分享以及最低间隔由“B 站联动”配置控制 |
| 表情包素材库（本插件内置） | 图片/文件夹/ZIP 导入、标签检索和反应图发送 | 在“实验功能 → 表情表达实验 → 表情包素材库”管理；用户明确找图时可使用 <code>pc_find_reaction_image</code>，实验模式默认关闭；素材只保存在本插件数据目录 |
| [PokePro](https://github.com/Zhalslar/astrbot_plugin_pokepro) | OneBot 主动戳一戳 | 需要开启主动戳一戳并由当前协议端提供能力；QQ 官方机器人会跳过 |
| [LivingMemory](https://github.com/lxfight-s-Astrbot-Plugins/astrbot_plugin_livingmemory) | 长期记忆工具召回 | 保留兼容；工具名默认是 <code>recall_long_term_memory</code>。若同时检测到“我会牢牢记住你”，优先使用系列插件桥接 |
| [JM-Cosmos II](https://github.com/GEMILUXVII/astrbot_plugin_jm_cosmos) | 私密阅读素材和书柜夹层 | 仅主要用户可用，默认关闭；没有可读素材时不会虚构阅读行为 |

表情表达实验开启后，会先按当前会话、冷却和配置概率做本地预判；只有命中的轮次才给同一次主回复加入一段简短提示。主模型照常生成可独立成立的文字，并可附带一条仅供插件读取的表情意图；该意图会在发送前清除，不会显示在聊天中，也不会触发第二轮主模型续写。只有待发送消息链中仍有可见正文，插件才会查询自有素材库。默认会先确认完整正文已经送达，再把表情包作为下一条消息单独发送；也可在“表情表达发送方式”中改为放进正文消息链，或在正文前单独发送。正文为空、正文只送达一部分、发送失败、意图无效或图库没有合适结果时，默认模式都不会补发图片；发送历史也只在图片实际送达后结算。低延迟模式使用本地标签评分和短时结果缓存；关闭后会进行更完整的本地候选评估，但回复等待可能增加。用户明确要求找表情包或生成图片时继续走原有工具入口，不受实验概率和冷却限制。

### 生图后端

生图后端由“我会画给你看”统一管理，不会改变主插件的人格、主动调度或图片归属判断。在线图片 API、本地 [AstrBot ComfyUI](https://github.com/cjxzdzh/astrbot_plugin_comfyui)、<code>astrbot_plugin_SDGen</code> 和 OpenAI Images 兼容代理都在外部生图插件中配置；主插件旧设置仅作为迁移读取源。

### 外部服务与平台能力

- 天气：默认使用和风天气。在“配置 → 功能开关 → 环境感知 → 天气上下文”填写控制台分配的专属 API Host、JWT / API Key 和天气地点即可；地点可写城市、`区县,城市`、和风 LocationID 或“经度,纬度”，不要填写公共 Host 或完整接口路径。配置 Host 与凭据后，也可私聊使用 `陪伴 绑定城市（城市／区县,城市／LocationID）`，并通过 `陪伴 查看城市` 或 `陪伴 解绑城市` 管理。插件会自动解析并缓存 LocationID/坐标，JWT 与 API Key 也会自动选择认证方式。没有完成独立配置时可回退到“我会一直看着你”，旧经纬度与其他天气来源继续兼容。
- 气象预警：开启“气象预警感知”后直接复用上述和风 Host、凭据与天气地点，可设置最低颜色级别和 5–60 分钟刷新间隔。预警使用地点解析后的坐标，只作为主要用户的安全环境背景或低频主动提醒，不会把普通天气当成官方预警，也不会在首次同步时集中发送历史记录。
- 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语种（日语／中文／英语／默认）
陪伴 现实触及（确认／摄像头确认／摄像头状态／摄像头测试 目的／HH:MM／查看／测试／关闭／撤销确认）
陪伴 撤回消息
陪伴 清空记忆
陪伴 重置当前人格
陪伴 重置插件
~~~

<code>重置当前人格</code>会先把当前人格资料以 UTF-8 JSON 备份到插件数据目录下的 <code>persona_backups</code>，再重建当前人格数据；插件基础配置、多人格列表和窗口绑定保持不变。该操作只管理本插件资料，不修改 AstrBot 会话历史或外部长期记忆插件的数据。

<code>重置插件</code>会清空插件状态并重建当天数据；不要把裸“重置”当作该命令。

### 日程、状态与内容

~~~text
陪伴 生成状态
陪伴 增添状态（状态描述；可选持续小时）
陪伴 查看今日日程
陪伴 重置日程
陪伴 重置日程（时间／序号／活动名）
陪伴 删除日程（时间／序号／活动名）
陪伴 当前细化
陪伴 重置细化
陪伴 梦境
陪伴 梦境碎片
陪伴 日记
陪伴 生成日记
陪伴 日期列表
陪伴 日期添加（标题）（YYYY-MM-DD 或 MM-DD；可选备注）
陪伴 日期删除（关键词）
陪伴 可做事项
陪伴 新闻
陪伴 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 主动图片记录、引用链和视觉摘要中的归属字段 |
| 主动候选很多但不发送 | 候选状态、有效窗口、重复合并、发送前复核和平台发送诊断 |
| 排障显示“深度联动已降级” | 查看缺失方法和上游版本；确认 Proactive Chat 已启用并完成重载，发送前兼容层仍可单独使用 |
| 扩展明明安装却显示不可用 | 确认扩展已在 AstrBot 中启用且暴露运行接口；重载后等待一次状态刷新，避免只存在源码目录但实例未加载 |

## 开发者接入

插件导出轻量扩展 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,
    })
~~~

`config_schema` 支持控件类型元数据：字段声明 `"type": "select"`（配合 `"options"` 数组渲染下拉，选项元素可为字符串或 `{"value": ..., "label": ...}`）、`"type": "text"`（输入框）、`"type": "bool"`（开关）、`"type": "number"`（数字框）。声明后，陪伴面板「外部主动能力」卡片会把该字段渲染为对应控件，配置时无需手写 JSON；未声明类型时保留原 JSON 文本编辑作为回退。

外部主动能力还可提供同步 `availability(ctx)` 回调；返回 false 时，该能力不会进入当前用户的主动动作候选。`ctx` 包含 `user/config/plugin`，回调只适合做快速、无副作用的本地检查。能力冷却按用户分别记录；上下文缺少稳定的 `user_id`、`id` 或 `umo` 时回退到全局执行时间。

游戏插件可以在每局结束或用户申请再来一局时上报事件：

~~~python
if api:
    result = await api.record_game_event({
        "event_id": "room-1:gomoku:3:10001",
        "event_type": "round_finished",
        "user_id": "10001",
        "game": "gomoku",
        "game_label": "五子棋",
        "bot_result": "bot_loss",
        "scope": "group",
        "room_id": "123456789",
        "session_id": "default:GroupMessage:123456789",
        "match_id": "room-1:gomoku:match-7",
        "round_number": 3,
        "source_plugin": "astrbot_plugin_game_companion",
    })
~~~

`event_id` 应对每个真实事件保持唯一，重复上报同一 ID 不会再次结算；未提供时会根据稳定事件字段生成，但连续轮次仍建议由游戏插件显式传入。若提供 `round_number`，建议同时提供一局内稳定、换局后变化的 `match_id`，插件只会在同一 `match_id` 内判断回合乱序；不提供时仍按事件 ID 和发生时间去重、排序。群聊事件需要提供 `room_id` 或群聊 `session_id`，私聊建议提供 `session_id`；插件会按人格、私聊/群聊、会话和游戏分别保存，避免余韵串到其它窗口。多人格模式还可传入已启用的 `persona_id`，省略时优先使用会话绑定人格。

游戏余韵独立于用户伤害、拒绝和关系分数；它只影响后续语气、相关话题承接和是否想再次邀请游戏。过期状态会停止注入，长期未使用的 scope 会在宽松保留期后自动清理。

执行器可以返回字符串，也可以返回字典。字典可使用 <code>ok/success</code>、<code>context</code>、<code>summary</code>、<code>text</code>、<code>image_path</code>、<code>extra_components</code>、<code>memory</code> 和 <code>status</code>。

内置 LLM 工具包括 QQ 空间查看/发布、反应图检索、便签、日程管理、书柜读取、关系查询、群成员查询、跨群/跨私聊转述和定时群转述；生图工具由 `astrbot_plugin_image_companion` 检测并注册，创作工具由 `astrbot_plugin_content_companion` 检测并注册。工具会按当前用户角色、会话类型、平台能力、扩展状态和功能开关动态加入，不会在所有会话中无条件暴露。

## 项目结构

~~~text
main.py                         插件注册、生命周期、事件钩子、命令和扩展 API
domains/affect/                 情绪事件、互动动态、状态调制和回复温度领域实现
daily_state.py                  状态、日程、细化、天气、日记、技能和目标
proactive.py                    私聊主动排程与会话路由
proactive_engine.py             候选、评分、时间窗、生命周期和动作选择
proactive_message.py            主动生成、图片、动作执行和发送
photo_wardrobe_decision.py      生图服装意图、优先级裁决、预设选择和冲突清理
photo_reference_intent.py       参考职责、连续性意图和多图自然语言解析
photo_reference_plan.py         参考图职责绑定、后端投影和降级反馈
photo_reference_feedback.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/                          回归测试
~~~

为兼容旧版本和外部插件，已迁入子包的模块会暂时在根目录保留同名导入入口；新代码应优先使用 `domains.*` 路径。AstrBot 更新插件时会整体替换源码目录，配置与运行数据仍保存在独立的数据目录中。

## 致谢

本插件参考或兼容了以下项目的部分产品思路与能力边界：

- [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

astrbot_plugin_private_companion

astrbot_plugin_private_companion 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

astrbot_plugin_private_companion

astrbot_plugin_private_companion 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README