knowme-careerforge-skill 0.0.2 → 0.0.4

package/scripts/template/search-template.py

@@ -1,12 +1,22 @@
 #!/usr/bin/env python3
 """
-KnowMe CareerForge — Template Search & Ranking Engine (BM25 + Multi-criteria scoring)
-根据目标岗位、期望版式风格、目标页数与信息密度，加权检索最匹配的 HTML 简历模板。
+KnowMe CareerForge — Template Search & Ranking Engine
+Architecture: Deep Module with Pluggable Scorer Strategies (Weighted Rules + BM25 Text Search)
+
+Design Contract:
+- BaseTemplateScorer: Abstract strategy interface
+- WeightedRuleScorer: Multi-criteria rule-based weighted scorer (Role 35%, Style 25%, ATS 20%, Page 10%, Density 10%)
+- BM25TextScorer: Pure-Python BM25 keyword retrieval across template text documents
+- HybridTemplateScorer: Weighted blend (70% Rule Score + 30% BM25 Text Score)
+- search_templates(): Public facade interface
 """
 
-import sys, os, json, argparse
+import sys, os, json, argparse, math, re
 from pathlib import Path
+from dataclasses import dataclass, field
 from typing import List, Dict, Any, Optional
+from abc import ABC, abstractmethod
+
 
 def get_project_root() -> Path:
     curr = Path(__file__).resolve().parent
@@ -16,6 +26,17 @@ def get_project_root() -> Path:
         curr = curr.parent
     return Path.cwd()
 
+
+@dataclass
+class SearchQuery:
+    role: str
+    style: Optional[str] = None
+    target_pages: int = 1
+    density: str = "balanced"
+    keywords: Optional[str] = None
+    engine: str = "hybrid"  # "weighted" | "bm25" | "hybrid"
+
+
 def load_templates() -> List[Dict[str, Any]]:
     root_dir = get_project_root()
     base_dir = root_dir / "src" / "templates"
@@ -30,120 +51,300 @@ def load_templates() -> List[Dict[str, Any]]:
         if meta_file.exists():
             try:
                 data = json.loads(meta_file.read_text(encoding="utf-8"))
-                data["directory"] = f"src/templates/{t_dir.name}"
+                data["_directory"] = str(t_dir.relative_to(root_dir))
                 templates.append(data)
             except Exception:
                 pass
     return templates
 
-def calculate_match_score(template: Dict[str, Any], query_role: str, query_style: Optional[str] = None, target_pages: int = 1, density: str = "balanced") -> float:
-    score = 0.0
+
+# ==============================================================================
+# 1. SCORER STRATEGY INTERFACE & IMPLEMENTATIONS
+# ==============================================================================
+
+class BaseTemplateScorer(ABC):
+    """Abstract interface for template scoring algorithms."""
     
-    # 1. 岗位匹配度 (Role Match - 35%)
-    role_score = 0.0
-    query_lower = query_role.lower()
-    supported = [r.lower() for r in template.get("supportedRoles", [])]
+    @abstractmethod
+    def score(self, template: Dict[str, Any], query: SearchQuery) -> float:
+        """Return match score normalized between 0.0 and 100.0."""
+        pass
+
+
+class WeightedRuleScorer(BaseTemplateScorer):
+    """
+    Rule-based weighted scoring engine:
+    - Role Match: 35%
+    - Style Match: 25%
+    - ATS Tier: 20%
+    - Page Fit: 10%
+    - Density Fit: 10%
+    """
     
-    for r in supported:
-        if r in query_lower or query_lower in r:
-            role_score = 1.0
-            break
-            
-    if role_score < 0.5:
-        cat = template.get("roleCategory", "")
-        if "ai" in query_lower or "algorithm" in query_lower or "agent" in query_lower:
-            role_score = 0.95 if cat == "engineering-ai" else 0.40
-        elif "product" in query_lower or "manager" in query_lower or "director" in query_lower:
-            role_score = 0.95 if cat == "management-product" else 0.40
-        elif "engineer" in query_lower or "architect" in query_lower:
-            role_score = 0.85
-        else:
-            role_score = 0.60
-            
-    score += role_score * 0.35
-
-    # 2. 风格匹配度 (Style Match - 25%)
-    style_score = 0.70
-    if query_style:
-        q_style_lower = query_style.lower()
-        t_style = template.get("style", "").lower()
-        t_tone = template.get("visualStyle", {}).get("tone", "").lower()
+    def __init__(self, weights: Optional[Dict[str, float]] = None):
+        self.weights = weights or {
+            "role": 0.35,
+            "style": 0.25,
+            "ats": 0.20,
+            "page": 0.10,
+            "density": 0.10
+        }
+
+    def score(self, template: Dict[str, Any], query: SearchQuery) -> float:
+        score = 0.0
         
-        if q_style_lower in t_style or q_style_lower in t_tone or q_style_lower == template.get("id"):
-            style_score = 1.0
-        elif "minimal" in q_style_lower and "minimal" in t_style:
-            style_score = 0.95
-        elif "split" in q_style_lower and "split" in t_style:
-            style_score = 0.95
-        elif "modern" in q_style_lower and "modern" in t_tone:
-            style_score = 0.95
+        # 1. Role Match
+        role_score = 0.0
+        query_lower = query.role.lower()
+        supported = [r.lower() for r in template.get("supportedRoles", [])]
+        
+        for r in supported:
+            if r in query_lower or query_lower in r:
+                role_score = 1.0
+                break
+                
+        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:
+                role_score = 0.85
+            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
+        style_score = 0.70
+        if query.style:
+            q_style_lower = query.style.lower()
+            t_style = template.get("style", "").lower()
+            t_tone = template.get("visualStyle", {}).get("tone", "").lower()
+            
+            if q_style_lower in t_style or q_style_lower in t_tone:
+                style_score = 1.0
+            elif any(k in t_style for k in q_style_lower.split("-")):
+                style_score = 0.85
+            else:
+                style_score = 0.50
+        score += style_score * self.weights["style"]
+
+        # 3. ATS Tier
+        ats_tier = template.get("atsScoreTier", "tier-1-optimal")
+        ats_score = 1.0 if "optimal" in ats_tier or "tier-1" in ats_tier else 0.85
+        score += ats_score * self.weights["ats"]
+
+        # 4. Page Fit
+        target_p = template.get("layout", {}).get("targetPages", 1)
+        max_p = template.get("layout", {}).get("maxPages", 2)
+        if query.target_pages == target_p:
+            page_score = 1.0
+        elif query.target_pages <= max_p:
+            page_score = 0.80
         else:
-            style_score = 0.50
-    score += style_score * 0.25
-
-    # 3. ATS 兼容评级 (ATS Tier - 20%)
-    ats_tier = template.get("atsScoreTier", "tier-1-optimal")
-    ats_score = 1.0 if "optimal" in ats_tier or "tier-1" in ats_tier else 0.85
-    score += ats_score * 0.20
-
-    # 4. 页数适配度 (Page Fit - 10%)
-    target_p = template.get("layout", {}).get("targetPages", 1)
-    max_p = template.get("layout", {}).get("maxPages", 2)
-    if target_pages == target_p:
-        page_score = 1.0
-    elif target_pages <= max_p:
-        page_score = 0.80
-    else:
-        page_score = 0.50
-    score += page_score * 0.10
+            page_score = 0.50
+        score += page_score * self.weights["page"]
+
+        # 5. Density Preference
+        t_density = template.get("layout", {}).get("density", "balanced")
+        density_score = 1.0 if query.density == t_density else 0.80
+        score += density_score * self.weights["density"]
+
+        return round(score * 100, 1)
+
+
+class BM25TextScorer(BaseTemplateScorer):
+    """
+    Pure Python BM25 Text Scorer across template metadata documents.
+    Constructs a virtual document per template: (name, category, style, supportedRoles, tone).
+    """
+    
+    def __init__(self, templates: Optional[List[Dict[str, Any]]] = None, k1: float = 1.5, b: float = 0.75):
+        self.k1 = k1
+        self.b = b
+        self.templates = templates or load_templates()
+        self.docs = [self._extract_doc(t) for t in self.templates]
+        self.avg_dl = sum(len(d) for d in self.docs) / max(len(self.docs), 1)
+        self.doc_freqs = self._calc_doc_freqs()
+
+    def _extract_doc(self, template: Dict[str, Any]) -> List[str]:
+        text_parts = [
+            template.get("name", ""),
+            template.get("style", ""),
+            template.get("roleCategory", ""),
+            template.get("visualStyle", {}).get("tone", ""),
+            " ".join(template.get("supportedRoles", []))
+        ]
+        combined = " ".join(text_parts).lower()
+        # Tokenize words & Chinese characters
+        tokens = re.findall(r'[a-zA-Z0-9_\-]+|[\u4e00-\u9fa5]', combined)
+        return tokens
 
