内容
# canopy
[](https://pkg.go.dev/m31labs.dev/canopy)
[](https://github.com/odvcencio/canopy/actions/workflows/ci.yml)
[](https://github.com/odvcencio/canopy/actions/workflows/release.yml)
由 [gotreesitter](https://github.com/odvcencio/gotreesitter) 驱动的结构化代码分析工具包。基于抽象语法树（AST）的索引、搜索、调用图分析、安全智能、架构治理以及 AI 代理集成，支持 206+ 种语言。
## 代理技能
帮助用户使用 Canopy 的代理应阅读规范的 M31 Labs 技能： [using-canopy](https://github.com/odvcencio/m31labs-skills/blob/main/skills/using-canopy/SKILL.md)。
## 安装
```bash
go install m31labs.dev/canopy/cmd/canopy@latest
```
## 快速开始
```bash
# 构建结构索引
canopy index build .
# 搜索符号
canopy search refs ParseConfig .
# 检查代码质量（CI 门控）
canopy analyze check --max-cyclomatic 30
# 完整执行报告
canopy analyze report --format markdown
# 为 AI 代理运行 MCP 服务器
canopy mcp --root .
```
## 当前主版本
当前主版本使用 gotreesitter `v0.45.0`，默认情况下对大型仓库索引进行限制：CLI 使用 1 GiB Go 软内存限制（调用者未提供时），索引构建最多使用两个并发解析工作线程和 32 个解析文件的垃圾回收节奏。索引遍历还在下降前修剪忽略的目录，并在解析前跳过不支持或无标签的语法。
默认设置可针对特殊工作负载进行调整：
- `GOMEMLIMIT` 覆盖 Go 软内存限制。
- `GTS_MAX_CONCURRENT` 覆盖解析器工作线程数。
- `CANOPY_INDEX_GC_EVERY` 覆盖收集节奏；设置为 `0` 以禁用强制收集。
多个定义共享名称时，可以使用 `--file` 或 `path/to/file.go:Name` 缩小调用图根范围。
## 命令
### 索引 — 构建和管理结构索引
| 命令 | 描述 |
|---------|-------------|
| `canopy index build [path]` | 构建/增量更新索引，支持监视模式 |
| `canopy index map` | 索引文件的结构化目录 |
| `canopy index files` | 列出文件，支持密度过滤和排序 |
| `canopy index stats` | 代码库指标：符号计数、语言分布 |
| `canopy index diff` | 比较两个快照之间的结构变化 |
| `canopy index errors` | 显示索引过程中的解析错误 |
| `canopy index validate` | 验证索引完整性 |
| `canopy index export` | 将索引导出到可移植的 `.canopyindex` 文件以进行联邦 |
| `canopy index import` | 加载和汇总导出的索引 |
### 搜索 — 查找符号、引用和模式
| 命令 | 描述 |
|---------|-------------|
| `canopy search grep` | 结构化选择器查询（例如 `function_definition[name=/^Test/]`） |
| `canopy search refs` | 按符号名称或正则表达式查找引用 |
| `canopy search query` | 原始树状语法查询 |
| `canopy search scope` | 在文件 + 行处解析作用域中的符号 |
| `canopy search context` | 为代理令牌预算打包聚焦上下文。 `--concept` 用于概念感知打包 |
| `canopy search symbols` | 按模式搜索符号 |
| `canopy search imports` | 分析导入模式 |
### 图 — 调用图、依赖和覆盖率分析
| 命令 | 描述 |
|---------|-------------|
| `canopy graph calls` | 从匹配根遍历调用图边 |
| `canopy graph dead` | 列出具有零个传入引用的可调用定义 |
| `canopy graph deps` | 导入依赖图，支持循环检测（ `--cycles` ） |
| `canopy graph bridge` | 映射跨组件依赖桥 |
| `canopy graph impact` | 通过反向调用图计算影响半径 |
| `canopy graph testmap` | 将测试函数映射到实现 |
| `canopy graph fanin` | 按传入调用计数排名函数 |
| `canopy graph unresolved` | 显示未解析的调用引用 |
| `canopy graph drift` | 比较两个 git 引用的依赖图 |
| `canopy graph services` | 从联邦索引的仓库到仓库依赖映射 |
### 分析 — 质量、复杂度、安全性和治理
| 命令 | 描述 |
|---------|-------------|
| `canopy analyze check` | 配置阈值的 CI 质量门控。 `--base` 用于 diff-aware PR 过滤。 `--format sarif` 用于 GitHub Advanced Security |
| `canopy analyze boundaries` | `.canopyboundaries` 的模块边界强制执行。 `--format sarif` |
| `canopy analyze complexity` | 按函数计算环复杂度、认知复杂度、嵌套复杂度、扇入/扇出指标 |
| `canopy analyze hotspot` | 从 git 变更 + 复杂度 + 中心度计算代码热点 |
| `canopy analyze lint` | 结构化 lint，支持内置规则、查询模式和机密检测。 `--format sarif` |
| `canopy analyze capa` | 能力检测，支持 MITRE ATT&CK 映射 |
| `canopy analyze reachability` | 供应链分析：软件包 X 是否达到能力 Y？ |
| `canopy analyze licenses` | 依赖许可检测，支持 SPDX 匹配和拒绝规则 |
| `canopy analyze similarity` | 在代码库之间查找相似函数 |
| `canopy analyze duplication` | 检测代码重复 |
| `canopy analyze report` | 执行摘要：复杂度、架构、安全、死代码、热点。 `--by-team` 用于 CODEOWNERS 分解 |
| `canopy analyze review` | 聚合 PR 审查：复杂度变化、边界违规、新能力、影响半径 |
| `canopy analyze trends` | 跟踪随时间变化的质量指标（ `record` / `show` ） |
### 转换 — 代码转换和输出生成
| 命令 | 描述 |
|---------|-------------|
| `canopy transform refactor` | AST 感知的声明重命名，支持跨包调用站点更新 |
| `canopy transform chunk` | AST 边界块，用于 RAG/索引。 `--format embeddings` 用于向量数据库 |
| `canopy transform sbom` | CycloneDX 1.5 SBOM，支持可选能力增强 |
| `canopy transform yara` | 从结构分析生成 YARA 规则 |
| `canopy transform normalize` | 标准化反编译输出 |
### 其他
| 命令 | 描述 |
|---------|-------------|
| `canopy init` | 引导项目设置：生成 `.canopyignore`、 `.canopygenerated`、 `.canopyboundaries` |
| `canopy init ci` | 生成 GitHub Actions 工作流，用于 CI 质量检查 |
| `canopy mcp` | MCP stdio 服务器，为 AI 代理公开 30+ 结构分析工具（Claude、Cursor、VS Code） |
## 配置文件
| 文件 | 目的 |
|------|---------|
| `.canopyignore` | Gitignore 样式的模式，排除文件索引 |
| `.canopygenerated` | 声明生成的文件模式，指定命名生成器 |
| `.canopyboundaries` | 模块边界规则（允许/拒绝导入关系） |
| `.canopylint` | Lint 阈值、作用域覆盖、包级规则、忽略规则、许可拒绝规则 |
### `.canopyboundaries` 示例
```
# pkg/model 没有内部依赖
module pkg/model allow -
# pkg/index 只能导入这些包
module pkg/index allow pkg/model, pkg/lang, pkg/generated
# 内部包可以使用任何 pkg 但不能交叉导入
module internal/* allow pkg/*
module internal/* deny internal/*
```
### `.canopylint` 示例
```
# 覆盖默认阈值
cyclomatic > 35 -> warn "函数太复杂"
cognitive > 60 -> warn "难以理解"
# 作用域规则
fan_out > 10 in pkg/* -> warn "高扇出"
# 包级规则
package import_depth > 5 -> error "依赖链太深"
package exported_symbols > 50 in pkg/* -> warn "API 表面太大"
package no_import_cycles -> error "检测到导入循环"
# 忽略特定函数
ignore cyclomatic in generated/
# 许可强制执行
license deny GPL-3.0, AGPL-3.0 -> error "不允许 copyleft 许可"
```
## 全局标志
| 标志 | 描述 |
|------|-------------|
| `--include-generated` | 在输出中包含生成的文件（默认情况下排除） |
| `--generator <name>` | 过滤到特定生成器（例如 `protobuf`、`human`） |
| `--federation <dir>` | `.canopyindex` 文件的目录，用于跨仓库分析 |
## 多仓库联邦
在没有中央服务器的情况下，跨多个仓库进行分析：
```bash
# 在每个仓库的 CI 中：
canopy index build . && canopy index export -o myrepo.canopyindex
# 收集所有 .canopyindex 文件，然后：
canopy graph services --federation ./indexes/
canopy search refs "AuthService" --federation ./indexes/
canopy graph dead --federation ./indexes/
```
## CI 集成
生成 GitHub Actions 工作流：
```bash
canopy init ci
```
这会创建 `.github/workflows/canopy-check.yml`，在 PR 上运行质量检查，并上传 SARIF 进行内联注释。
手动 SARIF 集成：
```bash
canopy analyze check --base origin/main --format sarif > results.sarif
```
跟踪随时间变化的指标：
```bash
canopy analyze trends record # 追加当前指标到 .canopy/trends.jsonl
canopy analyze trends show # 显示趋势摘要和变化
```
## MCP 服务器
MCP stdio 服务器通过 JSON-RPC 为 AI 代理公开 30+ 结构分析工具。
```bash
canopy mcp --root /path/to/repo
canopy mcp --root /path/to/repo --allow-writes # 启用重构工具
```
### 客户端设置
**Claude Desktop / Claude Code / Cursor / VS Code：**
```json
{
"mcpServers": {
"canopy": {
"command": "canopy",
"args": ["mcp", "--root", "/path/to/repo"]
}
}
}
```
### 关键 MCP 工具
| 工具 | 描述 |
|------|-------------|
| `gts_guardrails` | 文件级咨询：生成状态、复杂度、扇入警告。在编辑前调用 |
| `gts_review` | 变更文件的聚合 PR 审查 |
| `gts_reachability` | 供应链能力分析 |
| `gts_boundaries` | 模块边界强制执行 |
| `gts_report` | 所有分析的执行摘要 |
| `gts_callgraph` | 调用图遍历 |
| `gts_dead` | 死代码检测 |
| `gts_impact` | 影响半径计算 |
| `gts_context` | 令牌预算上下文打包 |
| `gts_grep` | 结构化选择器搜索 |
## 选择器语法
`canopy search grep` 和 `gts_grep` 使用：
```
<kind>[filter1,filter2,...]
```
**示例：**
- `function_definition[name=/^Test/]`
- `method_definition[receiver=/Service/,signature=/Serve/]`
- `*[file=/handlers\/.go$/,start>=20,end<=200]`
**过滤器：** `name`、`signature`、`receiver`、`file` （正则表达式）；`start`、`end`、`line` （数值比较）。
## 语言支持
通过 gotreesitter 语法支持 206+ 种语言，包括 Go、Python、JavaScript/TypeScript、Java、C/C++、Rust、C#、Ruby、PHP、Swift、Kotlin、Scala、SQL、HTML/CSS、YAML、JSON、Terraform、Dockerfile 等。
**作用域解析** （符号在文件 + 行的作用域）：Go、Python、TypeScript。
## 许可证
详见 [LICENSE](LICENSE)。
