knowme-careerforge-skill 0.0.4 → 0.0.6

package/scripts/rendering/browser-engine.js

@@ -0,0 +1,366 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { pathToFileURL } = require('node:url');
+const { randomUUID, createHash } = require('node:crypto');
+
+const CHECKS = ['input', 'fonts', 'dom', 'pdf', 'text', 'output'];
+function resultFor(html, expectedPages) {
+  return { status: 'UNVERIFIED', file: path.resolve(html), expectedPages,
+    errors: [], warnings: [], checks: Object.fromEntries(CHECKS.map(k => [k, { status: 'UNVERIFIED' }])) };
+}
+function failure(result, check, message, status = 'FAIL') {
+  result.checks[check] = { ...result.checks[check], status };
+  result.errors.push(`${check}: ${message}`);
+}
+function finish(result) {
+  result.status = result.errors.length
+    ? (Object.values(result.checks).some(c => c.status === 'FAIL') ? 'FAIL' : 'UNVERIFIED')
+    : Object.values(result.checks).every(c => c.status === 'PASS') ? 'PASS' : 'UNVERIFIED';
+  return result;
+}
+
+// Executed in the print-media page. Never relax height/overflow constraints.
+function inspectDOM() {
+  const tolerance = 0.75;
+  const pages = [...document.querySelectorAll('.resume-page')];
+  const issues = [];
+  const unsupported = [];
+  const rect = r => ({ left: r.left, top: r.top, right: r.right, bottom: r.bottom, width: r.width, height: r.height });
+  const label = e => e.id ? `#${e.id}` : e.tagName.toLowerCase() + (e.classList.length ? '.' + [...e.classList].join('.') : '');
+  function visible(e) {
+    for (let a = e; a; a = a.parentElement) {
+      const s = getComputedStyle(a);
+      if (s.display === 'none' || Number(s.opacity) === 0) return false;
+    }
+    return getComputedStyle(e).visibility === 'visible';
+  }
+  const details = pages.map((p, i) => {
+    const bounds = p.getBoundingClientRect();
+    const pageIndex = i + 1;
+    if (!visible(p) || !bounds.width || !bounds.height) issues.push({ pageIndex, selector: label(p), reason: 'invisible/empty page' });
+    if (bounds.width > 210 * 96 / 25.4 + tolerance || bounds.height > 297 * 96 / 25.4 + tolerance)
+      issues.push({ pageIndex, selector: label(p), reason: 'page exceeds A4', bounds: rect(bounds) });
+    function check(r, e, isPage = false) {
+      const sides = [];
+      if (r.left < bounds.left - tolerance) sides.push('left');
+      if (r.top < bounds.top - tolerance) sides.push('top');
+      if (r.right > bounds.right + tolerance) sides.push('right');
+      if (r.bottom > bounds.bottom + tolerance) sides.push('bottom');
+      if (sides.length) issues.push({ pageIndex, selector: label(e), reason: 'page boundary', sides, bounds: rect(r) });
+      for (let a = isPage ? e.parentElement : e; a; a = a.parentElement) {
+        const s = getComputedStyle(a);
+        const b = a.getBoundingClientRect();
+        const left = b.left + a.clientLeft, top = b.top + a.clientTop;
+        const clipX = /hidden|clip|scroll|auto/.test(s.overflowX);
+        const clipY = /hidden|clip|scroll|auto/.test(s.overflowY);
+        const paint = /paint|strict|content/.test(s.contain);
+        if (((clipX || paint) && (r.left < left - tolerance || r.right > left + a.clientWidth + tolerance)) ||
+            ((clipY || paint) && (r.top < top - tolerance || r.bottom > top + a.clientHeight + tolerance)))
+          issues.push({ pageIndex, selector: label(e), ancestor: label(a), reason: 'ancestor clipping', bounds: rect(r) });
+        if (s.clipPath !== 'none' || (s.maskImage && s.maskImage !== 'none') || s.clip !== 'auto')
+          unsupported.push({ pageIndex, selector: label(a), reason: 'non-rectangular/legacy clipping requires visual verification' });
+      }
+    }
+    check(bounds, p, true);
+    const text = [];
+    for (const e of [p, ...p.querySelectorAll('*')]) {
+      if (/^(SCRIPT|STYLE|TEMPLATE|NOSCRIPT)$/.test(e.tagName)) continue;
+      if (!visible(e)) {
+        if ([...e.childNodes].some(node => node.nodeType === Node.TEXT_NODE && node.textContent.trim()))
+          issues.push({ pageIndex, selector: label(e), reason: 'Hidden nonempty body text in print media' });
+        continue;
+      }
+      if (e !== p) for (const r of e.getClientRects()) check(r, e.parentElement);
+      for (const node of e.childNodes) {
+        if (node.nodeType !== Node.TEXT_NODE || !node.textContent.trim()) continue;
+        const range = document.createRange();
+        range.selectNodeContents(node);
+        const rs = [...range.getClientRects()];
+        if (!rs.length) continue;
+        text.push(node.textContent);
+        for (const r of rs) check(r, e);
+      }
+    }
+    return { pageIndex, bounds: rect(bounds), text: text.join(' '), textFragments: text };
+  });
+  const names = [...document.querySelectorAll('h1.candidate-name')];
+  const validName = names.length === 1 && visible(names[0]) && names[0].getBoundingClientRect().width > 0 && names[0].getBoundingClientRect().height > 0 && !!names[0].innerText.replace(/[\s\u200b-\u200f\ufeff]/g, '') && !!names[0].closest('.resume-page');
+  if (!validName) issues.push({ reason: 'Require exactly one nonempty visible h1.candidate-name inside a resume page' });
+  const compact = text => text.replace(/\s/g, '');
+  const substantive = compact(details.map(p => p.text).join('')).replace(validName ? compact(names[0].innerText) : '', '');
+  if (substantive.length < 20) issues.push({ reason: 'Require at least 20 non-whitespace body characters beyond the name' });
+  const comments = document.createTreeWalker(document, NodeFilter.SHOW_COMMENT);
+  while (comments.nextNode()) {
+    if (/^\s*resume:/.test(comments.currentNode.data))
+      issues.push({ reason: 'Unbound canvas slot remains in the document' });
+  }
+  if (/\{\{\s*resume:language\s*\}\}/.test(document.documentElement.lang))
+    issues.push({ reason: 'Unbound canvas language slot' });
+  return { totalPagesFound: pages.length, pages: details, issues, unsupported, candidateName: validName ? names[0].innerText.trim() : null, bodyCharacters: substantive.length };
+}
+
+function normalized(text) {
+  return text.normalize('NFKC').replace(/[\s\u200b-\u200f\u202a-\u202e\u2060\ufeff\u00ad]/gu, '');
+}
+// Compare character multiplicities, tolerating PDF column/RTL extraction order only.
+function missingText(expected, actual) {
+  const counts = new Map();
+  for (const c of normalized(actual)) counts.set(c, (counts.get(c) || 0) + 1);
+  let missing = '';
+  for (const c of normalized(expected)) {
+    if ((counts.get(c) || 0) > 0) counts.set(c, counts.get(c) - 1);
+    else missing += c;
+  }
+  return missing;
+}
+
+const ladder = [
+  ...[10.5, 9.5, 8.5].map(n => ({ '--resume-space-section': `${n}pt` })),
+  ...[[7, 2.5], [6, 2], [5, 1.5]].map(([a, b]) => ({ '--resume-space-item': `${a}pt`, '--resume-space-bullet': `${b}pt` })),
+  ...[[9, 1.42], [8.8, 1.38]].map(([a, b]) => ({ '--resume-font-size-body': `${a}pt`, '--resume-line-height-body': `${b}` }))
+];
+// Only edit existing numeric root declarations, never insert or increase a token.
+function reduceTokens(html, targets) {
+  const tuned = {};
+  const content = html.replace(/(<style\b[^>]*>)([\s\S]*?)(<\/style>)/gi, (all, open, css, close) =>
+    open + css.replace(/(:root\s*\{)([^}]*)(\})/g, (block, start, body, end) => {
+      for (const [token, value] of Object.entries(targets)) {
+        const target = /^([\d.]+)(pt)?$/.exec(value);
+        body = body.replace(new RegExp(`(${token}\\s*:\\s*)([\\d.]+)(pt)?(\\s*;)`, 'g'), (decl, prefix, n, unit, semi) => {
+          if ((unit || '') !== (target[2] || '') || Number(n) <= Number(target[1])) return decl;
+          tuned[token] = value;
+          return prefix + value + semi;
+        });
+      }
+      return start + body + end;
+    }) + close);
+  return { content, tuned };
+}
+
+async function dependencies() {
+  let pw;
+  try { pw = require('playwright'); } catch { pw = require('playwright-core'); }
+  const { PDFDocument } = require('pdf-lib');
+  const pdfjs = await import('pdfjs-dist/legacy/build/pdf.mjs');
+  return { pw, PDFDocument, pdfjs };
+}
+
+async function systemBrowsers() {
+  const home = require('node:os').homedir();
+  const candidates = [
+    ...['/Applications', path.join(home, 'Applications')].flatMap(base => [
+      'Google Chrome.app/Contents/MacOS/Google Chrome', 'Chromium.app/Contents/MacOS/Chromium',
+      'Microsoft Edge.app/Contents/MacOS/Microsoft Edge', 'Brave Browser.app/Contents/MacOS/Brave Browser'
+    ].map(name => path.join(base, name))),
+    ...[process.env.PROGRAMFILES, process.env['PROGRAMFILES(X86)'], process.env.LOCALAPPDATA].filter(Boolean).flatMap(base => [
+      'Google/Chrome/Application/chrome.exe', 'Microsoft/Edge/Application/msedge.exe', 'BraveSoftware/Brave-Browser/Application/brave.exe'
+    ].map(name => path.join(base, name))),
+    ...(process.env.PATH || '').split(path.delimiter).filter(Boolean).flatMap(base =>
+      ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser', 'microsoft-edge', 'brave-browser'].map(name => path.join(base, name)))
+  ];
+  const found = [];
+  for (const candidate of new Set(candidates)) {
+    try { await fs.access(candidate, require('node:fs').constants.X_OK); found.push(candidate); } catch {}
+  }
+  return found;
+}
+async function launchBrowser(pw) {
+  const override = process.env.CHROME_BIN || process.env.BROWSER_PATH;
+  if (override) return pw.chromium.launch({ headless: true, executablePath: override });
+  const failures = [];
+  for (const executablePath of [undefined, ...await systemBrowsers()]) {
+    try { return await pw.chromium.launch({ headless: true, ...(executablePath ? { executablePath } : {}) }); }
+    catch (error) { failures.push(`${executablePath || 'bundled Chromium'}: ${error.message}`); }
+  }
+  throw new Error(`No usable browser: ${failures.join('\n')}`);
+}
+
+async function inspect(page, htmlFile, expectedPages, deps) {
+  const result = resultFor(htmlFile, expectedPages);
+  result.checks.input = { status: 'PASS' };
+  let phase = 'fonts';
+  const resourceErrors = [];
+  const onFailed = request => resourceErrors.push(request.url());
+  const onResponse = response => { if (response.status() >= 400) resourceErrors.push(response.url()); };
+  page.on('requestfailed', onFailed);
+  page.on('response', onResponse);
+  try {
+    await page.emulateMedia({ media: 'print' });
+    await page.goto(pathToFileURL(htmlFile).href, { waitUntil: 'networkidle', timeout: 30000 });
+    await page.evaluate(async () => {
+      await Promise.race([document.fonts.ready, new Promise((_, reject) => setTimeout(() => reject(new Error('Font wait timed out')), 15000))]);
+      if ([...document.fonts].some(f => f.status === 'error')) throw new Error('A font failed to load');
+      await Promise.all([...document.images].map(img => img.decode()));
+      await new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+    });
+    if (resourceErrors.length) throw new Error(`Resources failed to load: ${resourceErrors.join(', ')}`);
+    result.checks.fonts = { status: 'PASS' };
+    phase = 'dom';
+    const dom = await page.evaluate(inspectDOM);
+    result.checks.dom = { status: 'PASS', ...dom };
+    if (dom.totalPagesFound < 1 || dom.totalPagesFound > expectedPages) failure(result, 'dom', `Require 1–${expectedPages} explicit .resume-page containers, found ${dom.totalPagesFound}`);
+    if (dom.issues.length) failure(result, 'dom', `${dom.issues.length} boundary/clipping violations`);
+    if (dom.unsupported.length && !dom.issues.length) failure(result, 'dom', 'Unsupported clipping', 'UNVERIFIED');
+    phase = 'pdf';
+    const bytes = await page.pdf({ format: 'A4', preferCSSPageSize: true, printBackground: true,
+      displayHeaderFooter: false, margin: { top: 0, right: 0, bottom: 0, left: 0 } });
+    const pdf = await deps.PDFDocument.load(bytes);
+    const sizes = pdf.getPages().map((p, i) => ({ pageIndex: i + 1, ...p.getSize(), cropBox: p.getCropBox(), rotation: p.getRotation().angle }));
+    result.checks.pdf = { status: 'PASS', pageCount: sizes.length, pages: sizes };
+    if (sizes.length < 1 || sizes.length > expectedPages) failure(result, 'pdf', `Page limit ${expectedPages}, generated ${sizes.length}`);
+    if (sizes.length !== dom.totalPagesFound) failure(result, 'pdf', 'Each physical PDF page must have its own explicit .resume-page container; flowing one container over multiple pages is unsupported');
+    if (sizes.some(p => Math.abs(p.width - 595.276) > 1 || Math.abs(p.height - 841.89) > 1 || p.rotation % 360 !== 0 || Math.abs(p.cropBox.x) > 1 || Math.abs(p.cropBox.y) > 1 || Math.abs(p.cropBox.width - p.width) > 1 || Math.abs(p.cropBox.height - p.height) > 1))
+      failure(result, 'pdf', 'Every PDF page must be portrait A4 (1pt tolerance)');
+    phase = 'text';
+    const task = deps.pdfjs.getDocument({ data: new Uint8Array(bytes), useSystemFonts: true, verbosity: 0 });
+    try {
+      const doc = await task.promise;
+      const pages = [];
+      for (let n = 1; n <= doc.numPages; n++) {
+        const content = await (await doc.getPage(n)).getTextContent();
+        const text = content.items.map(item => item.str || '').join(' ');
+        const expected = dom.pages[n - 1]?.text || '';
+        const missing = missingText(expected, text);
+        const missingFragments = (dom.pages[n - 1]?.textFragments || [])
+          .map(normalized).filter(fragment => fragment && !normalized(text).includes(fragment));
+        const codepoints = value => [...new Set([...value])].map(character => ({
+          character, codepoint: 'U+' + character.codePointAt(0).toString(16).toUpperCase().padStart(4, '0')
+        }));
+        const extractedRadicals = [...text].filter(character => {
+          const cp = character.codePointAt(0); return cp >= 0x2E80 && cp <= 0x2FDF;
+        }).join('');
+        pages.push({ pageIndex: n, text, expectedCharacters: normalized(expected).length, missing, missingFragments,
+          missingCodepoints: codepoints(missing), extractedRadicals: codepoints(extractedRadicals) });
+        if (missing && extractedRadicals)
+          result.warnings.push(`Page ${n}: extracted radical codepoints may indicate font mapping differences. Inspect missingCodepoints/extractedRadicals; choose an available explicit font and rerun without changing the facts.`);
+      }
+      result.checks.text = { status: 'PASS', pages };
+      if (doc.numPages !== sizes.length || pages.some(p => !normalized(p.text) || !p.expectedCharacters || p.missing || p.missingFragments.length || p.text.includes('\ufffd')))
+        failure(result, 'text', 'Blank, missing, undecodable or mismatched per-page PDF text');
+    } finally { await task.destroy(); }
+    result.checks.output = { status: 'PASS', committed: false };
+    return { result: finish(result), bytes };
+  } catch (error) {
+    failure(result, phase, error.message, 'UNVERIFIED');
+    return { result: finish(result) };
+  } finally {
+    page.off('requestfailed', onFailed);
+    page.off('response', onResponse);
+  }
+}
+
+async function run(html, { expectedPages = 1, autoHeal = false, outputPdf } = {}) {
+  const initial = resultFor(html, expectedPages);
+  const source = initial.file;
+  let browser, stagedHtml, stagedPdf, backupHtml;
+  let phase = 'input';
+  try {
+    if (![1, 2].includes(expectedPages)) {
+      failure(initial, 'input', 'expectedPages must be the page limit 1 or 2'); return finish(initial);
+    }
+    const originalBytes = await fs.readFile(source);
+    const original = originalBytes.toString('utf8');
+    const output = outputPdf ? path.resolve(outputPdf) : null;
+    if (output && (output === source || await fs.realpath(output).catch(() => output) === await fs.realpath(source))) {
+      failure(initial, 'input', 'PDF output must differ from HTML source'); return finish(initial);
+    }
+    initial.checks.input = { status: 'PASS' };
+    phase = 'fonts';
+    const deps = await dependencies();
+    browser = await launchBrowser(deps.pw);
+    const page = await browser.newPage({ viewport: { width: 794, height: 1123 } });
+    let attempt = await inspect(page, source, expectedPages, deps);
+    let candidate = original;
+    const tunedTokens = {};
+    let iterations = 0;
+    if (autoHeal && attempt.result.status === 'FAIL' && attempt.result.checks.dom.issues?.length) {
+      stagedHtml = path.join(path.dirname(source), `.${path.basename(source)}.${randomUUID()}.html`);
+      for (const targets of ladder) {
+        const reduced = reduceTokens(candidate, targets);
+        if (reduced.content === candidate) continue;
+        candidate = reduced.content;
+        Object.assign(tunedTokens, reduced.tuned);
+        await fs.writeFile(stagedHtml, candidate, { mode: (await fs.stat(source)).mode });
+        iterations++;
+        attempt = await inspect(page, stagedHtml, expectedPages, deps);
+        if (attempt.result.status !== 'FAIL') break;
+      }
+    }
+    await browser.close(); browser = null;
+    const result = attempt.result;
+    result.file = source;
+    result.checks.auto_heal = { status: result.status, requested: autoHeal, healed: result.status === 'PASS', iterations,
+      tunedTokens: result.status === 'PASS' ? tunedTokens : {}, committed: false };
+    if (result.status !== 'PASS') return result;
+    phase = 'output';
+    // All validation and browser shutdown precede publication. Each file is replaced
+    // by a same-directory rename; roll back HTML if the PDF rename fails.
+    try {
+      if (!(await fs.readFile(source)).equals(originalBytes)) throw new Error('HTML changed during validation');
+      if (output) {
+        await fs.mkdir(path.dirname(output), { recursive: true });
+        stagedPdf = path.join(path.dirname(output), `.${path.basename(output)}.${randomUUID()}.tmp`);
+        await fs.writeFile(stagedPdf, attempt.bytes, { flag: 'wx' });
+      }
+      if (iterations) {
+        backupHtml = path.join(path.dirname(source), `.${path.basename(source)}.${randomUUID()}.backup`);
+        await fs.copyFile(source, backupHtml);
+      }
+      let htmlCommitted = false;
+      try {
+        if (iterations) { await fs.rename(stagedHtml, source); htmlCommitted = true; }
+        if (output) await fs.rename(stagedPdf, output);
+      } catch (error) {
+        if (htmlCommitted) {
+          await fs.rename(backupHtml, source);
+        }
+        throw error;
+      }
+      result.checks.auto_heal.committed = iterations > 0;
+      result.checks.output = { status: 'PASS', committed: !!output, path: output,
+        pdfSha256: createHash('sha256').update(attempt.bytes).digest('hex'),
+        htmlSha256: createHash('sha256').update(iterations ? Buffer.from(candidate, 'utf8') : originalBytes).digest('hex') };
+      return finish(result);
+    } catch (error) { failure(result, 'output', error.message, 'FAIL'); return finish(result); }
+  } catch (error) {
+    failure(initial, phase, error.message, error.code === 'ENOENT' && phase === 'input' ? 'FAIL' : 'UNVERIFIED');
+    return finish(initial);
+  } finally {
+    if (browser) await browser.close().catch(() => {});
+    for (const file of [stagedHtml, stagedPdf, backupHtml]) if (file) await fs.unlink(file).catch(() => {});
+  }
+}
+
+async function cli(args = process.argv.slice(2), defaults = {}) {
+  let html = 'workspace/resume.html';
+  const options = { ...defaults };
+  const positional = [];
+  let bad;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (['--html', '--input', '-i'].includes(arg)) html = args[++i];
+    else if (['--output', '-o', '--output-pdf'].includes(arg)) {
+      options.outputPdf = args[++i];
+      if (!options.outputPdf || options.outputPdf.startsWith('-')) bad = 'Missing PDF output path';
+    }
+    else if (['--expected-pages', '-p'].includes(arg)) options.expectedPages = Number(args[++i]);
+    else if (arg === '--auto-heal') options.autoHeal = true;
+    else if (['--json', '--quiet', '-q'].includes(arg)) continue;
+    else if (arg.startsWith('-')) bad = `Unknown argument: ${arg}`;
+    else positional.push(arg);
+  }
+  if (positional.length > 2) bad = 'Too many positional arguments';
+  html = positional[0] || html;
+  if (positional[1]) options.outputPdf = positional[1];
+  let result;
+  if (bad || !html) { result = resultFor(html || '.', options.expectedPages || 1); failure(result, 'input', bad || 'Missing HTML path'); finish(result); }
+  else result = await run(html, options);
+  process.stdout.write(JSON.stringify(result) + '\n');
+  process.exitCode = result.status === 'PASS' ? 0 : result.status === 'FAIL' ? 1 : 2;
+  return result;
+}
+module.exports = { run, cli, reduceTokens, missingText, systemBrowsers };
+if (require.main === module) cli();

