本项目所有显著变更都记录在此文件中。
格式基于 Keep a Changelog, 版本号遵循 语义化版本。
本轮是副副旗舰深度升级:不靠 issue 清单,直接真跑 GPU 数值梯度测试,抓出三个会让训练结果静默错误的真 bug,并修掉一个会让 GPU 测试拿旧构建产物验证的假绿通道。
- ReLU 梯度用错对象:旧实现用
sign(relu(x))判定导数,而relu(x) >= 0,整个负半轴都拿到0.5的虚假梯度;死 ReLU 本该完全不更新。改为用输入sign(x),并由 GPU 数值梯度测试钉死。 - 广播轴
sumTo选错轴:旧启发式比较首维,遇到[2,2] * [2]这类方形张量会把行广播误判成列广播,梯度 reduce 到错误的轴(真跑出现 3 vs 4 的偏差)。改为与broadcastMode一致的尾部对齐规则:目标尾维等于当前尾维 → 行广播,sum 掉首轴;否则 sum 掉尾轴。 pow完全没有注册反向传播:powDef/powScalarDef只存在前向算子,backward()遇到幂运算会静默产出null,训练 containing power term 的 loss 会整段丢梯度。补上x^y双操作数梯度g·y·x^(y-1)/g·x^y·ln(x)与标量指数梯度g·c·x^(c-1),并加两个 GPU 数值梯度回归。- GPU 测试假绿通道:
test:gpu直接加载dist/moxwebgpu.browser.js,但不先构建;源码修完后旧 bundle 仍在被验证。现把test:gpu改成先pnpm build再跑浏览器测试,避免拿过期产物当真绿/真红。
pnpm exec tsc --noEmitEXIT=0。pnpm testEXIT=0:3 文件 / 66 单元测试全过。pnpm test:gpuEXIT=0:先真构建(ESM/CJS/IIFE/DTS),再在 SwiftShader Vulkan 上跑 5 文件 / 37 GPU 端到端测试全过,包含新增 pow 数值梯度回归。pnpm benchEXIT=0(真实 GPU dispatch + readback,SwiftShader 软件渲染,数值随机器负载波动):add 1M f32 67.80 ms;matmul 512×512 597.70 ms(0.45 GFLOP/s);sum 1M f32 35.30 ms;add→relu→mul→sum 1M 199.10 ms。dist/index.js中MOXWEBGPU_VERSION由构建期注入为1.1.4。
- 升级 devDependencies 到最新兼容版(不升破坏性 MAJOR):
vitest3.2.7 → 4.1.12(修复 tinypool 原型污染 RCE 与 @vitest/mocker 路径穿越等 critical / moderate 漏洞)tsup8.5.1 → 9.0.0(构建链路,已验证产物一致)@types/node22.20.5 → 26.6.6(类型定义,仅 dev)
- 保留
pnpm.overrides不变:vite锁>=7.3.7 <8、esbuild钉0.28.2(仍为各自最新,已无已知漏洞)。 pnpm audit由 5 个漏洞(2 critical / 3 moderate)降为 0。typescript(5.x 最新)、playwright-core已是最新兼容版,未改动。pnpm build与pnpm test(66 单元测试)真实通过;dist/index.js中MOXWEBGPU_VERSION由 tsup 构建期注入且等于1.1.3。- 文档修正:README / README.en 版本徽章、npm「已发布」状态、scope 包名
@codecloud-dev/moxwebgpu与 unpkg 路径、单测数 21 → 66。
@types/node升到 26 后,CI 的pnpm exec tsc --noEmit报tests/gpu/harness.ts找不到node:fs/process:tsconfig.json的types白名单只列@webgpu/types,旧版@types/node会被自动带入、 26 收紧后不再自动解析。已将node显式加入types数组(测试代码本就用 Node API,配置本就该列),而非回退依赖。- 复核 CI 三步契约全绿:
tsc --noEmit0 错误 /pnpm build全产物 /pnpm test3 文件 66 用例全过。
计划中(见 README 路线图):f16/bf16、tensor-core matmul、多 GPU pass 融合、生态集成。
- 版本号对齐:1.0.2 → 1.1.0(维护版本,构建链路与依赖更新,无破坏性变更)。
- 发布阻断级 bug:Node 下
require/import即崩溃。根因:src/core/buffer.ts顶层常量直接引用浏览器 WebGPU 全局GPUBufferUsage,在 Node 环境(无该全局)import时即抛ReferenceError,整包不可用。改为用标准 WebGPU 位值兜底(全局存在时仍走全局),包现在可在 Node 下正常 import;实际 GPU 执行仍需浏览器 / WebGPU 运行时。
- MoX 全家桶首个大版本:moxwebgpu 随 agent-core / moxsh 系列一同升 1.0.0 发布。
0.2.0 - 2026-10-02
- 任意轴归约:
sum(axis)/mean(axis)/max(axis)/min(axis)现支持 任意 rank、任意轴(负轴从末尾数,-1即最后一轴)。新通用内核axisReduceWgsl(每输出元素一线程,沿轴串行折叠,维度走 uniform 因此全形状共享 同一管线);末轴仍走原来的 workgroup 树形快速路径。2D 的sum(0)从借道 transpose 改为直连通用内核(单 pass,累加顺序不变)。 - 整型归约可用:
i32/u32的sum/max/min全部支持 (全局 + 按轴);argmax/argmin对整型本就可用。
- i32/u32 归约此前无法编译(真 bug):累加器
var acc = uniforms.identity被推断为 f32,与整型输入combine产生 WGSL 类型错误。现在整型在 shader 内 对 f32 identity 槽做显式饱和转换(identityTyped),max/min 的 identity 按 dtype 取饱和边界(i32:±2147483647…8,u32:0/4294967295)。 mean对整型输入给出明确报错(提示先cast('f32')),而不是难以理解的 shader 编译失败。- 调度器 temp 回收加固:
runNode原用单槽prevTemp回收中间缓冲,若某算子 出现 ≥3 个 step(多个中间 temp)会泄漏。现改为tempBufs数组,本节点分配的 全部中间 temp 一律回收(当前算子行为不变,属预防性加固)。
- GPU e2e +4:3D 任意轴(轴 0/1/2、负轴、mean)、i32 全局、u32 全局(含 0 元素)、 i32 按轴;单测 +axisReduceOpDef outShape / normAxis 共 4 用例(17 → 21)。
0.1.0 - 2026-10-02
首个公开版本。核心、算子、惰性计算图、测试基建与文档全部就绪; 23 个 GPU 端到端用例在 SwiftShader(CPU 模拟 GPU)上全绿。
核心(core/)
mox.init():一行获取MoxContext(device / queue / pool / pipelines / scheduler 全组装)。BufferPool:2 的幂字节桶内存池,storage 与 uniform 严格分池,live/pooled统计,稳态 dispatch 几乎零 GPU buffer 分配。PipelineCache:WGSL 哈希 → compute pipeline 缓存; 创建后显式getCompilationInfo(),把 WebGPU 的静默失败变成带行列号的可读报错。Kernel:原始 WGSL 逃生舱,dispatch()只下发 /run()下发并读回。- dtype 体系:
f32/i32/u32+ TypedArray 工厂。
张量与算子(tensor/)
Tensor:嵌套数组 / TypedArray 构造,链式调用,惰性执行,toArray/item/toBuffer读回。- 逐元素:
addsubmuldivpowclamp+ 标量反转rsubrdiv, 支持 1D / 2D 行广播 / 列广播,形状不合法直接抛错。 - 一元 14 个:
negabsexplogsqrtsincostanhfloorceilrelusigmoidsquaresign。 - 归约:全局
summeanmaxminargmaxargmin(两阶段树形,workgroup=64 / chunk=8); 按最后一轴sum(-1)等;2Dsum(0)借道 transpose。 max/min 的 ±Infinity identity 走 uniform 槽运行时传入(绕开 WGSL const-expression 限制)。 matmul:16×16 workgroup 分块,workgroup 内存 tile 累加。- 形状:
transpose(2D)、slice(≤4D)、concat(任意轴,多 chunk 一次直写)、reshape(零拷贝视图,支持-1)。 softmax:数值稳定实现,单 workgroup 融合三遍(max → exp 求和 → 归一)。cast:f32 ↔ i32 ↔ u32,向零截断。- 统一算子 API:
max()无参 = 归约、max(-1)= 按轴、max(t)= 元素级;min同理, 并提供maxReduce/minReduce无歧义别名。
计算图(graph/)
- 惰性 DAG:建图零 GPU 开销,
toArray()/item()时拓扑排序一次性下发; - 中间 buffer 引用计数,消费者归零瞬间归还内存池;
- 已执行节点缓存结果,重复读回不重算;
- 单
CommandEncoder多 compute pass,一次queue.submit。
工程与文档
- 双构建:tsup 产出 ESM / CJS / IIFE(浏览器全局
MoxWebGPU)+ 类型声明,运行时零依赖。 - 测试:17 个单元测试(uniform 字节级校验 / 图 / OpDef)+ 23 个 GPU e2e(与 CPU 参考实现逐值比对)。
- SwiftShader 测试配方:xvfb + Chrome Vulkan ICD 自动化套壳(
pnpm test:gpu一条命令, 无 GPU 机器 / CI 均可跑真 WebGPU)。 - 微基准:
pnpm bench(中位数统计,含 add / matmul / 归约 / 链式)。 - 浏览器演示页:液态玻璃设计语言,四张卡片真跑 WebGPU(
pnpm demo)。 - CI:GitHub Actions,类型检查 + 构建 + 单测 + SwiftShader GPU e2e 双 job。
- 文档:README(中文为主,含 API 参考 / 算子清单 / FAQ)、英文版、
docs/ARCHITECTURE.md(uniform 字节表 / 调度算法 / 踩坑实录)、MIT LICENSE、FUNDING.yml。
开发过程中被测试抓出来并固化为设计的缺陷(完整复盘见 docs/ARCHITECTURE.md §8):
shared是 WGSL 保留字 → workgroup 变量统一改名smem。- ±Infinity 作为 WGSL const-expression 字面量会报 shader-creation 错误
→ uniform 增加
identity槽位运行时传入,fmtF32()对特殊值直接抛错。 - uniform 地址空间数组 stride 跨实现不一致(SwiftShader 把
array<u32,4>当 16B stride) → copy 系 struct 全部改vec4<u32>(208 B → 64 B)。 - argmin 初始候选下标可越界(OOB 读回 0 被误判为最小值)
→ 候选 clamp 至
min(start + l.x, n - 1u)。 - BufferPool storage/uniform 混池导致 UNIFORM-only buffer 被当 storage 绑定
(validation error = 静默 no-op)→ 严格分池 +
releaseUniform()。 - 每次执行泄漏 scratch UBO → submit 后统一归还池。