Skip to content

zach22-1999/generic-skills / skills/zach-term-miner

zach-term-miner

Verified

术语挖掘:做一件事之前,先弄清楚这个领域里 AI 听得懂的专业术语,再用这些术语改写你的 prompt。 输入三句话(要做什么 / 已经知道什么 / 哪个领域),产出一个离线 HTML:5 个核验过来源的必要术语、 每个术语对应的「大白话 prompt → 术语版 prompt」前后对照、以及一条 30 分钟学习顺序。 用户说"术语挖掘""我要做 X,需要懂哪些术语才能跟你讲清楚""AI 总是理解偏""这个 prompt 怎么写得更专业" "帮我看看我该学什么术语"时使用。普通词义查询、已有完整 prompt 只想执行、或用户明确要求直接开始做原任务时不要触发。 本 skill 只出术语和 prompt 改写,不执行原任务;不编造术语和来源。

scripts/validate_pack.py

View on GitHub
#!/usr/bin/env python3
"""校验 term_prompt_pack JSON(以及可选的渲染后 HTML)。只依赖 Python 标准库。

用法:
    python3 scripts/validate_pack.py pack.json
    python3 scripts/validate_pack.py pack.json --html output.html
"""

from __future__ import annotations

import argparse
import json
import re
import sys
from html.parser import HTMLParser
from pathlib import Path
from typing import Any

ID_RE = re.compile(r"^[a-z0-9][a-z0-9._-]{1,79}$")
ARTIFACT_ID_RE = re.compile(r"^[a-z0-9][a-z0-9._-]{2,79}$")
SOURCE_KINDS = {"paper", "standard", "book", "official", "secondary", "user_material"}
STATUSES = {"verified", "source_defined", "private", "unverified"}
MAX_TERMS = 8
MAX_LEARNING_MINUTES = 40
DATA_SCRIPT_ID = "term-pack-data"
ROOT_ID = "zach-term-miner-root"


def load_json(path: Path) -> dict[str, Any]:
    try:
        data = json.loads(path.read_text(encoding="utf-8"))
    except (OSError, json.JSONDecodeError) as exc:
        raise ValueError(f"无法读取 JSON:{exc}") from exc
    if not isinstance(data, dict):
        raise ValueError("顶层必须是 JSON 对象")
    return data


def _obj(value: Any, path: str, errors: list[str]) -> dict[str, Any]:
    if not isinstance(value, dict):
        errors.append(f"{path} 必须是对象")
        return {}
    return value


def _text(value: Any, path: str, errors: list[str], *, allow_empty: bool = False) -> str:
    if not isinstance(value, str) or (not allow_empty and not value.strip()):
        errors.append(f"{path} 必须是非空字符串")
        return ""
    return value


def _text_list(value: Any, path: str, errors: list[str], *, min_items: int = 0, max_items: int | None = None) -> list[str]:
    if not isinstance(value, list):
        errors.append(f"{path} 必须是数组")
        return []
    items: list[str] = []
    for index, item in enumerate(value):
        items.append(_text(item, f"{path}[{index}]", errors))
    if len(items) < min_items:
        errors.append(f"{path} 至少 {min_items} 项")
    if max_items is not None and len(items) > max_items:
        errors.append(f"{path} 最多 {max_items} 项")
    if len(set(items)) != len(items):
        errors.append(f"{path} 不能有重复项")
    return items


def _keys(obj: dict[str, Any], path: str, required: set[str], allowed: set[str], errors: list[str]) -> None:
    missing = required - obj.keys()
    extra = obj.keys() - allowed
    if missing:
        errors.append(f"{path} 缺少字段:{', '.join(sorted(missing))}")
    if extra:
        errors.append(f"{path} 含未知字段:{', '.join(sorted(extra))}")


