📦 Q Wms — 技能工具

技能文档

1) When to Use

使用本 Skill 的场景：

• 查库存、库存数量、库存明细
• 查仓库、选择仓库、仓库列表
• 查货主、选择货主、货主列表
• 查库存变动日志
• 查订单池、订单池配置、波次开关配置
• 查订单完成情况、出库订单进展、订单异常排查
• 查任务完成情况、任务异常排查
• 查库内绩效、拣货绩效、绩效报表
• 查进销存（新）、IOS(New) 报表

不使用本 Skill 的场景：

• 与 WMS/ERP 无关的闲聊/翻译/写作

2) Critical Rules

• 只要是 WMS/ERP 请求，必须先调用 q-wms-flow，禁止直接回答。
• 在多轮选择中，用户只回数字（如 1/2/0/9）时，也必须调用 q-wms-flow，禁止自己分页、禁止自己映射编码。
• 禁止使用历史记忆自行拼列表。仓库/货主列表只能来自本轮工具返回。
• 只要工具返回 assistantReplyLines 且非空，最终回复必须严格等于它按换行拼接后的文本；不得新增、删减、改写、翻译、换模板。
• 工具返回 assistantReplyLines 为空时，才根据 data 做补充说明。
• 编码参数只能来自用户明确输入或工具返回，不得猜测。
• 用户意图含“查货主/货主列表/所有货主”时，scene 必须是 wms.owner.options，禁止改调 wms.inventory.query。
• 用户意图含“订单/查订单/这个月订单/本月订单/出库订单/已发货订单/未发货订单/待发货订单/订单完成情况”时，scene 必须是 wms.order.query，禁止改调 wms.order.pool.query、wms.inventory.query 或 wms.stock.log.query。
• 当 wms.order.query 或 wms.task.query 返回 SCENE_NOT_SUPPORTED 时，禁止改调任何别名 scene，直接按后端错误提示用户。禁止回退调用 wms.order.status.query、wms.task.status.query、wms.order.pool.query、wms.order.task.status.query、wms.inventory.query。
• 在订单会话链路中（如刚完成授权、刚选择仓库、用户回复“wms/好了/继续/1/2”等短输入），必须继承上一轮“订单”意图，继续走 wms.order.query（或其兼容别名），禁止改走库存/库存日志链路。
• 禁止在未实际调用目标 scene 前，主观声称“q-wms-flow 只支持库存/库存日志”。场景支持性必须以后端真实 toolResult 为准。
• 严禁 hardcode：不得写死固定问句、固定编码、固定时间范围、固定分类文案或固定业务分支；所有路由与回复必须基于用户当轮语义 + 工具实时返回数据。
• 通用防重试规则：同一轮内若“同一 scene + 同一参数语义”连续 2 次返回同一非授权失败码（如 WAREHOUSE_REQUIRED、WMS_ERROR、SCENE_NOT_SUPPORTED），必须停止继续调用工具，直接向用户说明失败原因并给出下一步（调整条件/稍后重试/联系管理员）。
• ownerCode 不做跨轮会话默认值：仅当用户本轮明确提供，或工具本轮返回并要求立即回传时才传入；禁止从历史会话自动回填 ownerCode。
• 用户意图含“库内绩效/绩效报表/拣货绩效”时，scene 必须是 wms.performance.query，禁止改调 wms.task.query、wms.order.query、wms.inventory.query、wms.stock.log.query。
• 当 wms.performance.query 返回 SCENE_NOT_SUPPORTED、SCENE_ERROR 或连续失败时，必须直接告知“当前环境暂未开通库内绩效场景或后端异常”，禁止回退到任务/订单/库存场景输出“近似结果”。
• 当用户明确要求“绩效”，若无法确定到 wms.performance.query（例如工具异常或场景不可用），必须显式告知“未命中绩效场景，暂不返回任务/订单替代结果”，并给出下一步（联系管理员开通或修复 scene）。
• 用户意图含“进销存（新）/进销存报表/进销存查询/IOS(New)/IOS 报表”时，scene 必须是 wms.ios.new.query，禁止改调 wms.task.query、wms.order.query、wms.inventory.query、wms.performance.query。
• 当 wms.ios.new.query 返回 SCENE_NOT_SUPPORTED、SCENE_ERROR 或连续失败时，必须直接告知“当前环境暂未开通进销存（新）场景或后端异常”，禁止回退到任务/订单/库存场景输出近似结果。
• 对话中出现时间要求时，必须优先转成显式时间参数，不得只传自然语言。示例归一：

