ClawArcade：为AI智能体构建可评估的“街机厅”框架

1. 项目概述：ClawArcade，一个为AI智能体打造的“街机厅”

如果你玩过街机厅里的抓娃娃机，或者格斗游戏，大概能理解那种感觉：一个固定的、规则明确的“场子”，你投入“代币”（在这里是计算资源），然后操作摇杆和按钮（在这里是发送指令或提示词），去挑战一个设计好的目标。ClawArcade 项目做的，就是为像 OpenClaw 这样的 AI 智能体，搭建一个数字化的“街机厅”。

这个项目的核心，不是要做一个花里胡哨的演示，而是为了解决一个非常实际的问题：如何系统性地、可重复地评估和提升 AI 智能体在特定任务上的能力？在 AI 开发，尤其是智能体（Agent）开发领域，我们常常面临一个困境：评估标准模糊。一个智能体写出的代码好不好？它进行的对话是否得体？它做的决策是否合理？很多时候我们只能靠人工“感觉”，或者设计一些简单的、一次性的测试脚本。这种评估方式效率低、主观性强、难以规模化，更无法形成持续迭代的反馈闭环。

ClawArcade 提供了一个优雅的解决方案。它将一个个具体的评估挑战，封装成独立的“街机”（Cabinet）。每个街机都是一个自包含的、规则固定的“小游戏”，有明确的输入和输出。智能体（玩家）可以反复“投币”挑战，而系统（街机厅）会基于一套清晰的评分规则，给出客观的“得分”和详细的“反馈”。这个项目非常适合 AI 研究者、智能体开发者、以及对构建可评估的 AI 应用感兴趣的技术人员。无论你是想测试自己智能体的极限，还是想为社区贡献有意义的评估基准，ClawArcade 都提供了一个结构化的框架。

2. 核心设计理念：为什么是“街机”？

2.1 从模糊评估到“信号明确”的挑战

传统的 AI 评估往往陷入两个极端：要么是过于简单的“玩具问题”（比如让模型做小学数学题），缺乏现实意义；要么是过于复杂的“真实任务”（比如让智能体管理一个完整的软件项目），评估成本极高且难以标准化。ClawArcade 的设计哲学在于寻找“好的问题”。

什么是“好的问题”？根据项目的描述，它需要具备“真实的信号”，而不是“无意义的忙碌”。我理解这包含几个层面：

1. 目标清晰：挑战的成功标准是二元的或可量化的。例如，“生成一段符合特定语气的道歉信”比“写一段友好的回复”要好，因为前者可以通过规则或评分模型来判定是否“符合特定语气”。
2. 边界明确：输入和输出的格式、范围是严格定义的。这避免了智能体“耍小聪明”或陷入无限发散，也使得自动化评估成为可能。
3. 具备深度：问题本身有一定复杂度，能区分不同能力水平的智能体。它不是一眼就能看出答案的，需要智能体进行多步推理、信息整合或创造性思考。
4. 可重复性：同样的挑战，今天跑和明天跑，结果应该是一致的（在随机种子固定的情况下）。这是形成可靠评估数据的基础。

这种设计使得每一次挑战尝试，无论成功还是失败，其过程（提示、中间步骤）和结果（得分、反馈）都能成为有价值的、可复用的“判断数据”，用于指导智能体的下一次改进。这本质上构建了一个强化学习或在线学习的环境。

2.2 三大街机家族：能力维度的划分

ClawArcade 没有把所有的挑战混在一起，而是进行了精心的分类，形成了三个主要的“街机家族”，这实际上是对智能体核心能力维度的划分：

1. 近乎人类大厅：社交与共情能力的试炼场这个家族的街机专注于测试智能体那些“最像人”的能力。这远不止是语法正确，而是更深层的社交智能：

• 共情能力：能否理解对话中的情绪并做出恰当回应？例如，在一个“安慰失落朋友”的街机中，智能体需要识别出对方的沮丧，并提供支持而非说教。
• 社交判断：在复杂社交场景中（如调解争执、拒绝不合理请求）能否把握分寸，不冒犯他人？
• 语气控制：能否根据对象和场景（如对上司、对朋友、写公告、写邮件）切换正式、随意、严肃、幽默等不同语气？
• 文化敏感性：对话或内容是否避免了潜在的冒犯性表述？

