代码库智能分析工具

贝雷帽

一种代码库智能工具，用于构建内存中的RDF知识图，并通过CLI命令、MCP工具和SPARQL查询将其公开。它使用结构化AST分析解析17种编程语言，从配置文件和文档中提取元数据，为人类活动分析的git历史建立索引，检测工程实践，并生成架构图。

安装

发布配置文件支持LTO和单个编码器单元，以实现最大的二进制性能。

用法

贝雷帽有三种操作模式： 命令行界面 为了直接分析， MCP 工作站 用于AI工具集成，以及 HTTP MCP 用于远程访问。

CLI模式

直接从终端运行分析命令。每个命令都对目标目录进行索引，并将JSON打印到stdout。

beret describe                     # consolidated project analysis
beret activity                     # git contributors, active files, recent commits
beret testing                      # test frameworks, test ratio
beret architecture                 # layers, structure counts
beret dependencies                 # package managers, dep count
beret practices                    # all detected engineering practices
beret stats                        # counts by structure type
beret find main                    # find symbols named "main"
beret diagram                      # generate LikeC4 architecture diagram
beret query 'SELECT ?f WHERE { ?f <http://repo.example.org/a> <http://repo.example.org/Function> }'

所有命令都接受可选 [PATH] 参数（默认为当前目录）：

beret describe /path/to/project
beret activity ~/repos/my-app

使用 --exclude 在使用gitignore样式模式进行索引时跳过路径（可重复）：

beret describe --exclude node_modules --exclude target
beret stats --exclude '*.generated.*' --exclude vendor/
beret describe /path/to/project --exclude dist --exclude .cache

MCP服务器模式

服务器从一个空的知识图和按需索引开始。呼叫 refresh_index 使用目录路径填充图形，然后使用其他工具进行探索。这使您可以启动一个服务器，并在工作时将其重新定位到不同的项目或子目录。

可选 [PATH] 论点（例如。， beret /path/to/project)为设置默认目录 refresh_index 当呼叫时没有路径。如果省略，则默认为当前工作目录。

在stdio模式下， --exclude 在命令行上传递的模式作为默认值应用于每个 refresh_index 电话。其他模式可以通过 exclude 刀具参数。

MCP客户端配置

所有条目都放置在

{
  "mcpServers": {
    "beret": ...
  }
}

在您的客户端配置中（例如。， mcp.json, claude_desktop_config.json).

连接后，要求代理为目录建立索引（例如，“为当前项目建立索引”），或者为远程HTTP建立存储库（例如https://github.com/user/repo").

工具

所有列表返回工具支持 limit, offset，以及 exclude 参数。 exclude 采用逗号分隔的目录名称列表进行过滤（例如。， "docs,stories,dist").当结果超过限制时，响应包括 has_more: true 和 next_offset 用于分页。

勘探工具

调用图工具

依赖关系和配置工具

代码搜索工具

可视化工具

• depth: 0 =自动（默认）， 1 =目录， 2 =+个文件， 3 =+函数/类
• code_only: true （默认）--不包括文档、配置、二进制文件、测试目录、故事等。
• exclude：逗号分隔的目录名要额外排除
• 贝雷帽主题：自定义颜色（海军蓝 #00005F，橙色 #F5921B，黄金 #FFCC17，青色 #37A3A3，蓝色 #0066CC)，每个元素类型的不同形状，样式关系箭头
• 输出：粘贴到 游乐场.likec.dev，另存为 .c4，或使用渲染 npx likec4

实践和项目分析工具

索引管理工具

分页

当结果被分页时，响应会用元数据包装结果：

{
  "results": [...],
  "total": 1847,
  "returned": 200,
  "offset": 0,
  "has_more": true,
  "next_offset": 200,
  "message": "Showing 1–200 of 1847 results. Use offset: 200 to see the next page."
}

search_pattern 例子

查找所有Rust函数：

pattern: "fn $NAME($$$ARGS) { $$$BODY }"
language: "rust"

查找JavaScript中的所有console.log调用：

pattern: "console.log($MSG)"
language: "javascript"

查找从基类继承的Python类：

pattern: "class $NAME($BASE): $$$BODY"
language: "python"

