1688 Distribution Knowledge Newton

SKILL.md

---
name: 1688-distribution-knowledge-newton
description: 查询 1688 分销知识库，获取发货流程、铺货操作、订单管理等分销相关文档。当用户询问分销工作流程、发货流程、平台操作指南，或涉及 1688 分销知识时使用此 skill。支持按渠道（淘宝、抖音、拼多多等）和工具（自动分销、店长铺货等）筛选。
metadata: {"openclaw": {"emoji": "📚", "requires": {"bins": ["python3"]}, "primaryEnv": "ALI_1688_AK"}}
---

# 分销知识库查询 Skill

## 背景说明

AK（Access Key）通过 clawhub 获取，通过环境变量 ALI_1688_AK 配置。AK 已绑定用户身份，无需任何额外的身份参数。

## 功能概述

- ✅ **知识查询** - 根据用户问题检索分销相关知识文档
- ✅ **渠道筛选** - 支持按淘宝、抖音、拼多多等渠道筛选
- ✅ **工具筛选** - 支持按自动分销、店长铺货等工具筛选

## 前置检查：确认 AK 已配置

**skill 触发后，第一步必须立即检查 AK，不得先执行任何接口调用。** 运行以下命令：

```bash
python3 scripts/capabilities/configure/cmd.py
```

- **显示 "✅ AK 已配置"**：直接进入后续步骤，不要向用户提及此检查。
- **显示 "❌ 尚未配置 AK"**：输出下方 **AK 引导话术**，然后**停止，等待用户回复，不要做任何其他操作**。
  - 用户回复后，从消息中提取 AK 字符串，执行：
    ```bash
    python3 scripts/capabilities/configure/cmd.py <提取到的AK>
    ```
  - 配置完成后，直接继续执行用户最初的需求，无需额外说明。

## AK 引导话术

```text
需要先配置 AK，获取方式：
打开 [clawhub.1688.com](https://clawhub.1688.com) 点击右上角**钥匙🔑图标**获取 AK
获取后告诉我：「我的AK是 xxxxxx」
```

## 使用流程

### 步骤 1：解析用户意图

分析用户问题，识别以下三个要素：

- **query**：**用户原始问题，原封不动传递，严禁修改**
- **渠道（channel）**：用户是否提到了具体的渠道平台
- **工具（business）**：用户是否提到了具体的分销工具

**⚠️ query 原则（必须严格遵守）：**
- 不要去掉任何词语
- 不要改写、精简或翻译用户问题
- 原封不动地将用户原话作为 query 参数传递
- **只有一种例外**：召回结果与用户问题完全无关时，才允许对 query 做极小调整（仅补充 1-2 个关键词），然后重新召回一次。重试只允许一次，不得反复修改。

### 步骤 2：确认渠道和工具（强制询问）

**⚠️ 重要规则：如果用户没有明确说明渠道和工具，必须先询问用户，不能跳过此步骤！**

**如果用户明确提到了渠道和工具**，直接使用中文名称传参，进入第三步。

**如果用户未明确渠道或工具（即使只缺少其中一个）**，**必须停下来追问用户**，使用以下话术：

```
为了给您提供更精准的知识，请告诉我您想查询的渠道和工具：

📱 **渠道**（您的店铺所在平台）：
淘宝、天猫、抖音、拼多多、快手、小红书、京东、微信小店、有赞、微店、淘特、快团团、微信小商店、支付宝、苏宁、闲鱼、饿了么、美团、度小店、微盟、微购相册
或选择"不限"使用通用知识库

🔧 **工具**（您使用的分销工具）：
逸淘分销铺货、自动分销、代发助手王、店长铺货、妙手分销、速当家分销、智淘分销、甩手易分销、无忧分销王、晓风分销、大泽云铺货、顶卖分销、铺货代发、1688官方铺货、普云铺货、麦爆了分销、马上分销、掌中宝分销、智汇分销、微购相册、抖掌柜分销、旺分销铺货、小天分销、火牛分销王
或选择"不限"使用通用知识库

请直接回复渠道和工具名称，例如："淘宝 + 逸淘分销铺货"
```

**然后停止，等待用户回复，不要继续执行任何操作！**

用户回复"不限"或"默认"时，对应参数传 `"default"`。

### 步骤 3：调用知识库接口

使用 `scripts/biz/knowledge_query.py` 中的 `query_knowledge` 函数执行查询：

```python
from scripts.biz.knowledge_query import query_knowledge

# 示例：用户问"抖音用自动分销怎么发货"
result = query_knowledge(
    query="发货",
    channel="抖音",        # 直接传中文名称
    business="自动分销",    # 直接传中文名称
)

# 如果用户未指定渠道或工具，传 "default"
result = query_knowledge(
    query="铺货流程",
    channel="default",
    business="default",
)
```

> channel 和 business 直接传中文名称，未指定时传 `"default"`。

### 步骤 4：处理响应

响应中的 `data` 是精排后的文档数组（最多 20 条），每条文档包含：

| 字段 | 说明 |
|------|------|
| `score` | 相关度分数（0-1 之间，分数越高越相关） |
| `chunking_val` | 文档正文内容 |
| `source_url` | 原始文档链接 |

**响应示例：**
```json
{
  "success": true,
  "data": [
    {
      "score": 0.99,
      "chunking_val": "工具名称：逸淘分销铺货;内容：...",
      "source_url": "https://peixun.1688.com/article/xxx"
    }
  ]
}
```

**输出字段说明（只输出以下三个字段给用户）：**

| 字段 | 说明 |
|------|------|
| `score` | 相关度分数，范围 0-1，分数越高表示与用户 query 越相关 |
| `chunking_val` | 召回的文档内容，包含具体的操作说明 |
| `source_url` | 文档来源链接，用户可点击查看完整内容 |

