# Dynamics 优化方案综合评估

> 分析日期：2026-06-12  
> 评估对象：`optimization/claude.md`、`optimization/codex.md`、`optimization/workbuddy.md`  
> 说明：用户问题中出现两次 `claude.md`，但目录内实际为三份不同文档，因此本文按 **Claude / Codex / Workbuddy** 三个工具的输出进行综合分析。

## 一、结论先行

这三份建议并不是互相冲突，而是分别代表了三种不同但互补的优化视角：

- **Claude**：最像“代码审计员”，擅长找出会崩溃、会出错、会不一致的具体问题。
- **Codex**：最像“性能工程师”，擅长定位热点路径、区分 CPU 与 I/O 瓶颈、给出高收益优化顺序。
- **Workbuddy**：最像“架构负责人”，擅长从模块拆分、全局变量治理、配置统一、测试体系等角度规划长期演进。

如果只选一个方案：

- 短期救火，优先参考 **Claude**
- 中期提速，优先参考 **Codex**
- 长期重构，优先参考 **Workbuddy**

如果要形成真正适合这个项目的落地方案，最佳做法不是三选一，而是：

1. 先按 **Claude** 修 correctness bug
2. 再按 **Codex** 做性能主线优化
3. 最后按 **Workbuddy** 做结构化治理

---

## 二、三款工具的评价

## 1. Claude

### 优势

- **最强的 bug 发现能力**  
  `claude.md` 明确指出了几个高价值问题，例如：
  - `compute.py` 里 `run_simulation()` 直接引用未传入的 `config`
  - `dynamics.py` 绘图分支使用未定义变量
  - `plot_wave.py` 仍按旧格式读取新 `display.txt`

  这些问题都属于“不是慢，而是可能直接错或崩”的问题，优先级非常高。

- **问题定位具体，能直接改代码**  
  Claude 的输出不是抽象建议，而是带着明确文件位置、触发条件和修复方向，适合立即进入修复。

- **对多引擎一致性比较敏感**  
  它注意到了 Python/C/C++/Fortran 之间在 `save_trajectory`、势能分配、输出格式支持等方面的不一致，这对多语言框架很重要。

### 劣势

- **整体视角偏“局部修补”**  
  它非常擅长发现局部 bug，但对“整体性能主瓶颈怎么排优先级”没有 Codex 那么系统。

- **长期架构建议相对弱一些**  
  虽然也提到一些结构问题，但没有 Workbuddy 那种模块拆分、配置治理、测试体系的完整路线。

- **偏静态审计，偏保守**  
  更适合“先修对”，不一定最适合“先做最值的性能投资”。

### 适合的角色

- 第一轮排雷
- 回归前 bug 清单
- 多引擎一致性核对

---

## 2. Codex

### 优势

- **性能视角最清晰**  
  `codex.md` 非常明确地区分了三类瓶颈：
  - Python 计算循环
  - 力学计算中的逐键/双层循环
  - 文本 I/O

  这种分层对项目很有价值，因为它避免把“算法慢”和“文件慢”混成一个问题。

- **优化顺序合理，投入产出比高**  
  它提出的几个优先项都很务实：
  - 弹簧力向量化
  - `display.txt` 增加二进制格式
  - `draw.py` Marker 批量更新

  这些建议的共同特点是：
  - 不需要推翻现有架构
  - 可验证
  - 回报高

- **能识别共享瓶颈**  
  它特别强调：即使换成 C 引擎，文本 I/O 仍然会拖后腿。这种判断比只盯 Python 引擎更深入。

### 劣势

- **对当前代码中的直接 bug 关注度不如 Claude**  
  虽然也指出了 `dynamics.py` 数据流和 README 不一致等风险，但没有 Claude 那么系统地清点“哪些地方一开功能就报错”。

- **工程治理不如 Workbuddy 完整**  
  它提到全局变量和状态对象，但没有把模块拆分、测试体系、案例配置统一讲得那么全面。

