TSPlay

A browser automation execution engine for AI agents and delivery teams. Use one toolkit across observe -> draft -> validate -> run -> repair, session reuse, and explicit security controls.

TSPlay is built with Go + Playwright and exposes three entry points: Lua CLI / Script, Flow DSL, and MCP Server.

It is designed for work that needs to survive handoff, review, AI generation, and ongoing delivery. Instead of treating browser automation as a pile of one-off scripts, TSPlay keeps the runtime, examples, docs, sessions, repair artifacts, and security boundaries close to each other.

TSPlay is not just a thin wrapper around browser actions. It organizes the capabilities that usually become fragmented in real delivery work:

page observation and interactive element extraction
structured Flow drafting, validation, and execution
failure traces, screenshots, HTML, and DOM snapshots
login state and browser session reuse
agent-facing MCP tools with explicit permission boundaries

If you want browser automation that can be maintained over time, generated by AI, reviewed by a team, and delivered reliably, TSPlay is built much closer to that goal.

Start Here

If you want to...	Start with	Then continue to
get the environment working first	5-Minute Quick Start	docs/tutorials/01-hello-world.md
write or fix a Flow	script/demo_baidu.flow.yaml	docs/tutorials/README.md
connect Codex or another agent	docs/training/ai-intent-to-flow.md	`go run . -action srv`
learn through step-by-step examples	docs/tutorials/README.md	docs/tutorials/01-hello-world.md
plan onboarding or training	docs/training/README.md	docs/training/bootcamp-plan.md

5-Minute Quick Start

If this is your first time touching TSPlay, do not choose between Lua / Flow / MCP / binary yet. Use the default path below and aim for one successful run first.

Default First-Run Path

Prepare:

Go 1.23.6+
a machine that can launch Chromium

On the first browser-related run, TSPlay uses a playwright/ folder next to the binary when one is present; otherwise it calls playwright.Install() automatically to download Chromium.

Then run these commands from the repository root:

go mod download
go run . -flow script/tutorials/01_hello_world.flow.yaml

If you want to practice against the local demo pages, open one more terminal:

go run . -action file-srv -addr :8000

You are done when:

go run . -flow ... completes successfully
artifacts/ contains run outputs
if you started file-srv, http://127.0.0.1:8000/demo/demo.html opens

Other Entry Points

After the default path works, pick the route that matches your goal.

Continue From Source

go run . -flow script/demo_baidu.flow.yaml

From A Built Binary

go build -o tsplay .
./tsplay -flow script/tutorials/01_hello_world.flow.yaml
./tsplay -action list-assets

Start With MCP / Agent

go run . -action srv
go run . -action mcp-tool -tool tsplay.list_actions

Good next commands after that:

go run . -action cli
go run . -action srv
go run . -action mcp-tool -tool tsplay.list_actions
docs/README.md for the full docs map

Recommended Starting Paths

1. I Mainly Want To Write Flows

Start with a runnable Flow, then move into the tutorial set and Flow-oriented training materials:

2. I Mainly Want To Connect An AI Agent

Start with the intent-to-flow path, then use MCP tools to observe, draft, validate, run, and repair:

docs/training/ai-intent-to-flow.md
go run . -action srv
go run . -action mcp-tool -tool tsplay.list_actions

3. I Mainly Want To Enable A Team

Start with the training overview, then go deeper into learning paths, labs, bootcamps, and trainer materials:

Use Cases

Web RPA: login, search, click, upload, download, export
page data extraction: text, attributes, links, tables, HTML, cookies, storage state
business workflow automation: variables, control flow, assertions, recovery, resumable runs
agent browser tooling: let Codex, OpenClaw, and similar models observe a page before drafting, running, and repairing flows
browser plus external systems: HTTP APIs, Redis, CSV/Excel, databases

Why TSPlay Is Not "Just Another Playwright Wrapper"

Flow is versionable, reviewable, reusable, and much easier for AI to generate strictly
failures automatically preserve trace data, screenshots, HTML, and DOM snapshots for debugging and repair
sessions can be named, saved, and reused for long-term delivery instead of one-off scripts
MCP mode comes with security boundaries, which is much safer for agent-facing automation than exposing a raw browser directly

Three Ways to Use TSPlay

