arc-reasoning-quiz

English documentation: README.en.md

一个纯 Node.js 的可复现 A/B/C/D 练习题包。它把两件事分开：公开练习题可以下载后离线作答、评分和查看解析；模型评测则通过交互式向导连接你自己选择的兼容 API，在运行期间不把题面、答案或模型原始回复打印到终端。

趣味 IQ 映射只是本题库正确率的 70–130 娱乐化显示，不是临床、教育或标准化 IQ 测量。ARC-AGI-2/3 类别中的 A/B/C/D 题是派生诊断题，不等同于官方分数。0.3.2 同时发布题面和独立答案键，因此下载后可以直接评分；这也意味着它是公开练习集，不是保密盲测集。

快速开始

需要 Node.js 20 或更高版本。新手只需运行一条命令：

npx arc-reasoning-quiz

在交互式终端中它会显示一个编号菜单。默认选择「测试模型」后，只需依次：

1. 粘贴兼容服务的 Base URL；
2. 粘贴 API key（输入隐藏，只保存在当前进程内存）；若服务要求 OAuth，就在同一个隐藏输入处键入 /oauth；
3. 程序通过安全的 GET /v1/models 获取可用模型，按编号选择；
4. 选择「快速诊断 / 下限完整检查 / 上限抽样 / 全量 / 本地 ARC-2」之一并确认。

运行时只显示脱敏进度（完成、超时、格式不合规、延迟）和最终聚合结果；不会在模型测试过程中显示题面、正确答案、解析、原始模型输出、Base URL 或 API key。模型名旁的「推理导向」「轻量/快速」仅来自名称的保守提示，绝不是能力评级；实际结果才是评测记录。

Base URL 必须提供 OpenAI 兼容的模型发现接口 /v1/models。空地址会直接要求重新输入；模型发现遇到网络、认证或兼容性错误时，向导不会发送题目，并提供 r 重试、b 重填 Base URL、k 重新认证、q 取消四种恢复操作。若服务根本不提供该接口，仍可使用后文的高级命令显式指定模型与线路格式。

可选 OAuth 登录

API key 是默认且最少步骤的路径。对于支持标准 OAuth 的服务，在隐藏的 API key 输入处输入 /oauth 即可切换：CLI 会先安全读取该资源公开的 OAuth metadata；若服务没有公开 resource metadata，可以手动填写服务文档给出的 issuer。随后只需填写服务方注册的 public client ID（它不是 secret，也不能由 Base URL 安全猜出）和可选 scope。

默认使用适合终端的 Device Authorization：CLI 显示服务返回的验证地址与一次性 user code，用户自行在浏览器完成登录。若服务只支持浏览器授权，可选 Authorization Code + PKCE；回调仅监听 127.0.0.1 的临时随机端口，完成、取消或超时后立即关闭。程序不会启动浏览器、读取浏览器 Cookie、保存 access token 或 refresh token，也不会将令牌、issuer、Base URL 写进报告。OAuth 完成后仍通过同一 Base URL 的 /v1/models 选择模型，因此服务还需要提供 OpenAI 兼容模型列表。

这里实现的是 RFC 标准 Device Authorization / PKCE / metadata discovery，不会猜测或模拟第三方私有 OAuth 流程。服务未提供标准 OAuth、没有给 CLI 注册 public client ID，或不兼容 Bearer token 时，请使用该服务支持的 API key 方式。

默认菜单还有两个本地/官方交互入口：

• 浏览本地 ARC-AGI-2：只读取你明确选择的本机目录，展示训练输入/输出与待测输入，刻意不显示待测输出，也不上传文件。
• 交互式官方 ARC-AGI-3：先确认才创建 scorecard，再从服务返回的合法动作中选择；终端展示裁剪后的公开帧状态、可用动作和最终数值摘要。会话 cookie 只在当前进程内存中保存，API key 不会写入报告。

以下是适合脚本、人工作答或复现实验的高级三步流程：

# 1. 先看题库里有什么：两层、各类别题量、能力维度
npx arc-reasoning-quiz --list

# 2. 抽题（题面末尾会直接给出可复制的评分命令）
npx arc-reasoning-quiz --tier floor --count 5 --seed run-1

