knowme-careerforge-skill 0.0.2 → 0.0.6

package/dist/scripts/validation/validate-layout.js

@@ -1,164 +1,10 @@
 #!/usr/bin/env ts-node
 "use strict";
-/**
- * KnowMe CareerForge — Playwright DOM Layout & Overflow Inspector
- * 基于无头浏览器真实渲染计算 DOM 盒模型高度，检测单页/双页物理 A4 溢出与孤行。
- */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateLayout = validateLayout;
-const playwright_1 = require("playwright");
-const path = __importStar(require("path"));
-const fs = __importStar(require("fs"));
-async function validateLayout(htmlPath, expectedPages = 1) {
-    const absoluteHtml = path.resolve(htmlPath);
-    if (!fs.existsSync(absoluteHtml)) {
-        throw new Error(`HTML file not found: ${absoluteHtml}`);
-    }
-    const browser = await playwright_1.chromium.launch({ headless: true });
-    const context = await browser.newContext({
-        viewport: { width: 794, height: 1123 }, // A4 at 96 DPI
-        deviceScaleFactor: 1
-    });
-    const page = await context.newPage();
-    await page.goto(`file://${absoluteHtml}`, { waitUntil: 'networkidle' });
-    await page.evaluateHandle('document.fonts.ready');
-    // A4 标准高度 (297mm in pixels at 96 DPI ~= 1122.5px)
-    const A4_HEIGHT_PX = 1122.5;
-    const evaluation = await page.evaluate((allowedHeight) => {
-        const pages = Array.from(document.querySelectorAll('.resume-page'));
-        const details = pages.map((p, idx) => {
-            const rect = p.getBoundingClientRect();
-            const actualHeight = Math.ceil(rect.height);
-            const isOverflow = actualHeight > allowedHeight + 2; // 2px 浮点容差
-            return {
-                pageIndex: idx + 1,
-                actualHeightPx: actualHeight,
-                allowedHeightPx: allowedHeight,
-                isOverflow,
-                overflowDeltaPx: isOverflow ? Math.ceil(actualHeight - allowedHeight) : 0
-            };
-        });
-        const overflowSections = [];
-        if (details.some(d => d.isOverflow)) {
-            const items = Array.from(document.querySelectorAll('.experience-item, .project-item, .skills-content, .resume-section'));
-            for (const item of items) {
-                const rect = item.getBoundingClientRect();
-                if (rect.bottom > allowedHeight) {
-                    overflowSections.push({
-                        selector: item.className ? `.${item.className.split(' ').join('.')}` : item.tagName.toLowerCase(),
-                        bottomPx: Math.ceil(rect.bottom),
-                        overflowByPx: Math.ceil(rect.bottom - allowedHeight)
-                    });
-                }
-            }
-        }
-        return {
-            totalPagesFound: pages.length || 1,
-            pageDetails: details.length ? details : [{
-                    pageIndex: 1,
-                    actualHeightPx: Math.ceil(document.body.getBoundingClientRect().height),
-                    allowedHeightPx: allowedHeight,
-                    isOverflow: document.body.getBoundingClientRect().height > allowedHeight + 2,
-                    overflowDeltaPx: Math.max(0, Math.ceil(document.body.getBoundingClientRect().height - allowedHeight))
-                }],
-            overflowSections
-        };
-    }, A4_HEIGHT_PX);
-    await browser.close();
-    const hasOverflow = evaluation.pageDetails.some(p => p.isOverflow) || evaluation.totalPagesFound > expectedPages;
-    return {
-        status: hasOverflow ? 'OVERFLOW' : 'PASS',
-        expectedPages,
-        totalPagesFound: evaluation.totalPagesFound,
-        pageDetails: evaluation.pageDetails,
-        overflowSections: evaluation.overflowSections
-    };
-}
-async function main() {
-    const args = process.argv.slice(2);
-    let htmlPath = 'workspace/resume.html';
-    let expectedPages = 1;
-    let jsonOutput = false;
-    for (let i = 0; i < args.length; i++) {
-        if (args[i] === '--html' || args[i] === '-i') {
-            htmlPath = args[i + 1];
-            i++;
-        }
-        else if (args[i] === '--expected-pages' || args[i] === '-p') {
-            expectedPages = parseInt(args[i + 1], 10) || 1;
-            i++;
-        }
-        else if (args[i] === '--json') {
-            jsonOutput = true;
-        }
-        else if (!args[i].startsWith('-')) {
-            htmlPath = args[i];
-        }
-    }
-    try {
-        const result = await validateLayout(htmlPath, expectedPages);
-        if (jsonOutput) {
-            console.log(JSON.stringify(result, null, 2));
-            process.exit(result.status === 'PASS' ? 0 : 1);
-        }
-        console.log('======================================================');
-        console.log(`  KnowMe CareerForge — Layout QA: ${result.status}`);
-        console.log(`  HTML Path      : ${htmlPath}`);
-        console.log(`  Expected Pages : ${result.expectedPages} | Pages Found: ${result.totalPagesFound}`);
-        console.log('------------------------------------------------------');
-        for (const p of result.pageDetails) {
-            const fitText = p.isOverflow ? `[✗ OVERFLOW by ${p.overflowDeltaPx}px]` : `[✓ FIT] (Overflow: ${p.overflowDeltaPx}px)`;
-            console.log(`  Page ${p.pageIndex}: ${p.actualHeightPx}px / ${p.allowedHeightPx}px ${fitText}`);
-        }
-        if (result.overflowSections.length > 0) {
-            console.log('\n[!] Offending Overflow Elements:');
-            for (const el of result.overflowSections.slice(0, 3)) {
-                console.log(`  - Element "${el.selector}" exceeds A4 baseline by ${el.overflowByPx}px (Bottom: ${el.bottomPx}px)`);
-            }
-            console.log('\n💡 Recommendation: Reduce --resume-space-section by 1~2pt or reduce --resume-font-size-body by 0.2pt in <style>.');
-        }
-        console.log('======================================================');
-        process.exit(result.status === 'PASS' ? 0 : 1);
-    }
-    catch (err) {
-        const errorMsg = err instanceof Error ? err.message : String(err);
-        console.error(`[✗] Layout Validation Failed: ${errorMsg}`);
-        process.exit(1);
-    }
-}
-if (require.main === module) {
-    main();
+const engine = require("../rendering/engine-loader");
+function validateLayout(htmlPath, expectedPages = 1, options = {}) {
+    return engine.run(htmlPath, { ...options, expectedPages });
 }
+if (require.main === module)
+    engine.cli();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knowme-careerforge-skill",
-  "version": "0.0.2",
+  "version": "0.0.6",
   "description": "An agent-native skill for self-discovery, career positioning, and tailored resume engineering.",
   "main": "dist/cli/src/index.js",
   "bin": {
@@ -13,7 +13,10 @@
     "scripts",
     "agents",
     "SKILL.md",
-    "skill.json"
+    "skill.json",
+    "references",
+    "AGENT.md",
+    "ARCHITECTURE.md"
   ],
   "scripts": {
     "build": "tsc",
@@ -30,7 +33,9 @@
     "build:knowledge": "python3 scripts/build/build-knowledge.py",
     "build:gallery": "python3 scripts/build/build-gallery.py",
     "release": "python3 scripts/build/release.py",
-    "prepublishOnly": "npm run build && npm test"
+    "version:sync": "python3 scripts/build/sync-version.py",
+    "prepublishOnly": "npm test",
+    "pretest": "npm run build"
   },
   "keywords": [
     "career-forge",
@@ -54,8 +59,15 @@
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
-    "playwright": "^1.49.0",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "pdf-lib": "^1.17.1",
+    "pdfjs-dist": "^5.4.624",
+    "playwright": "^1.62.1"
+  },
+  "engines": {
+    "node": ">=22.13.0"
   }
 }

