AI导哈

AI编码代理技能懒加载服务

Brain是一个为AI编码代理设计的懒加载技能服务，通过MCP服务器实现按需加载技能片段，显著减少上下文令牌使用，提升效率。

  • by Raulvalverdeleal
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 Raulvalverdeleal/brain

使用说明

脑

AI编码代理技能的延迟加载。 一个令牌高效的MCP服务器，让代理在需要时只获取他们需要的技能部分，而无需将整个技能库加载到上下文中。

每个技能都是一个文件夹 SKILL.md 这告诉代理如何处理特定任务——使用什么工具，遵循什么模式，注意什么。技能是通过MCP服务器逐步加载的，而不是一次全部拉入上下文。

一种标准格式。任何型号。任何IDE。零上下文膨胀。

基准测试

相同的任务，相同的项目，相同的提示-API文档加载了两种技能。

大脑（MCP） 原始标记文件
上下文令牌 20000 150000
成本 0.03美元 0.24美元
新增行数 876 693
删除行 161 90

大脑使用 代币减少86% 同时生产 产量增加26%。代理通过渐进式披露只获取了所需的部分，从未加载完整的技能文件。

运作原理

技能生活 ~/.agents/skills/ 但是 代理不得直接访问此目录相反，他们使用MCP服务器(brain_mcp.py)只在需要时获取所需内容，而不将整个文件加载到上下文中。

为什么这很重要： 将所有技能加载到上下文中会浪费令牌并降低性能。Brain的渐进式披露确保了代理只获取相关部分，从而将上下文使用率降低了86%。

安全说明： 您应该拒绝代理访问 ~/.agents/skills 并禁用任何直接技能加载工具。技能必须始终通过MCP服务器访问，以保持令牌效率。

CLI(brain)处理注册表管理：远程同步、搜索和组织技能。

~/.brain/
├── brain_mcp.py         ← MCP server (agent access layer)
├── brain_cli.py         ← CLI tool for registry management
├── index.json           ← pre-built frontmatter index
└── scripts/
    └── build_index.py   ← called by brain sync to regenerate index.json

~/.agents/
└── skills/              ← all available skills (agents must NOT access directly)
    ├── frontend-design/
    │   └── SKILL.md
    └── ...

设置

1.克隆注册表

git clone https://github.com/Raulvalverdeleal/brain ~/.brain

2.安装 brain

brain 是用于注册表管理的CLI。在全球范围内提供：

# Option 1: Create an alias
echo 'alias brain="python3 ~/.brain/brain_cli.py"' >> ~/.zshrc
source ~/.zshrc

# Option 2: Create a symlink in your PATH
ln -s ~/.brain/brain_cli.py /usr/local/bin/brain

3.构建索引

brain build-index

这会一次性解析所有技能前沿内容并写入 ~/.brain/index.jsonMCP服务器在启动时加载此文件，而不是扫描数百个文件——启动时间从几秒到几毫秒不等。

brain 需要Python 3。标准库之外没有依赖关系。

4.注册MCP服务器

添加到MCP配置中（例如。 claude_desktop_config.json, opencode.json等等）：

{
  "mcpServers": {
    "brain": {
      "command": "python3",
      "args": ["~/.brain/brain_mcp.py"]
    }
  }
}

或者对于基于stdio的传输：

{
  "mcp": {
    "brain": {
      "command": "python3",
      "args": ["~/.brain/brain_mcp.py"]
    }
  }
}

服务器自动安装其唯一的依赖项(mcp[cli])第一次跑步。

5.保护您的设置（重要）

永远不要让代理访问 ~/.agents/skills 直接。 这样做会击败懒惰加载，并通过将所有技能加载到上下文中来浪费令牌。

要执行此操作：

  1. 拒绝文件系统访问 到 ~/.agents/skills 在您的代理配置中
  2. 禁用直接技能加载工具 如果你的平台有它们
  3. 添加到您的全球AGENTS.md：
    - Do not access skills via `/Users/username/.agents/skills` use always brain mcp server instead.
  4. 仅暴露Brain MCP服务器 对于技能访问，它自动处理渐进式披露

CLI参考

brain sync                       Pull registry and rebuild index if changed
brain search <query> [--page N]  Search skills  (prefix terms with - to exclude)
brain info   <skill>             Show metadata and file tree for a skill
brain list                       List all skills in the registry

示例：

