project-interview-skill 1.1.0

package/references/output-templates.md

@@ -0,0 +1,77 @@
+# 输出骨架（仓库根目录两个文件）
+
+约定：**工作区根目录**（用户当前打开的项目根）生成：
+
+- `导学-{简称}.md`
+- `面经-{简称}.md`
+
+`{简称}` 由用户在输入中给出，或由你从项目描述中提炼（2～8 个字符为宜），并在文首「已确认输入」中写明。
+
+---
+
+## `导学-{简称}.md` 骨架
+
+```markdown
+# 导学：{简称}
+
+## 1. 前置知识（面试高频标注）
+| 知识点 | 为何需要 | 在本项目中的位置 | 高频度 |
+
+## 2. 重点亮点与学习顺序（先看这个）
+- （3～6 条：亮点标题 / 为什么重要 / 先看哪些文件（相对路径）/ 建议学习顺序）
+
+## 3. 必备知识点
+- （ checklist：必须搞懂的点，可与上表呼应）
+
+## 4. 推荐阅读（结合仓库）
+> 每条必须包含 **项目相对路径**（如 `src/views/xxx.vue`），无代码则写 `（仓库未提供路径，待用户补充）`。
+
+| 主题 | 建议阅读的代码/文档位置 | 预计时间 | 读完能回答什么 |
+
+## 5. 自学提醒
+- 若某文件或原理看不懂，请继续追问 AI；本 skill 负责给学习路径与题目，不提供逐行讲解。
+
+## 6. 项目技术定位
+- 倾向：前端 / 后端 / AI / 交叉；依据一句话
+
+## 7. 核心原理解析
+### 7.x 主题
+- 问题 → 机制 → 在本项目中的落点
+
+## 8. 关键设计决策
+| 决策点 | 备选 | 取舍 | 风险 | 验证 |
+
+## 9. 量化与验证（含待测，建议）
+- 文中涉及优化/性能/错误率等：无实测数据处标注 **（待测）**
+- **可选放在本文件末尾**：列出与本项目相关的 **如何测**（性能优化场景建议写：环境、指标、工具、基线/对比注意点）；无则写「本项目量化点较少，面试诚实说明」。
+```
+
+---
+
+## `面经-{简称}.md` 骨架
+
+```markdown
+# 面经：{简称}
+
+## 项目简介（简历可用，1～2 句）
+> 基于……的……；用户能……；支持……（参见同目录 `oral-and-resume-patterns.md`）
+
+## 简历 bullet（4～6 条）
+- 动作 + 技术/约束 + 结果或（待测）
+
+## 面试问题（按频率排序）
+> 正文重心放在面试题口播，不单独输出「亮点拆解」章节；建议 3～6 个主题，每主题至少 1 主问 + 2 追问。
+
+### Q1（频率：高）[标签/主题]
+**面试官问题**：……
+
+**口播版（第一人称，≥150 字，完整 STAR）**
+（场景→归因→动作→结果/兜底，可含英文术语括号）
+
+**追问 1**：……
+**口播版（≥150 字）**：……
+
+**追问 2**：……
+**口播版（≥150 字）**：……
+
+```

package/references/star-framework.md

@@ -0,0 +1,29 @@
+# STAR、追问与口播要求
+
+## 口播版（面经中的答题正文）
+
+- **第一人称**：面经文档里「主问题 / 追问」的**口播正文**一律用「我」作主语（协作题可一句内用「我们」说明边界）。
+- **字数**：每一道**主问题**、每一道**追问**的口播版均 **≥150 个汉字**（或等价符号不计入时以汉字为主），且须能单独讲清**完整 STAR**（情境—任务—行动—结果），禁止只列关键词。
+- **结构**：推荐「场景（现象）→ 归因（根因）→ 动作（分层方案）→ 结果/兜底/待测」；详见 [口播与简历抽象](oral-and-resume-patterns.md)。
+- **术语**：关键 API、库名、协议可加英文括号，如：`JSON.parse`、`safeParse`。
+- **待测数据**：口播中涉及性能、错误率等若暂无实测，用 **（待测）** 标出；在该文件末尾「量化与验证」中写清如何测（见 SKILL 输出契约）。
+
+## STAR 四要素（口播内需隐含或显式点到）
+
+- **S**：业务与现场约束（上线初期、某环境、流量特征）。
+- **T**：你的目标与可验证标准（哪怕定性）。
+- **A**：你具体落地的步骤与权衡（为何不用更简单的做法）。
+- **R**：结果、指标或（待测）+ 后续观测/降级。
+
+## 主问题设计
+
+- 从**最大风险或最难权衡**切入，能自然引出架构与细节。
+
+## 追问递进（每个亮点固定 2 个）
+
+1. **细节**：数据结构、API、边界、错误码、一致性。
+2. **失败与演化**：线上问题、回滚、债务、重做会改什么。
+
+## 频率标注
+
+- 题目排序：**岗位核心栈 > 跨栈基础 > 拓展**；标签 `通用` / `前端` / `后端` / `AI`。