package/scripts/rendering/browser_engine.py

@@ -0,0 +1,39 @@
+"""Standard-library bridge to the single Node rendering/validation engine."""
+import json
+import subprocess
+from pathlib import Path
+
+ENGINE = Path(__file__).resolve().with_name("browser-engine.js")
+
+
+def run(html, *, expected_pages=1, auto_heal=False, output_pdf=None):
+    command = ["node", str(ENGINE), str(Path(html).resolve()),
+               "--expected-pages", str(expected_pages)]
+    if auto_heal:
+        command.append("--auto-heal")
+    if output_pdf is not None:
+        command.extend(["--output", str(Path(output_pdf).resolve())])
+    try:
+        # The engine bounds browser operations and owns publication/cleanup.
+        proc = subprocess.run(command, capture_output=True, text=True)
+        result = json.loads(proc.stdout)
+        if not isinstance(result, dict):
+            raise ValueError('Engine result must be an object')
+        expected_exit = {"PASS": 0, "FAIL": 1, "UNVERIFIED": 2}.get(result.get("status"))
+        if (expected_exit is None or proc.returncode != expected_exit
+                or not isinstance(result.get("errors"), list)
+                or not isinstance(result.get("warnings"), list)
+                or not isinstance(result.get("checks"), dict)
+                or (result["status"] == "PASS" and (result["errors"] or any(
+                    not isinstance(result["checks"].get(key), dict) or result["checks"][key].get("status") != "PASS"
+                    for key in ('input', 'fonts', 'dom', 'pdf', 'text', 'output'))))):
+            raise ValueError("Invalid engine result or exit-code mismatch")
+        return result
+    except (OSError, ValueError) as error:
+        return {"status": "UNVERIFIED", "file": str(Path(html).resolve()),
+                "expectedPages": expected_pages, "errors": [str(error)],
+                "warnings": [], "checks": {"engine": {"status": "UNVERIFIED"}}}
+
+
+def exit_code(result):
+    return {"PASS": 0, "FAIL": 1, "UNVERIFIED": 2}[result["status"]]

