# 8XAI MCP 客户下载与使用说明

适用版本：0.2.1｜说明日期：2026-11-09

下载地址：`https://plugin.8xai.cn`

使用下方安装命令，或打开下载首页复制安装命令。

## 1. 使用前准备

- 一台 Windows x64 电脑，安装并可正常使用 PowerShell 5.1 或以上版本。
- 已安装一个支持本地 MCP 的 AI 客户端，例如 Claude Desktop、Codex、Cursor 或 Cherry Studio。
- 自己的 8XAI 账号，以及进行图像处理所需的账户额度。
- 可正常访问下载站和 8XAI 服务的网络。

Windows 无需另装 Python、Node 或 Docker。macOS 安装需 Python 3.11+，详见下方专节；Linux 客户端安装不在本次范围内。

当前15个非视频页签、57个业务主功能在记录样本和已支持范围内可用。32项裁剪与19项回贴按已记录标准验收；回贴沿用矩形羽化逻辑，可能出现接缝/重影，并不承诺自动语义蒙版或全部模型组合。教学示例仍 preview；视频不在本版本范围内。

## 2. 下载与安装

1. 先退出要接入的 AI 客户端。
2. 打开服务商提供的 HTTPS 下载首页，复制页面显示的安装命令。
3. 在 Windows 开始菜单搜索并打开“Windows PowerShell”，使用当前用户运行。
4. 粘贴命令并回车，等待下载安装及自检完成。
5. 重新打开 AI 客户端。

安装命令：

```powershell
$u='https://plugin.8xai.cn'; $p=Join-Path $env:TEMP '8xai-install.ps1'; Invoke-WebRequest "$u/install.ps1" -UseBasicParsing -OutFile $p; powershell.exe -NoProfile -ExecutionPolicy Bypass -File $p -BaseUrl $u -Clients all
```

默认安装目录为 `%LOCALAPPDATA%\Programs\8XAI-MCP`。安装器会校验下载文件，并进行本地 MCP 自检；安装和自检不会提交分析或生图任务。

安装器会为 Claude Desktop、Codex、Cursor 写入 MCP 配置，同时导出 Cherry Studio 和通用配置。各客户端的应用内调用需在你的电脑上确认。服务名为 `8xai-design`，请在客户端的 MCP／工具设置中检查并启用；若客户端要求授权使用工具，请按自己的任务选择授权。

### Cherry Studio

安装完成后，在资源管理器地址栏输入：

```text
%LOCALAPPDATA%\Programs\8XAI-MCP\client-configs
```

在 Cherry Studio 的 MCP 设置中使用“从 JSON 导入”导入 `cherry.json`，再为使用的助手或 Agent 启用该 MCP。具体菜单以所装版本为准。

### 其他客户端

支持本地 MCP stdio 的客户端，可参考同目录的 `mcp.json` 导入或手动填写配置。豆包、DeepSeek等是否可以直接接入，取决于具体应用是否提供本地 MCP 入口；也可在支持 MCP 的客户端中选择相应模型。

下载站地址用于安装文件下载。仅接受远程 MCP URL 的客户端暂不适用本版本。

## 3. 准备素材

默认素材目录为当前用户的：

```text
图片\8XAI\素材
```

可在资源管理器地址栏输入 `%USERPROFILE%\Pictures\8XAI\素材` 打开。建议按服装或项目建立子目录，例如“红色连衣裙”，再放入服装、模特、场景和姿态图片。使用时告诉 AI 文件名及所在子目录。

如需使用已有素材盘，安装时可指定素材根目录。例如把素材根目录设为 `D:\服装素材`：

```powershell
$u='https://plugin.8xai.cn'; $p=Join-Path $env:TEMP '8xai-install.ps1'; Invoke-WebRequest "$u/install.ps1" -UseBasicParsing -OutFile $p; powershell.exe -NoProfile -ExecutionPolicy Bypass -File $p -BaseUrl $u -Clients all -AssetRoot 'D:\服装素材'
```

