红薯自动操控Skill

概述

红薯自动化

仅通过本技能的平台启动器操作小红书：macOS/Linux 使用 ./scripts/run-hongshu <子命令>，Windows 使用 powershell.exe -NoProfile -ExecutionPolicy Bypass -File .scriptsrun-hongshu.ps1 <子命令>。启动器使用锁定依赖运行 CLI；不要调用其他小红书项目或旧版 xiaohongshu-skills，也不要用 MCP 或浏览器脚本绕开启动器直接操作小红书。处理非小红书来源时，可用宿主可信的网页读取或下载工具先将媒体保存到本地。

原生支持 macOS、Linux 和 Windows 10/11（Windows PowerShell 5.1 或 PowerShell 7），三个平台都要求系统已安装 uv 和 Google Chrome。不在 WSL 内运行；Windows 必须从本机 PowerShell 启动，以便 CLI、桥接和 Chrome 共享同一套 Windows 路径与回环网络。

核心流程

1. 每次新环境首次调用时，在技能目录用对应平台启动器运行 onboard；不要先尝试任何小红书页面命令。若是 Windows 新环境、本次安装尚未成功运行 onboard，或用户询问在哪里输入命令，必须先完整读取 [references/windows-first-run.md](references/windows-first-run.md)，把其“发给 Windows 用户的教程”发给用户，然后再运行或要求用户运行 onboard。
2. 读取 data.ready 与 data.onboarding：
   • state=ready：直接继续。
   • state=extension_install_required 或 extension_reload_required：完整读取 [references/extension-setup.md](references/extension-setup.md) 并严格按其流程安装、重载和验收。
   • state=bridge_repair_required：重新运行一次 onboard；若返回 bridge_upgrade_deferred，按下方的旧桥接升级边界处理，不得自动结束进程。
   • state=bridge_recovery_required：上一次写操作的最终状态不确定；停止所有页面操作，让用户先在浏览器和账号中核验，再按本次返回的 recovery_argv_after_confirmation 解除隔离。
   • state=package_invalid：停止并要求重新安装完整 Skill 包；不要从网络下载替代扩展。
3. 用户完成消息中的 Chrome 安全步骤后，原样运行 verification_argv；只有 ready=true 才算完成。不得把“已打开扩展页”误报为“已安装扩展”。
4. 若这是首次安装或首次重载扩展，本次 onboard 返回 ready=true 后原样发送 data.onboarding.success_user_message，其中包含三个可直接使用的案例，然后结束安装流程；不要自动执行案例，也不要运行 risk-report、check-login 或任何页面命令。扩展连接成功不代表账号已登录。
5. 用户之后明确提出实际小红书操作时，在任何页面操作前用对应平台启动器运行 risk-report；该命令只读取本地记录，不导航页面。若当前或历史等级为 high，立即停止并让用户先检查账号状态。
6. 风控允许继续时，用对应平台启动器运行 check-login。
7. 已登记多个账号时，先确认用户本次指定的账号名，并在所有页面命令前添加全局 --account NAME；不得猜测默认账号。
8. 根据意图选择命令：
   • 登录、退出或验证码：认证命令。
   • 首页、搜索、详情或主页：发现命令。
   • 将视频笔记保存到本地：视频下载命令。
   • 评论、回复、点赞或收藏：互动命令。
   • 图文、视频、长文或草稿：发布命令。
   • 竞品、热点、创作或互动策略：组合多个只读命令，再按确认边界执行写操作。
9. 解析唯一的 JSON 输出；使用 ok 判断成功，使用 error.code 决定恢复方式。

多账号矩阵管理