package/scripts/rendering/engine-loader.ts

@@ -0,0 +1,11 @@
+import * as fs from 'fs';
+import * as path from 'path';
+// tsc does not copy JS. Resolve the shipped source engine from source or dist.
+let root = __dirname;
+while (!fs.existsSync(path.join(root, 'package.json'))) {
+  const parent = path.dirname(root);
+  if (parent === root) throw new Error('Cannot locate browser engine project root');
+  root = parent;
+}
+const engine: typeof import('./browser-engine') = require(path.join(root, 'scripts/rendering/browser-engine.js'));
+export = engine;

package/scripts/rendering/render-pdf.py

@@ -1,162 +1,37 @@
 #!/usr/bin/env python3
-"""
-KnowMe CareerForge — Multi-Strategy Deterministic PDF Renderer
-多策略自愈式 A4 PDF 渲染器：自动嗅探 Playwright、系统级 Chromium/Chrome/Edge/Brave 浏览器并实现零配置确定性导出。
-"""
-
-import sys, os, subprocess, platform, shutil, argparse
+"""Render and verify a fresh PDF through browser-engine.js before publication."""
+import argparse
+import json
+import sys
 from pathlib import Path
-from typing import Optional, List
-
-def get_project_root() -> Path:
-    curr = Path(__file__).resolve().parent
-    for _ in range(5):
-        if (curr / "SKILL.md").exists() or (curr / "package.json").exists():
-            return curr
-        curr = curr.parent
-    return Path.cwd()
-
-def find_system_browser() -> Optional[str]:
-    system = platform.system()
-    
-    custom_bin = os.environ.get("CHROME_BIN") or os.environ.get("BROWSER_PATH")
-    if custom_bin and Path(custom_bin).exists():
-        return custom_bin
-
-    candidates: List[str] = []
-    
-    if system == "Darwin":  # macOS
-        candidates = [
-            "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
-            "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
-            "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
-            "/Applications/Chromium.app/Contents/MacOS/Chromium",
-            str(Path.home() / "Applications/Google Chrome.app/Contents/MacOS/Google Chrome"),
-            str(Path.home() / "Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"),
-        ]
-    elif system == "Linux":
-        candidates = [
-            "google-chrome", "google-chrome-stable", "chromium", "chromium-browser",
-            "/usr/bin/google-chrome", "/usr/bin/google-chrome-stable",
-            "/usr/bin/chromium", "/usr/bin/chromium-browser",
-            "/snap/bin/chromium"
-        ]
-    elif system == "Windows":
-        prog_files = os.environ.get("PROGRAMFILES", r"C:\Program Files")
-        prog_files_x86 = os.environ.get("PROGRAMFILES(X86)", r"C:\Program Files (x86)")
-        local_app = os.environ.get("LOCALAPPDATA", "")
-        
-        candidates = [
-            os.path.join(prog_files, r"Google\Chrome\Application\chrome.exe"),
-            os.path.join(prog_files_x86, r"Google\Chrome\Application\chrome.exe"),
-            os.path.join(prog_files_x86, r"Microsoft\Edge\Application\msedge.exe"),
-            os.path.join(prog_files, r"Microsoft\Edge\Application\msedge.exe"),
-            os.path.join(local_app, r"Google\Chrome\Application\chrome.exe"),
-            os.path.join(local_app, r"Microsoft\Edge\Application\msedge.exe"),
-            os.path.join(local_app, r"BraveSoftware\Brave-Browser\Application\brave.exe"),
-        ]
-
-    for candidate in candidates:
-        if candidate.startswith("/") or ":" in candidate:
-            if Path(candidate).exists():
-                return candidate
-        else:
-            resolved = shutil.which(candidate)
-            if resolved:
-                return resolved
-
-    return None
-
-def render_via_playwright(html_path: Path, pdf_path: Path) -> bool:
-    root = get_project_root()
-    script_ts = root / "scripts" / "rendering" / "render-pdf.ts"
-    if not script_ts.exists():
-        script_ts = root / "scripts" / "render-pdf.ts"
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from browser_engine import run, exit_code
 
