gz-laya-pilot 0.1.0

package/src/browser.ts

@@ -0,0 +1,20 @@
+// Adapted from anthonyli/laya-pilot lib/browser-provider.mjs (MIT).
+import { chromium, type LaunchOptions, type BrowserContextOptions } from 'playwright';
+export async function openBrowser(
+  options: { launch?: LaunchOptions; context?: BrowserContextOptions } = {},
+) {
+  const browser = await chromium.launch(options.launch);
+  try {
+    const context = await browser.newContext({
+      viewport: { width: 1500, height: 980 },
+      locale: 'zh-CN',
+      ...options.context,
+    });
+    const page = await context.newPage();
+    page.setDefaultTimeout(10000);
+    return { browser, context, page };
+  } catch (error) {
+    await browser.close();
+    throw error;
+  }
+}

package/src/decision.ts

@@ -0,0 +1,85 @@
+// Functional port of anthonyli/laya-pilot lib/model.mjs (MIT).
+export interface Decision {
+  choice: string;
+  probabilities: Record<string, number>;
+  confidence: number | null;
+}
+export type Decide = (state: string, criteria: Record<string, string>) => Promise<Decision>;
+export function decodeDecision(body: unknown, criteria: Record<string, string>): Decision {
+  const envelope = body as { choices?: { message?: { content?: string } }[] };
+  let result: Decision;
+  try {
+    result = JSON.parse(envelope.choices![0].message!.content!).result.answers.scenario;
+  } catch {
+    throw Error('模型没有返回有效的 Laya 决策 JSON');
+  }
+  const keys = Object.keys(criteria);
+  if (
+    !result ||
+    !Object.hasOwn(criteria, result.choice) ||
+    !result.probabilities ||
+    Object.keys(result.probabilities).length !== keys.length ||
+    keys.some(
+      (key) =>
+        !Number.isFinite(result.probabilities[key]) ||
+        result.probabilities[key] < 0 ||
+        result.probabilities[key] > 1,
+    )
+  )
+    throw Error('模型返回了候选集合之外的选择或无效概率');
+  if (
+    Math.abs(keys.reduce((sum, key) => sum + result.probabilities[key], 0) - 1) > 0.02 ||
+    keys.some((key) => result.probabilities[key] > result.probabilities[result.choice])
+  )
+    throw Error('模型概率与选择不一致');
+  return {
+    choice: result.choice,
+    probabilities: result.probabilities,
+    confidence: Number.isFinite(result.confidence) ? result.confidence : null,
+  };
+}
+export function createApiDecision(options: {
+  base: string;
+  model: string;
+  key: string;
+  timeout?: number;
+  fetchImpl?: typeof fetch;
+}): Decide {
+  const url = new URL(options.base);
+  if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash)
+    throw Error('API 地址必须是无凭据及查询参数的 HTTPS 地址');
+  if (!options.key.trim()) throw Error('缺少模型 API 密钥');
+  return async (state, criteria) => {
+    const response = await (options.fetchImpl ?? fetch)(
+      url.href.replace(/\/$/, '') + '/chat/completions',
+      {
+        method: 'POST',
+        redirect: 'error',
+        signal: AbortSignal.timeout(options.timeout ?? 30000),
+        headers: { Authorization: `Bearer ${options.key}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          model: options.model,
+          stream: false,
+          messages: [
+            {
+              role: 'system',
+              content:
+                '你是浏览器测试决策器。只返回 JSON：{"result":{"answers":{"scenario":{"choice":"候选原文","probabilities":{"每个候选":0.0},"confidence":0.0}}}}。choice 必须属于 criteria，概率覆盖全部候选且和为1，所选概率最大。证据不足选择停止，不编造确定性。',
+            },
+            {
+              role: 'user',
+              content: JSON.stringify({
+                state,
+                questions: {
+                  scenario: { type: 'choice', instructions: '用户请求对应哪个操作？', criteria },
+                },
+              }),
+            },
+          ],
+        }),
+      },
+    );
+    if (!response.ok) throw Error(`模型 API 返回 HTTP ${response.status}`);
+    return decodeDecision(await response.json(), criteria);
+  };
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from './schema.js';
+export { runCase, type ReplayOptions } from './replay.js';
+export { runAssertion } from './assertions.js';
+export { openBrowser } from './browser.js';
+export { waitForReady } from './readiness.js';
+export { createApiDecision, decodeDecision, type Decision, type Decide } from './decision.js';
+export { chooseStep } from './planner.js';

package/src/planner.ts

@@ -0,0 +1,28 @@
+import type { Decide } from './decision.js';
+import type { Step } from './schema.js';
+
+/** A model selects from observed, host-provided candidates. It never generates executable code. */
+export async function chooseStep(
+  instruction: string,
+  candidates: { description: string; step: Step }[],
+  decide: Decide,
+): Promise<Step | null> {
+  if (candidates.length < 1 || candidates.length > 7)
+    throw Error('每次提供 1–7 个可观察的候选操作');
+  const criteria = Object.fromEntries(
+    candidates.map((candidate, index) => [String(index), candidate.description]),
+  );
+  criteria.stop = '无法判断，停止并由用户确认';
+  const result = await decide(instruction, criteria);
+  if (result.choice === 'stop') return null;
+  const index = Number(result.choice);
+  if (!Number.isInteger(index) || !Object.hasOwn(criteria, result.choice) || !candidates[index])
+    throw Error('模型选择不属于候选集');
+  const probabilities = Object.values(result.probabilities).sort((a, b) => b - a);
+  if (
+    (result.probabilities[result.choice] ?? 0) < 0.7 ||
+    probabilities[0] - (probabilities[1] ?? 0) < 0.15
+  )
+    return null;
+  return structuredClone(candidates[index].step);
+}

package/src/readiness.ts

@@ -0,0 +1,92 @@
+// Adapted from anthonyli/laya-pilot lib/readiness.mjs (MIT).
+import type { Page } from 'playwright';
+type Failure = { status: number; path: string; resourceType: string };
+type ReadyOptions = { timeout?: number; minimum?: number; failures?: () => Failure[] };
+
+// Wait for the application, not merely the outer document's DOMContentLoaded.
+export async function waitForReady(
+  page: Page,
+  { timeout = 18000, minimum = 600, failures = () => [] }: ReadyOptions = {},
+) {
+  const start = Date.now();
+  let stableSince = Date.now(),
+    previous = '',
+    last;
+  while (Date.now() - start < timeout) {
+    const errors = failures().filter(
+      (x) =>
+        x.status >= 500 && (/\.html?$|\.js$|\.css$/i.test(x.path) || x.resourceType === 'document'),
+    );
+    const states = [];
+    for (const frame of page.frames())
+      try {
+        states.push(
+          await frame.evaluate(() => {
+            const visible = (e: Element) => {
+              const r = e.getBoundingClientRect(),
+                s = getComputedStyle(e);
+              return (
+                r.width > 0 &&
+                r.height > 0 &&
+                s.display !== 'none' &&
+                s.visibility !== 'hidden' &&
+                !e.closest('[aria-hidden="true"],[inert]')
+              );
+            };
+            const body = document.body;
+            if (!body) return { controls: 0, busy: true, text: '' };
+            const text = body.innerText.trim(),
+              controls = [
+                ...document.querySelectorAll(
+                  'button,input:not([type=hidden]),select,textarea,a[href],[role=tab],[role=combobox],[role=menuitem]',
+                ),
+              ].filter(visible);
+            const loading =
+              [
+                ...document.querySelectorAll(
+                  '[aria-busy=true],.ant-spin-spinning,.el-loading-mask,[role=progressbar]',
+                ),
+              ].some(visible) ||
+              text
+                .split('\n')
+                .some((x) => /^(?:loading\.{0,3}|加载中[.。…]*|正在加载[.。…]*)$/i.test(x.trim()));
+            return {
+              controls: controls.length,
+              busy: loading,
+              text: text.slice(0, 240),
+              signature: controls
+                .slice(0, 60)
+                .map((x) =>
+                  [
+                    x.getAttribute('role'),
+                    x.tagName,
+                    x.getAttribute('placeholder'),
+                    x.getAttribute('aria-label'),
+                    x.textContent?.trim().slice(0, 25),
+                  ].join(':'),
+                )
+                .join('|'),
+            };
+          }),
+        );
+      } catch { /* A frame can detach while the page is settling. */ }
+    const count = states.reduce((n, s) => n + s.controls, 0),
+      busy = states.some((s) => s.busy),
+      fingerprint = states.map((s) => s.signature || '').join('|');
+    last = { count, busy };
+    // A shell may preload unrelated microfrontends. Their errors must not block
+    // an already usable page; only correlate critical errors with an unready UI.
+    if (errors.length && (busy || count === 0))
+      throw new Error(errors.map((x) => x.path + ' HTTP ' + x.status).join('；'));
+    if (fingerprint !== previous || busy || count === 0) {
+      previous = fingerprint;
+      stableSince = Date.now();
+    }
+    if (count > 0 && !busy && Date.now() - stableSince >= minimum)
+      return { duration_ms: Date.now() - start, controls: count };
+    await page.waitForTimeout(150);
+  }
+  throw new Error(
+    `等待${timeout}ms后页面仍为空白或加载中（控件${last?.count || 0}，loading=${last?.busy}），停止本次会话，不继续刷新后续用例`,
+  );
+}

package/src/replay.ts

@@ -0,0 +1,154 @@
+import type { Page, BrowserContext, LaunchOptions, BrowserContextOptions } from 'playwright';
+import { openBrowser } from './browser.js';
+import { waitForReady } from './readiness.js';
+import { runAssertion } from './assertions.js';
+import { parseCase, type RunStatus, type AssertionResult, type Target } from './schema.js';
+
+export interface ReplayOptions {
+  origin: string;
+  allowedOrigins?: string[];
+  launch?: LaunchOptions;
+  context?: BrowserContextOptions;
+  delay?: number;
+  signal?: AbortSignal;
+  /** Host-owned login/setup, never serialized into a case or exposed to the browser. */
+  beforeRun?: (page: Page, context: BrowserContext) => Promise<void>;
+  onProgress?: (status: RunStatus) => void;
+}
+
+async function resolveTarget(page: Page, target: Target) {
+  await page.evaluate((selector) => document.querySelectorAll(selector).length, target.selector);
+  const locator = page.locator('css=' + target.selector);
+  await locator.waitFor({ state: 'attached' });
+  if ((await locator.count()) !== 1) throw Error('目标不是唯一控件，请重新录制');
+  const metadata = await locator.evaluate((e) => {
+    const element = e as HTMLInputElement;
+    const label =
+      element.getAttribute('aria-label') ||
+      element.getAttribute('placeholder') ||
+      element.labels?.[0]?.textContent ||
+      element.textContent ||
+      element.tagName;
+    return {
+      label: label.trim().slice(0, 200),
+      private:
+        Boolean(element.closest('[data-private],.rr-block,[data-research-assistant]')) ||
+        /password|passwd|token|secret|credential|验证码|密码|密钥|口令/i.test(
+          [element.type, element.name, element.id, element.autocomplete, label].join(' '),
+        ),
+    };
+  });
+  if (metadata.private) throw Error('不回放敏感字段或小蜜自身控件');
+  if (target.role) {
+    const named = page.getByRole(target.role as Parameters<Page['getByRole']>[0], {
+      name: target.label,
+      exact: true,
+    });
+    if ((await locator.and(named).count()) !== 1) throw Error('控件语义已变化，请重新录制');
+  } else if (metadata.label !== target.label) throw Error('控件内容已变化，停止回放以避免误操作');
+  if (!(await locator.isVisible())) await locator.locator('..').hover();
+  return locator;
+}
+
+/** Functions compose the execution path. No business route, login or data fixture is built in. */
+export async function runCase(value: unknown, options: ReplayOptions): Promise<RunStatus> {
+  const testCase = parseCase(value);
+  const origin = new URL(options.origin);
+  if (!['http:', 'https:'].includes(origin.protocol) || origin.username || origin.password)
+    throw Error('测试站点地址无效');
+  const destination = new URL(testCase.path, origin);
+  if (destination.origin !== origin.origin) throw Error('用例入口超出测试站点');
+  const allowed = new Set([
+    origin.origin,
+    ...(options.allowedOrigins ?? []).map((url) => new URL(url).origin),
+  ]);
+  const assertions: AssertionResult[] = [];
+  let status: RunStatus = {
+    state: 'running',
+    step: 0,
+    total: testCase.steps.length,
+    message: '正在启动浏览器',
+    assertions,
+  };
+  const report = (patch: Partial<RunStatus>) => {
+    status = { ...status, ...patch, assertions: [...assertions] };
+    options.onProgress?.(status);
+  };
+  if (options.signal?.aborted) return { ...status, state: 'stopped', message: '回放已停止' };
+  const { browser, page, context } = await openBrowser({
+    launch: options.launch,
+    context: options.context,
+  });
+  const stop = () => {
+    void browser.close().catch(() => {});
+  };
+  options.signal?.addEventListener('abort', stop, { once: true });
+  try {
+    if (options.signal?.aborted) throw Error('已停止');
+    await context.route('**/*', (route) =>
+      allowed.has(new URL(route.request().url()).origin) ? route.continue() : route.abort(),
+    );
+    await context.addInitScript(() => {
+      const mount = () => {
+        const style = document.createElement('style');
+        style.textContent = '[data-research-assistant],.research-assistant{display:none!important}';
+        document.documentElement.append(style);
+      };
+      if (document.documentElement) mount();
+      else document.addEventListener('DOMContentLoaded', mount, { once: true });
+    });
+    page.setDefaultNavigationTimeout(60000);
+    await page.goto(destination.href, { waitUntil: 'domcontentloaded' });
+    await waitForReady(page, { timeout: 45000 });
+    await options.beforeRun?.(page, context);
+    for (const [index, step] of testCase.steps.entries()) {
+      if (options.signal?.aborted) throw Error('已停止');
+      report({ step: index + 1, message: `正在执行第 ${index + 1} 步：${step.kind}` });
+      if (options.delay) await page.waitForTimeout(options.delay);
+      if (step.kind === 'assert' || step.kind === 'assert-text') {
+        const assertion = step.assertion ?? {
+          name: step.value!,
+          source: 'page-text' as const,
+          operator: 'contains' as const,
+          expected: step.value,
+          timeout: 10000,
+        };
+        const result = await runAssertion(
+          page,
+          assertion,
+          index + 1,
+          () => options.signal?.aborted === true,
+        );
+        assertions.push(result);
+        report({});
+        if (!result.passed) throw Error(`第 ${index + 1} 步断言失败：${assertion.name}`);
+      } else {
+        if (step.kind === 'unsupported' || !step.target) throw Error('请先补充未支持的步骤');
+        const target = await resolveTarget(page, step.target);
+        if (step.kind === 'click') await target.click();
+        else if (step.kind === 'fill') await target.fill(step.value!);
+        else if (step.kind === 'select') await target.selectOption(step.value!);
+        else if (step.kind === 'check') await target.setChecked(step.checked!);
+        else if (step.kind === 'press') await target.press(step.value!);
+      }
+      await waitForReady(page, { timeout: 10000, minimum: 200 });
+    }
+    report({
+      state: assertions.length ? 'passed' : 'completed',
+      message: assertions.length
+        ? `回放完成，${assertions.length} 条断言全部通过`
+        : '操作回放完成；未设置断言，尚未验证业务结果',
+    });
+  } catch (error) {
+    report({
+      state: options.signal?.aborted ? 'stopped' : 'failed',
+      message: options.signal?.aborted
+        ? '回放已停止'
+        : (error instanceof Error ? error.message : String(error)).slice(0, 1500),
+    });
+  } finally {
+    options.signal?.removeEventListener('abort', stop);
+    await browser.close();
+  }
+  return status;
+}

package/src/schema.ts

@@ -0,0 +1,222 @@
+export interface Target {
+  selector: string;
+  label: string;
+  role?: string;
+}
+export interface Step {
+  kind: 'click' | 'fill' | 'select' | 'check' | 'press' | 'assert-text' | 'assert' | 'unsupported';
+  assertion?: Assertion;
+  target?: Target;
+  value?: string;
+  checked?: boolean;
+  sourceEventId?: number;
+  supplemented?: boolean;
+}
+export const assertionSources = {
+  'page-text': '页面文字',
+  'element-text': '元素文字',
+  'element-value': '输入框值',
+  'element-state': '元素可见性',
+  'element-count': '元素数量',
+} as const;
+export const assertionOperators = {
+  contains: '包含',
+  'not-contains': '不包含',
+  equals: '等于',
+  'not-equals': '不等于',
+  visible: '可见',
+  hidden: '不可见或不存在',
+} as const;
+export interface Assertion {
+  name: string;
+  source: keyof typeof assertionSources;
+  operator: keyof typeof assertionOperators;
+  selector?: string;
+  expected?: string;
+  timeout: number;
+}
+export function operatorsFor(source: Assertion['source']): Assertion['operator'][] {
+  if (source === 'element-state') return ['visible', 'hidden'];
+  if (source === 'element-count') return ['equals', 'not-equals'];
+  return ['contains', 'not-contains', 'equals', 'not-equals'];
+}
+export function parseAssertion(value: unknown): Assertion {
+  const a = value as Assertion;
+  if (!a || typeof a.name !== 'string' || !a.name.trim() || a.name.length > 100)
+    throw Error('请填写 1–100 字的断言名称');
+  if (!Object.hasOwn(assertionSources, a.source) || !operatorsFor(a.source).includes(a.operator))
+    throw Error('不支持的断言对象或条件');
+  if (!Number.isInteger(a.timeout) || a.timeout < 500 || a.timeout > 30000)
+    throw Error('断言等待时间应为 500–30,000 毫秒');
+  if (
+    a.source !== 'page-text' &&
+    (typeof a.selector !== 'string' || !a.selector.trim() || a.selector.length > 2000)
+  )
+    throw Error('请填写有效的 CSS 定位信息');
+  if (a.source !== 'element-state' && (typeof a.expected !== 'string' || a.expected.length > 2000))
+    throw Error('请填写期望值，最多 2,000 字');
+  if (a.source !== 'element-state' && a.source !== 'element-value' && !a.expected?.trim())
+    throw Error('期望值不能为空');
+  if (a.source === 'element-count' && (!/^\d+$/.test(a.expected!) || Number(a.expected) > 100000))
+    throw Error('元素数量应为 0–100,000 的整数');
+  return {
+    name: a.name.trim(),
+    source: a.source,
+    operator: a.operator,
+    timeout: a.timeout,
+    ...(a.source !== 'page-text' ? { selector: a.selector!.trim() } : {}),
+    ...(a.source !== 'element-state' ? { expected: a.expected } : {}),
+  };
+}
+export interface AssertionResult {
+  step: number;
+  name: string;
+  passed: boolean;
+  expected: string;
+  actual: string;
+  duration: number;
+}
+export interface TimelineEvidence {
+  id: number;
+  time: number;
+  kind: string;
+  title: string;
+  page: string;
+  actionId?: number;
+}
+export interface TestCase {
+  schema: 'zhidao-recorded-case';
+  version: 1;
+  name: string;
+  path: string;
+  steps: Step[];
+  timeline?: { capturedAt: string; events: TimelineEvidence[] };
+}
+export interface RunStatus {
+  id?: string;
+  state: 'idle' | 'running' | 'passed' | 'completed' | 'failed' | 'stopped';
+  step: number;
+  total: number;
+  message: string;
+  assertions?: AssertionResult[];
+}
+
+// Shared by the browser and local bridge. No executable JavaScript in case files.
+export function parseCase(value: unknown): TestCase {
+  const input = value as TestCase;
+  if (!input || input.schema !== 'zhidao-recorded-case' || input.version !== 1)
+    throw Error('不是受支持的录制用例 JSON');
+  if (typeof input.name !== 'string' || !input.name.trim() || input.name.length > 100)
+    throw Error('用例名称应为 1–100 个字符');
+  if (
+    typeof input.path !== 'string' ||
+    !input.path.startsWith('/') ||
+    input.path.startsWith('//') ||
+    /[\\\r\n]/.test(input.path) ||
+    input.path.length > 2000
+  )
+    throw Error('用例入口必须是站点内的相对路径');
+  if (!Array.isArray(input.steps) || input.steps.length < 1 || input.steps.length > 100)
+    throw Error('用例需要 1–100 个步骤');
+  const steps = input.steps.map((step): Step => {
+    if (
+      !step ||
+      ![
+        'click',
+        'fill',
+        'select',
+        'check',
+        'press',
+        'assert-text',
+        'assert',
+        'unsupported',
+      ].includes(step.kind)
+    )
+      throw Error('用例包含未知操作');
+    if (step.value !== undefined && (typeof step.value !== 'string' || step.value.length > 2000))
+      throw Error('步骤内容不能超过 2000 个字符');
+    if (step.kind === 'press' && !['Enter', 'Escape', 'Tab'].includes(step.value ?? ''))
+      throw Error('不支持该快捷键');
+    if (step.kind === 'assert-text' && !step.value?.trim()) throw Error('检查点文字不能为空');
+    if (step.kind === 'check' && typeof step.checked !== 'boolean') throw Error('缺少勾选状态');
+    if (['fill', 'select'].includes(step.kind) && step.value === undefined)
+      throw Error('缺少输入值');
+    let target: Target | undefined;
+    if (!['assert-text', 'assert', 'unsupported'].includes(step.kind)) {
+      if (
+        !step.target ||
+        typeof step.target.selector !== 'string' ||
+        !step.target.selector ||
+        step.target.selector.length > 2000 ||
+        typeof step.target.label !== 'string' ||
+        step.target.label.length > 200
+      )
+        throw Error('步骤缺少有效定位信息');
+      target = {
+        selector: step.target.selector,
+        label: step.target.label,
+        ...(typeof step.target.role === 'string' && /^[a-z]+$/.test(step.target.role)
+          ? { role: step.target.role }
+          : {}),
+      };
+    }
+    return {
+      kind: step.kind,
+      ...(step.kind === 'assert' ? { assertion: parseAssertion(step.assertion) } : {}),
+      ...(target ? { target } : {}),
+      ...(step.value !== undefined ? { value: step.value } : {}),
+      ...(step.kind === 'check' ? { checked: step.checked } : {}),
+      ...(Number.isSafeInteger(step.sourceEventId) && step.sourceEventId! > 0
+        ? { sourceEventId: step.sourceEventId }
+        : {}),
+      ...(step.supplemented === true ? { supplemented: true } : {}),
+    };
+  });
+  let timeline: TestCase['timeline'];
+  if (input.timeline !== undefined) {
+    if (
+      !input.timeline ||
+      typeof input.timeline.capturedAt !== 'string' ||
+      !Number.isFinite(Date.parse(input.timeline.capturedAt)) ||
+      !Array.isArray(input.timeline.events) ||
+      input.timeline.events.length > 300
+    )
+      throw Error('时间线来源格式错误');
+    const ids = new Set<number>();
+    const events = input.timeline.events.map((e) => {
+      if (
+        !e ||
+        !Number.isSafeInteger(e.id) ||
+        e.id <= 0 ||
+        ids.has(e.id) ||
+        !Number.isFinite(e.time) ||
+        !['route', 'click', 'change', 'request', 'error', 'performance'].includes(e.kind) ||
+        typeof e.title !== 'string' ||
+        e.title.length > 200 ||
+        typeof e.page !== 'string' ||
+        e.page.length > 2000
+      )
+        throw Error('时间线来源事件格式错误');
+      ids.add(e.id);
+      return {
+        id: e.id,
+        time: e.time,
+        kind: e.kind,
+        title: e.title,
+        page: e.page,
+        ...(Number.isSafeInteger(e.actionId) && e.actionId! > 0 ? { actionId: e.actionId } : {}),
+      };
+    });
+    if (steps.some((s) => s.sourceEventId !== undefined && !ids.has(s.sourceEventId)))
+      throw Error('步骤引用的原始事件不存在');
+    timeline = { capturedAt: input.timeline.capturedAt, events };
+  } else if (steps.some((s) => s.sourceEventId !== undefined)) throw Error('缺少步骤的原始时间线');
+  return {
+    schema: 'zhidao-recorded-case',
+    version: 1,
+    name: input.name.trim(),
+    path: input.path,
+    steps,
+    ...(timeline ? { timeline } : {}),
+  };
+}

package/src/targets.ts

@@ -0,0 +1,61 @@
+import { computeAccessibleName, getRole } from 'dom-accessibility-api';
+import type { Target } from './schema.js';
+
+export const excluded = '[data-research-assistant],.research-assistant,[data-private],.rr-block';
+export const controls =
+  'button,a[href],input,textarea,select,[role="button"],[role="tab"],[role="option"],[role="menuitem"],[role="checkbox"],[role="combobox"],summary';
+export const normalizeText = (value: string) => value.replace(/\s+/g, ' ').trim();
+
+/** Accessible names follow the W3C AccName algorithm, including labelledby and label-for. */
+export function describeControl(element: Element) {
+  const role = getRole(element) ?? undefined;
+  const explicit = element.getAttribute('data-assistant-label');
+  const accessible = computeAccessibleName(element, { computedStyleSupportsPseudoElements: false });
+  const fallback =
+    element.getAttribute('placeholder') ||
+    element.getAttribute('name') ||
+    role ||
+    element.tagName.toLowerCase();
+  return {
+    role,
+    label: normalizeText(explicit || accessible || fallback).slice(0, 200),
+    labelSource: explicit ? 'business-label' : accessible ? 'accessible-name' : 'attribute',
+    testId: element.getAttribute('data-testid') ?? undefined,
+  };
+}
+export function privateInput(element: Element) {
+  return (
+    Boolean(element.closest('[data-private],.rr-block')) ||
+    /password|passwd|token|secret|credential|验证码|密码|密钥|口令/i.test(
+      ['type', 'name', 'id', 'autocomplete', 'aria-label', 'placeholder']
+        .map((key) => element.getAttribute(key))
+        .join(' ') +
+        ' ' +
+        computeAccessibleName(element, { computedStyleSupportsPseudoElements: false }),
+    )
+  );
+}
+export function locate(element: Element): Target {
+  const { label, role, labelSource } = describeControl(element);
+  const semantic = role && labelSource === 'accessible-name' ? { role } : {};
+  const doc = element.ownerDocument;
+  for (const attribute of ['data-testid', 'id', 'aria-label', 'placeholder', 'name']) {
+    const value = element.getAttribute(attribute);
+    const selector = `${element.tagName.toLowerCase()}[${attribute}=${JSON.stringify(value ?? '')}]`;
+    if (value && doc.querySelectorAll(selector).length === 1)
+      return { selector, label, ...semantic };
+  }
+  const path: string[] = [];
+  for (
+    let current: Element | null = element;
+    current && current !== doc.body;
+    current = current.parentElement
+  ) {
+    const parent: Element | null = current.parentElement;
+    if (!parent) break;
+    const index =
+      [...parent.children].filter((e) => e.tagName === current!.tagName).indexOf(current) + 1;
+    path.unshift(`${current.tagName.toLowerCase()}:nth-of-type(${index})`);
+  }
+  return { selector: `body > ${path.join(' > ')}`, label, ...semantic };
+}