knowme-careerforge-skill 0.0.2 → 0.0.6

package/scripts/pipeline/forge.py

@@ -1,142 +1,272 @@
 #!/usr/bin/env python3
-"""
-KnowMe CareerForge — Unified End-to-End Forge Engine
-一键打通：代码仓事实挖掘 (repo-to-resume) ➔ JD 深度解析 ➔ 多维模板检索 ➔ HTML 工作区装配 ➔ Dual-QA 质检 ➔ 确定性 PDF 导出。
-"""
-
-import sys, os, json, argparse, subprocess
+"""Run an isolated user-input resume build with explicit artifact and QA states."""
+import argparse
+import contextlib
+import copy
+import hashlib
+import importlib.util
+import io
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import uuid
+from datetime import datetime, timezone
 from pathlib import Path
 
-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()
+ROOT = Path(__file__).resolve().parents[2]
 
-def main():
-    parser = argparse.ArgumentParser(description="KnowMe CareerForge — One-Shot Unified Forge Engine")
-    parser.add_argument("--repo", "-r", default=".", help="Target code repository path (default: current directory)")
-    parser.add_argument("--role", help="Target job title / role (e.g. 'AI Agent Engineer', '资深前端专家')")
-    parser.add_argument("--jd", help="Path to JD file or raw JD text")
-    parser.add_argument("--template", "-t", default="minimal", help="Template ID (minimal, modern, executive, classic)")
-    parser.add_argument("--name", help="Candidate full name override")
-    parser.add_argument("--email", help="Candidate email override")
-    parser.add_argument("--phone", help="Candidate phone override")
-    parser.add_argument("--output", "-o", default="workspace/resume.pdf", help="Output PDF file path")
-    parser.add_argument("--html-output", default="workspace/resume.html", help="Intermediate working canvas HTML path")
-    parser.add_argument("--quiet", "-q", action="store_true", help="Quiet mode (compact JSON output for AI Agent)")
 
