From 7f84ea56fcf424c9361fca67e896b0243a9dbcf9 Mon Sep 17 00:00:00 2001 From: Childish-Ghost Date: Sat, 18 Jul 2026 22:17:37 +0800 Subject: [PATCH] docs: initial design documents - 9 pages: index, architecture, capabilities, roadmap, security, maintenance, pm-review, backlog, flow - shared style.css (dark theme) - .gitignore for OS / editor / build artifacts --- .gitignore | 38 ++ docs/architecture/index.html | 651 +++++++++++++++++++++++++++++++++++ docs/backlog/index.html | 164 +++++++++ docs/capabilities/index.html | 343 ++++++++++++++++++ docs/flow/index.html | 374 ++++++++++++++++++++ docs/index.html | 116 +++++++ docs/maintenance/index.html | 100 ++++++ docs/pm-review/index.html | 94 +++++ docs/roadmap/index.html | 208 +++++++++++ docs/security/index.html | 134 +++++++ docs/style.css | 164 +++++++++ 11 files changed, 2386 insertions(+) create mode 100644 .gitignore create mode 100644 docs/architecture/index.html create mode 100644 docs/backlog/index.html create mode 100644 docs/capabilities/index.html create mode 100644 docs/flow/index.html create mode 100644 docs/index.html create mode 100644 docs/maintenance/index.html create mode 100644 docs/pm-review/index.html create mode 100644 docs/roadmap/index.html create mode 100644 docs/security/index.html create mode 100644 docs/style.css diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..6c2d460 --- /dev/null +++ b/.gitignore @@ -0,0 +1,38 @@ +# OS +.DS_Store +Thumbs.db +desktop.ini + +# Editor +.vscode/ +.idea/ +*.swp +*.swo +*~ + +# Logs +*.log +npm-debug.log* + +# Env +.env +.env.local +.env.*.local + +# Build artifacts +node_modules/ +dist/ +build/ +target/ +*.exe +*.deb +*.apk +*.dmg + +# Tauri +src-tauri/target/ + +# Expo / React Native +.expo/ +.expo-shared/ +*.tsbuildinfo diff --git a/docs/architecture/index.html b/docs/architecture/index.html new file mode 100644 index 0000000..fbe7139 --- /dev/null +++ b/docs/architecture/index.html @@ -0,0 +1,651 @@ + + + + + +系统架构 — Global Control Assistant + + + +
+ 首页/ + 系统架构 +
+ +
+

系统架构设计

+

任意设备控制任意设备 · 全部通过客户端 MCP Server · 多通道统一记忆

+ + +
+

核心模型：任意设备 → 任意设备

+
+

自建客户端：两个功能模块

+

+ 功能 1 — 与 Gateway 沟通（发送命令）：客户端通过 WebSocket 连接 OpenClaw Gateway，提供聊天界面、设备管理、远程桌面。用户在客户端里的操作（聊天、点按钮）走的是 Gateway 的 API。

+ 功能 2 — 暴露本机能力（MCP Server）：客户端启动后自动注册到 Gateway 作为 MCP Server。AI 或其他设备要操作这台机器时，Gateway 调用它暴露的 MCP Tools（file_list、exec、screenshot 等）。

+ 所有被控设备都装客户端。不装客户端的设备不纳入控制范围。 +

+
+ +
┌─────────────────────────────────────────────────────────────────────────────┐ +│ 发起方 — 任意设备 / 任意通道 │ +│ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ 手机客户端│ │ 电脑客户端│ │ 飞书 │ │ 微信 │ │ Telegram │ │ +│ │(MCP+UI) │ │(MCP+UI) │ │ │ │ │ │ │ │ +│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ +└────────┼─────────────┼─────────────┼─────────────┼─────────────┼────────────┘ + ▼ ▼ ▼ ▼ ▼ +┌─────────────────────────────────────────────────────────────────────────────┐ +│ OpenClaw Gateway（MCP Host） │ +│ │ +│ AI Agent · 通道路由 · 记忆系统 · MCP Host │ +│ │ +│ ── 设备注册表（全部通过客户端 MCP Server）── │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ "home-pc" → MCP SSE 在线 [file,exec,screen,input] │ │ +│ │ "cloud-svr" → MCP SSE 在线 [file,exec,sysinfo] │ │ +│ │ "my-phone" → MCP SSE 在线 [file,exec,screenshot] │ │ +│ │ "work-pc" → MCP SSE 离线 [—] │ │ +│ └─────────────────────────────────────────────────────────────────────┘ │ +└───────────┬───────────────────────────────────────────────────────────────┘ + │ + ▼ + ┌────────┴────────┐ ┌──────────────────┐ + ▼ ▼ ▼ ▼ +┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ +│ home-pc │ │ cloud-svr│ │ my-phone │ │ work-pc │ +│客户端 │ │客户端 │ │客户端 │ │离线 │ +└──────────┘ └──────────┘ └──────────┘ └──────────┘
+
+ + +
+

典型场景

+
+
+

📱 手机找电脑文件

+

手机 App → Gateway → home-pc
"找桌面上的 PDF" → file_list("home-pc", "C:\\Desktop", "*.pdf")

+
+
+

💻 电脑查服务器日志

+

电脑 App → Gateway → cloud-svr
"看 nginx 最近 50 行日志" → exec("cloud-svr", "tail -50 /var/log/nginx.log")

+
+
+

💬 微信开关游戏服务器

+

微信 → Gateway AI → game-svr（客户端）
"把游戏服务器关了" → exec("game-svr", "systemctl stop minecraft")

+
+
+

📱 电脑看手机屏幕

+

电脑客户端 → Gateway → my-phone（客户端）
screenshot("my-phone") → 返回手机当前屏幕截图

+
+
+

🔄 跨设备文件传输

+

手机 App → Gateway → 从 NAS 传到电脑
file_transfer("nas", "/backup/data.zip", "home-pc", "D:\\backup\\")

+
+
+

🤖 AI 自动巡检

+

定时任务 → Gateway AI → 遍历所有设备
"检查所有服务器磁盘使用率" → AI 逐个调用 sysinfo

+
+
+
+ + +
+

目标设备接入方式

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
设备客户端类型说明
Windows / macOS / Linux 桌面桌面客户端Tauri 桌面客户端，MCP Server + 完整 UI（聊天/文件/远程桌面）
Android 手机移动端客户端React Native 客户端，MCP Server + 完整 UI
NAS（群晖/威联通等）CLI 客户端Node.js CLI，MCP Server 无 UI，Docker/systemd 后台运行
Linux 服务器CLI 客户端同 NAS CLI 版，npx 或 Docker 部署
树莓派 / 开发板CLI 客户端同 CLI 版，支持 GPIO/传感器扩展
+
+ +

能力说明

+

所有被控设备必须安装客户端。客户端作为 MCP Server 注册到 Gateway，能力完整（文件/命令/屏幕/输入/系统信息）。不装客户端的设备不纳入控制范围。

+
+ + +
+

自建客户端：两个功能

+

自建客户端部署在用户的手机和电脑上，连接到主机的 Gateway。

+
+
+

功能 1：与 Gateway 沟通

+

通过 WebSocket 连接 Gateway，提供聊天界面、设备管理、远程桌面。用户操作走 Gateway API。

+
+
+

功能 2：暴露本机能力（MCP Server）

+

启动后自动注册到 Gateway 作为 MCP Server。AI 或其他设备要操作这台机器时，Gateway 调用它的 MCP Tools。

+
+
+

远程桌面

+

获取目标设备屏幕推流，直接操控鼠标键盘。通过 WS 数据端口传输。

+
+
+

跨设备操作

+

手机上找电脑文件、电脑上查服务器日志。客户端不需要知道目标设备用什么协议，Gateway 统一路由。

+
+
+

独立代理

+

客户端内置独立代理配置（SOCKS5/HTTP），不影响系统代理。只代理客户端自身的 WebSocket 连接。适合需要代理才能访问 Tailscale/外网的场景。

+
+
+

启动自动连接

+

保存 Gateway 地址 + 认证 token。打开客户端自动连接 Gateway、注册 MCP Server、拉取设备列表。断线自动重连（指数退避 1s→2s→4s→...→60s）。

+
+
+ +

客户端配置

+
+ 客户端设置 +
// 本地存储，首次启动时配置，之后自动连接
+{
+  "gateway": {
+    "url": "ws://100.x.x.x:18789",     // Gateway 地址（Tailscale IP / DDNS 域名 / 内网 IP）
+    "token": "your-auth-token",        // 认证 token
+    "autoConnect": true,                // 启动自动连接
+    "reconnect": true                   // 断线自动重连
+  },
+  "proxy": {
+    "enabled": false,                   // 是否启用独立代理
+    "type": "socks5",                   // socks5 / http
+    "host": "127.0.0.1",
+    "port": 7890
+  },
+  "device": {
+    "name": "我的手机",                  // 本设备名称
+    "exposeAsMcp": true                 // 是否暴露本机能力给 Gateway
+  },
+  // OTA 更新由 expo-updates 自动处理，无需手动配置
+  // 更新 URL 在 app.json 的 updates.url 中配置
+}
+
+
+ + +
+

客户端完整连接流程

+ +

启动流程

+
┌──────────────────┐ +│ 客户端启动 │ +└────────┬─────────┘ + ▼ +┌──────────────────┐ 通了 ┌──────────────┐ +│ ① 测试 Gateway │───────────▶│ 连接 Gateway │ +│ 是否通联 │ │ 注册 MCP Server│ +│ (config 中的 URL │ │ 拉取设备列表 │ +│ timeout: 3s) │ │ 启动心跳 │ +└────────┬─────────┘ └──────────────┘ + │ 不通 + ▼ +┌──────────────────┐ +│ ② 检查 Tailscale │ +│ 状态 │ +└────────┬─────────┘ + │ + ┌────┼──────────────┐ + ▼ ▼ ▼ + 没运行 运行未连接 运行已连接 + │ │ │ + ▼ ▼ ▼ + 启动TS ③重连TS ┌─────────────┐ + started │ │ Gateway 不通 │ + _by_us=T │ │ 提示用户检查 │ + │ ┌─┴──┐ └─────────────┘ + │ ▼ ▼ + │ up 成功 up失败(需认证) + │ │ │ + │ │ ▼ + │ │ tailscale login + │ │ │ + │ │ ┌─┴──┐ + │ │ ▼ ▼ + │ │ 成功 失败→提示用户 + │ │ │ + ▼ ▼ ▼ + ┌──────────────┐ + │ 回到 ① 重试 │ + └──────────────┘
+ +

