tracer

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

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、特定数据文件），确保环境就绪后再执行追踪。
• 分析报告应重点关注项目自身的代码结构，而非被过滤掉的外部依赖。