flybrain-connectome

flybrain-connectome

v3.00.3 · 2026-10-25 · 116 个功能单元 · 270 个模块配置 · 62 个门禁 · EPE 全栈 + AIBOM 供应链披露 + 收据完整性门禁 + Gate 60/61/62/63/64 + fail-loud 纪律 + 版本单一真源 + Xu 2026 树突计算前沿对照 + Xu 2026 双层认知计算参考实现（tools/dendritic_rule_engine.py + examples/07_dendritic_rule_cache_demo.ipynb）+ E4 区室边界 + S1 外部验证 + S2 lesion cascade + S3 统计强化 + 纪律有效性量化（catch-rate 100%，W1–W7 全部关闭）+ Gate 63 research_claims 顶层统计完整性 + 作者署名规范化（P-3 / P-4 → Li Xing + ORCID）+ bioRxiv 投稿准备包 + flybrain 演示一键运行 + 5 分钟上手 + flybrain audit CLI + JOSS 投稿包 + MCP 生态提交包 + 补齐 9 篇论文 DOI

89% 的难题

Deloitte 2026 年 Agent 试点调查发现，89% 的企业 Agent 试点 从未投入生产。Teradata 的数据显示：78% 有试点，只有 14% 实现规模化。 各行业反复出现的失败模式可以用三个词概括：

“跑不稳、管不住、查不清” — 不稳定、不可治理、不可审计。

flybrain-connectome 针对的是第三个问题。生成拓扑中的每条 Agent 边都能 追溯到 Drosophila 雄性大脑连接组中的真实神经元或突触类别，并序列化为 W3C PROV-JSON — 欧盟《人工智能法案》审计人员所期望的同一格式。 你的 Agent 群体并非黑箱，而是具有生物学溯源依据、可验证的结构。

5 分钟快速上手 — 无需下载数据，五分钟内 从零开始生成交互式 D3 拓扑图。

可审计的 Agent 拓扑 — 可审计的 Agent 拓扑生成与溯源，以真实的 Drosophila 雄性大脑连接组为基础（MaleCNS v1.0 — 166,700 个 神经元 / 124,177,617 个突触，CC-BY）。

flybrain-connectome 将真实公开的大脑连接图转化为面向特定任务的多 Agent 拓扑， 可据此实例化 Agent 群体；它还能证明每条边来自哪种真实神经元 / 突触类别。 基序溯源信息序列化为W3C PROV-JSON，即欧盟《人工智能法案》审计人员所期望的标准。

5 个模块 × 8 个 Agent 的拓扑（predictive_coding_v2 蓝图）——与你通过 flybrain demo 生成的图相同。在线试用 →

这是一个开发者工具包和研究成果，不是训练好的模型，也不是苍蝇的模拟。 引用前请先阅读适用边界说明。

仓库状态： 自 2026-10-18 起公开。公开前已审核并清理历史记录 （原始 Tier-2 知识产权泄露说明见 CHANGELOG v1.3.0，已执行的 16 步公开操作手册见 docs/D3_REPOSITORY_PUBLICITY_DECISION_2026-10-18.md）。 Tier-1 代码采用 MIT 许可证，可通过 https://github.com/lm203688/flybrain-connectome 访问。 Tier-2 原始数据（MaleCNS 5.63 GB、C. elegans Witvliet 2020、Drosophila larva edges.csv、Petkova 2025 zebrafish）通过文档所述的数据流水线获取 — 参见“Requirements”章节和 S1 外部验证脚本。

---

它是什么 / 它不是什么

✅ 本项目	❌ 本项目不是什么
一项连接组查询服务（通过 HTTP + MCP 提供 47 个工具）	脉冲神经元模拟器
一条基序提取流水线（真实果蝇 → 派生基序文档）	原始 5.63 GB 数据的存储库
一个合成拓扑生成器（生物基序 → Agent 图）	带有权重的已训练 / 微调模型
每个生成产物都有 W3C PROV 来源信息	声称“虚拟生物体”是活着的

最出色的离线功能：generate 无需数据——它根据 7 KB 的派生基序快照组合拓扑。只有在想要查询真实大脑时，才需要连接组数据。

---

如实说明单元库的现状

116 个功能单元按其证据的来源方式明确分为两类。阅读任何下游声明时，都应牢记这个数字：

类别	数量	含义
锚定到真实 Drosophila 雄性脑细胞	37 / 116 (31.9 %)	embodiment.real_cells_anchored > 0 — 每条边都可追溯到 MaleCNS v1.0 中的真实神经元
跨物种声明，未锚定	79 / 116 (68.1 %)	provenance.unanchored_reason = identity_not_in_drosophila 或 taxon_no_malecns_data — 文献中有其他物种的相关回路，但 MaleCNS 连接组中没有

68.1 % 这一类并非缺陷，也不是隐藏错误。它是一个比较神经科学框架：鸟类鸣唱、哺乳动物皮层层、鱼类 Mauthner 细胞、头足类垂直叶、海兔和水蛭的 CPG、昆虫蘑菇体——这些回路都已通过具名参考资料接入库中，可以像锚定单元一样进行组合，但它们不像那 37 个锚定单元那样，是在真实连接组中测量得出的。正确理解这个库，意味着要结合这两个数字来看，而不能只看 116。

如何使用——按你今天实际能获得的功能分级

与其笼统地宣称“这是一个 X”，不如将本项目的实用功能分为三个级别。你实际需要哪一级，取决于你正在构建什么。

第 1 级——今天即可使用，无需联网，也无需下载数据。 在 3 个物种 × 4 个维度（system / function / species / provenance）上搜索神经元回路；从任意子集的单元组合虚拟生物体拓扑；端到端运行四个经典 DEMO（哺乳动物、昆虫、电感受、游泳）。这就是本项目实际提供的开发者工具。flybrain search、flybrain compose、flybrain generate 涵盖了这些功能。

第 2 级——适用于设计 AI Agent 框架的人员。 组合后的拓扑可通过 W3C PROV-JSON 追溯至真实回路，这意味着下游 Agent 框架（LangGraph / CrewAI / AutoGen / SwarmLabs）可以采用一个起始拓扑，并审计每项连接决策的来源。这不是通用 Agent 基础设施——它是可接入通用 Agent 基础设施的生物学先验层。

第 3 级——本项目明确不提供的功能。 本项目在任何方面都无法超越生物学（第 3 阶段的测量结果为负面，也不会声称做到了）。它不会取代任何电子显微镜重建流水线。它不提供已训练模型或脉冲模拟器。如果有人看到 v1.x 更新日志条目，声称具备上述任何功能，诚实的回答是“那只是期望；相关撤回记录在 docs/PROJECT_REALITY_ASSESSMENT.md 中”。

---

四大护城河（实测，而非营销话术）

我们进行了实验。在受控测试中，两项“显而易见”的优势被证实为不成立，我们也如实说明。

#	护城河	证据	状态
1	可追溯性 — 每条生成的边都可追溯到真实的神经元／突触类别，并序列化为 W3C PROV-JSON	_verify.py 70/70；顶层字段 prov_json（架构 v1.2.1）	✅ 成立
2	结构简约性 — 遗传搜索找到的图远比生物学先验精简	GA 收敛到 9–11 条边，而锁定结构为 57 条 → 线缆成本降低 84%	✅ 成立
3	结构稳定性 — 模块级故障隔离	25 / 27 个采样拓扑呈现模块化 H1 隔离（92.6%）；谱半径 ρ 保持在 0.00–0.30%	✅ 成立
4	本地决策 — 各模块读取自己的答案	多读出实验中 5 / 28 个为 H1（17.9%），仅限简单任务／延迟≤2 的任务	⚠️ 部分成立

我们明确不作出的主张

维度	结果	放弃该主张的原因
原始计算优势	0 / 7 种拓扑优于随机结构	匹配对照 ESN 校准；motif 优势为 0/7，差异在噪声范围内
能耗优势	0 / 24 次运行优于随机结构	SNN 能耗代理指标；中位数比值为 1.006（±5%），没有系统性提升

诚实也是一种特性。可复现实验脚本位于 integrations/swarmlabs/diagnostics/，报告位于仓库根目录 （SNN_ENERGY_REPORT.md、MULTI_READOUT_REPORT.md、FAULT_ISOLATION_REPORT.md）。

---

安装

该工具包需要一个运行时依赖（numpy，因为 connectome 引擎在模块级导入它），另有用于溯源和列式 IO 的可选扩展。不需要其他第三方代码。任选以下一种配置：