Mode	Best for	Entry
`Lua CLI / Script`	quick debugging, page exploration, one-off tasks	`go run . -action cli` / `go run . -script ...`
`Flow DSL`	versioned, reviewable, reusable business workflows that AI can generate	`go run . -flow ...`
`MCP Server`	exposing observe, draft, execute, repair, and session capabilities to agents	`go run . -action srv`

For day-to-day delivery work, Flow should usually be your main path.
Use CLI to explore a page first, and MCP when you want to connect TSPlay to an AI product or agent workflow.

Capability Matrix

The goal of this matrix is not to force every capability into mechanical 1:1 parity. The point is to separate what should stay aligned across layers and what belongs naturally at the Flow level.

Capability Area	Typical Actions	Flow	Lua	MCP	Recommendation
page primitives	`navigate`, `click`, `type_text`, `select_option`	Yes	Yes	Yes	Keep aligned
file and spreadsheet I/O	`screenshot`, `save_html`, `read_json`, `read_csv`, `read_excel`, `write_json`, `write_csv`, `write_excel`, `zip_compress`, `zip_extract`	Yes	Yes	Yes	Keep aligned; constrained by `allow_file_access` in MCP
HTTP requests	`http_request`, `ocr_ready`, `ocr_request`, `json_extract`	Yes	Yes	Yes	Keep aligned; Lua inside Flow / MCP also obeys `allow_http`, `allow_file_access`, and file-root constraints
email delivery	`send_email`	Yes	Yes	Yes	Keep aligned; Lua inside Flow / MCP also obeys `allow_email`
Redis operations	`redis_get`, `redis_set`, `redis_del`, `redis_incr`	Yes	Yes	Yes	Keep aligned; Lua inside Flow / MCP also obeys `allow_redis`
database operations	`db_insert`, `db_insert_many`, `db_upsert`, `db_query`, `db_query_one`, `db_execute`, `db_transaction`	Yes	Yes	Yes	Keep aligned; Lua inside Flow / MCP also obeys `allow_database`, and `db_transaction` auto-commits or rolls back
browser state	`get_storage_state`, `get_cookies_string`, `browser.use_session`, `browser.cdp_*`	Yes	Yes	Yes	Keep aligned; constrained by `allow_browser_state` in MCP
Flow convenience actions	`extract_text`, `assert_visible`, `assert_text`, `set_var`, `append_var`	Yes	Yes	Yes	Already aligned; better treated as orchestration sugar than low-level primitives
Flow control flow	`retry`, `if`, `foreach`, `on_error`, `wait_until`	Yes	No	Yes	No need to force parity into Lua
Lua callback-style capability	`intercept_request`	No	Yes	No	Best kept Lua-only

Recommended rule of thumb:

Atomic data actions such as HTTP / Redis / database / file I/O should ideally work in both Flow and Lua, so exploration, productionization, and integration do not drift apart.
Orchestration capabilities such as retry / foreach / on_error / wait_until belong more naturally in Flow DSL and do not need to be translated into Lua extension functions.
Semantic actions such as extract_text / assert_text / assert_visible can start as higher-level Flow actions; if Lua users keep rebuilding the same patterns, then a Lua sugar layer is worth adding.

If you want the capability-action layer explained systematically, start with docs/capability-actions/README.md.
If you want the command-line -action entry points instead, see docs/actions/README.md.

Quick Start

If you only want the shortest setup path, use the 5-Minute Quick Start above first. This section keeps the full command map and detailed notes.

Requirements

Go 1.23.6+
an environment that can run Playwright Chromium
on the first browser-related run, TSPlay will use an adjacent playwright/ folder when one is present, or call playwright.Install() automatically to download Chromium

Install Dependencies

go mod download

Pick One Way to Start

What you want to do	Command
start the interactive CLI	`go run . -action cli`
run a Lua script	`go run . -script script/open_url.lua`
run a Flow	`go run . -flow script/demo_baidu.flow.yaml`
start the built-in static file server	`go run . -action file-srv -addr :8000`
call one TSPlay MCP tool directly	`go run . -action mcp-tool -tool tsplay.list_actions`
list macOS screen recording devices	`go run . -action list-record-devices`
record the entire desktop	`go run . -action record-screen -record-cmd "go run . -flow script/tutorials/10_assert_page_state.flow.yaml"`
record only browser-page video	`go run . -flow script/tutorials/10_assert_page_state.flow.yaml -browser-video-output artifacts/recordings/lesson-10-assert-page-state.webm`
list bundled assets inside the binary	`go run . -action list-assets`
extract bundled docs/script/demo assets	`go run . -action extract-assets -extract-root ./tsplay-assets`
start the MCP server	`go run . -action srv`