运行中心跳保活

+
┌──────────────────┐ +│ 正常运行中 │ +└────────┬─────────┘ + ▼ +┌──────────────────┐ +│ 每 30s 发 WS ping│◀─────────────────────┐ +└────────┬─────────┘ │ + │ │ + ┌────┴────┐ │ + ▼ ▼ │ + 收到pong 连续3次无响应 │ + │ │ │ + 继续运行 ▼ │ + ┌──────────┐ │ + │ 判定断开 │ │ + └────┬─────┘ │ + ▼ │ + ┌──────────┐ 成功 │ + │ 重连流程 │──────────────────────┘ + │ ①②③ │ + └────┬─────┘ + │ 全部失败 + ▼ + ┌──────────┐ + │ 通知用户 │ + │ 连接丢失 │ + └──────────┘
+ +

退出流程

+
┌──────────────────┐ +│ 客户端退出 │ +└────────┬─────────┘ + ▼ +┌──────────────────┐ +│ 断开 Gateway WS │ +└────────┬─────────┘ + ▼ +┌──────────────────┐ 是 ┌──────────────┐ +│ started_by_us? │───────────▶│ tailscale down│ +└────────┬─────────┘ │ 恢复进入前状态 │ + │ 否 └──────────────┘ + ▼ +┌──────────────────┐ +│ 不动 Tailscale │ +└──────────────────┘
+ +

完整状态机

+
客户端状态： + + IDLE ──启动──▶ TESTING ──通──▶ CONNECTED ──断开──▶ RECONNECTING ──成功──▶ CONNECTED + │ │ │ + │ 不通 │ 退出 │ 全部失败 + ▼ ▼ ▼ + CHECK_TS SHUTDOWN DISCONNECTED + │ + ┌─────┼─────┐ + ▼ ▼ ▼ + 没运行 未连接 已连接 + │ │ │ + ▼ ▼ ▼ + 启动TS 重连TS 报错 + │ │ + ▼ ▼ + TESTING（重试）
+
+ + +
+

设备在外面怎么连？

+

当设备不在同一局域网时（手机在外面、出差用笔记本、云服务器），需要穿透 NAT 连到主机 Gateway。

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
方案原理优点缺点国内可用
FRP主机跑 frpc，连到有公网 IP 的 frps 服务器。客户端通过 frps 的公网地址连 Gateway。国内最流行、开源免费、配置灵活、延迟低需要一台有公网 IP 的服务器（轻量云 30 元/年）最佳
ZeroTier类似 Tailscale，设备装 ZeroTier 自动组网。有官方中继服务器。开源、国内可用、零配置官方服务器偶尔抽风，可自建 Planet推荐
Cloudflare Tunnel主机跑 cloudflared，Gateway 通过 Cloudflare 网络暴露。免费、不需要公网 IP、自带 DDoS 防护国内访问可能慢/被墙看网络
Tailscale设备装 Tailscale 自动组网。OpenClaw 官方推荐。零配置、加密国内可能需要 DERP 中继、延迟高看网络
WireGuard自建 VPN，所有设备连入。高性能、自控需要公网 IP 服务器、手机配置麻烦可选
公网直连主机有公网 IP，Gateway 直接暴露。最简单、延迟最低安全风险高谨慎
+
+ +

当前方案

+
+
+

Tailscale

+

所有设备装 Tailscale，自动组网。客户端通过 Tailscale IP 连 Gateway。OpenClaw 官方推荐。

+
+
+

DDNS-GO

+

主机跑 DDNS-GO，自动更新动态公网 IP 到域名。客户端通过域名连 Gateway。

+
+
+

初期通过聊天通道（微信/飞书/Telegram）控制设备不需要穿透 NAT。客户端直连（远程桌面等）用 Tailscale 或 DDNS-GO。

+
+ + +
+

多通道记忆统一

+
+ + + + + + +
机制配置作用
身份统一session.identityLinks手机 App / 飞书 / 微信 / Telegram 映射为同一用户
会话共享dmScope: "per-peer"跨通道共享对话上下文
长期记忆MEMORY.md设备信息、用户偏好、操作历史
每日笔记memory/YYYY-MM-DD.md按天记录操作日志，支持语义检索
+
+
+ + +
+

OpenClaw Gateway 配置

+

以下是主机上 OpenClaw 需要的完整配置。

+ +
+ ~/.openclaw/openclaw.json +
{
+  // ① MCP Server 注册 — 客户端设备
+  "mcpServers": {
+    "home-pc": {
+      "url": "http://192.168.1.100:3001/sse"
+    },
+    "cloud-svr": {
+      "url": "http://100.64.0.3:3001/sse"
+    }
+  },
+
+  // ② 全部设备通过客户端 MCP Server 接入
+
+  // ③ 跨通道记忆统一
+  "session": {
+    "dmScope": "per-peer",
+    "identityLinks": {
+      "user:me": {
+        "channels": {
+          "feishu": "ou_xxx",
+          "wechat": "wxid_xxx",
+          "telegram": "12345678"
+        }
+      }
+    }
+  },
+
+  // ④ Gateway 绑定（根据网络环境选一种）
+  "gateway": {
+    "bind": "tailnet",              // Tailscale 虚拟网络
+    "auth": {
+      "mode": "token",
+      "token": "your-secret-token"
+    }
+  },
+
+  // ⑤ 模型配置
+  "agent": {
+    "model": "openai/gpt-4o"
+  },
+
+  // ⑥ 通道配置（按需启用）
+  "channels": {
+    "telegram": {
+      "token": "your-telegram-bot-token",
+      "dmPolicy": "pairing"
+    },
+    "feishu": {
+      "appId": "your-feishu-app-id",
+      "appSecret": "your-feishu-app-secret"
+    }
+  }
+}
+
+ +

配置说明

+
+ + + + + + + + + +
配置项作用必填
mcpServers注册客户端设备，Gateway 自动发现其 MCP Tools是
session.dmScope跨通道会话共享（per-peer = 同一用户共享）推荐
session.identityLinks飞书/微信/Telegram 用户映射为同一人推荐
gateway.bindGateway 绑定地址（tailnet/0.0.0.0/127.0.0.1）是
gateway.auth认证方式（token/password）是
agent.modelAI 模型（建议用旗舰模型）是
channels聊天通道配置（Telegram/飞书/微信等）按需
+
+
+ + +
+

最终技术方案

+
+ + + + + + + + + + + + + +
组件技术说明
Gateway（主机）OpenClawMCP Host，AI 大脑，通道路由
MCP Server 核心TypeScript + @modelcontextprotocol/sdk全平台通用，36 个 MCP Tools
Desktop 客户端Tauri v2 (Rust + React)Windows/Linux/macOS，~5MB，内置 OTA updater
Android 客户端React Native + Expo移动端，Expo Updates OTA 热更新
CLI 客户端TypeScript (Node.js)NAS/服务器/树莓派，Docker/systemd 部署
共享类型TypeScript协议定义、MCP Tool 类型、配置类型
屏幕推流WS 数据端口直连screenshot-desktop + Sharp + MJPEG
鼠标键盘nut.js跨平台输入模拟
OTA 更新Expo Updates (JS bundle) + Tauri updater (APK)小更新 JS bundle OTA 静默推送（新增页面/改 UI/修 Bug）；大更新 APK 重装（原生模块变更）
CI/CDGitHub Actions / Giteepush tag → 自动构建所有平台
编辑器IntelliJ IDEATypeScript + Rust 开发
+
+
+ + +
+

OTA 更新策略

+
+

双轨更新：小更新 OTA 静默推送，大更新 APK 重装

+

+ 小更新（JS bundle）：新增页面、改 UI、修 Bug、改业务逻辑 → expo-updates 静默推送 JS bundle（~1-2MB），用户无感，下次打开自动生效。
+ 大更新（APK）：新增原生模块、改图标、升级 React Native 版本 → 需要重新打包 APK，用户手动安装。 +

+
+ +
+ + + + +
更新类型方式用户感知场景
小更新JS bundle OTA (expo-updates)无感，自动生效新增页面、改 UI、修 Bug、改逻辑、新增 JS 依赖
大更新APK 重装需手动安装新增原生模块、改图标/启动图、改包名、升级 RN
+
+ +

OTA 发布流程

+
+ 发布 JS bundle 更新 +
# 1. 修改代码（JS/TS）
+# 2. 增加版本号（app.json version + versionCode）
+
+# 3. 导出 JS bundle
+npx expo export --platform android
+
+# 4. 上传 dist/ 到 Gitee 静态仓库
+git add dist/ && git commit -m "ota: v0.1.1" && git push
+
+# 5. App 自动检测更新（启动时 + 每 24 小时）
+# 用户下次打开 App 自动生效
+
+ +

OTA 配置（app.json）

+
+ app.json +
{
+  "expo": {
+    "updates": {
+      "url": "https://gitee.com/your-org/gca-ota/manifest.json"
+    },
+    "plugins": [
+      ["expo-updates", { "username": "gca" }]
+    ]
+  }
+}
+
+
+ + +
+

项目结构

+
+
gca/
+├── packages/
+│   ├── client/                  # 桌面/移动端客户端（MCP Server + UI）
+│   │   ├── src/
+│   │   │   ├── server/          # MCP Server（暴露本机能力给 Gateway）
+│   │   │   │   ├── tools/       # MCP Tools（file/exec/screen/input/sysinfo）
+│   │   │   │   └── data-channel/# WS 数据端口（推流/文件/键鼠）
+│   │   │   ├── ui/              # UI（聊天/文件浏览/远程桌面，连 Gateway WS API）
+│   │   │   └── platform/        # 平台适配（win/linux/mac/android）
+│   │   └── package.json
+│   ├── client-cli/              # CLI 版客户端（NAS/树莓派/无显示器设备）
+│   │   ├── src/
+│   │   │   ├── index.ts         # CLI 入口（gca-cli start/stop/status）
+│   │   │   ├── daemon.ts        # 后台守护进程
+│   │   │   └── server/          # 复用 client/server 的 MCP Tools
+│   │   └── package.json
+│   └── shared/                  # 共享类型
+├── pnpm-workspace.yaml
+└── README.md
+
+
+ + +
+

