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 启动时自动加载。 不要进行全量测试，系统内存会被占满。

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 中都有同名小写版本。

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

_pure 后缀（仅 9 个函数）

_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_phase	当前阶段：translate / integrate / verify / done
.f2r_tasks	当前阶段待办列表（每行一个，完成后加 ✅ 前缀）
.f2r_complete	存在 = 全部完成，脚本自动停止
.f2r_rate_limit	API 限流重置时间，脚本自动管理

读取状态的规则

1. 启动时读取 .f2r_phase 确定阶段
2. 读取 .f2r_tasks 取第一个未完成任务
3. 完成后在 .f2r_tasks 中该任务行首加 ✅
4. 全部完成后更新 .f2r_phase 并生成新 tasks

参考文档（按需查阅）

阶段	文件	使用时机
Phase 1 翻译	references/phase1-translate.md	发现翻译遗漏时
Phase 3 验证	references/phase3-verify.md	Phase 2 完成后

---

当前阶段：Phase 2 集成（integrate）

目标：将已翻译的纯计算函数连接为可运行的编排流程。

任务和工作流详见 references/phase2-integrate.md。

---

自动化模式（定时任务触发）

定时任务 scripts/specf2r.sh 通过 --print 触发本 skill。 触发后必须立即按以下流程执行。

执行流程

Step 0: 读取状态
  → 读取 .f2r_phase 确定阶段
  → 读取 .f2r_tasks 取第一个未完成任务
  → 没有未完成任务 → 更新阶段，生成新 tasks
  → 没有更多阶段 → 创建 .f2r_complete

Step 1: 检查索引（仅确认健康，不扫描）
  → codegraph_status

Step 2: 执行当前任务
  → 分析目标函数/模块
  → 实现修改
  → 编译验证

Step 3: 更新状态
  → 标记任务完成 ✅
  → 取下一个任务继续

规则

┌─────────────────────────────────────────────────────────────────┐
│  ❌ 禁止询问用户"是否继续"                                       │
│  ❌ 禁止生成总结报告后停下                                       │
│  ❌ 禁止重复验证"所有函数已翻译"                                  │
│  ❌ 禁止做无目标的全面扫描                                       │
│                                                                   │
│  ✅ 读取 .f2r_tasks → 执行第一项 → 验证 → 标记 → 下一项           │
│  ✅ 只输出：做了什么 + 结果                                       │
└─────────────────────────────────────────────────────────────────┘

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

指标	数值
TLUSTY Fortran 函数	350 (100% 翻译)
SYNSPEC Fortran 函数	168 (100% 翻译)
Rust 总模块数	~495
编译	✅ 0 错误
当前阶段	Phase 2: 集成

故障排查

问题	解决方案
MCP 工具无响应	/reload-plugins
索引返回 0 文件	重建索引：rm -rf .codegraph && node .../codegraph.js init -i
查询结果为空	codegraph_search 模糊搜索
重复结果	优先信任 tlusty/tlusty208.f 原始文件

文件路径

内容	路径
CodeGraph 索引	.codegraph/
CodeGraph 二进制	/home/dckj/program/codegraph/dist/bin/codegraph.js
MCP 配置	.mcp.json
Fortran 源码（原始）	tlusty/tlusty208.f、synspec/synspec54.f
Fortran 源码（提取）	tlusty/extracted/*.f、synspec/extracted/*.f
Rust 源码	src/tlusty/、src/synspec/
定时任务脚本	scripts/specf2r.sh
阶段状态	.f2r_phase、.f2r_tasks、.f2r_complete