knowme-careerforge-skill 0.0.4 → 0.0.7

package/references/07-artifact-contract.md

@@ -0,0 +1,83 @@
+# 资料、运行与验收契约
+
+## 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；不得把字体修订误记为事实变更。
+
+## 简短输入与交付入口
+
+Agent 可直接整理裸 profile；只填写用户提供的值，删除未知字段及不需要的章节。以下尖括号仅说明字段含义，不能作为候选人数据执行：
+
+```json
+{
+  "basics": {"name": "<用户姓名>", "title": "<目标岗位>"},
+  "skills": [{"category": "<分组>", "items": ["<用户提供的技能>"]}],
+  "experience": [{"company": "<公司>", "role": "<实际职务>",
+    "startDate": "<开始时间>", "endDate": "<结束时间>",
+    "bullets": [{"text": "<用户提供的职责或成果>"}]}],
+  "education": [{"degree": "<学历>", "field": "<专业>"}]
+}
+```
+
+姓名和至少一个实质章节是当前 PDF 输入门槛；联系方式、学校、专业和日期允许未知。`missingFields` 仅列出 basics.name/title/email/phone 的缺失，空列表不表示所有字段完整，更不证明事实真实。
+
+`forge.py --summary` 仅精简终端报告，包含当前状态、模板、错误、仅 html/pdf 的 outputs 和 manifest 路径；默认及 `--quiet` 仍保留完整 JSON。完整 manifest 与 QA 始终落盘。正常交付用 `--output resume/resume.pdf --html-output resume/resume.html` 创建验收副本；内部运行历史不作为用户默认交付清单。失败时副本可能仍为旧版本，不能据此报告本次成功。Draft 不使用这些验收副本选项。

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.

package/scripts/build/build-gallery.py

