"""统一 CLI 入口(Extension Bridge 版本)
通过浏览器扩展 Bridge 连接用户已打开的浏览器,无需 Chrome 调试端口。
先启动 bridge_server.py,并在浏览器中安装 XHS Bridge 扩展,再运行此 CLI。
输出: JSON(ensure_ascii=False)
退出码: 0=成功, 1=未登录, 2=错误
"""
from __future__ import annotations
import argparse
import contextlib
import json
import logging
import os
import signal
import subprocess
import sys
import tempfile
import time
from pathlib import Path
# Windows 控制台默认编码(如 cp1252)不支持中文,强制 UTF-8
if sys.stdout and hasattr(sys.stdout, "reconfigure"):
sys.stdout.reconfigure(encoding="utf-8")
if sys.stderr and hasattr(sys.stderr, "reconfigure"):
sys.stderr.reconfigure(encoding="utf-8")
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s %(levelname)s %(name)s: %(message)s",
)
logger = logging.getLogger("xhs-cli")
_BROWSER_STATE_FILE = Path(tempfile.gettempdir()) / (
f"xhs-bridge-managed-chrome-{getattr(os, 'getuid', lambda: 0)()}.json"
)
# ─── 输出工具 ────────────────────────────────────────────────────────────────
def _output(data: dict, exit_code: int = 0) -> None:
print(json.dumps(data, ensure_ascii=False, indent=2))
sys.exit(exit_code)
def _open_file_if_display(path: str) -> None:
"""有桌面时用系统默认程序打开文件。"""
import platform
import subprocess
try:
system = platform.system()
if system == "Windows":
os.startfile(path)
elif system == "Darwin":
subprocess.Popen(["open", path])
else:
subprocess.Popen(["xdg-open", path])
except Exception:
logger.debug("无法自动打开文件: %s", path)
# ─── Bridge 连接 ──────────────────────────────────────────────────────────────
class _DummyBrowser:
"""空 browser 对象,保持与旧代码的兼容性。"""
def close(self) -> None:
pass
def close_page(self, page) -> None:
pass
def _find_chrome_pid() -> int | None:
"""返回 Chrome 主进程 PID;找不到时返回 None。"""
if sys.platform == "darwin":
commands = [
["pgrep", "-f", "^/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"],
["pgrep", "-x", "Google Chrome"],
]
elif sys.platform == "win32":
try:
result = subprocess.run(
["tasklist", "/FI", "IMAGENAME eq chrome.exe", "/FO", "CSV", "/NH"],
capture_output=True,
check=False,
text=True,
)
except OSError:
return None
for line in result.stdout.splitlines():
fields = [field.strip('"') for field in line.split('","')]
if len(fields) > 1 and fields[0].lower() == "chrome.exe":
with contextlib.suppress(ValueError):
return int(fields[1])
return None
else:
commands = [["pgrep", "-o", "-f", "(^|/)(google-chrome|chromium)( |$)"]]
for command in commands:
try:
result = subprocess.run(command, capture_output=True, check=False, text=True)
except OSError:
continue
if result.returncode == 0:
with contextlib.suppress(ValueError):
return int(result.stdout.splitlines()[0].strip())
return None
def _is_pid_alive(pid: int) -> bool:
try:
os.kill(pid, 0)
except OSError:
return False
return True
def _read_browser_state() -> dict | None:
try:
state = json.loads(_BROWSER_STATE_FILE.read_text(encoding="utf-8"))
pid = int(state["pid"])
except (FileNotFoundError, KeyError, TypeError, ValueError, json.JSONDecodeError):
return None
if not _is_pid_alive(pid) or _find_chrome_pid() != pid:
with contextlib.suppress(OSError):
_BROWSER_STATE_FILE.unlink()
return None
return state
def _record_managed_chrome(pid: int) -> None:
state = {"pid": pid, "platform": sys.platform, "started_at": time.time()}
_BROWSER_STATE_FILE.write_text(
json.dumps(state, ensure_ascii=False),
encoding="utf-8",
)
def _quit_chrome(force: bool = False) -> dict:
"""优雅关闭 Chrome;默认只关闭由本技能启动的实例。"""
state = _read_browser_state()
if state is None and not force:
return {
"closed": False,
"reason": "Chrome 不是由本次自动化启动,已保留用户浏览器",
}
pid = int(state["pid"]) if state else _find_chrome_pid() or 0
if not pid:
return {"closed": False, "reason": "未发现运行中的 Chrome"}
try:
if sys.platform == "darwin":
subprocess.run(
["osascript", "-e", 'tell application "Google Chrome" to quit'],
check=False,
timeout=15,
)
elif sys.platform == "win32":
subprocess.run(["taskkill", "/PID", str(pid)], check=False, timeout=15)
else:
os.kill(pid, signal.SIGTERM)
except (OSError, subprocess.TimeoutExpired) as exc:
return {"closed": False, "reason": f"关闭 Chrome 失败: {exc}"}
deadline = time.monotonic() + 15
while time.monotonic() < deadline and _is_pid_alive(pid):
time.sleep(0.25)
closed = not _is_pid_alive(pid)
if closed:
with contextlib.suppress(OSError):
_BROWSER_STATE_FILE.unlink()
return {
"closed": closed,
"reason": "Chrome 已优雅退出" if closed else "Chrome 未在等待时间内退出",
}
def _ensure_bridge_ready(bridge_url: str) -> None:
"""确保 bridge server 在运行、浏览器扩展已连接。若未就绪则自动启动。"""
import subprocess
import time
from pathlib import Path
from xhs.bridge import BridgePage
from xhs.errors import CDPError
page = BridgePage(bridge_url)
# ── 1. 检查 bridge server ────────────────────────────────────────
if not page.is_server_running():
logger.info("Bridge server 未运行,正在启动...")
scripts_dir = Path(__file__).parent
# Bridge 是长期服务,不应随一次 CLI 调用所在的终端/进程组退出。
# 否则扩展每次都会失去 WebSocket 连接,用户只能手动刷新扩展。
kwargs: dict = {
"stdin": subprocess.DEVNULL,
"stdout": subprocess.DEVNULL,
"stderr": subprocess.DEVNULL,
}
if sys.platform == "win32":
kwargs["creationflags"] = (
subprocess.CREATE_NO_WINDOW | subprocess.CREATE_NEW_PROCESS_GROUP
)
else:
kwargs["start_new_session"] = True
subprocess.Popen(
[sys.executable, str(scripts_dir / "bridge_server.py")],
**kwargs,
)
for _ in range(10):
time.sleep(1)
if page.is_server_running():
logger.info("Bridge server 已启动")
break
else:
raise CDPError("小红书本地连接服务启动失败,任务尚未执行,请稍后重试。")
# ── 2. 检查扩展是否连接 ──────────────────────────────────────────
if page.is_extension_connected():
return
# 已打开的 Chrome 不需要被唤到前台。先给 Manifest V3 service worker
# 一小段时间自行恢复 WebSocket,避免每条命令都抢走用户焦点。
logger.info("等待浏览器扩展自动重连...")
deadline = time.monotonic() + 6
while time.monotonic() < deadline:
if page.is_extension_connected():
logger.info("浏览器扩展已自动重连")
return
time.sleep(1)
logger.info("浏览器扩展仍未连接,正在后台启动 Chrome...")
_open_chrome()
# 预留至少一个 Chrome alarm 周期,覆盖电脑重启或长时间闲置后的后台唤醒。
deadline = time.monotonic() + 35
while time.monotonic() < deadline:
if page.is_extension_connected():
logger.info("浏览器扩展已连接")
return
time.sleep(1)
server_status = page.get_server_status()
extension_info = server_status.get("extension") or {}
if server_status.get("extension_connected") and not extension_info.get("protocol_version"):
raise CDPError(
"Chrome 当前仍在运行旧版 XHS Bridge。请在扩展管理页完成一次版本更新,"
"之后的新任务会自动恢复连接。"
)
raise CDPError(
"小红书连接未恢复。请确认 Chrome 已打开且 XHS Bridge 扩展已启用;"
"任务尚未执行,可以在扩展中点击“重新连接”后重试。"
)
def _open_chrome() -> bool:
"""尝试在后台启动 Chrome,不抢占用户当前窗口。"""
existing_pid = _find_chrome_pid()
already_running = existing_pid is not None
candidates = [
r"C:\Program Files\Google\Chrome\Application\chrome.exe",
r"C:\Program Files (x86)\Google\Chrome\Application\chrome.exe",
os.path.expandvars(r"%LOCALAPPDATA%\Google\Chrome\Application\chrome.exe"),
]
for path in candidates:
if os.path.exists(path):
process = subprocess.Popen([path])
if not already_running:
_record_managed_chrome(process.pid)
return not already_running
# macOS 的 -g / -j 分别表示不切到前台、启动后隐藏。
# 原先的 `open -a` 会让每次自动化都抢走用户正在使用的窗口。
if sys.platform == "darwin":
try:
subprocess.Popen(["open", "-g", "-j", "-a", "Google Chrome"])
if already_running:
return False
for _ in range(20):
time.sleep(0.25)
pid = _find_chrome_pid()
if pid is not None:
_record_managed_chrome(pid)
return True
logger.warning("Chrome 已启动,但未能记录主进程;收尾时将只关闭自动化标签页")
return True
except FileNotFoundError:
pass
# Linux fallback
for cmd in [["google-chrome"], ["chromium-browser"]]:
try:
process = subprocess.Popen(cmd)
if not already_running:
_record_managed_chrome(process.pid)
return not already_running
except FileNotFoundError:
continue
logger.warning("找不到 Chrome,请手动打开浏览器")
return False
def _connect(args: argparse.Namespace):
"""返回 (browser, page),browser 为空对象,page 通过 Extension Bridge 操作浏览器。"""
from xhs.bridge import BridgePage
bridge_url = getattr(args, "bridge_url", "ws://localhost:9333")
_ensure_bridge_ready(bridge_url)
return _DummyBrowser(), BridgePage(bridge_url)
# _connect_saved_tab / _connect_existing 在 bridge 模式下与 _connect 等价
_connect_saved_tab = _connect
_connect_existing = _connect
def cmd_cleanup(args: argparse.Namespace) -> None:
"""清理自动化标签页,并关闭由本技能启动的 Chrome。"""
from xhs.bridge import BridgePage
bridge_url = getattr(args, "bridge_url", "ws://localhost:9333")
page = BridgePage(bridge_url)
tab_result: dict = {
"closed_tabs": 0,
"reason": "Bridge 或扩展未连接,跳过标签页清理",
}
if page.is_server_running() and page.is_extension_connected():
try:
tab_result = page.cleanup_managed_tabs()
except Exception as exc:
# 扩展可能尚未重新加载到支持 cleanup 的版本;Chrome 收尾仍应继续。
tab_result = {"closed_tabs": 0, "reason": f"标签页清理失败: {exc}"}
chrome_result = _quit_chrome(force=args.force_close_chrome)
_output(
{
"success": True,
"cleanup": {
"tabs": tab_result,
"chrome": chrome_result,
},
}
)
# ─── 子命令实现 ───────────────────────────────────────────────────────────────
def _qrcode_fallback(browser, page, args: argparse.Namespace) -> None:
"""频率限制时刷新页面返回二维码。"""
from xhs.login import fetch_qrcode, make_qrcode_url, save_qrcode_to_file
from xhs.urls import EXPLORE_URL
page.navigate(EXPLORE_URL)
page.wait_for_load()
png_bytes, _b64_orig, already = fetch_qrcode(page)
if already:
_output({"logged_in": True, "message": "已登录"})
return
qrcode_path = save_qrcode_to_file(png_bytes)
image_url, login_url = make_qrcode_url(png_bytes)
_open_file_if_display(qrcode_path)
result: dict = {
"logged_in": False,
"login_method": "qrcode",
"qrcode_path": qrcode_path,
"qrcode_image_url": image_url,
"message": "验证码发送受限,已切换为二维码登录,请扫码。扫码后运行 wait-login 等待登录结果。",
}
if login_url:
result["qr_login_url"] = login_url
_output(result, exit_code=1)
def cmd_check_login(args: argparse.Namespace) -> None:
"""检查登录状态,未登录时自动获取二维码。"""
from xhs.login import fetch_qrcode, make_qrcode_url, save_qrcode_to_file
browser, page = _connect(args)
try:
png_bytes, _b64_orig, already = fetch_qrcode(page)
if already:
_output({"logged_in": True}, exit_code=0)
return
qrcode_path = save_qrcode_to_file(png_bytes)
image_url, login_url = make_qrcode_url(png_bytes)
_open_file_if_display(qrcode_path)
result: dict = {
"logged_in": False,
"login_method": "qrcode",
"qrcode_path": qrcode_path,
"qrcode_image_url": image_url,
"hint": "未登录,二维码已自动生成。扫码后运行 wait-login 等待登录结果",
}
if login_url:
result["qr_login_url"] = login_url
_output(result, exit_code=1)
finally:
browser.close()
def cmd_login(args: argparse.Namespace) -> None:
"""登录(扫码,阻塞等待完成)。"""
from xhs.login import fetch_qrcode, make_qrcode_url, save_qrcode_to_file, wait_for_login
browser, page = _connect(args)
try:
png_bytes, _b64_orig, already = fetch_qrcode(page)
if already:
_output({"logged_in": True, "message": "已登录"})
return
qrcode_path = save_qrcode_to_file(png_bytes)
image_url, login_url = make_qrcode_url(png_bytes)
_open_file_if_display(qrcode_path)
result: dict = {"qrcode_path": qrcode_path, "qrcode_image_url": image_url}
if login_url:
result["qr_login_url"] = login_url
logger.info("二维码已生成,等待扫码...")
success = wait_for_login(page, timeout=120)
_output(
{"logged_in": success, "message": "登录成功" if success else "等待超时"},
exit_code=0 if success else 2,
)
finally:
browser.close()
def cmd_get_qrcode(args: argparse.Namespace) -> None:
"""获取登录二维码截图并立即返回(非阻塞)。"""
from xhs.login import fetch_qrcode, make_qrcode_url, save_qrcode_to_file
browser, page = _connect(args)
try:
png_bytes, _b64_orig, already = fetch_qrcode(page)
if already:
browser.close_page(page)
browser.close()
_output({"logged_in": True, "message": "已登录"})
return
qrcode_path = save_qrcode_to_file(png_bytes)
image_url, login_url = make_qrcode_url(png_bytes)
_open_file_if_display(qrcode_path)
browser.close()
result: dict = {
"qrcode_path": qrcode_path,
"qrcode_image_url": image_url,
"message": "二维码已生成,请扫码登录。扫码后运行 wait-login 等待登录结果。",
}
if login_url:
result["qr_login_url"] = login_url
_output(result)
finally:
pass
def cmd_wait_login(args: argparse.Namespace) -> None:
"""等待扫码登录完成(配合 get-qrcode 使用)。"""
from xhs.login import wait_for_login
browser, page = _connect_saved_tab(args)
try:
success = wait_for_login(page, timeout=args.timeout)
_output(
{
"logged_in": success,
"message": "登录成功" if success else "等待超时,请重新运行 get-qrcode 获取新二维码",
},
exit_code=0 if success else 2,
)
finally:
browser.close()
def cmd_phone_login(args: argparse.Namespace) -> None:
"""手机号+验证码登录(交互式)。"""
from xhs.errors import RateLimitError
from xhs.login import send_phone_code, submit_phone_code
browser, page = _connect(args)
try:
sent = send_phone_code(page, args.phone)
if not sent:
_output({"logged_in": True, "message": "已登录,无需重新登录"})
return
code = args.code
if not code:
code = input("请输入收到的短信验证码: ").strip()
success = submit_phone_code(page, code)
_output(
{"logged_in": success, "message": "登录成功" if success else "验证码错误或超时"},
exit_code=0 if success else 2,
)
except RateLimitError:
_qrcode_fallback(browser, page, args)
finally:
browser.close()
def cmd_send_code(args: argparse.Namespace) -> None:
"""分步登录第一步:发送手机验证码。"""
from xhs.errors import RateLimitError
from xhs.login import send_phone_code
browser, page = _connect(args)
try:
sent = send_phone_code(page, args.phone)
if not sent:
_output({"logged_in": True, "message": "已登录,无需重新登录"})
return
_output({
"status": "code_sent",
"message": (
f"验证码已发送至 {args.phone[:3]}****{args.phone[-4:]},"
"请运行 verify-code --code <验证码>"
),
})
except RateLimitError:
_qrcode_fallback(browser, page, args)
finally:
browser.close()
def cmd_verify_code(args: argparse.Namespace) -> None:
"""分步登录第二步:填写验证码并提交。"""
from xhs.login import submit_phone_code
browser, page = _connect_saved_tab(args)
try:
success = submit_phone_code(page, args.code)
_output(
{"logged_in": success, "message": "登录成功" if success else "验证码错误或超时"},
exit_code=0 if success else 2,
)
finally:
browser.close()
def cmd_delete_cookies(args: argparse.Namespace) -> None:
"""退出登录(页面 UI 点击退出)。"""
from xhs.login import logout
browser, page = _connect(args)
try:
logged_out = logout(page)
msg = "已退出登录" if logged_out else "未登录"
_output({"success": True, "message": msg})
finally:
browser.close()
def cmd_list_feeds(args: argparse.Namespace) -> None:
"""获取首页 Feed 列表。"""
from xhs.feeds import list_feeds
browser, page = _connect(args)
try:
feeds = list_feeds(page)
_output({"feeds": [f.to_dict() for f in feeds], "count": len(feeds)})
finally:
browser.close()
def cmd_search_feeds(args: argparse.Namespace) -> None:
"""搜索 Feeds。"""
from xhs.search import search_feeds
from xhs.types import FilterOption
filter_opt = FilterOption(
sort_by=args.sort_by or "",
note_type=args.note_type or "",
publish_time=args.publish_time or "",
search_scope=args.search_scope or "",
location=args.location or "",
)
browser, page = _connect(args)
try:
feeds = search_feeds(page, args.keyword, filter_opt)
_output({"feeds": [f.to_dict() for f in feeds], "count": len(feeds)})
finally:
browser.close()
def cmd_browse_local(args: argparse.Namespace) -> None:
"""按小红书当前会话自动定位浏览本地公开账号。"""
from xhs.local_discovery import browse_local_accounts
browser, page = _connect(args)
try:
_output(
browse_local_accounts(
page,
args.keyword,
scope=args.scope,
limit=args.limit,
sort_by=args.sort_by,
)
)
finally:
browser.close()
def cmd_get_feed_detail(args: argparse.Namespace) -> None:
"""获取 Feed 详情。"""
if args.prepare_video and not args.confirm_video_understanding:
_output(
{
"success": False,
"confirmationRequired": True,
"warning": "完整视频理解耗时较长,并会消耗较多模型额度。",
"question": "是否需要继续理解这个视频?",
"nextStep": "用户确认后,重新运行并添加 --confirm-video-understanding。",
},
exit_code=2,
)
from image_downloader import ImageDownloader
from xhs.feed_detail import get_feed_detail
from xhs.types import CommentLoadConfig
config = CommentLoadConfig(
click_more_replies=args.click_more_replies or args.load_all_replies,
load_all_replies=args.load_all_replies,
max_replies_threshold=args.max_replies_threshold,
max_comment_items=args.max_comment_items,
scroll_speed=args.scroll_speed,
)
browser, page = _connect(args)
try:
detail = get_feed_detail(
page,
args.feed_id,
args.xsec_token,
load_all_comments=args.load_all_comments,
config=config,
keyword=getattr(args, "keyword", "篮球"),
)
result = detail.to_dict()
if args.download_images:
image_dir = os.path.abspath(
args.image_dir or os.path.join(os.getcwd(), "xhs-images", args.feed_id)
)
downloader = ImageDownloader(image_dir)
images = result.get("note", {}).get("imageList", [])
selected = images[: args.max_images] if args.max_images > 0 else images
failures: list[dict] = []
downloaded = 0
for index, image in enumerate(selected, start=1):
image_url = image.get("urlDefault", "")
if not image_url:
failures.append({"index": index, "error": "图片 URL 为空"})
continue
try:
image["localPath"] = os.path.abspath(downloader.download_image(image_url))
downloaded += 1
except Exception as download_error:
failures.append({"index": index, "error": str(download_error)})
result["imageDownloadStatus"] = {
"requested": len(selected),
"downloaded": downloaded,
"failed": len(failures),
"directory": image_dir,
"failures": failures,
}
if args.prepare_video:
from video_processor import VideoProcessor
video_dir = os.path.abspath(
args.video_dir or os.path.join(os.getcwd(), "xhs-videos", args.feed_id)
)
processor = VideoProcessor(video_dir)
video_data = result.get("note", {}).get("video", {})
result["videoPreparationStatus"] = processor.prepare(
video_data,
max_frames=args.max_video_frames,
)
_output(result)
except Exception as e:
# 附带 404 诊断事件,帮助定位根因
diagnostics: list = []
try:
diagnostics = page.get_404_diagnostics() or []
except Exception:
pass
err_data: dict = {"success": False, "error": str(e)}
if diagnostics:
latest = diagnostics[-1]
err_data["diagnosis"] = {
"root_cause": latest.get("diagnosis", {}).get("root_cause"),
"cause_category": latest.get("diagnosis", {}).get("cause_category"),
"detail": latest.get("diagnosis", {}).get("detail"),
"how_xhs_decides": latest.get("diagnosis", {}).get("how_xhs_decides"),
"url": latest.get("url"),
"final_url": latest.get("final_url"),
}
_output(err_data, exit_code=2)
finally:
browser.close()
def cmd_user_profile(args: argparse.Namespace) -> None:
"""获取用户主页。"""
from xhs.user_profile import get_user_profile
browser, page = _connect(args)
try:
profile = get_user_profile(
page,
args.user_id,
args.xsec_token,
load_all_notes=args.load_all_notes,
max_note_items=args.max_note_items,
scroll_speed=args.scroll_speed,
max_scroll_rounds=args.max_scroll_rounds,
stable_rounds=args.stable_rounds,
)
_output(profile.to_dict())
finally:
browser.close()
def cmd_post_comment(args: argparse.Namespace) -> None:
"""发表评论。"""
from xhs.comment import post_comment
browser, page = _connect(args)
try:
post_comment(page, args.feed_id, args.xsec_token, args.content)
_output({"success": True, "message": "评论发送成功"})
finally:
browser.close()
def cmd_reply_comment(args: argparse.Namespace) -> None:
"""回复评论。"""
from xhs.comment import reply_comment
browser, page = _connect(args)
try:
reply_comment(
page,
args.feed_id,
args.xsec_token,
args.content,
comment_id=args.comment_id or "",
user_id=args.user_id or "",
)
_output({"success": True, "message": "回复成功"})
finally:
browser.close()
def cmd_like_feed(args: argparse.Namespace) -> None:
"""点赞/取消点赞。"""
from xhs.like_favorite import like_feed, unlike_feed
browser, page = _connect(args)
try:
if args.unlike:
result = unlike_feed(page, args.feed_id, args.xsec_token)
else:
result = like_feed(page, args.feed_id, args.xsec_token)
_output(result.to_dict())
finally:
browser.close()
def cmd_favorite_feed(args: argparse.Namespace) -> None:
"""收藏/取消收藏。"""
from xhs.like_favorite import favorite_feed, unfavorite_feed
browser, page = _connect(args)
try:
if args.unfavorite:
result = unfavorite_feed(page, args.feed_id, args.xsec_token)
else:
result = favorite_feed(page, args.feed_id, args.xsec_token)
_output(result.to_dict())
finally:
browser.close()
def cmd_publish(args: argparse.Namespace) -> None:
"""发布图文内容。"""
from image_downloader import process_images
from xhs.publish import publish_image_content
from xhs.types import PublishImageContent
with open(args.title_file, encoding="utf-8") as f:
title = f.read().strip()
with open(args.content_file, encoding="utf-8") as f:
content = f.read().strip()
image_paths = process_images(args.images) if args.images else []
if not image_paths:
_output({"success": False, "error": "没有有效的图片"}, exit_code=2)
browser, page = _connect(args)
try:
publish_image_content(
page,
PublishImageContent(
title=title,
content=content,
tags=args.tags or [],
image_paths=image_paths,
schedule_time=args.schedule_at,
is_original=args.original,
visibility=args.visibility or "",
),
)
_output({"success": True, "title": title, "images": len(image_paths), "status": "发布完成"})
finally:
browser.close()
def cmd_fill_publish(args: argparse.Namespace) -> None:
"""只填写图文表单,不发布。"""
from image_downloader import process_images
from xhs.publish import fill_publish_form
from xhs.types import PublishImageContent
with open(args.title_file, encoding="utf-8") as f:
title = f.read().strip()
with open(args.content_file, encoding="utf-8") as f:
content = f.read().strip()
image_paths = process_images(args.images) if args.images else []
if not image_paths:
_output({"success": False, "error": "没有有效的图片"}, exit_code=2)
browser, page = _connect(args)
try:
fill_publish_form(
page,
PublishImageContent(
title=title,
content=content,
tags=args.tags or [],
image_paths=image_paths,
schedule_time=args.schedule_at,
is_original=args.original,
visibility=args.visibility or "",
),
)
_output({"success": True, "title": title, "images": len(image_paths), "status": "表单已填写,等待确认发布"})
finally:
browser.close()
def cmd_fill_publish_video(args: argparse.Namespace) -> None:
"""只填写视频表单,不发布。"""
from xhs.publish_video import fill_publish_video_form
from xhs.types import PublishVideoContent
with open(args.title_file, encoding="utf-8") as f:
title = f.read().strip()
with open(args.content_file, encoding="utf-8") as f:
content = f.read().strip()
browser, page = _connect(args)
try:
fill_publish_video_form(
page,
PublishVideoContent(
title=title,
content=content,
tags=args.tags or [],
video_path=args.video,
schedule_time=args.schedule_at,
visibility=args.visibility or "",
),
)
_output({"success": True, "title": title, "video": args.video, "status": "视频表单已填写,等待确认发布"})
finally:
browser.close()
def cmd_click_publish(args: argparse.Namespace) -> None:
"""点击发布按钮(在用户确认后调用)。"""
from xhs.publish import click_publish_button
browser, page = _connect_existing(args)
try:
click_publish_button(page)
_output({"success": True, "status": "发布完成"})
finally:
browser.close()
def cmd_save_draft(args: argparse.Namespace) -> None:
"""保存为草稿。"""
from xhs.publish import save_as_draft
browser, page = _connect_existing(args)
try:
save_as_draft(page)
_output({"success": True, "status": "内容已保存到草稿箱"})
finally:
browser.close()
def cmd_long_article(args: argparse.Namespace) -> None:
"""长文模式:填写内容 + 一键排版,返回模板列表。"""
from xhs.publish_long_article import publish_long_article
with open(args.title_file, encoding="utf-8") as f:
title = f.read().strip()
with open(args.content_file, encoding="utf-8") as f:
content = f.read().strip()
browser, page = _connect(args)
try:
template_names = publish_long_article(
page,
title=title,
content=content,
image_paths=args.images,
)
_output({"success": True, "templates": template_names, "status": "长文已填写,请选择模板"})
finally:
browser.close()
def cmd_select_template(args: argparse.Namespace) -> None:
"""选择排版模板。"""
from xhs.publish_long_article import select_template
browser, page = _connect_existing(args)
try:
selected = select_template(page, args.name)
if selected:
_output({"success": True, "template": args.name, "status": "模板已选择"})
else:
_output({"success": False, "error": f"未找到模板: {args.name}"}, exit_code=2)
finally:
browser.close()
def cmd_next_step(args: argparse.Namespace) -> None:
"""点击下一步 + 填写发布页描述。"""
from xhs.publish_long_article import click_next_and_fill_description
with open(args.content_file, encoding="utf-8") as f:
description = f.read().strip()
browser, page = _connect_existing(args)
try:
click_next_and_fill_description(page, description)
_output({"success": True, "status": "已进入发布页,等待确认发布"})
finally:
browser.close()
def cmd_diagnose_404(args: argparse.Namespace) -> None:
"""获取拦截器捕获的 404 诊断事件,打印根因分析报告。"""
browser, page = _connect(args)
try:
if args.clear:
page.clear_404_diagnostics()
_output({"success": True, "message": "诊断记录已清空"})
return
events = page.get_404_diagnostics()
if not events:
_output({"success": True, "events": [], "message": "暂无拦截记录,请在小红书页面进行操作后重试"})
return
# 控制台可读报告(写到 stderr)
logger.info("═" * 60)
logger.info("404 诊断报告 — 共 %d 条拦截记录", len(events))
logger.info("═" * 60)
for i, ev in enumerate(events, 1):
diag = ev.get("diagnosis", {})
logger.info(
"[%d] %s %s → HTTP %s",
i, ev.get("method", "?"), ev.get("url", "?")[:80], ev.get("status", "?"),
)
logger.info(" 根因: %s", diag.get("root_cause", "未知"))
logger.info(" 详情: %s", diag.get("detail", "")[:120])
logger.info(" 置信: %s | 类别: %s", diag.get("confidence", "?"), diag.get("cause_category", "?"))
logger.info(" 时间: %s | 页面: %s", ev.get("timestamp", "?"), ev.get("pageUrl", "?")[:60])
cookies = ev.get("cookies", {})
req = ev.get("request", {})
logger.info(
" 凭证: web_session=%s a1=%s xs=%s xsec_token=%s",
cookies.get("has_web_session"), cookies.get("has_a1"),
req.get("has_xs"), bool(req.get("xsec_token")),
)
logger.info("─" * 60)
_output({"success": True, "events": events})
finally:
browser.close()
def cmd_check_risk(args: argparse.Namespace) -> None:
"""分析小红书风控状态:检测自动化特征与 API 拦截情况。"""
import json as _json
browser, page = _connect(args)
try:
probe_urls = args.probe_urls or []
report = page.analyze_risk_control(probe_urls=probe_urls)
if not report:
_output({"success": False, "error": "扫描返回空结果"}, exit_code=2)
return
risk_level = report.get("risk_level", "unknown")
issues = report.get("issues", [])
# 控制台可读摘要(写到 stderr,不影响 JSON stdout)
logger.info("风控扫描完成 | 等级: %s | 问题数: %d", risk_level.upper(), len(issues))
for issue in issues:
logger.info(" [%s] %s", issue.get("level", "?").upper(), issue.get("msg", ""))
_output({"success": True, "report": report})
finally:
browser.close()
def cmd_get_netlog(args: argparse.Namespace) -> None:
"""获取 NetLog 原始 entries(最多 500 条)。"""
browser, page = _connect(args)
try:
if not page.get_netlog_enabled():
print(json.dumps({
"error": "netlogger 未启用",
"hint": "请打开扩展 popup,标题 XHS Bridge 连点 5 次激活 NetLog 后重试",
}, ensure_ascii=False, indent=2))
sys.exit(2)
entries = page.get_netlog()
if args.limit:
entries = entries[-args.limit:]
print(json.dumps({
"total": len(entries),
"entries": entries,
}, ensure_ascii=False, indent=2))
finally:
browser.close()
def cmd_risk_report(args: argparse.Namespace) -> None:
"""基于 NetLog 数据生成风控分析报告。"""
from xhs.risk_analyzer import analyze
browser, page = _connect(args)
try:
if not page.get_netlog_enabled():
print(json.dumps({
"error": "netlogger 未启用",
"hint": "请打开扩展 popup,标题 XHS Bridge 连点 5 次激活 NetLog 后重试",
}, ensure_ascii=False, indent=2))
sys.exit(2)
entries = page.get_netlog()
report = analyze(entries)
print(json.dumps(report, ensure_ascii=False, indent=2))
finally:
browser.close()
def cmd_publish_video(args: argparse.Namespace) -> None:
"""发布视频内容。"""
from xhs.publish_video import publish_video_content
from xhs.types import PublishVideoContent
with open(args.title_file, encoding="utf-8") as f:
title = f.read().strip()
with open(args.content_file, encoding="utf-8") as f:
content = f.read().strip()
browser, page = _connect(args)
try:
publish_video_content(
page,
PublishVideoContent(
title=title,
content=content,
tags=args.tags or [],
video_path=args.video,
schedule_time=args.schedule_at,
visibility=args.visibility or "",
),
)
_output({"success": True, "title": title, "video": args.video, "status": "发布完成"})
finally:
browser.close()
# ─── 参数解析 ──────────────────────────────────────────────────────────────────
def build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(
prog="xhs-cli",
description="小红书自动化 CLI(Extension Bridge 版)",
)
parser.add_argument(
"--bridge-url",
default="ws://localhost:9333",
help="Bridge server WebSocket 地址 (default: ws://localhost:9333)",
)
subparsers = parser.add_subparsers(dest="command", required=True)
# cleanup
sub = subparsers.add_parser("cleanup", help="任务收尾:清理自动化标签页并退出托管 Chrome")
sub.add_argument(
"--force-close-chrome",
action="store_true",
help="即使 Chrome 不是由本技能启动也退出(会关闭用户的全部 Chrome 窗口)",
)
sub.set_defaults(func=cmd_cleanup)
# check-login
sub = subparsers.add_parser("check-login", help="检查登录状态")
sub.set_defaults(func=cmd_check_login)
# login
sub = subparsers.add_parser("login", help="登录(扫码,阻塞等待)")
sub.set_defaults(func=cmd_login)
# get-qrcode
sub = subparsers.add_parser("get-qrcode", help="获取登录二维码截图(非阻塞)")
sub.set_defaults(func=cmd_get_qrcode)
# wait-login
sub = subparsers.add_parser("wait-login", help="等待扫码登录完成(配合 get-qrcode)")
sub.add_argument("--timeout", type=float, default=120.0, help="等待超时秒数 (default: 120)")
sub.set_defaults(func=cmd_wait_login)
# phone-login
sub = subparsers.add_parser("phone-login", help="手机号+验证码登录(交互式)")
sub.add_argument("--phone", required=True, help="手机号")
sub.add_argument("--code", default="", help="短信验证码(省略则交互式输入)")
sub.set_defaults(func=cmd_phone_login)
# send-code
sub = subparsers.add_parser("send-code", help="分步登录第一步:发送手机验证码")
sub.add_argument("--phone", required=True, help="手机号")
sub.set_defaults(func=cmd_send_code)
# verify-code
sub = subparsers.add_parser("verify-code", help="分步登录第二步:填写验证码")
sub.add_argument("--code", required=True, help="短信验证码")
sub.set_defaults(func=cmd_verify_code)
# delete-cookies
sub = subparsers.add_parser("delete-cookies", help="退出登录")
sub.set_defaults(func=cmd_delete_cookies)
# list-feeds
sub = subparsers.add_parser("list-feeds", help="获取首页 Feed 列表")
sub.set_defaults(func=cmd_list_feeds)
# search-feeds
sub = subparsers.add_parser("search-feeds", help="搜索 Feeds")
sub.add_argument("--keyword", required=True, help="搜索关键词")
sub.add_argument("--sort-by", help="排序: 综合|最新|最多点赞|最多评论|最多收藏")
sub.add_argument("--note-type", help="类型: 不限|视频|图文")
sub.add_argument("--publish-time", help="时间: 不限|一天内|一周内|半年内")
sub.add_argument("--search-scope", help="范围: 不限|已看过|未看过|已关注")
sub.add_argument("--location", help="位置: 不限|同城|附近")
sub.set_defaults(func=cmd_search_feeds)
# browse-local
sub = subparsers.add_parser(
"browse-local", help="按当前小红书会话自动定位浏览本地公开账号"
)
sub.add_argument("--keyword", required=True, help="搜索关键词")
sub.add_argument("--scope", choices=["同城", "附近"], default="同城", help="本地范围 (default: 同城)")
sub.add_argument("--limit", type=int, default=30, help="最多返回的去重账号数,1-100 (default: 30)")
sub.add_argument("--sort-by", default="综合", help="排序: 综合|最新|最多点赞|最多评论|最多收藏")
sub.set_defaults(func=cmd_browse_local)
# get-feed-detail
sub = subparsers.add_parser("get-feed-detail", help="获取 Feed 详情")
sub.add_argument("--feed-id", required=True, help="Feed ID")
sub.add_argument("--xsec-token", required=True, help="xsec_token")
sub.add_argument("--load-all-comments", action="store_true", help="加载全部评论")
sub.add_argument("--click-more-replies", action="store_true", help="展开更多回复")
sub.add_argument(
"--load-all-replies",
action="store_true",
help="展开并核验已加载一级评论下的全部子回复(可与 --max-comment-items 配合)",
)
sub.add_argument("--max-replies-threshold", type=int, default=10)
sub.add_argument("--max-comment-items", type=int, default=0)
sub.add_argument("--scroll-speed", default="normal", help="slow|normal|fast")
sub.add_argument("--keyword", default="篮球", help="风控重试时的搜索关键词")
sub.add_argument(
"--download-images",
action="store_true",
help="下载笔记原图,并在 imageList 中返回 localPath,供视觉读取",
)
sub.add_argument(
"--image-dir",
help="图片保存目录(建议使用绝对路径;默认 ./xhs-images/<feed-id>)",
)
sub.add_argument(
"--max-images",
type=int,
default=0,
help="最多下载图片数;0 表示全部",
)
sub.add_argument(
"--prepare-video",
action="store_true",
help="下载视频并提取关键帧、音轨和元数据,供视频理解",
)
sub.add_argument(
"--confirm-video-understanding",
action="store_true",
help="确认已向用户说明视频理解耗时较长且消耗较多模型额度",
)
sub.add_argument(
"--video-dir",
help="视频素材保存目录(建议使用绝对路径;默认 ./xhs-videos/<feed-id>)",
)
sub.add_argument(
"--max-video-frames",
type=int,
default=18,
help="最多提取的关键帧数量;默认 18",
)
sub.set_defaults(func=cmd_get_feed_detail)
# user-profile
sub = subparsers.add_parser("user-profile", help="获取用户主页")
sub.add_argument("--user-id", required=True)
sub.add_argument("--xsec-token", required=True)
sub.add_argument("--load-all-notes", action="store_true", help="滚动加载主页全部帖子")
sub.add_argument("--max-note-items", type=int, default=0, help="最多加载帖子数;0 表示全部")
sub.add_argument("--scroll-speed", default="normal", help="slow|normal|fast")
sub.add_argument("--max-scroll-rounds", type=int, default=120, help="最大滚动轮数")
sub.add_argument(
"--stable-rounds",
type=int,
default=4,
help="连续多少轮位于底部且无新增后判定加载完成",
)
sub.set_defaults(func=cmd_user_profile)
# post-comment
sub = subparsers.add_parser("post-comment", help="发表评论")
sub.add_argument("--feed-id", required=True)
sub.add_argument("--xsec-token", required=True)
sub.add_argument("--content", required=True)
sub.set_defaults(func=cmd_post_comment)
# reply-comment
sub = subparsers.add_parser("reply-comment", help="回复评论")
sub.add_argument("--feed-id", required=True)
sub.add_argument("--xsec-token", required=True)
sub.add_argument("--content", required=True)
sub.add_argument("--comment-id")
sub.add_argument("--user-id")
sub.set_defaults(func=cmd_reply_comment)
# like-feed
sub = subparsers.add_parser("like-feed", help="点赞")
sub.add_argument("--feed-id", required=True)
sub.add_argument("--xsec-token", required=True)
sub.add_argument("--unlike", action="store_true")
sub.set_defaults(func=cmd_like_feed)
# favorite-feed
sub = subparsers.add_parser("favorite-feed", help="收藏")
sub.add_argument("--feed-id", required=True)
sub.add_argument("--xsec-token", required=True)
sub.add_argument("--unfavorite", action="store_true")
sub.set_defaults(func=cmd_favorite_feed)
# publish
sub = subparsers.add_parser("publish", help="发布图文")
sub.add_argument("--title-file", required=True)
sub.add_argument("--content-file", required=True)
sub.add_argument("--images", nargs="+", required=True)
sub.add_argument("--tags", nargs="*")
sub.add_argument("--schedule-at")
sub.add_argument("--original", action="store_true")
sub.add_argument("--visibility")
sub.set_defaults(func=cmd_publish)
# publish-video
sub = subparsers.add_parser("publish-video", help="发布视频")
sub.add_argument("--title-file", required=True)
sub.add_argument("--content-file", required=True)
sub.add_argument("--video", required=True)
sub.add_argument("--tags", nargs="*")
sub.add_argument("--schedule-at")
sub.add_argument("--visibility")
sub.set_defaults(func=cmd_publish_video)
# fill-publish
sub = subparsers.add_parser("fill-publish", help="填写图文表单(不发布)")
sub.add_argument("--title-file", required=True)
sub.add_argument("--content-file", required=True)
sub.add_argument("--images", nargs="+", required=True)
sub.add_argument("--tags", nargs="*")
sub.add_argument("--schedule-at")
sub.add_argument("--original", action="store_true")
sub.add_argument("--visibility")
sub.set_defaults(func=cmd_fill_publish)
# fill-publish-video
sub = subparsers.add_parser("fill-publish-video", help="填写视频表单(不发布)")
sub.add_argument("--title-file", required=True)
sub.add_argument("--content-file", required=True)
sub.add_argument("--video", required=True)
sub.add_argument("--tags", nargs="*")
sub.add_argument("--schedule-at")
sub.add_argument("--visibility")
sub.set_defaults(func=cmd_fill_publish_video)
# click-publish
sub = subparsers.add_parser("click-publish", help="点击发布按钮")
sub.set_defaults(func=cmd_click_publish)
# save-draft
sub = subparsers.add_parser("save-draft", help="保存为草稿")
sub.set_defaults(func=cmd_save_draft)
# long-article
sub = subparsers.add_parser("long-article", help="长文模式:填写 + 一键排版")
sub.add_argument("--title-file", required=True)
sub.add_argument("--content-file", required=True)
sub.add_argument("--images", nargs="*")
sub.set_defaults(func=cmd_long_article)
# select-template
sub = subparsers.add_parser("select-template", help="选择排版模板")
sub.add_argument("--name", required=True)
sub.set_defaults(func=cmd_select_template)
# next-step
sub = subparsers.add_parser("next-step", help="点击下一步 + 填写描述")
sub.add_argument("--content-file", required=True)
sub.set_defaults(func=cmd_next_step)
# diagnose-404
sub = subparsers.add_parser("diagnose-404", help="获取拦截器捕获的 404 根因诊断报告")
sub.add_argument("--clear", action="store_true", help="清空已有诊断记录")
sub.set_defaults(func=cmd_diagnose_404)
# check-risk
sub = subparsers.add_parser("check-risk", help="分析小红书风控状态(自动化指纹 + API 探测)")
sub.add_argument(
"--probe-urls",
nargs="*",
dest="probe_urls",
default=[],
help="额外探测的 API URL 列表",
)
sub.set_defaults(func=cmd_check_risk)
# get-netlog
sub = subparsers.add_parser("get-netlog", help="获取 NetLog 原始 entries(需先在 popup 激活)")
sub.add_argument("--limit", type=int, default=None, help="只取最近 N 条")
sub.set_defaults(func=cmd_get_netlog)
# risk-report
sub = subparsers.add_parser("risk-report", help="基于 NetLog 生成风控分析报告")
sub.set_defaults(func=cmd_risk_report)
return parser
def main() -> None:
parser = build_parser()
args = parser.parse_args()
try:
args.func(args)
except Exception as e:
logger.error("执行失败: %s", e, exc_info=True)
_output({"success": False, "error": str(e)}, exit_code=2)
if __name__ == "__main__":
main()