ritoko

Ritoko — 面向 AI Agent 的可恢复浏览器自动化

一次解决任务。保存操作流程。使用新数据再次运行。

Ritoko 是一款面向 AI Agent 的开源浏览器自动化和机器人流程自动化（RPA）工具。将已解决的任务转为可复用的浏览器、HTTP API 或 MCP 工作流，处理 CSV 或 Excel 批次，验证结果，并使用本地 SQLite 日志恢复中断的工作。

可将其用作 Claude Code 或 Codex 插件、本地模型上下文协议（MCP）服务，或 独立命令行工具。直接重放引擎无需调用大模型即可运行已保存的工作流；连接的 MCP 工具本身可能会使用 AI。

本地试用 · 快速开始 · 使用场景 · 工作原理 · 工作流示例 · 常见问题 · 进阶指南

观看 34 秒演示 — 在本地测试应用中实时执行。第五条记录提交后终止进程，恢复运行，再次处理同一 CSV：共收到 10 条提交，10 条均不重复，另有一条记录仍待确认。录制结果和环境。

为什么使用 Ritoko？

Agent 可以找出如何录入客户、下载报告或调用业务工具。重复处理批次还需要输入格式、识别每条记录的规则、成功检查方式，以及中断后的恢复方法。

Ritoko 会将这些决策保存为可复用的操作流程：

• 复用已有工作。 将参数、选择器、API 调用和验证规则保存到易读的 JSON 工作流中。
• 处理新数据。 为操作流程提供其他 CSV 或 Excel 文件，而不用针对每一行重复说明相同步骤。
• 根据证据恢复。 查看哪些项目已完成、失败或结果不确定。后续运行会跳过已确认的项目；结果不确定的写入操作则会暂缓，留待审核。

配置好目标查询后，Ritoko 还可以 在创建记录前先检查（ensure），并 通过回读结果来确认不确定的操作（reconcile）。这些 0.2.0 功能需要直接 HTTP GET，或可信且明确设为只读的 MCP 工具，并分别配置用于证明记录存在和不存在的规则。查询失败时会阻止处理该行。配置和限制。

例如：先教你的 Agent 创建一位客户，保存为 customer-import，然后让它处理下周的电子表格并汇报每项结果。

可以自动化哪些任务？

Ritoko 适用于规则明确且结果可验证的重复任务。新任务仍需要 Agent 或工作流编写者了解网站并定义操作流程。

快速开始

在本地试用十个虚构客户

需要 Node.js 24+，并在空目录中运行：

npm install [email protected]
node node_modules/ritoko/examples/first-run/demo.mjs

此演示会启动一个回环 HTTP 服务，创建包含十个虚构客户的 CSV，逐条读取并验证记录，然后重新运行并检查十行是否全部跳过且没有额外写入。无需账户、API 密钥或 Chrome。日志保存在命令输出的临时目录中。此测试针对本地模拟；浏览器中断和目标系统对账是单独的测试。英文／法文指南和预期结果。

已发布的 npm 0.2.0 包含此演示以及 ensure、reconcile 和 doctor 功能。

1. 在 Agent 中安装

需要 Node.js 24 或更高版本。使用直接运行器的浏览器工作流还需要 Google Chrome。独立 HTTP／MCP 工作流无需浏览器即可运行。

ensure、reconcile、doctor 和首次试用演示需要 0.2.0 或更高版本。升级固定版本的安装前，请查看版本化发布和发布门槛。

Claude Code

claude plugin marketplace add Swih/ritoko
claude plugin install ritoko@ritoko

Codex CLI

codex plugin marketplace add Swih/ritoko
codex plugin add ritoko@ritoko

安装后重启客户端。Git 插件包含 Agent 技能和本地 MCP 服务；其启动器会在首次启动时安装固定版本的运行时依赖，并禁用 npm 生命周期脚本。

对于较长的 Codex 批次，请在运行前配置工具调用超时。

{
  "mcpServers": {
    "ritoko": {
      "command": "npx",
      "args": ["--yes", "--prefer-online", "ritoko@latest", "mcp"]
    }
  }
}

2. 选择浏览器或集成方式

告诉 Agent 要使用哪个浏览器。直接运行器会连接到个人 Chrome；你需要在 chrome://inspect/#remote-debugging 启用远程调试并允许连接。如需使用独立配置文件，请明确选择 RITOKO_BROWSER=clean。

