1688-marketing-skill

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

环境准备

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

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

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

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

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

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

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 总览

输出格式

所有命令统一输出 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 按下方「异常处理」应对即可。

安全声明

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

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

环境变量（.env）

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

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

埋点上报

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

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

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

• 上报参数：

  参数	值来源	说明
  apiName	固定 null	固定传 null
  skillsName	.env SKILL_NAME	skill 名称
  version	.env SKILL_VERSION	skill 版本号
  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 秒）。

输出格式：

{
  "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. 再根据关键词追加引导：

参数补齐引导话术

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

招商活动报名

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

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

商机推荐

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

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