symbols

symbols

一款快速、多语言的源代码智能 CLI。提取符号、解析导入、追踪依赖并分析影响——全部通过命令行完成。

无需语言服务器。项目无需构建步骤。只需将它指向你的代码。

目录

• 为何开发此工具
• 如何节省上下文
• 功能介绍
• 安装
• 语言支持
• 用法
  • 符号提取
  • 导入解析
  • 依赖查询
  • 影响分析
  • 项目图摘要
  • JSON 输出
  • 简写
  • 符号搜索
• MCP 服务
• 工作原理
• 项目根目录检测
• 限制
• 许可证

为何开发此工具

当你需要快速了解代码库，而不想先打开 30 个文件时，symbols 就能派上用场。

它针对的常见痛点：

• 即将修改某个文件，需要立即了解影响范围。
• 刚开始接触不熟悉的代码仓库，需要一份地图，而不是大海捞针。
• 正在审查 PR，想了解具体的依赖关系和归属信息。
• 使用 AI 编码工具，需要随时获取可靠、结构化的项目上下文。

symbols 无需你从编辑器标签页、grep 输出和记忆中手动重建上下文，只需一步即可呈现结构视图。

如何节省上下文

symbols 通过两种实用方式节省上下文：

1. 它将代码结构外化为快速、可重复的查询（list、deps、dependents、impact、graph、search），让你无需在每次会话中重新构建脑海中的项目地图。
2. 它通过 MCP（syms mcp）提供同一模型，让 Agent 和工具能够直接获取最新的项目事实，而不是依赖过时的聊天记录或猜测文件关系。

实际效果：

• 减少重复阅读
• 更少遇到“这样会造成什么影响？”的意外
• 加快上手，更安全地重构
• AI 能提供更有用的帮助，因为上下文是检索得到的，而非临时编造的
• 减少探索性工程周期，以及 AI 为重新发现代码仓库而消耗的 token，从而降低成本

功能介绍

syms list server.py           # functions, classes, constants, variables
syms imports server.py        # parsed import statements
syms deps server.py           # files this file imports from
syms dependents server.py     # files that import this file
syms impact server.py         # full impact analysis (direct + transitive)
syms graph .                  # project-wide dependency summary
syms search User              # find symbols by name across a project
syms mcp                      # run as MCP server for AI tools

安装

选项 1：从源代码构建

git clone https://github.com/Jordan-Horner/symbols.git
cd symbols
go build -o syms .
sudo mv syms /usr/local/bin/

要求： Go 1.26+

选项 2：直接安装（Linux/macOS）

# Install directly to /usr/local/bin
curl -L https://github.com/Jordan-Horner/symbols/releases/latest/download/syms-$(uname -s)-$(uname -m) -o /usr/local/bin/syms
chmod +x /usr/local/bin/syms

选项 3：Homebrew（macOS）

brew tap Jordan-Horner/tap
brew install syms

验证安装

syms --version

语言支持

符号提取使用 tree-sitter 进行完整的 AST 解析（函数签名及其参数、类、类型、常量）。导入解析和依赖解析使用正则表达式。

语言	符号	导入解析	依赖解析
Python	tree-sitter（函数、类、常量、变量）	正则表达式	相对导入 + 绝对导入
TypeScript	tree-sitter	正则表达式	tsconfig.json 路径别名、相对路径、index.ts
JavaScript	tree-sitter	正则表达式	与 TypeScript 相同（也会读取 jsconfig.json）
Svelte	tree-sitter（脚本块）	正则表达式	与 TypeScript 相同
Go	tree-sitter	正则表达式	go.mod 模块前缀、包目录
Java	tree-sitter	正则表达式	点号转斜杠，src/main/java 前缀
Kotlin	tree-sitter	正则表达式	与 Java 相同 + .kt
Rust	tree-sitter	正则表达式	crate/self/super、mod.rs
C#	tree-sitter	正则表达式	命名空间转路径，类名回退
PHP	tree-sitter	正则表达式	PSR-4 约定、require/include
C/C++	tree-sitter	—	—
Ruby	tree-sitter	—	—
Scala	tree-sitter	—	—
Bash	tree-sitter	—	—

用法

符号提取

# Single file
syms list app.py

# Multiple files
syms list src/main.go src/handlers.go

# Recursive directory scan
syms list -r src/

# JSON output (for piping to other tools)
syms list --json app.py

# Pretty JSON output (human-readable)
syms list --json --pretty app.py

# Optional: include precise symbol ranges
syms list --json --ranges app.py

# Count symbols per file
syms list --count src/

# Filter by symbol kind (repeatable or comma-separated)
syms list --filter class src/
syms list --filter class,function src/
syms list --filter class --filter function src/

输出：

### `app.py` — 245 lines

  constant VERSION  # line 1
  constant API_URL  # line 3
  variable app  # line 5
  class Application  # line 12
  def __init__(self, config)  # line 15
  async def start(self)  # line 34
  def shutdown(self)  # line 78

导入解析

syms imports server.py

输出：

### `server.py`

  from flask import Flask, jsonify  # line 1
  from .models import User, Post  # line 2
  import os  # line 3

依赖查询

# Direct dependencies
syms deps src/handlers.go

# Transitive (everything it depends on, recursively)
syms deps -t src/handlers.go

# Who imports this file?
syms dependents src/models.py

# Transitive dependents
syms dependents -t src/models.py

影响分析

syms impact src/core/utils.py

输出：

