SpectraRust/.claude/skills/codegraph-guide/SKILL.md

name	description
codegraph-guide	CodeGraph 辅助 Fortran→Rust 重构。触发条件： (1) 开始翻译新的 Fortran 函数前，需要了解其调用关系 (2) 检查某个函数是否已翻译、翻译是否完整 (3) 查找 Fortran 有但 Rust 没有的函数（翻译遗漏） (4) 对比 Fortran 和 Rust 的调用链是否一致 (5) 用户提及 "codegraph"、"调用图"、"谁调用了"、"依赖关系"

CodeGraph 辅助 F2R 重构

本项目已配置 CodeGraph MCP 服务器（.mcp.json），Claude 启动时自动加载。 CodeGraph 索引了 Fortran 原始文件（tlusty/tlusty208.f、synspec/synspec54.f）和 Rust 源码（src/），生成统一的 SQLite 代码图谱。

MCP 工具

工具	用途	示例
codegraph_explore	主力——自然语言或符号名查询，一次返回相关源码+调用关系	codegraph_explore "initia 如何初始化频率网格"
codegraph_search	按名称模糊搜索符号	codegraph_search "eldens"
codegraph_node	查看符号详情（完整源码、签名、调用者/被调用者）	codegraph_node "steqeq"
codegraph_callers	谁调用了该符号	codegraph_callers "initia"
codegraph_callees	该符号调用了谁	codegraph_callees "steqeq"
codegraph_impact	修改某符号会级联影响哪些符号	codegraph_impact "steqeq" depth=2
codegraph_files	浏览目录结构和文件符号数	codegraph_files "src/tlusty/math/hydrogen"
codegraph_status	索引健康检查（文件数、节点数、边数）	codegraph_status

所有查询直接使用 MCP 工具，不需要手写 SQL。

命名约定

函数命名：Fortran 与 Rust 完全对应

所有 TLUSTY Fortran 函数在 Rust 中都有同名小写版本。不再使用 _pure 后缀 （已于 2026-06-05 批量清理）。

Fortran:  RECHECK   ACCEL2   INITIA   STEKEQ   ELDENS
Rust:     rechck    accel2   initia   steqeq   eldens

CodeGraph 可以自动通过 lower(name) 匹配跨语言符号。

_pure 后缀的例外（仅 9 个函数）

以下函数同时有 _pure 和非-pure 两个版本，两者用途不同：

_pure 版本	非-pure 版本	关系
steqeq_pure	steqeq	纯计算内核 → 通过回调串联子程序的完整版本
resolv_pure	resolv	纯线性化求解 → 串联 28 个子程序的完整版本
start_pure	start	纯启动计算 → 带完整 I/O 的版本
solve_pure	solve	纯矩阵求解 → 完整求解器
inkul_pure	inkul	纯 Kurucz 谱线数据 → 带文件 I/O 的版本
lemini_pure	lemini	纯 Lemke 表插值 → 带表查询的版本
radtot_pure	radtot	纯辐射通量 → 完整辐射传输
rayini_pure	rayini	纯瑞利散射初始化 → 带文件读取的版本
iroset_pure	iroset	纯铁族元素设置 → 带回调的完整版本

规则：_pure = 纯计算内核（可独立测试），非-pure = 完整编排包装器（匹配 Fortran 行为）。

F2R 翻译工作流

Step 0: 数据同步

每次 Rust 代码修改后，MCP 文件监视器会自动同步（2秒延迟）。如有疑问可手动触发：

cd /home/fmq/program/SpectraRust
node /home/fmq/program/codegraph/dist/bin/codegraph.js sync

如果添加了新目录或数据异常，重建：

rm -rf .codegraph
node /home/fmq/program/codegraph/dist/bin/codegraph.js init -i

Step 1: 选择翻译目标

使用 fortran-analyzer skill 获取优先模块。然后用 CodeGraph 了解依赖：

codegraph_explore "<目标函数> 的调用链和依赖"   ← 一次性了解上游+下游
codegraph_impact <目标函数>                    ← 了解修改影响范围

