小红书笔记调研

把「翻小红书找爆款」变成可复现、口径可追溯、敢标注局限的流程。

三条原则（每次调用都适用）：口径先行、诚实标注样本边界、采集与计算分离（数字一律交给 scripts/xhs_rank.py，不在提示词里心算）。

本文件只放每次调用都必须遵守的东西：能不能做、该不该做、何时必须停。执行细节按需读 reference，导航表在文末。

⚠️ 硬依赖：能操作浏览器 + 用户本人已登录

小红书对未登录访问和自动化请求有反爬限制：搜索结果、完整笔记、评论区都在登录墙后，页面数据由服务端注入。HTTP 直连、爬虫库、第三方数据接口都拿不到可用数据，还会把账号推向验证码与风控。这不是"最好满足"，是必须同时成立：

缺能力时先引导用户装，不要硬跑：按宿主类型给具体步骤（桌面 Agent 走连接器市场、CLI Agent 走 Playwright、都没有则降级 D2/D3），步骤与话术见 references/workflow.md 阶段 1.1b。验证标准：四原语可调用，且页面探针返回 codes: []、hasNoteNodes > 0。运行环境另有 Python 3.8+（仅标准库）。

绝对不做：索取或代填账号密码、Cookie、token；用用户登录态注入请求；怂恿"多试几次就过了"。这些要么无效，要么把账号风险与合规风险转嫁给用户。

定位：只做小红书站内，不锁品类

稀缺价值是平台特异性知识——登录墙、服务端注入的数据结构、热评层边界、token 机制、反爬表现。换平台这部分就归零，所以边界刻意收窄：

• 只做小红书站内。 要抖音/微博/电商评论就换工具，别在本技能里加平台分支，那会把平台知识稀释成通用空话。
• 只做市场调研与用户研究。 爆款拆解、选题验证、竞品内容、评论需求与顾虑、新品概念验证。
• 不锁品类。 丝绸/真丝只是贯穿全文的默认示例，美妆、母婴、3C、家居用法完全一致。

🔴 三个检查点

无人值守模式：用户要求别打断时，把三项确认转成报告开头的「待确认假设」表（假设 / 依据 / 若不成立影响哪条结论）。换载体可以，省略不行。

七个阶段

默认口径（用户不指定就用，阶段 0 必须告知）：时间窗近 12 个自然月（--months，0 为不限；--since 优先）· 目标有效笔记150 条（--target-notes，不是卡片数）· 榜单20 条（--top）· 打分 raw、权重 1,1,1（赞,藏,评）、衰减关、基准日宿主机当天。完整默认表见 ranking.md。按自然月回溯，不是减 365 天。

研究型调研推荐 --score normalized --weights 1,3,2（收藏权重最高）。缺省 raw+1,1,1 会让点赞压过收藏与评论，与"内容机会/购买意图"类问题不匹配；开跑前确认用哪套并写进口径声明。

日期与时区：按宿主机本地时区解释，不做 UTC 换算；换机器或跨时区复算须显式传同一个 --today，细节见 commands.md 五个约定。不要手抄示例日期——复现用 summary.md 自动生成的那行。

用户只说"最近"就用默认并说明，给了具体时段就换算成 --since。

数据完整度 T0-T3（阶段 0′ 判定，与浏览器能力 D0-D3 正交）：T0 卡片+详情+评论正文 → 可做互动结构与评论洞察；T1 缺评论正文 → 不得回答"用户在意什么"；T2 仅卡片 → 只做排序与题材分布；T3 仅标题 → 只给方向性假设。T1 及以下按 references/report.md 的「评论不可得」分支写。

遇阻怎么办

三种高频情况直接按箭头走：

• 如果出现验证码 / 安全验证 / 访问频繁 → 立即停整轮，告知用户，不重试
• 如果详情页跳回搜索页或错误页 → token 原样重取并编码，重试一次
• 如果连续 3 篇详情失败 → 停止详情采集（多半被限速），按热评层样本交付

其余情况见下表。任何一次失败都要把原因与篇数写进报告的失败清单，不得当作「没有这类内容」。

硬性规则与反模式

必须：计数一律走脚本（1.2万 去符号取整会变 12）；研究型调研先清洗再排序（壁纸/抽奖互动量最高，不洗必霸榜）；每次调研独立运行 ID，启动扫描历史运行、确认后才清理；复算固定 --today；失败篇数与原因进报告；结论不臆造，取不到标「未取到」。

不要做：

1. 在页面直连评论接口——需请求签名，是死路，不是临时故障。
2. 在详情页反复滚动加载更多评论——懒加载未接线，任何滚动都无效。
3. 手抄 xsec_token——错一字符即跳错误页，让页面脚本拼好再原样导航。
4. 用 0 填充取不到的粉丝数/互动数——0 会被当真实值参与计算。
5. 把 T1/T2 数据包装成完整调研——缺评论正文就明说答不了。
6. 把字段名写死——xsec_token 实际叫 xsecToken，写死会让整轮采集静默丢字段。

文件导航

每篇都可以从这里一跳到达。只读当下需要的那篇。