# 3. 把答案写进 answers.json 后评分
npx arc-reasoning-quiz --count 5 --seed run-1 --tier floor --answers .\answers.json

直接使用向导可避免记忆这些参数。在交互式终端中无参数会打开同一菜单；非交互式脚本仍可使用下面的显式参数生成可复现题纸。

两层设计：--tier floor 与 --tier ceiling

题库分两层，用途不同：

| 层 | 题量 | 定位 | | --- | --- | --- | | floor | 16 | 基础能力下限。逻辑、代码语义、协议格式、实验方法学。一个合格模型应当全对，答错就是硬伤信号。 | | ceiling | 25 | 能力上限。ARC-AGI-2 风格归纳题、协议状态追踪，以及五道研究级数学题，用于区分前沿模型。 |

每题带四个能力维度 capabilities: {execution, induction, planning, proof}（0–5），difficulty 由四轴取最大值派生，因此不会出现「照说明书执行却标最高难度」这种失真。--list 会打印每个类别的峰值能力。

上限层里 arc2-induct-* 是真正的 ARC 式归纳题：只给训练样例，不公布规则，需要自行归纳后预测。其余 ARC 派生题会在题面注明「已给出完整规则，考精确执行」。

npx arc-reasoning-quiz --tier ceiling --count 10 --seed hard-1   # 只测上限
npx arc-reasoning-quiz --tier floor --mode full                  # 全部基础题

更多用法

npx arc-reasoning-quiz --mode random --count 10 --seed 20260808 --format quiz
npx arc-reasoning-quiz --mode full --format quiz
npx arc-reasoning-quiz --mode autocorrect --count 10 --models model-a `
  --base-url https://provider.example --api-key-env REASONING_QUIZ_API_KEY
npx arc-reasoning-quiz --mode random --category logic,code --count 8 --seed fixed
npx arc-reasoning-quiz --mode full --answers .\answers.json --format review
# 独立重算第 33-37 题的 minimax、策略、图构造和门状态机证书
npx arc-reasoning-quiz --verify-certificates

同一个 seed 会得到同一组题，适合复现实验。--format json 只输出题面，不包含答案和解析；评分时 CLI 自动加载同包的 questions/builtin.answers.json。答案键内的 questions_sha256 必须精确匹配当前 builtin.json，题面或答案键被混用时 CLI 会拒绝静默评分。如需尝试另一份兼容答案键，才使用 --answer-key PATH 或 REASONING_QUIZ_ANSWER_KEY_PATH；替代答案键也必须携带对应的 questions_sha256。

位置偏差与 --shuffle-options

公开答案键在发布前会检查 A/B/C/D 标签近似均衡。--shuffle-options 仍可用 seed 确定性地重排每题选项，适合做同一题面不同布局的消融实验。新手模型向导会自动开启它，并使用同一 seed 选择八种仅改变指令框架和字段标签的展示模板；题干、选项、规则、量词和答案映射保持不变。这样可以测量固定版式/提示词依赖，又不会用自动改写损坏形式化题目的唯一答案。

npx arc-reasoning-quiz --mode full --shuffle-options --seed run-1 `
  --models model-a --base-url https://provider.example --api-key-env REASONING_QUIZ_API_KEY

评分按题面标签进行，纠错报告额外给出 sourceSelected / sourceCorrect 和 meta.optionMaps（题面标签 → 题库原始标签）便于人工核对。optionMaps 只出现在评分和纠错报告里，不会进入题面输出。 --shuffle-options 只能减少固定标签的统计偏差，不能把已公开题目变成保密盲测。

布局指纹 layout：防止用错 seed 评分

打乱之后有个致命陷阱：拿 seed A 的题面作答，却用 seed B（或忘了加 --shuffle-options）评分，分数会静默变成垃圾——实测一份满分答案会掉到 8/37，看起来像模型很差，其实是参数用错了。

所有题面输出都带一个 layout 指纹（meta.layout，16 位十六进制），它由题目顺序和每题的选项排列共同决定。把它写进答案文件顶层：

{
  "layout": "2d3b4bb4c34de158",
  "logic-001": "C",
  "code-003": "A"
}

评分时如果对不上，程序会直接报错退出而不是给出错误分数：

错误：答案文件的 layout 是 2d3b4bb4c34de158，但本次题面是 35ff6dc401be3681。……