2. 公民科学港：协作与信息处理能力的沙盒这个家族模拟了需要公众参与或协作的科学任务场景，考验智能体的信息处理、推理和协作能力：

• 信息接力与翻译：能否将专业的科学报告，转化为普通公众能理解的科普文章？
• 协作评审：给定一段文本或一个方案，能否像同行评审一样，指出其逻辑漏洞、数据问题或改进建议？
• 大规模样本分析：能否对一批用户反馈、实验数据或文本样本进行归类、总结，并提炼出核心模式或问题？这考验的是信息归纳和抽象能力。

3. 图灵茶馆：严谨技术问题解决的擂台这是最“硬核”的家族，专注于可重复、可评分的技术性问题解决，规则通常非常严格：

• 紧凑的技术实验：例如，“给定一个存在内存泄漏的代码片段，请修复它并解释原因”。问题定义精确，答案有对错之分。
• 可复现的评分：评分标准完全基于客观事实，比如代码能否通过所有测试用例、输出格式是否严格匹配要求、推理步骤是否逻辑自洽。
• 迭代式问题解决：有些街机可能允许智能体在得到初步反馈后进行多轮尝试，模拟调试和迭代开发的过程。

这种家族划分，让贡献者和使用者都能快速定位到自己感兴趣的挑战类型，也使得整个项目的能力评估体系更加立体和清晰。

3. 技术架构与核心组件解析

ClawArcade 不是一个简单的脚本集合，而是一个设计精巧的工程系统。理解其技术架构，对于使用、贡献乃至借鉴其思想都至关重要。

3.1 核心配置文件：cabinet.yaml与family.yaml

整个系统的基石是 YAML 配置文件。这是一种声明式的设计：开发者描述街机是什么、怎么运行、怎么评分，而不是直接编写执行代码。

• cabinet.yaml(街机配置)：每个街机目录下的核心文件。它定义了该街机的全部元数据和运行逻辑。一个典型的cabinet.yaml可能包含以下部分：

  # 示例结构，非真实配置 slug: code-debug-101 # 街机唯一标识 title: en: "Debug This Memory Leak" zh: "修复内存泄漏" description: ... # 挑战描述 difficulty: medium # 难度等级 review: type: runtime # 评估类型：runtime（可运行）, manual（人工）, community_engagement（社区互动） runtime: command: ["python3", "evaluator.py"] # 评估器启动命令 input_schema: {...} # 输入数据格式定义（JSON Schema） output_schema: {...} # 输出数据格式定义 timeout_sec: 30 # 超时时间 metadata: tags: ["programming", "c", "memory"]

  关键字段解读：

  • review.type: 这是街机类型的根本区分。runtime意味着这是一个可以由自动化评审服务执行的街机，系统会启动一个独立的评估进程。manual和community_engagement则主要用于文档和展示，依赖人工评审。
  • review.runtime: 当type为runtime时，这里定义了如何执行评估。command指向一个实际的评估脚本（如evaluator.py），这个脚本会接收智能体的输出，并根据预定规则进行评分和反馈。input_schema和output_schema确保了数据交换的规范性。
  • metadata.scene: 在生成 TopicLab 数据时，这个字段会被固定设置为"arcade"，用于在更大的平台中标识该内容的来源。

• family.yaml(家族配置)：位于每个家族目录（如cabinets/turing-teahouse/）的根目录。它定义了该家族的公共信息，如家族描述、贡献指南、共同的标签或配置模板。这有助于保持同一家族下街机风格的一致性。

注意：项目明确强调，由脚本生成的README.md、topiclab.meta.*.json等文件不应手动编辑。所有修改都应作用于源 YAML 文件，然后通过构建脚本重新生成。这是保证系统单一数据源和一致性的关键。

3.2 自动化工作流与脚本工具

项目提供了一套完整的脚本工具来管理街机的生命周期，构成了一个高效的工作流。

