Practonaut

Practonaut

面向 AI Agent、基于真实应用的本地练习场。 只需演示一次任务，就能让任意 MCP Agent 练习，并获得独立、可复现的评分——只需一条 npx 命令，无需 VM，也无需 Docker。

Practonaut 将真实应用（目前是 Excalidraw）变成练习环境。任务由起始画稿和目标组成。你或通过 MCP 接入的 Agent 可以一次执行一个操作来修改图表；每个操作都会在真实且固定版本的 Excalidraw 引擎中应用，并在计入结果前读回确认。尝试结束时，独立的检查器会判断是否达成目标。用户和 Agent 可以同时在同一会话中操作，因此你可以在浏览器中观看 Agent：历史记录会标记每项更改是由你还是 Agent 执行的（Agent · claude-code）。

60 秒快速开始

需要 Node.js 22.18 或更高版本（macOS、Linux 或 Windows）。

npx practonaut                 # opens the example task in your browser at once
npx practonaut setup           # once: the Chromium headless shell for the real Excalidraw engine (about 105–130 MB)

观看演示：在 Player 中，系统会完成一次示例任务：操作会显示在画布上，真实的 Excalidraw 会确认每项操作，结果检查器会评估最终状态。这不会计入你的结果；点击 Stop 或按 Escape 即可结束。运行 setup 之前，所有操作都仅基于模型：不会在真实应用中确认操作，并会显示横幅说明这一点及下载地址。

让 Agent 进行练习（以下以 Claude Code 为例；任何 MCP 客户端均可）：

claude mcp add practonaut -- npx -y practonaut mcp --task excalidraw/connect

在原生 Windows（非 WSL）上，npx 是 MCP 客户端无法直接启动的 .cmd 文件；请在前面加上 cmd /c：claude mcp add practonaut -- cmd /c npx -y practonaut mcp --task excalidraw/connect。

使用全新的会话运行任务并进行独立检查，以此评分：

npx practonaut bench --agent claude-code --tasks excalidraw/connect

更多内容请参阅入门指南。

创建自己的任务

在 Excalidraw 中绘制起始状态和目标，然后：

npx practonaut tasks from-scenes start.excalidraw goal.excalidraw --out my-task
npx practonaut play my-task/world

两者的差异会成为目标（步骤、标签、形状、颜色、画框、分组、箭头）。只有目标通过自身检查、起始状态未通过、生成的参考解答通过且生成的近似错误解答未通过时，Practonaut 才会写入任务。在 Player 的 Create 中也可以进行同样的操作；你还可以在真实编辑器中录制演示，并通过第二次录制确认规则。请参阅任务编写指南。

对 Agent 进行基准测试

npx practonaut bench --agent oracle --tasks all --seeds 2            # reference solutions: the score's ceiling
npx practonaut bench --agent random --tasks all --max-actions 30       # random actions: the floor
npx practonaut bench --agent claude-code --tasks excalidraw/insert-between --repeats 3
npx practonaut bench --agent "my-agent --mcp {mcp_config} --prompt {prompt}"   # any agent
npx practonaut bench --agent claude-code --world my-task/world --oracle my-task/oracle.json   # your own task
npx practonaut report ~/.practonaut/bench/<id>/report.json --html report.html
npx practonaut report ~/.practonaut/bench/<id>/report.json --verify     # re-judge from the run files
npx practonaut compare before/report.json after/report.json --fail-on-regression   # did a change break an instance?
npx practonaut report ~/.practonaut/bench/<id>/report.json --junit runs.xml --card card --badge badge.svg

