docs: 综合三工具六版本分析，输出 workbuddy_v2.md

基于 workbuddy.md / claude.md / codex.md 三份原始分析
及 claude_v1.md / codex_v1.md / workbuddy_v1.md 三份综合
版本，输出最终优化方案。

核心改进：
- 三工具角色定位框架（QA/Perf/Architect）
- Bug 三级分类（真 Bug / 已修复 / 疑似误报）
- 三阶段方案（修正确性→做性能→做治理）
- 自我评价与修正（v1→v2 改进表）
- 10 场景工具选择速查表

optimization/claude_v1.md

@@ -0,0 +1,459 @@
+# Dynamics 项目优化方案综合报告
+
+> 整合日期：2026-06-12  
+> 来源文档：[`claude.md`](claude.md)（Claude Sonnet 4.6 分析）、[`workbuddy.md`](workbuddy.md)（WorkBuddy 分析）  
+> 项目路径：`D:\Share\Data\aliyun-gitea\dynamics`
+
+---
+
+## 第一部分：两份分析报告的评价与对比
+
+### 1.1 WorkBuddy 分析报告评价（`workbuddy.md`）
+
+#### 优势
+
+**① 架构视野宏观、分层清晰**  
+WorkBuddy 从整体软件工程角度出发，明确指出 `compute.py` 的职责混乱问题（1618 行同时承担物理引擎、文件 I/O、参数加载、外部引擎管理五种职责），并给出了完整的模块拆分方案：
+
+```
+compute/
+├── core.py        # 物理引擎
+├── io.py          # 文件 I/O
+├── params.py      # 参数加载
+├── runner.py      # 运行管理
+├── engine_helper.py  # 外部引擎
+└── main.py        # 主入口
+```
+
+这是一个系统性重构方向，有助于长期维护。
+
+**② 关注工程规范与测试**  
+WorkBuddy 专门开辟了"测试与质量"一节，强调了缺少单元测试的风险，并给出了类型标注的示例代码——这两点是 claude.md 未涉及的。对于一个教学/研究用项目，有测试才能安全重构。
+
+**③ 配置管理建议具体**  
+提出了将 `ball_color_r/g/b` 三个键合并为 `ball_color: [r,g,b]` 数组的配置统一方案，以及6个案例 `input.txt` 格式不统一的问题（如 `save_trajectory`、`camera_*` 字段缺失），并给出了统一模板，实操性强。
+
+**④ 引擎一致性梳理全面**  
+清晰列出了 C/C++/Fortran 三引擎在 `save_trajectory`、`box_a` 默认值等参数上的差异表格，对用户切换引擎有直接指导价值。
+
+**⑤ 区分"已完成"与"待做"**  
+文档中标注了"✅ 已修复"、"✅ 已完成"条目，帮助读者快速定位当前状态，避免重复分析。
+
+#### 劣势
+
+**① 缺少具体 Bug 定位**  
+WorkBuddy 的分析主要停留在架构和规范层面，对于已经导致运行崩溃的 Bug（如 `plot_wave.py` 格式不匹配、`run_simulation` 中 `config` 未定义）没有识别和标注。用户按此文档操作时，可能先花时间做重构，但基础功能仍然崩溃。
+
+**② 性能优化建议较抽象**  
+对 Python 引擎性能仅建议"使用 Numba JIT"或"numpy.vectorize"，缺少具体的向量化代码示例。文档注明"Python vs C 慢约 6-8 倍"，但未分析哪个函数是瓶颈（实际上是弹簧力的 Python for 循环）。
+
+**③ 部分建议颗粒度不足**  
+"消除全局变量"建议封装为 `SimulationState` 数据类，但未说明：封装后接口如何调整、外部引擎的 `param.json` 协议是否需要同步更新、draw.py 的全局变量是否属于同一重构范围。
+
+**④ 优先级排列有待商榷**  
+将"全局变量封装"列为 P0（与 Fortran 引擎修复同级），但封装全局变量是一项重构工作（3-4h），而 Fortran 引擎崩溃是已存在的功能阻断性问题，两者紧迫性不同。
+
+---
+
+### 1.2 Claude 分析报告评价（`claude.md`）
+
+#### 优势
+
+**① Bug 定位精准，附有复现条件**  
+每个 Bug 都说明了触发条件（"只要使用 `engine: python`"、"`step_plot_wave: 1` 时"），以及为什么当前没有爆发（"当前所有案例恰好设置 `step_plot: 0`"）。这对于开发者复现和验证问题极有价值。
+
+**② 代码级修复方案完整**  
+每个 Bug 都给出了完整可运行的修复代码，包括需要修改的行号、修改前后的对比。特别是 B3（`plot_wave.py` 格式不匹配）不仅指出问题，还解释了为何修复较复杂（`atom_masses` 等物理量在新格式中缺失，需要同步扩展 header 字段），给出了分层的修复路径（快速修复 vs 彻底修复）。
+
+**③ 弹簧力向量化方案具体可行**  
+给出了完整的 NumPy 向量化代码，包括处理重复索引的 `np.add.at` 用法，以及链状体系可进一步优化为直接索引的提示。预期加速 5-15 倍的估算也有根据（119 键 × 100,000 步的量级分析）。
+
+**④ 引擎差异的量化说明**  
+指出了 `engines/cpp/param.json` 中 `save_trajectory` 默认值为 1（与 C 引擎的 0 不一致），并说明了实际影响（切换引擎时可能意外生成大文件）。
+
+#### 劣势
+
+**① 覆盖面刻意与 workbuddy.md 错开，造成视野盲区**  
+claude.md 开篇声明"不与 workbuddy.md 重复"，因此主动跳过了架构、测试、配置管理等方向。但这导致文档读者如果只看 claude.md，会误以为架构是没问题的。两份文档需要结合阅读，割裂感较强。
+
+**② 部分建议依赖全局变量方案**  
+claude.md 提出的 Bug B1 修复方案（将 `camera_distance` 等加入全局变量）是在全局变量模式下的补丁式修复，与 workbuddy.md 建议的"封装全局变量为类"方向相反。若未来执行 workbuddy.md 的重构，B1 的修复需要再次调整。
+
+**③ 某些结论尚未验证**  
+文档末尾注明"基于代码静态分析，未实际运行测试验证"。例如 B3（`plot_wave.py` 格式不匹配）的结论基于函数调用链分析，如果 `load_text_data` 内部有容错逻辑，实际情况可能不同。
+
+**④ 缺乏对 draw.py 的深入分析**  
+draw.py 是用户交互最频繁的模块（3D 动画播放），但 claude.md 仅指出了一处裸 `except`（B5），未分析动画帧率优化、大原子数渲染性能等用户体验层面的问题。
+
+---
+
+### 1.3 两份报告对比总结
+
+| 维度 | WorkBuddy | Claude |
+|------|-----------|--------|
+| **Bug 识别** | ❌ 未发现运行时 Bug | ✅ 识别 5 个确认 Bug，附触发条件 |
+| **性能优化** | 🟡 方向正确但缺代码 | ✅ 完整向量化代码示例 |
+| **架构设计** | ✅ 完整模块拆分方案 | ❌ 刻意回避，未覆盖 |
+| **测试建议** | ✅ pytest 方案具体 | ❌ 未涉及 |
+| **配置管理** | ✅ 6 案例统一模板 | ❌ 未涉及 |
+| **引擎一致性** | ✅ 参数差异表格 | ✅ 补充了势能归属约定 |
+| **修复代码** | 🟡 仅有架构示意 | ✅ 逐条给出可运行代码 |
+| **优先级合理性** | 🟡 P0 安排有误 | ✅ 按紧迫性分层清晰 |
+| **可独立阅读** | ✅ 自成体系 | ❌ 依赖读者已读 workbuddy.md |
+| **当前状态标注** | ✅ 已完成项有标注 | ❌ 未区分 |
+
+**结论**：WorkBuddy 擅长系统性架构分析和工程规范，Claude 擅长 Bug 精确定位和具体修复代码。两份报告互补，单独使用任何一份都存在明显盲区。
+
+---
+
+## 第二部分：综合优化方案
+
+### 原则
+
+基于以上分析，综合方案遵循以下原则：
+1. **先止血再手术**：运行时 Bug 优先于架构重构，不能让教学演示功能处于崩溃状态
+2. **快速收益优先**：同等重要性时，工作量小的先做
+3. **向量化先于重构**：Python 引擎提速不依赖架构改动，可独立进行
+4. **渐进式重构**：全局变量封装等重构分阶段进行，避免一次性大改引入新 Bug
+
+---
+
+### 阶段一：紧急修复（总工作量约 4 小时）
+
+> 目标：恢复所有已有功能到正常可用状态
+
+#### 1. 修复 `plot_wave.py` 格式不匹配（B3）— 1.5h
+
+**根本原因**：`display.txt` 格式从 JSON 迁移到新文本格式时，`plot_wave.py` 未同步更新。
+
+**修复步骤**：
+
+① 修改加载函数（`plot_wave.py:22-27`）：
+```python
+def load_disp_data(output_dir):
+    disp_path = os.path.join(output_dir, "display.txt")
+    if not os.path.exists(disp_path):
+        raise FileNotFoundError(f"找不到 {disp_path}")
+    return compute.load_display_txt(disp_path)   # 改为新格式加载
+```
+
+② 在 `save_display_txt`（`compute.py:217`）的 header 中补充 `atom_masses` 字段：
+```python
+# 在 header_fields 中添加
+"atom_masses": ",".join(str(m) for m in ATOM_MASSES),
+```
+
+③ 修改 `plot_wave.py` 中的字段访问：
+```python
+# 旧 → 新
+data["n_frames"]       → disp_data["frames_x"].shape[0]
+data["disp_all_x"]     → disp_data["frames_x"]
+data["atom_masses"]    → np.array([float(x) for x in h.get("atom_masses","").split(",") if x])
+data["atom_ids"]       → disp_data["atom_ids"]
+data["bond_pairs"]     → []   # display.txt 不含成键信息，能量计算中弹性势能项跳过
+```
+
+**验证**：运行 case05（`step_plot_wave: 1`），确认生成 `wave_animation.gif`。
+
+---
+
+#### 2. 修复 `run_simulation()` 中的 `config` 未定义（B1）— 15min
+
+在 `compute.py` 模块顶部（约第 68 行，紧随 `camera_keyframes_raw`）添加全局变量：
+
+```python
+camera_keyframes_raw = ""
+camera_distance  = 40.0    # 新增
+camera_elevation = 0       # 新增
+camera_azimuth   = 0       # 新增
+```
+
+在 `run_from_config`（约第 756 行，`use_marker` 赋值附近）添加：
+```python
+use_marker = int(config.get("use_marker", 0))
+camera_distance  = float(config.get("camera_distance", 40.0))   # 新增
+camera_elevation = float(config.get("camera_elevation", 0))     # 新增
+camera_azimuth   = float(config.get("camera_azimuth", 0))       # 新增
+```
+
+在 `run_from_config` 的 `global` 声明行追加这三个变量：
+```python
+global use_marker, camera_keyframes_raw, camera_distance, camera_elevation, camera_azimuth
+```
+
+在 `run_simulation`（第 1548-1550 行）改为读全局变量：
+```python
+"camera_distance": str(camera_distance),
+"camera_elevation": str(camera_elevation),
+"camera_azimuth": str(camera_azimuth),
+```
+
+**验证**：用 `engine: python` 运行 case01，确认生成正确的 `display.txt`。
+
+---
+
+#### 3. 修复 `dynamics.py` 绘图块死代码（B2）— 30min
+
+`step_plot` 功能依赖完整轨迹数据，但当前架构中 `run_from_config` 不再在主流程中保留这些数据。
+快速修复：添加 "功能暂不可用" 保护，避免用户误开后崩溃：
+
+```python
+# dynamics.py 约 322 行
+if not no_plot and config.get("step_plot", 1):
+    print("[run] 注意：step_plot 绘图功能需要 save_trajectory=1 时的完整轨迹，")
+    print("[run]       当前版本暂未支持，已跳过。如需绘图请联系开发者。")
+```
+
+**长期修复**（阶段三再做）：从 `display.txt` 读取抽帧数据重建绘图逻辑。
+
+---
+
+#### 4. 修复 Fortran 引擎输出格式（E3）— 2h
+
+Fortran 引擎总是输出 JSON 格式 `trajectory.txt`，与 Python 侧期待的 `display.txt` 不兼容，
+使用 `engine: fortran` 时必然崩溃。
+
+参照 C 引擎的 `write_display_txt` 函数（`engines/c/main.c`）在 Fortran 中实现：
+1. 读取 `param.json` 中的 `save_trajectory` 参数
+2. 新增 `write_display_txt_f90` 子程序，按 NSTEP 抽帧写文本格式
+3. 根据 `save_trajectory` 决定是否额外写 `trajectory.txt`
+
+**同时**：将 `engines/cpp/param.json` 中的 `"save_trajectory": 1` 改为 `0`，与 C 保持一致。
+
+---
+
+#### 5. 其他 1-5 分钟的小修复
+
+```python
+# B4: examples/case06/run_dynamics.py:34
+description="运行 Dynamics 示例案例 case06"   # 改 case01 → case06
+
+# B5: draw.py:97
+except (ValueError, AttributeError):           # 改裸 except
+
+# Q1: dynamics.py 顶部
+from compute import _load_camera_motion as _load_camera_kf   # 删除重复实现
+
+# E2: engines/cpp/param.json
+"save_trajectory": 0                            # 统一默认值
+```
+
+---
+
+### 阶段二：性能优化（总工作量约 3 小时）
+
+> 目标：Python 引擎提速 5-10 倍，外部引擎减少启动开销
+
+#### 6. 弹簧力向量化（P1）— 1h
+
+将 `compute.py:1253-1277` 的 Python for 循环替换为 NumPy 向量化版本（见 claude.md §P1 完整代码）。
+
+**链状体系（case01-06）的进一步优化**：  
+由于链状体系每根键的两端没有重复（原子 i 和 j 各只出现一次），可以用更快的直接索引替代 `np.add.at`：
+
+```python
+# 比 np.add.at 快约 3 倍（无冲突索引时）
+fx[i_arr] += fx_bond
+fx[j_arr] -= fx_bond
+fy[i_arr] += fy_bond
+fy[j_arr] -= fy_bond
+fz[i_arr] += fz_bond
+fz[j_arr] -= fz_bond
+```
+
+对于有分叉键的复杂体系仍需用 `np.add.at`，可根据 `BOND_PAIRS` 检测是否有重复端点自动选择路径。
+
+---
+
+#### 7. `apply_fixed_constraints` 预计算掩码（P2）— 30min
+
+将 `compute.py:1408-1418` 的 `column_stack` 方案替换为预计算 bool 掩码，见 claude.md §P2 完整代码。  
+对 case06（120 原子，x/y 全固定）每步节省 2 次 `(120, 3)` 数组分配。
+
+---
+
+#### 8. 外部引擎校准缓存（E4）— 1h
+
+在 `compute.py:924` 校准逻辑前添加缓存命中检查：
+
+```python
+import hashlib, json as _json
+
+def _calib_cache_key(engine, n_atoms, method, dt):
+    s = f"{engine}:{n_atoms}:{method}:{dt}"
+    return hashlib.md5(s.encode()).hexdigest()[:8]
+
+_calib_cache_path = os.path.join(script_dir, "engines", engine, "_calib_cache.json")
+_calib_key = _calib_cache_key(engine, len(ATOM_IDS), config.get("method","leapfrog"), float(config["DT"]))
+_cached = {}
+if os.path.exists(_calib_cache_path):
+    with open(_calib_cache_path) as _cf:
+        _cached = _json.load(_cf)
+
+if _cached.get("key") == _calib_key and time.time() - _cached.get("ts", 0) < 86400:
+    # 缓存命中（1天内有效），跳过校准
+    _step_time = _cached["step_time"]
+    _overhead  = _cached["overhead"]
+else:
+    # 执行校准（现有逻辑）...
+    # 校准完成后写缓存
+    with open(_calib_cache_path, "w") as _cf:
+        _json.dump({"key": _calib_key, "ts": time.time(),
+                    "step_time": _step_time, "overhead": _overhead}, _cf)
+```
+
+**预期收益**：case06 第二次运行节省约 10 秒（校准 10,000 步）。
+
+---
+
+#### 9. 其他微优化（P3/P4）— 30min
+
+```python
+# P3: run_simulation 中删除 frame_indices 列表
+# 删除: frame_indices = []  和  frame_indices.append(step)
+# 替换: n_frames_actual = record_steps // NSTEP  （直接计算）
+
+# P4: apply_driving_force 中删除 t_vec 数组创建
+t_vec = np.array([t, t, t], dtype=np.float64)    # 删除此行
+pos_drive = d["amp"] * np.cos(2.0 * np.pi * d["freq"] * t + d["phi"])   # 直接用标量 t
+```
+
+---
+
+### 阶段三：架构重构（总工作量约 15-20 小时）
+
+> 目标：提升长期可维护性，支持并发模拟、单元测试
+
+> **重要说明**：此阶段是 workbuddy.md 建议的核心，以下是对其建议的细化和补充。  
+> 建议在阶段一、二完成并通过全案例验证后再开始。
+
+#### 10. 全局变量封装为 `SimulationState`（workbuddy.md §3.1）— 3-4h
+
+封装后，阶段一中 B1 的补丁修复（新增三个全局变量）可以一并纳入 `SimulationState`，不需要额外保留。
+
+封装时注意：外部引擎路径（`run_engine`）通过 `param.json` 传参，不受全局变量影响，可独立进行。
+
+#### 11. `compute.py` 模块拆分（workbuddy.md §1.1）— 4-6h
+
+拆分时建议**先拆 io.py**（文件读写），因为它与物理算法完全解耦，风险最低。  
+拆分顺序建议：`io.py` → `params.py` → `core.py` → `runner.py`。
+
+**补充**：同步删除已废弃的 `load_parameters()` 函数（102 行）和已被 `dynamics.py` 取代的 `compute.main()`（25 行），见 claude.md §Q2。
+
+#### 12. 添加单元测试（workbuddy.md §5.1）— 3-5h
+
+优先覆盖以下三类：
+1. 物理算法正确性：以简谐振子解析解验证 leapfrog、midpoint 方法（参照 `tools/NumericalMethods.py` 已有实现）
+2. 文件 I/O 往返一致性：`save_display_txt → load_display_txt` 数值不变
+3. 参数验证边界：质量为 0、键长为负、NT 为 0 等异常输入
+
+#### 13. 案例 `input.txt` 格式统一（workbuddy.md §4.1）— 1-2h
+
+将 `case01-05` 的 `input.txt` 补充缺失字段（`save_trajectory`、`camera_*`、`move_camera`），
+统一 `step_sample: 0`（新版引擎已内置抽帧），清理旧格式注释。
+
+#### 14. `dynamics.py` 绘图功能完整重建（B2 长期修复）— 2h
+
+从 `display.txt` 的抽帧数据重建绘图逻辑（替代依赖完整轨迹的旧实现）：
+
+```python
+disp_data = compute.load_display_txt(disp_path)
+frames_x = disp_data["frames_x"]   # (n_frames, n_atoms)
+# 对每帧计算能量，绘制时序图
+```
+
+能量计算需要质量等物理量，依赖阶段一 B3 修复中在 header 补充的 `atom_masses` 字段。
+
+---
+
+### 三个引擎的综合评价
+
+#### C 引擎（`engines/c/main.c`）
+
+| 维度 | 评价 |
+|------|------|
+| **功能完整性** | ✅ 最完整，支持 `display.txt` 直接输出，`save_trajectory` 控制 |
+| **性能** | ✅ 基准引擎，比 Python 快 6-8 倍 |
+| **一致性** | ✅ `save_trajectory` 默认值为 0，与 Python 行为一致 |
+| **代码质量** | 🟡 JSON 解析为自行实现（非 cJSON 库），维护成本高 |
+| **建议** | 作为参考实现，其他引擎向 C 引擎看齐 |
+
+#### C++ 引擎（`engines/cpp/main.cpp`）
+
+| 维度 | 评价 |
+|------|------|
+| **功能完整性** | ✅ 功能与 C 引擎相当 |
+| **性能** | 🟡 编译产物 3.3 MB（远大于 C 的 504 KB），有优化空间 |
+| **一致性** | ⚠️ `save_trajectory` 默认值为 1（与 C 不一致），已在阶段一修复 |
+| **代码质量** | 🟡 物理算法与 C 引擎重复，应提取到公共头文件 |
+| **建议** | 统一 `param.json` 默认值；考虑与 C 引擎共用物理算法头文件 |
+
+#### Fortran 引擎（`engines/fortran/main.f90`）
+
+| 维度 | 评价 |
+|------|------|
+| **功能完整性** | ❌ 不支持 `display.txt` 直接输出，使用时必然崩溃 |
+| **性能** | ✅ 编译性能与 C 相当，适合大规模计算 |
+| **一致性** | ❌ 输出 JSON 格式 trajectory.txt，与其他引擎行为完全不同 |
+| **代码质量** | 🟡 代码结构清晰，但与 C/C++ 引擎物理算法重复 |
+| **建议** | 阶段一 E3 修复为最高优先级；修复后可成为高性能替代引擎 |
+
+---
+
+### 综合优先级总表
+
+| 阶段 | 编号 | 问题 | 来源 | 优先级 | 预估工时 |
+|------|------|------|------|--------|---------|
+| 一 | B3 | `plot_wave.py` 格式不匹配（波形动画失效） | Claude | 🔴 P0 | 1.5h |
+| 一 | E3 | Fortran 引擎不支持 display.txt | 两者 | 🔴 P0 | 2h |
+| 一 | B1 | `run_simulation` 内 `config` 未定义 | Claude | 🔴 P0 | 15min |
+| 一 | B2 | `dynamics.py` 绘图块死代码 | Claude | 🔴 P0 | 30min |
+| 一 | B4/B5 | 小错误修复（case06 文字、裸 except 等） | Claude | 🟡 P1 | 15min |
+| 一 | Q1/E2 | 重复函数去除、C++ 默认值统一 | Claude | 🟡 P1 | 20min |
+| 二 | P1 | 弹簧力向量化（Python 引擎 5-15x） | Claude | 🟢 P1 | 1h |
+| 二 | E4 | 外部引擎校准缓存 | 两者 | 🟢 P1 | 1h |
+| 二 | P2-P4 | apply_fixed_constraints 等微优化 | Claude | 🟢 P2 | 1h |
+| 三 | 架构 | 全局变量封装为 SimulationState | WorkBuddy | 🔵 P2 | 3-4h |
+| 三 | 架构 | compute.py 模块拆分 | WorkBuddy | 🔵 P2 | 4-6h |
+| 三 | 测试 | 添加 pytest 单元测试 | WorkBuddy | 🔵 P2 | 3-5h |
+| 三 | 配置 | 6 案例 input.txt 格式统一 | WorkBuddy | 🔵 P3 | 1-2h |
+| 三 | 绘图 | dynamics.py 绘图功能重建 | Claude | 🔵 P3 | 2h |
+| 三 | 引擎 | C/C++/Fortran 共用物理算法头文件 | WorkBuddy | 🔵 P3 | 2-4h |
+
+---
+
+## 附录：快速执行清单
+
+### 今天可以完成（总计约 30 分钟的小修复）
+
+```
+[ ] examples/case06/run_dynamics.py:34  "case01" → "case06"
+[ ] draw.py:97  裸 except → except (ValueError, AttributeError):
+[ ] dynamics.py  删除 _load_camera_kf()，改为从 compute 导入
+[ ] engines/cpp/param.json  "save_trajectory": 1 → 0
+[ ] compute.py:1548-1550  config.get → 全局变量（B1 修复）
+```
+
+### 本周可以完成（核心功能恢复）
+
+```
+[ ] plot_wave.py 格式适配（B3）
+[ ] dynamics.py 绘图块保护（B2 临时修复）
+[ ] Fortran 引擎 display.txt 支持（E3）
+[ ] 弹簧力向量化（P1）
+[ ] 引擎校准缓存（E4）
+```
+
+### 下阶段规划（架构改善）
+
+```
+[ ] 全局变量 → SimulationState 类
+[ ] compute.py 拆分为子模块
+[ ] pytest 单元测试套件
+[ ] 案例 input.txt 格式统一
+```
+
+---
+
+*本文档综合 Claude Sonnet 4.6（`claude.md`）与 WorkBuddy（`workbuddy.md`）的分析报告生成。  
+所有代码改动建议均基于静态分析，实施前请先在独立分支验证。*

