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 改写,不执行原任务;不编造术语和来源。
| File | Kind | Size |
|---|---|---|
| .gitignore | other | 60 B |
| LICENSE | other | 1.0 KB |
| README.md | markdown | 5.0 KB |
| SKILL.md | skill md | 5.7 KB |
| examples/listing-bullets.html | other | 20.5 KB |
| examples/non-ecommerce.html | other | 20.3 KB |
| examples/review-mining.html | other | 21.3 KB |
| references/prompt-rewrite-guide.md | markdown | 3.3 KB |
| references/term-prompt-pack.schema.json | config | 4.8 KB |
| references/term-selection-rubric.md | markdown | 2.7 KB |
| scripts/fixtures/listing-bullets.json | config | 7.5 KB |
| scripts/fixtures/non-ecommerce.json | config | 7.5 KB |
| scripts/fixtures/review-mining.json | config | 8.0 KB |
| scripts/render_pack.py | script | 12.9 KB |
| scripts/test_pipeline.py | script | 6.5 KB |
| scripts/validate_pack.py | script | 15.0 KB |
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())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |