架构

ANet 由五个仓库组成:一个纯协议库,三个使用它的应用,一个用真实线协模拟被控硬件的试验场。 本页说明这五个仓各自负责什么、依赖只能朝哪个方向走、跑起来之后是哪些进程在监听哪些地址, 以及一次委派从命令行到证据链的完整路径。

当前版本:ANet 0.1.7 · ANetHub 0.1.6 · ANetCore v0.13.1。

五个仓库

                    ┌──────────────────┐
                    │     ANetCore     │  协议内核,零 I/O,v0.13.1
                    └─────────┬────────┘  CBOR / CID / KEL / TSIR / 效果 / 证据
                              │
        ┌─────────────────────┼─────────────────────┐
        │ import              │ import              │ import
        ▼                     ▼                     ▼
 ┌──────────────┐      ┌──────────────┐      ┌──────────────┐
 │   ANetHub    │◄─C2─►│     ANet     │◄─C1─►│   ANetLink   │
 │    0.1.6     │      │    0.1.7     │      │ 14 adapters  │
 └──────────────┘      └──────────────┘      └──────┬───────┘
  目录 / 中继            daemon / CLI               │ ONVIF · ISAPI
  评价验证 / 结算         十个可插拔模块              │ Modbus · MQTT
  联邦 / 运营面                                     ▼
                                             ┌──────────────┐
                                             │   ANetMock   │  忠实假件
                                             └──────────────┘  零依赖

测试数是顶层测试函数计数(grep -rE '^func Test[A-Z_]' --include='*_test.go'),不含子测试与表驱动用例。 ANetCore / ANetHub / ANetLink 三列与 ANet/docs/DESIGN-zh.md §3 一致;ANet 与 ANetMock 两列 DESIGN 写的是 224 / 43,按当前树数出的是 227 / 45,以本页的数为准(本页写作时没有跑测试套件, 数的是源码里的函数)。

两处口径要注意:ANet 的 227 里有 18 个在 module/shell,只有 -tags shell 才编译得到; ANetLink 的 324 里有 20 个带 //go:build realworld,要对着真设备加 -tags realworld 才跑。 默认 go test ./... 因此分别少跑这些。ANetCore / ANetHub / ANetMock 没有 tag 门控的测试文件。

十四个适配器(ANetLink/adapters/):bacnet ble btmesh can dahua habridge hikvision modbus mqttbridge onvif opcua sim thread zigbee。 sim 是一盏内置虚拟灯,存在的目的是验证 C4 契约、让任何环境都有一台可调用的设备。 Matter 栈不在 adapters/ 下,是顶层的 ANetLink/matter/。

十个可插拔单元:减法 p2p anetlink blackboard org cas service mcp x402 taskboard(默认编进去,-tags no_<name> 去掉),加法 shell(默认不在,-tags shell 才编进去)。其中九个是 ANet/module/ 下的目录;mcp 是例外,它挂在 cmd/anet/mcp.go 与 internal/mcpserv 上,no_mcp 换进 cmd/anet/mcp_stub.go。ANet/module/ 另有两个不带 tag 的不变式守卫 inv1(org 数据不得进 p2p 面)/ inv2(org 数据不得进公开发布面)。 九个减法 tag 在 .github/workflows/ci.yml 的 pluggable 矩阵里逐个单独构建并测试, shell 由 optin job 反向验。

依赖方向:唯一合法形态

三个应用 → ANetCore,永不反向;应用之间永不 import。

   合法                                  非法
   ANet     → ANetCore                   ANetCore → ANet
   ANetHub  → ANetCore                   ANet     → ANetHub
   ANetLink → ANetCore                   ANetHub  → ANet
   ANetMock → (无)                        ANetLink → ANet

为什么这条是硬的

三代实现的教训写在 ANet/docs/CONTRACTS-zh.md §0:v1 死于耦合,v3 死于没有合同, oss-v0.1 证明减法产品成立但减法靠 fork。anet4 的唯一命题由此而来:

让"裁剪"从 git 操作变成构建配置。一套代码,N 种发行版。

这条命题直接压在依赖方向上。可插拔的判据是符号数 —— 一个模块被拔掉,是二进制里没有它 的代码,不是运行时关掉:

go build -o full ./cmd/anet
go tool nm full | grep -c module/x402                      # 必须 > 0
 
go build -tags no_x402 -o lean ./cmd/anet
go tool nm lean | grep -c module/x402                      # 必须 == 0