实现细节

+ +

客户端实现

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
模块实现说明
MCP Server@modelcontextprotocol/sdk启动时创建 MCP Server 实例，注册 Tools，通过 SSE/WS 暴露给 Gateway
Gateway 连接WebSocket Client连接 Gateway 的 WS API，支持独立代理（SOCKS5/HTTP）、自动重连
文件服务Node.js fs / Rust std::fs实现 file_list/read/write/move/delete，支持 glob 过滤
命令执行child_process / Rust std::process::Command实现 exec，支持超时、工作目录、环境变量
屏幕捕获screenshot-desktop (Node) / screenshots crate (Rust)截取屏幕，JPEG 压缩后返回 base64
系统信息systeminformation (Node) / sysinfo crate (Rust)CPU/内存/磁盘/网络/运行时间
独立代理Tauri: tokio-tungstenite + HTTP CONNECT / RN: OkHttp proxy只代理客户端自身的 WS 连接，不影响系统代理
UITauri: React / RN: React Native聊天界面、设备列表、文件浏览器、远程桌面、设置页面
+
+ +

通信流程

+
场景：用户在手机上找电脑文件 + + 手机客户端 Gateway 电脑客户端 + │ │ │ + │ ① 用户操作/发消息 │ │ + │ ──WS──▶ │ │ + │ ② AI 调用 MCP Tool │ │ + │ file_list("pc-1") │ │ + │ │ ③ 转发到电脑客户端 │ + │ │ ──MCP──▶ │ + │ │ ④ 电脑执行 file_list│ + │ │ 本地文件系统操作 │ + │ │ ◀──结果── │ + │ ◀──结果── │ │ + │ ⑤ 返回给手机 │ │ + │ ◀──结果── │ │ + │ │ │ + 场景：用户在电脑上看手机屏幕 + + 电脑客户端 Gateway 手机客户端 + │ │ │ + │ ① 调用 screenshot("phone") │ │ + │ ──WS──▶ │ │ + │ ② 转发到手机客户端 │ │ + │ │ ──MCP──▶ │ + │ │ ③ 手机截屏 │ + │ │ ◀──base64─ │ + │ ◀──图片── │ │ + │ ④ 显示手机屏幕 │ │ + │ ◀──图片── │ │
+
+
+ + + + diff --git a/docs/backlog/index.html b/docs/backlog/index.html new file mode 100644 index 0000000..63d58aa --- /dev/null +++ b/docs/backlog/index.html @@ -0,0 +1,164 @@ + + + + + +开发代办清单 — Global Control Assistant + + + +
+ 首页/ + 架构/ + 开发代办 +
+ +
+

开发代办清单

+

按模块拆分，每个功能独立任务

+ +
+
6
模块
+
55
任务总数
+
15
P0
+
20
P1
+
20
P2
+
+ + +
+

模块 1：shared — 共享类型与协议

+ + + + + + + +
编号任务说明优先级依赖
S-001定义 MCP Tool 类型36 个 Tool 的 TypeScript 类型（name、inputSchema、outputSchema）P0—
S-002定义设备配置类型设备信息、连接配置、代理配置接口P0—
S-003定义数据通道协议屏幕推流、文件传输、键鼠事件的 WS 消息格式P1—
S-004定义客户端状态类型连接状态、Tailscale 状态、设备在线状态枚举P1—
S-005JSON Schema 生成从 TypeScript 类型自动生成 JSON SchemaP2S-001
+
+ + +
+

模块 2：client/server — MCP Server 核心

+ + + + + + + + + + + + + + + + + + + + +
编号任务说明优先级依赖
C-001MCP Server 框架用 @modelcontextprotocol/sdk 搭建基础框架，SSE 传输P0S-001
C-002file_list Tool列出目录内容，支持 glob 过滤和递归P0C-001
C-003file_read Tool读取文件内容，支持行范围P0C-001
C-004file_write Tool写入/创建文件P0C-001
C-005file_move Tool移动/重命名文件P0C-001
C-006file_delete Tool删除文件P1C-001
C-007file_transfer Tool跨设备文件传输（通过 WS 数据端口）P2C-001, S-003
C-008exec Tool执行命令并返回结果，支持超时P0C-001
C-009exec_background Tool后台执行长时间命令，返回任务 IDP1C-008
C-010process_list Tool列出进程，支持 CPU/内存排序P0C-001
C-011sysinfo Tool返回 CPU/内存/磁盘/网络/运行时间P0C-001
C-012power Tool关机/重启/休眠/WoLP1C-001
C-013service Tool系统服务管理（启动/停止/重启/状态）P1C-001
C-014notify_send Tool发送桌面通知P1C-001
C-015Gateway 注册与自动连接客户端启动时 SSE 注册到 Gateway，支持自动重连P0C-001
C-016独立代理支持SOCKS5/HTTP 代理，只代理自身连接P1C-015
C-017MCP Resourcesdevice://list、device://{id}/status 资源暴露P2C-001
C-018MCP Promptstroubleshoot、optimize 预置提示词P2C-001
+
+ + +
+

模块 3：client/platform — 平台适配

+ + + + + + + + + + + + + +
编号任务说明优先级依赖
P-001Windows 平台适配屏幕捕获、系统信息、命令执行的 Windows 实现P0C-001
P-002Linux 平台适配复用 Windows 代码，适配 Linux 路径和命令P1P-001
P-003macOS 平台适配复用代码，适配 macOS 特定 APIP2P-001
P-004Android 平台适配React Native 环境下的文件/进程/系统信息P1P-001
P-005CLI 平台适配无 UI 版，Node.js CLI 入口，systemd/Docker 部署P1C-001
P-006连接生命周期 — 通联检测启动时测试 Gateway 是否可达P0C-015
P-007连接生命周期 — Tailscale 管理按需启停 Tailscale，记录 started_by_us 状态P1P-006
P-008连接生命周期 — 心跳保活每 30s ping，连续 3 次无响应判定断开P0C-015
P-009连接生命周期 — 断线重连指数退避重连（1s→2s→4s→...→60s）P0P-008
P-010连接生命周期 — 退出恢复退出时恢复 Tailscale 到进入前状态P1P-007
P-011配置管理本地 JSON 配置读写、系统 keychain 凭据存储P1S-002
+
+ + +
+

模块 4：client/ui — 客户端界面

+ + + + + + + + + + + + + + +
编号任务说明优先级依赖
U-001设置页面Gateway 地址、token、代理、设备名称配置P0P-011
U-002连接状态指示器顶部状态栏显示 Gateway 连接状态、Tailscale 状态P1P-008
U-003设备列表页面所有设备卡片（名称、在线状态、CPU/内存/磁盘概览）P1C-015
U-004设备详情页面单设备完整信息（进程列表、系统信息、网络状态）P2U-003
U-005文件浏览器远程目录树、文件列表、面包屑导航P1C-002
U-006文件查看器文本文件查看、图片预览P2U-005
U-007文件上传/下载拖拽上传、下载进度条P2U-005, C-007
U-008远程终端命令输入框、输出显示、历史记录P1C-008
U-009远程桌面视图屏幕推流显示区域P2S-003
U-010远程桌面输入鼠标点击/移动/滚动、键盘输入转发P2U-009
U-011远程桌面工具栏全屏、缩放、剪贴板同步、快捷键P2U-009
U-012AI 聊天界面消息列表、输入框、Markdown 渲染P1C-015
+
+ + +
+

模块 5：远程控制与 AI 操控

+ + + + + + + + + + + +
编号任务说明优先级依赖
R-001screenshot Tool截取屏幕，返回 base64 JPEGP1P-001
R-002remote_input Tool鼠标移动/点击/滚动/拖拽、键盘输入/按键/快捷键P1P-001
R-003clipboard_sync Tool剪贴板读写/同步P1P-001
R-004remote_stream Tool开始/停止屏幕推流，WS 数据端口P2R-001, S-003
R-005ui_find Tool通过 Accessibility API 查找 UI 元素P2P-001
R-006ui_act Tool操作 UI 元素（点击/输入/选择/读取）P2R-005
R-007browser_open Tool打开 URL / 操控远端浏览器P2C-001
R-008browser_act Tool浏览器内操作（填写/点击/截图/获取文本）P2R-007
R-009ocr_screen Tool屏幕 OCR 文字识别P2R-001
+
+ + +
+

模块 6：OTA 更新与 CI/CD

+

策略：小更新 JS bundle OTA 静默推送，大更新 APK 重装。

+ + + + + + + +
编号任务说明优先级依赖
O-001CI/CD 流水线push tag → 自动构建 Desktop + Android + CLIP1—
O-002Android JS bundle OTAexpo-updates：启动检查 + 每 24h 检查 → 静默下载 JS bundle → 下次打开生效P1O-001
O-003Desktop 自动更新Tauri updater：检查 latest.json → 后台下载 APK → 静默安装P1O-001
O-004CLI 自动更新gca-cli update 命令，下载最新版本并替换P2O-001
O-005OTA 发布脚本一键导出 JS bundle 并上传到 Gitee 静态仓库P1O-002
+
+ + +
+

建议开发顺序

+
+ + + + + + + + + + + + +
批次任务产出
第 1 批S-001, S-002, U-001类型定义 + 设置页面
第 2 批C-001~C-005, C-008, C-010, C-011MCP Server 核心 8 个 Tool
第 3 批P-001, P-006, P-008, P-009, C-015Windows 适配 + 连接生命周期
第 4 批U-002, U-003, U-005, U-008, U-012核心 UI（设备列表/文件/终端/聊天）
第 5 批C-006, C-009, C-012~C-016, P-011扩展 Tool + 代理 + 配置
第 6 批R-001~R-003, P-002, P-005远程控制基础 + Linux/CLI 适配
第 7 批R-004, S-003, U-009~U-011屏幕推流 + 远程桌面 UI
第 8 批U-004, U-006, U-007, C-007, C-017, C-018设备详情/文件查看/Resources
第 9 批R-005~R-009, P-004AI 操控 + Android 适配
第 10 批O-001~O-005, S-005, P-003CI/CD + OTA + macOS
+
+
+
+ + + + diff --git a/docs/capabilities/index.html b/docs/capabilities/index.html new file mode 100644 index 0000000..7e1f179 --- /dev/null +++ b/docs/capabilities/index.html @@ -0,0 +1,343 @@ + + + + + +能力全景 — Global Control Assistant + + + + +
+ 首页/ + 架构/ + 能力全景 +
+ +
+

