browser-opt 1.0.1

package/dist/cli/utils/args.js

@@ -0,0 +1,74 @@
+/**
+ * 统一封装 CLI 参数解析与常用 flag 读取逻辑，避免各命令重复处理细节。
+ * 这里仅负责轻量解析，不引入命令语义，让命令文件保持聚焦在业务流程上。
+ */
+export function parseCliArgs(args) {
+    const positionals = [];
+    const flags = {};
+    for (let i = 0; i < args.length; i++) {
+        const token = args[i];
+        if (!token.startsWith('--')) {
+            positionals.push(token);
+            continue;
+        }
+        const key = token.slice(2);
+        const next = args[i + 1];
+        if (next && !next.startsWith('--')) {
+            flags[key] = next;
+            i += 1;
+        }
+        else {
+            flags[key] = true;
+        }
+    }
+    return { positionals, flags };
+}
+export function getStringFlag(flags, key) {
+    const value = flags[key];
+    return typeof value === 'string' ? value : undefined;
+}
+export function getBooleanFlag(flags, key) {
+    return flags[key] === true;
+}
+export function resolveProfile(flags) {
+    return getStringFlag(flags, 'profile');
+}
+export function resolveStatePath(flags) {
+    const flagState = getStringFlag(flags, 'state')?.trim();
+    if (flagState) {
+        return flagState;
+    }
+    const envState = process.env.AGENT_BROWSER_STATE?.trim();
+    return envState || undefined;
+}
+export function resolveReuseRunningBrowser(flags, statePath, defaultValue = false) {
+    if (statePath) {
+        return false;
+    }
+    if (getBooleanFlag(flags, 'clean-browser')) {
+        return false;
+    }
+    if (getBooleanFlag(flags, 'reuse-focused-browser')) {
+        return true;
+    }
+    return defaultValue;
+}
+export function resolveLiveViewport(flags) {
+    if (getBooleanFlag(flags, 'no-live-viewport')) {
+        return false;
+    }
+    if (getBooleanFlag(flags, 'live-viewport')) {
+        return true;
+    }
+    return true;
+}
+export function parseCsv(value) {
+    if (!value) {
+        return [];
+    }
+    return value
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+}
+//# sourceMappingURL=args.js.map

package/dist/cli/utils/args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../../../src/cli/utils/args.ts"],"names":[],"mappings":"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"}

package/dist/cli/utils/constants.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 存放 browser-opt CLI 复用的提示文案与常量，避免命令编排文件混入长文本。
+ * 当前只保留 browser-opt 自身会消费的内容，防止把 browser-e2e 边界带进来。
+ */
+export declare const LIVE_VIEWPORT_DASHBOARD_URL = "http://localhost:4848";
+export declare const HANDOFF_DONE_ANSWERS: readonly ["done", "ok", "继续", "完成"];
+export declare const BROWSER_OPT_USAGE = "\u4F7F\u7528\u65B9\u5F0F\uFF1A\n  npx browser-opt <\u81EA\u7136\u8BED\u8A00\u6D41\u7A0B> [--profile <name>] [--state <path>] [--session <id>] [--no-live-viewport] [--output-dir <dir>] [--agent-chat]\n  npx browser-opt setup [--with-deps] [--skip-skill] [--agent agents|codex] [--skills-dir <\u76EE\u5F55>]\n  npx browser-opt save \"<\u540D\u79F0>\" --flow \"<\u5B8C\u6574\u6D41\u7A0B>\" [--workflow-dir <\u76EE\u5F55>] [--force]\n  npx browser-opt run \"<\u67E5\u8BE2\u8BED\u53E5>\" [--workflow-dir <\u76EE\u5F55>]\n  npx browser-opt run --workflow-id \"<ID>\" [--workflow-dir <\u76EE\u5F55>]\n  npx browser-opt start --workflow-id \"<ID>\" [--workflow-dir <\u76EE\u5F55>] [--json]\n  npx browser-opt status --run-id \"<ID>\" [--json]\n  npx browser-opt resume --run-id \"<ID>\" [--json]\n  npx browser-opt list [--workflow-dir <\u76EE\u5F55>] [--json]\n  npx browser-opt match \"<\u67E5\u8BE2\u8BED\u53E5>\" [--workflow-dir <\u76EE\u5F55>] [--json]";
+//# sourceMappingURL=constants.d.ts.map

