diagramming-code

代码图示

根据 Trailmark 的代码图谱生成 Mermaid 图表。预置脚本负责生成 Mermaid 语法；Claude 选择图表类型和参数。Trailmark 0.4.0 内置了 trailmark diagram 命令；仅在检查版本和命令后使用，否则使用此技能捆绑的脚本。

适用场景

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

不适用场景

• 查询图谱但无需可视化（使用 trailmark 技能）
• 突变测试分流（使用 genotoxic 技能）
• 并非从代码推导出的架构图（手动绘制）

前置条件

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

uv tool install trailmark
# Python snippets: uv run --with trailmark python -   (a tool env is not importable)

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

版本检查

检查是否支持原生 v0.4 图表功能：

trailmark diagram --help 2>/dev/null || uv run trailmark diagram --help 2>/dev/null

如果成功，可以使用 trailmark diagram。如果失败，请使用 uv run {baseDir}/scripts/diagram.py，以保留旧版技能工作流。不要假设 Trailmark 0.2.x 中存在原生 CLI。

---

快速入门

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

# Trailmark 0.4.0+ equivalent after the Version Gate succeeds
uv run trailmark diagram \
    --target {targetDir} --language auto --type call-graph \
    --focus <function> --depth 2

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

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

---

图表类型

├─ "Who calls what?"               → --type call-graph
├─ "Class inheritance?"             → --type class-hierarchy
├─ "Module dependencies?"           → --type module-deps
├─ "Class members and structure?"   → --type containment
├─ "Where is complexity highest?"   → --type complexity
└─ "Path from input to function?"   → --type data-flow

各类型的详细示例请参阅 references/diagram-types.md。

---

工作流

Diagram Progress:
- [ ] Step 1: Verify trailmark is installed
- [ ] Step 2: Identify diagram type from user request
- [ ] Step 3: Determine focus node and parameters
- [ ] Step 4: Run diagram.py script (or native trailmark diagram on v0.4+)
- [ ] Step 5: Verify output is non-empty and well-formed
- [ ] Step 6: Embed diagram in response

步骤 1： 运行 uv run trailmark analyze --language auto --summary {targetDir}。如果失败，请安装。绘制图表时不要运行 engine.preanalysis()：图表命令会自行构建图谱，不使用预分析数据，因此无论是否运行预分析，各种图表类型的结果都相同。data-flow 使用 Trailmark 解析时记录的入口点。

如果自动检测出的目标语言不正确，请使用明确指定的语言或逗号分隔的语言列表（例如 python,rust）重新运行。

步骤 2： 根据上面的决策树，将用户请求对应到 --type。

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

步骤 4： 运行脚本并捕获标准输出。 如果原生 v0.4 CLI 可用，两种命令均可；若需要与此技能参考内容保持一致的行为，请优先使用捆绑脚本。

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

步骤 6： 用 ```mermaid ``` 围栏代码块包裹输出。

---

脚本参考

uv run {baseDir}/scripts/diagram.py [OPTIONS]
# or, on Trailmark 0.4.0+:
uv run trailmark diagram [OPTIONS]

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

示例

# Call graph centered on a function
uv run {baseDir}/scripts/diagram.py -t src/ -l auto -T call-graph -f parse_file

# Class hierarchy for a Rust project
uv run {baseDir}/scripts/diagram.py -t src/ -l rust -T class-hierarchy

# Module dependency map, left-to-right
uv run {baseDir}/scripts/diagram.py -t src/ -l auto -T module-deps --direction LR

# Class members
uv run {baseDir}/scripts/diagram.py -t src/ -l auto -T containment

# Complexity heatmap (threshold 5)
uv run {baseDir}/scripts/diagram.py -t src/ -l auto -T complexity --threshold 5

# Data flow from entrypoints to a specific function
uv run {baseDir}/scripts/diagram.py -t src/ -l auto -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 清理、转义、样式定义和常见问题