每次运行都有独立的会话和数据文件夹；Agent 只能通过 Practonaut MCP 工具访问会话，并会接收与用户相同的公开任务。claude-code 预设不会将环境中的提供方密钥、令牌或计费开关传递给 Claude Code（设置 ANTHROPIC_API_KEY 会悄然切换到 API 计费），因此 Claude Code 会使用它已有的登录方式——如果你登录时使用了订阅，就会使用你的订阅；--keep-env ANTHROPIC_API_KEY 则会有意传递密钥。分数来自主机的历史记录和独立的检查器，而非 Agent 的自述：pass@1、pass^k、操作数，以及相对于参考解法的效率。JSON 报告有固定的架构。report 会检查每个通过结果和每个数字是否都能从文件中的判定推导得出——这只是检查一致性，并非验证：经过一致性修改的文件仍会通过，而 report 会注明“已检查一致性，但未经重新验证”。report --verify 会针对会话以及保存在基准测试文件夹中的真实应用导出文件重新运行检查器；报告会记录该导出文件的 SHA-256，并根据存储在该文件夹中的世界状态和参考解法进行验证（因此移动文件夹后仍可验证），重新推导每次运行的操作数和参考解法长度，并按名称拒绝任何差异；主机调用和用时会标记为由运行器报告。内容不会签名：任何能写入基准测试文件夹的人也能替换其中的文件。

报告会说明运行失败的原因，而不只说明失败这一事实：以分数形式给出通过率和 95 % 区间，优先列出失败的运行；列出每个未满足的目标条件及其最后一次失效后的操作（检查器会在每次操作后进行判定）、附带解释的错误类别、操作轨迹、最终画板——旁边附有示例目标；最终画板为真实 Excalidraw 自带的导出文件，或明确标注为示意图的画板；还会列出调用日志，以及客户端报告的令牌数、轮次数和费用。compare 会按实例并排比较两份报告：它会拒绝不可比较的报告，列出实例回退情况（同一侧重复三次，之前全部通过，之后全部失败）；若精确 McNemar 检验无法区分二者，则会注明“在当前 n 下无法区分”。两份报告必须来自同类 Agent：oracle 和 random 分别代表分数范围的两端，且只能与内置类型比较；命令模板只能与命令模板比较。要为你的 Agent 建立基线，请对你信任的某个配置进行基准测试。

在 CI 中，examples/ci/practonaut-bench.yml 会使用你自己的凭据对 Agent 进行基准测试，并在实例相较于已提交的基线出现回退时使任务失败；--junit 会为 CI 测试视图提供测试用例，每次运行一个。--card 和 --badge 会将标题行制作为 1280 × 640 的卡片（SVG 和 PNG，浅色和深色）以及徽章，并在其中标明 n、区间、验证状态和隔离级别。

