果蝇神经科学与游戏控制 —— 从生物脑到通用决策引擎
Drosophila neuroscience meets interactive control — from a biological brain to a general-purpose decision engine.
BRAIN_VERSION:
2.23.12· Skill Version:3.5.0· 166,700 LIF neurons · 151.9M synapses · MaleCNS v1.0
FruitflyAI 是一个将果蝇（Drosophila）真实生物神经连接组（MaleCNS v1.0）接入数字环境的开源研究项目。核心目标是验证：一个完整生物脑的神经计算能否在游戏控制、运动仿真、乃至商业场景中产生有意义的行为。
项目的独特之处在于：
- 🧠 真实连接组驱动：使用果蝇雄性中枢神经系统完整连接组数据，166,700 个 LIF 神经元、2560 万条突触连接，非人工神经网络简化
- 🔄 自治演化闭环：EVO 技能系统形成「监测→诊断→修复→验证→存档」的自我进化闭环，22+ 轮持续迭代
- 📊 完整的可解释性栈：从复眼采样到运动输出的六级控制级联全程可归因，Web 仪表板实时呈现因果链
- 🔌 环境抽象协议：统一的 VisionSource / MotorTarget 接口，同时支持 Super Mario 64 和 FlyGym v2 仿真
| 子项目 / Module | 说明 / Description |
|---|---|
Fly64 (fly64/) |
核心系统 — 果蝇脑控制 Super Mario 64，包含完整脑模型、视觉管道、空间记忆、运动解码、EVO 自我进化、LLM 教官层、Web 仪表板 |
FlyGym (scripts/launch_interactive_viewer.py) |
NeuroMechFly v2 果蝇身体运动仿真（MuJoCo），验证脑模型在六足机器人躯干上的行为迁移 |
Environments Protocol (fly64/environments/protocol.py) |
环境抽象层 — VisionSource / MotorTarget 协议将主循环与具体环境解耦，支持 SM64 / FlyGym 适配器无侵入切换 |
Skills (fly64/skills/) |
EVO 自我进化系统 + Pattern 目录 + 修复目录 + 教练顾问策略 |
Plugin (fly64/plugin/) |
MHR 教官层 — LLM 多模态咨询 + 自治常驻服务 + 看门狗 |
Web Dashboard (fly64/web/) |
实时神经活动监控面板 + 因果链可视化 + 空间记忆热力图 + 轨迹回放 |
Docs & Analysis (docs/, fly64/docs/) |
35+ 篇技术文档覆盖设计/实施/评审/路线图/跨领域分析 |
- 推荐方案: Windows 10/11 + WSL2 (Ubuntu 22.04)
- 备选方案: macOS (Apple Silicon) 或原生 Linux (Ubuntu 22.04+)
- 磁盘: 至少 5GB 可用空间
- 内存: 建议 8GB+
- SM64 ROM: 一份未修改的美版 Super Mario 64 ROM (
.z64)
# 1. 初始化 WSL 环境
wsl
sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential libsdl2-dev libglew-dev pkg-config \
python3 python3-venv python3-pip curl git make
# 2. 克隆并进入项目
git clone https://github.com/rickqi/FruitflyAI.git
cd FruitflyAI/fly64
# 3. 设置 Python 环境
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
# 4. 下载脑数据 (~1.3GB)
python -m fly64.data --prepare --cache .cache/malecns
# 5. 设置 sm64ex 并编译
git clone https://github.com/sm64pc/sm64ex.git .cache/sm64ex
cd .cache/sm64ex
git checkout d7ca2c04364a6dd0dac58b47151e04e26887e6f0
git apply ../../patches/sm64ex-fly64.patch
# 将 SM64 ROM 放入该目录
make -j$(nproc) VERSION=us BETTERCAMERA=1 NODRAWINGDISTANCE=1 EXT_OPTIONS_MENU=1
# 6. 使用 tmux 守护启动器（推荐）
cd ../..
bash scripts/wsl_launcher.sh --rom /path/to/baserom.us.z64启动后浏览器访问 http://127.0.0.1:8765/ 查看实时仪表板。
完整设置指南见
fly64/README.md和WSL 部署指南。
┌──────────────┐ ┌──────────────────┐ ┌──────────────────────────────┐
│ 环境层 │───▶│ VisionSource │───▶│ Fly64 脑模型 │
│ SM64 / │◀───│ MotorTarget │◀───│ 166,700 神经元 / 151.9M 突触 │
│ FlyGym │ │ 协议桥 │ │ LIF 网络 + CX + 蘑菇体 │
└──────────────┘ └──────────────────┘ └──────────────────────────────┘
│ ▲ │
│ 渲染六面体贴图 │ 读取游戏帧 │ 计算控制信号
▼ │ ▼
┌───────────────────────────────────────────────────────────────────────────┐
│ Web Dashboard (http://127.0.0.1:8765) + WS 8766 (F643 packet) │
│ • 复眼视图 (270° + 16扇区叠加) • 神经活动图表 • 全脑热力图 │
│ • 决策解释卡 (decision_source 归因) • 四泳道因果时间轴 (120s) │
│ • 空间记忆/轨迹回放 • Escape 事件表 • 覆盖度与健康评分 │
│ • Coach 面板 (教官建议) • EVO/Brain 版本胶囊 │
└───────────────────────────────────────────────────────────────────────────┘
▲ ▲
│ 只读遥测 (JSON) │ 状态/建议
┌──────┴───────────────────┐ ┌─────────┴──────────────────────┐
│ EvolutionSkill v3.5.0 │ │ MHR 教官层插件 (10s 周期) │
│ Monitor→Diagnose→Fix→ │ │ runner → check_help_needed → │
│ Verify→Document │ │ LLM 多模态咨询 → │
│ 16 patterns · fix_catalog │ │ active_strategy.json (热加载) │
│ 常驻循环 (auto-fix) │ │ + coach_advice.json (展示) │
└──────────────────────────┘ └────────────────────────────────┘
▲ ▲
└──────── scripts/consolidate.sh（制度化重启，含自治服务）──────────┘
系统性治理 Fly64 基础设施瓶颈与契约缺陷：
| # | 交付 | 关键成果 |
|---|---|---|
| 1 | FixExecutor 模板覆盖 | 自然语言修复模板 → LLM 辅助结构化解释器，8 个降级 pattern 全部可自动执行 |
| 2 | 写入锁与竞态防护 | fcntl.flock() 进程级写入锁 + Git 式冲突检测，杜绝双 EVO 实例数据竞争 |
| 3 | 历史记录旋转归档 | EvolutionHistory 超阈值自动旋转 + 增量 README 更新，24h+ 运行零退化 |
| 4 | 契约审计与死旋钮清理 | audit_contract_pairs.py AST 级写入/读取点分析，清理 12+ 条死JSON 键，验证全部 brain_tunable_params.json 可消耗 |
| 5 | 回归基线可探测 | known_failures.json 36 条基线 + check_regressions.py 回归探测，回归不再淹没于噪声 |
大规模脑模型能力扩展：
| # | 交付 | 关键成果 |
|---|---|---|
| 1 | R22 Motor Expansion P1 | Z 触发解锁 + 拳击/俯冲/砸地/长跳/后空翻/爬行物理通路 |
| 2 | R23 Motor Expansion P2 | VNC 式 CPG 运动原语层 + pose 状态机 + 2s 超时熔断 |
| 3 | R24 Motor Expansion P3 | strike/crouch 双 20 神经元解码池 + MBON 5→9 列扩展 |
| 4 | R24 Motor Expansion P4/5 | 监控可视化 + EVO pattern 收编 + 惰性种子修复 |
| 5 | R29 视觉修复 | CCL 8 连通性修复，小目标检测 stride-2 采样恢复正常 |
| 6 | R31-fix2 截屏保真修复 | 帧捕获从观察者通道尾部 → end_frame 完成点，保真度回归套件 |
| 7 | R31-fix3 熔岩地修复 | 掉血检测 + 受击格写入失败记忆 + 覆盖度进展门控位移奖励 |
| 8 | R31-fix4 Fall 判定 | 垂直速度环形缓冲 + 三态模型，消除高处误判 |
| 9 | R31-fix5 micro_loop 相位 | 交替纯旋转 → 之字形推进，产生实际位移 |
| 10 | R31-fix6 stuck_duration 治理 | 异常分类器增加 disp_60s 门控，有进展不再被 stuck 锁定 |
三项并行深度分析，系统性识别剩余瓶颈：
| # | 分析域 | 关键发现 | 文档 |
|---|---|---|---|
| 1 | P0-A: EVO auto-fix 常驻运行 | 8 项阻塞级问题（66.7% pattern 降级、竞态条件、行号漂移、无界历史记录、日志爆满等） | next_challenge_analysis_report.md |
| 2 | P0-B: FlyGym 端到端集成 | 视觉适配器压缩比 691,200:1 → 完全失能，缺少 VisionSource 抽象层，8 项集成测试缺口 | 同上 |
| 3 | P1-A: 视觉覆盖度提升 | 颜色/UV ≈95% 已完成可直接启用，小目标追踪 ≈80% 需验证修复，多巴胺学习 ≈85% 需修复阻塞性缺陷 | 同上 |
即将交付的 P0/P1 实施项：
| # | 项 | 预估工作量 | 状态 |
|---|---|---|---|
| 1 | P0-A1: LLM 辅助 FixTemplateInterpreter | 1-2 天 | 待开始 |
| 2 | P0-A2: 写入锁 + Git 式冲突检测 | 0.5 天 | 设计中 |
| 3 | P0-B1: VisionSource 抽象层 + SM64 适配器 | 3-4 天 | 待开始 |
| 4 | P0-B2: FlyGym 适配器（空间降采样视觉） | 3-4 天 | 待开始 |
| 5 | P1-A: 颜色/UV 通道验证与启用 | 1 天 | 待开始 |
| 6 | P1: 小目标追踪行为验证 + 多巴胺学习全栈测试 | 5-8 天 | 待开始 |
| 指标 | 数值 |
|---|---|
| BRAIN_VERSION | 2.23.12 |
| Skill Version | 3.5.0 |
| 测试套件 | 1,278 项 (pytest --collect-only) |
| 测试文件 | 92 个 (tests/test_*.py) |
| 核心模块行数 | main.py ~2,280 · model.py ~1,538 · memory.py ~1,610 · retina.py ~1,269 |
| EVO 进化轮次 | 80 条权威记录（R1–R31 + 运维 + t 系列 + EVO-072） |
| Pattern 目录 | 16 条可检测 pattern |
| 文档数量 | 35+ 篇技术文档（设计/实施/评审/路线图/跨领域） |
| FlyGym 版本 | v1.2.1（与 SM64 双后端就绪） |
| 运行平台 | Windows 10/11 + WSL2（主推）· macOS Apple Silicon · Linux x86_64 |
| 自治服务 | MHR 插件 10s 闭环 · 看门狗自动重启 · consolidate.sh 制度化重启 |
| 类别 | 主要测试文件 | 覆盖范围 |
|---|---|---|
| 神经模型 | test_model.py, test_retina.py, test_mushroom_body.py, test_gain_modulation.py, test_brain_alternation.py, test_mbon_saturation.py, test_dan_shaping.py |
LIF 动力学、复眼采样、蘑菇体可塑、增益调制、转向交替、饱和守卫 |
| 记忆与感知 | test_memory.py, test_optic_flow.py, test_cliff_standoff.py |
空间网格/反射/光流/悬崖对峙 |
| 桥接与仪表板 | test_bridge.py, test_dashboard_protocol.py, test_dashboard_js.py |
mmap 协议、WS packet 字段契约、前端渲染 |
| EVO 与自治 | test_evolution_capability.py, test_service.py, test_autonomy_regression.py, test_plugin_mhr.py |
Pattern 判定、修复记录、服务心跳、看门狗、原子写出 |
| 神经接管 PIN | test_p1_neural_takeover.py, test_spin_loop_fix.py |
Python 旁路回归（11 处 A 类旁路必须保持删除） |
| 环境协议 | test_environment_protocol.py, test_flygym_adapter.py |
VisionSource / MotorTarget 适配器 + FlyGym 集成（20 项） |
| 在线检查 | check_live_version.py, check_bridge_mismatch.sh, ws_probe.py, evo_status_report.py |
运行中实例的版本/桥接/遥测/EVO 状态抽查 |
- 🔴 EVO auto-fix 常驻运行：实现 LLM 辅助修复模板解释器 + 写入锁 + Git 式冲突检测 + 历史记录旋转归档 + 迭代级健康看门狗（预估 3-5 天）
- 🔴 FlyGym 端到端集成：VisionSource/MotorTarget 抽象层 → SM64 适配器 → FlyGym 适配器（空间降采样视觉）→ 8 项集成测试（预估 8-11 天）
- 🟡 颜色/UV 通道启用：验证
encode_color()管道，默认启用color_signature=True，场景签名兼容性测试 - 🟡 小目标追踪行为验证：修复验证后启用 LIF 分裂注入通路
- 🟡 多巴胺学习全栈测试：修复 MBON 饱和 + 阈值错误后启用全栈测试
- 🟡 备份目录隔离：
.bak写入单独.evo_backups/目录，统一清理策略
- 🟢 本能固化晋级量化：P4.4 场景→策略本能绑定，度量工具化
- 🟢 课程三态判定扩展：不可观测 ≠ 失败，三态判定已实现，等待端到端验证
- 🟢 动作熵与抖动检测：防止反射相位的无效旋转抖动积累
- 🟢 回归检测自动化：
check_regressions.py集成到 CI 管道 - 🟢 24h+ 长时间运行压力测试：历史记录旋转、看门狗自动暂停、写放大治理
| 文档 | 说明 |
|---|---|
fly64/README.md |
Fly64 完整技术文档 — 安装/架构/进化历史/全部参数 |
docs/analysis/next_challenge_analysis_report.md |
P0/P1 挑战根因分析与综合路线图 |
docs/analysis/session_logs_analysis_report.md |
11 个 Session 对话日志全面分析报告 |
docs/analysis/t6_final_comprehensive_report.md |
跨领域能力最终综合报告 |
| 文档 | 主题 |
|---|---|
causal-chain-ui-design.md, causal-chain-implementation.md, causal-chain-final-review-t8.md |
因果链设计/实施/终审全套 |
layout-optimization.md, layout-audit-t5.md |
仪表板布局优化与逐区审核 |
color_uv_vision_design.md, emd_4direction_design.md, small_target_tracking_design.md, dopamine_mushroom_body_design.md |
P1a/P1b/P2/P3 视觉与学习能力设计 |
implementation_roadmap.md, visual-enhancement-plan.md |
能力增强规划与路线图 |
what_i_see_protocol.md |
教官层视觉协议定义 |
evolution-coach-roadmap.md |
EVO 进化 + Coach 教官双系统路线图 |
wsl-setup-guide.md, wsl-launcher-deployment.md |
WSL 部署与守护启动器 |
thin-plugin-design-analysis.md, lif_injection_feasibility_report.md |
薄插件设计与 LIF 注入可行性论证 |
| 文档 | 主题 |
|---|---|
bridge-bz-unlock.md |
桥接 Z 触发解锁设计 |
cpg-motor-primitives.md |
CPG 运动原语层架构 |
neural-pools-extension.md |
神经池扩展方案 |
dashboard-impact-assessment.md |
仪表板影响评估 |
execution-plan.md |
执行计划与阶段划分 |
next-optimization-plan.md |
下一优化步骤 |
mbon-learning-evaluation.md |
MBON 学习评估 |
cd fly64
python -m pytest -q # 全量套件 (1,221 项)
python -m pytest tests/test_invariants.py -q # 不变量（连接组/LIF 数值契约）
python -m pytest tests/test_evolution_capability.py -q # EVO 能力回归
python -m pytest tests/test_service.py tests/test_autonomy_regression.py -q # 自治服务与看门狗
python -m pytest tests/test_environment_protocol.py tests/test_flygym_adapter.py -q # 环境协议本项目以开放科学精神进行果蝇全脑连接组计算神经科学研究。欢迎：
- 🐛 报告行为瓶颈与异常 pattern
- 🧪 贡献测试用例与回归基线
- 📝 改进文档与可视化
- 🧠 提出新的神经计算假设
许可: 见仓库根目录 LICENSE 文件。
FruitflyAI — 从果蝇的 166K 神经元到通用决策智能。
From 166K fruitfly neurons toward general-purpose decision intelligence.