小红书统一入口

只做意图路由、参数选择、材料筛选和带来源的回答。让 scripts/xhs.py 执行登录、搜索、下载、入库与召回；不要在对话中重新拼接 Cookie、签名或临时爬虫。

前置检查

• 从本 SKILL.md 的实际安装位置定位脚本；不假设安装在某个用户目录。
• 登录、搜索、正文读取、本地召回只需要 Python 3.10+ 标准库与内置签名源码；首次登录还需要 Google Chrome。当前不支持 Windows。
• 视频下载需要 yt-dlp、ffprobe；口播提取另需 Whisper medium 与 ffmpeg。除 PATH 外还会在 ~/.local/bin、/opt/homebrew/bin、/usr/local/bin、~/bin 里找这些工具（cron、launchd 不读登录 shell 的 PATH）。仍找不到时报告 MISSING_TOOL，不要自动全局安装。
• 只在用户请求相应能力时使用媒体工具；普通搜索不自动下载全部帖子。
• 任何平台操作开始前先跑一次 status（要指定账号时用 profiles 先看标签）。拿到 NEED_LOGIN 就按下面的登录流程引导扫码，不要带着失效登录态往下跑。用户唯一需要做的动作是扫码，开窗口、等待、取 cookie、校验都由脚本完成。

示例中的 $SKILL_DIR 代表已定位的本 Skill 目录。所有命令输出单个 JSON 对象，包含 ok、schema_version 和 data 或 error。检查真实字段，不根据退出码独自推断内容完整。

路由

多账号

一个标签 = 一个账号 = 一套 cookie + 一个独立 Chrome 用户目录；账号之间不共用浏览器，因为一份 cookie 只能登一个号。

• 用户说「用小号搜」「把这个存到工作号草稿」时，先 profiles 确认标签，再带 --profile 执行；标签对不上就问用户，不要猜。
• 搜索、收藏夹、下载、草稿都跟着 --profile 走。素材库按账号 ID 分目录，同一账号换标签登录仍复用已有材料。
• 同时最多两个账号在工作，第三个会收到 BUSY。不要为了快而并发铺开：每多一个号就多一个 Chrome 和一路来自同一 IP 的请求。
• 批量跑完提醒用户 close --all，不要留着多个 Chrome。
• 同机、同 IP 下多号轮转有真实的风控风险，无法量化。脚本只做账号隔离（独立浏览器目录、按账号独立节流），不做代理池和指纹伪造；出现 RISK_CONTROL 就停下并如实告诉用户，不要换号重试同一件事。

收藏夹批量下载

用户要「把收藏里关于某主题的几篇下载下来」时：

1. 先 albums 看有没有对应主题的收藏夹。有就 collected --album 名字；没有就 collected --keyword 词，词取用户说法及其常见写法（如 ui、UI、设计）。标题预筛只匹配标题，漏召回很正常，必要时放宽关键词或加大 --pages。
2. 读返回的标题自己判断哪几篇真属于该主题，再确认篇数；用户说「几篇」且没给数字时按最近 3–5 篇并说明取了几篇。平台返回的是收藏页顺序，脚本不另外按时间排序。
3. 把选中的 ID 一次性交给 fetch ID1 ID2 ... --media，需要口播再加 --transcribe。转录在 CPU 上大约是视频时长的 2–4 倍（实测 6 分钟视频约 22 分钟），先按这个量级告诉用户预计耗时，再开始跑。
4. 逐篇结果在 notes 里，失败的在 failed 里。报告实际成功几篇、落在哪个目录，不要把请求篇数当成功篇数。遇到 RISK_CONTROL 或 NEED_LOGIN 时脚本会停下并把其余标成 SKIPPED，照实报告。

搜索与回答

