企业官网建设流程全解析

1. 一个人做 Dice Paradise 前端，卡点到底在哪

Dice Paradise 是一款把快艇骰子玩法搬到海岛度假场景里的休闲多人游戏，前端要同时承载大厅、房间、对局、排行榜、活动中心、个人中心这些页面。如果你也是一个人扛下产品、UI、前端、测试全部角色，真正拖慢进度的往往不是某个复杂算法，而是「想法到可运行页面」之间那段重复劳动：布局搭一遍、组件拆一遍、类型补一遍、样式再调一遍。

我试过纯手写的方式推进，一个大厅页面从设计稿到能点，断断续续要花掉两三个晚上。后来我把流程拆成三段：ChatGPT 负责把模糊需求拆成可执行清单，Codex 负责把清单补成组件逻辑，Claude Code 负责按项目规范校验前端结构。三者各管一段，中间用一份统一的配置骨架串起来，避免每个工具各写各的、命名和目录全乱。

这篇就按这个协作链路走一遍，交付可复制的settings.json与config.toml骨架，再给出用 TaoToken 统一 Key 接入的步骤，最后落到本地启动和前端渲染验证动作。适合正在做独立游戏前端、想用 AI 工具提效但不想被工具带偏结构的开发者。

2. 前置：用 TaoToken 统一三个工具的 Key

三个工具如果各自去配 Key，最直接的麻烦是额度分散、切换模型要改多处、排查问题时不知道是哪条链路出的错。我的做法是走 TaoToken 统一接入，一个 Key 覆盖 ChatGPT、Codex、Claude Code 的调用，配置集中管理。

先到官网了解接入方式：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，然后在控制台创建 Key：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite 。Key 生成后复制保存，后面settings.json和config.toml都要填。

API 基地址统一用：https://taotoken.net/api ，注意这个地址不带 UTM 参数，直接写进配置即可。模型对话调试入口在 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite ，接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，Key 管理页在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。如果你后面要长期跑编码和 Agent 任务，可以看 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。

注意：Key 只存在本地配置文件或环境变量里，不要提交到 Git 仓库。建议在项目根目录加.gitignore排除settings.json和config.toml的本地副本。

3. 可复制配置：settings.json 与 config.toml 骨架

3.1 settings.json：给 Codex 和 Claude Code 用的项目级配置

这份settings.json放在项目根目录，作用是告诉 AI 工具「这个项目长什么样、命名怎么走、哪些目录不要动」。Codex 补组件逻辑、Claude Code 校验结构时都会读它。

{ "project": { "name": "dice-paradise", "framework": "react", "language": "typescript", "style": "css-modules", "entry": "src/main.tsx" }, "paths": { "components": "src/components", "pages": "src/pages", "hooks": "src/hooks", "assets": "src/assets", "styles": "src/styles", "types": "src/types" }, "naming": { "component": "PascalCase", "hook": "camelCase", "file": "kebab-case", "cssClass": "kebab-case" }, "ui": { "theme": "island-resort", "baseResolution": "1920x1080", "aspectRatio": "16:9", "allowStretch": false, "transparentRule": "only-pure-black-area" }, "constraints": { "doNotModify": ["src/core", "src/router"], "requireTypeDefinition": true, "maxComponentLines": 300 }, "ai": { "provider": "taotoken", "baseUrl": "https://taotoken.net/api", "apiKeyEnv": "TAOTOKEN_API_KEY", "defaultModel": "gpt-4o", "codeModel": "claude-sonnet" } }

几个字段值得单独说。ui.transparentRule设成only-pure-black-area，是因为我在做透明背景时反复踩坑：需求写「边缘透明」，AI 经常理解成整个面板透明，后来把规则写死成「只处理纯黑区域」，生成结果才稳定。ui.aspectRatio固定 16:9 且allowStretch为 false，避免背景图被拉伸导致元素错位。constraints.doNotModify列出核心目录，防止 AI 顺手重构路由和核心逻辑。

3.2 config.toml：给 Claude Code 的会话级配置

Claude Code 更偏向按会话读配置，用config.toml管理模型、上下文和校验规则。

[provider] name = "taotoken" base_url = "https://taotoken.net/api" api_key_env = "TAOTOKEN_API_KEY" [model] default = "claude-sonnet" fallback = "gpt-4o" max_tokens = 8192 temperature = 0.3 [context] project_config = "./settings.json" agents_file = "./AGENTS.md" include_paths = ["src/components", "src/pages", "src/hooks"] exclude_paths = ["node_modules", "dist", "src/assets/raw"] [validate] check_naming = true check_import_order = true check_component_size = true max_component_lines = 300 [render] base_resolution = "1920x1080" aspect_ratio = "16:9" allow_stretch = false

temperature压到 0.3，是因为前端结构校验需要稳定输出，太发散反而容易改出风格不一致的代码。agents_file指向AGENTS.md，把项目目录职责、命名规范、UI 规范、开发约束写进去，Claude Code 每次校验都会参考。

3.3 AGENTS.md：让三个工具读同一份规范

在项目根目录建AGENTS.md，内容不用长，但要把关键约束写清楚：