package/references/01-evidence-mining.md

@@ -0,0 +1,5 @@
+# Organize user-supplied facts
+
+Use the user's descriptions, prior resume and explicitly supplied supporting material. Repository scanning is not a supported candidate input mode. Reuse known information; ask progressive follow-up questions only for consequential gaps. Do not invent dates, employers, degrees or metrics, or weaken stated ownership solely because it came from chat.
+
+Store incomplete information as Draft and reviewed supplied facts as Master. Derive role-specific Variant content without changing the Master. Unknown values remain omitted/null. Follow the shared lifecycle and error rules in 07-artifact-contract.md.

package/references/02-career-goal.md

@@ -0,0 +1,38 @@
+# Reference Manual 02: Career Goal Definition & Role Archetypes
+
+> **"Know Yourself. Define Your Direction. Forge Your Opportunity."**
+
+---
+
+## 1. Professional Seniority Signals
+
+Identify candidate level and calibrate narrative depth accordingly:
+
+| Seniority Tier | Core Value Proposition | Key Narrative Signals | Section Priority |
+|:---|:---|:---|:---|
+| **Junior (1~3 Years)** | Rapid learning, solid coding standards, reliable task delivery | Clean code, unit test coverage, framework fluency, bug resolution | Skills → Projects → Experience → Education |
+| **Mid-Level (3~5 Years)** | Independent ownership, feature architecture, performance optimization | End-to-end module ownership, database tuning, API design, CI/CD | Experience → Projects → Skills → Education |
+| **Senior / Lead (5~8+ Years)** | System architecture, technical leadership, cross-system trade-offs | Distributed systems, high availability, mentoring, business impact | Experience → Projects → Architecture → Skills |
+| **Principal / Architect** | Technical vision, organizational strategy, governance, ROI | Architecture governance, multi-team alignment, technology selection | Experience → Leadership → Architecture → Patents |
+
+---
+
+## 2. Role Archetypes Knowledge Base (`src/knowledge/roles/*.json`)
+
+The skill ships with 9+ structured role profiles:
+- `ai-agent-engineer.json`: LLM Orchestration, RAG, Tool Calling, VectorDB, Prompt Engineering
+- `frontend.json`: React/Vue/Next.js, Web Vitals, Design Systems, State Management
+- `java-backend.json`: Spring Boot, JVM tuning, Distributed Caching, Message Queues
+- `node-fullstack.json`: TypeScript, Node.js runtime, GraphQL, Cloud Native
+- `architect.json`: Distributed Systems, Domain-Driven Design, High Concurrency, Cloud Architecture
+- `product-manager.json`: PRD, User Research, Data Analysis, Roadmapping, Growth
+
+---
+
+## 3. Core Value Proposition Formulation
+
+Synthesize the 15~25 word Value Proposition headline following this formula:
+$$\text{Value Proposition} = [\text{Target Role}] + [\text{Years/Domain Focus}] + [\text{Top 2 Signature Strengths}] + [\text{Concrete Impact Deliverable}]$$
+
+*Example*:
+> **Senior AI Agent Engineer** with 5+ years building scalable LLM orchestration & enterprise RAG pipelines, delivering 40% latency reduction across multi-agent production workflows.

