Bookworm Admin b7a8e29d21 release: v6.7.0 - OTA E2E test release

- VERSION file as authoritative version source
- export.mjs reads VERSION with package.json fallback
- bw-ota.ps1 DryRun mode for safe testing
- auto-setup.ps1 bumped to v3.2.0 (Phase 8 OTA)

2026-04-27 17:59:44 +08:00

38 KiB

Raw Permalink Blame History

AI Universal Control Plane

架构白皮书 v1.0

让本地 AI 大脑统一控制所有可连接设备：Windows / Linux / macOS / Android / PLC / SCADA / HMI / 嵌入式硬件 / 网络设备 / 智能家居

字段	内容
版本	v1.0
日期	2026-04-25
作者	Bookworm Architecture Team
状态	Draft - 待 PoC 验证
目标读者	系统架构师 / 工程主管 / IT 决策层

1. 执行摘要

本架构以本地 Bookworm 智能助手 (Claude Opus 4.7) 为决策大脑, 通过分层 MCP (Model Context Protocol) 协议栈, 将企业范围内一切可连接设备统一为 AI 可调用的"工具集"。

核心价值主张：

统一意图入口：用户用自然语言指挥任何设备 ("把三号车间 12 号产线降速到 60%")
跨设备编排：一句指令触发跨 N 台设备的工作流 ("早班巡检：读 PLC + 摄像头识别 + 写报表 + 发邮件")
协议无关：底层封装 OPC UA / Modbus / SSH / ADB / SCPI / MQTT 等异构协议, AI 调用层完全统一
本地优先：核心 AI 运行在本地, 数据不必上云, 适合工业场景的合规与延迟要求

关键设计决策：

决策层 vs 执行层物理分离 → 大脑可单点部署, 边缘代理无状态
MCP 作为唯一适配协议 → 新设备接入只需写 MCP server, 无需改大脑
设备注册表是知识层核心 → 不是 IP 列表, 是"能力图谱"
安全联锁硬件优先 → AI 永远不能绕过物理急停

预期成本与收益（中型工厂场景, 30 设备）：

项目	成本
一次性开发	60 人日
Edge Agent 部署	30 设备 × 1 小时
服务器硬件 (本地大脑)	1 台中端 PC, ~12k RMB
每月运维	约 0.5 人日
节省工时	估算 40-60% 重复运维操作自动化

2. 愿景与范围

2.1 愿景

"让企业里每一台可连接设备, 都成为本地 AI 大脑的可调用器官; 用户只需用自然语言表达意图, AI 自动决策、跨设备协作、安全执行。"

2.2 范围（v1.0 覆盖设备类别）

类别	子类	协议/接入方式
桌面/服务器	Windows	OpenSSH + Edge Agent (UIAutomation/COM)
	Linux	SSH + Edge Agent (D-Bus/CLI)
	macOS	SSH + Edge Agent (AppleScript/Accessibility)
移动设备	Android	ADB / Scrcpy / Termux + MCP / UIAutomator2
	iOS	XCUITest (越狱) / Shortcuts API (受限)
工业控制	PLC	OPC UA / Modbus / S7 / EtherNet-IP
	SCADA	OPC UA / SQL / REST API
	HMI	RustDesk + Vision / 厂商 API
嵌入式/电子	ESP32/Arduino/STM32	USB Serial / MQTT / WiFi
	Raspberry Pi/Jetson	SSH + Edge Agent
	FPGA / JTAG	OpenOCD CLI
	PCB 测试仪器	SCPI over LXI / GPIB / VISA
网络设备	路由器/交换机	SSH + NETCONF / SNMP
	防火墙/AP	RESTCONF / 厂商 API
智能家居/IoT	Matter / Thread	python-matter-server
	Zigbee	Home Assistant + MQTT
	Z-Wave	zwave-js-server
音视频	摄像头/NVR	RTSP / ONVIF
	麦克风/扬声器	Edge Agent (本地 OS API)

2.3 非目标（v1.0 不包含）

❌ 替代 SCADA / DCS / MES 等专业平台
❌ 实时控制（< 10ms 周期, 留给 PLC 自身）
❌ 安全关键执行器的自主决策（医疗 / 化工功能安全 SIL3+）
❌ 多 AI 模型联邦学习（v2.0 考虑）

3. 设计原则

P1. 大脑唯一, 边缘无状态

决策只在本机大脑发生; Edge Agent 只是 API gateway, 重启后零状态恢复。

P2. 协议归一为 MCP

所有设备能力通过 MCP server 暴露; AI 看到的永远是统一的 "tool" 接口, 不感知底层是 SSH 还是 ADB 还是 Modbus。

P3. 能力优先于地址

设备注册表索引"能力"而非 IP; 用户说"读温度", AI 自动找有 read_temperature 能力的设备。

P4. 安全联锁硬件化

写入操作分级 (READ_ONLY / SOFT_PARAM / HARD_ACTION); HARD_ACTION 必须双因子 + 物理钥匙开关同时满足。

