nexus-mapper

Name: nexus-mapper
Author: Haaaiawd

162stars15forks

How to install nexus-mapper?

haaaiawd/nexus-skills/nexus-mapper

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

Installs into the current project.

Summary

Generate a persistent .nexus-map/ knowledge base that lets any AI session instantly understand a codebase's architecture, systems, dependencies, and change hotspots. Use when starting work on an unfamiliar repository, onboarding with AI-assisted context, preparing for a major ref

Files · 1

View on GitHub

SKILL.md

1	# nexus-mapper — AI 项目探测协议
2
3	本 Skill 指导 AI Agent 使用 PROBE 五阶段协议，对任意本地 Git 仓库执行系统性探测，产出 `.nexus-map/` 分层知识库。
4
5	---
6
7	## 何时调用 / 何时不调用
8
9	\| 场景 \| 调用 \|
10	\| ------------------------------------------------------------------- \| :---: \|
11	\| 用户提供本地 repo 路径，希望 AI 理解其架构 \| 是 \|
12	\| 需要生成 `.nexus-map/INDEX.md` 供后续 AI 会话冷启动 \| 是 \|
13	\| 用户说「帮我分析项目」「建立项目知识库」「让 AI 了解这个仓库」 \| 是 \|
14	\| 运行环境无 shell 执行能力（纯 API 调用模式，无 `run_command` 工具） \| 否 \|
15	\| 宿主机无本地 Python 3.10+ \| 否 \|
16	\| 目标仓库无任何已知语言源文件（`.py/.ts/.java/.go/.rs/.cpp` 等均无） \| 否 \|
17	\| 用户只想查询某个特定文件/函数 → 直接用 `view_file` / `grep_search` \| 否 \|
18
19	---
20
21	## 前提检查
22
23	缺失项要显式告知用户；需要降级等时及时提醒用户，经过同意才能继续。
24
25	\| 前提 \| 检查方式 \|
26	\| ----------------- \| --------------------------------------- \|
27	\| 目标路径存在 \| `$repo_path` 可访问 \|
28	\| Python 3.10+ \| `python --version` >= 3.10 \|
29	\| 脚本依赖已安装 \| `python -c "import tree_sitter"` 无报错 \|
30	\| 有 shell 执行能力 \| Agent 环境支持 `run_command` 工具调用 \|
31
32	`git` 历史是加分项，不是硬阻塞项。没有 `.git` 或历史过少时，跳过热点分析，并在输出中明确记录这是一次降级探测。
33
34	---
35
36	## 输入契约
37
38	```
39	repo_path: 目标仓库的本地绝对路径（必填）
40	```
41
42	语言支持：自动按文件扩展名 dispatch，语言配置（扩展名映射 + Tree-sitter 查询）存储在 `scripts/languages.json`。当前已接入 Python/JavaScript/TypeScript/TSX/Bash/Java/Go/Rust/C#/C/C++/Kotlin/Ruby/Swift/Scala/PHP/Lua/Elixir/GDScript/Dart/Haskell/Clojure/SQL/Proto/Solidity/Vue/Svelte/R/Perl 等 30+ 语言。
43
44	非标准语言：若仓库含有内置未支持的语言，通过命令行参数动态补充（详见 `references/05-language-customization.md`）：
45	- `--add-extension .templ=templ` 添加新文件扩展名映射
46	- `--add-query templ struct "(component_declaration ...)"` 添加结构查询
47	- `--language-config <JSON_FILE>` 复杂配置时使用 JSON 文件
48
49	扫描过滤：AST 提取与 `raw/file_tree.txt` 生成共享同一套过滤规则：
50	- `--exclude-dirs django_static,.go_root` 按目录名或仓库相对路径忽略杂物目录
51	- `--use-gitignore` 启用 `<repo_path>/.gitignore` 规则（默认开启），忽略其中声明的文件和目录
52	- `--no-gitignore` 不应用 `.gitignore` 规则；此时仍会保留内置排除项和 `--exclude-dirs`
53
54	---
55
56	## 输出格式
57
58	执行完成后，目标仓库根目录下将产出：
59
60	```text
61	.nexus-map/
62	├── INDEX.md ← AI 冷启动主入口（< 2000 tokens）
63	├── arch/
64	│ ├── systems.md ← 系统边界 + 代码位置
65	│ ├── dependencies.md ← Mermaid 依赖图 + 时序图
66	│ └── test_coverage.md ← 静态测试面：测试文件、覆盖到的核心模块、证据缺口
67	├── concepts/
68	│ ├── concept_model.json ← Schema V1 机器可读图谱
69	│ └── domains.md ← 核心领域概念说明
70	├── hotspots/
71	│ └── git_forensics.md ← Git 热点 + 耦合对分析
72	└── raw/
73	├── ast_nodes.json ← Tree-sitter 解析原始数据
74	├── git_stats.json ← Git 热点与耦合数据
75	└── file_tree.txt ← 过滤后的文件树
76	```
77
78	所有生成的 Markdown 文件必须带一个简短头部，至少包含：`generated_by`、`verified_at`、`provenance`。
79
80	`concept_model.json` 的人类可读名称字段统一使用 `label`，不要添加 `title`。
81
82	如果 PROFILE 阶段发现语言覆盖降级或人工推断，`provenance` 必须明确标注。
83
84	---
85
86	## PROBE 阶段门控
87
88	> [!IMPORTANT]
89	> 进入每个阶段前必须先读对应 reference，不得跳过。
90	> 各阶段详细步骤、完成检查清单与边界场景处理均在 reference 中定义。
91
92	```
93	[Skill 激活时] → read references/probe-protocol.md （阶段步骤蓝图，含边界场景与三维度质疑框架）
94	[EMIT 前] → read references/output-schema.md （Schema 校验规范）
95	[非标准语言时] → read references/language-customization.md（按需，非门控）
96	```
97
98	---
99
100	## 执行守则
101
102	### 守则1: OBJECT 拒绝形式主义
103
104	OBJECT 的存在意义是打破 REASON 的幸存者偏差。大量工程事实隐藏在目录命名和 git 热点背后，第一直觉几乎总是错的。
105
106	不合格质疑（禁止提交）：
107	```
108	Q1: 我对系统结构的把握还不够扎实
109	Q2: xxx 目录的职责暂时没有直接证据
110	```
111	问题不在措辞，而在于没有证据线索，也无法在 BENCHMARK 阶段验证。
112
113	合格质疑格式：
114	```
115	Q1: git_stats 显示 tasks/analysis_tasks.py 变更 21 次（high risk），
116	但 HYPOTHESIS 认为编排入口是 evolution/detective_loop.py。
117	矛盾：若 detective_loop 是入口，为何 analysis_tasks 热度更高？
118	证据线索: git_stats.json hotspots[0].path
119	验证计划: view tasks/analysis_tasks.py 的 class 定义 + import 树
120	```
121
122	---
123
124	### 守则2: implemented 节点必须有真实 code_path
125
126	> [!IMPORTANT]
127	> 写入 `concept_model.json` 前，必须先区分节点是 `implemented`、`planned` 还是 `inferred`。
128	> 只有 `implemented` 节点允许写入 `code_path`，且必须亲手验证存在。
129
130	```bash
131	# BENCHMARK 阶段验证方式
132	ls $repo_path/src/nexus/application/weaving/ # 目录存在 → 节点有效
133	ls $repo_path/src/nexus/application/nonexist/ # [!ERROR] → 修正或删除此节点
134	```
135
136	对于 `planned` 或 `inferred` 节点，使用：
137
138	```json
139	{
140	"implementation_status": "planned",
141	"code_path": null,
142	"evidence_path": "docs/architecture.md",
143	"evidence_gap": "仓库中未发现 src/agents/monarch/，仅在设计文档中出现"
144	}
145	```
146
147	禁止：用勉强相关的文件冒充 `code_path`、把状态塞进路径字段（如 `code_path: "PLANNED"`）。
148
149	---
150
151	### 守则3: EMIT 原子性
152
153	先全部写入 `.nexus-map/.tmp/`，全部成功后整体移动到正式目录，删除 `.tmp/`。
154	目的：中途失败不留半成品。下次执行检测到 `.tmp/` 存在 → 清理后重新生成。
155
156	幂等性规则：
157
158	\| 状态