package/references/03-jd-analysis.md

@@ -0,0 +1,44 @@
+# Reference Manual 03: Job Description (JD) Analysis & Keyword Extraction
+
+> **"Understand the hiring manager's unstated pain point to align your verified strengths."**
+
+---
+
+## 1. Automated JD Signal Parsing Protocol
+
+Execute the JD analyzer to extract structured requirements:
+```bash
+python3 scripts/evidence/analyze-jd.py --jd "path/to/jd.md" --json
+```
+
+### Signal Extraction Dimensions:
+1. **Target Role & Seniority Tier**: Extracted from title and years of experience requirements;
+2. **Must-Have Skills (Hard Constraints)**: Top technical stacks and non-negotiable architectural competencies;
+3. **Nice-to-Have Skills (Differentiators)**: Emerging tools, cloud certifications, domain bonuses;
+4. **Hiring Pain Points**: High-frequency verbs indicating immediate business challenges (e.g., "reduce latency", "overhaul legacy monolithic service", "establish CI/CD").
+
+---
+
+## 2. Keyword Density & Highlighting Rules
+
+In `workspace/resume.html`, inject JD keywords to pass ATS automated screening while remaining natural for human reviewers:
+
+- **Primary Stack (Top 3~5 Keywords)**: Wrap with `<strong>` tags inside bullet points where evidence exists;
+- **Technology Badges**: Place in `.tech-tags` or `.tech-badge` spans;
+- **Density Control**: Maintain keyword density around 2.5%~4.0% of total words to prevent ATS keyword stuffing penalties.
+
+---
+
+## 3. FAB (Feature-Advantage-Benefit) Bullet Engineering
+
+Structure every project bullet point using the FAB formula:
+
+```
+┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐
+│  Feature (技术动作)│ ────> │ Advantage (技术优势)│ ────> │  Benefit (业务价值) │
+│ Exact tech & tool │       │ Architectural gain│     │ Quantified impact│
+└─────────────────┘       └─────────────────┘       └─────────────────┘
+```
+
+*Before (Weak)*: Worked on database and improved query performance.  
+*After (FAB Standard)*: Refactored PostgreSQL indexing and introduced Redis multi-tier caching (**Feature**), cutting P99 query latency from 850ms to 45ms (**Advantage**), supporting 10x traffic spike during peak sales (**Benefit**).

