跳到主要内容

架构

GenKaKu 在生产环境中运行的一切,不是静态网站,就是节点进程。请求路径上没有任何 GenKaKu 服务器。

软件包​

软件包角色
@genkaku/protocolSolana 绑定、托管计费、libp2p sidecar、Ollama bridge
@genkaku/dsh-runtime两个插件共用的 adapter
@genkaku/dsh-worker-plugin@0.5.0-rc.8提供本机模型
@genkaku/dsh-user-plugin@0.5.0-rc.8取用网络模型
@genkaku/seedlibp2p relay 与节点发现服务
@genkaku/adminseed 主机的运营者控制台

协议内核不依赖 DeepSeek Harness。这是刻意的:另一个 adapter 不应该需要动到它。

链上​

一个程序,部署在 Solana mainnet-beta 与 Solana devnet 的同一个地址。该地址公布在 网站上,也写在插件的 netconfig.ts 里;在部署完成之前,网站的构建会拒绝宣传任何程序 id。

账户Seeds存放什么
RegistryConfig["registry"]owner、pending owner、曾经注册的 worker 数
Worker["worker", wallet]peer id、费率、locator、active、earned、settlements
EscrowConfig["escrow"]owner、金库、guardian、vault、USDC mint、会话上限、下一个会话 id、已累计的金库金额
Session["session", id]用户、worker、价格、押金、已累计、分钟数、时间戳、状态

托管的 USDC 放在 ["escrow"] PDA 的关联代币账户里。程序在每次转账时检查该账户的 mint 与 owner,而不是在链上推导地址:代币程序本来就是这两个字段的权威,而二进制文件必须塞进一份可部署 的租金预算里。

账户是固定大小的字节缓冲区,带有 8 字节的 discriminator,所以读取者不需要 IDL——只要 getAccountInfo 加上一份有文档的位移表。这个布局写在仓库的 solana/LAYOUT.md,并在 packages/protocol/src/solana.ts 中同步维护。

程序中的常量​

名称值意义
FEE_BPS1001% 分润,是常量而非设置
ABSOLUTE_SESSION_CAP100 USDC单一会话的最坏情况风险敞口
CLAIM_DELAY_SECS600用户仍能关闭会话的窗口
IDLE_CLOSE_SECS86 400沉默一天后,任何人都可以关闭
MAX_PRICE_PER_MIN1 USDC让打错的价格不会被当真

数据平面​

Worker 提供这些 libp2p 协议:

/genkaku/open/0 session open
/genkaku/token/0 auth token
/genkaku/receipt/0 signed ledger increments
/genkaku/settle/1 settle the session (the worker signs and sends it)
/genkaku/offers/0 offer board
/genkaku/policy/0 policy document
/genkaku/hello/0 identity, wallet proof, quote

每个 handler 都接受经过 relay 的连接(runOnLimitedConnection)。因此一次会话要么是直接 连接,要么由 relay 承载,两者都是一等公民。libp2p 会加密传输流,所以 relay 转发的是密文,只 看得到元数据。

这个版本没有 DCUtR/NAT 穿透。位于对称 NAT 后方的节点只能使用 relay,否则就是不可触及。

发现​

两条独立的路径:

  1. 链上目录 — 一次 getProgramAccounts 调用会返回每一个 Worker 账户。用户端会过滤掉 未激活的数据行、验证每一列的 peer id 是否编码它的钱包,并把结果缓存到磁盘,让没有网络的 开机也还能列出东西。
  2. Seed relay — https://seed.genkaku.app/seed(预发布环境: staging.genkaku.app/seed)以当下确实有效的 multiaddr 响应 GET /peers,并为无法直接 连接的节点提供 circuit relay。

Seed 地址已写死在 protocol 软件包中,但可以用 GENKAKU_BOOTSTRAP_SEEDS(以逗号分隔的 URL) 覆盖。

私密 worker​

可见性是 worker 的属性,而不是程序的属性:每个 worker 账户都保留自己的数据行,因为结算需要 一个可付款的账户。

公开私密
公告到 seed是否
链上数据行的 locator有全局可拨号地址时写入永远为空
active 标志11——open_session 会拒绝 inactive 的 worker
谁能拨号任何找到 peer id 的人允许清单上的钱包

