Listing巡检Skill安装与使用教程

Listing 巡检 Skill 安装教程:从下载,到收到第一张飞书告警

前一篇《如何用 Skills 做 Listing 每日巡检》讲了需求和技术方案。这一篇把安装步骤单独写清楚:拿到分享包以后,怎样在自己的电脑上使用,怎样接入自己的店铺,又怎样确认它确实查完了。

这套 Skill 用领星 Open API 查询 Listing 和运营日志,监控评分、差评、购物车以及父体成员变化,生成中文巡检报告,并可以通过飞书群机器人发送告警。赛狐是可选的评价数据来源。

安装完成,只代表 AI 能找到这套工具。真正开始巡检,还需要你自己的平台权限、监控清单和运行配置。

本文以 Codex 本地使用为例。先手动跑通一轮,核对报告,再启用真实通知;每天自动执行的计划任务,最后单独配置。

本文按实际动手顺序展开:获取领星与飞书凭据、设置白名单 → 下载 ZIP → 交给 Codex 安装并生成 .env → 自己填写凭据 → 让 Codex 自检 → 确认监控清单 → 联网验证 → 首次巡检 → 飞书通知。

版本说明
本文对应 20261008 分享包。告警规则与功能边界以包内 SKILL.md 和代码为准;之前的技术方案、直播演示可能使用不同版本的规则。

一、先获取领星、飞书凭据并设置白名单

要准备什么 用来做什么 是否必需
能执行本地命令的 Codex 环境 读取 Skill,调用本机程序,解释结果 本文使用方式需要
Python 3.9 及以上 执行包内程序 必需
领星开放平台 AppId、AppSecret 调用领星 Open API 必需
领星允许的出口 IP 通过平台 IP 白名单检查 必需
飞书群机器人 Webhook、签名密钥 发送告警;当前环境自检也要求配置成对存在 必需
自己的店铺、站点和 ASIN 清单 确定检查范围 必需
赛狐有效登录认证 补充评价数量变化与中差评净增加判断 可选

这里最容易卡住的是领星权限。能登录领星后台,不代表已经取得开放平台应用凭据和所需接口权限。 AppId、AppSecret 也不能用文档访问密钥代替。

飞书需要的是开启签名校验的群自定义机器人。Webhook 与签名密钥配套使用,不能拿飞书自建应用的 AppId、AppSecret 填进这两个字段。

第一次测试,可以先建一个用于验证的飞书群,避免测试消息和正式运营通知混在一起。

这一章只完成平台侧的准备:获取领星 AppId、AppSecret,配置公网 IP 白名单,创建飞书机器人并获取 Webhook 和签名密钥。先准备好这些信息,暂时不创建本机目录,也不填写 .env。第二章下载 ZIP,第三章把压缩包交给 Codex,由它安装 Skill、准备环境并生成 .env;第四章再填写凭据并自检。

1.1 获取领星 AppId 和 AppSecret

使用企业的超级管理员账号登录领星 ERP,按下面的路径进入:

设置 → 业务配置 → 全局 → 开放接口 → 进入开放后台。

首次开通时,按页面提示填写接收开放平台通知的邮箱;进入开放后台后,在 API 信息中查看企业的 AppID 和 AppSecret。如果普通账号看不到入口,先找企业超级管理员处理。

这两个值稍后分别填写到 .env 的以下字段:

LINGXING_APP_ID=复制领星API信息中的AppID
LINGXING_APP_SECRET=复制领星API信息中的AppSecret

不要填领星登录密码、临时 access token 或接口文档访问密钥。 这里需要的是企业开放平台应用凭据,程序会使用它们获取调用接口所需的 token。

image.png

image.png

操作入口参考 领星官方:API 信息的查询与配置。界面调整时,以自己账号里的实际菜单为准。

1.2 查询公网 IP,配置领星白名单

仍在领星 ERP 的 设置 → 业务配置 → 全局 → 开放接口页面,找到 IP 白名单配置,加入实际运行巡检程序的公网出口 IP并保存。领星要求应用凭据和 IP 白名单同时配置。领星官方接入说明

在运行程序的电脑上,可以打开 领星公网 IP 查询工具 查看当前浏览器的出口地址。如果程序使用服务器、代理或与浏览器不同的网络路径,要以程序实际访问领星时的出口 IP 为准。

[!tip] 不知道自己的公网 IP?按这三步操作 适用于在自己的电脑上直接运行巡检,且程序与浏览器使用同一网络出口的情况。

  1. 在准备运行巡检的电脑上,点击 领星官方公网 IP 查询工具,不用安装软件。
  2. 复制页面显示的 IP 地址。如果页面显示的是一段文字或 JSON,只复制其中的 IP,不要把引号、括号或整段内容一起复制。
  3. 打开领星「设置 → 业务配置 → 全局 → 开放接口」,将这个 IP 填入白名单并保存。

