# 孙小圣 · 商品素材技能 — 安装指南

本指南供 AI 智能体与开发者阅读并执行。
目标：接入「孙小圣商品/作品素材」能力，按商品链接或抖音、YouTube、快手、小红书完整分享获取标题、主图/封面、SKU 图、详情图、视频、规格价格与卖点。

**定价**：成功 ¥0.02 / 次；失败不扣费（自动退款）。  
**控制台**：https://sxsai.cn （获取 API → API Keys）  
**API**：`POST https://api.sxsai.cn/v1/ecom/product`（抖音亦可 `/v1/ecom/aweme`）  
**MCP**：`https://api.sxsai.cn/mcp`

---

## 两种接入方式（请先选对）

### A. ChatGPT / 需 OAuth 的客户端（不要贴 API Key）

1. MCP URL 填写：`https://api.sxsai.cn/mcp`
2. 在 ChatGPT 添加自定义 MCP / 连接器后，按提示用**孙小圣账号**登录并授权（邮箱密码或手机验证码）。
3. **不要**引导用户粘贴 `sk-sxs-...` API Key；鉴权走 OAuth 2.1。
4. 授权后可用工具：`get_product_material(url)`、`get_aweme_material(url)`、`get_balance()`。
5. 详细步骤见：https://sxsai.cn/install/CHATGPT_OAUTH.md

### B. Cursor / Claude Code / 通用 MCP（静态 Header）与脚本型智能体

- 远程 MCP：请求头 `Authorization: Bearer sk-sxs-...`（控制台「API Keys」创建）。
- Skill / 脚本：下载本指南同目录文件，配置环境变量 `SXS_API_KEY`（下文步骤）。

---

## 你需要向用户确认的信息（仅方式 B）

1. 已有孙小圣账号与 **API Key**（形如 `sk-sxs-...`）。若没有，请用户打开 https://sxsai.cn →「获取 API」登录 →「API Keys」创建并复制。
2. 将 API Key 存为环境变量 **`SXS_API_KEY`**（或写入用户本地私密配置）。**禁止**把密钥写进可分享的仓库文件或本技能目录里的明文配置。
3. 若用户使用 **ChatGPT**：改走上方「方式 A」，不要索取或粘贴 API Key。

---

## 安装步骤（方式 B：Skill / 脚本，请逐步执行）

### 1. 选择技能目录

按当前环境任选其一（不存在则创建）：

| 环境 | 推荐路径 |
|------|----------|
| Claude Code | `~/.claude/skills/sxs-material/` |
| Cursor | 项目内 `.cursor/skills/sxs-material/` 或用户技能目录 |
| 通用 / 其他 | `~/.sxs/skills/sxs-material/` |

下文以 `$SKILL_DIR` 表示所选目录。

```bash
mkdir -p "$SKILL_DIR"
cd "$SKILL_DIR"
```

### 2. 下载技能文件

```bash
curl -fsSL -o SKILL.md https://sxsai.cn/install/SKILL.md
curl -fsSL -o sxs_material.py https://sxsai.cn/install/sxs_material.py
curl -fsSL -o sxs_material.mjs https://sxsai.cn/install/sxs_material.mjs
chmod +x sxs_material.py sxs_material.mjs
```

也可从 `https://api.sxsai.cn/install/` 下载同一套文件。

### 3. 配置 API Key

```bash
# 当前 shell 临时生效（推荐先验证）
export SXS_API_KEY='sk-sxs-用户自己的密钥'

# 可选：写入用户 shell 配置（勿提交到 git）
# echo 'export SXS_API_KEY=sk-sxs-...' >> ~/.bashrc
```

### 4. 验证（会产生一次成功计费 ¥0.02，失败不扣费）

```bash
python3 sxs_material.py "https://detail.1688.com/offer/676049906949.html"
```

需要 Python 3.8+（推荐 3.10+）。  
期望：stdout 打印 JSON，含 `object: ecom.product`、`product.title`、`product.main_images` 等。  
若返回 401：检查 Key；402：余额不足，请到 https://sxsai.cn 充值。

