showrun (Useshowrun)

ShowRun

用于确定性、版本化浏览器自动化的TypeScript+Playwright框架 任务包：以JSON或代码定义流，通过CLI或MCP运行它们，并使用AI辅助仪表板（示教模式）进行编辑。

何时使用ShowRun

• 在没有API的情况下工作 -在没有公共或文档化API（如遗留平台）的情况下实现站点自动化，尽管它与现有API一起工作也很好
• 浏览器代理太慢或不稳定 --你需要生产级的可靠性，而不是尽力而为的提示
• 自动化需要内存、迭代和速度 --工作流程不断发展，您需要版本化、可重复的运行
• 人工智能发现工作流程，人类拥有它 --使用Teach Mode让AI提出步骤，然后将其锁定到确定性和可导出的流中

快速开始

使用npx

# Launch the dashboard — that's it!
# On first run, a setup wizard will prompt for your API key
# and the Camoufox browser will be downloaded automatically.
npx showrun@latest dashboard --headful  # --headful is optional; omit for headless mode

从Git克隆

# Clone the repository
git clone https://github.com/useshowrun/showrun
cd showrun

# Install dependencies (requires pnpm)
pnpm install

# Approve native module builds (pnpm 10+ requires this for native deps like better-sqlite3)
pnpm approve-builds

# Build all packages
pnpm build

# Start the dashboard (Camoufox browser downloads automatically on first launch)
pnpm dashboard --headful

运行示例

pnpm test:example

什么是任务包？

A. 任务包 是一个独立的、版本化的自动化模块，它：

• 定义自己的元数据（id、名称、版本、描述）
• 声明输入模式（它接受哪些参数）
• 声明收藏品模式（它提取什么数据）
• 实现确定性 run() 使用Playwright执行浏览器自动化的函数
• 可以独立进行版本控制和升级

任务包旨在：

• 确定性的：运行时没有人工智能，纯代码执行
• 版本化：每个包在元数据中都有自己的版本
• 便携的：可以独立打包和分发
• 可测试的：结构化日志记录和错误工件收集

项目结构

/showrun
  /packages
    /core               # Types, loader, validator, runner, DSL interpreter, auth resilience
    /harness            # CLI to load + execute a task pack
    /mcp-server         # MCP server exposing Task Packs as tools (HTTP/SSE)
    /dashboard         # Web UI: run packs, view runs, Teach Mode (AI-assisted flow editing)
    /browser-inspector-mcp  # MCP for browser inspection (screenshots, DOM, network)
    /taskpack-editor-mcp   # MCP for editing task pack flows (apply patches, run pack)
    /showrun            # Unified CLI (dashboard, MCP, etc.)
  /taskpacks
    /example            # TypeScript task pack
    /example-json       # JSON-only task pack (no build step)
    /ycombinator.get.batch  # Example with network steps + run-once

创建新任务包

任务包使用 json-dsl 包含两个文件的格式：

• taskpack.json -元数据（id、名称、版本、描述）
• flow.json -输入、收藏品和流程步骤

无需构建步骤！

1.创建任务包目录

mkdir -p taskpacks/my-pack

2.创建 taskpack.json

{
  "id": "my.pack.id",
  "name": "My Task Pack",
  "version": "0.1.0",
  "description": "What this pack does",
  "kind": "json-dsl"
}

3.创建 flow.json

{
  "inputs": {
    "url": {
      "type": "string",
      "required": true,
      "description": "URL to navigate to"
    }
  },
  "collectibles": [
    {
      "name": "title",
      "type": "string",
      "description": "Page title"
    }
  ],
  "flow": [
    {
      "id": "navigate",
      "type": "navigate",
      "params": {
        "url": "{{inputs.url}}",
        "waitUntil": "networkidle"
      }
    },
    {
      "id": "extract_title",
      "type": "extract_title",
      "params": {
        "out": "title"
      }
    }
  ]
}

就是这样！看 taskpacks/example-json/ 举一个完整的例子。

4.跑你的包

