Nexus-skills

Nexus-skills 项目图标

---

背景故事：当 AI 编程助手遭遇"代码失忆症"

每一位 AI 编程助手都面临一个根本性的困境：每次新的对话都是一次全新的起点。当你让 Claude Code 或 Cursor 分析一个陌生的代码仓库时，AI 必须在海量文件中大海捞针，从零构建对项目的理解。这种"冷启动"代价极高——浪费时间、消耗 token、且极易因为上下文窗口不足而遗漏关键架构信息。

更糟糕的是，当你对某个核心接口做了修改，AI 并不知道这个改动会波及哪些文件。它可能花了大量 token 分析了看似相关的模块，却完全忽略了真正受影响的耦合热点。这是 AI 辅助编程中最常见也最隐蔽的效率杀手。

Nexus-skills 正是在这个痛点上诞生的。它是一套专为 AI Agent 设计的代码库感知技能，通过 AST（抽象语法树）分析和 Git 历史挖掘，为每个仓库构建一份持久化的知识图谱，让 AI 每次会话都能"秒懂"项目结构，而不是每次都从零摸索。

---

什么是 Nexus-skills

Nexus-skills 是由开发者 Haaaiawd 创建的 AI 原生代码库智能技能集，当前已在 GitHub 获得 162 颗 stars、15 个 forks。它包含两个核心技能：

nexus-mapper：构建持久化知识图谱

nexus-mapper 执行一套名为 PROBE 的五阶段探测协议，对任意本地 Git 仓库进行系统性分析，最终产出分层知识库 .nexus-map/：

产出物	作用
INDEX.md	冷启动入口，完整架构上下文，控制在 2000 tokens 以内
arch/systems.md	每个子系统的职责与精确代码位置
arch/dependencies.md	组件间调用关系，Mermaid 依赖图可视化
arch/test_coverage.md	静态测试覆盖分析：哪些模块有测试、哪些没有
concepts/concept_model.json	机器可读知识图谱，供程序化查询
concepts/domains.md	代码库领域语言，人可读版本
hotspots/git_forensics.md	变更最频繁的文件及"总是同时变更"的文件对

这套设计的精妙之处在于：nexus-mapper 不会把第一眼印象直接写成结论。它会先产出证据，再挑战自己的初始判断，最后才输出正式资产。这解决了 AI 最常见的失败模式——把第一印象误写成结论。

nexus-query：精准结构查询

nexus-query 专注于开发过程中的实时查询，回答精确的结构问题而无需读完整个仓库。它支持以下查询模式：

# 文件骨架：类、方法、行号、import 清单
python query_graph.py ast_nodes.json --file src/core/vision.py

# 反向依赖：谁在引用这个模块？
python query_graph.py ast_nodes.json --who-imports src.core.vision

# 影响半径：上游依赖 + 下游被依赖者
python query_graph.py ast_nodes.json --impact src/core/vision.py --git-stats git_stats.json

# 架构核心节点：最高扇入/扇出的模块
python query_graph.py ast_nodes.json --hub-analysis

# 按顶层目录聚合的结构摘要
python query_graph.py ast_nodes.json --summary

最有价值的场景包括：改接口前用 --who-imports 找出会波及的文件；Sprint 估时前用 --impact --git-stats 量化风险；遗留代码库里用 --file 秒出文件骨架而无需读完 3000 行代码。

---

技术架构

核心依赖

nexus-skills 依赖三个 Python 包：

• tree-sitter（>=0.22.0）：高性能 AST 解析库，由 Tree-sitter 团队维护
• tree-sitter-language-pack：为 tree-sitter 提供多语言语法支持
• pathspec（>=0.12.1）：路径模式匹配，用于 .gitignore 规则应用

底层 AST 提取脚本 extract_ast.py（约 32KB）负责递归扫描仓库，对每种支持的语言使用 tree-sitter 提取函数、类、import 等结构化信息。

30+ 语言支持

项目通过 languages.json 配置文件（约 6KB）维护语言扩展名到 tree-sitter 语法的映射，自动支持 30+ 种语言：Python、JavaScript、JSX、TypeScript、TSX、Bash、Java、Go、Rust、C++、C、C#、Kotlin、Ruby、Swift、Scala、PHP、Vue、Svelte、Rust、Dart 等。

两个技能共享同一套脚本层（extract_ast.py、query_graph.py、git_detective.py、languages.json），nexus-query 可以直接复用 nexus-mapper 生成的 ast_nodes.json。

---

部署体验

安装方式

安装非常轻量，支持两种方式：

# 通过 Skills 协议安装（适配 Claude Code、Cursor、Cline 等）
npx skills add haaaiawd/nexus-skills

# 或直接 pip 安装脚本依赖
pip install tree-sitter tree-sitter-language-pack pathspec

硬件与前置要求

项目	要求
Python 版本	3.10+
内存	最低 512MB
磁盘	约 100MB（含依赖）
GPU	不需要
Docker	不支持

局限与不足

项目当前存在几个值得注意的问题：

许可缺失：仓库未声明开源许可证，这在 AI 工具生态中较为罕见，可能会影响企业用户的合规评估。

图标素材未上传到 main 分支：项目图标 Icon.png 存于 master 分支而非默认分支，链接维护存在隐患。

文档语言混杂：README 混合中英文写作，对于纯中文或纯英文团队可能造成一定阅读障碍。

---

行业意义

Nexus-skills 代表了一个正在兴起的 AI 编程工具子方向：为 AI Agent 提供持久化记忆能力。随着 Claude Code、Cursor、Cline 等 AI 编程工具的普及，如何让 AI 在多轮会话中积累对项目的理解，正在成为一个核心课题。

项目名称中的"skills"也暗示了它与 AI Agent Skills 生态的深度整合——它通过标准化的 SKILL.md 协议工作，天然适配所有遵循该协议的 AI 客户端。

对于大型遗留代码库或高度复杂的多模块项目，nexus-mapper 提供的结构化知识图谱能够显著降低 AI 的认知负担；对于需要频繁重构或修改接口的团队，nexus-query 的影响半径分析功能提供了数据驱动的决策依据。

Nexus-skills 的思路与 GitHub 的 semantic code、智能代码搜索等工具形成了有趣的互补——后者解决的是"怎么找"，它解决的是"怎么懂"。在 AI 编程助手从"辅助工具"向"协作者"演进的进程中，这类代码库感知基础设施的价值将会持续凸显。