P5. 失败显式可见

MCP 调用必须返回结构化结果 + 时间戳; AI 不允许"猜测"未确认的状态; 错误必须带可执行的修复建议。

P6. 增量部署

新设备接入不影响已有设备; 单台 Edge Agent 故障不影响其他设备控制。

P7. 审计强制

每次 AI 调用 → 设备执行的链路必须可溯源 (traceId 贯穿); HARD_ACTION 全量录像或日志归档至少 90 天。

4. 系统架构

4.1 总体分层

╔══════════════════════════════════════════════════════════════╗
║               L5: 用户交互层 (User Layer)                   ║
║   自然语言 / 语音 / 仪表盘 / Slack / 微信 / Web UI           ║
╚══════════════════════════════════════════════════════════════╝
                            ↕
╔══════════════════════════════════════════════════════════════╗
║               L4: 大脑层 (Brain Layer)                      ║
║   ┌─────────────────────────────────────────────────────┐   ║
║   │  Claude Opus 4.7 + Bookworm Skills + Agents         │   ║
║   ├─────────────────────────────────────────────────────┤   ║
║   │  设备注册表 (Device Registry)                       │   ║
║   │  能力图谱 (Capability Graph)                        │   ║
║   │  操作策略 (Policy Engine)                           │   ║
║   │  审计日志 (Audit Log)                               │   ║
║   └─────────────────────────────────────────────────────┘   ║
╚══════════════════════════════════════════════════════════════╝
                            ↕
╔══════════════════════════════════════════════════════════════╗
║               L3: 适配层 (Adapter Layer)                    ║
║   ┌─────────────────────────────────────────────────────┐   ║
║   │  MCP Server Cluster (本地)                          │   ║
║   │   ├─ ssh-mcp        - 通用 SSH 通道                 │   ║
║   │   ├─ adb-mcp        - Android 控制                  │   ║
║   │   ├─ opcua-mcp      - 工业控制                      │   ║
║   │   ├─ modbus-mcp     - PLC/仪表                      │   ║
║   │   ├─ scpi-mcp       - 测试仪器                      │   ║
║   │   ├─ mqtt-mcp       - IoT/消息总线                  │   ║
║   │   ├─ vision-mcp     - 视觉识别                      │   ║
║   │   └─ ...                                            │   ║
║   └─────────────────────────────────────────────────────┘   ║
╚══════════════════════════════════════════════════════════════╝
                            ↕
╔══════════════════════════════════════════════════════════════╗
║               L2: 传输层 (Transport Layer)                  ║
║   Tailscale (mesh VPN) / WireGuard / MQTT Broker            ║
║   TLS 1.3 / mTLS 双向证书 / Vault 凭证管理                  ║
╚══════════════════════════════════════════════════════════════╝
                            ↕
╔══════════════════════════════════════════════════════════════╗
║               L1: 边缘层 (Edge Layer)                       ║
║   每台被控设备本地运行的 Edge Agent / 协议端点              ║
║   ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       ║
║   │ Win Agent│ │Linux Agt │ │macOS Agt │ │Android Tx│       ║
║   └──────────┘ └──────────┘ └──────────┘ └──────────┘       ║
║   ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       ║
║   │ PLC OPCUA│ │ HMI VNC  │ │ESP32 MQTT│ │Scope SCPI│       ║
║   └──────────┘ └──────────┘ └──────────┘ └──────────┘       ║
╚══════════════════════════════════════════════════════════════╝
                            ↕
╔══════════════════════════════════════════════════════════════╗
║               L0: 物理层 (Physical Layer)                   ║
║   工业以太网 / WiFi / 蓝牙 / 串口 / 现场总线 / 蜂窝          ║
║   ★ 物理急停按钮 / 安全 PLC / 联锁硬件                      ║
╚══════════════════════════════════════════════════════════════╝

4.2 关键架构图：单次指令的端到端链路

[用户]
  │ "看下三号车间温度并截屏存档"
  ▼
[L5: Claude Code 终端]
  │
  ▼
[L4: Bookworm 大脑]
  │  1. 意图解析 → 需要 read_temperature + screenshot
  │  2. 查注册表 → device:line-12 (PLC), device:hmi-3 (Win)
  │  3. 策略检查 → READ_ONLY 操作, 直接放行
  │  4. 编排 → 并行调用 [opcua.read, win.screenshot]
  ▼
[L3: MCP Servers]
  │  opcua-mcp.read_node(line-12, ns=2;s=Temp)
  │  ssh-mcp.exec(hmi-3, screenshot.ps1)
  ▼
[L2: Tailscale Mesh]
  │  加密 + NAT 穿透
  ▼
[L1: Edge Layer]
  │  PLC line-12 ←→ OPC UA endpoint
  │  Windows hmi-3 ←→ Edge Agent
  ▼
