# 新手接入教程

跟着做就行，不需要会写代码。卡住了就把屏幕上的文字（**不要包含密钥**）发给 AI，问它“这一步怎么办”。

> 安全第一：Client Secret、Refresh Token、AWS 密钥、紫鸟密码，**只在 `xander setup` 里输入**（输入时不显示）。不要贴到聊天里。万一贴了，去对应后台重新生成一个。

## 1. 准备电脑

1. 安装 Node.js：打开 https://nodejs.org ，下载 **LTS** 版本（需要 22.13 或更高），双击安装，一路“下一步”。
2. 打开终端：
   - Mac：按 `⌘ + 空格`，输入“终端”，回车。
   - Windows：开始菜单搜索“PowerShell”，打开。
3. 输入 `node -v` 回车，看到 `v22.13.0` 或更大的数字就对了。
4. 下载本插件：在 GitHub 页面点绿色的 **Code → Download ZIP**，解压到一个好找的位置（比如“文档/xander”）。在终端里进入这个文件夹：
   - Mac：输入 `cd `（cd 后面有空格），把文件夹拖进终端窗口，回车。
   - Windows：在文件夹空白处按住 Shift 点右键 →“在此处打开 PowerShell 窗口”。
5. 输入 `npm link` 回车（只需一次）。之后在任何地方都能用 `xander` 命令。
   - Mac 提示权限不足：改用 `sudo npm link`，输入开机密码（不显示）回车。
   - 实在不行：以后把 `xander` 换成 `node cli/xander.js` 也一样。

## 2. 接入店铺数据（卖家接口 SP-API）

这是“私有应用自授权”：你自己给自己的店铺建一个只有你能用的应用，不经过任何服务商。

**第一次需要注册开发者（只做一次）：**

1. 用主账号登录卖家后台（Seller Central）。
2. 右上角 **设置 → 用户权限**，页面下方找到 **“开发者中心”/“开发应用”**（也可以直接访问 https://sellercentral.amazon.com/sellingpartner/developerconsole ，欧洲站把 `.com` 换成 `.co.uk` 等）。
3. 点“提出申请/Proceed to Developer Profile”，填开发者资料：
   - 开发者类型选 **“私有开发者：我为自己的公司开发应用”**。
   - 用途选你需要的数据（商品、库存、订单、财务、品牌分析等）。
   - 安全问题如实回答（数据只存本机、使用钥匙串加密等）。
4. 提交后等审核（一般 1–3 天，会邮件通知）。

**审核通过后：**

1. 开发者中心 → **添加新应用客户端**：
   - 应用名称：随便，比如 `xander-local`。
   - API 类型：**SP API**。
   - 角色：至少勾选 **商品列表、定价、库存与订单跟踪、财务与会计、亚马逊物流**；品牌卖家加勾 **品牌分析**。
2. 保存后，在应用列表那一行点 **LWA 凭证 → 查看**，得到：
   - **客户端编号（Client ID）**：`amzn1.application-oa2-client.` 开头
   - **客户端密钥（Client Secret）**
3. 同一行点 **授权 → 授权应用**，得到 **刷新令牌（Refresh Token）**：`Atzr|` 开头。
4. 卖家后台 → 设置 → **账户信息 → 商家记号（Merchant Token）**：这就是你的 **卖家 ID**。
5. 终端运行 `xander setup`，选“店铺数据”，按提示填入。向导会立即测试连接。

> 以后在应用里加了新角色，要**重新授权**生成新的 Refresh Token，再跑一次 `xander setup`。

## 3. 接入广告数据（Amazon Ads API）

广告接口和卖家接口是两套授权，需要单独申请一次。

1. **建一个 Login with Amazon 安全配置文件**：打开 https://developer.amazon.com ，登录（可用卖家账号）→ 顶部“Login with Amazon” → **Create a New Security Profile**，名称和说明随便填。
2. 建好后点这个配置文件的 **Web Settings → Edit**：
   - 记下 **Client ID** 和 **Client Secret**。
   - **Allowed Return URLs** 填：`https://www.amazon.com`，保存。
3. **申请 Ads API 权限**：打开 https://advertising.amazon.com/API/docs/en-us/guides/onboarding/overview ，按“Apply for access”填表。个人自用选 **Direct advertiser（直接广告主）**，填上一步的安全配置文件。等邮件（通常几天）。
4. 批准后，按邮件说明把安全配置文件关联到 Ads API。
5. 终端运行 `xander setup`，选“广告数据”：
   - 选对应的店铺，填 Client ID、Client Secret，返回网址默认 `https://www.amazon.com`。
   - 向导给出一个网址 → 复制到浏览器打开 → 登录**有广告的那个账户** → 点“允许”。
   - 浏览器会跳到亚马逊首页，**地址栏里有一长串带 `code=` 的网址**，整条复制回终端（几分钟内有效）。
   - 向导列出广告 profile，自动对应站点（选 seller 类型），确认即可。

常见问题：
- `redirect_uri_mismatch`：第 2 步填的返回网址和向导里的不一致。
- `unauthorized_client`：Ads API 还没批准，或安全配置文件还没关联。
- `invalid_grant`：code 过期了，重新走第 5 步。

