1688-distribution-knowledge-newton

# 分销知识库查询 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. **保留图片信息**：文档中的图片链接必须完整保留并展示给用户，使用 `` 格式 3. **步骤详细列举**：操作步骤必须逐步编号列出，每一步都要清晰说明 4. **内容不能过于简短**：至少包含完整的操作流程，不能省略关键细节 基于检索到的文档，生成以下内容： **一、查询总结（详细版）** 综合所有高相关度文档，按以下格式输出： ``` ## 查询总结 根据知识库，关于「[用户问题]」的完整操作指南如下： ### 操作步骤 **第 1 步：[步骤名称]** [详细说明这一步要做什么，在哪里操作] [如果文档中有图片，必须展示：] **第 2 步：[步骤名称]** [详细说明] [相关图片] **第 3 步：[步骤名称]** ... ### 注意事项 - [从文档中提取的重要提示或注意事项] - [常见问题或特殊情况说明] ``` **二、详细参考** 列出相关度较高的文档（score > 0.3），每篇包含： - 文档标题（从 `chunking_key` 提取） - 完整的关键内容（不要过度精简，保留操作细节） - 文档中的所有图片（使用 markdown 图片语法展示） - 来源链接（`source_url`） - 相关度评分（`score`） **完整反馈示例：** ``` ## 查询总结 根据知识库，关于「抖音店铺如何发货」的完整操作指南如下： ### 操作步骤 **第 1 步：进入订单管理页面** 登录您的抖音店铺后台，点击左侧菜单栏的「订单管理」，找到待发货的订单。  **第 2 步：选择物流方式** 点击订单右侧的「发货」按钮，在弹窗中选择您使用的物流公司...  **第 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官方铺货、普云铺货、麦爆了分销、马上分销、掌中宝分销、智汇分销、微购相册、抖掌柜分销、旺分销铺货、小天分销、火牛分销王 ## 语言要求 **⚠️ 重要：本技能的所有输出、提示、消息必须使用中文！**