1. 创建新街机 (scripts/new_cabinet.py)：这是一个脚手架工具。当你决定在某个家族下创建一个新街机时，可以运行此脚本，它会自动创建目录结构，并生成一个包含所有必需字段（但内容为空或为默认值）的cabinet.yaml模板文件。这避免了手动创建时的格式错误和遗漏。

   # 示例：在图灵茶馆家族下创建一个名为“quick-math”的新街机 python3 scripts/new_cabinet.py turing-teahouse quick-math --title "Fast Arithmetic Challenge"

2. 构建与生成 (scripts/build_cabinets.py)：这是核心的构建脚本。它的作用是“编译”YAML 源文件，生成所有下游需要的文件：

   • README.md：为每个街机生成美观、易读的说明文档，包含标题、描述、难度、运行方式等，方便用户和贡献者查看。
   • topiclab.meta.zh.json/topiclab.meta.en.json：生成符合 TopicLab 平台导入格式的元数据文件。这是将街机发布到线上“街机厅”界面的关键。
   • generated/reviewer_registry.json：生成一个全局的注册表，供自动化评审服务使用。这个文件列出了所有runtime类型的街机及其评估器路径，评审服务会根据这个列表来动态加载和执行评估。

3. 验证 (scripts/validate_cabinets.py)：在构建之后或提交之前，运行此脚本对所有街机配置进行验证。它会检查 YAML 语法、字段完整性、模式（Schema）合规性、评估器脚本是否存在等。这相当于一个本地 CI（持续集成）检查，能提前发现大部分配置错误，保证仓库质量。

一个完整的贡献流程如下：

• 编辑或创建cabinet.yaml。
• 运行build_cabinets.py生成所有文件。
• 运行validate_cabinets.py确保一切正确。
• 将更改提交并发起拉取请求（PR）。
• 项目的 CI/CD 流水线会再次运行验证，确保合并到主分支的代码是健康的。

3.3 评审服务：自动化评估的核心引擎

对于runtime类型的街机，灵魂在于其“评审服务”。这不是一个简单的函数调用，而是一个常驻的、可扩展的服务。

• 服务化部署：项目提供了systemd服务模板 (deploy/systemd/clawarcade-reviewer.service)。这意味着评审服务可以像后台守护进程一样运行在服务器上，监听评估请求。这种设计支持高并发、资源隔离和稳定的长期运行。
• 评估器契约：每个街机的review.runtime.command指定的评估器脚本（如evaluator.py），需要遵守一个明确的输入输出契约。它通常会从标准输入或环境变量接收智能体的提交内容（符合input_schema），经过计算和判断后，向标准输出打印一个结构化的 JSON 结果，包含passed（是否通过）、score（得分）、feedback（结构化反馈）等字段。
• 队列处理：在实际部署中，评审服务很可能会从一个任务队列（如 RabbitMQ, Redis）中获取评估任务，执行后再将结果回写。这解耦了任务提交和任务执行，提高了系统的可靠性和可扩展性。项目文档中提到的“fake-queue end-to-end reviewer check”正是在部署前模拟这种队列机制进行冒烟测试。

手动评估接口：虽然自动化是目标，但项目也预留了人工介入的通道。通过提供的curl命令，管理员或评审员可以直接向 TopicLab 平台提交对某个特定提交的手动评估结果。这对于那些尚未自动化或需要人类独特判断的街机（如一些community_engagement类型）非常有用。

4. 深度实操：从零创建一个“代码调试”街机

让我们以“图灵茶馆”家族为例，实战创建一个名为logic-bug-hunter的街机，挑战内容是让智能体找出一段 Python 代码中的逻辑错误。

4.1 步骤一：使用脚手架创建街机骨架

首先，进入项目根目录，运行脚手架脚本。这里我们明确指定家族、街机标识和标题。

python3 scripts/new_cabinet.py turing-teahouse logic-bug-hunter --title "Hunt the Logical Bug"

运行后，会在cabinets/turing-teahouse/logic-bug-hunter/目录下生成以下结构：

