paseo-req-kit 1.12.1 → 1.13.0-beta.2

package/engine/src/ui-check-page.js

@@ -0,0 +1,208 @@
+// Runs inside the page being checked (req ui-check, or an agent's browser_evaluate): finds layout
+// problems a person would see, and lists the page's visible labels, as plain data. It must stay
+// one self-contained function: it is sent to the browser as text.
+// Input: { width, narrow, state } — state: show only [data-state="<state>"] (prototypes).
+(function reqKitUiCheck(input) {
+  const opts = input || {};
+  const doc = document;
+  const win = window;
+  if (opts.state) {
+    for (const el of doc.querySelectorAll("[data-state]")) {
+      if (el.getAttribute("data-state") !== opts.state) el.style.setProperty("display", "none", "important");
+    }
+  }
+  const W = win.innerWidth;
+  const H_DOC = Math.max(doc.documentElement.scrollHeight, doc.body ? doc.body.scrollHeight : 0);
+  const issues = [];
+  const add = (kind, el, detail) => issues.push({ kind, target: el ? describe(el) : null, detail });
+
+  function visible(el) {
+    if (!el.isConnected) return false;
+    const cs = win.getComputedStyle(el);
+    if (cs.display === "none" || cs.visibility === "hidden" || Number(cs.opacity) === 0) return false;
+    const r = el.getBoundingClientRect();
+    return r.width > 0 && r.height > 0;
+  }
+  function ownText(el) {
+    let t = "";
+    for (const n of el.childNodes) if (n.nodeType === 3) t += n.textContent;
+    return t.replace(/\s+/g, " ").trim();
+  }
+  function text(el) {
+    if (el.tagName === "INPUT" || el.tagName === "TEXTAREA") return el.value || el.getAttribute("placeholder") || "";
+    if (el.tagName === "IMG") return el.getAttribute("alt") || "";
+    return (el.innerText || el.textContent || "").replace(/\s+/g, " ").trim();
+  }
+  const KIND = { BUTTON: "按钮", A: "链接", INPUT: "输入框", SELECT: "下拉框", TEXTAREA: "多行输入框", IMG: "图片", TABLE: "表格", TH: "表头", TD: "单元格", LABEL: "标签", LI: "列表项", H1: "标题", H2: "标题", H3: "标题", H4: "小标题", H5: "小标题", H6: "小标题", P: "文字", SPAN: "文字" };
+  function describe(el) {
+    const role = el.getAttribute("role");
+    let kind = KIND[el.tagName] || (role === "button" ? "按钮" : "区域");
+    if (el.tagName === "INPUT" && /submit|button/.test(el.type)) kind = "按钮";
+    const r = el.getBoundingClientRect();
+    return {
+      kind,
+      text: text(el).slice(0, 60),
+      selector: cssPath(el),
+      box: { x: Math.round(r.left + win.scrollX), y: Math.round(r.top + win.scrollY), w: Math.round(r.width), h: Math.round(r.height) },
+    };
+  }
+  function cssPath(el) {
+    const parts = [];
+    for (let n = el; n && n.nodeType === 1 && n.tagName !== "HTML"; n = n.parentElement) {
+      if (n.id) {
+        parts.unshift("#" + CSS.escape(n.id));
+        break;
+      }
+      let p = n.tagName.toLowerCase();
+      const parent = n.parentElement;
+      if (parent) {
+        const same = Array.from(parent.children).filter((c) => c.tagName === n.tagName);
+        if (same.length > 1) p += ":nth-of-type(" + (same.indexOf(n) + 1) + ")";
+      }
+      parts.unshift(p);
+      if (n.tagName === "BODY") break;
+    }
+    return parts.join(" > ");
+  }
+  function rgb(c) {
+    const m = /rgba?\(([^)]+)\)/.exec(c || "");
+    if (!m) return null;
+    const v = m[1].split(/[\s,/]+/).filter(Boolean).map(Number);
+    return { r: v[0], g: v[1], b: v[2], a: v.length > 3 ? v[3] : 1 };
+  }
+  function hex(c) {
+    return c ? "#" + [c.r, c.g, c.b].map((x) => Math.round(x).toString(16).padStart(2, "0")).join("") : "";
+  }
+  function lum(c) {
+    const f = (x) => {
+      x /= 255;
+      return x <= 0.03928 ? x / 12.92 : Math.pow((x + 0.055) / 1.055, 2.4);
+    };
+    return 0.2126 * f(c.r) + 0.7152 * f(c.g) + 0.0722 * f(c.b);
+  }
+  /** The color behind an element, or null when an image or gradient is behind it. */
+  function backdrop(el) {
+    for (let n = el; n && n.nodeType === 1; n = n.parentElement) {
+      const cs = win.getComputedStyle(n);
+      if (cs.backgroundImage && cs.backgroundImage !== "none") return null;
+      const c = rgb(cs.backgroundColor);
+      if (c && c.a > 0.95) return c;
+      if (c && c.a > 0.05) return null;
+    }
+    return { r: 255, g: 255, b: 255, a: 1 };
+  }
+
+  const all = Array.from(doc.body ? doc.body.querySelectorAll("*") : []).filter((el) => !/^(SCRIPT|STYLE|NOSCRIPT|TEMPLATE|svg|path|BR)$/.test(el.tagName) && visible(el));
+  const interactive = all.filter((el) => /^(BUTTON|A|INPUT|SELECT|TEXTAREA|SUMMARY)$/.test(el.tagName) || ["button", "link", "tab", "checkbox", "switch", "menuitem"].includes(el.getAttribute("role")));
+  const leaves = all.filter((el) => ownText(el) || /^(IMG|INPUT|SELECT|TEXTAREA|BUTTON)$/.test(el.tagName));
+
+  // 1. Wider than the window: what sticks out on the right.
+  const docWidth = doc.documentElement.scrollWidth;
+  if (docWidth > W + 1) {
+    const out = all.filter((el) => el.getBoundingClientRect().right > W + 1 && !(el.parentElement && el.parentElement.getBoundingClientRect().right > W + 1 && el.parentElement !== doc.body));
+    out.slice(0, 5).forEach((el) => add("overflow", el, { overBy: Math.round(el.getBoundingClientRect().right - W) }));
+    if (out.length === 0) add("overflow", null, { overBy: docWidth - W });
+  }
+  // 2. Cut-off text (hidden overflow, ellipsis).
+  for (const el of leaves) {
+    if (!ownText(el)) continue;
+    const cs = win.getComputedStyle(el);
+    const clipsX = cs.overflowX !== "visible" || cs.textOverflow === "ellipsis";
+    const clipsY = cs.overflowY !== "visible";
+    if ((clipsX && el.scrollWidth > el.clientWidth + 1) || (clipsY && el.scrollHeight > el.clientHeight + 2 && cs.overflowY !== "auto" && cs.overflowY !== "scroll")) {
+      add("clipped", el, { shown: el.clientWidth, needed: el.scrollWidth });
+    }
+  }
+  // 3. Things on top of each other (neither inside the other).
+  const boxes = leaves.slice(0, 500).map((el) => ({ el, r: el.getBoundingClientRect() }));
+  let overlaps = 0;
+  for (let i = 0; i < boxes.length && overlaps < 10; i++) {
+    for (let j = i + 1; j < boxes.length && overlaps < 10; j++) {
+      const a = boxes[i];
+      const b = boxes[j];
+      if (a.el.contains(b.el) || b.el.contains(a.el)) continue;
+      const w = Math.min(a.r.right, b.r.right) - Math.max(a.r.left, b.r.left);
+      const h = Math.min(a.r.bottom, b.r.bottom) - Math.max(a.r.top, b.r.top);
+      if (w <= 2 || h <= 2) continue;
+      const smaller = Math.min(a.r.width * a.r.height, b.r.width * b.r.height);
+      if (w * h >= 0.3 * smaller) {
+        overlaps++;
+        add("overlap", a.el, { other: describe(b.el), area: { w: Math.round(w), h: Math.round(h) } });
+      }
+    }
+  }
+  // 4. Off the page on the left or top.
+  for (const el of leaves) {
+    const r = el.getBoundingClientRect();
+    if (r.right + win.scrollX < 2 || r.bottom + win.scrollY < 2) add("offscreen", el, {});
+  }
+  // 5. Images that did not load.
+  for (const img of doc.querySelectorAll("img")) {
+    if (img.complete && img.naturalWidth === 0 && visible(img)) add("broken_image", img, { src: (img.getAttribute("src") || "").slice(0, 120) });
+  }
+  // 6. Too small to tap (narrow screens).
+  if (opts.narrow) {
+    for (const el of interactive) {
+      const r = el.getBoundingClientRect();
+      if (r.width < 24 || r.height < 24) add("small_target", el, { w: Math.round(r.width), h: Math.round(r.height) });
+    }
+  }
+  // 7. Text that is hard to read on its background.
+  let lowContrast = 0;
+  for (const el of leaves) {
+    if (lowContrast >= 10 || !ownText(el)) continue;
+    const cs = win.getComputedStyle(el);
+    const fg = rgb(cs.color);
+    const bg = backdrop(el);
+    if (!fg || !bg || fg.a < 0.5) continue;
+    const l1 = lum(fg);
+    const l2 = lum(bg);
+    const ratio = (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05);
+    const size = parseFloat(cs.fontSize);
+    // Only text that is clearly hard to read (WCAG asks 4.5:1; many component libraries' own
+    // buttons sit just under it, and reporting those would bury the real problems).
+    const large = size >= 24 || (size >= 18.6 && Number(cs.fontWeight) >= 700);
+    const need = large ? 2.5 : 3;
+    if (ratio < need && !el.closest("[disabled],[aria-disabled=true]")) {
+      lowContrast++;
+      add("low_contrast", el, { ratio: Math.round(ratio * 10) / 10, need, color: hex(fg), background: hex(bg) });
+    }
+  }
+  // 8. Controls nobody can name: inputs without a label, buttons without text.
+  for (const el of interactive) {
+    const named = el.getAttribute("aria-label") || el.getAttribute("aria-labelledby") || el.getAttribute("title");
+    if (/^(INPUT|SELECT|TEXTAREA)$/.test(el.tagName) && !/hidden|submit|button|image|reset/.test(el.type || "")) {
+      const before = el.previousElementSibling;
+      const labelled =
+        named ||
+        el.getAttribute("placeholder") ||
+        el.closest("label") ||
+        (el.id && doc.querySelector('label[for="' + CSS.escape(el.id) + '"]')) ||
+        (before && /^(LABEL|SPAN)$/.test(before.tagName) && text(before));
+      if (!labelled) add("no_label", el, {});
+    } else if (!named && !text(el) && !el.querySelector("img[alt]:not([alt=''])")) {
+      add("no_name", el, {});
+    }
+  }
+
+  // The labels people read: titles, buttons, links, field names, table headers, hints in the
+  // marked regions. Sample data in table cells is left out (it differs from the real page).
+  const labels = [];
+  const seen = new Set();
+  const push = (t) => {
+    const v = (t || "").replace(/\s+/g, " ").trim();
+    if (v && v.length <= 80 && !seen.has(v) && !/^[\d\s.,:\-/%¥$]+$/.test(v)) {
+      seen.add(v);
+      labels.push(v);
+    }
+  };
+  for (const el of all) {
+    if (/^(H1|H2|H3|H4|H5|H6|BUTTON|A|LABEL|TH|LEGEND|SUMMARY|CAPTION|OPTION)$/.test(el.tagName) || ["button", "tab", "link", "menuitem", "heading"].includes(el.getAttribute("role"))) push(text(el));
+    if (el.getAttribute("placeholder")) push(el.getAttribute("placeholder"));
+    if (el.tagName === "INPUT" && /submit|button/.test(el.type)) push(el.value);
+    if (el.closest("[data-ac]") && !el.closest("td") && ownText(el)) push(ownText(el));
+  }
+  if (doc.title) push(doc.title);
+
+  return { width: W, height: H_DOC, title: doc.title, issues, labels };
+});

