cartog

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

cartog — Code Graph Navigation Skill

cartog — 代码图谱导航工具

When to Use

适用场景

Use cartog before reaching for grep, cat, or file reads when you need to:

Understand the structure of a file →
```
cartog outline <file>
```
Find who calls a function →
```
cartog callers <name>
```
See what a function calls →
```
cartog callees <name>
```
Assess refactoring impact →
```
cartog impact <name> --depth 3
```
Find all references →
```
cartog refs <name>
```
Understand class hierarchies →
```
cartog hierarchy <class>
```
See file dependencies →
```
cartog deps <file>
```

当你需要完成以下操作时，请在使用grep、cat或读取文件之前先使用cartog：

理解文件结构 →
```
cartog outline <file>
```
查找调用某个函数的对象 →
```
cartog callers <name>
```
查看某个函数调用了哪些内容 →
```
cartog callees <name>
```
评估重构影响 →
```
cartog impact <name> --depth 3
```
查找所有引用 →
```
cartog refs <name>
```
理解类继承层级 →
```
cartog hierarchy <class>
```
查看文件依赖 →
```
cartog deps <file>
```

Workflow Rules

工作流规则

Before you grep or read a file to understand structure, query cartog first.
Use
cartog outline <file>
instead of
```
cat <file>
```
when you need structure, not content.
Before refactoring, run
```
cartog impact <symbol>
```
to see the blast radius.
Only fall back to grep/read when cartog doesn't have what you need (e.g., reading actual implementation logic, string literals, config values).
After making code changes, run
```
cartog index .
```
to update the graph.

在使用grep或读取文件来理解结构之前，先查询cartog。
使用
cartog outline <file>
替代
```
cat <file>
```
，当你需要了解结构而非内容时。
在重构之前，运行
```
cartog impact <symbol>
```
查看影响范围。
仅当cartog无法满足需求时（例如查看实际实现逻辑、字符串字面量、配置值），再使用grep或读取文件。
完成代码修改后，运行
```
cartog index .
```
来更新图谱。

Setup

安装配置

Ensure cartog is indexed before first use:

bash

bash scripts/ensure_indexed.sh

首次使用前请确保已完成cartog的索引构建：

bash

bash scripts/ensure_indexed.sh

Commands Reference

命令参考

Index (build/rebuild)

索引（构建/重建）

bash

cartog index .                    # Index current directory
cartog index src/                 # Index specific directory

bash

cartog index .                    # 索引当前目录
cartog index src/                 # 索引指定目录

Outline (file structure)

大纲（文件结构）

bash

cartog outline src/auth/tokens.py

Output shows symbols with types, signatures, and line ranges — no need to read the file.

bash

cartog outline src/auth/tokens.py

输出内容包含符号的类型、签名和行号范围——无需读取文件内容。

Callers (who calls this?)

调用方（谁调用了这个函数？）

bash

cartog callers validate_token

bash

cartog callers validate_token

Callees (what does this call?)

被调用方（这个函数调用了哪些内容？）

bash

cartog callees UserService.authenticate

bash

cartog callees UserService.authenticate

Impact (transitive blast radius)

影响范围（传递性影响半径）

bash

cartog impact SessionManager --depth 3

Shows everything that transitively depends on a symbol up to N hops.

bash

cartog impact SessionManager --depth 3

展示所有与该符号存在N层以内传递依赖的内容。

Refs (all references)

所有引用

bash

cartog refs parse_config

Returns calls, imports, inherits — every edge pointing to this name.

bash

cartog refs parse_config

返回调用、导入、继承关系——所有指向该名称的关联。

Hierarchy (inheritance tree)

继承层级（继承树）

bash

cartog hierarchy BaseService

bash

cartog hierarchy BaseService

Deps (file imports)

文件依赖（导入关系）

bash

cartog deps src/routes/auth.py

bash

cartog deps src/routes/auth.py

Stats (index summary)

统计信息（索引摘要）

bash

cartog stats

bash

cartog stats

JSON Output

JSON输出

All commands support

--json

for structured output:

bash

cartog --json callers validate_token
cartog --json outline src/auth/tokens.py

所有命令均支持

--json

参数以生成结构化输出：

bash

cartog --json callers validate_token
cartog --json outline src/auth/tokens.py

Decision Heuristics

决策指引

I need to...	Use
Know what's in a file	`cartog outline <file>`
Find usages of a function	`cartog callers <name>`
Understand what a function does at a high level	`cartog callees <name>`
Check if a change is safe	`cartog impact <name>`
Find all references (imports, calls, inherits)	`cartog refs <name>`
Understand class hierarchy	`cartog hierarchy <class>`
See file dependencies	`cartog deps <file>`
Read actual implementation logic	`cat <file>` (cartog can't help here)
Search for string literals / config	`grep` (cartog indexes structure, not content)

我需要...	使用命令
了解文件内容结构	`cartog outline <file>`
查找函数的调用方	`cartog callers <name>`
从宏观层面理解函数功能	`cartog callees <name>`
检查代码变更是否安全	`cartog impact <name>`
查找所有引用（导入、调用、继承）	`cartog refs <name>`
理解类继承层级	`cartog hierarchy <class>`
查看文件依赖关系	`cartog deps <file>`
查看实际实现逻辑	`cat <file>` （cartog无法提供此支持）
搜索字符串字面量/配置项	`grep` （cartog仅索引结构，不索引内容）

Limitations

局限性

Structural/heuristic resolution, not full semantic. ~90% accuracy for cross-file references.
Currently supports: Python, TypeScript/JavaScript, Rust, Go. Java planned.
Does not index string literals, comments (except docstrings), or config values.
Method resolution is name-based —
```
foo.bar()
```
resolves
```
bar
```
, not
```
Foo.bar
```
specifically.

采用结构化/启发式解析，而非完整语义分析。跨文件引用的准确率约为90%。
当前支持：Python、TypeScript/JavaScript、Rust、Go。计划支持Java。
不索引字符串字面量、注释（文档字符串除外）或配置值。
方法解析基于名称——
```
foo.bar()
```
会解析
```
bar
```
，而非特指
```
Foo.bar
```
。