教程七:把真实设备接进来

场景与前置条件

你有一台机器连着真实设备:一台 Modbus PLC、一根 Zigbee 协调器棒、一个已经跑着的 Home Assistant、几台 IP 摄像头。你想让网络另一端的 agent 能调用它们,并且拿回的 不是"我发了命令",而是可核对的效果记录。

这一页做三件事:先在一台机器上把 ANetLink 单独跑通(不需要 daemon,不需要 hub), 再接一台真实设备,最后把它接进 anet daemon,让另一台机器经 hub 委派它。

开始之前需要:

• 一台装了 Go 1.26.6+ 的机器(go.mod 声明 go 1.26.6)。ANetLink 只能从源码构建 —— 仓库里既没有发布脚本也没有 release workflow,.github/workflows 下只有 ci.yml。 CGO_ENABLED=0,无需 C 编译器。
• 一个 anet daemon(第三步才用到)。版本 0.1.7,一行安装见 安装。
• 第三步还需要另一台装了 anet 的机器作为调用方,两边都能出站访问同一个 hub。 本页用官方 hub https://hub.agentnetwork.org.cn。

ANetLink 是什么

ANetLink 是 ANet 面向物理世界的窄腰。它南向说各种设备协议,北向只暴露一个能力面。

三个模型撑起这件事:

DeviceProfile —— 一台设备"能做什么"的机器可读描述,是内容寻址的 CoreDet-CBOR 对象,有稳定 CID。它由三部分组成:

Effect —— 每次调用返回一个效果,状态与度量严格分离。这是 ANetLink 的诚实核心: sdk.EffectBuilder 在 Verified() 没有配套的观测(Metric() 的度量,或 Snapshot() / StreamURI() 的制品)时,Build() 自动降级为 UNVERIFIED。适配器在类型层面无法假报 OK。runtime 再钳一道:MaxTrust < V2 的设备,即使适配器声称 OK 也强制降为 UNVERIFIED。信任只能钳、不能抬,适配器和 quirk 都无权抬高。

Adapter / Backend —— 适配器说一个协议族,实现 C4 合同;一个适配器可以有多个后端, 启动时按优先序探测。

北向两个消费口,同一批设备与效果:MCP(给 Claude / IDE)与 C1(给 anet daemon)。

双后端制:探测优先,永远兜底

设计纪律写在 sdk/probe.go 的 Select 里:

• 有 backend_override 时用指定的后端,但探测仍然必须通过 —— 强制指定却探测失败 是配置错误,启动即报,不静默降级;
• 没有 override 时按声明顺序探测,取第一个可用的;
• 全部不可用时,错误信息里带每个后端各自的失败原因,而不是一句"不可用"。

意图是:宿主设施(已装的 BlueZ、已跑的 OTBR、已跑的 zigbee2mqtt 或 Home Assistant) 活着就骑上去,不活着就落到自研兜底路径,永远都要兜底。

14 个适配器与它们的 build tag

适配器全部是编译期插件,注册在 cmd/anetlinkd/plugin_<name>.go 里。有两套 tag 约定, 用哪一套本身说明了适配器的性质。

减法 tag(默认编入,-tags no_<name> 去掉) —— 对本地网络讲开放标准、不依赖发行版 之外的东西:

加法 tag(默认不编入,-tags <name> 才有) —— 经厂商 HTTP 接口触达设备、要持有凭据:

方向反过来的理由与 anet 的 shell tag 一致:两种 tag 写错的代价不对称。减法 tag 漏了, 是某人想去掉的模块没去掉;加法 tag 漏了,是一个没人启用过的攻击面进了所有构建。

另有一个加法 tag adap,是编译期之外的逃生口:经 UDS 托管一个不在本仓构建的 C4 适配器(可以是别的语言写的)。一个 socket 一个适配器,不做复用。

# 默认发行版(无摄像头、无厂商接口)
CGO_ENABLED=0 go build -o anetlinkd ./cmd/anetlinkd
 
# 安防网关:全部摄像头能力
CGO_ENABLED=0 go build -tags onvif,hikvision,dahua -o anetlinkd ./cmd/anetlinkd
 
# 边缘盒子:裁掉 mqtt / HA / sim
CGO_ENABLED=0 go build -tags no_mqtt,no_ha,no_sim -o anetlinkd-min ./cmd/anetlinkd

配置里写了没编入的适配器,启动响亮报错,并且指向正确的修法 —— 加法的说 "用 -tags onvif 重新构建",减法的说"是不是带了 no_x"。裁掉的能力绝不静默消失。

第一步:单机跑通

git clone https://github.com/ANetResearch/ANetLink.git
cd ANetLink
CGO_ENABLED=0 go build -o anetlinkd ./cmd/anetlinkd
./anetlinkd --demo