MCP Tools 能力全景

+

客户端（MCP Server）暴露给 Gateway 的全部工具，AI 自动调用

+ +
+
4
设备管理
+
3
命令执行
+
6
文件操作
+
3
系统控制
+
4
远程桌面
+
5
AI 操控
+
3
网络
+
3
硬件
+
3
开发工具
+
2
媒体
+
+ + +
+
+
📱
+

设备管理

+ 4 tools +
+
+
+

device_list

+

列出所有已注册设备及在线状态

+
无参数
+
+
+

device_info

+

获取指定设备的详细信息（OS、IP、资源使用）

+
device: string
+
+
+

device_add

+

添加新设备配置（客户端自动注册，此 Tool 用于手动注册 CLI 设备）

+
id, name, url: string
+
+
+

device_remove

+

移除设备配置

+
device: string
+
+
+
+ + +
+
+
💻
+

命令执行

+ 3 tools +
+
+
+

exec

+

在指定设备上执行命令并等待结果

+
device: string, command: string, timeout?: number
+
+
+

exec_background

+

后台执行长时间命令，返回任务 ID

+
device: string, command: string
+
+
+

process_list

+

列出指定设备上的进程（支持按 CPU/内存排序）

+
device: string, sort?: "cpu" | "memory", limit?: number
+
+
+
+ + +
+
+
📁
+

文件操作

+ 6 tools +
+
+
+

file_list

+

列出目录内容（支持 glob 过滤和递归）

+
device: string, path: string, pattern?: string, recursive?: boolean
+
+
+

file_read

+

读取文件内容（支持行范围读取）

+
device: string, path: string, offset?: number, limit?: number
+
+
+

file_write

+

写入/创建文件

+
device: string, path: string, content: string
+
+
+

file_move

+

移动/重命名文件

+
device: string, from: string, to: string
+
+
+

file_delete

+

删除文件

+
device: string, path: string
+
+
+

file_transfer

+

跨设备文件传输（从源设备传到目标设备）

+
from_device: string, from_path: string, to_device: string, to_path: string
+
+
+
+ + +
+
+
⚙️
+

系统控制

+ 3 tools +
+
+
+

sysinfo

+

获取系统信息（CPU/内存/磁盘/网络/运行时间）

+
device: string
+
+
+

power

+

电源操作（关机/重启/休眠/Wake-on-LAN）

+
device: string, action: "shutdown" | "restart" | "hibernate" | "wol"
+
+
+

service

+

系统服务管理（启动/停止/重启/查看状态）

+
device: string, name: string, action: "start" | "stop" | "restart" | "status"
+
+
+
+ + +
+
+
🖱️
+

远程桌面（人工操控）

+ 4 tools +
+
+
+

screenshot

+

截取远程设备屏幕画面（返回 base64 图片）

+
device: string, display?: number, quality?: number
+
+
+

remote_input

+

发送鼠标/键盘事件到远程设备

+
device: string, type: "mouse_move" | "mouse_click" | "mouse_scroll" | "key_type" | "key_press" | "hotkey", ...
+
+
+

remote_stream

+

开始/停止屏幕推流（返回 WS 数据端口地址）

+
device: string, action: "start" | "stop", fps?: number, quality?: number
+
+
+

clipboard_sync

+

读取/设置远程设备剪贴板，跨设备同步

+
device: string, action: "get" | "set" | "sync", content?: string
+
+
+
+ + +
+
+
🤖
+

AI 应用操控

+ 5 tools +
+
+
+

ui_find

+

通过 Accessibility API 查找应用内的 UI 元素

+
device: string, app: string, element: string, role?: string
+
+
+

ui_act

+

操作 UI 元素（点击/输入/选择/读取）

+
device: string, element_id: string, action: "click" | "set_value" | "get_value"
+
+
+

browser_open

+

在远程设备上打开 URL 或操控已打开的浏览器

+
device: string, url?: string, attach?: boolean
+
+
+

browser_act

+

浏览器内操作（填写表单/点击元素/截图/获取文本）

+
device: string, action: "fill" | "click" | "screenshot" | "get_text", selector?: string, value?: string
+
+
+

ocr_screen

+

对远程设备屏幕进行 OCR 文字识别

+
device: string, region?: { x, y, width, height }
+
+
+
+ + +
+
+
🌍
+

网络管理

+ 3 tools +
+
+
+

net_status

+

网络状态（接口/IP/连通性/流量）

+
device: string
+
+
+

net_wifi

+

WiFi 管理（扫描/连接/列出已保存网络）

+
device: string, action: "scan" | "connect" | "list", ssid?: string, password?: string
+
+
+

net_ping

+

网络诊断（ping/traceroute/DNS 查询）

+
device: string, target: string, action?: "ping" | "traceroute" | "dns"
+
+
+
+ + +
+
+
🔧
+

硬件监控

+ 3 tools +
+
+
+

hw_temps

+

温度监控（CPU/GPU/磁盘温度）

+
device: string
+
+
+

hw_battery

+

电池状态（电量/充电状态/健康度）

+
device: string
+
+
+

hw_disk

+

磁盘信息（分区/使用量/SMART 数据）

+
device: string
+
+
+
+ + +
+
+
🛠️
+

开发者工具

+ 3 tools +
+
+
+

docker_ps

+

Docker 容器管理（列表/启动/停止/重启/日志）

+
device: string, action: "list" | "start" | "stop" | "restart" | "logs", container?: string
+
+
+

git_op

+

Git 操作（status/pull/push/log）

+
device: string, repo: string, action: "status" | "pull" | "push" | "log"
+
+
+

log_read

+

读取系统/应用日志

+
device: string, source: string, lines?: number, filter?: string
+
+
+
+ + +
+
+
🎬
+

媒体通信

+ 2 tools +
+
+
+

media_control

+

媒体播放控制（播放/暂停/下一曲/音量）

+
device: string, action: "play" | "pause" | "next" | "prev" | "volume", value?: number
+
+
+

notify_send

+

发送桌面通知到指定设备

+
device: string, title: string, body?: string
+
+
+
+
+ + + + diff --git a/docs/flow/index.html b/docs/flow/index.html new file mode 100644 index 0000000..bb4336a --- /dev/null +++ b/docs/flow/index.html @@ -0,0 +1,374 @@ + + + + + +系统流程 — Global Control Assistant + + + + +
+ 首页/ + 架构/ + 能力/ + 路线图/ + 代办/ + 安全/ + 流程 +
+ +
+

系统流程

+

GCA 系统中各个核心流程的完整走查

+ + +
+

1. 客户端启动流程

+
+

客户端打开后的完整启动链路

+
    +
  1. App 启动 → 加载本地配置（Gateway 地址、Token、代理设置）
    2. +
  2. 启动 MCP Server → 客户端内置 MCP Server 开始监听，暴露本机能力（file/exec/screen/sysinfo 等）
    3. +
  3. 连接 Gateway → WebSocket 连接 OpenClaw Gateway，发送认证 Token
    4. +
  4. 注册设备 → 向 Gateway 报告设备信息（名称、IP、OS、能力列表）
    5. +
  5. 开始心跳 → 每 30 秒发送心跳，Gateway 更新设备在线状态
    6. +
  6. OTA 检查 → 启动 3 秒后检查一次更新，之后每 24 小时检查一次
    7. +
  7. 就绪 → 设备出现在 Gateway 设备列表中，可被 AI 或其他设备调用
    8. +
+
+ +
客户端启动 + │ + ├── 1. 读取本地配置 + │ └── Gateway URL / Token / 代理 / 设备名 + │ + ├── 2. 启动 MCP Server + │ └── 注册 36 个 MCP Tools (file/exec/screen/sysinfo/...) + │ + ├── 3. 连接 OpenClaw Gateway + │ ├── WebSocket → ws://gateway:port + │ └── 发送认证 Token + │ + ├── 4. 注册设备 + │ └── { name, ip, os, capabilities } + │ + ├── 5. 心跳循环 (30s) + │ └── 持续上报设备状态 + │ + └── 6. OTA 检查 (启动后 3s + 每 24h) + └── expo-updates 检查 → 静默下载 JS bundle
+
+ + +
+

2. AI 控制设备流程

+
+

用户通过任意通道发送自然语言指令

+
    +
  1. 用户发消息 → 通过微信/飞书/Telegram/自建客户端发送："看看服务器磁盘满了没"
    2. +
  2. Gateway 接收 → OpenClaw Gateway 的 AI Agent 接收消息，理解意图
    3. +
  3. AI 选择工具 → AI 决定调用 exec 工具，参数 device="cloud-svr", command="df -h"
    4. +
  4. Gateway 路由 → Gateway 将 MCP Tool 调用转发到 cloud-svr 客户端
    5. +
  5. 客户端执行 → cloud-svr 的 MCP Server 执行 df -h，返回磁盘信息
    6. +
  6. AI 格式化 → AI 将原始数据格式化为易读的回复
    7. +
  7. 回复用户 → 通过原通道返回结果给用户
    8. +
+
+ +
用户: "看看服务器磁盘满了没" + │ + ▼ +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ +│ 任意通道 │───▶│ Gateway │───▶│ cloud-svr │ +│ 微信/飞书/ │ │ AI Agent │ │ 客户端 │ +│ Telegram │ │ │ │ MCP Server │ +└─────────────┘ └──────┬──────┘ └──────┬──────┘ + │ │ + │ MCP Tool 调用 │ + │ exec("df -h") │ + │──────────────────▶│ + │ │ + │ 执行结果 │ + │◀──────────────────│ + │ │ + │ AI 格式化回复 │ + ▼ │ + "磁盘使用率 78%， │ + 剩余 120GB" │ + │ │ + ▼ │ + 回复给用户 │
+
+ + +
+