package/engine/src/ui-check.ts

@@ -0,0 +1,366 @@
+// `req ui-check` (1.13): checks a web page without looking at it. Opens the page in this machine's
+// Edge or Chrome (headless, through playwright-core; no browser download), at each width, and
+// reports in words what a person would notice: things cut off, on top of each other, sticking
+// out of the screen, images not loading, text too pale to read, controls without a name,
+// console errors and failed requests. With --prototype it also compares the page's labels
+// (titles, buttons, field names, table headers) with the confirmed prototype. Screenshots go to
+// files for people, not to the model: models with weak vision gain little from them and pay
+// for every image in tokens.
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { ENGINE_DIR, KIT_ROOT, kitHome } from "./locations.js";
+
+const PLAYWRIGHT_VERSION = "1.56.1";
+const PAGE_SCRIPT = path.join(ENGINE_DIR, "src", "ui-check-page.js");
+
+export interface Target {
+  kind: string;
+  text: string;
+  selector: string;
+  box: { x: number; y: number; w: number; h: number };
+}
+
+export interface Issue {
+  kind: "overflow" | "clipped" | "overlap" | "offscreen" | "broken_image" | "small_target" | "low_contrast" | "no_label" | "no_name";
+  target: Target | null;
+  detail: Record<string, unknown> & { other?: Target };
+}
+
+export interface PageFindings {
+  width: number;
+  height: number;
+  title: string;
+  issues: Issue[];
+  labels: string[];
+}
+
+/** The in-page check as a function expression (also what an agent passes to browser_evaluate). */
+export function pageScript(): string {
+  const src = fs.readFileSync(PAGE_SCRIPT, "utf8");
+  const start = src.indexOf("(function");
+  return src.slice(start).trim().replace(/;\s*$/, "");
+}
+
+// ---------------------------------------------------------------------------
+// Words
+
+const who = (t: Target | null | undefined) => (t ? `${t.kind}${t.text ? `"${t.text.slice(0, 30)}${t.text.length > 30 ? "…" : ""}"` : ""}` : "页面");
+
+export function issueText(i: Issue): string {
+  const d = i.detail;
+  switch (i.kind) {
+    case "overflow":
+      return `超出屏幕：${who(i.target)} 右边超出 ${d.overBy}px，会出现横向滚动条`;
+    case "clipped":
+      return `文字显示不全：${who(i.target)}（可见宽 ${d.shown}px，需要 ${d.needed}px）`;
+    case "overlap":
+      return `互相遮挡：${who(i.target)} 和 ${who(d.other)} 重叠了 ${(d.area as { w: number }).w}×${(d.area as { h: number }).h}px`;
+    case "offscreen":
+      return `跑到页面外：${who(i.target)} 在左边或上边看不到的地方`;
+    case "broken_image":
+      return `图片没有加载出来：${d.src || who(i.target)}`;
+    case "small_target":
+      return `太小不好点：${who(i.target)} 只有 ${d.w}×${d.h}px（手机上建议至少 24×24）`;
+    case "low_contrast":
+      return `文字太淡看不清：${who(i.target)}（${d.color} 在 ${d.background} 上，对比度 ${d.ratio}:1，至少要 ${d.need}:1）`;
+    case "no_label":
+      return `输入框没有名字：${who(i.target)} 旁边没有标签或提示文字`;
+    case "no_name":
+      return `按钮或链接没有文字：${who(i.target)}（只有图标时要有提示文字）`;
+    default:
+      return `${i.kind}：${who(i.target)}`;
+  }
+}
+
+/** Labels in the prototype and not on the page (and the other way round). */
+export function compareLabels(prototype: string[], page: string[]): { missing: string[]; extra: string[] } {
+  const norm = (s: string) => s.replace(/\s+/g, "").replace(/[：:]$/, "").toLowerCase();
+  const pageSet = new Set(page.map(norm));
+  const protoSet = new Set(prototype.map(norm));
+  return {
+    missing: prototype.filter((t) => !pageSet.has(norm(t))),
+    extra: page.filter((t) => !protoSet.has(norm(t))),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The browser
+
+interface Pw {
+  chromium: {
+    launch(o: Record<string, unknown>): Promise<{
+      newPage(o: Record<string, unknown>): Promise<PwPage>;
+      close(): Promise<void>;
+    }>;
+  };
+}
+interface PwPage {
+  goto(url: string, o?: Record<string, unknown>): Promise<unknown>;
+  evaluate<T>(src: string): Promise<T>;
+  screenshot(o: Record<string, unknown>): Promise<unknown>;
+  on(event: string, fn: (x: never) => void): void;
+  setViewportSize(s: { width: number; height: number }): Promise<void>;
+  waitForTimeout(ms: number): Promise<void>;
+  getByText(t: string, o?: Record<string, unknown>): { first(): { waitFor(o?: Record<string, unknown>): Promise<void> } };
+  locator(s: string): { first(): { click(): Promise<void>; fill(v: string): Promise<void>; selectOption(v: string): Promise<unknown>; press(k: string): Promise<void>; waitFor(o?: Record<string, unknown>): Promise<void> } };
+  close(): Promise<void>;
+}
+
+const toolsDir = (env: NodeJS.ProcessEnv) => path.join(kitHome(env), "tools");
+
+function tryRequire(from: string): Pw | null {
+  try {
+    return createRequire(path.join(from, "noop.js"))("playwright-core") as Pw;
+  } catch {
+    return null;
+  }
+}
+
+/** playwright-core: next to req-kit, in ~/.req-kit/tools, or installed there now (from the npm registry or mirror). */
+export function loadPlaywright(env: NodeJS.ProcessEnv = process.env, log: (s: string) => void = (s) => console.error(s)): Pw {
+  const found = tryRequire(KIT_ROOT) ?? tryRequire(toolsDir(env));
+  if (found) return found;
+  log(`第一次使用界面检查：安装 playwright-core@${PLAYWRIGHT_VERSION} 到 ${toolsDir(env)}（只装驱动，用本机的 Edge 或 Chrome，不下载浏览器）……`);
+  fs.mkdirSync(toolsDir(env), { recursive: true });
+  const windows = process.platform === "win32";
+  const r = spawnSync(windows ? "npm.cmd" : "npm", ["install", "--prefix", toolsDir(env), "--no-audit", "--no-fund", "--no-save", `playwright-core@${PLAYWRIGHT_VERSION}`], {
+    stdio: ["ignore", "inherit", "inherit"],
+    shell: windows,
+    env: { ...env, PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: "1" },
+    timeout: 600_000,
+  });
+  const loaded = r.status === 0 ? tryRequire(toolsDir(env)) : null;
+  if (!loaded) throw new Error(`没能安装 playwright-core（npm 退出码 ${r.status}）。请检查 npm 源（npm config get registry），或手动运行：npm install --prefix "${toolsDir(env)}" playwright-core@${PLAYWRIGHT_VERSION}`);
+  return loaded;
+}
+
+/** This machine's Edge or Chrome; REQ_KIT_BROWSER / --browser names a browser program directly. */
+export async function launchBrowser(pw: Pw, executable: string | null) {
+  const tries: Array<Record<string, unknown>> = executable ? [{ executablePath: executable }] : [{ channel: "msedge" }, { channel: "chrome" }, {}];
+  const errors: string[] = [];
+  for (const t of tries) {
+    try {
+      return await pw.chromium.launch({ headless: true, ...t });
+    } catch (error) {
+      errors.push(`${JSON.stringify(t)}：${(error as Error).message.split("\n")[0]}`);
+    }
+  }
+  throw new Error(`没有找到能用的浏览器（Edge 或 Chrome）。装好其中一个，或用 --browser <浏览器程序路径> 指定。\n${errors.join("\n")}`);
+}
+
+export interface Step {
+  goto?: string;
+  click?: string;
+  fill?: [string, string];
+  select?: [string, string];
+  press?: [string, string];
+  wait?: string;
+}
+
+async function runSteps(page: PwPage, steps: Step[]) {
+  for (const s of steps) {
+    if (s.goto) await page.goto(s.goto, { waitUntil: "load" });
+    else if (s.click) await page.locator(s.click).first().click();
+    else if (s.fill) await page.locator(s.fill[0]).first().fill(s.fill[1]);
+    else if (s.select) await page.locator(s.select[0]).first().selectOption(s.select[1]);
+    else if (s.press) await page.locator(s.press[0]).first().press(s.press[1]);
+    else if (s.wait) await page.locator(s.wait).first().waitFor({ timeout: 15_000 });
+    await page.waitForTimeout(150);
+  }
+}
+
+export interface CheckOptions {
+  url: string;
+  widths: number[];
+  prototype: string | null;
+  state: string | null;
+  steps: Step[];
+  shots: string | null;
+  browser: string | null;
+  env?: NodeJS.ProcessEnv;
+}
+
+export interface WidthReport {
+  width: number;
+  findings: PageFindings;
+  console: string[];
+  failedRequests: string[];
+  screenshot: string | null;
+}
+
+export interface CheckReport {
+  url: string;
+  widths: WidthReport[];
+  prototype: { file: string; state: string | null; missing: string[]; extra: string[] } | null;
+}
+
+export async function check(opts: CheckOptions): Promise<CheckReport> {
+  const env = opts.env ?? process.env;
+  const pw = loadPlaywright(env);
+  const browser = await launchBrowser(pw, opts.browser ?? env.REQ_KIT_BROWSER?.trim() ?? null);
+  const script = pageScript();
+  try {
+    const widths: WidthReport[] = [];
+    for (const width of opts.widths) {
+      const page = await browser.newPage({ viewport: { width, height: 900 } });
+      const consoleErrors: string[] = [];
+      const failed: string[] = [];
+      page.on("console", (m: { type(): string; text(): string }) => {
+        if (m.type() === "error") consoleErrors.push(m.text().slice(0, 300));
+      });
+      page.on("pageerror", (e: Error) => consoleErrors.push(e.message.slice(0, 300)));
+      page.on("requestfailed", (r: { method(): string; url(): string; failure(): { errorText: string } | null }) => failed.push(`${r.method()} ${r.url().slice(0, 160)}（${r.failure()?.errorText ?? "失败"}）`));
+      page.on("response", (r: { status(): number; request(): { method(): string }; url(): string }) => {
+        if (r.status() >= 400) failed.push(`${r.request().method()} ${r.url().slice(0, 160)} → ${r.status()}`);
+      });
+      await page.goto(opts.url, { waitUntil: "networkidle", timeout: 45_000 }).catch(async (e: Error) => {
+        if (!/Timeout/.test(e.message)) throw e;
+      });
+      await runSteps(page, opts.steps);
+      await page.waitForTimeout(300);
+      const findings = await page.evaluate<PageFindings>(`(${script})(${JSON.stringify({ width, narrow: width <= 480, state: null })})`);
+      let shot: string | null = null;
+      if (opts.shots) {
+        fs.mkdirSync(opts.shots, { recursive: true });
+        const u = new URL(opts.url);
+        const last = (u.protocol === "file:" ? path.basename(u.pathname).replace(/\.html?$/i, "") : u.pathname.split("/").filter(Boolean).slice(-2).join("-")) || "page";
+        const name = `${last.replace(/[^a-zA-Z0-9\u4e00-\u9fa5_-]+/g, "-").slice(0, 60)}-${width}.png`;
+        shot = path.join(opts.shots, name);
+        await page.screenshot({ path: shot, fullPage: true });
+      }
+      widths.push({ width, findings, console: [...new Set(consoleErrors)], failedRequests: [...new Set(failed)], screenshot: shot });
+      await page.close();
+    }
+    let prototype: CheckReport["prototype"] = null;
+    if (opts.prototype) {
+      // The prototype's own scripts (there should be none) are dropped; the check needs JavaScript.
+      const p2 = await browser.newPage({ viewport: { width: opts.widths[0] ?? 1280, height: 900 } });
+      const html = fs.readFileSync(opts.prototype, "utf8").replace(/<script\b[\s\S]*?<\/script>/gi, "");
+      await p2.goto("about:blank");
+      await p2.evaluate(`document.open(); document.write(${JSON.stringify(html)}); document.close();`);
+      const protoFindings = await p2.evaluate<PageFindings>(`(${script})(${JSON.stringify({ width: opts.widths[0] ?? 1280, narrow: false, state: opts.state })})`);
+      await p2.close();
+      const pageLabels = [...new Set(widths.flatMap((w) => w.findings.labels))];
+      const { missing, extra } = compareLabels(protoFindings.labels, pageLabels);
+      prototype = { file: opts.prototype, state: opts.state, missing, extra };
+    }
+    return { url: opts.url, widths, prototype };
+  } finally {
+    await browser.close();
+  }
+}
+
+const WIDTH_NAME: Record<number, string> = { 1280: "电脑", 1440: "电脑", 1920: "大屏", 768: "平板", 390: "手机", 375: "手机", 414: "手机" };
+
+export function reportText(r: CheckReport): { text: string; problems: number } {
+  const out: string[] = [];
+  let problems = 0;
+  for (const w of r.widths) {
+    out.push(`## ${WIDTH_NAME[w.width] ?? ""}宽度 ${w.width}px：${r.url}`);
+    out.push(`页面标题：${w.findings.title || "（无）"}；页面高度 ${w.findings.height}px`);
+    if (w.console.length) {
+      problems += w.console.length;
+      out.push(`控制台报错（${w.console.length}）：`, ...w.console.slice(0, 10).map((c) => `- ${c}`));
+    }
+    if (w.failedRequests.length) {
+      problems += w.failedRequests.length;
+      out.push(`请求失败（${w.failedRequests.length}）：`, ...w.failedRequests.slice(0, 10).map((c) => `- ${c}`));
+    }
+    if (w.findings.issues.length) {
+      problems += w.findings.issues.length;
+      out.push(`版面问题（${w.findings.issues.length}）：`, ...w.findings.issues.slice(0, 30).map((i) => `- ${issueText(i)}${i.target ? `  [${i.target.selector}]` : ""}`));
+    } else out.push("版面问题：没有发现");
+    if (w.screenshot) out.push(`截图（给人看）：${w.screenshot}`);
+    out.push("");
+  }
+  if (r.prototype) {
+    const p = r.prototype;
+    out.push(`## 和原型对文字：${p.file}${p.state ? `，状态"${p.state}"` : ""}`);
+    if (p.missing.length) {
+      problems += p.missing.length;
+      out.push(`原型里有、页面上没有（${p.missing.length}）：${p.missing.slice(0, 30).map((t) => `"${t}"`).join("、")}`);
+    } else out.push("原型里的标题、按钮、字段名、表头在页面上都找到了。");
+    if (p.extra.length) out.push(`页面上有、原型里没有（多数是原型没画的部分，核对一下是否应该有）：${p.extra.slice(0, 20).map((t) => `"${t}"`).join("、")}`);
+    out.push("");
+  }
+  out.push(problems === 0 ? "结论：没有发现问题。" : `结论：发现 ${problems} 处需要核对的地方。逐条判断是不是真的问题（有的是故意的设计），是的按缺陷处理。`);
+  return { text: out.join("\n"), problems };
+}
+
+// ---------------------------------------------------------------------------
+// req ui-check <网址> [选项]
+
+const HELP = `用法：req ui-check <网址> [选项]
+
+不靠看图检查网页：用本机的 Edge 或 Chrome 打开页面，按每个宽度用文字报告看得出来的问题
+（文字显示不全、互相遮挡、超出屏幕、图片没加载、文字太淡、控件没有名字、控制台报错、请求失败）。
+
+  --width 1280,390          检查的宽度（默认电脑 1280 和手机 390）
+  --prototype <原型文件>    和确认过的原型对文字：标题、按钮、字段名、表头、提示语
+  --state <状态名>          原型中 data-state 的状态（如"空数据"），对文字时只看这个状态
+  --steps <文件.json>       打开后先做的操作，例如 [{"fill":["#keyword","手机"]},{"click":"text=查询"},{"wait":"text=共 3 条"}]
+  --shots <目录>            把整页截图存到这个目录（给人看；不要再把截图读给模型）
+  --browser <程序路径>      指定浏览器（默认找本机的 Edge，再找 Chrome；也可以设 REQ_KIT_BROWSER）
+  --json                    输出 JSON
+  --script                  只输出页面检查脚本（在 Paseo 浏览器的 browser_evaluate 中用）
+
+退出码：0 没有发现问题，1 发现需要核对的地方，2 没能检查（打不开页面、没有浏览器等）。`;
+
+function option(argv: string[], name: string): string | null {
+  const i = argv.findIndex((a) => a === name || a.startsWith(`${name}=`));
+  if (i < 0) return null;
+  const a = argv[i];
+  return a.includes("=") ? a.slice(name.length + 1) : (argv[i + 1] ?? null);
+}
+
+async function main(argv: string[]): Promise<number> {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    console.log(HELP);
+    return 0;
+  }
+  if (argv.includes("--script")) {
+    console.log(pageScript());
+    return 0;
+  }
+  const valued = new Set(["--width", "--prototype", "--state", "--steps", "--shots", "--browser"]);
+  const url = argv.find((a, i) => !a.startsWith("--") && !valued.has(argv[i - 1] ?? ""));
+  if (!url) {
+    console.error(HELP);
+    return 2;
+  }
+  const widths = (option(argv, "--width") ?? "1280,390")
+    .split(/[,，\s]+/)
+    .map(Number)
+    .filter((n) => Number.isInteger(n) && n >= 200 && n <= 4000);
+  const stepsFile = option(argv, "--steps");
+  const prototype = option(argv, "--prototype");
+  if (prototype && !fs.existsSync(prototype)) {
+    console.error(`没有这个原型文件：${prototype}`);
+    return 2;
+  }
+  const report = await check({
+    url: /^[a-z]+:\/\//i.test(url) ? url : fs.existsSync(url) ? pathToFileURL(path.resolve(url)).href : `http://${url}`,
+    widths: widths.length ? widths : [1280, 390],
+    prototype,
+    state: option(argv, "--state"),
+    steps: stepsFile ? (JSON.parse(fs.readFileSync(stepsFile, "utf8")) as Step[]) : [],
+    shots: option(argv, "--shots"),
+    browser: option(argv, "--browser"),
+  });
+  const { text, problems } = reportText(report);
+  console.log(argv.includes("--json") ? JSON.stringify(report, null, 2) : text);
+  return problems === 0 ? 0 : 1;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(import.meta.filename)) {
+  main(process.argv.slice(2)).then(
+    (code) => process.exit(code),
+    (error: Error) => {
+      console.error(`没能检查：${error.message}`);
+      process.exit(2);
+    },
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paseo-req-kit",
-  "version": "1.12.1",
+  "version": "1.13.0-beta.2",
   "description": "req-kit: a requirement-development workflow for Paseo. /req aligns a requirement in chat; the engine runs design, implementation, review and verification as Paseo agents.",
   "type": "module",
   "license": "MIT",
@@ -27,6 +27,7 @@
   "bin": {
     "req": "bin/req.mjs",
     "req-kit": "bin/req.mjs",
+    "paseo-req-kit": "bin/req.mjs",
     "start-pipeline": "bin/start-pipeline.mjs"
   },
   "scripts": {
@@ -57,6 +58,7 @@
     "docs/guide/",
     "docs/adr/",
     "install.mjs",
+    "site-dist/",
     "config.example.json",
     "CHANGELOG.md",
     "SCOPE.md",

package/paseo-plugin/client/data.ts

@@ -1,7 +1,7 @@
 // Data hooks: every read is an RPC to the daemon side (req api), cached by React Query.
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { useRpc, useSettings } from "@getpaseo/plugin/client";
-import { configRpc, fileRpc, listRpc, modelsRpc, preferences, runRpc, setAgentsRpc, statsRpc, statusRpc, versionRpc, type Action, type AgentProfileData } from "../shared/contracts";
+import { configRpc, fileRpc, listRpc, modelsRpc, preferences, reviewUrlRpc, runRpc, setAgentsRpc, statsRpc, statusRpc, versionRpc, type Action, type AgentProfileData } from "../shared/contracts";
 
 export function usePreferences(): { readOnly: boolean; refreshMs: number } {
   const settings = useSettings(preferences);
@@ -72,3 +72,14 @@ export function useConfigView(repo: string | null) {
   const config = useRpc(configRpc);
   return useQuery({ queryKey: ["req", "config", repo ?? ""], queryFn: () => config(repo ? { repo } : {}), retry: false });
 }
+
+/** The prototype review page's address (1.13); it stays valid while its server runs. */
+export function useReviewUrl(repo: string, featureDir: string, enabled: boolean) {
+  const reviewUrl = useRpc(reviewUrlRpc);
+  return useQuery({
+    queryKey: ["req", "review-url", repo, featureDir],
+    queryFn: () => reviewUrl({ repo, featureDir }),
+    enabled: enabled && Boolean(repo && featureDir),
+    retry: false,
+  });
+}

package/paseo-plugin/client/detail.tsx

@@ -9,6 +9,7 @@ import type { Action, RequirementDetail, Step } from "../shared/contracts";
 import { useAction, useDocument, usePreferences, useRequirement, useRequirements } from "./data";
 import { ACTION_TEXT, actionsFor, ago, ATTENTION_LABELS, facts, FILE_LABELS, minutes, tokens } from "./format";
 import { Markdown, tsvToMarkdown } from "./markdown";
+import { ReviewLink } from "./review-link";
 import { Badge, Button, Chip, Status, useStyles } from "./ui";
 
 type Theme = PluginHostProps["theme"];
@@ -192,6 +193,8 @@ export function RequirementView({
         </View>
       ) : null}
 
+      {d.hasPrototype ? <ReviewLink theme={theme} compact={layout.compact} repo={d.sourceRepo ?? d.repo} featureDir={d.featureDir} waiting={d.attention === "approval"} /> : null}
+
       {d.files.length > 0 ? (
         <View style={{ gap: 6 }}>
           <Text style={s.heading}>文档</Text>

package/paseo-plugin/client/inbox.tsx

@@ -8,6 +8,7 @@ import { Text, View } from "react-native";
 import type { Attention, Requirement } from "../shared/contracts";
 import { useAction, usePreferences } from "./data";
 import { facts } from "./format";
+import { ReviewLink } from "./review-link";
 import { Badge, Button, useStyles } from "./ui";
 
 type Theme = PluginHostProps["theme"];
@@ -98,6 +99,7 @@ function InboxCard({ theme, layout, item, open, readOnly }: { theme: Theme; layo
         </View>
       ) : (
         <>
+          {item.attention === "approval" && item.hasPrototype ? <ReviewLink theme={theme} compact={layout.compact} repo={repo} featureDir={item.featureDir} waiting /> : null}
           {writing && w?.canReply ? (
             <View style={{ gap: 8 }}>
               <TextInput