AstrBot Private Companion Plugin – “我会永远陪着你”

What it is – A plug‑in for the open‑source chatbot framework AstrBot that adds a long‑term, personality‑driven “companion” layer. The plugin keeps a continuous life‑style context (state, schedule, relationships, dreams, health, etc.) and uses that context to generate both reactive replies and proactive messages (greetings, reminders, image posts, voice messages, …) in private chats, group chats, or via an optional stand‑alone web UI.

---

Core idea

AstrBot already provides a base “persona” that answers incoming messages. This plug‑in does not replace that persona; it augments it with a living simulation of a character that:

• Maintains daily status, schedule, location, weather, health, hunger, and optional cyclical moods.
• Tracks relationships with a primary user (the “main companion”) and secondary users, storing affection levels, interaction stages, and recent topics.
• Generates proactive actions (text, images, voice, poke, screen‑capture, etc.) based on the simulated life events, time windows, token limits, and permission checks.
• Logs every decision (why a message was sent or blocked, token usage, audit trail) for debugging and transparency.
• Can be extended with optional modules for image generation, content creation, ComfyUI, real‑world device interaction, etc.

---

Main capabilities

Area	What the plug‑in does
Life continuity	Daily state (energy, mood, sleep, health, hunger), detailed schedule, location, weather, lunar calendar, optional cyclical simulation.
Private‑chat companion	Personalized greetings, memory of unfinished topics, lightweight user profile, rate‑limited proactive outreach, configurable tone per user.
Proactive behavior	Sends text, pictures, voice, poke, screen‑capture, external tool calls, segmented messages, quoted triggers.
Group‑chat understanding	Observes allowed groups, builds group atmosphere, tracks members, slang, topic threads, short‑term memory, relationship graph, can insert remarks when appropriate.
Multimodal	Handles private‑chat images, GIF frame extraction, image quoting, merges forwards, generates images (via linked image plug‑in), TTS, short‑term recall of retracted messages.
Content life	News, AI daily reports, proactive web search, B‑site highlights, dream logs, diary entries, notes; can sync with QQ Space when the adapter is present.
Growth & memory	Skill progression, personal non‑creative goals, self‑timeline, relationship observation, memory‑assistant integration.
Management & diagnostics	Visual “Companion Panel”, model routing, token & balance overview, config migration, proactive‑action audit, built‑in FAQ.

---

Optional extensions (installed separately)

• astrbot_plugin_image_companion – image generation (text‑to‑image) and related commands.
• astrbot_plugin_content_companion – creative writing, story/album management.
• astrbot_plugin_comfyui – local ComfyUI workflow for image generation.
• astrbot_plugin_reality_companion – camera/audio device interaction (real‑world “I will be with you”).
• Additional “memory”, “together”, “screen”, “live‑stream” companions that each add a focused set of abilities.

---

Installation

Method	Steps
Plugin market (AstrBot WebUI)	Search for astrbot_plugin_private_companion, install, restart AstrBot.
Git install	In AstrBot’s plugin manager, choose Install from Git and enter https://github.com/menglimi/astrbot_plugin_private_companion.
ZIP upload	Build a package with python scripts/build_plugin_package.py (produces dist/astrbot_plugin_private_companion‑vX.Y.Z.zip) and upload via the WebUI.
Manual copy	Clone the repo into <AstrBot data>/plugins/astrbot_plugin_private_companion.
Standalone WebUI (optional)	Enable enable_standalone_webui in the config, set an access token, then access http://127.0.0.1:6190/.

---

Quick‑start checklist (≈10 min)

1. Open the Companion Panel → confirm the plug‑in loads without errors.
2. Set the World Knowledge – point to the main AstrBot persona and add any extra character or world description.
3. Model page – pick a quick model for low‑latency tasks, a complex model for scheduling/relationship reasoning, and (if you have the image plug‑in) a visual model.
4. Fill Basic config – bot name, time‑zone, do‑not‑disturb hours, and the primary user ID.
5. In Private‑chat tab, mark the primary user as Main User.
6. Send 陪伴 状态 in a private chat; you should see the bot’s current state, schedule, and next proactive candidate.
7. (Optional) Enable Group‑chat observation, whitelist a group, and test with 陪伴群 状态.
8. Gradually turn on extra abilities (image, voice, screen‑capture, news, etc.) as needed.

---

How it works (high‑level flow)

• Passive reply – when a message arrives, the plug‑in builds a layered context (persona → time → relationship → content → pre‑send checks) and appends its own prompt before handing the whole thing to the LLM provider.
• Proactive candidate – life events, schedule items, reminders, weather changes, news, etc. generate candidate actions. Each candidate passes through:
  1. Time‑window & value scoring
  2. User‑/relationship‑/do‑not‑disturb checks
  3. Persona‑level decision
  4. Generation of text / execution of external tool
  5. Final audit (duplicate detection, privacy guard, token budget)
  6. Send → log → update memory
• State & schedule – stored in JSON (default) or SQLite (optional). The plug‑in updates the state after each interaction and can export/import via the panel.
• Relationship engine – eight affection stages + a “exclusive bond” for the main user; seven interaction intensity levels; automatic decay, caps, and configurable “apology” repair logic.
• Multi‑persona mode (off by default) – each persona gets its own independent state, schedule, diary, and token accounting.

---

Configuration highlights

• Token limits – hard limit stops all new LLM tasks; soft limit throttles low‑priority background jobs (news, image generation, etc.).
• Model routing – quick/complex/creative/visual models can be assigned per task; fallback to AstrBot defaults if a model is missing.
• Image generation – daily outfit, user‑requested generation, edit, or automatic “life‑event” pictures; supports multiple back‑ends (online APIs, ComfyUI, SDGen) with automatic fallback.
• TTS – text‑to‑speech can be sent together with the reply or as a separate voice message; supports Fish‑Audio models and optional MiMo voice‑clone integration.
• Privacy & safety – the plug‑in never stores or forwards adult content; relationship‑based permissions prevent escalation of privacy or device access.

---

Where to get help

• Wiki – https://vue.syuan.org (installation, config, FAQ)
• Issues – GitHub Issues page of the repo
• QQ group – 1097283005
• Sponsor – optional support via the provided 爱发电 link (no functional impact).

---

TL;DR

astrbot_plugin_private_companion is a fully‑featured, extensible companion layer for AstrBot that gives a chatbot a persistent “life”, relationship memory, and proactive behavior while keeping everything auditable and configurable. Install it via AstrBot’s plugin market, configure a main user and models, and the bot will start greeting you, remembering your past talks, posting daily status updates, and (if you enable extra modules) generating images, voice messages, and even interacting with real‑world devices. All behavior is driven by JSON/SQLite state files and can be inspected or tuned through the built‑in web panel.