闸门在 libp2p stream handler 上检查 connection.remotePeer——那是传输层认证过的值,不是请求 里的声明。walletOfPeerId() 把它换算回 Solana 地址,这就是同一把 ed25519 金钥既能当钱包又能 当 PeerId 的原因。不需要签两次名,也不保存 bearer token。

存取权由 /genkaku/pair/0 上的配对外换授予:

genkaku1.<base64url({ peerId, wallet, name, addrs, relay, secret, exp })>

Worker 只保存 sha256(secret),一组码一条记录,带到期时间(15 分钟)与 usedAt 戳记。兑换绑定 的是兑换者的钱包,不是字串,所以外流的码只是码,不是金钥。已用过的码由当初兑换的钱包重试会 幂等成功;换别的钱包则被拒。

私密模式不等于匿名。Relay 仍然承载电路,链上仍然记录付款,worker 运营者也仍然看得到提示词。

客户端偏好​

User 插件保存的是使用者选了什么,而不是网络提供了什么:

键意义
selected(worker, model) 键,最多十个(MAX_SELECTED_MODELS)
seeded清单尚未实体化前为 false
sort六种排序之一;选单使用同一顺序
privatePeers已配对的私密 worker:钱包、peer id、addrs、relay、标签

同一个 ~/.dsh/genkaku 目录里还有两个文件,属于客户端自己的政策,不是网络能看到的偏好:

文件意义
policy.jsonSpendPolicy:是否启用、名称、到期、额度上限、重置周期、单场上限、价格上限、本期支出、终身支出、待结算保留
spend.jsonl已结算场次:时间、micro-USDC、模型、worker、escrow id、tx;超过 512 KiB 后裁到最近 1000 行

policy.json 刻意不是链上账户。链只强制执行它收到的押金;押金之上的天花板只有客户端知道, 而一次拒绝的代价只是组交易之前的 HTTP 402。

selected 加上 seeded 才能让「我把全部取消勾选」撑过重启:一旦 seeded 为 true,空清单就是 一个选择,bridge 不会再自动填回。上限在 bridge 与 UI 都强制执行,因为 bridge 是唯一的写入者, 而 HTTP 客户端不等于 UI。

已配对的私密 worker 由背景 ticker(20 秒)探测。探测回来是空盘面时视为被拒绝,而不是线上 但没有模型,所以面板不会在允许清单说不行的时候宣称私密 worker 在线。探测永远不会阻塞状态请求。

计费模型​

pricePerHour : 6-decimal USDC, set by the worker
unit : 1 minute (60 units per hour)
billed : ceil(elapsed / 1min) × ceil(pricePerHour / 60)
deposit : 10 minutes of session time, prepaid, capped at 100 USDC

取整只发生一次,而不是每个 tick,所以用户永远不会付超过报价的每小时价格,而 worker 未计费 的风险敞口最多就是一分钟。

一次付费会话是两笔交易:

  1. open_session(worker, price, deposit) — 用户的 USDC 从自己的代币账户进入托管 vault,
  2. settle(minutes) — 由 worker 签署:99% 进入它的可提取余额,1% 进入金库。用户端接着 关闭会话以取回余额;claim 会在最后一次结算十分钟后付款给 worker。

报价为 0 时完全不经任何会话即提供服务,这就是为什么免费的 worker 可以跑在一台完全 没有 USDC 的机器上。

运营者接口​

  • 面板 — 插件在 DeepSeek Harness 中的自有 UI:模型、价格、钱包、提取、付款、手动 worker。
  • 状态服务器 — 127.0.0.1 上的本机 HTTP 接口,使用 47821–47826 中第一个空闲的端口, 供面板与 client adapter 使用。
  • Seed admin — seed VM 上另一个独立的控制台,位于 Caddy 之后的 /admin,读取 seed 统计 与程序的账户。它不持有任何钱包密钥,也不移动任何资金。

刻意不存在的东西​

  • 没有代币、没有质押、没有信用分数代币。
  • 没有 orchestrator 服务器、没有提示词数据库。
  • 没有自动内容过滤——协议没有在 worker 看到提示词之前检查它的 hook。
  • 没有链上价格预言机:费率是 worker 公布的一个数字,由用户决定它值不值得付。