brain sync
brain search "react state management"
brain search frontend -azure --page 2
brain info   react-best-practices
brain list

同步

跑 git pull。如果检测到变化，或者 index.json 缺失——它会自动重建索引。如果注册表已经是最新的，它将打印索引统计数据并退出。

● Syncing ~/.brain ...
✓ Already up to date.
──────────────────────────────────────────────────
   index    2025-01-05T10:22:11Z  943 skills
   no changes — index up to date

搜索

根据您的查询对技能进行评分，并返回排名结果（通过MCP每页3个，通过CLI每页5个）。名称匹配得分最高，然后是关键字，然后是描述。使用 -term 以排除噪声结果。

brain search "react state"
brain search postgres -azure -cloud
brain search "api design" --page 2

信息

显示技能的完整元数据：描述、关键字、依赖关系、文件树。

brain info postgres-best-practices

MCP服务器工具

MCP服务器提供了七种渐进式技能访问工具。代理仅在需要时移动级别-- 一个典型的会话花费约400个代币，而2000个代币+ 冷加载完整的技能文件。

skill_search    → find candidates (paginated, ranked)
skill_info      → frontmatter + file tree, zero content cost
skill_toc       → heading tree only, up to 5 skills at once
skill_section   → one section by slug
skill_get       → full SKILL.md content
skill_get_file  → any supporting file (references/, scripts/)
skill_index_status → health check, force reload after sync

渐进式披露流程

agent: skill_search("figma design implementation")
→ 3 results, page 1 of 2

agent: skill_info("figma-implement-design")
→ frontmatter + file tree (no content loaded)

agent: skill_toc("figma-implement-design")
→ heading tree with slugs, dependency TOCs appended

agent: skill_section("figma-implement-design", "phase-3-design-tokens")
→ only that section

技能搜索

跨所有技能的分页搜索。通过MCP服务器每页返回3个结果（通过CLI每页返回5个结果）。支持负过滤。

query: "figma design"  matches:4  page:1/2

→ call skill_search(query='figma design', page=2) for more

■ figma-implement-design  (score:14)
  Full workflow to go from a Figma file to production-ready code...

技能_toc

将一个或多个技能的标题树作为可寻址的蛞蝓返回。在一次通话中传递最多5个ID，以预先计划您的部门获取。

■ figma-implement-design

#phase-1-orient  Phase 1 — Orient
#phase-2-visual-reference  Phase 2 — Visual reference
  #phase-3-design-tokens  Phase 3 — Design tokens
  ...

supporting files:
  references/advanced-patterns.md

依赖TOC已列出，但不会自动展开——如果需要，代理会明确请求它们。

技能专区

将内容从一个标题提取到下一个相同或更高级别的标题。主要的效率工具——使用它而不是 skill_get 只要有可能。

skill_section("figma-implement-design", "phase-3-design-tokens")

技能信息

返回内容成本为零的frontmatter元数据和文件树。如果 skills.json 存在于项目中 notes 对于此技能，它们会自动附加。

技能如何发挥作用

当代理接收到任务时，它使用 skill_search 找到相关技能，然后通过以下方式逐步加载内容 skill_toc 和 skill_section。代理获取 skill_get 只有当它需要完整的文档时。

技能是有意独立的——你只加载任务所需的内容。

技能结构

~/.agents/skills/
└── your-skill-name/
    ├── SKILL.md          ← required
    ├── references/       ← optional: supplementary docs
    └── scripts/          ← optional: helper scripts

所需正面材料

每 SKILL.md 必须以YAML frontmatter块开头：

---
name: your-skill-name
description: One or two sentences. When should an agent use this skill?
keywords: react ui components typescript
---

name 和 description 是必需的。 keywords 是可选的，但可以提高搜索排名和相关性解析。

index.json

index.json 由生成 build_index.py 并且是MCP服务器的数据源。它包含每种技能的解析前体，但从不包含全部内容。在任何情况下重建它 brain sync 这会带来变化。

{
  "_meta": {
    "built_at": "2025-01-05T10:22:11Z",
    "skill_count": 943
  },
  "skills": {
    "frontend-design": {
      "name": "frontend-design",
      "description": "...",
      "keywords": ["react", "ui", "css"],
      "file_tree": ["SKILL.md"],
      "has_references": false,
      "has_scripts": false
    }
  }
}

# 所有人

  • []添加技能时构建索引/在mcp启动时重新构建索引。

相关 MCP