diagramming-code

代码图生成

根据 Trailmark 的代码图生成 Mermaid 图表。预置脚本处理 Mermaid 语法生成；Claude 选择图表类型和参数。

使用时机

• 可视化函数之间的调用路径
• 绘制类继承层次结构
• 映射模块导入依赖关系
• 展示类结构及其成员
• 通过颜色编码突出复杂度热点
• 追踪从入口点到敏感函数的数据流

不适用场景

• 查询图而不进行可视化（请使用 trailmark 技能）
• 变异测试分类（请使用 genotoxic 技能）
• 非代码派生的架构图（请手动绘制）

前置条件

必须安装 trailmark。如果 uv run trailmark 失败，请运行：

uv pip install trailmark

不要退而求其次通过阅读源代码手动编写 Mermaid。脚本使用 Trailmark 解析后的图以确保准确性。如果安装失败，请向用户报告错误。

---

快速开始

uv run {baseDir}/scripts/diagram.py \
    --target {targetDir} --language auto --type call-graph \
    --focus main --depth 2

输出为原始 Mermaid 文本。请包裹在围栏代码块中：

```mermaid
flowchart TB
    ...
```

---

图表类型

├─ "谁调用了谁？"               → --type call-graph
├─ "类继承关系？"               → --type class-hierarchy
├─ "模块依赖关系？"             → --type module-deps
├─ "类成员和结构？"             → --type containment
├─ "复杂度最高的地方？"         → --type complexity
└─ "从输入到函数的路径？"       → --type data-flow

每种类型的详细示例，请参见
references/diagram-types.md。

---

工作流程

图表进度：
- [ ] 步骤 1：验证 trailmark 已安装
- [ ] 步骤 2：根据用户请求确定图表类型
- [ ] 步骤 3：确定焦点节点和参数
- [ ] 步骤 4：运行 diagram.py 脚本
- [ ] 步骤 5：验证输出非空且格式正确
- [ ] 步骤 6：将图表嵌入响应中

步骤 1： 运行 uv run trailmark analyze --language auto --summary {targetDir}。如果失败则安装。然后通过编程 API 运行预分析：

from trailmark.query.api import QueryEngine

engine = QueryEngine.from_directory("{targetDir}", language="auto")
engine.preanalysis()

预分析会丰富图数据，添加影响范围、污点传播和特权边界信息，这些数据用于 data-flow 图表。

如果自动检测目标语言错误，请使用显式语言或逗号分隔列表重新运行，例如 python,rust。

步骤 2： 使用上述决策树将用户请求匹配到 --type。

步骤 3： 对于 call-graph 和 data-flow，确定焦点函数。默认 --depth 2。对于依赖流，使用 --direction LR。

步骤 4： 运行脚本并捕获标准输出。

步骤 5： 检查：输出以 flowchart 或 classDiagram 开头，且至少包含一个节点。如果为空或格式错误，请查阅 references/mermaid-syntax.md。

步骤 6： 将输出包裹在 ```mermaid ``` 代码围栏中。

---

脚本参考

uv run {baseDir}/scripts/diagram.py [OPTIONS]

参数	缩写	默认值	描述
--target	-t	必填	要分析的目录
--language	-l	python	源代码语言
--type	-T	必填	图表类型（见上文）
--focus	-f	无	以该节点为中心绘制图表
--depth	-d	2	BFS 遍历深度
--direction		TB	布局：TB（从上到下）或 LR（从左到右）
--threshold		10	complexity 类型的最小复杂度

示例

# 以某个函数为中心的调用图
uv run {baseDir}/scripts/diagram.py -t src/ -T call-graph -f parse_file

# Rust 项目的类层次结构
uv run {baseDir}/scripts/diagram.py -t src/ -l rust -T class-hierarchy

# 模块依赖图，从左到右
uv run {baseDir}/scripts/diagram.py -t src/ -T module-deps --direction LR

# 类成员
uv run {baseDir}/scripts/diagram.py -t src/ -T containment

# 复杂度热力图（阈值 5）
uv run {baseDir}/scripts/diagram.py -t src/ -T complexity --threshold 5

# 从入口点到特定函数的数据流
uv run {baseDir}/scripts/diagram.py -t src/ -T data-flow -f execute_query

---

自定义

方向： 使用 TB（默认）用于层次视图，LR 用于从左到右的流（如依赖链）。

深度： 增加 --depth 以查看更多调用图。减少以降低杂乱。如果图表超过 100 个节点，脚本会发出警告。

焦点： 对于非平凡的代码库，call-graph 始终使用 --focus。对于 data-flow，省略焦点会自动定位复杂度最高的前 10 个热点。

语言： 对于多语言或不熟悉的仓库，优先使用 --language auto。仅当确定目标是单一语言或需要排除无关组件时，才使用显式语言。

---

支持文档

• references/diagram-types.md - 每种图表类型的详细文档和 Mermaid 示例
• references/mermaid-syntax.md - ID 清理、转义、样式定义和常见陷阱