Impeccable Skill 使用教程：让 Codex 和 Claude Code 改掉 AI 网页味

1. 为什么 AI 写的网页总有一股“模板味”你大概遇到过这种场景让 Codex 或 Claude Code 做一个“现代、专业、有高级感”的落地页出来的东西一眼就能认出来——紫蓝渐变铺满首屏深色背景配霓虹描边超大标题下面跟着一排圆角卡片每张卡片里再套一个圆角方形图标。页面不算丑但就是像从同一个模板里抠出来的换个 logo 就能当另一个产品的官网。这不是模型不会设计而是它在没有上下文的情况下只能从训练数据里挑“最常见、最安全”的视觉答案。紫蓝渐变、毛玻璃、发光球体是第一代套路现在换成了暖米色背景、超大衬线标题、细边框配大阴影、01/02/03 编号章节。单独用哪一个都没错问题是模型在不了解你产品的情况下反复用同一套组合。Impeccable 就是冲着这个问题来的。它是一个开源的设计 Skill不重新发明网页生成平台而是把设计语汇、项目上下文、审查命令和反模板化检测器塞进 Codex、Claude Code、Cursor 这些 AI 编程工具里让智能体在真实代码库里改页面。它把设计工作拆成 23 个有明确职责的命令用 PRODUCT.md 和 DESIGN.md 保存受众、品牌语气、颜色、字体、组件和禁用风格再用确定性检测器找出能定位到文件与行号的问题。下面我从接入配置讲到改稿验证把 Codex 和 Claude Code 两条路径都走一遍。2. 接入前的准备TaoToken 统一 Key 与 Node 环境Impeccable 本身是本地 Skill安装和检测命令不需要大模型 API Key。但当你用 Codex 或 Claude Code 调用/impeccable critique、/impeccable craft这类需要 LLM 评审的命令时背后还是要走模型接口。这时候用 TaoToken 的统一 Key 最省事——一个 Key 同时给 Codex 和 Claude Code 用不用在两个工具里分别维护不同的凭证。TaoToken 的定位是统一模型接入层官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。你需要先去控制台创建一个 API Key位置在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建完在 API Keys 页面复制出来形如sk-开头的一串字符。这个 Key 后面会分别填进 Codex 的config.toml和 Claude Code 的settings.json。环境方面Impeccable 当前安装器要求 Node.js 22.12 或更高版本。如果你机器上还是 18.x别急着升级生产运行时用 nvm 或 fnm 单独准备一个兼容的 Node 环境就行# 用 fnm 安装并切换到 Node 22 fnm install 22 fnm use 22 node -v # 期望输出 v22.x.x确认 Node 版本后从你的项目根目录执行安装器。它会自动识别当前项目用了哪些 AI 编程工具并询问装到项目级还是全局。正式开发建议项目级规则能随仓库版本管理npx impeccable install如果要在脚本里明确指定 Codex 并跳过交互可以这样npx impeccable install --providerscodex --scopeproject同时装 Codex、Claude Code 和 Cursornpx impeccable install --providerscodex,claude,cursor --scopeproject装完重启 AI 编程工具再执行/impeccable init初始化项目上下文。这一步会问你受众、品牌语气、视觉参照和明确不想要的风格结果写进 PRODUCT.md。现有项目还能生成 DESIGN.md记录颜色、字体、圆角、组件等约束。注意这两个文件是设计文档不要往里写 API Key、客户隐私或内部密码。3. 可复制配置settings.json 与 config.toml 骨架这一节是全文最需要你动手的部分。Codex 和 Claude Code 读取配置的位置不同我把两份骨架都列出来你按自己的工具选一份改。3.1 Claude Code 的 settings.jsonClaude Code 的配置通常放在项目根目录的.claude/settings.json或者用户级的~/.claude/settings.json。项目级更适合团队协作因为可以随仓库提交。骨架如下{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [ Skill(impeccable), Bash(npx impeccable:*) ] } }几个关键点。ANTHROPIC_BASE_URL填 TaoToken 的 API 端点注意这里不带 UTM 参数就是干净的https://taotoken.net/api。ANTHROPIC_AUTH_TOKEN填你从控制台复制的 Key。permissions.allow里放行 Impeccable 的 Skill 调用和npx impeccable命令否则每次执行检测都会弹权限确认很烦。如果你是从插件市场装的 Impeccable还需要先添加市场/plugin marketplace add pbakaus/impeccable然后在/plugin菜单里安装。插件用户通过菜单更新不走npx impeccable update。3.2 Codex 的 config.tomlCodex CLI 的配置一般在~/.codex/config.toml项目级可以放在.codex/config.toml。骨架如下model gpt-5-codex model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY [skills] enabled true paths [.agents/skills]然后在 shell 里导出环境变量或者写进.envexport TAOTOKEN_API_KEYsk-你的TaoToken密钥Codex 对 Skill 的入口和 Claude Code 不一样。官方 FAQ 特别说明Impeccable 不一定出现在普通斜杠命令菜单里。你可以打开/skills查看或者输入$查找 Skill需要明确触发时直接在任务里写“使用 impeccable skill”。项目级 Skill 通常位于.agents/skills/用户级在~/.agents/skills/。Impeccable 还能为 Codex 装项目级设计 Hook。安装或更新后打开/hooks检查并批准它会在 AI 修改界面文件后自动跑检测把新问题反馈给 Codex。Hook 定义更新后 Codex 可能要求重新批准这是正常的信任机制别为了省事关掉安全检查。3.3 参数对照表配置项Claude CodeCodex说明配置文件.claude/settings.json~/.codex/config.toml项目级优先API 端点ANTHROPIC_BASE_URLbase_url均为https://taotoken.net/api密钥字段ANTHROPIC_AUTH_TOKENenv_key指向环境变量同一个 TaoToken KeySkill 路径插件市场自动管理.agents/skillsCodex 需手动确认路径Hook 入口插件内置/hooks批准Codex 独有注意两份配置里的 Key 是同一个但字段名不同。别把ANTHROPIC_AUTH_TOKEN直接抄进config.tomlCodex 读的是env_key指向的环境变量。4. 验证请求一次改稿前后对比配置填完先别急着跑完整工作流。用一条最小命令验证链路通不通再进入改稿对比。4.1 验证模型接口在 Claude Code 里执行/impeccable critique the pricing page如果配置正确它会读取 PRODUCT.md 和 DESIGN.md然后从层级、清晰度、情绪、角色场景几个角度给出评审意见。如果报 401 或连接失败说明 Key 或端点填错了回到第 3 节检查。在 Codex 里则这样触发使用 impeccable skillcritique 当前项目的 pricing 页面只输出问题和文件位置不要改代码。4.2 跑确定性检测器只做静态检查时不需要模型 Key直接跑 CLInpx impeccable detect src/它会返回文件、行号、规则名称和退出码可以接进 CI 或 PR 检查。只查字体或布局npx impeccable detect src/ --scope type npx impeccable detect src/ --scope layout查 GPT/Codex 常见特征npx impeccable detect src/ --gpt4.3 改稿前后对比我试过拿一个典型的 AI 生成落地页做对比。改稿前检测器报出这些问题首屏用了紫蓝渐变规则命中、卡片嵌套两层圆角规则命中、正文对比度低于 WCAG AA规则命中、标题和正文尺寸只差 4px规则命中。改稿时只跑一条命令/impeccable polish the landing page要求它不新增颜色、字体和卡片样式只在现有设计系统内调整层级和比例。改完再跑一次npx impeccable detect src/紫蓝渐变和卡片嵌套的告警消失对比度提升到 AA 以上标题与正文的字号差拉开到 12px。整个过程没有换配色方案只是把模型默认的“平均答案”拉回到项目自己的设计约束里。提示polish是发布前整理命令适合最后一轮统一设计系统。如果你要的是从零规划用craft或shape要的是工程验收用audit。5. 本篇常见错排查5.1 安装后/impeccable不出现在菜单里Codex 用户最容易踩这个坑。Impeccable 不一定注册成普通斜杠命令打开/skills或输入$查找或者直接在任务里写“使用 impeccable skill”。Claude Code 用户如果从插件市场装确认/plugin菜单里 Impeccable 是启用状态。5.2 检测器报了一堆误报--gpt规则里有一条“Codex 常用网格背景”但地图、测量工具、蓝图界面用网格是有业务意义的。Impeccable 支持规则、文件和值级别的忽略配置但每个例外都要写清楚原因别为了让 CI 变绿全部关掉。误报本身是信号提醒你这条规则在当前语境下不适用。5.3 模型接口 401 或超时先确认ANTHROPIC_BASE_URL和base_url填的是https://taotoken.net/api不带任何查询参数。再确认 Key 是从控制台复制的完整字符串没有多余空格。Codex 用户检查env_key指向的环境变量是否真的导出了echo $TAOTOKEN_API_KEY能打印出来才算生效。5.4 Node 版本不够npx impeccable install报引擎不兼容说明当前 Node 低于 22.12。用node -v确认然后用 fnm 或 nvm 切到 22.x。旧项目不必升级生产运行时单独给 CLI 准备兼容环境即可。5.5 Live Mode 写回失败/impeccable live目前还是 Beta复杂框架、状态管理和非标准构建流程可能影响预览或写回。正式项目里先提交当前代码保留可回退点。接受变体后仍要看 git diff、跑测试确认没破坏组件复用、响应式布局和无障碍语义。5.6 Hook 反复要求批准Codex 的 Hook 定义更新后会要求重新批准这是信任机制不是 bug。不要通过关闭安全检查来绕过正常批准即可。6. 把去 AI 味工作流固定下来第一次用不必跑完 23 个命令。先完成三步npx impeccable install、/impeccable init、/impeccable polish the page you care about然后跑npx impeccable detect src/看它指出的问题是否符合当前产品语境。能解释、能验证、能安全写回代码这套 Skill 才比“帮我把页面做高级一点”更有价值。长期在 Codex 和 Claude Code 里做前端迭代的话建议把 TaoToken 的 Key 配成统一入口省得在两个工具里分别维护凭证。模型对话可以在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 直接试接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。如果你要跑长期编码或 Agent 任务Coding Plan 在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。Claude Code 相关的接入细节可以看 https://taotoken.net/claudecode?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 。最后提醒一句Impeccable 的规则会过时。今天被识别为 AI 套路的米色背景、衬线标题、网格线本来都是正常设计手段问题在于无差别滥用。检测不等于设计消除紫蓝渐变和卡片嵌套只能减少常见问题产品定位、用户研究和信息架构仍然需要人来负责。把确定性 CLI 当门禁把主观评审当候选意见两者分开看这套工作流才能长期跑下去。