Lingmao Scm Cloud

---
name: "lingmao-scm-cloud"
description: "领猫 SCM Cloud 供应链系统 —— 查询与操作采购单、款式档案、物料、仓储、质检、财务等开放平台接口"
version: "1.0.1"
author: "领猫科技"
display_name: "领猫 SCM Cloud"
display_name_en: "Lingmao SCM Cloud"
description_zh: "用自然语言查询和操作领猫 SCM Cloud 服装供应链系统的 56 个业务模块：采购单、款式档案、物料、仓储、质检、财务；内置业务知识库问答，回答字段口径与操作前提时有据可依。"
description_en: "Natural-language access to Lingmao SCM Cloud: purchase orders, styles, materials, warehousing, QC."
---

# 领猫 SCM Cloud Skill

本 Connector 把领猫 SCM Cloud（服装供应链 SaaS）的开放平台接口以 MCP 工具形式提供。
**一个工具 = 一个开放平台接口**，把它当 SDK 用，不要期待它替用户做决定。

本 Connector 只有一个 MCP Server（`lingmao-scm-cloud`），连接一次即可，它同时提供两类能力：

| 能力 | 工具 | 说明 |
|---|---|---|
| 取数 | 56 个模块的 `op_*` | 一个工具 = 一个开放平台接口，按授权勾选的模块露出 |
| 口径 | `ask_knowledge` | 业务知识库问答（字段含义、操作前提、报错原因、状态含义、上下游影响），**不计配额** |

两类能力是互补的：`op_*` 告诉你「这个数是多少」，`ask_knowledge` 告诉你「这个数是什么口径」。

## 授权与范围

- 首次使用时 WorkBuddy 会打开浏览器，用户用 SCM Cloud 账号登录、选择租户、勾选允许访问的模块后完成绑定（OAuth，无需手填任何密钥）。
- **授权页默认全选全部模块**（含写入的模块会标「含写」），用户可按业务域整组取消；事后也能在控制台 `https://mcp.scm321.com/api-keys` 该授权的「可用能力」里增减。
- 未勾选的模块，其工具**既不出现在 `tools/list` 也调不动** —— 用户说「你怎么查不了 XX」时先用 `list_capabilities` 确认是不是模块没开，别反复重试。
- 授权 1 小时自动续期，30 天内无需重新登录；用户随时可在控制台吊销。

## 工具形态

| 类别 | 工具 | 说明 |
|------|------|------|
| 自述（不计费，任何时候可用） | `health` | 服务状态、配额余量与重置时间、限速余量。**排查问题先调它。** |
| 自述（不计费，任何时候可用） | `list_capabilities` | 当前授权**实际**能调的模块与工具清单、未开通的模块清单。 |
| 业务接口 | `op_*`（如 `op_get_purchase_order_list_paged`） | 每个工具对应一个开放平台接口，描述形如「模块 · 接口标题」；**入参就是该接口的请求体字段**，以 `tools/list` 返回的 `inputSchema` 为准。 |
| 业务知识库（不计配额，任何授权都可用） | `ask_knowledge` | 问业务口径：字段含义、操作前提、报错原因、状态含义、上下游影响。入参是一个**自包含的完整业务问题**（无对话记忆，追问要改写完整）。 |

工具名与模块划分随开放平台演进，**以运行时 `tools/list` 为准**，不要把工具名写死。
全部工具（按模块列出用途与入参）见 `skills/tools-reference/SKILL.md`。

## 场景 Skill

`skills/` 下另有 6 个按业务场景组织的 Skill，写明了该场景**用哪几个工具、按什么顺序调、
哪些口径必须去业务知识库取**。用户的问题落在某个场景里时，优先按对应 Skill 的流程走：

| Skill | 覆盖场景 |
|---|---|
| `scm-purchase-order-triage/` | 采购单列表、汇总、物料进度、审核前提 |
| `scm-order-fulfillment-watch/` | 销售订单、订单需求、生产跟进与节点异常 |
| `scm-warehouse-snapshot/` | 出入库单据、预约单入库进度、物料库存、装箱 |
| `scm-supplier-reconcile/` | 应付账单、对账单、付款单、账期分布 |
| `scm-material-bom-explorer/` | 物料档案、物料库存、标准/生产资料包 BOM、核价清单 |
| `scm-daily-ops-brief/` | 跨模块的每日运营简报（配额消耗较大，执行前先与用户确认范围） |

## 代表性工具与参数

完整参数以 `tools/list` 返回的 `inputSchema` 为准（工具集合随该授权勾选的模块变化，
写死清单会过期）。下面三个例子说明参数的组织方式。

### `health` —— 服务与配额自检

无参数。返回服务版本、绑定租户、配额余量与重置时间、限速余量。**不计配额，排查问题先调它。**

### `list_capabilities` —— 当前授权实际可用的能力

无参数。返回已开通模块及其下工具、未开通模块清单。工具不在 `tools/list` 里时，用它确认是不是模块没勾。

### `op_get_purchase_order_list_paged` —— 采购单分页查询（列表类工具的通用形态）

| 参数 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `pageIndex` | integer | - | 起始页，不传默认 1 |
| `pageSize` | integer | - | 每页大小，不传默认 50，区间 1–100 |
| `codes` | array | - | 业务编码，支持模糊与多值，取并集 |
| `names` | array | - | 业务名称，支持模糊与多值，取并集 |
| `createTimeBegin` / `createTimeEnd` | string | - | 创建时间区间 |
| `modifyTimeBegin` / `modifyTimeEnd` | string | - | 最后修改时间区间 |
| `status` | array | - | 采购单状态 |
| `orderBy` / `orderRule` | string | - | 排序字段与升降序，仅支持单条件 |
| `purchaseOrderCode` | string | - | 采购单编码 |

