# D5 Works MCP 安装、使用与排障指南

将 D5 Works 连接到 AI Agent，查找家具与创作资源、比较候选方案，并为清单保留来源链接。本指南介绍 MCP 与 Skill 安装、API Key 配置、使用示例和常见问题排查。

## 快速开始与支持的资源

支持查找家具商品、3D 模型、2D 资源、HDRI 环境贴图和 PBR 材质。使用前请核对返回资源的类型、尺寸、格式、许可与访问要求。搜索到商品不代表一定有对应的可下载模型，也不代表可自动导入设计软件。

- 将下方指令复制给受支持的 AI Agent，按提示完成安装。
- 创建 Works API Key，仅在受保护的配置流程中填写。不要将密钥放入共享对话、截图或日志。
- 按需重新加载 Agent，确认 Works MCP 工具可用，再执行一次简单搜索并核对来源链接。

### 安装与连接

- [下载安装包（ZIP）](https://resource.d5works.cn/mcp/d5-works-skill.zip)：获取 D5 Works Skill 及配套安装文件。
- [查看安装说明](https://resource.d5works.cn/mcp/d5-works-mcp-install.md)：了解安装步骤，或将说明链接提供给 AI Agent 协助安装。
- [创建 API Key](https://myspace.d5render.cn/works-mcp)：登录 D5 账户，创建用于连接 D5 Works 的密钥。

**MCP 服务地址（手动配置）**

如果客户端要求填写 MCP 服务地址，请复制以下地址：

```text
https://cn.api.d5render.cn/works/mcp
```

将下方指令复制到支持 MCP 和 Agent Skills 的 AI Agent 对话中，按照提示完成安装与连接。

**安装指令**

```text
请按照 https://resource.d5works.cn/mcp/d5-works-mcp-install.md 中的说明，安装 D5 Works MCP 和配套 Skill。
```

## 让 AI Agent 协助排查问题

点击本页标题下方的“LLM 请查看 llms.txt”，复制打开后的链接并提供给 Agent。这是 Works 文档索引，请让 Agent 从中找到本篇《D5 Works MCP 安装、使用与排障指南》并阅读正文。

也可以点击“以 Markdown 格式查看”，将打开的文档内容复制给 Agent，或保存为文件后上传。如果地址栏显示 `blob:`，请提供文档内容或文件，不要复制该临时地址。

同时说明失败步骤、完整报错、Agent 名称与版本、操作系统，以及基础搜索是否成功。先移除密钥、令牌和个人信息，再发送下方提示词。

**排障提示词**

```text
请根据我提供的 D5 Works MCP 指南，帮我排查使用问题。如果我提供的是 llms.txt 索引链接，请先找到《D5 Works MCP 安装、使用与排障指南》并阅读正文。先确认我的 Agent、操作系统、失败步骤和脱敏报错，分别检查安装、认证、工具可用性和资源访问权限。提出修复前说明依据，修改配置前征求确认，不要要求我在对话中粘贴 API Key。
```

- 找不到工具：确认当前 Agent 已安装并启用 MCP 服务，按该 Agent 的要求重新加载。
- 认证失败：检查密钥是否有效及账号是否正确，通过受保护的配置流程更新凭据。
- 没有合适结果：简化需求、核对资源类型，并逐项放宽筛选条件。
- 下载或导入失败：核对账号权益、许可、链接有效性、文件格式和工具支持。搜索成功不代表拥有下载或导入权限。

## 1. 安装

请在您使用的 AI 智能体中，按照以下步骤完成安装与连接。

### 1.1 安装 D5 Works MCP 和 Skill

复制本页“安装与连接”中的安装指令，粘贴至智能体对话中并发送。

![install with ai agent cursor](/images/works/mcp/install-with-ai-agent-cursor.png)

智能体将读取安装指南，识别当前客户端并检查安装包，随后说明安装位置及配置变更。请核对相关信息并确认安装。

确认后，智能体将安装 D5 Works MCP 及配套的 D5 Works Skill，同时保留已有配置。如客户端提示需要重启或重新加载，请按提示完成操作。

### 1.2 创建 API Key 并完成连接

安装完成后，访问[创建 D5 Works MCP API Key](https://myspace.d5render.cn/works-mcp)页面，登录 D5 账户并创建密钥。如尚无 D5 账户，请先完成注册。

密钥创建完成后，返回智能体对话并回复 API Key 已准备好。请勿将密钥粘贴至对话中。

按照智能体的指引，打开受保护的凭据输入界面或插件配置界面，在 Works API key 字段中自行输入密钥。客户端确认连接成功后，返回对话并回复 已连接。

请仅通过受保护的界面输入密钥，避免在聊天消息、命令、网址、截图或明文文件中泄露密钥。

### 1.3 验证安装

连接成功后，智能体将检查 Skill 和 MCP 工具的可用性，并执行一次搜索验证。

在 Codex 中，可按下图检查 D5 Works Skill 的安装与启用状态。

![verify skill installed](/images/works/mcp/verify-skill-installed.png)

D5 Works Skill 已出现在 Installed 列表中。

![verify skill enabled](/images/works/mcp/verify-skill-enabled.png)

D5 Works Skill 已启用，右上角开关处于开启状态。

Skill 检查与 MCP 搜索验证均通过后，即可开始使用。智能体将分别反馈验证结果，并提供安装包的更新与卸载说明。如验证失败，请参阅第 3 节“常见问题”。

## 2. 使用场景

D5 Works MCP 与 D5 Works Skill 可用于家具选品、空间搭配和效果图制作等设计环节。

请根据当前设计阶段选择相应场景，将示例提示词复制至智能体对话中，即可发起选品或资产搜索任务。

| 设计阶段 | 所需输入信息 | 对应场景 |
| --- | --- | --- |
| 家具选品 | 家具类型、风格、颜色和材质 | [2.1 查找真实品牌沙发](#zh-section-2-1) |
| 空间方案搭配 | 体现目标风格的参考图 | [2.2 根据参考图查找家具组合](#zh-section-2-2) |
| 替代选品 | 清晰展示单件家具的图片 | [2.3 根据单品图片查找相似家具](#zh-section-2-3) |
| 效果图制作 | 资产类别、风格和文件格式 | [2.4 获取免费 3D 模型](#zh-section-2-4) |

### 2.1 根据需求查找真实品牌沙发 {#zh-section-2-1}

提供沙发类型、风格、颜色和材质要求，获得三款真实品牌沙发的对比清单。

**提示词**

```text
请帮我查找三款来自真实家具品牌的双人沙发，要求为北欧风格、米白色、布艺面料。请列出品牌、产品名称、尺寸、材质和来源链接，并以表格对比三款产品的差异。未能核实的信息请标注为“待确认”。
```

![case 1 codex result](/images/works/mcp/case-1-codex-result.png)

案例 1：Codex 使用过程与结果预览

### 2.2 根据参考图查找家具组合 {#zh-section-2-2}

上传客厅参考图，获得包含沙发、扶手椅、茶几和落地灯的协调家具组合。

**提示词**

```text
请使用 D5 Works Skill，按照附图中的客厅设计风格，查找并搭配一组真实品牌家具，包括双人沙发、扶手椅、茶几和落地灯，并提供家具清单。
```

![case 2 attached image](/images/works/mcp/case-2-attached-image.png)

![case 2 codex result](/images/works/mcp/case-2-codex-result.png)

案例 2：Codex 使用过程与结果预览
根据家具清单评估整体配色、造型和材质的协调性，并查看各产品的详情及来源，确定适合方案的家具组合。

### 2.3 根据单品图片查找相似家具 {#zh-section-2-3}

上传清晰的扶手椅图片，获得三款造型和风格相近的真实品牌替代选项。

**提示词**

```text
请使用 D5 Works Skill，根据附图中的扶手椅查找三款造型和风格相近的真实品牌扶手椅，提供产品图片、品牌、产品名称和来源链接，并说明与参考家具的相似之处及主要差异。
```

![case 3 attached image](/images/works/mcp/case-3-attached-image.png)

![case 3 codex result](/images/works/mcp/case-3-codex-result.png)

案例 3：Codex 使用过程与结果预览

### 2.4 为效果图获取免费 3D 模型 {#zh-section-2-4}

提供模型类别、风格和文件格式，获得免费 3D 模型选项及可用的获取方式。

**提示词**

```text
请在 Works 中查找三款免费的休闲椅模型，要求为简约现代风格，文件格式为 SKP 或 D5A，并提供下载链接。
```

![case 4 codex result](/images/works/mcp/case-4-codex-result.png)

案例 4：Codex 使用过程与结果预览
确认文件格式和使用许可后，通过返回的链接下载模型。若结果提供 D5 Launcher 打开入口，请按照该方式获取资产。随后在目标软件中打开或导入模型，检查模型比例、材质和贴图。

## 3. 常见问题（FAQ）

### 3.1 安装或连接失败时如何排查？

| 问题 | 处理方式 |
| --- | --- |
| 身份验证失败 | 在受保护的 Works API key 字段中核对密钥。若密钥已过期或被撤销，请更换有效密钥后重新连接。 |
| 未显示 Works 工具 | 确认安装包已安装并启用。重启或重新加载智能体后，再次执行安装验证。 |
| MCP 可用，但未加载 Skill | 在对话中要求智能体检查 D5 Works Skill 及其支持文件，并根据提示重新加载。 |
| 无法加载安装包或安全保存密钥 | 确认所用智能体支持 MCP、Agent Skills 和受保护的凭据输入功能。 |

### 3.2 D5 Works MCP 是否支持自动摆放家具或渲染房间？

D5 Works MCP 主要提供资源搜索、产品信息查询和资产获取功能。场景导入、家具摆放及渲染需要通过相应的设计软件或其他工具完成，具体以所用工具的支持范围为准。

### 3.3 如何查看包含图片的家具清单？

D5 Works Skill 会将包含产品图片的结果整理为独立的 HTML 清单。点击智能体回复中的文件链接，即可查看产品图片、详情和来源。部分图片需要联网加载；如图片无法显示，请检查网络连接，并要求智能体确认图片来源是否有效。

### 3.4 搜索到的家具是否都有对应的 3D 模型？

家具产品与 3D 资产属于不同的检索内容，搜索结果不一定存在一一对应关系。如需查找特定家具的 3D 模型，请提供品牌、产品名称或来源链接，并要求智能体核验匹配关系。仅凭外观相似无法确认模型与产品相符。

### 3.5 为什么部分资产提供 D5 打开入口而非下载链接？

部分资产通过 D5 Launcher 提供访问入口，具体获取方式以返回结果为准。请通过该入口继续操作；如需帮助，可在对话中要求智能体说明后续步骤。操作完成后，请在目标应用中确认模型是否成功加载。

### 3.6 免费模型是否适用于所有项目？

免费模型的使用范围以资产页面标注的许可和账户权限为准。FREE 标签仅表示价格类别，并不代表适用于所有用途。使用前，请确认授权范围符合项目要求。

### 3.7 下载链接过期或访问被拒绝时应如何处理？

下载链接过期时，可在对话中要求智能体重新查询该产品及文件，并在可用时获取新的链接。如提示访问被拒绝，请确认当前连接的账户具备相应访问权限，再重新获取资产。