agent-coderag Skill 技能

技能简介

agent-coderag 是一款专为 AI 编程 Agent 打造的本地语义代码搜索与知识蒸馏工具。它解决了 AI Agent 最核心的痛点：训练数据过时导致的 API 调用幻觉。不同于传统的关键词搜索或向量检索，agent-coderag 通过实时解析本地代码库的 API 签名、函数意图和技术上下文，将 Agent 需要阅读的上万行原始代码压缩为精确的语义摘要，注入到模型上下文窗口中，从根源上消除幻觉。

核心能力

• API 知识桥接：实时从本地代码库提取 6 大主流生态（Python/Java/Go/TypeScript/Rust/C#）的公共 API 签名，让 Agent 看到的是真实安装版本的接口，而非训练数据中的旧版文档
• 多语言树解析器：基于 Tree-Sitter 的统一解析引擎，支持 25 种以上编程语言，精准识别类、方法及其导入关系
• 上下文压缩：将 10,000 行原始代码压缩为约 200 token 的语义摘要，大幅降低上下文消耗
• 本地向量检索：使用本地 ONNX 模型生成 384 维向量，存入高性能 DuckDB 向量索引，实现亚毫秒级相似度搜索
• 零 PyTorch 开销：完全基于 onnxruntime 和 Rust 底层 tokenizers，冷启动速度极快
• 离线优先：所有嵌入和数据留在本地机器，不依赖云端
• Agent 原生协议：输出 JSON 格式，可被 Claude Code/Cursor/Copilot 等主流 Agent 直接调用

安装配置

pip install agent-coderag
pip install tree-sitter-python tree-sitter-javascript

使用步骤

1. 初始化设置：下载预训练多语言嵌入模型（约 130MB）

   agent-coderag setup

2. 配置 LLM 提供商（可选）

   agent-coderag config --url "http://localhost:11434" --provider "ollama" --model "qwen2.5-coder"

3. 建立代码索引

   agent-coderag sync --all

4. 执行语义搜索

   agent-coderag search "authentication middleware 是如何工作的？"

5. 验证 API 签名

   agent-coderag api requests --lang python

适用场景

• 代码审查：避免 API 幻觉，确保 AI 修改代码时调用的是真实安装版本的接口
• 遗留代码维护：快速提取真实签名和依赖关系，降低理解成本
• 跨语言代码库：同时处理多语言项目，统一语义索引
• AI 编程教育：帮助学习者理解真实项目中的 API 用法
• 团队知识沉淀：将分散在各语言代码中的业务逻辑提取为可检索的语义摘要

适用人群

• 日常使用 Claude Code / Cursor / Copilot 等 AI 编程工具的开发者
• 需要维护大型多语言代码库的团队
• 对 AI 生成代码质量有较高要求的工程师

工作原理

agent-coderag 通过四阶段管道构建代码语义地图：结构解析 → 技术蒸馏 → 向量化（本地 ONNX） → DuckDB VSS 向量索引检索。

官方链接

• PyPI：https://pypi.org/project/agent-coderag/
• GitHub：https://github.com/naranor/agent-coderag