换了 Wi-Fi、网络或代理后,公网 IP 可能变化,需要重新查询。 如果巡检跑在服务器上,或者程序与浏览器使用不同代理,应让负责部署的人核实程序实际使用的出口 IP。

image.png

不要填写 127.0.0.1 或路由器分配的局域网地址。换网络、换服务器或更换代理出口后,也要重新核对白名单。

IP 白名单是在领星后台保存的,不是往 .env 里随意增加一个 IP 字段。 本 Skill 的代理配置是可选项;没有配置代理时,按程序直接联网的出口核对。

image.png

1.3 创建飞书群机器人,复制 Webhook

在飞书桌面端打开准备接收告警的群,进入:

群右上角菜单 → 设置 → 群机器人 → 添加机器人 → 自定义机器人。

填写机器人名称,例如「Listing 巡检提醒」,然后点击添加。创建完成后复制它的 Webhook 地址。已经建过机器人,则回到「群机器人」列表,点击对应机器人查看配置。飞书官方:在群组中使用机器人

复制完整地址,稍后填入 .env 的这个字段:

FEISHU_WEBHOOK_URL=复制这个群机器人的完整Webhook地址

它的地址形式通常是:

https://open.feishu.cn/open-apis/bot/v2/hook/你的机器人标识

这里要填完整网址,不能只填最后一段标识,也不能填群邀请链接。选择的是群里的自定义机器人,不需要为了这套 Skill 另外创建飞书自建应用。

image.png

image.png

1.4 开启飞书签名校验,复制密钥

进入刚才那个自定义机器人的配置页面,在「安全设置」中开启 签名校验,复制界面提供的密钥,并保存设置。具体入口可对照 飞书官方:自定义机器人使用指南。

复制密钥,稍后填入 .env 的这个字段:

FEISHU_WEBHOOK_SECRET=复制同一个机器人签名校验中的密钥

Webhook 和签名密钥必须来自同一个机器人。 不能用 A 群机器人的地址,配上 B 群机器人的密钥。更换或重置密钥后,也要同步更新自己的 .env。

当前 Skill 采用签名群机器人发送,因此只复制 Webhook、漏填签名密钥,环境自检会不通过。签名由程序生成,你只需要保存机器人提供的密钥,不用自己计算。

二、下载 ZIP,保持压缩包原样

+联系博主获取Skill 😀

下载后不用自己解压,也不用手动创建 Skill 目录或移动文件。 把 ZIP 保存在电脑上,下一步将文件的本地路径交给 Codex,让它完成安装。

分享包已经包含完整的 SKILL.md、Python 程序、配置模板和参考资料,不需要从里面单独取出任何文件。它不包含我的账号或运行数据,安装后填写你自己的凭据即可。

压缩包里的主要文件如下,了解用途即可,解压和安装仍交给 Codex 处理:

lingxing-listing-alert-monitor/
├── SKILL.md                       # 给 Codex 的工作说明:何时使用、按什么步骤执行
├── README.md                      # 安装步骤、使用方法和常见问题
├── .env.example                   # 空配置模板,安装后生成你自己的 .env
├── expected-targets.example.json  # 监控清单模板:店铺、站点和 ASIN 等
├── requirements.txt               # Python 依赖清单,由 Codex 安装
├── agents/                        # Skill 的显示名称和默认提示语
├── scripts/                       # 实际执行采集、判断、报告和飞书发送的程序
├── references/                    # 接口说明、告警规则和其他参考资料
└── migrations/                    # 本地数据库的初始化文件

.env.example 是不含真实凭据的模板。 你填写的 .env 和运行数据会放在 Skill 目录之外,后续升级 Skill 时可以继续保留。

三、把 ZIP 交给 Codex,让它安装并生成 .env

在能访问这个 ZIP 的 Codex 本地聊天中,提供压缩包的完整路径。最简单可以直接说:

帮我安装一下 xxxx.zip (这里粘贴压缩包的路径)

image.png

希望它一次完成安装、准备环境和生成配置模板,可以直接复制下面这段:

请帮我安装这个 Listing 巡检 Skill:
ZIP 路径:[在这里粘贴下载好的 ZIP 完整路径]

请由你解压并检查包内文件,将完整 Skill 安装到当前 Codex 能识别的技能目录,
确认可以找到 lingxing-listing-alert-monitor,并读取其中的 SKILL.md 和 README.md。
如果已有同名 Skill,先说明版本情况,备份旧版,不要混用新旧文件。