# Dice Paradise 前端规范 ## 目录职责 - src/components：可复用 UI 组件，不含业务请求 - src/pages：页面级组件，负责组合与数据编排 - src/hooks：自定义 hook，封装状态与副作用 - src/core：核心逻辑，AI 不得修改 ## 命名 - 组件文件：kebab-case，如 dice-panel.tsx - 组件名：PascalCase，如 DicePanel - hook：camelCase，以 use 开头 ## UI - 基准分辨率 1920x1080，严格 16:9 - 透明处理只针对纯黑区域 - 主题色走 island-resort 变量 ## 约束 - 单组件不超过 300 行 - 新增组件必须补 TypeScript 类型 - 不得改动 src/core 与 src/router

这份文件是三个工具协作的「共同语言」。ChatGPT 拆需求时按目录职责分任务，Codex 生成组件时按命名规范走，Claude Code 校验时按约束逐条对。

4. 验证请求：本地启动与前端渲染检查

4.1 配置环境变量并启动

先把 Key 写进环境变量，避免硬编码：

export TAOTOKEN_API_KEY="你的Key"

Windows PowerShell 用：

$env:TAOTOKEN_API_KEY="你的Key"

然后安装依赖并启动开发服务器：

npm install npm run dev

启动后终端会输出本地地址，通常是http://localhost:5173。打开浏览器，先看大厅页面是否正常渲染。

4.2 用模型对话验证 Key 是否通

在正式让 Codex 和 Claude Code 跑任务前，先用模型对话入口确认 Key 可用：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。发一条简单请求，比如让它按settings.json里的命名规范生成一个dice-panel.tsx骨架，看返回是否符合 PascalCase 组件名和 kebab-case 文件名。

如果返回正常，说明 Key 和基地址配置没问题。如果报 401，先检查TAOTOKEN_API_KEY是否生效；如果报 404，检查base_url是否写成了带路径的地址，正确写法是https://taotoken.net/api。

4.3 前端渲染验证动作

页面起来后，按这几步检查渲染是否符合预期：

第一步，打开浏览器开发者工具，切到 Console，确认没有红色报错。常见的是资源路径错误，检查src/assets下的图片引用是否用了相对路径。

第二步，切到 Elements，找到大厅容器，确认宽高比是 16:9。如果背景图被拉伸，检查 CSS 里是否写了object-fit: cover，以及settings.json里的allowStretch是否被某处覆盖。

第三步，检查透明区域。如果面板该透明的地方没透明、不该透明的地方透了，回到AGENTS.md确认transparentRule是否写清楚，再让 Claude Code 按规则重新校验对应组件。

第四步，跑一次结构校验。在 Claude Code 里执行：

claude-code validate --config ./config.toml

它会按config.toml里的validate段逐条检查命名、导入顺序、组件行数。输出里如果有max_component_lines超限，说明某个组件该拆了。

5. 本篇常见错排查

5.1 Key 配置了但请求 401

最常见的原因是环境变量没生效。settings.json里写的是apiKeyEnv: "TAOTOKEN_API_KEY"，工具读的是环境变量，不是文件里的字面值。确认echo $TAOTOKEN_API_KEY有输出，再重启开发服务器。另一个原因是 Key 复制时带了空格，重新从 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 复制一次。

5.2 基地址写成带路径导致 404

base_url必须是https://taotoken.net/api，不要在后面加/v1或/chat。有些工具会自动拼路径，手动加了反而重复。如果拿不准，对照接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。

5.3 AI 生成的组件命名和项目不一致

这是没读AGENTS.md的典型表现。检查config.toml里agents_file路径是否正确，以及settings.json里naming段是否和AGENTS.md一致。两处规范冲突时，AI 会随机选一个，结果就是命名混乱。统一以AGENTS.md为准，settings.json只做引用。

5.4 透明背景处理错区域

需求描述不够精确时，AI 容易把「边缘透明」理解成「整体透明」。解决办法是在AGENTS.md里把规则写死成「只处理纯黑区域，其余保持不变」，并在每次提需求时带上这句。如果已经生成错了，让 Claude Code 按transparentRule重新校验，不要手动改，避免遗漏。

5.5 背景图比例被拉伸

检查三处：CSS 里图片容器的aspect-ratio是否设为16 / 9；settings.json里allowStretch是否为 false；config.toml里render.aspect_ratio是否为16:9。三处一致才能保证渲染不变形。如果用了背景图铺满，记得加background-size: cover而不是100% 100%。

5.6 组件超过 300 行被校验拦下

config.toml里max_component_lines设为 300 是刻意为之，超过就说明职责太重。让 Codex 按settings.json里的paths.components拆分，把纯展示部分抽成子组件，业务逻辑抽成 hook。拆完再跑一次claude-code validate确认通过。

6. 把三个工具串成一条流水线

配置骨架搭好之后，日常开发就变成一条固定流水线：新页面先用 ChatGPT 拆需求，产出组件清单和目录归属；把清单丢给 Codex，按settings.json的命名和路径生成组件骨架；生成完让 Claude Code 按config.toml跑校验，超行数、命名不符、导入顺序乱的当场拦下。

这条链路跑顺之后，一个大厅页面从想法到可运行，基本能压到一个晚上以内。Key 统一走 TaoToken，配置集中在settings.json和config.toml，规范集中在AGENTS.md，三个工具读同一份约束，就不会各写各的。如果你也在一个人做游戏前端，建议先把这三份文件建起来，再开始让 AI 写第一行组件代码。