nexus-query

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

nexus-query — 代码结构精准查询

nexus-query — Precise Code Structure Query

"改之前先算清楚——数字比猜测更有力。"

本 Skill 将

extract_ast.py

、

git_detective.py

、

query_graph.py

三个脚本封装成一个开发辅助工具：按需生成数据、精确回答问题。

"Calculate clearly before making changes — numbers speak louder than guesses."

This Skill encapsulates three scripts:

extract_ast.py

git_detective.py

, and

query_graph.py

, into a development assistant tool: generate data on demand and provide precise answers to your questions.

📌 和 nexus-mapper 的区别

📌 Differences from nexus-mapper

维度	nexus-mapper	nexus-query
目的	为 AI 建立项目持久记忆（ `.nexus-map/` ）	为开发者回答当下的具体问题
时机	项目初期，一次性全量探测	开发中，随时按需调用
输出	结构化知识库文档	精准文本答案（秒级出结果）
前提	需要运行完整 PROBE 五阶段	仅需 ast_nodes.json 存在即可

nexus-query 是 nexus-mapper 的轻量伴侣：如果

.nexus-map/

已存在，直接复用；如果不存在，先运行

extract_ast.py

生成 ast_nodes.json，再开始查询。

Dimension	nexus-mapper	nexus-query
Purpose	Build persistent project memory for AI ( `.nexus-map/` )	Answer developers' immediate specific questions
Timing	One-time full detection at project initiation	On-demand invocation during development
Output	Structured knowledge base documents	Precise text answers (results in seconds)
Prerequisite	Requires running the complete 5-stage PROBE process	Only requires ast_nodes.json to exist

nexus-query is the lightweight companion of nexus-mapper: If

.nexus-map/

already exists, reuse it directly; if not, run

extract_ast.py

first to generate ast_nodes.json before starting queries.

📌 何时调用

📌 When to Invoke

场景	调用
「这个文件有哪些类/方法，依赖什么」	✅
「改这个接口/模块，哪些文件受影响」	✅
「这个改动的影响半径是多大」	✅
「项目里谁是真正的核心依赖节点」	✅
「整个项目大概分哪几块」	✅
用户希望生成完整的 `.nexus-map/` 知识库	❌ → 改用 nexus-mapper
运行环境无 shell 执行能力	❌
宿主机无本地 Python 3.10+	❌

Scenario	Invoke?
What classes/methods does this file have, and what does it depend on?	✅
Which files will be affected if I modify this interface/module?	✅
What is the impact scope of this change?	✅
Which module is the true core dependency node in the project?	✅
How is the entire project roughly structured?	✅
User wants to build a complete `.nexus-map/` knowledge base	❌ → Use nexus-mapper instead
No shell execution capability in the runtime environment	❌
No local Python 3.10+ on the host machine	❌

⚙️ 前提：确保 ast_nodes.json 可用

⚙️ Prerequisite: Ensure ast_nodes.json is Available

进入查询前 → 检查是否有 ast_nodes.json
├── 有（.nexus-map/raw/ast_nodes.json 或用户指定路径）→ 直接查询
└── 没有 → 运行 extract_ast.py 生成 → 再查询

bash

undefined

Before starting a query → Check if ast_nodes.json exists
├── Exists (at .nexus-map/raw/ast_nodes.json or user-specified path) → Proceed with query directly
└── Does not exist → Run extract_ast.py to generate it → Then start query

bash

undefined

默认路径（和 nexus-mapper 的 .nexus-map/ 兼容，可互通）

