1688 Distribution Knowledge Newton

分销知识库查询 Skill

背景说明

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

功能概述

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

前置检查：确认 AK 已配置

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

python3 scripts/capabilities/configure/cmd.py

• 显示 "✅ AK 已配置"：直接进入后续步骤，不要向用户提及此检查。
• 显示 "❌ 尚未配置 AK"：输出下方 AK 引导话术，然后停止，等待用户回复，不要做任何其他操作。
  • 用户回复后，从消息中提取 AK 字符串，执行：

    python3 scripts/capabilities/configure/cmd.py <提取到的AK>
    

  • 配置完成后，直接继续执行用户最初的需求，无需额外说明。

AK 引导话术

需要先配置 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 函数执行查询：

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 条），每条文档包含：

响应示例：

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

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

步骤 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
...

错误处理

result = query_knowledge(...)

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

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

依赖包

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官方铺货、普云铺货、麦爆了分销、马上分销、掌中宝分销、智汇分销、微购相册、抖掌柜分销、旺分销铺货、小天分销、火牛分销王

语言要求

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