小红书媒体助手技能 (`skill-xiaohongshu-media-assistant`)

skill-xiaohongshu-media-assistant 是一个标准的 Claude Code 技能模块，通过接入 ServiceHub 平台的小红书数据接口，为 AI Agent 提供小红书博主主页笔记列表、图文与视频笔记详情、笔记评论与回复抓取、视频笔记原始文案提取以及笔记搜索等全方位自媒体数据能力。

核心功能

博主笔记列表 (blogger)：抓取指定小红书博主已发布笔记列表，支持分页游标断点续翻。
图文笔记详情 (note --note-type image)：获取图文笔记元数据、描述正文、图片 URL 列表及互动数据（点赞、收藏、评论、分享）。
视频笔记详情 (note --note-type video)：获取视频笔记元数据、无水印视频下载链接、视频时长及播放数据。
视频笔记原始文案 (text)：解析视频笔记的字幕文件（subtitle_url），转换为无时间轴的原始文本稿（video_text_ori）。
笔记评论及回复 (comment / reply)：抓取笔记根评论列表以及指定根评论下的子评论/回复列表。
笔记搜索 (search)：根据关键词与筛选条件检索小红书笔记。

业务流程图

flowchart TD
    A[用户自然语言请求] --> B[技能意图识别 & 参数提取]
    B --> C{必要的凭证或参数是否完整?}
    C -- 否 --> D[针对性追问用户补充参数]
    C -- 是 --> E{模式判断 extract / update}
    E -- update --> F[提示用户扣减积分并确认]
    E -- extract --> G[直接执行底层脚本]
    F -- 确认 --> G
    G --> H[调用 scripts/xiaohongshu_tool.py]
    H --> I[请求 ServiceHub 接口 https://www.ccailab.top]
    I --> J[解析 JSON 响应结构]
    J --> K[输出结构化摘要、互动数据与审计单号]

目录结构

skill-xiaohongshu-media-assistant/
├── SKILL.md                 # 技能核心定义文件（Frontmatter、流程规范、决策规则、例句）
├── README.md                # 技能主说明文档
├── INSTALL.md               # 技能安装与手动调用指南
├── .env.example             # 环境变量配置示例
├── .gitignore               # Git 忽略配置（物理隔离凭证与本地缓存）
├── requirements.txt         # Python 依赖清单
├── scripts/
│   └── xiaohongshu_tool.py  # 命令行工具脚本
└── references/
    └── api_spec.md          # ServiceHub 小红书 API 详细规范

凭证安全与隔离规范

为了保证账号安全与凭证隔离，本技能严格遵循以下规则：

禁止硬编码凭证：代码与配置文件中绝不出现真实密码、passtoken 或 API 密钥。
凭证加载优先级：
- 命令行参数：--username, --password
- 专属环境变量：XIAOHONGSHU_MEDIA_ASSISTANT_USERNAME, XIAOHONGSHU_MEDIA_ASSISTANT_PASSWORD
- 共享环境变量：SERVICEHUB_USERNAME, SERVICEHUB_PASSWORD, SERVICEHUB_PASSTOKEN
- 本地凭证文件：data/credentials.json
物理隔离：data/credentials.json 和 .env 已被包含在 .gitignore 中，确保不会提交到版本库。

安装与使用说明

1. 安装依赖

pip install -r requirements.txt

2. 凭证配置

你可以选择通过环境变量配置凭证：

cp .env.example .env
# 编辑 .env 文件，填入你的 ServiceHub 账号与密码

或在首次运行命令行工具时保存凭证：

python scripts/xiaohongshu_tool.py note --url "https://xhslink.com/a/abc123" --username "your_user" --password "your_pass" --save-credentials

3. 命令行调用示例

获取视频笔记原始文案

python scripts/xiaohongshu_tool.py text --url "https://xhslink.com/a/abc123" --type extract

获取博主已发布笔记列表

python scripts/xiaohongshu_tool.py blogger --url "https://www.xiaohongshu.com/user/profile/600000000000000000000000" --type extract --turns 1

获取笔记根评论

python scripts/xiaohongshu_tool.py comment --id "66a000000000000000000000" --type extract --turns 1

获取根评论回复

python scripts/xiaohongshu_tool.py reply --comment-id "66a011110000000000000000" --type extract

核心设计决策

缓存优先策略 (extract)：默认使用 extract 模式读取 ServiceHub 本地数据库缓存，避免产生不必要的积分扣减；仅在显式请求最新数据时启用 update 模式（每次扣减 12.5 积分）。
显式 note_type 分流：小红书接口要求区分图文 (image) 和视频 (video)，技能内部根据用户需求显式分流，保证请求匹配正确的上游接口。
短链防误判处理：xhslink.com 短链统一通过 share_text 参数透传给 ServiceHub，由服务端自动解析真实 note_id 或 user_id。

开源协议

MIT License