人人商城助手

接入人人商城开放接口（龙虾助手 API），让智能体具备查询与管理商城运营数据、商品、会员、订单与营销活动的能力。本技能仅提供只读查询与受控写操作，所有请求均发往用户自己配置的商城服务器地址。

一、安装与凭证配置

本技能通过环境变量读取凭证，无需任何平台专属配置文件。使用前请先配置以下两个环境变量（在运行 WorkBuddy 的终端 / 环境一次设置即可，重启后需重新 export）：

获取凭证：登录人人商城后台 → 插件 → 龙虾助手 → API Key 管理，获取 API Key 与「服务器地址」。

配置方式（任选其一）：

• 临时（当前会话）：在终端执行 export RR_CLAW_BASE_URL=... 与 export RR_CLAW_API_KEY=...
• 永久（推荐）：写入 shell 配置文件（~/.zshrc 或 ~/.bashrc），或在 WorkBuddy 的技能环境变量配置中填入。

> 凭证全程仅用于向用户配置的商城服务器发起请求，不会发送或落盘到任何第三方端点。

二、安全约定（必读）

• 操作的是用户线上电商系统，任何失误都可能造成直接经济损失。
• 写操作类接口提交前，必须与用户明确确认后再执行（见第七节危险操作清单）。
• 运行时仅向用户配置的 RR_CLAW_BASE_URL 发送请求，不会将 API Key 传输至任何第三方端点。
• 严禁在聊天消息中明文输出 API Key；如需展示，一律脱敏（如 lh-****-oc）。

三、认证与请求方式

请求头

• Authorization: Bearer $RR_CLAW_API_KEY

请求方法

• GET：查询类接口
• POST：提交 / 操作类接口，请求体以 application/x-www-form-urlencoded 格式提交

接口地址拼接

完整地址 = RR_CLAW_BASE_URL + 接口路由。

示例：https://example.com/wap/25/api/apps/openClaw/statistics/overview/to-do

响应约定（重要）

• 所有接口统一返回 HTTP 200，禁止以 HTTP 状态码判断成功或失败。
• 响应体为 JSON：{"error": 0, "message": "success", ...}
• 必须检查 error 字段：0 = 成功；非 0 = 业务失败（message 含错误描述），此时应停止并向用户报告错误。

发起请求（推荐用封装脚本）

优先调用 scripts/request_client.py 中的客户端（仅依赖标准库，自动读取环境变量）：

from request_client import get_client

# 自动从环境变量 RR_CLAW_BASE_URL / RR_CLAW_API_KEY 读取凭证
client = get_client()

# 查询类
data = client.get("/statistics/overview/to-do")
goods = client.get("/goods/list/get", params={"keywords": "iPhone"})

# 操作类（危险，须先确认）
client.post("/goods/operation/put-store", data={"id": 184})

也可自行用 cURL 拼接请求；无论哪种方式，都必须在拿到响应后校验 error 字段。

四、能力速查表

五、功能模块与接口文档

各模块的完整字段说明、请求 / 响应参数与示例响应，按需读取对应 references 文档：

• 数据统计模块 → references/statistics.md
• 商品查询管理模块 → references/goods.md
• 订单查询管理模块 → references/order.md
• 会员查询管理模块 → references/member.md
• 营销活动查询管理模块 → references/sales.md

读取对应文档后，按文档中的路由、参数与响应结构执行查询或操作，并在返回后校验 error 字段。

六、意图判断指南

商城字段名词解释

时间段判断

功能关键词判断

七、⚠️ 危险操作（必须二次确认）

以下接口会直接影响线上业务，执行前必须向用户明确确认，禁止自动执行：

• POST /goods/operation/put-store — 下架商品（影响前台展示）
• POST /order/operation/close — 关闭订单（不可逆）
• POST /sales/coupon/manual-stop — 停止发放优惠券（立即生效）
• POST /sales/full-free/close — 关闭满额包邮（立即生效）

执行建议流程：先向用户复述「将要对商品/订单/优惠券 X 执行 Y 操作」，得到明确确认（如「确认执行」）后再调用接口；返回后把 error 与 message 结果如实反馈给用户。