新手必读:Handwired 核心概念完全指南——Cell 单元、Builder 代码与 Host 循环一文讲透

原创2026-10-19 22:30:031,656 阅读

新手必读:Handwired 核心概念完全指南——Cell 单元、Builder 代码与 Host 循环一文讲透

Handwired 是一个开源项目,它能把普通的 JavaScript 代码"编译"成一个神经网络:把 if-else、循环和状态全部转换成矩阵乘法 + ReLU 运算,无需训练、结果精确,而且全程可微分。本文将面向新手,一次性讲透 Handwired 神经网络的三大核心概念:Cell 单元、Builder 代码和 Host 循环,并带你跑通官方的 toggle 开关示例。

Handwired 是什么:把代码变成神经网络 🧠

Handwired 的核心思路非常直接:

一个程序由 if-else、循环和状态构成,Handwired 把它们统统转换成 矩阵乘法 + ReLU(对浮点数取 ReLU 的 reglu)。

举个最小例子。下面的 JS 三元表达式:

const a = 5
const result = (a > 4) ? 10 : 12

可以改写成纯算术形式:

// Math.max(0, x) 就是 ReLU
const above4 = Math.max(0, a - 4) - Math.max(0, a - 5) // a > 4 时为 1,否则为 0
const result = above4 * 10 + (1 - above4) * 12 // 两个分支都算,用 above4 选一个

Handwired 把所有 +、*、ReLU 收集成一个巨型 matmul,在 JS(CPU)或 WebGPU 上运行。因为只用了这两种原语,带来三个好处:

  • ✅ 整个程序保持可微分
  • ✅ 权重是手写的,不需要训练
  • ✅ GPU 的融合、稀疏化等优化技巧可以直接套用

最终效果是惊人的:JSON 搜索 demo 在每次击键时能毫秒级搜索 10 万份文档;HandwiredOS 则用一个编译好的程序驱动了一整个带三个窗口和 Dock 的迷你桌面系统。

Handwired 神经网络驱动的迷你操作系统 HandwiredOS:Monitor、Notes、Photos 三个窗口与 Dock 全部由一个神经程序控制

上图就是 HandwiredOS 演示界面:左侧 Monitor 窗口实时展示这个神经程序本身(234 个状态 Cell、4,646 个有效操作、130 层),右侧是 Notes 和 Photos 窗口。整个系统的所有权重都由 Builder 代码手写,没有任何训练环节。更多细节见 src/handwiredos/README.md。

概念一:Cell 单元——程序的"内存格" 📦

在 Handwired 中,程序读入的每一个数字,都是**源表(source table)**里的一个 Cell 单元。源表就是一个 Float32Array(32 位浮点数组)。Cell 分六种,由 src/runtime/cells.ts 中的函数声明:

声明函数 语义 典型例子
constant(value, range) 初始表里设一次,之后保持不变 12px 的边距
input(range, {initial, grid}) 每次求值前由 JavaScript 写入,且被保留 视口宽度
inputBit(initial) 只能是 0 或 1 的输入 弹簧是否允许停止
event() 事件到达时 JS 置 1,程序随后清零 一次指针按下(旁边配坐标单元)
state(range, {initial, grid}) 由程序自己计算 弹簧的速度
stateBit(initial) 只能是 0 或 1 的状态单元 开关是否打开

两个关键"承诺"(promise):

  • range(值域):声明 Cell 的取值范围。每次求值都会检查,越界会直接抛错;
  • grid(网格):声明值都是某个 2 的幂的倍数(如指针坐标对齐到 1/64 px),这能大幅降低比较运算的成本。

官方 toggle 模板中的声明(节选自 template/toggle.ts):

export const toggleCells = {
  viewportWidth: input([0, 16_384], {initial: 1280, grid: 1}),
  down: {active: event(), x: coordinate(), y: coordinate()},
  on: stateBit(),   // 开关是否打开
  armed: stateBit(),// 是否已"预压"
  thumb: {
    displacement: state([-2 * layout.travel, 2 * layout.travel]),
    velocity: state([-64 * layout.travel, 64 * layout.travel]),
    destination: state([0, layout.travel]),
  },
}

💡 Wire(线) 是另一个重要词汇:一个数字在表中的位置,既可以是 Cell,也可以是某次运算的结果。声明完 Cell 后,table.declare 会为每个 Cell 分配位置并返回对应的 wire。

概念二:Builder 代码——一次性的"施工脚本" 🏗️

你不直接写那条运算列表,而是写 Builder 代码:一段普通的 JavaScript,只运行一次,负责把运算追加到 Circuit 上。构建完成后,程序运行时没有任何分支和循环。

一个程序最终只有 4 种指令(详见 docs/execution-model.md):

  • affine:加权和(circuit.affine(terms, bias))
  • reglu:乘积 + ReLU(circuit.reglu)
  • boolean:把分数四舍五入成精确的 0 或 1
  • indexRead:按整数索引查表

Builder 函数(也叫宏)负责把熟悉的 JS 表达式展开成这些指令。toggle 模板中最有代表性的几个:

// JS: if (down) armed = insideTrack(down)
const armedAfterDown = emitSelect(circuit, cells.down.active, cells.armed, insideTrack(cells.down))
// JS: if (up && armed && insideTrack(up)) on = !on
const on = emitSelect(circuit, all(cells.up.active, armedAfterDown, insideTrack(cells.up)), cells.on, not(cells.on))

几个 Builder 世界的"翻译规则":

  1. emitCompare 替代 >=/<:返回一个精确的 0/1 位,对声明范围内的所有 FP32 值都与 JavaScript 比较结果一致;
  2. emitSelect 替代 if:两个分支都会计算,再用条件位挑一个——所以"给 Cell 赋值的 if"变成了"对该 Cell 下一个值的 select";
  3. 重新赋值变成新 wire:JavaScript 里 armed = ... 是覆盖变量,Builder 代码里则是 armedAfterDown 持有新值,cells.armed 仍是上一次求值的结果;
  4. table.next 提交状态:每个 state Cell 必须且只能拿到一个"下一个值",table.finish() 后程序才算构建完成。

Circuit 类与全部 Builder 函数位于 src/runtime/numeric-ui-core.ts。每个单表达式(如 a >= b、Math.min(a, b))怎么精确实现,见 docs/expressions.md;循环类模式(findIndex、排序等)如何转换,见 docs/patterns.md。

概念三:Host 循环——程序之外的 JavaScript 🔄

程序本身只会在一张源表上"跑一遍"。真正驱动它的是 Host:包围在程序外面的 JavaScript。Host 的职责是:

  1. 把浏览器输入写进 Cell;
  2. 运行一次程序(称为一次 evaluation / 求值);
  3. 把程序算出的下一个状态值抄回表里;
  4. 把输出写进 DOM。

Host 的关键组件是 src/runtime/host-timing.ts 中的 advanceFrame,它负责为每一帧规划求值:

  • 事件处理器只负责排队(带时间戳);
  • 每个不同的事件时间戳对应一次求值,且先把弹簧步进到该时间戳再应用事件;
  • 每 64ms 模拟时间做一次"沉降检查",让弹簧在固定时刻精确停下;
  • 帧自己的那次求值跑在表的副本上,因此存储状态只依赖事件、不依赖帧率。
machine.clock = advanceFrame(machine.clock, frameTime, queued, evaluation => {
  values[cells.settleCheck] = evaluation.settleCheck ? 1 : 0
  values[cells.viewportWidth] = viewportWidth
  for (const {kind, x, y} of evaluation.events) { /* 把事件写进对应 Cell */ }
  const result = evaluate(values)        // 运行程序
  if (evaluation.writesBack) source.set(result.nextValues) // 抄回状态
  frameOutput = result.output
  return result.output.active > 0         // 是否还有动画、要不要再要下一帧
})

动画是 Host 的拿手戏:程序不能"循环一个只有运行时才知道的次数",而弹簧每帧要走多少个固定 4ms 步长正取决于时间间隔。解决办法是——n 步 = 步长矩阵的 n 次方。Host 在 JS 里算好这个 2×2 矩阵的幂,把 4 个数字写进 springMatrix 单元,程序只需应用一次。

最后,页面用 requestAnimationFrame 每帧调用一次 machine.step(...),再把输出写进 DOM(transform、aria-checked 等),只在时钟还在运行时才请求下一帧。

WebGPU 用 Handwired 生成的神经电路逐像素渲染的文本帧示例:由 matmul 与 ReLU 计算出的字形像素

三大概念如何协同:一次点击的完整旅程 ⚡

把上面的 toggle 开关串起来看,一次"点击开关"是这样流动的:

  1. Host 收到 pointerdown,把事件(类型、x/y、时间戳)排队;
  2. 下一帧 advanceFrame 规划求值:先把弹簧步进到事件时间戳,再把 down.active、down.x、down.y 写进 Cell;
  3. 程序求值:emitCompare 比较指针是否在轨道内 → emitSelect 决定 armed 和 on 的下一个值 → 弹簧矩阵推进 thumb 的位移与速度;
  4. Host 抄回状态(source.set(result.nextValues)),事件 Cell 自动清零;
  5. Host 写 DOM:track 和 thumb 的 translate3d 更新,开关"啪"地弹到另一边。

整个过程没有任何训练、没有采样误差,结果与纯 JS 参考实现逐位对齐——这正是 template/toggle.test.ts 每帧对比验证的内容(位置误差 < 1e-5 px)。

新手上手路径:从模板到你的第一个应用 🚀

第一步:跑起来(仓库需要 Bun):

git clone https://gitcode.com/gh_mirrors/ha/handwired
cd handwired
bun install
bun run start:template   # toggle 开关演示,http://localhost:3000/
bun start                # 完整演示站(含 HandwiredOS),http://127.0.0.1:3000/

第二步:按顺序读文档(docs/README.md 推荐的阅读顺序):

文档 内容
docs/tutorial.md 逐行走读模板:Cell 声明、Builder 代码、Host 循环、DOM 写入、测试
docs/expressions.md 单个表达式(a >= b、Math.min、查表)的精确实现
docs/patterns.md 循环的神经化:计数、树、表、对每个元素做同样的事
docs/behavior-choices.md 影响用户体验的取舍:命中"目标位置"而非"绘制位置"等
docs/execution-model.md 参考手册:4 种指令、舍入规则、每个 Builder 函数的契约

第三步:写自己的应用:把 template/ 复制到仓库根目录下的新文件夹(如 counter/),在 tsconfig.json、scripts/check.ts 和 package.json 的 test 脚本中登记,然后开始改 Builder 代码。完整步骤见 docs/tutorial.md。

常见问题速答 ❓

Q:Handwired 会把现有 JS 源码自动转成神经网络吗? 不会。没有这样的工具——你写的是 Builder 代码,它"一次性"把运算追加进 Circuit。docs/README.md 明确说明了这一点。

Q:真的完全不需要训练吗? 对,所有权重都是 Builder 代码手写的。但正因为程序可微分,你可以"解冻"权重做训练,或把冻结程序接进一个通用神经网络一起端到端训练——这正是 src/learned-gallery/ 照片布局 demo 在做的事。

Q:性能如何? HandwiredOS 这个程序只有 234 个源 Cell、4,646 个有效操作、130 层,单次求值在 CPU 上不到 0.1ms;而 JSON 搜索 demo 把 10 万份文档留在 WebGPU 上时,一次搜索约 5ms(同等程序在 CPU 上要 13~14s)。

总结:一张表记住三大概念 📋

概念 一句话定义 关键文件
Cell 单元 源表中的一个数字:常量、输入、事件位或状态 src/runtime/cells.ts
Builder 代码 只运行一次、把运算追加到 Circuit 的普通 JS src/runtime/numeric-ui-core.ts
Host 循环 写输入 → 求值 → 抄回状态 → 写 DOM 的外层 JavaScript src/runtime/host-timing.ts
程序 4 种指令的固定列表,无分支、无循环、全程可微 docs/execution-model.md

掌握了 Cell、Builder 和 Host,你就拿到了 Handwired 的完整世界观:Cell 是内存格,Builder 是施工脚本,Host 是驱动程序的心跳。建议立刻打开 template/toggle.ts 边读边跑,一个开关就能串起全部概念——然后去 docs/tutorial.md 挑战你的第二个开关!

登录后查看全文
handwired