[结果聚合]
  │  Temperature: 78.3°C
  │  Screenshot: \\storage\archive\2026-04-25-1830.png
  ▼
[L4 → L5] 返回用户 + 写入 Audit Log

5. 设备分类与接入方案

5.1 桌面/服务器类

Windows

能力	实现
Shell 命令	OpenSSH Server + PowerShell
UI 自动化	pywinauto / FlaUI / windows-mcp
COM 对象 (Office)	mcp-com-server
屏幕截图	Edge Agent (GDI+)
文件操作	SSH/SFTP
服务管理	sc.exe / Get-Service

关键坑: SSH 默认 Session 0 看不到 GUI → 必须用任务计划在用户登录会话起 Edge Agent (端口 8901, 仅 Tailscale 网内访问)。

Linux

能力	实现
Shell	SSH (默认)
GUI 自动化	xdotool + scrot (X11) / ydotool (Wayland)
系统服务	systemd / D-Bus
容器编排	Docker / Podman API

macOS

能力	实现
Shell	SSH (启用 Remote Login)
UI 自动化	AppleScript / osascript / Accessibility API
屏幕截图	screencapture

关键坑: 13.0+ 屏幕录制权限弹窗 → 首次手动授权 + 系统设置永久允许。

5.2 移动设备类

Android（重点扩展）

Android 接入有 3 种模式, 按权限/能力递增：

模式 A：ADB 网络模式（最常用）⭐

适用：开发机、工程机、测试机、商用 Android 设备

[本机 adb-mcp] ──Tailscale──> [Android 设备 ADB-over-WiFi:5555]

配置步骤：

# Android 11+ 无线调试 (设备本地一次性)
设置 → 开发者选项 → 无线调试 → 配对(显示 IP:PORT + 配对码)

# 本机 PC 配对一次
adb pair <IP>:<PORT>
adb connect <IP>:5555

MCP 能力包装：

# mcp-servers/android-adb/server.py
from mcp import Server
import subprocess

mcp = Server('android-adb')

@mcp.tool()
def list_devices() -> list:
    """列出所有 ADB 连接的 Android 设备"""
    out = subprocess.check_output(['adb', 'devices', '-l'])
    return parse_devices(out)

@mcp.tool()
def shell(device: str, cmd: str) -> str:
    """在指定 Android 设备上执行 shell 命令"""
    return subprocess.check_output(['adb', '-s', device, 'shell', cmd]).decode()

@mcp.tool()
def install_apk(device: str, apk_path: str) -> bool:
    """安装 APK"""
    subprocess.run(['adb', '-s', device, 'install', '-r', apk_path], check=True)
    return True

@mcp.tool()
def tap(device: str, x: int, y: int):
    """模拟点击屏幕坐标"""
    subprocess.run(['adb', '-s', device, 'shell', 'input', 'tap', str(x), str(y)])

@mcp.tool()
def type_text(device: str, text: str):
    """输入文本"""
    subprocess.run(['adb', '-s', device, 'shell', 'input', 'text', text])

@mcp.tool()
def screenshot(device: str, save_path: str) -> str:
    """截屏保存到本机"""
    subprocess.run(['adb', '-s', device, 'exec-out', 'screencap', '-p'],
                   stdout=open(save_path, 'wb'))
    return save_path

@mcp.tool()
def screen_record(device: str, seconds: int, save_path: str) -> str:
    """录屏"""
    subprocess.run(['adb', '-s', device, 'shell', 'screenrecord',
                    f'--time-limit={seconds}', '/sdcard/_rec.mp4'])
    subprocess.run(['adb', '-s', device, 'pull', '/sdcard/_rec.mp4', save_path])
    return save_path

@mcp.tool()
def logcat(device: str, tag: str = None, lines: int = 100) -> str:
    """读取应用日志"""
    args = ['adb', '-s', device, 'logcat', '-d', '-t', str(lines)]
    if tag: args += ['-s', tag]
    return subprocess.check_output(args).decode()

@mcp.tool()
def list_packages(device: str) -> list:
    """列出已安装应用"""
    out = subprocess.check_output(['adb', '-s', device, 'shell', 'pm', 'list', 'packages'])
    return [l.replace('package:', '') for l in out.decode().splitlines()]

模式 B：Termux + Node MCP（深度集成）

适用：自有/管理的 Android 设备, 想跑 7×24 后台 Agent

[本机大脑] ──SSH──> [Android Termux SSH 服务器] ──> [本地 Node MCP Server + Termux:API]

优势：

真正的 Linux 环境（apt 装 nodejs/python/git）
Termux:API 访问 Android 原生 API（摄像头、传感器、通知、TTS、振动、剪贴板、定位、电池）
Termux:Boot 开机自启
无需 root, 但有 root 后能力更强

部署清单：

# 1. F-Droid 装 Termux + Termux:API + Termux:Boot (官方 Play 商店版本已停止维护)
# 2. 在 Termux 里：
pkg install openssh nodejs-lts python git
sshd                          # 启动 SSH
passwd                        # 设密码 (或 ~/.ssh/authorized_keys)
ifconfig                      # 查 IP

