核心用法
Atris 通过维护 atris/MAP.md 结构化代码地图，彻底改变代码探索方式。首次使用时扫描代码库，提取关键符号（入口点、导出、路由处理器、主类、配置加载器等），生成包含精确文件路径与行号的导航指南。后续所有查询优先查阅 MAP.md，直接跳转目标位置，避免重复全文搜索。
地图结构
- Quick Reference：15-25 个核心符号速查表
- By-Feature Map：按功能模块分组（如用户认证、支付处理）
- By-Concern Map：按横切关注点分组（如错误处理、日志记录）
- Critical Files：标注高影响力文件及关键函数位置
- Entry Points：文档化执行流程链路
工作流程
1. 查询前强制检查 atris/MAP.md
2. 命中 → 直接跳转 file:line
3. 未命中 → 用 rg 搜索一次 → 结果写入 MAP.md 永久保存
显著优点
- Token 效率极致优化：单次会话 10 个问题可节省 10 万+ tokens，降低 80-95% 探索成本
- 累积式智能：每次发现自动写入地图，知识资产持续增值
- 精确导航：行号级定位，消除「大概在这一片」的模糊搜索
- 多维度索引：功能视角 + 技术视角双轨并行，适配不同查询场景
- 轻量维护：支持增量更新，小修小补而非全量重建
潜在缺点与局限性
- 初始沉没成本：首次扫描需消耗固定 tokens 生成地图
- 同步依赖：代码大幅重构后需人工更新或选择性重生成，存在地图过期风险
- 符号提取局限：依赖
rg正则匹配，动态生成代码、复杂元编程场景可能遗漏 - 单项目隔离：每个代码库独立地图，无跨项目知识共享机制
- 工具链依赖：强制要求安装
ripgrep，Windows 环境需额外配置
适合人群
- 高频代码库探索者：需要反复查询大型/陌生项目的开发者
- 上下文受限场景：API 令牌预算紧张或长对话窗口有限的用例
- Agent/自动化工作流：需要确定性、可复现导航路径的系统集成
- 遗留项目维护：缺乏文档、结构混乱的代码库快速摸底
常规风险
- 地图过时导致错位：若用户修改代码后未同步更新 MAP.md，行号引用可能指向错误位置甚至空内容，需建立「变更即更新」的协作约定
- 过度依赖跳过验证：完全信任地图可能忽略新增文件，建议定期抽样校验
- 敏感信息泄露：MAP.md 包含完整文件路径与代码结构，提交至公共仓库可能暴露内部架构细节，建议加入
.gitignore - 增量更新遗漏：复杂重构时手工维护负担重，可能选择惰性全量重建而损失累积优势