package/references/04-template-selection.md

@@ -0,0 +1,43 @@
+# Reference Manual 04: Template Selection & Layout Geometries
+
+> **"Layout geometry determines information hierarchy. Select the composition that earns the candidate's strongest evidence."**
+
+---
+
+## 1. Core Template Matrix (Baseline 4)
+
+| Template ID | Layout Geometry | Tone & Accent | Target Roles | Density | ATS Tier |
+|:---|:---|:---|:---|:---|:---|
+| `minimal` (`minimal-tech`) | Single-Column Linear Flow | Geek Minimal (Tech Blue `#2563eb`) | Backend, AI/LLM, Systems, DevOps, Fullstack | High | Tier 1 (Optimal) |
+| `modern` (`modern-split-sidebar`) | Two-Column Split (32:68 Dark Sidebar) | Deep Navy (`#254665`) + Sky Blue (`#38bdf8`) | AI Agent, Frontend, Fullstack, Mobile | Balanced | Tier 1 (Optimal) |
+| `executive` (`executive-split`) | Hero Banner + Two-Column (33:67 Split) | Executive Slate (`#1e293b`) + Teal (`#0f766e`) | Tech Director, Architect, PM, CTO | Balanced | Tier 1 (Optimal) |
+| `classic` (`table-structured`) | 6-Column Structured Grid Table | Corporate Blue (`#1d4ed8`) + Slate | Enterprise, Fintech, Hardware, State-Owned | High | Tier 1 (Optimal) |
+
+---
+
+## 2. Template Search Engine (`scripts/template/search-template.py`)
+
+Search for the optimal template via CLI:
+```bash
+# Hybrid Search (Default Recommended)
+python3 scripts/template/search-template.py "AI Agent Engineer" --style "two-column-split" --target-pages 1
+
+# BM25 Keyword Search
+python3 scripts/template/search-template.py "Distributed Architect" --engine bm25 --json
+
+# Weighted Multi-Criteria Rule Search
+python3 scripts/template/search-template.py "Frontend Engineer" --engine weighted
+```
+
+### Search Scoring Formulation (Weighted Scorer):
+$$\text{Score} = (\text{RoleMatch} \times 0.35) + (\text{StyleMatch} \times 0.25) + (\text{ATSTier} \times 0.20) + (\text{PageFit} \times 0.10) + (\text{Density} \times 0.10)$$
+
+---
+
+## 3. Instantiating the Intermediate HTML Canvas
+
+```bash
+python3 scripts/template/instantiate-resume.py --template modern --profile workspace/evidence-master.json --keywords "Python,LLM,RAG,FastAPI" --output workspace/resume.html
+```
+
+*The instantiator automatically inlines `src/templates/common/base.css` + `src/templates/{template}/style.css` into a single self-contained HTML file.*

package/references/05-html-canvas-tokens.md

@@ -0,0 +1,12 @@
+# HTML canvas and tokens
+
+Instantiate an empty canvas.html skeleton with explicit user facts. canvas.html is the sole maintained structure. Gallery previews bind explicit fictional sample-profile.json through the same instantiator and full CSS chain; sample data must never serve as default candidate facts. Shared normalization accepts omitted/null optional fields and rejects invalid types. Failed binding must preserve old output and return nonzero.
+
+Tune the run's HTML with CSS variables for section/item/bullet spacing and body typography. Preserve manually edited content rather than regenerating stale profile data. Auto-healing cannot remove facts or reduce body font below 8.8pt. Validate in print mode, inspect all pages and verify the actual PDF before delivery. See 07-artifact-contract.md.
+
+
+## 本地字体与缺字诊断
+
+`forge.py` 和 `instantiate-resume.py` 支持 `--font-preset system|arial-unicode`，默认保留系统字体。`arial-unicode` 显式使用本机 Arial Unicode MS；没有该字体时字体验收失败并返回 UNVERIFIED，不保证跨机器可用，也不自动下载字体。字体选择只改变画布样式，不改变 Master 事实，并记录在 Variant 的 source.fontPreset 和运行清单中。
+
+中文 PDF 若文本验收失败，检查 QA 每页的 missingCodepoints、missingFragments 与 extractedRadicals。部首字符可能来自字体字码映射差异，也可能存在真实缺字；不能仅凭这种提示放行。可选用本机可用字体、创建新运行并重新检查，不改写姓名/经历来绕过问题，也不把部首字符全部忽略。