-    if script_ts.exists() and shutil.which("npx"):
-        try:
-            cmd = ["npx", "ts-node", str(script_ts), "--input", str(html_path), "--output", str(pdf_path)]
-            res = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=30)
-            if res.returncode == 0 and pdf_path.exists():
-                return True
-        except Exception:
-            pass
-    return False
 
-def render_via_browser(browser_bin: str, html_path: Path, pdf_path: Path) -> bool:
-    html_url = html_path.resolve().as_uri()
-    cmd = [
-        browser_bin,
-        "--headless=new",
-        "--disable-gpu",
-        "--no-first-run",
-        "--no-default-browser-check",
-        "--disable-background-networking",
-        "--no-pdf-header-footer",
-        "--run-all-compositor-stages-before-draw",
-        f"--print-to-pdf={pdf_path.resolve()}",
-        html_url
-    ]
-    try:
-        res = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=25)
-        return pdf_path.exists() and pdf_path.stat().st_size > 0
-    except Exception as e:
-        print(f"[!] Browser render failed: {e}")
-        return False
+def render_pdf(html_path_str, pdf_path_str, quiet=False, expected_pages=1, auto_heal=False):
+    result = run(html_path_str, expected_pages=expected_pages,
+                 auto_heal=auto_heal, output_pdf=pdf_path_str)
+    if result["status"] != "PASS":
+        raise RuntimeError(json.dumps(result, ensure_ascii=False))
+    return Path(pdf_path_str).resolve()
 
