开发者入口

服务器只给数字（数据、参数、链上记录），stateRoot 在你这边算 —— 这是平台原则，不是"服务端没做仿真"。 我们不发 npm 包：浏览器用下面的站点托管 SDK，Node / 任何语言只用公开只读 API（或把 SDK 文件存到本地，见 §1b）。

0 · 60 秒（浏览器，复制即跑）

// 存成 index.html，用浏览器打开；或直接粘进 <script type="module">
import { loadConnectome, Sim, resolveGroups, Q16, verifyStateRoot } from "https://fractalflyco.pages.dev/sdk/index.js";

const GOLDEN = "507914cd1a86eda415098506f53c8ff3492dd992b727962c3bd6fb66c1e57d75";
const { manifest, graph } = await loadConnectome({ api: "https://fractalfly-api-co.fractalfly.workers.dev" });
const { groups } = resolveGroups(graph);           // 只经命名群与内核通信（平台规则）
const sim = new Sim({ graph, manifest, seed: 64 });
for (let s = 0; s < 50; s++) {
  if (s % 5 === 0) sim.stimulate(groups["R1-6"].indices, Math.round(0.61 * Q16));
  sim.step();
}
const { match, root } = verifyStateRoot({ expected: GOLDEN, brain: sim.brain });
console.log(match ? "MATCH" : "MISMATCH", root);

预期输出：MATCH + 一串 root。黄金值（malecns-v1.0 + malecns-lif-v1 + seed 64 + 每 5 步给 R1-6 注入 0.61）： 507914cd1a86eda415098506f53c8ff3492dd992b727962c3bd6fb66c1e57d75

首次加载要下全脑分片：59 MB（gzip，1 MB Range 分块）⇒ 桌面 6–10 s；之后走浏览器缓存。 内核 20 ms/步 ⇒ 最快 50 Hz。现场可跑：/sdk-demo（同样只依赖站点 SDK + 公开 API）。

1 · Node（仓库之外）

1a · 只用 HTTP API（任何语言）

# 分片清单（含每片 sha256 与 URL）
curl "https://fractalfly-api-co.fractalfly.workers.dev/v1/connectome/parts?id=malecns-v1.0"

# 取一段分片字节（支持 Range => 206）
curl -H "Range: bytes=0-1048575" \
     "https://fractalfly-api-co.fractalfly.workers.dev/v1/connectome/graph?part=0&id=malecns-v1.0" -o part0.head

# 命名细胞索引（2.3 MB，不必下全图）
curl "https://fractalfly-api-co.fractalfly.workers.dev/v1/connectome/cells?type=DNa02&side=L&id=malecns-v1.0"

只靠 API 拿不到 stateRoot：内核是代码，不是数字。API 给你的是数据、模型参数与链上记录； 要复算状态根，需要下面的内核（浏览器 import，或 §1b 存到本地）。

1b · 把站点托管的 SDK 存到本地再 import（可校验）

站点上每个 SDK 文件的 sha256 都列在 /sdk/PROVENANCE.json 里（构建时写入，逐字节钉死）， 所以下载时可以当场校验，不必相信我们：

// node fetch-sdk.mjs
import fs from "node:fs/promises";
import path from "node:path";
import { createHash } from "node:crypto";

const ORIGIN = "https://fractalflyco.pages.dev";   // 站点 origin（本页自动填好）
const OUT = "./sdk";
const prov = await (await fetch(`${ORIGIN}/sdk/PROVENANCE.json`)).json();
for (const f of prov.files) {
  const buf = Buffer.from(await (await fetch(`${ORIGIN}/sdk/${f.name}`)).arrayBuffer());
  if (createHash("sha256").update(buf).digest("hex") !== f.sha256) {
    throw new Error(`sha256 mismatch: ${f.name}`);   // 对不上就别用
  }
  const to = path.join(OUT, f.name);
  await fs.mkdir(path.dirname(to), { recursive: true });
  await fs.writeFile(to, buf);
}
console.log(`ok: ${prov.files.length} 个文件已校验并落盘 -> ${OUT}`);

