# code-navigator

**Repository Path**: jatxl3/code-navigator

## Basic Information

- **Project Name**: code-navigator
- **Description**: 百万行级代码仓库的模块化导航与按需加载引擎。将大型代码库分解为<2万行的模块，生成导航知识库(.code-nav/)，在Coding任务中精准加载目标模块代码，让200k上下文窗口的模型也能驾驭超大规模项目。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-07-25
- **Last Updated**: 2026-07-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

---
name: code-navigator
description: 百万行级代码仓库的模块化导航与按需加载引擎。将大型代码库分解为<2万行的模块，生成导航知识库(.code-nav/)，在Coding任务中精准加载目标模块代码，让200k上下文窗口的模型也能驾驭超大规模项目。当用户需要理解、导航、搜索大型代码库，或在大型项目上执行编码任务时，务必使用此skill——即使用户只是说"帮我看看这个项目"或"在xxx上加个功能"，只要项目代码量超过2万行，就应该激活code-navigator。
license: MIT
---

# Code Navigator — 百万行代码的导航引擎

## 解决什么问题

国产模型支持200k上下文窗口，但团队项目动辄几十万行代码。把全量代码塞进上下文不现实，模型编码时容易上下文缺失、遗漏依赖关系，导致产出质量下降。

Code Navigator 的核心思路是**化整为零、按需加载**：

1. **MAPPER 模式**：分析整个代码库，按耦合/内聚拆分成 <2万行 的模块，生成 `.code-nav/` 导航知识库
2. **QUERY 模式**：面对编码任务时，通过导航文档精准定位目标模块，只加载相关代码到上下文

为什么是2万行？200k token 的上下文窗口中，扣除系统提示、任务指令、对话历史，留给代码的空间约 4-5万 token。2万行代码（约 2-4万 token）+ 模块说明文档 + 任务指令，刚好填满而不溢出。模型能完整掌握单个模块，理解调用链，做出高质量的编码决策。

## 目录结构

```
.code-nav/
├── INDEX.md              ← 冷启动入口，架构全景 < 2000 token
├── modules/
│   ├── module-001.md     ← 模块描述、代码位置、关键 API、行数
│   ├── module-002.md
│   └── ...
├── arch/
│   ├── systems.md        ← 子系统职责与代码位置
│   ├── dependencies.md   ← 模块间依赖关系图（Mermaid）
│   └── boundaries.md     ← 模块边界定义
├── concepts/
│   ├── domain_model.json ← 机器可读的知识图谱
│   └── domains.md        ← 领域语言术语表
├── hotspots/
│   └── git_forensics.md  ← 高频变更文件与耦合分析
└── raw/
    ├── ast_nodes.json    ← 原始 AST 数据
    ├── module_map.json   ← 模块-文件映射（含行数）
    └── git_stats.json    ← Git 统计数据
```

每个文件的职责：

| 文件 | 用途 | 谁读 |
|------|------|------|
| `INDEX.md` | 架构全景，< 2000 token，模型冷启动时第一个读 | QUERY 模式 |
| `modules/*.md` | 每个模块的"说明书"：职责、文件列表、关键 API、依赖 | QUERY 模式 |
| `arch/systems.md` | 子系统级视图，比模块更粗粒度 | MAPPER 输出、QUERY 辅助 |
| `arch/dependencies.md` | Mermaid 依赖图，快速判断修改影响范围 | QUERY 模式 |
| `arch/boundaries.md` | 模块边界定义，解释为什么这样拆分 | MAPPER 输出 |
| `concepts/domain_model.json` | 领域实体关系，机器可读 | query_graph.py |
| `concepts/domains.md` | 业务术语→代码映射，帮助理解领域语言 | QUERY 模式 |
| `hotspots/git_forensics.md` | 高频变更文件 & 耦合分析，辅助风险评估 | QUERY 模式 |
| `raw/ast_nodes.json` | AST 提取原始数据，所有分析的基石 | scripts |
| `raw/module_map.json` | module_slicer 输出，模块→文件的精确映射 | scripts |
| `raw/git_stats.json` | git_detective 输出，变更频率与耦合数据 | scripts |

## 核心设计原则

### 1. 模块 < 2万行

每个模块的代码量严格控制在 2万行以内。这不是任意设限——200k 上下文窗口中，2万行代码约占 2-4万 token，剩余空间留给指令、对话历史和其他必要模块。模块超限时，按子目录或职责进一步拆分，不要合并松耦合的代码来凑数。

### 2. 导航即地图

`INDEX.md` 是整个代码库的"导航地图"。模型拿到编码任务后，先读 INDEX.md 获取全景，再精准跳转到目标模块。就像用地图导航——不需要看到整座城市的每栋楼，只需要知道目标在哪个街区、怎么过去。

