软件开发统一规范¶
这一页不追求面面俱到，只强调当前项目里最容易出错、也最值得统一的几条规则。
1. Python 环境统一由 uv 和 pyproject.toml 管理¶
当前项目的 Python 根目录是：
统一原则：
- 依赖写进
pyproject.toml - 环境由
.venv承载 - 通过
uv sync同步
不推荐：
- 在系统 Python 里手动乱装包
- 在 conda base 里混装
- 一边用项目
.venv，一边让 VS Code 指向别的解释器
2. 运行目录统一以 ZBin 为根¶
很多路径都默认从 ZBin 开始算：
zss.iniPythonScripts/params/data/
所以：
- Python 顶层启动优先从
ZBin运行 - 工具脚本也尽量从
ZBin视角设计
3. Python 负责组织，C++ 负责执行¶
写新功能时，先判断它属于哪一层：
- 如果是状态机、脚本组织、角色匹配、实验逻辑，优先放 Python
- 如果是高频、重计算、底层 Skill 或运动控制，优先放 C++
最忌讳的是把边界越写越糊，最后两边都维护半套逻辑。
4. 重构时不要“新旧两套并存太久”¶
当前软件章节重构的一个重要原则也是：
明确已经废弃的旧实现，可以删，或者归档，不要长期双轨维护。
原因很简单：
- 双轨最容易让新人不知道该看哪套
- 调试时很难判断实际生效的是哪份逻辑
- 最后会拖垮维护成本
5. 写 Play 时优先保证可读性¶
高层脚本最重要的是“别人能看懂你在组织什么战术”。
建议优先做到：
- 状态名清楚
- 角色意图清楚
matchStr写得能解释- 不要把大量魔法数字和几何细节直接塞进顶层
如果某段几何逻辑已经在多个脚本重复出现，优先考虑提炼到 WorldModel/。
6. 新增 C++ 能力时，顺带考虑 Python 暴露方式¶
如果某个底层能力明显对高层脚本有价值，就不要只停留在 C++ 自用状态。
可以同步考虑：
- 是否需要进
Pybind11Module - 是否应该暴露成
CppPackage接口 - 是否需要
.pyi类型提示
这样后续高层实验会轻松很多。
7. 提交代码前至少做三件事¶
- 看
git status - 确认自己修改的解释器 / 构建结果 / 运行目录是统一的
- 用最小方式验证你改的东西确实生效
很多问题都不是“代码错了”，而是“以为自己在跑新代码，实际还在跑旧二进制”。