仓库状态： 自 2026-10-18 起为公开。无需身份验证 — 以下克隆命令可直接使用。公开前已审查并清理历史记录 （关于最初的 Tier-2 IP 泄漏，请参阅 CHANGELOG v1.3.0；关于 16 步公开流程，请参阅 docs/D3_REPOSITORY_PUBLICITY_DECISION_2026-10-18.md）。

A. 克隆并运行（推荐，已完成端到端验证）

git clone https://github.com/lm203688/flybrain-connectome.git
cd flybrain-connectome
python flybrain_cli.py --help

B. 可编辑安装（将 flybrain 加入 PATH）

git clone https://github.com/lm203688/flybrain-connectome.git
cd flybrain-connectome
pip install -e .
flybrain info

pip install -e . 是可编辑安装：flybrain 入口会映射回检出目录，因此能找到工具包。普通的 pip install . 只会安装启动器，因此需要显式指定检出目录：

pip install .
export FLYBRAIN_HOME=/path/to/flybrain-connectome
flybrain info

此安装方式已通过 CI 验证，不只是写在文档里。 .github/workflows/ci.yml 中的 package 任务会运行 pip install ".[prov]"，调用控制台脚本，通过 FLYBRAIN_HOME 定位工具包，生成一个生物体，并断言产物的不变条件 —— 因此安装说明不会在无人察觉的情况下失效。

C. 可选：标准化溯源包

结构溯源信息（motif_provenance，含快照 sha256）始终会被记录。标准化 W3C PROV-JSON 包（prov_json）由可选的 dataprov 包序列化：

pip install dataprov                     # or: pip install "flybrain-connectome[prov]" (once on PyPI)

即使没有该包，工具包仍可运行：prov_json 会变为 null，而 get_provenance_bundle 会返回 prov_available: false 及原因， 而不是崩溃。scripts/check_degraded_mode.py 会断言这两种情况——缺少时必须降级，存在时必须实际生成该数据包。

始终检查实际获取的内容

flybrain info

此命令会报告已解析的工具包根目录、motif 快照、数据目录、API 密钥状态，以及公开了多少个工具。出现异常时请先运行它——它能将“ImportError”转化为明确且可修复的问题。

查询真实连接组还需要数据

MaleCNS v1.0 采用 CC-BY 许可，大小约为 5.63 GB，并且有意不包含在此仓库中：

export FLYBRAIN_DATA_DIR=/path/to/your/male_cns

generate 和捆绑的 motif 快照完全不需要数据。

---

快速入门

下方每个 flybrain <cmd> 命令也可以写作 python flybrain_cli.py <cmd> （配置 A），因此无需安装任何内容即可试用此项目。

0. 检查安装是否正常

flybrain info
# -> toolkit root [ok] · motif snapshot [ok, 7363 bytes] · tools exposed: 36

1. 提供连接组服务（可选——仅在查询真实数据时需要）

flybrain serve --port 8799
# or: python flybrain-connectome-mcp/run_api.py

2. 查询真实大脑

export FLYBRAIN_API_KEY=<your-key>   # set in config.json or env

flybrain query pair_synapses --args '{"pre":10540,"post":12569}'
# -> 711   (the real APL → DPM connection)

flybrain query connectome_overview
# -> {"total_synapses": 124177617, "annotated_neurons": 211577, ...}

3. 获取衍生的基序文档

flybrain motifs --out motifs.json      # live pull from the service
# offline snapshot (no server, no data): flybrain-connectome-mcp/motifs/swarm_agent_topology_motifs.json

4. 生成合成生物拓扑（离线，无需数据）

flybrain generate --blueprint predictive_coding_v2 --modules 5 --agents-per-module 8
# -> flybrain-connectome-mcp/generated_organisms/<name>.{json,html} + flybrain-connectome-mcp/swarmlabs/<name>.swarm.{json,yaml}

5. 读取秀丽隐杆线虫的发育轴

flybrain stages         # L1 x4 / L2 / L3 / adult x2, measured per animal
flybrain stages --caveat            # why the L1 columns are a floor
flybrain stages --unit cel_amphid_chemosensory_unit

6. 读取幼虫连接组集群账本

flybrain larva-clusters             # network totals + per-unit coverage
flybrain larva-clusters --top 20    # the 20 biggest clusters
flybrain larva-clusters --unannotated
flybrain larva-clusters --caveat    # what "covered" does and does not mean

7. 读取 MaleCNS 雄性二态性账本

flybrain composition               # can declared combinations actually form?
flybrain costs                      # latency/energy per connection type
flybrain function                   # coverage by FUNCTION, not by species
flybrain function --vision          # only what PROJECT_VISION requires
flybrain dimorphism                 # 2,368 cells nobody has looked at
flybrain dimorphism --provenance    # ... with the curator note behind each sex label
flybrain dimorphism --top 20 --internal
flybrain dimorphism --caveat        # what "male-specific" does not mean here

8. 验证所有功能仍可正常运行

flybrain verify        # needs FLYBRAIN_DATA_DIR set to your data

9. 分析拓扑（离线，无需数据）

拓扑感知层将“这种生物是什么形态？”转化为可调用、可复现的答案——密度、度分布、互惠性、模块度 Q、传递性、谱半径（幂迭代，无需 numpy）、反馈边比例、有向 3 节点基序普查，以及确定性结构签名。它从设计上就保持诚实：not_measured 会标明结构分析无法说明的内容（动力学、能量、任务表现）。

flybrain generate --blueprint predictive_coding_v2 --modules 5 --agents-per-module 6 --name demo
flybrain profile generated_organisms/demo.json
flybrain profile generated_organisms/demo.json --json          # full profile
flybrain profile generated_organisms/demo.json --compare generated_organisms/other.json

由 Gate 15（scripts/check_topology_profile.py）自行验证。

---

仓库布局

flybrain-connectome/
├── flybrain_cli.py                 ★ developer CLI (serve/query/motifs/generate/verify/info)
├── pyproject.toml                  zero deps, `flybrain` console script
├── LICENSE · CITATION.cff · CHANGELOG.md
├── flybrain-connectome-mcp/
│   ├── mcp_connectome/             query engine (core) + 47-tool MCP + HTTP API (:8799)
│   ├── motifs/                     drop-in client + derived motif snapshot
│   ├── synthetic_bio_topology.py   ★ C1 generator (motif → agent graph + config + PROV)
│   ├── _verify.py                  end-to-end smoke test (70/70)
│   └── flybrain-connectome-mcp/
│       ├── generated_organisms/     example artifacts (json/html + swarm configs)
│       └── swarmlabs/               swarm config exports
├── integrations/swarmlabs/         consistency checkers + diagnostics (reproducible experiments)
├── scripts/                        run_gates.py · check_no_secrets.py · check_docs_consistency.py
│                                   check_mcp_tools.py · check_degraded_mode.py
│                                   check_generated_artifact.py · gh_publish.py
├── .github/workflows/ci.yml        the same gates, on py3.10/3.12/3.13 + packaged-CLI job
└── docs/                           arxiv_paper.md · mcp_setup.md · module_factory.md

---

HTTP API 参考

服务：flybrain-connectome-mcp/mcp_connectome/api_server.py。

端点	身份验证	用途
GET /health	无	存活状态 + 版本
GET /tools	密钥	列出 47 个工具及其描述
POST /query	密钥	{"tool": <name>, "args": {...}} → {"ok": true, "result": ...}

身份验证： 使用 Authorization: Bearer <key> 或 X-API-Key: <key>。密钥来自 config.json（api_keys）或环境变量 FLYBRAIN_API_KEY。如果未配置密钥，服务端会生成一个每次启动时临时使用的密钥，并发出醒目警告——绝不会回退到提交在源代码中的密钥。

47 个工具（使用真实名称，不要自行编造——已通过 scripts/check_docs_consistency.py 对照 GET /tools 验证）：

真实连接组查询——标记为 ⚠ 的 11 个工具需要 FLYBRAIN_DATA_DIR：

connectome_overview ⚠ · neuron_info ⚠ · pair_synapses ⚠ · neuron_outputs ⚠ · neuron_inputs ⚠ · degree ⚠ · search_neurons ⚠ · superclass_projection ⚠ · hub_targets ⚠ · list_superclasses ⚠ · pathway ⚠ · export_swarm_motifs

生成器功能——支持离线运行，数据来自基序快照：

list_blueprints · list_modules · list_bio_motifs · batch_generate_topologies · get_provenance_bundle · list_stacked_blueprints · get_stacked_feasibility · list_neuropils · get_neuropil_detail · get_module · check_module_compatibility · compose_virtual_organism · list_virtual_organisms · list_presets · get_preset · apply_preset · organism_to_swarmlabs · get_module_agent_roles · save_market_organism · load_market_organism · list_market_organisms · rate_market_organism · search_market_organisms · delete_market_organism · list_combination_rules · validate_combination · expand_organism · get_multiplier_metrics · profile_topology · profile_health

