pageqa 0.1.0

package/README.md

@@ -0,0 +1,152 @@
+# pageqa
+
+用自然语言驱动的页面测试 agent。基于 **pi-agent-core**（状态化 LLM agent）编排测试步骤，**browserskill（`bsk`）** 驱动真实浏览器执行，自然语言解析由可配置的 LLM 端点完成。最终产出可读文本报告与机器可读 JSON 报告，返回可接入 CI 的退出码。
+
+- 运行时：**Node.js + TypeScript**，npm 分发，CLI 入口。
+- 浏览器驱动：**browserskill（`bsk`）**，连接一个已运行的真实浏览器（Chrome/Edge），支持公开页与登录态页面。
+- 自然语言驱动：**pi-agent-core** 状态化 agent，把自然语言意图解析为浏览器操作步骤并自动编排；LLM 后端通过可配置的 OpenAI 兼容端点接入（base URL / API Key / 模型均可配置）。
+
+## 前置
+
+### 1. 安装并配置 browserskill（`bsk`）
+
+`bsk` 是连接真实浏览器（Chrome/Edge）的驱动，本项目通过它执行页面操作。
+
+- 项目主页与安装方式：**https://github.com/Tencent/BrowserSkill**
+- 按仓库 README 安装 `bsk` CLI 并启动 daemon，然后连接一个已登录的浏览器（支持公开页与登录态页面）。
+
+验证安装与连接：
+```bash
+bsk status           # 确认 daemon 已启动且已连接浏览器
+bsk session start    # 创建 session（CLI 也会自动创建）
+```
+
+> 提示：本工具的 `--session <id>` 即来自 `bsk session start` 返回的 `session_id`；不传时 CLI 会自动新建一个（前提 daemon 已连浏览器）。
+
+### 2. LLM 后端（可配置 OpenAI 兼容端点）
+
+自然语言解析依赖一个 OpenAI 兼容的 LLM 端点。端点地址、密钥与模型均可通过配置文件或环境变量设置：
+
+- 默认地址：`http://127.0.0.1:3000/v1`（可被覆盖为任意 OpenAI 兼容端点）
+- 默认 Key：`codebuddy-proxy-key`
+
+可用环境变量覆盖（优先级高于配置文件）：
+- `PAGEQA_LLM_BASE_URL`
+- `PAGEQA_LLM_API_KEY`
+- `PAGEQA_LLM_MODEL`
+
+### 3. 用户级配置文件（可选但推荐）
+
+工具会在**用户主目录**自动创建配置文件，持久化 LLM 设置，避免每次用环境变量：
+
+- 配置目录：`~/.pageqa`（Windows：`%USERPROFILE%\.pageqa`）
+- 配置文件：`config.json`
+
+```json
+{
+  "baseUrl": "http://127.0.0.1:3000/v1",
+  "apiKey": "codebuddy-proxy-key",
+  "model": "hunyuan-2.0-instruct"
+}
+```
+
+- 首次运行（或执行 `pageqa --init-config`）会自动创建该文件，编辑即可切换模型/端点地址/密钥。
+- **优先级（高 → 低）**：环境变量 `PAGEQA_LLM_*`  >  用户配置文件 `config.json`  >  内置默认值。
+- 例如要改用其他兼容 OpenAI 的端点，把 `baseUrl`/`apiKey`/`model` 改掉即可，无需改代码。
+
+## 安装
+
+本地开发：
+```bash
+npm install
+npm run build
+```
+
+全局安装（发布后）：
+```bash
+npm install -g pageqa
+pageqa --init-config   # 在用户目录创建配置文件 ~/.pageqa/config.json
+```
+
+> 全局安装后首次运行也会自动创建配置文件；用 `--init-config` 可显式创建/重置。
+
+## 使用
+
+```bash
+# 内联自然语言（多句按行分隔）
+pageqa --session <id> "打开 https://example.com
+并断言标题包含 Example"
+
+# 读取脚本文件（自动识别 `## ` 分隔的多个场景，逐个运行并汇总）
+pageqa examples/smoke.md
+
+# JSON 报告
+pageqa --json examples/smoke.md
+
+# 强制按多场景套件运行（即使只有一个场景）
+pageqa --suite "打开 https://example.com 并断言标题包含 Example"
+```
+
+### 多场景套件
+
+脚本（`.md`/`.txt`）中用 `## 场景名` 分隔多个独立测试场景，CLI 会逐个运行、分别给出结论，并汇总整体 PASS/FAIL 与总退出码（任一场景失败则整体失败）。
+
+### CLI 选项
+
+| 选项 | 说明 |
+| --- | --- |
+| `--session <id>` | 指定已存在的 bsk session（默认自动创建） |
+| `--json` | 输出 JSON 报告 |
+| `--suite` | 强制按多场景套件运行 |
+| `--init-config` | 在用户目录创建/重置配置文件 |
+| `--out <file>` | 将报告写入文件 |
+| `-h, --help` | 帮助 |
+
+退出码：`0` 全部断言通过；`1` 任一断言失败/错误/无法执行。可直接接入 CI。
+
+## 工作原理
+
+```
+自然语言意图
+   └─> pi-agent-core Agent（LLM: pi-ai 自定义 provider -> 可配置 OpenAI 兼容端点）
+          └─> bsk 工具：navigate / snapshot / click / fill / hover / scroll / wait / assert_text
+                 └─> 真实浏览器（bsk 连接）
+          └─> 结论与证据 -> 报告（文本/JSON）+ 退出码
+```
+
+可用工具（`src/bsk/tools.ts`）：
+- `navigate(url)` 打开网页
+- `snapshot()` 读取页面 aria 树与可见文本（标题、段落、链接、按钮等）
+- `click(target)` / `fill(target, value)` / `hover(target)` 元素交互（target 用 `@eN` 引用或 CSS 选择器）
+- `scroll(target)` / `wait(ms)` 滚动与等待
+- `assert_text(expectation)` 断言页面是否包含指定文本，返回「成立/不成立」与证据
+
+## 验证
+
+```bash
+npm test
+```
+
+冒烟测试覆盖：A1 打开+标题断言、A2 元素交互与断言、A3 失败可读原因与退出码、A4 文本/JSON 报告。需 bsk daemon 连接浏览器且 LLM 端点可用。
+
+也可直接运行套件脚本：
+
+```bash
+pageqa examples/smoke.md --json
+```
+
+## CI 集成
+
+`.github/workflows/ci.yml` 演示如何在 GitHub Actions 中接入：安装 bsk 并连接浏览器 → 构建 → 运行 `examples/smoke.md` → 上传 JSON 报告。失败场景会使退出码非零，从而标记 CI 失败。LLM 端点地址/Key 通过仓库 Secrets（`PAGEQA_LLM_BASE_URL` 等）注入。
+
+## 目录
+
+```text
+src/
+  index.ts       CLI 入口
+  agent.ts       编排器（pi-agent-core Agent + bsk 工具 + 报告）
+  llm.ts         LLM 后端（pi-ai 自定义 provider -> 可配置 OpenAI 兼容端点）
+  bsk/tools.ts   browserskill 工具层
+  report.ts      报告解析与渲染
+tests/smoke.test.mjs 端到端验证
+```

