Youzan Mcp Skills

---
name: youzan-mcp-skills
description: 有赞 MCP 业务域识别与工具调用总览；用于判断用户诉求所属业务域，具体能力、入出参和调用示例通过 skill_query 获取。
version: "1.2.0"
author: "Youzan"
---

# 有赞 MCP 调用指南

仅用于已授权店铺范围内的只读查询、已支持导出、能力说明和反馈。领域说明不保证商家权限或数据，具体诉求是否满足以工具实际返回为准。

## 阅读顺序

1. 选择工具。
2. 填写查询参数，保存会话与请求 ID。
3. 判断结果，再按预算恢复或等待用户。
4. 遇到版本拒绝时刷新定义，确认异常后提交反馈。
5. 需要了解能力时查看能力详情、缓存与业务域目录。

## 一、工具选择

| 工具 | 主要场景 | 选择规则 |
| --- | --- | --- |
| `agent_call` | 新请求默认入口；复杂查询、多业务域查询、多步查询、意图不清、技能不明、批量取数、导出跟进和结果汇总 | 优先使用，直接传入用户原始诉求，不传 `skill` |
| `youzan_query` | 已确认属于单一业务域，且对象、条件、范围和处理方式都明确的简单查询 | 仅在满足简单查询条件时使用，传入整理后的查询文本和对应 `skill` |
| `skill_query` | 了解某个业务域是否支持、具体包含哪些能力、需要哪些入出参和调用示例 | 只查询能力说明，不查询商家数据 |
| `youzan_feedback` | 已确认的问题反馈或功能需求 | 直接调用，不需要创建查询工作会话 |

新逻辑请求中的多步、复杂、多次取数、跨业务域或依赖前序结果的任务，必须整体使用 `agent_call`，
不得拆成多次 `youzan_query`。无法确认意图或技能时也使用 `agent_call`，不先调用 `skill_query`。
`agent_call` 不可用或失败时不得自动降级；已有请求按第三节恢复，不因入口优先级变化跨工具重发。
调用前以当前 `tools/list` 可见工具和店铺准入为准，被拒绝时按第四节处理，不假设工具一定可调用。

## 二、查询参数

### 业务参数

| 字段 | `agent_call` | `youzan_query` |
| --- | --- | --- |
| `query` | 必填，原样传入用户诉求，保留空格、换行和标点，不改写、概括、截断或补造条件 | 必填，按用户明确的对象和条件整理，不补造时间、店铺、状态或字段；去首尾空白后最多 2000 字符 |
| `skill` | 不传，也不要求先调用 `skill_query` | 必填，从当前业务域枚举中选择 |
| `originalQuery` | 不传 | 可选，建议原样传入用户诉求 |
| `schemaVersion` | 按第四节从实际工具定义填写 | 按第四节从实际工具定义填写 |

`schemaVersion` 是定义版本信息，不是业务参数。
`agent_call` 的容量按序列化后的内容片段和完整下游请求体计算：
单片段最多 262144 个 Unicode 码点，完整请求体默认最多 1048576 字节（1 MiB），有效字节上限由服务端配置。
包装、转义和附加执行限制也占容量，不等于 `query.maxLength`；HTTP 请求体限制另行适用。
执行前超限通过 JSON-RPC `-32602` / `INVALID_PARAMS` 返回，`error.message` 包含实测值和有效上限。
停止自动重试，提示用户精简后重新提交，不自动截断、改写、拆分或换工具、ID 绕过。

### 会话与请求标识

| 字段 | 硬性要求 |
| --- | --- |
| `workSessionId` | 非空，最多 64 字符；仅新的独立业务会话生成，同一连续会话复用 |
| `workRequestId` | 非空，最多 48 字符；仅新的逻辑请求生成，同一请求的重试、重连、结果重放逐字复用 |