# 3. 装 Bookworm Edge Agent
git clone <bookworm-edge-repo>
cd bookworm-edge && npm install
node server.js --port 8901

模式 C：Scrcpy + Vision（视觉兜底）

适用：无法装 Termux/无 ADB 权限的设备 (受控企业设备 / 用户私设)

[本机 askui-vision] ──看──> [本地 Scrcpy Viewer 窗口] ──镜像──> [Android 屏幕]
[本机 input 转发] ──发──> [Scrcpy Viewer] ──控制──> [Android]

Android 特殊场景能力

场景	实现
自动化运营手机店 / 群控	adb-mcp 多设备并发
应用测试 / 自动化 QA	uiautomator2 + MCP wrapper
移动设备 IT 资产管理	批量 logcat / 安装策略
工业 PDA / 扫码枪	Termux + 串口透传
家庭老人手机远程辅助	scrcpy + 视觉 + TTS
抓包分析	tcpdump (root) / Frida

iOS（受限支持）

能力	实现
屏幕镜像	QuickTime / scrcpy-iOS
自动化	XCUITest (开发模式) / Shortcuts URL Scheme
越狱设备	Frida + SSH

5.3 工业控制类

PLC 接入决策树

PLC 品牌 / 系列?
├── 西门子 S7-1200/1500 → 优先 OPC UA (内置), 备选 S7 协议 (snap7)
├── 西门子 S7-300/400   → S7 协议 (snap7)
├── 罗克韦尔 ControlLogix → EtherNet/IP (pycomm3) 或 OPC UA (FactoryTalk Linx)
├── 三菱 FX/Q          → MC 协议 (pymcprotocol)
├── 欧姆龙 CJ/CP       → FINS (omron-fins-py)
├── 汇川 H5U/AC800     → Modbus TCP
└── 其他               → 优先 Modbus TCP, 备选厂商 SDK

SCADA 接入

平台	接入方式
西门子 WinCC Unified	OPC UA + REST API
罗克韦尔 FactoryTalk	OPC UA via Linx Gateway
Inductive Ignition	内置 MQTT / OPC UA / REST
国产组态王 / 力控	OPC DA → KEPServerEX 转 OPC UA
Wonderware InTouch	OPC UA + SQL 后端

5.4 嵌入式/电子类

设备	接入
ESP32 / ESP8266	MQTT (PubSubClient) + OTA
Arduino	USB Serial (pyserial)
STM32	UART / SWD (OpenOCD)
Raspberry Pi	SSH + Edge Agent
Jetson	SSH + Edge Agent + GPU APIs
FPGA (Xilinx/Lattice)	OpenOCD JTAG / 厂商 SDK
PCB ATE 测试仪器	SCPI over LXI/USB (pyvisa)
万用表/示波器/电源	SCPI (Keysight/Rigol/Siglent 通用)

5.5 网络与基础设施

设备	协议
Cisco / H3C / 华为路由交换	SSH + NETCONF/YANG
防火墙 (FortiGate/PaloAlto)	REST API
Wi-Fi AP (Unifi/Aruba)	REST API + SSH
UPS	SNMP
监控摄像头	RTSP + ONVIF
NAS (Synology/QNAP)	SSH + REST API

6. 核心组件详细设计

6.1 大脑 (Brain) 组件

6.1.1 设备注册表 (Device Registry)

存储: SQLite (单机) / PostgreSQL (集群) 访问: 大脑启动时全量加载, 内存索引 + 文件 watch 热更新

Schema:

# devices.yaml
- id: prod-line-12-plc          # 全局唯一 ID
  display_name: 一号车间 12 号产线 PLC
  type: plc
  vendor: siemens
  model: S7-1500
  
  # 网络位置 (可选, 仅当大脑直连时)
  network:
    transport: tailscale         # tailscale / lan / mqtt-broker
    endpoint: opc.tcp://prod-line-12-plc.tail-net:4840
  
  # 边缘代理 (可选, 仅当通过 Edge Agent 间接访问)
  via_agent: edge-floor1-gw      # 引用另一个设备 ID
  
  # 协议描述
  protocol:
    type: opc-ua
    security: SignAndEncrypt
    auth: cert
    cert_id: vault://plc-floor1
  
  # 能力清单 (能力图谱的核心)
  capabilities:
    - id: read_temperature
      type: read
      address: ns=2;s=DB10.Temp
      datatype: float
      unit: celsius
      tags: [temperature, monitor]
    - id: set_speed
      type: write
      address: ns=2;s=DB10.SetSpeed
      datatype: int
      unit: rpm
      range: [0, 3000]
      safety_level: SOFT_PARAM   # READ_ONLY / SOFT_PARAM / HARD_ACTION
    - id: emergency_stop
      type: write
      address: ns=2;s=DB10.EStop
      datatype: bool
      safety_level: HARD_ACTION
      requires: [user_confirm, physical_key, two_engineers]
  
  # 元信息
  meta:
    location: 车间 1 楼 A 区
    owner: 设备部-张工
    criticality: HIGH
    last_audit: 2026-04-20
    sop_link: https://wiki/SOP-line12