其余 `op_*` 列表类工具共用这套分页与时间区间参数；详情类传单据编码；
批量操作类（如 `op_purchase_order_batch_audit`）传 `codes` 或 `orderIds`，
并用 `operate` 区分动作（`1` = 审核、`2` = 反审核）。

**返回体统一为** `{ code, message, data }`：`code = 200` 为成功；
列表类的 `data` 含 `totalCount` / `pageIndex` / `pageSize` / `items[]`。

## 回答业务问题前：先分清「取数」还是「口径」

本 Connector 的工具**只负责取数**。它能告诉你 `availableInboundQuantity = 120`，
但答不了「这个 120 是怎么算的」「和页面上那一列为什么不一样」——
接口字段的业务含义不在接口里。

**按问题类型路由，不要按关键词猜**（同一个词在不同问法里意思完全不同）：

| 用户实际在问什么 | 怎么答 |
|---|---|
| 「帮我查 / 列出 / 统计某单据」 | 直接调 `op_*`，不需要业务知识库 |
| 「这个字段什么意思 / 为什么是这个值 / 什么情况下会这样 / 有什么前提」 | **先取业务口径**，再决定要不要调接口 |
| 「这个数对不对 / 怎么算出来的 / 和页面对不上」 | **两者都要**，并按下面的「口径冲突」处理 |
| 报错、校验没过、操作被拒 | **先取业务口径要原因**，再改参数；不要盲目重试 |
| 「我现在能调什么」 | `list_capabilities` |

### 业务口径从哪来

本 Connector **内置业务知识库问答**工具 `ask_knowledge`，收录 215 个业务菜单的字段口径、
操作前提、报错原因、状态含义与上下游影响。它与业务工具是互补关系：`op_*` 负责取数，
`ask_knowledge` 负责口径；**不计配额**，任何授权范围都能调（口径与模块授权无关）。

- 上表标「取业务口径」的问题，先调 `ask_knowledge`，再结合接口数据回答。
- 问题必须**自包含**：它没有对话记忆，用户的追问（「那超了会怎样」）要改写成完整问题
  （「生产分配中分配数量超过需求数量会被怎样卡控」）再传，带上菜单名更容易命中。
- 知识库答「未收录」时，就据实说这一层没有依据，**不要凭常识编业务规则**。

### 口径冲突怎么办（重要）

知识库讲的是**页面口径**，本 Connector 返回的是**接口口径**，两者经常不等。
真实案例：预约单的 `availableInboundQuantity`（接口）已经把本单预约数扣掉了，
而页面「可入库数量」列没扣——**页面值 = 接口值 + 本次预约数**。
拿页面公式去解释接口返回值，会得出一个看着有依据、其实错位的答案。

所以两者对不上时：**把两个数各自的含义都摆给用户，说明差异来自口径不同，不要自行折中、
不要挑一个当"正确答案"**。知识库明确回答「未说明开放平台接口的取数逻辑」时，
就照实说这一层没有依据，不要用页面口径去补。

## 推荐流程

1. 用户提出业务问题 → 先看 `tools/list` 里有没有对应模块的工具；拿不准时调 `list_capabilities`。
2. 目标工具不在清单里 → 说明该模块未授权：告诉用户去控制台该授权的「可用能力」勾上模块（**下一次调用即生效**），不要反复重试。
3. 按 `inputSchema` 填参数调用；列表类接口先用小 `pageSize`（默认 50，上限 100）。
4. 返回是接口原始响应：`code: 200 / message: "ok" / data: {...}`；`code: 500` 且带业务提示（如「数据不存在！」）= 上游校验没过，按提示改参数。

## 常见示例

| 用户意图 | 调用 |
|----------|------|
| 本月未审核的采购单 | `op_get_purchase_order_list_paged`，按创建时间区间 + 状态筛选 |
| 某采购单的物料到位情况 | 采购单模块的「物料进度」类工具，传采购单编码 |
| 某款式的 SKU 与价格 | 款式模块的详情类工具，传款式编码 |
| 我现在能调什么 | `list_capabilities` |
| 「未审核」到底包含哪些状态 | `ask_knowledge`（状态口径），再据此设 `status` 参数 |
| 这张单为什么审核不了 | `ask_knowledge`（操作前提），不要靠反复调接口试 |
| 接口给的可入库数量和页面不一样 | 两边都取，按「口径冲突」处理，不要折中 |
| 改了这个字段会影响什么 | `ask_knowledge`（上下游影响）——接口不会告诉你这个 |

## 写操作注意

- **调用即执行，不做二次确认** —— 调写接口前把要做的事和关键参数复述给用户确认一次。
- **失败不要盲目重试**：建单 / 改单 / 审核失败时单据可能已经生成，先查一次再决定，否则会建重。只读查询可以重试。
- 每次写操作平台都会留存请求快照（谁、何时、哪个接口、传了什么、结果、上游 `request_id`），用户可在控制台「审计」页查。
- 计费：读 1 单位 / 写 2 单位。

## 错误对照

| 报错 | 含义 | 处理 |
|------|------|------|
| `该 Key 未开通「xx」模块,不能调用 'op_xxx'` | 模块未授权 | 引导用户在控制台勾选模块 |
| `授权已失效,请在客户端重新授权` | 授权被吊销或过期 | 引导用户在 WorkBuddy 重新连接本 Connector |
| 配额 / 限速报错 | 超出套餐额度 | 调 `health` 看余量与重置时间，告知用户 |
| `code: 500` + 业务提示 | 上游业务校验失败 | 按提示修正参数；响应里的 `request_id` 可用于追溯 |