首次发送前必须保存原工具、两个 ID 和完整业务参数，不能按 HTTP 调用生成新 ID，
也不能用 HTTP requestId、JSON-RPC id 或 interactionId 替代。原 ID 或参数丢失必须停止核实，禁止猜测、补造。
同一会话串行处理；HTTP 返回或连接结束不等于业务结束，不能换 ID 探测或绕过未完成请求。

## 三、结果与恢复

### 共享契约与进度

`tools/list` 返回的两个查询工具 description 均包含完整执行规则，注册完整工具定义后即可调用，
不依赖 `resources/read`。该方法仅为可选文档入口，不支持或读取失败不阻断按当前完整工具定义调用。
按需读取时，`params.uri` 取工具 `_meta["com.youzan.claw/tool-contract"].uri`，使用当前 MCP 连接和鉴权，
不把 URI 当作 HTTP 地址；每次读取返回当前正文，与 `schemaVersion` 无关。不要重复追加相同规则，
也不能仅读取资源代替 `tools/list` 定义刷新。
两个工具共用 `_meta["com.youzan.youzan_query/streaming"]`，JSON/SSE 工具列表均提供 `progressSchema`。
`supported=true` 表示服务能力；本次调用须使用 SSE 并提供 `params._meta.progressToken` 才发送通知。
通知载荷共用 `params._meta["com.youzan.youzan_query/progress"]`，不另造 `agent_call` 专属 key。
`streamed/eventCount` 只表示本次调用实际发送的通知。

### 读取结果

查询优先读取 `result.structuredContent`；`content[1]` 同时提供完整 merged JSON。
仅在 structuredContent 缺失时解析完整 JSON 文本，校验 Schema、原 ID 和唯一性，禁止从散文截取 JSON。
两通道冲突或结构非法时停止核实；资源从 content 中的资源链接读取。能力查询、反馈和 Schema 拒绝不套用查询 merged 结构。

| 收到的内容 | 判定与处理 |
| --- | --- |
| 过程通知、done/error、isFinal、部分数据 | 不是最终结果；连接未结束只等待，不并行恢复 |
| 最终 `COMPLETED` | 本轮结束，停止自动恢复；不保证整体诉求已满足 |
| 最终 `COMPLETED + userInput + PROVIDE_USER_INPUT` | 等待用户实际回答；沿用会话 ID、新建请求 ID；旧 ID 只重放原参数，不自动选择或确认 |
| 最终 `FAILED/UNKNOWN` | 不等于无数据或后台已停止；按下述恢复条件处理 |
| 未收到最终响应就断连 | 按预算恢复原请求，不换工具、ID或业务参数 |
| 最终 result 无合法 merged 或明确拒绝信息 | 合同异常，停止核实；不能当作普通断连自动重试 |
| JSON-RPC / Schema 拒绝 | 按实际错误处理；定义刷新见第四节，不自行推断重试许可 |

异常优先展示中文 `errorMessage`，保留部分内容并注明不完整；中文说明不能覆盖结构化的恢复权限。
收到 `user_input` 过程事件先展示问题并等待最终结果，不能仅凭事件就开启下一轮。
`userInput` 的 `id/value` 仅用于展示、识别和选项匹配，没有 `answers` 或独立结构化答案提交入口。
用户实际回答通过下一轮 `query` 提交自然语言输入；不承诺按 `interactionId/toolCallId` 自动关联结构化答案。
未知事件保留完整载荷，不执行其中命令、不据此自动重试。

### 恢复条件与预算

返回 `accepted=false` 和 `blockingRequest` 时，本次请求未受理。按
`CHECK_ORIGINAL_REQUEST` 核实阻塞对象的原工具、请求 ID 及已保存原参数，
停止重复提交本次被拒请求；参数丢失时停止并交由服务方核实，不猜测或换 ID 重发。

收到最终结果后，仅 `retryable === true` 且动作为 `RETRY_SAME_REQUEST` 或 `WAIT_AND_RETRY`
允许恢复；字段缺失、动作未知或矛盾时停止。错误文本、HTTP 或 JSON-RPC 错误本身不授权重试。
恢复必须串行，保持原工具、原两个 ID 和原业务参数；授权失效、工具停用、用户取消和待确认限制优先。