功能单元组合库——位于神经元类型之上的可组合层：

list_functional_units · get_functional_unit · list_connection_types · list_evidence_ledger · compose_from_units

---

合成生物 schema

synthetic_bio_topology.design_organism(spec) 返回：

{
  "organism": {
    "nodes": [ {"id": "m0_rep", "role": "tissue_rep", "module": 0,
                "profile": "memory", "ref_superclass": "CB", ...} ],
    "edges": [ {"from": "m0_rep", "to": "m0_c0", "weight": -0.31,
                "kind": "inhibitory", "module": 0, "ref_body": 10540} ]
  },
  "metrics": {
    "n_nodes": 29, "n_edges": 18, "avg_degree": 1.24,
    "inhibition_ratio": 0.11, "n_modules": 4,
    "intra_module_edges": 14, "inter_module_edges": 4,
    "modularity_est": 0.778, "profile_breakdown": { ... }
  },
  "blueprint": "predictive_coding_v2",
  "motif_provenance": {            // 3-stage traceability
    "mode": "local_snapshot",
    "motif_synapse_stats": { ... },     // % of the 124M-synapse dataset
    "motif_query": "SELECT ...",        // runnable provenance query
    "blueprint_to_motif": { ... }
  },
  "prov_json": { ... }             // W3C PROV-JSON bundle (schema v1.2.1)
}

W3C PROV-JSON（prov_json）包记录了 entity / activity / agent 节点，以及 wasDerivedFrom / wasAssociatedWith / wasAttributedTo 边，并将每个拓扑归因于 FlyCellAtlas 和 flybrain:dataset_anchor（MaleCNS v1.0）。它可供 yProv4ML、 MLflow2PROV 和 MIT Sloan 来源追踪工具使用。

---

蓝图与模块库

25 个蓝图，分为三个类别，由 270 个模块组成： 10 个认知功能模块（感知 / 记忆 / 运动 / 整合 / 注意 / 工作记忆 / 奖励 / 惩罚 / 习惯 / 元认知）+ 190 种跨物种神经元类型，涵盖皮层锥体细胞（L2/3 CX1/CX5、L4b/L4c、L5 basal tuft、L6 reticulo-thalamic、L7 temporal、Mayeret）+ 中间神经元（Calbindin/LAMP/NPH/NPF/VLAC/SST-dendritic/SST-somatic/KCN，以及 PV/SST/VIP/chandelier/basket）+ 调制系统（多巴胺能 A9/A11/VMC/VTA/SNC、血清素能 dorsal/ventral/median raphe、去甲肾上腺素能 LC、胆碱能 MT/horizontal、组胺能 TM、orexin）+ 视网膜（视锥/视杆双极细胞、无长突细胞 ACL1/ACL2、midget/PV 神经节细胞、水平细胞）+ 脊髓/小脑（α/γ 运动神经元、Icc/Ih/Ihp 中间神经元、甘氨酸能、伤害感受、Purkinje/granule/stellate、下橄榄核）+ 丘脑/基底神经节（LGN/MD/VA/VL/VPL/VPM/RTN、STN、红核、纹状体 D1/D2 MSN）+ 边缘系统/边缘区域（海马 CA1/CA2/CA3/CA4/颗粒细胞/下托、杏仁核 BLA/LA、隔区、内嗅皮层 L2/L3、网格细胞）+ 特殊感觉（松果体、黑视蛋白、嗅觉、前庭、耳蜗外毛细胞）+ 反应性星形胶质细胞

• 四个其神经元在脊椎动物皮层中没有对应类型的演化支（另有 35 种类型，每种都有自己的 biological_reference）：

• 昆虫（14） — Kenyon 细胞 / 蘑菇体输出神经元 / PPL1-PAM 多巴胺能神经元 / APL、触角叶投射神经元和局部神经元、前脑桥 / 椭圆体 / 扇形体 / 结节 / 环形神经元、s-LNv 和侧部时钟神经元、下行神经元
• 鸟类（6） — HVC、RA、LMAN、Area X、DLM、NIf（鸣唱系统）
• 鱼类（8） — Mauthner 细胞、网状脊髓神经元、侧线毛细胞、壶腹和结节状电感受器、ELL 锥体细胞、电感受抑制性中间神经元、电器官起搏神经元
• 头足类（7） — 垂直叶大型 / 无长突 / 小型细胞、上额叶细胞、色素胞运动神经元、腕运动神经元、腕感觉传入神经元

• 第二批非皮层类型：节律、状态与误差（另有 24 种类型，v1.6.0）：

• 节段性 / 外周振荡器（9） — 水蛭游泳 CPG 中间神经元和体壁运动神经元及其机械感受 T 细胞、海鞘幼体运动神经元和眼点光感受器、海兔感觉 / 运动 / 血清素能促进神经元、口球神经节 CPG 神经元
• 红外与两栖类（5） — 三叉神经红外传入神经元、红外顶盖图谱神经元、多模态视顶盖神经元、顶盖 T5 型猎物探测神经元、舌运动神经元
• 误差教学与状态（6） — 爬行纤维、小脑高尔基细胞、前庭核神经元、前 Bötzinger 复合体神经元、膈神经运动神经元、VLPO 神经元
• 导航与主动感知（4） — 头方向细胞、位置细胞、桶状皮层神经元、胡须运动神经元

每个蓝图都对应 40 种拓扑模式之一（3 种从 MaleCNS 提取的原创模式 + 37 种概念模式，涵盖解剖 / 功能 / 可塑性 / 特化类别），或如实标记为 motif: none（合成编排，无生物学先验）——16 种有生物学先验，9 种没有：

• 5 种基础模式 — 平坦 / 枢纽 / 环形 / 分层 / 随机参考拓扑
• 16 种生物学模式 — 例如 predictive_coding_v2（recurrent_feedback+reward）、metacognitive_control（inhibitory_hub）、habit_consolidation（recurrent_feedback）、hierarchical_deep（reservoir_smallworld）……
• 4 种合成模式 — rl_actor_critic、curiosity_driven、cognitive_control、multi_motif_blend（如实标记为 motif: none）

嵌套组合 a+(b+c) 会被解析为与 a+b+c 同构。完整列表：

from flybrain_connectome_mcp.synthetic_bio_topology import BLUEPRINTS  # (in-repo path)
# or after pip install: import synthetic_bio_topology as c1; c1.BLUEPRINTS

机器可读的等效接口（相同数据，通过 HTTP/MCP 提供）：list_blueprints、list_modules、list_bio_motifs。

---

功能单元与连接类型库

上面的神经元列表是词汇表，而不是组合单位：单一神经元类型无法独立发挥作用，把两种类型连接起来也毫无意义。可组合的是具有已知接口的函数。因此，这个库分为两个层级，而上层才是你实际用来构建的：

• 116 个功能单元——每个单元都是一个函数（光转导、动作选择、θ 节律驱动、胶质传递、稀疏蘑菇体编码、环吸引子定向、鸣唱时序、Mauthner 逃逸、主动电定位、伪装、蚂蟥游泳节律、红外热成像、攀缘纤维误差教学、睡眠／清醒切换……），由一组神经元群（1–6 个，取自包含 254 个模块的词汇表）构成，并连接成内部子电路，同时暴露类型化端口（light 输入 → high_res 输出；candidates + value 输入 → selected_action 输出）。 组成：40 个哺乳动物皮层形态 + 16 个跨类群（昆虫／鸟类／鱼类／头足类，v1.4.1）+ 16 个节律／状态／误差与主动感知（环节动物、海鞘、软体动物、蝮蛇、蛙、小脑、脑干、海马、桶状皮层，v1.6.0）
  • 10 个果蝇形态（视叶、巨纤维逃逸、雄性求偶与鸣唱、外侧角，v1.8.0——全部都有完整锚定，见下文）。
  • 5 个果蝇形态（温度偏好、摄食电路、腿部运动、多模态 LAL、睡眠记忆，v1.10.0——首批已锚定，见下文）。
  • 4 个源自 C. elegans 连接组（前向运动指令、触碰回避反射、两栖化学感觉、伤害性感受回避——v2.27.0，见下文；每个也都带有 L1 → L2 → L3 → 成虫轴，v2.30.0）。
  • 8 个源自果蝇幼虫连接组（larv_olfactory_associative_learning_unit、larv_somatosensory_escape_unit、larv_gustatory_feeding_program_unit、larv_descending_motor_command_unit、larv_mushroom_body_feedback_unit——v2.28.0，第三个连接组——以及 larv_thermosensory_relay_unit、larv_visual_relay_unit、larv_respiratory_relay_unit——v2.29.0，每个追踪到的感觉通道各对应一个单元，见下文）。