6.1.2 能力图谱 (Capability Graph)

将设备注册表升级为可查询的语义图：

能力 "read_temperature"
├── 设备: prod-line-12-plc, lab-thermo-01, hvac-floor1
├── 同义词: 测温度, get temp, 温度读数
└── 上下文: 工业产线 / 实验室 / 楼宇

意图 "三号车间温度异常"
├── 触发设备: workshop-3 范围内所有有 temperature 能力的
├── 关联 SOP: 报警确认 → 通知班长 → 写日志
└── 安全级别: 仅 READ

实现：用 embedding 向量化 + 关键词倒排索引混合检索, AI 调用前先查图谱, 召回 Top-K 设备 + 能力候选。

6.1.3 策略引擎 (Policy Engine)

职责: 决定一个 AI 调用是否被允许执行

# policies.yaml
- name: read-only-anytime
  match:
    capability_type: read
  effect: ALLOW

- name: soft-param-business-hours
  match:
    capability_safety: SOFT_PARAM
  conditions:
    - time_window: "09:00-18:00 weekdays"
    - user_role: ["operator", "engineer"]
  effect: ALLOW
  audit: REQUIRED

- name: hard-action-strict
  match:
    capability_safety: HARD_ACTION
  conditions:
    - user_confirm: true               # AI 不能自动执行
    - physical_key_present: true       # 物理钥匙开关
    - dual_approval: ["engineer", "supervisor"]
    - blackout_period: NOT_IN          # 不在停产/检修禁令期
  effect: ALLOW
  audit: VIDEO_RECORD                  # 全程录像

- name: production-line-blackout
  match:
    device_id_prefix: "prod-line-"
  conditions:
    - blackout_until: 2026-05-01       # 大检修期间禁所有写入
  effect: DENY_WRITE

6.1.4 审计日志 (Audit Log)

每次 MCP 调用追加一行 JSON Lines, traceId 贯穿大脑 → 适配 → 边缘：

{"ts":"2026-04-25T10:30:15Z","traceId":"abc123","actor":"user:janson","intent":"读三号车间温度","tools":["opcua-mcp.read"],"devices":["prod-line-12-plc"],"result":"ok","latency_ms":47}
{"ts":"2026-04-25T10:31:02Z","traceId":"def456","actor":"user:janson","intent":"将12号线降速到60%","tools":["opcua-mcp.write"],"devices":["prod-line-12-plc"],"safety":"SOFT_PARAM","approved_by":"engineer:wang","result":"ok","old_value":2400,"new_value":1800}

90 天热存储 (SQLite/Loki) + 1 年冷归档 (S3/MinIO)。

6.2 适配层 (MCP Servers)

6.2.1 标准化 MCP Server 模板

每个 MCP server 应提供：

list_capabilities() - 自描述支持的能力
health_check() - 探活
execute(capability_id, params) - 统一执行入口
结构化错误码 (E001-DEVICE_OFFLINE, E002-PERMISSION_DENIED, ...)

6.2.2 必需的 MCP Server 清单

优先级	MCP Server	实现栈	工作量
P0	ssh-mcp	Node + ssh2	复用现成
P0	adb-mcp (Android)	Python + adb cli	1 周
P0	opcua-mcp	Python + asyncua	2 周
P0	modbus-mcp	Python + pymodbus	1 周
P0	edge-agent (Win/Linux/macOS)	Node + 平台 API	3 周
P1	scpi-mcp	Python + pyvisa	1 周
P1	mqtt-mcp	Python + paho-mqtt	3 天
P1	vision-mcp	已有 askui-vision	复用
P2	s7-mcp	Python + snap7	1 周
P2	snmp-mcp	Python + pysnmp	1 周
P2	matter-mcp	python-matter-server	1 周
P3	bacnet-mcp	BAC0	1 周
P3	netconf-mcp	ncclient	1 周

6.3 传输层

6.3.1 Tailscale Mesh VPN

职责: 跨网络可达性 + 端到端加密 + 零信任 ACL

关键能力:

MagicDNS: 用 hostname 替代 IP
Tailscale ACLs: 谁能访问谁、走什么端口、什么协议
Subnet Router: Edge Agent 可作为子网网关, 暴露下游 PLC
Tailscale SSH: 内置 SSH (无需密码/密钥)

ACL 示例:

{
  "groups": {
    "group:brain":     ["leesu@example.com"],
    "group:engineer":  ["janson@example.com", "wang@example.com"],
    "group:operator":  ["op-1@example.com"],
  },
  "tagOwners": {
    "tag:plc":         ["group:engineer"],
    "tag:edge-win":    ["group:engineer"],
    "tag:edge-android":["group:engineer"],
  },
  "acls": [
    // 大脑可以访问所有设备
    { "action": "accept", "src": ["group:brain"], "dst": ["*:*"] },
    // 工程师可访问 PLC + Win 边缘 (业务时间)
    { "action": "accept", "src": ["group:engineer"], "dst": ["tag:plc:4840", "tag:edge-win:8901"] },
    // 操作员只读 PLC
    { "action": "accept", "src": ["group:operator"], "dst": ["tag:plc:4840"] }
  ]
}

6.3.2 MQTT Broker (异步消息)

用途: ESP32 / 现场仪表 / 异步事件流

部署: Mosquitto (轻量) 或 EMQX (集群)

6.4 边缘层 (Edge Agent)

6.4.1 通用 Edge Agent 架构

跨平台单二进制 (Node.js + pkg), 组件：

┌────────────────────────────────────────┐
│        Edge Agent (Node.js)            │
├────────────────────────────────────────┤
│  HTTP Server :8901 (本机)              │
│   ├─ /mcp        - MCP 协议端点        │
│   ├─ /health     - 健康检查            │
│   ├─ /metrics    - Prometheus 指标     │
│   └─ /version                          │
├────────────────────────────────────────┤
│  Capability Modules                    │
│   ├─ shell.js     - 执行命令           │
│   ├─ filesystem.js- 文件操作           │
│   ├─ ui-automation.js - GUI 控制        │
│   ├─ screenshot.js                      │
│   ├─ process.js   - 进程管理            │
│   └─ platform-specific/                 │
│       ├─ windows-com.js                 │
│       ├─ linux-dbus.js                  │
│       └─ macos-applescript.js           │
├────────────────────────────────────────┤
│  Auth & Audit                          │
│   ├─ mTLS (Tailscale 内信任)           │
│   └─ 本地 audit.log                    │
└────────────────────────────────────────┘

6.4.2 Edge Agent 部署形态

平台	形态	启动方式
Windows	EXE / MSI	任务计划在用户登录会话起
Linux	systemd service	默认 root, GUI 任务用 user systemd
macOS	launchd plist	LaunchAgent (用户) / LaunchDaemon (系统)
Android (Termux)	shell script	Termux:Boot 开机自启
树莓派	Docker / systemd	推荐 Docker 便于升级

7. 数据流与控制流

7.1 同步控制流 (用户实时指令)

用户  →  大脑  →  策略检查  →  MCP  →  Edge/协议  →  设备
       (NLU)    (Policy)            (Tailscale)
                                                       ↓
用户 ←  大脑 ← 结果聚合 ← MCP ← Edge ← 设备响应

目标延迟: P95 < 2 秒（不含 LLM 推理）

7.2 异步事件流 (设备主动上报)

设备  →  MQTT Broker  →  事件订阅服务  →  规则引擎  →  大脑触发
        (传感器/告警)    (Bookworm Hook)  (匹配)      (主动通知用户/动作)

用途: 温度超限自动报警、PLC 心跳监控、设备异常事件

7.3 定时巡检流

Cron / Scheduler  →  大脑加载 SOP Skill  →  并行调多个设备  →  聚合报表  →  推送
(每小时/班次)         (/inspect-line)         (OPC UA 读 N 个点)            (邮件/钉钉)

8. 安全架构

8.1 威胁模型 (STRIDE)

威胁	场景	缓解
Spoofing	假冒大脑发指令	mTLS 双向证书 + Tailscale 设备认证
Tampering	篡改 MCP 调用	TLS 完整性 + Audit Log 链式 hash
Repudiation	否认操作	审计日志 + HARD_ACTION 录像
Information Disclosure	设备数据泄露	端到端加密 + 字段级脱敏
Denial of Service	被攻击瘫痪	Rate limit + 隔离区 + 物理冗余
Elevation of Privilege	越权写入	Policy Engine 强制 + 物理钥匙

8.2 凭证管理

禁止:

❌ 硬编码密码 / 证书 / API Key 到代码或配置
❌ 凭证明文写日志

强制:

✅ 所有凭证存 Vault / 1Password / DPAPI
✅ MCP server 启动时按需拉取, 内存暂存
✅ 90 天轮转
✅ 凭证使用全部审计

8.3 操作分级矩阵

级别	示例	AI 自主权	强制要求
READ_ONLY	读温度、查日志、截屏	完全自主	仅审计
SOFT_PARAM	调速度、改设定值、启停应用	需要用户口头 OK	双人 + 审计 + 业务时间
HARD_ACTION	急停、合分闸、删数据库、刷固件	永远不自动	物理钥匙 + 双工程师 + 录像 + 上级审批
DESTRUCTIVE	格式化磁盘、删除生产数据	完全禁用	不实现 / 走专门工单

8.4 网络隔离区

工业现场推荐 Purdue Model 分层：

