Atris — 代码库智能系统

维护一份结构清晰的代码库地图，精确到文件路径与行号。一次扫描，永久留存知识。在代码探索过程中可节省 80–95% 的 token 消耗。

适用范围

• 适用于任何需要导航代码的仓库。
• 生成 atris/MAP.md 作为唯一的导航索引文件。

MAP 优先原则

在代码库中搜索任何内容之前，请执行以下步骤：

1. 先阅读 atris/MAP.md
2. 若在 MAP 中找到关键词 → 直接跳转至对应文件:行号。完成。
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 — [Project Name] 导航指南

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

## 快速参考

rg "functionName" path/to/file.ext    # 描述（第 N 行）
rg "className" path/to/file.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 就直接搜索
• 发现新信息后未及时记录到 MAP
• 本可通过精准更新解决的问题，却选择全量重建地图
• 将密钥、凭据或 .env 类文件纳入地图
• 凭猜测定位文件，而非依赖索引