- **更偏策略，不总是落到立即可改的具体 patch**  
  对项目 owner 来说这很好，但如果是要当天就修 bug，Claude 会更直接。

### 适合的角色

- 性能优化主方案
- 技术债排序
- 中期研发路线设计

---

## 3. Workbuddy

### 优势

- **最强的工程化和长期治理视角**  
  `workbuddy.md` 关注的重点包括：
  - `compute.py` 拆模块
  - 消除全局变量
  - 配置结构统一
  - 测试体系建设
  - Fortran/C/C++ 引擎功能对齐

  这类建议对项目走向稳定维护很关键。

- **适合把个人项目变成可持续项目**  
  它不是只盯某一个性能点，而是在思考这个项目未来怎么更好地维护、测试、扩展。

- **对“项目管理成本”比较敏感**  
  比如配置格式不统一、废弃文件残留、测试缺失，这些短期不一定影响运行，但长期一定影响开发效率。

### 劣势

- **短期收益不如另外两者明显**  
  比如模块拆分、类型标注、状态封装，这些很重要，但如果当前主要痛点是“功能坏了”或“运行太慢”，它们不会立刻让用户感受到变化。

- **有些建议偏大改**  
  像 `compute.py` 模块拆分、全局变量全面状态化，工作量不小，如果现在马上做，容易把项目带入较长重构周期。

- **对现存 bug 的敏锐度不如 Claude，对热点性能的聚焦不如 Codex**  
  它更像制定制度和框架的人，而不是先冲到一线止血的人。

### 适合的角色

- 中长期架构治理
- 重构路线设计
- 代码库标准化与测试建设

---

## 三、三者对比总结

| 维度 | Claude | Codex | Workbuddy |
|------|--------|-------|-----------|
| 找 bug | 最强 | 中等 | 中等 |
| 找性能瓶颈 | 强 | 最强 | 中等 |
| 架构治理 | 中等 | 强 | 最强 |
| 可直接落地修复 | 最强 | 强 | 中等 |
| 中期路线规划 | 中等 | 最强 | 强 |
| 长期工程化 | 中等 | 强 | 最强 |
| 风险意识 | 最强 | 强 | 强 |
| 适合当前项目阶段 | 很适合当前排雷 | 很适合当前提速 | 很适合下一阶段治理 |

可以概括为：

- **Claude 更像 QA/审计**
- **Codex 更像性能工程师**
- **Workbuddy 更像架构经理**

---

## 四、综合判断

从这三份文档综合看，`Dynamics` 项目当前不是单一问题，而是三类问题叠加：

1. **已有功能正确性问题**
   - 某些路径会直接崩溃
   - 某些脚本已经和新格式脱节
   - 多引擎行为存在不一致

2. **性能与 I/O 问题**
   - Python 引擎热点循环还没做足够向量化
   - `display.txt`/`trajectory.txt` 文本格式开始成为共享瓶颈
   - 动画路径里还有逐原子更新

3. **工程治理问题**
   - `compute.py` 过大
   - 全局变量过多
   - 配置不统一
   - 缺少测试

因此，最合理的综合方案必须是 **分阶段方案**，而不是试图一次性全做。

---

## 五、推荐的综合方案

## 阶段 A：先修正确性，避免“带病优化”

这一阶段以 Claude 的结论为主，目标是先把明显会崩溃、会错的地方修掉。

建议优先做：

1. 修复 `compute.py` 中 `run_simulation()` 对 `config` 的非法引用
2. 修复 `dynamics.py` 绘图分支中未定义变量的死代码问题
3. 修复 `plot_wave.py` 对新 `display.txt` 格式的不兼容
4. 统一外部引擎在 `save_trajectory`、输出格式上的行为
5. 清理少量明显错误与危险写法
   - case06 文案错误
   - `draw.py` 裸 `except`

这一阶段的目标不是提速，而是让系统进入“功能可信、路径可跑”的状态。

