nexus-mapper

# nexus-mapper — AI 项目探测协议

本 Skill 指导 AI Agent 使用 **PROBE 五阶段协议**，对任意本地 Git 仓库执行系统性探测，产出 `.nexus-map/` 分层知识库。

---

## 何时调用 / 何时不调用

| 场景                                                                | 调用  |
| ------------------------------------------------------------------- | :---: |
| 用户提供本地 repo 路径，希望 AI 理解其架构                          |  是   |
| 需要生成 `.nexus-map/INDEX.md` 供后续 AI 会话冷启动                 |  是   |
| 用户说「帮我分析项目」「建立项目知识库」「让 AI 了解这个仓库」      |  是   |
| 运行环境无 shell 执行能力（纯 API 调用模式，无 `run_command` 工具） |  否   |
| 宿主机无本地 Python 3.10+                                           |  否   |
| 目标仓库无任何已知语言源文件（`.py/.ts/.java/.go/.rs/.cpp` 等均无） |  否   |
| 用户只想查询某个特定文件/函数 → 直接用 `view_file` / `grep_search`  |  否   |

---

## 前提检查

缺失项要显式告知用户；需要降级等时及时提醒用户，经过同意才能继续。

| 前提              | 检查方式                                |
| ----------------- | --------------------------------------- |
| 目标路径存在      | `$repo_path` 可访问                     |
| Python 3.10+      | `python --version` >= 3.10              |
| 脚本依赖已安装    | `python -c "import tree_sitter"` 无报错 |
| 有 shell 执行能力 | Agent 环境支持 `run_command` 工具调用   |

`git` 历史是加分项，不是硬阻塞项。没有 `.git` 或历史过少时，跳过热点分析，并在输出中明确记录这是一次降级探测。

---

## 输入契约

```
repo_path: 目标仓库的本地绝对路径（必填）
```

**语言支持**：自动按文件扩展名 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+ 语言。

**非标准语言**：若仓库含有内置未支持的语言，通过命令行参数动态补充（详见 `references/05-language-customization.md`）：
- `--add-extension .templ=templ` 添加新文件扩展名映射
- `--add-query templ struct "(component_declaration ...)"` 添加结构查询
- `--language-config <JSON_FILE>` 复杂配置时使用 JSON 文件

**扫描过滤**：AST 提取与 `raw/file_tree.txt` 生成共享同一套过滤规则：
- `--exclude-dirs django_static,.go_root` 按目录名或仓库相对路径忽略杂物目录
- `--use-gitignore` 启用 `<repo_path>/.gitignore` 规则（默认开启），忽略其中声明的文件和目录
- `--no-gitignore` 不应用 `.gitignore` 规则；此时仍会保留内置排除项和 `--exclude-dirs`

---

## 输出格式

执行完成后，目标仓库根目录下将产出：

```text
.nexus-map/
├── INDEX.md                    ← AI 冷启动主入口（< 2000 tokens）
├── arch/
│   ├── systems.md              ← 系统边界 + 代码位置
│   ├── dependencies.md         ← Mermaid 依赖图 + 时序图
│   └── test_coverage.md        ← 静态测试面：测试文件、覆盖到的核心模块、证据缺口
├── concepts/
│   ├── concept_model.json      ← Schema V1 机器可读图谱
│   └── domains.md              ← 核心领域概念说明
├── hotspots/
│   └── git_forensics.md        ← Git 热点 + 耦合对分析
└── raw/
    ├── ast_nodes.json          ← Tree-sitter 解析原始数据
    ├── git_stats.json          ← Git 热点与耦合数据
    └── file_tree.txt           ← 过滤后的文件树
```

所有生成的 Markdown 文件必须带一个简短头部，至少包含：`generated_by`、`verified_at`、`provenance`。

`concept_model.json` 的人类可读名称字段统一使用 `label`，不要添加 `title`。

如果 PROFILE 阶段发现语言覆盖降级或人工推断，`provenance` 必须明确标注。

---

## PROBE 阶段门控

> [!IMPORTANT]
> **进入每个阶段前必须先读对应 reference，不得跳过。**
> 各阶段详细步骤、完成检查清单与边界场景处理均在 reference 中定义。

```
[Skill 激活时]     → read references/probe-protocol.md  （阶段步骤蓝图，含边界场景与三维度质疑框架）
[EMIT 前]          → read references/output-schema.md    （Schema 校验规范）
[非标准语言时]     → read references/language-customization.md（按需，非门控）
```

---

## 执行守则

### 守则1: OBJECT 拒绝形式主义

OBJECT 的存在意义是打破 REASON 的幸存者偏差。大量工程事实隐藏在目录命名和 git 热点背后，第一直觉几乎总是错的。

