WC4 BTL Reference

外观

BTL Reference HTML 站点构建与分发 ​

1. 定位 ​

本页只描述 reconstruction/docs/btl-reference/ 的 HTML 展示层。

Markdown 与 reports/btl_reference/*.json 继续承担 BTL Reference 的正文和机器 authority。VitePress 配置、主题和构建产物不得反向定义字段语义、版本规则或写入权限。

2. 固定工具链 ​

当前展示层固定：

text
Node.js: 24.x compatible
VitePress: 2.0.0-alpha.19 (exactly pinned)
Resolved Vite: 8.2.1
Dependency lock: package-lock.json

安装依赖：

text
npm ci

本地编辑预览：

text
npm run docs:dev

正式静态构建：

text
npm run docs:build

构建输出：

text
.vitepress/dist/

本地检查正式构建：

text
npm run docs:preview

构建、内部链接、核心页面、搜索索引和 HTTP smoke 的 focused gate：

text
npm run docs:check

联网依赖安全检查：

text
npm run docs:audit

.vitepress/dist/ 和 node_modules/ 都是可重建本地产物，不进入 Git。

3. 当前站点能力 ​

当前站点使用 VitePress 默认文档主题并做有限 CSS 扩展，提供：

  • 简体中文导航；
  • Header、Country、Building、Unit、Event、Reinforcement、Extension 等固定侧栏；
  • 每页二至四级标题目录；
  • 深色/浅色模式；
  • 为大 offset 表放宽的正文区域；
  • 横向滚动字段表；
  • 代码高亮；
  • 浏览器内本地全文搜索；
  • 针对中文单字、双字与 0x25、ArmyAIConfig 等技术字符串的定制 tokenizer；
  • 桌面与移动端响应式布局。

4. Web 分发 ​

默认 base 为 /，适合部署在独立域名或站点根路径。

如果以后部署到子路径，例如：

text
https://example.invalid/wc4-btl/

构建时设置：

text
WC4_BTL_DOCS_BASE=/wc4-btl/

该值必须以 / 开头并以 / 结尾；站点配置会在构建时验证。VitePress 不支持相对 base。因此当前正式发布目标是静态 HTTP/HTTPS 托管，而不是直接双击 file://.../index.html。

如果未来需要“解压后双击即可离线使用”，应单独实现 OfflineExport，不能通过修改正文 Markdown 或伪造相对路由破坏主站。

5. 当前生产部署 ​

2026-08-10 已通过官方 EdgeOne CLI 直接上传生产构建，建立独立发布项目：

text
Provider: Tencent EdgeOne Makers
Project: wc4-btl-reference
Project ID: makers-g42c5rliovy1
Environment: production
Acceleration area: overseas
Source artifact: .vitepress/dist/
Public domain: btl.wc4.top

overseas 表示全球可用区（不含中国大陆节点），因此绑定自定义域名时不要求中国大陆 ICP 备案。平台生成项目域名和部署域名不是面向中国大陆用户的正式入口；公开分发应使用自定义域名 btl.wc4.top。

当前远程状态：生产构建已经部署成功，btl.wc4.top 已完成 EdgeOne 自定义域名绑定和 Cloudflare DNS CNAME 配置，并可通过 HTTPS 正常访问。后续 Reference 更新仍必须先通过本地 docs:check 等门禁，再独立执行 R3 生产发布。不得在仓库中保存 EdgeOne 登录 token、Cloudflare API token、浏览器 cookie 或临时带 token 的预览 URL。

2026-08-10 Event producer/lifecycle Reference 更新 ​

本次 substantive Reference 发布对应本地 authority commit：

text
1997cb96aca6cb7afcb0698e002f75bf25ea396f

EdgeOne production deployment：

text
Deployment ID: dpa0day0v1ko
Environment: production
Area: overseas
Result: Deploy Success

发布后对正式域名进行了自动化公网内容验收，而不只检查部署命令退出码：

text
https://btl.wc4.top/records/building       HTTP 200 + 新增 native 指令地址命中
https://btl.wc4.top/records/reinforcement  HTTP 200 + 新增 spawned-Unit death Event 证据命中
https://btl.wc4.top/records/event          HTTP 200 + Type3 / executed lifecycle 新统计命中
https://btl.wc4.top/values/event           HTTP 200 + 对应值域正文命中

结果：PUBLIC_VERIFY_PASS。本次只记录自动化 HTTP/content acceptance；没有把它冒充成人工浏览器视觉验收。EdgeOne CLI 的原始临时输出可能含 tokenized URL，因此不进入仓库。

6. 第三方许可 ​

直接展示层依赖为精确固定的 VitePress 2.0.0-alpha.19，许可证为 MIT。它是预发布版本，因此升级必须单独运行完整 docs:check；当前选择该版本是为了避免 VitePress 1.6.4 稳定版依赖链中的已知 Vite dev-server 高危漏洞。精确依赖树由 package-lock.json 固定，当前 npm audit --audit-level=high 为 0 vulnerabilities。

公开分发构建产物前，应同时保留构建所包含第三方组件要求的版权和许可证通知。当前直接依赖说明见 THIRD_PARTY_NOTICES.md。