symbols (Jordan Horner)

符号

一个快速、多语言的源代码智能CLI。从命令行提取符号、解析导入、跟踪依赖关系和分析影响。

不需要语言服务器。您的项目没有构建步骤。只需将其指向您的代码即可。

  

目录

• 为什么存在
• 它如何保存上下文
• 它做什么
• 安装
• 语言支持
• 用法

- 符号提取 - 导入解析 - 依赖关系查询 - 影响分析 - 项目图摘要 - JSON输出 - 速记 - 符号搜索

• MCP服务器
• 运作原理
• 项目根检测
• 局限性
• 许可证

为什么存在

symbols 适用于需要快速理解代码库而无需先打开30个文件的时刻。

它针对的常见痛点：

• 您即将更改文件，需要立即知道爆炸半径。
• 你正在进入一个不熟悉的仓库，需要一张地图，而不是寻宝游戏。
• 您正在审查PR，并希望获得具体的依赖关系和所有权信号。
• 您正在使用AI编码工具，需要可靠、结构化的项目上下文。

代替从编辑器选项卡、grep输出和内存手动重建上下文， symbols 一步完成结构视图。

它如何保存上下文

symbols 以两种实用的方式保存上下文：

1. 它将代码结构外部化为快速、可重复的查询(list, deps, dependents, impact, graph, search)所以你不必每次都重建思维导图。
2. 它通过MCP公开相同的模型(syms mcp)因此，代理和工具可以直接获取新的项目事实，而不是依赖过时的聊天历史或猜测的文件关系。

净效应：

• 减少重读
• 更少的“这会打破什么？”惊喜
• 更快的上线和更安全的重构
• 更有用的人工智能辅助，因为上下文是检索的，而不是即兴的
• 通过减少探索性工程周期和减少回购重新发现的AI代币支出来降低成本

它做什么

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/

要求： 转到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：自制（macOS）

brew tap Jordan-Horner/tap
brew install syms

验证安装

syms --version

语言支持

符号提取使用树形图进行完整的AST解析（具有参数、类、类型、常量的函数签名）。导入解析和依赖解析使用正则表达式。

用法

符号提取

# 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 作为用于AI工具集成的MCP服务器（例如Claude Code）：

syms mcp

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

syms_list 和 syms_search 接受可选 kinds: string[] 用于过滤符号类型的参数。 syms_list 和 syms_search 也接受可选 include_ranges: boolean 用于开始/结束行+列元数据。 工具结果返回 structuredContent （不是JSON文本blob content[].text).

Claude代码设置

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

项目级别 （推荐给团队）：

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

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

提交此文件，以便您的团队自动获取符号服务器。

全球（所有项目）:

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

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

配置后：

1. 重新启动Claude代码
2. 出现提示时，批准 symbols MCP服务器
3. Claude Code现在可以访问您所有项目中的代码智能工具

运作原理

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

导入解析 使用根据每种语言的导入语法调整的正则表达式模式。这对于标准导入表单来说是快速可靠的，不需要AST解析。

依赖解析 使用特定于语言的约定将导入说明符映射到磁盘上的实际文件：

• Python：模块点路径到文件路径，相对导入分辨率
• 去： go.mod 模块名称剥离，包到目录映射
• Java/Kotlin：点到斜线约定，标准源代码根前缀(src/main/java/)
• 锈蚀： 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

局限性

• 基于公约的决议 --依赖解析使用文件路径约定，而不是编译器/构建系统集成。Types/JavaScript paths 从 tsconfig.json/jsconfig.json 支持（包括 extends)，但tsconfig之外定义的webpack/vite别名则不是。
• 文件级粒度 --依赖关系是在文件级别（导入图）跟踪的，而不是在函数或符号级别。没有调用图。
• C/C++包括 — #include 解析和标头解析尚未实现。符号提取有效，但依赖关系跟踪无效。
• Ruby/Scala/Bash --符号提取通过树形图进行，但没有实现导入解析和依赖关系解析。
• 动态导入 --Python的 importlib.import_module()，JavaScript的计算 require()，并且未检测到类似的动态模式。
• Monorepo边界 --该工具在单个项目根中解析导入。monorepos中的跨包导入可能无法正确解析。

许可证

麻省理工学院