不合格质疑（禁止提交）：
```
Q1: 我对系统结构的把握还不够扎实
Q2: xxx 目录的职责暂时没有直接证据
```
问题不在措辞，而在于没有证据线索，也无法在 BENCHMARK 阶段验证。

合格质疑格式：
```
Q1: git_stats 显示 tasks/analysis_tasks.py 变更 21 次（high risk），
    但 HYPOTHESIS 认为编排入口是 evolution/detective_loop.py。
    矛盾：若 detective_loop 是入口，为何 analysis_tasks 热度更高？
    证据线索: git_stats.json hotspots[0].path
    验证计划: view tasks/analysis_tasks.py 的 class 定义 + import 树
```

---

### 守则2: implemented 节点必须有真实 code_path

> [!IMPORTANT]
> 写入 `concept_model.json` 前，必须先区分节点是 `implemented`、`planned` 还是 `inferred`。
> 只有 `implemented` 节点允许写入 `code_path`，且必须亲手验证存在。

```bash
# BENCHMARK 阶段验证方式
ls $repo_path/src/nexus/application/weaving/   # 目录存在 → 节点有效
ls $repo_path/src/nexus/application/nonexist/  # [!ERROR] → 修正或删除此节点
```

对于 `planned` 或 `inferred` 节点，使用：

```json
{
  "implementation_status": "planned",
  "code_path": null,
  "evidence_path": "docs/architecture.md",
  "evidence_gap": "仓库中未发现 src/agents/monarch/，仅在设计文档中出现"
}
```

禁止：用勉强相关的文件冒充 `code_path`、把状态塞进路径字段（如 `code_path: "PLANNED"`）。

---

### 守则3: EMIT 原子性

先全部写入 `.nexus-map/.tmp/`，全部成功后整体移动到正式目录，删除 `.tmp/`。
目的：中途失败不留半成品。下次执行检测到 `.tmp/` 存在 → 清理后重新生成。

幂等性规则：

| 状态                                 | 处理方式                                   |
| ------------------------------------ | ------------------------------------------ |
| `.nexus-map/` 不存在                 | 直接继续                                   |
| `.nexus-map/` 存在且 `INDEX.md` 有效 | 询问用户：「是否覆盖？[y/n]」              |
| `.nexus-map/` 存在但文件不完整       | 「检测到未完成分析，将重新生成」，直接继续 |

---

### 守则4: INDEX.md 的角色——冷启动路由器，而非静态字典

`INDEX.md` 的读者是**从未见过这个仓库的 AI**。两个硬约束：
- **< 2000 tokens** — 超过就重写，不是截断
- **结论必须具体** — 证据不足时明确写出 `evidence gap` 或 `unknown`，并说明缺了什么证据

写完后执行 token 估算：行数 × 平均 30 tokens/行 = 粗估值。

**INDEX.md 必须包含的强制路由块（Hard-Trigger Block）**——生成时把这段结构写入文件末尾：

```markdown
## [操作指南] 强制执行步骤

> 本节是对所有读取本文件的 AI 发出的硬性操作指令，不是建议。

### 步骤1 — 必须先读完以下所有文件（顺序不限）

读完本文件后，在执行任何任务之前，必须依次 read 以下文件完整内容：

- `.nexus-map/arch/systems.md` — 系统边界与代码位置
- `.nexus-map/arch/dependencies.md` — 系统间依赖关系与 Mermaid 图
- `.nexus-map/arch/test_coverage.md` — 测试面与证据缺口
- `.nexus-map/hotspots/git_forensics.md` — Git 热点与耦合风险
- `.nexus-map/concepts/domains.md` — 核心领域概念

> 这些文件均为高密度摘要，总量通常 < 5000 tokens，是必要的上下文成本。
> 不得以"任务简单"或"只改一个文件"为由跳过。

### 步骤2 — 按任务类型追加操作（步骤1 完成后执行）

- 若任务涉及**接口修改、新增跨模块调用、删除/重命名公共函数**：
  → 必须运行 `query_graph.py --impact <目标文件>` 确认影响半径后再写代码。
- 若任务需要**判断某文件被谁引用**：
  → 运行 `query_graph.py --who-imports <模块名>`。
- 若仓库结构已发生重大变化（新增系统、重构模块边界）：
  → 任务完成后评估是否需要重新运行 nexus-mapper 更新知识库。
```

---

### 守则5: 最小执行面与敏感信息保护

> [!IMPORTANT]
> 默认只运行本 Skill 自带脚本和必要的只读检查。不要因为"想更懂仓库"就执行目标仓库里的构建脚本、测试脚本或自定义命令。

- 默认允许：`extract_ast.py`、`git_detective.py`、目录遍历、文本搜索、只读文件查看
- 默认禁止：执行目标仓库的 `npm install`、`pnpm dev`、`python main.py`、`docker compose up` 等，除非用户明确要求
- 遇到 `.env`