-    args = parser.parse_args()
-    root = get_project_root()
-    scripts_dir = root / "scripts"
-
-    if not args.quiet:
-        print("==============================================================")
-        print("  KnowMe CareerForge — One-Shot Resume Engineering Pipeline")
-        print(f"  Target Role : {args.role or 'Auto-Detect'}")
-        print(f"  Repo Source : {args.repo}")
-        print(f"  Template    : {args.template}")
-        print("==============================================================")
-
-    # 1. 证据挖掘 (Stage 1: Evidence Mining)
-    evidence_json = Path("workspace/evidence-master.json")
-    
-    extract_script = scripts_dir / "evidence" / "extract-evidence.py"
-    if not extract_script.exists():
-        extract_script = scripts_dir / "extract-evidence.py"
-
-    evidence_cmd = [sys.executable, str(extract_script), "--repo", args.repo, "--output", str(evidence_json), "--quiet"]
-    if args.name: evidence_cmd.extend(["--name", args.name])
-    if args.role: evidence_cmd.extend(["--role", args.role])
-    if args.email: evidence_cmd.extend(["--email", args.email])
-    if args.phone: evidence_cmd.extend(["--phone", args.phone])
-
-    subprocess.run(evidence_cmd, check=True)
-    if not args.quiet:
-        print("[✓] Stage 1: Codebase evidence mined -> workspace/evidence-master.json")
-
-    # 2. JD 分析与关键词提取 (Stage 2: JD Analysis)
-    keywords = []
-    if args.jd:
-        try:
-            analyze_script = scripts_dir / "evidence" / "analyze-jd.py"
-            if not analyze_script.exists():
-                analyze_script = scripts_dir / "analyze-jd.py"
-
-            jd_cmd = [sys.executable, str(analyze_script)]
-            if Path(args.jd).exists():
-                jd_cmd.extend(["--jd", args.jd])
+def load_module(name, relative):
+    spec = importlib.util.spec_from_file_location(name, ROOT / 'scripts' / relative)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+contract = load_module('profile_contract', 'contracts/profile.py')
+
+
+def atomic_write(path, data):
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, temp = tempfile.mkstemp(prefix='.' + path.name + '-', dir=path.parent)
+    try:
+        with os.fdopen(fd, 'wb') as stream:
+            stream.write(data if isinstance(data, bytes) else data.encode('utf-8'))
+        os.replace(temp, path)
+    finally:
+        if os.path.exists(temp):
+            os.unlink(temp)
+
+
+def write_json(path, value):
+    atomic_write(path, json.dumps(value, ensure_ascii=False, indent=2) + '\n')
+
+
+def file_hash(path):
+    return hashlib.sha256(Path(path).read_bytes()).hexdigest()
+
+
+def publish_aliases(pairs):
+    """Stage every requested copy before publishing; rollback ordinary write failures.
+
+    The run directory remains canonical. Lock files reject concurrent publishers
+    to the same requested destination instead of interleaving their outputs.
+    """
+    staged, locks, replaced = [], [], []
+    try:
+        for source, target in pairs:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            lock = target.with_name('.' + target.name + '.knowme-lock')
+            fd = os.open(lock, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+            os.close(fd)
+            locks.append(lock)
+            if target.exists() and not target.is_file():
+                raise ValueError('Output is not a regular file: ' + str(target))
+            backup = target.read_bytes() if target.exists() else None
+            fd, temp = tempfile.mkstemp(prefix='.knowme-export-', dir=target.parent)
+            os.close(fd)
+            staged.append((Path(temp), target, backup))
+            shutil.copyfile(source, temp)
+        for temp, target, backup in staged:
+            os.replace(temp, target)
+            replaced.append((target, backup))
+    except Exception:
+        for target, backup in reversed(replaced):
+            if backup is None:
+                target.unlink(missing_ok=True)
             else:
-                jd_cmd.extend(["--text", args.jd])
-            jd_res = subprocess.run(jd_cmd, stdout=subprocess.PIPE, text=True, check=True)
-            for line in jd_res.stdout.splitlines():
-                if "Must-have Skills" in line or "Detected" in line:
-                    parts = line.split(":")[-1].strip().split(",")
-                    keywords.extend([p.strip() for p in parts if p.strip()])
-        except Exception:
-            pass
-
-    # 3. 模板装配到工作区 (Stage 3 & 4: Template Instantiation)
-    kw_arg = ",".join(keywords[:8]) if keywords else "TypeScript,Playwright,Python,Docker"
-    
-    instantiate_script = scripts_dir / "template" / "instantiate-resume.py"
-    if not instantiate_script.exists():
-        instantiate_script = scripts_dir / "instantiate-resume.py"
-
-    instantiate_cmd = [
-        sys.executable, str(instantiate_script),
-        "--template", args.template,
-        "--profile", str(evidence_json),
-        "--keywords", kw_arg,
-        "--output", args.html_output
-    ]
-    subprocess.run(instantiate_cmd, stdout=subprocess.DEVNULL if args.quiet else None, check=True)
-    if not args.quiet:
-        print(f"[✓] Stage 2: HTML Working Canvas instantiated -> {args.html_output}")
-
-    # 4. 质检与自愈校验 (Stage 5: Dual QA Validation)
-    val_script = scripts_dir / "validation" / "validate-resume.py"
-    if not val_script.exists():
-        val_script = scripts_dir / "validate-resume.py"
-
-    validator_cmd = [
-        sys.executable, str(val_script),
-        args.html_output
-    ]
-    subprocess.run(validator_cmd, stdout=subprocess.DEVNULL if args.quiet else None, check=True)
-    if not args.quiet:
-        print("[✓] Stage 3: Dual QA Validation Passed 100%")
-
-    # 5. 确定性渲染导出 PDF (Stage 6: PDF Export)
-    render_script = scripts_dir / "rendering" / "render-pdf.py"
-    if not render_script.exists():
-        render_script = scripts_dir / "render-pdf.py"
-
-    render_cmd = [
-        sys.executable, str(render_script),
-        args.html_output, args.output
-    ]
-    if args.quiet:
-        render_cmd.append("--quiet")
-    subprocess.run(render_cmd, check=True)
-
-    if not args.quiet:
-        print("==============================================================")
-        print(f"  [✓] ALL STAGES COMPLETED SUCCESSFULLY!")
-        print(f"  HTML Working Canvas : {Path(args.html_output).resolve()}")
-        print(f"  Final Verified PDF  : {Path(args.output).resolve()}")
-        print("==============================================================")
-    else:
-        result = {
-            "status": "SUCCESS",
-            "htmlCanvas": str(Path(args.html_output).resolve()),
-            "pdfDelivery": str(Path(args.output).resolve()),
-            "evidenceProfile": str(evidence_json.resolve()),
-            "templateUsed": args.template
-        }
-        print(json.dumps(result, ensure_ascii=False, indent=2))
-
-if __name__ == "__main__":
-    main()
+                atomic_write(target, backup)
+        raise
+    finally:
+        for temp, _, _ in staged:
+            temp.unlink(missing_ok=True)
+        for lock in locks:
+            lock.unlink(missing_ok=True)
+
+
+class Parser(argparse.ArgumentParser):
+    def error(self, message):
+        print(json.dumps({'status': 'FAIL', 'stage': 'arguments', 'errors': [message],
+                          'warnings': [], 'checks': {}, 'outputs': {}}, ensure_ascii=False))
+        self.exit(1)
+
+
+def main():
+    parser = Parser(description=__doc__)
+    parser.add_argument('--profile-json', required=True, help='User/Agent supplied facts or Draft/Master document; never a repository')
+    parser.add_argument('--workspace', default='workspace/runs', help='Parent directory for unique run directories')
+    parser.add_argument('--draft', action='store_true', help='Create an incomplete draft canvas without claiming PDF delivery')
+    parser.add_argument('--role')
+    parser.add_argument('--jd', help='Optional JD path or inline text; used only as highlighting/search hints')
+    parser.add_argument('--template', '-t')
+    parser.add_argument('--font-preset', choices=('system', 'arial-unicode'), default='system', help='Explicit local font choice; missing fonts fail verification')
+    for key in ('name', 'email', 'phone'):
+        parser.add_argument('--' + key)
+    parser.add_argument('--output', '-o', help='Optional verified PDF copy; default is the isolated run PDF')
+    parser.add_argument('--html-output', help='Optional verified HTML copy; default is the isolated run canvas')
+    parser.add_argument('--expected-pages', type=int, choices=(1, 2), default=1)
+    parser.add_argument('--auto-heal', action='store_true')
+    parser.add_argument('--quiet', '-q', action='store_true')
+    args = parser.parse_args()
+    report = {'schemaVersion': '1.0', 'runId': uuid.uuid4().hex, 'status': 'RUNNING',
+              'stage': 'input', 'errors': [], 'warnings': [], 'checks': {}, 'outputs': {}}
+    run = None
+    exit_code = 1
+    try:
+        parent = Path(args.workspace).resolve()
+        parent.mkdir(parents=True, exist_ok=True)
+        run = parent / report['runId']
+        run.mkdir(mode=0o700)
+        report['runDirectory'] = str(run)
+        report['startedAt'] = datetime.now(timezone.utc).isoformat()
+        write_json(run / 'manifest.json', report)
+        source = Path(args.profile_json).resolve()
+        aliases = [Path(p).resolve() for p in (args.html_output, args.output) if p]
+        if len(set([source] + aliases)) != len([source] + aliases):
+            raise ValueError('Input, HTML and PDF output paths must be distinct')
+        for target in aliases:
+            if target == run or run in target.parents:
+                raise ValueError('Explicit output cannot replace an internal run artifact')
+        raw_bytes = source.read_bytes()
+        atomic_write(run / 'input.json', raw_bytes)
+        supplied = contract.load_document(json.loads(raw_bytes))
+        if supplied['kind'] == 'variant':
+            raise ValueError('A Variant is not a Master; use its original Master to derive another resume')
+        if supplied['kind'] == 'draft' and not args.draft:
+            raise ValueError('Draft input cannot be delivered; review facts and provide a Master, or use --draft')
+        facts = copy.deepcopy(supplied['profile'])
+        for key in ('name', 'email', 'phone'):
+            if getattr(args, key) is not None:
+                facts['basics'][key] = getattr(args, key)
+        kind = 'draft' if args.draft else 'master'
+        master = contract.document(kind, facts, {'type': 'user-input', 'path': str(source),
+                     'inputSha256': hashlib.sha256(raw_bytes).hexdigest(),
+                     'suppliedKind': supplied['kind'], 'suppliedSource': supplied['source']})
+        write_json(run / (kind + '.json'), master)
+        report['checks']['missingFields'] = master['missingFields']
+        report['warnings'].extend('Missing optional contact/position field: ' + v for v in master['missingFields'] if v != 'basics.name')
+        if not args.draft:
+            errors = contract.delivery_errors(master['profile'])
+            if errors:
+                raise ValueError('; '.join(errors))
+        profile = copy.deepcopy(master['profile'])
+        if args.role is not None:
+            profile['basics']['title'] = args.role
+        keywords = []
+        if args.jd:
+            report['stage'] = 'jd'
+            try:
+                jd_file = Path(args.jd)
+                jd = jd_file.read_text(encoding='utf-8') if jd_file.is_file() else args.jd
+            except OSError:
+                jd = args.jd
+            atomic_write(run / 'jd.txt', jd)
+            analyzer = load_module('jd_analyzer', 'evidence/analyze-jd.py')
+            with contextlib.redirect_stdout(io.StringIO()):
+                result = analyzer.analyze_jd_text(jd)
+            write_json(run / 'jd-analysis.json', result)
+            keywords = result.get('detectedSkills', [])
+        report['stage'] = 'template'
+        template = args.template
+        if not template:
+            search = load_module('template_search', 'template/search-template.py')
+            with contextlib.redirect_stdout(io.StringIO()):
+                results = search.search_templates(role=args.role or profile['basics'].get('title') or '',
+                                                  keywords=','.join(keywords), target_pages=args.expected_pages, engine='hybrid')
+            if not results:
+                raise ValueError('No matching template available')
+            template = results[0].get('id') or results[0]['template']['id']
+        variant = contract.document('draft' if args.draft else 'variant', profile,
+                     {'masterSha256': master['profileSha256'], 'masterPath': str(run / (kind + '.json')),
+                      'template': template, 'targetRole': args.role, 'fontPreset': args.font_preset})
+        variant_path = run / ('draft-canvas-profile.json' if args.draft else 'variant.json')
+        write_json(variant_path, variant)
+        report['templateUsed'] = template
+        report['fontPreset'] = args.font_preset
+        report['stage'] = 'binding'
+        inst = load_module('instantiate_resume', 'template/instantiate-resume.py')
+        canvas, pdf = run / 'resume.html', run / 'resume.pdf'
+        with contextlib.redirect_stdout(io.StringIO()):
+            inst.instantiate_workspace(template, str(variant_path), ','.join(keywords), str(canvas), font_preset=args.font_preset)
+        if args.draft:
+            report.update(status='DRAFT', stage='draft', outputs={'draft': str(run / 'draft.json'), 'htmlCanvas': str(canvas)})
+            exit_code = 0
+        else:
+            report['stage'] = 'qa'
+            cmd = ['node', str(ROOT / 'scripts/rendering/browser-engine.js'), str(canvas),
+                   '--expected-pages', str(args.expected_pages), '--output', str(pdf)]
+            if args.auto_heal:
+                cmd.append('--auto-heal')
+            process = subprocess.run(cmd, capture_output=True, text=True, timeout=120)
+            try:
+                qa = json.loads(process.stdout)
+                if not isinstance(qa, dict):
+                    raise ValueError('QA result must be an object')
+                expected_exit = {'PASS': 0, 'FAIL': 1, 'UNVERIFIED': 2}.get(qa.get('status'))
+                if expected_exit is None or process.returncode != expected_exit:
+                    raise ValueError('QA status and exit code disagree')
+                if (not isinstance(qa.get('checks'), dict)
+                        or any(not isinstance(v, dict) for v in qa['checks'].values())
+                        or any(not isinstance(qa.get(key), list) or any(not isinstance(v, str) for v in qa[key])
+                               for key in ('errors', 'warnings'))):
+                    raise ValueError('Malformed QA diagnostics')
+            except (ValueError, TypeError) as error:
+                report['status'] = 'UNVERIFIED'
+                raise ValueError('Browser returned no valid QA result: ' + str(error) + '; ' + process.stderr[:400])
+            write_json(run / 'qa.json', qa)
+            report['checks']['qa'] = qa
+            report['warnings'].extend(qa.get('warnings', []))
+            if process.returncode != 0 or qa.get('status') != 'PASS':
+                report['status'] = 'UNVERIFIED' if qa.get('status') == 'UNVERIFIED' else 'FAIL'
+                raise ValueError('; '.join(qa.get('errors', [])) or 'PDF validation did not pass')
+            checks = qa.get('checks', {})
+            required_checks = ('input', 'fonts', 'dom', 'pdf', 'text', 'output')
+            if qa.get('errors') or any(checks.get(key, {}).get('status') != 'PASS' for key in required_checks):
+                report['status'] = 'UNVERIFIED'
+                raise ValueError('Incomplete or contradictory QA result; refusing delivery')
+            accepted = checks['output']
+            if not accepted.get('committed') or accepted.get('path') != str(pdf):
+                report['status'] = 'UNVERIFIED'
+                raise ValueError('QA did not commit this run PDF')
+            if not pdf.is_file() or not pdf.read_bytes().startswith(b'%PDF-'):
+                raise ValueError('Verified PDF was not produced by this run')
+            if accepted.get('pdfSha256') != file_hash(pdf) or accepted.get('htmlSha256') != file_hash(canvas):
+                raise ValueError('Output changed after QA or acceptance hashes are missing')
+            report['stage'] = 'publish'
+            pairs = []
+            if args.html_output:
+                pairs.append((canvas, Path(args.html_output).resolve()))
+            if args.output:
+                pairs.append((pdf, Path(args.output).resolve()))
+            publish_aliases(pairs)
+            report.update(status='PASS', stage='complete', outputs={
+                'master': str(run / 'master.json'), 'variant': str(variant_path),
+                'htmlCanvas': str(canvas), 'pdfDelivery': str(pdf), 'qa': str(run / 'qa.json'),
+                'copies': [str(target) for _, target in pairs]},
+                sha256={'html': file_hash(canvas), 'pdf': file_hash(pdf), 'master': master['profileSha256']})
+            exit_code = 0
+    except Exception as error:
+        if report['status'] == 'RUNNING':
+            report['status'] = 'UNVERIFIED' if (report['stage'] == 'qa' and isinstance(error, (subprocess.TimeoutExpired, FileNotFoundError))) or not isinstance(error, (OSError, ValueError, TypeError, RuntimeError)) else 'FAIL'
+        report['errors'].append(str(error))
+        report['outputs'] = {}
+        exit_code = 2 if report['status'] == 'UNVERIFIED' else 1
+    finally:
+        report['finishedAt'] = datetime.now(timezone.utc).isoformat()
+        if run:
+            try:
+                write_json(run / 'manifest.json', report)
+            except OSError as error:
+                report.update(status='FAIL', outputs={})
+                report['errors'].append('Could not persist manifest: ' + str(error))
+                exit_code = 1
+        print(json.dumps(report, ensure_ascii=False, indent=None if args.quiet else 2))
+    return exit_code
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/scripts/rendering/README.md

@@ -0,0 +1,65 @@
+# Browser rendering and validation
+
+All rendering/layout entry points delegate to `browser-engine.js`:
+
+```js
+const { run } = require('./browser-engine');
+const result = await run(htmlPath, { expectedPages: 1, autoHeal: false, outputPdf });
+```
+
+```sh
+node scripts/rendering/browser-engine.js resume.html --expected-pages 1 --output resume.pdf
+```
+
+CLI stdout is one JSON object with `status`, `errors`, `warnings`, `checks`,
+`file`, and `expectedPages`. Exit codes: PASS=0, FAIL=1, UNVERIFIED=2.
+`expectedPages` is an upper limit, restricted to 1 or 2.
+Missing dependencies, browser/font/resource failures and parser failures cannot pass.
+Validation without `outputPdf` still generates and inspects a fresh in-memory PDF.
+No previous PDF is read to decide success. Output write/publication failures are
+FAIL (exit 1); UNVERIFIED is reserved for unavailable verification facilities.
+On successful export, `checks.output` contains `status: "PASS"`, `committed: true`,
+the absolute `path`, and lowercase SHA-256 `pdfSha256` / `htmlSha256` digests of
+the exact published PDF and final source HTML bytes. Without export, `committed`
+is false and `path` is null, while digests identify the verified in-memory PDF
+and final HTML.
+
+Runtime dependencies: Playwright (or playwright-core with a browser), pdf-lib,
+and pdfjs-dist with `legacy/build/pdf.mjs`; use a Node version supported by
+pdfjs-dist. `CHROME_BIN` / `BROWSER_PATH` can select a Chromium executable.
+Without overrides, bundled Chromium is tried first, then detected system
+Chrome/Chromium/Edge/Brave installations (including PATH and macOS/Windows locations).
+Dependency installation and package manifests are managed separately.
+
+Checks use print media, await fonts and images, and inspect every `.resume-page`,
+its descendants and text ranges against all four boundaries and rectangular
+ancestor clips. Exactly one nonempty visible `h1.candidate-name` is required,
+Nonempty print-hidden body text (display, visibility or ancestor opacity) fails,
+even if other body text still survives PDF extraction. Also required:
+at least 20 non-whitespace body characters beyond the name with no unbound
+resume slot comments or language attribute. Literal brace syntax in user text is preserved. Each PDF page must correspond to an explicit `.resume-page`;
+a single root naturally flowing into multiple PDF pages is rejected. DOM tolerance is 0.75 CSS pixels. Unsupported clipping returns
+UNVERIFIED. The generated PDF must have 1–`expectedPages` portrait A4
+pages (1 PDF point tolerance, including crop boxes). PDF.js extracts every page:
+normalized character multiplicities and each DOM text fragment must survive on
+the corresponding PDF page. NFKC and whitespace/control normalization tolerate
+line wrapping and ligatures; a missing or reordered name cannot pass.
+
+Autoheal only reduces existing numeric inline `:root` tokens through the bounded
+ladder. Each candidate is loaded from a temporary sibling HTML file to preserve
+relative assets and fully revalidated. No source change is published on failed
+validation. On success, files are replaced by same-directory renames; an HTML
+backup allows rollback if PDF publication fails. This is per-file atomicity with
+rollback, not a crash-atomic transaction spanning two files. Temporary candidates
+are cleaned up. Concurrent source edits detected before publication abort the run.
+
+Isolated tests (real Chromium, temporary directories and injected PDF/I/O failures):
+
+```sh
+node --test tests/rendering/browser-engine.test.js
+python3 scripts/build/run-all-tests.py
+```
+
+The Python suite runs the Node regressions through `tests/validation/test_auto_heal.py`.
+
+Per-page text diagnostics include missingCodepoints and extractedRadicals (glyph and U+ codepoint). A warning about possible font mapping differences never changes FAIL to PASS. The pipeline and instantiator accept --font-preset arial-unicode to explicitly use locally installed Arial Unicode MS; this is not a browser-engine option. Missing explicit fonts remain UNVERIFIED.

package/scripts/rendering/browser-engine.d.ts

@@ -0,0 +1,15 @@
+export interface EngineOptions {
+  expectedPages?: number;
+  autoHeal?: boolean;
+  outputPdf?: string;
+}
+export interface EngineResult {
+  status: 'PASS' | 'FAIL' | 'UNVERIFIED';
+  file: string;
+  expectedPages: number;
+  errors: string[];
+  warnings: string[];
+  checks: Record<string, { status: 'PASS' | 'FAIL' | 'UNVERIFIED'; [key: string]: unknown }>;
+}
+export function run(html: string, options?: EngineOptions): Promise<EngineResult>;
+export function cli(args?: string[], defaults?: EngineOptions): Promise<EngineResult>;