kba-cli 0.3.0rc4__py3-none-any.whl

kba/cli.py

@@ -0,0 +1,552 @@
+"""KBA command line interface."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import time
+import traceback
+from pathlib import Path
+
+from . import (__version__, analyze, doctor, eval as eval_mod, extract,
+               fingerprint, jobs, report, summary as summary_mod, telemetry, util)
+
+
+def _print_json(obj) -> None:
+    print(json.dumps(obj, ensure_ascii=False, indent=2))
+
+
+def _brand(path: str | None) -> dict:
+    if not path:
+        return {}
+    return util.read_json(Path(path), {}) or {}
+
+
+# ---------- audit ----------
+
+def _write_params(job: Path, args) -> dict:
+    params = {
+        "root": str(Path(args.root).resolve()),
+        "exclude": args.exclude or sorted(util.DEFAULT_EXCLUDE),
+        "max_file_mb": args.max_file_mb,
+        "extract_dir": str(Path(args.extract_dir).resolve()) if args.extract_dir else None,
+        "redact": bool(args.redact_paths),
+    }
+    util.write_json(job / "params.json", params)
+    return params
+
+
+def _run_scan(job: Path, params: dict) -> dict:
+    try:
+        fp = fingerprint.scan(
+            root=Path(params["root"]),
+            job=job,
+            exclude=params.get("exclude"),
+            max_file_mb=params.get("max_file_mb", 200),
+            extract_dir=Path(params["extract_dir"]) if params.get("extract_dir") else None,
+            redact=params.get("redact", False),
+        )
+        return fp
+    except Exception as exc:  # noqa: BLE001
+        jobs.write_state(job, status="error", error=str(exc))
+        raise
+
+
+def _worker_main(job_dir: str) -> int:
+    job = Path(job_dir)
+    params = util.read_json(job / "params.json", {}) or {}
+    if not params:
+        jobs.write_state(job, status="error", error="params.json missing")
+        return 1
+    try:
+        fp = _run_scan(job, params)
+        s = fp["summary"]
+        print(f"[ok] {s['files']} files, {util.human_bytes(s['bytes'])}, "
+              f"text {s['with_text']}, unsupported {s.get('unsupported', 0)}")
+        return 0
+    except Exception:  # noqa: BLE001
+        (job / "worker.log").write_text(traceback.format_exc(), encoding="utf-8")
+        return 1
+
+
+def cmd_scan_summary(args) -> int:
+    root = Path(args.root).resolve()
+    if not root.is_dir():
+        print(f"[error] 目录不存在：{root}")
+        return 2
+    out = Path(args.out)
+    extract_dir = Path(args.extract_dir).resolve() if args.extract_dir else None
+    try:
+        with tempfile.TemporaryDirectory(prefix="kba-scan-") as td:
+            job = Path(td)
+            fp = fingerprint.scan(
+                root, job, exclude=args.exclude, max_file_mb=args.max_file_mb,
+                extract_dir=extract_dir,
+            )
+            result = analyze.analyze(job)
+            data = summary_mod.build_summary(fp, result)
+            util.write_json(out, data)
+    except (OSError, ValueError) as exc:
+        print(f"[error] {exc}")
+        return 2
+    if args.json:
+        _print_json(data)
+    else:
+        print(f"[ok] 摘要：{out}（{data['scan']['files']} 文件，置信度 {data['confidence']}）")
+        print("下一步：把摘要交给付费专家解读；不要上传原始文档。")
+    return 0
+
+
+def cmd_start(args) -> int:
+    root = Path(args.root).resolve()
+    if not root.is_dir():
+        print(f"[error] 目录不存在：{root}")
+        return 2
+    job_id = args.job or jobs.new_job_id()
+    job = jobs.job_dir(job_id)
+    job.mkdir(parents=True, exist_ok=True)
+    params = _write_params(job, args)
+    jobs.write_state(job, status="queued", stage="fingerprint", root=str(root),
+                     total=0, done=0, created_at=util.now_iso(), job_id=job_id)
+
+    swept = fingerprint.sweep_expired_text(skip_job=job_id)
+    if swept.get("files"):
+        print(f"[info] 已清理 {swept['files']} 个过期正文缓存（TTL {swept['ttl_days']} 天）")
+
+    if args.foreground:
+        fp = _run_scan(job, params)
+        s = fp["summary"]
+        print(f"[ok] 扫描完成：{s['files']} 个文件 / {util.human_bytes(s['bytes'])} / "
+              f"有文本 {s['with_text']} / 未支持格式 {s.get('unsupported', 0)}")
+        print(f"job: {job_id}")
+        print(f"下一步：kba audit analyze --job {job_id}")
+        return 0
+
+    log = open(job / "worker.log", "a", encoding="utf-8")
+    flags = 0
+    if os.name == "nt":
+        flags = 0x00000008 | 0x08000000  # DETACHED_PROCESS | CREATE_NO_WINDOW
+    subprocess.Popen([sys.executable, "-m", "kba", "_worker", str(job)],
+                     stdout=log, stderr=log, stdin=subprocess.DEVNULL,
+                     creationflags=flags, close_fds=True)
+    print(f"已启动：{job_id}")
+    print(f"进度：kba audit status --job {job_id}")
+    return 0
+
+
+def cmd_extract(args) -> int:
+    root = Path(args.root).resolve()
+    if not root.is_dir():
+        print(f"[error] 目录不存在：{root}")
+        return 2
+    out = Path(args.out).resolve()
+    ttl = args.ttl_days if args.ttl_days is not None and args.ttl_days >= 0 else None
+    try:
+        manifest = extract.extract_root(
+            root, out, exclude=args.exclude, overwrite=args.overwrite,
+            max_file_mb=args.max_file_mb, workers=args.workers, ttl_days=ttl,
+        )
+    except (ValueError, OSError) as exc:
+        print(f"[error] {exc}")
+        return 2
+    s = manifest["summary"]
+    print(f"[ok] 抽取完成：{s['files']} 个待处理文件 / 已抽取 {s['extracted']} / "
+          f"无文本 {s['no_text']} / 失败 {s['failed']} / 未支持 {s['unsupported']} / "
+          f"跳过已存在 {s['skipped_existing']}（workers={args.workers}）")
+    if s.get("missing_dependencies"):
+        deps = "、".join(f"{k}({v})" for k, v in s["missing_dependencies"].items())
+        print(f"[warn] 缺少抽取依赖：{deps}；安装：pip install -e .[extract]")
+    print(f"输出：{out}")
+    print(f"下一步：kba audit start --root \"{root}\" --extract-dir \"{out}\" --foreground")
+    return 0
+
+
+def _latest_with(name: str) -> str | None:
+    dirs = sorted([p for p in jobs.jobs_root().iterdir() if p.is_dir()],
+                  key=lambda p: p.stat().st_mtime, reverse=True)
+    for j in dirs:
+        if (j / name).exists():
+            return j.name
+    return None
+
+
+def _job_from_args(args, need: str | None = None) -> Path:
+    job_id = getattr(args, "job", None)
+    if not job_id and need:
+        job_id = _latest_with(need)
+    if not job_id:
+        job_id = jobs.latest_job()
+    if not job_id:
+        raise SystemExit("没有可用任务，先运行 kba audit start")
+    return jobs.job_dir(job_id)
+
+
+def cmd_status(args) -> int:
+    job = _job_from_args(args)
+    st = jobs.read_state(job)
+    if not st:
+        print(f"[error] 任务不存在：{job}")
+        return 2
+    if args.json:
+        _print_json(st)
+        return 0
+    total = st.get("total") or 0
+    done = st.get("done") or 0
+    pct = f"{done / total * 100:.0f}%" if total else "—"
+    print(f"任务 {job.name}：{st.get('status')} / {st.get('stage')}  {done}/{total} ({pct})")
+    if st.get("error"):
+        print(f"错误：{st['error']}")
+    if st.get("confidence"):
+        wc = st.get("weight_coverage")
+        wc_text = "—" if wc is None else f"{wc * 100:.0f}%"
+        print(f"数据置信度：{st['confidence']} ｜ 权重覆盖度 {wc_text}")
+    if st.get("status") == "done" and st.get("stage") == "fingerprint":
+        print(f"下一步：kba audit analyze --job {job.name}")
+    if st.get("status") == "done" and st.get("stage") == "analyze":
+        print(f"下一步：kba audit report --job {job.name} --out report.html")
+    return 0
+
+
+def cmd_analyze(args) -> int:
+    job = _job_from_args(args, "fp.json")
+    result = analyze.analyze(job, pack=args.pack)
+    telemetry.record(job)
+    m = result["metrics"]
+    dc = result.get("data_coverage") or {}
+    grade = dc.get("confidence") or result.get("confidence") or "C"
+    cov = dc.get("text_coverage")
+    cov_text = "—（无二进制文件）" if cov is None else f"{cov * 100:.1f}%"
+    print(f"[ok] 数据置信度 {grade}（文本覆盖率 {cov_text}）")
+    if grade == "C":
+        print("     元数据盘点版：不展示综合健康分；覆盖范围与结论边界见报告第 2 节")
+    else:
+        wc = ((result.get("health") or {}).get("weight_coverage") or 0) * 100
+        print(f"     归一化健康分 {result['health_score']}/100（权重覆盖度 {wc:.0f}%）")
+    print(f"     正文：纯文本 {dc.get('text_files', 0)} ｜ 可抽取文件已抽取 {dc.get('extracted', 0)}、"
+          f"无文本 {dc.get('no_text', 0)}、失败 {dc.get('failed', 0)}、未启用 {dc.get('not_enabled', 0)}"
+          f" ｜ 未支持 {dc.get('unsupported', 0)}")
+    print(f"     重复 {m['dup_groups']} 组 / 冗余 {m['dup_redundant']} 个（{m['dup_rate'] * 100:.1f}%）")
+    hit = "—" if m['top5_hit'] is None else f"{m['top5_hit'] * 100:.1f}%"
+    print(f"     过时 {m['stale_rate'] * 100:.1f}% ｜ 有效标签覆盖 {m['valid_tag_coverage'] * 100:.1f}%"
+          f"（推断 {m['inferred_tag_coverage'] * 100:.1f}%）｜ 自检索命中 {hit}")
+    print(f"     负责人覆盖 {m['owner_coverage'] * 100:.1f}% ｜ 断链 {m['broken_links']} 个"
+          f"（{m['broken_link_files']} 个文件）")
+    print(f"     预计工作量 {result['plan']['effort_days']} 人日")
+    print(f"下一步：kba audit report --job {job.name} --out report.html")
+    return 0
+
+
+def cmd_report(args) -> int:
+    job = _job_from_args(args, "analysis.json")
+    out = Path(args.out)
+    report.write_report(job, out, brand=_brand(args.brand), fmt=args.format)
+    analysis = util.read_json(job / "analysis.json", {}) or {}
+    grade = (analysis.get("data_coverage") or {}).get("confidence")
+    print(f"[ok] 报告：{out.resolve()}" + (f"（数据置信度 {grade}）" if grade else ""))
+    return 0
+
+
+def cmd_share(args) -> int:
+    job = _job_from_args(args, "analysis.json")
+    fp = util.read_json(job / "fp.json", {}) or {}
+    analysis = util.read_json(job / "analysis.json", {}) or {}
+    if not analysis:
+        print("[error] 先运行 kba audit analyze")
+        return 2
+    out = Path(args.out)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(report.render_share_md(analysis, fp), encoding="utf-8")
+    print(f"[ok] 摘要：{out.resolve()}")
+    return 0
+
+
+def cmd_summary(args) -> int:
+    job = _job_from_args(args, "analysis.json")
+    analysis = util.read_json(job / "analysis.json", {}) or {}
+    if not analysis:
+        print("[error] 先运行 kba audit analyze")
+        return 2
+    dc = analysis.get("data_coverage") or {}
+    grade = dc.get("confidence") or analysis.get("confidence")
+    out = {
+        "job_id": analysis.get("job_id"),
+        "confidence": grade,
+        # C-level metadata reports do not publish a composite score.
+        "health_score": None if grade == "C" else analysis.get("health_score"),
+        "weight_coverage": (analysis.get("health") or {}).get("weight_coverage"),
+        "data_coverage": dc,
+        "metrics": analysis.get("metrics"),
+        "findings": [{"type": f.get("type"), "title": f.get("title"), "count": f.get("count")}
+                     for f in analysis.get("findings", [])],
+    }
+    _print_json(out) if args.json else print(json.dumps(out, ensure_ascii=False, indent=2))
+    return 0
+
+
+def cmd_clusters(args) -> int:
+    job = _job_from_args(args, "analysis.json")
+    analysis = util.read_json(job / "analysis.json", {}) or {}
+    clusters = analysis.get("clusters", [])
+    if args.json:
+        _print_json(clusters[: args.top])
+        return 0
+    if not clusters:
+        print("未发现重复或同名组。")
+        return 0
+    print(f"{'组':<8}{'类型':<11}{'成员':<5}{'建议保留':<40}{'处置'}")
+    for c in clusters[: args.top]:
+        rec = c.get("recommend", {})
+        keep = next((x["name"] for x in c["members"] if x["p"] == rec.get("keep")), "—")
+        act = f"折叠 {len(rec.get('fold') or [])} 个" if rec.get("fold") else ("人工合并" if rec.get("merge") else "全部保留")
+        print(f"{c['id']:<8}{c['type']:<11}{len(c['members']):<5}{keep[:38]:<40}{act}")
+    if len(clusters) > args.top:
+        print(f"…还有 {len(clusters) - args.top} 组，用 --top 调整")
+    return 0
+
+
+# ---------- misc ----------
+
+def cmd_doctor(args) -> int:
+    result = doctor.run()
+    if args.json:
+        _print_json(result)
+    else:
+        doctor.print_report(result)
+    return 0 if result["ok"] else 2
+
+
+def cmd_version(args) -> int:
+    if args.json:
+        _print_json({"name": "kba", "version": __version__, "schema": "kba.version/1"})
+    else:
+        print(f"kba {__version__}")
+    return 0
+
+
+def cmd_eval(args) -> int:
+    root = Path(args.root).resolve()
+    if not root.is_dir():
+        print(f"[error] 目录不存在：{root}")
+        return 2
+    labels = {}
+    if args.labels:
+        labels = util.read_json(Path(args.labels), {}) or {}
+        if not isinstance(labels, dict):
+            print("[error] labels 必须是 JSON 对象")
+            return 2
+    try:
+        result = eval_mod.eval_corpus(
+            root, labels=labels,
+            extract_dir=Path(args.extract_dir).resolve() if args.extract_dir else None,
+        )
+    except (OSError, ValueError) as exc:
+        print(f"[error] {exc}")
+        return 2
+    if args.out:
+        util.write_json(Path(args.out), result)
+    if args.json:
+        _print_json(result)
+    else:
+        print(eval_mod.format_text(result))
+    return 0
+
+
+def cmd_telemetry(args) -> int:
+    if args.action == "on":
+        telemetry.set_enabled(True)
+        print("已开启匿名遥测（仅聚合指标，不含文件名/路径/正文）。")
+    elif args.action == "off":
+        telemetry.set_enabled(False)
+        q = jobs.kba_home() / "telemetry_queue.jsonl"
+        if q.exists():
+            q.unlink()
+        print("已关闭遥测，并清空未发送队列。")
+    elif args.action == "preview":
+        job = _job_from_args(args, "analysis.json")
+        _print_json(telemetry.preview(job))
+    else:
+        print(f"遥测：{'开启' if telemetry.enabled() else '关闭'}")
+        print(f"配置：{jobs.kba_home() / 'config.json'}")
+    return 0
+
+
+def cmd_clean(args) -> int:
+    if args.purge_extract:
+        if not args.dir:
+            print("[error] --purge-extract 需要 --dir <kba extract --out 目录>")
+            return 2
+        if args.purge_text:
+            print("[error] --purge-text 与 --purge-extract 不能同时使用")
+            return 2
+        try:
+            result = extract.purge_sidecars(
+                Path(args.dir), older_than_days=args.older_than_days
+            )
+        except OSError as exc:
+            print(f"[error] {exc}")
+            return 2
+        print(f"已清理 {result['files']} 个抽取 sidecar；剩余 {result['remaining']} 个，"
+              f"manifest {'保留' if result['manifest'] else '已删除'}")
+        return 0
+    if args.dir:
+        print("[error] --dir 只能与 --purge-extract 一起使用")
+        return 2
+    if args.purge_text:
+        if args.job:
+            targets = [jobs.job_dir(args.job)]
+        else:
+            targets = [p for p in jobs.jobs_root().iterdir() if p.is_dir()]
+        removed = 0
+        hit = 0
+        for j in targets:
+            n = fingerprint.purge_text(j)
+            if n:
+                removed += n
+                hit += 1
+                try:
+                    jobs.write_state(j, text_cache_purged_at=util.now_iso(),
+                                     text_cache_purged_files=n)
+                except OSError:
+                    pass
+        print(f"已清理 {removed} 个缓存正文文件（{hit} 个任务）")
+        return 0
+    if args.job:
+        print("[error] --job 只能与 --purge-text 一起使用")
+        return 2
+    cutoff = time.time() - args.days * 86400
+    removed = 0
+    for p in jobs.jobs_root().iterdir():
+        if p.is_dir() and p.stat().st_mtime < cutoff:
+            import shutil
+            shutil.rmtree(p, ignore_errors=True)
+            removed += 1
+    print(f"已清理 {removed} 个超过 {args.days} 天的任务")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(prog="kba", description="只读知识库体检工具")
+    ap.add_argument("--version", action="version", version=f"kba {__version__}")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p = sub.add_parser("doctor", help="环境检查")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=cmd_doctor)
+
+    p = sub.add_parser("version", help="版本")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=cmd_version)
+
+    p = sub.add_parser("extract", help="从 PDF/Office 抽取正文到 sidecar 目录")
+    p.add_argument("--root", required=True)
+    p.add_argument("--out", required=True, help="抽取文本目录，供 audit start --extract-dir 使用")
+    p.add_argument("--exclude", nargs="*")
+    p.add_argument("--overwrite", action="store_true", help="覆盖已存在的 sidecar")
+    p.add_argument("--max-file-mb", type=int, default=200)
+    p.add_argument("--workers", type=int, default=1,
+                   help="并行抽取线程数（1–16，默认 1）")
+    p.add_argument("--ttl-days", type=int, default=7,
+                   help="抽取前清理超过 N 天的 sidecar（-1 关闭，默认 7）")
+    p.set_defaults(func=cmd_extract)
+
+    p = sub.add_parser("eval", help="用标注语料评测抽取/分析指标")
+    p.add_argument("--root", required=True)
+    p.add_argument("--labels", help="标注 JSON；省略则只输出抽取/覆盖统计")
+    p.add_argument("--extract-dir", help="kba extract --out 目录")
+    p.add_argument("--out", help="把评测结果写入 JSON")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=cmd_eval)
+
+    p = sub.add_parser("scan-summary", help="一次性扫描+分析，输出脱敏摘要")
+    p.add_argument("--root", required=True)
+    p.add_argument("--out", required=True)
+    p.add_argument("--extract-dir")
+    p.add_argument("--exclude", nargs="*")
+    p.add_argument("--max-file-mb", type=int, default=200)
+    p.add_argument("--json", action="store_true", help="把摘要 JSON 打到 stdout")
+    p.set_defaults(func=cmd_scan_summary)
+
+    audit = sub.add_parser("audit", help="体检流程")
+    asub = audit.add_subparsers(dest="audit_cmd", required=True)
+
+    s = asub.add_parser("start", help="启动只读扫描")
+    s.add_argument("--root", required=True)
+    s.add_argument("--job")
+    s.add_argument("--exclude", nargs="*")
+    s.add_argument("--max-file-mb", type=int, default=200)
+    s.add_argument("--extract-dir", help="已有的抽取文本目录（可选）")
+    s.add_argument("--redact-paths", action="store_true", help="指纹中不保留原始路径/文件名")
+    s.add_argument("--foreground", action="store_true", help="前台执行（调试用）")
+    s.set_defaults(func=cmd_start)
+
+    s = asub.add_parser("status", help="查看进度")
+    s.add_argument("--job")
+    s.add_argument("--json", action="store_true")
+    s.set_defaults(func=cmd_status)
+
+    s = asub.add_parser("analyze", help="分析")
+    s.add_argument("--job")
+    s.add_argument("--pack", default="generic")
+    s.set_defaults(func=cmd_analyze)
+
+    s = asub.add_parser("report", help="生成报告")
+    s.add_argument("--job")
+    s.add_argument("--out", required=True)
+    s.add_argument("--format", choices=["html", "md"], default="html")
+    s.add_argument("--brand", help="品牌配置 JSON")
+    s.set_defaults(func=cmd_report)
+
+    s = asub.add_parser("share", help="生成一页纸摘要")
+    s.add_argument("--job")
+    s.add_argument("--out", required=True)
+    s.set_defaults(func=cmd_share)
+
+    s = asub.add_parser("summary", help="输出指标与问题清单（JSON）")
+    s.add_argument("--job")
+    s.add_argument("--json", action="store_true")
+    s.set_defaults(func=cmd_summary)
+
+    cl = sub.add_parser("clusters", help="重复簇")
+    clsub = cl.add_subparsers(dest="cluster_cmd", required=True)
+    s = clsub.add_parser("list", help="列出重复簇")
+    s.add_argument("--job")
+    s.add_argument("--top", type=int, default=20)
+    s.add_argument("--json", action="store_true")
+    s.set_defaults(func=cmd_clusters)
+
+    t = sub.add_parser("telemetry", help="匿名遥测")
+    t.add_argument("action", choices=["status", "on", "off", "preview"])
+    t.add_argument("--job")
+    t.set_defaults(func=cmd_telemetry)
+
+    c = sub.add_parser("clean", help="清理旧任务或正文缓存")
+    c.add_argument("--days", type=int, default=30, help="删除超过 N 天的整个任务目录")
+    c.add_argument("--purge-text", action="store_true",
+                   help="只清理 job/text/ 正文缓存，不删除任务（默认 TTL 7 天，可随时手动清理）")
+    c.add_argument("--purge-extract", action="store_true",
+                   help="按 extract.json 清理 kba extract --out 目录的 sidecar")
+    c.add_argument("--dir", help="配合 --purge-extract，指定抽取输出目录")
+    c.add_argument("--older-than-days", type=int,
+                   help="配合 --purge-extract，只清理超过 N 天的 sidecar；省略则全部清理")
+    c.add_argument("--job", help="配合 --purge-text，只清理指定任务")
+    c.set_defaults(func=cmd_clean)
+
+    return ap
+
+
+def main(argv=None) -> int:
+    try:
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, ValueError):
+        pass
+    if argv is None:
+        argv = sys.argv[1:]
+    if argv and argv[0] == "_worker":
+        return _worker_main(argv[1])
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)

kba/doctor.py

@@ -0,0 +1,73 @@
+"""Environment self-check."""
+from __future__ import annotations
+
+import importlib.util
+import os
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+
+from . import util
+from .jobs import kba_home
+
+
+def run() -> dict:
+    checks = []
+
+    def add(name, ok, detail, fix=""):
+        checks.append({"name": name, "status": "ok" if ok else "warn", "detail": detail, "fix": fix})
+
+    ver = sys.version_info
+    add("Python", ver >= (3, 10), f"{ver.major}.{ver.minor}.{ver.micro}", "安装 Python 3.10+")
+    add("平台", True, f"{sys.platform} ({os.name})")
+    home = kba_home()
+    try:
+        home.mkdir(parents=True, exist_ok=True)
+        probe = home / ".probe"
+        probe.write_text("ok", encoding="utf-8")
+        probe.unlink()
+        add("数据目录可写", True, str(home))
+    except OSError as exc:
+        add("数据目录可写", False, f"{home}: {exc}", "检查目录权限或设置 KBA_HOME")
+
+    try:
+        free = shutil.disk_usage(home).free
+        add("磁盘空间", free > 200 * 1024 * 1024, util.human_bytes(free), "清理磁盘")
+    except OSError:
+        add("磁盘空间", True, "未知")
+
+    try:
+        d = Path(tempfile.mkdtemp(prefix="kba-中文路径-"))
+        p = d / "测试 文件.md"
+        p.write_text("ok", encoding="utf-8")
+        p.unlink()
+        d.rmdir()
+        add("中文/空格路径", True, "通过")
+    except OSError as exc:
+        add("中文/空格路径", False, str(exc), "检查系统编码设置")
+
+    for mod, label, fix in (
+        ("pypdf", "pypdf（pdf 文本）", "pip install -e .[extract]"),
+        ("docx", "python-docx（docx 文本）", "pip install -e .[extract]"),
+        ("pptx", "python-pptx（pptx 文本）", "pip install -e .[extract]"),
+        ("openpyxl", "openpyxl（xlsx 文本/结构指纹）", "pip install -e .[extract]"),
+    ):
+        ok = importlib.util.find_spec(mod) is not None
+        add(label, ok, "已安装" if ok else "未安装（相应格式只做盘点，不做文本分析）", fix)
+
+    return {
+        "ok": all(c["status"] == "ok" for c in checks),
+        "version": __import__("kba").__version__,
+        "checks": checks,
+    }
+
+
+def print_report(result: dict) -> None:
+    print(f"KBA {result['version']} 环境检查")
+    for c in result["checks"]:
+        mark = "OK  " if c["status"] == "ok" else "WARN"
+        print(f"[{mark}] {c['name']}: {c['detail']}")
+        if c["status"] != "ok" and c["fix"]:
+            print(f"       修复：{c['fix']}")
+    print("\n结论：", "可用" if result["ok"] else "有警告，部分能力受限")