关键规则：如果下游函数还没翻译，必须优先翻译它们。

Step 2: 翻译函数

用 codegraph_node <函数名> 获取完整信息：

• Fortran 源码（完整函数体）
• 所在文件和行号
• 签名、参数、返回值
• 所有调用者和被调用者列表

对照 Fortran 源码逐行翻译。翻译后的 Rust 函数直接使用 Fortran 同名小写， 例如 ELDENS → pub fn eldens(...)。

Step 3: 验证调用链一致性

翻译完成后对比 Fortran 和 Rust 的调用链：

codegraph_explore "<函数名> Fortran vs Rust 调用链对比"

两边的被调用者列表应该结构一致（Rust 端用 snake_case，Fortran 端用 UPPER_CASE）。 如果 Rust 端缺少被调用者 → 可能需要创建非-pure 编排包装器。

Step 4: 完整性检查

codegraph_search <Fortran函数名>   ← 确认 Rust 中有同名小写实现
codegraph_callers <函数名>         ← 确认 Rust 端有对应的调用者

翻译完整性判断

计算逻辑完整（_pure/同名版本）

函数的核心算法已翻译，但不直接调用子程序。占 TLUSTY 的绝大多数。

编排完整（非-pure 包装器）

函数不仅包含计算逻辑，还通过回调或直接调用来串联子程序，完整匹配 Fortran 行为。 目前仅 9 个函数有此版本。

判断标准

codegraph_callees <函数名>   ← Rust 端
codegraph_callees <函数名>   ← Fortran 端（用大写名）

• 两边被调用者列表完全匹配 → 编排完整
• Rust 端缺少被调用者 → 计算逻辑完整，需编排包装器
• Rust 端没有该函数 → 未翻译

实际案例

检查 INITIA 翻译完整性

codegraph_explore "initia Fortran Rust 对比"
→ Fortran INITIA 调用: LEVSET, NSTPAR, STATE0, STATE, RDATA, LINSET...
→ Rust initia 调用: generate_log_frequency_grid, init_reciprocal_powers...
→ 结论: Rust 版本是简化实现，缺少大部分 Fortran 子程序调用
→ 状态: 计算框架存在，需编排包装器

快速了解函数被谁依赖

codegraph_callers ELDENS
→ Fortran: CONREF, ROSSOP, TEMPER, RHOEN, TRMDER (5 个)
→ Rust: rybchn, rhonen, trmder, resolv (4 个)
→ 差异: rossop 未调用 → 需检查 rossop 翻译状态

查找遗漏

codegraph_status                → 先看总体统计
codegraph_search "<逐个查>"     → 确认 Fortran 名在 Rust 中是否存在

评估修改影响

codegraph_impact "steqeq" depth=2
→ 修改 steqeq 会影响: hesolv, elcor, rybsol, steqeq_pure (12 个符号)
→ 其中 2 个在 Fortran 端 (RYBSOL, TLUSTY), 10 个在 Rust 端

当前翻译状态（2026-06-05）

指标	数值
TLUSTY Fortran 函数	350
TLUSTY Rust 匹配	350 (100%)
计算逻辑完整	~309 函数
编排完整（非-pure 包装器）	9 函数
RESOLV 编排进度	24/42 被调用者 (57%)
计算逻辑存在但缺编排	41 函数
SYNSPEC 待翻译	61 函数

已知限制

1. 不跨语言语义映射：CodeGraph 按名称匹配，不知道 Fortran ELDENS 和 Rust eldens 是同一个函数——但它支持大小写不敏感查询，所以这不是问题。
2. 文件监视器 2 秒延迟：修改 Rust 代码后等 2 秒再查询，或手动 codegraph sync。
3. 提取文件可能有冗余：tlusty/extracted/ 和 synspec/extracted/ 中的函数与原始文件重复（平均 2.2 次），MCP 工具查询时可能返回重复结果。优先信任原始文件（tlusty/tlusty208.f）中的结果。
4. Fortran 调用边覆盖率 ~98.3%：约 1.7% 的调用（~22 条）来自语法解析错误的区域，caller 显示为 <anonymous>。