layout 是可选的：不带这个字段的答案文件照常评分，向后兼容。但只要你用了 --shuffle-options，就强烈建议带上。

题库版本发布前还应对干扰项质量进行人工审阅：选项长度、措辞和题型来源都可能形成模型可利用的捷径。它们不能用选项打乱替代，也不能由单一总分掩盖。

题目证据与外部规范

每道可计算题在测试中都有独立重算或状态机证书；第 33–37 题还会执行完整 minimax、策略重放、图构造或逐轮模拟。逐题的规则闭合、信息集、量词、成本函数和验证方式见随包发布的 QUALITY_ASSURANCE.md。Java、Unicode、SQL 与 ARC-AGI-2 等必须依赖外部标准的事实，均列在 REFERENCES.md，其中注明了规范链接、最后核对日期和题面边界。自定义 wrapper 题不以外部 API 记忆作为答案依据。

不需要源码仓库也可运行 npx arc-reasoning-quiz --verify-certificates：该命令会从 npm tarball 内的题面和答案键独立重算高难题。它对有限 minimax 和状态机执行穷举/重放；对无限状态空间结论则执行一般性不变量、信息集分离、图度数与奇偶论证的可执行检查，而不会把有限窗口抽样伪装成完整证明。它输出题面 SHA-256、状态数与见证摘要；任何不一致都会以非零退出状态失败。

盲测污染与 --blind-test-only

source=shared-chat-derived 的 5 道题（shared-hard-*）带 blind_test_safe: false：它们的答案和完整解析曾在公开对话中出现。--blind-test-only 仅按这条来源标记排除它们：

npx arc-reasoning-quiz --mode full --blind-test-only --shuffle-options --seed blind-1

这不是“恢复盲测”的开关。0.2.0 曾把完整答案发布到 npm，因此固定的 builtin 题目都不应再用于声称对公开模型或人员的保密、无污染能力评估；请用权限隔离的新鲜题、服务端评分和预先注册的协议做真正盲测。

三种运行模式：

• random：固定 seed 的随机抽题。
• full：完整题库。
• autocorrect：模型先回答；错误、空缺或格式不合规时自动复核一次。复核提示不会包含正确答案，报告会同时保存首次答案、复核答案和纠正是否成功。

也可以对全量题库启用模型自我纠错：--mode full --self-correct --models ...。 模型报告会同时给出首次准确率、最终准确率、准确率提升、自纠次数和纠正成功次数。

内置题库包含 arc2-hard 和 arc3-hard 两组高难派生题；它们能直接参加 random/full/autocorrect，但明确不计作官方 ARC 分数。

答案文件可以是题目编号到选项的对象，也可以使用 answers 包一层：

{
  "logic-001": "C",
  "code-003": "A"
}

纠错模式会区分答对、答错、未作答、格式错误和未知题目编号，并逐题给出你的答案、正确选项、正确文本和解析。解析器接受严格 {"choice":"A"}、单独的 A，或只含一个明确选项字母的短文本；同时出现多个 A/B/C/D 时拒绝猜测并标为歧义。答案文件只在本地读取；题面模式不会显示答案。

使用本机 ARC-AGI-2 数据

包不会携带 ARC-AGI-2 原始数据，也不会在运行题目时悄悄创建目录。第一次使用可以明确初始化一个空的本地工作目录：

npx arc-reasoning-quiz --init-arc2-dir .\arc-agi-2-local

这会只创建 training/、evaluation/ 和说明文件；不会下载、复制、上传或伪造任何 ARC 数据。把你合法取得的 ARC-AGI-2 JSON 放入这两个目录之一（允许保留任意子目录布局），再通过 --arc2-dir 读取并生成本地派生题：

npx arc-reasoning-quiz --arc2-dir .\arc-agi-2-local `
  --arc2-limit 20 --mode random --count 10 --seed arc2-demo --format quiz

# 交互式本地浏览：仅展示训练输入/输出和待预测输入，绝不显示测试输出
npx arc-reasoning-quiz --arc2-explore

--init-arc2-dir 只接受新的空目录或之前由该命令初始化过的目录；遇到其他非空目录会拒绝写入，避免覆盖你的数据。适配器会展示训练输入/输出和测试输入，并从真实输出生成三个确定性扰动项。它不把本地绝对路径写入题面，也不把数据复制进 npm 包；正式 ARC-AGI-2 比较仍应使用官方评测工具。

加载全部本地可转换任务：

npx arc-reasoning-quiz --mode random --category arc2-local --count 20 `
  --arc2-dir E:\path\to\arc-agi-2\data --arc2-all --seed arc2-all-sample --format quiz