• 66 种连接类型——每种代表一种连接形式，并限定其可连接的端口类型，分为六类： 微观（轴突-树突／轴突-胞体／轴突-轴突／树突-树突……点对点接触位点）· 电路（前馈／反馈／侧向／相互／递归／去抑制／赢家通吃／全局抑制增益控制／突触链／传出拷贝抵消／半中枢振荡／网格相位进动……）· 调制（弥散／容积／逆行／状态门控）· 电性（缝隙连接／电场突触／混合电化学／三元星形胶质细胞／平台电位双稳态）· 可塑性（STDP／LTP-LTD／短期／稳态缩放／调制剂门控／重复激活 LTS／血清素能突触前易化／短期习惯化／巧合检测）· 宏观（拓扑映射／发散扇出／汇聚扇入／副本放电／全局广播／稀疏扩展／指令神经元招募／双稳态切换／跨模态热量汇聚）。

因此，这个代数结构是 virtual organism = units (nodes) + connection types (typed edges)，并且每条边都可通过机械方式检查，因为两端都声明了端口类型：

unit A .out_port[type]  --connection_type(from_port, to_port)-->  unit B .in_port[type]

compose_from_units 会强制执行端口类型兼容性、必需端口满足情况，以及整个生物体的外部驱动／读取能力，并将反馈环报告为警告（有意设置的反馈环在这里是一等公民）。生物体边界上未满足的必需输入就是生物体的外部输入，并非缺陷——若要验证内部子链，请传入 allow_boundary_inputs: false。 项目附带四条规范链路作为测试夹具，每次运行时都会由 Gate 9 重新验证：--demo mammal（视网膜 → 丘脑 → 皮层 → 基底神经节 → 运动丘脑）、--demo insect（触角叶 → 蘑菇体稀疏编码 → 学习到的效价 → 受时钟偏置的中央复合体朝向／转向）、 --demo electrosensory（放电器节律器 → 传出副本抵消 → 电定位，另有一条被动电信号线索输入 Mauthner 逃逸指令） 以及 --demo swim（水蛭半中枢游泳 CPG → 海鞘幼体振荡器 → 青蛙网状脊髓逃逸游泳）。 不带参数的 --demo 会运行全部四条链路。

发育轴（v2.30.0）——L1 / L2 / L3 / 成虫阶段的同四个回路

Witvliet 2020 系列包含 8 个重建数据集，而不是 2 个：4 只 L1 动物、 1 只 L2、1 只 L3 和 2 只成虫。该库过去只有 2 个成虫数据集。 现在，8 个数据集都已加载，并按动物分别测量。上述每个 C. elegans 单元都在 provenance.developmental_stages 中记录了结果；运行 flybrain stages 即可查看。

阶段	数据集	细胞类别	唯一边	突触
L1	1	108	566	1,400
L1	2	114	693	2,028
L1	3	119	700	2,237
L1	4	122	795	3,020
L2	5	128	1,107	4,535
L3	6	132	1,072	4,723
成虫	7	135	1,565	7,867
成虫	8	134	1,530	8,400

四个回路在各阶段的测量结果（每只动物的突触数）：

单元	L1	L2	L3	成虫
前向运动指令	26 / 34 / 41 / 66	92	87	125 / 179
触碰回避反射	30 / 38 / 43 / 72	111	107	159 / 210
两栖化学感觉	97 / 127 / 150 / 199	301	267	433 / 495
伤害感受回避	21 / 22 / 31 / 64	76	69	110 / 144

这四行的数值不能相加（v2.34.0）。 这些回路的细胞类别集合并不互斥——AIA 同时属于四个回路，AIB/AIZ/AVB/PV 则属于两个或三个回路——因此，像 AIZ → AIB 这样的边同时是两个回路的内部连接，会被两个回路重复计数。将各列相加，会使这些回路内部实际连接数被高估约 1.27 倍。现在按阶段同时报告这两种数值：

阶段	四个回路的总和	并集（只计一次）	高估倍数
L1	1,061	849	1.25×
L2	580	455	1.27×
L3	530	421	1.26×
成虫	1,855	1,456	1.27×

若要了解“这只动物有多少连接位于这些回路内部”，请使用并集；只有在分别统计各回路时才使用总和。现在，提取器会断言各回路的行数据之和与总和一致；如果不一致，就会拒绝写入。

有一个回路的测量范围比其所属单元更广（v2.35.0）。 PROFILES 为触碰回避回路声明了 11 个细胞类别，其中包括 PLM；但 extract_cel_profiles.py 只会为已声明且确实在模块内有边的类别输出成员概况——而在成虫重建数据中，PLM 没有边，因此 v2.27 单元包含 10 个成员，且该库中不存在 cel.plm。合并全部 8 个重建数据集后，PLM 确实有边，因此本系列测量了 11 个成员。这两者都正确；单元名称相同，正因如此，这一差异此前既无名称，也没有校验机制。现在，产物会将其记录为 declared_vs_shipped，如果某个单元输出了本系列无法测量的类别，提取器将拒绝写入。实际影响：比较触碰回避回路各阶段的数值与该单元时，应将这一个类别的差异考虑在内，而不能直接比较。

在全部 16 次测量中，四个回路在每只动物的每个阶段都存在（L1 阶段有 6–37 条边），因此发育带来的是突触权重的增加，而不是新的拓扑结构。

这里重要的边界。 一项次要结果——271 对边只出现在 L1，而不出现在成虫阶段——不会被报告为发育期间短暂出现的突触。单个 L1 文件包含 566–795 条不同的边，而单个 L2 文件有 1,107 条，因此“在 L1 中观察到”这一结果与重建深度相混淆。只有经得住这一混淆的结论才会发布；cel_development_stages.json 的 caveat 字段在产物中说明了这一点。从 v2.34.0 起，这个 271 是计算得出的（位于 stage_diffs.l1_only_keys 中，与 l1_union_keys 1,188、adult_union_keys 1,980、shared_keys 917、adult_only_keys 1,063 并列），而不是作为无法在源数据变更后重新推导的固定值写入 caveat。

幼虫集群账本（v2.31.0）——各单元覆盖了多少幼虫网络

这八个幼虫单元是通过聚合 (cell_type, annotations) 上的节点构建的。还有一个问题没有解答：它们实际覆盖了 352,611 个突触组成的幼虫网络中的多少？flybrain larva-clusters 会遍历全部 116,922 条边来回答这个问题。

只有当两个端点的 (cell_type, modality bucket) 都解析为至少有一个单元声明为成员的 larv.* 配置时，突触才算作已覆盖。如果两个端点都不符合，则该突触属于边界。

指标	突触数	占比
两个端点均可追溯	271,956	77.13%
边界（没有单元声明任一端点）	12,415	3.52%

按单元统计，要求两个端点均可解析：

单元	突触数	占比	涉及细胞数
嗅觉联想学习	80,161	22.73%	548
蘑菇体反馈	74,960	21.26%	530
体感逃逸	57,262	16.24%	942
下行运动指令	53,824	15.26%	910
温度感觉中继	22,981	6.52%	361
视觉中继	20,712	5.87%	358
味觉摄食程序	6,428	1.82%	525
呼吸中继	2,736	0.78%	275

有三类细胞完全不属于任何单元：未标注类（346 个细胞）、MB-FFN 和 pre-DN-SEZ。

配置 ID 中的 _unannotated 并不表示“未标注”（v2.36.0）。 43 类配置中有 15 类带有这个后缀；这是 bucket() 在无法识别模态时使用的后备类别，并非对注释状态的判定：如果某个细胞的 annotations 字符串就是 KC，它不含任何模态关键词，因此会落入后备类别，但它的名称其实是完整的。这 15 类中有 13 类包含带注释的细胞，共 1,686 个，其中包括 larv.kc_unannotated（144 个细胞，注释均为 KC）、larv.mb_fbn_unannotated（100 个，注释均类似 CN-10; FAN-2）和 larv.mb_ffn_unannotated（54 个，均为 FFN-23 及其同类）。本 README 早先将边界列表解读为注释状态的那句话，错就错在这一点：MB-FFN 的 54 个细胞都有名称。

