feat(prompts): 实现 MaiBot 提示词覆盖系统

实现 maim_message template_info 机制覆盖 MaiBot 核心提示词，
使 MaiBot 在 VTuber 直播场景下具有一致的人设和回复风格。

主要功能:
- TemplateOverrideService 构建 TemplateInfo 对象
- 自动剥离 YAML frontmatter 元数据
- 支持 replyer_prompt 和 replyer_prompt_0 覆盖
- 添加 group_info 标识群聊（直播间）场景
- 详细的调试日志输出

模板文件:
- replyer_prompt.md - VTuber 群聊回复主模板
- replyer_prompt_0.md - 轻量回复模板 (think_level=0)
- private_replyer_prompt.md - 私聊回复模板
- chat_target_group1/2.md - 群聊场景描述
- chat_target_private1/2.md - 私聊场景描述

配置示例:
  [providers.decision.maicore]
  enable_prompt_override = true
  override_templates = ["replyer_prompt", "replyer_prompt_0", ...]

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: ChangingSelf

config-template.toml

@@ -321,6 +321,17 @@ user_nickname = "语音"
 # connect_timeout = 10.0
 # reconnect_interval = 5.0
 
+# --- MaiCore DecisionProvider 提示词覆盖配置 ---
+# 覆盖 MaiBot 默认回复提示词，使 VTuber 人设更一致（默认启用）
+# enable_prompt_override = true
+# override_template_name = "amaidesu_override"
+# override_templates = [
+#     "replyer_prompt",      # think_level=1 时使用
+#     "replyer_prompt_0",    # think_level=0 时使用（轻量回复）
+#     "chat_target_group1",
+#     "chat_target_group2",
+# ]
+
 # --- LLM DecisionProvider ---
 # [providers.decision.llm]
 # fallback_mode = "simple"  # simple | echo | error

docs/development/maibot-override.md

@@ -0,0 +1,135 @@
+# MaiBot 提示词覆盖功能
+
+## 功能概述
+
+Amaidesu 支持通过 `maim_message` 的 `template_info` 机制覆盖 MaiBot 的回复提示词，使 VTuber 在直播场景下具有更一致的个性和回复风格。
+
+**默认启用**: 该功能默认启用，确保所有消息都使用 VTuber 风格的提示词。
+
+## 工作原理
+
+1. Amaidesu 发送消息到 MaiBot 时，携带 `template_info` 和 `group_info`
+2. `template_info` 包含自定义的提示词模板
+3. `group_info` 标识消息来自直播间（群聊），确保使用群聊提示词
+4. MaiBot 收到消息后，在 `async_message_scope` 作用域内注册这些模板
+5. 处理该消息时，MaiBot 使用覆盖后的提示词而非默认提示词
+
+**重要**: 模板变量（如 `{bot_name}`, `{identity}` 等）由 MaiBot 端填充，Amaidesu 只需提供原始模板字符串。
+
+### 群聊 vs 私聊
+
+MaiBot 通过 `group_info` 判断消息类型：
+- **有 `group_info`**: 使用群聊模板（`replyer_prompt`, `chat_target_group1/2`）
+- **无 `group_info`**: 使用私聊模板（`private_replyer_prompt`, `chat_target_private1/2`）
+
+Amaidesu 默认为所有消息设置 `group_info`（`group_id="live_room"`, `group_name="直播间"`），确保使用群聊模板。
+
+## 配置方法
+
+在 `config.toml` 的 `[providers.decision.maicore]` 段添加：
+
+```toml
+[providers.decision.maicore]
+# 现有配置...
+host = "127.0.0.1"
+port = 8000
+
+# 提示词覆盖配置
+enable_prompt_override = true
+override_template_name = "amaidesu_override"
+override_templates = [
+    "replyer_prompt",      # think_level=1 时使用
+    "replyer_prompt_0",    # think_level=0 时使用（轻量回复）
+    "chat_target_group1",
+    "chat_target_group2",
+]
+```
+
+### 配置项说明
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `enable_prompt_override` | bool | `true` | 是否启用提示词覆盖 |
+| `override_template_name` | str | `"amaidesu_override"` | 作用域名称 |
+| `override_templates` | list | 见上方 | 要覆盖的模板列表 |
+
+### 重要：replyer_prompt vs replyer_prompt_0
+
+MaiBot 根据消息复杂度选择不同的回复模板：
+- **`think_level=0`**：使用 `replyer_prompt_0`（轻量回复，简短平淡）
+- **`think_level=1`**：使用 `replyer_prompt`（标准回复，日常口语化）
+
+**必须同时覆盖两个模板**，否则在某些场景下仍会使用默认的 QQ 群聊提示词。
+
+## 可覆盖的提示词
+
+### 核心回复模板
+
+| 模板名称 | 用途 |
+|---------|------|
+| `replyer_prompt` | 群聊回复（主模板） |
+| `replyer_prompt_0` | 群聊回复（备选） |
+| `private_replyer_prompt` | 私聊回复 |
+
+### 场景描述模板
+
+| 模板名称 | 用途 |
+|---------|------|
+| `chat_target_group1` | 群聊场景描述 |
+| `chat_target_group2` | 群聊场景简短描述 |
+| `chat_target_private1` | 私聊场景描述 |
+| `chat_target_private2` | 私聊场景简短描述 |
+
+## 自定义模板
+
+模板文件位于 `src/modules/prompts/templates/maibot_override/` 目录。
+
+### 模板格式
+
+使用 YAML frontmatter 定义元数据：
+
+```markdown
+---
+name: replyer_prompt
+version: "1.0"
+description: "VTuber 场景回复提示词"
+variables:
+  - bot_name
+  - identity
+  - dialogue_prompt
+---
+
+{knowledge_prompt}
+你是一位正在直播的 VTuber {bot_name}...
+{dialogue_prompt}
+现在，你说：
+```
+
+### 注意事项
+
+1. **保留所有变量**: 模板中的变量占位符（如 `{identity}`）必须保留，由 MaiBot 端填充
+2. **使用原始字符串**: 服务类使用 `get_raw()` 获取模板，不进行变量渲染
+3. **模板缺失**: 缺失的模板会被跳过并记录警告日志
+
+## 常见问题
+
+### Q: 覆盖后 MaiBot 回复不符合预期？
+
+检查：
+1. 模板是否包含所有必需的变量占位符
+2. `override_templates` 配置是否包含目标模板名称
+3. 查看 Amaidesu 日志确认 template_info 已注入
+
+### Q: 如何临时禁用覆盖？
+
+设置 `enable_prompt_override = false` 或注释掉该配置项。
+
+### Q: 多个 DecisionProvider 会冲突吗？
+
+不会。`template_info` 在 `MaiCoreDecisionProvider` 层注入，其他 DecisionProvider（如 LLMDecisionProvider）不使用此机制。
+
+## 相关文件
+
+- 服务类: `src/modules/prompts/template_override_service.py`
+- Provider 修改: `src/domains/decision/providers/maicore/maicore_decision_provider.py`
+- 模板目录: `src/modules/prompts/templates/maibot_override/`