Level 5: 企业网 (办公 + 大脑可放此层 DMZ)
Level 4: 业务网 (MES / ERP)
─── 防火墙 ────────────────────────────
Level 3: 工厂控制网 (SCADA Server / Historian)
Level 2: 监控网 (HMI / 工程师站)
Level 1: 现场控制网 (PLC / DCS)
Level 0: 物理设备 (传感器 / 执行器 / 电机)

大脑放 L4-L5; Edge Agent 跨 L3-L4 (单向数据二极管或严格防火墙); L0-L2 严格隔离, AI 永远不直接接触。

9. 部署模型

9.1 单机/家庭场景 (1-5 设备)

[本机大脑 Win/Mac/Linux PC]
    ├─ Claude Code + 全部 MCP servers
    ├─ Tailscale 节点
    └─ 本地 SQLite Registry
[1-3 台被控设备]
    └─ Edge Agent + Tailscale

部署 1 天内完成。

9.2 中型企业 (10-50 设备)

[中央服务器]
    ├─ Bookworm 大脑 (1 台中端 PC, 32GB RAM)
    ├─ MCP Cluster (Docker Compose)
    ├─ PostgreSQL (Registry + Audit)
    ├─ MQTT Broker (Mosquitto)
    └─ Tailscale Coordination Server (自托管 Headscale)

[每楼层/车间一台 Edge Gateway]
    ├─ 工业网关或 NUC
    ├─ Edge Agent + Subnet Router
    └─ 桥接 PLC/HMI (无法直接装 Tailscale 的设备)

[终端被控设备]
    └─ Edge Agent (Win/Linux/macOS/Android)

部署 2-4 周。

9.3 大型企业 (100+ 设备 / 多分公司)

[云端协调层 (可选)]
    └─ Tailscale / Headscale / 内部 PKI

[每分公司一套大脑 + 集群]
    ├─ 主备 (HA) 大脑节点
    ├─ Kubernetes 跑 MCP cluster
    ├─ TimeSeries DB (InfluxDB)
    ├─ Grafana 可视化
    └─ ELK / Loki 日志

[联邦层]
    └─ 跨分公司知识共享 (设备 SOP / 故障案例库)

部署 3-6 个月。

10. 技术选型

10.1 核心技术栈

层	选型	理由
AI 大脑	Claude Opus 4.7	工具调用 + 长上下文 + 推理质量
编排框架	Bookworm Skills + Agents	已有基础设施
协议	MCP (Model Context Protocol)	业界标准化, 工具发现 + 流式
网络	Tailscale (商业) / Headscale (自托管)	NAT 穿透 + 零信任 + 易用
MCP SDK 语言	Python (主) + Node.js (辅)	Python 生态最全 (工业/AI)
Edge Agent 语言	Node.js (跨平台单二进制)	pkg 打包 + 性能 + 平台 API 全
注册表	SQLite → PostgreSQL	单机起步, 集群升级
时序数据	InfluxDB / TimescaleDB	工业数据优化
消息总线	MQTT (Mosquitto/EMQX)	工业事实标准
凭证管理	HashiCorp Vault / 1Password CLI	企业级
容器化	Docker Compose (中型) / K8s (大型)	标准化部署
可视化	Grafana	通用
日志	Loki + Promtail	轻量

10.2 依赖清单 (PyPI / npm)

Python (适配层主语言):

asyncua            # OPC UA
pymodbus           # Modbus
python-snap7       # 西门子 S7
pycomm3            # 罗克韦尔 EtherNet/IP
pyvisa             # SCPI 仪器
paho-mqtt          # MQTT
pysnmp             # SNMP
ncclient           # NETCONF
uiautomator2       # Android UI
pywinauto          # Windows UI
mcp-server-sdk     # MCP 协议

Node.js (Edge Agent + 部分 MCP):

@modelcontextprotocol/sdk
ssh2               # SSH 客户端
node-windows       # Windows 服务/COM
@nut-tree/nut-js   # 跨平台 GUI 控制

11. 路线图

Phase 0: 立项 + PoC (Week 1-2)

选定 1 台 Win + 1 台 Android + 1 个 PLC (或模拟器) 作试点
部署 Tailscale 三节点
实现 ssh-mcp / adb-mcp / opcua-mcp 三个 MCP server
设备注册表 v0.1 (3 条 YAML)
验证目标: 用 Bookworm 一句话: "读 PLC 温度, 在 Win 上弹窗显示, 同时推送到 Android 通知栏"

交付: PoC Demo 视频 + 架构验证报告

Phase 1: 基础平台 (Week 3-8)

Edge Agent 跨平台二进制 (Win/Linux/macOS)
Android Termux Edge Agent
设备注册表 SQLite + 基础 Web UI
策略引擎 v1.0 (READ/WRITE 二级)
审计日志 + Grafana 可视化
Bookworm Skill /device 统一入口
CI/CD: Edge Agent 一键部署脚本

交付: 内部可用 v1.0, 5-10 台设备