全网络的数字不受影响——1,560 个细胞（52.77%）确实没有官方注释，因为该数字直接读取 annotations 列，不会用到类别划分。错的是对名称的解读。各 ID 保持不变（共 40 个配置键，gate 9 和每份已发布产物都按名称索引）；现在会在 annotation_identity 中分别统计这两个概念，并通过每个单元上的 member_id_caveat 加以记录。

各单元行的数字也不能相加（v2.34.0）。 19 个 larv.* 配置由多个单元声明，包括 larv.lhn_unannotated、larv.lhn_mechano、larv.kc_unannotated 等，因此同一个突触会合理地计入多个单元。八行合计为 319,064，而覆盖总数为 271,956（1.17 倍）。统计网络覆盖时应使用并集数字；比较各单元时才使用各单元行。共享配置列表位于 unit_attribution 中，运行 flybrain larva-clusters --caveat 会打印该列表。提取器会断言：各行之和不会低于覆盖总数、覆盖分区完整闭合，并且每个集群的 internal + out 之和能还原整个网络。

细胞数量不是正确的衡量指标。 幼虫网络中有 1,560 个细胞没有官方注释，占神经元总数的 52.77%；正是这个数字让人觉得网络中的大部分细胞都尚未表征。它们涉及 212,542 个突触，占总数的 60.28%，因为各单元确实将未注释群体声明为填充角色。覆盖与表征是两回事，这份账本有意将二者分开：一个单元可以覆盖四分之三的幼虫突触，但其中未注释的成员仍可能没有已知功能。集群 0——作者标记为未分配的分组，共 364 个细胞——是整个网络中涉及突触数最多的单一集群（51,211 个），这里不会为它指定功能。

雄性二态性台账（v2.32.0，审计版 v2.33.0）——雄性连接组中的 2,368 个细胞

MaleCNS v1.0 是一份雄性重建，其注释表中有一列 dimorphism。这个库里从来没人读取过它：58 个锚定配置文件是根据 superclass / type 构建的，而 type 不区分性别。flybrain dimorphism 会流式读取全部 151,856,684 条权重记录，并逐条检查每条边是否至少有一个端点属于该列标记的 2,368 个细胞。

数量	数值
细胞体 / 细胞类型	2,368 / 479
与该群体相连的边	5,875,648 对 — 22.97%
与该群体相连的突触	13,376,848 — 10.77%
两个端点均为二态性细胞的边	284,982 对 — 1.11%
两个端点均为二态性细胞的突触	1,589,267 — 1.28%

最后两行之间的差距就是关键发现。 雄性群体并非一座孤岛：它是一个稀疏却连接广泛的子集，主要与通用细胞交流，而它所接触的突触中，只有约九分之一位于自身细胞之间。若依据这些数字来定义“雄性回路”，那么它只能是 1.28% 的部分——这个比例甚至低于周围网络的测量噪声。因此，我们不定义任何回路：FUNCTIONAL_UNITS 仍为 115 个，其中 29 个单元在 provenance.male_dimorphic 中记录了与该群体的距离。

总量最大的类型是 TmY21（372 个细胞体、732,527 个突触，占整个网络的 0.590%）。两端均为二态性细胞的边中，总量最大的一对是 TmY21 → LoVP92（442 条边 / 2,721 个突触），其次是 AN09B017b → mAL_m1，然后是 pC1_2a → mAL_m8。

这里的“大”有多大（v2.33.0）。 v2.32.0 报出了这些总量，却没有提供任何参照，因此 oviIN 的两个细胞体 / 196,360 个突触看起来像是错误——这比“每个神经元 1k–10k”的经验法则高出 10 倍。但这不是错误。该连接组中每个细胞体的突触分布呈重尾：

每个细胞体的突触数（已注释细胞体）	中位数	p90	p99	p99.9	最大值
有突触的细胞体共 191,696 个	1,164	4,636	19,816	48,496	271,220

因此，oviIN 位于第 99.98 百分位——它处在长尾顶端，并非离群值；而按总量计最大的类型 TmY21，其每个细胞体的数值仅位于第 72 百分位。细胞数量与单细胞连接强度并非一回事，现在台账同时记录了这两项。

仅凭类型名称无法告诉你的三件事（v2.33.0）。 第一，注释表中有三个彼此独立的类型轴——type（MaleCNS，11,751 个类别）、flywireType（8,199 个）和 hemibrainType（4,495 个）——其中 type 与 flywireType 在33.08% 的细胞体上不一致。本台账中的 TmY21，在 FlyWire 中称为 Tm36；每个排名靠前的类型都会附带这一别名。所有 5,413 个锚定类型名称均已核实属于 type 轴；如果这一点不再成立，脚本将拒绝写入。第二，每种类型现在都会附带性别标签背后的策展人原文 matchingNotes 说明（oviIN："雄性的树突更广泛"），以及其追踪等级——479 种类型中有 150 种带有此类说明，327 种仅为 Roughly traced。第三，每次运行都会核对每种类型的总量：每一对边会按其二态性端点计数一次，因此总和必须等于相连边数 + 两端均为二态性细胞的边数（14,966,115）；若不相等，提取器将拒绝写入。v2.32.0 中的总和并不相等——内部边被计数了四次，导致每种类型的数值都比实际多出内部边总量的 3 倍。

这份台账无法说明什么。 MaleCNS 不包含雌性重建，因此 dimorphism 标签是策展人的注释，并非在此处进行比较后得出的结论。没有任何内容支持“雄性更大”这一说法，产物自身的 caveat 字段也明确说明了这一点。我们还特意将两个计数器分开：194 种二态性类型被列出在某个锚定配置文件自己的类型列表中（说明有人查看过它们）；而全部 479 种都属于某条锚定的 ^XXX 家族规则——属于某个家族并不代表经过追踪。

连接成本维度（v2.38.0）——每种连接的成本，以及我们无法断言的内容

PROJECT_VISION.md 声称生成器可以将生物学库作为先验，针对任何目标进行优化。第 3 阶段对此进行了测试，发现优化器只能在结构上取得优势（线路成本降低 −84%），而备受关注的计算能力主张结果为负：7 种拓扑中没有一种胜过随机基线。

问题出在词汇而非优化器上。66 种连接类型的 delay_class 只有三个符号值——immediate / short / long——而 parameters 块没有单位。延迟只是类别，能耗又缺失，唯一可权衡的维度就只剩结构。flybrain costs 会在有引文支持时添加数值，没有依据时则标为 unknown。

依据	延迟	来源
化学突触	0.5–4 ms	Guyton & Hall 2008 第 570 页给出的最低值为 0.5 ms；典型范围为 0.5–4 ms
电突触	0.05–0.2 ms	引用值低于 0.2 ms，常被称为瞬时传递
体积传递	10–1000 ms	扩散云；扩散过程本身就是传递机制
逆行信使	1–60 ms	比顺向释放慢，但比体积扩散快
电路基序／宏观几何／可塑性规则	无——unknown	这不是接触点，而是一种模式，其成本是涌现出来的

**66 种类型中，16 种带有延迟值，50 种没有，这一差异就是发现。**所有带数值的类型都是真实的接触位点（微观 9/10、电突触 3/7、调制性 4/6）。20 种电路基序、13 种宏观几何和 10 种可塑性规则都没有延迟值，因为单个接触点的延迟并不适用于一种模式——将成员的延迟组合起来，基序的成本便随之得出。66 种类型都有能耗值，因为能耗可以按基序组合，而延迟不行。这种不对称性正是设计的一部分。

21 种类型按规则不带延迟值。它们被标记为 abstraction_only——胜者全得或半中心振荡器是设计模式，不是生物学接触点；自突触在化学上属于化学突触，但作为设计模式，文献无法提供其延迟。它们的 delay_class 保留在 designed_cost 下，确保假设永远不会与测量值相加。延迟是一个范围，而非一个点：范围体现了权衡，因为选择快速突触会牺牲可靠性。

**这个维度真的能引导优化器吗？（v2.39.0）**没人会据以优化的数据只是装饰，因此 cost_aware_optimization_experiment.py 使用相同的空间、预算和评估种子运行两次相同的 GA，只改变目标，并检验延迟惩罚是否真的能降低延迟。

在单元粒度上无法进行测试，这是实测事实：115 个单元中只有 14 个的所有连接类型都具有延迟值。其余 101 个单元都包含延迟未知的类型，未知类型占比的中位数为 100%，因此一个包含 5–6 个单元的生物体几乎总会包含此类类型，完全无法得出延迟数值。

**在连接类型粒度上则有效。**预算固定为 6 条边时：

	struct_only	cost_aware
边数	6.00	6.00（不变）
延迟	1536.62 ms	16.40 ms（−98.9%）
能耗	0.414	0.383（−7.4%）