docs/development/provider-guide.md

@@ -472,6 +472,37 @@ class MyProvider(OutputProvider):
 | `maicraft` | Maicraft 决策 | `src/domains/decision/providers/maicraft/` |
 | `replay` | 回放决策（调试用） | `src/domains/decision/providers/replay/` |
 
+### MaiCoreDecisionProvider 提示词覆盖
+
+MaiCoreDecisionProvider 支持通过 `template_info` 机制覆盖 MaiBot 的回复提示词，使 VTuber 在直播场景下具有更一致的个性。
+
+#### 启用方式
+
+在 `config.toml` 中配置：
+
+```toml
+[providers.decision.maicore]
+host = "127.0.0.1"
+port = 8000
+
+# 启用提示词覆盖
+enable_prompt_override = true
+override_template_name = "amaidesu_override"
+override_templates = ["replyer_prompt", "chat_target_group1", "chat_target_group2"]
+```
+
+#### 配置项
+
+| 配置项 | 说明 |
+|--------|------|
+| `enable_prompt_override` | 是否启用提示词覆盖 |
+| `override_template_name` | 作用域名称 |
+| `override_templates` | 要覆盖的模板列表 |
+
+#### 自定义模板
+
+模板文件位于 `src/modules/prompts/templates/maibot_override/` 目录。详细说明请参阅 [MaiBot 提示词覆盖文档](maibot-override.md)。
+
 ### OutputProvider（12个）
 
 | 名称 | 说明 | 位置 |

src/domains/decision/providers/maicore/maicore_decision_provider.py

@@ -20,6 +20,10 @@
 from src.modules.config.schemas.base import BaseProviderConfig
 from src.modules.logging import get_logger
 from src.modules.types.base.decision_provider import DecisionProvider
+from src.modules.prompts.template_override_service import (
+    TemplateOverrideService,
+    OverrideConfig,
+)
 
 from .router_adapter import RouterAdapter
 
@@ -81,6 +85,25 @@ class ConfigSchema(BaseProviderConfig):
         action_cooldown_seconds: float = Field(default=5.0, gt=0.0, description="同一 Action 的最小间隔（秒）")
         max_suggested_actions: int = Field(default=3, ge=1, le=10, description="每条消息最大建议数量")
 
+        # 提示词覆盖配置
+        enable_prompt_override: bool = Field(
+            default=True,
+            description="是否启用 MaiBot 提示词覆盖功能"
+        )
+        override_template_name: str = Field(
+            default="amaidesu_override",
+            description="覆盖模板组名（作用域名称）"
+        )
+        override_templates: list[str] = Field(
+            default=[
+                "replyer_prompt",      # think_level=1 时使用
+                "replyer_prompt_0",    # think_level=0 时使用（轻量回复）
+                "chat_target_group1",
+                "chat_target_group2",
+            ],
+            description="要覆盖的提示词名称列表"
+        )
+
     @classmethod
     def get_registration_info(cls) -> Dict[str, Any]:
         """
@@ -133,6 +156,14 @@ def __init__(self, config: Dict[str, Any], context: "ProviderContext"):
         # EventBus 引用（用于事件通知）
         self._event_bus: Optional["EventBus"] = None
 
+        # 初始化提示词覆盖服务
+        override_config = OverrideConfig(
+            enabled=self.typed_config.enable_prompt_override,
+            template_name=self.typed_config.override_template_name,
+            templates=self.typed_config.override_templates,
+        )
+        self._override_service = TemplateOverrideService(override_config)
+
     async def init(self) -> None:
         """
         初始化 MaiCoreDecisionProvider
