> ## 文档索引
> 获取完整文档索引： https://fushouagent.com/docs/llms.txt
> 先阅读此索引，了解所有可用页面。

# design

> 将 Sketch 或 Figma 设计稿转换为前端产物，并在本地列出或过滤 OpenAPI、Swagger 与 ApiFox 接口定义。

`fushou-agent design` 包含两类能力：上传本地 Sketch 或 Figma 设计稿并写入转换产物；在本地列出、筛选 OpenAPI 3.x、Swagger 2.0 或 ApiFox 文档中的接口，缩小编码 Agent 需要读取的上下文。

## 命令格式

```bash title="Terminal"
fushou-agent design \
  --file FILE \
  --output DIR
```

本地列出或过滤 API 定义：

```bash title="Terminal"
fushou-agent design openapi --list FILE
fushou-agent design openapi --filter IDS --target OUTPUT FILE
```

## 选项

| 选项 | 必填 | 类型/格式 | 默认值 | 约束与行为 |
| --- | --- | --- | --- | --- |
| `--file FILE` | 是 | 本地文件路径 | 无 | 必须是存在的普通 `.sketch` 或 `.fig` 文件，大小为 1 字节至 100 MiB。扩展名不区分大小写；相对路径从当前工作目录解析。 |
| `--output DIR` | 是 | 本地目录路径 | 无 | 生成结果的项目目录。相对路径从当前工作目录解析；目录不存在时会在写入结果前创建。路径必须能够解析为目录。 |

每个选项都只能传入一次，也可以使用 `--file=FILE` 和 `--output=DIR` 形式。命令不接受位置参数。

## 环境变量

| 变量 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `FUSHOU_DESIGN_OPEN_BROWSER` | 否 | 自动打开浏览器 | 仅值 `0` 禁止自动打开，并在终端打印需要手动访问的转换页面地址；其他值和空值均保持自动打开。 |

## 转换过程

1. 命令校验并读取设计稿，然后尝试打开浏览器转换页面。
2. 在浏览器中选择画板、完成页面设置和可选元素标记；在标记步骤点击“下一步”会立即开始转换。无法自动打开浏览器时，终端会打印可手动访问的地址。
3. 命令等待浏览器中的转换完成，最长等待 60 分钟。
4. 转换完成后，命令将结果写入 `--output` 并打印主要产物路径。

等待期间应保持命令运行。生成过程中浏览器不提供返回或取消操作；生成失败后可以保留当前选择返回标记步骤，也可以取消并让客户端以非零状态退出。按 Ctrl-C 会终止当前命令，尚未写入的结果不会生成。

## 生成结果与目录合并

目标目录会收到生成的代码和资源，并始终包含：

- `design-to-code-refactor.md`：实现与重构说明；
- `design-to-code-screenshot.png`：设计稿参考截图；
- 每个已选画板对应一个 `.txt`：该画板重构前的完整原始代码块、样式，以及适用时的小程序配置。

`design-to-code-refactor.md` 按画板名称链接对应的 `.txt` 文件，可从说明文件打开每个画板的生成内容。

目标目录中与生成结果同路径的普通文件会被覆盖，其他文件会保留。同名目录会合并；符号链接、文件与目录类型冲突，以及仅大小写或 Unicode 形式不同的冲突路径会使命令停止，不会覆盖这些路径。

成功时 stdout 会打印进度、转换提示和主要产物路径。参数校验、浏览器转换、下载或写入失败时使用非零退出码。

## 列出与过滤 OpenAPI 接口

`design openapi` 支持 `.json`、`.yaml` 和 `.yml` 文件，不设业务文件大小上限，也不访问网络。OpenAPI 3.x 文档会保持其版本；Swagger 2.0 与 ApiFox 文档会先归一化为 OpenAPI 3.0，再进行列出或过滤。

列出接口：

```bash title="Terminal"
fushou-agent design openapi --list './docs/openapi.json'
```

stdout 按文档中的原始 `paths` 与 HTTP 方法顺序输出 Markdown 表格，列为 `ID`、`Method`、`Path` 和 `Description`。描述优先使用 `summary`，没有时使用 `description`。ID 从 1 开始，只在当前文档与本次命令输出中有效。

按 ID 过滤并写入新文档：

```bash title="Terminal"
fushou-agent design openapi \
  --filter '1,3-5,8' \
  --target './output/openapi.filtered.json' \
  './docs/openapi.json'
```

`IDS` 支持逗号、空白和闭区间，可混合书写；重复 ID 会去重并按升序处理。`--target` 必须以 `.json`、`.yaml` 或 `.yml` 结尾。父目录不存在时会创建，同名文件会被替换。

筛选结果包含所选接口及其引用内容，未使用的组件会移除。命令仅处理本地文件，不会下载外部引用。引用有误、ID 越界、格式错误或扩展名不受支持时，命令返回非零退出码，不会写入目标文件。

命令输出筛选后的 API 定义文件。需要生成接口代码时，请让您使用的编码工具读取该文件。

## 示例

转换 Sketch 文件并写入当前项目的 `src/generated-page`：

```bash title="Terminal"
fushou-agent login
fushou-agent design \
  --file './designs/checkout.sketch' \
  --output './src/generated-page'
```

不自动打开浏览器：

```bash title="Terminal"
export FUSHOU_DESIGN_OPEN_BROWSER=0
fushou-agent design \
  --file '/absolute/path/dashboard.fig' \
  --output '/absolute/path/project/src/dashboard'
```

运行后复制终端打印的地址到浏览器，并在 60 分钟内完成转换。

## 常见错误

- 缺少选项或重复传入选项：分别提供一次 `--file` 和 `--output`。
- 设计稿不是普通文件、为空、超过 100 MiB 或扩展名不受支持：选择符合要求的 `.sketch` 或 `.fig` 文件。
- 浏览器未打开：使用终端打印的地址，或设置 `FUSHOU_DESIGN_OPEN_BROWSER=0` 后重新运行。
- 等待超过 60 分钟：重新运行命令，并及时在浏览器中完成转换。
- 目标目录写入失败：检查父目录权限，以及现有路径是否存在符号链接或类型冲突。
- OpenAPI ID 越界或范围倒序：重新运行 `--list`，再从本次输出选择有效 ID。
- OpenAPI 过滤失败且提示本地引用不存在：修复源文档中的 `$ref` 后重试；命令不会生成带悬空引用的目标文件。