连接自建 ARC-AGI-2 评测后端（可选）

--arc2-api 是一套通用客户端，用来对接你自己搭建的 ARC-AGI-2 盲测服务。包内不含任何服务器地址， 地址只能由环境变量注入；后端放在 Cloudflare Access 之后时，用服务令牌（Service Auth）认证：

$env:ARC2_API_BASE_URL   = 'https://your-own-host.example'
$env:CF_ACCESS_CLIENT_ID = '<service token client id>'
$env:CF_ACCESS_CLIENT_SECRET = '<service token secret>'

npx arc-reasoning-quiz --arc2-api manifest --arc2-split evaluation --arc2-limit 20
npx arc-reasoning-quiz --arc2-api run --arc2-split evaluation --count 10 --seed run-1
npx arc-reasoning-quiz --arc2-api status --arc2-run-id <run_id>
npx arc-reasoning-quiz --arc2-api submit --arc2-run-id <run_id> --arc2-predictions .\predictions.json
npx arc-reasoning-quiz --arc2-api close --arc2-run-id <run_id>

后端需要实现的端点契约。这套形状照官方 ARC-AGI-3 REST API 的生命周期设计，两者可以共用一套心智模型：

| ARC-AGI-3 官方 | 本接口 (ARC-AGI-2) | 说明 | | --- | --- | --- | | GET /api/games | GET /api/v1/arc2/manifest?split=&limit= | 发现可用任务，limit 上限 50 | | POST /api/scorecard/open → card_id | POST /api/v1/arc2/runs → run_id | 开一次 run；run_id 聚合多个任务 | | POST /api/cmd/RESET → 盲化 frame | 同上，返回去掉每个 test[].output 的任务 | 训练样例可见，答案不可见 | | POST /api/cmd/ACTIONn | POST /api/v1/arc2/runs/{run_id}/submit | 提交预测，1–50 项 | | GET /api/scorecard/{card_id} | GET /api/v1/arc2/runs/{run_id} | 只读进度 | | POST /api/scorecard/close | POST /api/v1/arc2/runs/{run_id}/close | 结算并返回准确率（无请求体） |

评分是 ARC-AGI-2 官方的 pass@2：每个 test pair 最多两个候选网格，任一命中即算该 pair 正确；一个任务的所有 pair 都正确才算解出。predictions 每个元素对应一个 test pair，可以是单个网格、[grid1, grid2]，或 {"attempt_1":…, "attempt_2":…}。

盲测语义：submit 只回执 accepted_count / remaining_count，不返回对错；close 之前 status 也不含任何 exact 字段。这样单次 run 内无法靠反复试探套出答案。同一 task_id 重复提交返回 409，已结算的 run 再提交返回 400。

seed 决定题目选择：同 seed 复现同一题集，但每次仍分配新的 run_id。

task_id 必须是 8 位十六进制，run_id 是 20–64 位 [A-Za-z0-9_-]。客户端强制以下不变式， 后端违反其中任何一条都会直接报错而不是静默接受：

• 非回环地址必须 HTTPS；URL 不允许带凭据、query 或 fragment。
• redirect: manual：任何 3xx 都判为被 Cloudflare Access 拦截，不跟随、不重放凭据。
• 响应中出现 expected / ground_truth / answer_key / correct_output，或 test[].output， 一律视为后端泄漏答案并中止。
• 响应上限 8 MiB，请求体上限 2 MiB，默认超时 120 秒（最大 10 分钟）。
• 服务令牌只从环境变量读取，不接受命令行传入，也不会出现在输出里（打印前按密钥做脱敏替换）。

没有自建后端时跳过本节：--arc2-dir 的本地模式和下面的官方 ARC-AGI-3 API 都不依赖它。

调用官方 ARC-AGI-3 API

