FlyBrain · Flappy —— 用真实果蝇脑玩 Flappy

把 FlyWire FAFB v783 果蝇全脑连接组（144,837 神经元 / 15,023,799 突触） 当成一个完全冻结、零可学参数的神经网络，去驱动一只小鸟飞过管子。

不训练。 用的是连接组里真实存在的一条逃逸反射通路：

视觉逼近  →  LC4（104 个）/ LPLC2（210 个）  →  DNp01（巨型纤维，2 个细胞）  →  拍翅

cut 与 shuffled 都是 0 次拍翅 —— 脑子不再指挥翅膀。 这就是"分数必须穿过真实连接组"的硬证据。

⚠️ 上表那些分数是在"旧噪声流"下测的（见下方"噪声流与可复现性"）。 现在的代码用每个脑独占的噪声流，所以重跑会得到统计上同类、但不逐位相同 的数字。这不是回归，而是修掉了一个可复现性缺陷 —— 具体原因写在那一节里。

网页版现在是恒定 50 步/秒、严格 1:1、60fps 流畅： 游戏仿真跑在服务端（GameWorld + 固定 50 Hz 锁步线程）， 前端只取状态 + 插值渲染。见 页面 vs 评测台。

零第三方前端依赖：只用 Python 标准库 http.server + 仓库自带的 three.js。 后端需要 numpy / pandas / torch（CPU 版即可），需要 Python ≥ 3.10。

# 依赖（CPU 版 torch 就够）
pip install numpy pandas torch --index-url https://download.pytorch.org/whl/cpu

# 起服务（默认资产就是 spiking_full，无需额外参数）
OMP_NUM_THREADS=1 python demo/server.py --no-browser --port 8620
# 浏览器打开 http://127.0.0.1:8620/

--asset 默认已是 spiking_full，正常不用传。 这里曾经是个静默失败陷阱：默认到不含 LC4/LPLC2 的 spiking_circuit 子图时， 脑完全不发放、分数恒为 0，而且不报任何错 —— 很容易被当成"反射不行"。 现在传了不含关键群的资产会在启动时被直接拒绝，并说清是哪一种问题 （群缺失 / 预烤坐标索引越界）。

Windows 下也可以直接双击 demo/run_demo.bat（关闭用 demo/stop_demo.bat）。 部署到 Linux 服务器请看 DEPLOY.md（systemd、验收清单、排障表）。

PY=python                                    # 或你的 venv 解释器

# 双向逼近反射，60 局
$PY scripts/flappy_bench.py --asset spiking_full --modes bidi --games 60 --max-ticks 5000

# 神经消融三连（这是全项目的重点实验）
$PY scripts/flappy_bench.py --asset spiking_full --modes bidi --games 40 \
    --graph real      --out output/abl_real.json
$PY scripts/flappy_bench.py --asset spiking_full --modes bidi --games 40 \
    --graph cut       --out output/abl_cut.json
$PY scripts/flappy_bench.py --asset spiking_full --modes bidi --games 40 \
    --graph shuffled  --out output/abl_shuffled.json

一个绕不开的量化事实：DNp01 每个 tick 需要 need = (1−leak)·thr/gain = 0.06042 的持续驱动，而它是漏积分的 （leak = 0.81873）—— 所以单次刺激不够，必须持续逼近才会发放。 整个控制回路的节奏都由这一条决定。

方向由缺口在视野里的高低决定：

• 缺口在上方 → 驱动 腹侧 LC4 半群 → 爬升
• 缺口在下方 → 驱动 背侧 LC4 半群 → 下潜

再加接近速度门控（地面只在下落时逼近、天花板只在上升时逼近）。 神经计算全部在后端；前端只取状态、只渲染（不再算几何、不再喂脑）。

控制回路是 scripts/flappy_bench.py 的同构版本： 按当前世界算驱动 → 走一个脑 tick → 用 DNp01 的发放决定拍不拍 → 走一步物理。 决策与物理步严格配对，中间没有网络、没有定时器节拍。

前端曾经要自己跑这个回路，试过四种驱动方式全部失败（见 页面 vs 评测台）—— 根因是浏览器没有可用的可信节拍（setTimeout(4) 被压到 29.8 次/s、 rAF 后台会被完全暂停），而 HTTP 往返抖动十几倍。

python scripts/make_doc_figures.py --out output/doc_figs python scripts/make_doc_page.py（写到桌面）