@@ -242,6 +273,20 @@ def _normalized_to_message_base(self, normalized: "NormalizedMessage") -> Option
                 "original_platform": normalized.source,  # 保留原始平台信息
                 "original_message_id": message_id,  # 存储原始 message_id 用于关联响应
             }
+
+            # 构建 template_info（如果启用）
+            template_info = self._override_service.build_template_info()
+
+            # 构建 group_info（直播间作为群聊处理）
+            # MaiBot 通过 group_info 是否存在来判断是群聊还是私聊
+            # 群聊会使用 replyer_prompt，私聊会使用 private_replyer_prompt
+            from maim_message import GroupInfo
+            group_info = GroupInfo(
+                platform=self.platform,
+                group_id="live_room",  # 直播间群组ID
+                group_name="直播间",  # 直播间名称
+            )
+
             message = MessageBase(
                 message_info=BaseMessageInfo(
                     message_id=message_id,
@@ -250,11 +295,27 @@ def _normalized_to_message_base(self, normalized: "NormalizedMessage") -> Option
                     time=normalized.timestamp,
                     format_info=format_info,
                     additional_config=additional_config,
+                    template_info=template_info,  # 新增：注入 template_info
+                    group_info=group_info,  # 新增：注入 group_info（群聊标识）
                 ),
                 message_segment=seg,
                 raw_message=normalized.text,  # 添加原始消息内容
             )
 
+            # 调试日志
+            if template_info:
+                self.logger.debug(
+                    f"消息携带 template_info: "
+                    f"template_name={template_info.template_name}, "
+                    f"templates={list(template_info.template_items.keys())}"
+                )
+            if group_info:
+                self.logger.debug(
+                    f"消息携带 group_info: "
+                    f"group_id={group_info.group_id}, "
+                    f"group_name={group_info.group_name}"
+                )
+
             return message
         except Exception as e:
             self.logger.error(f"转换为 MessageBase 失败: {e}", exc_info=True)
@@ -281,6 +342,22 @@ async def decide(self, normalized_message: "NormalizedMessage") -> None:
             return
 
         try:
+            # 打印发送的 maim-message 结构（调试用）
+            self.logger.info("发送到 MaiCore 的消息结构:")
+            self.logger.info(f"  - message_id: {message.message_info.message_id}")
+            self.logger.info(f"  - platform: {message.message_info.platform}")
+            self.logger.info(f"  - user_info: {message.message_info.user_info}")
+            self.logger.info(f"  - group_info: {message.message_info.group_info}")
+            self.logger.info(f"  - template_info: {message.message_info.template_info}")
+            if message.message_info.group_info:
+                self.logger.info(f"    - group_id: {message.message_info.group_info.group_id}")
+                self.logger.info(f"    - group_name: {message.message_info.group_info.group_name}")
+            if message.message_info.template_info:
+                self.logger.info(f"    - template_default: {message.message_info.template_info.template_default}")
+                self.logger.info(f"    - template_name: {message.message_info.template_info.template_name}")
+                self.logger.info(f"    - template_items keys: {list(message.message_info.template_info.template_items.keys()) if message.message_info.template_info.template_items else None}")
+            # 打印完整消息字典（调试用）
+            self.logger.debug(f"完整消息字典: {message.to_dict()}")
             await self._router_adapter.send(message)
             self.logger.debug(f"消息已发送至 MaiCore (id: {message.message_info.message_id})")
         except Exception as e:

src/domains/decision/providers/maicore/router_adapter.py

@@ -55,6 +55,11 @@ async def send(self, message: MessageBase) -> None:
 
         try:
             self.logger.debug(f"准备发送消息: {message.message_info.message_id}")
+            # 打印序列化后的消息（调试用）
+            msg_dict = message.to_dict()
+            self.logger.info("RouterAdapter 发送的消息字典:")
+            self.logger.info(f"  - group_info: {msg_dict.get('message_info', {}).get('group_info')}")
+            self.logger.info(f"  - template_info: {msg_dict.get('message_info', {}).get('template_info')}")
             await self._router.send_message(message)
             self.logger.debug(f"消息 {message.message_info.message_id} 已发送")
         except Exception as e:

src/modules/prompts/__init__.py

@@ -24,11 +24,17 @@
     get_prompt_manager,
     reset_prompt_manager,
 )
+from src.modules.prompts.template_override_service import (
+    OverrideConfig,
+    TemplateOverrideService,
+)
 
 __all__ = [
     "PromptManager",
     "PromptTemplate",
     "TemplateMetadata",
     "get_prompt_manager",
     "reset_prompt_manager",
+    "OverrideConfig",
+    "TemplateOverrideService",
 ]