安装完成后,请继续准备本机环境:
1. 检查 Python 环境,在独立虚拟环境中安装包内依赖。
   如果缺少 Python,请告诉我怎么安装,等环境可用后再继续。
2. 在当前用户主目录下建立 listing-monitor 运行目录,放在 Skill 目录之外。
3. 从包内 .env.example 复制 .env 到运行目录。
   已存在的目录或配置文件保留原内容,不要覆盖。
4. 按实际路径填好 LISTING_MONITOR_DB,但暂时不要创建数据库。
5. 打开 .env,并告诉我文件在哪里,让我自己填写领星 AppId、AppSecret、
   飞书 Webhook 和签名密钥;不要在聊天中展示真实凭据。

先停在安装及空配置模板准备完成,等我填好并保存 .env 后再执行自检。
不查询店铺、不初始化数据库、不发送飞书、不创建定时任务。

image.png

这里的解压、安装、建目录和生成模板,都由 Codex 完成。你需要确认的结果是:Skill 已被识别,而且 Codex 已打开或给出了 .env 文件的位置。

如果 Codex 提示找不到 ZIP,先确认提供的是这台运行电脑上真实存在的文件路径;如果安装完成但技能没有显示,可以重启 Codex 后再让它检查。安装目录和发现机制参考 OpenAI 官方 Skills 文档。

如果 Codex 实际运行在 WSL 或远程电脑上,让它先确认 ZIP、Python 和运行目录都处于该执行环境中,不要把不同电脑的文件路径混用。

四、填写 .env,保存后让 Codex 检查

4.1 填入领星、飞书凭据

Codex 已在上一章完成安装,并生成或找到你的 .env。现在只需要在它打开的文件里,填写第一章获取的领星和飞书凭据。

不用自己创建目录或规划文件结构。 以 Codex 给出的 .env 完整路径为准;编辑的是运行目录里的 .env,不是 Skill 包内的 .env.example。保存时不要改成 .env.txt。

在运行目录的 .env 中,填入第一章获取的凭据。LISTING_MONITOR_DB 使用 Codex 根据本机运行目录确定的绝对路径:

LINGXING_APP_ID=填写自己的领星AppId
LINGXING_APP_SECRET=填写自己的领星AppSecret
FEISHU_WEBHOOK_URL=填写自己的飞书机器人Webhook
FEISHU_WEBHOOK_SECRET=填写自己的飞书签名密钥
LISTING_MONITOR_DB=填写运行目录中listing-monitor.sqlite的绝对路径

上面是字段说明,前四项填自己的真实凭据。LISTING_MONITOR_DB 由 Codex 按实际目录填写,保留它生成的绝对路径,不要用上面的中文占位文字覆盖。

image.png

领星凭据和飞书凭据分别来自自己的平台配置。完整 Cookie、Webhook、AppSecret 不需要贴进文章、群聊或公开截图。

4.2 核对字段与来源

.env 字段 从哪里获取 容易填错的地方
LINGXING_APP_ID 领星开放后台的 API 信息 不要填文档访问密钥
LINGXING_APP_SECRET 同一企业应用的 AppSecret 不要填登录密码或临时 token
FEISHU_WEBHOOK_URL 目标飞书群中自定义机器人的 Webhook 要完整地址,不是群链接
FEISHU_WEBHOOK_SECRET 同一机器人开启签名校验后的密钥 不要与其他机器人的密钥混用
LISTING_MONITOR_DB 自己的外部运行目录中 SQLite 文件的绝对路径 这是本机文件路径,不从领星或飞书获取

填完后保存 .env,再进入 4.3 做环境自检,检查程序能否正确读取配置。截图只用来说明入口和字段,真实凭据保留在自己的本机配置里。

4.3 保存后,让 Codex 自检

确认 4.1 的 .env 已填写并保存后,可以对 Codex 说:

我已填好并保存运行目录中的 .env。
请使用该文件执行 setup_check.py 环境与配置自检,不展示凭据内容。
通过后告诉我结果;未通过就说明缺少什么,先不要进入采集或发送。

这一步不联网、不写数据库。输出里 ready: true 表示本地配置检查通过;不通过就按 next_steps 补齐。

image.png

环境自检通过,还不代表领星接口和店铺数据已经验证成功。 联网验证在后面单独做。

后面章节中的命令示例用于说明程序实际执行什么,可以继续让 Codex 按包内 README 运行,不需要自己打开终端逐条输入。执行环境、依赖和具体文件路径由 Codex 根据本机安装结果处理。