## 4. 卖家精灵 MCP（可选）

用于关键词和竞品的市场估算数据。本插件不保存它的密钥。

1. 在卖家精灵官网找到 MCP 服务（需要对应套餐），拿到你的专属 MCP 地址。
2. 加到你用的 AI 里：
   - Claude Code：终端运行 `claude mcp add --transport http sellersprite <你的地址>`
   - Claude 桌面版：设置 → 连接器 → 添加自定义连接器
   - Codex：编辑 `~/.codex/config.toml`，加入
     ```toml
     [mcp_servers.sellersprite]
     url = "<你的地址>"
     ```
3. 重启 AI。之后做关键词/竞品时会自动用上，数据会标成“第三方估算”。

## 5. 云备份档案库（可选）

档案库默认只在本机。想在两台电脑间同步、或防止电脑坏了丢数据：

**简单办法**：把数据目录放进 OneDrive/iCloud。设置环境变量 `XANDER_HOME` 指向同步盘里的一个文件夹即可（不要两台电脑同时使用）。

**加密备份到你自己的 AWS S3：**

1. AWS 控制台 → S3 → **创建存储桶**：名字随意（全球唯一）、区域就近，**保持“阻止所有公开访问”**，建议开启“存储桶版本控制”。
2. IAM → 用户 → **创建用户**（如 `xander-backup`），不给控制台权限 → 直接附加内联策略（把 `你的桶名` 换掉）：
   ```json
   {
     "Version": "2012-10-17",
     "Statement": [{
       "Effect": "Allow",
       "Action": ["s3:GetObject", "s3:PutObject"],
       "Resource": "arn:aws:s3:::你的桶名/xander-zaozao/*"
     }]
   }
   ```
3. 这个用户 → 安全凭证 → **创建访问密钥**（用途选“在 AWS 外部运行的应用程序”），记下访问密钥 ID 和秘密访问密钥。
4. `xander setup` → “云备份”，填桶名、区域、密钥，再设置一个**同步口令**（加密用，忘了就解不开，请记好）。
5. 以后：`xander sync push` 备份；换电脑后先 `xander setup` 填同样的信息，再 `xander sync pull --replace` 恢复。

## 6. 紫鸟浏览器（可选，高风险）

只在官方接口做不到时用（比如部分促销设置）。

1. 确认你的紫鸟账号有 WebDriver / 开放接口权限（企业版通常要管理员开通）。
2. 按紫鸟官方 WebDriver 文档，用 WebDriver 模式启动客户端（常见参数 `--run_type=web_driver --ipc_type=http --port=16851`）。
3. `xander setup` → “紫鸟浏览器”，填端口、公司名、用户名、密码。
4. 要用的时候，在开关面板里打开“紫鸟控制”；用完关掉。每次操作仍需你批准具体步骤。

## 7. 开关面板和第一次练习

1. 终端运行 `xander panel`，浏览器会打开面板（网址里带一次性口令，别发给别人；关掉终端面板就停止）。
2. 打开 **演练模式**（执行只记录、不提交）。
3. 打开 **新增否定关键词** 这一个开关。
4. 回到 AI 对话：“看看我最近 14 天的搜索词，有没有花了钱没出单、明显不相关的词，帮我出一个加否定的提案。”
5. AI 会给你一张表：哪个活动、哪个广告组、什么词、为什么。确认无误后说“批准执行”。
6. 演练成功后，关掉演练模式，再真实执行一次，看回读结果是“已生效”。
7. 熟悉以后，再按需要打开其他开关。

## 8. 手动安装（备用）

插件目录装不上时：

- **Codex**：编辑 `~/.codex/config.toml`，加入（路径换成你解压的位置，Windows 用 `/` 或 `\\`）：
  ```toml
  [mcp_servers.xander]
  command = "node"
  args = ["/Users/你/Documents/xander/server/index.js"]
  ```
  再把 `skills/` 里的 7 个文件夹复制到 `~/.codex/skills/`。
- **Claude 桌面版**：设置 → 开发者 → 编辑配置，在 `claude_desktop_config.json` 里加入
  ```json
  { "mcpServers": { "xander": { "command": "node", "args": ["/Users/你/Documents/xander/server/index.js"] } } }
  ```
  技能：把 `skills/` 下每个文件夹分别压缩成 zip，在 设置 → 功能 → 技能 里上传。
- `xander install` 会按你电脑上的实际路径打印这些配置。

## 9. 遇到问题

1. 先运行 `xander doctor`，它会逐项告诉你哪里不通、为什么。
2. 国内网络连亚马逊接口超时：确认代理已打开；可以设置环境变量 `NODE_USE_ENV_PROXY=1`（配合 `HTTPS_PROXY=http://127.0.0.1:你的代理端口`）让 Node 走代理。
3. AI 的工具列表里没有 `xander_` 开头的工具：重启 Claude/Codex；还不行就用第 8 节手动安装。
4. 还解决不了：在 GitHub 提 Issue，附上 `xander doctor` 的输出（它不会打印密钥）。