BHGL / DCCTools / 通用规范
🏠 BHGL 主页 | DCCTools 追踪台

通用规范 · 四项目共用

仓库根的 CODEBUDDY.md —— 无论打开哪个子项目工作区，都会自动向上继承本文件
项目数
4 个
仓库
单仓库
共用规范
CODEBUDDY.md
归档区
_archive/ 只读

仓库结构

DCCTools/
├── CODEBUDDY.md        # 共用规范（自动向上继承，勿改名/移动）
├── uvpack/             # C++ 引擎 + Blender 插件 v2.7.2 + 开发测试台
├── blender-export/     # UE5 导出 v3.49.0（含 docs/ 与 Log/）
├── blender-modifiers/  # Boolean/Slice/Fracture v3.48.0
├── ps-plugin/          # PS UXP 插件（quick-export，git submodule）
├── scripts/            # 跨项目脚本
├── builds/             # 打包产物
└── _archive/           # 已归档旧快照（只读，勿引用）

工作区使用方式（影响上下文成本）

规则注释
每个项目单独开 IDE 工作区 不要长期开着 DCCTools 父目录——那会把四个项目全带进上下文，且项目级规则不会加载。父目录只在做跨项目整理时打开。
父目录搜索要限定 path 在父目录里全库搜索时，必须限定到目标项目目录，否则四个项目的结果一起进上下文。
_archive/ 只读 里面是旧引擎快照（缺 bitmap_pack.cpp）、失效脚本、v0.2.0 旧版等死数据，引用会出错。

三层上下文结构

这是 2026-09-14 重构的核心：共用规范放顶层，项目细节下沉，避免开发一个项目时被迫带上另外三个的细节。
层级文件加载方式
全局规范CODEBUDDY.md自动 向上递归查找，四个项目共用一份
项目规则.codebuddy/rules/context.md自动 仅当前工作区
项目上下文AI_CONTEXT.md按需 硬性门禁：改代码前必读
为什么共用规范叫 CODEBUDDY.md：这是 CodeBuddy 唯一会从工作目录向上递归查找的项目级记忆文件。AI_CONTEXT.md、WORKFLOW.md 这类自定义文件名都不会被自动加载——改名或移走会导致共用规范在子项目里失效。

提交规范

规则注释
每轮结束提交保护点 撤销卡片、误操作时才有得回退。PS 插件就发生过 style.css 改动被 IDE 撤销卡片回退的事故。
提交前扫 git status --short 确认改动范围只限当前项目，别把无关项目的改动混进来。
禁止父仓库 reset --hard / checkout . 曾因此把 ps_plugin/quick-export 工作树覆盖成旧版（manifest 闪 0.7.0、4912 行删除）。现已是 submodule，风险结构性杜绝，但仍禁止。
不 force push 到 main —
改 PS 插件要推两次 quick-export 是 submodule：先推子仓库，再推父仓库。顺序反了父仓库 gitlink 会指向远端不存在的 commit，别人 clone --recursive 直接失败。

版本管理

  • 版本号规则 (主, 次, 补丁)：功能新增升次版本，Bug 修复升补丁
  • 版本真理源是各项目的清单文件，不是文档：
    • uvpack / blender-export / blender-modifiers → blender_manifest.toml
    • ps-plugin → quick-export/manifest.json（改完跑 npm run version:sync）
  • 目前只有 blender-export/CHANGELOG.md 存在，且停更在 3.9.0（实际 v3.49.0），不可当版本依据。其余项目不强制建 CHANGELOG。

基本规范

  • 交流语言：中文
  • 交付格式：简短说明变更 + 完整可运行代码 + 版本号。不展示伪代码，不长篇大论
  • 代码注释用英文，文档可用中文。注释解释「为什么」而非「做什么」
  • 不擅自修改已稳定的功能模块，除非明确要求
  • 不擅自改动版本号，除非明确要求升级