只要兼容的 Agent 浏览器允许执行页面脚本，就可以执行主机工作流。**Codex 当前的计算机使用 evaluate 功能是只读的，因此无法执行主机浏览器重放。**主机 API 专用批次和已连接的 MCP 工具批次仍可使用。请参阅浏览器选择和信任边界。

3. 教会一个任务，然后重复使用

向你的 Agent 提问：

使用我选择的浏览器，在此后台通过 Ritoko 记录一次客户导入。将其保存为 customer-import，并添加一个名为 input 的电子表格参数。使用 Email 作为业务键，并验证所创建客户的电子邮件地址。

如果演示创建了真实记录，Agent 应在重放批次前，使用 run_adopt 和证据接管已提交的那一行。

然后：

在同一后台运行 customer-import，并将 input 设置为 customers.csv 的绝对路径。向我展示已确认、失败和待审核的项目，以及任何已保存的文件。

之后：

恢复我上一次的 Ritoko 运行。

显示我上一次运行的报告，并说明哪些项目仍需审核。

工作原理

flowchart LR
    A["Describe a task"] --> B["Agent records or authors it"]
    B --> C["Save a JSON workflow"]
    C --> D["Replay with new data"]
    D --> E["Journal and verify each item"]
    E --> F["Report results and review holds"]

1. 定义。 Agent 记录浏览器操作，或编写受支持的 API/MCP 步骤。记录器优先使用唯一标签、角色和其他有意义的选择器；脆弱的位置选择器会被标记。
2. 保存。 工作流声明其参数、输入、业务键、提交边界（commit）和结果检查（expect）。
3. 重放。 直接引擎执行已保存的步骤。主机模式允许兼容的 Agent 执行受支持的浏览器操作或已连接的工具。
4. 记录并恢复。 SQLite 会保留每次运行的工作流和输入行。恢复批次时会使用该快照，即使原始电子表格已更改。如果页面发生变化，运行可能会暂停以便修复；如果提交状态不确定，则会暂缓处理以待审核。

失败后会发生什么？

只有在所有项目都已确认或跳过，且最终检查通过后，运行才算完成。部分结果或修复暂停会显示在报告中，并返回 CLI 退出代码 2。

验证质量很重要。 回执、记录 ID 或匹配的客户电子邮件地址可以证明预期结果。通用的“成功”横幅通常无法证明。日志仅跟踪此 Ritoko 安装；它无法阻止独立提交，也无法保证远程站点具有幂等性。

工作流是什么样的？

以下浏览器工作流示例会为每个电子表格行创建一位客户。保存前，请根据你的应用调整 URL、标签和结果选择器。

{
  "name": "customer-import",
  "version": 1,
  "description": "Create customers and verify their email.",
  "params": {
    "base": { "description": "Back-office base URL" },
    "input": { "description": "Absolute CSV or XLSX path" }
  },
  "items": {
    "from": "{{param.input}}",
    "key": "{{item.Email}}",
    "scope": "{{param.base}}"
  },
  "item": [
    {
      "do": "goto",
      "url": "{{param.base}}/customers/new"
    },
    {
      "do": "fill",
      "target": { "primary": { "by": "label", "text": "Email" } },
      "value": "{{item.Email}}"
    },
    {
      "do": "click",
      "target": {
        "primary": { "by": "role", "role": "button", "name": "Create customer" }
      },
      "commit": true
    },
    {
      "do": "expect",
      "target": { "primary": { "by": "testid", "id": "customer-email" } },
      "text": "{{item.Email}}"
    }
  ]
}

key 用于标识业务记录；本例中的 scope 用于区分目标 URL。如果多个账户共用一个 URL，请将账户标识符加入范围。commit 标记不可逆操作，后续的 expect 则检查该特定行。只读批次应声明 readOnly: true。

请参阅完整的示例工作流、工作流架构和 HTTP/MCP 参考。

不使用 Agent 的情况下通过 CLI 运行

从 Git 检出目录中，启动器可以导入并运行现有工作流，无需 Agent 或大模型 API 密钥：

git clone https://github.com/Swih/ritoko.git
cd ritoko
node bin/ritoko.mjs import examples/rpa-challenge.json
node bin/ritoko.mjs run rpa-challenge
node bin/ritoko.mjs report

