design - 赋手智能体文档

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

命令格式

fushou-agent design \
  --file FILE \
  --output DIR

本地列出或过滤 API 定义：

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` 禁止自动打开，并在终端打印需要手动访问的转换页面地址；其他值和空值均保持自动打开。

转换过程

命令校验并读取设计稿，然后尝试打开浏览器转换页面。
在浏览器中选择画板、完成页面设置和可选元素标记；在标记步骤点击“下一步”会立即开始转换。无法自动打开浏览器时，终端会打印可手动访问的地址。
命令等待浏览器中的转换完成，最长等待 60 分钟。
转换完成后，命令将结果写入 --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，再进行列出或过滤。

列出接口：

fushou-agent design openapi --list './docs/openapi.json'

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

按 ID 过滤并写入新文档：

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：

fushou-agent login
fushou-agent design \
  --file './designs/checkout.sketch' \
  --output './src/generated-page'

不自动打开浏览器：

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 后重试；命令不会生成带悬空引用的目标文件。