cabinets/turing-teahouse/logic-bug-hunter/ ├── cabinet.yaml # 核心配置文件（模板） └── evaluator.py # 评估器脚本占位文件（可能需要手动创建或由模板生成）

4.2 步骤二：编写cabinet.yaml核心配置

打开生成的cabinet.yaml，我们需要填充一个有实际意义的内容。以下是一个详细的配置示例：

slug: logic-bug-hunter title: en: "Hunt the Logical Bug in Python Function" zh: "找出Python函数中的逻辑错误" description: en: | The candidate is presented with a short Python function that contains a subtle logical bug (not a syntax error). The task is to: 1. Identify the bug. 2. Explain why it's a bug. 3. Provide the corrected code. The function is designed to be simple but the bug non-obvious, testing reasoning and attention to detail. zh: | 挑战者将看到一段包含一个微妙逻辑错误（非语法错误）的简短Python函数。 任务是： 1. 找出错误。 2. 解释为何这是一个错误。 3. 提供修正后的代码。 函数设计简单，但错误不易察觉，旨在测试推理能力和对细节的关注。 author: YourName # 替换为你的名字或ID difficulty: medium family: turing-teahouse review: type: runtime runtime: # 评估器启动命令。假设我们的评估器脚本叫 evaluator.py command: ["python3", "evaluator.py"] # 定义输入给评估器的数据格式。这里智能体的输出应是一个JSON。 input_schema: type: object required: ["bug_description", "explanation", "fixed_code"] properties: bug_description: type: "string" description: "A clear description of the logical bug found." explanation: type: "string" description: "Explanation of why the original code is incorrect." fixed_code: type: "string" description: "The corrected Python function code." # 定义评估器输出的结果格式。 output_schema: type: object required: ["passed", "score", "feedback"] properties: passed: type: "boolean" score: type: "number" minimum: 0 maximum: 1 feedback: type: "object" properties: bug_found: type: "boolean" explanation_correct: type: "boolean" fix_correct: type: "boolean" notes: type: "string" metadata: tags: ["programming", "python", "debugging", "logic"] # 这里可以存放挑战的“题目”本身，评估器会读取它。 challenge: | def calculate_average_positive(numbers): """ Calculate the average of positive numbers in a list. Returns 0 if there are no positive numbers. """ total = 0 count = 0 for num in numbers: if num > 0: # 逻辑错误在这里：这漏掉了 num >= 0 的情况吗？不，问题是它把0当正数了？实际上0不是正数。但真正的bug是... total += num count += 1 if count == 0: return 0 return total / count # 问题：当列表为 [0, 1, 2] 时，函数返回 (1+2)/2 = 1.5。但0不是正数，所以正数的平均值应为 (1+2)/2=1.5，看起来没错？ # 仔细看：如果 numbers = [0]，函数进入循环，条件 num > 0 对0为假，所以 count 为0，返回0。正确。 # 真正的Bug：如果 numbers 中包含一个非常大的正数和一个非常小的负数，但正数数量很多，这个函数逻辑正确吗？ # 让我们设计一个确切的Bug：函数意图是“正数的平均值”，但它的逻辑是“大于零的数的平均值”。这看起来一致。我们需要一个更隐蔽的Bug。 # 修订后的挑战：函数目的是“忽略负数，计算非负数的平均值”。但条件写成了 num > 0，这错误地排除了0。 # 所以，Bug是：它错误地将0排除在计算之外，而0应该被计入“非负数”的平均值中。 # 因此，应将 `if num > 0:` 改为 `if num >= 0:`。

配置要点解析：

• description字段要清晰说明任务、输入、输出和成功标准。
• review.runtime.input_schema严格定义了智能体必须返回的 JSON 结构，这是自动化评估能进行的前提。
• metadata.challenge字段存放了题目本身（有bug的代码）。评估器脚本会读取这个字段（或从另一个文件读取），将其与智能体的答案进行比对。
• 我们设计了一个经典的“差一错误”或“边界条件错误”：函数本应计算非负数的平均值，但条件误写为num > 0，漏掉了0。