RPA Challenge 示例会下载自己的 Excel 输入文件。运行前，请按上述说明选择直接浏览器。若要有意再次运行同一挑战，请添加 --repeat；待审核项仍会被阻止。

对于中断的直接运行，请使用 node bin/ritoko.mjs resume <runId>。默认情况下，工作流、日志、证据和输出文件存放在 ~/.ritoko 中；可通过 RITOKO_HOME 更改位置。

批量任务排查问题前，请使用 node bin/ritoko.mjs doctor 检查本地设置。对于配置了目标查询的待审核行，node bin/ritoko.mjs reconcile <runId> <key> 会读取结果，而不会再次提交。手动执行 resolve 时，必须提供备注，并在自行检查目标后添加 --confirm-checked。

证据与当前范围

记录的演示使用了 Windows 上的 Ritoko 0.1.0 和无头 Chrome。RPA 网站的计时不包含安装和设置；记录的 CLI 总耗时为 3.559 秒。RPA Challenge 不提供逐行回执，因此示例依赖最终得分。这些演示和受控测试无法证明所有网站的可靠率或吞吐量。

常见问题

我需要单独的大模型 API 密钥吗？

Ritoko 的确定性运行器不需要。使用插件时，客户端 Agent 会通过现有订阅或 API 配置提供推理能力。录制、修复和主机编排仍会使用该客户端，已连接的工具也可能自行调用模型。外部 API、OCR 服务或付费生成服务需要各自的访问权限，并且可能会单独收费。

Ritoko 能读取发票或执行 OCR 吗？

文档读取是可选功能。document_image 会将下载的 JPEG/PNG 返回给客户端 Agent，由其模型读取。Ritoko 不包含本地 OCR 引擎或发票解析器。选用的外部 OCR 服务需要使用用户配置的凭据。每张新图片仍需由 Agent 或该服务处理；普通浏览器和 API 回放则不需要。

Ritoko 能使用我已登录的浏览器吗？

直接运行器可在获得你的远程调试许可后连接个人 Chrome。你也可以明确选择独立的干净配置文件。集成浏览器支持取决于客户端允许的操作；请参阅驱动程序限制。如有需要，请在选定的浏览器中完成登录或 MFA。

Ritoko 能与任意 MCP 客户端配合使用吗？

能够启动 stdio 进程的本地客户端可以连接到该服务。Claude Code 和 Codex CLI 是经过测试的插件客户端。其他客户端需要进行配置和能力检查。没有单独的连接机制时，隔离的云端客户端无法访问你的本地 MCP 进程或文件。

Ritoko 能保证不重复写入吗？

不能。它会跳过已确认的项目，并在其日志中阻止不确定的写入，包括后续运行。工作流需要使用正确的业务键、目标范围和结果检查。独立提交和远程系统的行为不受该日志管理。要解决待审核项目，需要提供实际发生情况的证据。

浏览器录制能转换成 API 工作流吗？

可选的网络捕获会提供 fetch/XHR 元数据，帮助 Agent 调查 API。它不会自动将录制内容转换为可执行的 API 步骤。请验证 API 契约和身份验证，测试一个经授权的行，然后明确保存替代方案。参见网络提示。

文档与贡献

• 高级用法：客户端配置、CLI、浏览器选项、主机批次、恢复和工作流规则。
• Agent 技能：录制、运行、采用和修复工作流的说明。
• 集成参考：输入格式、HTTP/MCP 步骤结构和驱动程序限制。
• 问题指南和工具对比：选择工作流并了解其权衡。
• 搜索可见性测量：基于捕获的回答生成固定的英语/法语提示词和报告。
• 发布门槛：必要检查、验证路线图、发布和更新政策。
• 本地软件隐私：已存储的运行数据、配置的目标、凭据和保留期限。
• 报告错误或申请功能：请注明客户端、Node/浏览器/OS 版本，并提供已脱敏的复现步骤。请妥善保护凭据和业务数据。

开发环境需要 Node.js 24+ 和 pnpm：

pnpm install
pnpm check
pnpm test
pnpm build
pnpm test:e2e

Ritoko 会自动执行你获准使用的服务。它不会绕过 CAPTCHA 或反机器人保护。工作流和 API/MCP 命令都是可执行配置，因此必须由可信作者编写。

由 Swih 与 Claude（Anthropic）和 Codex（OpenAI）共同构建，Git 历史中已将其列为贡献者。根据 MIT 许可证发布。