Phase 2: 工业接入 (Week 9-16)

OPC UA / Modbus / S7 三协议生产级 MCP
SCADA 集成 (至少 1 个主流平台)
HMI 视觉控制 (RustDesk + askui-vision)
操作分级策略 (SOFT_PARAM + HARD_ACTION)
双因子审批 + 物理钥匙集成
工业现场试点 (1 个车间)

交付: 工厂级 v1.5, 真实生产数据接入

Phase 3: 智能化 (Week 17-26)

能力图谱 + 语义检索
跨设备 Workflow 编排 Skill
异常自动诊断 (日志 + 视觉 + 协议联合)
自然语言 SOP (用户说"上次故障怎么处理的？" → 自动回溯)
角色权限 (Operator/Engineer/Manager)

交付: AI 运维助手 v2.0

Phase 4: 规模化 (Month 7-12)

多分公司部署架构
跨地点知识联邦
时序数据 + 趋势预测
故障案例库自学习
SLA 监控 + 灾备

交付: 企业级生产平台 v3.0

12. 风险与缓解

风险	影响	概率	缓解措施
AI 误操作伤人/毁设备	极高	中	HARD_ACTION 必须物理钥匙 + 双人 + 录像; 安全 PLC 独立硬件
单点大脑故障	高	中	HA 双节点 + 设备本地降级 (PLC 自身逻辑保底)
网络中断	高	高	Edge Agent 本地缓存最近指令; MQTT 断线重连
凭证泄露	高	低	Vault + 90 天轮转 + Tailscale 双重网络隔离
协议厂商私有变更	中	中	OPC UA 优先, 私有协议作为备份
工控网攻击面扩大	高	低	严格 Purdue 分层 + 单向数据二极管
AI 幻觉决策	中	中	强制 MCP 调用返回真实数据时间戳, 决策前必读
部署/运维复杂度	中	高	Edge Agent 一键安装脚本; 可观测性建设
人员抗拒	中	高	从只读巡检场景切入, 让员工先看到价值
合规审计	中	中	全程审计 + 法务前置评估

13. 成功标准 (KPI)

12 个月目标

维度	KPI	目标值
覆盖率	接入设备数	≥ 30
协议种类	支持的设备协议	≥ 8 种
自动化率	重复任务自动化比例	≥ 50%
响应延迟	P95 端到端控制延迟	< 2 秒
可用性	大脑 + 核心 MCP 月可用	≥ 99.5%
安全	HARD_ACTION 误执行	= 0
审计	操作可追溯率	= 100%
ROI	节省人工时 / 月	≥ 80 小时

14. 附录

A. 参考实现 (开源)

MCP 协议规范: https://modelcontextprotocol.io
Tailscale: https://tailscale.com / https://github.com/juanfont/headscale
OPC UA Python: https://github.com/FreeOpcUa/opcua-asyncio
PyVISA: https://github.com/pyvisa/pyvisa
Termux: https://termux.dev / https://f-droid.org/packages/com.termux/
uiautomator2: https://github.com/openatx/uiautomator2
scrcpy: https://github.com/Genymobile/scrcpy
askui-vision: 已集成于 Bookworm

B. 关键术语表

术语	定义
MCP	Model Context Protocol, AI 工具调用标准协议
Edge Agent	部署在被控设备本地的轻量代理
Capability	设备暴露的能力单元 (如 read_temperature)
Policy Engine	决定 AI 调用是否被允许执行的规则引擎
Tailscale	基于 WireGuard 的零信任 mesh VPN
ADB	Android Debug Bridge, Android 控制协议
OPC UA	OPC Unified Architecture, 工业互联协议标准
SCPI	Standard Commands for Programmable Instruments, 测试仪器协议
Purdue Model	工业控制网络分层参考模型

C. 第一台设备接入清单 (Quick Start)

接入 Windows 设备

装 Tailscale + 加入 tailnet
装 OpenSSH Server + 推送公钥
装 Edge Agent + 任务计划用户会话启动
大脑端 ~/.claude.json 注册 MCP
测试: 远程启动 Notepad

接入 Android 设备

装 Tailscale (Play 商店) + 登录
启用无线调试 + adb pair / 或装 Termux + sshd
大脑端配置 adb-mcp 或 ssh-mcp
测试: 截图 + 推送通知

接入西门子 PLC

在 TIA Portal 启用 OPC UA Server
配置证书 + 命名空间
大脑端配置 opcua-mcp + endpoint
测试: 读 1 个 DB 变量

15. 修订记录

版本	日期	作者	变更摘要
v1.0	2026-04-25	Bookworm Architecture	初版, 含 Win/Linux/macOS/Android/工控/嵌入式/网络/IoT 全覆盖

下一步: 阅毕本白皮书后, 建议召开 1 小时 Kick-off 会议, 选定 Phase 0 的 3 台试点设备, 启动 PoC。

38 KiB Raw Permalink Blame History Unescape Escape