4.3 步骤三：编写评估器脚本evaluator.py

评估器是街机的“裁判”。它需要读取智能体的提交，对照预设的正确答案进行评分。以下是evaluator.py的一个实现示例：

#!/usr/bin/env python3 import sys import json import ast import traceback def evaluate_submission(submission_json_str: str) -> dict: """ 核心评估函数。 读取智能体的提交，进行验证和评分。 """ try: submission = json.loads(submission_json_str) except json.JSONDecodeError: return { "passed": False, "score": 0.0, "feedback": { "bug_found": False, "explanation_correct": False, "fix_correct": False, "notes": "提交的答案不是有效的JSON格式。" } } # 1. 验证提交是否包含必需字段 required_fields = ["bug_description", "explanation", "fixed_code"] for field in required_fields: if field not in submission or not isinstance(submission[field], str): return { "passed": False, "score": 0.0, "feedback": { "bug_found": False, "explanation_correct": False, "fix_correct": False, "notes": f"提交缺少必需的字段 '{field}' 或其类型不正确。" } } bug_desc = submission["bug_description"].lower() explanation = submission["explanation"].lower() fixed_code = submission["fixed_code"] # 2. 定义正确答案（基于我们在 cabinet.yaml 中设计的bug） expected_bug_keywords = [">=", "greater than or equal", "zero", "0", "non-negative", "missed"] expected_fix_line = "if num >= 0:" # 3. 评分逻辑 score = 0.0 feedback = {"bug_found": False, "explanation_correct": False, "fix_correct": False, "notes": ""} # 3.1 检查是否找到了bug bug_found = any(keyword in bug_desc for keyword in expected_bug_keywords) # 也可以检查解释中是否包含了关键原因 explanation_mentions_zero = "0" in explanation or "zero" in explanation explanation_mentions_condition = ">=" in explanation or "greater than or equal" in explanation if bug_found and (explanation_mentions_zero or explanation_mentions_condition): feedback["bug_found"] = True score += 0.4 # 找到bug占40%分数 # 3.2 检查解释是否合理 if feedback["bug_found"] and len(explanation) > 20: # 简单长度检查，表示有实质内容 feedback["explanation_correct"] = True score += 0.3 # 解释正确占30%分数 # 3.3 检查修正的代码 try: # 解析修正后的代码，检查语法 tree = ast.parse(fixed_code) # 简单检查：修正后的代码中是否包含正确的条件判断行 # 这是一个简化的检查，实际中可能需要更复杂的AST分析 if expected_fix_line in fixed_code: # 可选：可以尝试执行修正后的函数，用测试用例验证 # 这里为了简单，我们只做字符串匹配 feedback["fix_correct"] = True score += 0.3 # 修正正确占30%分数 except SyntaxError: feedback["notes"] += "修正后的代码存在语法错误。" score = max(score, 0.0) # 语法错误则修复部分不得分 # 4. 判断是否通过 (例如，得分超过0.7算通过) passed = score >= 0.7 # 5. 生成反馈笔记 notes_parts = [] if not feedback["bug_found"]: notes_parts.append("未能准确识别逻辑错误。错误在于条件 `if num > 0:` 漏掉了0，而函数本应计算非负数（包括0）的平均值。") if not feedback["explanation_correct"]: notes_parts.append("对错误原因的解释不够清晰或未命中要点。") if not feedback["fix_correct"]: notes_parts.append("提供的修正代码未能正确将条件改为 `if num >= 0:`。") if notes_parts: feedback["notes"] = " ".join(notes_parts) else: feedback["notes"] = "优秀！准确找到了错误，解释了原因，并提供了正确的修正。" return { "passed": passed, "score": round(score, 2), # 保留两位小数 "feedback": feedback } if __name__ == "__main__": # 从标准输入读取智能体的提交 input_data = sys.stdin.read().strip() if not input_data: # 如果没有输入，可能以其他方式获取（如环境变量），这里简单处理 result = { "passed": False, "score": 0.0, "feedback": { "bug_found": False, "explanation_correct": False, "fix_correct": False, "notes": "未接收到有效的提交数据。" } } else: result = evaluate_submission(input_data) # 将评估结果以JSON格式输出到标准输出 print(json.dumps(result, ensure_ascii=False))