package/references/06-qa-and-rendering.md

@@ -0,0 +1,14 @@
+# QA and final rendering
+
+Validation and rendering use scripts/rendering/browser-engine.js. Inspect print media after fonts settle, every page container and visible content boundary; generate a fresh PDF and parse every page for A4 portrait dimensions, allowed page count and extractable content matching the canvas.
+
+PASS requires the actual checks to complete. Missing browser/dependencies or timeout is UNVERIFIED (exit 2), a failed check is FAIL (exit 1). JSON mode uses the same exit rules. Do not use an estimate or an existing PDF as proof. Export verified bytes through a temporary file and atomic replacement; failed export retains the previous file.
+
+The pipeline isolates each run and records artifact hashes in manifest.json. Use its current PASS output paths, not shared default filenames. Factual and visual review remain Agent responsibilities; text extraction does not certify every ATS. See 07-artifact-contract.md for the complete lifecycle.
+
+
+## 本地字体与缺字诊断
+
+`forge.py` 和 `instantiate-resume.py` 支持 `--font-preset system|arial-unicode`，默认保留系统字体。`arial-unicode` 显式使用本机 Arial Unicode MS；没有该字体时字体验收失败并返回 UNVERIFIED，不保证跨机器可用，也不自动下载字体。字体选择只改变画布样式，不改变 Master 事实，并记录在 Variant 的 source.fontPreset 和运行清单中。
+
+中文 PDF 若文本验收失败，检查 QA 每页的 missingCodepoints、missingFragments 与 extractedRadicals。部首字符可能来自字体字码映射差异，也可能存在真实缺字；不能仅凭这种提示放行。可选用本机可用字体、创建新运行并重新检查，不改写姓名/经历来绕过问题，也不把部首字符全部忽略。

package/references/07-artifact-contract.md