五、确认监控清单,再初始化本地账本

先从一个店铺、少量商品开始,容易核对结果。

清单里几个字段要分清:

字段 应当填写什么
sid 领星授权店铺列表中的店铺 ID,不是 Amazon Seller ID
marketplace_id Amazon 站点编号,需要与该店铺对应
target_type 子体填 ASIN;父体填 PARENT_ASIN
target_value 实际要监控的子 ASIN 或父 ASIN
business_level 按自己的业务确认 CORE 或 NORMAL
notify_chat_id 按当前签名群机器人方式配置,包内示例为 WEBHOOK

父体监控与子体监控,检查的内容不同。 配置父 ASIN,主要用于比较成员名单;要检查某个子体的评分、评价或购物车,还需要把那个子 ASIN 显式加入清单。

此外,expected-targets.json 是用于核对范围的清单,只编辑这个文件,不会自动把对象写进数据库。还需要初始化外部 SQLite,再逐个配置已确认的目标,最后对账。

可以把自己的目标清单给 Codex,并附上:

请将我的目标整理成 expected-targets.json,并展示完整清单。
不要沿用分享包里的示例店铺 ID 和 ASIN。

先核对 sid、站点、父子 ASIN 类型及业务等级。
把要写入的 SQLite 绝对路径、目标数量和对象列给我确认。
确认后,仅在这个本地运行目录内初始化数据库、配置这些目标并执行对账。
不修改平台商品,不发送飞书。

包内 README.md 提供了 init-db、configure-target 与 preflight.py 的具体命令。让 AI 按说明操作即可,但对象有歧义时,要先把清单说清楚。

数据库与清单出现差异时,先看缺了谁、多了谁、哪个字段不一致。不要为了让检查通过,就把不知道用途的对象自动新增或停用。

六、联网预检:确认账号和商品真的能查到

本地配置和对象对账完成后,再运行接口验证:

python scripts/preflight.py \
  --env-file "$HOME/listing-monitor/.env" \
  --db "$HOME/listing-monitor/listing-monitor.sqlite" \
  --expected-targets "$HOME/listing-monitor/expected-targets.json" \
  --probe-api \
  --verify-provider-targets

这一步会实际联网,核对授权店铺、目标商品与接口能力;配置了赛狐时,还会检查相应接口。使用前先确认本次清单就是自己要检查的范围。

只有必要检查通过,才能进入正式采集。出现 ERROR 时,先看原因:是账号权限、出口 IP、店铺编号,还是商品不在返回范围内。

鉴权失败,不能解释成“商品不存在”;缺页,也不能解释成“父体少了一个子体”。

不配置赛狐是允许的,会明确标记跳过或降级。已经配置赛狐却认证失效,则需要修复配置,不能忽略错误继续当作完整检查。

七、第一次巡检:先决定历史变化怎么处理

首次运行前,有一个业务选择需要自己做。

首次策略 会发生什么 适用考虑
正常巡检,暂不发送 采集、保存变化、生成报告,并保留符合规则的待发告警 希望看到并保留当前查询窗口内的告警
使用 --baseline-only 建立基线 保存状态、快照和审计记录,不创建基线期告警待发项 明确决定首次接入时不生成历史存量告警

“这次不发送”和“这次不生成告警”,是两件事。 正常巡检即使不加发送参数,也可能留下待发记录,之后启用发送时仍需检查这些记录。

不要因为是第一次使用,就默认加上 --baseline-only。它要求账本尚无运行历史,而且不能和 --send-alerts 一起使用。

如果选择正常巡检、先看报告,执行:

python scripts/run_daily.py \
  --env-file "$HOME/listing-monitor/.env" \
  --db "$HOME/listing-monitor/listing-monitor.sqlite" \
  --expected-targets "$HOME/listing-monitor/expected-targets.json"

这条命令会联网采集并写入本地 SQLite,不发送飞书。日巡检入口本身还会执行完整的五步检查,不会因为之前预检过就跳过本次验证。

如果已经明确选择仅建立基线,在同一条命令末尾增加 --baseline-only。

第一次拿到父体的完整名单,只能作为后续比较的参照。没有更早的完整记录,不能推断之前移除了哪个成员。

报告出来以后,先看这四件事

  • **范围:**计划查哪些店铺和商品,实际完成了多少,有没有失败对象。
  • **证据:**前后值、业务日期、父体成员变化是否能核对。
  • **状态:**零告警是检查完整后的结果,还是部分数据没有查到。
  • **通知:**这轮是否跳过发送,有多少条待发事件、多少个合并提醒。