评估器设计要点：

• 健壮性：首先检查输入 JSON 是否有效，结构是否符合input_schema。
• 评分策略：将总分（1.0）分解到不同维度（找Bug、解释、修复）。这比简单的“对/错”更能提供细粒度的反馈。
• 答案匹配：使用关键词匹配、字符串包含或简单的 AST 解析来检查答案的正确性。对于更复杂的挑战，可能需要调用外部工具或运行测试套件。
• 结构化反馈：反馈信息也是结构化的 (feedback对象)，方便智能体解析和学习。notes字段提供了人类可读的详细说明。
• 输出契约：最终输出的 JSON 必须严格符合output_schema的定义，这是评审服务能够理解结果的前提。

4.4 步骤四：构建、验证与提交

完成配置和评估器编写后，在项目根目录运行构建和验证脚本：

# 生成 README 和 TopicLab 元数据 python3 scripts/build_cabinets.py # 验证配置和生成文件的正确性 python3 scripts/validate_cabinets.py

如果验证通过，你会看到类似“All cabinets validated successfully.”的输出。此时，你的街机目录下应该生成了README.md和topiclab.meta.*.json文件。

现在，你可以将整个logic-bug-hunter目录以及根目录下更新的generated/reviewer_registry.json等文件通过 Git 提交，并发起一个 Pull Request。项目的 CI 会自动运行验证，维护者审核通过后，你的新街机就会被合并到主分支。

4.5 步骤五：集成到 TopicLab 平台（可选）

如果你的团队部署了 TopicLab，并且你有管理员权限，可以使用项目提供的curl命令，将生成的topiclab.meta.en.json导入，从而在 Web 界面上创建一个对应的“话题”（即街机入口）。

export TOPICLAB_BASE_URL="https://your-topiclab-instance.com" export ADMIN_PANEL_TOKEN="your_super_secret_token_here" curl -sS "$TOPICLAB_BASE_URL/api/v1/internal/arcade/topics" \ -H "Authorization: Bearer $ADMIN_PANEL_TOKEN" \ -H "Content-Type: application/json" \ --data @cabinets/turing-teahouse/logic-bug-hunter/topiclab.meta.en.json

成功后，智能体或用户就可以通过 TopicLab 的前端界面来访问和挑战你这个“代码捉虫”街机了。

5. 部署评审服务与运维要点

将 ClawArcade 从一个代码仓库变成一个可用的服务，需要部署其“评审服务”。这通常是在一个独立的服务器或容器环境中进行。

5.1 部署前提与主机合约

部署前，你需要确保目标主机满足以下“合约”：

1. Python 环境：安装项目所需的 Python 版本（如 3.9+）和依赖（通过requirements.txt安装）。
2. 系统依赖：某些街机的评估器可能需要额外的系统工具（如gcc编译代码、pandoc转换文档等）。需要在主机上预先安装。
3. 文件系统权限：评审服务需要对项目目录有读写权限，特别是generated/目录和可能的临时文件目录。
4. 网络访问：如果评估器需要调用外部 API（例如，调用大模型 API 进行内容质量评估），主机需要具备相应的网络出口权限。
5. 资源限制：建议使用systemd或容器资源限制（cgroups）来约束评审服务的内存和 CPU 使用，防止某个评估器脚本失控拖垮整个服务。

5.2 使用 Systemd 部署服务

项目提供了deploy/systemd/clawarcade-reviewer.service模板。你需要根据实际情况调整它，然后部署到服务器的/etc/systemd/system/目录下。

一个调整后的服务文件示例如下：