请将示例路径换成自己实际使用的目录，重新安装配置后重启 AI 客户端。

## 4. 首次登录和检查

在 AI 客户端中新建对话，可以直接发送：

> 请使用 8XAI MCP 检查登录状态，并列出当前可正式使用的页签和功能。暂不分析或生成图片。

未登录时，按提示使用自己的 8XAI 账号登录。默认会在当前系统用户下保护账号密码和令牌（Windows DPAPI，macOS 登录钥匙串）；不希望记住密码时，请明确要求登录时设置 `remember_password=false`，此时仅保存令牌。

若通过聊天输入登录信息，是否保留输入内容由所用客户端决定；本机凭据加密不会清除聊天记录。不要把密码或令牌发给客服。

本机登录状态仅表示存在可用的本地凭据；遇到登录过期或服务端认证失败时，应重新登录。

## 5. 生成第一张图片

不熟悉功能时，直接说：

> 请用八象引导我处理图片。我不懂页签和参数，请先问清楚我想改什么、保留什么，每次问一两个问题，给我推荐。先预演，等我确认后再生成。

例如“让这张更高级”，助手应先问是改善光线、背景、服装展示还是细节；“换这个”应先确认哪张是原图、哪张提供服装或元素。你已经说过的设置无需重复填写，后续可直接补充或纠正。

0.2.1 内置 `usage_guide`、`intent_guide`，覆盖15个非视频页签、57个业务功能，以及登录、预设、预演、提交、保存和恢复。客户端支持 MCP 即可调用这些引导工具；是否主动提问仍取决于客户端模型及工具权限。

安装器同时下载经过哈希校验的 `8xai-design-guide` skill 文件夹，位置为 Windows 安装目录 `versions/<版本>/guidance/8xai-design-guide`，Mac 安装目录 `current/guidance/8xai-design-guide`。支持本地 skill 的客户端可按其导入方式加载整个文件夹；不支持 skill 的客户端直接使用上述 MCP 引导工具，无需另行导入。skill 是公开操作说明，不含服务端核心生图提示词。

推荐从一张图开始。可以复制并修改下面的提示语：

> 请使用 8XAI MCP 的“整图单张”功能。素材位于已配置素材目录下的“红色连衣裙”文件夹，服装图为“服装.jpg”，模特图为“模特.jpg”。目标为服装商品展示图，生成数量设为 1。请先检查功能参数和素材，列出可选模型、分辨率、是否需要参考分析及预计生成数量，只建立本地预演计划，等我确认后再提交。如果接口无法给出准确费用，请明确说明，不要猜测。

检查 AI 给出的功能、素材、模型、分辨率、分析需求和数量。确认后再发送：

> 确认按刚才的计划提交，只生成 1 张。完成后保存到“D:\8XAI结果”，按服装文件夹和功能命名，只保存图片。

结果目录应使用你电脑上存在的磁盘和绝对路径。上述 D 盘路径是示例，请按实际情况修改。

预演计划仅在本地校验，不上传、不分析、不生成。提交可能产生参考分析及图片生成费用，具体以使用模型和 8XAI 账户实际账单为准。

图片完成后，AI 应返回保存目录。请打开图片检查效果；下载完成不等于图像效果已验收。输出目录仅保存图片，任务记录保存在应用内部数据目录。

## 6. 超时、断线或图片尚未完成

保留原来的计划 ID 和任务 ID，可以发送：

> 请检查刚才原计划的状态，只查询并继续收集原任务结果，不重新分析或生成。保存位置沿用原来的结果根目录、服装组和功能名称。

同一计划只能提交一次。尚未完成时继续查询和收集；遇到状态不明、没有已知任务 ID 或提交异常时，先核实原任务，不要直接建立新计划重做。

## 7. 更新、自检、回退和退出登录

更新：退出 AI 客户端，重新从服务商的 HTTPS 下载首页获取并运行安装命令，完成后重启客户端。

