Trickle 发布 Python 运行时类型追踪工具，支持 VSCode 与终端内联提示

为 Python、Javascript/Typescript 提供运行时类型注解——编码时即可查看张量形状、变量类型和崩溃时的值。

不再需要 print(x.shape)。运行代码，即可在 VSCode 或终端中内联查看每个变量的类型和值。

快速开始

pip install trickle-observe                         # Python runtime tracer
npm install -g trickle-cli                          # CLI (trickle run, trickle hints)
code --install-extension yiheinchai.trickle-vscode  # VSCode inline hints

trickle run python train.py     # run with tracing
trickle hints                   # view source with inline types

查看张量形状如何在模型中流转

def forward(self, x: Tensor[128, 2] float32):
    x: Tensor[128, 256] float32  = self.relu(self.bn0(self.embed(x)))
    x: Tensor[128, 16, 16] float32  = x.view(x.size(0), 16, 16)
    x: Tensor[128, 32, 16] float32  = self.relu(self.bn1(self.conv1(x)))
    x: Tensor[128, 64, 16] float32  = self.gelu(self.ln2(self.conv2(x)))
    x: Tensor[128, 128, 16] float32  = self.relu(self.bn3(self.conv3(x)))
    x: Tensor[128, 64, 7] float32  = self.gelu(self.bn4(self.conv4(x)))
    x: Tensor[128, 32, 3] float32  = self.relu(self.ln5(self.conv5(x)))
    x: Tensor[128, 96] float32  = x.flatten(1)
    x: Tensor[128, 64] float32  = self.gelu(self.ln6(self.fc1(x)))
    return self.fc2(x)

准确查看导致崩溃的原因

data_dir: PosixPath = Path("../data/gaitpdb/1.0.0")
excluded_files: unknown[] = []
data_file_paths: string[] = [p for p in os.listdir(data_dir) if '.txt' in p]

for file_path: string = "demographics.txt" in data_file_paths:
    with open(data_dir / file_path, 'r') as data:
        patient_gait_data: string[] = data.readlines()
        parsed_data = [[float(d) for d in time.split('\t')] for time in patient_gait_data]
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        <- ValueError: could not convert string to float: 'ID'

file_path 是 "demographics.txt"。patient_gait_data 是 string[]——是表头，不是数字。几秒内即可发现 Bug。

命令

trickle run

运行任意 Python 脚本并自动进行变量追踪。无需修改任何代码。

trickle run python train.py
trickle run python -m pytest tests/
trickle run python manage.py runserver

trickle hints

输出带有内联类型注解的源代码——专为 AI 智能体和终端工作流设计。

trickle hints train.py                     # types for a file
trickle hints --errors                     # crash-time values + error underline
trickle hints --errors --show types        # types only
trickle hints --errors --show values       # values only
trickle hints --errors --show both         # both (default in error mode)

trickle vars

所有捕获变量的表格视图。

trickle vars                     # all variables
trickle vars --tensors           # only tensors
trickle vars --file model.py     # filter by file

trickle init

在项目中设置 trickle。

trickle init
trickle init --python

Jupyter Notebooks

%load_ext trickle                # first cell, then run your code

每个单元格运行后，类型会立即内联显示在 VSCode 中。

试用演示

git clone https://github.com/yiheinchai/trickle.git
cd trickle
trickle run python demo/demo.py
trickle hints demo/demo.py

工作原理

Trickle 在执行前通过 AST 转换重写你的 Python 源代码。在每个变量赋值之后，它会插入一个轻量级调用，捕获类型和样本值，然后写入 .trickle/variables.jsonl。

• 仅追踪你的代码——标准库、site-packages、torch/numpy 内部实现均被跳过
• 无需修改代码。无需装饰器。无需类型注解
• VSCode 扩展读取此文件并渲染内联提示

使用场景

• ML 工程师——张量形状、训练循环、Jupyter notebooks
• AI 智能体——在终端中提供运行时上下文，以便调试不熟悉的代码

文档

• 功能特性
• 完整文档

许可证

Apache-2.0