• 用户要求“新增账号”且当前 Chrome Profile 已登录时，先运行 account-inspect；展示返回的昵称、user_id 和 instance_id，不展示会话指纹。
• 只有用户确认“将检测到的这个账号绑定为 NAME”后，才运行 account-add --name NAME --expected-user-id USER_ID --confirm。
• 一个 Chrome Profile 扩展实例只能绑定一个账号名。第二个同时保持登录的账号必须使用另一个由用户创建的 Chrome Profile，并在该 Profile 中按 [references/extension-setup.md](references/extension-setup.md) 安装同一包内扩展。
• account-list 返回已绑定账号、连接状态与未绑定扩展实例。连接多个实例时，用 --instance-id 完成只读检查和绑定。
• 账号绑定后，扩展会在写操作开始前比对会话 HMAC 指纹。指纹变化时停止操作；只有当前 user_id 仍与旧绑定一致且用户确认后，才运行 account-verify --name NAME --confirm。
• account-unbind 只删除本地路由记录；不退出小红书、不删 Cookie、不删 Chrome Profile。需先向用户明确说明此边界并取得本次确认。
• 本地账号注册表只保存账号名、昵称、平台用户 ID、扩展实例 ID 和不可逆会话指纹；不保存原始 Cookie、密码、手机号或验证码。

构造参数时读取 [references/commands.md](references/commands.md)。执行竞品分析、热点追踪、内容创作或互动管理时读取 [references/workflows.md](references/workflows.md)。

强制安全边界

• 扩展安装与重载只按 [references/extension-setup.md](references/extension-setup.md) 执行；只使用 onboard 本次输出的真实路径、名称、版本和命令数组，不安装第三方扩展或绕过 Chrome 安全界面。
• 先取得用户对最终标题、正文、本地媒体和发布设置的明确确认，再运行任一预览创建命令。
• 先取得用户对最终评论或回复文字的明确确认，再运行评论命令。
• 仅在用户明确授权本次账号写操作后添加 --confirm。不要预先添加或把历史确认复用于新内容。
• 互动目标不确定时先运行只读的 inspect-actions；它可检查当前点赞/收藏状态、评论入口和回复目标，不执行点击。
• 详情和互动的 feed_id、xsec_token、xsec_source 必须原样来自同一条首页或搜索结果；不得混用或猜测来源。用户主页使用该结果独立返回的作者 ID、作者令牌和作者来源。
• fill-publish、fill-publish-video、publish 和 publish-video 都只创建浏览器预览，不执行最终发布；保留返回的 preview_id，让用户检查预览并再次明确确认后，才运行 click-publish --preview-id PREVIEW_ID --confirm。
• preview_id 必须来自当前最新且完整校验的预览；不得推断、修改或复用旧预览标识。
• 只有完整上传、填表和设置校验都成功的预览才可提交；新一轮填写会使旧预览失效，成功提交或保存后也会立即失效，预览最长保留 4 小时。
• 若提交返回 remote_code=operation_state_uncertain，且 cause_code 为 submission_state_uncertain 或 submission_unconfirmed，不要自动重试；先让用户在浏览器和账号内容中确认是否已经发布或保存。
• 若 onboard 返回 bridge_recovery_required，不得自动恢复或重试原操作。只有用户已核验上次操作结果并对“解除隔离”再次明确确认后，才可原样运行带当前 request_id 的 recovery_argv_after_confirmation。
• 若错误详情的 remote_code=bridge_upgrade_deferred，表示检测到旧版未认证桥接，无法判断它是否正在执行写操作。让用户先确认浏览器中没有发布、评论、登录等进行中操作，再经本次明确确认运行 upgrade-bridge --confirm；不得为了升级而直接杀进程。
• 用户取消发布时运行 save-draft --preview-id PREVIEW_ID --confirm；使用当前预览返回的同一 ID，不要直接关闭仍有内容的创作标签页。
• 发送短信、退出登录、评论、回复、点赞、收藏、上传发布预览、长文草稿编辑、发布、点击发布和保存草稿均受代码级确认门禁保护。
• 标题、正文、图片和视频只使用绝对本地路径；不将远程图片 URL 传给 CLI。不要把敏感文本写入命令日志；标题和正文使用 UTF-8 文件传递。
• download-video 每次只下载一条由同一搜索或首页结果三元组定位的视频笔记，保存到 Chrome 默认下载目录的 hongshuskill 子目录；只允许安全的 .mp4 文件名，不接受绝对路径、子目录或远程输出地址。
• 视频下载使用跨账号、跨 Chrome Profile、跨桥接重启共享的每日安全下载额度：每个本机自然日最多启动 20 次，本地时间次日 00:00 自动重置。额度在转发给 Chrome 前持久占用；即使下载失败、断线或用户重试，本次仍计入，不能通过切换账号或清理浏览器扩展存储绕过。成功后向用户原样展示 rate_limit.safe_download_remaining_text（例如“安全下载额度剩余 14 次”）；数值也可从 rate_limit.safe_download_remaining 读取。
• 已登记两个或更多账号时，任何小红书页面操作都必须显式指定 --account；不根据历史对话、昵称相似度或最后连接顺序猜测。
• 不批量刷互动。详情每读取 3 篇后随机等待 10–20 秒；互动之间等待 30–60 秒。
• check-risk 默认只做被动检查。只有用户明确授权本次真实 API 诊断后，才可使用 --active-probes --confirm；已有近期高风险响应、验证页或可见限制时不得执行主动探测。
• 遇到 risk_level 为 high 时立即停止账号操作并报告用户。
• risk-report 的 risk_level 代表最近 15 分钟，historical_risk_level 代表 24 小时保留证据；历史等级为 high 时，在用户检查账号状态前不要恢复写操作。
• 扩展会在最近 15 分钟出现 429、461 或 999 时返回 risk_control_active，即使已有 --confirm 也不会执行写操作；不要绕过或清理日志后重试。
• 最终 click-publish 会再次检查风控；页面可见的发布限制也会转为保留门禁，不能因上传开始时状态正常而继续提交。