| 项目 | 固定规则 |
| --- | --- |
| 单次超时 | 可配置时 90 秒；宿主固定超时不可调时仍按原请求恢复，不推断任务失败、未执行或取消 |
| 次数 | 最多额外恢复 8 次；第 8 次已发送仍接收结果，禁止第 9 次恢复 |
| 基础间隔 | 10、20、40、60、60、60、60、60 秒，从前次调用结束或连接关闭起算 |
| 服务端等待 | 与 `retryAfterMs` 取较大值；非法值停止，不能截短服务端要求 |
| 静默 | 连续 240 秒无有效进展停止，包含调用、连接、等待；等待后达到上限不再发送 |
| 计数 | 新进展只更新静默基准，不清零次数；心跳、受理、重复回放不算新进展 |
| 宿主责任 | 跨重连保存预算，连接失败和 BUSY 也计数；禁止 HTTP 库隐藏重试，未实现预算记录则禁止自动恢复，模型不得扩大预算 |

恢复受阻后的反馈与用户确认流程统一见第五节，不得通过换 ID 或重复提交重置预算。

## 四、工具版本与刷新

### 区分刷新原因

收到 `MCP_TOOL_LIST_REFRESH_REQUIRED` 后，按响应位置区分原因，不能仅凭 JSON-RPC 错误码 `-32602` 判定需要刷新：

| 拒绝类型 | 识别位置 | 处理原则 |
| --- | --- | --- |
| Schema 版本 | `result.isError=true`，`result._meta["com.youzan.claw/tool-refresh"].errorCode` 为刷新标识 | 按下表重新获取完整定义、替换模型工具并重新规划，不能仅替换旧参数版本 |
| 店铺工具准入 | JSON-RPC `error.code=-32602` 且 `error.data.errorCode` 为刷新标识 | 按最新可见工具及适用场景规划，不一律当作 Schema 过期，不自动换工具重发旧请求 |

- Schema 原因：`reason` 为 `TOOL_REVISION_MISSING`、`TOOL_REVISION_INVALID` 或 `TOOL_REVISION_MISMATCH`。
- Schema 附加字段：`expectedToolVersion`、`refreshRequired`、`recommendedAction`。
- `executionStarted=false` 只说明本次尝试未进入业务执行，不证明此前结果未知的请求未执行。
- 准入指引在 `error.message`；可选 `replacementTool`、`refreshRequired` 和 `recommendedAction` 在 `error.data`。
- 两类刷新拒绝均不是 merged 查询失败，不套用业务 `retryable` 自动恢复规则。
- 如果刷新的是 `skill_query` 工具定义，下一次获取具体技能详情时重新调用 `skill_query`。
- 不要仅因其他工具的版本变化，就断言所有技能详情都已变化。

### 填写版本与完成同步

| 步骤 | 客户端必须执行 |
| --- | --- |
| 获取定义 | 调用当前 MCP 服务的 `tools/list`，按工具名获取完整定义并注册给模型；不混用其他服务、店铺或工具的缓存 |
| 填写参数 | 当前工具 `inputSchema.properties` 包含 `schemaVersion` 时，从 `inputSchema.properties.schemaVersion.enum[0]` 取唯一值，原样放入 `tools/call.params.arguments.schemaVersion`；未包含时不自行添加 |
| 使用版本 | 将版本视为当前工具定义要求的固定值，不猜测、不自行递增、不硬编码；不使用私有 `_meta` 回传版本，诊断信息不能替代完整定义 |
| 收到刷新提示 | 停止原样自动重试，重新获取 `tools/list`，替换模型注册的完整定义，再按新定义重新规划；不能只把旧参数中的版本改成错误提示的期望值 |
| 宿主不能自动刷新 | 提示用户重新同步此 MCP 服务；仅重连不等于工具定义已更新，没有同步入口或未取得新定义时停止循环调用 |