-    # 5. 信息密度偏好 (Density - 10%)
-    t_density = template.get("layout", {}).get("density", "balanced")
-    density_score = 1.0 if density == t_density else 0.80
-    score += density_score * 0.10
+    def _calc_doc_freqs(self) -> Dict[str, int]:
+        freqs: Dict[str, int] = {}
+        for doc in self.docs:
+            for word in set(doc):
+                freqs[word] = freqs.get(word, 0) + 1
+        return freqs
 
-    return round(score * 100, 1)
+    def score(self, template: Dict[str, Any], query: SearchQuery) -> float:
+        doc = self._extract_doc(template)
+        doc_len = len(doc)
+        if doc_len == 0:
+            return 50.0
 
-def search_templates(role: str, style: Optional[str] = None, target_pages: int = 1, density: str = "balanced") -> List[Dict[str, Any]]:
+        query_text = f"{query.role} {query.style or ''} {query.keywords or ''}".lower()
+        q_tokens = re.findall(r'[a-zA-Z0-9_\-]+|[\u4e00-\u9fa5]', query_text)
+        if not q_tokens:
+            return 70.0
+
+        n_docs = len(self.docs)
+        score = 0.0
+
+        for term in q_tokens:
+            df = self.doc_freqs.get(term, 0)
+            if df == 0:
+                continue
+            # Standard BM25 IDF with smoothing
+            idf = math.log(1 + (n_docs - df + 0.5) / (df + 0.5))
+            tf = doc.count(term)
+            numerator = tf * (self.k1 + 1)
+            denominator = tf + self.k1 * (1 - self.b + self.b * (doc_len / max(self.avg_dl, 1)))
+            score += idf * (numerator / max(denominator, 0.001))
+
+        # Normalize score into roughly 50.0 ~ 100.0 range
+        normalized = 50.0 + min(score * 15.0, 50.0)
+        return round(normalized, 1)
+
+
+class HybridTemplateScorer(BaseTemplateScorer):
+    """
+    Weighted combination of rule-based constraints and BM25 text relevance.
+    Default: 70% Weighted Rules + 30% BM25 Relevance.
+    """
+    
+    def __init__(self, rule_weight: float = 0.70, bm25_weight: float = 0.30):
+        self.rule_scorer = WeightedRuleScorer()
+        self.bm25_scorer = BM25TextScorer()
+        self.rule_weight = rule_weight
+        self.bm25_weight = bm25_weight
+
+    def score(self, template: Dict[str, Any], query: SearchQuery) -> float:
+        rule_score = self.rule_scorer.score(template, query)
+        bm25_score = self.bm25_scorer.score(template, query)
+        blended = (rule_score * self.rule_weight) + (bm25_score * self.bm25_weight)
+        return round(blended, 1)
+
+
+# ==============================================================================
+# 2. PUBLIC FACADE INTERFACE (DEEP MODULE)
+# ==============================================================================
+
+def search_templates(
+    role: str,
+    style: Optional[str] = None,
+    target_pages: int = 1,
+    density: str = "balanced",
+    keywords: Optional[str] = None,
+    engine: str = "hybrid"
+) -> List[Dict[str, Any]]:
+    """
+    Search and rank HTML resume templates.
+    
+    Args:
+        role: Target job title or direction (e.g., 'AI Agent Engineer', 'Tech Lead')
+        style: Preferred visual/layout style (e.g., 'single-column-minimal', 'two-column-split')
+        target_pages: Expected page count (1 or 2)
+        density: Information density preference ('high', 'balanced', 'spacious')
+        keywords: Optional JD keywords for text matching
+        engine: Scoring engine ('hybrid' | 'weighted' | 'bm25')
+        
+    Returns:
+        List of matching templates sorted by matchScore descending.
+    """
+    query = SearchQuery(
+        role=role,
+        style=style,
+        target_pages=target_pages,
+        density=density,
+        keywords=keywords,
+        engine=engine
+    )
+    
     templates = load_templates()