If you want one place that explains every supported command-line -action, start with docs/actions/README.md.

Add -headless if you want to hide the browser window. To attach to Chrome/Chromium that was already started with --remote-debugging-port=9222, add -browser-cdp-port 9222 to -flow, -script, or -action cli; use -browser-cdp-endpoint when you already have the full CDP endpoint. -browser-cdp-endpoint accepts ws://127.0.0.1:9222/devtools/browser/..., http://127.0.0.1:9222, and pasted local forms like 127.0.0.1:9222/json/version, 127.0.0.1:9222/json/list, 127.0.0.1:9222/json/new, 127.0.0.1:9222/json/protocol, or 127.0.0.1:9222/devtools/browser/.... If you want TSPlay to make this easy, use -browser-cdp-launch: TSPlay will search common Chrome/Chromium/Edge locations on macOS, Windows, and Linux, launch a separate profile with remote debugging enabled, then attach over CDP. Use -browser-cdp-executable or -browser-cdp-user-data-dir only when you need to override the detected browser or profile directory.

Use A Real Chrome Through CDP

CDP mode is for trusted local automation where you need a real browser environment: a profile that is already logged in, installed extensions, cached site state, or a page that needs manual intervention during a run.

If your current daily Chrome was not started with a remote debugging port, TSPlay cannot safely attach to that exact process. Start a separate Chrome profile instead:

# macOS
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --remote-debugging-port=9222 \
  --user-data-dir="$PWD/artifacts/chrome-cdp-profile"

# Linux
google-chrome \
  --remote-debugging-port=9222 \
  --user-data-dir="$PWD/artifacts/chrome-cdp-profile"

# Windows PowerShell
& "$env:ProgramFiles\Google\Chrome\Application\chrome.exe" `
  --remote-debugging-port=9222 `
  --user-data-dir="$pwd\artifacts\chrome-cdp-profile"

Then attach TSPlay:

go run . -flow script/demo_baidu.flow.yaml -browser-cdp-port 9222

For the easiest first run, let TSPlay find Chrome and launch an isolated profile for you:

go run . -flow script/demo_baidu.flow.yaml -browser-cdp-launch

Important behavior:

external CDP attach disconnects Playwright at the end and leaves the real browser running
cdp_launch starts a browser owned by TSPlay and cleans it up when the run finishes
cdp_user_data_dir is only for cdp_launch; it defaults under the artifact root
MCP requests that use browser_cdp_* or Flow browser.cdp_* require allow_browser_state=true
CDP mode cannot be combined with use_session, storage_state/load_storage_state, persistent profile/session, user_agent, or -browser-video-output

record-screen captures the entire macOS desktop, which is useful for desktop demos.
-browser-video-output records the Playwright page itself, which is better for browser tutorials.
TSPlay also keeps the page open slightly longer by default so short recordings remain watchable.
For the full instructor workflow, see docs/training/tutorial-video-recording.md.

When you build ./tsplay, ReadMe.md, docs/, script/, and demo/ are bundled into the binary:

run a bundled example directly: ./tsplay -script script/tutorials/01_hello_world.lua
run a bundled Flow directly: ./tsplay -flow script/tutorials/01_hello_world.flow.yaml
serve the bundled demo pages directly: ./tsplay -action file-srv -addr :8000
extract the reference assets to a local directory: ./tsplay -action extract-assets -extract-root ./tsplay-assets

Run a Flow First

The repository already includes a minimal example:

go run . -flow script/demo_baidu.flow.yaml

The Flow looks roughly like this:

schema_version: "1"
name: baidu_search
vars:
  query: 山东大学
steps:
  - action: navigate
    url: https://www.baidu.com

  - action: wait_for_selector
    selector: "#kw"
    timeout: 5000

  - action: type_text
    selector: "#kw"
    text: "{{query}}"

  - action: click
    selector: "#su"

  - action: wait_for_network_idle

  - action: get_all_links
    selector: "xpath=//body"
    save_as: links

The run returns structured JSON with variables, step traces, durations, and failure artifact paths when something goes wrong.

Explore with the CLI

Start the CLI:

go run . -action cli

Then enter:

start