产出是一份自包含 HTML 教材（约 390 KB，双击即可离线阅读），20 节，分七部 + 附录：

1. 全局 —— 五分钟看懂、20ms 闭环总图
2. 计算基础 —— LIF 神经元、驱动门槛 need = 0.06042 的推导
3. 感觉与指令 —— LC4/LPLC2 通路、几何→驱动、够不够触发的判据
4. 反射 —— 双向逼近反射、回路闭合
5. 游戏世界 —— 物理与像素语义、关卡生成
6. 证据 —— 消融实验、逐 tick 对账、可复现性与噪声
7. 工程 —— 为什么必须服务端、六个真实 bug、负结果
8. 附录 —— 常见误解、术语表、一页带走

写法上每节分三层（直觉 / 形式 / 本项目具体数字）， 配手算算例、17 道可展开的自测题、常见误解与速查表。

两条防脱节的措施：

• 配图全部取自真实数据 —— 栅格图从跑着的仿真里逐 tick 取发放， 膜电位图按 LIF 公式逐步算出（读者可拿纸笔核对每一点）， 分布图是真实生成器的 4000 次输出。
• 正文里的常数直接从 demo/server.py 读（make_doc_page.py 里 import）， 所以改了代码重新生成，文档里的数字自动跟着变，不会出现"文档写 0.06、 代码是 0.05"这种情况。

"相邻缺口的向上跳变不能超过执行器带宽"这条约束是对的（鸟一个间隔最多净爬约 125 px， 更大的跳变物理上飞不进去）。但原来的实现方式让它退化了：

# 旧：从下方均匀抽样
uniform(lo, min(hi, prev_c + max_climb - GAP/2))

一旦缺口中心下沉，这个上界就缩到低于下界，于是退化成 uniform(70, 70) —— 恒等于 70。 实测 200 根管子：top 全是同一个值、标准差 0.0、上升次数 0/199。 那不是"不够随机"，是生成器死了；而且只用到量程的一半。

现在改成以上一根缺口中心为中心的有界随机游走，两条界都设：

next_hi = min(c_hi, prev_c + max_climb)    # 向上：受执行器带宽约束（110 px）
next_lo = max(c_lo, prev_c - max_drop)     # 向下：给一个与缺口等高的界（230 px）
c = uniform(next_lo, next_hi) + N(0, 16²)  # 再叠独立抖动
c = clip(c, next_lo, next_hi, c_lo, c_hi)  # 抖动之后必须重新夹

两个容易踩的点，都写在代码注释里了：

1. 抖动必须夹在约束之内。 我第一版把抖动加在夹取之后， 实测最大上升 211 px，超过了 110 的上限 —— 抖动把"物理可达"这条硬约束冲掉了。
2. 只设向上界不够。 那样缺口中心只能活在 [c_lo, c_hi] 死区里， 一旦被推到边界，下一根必须落在死区内 → 被迫向下掉 216 px。 这不是设计，是边界效应。

效果：缺口 top 从"恒定一个值"变成覆盖 70..250 全量程、标准差约 50 px。 代价是单局均分从约 36 降到约 31（20 局口径，在方差内）。 参数扫描见 scripts/tune_levels.py。

离线评测台 scripts/flappy_bench.py，前几档 200 局/条件：

最后一档是 40 局、max_ticks=8000（所以"最高 115"是被 tick 上限截断的， 不是真实上限）。前面几档是 200 局、max_ticks=5000。

关卡可达性是执行器带宽卡死的：管距 300 px / 240 px·s⁻¹ = 1.25 s， 而鸟的可持续爬升率只有约 100 px/s（scripts/flappy_climb_rate.py 实测）， 所以一个间隔最多爬约 125 px。原来缺口跳变有 330 px 量程 —— 超出的关卡无论如何都飞不进去。把向上跳变限制在 40 px 以内（向下不设限）之后， 分数从 7.2 跳到 29.5。管宽、缺口高、管速、重力一个都没改。