+    if not templates:
+        return []
+
+    # Select Scorer Strategy
+    scorer: BaseTemplateScorer
+    if engine == "bm25":
+        scorer = BM25TextScorer(templates)
+    elif engine == "weighted":
+        scorer = WeightedRuleScorer()
+    else:
+        scorer = HybridTemplateScorer()
+
     results = []
-    
     for t in templates:
-        s = calculate_match_score(t, role, style, target_pages, density)
-        results.append({
-            "score": s,
-            "template": t
-        })
+        t_copy = dict(t)
+        score_val = scorer.score(t, query)
+        t_copy["matchScore"] = score_val
+        t_copy["score"] = score_val
+        t_copy["template"] = t
+        results.append(t_copy)
         
-    results.sort(key=lambda x: x["score"], reverse=True)
+    results.sort(key=lambda x: x.get("matchScore", 0.0), reverse=True)
     return results
-
 def main():
     parser = argparse.ArgumentParser(description="KnowMe CareerForge — Template Search Engine")
-    parser.add_argument("role", nargs="?", default="AI Agent Engineer", help="Target role title")
-    parser.add_argument("--style", "-s", default=None, help="Desired style (minimal, modern, executive, classic)")
-    parser.add_argument("--target-pages", "-p", type=int, default=1, help="Expected target pages (1 or 2)")
-    parser.add_argument("--density", "-d", default="balanced", help="Information density preference (high, balanced, normal)")
-    parser.add_argument("--json", action="store_true", help="Output results in raw JSON")
-
+    parser.add_argument("role", nargs="?", default=None, help="Target role or job title (e.g. 'AI Agent Engineer')")
+    parser.add_argument("--role", "-r", dest="named_role", default=None, help="Target role (named option)")
+    parser.add_argument("--style", "-s", default=None, help="Style preference (minimal, modern, executive, classic)")
+    parser.add_argument("--target-pages", "-p", type=int, default=1, help="Target pages (1 or 2)")
+    parser.add_argument("--density", "-d", default="balanced", choices=["high", "balanced", "spacious"], help="Density")
+    parser.add_argument("--keywords", "-k", default=None, help="Additional JD keywords")
+    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")
+    
     args = parser.parse_args()
-    results = search_templates(args.role, style=args.style, target_pages=args.target_pages, density=args.density)
+    target_role = args.named_role or args.role
+    if not target_role:
+        parser.error("the following arguments are required: role (or --role / -r)")
 
+    results = search_templates(
+        role=target_role,
+        style=args.style,
+        target_pages=args.target_pages,
+        density=args.density,
+        keywords=args.keywords,
+        engine=args.engine
+    )
+    
     if args.json:
         print(json.dumps(results, ensure_ascii=False, indent=2))
         return
