front/xhs-agent-desktop/engine/xhs_bridge/tools_catalog.py

from __future__ import annotations

from typing import Any, NotRequired, TypedDict


class XhsToolDef(TypedDict):
    name: str
    title: str
    category: str
    description: str
    args_template: dict[str, Any]
    skip_license: bool
    hidden_in_gui: NotRequired[bool]
    interaction_flow: NotRequired[str]  # comment | like | favorite


TOOL_CATEGORIES = ["浏览", "发布", "互动", "用户"]
ANALYSIS_CATEGORIES = ["浏览", "互动", "用户"]
CREATION_CATEGORIES = ["发布"]

# (对外说法, 用户价值) — 按侧栏分组与分类展示
TOOL_CATEGORY_LABELS: dict[str, dict[str, tuple[str, str]]] = {
    "analysis": {
        "浏览": ("竞品/爆款拆解", "知道发什么能引流"),
        "互动": ("评论区截流", "在同行笔记下留痕找客户"),
        "用户": ("对标账号", "了解同行人设与主页"),
    },
    "creation": {
        "发布": ("AI发布", "省时间，坚持日更"),
    },
}


def category_display(nav_group: str, category: str) -> tuple[str, str]:
    """返回分类在 GUI 中的 (对外说法, 用户价值)。"""
    labels = TOOL_CATEGORY_LABELS.get(nav_group, {})
    return labels.get(category, (category, ""))

XHS_TOOLS: list[XhsToolDef] = [
    {
        "name": "check_login_status",
        "title": "检查登录状态",
        "category": "登录",
        "description": "检查当前平台账号是否已登录（无参数）",
        "args_template": {},
        "skip_license": True,
        "hidden_in_gui": True,
    },
    {
        "name": "browser_login",
        "title": "浏览器登录",
        "category": "登录",
        "description": "在 Chrome 中打开小红书并等待扫码登录（须在启动服务页操作）",
        "args_template": {},
        "skip_license": True,
        "hidden_in_gui": True,
    },
    {
        "name": "delete_cookies",
        "title": "重置登录",
        "category": "登录",
        "description": "退出登录并重置浏览器会话",
        "args_template": {},
        "skip_license": True,
        "hidden_in_gui": True,
    },
    {
        "name": "publish_content",
        "title": "发布图文",
        "category": "发布",
        "description": "发布图文笔记。images 至少 1 张，支持本地绝对路径或 HTTP 链接",
        "args_template": {
            "title": "笔记标题",
            "content": "正文内容",
            "images": ["C:/path/to/image.jpg"],
            "tags": ["生活"],
            "visibility": "公开可见",
        },
        "skip_license": False,
    },
    {
        "name": "publish_with_video",
        "title": "发布视频",
        "category": "发布",
        "description": "发布视频笔记，video 为本地视频绝对路径",
        "args_template": {
            "title": "视频标题",
            "content": "视频描述",
            "video": "C:/path/to/video.mp4",
            "tags": ["生活"],
            "visibility": "公开可见",
        },
        "skip_license": False,
    },
    {
        "name": "list_feeds",
        "title": "首页推荐",
        "category": "浏览",
        "description": "打开首页并模拟浏览后加载推荐列表；可按「类型」在结果中筛选（图文/视频）",
        "args_template": {},
        "skip_license": False,
    },
    {
        "name": "search_feeds",
        "title": "搜索内容",
        "category": "浏览",
        "description": "搜索关键词并应用排序/类型/时间等站内筛选，滚动加载后展示列表",
        "args_template": {},
        "skip_license": False,
    },
    {
        "name": "get_feed_detail",
        "title": "AI分析",
        "category": "浏览",
        "description": "查询笔记详情并在右侧进行 AI 拆解分析",
        "args_template": {
            "feed_id": "",
            "xsec_token": "",
            "load_all_comments": False,
            "limit": 20,
        },
        "skip_license": False,
    },
    {
        "name": "post_comment_to_feed",
        "title": "发表评论",
        "category": "互动",
        "description": "对指定帖子发表评论（可配合列表多选批量执行）",
        "interaction_flow": "comment",
        "args_template": {
            "feed_id": "",
            "xsec_token": "",
            "content": "评论内容",
        },
        "skip_license": False,
    },
    {
        "name": "reply_comment_in_feed",
        "title": "回复评论",
        "category": "互动",
        "description": "回复指定评论（comment_id 与 user_id 至少填一个）",
        "args_template": {
            "feed_id": "",
            "xsec_token": "",
            "content": "回复内容",
            "comment_id": "",
            "user_id": "",
        },
        "skip_license": False,
    },
    {
        "name": "like_feed",
        "title": "点赞 / 取消赞",
        "category": "互动",
        "description": "点赞或取消点赞（unlike: true 取消）",
        "interaction_flow": "like",
        "args_template": {
            "feed_id": "",
            "xsec_token": "",
            "unlike": False,
        },
        "skip_license": False,
    },
    {
        "name": "favorite_feed",
        "title": "收藏 / 取消收藏",
        "category": "互动",
        "description": "收藏或取消收藏（unfavorite: true 取消）",
        "interaction_flow": "favorite",
        "args_template": {
            "feed_id": "",
            "xsec_token": "",
            "unfavorite": False,
        },
        "skip_license": False,
    },
    {
        "name": "user_profile",
        "title": "用户主页",
        "category": "用户",
        "description": "输入用户 ID，获取对标账号个人主页信息",
        "args_template": {
            "user_id": "",
            "xsec_token": "",
        },
        "skip_license": False,
    },
    {
        "name": "my_account_feeds",
        "title": "我的账号",
        "category": "用户",
        "description": "打开当前登录账号主页，滚动加载我的笔记（图文与视频），支持按类型筛选",
        "args_template": {},
        "skip_license": False,
    },
]


def visible_tools() -> list[XhsToolDef]:
    return [t for t in XHS_TOOLS if not t.get("hidden_in_gui")]


def tools_by_category(nav_group: str = "analysis") -> dict[str, list[XhsToolDef]]:
    cats = CREATION_CATEGORIES if nav_group == "creation" else ANALYSIS_CATEGORIES
    grouped: dict[str, list[XhsToolDef]] = {c: [] for c in cats}
    for tool in visible_tools():
        cat = tool["category"]
        if cat in grouped:
            grouped[cat].append(tool)
    return grouped