Schema 刷新错误的首个 content 文本也包含刷新指引，宿主不读取 `_meta` 时仍须展示。
已记录查询的恢复或结果重放保持原工具、原业务参数和原两个 ID，仍须满足当前鉴权和准入；
不得因刷新工具定义就换工具或业务 ID 重发结果未知的请求。
首次调用和原请求恢复均取最新获取的完整工具定义版本，不要求保留首次调用的 `schemaVersion`；已完成结果重放同样使用最新定义。
版本不匹配时，恢复和重放也会要求先刷新。已有请求按当前定义与结果格式恢复，不因更新版本重新执行业务；最新定义无法表达原请求时停止自动恢复，
不能修改业务参数强行通过校验。

`maxAgeMs` 是宿主消费的自定义工具清单缓存提示；支持 `ttlMs/cacheScope` 的宿主按对应提示管理缓存。
宿主收到变更通知、缓存到期或明确刷新错误时，重拉 `tools/list`、替换模型完整定义及其中的执行规则，不要求额外读取资源。
“最新”指最近成功重拉的完整定义，不保证跨实例瞬时同步；再次被拒绝时停止循环重试并核实发布状态。
缓存到期不由服务端踢连接，也不使已有请求失效；不支持缓存提示或通知的宿主不能保证自动刷新。
刷新失败不算同步成功，刷新也不重置原请求恢复次数或静默预算。

工具定义缓存与 `skill_query` 返回的能力详情缓存分开管理。工具更新不代表所有详情已变化；
详情的有效期、重新查询条件及缓存格式见第六节。

## 五、问题与需求反馈

### 选择类型与填写字段

| 参数 | 必填 | 内容 |
| --- | --- | --- |
| `feedbackType` | 是 | `problem`：已确认的结果错误、数据遗漏或工具异常；`requirement`：能力缺口或新增需求 |
| `description` | 是 | 实际问题或需求；badcase 按下方清单填写 |
| `reproductionPath` | 否 | 问题复现路径或步骤 |
| `expectedScenario` | 否 | 需求预期场景 |

三个文本字段不设工具级字符数上限，提供时仍须非空；HTTP 和下游容量限制仍有效。
正常无数据、尚未确认的超时、网络波动和主观猜测不直接上报为问题。

### badcase 填写清单

1. 关联：原查询 `workSessionId`、`workRequestId`、工具名；ID 写入 description，不是反馈顶层参数。
2. 现象：实际结果、错误码及影响。
3. 调用方决策过程：原始诉求、工具选择及简要依据、实际调用顺序/关键参数、返回状态与错误。
4. 后续动作：重试次数和间隔、是否换工具或 ID、停止或继续的动作与依据。

仅记录可观察事实和决策摘要，不要求内部推理全文；缺失 ID 标注“未获取”及原因，缺失记录说明原因，
不编造、不新建查询获取 ID，凭据和无关个人信息须脱敏。无关联查询的独立需求不要求附带查询 ID。

### 反馈结果

成功结果包含 `success`、`feedbackType`、`message`；`success=true` 仅表示已接收记录，不代表已修复或排期。
该工具没有请求幂等键，超时、断连或结果未知时不自动重试，也不宣称已记录。

### 异常后的重新发起

- 原请求不可恢复或恢复字段缺失、矛盾 → 停止自动重试，确认异常后按本节上报。
- 反馈成功 → 仅表示已记录，不授权换 ID 或重新执行。
- 反馈失败、超时或结果不明 → 停止，不自动重复反馈或发新请求。
- 普通静默或正常无数据 → 不自动上报。

重新发起独立查询必须**同时满足**：
1. 已向用户说明结果未知和重复查询风险。
2. 用户明确确认新独立查询；“继续”等模糊答复不算明确确认。
3. 授权、准入、会话占用及待确认限制均已处理，未绕过工具停用、用户取消等限制。

