| name | jushuitan-inventory-query |
| description | 当需要查询聚水潭主库存或虚拟库存时使用。本技能通过 HTTP 调用后端服务完成查询,支持按商品名称、SKU、款式编码进行查询。
|
聚水潭库存查询工具 (Jushuitan Skill)
简介
本技能用于执行聚水潭库存相关的只读查询,当前仅包含以下两类能力:
本技能通过 HTTP 调用 jushuitan-skill-service 后端服务获取原始数据,由客户端脚本完成 markdown 渲染输出。
核心调用入口:
- 技能注册表:
scripts/registry.py
- 主库存脚本:
scripts/tools/query_inventory.py
- 虚拟库存脚本:
scripts/tools/query_virtual_stock.py
环境准备
首次使用前需在 scripts/ 目录下初始化 Python 环境:
cd scripts
uv sync
如未安装 uv,先执行:
- macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
- Windows:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
初始化完成后,使用 .venv 中的 Python 执行工具脚本。
使用原则
使用本技能时,应遵循以下原则:
- 应优先调用固定包装脚本,不应直接手写 API 调用。
- 应根据查询目标选择对应脚本,不应将主库存和虚拟库存逻辑混用。
- 应仅使用脚本已封装的查询方式:商品名称、SKU、款式编码。
主库存查询
主库存查询脚本为 scripts/tools/query_inventory.py。
适用场景:
- 查询指定 SKU 的主库存
- 查询指定款式编码
i_id 的主库存
- 查询指定商品名称的主库存
- 查询
实际库存、库存锁定数、订单占有数、采购在途数、剩余可用
命令示例:
以下命令默认在 skills/jushuitan-inventory-query/ 目录下执行。
python scripts/tools/query_inventory.py --sku-ids 6974318532161,6974318532147
python scripts/tools/query_inventory.py --i-ids KQ26043,KQ26044
python scripts/tools/query_inventory.py --names 小森林翻翻帽,甜粉小番茄
可选参数:
--page-index
--page-size
--timeout
--json
使用限制:
- 必须且只能提供一种查询条件:
--sku-ids / --i-ids / --names
page_size 最大值为 100
主库存输出字段:
SKU ID
款式ID
颜色/规格
实际库存
库存锁定数
订单占有数
采购在途数
进货仓库存
剩余可用
虚拟库存查询
虚拟库存查询脚本为 scripts/tools/query_virtual_stock.py。
适用场景:
- 查询指定 SKU 的虚拟库存
- 查询指定款式编码
i_id 对应的虚拟库存
- 查询指定商品名称对应的虚拟库存
- 查询天猫仓可配货数
命令示例:
以下命令默认在 skills/jushuitan-inventory-query/ 目录下执行。
python scripts/tools/query_virtual_stock.py --sku-ids 6974318532161,6974318532147
python scripts/tools/query_virtual_stock.py --i-ids KQ26043,KQ26044
python scripts/tools/query_virtual_stock.py --names 小森林翻翻帽,甜粉小番茄
可选参数:
--wms-co-id
--page-index
--page-size
--timeout
--json
使用限制:
- 必须且只能提供一种查询条件:
--sku-ids / --i-ids / --names
page_size 最大值为 500
虚拟库存输出字段:
SKU ID
颜色/规格
库存数
仓库待发数
可配货数
输出要求
- 默认输出 markdown(由客户端脚本渲染),传
--json 输出原始 JSON 数据
- markdown 输出按商品名称分组,减少商品名称重复
- 当补查失败、接口失败或
颜色/规格 缺失时,应在 异常与补查 区域体现
- 可适当使用emoji增强可读性
示例
注意不要少数据,所有返回数据都需要
可以适当给出一些建议,但不要过多,保持简洁。
尽量保持 markdown 格式的美观和清晰,方便阅读和理解。
- 主库存查询示例:
## *数据明细*
### **小森林翻翻帽**
| 🏷️ SKU ID | 🧾 款式ID | 🎨 颜色/规格 | 📦 实际库存 | 🔒 库存锁定数 | 📌 订单占有数 | 🚚 采购在途数 | 📥 进货仓库存 | ✅ 剩余可用 |
| --- | --- | --- | ---: | ---: | ---: | ---: | ---: | ---: |
| 6974318532147 | KQ26043 | 山野果语M | 2347 | 0 | 5 | 120 | 2342 |
| 6974318532130 | KQ26043 | 山野果语S | 0 | 0 | 12 | 80 | -12 |
---
## *异常与补查*
---
## *建议*
- 虚拟库存查询示例:
## *数据明细*
### **小森林翻翻帽**
| 🏷️ SKU ID | 🧾 款式ID | 🎨 颜色/规格 | 📦 库存数 | 🚚 仓库待发数 | ✅ 虚拟仓可配货数 |
| --- | --- | --- | ---: | ---: | ---: |
| 6974318533328 | KQ26043 | 甜粉小番茄 | 140 | 0 | 140 |
| 6974318533329 | KQ26043 | 甜粉小番茄 | 120 | 5 | 115 |
---
## *异常与补查*
---
## *建议*