agentsbestfriend

AgentsBestFriend (abf)

为你的 AI 编码 Agent 注入超能力——一个本地 MCP 服务，可快速、节省令牌地进行代码导航、搜索和分析。

适用于 VS Code Copilot、Cursor、Claude Code/Desktop、Codex、Cline、Zed、Gemini CLI、Goose、OpenCode，以及任何其他兼容 MCP 的 Agent。

---

为什么？

AI 编码 Agent 会浪费令牌，反复读取文件并盲目搜索。ABF 提供专用工具，只返回它们真正需要的信息——以紧凑、结构化的响应保留上下文。

工具

工具	功能
abf_search	代码搜索——精确搜索（ripgrep）、关键词排序搜索或语义搜索（基于嵌入）
abf_search_multi	一次调用运行多个搜索查询（精确／关键词／语义），并合并加权评分
abf_symbols	查找文件中的函数、类和导出项（TS/JS 使用基于 AST 的分析，Python 使用正则表达式）
abf_chunk	按符号名称、块索引或文件概览智能分块文件
abf_project_overview	一览技术栈、文件夹结构和关键依赖项
abf_dependencies	导入关系图——谁导入了什么
abf_impact	查找项目中某个符号的所有用法
abf_impact_typed	基于 AST（ts-morph）的影响分析，可分类引用（定义／调用／导入／类型引用／jsx）并给出置信度
abf_blast_radius	对文件的反向导入关系图进行广度优先搜索，并评估风险（低／中／高）
abf_related_tests	根据启发式规则，为文件或符号最可能对应的测试文件排序
abf_preview_changes	只读预览：差异 + 符号／导入变更 + 风险标记 + 外部用法探测（不写入）
abf_refactor_plan	针对重命名／移动／提取／拆分的只读有序编辑计划，并检测冲突
abf_apply_edit	写入工具——通过 sha256 哈希检查进行原子文件写入（除非设置 ABF_ENABLE_WRITES=1，否则禁用）
abf_diagnostics	针对单个文件或所有已跟踪 TS/JS 文件的 TypeScript 诊断（错误／警告）
abf_definition	通过 TypeScript 语言服务跳转到定义——文件、行范围和源代码预览
abf_hover	标识符的类型签名 + JSDoc（IDE 样式悬停）
abf_call_graph	函数或方法的传递调用者／被调用者（TS/JS、ts-morph）
abf_git	Git 日志、blame、差异（最近／已暂存／未暂存）
abf_file_summary	在 LLM 生成的文件摘要中进行全文搜索（FTS5，OR/AND 模式）
abf_conventions	检测到的命名、结构和格式约定
abf_index	索引状态、重建、增量更新或触发重新生成摘要
abf_ping	健康检查——返回版本和项目根目录

安装

npm install -g agentsbestfriend

前置条件

• Node.js ≥ 20
• ripgrep——brew install ripgrep（macOS）／apt install ripgrep（Linux）
• git
• Ollama（可选）——用于生成摘要和语义搜索：ollama.com

快速开始

abf init

abf init 会引导你完成所有操作：

1. 为项目建立索引——通过 git ls-files 发现所有文件并为其建立索引
2. 生成 LLM 摘要和嵌入（如果 Ollama 正在运行）——实时显示 (12/80) 进度
3. 将 .abf/ 添加到 .gitignore——写入前会征求确认
4. 为你的 Agent 安装 ABF 作为 MCP 服务——选择要配置的 Agent（Cursor、VS Code、Claude Code 等），以及使用 npx agentsbestfriend start（始终运行最新版）还是 abf start（本地安装）

手动配置 Agent

如果你更喜欢手动配置，可以将 ABF 添加为 stdio MCP 服务。建议使用 npx——无需全局安装，即可始终运行最新发布版本：

VS Code / GitHub Copilot（.vscode/mcp.json）：

{
  "servers": {
    "abf": {
      "command": "npx",
      "args": ["agentsbestfriend", "start"]
    }
  }
}