ARC-AGI-3 现在使用官方在线 REST API，不把观察/行动/学习/规划闭环伪装成 A/B/C/D 静态题。官方 API 的完整流程是列出游戏、打开 scorecard、RESET、按返回的 guid 发送 ACTION1–ACTION7，最后关闭 scorecard。下面这些命令已经直接对应官方 HTTP 路径；字段和流程以 ARC-AGI-3 官方 Full Play Test 文档 为准：

新手可直接运行 npx arc-reasoning-quiz --arc3-play。它在创建 scorecard 前明确确认、只允许服务当前公开帧声明的动作、展示有界的状态预览；下面的逐条生命周期命令是高级/脚本化替代方案。

$env:ARC_API_KEY = '<从密码管理器注入的新 key>'

# 1. 列出官方在线游戏
npx arc-reasoning-quiz --arc3-api list-games

# 2. 打开 scorecard
npx arc-reasoning-quiz --arc3-api open-scorecard --arc3-tags '["arc-reasoning-quiz"]'

# 3. 用上一步返回的 card_id 和游戏 ID 启动游戏；返回 guid/state/frame
npx arc-reasoning-quiz --arc3-api reset `
  --arc3-game-id <game_id> --arc3-card-id <card_id>

# 4. 使用 RESET 返回的 guid 发送动作；ACTION6 还要提供坐标
npx arc-reasoning-quiz --arc3-api action --arc3-action ACTION1 `
  --arc3-game-id <game_id> --arc3-card-id <card_id> --arc3-guid <guid>
npx arc-reasoning-quiz --arc3-api action --arc3-action ACTION6 `
  --arc3-game-id <game_id> --arc3-card-id <card_id> --arc3-guid <guid> --arc3-x 3 --arc3-y 4

# 5. 可选：读取尚未关闭的 scorecard 进度
npx arc-reasoning-quiz --arc3-api get-scorecard --arc3-card-id <card_id>

# 6. 结束并取得最终 scorecard 结果
npx arc-reasoning-quiz --arc3-api close-scorecard --arc3-card-id <card_id>

默认地址是 https://three.arcprize.org，请求使用 X-API-Key 和 Accept: application/json。API key 只从 ARC_API_KEY（或 --arc3-api-key-env 指定的环境变量）读取，不接受命令行 key，也不写入报告。官方在线接口要求保持游戏会话亲和性：本客户端只在当前 CLI 进程的内存中保存 RESET/动作响应的受上限 cookie，并仅回送到同一官方源；不会写入文件、报告或终端输出。官方在线接口有请求速率限制；开发阶段可以改用官方 Toolkit 的 offline 模式。

现有 --arc3-list-tools / --arc3-call 仅作为本地或自建 MCP 的可选扩展。npm 包不会自动执行未经确认的 npx 包；使用 MCP 时必须显式提供本地 launcher，或在同一工作区存在本地入口：

npx arc-reasoning-quiz --arc3-command node `
  --arc3-command-args '["C:\path\to\arc-agi-3-mcp.mjs"]' `
  --arc3-list-tools

跨厂商对比多个模型

一次运行就能比较不同厂商的模型:--base-url、--api-key-env 和线路格式都支持按模型逐一对应。

$env:KEY_ANTHROPIC = '<从密码管理器注入>'
$env:KEY_OPENAI    = '<从密码管理器注入>'

npx arc-reasoning-quiz --mode full `
  --models "claude-sonnet-4-5@anthropic,gpt-5@openai" `
  --base-url "https://api.anthropic.com,https://api.openai.com" `
  --api-key-env "KEY_ANTHROPIC,KEY_OPENAI" `
  --max-tokens 4096 --format table

| 选项 | 说明 | | --- | --- | | --wire anthropic\|openai | 线路格式。anthropic 用 x-api-key 打 /v1/messages;openai 用 Authorization: Bearer 打 /v1/chat/completions。也可以写成 --models "a@openai,b@anthropic" 逐模型指定。 | | --max-tokens N | 输出预算,默认 1024。推理模型务必调高:预算太小会把回答截断,记成格式失败而不是答错。 | | --temperature N | 采样温度,默认 0;传 off 则请求体完全不带该字段(部分推理模型拒绝这个参数)。 |

--base-url 与 --api-key-env 给一个值时所有模型共用,给多个值时必须与 --models 数量相同。

报告按两层与四轴给分

| 模型 | 题数 | 正确 | 下限层 | 上限层 | … |
| strong-mock | 41 | 41 | 16/16 | 25/25 | … |
| weak-mock   | 41 | 11 | 5/16 ⚠ | 6/25 | … |

能力维度（按题目载荷加权的正确率）：
| 模型 | 精确执行 | 规则归纳 | 方案规划 | 证明构造 |
| strong-mock | 100% | 100% | 100% | 100% |
| weak-mock   |  27% |  26% |  26% |  34% |

下限层未满分会标 ⚠ 并在 JSON 报告里给出 redFlag: true 和漏掉的题号——这些题一个合格模型应当全对,失分是硬伤信号而非能力差异。能力四轴按题目在该轴上的载荷加权,可直接画雷达图。

报告的隐私边界

报告默认可以安全分享:

• 不含 API key。向导中的隐藏输入只存在于当前进程；高级模式从环境变量读取。两种方式都不接受命令行 key（argv 会落进进程列表和 Windows Security 4688 日志）。
• 不含端点地址。自建或内网 base-url 不会写入报告,只记录密钥所用的环境变量名。
• 不含原始模型响应。只保存选项、正确性、格式是否合规、延迟与 token 用量。
• meta.request 记录 maxTokens / temperature / timeoutMs / repeats 和每个模型的线路格式,供他人复现同一次评测。

逐模型测试

模型接口支持 Anthropic Messages 与 OpenAI Chat Completions 兼容请求。新手优先使用无参数菜单；高级/脚本模式的密钥通过环境变量注入，不能写在命令行参数、题库或报告中：

$env:REASONING_QUIZ_API_KEY = '<由密码管理器注入的新 key>'
npx arc-reasoning-quiz --mode random --count 10 --seed model-run `
  --models model-a,model-b --base-url https://provider.example `
  --api-key-env REASONING_QUIZ_API_KEY --format table --output .\report.json

