troytt
/
diablo2-web
1
0
Fork 0
Code Issues 15 Pull Requests Packages Projects Releases Wiki Activity

[P2][CR-T6] 仓库卫生：public/ 约 54.2MB 烘焙资源入库（与 package.json 声明矛盾）、已合并 worktree 与分支未清理 #538

New Issue
Open
opened 2026-09-29 06:44:02 +00:00 by troytt · 0 comments
troytt commented 2026-09-29 06:44:02 +00:00
Owner
Copy Link

来源：#516｜优先级 P2｜评审编号 T6｜基线 e475c2e

问题描述

仓库在版本控制卫生上有两处明显不一致：

  1. public/ 下追踪了 2,191 个由 MPQ 烘焙生成的贴图与元数据文件（合计约 54.2MB），直接把 .git 撑到约 84MB，而且与 package.json 中 "No game assets are bundled" 的版权/架构声明矛盾。
  2. 本地残留已合并进 main 的 worktree 与分支，违反 AGENTS.md §7.4 的清理铁律。

证据

1. public/ 入库资产统计（git ls-tree -r -l e475c2e -- public）

子目录 追踪文件数 说明
public/overlays/ 1,178 烘焙后的 overlay 图集（.png + .json）
public/skills/ 447 技能图标与特效资源
public/missiles/ 298 投射物图集（.png + .json）
public/ui/ 259 界面切片与面板贴图
public/assets/ 9 字体（2 个 .ttf）等
合计 2,191 54,232,653 字节（约 54.2MB）；按扩展名：1,446 个 .png、743 个 .json、2 个 .ttf
  • package.json:6 声明："description": "Web-native Diablo II engine: reads assets from a user-supplied classic MPQ. No game assets are bundled."
  • 每次重跑 npm run pack:missiles、npm run pack:overlays、npm run pack:ui 都会直接改写大批二进制 PNG，造成巨大的 git diff 与历史体积膨胀。

2. 已合并但未清理的 worktree 与本地分支

AGENTS.md:107-108（§7.4）规定："合并并推送成功后，立即执行 git worktree remove .worktrees/<topic> 与 git branch -d <type>/<topic>，并执行 git worktree prune，确保不遗留悬空 worktree 或分支。"

当前工作区中残留以下已完全合入 main 的 worktree 与分支：

  • .worktrees/runeword-system（分支 feat/runeword-system，其提交已合入 main）
  • .worktrees/set-items（分支 feat/set-items，其提交已合入 main）
  • 本地分支 feat/issue-507-socket-system（已合入 main，未删除）

根因

  • 离线烘焙管线（scripts/pack-*.ts）直接将产物输出到 public/，而 .gitignore 没有忽略这些可由本地 MPQ 确定性重生成的目录，提交时顺手 git add 入库。
  • 多智能体并行开发合并后漏跑了收尾清理命令。

修复指南

  1. 明确烘焙资产的托管策略（二选一，与 package.json 保持一致）：
    • 方案 A（推荐，符合 package.json 声明）：代码仓不追踪从商业 MPQ 导出的烘焙贴图。
      1. 在 .gitignore 中忽略 public/missiles/、public/overlays/、public/skills/、public/ui/（保留必要的开源占位或字体说明）；
      2. 执行 git rm -r --cached public/missiles public/overlays public/skills public/ui 从当前索引移除；
      3. 提供一键烘焙命令 npm run pack:all（串联 pack:ui、pack:missiles、pack:overlays、pack:entities 等，读取 #536 中的 D2_DATA_DIR），并在构建/部署流水线或独立私有制品桶中托管预烘焙包；
      4. 可选（需仓库所有者单独决定）：是否使用 git filter-repo 清理历史提交中的二进制体积（会重写历史 SHA，不建议在日常 PR 中做）。
    • 方案 B（若决定保留在当前私有 Gitea 仓内以便免烘包直接预览）：
      1. 修改 package.json 的 description 与 README.md，删除 "No game assets are bundled" 的不实描述，明确仓库仅限私有部署；
      2. 将 public/**/*.png 迁移到 Git LFS，避免每次微调透明阈值或调色板都把几十 MB 的二进制 blob 直接写进常规模特对象库。
  2. 清理已合并的 worktree 与本地分支（由仓库所有者在本机执行）： 
    git worktree remove .worktrees/runeword-system
git worktree remove .worktrees/set-items
git worktree prune
git branch -d feat/runeword-system feat/set-items feat/issue-507-socket-system

验收标准

  • public/ 的托管方式与 package.json / README.md 的声明一致（要么从 git 索引移除并由 npm run pack:all 生成，要么更新文档并接入 Git LFS）。
  • git worktree list 只剩主工作区（或当前正在开发的活跃 worktree），git branch --merged main 不再残留已合并的历史特性分支。
  • npm run typecheck 0 error；npx vitest run 全部通过。

相关

  • #532：约 8 万行生成的 *-meta.ts 文件与构建产物拆分。
  • #536：D2_DATA_DIR 环境变量约定。