-def render_pdf(html_path_str: str, pdf_path_str: str, quiet: bool = False) -> Path:
-    html_path = Path(html_path_str).resolve()
-    pdf_path = Path(pdf_path_str).resolve()
-
-    if not html_path.exists():
-        raise FileNotFoundError(f"Input HTML file does not exist: {html_path}")
-
-    pdf_path.parent.mkdir(parents=True, exist_ok=True)
-
-    if not quiet:
-        print("==============================================================")
-        print("  KnowMe CareerForge — Multi-Strategy PDF Renderer")
-        print(f"  Source Canvas : {html_path}")
-        print(f"  Target PDF    : {pdf_path}")
-        print("==============================================================")
-
-    # Strategy 1: Playwright Headless
-    if not quiet:
-        print("[*] Strategy 1: Trying Playwright Headless Engine...")
-    if render_via_playwright(html_path, pdf_path):
-        if not quiet:
-            print(f"[✓] Render Succeeded via Playwright -> {pdf_path}")
-        return pdf_path
-
-    # Strategy 2: System Installed Chromium/Chrome/Edge/Brave
-    browser_bin = find_system_browser()
-    if browser_bin:
-        if not quiet:
-            print(f"[*] Strategy 2: Found system browser at: {browser_bin}")
-        if render_via_browser(browser_bin, html_path, pdf_path):
-            if not quiet:
-                print(f"[✓] Render Succeeded via System Browser -> {pdf_path}")
-            return pdf_path
-
-    raise RuntimeError("No suitable PDF rendering engine found. Please install Playwright or Google Chrome / Edge.")
 
 def main():