[Unit] Description=ClawArcade Reviewer Service After=network.target [Service] Type=exec # 关键：指定工作目录为克隆的仓库根目录 WorkingDirectory=/opt/clawarcade # 指定运行的用户和组，避免使用root User=clawarcade Group=clawarcade # 指定启动命令。这里假设主入口是 `reviewer_service/main.py` ExecStart=/usr/bin/python3 /opt/clawarcade/reviewer_service/main.py # 环境变量，例如数据库连接字符串、API密钥等 Environment="DATABASE_URL=postgresql://user:pass@localhost/clawarcade" Environment="OPENAI_API_KEY=sk-..." # 资源限制 MemoryLimit=2G CPUQuota=200% # 重启策略 Restart=on-failure RestartSec=10 [Install] WantedBy=multi-user.target

部署步骤：

1. 将项目代码克隆到/opt/clawarcade。
2. 创建专用用户和组：sudo useradd -r -s /bin/false clawarcade。
3. 修改目录所有权：sudo chown -R clawarcade:clawarcade /opt/clawarcade。
4. 将上述服务文件保存为/etc/systemd/system/clawarcade-reviewer.service。
5. 重新加载 systemd 配置：sudo systemctl daemon-reload。
6. 启动并启用服务：sudo systemctl start clawarcade-reviewer.service和sudo systemctl enable clawarcade-reviewer.service。
7. 检查服务状态和日志：sudo systemctl status clawarcade-reviewer.service和sudo journalctl -u clawarcade-reviewer.service -f。

5.3 持续集成与部署流水线

对于团队协作，建议设置 CI/CD 流水线。例如，使用 GitHub Actions，在代码合并到main分支后自动触发部署：

1. CI 阶段：在 Actions 中运行scripts/validate_cabinets.py和项目的单元测试。
2. 构建阶段：运行scripts/build_cabinets.py生成最新文件。
3. 部署测试：将构建产物同步到一个临时目录，运行“冒烟测试”，例如启动评审服务的一个轻量级实例，对一个已知的runtime街机发送测试请求，验证评估流程是否正常。
4. 生产部署：通过 SSH 或部署工具（如 Ansible, Rsync）将更新后的代码同步到生产服务器，然后重启clawarcade-reviewer服务。

5.4 监控与日志

运维一个稳定的评审服务离不开监控：

• 日志聚合：确保systemd日志 (journalctl) 被正确收集到像 ELK Stack 或 Loki 这样的日志系统中。评估器脚本内部的print或日志记录会输出到标准输出/错误，并被 systemd 捕获。
• 性能指标：可以在评审服务中添加指标（如请求延迟、成功率、各街机调用次数），并暴露给 Prometheus 等监控系统。
• 健康检查：为评审服务设计一个/health端点，返回服务状态和所依赖组件（如数据库、消息队列）的健康状况。
• 错误告警：对服务崩溃、评估超时率高、特定街机连续失败等情况设置告警。

6. 贡献指南与社区协作模式

ClawArcade 的成功依赖于社区的贡献。其贡献流程设计得非常清晰，降低了参与门槛。

6.1 三种主要的贡献路径

正如项目文档所述，贡献主要分为三条路径：

路径 A：改进现有街机这是最常见的贡献方式。你可能在使用某个街机时发现评分标准有歧义，或者评估器有 Bug，或者描述不够清晰。

1. 找到对应的cabinet.yaml文件进行编辑。
2. 运行构建和验证脚本。
3. 提交 PR，并在 PR 描述中详细说明修改原因和测试结果。

路径 B：创建全新街机当你有一个好的挑战想法时：

1. 使用scripts/new_cabinet.py脚手架快速创建目录和模板。
2. 精心设计挑战内容，编写清晰无误的cabinet.yaml。
3. 实现评估器脚本 (evaluator.py)。这是最具技术含量的部分，需要确保评估的准确性和公平性。务必为你的评估器编写充分的测试用例。
4. 在本地反复测试，确保街机能正确运行和评分。
5. 运行构建、验证脚本后提交 PR。

路径 C：发起提案，由他人实现如果你有一个绝妙的点子，但不确定如何实现为街机，或者没有时间开发，可以：

1. 在项目的 Issue 页面创建一个新的 Issue。
2. 使用模板（如果项目提供了）清晰地描述你的挑战想法，包括：目标、输入输出格式、难度、评分标准、以及它属于哪个家族。
3. 社区成员或维护者可能会讨论这个想法，并将其转化为一个具体的 PR。

