Helixwright 1.0

精确运行合同

启动时严格校验协议、端点、内核合同、方法集合、逐方法 schema、能力版本和语义 hash。 任一不一致都会 fail closed，不会降级到另一套 wire 行为。

快速开始

import helixwright as hw

with hw.launch("https://example.com", name="example") as page:
    page.locator("body").wait(timeout_ms=10_000)
    print(page.url, page.title())

    effect = page.get_by_role(
        "link", name="More information..."
    ).click()

    assert effect.ok
    assert effect.dispatch_phase == "completed"
    assert effect.receipt_confirmed

未传 reuse_profile_id 时，Desktop 创建新的服务端 profile；名称可不传。 指纹选择与 geo-follow 由服务端负责，通常调用者只需按需提供代理。

职责边界

定位与原子动作

email = page.get_by_label("Email")
if email.input_value() != "buyer@example.test":
    email.fill("buyer@example.test")

effect = page.get_by_role("button", name="Continue").click()

fill() 替换值；type() 聚焦后追加真实按键输入。 普通 click() 已包含目标所属滚动、稳定性、遮挡、命中、最终 pointer-down 复核和可信轨迹，不应额外先滚动或猜坐标。

慢加载与业务就绪

ready = hw.ReadinessContract(
    all_of=(
        hw.ReadinessSignal.attribute(
            "#submit", "data-hydrated", equals="true"
        ),
    ),
    stable_frames=3,
    quiet_ms=100,
)

effect = page.locator("#submit").click(
    ready=ready,
    timeout_ms=20_000,
)

“元素可见”不等于组件已就绪。业务条件与动作一起发送，在同一 document epoch 内评估， 并在派发前再次检查身份、几何与 hit-test。机械可操作性不能关闭。

不可变 Frame 与 Shadow DOM

payment = page.frame("iframe#payment")
payment.get_by_label("Card number").fill("4111111111111111")
effect = payment.get_by_role("button", name="Pay").click()

每个 Frame/Locator/Input/Probe 都携带自己的冻结 frame chain，不修改全局 frame cursor。 Shadow DOM 与 OOPIF 目标由内核在同一动作事务中解析；目标重渲染后必须重新绑定身份。

轨迹与低层手势

with hw.launch(
    "https://example.com",
    motion=hw.MotionProfile.careful(seed=20260714),
) as page:
    gesture = page.input.gesture(timeout_ms=15_000)
    gesture.move(120, 240).down().pause(80)
    gesture.move(520, 240, duration_ms=1200).up()
    effect = gesture.commit()

普通元素轨迹在最终 frame/target 绑定后由内核生成。高级调用者可一次性提交完整、平衡的 Gesture。回执包含 input sequence、motion/path digest、样本、持续时间、最大步长、 pointer continuity 和 scroll chain；画面光点不能替代这些证明。

事件驱动状态机

def submit(ctx):
    return ctx.scope.locator("#submit").click(ready=ctx.ready)

machine = hw.StateMachine([
    hw.State(
        "form",
        match=hw.Signature(
            require_selectors=["#form", "#submit"],
            absent_selectors=["#complete"],
        ),
        ready=ready,
        handler=submit,
        expect=hw.OutcomeContract(
            success_states=["done"],
            progress=[hw.signals.DomChanged()],
            no_effect="report",
        ),
    ),
    hw.State(
        "done",
        match=hw.Signature(require_selectors=["#complete"]),
        terminal=True,
    ),
])

result = machine.run(page, until="done")

每次 transition 都执行“单 epoch 分类 → 独立事件订阅 → 一个权威动作 → 因果 Outcome → 再分类”。未知、歧义、混合 epoch、外来回执、事件缺口、派发不确定、超时或震荡都会停止。

私有 Trace/Authoring

$run = "evidence\authoring-run"
python -m helixwright author start --url "https://target.example" --run-dir $run
python -m helixwright author exec --run-dir $run --code "page.probe.forms()"
python -m helixwright author checkpoint --run-dir $run --label "form"
python -m helixwright author stop --run-dir $run

一个 controller 持续复用同一 browser/profile/session/page，Trace 在目标导航前启动。 截图只是补充证据，结构化状态、就绪、事件、动作 effect 和 receipt 才是主证据。

API 分层

AI 文档与校验

AI 应先读取 manifest，校验文档字节数和 SHA-256，再读取 always_read 文档和任务相关文档。

• AI manifest
• llms.txt
• 强制规则
• 完整 API
• 定位与可信输入
• 状态机
• Trace/Authoring
• 生产示例

合同与文档 hashes 由同一个 manifest 生成器校验。