package/dist/cli/utils/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,eAAO,MAAM,2BAA2B,0BAA0B,CAAC;AAEnE,eAAO,MAAM,oBAAoB,qCAAsC,CAAC;AAExE,eAAO,MAAM,iBAAiB,07BAUkC,CAAC"}

package/dist/cli/utils/constants.js

@@ -0,0 +1,18 @@
+/**
+ * 存放 browser-opt CLI 复用的提示文案与常量，避免命令编排文件混入长文本。
+ * 当前只保留 browser-opt 自身会消费的内容，防止把 browser-e2e 边界带进来。
+ */
+export const LIVE_VIEWPORT_DASHBOARD_URL = 'http://localhost:4848';
+export const HANDOFF_DONE_ANSWERS = ['done', 'ok', '继续', '完成'];
+export const BROWSER_OPT_USAGE = `使用方式：
+  npx browser-opt <自然语言流程> [--profile <name>] [--state <path>] [--session <id>] [--no-live-viewport] [--output-dir <dir>] [--agent-chat]
+  npx browser-opt setup [--with-deps] [--skip-skill] [--agent agents|codex] [--skills-dir <目录>]
+  npx browser-opt save "<名称>" --flow "<完整流程>" [--workflow-dir <目录>] [--force]
+  npx browser-opt run "<查询语句>" [--workflow-dir <目录>]
+  npx browser-opt run --workflow-id "<ID>" [--workflow-dir <目录>]
+  npx browser-opt start --workflow-id "<ID>" [--workflow-dir <目录>] [--json]
+  npx browser-opt status --run-id "<ID>" [--json]
+  npx browser-opt resume --run-id "<ID>" [--json]
+  npx browser-opt list [--workflow-dir <目录>] [--json]
+  npx browser-opt match "<查询语句>" [--workflow-dir <目录>] [--json]`;
+//# sourceMappingURL=constants.js.map

package/dist/cli/utils/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/cli/utils/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,CAAC,MAAM,2BAA2B,GAAG,uBAAuB,CAAC;AAEnE,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAU,CAAC;AAExE,MAAM,CAAC,MAAM,iBAAiB,GAAG;;;;;;;;;;gEAU+B,CAAC"}

package/dist/cli/utils/output.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 统一管理 browser-opt CLI 的结果输出，避免命令编排代码夹杂大量控制台细节。
+ * 该文件只保留 browser-opt 自己会用到的展示逻辑，不再耦合 browser-e2e 文案。
+ */
+import type { BrowserOptRunResult } from '../../browser-opt/type.js';
+export declare function printBrowserOptResult(result: BrowserOptRunResult): void;
+//# sourceMappingURL=output.d.ts.map

package/dist/cli/utils/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/output.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAGrE,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI,CA8CvE"}

package/dist/cli/utils/output.js

@@ -0,0 +1,45 @@
+import { collectFailedBrowserOptSteps, formatBrowserOptStepStatus } from '../../browser-opt/utils.js';
+export function printBrowserOptResult(result) {
+    if (result.passed) {
+        console.log('执行成功');
+        return;
+    }
+    const { report } = result;
+    console.log(`Status: ${report.status}`);
+    if (report.handoffTriggered) {
+        console.log('Handoff: 已触发，请在浏览器中完成登录后输入 done 继续。');
+    }
+    console.log(`Report JSON: ${report.reportJsonPath}`);
+    console.log(`Report Markdown: ${report.reportMarkdownPath}`);
+    console.log(`Log: ${report.logPath}`);
+    const failedSteps = collectFailedBrowserOptSteps(report);
+    console.log('Failed steps:');
+    if (failedSteps.length === 0) {
+        console.log('  - n/a');
+    }
+    else {
+        for (const step of failedSteps) {
+            console.log(`  - ${step.index}. ${step.instruction}`);
+            console.log(`    Reason: ${step.error ?? step.verification ?? '未知原因'}`);
+        }
+    }
+    console.log('Evidence screenshots:');
+    for (const screenshot of report.screenshots) {
+        console.log(`  - ${screenshot}`);
+    }
+    console.log('Detailed log:');
+    for (const log of report.logs) {
+        console.log(`  ${log}`);
+    }
+    for (const step of report.steps) {
+        const mark = formatBrowserOptStepStatus(step);
+        console.log(`${mark} ${step.index}. ${step.instruction}`);
+        if (step.handoffTriggered && step.verification) {
+            console.log(`  Handoff: ${step.verification}`);
+        }
+        if (step.error) {
+            console.log(`  Error: ${step.error}`);
+        }
+    }
+}
+//# sourceMappingURL=output.js.map

