docs: 综合三方工具分析，输出最终优化方案 workbuddy_v1.md

对比 WorkBuddy/Claude/Codex 三款 AI 工具对同一代码库的优化建议，以表格形式评价各自优劣（Bug 发现/代码质量/战略思维/代码示例），最终整合为 6 阶段实施计划（11 人天）。
2026-06-12 15:39:31 +08:00
parent 782422e800
commit d930fb558c
4 changed files with 1358 additions and 0 deletions
@@ -0,0 +1,216 @@
+# Dynamics 项目优化方案 — 三方工具综合评价与整合
+
+> **分析日期**：2026-06-12  
+> **参与工具**：WorkBuddy（本助手）、Claude（Sonnet 4.6）、Codex（GPT-4o 代码分析）  
+> **分析范围**：`D:\Share\Data\aliyun-gitea\dynamics` 完整代码库  
+> **参考文档**：`optimization/workbuddy.md`、`optimization/claude.md`、`optimization/codex.md`
+
+---
+
+## 一、三方工具评价
+
+### 1.1 WorkBuddy（AI Agent，Senior Developer 角色）
+
+| 维度 | 评价 |
+|------|------|
+| **优势** | ✅ 实际运行和修改过整个代码库，已验证 display.txt 格式/渲染参数/运动相机等功能的正确性 — 不是静态分析，是实机验证 |
+| | ✅ 覆盖最广：架构、性能、代码质量、配置、测试、引擎一致性、UX 等 9 个维度 |
+| | ✅ 每个建议标注优先级(P0-P3)和预估工作量(小时级) |
+| | ✅ 发现了一些真正的坑：C++ 引擎 `save_trajectory` 默认值 1（导致行为不一致）、`alpha` 字段未传递到 display.txt 等 |
+| | ✅ 提供 input.txt 格式统一模板和 YAML 结构优化建议 |
+| **劣势** | ❌ 建议偏"宏观架构"（模块拆分、全局变量封装），缺乏具体的向量化代码 |
+| | ❌ 没有发现 B1（config 不存在作用域）、B2（绘图代码完全失效）等具体 Bug |
+| | ❌ 对 Python 引擎性能优化仅提到 Numba，没有给出弹簧力向量化等具体代码 |
+
+### 1.2 Claude（Sonnet 4.6）
+
+| 维度 | 评价 |
+|------|------|
+| **优势** | ✅ **Bug 挖掘能力极强**：发现了 `run_simulation` 内 `config` 未定义、`dynamics.py` 绘图块完全失效、`plot_wave.py` 格式不匹配等 5 个确切 Bug |
+| | ✅ **Python 引擎向量化代码极其具体**：弹簧力、引力 O(N²)、固定约束、驱动力的优化都给出了可直接替换的代码（含 `np.add.at`） |
+| | ✅ 引擎一致性分析全面：C/C++/Fortran 默认值差异、势能归属约定差异 |
+| | ✅ 标注了 `load_parameters` 已废弃、相机解析函数重复等代码质量问题 |
+| | ✅ 按投入产出比排序最高回报的 3 件事 |
+| **劣势** | ❌ 纯静态分析，**部分结论可能是误报**：B1 中 `config` 在 `run_simulation` 中不可用 → 但 `run_simulation` 是从 `run_from_config` 内部调用的，实际上 Python 引擎路径已验证可正常工作（后续对话中用户成功运行） |
+| | ❌ 没有分析 Fortran 引擎（可能只读了 C 引擎代码） |
+| | ❌ 没有发现 display.txt 格式最初加载过慢的问题（已修复） |
+| | ❌ 没有发现 `use_marker` 字段丢失导致 VisPy 卡顿的问题（已修复） |
+| | ❌ 没有分析 input.txt 格式统一性问题 |
+
+### 1.3 Codex（GPT-4o）
+
+| 维度 | 评价 |
+|------|------|
+| **优势** | ✅ **战略思维最好**：建议先加 profiling 再做优化（"没度量就没有优化"），反对盲目优化 |
+| | ✅ 提出 `display.npz` 二进制格式替代方案 — 所有工具中唯一想到这个的 |
+| | ✅ "分两层优化"理念清晰：计算性能(CPU) vs I/O 性能(磁盘)分开处理 |
+| | ✅ 强调 "最小一致性测试集" — 多引擎正确性验证的实用方案 |
+| | ✅ 推荐实施顺序最合理：1)计时 2)向量化 3)Marker 切片 4)二进制输出 5)修复绘图 6)架构重构 |
+| **劣势** | ❌ 代码细节最少，没有给出具体的向量化实现 |
+| | ❌ 没有发现任何确切的 Bug——描述的都是"可能的风险"而非"可复现的崩溃" |
+| | ❌ 架构建议偏泛（"减少全局变量""收敛到状态对象"），没有 WorkBuddy 的 SimulationState 代码示例 |
+| | ❌ 没有分析相机运动、渲染参数传递等最近新增功能 |
+
+---
+
+## 二、建议对比汇总
+
+### 2.1 Bug 发现对比
+
+| Bug 编号 | 描述 | WorkBuddy | Claude | Codex | 验证状态 |
+|----------|------|-----------|--------|-------|---------|
+| B1 | `run_simulation` 内 `config` 变量作用域 | ❌ 未发现 | ✅ 发现 | ❌ 未发现 | ⚠️ 疑似误报（Python 引擎实际可用） |
+| B2 | `dynamics.py` 绘图块死代码/变量未定义 | ❌ 未发现 | ✅ 发现 | ✅ 提及风险 | ✅ 确认（step_plot=1 时崩溃） |
+| B3 | `plot_wave.py` 旧格式加载新 display.txt | ❌ 未发现 | ✅ 发现 | ❌ 未发现 | ✅ 确认（step_plot_wave=1 时崩溃） |
+| B4 | case06 描述写 case01 | ❌ 未发现 | ✅ 发现 | ❌ 未发现 | ✅ 确认 |
+| B5 | `draw.py` 裸 `except` | ❌ 未发现 | ✅ 发现 | ❌ 未发现 | ✅ 确认 |
+| B6 | display.txt 旧格式加载过慢（已修复） | ✅ 发现修复 | ❌ 未发现 | ❌ 未发现 | ✅ 已修复 |
+| B7 | `use_marker` 丢失 → VisPy 卡顿（已修复） | ✅ 发现修复 | ❌ 未发现 | ❌ 未发现 | ✅ 已修复 |
+| B8 | `alpha` 未写入 display.txt header（已修复） | ✅ 发现修复 | ❌ 未发现 | ❌ 未发现 | ✅ 已修复 |
+| B9 | 运动相机数据缓存不刷新（已修复） | ✅ 发现修复 | ❌ 未发现 | ❌ 未发现 | ✅ 已修复 |
+
+### 2.2 优化建议对比
+
+| 优化项 | WorkBuddy | Claude | Codex | 综合评价 |
+|--------|-----------|--------|-------|---------|
+| 弹簧力向量化 | 仅提到 Numba | ✅ 完整代码含 `np.add.at` | ✅ 有思路但无代码 | **Claude 最佳** |
+| 固定约束优化 | 提到但无代码 | ✅ 有代码 | ✅ 有思路 | **Claude 最佳** |
+| display.npz 二进制格式 | ❌ 未想到 | ❌ 未想到 | ✅ 唯一想到 | **Codex 最佳** |
+| 全局变量封装 SimulationState | ✅ 有代码示例 | ✅ 提及 | ✅ 提及 | **WorkBuddy 最佳** |
+| compute.py 模块拆分 | ✅ 完整目录结构 | ❌ 未提及 | ❌ 未提及 | **WorkBuddy 最佳** |
+| input.txt 格式统一 | ✅ 完整模板 | ❌ 未提及 | ❌ 未提及 | **WorkBuddy 最佳** |
+| 先加 profiling 再优化 | ❌ 未提及 | ❌ 未提及 | ✅ 强烈建议 | **Codex 最佳** |
+| Fortran 引擎更新 | ✅ 提及 P0 | ✅ 提及 | ❌ 未提及 | **WorkBuddy+Claude** |
+| 外部引擎校准缓存 | ✅ 有代码示例 | ✅ 有方案 | ❌ 未提及 | **WorkBuddy+Claude** |
+| 多引擎一致性测试集 | ❌ 未提及 | ❌ 未提及 | ✅ 建议 | **Codex 最佳** |
+| Marker 更新切片化 | ❌ 未提及 | ❌ 未提及 | ✅ 建议 | **Codex 最佳** |
+| 驱动去 t_vec 分配 | ❌ 未提及 | ✅ 有代码 | ✅ 提及 | **Claude 最佳** |
+
+### 2.3 风格对比
+
+| 维度 | WorkBuddy | Claude | Codex |
+|------|-----------|--------|-------|
+| 粒度 | 宏观+微观 | 微观为主 | 宏观为主 |
+| 代码示例 | 中等（配置模板/架构） | 丰富（向量化/性能优化） | 最少 |
+| Bug 发现 | 运行时验证的 Bug | 静态分析发现的 Bug | 潜在风险 |
+| 战略层 | 中度 | 低 | 高 |
+| 实施顺序 | P0-P3 优先级 | 投入产出比排序 | 推荐实施顺序 |
+| 可信度 | 高（实际运行过） | 中（静态分析） | 中（静态分析） |
+
+---
+
+## 三、最终综合方案
+
+综合三方分析，推荐按以下 **6 个阶段** 实施，每阶段都有明确的可验证交付物。
+
+### 阶段一：立即修复已确认的 Bug（1 天）
+
+| 编号 | 内容 | 参考工具 | 工作量 |
+|------|------|---------|--------|
+| F1 | `plot_wave.py` 适配 `load_display_txt` 新格式 (B3) | Claude | 1-2h |
+| F2 | `dynamics.py` 绘图块添加保护，避免 `step_plot=1` 崩溃 (B2) | Claude | 30min |
+| F3 | 修复 `draw.py` 裸 `except` (B5) | Claude | 5min |
+| F4 | 修复 case06 描述文字 (B4) | Claude | 1min |
+| F5 | C++ 引擎 `save_trajectory` 默认值改为 0 (E2) | Claude | 5min |
+| F6 | **Fortran 引擎支持 `save_trajectory=0`**（参照 C 引擎实现） | WorkBuddy/Claude | 2-3h |
+| F7 | 相机解析函数去重：`dynamics.py` 导入 `compute._load_camera_motion` (Q1) | Claude | 15min |
+| F8 | 废弃 `load_parameters` + `main()` 删除或移入 tools/ (Q2) | Claude | 15min |
+
+**验证**：Python/C/C++/Fortran 全部 4 种引擎跑 case06，`step_plot: 1` + `step_plot_wave: 1` 不崩溃
+
+### 阶段二：Python 引擎性能优化（2 天）
+
+| 编号 | 内容 | 参考工具 | 工作量 |
+|------|------|---------|--------|
+| P1 | **弹簧力向量化**：`compute_force()` 中键循环改为 `np.add.at` 批量计算 | Claude（完整代码） | 1h |
+| P2 | 固定约束原地掩码写回，消除 `column_stack` | Claude | 30min |
+| P3 | `frame_indices` 列表改计数器 | Claude | 5min |
+| P4 | 驱动力去掉 `t_vec` 临时数组 | Claude/Codex | 5min |
+| P5 | `GRAVITY_INTERACTION` O(N²) 双重循环向量化（可选） | Claude | 1h |
+
+**验证**：`engine: python` 跑 case06 耗时缩短 5-15 倍（目标：从 43s → <5s）
+
+### 阶段三：I/O 与可视化优化（2 天）
+
+| 编号 | 内容 | 参考工具 | 工作量 |
+|------|------|---------|--------|
+| I1 | **新增 `display.npz` 二进制格式**：`save_display_npz` / `load_display_npz` | Codex（方案） | 1-2h |
+| I2 | `draw.py` 优先读 `.npz`，不存在时回退 `display.txt` | Codex | 1h |
+| I3 | `draw.py` Marker 更新改为切片赋值（消除 `for i in range(N_ATOMS)`） | Codex | 15min |
+| I4 | `save_trajectory=1` 时轨迹数据改为 `memmap` 或分块写入 | Codex | 2h |
+
+**验证**：读取 200 帧×120 原子数据 < 0.01s（现 0.087s），动画帧率 60fps
+
+### 阶段四：架构重构（3 天）
+
+| 编号 | 内容 | 参考工具 | 工作量 |
+|------|------|---------|--------|
+| A1 | **`compute.py` 模块拆分**：`core/io/params/runner/main` | WorkBuddy（目录结构） | 4-6h |
+| A2 | **全局变量封装为 `SimulationState` 类**，从 `compute_force()` 开始 | WorkBuddy | 3-4h |
+| A3 | `draw.py` 全局变量封装为 `AnimationData` + `CameraState` | WorkBuddy | 2-3h |
+| A4 | C 和 C++ 引擎共用公共头文件（`engines/common/`） | Workbuddy | 3h |
+
+**验证**：所有 6 个 case + 4 种引擎，结果与重构前一致
+
+### 阶段五：配置与文档统一（1 天）
+
+| 编号 | 内容 | 参考工具 | 工作量 |
+|------|------|---------|--------|
+| C1 | **统一 6 个案例的 input.txt 格式**（增加 save_trajectory/camera 等缺失字段） | WorkBuddy（模板） | 1-2h |
+| C2 | `ball_color_r/g/b` 改为 YAML 列表 `ball_color: [R,G,B]` | WorkBuddy | 30min |
+| C3 | 更新 README.md 匹配当前架构 | Codex | 1h |
+| C4 | 注释清理：边界条件分工、弹性势能归属约定 | Claude | 20min |
+
+**验证**：6 个 `run_dynamics.py` 全部可运行，README 描述与代码一致
+
+### 阶段六：测试与CI（2 天）
+
+| 编号 | 内容 | 参考工具 | 工作量 |
+|------|------|---------|--------|
+| T1 | **添加 pytest 单元测试**：物理算法（Leapfrog/Euler）、文件 I/O 读写一致性 | WorkBuddy | 3-5h |
+| T2 | **多引擎一致性测试**：4 种引擎跑 case07（2 原子 10 步最小案例），输出容差内一致 | Codex | 2h |
+| T3 | 添加基础 profiling 计时（总时间、力计算、I/O 分段） | Codex | 1h |
+| T4 | 添加外部引擎校准缓存 | WorkBuddy/Claude | 1-2h |
+
+**验证**：`pytest` 绿色通过，`python run_dynamics.py --engine python` 与 `--engine c` 结果一致
+
+---
+
+## 四、总体工作量估算
+
+| 阶段 | 内容 | 预估人天 | 依赖 |
+|------|------|---------|------|
+| 一 | Bug 修复 | 1 天 | — |
+| 二 | Python 引擎性能优化 | 2 天 | 阶段一 |
+| 三 | I/O 与可视化优化 | 2 天 | 阶段一 |
+| 四 | 架构重构 | 3 天 | 阶段一、二 |
+| 五 | 配置与文档统一 | 1 天 | 阶段四 |
+| 六 | 测试与 CI | 2 天 | 阶段二、四 |
+| **合计** | | **~11 人天** | |
+
+---
+
+## 五、如果只做 3 件事
+
+基于三方分析共识 + 投入产出比，最值得做的三件事：
+
+1. **弹簧力向量化**（Claude 给出完整代码，Python 引擎性能提升 5-15 倍）
+2. **Fortran 引擎支持 `save_trajectory=0`**（WorkBuddy + Claude 共识 P0，所有引擎行为一致的必要条件）
+3. **新增 `display.npz` 二进制格式**（Codex 独有见解，统一切换 I/O 性能瓶颈）
+
+---
+
+## 六、工具选择建议
+
+| 场景 | 推荐工具 | 原因 |
+|------|---------|------|
+| 找 Bug | **Claude** | Bug 发现能力最强（5 个确切 Bug） |
+| 性能优化（向量化） | **Claude** | 给出可直接替换的 Numpy 向量化代码 |
+| 架构重构 | **WorkBuddy** | 熟悉整体代码结构，有模块拆分/状态封装的具体方案 |
+| I/O 策略设计 | **Codex** | 战略思维好，提出二进制格式等创新方案 |
+| 实施顺序 | **Codex + WorkBuddy** | Codex 的 profiling-first 理念 + WorkBuddy 的 P0-P3 优先级 |
+| 确认 Bug 是否真实 | **实际运行测试** | 三方都是静态分析，最终需要运行确认 |
+
+---
+
+*本文档综合了 WorkBuddy（实机验证）、Claude Sonnet 4.6（静态 Bug 挖掘）、Codex/GPT-4o（战略思维）三方的分析。建议在实施每个阶段前，先用相关案例运行确认 Bug 现象和优化收益。*