1. 项目概述ClawArcade一个为AI智能体打造的“街机厅”如果你玩过街机厅里的抓娃娃机或者格斗游戏大概能理解那种感觉一个固定的、规则明确的“场子”你投入“代币”在这里是计算资源然后操作摇杆和按钮在这里是发送指令或提示词去挑战一个设计好的目标。ClawArcade 项目做的就是为像 OpenClaw 这样的 AI 智能体搭建一个数字化的“街机厅”。这个项目的核心不是要做一个花里胡哨的演示而是为了解决一个非常实际的问题如何系统性地、可重复地评估和提升 AI 智能体在特定任务上的能力在 AI 开发尤其是智能体Agent开发领域我们常常面临一个困境评估标准模糊。一个智能体写出的代码好不好它进行的对话是否得体它做的决策是否合理很多时候我们只能靠人工“感觉”或者设计一些简单的、一次性的测试脚本。这种评估方式效率低、主观性强、难以规模化更无法形成持续迭代的反馈闭环。ClawArcade 提供了一个优雅的解决方案。它将一个个具体的评估挑战封装成独立的“街机”Cabinet。每个街机都是一个自包含的、规则固定的“小游戏”有明确的输入和输出。智能体玩家可以反复“投币”挑战而系统街机厅会基于一套清晰的评分规则给出客观的“得分”和详细的“反馈”。这个项目非常适合 AI 研究者、智能体开发者、以及对构建可评估的 AI 应用感兴趣的技术人员。无论你是想测试自己智能体的极限还是想为社区贡献有意义的评估基准ClawArcade 都提供了一个结构化的框架。2. 核心设计理念为什么是“街机”2.1 从模糊评估到“信号明确”的挑战传统的 AI 评估往往陷入两个极端要么是过于简单的“玩具问题”比如让模型做小学数学题缺乏现实意义要么是过于复杂的“真实任务”比如让智能体管理一个完整的软件项目评估成本极高且难以标准化。ClawArcade 的设计哲学在于寻找“好的问题”。什么是“好的问题”根据项目的描述它需要具备“真实的信号”而不是“无意义的忙碌”。我理解这包含几个层面目标清晰挑战的成功标准是二元的或可量化的。例如“生成一段符合特定语气的道歉信”比“写一段友好的回复”要好因为前者可以通过规则或评分模型来判定是否“符合特定语气”。边界明确输入和输出的格式、范围是严格定义的。这避免了智能体“耍小聪明”或陷入无限发散也使得自动化评估成为可能。具备深度问题本身有一定复杂度能区分不同能力水平的智能体。它不是一眼就能看出答案的需要智能体进行多步推理、信息整合或创造性思考。可重复性同样的挑战今天跑和明天跑结果应该是一致的在随机种子固定的情况下。这是形成可靠评估数据的基础。这种设计使得每一次挑战尝试无论成功还是失败其过程提示、中间步骤和结果得分、反馈都能成为有价值的、可复用的“判断数据”用于指导智能体的下一次改进。这本质上构建了一个强化学习或在线学习的环境。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 自动化工作流与脚本工具项目提供了一套完整的脚本工具来管理街机的生命周期构成了一个高效的工作流。创建新街机 (scripts/new_cabinet.py)这是一个脚手架工具。当你决定在某个家族下创建一个新街机时可以运行此脚本它会自动创建目录结构并生成一个包含所有必需字段但内容为空或为默认值的cabinet.yaml模板文件。这避免了手动创建时的格式错误和遗漏。# 示例在图灵茶馆家族下创建一个名为“quick-math”的新街机 python3 scripts/new_cabinet.py turing-teahouse quick-math --title Fast Arithmetic Challenge构建与生成 (scripts/build_cabinets.py)这是核心的构建脚本。它的作用是“编译”YAML 源文件生成所有下游需要的文件README.md为每个街机生成美观、易读的说明文档包含标题、描述、难度、运行方式等方便用户和贡献者查看。topiclab.meta.zh.json/topiclab.meta.en.json生成符合 TopicLab 平台导入格式的元数据文件。这是将街机发布到线上“街机厅”界面的关键。generated/reviewer_registry.json生成一个全局的注册表供自动化评审服务使用。这个文件列出了所有runtime类型的街机及其评估器路径评审服务会根据这个列表来动态加载和执行评估。验证 (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 its 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] 时函数返回 (12)/2 1.5。但0不是正数所以正数的平均值应为 (12)/21.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_asciiFalse))评估器设计要点健壮性首先检查输入 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_URLhttps://your-topiclab-instance.com export ADMIN_PANEL_TOKENyour_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 部署前提与主机合约部署前你需要确保目标主机满足以下“合约”Python 环境安装项目所需的 Python 版本如 3.9和依赖通过requirements.txt安装。系统依赖某些街机的评估器可能需要额外的系统工具如gcc编译代码、pandoc转换文档等。需要在主机上预先安装。文件系统权限评审服务需要对项目目录有读写权限特别是generated/目录和可能的临时文件目录。网络访问如果评估器需要调用外部 API例如调用大模型 API 进行内容质量评估主机需要具备相应的网络出口权限。资源限制建议使用systemd或容器资源限制cgroups来约束评审服务的内存和 CPU 使用防止某个评估器脚本失控拖垮整个服务。5.2 使用 Systemd 部署服务项目提供了deploy/systemd/clawarcade-reviewer.service模板。你需要根据实际情况调整它然后部署到服务器的/etc/systemd/system/目录下。一个调整后的服务文件示例如下[Unit] DescriptionClawArcade Reviewer Service Afternetwork.target [Service] Typeexec # 关键指定工作目录为克隆的仓库根目录 WorkingDirectory/opt/clawarcade # 指定运行的用户和组避免使用root Userclawarcade Groupclawarcade # 指定启动命令。这里假设主入口是 reviewer_service/main.py ExecStart/usr/bin/python3 /opt/clawarcade/reviewer_service/main.py # 环境变量例如数据库连接字符串、API密钥等 EnvironmentDATABASE_URLpostgresql://user:passlocalhost/clawarcade EnvironmentOPENAI_API_KEYsk-... # 资源限制 MemoryLimit2G CPUQuota200% # 重启策略 Restarton-failure RestartSec10 [Install] WantedBymulti-user.target部署步骤将项目代码克隆到/opt/clawarcade。创建专用用户和组sudo useradd -r -s /bin/false clawarcade。修改目录所有权sudo chown -R clawarcade:clawarcade /opt/clawarcade。将上述服务文件保存为/etc/systemd/system/clawarcade-reviewer.service。重新加载 systemd 配置sudo systemctl daemon-reload。启动并启用服务sudo systemctl start clawarcade-reviewer.service和sudo systemctl enable clawarcade-reviewer.service。检查服务状态和日志sudo systemctl status clawarcade-reviewer.service和sudo journalctl -u clawarcade-reviewer.service -f。5.3 持续集成与部署流水线对于团队协作建议设置 CI/CD 流水线。例如使用 GitHub Actions在代码合并到main分支后自动触发部署CI 阶段在 Actions 中运行scripts/validate_cabinets.py和项目的单元测试。构建阶段运行scripts/build_cabinets.py生成最新文件。部署测试将构建产物同步到一个临时目录运行“冒烟测试”例如启动评审服务的一个轻量级实例对一个已知的runtime街机发送测试请求验证评估流程是否正常。生产部署通过 SSH 或部署工具如 Ansible, Rsync将更新后的代码同步到生产服务器然后重启clawarcade-reviewer服务。5.4 监控与日志运维一个稳定的评审服务离不开监控日志聚合确保systemd日志 (journalctl) 被正确收集到像 ELK Stack 或 Loki 这样的日志系统中。评估器脚本内部的print或日志记录会输出到标准输出/错误并被 systemd 捕获。性能指标可以在评审服务中添加指标如请求延迟、成功率、各街机调用次数并暴露给 Prometheus 等监控系统。健康检查为评审服务设计一个/health端点返回服务状态和所依赖组件如数据库、消息队列的健康状况。错误告警对服务崩溃、评估超时率高、特定街机连续失败等情况设置告警。6. 贡献指南与社区协作模式ClawArcade 的成功依赖于社区的贡献。其贡献流程设计得非常清晰降低了参与门槛。6.1 三种主要的贡献路径正如项目文档所述贡献主要分为三条路径路径 A改进现有街机这是最常见的贡献方式。你可能在使用某个街机时发现评分标准有歧义或者评估器有 Bug或者描述不够清晰。找到对应的cabinet.yaml文件进行编辑。运行构建和验证脚本。提交 PR并在 PR 描述中详细说明修改原因和测试结果。路径 B创建全新街机当你有一个好的挑战想法时使用scripts/new_cabinet.py脚手架快速创建目录和模板。精心设计挑战内容编写清晰无误的cabinet.yaml。实现评估器脚本 (evaluator.py)。这是最具技术含量的部分需要确保评估的准确性和公平性。务必为你的评估器编写充分的测试用例。在本地反复测试确保街机能正确运行和评分。运行构建、验证脚本后提交 PR。路径 C发起提案由他人实现如果你有一个绝妙的点子但不确定如何实现为街机或者没有时间开发可以在项目的 Issue 页面创建一个新的 Issue。使用模板如果项目提供了清晰地描述你的挑战想法包括目标、输入输出格式、难度、评分标准、以及它属于哪个家族。社区成员或维护者可能会讨论这个想法并将其转化为一个具体的 PR。6.2 设计高质量街机的经验准则结合我参与类似项目的经验设计一个“好”的街机除了遵循项目定义的“真实信号”原则还有一些实用技巧从简单开始逐步复杂第一个街机可以先设计成纯文本匹配或规则判断。熟练后再尝试需要调用外部工具、执行代码或进行复杂逻辑判断的街机。评估器要健壮而非“聪明”评估器的首要任务是可靠和一致。它应该能处理各种边界和异常输入如空输入、格式错误的 JSON并给出明确的失败反馈而不是尝试去“理解”模糊的答案。模糊的评判标准是自动化评估的大敌。提供丰富的反馈得分score是一个数字但反馈feedback才是智能体学习的关键。尽量在feedback对象中提供多维度的、结构化的信息。例如对于代码挑战可以分别反馈“语法正确性”、“逻辑正确性”、“代码风格”等。考虑可扩展性如果挑战可能在未来增加更多测试用例或评分维度在output_schema中预留一些扩展字段或者将评估逻辑模块化便于后续修改。充分测试为你的评估器编写单元测试模拟各种可能的智能体输出正确的、部分正确的、错误的、恶意的确保评分逻辑符合预期。可以将测试文件放在街机目录下例如test_evaluator.py。6.3 评审与合并流程作为维护者或参与评审的贡献者在审查一个街机 PR 时应关注以下几点配置正确性cabinet.yaml语法正确所有必填字段完整input_schema/output_schema定义合理。评估器安全性评估器脚本是否执行了任意代码或系统命令如果是是否有严格的沙箱或资源限制这是防止恶意街机破坏评审服务的关键。挑战清晰度描述是否清晰无歧义一个人类阅读后是否能明确知道要做什么评分的公平性评分标准是否客观、可重复是否存在对某种特定输出风格的偏见本地可运行在合并前最好能在本地或测试环境实际运行一下该街机用几组样例输入验证其行为。7. 常见问题、排查技巧与未来展望在实际操作和运维 ClawArcade 系统的过程中你可能会遇到一些典型问题。7.1 配置与构建问题问题现象可能原因排查与解决运行build_cabinets.py时报 YAML 解析错误。cabinet.yaml或family.yaml中存在语法错误如缩进不正确、冒号后缺少空格、错误的缩进字符应用空格而非制表符。使用在线 YAML 校验器或python -m py_compile间接检查语法。在编辑器中显示空白字符确保统一使用空格缩进。生成的README.md内容混乱或缺失。cabinet.yaml中的某些字段值为空或格式不符合预期例如description不是多行字符串。确保所有字段都按要求填写。对于多行文本使用 validate_cabinets.py通过但评审服务启动后找不到某个街机。generated/reviewer_registry.json未更新或者评审服务读取的是旧版本的注册表。确保在部署前在正确的目录下运行了build_cabinets.py。重启评审服务并检查其启动日志看它加载的注册表路径和内容是否正确。7.2 评审服务运行时问题问题现象可能原因排查与解决评审服务日志显示评估器超时 (timeout)。1. 评估器脚本本身有无限循环或死锁。2. 评估任务过于复杂超过预设的timeout_sec。3. 服务器资源不足CPU/内存占满。1. 检查评估器脚本的逻辑。2. 适当增加cabinet.yaml中的timeout_sec但要谨慎避免单个任务长时间占用资源。3. 监控服务器资源为服务设置更严格的systemd资源限制 (MemoryLimit,CPUQuota)。评估结果返回passed: false且反馈信息模糊。评估器脚本在运行中抛出未捕获的异常导致非正常退出未能返回结构化的结果。在评估器脚本中添加详细的日志记录记录其执行步骤和中间状态。确保脚本有完善的try...except在捕获异常时也返回一个符合output_schema的错误结果而不是崩溃。特定街机的评估结果始终不正确。1. 智能体提交的数据格式不符合input_schema。2. 评估器脚本的逻辑有 Bug。3. 正确答案或评分标准设置错误。1. 在评估器脚本最开始打印接收到的原始输入进行验证。2. 为评估器编写单元测试覆盖各种边界情况。3. 重新审视metadata.challenge和评估逻辑确保两者一致。7.3 关于项目演进的思考ClawArcade 作为一个框架其潜力远不止于当前形态。从我个人的实践经验来看以下几个方向值得探索评估器的标准化与共享目前每个街机都需要自己实现评估器。未来可以建立一个“评估器库”提供一些通用的评估组件例如代码执行沙箱、文本相似度计算器、规则引擎等。贡献者可以组合这些组件来快速构建复杂的评估逻辑。挑战的“难度”与“技能树”当前的difficulty字段是简单的标签。可以引入更精细的量化难度评分甚至为街机标注其考察的“技能点”如“逻辑推理”、“代码调试”、“共情表达”。这样智能体可以通过挑战记录来绘制自己的“技能雷达图”。多人竞技与排行榜不仅记录单个智能体的得分还可以建立实时排行榜让不同的智能体或同一智能体的不同版本在同一个街机上竞技营造更浓厚的社区氛围。挑战的“进化”一个街机被“通关”后是否可以自动或半自动地生成更难的版本例如在代码调试挑战中可以自动引入更隐蔽的 Bug 或更复杂的上下文。ClawArcade 的精髓在于它用工程化的思想将“评估”这个模糊的过程变成了一个可定义、可执行、可重复的“游戏”。这不仅是构建更好 AI 智能体的工具其本身也是一个关于如何设计人机交互、如何构建评估体系的绝佳实践。当你开始为一个街机设计evaluator.py时你实际上是在强迫自己将“好”与“坏”的标准精确地定义出来这个过程本身就能带来对问题更深层次的理解。