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
2026-07-18 22:17:37 +08:00
commit 7f84ea56fc
11 changed files with 2386 additions and 0 deletions
--- a/docs/backlog/index.html
+++ b/docs/backlog/index.html
@@ -0,0 +1,164 @@
+<!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">
+</head>
+<body>
+<div class="topbar">
+  <a href="../index.html">首页</a><span class="sep">/</span>
+  <a href="../architecture/index.html">架构</a><span class="sep">/</span>
+  <span class="current">开发代办</span>
+</div>
+
+<div class="container">
+  <h1>开发代办清单</h1>
+  <p class="subtitle">按模块拆分，每个功能独立任务</p>
+
+  <div class="summary-bar">
+    <div class="s-item"><div class="num" style="color:var(--accent)">6</div><div class="label">模块</div></div>
+    <div class="s-item"><div class="num" style="color:var(--green)">55</div><div class="label">任务总数</div></div>
+    <div class="s-item"><div class="num" style="color:var(--red)">15</div><div class="label">P0</div></div>
+    <div class="s-item"><div class="num" style="color:var(--orange)">20</div><div class="label">P1</div></div>
+    <div class="s-item"><div class="num" style="color:var(--accent2)">20</div><div class="label">P2</div></div>
+  </div>
+
+  <!-- 模块 1 -->
+  <div class="module">
+    <h2><span class="dot" style="background:var(--accent)"></span> 模块 1：shared — 共享类型与协议</h2>
+    <table class="task-table">
+      <tr><th>编号</th><th>任务</th><th>说明</th><th>优先级</th><th>依赖</th></tr>
+      <tr><td>S-001</td><td>定义 MCP Tool 类型</td><td>36 个 Tool 的 TypeScript 类型（name、inputSchema、outputSchema）</td><td><span class="tag t-red">P0</span></td><td>—</td></tr>
+      <tr><td>S-002</td><td>定义设备配置类型</td><td>设备信息、连接配置、代理配置接口</td><td><span class="tag t-red">P0</span></td><td>—</td></tr>
+      <tr><td>S-003</td><td>定义数据通道协议</td><td>屏幕推流、文件传输、键鼠事件的 WS 消息格式</td><td><span class="tag t-orange">P1</span></td><td>—</td></tr>
+      <tr><td>S-004</td><td>定义客户端状态类型</td><td>连接状态、Tailscale 状态、设备在线状态枚举</td><td><span class="tag t-orange">P1</span></td><td>—</td></tr>
+      <tr><td>S-005</td><td>JSON Schema 生成</td><td>从 TypeScript 类型自动生成 JSON Schema</td><td><span class="tag t-purple">P2</span></td><td>S-001</td></tr>
+    </table>
+  </div>
+
+  <!-- 模块 2 -->
+  <div class="module">
+    <h2><span class="dot" style="background:var(--green)"></span> 模块 2：client/server — MCP Server 核心</h2>
+    <table class="task-table">
+      <tr><th>编号</th><th>任务</th><th>说明</th><th>优先级</th><th>依赖</th></tr>
+      <tr><td>C-001</td><td>MCP Server 框架</td><td>用 @modelcontextprotocol/sdk 搭建基础框架，SSE 传输</td><td><span class="tag t-red">P0</span></td><td>S-001</td></tr>
+      <tr><td>C-002</td><td>file_list Tool</td><td>列出目录内容，支持 glob 过滤和递归</td><td><span class="tag t-red">P0</span></td><td>C-001</td></tr>
+      <tr><td>C-003</td><td>file_read Tool</td><td>读取文件内容，支持行范围</td><td><span class="tag t-red">P0</span></td><td>C-001</td></tr>
+      <tr><td>C-004</td><td>file_write Tool</td><td>写入/创建文件</td><td><span class="tag t-red">P0</span></td><td>C-001</td></tr>
+      <tr><td>C-005</td><td>file_move Tool</td><td>移动/重命名文件</td><td><span class="tag t-red">P0</span></td><td>C-001</td></tr>
+      <tr><td>C-006</td><td>file_delete Tool</td><td>删除文件</td><td><span class="tag t-orange">P1</span></td><td>C-001</td></tr>
+      <tr><td>C-007</td><td>file_transfer Tool</td><td>跨设备文件传输（通过 WS 数据端口）</td><td><span class="tag t-purple">P2</span></td><td>C-001, S-003</td></tr>
+      <tr><td>C-008</td><td>exec Tool</td><td>执行命令并返回结果，支持超时</td><td><span class="tag t-red">P0</span></td><td>C-001</td></tr>
+      <tr><td>C-009</td><td>exec_background Tool</td><td>后台执行长时间命令，返回任务 ID</td><td><span class="tag t-orange">P1</span></td><td>C-008</td></tr>
+      <tr><td>C-010</td><td>process_list Tool</td><td>列出进程，支持 CPU/内存排序</td><td><span class="tag t-red">P0</span></td><td>C-001</td></tr>
+      <tr><td>C-011</td><td>sysinfo Tool</td><td>返回 CPU/内存/磁盘/网络/运行时间</td><td><span class="tag t-red">P0</span></td><td>C-001</td></tr>
+      <tr><td>C-012</td><td>power Tool</td><td>关机/重启/休眠/WoL</td><td><span class="tag t-orange">P1</span></td><td>C-001</td></tr>
+      <tr><td>C-013</td><td>service Tool</td><td>系统服务管理（启动/停止/重启/状态）</td><td><span class="tag t-orange">P1</span></td><td>C-001</td></tr>
+      <tr><td>C-014</td><td>notify_send Tool</td><td>发送桌面通知</td><td><span class="tag t-orange">P1</span></td><td>C-001</td></tr>
+      <tr><td>C-015</td><td>Gateway 注册与自动连接</td><td>客户端启动时 SSE 注册到 Gateway，支持自动重连</td><td><span class="tag t-red">P0</span></td><td>C-001</td></tr>
+      <tr><td>C-016</td><td>独立代理支持</td><td>SOCKS5/HTTP 代理，只代理自身连接</td><td><span class="tag t-orange">P1</span></td><td>C-015</td></tr>
+      <tr><td>C-017</td><td>MCP Resources</td><td>device://list、device://{id}/status 资源暴露</td><td><span class="tag t-purple">P2</span></td><td>C-001</td></tr>
+      <tr><td>C-018</td><td>MCP Prompts</td><td>troubleshoot、optimize 预置提示词</td><td><span class="tag t-purple">P2</span></td><td>C-001</td></tr>
+    </table>
+  </div>
+
+  <!-- 模块 3 -->
+  <div class="module">
+    <h2><span class="dot" style="background:var(--accent2)"></span> 模块 3：client/platform — 平台适配</h2>
+    <table class="task-table">
+      <tr><th>编号</th><th>任务</th><th>说明</th><th>优先级</th><th>依赖</th></tr>
+      <tr><td>P-001</td><td>Windows 平台适配</td><td>屏幕捕获、系统信息、命令执行的 Windows 实现</td><td><span class="tag t-red">P0</span></td><td>C-001</td></tr>
+      <tr><td>P-002</td><td>Linux 平台适配</td><td>复用 Windows 代码，适配 Linux 路径和命令</td><td><span class="tag t-orange">P1</span></td><td>P-001</td></tr>
+      <tr><td>P-003</td><td>macOS 平台适配</td><td>复用代码，适配 macOS 特定 API</td><td><span class="tag t-purple">P2</span></td><td>P-001</td></tr>
+      <tr><td>P-004</td><td>Android 平台适配</td><td>React Native 环境下的文件/进程/系统信息</td><td><span class="tag t-orange">P1</span></td><td>P-001</td></tr>
+      <tr><td>P-005</td><td>CLI 平台适配</td><td>无 UI 版，Node.js CLI 入口，systemd/Docker 部署</td><td><span class="tag t-orange">P1</span></td><td>C-001</td></tr>
+      <tr><td>P-006</td><td>连接生命周期 — 通联检测</td><td>启动时测试 Gateway 是否可达</td><td><span class="tag t-red">P0</span></td><td>C-015</td></tr>
+      <tr><td>P-007</td><td>连接生命周期 — Tailscale 管理</td><td>按需启停 Tailscale，记录 started_by_us 状态</td><td><span class="tag t-orange">P1</span></td><td>P-006</td></tr>
+      <tr><td>P-008</td><td>连接生命周期 — 心跳保活</td><td>每 30s ping，连续 3 次无响应判定断开</td><td><span class="tag t-red">P0</span></td><td>C-015</td></tr>
+      <tr><td>P-009</td><td>连接生命周期 — 断线重连</td><td>指数退避重连（1s→2s→4s→...→60s）</td><td><span class="tag t-red">P0</span></td><td>P-008</td></tr>
+      <tr><td>P-010</td><td>连接生命周期 — 退出恢复</td><td>退出时恢复 Tailscale 到进入前状态</td><td><span class="tag t-orange">P1</span></td><td>P-007</td></tr>
+      <tr><td>P-011</td><td>配置管理</td><td>本地 JSON 配置读写、系统 keychain 凭据存储</td><td><span class="tag t-orange">P1</span></td><td>S-002</td></tr>
+    </table>
+  </div>
+
+  <!-- 模块 4 -->
+  <div class="module">
+    <h2><span class="dot" style="background:var(--pink)"></span> 模块 4：client/ui — 客户端界面</h2>
+    <table class="task-table">
+      <tr><th>编号</th><th>任务</th><th>说明</th><th>优先级</th><th>依赖</th></tr>
+      <tr><td>U-001</td><td>设置页面</td><td>Gateway 地址、token、代理、设备名称配置</td><td><span class="tag t-red">P0</span></td><td>P-011</td></tr>
+      <tr><td>U-002</td><td>连接状态指示器</td><td>顶部状态栏显示 Gateway 连接状态、Tailscale 状态</td><td><span class="tag t-orange">P1</span></td><td>P-008</td></tr>
+      <tr><td>U-003</td><td>设备列表页面</td><td>所有设备卡片（名称、在线状态、CPU/内存/磁盘概览）</td><td><span class="tag t-orange">P1</span></td><td>C-015</td></tr>
+      <tr><td>U-004</td><td>设备详情页面</td><td>单设备完整信息（进程列表、系统信息、网络状态）</td><td><span class="tag t-purple">P2</span></td><td>U-003</td></tr>
+      <tr><td>U-005</td><td>文件浏览器</td><td>远程目录树、文件列表、面包屑导航</td><td><span class="tag t-orange">P1</span></td><td>C-002</td></tr>
+      <tr><td>U-006</td><td>文件查看器</td><td>文本文件查看、图片预览</td><td><span class="tag t-purple">P2</span></td><td>U-005</td></tr>
+      <tr><td>U-007</td><td>文件上传/下载</td><td>拖拽上传、下载进度条</td><td><span class="tag t-purple">P2</span></td><td>U-005, C-007</td></tr>
+      <tr><td>U-008</td><td>远程终端</td><td>命令输入框、输出显示、历史记录</td><td><span class="tag t-orange">P1</span></td><td>C-008</td></tr>
+      <tr><td>U-009</td><td>远程桌面视图</td><td>屏幕推流显示区域</td><td><span class="tag t-purple">P2</span></td><td>S-003</td></tr>
+      <tr><td>U-010</td><td>远程桌面输入</td><td>鼠标点击/移动/滚动、键盘输入转发</td><td><span class="tag t-purple">P2</span></td><td>U-009</td></tr>
+      <tr><td>U-011</td><td>远程桌面工具栏</td><td>全屏、缩放、剪贴板同步、快捷键</td><td><span class="tag t-purple">P2</span></td><td>U-009</td></tr>
+      <tr><td>U-012</td><td>AI 聊天界面</td><td>消息列表、输入框、Markdown 渲染</td><td><span class="tag t-orange">P1</span></td><td>C-015</td></tr>
+    </table>
+  </div>
+
+  <!-- 模块 5 -->
+  <div class="module">
+    <h2><span class="dot" style="background:var(--orange)"></span> 模块 5：远程控制与 AI 操控</h2>
+    <table class="task-table">
+      <tr><th>编号</th><th>任务</th><th>说明</th><th>优先级</th><th>依赖</th></tr>
+      <tr><td>R-001</td><td>screenshot Tool</td><td>截取屏幕，返回 base64 JPEG</td><td><span class="tag t-orange">P1</span></td><td>P-001</td></tr>
+      <tr><td>R-002</td><td>remote_input Tool</td><td>鼠标移动/点击/滚动/拖拽、键盘输入/按键/快捷键</td><td><span class="tag t-orange">P1</span></td><td>P-001</td></tr>
+      <tr><td>R-003</td><td>clipboard_sync Tool</td><td>剪贴板读写/同步</td><td><span class="tag t-orange">P1</span></td><td>P-001</td></tr>
+      <tr><td>R-004</td><td>remote_stream Tool</td><td>开始/停止屏幕推流，WS 数据端口</td><td><span class="tag t-purple">P2</span></td><td>R-001, S-003</td></tr>
+      <tr><td>R-005</td><td>ui_find Tool</td><td>通过 Accessibility API 查找 UI 元素</td><td><span class="tag t-purple">P2</span></td><td>P-001</td></tr>
+      <tr><td>R-006</td><td>ui_act Tool</td><td>操作 UI 元素（点击/输入/选择/读取）</td><td><span class="tag t-purple">P2</span></td><td>R-005</td></tr>
+      <tr><td>R-007</td><td>browser_open Tool</td><td>打开 URL / 操控远端浏览器</td><td><span class="tag t-purple">P2</span></td><td>C-001</td></tr>
+      <tr><td>R-008</td><td>browser_act Tool</td><td>浏览器内操作（填写/点击/截图/获取文本）</td><td><span class="tag t-purple">P2</span></td><td>R-007</td></tr>
+      <tr><td>R-009</td><td>ocr_screen Tool</td><td>屏幕 OCR 文字识别</td><td><span class="tag t-purple">P2</span></td><td>R-001</td></tr>
+    </table>
+  </div>
+
+  <!-- 模块 6 -->
+  <div class="module">
+    <h2><span class="dot" style="background:var(--accent3)"></span> 模块 6：OTA 更新与 CI/CD</h2>
+    <p style="color:var(--dim);font-size:.85rem;margin-bottom:12px">策略：小更新 JS bundle OTA 静默推送，大更新 APK 重装。</p>
+    <table class="task-table">
+      <tr><th>编号</th><th>任务</th><th>说明</th><th>优先级</th><th>依赖</th></tr>
+      <tr><td>O-001</td><td>CI/CD 流水线</td><td>push tag → 自动构建 Desktop + Android + CLI</td><td><span class="tag t-orange">P1</span></td><td>—</td></tr>
+      <tr><td>O-002</td><td>Android JS bundle OTA</td><td>expo-updates：启动检查 + 每 24h 检查 → 静默下载 JS bundle → 下次打开生效</td><td><span class="tag t-orange">P1</span></td><td>O-001</td></tr>
+      <tr><td>O-003</td><td>Desktop 自动更新</td><td>Tauri updater：检查 latest.json → 后台下载 APK → 静默安装</td><td><span class="tag t-orange">P1</span></td><td>O-001</td></tr>
+      <tr><td>O-004</td><td>CLI 自动更新</td><td>gca-cli update 命令，下载最新版本并替换</td><td><span class="tag t-purple">P2</span></td><td>O-001</td></tr>
+      <tr><td>O-005</td><td>OTA 发布脚本</td><td>一键导出 JS bundle 并上传到 Gitee 静态仓库</td><td><span class="tag t-orange">P1</span></td><td>O-002</td></tr>
+    </table>
+  </div>
+
+  <!-- 开发顺序 -->
+  <div class="section">
+    <h2><span class="dot" style="background:var(--green)"></span> 建议开发顺序</h2>
+    <div class="table-wrap">
+      <table>
+        <tr><th>批次</th><th>任务</th><th>产出</th></tr>
+        <tr><td><b>第 1 批</b></td><td>S-001, S-002, U-001</td><td>类型定义 + 设置页面</td></tr>
+        <tr><td><b>第 2 批</b></td><td>C-001~C-005, C-008, C-010, C-011</td><td>MCP Server 核心 8 个 Tool</td></tr>
+        <tr><td><b>第 3 批</b></td><td>P-001, P-006, P-008, P-009, C-015</td><td>Windows 适配 + 连接生命周期</td></tr>
+        <tr><td><b>第 4 批</b></td><td>U-002, U-003, U-005, U-008, U-012</td><td>核心 UI（设备列表/文件/终端/聊天）</td></tr>
+        <tr><td><b>第 5 批</b></td><td>C-006, C-009, C-012~C-016, P-011</td><td>扩展 Tool + 代理 + 配置</td></tr>
+        <tr><td><b>第 6 批</b></td><td>R-001~R-003, P-002, P-005</td><td>远程控制基础 + Linux/CLI 适配</td></tr>
+        <tr><td><b>第 7 批</b></td><td>R-004, S-003, U-009~U-011</td><td>屏幕推流 + 远程桌面 UI</td></tr>
+        <tr><td><b>第 8 批</b></td><td>U-004, U-006, U-007, C-007, C-017, C-018</td><td>设备详情/文件查看/Resources</td></tr>
+        <tr><td><b>第 9 批</b></td><td>R-005~R-009, P-004</td><td>AI 操控 + Android 适配</td></tr>
+        <tr><td><b>第 10 批</b></td><td>O-001~O-005, S-005, P-003</td><td>CI/CD + OTA + macOS</td></tr>
+      </table>
+    </div>
+  </div>
+</div>
+
+<footer>
+  <a href="../index.html">首页</a> &nbsp;|&nbsp; <a href="../architecture/index.html">架构</a> &nbsp;|&nbsp; <a href="../roadmap/index.html">路线图</a>
+  <br><br>
+  Global Control Assistant &copy; 2026
+</footer>
+</body>
+</html>