Cursor（.cursor/mcp.json）：

{
  "mcpServers": {
    "abf": {
      "command": "npx",
      "args": ["agentsbestfriend", "start"]
    }
  }
}

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "abf": {
      "command": "npx",
      "args": ["agentsbestfriend", "start"]
    }
  }
}

如果 Agent 不会自动传入其工作目录，请在 env 块中设置 ABF_PROJECT_ROOT。

CLI 命令

abf start             Start MCP server in stdio mode (used by agents)
abf init [path]       Index project, set up .gitignore entry, install MCP for agents
abf skill [path]      Install or update the ABF workflow skill for your coding agents
abf index [path]      Re-index a project (incremental by default)
abf status [path]     Show index stats
abf config            Interactive configuration editor
abf doctor            Health checks (Node, ripgrep, git, Ollama)
abf portal            Interactive TUI dashboard

工作原理

ABF 会在每个项目根目录中维护一个轻量级 SQLite 索引（.abf/index.db）。索引只需构建一次，之后会增量更新——仅重新处理有变更的文件。文件监视器会在你编辑时保持索引最新。

表	内容
files	路径、哈希、语言、行数、LLM 摘要
symbols	函数、类、接口、类型（通过 AST 提取）
imports	文件之间的依赖关系
embeddings	用于语义搜索的 Float32 向量（大型文件会分块）
file_chunks	与符号边界对齐的智能分块
files_fts	对摘要建立的 FTS5 全文索引

可选：LLM 增强

在本地运行 Ollama 后，ABF 会生成文件摘要和嵌入：

ollama pull qwen2.5-coder:1.5b    # file summaries
ollama pull nomic-embed-text       # embeddings / semantic search

abf init 和 abf portal → Re-index 都会显示实时进度：

◆  Generating LLM summaries... (14/80)
◆  Generating embeddings... (28/80)

大型文件会自动拆分为多个分块以生成嵌入——不会出现上下文长度错误。

不使用 Ollama 时，所有工具仍可正常运行。语义搜索会回退到关键词模式。

配置

全局配置位于 ~/.abf/config.json。使用 abf config 或通过 abf portal 进行交互式编辑。

{
  "llm": {
    "provider": "ollama",
    "ollama": {
      "baseUrl": "http://localhost:11434",
      "summaryModel": "qwen2.5-coder:1.5b",
      "embeddingModel": "nomic-embed-text"
    }
  },
  "indexing": {
    "autoWatch": true,
    "respectGitignore": true,
    "maxFileSizeKb": 512,
    "excludedPatterns": ["*.min.js", "*.min.css", "*.map", "*.lock"]
  },
  "search": {
    "defaultMaxResults": 20
  }
}

架构

AgentsBestFriend/
├── packages/
│   ├── core/     Shared logic — DB, config, search, analysis, indexer, LLM
│   ├── server/   MCP server (11 tools)
│   └── cli/      Commander.js CLI + TUI portal
├── turbo.json
└── package.json

使用 Turborepo + pnpm 工作区构建。核心模块：

模块	用途
@abf/core/db	Drizzle ORM + SQLite（WAL、FTS5）
@abf/core/config	经 Zod 验证的配置
@abf/core/search	ripgrep、关键词评分器、语义搜索（余弦相似度）
@abf/core/analysis	ts-morph AST、惯例检测器、项目概览
@abf/core/indexer	通过 git ls-files 发现文件、增量处理流水线、文件监视器
@abf/core/llm	Ollama 客户端、摘要与分块嵌入流水线
@abf/core/git	Git CLI 封装

开发

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Watch mode
pnpm dev

# Type-check
pnpm type-check

链接

• GitHub：github.com/TheRealFloatDev/AgentsBestFriend
• npm：npmjs.com/package/agentsbestfriend
• 问题反馈：github.com/TheRealFloatDev/AgentsBestFriend/issues
• MCP 规范：modelcontextprotocol.io

许可证

MIT