将代码读取令牌成本降低高达 99%
大多数AI代理以昂贵的方式探索存储库： 打开整个文件>浏览数千行不相关的内容>重复。
ASTral只索引一次代码库，让代理只检索他们需要的确切符号 --函数、类、方法、常量——具有字节级精度。
| 任务 | 传统方法 | 使用ASTral |
|---|---|---|
| 查找函数 | ~40000个标记 | ~200个标记 |
| 了解模块API | 约15000个代币 | 约800个代币 |
| 探索回购结构 | 约200000个代币 | 约2k个代币 |
索引一次。永远低价查询。 精确上下文胜过暴力上下文。
______________________________________________________________________
星的
严重人工智能代理的结构化检索
停止将文件转储到上下文窗口中。开始准确检索代理所需的内容。
ASTral使用树型AST解析对代码库进行一次索引，然后允许MCP兼容的代理（Claude Desktop、VS Code、Google Antigravity等） 按符号发现和检索代码 而不是暴力读取文件。
每个符号存储：
- 签名
- 亲切的
- 限定名
- 单行摘要
- 原始文件的字节偏移量
使用O（1）字节偏移量查找按需检索完整源。
______________________________________________________________________
证据：代币在野外的节省
代表： geekcomputers/Python 尺寸： 338个文件，1422个符号索引 任务： 查找计算器/数学实现
| 方法 | 令牌 | 代理必须做什么 |
|---|---|---|
| 原始文件方法 | ~7500 | 打开多个文件并手动扫描 |
| ASTral | ~ 1449 | search_symbols() > get_symbol() |
结果： 代币数量减少约80% （效率提高约5倍）
成本随代币而变化。 延迟随无关上下文而变化。
ASTral将搜索转化为导航。
______________________________________________________________________
为什么代理商需要这个
代理商在以下情况下浪费金钱：
- 打开整个文件以查找一个函数
- 重复读取相同的代码
- 使用导入、样板和无关的助手
ASTral提供精确的上下文访问：
- 按名称、种类或语言搜索符号
- 未加载完整内容的大纲文件
- 仅检索精确的符号实现
- 必要时回退到全文搜索
代理不需要更大的上下文窗口。 它们需要结构化检索。
______________________________________________________________________
运作原理
- 发现 -GitHub API或本地目录行走
- 安全过滤 --遍历保护、秘密排除、二进制检测
- 解析 --树型AST提取
- 存储 --JSON索引+本地存储的原始文件(
~/.code-index/) - 检索 --通过稳定的符号ID查找O（1）字节偏移量
稳定的符号ID
{file_path}::{qualified_name}#{kind}示例：
src/main.py::UserService.login#methodsrc/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）
| 工具 | 目的 |
|---|---|
index_repo | 为GitHub存储库建立索引 |
index_folder | 为本地文件夹建立索引 |
list_repos | 列出索引存储库 |
get_file_tree | 存储库文件结构 |
get_file_outline | 文件的符号层次结构 |
get_symbol | 检索完整符号源 |
get_symbols | 批量检索符号 |
search_symbols | 使用过滤器搜索符号 |
search_text | 全文搜索 |
get_repo_outline | 高级回购概述 |
invalidate_cache | 删除缓存索引 |
每个工具响应都包括 _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.
______________________________________________________________________
支持的语言
| 语言 | 扩展名 | 符号类型 |
|---|---|---|
python .py | 函数、类、方法、常量、类型 | |
| JavaScript | .js, .jsx | 函数、类、方法、常量 |
| TypeScript | .ts, .tsx | 函数、类、方法、常量、类型 |
| 去吧 | .go | 函数、方法、类型、常量 |
| 生锈 | .rs | 函数、类型、impl、常量 |
Java .java | 方法、类、类型、常量 | |
| Kotlin | .kt, .kts | 函数、类、对象、类型 |
| PHP | .php | 函数、类、方法、类型、常量 |
| 飞镖 | .dart | 函数、类、方法、类型 |
C .cs | 类、方法、类型、记录 | |
C .c | 函数、类型、常数 | |
C .cpp, .cc, .cxx, .hpp, .hh, .hxx, .h\* | 函数、类、方法、类型、常量 | |
| Swift | .swift | 函数、类、类型 |
| 灵丹妙药 | .ex, .exs | 类（模块/impl）、类型（协议/@type/@回调）、方法、函数 |
| 红宝石 | .rb, .rake | 类、类型（模块）、方法、函数 |
| Perl | .pl, .pm | 函数、类（包） |
\* .h 首先被解析为C++，然后在没有提取C++符号时回退到C。
看 语言支持 为了获得完整的语义。
______________________________________________________________________
安全
内置保护：
- 路径遍历预防（所有者/名称净化+验证的解析路径）
- Symlink逃生保护
- 机密文件排除(
.env,*.pem等等） - 二进制检测
- 可配置的文件大小限制
看 安全 了解详情。
______________________________________________________________________
技术栈
| 组件 | 技术 |
|---|---|
| 运行时 | 。净值10 |
| 语言 | C# |
| MCP框架 | 模型上下文协议 |
| AST解析 | TreeSitter。DotNet |
| .gitignore | MAB。点忽略 |
| 人工智能概述 | 人类学（克劳德·海库） |
| 托管 | 微软。扩展。托管服务 |
| Testing | xunit v3 |
| 日志 | 微软。扩展。日志记录 |
______________________________________________________________________
最佳使用案例
- 大型多模块存储库
- 代理驱动重构
- 建筑探索
- 更快的入职流程
- 令牌高效多代理工作流
______________________________________________________________________
安装
作为一个。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配置文件，或两者兼而有之。
环境变量
| 变量 | 描述 | 默认值 |
|---|---|---|
CODE_INDEX_PATH | 索引存储目录 | ~/.code-index/ |
ASTRAL_LOG_LEVEL | 日志级别： DEBUG, INFO, WARNING, ERROR | WARNING |
ASTRAL_EXTRA_EXTENSIONS | 额外的扩展映射（例如。 .vue:javascript,.svelte:javascript) | — |
ASTRAL_WATCH | 启用文件监视器以自动重新索引(true/false) | false |
GITHUB_TOKEN | 的GitHub API令牌 index_repo | — |
ANTHROPIC_API_KEY | 人工智能摘要的Anthropic API密钥 | - |
配置文件(.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