XHS Opportunity Kit

把小红书上的潜在线索整理成有来源、有判断依据、可持续跟进的合作机会。

TypeScript SDK + JSON CLI + 标准 stdio MCP 服务 + 通用 Agent Skill。 本地 SQLite 保存状态，支持离线导入与可配置的小红书 MCP 连接。与小红书无官方关联。

第一版覆盖：搜索与详情读取、笔记去重、证据保存、人工/Agent 判断、规则筛选、业务状态记录、JSON/CSV 导出。它不发送消息、不发布内容、不自动接单，也不创建后台定时任务。

安装

需要 Node.js 22.13 或以上。使用 Node 内置 SQLite，无需另外安装数据库。部分 Node 版本会向 stderr 输出 SQLite 实验性提示，stdout 仍是纯 JSON。

安装 GitHub Release 中的已编译包（无需 TypeScript 编译器）：

npm install -g https://github.com/huntingrin/xhs-opportunity-kit/releases/download/v0.1.0/huntingrin-xhs-opportunity-kit-0.1.0.tgz
xhs-opportunity --help
xhs-opportunity doctor

源码开发：

git clone https://github.com/huntingrin/xhs-opportunity-kit.git
cd xhs-opportunity-kit
npm ci
npm test
node examples/quickstart.mjs

目前通过 GitHub 分发，尚未发布 npm registry 包。不要使用 npm install @huntingrin/xhs-opportunity-kit，除非你确认它日后已在 registry 发布。其他 Node 项目可以 npm install <上面的 tgz URL> 后导入同名 SDK。

Related MCP server: X Archive Daemon

任何 Agent 如何使用

CLI 是跨 Agent 的基础入口；Skill 不绑定 Codex、Cola 或特定模型。小红书登录和连接需要由使用者自行配置，不随安装包分发。没有平台连接也能处理已有数据。

五分钟离线演示

仓库中的示例全部为虚构数据。以下命令从仓库根目录执行：

node dist/cli.js collect --db ./demo.sqlite --input examples/collect-file.json
node dist/cli.js list --db ./demo.sqlite
node dist/cli.js export --db ./demo.sqlite --input examples/export-csv.json --output ./demo.csv

输出始终为 { "ok": true, "data": ... } 或 { "ok": false, "error": { "code": ..., "message": ... } }。

• 退出码 0：操作成功；1：错误；3：采集部分完成或失败，检查 data.status/errors/warnings。部分结果已经保存。

• 真实小红书搜索端点没有完整结果范围保证，因此正常采集也可能是 partial。不要把它改报成“全部搜索完成”。

• 重新执行同一采集不会重复新增同一笔记。进程中断后可重跑；已保存数据保留，中断运行可能保留 running 状态，须结合进程状态判断。不会自动重放旧游标。

接入真实搜索

复制 examples/collect-mcp.json，在仓库外填写你实际可访问的 MCP URL。认证令牌通过环境变量传入。也支持 stdio 与 SSE，见 提供器接口。

xhs-opportunity collect --input /path/to/your/collect-config.json

适配器调用 search_feeds 和 get_feed_detail。平台搜索、访问资格、登录和限流由上游工具处理。SDK 不提供账号、浏览器或登录状态，也不保证上游一直可用。

Agent 已经能读取小红书、但不能让本包直接连接同一工具时，可以使用自己的已授权工具收集内容，转换成 标准 Note 数据，调用 import。无需重新实现登录。

MCP 配置

通用配置结构如下，具体放置位置遵循你的 Agent 客户端说明：

{
  "mcpServers": {
    "xhs-opportunity-kit": {
      "command": "xhs-opportunity-mcp",
      "args": ["--db", "/absolute/path/to/opportunities.sqlite"]
    }
  }
}

如客户端找不到全局可执行文件，可用 node 配合已构建项目的绝对路径 dist/mcp-server.js。需要 MCP 工具直接采集时，在启动参数增加 --provider /absolute/path/to/provider.local.json。配置只包含 provider 对象，示例见 examples/provider-mcp.json。

证据和状态

• 筛选等级 priority / pending / excluded 与业务阶段 discovered / contacted / requirements_review / accepted / delivered / closed 分开保存。

• review 必须引用 show 返回的证据 ID。未知预算、未知 AI 接受度不会自动判为符合要求。

• 原帖内容更新会标记 reviewStale；规则筛选不继续使用过期判断。

• stage 仅记录已发生的事实，不会真的联系客户或交付文件。

• 从旧的 lead-delivery.json 导入时，旧结论保存为历史证据，进入待复核状态，不当成当前有效客户。

• 搜索卡片不会覆盖已有详情。时间、评论覆盖范围、部分失败会保留。

数据与依赖

默认数据库放在系统用户数据目录下的 xhs-opportunity-kit/，不写入安装目录。可用 XHS_OPPORTUNITY_DATA_DIR 或 --db 指定。doctor 不验证平台登录。

本包只保存规范化字段，不保存原始响应中的 Cookie、访问令牌或带签名的 URL。正文、作者与评论仍可能包含个人信息，属于你的本地数据；导出前按你的使用场景审阅。示例、测试与发布包不含真实账户、线索或运行资料。

现有截图表格中的图像文字可由宿主 OCR 后作为 image_text 证据导入。本版没有内置 OCR、LLM、私信收发、邮件轮询、网页界面或 Excel 排版引擎；这些可以通过适配器或上层应用扩展。

文档与维护

• CLI 请求和错误契约

• SDK、数据模型和状态转换

• 连接适配器与兼容边界

• English quick start

• Agent Skill

npm run check
npm test
npm pack

合成测试覆盖核心业务行为、CLI 子进程和真实 MCP 协议连接。CI 验证 Linux / macOS / Windows 与多个 Node 版本。线上功能是否可用仍取决于使用者的 MCP 服务与平台会话。MIT License。