# ControlCmd Windows Agent 3.0.0

这是 Windows 测试版 Agent，用于让手机 App 远程连接并控制 Windows 电脑终端。

## 系统要求

- Windows 10 或 Windows 11，amd64。
- PowerShell 5.1 或 PowerShell 7。
- 电脑可以访问 `https://api.xiaoli.world`。

## 安装配置

在 PowerShell 中进入解压目录：

```powershell
Copy-Item config\agent.env.example config\agent.env
notepad config\agent.env
```

必须修改：

```env
AGENT_ACCOUNT=zhangsan@example.com
AGENT_PASSWORD=手机 App 登录使用的同一个密码
AGENT_DEVICE_NAME=office-windows-01
AGENT_DEVICE_FINGERPRINT=550e8400-e29b-41d4-a716-446655440000
```

字段说明：

- `AGENT_ACCOUNT`：服务端登录账号，必须和手机 App 登录账号一致。
- `AGENT_PASSWORD`：这个账号的密码，必须和手机 App 登录密码一致。
- `AGENT_DEVICE_NAME`：手机 App 设备列表显示的电脑名称，例如 `office-windows-01`。
- `AGENT_DEVICE_FINGERPRINT`：这台电脑的稳定唯一 ID，不是密码。每台电脑必须不同，安装后尽量不要修改。

手机 App 登录后，只会显示同一个 `AGENT_ACCOUNT` 下面注册上来的电脑。如果 Agent 配置的是账号 A，App 登录的是账号 B，这台电脑不会出现在 App 里。

可以用固定可读 ID 作为指纹，例如 `windows-office-01-20260508`，也可以在 PowerShell 里生成 UUID：

```powershell
[guid]::NewGuid().ToString()
```

`SERVER_URL` 默认是正式测试服务器：

```env
SERVER_URL=https://api.xiaoli.world
```

## 推荐启动方式：桌面用户交互启动

Windows 终端依赖 ConPTY，必须运行在当前登录桌面用户的交互会话中。不要用 WinRM、SSH 或 Windows Service 启动终端 Agent，否则手机上可能只有黑屏和光标。

本机电脑可以通过浏览器打开共享终端：

```text
http://127.0.0.1:18081/terminal
```

手机和这个浏览器终端会连接到同一个任务终端会话。

用当前桌面用户打开 PowerShell，执行：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\start-agent.ps1
powershell -ExecutionPolicy Bypass -File .\scripts\status-agent.ps1
```

停止：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\stop-agent.ps1
```

日志：

```text
logs\agent.out.log
logs\agent.err.log
```

## 设置开机登录后自动启动

用当前桌面用户打开 PowerShell，执行：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\install-interactive-task.ps1
```

卸载自动启动：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\uninstall-interactive-task.ps1
```

## Windows 服务模式

不推荐用于手机终端交互。服务运行在 Windows Session 0，ConPTY 可能不会输出提示符或命令结果，手机端会表现为黑屏。

需要用管理员权限打开 PowerShell：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\install-service.ps1
```

卸载：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\uninstall-service.ps1
```

## 手机测试

1. 手机 App 登录同一个账号。
2. 设备列表中应该看到 Windows 设备。
3. 点击任务窗口进入终端。
4. 断开后再次进入同一个任务窗口，应该自动回到同一个 Agent 内部会话。

## 排查

运行：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\doctor.ps1
```

常见问题：

- 登录失败：检查账号密码、服务器地址和电脑网络。
- 看不到设备：确认 Agent 正在运行，且每台电脑的 `AGENT_DEVICE_FINGERPRINT` 不重复。
- 连接中断：先看 `logs\agent.log`，再确认服务器 TURN/HTTPS 端口可访问。
- 终端无法启动：确认系统支持 Windows ConPTY。Windows 10 旧版本建议升级。