输出与错误

启动器预检失败、uv 无法启动锁定环境，以及 CLI 成功启动后的所有命令，都输出一个 JSON 对象：

{
  "ok": true,
  "command": "search-feeds",
  "data": {},
  "meta": {"version": "1.7.7", "elapsed_ms": 1234}
}

失败时读取 error.code：

• authentication_required：进入登录流程。
• confirmation_required：展示最终动作并等待用户确认；不要自动重试。
• invalid_input：修正参数、路径、标题长度或文件格式。
• runtime_dependency_missing：安装缺失的 uv；macOS/Linux 还需 POSIX 基础工具。
• runtime_platform_unsupported：Windows 正在从 Git Bash、MSYS 或 Cygwin 启动；改用包内 PowerShell 启动器，不复用 Bash 的 $TEMP 或虚拟环境。
• unsafe_runtime_directory 或 runtime_setup_failed：停止并报告本地运行目录问题；不绕过符号链接或权限检查。
• runtime_launch_failed：uv 未能创建或启动锁定环境；报告稳定错误，不转发可能含本机路径的原始 stderr。
• bridge_unavailable：读取扩展安装说明并检查本地扩展。
• browser_operation_failed：先读取 remote_code。普通页面错误可运行 check-risk 和 diagnose-404 后再决定是否重试；不确定操作或桥接隔离必须按下方恢复流程处理。
• risk_control_active：立即停止账号操作，报告状态码和建议等待时间；不要自动重试。
• browser_operation_failed 且 remote_code=download_rate_limit：今日安全下载额度已满；原样展示 safe_download_remaining_text，并报告 reset_at 与 retry_after_seconds，重置前不要重试或切换账号规避。