@@ -4,7 +4,13 @@ KnowMe CareerForge — Template Gallery Builder
 扫描验证 src/templates/ 核心模板，生成 output/templates_gallery/ 静态可视化画廊。
 """
 
-import os, sys, json, re
+import argparse
+import importlib.util
+import json
+import os
+import sys
+import tempfile
+from html import escape
 from pathlib import Path
 
 def get_project_root() -> Path:
@@ -15,61 +21,55 @@ def get_project_root() -> Path:
         curr = curr.parent
     return Path.cwd()
 
-def build_gallery():
-    base_dir = get_project_root()
-    templates_dir = base_dir / "src" / "templates"
-    gallery_dir = base_dir / "output" / "templates_gallery"
+def load_instantiator():
+    spec = importlib.util.spec_from_file_location(
+        "gallery_instantiator", get_project_root() / "scripts/template/instantiate-resume.py")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def build_gallery(output_dir=None, font_preset="system"):
+    """Validate and stage every preview before publishing; publish the index last."""
+    gallery_dir = Path(output_dir) if output_dir else get_project_root() / "output/templates_gallery"
     gallery_dir.mkdir(parents=True, exist_ok=True)
-    
-    gallery_items = []
+    with tempfile.TemporaryDirectory(prefix=".gallery-", dir=gallery_dir) as scratch:
+        stage = Path(scratch)
+        _render_gallery(stage, font_preset)
+        for preview in sorted(stage.glob("*.html")):
+            if preview.name != "index.html":
+                os.replace(preview, gallery_dir / preview.name)
+        os.replace(stage / "index.html", gallery_dir / "index.html")
+    return gallery_dir / "index.html"
 
-    print("==============================================================")
-    print("  KnowMe CareerForge — Template Gallery Builder")
-    print("==============================================================")
 
+def _render_gallery(gallery_dir, font_preset):
+    templates_dir = get_project_root() / "src/templates"
+    binder = load_instantiator()
+    gallery_items = []
     for t_dir in sorted(templates_dir.iterdir()):
         if not t_dir.is_dir() or t_dir.name == "common":
             continue
-            
-        html_file = t_dir / "template.html"
-        css_file = t_dir / "style.css"
-        meta_file = t_dir / "metadata.json"
-
-        if not html_file.exists() or not css_file.exists() or not meta_file.exists():
-            print(f"[!] Skipping incomplete template: {t_dir.name}")
-            continue
-
-        try:
-            meta = json.loads(meta_file.read_text(encoding="utf-8"))
-            html_content = html_file.read_text(encoding="utf-8")
-            css_content = css_file.read_text(encoding="utf-8")
-
-            # 编译内联单文件独立预览页面
-            inlined_preview = html_content.replace(
-                '<link rel="stylesheet" href="style.css">',
-                f'<style>\n{css_content}\n  </style>'
-            )
-
-            preview_path = gallery_dir / f"{t_dir.name}.html"
-            preview_path.write_text(inlined_preview, encoding="utf-8")
-
-            gallery_items.append({
-                "id": meta.get("id", t_dir.name),
-                "name": meta.get("name", t_dir.name),
-                "style": meta.get("style", "single-column"),
-                "category": meta.get("roleCategory", "engineering-ai"),
-                "tone": meta.get("visualStyle", {}).get("tone", "modern"),
-                "accent": meta.get("visualStyle", {}).get("accentColor", "#2563eb"),
-                "pages": meta.get("layout", {}).get("targetPages", 1),
-                "density": meta.get("layout", {}).get("density", "balanced"),
-                "atsTier": meta.get("atsScoreTier", "tier-1-optimal"),
-                "previewFile": f"{t_dir.name}.html",
-                "supported": meta.get("supportedRoles", [])
-            })
-            print(f"[✓] Generated Gallery Preview -> {preview_path.name}")
-        except Exception as e:
-            print(f"[✗] Error processing {t_dir.name}: {e}")
-
+        for name in ("canvas.html", "sample-profile.json", "style.css", "metadata.json"):
+            if not (t_dir / name).is_file():
+                raise ValueError(f"Incomplete template {t_dir.name}: missing {name}")
+        meta = json.loads((t_dir / "metadata.json").read_text(encoding="utf-8"))
+        binder.instantiate_workspace(
+            t_dir.name, profile_path=t_dir / "sample-profile.json",
+            output_path=gallery_dir / f"{t_dir.name}.html", quiet=True,
+            font_preset=font_preset)
+        gallery_items.append({
+            "name": meta.get("name", t_dir.name),
+            "style": meta.get("style", "single-column"),
+            "tone": meta.get("visualStyle", {}).get("tone", "modern"),
+            "pages": meta.get("layout", {}).get("targetPages", 1),
+            "density": meta.get("layout", {}).get("density", "balanced"),
+            "atsTier": meta.get("atsScoreTier", "unspecified"),
+            "previewFile": f"{t_dir.name}.html",
+            "supported": meta.get("supportedRoles", [])
+        })
+    if not gallery_items:
+        raise ValueError("No templates found")
     # 生成主索引 index.html
     gallery_html = f"""<!DOCTYPE html>
 <html lang="zh-CN">
@@ -217,18 +217,20 @@ def build_gallery():
   <div class="gallery-container">
     <header>
       <h1>KnowMe CareerForge — Template Gallery</h1>
-      <p class="subtitle">A4 Deterministic HTML Resume Templates with Design Tokens Calibration</p>
+      <p class="subtitle">虚构样例 · 与实际简历共用 canvas.html 和完整样式 · ATS 标签仅代表设计目标</p>
     </header>
     <div class="grid">
 """
 
-    for item in gallery_items:
+    for raw_item in gallery_items:
+        item = {k: ([escape(str(v)) for v in value] if isinstance(value, list) else escape(str(value), quote=True))
+                for k, value in raw_item.items()}
         tags_html = "".join([f'<span class="tag">{r}</span>' for r in item['supported'][:5]])
         gallery_html += f"""
       <div class="card">
         <div class="card-header">
           <span class="card-title">{item['name']}</span>
