企业官网建设流程全解析

如果你最近关注过 AI 编程工具，一定绕不开 Claude Code。在终端里以自然语言给它下达任务，它就能读取代码、定位问题、修改文件、运行命令，甚至反复调试直到通过测试。这种体验和过去“人写代码、AI 补全”完全不同，更像是在带一个能独当一面的实习生。

不过新问题也来了：既然 AI 能写代码，我们怎么验收它的能力？靠肉眼盯屏幕？靠一遍遍重复提问？这也是我关注到 “Show HN: Claude Code Arcade” 这类项目的原因。单看名字，它像是一个给 Claude Code 玩的“游戏厅”，但我的判断是：它真正想做的，是把 Agent 的验证过程变成一套可复现、可计分、可回放的任务关卡系统。这个思路的价值远不止“好玩”。

所以这篇文章会把两层内容一次性讲透：先分析 Claude Code Arcade 这类项目背后的工程逻辑，再带你从零装好 Claude Code、完成 settings.json 配置，并照“Arcade 闯关”的思路，自己搭一个能自动评分的最小验证脚本。

1. “Claude Code Arcade”到底是一个什么东西

先说结论：Claude Code Arcade 不是一个官方产品，更像是开发者社区里典型的 Show HN 项目。Show HN 是 Hacker News 上开发者用来展示自己原型项目的一种主题标签，意味着这个项目可能还很早期，但作者愿意把想法拿出来接受大家试用和讨论。

单从命名习惯来看，Arcade 这个词通常包含三层可能的含义：

按目前能看到的公开资料推断，它大概率不是一个“在终端里玩俄罗斯方块”的普通游戏库，而是位于“展示”和“评测”之间的产物。它真正提供的价值，是让开发者意识到：AI Agent 的能力边界，必须在具体的任务里才能被看见。

这种“Arcade”思路的重点只有四个字：关卡、验收。每个任务都是独立关卡，每个关卡都有明确目标，Agent 做完之后由脚本检查结果，而不是靠人脑判断。它让“这个模型能不能写好代码”这种模糊问题，变成“这个 Agent 能不能通过这一关”这样可验证的问题。

如果你也在做 Agent 应用，真正值得从这类项目里学到的，不是具体某个小游戏写得多漂亮，而是它如何把一次性的“灵魂提问”改造成可持续运行的Agent 验收流水线。

1.1 为什么这样的项目会在现在出现

如果用一句话概括当前 Agent 工具链的现状：模型能力已经超过了配套工程能力。模型越来越聪明，但谁来定义“聪明”、谁来持续测试“聪明”，至今没有标准答案。

过去我们写单元测试，是因为函数行为是确定性的。给入参、等出参、比对结果，一个用例就能守住一个功能。但 Claude Code 这类 CLI Agent 的行为是非确定性的：它可能先读文件再搜索，可能一次改对也可能试三次，可能用 Python 也可能临时起意用 Shell。如果你没有一套“关卡系统”，想评估它的能力，就只能靠感觉。

Claude Code Arcade 这类项目的核心贡献，是把“测试 Agent”这件事产品化了：用任务当输入，用结果当输出，用关卡来对冲不确定性。这也是为什么我认为它值得单独写一篇，而不是当作一个娱乐向的小玩具。

2. Claude Code 为什么突然这么受关注

要理解 Claude Code Arcade，必须先理解 Claude Code 本身。

Claude Code 是 Anthropic 推出的终端编程 Agent。它不只是一个 IDE 插件，而是在命令行里直接运行的智能体：它能读取项目文件、搜索代码、调用工具，在获得授权后直接修改文件、执行命令，然后继续观察结果，形成“思考—行动—验证”的循环。

过去开发者的工作流是：打开 IDE，写代码，跑测试，看报错，手动修。现在可以变成：在项目根目录启动 claude，描述需求，Agent 自己去拆解并执行，开发者在关键节点审核。

传统 AI 编程辅助与 Claude Code 的一个关键区别如下：

这带来的体验变化是巨大的：以前 AI 是“输入法”，现在 AI 是“结对同事”。但“结对同事”也会犯错，所以我们需要 Arcade 式的任务关卡来持续验证它的能力。

2.1 生态里的常用概念