• 在 choose_warehouse/choose_owner 多轮中，用户只回 1/2/0/9 时，必须继承上一轮已确定的业务参数（尤其时间范围、筛选条件），禁止因仅传数字而丢失时间参数并回退默认时间窗。

3) Scene Routing

以下映射按“语义意图”执行，禁止按固定关键词做硬编码分流。

4) Call Patterns (Must Follow)

4.1 首轮

• 查库存：

{"scene":"wms.inventory.query","userInput":"我要查库存","params":{}}

• 查订单池：

{"scene":"wms.order.pool.query","userInput":"查下我的订单池","params":{}}

• 查订单完成情况：

{"scene":"wms.order.query","userInput":"查询近一个月出库订单完成情况","params":{}}

• 查订单状态（通用）：

{"scene":"wms.order.query","userInput":"查询订单状态","params":{}}

• 查任务完成情况：

{"scene":"wms.task.query","userInput":"查询任务完成情况并排查异常","params":{}}

• 查库内绩效：

{"scene":"wms.performance.query","userInput":"查询库内绩效","params":{}}

• 查进销存（新）：

{"scene":"wms.ios.new.query","userInput":"查询进销存（新）报表","params":{}}

• 查进销存报表（不带“新”）：

{"scene":"wms.ios.new.query","userInput":"我要查进销存报表","params":{}}

• 查仓库：

{"scene":"wms.warehouse.options","userInput":"查下仓库","params":{}}

• 查货主：

{"scene":"wms.owner.options","userInput":"查下货主","params":{}}

4.2 选择/翻页回合（关键）

当上一轮结果是 choose_warehouse / choose_owner，用户回复 1/2/0/9/...：

• 必须再次调用同一 scene；
• userInput 原样传用户数字；
• params 不得清空：必须保留上一轮已确定的时间与筛选参数；只是不在本地猜编码。

示例：

{"scene":"wms.inventory.query","userInput":"2","params":{}}

{"scene":"wms.inventory.query","userInput":"0","params":{}}

禁止行为：

• 直接输出“第 2 页内容”而不调工具
• 直接把 2 当 warehouseCode/ownerCode

5) Result Handling

按顺序处理：

• assistantReplyLines 非空：直接输出。
• AUTH_REQUIRED/AUTH_EXPIRED 且无 assistantReplyLines：提示需要授权，并输出 authorizationGuide.verificationUri（若有）。

• WAREHOUSE_REQUIRED：优先调用 wms.warehouse.options（params:{}）拿候选仓库。

• OWNER_REQUIRED：若已知仓库，先调 wms.owner.options（仅带 warehouseCode）拿候选货主。
• 其他失败：输出 message，并给“重试/切换条件”的下一步。

6) Inventory Constraints

• wms.inventory.query 合法参数：warehouseCode、ownerCode、skus、queryMode。
• 新一轮“查库存”不要复用旧轮仓库/货主；先走工具引导。
• 有候选列表时，不要求用户手填编码。
• 当 wms.inventory.query 返回 assistantReplyLines 为空时，库存描述优先使用 data.queryOwnerName、data.queryOwnerCode、data.ownerScoped。
• 当 data.ownerScoped=false 或 data.queryOwnerCode 为空时，必须描述为“全部货主”，禁止从 data.inventoryRows 的前几行推断某个具体货主。
• 当返回包含 data.resultNote 时，回复中必须包含该说明，帮助用户理解当前返回范围。
• 当 data.resultTruncated=true 时，必须明确告知“当前仅返回默认第 1 页（pageNo=1,pageSize=200）”，避免用户误解为全量结果。