### `src/core/utils.py` — impact analysis

  Direct dependents:     8
  Transitive dependents: 23

  Direct:
    src/api/handlers.py
    src/core/auth.py
    src/core/db.py
    ...

  Indirect (transitive):
    src/api/routes.py
    src/main.py
    tests/test_auth.py
    ...

项目图摘要

syms graph .

输出：

Project dependency graph

  Files:              187
  Import edges:       562
  Unresolved imports: 43

  Most depended-on files:
    src/utils.py  (36 dependents)
    src/config.py  (33 dependents)
    src/models.py  (23 dependents)

  Heaviest importers:
    src/app.py  (28 imports)
    src/main.py  (24 imports)

  Circular dependencies (1):
    src/config.py <-> src/runner.py

JSON 输出

所有命令都支持 --json，用于生成机器可读的输出：

syms impact --json src/utils.py | jq '.direct_dependents'
syms graph --json . | jq '.hot_spots[:5]'

# Optional: pretty-print JSON for humans
syms graph --json --pretty .

# Full edge map (file → its dependencies)
syms graph --json . | jq '.edges'

# What does a specific file depend on?
syms graph --json . | jq '.edges["src/app.py"]'

简写

list 子命令是默认命令，因此可以省略：

# These are equivalent:
syms list app.py
syms app.py

# Flags work too:
syms -r src/ --json

符号搜索

# Find symbols by name (fuzzy: exact > prefix > contains)
syms search User

# JSON output
syms search --json handle

# Search in a specific project
syms search --root /path/to/project Config

# Search only specific symbol kinds
syms search --filter class User

# Optional: include precise symbol ranges in search results
syms search --json --ranges User

输出：

Found 3 symbols matching "User":

  class User  models.py:1
  class UserProfile  models.py:5
  function get_user(id)  api/handlers.py:12

MCP 服务

将 syms 作为 MCP 服务运行，以集成 AI 工具（例如 Claude Code）：

syms mcp

通过 stdio（JSON-RPC 2.0）将所有功能作为 MCP 工具提供：

工具	说明
syms_list	从文件中提取符号
syms_imports	解析导入语句
syms_deps	文件依赖
syms_dependents	反向依赖
syms_impact	影响分析
syms_search	按名称搜索符号
syms_graph	项目依赖图

syms_list 和 syms_search 接受可选的 kinds: string[] 参数，用于筛选符号种类。 syms_list 和 syms_search 还接受可选的 include_ranges: boolean，用于包含起始/结束行号和列号元数据。 工具结果会在 structuredContent 中返回（而非作为 JSON 文本块放在 content[].text 中）。

Claude Code 配置

安装 syms 后，将其配置为 MCP 服务：

项目级（推荐团队使用）：

在项目根目录中创建 .mcp.json：

{
  "mcpServers": {
    "symbols": {
      "command": "syms",
      "args": ["mcp"]
    }
  }
}

提交此文件，即可让团队自动获得符号服务。

全局（所有项目）：

创建或编辑 ~/.mcp.json：

{
  "mcpServers": {
    "symbols": {
      "command": "syms",
      "args": ["mcp"]
    }
  }
}

配置完成后：

1. 重启 Claude Code
2. 出现提示时，批准 symbols MCP 服务
3. 现在 Claude Code 即可在所有项目中使用代码智能工具

工作原理

符号提取 使用 tree-sitter 进行完整的 AST 解析。每种语言都有一个编译好的语法（静态链接到二进制文件中），用于生成语法树。工具会遍历语法树，提取顶层声明及其名称、类型、行号和函数参数。对于 Python，模块级赋值也会作为常量（UPPER_CASE）或变量提取。

导入解析 使用针对每种语言的导入语法调整过的正则表达式。对于标准导入形式，这种方式快速可靠，无需解析 AST。

依赖解析 根据各语言的特定约定，将导入说明符映射到磁盘上的实际文件：

• Python：将模块点分路径映射为文件路径，解析相对导入
• Go：去除 go.mod 模块名，将包映射到目录
• Java/Kotlin：采用点到斜杠的约定，以及标准源代码根目录前缀（src/main/java/）
• Rust：解析 crate/self/super 路径，采用 mod.rs 约定
• C#：将命名空间映射到路径，并逐步剥离前缀
• PHP：采用 PSR-4 反斜杠到斜杠的映射，解析 require/include 路径

目录扫描 会提前跳过 .git、node_modules、dist、build、vendor、target 等常见的非源代码目录。

项目根目录检测

对于 deps、dependents、impact 和 graph，工具会沿目录树向上查找 .git、package.json 或 pyproject.toml，自动检测项目根目录。使用 --root 覆盖：

syms deps src/app.py --root /path/to/project

限制

• 基于约定的解析 —— 依赖解析使用文件路径约定，不与编译器或构建系统集成。支持来自 tsconfig.json/jsconfig.json 的 TypeScript/JavaScript paths（包括 extends），但不支持在 tsconfig 之外定义的 webpack/vite 别名。
• 文件级粒度 —— 依赖在文件级别（导入图）进行追踪，而非函数或符号级别。不提供调用图。
• C/C++ 包含 —— 尚未实现 #include 解析和头文件解析。符号提取可用，但不支持依赖追踪。
• Ruby/Scala/Bash —— 可通过 tree-sitter 提取符号，但尚未实现导入解析和依赖解析。
• 动态导入 —— 无法检测 Python 的 importlib.import_module()、JavaScript 的计算型 require() 及类似动态模式。
• 单体仓库边界 —— 工具会在单个项目根目录内解析导入。单体仓库中的跨包导入可能无法正确解析。

许可证

MIT