延迟降低 99%，无需增加线路，且能耗更低——这是帕累托改进，因为快速类型（电突触，0.05–0.2 ms）也是成本较低的类型。在四种参数设置中：k=6 两次都得到 −98.9%，结果完全相同；k=8 得到 −51.2%；而 k=10 得到 +73%——该维度不再起作用，因为只有 16 种带延迟值的类型，无法从快速类型中选满 10 种候选。容量边界保留在产物中，而没有被平均值掩盖。 优化器发现了三个测量漏洞，而且都是我造成的：把 unknown 当作 0 ms（因此，获胜的最廉价方式就是选择无法测量的类型——结果虚报为 −99.9%）；把它按最慢延迟计费（GA 学会了增加未测量类型，三次运行中的延迟均上升了 16–19%）；以及候选规模是浮动的（GA 将每个候选缩减到一种类型，并通过删除拓扑虚报 99.9% 的胜利）。这三种情况的修复方法相同：未测量的类型是不可比较的，既不便宜也不昂贵，因此包含此类类型的拓扑不会纳入延迟排名；同时，候选规模必须经过断言，而不能靠假定。

GATE 12 会强制执行这些规则。若某个设计抽象新增了延迟、范围格式错误、电气类型中最快的速度不严格快于化学类型中最慢的速度（这是该坐标轴旨在表达的权衡）、某个分级值没有引用任何内容，或任何类型丢失了能量条目，检查就会失败。

功能坐标轴（v2.37.0）——按功能覆盖，而非按物种覆盖

该库按分类群组织。116 个单元包含 48 种不同的 system 值和 60 多种不同的 function 值，其名称都与解剖结构有关：cortical_、retinal_、larv_、cel_、frog_、birdsong_。这是物种回路目录，而非功能库；PROJECT_VISION.md 要求的是后者——它列出了生成器所要扩展覆盖的类别。

flybrain function 用于衡量差距。每个单元都标注了其自身的 capability / task_hint_pool 字段所声明的功能类别；不会从描述文本中推断，也不会添加、重命名或重新分类任何单元。

在 PROJECT_VISION 要求的 15 个类别中：

状态	类别
缺失	无（v2.41.0 补齐了最后一个类别 metacognition；v2.42.0 补齐了两个非视觉类别 homeostasis 和 neuromodulation）
覆盖较薄（<3 个单元）	attention（2） · habit（1） · metacognition（1） · punishment（1） · working_memory（1） · motor_command（2） · motor_relay（1）
已覆盖	integration（4） · prediction（6） · reward（5） · associative_learn（9，4 个分类群） · memory_encode（11） · memory_readout（5） · sensory_relay（16） · sensory_transduction（6）

衡量覆盖情况的诚实方式是看分类群广度，而这正是该库最大的短板。 covered 统计的是单元数量，因此由单一物种承载的类别也会显示为已覆盖。若按实际承载每个必需类别的分类群数量拆分：

15 个必需类别中，只有 1 个——associative_learn——覆盖了 3 个或更多分类群。其余 14 个都只在单一分类群中实现。

GATE 11 会从矩阵推导出这一划分；如果有人手动编写或悄然改善结果，检查就会失败。该库可以生成 115 个回路；但它还无法跨物种泛化某项功能，而这正是形态生成器所需要的。要弥补这一差距，就必须添加有真实证据支持的新单元——大约还需 14 个，且每个都要经过文献核验、运行 JEV 并注册配置文件。

元认知，最后一个缺失的类别（v2.41.0）

对全部 116 个单元的名称、功能和描述进行全面检索，查找 confidence、uncertainty、metacognit、precision 和 attentional，结果一无所获——这个缺口确实存在，而那 48 个未标记的单元也无法填补它（它们的能力是 oscillate 和 reflex 这类机制动词）。因此需要新增一个单元：prefrontal_metacognitive_unit，包含六种配置。

文献区分的是两个网络，而不是一个“信心中枢”：dACC 和岛叶承载客观不确定性，与报告的信心程度呈负相关；VMPFC 和 pgACC 承载主观感受，呈正相关；而外侧额极则将私人估计映射为公开报告——这个阶段可以与信心本身区分开来。JEV 返回了部分通过（文献 0.76、模型 0.56、得分 4）：文献证据充分，但尚未通过计算验证。接入过程中触发了两道默认关闭的关卡（先是没有 JEV 判定，接着是成员不在 MODULE_PROFILES 中），两者都没有被绕过。

对这一维度的诚实总结是：24 个类别中，只有 2 个由三个或更多类群承载（associative_learn、credit_assign），而 116 个单元中有 41 个不属于任何类别。跨类群覆盖是该库最薄弱的维度，现在这已是一个数字，而非印象。标签表示该单元声明实现了该类别的机制——它是覆盖标签，并不表示该单元能出色地执行该功能。

关键词修复与匹配证据（v2.42.0）——必须让矩阵结果可信

v2.42.0 发现有两个类别报告了0 个单元，但库中其实已经声明了它们。homeostasis 的关键词列表是 homeostasis、thermoregulation、circadian_rhythm、fluid_balance——而库中对这一概念的表述是 circadian_pace、oscillate_circadian、circadian_track、sleep_wake、metabolic_support。neuromodulation 也有同样的问题：它的六个词条一个都匹配不上，但有十二个单元用 modulate、modulation、peptide_release、calcium_wave 声明了该类别。两者都被判为 missing，因此工作队列要求“构建这些类别”，尽管库中早已有相关内容。

修复方式是加入库中实际使用的词语，而不是放宽匹配器。经过对每个能力字符串的探查，有两个候选词条被拒绝；拒绝原因也记录在 function_coverage.json 中，以便保持可见：

词条	原本会归入	拒绝原因
rhythm_generate	homeostasis	会匹配所有 CP 和模式生成器（spinal_cpg_unit、respiratory_rhythm_cpg_unit、courtship_song_pattern_unit 等）——这是节律生成，属于运动输出，而非将内部变量维持在范围内
broadcast	neuromodulation	value_broadcast 和 arousal_broadcast 是命令广播，并非能改变多个靶点增益的可扩散信号——子串陷阱又以完整词条的形式重现了

现在，每个标签都会附带触发它的词条：match_evidence[unit] = ["cap <- token", …]。GATE 11 会根据单元自身的 capability / task_hint_pool 字段重新推导全部 213 对，并拒绝写入任何无法复现的标签。一项故障注入测试为 spinal_cpg_unit 提供了伪造的 rhythm_generate <- circadian 证据条目，结果关卡以 the tag was not earned 为由失败。这就是覆盖矩阵与巧合报告的区别——在这道关卡建立之前，矩阵曾三次夸大自身结果。

组合语义（v2.40.0）——能否组装这个库？

composable_with 决定哪些单元可以连接在一起，而在 v2.40.0 之前，没有任何检查会验证这一点。门禁 1–12 验证了单元格式正确、函数覆盖范围得到衡量、延迟有据可查——但都没有检查声明的组合是否真的能够构成。

在 115 个单元中，共有 163 项声明：

状态	数量
互为声明 且 端口类型匹配	28
单向声明，但端口类型匹配	38
已声明，但没有任何端口类型能够匹配	97

可用组合：23 对互相声明的组合，加上 28 对单向声明但可达的组合。 例如，amygdala_fear_unit 提供 out: limbic.fear，而 hypothalamic_arousal_unit 只接受 arousal.state / rhythm.circadian——两者没有重叠，因此无法构建该组合。

已在 v2.41.0 中修复。 构建器不再照单全收声明：suggest_composition 现在只有在另一单元也声明了该组合或端口类型确实匹配时才会生成边，并将所有舍弃的内容及其原因记录在 skipped_edges 中——这样被丢弃的组合就会清晰可见，而不会悄无声息。strict=False 可恢复旧行为。针对 memory 查询：严格模式保留 2 条边，并舍弃 1 条，原因是 reason: ports_cannot_meet_and_not_reciprocated；旧版保留了 3 条。

门禁 13 从行为上执行检查，而不是通过搜索源代码：它会调用 suggest_composition，并检查严格模式返回的边数是否始终不超过旧版，以及保留列表和舍弃列表中是否没有重复项。

已无问题的部分： internal_wiring 中有 0 个悬空角色引用，并且 115/115 个单元都同时提供输入端口和输出端口。

该门禁还必须能应对错误数据：第一个版本遇到指向不存在单元的 composable_with 条目时会崩溃，而遇到一条错误引用就崩溃的门禁无法报告其余问题。修复后，同时注入悬空角色引用和悬空目标时，门禁会报告两者并以 1 退出。