After that you can execute Lua-style commands directly:

navigate("https://www.baidu.com")
wait_for_network_idle()
type_text("#kw", "山东大学")
click("#su")

Start the MCP Server

go run . -action srv
go run . -action srv -addr :8081
go run . -action srv -flow-root script -artifact-root artifacts
go run . -action mcp-stdio -flow-root script -artifact-root artifacts
go run . -action mcp-tool -tool tsplay.list_actions
go run . -action mcp-tool -tool tsplay.observe_page -args-file script/tutorials/113_mcp_observe_page_template_release.args.json

Default constraints:

flow_path can only read files under script/ unless you change it with -flow-root
file input and output are limited to the artifact root by default
run_flow defaults to headless=true

If you want to start from the path where a user describes intent and the model helps draft and run a Flow, begin with docs/training/ai-intent-to-flow.md.

Why Flow Should Be the Main Path

Compared with raw Lua, Flow works better as a long-lived business asset:

easier for AI to generate strictly
easier for humans to review and diff
easier to validate with a schema and return structured issues
easier to preserve failure context and repair hints
easier to expose through MCP to agents

Common Flow capabilities include:

variables: vars, save_as, set_var, append_var
control flow: retry, if, foreach, on_error, wait_until
page actions: click, type, wait, assert, screenshot, upload, download
data actions: http_request, json_extract, send_email, read_json, read_csv, read_excel, write_json, write_csv, write_excel, zip_compress, zip_extract
browser state: use_session, storage_state, save_storage_state, cdp_launch, cdp_endpoint, cdp_port

Core Capabilities

Chromium automation driven by Playwright
direct browser control through Lua
structured Flow in YAML / JSON
page observation, Flow drafting, validation, execution, and failure repair
named browser session save, reuse, and export
data actions such as redis_get/set/del/incr and db_insert/db_query/db_transaction
automatic failure artifacts including screenshots, HTML, and DOM snapshots
explicit security boundaries and capability grants through MCP

Execution Output and Failure Artifacts

Every Flow run returns a step trace that usually includes:

action
parameter summary
status
duration_ms
output summary
current page_url

When a step fails, TSPlay writes the scene into the artifact root, which defaults to artifacts/.
Common files include:

failure.png
page.html
dom_snapshot.json

You can change the output directory with:

go run . -flow script/demo_baidu.flow.yaml -artifact-root artifacts

MCP / Agent Integration

TSPlay can run as an MCP server so an agent does not need to read a full HTML page or hand-author selectors directly.

If you want a shorter default path for the model, prefer tsplay.finalize_flow.
If you need finer-grained control, use the full chain: observe_page -> draft_flow -> validate_flow -> run_flow -> repair_flow_context -> repair_flow.

Common tsplay.finalize_flow statuses:

ready: the Flow can run immediately
needs_input: more variables or user input are required
needs_permission: a security boundary was hit and additional permission is required
needs_repair: the Flow is close, but should be fixed before running

MCP Tool Groups

Group	Tools
Flow discovery	`tsplay.list_actions`, `tsplay.flow_schema`, `tsplay.flow_examples`
page observation and drafting	`tsplay.observe_page`, `tsplay.draft_flow`, `tsplay.finalize_flow`
validation, execution, and repair	`tsplay.validate_flow`, `tsplay.run_flow`, `tsplay.repair_flow_context`, `tsplay.repair_flow`
session management	`tsplay.save_session`, `tsplay.list_sessions`, `tsplay.get_session`, `tsplay.export_session_flow_snippet`, `tsplay.delete_session`

Recommended Call Order

If you want a shorter default path for smaller models or productized integrations, start with:

tsplay.finalize_flow
if status=ready, run tsplay.run_flow
if status=needs_permission, grant permissions and call tsplay.finalize_flow again
if status=needs_input, provide the missing input and call tsplay.finalize_flow again
if status=needs_repair, move into tsplay.validate_flow / tsplay.repair_flow_context / tsplay.repair_flow

If you need finer control, use the full path:

tsplay.flow_schema
tsplay.flow_examples
tsplay.observe_page
tsplay.draft_flow
tsplay.validate_flow
tsplay.run_flow
tsplay.repair_flow_context / tsplay.repair_flow
tsplay.save_session

The golden-path tools try to return a unified envelope whose top-level fields usually include:

ok
tool
summary
artifacts
next_action
warnings
run