package/dist/cli/utils/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../../../src/cli/utils/output.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,4BAA4B,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AAEtG,MAAM,UAAU,qBAAqB,CAAC,MAA2B;IAC/D,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClB,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACpB,OAAO;IACT,CAAC;IAED,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IAC1B,OAAO,CAAC,GAAG,CAAC,WAAW,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IACxC,IAAI,MAAM,CAAC,gBAAgB,EAAE,CAAC;QAC5B,OAAO,CAAC,GAAG,CAAC,qCAAqC,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,gBAAgB,MAAM,CAAC,cAAc,EAAE,CAAC,CAAC;IACrD,OAAO,CAAC,GAAG,CAAC,oBAAoB,MAAM,CAAC,kBAAkB,EAAE,CAAC,CAAC;IAC7D,OAAO,CAAC,GAAG,CAAC,QAAQ,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;IAEtC,MAAM,WAAW,GAAG,4BAA4B,CAAC,MAAM,CAAC,CAAC;IACzD,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IAC7B,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACzB,CAAC;SAAM,CAAC;QACN,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;YAC/B,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;YACtD,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,YAAY,IAAI,MAAM,EAAE,CAAC,CAAC;QAC1E,CAAC;IACH,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;IACrC,KAAK,MAAM,UAAU,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC;QAC5C,OAAO,CAAC,GAAG,CAAC,OAAO,UAAU,EAAE,CAAC,CAAC;IACnC,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IAC7B,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;QAC9B,OAAO,CAAC,GAAG,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC;IAC1B,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QAChC,MAAM,IAAI,GAAG,0BAA0B,CAAC,IAAI,CAAC,CAAC;QAC9C,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;QAC1D,IAAI,IAAI,CAAC,gBAAgB,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YAC/C,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC;QACjD,CAAC;QACD,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "browser-opt",
+  "version": "1.0.1",
+  "description": "带证据报告的自然语言浏览器工作流 CLI",
+  "type": "module",
+  "main": "dist/browser-opt/index.js",
+  "types": "dist/browser-opt/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/browser-opt/index.js",
+      "types": "./dist/browser-opt/index.d.ts"
+    }
+  },
+  "bin": {
+    "browser-opt": "dist/cli/browser-opt.js"
+  },
+  "files": [
+    "dist",
+    "skills/browser-opt"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@browser-automated/browser-core": "1.0.0",
+    "agent-browser": "^0.33.1"
+  }
+}