### 步骤 4.5：判断召回结果是否可用

拿到 `data` 数组后，在总结之前先做相关性判断：

**✅ 直接进入步骤 5 总结（满足以下任一条件）：**
- 最高 `score` ≥ 0.3
- `chunking_val` 内容与用户问题有明显关联（哪怕 score 较低）
- 有任意文档内容提到了用户问题中的核心关键词

**❌ 才允许调整 query 重试一次（需同时满足以下所有条件）：**
- 所有文档的 `score` 都低于 0.15
- 且 `chunking_val` 内容与用户问题完全无关

**重试规则：**
- 仅允许重试 **1 次**，不得多次重试
- query 调整方式：仅提取用户问题中最核心的 1-2 个关键词，不得大幅改写
- 重试后无论结果如何，直接进入步骤 5 总结

### 步骤 5：向用户反馈结果（详细且完整）

**⚠️ 总结要求（必须严格遵守）：**
1. **精准解决问题**：总结必须直接回答用户的问题，不能泛泛而谈
2. **保留图片信息**：文档中的图片链接必须完整保留并展示给用户，使用 `![图片说明](图片URL)` 格式
3. **步骤详细列举**：操作步骤必须逐步编号列出，每一步都要清晰说明
4. **内容不能过于简短**：至少包含完整的操作流程，不能省略关键细节

基于检索到的文档，生成以下内容：

**一、查询总结（详细版）**

综合所有高相关度文档，按以下格式输出：

```
## 查询总结

根据知识库，关于「[用户问题]」的完整操作指南如下：

### 操作步骤

**第 1 步：[步骤名称]**
[详细说明这一步要做什么，在哪里操作]
[如果文档中有图片，必须展示：![操作示意图](图片URL)]

**第 2 步：[步骤名称]**
[详细说明]
[相关图片]

**第 3 步：[步骤名称]**
...

### 注意事项
- [从文档中提取的重要提示或注意事项]
- [常见问题或特殊情况说明]
```

**二、详细参考**

列出相关度较高的文档（score > 0.3），每篇包含：
- 文档标题（从 `chunking_key` 提取）
- 完整的关键内容（不要过度精简，保留操作细节）
- 文档中的所有图片（使用 markdown 图片语法展示）
- 来源链接（`source_url`）
- 相关度评分（`score`）

**完整反馈示例：**
```
## 查询总结

根据知识库，关于「抖音店铺如何发货」的完整操作指南如下：

### 操作步骤

**第 1 步：进入订单管理页面**
登录您的抖音店铺后台，点击左侧菜单栏的「订单管理」，找到待发货的订单。

![进入订单管理](https://example.com/image1.png)

**第 2 步：选择物流方式**
点击订单右侧的「发货」按钮，在弹窗中选择您使用的物流公司...

![选择物流](https://example.com/image2.png)

**第 3 步：填写快递单号**
输入快递单号，确认无误后点击「确认发货」...

### 注意事项
- 发货后 24 小时内需上传物流单号，否则可能影响店铺评分
- 如使用无需物流的商品，请选择「无需物流」选项

---

## 详细参考

### 1. 抖音发货操作指南
**相关度**: 0.584
**来源**: [查看原文](https://help.example.com/doc1)

[完整的文档内容，包含所有图片和步骤说明]

### 2. 分销订单发货常见问题
**相关度**: 0.432
...
```

## 错误处理

```python
result = query_knowledge(...)

if not result.get("success"):
    print(f"调用失败：{result.get('error')}")
    # 常见错误：
    # - "AK 未配置"：请设置环境变量 ALI_1688_AK
    # - "参数错误"：检查传入的参数是否正确
    # - "网络异常"：请稍后重试
```

- 若 `reRankDocList` 为空或不存在：提示用户换关键词或扩大搜索范围（使用默认渠道/工具）
- 若 AK 无效导致鉴权失败：提示用户检查 AK 是否正确
- 若接口调用异常：提示用户服务暂不可用，稍后重试

## 依赖包

```bash
pip install requests
```

## 项目结构

```
1688-distribution-knowledge-newton/
├── SKILL.md                     # 技能说明文档（本文档）
├── README.md                    # 项目说明（开发者阅读）
├── scripts/                     # 核心脚本目录
│   ├── _http.py                # HTTP 客户端（系统文件，不要修改）
│   ├── _auth.py                # 签名认证（系统文件）
│   ├── _errors.py              # 错误类型（系统文件）
│   ├── _const.py               # 常量定义（按需修改）
│   ├── _output.py              # 输出格式化（系统文件）
│   ├── capabilities/configure/  # AK 配置能力（系统文件）
│   └── biz/                    # 业务逻辑目录
│       ├── __init__.py
│       ├── const.py            # 业务常量配置（可修改）
│       └── knowledge_query.py  # 知识库查询模块
```

## 渠道与工具列表

完整列表见 `scripts/biz/const.py`。

### 21个渠道
淘宝、天猫、抖音、拼多多、快团团、小红书、快手、微信小店、京东、有赞、微店、淘特、微信小商店、支付宝、苏宁、闲鱼、饿了么、美团、度小店、微盟、微购相册

### 24个工具
逸淘分销铺货、自动分销、代发助手王、店长铺货、妙手分销、速当家分销、智淘分销、甩手易分销、无忧分销王、晓风分销、大泽云铺货、顶卖分销、铺货代发、1688官方铺货、普云铺货、麦爆了分销、马上分销、掌中宝分销、智汇分销、微购相册、抖掌柜分销、旺分销铺货、小天分销、火牛分销王

## 语言要求

**⚠️ 重要：本技能的所有输出、提示、消息必须使用中文！**