package/dist/agent.d.ts

@@ -0,0 +1,24 @@
+import { type TestReport } from "./report.js";
+export interface AgentOptions {
+    session?: string;
+    systemPrompt?: string;
+}
+export interface AgentRunResult {
+    report: TestReport;
+    text: string;
+    json: string;
+    transcript: string;
+}
+interface Scenario {
+    name: string;
+    body: string;
+}
+/**
+ * 用 pi-agent-core 编排一次自然语言页面测试：注入 bsk 工具，驱动浏览器执行，整理报告。
+ */
+export declare function runAgent(input: string, opts?: AgentOptions): Promise<AgentRunResult>;
+/** 把一个脚本拆分为多个场景（按 `## ` 二级标题分隔）。无标题则整体作为一个场景。 */
+export declare function splitScenarios(script: string): Scenario[];
+/** 批量运行多个场景并汇总报告。任一失败则整体失败。 */
+export declare function runSuite(script: string, opts?: AgentOptions): Promise<AgentRunResult>;
+export {};

package/dist/agent.js

@@ -0,0 +1,157 @@
+import { Agent } from "@earendil-works/pi-agent-core";
+import { createLlmBackend } from "./llm.js";
+import { createBskTools, ensureSession } from "./bsk/tools.js";
+import { buildReport } from "./report.js";
+const DEFAULT_SYSTEM_PROMPT = [
+    "你是「页面测试 agent」。你根据用户的自然语言测试意图，驱动浏览器完成端到端测试。",
+    "",
+    "可用工具：",
+    "- navigate(url): 打开网页",
+    "- snapshot(): 读取页面 aria 树与可见文本（标题、段落、链接、按钮等），并定位元素",
+    "- click(target) / fill(target, value) / hover(target): 元素交互，target 用 @eN 引用或 CSS 选择器",
+    "- scroll(target) / wait(ms): 滚动与等待",
+    "- assert_text(expectation): 断言页面是否包含某文本，返回「成立/不成立」与证据",
+    "",
+    "工作流程：",
+    "1. 若需要打开页面，先 navigate。",
+    "2. 用 snapshot 读取当前内容并定位要操作的元素。",
+    "3. 按用户意图逐步交互；每次交互后如需要可再次 snapshot 确认状态。",
+    "4. 用 assert_text 校验关键结果，或在 snapshot 基础上自行判断文本/标题是否匹配。",
+    "5. 最后用简洁中文给出结论：每个断言「成立/不成立」，并附证据（实际看到的标题或文本片段）。",
+    "6. 不要编造未观察到的内容；若元素不存在或断言失败，明确说明。",
+    "",
+    "只输出测试结论与证据，不要输出多余解释。",
+].join("\n");
+/**
+ * 用 pi-agent-core 编排一次自然语言页面测试：注入 bsk 工具，驱动浏览器执行，整理报告。
+ */
+export async function runAgent(input, opts = {}) {
+    const { models, model } = createLlmBackend();
+    const session = ensureSession(opts.session);
+    const tools = createBskTools({ session });
+    const events = [];
+    const agent = new Agent({
+        initialState: {
+            systemPrompt: opts.systemPrompt ?? DEFAULT_SYSTEM_PROMPT,
+            model,
+            tools,
+        },
+        streamFn: models.streamSimple.bind(models),
+    });
+    agent.subscribe((e) => {
+        if (e.type === "tool_execution_start")
+            events.push("[tool] " + e.toolName);
+        else if (e.type === "tool_execution_end")
+            events.push("[tool-ok] " + e.toolName);
+        else if (e.type === "message_update" && e.assistantMessageEvent?.type === "text_delta") {
+            events.push(e.assistantMessageEvent.delta);
+        }
+    });
+    await agent.prompt(input);
+    await agent.waitForIdle();
+    const transcript = events.join("");
+    const report = buildReport(input, transcript);
+    return {
+        report,
+        text: renderText(report),
+        json: JSON.stringify(report, null, 2),
+        transcript,
+    };
+}
+/** 把一个脚本拆分为多个场景（按 `## ` 二级标题分隔）。无标题则整体作为一个场景。 */
+export function splitScenarios(script) {
+    const lines = script.split(/\r?\n/);
+    const collected = [];
+    let currentName = "";
+    let currentLines = [];
+    let inScenario = false;
+    const flush = () => {
+        if (!inScenario)
+            return;
+        const body = currentLines.join("\n").trim();
+        if (body.length > 0)
+            collected.push({ name: currentName || "场景 1", body });
+        currentLines = [];
+    };
+    for (const line of lines) {
+        const m = line.match(/^##\s+(.*)$/);
+        if (m) {
+            flush();
+            inScenario = true;
+            currentName = m[1].trim();
+        }
+        else if (inScenario) {
+            currentLines.push(line);
+        }
+        // 一级标题(#)与##之前的开场说明文字：不计入任何场景
+    }
+    flush();
+    return collected.length ? collected : [{ name: "场景 1", body: script.trim() }];
+}
+/** 批量运行多个场景并汇总报告。任一失败则整体失败。 */
+export async function runSuite(script, opts = {}) {
+    const scenarios = splitScenarios(script);
+    const results = [];
+    for (const sc of scenarios) {
+        const r = await runAgent(sc.body, { ...opts, systemPrompt: undefined });
+        results.push(r);
+    }
+    const overall = results.every((r) => r.report.status === "pass") ? "pass" : "fail";
+    const summary = {
+        status: overall,
+        assertions: results.flatMap((r, i) => r.report.assertions.map((a) => ({
+            ...a,
+            expectation: "[" + (scenarios[i]?.name ?? String(i + 1)) + "] " + a.expectation,
+        }))),
+        summary: "共 " + results.length + " 个场景，通过 " +
+            results.filter((r) => r.report.status === "pass").length + " 个",
+        transcript: results
+            .map((r, i) => "## " + (scenarios[i]?.name ?? String(i + 1)) + "\n" + r.transcript.trim())
+            .join("\n\n"),
+    };
+    return {
+        report: summary,
+        text: renderSuiteText(summary, results, scenarios),
+        json: JSON.stringify(summary, null, 2),
+        transcript: summary.transcript,
+    };
+}
+function verdictTag(v) {
+    return v === "pass" ? "PASS" : "FAIL";
+}
+function assertionLine(a) {
+    const ev = a.evidence ? " (" + a.evidence + ")" : "";
+    return "  - [" + verdictTag(a.verdict) + "] " + a.expectation + ev;
+}
+function renderText(r) {
+    const lines = [];
+    lines.push("=== 页面测试报告 ===");
+    lines.push("结论: " + (r.status === "pass" ? "PASS" : "FAIL"));
+    lines.push("断言数: " + r.assertions.length);
+    for (const a of r.assertions)
+        lines.push(assertionLine(a));
+    if (r.summary)
+        lines.push("摘要: " + r.summary);
+    lines.push("---");
+    lines.push(r.transcript.trim());
+    return lines.join("\n");
+}
+function renderSuiteText(summary, results, scenarios) {
+    const lines = [];
+    lines.push("=== 页面测试套件报告 ===");
+    lines.push("整体结论: " + (summary.status === "pass" ? "PASS" : "FAIL"));
+    lines.push("场景数: " + results.length);
+    results.forEach((r, i) => {
+        lines.push("");
+        lines.push("--- 场景 " + (i + 1) + "：" + (scenarios[i]?.name ?? "") +
+            " [" + (r.report.status === "pass" ? "PASS" : "FAIL") + "] ---");
+        for (const a of r.report.assertions)
+            lines.push(assertionLine(a));
+        if (r.report.summary)
+            lines.push("  摘要: " + r.report.summary);
+    });
+    lines.push("");
+    lines.push("汇总: " + summary.summary);
+    return lines.join("\n");
+}
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

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

package/dist/bsk/tools.d.ts

@@ -0,0 +1,8 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+export interface BskToolOptions {
+    session: string;
+}
+/** 构造一组浏览器操作工具，供 page-test agent 调用。 */
+export declare function createBskTools(opts: BskToolOptions): AgentTool[];
+/** 创建一个 bsk session；若已提供且仍在活跃列表中则复用，否则新建。 */
+export declare function ensureSession(existing?: string): string;

package/dist/bsk/tools.js

@@ -0,0 +1,172 @@
+import { execFileSync } from "node:child_process";
+/**
+ * browserskill（`bsk`）工具层：把 bsk CLI 命令包装成 pi-agent-core 的 AgentTool。
+ *
+ * bsk 连接一个已运行的真实浏览器，每个命令都需要 --session <id>。
+ * 所有命令以 --quiet 抑制进度输出，仅返回结构化/可读结果。
+ */
+function bsk(args) {
+    return execFileSync("bsk", args, { encoding: "utf-8" }).toString();
+}
+/** 构造 AgentTool 标准的成功返回（含必填 details 字段）。 */
+function ok(text) {
+    return { content: [{ type: "text", text }], details: {} };
+}
+/** 构造一组浏览器操作工具，供 page-test agent 调用。 */
+export function createBskTools(opts) {
+    const s = opts.session;
+    const quiet = ["--session", s, "--quiet"];
+    const navigate = {
+        name: "navigate",
+        label: "Navigate",
+        description: "在浏览器标签页打开一个 URL（支持 http/https/about: 等）。导航完成后页面 DOM 就绪。",
+        parameters: {
+            type: "object",
+            properties: { url: { type: "string", description: "目标 URL" } },
+            required: ["url"],
+        },
+        execute: async (_id, params) => {
+            const p = params;
+            const out = bsk(["navigate", p.url, ...quiet, "--wait-until", "domcontentloaded"]);
+            return ok(`已导航到 ${p.url}\n${out}`);
+        },
+    };
+    const snapshot = {
+        name: "snapshot",
+        label: "Snapshot",
+        description: "读取当前页面的 aria 语义树与可见文本（标题、段落、链接、按钮等）。用于读取内容、标题、文本并定位元素。",
+        parameters: { type: "object", properties: {} },
+        execute: async () => ok(bsk(["snapshot", ...quiet])),
+    };
+    const click = {
+        name: "click",
+        label: "Click",
+        description: "点击一个元素。可用快照里的 @eN 引用或 CSS 选择器。",
+        parameters: {
+            type: "object",
+            properties: { target: { type: "string", description: "@eN 引用或 CSS 选择器" } },
+            required: ["target"],
+        },
+        execute: async (_id, params) => {
+            const p = params;
+            const out = bsk(["click", p.target, ...quiet]);
+            return ok(`已点击 ${p.target}\n${out}`);
+        },
+    };
+    const fill = {
+        name: "fill",
+        label: "Fill",
+        description: "在输入框/文本域中填入文本（会先清空原有内容）。",
+        parameters: {
+            type: "object",
+            properties: {
+                target: { type: "string", description: "@eN 引用或 CSS 选择器" },
+                value: { type: "string", description: "要输入的文本" },
+            },
+            required: ["target", "value"],
+        },
+        execute: async (_id, params) => {
+            const p = params;
+            const out = bsk(["fill", p.target, "--value", p.value, ...quiet]);
+            return ok(`已在 ${p.target} 填入文本\n${out}`);
+        },
+    };
+    const hover = {
+        name: "hover",
+        label: "Hover",
+        description: "悬停在一个元素上，用于触发悬停菜单/提示。",
+        parameters: {
+            type: "object",
+            properties: { target: { type: "string", description: "@eN 引用或 CSS 选择器" } },
+            required: ["target"],
+        },
+        execute: async (_id, params) => {
+            const p = params;
+            const out = bsk(["hover", p.target, ...quiet]);
+            return ok(`已悬停 ${p.target}\n${out}`);
+        },
+    };
+    const scroll = {
+        name: "scroll",
+        label: "Scroll",
+        description: "滚动到指定元素使其进入视口。",
+        parameters: {
+            type: "object",
+            properties: { target: { type: "string", description: "@eN 引用或 CSS 选择器" } },
+            required: ["target"],
+        },
+        execute: async (_id, params) => {
+            const p = params;
+            const js = `(() => { const el = document.querySelector(${JSON.stringify(p.target)}); if (el) el.scrollIntoView({block:'center'}); return el ? 'scrolled' : 'element-not-found'; })()`;
+            const res = bsk(["evaluate", js, ...quiet]);
+            return ok(res);
+        },
+    };
+    const wait = {
+        name: "wait",
+        label: "Wait",
+        description: "等待一段时间（毫秒）或等待页面导航完成。",
+        parameters: {
+            type: "object",
+            properties: { ms: { type: "number", description: "等待毫秒数" } },
+            required: [],
+        },
+        execute: async (_id, params) => {
+            const p = params ?? {};
+            const ms = p.ms ?? 1000;
+            // wait-ms 是 daemon 端 sleep，不接受 --session
+            bsk(["wait-ms", String(ms)]);
+            return ok(`已等待 ${ms}ms`);
+        },
+    };
+    const assertText = {
+        name: "assert_text",
+        label: "Assert Text",
+        description: "断言当前页面是否包含指定文本。返回「成立」或「不成立」并附上证据（命中片段）。用于校验测试结果。",
+        parameters: {
+            type: "object",
+            properties: { expectation: { type: "string", description: "期望在页面中出现的文本" } },
+            required: ["expectation"],
+        },
+        execute: async (_id, params) => {
+            const p = params;
+            const snap = bsk(["snapshot", ...quiet]);
+            const hit = snap.includes(p.expectation);
+            const verdict = hit ? "成立" : "不成立";
+            const evidence = hit ? `页面中包含「${p.expectation}」` : `页面中未找到「${p.expectation}」`;
+            return ok(`断言「${p.expectation}」：${verdict}。${evidence}`);
+        },
+    };
+    return [navigate, snapshot, click, fill, hover, scroll, wait, assertText];
+}
+/** 创建一个 bsk session；若已提供且仍在活跃列表中则复用，否则新建。 */
+export function ensureSession(existing) {
+    if (existing && isActiveSession(existing))
+        return existing;
+    const out = bsk(["session", "start", "--json"]);
+    try {
+        const json = JSON.parse(out);
+        if (json?.session_id)
+            return json.session_id;
+    }
+    catch {
+        const m = out.match(/session_id["\s:]+([a-z0-9]+)/i);
+        if (m)
+            return m[1];
+    }
+    throw new Error("无法创建 bsk session，请确认 bsk daemon 已连接浏览器。");
+}
+/** 检查给定 session 是否在 bsk 活跃列表里。 */
+function isActiveSession(id) {
+    try {
+        const out = bsk(["session", "list", "--json"]);
+        const list = JSON.parse(out);
+        if (Array.isArray(list))
+            return list.some((s) => s?.session_id === id);
+    }
+    catch {
+        // 忽略解析错误
+    }
+    return false;
+}
+//# sourceMappingURL=tools.js.map

package/dist/bsk/tools.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 用户级配置：在用户主目录下创建配置目录与文件，持久化 LLM 后端设置。
+ *
+ * 配置目录：~/.pageqa（Windows 为 %USERPROFILE%/.pageqa）
+ * 配置文件：config.json，字段：
+ *   - baseUrl: 反代/兼容 OpenAI 的 base URL
+ *   - apiKey:  访问密钥
+ *   - model:   模型 ID
+ *
+ * 优先级（高 -> 低）：
+ *   环境变量 PAGEQA_LLM_*  >  用户配置文件  >  内置默认值
+ *
+ * 首次运行（配置文件不存在）会自动创建带默认值的配置文件，便于用户日后修改。
+ */
+export interface PageQaConfig {
+    baseUrl: string;
+    apiKey: string;
+    model: string;
+}
+export declare const CONFIG_DIR: string;
+export declare const CONFIG_PATH: string;
+/** 读取配置：合并 默认值 < 用户文件 < 环境变量。返回最终生效配置。 */
+export declare function loadConfig(): PageQaConfig;
+/** 确保配置目录存在（首次运行时创建 ~/.pageqa）。 */
+export declare function ensureConfigDir(): string;
+/** 平台无关地展示用户配置目录（便于 README/帮助说明）。 */
+export declare function describeConfigLocation(): string;

package/dist/config.js

@@ -0,0 +1,53 @@
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+const DEFAULTS = {
+    baseUrl: "http://127.0.0.1:3000/v1",
+    apiKey: "codebuddy-proxy-key",
+    model: "hunyuan-2.0-instruct",
+};
+export const CONFIG_DIR = join(homedir(), ".pageqa");
+export const CONFIG_PATH = join(CONFIG_DIR, "config.json");
+/** 读取配置：合并 默认值 < 用户文件 < 环境变量。返回最终生效配置。 */
+export function loadConfig() {
+    const fromFile = readConfigFile();
+    return {
+        baseUrl: process.env.PAGEQA_LLM_BASE_URL ?? fromFile.baseUrl ?? DEFAULTS.baseUrl,
+        apiKey: process.env.PAGEQA_LLM_API_KEY ?? fromFile.apiKey ?? DEFAULTS.apiKey,
+        model: process.env.PAGEQA_LLM_MODEL ?? fromFile.model ?? DEFAULTS.model,
+    };
+}
+/** 读取用户配置文件；不存在则创建默认文件并返回默认值。 */
+function readConfigFile() {
+    if (!existsSync(CONFIG_PATH)) {
+        ensureConfigDir();
+        writeFileSync(CONFIG_PATH, JSON.stringify(DEFAULTS, null, 2), "utf8");
+        return { ...DEFAULTS };
+    }
+    try {
+        const raw = readFileSync(CONFIG_PATH, "utf8");
+        const parsed = JSON.parse(raw);
+        return {
+            baseUrl: parsed.baseUrl ?? DEFAULTS.baseUrl,
+            apiKey: parsed.apiKey ?? DEFAULTS.apiKey,
+            model: parsed.model ?? DEFAULTS.model,
+        };
+    }
+    catch {
+        return { ...DEFAULTS };
+    }
+}
+/** 确保配置目录存在（首次运行时创建 ~/.pageqa）。 */
+export function ensureConfigDir() {
+    if (!existsSync(CONFIG_DIR)) {
+        mkdirSync(CONFIG_DIR, { recursive: true });
+    }
+    return CONFIG_DIR;
+}
+/** 平台无关地展示用户配置目录（便于 README/帮助说明）。 */
+export function describeConfigLocation() {
+    const home = homedir();
+    const tail = platform() === "win32" ? "%USERPROFILE%\\.pageqa" : "~/.pageqa";
+    return `${CONFIG_DIR} (${tail} → ${home})`;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAW,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAuB7E,MAAM,QAAQ,GAAiB;IAC7B,OAAO,EAAE,0BAA0B;IACnC,MAAM,EAAE,qBAAqB;IAC7B,KAAK,EAAE,sBAAsB;CAC9B,CAAC;AAEF,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC,CAAC;AACrD,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;AAE3D,0CAA0C;AAC1C,MAAM,UAAU,UAAU;IACxB,MAAM,QAAQ,GAAG,cAAc,EAAE,CAAC;IAClC,OAAO;QACL,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,QAAQ,CAAC,OAAO,IAAI,QAAQ,CAAC,OAAO;QAChF,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,MAAM;QAC5E,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,QAAQ,CAAC,KAAK,IAAI,QAAQ,CAAC,KAAK;KACxE,CAAC;AACJ,CAAC;AAED,iCAAiC;AACjC,SAAS,cAAc;IACrB,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QAC7B,eAAe,EAAE,CAAC;QAClB,aAAa,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;QACtE,OAAO,EAAE,GAAG,QAAQ,EAAE,CAAC;IACzB,CAAC;IACD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;QAC9C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAA0B,CAAC;QACxD,OAAO;YACL,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,QAAQ,CAAC,OAAO;YAC3C,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,QAAQ,CAAC,MAAM;YACxC,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,QAAQ,CAAC,KAAK;SACtC,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,GAAG,QAAQ,EAAE,CAAC;IACzB,CAAC;AACH,CAAC;AAED,mCAAmC;AACnC,MAAM,UAAU,eAAe;IAC7B,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5B,SAAS,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,qCAAqC;AACrC,MAAM,UAAU,sBAAsB;IACpC,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IACvB,MAAM,IAAI,GAAG,QAAQ,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,wBAAwB,CAAC,CAAC,CAAC,WAAW,CAAC;IAC7E,OAAO,GAAG,UAAU,KAAK,IAAI,MAAM,IAAI,GAAG,CAAC;AAC7C,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { runAgent, runSuite } from "./agent.js";
+import { ensureConfigDir, CONFIG_PATH, loadConfig } from "./config.js";
+function parseArgs(argv) {
+    const args = { json: false, suite: false, initConfig: false, help: false };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        switch (a) {
+            case "-h":
+            case "--help":
+                args.help = true;
+                break;
+            case "--session":
+                args.session = argv[++i];
+                break;
+            case "--json":
+                args.json = true;
+                break;
+            case "--suite":
+                args.suite = true;
+                break;
+            case "--init-config":
+                args.initConfig = true;
+                break;
+            case "--out":
+                args.out = argv[++i];
+                break;
+            default:
+                if (!a.startsWith("-"))
+                    args.input = a;
+        }
+    }
+    return args;
+}
+const HELP = `pageqa - 自然语言驱动的页面测试工具（pi-agent-core + browserskill）
+
+用法:
+  pageqa [options] <input>
+
+  <input>          自然语言脚本文件(.md/.txt)，或用引号包裹的内联文本
+                  脚本中可用『## 场景名』分隔多个测试场景，自动批量运行
+
+选项:
+  --session <id>   指定已存在的 bsk session（默认自动创建）
+  --json           输出 JSON 报告
+  --suite          强制按多场景套件运行（即使只有一个场景）
+  --init-config    在用户目录创建/重置配置文件
+  --out <file>     将报告写入文件
+  -h, --help       显示帮助
+
+配置:
+  - 首次运行会在用户目录自动创建配置文件：~/.pageqa/config.json
+    （Windows: %USERPROFILE%\.pageqa\config.json）
+  - 可编辑该文件设置 baseUrl / apiKey / model
+  - 也可用环境变量覆盖（优先级高于配置文件）：
+      PAGEQA_LLM_BASE_URL / PAGEQA_LLM_API_KEY / PAGEQA_LLM_MODEL
+  - 运行 pageqa --init-config 可显式创建/重置配置文件
+
+前置:
+  - 已安装并启动 bsk daemon，且连接了一个浏览器（bsk session start）
+  - CodeBuddy 本地反代可用（默认 http://127.0.0.1:3000/v1，模型 hunyuan-2.0-instruct）
+
+示例:
+  pageqa --session ulao "打开 https://example.com 并断言标题包含 Example"
+  pageqa examples/smoke.md --json
+`;
+function readInput(input) {
+    if (!input.includes("\n") && (input.endsWith(".md") || input.endsWith(".txt"))) {
+        try {
+            return readFileSync(input, "utf8");
+        }
+        catch {
+            // 不是文件：视为内联文本
+        }
+    }
+    return input;
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help) {
+        process.stdout.write(HELP + "\n");
+        return 0;
+    }
+    if (args.initConfig) {
+        const dir = ensureConfigDir();
+        loadConfig(); // 触发配置文件创建
+        process.stdout.write(`配置文件已创建/确认：${CONFIG_PATH}\n目录：${dir}\n`);
+        process.stdout.write(`当前生效配置：${JSON.stringify(loadConfig(), null, 2)}\n`);
+        return 0;
+    }
+    if (!args.input) {
+        process.stdout.write(HELP + "\n");
+        return 1;
+    }
+    const input = readInput(args.input);
+    try {
+        const hasScenarios = /^##\s+/m.test(input);
+        const result = hasScenarios || args.suite
+            ? await runSuite(input, { session: args.session })
+            : await runAgent(input, { session: args.session });
+        const out = args.json ? result.json : result.text;
+        if (args.out) {
+            const { writeFileSync } = await import("node:fs");
+            writeFileSync(args.out, out + "\n");
+        }
+        process.stdout.write(out + "\n");
+        return result.report.status === "pass" ? 0 : 1;
+    }
+    catch (err) {
+        process.stderr.write(`执行失败: ${err instanceof Error ? err.stack : String(err)}\n`);
+        return 1;
+    }
+}
+main()
+    .then((code) => process.exit(code))
+    .catch((err) => {
+    process.stderr.write(`执行失败: ${err instanceof Error ? err.stack : String(err)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/llm.d.ts

@@ -0,0 +1,6 @@
+import { createModels, type Model, type Api } from "@earendil-works/pi-ai";
+export interface LlmBackend {
+    models: ReturnType<typeof createModels>;
+    model: Model<Api>;
+}
+export declare function createLlmBackend(): LlmBackend;

package/dist/llm.js

@@ -0,0 +1,62 @@
+import { createModels, createProvider } from "@earendil-works/pi-ai";
+import * as openaiCompletions from "@earendil-works/pi-ai/api/openai-completions";
+import { loadConfig } from "./config.js";
+/**
+ * LLM 后端：基于 @earendil-works/pi-ai 构造一个指向 CodeBuddy 本地反代的自定义 provider。
+ *
+ * 配置优先级（高 -> 低）：环境变量 PAGEQA_LLM_*  >  用户配置文件（~/.pageqa/config.json）  >  内置默认值。
+ * 首次运行会自动在用户主目录创建配置文件，便于用户修改模型/反代地址/密钥。
+ */
+const PROVIDER_ID = "codebuddy";
+const MODELS = [
+    { id: "hunyuan-2.0-instruct", name: "Hunyuan 2.0 Instruct", contextWindow: 32000, maxOutput: 64000 },
+    { id: "hy3", name: "Hy3", contextWindow: 192000, maxOutput: 64000 },
+    { id: "deepseek-v4.1-flash", name: "Deepseek-V4.1-Flash", contextWindow: 1_000_000, maxOutput: 128_000 },
+];
+/** 构造一个静态解析的 ApiKeyAuth（避免交互式 env 探测）。 */
+function staticApiKeyAuth(apiKey, baseUrl) {
+    return {
+        name: "CodeBuddy Proxy",
+        resolve: async () => ({ auth: { apiKey, baseUrl }, source: "static" }),
+    };
+}
+export function createLlmBackend() {
+    const cfg = loadConfig();
+    const DEFAULT_BASE_URL = cfg.baseUrl;
+    const DEFAULT_API_KEY = cfg.apiKey;
+    const DEFAULT_MODEL = cfg.model;
+    const models = createModels();
+    const provider = createProvider({
+        id: PROVIDER_ID,
+        name: "CodeBuddy (本地反代)",
+        auth: { apiKey: staticApiKeyAuth(DEFAULT_API_KEY, DEFAULT_BASE_URL) },
+        models: MODELS.map((m) => ({
+            id: m.id,
+            name: m.name,
+            api: "openai-completions",
+            provider: PROVIDER_ID,
+            baseUrl: DEFAULT_BASE_URL,
+            input: ["text"],
+            reasoning: false,
+            contextWindow: m.contextWindow,
+            maxTokens: m.maxOutput,
+            maxOutput: m.maxOutput,
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            compat: {
+                supportsStore: false,
+                supportsDeveloperRole: false,
+                supportsReasoningEffort: false,
+                maxTokensField: "max_tokens",
+                supportsLongCacheRetention: false,
+            },
+        })),
+        api: openaiCompletions,
+    });
+    models.setProvider(provider);
+    const model = models.getModel(PROVIDER_ID, DEFAULT_MODEL);
+    if (!model) {
+        throw new Error(`未找到模型 ${DEFAULT_MODEL}（provider=${PROVIDER_ID}）。请确认 CodeBuddy 反代可用。`);
+    }
+    return { models, model };
+}
+//# sourceMappingURL=llm.js.map

package/dist/llm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm.js","sourceRoot":"","sources":["../src/llm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,cAAc,EAAwB,MAAM,uBAAuB,CAAC;AAC3F,OAAO,KAAK,iBAAiB,MAAM,8CAA8C,CAAC;AAClF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;GAKG;AAEH,MAAM,WAAW,GAAG,WAAW,CAAC;AAShC,MAAM,MAAM,GAA2B;IACrC,EAAE,EAAE,EAAE,sBAAsB,EAAE,IAAI,EAAE,sBAAsB,EAAE,aAAa,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE;IACpG,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE;IACnE,EAAE,EAAE,EAAE,qBAAqB,EAAE,IAAI,EAAE,qBAAqB,EAAE,aAAa,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE;CACzG,CAAC;AAEF,0CAA0C;AAC1C,SAAS,gBAAgB,CAAC,MAAc,EAAE,OAAe;IACvD,OAAO;QACL,IAAI,EAAE,iBAAiB;QACvB,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;KACvE,CAAC;AACJ,CAAC;AAOD,MAAM,UAAU,gBAAgB;IAC9B,MAAM,GAAG,GAAG,UAAU,EAAE,CAAC;IACzB,MAAM,gBAAgB,GAAG,GAAG,CAAC,OAAO,CAAC;IACrC,MAAM,eAAe,GAAG,GAAG,CAAC,MAAM,CAAC;IACnC,MAAM,aAAa,GAAG,GAAG,CAAC,KAAK,CAAC;IAChC,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,QAAQ,GAAG,cAAc,CAAC;QAC9B,EAAE,EAAE,WAAW;QACf,IAAI,EAAE,kBAAkB;QACxB,IAAI,EAAE,EAAE,MAAM,EAAE,gBAAgB,CAAC,eAAe,EAAE,gBAAgB,CAAC,EAAE;QACrE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACzB,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,GAAG,EAAE,oBAAoB;YACzB,QAAQ,EAAE,WAAW;YACrB,OAAO,EAAE,gBAAgB;YACzB,KAAK,EAAE,CAAC,MAAM,CAAC;YACf,SAAS,EAAE,KAAK;YAChB,aAAa,EAAE,CAAC,CAAC,aAAa;YAC9B,SAAS,EAAE,CAAC,CAAC,SAAS;YACtB,SAAS,EAAE,CAAC,CAAC,SAAS;YACtB,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE;YAC1D,MAAM,EAAE;gBACN,aAAa,EAAE,KAAK;gBACpB,qBAAqB,EAAE,KAAK;gBAC5B,uBAAuB,EAAE,KAAK;gBAC9B,cAAc,EAAE,YAAY;gBAC5B,0BAA0B,EAAE,KAAK;aAClC;SACF,CAAC,CAAC;QACH,GAAG,EAAE,iBAAiB;KACvB,CAAC,CAAC;IACH,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;IAE7B,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC;IAC1D,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,SAAS,aAAa,aAAa,WAAW,uBAAuB,CAAC,CAAC;IACzF,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AAC3B,CAAC"}

package/dist/report.d.ts

@@ -0,0 +1,16 @@
+export interface AssertionResult {
+    expectation: string;
+    verdict: "pass" | "fail";
+    evidence?: string;
+}
+export interface TestReport {
+    status: "pass" | "fail";
+    assertions: AssertionResult[];
+    summary?: string;
+    transcript: string;
+}
+/**
+ * 从 agent 的结论文本中解析断言结果。agent 会以「成立/不成立」给出每个断言，
+ * 并用「断言「X」：成立。证据...」句式。无法解析时降级为基于 PASS/FAIL 关键字的整体判断。
+ */
+export declare function buildReport(input: string, transcript: string): TestReport;

package/dist/report.js

@@ -0,0 +1,41 @@
+/**
+ * 从 agent 的结论文本中解析断言结果。agent 会以「成立/不成立」给出每个断言，
+ * 并用「断言「X」：成立。证据...」句式。无法解析时降级为基于 PASS/FAIL 关键字的整体判断。
+ */
+export function buildReport(input, transcript) {
+    const assertions = parseAssertions(transcript);
+    let status;
+    if (assertions.length > 0) {
+        status = assertions.every((a) => a.verdict === "pass") ? "pass" : "fail";
+    }
+    else {
+        // 无结构化断言：依据关键字与「不成立/失败」判定
+        const lowered = transcript.toLowerCase();
+        const negative = /不成立|未找到|失败|不存在|not found|fail|missing/.test(transcript);
+        status = negative ? "fail" : "pass";
+    }
+    const summary = extractSummary(transcript);
+    return { status, assertions, summary, transcript };
+}
+function parseAssertions(text) {
+    const results = [];
+    // 匹配两种常见句式：
+    //   断言「X」：成立/不成立。证据...
+    //   断言「X」成立。证据...
+    const re = /断言[「"']?([^」"']+?)[""」]?\s*(?:[:：]\s*)?(成立|不成立)/g;
+    let m;
+    while ((m = re.exec(text)) !== null) {
+        const expectation = m[1].trim();
+        const verdict = m[2] === "成立" ? "pass" : "fail";
+        const after = text.slice(m.index + m[0].length).split("\n")[0].trim();
+        const evidence = after.startsWith("。") ? after.slice(1).trim() : after;
+        results.push({ expectation, verdict, evidence: evidence || undefined });
+    }
+    return results;
+}
+function extractSummary(text) {
+    // 取最后一段非空文本作为摘要
+    const paras = text.split("\n").map((l) => l.trim()).filter(Boolean);
+    return paras.at(-1) ?? "";
+}
+//# sourceMappingURL=report.js.map

package/dist/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../src/report.ts"],"names":[],"mappings":"AAaA;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa,EAAE,UAAkB;IAC3D,MAAM,UAAU,GAAG,eAAe,CAAC,UAAU,CAAC,CAAC;IAE/C,IAAI,MAAuB,CAAC;IAC5B,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;IAC3E,CAAC;SAAM,CAAC;QACN,0BAA0B;QAC1B,MAAM,OAAO,GAAG,UAAU,CAAC,WAAW,EAAE,CAAC;QACzC,MAAM,QAAQ,GAAG,uCAAuC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC1E,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;IACtC,CAAC;IAED,MAAM,OAAO,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;IAC3C,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;AACrD,CAAC;AAED,SAAS,eAAe,CAAC,IAAY;IACnC,MAAM,OAAO,GAAsB,EAAE,CAAC;IACtC,YAAY;IACZ,uBAAuB;IACvB,kBAAkB;IAClB,MAAM,EAAE,GAAG,kDAAkD,CAAC;IAC9D,IAAI,CAAyB,CAAC;IAC9B,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QACpC,MAAM,WAAW,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAChC,MAAM,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;QAChD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACtE,MAAM,QAAQ,GAAG,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;QACvE,OAAO,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,IAAI,SAAS,EAAE,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,cAAc,CAAC,IAAY;IAClC,gBAAgB;IAChB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACpE,OAAO,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AAC5B,CAAC"}

package/examples/smoke.md

@@ -0,0 +1,15 @@
+# 页面测试套件示例
+
+用 `## ` 分隔多个测试场景，CLI 会逐个运行并汇总整体结论与退出码。
+
+## A1 打开页面并断言标题
+打开 https://example.com 并断言标题包含 Example
+
+## A2 交互流程（点击链接 + 等待 + 断言）
+打开 https://example.com 。点击页面上的「Learn more」链接，等待页面加载，然后断言页面包含 'IANA'。
+
+## A3 失败场景（断言不存在文本）
+打开 https://example.com 并断言页面包含 'THIS_TEXT_SHOULD_NOT_EXIST_XYZ'
+
+> 说明：自然语言意图由 pi-agent-core 驱动的 agent 解析为浏览器操作步骤，并经 browserskill（bsk）连接真实浏览器执行。
+> 默认 LLM 后端为 CodeBuddy 本地反代（混元），无需官网 Key。

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "pageqa",
+  "version": "0.1.0",
+  "description": "用自然语言驱动的页面测试 agent：基于 pi-agent-core 编排 + browserskill 驱动真实浏览器，经 CodeBuddy 反代（混元）实现免 Key 自然语言测试。",
+  "type": "module",
+  "bin": {
+    "pageqa": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "pretest": "npm run build",
+    "test": "node --test tests/smoke.test.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "examples"
+  ],
+  "keywords": [
+    "page-qa",
+    "e2e",
+    "testing",
+    "agent",
+    "pi-agent-core",
+    "browserskill",
+    "bsk"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@earendil-works/pi-agent-core": "^0.85.1",
+    "@earendil-works/pi-ai": "^0.85.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.5.0"
+  }
+}