optimization/workbuddy_v2.md

@@ -0,0 +1,241 @@
+# Dynamics 项目优化方案 — 三工具六版本综合分析 v2
+
+> **分析日期**：2026-06-12  
+> **参与工具**：WorkBuddy（Senior Developer 角色）、Claude（Sonnet 4.6）、Codex（GPT-4o）  
+> **分析范围**：`D:\Share\Data\aliyun-gitea\dynamics` 完整代码库  
+> **参考文档**：
+>   - 原始分析：`workbuddy.md`、`claude.md`、`codex.md`
+>   - 综合版本：`claude_v1.md`、`codex_v1.md`、`workbuddy_v1.md`
+
+---
+
+## 一、三工具角色定位
+
+三份原始分析报告和它们的 v1 版本揭示了三个工具最适合的角色，可以用一句话概括：
+
+> **Claude 是 QA / 审计员，Codex 是性能工程师，WorkBuddy 是架构负责人**
+
+这是一个高度互补的关系，而非互相竞争。
+
+### 1.1 角色矩阵
+
+| 维度 | Claude | Codex | WorkBuddy |
+|------|--------|-------|-----------|
+| **角色类比** | 代码审计员 | 性能工程师 | 架构负责人 |
+| **最擅长** | 找会崩溃的 Bug & 具体修复代码 | 定位性能瓶颈 & 战略优先级 | 模块拆分 & 工程治理 |
+| **最弱项** | 架构视野窄 | 代码细节少 | 微观 Bug 不敏感 |
+| **输出风格** | 逐条 Bug + 修复代码 | 分层分析 + 实施路线 | 全景目录 + 优先级表格 |
+| **适合阶段** | **第一步：排雷** | **第二步：提速** | **第三步：治理** |
+| **可执行性** | ⭐⭐⭐⭐⭐ 直接可改 | ⭐⭐⭐ 方案级 | ⭐⭐⭐ 框架级 |
+
+### 1.2 自我认知修正（v1 版本揭示的关键洞察）
+
+claude_v1.md 和 codex_v1.md 在分析 WorkBuddy 的原始报告时，指出了几项重要的自我修正：
+
+| 原始 WorkBuddy 结论 | v1 版本揭示的问题 | 修正 |
+|---------------------|-------------------|------|
+| 全局变量封装列为 P0（与 Fortran 同级） | Fortran 崩溃是功能阻断，重构是长期工作 | P0 → P2 ⬇️ |
+| 建议在 B1 修复中继续加全局变量 | 这与"封装全局变量"方向矛盾 | 短期补丁 + 长期封装需注明衔接 |
+| `compute.py` 拆模块建议偏理想化 | 未说明拆分顺序和风险控制 | 补充 `io.py` 优先，`runner.py` 最后 |
+
+---
+
+## 二、各工具 v1 版本评价
+
+### 2.1 claude_v1.md — Claude 的第二轮分析
+
+**性质**：Claude 对 workbuddy.md 和 claude.md 的综合
+
+**新增价值**：
+- 对 WorkBuddy 的优势/劣势做了 5 条以上具体分析（非泛泛批评）
+- 将 B1 修复方案做了更完善的设计（全局变量 + `global` 声明 + 作用域验证）
+- 给出了 B3 的完整分步修复代码（含 header 补充 `atom_masses` 字段）
+- **引擎评价表格**：对 C/C++/Fortran 三个引擎逐一评估功能/性能/一致性/代码质量
+- **"今天可以完成"清单**：5 个 1-5 分钟的小修复，非常实用
+
+**不足之处**：
+- 仍然基于静态分析，未发现 B1 实际上可能不是 Bug（已在实机验证中确认 Python 引擎可用）
+- 补丁式修复（继续加全局变量）与长期封装方向存在内在矛盾，虽已指出但未给出桥接方案
+
+### 2.2 codex_v1.md — Codex 的第二轮分析
+
+**性质**：Codex 对 workbuddy.md + claude.md + codex.md 三份的综合
+
+**新增价值**：
+- **"结论先行"式结构**：开篇即给出 "Claude=QA, Codex=Perf, WorkBuddy=Architect" 框架
+- **角色定位最清晰**：三段式建议（先 Claude 修正确性 → 再 Codex 做性能 → 最后 WorkBuddy 做治理）被 claude_v1.md 采纳，形成共识
+- 指出即使切到 C 引擎，文本 I/O 仍然是共享瓶颈 — 这是比仅关注 Python 引擎更深层的洞察
+- **性能分层最系统**：CPU 瓶颈（弹簧力）vs I/O 瓶颈（文本格式）vs 可视化瓶颈（逐原子更新）
+
+**不足之处**：
+- 对架构建议仍然偏泛，没有 WorkBuddy 或 claude_v1 的详细代码
+- 没有引擎一致性分析
+
+### 2.3 workbuddy_v1.md — 本工具的第一次综合
+
+**性质**：对三份原始报告的综合对比
+
+**自我评价**：
+| 维度 | 表现 | 与 v2 对比 |
+|------|------|-----------|
+| Bug 对比表格 | ✅ 全面（B1-B9，含验证状态） | 保持 |
+| 优化建议对比 | ✅ 12 项工具间对比 | 补充 v1 版本对比 |
+| 阶段划分 | 🟡 6 阶段偏细，v2 合并为 3 阶段 | 精简为 3 阶段 |
+| 工具选择建议 | ✅ 场景化推荐 | 保持并丰富 |
+| v1 版本覆盖 | ❌ 未覆盖 claude_v1/codex_v1 | 新增 ✅ |
+| 自我修正 | ❌ 未对自己做评价 | 新增 §1.2 ✅ |
+
+---
+
+## 三、Bug 核实与状态（B1-B9）
+
+### 3.1 已验证的真 Bug（可直接复现）
+
+| 编号 | 描述 | 触发条件 | 发现者 | 验证方式 | 优先级 |
+|------|------|---------|--------|---------|--------|
+| **B2** | `dynamics.py` 绘图块变量未定义 → NameError | `step_plot: 1` | Claude | 代码分析，当前案例设为 0 才未爆发 | 🔴 P0 |
+| **B3** | `plot_wave.py` 使用 `load_text_data` 读新格式 display.txt | `step_plot_wave: 1` | Claude | 代码分析，函数调用链不兼容 | 🔴 P0 |
+| **B4** | case06 描述文字写 case01 | 运行显示 | Claude | 肉眼可见 | 🟡 P1 |
+| **B5** | `draw.py` 裸 `except` 吞异常 | 任何运行 | Claude | 代码分析 | 🟡 P1 |
+| **E3** | Fortran 引擎不支持 `display.txt` | `engine: fortran` | 双方共识 | 代码分析，引擎无此功能 | 🔴 P0 |
+
+### 3.2 已修复的 Bug（当前版本已解决）
+
+| 编号 | 描述 | 发现者 | 修复阶段 |
+|------|------|--------|---------|
+| B6 | display.txt 加载过慢（逐行解析 60s+） | WorkBuddy | 已修复：改用 `np.genfromtxt` → 0.087s |
+| B7 | `use_marker` 未传递 → VisPy 卡顿 | WorkBuddy | 已修复：加入 header 传递 |
+| B8 | `alpha` 未写入 display.txt header | WorkBuddy | 已修复：C/C++/Python 引擎均已补全 |
+| B9 | 运动相机缓存不刷新 | WorkBuddy | 已修复：draw.py 直读 move_camera.txt |
+
+### 3.3 疑似误报的 Bug
+
+| 编号 | 描述 | 发现者 | 分析 |
+|------|------|--------|------|
+| **B1** | `run_simulation` 内 `config` 未定义 | Claude | ⚠️ Python 引擎已验证可用。`run_simulation` 虽不接收 `config` 参数，但在 `run_from_config` 内部调用时可能通过闭包/全局变量获得 `config`。虽建议修复（50% 概率是 Bug，50% 是侥幸可用），但优先级应降低 |
+
+---
+
+## 四、最终综合方案（3 阶段，约 8-10 人天）
+
+综合三工具六版本的全部建议，采用 **codex_v1 的三阶段框架** + **claude_v1 的详细修复步骤** + **workbuddy_v1 的对比表格**，形成以下方案。
+
+### 阶段 A：先修正确性（~2 天）— 以 Claude 为主
+
+> 目标：恢复所有功能到可用状态，禁止"带病优化"
+
+| 任务 | 参考 | 工作量 | 产出 |
+|------|------|--------|------|
+| A1 | `plot_wave.py` 适配 `load_display_txt` + header 补充 `atom_masses` | claude_v1 §1 | 1.5h | `step_plot_wave: 1` 可运行 |
+| A2 | `dynamics.py` 绘图块添加保护（短期） / 从 display.txt 重建（长期） | claude_v1 §3 | 30min | `step_plot: 1` 不崩溃 |
+| A3 | **Fortran 引擎写 display.txt**（参照 C 引擎 `write_display_txt`） | claude_v1 §4 | 2-3h | `engine: fortran` 可用 |
+| A4 | 小修复：case06 文字 / draw.py except / C++ 默认值 / 相机函数去重 / 废弃函数清理 | claude_v1 §5 | 30min | 代码整洁 |
+| A5 | B1 修复：`camera_distance/elevation/azimuth` 改为全局变量（短期补丁） | claude_v1 §2 | 15min | Python 引擎无潜在风险 |
+
+**验证标准**：4 种引擎跑 case06 均通过，`step_plot: 1` + `step_plot_wave: 1` 不崩溃
+
+### 阶段 B：再做性能优化（~3 天）— 以 Codex 框架 + Claude 代码为主
+
+> 目标：Python 引擎加速 5-15x，新增二进制格式消除 I/O 瓶颈
+
+| 任务 | 参考 | 工作量 | 预期收益 |
+|------|------|--------|---------|
+| B1 | **弹簧力向量化**：`np.add.at` 批量计算（链状体系可进一步优化为直接索引） | claude.md §P1 + claude_v1 §6 | 1h | Python 引擎 5-15x |
+| B2 | 固定约束原地掩码写回，消除 `column_stack` | claude.md §P2 | 30min | 每步减少 2 次临时数组分配 |
+| B3 | Marker 更新改为整列切片赋值 | codex_v1 阶段 B | 15min | 大原子数动画帧率提升 |
+| B4 | 驱动力去掉 `t_vec` / `frame_indices` 改计数器 | claude.md §P3-P4 | 10min | 微优化 |
+| B5 | **新增 `display.npz` 二进制格式**，draw.py 优先读二进制 | codex.md + codex_v1 | 2h | I/O 从文本级加速到二进制级 |
+| B6 | 外部引擎校准缓存 | claude_v1 §8 | 1h | 二次运行节省 10s+ |
+| B7 | `GRAVITY_INTERACTION` O(N²) 向量化（可选） | claude.md §P5 | 1h | 仅影响引力场景 |
+
+**验证标准**：`engine: python` 跑 case06 < 5s（当前 43s），`load_display_npz` < 0.01s
+
+### 阶段 C：最后做工程治理（~3-4 天）— 以 WorkBuddy 为主
+
+> 目标：从"能用"变成"好维护"
+
+| 任务 | 参考 | 工作量 | 说明 |
+|------|------|--------|------|
+| C1 | `compute.py` 模块拆分（`io.py` → `params.py` → `core.py` → `runner.py`） | workbuddy.md §1.1 | 4-6h | io.py 优先（与物理解耦），runner.py 最后 |
+| C2 | 全局变量 → `SimulationState` 类（是 A5 补丁的长期替代） | workbuddy.md §3.1 + claude_v1 §10 | 3-4h | 从 `compute_force` 开始，逐步替换 |
+| C3 | 统一 6 案例 input.txt 格式 + `ball_color` 列表化 | workbuddy.md §4.1-4.2 | 1-2h | 所有案例含 `save_trajectory`、`camera_*` 字段 |
+| C4 | pytest 单元测试（物理算法 + I/O 往返 + 参数边界） | workbuddy.md §5.1 | 3-5h | 简谐振子解析解验证 leapfrog |
+| C5 | 多引擎一致性测试 + profiling 计时 | codex_v1 + claude_v1 | 2h | 4 种引擎输出容差内一致 |
+| C6 | C/C++ 引擎共用公共头文件 | workbuddy.md §1.2 | 2-3h | `engines/common/` |
+| C7 | README 更新 / 废弃脚本清理 / 注释完善 | 综合 | 1h | 匹配当前架构 |
+
+**验证标准**：全部案例 + 全部引擎通过 pytest，README 与代码一致
+
+---
+
+## 五、三阶段总工作量与依赖
+
+```
+阶段 A（修复）   阶段 B（提速）   阶段 C（治理）
+   A1 1.5h ───── B1 1h ─────  C1 4-6h
+   A2 30min ──── B2 30min ─── C2 3-4h
+   A3 2-3h ───── B3 15min      C3 1-2h
+   A4 30min ──── B4 10min ─── C4 3-5h
+   A5 15min ──── B5 2h ────── C5 2h
+                  B6 1h         C6 2-3h
+                  B7 1h(可选)   C7 1h
+ ───────────── ───────────── ─────────────
+   ~5h           ~6h           ~15-20h
+   ~1天          ~1天          ~3-4天
+                               
+                总人天：约 8-10 天
+```
+
+**依赖规则**：
+- A 阶段无外部依赖，可直接开始
+- B 阶段依赖 A 阶段完成（否则优化可能建立在错误的代码上）
+- C 阶段依赖 B 阶段完成（架构重构应在性能热点明确后再做）
+
+---
+
+## 六、如果只做 5 件事
+
+基于三工具六版本全文分析共识，最高回报的 5 件事：
+
+| 排名 | 任务 | 工作量 | 来源 | 投入产出比 |
+|------|------|--------|------|-----------|
+| ⭐1 | **弹簧力向量化**（B1） | 1h | Claude 代码 | Python 引擎 5-15x，所有案例通用 |
+| ⭐2 | **Fortran 引擎写 display.txt**（A3） | 2-3h | 双方共识 P0 | 恢复第 4 种引擎，消除功能盲区 |
+| ⭐3 | **plot_wave.py 格式适配**（A1） | 1.5h | Claude B3 | 恢复波形动画功能（case05/06） |
+| ⭐4 | **display.npz 二进制格式**（B5） | 2h | Codex 独有 | 消除 I/O 瓶颈，所有引擎受益 |
+| ⭐5 | **校准缓存**（B6） | 1h | claude_v1 §8 | 二次运行节省 10s+，小投入大回报 |
+
+---
+
+## 七、工具选择速查表
+
+| 你需要 | 最佳工具 | 次选 | 为什么 |
+|--------|---------|------|--------|
+| 找会崩溃的 Bug | **Claude** | — | B1-B5 五个确认 Bug 全来自 Claude |
+| Python 引擎向量化 | **Claude** | Codex | 给出 `np.add.at` 可运行代码 |
+| 二进制格式策略 | **Codex** | — | 唯一想到 `display.npz` 的工具 |
+| 模块拆分方案 | **WorkBuddy** | — | 唯一给出完整目录结构的 |
+| 实施顺序规划 | **Codex** | WorkBuddy | "先修正确性→再提速→最后治理"逻辑最清晰 |
+| 多引擎一致性 | **Claude** | WorkBuddy | C/C++/Fortran 逐一评估 |
+| 配置统一 & 模板 | **WorkBuddy** | — | 提供了 6 案例统一 YAML 模板 |
+| 快速执行清单 | **codex_v1** | claude_v1 | 按"今天/本周/下阶段"列优先级 |
+| 对比多种方案 | **workbuddy_v1/v2** | claude_v1 | Bug 发现/优化项/风格三维对比表 |
+
+---
+
+## 八、附录：从 v1 到 v2 的改进
+
+| 维度 | workbuddy_v1 | workbuddy_v2 (当前) |
+|------|-------------|-------------------|
+| 参考文档数 | 3 份 | 6 份（含 3 份 v1 版本） |
+| 自我评价 | ❌ 无 | ✅ 新增 §1.2 自我修正 |
+| 阶段数 | 6 阶段 | 3 阶段（更精简） |
+| Bug 验证 | 🟡 部分标注 | ✅ 分类"真 Bug / 已修复 / 疑似误报" |
+| 工具角色定位 | 散落在各处 | ✅ 统一框架（QA/Perf/Architect） |
+| 快速执行 | 3 件事 | 5 件事（更全面） |
+| 工具选择速查 | 6 场景 | 10 场景（覆盖更全） |
+| 篇幅 | 216 行 | 约 250+ 行 |
+
+---
+
+*本文档综合了 WorkBuddy（实机验证 + 架构视野）、Claude Sonnet 4.6（Bug 挖掘 + 向量化代码）、Codex/GPT-4o（战略思维 + 二进制格式）三方共六份分析报告。建议按 A → B → C 三阶段顺序实施。*