Default path (compatible with nexus-mapper's .nexus-map/, interoperable)

AST_JSON="$repo_path/.nexus-map/raw/ast_nodes.json" GIT_JSON="$repo_path/.nexus-map/raw/git_stats.json" # 可选

AST_JSON="$repo_path/.nexus-map/raw/ast_nodes.json" GIT_JSON="$repo_path/.nexus-map/raw/git_stats.json" # Optional

若 ast_nodes.json 不存在，先创建目录再生成（约数秒）

If ast_nodes.json does not exist, create directory first then generate (takes a few seconds)

mkdir -p "$repo_path/.nexus-map/raw" python $SKILL_DIR/scripts/extract_ast.py $repo_path > $AST_JSON

若需要 git 风险数据（可选，仅在存在 .git 时）

If git risk data is needed (optional, only if .git exists)

python $SKILL_DIR/scripts/git_detective.py $repo_path --days 90 \

$GIT_JSON


> `$SKILL_DIR` 为本 Skill 的安装路径（`.agent/skills/nexus-query` 或独立 repo 路径）。

**依赖安装（首次使用）**：
```bash
pip install -r $SKILL_DIR/scripts/requirements.txt

python $SKILL_DIR/scripts/git_detective.py $repo_path --days 90 \

$GIT_JSON


> `$SKILL_DIR` is the installation path of this Skill (`.agent/skills/nexus-query` or independent repo path).

**Dependency Installation (First Use)**:
```bash
pip install -r $SKILL_DIR/scripts/requirements.txt

🔍 五个查询模式

🔍 Five Query Modes

bash

undefined

bash

undefined

查看某个文件的类/函数结构及 import 清单

View the class/function structure and import list of a specific file

python $SKILL_DIR/scripts/query_graph.py $AST_JSON --file <path> python $SKILL_DIR/scripts/query_graph.py $AST_JSON --file <path> --git-stats $GIT_JSON

反向依赖查询：谁 import 了这个模块

Reverse dependency query: Which modules import this one

python $SKILL_DIR/scripts/query_graph.py $AST_JSON --who-imports <module_or_path>

影响半径：上游依赖 + 下游被依赖者（推荐叠加 git-stats）

Impact scope: Upstream dependencies + downstream dependents (recommended to combine with git-stats)

python $SKILL_DIR/scripts/query_graph.py $AST_JSON --impact <path> python $SKILL_DIR/scripts/query_graph.py $AST_JSON --impact <path> --git-stats $GIT_JSON

高扇入/扇出核心节点识别

Identify core nodes with high in-degree/out-degree

python $SKILL_DIR/scripts/query_graph.py $AST_JSON --hub-analysis [--top N]

按顶层目录聚合的结构摘要

Structure summary aggregated by top-level directory

python $SKILL_DIR/scripts/query_graph.py $AST_JSON --summary

---

python $SKILL_DIR/scripts/query_graph.py $AST_JSON --summary

---

--file <路径> — 文件骨架解剖

--file <path> — File Skeleton Analysis

输出：类、方法、行号范围、所有 import（内部 import 解析成真实路径）。加

--git-stats

追加变更热度和耦合文件。

深层价值：AI 不读源码也能掌握文件结构，精确到行号；针对大型遗留代码库尤其有效——一个 3000 行的 legacy 模块可能有数十个类，逐行阅读效率极低，

--file

秒出骨架，按行号精准跳转。

适用场景：

接手超大遗留模块（"屎山"代码），建立结构地图再动手
连续重构任务中，确认当前目标文件的完整方法签名，避免改了一处遗漏其他重载
Bug 调查：快速确认候选类/函数的行号范围，缩小
```
view_file
```
的读取区间
Code Review：确认一个 PR 涉及到的方法是否在预期边界内

Output: Classes, methods, line number ranges, all imports (internal imports resolved to real paths). Add

--git-stats

to append change heat and coupled files.

Deep Value: AI can grasp the file structure down to line numbers without reading the source code; it is especially effective for large legacy codebases — a 3000-line legacy module may have dozens of classes, and line-by-line reading is extremely inefficient.

--file

generates the skeleton in seconds, enabling precise jumps by line numbers.

Applicable Scenarios:

Taking over a huge legacy module ("spaghetti code"), build a structure map before making changes
During continuous refactoring tasks, confirm the complete method signatures of the target file to avoid missing other overloads after modifying one
Bug investigation: Quickly confirm the line number range of candidate classes/functions to narrow down the reading range of
```
view_file
```
Code Review: Confirm whether the methods involved in a PR are within the expected boundaries

--who-imports <路径或模块名> — 反向依赖追踪

--who-imports <path or module name> — Reverse Dependency Tracking

输出：所有引用了该模块的文件（区分源码文件和测试文件）。

深层价值：改接口之前唯一必须跑的命令。任何修改公共函数签名、删除方法、重命名类的操作如果跳过这步，都是在赌不会炸。

适用场景：

删函数/改签名/迁移模块前，确认「炸弹清单」——列出所有需要同步修改的调用方
连续开发任务中，修改了 step 1 的接口后，确认后续 step 2~N 哪些受影响，规划工作顺序
决定测试策略：知道谁依赖了目标模块，才能做精准回归测试而不是全量跑
评估「是否值得重构这个老接口」：依赖方越多，重构成本越高；0 个依赖方 = 可以随意重构

Output: All files that reference this module (distinguishing between source code files and test files).

Deep Value: The only command you must run before modifying an interface. Skipping this step when modifying public function signatures, deleting methods, or renaming classes is a gamble that nothing will break.

Applicable Scenarios:

Before deleting functions, modifying signatures, or migrating modules, confirm the "bomb list" — list all callers that need synchronous modifications
During continuous development tasks, after modifying the interface in step 1, confirm which subsequent steps 2~N are affected and plan the work sequence
Determine testing strategies: Only by knowing who depends on the target module can you perform precise regression testing instead of full-scale testing
Evaluate "whether it is worth refactoring this old interface": The more dependents there are, the higher the refactoring cost; 0 dependents = can refactor freely

--impact <路径> [--git-stats] — 影响半径量化

--impact <path> [--git-stats] — Impact Scope Quantification

输出：上游依赖（这个文件引用了谁）+ 下游被依赖（谁引用了这个文件），最终给出

X upstream, Y downstream

数字。加

--git-stats

追加 git 风险等级和耦合对。

深层价值：最有实战价值的单一命令。

0 upstream, 24 downstream

一眼告诉你这是基础层，改动影响最广；

upstream

数字高往往意味着它依赖很多东西，自己也容易被连锁影响。与 git-stats 叠加后：high-risk + high downstream = 当前最危险的改动点。

适用场景：

衡量一个功能修改的风险与实际工作量，在 Sprint 估时/技术债偿还决策时有直接参考价值
评估「当前这个改动是局部手术还是全局手术」——downstream 数字决定了测试范围
架构评审时，对「候选重构模块」做影响量化：改哪个代价最小？
遗留系统拆分规划：downstream 很高的模块先不动，从边缘模块开始清理

Output: Upstream dependencies (who this file references) + downstream dependents (who references this file), finally giving the numbers

X upstream, Y downstream

. Add

--git-stats

to append git risk levels and coupled pairs.

Deep Value: The most practically valuable single command.

0 upstream, 24 downstream

tells you at a glance that this is a base layer, and changes will have the widest impact; a high

upstream

number often means it depends on many things and is prone to chain reactions. When combined with git-stats: high-risk + high downstream = the most dangerous change point currently.

Applicable Scenarios:

Measure the risk and actual workload of a feature modification, which has direct reference value for Sprint estimation/technical debt repayment decisions
Evaluate "whether the current change is a local or global operation" — the downstream number determines the testing scope
During architecture reviews, quantify the impact of "candidate refactoring modules": Which one has the lowest refactoring cost?
Legacy system splitting planning: Leave modules with high downstream dependencies untouched first, and start cleaning from edge modules

--hub-analysis [--top N] — 架构核心节点识别

--hub-analysis [--top N] — Architecture Core Node Identification

输出：按扇入（被多少模块引用）和扇出（引用了多少模块）排序的全仓库模块列表，直接揭示真实核心节点。

深层价值：目录名 ≠ 重要性。命名为

core/

的不一定是实际核心；真正的高耦合节点往往藏在不起眼的工具类、数据模型或配置模块里。扇入高 = 很多人依赖它，扇出高 = 它依赖很多人，两者都高 = 「蛛网中心」，改动最危险。

适用场景：

架构评审：找出「明星模块」——被所有人依赖却从不在路线图里出现的那个
技术债优先级排序：扇入高 + git-stats risk high = 最值得重构的目标（风险高、影响大）
遗留代码清理入口：扇出极高但扇入很低的模块，是可以安全替换或拆分的「孤立节点」
新同学接手项目：先看扇入 Top 5，这几个模块搞懂了，项目的一半架构就清楚了

Output: A list of all repository modules sorted by in-degree (how many modules reference it) and out-degree (how many modules it references), directly revealing the true core nodes.

Deep Value: Directory name ≠ importance. A module named

core/

is not necessarily the actual core; true high-coupling nodes are often hidden in unassuming utility classes, data models, or configuration modules. High in-degree = many dependents, high out-degree = depends on many others, both high = "spider web center", the most dangerous to modify.

Applicable Scenarios:

Architecture review: Identify the "star module" — the one that everyone depends on but never appears in the roadmap
Technical debt priority ranking: High in-degree + high git-stats risk = the most worthy refactoring target (high risk, high impact)
Legacy code cleanup entry point: Modules with extremely high out-degree but low in-degree are "isolated nodes" that can be safely replaced or split
New team members taking over the project: First look at the top 5 modules by in-degree; understanding these modules will clarify half of the project's architecture

--summary — 全局目录聚合

--summary — Global Directory Aggregation

输出：按顶层目录分区统计模块数/类数/函数数/行数，附带各区域的 import 关系。

深层价值：用一条命令建立系统分层意识。哪个目录是「业务逻辑层」、哪个是「基础设施层」、哪个是「测试层」，从 import 关系图里直接读出来比读任何文档都客观。

适用场景：

项目初次接触（5 秒摸清全局）：比读 README 更客观，比手动 ls 更结构化
识别循环依赖风险区域：两个顶层目录互相 import 是架构坏味道，
```
--summary
```
立刻暴露
项目交接给新成员：一张聚合表替代冗长的架构介绍文档
评估测试覆盖均衡性：tests 目录的函数数 vs src 目录的函数数，比例是否合理

Output: Statistics on the number of modules/classes/functions/lines partitioned by top-level directory, along with import relationships between regions.

Deep Value: Establish a system layering awareness with one command. Which directory is the "business logic layer", which is the "infrastructure layer", and which is the "test layer" — reading directly from the import relationship graph is more objective than reading any document.

Applicable Scenarios:

First contact with the project (grasp the whole picture in 5 seconds): More objective than reading the README, more structured than manual ls
Identify circular dependency risk areas: Mutual imports between two top-level directories are an architecture smell, and
```
--summary
```
exposes it immediately
Handing over the project to new members: An aggregation table replaces lengthy architecture introduction documents
Evaluate test coverage balance: The ratio of the number of functions in the tests directory to that in the src directory, whether the ratio is reasonable

场景速查

Scenario Quick Reference

你此刻的问题	用哪个
这个文件有哪些类/方法，各在哪几行	`--file`
改这个接口/删这个函数，哪些文件跟着改	`--who-imports`
这个改动最终会影响多少模块	`--impact`
这个改动风险有多高（加 git 热度）	`--impact --git-stats`
项目里谁是真正的高耦合中心	`--hub-analysis`
整个项目的模块分布和层级关系	`--summary`
连续重构任务，改完一处要看影响链	`--who-imports` → `--impact`
估算技术债改造的工作量	`--hub-analysis` → `--impact`

Your Current Question	Which to Use
What classes/methods does this file have, and which lines are they on?	`--file`
Which files need to be modified along with this interface change/function deletion?	`--who-imports`
How many modules will be ultimately affected by this change?	`--impact`
How high is the risk of this change (add git heat)?	`--impact --git-stats`
Which is the true high-coupling center in the project?	`--hub-analysis`
What is the module distribution and hierarchical relationship of the entire project?	`--summary`
During continuous refactoring tasks, check the impact chain after modifying one part	`--who-imports` → `--impact`
Estimate the workload of technical debt transformation	`--hub-analysis` → `--impact`

🧠 执行守则

🧠 Execution Guidelines

守则1: 先读引用再查询

Guideline 1: Read References Before Querying

在使用

--impact

或

--who-imports

分析某个模块前，建议先用

--file

读取其骨架，理解它的职责和现有 import，避免对查询结果产生误判。

Before using

--impact

--who-imports

to analyze a module, it is recommended to first use

--file

to read its skeleton, understand its responsibilities and existing imports, to avoid misjudging the query results.

守则2: git-stats 是加分项，不是硬阻塞

Guideline 2: git-stats is a Bonus, Not a Hard Block

没有

.git

或 git 历史不足时，跳过

git_detective.py

，只用 AST 数据查询。不要因为缺少 git 数据而停止查询，降级继续。

When there is no

.git

or insufficient git history, skip

git_detective.py

and only use AST data for queries. Do not stop querying due to the lack of git data; continue with degraded functionality.

守则3: 路径匹配灵活但要验证

Guideline 3: Flexible Path Matching but Needs Verification

query_graph.py

支持路径片段匹配（如

vision.py

可匹配

src/core/vision.py

）。当结果返回

[NOT FOUND]

时，先用

--summary

确认仓库中存在的模块路径格式，再重新查询。

query_graph.py

supports path fragment matching (e.g.,

vision.py

can match

src/core/vision.py

). When the result returns

[NOT FOUND]

, first use

--summary

to confirm the module path format existing in the repository, then query again.

守则4: 结果直接呈现，不过度解读

Guideline 4: Present Results Directly, Do Not Over-Interpret

--impact

返回的

X upstream, Y downstream

是客观数字，直接告知用户。不要用「可能影响较大」这类模糊词替代数字——让数字说话。

The

X upstream, Y downstream

returned by

--impact

are objective numbers; inform the user directly. Do not use vague terms like "may have a large impact" to replace the numbers — let the numbers speak.

✅ 输出质量自检

✅ Output Quality Self-Check

查询前确认
```
ast_nodes.json
```
路径正确，文件非空
若
```
[NOT FOUND]
```
：已用
```
--summary
```
核实路径格式，重新查询
```
--impact
```
结果：已明确给出 upstream/downstream 的具体数字
```
--who-imports
```
结果：按源码文件 / 测试文件分类展示，更直观
若叠加
```
--git-stats
```
：已说明 git 风险等级的含义（high=90天内改动多）

Confirm the
```
ast_nodes.json
```
path is correct and the file is non-empty before querying
If
```
[NOT FOUND]
```
: Verified the path format with
```
--summary
```
and queried again
```
--impact
```
results: Clearly provided specific numbers for upstream/downstream
```
--who-imports
```
results: Displayed by source code files / test files for better intuitiveness
If
```
--git-stats
```
is used: Explained the meaning of git risk levels (high=many changes within 90 days)