package/skills/browser-opt/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: browser-opt
+description: Execute natural-language browser flows with agent-browser and produce simplified PASS/FAIL results.
+summary: Run deterministic browser execution loops with screenshots, JSON snapshots, retries, and concise success output.
+---
+
+# browser-opt skill
+
+This skill is the deterministic browser execution entrypoint. It is intentionally separate from `browser-e2e`: `browser-opt` runs the flow now and reports evidence; it does not match generated tests or create Playwright code.
+
+By default, the calling AI is responsible for understanding the page from `snapshot --json`; `agent-browser` only executes deterministic commands such as `open`, `fill @ref`, `click @ref`, screenshots, and waits. Do not use `agent-browser chat` unless the user explicitly asks for the legacy chat mode or passes `--agent-chat`.
+
+Natural-language steps that explicitly ask to open developer tools are mapped to
+CDP's experimental `Target.openDevTools` command. This opens native DevTools for
+the active target in the same Chrome window; do not use `agent-browser inspect`,
+which opens a separate DevTools frontend URL. If the current Chrome version does
+not support `Target.openDevTools`, report the failure instead of falling back to
+the separate frontend. Supported expressions include `打开开发者工具`,
+`启动 DevTools`, `调起 Chrome DevTools`, and `inspect current page`:
+
+```text
+/browser-opt 测试 https://example.com 的页面调试流程。
+
+目标：
+1. 打开开发者工具。
+```
+
+## Image upload examples
+
+For test environments, describe upload steps as automatic URL uploads. `browser-opt` downloads the remote image into the run evidence directory and calls `agent-browser upload` with the local file path:
+
+```text
+/browser-opt 测试 https://example.com/live/create 的直播间创建流程。
+
+目标：
+1. 打开页面。
+2. 在“直播间名称”输入“自动化测试直播间”。
+3. 自动上传“直播间分享封面”，图片来源 URL 为“https://stantic.ifengqun.com/front/fq-ecmiddle-sys/upload/82243689cae75e27b3867a5cbdd4292b.png”。
+4. 自动上传“直播间封面”，图片来源 URL 为“https://stantic.ifengqun.com/front/fq-ecmiddle-sys/upload/82243689cae75e27b3867a5cbdd4292b.png”。
+5. 验证页面显示封面预览或上传成功状态。
+```
+
+For production environments, describe upload steps as manual handoff so the operator can choose real local images through the system file picker:
+
+```text
+/browser-opt 操作 https://example.com/live/create 的直播间创建流程。
+
+目标：
+1. 打开页面。
+2. 在“直播间名称”输入“正式直播间名称”。
+3. handoff 给操作人员：请手动选择“直播间分享封面”的本地真实图片，并在裁剪/确认完成后恢复自动化。
+4. handoff 给操作人员：请手动选择“直播间封面”的本地真实图片，并在裁剪/确认完成后恢复自动化。
+5. 验证页面显示封面预览或上传成功状态。
+```
+
+## Required agent-browser practice
+
+Every execution must follow these rules:
+
+- Always open the actual system Chrome browser for the run. Do not open or operate inside the agent tool's built-in browser, including the Copilot/Codex in-app browser or any agent-browser dashboard/preview window.
+- Strictly run an `open -> snapshot --json -> deterministic act -> re-snapshot` loop.
+- Take a screenshot for every step.
+- Use text matching or element existence checks for verification points.
+- Retry with a fresh snapshot when an action fails or an element reference is stale.
+- Use `--json` output when parsing elements.
+- After every step, reason about the current page state and the next action.
+- If a reference becomes invalid, take a fresh snapshot before retrying.
+- Prefer deterministic commands and element refs over natural-language `chat`.
+- Final report must include `PASS` or `FAIL`, evidence screenshot paths, and detailed logs.
+
+## Interactive handoff execution
+
+For saved workflows, start the browser run as a detached task and keep the returned stable `runId`. Do not keep an `exec_command` or PTY session id as the recovery handle; Codex may discard that process handle when the handoff response ends the current turn.
+
+```bash
+npx --yes browser-opt start --workflow-id "<matched.id>" --json
+npx --yes browser-opt status --run-id "<runId>" --json
+```
+
+Poll `status` until it returns `PASS`, `FAIL`, or `HANDOFF`. When it returns `HANDOFF`, ask the user to finish the manual action and end the current turn normally. After the user replies `done`, restore the original runner and browser with:
+
+```bash
+npx --yes browser-opt resume --run-id "<runId>" --json
+npx --yes browser-opt status --run-id "<runId>" --json
+```
+
+The detached task still executes `browser-opt run` exactly once. `status` is read-only and `resume` only sends a one-time signal to that original process. Never start a second `run` or `start` command to simulate resume.
+
+## Saved workflows
+
+Reusable flows are stored as JSON files under the calling project's
+`.browser-opt/workflows/` directory by default. Resolve relative paths from the
+calling project's current working directory, not from this skill or package directory.
+
+Install the published CLI and this Skill with `npx --yes browser-opt setup`.
+By default it installs to the shared Agent Skills directory, similar to
+`npx skills add`. Use `--agent codex` for the Codex-specific skills directory,
+or `--skills-dir <dir>` for another agent root.
+Use this command prefix for every `browser-opt` invocation:
+
+```bash
+npx --yes browser-opt
+```
+
+Only use `browser-opt ...` when `command -v browser-opt` succeeds in the same
+execution environment; otherwise use `npx --yes browser-opt ...`.
+
+Save a complete flow without executing it:
+
+```bash
+npx --yes browser-opt save "创建安选公开直播流程" --flow "<full natural language flow>"
+npx --yes browser-opt save "创建安选公开直播流程" --flow "<full natural language flow>" --workflow-dir ./custom/workflows
+```
+
+Saving an existing name fails by default. Only pass `--force` when the user
+explicitly wants to replace it.
+
+Saved workflow files are structured JSON, not a single `flow` string. The
+persisted schema uses `target.url` as the page entrypoint plus a `steps` string
+array for business actions after the page is opened. When `target.url` exists,
+do not include a first step such as "打开页面":
+
+```json
+{
+  "id": "创建安选公开直播流程",
+  "name": "创建安选公开直播流程",
+  "target": {
+    "url": "https://example.com/live/create"
+  },
+  "steps": [
+    "在“直播间名称”输入“自动化测试直播间”。",
+    "验证页面包含“创建成功”。"
+  ],
+  "createdAt": "2026-07-28T08:00:00.000Z",
+  "updatedAt": "2026-07-28T08:00:00.000Z"
+}
+```
+
+When `/browser-opt` is followed by a short request without a URL, such as:
+
+```text
+/browser-opt 执行创建安选公开直播流程
+```
+
+Do not treat it as a new one-shot flow. First run:
+
+```bash
+npx --yes browser-opt match "<short request>" --json
+```
+
+Handle the JSON result as follows:
+
+- `matched`: run `npx --yes browser-opt start --workflow-id "<matched.id>" --json`, retain its `runId`, and follow the interactive handoff execution protocol above.
+- `ambiguous`: do not rely on the CLI's human-readable stdout as the user-facing
+  choice list, and do not ask through a modal/input tool that may render Markdown
+  as plain text. Parse `match --json`, then ask in a normal assistant message.
+  Show the returned candidates, at most three, numbered from 1. Render each
+  candidate name itself as a Markdown file link using `filePath`, such as
+  `[创建安选公开直播流程](</absolute/path/创建安选公开直播流程.json>)`. Do not show a
+  bare `file://` URL. Ask the user to reply with the number (for example `1`,
+  `2`, or `3`), even when there is only one weakly similar candidate. Do not
+  open a browser before the choice. Then map the selected number back to the
+  candidate ID and run it. In GitHub Copilot Chat, local Markdown file links may
+  render as plain text; include `displayPath` in backticks after the link so the
+  path remains visible and can be opened through VS Code's file detection.
+- `not-found`: tell the user no saved workflow matched and show the returned
+  available workflow names as Markdown file links using `filePath` when present.
+  Ask for a more specific request or a full flow with URL.
+- Warnings describe invalid workflow files that were skipped. Report them without
+  blocking valid candidates.
+
+Use `--workflow-dir` consistently on both `match` and `run` when the user selects
+a custom directory. Use `npx --yes browser-opt list --json` when
+the user asks to see all saved workflows.
+
+Example ambiguous response format:
+
+```markdown
+匹配结果是 `ambiguous`，请回复要执行的流程编号：
+
+1. [创建安选公开直播（测试环境）](</Users/lee/project/.browser-opt/workflows/创建安选公开直播（测试环境）.json>)
+   `.browser-opt/workflows/创建安选公开直播（测试环境）.json`
+2. [创建安选私域直播](</Users/lee/project/.browser-opt/workflows/创建安选私域直播.json>)
+   `.browser-opt/workflows/创建安选私域直播.json`
+
+请回复数字，例如 `1`。
+```
+
+## Trigger
+
+Use `/browser-opt` followed by either a full natural-language flow or a saved
+workflow request. A full flow includes its target URL:
+
+```text
+/browser-opt 测试 https://example.com 的搜索功能。
+
+目标：
+1. 打开首页。
+2. 在搜索框输入 "agent-browser"。
+3. 点击搜索按钮。
+4. 验证搜索结果页面是否包含至少 3 个结果项。
+5. 点击第一个结果，验证跳转正确。
+```
+
+Translate that into:
+
+```bash
+npx --yes browser-opt "<full natural language flow>"
+```
+
+Optional runtime flags:
+
+```bash
+npx --yes browser-opt "<flow>" --profile Default
+npx --yes browser-opt "<flow>" --state ./.browser-opt/states/browser-opt-default.json
+npx --yes browser-opt "<flow>" --no-live-viewport
+npx --yes browser-opt "<flow>" --output-dir ./.browser-opt/artifacts
+npx --yes browser-opt "<flow>" --agent-chat
+```
+
+Auth state reuse policy:
+
+- `browser-opt` first checks its saved auth state under `.browser-opt/states/`.
+- If a default state file exists, it loads that state first, so only cookies/storage are reused and prior Chrome tabs are not restored.
+- If the default state opens on a login screen or later redirects there, close the state window and replace it once with the selected Chrome profile before entering handoff. Keep that profile window and the original `browser-opt` runner alive for resume so the operator can use Chrome's password manager.
+- Saved workflows keep the original runner alive as a detached task and use `runId` for handoff recovery across Codex turns; an `exec_command` session id is never a durable recovery handle.
+- Programmatic runs use the same one-time profile fallback when the default state is invalid.
+- If no default state file exists, the single main agent opens the target directly with `--profile Default` and saves state from that same window. Do not create a separate profile importer.
+- Pass `--profile <name>` to choose a different Chrome profile for first import and default-state fallback.
+- Pass `--state <path>` to use a custom state file without automatic profile fallback.
+- Do not rely on focused-browser reuse for login import: ordinary Chrome is usually not CDP-accessible, and auto-connect can attach to the wrong temporary browser.
+
+It shows and keeps the actual system Chrome browser by default so the user can watch the operation and inspect the final page state. This must be a real Chrome window, not the agent tool's built-in browser such as the Copilot/Codex in-app browser, and it must not open the agent-browser dashboard at `http://localhost:4848`. Use `--no-live-viewport` only when the user explicitly wants headless execution. `--agent-chat` is a legacy compatibility mode. It may require `AI_GATEWAY_API_KEY`; avoid it when the caller can inspect snapshots and produce deterministic actions.
+
+## Output
+
+The CLI writes an evidence directory under `.browser-opt/artifacts/` unless `--output-dir` is provided.
+
+Expected artifacts:
+
+- `report.json` for machine parsing.
+- `report.md` for human review.
+- `00-open.png`, `01-before.png`, `01-after.png`, and later step screenshots.
+- `*.snapshot.json` files captured through `agent-browser snapshot -i --json`.
+
+The assistant response must be concise:
+
+- If the run succeeds, reply only with `执行成功`.
+- If the run fails, summarize the failure status, report paths, screenshot paths, and failing step.

