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/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 三阶段顺序实施。*