nexus-query

Name: nexus-query
Author: Haaaiawd

162stars15forks

How to install nexus-query?

haaaiawd/nexus-skills/nexus-query

$npx -y skills add Haaaiawd/Nexus-skills --skill nexus-query

Installs into the current project.

Summary

Precise, instant code structure queries for active development — answer 'who depends on this interface before I refactor it', 'how many modules break if I change this', 'what is the real impact radius of this feature change', 'which module is the true high-coupling hotspot in thi

Files · 1

View on GitHub

SKILL.md

1	# nexus-query — 代码结构精准查询
2
3
4	## 何时调用
5
6	\| 场景 \| 调用 \|
7	\|------\|:----:\|
8	\| 「这个文件有哪些类/方法，依赖什么」 \| 是 \|
9	\| 「改这个接口/模块，哪些文件受影响」 \| 是 \|
10	\| 「这个改动的影响半径是多大」 \| 是 \|
11	\| 「项目里谁是真正的核心依赖节点」 \| 是 \|
12	\| 「整个项目大概分哪几块」 \| 是 \|
13	\| 用户希望生成完整的 `.nexus-map/` 知识库 \| 否 → 改用 nexus-mapper \|
14	\| 运行环境无 shell 执行能力 \| 否 \|
15	\| 宿主机无本地 Python 3.10+ \| 否 \|
16
17	---
18
19	## 前提：确保 ast_nodes.json 可用
20
21	```
22	进入查询前 → 检查是否有 ast_nodes.json
23	├── 有（.nexus-map/raw/ast_nodes.json 或用户指定路径）→ 直接查询
24	└── 没有 → 运行 extract_ast.py 生成 → 再查询
25	```
26
27	生成 AST 时，支持与 `nexus-mapper` 一致的扫描过滤：
28	- `--exclude-dirs django_static,.go_root` 按目录名或仓库相对路径忽略杂物目录
29	- `--use-gitignore` 启用 `<repo_path>/.gitignore` 规则（默认开启），忽略其中声明的文件和目录
30	- `--no-gitignore` 不应用 `.gitignore` 规则；此时仍会保留内置排除项和 `--exclude-dirs`
31
32	```bash
33	# 默认路径（和 nexus-mapper 的 .nexus-map/ 兼容，可互通）
34	AST_JSON="$repo_path/.nexus-map/raw/ast_nodes.json"
35	GIT_JSON="$repo_path/.nexus-map/raw/git_stats.json" # 可选
36
37	# 若 ast_nodes.json 不存在，先创建目录再生成（约数秒）
38	mkdir -p "$repo_path/.nexus-map/raw"
39	python $SKILL_DIR/scripts/extract_ast.py $repo_path > $AST_JSON
40
41	# 若仓库包含大批静态资源、生成物或杂物目录，可显式追加排除项
42	python $SKILL_DIR/scripts/extract_ast.py $repo_path \
43	--exclude-dirs django_static,.go_root,third_party/assets \
44	> $AST_JSON
45
46	# 若不希望读取 .gitignore，可显式关闭
47	python $SKILL_DIR/scripts/extract_ast.py $repo_path \
48	--no-gitignore \
49	> $AST_JSON
50
51	# 若需要 git 风险数据（可选，仅在存在 .git 时）
52	python $SKILL_DIR/scripts/git_detective.py $repo_path --days 90 > $GIT_JSON
53	```
54
55	> `$SKILL_DIR` 为本 Skill 的安装路径（`.agent/skills/nexus-query` 或独立 repo 路径）。
56	> `extract_ast.py` 默认排除 `.git/`、`.nexus-map/`、`node_modules/`、`__pycache__/`、`.venv/`、`dist/`、`build/` 等噪音目录及文件；默认还会读取 `<repo_path>/.gitignore`，忽略其中声明的文件和目录。`--no-gitignore` 仅关闭 `.gitignore` 规则，不会关闭内置排除项，也不会关闭 `--exclude-dirs`。
57
58	依赖安装（首次使用）：
59	```bash
60	pip install -r $SKILL_DIR/scripts/requirements.txt
61	```
62
63	---
64
65	## 五个查询模式
66
67	```bash
68	# 文件骨架：类、方法、行号、import 清单
69	python $SKILL_DIR/scripts/query_graph.py $AST_JSON --file <path>
70	python $SKILL_DIR/scripts/query_graph.py $AST_JSON --file <path> --git-stats $GIT_JSON
71
72	# 反向依赖：谁 import 了这个模块（区分源码文件和测试文件）
73	python $SKILL_DIR/scripts/query_graph.py $AST_JSON --who-imports <module_or_path>
74
75	# 影响半径：上游依赖 + 下游被依赖（X upstream, Y downstream）
76	python $SKILL_DIR/scripts/query_graph.py $AST_JSON --impact <path>
77	python $SKILL_DIR/scripts/query_graph.py $AST_JSON --impact <path> --git-stats $GIT_JSON
78
79	# 全仓库核心节点：按扇入（被引用最多）和扇出（引用最多）排序
80	python $SKILL_DIR/scripts/query_graph.py $AST_JSON --hub-analysis [--top N]
81
82	# 按顶层目录聚合结构摘要
83	python $SKILL_DIR/scripts/query_graph.py $AST_JSON --summary
84	```
85
86	### 各模式核心价值
87
88	\| 模式 \| 一句话价值 \| 典型触发时机 \|
89	\|------\|-----------\|------------\|
90	\| `--file` \| 不读源码也能掌握文件骨架，精确到行号 \| 接手大型模块前；Bug 调查缩小读取区间 \|
91	\| `--who-imports` \| 改接口前的"炸弹清单"——列出所有调用方 \| 删函数/改签名/重命名类之前，必须跑 \|
92	\| `--impact` \| `0 upstream, 24 downstream` 一眼看清改动范围 \| Sprint 估时；评估修改是局部手术还是全局手术 \|
93	\| `--hub-analysis` \| 找出真正的高耦合核心，不靠目录名猜 \| 架构评审；技术债优先级排序 \|
94	\| `--summary` \| 5 秒建立全局分层认知，比 README 更客观 \| 初次接触项目；识别循环依赖风险区域 \|
95
96	---
97
98	## 场景速查
99
100	\| 你此刻的问题 \| 用哪个 \|
101	\|-------------\|--------\|
102	\| 这个文件有哪些类/方法，各在哪几行 \| `--file` \|
103	\| 改这个接口/删函数，哪些文件跟着改 \| `--who-imports` \|
104	\| 这个改动最终影响多少模块 \| `--impact` \|
105	\| 这个改动风险有多高（加 git 热度） \| `--impact --git-stats` \|
106	\| 项目里谁是真正的高耦合中心 \| `--hub-analysis` \|
107	\| 整个项目的模块分布和层级 \| `--summary` \|
108	\| 连续重构，改完一处要看影响链 \| `--who-imports` → `--impact` \|
109	\| 估算技术债改造的工作量 \| `--hub-analysis` → `--impact` \|
110
111	---
112
113	## 执行守则
114
115	守则1: 先骨架再查询
116	使用 `--impact` 或 `--who-imports` 分析某个模块前，建议先用 `--file` 读取其骨架，理解职责和现有 import，避免对查询结果产生误判。
117
118	守则2: git-stats 是加分项，不是硬阻塞
119	没有 `.git` 或 git 历史不足时，跳过 `git_detective.py`，只用 AST 数据查询。
120
121	守则3: 路径匹配灵活但要验证
122	支持路径片段匹配（如 `vision.py` 可匹配 `src/core/vision.py`）。结果返回 `[NOT FOUND]` 时，先用 `--summary` 确认仓库中存在的模块路径格式，再重新查询。
123
124	守则4: 结果直接呈现，让数字说话
125	`--impact` 返回的 `X upstream, Y downstream` 是客观数字，直接告知用户，不用「可能影响较大」这类模糊词替代。