-
+        
     print("=" * 80)
-    print(f"  KnowMe CareerForge — Template Recommendations for '{args.role}'")
+    print(f"  KnowMe CareerForge — Template Search Engine Results")
+    print(f"  Query Role   : {target_role}")
+    print(f"  Style Filter : {args.style or 'Any'}")
+    print(f"  Engine       : {args.engine.upper()}")
+    print(f"  Matches      : {len(results)} template(s) found")
     print("=" * 80)
+    
     for idx, r in enumerate(results, 1):
-        t = r["template"]
-        print(f"{idx}. [Score: {r['score']}] {t['name']} (ID: {t['id']})")
-        print(f"   Category: {t['roleCategory']} | Style: {t['style']} | ATS Tier: {t['atsScoreTier']}")
-        print(f"   Target Pages: {t['layout']['targetPages']} (Max: {t['layout']['maxPages']}) | Density: {t['layout']['density']}")
-        print(f"   Tone: {t['visualStyle']['tone']} | Accent: {t['visualStyle']['accentColor']}")
-        print(f"   Directory: {t['directory']}")
+        custom_tokens = r.get("customizableTokens", [])
+        tokens_preview = ", ".join(custom_tokens[:4]) + ("..." if len(custom_tokens) > 4 else "")
+        print(f"\n{idx}. [{r.get('matchScore')} pts] {r.get('name')} (ID: {r.get('id')})")
+        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')}")
+        if tokens_preview:
+            print(f"   Tokens   : {tokens_preview}")
         print("-" * 80)
 
+
 if __name__ == "__main__":
     main()

package/skill.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/skill.json",
   "name": "knowme-careerforge",
   "displayName": "KnowMe CareerForge",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "An agent-native skill for self-discovery, career positioning, and tailored resume engineering. Know yourself. Define your direction. Forge your opportunity.",
   "author": "Miles <https://github.com/Max-Samson>",
   "license": "MIT",

