yuanbao_tools.py 21 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493
  1. """yuanbao_tools.py - 元宝平台工具集 (the "hermes-yuanbao" toolset).
  2. get_group_info / query_group_members / search_sticker / send_sticker / send_dm. Sticker
  3. flow mirrors chatbot-web's sticker-search/sticker-send: the LLM should search_sticker for
  4. a sticker_id (or pass the Chinese name), then send_sticker — never bare Unicode emoji.
  5. The active adapter singleton lives in ``plugins.platforms.yuanbao.adapter.YuanbaoAdapter.get_active``.
  6. """
  7. from __future__ import annotations
  8. import functools
  9. import logging
  10. from contextlib import suppress
  11. from pathlib import Path
  12. from typing import Tuple
  13. from tools.registry import registry, tool_result
  14. logger = logging.getLogger(__name__)
  15. _USER_TYPE_LABEL = {0: "unknown", 1: "user", 2: "yuanbao_ai", 3: "bot"}
  16. MENTION_HINT = (
  17. 'To @mention a user, you MUST use the format: '
  18. 'space + @ + nickname + space (e.g. " @Alice ").'
  19. )
  20. # Image extensions for media dispatch (mirrors MessageSender.IMAGE_EXTS)
  21. _IMAGE_EXTS = frozenset({".jpg", ".jpeg", ".png", ".gif", ".webp", ".bmp"})
  22. class _YbError(Exception):
  23. """Tool-level failure; ``payload`` is the error envelope returned to the model."""
  24. def __init__(self, msg: str, **extra):
  25. super().__init__(msg)
  26. self.payload = {"success": False, "error": msg, **extra}
  27. def _yb_tool(label: str):
  28. """Handler decorator: ``fn(args)`` → tool_result; ``_YbError`` → its envelope; else logged envelope."""
  29. def deco(fn):
  30. @functools.wraps(fn)
  31. async def handler(args, **kw):
  32. try:
  33. return tool_result(await fn(args))
  34. except _YbError as exc:
  35. return tool_result(exc.payload)
  36. except Exception as exc:
  37. logger.exception("[yuanbao_tools] %s error", label)
  38. return tool_result(_YbError(str(exc)).payload)
  39. return handler
  40. return deco
  41. def _get_active_adapter():
  42. """Lazy import to avoid ImportError when plugins.platforms.yuanbao is unavailable."""
  43. with suppress(ImportError):
  44. from plugins.platforms.yuanbao.adapter import YuanbaoAdapter
  45. return YuanbaoAdapter.get_active()
  46. return None
  47. def _adapter():
  48. if (adapter := _get_active_adapter()) is None:
  49. raise _YbError("Yuanbao adapter is not connected")
  50. return adapter
  51. def _session_env(name: str) -> str:
  52. with suppress(Exception):
  53. from gateway.session_context import get_session_env
  54. return get_session_env(name, "")
  55. return ""
  56. def _nick(m: dict, default: str = "") -> str:
  57. return m.get("nickname", m.get("nick_name", default))
  58. async def _members(adapter, group_code: str) -> list:
  59. raw = await adapter.get_group_member_list(group_code)
  60. if raw is None:
  61. raise _YbError("get_group_member_list returned None")
  62. return raw.get("members", [])
  63. async def _resolve_dm_recipient(adapter, group_code: str, name: str) -> tuple[str, str]:
  64. """Resolve ``name`` to (user_id, nickname) via the group member list; >1 partial match raises
  65. with ``candidates`` for disambiguation instead of guessing."""
  66. if not group_code:
  67. raise _YbError("group_code is required when user_id is not provided")
  68. if not name:
  69. raise _YbError("name is required when user_id is not provided")
  70. filt = name.strip().lower()
  71. matched = [m for m in await _members(adapter, group_code)
  72. if filt in (m.get("nickname") or m.get("nick_name") or "").lower()]
  73. if not matched:
  74. raise _YbError(f'No member matching "{name}" found in group {group_code}.')
  75. if len(matched) > 1:
  76. raise _YbError(
  77. f'Multiple members match "{name}". Please specify which one.',
  78. candidates=[{"user_id": m.get("user_id", ""), "nickname": _nick(m)} for m in matched],
  79. )
  80. m = matched[0]
  81. return m.get("user_id", ""), _nick(m, name)
  82. @_yb_tool("get_group_info")
  83. async def get_group_info(args) -> dict:
  84. """查询群基本信息(群名、群主、成员数)。"""
  85. group_code = args.get("group_code", "")
  86. if not group_code:
  87. raise _YbError("group_code is required")
  88. gi = await _adapter().query_group_info(group_code)
  89. if gi is None:
  90. raise _YbError("query_group_info returned None")
  91. return {
  92. "success": True, "group_code": group_code, "group_name": gi.get("group_name", ""),
  93. "member_count": gi.get("member_count", 0),
  94. "owner": {"user_id": gi.get("owner_id", ""), "nickname": gi.get("owner_nickname", "")},
  95. "note": 'The group is called "派 (Pai)" in the app.',
  96. }
  97. @_yb_tool("query_group_members")
  98. async def query_group_members(args) -> dict:
  99. """统一的群成员查询(对齐 TS query_session_members)。
  100. action: find (按昵称模糊搜索; 无 name 时等同 list_all) / list_bots / list_all (默认)."""
  101. group_code, name = args.get("group_code", ""), args.get("name", "")
  102. action = args.get("action", "list_all")
  103. if not group_code:
  104. raise _YbError("group_code is required")
  105. all_members = [
  106. {"user_id": m.get("user_id", ""), "nickname": _nick(m),
  107. "role": _USER_TYPE_LABEL.get(m.get("user_type", m.get("role", 0)), "unknown")}
  108. for m in await _members(_adapter(), group_code)
  109. ]
  110. if not all_members:
  111. raise _YbError("No members found in this group.")
  112. hint = {"mention_hint": MENTION_HINT} if args.get("mention", False) else {}
  113. def _listing(ok: bool, msg: str, members: list) -> dict:
  114. return {"success": ok, "msg": msg, "members": members, **hint}
  115. if action == "list_bots":
  116. bots = [m for m in all_members if m["role"] in {"yuanbao_ai", "bot"}]
  117. if not bots:
  118. raise _YbError("No bots found in this group.")
  119. return _listing(True, f"Found {len(bots)} bot(s).", bots)
  120. if action == "find" and name:
  121. filt = name.strip().lower()
  122. matched = [m for m in all_members if filt in m["nickname"].lower()]
  123. if matched:
  124. return _listing(True, f'Found {len(matched)} member(s) matching "{name}".', matched)
  125. return _listing(False, f'No match for "{name}". All members listed below.', all_members)
  126. return _listing(True, f"Found {len(all_members)} member(s).", all_members)
  127. @_yb_tool("search_sticker")
  128. async def search_sticker(args) -> dict:
  129. """在内置贴纸表中按关键词模糊搜索,返回 Top-N 候选(空 query 返回前 N 条)。"""
  130. from plugins.platforms.yuanbao.yuanbao_sticker import search_stickers
  131. query, limit = args.get("query", ""), args.get("limit", 10)
  132. try:
  133. safe_limit = max(1, min(50, int(limit) if limit else 10))
  134. except (TypeError, ValueError):
  135. safe_limit = 10
  136. matches = search_stickers(query or "", limit=safe_limit)
  137. return {
  138. "success": True, "query": query or "", "count": len(matches),
  139. "results": [{k: s.get(k, "") for k in ("sticker_id", "name", "description", "package_id")}
  140. for s in matches],
  141. }
  142. @_yb_tool("send_sticker")
  143. async def send_sticker(args) -> dict:
  144. """向 chat_id(缺省取当前会话 HERMES_SESSION_CHAT_ID)发送一张内置贴纸(TIMFaceElem)。
  145. ``sticker``: 名称(如 "六六六")或 sticker_id(如 "278");为空时随机发送。
  146. ``chat_id``: ``direct:{account_id}`` / ``group:{group_code}`` / 裸 account_id。"""
  147. from plugins.platforms.yuanbao.yuanbao_sticker import get_sticker_by_id, get_sticker_by_name, get_random_sticker
  148. target = (args.get("chat_id", "") or "").strip() or _session_env("HERMES_SESSION_CHAT_ID")
  149. if not target:
  150. raise _YbError("chat_id is required (no active yuanbao session detected)")
  151. adapter = _adapter()
  152. raw = (args.get("sticker", "") or "").strip()
  153. if not raw:
  154. sticker_obj = get_random_sticker()
  155. else:
  156. sticker_obj = (get_sticker_by_id(raw) if raw.isdigit() else None) or get_sticker_by_name(raw)
  157. if sticker_obj is None:
  158. raise _YbError(f"Sticker not found: {raw!r}. Use search_sticker first to discover available stickers.")
  159. result = await adapter.send_sticker(chat_id=target, sticker_name=sticker_obj.get("name", ""),
  160. reply_to=args.get("reply_to", "") or None)
  161. if not getattr(result, "success", False):
  162. raise _YbError(getattr(result, "error", "send_sticker failed"))
  163. return {
  164. "success": True, "chat_id": target,
  165. "sticker": {"sticker_id": sticker_obj.get("sticker_id", ""), "name": sticker_obj.get("name", "")},
  166. "message_id": getattr(result, "message_id", None),
  167. "note": "Sticker delivered to the chat. If you have additional text to say, reply now; otherwise end your turn without generating text.",
  168. }
  169. @_yb_tool("send_dm")
  170. async def send_dm(args) -> dict:
  171. """Send a DM to a group member, with optional media. group_code defaults to the session's
  172. "group:<code>" chat_id. Without ``user_id`` the member list is searched by ``name`` (partial,
  173. case-insensitive; >1 match returns candidates). media_files items are {"path", "is_voice"} dicts or
  174. (path, is_voice) pairs; ``MEDIA:<path>`` tags in the text count too. Partial media failures are
  175. reported in ``note``, not as failure."""
  176. group_code = args.get("group_code", "")
  177. if not group_code and (chat_id := _session_env("HERMES_SESSION_CHAT_ID")).startswith("group:"):
  178. group_code = chat_id.split(":", 1)[1]
  179. media_files = []
  180. for item in args.get("media_files") or []:
  181. if isinstance(item, dict):
  182. media_files.append((item.get("path", ""), bool(item.get("is_voice", False))))
  183. elif isinstance(item, (list, tuple)) and len(item) >= 2:
  184. media_files.append((str(item[0]), bool(item[1])))
  185. from gateway.platforms.base import BasePlatformAdapter
  186. embedded_media, message = BasePlatformAdapter.extract_media(args.get("message", ""))
  187. media_files = BasePlatformAdapter.filter_media_delivery_paths(media_files + list(embedded_media or []))
  188. if not message and not media_files:
  189. raise _YbError("message or media_files is required")
  190. adapter = _adapter()
  191. name = args.get("name", "")
  192. resolved_user_id, resolved_nickname = (args.get("user_id", "") or "").strip(), name.strip()
  193. if not resolved_user_id:
  194. resolved_user_id, resolved_nickname = await _resolve_dm_recipient(adapter, group_code, name)
  195. if not resolved_user_id:
  196. raise _YbError("Could not resolve user_id")
  197. chat_id = f"direct:{resolved_user_id}"
  198. last_result = None
  199. errors: list[str] = []
  200. if message and message.strip():
  201. last_result = await adapter.send_dm(resolved_user_id, message, group_code=group_code)
  202. if not last_result.success:
  203. errors.append(last_result.error or "text send failed")
  204. for media_path, _is_voice in media_files:
  205. send = adapter.send_image_file if Path(media_path).suffix.lower() in _IMAGE_EXTS else adapter.send_document
  206. last_result = await send(chat_id, media_path, group_code=group_code)
  207. if not last_result.success:
  208. errors.append(last_result.error or "media send failed")
  209. if last_result is None:
  210. raise _YbError("No deliverable text or media remained")
  211. if errors and not last_result.success:
  212. raise _YbError("; ".join(errors))
  213. note = f'DM sent to "{resolved_nickname}" successfully.'
  214. if errors:
  215. note += f" (partial failure: {'; '.join(errors)})"
  216. return {"success": True, "user_id": resolved_user_id, "nickname": resolved_nickname,
  217. "message_id": last_result.message_id, "note": note}
  218. def _check_yuanbao():
  219. """Toolset availability check — True when running in a yuanbao gateway session."""
  220. return _session_env("HERMES_SESSION_PLATFORM") == "yuanbao" or _get_active_adapter() is not None
  221. # (schema, handler, emoji); the tool name is schema["name"].
  222. _TOOLS = (
  223. (
  224. {
  225. "name": "yb_query_group_info",
  226. "description": (
  227. "Query a group's name, owner and member count (a group is '派/Pai' in the app)."
  228. ),
  229. "parameters": {
  230. "type": "object",
  231. "properties": {
  232. "group_code": {
  233. "type": "string",
  234. "description": "The unique group identifier (group_code).",
  235. },
  236. },
  237. "required": ["group_code"],
  238. },
  239. },
  240. get_group_info,
  241. "👥",
  242. ),
  243. (
  244. {
  245. "name": "yb_query_group_members",
  246. "description": (
  247. "Query members of a group (called '派/Pai' in the app). "
  248. "Use this tool when you need to @mention someone, find a user by name, "
  249. "list bots (including Yuanbao AI), or list all members. "
  250. "IMPORTANT: You MUST call this tool before @mentioning any user, "
  251. "because you need the exact nickname to construct the @mention format."
  252. ),
  253. "parameters": {
  254. "type": "object",
  255. "properties": {
  256. "group_code": {
  257. "type": "string",
  258. "description": "The unique group identifier (group_code).",
  259. },
  260. "action": {
  261. "type": "string",
  262. "enum": ["find", "list_bots", "list_all"],
  263. "description": (
  264. "find — search a user by name (use when you need to @mention or look up someone); "
  265. "list_bots — list bots and Yuanbao AI assistants; "
  266. "list_all — list all members."
  267. ),
  268. },
  269. "name": {
  270. "type": "string",
  271. "description": (
  272. "User name to search (partial match, case-insensitive). "
  273. "Required for 'find'. Use the name the user mentioned in the conversation."
  274. ),
  275. },
  276. "mention": {
  277. "type": "boolean",
  278. "description": (
  279. "Set to true when you need to @mention/at someone in your reply. "
  280. "The response will include the exact @mention format to use."
  281. ),
  282. },
  283. },
  284. "required": ["group_code", "action"],
  285. },
  286. },
  287. query_group_members,
  288. "📋",
  289. ),
  290. (
  291. {
  292. "name": "yb_send_dm",
  293. "description": (
  294. "Send a private message (DM / 私信) to a group member by name, with optional media. "
  295. "It looks the user up in the group member list (or pass user_id if known). "
  296. "Use it when someone asks to privately message a user. "
  297. "Supports text, images, and file attachments."
  298. ),
  299. "parameters": {
  300. "type": "object",
  301. "properties": {
  302. "group_code": {
  303. "type": "string",
  304. "description": (
  305. "The group where the target user belongs. "
  306. "Extract from chat_id: 'group:328306697' → '328306697'. "
  307. "Required when user_id is not provided."
  308. ),
  309. },
  310. "name": {
  311. "type": "string",
  312. "description": (
  313. "Target user's display name (partial match, case-insensitive). "
  314. "Required when user_id is not provided."
  315. ),
  316. },
  317. "message": {
  318. "type": "string",
  319. "description": "The message text to send as a DM. Can be empty if only sending media.",
  320. },
  321. "user_id": {
  322. "type": "string",
  323. "description": (
  324. "Target user's account ID. If provided, skips the member lookup. "
  325. "Usually obtained from a previous yb_query_group_members call."
  326. ),
  327. },
  328. "media_files": {
  329. "type": "array",
  330. "description": (
  331. "Optional list of media files to send along with the DM. "
  332. "Images (.jpg/.png/.gif/.webp/.bmp) are sent as image messages; "
  333. "other files are sent as document attachments."
  334. ),
  335. "items": {
  336. "type": "object",
  337. "properties": {
  338. "path": {
  339. "type": "string",
  340. "description": "Absolute local file path of the media to send.",
  341. },
  342. "is_voice": {
  343. "type": "boolean",
  344. "description": "Whether this file is a voice message (default false).",
  345. },
  346. },
  347. "required": ["path"],
  348. },
  349. },
  350. },
  351. "required": [],
  352. },
  353. },
  354. send_dm,
  355. "✉️",
  356. ),
  357. (
  358. {
  359. "name": "yb_search_sticker",
  360. "description": (
  361. "Search the built-in Yuanbao sticker (TIM face / 表情包) catalogue by keyword. "
  362. "Returns the top matching candidates with sticker_id, name, and description. "
  363. "Use this BEFORE yb_send_sticker to discover the right sticker_id. "
  364. "Sticker = 贴纸 = TIM face — NOT a message reaction. "
  365. "Prefer sending a sticker over bare Unicode emoji when reacting/expressing emotion."
  366. ),
  367. "parameters": {
  368. "type": "object",
  369. "properties": {
  370. "query": {
  371. "type": "string",
  372. "description": (
  373. "Search keyword (Chinese or English, e.g. '666', '比心', 'cool', '吃瓜'). "
  374. "Empty string returns the first N stickers."
  375. ),
  376. },
  377. "limit": {
  378. "type": "integer",
  379. "description": "Max number of candidates to return (default 10, max 50).",
  380. },
  381. },
  382. "required": [],
  383. },
  384. },
  385. search_sticker,
  386. "🔍",
  387. ),
  388. (
  389. {
  390. "name": "yb_send_sticker",
  391. "description": (
  392. "Send a built-in sticker (TIMFaceElem / 贴纸表情) to the current Yuanbao chat. "
  393. "Call yb_search_sticker first if you don't know the sticker_id/name. "
  394. "Sticker = 贴纸 = TIM face — NOT a message reaction. "
  395. "CRITICAL: Whenever the user asks you to send a sticker / 贴纸 / 表情包, you MUST "
  396. "use this tool. DO NOT draw a PNG via execute_code / Pillow / matplotlib and "
  397. "then call send_image_file — that produces a fake 'sticker' image instead of a "
  398. "real TIM face and is the WRONG path. If no suitable sticker_id is known, call "
  399. "yb_search_sticker first. When the recent thread shows users sending stickers, "
  400. "prefer matching that tone by replying with a sticker instead of (or in "
  401. "addition to) text."
  402. ),
  403. "parameters": {
  404. "type": "object",
  405. "properties": {
  406. "sticker": {
  407. "type": "string",
  408. "description": (
  409. "Sticker name (e.g. '六六六', '比心', 'ok') or numeric sticker_id "
  410. "(e.g. '278'). Empty string sends a random built-in sticker."
  411. ),
  412. },
  413. "chat_id": {
  414. "type": "string",
  415. "description": (
  416. "Target chat. Defaults to the current session. "
  417. "Format: 'direct:{account_id}', 'group:{group_code}', or bare account_id."
  418. ),
  419. },
  420. "reply_to": {
  421. "type": "string",
  422. "description": "Optional ref_msg_id to quote-reply (group chat only).",
  423. },
  424. },
  425. "required": [],
  426. },
  427. },
  428. send_sticker,
  429. "🎨",
  430. ),
  431. )
  432. for _schema, _handler, _emoji in _TOOLS:
  433. registry.register(
  434. name=_schema["name"], toolset="hermes-yuanbao", schema=_schema, handler=_handler,
  435. check_fn=_check_yuanbao, is_async=True, emoji=_emoji,
  436. )