ZJU-REAL/Easel / skills/builtin/skill-xhs-analyzer
redbook
Flagged小红书内容分析:搜索笔记、拉取互动数据、分析爆款规律、创作者画像、限流检测,支持 CLI 自动化操作。 当用户说"小红书数据分析""小红书爆款分析""笔记数据""小红书限流检测""小红书创作者画像""分析小红书账号"时使用。 发布与日常互动运营请用 skill-xhs-publisher。
| File | Kind | Size |
|---|---|---|
| .github/workflows/npm-publish.yml | config | 3.8 KB |
| EASEL-META.md | markdown | 2.1 KB |
| SKILL.md | skill md | 5.2 KB |
| package-lock.json | manifest | 36.6 KB |
| package.json | manifest | 1.6 KB |
| references/commands.md | markdown | 4.4 KB |
| references/modules.md | markdown | 6.2 KB |
| references/platform-signals.md | markdown | 1.7 KB |
| references/research-loop.md | markdown | 8.2 KB |
| references/technical-reference.md | markdown | 3.8 KB |
| scripts/postinstall.js | script | 4.5 KB |
| scripts/preuninstall.js | script | 1.4 KB |
| social-preview.html | other | 5.1 KB |
| social-preview.png | binary | 261.4 KB |
| src/cli.ts | script | 76.8 KB |
| src/lib/analyze.ts | script | 20.0 KB |
| src/lib/cdp-cookies.ts | script | 13.1 KB |
| src/lib/client.ts | script | 22.2 KB |
| src/lib/cookies.ts | script | 13.3 KB |
| src/lib/creator-signing.ts | script | 1.8 KB |
| src/lib/detect.ts | script | 6.6 KB |
| src/lib/fingerprint-data.ts | script | 2.3 KB |
| src/lib/health.ts | script | 5.5 KB |
| src/lib/platform.ts | script | 2.7 KB |
| src/lib/render.ts | script | 19.5 KB |
| src/lib/reply-strategy.ts | script | 6.0 KB |
| src/lib/signing.ts | script | 21.1 KB |
| src/lib/template.ts | script | 8.0 KB |
| src/lib/url.ts | script | 1.8 KB |
| tsconfig.json | config | 458 B |
references/technical-reference.md
View on GitHub# 技术参考
## 大陆小红书 vs 全球 RedNote
XHS 跑**两个独立后端,不共享 session/cookie**:
| | 大陆 | 全球 |
|---|---|---|
| App/站点 | 小红书 / `xiaohongshu.com` | RedNote / `rednote.com` |
| API host | `edith.xiaohongshu.com` | `webapi.rednote.com` |
| Cookie 域 | `.xiaohongshu.com` | `.rednote.com` |
RedNote 按 IP/地区路由,一台机器一次只能登一个 —— **CLI 自动检测**你登的是哪个,通常**不传任何 flag**。检测:探测两个 cookie 域,只一个有 session 就用它;两个都有则用一次 `/user/me` 验证。结果缓存 `~/.redbook/platform-cache.json`(按 cookie 指纹),登入/登出自失效。stderr 显示 `Platform: … [auto-detected|cached]`。
强制覆盖(罕见):`--global` / `--platform xhs` / `export REDBOOK_PLATFORM=rednote`。web 签名(x-s/x-t)两端**相同**,只 host + cookie 域不同。
全球后端已知缺口:`user-posts`/`user` 可能需新鲜 profile `xsec_token`;`health` 需先登 RedNote 创作者面板。
## xsec_token —— 读取与分享笔记必需
XHS API 需有效 `xsec_token` 才能取笔记内容,否则 `read`/`comments`/`analyze-viral` 返回 `{}`。无 token 的 `explore/<id>` URL 会被反爬层 302 重定向到 404 页。
**用 `webUrl`(v0.7.0 起)**:每个返回笔记的命令(`feed`/`search`/`user-posts`/`favorites`/`board`/`read`/`post`)都含 `webUrl` 字段,token 已内嵌 + 正确 `xsec_source`。直接用 `webUrl`,别手工拼 URL。`xsec_source` 按命令设:`pc_feed`/`pc_search`/`pc_user`/`pc_board`/`pc_share`。
关键规则:
1. **token 会过期。** 上个会话的 URL 会返回 `{}`,绝不缓存/复用旧 URL。
2. **`search` 和 `feed` 总返回新鲜 token。**
3. **bare noteId 返回 `{}`。** 正确工作流:先 `search`,从结果取 `webUrl`,再 `read "<webUrl>"`。
需笔记 xsec_token:`read`/`comments`/`analyze-viral`;可能需 profile xsec_token:`user`/`user-posts`;不需要:`search`/`feed`/`whoami`/`topics`。
## 中文数字格式
API 返回带中文单位的缩写数字,解析 `interact_info` 时注意:
| API 值 | 实际 |
|--------|------|
| `"1.5万"` | 15,000 |
| `"2.4万"` | 24,000 |
| `"1.2亿"` | 120,000,000 |
| `"115"` | 115 |
`万`=×10,000,`亿`=×100,000,000。<10,000 是纯整数字符串。`analyze-viral` 自动处理,手动解析 `--json` 时留意后缀。
## 错误处理
| 错误 | 含义 | 修复 |
|------|------|------|
| `{}` 空响应 | 缺/过期 xsec_token | 先 search 拿新鲜 token |
| "No 'a1' cookie" | 未登录 XHS | 在 Chrome 登录 xiaohongshu.com |
| "Session expired" | cookie 太旧 | 重登 Chrome |
| "NeedVerify"/验证码 | 反爬触发 | 等待重试,或降频(见 research-loop.md) |
| "IP blocked" (300012) | 限速 | 等待或换网 |
## API vs 浏览器 限制
- API 可靠:读(search/notes/comments/user/feed/favorites)、写(一级评论/回复/收藏)、分析(viral 评分/模板/批量回复计划)。
- API 不可靠(常触发验证码):发布笔记(`--private` 成功率高些)、超高频批量。
- 需浏览器自动化(本 CLI 不支持):验证码求解、实时通知、点赞/关注(重反自动化)、私信、封面生图。
## 输出格式指引
- 数据表:Markdown 表 + 精确字段映射,含单位。
- 热力图:ASCII 条形图做跨主题对比。
- 最终报告章节顺序:1.市场概览 → 2.关键词版图 → 3.跨主题热力图 → 4.受众画像 → 5.竞争版图 → 6.内容机会(分级)→ 7.内容 idea(具体 hook/角度/目标)。
## 程序化 API
```typescript
import { XhsClient } from "@lucasygu/redbook";
import { loadCookies } from "@lucasygu/redbook/cookies";
const cookies = await loadCookies("chrome");
const client = new XhsClient(cookies);
const results = await client.searchNotes("AI编程", 1, 20, "popular");
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |