agentleFS
l0190l0190/DevSkills/.claude/skills/tracer/SKILL.md

tracer

Skill4 starsChanged 5 months agoMITView on GitHub

为Python项目生成函数调用树,可视化执行流程和代码结构。务必在以下场景触发:用户想了解代码执行流程、追踪函数调用、分析调用链、可视化代码流、查找入口点、调试复杂执行路径;用户提到"调用图"、"调用树"、"函数追踪"、"执行流程"、"调用链"、"代码是怎么运行的"、"有哪些函数被调用了"、"分析代码结构"、"trace"、"call graph"、"call tree"、"function trace"。

3 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions3 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 3

    1. agentmemoir/skills★ 3same name
    2. Curious-Keeper/skills★ 1same name
    3. steveu/skills★ 1same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository4 other files it gives its agents.

The file

Files
SKILL.md

Python 函数调用图生成器

本技能使用 trace_call_tree.py 通过 sys.setprofile 追踪 Python 函数调用,输出结构化的调用树日志,然后对日志进行深度分析并生成 Markdown 分析报告。

适用场景

  • 理解陌生代码库的执行流程
  • 分析某个入口点调用了哪些函数
  • 调试复杂的调用链
  • 对比实际运行时调用路径与静态代码结构的差异
  • 验证重构后的代码是否遵循预期的执行路径
  • 定位性能热点(高频调用函数)
  • 理解多模块项目的初始化依赖关系

工作原理

追踪器使用 Python 的 sys.setprofile 钩子在运行时捕获每一次函数调用和返回。它会过滤掉标准库和第三方库的调用,只保留项目内部的调用,然后格式化为缩进树形结构。

执行流程

当用户要求追踪或理解代码执行流程时,按以下步骤执行:

步骤 1:确定追踪参数

  • 确定入口点 — 找到项目中的 main() 函数或用户指定的入口脚本。如果用户指定了具体文件,使用该文件;否则搜索项目中的 main.py、__main__.py、app.py 等常见入口。
  • 确定项目根目录 — 使用项目顶层目录,确保追踪器正确过滤内部与外部调用。
  • 确定入口函数名 — 默认为 main,如果入口文件中没有 main() 则使用 --module-exec 模式。

步骤 2:运行追踪器生成日志

使用 Bash 工具执行 trace_call_tree.py:

# 基本用法:从 main() 开始追踪
python .claude/skills/tracer/scripts/trace_call_tree.py \
  --entry path/to/script.py \
  --project-root path/to/project

# 指定其他入口函数
python .claude/skills/tracer/scripts/trace_call_tree.py \
  --entry path/to/script.py \
  --main-func run_server \
  --project-root path/to/project

# 追踪模块级代码(无需 main 函数)
python .claude/skills/tracer/scripts/trace_call_tree.py \
  --entry path/to/script.py \
  --module-exec \
  --project-root path/to/project

# 自定义输出路径
python .claude/skills/tracer/scripts/trace_call_tree.py \
  --entry path/to/script.py \
  --output logs/call_tree_{project_name}.log \
  --project-root path/to/project

参数说明:

参数必填默认值说明
--entry是-Python 入口文件路径
--main-func否main入口函数名称
--project-root否.项目根目录,用于过滤内部调用
--output否call_tree.log输出日志文件路径
--module-exec否false追踪模块级代码,无需 main() 函数
-- 分隔符否--- 之后的参数会转发给入口脚本

步骤 3:读取 trace 日志

追踪完成后,使用 Read 工具读取生成的日志文件(默认为 call_tree.log)。

步骤 4:生成 Markdown 分析报告

对 trace 日志进行深度分析,生成一份结构化的 Markdown 分析文档,保存到 logs/ 目录下,文件名为 call_tree_{project_name}_analysis.md。报告必须包含以下章节:

报告结构

# {项目名称} 函数调用树分析报告

## 1. 概述

- **入口文件**:追踪的入口脚本路径
- **入口函数**:追踪的入口函数名称
- **项目根目录**:项目根路径
- **追踪模式**:`main()` 函数 / 模块级执行

## 2. 整体架构

用文字描述项目的整体执行流程,按阶段划分(如:初始化 → 数据加载 → 核心处理 → 输出)。说明各阶段的职责和阶段间的数据流转。

## 3. 调用树结构

将原始 trace 日志整理为带注释的树形结构,在每个关键节点添加行内注释说明其作用。对模块加载阶段的 `<module>` 节点,注释说明该模块的职责。

## 4. 核心调用链分析

识别 3-5 条最重要的调用链(从入口到关键输出的完整路径),逐一分析:
- 该调用链的功能
- 沿途各函数的职责
- 数据在各函数间的流转方式

## 5. 关键模块与类

提取调用树中出现的重要模块和类,说明:
- 模块/类的职责
- 与其他模块的依赖关系
- 设计模式(如工厂模式、策略模式等)

## 6. 热点函数

列出调用次数最高的函数(count > 1),分析:
- 为何被频繁调用
- 是否存在优化空间
- 调用频率是否符合预期

## 7. 模块依赖图

用文本描述各模块间的依赖关系,重点标注:
- 核心模块与辅助模块的分层
- 循环依赖(如果存在)
- 模块间的主要接口

## 8. 发现与建议

基于调用树分析,提出观察发现和改进建议:
- 架构层面是否有不合理之处
- 是否有过度耦合的模块
- 初始化阶段是否有冗余加载
- 性能优化建议

步骤 5:向用户展示

将分析报告的关键发现简明扼要地展示给用户,并告知报告文件的保存路径。如果用户想深入了解某个方面,可以直接引用报告中的对应章节。

注意事项

  • 追踪器捕获的是运行时调用,未被执行到的代码路径(如未触发的异常处理)不会出现在调用树中。
  • --module-exec 标志适用于在模块级别运行逻辑而非通过 main() 函数的脚本。
  • 追踪器会过滤掉 site-packages/、dist-packages/ 以及虚拟环境目录(env/、venv/、.venv/)中的调用。
  • 对于多线程代码,追踪器会对所有线程进行 profile 并将结果合并到同一棵调用树中。
  • 如果追踪的目标脚本需要额外的运行环境(如 GPU、特定数据文件),确保环境就绪后再执行追踪。
  • 分析报告应重点关注项目自身的代码结构,而非被过滤掉的外部依赖。

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.