PersonaChatter by ZaylLahnma

# PersonaChatter

Sneak a pseudo-human into the group chat!  
A QQ group chat plugin that imitates human behavior, with anthropomorphic decision-making, fuzzy memory, and a vivid personality that evolves over time.

## ✨ Features

- **Anthropomorphic Replies**: Generates natural, conversational responses based on group atmosphere and personal impressions of each member—can tease, banter, or show attitude just like a real person.
- **Fuzzy Memory**: Remembers recent chat history (sliding window) and keeps evolving impressions of each user, updated by AI as conversations go on.
- **User Impression System**: Stores multiple nicknames, roles, titles, and custom tags for each user (like "chatterbox", "lurker", "meme lord").
- **Self Memory**: The bot has its own mood and inner thoughts that change through interactions—it can be happy, bored, or annoyed just like anyone else.
- **Group Summary & Tags**: Automatically summarizes the group’s vibe and generates tags (e.g., "tech group", "shitposting den", "gaming squad").
- **Smart Sticker System**: Automatically catalogs frequently used images/stickers in the group, learns their context, and picks the right one to send when the moment calls for it.
- **Image Understanding (Optional)**: When enabled, the bot can "see" and understand pictures sent by others, using that information to craft better replies.
- **User-specific Tweaks**: Customize how the bot reacts to a specific person—boost or lower its willingness to reply, and inject special instructions like "roast this person relentlessly."
- **Annoyance Quit**: If the bot detects that someone is genuinely angry or fed up with it, it can choose to shut up and avoid further trouble (optional).
- **Auto Split Long Replies**: Long replies are automatically broken into multiple short messages sent one after another, mimicking real human typing.
- **Whitelist/Blacklist Support**: Only active in groups you choose, with optional random surprise replies in other groups.
- **Group Nickname Fetching**: Automatically grabs members' group nicknames so it can address them naturally.

## 🔧 Configuration

The plugin is configured via the LangBot WebUI or `manifest.yaml`. Main settings:

| Setting | Type | What it does | Default |
|--------|------|-------------|---------|
| `API Mode` | Select | Use LangBot's unified model or call APIs directly | `langbot` |
| `Filtering & Summary Model` | LLM | Small, fast model for deciding whether to reply and summarizing | (Required) |
| `Core Chat Model` | LLM | Large model that actually writes the bot's replies | (Required) |
| `Filter Model API Config*` | Strings | API address, key, model name for direct mode | ( / ) |
| `Chat Model API Config` | Strings | API address, key, model name for direct mode | ( / ) |
| `Reply Threshold (0-1)` | Float | How willing the bot is to reply; lower = chattier | 0.6 |
| `Persona Prompt` | Text | The bot's entire personality and way of speaking | "You are a tsundere but soft-hearted worker..." |
| `Bot Name` | String | The bot's main name | "Cuihua" |
| `Bot Aliases` | String list | Other names people might call it, one per line | ["Wang Cuihua"] |
| `Message Split Mode` | Select | `No split` or `Auto split` (sends long replies in chunks) | `No split` |
| `Chat History Length` | Integer | How many recent messages per group the bot remembers | 20 |
| `HTTP Service Port` | Integer | Port for fetching group nicknames via OneBot etc. | 3000 |
| `Group Filter Mode` | Select | `whitelist` (only listed groups) or `blacklist` (all except listed) | `whitelist` |
| `Target Group IDs` | Integer list | The group IDs to apply the filter mode to | [] |
| `Show Debug Logs` | Boolean | Print the bot's internal decision process to console | On |
| `Surprise Reply Probability` | Float | Tiny chance to reply in non‑whitelisted groups | 0.002 |
| `Enable Image Understanding` | Boolean | Let the bot see and describe images to inform its replies | Off |
| `Vision Model` | LLM | Multimodal model for image understanding (LangBot mode) | Optional, falls back to filter model |
| `Vision API Config` | Strings | API address, key, and model name for direct mode | ( / ) |
| `Sticker Send Probability` | Float | When the bot wants to send a sticker but no perfect match, chance to send a random one from its library | 0.15 |
| `User-specific Tweaks` | Text list | Per-user adjustments: `QQ:score_delta:instruction` | [] |
| `Annoyance Quit` | Boolean | If on, stop replying when someone seems truly pissed; off = ignore | Off |

> **Tips**:
> - The two main models must be set up in LangBot first.
> - If using "Direct API" mode, you’ll need to provide all API endpoints and keys yourself.
> - For group nickname fetching, enable the HTTP server in your OneBot framework and set the same port number here.
> - Image understanding requires a multimodal model (e.g., gpt-4o, claude-3.5-sonnet).
> - User-specific tweak example: `123456789:0.3:keep roasting him` makes the bot more eager to reply to that user and adds the instruction to its prompt.

## 📝 Usage

- Once installed and enabled, the plugin works automatically—no commands needed.
- Control which groups it runs in via whitelist/blacklist.
- The bot decides on its own whether to speak, what to say, and when to jump in, based on the chat context, group atmosphere, and what it “knows” about each person.
- When “Auto split” is on, long messages are broken into multiple short ones sent in sequence, like a real person typing.
- The sticker system is fully automatic: images that are used repeatedly in the group get collected, analyzed for context, and later the bot picks fitting ones on the fly. You can manually edit the `emoji_library.json` file in the plugin’s data folder to fine‑tune descriptions and keywords.
- Use the “User-specific Tweaks” to make the bot more (or less) responsive to certain people, or to give it special instructions for interacting with them.

## 🚧 Current Limitations

- **QQ groups only**: This plugin currently only works in QQ group chats—no private chats or other platforms.
- **Vision depends on model**: Image understanding requires a multimodal model that actually supports it.
- **No forwarded message, video, or voice parsing**: Merged forwarded messages, videos, and voice messages are not understood (plain images and stickers are supported).
- **No red packets**: The bot will not and cannot interact with red packets.
- **No voice/video sending**: Only text and sticker images can be sent; voice and video messages are not supported.
- **Low repetition tendency**: LLMs rarely repeat messages like a human “copy‑paste” bot—you can nudge this behavior in the persona prompt if desired.

## ⚠️ Important Notes

- **LangBot main program commands no longer work**  
  Commands like `!reset` from the LangBot core do not affect this plugin. To completely stop the plugin in a group, you must remove it from the whitelist (or add to blacklist) or disable the plugin.

- **Model & prompt risks**  
  The output depends entirely on the model and personality prompt you configure. Bad prompts or model choices can lead to unpredictable or inappropriate replies. Always test thoroughly and choose responsible prompts.

- **Concurrency risks**  
  The plugin makes many API calls in active groups. Adding too many groups at once may cause delays, timeouts, or high API costs. Start small and scale up cautiously. (And keep an eye on your wallet!)

- **Privacy & data**  
  The bot collects chat messages, nicknames, tags, and user profiles, storing them locally in the plugin’s data directory. Make sure this complies with your local regulations and keep the data secure.

## 🙏 Acknowledgments

- This plugin was created under the guidance of Artificial Intelligence, with the kind assistance of an Unintelligent Author.

## 📄 License

Part of the LangBot plugin ecosystem.