node packages/showrun/dist/cli.js run ./taskpacks/my-pack --inputs '{"url":"https://example.com"}'

退出代码： 0 成功， 1 执行失败， 2 验证错误。

日志和工件

当任务包运行时，线束会创建一个带时间戳的运行目录：

./runs//
  events.jsonl          # Structured log events (JSONL format)
  artifacts/            # Screenshots and HTML snapshots (on error)
    error.png
    error.html

日志事件

事件被写成JSONL（每行一个JSON对象）：

• run_started：包执行开始
• step_started：一个步骤开始
• step_finished：一个步骤完成
• run_finished：包执行完成
• error：发生错误

每个活动包括：

• timestamp：ISO 8601时间戳
• type：事件类型
• data：事件特定数据

人工制品

出现错误时，线束会自动保存：

• 全页面截图(error.png)
• 页面HTML快照(error.html)

这些已保存到 ./runs//artifacts/.

仪表板和示教模式

仪表板是一个web UI，用于运行任务包、查看运行和事件以及编辑流 教学模式 （使用LLM和浏览器MCP的AI辅助步骤建议）。

pnpm dashboard                          # headless (default)
pnpm dashboard --headful                # see the browser window
pnpm dashboard --packs ./my-packs       # custom packs directory

打开终端中显示的URL。使用示教模式让AI通过在浏览器中描述操作来提出DSL步骤。

看 packages/dashboard/README.md 用于环境变量和完整选项。

配置

ShowRun使用分层配置系统。值按以下顺序解决（最高优先级获胜）：

Real env vars > .env file > project config.json > global config.json > built-in defaults

快速设置

# Create a project-local config
showrun config init

# Or create a global config (shared across all projects)
showrun config init --global

# See what ShowRun resolved
showrun config show

# See which directories are searched
showrun config path

配置文件格式

配置文件存储为 .showrun/config.json （项目本地）或特定于平台的全局目录中：

{
  "llm": {
    "provider": "anthropic",
    "anthropic": { "apiKey": "sk-ant-...", "model": "", "baseUrl": "" },
    "openai": { "apiKey": "", "model": "", "baseUrl": "" }
  },
  "agent": {
    "maxBrowserRounds": 0
  },
  "prompts": {
    "teachChatSystemPrompt": "",
    "autonomousExplorationPromptPath": "",
    "teachModeSystemPromptPath": ""
  }
}

每个键都映射到一个环境变量。价值观来自 config.json 仅当相应的env变量为 尚未设置，所以 .env 真正的环境变量总是赢。

目录搜索顺序

ShowRun搜索 .showrun/config.json 在多个位置（从最低到最高优先级）：

1. 全局配置目录（特定于平台，见上表）
2. $HOME/.showrun/ （仅限Linux/macOS）
3. 从cwd中走出来的祖先目录（例如。 ../../.showrun/)
4. /.showrun/

当发现多个配置文件时，它们会被深度合并，优先级更高的值获胜。

系统提示

探索代理的系统提示在可用时从Techniques DB动态组装。当数据库不可用时，会使用内置的回退提示。您可以通过以下方式覆盖提示 TEACH_CHAT_SYSTEM_PROMPT env-var（内联文本）或 EXPLORATION_AGENT_PROMPT_PATH env-var（文件路径）。

MCP服务器

将任务包作为人工智能代理的MCP工具公开：

node packages/showrun/dist/cli.js serve --packs ./taskpacks          # stdio transport
node packages/showrun/dist/cli.js serve --packs ./taskpacks --http   # HTTP/SSE transport

看 packages/mcp-server/README.md 了解详情。

需求

• Node.js 20+
• pnpm（用于开发；npx适用于最终用户）

实验性 --该项目尚处于早期开发阶段。API、文件格式和CLI接口可能会更改，恕不另行通知。

贡献

目前还没有正式的贡献指南。也就是说，所有的贡献都是受欢迎的——随时可以公开问题、提交拉取请求或开始讨论。

许可证

麻省理工学院