People who liked this also viewed

6 picks

Type

nexus-mapper

162stars15forks

View on GitHub

How to install nexus-mapper?

haaaiawd/nexus-skills/nexus-mapper

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

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# nexus-mapper — AI 项目探测协议
2
3	本 Skill 指导 AI Agent 使用 PROBE 五阶段协议，对任意本地 Git 仓库执行系统性探测，产出 `.nexus-map/` 分层知识库。
4
5	---
6
7	## 何时调用 / 何时不调用
8
9	\| 场景 \| 调用 \|
10	\| ------------------------------------------------------------------- \| :---: \|
11	\| 用户提供本地 repo 路径，希望 AI 理解其架构 \| 是 \|
12	\| 需要生成 `.nexus-map/INDEX.md` 供后续 AI 会话冷启动 \| 是 \|
13	\| 用户说「帮我分析项目」「建立项目知识库」「让 AI 了解这个仓库」 \| 是 \|
14	\| 运行环境无 shell 执行能力（纯 API 调用模式，无 `run_command` 工具） \| 否 \|
15	\| 宿主机无本地 Python 3.10+ \| 否 \|
16	\| 目标仓库无任何已知语言源文件（`.py/.ts/.java/.go/.rs/.cpp` 等均无） \| 否 \|
17	\| 用户只想查询某个特定文件/函数 → 直接用 `view_file` / `grep_search` \| 否 \|
18
19	---
20
21	## 前提检查
22
23	缺失项要显式告知用户；需要降级等时及时提醒用户，经过同意才能继续。
24
25	\| 前提 \| 检查方式 \|
26	\| ----------------- \| --------------------------------------- \|
27	\| 目标路径存在 \| `$repo_path` 可访问 \|
28	\| Python 3.10+ \| `python --version` >= 3.10 \|
29	\| 脚本依赖已安装 \| `python -c "import tree_sitter"` 无报错 \|
30	\| 有 shell 执行能力 \| Agent 环境支持 `run_command` 工具调用 \|
31
32	`git` 历史是加分项，不是硬阻塞项。没有 `.git` 或历史过少时，跳过热点分析，并在输出中明确记录这是一次降级探测。
33
34	---
35
36	## 输入契约
37
38	```
39	repo_path: 目标仓库的本地绝对路径（必填）
40	```
41
42	语言支持：自动按文件扩展名 dispatch，语言配置（扩展名映射 + Tree-sitter 查询）存储在 `scripts/languages.json`。当前已接入 Python/JavaScript/TypeScript/TSX/Bash/Java/Go/Rust/C#/C/C++/Kotlin/Ruby/Swift/Scala/PHP/Lua/Elixir/GDScript/Dart/Haskell/Clojure/SQL/Proto/Solidity/Vue/Svelte/R/Perl 等 30+ 语言。
43
44	非标准语言：若仓库含有内置未支持的语言，通过命令行参数动态补充（详见 `references/05-language-customization.md`）：
45	- `--add-extension .templ=templ` 添加新文件扩展名映射
46	- `--add-query templ struct "(component_declaration ...)"` 添加结构查询
47	- `--language-config <JSON_FILE>` 复杂配置时使用 JSON 文件
48
49	扫描过滤：AST 提取与 `raw/file_tree.txt` 生成共享同一套过滤规则：
50	- `--exclude-dirs django_static,.go_root` 按目录名或仓库相对路径忽略杂物目录
51	- `--use-gitignore` 启用 `<repo_path>/.gitignore` 规则（默认开启），忽略其中声明的文件和目录
52	- `--no-gitignore` 不应用 `.gitignore` 规则；此时仍会保留内置排除项和 `--exclude-dirs`
53
54	---
55
56	## 输出格式
57
58	执行完成后，目标仓库根目录下将产出：
59
60	```text
61	.nexus-map/
62	├── INDEX.md ← AI 冷启动主入口（< 2000 tokens）
63	├── arch/
64	│ ├── systems.md ← 系统边界 + 代码位置
65	│ ├── dependencies.md ← Mermaid 依赖图 + 时序图
66	│ └── test_coverage.md ← 静态测试面：测试文件、覆盖到的核心模块、证据缺口
67	├── concepts/
68	│ ├── concept_model.json ← Schema V1 机器可读图谱
69	│ └── domains.md ← 核心领域概念说明
70	├── hotspots/
71	│ └── git_forensics.md ← Git 热点 + 耦合对分析
72	└── raw/
73	├── ast_nodes.json ← Tree-sitter 解析原始数据
74	├── git_stats.json ← Git 热点与耦合数据
75	└── file_tree.txt ← 过滤后的文件树
76	```
77
78	所有生成的 Markdown 文件必须带一个简短头部，至少包含：`generated_by`、`verified_at`、`provenance`。
79
80	`concept_model.json` 的人类可读名称字段统一使用 `label`，不要添加 `title`。
81
82	如果 PROFILE 阶段发现语言覆盖降级或人工推断，`provenance` 必须明确标注。
83
84	---
85
86	## PROBE 阶段门控
87
88	> [!IMPORTANT]
89	> 进入每个阶段前必须先读对应 reference，不得跳过。
90	> 各阶段详细步骤、完成检查清单与边界场景处理均在 reference 中定义。
91
92	```
93	[Skill 激活时] → read references/probe-protocol.md （阶段步骤蓝图，含边界场景与三维度质疑框架）
94	[EMIT 前] → read references/output-schema.md （Schema 校验规范）
95	[非标准语言时] → read references/language-customization.md（按需，非门控）
96	```
97
98	---
99
100	## 执行守则
101
102	### 守则1: OBJECT 拒绝形式主义
103
104	OBJECT 的存在意义是打破 REASON 的幸存者偏差。大量工程事实隐藏在目录命名和 git 热点背后，第一直觉几乎总是错的。
105
106	不合格质疑（禁止提交）：
107	```
108	Q1: 我对系统结构的把握还不够扎实
109	Q2: xxx 目录的职责暂时没有直接证据
110	```
111	问题不在措辞，而在于没有证据线索，也无法在 BENCHMARK 阶段验证。
112
113	合格质疑格式：
114	```
115	Q1: git_stats 显示 tasks/analysis_tasks.py 变更 21 次（high risk），
116	但 HYPOTHESIS 认为编排入口是 evolution/detective_loop.py。
117	矛盾：若 detective_loop 是入口，为何 analysis_tasks 热度更高？
118	证据线索: git_stats.json hotspots[0].path
119	验证计划: view tasks/analysis_tasks.py 的 class 定义 + import 树
120	```
121
122	---
123
124	### 守则2: implemented 节点必须有真实 code_path
125
126	> [!IMPORTANT]
127	> 写入 `concept_model.json` 前，必须先区分节点是 `implemented`、`planned` 还是 `inferred`。
128	> 只有 `implemented` 节点允许写入 `code_path`，且必须亲手验证存在。
129
130	```bash
131	# BENCHMARK 阶段验证方式
132	ls $repo_path/src/nexus/application/weaving/ # 目录存在 → 节点有效
133	ls $repo_path/src/nexus/application/nonexist/ # [!ERROR] → 修正或删除此节点
134	```
135
136	对于 `planned` 或 `inferred` 节点，使用：
137
138	```json
139	{
140	"implementation_status": "planned",
141	"code_path": null,
142	"evidence_path": "docs/architecture.md",
143	"evidence_gap": "仓库中未发现 src/agents/monarch/，仅在设计文档中出现"
144	}
145	```
146
147	禁止：用勉强相关的文件冒充 `code_path`、把状态塞进路径字段（如 `code_path: "PLANNED"`）。
148
149	---
150
151	### 守则3: EMIT 原子性
152
153	先全部写入 `.nexus-map/.tmp/`，全部成功后整体移动到正式目录，删除 `.tmp/`。
154	目的：中途失败不留半成品。下次执行检测到 `.tmp/` 存在 → 清理后重新生成。
155
156	幂等性规则：
157
158	\| 状态

People who liked this also viewed

6 picks

Type