1688-marketing-skill#

统一入口： python3 {baseDir}/cli.py <command> [options]

环境准备#

重要：本 skill 所在的整个目录文件需要先拷贝到 ${AGENT_WORK_ROOT}/workspace 目录下，再执行后续操作。 统一入口： python3 {baseDir}/cli.py <command> [options] 尽量使用绝对路径执行脚本

Windows 权限问题（仅 Windows 用户需要）#

若 skills 目录缺少执行权限（提示"拒绝访问"），需先将目录拷贝到 workspace 再操作：

cmd

xcopy /E /I /Y "<skills目录路径>" "%USERPROFILE%\workspace\1688-auth-skill-for-wukong"
cd /d "%USERPROFILE%\workspace\1688-auth-skill-for-wukong"

/E 递归复制所有子目录， /I 目标不存在时自动创建， /Y 覆盖时不询问确认。 拷贝完成后，后续所有命令均在 workspace 路径下执行。

首次使用前，在项目根目录执行：

bash

pip install -r requirements.txt
# 若上述命令不可用，尝试：
pip3 install -r requirements.txt

依赖列表：仅使用 Python 标准库，无需额外安装第三方包。

AK 安全说明#

⚠️ AK 是访问 1688 接口的唯一凭证，请妥善保管，避免泄漏。

• AK 在本地以 设备绑定加密 方式存储（PBKDF2 派生密钥 + 流加密 + HMAC 校验），加密文件拷贝到其他机器后 无法解密
• 不要将 AK 明文粘贴到聊天记录、截图、日志或版本控制中
• 不要将 ak_store.json 或 .device_id 上传到任何云端或共享目录
• 如怀疑 AK 已泄漏，立即执行 cli.py configure --clear 清除本地存储，并前往 clawhub.1688.com 重新获取

意图判断#

触发场景#

当用户表达以下意图时，应触发本技能：

• 招商活动报名: 报名活动、招商活动、查询活动、提报、报名、活动报名
• 商品建议价查询: 查看建议价、查询价格、提报价
• 商机推荐查询: 商机推荐、商机、市场机会、找商机、查商机

不触发场景#

当用户仅询问以下非 1688 业务话题时，不应触发本技能：

• 闲聊（如：今天天气怎么样）
• 通用编程问题（如：帮我写一个 Python 排序算法）
• 翻译请求（如：帮我把这段话翻译成英文）
• 其他与 1688 营销无关的话题

Tool 总览#

工具名称用途调用方式1688_enroll_activity_query查询招商活动列表python3 {baseDir}/cli.py 1688_enroll_activity_query [--keyword <关键词>] [--pageNo <页码>] [--pageSize <条数>]``1688_enroll_offer_query查询商品建议提报价python3 {baseDir}/cli.py 1688_enroll_offer_query --activityId <活动ID> --itemId <商品ID>``1688_enroll_submit_item提交活动报名（⚠️写入）python3 {baseDir}/cli.py 1688_enroll_submit_item --activityId <活动ID> --itemId <商品ID> --fillFormDataList '<JSON>'``1688_opp_recommend查询商机推荐列表python3 {baseDir}/cli.py 1688_opp_recommend [--keyword <关键词>] [--categoryId <类目>] [--pageNo <页码>] [--pageSize <条数>]``configure配置 AK（支持 --status / --clear / --reset）python3 {baseDir}/cli.py configure YOUR_AK``get_ak获取AKcli.py get_ak

输出格式#

所有命令统一输出 JSON 格式，结构如下：

json

{
  "success": true,
  "markdown": "可选的用户可读描述",
  "data": {},
  "error_code": "可选的错误码（仅失败时）",
  "required_scope": "可选的所需 OAuth Scope（仅授权错误时）"
}

仅包含非空字段。 error_code 和 required_scope 用于 Agent 自动识别网关授权错误并触发恢复流程。

使用流程#

Agent 根据用户意图 识别所属功能模块，按对应流程执行：

流程一：招商活动报名#

1. 查询活动：用户表达报名意图时，先调用 1688_enroll_activity_query 查询招商活动，展示活动列表供用户选择
2. 查询建议价：用户选定活动和商品后，调用 1688_enroll_offer_query 查询商品信息和建议提报价，展示给商家确认，此接口返回的价格单位为分。当建议价为空时，中断流程，提示商家无法报名此活动
3. 确认价格： 必须等商家明确确认建议价后，才能进入报名步骤
4. 提交报名：商家确认后，根据商品是否有 SKU 构造 fillFormDataList，调用 1688_enroll_submit_item 提交报名，此接口入参价格单位为元

流程二：商机推荐查询#

1. 明确意图：用户表达查看商机、市场机会的意图
2. 收集筛选条件：从用户消息中提取关键词、类目等筛选条件（均为可选）
3. 执行查询：调用 1688_opp_recommend 查询商机推荐列表
4. 展示结果：将商机列表以易读格式展示（标题、类目、求购数、参考价格等），如有更多结果提示用户可翻页

各命令在 AK 缺失等情况下会自行返回明确错误，Agent 按下方「异常处理」应对即可。

安全声明#

风险级别命令Agent 行为只读1688_enroll_activity_query直接执行只读1688_enroll_offer_query直接执行只读1688_opp_recommend直接执行写入1688_enroll_submit_item必须在商家确认建议价后才能执行，不得自动提交