两个方向都要验。只验 lean == 0 会让一个从未被链接的模块看起来"可插拔"。

如果 ANet 引用了 ANetHub 的包,-tags no_x402 这类裁剪立刻失效:hub 的类型会把它整棵依赖 树拖进每一个 daemon 构建,而这些代码里没有一个 tag 是 daemon 能控制的。同理,如果 ANetCore 反向引用了任何一个应用,那"纯协议库"就不再纯,一个只想验证一张回执的第三方也得把整个 daemon 编进去 —— 那正是 anet verify 刻意避开的:它在解析 daemon 之前处理,因为检查一张回执只需要 一张回执和一份密钥历史,再多要求一样,"任何人都能验证"就变成"任何运行我们软件的人才能验证"。

三个应用同时钉在 ANetCore v0.13.1。三仓跨语言、跨仓库的线协字段由契约测试钉住 (ANet/internal/hubapi、ANetHub/internal/aghub/wirecontract_test.go、 ANetCore/relayauth),否则一侧改个分隔符,另一侧看到的是"一个完全有效的密钥签出了无效签名"。

今天怎么验

cd ANet && go list -deps ./... | grep ANetResearch

对 ANet / ANetHub / ANetLink 三个仓分别跑,结果里除本仓自己的包外只应出现 github.com/ANetResearch/ANetCore/*。

没有 Go 工具链时可以直接看源码,结论一样:

grep -rhoE '"github.com/ANetResearch/[A-Za-z]+' --include='*.go' .

三个仓分别只回两个前缀 —— 本仓自己,加 ANetCore。go.mod 的 require 块也只列 ANetCore 一条 ANetResearch 依赖。

同一条红线在进程内的形态:C1

依赖方向管的是仓与仓,C1 管的是概念不许穿过接缝:daemon 不得知道"设备"这个概念。 ANet/module/anetlink 注册的是一个 provider.CapabilityProvider,交给 daemon 的是能力 id; daemon 解析、调用、记录效果,和对待任何其他 provider 完全一样。它不知道背后是一台摄像机、 一个 Modbus 寄存器,还是一个 shell 命令。

type CapabilityProvider interface {
	ID() string
	Capabilities(ctx context.Context) ([]string, error)
	Describe(ctx context.Context) (string, error)
	Invoke(ctx context.Context, call Call) (effect.Effect, error)
	Health(ctx context.Context) error
}

Describe 是这个接口上今天还空着的一格:注释说它返回描述对象在本地 CAS 里的 CID,而树里 每一个实现都返回 "" —— 内置模块直接 return "", nil,ANetLink 的 provider 转发 GET /v0/describe,而 ANetLink/northbound/c1serv 对这个路由写死了 {"cid": ""} (源码里标着 DeviceCatalog CAS object: later)。接口形状定了,CAS 目录还没有成为描述的载体, ANet/docs/DESIGN-zh.md §4 也是这么记的。

同一条线也画在传输上:module/p2p 是一个客户端,对 daemon 呈现为一个普通的 module.Transport,daemon 学不到 peer id、multiaddr 或 pubsub topic。

进程与端口

一个完整部署最多是六个进程:anet daemon、anetpeer、anetlinkd、anet-hub、 anet-hub-admin,加上按需被 IDE 拉起的 anet mcp。大多数节点只跑第一个。

下表按监听面列,不完全等于进程:第二行的 x402 兑付口不是独立进程,是 daemon 里的 第二个监听器;anet mcp 走 stdio,不出现在表里。

anet mcp 走 stdio,由 Claude Code / Cursor 这类客户端启动,不开任何端口,会话结束即退出。

几处容易读错的地方

daemon 自己不开 p2p 端口。 监听对等连接的是 anetpeer 进程。这是刻意的:libp2p 栈会把 一千多个模块的依赖树拖进 go.mod,而 build tag 只能从二进制里去掉代码,永远去不掉 go.mod 里的依赖 —— 每次构建仍要解析它,CI 仍要下载它,供应链审计仍要覆盖它。

anetpeer --socket run/a/peer.sock --peer run/a/wire.sock --rendezvous run/rv

--rendezvous 收两种值:一个共享目录,或一个 hub URL。目录形态下 anetpeer 自己写条目, 两台机器没有共享目录就用不上;hub 形态下发布地址的是 daemon(anet p2p-advertise), 因为发布是一句关于身份的签名陈述,而 anetpeer 刻意不持有密钥 —— 它是替别人转发流量的那个进程。 hub 侧 POST /agents/{aid}/p2p 用 relayauth 挑战验签后才收,anetpeer 只读 (GET /agents/{aid}/p2p,查不到时按对方的 home hub 再问一跳,只一跳),答案缓存一分钟。

无论哪种形态,都没有 NAT 穿透、没有中继、没有会合点之外的发现:对端必须是可直接拨通的。 这是 ANet/tools/anetpeer/main.go 自己写明的缺口。(该文件的包注释仍写着"会合点还是一个共享 目录",没有跟上 hub 形态的加入 —— 以 --rendezvous 的 flag 说明与 isURL 分支为准。)

控制面只有 bearer token 保护,明文 HTTP。 control_addr 字段的定义处 (ANet/internal/daemon/config.go)写得很直白:除非你在前面放了 TLS 加鉴权, 否则它必须留在 127.0.0.1。29 条 API 路由全部在 token 之后; /console、/ping、/attachment 与根路径重定向在 token 之外 —— 浏览器导航发不出 Authorization 头,能这么做的前提就是只监听回环。

同一台机器可以跑多个身份。 anet id new <name> 从 39811 起向上扫描,分配一个既没被任何 已知身份的配置占用、当下也能绑定的回环端口。每个身份有自己的密钥、数据目录和控制口。

运营面与公网 hub 是两个进程,但共用同一个 hub.db 文件。 两边都以 WAL 模式打开、 15 秒 busy timeout。运营面的读不受限,写只有两个动作(改 guest 配额、删注册),其余变更都 属于公网 hub 自己那套签名挑战 API。注册删除还有速率上限:每分钟最多 5 次。

一次委派的完整数据流

以最常见的路径为例:两个节点注册在同一个 hub 上,没有 p2p,不涉及付费。

anet delegate <provider-aid> "复审这个 PR 的并发安全"

POST /relay/send
{ "to_aid": …, "from_aid": …, "kind": "delegate",
  "interaction_id": …, "payload": "<base64>" }

anet inbox --pending
anet thread <interaction_id>
anet message <interaction_id> "补充:重点看 worker 池的关闭路径"

anet end <interaction_id>          # 提议结束
anet accept-end <interaction_id>   # 对方接受

Receipt {
  InteractionID   本次交互 id
  RequesterAID    请求方
  ProviderAID     提供方(签名者)
  RequestCID      请求方那份 TaskDoc 的 CID
  ResultCID       转录本的 CID
  CompletedAt     完成时刻
}

anet results

anet review <interaction_id> 5 "找到了两个真问题"

hub 看得到什么、看不到什么

x402 付费路径同理:hub 只卖门票,不代理内容。买家在 GET /x402/resource/{aid}/{capability} 未付款拿到 402,付款后拿到一张 voucher,拿着它直接找提供方的兑付口。 hub 全程见不到请求参数,也见不到结果。

存储

daemon 侧

数据目录默认 ~/.anet,环境变量 ANET_DATA_DIR 覆盖;目录权限 0700(里面有私钥)。

跨进程协调放在 /tmp/anet-<uid>/(固定路径,不走 $TMPDIR,按 uid 隔离、0700): daemon.json 是单 daemon 指针,daemons/ 每个运行中的身份一个条目。这两样是 daemon 启动时写、退出时删的运行时状态,删了不影响任何持久数据。

hub 侧

数据目录由 --data 指定,默认 ./.anet-hub。

运营面侧

anet-hub-admin --data 下是 admin.db 与 datasets/:运营面自己的状态、审计记录 (每一次变更动作的 who/what/when)、统计快照与数据集归档。它另外用 --hub-data 打开公网 hub 的 hub.db,从不创建也从不迁移那个库。

这两个 flag 的默认值是 /data/projs/anet-hub/admin 与 /data/projs/anet-hub/data —— 一台特定机器的部署路径被写进了 flag 默认值。对别的部署这个"默认"没有意义,两个都得显式给。 anet-hub 的 --data 默认 ./.anet-hub 是相对路径,没有这个问题。

anet-hub --addr :8088 --data ./.anet-hub
anet-hub-admin --addr 127.0.0.1:8078 --hub-data /data/projs/anet-hub/data --data /data/projs/anet-hub/admin

已知缺口

按影响排序,每条给位置、行为、影响、发现方式。

接下来读什么