现在和 Claude Code 相关的高频词越来越多，这篇文章后面会反复用到几个概念，先帮你梳理清楚：

• Agent：能自主规划并调用外部工具完成任务的 AI 系统，Claude Code 就是面向编程场景的 Agent。
• Skill：一组预置的能力包，包含专门的行为指令和参考示例。Agent 在遇到对应任务时可以通过 Skill 激活，避免每次从零摸索。
• MCP：全称 Model Context Protocol，是一种让 Agent 统一连接外部工具/数据的标准协议，解决“每个工具都要单独集成”的问题。
• Settings.json：Claude Code 的配置文件，集中控制权限、模型、钩子、环境变量等。
• 沙箱/隔离环境：Agent 修改文件有风险，因此在独立、可丢弃的目录或容器里执行任务，是工程上最基本的防线。

把这些概念连起来，你就有了理解 Claude Code Arcade 的完整地图：Arcade 提供关卡任务，Agent 负责闯关，Skill 相当于 Agent 平时积累的“技能书”，而 MCP 则相当于 Agent 的“外接工具箱”。

3. 安装 Claude Code 并完成基础验证

不管你最终是要复现一个 Claude Code Arcade 项目，还是只想把它当普通开发工具用，第一步都是把它装到自己的终端里。

3.1 安装前确认环境

Claude Code 是一个终端工具，对运行环境有一定要求。在实际动手前，先确认三件事：

1. 操作系统：macOS、Linux 都可以直接在终端安装；Windows 上最稳妥的方式是使用 Windows Terminal + WSL，这样能避免很多原生终端兼容性问题。
2. Node.js：官方推荐使用较新的 Node.js LTS 版本。你可以用下述命令检查版本：

node -v npm -v

3. 账号凭证：使用 Claude Code 需要 Anhtropic 账号凭证，或你所使用的 API 服务商提供的密钥。具体获取方式请以官方文档为准，不要相信任何来路不明的“免费 key”。

版本细节我这里不写死，因为工具迭代很快。更推荐的做法是看官方 README 的 prerequisites 部分，一般会明确最低版本要求。

3.2 npm 全局安装与验证

在满足前置条件后，打开终端执行：

# 全局安装 Claude Code npm install -g @anthropic-ai/claude-code # 查看版本，确认安装成功 claude --version

安装完成后，如果claude命令找不到，通常是 Node.js 的全局 bin 目录不在 PATH 中。可以先执行：

npm bin -g

然后把输出目录加入系统的 PATH。运行claude或claude --version不再报错，说明核心程序已经装好。

3.3 两种基本启动方式

Claude Code 有两种最常见的启动方式，后续做 Arcade 关卡时也会用到：

# 方式一：交互式启动，适合手动沟通 claude # 方式二：非交互式一次性指令，适合被脚本调用 claude -p "请帮我看看当前目录里有什么代码"

交互模式适合你亲自盯着它改代码；-p参数（print 模式）则适合自动化脚本。Arcade 类的自动化关卡，本质就是不断调用-p模式并向脚本索取结果。

启动失败时不必慌，先按顺序检查 Node 版本、npm 全局路径、账号鉴权三个环节，大多数问题都能解决。

4. settings.json 配置模型与权限

Claude Code 安装好还不够，要让它在真实任务中稳定工作，你必须理解 settings.json。很多群里讨论的“模型不识别”“权限失效”问题，基本都是这一层配置出了问题。

4.1 settings.json 放在哪里

Claude Code 支持多级配置文件，常见位置包括：

• 用户级：~/.claude/settings.json，作用于当前用户的所有项目。
• 项目级：.claude/settings.json，放在当前项目根目录下，建议提交到仓库中。
• 本地级：.claude/settings.local.json，适合写个人的密钥、本地环境变量，不建议提交。

一套推荐的 settings.json 示例如下：

{ "env": { "ANTHROPIC_MODEL": "your-model-id" }, "permissions": { "deny": ["Bash(npm publish:*)", "Bash(rm -rf:*)"], "allow": ["Read", "Glob"] }, "statusLine": { "type": "command", "command": "echo 'Claude Code Ready'" } }

注意，上面代码里your-model-id需要替换成你实际要用的模型标识。环境变量、权限策略的具体字段以你当前安装版本为准。每台机器、每个项目目录下生效的配置可能不同，误改配置后优先检查是哪一层文件覆盖了另一层。