3. 人工远程控制流程

+
+

用户通过客户端直接操控远端设备（类 TeamViewer）

+
    +
  1. 选择设备 → 在客户端设备列表中点击目标设备
    2. +
  2. 发起远程桌面 → 客户端发送 screen_stream_start 请求
    3. +
  3. 建立数据通道 → 客户端与目标设备建立 WebSocket 直连（不经过 Gateway，低延迟）
    4. +
  4. 屏幕推流 → 目标设备以 MJPEG 格式推流（15-30fps）
    5. +
  5. 输入转发 → 用户的鼠标/键盘操作通过数据通道实时转发到目标设备
    6. +
  6. 剪贴板同步 → 双向剪贴板同步（可选）
    7. +
  7. 结束 → 用户断开，数据通道关闭
    8. +
+
+ +
用户客户端 Gateway 目标设备 + │ │ │ + │ ① 请求远程桌面 │ │ + │ MCP: screen_stream_start │ │ + │───────────────────────────▶│ │ + │ │ ② 转发请求 │ + │ │─────────────────────────▶│ + │ │ │ + │ │ ③ 返回数据通道地址 │ + │ │◀─────────────────────────│ + │ ④ 数据通道地址 │ │ + │◀───────────────────────────│ │ + │ │ + │ ⑤ 直连数据通道 (WebSocket) │ + │◀══════════════════════════════════════════════════════▶│ + │ │ + │ ⑥ 屏幕推流 (MJPEG 15-30fps) │ + │◀──────────────────────────────────────────────────────│ + │ │ + │ ⑦ 鼠标/键盘事件 │ + │───────────────────────────────────────────────────────▶│ + │ │ + │ ⑧ 剪贴板同步 (可选) │ + │◀══════════════════════════════════════════════════════▶│
+
+ + +
+

4. AI 自动操控应用流程

+
+

AI 代理自动操作设备上的应用（无需人工干预）

+
    +
  1. 用户指令 → "帮我打开 Chrome，搜索今天的天气"
    2. +
  2. AI 分解任务 → ① 启动 Chrome ② 打开 Google ③ 输入搜索词 ④ 点击搜索
    3. +
  3. 执行 Step 1 → MCP Tool: exec("home-pc", "start chrome")
    4. +
  4. 执行 Step 2 → MCP Tool: browser_open("home-pc", "https://google.com")
    5. +
  5. 执行 Step 3 → MCP Tool: browser_fill("home-pc", "input[name=q]", "今天天气")
    6. +
  6. 执行 Step 4 → MCP Tool: browser_click("home-pc", "input[name=btnK]")
    7. +
  7. 返回结果 → 截图返回给用户
    8. +
+
+ +
用户: "帮我打开 Chrome，搜索今天的天气" + │ + ▼ +AI Agent 分解任务: + ├── Step 1: exec("home-pc", "start chrome") + ├── Step 2: browser_open("home-pc", "https://google.com") + ├── Step 3: browser_fill("home-pc", "input[name=q]", "今天天气") + ├── Step 4: browser_click("home-pc", "input[name=btnK]") + └── Step 5: screenshot("home-pc") → 返回截图给用户 + +每个 Step 都是 MCP Tool 调用，通过 Gateway 路由到 home-pc 客户端执行
+
+ + +
+

5. 跨设备文件传输流程

+
+

从一台设备传输文件到另一台设备

+
    +
  1. 用户指令 → "把 NAS 上的 backup.zip 传到电脑桌面"
    2. +
  2. AI 调用 → MCP Tool: file_transfer("nas", "/backup/backup.zip", "home-pc", "C:\\Desktop\\")
    3. +
  3. Gateway 协调 → Gateway 分别连接 NAS 和 home-pc 的 MCP Server
    4. +
  4. NAS 读取 → NAS 客户端读取文件，通过数据通道流式传输
    5. +
  5. PC 写入 → home-pc 客户端接收并写入目标路径
    6. +
  6. 完成 → 返回传输结果（文件大小、耗时）
    7. +