1. 根据问题先 recall 已有材料；需要新证据时再 search。默认最多三个搜索词，深入读取最多十篇，有足够证据就停止。
2. 根据标题和相关性选择帖子，调用 fetch 读正文。搜索卡片只能当线索。
3. 视频正文只有标签时，不能假装已经理解视频。重要视频用 --transcribe；图文信息主要在图片时，阅读已下载图片，说明图片文字尚未进入自动索引。
4. 将答案连接到实际读过的正文、口播或图片，并附帖子链接或本地 note.md。区分作者经验、评论、模型推断与转录错误；不把点赞量当真实性证明。
5. 缺少材料或作者说法冲突时明确指出；不用已有常识填充成“小红书搜索结论”。

数据与账号

数据默认放在用户主目录下 .local/share/xiaohongshu，可在子命令前用 --data-dir 指定。登录态按标签放在 profiles/<标签>/（cookie、浏览器端口、Chrome 用户目录、并发锁各自一份）；素材按账号 ID 放在 accounts/<哈希>/，各账号独立的 SQLite 和笔记目录。旧的单账号安装会在首次运行时自动迁到 profiles/default，不需要重新扫码；迁移前会先关掉还在跑的专用浏览器，避免移动正在使用的 Chrome 用户目录。Skill 源码与用户知识分离。

search、collected 保存候选记录与详情访问引用；收藏夹标称篇数可能大于接口实际能取到的篇数，已删除或已不可见的帖子仍计入显示数字，按返回的条目报告而不是按标称数字；只有 fetch 保存的完整材料进入本地召回。collected 不改动平台上的收藏，只读；收藏夹列表取自专用浏览器渲染的页面（平台没有可签名的列表接口），收藏夹里的帖子仍走接口。按帖子 ID 去重，已保存正文、媒体和字幕可复用，不重复跑转录。价格、日期等需要新鲜数据时不要把旧缓存当现状；当前需要更新单篇内容时先说明缓存范围，由用户决定是否重新获取。

账号凭证只保存在本地私有文件，不输出到回答、日志、Git 或外部模型。只连接本脚本创建的 Chrome endpoint，不扫描主浏览器、不注入旧 Cookie。不承诺登录永久有效。

专用浏览器纪律

• 网页操作只用专用浏览器：任何要打开小红书网页的事（主站、创作服务平台、小工具模拟器等），都通过 xhs.py 命令，或脚本里的 Browser(profiles/<标签>).connect() 连接已登录的那个 Chrome。
• 禁止另开浏览器：
  • 禁止启动无头浏览器、Playwright / Puppeteer 测试浏览器或另一个 Chrome 实例去访问小红书。
  • 尤其不要用它们打开 profiles/<标签>/ 下的 Chrome 用户目录：另一个进程会改写同一份 cookie 库，实测会让专用浏览器里的主站和创作平台同时掉登录。
  • 而且 status 校验的是另存的凭据，掉登录后它仍显示已登录，问题不会立刻暴露。
• 后台标签不会正常运行：专用浏览器默认在后台标签打开页面。这种标签里动画停在中间帧、计时器被节流，会出现：
  • 截图截到半透明的弹窗；
  • 登录页轮询扫码结果变慢；
  • 动态页面卡住。
• 要页面持续运行就用前台标签：用 CDP Target.createTarget 并传 background: false。这只是切换 Chrome 里的标签，不会把 Chrome 提到前台、不抢用户焦点。

网页端掉登录

现象：专用浏览器里主站弹出登录框，或创作服务平台跳到 /login，但 status 可能仍是已登录（见上一节）。恢复时仍在专用浏览器里扫码，不换浏览器、不导入别处的 Cookie：

1. 打开登录页（在专用浏览器的前台标签里打开）：
   • 主站打开发现页，登录弹窗默认就是二维码；
   • 创作服务平台打开后会跳到登录页，点登录卡片右上角的小图标，切到“APP扫一扫登录”。