4.2 权限配置：别把控制权全交出去

很多刚开始用 Claude Code 的人会贪图方便把权限全开，这是很危险的做法。即使是在测试项目里，也建议遵循最小权限原则：只允许 Agent 读文件，在明确授权后再允许它写文件。

我通常这样处理：先用只读权限让 Agent 做分析和计划，审阅后切换成允许编辑的模式，需要执行高风险命令时再按需授权。把allow列表写得越短，你的项目越安全。

4.3 为什么会出现“模型不被识别”

搜索热度很高的一条报错是类似这样的：

xx-model is not a model this version of claude code recognizes

这个问题多半不是你安装错了，而是三种情况之一：

1. settings.json 里的ANTHROPIC_MODEL或启动命令里指定的模型名，与当前服务商/兼容网关提供的模型 ID 不一致。
2. 当前 Claude Code 版本内置的模型识别列表还没有覆盖新模型 ID，升级或换用已支持的名字即可。
3. 环境变量里的接口地址与密钥不匹配，导致 Agent 拿着 A 服务商的密钥请求 B 服务商的接口。

碰到这种报错，第一步打开claude model查看当前可用模型列表，确认你填写的 ID 是否在列表内；第二步检查 settings.json 的 env 区域；第三步确认 API 兼容地址正确。不要靠瞎猜反复重启，错误提示里通常已经说了是模型名问题还是版本问题。

4.4 使用兼容网关切换模型时要注意什么

现在很多人会把 Ollama 或各类兼容第三方 API 接入 Claude Code，本意是省 token、做本地验证。切换本身可行，但容易踩坑的地方也很集中：模型 ID 不匹配、接口路径不对、密钥混淆、上下文长度不支持。

• 严格确认你使用的服务商/SDK 官方提供的 Anthropic 兼容地址。
• 切换模型后先跑一个最小指令，例如claude -p "hi"。
• 不要直接在一个仓库里换模型跑全量任务，先在临时目录里做冒烟验证。

Arcade 类项目对模型 ID 尤其敏感，因为自动化脚本通常会用环境变量固定模型名。如果你换模型跑关却一直失败，优先怀疑模型名被写死，而不是关卡写得有问题。

5. 照 Arcade 思路做一个最小闯关系统

理解完概念和配置，下面进入最有价值的部分：自己搭一个极简的“Arcade 关卡”。

我不打算让你去复制一个完整开源项目，而是用最小的文件结构演示关卡机制。它的核心只有三样东西：一个任务定义、一个带 bug 的项目、一个评分脚本。Agent 闯关成功后，脚本会自动判定并输出分数。

5.1 目录结构

arcade-demo/ ├── levels/ │ └── fix-average/ │ ├── task.md │ └── project/ │ └── calc.py ├── runner.sh └── verify.sh

这个结构模拟的关卡叫做 fix-average：给 Claude Code 一个“算平均分”的小脚本，但脚本里藏着一个会导致运行报错的 bug，Agent 必须定位并修复它。

5.2 关卡任务与初始代码

先创建关卡任务说明levels/fix-average/task.md：

# 关卡：修复平均分计算 - 请阅读 project/calc.py - 当前脚本运行会报错，原意是计算若干分数的平均值 - 只允许修改 project 目录内的代码 - 不要删除文件，不要引入新的第三方依赖 - 修改完成后，运行 python3 project/calc.py，输出应为 20.0

接着在project/calc.py中放入一个故意写错的脚本：

# 文件路径：arcade-demo/levels/fix-average/project/calc.py def average(scores): total = 0 for score in scores: total += score count = len(score) # Bug：这里是 score，不是 scores return total / count if __name__ == "__main__": print(average([10, 20, 30]))

这个 bug 很典型：变量score在循环内是一个整数，对它调用len()会直接抛出TypeError，导致程序崩溃。Agent 只要运行脚本就能看到报错，然后追踪到count = len(score)这一行，把它改成len(scores)，程序就能正确输出20.0。

5.3 任务启动脚本 runner.sh

为了把闯关过程的“人工操作”降到最低，我们写一个 runner.sh 自动把任务目录复制到临时工作区，再调用 Claude Code 的非交互模式执行任务：

