{"id":"cc154c99-153e-45ae-a3bc-c7b9040535ae","shortId":"8Qu2nz","kind":"skill","title":"nexus-query","tagline":"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","description":"# nexus-query — 代码结构精准查询\n\n\n## 何时调用\n\n| 场景 | 调用 |\n|------|:----:|\n| 「这个文件有哪些类/方法，依赖什么」 | 是 |\n| 「改这个接口/模块，哪些文件受影响」 | 是 |\n| 「这个改动的影响半径是多大」 | 是 |\n| 「项目里谁是真正的核心依赖节点」 | 是 |\n| 「整个项目大概分哪几块」 | 是 |\n| 用户希望生成完整的 `.nexus-map/` 知识库 | 否 → 改用 nexus-mapper |\n| 运行环境无 shell 执行能力 | 否 |\n| 宿主机无本地 Python 3.10+ | 否 |\n\n---\n\n## 前提：确保 ast_nodes.json 可用\n\n```\n进入查询前 → 检查是否有 ast_nodes.json\n├── 有（.nexus-map/raw/ast_nodes.json 或用户指定路径）→ 直接查询\n└── 没有 → 运行 extract_ast.py 生成 → 再查询\n```\n\n生成 AST 时，支持与 `nexus-mapper` 一致的扫描过滤：\n- `--exclude-dirs django_static,.go_root` 按目录名或仓库相对路径忽略杂物目录\n- `--use-gitignore` 启用 `<repo_path>/.gitignore` 规则（默认开启），忽略其中声明的文件和目录\n- `--no-gitignore` 不应用 `.gitignore` 规则；此时仍会保留内置排除项和 `--exclude-dirs`\n\n```bash\n# 默认路径（和 nexus-mapper 的 .nexus-map/ 兼容，可互通）\nAST_JSON=\"$repo_path/.nexus-map/raw/ast_nodes.json\"\nGIT_JSON=\"$repo_path/.nexus-map/raw/git_stats.json\"    # 可选\n\n# 若 ast_nodes.json 不存在，先创建目录再生成（约数秒）\nmkdir -p \"$repo_path/.nexus-map/raw\"\npython $SKILL_DIR/scripts/extract_ast.py $repo_path > $AST_JSON\n\n# 若仓库包含大批静态资源、生成物或杂物目录，可显式追加排除项\npython $SKILL_DIR/scripts/extract_ast.py $repo_path \\\n  --exclude-dirs django_static,.go_root,third_party/assets \\\n  > $AST_JSON\n\n# 若不希望读取 .gitignore，可显式关闭\npython $SKILL_DIR/scripts/extract_ast.py $repo_path \\\n  --no-gitignore \\\n  > $AST_JSON\n\n# 若需要 git 风险数据（可选，仅在存在 .git 时）\npython $SKILL_DIR/scripts/git_detective.py $repo_path --days 90 > $GIT_JSON\n```\n\n> `$SKILL_DIR` 为本 Skill 的安装路径（`.agent/skills/nexus-query` 或独立 repo 路径）。\n > `extract_ast.py` 默认排除 `.git/`、`.nexus-map/`、`node_modules/`、`__pycache__/`、`.venv/`、`dist/`、`build/` 等噪音目录及文件；默认还会读取 `<repo_path>/.gitignore`，忽略其中声明的文件和目录。`--no-gitignore` 仅关闭 `.gitignore` 规则，不会关闭内置排除项，也不会关闭 `--exclude-dirs`。\n\n**依赖安装（首次使用）**：\n```bash\npip install -r $SKILL_DIR/scripts/requirements.txt\n```\n\n---\n\n## 五个查询模式\n\n```bash\n# 文件骨架：类、方法、行号、import 清单\npython $SKILL_DIR/scripts/query_graph.py $AST_JSON --file <path>\npython $SKILL_DIR/scripts/query_graph.py $AST_JSON --file <path> --git-stats $GIT_JSON\n\n# 反向依赖：谁 import 了这个模块（区分源码文件和测试文件）\npython $SKILL_DIR/scripts/query_graph.py $AST_JSON --who-imports <module_or_path>\n\n# 影响半径：上游依赖 + 下游被依赖（X upstream, Y downstream）\npython $SKILL_DIR/scripts/query_graph.py $AST_JSON --impact <path>\npython $SKILL_DIR/scripts/query_graph.py $AST_JSON --impact <path> --git-stats $GIT_JSON\n\n# 全仓库核心节点：按扇入（被引用最多）和扇出（引用最多）排序\npython $SKILL_DIR/scripts/query_graph.py $AST_JSON --hub-analysis [--top N]\n\n# 按顶层目录聚合结构摘要\npython $SKILL_DIR/scripts/query_graph.py $AST_JSON --summary\n```\n\n### 各模式核心价值\n\n| 模式 | 一句话价值 | 典型触发时机 |\n|------|-----------|------------|\n| `--file` | 不读源码也能掌握文件骨架，精确到行号 | 接手大型模块前；Bug 调查缩小读取区间 |\n| `--who-imports` | 改接口前的\"炸弹清单\"——列出所有调用方 | 删函数/改签名/重命名类之前，必须跑 |\n| `--impact` | `0 upstream, 24 downstream` 一眼看清改动范围 | Sprint 估时；评估修改是局部手术还是全局手术 |\n| `--hub-analysis` | 找出真正的高耦合核心，不靠目录名猜 | 架构评审；技术债优先级排序 |\n| `--summary` | 5 秒建立全局分层认知，比 README 更客观 | 初次接触项目；识别循环依赖风险区域 |\n\n---\n\n## 场景速查\n\n| 你此刻的问题 | 用哪个 |\n|-------------|--------|\n| 这个文件有哪些类/方法，各在哪几行 | `--file` |\n| 改这个接口/删函数，哪些文件跟着改 | `--who-imports` |\n| 这个改动最终影响多少模块 | `--impact` |\n| 这个改动风险有多高（加 git 热度） | `--impact --git-stats` |\n| 项目里谁是真正的高耦合中心 | `--hub-analysis` |\n| 整个项目的模块分布和层级 | `--summary` |\n| 连续重构，改完一处要看影响链 | `--who-imports` → `--impact` |\n| 估算技术债改造的工作量 | `--hub-analysis` → `--impact` |\n\n---\n\n## 执行守则\n\n**守则1: 先骨架再查询**\n使用 `--impact` 或 `--who-imports` 分析某个模块前，建议先用 `--file` 读取其骨架，理解职责和现有 import，避免对查询结果产生误判。\n\n**守则2: git-stats 是加分项，不是硬阻塞**\n没有 `.git` 或 git 历史不足时，跳过 `git_detective.py`，只用 AST 数据查询。\n\n**守则3: 路径匹配灵活但要验证**\n支持路径片段匹配（如 `vision.py` 可匹配 `src/core/vision.py`）。结果返回 `[NOT FOUND]` 时，先用 `--summary` 确认仓库中存在的模块路径格式，再重新查询。\n\n**守则4: 结果直接呈现，让数字说话**\n`--impact` 返回的 `X upstream, Y downstream` 是客观数字，直接告知用户，不用「可能影响较大」这类模糊词替代。","tags":["nexus","query","skills","haaaiawd","agent-skills","agentic-ai","ai-coding","ai-tools","ast","claude-code","claude-skills","cline"],"capabilities":["skill","source-haaaiawd","skill-nexus-query","topic-agent-skills","topic-agentic-ai","topic-ai-coding","topic-ai-tools","topic-ast","topic-claude-code","topic-claude-skills","topic-cline","topic-code-analysis","topic-codebase-intelligence","topic-cursor","topic-dependency-graph"],"categories":["Nexus-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/Haaaiawd/Nexus-skills/nexus-query","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add Haaaiawd/Nexus-skills","source_repo":"https://github.com/Haaaiawd/Nexus-skills","install_from":"skills.sh"}},"qualityScore":"0.530","qualityRationale":"deterministic score 0.53 from registry signals: · indexed on github topic:agent-skills · 161 github stars · SKILL.md body (3,676 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-02T12:54:42.086Z","embedding":null,"createdAt":"2026-04-18T22:09:00.383Z","updatedAt":"2026-05-02T12:54:42.086Z","lastSeenAt":"2026-05-02T12:54:42.086Z","tsv":"'/.gitignore':129,251 '/raw/ast_nodes.json':101 '0':378 '24':380 '3.10':88 '5':394 '90':225 'activ':10 'agent/skills/nexus-query':233 'analysi':347,388,427,439 'answer':12 'ast':110,155,178,197,210,283,289,305,320,326,343,354,471 'ast_nodes.json':92,96,165 'bash':143,266,273 'break':25 'bug':365 'build':248 'chang':28,39 'code':6 'coupl':47 'day':224 'depend':14 'develop':11 'dir':119,142,190,229,263 'dir/scripts/extract_ast.py':175,185,204 'dir/scripts/git_detective.py':221 'dir/scripts/query_graph.py':282,288,304,319,325,342,353 'dir/scripts/requirements.txt':271 'dist':247 'django':120,191 'downstream':316,381,496 'exclud':118,141,189,262 'exclude-dir':117,140,188,261 'extract_ast.py':106,237 'featur':38 'file':285,291,361,407,452 'found':482 'git':159,213,217,226,239,293,295,330,332,418,422,459,464,466 'git-stat':292,329,421,458 'git_detective.py':469 'gitignor':127,135,137,200,209,255,257 'go':122,193 'high':46 'high-coupl':45 'hotspot':48 'hub':346,387,426,438 'hub-analysi':345,386,425,437 'impact':34,322,328,377,415,420,435,440,445,491 'import':278,299,309,369,413,434,449,455 'instal':268 'instant':5 'interfac':17 'json':156,160,179,198,211,227,284,290,296,306,321,327,333,344,355 'mani':23 'map':75,100,152,242 'mapper':81,115,148 'mkdir':169 'modul':24,41,244 'n':349 'nexus':2,52,74,80,99,114,147,151,241 'nexus-map':73,98,150,240 'nexus-mapp':79,113,146 'nexus-queri':1,51 'no-gitignor':133,207,253 'node':243 'p':170 'party/assets':196 'path':177,187,206,223 'path/.nexus-map/raw':172 'path/.nexus-map/raw/ast_nodes.json':158 'path/.nexus-map/raw/git_stats.json':162 'pip':267 'precis':4 'pycach':245 'python':87,173,183,202,219,280,286,302,317,323,340,351 'queri':3,8,53 'r':269 'radius':35 'readm':397 'real':33 'refactor':20 'repo':157,161,171,176,186,205,222,235 'root':123,194 'shell':83 'skill':174,184,203,220,228,231,270,281,287,303,318,324,341,352 'skill-nexus-query' 'source-haaaiawd' 'sprint':383 'src/core/vision.py':479 'stat':294,331,423,460 'static':121,192 'structur':7 'summari':356,393,429,485 'thi':50 'third':195 'top':348 'topic-agent-skills' 'topic-agentic-ai' 'topic-ai-coding' 'topic-ai-tools' 'topic-ast' 'topic-claude-code' 'topic-claude-skills' 'topic-cline' 'topic-code-analysis' 'topic-codebase-intelligence' 'topic-cursor' 'topic-dependency-graph' 'true':44 'upstream':314,379,494 'use':126 'use-gitignor':125 'venv':246 'vision.py':477 'who-import':307,367,411,432,447 'x':313,493 'y':315,495 '一句话价值':359 '一眼看清改动范围':382 '一致的扫描过滤':116 '上游依赖':311 '下游被依赖':312 '不会关闭内置排除项':259 '不存在':166 '不应用':136 '不是硬阻塞':462 '不用':499 '不读源码也能掌握文件骨架':362 '不靠目录名猜':390 '为本':230 '也不会关闭':260 '了这个模块':300 '五个查询模式':272 '仅关闭':256 '仅在存在':216 '代码结构精准查询':54 '估时':384 '估算技术债改造的工作量':436 '何时调用':55 '你此刻的问题':402 '使用':444 '依赖什么':60 '依赖安装':264 '先创建目录再生成':167 '先用':484 '先骨架再查询':443 '全仓库核心节点':334 '典型触发时机':360 '兼容':153 '再查询':108 '再重新查询':487 '分析某个模块前':450 '列出所有调用方':372 '初次接触项目':399 '删函数':373,409 '前提':90 '加':417 '区分源码文件和测试文件':301 '历史不足时':467 '反向依赖':297 '只用':470 '可互通':154 '可匹配':478 '可显式关闭':201 '可显式追加排除项':182 '可用':93 '可能影响较大':500 '可选':163,215 '各在哪几行':406 '各模式核心价值':357 '否':77,85,89 '启用':128 '和':145 '和扇出':337 '哪些文件受影响':64 '哪些文件跟着改':410 '场景':56 '场景速查':401 '如':476 '守则1':442 '守则2':457 '守则3':473 '守则4':488 '宿主机无本地':86 '建议先用':451 '引用最多':338 '影响半径':310 '必须跑':376 '忽略其中声明的文件和目录':132,252 '或':446,465 '或独立':234 '或用户指定路径':102 '执行守则':441 '执行能力':84 '找出真正的高耦合核心':389 '技术债优先级排序':392 '按扇入':335 '按目录名或仓库相对路径忽略杂物目录':124 '按顶层目录聚合结构摘要':350 '排序':339 '接手大型模块前':364 '支持与':112 '支持路径片段匹配':475 '改完一处要看影响链':431 '改接口前的':370 '改用':78 '改签名':374 '改这个接口':62,408 '数据查询':472 '整个项目大概分哪几块':70 '整个项目的模块分布和层级':428 '文件骨架':274 '方法':59,276,405 '时':111,218,483 '是':61,65,67,69,71 '是加分项':461 '是客观数字':497 '更客观':398 '有':97 '架构评审':391 '检查是否有':95 '模块':63 '模式':358 '此时仍会保留内置排除项和':139 '比':396 '没有':104,463 '清单':279 '炸弹清单':371 '热度':419 '理解职责和现有':454 '生成':107,109 '生成物或杂物目录':181 '用哪个':403 '用户希望生成完整的':72 '的':149 '的安装路径':232 '直接告知用户':498 '直接查询':103 '知识库':76 '确保':91 '确认仓库中存在的模块路径格式':486 '秒建立全局分层认知':395 '等噪音目录及文件':249 '类':275 '精确到行号':363 '约数秒':168 '结果直接呈现':489 '结果返回':480 '若':164 '若不希望读取':199 '若仓库包含大批静态资源':180 '若需要':212 '行号':277 '被引用最多':336 '规则':130,138,258 '让数字说话':490 '评估修改是局部手术还是全局手术':385 '识别循环依赖风险区域':400 '读取其骨架':453 '谁':298 '调查缩小读取区间':366 '调用':57 '路径':236 '路径匹配灵活但要验证':474 '跳过':468 '运行':105 '运行环境无':82 '返回的':492 '这个改动最终影响多少模块':414 '这个改动的影响半径是多大':66 '这个改动风险有多高':416 '这个文件有哪些类':58,404 '这类模糊词替代':501 '进入查询前':94 '连续重构':430 '避免对查询结果产生误判':456 '重命名类之前':375 '项目里谁是真正的核心依赖节点':68 '项目里谁是真正的高耦合中心':424 '风险数据':214 '首次使用':265 '默认开启':131 '默认排除':238 '默认路径':144 '默认还会读取':250","prices":[{"id":"b97cac19-bfe1-4c7e-9564-4d65aa1a261d","listingId":"cc154c99-153e-45ae-a3bc-c7b9040535ae","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"Haaaiawd","category":"Nexus-skills","install_from":"skills.sh"},"createdAt":"2026-04-18T22:09:00.383Z"}],"sources":[{"listingId":"cc154c99-153e-45ae-a3bc-c7b9040535ae","source":"github","sourceId":"Haaaiawd/Nexus-skills/nexus-query","sourceUrl":"https://github.com/Haaaiawd/Nexus-skills/tree/master/skills/nexus-query","isPrimary":false,"firstSeenAt":"2026-04-18T22:09:00.383Z","lastSeenAt":"2026-05-02T12:54:42.086Z"}],"details":{"listingId":"cc154c99-153e-45ae-a3bc-c7b9040535ae","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"Haaaiawd","slug":"nexus-query","github":{"repo":"Haaaiawd/Nexus-skills","stars":161,"topics":["agent-skills","agentic-ai","ai-coding","ai-tools","ast","claude-code","claude-skills","cline","code-analysis","codebase-intelligence","cursor","dependency-graph","github-copilot","legacy-code","refactoring","skills","spec","tree-sitter","vibe-coding"],"license":null,"html_url":"https://github.com/Haaaiawd/Nexus-skills","pushed_at":"2026-03-31T13:40:48Z","description":"AI-native codebase intelligence skills — generate persistent .nexus-map/ knowledge bases and instantly query file structure, dependency graphs, and change impact. Built for Copilot, Cursor, and any tool-calling LLM. 面向 AI 编程助手的代码库感知技能——生成持久化知识图谱，精准查询文件结构、依赖关系与改动影响半径。","skill_md_sha":"659b61a540d989082b626078a24f82f8566b8476","skill_md_path":"skills/nexus-query/SKILL.md","default_branch":"master","skill_tree_url":"https://github.com/Haaaiawd/Nexus-skills/tree/master/skills/nexus-query"},"layout":"multi","source":"github","category":"Nexus-skills","frontmatter":{"name":"nexus-query","description":"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 this legacy codebase'. Essential before any interface change, continuous refactoring task, sprint work estimation, or when navigating unfamiliar or large legacy codebases. Requires Python 3.10+ and shell. Use nexus-mapper instead when building a full .nexus-map/ knowledge base."},"skills_sh_url":"https://skills.sh/Haaaiawd/Nexus-skills/nexus-query"},"updatedAt":"2026-05-02T12:54:42.086Z"}}