Flow Authoring Tips

use type_text, not fill
use save_as, not result_var
for file I/O, uploads, downloads, and screenshots in MCP mode, pass allow_file_access=true or use security_preset=browser_write
set page-level timeout in browser.timeout instead of adding an unsupported timeout directly to navigate
if you are unsure about an action name, check tsplay.list_actions and tsplay.flow_schema first

Browser Sessions and Top-Level Flow Config

If a business flow depends on login state, put browser config at the top of the Flow instead of scattering it across individual steps:

schema_version: "1"
name: admin_orders
browser:
  headless: true
  use_session: admin
  save_storage_state: states/admin-latest.json
  timeout: 30000
  viewport:
    width: 1440
    height: 900
steps:
  - action: navigate
    url: https://example.com/admin/orders

  - action: assert_visible
    selector: "#orders-table"
    timeout: 10000

Common browser fields:

headless
use_session
storage_state / storage_state_path / load_storage_state
save_storage_state
cdp_launch
cdp_endpoint
cdp_port
cdp_executable
cdp_user_data_dir
persistent
profile
session
timeout
user_agent
viewport.width / viewport.height

Notes:

use_session expands automatically from a named session saved with tsplay.save_session
save_storage_state saves the current login state after the Flow finishes
cdp_launch: true starts a local Chrome/Chromium/Edge with remote debugging enabled and then attaches over CDP; when cdp_executable is omitted, TSPlay searches common browser locations on macOS, Windows, and Linux
cdp_endpoint / cdp_port attaches to an existing Chromium/Chrome process started with --remote-debugging-port; for example cdp_port: 9222 or cdp_endpoint: "127.0.0.1:9222/json/version"
cdp_endpoint may be an HTTP base URL, a WebSocket browser endpoint, or a pasted DevTools helper URL such as /json/version, /json/list, /json/new, /json/protocol, or /devtools/browser/...
cdp_user_data_dir selects the independent profile directory for cdp_launch; when omitted, TSPlay creates one under the artifact root
profile / session enables a persistent browser context
persistent profile/session cannot be combined with storage_state or use_session
CDP attach reuses the external browser's default context and first page; TSPlay disconnects Playwright when done and does not close the real browser
CDP launch is cleaned up by TSPlay when it started the browser process
cdp_launch is the beginner-friendly path: it avoids interrupting the user's daily Chrome window while still using the locally installed Chrome/Chromium/Edge binary
cdp_launch / cdp_endpoint / cdp_port cannot be combined with use_session, storage_state/load_storage_state, persistent/profile/session, user_agent, or -browser-video-output

If you want business users to remember only a single session name, save one first:

{
  "name": "admin",
  "storage_state_path": "states/admin.json"
}

Then write this in later Flows:

browser:
  use_session: admin

Security Boundaries

MCP mode is not fully open by default. High-risk capabilities require explicit permission per request.

`security_preset`

readonly: default minimum permissions
browser_write: enables file I/O and browser-state capabilities, which is suitable for upload, download, screenshots, and storage-state reuse
full_automation: enables all MCP security capabilities

Explicit allow_* flags override the corresponding fields inside security_preset.

Common Permission Flags

Permission Flag	Allows
`allow_lua=true`	`lua`
`allow_javascript=true`	`execute_script`, `evaluate`
`allow_file_access=true`	`screenshot`, `save_html`, `read_csv`, `read_excel`, upload/download, `write_json`, `write_csv`, `write_excel`, `zip_compress`, `zip_extract`
`allow_browser_state=true`	cookies / storage state / `browser.use_session` / persistent profile / `browser.cdp_` and MCP `browser_cdp_`
`allow_http=true`	`http_request`, `ocr_ready`, `ocr_request`
`allow_email=true`	`send_email`
`allow_redis=true`	`redis_get`, `redis_set`, `redis_del`, `redis_incr`, `foreach.with.progress_key`
`allow_database=true`	`db_insert`, `db_insert_many`, `db_upsert`, `db_query`, `db_query_one`, `db_execute`, `db_transaction`

Additional notes:

even when file actions are allowed, reads and writes still stay within the artifact root
relative paths inside top-level browser config are also resolved under the artifact root
CDP attach and launch are treated as browser-state capabilities because they can expose real cookies, extensions, profile data, and logged-in sessions
http_request, redis_*, and db_* inside Lua inherit the corresponding allow_* constraints when running inside Flow / MCP security contexts
local CLI runs such as go run . -flow ... remain a more flexible local workflow