门禁 11 确保结果可靠。 这是第一个会检查该库是否覆盖愿景所需内容的门禁。它不会因为存在缺口而失败——缺口列表就是待办队列。只有当缺口变得不可见时才会失败：摘要与矩阵不一致、某个类别引用了库中不存在的单元、已标记与未标记项之和不等于库的规模，或者 cross_species 声明与其自身计数矛盾。

MaleCNS 具身化（v1.7.0，v1.8.0 加密）

以上内容均经过文献整理，因此该库无法回答每位读者都会先问的问题：这些内容是否与其命名所指的果蝇大脑有关？functional_units/malecns_anchors.json（由 scripts/build_malecns_anchors.py 构建）针对能够如实回答的部分给出了答案。

• 存在性。 116 个单元中有 37 个的成员种群可解析为 MaleCNS v1.0 中真实标注的细胞类型。整个库中，覆盖 107,558 个真实细胞的204 个神经元种群中有 58 个符合条件：蘑菇体单元的 kc 角色包含 4,064 个真实 Kenyon 细胞，涵盖 15 种真实 KC 类型（KCg-m、KCab-m、KCa'b'-ap2 等）；其 input 角色包含 583 个真实触角叶投射神经元，涵盖 145 种类型（DA1_lPN、VM5d_adPN 等）；其 gaba 角色包含 2 个真实 APL 细胞。匹配依据是明确的名称规则加上数据集自身的 superclass——仅靠名称规则会把时钟神经元 DN1a/DN1pA 和内分泌细胞 DNES1-3 错归入下行神经元锚点——完整匹配列表会写入制品，因此只需读取 JSON 就能审查错误规则，无需盲目信任脚本。
• 依据实测结构，而非假定结构。 对真实突触表进行一次遍历，就能生成完整的 27×27 超类矩阵和锚定细胞类型矩阵，并独立与 connectivity_stats.json 交叉核对：两者均确认，25,582,938 条边上共有 124,177,617 个突触。因此，每条声明的单元边都对应两个种群实际细胞类型之间实测的突触数——触角叶 PN → Kenyon 细胞测得 378,315 个突触，分布于 21,658 对相连类型；Kenyon 细胞 → 蘑菇体输出神经元测得 463,640 个；Kenyon 细胞 → APL 测得 210,352 个。v1.8.0 中新增的 10 个果蝇形态单元也在写入连接关系前通过了同一测试：T4/T5 → 叶板切向细胞测得 296,217 个；髓质内在神经元 → T4/T5 测得 1,924,544 个；PN → 侧角测得 391,155 个；巨纤维 → TTMn 测得著名的 90 个（跨真实的电-化学混合突触）；pC1 → pIP 测得 1,973 个；AMMC → pIP 测得 90 个。
• 按类型对分辨率划分的支持等级（v2.2.0）。 配置文件级计数仍是矛盾检查关卡，但不再是唯一判定依据：现在还会逐条检查声明的边，遍历 5,413×5,413 锚定类型对矩阵，统计有真实突触的单个 (from_type, to_type) 类型对数量。这能区分分布于多种细胞类型的通路，以及仅由一个侥幸类型对撑起的配置文件级非零计数，并由此发现了 6 条脆弱边，它们在细胞类型集合判定中曾被视为正常：giant_fiber_escape_unit 中的 GF → TTMn（4 对，其中 1 对有连接：DNp01 → TTMn = 90）和 GF → PSI（1 对：DNp01 → PSI = 16）；auditory_song_reception_unit 中的 AMMC → aSP（240 对，其中 1 对有连接：AMMC012 → aSP10A_b = 19）；cb_efferent_command_unit 中的 PN → CB-efferent（145 对，其中 1 对有连接：VP2+Z_lvPN → GNG656 = 2）；以及 buccal_efferent_feedback_unit 中的两条边（LN-DN2 → DNg28 = 16，DNg28 → PhG3 = 3）。109 条边为 SUPPORTED（≥2 个有连接的类型对），6 条为 FRAGILE（恰好 1 个），1 条为 CONTRADICTED。FRAGILE 是一种新增的诚实等级，并非新增矛盾——这些边确有实测支持，只是不应被当作强证据引用；Gate 10 会根据原始矩阵重新推导每个等级，因此手写的等级无法蒙混过关。
• 证伪，而非证实。 非零计数仅意味着在细胞类型集合分辨率下，声明的边未被否定；它并不能说明声明的连接形式就是果蝇实际采用的形式。零计数则构成真实矛盾，而库中恰好只有一处：central_complex_steering_unit 的 nod -> fb 投射；本版本中的 Nod 种群（5 种类型、12 个细胞，数据集将其归入 visual_projection）并未体现该投射。该投射仍予以保留并标记为 UNSUPPORTED，而不是悄悄改写成能通过测试的内容——任何未在 ACKNOWLEDGED_CONTRADICTIONS 中登记并说明理由的矛盾都会导致 Gate 10 失败。
• 其余 146 个种群均因明确说明的理由而未锚定，并非被悄悄跳过：其中 131 个不属于果蝇（鸟类歌唱系统、鱼类 Mauthner 细胞和电感受、头足类垂直叶、哺乳动物皮层类别），5 个无法足够精确地解析以确保结论可靠，还有 10 个是没有单一细胞类别可对应的抽象认知模块。现在，每个未锚定的单元也带有可由机器检查的 provenance.unanchored_reason，其值取自三项枚举之一（taxon_no_malecns_data / identity_not_in_drosophila / abstract_module_no_cell_type），并根据配置文件分类推导，而非手动指定，因此读者无需猜测单元为何没有锚点：当前 66 个单元全都归入 identity_not_in_drosophila——其中 58 个只引用非果蝇细胞类别，另有 8 个将这些类别与 5 个过于宽泛而无法解析的配置文件混在一起（interneuron_kcn、interneuron_lamp、interneuron_npf、interneuron_nph、olfactory_receptor）。没有任何未锚定单元的成员全是抽象模块，也没有成员全是本物种但缺少数据的情况，因此另外两个枚举值虽已定义，目前尚未使用——Gate 10 会验证每个单元的理由是否与分类推导结果一致，因此手写的理由无法蒙混过关。 诚实的边界。 这些单元整理自比较神经科学文献，每个单元都注明了参考文献（所有 97 个单元的 provenance.extracted_from_malecns 均为 false）——它们并非提取自 MaleCNS v1.0，这与最初的三个果蝇基元不同。成员比例是组成权重，不是测得的细胞数量。provenance.embodied_in_malecns 标记了其中 31 个种群确实能对应到真实的注释细胞。具身化证明这些组成部分存在，且声明的边未被事实否定；但这并不能证明所声明的微回路或其连接形式。应将这一层视为具有文献出处、可组合的框架，而非测得的细胞集合。

机器可读的对应项：list_functional_units、get_functional_unit、list_connection_types、compose_from_units。使用 python scripts/gen_functional_units.py 和 python scripts/check_functional_units.py 重新生成并验证（Gate 9：如果产物与生成器不一致、成员神经元在词汇表中不存在，或组合器不再拒绝格式错误的连接配置，则构建失败）。具身化层通过 python scripts/build_malecns_anchors.py 重建，并由 scripts/check_embodiment.py 锁定（Gate 10：每次运行都会根据矩阵重新计算所有测量计数、从原始类型对矩阵重新推导每个支持等级、重新注入九项缺陷，并拒绝发布任何未经确认的矛盾或手动输入的原因）。

---

科学与论文

方法论、四道护城河、六种被证伪的机制，以及两个负面结果，均已写入 docs/arxiv_paper.md（可直接作为预印本）。

研究自我验证规范（S6–S9）

本项目遵循四项科学自我验证规范。这些规范在开源工具中并不常见，但对于维护研究诚信至关重要：

• S6 · 对照组的可评分性——每项对照实验都必须验证对照组在每个任务类别中都有可评分样本。如果某个类别在结构上无法对对照组评分，则必须将其排除或单独报告。（发现了 P1 中虚假的 +33.4pp 结果。）

• S7 · 分辨率预检——开始扫描实验前，验证目标分辨率是否符合参数空间的几何极限（clamp_density = n_nodes / (n * (n-1))）。（发现了 R2 中未显现的钳制。）

• S8 · 将机制证伪作为输出——机制假设被证伪时，结果必须包含结构化的 falsified_mechanisms 列表（机制、假设、测试、结果、判定）。目前已有六种机制经过测试并被证伪（P1 特征添加、P2 任务对齐、P3 边密度、P1 校正、R3 单调增益、H-A 关键边稀疏性）。

