新手必读:Handwired 核心概念完全指南——Cell 单元、Builder 代码与 Host 循环一文讲透
新手必读: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 的迷你桌面系统。
上图就是 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 世界的"翻译规则":
emitCompare替代>=/<:返回一个精确的 0/1 位,对声明范围内的所有 FP32 值都与 JavaScript 比较结果一致;emitSelect替代if:两个分支都会计算,再用条件位挑一个——所以"给 Cell 赋值的 if"变成了"对该 Cell 下一个值的 select";- 重新赋值变成新 wire:JavaScript 里
armed = ...是覆盖变量,Builder 代码里则是armedAfterDown持有新值,cells.armed仍是上一次求值的结果; 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 的职责是:
- 把浏览器输入写进 Cell;
- 运行一次程序(称为一次 evaluation / 求值);
- 把程序算出的下一个状态值抄回表里;
- 把输出写进 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 等),只在时钟还在运行时才请求下一帧。
三大概念如何协同:一次点击的完整旅程 ⚡
把上面的 toggle 开关串起来看,一次"点击开关"是这样流动的:
- Host 收到
pointerdown,把事件(类型、x/y、时间戳)排队; - 下一帧
advanceFrame规划求值:先把弹簧步进到事件时间戳,再把down.active、down.x、down.y写进 Cell; - 程序求值:
emitCompare比较指针是否在轨道内 →emitSelect决定armed和on的下一个值 → 弹簧矩阵推进thumb的位移与速度; - Host 抄回状态(
source.set(result.nextValues)),事件 Cell 自动清零; - 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 挑战你的第二个开关!