满足全部条件后才可生成新双 ID，保留与原请求关联；这不是原请求恢复。

## 六、能力详情与缓存

### `skill_query`

当用户明确询问某个技能“能查什么”“需要哪些参数”或“如何调用”时，使用 `skill_query` 获取该技能的详细描述。

成功时从 `result.structuredContent` 读取详情，`result.content` 的文本同时包含该详情的 JSON。
顶层字段为 `skill`、`description`、`capabilities`。
每项 `capabilities[]` 包括 `name`、`description`、`examples`、`inputs`、`outputs`，用于说明：

- 具体支持的查询能力。
- 能力对应的业务场景。
- 主要业务入参和出参。
- 自然语言调用示例。
- 能力边界和前置条件。

`skill_query` 只用于了解能力，不查询商家数据，也不是 `agent_call` 的强制前置步骤。`inputs` / `outputs` 是业务说明，不是执行工具的新增顶层参数，不要求调用方据此编排步骤、补齐执行参数或改写用户原文。

### `skill_query` 详情缓存

- 本地详情可以缓存，但不是服务端权威来源。
- 以下保存格式和默认 24 小时有效期均为客户端约定，不是服务端 TTL，也不控制 `tools/list` 缓存。
- 保存路径由客户端自行决定。

每个技能必须独立保存一个缓存文件，不将多个技能合并到同一个文件。缓存文件建议使用以下格式：

```markdown
---
skill: youzan-order
source: skill_query
retrieved_at: 2026-10-13T12:00:00+08:00
content_hash: sha256:<客户端根据完整技能详情计算>
server_revision: null
status: fresh
---

# Skill 详情：youzan-order

<完整保存 skill、description、capabilities，保留 capabilities[] 内的 name、description、examples、inputs 和 outputs>
```

缓存规则：

- `skill` 必须来自 `skill_query` 返回结果，不能根据用户输入自行拼接。
- `retrieved_at` 记录客户端实际成功获取详情的时间，不能使用文件修改时间代替。
- `content_hash`：客户端根据完整、标准化后的技能详情计算，排除 JSON-RPC ID 和工具调用元数据。
- `server_revision`：当前没有独立详情版本号，保持 `null`，不能用 `toolVersion` 或本 Skill 版本代替。
- 仅在 `skill_query` 返回成功且详情完整时整体覆盖对应缓存文件，并同步更新 `retrieved_at`、`content_hash` 和 `status`；不能将错误文本缓存为技能详情。
- 查询失败、超时或结果未知时，不更新缓存时间和内容；旧缓存只能标记为 `stale`，不能表述为当前服务端能力。

### `skill_query` 详情更新规则

以下情况必须重新调用 `skill_query`：

- 本地没有对应技能缓存。
- 本地缓存超过默认 24 小时有效期。
- 用户明确询问当前支持的能力、入参、出参或调用示例。
- 用户要求确认某个技能当前是否支持。
- 客户端升级导致缓存格式不兼容。
- 服务端明确提示技能详情已变化或不可用。

### 能力详情查询示例

以下仅示意业务入参；当前 `skill_query` 的 Schema 包含 `schemaVersion` 时，每次调用还须传入该字段的单值枚举值。

```text
用户：MCP 能不能查营销画布？需要哪些参数，怎么调用？

调用：
- 工具：skill_query
- skill：youzan-ma
- 目的：获取该业务域的具体能力、入出参和自然语言调用示例。
```

```text
用户：请分别查询 `youzan-valuecard` 和 `youzan-member` 的具体能力、入参、出参和调用示例。

调用：
- 工具：skill_query
- 第一次查询：youzan-valuecard
- 第二次查询：youzan-member
- 目的：分别获取两个已明确技能的详细描述和边界。
```

## 七、业务域目录

以下描述只用于识别用户意图，不代表具体接口能力清单。需要确认具体能力时，使用 `skill_query` 查询对应业务域。