External System Integrations

TSPlay can place browser automation and data actions inside the same Flow.

HTTP

You can call external APIs directly with http_request and continue the orchestration with json_extract.
Typical examples:

OCR or captcha recognition
internal lookup or patch APIs
webhook or notification endpoints

Additional notes:

both Flow and Lua support http_request
when Lua http_request runs inside a Flow / MCP security context, it also obeys allow_http
if http_request uses save_path or multipart_files, Lua follows the same allow_file_access constraints as Flow
in restricted mode, relative paths in save_path and multipart_files resolve under the configured file root

Email

Useful when you want to send import results, failure summaries, or run-complete notifications directly to business or operations inboxes.

Environment variable conventions:

default connection: TSPLAY_EMAIL_*
named connection: TSPLAY_EMAIL_<NAME>_*

Common fields:

HOST, PORT
USERNAME, PASSWORD
FROM
TLS_MODE: none, starttls, tls
TIMEOUT_MS

Additional notes:

both Flow and Lua support send_email
send_email requires allow_email=true in restricted Flow / MCP contexts
send_email accepts with.to, with.cc, and with.bcc as either one email string or a list of email strings
send_email requires at least one of with.body or with.html
you can either use connection: qq with environment variables or put host, port, username, password, from, and tls_mode directly under with.smtp
send_email supports with.attachments as either a single file path/object or a list of file paths/objects shaped like {path, name?, content_type?}
attachments read local files, so restricted Flow / MCP contexts also require allow_file_access=true

Redis

Redis works well for shared cookies, cursors, deduplication keys, and resumable checkpoints.

Environment variable conventions:

default connection: TSPLAY_REDIS_*
named connection: TSPLAY_REDIS_<NAME>_*
URL form is also supported: TSPLAY_REDIS_URL, TSPLAY_REDIS_<NAME>_URL

CSV / Excel

Useful for batch import, chunked execution, and writing results back into a ledger.

read_csv treats the first non-empty row as the header by default
read_excel currently supports .xlsx
write_excel currently supports .xlsx
write_excel supports multi-sheet workbook values shaped like value = { sheets = [...] }
write_excel writes numbers and booleans as native Excel cell types
read_excel.range supports rectangular ranges such as A2:B20
you can combine with.start_row, with.limit, and with.row_number_field for resumable processing

ZIP Archives

Useful when a Flow needs to package generated reports, unpack a downloaded handoff, or move a folder as one artifact.

- action: zip_compress
  file_path: artifacts/reports/run.zip
  files:
    - artifacts/reports/summary.json
    - artifacts/reports/results.csv
  folders:
    - artifacts/reports/screenshots
  password: "{{zip_password}}"
  save_as: archive

- action: zip_extract
  file_path: "{{archive.file_path}}"
  save_path: artifacts/unpacked
  password: "{{zip_password}}"

Additional notes:

zip_compress accepts a single source_path, file, folder, files, folders, paths, or sources
with.base_dir controls the relative paths stored inside the archive
zip_extract rejects unsafe archive paths that would escape save_path
password support uses traditional ZipCrypto compatibility
restricted Flow / MCP contexts require allow_file_access=true

Database

Useful when you want to persist structured output directly into tables or query business data during a Flow.

Environment variable conventions:

default connection: TSPLAY_DB_*
named connection: TSPLAY_DB_<NAME>_*

Common supported drivers:

mysql
pgsql
sqlserver
oracle

Notes:

both Flow and Lua support db_insert, db_insert_many, db_upsert, db_query, db_query_one, db_execute, and db_transaction
when Lua db_* or Lua db_transaction runs inside a Flow / MCP security context, it also obeys allow_database=true
db_transaction executes inner database actions in one transaction scope, auto-commits on success, and auto-rolls back on failure
db_* actions require allow_database=true in MCP mode
SQL Server and Oracle require binaries built with the corresponding driver build tags

Documentation Map

This README covers project positioning and quick start. Training, enablement, and delivery-oriented materials live under docs/.

