1. 为什么要在 Claude Code 里用 ui-spec 生成 UI 设计说明如果你正在做前端或移动端开发大概率遇到过这种场景设计师丢过来一张 UI 稿你需要把它翻译成一份开发能直接照着写的设计说明文档——层级结构、间距、颜色、切图清单、交互逻辑一个都不能少。手工写一份完整的 UI 设计规范熟练的人也要一两个小时遇到多张图更是折磨。Claude Code 的ui-spec命令就是来解决这个问题的。它本质上是一个自定义斜杠命令你把设计图路径传进去它按照预设的角色提示词UI 设计规范分析师和输出模板生成一份结构化的 Markdown 设计说明文档保存到项目的.claude/ui-specs/目录下。适合谁用前端工程师、全栈开发者、独立开发者、需要快速把设计稿转成开发文档的小团队。但这里有个前提ui-spec命令要能稳定调用模型而 Claude Code 默认走的是 Anthropic 官方通道国内网络环境下经常连不上或者超时。我试过几种方案后最终用 TaoToken 的统一 Key 接入来解决——它提供兼容 Anthropic 的 API 通道只要在settings.json里改几行配置Claude Code 的所有命令包括ui-spec就能稳定跑起来。这篇就聚焦一件事从settings.json配置骨架入手把 TaoToken 统一 Key 接进 Claude Code然后跑通ui-spec命令输出一份结构化的 UI 设计说明。全程可复制、可验证。2. TaoToken 前置准备拿到统一 Key 和 API 地址在动settings.json之前你需要先准备好两样东西一个可用的 API Key以及确认 API 通道地址。TaoToken 的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 注册登录后进入控制台。API 基础地址是 https://taotoken.net/api 注意这个地址不加 UTM 参数直接用于配置。具体操作路径进入控制台后找到 API Keys 管理页面deep linkhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 创建一个新的 Key。建议给这个 Key 起个能识别的名字比如claude-code-ui-spec方便后续排查是哪个项目在用。创建完成后Key 只会完整显示一次复制下来存到安全的地方。这个 Key 就是后面settings.json里要填的凭证。注意不要把 Key 直接提交到 Git 仓库。推荐用环境变量引用或者把settings.json加入.gitignore。后面配置骨架里我会给出环境变量引用的写法。如果你还想先验证一下模型通道是否正常可以到模型对话页面deep linkhttps://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 发一条测试消息确认 Key 有额度、通道能通。这一步能省掉后面很多到底是配置错了还是 Key 没额度的排查时间。3. settings.json 配置骨架把 TaoToken 接进 Claude CodeClaude Code 的配置分几个层级全局配置在~/.claude/settings.json项目级配置在项目根目录的.claude/settings.json。ui-spec这种命令属于项目级工作流建议把配置放在项目级这样团队成员拉下来就能用。下面是一份可直接复制的配置骨架。核心思路是通过env字段注入 API 地址和 Key让 Claude Code 走 TaoToken 的兼容通道。{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: ${TAOTOKEN_API_KEY}, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [ Read, Write, Bash(mkdir:*) ] } }几个关键点说明ANTHROPIC_BASE_URL指向 TaoToken 的 API 地址这是让 Claude Code 不走官方通道、改走统一 Key 通道的核心。ANTHROPIC_AUTH_TOKEN用${TAOTOKEN_API_KEY}引用环境变量避免把明文 Key 写进文件。你需要在 shell 里设置这个环境变量export TAOTOKEN_API_KEY你的KeyWindows 用户可以在系统环境变量里添加或者用 PowerShell$env:TAOTOKEN_API_KEY你的KeyANTHROPIC_MODEL指定默认模型。ui-spec需要理解图片内容并生成结构化文档建议用能力较强的模型。具体可用模型名以 TaoToken 控制台或文档为准deep linkhttps://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。permissions.allow里加了Write和Bash(mkdir:*)因为ui-spec命令需要创建.claude/ui-specs/目录并写入 Markdown 文件。如果不加命令跑到写文件那一步会被权限拦截。配置写好后可以用 Claude Code 的配置检查命令确认加载正常claude config list如果看到env里的ANTHROPIC_BASE_URL显示为 TaoToken 地址说明配置生效了。4. 定义 ui-spec 命令并跑通验证配置好通道后接下来定义ui-spec命令本身。Claude Code 的自定义命令放在.claude/commands/目录下文件名就是命令名。创建.claude/commands/ui-spec.md--- description: 根据 UI 设计图生成结构化设计说明文档 --- 你是一名专业的 UI 设计规范分析师。请严格根据图片生成 UI 设计规范文档。 任务生成 UI 设计说明文档含层级、交互、切图及注意事项 你将获得一张或多张 UI 设计图片。请严格遵循图片上的所有可见信息不得自由发挥不得添加图片中不存在的元素、颜色、尺寸、文字、交互行为、层级关系或注意事项。 如果某些数值无法从图片中精确判断例如具体像素值、颜色十六进制码请如实说明无法精确判断依据图片视觉比例估算或图片未显示该细节禁止伪造。 图片路径$ARGUMENTS 输出要求 1. 全局设计基准假设屏幕宽度并说明理由 2. 元素层级关系树状结构 3. 布局结构描述 4. 页面结构示意图文本字符绘制 5. 每个元素的详细规范尺寸/位置/颜色/内外边距/内容/背景/其他样式 6. 切图清单文件名/尺寸/格式/用途 7. UI 交互逻辑说明仅基于图片可见的交互暗示 8. 其他注意事项 输出格式生成 Markdown 文件保存到项目根目录下的 .claude/ui-specs/ 文件夹中若不存在则创建。 文件名ui-spec-页面简述.md或默认 ui-design-spec.md。这个命令定义参考了 UI 设计规范分析的标准角色设定核心约束是严格基于图片、不伪造数值。定义好之后在 Claude Code 里执行/ui-spec ./designs/homepage.png符号后面跟图片路径Claude Code 会把图片作为上下文传给模型。执行后你应该看到模型先读取图片然后按模板逐段生成内容最后调用 Write 工具把 Markdown 文件写到.claude/ui-specs/目录。终端会显示文件创建成功的提示。验证输出ls .claude/ui-specs/ cat .claude/ui-specs/ui-design-spec.md打开生成的 Markdown检查几个关键点层级树是否和图片一致、切图清单是否列出了所有独立资源、交互说明是否只写了图片上能看到的交互而不是凭空编造。如果发现模型添加了图片里没有的元素说明提示词约束还不够严可以在命令定义里加强禁止添加的措辞。5. 本篇常见错误排查配置和调用过程中最容易卡在下面几个地方。报错一401 Unauthorized或invalid api key这是 Key 没生效。先确认环境变量是否真的设置成功echo $TAOTOKEN_API_KEY如果输出为空说明环境变量没设上。注意settings.json里的${TAOTOKEN_API_KEY}是引用语法它依赖 shell 环境变量存在。如果你在 IDE 里跑 Claude CodeIDE 可能没有继承 shell 的环境变量需要在 IDE 的终端配置里单独设置。报错二Connection timeout或ECONNREFUSED检查ANTHROPIC_BASE_URL是否写成了https://taotoken.net/api注意不要多加斜杠或路径。如果地址对但还是超时确认本地网络能正常访问该地址curl -I https://taotoken.net/api报错三ui-spec命令执行后没有生成文件大概率是权限问题。检查settings.json的permissions.allow里是否有Write和Bash(mkdir:*)。另外确认.claude/ui-specs/目录的父目录.claude/存在且可写。如果项目根目录没有.claude/文件夹先手动创建mkdir -p .claude/commands .claude/ui-specs报错四生成的文档里出现图片中不存在的元素这是模型自由发挥了。解决办法是在命令定义的提示词里加强约束明确写如果图片未显示某属性写图片未显示禁止推测。也可以在调用时追加一句/ui-spec ./designs/homepage.png 严格基于图片不要添加图片中不存在的元素报错五模型名不被识别ANTHROPIC_MODEL填的模型名如果 TaoToken 通道不支持会报模型不存在。到 TaoToken 文档页deep linkhttps://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 确认当前支持的模型列表换成可用的名字。6. 长期使用建议与接入入口如果你只是偶尔跑一两次ui-spec按上面的配置就够了。但如果你打算把 Claude Code 作为日常开发工具经常用ui-spec、代码生成、重构等命令建议关注 TaoToken 的 Coding Plandeep linkhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。它针对长期编码场景做了额度优化比按量计费更适合高频调用。另外几个实用建议把.claude/settings.json里的 Key 引用方式统一成环境变量团队协作时每个人用自己的 Key配置文件可以安全提交。ui-spec命令定义也可以提交到仓库团队成员拉下来就能用同一套提示词保证生成的文档格式一致。如果项目有多个设计稿可以批量调用/ui-spec ./designs/page-a.png ./designs/page-b.png模型会分别处理每张图生成对应的设计说明文件。接入文档和 API Keys 管理入口API Keys 管理https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite模型对话验证https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite配置骨架跑通一次之后后面就是复制粘贴的事。真正花时间的不是配置而是把ui-spec的提示词调教到符合你团队的设计规范——这一步值得多花点心思因为提示词的质量直接决定生成文档的可用性。