webwright-to-intuned

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Webwright → Intuned

Port a Webwright Crafted CLI into a deployed Intuned project and verify it end to end. The contract is a faithful 1:1 port: one craft function → one Intuned

automation

API, re-fitted only at Intuned's boundary.

将Webwright Crafted CLI 移植为 已部署的Intuned项目 并进行端到端验证。本次移植遵循1:1忠实映射原则：一个craft函数对应一个Intuned

automation

API，仅在Intuned的边界处进行适配。

Prerequisites

前置条件

The Intuned CLI is installed and authenticated. If the
```
intuned
```
command isn't found, install it first:
```
npm i -g @intuned/cli
```
. Then confirm auth with
```
intuned auth whoami
```
(it should show a workspace). The skill never logs the user in or creates accounts — if
```
whoami
```
fails, stop and ask the user to authenticate.
Input is a Webwright craft output directory (contains
```
final_script.py
```
with an
```
argparse
```
wrapper,
```
plan.md
```
,
```
task.json
```
). If it isn't, stop and say so.

已安装并认证Intuned CLI。若无法找到
```
intuned
```
命令，请先执行安装：
```
npm i -g @intuned/cli
```
。随后通过
```
intuned auth whoami
```
确认认证状态（应显示一个工作区）。本流程不会为用户登录或创建账户——若
```
whoami
```
命令执行失败，请停止操作并要求用户完成认证。
输入必须为Webwright craft输出目录（包含带有
```
argparse
```
封装的
```
final_script.py
```
、
```
plan.md
```
、
```
task.json
```
文件）。若不符合要求，请停止操作并告知用户。

Read first

必读文档

Supporting docs live in

resources/

beside this file.

```
resources/transformation-rules.md
```
— the step-by-step transform and gates.
```
resources/intuned-contract.md
```
— the exact target (API signature, SDK, CLI, manifest), all verified against real scaffolds.
```
resources/gotchas.md
```
— the hardening layer. Re-read before every port and add to it after every failure.
```
resources/CONTEXT.md
```
— canonical vocabulary.
```
resources/DECISIONS.md
```
— why the key decisions hold.

支持文档位于本文件旁的

resources/

目录中：

```
resources/transformation-rules.md
```
—— 分步转换规则与验证关卡。
```
resources/intuned-contract.md
```
—— 明确的目标要求（API签名、SDK、CLI、清单），所有内容均已通过真实脚手架验证。
```
resources/gotchas.md
```
—— 加固层说明。每次移植前请重新阅读，并在每次失败后补充内容。
```
resources/CONTEXT.md
```
—— 标准术语表。
```
resources/DECISIONS.md
```
—— 关键决策的依据。

Workflow (one port)

工作流（单次移植）

Validate the input is a real craft; else fail loudly.

Scaffold

intuned dev init <task_id> --template <python-starter | python-starter-auth> --language python --install-deps --non-interactive [--stealth]

into

intuned_projects/<task_id>/

Transform per
```
resources/transformation-rules.md
```
:
- strip the browser bootstrap +
```
asyncio.run
```
  wrapper; the inner async body becomes
```
async def automation(page, params=None, **_kwargs)
```
  ;
- map surviving params (snake_case preserved, harness params dropped+logged) into
```
Params
```
  , a pydantic schema if needed, and
```
.parameters/.../default.json
```
  so empty params reproduce the task;
- replace
```
page.goto
```
  →
```
go_to_url
```
  ; drop screenshots/file-writes;
```
log()
```
  →
```
print()
```
  ; return substantive data minus harness fields;
- set
```
apiAccess.enabled: true
```
  and the Playground default input in
```
Intuned.jsonc
```
  .
Local gate:
```
intuned dev run api <name> '{}'
```
; compare output to the craft's
```
final_runs/
```
known-good shape/count. If the run is blocked by anti-bot defenses, don't keep fighting it locally — stealth/captcha/proxy only apply on the deployed platform (see step 6 and the bot-detection note below).
Deploy: after the local gate passes, ask the user whether to deploy to Intuned (surface the target workspace when you ask). Only on a yes, run
```
intuned dev deploy --non-interactive
```
; otherwise stop here.

Platform run (final gate):

intuned platform runs start '{"api":"<name>","parameters":{}}' -p <task_id>

; poll

intuned platform runs get <id>

until terminal.

On any failure, root-cause into a
```
resources/gotchas.md
```
entry, fix, re-run.

验证输入是否为有效的craft项目；若无效，立即终止并提示。

搭建脚手架：执行