然后 import { … } from "./sdk/index.js" 即可（相对导入自洽）。 为什么不发 npm：我们不想把 SDK 源码放进 npm 仓库；但它本来就公开在站点上，而且逐文件可校验。 顺带一句：不要去 npm 上找 @fractalfly/sdk，那里面没有。

2 · /v1 API（公开 · 只读 · ACAO:*）

方法	路径	说明
GET	/v1/datasets[?commercial=1]	数据集注册表 + 实时 FFN 进度 + 许可/署名；commercial=1 只列可商用
GET	/v1/connectome/parts[?id=]	分片清单（id/graphSha256/counts/每片 sha256+url）
GET	/v1/connectome/manifest[?id=]	数据契约 manifest（含许可与来源）
GET	/v1/connectome/graph?part=N[&id=]	分片字节流；支持 Range ⇒ 206
GET	/v1/connectome/cells.bin[?id=]	cells 索引（FFC1，2.3 MB）
GET	/v1/connectome/cells?type=&side=[&superclass=&limit=&names=1&id=]	服务端过滤，返回 indices（不必下 59 MB 也能取索引）
GET	/v1/connectome/neurons/leaves.bin[?id=]	神经元累加器叶子（每叶 32 B）
GET	/v1/connectome/neurons/acc.bin[?id=]	累加器前缀根（含 count=total 的根）
GET	/v1/params	模型目录（id/paramsHash/常数，与内核同源）
GET	/v1/growth	生长计划 N(block)、累加器根/count、最近承诺、full.order/orderV2
GET	/v1/ledger?limit=N	链上流水（txid + explorer 链接）

/v1/sim/* 与 /v1/verify/* 刻意不存在：Worker 免费档跑不了仿真。 服务器给数字、客户端自己算一遍 —— 这是设计。

3 · SDK 表面

导出	环境	说明
loadConnectome({api,id,mode})	浏览器 / Node	mode:"api" 走 /v1/connectome/*；mode:"static" 读目录
loadConnectomeFS({dir})	Node	本地 manifest.json + 分片（离线最快）
loadCells({api,id})	浏览器 / Node	cells 索引（按类型/侧别查询，不必解析全图）
Sim / Brain / MODELS / Q16	两者	定点 Q16.16 LIF 内核（stimulate/step/stateRoot/snapshot/restore）
resolveGroups / makeSpikeCounter / GROUPS_SPEC	两者	命名神经群注册表（唯一允许的内核接口面）
eye / world / body	两者	eye.v1 / arena.v1 / arena2d.v1 声明式接口
verifyStateRoot / verifyBrainPayload	两者	复算与链上声明回放

4 · 许可与商用

• 数据：MaleCNS v1.0、BANC v888 为 CC BY 4.0（需署名）；FlyWire FAFB v783 为 CC BY-NC ⇒ 商用部署不提供其字节。
• SDK 代码：MIT（数据不在包里，从 /v1 取）。
• 商用栈是独立部署（独立 D1 / 独立桶 / 无密钥 / 不广播），价格与计量与条款目前都是草案。

5 · 诚实的缺口

• 未发 npm（只站点托管；见 §1b）。
• 只有一个实现：规范开放且可独立验证，但没有第二个实现者，也没有治理。
• 链是 testnet：承诺与累加器根都在 Fractal 测试网；主网尚未开始。
• 没有 SLA：有一个公开邮箱（§6），但不承诺响应时间；我们不声称什么那一页是认真的。
• 首次加载要下 59 MB 连接组；压缩、分块、缓存都做了，但第一次仍是 59 MB。

6 · 联系我们

邮件是我们唯一公开的联系方式：info@fractalfly.fun

为什么只给邮件：我们不用第三方统计脚本，也没有客服系统。写信时说明你在做什么、 卡在哪一步，比"有人吗"更容易得到有用的回复。数据集许可（尤其 CC BY-NC 的 FlyWire）、 商用授权、以及任何"你们的数字对不上"的问题，都走同一个地址。

这是一个个人维护的项目，不承诺响应时间。若没有回复，请再发一次， 并附上可复现的命令或链接 —— 我们没有私密的 Discord，也不在私信里做技术支持。