2026/09/03 17:49:35 vendor corrections loaded: 7 quirk(s)
2026/09/03 17:49:35 adapters compiled+configured: sim
2026/09/03 17:49:35 device sim/lamp-1 online=true trust=T4 profile=bafyreifz4fnvfxulvtxllo3nkahcrbpeyklonfpbahl6ocnx25s2quot5i
demo: light.onoff on=true → status=OK verifiable=true metrics=map[power_state:1]

./anetlinkd --mcp

第二步:接一台真实设备

./anetlinkd --scan

found 0 device(s)

no devices discovered.
  (the compiled-in adapters either need configuration first —
   a coordinator port, a broker URL, a Home Assistant token —
   or their networks are empty.)

./anetlinkd --scan --scan-out config.json

{
  "backend_override": { "thread": "host-otbr" },
  "quirk_dir": "/etc/anetlink/quirks.d",
  "adapters": {
    "sim": { "enabled": false },
 
    "modbus": {
      "devices": [
        {
          "id": "plc-1",
          "addr": "192.168.1.50:502",
          "unitid": 1,
          "vendor": "acme",
          "model": "rtu-8",
          "caps": [
            { "id": "switch.onoff", "kind": "coil", "address": 3, "access": 6 },
            { "id": "sensor.temperature", "kind": "holding", "address": 7,
              "access": 4, "scale": 0.1, "unit": "°C" }
          ]
        }
      ]
    },
 
    "homeassistant": {
      "url": "ws://homeassistant.local:8123/api/websocket",
      "token": "长期访问令牌"
    }
  }
}

./anetlinkd --config config.json --pair 60s

./anetlinkd --config config.json --mcp

第三步:接进 ANet

到这一步为止,设备只对本机可见。接上 daemon 之后,它们变成这个节点在 hub 上可被 委派的能力。

./anetlinkd --config config.json --c1-socket /run/anetlink.sock

GET  /v0/health        → 204
GET  /v0/capabilities  → {"capabilities": ["light.onoff@sim/lamp-1", ...]}
GET  /v0/describe      → {"cid": ""}          # DeviceCatalog CAS 对象未做,当前恒为空
POST /v0/invoke        {"capability":"...","args":{...},"call_id":"...","caller_aid":"..."}
                       → {"status":"...","metrics":{...},"message":"...","evidence":{...}}

curl -s --unix-socket /run/anetlink.sock http://anetlink/v0/capabilities
curl -s -o /dev/null -w 'health=%{http_code}\n' --unix-socket /run/anetlink.sock http://anetlink/v0/health
curl -s --unix-socket /run/anetlink.sock -X POST -H 'Content-Type: application/json' \
  -d '{"capability":"light.onoff@sim/lamp-1","args":{"on":true}}' \
  http://anetlink/v0/invoke

{"capabilities":["light.onoff@sim/lamp-1"]}
health=204
{"status":"OK","metrics":{"power_state":1}}

anet version

anet 0.1.7 (commit unknown, built unknown)
modules: anetlink,blackboard,cas,mcp,org,p2p,service,taskboard,x402

go tool nm ./anet | grep -c module/anetlink   # 默认构建 > 0
go build -tags no_anetlink -o /tmp/anet-lean ./cmd/anet
go tool nm /tmp/anet-lean | grep -c module/anetlink   # 必须 0

{
  "modules": {
    "anetlink": {
      "socket": "/run/anetlink.sock",
      "timeout_s": 5
    }
  }
}

anet stop
anet up

anet hub-register https://hub.agentnetwork.org.cn --name lab-gateway
anet status

anet find --cap 'light.onoff@sim/lamp-1'
anet find --cap 'light.*'

anet delegate <provider-aid> --capability 'light.onoff@sim/lamp-1' --args '{"on":true}'
anet results

{
  "capability": "switch.onoff@modbus/plc-1",
  "status": "OK",
  "verifiable": true,
  "metrics": { "switch_onoff": 1 },
  "evidence": {
    "requested": "switch.onoff=true",
    "protocol": "modbus",
    "native_ack": true,
    "observed_state": "true",
    "latency_ms": 12,
    "verify_trust": 2,
    "auth_trust": 1
  }
}

C1 红线:能力 id 里带着设备,daemon 不知道设备是什么

light.onoff@sim/lamp-1 这个 id 的形状是 <能力>@<适配器>/<设备>。它只在 ANetLink 一侧铸造和解析 —— northbound/c1serv 的 CapabilityID 与 ParseCapabilityID 是全 系统唯一认识这个形状的两个函数。

过了 socket 之后,它在 daemon 眼里是一个不透明字符串:

• provider/anetlink 只负责把它放进 HTTP body;
• provider.Registry 把它当 map 的键;
• internal/daemon/capability.go 把它写进 TaskDoc 的 Requires,签名、投递、记账。

这几层里没有一行代码去看 @ 右边是什么。daemon 因此不需要有"设备"这个概念, 也不需要有"设备表""在线状态""配对窗口"。它只知道"某个 id 可以被调用,调用会返回一个 效果"。

这条红线的实用后果是:ANetLink 可以长出第 15、第 20 个适配器,daemon 一行都不用改; 而 daemon 也不会慢慢长成第二个设备管理系统。同一道门里还进来别的东西 —— cas、shell、service、taskboard 的能力,走的是同一个 provider.CapabilityProvider 接口。

诚实效果:UNVERIFIED 不是失败

设备这一侧最容易出错的地方,是把"我发了命令"当成"我确认了效果"。ANetLink 用两条机制 挡这件事:

结构上挡 —— EffectBuilder.Verified() 没有配套的度量或制品时,Build() 降级为 UNVERIFIED。适配器作者写不出一个没有观测支撑的 OK。

运行时钳 —— runtime 对 MaxTrust < V2 的设备把 OK 强制降为 UNVERIFIED。 云 API 封顶在 V1(只有传输层 ack),所以任何走厂商云的路径都不可能报出可验证的成功。

各适配器如实标注自己能验证到哪一级:

摄像头这一族有自己的红线,因为它们是第一类"结果不是数字"的设备:

• ptz.move 的速度契约统一为 [-1,1],厂商标度在适配器内部换算(海康 [-100,100]、 大华离散方向码加 1–8 速度)。调用方不需要知道这是谁家的相机。
• 每次 move 都是有界的,发完必停。ONVIF 的 continuous move 不停就一直转。
• 位置回读是 PTZ 的验证手段。相机到机械限位时会照常 ack 却纹丝不动;只信 ack 就会 报告一次没发生的转动。这种情况报 UNVERIFIED 并说明"位置未变"。
• verify_stream 打开后,取流会真做一次 RTSP DESCRIBE 拿到 SDP 才算验证通过。 GetStreamUri 只是返回一个字符串,相机会为一条编码器没起来的流照样发 URI。

五种效果状态的完整语义见效果状态参考。

已知缺口

这些是当前代码的实际状态,不是路线图上的措辞。

Matter 栈没有接成适配器。 matter/ 下九个包齐备(TLV、mDNS 发现、SPAKE2+、PASE、 帧、exchange/MRP、加密会话、交互模型、入网序列),SPAKE2+ 对 RFC 9383 与 connectedhomeip 官方向量双钉,PASE 与一只 matter.js 虚拟灯完成了完整握手、双方导出 同一会话密钥(那是真实的 Matter 协议实现,但不是硬件设备;硬件握手没有记录)。但 cmd/anetlinkd/ 下没有 plugin_matter.go —— 这套栈今天还不能作为设备出现在 runtime 的设备表里, 也不会出现在 --scan 的结果中。

厂商云适配器为零。 adapters/ 下 14 个适配器全部走本地网络或局域网内的厂商 HTTP 接口。没有任何一个适配器接厂商云(小米、涂鸦、Aqara 之类)。这意味着一批只提供 云 API 的设备目前接不进来 —— 并且即使接进来,它们的效果也封顶在 V1,永远报不出可验证 的 OK。

摄像头的 PTZ / 事件 / 抓拍没有真机验证记录。 L0 假件覆盖了全部路径(真 SOAP 与 ISAPI/CGI 线格式、真 multipart 事件流),L1 用 onvif-server 覆盖发现、能力投影与 RTSP 探测 —— 但 onvif-server 只实现 Profile S,PTZ、事件、JPEG 抓拍这三样必须真机。海康 ISAPI 与 大华 CGI 是厂商私有协议,不存在模拟器,整条路径都只能在 L2 跑。相应的 -tags realworld 测试写好了(TestRealPTZ、TestRealSnapshotIsRealBytes、 TestRealStreamProbe),等的是把 ANETLINK_HIKVISION_ADDR 之类指向真机。

已经验证过的那部分要一并说清楚:ANetLink 的 ONVIF 适配器驱动 ANetMock 里的模拟海康球机 跑通过 —— 绝对定位经位置回读确认(pan 0 → 0.6)、抓拍拿到 2391 字节真 JPEG 并内容寻址、 RTSP DESCRIBE 得到 H265。这三个数字取自 ANetMock/README.md 的自述,本页没有重跑这条链路。 ANetMock 说真实线协议且状态闭环,但它不是真机;两者不能互相替代。

自动发现覆盖 5/14。 见上文第二步的清单。其余适配器要手写地址与寄存器/节点映射。

排查

更多见排查手册。

接下来