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
This commit is contained in:
Childish-Ghost
374
docs/flow/index.html
Normal file
374
docs/flow/index.html
Normal file
@@ -0,0 +1,374 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>系统流程 — Global Control Assistant</title>
|
||||
<link rel="stylesheet" href="style.css">
|
||||
<style>
|
||||
.flow-section{margin-bottom:40px}
|
||||
.flow-section h2{font-size:1.2rem;margin-bottom:16px;display:flex;align-items:center;gap:8px}
|
||||
.flow-box{background:var(--card);border:1px solid var(--border);border-radius:12px;padding:20px;margin-bottom:16px}
|
||||
.flow-box h4{font-size:.95rem;margin-bottom:8px;color:var(--accent)}
|
||||
.flow-box p{color:var(--dim);font-size:.85rem;line-height:1.6}
|
||||
.step-list{list-style:none;counter-reset:step}
|
||||
.step-list li{counter-increment:step;padding:10px 14px;margin-bottom:8px;background:rgba(255,255,255,.02);border-radius:8px;font-size:.85rem;color:var(--dim);line-height:1.5;display:flex;align-items:flex-start;gap:10px}
|
||||
.step-list li::before{content:counter(step);min-width:24px;height:24px;border-radius:50%;background:var(--accent);color:white;display:flex;align-items:center;justify-content:center;font-size:.75rem;font-weight:700;flex-shrink:0}
|
||||
.step-list li b{color:var(--text)}
|
||||
.diagram-box{background:#0d1117;border:1px solid var(--border);border-radius:12px;padding:20px;font-family:'Cascadia Code','Fira Code',monospace;font-size:.78rem;line-height:1.6;overflow-x:auto;white-space:pre;color:#c9d1d9;margin-bottom:16px}
|
||||
.tag{display:inline-block;padding:2px 8px;border-radius:6px;font-size:.7rem;font-weight:600}
|
||||
.t-green{background:rgba(34,197,94,.15);color:var(--green)}
|
||||
.t-blue{background:rgba(59,130,246,.15);color:var(--accent)}
|
||||
.t-orange{background:rgba(245,158,11,.15);color:var(--orange)}
|
||||
.t-pink{background:rgba(236,72,153,.15);color:var(--pink)}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="topbar">
|
||||
<a href="index.html">首页</a><span class="sep">/</span>
|
||||
<a href="architecture/index.html">架构</a><span class="sep">/</span>
|
||||
<a href="capabilities/index.html">能力</a><span class="sep">/</span>
|
||||
<a href="roadmap/index.html">路线图</a><span class="sep">/</span>
|
||||
<a href="backlog/index.html">代办</a><span class="sep">/</span>
|
||||
<a href="security/index.html">安全</a><span class="sep">/</span>
|
||||
<span class="current">流程</span>
|
||||
</div>
|
||||
|
||||
<div class="container">
|
||||
<h1>系统流程</h1>
|
||||
<p class="subtitle">GCA 系统中各个核心流程的完整走查</p>
|
||||
|
||||
<!-- ===== 1. 客户端启动流程 ===== -->
|
||||
<div class="flow-section">
|
||||
<h2>1. 客户端启动流程</h2>
|
||||
<div class="flow-box">
|
||||
<h4>客户端打开后的完整启动链路</h4>
|
||||
<ol class="step-list">
|
||||
<li><b>App 启动</b> → 加载本地配置（Gateway 地址、Token、代理设置）</li>
|
||||
<li><b>启动 MCP Server</b> → 客户端内置 MCP Server 开始监听，暴露本机能力（file/exec/screen/sysinfo 等）</li>
|
||||
<li><b>连接 Gateway</b> → WebSocket 连接 OpenClaw Gateway，发送认证 Token</li>
|
||||
<li><b>注册设备</b> → 向 Gateway 报告设备信息（名称、IP、OS、能力列表）</li>
|
||||
<li><b>开始心跳</b> → 每 30 秒发送心跳，Gateway 更新设备在线状态</li>
|
||||
<li><b>OTA 检查</b> → 启动 3 秒后检查一次更新，之后每 24 小时检查一次</li>
|
||||
<li><b>就绪</b> → 设备出现在 Gateway 设备列表中，可被 AI 或其他设备调用</li>
|
||||
</ol>
|
||||
</div>
|
||||
|
||||
<div class="diagram-box">客户端启动
|
||||
│
|
||||
├── 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</div>
|
||||
</div>
|
||||
|
||||
<!-- ===== 2. AI 控制设备流程 ===== -->
|
||||
<div class="flow-section">
|
||||
<h2>2. AI 控制设备流程</h2>
|
||||
<div class="flow-box">
|
||||
<h4>用户通过任意通道发送自然语言指令</h4>
|
||||
<ol class="step-list">
|
||||
<li><b>用户发消息</b> → 通过微信/飞书/Telegram/自建客户端发送："看看服务器磁盘满了没"</li>
|
||||
<li><b>Gateway 接收</b> → OpenClaw Gateway 的 AI Agent 接收消息，理解意图</li>
|
||||
<li><b>AI 选择工具</b> → AI 决定调用 <code>exec</code> 工具，参数 <code>device="cloud-svr", command="df -h"</code></li>
|
||||
<li><b>Gateway 路由</b> → Gateway 将 MCP Tool 调用转发到 cloud-svr 客户端</li>
|
||||
<li><b>客户端执行</b> → cloud-svr 的 MCP Server 执行 <code>df -h</code>，返回磁盘信息</li>
|
||||
<li><b>AI 格式化</b> → AI 将原始数据格式化为易读的回复</li>
|
||||
<li><b>回复用户</b> → 通过原通道返回结果给用户</li>
|
||||
</ol>
|
||||
</div>
|
||||
|
||||
<div class="diagram-box">用户: "看看服务器磁盘满了没"
|
||||
│
|
||||
▼
|
||||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||
│ 任意通道 │───▶│ Gateway │───▶│ cloud-svr │
|
||||
│ 微信/飞书/ │ │ AI Agent │ │ 客户端 │
|
||||
│ Telegram │ │ │ │ MCP Server │
|
||||
└─────────────┘ └──────┬──────┘ └──────┬──────┘
|
||||
│ │
|
||||
│ MCP Tool 调用 │
|
||||
│ exec("df -h") │
|
||||
│──────────────────▶│
|
||||
│ │
|
||||
│ 执行结果 │
|
||||
│◀──────────────────│
|
||||
│ │
|
||||
│ AI 格式化回复 │
|
||||
▼ │
|
||||
"磁盘使用率 78%， │
|
||||
剩余 120GB" │
|
||||
│ │
|
||||
▼ │
|
||||
回复给用户 │</div>
|
||||
</div>
|
||||
|
||||
<!-- ===== 3. 人工远程控制流程 ===== -->
|
||||
<div class="flow-section">
|
||||
<h2>3. 人工远程控制流程</h2>
|
||||
<div class="flow-box">
|
||||
<h4>用户通过客户端直接操控远端设备（类 TeamViewer）</h4>
|
||||
<ol class="step-list">
|
||||
<li><b>选择设备</b> → 在客户端设备列表中点击目标设备</li>
|
||||
<li><b>发起远程桌面</b> → 客户端发送 <code>screen_stream_start</code> 请求</li>
|
||||
<li><b>建立数据通道</b> → 客户端与目标设备建立 WebSocket 直连（不经过 Gateway，低延迟）</li>
|
||||
<li><b>屏幕推流</b> → 目标设备以 MJPEG 格式推流（15-30fps）</li>
|
||||
<li><b>输入转发</b> → 用户的鼠标/键盘操作通过数据通道实时转发到目标设备</li>
|
||||
<li><b>剪贴板同步</b> → 双向剪贴板同步（可选）</li>
|
||||
<li><b>结束</b> → 用户断开，数据通道关闭</li>
|
||||
</ol>
|
||||
</div>
|
||||
|
||||
<div class="diagram-box">用户客户端 Gateway 目标设备
|
||||
│ │ │
|
||||
│ ① 请求远程桌面 │ │
|
||||
│ MCP: screen_stream_start │ │
|
||||
│───────────────────────────▶│ │
|
||||
│ │ ② 转发请求 │
|
||||
│ │─────────────────────────▶│
|
||||
│ │ │
|
||||
│ │ ③ 返回数据通道地址 │
|
||||
│ │◀─────────────────────────│
|
||||
│ ④ 数据通道地址 │ │
|
||||
│◀───────────────────────────│ │
|
||||
│ │
|
||||
│ ⑤ 直连数据通道 (WebSocket) │
|
||||
│◀══════════════════════════════════════════════════════▶│
|
||||
│ │
|
||||
│ ⑥ 屏幕推流 (MJPEG 15-30fps) │
|
||||
│◀──────────────────────────────────────────────────────│
|
||||
│ │
|
||||
│ ⑦ 鼠标/键盘事件 │
|
||||
│───────────────────────────────────────────────────────▶│
|
||||
│ │
|
||||
│ ⑧ 剪贴板同步 (可选) │
|
||||
│◀══════════════════════════════════════════════════════▶│</div>
|
||||
</div>
|
||||
|
||||
<!-- ===== 4. AI 自动操控应用流程 ===== -->
|
||||
<div class="flow-section">
|
||||
<h2>4. AI 自动操控应用流程</h2>
|
||||
<div class="flow-box">
|
||||
<h4>AI 代理自动操作设备上的应用（无需人工干预）</h4>
|
||||
<ol class="step-list">
|
||||
<li><b>用户指令</b> → "帮我打开 Chrome，搜索今天的天气"</li>
|
||||
<li><b>AI 分解任务</b> → ① 启动 Chrome ② 打开 Google ③ 输入搜索词 ④ 点击搜索</li>
|
||||
<li><b>执行 Step 1</b> → MCP Tool: <code>exec("home-pc", "start chrome")</code></li>
|
||||
<li><b>执行 Step 2</b> → MCP Tool: <code>browser_open("home-pc", "https://google.com")</code></li>
|
||||
<li><b>执行 Step 3</b> → MCP Tool: <code>browser_fill("home-pc", "input[name=q]", "今天天气")</code></li>
|
||||
<li><b>执行 Step 4</b> → MCP Tool: <code>browser_click("home-pc", "input[name=btnK]")</code></li>
|
||||
<li><b>返回结果</b> → 截图返回给用户</li>
|
||||
</ol>
|
||||
</div>
|
||||
|
||||
<div class="diagram-box">用户: "帮我打开 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 客户端执行</div>
|
||||
</div>
|
||||
|
||||
<!-- ===== 5. 跨设备文件传输流程 ===== -->
|
||||
<div class="flow-section">
|
||||
<h2>5. 跨设备文件传输流程</h2>
|
||||
<div class="flow-box">
|
||||
<h4>从一台设备传输文件到另一台设备</h4>
|
||||
<ol class="step-list">
|
||||
<li><b>用户指令</b> → "把 NAS 上的 backup.zip 传到电脑桌面"</li>
|
||||
<li><b>AI 调用</b> → MCP Tool: <code>file_transfer("nas", "/backup/backup.zip", "home-pc", "C:\\Desktop\\")</code></li>
|
||||
<li><b>Gateway 协调</b> → Gateway 分别连接 NAS 和 home-pc 的 MCP Server</li>
|
||||
<li><b>NAS 读取</b> → NAS 客户端读取文件，通过数据通道流式传输</li>
|
||||
<li><b>PC 写入</b> → home-pc 客户端接收并写入目标路径</li>
|
||||
<li><b>完成</b> → 返回传输结果（文件大小、耗时）</li>
|
||||
</ol>
|
||||
</div>
|
||||
|
||||
<div class="diagram-box">用户: "把 NAS 上的 backup.zip 传到电脑桌面"
|
||||
│
|
||||
▼
|
||||
Gateway AI → file_transfer("nas", "/backup.zip", "home-pc", "C:\Desktop\")
|
||||
│
|
||||
├── NAS 客户端 Gateway home-pc 客户端
|
||||
│ │ │ │
|
||||
│ │ ① 读取文件 │ │
|
||||
│ │◀──────────────────│ │
|
||||
│ │ │ │
|
||||
│ │ ② 流式传输 │ │
|
||||
│ │──────────────────▶│ │
|
||||
│ │ │ ③ 写入文件 │
|
||||
│ │ │─────────────────────▶│
|
||||
│ │ │ │
|
||||
│ │ │ ④ 完成确认 │
|
||||
│ │ │◀─────────────────────│
|
||||
│ │ │ │
|
||||
└─────┴───────────────────┴──────────────────────┘
|
||||
│
|
||||
▼
|
||||
"传输完成，128MB，耗时 3.2s"</div>
|
||||
</div>
|
||||
|
||||
<!-- ===== 6. OTA 更新流程 ===== -->
|
||||
<div class="flow-section">
|
||||
<h2>6. OTA 更新流程</h2>
|
||||
<div class="flow-box">
|
||||
<h4>JS bundle 静默更新（小更新）</h4>
|
||||
<ol class="step-list">
|
||||
<li><b>开发者修改代码</b> → 修改 JS/TS 代码（新增页面、修 Bug、改 UI）</li>
|
||||
<li><b>导出 bundle</b> → <code>npx expo export --platform android</code> 生成 JS bundle</li>
|
||||
<li><b>上传到 Gitee</b> → 将 bundle 上传到 Gitee 静态仓库</li>
|
||||
<li><b>App 检查更新</b> → 启动时 + 每 24 小时自动检查</li>
|
||||
<li><b>静默下载</b> → 发现新版，后台下载 JS bundle（~1-2MB）</li>
|
||||
<li><b>下次启动生效</b> → 用户下次打开 App 自动使用新版本</li>
|
||||
</ol>
|
||||
</div>
|
||||
|
||||
<div class="flow-box">
|
||||
<h4>APK 重装（大更新）</h4>
|
||||
<ol class="step-list">
|
||||
<li><b>开发者修改原生代码</b> → 新增原生模块、改图标、升级 RN</li>
|
||||
<li><b>构建 APK</b> → <code>eas build -p android --profile preview</code></li>
|
||||
<li><b>发布到 Gitee</b> → 上传 APK 到 Releases</li>
|
||||
<li><b>通知用户</b> → App 内提示有新版本</li>
|
||||
<li><b>用户手动安装</b> → 下载 APK 并安装</li>
|
||||
</ol>
|
||||
</div>
|
||||
|
||||
<div class="diagram-box">小更新 (JS bundle OTA):
|
||||
开发者 → expo export → 上传 Gitee → App 自动检查 → 静默下载 → 下次启动生效
|
||||
用户无感，1-2MB，几秒钟完成
|
||||
|
||||
大更新 (APK 重装):
|
||||
开发者 → eas build → 上传 Gitee Releases → App 提示 → 用户手动下载安装
|
||||
需要用户操作，15-30MB</div>
|
||||
</div>
|
||||
|
||||
<!-- ===== 7. 多通道记忆流程 ===== -->
|
||||
<div class="flow-section">
|
||||
<h2>7. 多通道记忆流程</h2>
|
||||
<div class="flow-box">
|
||||
<h4>用户在不同通道的对话如何统一记忆</h4>
|
||||
<ol class="step-list">
|
||||
<li><b>身份映射</b> → OpenClaw 的 <code>identityLinks</code> 将微信/飞书/Telegram 账号映射为同一用户</li>
|
||||
<li><b>会话共享</b> → <code>dmScope: "per-peer"</code> 确保同一用户跨通道共享会话上下文</li>
|
||||
<li><b>记忆存储</b> → <code>MEMORY.md</code> 存储持久记忆（设备信息、用户偏好、操作历史）</li>
|
||||
<li><b>每日笔记</b> → <code>memory/YYYY-MM-DD.md</code> 记录当天操作日志</li>
|
||||
<li><b>记忆蒸馏</b> → Dreaming 系统自动从每日笔记中提取有价值信息晋升到长期记忆</li>
|
||||
<li><b>跨通道回忆</b> → 在飞书中问"刚才微信说的那个文件在哪"，AI 能从记忆中找到</li>
|
||||
</ol>
|
||||
</div>
|
||||
|
||||
<div class="diagram-box">微信: "帮我备份桌面 PDF"
|
||||
│
|
||||
▼
|
||||
AI 执行 file_list + file_move → 完成
|
||||
│
|
||||
├── 写入 memory/2026-07-16.md:
|
||||
│ "用户要求备份桌面 PDF，已移动 12 个文件到 D:\备份\"
|
||||
│
|
||||
▼
|
||||
飞书 (3小时后): "刚才那个备份做了吗？"
|
||||
│
|
||||
▼
|
||||
AI → memory_search("备份 PDF") → 找到今日笔记
|
||||
│
|
||||
▼
|
||||
"已备份，共 12 个 PDF 文件到 D:\备份\"</div>
|
||||
</div>
|
||||
|
||||
<!-- ===== 8. 设备连接生命周期 ===== -->
|
||||
<div class="flow-section">
|
||||
<h2>8. 设备连接生命周期</h2>
|
||||
<div class="flow-box">
|
||||
<h4>设备从离线到在线的完整流程</h4>
|
||||
<div class="diagram-box">设备状态流转:
|
||||
|
||||
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 │
|
||||
└──────────────────────────────────────────────┘</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- ===== 9. 安全控制流程 ===== -->
|
||||
<div class="flow-section">
|
||||
<h2>9. 安全控制流程</h2>
|
||||
<div class="flow-box">
|
||||
<h4>多层安全防护</h4>
|
||||
<div class="diagram-box">请求进入
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────┐
|
||||
│ ① 身份验证 │
|
||||
│ - Gateway Token 认证 │
|
||||
│ - 设备配对 Token │
|
||||
│ - 通道身份验证 (微信/飞书) │
|
||||
└──────────────┬──────────────────────┘
|
||||
▼
|
||||
┌─────────────────────────────────────┐
|
||||
│ ② 权限控制 │
|
||||
│ - Tool 白名单/黑名单 │
|
||||
│ - 设备级权限 │
|
||||
│ - 通道级权限 │
|
||||
└──────────────┬──────────────────────┘
|
||||
▼
|
||||
┌─────────────────────────────────────┐
|
||||
│ ③ 执行沙箱 │
|
||||
│ - 命令白名单 │
|
||||
│ - 路径限制 │
|
||||
│ - 超时控制 │
|
||||
└──────────────┬──────────────────────┘
|
||||
▼
|
||||
┌─────────────────────────────────────┐
|
||||
│ ④ 审计日志 │
|
||||
│ - 所有操作记录 │
|
||||
│ - 异常行为告警 │
|
||||
└──────────────┬──────────────────────┘
|
||||
▼
|
||||
执行完成</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
<footer>
|
||||
<a href="index.html">首页</a> | <a href="architecture/index.html">架构</a>
|
||||
<br><br>
|
||||
Global Control Assistant © 2026
|
||||
</footer>
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user