#!/usr/bin/env bash # 文件路径：arcade-demo/runner.sh set -euo pipefail LEVEL_DIR="levels/fix-average" WORK_DIR=".arcade-run" # 1. 每次闯关都从干净副本开始，避免上一次修改影响结果 rm -rf "$WORK_DIR" mkdir -p "$WORK_DIR" cp -r "$LEVEL_DIR/project" "$WORK_DIR/project" # 2. 以任务描述作为系统指令，把修改任务交给 Claude Code CLAUDE_CMD="${CLAUDE_CMD:-claude}" "$CLAUDE_CMD" -p "请阅读 $LEVEL_DIR/task.md，并在 $WORK_DIR/project 目录中完成修复。" \ --allowedTools "Read Write Bash" \ --output-format json > agent_round_1.log 2>&1 || true echo "agent 执行完毕，日志已保存到 agent_round_1.log" echo "开始执行关卡评分..."

脚本里我特意加了|| true，是因为即使 Agent 修复失败，我们仍然希望评分脚本能给出明确结果，而不是让 runner 的中断掩盖真实情况。日志会被完整保存，方便之后回放分析。

5.4 评分脚本 verify.sh

评分脚本是这个系统的“裁判”。它不关心 Agent 过程中说了什么，只看修复后程序的行为是否符合任务要求：

#!/usr/bin/env bash # 文件路径：arcade-demo/verify.sh set -euo pipefail WORK_DIR=".arcade-run" if [ ! -f "$WORK_DIR/project/calc.py" ]; then echo "FAIL: project/calc.py 不存在" exit 1 fi # 执行修复后的脚本并捕获输出 ACTUAL_OUTPUT=$(python3 "$WORK_DIR/project/calc.py" 2>&1) || { echo "FAIL: 脚本执行报错：$ACTUAL_OUTPUT" exit 1 } EXPECTED_OUTPUT="20.0" if [ "$ACTUAL_OUTPUT" = "$EXPECTED_OUTPUT" ]; then echo "PASS: 输出正确，得分 1/1" exit 0 else echo "FAIL: 预期输出 $EXPECTED_OUTPUT，实际输出 $ACTUAL_OUTPUT" exit 1 fi

最后执行：

chmod +x runner.sh verify.sh ./runner.sh ./verify.sh

如果一切顺利，你会看到类似输出：

agent 执行完毕，日志已保存到 agent_round_1.log 开始执行关卡评分... PASS: 输出正确，得分 1/1

这个最小系统已经具备 Arcade 的两个核心要素：Agent 在隔离目录里执行修复，脚本根据最终行为评分。你可以把 calc.py 换成任何带 bug 的业务代码，把 verify.sh 换成任意测试逻辑，这套关卡就能复用到各种场景。

6. 从“跑通一个关卡”到“跑通一整套验收”

上面只是一个最小示例，真正运营一个 Claude Code Arcade 类项目，需要在此基础上增加几层工程能力。

6.1 测试任务目录要与真实工作区隔离

最需要注意的是环境隔离。无论你的 Agent 有多强，只要它直接修改真实代码库，任何一次错误判断都可能覆盖你没有提交的代码。Arcade 类测试的通用做法是：每次运行都从 Git 标签或干净副本创建临时目录，Agent 只允许在临时目录里操作。

如果你的场景必须让 Agent 修改真实仓库，那至少要做到三点：先创建独立分支、提交一次初始快照、给 Agent 配置最小权限。Agent 改完以后，由人工 review diff，确认无误再合入。

6.2 用多关卡跑回归

一个关卡只能证明 Agent 能完成一类问题。要让 Arcade 有价值，你需要把它们积累成一个回归测试集：

• 第一关：修复一个语法错误。
• 第二关：重构一段重复代码并保证测试通过。
• 第三关：按需求文档新增一个接口。
• 第四关：根据失败测试反推并定位 bug。

这四个关卡难度递增、考察能力不同，正好覆盖 Agent 编程中最常见的几类行为。每次更换模型版本、修改提示词模板或升级 Claude Code，都可以用同一套关卡回归一遍。

