191 lines
7.9 KiB
Markdown
191 lines
7.9 KiB
Markdown
---
|
||
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: 更新状态
|
||
→ 标记任务完成 ✅
|
||
→ 取下一个任务继续
|
||
```
|
||
|
||
### 规则
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ ❌ 禁止询问用户"是否继续" │
|
||
│ ❌ 禁止生成总结报告后停下 │
|
||
│ ❌ 禁止重复验证"所有函数已翻译" │
|
||
│ ❌ 禁止做无目标的全面扫描 │
|
||
│ ❌ 禁止只编译不运行（cargo build 通过 ≠ 完成） │
|
||
│ ❌ 禁止"格式正确+0 NaN"就标记完成（必须数值对比 Fortran 参考输出） │
|
||
│ ❌ 禁止用"expected at this stage"跳过已知问题 │
|
||
│ ❌ 禁止在 phase=done 时机械创建 .f2r_complete │
|
||
│ │
|
||
│ ✅ 读取 .f2r_tasks → 执行第一项 → 编译 → 运行 → 标记 → 下一项 │
|
||
│ ✅ 运行验证：程序必须产出非空 fort.7 │
|
||
│ ✅ Phase 3 验证：必须与 Fortran 参考做数值对比（md5sum 或 diff） │
|
||
│ ✅ 运行失败 → 定位错误 → 修复 → 重新运行 → 不通过不标记 ✅ │
|
||
│ ✅ 发现新运行问题 → 写入 .f2r_tasks（即使认为是"expected"） │
|
||
│ ✅ 创建 .f2r_complete 前：确认两个程序输出都与 Fortran 匹配 │
|
||
│ ✅ 只输出：做了什么 + 运行结果 │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### Phase 3 验证硬性标准
|
||
|
||
创建 `.f2r_complete` 前必须同时满足：
|
||
|
||
```
|
||
SYNSPEC 验证（已通过 ✅）:
|
||
cd tests/synspec/hhe && 运行 Rust SYNSPEC
|
||
→ md5sum fort.7 必须与 Fortran 参考 fort.7 一致
|
||
|
||
TLUSTY 验证（当前未通过）:
|
||
cd tests/tlusty/hhe_rust && 运行 Rust TLUSTY
|
||
→ md5sum fort.7 必须与 tests/tlusty/hhe_fortran/fort.7.ref 一致
|
||
→ 或逐行数值偏差 < 1%（DM, T, Ne, Rho 四列全部）
|
||
如果不满足 → 不能标记 phase=done，不能创建 .f2r_complete
|
||
```
|
||
|
||
## 当前翻译状态（2026-06-12）
|
||
|
||
| 指标 | 数值 |
|
||
|------|------|
|
||
| TLUSTY Fortran 函数 | 350 (100% 翻译) |
|
||
| SYNSPEC Fortran 函数 | 168 (100% 翻译) |
|
||
| Rust 总模块数 | ~495 |
|
||
| 编译 | ✅ 0 错误 |
|
||
| 当前阶段 | **Phase 3: 验证** |
|
||
| SYNSPEC 验证 | ✅ fort.7 逐字节匹配 |
|
||
| TLUSTY 验证 | ❌ DM 偏差 <42%, T 偏差 <8%（需 ROSSOP 集成）|
|
||
|
||
## 故障排查
|
||
|
||
| 问题 | 解决方案 |
|
||
|------|---------|
|
||
| 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` |
|