"""命令行工具:查看与分析 `state/param_usage.json` 记录,或静态扫描代码中的跟踪调用。 用法示例: python tools/param_usage_tool.py show --limit 200 python tools/param_usage_tool.py scan --pattern track_param python tools/param_usage_tool.py tail """ from __future__ import annotations import argparse import json import os import sys import time from collections import defaultdict from typing import Dict, List ROOT = os.path.abspath(os.path.dirname(os.path.dirname(__file__))) STATE_PATH = os.path.join(ROOT, "state", "param_usage.json") def read_entries(path: str) -> List[Dict]: if not os.path.exists(path): return [] out = [] with open(path, "r", encoding="utf-8") as f: for line in f: line = line.strip() if not line: continue try: out.append(json.loads(line)) except Exception: continue return out def cmd_show(args: argparse.Namespace) -> int: entries = read_entries(STATE_PATH) if not entries: print("no entries found: {}".format(STATE_PATH)) return 1 if args.limit: entries = entries[-args.limit :] by_param = defaultdict(list) calls = [] for e in entries: t = e.get("type") if t == "param_access": by_param[e.get("param")].append(e) else: calls.append(e) print("Summary:") print(" param_access entries: {}".format(sum(len(v) for v in by_param.values()))) print(" call entries: {}".format(len(calls))) print("") if args.param: items = by_param.get(args.param) if not items: print(f"no records for param: {args.param}") return 0 for i in items: print(json.dumps(i, ensure_ascii=False)) return 0 # show top params top = sorted(by_param.items(), key=lambda kv: -len(kv[1]))[: args.top] for name, lst in top: first = lst[0] print( f"{name}: count={len(lst)} first_at={first.get('caller_file')}:{first.get('caller_line')}" ) return 0 def cmd_tail(args: argparse.Namespace) -> int: print("tailing {} (press Ctrl-C to stop)".format(STATE_PATH)) try: with open(STATE_PATH, "r", encoding="utf-8") as f: # seek to end f.seek(0, os.SEEK_END) while True: line = f.readline() if not line: time.sleep(0.5) continue print(line.rstrip()) except KeyboardInterrupt: return 0 except FileNotFoundError: print("file not found: {}".format(STATE_PATH)) return 1 def cmd_scan(args: argparse.Namespace) -> int: root = os.path.abspath(args.root or ROOT) matches = [] for dirpath, dirs, files in os.walk(root): # skip virtual envs and .git if ".venv" in dirpath or ".git" in dirpath: continue for fn in files: if not fn.endswith((".py", ".md", ".txt")): continue path = os.path.join(dirpath, fn) try: with open(path, "r", encoding="utf-8", errors="ignore") as f: for i, line in enumerate(f, 1): if args.pattern in line: matches.append((path, i, line.strip())) except Exception: continue for p, lno, text in matches: print(f"{p}:{lno}: {text}") print(f"found {len(matches)} matches for '{args.pattern}'") return 0 def main(argv: List[str]) -> int: p = argparse.ArgumentParser(description="Param usage viewer tool") sp = p.add_subparsers(dest="cmd") s_show = sp.add_parser("show") s_show.add_argument("--limit", type=int, default=200) s_show.add_argument("--top", type=int, default=20) s_show.add_argument("--param", type=str, help="show specific param records") s_show.set_defaults(func=cmd_show) s_tail = sp.add_parser("tail") s_tail.set_defaults(func=cmd_tail) s_scan = sp.add_parser("scan") s_scan.add_argument("pattern", help="substring to search for") s_scan.add_argument("--root", help="root to scan") s_scan.set_defaults(func=cmd_scan) args = p.parse_args(argv) if not args.cmd: p.print_help() return 1 return args.func(args) if __name__ == "__main__": raise SystemExit(main(sys.argv[1:]))