package/skills/browser-opt/manifest.json

@@ -0,0 +1,75 @@
+{
+  "name": "browser-opt",
+  "version": "0.2.0",
+  "description": "Run immediate or project-saved natural-language browser workflows with simplified PASS/FAIL results",
+  "triggers": [
+    "browser-opt",
+    "natural language browser flow",
+    "execute browser flow",
+    "自然语言执行浏览器流程",
+    "执行已保存的浏览器流程",
+    "运行 workflow"
+  ],
+  "inputs": {
+    "type": "object",
+    "properties": {
+      "flow": {
+        "type": "string",
+        "description": "Full natural-language browser flow including a URL and expected steps"
+      },
+      "query": {
+        "type": "string",
+        "description": "Short request used to match a saved workflow in the calling project"
+      },
+      "workflowDir": {
+        "type": "string",
+        "description": "Optional workflow directory, default .browser-opt/workflows under the calling project"
+      },
+      "profile": {
+        "type": "string",
+        "description": "Chrome profile name or path. Use state for login-only reuse; profile keeps full Chrome profile behavior."
+      },
+      "state": {
+        "type": "string",
+        "description": "Path to an agent-browser state file. Preferred for reusing login state without restoring tabs or Chrome recovery UI."
+      },
+      "liveViewport": {
+        "type": "boolean",
+        "description": "Whether to show the actual system Chrome browser, default true; never use the agent tool's built-in browser or the agent-browser dashboard"
+      },
+      "outputDir": {
+        "type": "string",
+        "description": "Optional directory for evidence reports"
+      }
+    }
+  },
+  "outputs": {
+    "type": "object",
+    "properties": {
+      "status": {
+        "enum": [
+          "PASS",
+          "FAIL"
+        ]
+      },
+      "reportJsonPath": {
+        "type": "string"
+      },
+      "reportMarkdownPath": {
+        "type": "string"
+      },
+      "screenshotPaths": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      },
+      "logPaths": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}