> 来源：#516｜优先级 P2｜评审编号 T6｜基线 `e475c2e` ## 问题描述 仓库在版本控制卫生上有两处明显不一致： 1. **`public/` 下追踪了 2,191 个由 MPQ 烘焙生成的贴图与元数据文件（合计约 54.2MB）**，直接把 `.git` 撑到约 84MB，而且与 `package.json` 中 "No game assets are bundled" 的版权/架构声明矛盾。 2. **本地残留已合并进 `main` 的 worktree 与分支**，违反 `AGENTS.md` §7.4 的清理铁律。 ## 证据 ### 1. `public/` 入库资产统计（`git ls-tree -r -l e475c2e -- public`） | 子目录 | 追踪文件数 | 说明 | |---|---|---| | `public/overlays/` | 1,178 | 烘焙后的 overlay 图集（`.png` + `.json`） | | `public/skills/` | 447 | 技能图标与特效资源 | | `public/missiles/` | 298 | 投射物图集（`.png` + `.json`） | | `public/ui/` | 259 | 界面切片与面板贴图 | | `public/assets/` | 9 | 字体（2 个 `.ttf`）等 | | **合计** | **2,191** | **54,232,653 字节（约 54.2MB）**；按扩展名：`1,446` 个 `.png`、`743` 个 `.json`、`2` 个 `.ttf` | - [package.json:6](https://git.projectdiablo2.cn/troytt/diablo2-web/src/commit/e475c2e6d8a6e85eabb607525d9d87beca9fbee3/package.json#L6) 声明：`"description": "Web-native Diablo II engine: reads assets from a user-supplied classic MPQ. No game assets are bundled."` - 每次重跑 `npm run pack:missiles`、`npm run pack:overlays`、`npm run pack:ui` 都会直接改写大批二进制 PNG，造成巨大的 git diff 与历史体积膨胀。 ### 2. 已合并但未清理的 worktree 与本地分支 [AGENTS.md:107-108](https://git.projectdiablo2.cn/troytt/diablo2-web/src/commit/e475c2e6d8a6e85eabb607525d9d87beca9fbee3/AGENTS.md#L107-L108)（§7.4）规定："合并并推送成功后，立即执行 `git worktree remove .worktrees/<topic>` 与 `git branch -d <type>/<topic>`，并执行 `git worktree prune`，确保不遗留悬空 worktree 或分支。" 当前工作区中残留以下已完全合入 `main` 的 worktree 与分支： - `.worktrees/runeword-system`（分支 `feat/runeword-system`，其提交已合入 `main`） - `.worktrees/set-items`（分支 `feat/set-items`，其提交已合入 `main`） - 本地分支 `feat/issue-507-socket-system`（已合入 `main`，未删除） ## 根因 - 离线烘焙管线（`scripts/pack-*.ts`）直接将产物输出到 `public/`，而 `.gitignore` 没有忽略这些可由本地 MPQ 确定性重生成的目录，提交时顺手 `git add` 入库。 - 多智能体并行开发合并后漏跑了收尾清理命令。 ## 修复指南 1. **明确烘焙资产的托管策略（二选一，与 `package.json` 保持一致）**： - **方案 A（推荐，符合 `package.json` 声明）**：代码仓不追踪从商业 MPQ 导出的烘焙贴图。 1. 在 `.gitignore` 中忽略 `public/missiles/`、`public/overlays/`、`public/skills/`、`public/ui/`（保留必要的开源占位或字体说明）； 2. 执行 `git rm -r --cached public/missiles public/overlays public/skills public/ui` 从当前索引移除； 3. 提供一键烘焙命令 `npm run pack:all`（串联 `pack:ui`、`pack:missiles`、`pack:overlays`、`pack:entities` 等，读取 #536 中的 `D2_DATA_DIR`），并在构建/部署流水线或独立私有制品桶中托管预烘焙包； 4. *可选（需仓库所有者单独决定）*：是否使用 `git filter-repo` 清理历史提交中的二进制体积（会重写历史 SHA，不建议在日常 PR 中做）。 - **方案 B（若决定保留在当前私有 Gitea 仓内以便免烘包直接预览）**： 1. 修改 `package.json` 的 `description` 与 `README.md`，删除 "No game assets are bundled" 的不实描述，明确仓库仅限私有部署； 2. 将 `public/**/*.png` 迁移到 Git LFS，避免每次微调透明阈值或调色板都把几十 MB 的二进制 blob 直接写进常规模特对象库。 2. **清理已合并的 worktree 与本地分支**（由仓库所有者在本机执行）： ```bash git worktree remove .worktrees/runeword-system git worktree remove .worktrees/set-items git worktree prune git branch -d feat/runeword-system feat/set-items feat/issue-507-socket-system ``` ## 验收标准 - [ ] `public/` 的托管方式与 `package.json` / `README.md` 的声明一致（要么从 git 索引移除并由 `npm run pack:all` 生成，要么更新文档并接入 Git LFS）。 - [ ] `git worktree list` 只剩主工作区（或当前正在开发的活跃 worktree），`git branch --merged main` 不再残留已合并的历史特性分支。 - [ ] `npm run typecheck` 0 error；`npx vitest run` 全部通过。 ## 相关 - #532：约 8 万行生成的 `*-meta.ts` 文件与构建产物拆分。 - #536：`D2_DATA_DIR` 环境变量约定。
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
main
fix/p0-issues-516
feat/runeword-system
feat/issue-507-socket-system
feat/automap-113c
Labels
Clear labels
No items
No Label
Milestone
Clear milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
No Assignees
1 Participants
Notifications
Due Date
The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: troytt/diablo2-web#538
No description provided.
Delete Branch "%!s(<nil>)"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?