示例报告是 Claude Code 在三个任务上各重复两次的真实运行 （JSON、[HTML](docs/benchmarks/example-report.html）——一个种子，六次运行：它展示的是格式，并非模型排名。详情见： 基准测试。

任务库

这是任务库，不是挑战等级。 这些任务是一组示例和共享冒烟测试，并非能力衡量标准：当前的 Claude 模型能够完成这些任务，而且五个难度更高的候选系列在 Practonaut 自身的 0.2.0 操作上也未发现提升空间（门槛报告）。 只有通过预注册阶梯门槛的系列，才会成为挑战等级。

针对 Excalidraw 0.18.1 的 16 个任务，每个任务都有英文和德文版本、三个标签变体、参考解法和相似错误方案。使用 npx practonaut tasks list 查看任务；使用 npx practonaut play <task> 打开任务；在 mcp 和 bench 中用 excalidraw/<task> 指定任务。

任务	难度	参考操作数	目标
add-step	●○○	1	添加一个步骤
connect	●○○	1	连接两个步骤
disconnect	●○○	1	移除一条捷径箭头
recolor	●○○	1	标记错误步骤
remove-step	●○○	1	移除一个步骤
rename-frame	●○○	1	为框架命名
rename-step	●○○	1	修正标签
align	●●○	3	对齐一行
close-chain	●●○	1	补上链条中的缺口
group	●●○	2	将子流程分组
insert-between	●●○	4	在两个步骤之间插入一个步骤
reconnect	●●○	1	重新连接箭头
reorder	●●○	4	将步骤按顺序排列
decision	●●●	6	构建一个有两个出口的决策流程
restyle-flow	●●●	6	将列表转换为带样式的流程
two-frames	●●●	4	将两个子流程分别整理到框架中

评分方式

1. 主机保存历史记录。 每个操作都经由同一个会话主机完成。主机会记录每个操作的状态哈希和操作者；Agent 和用户都无法通过其他方式写入状态。
2. 真实引擎确认每个操作。 安装 Chromium 后，每个操作都会应用到以无头模式运行的固定版本 Excalidraw，并读取结果；如果真实应用不认可某个操作，该操作就会被拒绝。
3. 独立检查器进行判定。 尝试结束后，另一个进程会用自己的解释器重放历史记录，用自己的解析器读取真实的 Excalidraw 导出文件，并评估目标。检查器会先确认空提交、未更改的提交和错误提交都会失败。

Agent 和 Player 中的用户会拿到相同的任务和相同的公开目标条件——每个条件都有一句话描述及其形式化表达，也就是展开写出的目标谓词——并使用相同的 Check 按钮。Agent 通过 MCP 使用 Practonaut 的语义操作，而不是 GUI。参考解法、相似错误方案和保留的检查器数据不会通过 MCP 提供给 Agent。

限制

• 仅支持一个应用。 目前唯一支持的应用是 Excalidraw 0.18.1。适配器契约旨在支持更多应用（适配器指南）；目前还没有其他适配器。
• 语义操作，而非像素操作。 Agent 通过 Practonaut 的操作（添加步骤、连接、重命名等）来执行任务，而不是点击屏幕。测量的是 Agent 能否在应用的模型中达成目标，而非能否操作 GUI。
• 未封闭。 Agent 以你的操作系统用户身份运行。拥有自身文件或 Shell 工具的 Agent 可以读取磁盘上的任务库，包括参考解法。claude-code 预设仅允许使用 Practonaut 的工具；其他 Agent 则由你自行决定。
• 目前的证据有限。 示例报告中每个任务只有两次运行。尚未研究在此练习是否能提升人们使用真实工具的能力。
• 如果没有 Chromium，Practonaut 会以纯模型模式运行：任务仍可执行，但不会与真实应用进行核对，并会明确说明这一点。
• 由用户进行的屏幕阅读器和 200 % 缩放检查：目前仅测试过一次（2026-10-17，在 macOS 上使用 Chrome 和 VoiceOver），未发现问题；尚未测试其他屏幕阅读器，也未邀请日常使用屏幕阅读器的用户进行测试（手动检查）。

要求

• Node.js ≥ 22.18 和 npm。
• 可选：运行 npx practonaut setup，一次性下载 Playwright 的 Chromium 无头 Shell，用作真实引擎。安装时不会下载任何内容；此软件包没有安装脚本。
• 本地数据存储在 ~/.practonaut（或 PRACTONAUT_HOME）中。无遥测，无需账号。练习期间，Practicenaut 自身进程不会发起网络请求（npx 会获取软件包，setup 会获取 Chromium，各一次）；你连接的 Agent 会与其自身的模型提供商通信。

文档

入门指南 · Agent 指南 · 基准测试 · 编写指南 · 世界格式 · 架构 · 适配器指南 · 会话主机 · 威胁模型 · 术语表 · 所有文档

参与贡献

欢迎提交问题和拉取请求，包括新任务、错误修复，尤其是第二个应用适配器。请从 CONTRIBUTING.md 开始；只需运行三个命令即可完成设置。安全问题请通过 SECURITY.md 报告。

许可证

Apache License 2.0；请参阅 NOTICE。随软件包提供的 Excalidraw 引擎和字体各自遵循其许可证。示例世界和任务库采用 CC0-1.0 许可证。