在实现时，可以考虑把每个关卡目录里的 task.md 做得更严格，明确“可修改范围”“禁止事项”“验收命令”，因为 Agent 并不会自动按照人的常识去行动。Task 描述越无歧义，评审结果越可信。

6.3 日志回放比评分结果更重要

如果只想看“过没过”，跑一个二进制脚本就行。但关卡系统最重要的资产其实是日志。agent_round_1.log 里记录着 Agent 的每一步思考工具调用和修改动作，遇到关卡失败时，回放日志能让你快速定位是模型理解错了、操作顺序错了，还是测试脚本本身有歧义。

所以不要只把日志写到标准输出再丢弃，建议保存带时间戳的文件，例如：

LOG_FILE="logs/level_$(date +%Y%m%d_%H%M%S).json"

这样每一次模型升级后的尝试都是可追溯的，你才能判断一个 Agent 是“变强了”还是“碰巧过了”。

7. Claude Code 常见问题与排查方法

下面整理安装和配置中最常见的几类问题。这些问题不只在 Arcade 项目会出现，日常用 Claude Code 也躲不开。

如果遇到报错不知道怎么处理，先从日志入手。Claude Code 在-p模式下会输出结构化 JSON，里面既包含模型的请求响应，也包含工具调用记录。第一次排查时把它完整打开，找到第一个异常点，通常就能定位问题。

8. Claude Code Arcade 类项目的工程建议

把上面的内容沉淀成工程经验，有几条建议值得反复强调：

1. 模型和版本要固定下来。Agent 的能力受底层模型影响很大，Arcade 评测如果没有固定模型和工具版本，今天过明天挂，你根本无法判断是回归还是噪声。
2. 用可回放的日志替代肉眼观察。把每一轮 Agent 操作完整落盘，比任何“现场盯屏”都有价值。
3. 关卡任务先写验收标准，再写任务描述。很多 Agent 效率低，不是因为模型笨，而是因为任务说明里没有写清楚“怎样才算完成”。把 verify 脚本先写好，Agent 才知道自己该朝哪个方向收敛。
4. 控制单次任务的执行预算。给 Agent 设定时间或 token 上限，避免一个错误方向让它无限循环下去。runner 脚本里可以加一条 timeout 命令，在 Agent 超时后强制结束本轮闯关。
5. 权限最小化是底线。即使只是测试脚本，也不要让 Agent 拥有整台机器的完全控制权。允许名单越短，你后续修复问题的成本越低。
6. 不要在配置文件里写明文密钥。settings.local.json 虽然可以存放本地环境变量，但如果你要提交项目级配置，务必确保里面没有密钥，并且生产环境密钥通过环境变量或密钥管理服务注入。

如果未来你要把这类关卡接入团队 CI，建议把运行阶段进一步分成 smoke、daily、release 三档：每次提交只跑一道最小关卡，每晚跑全部日常关卡，发版前再配合真实回归测试跑关键路径。这样既能快速反馈，又不会因为 Agent 评测的偶发性阻塞正常开发。

9. 总结：从“游戏厅”到“验收场”

回过头再看 “Show HN: Claude Code Arcade” 这个项目名，我觉得它真正打开了一个值得持续跟踪的方向：把 Agent 能力测试变成一套带关卡、带评分、带回放的系统化工程。表面上看是让 Claude Code 玩游戏，实际上是让每个开发者都能用最小成本回答一个关键问题——这个 Agent 到底能不能完成我定义的那类任务。

这篇文章带你完成了三件事：理解了 Claude Code Arcade 背后的运行逻辑；完成了从安装到 settings.json 配置的实操；搭建了第一个能自动执行、自动评分的 Agent 闯关脚本。有了这套最小框架，你可以开始往里面添加自己的关卡。

如果你也打算尝试，建议从一个小步骤开始：挑一个最近困扰过你的经典 bug，把那块出问题的代码摘出来做成一个隔离关卡，再让 Claude Code 从零修复并自动评分。跑通第一关之后，再扩成十个、二十个关卡，你会开始真正了解你的 Agent，而不是只能感叹它“有时聪明有时笨”。

这套思路的本质其实很简单：不能量化，就无法改进。Arcade 不是让 Agent 去玩，而是让我们找到一种更靠谱的方式去衡量 Agent。下一步，就可以把你自己的“第一关”设计出来了。