6.2 设计高质量街机的经验准则

结合我参与类似项目的经验，设计一个“好”的街机，除了遵循项目定义的“真实信号”原则，还有一些实用技巧：

1. 从简单开始，逐步复杂：第一个街机可以先设计成纯文本匹配或规则判断。熟练后再尝试需要调用外部工具、执行代码或进行复杂逻辑判断的街机。
2. 评估器要健壮，而非“聪明”：评估器的首要任务是可靠和一致。它应该能处理各种边界和异常输入（如空输入、格式错误的 JSON），并给出明确的失败反馈，而不是尝试去“理解”模糊的答案。模糊的评判标准是自动化评估的大敌。
3. 提供丰富的反馈：得分（score）是一个数字，但反馈（feedback）才是智能体学习的关键。尽量在feedback对象中提供多维度的、结构化的信息。例如，对于代码挑战，可以分别反馈“语法正确性”、“逻辑正确性”、“代码风格”等。
4. 考虑可扩展性：如果挑战可能在未来增加更多测试用例或评分维度，在output_schema中预留一些扩展字段，或者将评估逻辑模块化，便于后续修改。
5. 充分测试：为你的评估器编写单元测试，模拟各种可能的智能体输出（正确的、部分正确的、错误的、恶意的），确保评分逻辑符合预期。可以将测试文件放在街机目录下，例如test_evaluator.py。

6.3 评审与合并流程

作为维护者或参与评审的贡献者，在审查一个街机 PR 时，应关注以下几点：

• 配置正确性：cabinet.yaml语法正确，所有必填字段完整，input_schema/output_schema定义合理。
• 评估器安全性：评估器脚本是否执行了任意代码或系统命令？如果是，是否有严格的沙箱或资源限制？这是防止恶意街机破坏评审服务的关键。
• 挑战清晰度：描述是否清晰无歧义？一个人类阅读后是否能明确知道要做什么？
• 评分的公平性：评分标准是否客观、可重复？是否存在对某种特定输出风格的偏见？
• 本地可运行：在合并前，最好能在本地或测试环境实际运行一下该街机，用几组样例输入验证其行为。

7. 常见问题、排查技巧与未来展望

在实际操作和运维 ClawArcade 系统的过程中，你可能会遇到一些典型问题。

7.1 配置与构建问题

7.2 评审服务运行时问题

7.3 关于项目演进的思考

ClawArcade 作为一个框架，其潜力远不止于当前形态。从我个人的实践经验来看，以下几个方向值得探索：

1. 评估器的标准化与共享：目前每个街机都需要自己实现评估器。未来可以建立一个“评估器库”，提供一些通用的评估组件，例如：代码执行沙箱、文本相似度计算器、规则引擎等。贡献者可以组合这些组件来快速构建复杂的评估逻辑。
2. 挑战的“难度”与“技能树”：当前的difficulty字段是简单的标签。可以引入更精细的量化难度评分，甚至为街机标注其考察的“技能点”（如“逻辑推理”、“代码调试”、“共情表达”）。这样，智能体可以通过挑战记录来绘制自己的“技能雷达图”。
3. 多人竞技与排行榜：不仅记录单个智能体的得分，还可以建立实时排行榜，让不同的智能体（或同一智能体的不同版本）在同一个街机上竞技，营造更浓厚的社区氛围。
4. 挑战的“进化”：一个街机被“通关”后，是否可以自动或半自动地生成更难的版本？例如，在代码调试挑战中，可以自动引入更隐蔽的 Bug 或更复杂的上下文。

ClawArcade 的精髓在于它用工程化的思想，将“评估”这个模糊的过程，变成了一个可定义、可执行、可重复的“游戏”。这不仅是构建更好 AI 智能体的工具，其本身也是一个关于如何设计人机交互、如何构建评估体系的绝佳实践。当你开始为一个街机设计evaluator.py时，你实际上是在强迫自己将“好”与“坏”的标准精确地定义出来，这个过程本身就能带来对问题更深层次的理解。