@@ -0,0 +1,64 @@
+# 资料、运行与验收契约
+
+## Draft / Master / Variant
+
+这三个值表示资料用途，不是质量评分，也不表示已独立核实事实。
+
+| kind | 用途 | 约束 |
+| --- | --- | --- |
+| draft | 用户资料尚不完整的草稿 | 可缺姓名及经历；仅生成草稿画布，不能报告 PDF 已验收 |
+| master | 用户或 Agent 整理的完整事实集合 | 每次运行只保存新快照，不反写输入；完整指保留本次已知事实，不强制具备所有可选字段 |
+| variant | 为目标岗位派生的展示资料 | 记录来源 Master 的 profileSha256；岗位标题只修改 Variant，不回写 Master；不能作为下一份 Master 隐式导入 |
+
+标准文档形状为：
+
+```json
+{
+  "schemaVersion": "1.0",
+  "kind": "master",
+  "profile": {"basics": {"name": "候选人姓名"}},
+  "source": {"type": "user-input"}
+}
+```
+
+`profile` 的字段定义见 `src/knowledge/resume-schema.json`；脚本 `scripts/contracts/profile.py` 是归一化与封装契约的实现。脚本输出时附加 `profileSha256` 和 `missingFields`。摘要用于发现资料版本变化，不证明用户陈述真实性。手动修改封装资料后，应重新生成摘要或移除旧摘要再读入；不能保留不匹配的摘要。
+
+兼容旧版的裸 profile JSON，按调用者明确提供的 Master 事实输入处理。封装为 Draft 的输入必须加 `--draft` 才能生成草稿；复核后由 Agent 显式整理为 Master，不由工具自动升级。Variant 的语义改写与事实选择仍由宿主 Agent 完成；当前脚本保留所有输入条目，只处理显式基础信息覆盖、岗位标题及展示装配。
+
+## 缺失值
+
+- 可选字段省略或 null 均表示未知，空白字符串归为 null，不生成占位候选人事实。
+- null 的数组归为空数组；数组中的空白/null 项省略。未知字段和错误类型拒绝，不能悄悄丢失可能重要的资料。
+- 教育经历、项目和工作经历为独立数组，按输入顺序完整处理；无教育描述不补“优秀毕业生”等默认荣誉。
+- 缺失联系方式和目标岗位记录为待补信息。正式交付至少需要非空姓名及实质内容，打印与 PDF 验收进一步判断内容有效性。
+- 旧版 L1/L2/L3 元数据可保留；用户陈述不因为来自对话就自动降级为“参与”。
+
+## 每次运行独立
+
+`forge --profile-json <file>` 在 `workspace/runs/<唯一运行ID>/` 下创建私有目录，包含 `input.json` 原始输入快照、`master.json`、`variant.json`、`resume.html`、`qa.json`、通过验收后写入的 `resume.pdf` 和 `manifest.json`。Draft 运行保存 `draft.json` 和草稿画布，不生成正式 PDF。
+
+`--workspace` 仅改变运行目录的父目录，不复用已有运行。失败现场保留供诊断，不自动删除或继续使用其他运行的文件。目录包含个人资料，不提交到 Git；可由用户按需删除。测试必须使用临时目录。
+
+`--html-output` 和 `--output` 是可选的已验收副本路径。先在独立运行中完成验证，再一起准备副本；写入失败时回滚普通错误，目标锁阻止两个本工具进程交错写入。跨文件复制不具备操作系统崩溃下的事务保证，因此运行目录和 manifest 始终是交付判据。发现遗留锁时报告冲突，不擅自删除其他运行的锁。
+
+## 运行与检查状态
+
+| status | 退出码 | 意义 |
+| --- | --- | --- |
+| RUNNING | 不作为最终结果 | 已开始但未完成，不能交付 |
+| DRAFT | 0 | 草稿准备完成，无 PDF 验收承诺 |
+| PASS | 0 | 本次指定检查及最终 PDF 验收通过 |
+| FAIL | 1 | 输入、绑定、布局、PDF 内容或输出写入不符合要求 |
+| UNVERIFIED | 2 | 浏览器、依赖、超时或检查协议故障，无法完成验收 |
+
+`manifest.json` 包含 `runId`、`stage`、`errors`、`warnings`、`checks`、`outputs`。失败的 `outputs` 为空，即使目录或显式输出位置存在旧 PDF，也不能返回它作为本次交付。只有 PASS 的清单记录本次输出路径及 HTML/PDF SHA-256。JSON 模式与人读模式使用同一退出语义。
+
+## 打印与最终 PDF
+
+布局与导出共用 `scripts/rendering/browser-engine.js`，以 print 媒体模式等待字体，检查所有页面容器与内容边界。再生成新的 PDF，解析所有页，检查 A4 纵向尺寸、页数上限、逐页可提取文本与正文覆盖。最终写入的是通过验收的 PDF 字节，使用临时文件原子替换，不接受旧输出文件作为生成成功的证据。
+
+自动调优不得增加当前间距，正文字号不降至 8.8pt 以下；调优失败保留原画布，不删改事实来强行过关。浏览器不可用不得用字数/盒模型估算替代 PASS。PDF 文本提取通过不代表所有 ATS 对多栏阅读顺序的解释一致；事实与视觉仍需 Agent 复核。
+
+当前分页契约要求每个 `.resume-page` 对应一个 A4 页面，`--expected-pages` 为 1 或 2 的上限。一页文档可用上限 2；两页文档需由 Agent 显式建立两个页面容器。单个超高容器自然流入多页会被拒绝，不猜测浏览器分页后每页应有的内容。
+
+输入文档的来源说明保存在 Master 的 source.suppliedSource 中，包括 synthetic-simulation 等原始标签。它是来源元数据，不是新增候选人事实。字体预设单独记录为 Variant.source.fontPreset；不得把字体修订误记为事实变更。

package/scripts/Agent.md

@@ -1,138 +1,11 @@
-# KnowMe CareerForge — Scripts Architecture & Agent Execution Specification
+# Script responsibilities
 
-> **定位**：面向 AI Agent 与研发工程师的 `scripts/` 工具链架构规范、模块划分标准与执行契约手册。
->
-> **版本**：v1.0.0-modular  
-> **核心原则**：Domain-Driven Modularization · Quiet Agent Execution · Deterministic Rendering · Zero-Dependency Python Core
+- contracts/: shared Draft/Master/Variant normalization and missing-value rules.
+- pipeline/: unique run directory, immutable input snapshot, Master and Variant lineage, explicit result manifest and verified copies.
+- evidence/: optional JD helpers; legacy extract-evidence.py is not a supported candidate input path.
+- template/: template ranking and deterministic fact-only canvas binding.
+- validation/: print-mode geometry and content checks through the shared browser engine; no estimate-based PASS.
+- rendering/: final PDF page/text validation and atomic write, preserving old outputs on failure.
+- build/: package, gallery and test utilities. Tests must write only to temporary directories.
 