-    parser = argparse.ArgumentParser(description="KnowMe CareerForge — Multi-Strategy PDF Renderer")
-    parser.add_argument("html", nargs="?", default="workspace/resume.html", help="Input HTML canvas path")
-    parser.add_argument("pdf", nargs="?", default="workspace/resume.pdf", help="Output PDF path")
-    parser.add_argument("--input", "-i", help="Input HTML (named option)")
-    parser.add_argument("--output", "-o", help="Output PDF (named option)")
-    parser.add_argument("--quiet", "-q", action="store_true", help="Quiet execution mode")
-
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("html", nargs="?", default="workspace/resume.html")
+    parser.add_argument("pdf", nargs="?", default="workspace/resume.pdf")
+    parser.add_argument("--input", "-i")
+    parser.add_argument("--output", "-o")
+    parser.add_argument("--expected-pages", "-p", type=int, default=1)
+    parser.add_argument("--auto-heal", action="store_true")
+    parser.add_argument("--quiet", "-q", action="store_true")
+    parser.add_argument("--json", action="store_true")
     args = parser.parse_args()
-    input_html = args.input or args.html
-    output_pdf = args.output or args.pdf
+    result = run(args.input or args.html, expected_pages=args.expected_pages,
+                 auto_heal=args.auto_heal, output_pdf=args.output or args.pdf)
+    print(json.dumps(result, ensure_ascii=False))
+    return exit_code(result)
 
-    try:
-        render_pdf(input_html, output_pdf, quiet=args.quiet)
-    except Exception as e:
-        print(f"[✗] PDF Generation Failed: {e}", file=sys.stderr)
-        sys.exit(1)
 
 if __name__ == "__main__":
-    main()
+    raise SystemExit(main())