knowme-careerforge-skill 0.0.4 → 0.0.7

package/scripts/template/instantiate-resume.py

@@ -1,184 +1,277 @@
 #!/usr/bin/env python3
-"""
-KnowMe CareerForge — Resume Workspace Instantiator (Intermediate Working Canvas)
-将指定模板、候选人结构化事实档案 (evidence-master.json) 与 JD 关键词高亮组装为自包含的单文件 HTML 工作区修改场。
+"""Bind supplied facts to independent blank canvases; publish only complete output.
+
+canvas.html owns layout, not candidate content. Each <!-- resume:NAME --> slot
+must occur exactly once. sample-profile.json is gallery-only input, never an automatic fallback.
+The shared profile contract validates and normalizes every input document.
+Omitting --profile deliberately produces a blank canvas.
 """
 
-import sys, os, json, argparse, re
+import argparse
+from collections import Counter
+from html import escape
+from html.parser import HTMLParser
+import json
+import importlib.util
+import os
 from pathlib import Path
-from typing import Dict, Any, Optional, List
+import re
+import sys
+import tempfile
+
+SLOTS = {"styles", "document-title", "basics", "summary", "skills",
+         "experience", "projects", "education", "certifications", "language"}
+SLOT = re.compile(r"<!-- resume:([a-z-]+) -->|{{ resume:(language) }}")
+LABELS = {
+    "zh": {"document-title": "个人简历", "summary": "个人简介", "skills": "专业技能",
+           "experience": "工作经历", "projects": "项目经历", "education": "教育背景", "certifications": "证书"},
+    "en": {"document-title": "Resume", "summary": "Summary", "skills": "Skills",
+           "experience": "Experience", "projects": "Projects", "education": "Education", "certifications": "Certifications"},
+}
+
+
+
+FONT_PRESETS = {
+    "system": "",
+    "arial-unicode": """/* Explicit local font: a missing face must fail font QA, not silently pass. */
+@font-face { font-family: "KnowMe Unicode"; src: local("Arial Unicode MS"); font-weight: 400; font-style: normal; }
+:root { --primitive-font-sans: "KnowMe Unicode", Arial, sans-serif; --resume-font-body: "KnowMe Unicode", Arial, sans-serif; }
+""",
+}
+
 
 def get_project_root() -> Path:
-    curr = Path(__file__).resolve().parent
-    for _ in range(5):
-        if (curr / "SKILL.md").exists() or (curr / "package.json").exists() or (curr / "src" / "templates").exists():
-            return curr
-        curr = curr.parent
-    return Path.cwd()
-
-def highlight_keywords(text: str, keywords: List[str]) -> str:
-    if not keywords or not text:
-        return text
-    for kw in keywords:
-        kw_clean = kw.strip()
-        if kw_clean:
-            pattern = re.compile(rf'(?<!<strong>)(?<![<\w/])({re.escape(kw_clean)})(?![>\w])(?!</strong>)', re.IGNORECASE)
-            text = pattern.sub(r"<strong>\1</strong>", text)
-    return text
-
-def render_profile_into_html(html_str: str, profile: Dict[str, Any], keywords: Optional[List[str]] = None) -> str:
-    basics = profile.get("basics", {})
-    name = basics.get("name", "")
-    title = basics.get("title", "")
-    phone = basics.get("phone", "")
-    email = basics.get("email", "")
-    location = basics.get("location", "")
-    github = basics.get("github", "")
-
-    # 1. 替换基础信息
-    if name:
-        html_str = re.sub(r'(<h1[^>]*class="[^"]*candidate-name[^"]*"[^>]*>).*?(</h1>)', rf'\g<1>{name}\g<2>', html_str)
-        html_str = re.sub(r'(<title>).*?(</title>)', f'<title>{name} - 个人简历</title>', html_str)
-    
-    if title:
-        html_str = re.sub(r'(<(?:p|span)[^>]*class="[^"]*(?:job-target|target-title)[^"]*"[^>]*>).*?(</(?:p|span)>)', rf'\g<1>求职意向：{title}\g<2>', html_str)
-
-    if phone:
-        html_str = re.sub(r'138-0000-0000|\b1[3-9]\d{9}\b|\+?\d{1,4}[-\s]?\d{7,11}', phone, html_str)
-    
-    if email:
-        html_str = re.sub(r'[a-zA-Z0-9_.+-]+@example\.com|[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+', email, html_str)
-
-    if location:
-        html_str = re.sub(r'北京\s*[·•-]\s*海淀(?:区)?', location, html_str)
-
-    if github:
-        html_str = re.sub(r'github\.com/[a-zA-Z0-9_-]+', github.replace("https://", "").replace("http://", ""), html_str)
-
-    # 2. 注入经历
-    experiences = profile.get("experience", [])
-    if experiences and '<section class="resume-section" id="experience">' in html_str:
-        exp_html_items = []
-        for exp in experiences:
-            bullets_html = "".join([f"<li>{highlight_keywords(b.get('text', ''), keywords or [])}</li>" for b in exp.get("bullets", [])])
-            exp_html_items.append(f"""
-        <div class="experience-item">
-          <div class="item-header">
-            <div class="item-title-group">
-              <span class="org-name">{exp.get('company', '')}</span>
-              <span class="role-badge">{exp.get('role', '')}</span>
-            </div>
-            <span class="date-range">{exp.get('startDate', '')} - {exp.get('endDate', '')}</span>
-          </div>
-          <ul class="bullet-list">
-            {bullets_html}
-          </ul>
-        </div>""")
-        
-        exp_block_pattern = re.compile(r'(<section[^>]*id="experience"[^>]*>.*?<h2[^>]*>.*?</h2>\s*).*?(</section>)', re.DOTALL)
-        if exp_block_pattern.search(html_str):
-            html_str = exp_block_pattern.sub(rf'\g<1>{"".join(exp_html_items)}\n      \g<2>', html_str)
-
-    # 3. 注入项目
-    projects = profile.get("projects", [])
-    if projects and '<section class="resume-section" id="projects">' in html_str:
-        proj_html_items = []
-        for proj in projects:
-            bullets_html = "".join([f"<li>{highlight_keywords(b.get('text', ''), keywords or [])}</li>" for b in proj.get("bullets", [])])
-            tech_tags_html = "".join([f'<span class="tech-tag">{t}</span>' for t in proj.get("techStack", [])])
-            proj_html_items.append(f"""
-        <div class="project-item">
-          <div class="item-header">
-            <div class="item-title-group">
-              <span class="project-name">{proj.get('name', '')}</span>
-              <span class="role-badge">{proj.get('role', '')}</span>
-            </div>
-            <span class="date-range">{proj.get('startDate', '')} - {proj.get('endDate', '')}</span>
-          </div>
-          <div class="tech-stack-tags">
-            {tech_tags_html}
-          </div>
-          <ul class="bullet-list">
-            {bullets_html}
-          </ul>
-        </div>""")
-        
-        proj_block_pattern = re.compile(r'(<section[^>]*id="projects"[^>]*>.*?<h2[^>]*>.*?</h2>\s*).*?(</section>)', re.DOTALL)
-        if proj_block_pattern.search(html_str):
-            html_str = proj_block_pattern.sub(rf'\g<1>{"".join(proj_html_items)}\n      \g<2>', html_str)
-
-    return html_str
-
-def instantiate_workspace(template_id: str, profile_path: Optional[str] = None, keywords: Optional[str] = None, output_path: str = "workspace/resume.html") -> Path:
-    base_dir = get_project_root()
-    template_dir = base_dir / "src" / "templates" / template_id
-    
-    if not template_dir.exists():
-        for sub in (base_dir / "src" / "templates").iterdir():
-            if sub.is_dir() and (sub / "metadata.json").exists():
-                try:
-                    meta = json.loads((sub / "metadata.json").read_text(encoding="utf-8"))
-                    if meta.get("id") == template_id:
-                        template_dir = sub
-                        break
-                except Exception:
-                    pass
-
-    if not template_dir.exists():
-        raise ValueError(f"Template '{template_id}' not found in src/templates/")
-        
-    html_file = template_dir / "template.html"
-    css_file = template_dir / "style.css"
-    base_css_file = base_dir / "src" / "templates" / "common" / "base.css"
-    
-    if not html_file.exists() or not css_file.exists():
-        raise FileNotFoundError(f"template.html or style.css missing in {template_dir}")
-        
-    html_content = html_file.read_text(encoding="utf-8")
-    css_content = css_file.read_text(encoding="utf-8")
-    
-    combined_css = ""
-    if base_css_file.exists():
-        combined_css = base_css_file.read_text(encoding="utf-8") + "\n\n/* === TEMPLATE SPECIFIC STYLES === */\n" + css_content
-    else:
-        combined_css = css_content
-    
-    inlined_html = html_content.replace(
-        '<link rel="stylesheet" href="style.css">',
-        f'<style>\n{combined_css}\n  </style>'
-    )
-    kw_list = [k.strip() for k in keywords.split(",") if k.strip()] if keywords else []
-
-    if profile_path and Path(profile_path).exists():
-        try:
-            profile_data = json.loads(Path(profile_path).read_text(encoding="utf-8"))
-            inlined_html = render_profile_into_html(inlined_html, profile_data, kw_list)
-        except Exception as e:
-            print(f"[!] Warning: Failed to inject profile data: {e}")
-    elif kw_list:
-        inlined_html = highlight_keywords(inlined_html, kw_list)
-        
-    out_file = Path(output_path)
-    out_file.parent.mkdir(parents=True, exist_ok=True)
-    out_file.write_text(inlined_html, encoding="utf-8")
-    
-    print("==============================================================")
-    print(f"  KnowMe CareerForge — Intermediate Canvas Instantiated!")
-    print(f"  Selected Template : {template_id} ({template_dir.name})")
-    print(f"  Profile Injected  : {profile_path or 'Default Template Content'}")
-    print(f"  Working Canvas    : {out_file.resolve()}")
-    print("==============================================================")
-    return out_file
+    return Path(__file__).resolve().parents[2]
+
+
+class CanvasContract(HTMLParser):
+    """Reject absent, duplicate, unknown or non-content-context binding slots."""
+
+    def __init__(self):
+        super().__init__(convert_charrefs=True)
+        self.stack = []
+        self.slots = []
+
+    def handle_starttag(self, tag, attrs):
+        if tag == "html" and not self.stack and attrs.count(("lang", "{{ resume:language }}")) == 1:
+            self.slots.append("language")
+        if tag not in {"meta", "link", "br", "hr", "img", "input", "wbr"}:
+            self.stack.append(tag)
+
+    def handle_endtag(self, tag):
+        if not self.stack or self.stack.pop() != tag:
+            raise ValueError(f"Malformed canvas closing tag: {tag}")
+
+    def handle_comment(self, data):
+        if not data.strip().startswith("resume:"):
+            return
+        name = data.strip()[7:]
+        parent = self.stack[-1] if self.stack else None
+        valid = (parent == "head" if name == "styles" else
+                 parent == "title" if name == "document-title" else
+                 "body" in self.stack and parent in {"main", "aside", "div", "header", "section", "td", "body"})
+        if not valid:
+            raise ValueError(f"Invalid canvas slot context: {name}")
+        self.slots.append(name)
+
+
+def validate_canvas(canvas):
+    parser = CanvasContract()
+    parser.feed(canvas)
+    parser.close()
+    expected = Counter(SLOTS)
+    if parser.stack or Counter(parser.slots) != expected or Counter(m.group(1) or m.group(2) for m in SLOT.finditer(canvas)) != expected:
+        raise ValueError("Canvas must contain every named resume slot exactly once")
+
+
+def profile_contract():
+    path = get_project_root() / "scripts" / "contracts" / "profile.py"
+    spec = importlib.util.spec_from_file_location("careerforge_profile_contract", path)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def text_field(obj, key):
+    value = obj.get(key)
+    return "" if value is None else str(value)
+
+
+def records(obj, key):
+    return obj.get(key) or []
+
+
+def strings(obj, key):
+    return obj.get(key) or []
+
+
+def highlight_keywords(text, keywords):
+    """Match plain text once, then escape each slice; never search generated HTML."""
+    words = sorted({kw.strip() for kw in keywords if kw.strip()}, key=lambda kw: (-len(kw), kw))
+    if not words:
+        return escape(text, quote=True)
+    alternatives = [
+        (r"(?<!\w)" if re.match(r"\w", word[0]) else "") + re.escape(word)
+        + (r"(?!\w)" if re.match(r"\w", word[-1]) else "")
+        for word in words
+    ]
+    pattern = re.compile("|".join(alternatives), re.I)
+    parts, offset = [], 0
+    for match in pattern.finditer(text):
+        parts.extend((escape(text[offset:match.start()]), "<strong>", escape(match.group()), "</strong>"))
+        offset = match.end()
+    parts.append(escape(text[offset:]))
+    return "".join(parts)
+
+
+def render_profile_into_html(html_str, profile, keywords=None, *, css=""):
+    validate_canvas(html_str)
+    profile = profile_contract().normalize_profile(profile)
+    language = profile.get("language") or "zh-CN"
+    if not re.fullmatch(r"(?:en|zh)(?:-[A-Za-z0-9]{1,8})*", language, re.I):
+        raise ValueError("Unsupported canvas language; use an en or zh language tag")
+    labels = LABELS[language.split("-")[0].lower()]
+    basics = profile.get("basics") or {}
+    keywords = keywords or []
+
+    def element(tag, cls, value):
+        return f'<{tag} class="{cls}">{highlight_keywords(value, keywords)}</{tag}>' if value else ""
+
+    def field(obj, key, cls="fact-text", tag="p"):
+        return element(tag, cls, text_field(obj, key))
+
+    def section(key, content):
+        label = labels[key]
+        if not content:
+            return ""
+        return f'<section class="resume-section" id="{key}"><h2 class="section-title">{label}</h2>{content}</section>'
+
+    def bullets(obj):
+        content = "".join(field(b, "text", "fact-bullet", "li") for b in records(obj, "bullets"))
+        return f'<ul class="bullet-list">{content}</ul>' if content else ""
+
+    def dates(obj):
+        return element("span", "date-range", " – ".join(filter(None, (text_field(obj, "startDate"), text_field(obj, "endDate")))))
+
+    def entries(key, name_key):
+        rendered = []
+        for item in records(profile, key):
+            heading = field(item, name_key, "org-name", "span")
+            heading += "".join(field(item, k, "role-badge", "span") for k in ("role", "degree", "field"))
+            heading += dates(item)
+            content = f'<div class="item-header">{heading}</div>' if heading else ""
+            content += field(item, "location") + field(item, "summary")
+            gpa = item.get("gpa")
+            if gpa is not None and gpa != "":
+                content += element("p", "edu-detail", f"GPA: {gpa}")
+            content += field(item, "repoUrl") + field(item, "demoUrl")
+            content += "".join(element("span", "tech-tag", t) for t in strings(item, "techStack"))
+            content += "".join(element("p", "edu-detail", honor) for honor in strings(item, "honors"))
+            content += bullets(item)
+            if content:
+                rendered.append(f'<div class="{key[:-1] if key == "projects" else key}-item">{content}</div>')
+        return "".join(rendered)
+
+    name = text_field(basics, "name")
+    basic_html = element("h1", "candidate-name", name) + field(basics, "title", "job-target")
+    contacts = "".join(field(basics, k, "contact-item", "span") for k in ("phone", "email", "location", "github", "website"))
+    if contacts:
+        basic_html += f'<div class="contact-grid">{contacts}</div>'
+    skill_rows = []
+    for skill in records(profile, "skills"):
+        category = field(skill, "category", "skill-category", "span")
+        items = strings(skill, "items")
+        # highlighted is metadata selecting emphasis, never an additional source of facts.
+        content = category + element("span", "skill-items", ("; " if language.lower().startswith("en") else "、").join(items))
+        if content:
+            skill_rows.append(f'<div class="skill-row">{content}</div>')
+    values = {
+        "styles": f"<style>\n{css}\n</style>",
+        "language": escape(language, quote=True),
+        "document-title": escape(name + " - " + labels["document-title"] if name else labels["document-title"]),
+        "basics": f'<header class="resume-header">{basic_html}</header>' if basic_html else "",
+        "summary": section("summary", field(basics, "summary", "value-prop")),
+        "skills": section("skills", "".join(skill_rows)),
+        "experience": section("experience", entries("experience", "company")),
+        "projects": section("projects", entries("projects", "name")),
+        "education": section("education", entries("education", "institution")),
+        "certifications": section("certifications", "".join(element("p", "fact-text", item) for item in strings(profile, "certifications"))),
+    }
+    # One substitution pass: user text resembling a slot is never interpreted.
+    return SLOT.sub(lambda match: values[match.group(1) or match.group(2)], html_str)
+
+
+def resolve_template(root, template_id):
+    templates = root / "src" / "templates"
+    for folder in sorted(templates.iterdir()):
+        if not folder.is_dir() or folder.name == "common":
+            continue
+        if folder.name == template_id:
+            return folder
+        metadata = folder / "metadata.json"
+        if metadata.exists() and json.loads(metadata.read_text(encoding="utf-8")).get("id") == template_id:
+            return folder
+    raise ValueError(f"Template '{template_id}' not found")
+
+
+def instantiate_workspace(template_id, profile_path=None, keywords=None, output_path="workspace/resume.html", quiet=False, font_preset="system"):
+    if font_preset not in FONT_PRESETS:
+        raise ValueError("Unknown font preset: " + str(font_preset))
+    root = get_project_root()
+    folder = resolve_template(root, template_id)
+    canvas = (folder / "canvas.html").read_text(encoding="utf-8")
+    common = root / "src" / "templates" / "common"
+    css = "\n".join(path.read_text(encoding="utf-8") for path in
+                    (common / "base.css", folder / "style.css", common / "canvas-bindings.css"))
+    css += "\n" + FONT_PRESETS[font_preset]
+    profile = json.loads(Path(profile_path).read_text(encoding="utf-8")) if profile_path is not None else {}
+    profile = profile_contract().load_document(profile)["profile"]
+    rendered = render_profile_into_html(canvas, profile, keywords.split(",") if keywords else [], css=css)
+    output = Path(output_path)
+    if profile_path is not None and output.resolve() == Path(profile_path).resolve():
+        raise ValueError("Output must not overwrite the input profile")
+    output.parent.mkdir(parents=True, exist_ok=True)
+    temporary = None
+    try:
+        with tempfile.NamedTemporaryFile(mode="w", encoding="utf-8", dir=output.parent,
+                                         prefix=f".{output.name}.", suffix=".tmp", delete=False) as stream:
+            temporary = Path(stream.name)
+            stream.write(rendered)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(temporary, output)
+    finally:
+        if temporary is not None:
+            temporary.unlink(missing_ok=True)
+    if not quiet:
+        print(f"Canvas written: {output.resolve()}")
+    return output
+
+
+class CLIParser(argparse.ArgumentParser):
+    def error(self, message):
+        raise ValueError(message)
+
 
 def main():
-    parser = argparse.ArgumentParser(description="KnowMe CareerForge — Workspace Instantiator")
-    parser.add_argument("--template", "-t", required=True, help="Template ID (minimal, modern, executive, classic)")
-    parser.add_argument("--profile", "-p", default=None, help="Path to evidence-master.json candidate profile")
-    parser.add_argument("--keywords", "-k", default=None, help="Comma-separated keywords to highlight (e.g. 'Python,LLM,RAG')")
-    parser.add_argument("--output", "-o", default="workspace/resume.html", help="Output canvas path (default: workspace/resume.html)")
+    parser = CLIParser(description=__doc__)
+    parser.add_argument("--template", "-t", required=True, help="Template directory name or metadata ID")
+    parser.add_argument("--profile", "-p", help="Candidate JSON; omitted produces a blank canvas")
+    parser.add_argument("--keywords", "-k", help="Comma-separated plain-text keywords")
+    parser.add_argument("--output", "-o", default="workspace/resume.html")
+    parser.add_argument("--font-preset", choices=sorted(FONT_PRESETS), default="system")
+    parser.add_argument("--quiet", "-q", action="store_true", help="Suppress human diagnostics; JSON result is always emitted")
+    result = {"status": "FAIL", "errors": [], "warnings": [], "checks": {"canvasWritten": False}}
+    try:
+        args = parser.parse_args()
+        output = instantiate_workspace(args.template, args.profile, args.keywords, args.output, quiet=True, font_preset=args.font_preset)
+        result.update(status="PASS", output=str(output.resolve()))
+        result["checks"]["canvasWritten"] = True
+    except (OSError, ValueError, TypeError) as error:
+        result["errors"].append(str(error))
+    print(json.dumps(result, ensure_ascii=False))
+    return 0 if result["status"] == "PASS" else 1
 
-    args = parser.parse_args()
-    instantiate_workspace(args.template, profile_path=args.profile, keywords=args.keywords, output_path=args.output)
 
 if __name__ == "__main__":
-    main()
+    sys.exit(main())

package/scripts/template/search-template.py

@@ -105,15 +105,24 @@ class WeightedRuleScorer(BaseTemplateScorer):
                 
         if role_score < 0.5:
             cat = template.get("roleCategory", "")
-            if any(k in query_lower for k in ["ai", "agent", "llm", "frontend", "backend", "fullstack", "devops", "engineer"]) and "engineering" in cat:
+            if any(k in query_lower for k in ["research", "scientist", "algorithm", "phd", "academic", "postdoc", "算法", "科研", "学者", "研究员"]) and "research" in cat:
+                role_score = 0.90
+            elif any(k in query_lower for k in ["remote", "international", "global", "overseas", "foreign", "外企", "海外", "跨国", "远程"]) and "international" in cat:
+                role_score = 0.90
+            elif any(k in query_lower for k in ["creative", "ui", "ux", "design", "interaction", "动效", "交互", "视觉"]) and "creative" in cat:
+                role_score = 0.90
+            elif any(k in query_lower for k in ["data", "analyst", "bi", "analytics", "metric", "数据", "商业智能", "数仓"]) and "data" in cat:
+                role_score = 0.90
+            elif any(k in query_lower for k in ["startup", "indie", "growth", "founder", "hacker", "初创", "增长", "独立开发"]) and "startup" in cat:
+                role_score = 0.90
+            elif any(k in query_lower for k in ["ai", "agent", "llm", "frontend", "backend", "fullstack", "devops", "engineer"]) and "engineering" in cat:
                 role_score = 0.85
-            elif any(k in query_lower for k in ["manager", "product", "lead", "director", "architect", "cto"]) and "management" in cat:
+            elif any(k in query_lower for k in ["manager", "product", "lead", "director", "architect", "cto", "高管", "总监"]) and "management" in cat:
                 role_score = 0.85
             elif any(k in query_lower for k in ["bank", "fintech", "state", "corp", "government"]) and "corporate" in cat:
                 role_score = 0.85
             else:
                 role_score = 0.60
-                
         score += role_score * self.weights["role"]
 
         # 2. Style Match
@@ -238,6 +247,70 @@ class HybridTemplateScorer(BaseTemplateScorer):
         return round(blended, 1)
 
 
+PALETTE_PRESETS: Dict[str, Dict[str, Any]] = {
+    "--palette-tech-blue": {
+        "name": "经典科技蓝",
+        "token": "--palette-tech-blue",
+        "hex": "#2563eb",
+        "tone": "tech-blue",
+        "keywords": ["engineering", "frontend", "backend", "fullstack", "devops", "cloud", "software", "前端", "后端", "全栈"]
+    },
+    "--palette-deep-navy": {
+        "name": "深邃海航蓝",
+        "token": "--palette-deep-navy",
+        "hex": "#1e3a8a",
+        "tone": "oxford-navy",
+        "keywords": ["research", "academic", "algorithm", "phd", "scientist", "ai-agent", "llm", "cv", "nlp", "算法", "科研", "学者", "博士"]
+    },
+    "--palette-teal-modern": {
+        "name": "现代松石绿",
+        "token": "--palette-teal-modern",
+        "hex": "#0f766e",
+        "tone": "executive-formal",
+        "keywords": ["executive", "management", "cto", "director", "lead", "product", "architect", "高管", "总监", "架构师", "产品经理"]
+    },
+    "--palette-emerald-fresh": {
+        "name": "活力翡翠绿",
+        "token": "--palette-emerald-fresh",
+        "hex": "#059669",
+        "tone": "emerald-green",
+        "keywords": ["startup", "generalist", "indie", "growth", "founder", "hacker", "初创", "独立开发", "增长"]
+    },
+    "--palette-violet-creative": {
+        "name": "创意极光紫",
+        "token": "--palette-violet-creative",
+        "hex": "#7c3aed",
+        "tone": "tech-violet",
+        "keywords": ["creative", "ui", "ux", "design", "interaction", "threejs", "webgl", "motion", "动效", "视觉", "体验"]
+    },
+    "--palette-slate-minimal": {
+        "name": "极简碳素灰",
+        "token": "--palette-slate-minimal",
+        "hex": "#334155",
+        "tone": "neutral-slate",
+        "keywords": ["international", "remote", "global", "overseas", "minimal", "compact", "dense", "外企", "海外", "远程", "极简"]
+    }
+}
+
+def recommend_palette(role: str, template: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    """Recommend official palette preset based on role keywords and template style."""
+    role_lower = (role or "").lower()
+    template_tone = (template.get("visualStyle", {}).get("tone", "") if template else "").lower()
+    template_cat = (template.get("roleCategory", "") if template else "").lower()
+
+    # 1. Match against palette keywords
+    for token, p in PALETTE_PRESETS.items():
+        if any(kw in role_lower for kw in p["keywords"]):
+            return p
+
+    # 2. Match template visual tone
+    for token, p in PALETTE_PRESETS.items():
+        if p["tone"] in template_tone or template_tone in p["tone"]:
+            return p
+
+    # 3. Default fallback
+    return PALETTE_PRESETS["--palette-tech-blue"]
+
 # ==============================================================================
 # 2. PUBLIC FACADE INTERFACE (DEEP MODULE)
 # ==============================================================================
@@ -289,6 +362,7 @@ def search_templates(
     results = []
     for t in templates:
         t_copy = dict(t)
+        t_copy["recommendedPalette"] = recommend_palette(role, t)
         score_val = scorer.score(t, query)
         t_copy["matchScore"] = score_val
         t_copy["score"] = score_val
@@ -308,6 +382,7 @@ def main():
     parser.add_argument("--engine", "-e", default="hybrid", choices=["hybrid", "weighted", "bm25"], help="Scoring engine")
     parser.add_argument("--json", action="store_true", help="Output raw JSON array")
     
+    parser.add_argument("--summary", action="store_true", help="Compact JSON with the top three ranked layouts; no full metadata")
     args = parser.parse_args()
     target_role = args.named_role or args.role
     if not target_role:
@@ -322,6 +397,14 @@ def main():
         engine=args.engine
     )
     
+    if args.summary:
+        print(json.dumps({"totalMatches": len(results), "candidates": [
+            {"id": item["id"], "name": item.get("name"), "score": item["matchScore"],
+             "layout": item.get("layout", {})}
+            for item in results[:3]
+        ]}, ensure_ascii=False, indent=2))
+        return
+
     if args.json:
         print(json.dumps(results, ensure_ascii=False, indent=2))
         return
@@ -341,6 +424,9 @@ def main():
         print(f"   Category: {r.get('roleCategory')} | Style: {r.get('style')} | ATS Tier: {r.get('atsScoreTier')}")
         print(f"   Target Pages: {r.get('layout', {}).get('targetPages', 1)} | Density: {r.get('layout', {}).get('density')}")
         print(f"   Directory: {r.get('_directory')}")
+        pal = r.get("recommendedPalette")
+        if pal:
+            print(f"   Palette  : {pal.get('name')} ({pal.get('hex')}) [Token: {pal.get('token')}]")
         if tokens_preview:
             print(f"   Tokens   : {tokens_preview}")
         print("-" * 80)

package/scripts/validation/measure-dom.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+'use strict';
+const engine = require('../rendering/browser-engine.js');
+module.exports = engine;
+if (require.main === module) engine.cli();