自检、回退或移除接入：在 PowerShell 中先重新下载当前安装脚本，再选择执行下面所需的一项操作：

```powershell
$u='https://plugin.8xai.cn'; $p=Join-Path $env:TEMP '8xai-install.ps1'; Invoke-WebRequest "$u/install.ps1" -UseBasicParsing -OutFile $p
```

本地自检，不分析、不生图：

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File $p -Action Doctor
```

回退到本机保留的上一安装版本（需要此前已安装过另一版本）：

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File $p -Action Rollback
```

移除安装器登记的客户端接入：

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File $p -Action Uninstall
```

移除接入会保留安装版本、配置备份、账号数据、任务记录和素材。需要删除 MCP 保存的登录信息时，请先在客户端要求调用 `auth_logout`；该操作删除本机保存的凭据，不承诺撤销远端会话。

## 8. 常见问题

| 问题 | 处理方法 |
| --- | --- |
| 无法下载／域名打不开 | 确认使用服务商提供的真实 HTTPS 地址，并检查网络；联系服务商核查下载站。 |
| 安装后看不到工具 | 完全退出并重启客户端；检查 `8xai-design` 是否启用。Cherry Studio需导入配置并绑定助手。 |
| 找不到图片／素材越界 | 把素材放到配置的素材根目录内，核对子目录、文件名和扩展名；使用已有素材盘时按第3节修改根目录。 |
| 某功能为 preview／拒绝提交 | 检查当前发布版本和功能状态；教学示例不提交收费任务。 |
| 登录失败或过期 | 核对自己的账号，按提示重新登录；不要反复猜测密码。 |
| 文件哈希校验失败 | 停止安装，重新获取安装命令；仍失败时联系服务商，不跳过校验。 |
| 提示已有配置冲突或格式无效 | 安装器会保留原文件。联系服务商协助合并，不要直接删除原有客户端配置。 |
| 超时或部分图片未保存 | 按第6节查询原计划并恢复收集，保持原输出位置，不重新提交。 |
| Mac 安装失败 | 记录 `stage`、`host` 和 `curl` 错误码。6为DNS、28为超时、60为证书，22为下载文件HTTP错误；不要关闭证书校验。 |
| Mac 提示 `compdef` 不存在 | 这是 zsh/OpenClaw 补全初始化问题，与 MCP 的 HTTPS 下载错误分开处理；不要因此删除账号或素材。 |
| 客户端没有主动引导 | 检查工具权限，明确要求“先调用 intent_guide 引导我”；可用 usage_guide 查询具体页签与功能。 |

反馈问题时请提供：客户端名称和版本、Windows版本、错误提示、发生时间，以及相关计划 ID／任务 ID。不要附带密码、令牌或完整凭据文件。

## macOS 安装与使用

新包上传部署后，先安装 Python 3.11+（Apple Silicon / Intel），退出客户端，在终端执行：

```bash
(u='https://plugin.8xai.cn'; p=$(mktemp) || exit; trap 'rm -f "$p"' EXIT; /usr/bin/curl -q -fsSL --connect-timeout 20 --max-time 180 --proto '=https' --proto-redir '=https' "$u/install.sh" -o "$p" && bash "$p" "$u" --clients all)
```

默认目录 `~/Library/Application Support/8XAI-MCP`；素材 `~/Pictures/8XAI/素材`；数据 `~/.8xai-mcp`。安装后重启客户端，Cherry Studio 导入安装目录 client-configs/cherry.json。账号信息保存在系统钥匙串，拒绝访问时不回退明文。脚本可追加 `--asset-root "/绝对路径/素材"`，以及 `--action doctor`、`--action rollback`、`--action uninstall --clients all`。

本次已完成可移植安装逻辑验证，macOS 原生环境和客户端界面仍需实机验收；当前不是免 Python 的签名原生 Mac 应用。PyPI 依赖需联网下载，wheel 内含可读代码。完整方式见 [macOS 说明](macos-installation.md)。