fkenmar/atlas

当 AI 编程代理在你的 repo 中工作时，它把大部分精力都花在了弄清楚各个代码的位置上：打开一个又一个文件来了解项目布局。**atlas** 只需执行一次此操作，就能为代理提供一张约 2,000-token 的浓缩地图——包含所有函数签名、类型和 import，并按重要性排序，且不包含函数体。代理可以立即找到方向并开始工作。 在我们的基准测试中，将 atlas 地图添加到代理的上下文中，在“查找正确代码”的任务中，它进行探索所消耗的 token 最多减少了 **78%**——且准确度没有任何损失。 ## 效果展示 在这个 repo 中运行 `atlas src --budget 600`，它会输出： ``` # atlas: src (3740 LOC, 16 个文件) | budget 600 | rendered 585 tok ## cache.rs (#1 — 被 1 个文件导入) pub struct Cache pub fn open(&Path) -> Cache pub fn get(&mut self, &str, u64) -> Option pub fn save(self) pub fn content_hash(&str) -> u64 imports: parse.rs used by: parse.rs ``` 文件按重要性排序（基于 import 图的 PageRank 算法），`#1` 是最核心的文件。每个文件都展示了它的 public symbol、它 import 的内容以及依赖于它的模块——包含了代理导航所需的一切信息，没有半点多余。页眉处显示了预算以及实际 `rendered` 的 token 数量。 **支持映射的格式：** Python (`.py`, `.pyi`)、TypeScript/JavaScript (`.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs`, ……) 以及 Rust (`.rs`)。它会识别你的 `.gitignore` 和可选的 `.atlasignore`，并始终跳过隐藏目录和常见的 vendored/build 文件夹（`node_modules`、`target`、`dist`、`build`、`venv`、`__pycache__`、`vendor`……）。如果你发现某个预期的文件没出现在地图里，通常是因为它属于不支持的语言，或者是被跳过的目录。 ## 安装 **预编译二进制文件** — 无需 Rust 环境（支持 macOS 和 Linux）： ``` curl --proto '=https' --tlsv1.2 -LsSf https://github.com/fkenmar/atlas/releases/download/v0.1.0-alpha/atlas-installer.sh | sh ``` 在 Windows 上，请从 [releases 页面](https://github.com/fkenmar/atlas/releases) 下载 `atlas-x86_64-pc-windows-msvc.zip`。所有平台（x64 + arm64）的二进制文件均由 [cargo-dist](https://opensource.axo.dev/cargo-dist/) 附带在每次发布中。 **通过源码编译** — 适用所有平台，需要 [Rust](https://rustup.rs)： ``` git clone https://github.com/fkenmar/atlas cd atlas cargo install --path . ``` 这会将 `atlas` 编译到 `~/.cargo/bin` 目录中——请确保该路径在你的 `PATH` 中（rustup 默认会自动配置此项）。 无论使用哪种方式，都可以进行验证并试运行： ``` atlas --version cd path/to/your/project atlas . ``` 你应该会看到一个 `# atlas: …` 页眉，后面跟着按权重排序的文件列表。这就是该工具的全部输出。 ## 使用 ``` atlas . # map the current folder (2,048-token budget) atlas . --budget 4096 # give it a bigger budget atlas . --focus src/auth # rank the files you're working on higher atlas . --lang py,rs # only these languages atlas . --no-private # public API surface only atlas . --format json # JSON instead of Markdown ``` 默认情况下，atlas 的目标预算是 2,048 个 token。当 repo 的大小超出预算时，它会分阶段降级处理，而不是直接截断：它会先剔除 private symbol（此时页眉会显示 `public-only`），接着省略参数细节，最后将权重最低的文件折叠成单行。你可以调高 `--budget` 来获取更多细节，或者使用 `--focus` 来重点保护你在意的路径。 atlas 会将解析结果缓存在 repo 根目录下的 `.atlas/` 文件夹中，从而让重复执行的速度非常快——请记得将 `.atlas/` 添加到你的 `.gitignore` 中。 你可以直接将输出通过管道传递到代理的上下文中，或者将其保存到文件中： ``` atlas . > map.md ``` ## 与你的 AI 代理配合使用 atlas 会将地图输出到标准输出，因此它可以无缝接入任何代理的上下文。 **保存并引用它** — 适用于 Claude Code、Cursor、Windsurf、Copilot 或任何聊天工具： ``` atlas . > atlas-map.md ``` 然后，在你的 prompt 中使用 `@` 提及 `atlas-map.md`（或者直接将其内容粘贴进去）。当代码结构发生改变时，只需重新生成即可——重复运行会利用热缓存，只需约 80 毫秒即可完成，因此保持最新状态的成本极低。 **通过管道内联**传递给任何 CLI 代理： ``` { echo "Repo map:"; atlas .; echo; echo "Task: add a --verbose flag"; } | your-agent ``` **将预算集中在你正在修改的部分** — `--focus` 会提高这些路径的权重；可以多次重复该标签来指定多个路径： ``` atlas . --focus src/auth --focus src/api > atlas-map.md ``` **将其保存在 repo 中**，这样每一位贡献者和代理在初始阶段就能明确代码结构——将 `atlas-map.md` 提交到版本库，并在 pre-commit 钩子或 CI 中重新生成它。 ## 工作原理 代理在陌生 repo 上消耗的大笔 token 费用主要用于*探索*——即读取文件以构建心智模型。地图可以预先提供这种模型，但是一张粗糙的地图（直接导出所有文件）体积过大，省下的成本还不够抵消其消耗。atlas 通过两种方式来发挥其价值： 1. **仅提取结构。** 仅包含签名、类型和 import——绝不包含函数体。仅此一项就只占用源代码的一小部分体积。 2. **排序与预算控制。** 它会根据每个文件在代码库中的核心程度对其进行评分，并将最重要的部分打包到固定的 token 预算中，从而保证地图足够小巧，能够在每一轮对话中都驻留在上下文中。 ``` discover → parse → link → rank → budget → render ``` 它通过 [tree-sitter](https://tree-sitter.github.io/tree-sitter/) 读取你的 repo，遵循 `.gitignore`（以及 `.atlasignore`）规则，并缓存解析结果以实现快速重复执行。 ## 故障排除 - **地图为空 / "0 files"。** atlas 在该路径下找不到支持的源代码。请检查其语言是否属于支持映射的类型（Python、TS/JS、Rust），并确保你指向的是项目根目录——而不是单个文件，也不是被 vendored 或被忽略的目录。 - **`command not found: atlas`。** `~/.cargo/bin` 不在你的 `PATH` 中。请将其添加进去（rustup 的安装程序通常会自动处理），或者通过完整路径来运行该二进制文件。 - **某个 symbol 错误或缺失。** 这通常是 tree-sitter 提取 bug 引起的——请[提交一个 issue](https://github.com/fkenmar/atlas/issues/new?template=bug_report.md)，并附上能够复现该问题的最小代码片段。 ## 项目状态 Alpha 阶段。核心功能已实现端到端运作，并经过了基准测试，但 CLI 和输出格式可能仍会发生变化。请参阅 [STATUS.md](STATUS.md) 了解当前状态，查阅 [CHANGELOG.md](CHANGELOG.md) 了解已发布的内容，以及 [docs/PRD.md](docs/PRD.md) 获取完整的设计文档。 即将推出：一个 MCP server，以便代理可以直接查询地图（`atlas serve --mcp`）；以及用于对比不同版本之间差异的 API-surface diff 功能（`atlas diff HEAD~5`）。 ## 贡献指南 约定和工作流位于 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [CLAUDE.md](CLAUDE.md) 中；架构决策记录在 [docs/adr/](docs/adr/) 中。构建和测试方法如下： ``` cargo build && cargo test ```

_{MIT © Kenmar}

标签：AI编程辅助, IPv6支持, Rust, SOC Prime, 上下文优化, 代码分析, 凭证管理, 可视化界面, 开发工具, 网络流量审计, 通知系统