People who liked this also viewed

6 picks

Type

nexus-query

162stars15forks

View on GitHub

How to install nexus-query?

haaaiawd/nexus-skills/nexus-query

$npx -y skills add Haaaiawd/Nexus-skills --skill nexus-query

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# nexus-query — 代码结构精准查询
2
3
4	## 何时调用
5
6	\| 场景 \| 调用 \|
7	\|------\|:----:\|
8	\| 「这个文件有哪些类/方法，依赖什么」 \| 是 \|
9	\| 「改这个接口/模块，哪些文件受影响」 \| 是 \|
10	\| 「这个改动的影响半径是多大」 \| 是 \|
11	\| 「项目里谁是真正的核心依赖节点」 \| 是 \|
12	\| 「整个项目大概分哪几块」 \| 是 \|
13	\| 用户希望生成完整的 `.nexus-map/` 知识库 \| 否 → 改用 nexus-mapper \|
14	\| 运行环境无 shell 执行能力 \| 否 \|
15	\| 宿主机无本地 Python 3.10+ \| 否 \|
16
17	---
18
19	## 前提：确保 ast_nodes.json 可用
20
21	```
22	进入查询前 → 检查是否有 ast_nodes.json
23	├── 有（.nexus-map/raw/ast_nodes.json 或用户指定路径）→ 直接查询
24	└── 没有 → 运行 extract_ast.py 生成 → 再查询
25	```
26
27	生成 AST 时，支持与 `nexus-mapper` 一致的扫描过滤：
28	- `--exclude-dirs django_static,.go_root` 按目录名或仓库相对路径忽略杂物目录
29	- `--use-gitignore` 启用 `<repo_path>/.gitignore` 规则（默认开启），忽略其中声明的文件和目录
30	- `--no-gitignore` 不应用 `.gitignore` 规则；此时仍会保留内置排除项和 `--exclude-dirs`
31
32	```bash
33	# 默认路径（和 nexus-mapper 的 .nexus-map/ 兼容，可互通）
34	AST_JSON="$repo_path/.nexus-map/raw/ast_nodes.json"
35	GIT_JSON="$repo_path/.nexus-map/raw/git_stats.json" # 可选
36
37	# 若 ast_nodes.json 不存在，先创建目录再生成（约数秒）
38	mkdir -p "$repo_path/.nexus-map/raw"
39	python $SKILL_DIR/scripts/extract_ast.py $repo_path > $AST_JSON
40
41	# 若仓库包含大批静态资源、生成物或杂物目录，可显式追加排除项
42	python $SKILL_DIR/scripts/extract_ast.py $repo_path \
43	--exclude-dirs django_static,.go_root,third_party/assets \
44	> $AST_JSON
45
46	# 若不希望读取 .gitignore，可显式关闭
47	python $SKILL_DIR/scripts/extract_ast.py $repo_path \
48	--no-gitignore \
49	> $AST_JSON
50
51	# 若需要 git 风险数据（可选，仅在存在 .git 时）
52	python $SKILL_DIR/scripts/git_detective.py $repo_path --days 90 > $GIT_JSON
53	```
54
55	> `$SKILL_DIR` 为本 Skill 的安装路径（`.agent/skills/nexus-query` 或独立 repo 路径）。
56	> `extract_ast.py` 默认排除 `.git/`、`.nexus-map/`、`node_modules/`、`__pycache__/`、`.venv/`、`dist/`、`build/` 等噪音目录及文件；默认还会读取 `<repo_path>/.gitignore`，忽略其中声明的文件和目录。`--no-gitignore` 仅关闭 `.gitignore` 规则，不会关闭内置排除项，也不会关闭 `--exclude-dirs`。
57
58	依赖安装（首次使用）：
59	```bash
60	pip install -r $SKILL_DIR/scripts/requirements.txt
61	```
62
63	---
64
65	## 五个查询模式
66
67	```bash
68	# 文件骨架：类、方法、行号、import 清单
69	python $SKILL_DIR/scripts/query_graph.py $AST_JSON --file <path>
70	python $SKILL_DIR/scripts/query_graph.py $AST_JSON --file <path> --git-stats $GIT_JSON
71
72	# 反向依赖：谁 import 了这个模块（区分源码文件和测试文件）
73	python $SKILL_DIR/scripts/query_graph.py $AST_JSON --who-imports <module_or_path>
74
75	# 影响半径：上游依赖 + 下游被依赖（X upstream, Y downstream）
76	python $SKILL_DIR/scripts/query_graph.py $AST_JSON --impact <path>
77	python $SKILL_DIR/scripts/query_graph.py $AST_JSON --impact <path> --git-stats $GIT_JSON
78
79	# 全仓库核心节点：按扇入（被引用最多）和扇出（引用最多）排序
80	python $SKILL_DIR/scripts/query_graph.py $AST_JSON --hub-analysis [--top N]
81
82	# 按顶层目录聚合结构摘要
83	python $SKILL_DIR/scripts/query_graph.py $AST_JSON --summary
84	```
85
86	### 各模式核心价值
87
88	\| 模式 \| 一句话价值 \| 典型触发时机 \|
89	\|------\|-----------\|------------\|
90	\| `--file` \| 不读源码也能掌握文件骨架，精确到行号 \| 接手大型模块前；Bug 调查缩小读取区间 \|
91	\| `--who-imports` \| 改接口前的"炸弹清单"——列出所有调用方 \| 删函数/改签名/重命名类之前，必须跑 \|
92	\| `--impact` \| `0 upstream, 24 downstream` 一眼看清改动范围 \| Sprint 估时；评估修改是局部手术还是全局手术 \|
93	\| `--hub-analysis` \| 找出真正的高耦合核心，不靠目录名猜 \| 架构评审；技术债优先级排序 \|
94	\| `--summary` \| 5 秒建立全局分层认知，比 README 更客观 \| 初次接触项目；识别循环依赖风险区域 \|
95
96	---
97
98	## 场景速查
99
100	\| 你此刻的问题 \| 用哪个 \|
101	\|-------------\|--------\|
102	\| 这个文件有哪些类/方法，各在哪几行 \| `--file` \|
103	\| 改这个接口/删函数，哪些文件跟着改 \| `--who-imports` \|
104	\| 这个改动最终影响多少模块 \| `--impact` \|
105	\| 这个改动风险有多高（加 git 热度） \| `--impact --git-stats` \|
106	\| 项目里谁是真正的高耦合中心 \| `--hub-analysis` \|
107	\| 整个项目的模块分布和层级 \| `--summary` \|
108	\| 连续重构，改完一处要看影响链 \| `--who-imports` → `--impact` \|
109	\| 估算技术债改造的工作量 \| `--hub-analysis` → `--impact` \|
110
111	---
112
113	## 执行守则
114
115	守则1: 先骨架再查询
116	使用 `--impact` 或 `--who-imports` 分析某个模块前，建议先用 `--file` 读取其骨架，理解职责和现有 import，避免对查询结果产生误判。
117
118	守则2: git-stats 是加分项，不是硬阻塞
119	没有 `.git` 或 git 历史不足时，跳过 `git_detective.py`，只用 AST 数据查询。
120
121	守则3: 路径匹配灵活但要验证
122	支持路径片段匹配（如 `vision.py` 可匹配 `src/core/vision.py`）。结果返回 `[NOT FOUND]` 时，先用 `--summary` 确认仓库中存在的模块路径格式，再重新查询。
123
124	守则4: 结果直接呈现，让数字说话
125	`--impact` 返回的 `X upstream, Y downstream` 是客观数字，直接告知用户，不用「可能影响较大」这类模糊词替代。

People who liked this also viewed

6 picks

Type