AgentNavi v0.2.0 — First Release

AgentNavi v0.2.0

这是 AgentNavi 的第一个 GitHub Release。

AgentNavi 是一个独立于项目仓库、具体 Agent 和 Obsidian 的项目上下文导航引擎：让 Codex、Claude Code、DeepSeek Harness 等 Agent 在开始工作前，先知道应该读什么、为什么相关、过去发生过什么。

核心能力

• L1 物理图：索引文件、导入、引用、测试关系和文件内部资源；
• L2 语义图：把分散文件组织为业务概念，并支持外部语义提供器与人工 Overlay；
• L3 任务图：记录任务、读取、修改、搜索、测试与结果，形成可跨会话复用的项目记忆；
• 上下文路由：提供 context、impact、history 查询，默认沿“任务 → 概念 → 文件 → 一跳依赖 → 历史”缩小探索范围；
• 增量扫描：Git 感知地更新项目索引，而不是每次重新遍历整个项目。

可靠性

• L3 使用 ~/.agentnavi/events.jsonl 作为追加式权威事件日志；
• 支持日志校验、旧数据回填和 SQLite 丢失后的幂等重放；
• L2 人工接受、拒绝、重命名、合并和文件映射持久化到 semantic-overlays.jsonl；
• 自动语义图可以重建，但人工判断不会被扫描覆盖。

Agent 集成

DeepSeek Harness

首版已经包含完整的本地插件闭环：

• Local Provider；
• agentnavi_context；
• agentnavi_impact；
• agentnavi_history；
• agentnavi_scan；
• agent/pre-step 自动上下文注入；
• session/event → AgentNavi L3 事件桥。

Codex / Claude Code

支持全局 Hook 与“上下文优先”Skill：

agentnavi integration install codex
agentnavi integration install claude

文件与数据格式

在基础 Python、JavaScript、TypeScript、Markdown 之外，本版进一步扩展了：

• Go、Rust、Java、Kotlin、C、C++、C#、Ruby、PHP、Swift、Shell、Lua；
• JSON、YAML、TOML、INI、XML、CSV、TSV、SQL；
• Jupyter Notebook、XLSX；
• NPY、NPZ、SQLite；
• 可选支持 Parquet、Arrow、HDF5、NetCDF、MAT、FITS。

大型二进制、压缩包和流式文本均设置了解析预算，科学数据格式以元数据优先方式读取。

基准测试

仓库内置的 observed benchmark 测试夹具中：

baseline：10,000 探索 Token
AgentNavi：2,500 探索 Token
节省：7,500 Token
降幅：75%
必要文件召回率：双方均为 100%
任务状态：双方均为 success

这组数据用于验证 benchmark 的质量门槛与 reduction 计算逻辑，不是模型供应商的生产账单，也不代表所有项目固定节省 75%。

正式节省只有在 baseline 与 AgentNavi 两侧必要文件召回率均至少 95%，且双方任务均成功时才会计入。

安装

要求 Python 3.11+：

git clone https://github.com/Andrewlislin/AgentNavi.git
cd AgentNavi
python -m pip install -e .
agentnavi init

进入项目后：

agentnavi project add .
agentnavi context "你的任务"

开源许可证

从本版本起，AgentNavi 使用 Apache License 2.0。

当前阶段

v0.2.0 仍是 Alpha 版本。当前以本地优先、单机上下文基础设施为主；远程沙箱、HTTP/MCP Context Service、跨项目 Work Graph 和图形化语义审查仍属于后续路线。