# 小红书工作流技能说明 / XHS Workflow Skill Guide ## 中文说明 ### 参考库 * 本技能由 `Spider_XHS` 重构而来。 * 参考仓库：`cv-cat/Spider_XHS` * 参考地址：重构原则： 1. 去除对原仓 `apis/`、`xhs_utils/` 的运行时依赖。 2. 将签名 JS 与依赖打包到技能目录。 3. 提供统一 CLI 与分场景脚本，降低调用复杂度。 ### 安装在新机器上首次运行： skills/xhs-search-workflow/scripts/setup_env.sh 该命令会创建 `skills/xhs-search-workflow/.venv` 并安装 Python 依赖。 ### 鉴权输入 * `--cookie "..."` * 或 `--env-file /path/to/.env`（其中 `COOKIES="..."`） * 如宿主机代理变量导致失败，添加 `--no-env-proxy` ### 首次使用：如何获取 Cookie 1. 在浏览器登录小红书网页端（确保是已登录状态）。 2. 打开开发者工具 `Network`，筛选 `Fetch/XHR`，刷新页面后任选一条业务请求。 3. 优先选择 `edith.xiaohongshu.com` 的请求并复制 `Request Headers` 里的完整 `cookie` 字段。 4. 其他域名请求也可用，但需满足： * 请求头里包含完整 Cookie。 * 至少有 `a1`、`web_session`、`gid`。 5. 将 Cookie 写入 `.env`： COOKIES="完整cookie字符串" 6. 首次验证建议先运行： skills/xhs-search-workflow/.venv/bin/python \ skills/xhs-search-workflow/scripts/xhs_full_cli.py \ --env-file .env --no-env-proxy homefeed-channels 7. 若返回“登录已过期”或“无登录信息”，重新登录网页并重新抓取 Cookie。安全建议： * 不要在聊天、截图、Git 仓库中泄露 Cookie。 * 将 `.env` 加入 `.gitignore`。 ### 脚本清单 * `scripts/search_notes.py`：笔记搜索（支持筛选） * `scripts/fetch_note_texts.py`：提取标题/正文/图片链接，可选下载图片 * `scripts/xhs_full_cli.py`：统一入口（用户/评论/消息/首页/创作者/无水印） * `scripts/export_notes.py`：导出 Excel 与媒体文件 ### 常用命令 1. 搜索笔记 skills/xhs-search-workflow/.venv/bin/python \ skills/xhs-search-workflow/scripts/search_notes.py "汇丰银行" \ --num 10 --sort 0 --note-type 0 --no-env-proxy --json 2. 提取笔记正文与图片链接 skills/xhs-search-workflow/.venv/bin/python \ skills/xhs-search-workflow/scripts/fetch_note_texts.py \ --url-file note_urls.txt --no-env-proxy \ --timeout 30 --retries 2 --min-interval 4 --max-interval 7 \ --out note_content.json 3. 提取同时下载图片 skills/xhs-search-workflow/.venv/bin/python \ skills/xhs-search-workflow/scripts/fetch_note_texts.py \ --url-file note_urls.txt --no-env-proxy \ --download-images --image-dir xhs_images \ --timeout 30 --retries 2 --min-interval 4 --max-interval 7 \ --out note_content.json 4. 统一 CLI 示例（搜索用户） skills/xhs-search-workflow/.venv/bin/python \ skills/xhs-search-workflow/scripts/xhs_full_cli.py \ --env-file .env --no-env-proxy search-users --query "汇丰银行" --num 10 5. 导出 Excel/媒体 skills/xhs-search-workflow/.venv/bin/python \ skills/xhs-search-workflow/scripts/export_notes.py \ --query "汇丰银行" --num 10 --save all \ --excel xhs_notes.xlsx --media-dir xhs_media --no-env-proxy ### `xhs_full_cli.py` 子命令 * `user-info --user-id ` * `user-self-info` * `user-self-info2` * `user-posts --user-url ` * `user-likes --user-url ` * `user-collects --user-url ` * `note-info --url ` * `note-comments --url ` * `search-keyword --word ` * `search-users --query --num ` * `messages-unread` * `messages-mentions` * `messages-likes` * `messages-connections` * `homefeed-channels` * `homefeed-recommend --category --num ` * `creator-posted` * `no-water-video --note-id ` * `no-water-img --img-url ` ### 功能范围与边界 * 覆盖范围：搜索、详情、评论、用户、消息、首页推荐、创作者作品、无水印链接转换、导出。 * 当前边界：以 Cookie 鉴权为主，不内置交互式登录流程。 * 设计优点：脚本职责清晰、统一入口完整、离线资源齐全、迁移成本低。 ### 离线与可移植设计 * 签名 JS 打包在 `assets/js/`。 * 离线 `crypto-js` 位于 `assets/js/vendor/crypto-js.js`。 * 运行时不依赖原仓 `Spider_XHS` 的 `apis/` 或 `xhs_utils/`。 ### 校验每次改动后执行： skills/xhs-search-workflow/.venv/bin/python \ "$CODEX_HOME/skills/.system/skill-creator/scripts/quick_validate.py" \ skills/xhs-search-workflow 基础 smoke tests： skills/xhs-search-workflow/.venv/bin/python skills/xhs-search-workflow/scripts/xhs_full_cli.py --help skills/xhs-search-workflow/.venv/bin/python skills/xhs-search-workflow/scripts/export_notes.py --help ### 执行注意事项 * 优先使用 `skills/xhs-search-workflow/.venv/bin/python`，避免系统 Python 版本偏差。 * 环境变化后先执行 `scripts/setup_env.sh`。 * 保留 `assets/js/vendor/crypto-js.js` 以保证离线可运行。 * 脚本默认 UTF-8；Windows 下可额外设置 `PYTHONUTF8=1` 与 `PYTHONIOENCODING=utf-8`。 * `scripts/xhs_client.py` 会自动校验 JS 资源并同步 `assets/js/static/xhs_xray_pack{1,2}.js`。 * `xhs_full_cli.py` 全局参数必须在子命令之前。 * 正确：`xhs_full_cli.py --env-file .env --no-env-proxy ...` * 错误：`xhs_full_cli.py ... --env-file .env` * `messages-*` 返回可能很大，建议配合 `--out` 输出文件。 * `fetch_note_texts.py` 默认串行节流+重试，适合规避不稳定网络与风控抖动。 ### 故障排查见 `references/troubleshooting.md`。 ## English Guide ### Reference Repository * This skill is refactored from `Spider_XHS`. * Reference repository: `cv-cat/Spider_XHS` * Reference URL: Refactor principles: 1. Remove runtime dependency on original `apis/` and `xhs_utils` modules. 2. Bundle signing JS assets and dependencies inside this skill. 3. Provide a unified CLI plus scenario scripts for simpler reuse. ### Setup Run once on a new machine: skills/xhs-search-workflow/scripts/setup_env.sh It creates `skills/xhs-search-workflow/.venv` and installs Python dependencies. ### Auth Input * `--cookie "..."` * Or `--env-file /path/to/.env` with `COOKIES="..."` * Add `--no-env-proxy` when host proxy variables break requests. ### First Use: How to Capture Cookie 1. Log in to Xiaohongshu Web in your browser. 2. Open devtools `Network`, filter `Fetch/XHR`, refresh, and pick a business API request. 3. Prefer a request to `edith.xiaohongshu.com`, then copy the full `cookie` value from `Request Headers`. 4. Other request domains can also work if: * The request contains a full cookie header. * It includes at least `a1`, `web_session`, and `gid`. 5. Save cookie in `.env`: COOKIES="your_full_cookie_string" 6. First-run verification: skills/xhs-search-workflow/.venv/bin/python \ skills/xhs-search-workflow/scripts/xhs_full_cli.py \ --env-file .env --no-env-proxy homefeed-channels 7. If response shows `登录已过期` / `无登录信息`, re-login in browser and capture cookie again. Security notes: * Never paste cookie in chats, screenshots, or Git repositories. * Keep `.env` in `.gitignore`. ### Script List * `scripts/search_notes.py`: note search with filters * `scripts/fetch_note_texts.py`: extract title/text/image URLs, optional image download * `scripts/xhs_full_cli.py`: unified entry for user/comment/message/homefeed/creator/no-water APIs * `scripts/export_notes.py`: export note data to Excel and/or media files ### Typical Commands 1. Search notes skills/xhs-search-workflow/.venv/bin/python \ skills/xhs-search-workflow/scripts/search_notes.py "HSBC" \ --num 10 --sort 0 --note-type 0 --no-env-proxy --json 2. Extract note text and image URLs skills/xhs-search-workflow/.venv/bin/python \ skills/xhs-search-workflow/scripts/fetch_note_texts.py \ --url-file note_urls.txt --no-env-proxy \ --timeout 30 --retries 2 --min-interval 4 --max-interval 7 \ --out note_content.json 3. Download images while extracting skills/xhs-search-workflow/.venv/bin/python \ skills/xhs-search-workflow/scripts/fetch_note_texts.py \ --url-file note_urls.txt --no-env-proxy \ --download-images --image-dir xhs_images \ --timeout 30 --retries 2 --min-interval 4 --max-interval 7 \ --out note_content.json 4. Unified CLI example (search users) 技能/xhs-search-workflow/.venv/bin/python \ 技能/xhs-search-workflow/scripts/xhs_full_cli.py \ --env-file .env --no-env-proxy 搜索用户 --query "HSBC" --num 10 5.导出Excel/媒体技能/xhs-search-workflow/.venv/bin/python \ 技能/xhs-search-workflow/scripts/export_notes.py \ --query "HSBC" --num 10 --保存全部 \ --excel xhs_notes.xlsx --media-dir xhs_media --no-env-proxy ### `xhs_full_cli.py` 子命令 * `用户信息 --用户 ID ` * `用户自我信息` * `用户自我信息2` * `用户帖子 --user-url ` * `用户喜欢 --user-url ` * `用户收集 --user-url ` * `note-info --url ` * `note-comments --url ` * `搜索关键字 --word ` * `搜索用户 --query --num ` * `消息未读` * `消息提及` * `消息喜欢` * `消息连接` * `homefeed-channels` * `homefeed-recommend --category <名称> --num ` * `创建者发布` * `无水视频 --note-id ` * `no-water-img --img-url ` ### 范围和边界 * 覆盖范围：搜索、注释详细信息、评论、用户、消息、主页、创建者帖子、无水印转换、导出。 * 边界：默认基于cookie的身份验证；不包括交互式登录流程。 * 优点：脚本职责明确、完整的统一CLI、捆绑离线资产、可移植部署。 ### 离线和便携性 * 签名 JS 捆绑在 `assets/js/` 中。 * 离线“crypto-js”捆绑在“assets/js/vendor/crypto-js.js”。 * 运行时不会从原始 Spider_XHS 导入 `apis/` 或 `xhs_utils/`。 ### 验证编辑后运行：技能/xhs-search-workflow/.venv/bin/python \ “$CODEX_HOME/skills/.system/skill-creator/scripts/quick_validate.py”\ 技能/xhs-搜索工作流程基本烟雾测试：技能/xhs-search-workflow/.venv/bin/python 技能/xhs-search-workflow/scripts/xhs_full_cli.py --help 技能/xhs-search-workflow/.venv/bin/python 技能/xhs-search-workflow/scripts/export_notes.py --help ### 执行注释 * 优先选择 `skills/xhs-search-workflow/.venv/bin/python` 而不是系统 Python。 * 环境更改后重新运行 `scripts/setup_env.sh`。 * 保留 `assets/js/vendor/crypto-js.js` 以便离线移植。 * 脚本强制UTF-8输出；在 Windows 上还设置 `PYTHONUTF8=1` 和 `PYTHONIOENCODING=utf-8`。 * `scripts/xhs_client.py` 自动检查 JS 资源并同步 `assets/js/static/xhs_xray_pack{1,2}.js`。 * 将全局标志放在`xhs_full_cli.py`中的子命令之前。 * 消息端点可以很大；更喜欢“--out”文件。 * `fetch_note_texts.py` 使用串行限制和重试来保证稳定性。 ### 故障排除请参阅“references/troubleshooting.md”。

Xhs 搜索工作流程

包含技能