# debug-tree

**Repository Path**: ai2o333/debug-tree

## Basic Information

- **Project Name**: debug-tree
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-20
- **Last Updated**: 2026-06-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Debug Tree — 计算模块调试工具集

一套用于调试计算模块（量子化学、数值模拟、科学计算）的skill。

## 安装
Claude Code用户：

```bash
git clone https://gitee.com/ai2o333/debug-tree.git ~/.claude/skills/
```

Claude Code 在下次启动时自动发现 skill。
尚未在其他编程工具测试过。不过可以git clone后和ai沟通怎么使用。推荐superpowers:writing-skills

## 功能

### `debug-tree` — 系统化检查点调试（主入口）
**核心用途：对写出来的代码加入检查点树并依赖检查点树进行debug。** 在理想情况下，假设检查点n正确而检查点n+1错误，即可断定n-n+1之间存在问题。对于**正确**的判断标准笔者做出的排序即为下面所写的四层判断。  
如果在每个检查点都存在可以信任的benchmark值(一般需要存在参考程序)，那么debug的过程就可以完全用这套流程公式化。如果不存在值而只存在推导的理论，该skill会把物理量索引到checkpoint-tree上(这一点写在coherence skill里面)。

- 加载检查点树，收集 debug 输出，二分搜索定位 bug
- 四层判断：T1 参考程序输出对比 → T2 参考源码逻辑推导 → T3 公式文档验证 → T4 AI 自检
- T2 失败时调用 `coherence` 做物理/数学自洽性验证
- 从粗粒度检查点逐层展开到细粒度代码区间
- 检查点树缺失或过期时自动调用 `trace-tree` 生成/更新

### `trace-tree` — 构建和展开检查点树

- 扫描调用链，识别逻辑计算阶段
- 将每个阶段映射到当前代码、参考源码、推导文档（逻辑对应，非逐行翻译）
- 插入条件 debug 打印（环境变量控制，默认关闭）
- 按需将粗粒度节点展开为细粒度子树
- 语义文件存在时自动填充 `computes` 字段，为 `coherence` 建立代码↔数学变量的桥接

### `coherence` — 物理/数学自洽性验证

- **无需参考程序**即可验证模块内部数学自洽性
- 7 种内置检查模式：链式法则、有限差分、对称性、守恒律、量纲分析、迭代收敛、支线独立性
- 三层策略匹配：通用模式库 → 从文档公式推理 → 联网搜索
- 失败项映射回 checkpoint 节点 → 代码行号
- 可独立调用，也可由 `debug-tree` 在 T2 失败时自动调用

### `write-documentation` — 文档写作规范
**核心用途：在已有代码的前提下通过代码写出理论推导，** 可用于用户学习理论本身/用户了解理论和代码的对应关系, 生成的文档也可以作为coherence skill的知识进行学习。同时集成了代码注释规范。

- 两种范式：**A**（公式推导主线，适合物理推导）和 **B**（数据流主线，适合代码文档）
- 硬性要求：每个变量标注物理意义 + 单位 + 在公式中的角色
- 添加注释规范：Rust三层注释结构：`//!` 模块级 → `///` 条目级 → `//` 仅行内简短标注
- 为调试工作流提供基础：好文档让 `trace-tree` 精确标记节点、`coherence` 自动推导语义文件

## 架构

`debug-tree` 是主入口，其余 skill 由其按需调度。笔者平时自己会独立调度的是write-documentation和debug-tree

```
用户: "模块 X 算错了"
  │
  ▼
 debug-tree ──(缺 tree?)──→ trace-tree
     │                           ↑
     │ (T2 失败?)                 │ (展开节点)
     ▼                           │
 coherence ──(失败映射到节点)────┘
     │
     │ (Step 0 选项 D: 先写文档)
     ▼
 write-documentation
```

- **文件是状态媒介**：skill 之间通过 `checkpoints/<module>.yaml` 和 `<module>_semantics.yaml` 通信
- **语言无关**：当前程序和参考程序可用任何语言
- **每个 skill 可独立调用**，供高级用户直接使用

## 使用场景

### 1. 有可供对比的程序，能加 debug 输出 → `trace-tree` + `debug-tree`

```
用户: "SMD CDS 梯度错了。Fortran 参考在 mnsol.F。"

trace-tree 生成 Rust↔Fortran 对照树，在两侧插入 debug 打印。
debug-tree 收集输出，沿 T1（数值对比）二分搜索。
直接定位到出错的代码区间。
```

### 2. 有原理性文档 → 将符号追踪到检查点树上

```
用户: "我有 smd_cds_gradient.md，含完整公式推导。"

trace-tree 生成树，节点标注 doc_ref。
debug-tree 将每个公式项映射到 checkpoint 节点。
coherence 读取文档，提取变量依赖关系，
自动推导语义文件，执行链式法则/量纲检查。
失败项直接定位到具体节点和代码行。
```

### 3. 无参考程序，无原理文档 → `coherence` 独立使用

```
用户: "新模块能量算错了。没有参考代码，也没有文档。"

coherence Step 0: 语义文件缺失。
  → 选项 D: 调用 write-documentation 从代码起草文档
  → 从文档自动推导语义文件
  → 执行静态检查：链式法则、量纲、支线独立性
  → 可选：生成有限差分扰动脚本供用户运行
全部通过? bug 在别处（输入、边界条件、单位转换）。
有失败? 通过 source_func 名映射到代码位置。
```


## 写在最后
我也不知道是出于什么心态写这个skill的，可能是“打不过就加入”，~~也有可能是想把大脑优化掉了~~:innocent: