Listing巡检Skill安装与使用教程
- AI 自动化工作流
- 2026-10-12
- 356热度
- 0评论
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。


操作入口参考 领星官方:API 信息的查询与配置。界面调整时,以自己账号里的实际菜单为准。
1.2 查询公网 IP,配置领星白名单
仍在领星 ERP 的 设置 → 业务配置 → 全局 → 开放接口页面,找到 IP 白名单配置,加入实际运行巡检程序的公网出口 IP并保存。领星要求应用凭据和 IP 白名单同时配置。领星官方接入说明
在运行程序的电脑上,可以打开 领星公网 IP 查询工具 查看当前浏览器的出口地址。如果程序使用服务器、代理或与浏览器不同的网络路径,要以程序实际访问领星时的出口 IP 为准。
[!tip] 不知道自己的公网 IP?按这三步操作 适用于在自己的电脑上直接运行巡检,且程序与浏览器使用同一网络出口的情况。
- 在准备运行巡检的电脑上,点击 领星官方公网 IP 查询工具,不用安装软件。
- 复制页面显示的 IP 地址。如果页面显示的是一段文字或 JSON,只复制其中的 IP,不要把引号、括号或整段内容一起复制。
- 打开领星「设置 → 业务配置 → 全局 → 开放接口」,将这个 IP 填入白名单并保存。
换了 Wi-Fi、网络或代理后,公网 IP 可能变化,需要重新查询。 如果巡检跑在服务器上,或者程序与浏览器使用不同代理,应让负责部署的人核实程序实际使用的出口 IP。

不要填写 127.0.0.1 或路由器分配的局域网地址。换网络、换服务器或更换代理出口后,也要重新核对白名单。
IP 白名单是在领星后台保存的,不是往 .env 里随意增加一个 IP 字段。 本 Skill 的代理配置是可选项;没有配置代理时,按程序直接联网的出口核对。

1.3 创建飞书群机器人,复制 Webhook
在飞书桌面端打开准备接收告警的群,进入:
群右上角菜单 → 设置 → 群机器人 → 添加机器人 → 自定义机器人。
填写机器人名称,例如「Listing 巡检提醒」,然后点击添加。创建完成后复制它的 Webhook 地址。已经建过机器人,则回到「群机器人」列表,点击对应机器人查看配置。飞书官方:在群组中使用机器人
复制完整地址,稍后填入 .env 的这个字段:
FEISHU_WEBHOOK_URL=复制这个群机器人的完整Webhook地址
它的地址形式通常是:
https://open.feishu.cn/open-apis/bot/v2/hook/你的机器人标识
这里要填完整网址,不能只填最后一段标识,也不能填群邀请链接。选择的是群里的自定义机器人,不需要为了这套 Skill 另外创建飞书自建应用。


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 (这里粘贴压缩包的路径)

希望它一次完成安装、准备环境和生成配置模板,可以直接复制下面这段:
请帮我安装这个 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 后再执行自检。
不查询店铺、不初始化数据库、不发送飞书、不创建定时任务。

这里的解压、安装、建目录和生成模板,都由 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 按实际目录填写,保留它生成的绝对路径,不要用上面的中文占位文字覆盖。

领星凭据和飞书凭据分别来自自己的平台配置。完整 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 补齐。

环境自检通过,还不代表领星接口和店铺数据已经验证成功。 联网验证在后面单独做。
后面章节中的命令示例用于说明程序实际执行什么,可以继续让 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 能识别技能,自己的清单能完成一次有证据的巡检,授权后的测试卡片能送达。 这三步核对清楚,再逐步增加商品、数据来源和运行频率。