----
-
-## 1. 目录架构与模块职责划分 (Domain Architecture)
-
-为了保证脚本工具链的高内聚、低耦合与易维护性，`scripts/` 目录划分为 **6 大功能领域模块**：
-
-```text
-scripts/
-├── Agent.md                         # 本规范文档 (Source of Truth for Agent/Dev)
-│
-├── pipeline/                        # 【模块 1: 端到端统筹管线】
-│   └── forge.py                     # 一键端到端装配引擎 (One-Shot Pipeline: 挖掘 -> 装配 -> QA -> PDF)
-│
-├── evidence/                        # 【模块 2: 事实与证据挖掘 (repo-to-resume)】
-│   ├── extract-evidence.py          # 代码仓与 Git 事实挖掘器 (提取技术栈、架构信号、Git 贡献 -> L1~L3 证据链)
-│   └── analyze-jd.py                # 目标 JD 深度分析器 (提取职级、分类、必备/加分项、痛点关键词)
-│
-├── template/                        # 【模块 3: 模板检索与工作区装配】
-│   ├── search-template.py           # 多维加权打分搜索引擎 (BM25 + 岗位/风格/页数/密度推荐)
-│   └── instantiate-resume.py        # 模板装配与数据注入引擎 (CSS 内联单文件 + 结构化数据注入 + 关键词高亮)
-│
-├── validation/                      # 【模块 4: 双重 QA 自动化质检】
-│   ├── validate-resume.py           # 语义结构、Design Tokens 与字符密度轻量校验器
-│   ├── validate-layout.ts           # Playwright DOM 盒模型物理高度 (1122.5px A4) 溢出与孤行检测
-│   └── validate-ats.ts              # ATS 纯文本流解析、联系方式与 H1/H2 标头层级校验
-│
-├── rendering/                       # 【模块 5: 确定性 PDF 渲染导出】
-│   ├── render-pdf.py                # 跨平台自愈式 PDF 渲染调度器 (自动探测 Playwright 及全平台 Chromium/Edge/Brave)
-│   └── render-pdf.ts                # Playwright 驱动的无损矢量 A4 PDF 渲染器
-│
-└── build/                           # 【模块 6: 编译构建、测试与发布工具链】
-    ├── build-knowledge.py           # 岗位画像与模板知识库索引编译器 (生成 index.json & templates.json)
-    ├── build-gallery.py             # 静态交互式模板画廊生成器 (编译 output/templates_gallery/)
-    ├── run-all-tests.py             # 全链路自动化测试运行器 (discover & run tests/)
-    ├── sync-version.py              # 多清单版本号同步器 (package.json / pyproject.toml / skill.json / cli)
-    └── release.py                   # 自动化发布流水线引擎 (版本对齐 -> 编译 -> 测试 -> 打包预检)
-```
----
-
-## 2. 脚本契约与 Agent 调用规范 (Execution Contracts)
-
-### 2.1 推荐调用模式：一键直达管线 (One-Shot Execution)
-
-AI Agent 响应用户求职定制需求时，**强烈推荐首选一键管线**：
-
-```bash
-# 静默全流程执行 (后台自动完成：代码仓扫描 -> 模板检索 -> 工作区注入 -> Dual QA -> PDF 导出)
-python3 scripts/pipeline/forge.py --repo . --role "<Target Role>" --jd "<path/to/jd.txt>" --template modern --quiet
-```
-* **CLI 等价形式**：`knowme forge --repo . --role "<Target Role>" --template modern --quiet`
-* **返回格式**：结构化 JSON，供 Agent 直接获取交付文件路径：
-  ```json
-  {
-    "status": "SUCCESS",
-    "htmlCanvas": "workspace/resume.html",
-    "pdfDelivery": "workspace/resume.pdf",
-    "evidenceProfile": "workspace/evidence-master.json",
-    "templateUsed": "modern"
-  }
-  ```
-
----
-
-### 2.2 细粒度分步调用接口 (Granular Step-by-Step APIs)
-
-当 Agent 或用户需要分步微调、审查证据或调校 Design Tokens 时，按以下顺序执行：
-
-| 步骤 | 阶段 | 推荐命令 | 关键参数 | 产出物 |
-| :--- | :--- | :--- | :--- | :--- |
-| **Step 1** | **事实挖掘** | `python3 scripts/evidence/extract-evidence.py` | `--repo <dir>` `--name <name>` `--quiet` | `workspace/evidence-master.json` |
-| **Step 2** | **JD 解析** | `python3 scripts/evidence/analyze-jd.py` | `--jd <file>` 或 `--text "<str>"` `--json` | 提取必须技能与权重关键词 |
-| **Step 3** | **模板检索** | `python3 scripts/template/search-template.py` | `"<Role>"` `--style "<style>"` `--json` | 加权推荐模板列表 (Top 1) |
-| **Step 4** | **画布装配** | `python3 scripts/template/instantiate-resume.py` | `--template <id>` `--profile <json>` `--keywords <kw>` | `workspace/resume.html` (单文件内联) |
-| **Step 5** | **质检自愈** | `python3 scripts/validation/validate-resume.py` | `--html workspace/resume.html` `--expected-pages 1` | QA 诊断状态与溢出提示 |
-| **Step 6** | **PDF 导出** | `python3 scripts/rendering/render-pdf.py` | `workspace/resume.html` `workspace/resume.pdf` `--quiet` | `workspace/resume.pdf` (确定性矢量) |
-
----
-
-## 3. Agent 对话降噪规范 (Strict Quiet Execution Protocol)
-
-为了杜绝对话框中出现几百行冗余代码或中间脚本，所有接入的 AI Agent 必须遵守以下铁律：
-
-1. **禁止在 Chat 中打印原始 HTML/CSS**：禁止将 `workspace/resume.html` 的数百行代码打印到对话框中；
-2. **禁止在 Chat 中编写现场临时脚本**：严禁现场生成临时验证脚本或修改场脚本，必须使用 `scripts/` 下既有的标准工具链；
-3. **静默执行原则**：调用脚本时统一添加 `--quiet` 或 `--json` 参数；
-4. **标准交付物格式**：
-   ```markdown
-   ### 🎯 职业定位与核心价值主张 (Core Value Proposition)
-   > **[姓名] · [目标岗位]**
-   > *[15~25字核心定位与价值阐述]*
-
-   ---
-
-   ### 🛡️ Top 3 真实证据链亮点 (L1/L2 级别可追溯事实)
-   1. **[业务方向/核心架构]**: [动词 + 可量化成果 + 证据来源]
-   2. **[核心技术栈工程化]**: [关键框架与工程规范落地]
-   3. **[交付与系统效能]**: [稳定性/CI-CD/性能指标]
-
-   ---
-
-   ### 📄 最终交付产物
-   - **PDF 终稿 (确定性 A4)**: `workspace/resume.pdf`
-   - **HTML 修改场 (Design Tokens)**: `workspace/resume.html`
-   - **证据事实底座**: `workspace/evidence-master.json`
-   ```
-
----
-
-## 4. 后续开发与扩展规范 (Developer Standards)
-
-为保持工程整洁与跨平台稳定性，后续新增或修改脚本必须遵循以下标准：
-
-### 4.1 根路径自适应解析 (Root Path Resolution Standard)
-所有 Python 脚本**严禁使用硬编码相对路径**，必须通过自适应探测函数定位项目根目录：
-```python
-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()
-```
-
-### 4.2 零重型依赖原则 (Zero-Heavy-Dependency)
-* 核心运行脚本（`evidence/`、`template/`、`pipeline/`）**仅使用 Python 3.9+ 标准库**（`json`, `argparse`, `pathlib`, `re`, `subprocess` 等）；
-* 避免引入大型三方包（如 pandas、scikit-learn），保证轻量秒开与跨平台零安装成本。
-
-### 4.3 渲染与 QA 规范
-* A4 绝对高度基准固化为 `1122.5px` ($297\text{mm} \times 96\text{DPI} / 25.4$)；
-* 任何涉及排版验证与 PDF 导出的改动，必须通过 `scripts/build/run-all-tests.py` 全量测试套件验证。
+Read ../references/07-artifact-contract.md for the authoritative artifact lifecycle, status/exit-code rules and output contract. Runtime scripts are resolved from the Skill installation; candidate artifacts belong to the user's workspace. A Draft is useful output but is never a verified PDF. FAIL and UNVERIFIED are nonzero exits in JSON and human-readable modes.