shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 数据与分析需要 API Key

QINLU.AI 灵犀数据下载

QINLU.AI 灵犀数据下载——小红书灵犀数据采集封装技能，帮助用户授权后自动采集数据用于本地分析，当用户要采集/下载/获取灵犀数据时触发。

person作者: u_013c9eb8hubenterprise
download下载资源包

灵犀数据下载

QINLU.AI 灵犀数据下载——小红书灵犀数据采集。当用户要采集/下载/拿灵犀数据，或提到灵犀账号（有哪些账号、绑定品牌、登录态/账号失效）时触发：绑定品牌账号、提交采集任务、等待完成、下载归档到本地。

给执行 agent：命令相对本文件所在目录（scripts/ 即 skill/scripts/）；每个脚本末行输出 __RESULT__:{json}，以它判成败；命令自己跑，不对用户展示。

行为规范

  1. 不向用户介绍过多的技术细节，而是直接帮用户干活
  2. 全程用人话向用户汇报进度，不输出命令和参数
  3. 不要尝试阅读代码, 仅可阅读 references 目录下的文档，按需读取，帮助理解

一句话：非必要不向用户咨询问题，而是直接执行脚本命令响应用户请求。bind 会开浏览器，执行前征得用户同意。

初始化

  1. 首次需要进行绑定
  2. 需要安装nodejs环境
  3. 需要playwright

典型工作流

  1. 仅需要进行数据解读（用户只要结论/分析，没要下载数据）：直接阅读 references/data-map.md，了解数据结构，按需读取 ~/.ai-shared/data/ 下已有数据做出即可；仅当数据不满足分析需要时，才进行数据下载
  2. 需要下载数据（用户主动要求下载，或数据无法达到需求）：本地已有同日期数据不是跳过的理由（云端是唯一真相，重新拉取幂等），照常走下载链路：
    • 首次使用：configure（平台授权）→ bind（绑定品牌账号，登录哪个品牌就绑定哪个）
    • 日常采集：list 拿品牌名 → 查 references/data-map.md 选模块（模块名/类目/SPU 都不猜）→ categories <品牌> 拿真实类目（SPU 模块改用 spus）→ 把 config JSON 写成临时文件（放系统临时目录，不落 workspace 根，用完即删）→ create --brand=<品牌> --config-file=<绝对路径> → poll <task_id> → download <task_id> --account=<品牌>

命令目录

lingxi-account.js — 灵犀品牌账号

| 命令 | 入参 | 作用 | |---|---|---| | list | 无 | 列已绑定品牌——判断绑定态的唯一途径，必须跑这条命令，禁止直接翻 ~/.ai-shared/accounts/ 目录作答（目录混有其他平台账号，也看不出登录态是否有效；已绑品牌只能来自这里或 bind 的识别结果） | | status | [品牌] | 登录态联网探活，出参 active / invalid / error | | bind | [品牌名] | 开浏览器登录灵犀，登录哪个品牌就绑定哪个；绑新品牌且本地已绑其他品牌时，必须带上目标品牌名（阻塞最多 5 分钟，见「阻塞等待契约」） | | spus | <品牌> | 列真实 SPU 名（SPU 模块入参只能来自这里） | | categories | <品牌> | 列真实类目 [{code,name,path}]（category 的 code 只能来自这里） | | remove | <品牌> | 删除该品牌绑定文件 |

qinlu-account.js — 平台授权

| 命令 | 入参 | 作用 | |---|---|---| | configure | 无 | 平台 apiKey 授权（首次使用，或提示"还没完成平台授权/授权已失效"时运行；已授权秒过，无则开浏览器确认授权） | | status | 无 | 检查授权是否还有效 | | remove | 无 | 清除授权 |

lingxi-download.js — 采集

| 命令 | 入参 | 作用 | |---|---|---| | create | --brand=... --config-file=... | 创建任务（自检全过才提交）；config 文件是唯一入口（v1.1.0 起不支持内联） | | poll | <task_id> | 轮询到 done/failed/超时（默认 --timeout=600 --interval=8，秒） | | download | <task_id> [--account=...] [--from/--to=YYYY-MM-DD] | 下载 zip 按日期归档；--account 传 create 时的品牌名（可选，默认全部已完成账号）；--from/--to 按日期预筛 | | list | [--brand=...] | 列任务 | | result | <task_id> | 看结果清单（不下文件） |