7) Stock Log

wms.stock.log.query 且 assistantReplyLines 为空时：

• 先结论
• 再关键记录
• 最后异常点（数量跳变/链路断点/可疑操作）

8) Order Pool

wms.order.pool.query 且 assistantReplyLines 为空时：

• 必须先说明仓库（warehouseCode / warehouseName）与总订单数（totalOrders）。
• 分类说明优先使用 classSummaryRows，每行至少包含：分类名（className）与订单数（orderCount）。
• 若 maxOrdersForWave / countPerWave / leftoverHandling 有值，需一并带出；为空时明确说明“未配置/为空”。
• 波次开关使用 waveConfigRows：按 field + selected 输出（如 AUTO_ALLOCATE、AUTO_RELEASE）。
• 若 ruleConfigAvailable=false，必须明确告知“当前仅拿到实时订单池与波次开关，未读取到规则配置明细”。
• 若有 resultNote，回复中应包含该说明。

9) Order Status

wms.order.query 且 assistantReplyLines 为空时：

• 先说明仓库（warehouseCode / warehouseName）与订单风险等级概况（highRiskSignalCount、mediumRiskSignalCount）。
• 订单统计优先使用 orderSummary（totalOrders、returnedRows、pageNo、pageSize、createTimeFrom、createTimeTo）。
• 状态分布优先使用 stageSummaryRows 与 statusSummaryRows，不得臆测不存在的看板字段。
• 订单样例引用 sampleOrders（如 orderCode、stageCode、statusCode、applyStageCode、shortage、shortShip）。
• 异常结论优先基于 anomalySignals：按 severity=HIGH/MEDIUM/LOW 分层说明，并给出排查优先级。
• 若有 resultNote，回复中应包含该说明。

10) Task Status

wms.task.query 且 assistantReplyLines 为空时：

• 先说明仓库（warehouseCode / warehouseName）与任务风险等级概况（highRiskSignalCount、mediumRiskSignalCount）。
• 任务统计使用 taskSummary（taskTypeCount、totalTasks、releasedTasks、assignedTasks、heldTasks、suspendedTasks）。
• 任务类型明细使用 taskTypeRows（taskType、released、assigned、held、suspended、total）。
• 异常结论优先基于 anomalySignals：按 severity=HIGH/MEDIUM/LOW 分层说明，并给出排查优先级。
• 若有 resultNote，回复中应包含该说明。

11) Performance Report

wms.performance.query 且 assistantReplyLines 为空时：

• 优先说明仓库（warehouseCode / warehouseName）与统计时间范围（pickTimeFrom、pickTimeTo）。
• 汇总优先使用 summary（b2cSingleQty、b2cMultiQty、b2bQty、otherQty、skuSpecies、skuQty）。
• 明细优先使用 rows，按操作员输出 operatorName 与上述 6 个绩效指标。
• 若返回分页字段（如 pageNo、pageSize、totalCount），需明确告知当前页与总条数。
• 若有 resultNote，回复中应包含该说明。

12) IOS(New) Report

wms.ios.new.query 且 assistantReplyLines 为空时：

• 优先说明仓库（warehouseCode / warehouseName）、货主（ownerCode / ownerName）与时间范围（startDate、endDate）。
• 汇总优先使用 totals（至少包含 beginBalance、endBalance、b2cOrderQty、b2bOrderQty、supplierReceiptQty、returnReceiptQty）。
• 明细优先使用 rows，按 SKU 输出 skuCode、skuStatusCode、beginBalance、endBalance、b2cOrderQty、b2bOrderQty、supplierReceiptQty。
• 若返回分页字段（pageNo、pageSize、totalCount），需明确告知当前页与总条数。
• 若有 resultNote，回复中应包含该说明。