Content	Description	Entry
docs index	repository-wide documentation map and recommended reading order	docs/README.md
skills overview	explains what a Codex skill solves and what TSPlay currently provides	docs/skills/README.md
tutorial pyramid overview	explains why the curriculum is organized as four layers instead of a flat lesson list	docs/tutorials/curriculum-overview.zh-CN.md
training overview	a single entry for implementers, testers, developers, and trainers	docs/training/README.md
AI intent to Flow	hands-on guide for the agent path from user intent to MCP to Flow to execution and repair	docs/training/ai-intent-to-flow.md
learning path	roadmap from beginner to MCP integrator / trainer	docs/training/learning-path.md
bootcamp plan	2-day bootcamp and 4-week rollout rhythm	docs/training/bootcamp-plan.md
labs	hands-on exercises built on `demo/` and `script/`	docs/training/labs.md
assessment and certification	scoring dimensions, evidence standards, and graduation criteria	docs/training/assessment.md
trainer playbook	preparation, delivery, and retrospective guidance for instructors	docs/training/trainer-playbook.md

Project Structure

.
├── main.go
├── docs/             # docs index, training system, labs, and trainer materials
├── tsplay_core/      # core engine, Flow, MCP, observation, and repair
├── script/           # Lua and Flow examples
├── demo/             # local demo pages
├── tsplay_test/      # tests and demo resources
└── mcp_test/         # MCP-related experiment code

Development and Testing

go test ./...

If this is your first time with TSPlay, this reading order works well:

start with this page to understand the three layers and quick start
continue with docs/README.md to locate the rest of the materials
if you want the system view first, read docs/tutorials/curriculum-overview.zh-CN.md
if you want to learn Flow delivery, focus on docs/training/learning-path.md
if you want to integrate agents or MCP, focus on docs/training/ai-intent-to-flow.md

Name		Name	Last commit message	Last commit date
Latest commit History 142 Commits
.github/workflows		.github/workflows
.idea		.idea
aiscript		aiscript
demo		demo
docs		docs
installers		installers
mcp_test		mcp_test
script		script
site-src		site-src
skills		skills
theme-overrides		theme-overrides
tools		tools
tsplay_core		tsplay_core
tsplay_test		tsplay_test
.DS_Store		.DS_Store
.gitignore		.gitignore
LICENSE		LICENSE
README.zh-CN.md		README.zh-CN.md
ReadMe.md		ReadMe.md
embedded_assets.go		embedded_assets.go
embedded_assets_test.go		embedded_assets_test.go
getting-started.md		getting-started.md
go.mod		go.mod
go.sum		go.sum
main.go		main.go
main_test.go		main_test.go
mcp_tool_cli.go		mcp_tool_cli.go
mcp_tool_cli_test.go		mcp_tool_cli_test.go
mkdocs.yml		mkdocs.yml
process_group_unix.go		process_group_unix.go
process_group_windows.go		process_group_windows.go
quickstart_demo.go		quickstart_demo.go
quickstart_demo_test.go		quickstart_demo_test.go
requirements-docs.txt		requirements-docs.txt
screen_record.go		screen_record.go
screen_record_test.go		screen_record_test.go
static_server.go		static_server.go
static_server_test.go		static_server_test.go
tsplay.iml		tsplay.iml
tutorial_flows_test.go		tutorial_flows_test.go
workbench_app.go		workbench_app.go
workbench_app_test.go		workbench_app_test.go

Folders and files

Latest commit

History

Repository files navigation

TSPlay

Start Here

5-Minute Quick Start

Default First-Run Path

Other Entry Points

Continue From Source

From A Built Binary

Start With MCP / Agent

Recommended Starting Paths

1. I Mainly Want To Write Flows

2. I Mainly Want To Connect An AI Agent

3. I Mainly Want To Enable A Team

Use Cases

Why TSPlay Is Not "Just Another Playwright Wrapper"

Three Ways to Use TSPlay

Capability Matrix

Quick Start

Requirements

Install Dependencies

Pick One Way to Start

Use A Real Chrome Through CDP

Run a Flow First

Explore with the CLI

Start the MCP Server

Why Flow Should Be the Main Path

Core Capabilities

Execution Output and Failure Artifacts

MCP / Agent Integration

MCP Tool Groups

Recommended Call Order

Flow Authoring Tips

Browser Sessions and Top-Level Flow Config

Security Boundaries

security_preset

Common Permission Flags

External System Integrations

HTTP

Email

Redis

CSV / Excel

ZIP Archives

Database

Documentation Map

Project Structure

Development and Testing

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

`security_preset`

Packages