---
name: codegraph-guide
description: |
  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` |