VALE 是面向 Minecraft 1.7/1.8 PvP 玩家的静态材质包浏览、下载与以图搜图网站,部署于 vale.cc.cd。
主仓库 Sakyvo/VALE 只保存站点代码、索引和缩略图;材质包归档保存在远端 Sakyvo/packs-NNN。
SBI 是项目核心能力,必须同时维持准确率、响应速度和静态托管兼容性。
- 技术栈:HTML、CSS、原生 JavaScript、CommonJS Node.js、Python、GitHub Actions/Pages。
assets/:共享样式、浏览器逻辑和字体。scripts/:上传、提取、索引、页面和 SBI 数据生成工具。data/、thumbnails/:目录数据、指纹分片和提取资源。p/、l/:生成的 pack 与 List 路由页面。tests/、test_sbi.py:Node 测试和 SBI Edge 回归。.docs/:开发契约、研究记录、issues 和历史归档。
- Node 测试:
npm test - JavaScript 语法检查:
node --check <changed-file.js> - 生成公开索引:
npm run index - 生成路由页面:
node scripts/build.js - 生成 SBI 指纹:
npm run sbi:data - SBI 回归:
python test_sbi.py - 完整内容指纹扫描:
npm run packs:scan-content -- --concurrency 6
- 每次任务开始先执行
git pull,完成并验证后执行git push;用户明示跳过时仅对当次任务生效。 - 领取“下一个 issue”时先按
Executor过滤当前工具,再从匹配项中选择编号最小的 open、无阻塞 issue;Codex 不执行Executor: Claude Code的任务,Claude Code 反之。 - 主仓库不得出现材质包
.zip或resourcepacks/;提交前检查 tracked/staged 文件。 - 材质包只长期保存在远端
Sakyvo/packs-NNN;.vale-pack-upload仅作临时中转并必须在成功或失败后清理。 - 远端仓库达到 5GB 时写入
! FULL !,然后使用或创建下一个编号仓库。 - 修改 registry、List 或生成器后,运行权威生成命令并检查生成差异;不要批量手改生成页面或 JSON。
- 新增或修改页面时沿用共享 CSS 变量、边框、字体、间距、顶栏和控件样式。
- 主页与 List 页面必须保持一致:同一 pack 在两处的卡片结构、徽章、名称字体和交互行为必须相同;修改任一处时同步另一处。
- 主页类 pack 链接使用新标签页及
noopener noreferrer;搜索只在提交后渲染,清空输入时立即恢复全部结果。 - 修改 SBI 匹配器或指纹数据时同步版本常量和 HTML cache buster,并运行
python test_sbi.py。 - 站点经 Cloudflare 缓存(静态资源 4 小时):修改
style.css或共享 JS 后,必须统一 bump 全站 HTML 引用的?v=版本号(含重新生成p/*),否则线上长时间不生效。 - 不得根据扫描结果直接删除或替换远端包;必须执行完整内容判定、人工保留决策和两阶段清理。
- pack/List 名新增非拉丁字符后,运行
python scripts/subset-font.py更新字体子集(同时生成名称像素字体与 HarmonyOS Sans UI 字体)。
- 修改远端仓库分配、registry 或下载链接时,读
.docs/PACK_STORAGE.md。 - 扫描、上传、判重或替换材质包时,读
.docs/PACK_INGESTION.md和.docs/PACK_CONTENT_IDENTITY.md。 - 修改页面、浏览器交互、状态、样式或生成流程时,读
.docs/frontend/index.md。 - 修改 SBI 算法、权重、分片或版本时,读
.docs/SBI_SEARCH.md。 - 维护 Overlay/Conquest 分类时,读
.docs/OVERLAY_DETECTION_PLAN.md。 - 查阅旧 Trellis 工作记录时,读
.docs/archive/trellis-tasks/INDEX.md。
- 用户当前明确指令。
- 更近目录的
AGENTS.md。 - 本文件。
- 本文件路由到的
.docs/*.md。