﻿TUNE 远程助手 · 使用说明
================================================================

【这是什么】
一个跑在客户电脑上的小工具，让调校师在远程会话（ToDesk 等）里能"做深活"：
不只是动鼠标点点点，而是能执行命令、做体检、看系统信息，并把结果送回给调校师。

【为什么需要它】
远程桌面软件通常只转发鼠标（键盘经常不转发），所以调校师在远程会话里只能点。
有了这个助手，调校师用鼠标点按钮就能执行命令，
或者用剪贴板把命令送进来执行、把结果送回去。

【客户怎么用】
1. 双击"启动远程助手.cmd"
2. 窗口出来后会看到左边一排按钮（系统信息/硬件配置/显卡驱动/磁盘/内存/电源计划/启动项/
   服务/网络/温度/蓝屏记录…）和右边的输出区
3. 调校师说"开始体检"，点最下面的绿色按钮"一键体检"即可（跑全部只读项）
4. 任何操作的结果都会同时存到：我的文档\TUNE助手\报告\（可以自己翻看）

【安全说明（请客户放心）】
· 所有体检命令都是只读的，不改你的系统
· 危险命令被硬拦：格式化、diskpart、删除系统盘、关闭 Windows Defender、关防火墙、
  删还原点、BitLocker 关闭等，助手一律拒绝执行
· 只有你勾选"允许调校师远程执行"之后，剪贴板/文件通道才会生效；不勾选就完全不动
· 每一条命令和它的输出都记录在：我的文档\TUNE助手\日志\日期.log，你随时可以打开看
· 可以随时关掉窗口（关了通道就断了）

【调校师怎么用（我这一侧）】
工具在 D:\HarnessWorkspace\屏幕眼\操远程.ps1：
  操远程.ps1 -Act info                        找远程窗口、打印客户区（截图与点击的基准）
  操远程.ps1 -Act read                        截远程画面并读字（返回图内坐标）
  操远程.ps1 -Act find -Text 设置              在远程画面里找字
  操远程.ps1 -Act clickat -X 100 -Y 200       按图内坐标点击（所见即所点）
  操远程.ps1 -Act clicktext -Text 设置         找字并点击
  操远程.ps1 -Act cmd -Text "ipconfig /all"   在客户机上执行命令并取回结果
  操远程.ps1 -Act probe                       通道自检（执行一条已知命令并校验返回）

命令通道的原理：本地把 \"#TUNE: 命令\" 放进剪贴板 → 远程桌面把剪贴板同步到客户机 →
客户机上的助手执行命令 → 把结果写回剪贴板 → 同步回本地 → 我读到结果。
所以这条通道**不依赖键盘转发**，全靠鼠标+剪贴板，正好补上远程会话的限制。

【现场使用前必须确认的三件事（本机测不出来）】
1. ToDesk 的"剪贴板同步"要打开（双向都要）
2. 客户机上助手要在运行，并且勾选了"允许调校师远程执行"
3. 客户机上的 PowerShell 执行策略允许运行脚本（助手已用 -ExecutionPolicy Bypass 启动）

【本机已验证 / 待现场验证】
已验证（这台机器上端到端跑通）：
  · 客户侧助手能执行命令、结果能回到剪贴板（含中文、双引号、复杂表达式）
  · 操远程的通道自检：往返 0.6 秒，随机标记校验通过
  · 坐标映射：点图内坐标命中目标按钮，输出区从 46 行被清空到 21 行
  · 危险命令黑名单生效；日志与报告落盘
待现场验证（需要真的连一台客户机）：
  · ToDesk 剪贴板是否双向同步（这是整条通道的前提）
  · ToDesk 是否转发普通按键（如果转发，还能多一条"Win+R 开命令行"的路，更快）
  · 真实网络下通道往返耗时（本机 0.6 秒，跨网预计 2~5 秒）

【已知限制】
· 远程画面里的按钮小字，OCR 大约只有一半能读准（实测"一键体检"读成"一键休栓"）。
  所以远程点击优先用"大字号、特征明显"的目标，或者直接走命令通道，不要在按钮小字上赌
· 助手窗口必须留在前台可见，最小化后剪贴板通道仍工作，但调校师看不到进度
· 命令默认 90 秒超时；超时会中止并返回提示

================================================================
【附：调校师怎么把工具送上客户机并启动（全程鼠标，不需要键盘）】
1. 把 TUNE远程助手_v1.zip 发给客户（微信/闲鱼/网盘都行），或走 ToDesk 的文件传输推过去
2. 让客户解压后双击"启动远程助手.cmd"（这一步最好让客户自己点，最快）
3. 如果客户不方便操作，调校师在远程画面里全程用鼠标：打开"此电脑"→ 找到 zip →
   右键 → 全部解压缩 → 进文件夹 → 双击"启动远程助手.cmd"
4. 工具窗口出来后，调校师点一下"允许调校师远程执行"复选框（这是客户授权开关）
5. 然后在自己这边跑：操远程.ps1 -Act doctor
   诊断会告诉你三件事：眼睛服务在不在、远程窗口客户区是多少、命令通道通不通
6. 通道通了就可以：-Act cmd 单条命令 / -Act cmdfile 投递整段脚本（推荐，能留档复核）

【实测踩过的三个坑（都已修好，写下来免得下次又花时间）】
1. 用 -Command 传命令，双引号会被吞掉（"主机名:" 后面的引号消失）
   -> 改用 -EncodedCommand（base64，UTF-16LE），中文与引号全部保真
2. 多行脚本用 -File 传参会被拆成多个参数（PowerShell 参数解析限制）
   -> 改成把脚本写成文件，用 -Act cmdfile -Path 投递
3. 助手的命令正则写成 #TUNE:(.+)$，而 . 不匹配换行 -> 多行脚本被静默忽略
   -> 改成 (?s) 单行模式；另外助手按剪贴板内容去重，同一条命令发第二次会被忽略
   -> 所以每此投递都会自动追加一个 #NONCE 唯一标记

【验证记录（本机端到端，2026-10-04）】
· 单条命令往返 0.5~0.6 秒，随机标记校验通过
· 整段体检脚本（675 字符）往返 1.3~1.4 秒，连跑两次结果一致
· 坐标映射：图内坐标点击命中目标，输出区 46 行 -> 21 行
· 文件投递通道：命令文件 -> 0.3 秒执行 -> 生成 .out.txt
· 回传内容示例（本机自测）：
    主机: DESKTOP-7QU82MH   用户: HLH
    CPU: AMD Ryzen 9 7945HX with Radeon Graphics
    内存GB: 15.2
    显卡: NVIDIA GeForce RTX 5060 Laptop GPU   驱动: 32.0.15.9174
    磁盘 C: 剩余/总GB: 37.1 / 100
    电源计划: 电源方案 GUID: 1b0234cb-...  (HLH)
