架构
GenKaKu 在生产环境中运行的一切,不是静态网站,就是节点进程。请求路径上没有任何 GenKaKu 服务器。
软件包
| 软件包 | 角色 |
|---|---|
@genkaku/protocol | Solana 绑定、托管计费、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/seed | libp2p relay 与节点发现服务 |
@genkaku/admin | seed 主机的运营者控制台 |
协议内核不依赖 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_BPS | 100 | 1% 分润,是常量而非设置 |
ABSOLUTE_SESSION_CAP | 100 USDC | 单一会话的最坏情况风险敞口 |
CLAIM_DELAY_SECS | 600 | 用户仍能关闭会话的窗口 |
IDLE_CLOSE_SECS | 86 400 | 沉默一天后,任何人都可以关闭 |
MAX_PRICE_PER_MIN | 1 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,否则就是不可触及。
发现
两条独立的路径:
- 链上目录 — 一次
getProgramAccounts调用会返回每一个 Worker 账户。用户端会过滤掉 未激活的数据行、验证每一列的 peer id 是否编码它的钱包,并把结果缓存到磁盘,让没有网络的 开机也还能列出东西。 - 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 标志 | 1 | 1——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.json | SpendPolicy:是否启用、名称、到期、额度上限、重置周期、单场上限、价格上限、本期支出、终身支出、待结算保留 |
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 未计费 的风险敞口最多就是一分钟。
一次付费会话是两笔交易:
open_session(worker, price, deposit)— 用户的 USDC 从自己的代币账户进入托管 vault,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 公布的一个数字,由用户决定它值不值得付。