---

## 阶段 B：再做高收益性能优化

这一阶段以 Codex 的结论为主，重点是先做收益大、改动相对可控的优化。

建议优先做：

1. 给 `compute.py` / `dynamics.py` 增加基础 profiling
   - 总耗时
   - 力计算耗时
   - 抽帧耗时
   - I/O 耗时

2. 向量化 `compute_force()` 中的弹簧键计算

3. 在 `draw.py` 中将 Marker 更新改成整列切片赋值

4. 新增二进制显示格式
   - 推荐 `display.npz`
   - `draw.py` 优先读二进制，回退读文本

5. 将完整轨迹保存改为分块/流式写出

这一步完成后，项目会得到最直观的收益：

- Python 引擎更快
- C 引擎的后处理更快
- 大规模 case 的内存压力更低

---

## 阶段 C：最后做工程治理与结构化重构

这一阶段以 Workbuddy 的结论为主，目标是让项目从“能用”变成“好维护”。

建议优先做：

1. 拆分 `compute.py`
   - `core.py`
   - `io.py`
   - `params.py`
   - `runner.py`
   - `engine_helper.py`

2. 引入 `SimulationState` / `SimulationConfig` / `SystemData`
   - 逐步消灭模块级全局变量

3. 统一案例配置格式
   - 六个案例字段保持一致
   - 将颜色、相机等零散字段收束成结构化配置

4. 建立最小测试体系
   - 数值方法单元测试
   - I/O 一致性测试
   - Python/C 输出一致性测试

5. 清理废弃脚本和旧逻辑
   - 尤其是已经不再处于主流程中的脚本

这一步不会像阶段 B 那样马上体现性能收益，但它会显著降低后续维护成本。

---

## 六、最终推荐方案

如果只给一个“综合最优”的执行方案，我建议采用下面这个顺序：

1. **先按 Claude 修 bug**
   - 因为错误路径不先修，后面性能优化和重构都会建立在不稳定基础上

2. **再按 Codex 做性能主线**
   - 因为当前性能瓶颈已经很清楚，尤其是 Python 热点和文本 I/O

3. **最后按 Workbuddy 做结构治理**
   - 因为工程化重构最适合在功能稳定、热点清楚之后进行

换句话说：

- **Claude 决定“先修什么”**
- **Codex 决定“先优化什么”**
- **Workbuddy 决定“最后把系统整理成什么样”**

这是三份建议里最不冲突、也最符合实际开发节奏的组合方式。

---

## 七、简版执行清单

如果要把这份综合方案压缩成一份实际待办，我建议如下：

### P0：立即处理

- 修 `run_simulation()` 的 `config` 作用域错误
- 修 `dynamics.py` 绘图分支未定义变量
- 修 `plot_wave.py` 与新 `display.txt` 格式不兼容
- 校正多引擎 `save_trajectory` / 输出行为不一致

### P1：本轮优化主线

- 增加 profiling
- 向量化弹簧力计算
- `draw.py` Marker 批量更新
- 新增 `display.npz`
- 完整轨迹改为分块写出

### P2：下一轮治理

- 拆分 `compute.py`
- 全局变量状态化
- 统一 `input.txt` 结构
- 建立 pytest 测试
- 清理废弃脚本与旧文档

---

## 八、最终评价

三款工具的输出质量都不错，但擅长点不同。

- **Claude** 最适合当前这个项目的“第一步”，因为它最能发现会直接影响运行正确性的缺陷。
- **Codex** 最适合当前这个项目的“第二步”，因为它对性能瓶颈的层次判断最清楚，最容易产出高收益优化。
- **Workbuddy** 最适合当前这个项目的“第三步”，因为它能把一套已经能跑的系统整理成一套更稳定、更易维护的工程。

因此，综合最优解不是选其中一个，而是：

**用 Claude 排雷，用 Codex 提速，用 Workbuddy 收尾治理。**