INDEX.md 控制 < 2000 token，因为它是每次 QUERY 的必读内容。太大会挤占代码空间。

### 3. 按需加载

只加载当前编码任务相关的模块代码。一个典型的编码任务通常只涉及 1-3 个模块——目标模块 + 直接依赖模块。把不相关的代码塞进上下文只会增加噪音，降低模型输出质量。

### 4. 证据驱动

模块边界基于 AST 数据和 Git 历史推导，不是凭感觉划分。耦合度、内聚度、变更频率都是可量化的证据。每条信息标注来源：`implemented`（代码中已实现）、`planned`（设计文档中规划但未实现）、`inferred`（从代码模式推断）。

### 5. 来源追踪

所有分析结果标注数据来源。模型在做编码决策时需要区分哪些是确定的事实、哪些是推断——错误地把 `inferred` 当作 `implemented` 可能导致编码错误。

---

## MAPPER 模式 — 代码分析与模块拆分

MAPPER 模式对代码库做全量分析，输出 `.code-nav/` 知识库。在项目初始化或大重构后运行一次，后续 QUERY 模式反复使用。

### PROBE 协议

MAPPER 按五个阶段执行，每个阶段有明确的输入/输出和质量校验：

#### P — PROFILE（采集画像）

运行 `extract_ast.py` 收集代码库的原始数据：

```bash
python skills/code-navigator/scripts/extract_ast.py /path/to/repo > .code-nav/raw/ast_nodes.json
```

这个脚本做了什么：
- 遍历仓库中所有源码文件，提取 AST 节点（类、函数、变量定义、导入关系）
- 输出 JSON 格式的 AST 数据，包含文件路径、节点类型、名称、位置、调用关系
- 同时采集 Git 统计数据：

```bash
python skills/code-navigator/scripts/git_detective.py /path/to/repo > .code-nav/raw/git_stats.json
```

git_detective 输出高频变更文件、文件间变更耦合（经常一起修改的文件对）、贡献者分布。这些数据帮助后续判断模块的"稳定性"和"变更边界"。

语言配置见 `scripts/languages.json`，支持扩展新语言。

#### R — REASON（推理边界）

基于 AST 数据和 Git 历史，分析代码的耦合/内聚结构：

- **静态耦合**：文件 A import 文件 B → 存在耦合
- **动态耦合**：文件 A 和 B 经常在同一次 commit 中修改 → 变更耦合（git_detective 提供）
- **内聚指标**：同一目录下的文件共享多少类型/函数引用

这一步的核心判断：哪些文件应该在一起（高内聚），哪些文件应该分开（低耦合）。目标是最小化模块间依赖，最大化模块内内聚。

#### O — OBJECT（定义模块）

运行 `module_slicer.py` 执行模块拆分：

```bash
python skills/code-navigator/scripts/module_slicer.py .code-nav/raw/ast_nodes.json --max-lines 20000
```

module_slicer 根据 REASON 阶段的耦合/内聚分析，将文件分配到模块中。关键参数 `--max-lines 20000` 控制每个模块的代码量上限。拆分策略：

1. 优先按目录结构分组（目录通常是模块的自然边界）
2. 超限目录按子目录或职责进一步拆分
3. 跨目录的高耦合文件归入同一模块
4. 工具类/共享代码归入独立的 `shared` 或 `common` 模块

输出 `.code-nav/raw/module_map.json`，格式：

```json
{
  "modules": [
    {
      "id": "module-001",
      "name": "用户认证",
      "files": [
        {"path": "src/auth/login.py", "lines": 245},
        {"path": "src/auth/token.py", "lines": 180}
      ],
      "total_lines": 425,
      "dependencies": ["module-003"]
    }
  ]
}
```

#### B — BENCHMARK（校验质量）

验证每个模块满足约束：

| 约束 | 标准 | 不满足时的处理 |
|------|------|----------------|
| 模块行数 | < 20,000 行 | 按 REASON 策略进一步拆分 |
| 模块依赖数 | < 8 个直接依赖 | 检查是否拆分过细，考虑合并 |
| 孤立模块 | 至少被一个其他模块依赖 | 检查是否为入口模块或工具库 |

如果校验不通过，回到 REASON 阶段调整边界。

#### E — EMIT（生成知识库）

生成 `.code-nav/` 完整知识库：

1. **INDEX.md**：架构全景，包含子系统列表、模块索引、核心依赖关系。< 2000 token。这是模型冷启动时唯一需要读取的文件，所以要精炼。