intuned dev init <task_id> --template <python-starter | python-starter-auth> --language python --install-deps --non-interactive [--stealth]

命令，将项目生成到

intuned_projects/<task_id>/

目录下。

转换：按照
```
resources/transformation-rules.md
```
执行：
- 移除浏览器初始化代码和
```
asyncio.run
```
  封装；内部异步代码主体将变为
```
async def automation(page, params=None, **_kwargs)
```
  ；
- 将保留的参数（保留蛇形命名snake_case，移除并记录工具相关参数）映射到
```
Params
```
  （必要时使用pydantic schema），并写入
```
.parameters/.../default.json
```
  ，确保空参数时可复现任务；
- 将
```
page.goto
```
  替换为
```
go_to_url
```
  ；移除截图/文件写入操作；将
```
log()
```
  替换为
```
print()
```
  ；返回实质性数据，移除工具相关字段；
- 在
```
Intuned.jsonc
```
  中设置
```
apiAccess.enabled: true
```
  ，并配置Playground的默认输入。
本地验证关卡：执行
```
intuned dev run api <name> '{}'
```
；将输出与craft项目
```
final_runs/
```
目录下的已知正确输出的格式/数量进行对比。若运行被反机器人防御机制阻止，无需在本地继续尝试——隐身模式/验证码解决/代理仅在部署后的平台生效（参见步骤6及下方反机器人检测说明）。
部署：本地验证通过后，询问用户是否要部署到Intuned（询问时需显示目标工作区）。仅在用户同意时，执行
```
intuned dev deploy --non-interactive
```
；否则在此处停止操作。

平台运行（最终验证关卡）：执行

intuned platform runs start '{"api":"<name>","parameters":{}}' -p <task_id>

；轮询

intuned platform runs get <id>

命令，直到运行结束。

若出现任何失败，将根本原因记录到
```
resources/gotchas.md
```
中，修复后重新运行。

Exceptions to faithful-port (decide deliberately)

忠实移植的例外情况（需谨慎决策）

Auth craft → AuthSessions (resources/DECISIONS.md §2): decompose login into
```
auth-sessions/create.py
```
+ a derived
```
check.py
```
, enable
```
authSessions
```
; the
```
automation
```
assumes a valid session. Test with
```
dev run authsession create
```
then
```
--auth-session
```
.
Bot-detection block (resources/DECISIONS.md §3): if a run is blocked by anti-bot defenses, don't conclude the port is broken — stealth, captcha solving, and proxies run only on the deployed platform. Set
```
headful
```
+
```
stealthMode
```
in the manifest and verify with a deployed run; add
```
captchaSolver
```
/
```
proxy
```
if the deployed run is still walled. Configure per the Intuned docs: https://intunedhq.com/docs/main/02-features/stealth-mode-captcha-solving-proxies
No crawl fan-out by default — a crawl returns a flat list from one API;
```
extend_payload
```
is opt-in only.

认证类craft → AuthSessions（参考
```
resources/DECISIONS.md
```
第2节）：将登录流程拆分为
```
auth-sessions/create.py
```
+ 衍生的
```
check.py
```
，启用
```
authSessions
```
；
```
automation
```
函数将假定存在有效的会话。测试时先执行
```
dev run authsession create
```
，再使用
```
--auth-session
```
参数。
反机器人检测拦截（参考
```
resources/DECISIONS.md
```
第3节）：若运行被反机器人防御机制阻止，不要判定移植失败——隐身模式、验证码解决和代理仅在部署后的平台生效。在清单中设置
```
headful
```
+
```
stealthMode
```
，并通过部署后的运行进行验证；若部署后的运行仍被拦截，添加
```
captchaSolver
```
/
```
proxy
```
配置。请按照Intuned文档进行配置：https://intunedhq.com/docs/main/02-features/stealth-mode-captcha-solving-proxies
默认不支持爬虫扩展——单次爬虫调用仅返回一个API的扁平列表；仅可选择启用
```
extend_payload
```
。

Guardrails

防护规则

Never launch a browser in
```
automation
```
(page is injected).
Never invent Intuned APIs the craft didn't imply; this is a port, not a rewrite.
Deploy goes to the user's own workspace — surface which workspace before first deploy.
Don't try to beat bot-detection locally; that's what the deployed run is for.

切勿在
```
automation
```
函数中启动浏览器（页面将被注入）。
切勿创建craft未隐含的Intuned API；这是移植，而非重写。
部署将进入用户自己的工作区——首次部署前需明确告知用户目标工作区。
不要尝试在本地突破反机器人检测；部署后的运行才用于此目的。