def _source(value: Any, path: str, errors: list[str]) -> None:
    src = _obj(value, path, errors)
    if not src:
        return
    _keys(src, path, {"title", "kind"}, {"title", "kind", "author", "year", "url"}, errors)
    _text(src.get("title"), f"{path}.title", errors)
    if src.get("kind") not in SOURCE_KINDS:
        errors.append(f"{path}.kind 必须是 {sorted(SOURCE_KINDS)} 之一")
    if "author" in src and not isinstance(src["author"], str):
        errors.append(f"{path}.author 必须是字符串")
    if "year" in src and not (isinstance(src["year"], int) and 1000 <= src["year"] <= 2200):
        errors.append(f"{path}.year 必须是 1000–2200 的整数")
    if "url" in src and not (isinstance(src["url"], str) and src["url"].startswith(("http://", "https://"))):
        errors.append(f"{path}.url 必须以 http:// 或 https:// 开头")


def validate_data(data: dict[str, Any]) -> list[str]:
    errors: list[str] = []
    top_required = {
        "artifact_kind", "schema_version", "artifact_id", "generated_at", "locale", "title", "summary",
        "task", "terms", "prompt_rewrites", "learning_path", "unverified", "evidence_summary",
    }
    _keys(data, "$", top_required, top_required, errors)
    if data.get("artifact_kind") != "term_prompt_pack":
        errors.append("artifact_kind 必须是 term_prompt_pack")
    if data.get("schema_version") != 1:
        errors.append("schema_version 必须是 1")
    artifact_id = _text(data.get("artifact_id"), "artifact_id", errors)
    if artifact_id and not ARTIFACT_ID_RE.match(artifact_id):
        errors.append("artifact_id 只能用小写字母、数字、点、下划线、连字符,长度 3–80")
    _text(data.get("generated_at"), "generated_at", errors)
    _text(data.get("locale"), "locale", errors)
    _text(data.get("title"), "title", errors)
    _text(data.get("summary"), "summary", errors)

    task = _obj(data.get("task"), "task", errors)
    if task:
        _keys(task, "task", {"goal", "known", "domain", "assumptions"}, {"goal", "known", "domain", "assumptions"}, errors)
        for key in ("goal", "known", "domain"):
            _text(task.get(key), f"task.{key}", errors)
        _text_list(task.get("assumptions"), "task.assumptions", errors)

    terms = data.get("terms")
    term_ids: set[str] = set()
    status_counts = {status: 0 for status in STATUSES}
    if not isinstance(terms, list) or not terms:
        errors.append("terms 必须是非空数组")
        terms = []
    if len(terms) > MAX_TERMS:
        errors.append(f"terms 最多 {MAX_TERMS} 个,当前 {len(terms)}")
    for index, raw in enumerate(terms):
        path = f"terms[{index}]"
        term = _obj(raw, path, errors)
        if not term:
            continue
        required = {"id", "term", "chinese_name", "definition", "why_for_this_task", "source_status", "sources"}
        _keys(term, path, required, required, errors)
        term_id = _text(term.get("id"), f"{path}.id", errors)
        if term_id:
            if not ID_RE.match(term_id):
                errors.append(f"{path}.id 格式不合法")
            if term_id in term_ids:
                errors.append(f"{path}.id 重复:{term_id}")
            term_ids.add(term_id)
        for key in ("term", "chinese_name", "definition", "why_for_this_task"):
            _text(term.get(key), f"{path}.{key}", errors)
        status = term.get("source_status")
        if status not in STATUSES:
            errors.append(f"{path}.source_status 必须是 {sorted(STATUSES)} 之一")
        else:
            status_counts[status] += 1
        sources = term.get("sources")
        if not isinstance(sources, list):
            errors.append(f"{path}.sources 必须是数组")
            sources = []
        for s_index, src in enumerate(sources):
            _source(src, f"{path}.sources[{s_index}]", errors)
        if status in {"verified", "source_defined"} and not sources:
            errors.append(f"{path} 状态为 {status} 但没有来源")
        if status == "private" and not any(isinstance(s, dict) and s.get("kind") == "user_material" for s in sources):
            errors.append(f"{path} 私有术语必须有一条 user_material 来源")
        if status == "private" and "非行业共识" not in (term.get("definition", "") + term.get("why_for_this_task", "")):
            errors.append(f"{path} 私有术语的定义或说明里必须写明「非行业共识」")

    rewrites = data.get("prompt_rewrites")
    rewrite_ids: set[str] = set()
    covered_terms: set[str] = set()
    if not isinstance(rewrites, list) or not rewrites:
        errors.append("prompt_rewrites 必须是非空数组")
        rewrites = []
    for index, raw in enumerate(rewrites):
        path = f"prompt_rewrites[{index}]"
        rw = _obj(raw, path, errors)
        if not rw:
            continue
        required = {"id", "term_ids", "plain_prompt", "term_prompt", "added_dimensions"}
        _keys(rw, path, required, required, errors)
        rw_id = _text(rw.get("id"), f"{path}.id", errors)
        if rw_id:
            if not ID_RE.match(rw_id):
                errors.append(f"{path}.id 格式不合法")
            if rw_id in rewrite_ids:
                errors.append(f"{path}.id 重复:{rw_id}")
            rewrite_ids.add(rw_id)
        ids = _text_list(rw.get("term_ids"), f"{path}.term_ids", errors, min_items=1, max_items=2)
        for tid in ids:
            if tid not in term_ids:
                errors.append(f"{path}.term_ids 引用了不存在的术语:{tid}")
            covered_terms.add(tid)
        plain = _text(rw.get("plain_prompt"), f"{path}.plain_prompt", errors)
        term_prompt = _text(rw.get("term_prompt"), f"{path}.term_prompt", errors)
        if plain and term_prompt and len(term_prompt) >= len(plain):
            errors.append(f"{path} 术语版 prompt 应比大白话版短(当前 {len(term_prompt)} ≥ {len(plain)} 字)")
        _text_list(rw.get("added_dimensions"), f"{path}.added_dimensions", errors, min_items=1)
    missing_cover = term_ids - covered_terms
    if missing_cover:
        errors.append(f"以下术语没有任何 prompt 对照:{', '.join(sorted(missing_cover))}")

    path_steps = data.get("learning_path")
    seen_steps: set[str] = set()
    total_minutes = 0
    if not isinstance(path_steps, list) or not path_steps:
        errors.append("learning_path 必须是非空数组")
        path_steps = []
    for index, raw in enumerate(path_steps):
        path = f"learning_path[{index}]"
        step = _obj(raw, path, errors)
        if not step:
            continue
        required = {"term_id", "minutes", "why_this_order"}
        _keys(step, path, required, required, errors)
        tid = _text(step.get("term_id"), f"{path}.term_id", errors)
        if tid and tid not in term_ids:
            errors.append(f"{path}.term_id 引用了不存在的术语:{tid}")
        if tid in seen_steps:
            errors.append(f"{path}.term_id 重复出现:{tid}")
        seen_steps.add(tid)
        minutes = step.get("minutes")
        if not (isinstance(minutes, int) and 1 <= minutes <= 30):
            errors.append(f"{path}.minutes 必须是 1–30 的整数")
        else:
            total_minutes += minutes
        _text(step.get("why_this_order"), f"{path}.why_this_order", errors)
    if term_ids - seen_steps:
        errors.append(f"以下术语没有进入学习顺序:{', '.join(sorted(term_ids - seen_steps))}")
    if total_minutes > MAX_LEARNING_MINUTES:
        errors.append(f"学习顺序合计 {total_minutes} 分钟,超过 {MAX_LEARNING_MINUTES} 分钟上限")

    unverified = data.get("unverified")
    if not isinstance(unverified, list):
        errors.append("unverified 必须是数组")
        unverified = []
    for index, raw in enumerate(unverified):
        path = f"unverified[{index}]"
        item = _obj(raw, path, errors)
        if item:
            _keys(item, path, {"term", "reason"}, {"term", "reason"}, errors)
            _text(item.get("term"), f"{path}.term", errors)
            _text(item.get("reason"), f"{path}.reason", errors)

    summary = _obj(data.get("evidence_summary"), "evidence_summary", errors)
    if summary:
        required = {"verified", "source_defined", "private", "unverified", "online_verification", "notes"}
        _keys(summary, "evidence_summary", required, required, errors)
        for key in ("verified", "source_defined", "private"):
            if not (isinstance(summary.get(key), int) and summary[key] >= 0):
                errors.append(f"evidence_summary.{key} 必须是非负整数")
            elif summary[key] != status_counts[key]:
                errors.append(f"evidence_summary.{key}={summary[key]} 与 terms 实际计数 {status_counts[key]} 不一致")
        if not (isinstance(summary.get("unverified"), int) and summary["unverified"] >= 0):
            errors.append("evidence_summary.unverified 必须是非负整数")
        elif summary["unverified"] != status_counts["unverified"] + len(unverified):
            errors.append(
                f"evidence_summary.unverified={summary['unverified']} 与实际(terms 中 {status_counts['unverified']} + 待核验区 {len(unverified)})不一致"
            )
        if not isinstance(summary.get("online_verification"), bool):
            errors.append("evidence_summary.online_verification 必须是布尔值")
        elif summary["online_verification"] is False and status_counts["verified"] + status_counts["source_defined"] > 0:
            errors.append("未联网核验时,terms 里不应出现 verified / source_defined 状态")
        _text_list(summary.get("notes"), "evidence_summary.notes", errors)
    return errors