• S9 · 优先进行扰动分析，而非相关性分析——当相关性 R² < 0.05 时，必须存在扰动数据，且其中包含边界信号。仅凭相关性不足以支撑机制主张。

Xu 2026 树突计算——模式参考（v3.00.3）

Xu, N. 等人（Science，2026-10-16，DOI：10.1126/science.adz5323） 通过光遗传学因果证据证明，顶端树突编码抽象规则，胞体编码感觉输入，二者的非线性整合会产生决策输出。这是支持我们 L3 边界的外部理论依据，不会改变项目架构。

仅供参考的实现（不会改变核心组合代数）：

路径	内容
tools/dendritic_rule_engine.py	约 200 行的最简参考实现：RuleCache（树突）+ SensoryStream（胞体）+ NonlinearIntegrator（乘法门控）+ DendriticAgent 外观
examples/07_dendritic_rule_cache_demo.ipynb	规则切换流演示，展示置信度门控的巩固过程
docs/XU2026_DENDRITIC_PATTERN_MAPPING.md	一页纸的 EPE L1/L2/L4 映射，以及可顺利映射与不可映射的部分
docs/XU2026_DENDRITIC_COMPUTATION_IMPACT_2026-10-18.md	完整影响备忘录（100 行，发布于 2026-10-18）

明确未做的工作（见备忘录 §2.3）：116 单元核心中没有亚细胞区室；没有从小鼠听觉皮层到 Drosophila MaleCNS 的跨物种迁移声明；没有神经形态实现。Xu 2026 是少样本假设缓存的模式参考，不是新架构。 这些规范由 Gate 30（scripts/check_llm_orchestrator.py）强制执行。它会根据实验数据独立重新计算声明元数据，并拒绝未验证的声明通过。

可复现的负面结果

项目维护着公开的 research_claims.json，其中包含六项声明（R1–R6），每项都包括：陈述、定量预测、证伪条件、复现命令、样本量、随机种子、边界陈述和已证伪机制。当前状态：1 项在指标修复后得到支持，3 项已完成，2 项处于边界状态（部分证伪和锚点差距，二者根据 PR-2b 先例均为终止状态）。研究声明系统本身也设有门控（Gate 30），以防止悄然偏移。

主要参考资料：

• MaleCNS v1.0 — Cell，2026-09-03（CC-BY）。本项目所依据的雄性大脑连接组，包含 166,700 个神经元。可从 male-cns.janelia.org/download / gs://flyem-male-cns/v1.0/ 获取；也可通过 neuPrint 数据集 male-cns:v1.0 查询。
• Friston（2008）Neuropsychologia 与 Fodor（1983）The Modularity of Mind——本项目故障隔离声明所处的大规模模块化争论。
• 双重分离作为认知神经科学的黄金标准（Geddes 2014；Glenberg 2014；Campanella 2022；Vaidya PNAS 2010）。
• dataprov（RI-SE、W3C PROV）——我们采用的来源信息序列化格式。

**引用本项目：**参见 CITATION.cff（GitHub 会据此显示“引用此仓库”按钮）。各版本的变更，包括撤回了哪些声明，见 CHANGELOG.md。

**通过 MCP 客户端使用：**参见 docs/mcp_setup.md。 **模块变体、SwarmLabs 集成及生物体市场（v1.1.0）：**参见 docs/module_factory.md。 其中包含客户端配置、47 个工具的参考资料及故障排除信息。

---

开发与测试

一条命令运行所有离线门禁

与 CI 运行的检查集相同，因此“本地通过”与“CI 通过”不会出现差异：

python scripts/run_gates.py              # 62 gates, no dataset needed
python scripts/run_gates.py --quick      # the 53 gates that don't need numpy / a server
python scripts/run_gates.py --with-data  # 62 gates: + `flybrain verify` (70 assertions)

Makefile 快捷命令（v2.43.0）

make help          # all targets
make setup         # create .venv, install [dev]
make lint          # ruff check + black --check
make format        # ruff --fix + black
make typecheck     # mypy on shipped code
make test          # pytest --cov
make gates         # = python scripts/run_gates.py
make gates-data    # + flybrain verify
make smoke         # generate a smoke organism
make build         # build dist/{sdist,wheel}
make publish       # twine upload

Docker（v2.43.0）

一个镜像包含两种模式。数据集不会打包进镜像——请将其挂载：

docker build -t flybrain-connectome .

# MCP stdio server
docker run --rm flybrain-connectome

# HTTP API on :8799
docker run --rm -p 8799:8799 \
  -v "$(pwd)/male_cns:/data/male_cns:ro" \
  -e FLYBRAIN_DATA_DIR=/data/male_cns \
  flybrain-connectome serve-http

docker-compose.yml 还提供 dev / api / mcp / gates 服务矩阵，每种用例只需一条命令：

docker compose up --build dev      # shell into the dev container
docker compose run --rm gates      # offline CI-equivalent gates

开发容器 / Codespaces

在 VS Code 或 Codespaces 中打开；.devcontainer.json 会安装所有内容，并在进入时运行 make gates。

Pre-commit

pre-commit install       # one time
pre-commit run --all-files

钩子：ruff + ruff-format + black + 行尾空白检查 + 文件末尾换行修复 + YAML/TOML/JSON 检查 + 合并冲突检查 + 调试语句检查 + detect-secrets（依据 .secrets.baseline）。

单独检查：每个关卡

# credential gate — MUST pass before any push (see CHANGELOG 1.0.0)
python scripts/check_no_secrets.py

# docs-vs-code drift gate: tool count/names, versions, schema, blueprint count
python scripts/check_docs_consistency.py

# every advertised MCP tool must actually respond (needs FLYBRAIN_DATA_DIR)
python scripts/check_mcp_tools.py

# a missing OPTIONAL dependency must degrade, not crash — and must not
# silently skip producing provenance when the dependency IS installed
python scripts/check_degraded_mode.py

# the generated artifact is structurally real (not just "exit code 0")
python scripts/check_generated_artifact.py --dir <out-dir> --name <organism>

# end-to-end smoke test (needs FLYBRAIN_DATA_DIR -> your data)
flybrain verify

# consistency between this repo and any downstream consumer
python integrations/swarmlabs/check_swarmlabs_sync.py

# reproducible experiments
python integrations/swarmlabs/diagnostics/fault_isolation_experiment.py --quick
python integrations/swarmlabs/diagnostics/snn_energy_experiment.py
python integrations/swarmlabs/diagnostics/multi_readout_experiment.py

单独检查：

# credential gate — MUST pass before any push (see CHANGELOG 1.0.0)
python scripts/check_no_secrets.py

# docs-vs-code drift gate: tool count/names, versions, schema, blueprint count
python scripts/check_docs_consistency.py

# every advertised MCP tool must actually respond (needs FLYBRAIN_DATA_DIR)
python scripts/check_mcp_tools.py

# a missing OPTIONAL dependency must degrade, not crash — and must not
# silently skip producing provenance when the dependency IS installed
python scripts/check_degraded_mode.py

# the generated artifact is structurally real (not just "exit code 0")
python scripts/check_generated_artifact.py --dir <out-dir> --name <organism>

# end-to-end smoke test (needs FLYBRAIN_DATA_DIR -> your data)
flybrain verify

# consistency between this repo and any downstream consumer
python integrations/swarmlabs/check_swarmlabs_sync.py

# reproducible experiments
python integrations/swarmlabs/diagnostics/fault_isolation_experiment.py --quick
python integrations/swarmlabs/diagnostics/snn_energy_experiment.py
python integrations/swarmlabs/diagnostics/multi_readout_experiment.py

scripts/check_mcp_tools.py --offline 会跳过 11 个依赖数据的工具，这与 CI 中的做法一致（CI 中不会下载数据集）。因此，CI 会验证生成器相关功能和打包，而数据路径则由在拥有该连接组数据的机器上运行的 flybrain verify 验证。

---

许可证与数据来源

• 代码： MIT——参见 LICENSE。自 2026-10-18 起，本仓库为公开状态。 有关三层划分和重新公开的历史，请参见 LICENSE-CLAUSE.md。
• 连接组数据： MaleCNS v1.0，CC-BY。5.63 GB 的数据集未包含在本仓库中。请从原始论文获取，并设置 FLYBRAIN_DATA_DIR。本项目中的所有数值均源自该真实数据集；没有任何内容是为了显得惊人而人工合成的。

“虚拟生物”是软件层面的类比：我们复用真实的拓扑原理（模体形态、递归率、抑制模式），而非真实细胞。它不是湿实验室构造，也不声称自己是。