Atris — 代码库智能导航

通过精确的文件:行号引用，维护代码库的结构化地图。一次扫描，永久知识。在代码探索中节省 80-95% 的 token。

作用范围

• 适用于任何需要导航代码库的项目。
• 创建 atris/MAP.md 作为唯一的导航索引。

先看 MAP 规则

在代码库中搜索任何内容之前：

1. 阅读 atris/MAP.md
2. 找到关键词 → 直接跳转到文件:行号。完成。
3. 未找到 → 使用 rg 搜索一次，然后 将结果添加到 MAP.md

每次使用，地图都会变得更智能。不要让任何发现被遗漏。

首次设置

如果 atris/MAP.md 不存在，请生成它：

1. 在项目根目录创建 atris/ 文件夹
2. 扫描代码库（规则如下）
3. 将结果写入 atris/MAP.md
4. 提示用户：“已在 atris/MAP.md 建立你的代码库地图。”

如果 atris/MAP.md 已存在，请直接使用。仅当用户要求或地图明显过期（引用文件缺失、行号严重偏差）时才重新生成。

如何扫描

跳过：node_modules、.git、dist、build、vendor、__pycache__、.venv、.env*、*.key、*.pem、credentials*、secrets*

使用 ripgrep 提取代码结构：

# 关键定义
rg "^(export|function|class|const|def |async def |router\.|app\.|@app\.)" --line-number -g "!node_modules" -g "!.git" -g "!dist" -g "!.env*"

# 路由定义
rg "(get|post|put|delete|patch)\s*\(" --line-number -g "*.ts" -g "*.js" -g "*.py"

# 入口点
rg "listen|createServer|app\.start|if __name__" --line-number

MAP.md 结构

# MAP.md — [项目名称] 导航指南

> 由 Atris 生成 | 最后更新：YYYY-MM-DD

## 快速参考

rg "函数名" 路径/文件.ext    # 描述（第 N 行）
rg "类名" 路径/文件.ext       # 描述（第 N 行）

提取前 15-25 个最重要的符号：入口点、导出项、路由处理器、主类、配置加载器。

按功能划分的地图

按功能组织代码。每个引用包含确切的文件路径和行号。

### 功能：用户认证
**目的：** 登录、注册、令牌管理
- **入口：** `src/auth/login.ts:45-89` （handleLogin）
- **验证：** `src/auth/validate.ts:12-67` （validateToken）
- **模型：** `src/models/user.ts:8-34` （User Schema）
- **路由：** `src/routes/auth.ts:5-28` （POST /login, POST /register）

按关注点划分的地图

按跨功能模式分组（错误处理、日志记录、认证中间件等）。

关键文件

标记高影响文件，并说明其重要性；列出关键函数及其行号。

入口点

执行流程说明——开发服务器启动、请求生命周期、构建流程。

保持地图更新

代码库变更时，小范围更新 MAP.md：

• 新增文件 → 添加到相关章节
• 移动/重命名 → 更新所有引用
• 新增重要函数 → 添加到快速参考
• 删除文件 → 从地图中移除
• 重大重构 → 重新生成受影响部分

小幅度更新，不进行全量再生。地图随代码演进。

反模式

• 不检查 MAP 就开始搜索
• 让发现未被记录
• 用全量再生代替局部更新
• 将密钥、凭证或 .env 文件包含在地图中
• 未经索引猜测文件位置