2. **modules/*.md**：每个模块一份说明文档，包含：
   - 模块职责（一段话）
   - 文件列表及每个文件的职责
   - 关键 API / 类 / 函数列表
   - 依赖的其他模块
   - 代码总行数

3. **arch/**：架构视图
   - `systems.md`：子系统职责划分，比模块更粗的粒度
   - `dependencies.md`：Mermaid 格式的依赖关系图，一目了然
   - `boundaries.md`：模块边界定义，解释拆分理由

4. **concepts/**：领域知识
   - `domain_model.json`：领域实体和关系，机器可读
   - `domains.md`：业务术语→代码位置的映射

5. **hotspots/git_forensics.md**：高频变更区域和耦合分析结果

每条信息标注来源标签：`[implemented]`、`[planned]`、`[inferred]`。

### 完整 MAPPER 执行流程

```bash
# 1. 创建输出目录
mkdir -p .code-nav/{modules,arch,concepts,hotspots,raw}

# 2. 采集 AST 画像
python skills/code-navigator/scripts/extract_ast.py /path/to/repo > .code-nav/raw/ast_nodes.json

# 3. 采集 Git 统计
python skills/code-navigator/scripts/git_detective.py /path/to/repo > .code-nav/raw/git_stats.json

# 4. 模块拆分
python skills/code-navigator/scripts/module_slicer.py .code-nav/raw/ast_nodes.json --max-lines 20000

# 5. 生成知识库（由 LLM 根据 raw 数据和模块映射生成 Markdown 文档）
```

步骤 5 由 LLM 执行——读取 `raw/module_map.json` 和 `raw/ast_nodes.json`，按照上面的格式规范生成各 Markdown 文件。LLM 能理解代码语义，写出人类可读的模块说明，这是纯脚本做不到的。

---

## QUERY 模式 — 按需加载代码

QUERY 模式是日常编码时的入口。模型拿到编码任务后，通过导航知识库精准定位并加载目标代码。

### 执行步骤

#### Step 1: 读取导航地图

```bash
# 读取 INDEX.md，获取架构全景（< 2000 token，成本很低）
cat .code-nav/INDEX.md
```

INDEX.md 提供足够的上下文让模型判断：这个任务涉及哪些子系统、哪些模块。

#### Step 2: 定位目标模块

根据任务描述，从 INDEX.md 中识别目标模块。如果需要更详细的模块信息，读取对应的 `modules/module-xxx.md`。

也可以用 `query_graph.py` 精确查询：

```bash
# 查询某个文件属于哪个模块
python skills/code-navigator/scripts/query_graph.py .code-nav/raw/ast_nodes.json --file src/core/engine.py

# 查询谁依赖了某个模块
python skills/code-navigator/scripts/query_graph.py .code-nav/raw/ast_nodes.json --who-imports src.core.engine

# 修改某个文件的影响分析
python skills/code-navigator/scripts/query_graph.py .code-nav/raw/ast_nodes.json --impact src/core/engine.py --git-stats .code-nav/raw/git_stats.json

# 查找枢纽模块（被依赖最多的模块）
python skills/code-navigator/scripts/query_graph.py .code-nav/raw/ast_nodes.json --hub-analysis

# 仓库概览摘要
python skills/code-navigator/scripts/query_graph.py .code-nav/raw/ast_nodes.json --summary
```

#### Step 3: 加载目标代码

确定模块后，只加载相关模块的源码到上下文：

```bash
# 加载某个模块的全部源码
python skills/code-navigator/scripts/query_graph.py .code-nav/raw/ast_nodes.json --module module-001 --load-code /path/to/repo
```

加载策略——根据任务类型选择加载范围：

| 任务类型 | 加载范围 | 原因 |
|----------|----------|------|
| Bug 修复 | 目标模块 + 直接依赖 | Bug 通常局部化，但需理解调用链 |
| 新功能 | 目标模块 + 相邻模块 + 接口定义 | 需要理解边界和插入点 |
| 重构 | 目标模块 + 所有依赖方 | 修改接口影响全局 |
| 代码审查 | 仅目标模块 | 审查关注单模块质量 |

#### Step 4: 执行编码任务

在精准的上下文中完成编码。此时模型已掌握：
- 目标模块的完整代码（< 2万行，在上下文窗口内）
- 模块说明文档（关键 API、职责、依赖关系）
- 依赖模块的接口（不需要完整代码，只需 API 签名）

### QUERY 决策流程

```
收到编码任务
    │
    ▼
读 INDEX.md（< 2000 token）
    │
    ▼
识别目标模块 ──────────────── 不确定？用 query_graph.py 精确查询
    │
    ▼
读 modules/target.md ──────── 了解模块详情
    │
    ▼
加载目标模块源码 ──────────── --module module-xxx --load-code
    │
    ▼
需要依赖模块？ ──── 是 ──── 加载依赖模块的接口/关键文件
    │
    否
    │
    ▼
执行编码任务
```

---

## 脚本参考

### scripts/extract_ast.py — 多语言 AST 提取器

```bash
python scripts/extract_ast.py <repo_path> [--lang python,typescript,go,...] [--exclude "test/**,vendor/**"]
```

- 遍历仓库源码文件，提取类、函数、变量、导入等 AST 节点
- 输出 JSON 到 stdout，包含节点类型、名称、位置、调用关系
- 语言配置见 `scripts/languages.json`
- `--exclude` 排除测试、第三方等不需要分析的目录

### scripts/module_slicer.py — 模块拆分引擎

```bash
python scripts/module_slicer.py <ast_nodes.json> --max-lines 20000 [--output .code-nav/raw/module_map.json]
```

- 读取 AST 数据，按耦合/内聚分析拆分模块
- `--max-lines` 控制每个模块的代码量上限
- 输出 `module_map.json`，包含模块→文件映射、依赖关系、行数统计

### scripts/query_graph.py — 按需代码查询

```bash
# 查询文件所属模块
python scripts/query_graph.py <ast_nodes.json> --file <file_path>

# 查询谁导入了指定模块
python scripts/query_graph.py <ast_nodes.json> --who-imports <module_path>

# 影响分析（修改某文件会影响哪些模块）
python scripts/query_graph.py <ast_nodes.json> --impact <file_path> --git-stats <git_stats.json>

# 枢纽模块分析（被依赖最多的模块）
python scripts/query_graph.py <ast_nodes.json> --hub-analysis

# 仓库概览摘要
python scripts/query_graph.py <ast_nodes.json> --summary

# 加载指定模块的源码
python scripts/query_graph.py <ast_nodes.json> --module <module_id> --load-code <repo_path>
```

### scripts/git_detective.py — Git 热点与耦合分析

```bash
python scripts/git_detective.py <repo_path> [--since "6 months ago"] [--top 50]
```

- 分析 Git 历史，输出高频变更文件和变更耦合对
- `--since` 限定分析的时间范围
- `--top` 输出前 N 个热点文件
- 结果写入 `.code-nav/raw/git_stats.json` 和 `.code-nav/hotspots/git_forensics.md`

### scripts/languages.json — 语言配置

定义每种支持的语言的：文件扩展名、AST 解析策略、导入语法、注释语法。扩展新语言时编辑此文件。

---

## 参考文档

| 文件 | 内容 | 何时读取 |
|------|------|----------|
| `references/mapper-protocol.md` | MAPPER 模式完整执行蓝图，包含每个阶段的详细步骤和输出格式 | 执行 MAPPER 前 |
| `references/output-schema.md` | 所有 JSON 和 Markdown 输出格式的完整 schema 定义 | 生成知识库时 |
| `references/language-customization.md` | 如何扩展语言支持，添加新的 AST 解析策略 | 遇到不支持的语种时 |

---

## 与 Nexus-skills 的关系

本 skill 的灵感来自开源项目 [Nexus-skills](https://github.com/Haaaiawd/Nexus-skills)，该项目提供：
- **nexus-mapper**：代码仓库全量分析，生成 `.nexus-map/` 知识库
- **nexus-query**：从 AST 数据查询代码结构

Code Navigator 在此基础上做了关键创新：

| 维度 | Nexus-skills | Code Navigator |
|------|-------------|----------------|
| 输出粒度 | 文件级别 | **模块级别（<2万行）** |
| 核心目标 | 代码结构查询 | **支撑编码任务的按需加载** |
| 上下文管理 | 无 | **精确控制在200k窗口内** |
| 编码集成 | 无 | **QUERY模式直接对接编码任务** |
| Git 分析 | 无 | **热点和耦合分析辅助决策** |

简单说，Nexus-skills 回答"代码长什么样"，Code Navigator 回答"我该看哪些代码来完成任务"。

---

## 常见问题

**Q: 什么时候运行 MAPPER？**
项目初始化时运行一次。重大重构后（目录结构调整、模块拆分合并）重新运行。日常小改动不需要重跑。

**Q: 代码库只有几千行还需要这个 skill 吗？**
不需要。小项目整个代码库都能塞进上下文，直接读取即可。这个 skill 的价值在代码量超过2万行时才显现。

**Q: 模块拆分结果不理想怎么办？**
module_slicer 基于耦合/内聚自动拆分，但不一定符合团队的模块认知。可以手动编辑 `module_map.json`，调整文件归属后再生成知识库。MAPPER 的 EMIT 阶段会尊重手动调整。

**Q: 多语言项目怎么处理？**
extract_ast.py 支持多语言（配置见 languages.json）。模块拆分时跨语言的耦合关系通过接口定义（如 RPC、消息队列）推断，标注为 `[inferred]`。

**Q: 和 coding-agent skill 怎么配合？**
coding-agent 提供编码工作流（规划→执行→验证），code-navigator 提供精准的代码上下文。大型项目中先启动 code-navigator 的 QUERY 模式定位代码，再用 coding-agent 的流程执行编码——上下文精准 + 流程规范 = 高质量产出。