tsplay-flow-authoring

name

tsplay-flow-authoring

description

Shareable TSPlay Flow authoring skill for coders. Use when Codex needs to write, modify, fix, review, or explain TSPlay `.flow.yaml` files, choose between Flow DSL, Lua script mode, and MCP workflows, draft or review tutorial flows, send email notifications with `send_email`, attach to real Chrome/Chromium over CDP, use `browser.cdp_launch`, or debug artifacts and saved sessions. Typical English triggers include write flow, fix flow, review flow, generate flow, repair selector, attach Chrome over CDP, use cdp_launch, send email flow, email notification flow, and convert a requirement into Flow. Typical Chinese triggers include 编写 Flow, 写 Flow, 改 Flow, 修 Flow, 生成 flow, 补一条 flow, 调试 flow, 排查 flow, 设计教程 flow, 接管 Chrome, cdp_launch, 发邮件 flow, 邮件通知 flow, and 把需求转成 TSPlay Flow.

TSPlay

Overview

Use this skill when the task is about the TSPlay codebase or, most importantly, when a coder needs help producing a solid TSPlay Flow. Prefer Flow as the default delivery asset, use Lua for quick local exploration, and use MCP when the task is agent-facing or needs observation, drafting, validation, execution, browser-state/CDP control, or repair loops.

Quick Start

• 如果用户主要用中文提需求，先读 references/zh-cn.md。
• 如果用户已经在中文排错，继续读 references/zh-cn-troubleshooting.md。
• 如果用户想直接套中文业务模板，继续读 references/zh-cn-business-templates.md。
• 如果用户主要卡在 selector，继续读 references/zh-cn-selectors.md。
• 如果用户是在做中文 review，继续读 references/zh-cn-review-checklist.md。
• Read references/flow-authoring.md first for the self-contained Flow writing and repair guide.
• Read references/actions.md when you need to choose the right TSPlay action, remember YAML shape, or write flows that use browser.cdp_launch, browser.cdp_endpoint, browser.cdp_port, execute_script, file output, or MCP security flags.
• Read references/examples.md when the user request is still vague and you need a strong prompt shape for authoring or repairing a Flow.
• Read references/example-index.md when you want the fastest repo-backed starting point by category such as form, table, import, session, recovery, or MCP.
• Read references/repo-map.md when you are inside the TSPlay repository and need exact paths or commands.
• If the local repo is available and the task is about product behavior, CLI flags, or repository entry points, read ReadMe.md.
• If the local repo is available and the task is about agent-driven Flow generation or repair, read docs/training/ai-intent-to-flow.md.
• If the local repo is available and the task is about a specific tutorial, inspect both script/tutorials/<lesson>.flow.yaml or script/tutorials/<lesson>.lua and the matching docs/tutorials/<lesson>.md.

Decision Rules

• Default to Flow when the result should be reviewed, versioned, reused, or repaired later.
• Use Lua CLI or standalone Lua scripts only for one-off debugging, quick page exploration, or primitive-level experiments.
• Use MCP when another agent or product needs tool calling, page observation, security boundaries, or a finalize -> run -> repair loop.
• Use CDP mode only for trusted local browser sessions: browser.cdp_launch when TSPlay should find and start Chrome/Chromium/Edge with an isolated profile, or browser.cdp_port / browser.cdp_endpoint when an external browser was already started with --remote-debugging-port.
• Prefer tsplay.finalize_flow as the default agent path. Split the workflow into observe_page, draft_flow, validate_flow, run_flow, repair_flow_context, and repair_flow only when the status, warnings, or unresolved items require tighter control.

Runtime Assumptions

• Do not hardcode one absolute binary path into the skill.
• Prefer a release tsplay binary from the current PATH, or a downloaded local release binary such as ./tsplay / .\tsplay.exe.
• For new users, point them to https://github.com/tensafe/tsplay/releases/latest to download the matching OS/architecture binary package and the tsplay-flow-authoring skill zip.
• Do not use go run . in user-facing skill guidance unless the user explicitly says they are developing inside the TSPlay source repository.
• If neither PATH nor a downloaded binary exists, guide the user to the latest release before assuming a custom path.

Flow Authoring Priorities

• Start from the user goal, page URL, required inputs, desired output file or variables, and the minimum security boundary.
• Prefer stable and readable Flow structure over clever Lua detours.
• Use clear name, optional description, and meaningful save_as names so the Flow is reviewable.
• Reach for common Flow-native actions first: navigate, wait_for_selector, type_text, click, assert_visible, assert_text, extract_text, set_var, foreach, on_error, read_json, write_json, write_csv, zip_compress, zip_extract, and send_email.
• For Chinese requests, normalize the task into five fields first: 页面, 目标, 输入, 输出, 授权.
• Keep artifact paths stable and task-scoped, especially for tutorial or handoff work.
• Reuse existing tutorial patterns before inventing a brand-new structure from scratch.
• For real-browser or anti-bot-sensitive work, prefer browser.cdp_launch: true as the beginner path. It avoids interrupting the user's daily Chrome window while still using the local browser binary.
• For MCP CDP work, always include allow_browser_state=true; add allow_file_access=true for screenshots/JSON/CSV/Excel outputs and allow_javascript=true for execute_script or evaluate.
• Do not combine CDP mode with browser.use_session, storage_state/load_storage_state, persistent profile/session, user_agent, or browser video recording.

Operating Workflow

1. Clarify the page or system target, the user intent, required inputs, and the minimum authorization boundary.
2. Pick the smallest viable entry point: tsplay -flow ... when the binary is already on PATH, ./tsplay -flow ... or .\tsplay.exe -flow ... when using a downloaded release binary, file-srv for local demo pages, mcp-stdio for local agent integration, or srv for HTTP MCP.
3. Check validation results, warnings, unresolved selectors, and repair hints before treating a draft as complete.
4. If execution fails, inspect artifacts under artifacts/ and prefer validation or repair tools over blindly rewriting selectors.
5. If login state matters, prefer saved sessions and put browser.use_session in top-level browser config instead of scattering login steps.
6. If the user asks to attach to a real browser, first check whether they already have a remote debugging port. If not, use browser.cdp_launch or show a separate-profile Chrome launch command for macOS, Windows, or Linux.