123 lines
13 KiB
Markdown
123 lines
13 KiB
Markdown
# iTuoke
|
||
|
||
手机操控桌面应用：**Wails + Vue3 + TypeScript**（UI） / **Go**（ADB 设备核心） / **Python**（Agent 独立进程）。
|
||
|
||
## 架构
|
||
|
||
```text
|
||
frontend/ UI：左画面 | 右对话 | 设置 | 日志
|
||
main.go 桌面壳入口（窗口 + 注册服务）
|
||
internal/device/ ADB 连接 / 视频预览 / 实时触摸控制（Go）
|
||
internal/agent/ 模型配置 / 系统凭据存储 / Go 直连模型 / 对话上下文
|
||
internal/mcpclient/ MCP 服务管理 / 系统凭据存储 / stdio 与 HTTP 工具发现
|
||
internal/protocol/ 版本化 JSON-RPC 契约
|
||
agent/ Python Agent 进程（可后接云端模型）
|
||
```
|
||
|
||
关键改代码位置已在源文件顶部用 `[关键]` / `[入口]` / `[UI · …]` 备注标出。
|
||
|
||
## 开发
|
||
|
||
构建机需要 Go 1.26+、Node.js 22.18+（测试直接运行 TypeScript）、npm 和 Wails v3。**客户机无需安装 Go、Node、Python、ADB、scrcpy、FFmpeg 或 WebView2**。工作台对话由 Go 直接调用配置的模型服务，不启动 Python。
|
||
|
||
先安装前端依赖，再按构建平台准备运行资源：
|
||
|
||
```bash
|
||
npm --prefix frontend install
|
||
```
|
||
|
||
Windows 10/11 x64（PowerShell，在项目根目录）：
|
||
|
||
```powershell
|
||
./scripts/sync-windows-runtime.ps1
|
||
wails3 dev
|
||
# 正式构建：自动准备并复制依赖到 bin/
|
||
wails3 build
|
||
# 免安装包：整个目录解压后运行 iTuoke.exe，不要单独拷贝 exe
|
||
wails3 task windows:package:portable
|
||
# 安装包（构建机需有 NSIS / makensis）
|
||
wails3 package
|
||
```
|
||
|
||
Windows 内置固定版本 scrcpy server 5.0.1、FFmpeg 8.1.2、ADB 和私有 WebView2 156.0.4314.58，下载缓存及二进制不提交 Git。ZIP/安装包都包含运行资源，无客户侧下载。当前 Windows 交付目标为 amd64；ARM64 和当前只复制主 exe 的 Wails MSIX 打包路径会明确拒绝，避免交付缺少资源的包。Windows 的后台工具不弹控制台窗口，macOS 专用网络权限按钮不会显示。
|
||
|
||
macOS（在 Mac 构建机上）：
|
||
|
||
```bash
|
||
# 构建机准备 ffmpeg；也可通过 ITUOKE_FFMPEG_SOURCE 指向已有二进制
|
||
brew install ffmpeg
|
||
bash scripts/sync-macos-runtime.sh
|
||
wails3 dev
|
||
wails3 package
|
||
# 对外分发仍需自己的 Developer ID 签名和公证
|
||
wails3 task darwin:sign:notarize
|
||
```
|
||
|
||
macOS 准备脚本下载 Mac 版 ADB 和相同的 scrcpy server，收集 FFmpeg 的非系统 dylib 依赖并重写为包内相对路径，不依赖客户的 Homebrew。打包和开发 `.app` 均将工具放进 `Contents/Resources/{platform-tools,scrcpy,ffmpeg}` 后再签名。缺资源、错平台或缺目标架构会直接失败。Apple Silicon 和 Intel 分别构建相应版本；universal 包要求 FFmpeg 和所有 dylib 同时包含 arm64、x86_64，不能使用单架构 Homebrew FFmpeg 冒充 universal。
|
||
|
||
两个平台均优先按主程序位置查找资源，因此支持从快捷方式或不同工作目录启动。准备步骤只在构建机执行；离线重建可使用已经准备好的资源，Windows 通过 `-StageOnly` 校验和复制。升级依赖后需要重新验证投屏协议、签名以及第三方许可和对应源码分发要求，参见 `third_party/RUNTIME-NOTICES.txt`。
|
||
|
||
```bash
|
||
# 1) 生成前端绑定（改 Go 导出方法后重跑）
|
||
wails3 generate bindings -ts -i ./...
|
||
|
||
# 2) 跑桌面应用（热重载，先完成对应平台运行资源准备）
|
||
wails3 dev
|
||
|
||
# 3) 可选：单独起 Python Agent
|
||
cd agent && python3 main.py
|
||
```
|
||
|
||
macOS 开发运行会把应用包同步到 `~/Applications/iTuoke.app` 后启动，避免从外置磁盘运行时反复触发「可移除宗卷」文件授权。ADB 使用应用专用的本地后台服务，不复用其他工具的默认服务；配对记录继续保留。
|
||
|
||
## 内置运行资源（客户无需安装）
|
||
|
||
```bash
|
||
bash scripts/sync-macos-runtime.sh # Mac 构建机：完整投屏运行资源
|
||
wails3 package # macOS 打进 .app/Contents/Resources/
|
||
```
|
||
|
||
Windows 使用上面的 PowerShell 脚本和 Windows 打包任务；不要在 Windows 上运行旧的 `sync-platform-tools.sh`。`scripts/sync-platform-tools.sh` 仅作为历史 ADB 同步工具保留，不能代替完整运行资源准备。
|
||
|
||
## 当前能力
|
||
|
||
- USB / 无线 ADB 设备发现、配对、连接与离线重连。「设置 → 设备连接」提供 USB 数据线入口：开启手机 USB 调试并允许电脑授权后即可投屏与操作，无需无线配对；插拔或授权后点击「检测 USB 设备」或顶部「刷新」更新列表，设备选择器区分 USB 和无线连接。
|
||
- scrcpy 视频预览，支持适应窗口及 50%–200% 缩放。
|
||
- 预览中点按、长按及连续拖动：按下、移动、松开实时发送到 scrcpy 控制通道。
|
||
- 深色、浅色和跟随系统主题，连接配置与缩放偏好持久化。
|
||
- 设置与日志页面；模型配置支持 OpenAI、DeepSeek、通义千问、已有 Ollama 及自定义 Chat Completions 兼容服务。
|
||
- 运行日志自动保存到系统用户配置目录的 `iTuoke/logs/`，Windows 与 macOS 均支持。单文件最多 2 MiB，写入下一条会超出时按时间另建历史分卷，旧文件保留。重启后恢复最近 2000 条供界面查看；清空会删除当前和历史日志文件，保存失败可重试。
|
||
- API 基础地址、模型名称、系统提示词、可选 Temperature、输出上限、上下文轮数与请求超时可配置。获取模型列表及连接测试使用当前表单，保存后用于工作台真实对话。
|
||
- API Key 由 Go 写入 Windows 凭据管理器 / macOS 钥匙串，按服务地址隔离；普通配置保存到系统用户配置目录下的 `iTuoke/model.json`，不包含密钥。
|
||
- 对话支持新建、切换、搜索、重命名和删除会话。消息及输入草稿自动保存到用户配置目录的 `iTuoke/conversations/`，每个会话一个 JSON 文件，使用原子替换写入。保存失败时提示并可重试；重启后恢复上次会话。
|
||
- 对话顶栏在同一行显示会话列表图标、会话名称、模型名称和新会话图标。会话管理从窗口左侧抽屉展开，支持遮罩、关闭按钮和 Esc 收起；界面图标统一使用 Lucide Vue 线性图标。
|
||
- 各会话拥有独立模型上下文，可并行生成，切换会话不会串消息；重启后从已保存的摘要与近期问答恢复上下文。中断回复仍可查看，重启时标为已停止，不作为完整问答直接发送；摘要只按实际状态记录结果。更换模型配置不会删除会话记录。
|
||
- 会话支持自动摘要记忆：历史问答超出设置的近期轮数或正文长度预算时，使用当前模型把较早内容增量整理为摘要，后续发送“摘要 + 近期问答 + 当前问题”。摘要包含需求、限制、决定、关键参数、工具结果及待办，原始消息保留。摘要与覆盖范围按会话保存到同一 JSON 文件，重启后恢复；前端旧快照不能覆盖后端新记忆，历史原文被修改时会失效并重新整理。记忆及整理过程在后台处理，不在页面展示；停止生成仍可取消整理。摘要失败或取消不会丢弃原记录，也不会推进覆盖范围。摘要会额外调用当前模型，上下文轮数为 0 时不使用或生成摘要。
|
||
- 对话支持文件选择、拖放和粘贴图片。附件可在发送前移除，也可仅发送附件；待发送附件随草稿保存，已发送附件显示在消息中，按会话隔离，重启后可继续引用。原文件与提取正文保存在用户配置目录的 `iTuoke/attachments/{会话ID}/{附件ID}/`，删除会话时同步清理。文件名只作为元数据，文件路径由程序生成，客户端无需安装额外解析工具。
|
||
- 支持 UTF-8、带 BOM 的 UTF-16、GB18030 文本与代码文件，以及文字型 PDF、DOCX、XLSX 和 PNG/JPEG/WebP。PDF 不做扫描件 OCR；Excel 使用单元格缓存值，不执行公式。每条最多 5 个附件，单个最多 20 MB、合计最多 30 MB；单文件提取正文最多 128 KB，超出会标记“部分正文”，每条附件正文合计最多 256 KB。文本内容用于对话和自动摘要，图片作为当前模型的图片输入，模型需支持识图。
|
||
- Agent 支持 Chat Completions 工具调用：将已启用 MCP 的工具提供给模型，执行后回传结果并继续流式回复；支持手机操作及文件工具。Agent 不设固定工具轮数、调用次数或整段任务时长上限，任务完成后结束，用户可随时停止；单次模型请求超时仍按配置执行。投屏本身不上传模型；截图等工具返回的图片会作为当前轮图片输入发送给所配置模型（需要支持图片）。手机操作所需的截图默认仅用于内部识别；只有用户本轮明确要求截图或展示画面时，才保存到本机会话附件并显示图片卡片，可点击放大，切换会话和重启后恢复。Ollama 选项连接已有服务，不随应用打包本地推理引擎或模型权重。
|
||
- “截图给我看”等单纯截图请求使用本地快捷路径：只识别唯一在线手机并调用截图工具，跳过模型规划、历史摘要、页面与目录查询，不再另存重试。包含导航、分析、指定保存路径等额外要求时仍由模型执行。普通任务优先使用已确定的设备和批量顺序动作，减少逐步播报和重复核验。Qwen3.8-Max 工具任务默认设置 `enable_thinking=false`，可在模型高级设置中开启“工具执行使用深度思考”。
|
||
- 系统内置 Mobile Next MCP 1.0.16 与 Filesystem，默认启用，不允许删除或改成其他连接方式，可在 MCP 管理中停用、编辑或测试。Filesystem 保留已有允许目录，新安装默认开放应用用户配置目录中的 `iTuoke/files/`。固定依赖随应用交付，共用私有 Node 并使用内置 ADB 和 iTuoke 专用连接；无需填写 npx 命令或在客户机下载依赖。当前内置集成面向已连接的 Android 手机，使用上游 ADB 模式，关闭遥测；中文输入等上游功能可能需要手机侧 DeviceKit。构建机执行 `npm --prefix runtime/mobile run stage` 准备锁定资源。
|
||
- 「设置 → MCP 管理」支持添加、编辑、启停和删除多个 MCP 服务。支持本地 stdio 进程和远程 Streamable HTTP，连接测试真实发现工具（含分页），可展开查看工具说明和输入参数。测试使用当前表单，不自动保存或执行工具，完成后关闭连接。Agent 每次对话读取启用服务，保留连接直至本轮结束；停用、删除或修改目标会阻止旧会话继续调用该服务。
|
||
- 工具名称按服务隔离，调用前校验 JSON Schema，执行结果（含错误）回传模型。工具进度、参数和结果摘要显示在聊天中并随会话保存；停止生成会取消请求和后续调用。同一应用中的 MCP 操作序列按任务排队，避免多个会话交错操作同一手机，纯文字对话仍可并行。
|
||
- MCP 普通配置保存在系统用户配置目录下的 `iTuoke/mcp.json`；环境变量与认证请求头保存到系统凭据库，不返回前端。编辑时可保留、替换或清除凭据，修改连接目标须重新填写或清除凭据。本地服务的 Node/Python 等运行环境需自行准备；命令与 JSON 启动参数分开填写，不经 shell 执行。远程服务目前支持自定义认证请求头，不包含 OAuth 登录流程或旧版 HTTP+SSE 传输。
|
||
- 「添加 Filesystem」使用官方 `@modelcontextprotocol/server-filesystem` 2.1.0，默认只开放系统用户配置目录的 `iTuoke/files/`。编辑中可指定多个已有目录；配置不保存随安装位置变化的启动路径。普通连接测试只发现工具，「测试文件读写」会实际创建临时目录、写入及读取中文文件、搜索、重命名并验证目录外读写被拒绝，随后清理测试文件。启用后可由对话 Agent 调用。
|
||
- Filesystem 的 Node 与锁定依赖随 Windows/macOS 包交付，客户端无需安装或联网下载。构建机需 Node >= 24，首次执行 `npm --prefix runtime/filesystem run stage`；Windows/macOS 运行资源准备脚本也会执行该步骤。`runtime/filesystem/package-lock.json` 固定依赖，目录搜索依赖覆盖为修复版本。Mac 使用官方自包含 Node，检查目标架构及系统 dylib；universal 构建需通过 `ITUOKE_NODE_UNIVERSAL_SOURCE` 提供同时含 arm64/x86_64 的 Node，并用 `ITUOKE_NODE_LICENSE` 指定其许可证（若不在当前 Node 相邻目录）。
|
||
- 工作台使用 SSE 流式输出并逐段显示，支持停止生成。停止或连接中断后保留已收到的文字并显示状态；未完成的回答不加入模型上下文。达到输出上限时显示不完整提示。模型服务需支持 Chat Completions 的 `stream=true`。
|
||
|
||
`frontend/bindings/`、依赖目录、构建产物、录屏和本机配置不提交；前端绑定由上述生成命令或 Wails 构建任务重建。图标、原始图标素材及各平台打包模板保留在仓库。
|
||
|
||
## 验证
|
||
|
||
```bash
|
||
node --test frontend/tests/*.test.mjs
|
||
npm --prefix frontend run build
|
||
go test -race ./internal/...
|
||
```
|
||
|
||
可选实机预览检查（设备需已连接到 iTuoke 的专用 ADB 服务）：
|
||
|
||
```bash
|
||
ITUOKE_TEST_DEVICE='手机IP:连接端口' go test -race ./internal/device -run TestLocalPhonePreview -v -count=1
|
||
```
|