-          <span class="badge optimal">ATS Tier 1</span>
+          <span class="badge">{item['atsTier']}</span>
         </div>
         <div class="preview-frame-wrapper">
           <iframe class="preview-frame" src="{item['previewFile']}"></iframe>
@@ -255,8 +257,16 @@ def build_gallery():
 """
     gallery_index = gallery_dir / "index.html"
     gallery_index.write_text(gallery_html, encoding="utf-8")
-    print(f"\n[✓] Generated Gallery Master Index -> {gallery_index}")
-    print("==============================================================")
+
 
 if __name__ == "__main__":
-    build_gallery()
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--output", type=Path, help="Gallery output directory")
+    parser.add_argument("--font-preset", choices=("system", "arial-unicode"), default="system")
+    args = parser.parse_args()
+    try:
+        index = build_gallery(args.output, args.font_preset)
+        print(json.dumps({"status": "PASS", "index": str(index)}, ensure_ascii=False))
+    except Exception as exc:
+        print(json.dumps({"status": "FAIL", "error": str(exc)}, ensure_ascii=False), file=sys.stderr)
+        sys.exit(1)

package/scripts/build/run-all-tests.py

@@ -19,6 +19,7 @@ def run_all_test_suites():
     start_time = time.time()
     base_dir = get_project_root()
     tests_dir = base_dir / "tests"
+    sys.path.insert(0, str(base_dir))
 
     print("==============================================================")
     print("  KnowMe CareerForge — Full-Chain Automated Test Suite")

package/scripts/build/sync-version.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """
 KnowMe CareerForge — Version Synchronization Engine
