dynamics/optimization/workbuddy_v2.md

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
A2	dynamics.py 绘图块添加保护（短期） / 从 display.txt 重建（长期）	claude_v1 §3	30min
A3	Fortran 引擎写 display.txt（参照 C 引擎 write_display_txt）	claude_v1 §4	2-3h
A4	小修复：case06 文字 / draw.py except / C++ 默认值 / 相机函数去重 / 废弃函数清理	claude_v1 §5	30min
A5	B1 修复：camera_distance/elevation/azimuth 改为全局变量（短期补丁）	claude_v1 §2	15min

验证标准：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
B2	固定约束原地掩码写回，消除 column_stack	claude.md §P2	30min
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
B6	外部引擎校准缓存	claude_v1 §8	1h
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
C2	全局变量 → SimulationState 类（是 A5 补丁的长期替代）	workbuddy.md §3.1 + claude_v1 §10	3-4h
C3	统一 6 案例 input.txt 格式 + ball_color 列表化	workbuddy.md §4.1-4.2	1-2h
C4	pytest 单元测试（物理算法 + I/O 往返 + 参数边界）	workbuddy.md §5.1	3-5h
C5	多引擎一致性测试 + profiling 计时	codex_v1 + claude_v1	2h
C6	C/C++ 引擎共用公共头文件	workbuddy.md §1.2	2-3h
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 三阶段顺序实施。