package/src/knowledge/index.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.0.2",
+  "version": "0.0.4",
   "totalRoles": 9,
   "totalTemplates": 4,
   "roles": [
@@ -530,9 +530,7 @@
         "--resume-font-size-meta",
         "--resume-font-size-title",
         "--resume-line-height-body",
-        "--resume-page-min-height",
-        "--resume-page-padding",
-        "--resume-page-width"
+        "--resume-page-padding"
       ]
     },
     {
@@ -592,8 +590,6 @@
         "--resume-font-size-title",
         "--resume-left-col-width",
         "--resume-line-height-body",
-        "--resume-page-min-height",
-        "--resume-page-width",
         "--resume-space-bullet",
         "--resume-space-item",
         "--resume-space-section"
@@ -654,9 +650,7 @@
         "--resume-font-size-name",
         "--resume-font-size-target",
         "--resume-line-height-body",
-        "--resume-page-min-height",
         "--resume-page-padding",
-        "--resume-page-width",
         "--resume-space-bullet",
         "--resume-space-header-bottom",
         "--resume-space-item",
@@ -722,8 +716,6 @@
         "--resume-font-size-name",
         "--resume-font-size-target",
         "--resume-line-height-body",
-        "--resume-page-min-height",
-        "--resume-page-width",
         "--resume-sidebar-width",
         "--resume-space-bullet",
         "--resume-space-item",

package/src/knowledge/templates.json

@@ -51,9 +51,7 @@
         "--resume-font-size-meta",
         "--resume-font-size-title",
         "--resume-line-height-body",
-        "--resume-page-min-height",
-        "--resume-page-padding",
-        "--resume-page-width"
+        "--resume-page-padding"
       ]
     },
     {
@@ -113,8 +111,6 @@
         "--resume-font-size-title",
         "--resume-left-col-width",
         "--resume-line-height-body",
-        "--resume-page-min-height",
-        "--resume-page-width",
         "--resume-space-bullet",
         "--resume-space-item",
         "--resume-space-section"
@@ -175,9 +171,7 @@
         "--resume-font-size-name",
         "--resume-font-size-target",
         "--resume-line-height-body",
-        "--resume-page-min-height",
         "--resume-page-padding",
-        "--resume-page-width",
         "--resume-space-bullet",
         "--resume-space-header-bottom",
         "--resume-space-item",
@@ -243,8 +237,6 @@
         "--resume-font-size-name",
         "--resume-font-size-target",
         "--resume-line-height-body",
-        "--resume-page-min-height",
-        "--resume-page-width",
         "--resume-sidebar-width",
         "--resume-space-bullet",
         "--resume-space-item",

package/src/references/01-evidence-mining.md

@@ -0,0 +1,41 @@
+# Reference Manual 01: Evidence Mining & Anti-Hallucination Gate
+
+> **"The goal is not to make the candidate look better than they are. The goal is to make their real strengths visible to the right opportunity."**
+
+---
+
+## 1. L1~L3 Evidence Classification Standard
+
+Every bullet point and technical claim on the resume MUST be grounded in traceable candidate evidence:
+
+| Level | Evidence Source | Confidence | Usage & Phrasing Standard | Prohibited Anti-Patterns |
+|:---|:---|:---|:---|:---|
+| **Level 1 (Direct Strong Evidence)** | Code implementation (`src/`), config files (`package.json`, `go.mod`, `Cargo.toml`, `Dockerfile`), API contracts, CI/CD pipelines, Git commit history | 95%+ | Direct, confident assertion with quantified metrics: *"Designed dual-path retrieval pipeline using FastAPI and Qdrant, achieving 92% Top-3 recall rate."* | Fabricating business revenue or claiming ownership beyond repository boundaries. |
+| **Level 2 (Structural Medium Evidence)** | Directory structure, module dependencies, database schemas, framework integrations | 80%~95% | Engineering integration verbs: *"Engineered distributed microservice endpoints for order and inventory management using gRPC."* | Exaggerating simple library imports as custom from-scratch underlying framework development. |
+| **Level 3 (Contextual Weak Inference)** | Agile practices, code reviews, deployment workflows, cross-team collaboration | 60%~80% | Conservative contextual phrasing: *"Participated in system architecture reviews and collaborated with product teams on sprint delivery."* | Claiming solo leadership of large engineering teams without organizational backing. |
+| **Unsupported (No Evidence)** | Facts not found in candidate records or codebases | <50% | **STRICTLY PROHIBITED FROM RESUME** | Inventing unverified degrees, false company tenures, or imaginary revenue numbers. |
+
+---
+
+## 2. Automated Codebase & Git Mining Protocol
+
+Run the evidence extraction engine against local repository or workspace:
+```bash
+python3 scripts/evidence/extract-evidence.py --repo . --name "<Candidate Name>" --output workspace/evidence-master.json --quiet
+```
+
+### Extracted Evidence Dimensions:
+1. **Git Provenance**: Author names, email, commit count, active development timeframes;
+2. **Tech Stack Signatures**: Dependency parsing across 25+ language/framework ecosystems;
+3. **Architecture Signals**: Monorepo setups, containerization (Docker/K8s), automated testing, CI/CD workflows;
+4. **Code Volume & Distribution**: Breakdown by language and directory hierarchy.
+
+---
+
+## 3. Anti-Hallucination Execution Checklist
+
+Before writing any line into `workspace/resume.html`:
+- [ ] Is the primary technology verified in candidate code, config, or explicit profile?
+- [ ] Is the action verb accurate to actual candidate contribution level (Led vs Implemented vs Participated)?
+- [ ] Are all metrics (percentages, QPS, latency) grounded in reality rather than fabricated?
+- [ ] If JD requires a skill absent from candidate evidence, mark as gap rather than hallucinating.

package/src/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/src/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**).