用途:在活跃开发中快速查询代码结构,回答“改这个接口前谁依赖它”“这个改动影响多少模块”等问题。
主要能力(五种查询模式): --file:输出文件骨架,含类、方法、行号与 import 清单; --who-imports:列出所有 import 该模块的调用方,区分源码与测试文件; --impact:给出上游依赖与下游被依赖数量(X upstream, Y downstream); --hub-analysis:按扇入、扇出排序全仓库核心节点,可加 --top N; --summary:按顶层目录聚合结构摘要。
使用方式:先确保 ast_nodes.json 可用,默认路径为 $repo_path/.nexus-map/raw/ast_nodes.json。若不存在,先执行: mkdir -p "$repo_path/.nexus-map/raw" python $SKILL_DIR/scripts/extract_ast.py $repo_path > $AST_JSON 可选生成 git 风险数据: python $SKILL_DIR/scripts/git_detective.py $repo_path --days 90 > $GIT_JSON 首次使用需安装依赖:pip install -r $SKILL_DIR/scripts/requirements.txt 查询示例:python $SKILL_DIR/scripts/query_graph.py $AST_JSON --file <path>;--who-imports <module_or_path>;--impact <path>;--hub-analysis;--summary。
扫描过滤:extract_ast.py 默认排除 .git/、.nexus-map/、node_modules/、pycache/、.venv/、dist/、build/ 等,并默认读取 .gitignore;可用 --exclude-dirs 追加排除目录,--no-gitignore 关闭 .gitignore 规则(内置排除项与 --exclude-dirs 仍生效)。
适用场景:接手大型模块前了解骨架、删函数或改签名前排查调用方、Sprint 估时评估改动范围、架构评审找高耦合核心、初次接触项目建立分层认知。
限制:需要本地 Python 3.10+ 与 shell 执行能力;若用户希望生成完整 .nexus-map/ 知识库,应改用 nexus-mapper;无 .git 或历史不足时可跳过 git 数据,仅用 AST 查询;路径支持片段匹配,返回 [NOT FOUND] 时先用 --summary 确认路径格式。建议先用 --file 读骨架再跑 --impact 或 --who-imports,避免误判。