发布类的不确定终态会统一返回 remote_code=operation_state_uncertain，原始原因保存在 cause_code。若 cause_code 为 submission_state_uncertain 或 submission_unconfirmed，不得按普通页面错误重试；必须先由用户检查实际账号状态。若 remote_code 为 preview_id_required 或 preview_id_mismatch，不得猜测 ID 或继续提交；丢失当前 preview_id 时重新创建预览并让用户重新检查。若 remote_code 为 operation_state_uncertain，表示任意账号写操作在执行期间超时、断线，或互动状态在重新加载后未被服务器页面确认；同样不得自动重试，必须先核对浏览器、短信、互动状态、个人主页或草稿箱。若 remote_code 为 operation_quarantined，或核验不确定写操作后需要恢复，先运行 onboard 取得当前 bridge_recovery_required 和唯一 request_id；此时 risk-report、check-risk 和页面命令同样会被隔离，不得把它们当成恢复步骤循环重试。若 bridge_unavailable 的 remote_code 为 bridge_upgrade_deferred，不按“扩展未连接”处理；使用上述有人确认的旧桥接升级流程。若 bridge_unavailable 的 remote_code 为 bridge_identity_unverified，表示端口可能被另一份安装或其他本地进程占用。不得运行 upgrade-bridge、发送信号或删除 PID 文件；让用户先确认没有进行中的账号操作，再从该旧副本的所属应用或任务中关闭它，然后重新运行 onboard。若评论或回复返回的 remote_code=operation_state_uncertain 且 cause_code=comment_submission_unconfirmed，页面没有给出足够成功证据；先由用户检查目标笔记，不要自动发送相同文字。若 cause_code=logout_unconfirmed，先让用户检查当前登录状态，再按隔离恢复流程处理；不要先运行会同样被隔离的页面诊断命令。

退出码为 0 表示成功，1 表示检查到需要登录，2 表示输入/未知错误或本次登录未完成，3 表示桥接不可用，4 表示浏览器操作失败，5 表示缺少用户确认。

登录边界

• 二维码登录：运行 get-qrcode，展示 qrcode_path，再运行一次 wait-login；二维码过期后重新获取。
• 手机登录：每次都重新向用户确认手机号，然后运行 send-code --confirm；收到用户提供的本次验证码后运行 verify-code。
• 不从对话历史、记忆或浏览器内容推断手机号或验证码。
• 不读取浏览器密码。为防止用户在预览后切换账号却仍提交旧草稿，扩展会在本机内短暂读取最小会话 Cookie 标识并立即用本地配对密钥转换为 HMAC 指纹；原始 Cookie 值不写入扩展存储、日志或 RPC 输出。delete-cookies --confirm 仅用于用户明确要求退出账号时。
• 检测到未登录、开始重新登录或执行退出时，扩展会使已有发布预览失效，防止旧账号草稿被提交到另一个账号。

发布边界

• 校验普通图文/视频标题不超过 20 个小红书长度单位：逐个 UTF-16 码元计算，非 ASCII 计 1，ASCII 计 0.5，最后向上取整。
• 图文提供 1–18 张 JPG、JPEG、PNG、GIF、WebP、BMP 或 SVG；单张不超过 32 MB，仅支持绝对本地路径。
• 标签去重后最多使用 10 个；多余标签不会进入发布表单。
• 视频使用绝对本地路径；不要混合图片与视频。
• 可见范围仅使用：公开可见、仅自己可见、仅互关好友可见。
• 长文在用户确认内容后，按照 long-article --confirm → 保留 preview_id → select-template --preview-id PREVIEW_ID --confirm → 展示并确认描述、可见范围、定时时间和原创声明 → next-step --preview-id PREVIEW_ID ... --confirm → 用户预览并再次确认 → click-publish --preview-id PREVIEW_ID --confirm 执行。
• 长文模板未成功加载时命令会失败，不会把空模板列表误报为可继续；未选择模板时不能进入下一步。

视频下载边界

• 从首页或搜索结果取得同一条视频笔记的 feed_id、xsec_token 和 xsec_source，原样传给 download-video；不要猜测或混用三元组。
• 命令只启动 Chrome 管理的视频下载，不发布内容、不修改笔记互动状态，也不需要 --confirm。返回的 filename 是 Chrome 解析后的目标路径；state=in_progress 表示 Chrome 正在后台继续下载。
• 默认文件名为 FEED_ID.mp4；用户指定时只传 .mp4 文件名。已有同名文件时 Chrome 自动添加序号，不覆盖旧文件。
• 批量请求必须串行执行并在调用前自行截断到当天安全下载额度的剩余次数；每次成功后向用户原样展示 rate_limit.safe_download_remaining_text。收到 download_rate_limit 后立即停止，不自动等待并继续下一批；额度会在 reset_at 所示的本机次日 00:00 自动重置。