每一行都能在 output/*.json 里找到原始产物。

game_slack = 0.694 那一行特别值得注意：它正是页面当年实测的物理/脑速率比 （50 / (60×1.2) ≈ 0.694），得分只有 2.07。这把"页面为什么远低于评测台" 从猜测变成了可复现的实验。 现在这个现象不会再出现了：仿真搬到服务端之后，页面与评测台的速率比就是 1.0 （两边跑同一份物理、同一个 50 Hz），并且由 scripts/verify_server_physics.py 守着。

游戏里"看着撞上了却不判失败"这个 bug 查了很久，根因是像素与坐标混用。 最终判定由逐像素对账定出（现在这条判据在 server.py 的 GameWorld.step 里， 因为物理已经搬到服务端）：

if (self.y - self.BIRD_R <= p["top"] + self.BIRD_R
        or self.y + self.BIRD_R >= p["top"] + self.GAP - self.BIRD_R - 1):
    return self.die("撞上管子")

推导依据（闭区间像素）：

• fillRect(y, h) 覆盖像素 y … y+h-1
• 上管覆盖像素 [0, top+R]、下管覆盖像素 [top+GAP-R-1, …]
• 鸟圆周覆盖像素 [⌈y-R⌉, ⌊y+R⌋]
• 两组像素行有交集 ⇔ 视觉重叠

要求"只画不判"与"只判不画"同时为 0。历史上错过两次，而且方向相反 （<= / >= 和 < / > 各差一段 R，实测都是"只画不判" 35~37 个 y）。

⚠️ check_syntax.mjs 抓不到"调用了不存在的函数"。 我因为这个吃过大亏： 删掉 brainBusy() 之后页面报 ReferenceError，而语法检查一路绿灯。 凡是删函数的改动，都必须真的把页面跑起来（demo/verify_page.js 会抓异常）。

同样地，把物理搬到服务端时我两次把测试范围写错， 于是好代码被报成坏代码（一次扫了画面外的 y、一次扫了真实游戏生成不出的 top）。 校验器本身也要能被质疑。

曾经页面上只有 27 分而评测台 100+，差距定位为"浏览器喂不动脑"。 现在这个问题已经从根上解决：游戏仿真整体搬到服务端（server.py 的 GameWorld

• 一个固定 50 Hz 的锁步线程），前端只取状态、只渲染。

前端一共试过四种驱动方式，每一种都实测过，每一种都失败：

根因是结构性的：游戏时钟必须挂在某个节奏上，而浏览器里只有两个可选项， 页面内实测都不行：

setTimeout(4)            → 29.8 次/s   （被浏览器压到 ~33ms）
requestAnimationFrame    → 28.2 次/s   （后台还会被完全暂停）

再��上 HTTP 往返 中位 60ms / p90 86ms / 最快 4ms（差十几倍）—— 只要决策要靠一次跨进程往返拿到，时钟就一定是抖的。

脑与物理在同一个进程、同一个锁里按固定 50 Hz 跑严格 1:1（先按当前世界算驱动 → 走一个脑 tick → 用 DNp01 的发放决定拍不拍 → 走一步物理）， 没有任何网络或定时器节拍进入游戏时钟。前端只做两件事：按自己的帧率取状态、 在两次状态之间插值后画出来。

服务端的 GameWorld 与评测台的 World 必须逐 tick 等价，否则"分数"就没意义了。 scripts/verify_server_physics.py 用同一串拍翅命令对账两边的 位置/速度/分数/死亡时刻/死因/管道布局：

对账 60 局 × ≤3000 tick（其中 60 局死亡，覆盖了碰撞路径）
✅ 服务端 GameWorld 与评测台 World 逐 tick 等价

这个脚本当场抓到了一个真 bug：我最初把拍翅冷却塞在 GameWorld 里， 而评测台的 World.step(flap) 是无条件执行拍翅的（冷却由它的 harness 管）， 于是 vy 差了 23.6（评测台 -316.4、服务端 -292.8）。冷却门已移到调用方。

SpikingBrain.step() 的泊松噪声原来读全局 RNG（np.random.binomial / torch.randint / torch.rand）。后果是"同一个种子"根本保证不了可复现： 噪声序列取决于此前的代码消耗了多少随机数。

这不是理论担忧，是实测出来的。我在给"网页服务端 vs 离线评测台"做逐 tick 对账时 （scripts/verify_server_vs_bench.py）发现：两边用同一个种子、喂完全相同的驱动， 脑的行为却不一样 ——

DNp01 发放数：服务端 2 / 评测台 1
膜电位最大差：0.674

原因是两个进程初始化时消耗的随机数个数不同（服务端要建 3D 点云抽样、可点亮清单等）， 于是从第一 tick 起噪声就错开了。表现就是"同一套代码、同一个种子，却飞得完全不同"。

修复：每个脑持有自己的 rng / tgen，reset() / set_seed() 时按种子重置。 修完之后同样的对账：膜电位最大差 0.000000，逐 tick 完全一致。

噪声序列变了，所以 README 里历史测出的具体分数不再逐位可复现。 我留了一个 --legacy-noise 开关（把噪声切回全局 RNG）专门用来做这个对照：

读数要注意两点：

1. 噪声流本身值 ~12 分（标准误 4.2，所以这个差是显著的）。 也就是说这个修复确实把分数拉低了一截，不能假装没发生。
2. 但历史那个 100.8 在两条路径上都复现不了（43.65 也远不到 100.8）。 它是在更早的代码 + first_gap_extra=0 + 8000 tick、 且 35/40 局存活到上限的条件下产生的。我无法在现在的代码上复原它 —— 记录在这里，免得以后有人拿它对不上数、又不知道为什么。

消融三连在当前代码下重测（40 局 / 5000 tick）：

cut / shuffled 一次都不拍翅（0.0 次/局、方差 0），40 局全部死在第 1 根管子。 "分数必须穿过真实连接组"这个结论完好无损。

那个 1.00（而不是 0.00）来自一种结构性白送，不是脑在做事： 第 1 根管子的起点是 x = 120 + 0.75·240 − 62 = 118，而鸟在 x = 120 —— 鸟一出生就在第 1 根管子的缺口里；再加上开局 0.8s 的加速期不判碰撞， 而第 1 根管子移出鸟身只需要约 40 tick（= 0.8s）， 于是加速期一结束它就已经"过"了第 1 根。所以裸分是 1。

• dors_scale / vent_gain 是外部手写旋钮，不是连接组里的东西。 它们调节"感觉信号有多强"，作用在脑的输入端；连接组内部结构没有改过。
• 模型时钟 dt = 20 ms，而真实巨型纤维通路是 1.4–25 ms， 所以延迟类数字只能定性。
• LC4 的灵敏度 s50 是外部假设（文献里没找到 LC4 的实测发放率）， 它可调、会改变触发早晚，但不改变"有阈值、且由那 102 条边携带"这个结论。
• 预测/前瞻类尝试全部失败，已如实记为负结果（见上表）。
• scripts/flappy_page_parity.py 已删除。它当初继承了评测台的 World， 所以"比值 1.0"没有验证力（一个自己和自己比的校验器）。 这个坑值得记住，所以写在这里：校验器本身也要能被质疑 —— 它在仓库里存在了很久，一直报"通过"，却什么都没验。 它的职责现在由 scripts/verify_server_physics.py 承担（那一个是真对账）。
• 服务端仿真是单例：Session 是全局共享的一个，所以多个浏览器窗口会互相干扰 （看到同一个游戏）。演示够用，不适合对外公开（无鉴权）。
• 服务端占一个核：50 Hz 锁步线程会持续占用一个 CPU 核（约 500 MB 内存）。 闲置时也照跑，因为"随时打开页面都是活的"体验更好。

看 DEPLOY.md。一句话版 —— 仓库是自包含的：data/ 里三个文件 （spiking_full.npz 50 MB / spiking_full.json 226 KB / coords.npz 1.6 MB）已入库， three.js 也在 demo/vendor/ 里，所以：

pip install numpy pandas torch --index-url https://download.pytorch.org/whl/cpu
python demo/server.py --no-browser --port 8620

--asset 的默认值是 spiking_full，正常不用管它。 这个默认值原来是个静默失败陷阱：默认到 spiking_circuit（不含 LC4/LPLC2） 的后果是分数恒为 0、脑一次都不拍翅，而且不报任何错。 现在已经反过来 —— 传了不含关键群的资产会在启动时被直接拒绝， 并且说清是哪一种问题（群缺失 / 预烤坐标索引越界）。

本机实测：启动 4.7 s、内存约 500 MB、服务端仿真线程持续占一个 CPU 核 （固定 50 Hz 跑脑 + 物理）；回退到 < 5% 占用。

状态端点是 GET /api/game/state（前端每帧取，约 400 字节）； /api/step 仍然保留，用于「一次性推进 N 个 tick」的离线式调用， 但页面已经不再用它（页面走 /api/game/state）。

• 把仿真搬到服务端 —— 页面 < 评测台的唯一正解
• 页面主循环抗性不足：渲染慢时物理步进会被拖住（应改成物理与脑完全解耦）
• scripts/flappy_page_parity.py 需要重写 → 已删除，职责移交 scripts/verify_server_physics.py
• 前瞻 / 预测控制器尚未成功

暂无 LICENSE（默认保留所有权利）。