+
+ +
用户: "把 NAS 上的 backup.zip 传到电脑桌面" + │ + ▼ +Gateway AI → file_transfer("nas", "/backup.zip", "home-pc", "C:\Desktop\") + │ + ├── NAS 客户端 Gateway home-pc 客户端 + │ │ │ │ + │ │ ① 读取文件 │ │ + │ │◀──────────────────│ │ + │ │ │ │ + │ │ ② 流式传输 │ │ + │ │──────────────────▶│ │ + │ │ │ ③ 写入文件 │ + │ │ │─────────────────────▶│ + │ │ │ │ + │ │ │ ④ 完成确认 │ + │ │ │◀─────────────────────│ + │ │ │ │ + └─────┴───────────────────┴──────────────────────┘ + │ + ▼ + "传输完成，128MB，耗时 3.2s"
+
+ + +
+

6. OTA 更新流程

+
+

JS bundle 静默更新（小更新）

+
    +
  1. 开发者修改代码 → 修改 JS/TS 代码（新增页面、修 Bug、改 UI）
    2. +
  2. 导出 bundle → npx expo export --platform android 生成 JS bundle
    3. +
  3. 上传到 Gitee → 将 bundle 上传到 Gitee 静态仓库
    4. +
  4. App 检查更新 → 启动时 + 每 24 小时自动检查
    5. +
  5. 静默下载 → 发现新版，后台下载 JS bundle（~1-2MB）
    6. +
  6. 下次启动生效 → 用户下次打开 App 自动使用新版本
    7. +
+
+ +
+

APK 重装（大更新）

+
    +
  1. 开发者修改原生代码 → 新增原生模块、改图标、升级 RN
    2. +
  2. 构建 APK → eas build -p android --profile preview
    3. +
  3. 发布到 Gitee → 上传 APK 到 Releases
    4. +
  4. 通知用户 → App 内提示有新版本
    5. +
  5. 用户手动安装 → 下载 APK 并安装
    6. +
+
+ +
小更新 (JS bundle OTA): + 开发者 → expo export → 上传 Gitee → App 自动检查 → 静默下载 → 下次启动生效 + 用户无感，1-2MB，几秒钟完成 + +大更新 (APK 重装): + 开发者 → eas build → 上传 Gitee Releases → App 提示 → 用户手动下载安装 + 需要用户操作，15-30MB
+
+ + +
+

7. 多通道记忆流程

+
+

用户在不同通道的对话如何统一记忆

+
    +
  1. 身份映射 → OpenClaw 的 identityLinks 将微信/飞书/Telegram 账号映射为同一用户
    2. +
  2. 会话共享 → dmScope: "per-peer" 确保同一用户跨通道共享会话上下文
    3. +
  3. 记忆存储 → MEMORY.md 存储持久记忆（设备信息、用户偏好、操作历史）
    4. +
  4. 每日笔记 → memory/YYYY-MM-DD.md 记录当天操作日志
    5. +
  5. 记忆蒸馏 → Dreaming 系统自动从每日笔记中提取有价值信息晋升到长期记忆
    6. +
  6. 跨通道回忆 → 在飞书中问"刚才微信说的那个文件在哪"，AI 能从记忆中找到
    7. +
+
+ +
微信: "帮我备份桌面 PDF" + │ + ▼ +AI 执行 file_list + file_move → 完成 + │ + ├── 写入 memory/2026-07-16.md: + │ "用户要求备份桌面 PDF，已移动 12 个文件到 D:\备份\" + │ + ▼ +飞书 (3小时后): "刚才那个备份做了吗？" + │ + ▼ +AI → memory_search("备份 PDF") → 找到今日笔记 + │ + ▼ +"已备份，共 12 个 PDF 文件到 D:\备份\"
+
+ + +
+

8. 设备连接生命周期

+
+

设备从离线到在线的完整流程

+
设备状态流转: + + offline ──客户端启动──▶ online ──开始操控──▶ busy ──操控结束──▶ online + │ │ + │ ├── 设备休眠 ──▶ sleeping ──唤醒──▶ online + │ │ + │ └── 维护模式 ──▶ maintenance ──完成──▶ online + │ + └── 连接失败 ──▶ unreachable ──重连成功──▶ online + │ + └── 重连失败 ──▶ offline + +Gateway 设备注册表: + ┌──────────────────────────────────────────────┐ + │ 设备ID │ 协议 │ 状态 │ 最后心跳 │ + │─────────────┼─────────┼─────────┼─────────────│ + │ home-pc │ MCP SSE │ online │ 2s ago │ + │ cloud-svr │ MCP SSE │ online │ 5s ago │ + │ my-phone │ MCP SSE │ busy │ 1s ago │ + │ game-svr │ MCP SSE │ offline │ 2h ago │ + └──────────────────────────────────────────────┘
+
+
+ + +
+

9. 安全控制流程

+
+

多层安全防护

+
请求进入 + │ + ▼ +┌─────────────────────────────────────┐ +│ ① 身份验证 │ +│ - Gateway Token 认证 │ +│ - 设备配对 Token │ +│ - 通道身份验证 (微信/飞书) │ +└──────────────┬──────────────────────┘ + ▼ +┌─────────────────────────────────────┐ +│ ② 权限控制 │ +│ - Tool 白名单/黑名单 │ +│ - 设备级权限 │ +│ - 通道级权限 │ +└──────────────┬──────────────────────┘ + ▼ +┌─────────────────────────────────────┐ +│ ③ 执行沙箱 │ +│ - 命令白名单 │ +│ - 路径限制 │ +│ - 超时控制 │ +└──────────────┬──────────────────────┘ + ▼ +┌─────────────────────────────────────┐ +│ ④ 审计日志 │ +│ - 所有操作记录 │ +│ - 异常行为告警 │ +└──────────────┬──────────────────────┘ + ▼ + 执行完成
+
+
+ +
+ + + + diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..3daf227 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,116 @@ + + + + + +Global Control Assistant — 全局控制助手 + + + +
+ 首页 +
+ +
+

Global Control Assistant

+

任意设备控制任意设备 · AI 对话操作所有设备

+
自建客户端 = MCP Server · Gateway = MCP Host · 所有被控设备装客户端
+
+ +
+

这个项目是什么？

+
+

+ Global Control Assistant (GCA) 是一个跨设备远程控制与 AI 自动化系统。

+ 核心思路：1 台主机运行 OpenClaw Gateway（MCP Host，AI 大脑）。每台被控设备装一个自建客户端，客户端作为 MCP Server 暴露本机能力给 Gateway。不装客户端的设备不纳入控制范围。

+ 使用方式：通过任意通道（微信、飞书、Telegram、自建客户端）用自然语言告诉 AI 你要做什么——"看看服务器磁盘满了没"、"把手机照片传到电脑"、"重启游戏服务器"。AI 自动选择正确的设备和 MCP Tool 执行。

+ 自建客户端有两个功能：① 与 Gateway 沟通（聊天/远程桌面 UI）；② 暴露本机能力（MCP Server，让 AI 能操作这台设备）。 +

+
+ +

项目文档

+
+ +
🏗️
+

系统架构

+

连接流程、实现细节、配置

+ + +
🧩
+

能力全景

+

36 MCP Tools 定义

+ + +
🗺️
+

实施路线图

+

5 阶段开发计划

+ + +
🔒
+

安全分析

+

风险矩阵与安全机制

+ + +
🔧
+

维护优化

+

技术债务与可维护性

+ + +
📋
+

PM 审查

+

范围、风险、验收标准

+ + +
✅
+

开发代办

+

55 个任务 · 6 个模块

+ + +
🔄
+

系统流程

+

9 大核心流程完整走查

+ +
+ +

核心设计

+
+
+

🔀 任意 → 任意

+

手机找电脑文件、电脑查服务器日志、微信开关游戏服务器。发起方可以是任意设备或任意聊天通道。

+
+
+

🔌 客户端接入

+

所有被控设备装自建客户端（MCP Server + UI）。Gateway 统一调度所有客户端。

+
+
+

💬 AI 对话控制

+

通过微信/飞书/Telegram 用自然语言控制设备。AI 自动选择正确的设备和命令。

+
+
+

🖥️ 自建客户端

+

Android APK + Desktop (Tauri) + CLI。AI 对话 + 设备管理 + 远程桌面 UI。

+
+
+

🖱️ 远程桌面

+

客户端截取本机屏幕，通过 WS 数据端口推流到请求方。鼠标键盘事件实时转发。

+
+
+

🌍 外网访问

+

聊天通道（微信/飞书）不需要穿透 NAT。客户端直连用 Tailscale 或 DDNS-GO。

+
+
+

🧠 跨通道记忆

+

identityLinks 统一身份，MEMORY.md 跨通道持久记忆。微信说的事飞书也知道。

+
+
+

🔄 双轨更新

+

小更新 JS bundle OTA 静默推送（新增页面/修 Bug），大更新 APK 重装（原生模块变更）。

+
+
+
+ + + + diff --git a/docs/maintenance/index.html b/docs/maintenance/index.html new file mode 100644 index 0000000..341a12b --- /dev/null +++ b/docs/maintenance/index.html @@ -0,0 +1,100 @@ + + + + + +维护优化 — Global Control Assistant + + + +
+ 首页/ + 架构/ + 维护优化 +
+ +
+

项目维护优化清单

+

从项目维护角度审视架构、流程和技术债务

+ +
+
1
已解决
+
3
必须做
+
3
强烈建议
+
2
锦上添花
+
+ +
+

已解决

+
+
+

已解决 API 数量精简

+

从最初 180+ API 精简到 36 个 MCP Tool，用 exec 兜底低频操作。JSON Schema 自动校验。

+
+
+
+ +
+

必须做

+
+
+

P0 跨平台 UI 自动化

+

AI 应用操控需要 Accessibility API：Windows (UIAutomation)、Linux (AT-SPI2)、macOS (AX API)。三套 API，每个平台独立实现。

+
方案：① 定义 UIAdapter 接口，每平台一个实现；② Phase 1 只做 Windows；③ 优先用浏览器自动化（Playwright 跨平台一致）。
+
+
+

P0 缺少测试策略

+

36 MCP Tool × 多平台 × 多设备接入方式 = 测试矩阵。

+
方案：① 单元测试：每个 tool handler 独立测试；② 集成测试：客户端 MCP Server ↔ Gateway；③ E2E 测试：Telegram → AI → MCP Tool → 执行；④ CI：GitHub Actions。
+
+
+

P0 无错误恢复策略

+

网络断开、Gateway 重启、设备休眠。远程场景下错误是常态。

+
方案：① WS 自动重连（指数退避）；② 请求超时 + 重试；③ 幂等性设计（idempotency key）。
+
+
+
+ +
+

强烈建议

+
+
+

P1 无日志与可观测性

+

远程设备出问题时没有日志无法排查。

+
方案：① 结构化日志（pino/winston）；② 日志通过 WS 上报到 Gateway 集中查看；③ 健康心跳（30s 上报 CPU/内存/磁盘）。
+
+
+

P1 无配置管理方案

+

客户端需要配置（Gateway 地址、token、代理、服务开关）。

+
方案：① 本地 JSON 配置 + 系统 keychain 存凭据；② Gateway 可远程推送配置；③ JSON Schema 校验。
+
+
+

P1 无自动化构建发布

+

客户端要打包成 Windows .exe / Linux .deb / Android APK。手动打包耗时易错。

+
方案：① GitHub Actions CI；② tag push 自动构建所有平台；③ 自动更新机制（Tauri updater / Expo OTA）。
+
+
+
+ +
+

锦上添花

+
+
+

P2 文档迁移

+

当前手写 HTML，改一个样式要改多处。迁移到 VitePress 可用 Markdown 写内容。

+
+
+

P2 性能监控仪表盘

+

多设备运行后需要统一视图查看所有设备健康状态。

+
+
+
+
+ + + + diff --git a/docs/pm-review/index.html b/docs/pm-review/index.html new file mode 100644 index 0000000..c794ddb --- /dev/null +++ b/docs/pm-review/index.html @@ -0,0 +1,94 @@ + + + + + +项目经理审查 — Global Control Assistant + + + +
+ 首页/ + 架构/ + PM 审查 +
+ +
+

项目经理审查报告

+

从项目管理角度审视风险、范围、进度和资源

+ +
+

总体评估

+
+

+ 结论：范围过大，需要砍阶段。

+ 当前设计覆盖了 10 大类能力、4 个客户端平台、外网穿透、远程桌面、AI 操控——对一个个人开发者来说是 2-3 年的工作量。

+ 建议：Phase 1 严格控制范围，只做"通过聊天通道控制一台设备"。其他全部推后。先跑通核心链路。 +

+
+
+ +
+

关键问题

+
+
+

P0 范围过大

+

36 MCP Tool × 4 平台 × 外网穿透 × 远程桌面 × AI 操控 = 不可能在 28 周内完成。

+
建议：Phase 1 只做 10 个 Tool + 聊天通道控制。远程桌面、AI 操控、Android 客户端全部推到 Phase 2+。
+
+
+

P0 没有用户验证

+

设计了大量功能但没有验证用户是否需要。

+
建议：Phase 1 交付后自己用 2 周，记录哪些功能真正用到。根据实际使用调整优先级。
+
+
+

P0 外部依赖风险

+

OpenClaw 是核心依赖，MCP 支持可能变更、API 可能不稳定。

+
建议：① 锁定 OpenClaw 版本；② 所有交互封装在适配层；③ 关注 CHANGELOG。
+
+
+

P1 跨平台是最大技术风险

+

四个平台的屏幕捕获、输入模拟、UI 自动化都不同。

+
建议：Phase 1 只做 Windows。验证核心链路通了再扩平台。
+
+
+

P1 没有里程碑和验收标准

+

路线图有阶段划分，但没有明确的"完成"定义。

+
建议：每个 Phase 定义 3 个验收测试用例，全部通过才算完成。
+
+
+
+ +
+

各阶段验收标准

+
+ + + + + +
阶段验收用例完成定义
Phase 1① Telegram 发 "列出电脑文件" → 收到列表
② Telegram 发 "执行 dir" → 收到结果
③ 客户端重启后自动重连		3 个用例全部通过
Phase 2① Android 客户端看到 2+ 设备在线
② 手机找电脑文件成功
③ 跨设备远程桌面连接成功		3 个用例全部通过
Phase 3① 远程桌面操控流畅（<300ms）
② AI 自动打开记事本输入文字
③ 跨设备文件传输成功		3 个用例全部通过
+
+
+ +
+

建议的最小 MVP（2 周）

+
+

砍到不能再砍

+

+ 只做一件事：通过 Telegram 用自然语言在一台 Windows 电脑上执行命令并返回结果。

+ 技术栈：OpenClaw Gateway + 客户端 MCP Server（只实现 exec 和 file_list 两个 Tool）
+ 验证方式：Telegram 发 "dir C:\Users" → 收到目录列表
+ 不做的：远程桌面、Android 客户端、AI 操控、外网访问、多设备 +

+
+
+
+ + + + diff --git a/docs/roadmap/index.html b/docs/roadmap/index.html new file mode 100644 index 0000000..4e8a12c --- /dev/null +++ b/docs/roadmap/index.html @@ -0,0 +1,208 @@ + + + + + +实施路线图 — Global Control Assistant + + + + +
+ 首页/ + 架构/ + 实施路线图 +
+ +
+

实施路线图

+

五阶段渐进式开发，每个阶段交付独立可用的产品

+ +
+
5
实施阶段
+
28
总周数
+
36
MCP Tools
+
4
目标平台
+
+ +
+ +
+
+
+
+ Phase 1 +

基础 MVP

+ 第 1-4 周 +
+
+
目标：MCP Server 跑通，通过聊天通道控制一台设备
+
    +
  • 1安装配置 OpenClaw Gateway（主机），配置 mcpServers
    • +
  • 2实现客户端的 MCP Server 功能：10 个核心 MCP Tool（file_list/read/write、exec、process_list、sysinfo、power、notify_send）
    • +
  • 3客户端启动时自动通过 SSE 注册到 Gateway
    • +
  • 4端到端测试：Telegram/飞书发 "查看电脑上的文件" → AI 调用 MCP tool → 执行 → 返回
    • +
  • 5配置 session.identityLinks 跨通道记忆统一
    • +
+
交付物：客户端运行在主机，通过 Telegram/飞书/微信控制
+
+
+
+ + +
+
+
+
+ Phase 2 +

多设备 + Android 客户端

+ 第 5-10 周 +
+
+
目标：多设备 + Android 客户端 + 远程控制
+
    +
  • 1客户端跨平台：Linux / macOS 版本（复用 Windows 代码）
    • +
  • 2添加远程控制能力：屏幕截图/推流、鼠标键盘直通、剪贴板同步
    • +
  • 3自建 Android 客户端：设备列表、文件浏览器、远程终端、远程桌面、AI 聊天
    • +
  • 4跨设备操作：手机找电脑文件、电脑看手机截图
    • +
+
交付物：多设备互联，手机控制电脑
+
+
+
+ + +
+
+
+
+ Phase 3 +

桌面客户端 + 完善

+ 第 11-16 周 +
+
+
目标：桌面客户端 + AI 应用操控 + 完整体验
+
    +
  • 1自建 Tauri 桌面客户端：设备仪表盘、文件管理器、远程终端、远程桌面、系统监控
    • +
  • 2远程控制增强：MJPEG 推流（15-30fps）、鼠标键盘实时操控、多显示器、剪贴板同步
    • +
  • 3AI 应用操控：UI 元素操作（Accessibility API）、浏览器自动化、OCR 屏幕识别
    • +
  • 4跨设备文件传输：设备间直接传输文件
    • +
  • 5客户端连接生命周期：自动通联检测、Tailscale 按需启停、心跳保活、断线重连
    • +
  • 6打包为 Windows .exe + Linux .deb + Android APK
    • +
+
交付物：全平台客户端，AI 操控应用，跨设备文件传输
+
+
+
+ + +
+
+
+
+ Phase 4 +

智能家居与 IoT

+ 第 17-22 周 +
+
+
目标：扩展到计算机之外的设备
+
    +
  • 1轻量 IoT 客户端（树莓派 CLI 版）
    • +
  • 2智能家居集成（Tuya / SmartThings / Home Assistant）
    • +
  • 3定时任务（通过 OpenClaw cron，如每晚 2 点备份照片）
    • +
  • 4通知转发（手机通知 → 聊天通道）
    • +
+
交付物：统一控制 PC、手机和 IoT 设备
+
+
+
+ + +
+
+
+
+ Phase 5 +

安全加固与发布

+ 第 23-28 周 +
+
+
目标：生产级质量，可正式发布
+
    +
  • 1端到端加密（libsodium / NaCl）
    • +
  • 2基于角色的权限控制（如 "此通道只能读文件，不能执行命令"）
    • +
  • 3所有远程操作审计日志
    • +
  • 4客户端自动更新机制
    • +
  • 5发布：Play Store、GitHub Releases
    • +
  • 6文档和安装指南
    • +
+
交付物：可发布的正式产品
+
+
+
+
+ + +
+

风险与缓解

+
+ + + + + + +
风险影响缓解措施
OpenClaw MCP 协议变更集成困难适配层隔离；锁定 OpenClaw 版本
跨平台 UI 自动化开发效率Phase 1 只做 Windows；优先浏览器自动化
个人开发者精力有限进度延迟每阶段独立交付；Phase 1 仅需 4 周
外网访问不稳定连接中断Tailscale + DDNS-GO 双方案；心跳自动重连
+
+
+ + +
+

验证方式

+
+

Phase 1

Telegram 发 "列出电脑上的文件" → 收到文件列表

+

Phase 2

Android 客户端看到多台设备在线，手机找电脑文件成功

+

Phase 3

桌面客户端远程桌面操控流畅，AI 自动操作应用成功

+

Phase 4

"关闭客厅灯" → IoT 设备响应；定时备份执行

+

Phase 5

安全审计通过，自动更新正常，Play Store 上架

+
+
+
+ + + + diff --git a/docs/security/index.html b/docs/security/index.html new file mode 100644 index 0000000..7007cf5 --- /dev/null +++ b/docs/security/index.html @@ -0,0 +1,134 @@ + + + + + +安全分析 — Global Control Assistant + + + + +
+ 首页/ + 架构/ + 安全分析 +
+ +
+

可行性与安全性分析

+

基于 OpenClaw + MCP 架构的技术验证与风险评估

+ +
+
✓
整体可行
+
3
高风险
+
4
中风险
+
2
低风险
+
+ + +
+

技术可行性

+
+ + + + + + + +
评估项结论依据
Gateway MCP Host可行OpenClaw 原生支持 mcpServers 配置，自动发现 MCP Tools
客户端 MCP Server可行@modelcontextprotocol/sdk 成熟，SSE/WS 传输
远程桌面推流需要适配screenshot-desktop + Sharp + WS，跨平台有差异
UI 自动化平台差异大Windows UIAutomation / Linux AT-SPI2 / macOS AX API 三套
外网访问可行Tailscale + DDNS-GO 已验证可用
+
+
+ + +
+

高风险项

+
+
+

远程命令执行 — 命令注入

+

客户端暴露 exec MCP Tool，AI 被 prompt injection 攻击可能执行恶意命令。

+
缓解：OpenClaw exec approval 机制（allowlist + ask）；敏感命令黑名单；沙箱模式。
+
+
+

远程桌面 — 未授权访问

+

屏幕推流 + 鼠标键盘直通 = 完全控制。连接被劫持则设备沦陷。

+
缓解：Gateway auth token 强制认证；Tailscale 加密隧道；远程控制需被控端确认。
+
+
+

Prompt Injection — AI 被劫持

+

不受信内容（网页、邮件、文件）携带恶意指令，操纵 AI 执行危险操作。

+
缓解：使用旗舰模型；不受信内容用只读 reader agent 预处理；高风险工具走 approval。
+
+
+
+ + +
+

中风险项

+
+
+

Gateway Token 泄露

+

客户端存储 Gateway 认证 token，泄露则未授权设备可接入。

+
缓解：token 存储在系统 keychain；定期轮换；Gateway 侧可撤销已知设备。
+
+
+

剪贴板数据泄露

+

跨设备剪贴板同步可能无意中传输密码、token。

+
缓解：敏感模式检测；同步后自动清除远端剪贴板。
+
+
+

Gateway 单点故障

+

Gateway 挂掉导致所有设备失联、所有通道中断。

+
缓解：launchd/systemd 守护进程自动重启；健康检查告警。
+
+
+

外网暴露攻击面

+

Tailscale/DDNS-GO 暴露 Gateway 到外网，可能被扫描攻击。

+
缓解：Gateway auth token 必须设置；Tailscale 本身有加密；定期安全审计。
+
+
+
+ + +
+

低风险项

+
+
+

配置文件安全

+

客户端本地存储 Gateway token、Headscale 密钥等凭据。

+
缓解：使用系统 keychain 存储凭据；不写入明文配置文件。
+
+
+

第三方依赖漏洞

+

systeminformation/screenshot-desktop/@modelcontextprotocol/sdk 等 npm 包可能存在安全漏洞。

+
缓解：npm audit 定期检查；锁定版本；关键依赖 fork。
+
+
+
+ + +
+

可复用的 OpenClaw 安全机制

+
+

设备配对

challenge 签名 + 人工审批，防止未授权设备接入

+

工具策略

per-agent allow/deny 列表，AI 只能看到被允许的 Tools

+

Exec Approval

命令执行审批机制，allowlist + 每次确认

+

沙箱模式

Docker 容器隔离工具执行，限制文件系统和网络访问

+

安全审计

openclaw security audit 自动检查配置风险

+

会话隔离

dmScope: per-peer，不同用户上下文隔离

+
+
+
+ + + + diff --git a/docs/style.css b/docs/style.css new file mode 100644 index 0000000..60c16d3 --- /dev/null +++ b/docs/style.css @@ -0,0 +1,164 @@ +:root{--bg:#0f172a;--card:#1e293b;--border:#334155;--accent:#3b82f6;--accent2:#8b5cf6;--accent3:#06b6d4;--text:#e2e8f0;--dim:#94a3b8;--green:#22c55e;--orange:#f59e0b;--red:#ef4444;--pink:#ec4899;--amber:#f59e0b;--lime:#84cc16;--teal:#14b8a6;--sky:#0ea5e9} +*{margin:0;padding:0;box-sizing:border-box} +body{font-family:'Segoe UI',system-ui,-apple-system,sans-serif;background:var(--bg);color:var(--text);min-height:100vh;line-height:1.6} + +/* Topbar */ +.topbar{position:sticky;top:0;z-index:100;background:rgba(15,23,42,.92);backdrop-filter:blur(12px);border-bottom:1px solid var(--border);padding:12px 24px;display:flex;align-items:center;gap:14px;flex-wrap:wrap} +.topbar a{color:var(--dim);text-decoration:none;font-size:.88rem;transition:color .2s} +.topbar a:hover{color:var(--accent)} +.topbar .sep{color:var(--border)} +.topbar .current{color:var(--text);font-weight:600} + +/* Layout */ +.container{max-width:1200px;margin:0 auto;padding:40px 20px} +h1{font-size:2rem;font-weight:800;margin-bottom:8px} +h2{font-size:1.3rem;font-weight:700;margin-bottom:16px;display:flex;align-items:center;gap:10px} +h2 .dot{width:10px;height:10px;border-radius:50%;flex-shrink:0} +h3{font-size:1rem;margin:20px 0 10px;color:var(--accent2)} +.subtitle{color:var(--dim);margin-bottom:40px;font-size:1rem} + +/* Grid */ +.grid{display:grid;gap:14px} +.grid-2{grid-template-columns:repeat(auto-fit,minmax(340px,1fr))} +.grid-3{grid-template-columns:repeat(auto-fit,minmax(280px,1fr))} + +/* Card */ +.card{background:var(--card);border:1px solid var(--border);border-radius:14px;padding:20px;transition:all .3s} +.card:hover{border-color:var(--accent);box-shadow:0 4px 20px rgba(59,130,246,.08)} +.card h4{font-size:.95rem;margin-bottom:6px;display:flex;align-items:center;gap:8px} +.card p{color:var(--dim);font-size:.82rem;line-height:1.5} + +/* Nav card */ +.nav-cards{display:grid;grid-template-columns:repeat(auto-fit,minmax(200px,1fr));gap:12px} +.nav-card{background:var(--card);border:1px solid var(--border);border-radius:14px;padding:24px 16px;text-align:center;text-decoration:none;color:var(--text);transition:all .3s} +.nav-card:hover{border-color:var(--accent);transform:translateY(-3px);box-shadow:0 8px 32px rgba(59,130,246,.12)} +.nav-card .emoji{font-size:2rem;margin-bottom:8px} +.nav-card h3{margin-bottom:4px;font-size:1rem} +.nav-card p{color:var(--dim);font-size:.78rem} + +/* Summary bar */ +.summary-bar{display:grid;grid-template-columns:repeat(auto-fit,minmax(130px,1fr));gap:12px;margin-bottom:40px} +.s-item{background:var(--card);border:1px solid var(--border);border-radius:12px;padding:14px;text-align:center} +.s-item .num{font-size:1.8rem;font-weight:800} +.s-item .label{color:var(--dim);font-size:.72rem;margin-top:2px} + +/* Tags */ +.tag{display:inline-block;padding:3px 10px;border-radius:10px;font-size:.72rem;font-weight:600} +.t-red{background:rgba(239,68,68,.15);color:var(--red)} +.t-orange{background:rgba(245,158,11,.15);color:var(--orange)} +.t-blue{background:rgba(59,130,246,.15);color:var(--accent)} +.t-green{background:rgba(34,197,94,.15);color:var(--green)} +.t-purple{background:rgba(139,92,246,.15);color:var(--accent2)} +.t-pink{background:rgba(236,72,153,.15);color:var(--pink)} +.t-cyan{background:rgba(6,182,212,.15);color:var(--accent3)} + +/* Table */ +.table-wrap{overflow-x:auto;margin-bottom:20px} +table{width:100%;border-collapse:collapse;font-size:.85rem} +th{text-align:left;padding:10px 14px;background:rgba(59,130,246,.08);border-bottom:2px solid var(--border);color:var(--accent);font-weight:600} +td{padding:10px 14px;border-bottom:1px solid var(--border);color:var(--dim)} +tr:hover td{background:rgba(59,130,246,.03)} +td:first-child{color:var(--text);font-weight:500} + +/* Service grid */ +.svc-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:10px} +.svc{background:var(--card);border:1px solid var(--border);border-radius:12px;padding:14px;text-align:center;transition:all .3s} +.svc:hover{border-color:var(--accent);transform:translateY(-1px)} +.svc .icon{font-size:1.5rem;margin-bottom:6px} +.svc h4{font-size:.85rem;margin-bottom:2px} +.svc p{color:var(--dim);font-size:.72rem} + +/* Code block */ +.code-block{background:#0d1117;border:1px solid var(--border);border-radius:12px;padding:18px;overflow-x:auto;font-family:'Cascadia Code','Fira Code','Consolas',monospace;font-size:.8rem;line-height:1.7;color:#c9d1d9;position:relative} +.code-block .lang{position:absolute;top:8px;right:12px;font-size:.68rem;color:var(--dim);text-transform:uppercase;letter-spacing:1px} +.code-block pre{margin:0} +.key{color:#7ee787} +.str{color:#a5d6ff} +.num{color:#79c0ff} +.bool{color:#ff7b72} +.comment{color:#8b949e} + +/* Diagram */ +.diagram{background:var(--card);border:1px solid var(--border);border-radius:14px;padding:20px;font-family:'Cascadia Code','Fira Code','Consolas',monospace;font-size:.76rem;line-height:1.8;overflow-x:auto;white-space:pre} +.diagram .hl{color:var(--accent);font-weight:700} +.diagram .hi{color:var(--pink);font-weight:700} +.diagram .gr{color:var(--green);font-weight:700} +.diagram .dim{color:var(--dim)} + +/* Before-after */ +.before-after{display:grid;grid-template-columns:1fr 36px 1fr;gap:10px;align-items:start;margin:16px 0} +.ba-box{background:var(--card);border:1px solid var(--border);border-radius:10px;padding:14px;font-family:'Cascadia Code','Fira Code','Consolas',monospace;font-size:.76rem;line-height:1.7;overflow-x:auto} +.ba-box.before{border-color:rgba(239,68,68,.3)} +.ba-box.after{border-color:rgba(34,197,94,.3)} +.ba-arrow{display:flex;align-items:center;justify-content:center;font-size:1.3rem;color:var(--dim)} +.ba-label{font-size:.68rem;font-weight:700;text-transform:uppercase;letter-spacing:1px;margin-bottom:6px;display:block} +.ba-label.red{color:var(--red)} +.ba-label.green{color:var(--green)} + +/* Highlight box */ +.highlight{background:rgba(34,197,94,.06);border:1px solid rgba(34,197,94,.2);border-radius:14px;padding:18px;margin-bottom:16px} +.highlight h4{color:var(--green);margin-bottom:6px;font-size:.95rem} +.highlight p{color:var(--dim);font-size:.85rem;line-height:1.5} + +/* Issue card */ +.issue-grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(340px,1fr));gap:14px} +.issue{background:var(--card);border:1px solid var(--border);border-radius:14px;padding:18px;transition:all .3s} +.issue:hover{border-color:var(--accent)} +.issue h4{font-size:.92rem;margin-bottom:6px;display:flex;align-items:center;gap:6px} +.issue>p{color:var(--dim);font-size:.82rem;line-height:1.5;margin-bottom:10px} +.issue .fix{font-size:.8rem;padding:10px 14px;background:rgba(34,197,94,.05);border:1px solid rgba(34,197,94,.12);border-radius:8px;line-height:1.6} +.issue .fix strong{color:var(--green)} + +/* Risk card */ +.risk-matrix{display:grid;grid-template-columns:repeat(auto-fill,minmax(300px,1fr));gap:14px} +.risk{background:var(--card);border-left:4px solid;border-radius:0 12px 12px 0;padding:16px 18px} +.risk h4{font-size:.9rem;margin-bottom:6px} +.risk p{color:var(--dim);font-size:.82rem;line-height:1.5} +.risk .fix{margin-top:8px;font-size:.8rem;padding:8px 12px;background:rgba(255,255,255,.03);border-radius:8px} +.risk .fix strong{color:var(--green)} +.risk-critical{border-color:var(--red)} +.risk-high{border-color:var(--orange)} +.risk-medium{border-color:var(--accent)} +.risk-low{border-color:var(--green)} + +/* Capability card */ +.cap-grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(320px,1fr));gap:12px} +.cap{background:var(--card);border:1px solid var(--border);border-radius:12px;padding:16px;transition:all .3s} +.cap:hover{border-color:var(--accent)} +.cap h4{font-size:.92rem;margin-bottom:4px;display:flex;align-items:center;gap:6px} +.cap p{color:var(--dim);font-size:.8rem;line-height:1.4;margin-bottom:6px} +.cap-methods{display:flex;flex-wrap:wrap;gap:3px} +.mtag{padding:2px 7px;border-radius:5px;font-size:.68rem;font-weight:600;font-family:'Cascadia Code','Fira Code','Consolas',monospace;background:rgba(59,130,246,.1);color:var(--accent)} +.mtag.green{background:rgba(34,197,94,.1);color:var(--green)} +.mtag.purple{background:rgba(139,92,246,.1);color:var(--accent2)} +.mtag.pink{background:rgba(236,72,153,.1);color:var(--pink)} +.mtag.orange{background:rgba(245,158,11,.1);color:var(--orange)} +.mtag.cyan{background:rgba(6,182,212,.1);color:var(--accent3)} +.mtag.red{background:rgba(239,68,68,.1);color:var(--red)} + +/* Hero */ +.hero{text-align:center;padding:60px 20px 32px;background:linear-gradient(135deg,#0f172a 0%,#1e1b4b 50%,#0f172a 100%);position:relative;overflow:hidden} +.hero::before{content:'';position:absolute;top:-50%;left:-50%;width:200%;height:200%;background:radial-gradient(circle at 30% 50%,rgba(59,130,246,.06) 0%,transparent 50%),radial-gradient(circle at 70% 50%,rgba(139,92,246,.06) 0%,transparent 50%);animation:pulse 8s ease-in-out infinite} +@keyframes pulse{0%,100%{transform:scale(1)}50%{transform:scale(1.05)}} +.hero h1{font-size:2.5rem;font-weight:800;background:linear-gradient(135deg,var(--accent),var(--accent2),var(--accent3));-webkit-background-clip:text;-webkit-text-fill-color:transparent;background-clip:text;position:relative} +.hero p{color:var(--dim);font-size:1.1rem;margin-top:10px;position:relative} +.hero .badge{display:inline-block;margin-top:16px;padding:5px 14px;border-radius:18px;background:rgba(59,130,246,.12);border:1px solid rgba(59,130,246,.25);color:var(--accent);font-size:.82rem;position:relative} + +/* Footer */ +footer{text-align:center;padding:40px 20px;color:var(--dim);font-size:.78rem;border-top:1px solid var(--border);margin-top:40px} +footer a{color:var(--accent);text-decoration:none} +footer a:hover{text-decoration:underline} + +/* Section */ +.section{margin-bottom:40px} + +/* Backlog / Task table */ +.module{margin-bottom:40px} +.module h2{font-size:1.15rem;margin-bottom:14px;display:flex;align-items:center;gap:8px} +.module h2 .dot{width:10px;height:10px;border-radius:50%;flex-shrink:0} +.task-table{width:100%;border-collapse:collapse;font-size:.82rem;margin-bottom:12px} +.task-table th{text-align:left;padding:8px 12px;background:rgba(59,130,246,.06);border-bottom:2px solid var(--border);color:var(--accent);font-weight:600;font-size:.75rem} +.task-table td{padding:7px 12px;border-bottom:1px solid var(--border);color:var(--dim);font-size:.82rem} +.task-table tr:hover td{background:rgba(59,130,246,.02)} +.task-table td:first-child{color:var(--text);font-weight:500;font-family:'Cascadia Code','Fira Code','Consolas',monospace;font-size:.78rem;white-space:nowrap} +.task-table td:nth-child(2){color:var(--text)}