# Waifu Plugin
A LangBot plugin that creates realistic chatbots by combining programmatic logic with LLMs, exploring an authentic chat experience.
**Language / 语言**: [简体中文](README_zh_Hans.md) | [English](README_en.md) | [Back to Main](../README.md)
[](https://github.com/ElvisChenML/Waifu/stargazers)
[](https://qm.qq.com/q/PClALFK242)
[]
> The community group is the LangBot community group. For questions about the main program or plugins, please ask there. Check the documentation and Issues before asking.
> **Important Notice:** The Waifu project will only receive essential maintenance updates going forward. Version 2.0 and subsequent features will be presented as an independent project: [Husbando](https://github.com/ElvisChenML/Husbando).
## Features
- **Multi-level Memory System**: Short-term + long-term memory summarization
- **Character Card System**: Separate templates for private/group chats
- **Story Mode**: Narrator, affection system for immersive storytelling
- **Humanized Mode**: Typing delay, segmented replies for natural conversation
- **Proactive Greeting**: Automatic initiation when user is inactive
- **Emotion Perception**: Analyze user emotions and adjust reply tone
- **Life Events**: Fictional daily activities for characters
- **Web Search**: AI autonomously decides whether to search
- **Jailbreak Mode**: Multi-position prompt injection
- **Chain of Thought**: Enhanced humanization through reasoning
## Installation
1. Configure the [LangBot](https://github.com/RockChinQ/LangBot) main program
2. Search for `Waifu` in the LangBot **Plugin Market** to install
3. Or enter the repository URL in the plugin page of the admin panel:
```
https://github.com/ElvisChenML/Waifu
```
Or see the detailed [Plugin Installation Guide](https://docs.langbot.app/plugin/plugin-intro.html)
## Configuration
Configure the following parameters in the LangBot plugin management interface after installation:
### Basic Settings
| Config Item | Type | Default | Description |
|-------------|------|---------|-------------|
| `character` | String | `default` | Character card name. `default` auto-selects template, `off` disables preset |
| `llm_model` | Model Selection | First available model | LLM model used by Waifu |
| `summarization_mode` | Boolean | `true` | Enable long-term memory summarization; if disabled, truncates when limit exceeded |
| `short_term_memory_size` | Integer | `2000` | Maximum character count for short-term conversation memory |
### Mode Settings
| Config Item | Type | Default | Description |
|-------------|------|---------|-------------|
| `story_mode` | Boolean | `false` | Story mode (narrator, affection system), only effective in private chats |
| `thinking_mode` | Boolean | `false` | Chain of thought, enhances humanization, may affect reply style |
| `personate_mode` | Boolean | `true` | Humanized mode: typing delay, segmented replies |
| `jail_break_mode` | Select | `off` | Jailbreak prompt injection position: `off` / `before` / `after` / `end` / `all` |
| `emotion_mode` | Boolean | `true` | Emotion perception: analyze user emotions, auto-adjust reply tone |
| `event_mode` | Boolean | `true` | Life events: fictional daily activities for characters, enrich conversation topics |
### Reply Settings
| Config Item | Type | Default | Description |
|-------------|------|---------|-------------|
| `response_rate` | Float | `1.0` | Reply probability after reaching minimum message count in group chat (0.0-1.0) |
| `group_response_delay` | Integer | `0` | Seconds to wait before generating reply in group chat (message merge window) |
| `person_response_delay` | Integer | `5` | Seconds to wait before generating reply in private chat |
### Proactive Greeting Settings
| Config Item | Type | Default | Description |
|-------------|------|---------|-------------|
| `proactive_greeting_enabled` | Boolean | `false` | Enable proactive greeting when user is inactive |
| `proactive_target_type` | Select | `person` | Proactive greeting target type: `person` (private chat) / `group` (group chat) |
| `proactive_target_id` | String | Empty | Target user/group ID for proactive greeting, leave empty to disable |
### Search Settings
| Config Item | Type | Default | Description |
|-------------|------|---------|-------------|
| `search_mode` | Boolean | `false` | Web search: AI autonomously decides whether to search and include results |
| `search_api` | Select | `duckduckgo` | Search engine: `duckduckgo` / `bing` / `google` |
| `search_api_key` | String | Empty | API key for Bing or Google (Google format: `api_key:cx_id`) |
## Commands
> Command components are divided into two categories:
> - **Command**: Instructions that need to be actively sent
> - **EventListener**: Automatically triggered by message events, no explicit call required
### Basic Commands
| Command | Description |
|---------|-------------|
| `列出命令` | List all supported commands and descriptions |
| `全部记忆` | Display all current long and short-term memory |
| `删除记忆` | Delete all long and short-term memory |
| `加载配置` | Reload all configuration files |
| `撤回` | Delete the last dialogue from short-term memory |
### Story Commands
| Command | Description |
|---------|-------------|
| `修改数值[value]` | Modify affection value, e.g., `修改数值100` |
| `态度` | Display current attitude based on affection value |
| `停止活动` | Stop narrator timer |
| `开场场景` | Trigger narrator to output opening scene from character card |
| `旁白` | Manually trigger narrator to advance plot |
| `继续` | Manually trigger Bot to continue reply and advance plot |
| `控制人物[character]\|[dialogue]` | Control character speech or trigger AI to generate character messages |
| `推进剧情[character_name]` | Auto-sequentially call: narrator → control character |
### Debug Commands
| Command | Description |
|---------|-------------|
| `请设计[content]` | Design a list |
| `请选择[question]\|[option1,option2]` | Choose from given list |
| `回答数字[question]` | Return numeric answer |
| `回答问题[system_prompt]\|[user_prompt]` | Q&A mode with custom system prompt |
## Character Cards
### Directory Structure
```
data/plugins/Waifu/
├── cards/ # Character card files (.yaml)
├── config/ # Configuration files
└── data/ # Runtime data (conversation logs, memory, etc.)
```
Template files are stored under `plugins/Waifu/templates/`. Files under `data/plugins/Waifu/` are generated from templates.
### Character Card Format
```yaml
# Required fields
user_name: Wang # How to address the user
assistant_name: Susu # Character name
language: English # Conversation language
Profile:
- Bio: You are... (character description)
# Optional fields
Skills:
- You speak gently with humor, avoiding aggressive words, making people feel comfortable.
Background:
- You chat with the user via QQ.
Rules:
- When introducing yourself, only mention your name, don't include occupation or other info.
Prologue:
- Every day, Wang sells watermelons at the school gate... (opening scene description)
# Story mode related (optional)
max_manner_change: 10
value_descriptions:
- max: 100
description:
- Interaction behavior: Maintain appropriate distance, formal language.
- max: 500
description:
- Interaction behavior: Enter romantic phase, words reveal tenderness and affection.
```
### Using Custom Character Cards
1. Create a character card referencing the template `plugins/Waifu/templates/default_person.yaml`, e.g., `example.yaml`
2. Place the file in the `data/plugins/Waifu/cards/` directory
3. In LangBot **Plugin Management Panel → Waifu → Configuration**, set the `character` field to `example`, save to take effect
> **Using different character cards for specific users/groups:**
> Create or edit `waifu_{session_ID}.yaml` under `data/plugins/Waifu/config/`, add `character: "example"` to override the global configuration.
## How It Works
1. **Message Listening**: Listen to private/group chat message events
2. **Emotion Analysis**: Analyze user emotional state (if enabled)
3. **Memory Retrieval**: Retrieve short-term memory and long-term memory summary
4. **Life Events**: Get character's current fictional activities (if enabled)
5. **Web Search**: AI decides whether search is needed (if enabled)
6. **Chain of Thought**: Generate internal reasoning process (if enabled)
7. **Reply Generation**: Generate character reply based on context
8. **Humanized Output**: Simulate typing delay and segmented replies (if enabled)
9. **Memory Update**: Update short-term memory, summarize to long-term memory when necessary
## Version History
<details><summary>Click to expand/collapse</summary>
### Waifu! 3.0
- Compatible with latest plugin system
### Waifu 2.0
- Emotion perception: Analyze user emotional state, AI auto-adjusts reply tone
- Life events: Fictional daily activities for characters, enrich conversation topics
- Web search: AI autonomously decides whether to search and include in context
- Migrated to LangBot new plugin architecture, supports plugin management interface configuration
### Waifu 1.9
- Support running with other plugins simultaneously, no longer blocks subsequent events
- No longer need to modify random response probability in group message response rules
- Jailbreak adds `all` mode, enables all jailbreak positions simultaneously
### Waifu 1.6
- Added `character: off` option, disables character preset
### Waifu 1.5
- Added group chat blacklist `blacklist` config item
- Added repeat `repeat_trigger` config item
- Added max narrator word count, max thinking word count configs
### Waifu 1.4
- Added `thinking_mode` to disable chain of thought
- Added character card built-in attribute `Prologue` (opening scene) and `[开场场景]` command
### Waifu 1.3
- Added integrated jailbreak, supports three positions: before/after/end of system prompt
- Added `continued_rate` for auto-continue speech
- Added `display_value` to control whether to display value each time
- Added `继续`, `剧情推进` commands
### Waifu 1.2
- Group chat supports @ commands
- Messages support images
- Added nickname recognition
### Waifu 1.1
- Each session uses independent configuration file
- Added undo function
- Added message accumulation processing
- Added humanized mode (typing time, segmented replies)
### Waifu 1.0
- Basic framework: Q&A module, character module, thinking module, memory database, narrator, emotion perception, status bar
</details>
## Contributing
1. Clone [LangBot](https://github.com/RockChinQ/LangBot)
2. Clone Waifu
3. Create `plugins/` directory in the LangBot root directory
4. Place Waifu in the `LangBot/plugins/` directory
## License
MIT
## Acknowledgments
- [LangBot](https://github.com/RockChinQ/LangBot) — Provides Bot functionality and base methods
- [LangGPT](https://github.com/langgptai/LangGPT) — Provides character preset prompt paradigm
- [Tencent TexSmart](https://ai.tencent.com/ailab/nlp/texsmart/zh/index.html) — Provides text understanding API
- [CyberWaifu](https://github.com/Syan-Lin/CyberWaifu), [koishi-plugin-aikanojo](https://github.com/HunterShenSmzh/koishi-plugin-aikanojo), [Spit_chatBot](https://github.com/LUMOXu/Spit_chatBot) — Provided ideas and code references
Waifu by Typer_Body
A 1:1 replica of the LangBot Peak Plugin, with more features planned. Compatible with the latest plugin system (not compatible with WEBCHAT). The latest masterpiece jointly crafted by ElvisChenML and Typer_Body - an advanced AI companion plugin featuring a multi-level memory system, character cards, narration, affection system, proactive greetings, and more.
Loading...