query_codebase SPARQL示例

所有IRI都使用 repo: 前缀，扩展为 http://repo.example.org/.

列出所有功能：

SELECT ?func WHERE {
  ?func <http://repo.example.org/a> <http://repo.example.org/Function>
}

查找函数的所有调用者：

SELECT ?caller WHERE {
  ?caller <http://repo.example.org/calls> <http://repo.example.org/process>
}

查找所有依赖项：

SELECT ?file ?dep WHERE {
  ?file <http://repo.example.org/dependsOn> ?dep
}

查找测试函数（基于注释或路径）：

SELECT ?func WHERE {
  ?func <http://repo.example.org/isTestFunction> <http://repo.example.org/true>
}

查找最近提交的作者：

SELECT ?author ?date ?message WHERE {
  ?commit <http://repo.example.org/commitAuthor> ?author .
  ?commit <http://repo.example.org/commitDate> ?date .
  ?commit <http://repo.example.org/commitMessage> ?message
} ORDER BY DESC(?date) LIMIT 10

查找修改最多的文件：

SELECT ?file ?count WHERE {
  ?file <http://repo.example.org/commitCount> ?count
} ORDER BY DESC(?count) LIMIT 20

列出MIME类型的二进制文件：

SELECT ?file ?mime WHERE {
  ?file <http://repo.example.org/a> <http://repo.example.org/Binary> .
  ?file <http://repo.example.org/hasMimeType> ?mime
}

检查是否存在任何呼叫关系：

ASK { ?a <http://repo.example.org/calls> ?b }

知识图谱

代码结构

受试者通过文件路径进行资格认证（例如。， src/main.rs/handle_request).呼叫目标是不合格的被叫方名称。对于以下方法调用 obj.method()，仅 method 被记录下来。对于命名空间呼叫，如 mod::func()，仅 func 被记录下来。

试验检测：功能通过以下方式标记为测试 @Test/@ParameterizedTest/@RepeatedTest 注释（Java）， [TestMethod]/[Fact]/[Theory]/[Test] 属性（C#），或位于测试目录中时(/test/, /tests/, /__tests__/, /spec/).

配置文件（JSON、YAML）

文档（Markdown、HTML、AsciiDoc、重新结构化文本、手册页）

样式表（CSS）

二进制文件

Git活动

索引来自 git log 输出（最后500次提交）。即使不是git repo，也很优雅地跳过了。

支持的语言

非代码文件

二进制文件（仅元数据）

图片(.png, .jpg, .gif, .webp, .svg, .ico, .bmp)，音频(.mp3, .wav, .ogg, .flac, .aac)，视频(.mp4, .webm, .avi, .mov, .mkv)，字体(.ttf, .otf, .woff, .woff2)，文件(.pdf)，档案(.zip, .gz, .tar)，可执行文件(.exe, .dll, .so, .dylib, .wasm)，数据库(.sqlite, .db).

生成文件依赖关系提取

从20多种构建文件格式中提取依赖关系： package.json, Cargo.toml, pom.xml, build.gradle(.kts), go.mod, Gemfile, Podfile, requirements.txt, pyproject.toml, composer.json, Pipfile, pubspec.yaml, Package.swift, build.sbt, mix.exs, .csproj/.fsproj, Dockerfile/Containerfile （来自）， docker-compose.yml （图像）， .spec （需要/构建需要）， debian/control （依赖项/构建依赖项）。

工程实践

从文件存在和目录结构中检测到。全部使用 <project> 作为主题。

演出

ingestor使用并行文件遍历（通过 ignore crate）和直接树型节点类型匹配以提高速度。在调试模式下，在1秒内将5000个文件/60000个三元组作为基准。Git历史索引添加了一个 git log 文件遍历后调用。

出版

板条箱.io

cargo publish

发布为 chapeaux-beret。用户安装时使用 cargo install chapeaux-beret.

npm

cd npm && npm publish --access public

发布为 @chapeaux/beret。需要将预构建的二进制文件上传到GitHub版本。

JSR公司

cd npm && npx jsr publish

发布为 @chapeaux/beret 关于JSR。用户使用 npx jsr:@chapeaux/beret.

测试

cargo test

许可证

麻省理工学院