让 Codex 输出中文报告即可,不必自己逐条读 JSON:

请根据这次实际运行结果,给我一份中文巡检简报。
写清检查范围、完成与失败对象、发现的变化、优先级、待发通知和下一步建议。
区分原始事件数与合并提醒数。
未查到或未完成的部分如实说明,不要推断全部正常。

八、报告核对完成,再验证飞书通知

建议先让 Codex 用包内的 send_test_card.py 生成一张测试卡片,核对预览后再明确授权发送。这个测试使用模拟变化,不代表已经采集到真实业务异常。

可以这样说:

请先用这个 Skill 的 send_test_card.py 生成一张 P1 测试卡片预览,使用 --dry-run。
测试卡片只用于检查格式和发送通道,不代表真实业务异常。
说明将使用哪份本机飞书配置,不显示 Webhook 或密钥。
等我核对后,再发送一张带“测试”标记的卡片。

测试脚本从进程环境读取飞书凭据,不支持 --env-file 参数。让 Codex 按包内代码读取已有外部配置并注入进程环境,不要把真实凭据拼进公开命令。

测试卡片确认送达后,如果要发送正式业务告警,先查看待发范围和卡片预览,再明确授权。正式日巡检命令增加 --send-alerts 后,才会进入真实发送:

python scripts/run_daily.py \
  --env-file "$HOME/listing-monitor/.env" \
  --db "$HOME/listing-monitor/listing-monitor.sqlite" \
  --expected-targets "$HOME/listing-monitor/expected-targets.json" \
  --send-alerts

这条命令会真的通知已配置的飞书群。 它也可能处理之前未发送的待发记录,所以不要把它当成“只发刚才屏幕上那一条”的按钮。

如果网络超时、结果不明确,先核对群消息和发送记录,再决定怎么处理,避免盲目重复发送。

当前包的主要分级如下,首次使用时可以拿自己的业务例子核对:

变化 当前规则
明确丢失购物车 P0
购物车卖家变化 核心链接 P0,普通链接 P1
评分下降、新增 1~3 星差评、中差评数量净增加 P1
父体移除或替换成员 P1
父体仅新增成员 P2
显式开启通知后的评分上升 P3

九、赛狐与每日自动运行,可以后面再加

赛狐是可选项,领星是必需项。 先用领星跑通,再决定是否需要补充评价数量数据。

接入赛狐时,按包内 references/sellfox-web-api.md 导入登录后的查询 cURL,认证文件放到自己的运行目录,通过 SELLFOX_AUTH_FILE 指定。导入后重新做环境自检和接口验证。

Cookie 会过期。没有配置赛狐时,报告会说明评价数据仅来自领星,中差评净增加告警不可用;配置后认证失效,要按报错更新认证。如果采集阶段才发生失败,当前流程会记录降级原因,不能把降级结果描述成评价已完整核对。

定时执行也建议放在手动验收之后。先确认每日运行时间、业务时区、目标清单、数据库路径和真实发送范围,再安排计划任务。

安装 Skill 不会自动创建定时任务,每天运行一次也不等于实时监控。 运行环境需要在计划执行时可用,接口凭据和网络也需要正常。

十、常见问题,先按这个顺序排查

现象 优先检查什么
Codex 找不到 Skill 安装目录、是否多套一层文件夹、Skill 是否在实际运行的电脑上;必要时重启
.env.example 看不见 文件以点开头,可能被文件管理器隐藏;用终端或显示隐藏文件查看
缺少 Python 依赖 确认安装依赖与执行脚本使用同一个虚拟环境
ready: true,但采集失败 本地自检不等于接口验证通过,继续看联网预检结果
领星鉴权或访问失败 AppId、AppSecret、出口 IP 白名单、接口权限
提示目标与清单不一致 是否只编辑了 JSON、没有配置数据库目标;店铺、站点与父子类型是否一致
父体第一次没有成员变化提醒 没有更早的完整快照时,先建立参照是正常行为
有报告但飞书没消息 是否跳过发送、是否存在可告警事件、是否有投递失败;不要先认定程序没运行
配置赛狐后预检失败 登录认证是否有效,更新认证后重新验证
换目录后报路径错误 .env、认证文件、数据库和可选运行约束文件是否仍指向旧绝对路径

升级 Skill 时,保留自己的外部运行目录和数据库,再替换源码。不要为了“重新开始”按天建新账本,否则之前保存的状态和去重记录无法自然衔接。

安装是否完成,最终看三件事:Codex 能识别技能,自己的清单能完成一次有证据的巡检,授权后的测试卡片能送达。 这三步核对清楚,再逐步增加商品、数据来源和运行频率。