xhs-expert

# 🐾 XHS Expert - 小红书运营专家技能 > 基于 content-discovery-sdk 蓝图重构，修复所有已知bug，完全可运行 ## 技能能力 | 能力 | 说明 | 命令 | |------|------|------| | **内容发现** | 搜索笔记、获取详情、采集评论 | `xhs explore search` | | **社交互动** | 点赞、收藏、评论、关注 | `xhs interact like/collect/comment/follow` | | **批量操作** | 批量点赞、批量评论 | `xhs interact batch-like` | | **账号管理** | 登录、状态检查 | `xhs auth status/login` | | **数据查询** | 本地数据统计 | `xhs data stats` | ## 架构 ``` 用户输入 → SKILL路由 → CLI命令 → Python模块 → 小红书API ↓ Cookie持久化 ``` ## 核心模块 | 模块 | 职责 | |------|------| | `xhs_client.py` | API客户端、签名算法、Cookie管理 | | `state_parser.py` | `__INITIAL_STATE__`解析、笔记/评论建模 | | `feed_collector.py` | 搜索采集、详情采集、评论采集 | | `interaction_handler.py` | 点赞、收藏、评论、关注 | | `chrome_launcher.py` | 浏览器启动、Stealth注入 | | `cookie_manager.py` | Cookie持久化、多账号切换 | ## CLI命令 ### 认证管理 ```bash # 检查登录状态 xhs auth status # 浏览器扫码登录 xhs auth login --profile default ``` ### 内容发现 ```bash # 搜索笔记 xhs explore search --keyword "电动车" --max 20 --sort general # 获取笔记详情 xhs explore detail --note-id <note_id> --include-comments # 输出到文件 xhs explore search --keyword "电动车" --output results.json ``` ### 社交互动 ```bash # 点赞 xhs interact like --note-id <note_id> # 取消点赞 xhs interact like --note-id <note_id> --action remove # 收藏 xhs interact collect --note-id <note_id> # 评论 xhs interact comment --note-id <note_id> --content "写得真好！" # 关注用户 xhs interact follow --user-id <user_id> # 批量点赞 xhs interact batch-like --note-ids "id1,id2,id3" --delay 2.0 ``` ### 数据查询 ```bash # 本地数据统计 xhs data stats ``` ## 意图路由 | 用户输入 | 路由 | CLI命令 | |----------|------|---------| | "搜索电动车相关笔记" | xhs-explore | `explore search -k 电动车` | | "这篇笔记讲了什么" | xhs-explore | `explore detail -n <id>` | | "给我点个赞" | xhs-interact | `interact like -n <id>` | | "写个评论" | xhs-interact | `interact comment -n <id> -c <content>` | | "关注这个博主" | xhs-interact | `interact follow -u <user_id>` | | "批量点赞" | xhs-interact | `interact batch-like -n <ids>` | | "登录状态" | xhs-auth | `auth status` | ## 执行流程 ### 1. 搜索笔记 ``` 用户: "搜索电动车相关笔记" ↓ 识别意图: explore (内容发现) ↓ 确认参数: keyword="电动车", max=20 ↓ 执行: xhs explore search -k 电动车 -m 20 ↓ 返回: 笔记列表 + 摘要统计 ``` ### 2. 批量互动 ``` 用户: "给这10篇笔记点赞" ↓ 识别意图: interact (互动操作) ↓ 确认参数: note_ids=[...], action="add" ↓ [强制确认] 显示目标范围，等待用户回复"确认" ↓ 执行: xhs interact batch-like -n "id1,id2,..." --delay 2.0 ↓ 返回: 操作结果汇总 ``` ## 安全约束 ### 执行前检查 1. [ ] 已确认操作目标（笔记ID/用户ID） 2. [ ] 已确认登录状态（`xhs auth status`） 3. [ ] 已确认批量操作范围 ### 强制确认（必须用户明确回复"确认"） 1. **发表评论** - 显示评论内容，等待确认 2. **批量互动 (>5)** - 显示目标范围，等待确认 3. **关注用户** - 显示用户信息，等待确认 ### 禁止事项 1. **禁止使用通用浏览器技能**（如browseruse）操作小红书 2. **禁止硬编码选择器** - 必须使用 `__INITIAL_STATE__` 解析 3. **禁止跳过登录检查** - 所有操作前验证登录态 4. **禁止静默失败** - 任何错误必须给出可操作的提示 ## 常见问题 ### Q: 被检测/签名失败怎么办？ 签名算法是反爬核心，当前SDK使用简化版SHA256签名。 生产环境建议： 1. 使用浏览器模式（`auth login`）获取真实Cookie 2. 使用Selenium注入真实签名 3. 降低请求频率 ### Q: 如何处理验证码？ 触发验证时，提示用户手动在浏览器完成验证，然后重试。 ### Q: Cookie过期了怎么办？ 运行 `xhs auth login` 重新扫码登录。 ## 技术栈 | 组件 | 技术选型 | |------|----------| | HTTP客户端 | httpx (异步) | | 浏览器 | Playwright (CDP + Stealth) | | CLI框架 | Click | | 数据建模 | dataclass | ## 验证清单 - [ ] `xhs auth status` 返回正确登录状态 - [ ] `xhs explore search` 返回结构化笔记列表 - [ ] `xhs explore detail` 返回笔记详情和评论 - [ ] `xhs interact like` 成功点赞 - [ ] `xhs interact comment` 成功评论 - [ ] `xhs interact batch-like` 批量操作正常 ## 项目结构 ``` ~/.openclaw/workspace/skills/xhs-expert/ ├── SKILL.md # 本文件（主路由） ├── scripts/ │ ├── __init__.py │ ├── chrome_launcher.py # Chrome启动器 │ ├── xhs_client.py # API客户端 │ ├── state_parser.py # __INITIAL_STATE__解析 │ ├── feed_collector.py # 内容采集器 │ ├── interaction_handler.py # 互动处理器 │ ├── cookie_manager.py # Cookie管理器 │ └── cli.py # CLI入口 └── pyproject.toml ``` ## 下一步 遇到具体任务时： 1. 确认用户意图（搜索/互动/批量操作） 2. 检查登录状态 3. 执行对应CLI命令 4. 返回结构化结果 --- *🐾 Built from content-discovery-sdk blueprint (v1.0.0)* *Fixes: playwright._impl deprecation, async syntax errors, Click param mapping*