Plugin:[QQ] 猫娘代发言追回 (Project-N-E-K-O#1312)

* Plugin:[QQ] 猫娘代发言追回

* Plugin:[QQ] 猫娘代发言追回

* Plugin:[QQ] 猫娘代发言追回

* Plugin:[QQ] 猫娘代发言追回

Author: zhaijiunknow

plugin/plugins/qq_auto_reply/__init__.py

@@ -25,7 +25,7 @@
 from .prompting import QQAutoReplyPromptingMixin
 from .qq_client import QQClient
 from .session import QQAutoReplySessionMixin
-from .targets import QQAutoReplyTargetsMixin
+from .targets import QQAutoReplyTargetsMixin, QQAutoReplyValidationError
 
 
 def build_open_ui_payload(*, plugin_id: str, available: bool, i18n=None) -> dict[str, Any]:
@@ -388,7 +388,7 @@ async def init_config(self, guide_step_config_done: Optional[bool] = None, **_):
         self._refresh_admin_qq()
         return Ok(await self._build_dashboard_state())
 
-    @plugin_entry(id="qq_auto_reply_get_dashboard_state", name=tr("entries.get_dashboard_state.name", default="获取控制面板状态"), description=tr("entries.get_dashboard_state.description", default="返回 QQ 自动回复前端控制面板所需的完整状态。"), input_schema={"type": "object", "properties": {}})
+    @plugin_entry(id="get_dashboard_state", name=tr("entries.get_dashboard_state.name", default="获取控制面板状态"), description=tr("entries.get_dashboard_state.description", default="返回 QQ 自动回复前端控制面板所需的完整状态。"), input_schema={"type": "object", "properties": {}})
     async def get_dashboard_state(self, **_):
         return Ok(await self._build_dashboard_state())
 
@@ -523,7 +523,7 @@ async def remove_trusted_group(self, group_id: str, **_):
         payload["persisted"] = success
         return Ok(payload)
 
-    @plugin_entry(id="qq_auto_reply_sync_qrcode", name=tr("entries.sync_qrcode.name", default="刷新二维码"), description=tr("entries.sync_qrcode.description", default="重新复制 NapCat 登录二维码到插件静态目录并返回最新状态。"), input_schema={"type": "object", "properties": {}})
+    @plugin_entry(id="sync_qrcode", name=tr("entries.sync_qrcode.name", default="刷新二维码"), description=tr("entries.sync_qrcode.description", default="重新复制 NapCat 登录二维码到插件静态目录并返回最新状态。"), input_schema={"type": "object", "properties": {}})
     async def sync_qrcode(self, **_):
         await self._sync_napcat_qrcode_into_static()
         return Ok(await self._build_dashboard_state())
@@ -550,6 +550,92 @@ async def stop_auto_reply(self, **_):
         await self._stop_auto_reply_runtime(stop_napcat=False)
         return Ok({"status": "stopped"})
 
+    @plugin_entry(id="send_private_proactive_message", name=tr("entries.send_private_proactive_message.name", default="主动发送私聊消息"), description=tr("entries.send_private_proactive_message.description", default="让 AI 生成一条私聊消息并主动发送给指定 QQ 用户。"), input_schema={"type": "object", "properties": {"target": {"type": "string"}, "message": {"type": "string"}}, "required": ["target", "message"], "additionalProperties": False}, metadata={"timeout": 90})
+    async def send_private_proactive_message(self, target: str, message: str, **_):
+        try:
+            self._ensure_qq_client_connected()
+            resolved_qq, matched_nickname = self._resolve_private_message_target(target)
+            prompt_message = self._validate_outbound_message(message)
+            permission_level = "admin" if resolved_qq == self._admin_qq else (self.permission_mgr.get_permission_level(resolved_qq) if self.permission_mgr else "trusted")
+            if permission_level == "none":
+                permission_level = "trusted"
+            reply_text = await self._generate_reply(
+                prompt_message,
+                permission_level,
+                resolved_qq,
+                is_group=False,
+                user_nickname=matched_nickname,
+                use_memory_context=permission_level == "admin",
+                persist_memory=False,
+                ephemeral_session=True,
+            )
+            if not reply_text:
+                return Err(SdkError(f"GENERATE_FAILED: {self.i18n.t('errors.proactive_private_generate_failed', default='AI 未生成可发送的私聊内容')}"))
+            await self.qq_client.send_message(resolved_qq, reply_text)
+            return Ok({
+                "status": "sent",
+                "target": str(target or "").strip(),
+                "resolved_qq": resolved_qq,
+                "resolved_nickname": matched_nickname,
+                "message_prompt": prompt_message,
+                "generated_message": reply_text,
+            })
+        except QQAutoReplyValidationError as e:
+            code = e.code
+            message_text = str(e)
+            if code in ("NICKNAME_NOT_FOUND", "NICKNAME_AMBIGUOUS"):
+                return Err(SdkError(f"{code}: {message_text}"))
+            if code == "INVALID_TARGET":
+                return Err(SdkError(f"INVALID_TARGET: {self.i18n.t('errors.proactive_invalid_target', default=message_text)}"))
+            if code == "INVALID_MESSAGE":
+                return Err(SdkError(f"INVALID_MESSAGE: {self.i18n.t('errors.proactive_invalid_message', default=message_text)}"))
+            return Err(SdkError(f"INVALID_TARGET: {message_text}"))
+        except RuntimeError as e:
+            return Err(SdkError(f"NOT_READY: {self.i18n.t('errors.proactive_not_ready', default='{error}', error=str(e))}"))
+        except Exception as e:
+            self.logger.exception("Failed to send proactive private QQ message")
+            return Err(SdkError(f"SEND_FAILED: {self.i18n.t('errors.proactive_send_failed', default='{error}', error=str(e))}"))
+
+    @plugin_entry(id="send_group_proactive_message", name=tr("entries.send_group_proactive_message.name", default="主动发送群聊消息"), description=tr("entries.send_group_proactive_message.description", default="让 AI 生成一条群聊消息并主动发送给指定 QQ 群。"), input_schema={"type": "object", "properties": {"group_id": {"type": "string"}, "message": {"type": "string"}}, "required": ["group_id", "message"], "additionalProperties": False}, metadata={"timeout": 90})
+    async def send_group_proactive_message(self, group_id: str, message: str, **_):
+        try:
+            self._ensure_qq_client_connected()
+            normalized_group_id = self._validate_group_id(group_id)
+            prompt_message = self._validate_outbound_message(message)
+            reply_text = await self._generate_reply(
+                prompt_message,
+                "open",
+                self._admin_qq or "0",
+                is_group=True,
+                group_id=normalized_group_id,
+                use_memory_context=False,
+                persist_memory=False,
+                ephemeral_session=True,
+                group_facing=True,
+            )
+            if not reply_text:
+                return Err(SdkError(f"GENERATE_FAILED: {self.i18n.t('errors.proactive_group_generate_failed', default='AI 未生成可发送的群聊内容')}"))
+            await self.qq_client.send_group_message(normalized_group_id, reply_text)
+            return Ok({
+                "status": "sent",
+                "group_id": normalized_group_id,
+                "message_prompt": prompt_message,
+                "generated_message": reply_text,
+            })
+        except QQAutoReplyValidationError as e:
+            code = e.code
+            message_text = str(e)
+            if code == "INVALID_GROUP_ID":
+                return Err(SdkError(f"INVALID_GROUP_ID: {self.i18n.t('errors.proactive_invalid_group_id', default=message_text)}"))
+            if code == "INVALID_MESSAGE":
+                return Err(SdkError(f"INVALID_MESSAGE: {self.i18n.t('errors.proactive_invalid_message', default=message_text)}"))
+            return Err(SdkError(f"INVALID_GROUP_ID: {message_text}"))
+        except RuntimeError as e:
+            return Err(SdkError(f"NOT_READY: {self.i18n.t('errors.proactive_not_ready', default='{error}', error=str(e))}"))
+        except Exception as e:
+            self.logger.exception("Failed to send proactive group QQ message")
+            return Err(SdkError(f"SEND_FAILED: {self.i18n.t('errors.proactive_send_failed', default='{error}', error=str(e))}"))
+
     async def _stop_auto_reply_runtime(self, *, stop_napcat: bool):
         self._running = False
         if self._message_task:
@@ -574,6 +660,19 @@ async def _stop_auto_reply_runtime(self, *, stop_napcat: bool):
             await self._stop_managed_napcat()
         self._session_locks.clear()
 
+    def _track_handler_task(self, task: asyncio.Task) -> None:
+        self._handler_tasks.add(task)
+        task.add_done_callback(self._on_handler_task_done)
+
+    def _on_handler_task_done(self, task: asyncio.Task) -> None:
+        self._handler_tasks.discard(task)
+        try:
+            task.result()
+        except asyncio.CancelledError:
+            pass
+        except Exception as exc:
+            self.logger.error(f"Message handler task failed: {exc}")
+
     async def _process_messages(self):
         while self._running:
             try:
@@ -651,10 +750,6 @@ async def _handle_normal_relay(self, message_text: str, sender_id: str, source_t
         await self.qq_client.send_message(self._admin_qq, relay_text)
         return None
 
-    def _track_handler_task(self, task: asyncio.Task) -> None:
-        self._handler_tasks.add(task)
-        task.add_done_callback(self._handler_tasks.discard)
-
     async def _run_message_handler(self, message: Dict[str, Any]) -> None:
         session_key = self._message_session_key(message)
         async with self._message_concurrency:

plugin/plugins/qq_auto_reply/doc/README.en.md

@@ -95,7 +95,8 @@ Notes:
 - Existing character persona and model configuration are reused.
 - Proactive private sending may read memory context for generation, but this action itself is not written back into memory.
 - Proactive group sending is not written into memory.
-- `qq_number` / `group_id` must be numeric strings.
+- The private entry uses `target`: it can be either a numeric QQ ID or a nickname already configured in the trusted-user list.
+- `group_id` must be a numeric string.
 - `message` cannot be empty.
 - Auto-reply must already be started and OneBot must be connected; otherwise the entry fails immediately.
 

plugin/plugins/qq_auto_reply/doc/README.es.md

@@ -95,7 +95,8 @@ Notas:
 - Se reutilizan la personalidad del personaje y la configuración del modelo existentes.
 - En mensajes privados proactivos puede leerse el contexto de memoria, pero este envío no se vuelve a escribir en la memoria.
 - Los envíos proactivos a grupos no se escriben en memoria.
-- `qq_number` / `group_id` deben ser cadenas numéricas puras.
+- La entrada privada usa `target`: puede ser un ID numérico de QQ o un apodo ya configurado en la lista de usuarios de confianza.
+- `group_id` debe ser una cadena numérica.
 - `message` no puede estar vacío.
 - La respuesta automática debe estar ya iniciada y OneBot debe estar conectado; de lo contrario, la entrada fallará inmediatamente.
 

plugin/plugins/qq_auto_reply/doc/README.ja.md

@@ -95,7 +95,8 @@ OneBot プロトコル経由で QQ に接続し、権限に応じたインテリ
 - 既存のキャラ設定とモデル設定をそのまま使います。
 - 個人チャットへの能動送信では記憶コンテキストを参照する場合がありますが、この送信自体は記憶へ書き戻しません。
 - グループへの能動送信も記憶へは書き込みません。
-- `qq_number` / `group_id` は数字だけの文字列である必要があります。
+- 個人向け entry は `target` を使います。数値の QQ ID、または信頼ユーザー一覧に設定済みのニックネームを指定できます。
+- `group_id` は数字だけの文字列である必要があります。
 - `message` は空にできません。
 - あらかじめ自動返信が起動していて、OneBot が接続済みである必要があります。
 

plugin/plugins/qq_auto_reply/doc/README.ko.md

@@ -97,7 +97,8 @@ OneBot 프로토콜을 통해 QQ에 연결하고, 권한에 따라 지능형 자
 - 기존 캐릭터 설정과 모델 설정을 그대로 사용합니다.
 - 개인 채팅 능동 발신은 메모리 문맥을 읽어 생성할 수 있지만, 이 발신 자체는 메모리에 다시 기록되지 않습니다.
 - 그룹 능동 발신도 메모리에 기록되지 않습니다.
-- `qq_number` / `group_id` 는 숫자로만 이루어진 문자열이어야 합니다.
+- 개인 발신 entry 는 `target` 을 사용하며, 숫자 QQ ID 또는 신뢰 사용자 목록에 등록된 별명을 지정할 수 있습니다.
+- `group_id` 는 숫자로만 이루어진 문자열이어야 합니다.
 - `message` 는 비워둘 수 없습니다.
 - 먼저 자동 응답이 시작되어 있고 OneBot이 연결되어 있어야 합니다.
 

plugin/plugins/qq_auto_reply/doc/README.md

@@ -96,7 +96,8 @@ https://github.com/NapNeko/NapCatQQ/releases
 - 会复用现有角色人设与模型配置
 - 私聊主动发送会读取记忆库上下文辅助生成，但不会把这次主动发送写回记忆库
 - 群聊主动发送不会写入记忆库
-- `qq_number` / `group_id` 必须是纯数字字符串
+- 私聊入口使用 `target` 参数：可以填写纯数字 QQ 号，或填写已配置在信任用户列表中的昵称
+- `group_id` 必须是纯数字字符串
 - `message` 不能为空
 - 使用前需先启动自动回复并确保 OneBot 已连接，否则入口会直接报错
 

plugin/plugins/qq_auto_reply/doc/README.pt.md

@@ -95,7 +95,8 @@ Observações:
 - A personalidade do personagem e a configuração do modelo existentes são reutilizadas.
 - Em envios proativos privados, o contexto de memória pode ser lido, mas esse envio não é escrito de volta na memória.
 - Envios proativos para grupos não são escritos na memória.
-- `qq_number` / `group_id` devem ser cadeias numéricas puras.
+- A entrada privada usa `target`: ele pode ser um ID numérico do QQ ou um apelido já configurado na lista de usuários confiáveis.
+- `group_id` deve ser uma cadeia numérica.
 - `message` não pode ser vazio.
 - A resposta automática deve estar iniciada e o OneBot conectado; caso contrário, a entrada falha imediatamente.
 

plugin/plugins/qq_auto_reply/doc/README.ru.md

@@ -95,7 +95,8 @@
 - Используются текущие настройки персонажа и модели.
 - При активной отправке в личку может быть прочитан контекст памяти, но этот отправленный текст сам в память не записывается.
 - При активной отправке в группу память не обновляется.
-- `qq_number` / `group_id` должны быть строками, состоящими только из цифр.
+- Личная entry использует `target`: это может быть числовой QQ ID или ник, уже добавленный в список доверенных пользователей.
+- `group_id` должен быть строкой, состоящей только из цифр.
 - `message` не может быть пустым.
 - Автоответчик должен быть уже запущен, а OneBot должен быть подключён, иначе entry завершится ошибкой.
 

plugin/plugins/qq_auto_reply/doc/README.zh-TW.md

@@ -95,7 +95,8 @@
 - 會沿用既有角色設定與模型設定。
 - 私聊主動發送時可能會讀取記憶上下文輔助生成，但這次主動發送本身不會寫回記憶庫。
 - 群組主動發送也不會寫入記憶庫。
-- `qq_number` / `group_id` 必須是純數字字串。
+- 私聊 entry 使用 `target` 參數：可填入純數字 QQ 號，或填入已設定於信任使用者清單中的暱稱。
+- `group_id` 必須是純數字字串。
 - `message` 不能為空。
 - 需先啟動自動回覆並確認 OneBot 已連線，否則 entry 會直接失敗。
 

plugin/plugins/qq_auto_reply/i18n/en-US.json

@@ -19,6 +19,10 @@
   "entries.add_trusted_group.description": "Add a trusted QQ group to the allowlist.",
   "entries.remove_trusted_group.name": "Remove trusted group",
   "entries.remove_trusted_group.description": "Remove a QQ group from the allowlist.",
+  "entries.send_private_proactive_message.name": "Send proactive private message",
+  "entries.send_private_proactive_message.description": "Generate a private QQ message with AI and proactively send it to the target user.",
+  "entries.send_group_proactive_message.name": "Send proactive group message",
+  "entries.send_group_proactive_message.description": "Generate a group QQ message with AI and proactively send it to the target group.",
   "entries.start_auto_reply.name": "Start auto-reply",
   "entries.start_auto_reply.description": "Start listening for QQ messages and auto-replying.",
   "entries.stop_auto_reply.name": "Stop auto-reply",
@@ -37,6 +41,13 @@
   "errors.admin_no_nickname": "Admins are always called Master, so a nickname can’t be set",
   "errors.set_nickname_failed": "Couldn’t save the nickname",
   "errors.start_connect_failed": "Can’t connect to the OneBot service at {url}. Please wake up external NapCat/OneBot first: {error}",
+  "errors.proactive_private_generate_failed": "AI did not generate a private message that can be sent",
+  "errors.proactive_group_generate_failed": "AI did not generate a group message that can be sent",
+  "errors.proactive_invalid_target": "target cannot be empty, and nicknames must exist in the trusted user list",
+  "errors.proactive_invalid_group_id": "group_id cannot be empty and must contain digits only",
+  "errors.proactive_invalid_message": "message cannot be empty",
+  "errors.proactive_not_ready": "{error}",
+  "errors.proactive_send_failed": "{error}",
   "prompts.default_master": "Master",
   "prompts.default_qq_user": "QQ User {sender_id}",
   "prompts.default_ai_assistant": "You are a friendly AI assistant",
@@ -124,6 +135,9 @@
   "ui.tabs.users": "Trusted Users",
   "ui.tabs.groups": "Trusted Groups",
   "ui.actions.add": "Add",
+  "ui.actions.open": "Open UI",
+  "ui.open_path.message": "UI is available",
+  "ui.unavailable.message": "UI is unavailable",
   "ui.actions.save_settings": "Save Settings",
   "ui.empty.no_items": "There’s nothing here yet~",
   "ui.defaults.user": "Trusted Friend",