-将项目根版本号统一同步至 package.json, pyproject.toml, skill.json, cli/package.json, SKILL.md, agents/*, Agent.md。
+将项目根版本号统一同步至 package.json, pyproject.toml, skill.json, cli/package.json, npm 锁文件, SKILL.md, agents/*, CLI 与知识索引。
 """
 
 import sys, os, json, re, argparse
@@ -18,7 +18,11 @@ def get_project_root() -> Path:
 def sync_version(new_version: str):
     base_dir = get_project_root()
     # 去除可能传入的 'v' 前缀
-    semver = new_version.lstrip("v")
+    semver = new_version.removeprefix("v")
+    core = r"(?:0|[1-9][0-9]*)"
+    prerelease = r"(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)"
+    if not re.fullmatch(rf"{core}\.{core}\.{core}(?:-{prerelease}(?:\.{prerelease})*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?", semver):
+        raise ValueError(f"Invalid semantic version: {new_version}")
 
     print("==============================================================")
     print(f"  KnowMe CareerForge — Synchronizing Version to v{semver}")
@@ -40,6 +44,17 @@ def sync_version(new_version: str):
         cli_pkg_path.write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
         print(f"[✓] Synced cli/package.json -> {semver}")
 
+    # Lockfiles carry the package version separately from dependency versions.
+    for relative in ("package-lock.json", "cli/package-lock.json"):
+        lock_path = base_dir / relative
+        if lock_path.exists():
+            data = json.loads(lock_path.read_text(encoding="utf-8"))
+            data["version"] = semver
+            if "" in data.get("packages", {}):
+                data["packages"][""]["version"] = semver
+            lock_path.write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+            print(f"[✓] Synced {relative} -> {semver}")
+
     # 3. Update skill.json
     skill_json_path = base_dir / "skill.json"
     if skill_json_path.exists():
@@ -60,7 +75,7 @@ def sync_version(new_version: str):
     skill_md_path = base_dir / "SKILL.md"
     if skill_md_path.exists():
         text = skill_md_path.read_text(encoding="utf-8")
-        new_text = re.sub(r'version:\s*[\d.]+', f'version: {semver}', text)
+        new_text = re.sub(r'(?m)^(\s*version:)[ \t]*[^\r\n]+$', lambda m: f'{m[1]} {semver}', text)
         skill_md_path.write_text(new_text, encoding="utf-8")
         print(f"[✓] Synced SKILL.md -> {semver}")
 
@@ -68,7 +83,7 @@ def sync_version(new_version: str):
     codex_yaml = base_dir / "agents" / "codex" / "knowme-careerforge.yaml"
     if codex_yaml.exists():
         text = codex_yaml.read_text(encoding="utf-8")
-        new_text = re.sub(r'version:\s*[\d.]+', f'version: {semver}', text)
+        new_text = re.sub(r'(?m)^(\s*version:)[ \t]*[^\r\n]+$', lambda m: f'{m[1]} {semver}', text)
         codex_yaml.write_text(new_text, encoding="utf-8")
         print(f"[✓] Synced agents/codex/knowme-careerforge.yaml -> {semver}")
 
@@ -76,7 +91,7 @@ def sync_version(new_version: str):
     opencode_yaml = base_dir / "agents" / "opencode" / "skill.yaml"
     if opencode_yaml.exists():
         text = opencode_yaml.read_text(encoding="utf-8")
-        new_text = re.sub(r'version:\s*[\d.]+', f'version: {semver}', text)
+        new_text = re.sub(r'(?m)^(\s*version:)[ \t]*[^\r\n]+$', lambda m: f'{m[1]} {semver}', text)
         opencode_yaml.write_text(new_text, encoding="utf-8")
         print(f"[✓] Synced agents/opencode/skill.yaml -> {semver}")
     # 8. Update cli/src/index.ts fallback version
@@ -84,7 +99,7 @@ def sync_version(new_version: str):
     if cli_ts_path.exists():
         text = cli_ts_path.read_text(encoding="utf-8")
         new_text = re.sub(r"return\s+data\.version\s*\|\|\s*'[^']+'", f"return data.version || '{semver}'", text)
-        new_text = re.sub(r"return\s+'[^']+'\s*;", f"return '{semver}';", new_text)
+        new_text = re.sub(r"return\s+'\d+\.\d+\.\d+[^']*'\s*;", f"return '{semver}';", new_text)
         cli_ts_path.write_text(new_text, encoding="utf-8")
         print(f"[✓] Synced cli/src/index.ts -> {semver}")
 
@@ -101,16 +116,19 @@ def sync_version(new_version: str):
     kb_script = base_dir / "scripts" / "build" / "build-knowledge.py"
     if kb_script.exists():
         import subprocess
-        subprocess.run([sys.executable, str(kb_script)], stdout=subprocess.DEVNULL)
+        subprocess.run([sys.executable, str(kb_script)], stdout=subprocess.DEVNULL, check=True)
         print(f"[✓] Recompiled knowledge index -> v{semver}")
 
     print("\n[✓] All package versions successfully synchronized!")
 
 def main():
     parser = argparse.ArgumentParser(description="Synchronize project version")
-    parser.add_argument("version", nargs="?", default="0.0.2", help="New semantic version (e.g. 0.0.2)")
+    parser.add_argument("version", help="Required target semantic version (e.g. 0.0.6)")
     args = parser.parse_args()
-    sync_version(args.version)
+    try:
+        sync_version(args.version)
+    except (ValueError, OSError) as error:
+        parser.exit(1, f"Version synchronization failed: {error}\n")
 
 if __name__ == "__main__":
     main()

package/scripts/contracts/profile.py

@@ -0,0 +1,101 @@
+"""Shared input contract. Structural validity does not certify candidate facts."""
+import copy
+import hashlib
+import json
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+SCHEMA = json.loads((ROOT / 'src/knowledge/resume-schema.json').read_text(encoding='utf-8'))
+
+class ContractError(ValueError):
+    pass
+
+
+def _normalize(value, schema, path):
+    types = schema.get('type', [])
+    types = [types] if isinstance(types, str) else types
+    if value is None:
+        if 'null' not in types:
+            raise ContractError(path + ': null is not allowed')
+        return [] if 'array' in types else {} if 'object' in types else None
+    if isinstance(value, str):
+        if 'string' not in types:
+            raise ContractError(path + ': expected ' + '/'.join(types))
+        value = value.strip() or None
+        if value is not None and 'enum' in schema and value not in schema['enum']:
+            raise ContractError(path + ': invalid value')
+        return value
+    if isinstance(value, dict) and 'object' in types:
+        properties = schema.get('properties', {})
+        unknown = set(value) - set(properties)
+        if unknown:
+            raise ContractError(path + ': unsupported fields: ' + ', '.join(sorted(unknown)))
+        result = {}
+        for key, child in properties.items():
+            if key in value:
+                item = _normalize(value[key], child, path + '.' + key)
+                if item is not None and item != {} and item != []:
+                    result[key] = item
+        return result
+    if isinstance(value, list) and 'array' in types:
+        values = [_normalize(item, schema['items'], path + '[' + str(i) + ']') for i, item in enumerate(value)]
+        return [item for item in values if item is not None and item != '' and item != {}]
+    raise ContractError(path + ': expected ' + '/'.join(types))
+
+
+def normalize_profile(raw):
+    result = _normalize(raw, SCHEMA, 'profile')
+    result.setdefault('basics', {})
+    for field in ('skills', 'experience', 'projects', 'education', 'certifications'):
+        result.setdefault(field, [])
+    return result
+
+
+def digest(value):
+    return hashlib.sha256(json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(',', ':')).encode()).hexdigest()
+
+
+def missing_fields(profile):
+    # Informational gaps; optional omissions never turn into invented defaults.
+    return ['basics.' + field for field in ('name', 'title', 'email', 'phone')
+            if not profile.get('basics', {}).get(field)]
+
+
+def delivery_errors(profile):
+    errors = []
+    if not profile['basics'].get('name'):
+        errors.append('A non-empty candidate name is required for delivery')
+    if not any(profile.get(key) for key in ('experience', 'projects', 'education', 'skills', 'certifications')):
+        errors.append('At least one substantive resume section is required for delivery')
+    return errors
+
+
+def document(kind, profile, source=None):
+    if kind not in ('draft', 'master', 'variant'):
+        raise ContractError('Unknown document kind: ' + str(kind))
+    profile = normalize_profile(profile)
+    return {'schemaVersion': '1.0', 'kind': kind, 'profile': profile,
+            'profileSha256': digest(profile), 'missingFields': missing_fields(profile),
+            'source': copy.deepcopy(source or {})}
+
+
+def load_document(raw):
+    if not isinstance(raw, dict):
+        raise ContractError('Profile document must be an object')
+    if 'profile' not in raw:
+        # Existing --profile-json inputs are explicit user/Agent supplied facts.
+        return document('master', raw, {'type': 'legacy-user-input'})
+    unknown = set(raw) - {'schemaVersion', 'kind', 'profile', 'profileSha256', 'missingFields', 'source'}
+    if unknown:
+        raise ContractError('Unsupported document fields: ' + ', '.join(sorted(unknown)))
+    if raw.get('schemaVersion') != '1.0':
+        raise ContractError('Unsupported profile schemaVersion')
+    source = raw.get('source', {})
+    if not isinstance(source, dict):
+        raise ContractError('Document source must be an object')
+    result = document(raw.get('kind'), raw['profile'], source)
+    if raw.get('profileSha256') and result['profileSha256'] != raw['profileSha256']:
+        raise ContractError('Profile hash mismatch; regenerate metadata after editing facts')
+    if result['kind'] == 'variant' and not source.get('masterSha256'):
+        raise ContractError('Variant requires source.masterSha256')
+    return result