2. 扫码：用户用登录了同一账号的小红书 App 扫码。手机 App 上登录的是哪个号，浏览器就会登进哪个号。
3. 等页面跳走：扫码后保持登录页，别刷新，等它自己跳转。刷新会丢掉这次扫码会话。

想把扫码自动化（例如有一台用 adb 控制、已登录同一账号的安卓手机）时：

• 取码：不要截屏，直接取二维码 <img> 的 src（两个站都是 data:image/png），放大并加白边后推进手机相册。截屏会截到半透明的弹窗，手机识别不了。
• App 里的操作：“我 → 扫一扫 → 相册”，选这张图。首次扫码会请求相机权限。
• 确认页：
  • 创作服务平台：点“登录”；弹出“请阅读并同意”就点“同意并登录”。
  • 主站：点“确认登录”。
• 核对账号：扫码前先在 App“我”页核对昵称就是目标账号，对不上就停，交给用户。
• 收尾：完成后删掉推进手机相册的二维码图片。

draft 只写入草稿箱，不发布、不定时发布、不改动已发布笔记。草稿存在专用浏览器的本地存储里，不在账号云端：换浏览器或清除该 profile 数据即消失，也不会出现在手机 App。draft 会先关掉遗留的创作页标签，再开新标签操作，结束后回查草稿箱确认最新一条就是本次标题；标题未被确认时不会留下草稿。用户要求真正发布时，让其本人在专用浏览器里点击发布。

错误处理

• NEED_LOGIN：先告诉用户要扫码，再跑 login（会自己等待并收尾）；不自动切到别的账号。若报错来自浏览器页面（如 draft 提示创作服务平台要求登录），按「网页端掉登录」在专用浏览器里扫码。
• LOGIN_TIMEOUT：等待期内没扫完，窗口仍开着。确认用户是否还要登录，要就再跑一次 login；不要改用别的账号或别的方式绕过。
• RISK_CONTROL：停止本次平台请求，让用户查看专用浏览器，不更换代理、伪造验证或循环重试。
• INCOMPLETE_RESPONSE：响应缺少必要数据，不能报告“没有结果”或“帖子已删除”。
• TOOL_FAILED、INVALID_VIDEO：报告阶段未完成，保留已经保存的正文与部分文件；不要声称完整下载成功。
• BUSY：同一账号已有操作在跑，或已有两个账号在同时工作。等它结束，不绕开锁并行访问账号。
• UPLOAD_FAILED：素材未被编辑器接收，此时没有保存任何草稿；检查文件格式与大小后重试，不要声称已存草稿。
• DRAFT_UNCONFIRMED：没有拿到平台确认，或草稿箱里最新一条不是本次标题。报告未确认，让用户在专用浏览器核对；不要重复提交。
• PAGE_CHANGED：创作页结构与脚本预期不符，可能是平台改版。报告具体步骤，不要改用猜测的选择器硬点。
• ALBUM_UNKNOWN、ALBUM_AMBIGUOUS：收藏夹名没缓存或匹配到多个。先跑 albums，或用返回的完整名字、收藏夹链接重试；不要猜 ID。
• PERMISSION_DENIED：报告不可写的安装/数据边界，不尝试绕过。

单入口安装

先运行 python3 "$SKILL_DIR/scripts/xhs.py" install 查看迁移对象。用户已要求统一本机入口时执行 install --apply：旧小红书入口移到不可发现的备份目录，Codex 与 Claude 各保留指向同一源码的 xiaohongshu 链接。

换一台电脑时：代码跟仓库走，登录态不跟着走。新机器上先 install --apply 建链接，再 login 扫码登录每个要用的账号（--profile 标签 分别登），数据目录和素材库都是本机的，不与旧机同步。

恢复使用 install --restore "返回的备份目录"。安装程序不修改已有用户知识或 Chrome profile；安装成功不表示当前会话已经重新加载技能，必要时新开会话验证发现结果。

源码来源、许可证和修改范围见 THIRD_PARTY_NOTICES.md。