模型按顺序、每题一次请求；程序只保存选择、正确性、格式是否合规、延迟和 token 用量，不保存原始回复。表格会给出总准确率、分类准确率、格式错误、平均/P95 延迟和重复测试稳定性。

题目来源边界

• questions/builtin.json：本包维护并公开发布的 A/B/C/D 题面；不内嵌答案、解析或审计细节。
• questions/builtin.answers.json：与题面一一对应的公开答案键，随 npm tarball 一起发布，因此任何下载者都能直接做本地评分和查看解析。
• questions/shared-chat-catalog.md：本地审计用的高难题标题和能力标签；它来自用户提供的共享聊天，但刻意不进入 npm tarball，以避免把私有上下文带入公开包。
• arc2-proxy / arc3-proxy：公开任务范式的文字化代理题，仅用于快速诊断。
• --arc2-api：连接你自建的盲测后端；包内既不含服务器地址，也不含 ARC-AGI-2 原始数据。
• 官方 ARC-AGI-3 的观察、行动、学习、规划和适应闭环使用上面的官方 REST API；本地 arc-agi-3-mcp 只作为可选扩展，不用选择题分数冒充交互式基准。
• arc3-hard-002/003/004 描述的是本包自定义 MCP wrapper 协议，题面已显式标注。官方 ARC-AGI-3 REST 的复杂动作固定是 ACTION6（携带 0–63 的 x/y），ACTION7 是 undo；本 wrapper 的 arc3_get_scorecard(session_id) 按会话读取 scorecard，均不是官方接口名。

隐私和发布

默认题面、纠错和统计模式不联网，下载后无需任何额外配置即可使用全部 37 道 builtin 题。只有显式使用 --models 时，程序才会把选中的题面发送到你指定的模型端点，并在内存中用环境变量 API key 发起请求。远程端点默认必须是 HTTPS，原始模型响应不会写入报告。ARC-3 子进程只继承必要的运行环境变量，不会自动继承 API key。包本身不依赖第三方 npm 运行库。发布前应执行：

npm run verify-release

verify-release 会实际打包 tarball，并验证公开题面和公开答案键完整对应；它仍拒绝私有答案键、测试目录、API key、.env、密码库导出、服务器地址和个人聊天原文。