As Tral

将代码读取令牌成本降低高达 99%

大多数AI代理以昂贵的方式探索存储库： 打开整个文件>浏览数千行不相关的内容>重复。

ASTral只索引一次代码库，让代理只检索他们需要的确切符号 --函数、类、方法、常量——具有字节级精度。

索引一次。永远低价查询。 精确上下文胜过暴力上下文。

______________________________________________________________________

星的

严重人工智能代理的结构化检索

停止将文件转储到上下文窗口中。开始准确检索代理所需的内容。

ASTral使用树型AST解析对代码库进行一次索引，然后允许MCP兼容的代理（Claude Desktop、VS Code、Google Antigravity等） 按符号发现和检索代码 而不是暴力读取文件。

每个符号存储：

• 签名
• 亲切的
• 限定名
• 单行摘要
• 原始文件的字节偏移量

使用O（1）字节偏移量查找按需检索完整源。

______________________________________________________________________

证据：代币在野外的节省

代表： geekcomputers/Python 尺寸： 338个文件，1422个符号索引 任务： 查找计算器/数学实现

结果： 代币数量减少约80% （效率提高约5倍）

成本随代币而变化。 延迟随无关上下文而变化。

ASTral将搜索转化为导航。

______________________________________________________________________

为什么代理商需要这个

代理商在以下情况下浪费金钱：

• 打开整个文件以查找一个函数
• 重复读取相同的代码
• 使用导入、样板和无关的助手

ASTral提供精确的上下文访问：

• 按名称、种类或语言搜索符号
• 未加载完整内容的大纲文件
• 仅检索精确的符号实现
• 必要时回退到全文搜索

代理不需要更大的上下文窗口。 它们需要结构化检索。

______________________________________________________________________

运作原理

1. 发现 -GitHub API或本地目录行走
2. 安全过滤 --遍历保护、秘密排除、二进制检测
3. 解析 --树型AST提取
4. 存储 --JSON索引+本地存储的原始文件(~/.code-index/)
5. 检索 --通过稳定的符号ID查找O（1）字节偏移量

稳定的符号ID

{file_path}::{qualified_name}#{kind}

示例：

• src/main.py::UserService.login#method
• src/utils.py::authenticate#function

当路径、限定名和类型不变时，ID在重新索引过程中保持稳定。

______________________________________________________________________

用法示例

index_folder: { "path": "/path/to/project" }
index_repo:   { "url": "owner/repo" }

get_repo_outline: { "repo": "owner/repo" }
get_file_outline: { "repo": "owner/repo", "file_path": "src/main.py" }
search_symbols:   { "repo": "owner/repo", "query": "authenticate" }
get_symbol:       { "repo": "owner/repo", "symbol_id": "src/main.py::MyClass.login#method" }
search_text:      { "repo": "owner/repo", "query": "TODO" }

______________________________________________________________________

工具（11）

每个工具响应都包括 _meta 具有时间、代币节省和避免成本的信封：

"_meta": {
  "timing_ms": 4.3,
  "tokens_saved": 48153,
  "total_tokens_saved": 1280837,
  "cost_avoided": { "claude_opus": 0.7223, "gpt5_latest": 0.4815 },
  "total_cost_avoided": { "claude_opus": 19.21, "gpt5_latest": 12.81 }
}

total_tokens_saved 和 total_cost_avoided 在所有工具调用中累积并持续 ~/.code-index/_savings.json.

______________________________________________________________________

支持的语言

\* .h 首先被解析为C++，然后在没有提取C++符号时回退到C。

看 语言支持 为了获得完整的语义。

______________________________________________________________________

安全

内置保护：

• 路径遍历预防（所有者/名称净化+验证的解析路径）
• Symlink逃生保护
• 机密文件排除(.env, *.pem等等）
• 二进制检测
• 可配置的文件大小限制

看 安全 了解详情。

______________________________________________________________________

技术栈

______________________________________________________________________

最佳使用案例

• 大型多模块存储库
• 代理驱动重构
• 建筑探索
• 更快的入职流程
• 令牌高效多代理工作流

______________________________________________________________________

安装

作为一个。NET全局工具

dotnet tool install -g ASTral

然后运行：

astral

来源

git clone https://github.com/Atypical-Consulting/ASTral.git
cd ASTral
dotnet build
dotnet run --project src/ASTral

______________________________________________________________________

配置

ASTral可以通过环境变量进行配置 .astralrc JSON配置文件，或两者兼而有之。

环境变量

配置文件(.astralrc)

地点a .astralrc 项目目录或主目录中的JSON文件(~/.astralrc).项目级值覆盖主级值。环境变量会覆盖这两者。

{
  "storage_path": "/custom/index/path",
  "log_level": "DEBUG",
  "max_index_files": 5000,
  "extra_extensions": ".vue:javascript,.svelte:javascript",
  "excluded_patterns": ["*.generated.cs", "*.Designer.cs"]
}

______________________________________________________________________

高级功能

强制重新索引

两者 index_repo 和 index_folder 接受一个 force 参数以绕过增量缓存并执行完全重新索引：

{ "path": "/path/to/project", "force": true }

定时元数据

索引工具的响应包括时间细分：

{
  "parse_time_ms": 120,
  "save_time_ms": 45,
  "total_time_ms": 165
}

文件监视器（选择加入）

集 ASTRAL_WATCH=true 当索引的本地文件夹中的文件发生更改时，启用自动后台重新索引。观察器使用去抖动检测（500ms）和信号量来防止并发索引。

______________________________________________________________________

不适用于

• LSP诊断或完成
• 编辑工作流程
• 跨存储库全局索引
• 语义程序分析

______________________________________________________________________

文档

• 用户指南 --安装、配置、工作流和故障排除
• 建筑 --项目结构、数据流和设计决策
• 技术规范 --工具、数据模型和响应格式
• 安全 --路径遍历、秘密排除和其他保护
• 语言支持 --支持的语言、符号类型以及如何添加新的
• 代币节省 --基准和节约方法

______________________________________________________________________

起源和归属

ASTral是一个。NET重写 jCodeMunch MCP 通过 J.格拉夫勒最初是用Python编写的。

该衍生作品包括以下修改：

• 从Python到C#的完全重写。净值10
• 添加了Kotlin语言支持（.kt、.kts）
• 添加了配置文件支持（.astralrc）
• 添加了结构化日志记录（Microsoft.Extensions.logging）
• 添加了用于自动重新索引的文件监视器
• 添加了带有定时元数据的强制重新索引参数
• 添加了NuGet全局工具包
• 添加了工具集成测试（xunit v3）
• 各种错误修复和性能改进

许可证（双重用途）

此存储库是 免费用于非商业用途 根据J.Gravelle的原始两用许可证。 商业使用需要付费的商业许可证 --看 许可证 完整条款。

• 原创作品：版权所有（c）2026 J.Gravelle
• 修改：版权所有（c）2026 Philippe Matray/非典型咨询

如需商业许可咨询，请联系：j@gravelle.us|https://j.gravelle.us