全局写入规则（适用于所有写操作）：

1. 所有写入操作必须经过商家明确确认，不得自动执行。
2. 提交报名前，必须先查询建议价并展示给商家；商家明确确认价格后，方可提交报名。
3. 不擅自修改商家确认的任何参数。

环境变量（.env）#

项目根目录的 .env 文件存储 skill 基础信息，供埋点上报等模块读取。发布到不同环境时可直接替换该文件中的变量值。

变量默认值说明SKILL_NAME``1688-marketingskill 名称SKILL_VERSION``1.0.0skill 版本号SKILL_CHANNEL``clawhub发布渠道

已存在的系统环境变量优先级高于 .env，CI/CD 注入的变量不会被覆盖。

埋点上报#

每次 CLI 命令执行时，自动向 skill 网关上报一次调用记录，用于统计 skill 调用次数。

• 实现位置： scripts/_tracker.py → report_skill_usage()，在 cli.py 的 main() 中每次命令执行后自动调用

• 上报接口： POST /api/reportSkillsUsage/1.0.0

• 上报参数： 参数值来源说明apiName固定 null固定传 nullskillsName``.env SKILL_NAMEskill 名称version``.env SKILL_VERSIONskill 版本号scene固定 CLI固定值channel``.env SKILL_CHANNEL发布渠道

• 失败处理：上报失败静默忽略，不影响主流程

执行前置（首次命中能力时必须）#

• 首次执行 1688_enroll_activity_query 前：先完整阅读 references/capabilities/1688_enroll_activity_query.md
• 首次执行 1688_enroll_offer_query 前：先完整阅读 references/capabilities/1688_enroll_offer_query.md
• 首次执行 1688_enroll_submit_item 前：先完整阅读 references/capabilities/1688_enroll_submit_item.md
• 首次执行 1688_opp_recommend 前：先完整阅读 references/capabilities/1688_opp_recommend.md
• 首次执行 configure 前：先完整阅读 references/capabilities/configure.md
• 同一会话内后续重复调用可复用已加载知识；仅在规则冲突或文档更新时重读。

授权链接处理（browser_use）#

get_ak 和 authorize 命令输出一条 JSON 后 立即退出，回调服务器作为独立后台进程继续运行（最长 300 秒）。

输出格式：

json

{
  "pending": true,
  "action": "browser_use",
  "url": "https://...",
  "markdown": "授权链接已生成！请使用 browser_use 工具打开以下链接完成授权..."
}

⚠️ 强制动作：输出中只要出现 "action": "browser_use"，Agent 必须立即 调用 browser_use 工具打开 url 字段中的链接，不得跳过、延迟或用其他方式替代。

Agent 处理流程：

1. 读到 "action": "browser_use" → 立即 用 browser_use 工具导航到 url，并向用户展示 markdown 字段内容。
2. 在页面中完成登录和授权操作（AK 模式：复制 AK；OAuth 模式：点击授权确认）。
3. 授权完成后，浏览器页面会自动将结果回调给后台服务器（ localhost），服务器直接将 AK/Token 写入本地存储。
4. browser_use 返回后，调用 python3 cli.py configure --status 确认 AK 是否已保存成功。

注意事项：

• 命令本身只输出这一条 JSON， 不会有第二条结果 JSON，无需继续等待命令输出。
• 授权回调目标是 localhost，browser_use 执行环境必须能访问本机回调端口（8080–8089）。
• 若 300 秒内未完成授权，后台服务进程自动退出，下次运行 get_ak 时会自动清理并重新启动。
• 禁止 调用系统浏览器、 open 命令或任何其他方式替代 browser_use。

异常处理#

任何命令输出 success: false 时：

1. markdown 不为空时先输出 markdown 字段（已包含用户可读的错误描述）
2. 再根据关键词追加引导：

markdown 关键词 / error_codeAgent 额外动作"AK 未配置" 或 "AK 未就绪"停止一切搜索尝试，优先执行 python3 cli.py get_ak 自动获取 AK；如自动获取失败，引导用户前往 https://clawhub.1688.com/ 登录后右上角点击🔑复制获取ak内容后执行 python3 cli.py configure YOUR_AK。 禁止浏览器替代"参数缺失" 或 "参数错误"提示用户补充缺失参数后重试"限流" 或 "429"建议用户等待 1-2 分钟后重试"报名失败"展示失败原因，引导用户检查商品或活动状态"格式错误"提示用户检查 fillFormDataList 的 JSON 格式"投放类型" 或 "cpxObjEvent"提示用户投放类型仅支持 ENQUIRY（询盘）、FEEDBACK（线索）、PAYMENT（订单）"无法识别的类目"提示用户输入正确的类目 ID 或中文名称其他仅输出 markdown 即可

参数补齐引导话术#

Agent 根据用户意图选择对应的引导话术：

招商活动报名#

"要进行招商活动报名，我需要以下信息：

1. 您想报名哪个活动？（我可以帮您查询当前有效的活动）
2. 您要提报的商品ID是什么？ 查询到建议价后，需要您确认提报价格，我再帮您提交报名。"

商机推荐#

"我可以帮您查看商机推荐，您可以告诉我：

1. 想搜索什么关键词？（可选，如：连衣裙、运动鞋）
2. 想看哪个类目的商机？（可选，如：女装、鞋、童装） 也可以直接查看默认推荐。"