config 内容是 dates + selection（dates 最晚到 T-2），外加可选顶层字段 intent（字符串）= 用户下载数据的原始诉求，随任务透传给平台，不填就不带（>500 字符截断）。intent 不是命令行旗标，--intent 已移除，要写进 config 文件顶层：

{"dates":["2026-08-01"],"selection":{"namespaces":["business.trend"],"category":[{"code":"…","name":"…"}],"spus":["…"]},"intent":"可选：用户下载数据的原始诉求"}

数据地图

references/data-map.md：每个模块（ns）的归属维度、产出路径、文件清单、关键字段——create 前必查；references/namespaces.md 是模块词汇表与入参门控（何时需要 category/spus），references/output-tree.md 是产物目录结构索引。

错误路由

脚本每条结果的末行都带明确的错误提示（error + remedy），remedy 本身就是可执行的修复动作，照做即可：

| 类别 | 触发条件 | 走 remedy | |---|---|---| | 授权 | unauthorized / no-api-key / unauthorized-cookie / token-invalid / device-request-failed / already-claimed | 重跑 configure（引导用户重新授权） | | 绑定 | brand-unbound / brand-not-found / brand-not-detected / no-category-tree / waf-blocked | 征得同意后 bind；先 list 看已绑品牌 | | 参数 | category-format / missing-* / unknown-namespace / date-beyond-t2 / invalid-date* / intent-not-flag / invalid-intent / config-file-* / use-config-file | 按提示修 config 或跑对应命令拿真实值 | | 网络/浏览器 | cloud-unreachable / create-failed / playwright-not-installed / chrome-not-found / chromium-missing / browser-launch-failed / browser-crashed / login-timeout | 检查网络 / 装浏览器 / 设 LINGXI_BROWSER=bundled | | 下载/解压 | no-done-accounts / account-not-found / extract-failed / extract-no-dates | 等 poll 到 done 再下 / --account 传品牌名 / 重跑 download（云端是唯一真相，数据可重新拉取） |

date-beyond-t2：灵犀只能拿到 T-2（今天往前数两天）之前的数据，自动调整时间范围后重试。

数据放在哪（共享凭证目录）

统一共享根 ~/.ai-shared/（独立于任何 skill 安装目录，多平台 SDK 共用；旧根 ~/.qinlu-ai-data/、~/.lingxi-data-tool/ 由脚本自动迁移）：

~/.ai-shared/
├── config.json                        ← 共享平台凭证（apiKey + cloudBase），所有 SDK 共用
├── accounts/{品牌}/{平台}/             ← 品牌凭证：cookie.json / brand-info.json / spus.json / main-category.json
├── browser-profile/                   ← configure 持久 profile
└── data/{品牌}/{平台}/{日期}/          ← 采集数据（灵犀的平台段是 lingxi，落点 ~/.ai-shared/data/{品牌}/lingxi/{日期}/）

下载完成后要向客户汇报本次数据的具体路径。解读类诉求可直接使用本地已有数据、告知位置即可，不必重复采集。

阻塞等待契约

所有 CLI 退出只认 stdout 末行的 __RESULT__，不认 stderr 心跳，不认浏览器是否关闭。

| 命令 | 最长阻塞 | 阻塞期间 stderr 会打什么 | 完成标志 | |---|---|---|---| | bind | 5 分钟 | ...仍在等待登录（已等待 Ns）（每 15s） | __RESULT__（含 brand） | | configure | 数分钟 | 浏览器 UI 操作提示 | __RESULT__ | | poll | 默认 600 秒（--timeout 可调） | [Ns] status=... accounts=[...] | __RESULT__（done/failed/timeout） | | 其余命令 | 秒级 | 自检日志 / 进度行 | __RESULT__ |

  • stderr 心跳只是进度播报，不代表脚本已退出；浏览器窗口关闭也不算（先见 __RESULT__、后见关窗）
  • 不要设短超时：bind 5 分钟、configure 走授权流可能更久、采集任务几分钟到几十分钟（看数据量）——至少等 10 分钟，请勿中断
  • 超过 10 分钟仍无 __RESULT__：看 stderr 末尾有无 browser-crashed / login-timeout / cloud-unreachable，按 remedy 处理后重跑

支持

如使用中遇到问题，欢迎咨询 kezy@enbrands.com