bookworm-smart-assistant/docs/AI-Universal-Control-Plane-WhitePaper.md

# 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 运行在本地, 数据不必上云, 适合工业场景的合规与延迟要求

**关键设计决策**：

1. 决策层 vs 执行层物理分离 → 大脑可单点部署, 边缘代理无状态
2. MCP 作为唯一适配协议 → 新设备接入只需写 MCP server, 无需改大脑
3. 设备注册表是知识层核心 → 不是 IP 列表, 是"能力图谱"
4. 安全联锁硬件优先 → 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]
```

**配置步骤**：

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

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

**MCP 能力包装**：

```python
# 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 后能力更强

**部署清单**：

```bash
# 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**:

```yaml
# 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 调用是否被允许执行

```yaml
# 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 贯穿大脑 → 适配 → 边缘：

```jsonl
{"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 示例**:

```hujson
{
  "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)

| 威胁 | 场景 | 缓解 |
|---|---|---|
| **S**poofing | 假冒大脑发指令 | mTLS 双向证书 + Tailscale 设备认证 |
| **T**ampering | 篡改 MCP 调用 | TLS 完整性 + Audit Log 链式 hash |
| **R**epudiation | 否认操作 | 审计日志 + HARD_ACTION 录像 |
| **I**nformation Disclosure | 设备数据泄露 | 端到端加密 + 字段级脱敏 |
| **D**enial of Service | 被攻击瘫痪 | Rate limit + 隔离区 + 物理冗余 |
| **E**levation 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。