package/scripts/build_prompt.py

@@ -0,0 +1,202 @@
+#!/usr/bin/env python3
+"""
+Build a single consolidated prompt block for generating 导学 + 面经 Markdown files.
+
+Reads fields from CLI flags or a JSON file and prints UTF-8 Markdown for agent consumption.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+ILLEGAL_SHORT_NAME_CHARS = {"/", "\\", ":", "*", "?", '"', "<", ">", "|"}
+
+
+def _escape_md(text: str) -> str:
+    """Avoid accidental markdown break when embedding user text."""
+    return text.replace("```", "``\u200b`")
+
+
+def _validate_short_name(short_name: str) -> str:
+    """
+    Validate filename-safe short name used in 导学-{简称}.md / 面经-{简称}.md.
+    """
+    cleaned = short_name.strip()
+    if not cleaned:
+        return ""
+    if cleaned in {".", ".."}:
+        raise ValueError("short name cannot be '.' or '..'.")
+    if any(ch in cleaned for ch in ILLEGAL_SHORT_NAME_CHARS):
+        chars = "".join(sorted(ILLEGAL_SHORT_NAME_CHARS))
+        raise ValueError(f"short name contains illegal path chars. disallowed: {chars}")
+    if len(cleaned) > 24:
+        raise ValueError("short name is too long (max 24 characters).")
+    return cleaned
+
+
+def build_prompt(
+    description: str,
+    tech_stack: str | None,
+    role_focus: str | None,
+    short_name: str | None,
+    extra: str | None,
+) -> str:
+    """
+    Compose the master prompt for the analyzing agent.
+
+    Args:
+        description: Required project description.
+        tech_stack: Optional stack string.
+        role_focus: Optional frontend/backend/AI.
+        short_name: Optional short name for `导学-{简称}.md` / `面经-{简称}.md`.
+        extra: Optional free-form notes.
+
+    Returns:
+        Markdown string to paste into a chat or pipe to an LLM.
+    """
+    lines: list[str] = [
+        "请严格按 `project-interview-skill` 执行：在**工作区根目录**写入两个文件：",
+        "`导学-{简称}.md` 与 `面经-{简称}.md`；量化与验证仅作为导学中的可选建议项。",
+        "",
+        "## 已确认输入",
+        "",
+        "### 项目简称（用于文件名）",
+        "",
+    ]
+    if short_name and short_name.strip():
+        lines.append(short_name.strip())
+    else:
+        lines.append("_（未提供，请从描述提炼并在写入前写明）_")
+    lines.extend(["", "### 项目描述（必须）", "", "```text", _escape_md(description.strip()), "```", ""])
+
+    lines.append("### 技术栈（可选）")
+    lines.append("")
+    if tech_stack and tech_stack.strip():
+        lines.append("```text")
+        lines.append(_escape_md(tech_stack.strip()))
+        lines.append("```")
+    else:
+        lines.append("_（未提供，请合理推断并列出假设）_")
+    lines.append("")
+
+    lines.append("### 求职方向（可选）")
+    lines.append("")
+    if role_focus and role_focus.strip():
+        lines.append(role_focus.strip())
+    else:
+        lines.append("_（未提供，请从描述推断或给出交叉标签）_")
+    lines.append("")
+
+    if extra and extra.strip():
+        lines.append("### 补充说明")
+        lines.append("")
+        lines.append(extra.strip())
+        lines.append("")
+
+    lines.extend(
+        [
+            "## 输出要求（摘要）",
+            "",
+            "- 面经：项目简介 1～2 句（简历向）；主问题 15～25；追问不计入总数；建议按 3～6 个主题组织，每主题至少 1 主问 + 2 追问。",
+            "- 面经：正文重心放在面试题口播，不单独输出「亮点拆解」章节。",
+            "- 口播：第一人称；主问与每个追问口播均 **≥150 字**，完整 STAR（场景→归因→动作→结果/兜底）。",
+            "- 导学：必须包含「重点亮点与学习顺序」和「推荐阅读」表，含 **仓库相对路径**。",
+            "- 导学：加一条固定自学提醒——看不懂继续问 AI，本 skill 不做逐行讲解。",
+            "- 量化与验证：仅导学可选添加（建议语气）；面经不强制该章节。",
+            "",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def _load_json(path: Path) -> dict[str, Any]:
+    raw = path.read_text(encoding="utf-8")
+    data = json.loads(raw)
+    if not isinstance(data, dict):
+        raise ValueError("JSON root must be an object")
+    return data
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI entry point."""
+    parser = argparse.ArgumentParser(
+        description="Build consolidated prompt for project-interview-skill."
+    )
+    parser.add_argument(
+        "--description",
+        "-d",
+        help="Project description text.",
+    )
+    parser.add_argument(
+        "--short-name",
+        "-s",
+        default="",
+        help="Short name for filenames: 导学-{简称}.md / 面经-{简称}.md",
+    )
+    parser.add_argument("--tech", default="", help="Technology stack string.")
+    parser.add_argument(
+        "--role",
+        default="",
+        help="Job direction, e.g. 前端 / 后端 / AI.",
+    )
+    parser.add_argument(
+        "--extra",
+        default="",
+        help="Additional notes appended under 补充说明.",
+    )
+    parser.add_argument(
+        "--json-file",
+        help="Path to JSON with keys: description, short_name?, tech_stack?, role_focus?, extra?.",
+    )
+    args = parser.parse_args(argv)
+
+    description = args.description or ""
+    tech = args.tech or ""
+    role = args.role or ""
+    short_name = args.short_name or ""
+    extra = args.extra or ""
+
+    if args.json_file:
+        try:
+            payload = _load_json(Path(args.json_file))
+        except (OSError, json.JSONDecodeError, ValueError) as exc:
+            print(f"Error loading JSON: {exc}", file=sys.stderr)
+            return 1
+        description = str(payload.get("description", "")).strip()
+        tech = str(payload.get("tech_stack", payload.get("tech", ""))).strip()
+        role = str(payload.get("role_focus", payload.get("role", ""))).strip()
+        short_name = str(payload.get("short_name", payload.get("简称", ""))).strip()
+        extra = str(payload.get("extra", "")).strip()
+
+    try:
+        short_name = _validate_short_name(short_name)
+    except ValueError as exc:
+        print(f"Error: invalid --short-name: {exc}", file=sys.stderr)
+        return 1
+
+    if not description:
+        print(
+            "Error: missing description. Use -d, or --json-file with description field.",
+            file=sys.stderr,
+        )
+        return 1
+
+    prompt = build_prompt(
+        description,
+        tech or None,
+        role or None,
+        short_name or None,
+        extra or None,
+    )
+    sys.stdout.write(prompt)
+    if not prompt.endswith("\n"):
+        sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/check_inputs.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""
+Validate project narrative inputs for project-interview-skill.
+
+Reads UTF-8 text from stdin or a file, checks for minimum signal,
+and prints suggested follow-up questions in Chinese.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Iterable
+
+
+MIN_DESCRIPTION_CHARS = 40
+KEYWORD_HINTS = (
+    "指标",
+    "qps",
+    "延迟",
+    "用户",
+    "线上",
+    "数据",
+    "规模",
+    "难点",
+    "结果",
+    "职责",
+)
+
+
+@dataclass
+class CheckResult:
+    """Outcome of input validation."""
+
+    ok: bool
+    missing: list[str] = field(default_factory=list)
+    suggestions: list[str] = field(default_factory=list)
+    notes: list[str] = field(default_factory=list)
+
+
+def _text_length(text: str) -> int:
+    """Character count after strip."""
+    return len(text.strip())
+
+
+def _has_any_keyword(text: str, keywords: Iterable[str]) -> bool:
+    lower = text.lower()
+    for kw in keywords:
+        if kw.lower() in lower:
+            return True
+    return False
+
+
+def analyze(description: str, tech_stack: str | None, role_focus: str | None) -> CheckResult:
+    """
+    Analyze user-provided fields and return gaps plus follow-up suggestions.
+
+    Args:
+        description: Required project description.
+        tech_stack: Optional technology list or sentence.
+        role_focus: Optional job direction (frontend/backend/AI).
+
+    Returns:
+        CheckResult with ok flag, missing topics, and concrete questions.
+    """
+    missing: list[str] = []
+    suggestions: list[str] = []
+    notes: list[str] = []
+
+    desc_len = _text_length(description)
+    if desc_len < MIN_DESCRIPTION_CHARS:
+        missing.append(
+            f"项目描述过短（当前约 {desc_len} 字符，建议至少 {MIN_DESCRIPTION_CHARS}+ "
+            "并包含职责、难点或结果线索）"
+        )
+
+    if not _has_any_keyword(description, KEYWORD_HINTS) and desc_len < MIN_DESCRIPTION_CHARS * 2:
+        suggestions.append(
+            "请补充：你在项目中的**具体职责**（独立负责模块 / 协作边界）？"
+        )
+        suggestions.append(
+            "请补充：一个**技术或业务难点**，以及你如何验证「已解决」？"
+        )
+
+    if not tech_stack or not tech_stack.strip():
+        suggestions.append(
+            "技术栈未提供：若补充语言/框架/存储/消息/观测栈，面试题会更准。"
+        )
+
+    if not role_focus or not role_focus.strip():
+        suggestions.append(
+            "求职方向未指定：目标是 **前端 / 后端 / AI** 中的哪些？会影响题目权重与标签。"
+        )
+
+    suggestions.extend(
+        [
+            "请描述一次**线上问题或惊险排障**：现象、定位手段、修复、复盘项？",
+            "若重新做一遍，你会在哪个**设计决策**上改变？为什么？",
+            "项目中**如何发布与回滚**（灰度、特性开关、数据迁移）？",
+        ]
+    )
+
+    if desc_len >= MIN_DESCRIPTION_CHARS:
+        notes.append("项目描述长度达标；可按追问补齐量化与线上证据。")
+
+    ok = len(missing) == 0
+    return CheckResult(ok=ok, missing=missing, suggestions=suggestions, notes=notes)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI entry point."""
+    parser = argparse.ArgumentParser(
+        description="Check project description completeness for project-interview-skill."
+    )
+    parser.add_argument(
+        "-f",
+        "--file",
+        help="Read project description from file (UTF-8).",
+    )
+    parser.add_argument(
+        "--tech",
+        default="",
+        help="Optional tech stack string.",
+    )
+    parser.add_argument(
+        "--role",
+        default="",
+        help="Optional job focus: frontend, backend, AI, etc.",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Print machine-readable JSON.",
+    )
+    args = parser.parse_args(argv)
+
+    if args.file:
+        try:
+            description = Path(args.file).read_text(encoding="utf-8").strip()
+        except OSError as exc:
+            print(f"Error reading file: {exc}", file=sys.stderr)
+            return 1
+    else:
+        description = sys.stdin.read().strip()
+
+    if not description:
+        print("Error: empty description. Pipe text or use --file.", file=sys.stderr)
+        return 1
+
+    tech = args.tech.strip() or None
+    role = args.role.strip() or None
+    result = analyze(description, tech, role)
+
+    if args.json:
+        print(json.dumps(asdict(result), ensure_ascii=False, indent=2))
+        return 0
+
+    status = "PASS" if result.ok else "NEEDS_INPUT"
+    print(f"[{status}] project-interview-skill input check\n")
+    if result.missing:
+        print("必须补齐：")
+        for item in result.missing:
+            print(f"  - {item}")
+        print()
+    print("建议追问：")
+    for q in result.suggestions:
+        print(f"  - {q}")
+    if result.notes:
+        print("\n备注：")
+        for n in result.notes:
+            print(f"  - {n}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())