抖音作品（`object: ecom.aweme`，`type: aweme`）：

```bash
# 分享链接
curl https://api.sxsai.cn/v1/ecom/aweme \
  -H "Authorization: Bearer $SXS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://v.douyin.com/e3x2fjE/"}'

# 或 aweme_id
curl https://api.sxsai.cn/v1/ecom/aweme \
  -H "Authorization: Bearer $SXS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"aweme_id":"6894784055775071503"}'

# Skill 脚本同样可用分享链接
python3 sxs_material.py "https://v.douyin.com/e3x2fjE/"
```

成功响应要点：`object` 为 `ecom.aweme`，`product.platform` 为 `douyin`，`product.type` 为 `aweme`，含 `title` / `main_images`（封面）/ `video` / `author` / `statistics`。  
站点首页与「在线采集」页提供**自托管预存示例**（点选不扣费），可对照字段。

### 5. 可选：下载素材到本地目录

```bash
python3 sxs_material.py "商品链接" --download ./out
# 目录结构：out/main/  out/sku/  out/detail/  out/video/  out/product.json
```

Node 版：

```bash
node sxs_material.mjs "商品链接"
node sxs_material.mjs "商品链接" --download ./out
```

---

## 使用方式（安装后）

当用户说出类似意图时触发本技能：

- 「帮我获取这个 1688 链接的主图和详情图」
- 「解析这条淘宝商品，导出 SKU 图和价格」
- 「把这个天猫链接的素材整理到本地文件夹」
- 「解析这条抖音分享链接的封面和视频」

流程：从用户消息中提取商品 URL → 调用 `sxs_material.py`（或 MCP 工具 `get_product_material`）→ 向用户展示标题/图片数量/规格，并按需 `--download`。

---

## 接入 MCP（Cursor / Claude 桌面等，静态 Header）

在 MCP 客户端配置中加入（把 Key 换成用户自己的）：

```json
{
  "mcpServers": {
    "sxs-material": {
      "url": "https://api.sxsai.cn/mcp",
      "headers": {
        "Authorization": "Bearer sk-sxs-你的APIKey"
      }
    }
  }
}
```

工具：

- `get_product_material(url)` — 获取商品或抖音作品素材 JSON（¥0.02/次成功，自动识别）
- `get_aweme_material(url)` — 专用于抖音作品素材
- `get_balance()` — 查询余额

ChatGPT 请用本文开头「方式 A」，勿使用上述 Bearer 配置。详见 https://sxsai.cn/install/CHATGPT_OAUTH.md

---

## 合规与安全

- 本服务帮助商家**整理与复用自有商品素材**，通过官方 HTTP / MCP 数据接口调用。
- 不要把 API Key 写入公开仓库、聊天记录或可转发的文件。
- 不要伪造或硬编码他人密钥。
- ChatGPT 等 OAuth 客户端：只引导登录授权，不要索取或粘贴 API Key。

## 快手与小红书

- 统一入口 `POST /v1/ecom/product` 和 `get_product_material(url)` 按完整分享自动识别；保留小红书短链、查询参数及整段分享文案。
- 独立接口：`POST /v1/ecom/kuaishou`、`POST /v1/ecom/kuaishou/download`、`POST /v1/ecom/xiaohongshu`、`POST /v1/ecom/xiaohongshu/download`。
- MCP：`get_kuaishou_material(url, download)`、`get_xiaohongshu_material(url, download)`，也可显式传入真实 `photo_id` / `note_id`；普通数字不自动识别为作品 ID。
- 小红书图文 `media_kind=images`，`detail_images` 是原始图集，`video` / `videos` 为空；视频时返回封面与视频。`/download` 只对视频转存并返回 48 小时有效下载地址，图集图片不承诺 48 小时有效。
- 新平台成功仍 ¥0.02 / 次，失败自动退款。下载或本机重新查看已有结果不重新调用解析；网络重试复用 Idempotency-Key。
- 新平台不提供预设作品演示，请仅使用用户明确提供且有权使用的实际分享。文档：https://sxsai.cn/docs/kuaishou 与 https://sxsai.cn/docs/xiaohongshu。