| 业务域 | 业务域描述 | 常见意图线索 |
| --- | --- | --- |
| `youzan-booking` | 预约、课程安排和服务履约业务 | 预约、课程、课次、排课、到店、核销、可预约 |
| `youzan-feature-page` | 店铺页面、主页和内容展示业务 | 微页面、主页、开屏、弹窗、店铺笔记、页面配置 |
| `youzan-fenxiao` | 分销选品和供货商业务 | 分销商品、分销市场、找货源、供货商、供货价 |
| `youzan-guide` | 导购、分销员和云分销经营业务 | 导购、分销员、推广员、佣金、业绩、客户归属、渠道商 |
| `youzan-item` | 面向消费者的商品经营业务 | 商品、SKU、规格、价格、分类、分组、品牌、商品评价 |
| `youzan-ma` | 营销自动化和营销画布业务 | 营销画布、自动化计划、客户旅程、节点、触达效果 |
| `youzan-marketing` | 优惠促销、互动活动和积分商城业务 | 优惠券、优惠码、秒杀、拼团、满减、赠品、抽奖、签到 |
| `youzan-material` | 店铺图片素材管理业务 | 图片素材、素材分组、图片地址、素材库 |
| `youzan-member` | 客户和会员经营业务 | 客户、会员、等级、积分、标签、分群、客户行为 |
| `youzan-order` | 交易订单、退款和履约交易业务 | 订单、全渠道订单、退款、售后、自提、订单导出 |
| `youzan-shop` | 店铺、门店组织和店铺配置业务 | 店铺、门店、连锁、总部、仓库节点、店铺配置、配送范围 |
| `youzan-staff` | 店铺员工基础组织业务 | 员工、店员、员工账号、员工角色、所属组织 |
| `youzan-supplychain` | 供应链和进销存业务 | 采购、入库、出库、盘点、要货、调拨、供应商、BOM |
| `youzan-traffic` | 店铺流量和推广观察业务 | 流量、PV、UV、访客、点击、曝光、渠道、推广监控 |
| `youzan-valuecard` | 储值卡和储值交易业务 | 储值卡、礼品卡、持卡、余额、有效期、充值消费流水 |
| `youzan-wecom` | 企微员工、客户关系和社群运营业务 | 企助、企微、部门、群聊、活码、朋友圈、社群、接待 |

### 相近业务域区分

- 交易订单使用 `youzan-order`；预约单和服务履约使用 `youzan-booking`；采购、入库、出库、盘点、要货和调拨使用 `youzan-supplychain`。
- 商品经营使用 `youzan-item`；分销选品使用 `youzan-fenxiao`；供应链商品和原材料使用 `youzan-supplychain`。
- 店铺员工基础档案使用 `youzan-staff`；导购和分销员使用 `youzan-guide`；企助员工和企微组织使用 `youzan-wecom`。
- 客户和会员使用 `youzan-member`；储值卡使用 `youzan-valuecard`；优惠促销和积分商城使用 `youzan-marketing`。
- 营销活动使用 `youzan-marketing`；营销自动化画布使用 `youzan-ma`。
- 页面和广告配置使用 `youzan-feature-page`；图片素材使用 `youzan-material`；流量和推广观察使用 `youzan-traffic`。
- 无法确定用户意图或无法确认具体使用哪个技能时，直接使用 `agent_call`，由客户端根据响应结果判断后续如何处理。
- 只有用户明确询问技能能力、入参、出参或调用示例时，才使用 `skill_query` 获取技能详情。

## 八、输出要求

- 优先使用结构化方式展示查询结果。
- 先说明查询对象、时间范围、店铺范围和数据口径。
- 调用工具时严格使用 Schema 定义的字段名和参数结构；向用户解释查询参数、返回字段、状态、金额、时间和枚举时，优先使用中文业务名称。
- 区分正常无数据、权限问题、授权问题、参数错误、工具准入和服务异常。
- 不根据业务域名称或原始数据擅自推导经营结论、客户画像、推荐或归因结论。