class OfflineHTMLParser(HTMLParser):
    def __init__(self) -> None:
        super().__init__()
        self.external_assets: list[str] = []
        self.csp = ""
        self.data_script_count = 0
        self.root_found = False

    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
        values = dict(attrs)
        if tag == "script":
            if values.get("src"):
                self.external_assets.append(f"script src={values['src']}")
            if values.get("id") == DATA_SCRIPT_ID:
                self.data_script_count += 1
        if tag == "link":
            rel = values.get("rel") or ""
            if any(token in rel.split() for token in ("stylesheet", "preload", "modulepreload")):
                self.external_assets.append(f"link href={values.get('href', '')}")
        if tag in {"img", "iframe", "video", "audio"} and (values.get("src") or "").startswith(("http://", "https://")):
            self.external_assets.append(f"{tag} src={values.get('src')}")
        if tag == "meta" and (values.get("http-equiv") or "").lower() == "content-security-policy":
            self.csp = values.get("content") or ""
        if values.get("id") == ROOT_ID:
            self.root_found = True


def validate_html(path: Path) -> list[str]:
    try:
        html = path.read_text(encoding="utf-8")
    except OSError as exc:
        return [f"无法读取 HTML:{exc}"]
    errors: list[str] = []
    parser = OfflineHTMLParser()
    try:
        parser.feed(html)
    except Exception as exc:  # noqa: BLE001
        errors.append(f"HTML 解析失败:{exc}")
    if parser.external_assets:
        errors.append(f"存在外部资源:{', '.join(parser.external_assets)}")
    if parser.data_script_count != 1:
        errors.append(f"{DATA_SCRIPT_ID} 应恰好出现一次,当前 {parser.data_script_count}")
    if not parser.root_found:
        errors.append(f"缺少 #{ROOT_ID}")
    if not parser.csp:
        errors.append("缺少 Content-Security-Policy")
    elif "connect-src 'none'" not in parser.csp:
        errors.append("CSP 必须包含 connect-src 'none'")
    for needle in ("fetch(", "XMLHttpRequest", "new WebSocket", "sendBeacon", "import("):
        if needle in html:
            errors.append(f"HTML 含运行时网络 API:{needle}")
    return errors


def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("json_file", type=Path)
    parser.add_argument("--html", type=Path)
    args = parser.parse_args()
    try:
        errors = validate_data(load_json(args.json_file))
    except ValueError as exc:
        errors = [str(exc)]
    if args.html:
        errors.extend(validate_html(args.html))
    if errors:
        print("INVALID")
        for error in errors:
            print(f"- {error}")
        return 1
    print(f"VALID: {args.json_file}" + (f" + {args.html}" if args.html else ""))
    return 0


if __name__ == "__main__":
    sys.exit(main())
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall