# WoWS Remote Agent

一个面向 Windows 的受限远程控制代理。它让 Codex 或其他支持 MCP/HTTP 的 AI 通过 Tailscale 私有网络完成以下操作：

- 查看游戏电脑和《战舰世界》进程状态；
- 获取当前桌面截图；
- 启动并聚焦本机配置的游戏程序；
- 点击用户在本机校准过的菜单位置；
- 执行预先审核过的菜单工作流；
- 随时通过本机 `Ctrl+Alt+F12` 或远程 `abort` 急停。

项目不提供自动驾驶、瞄准、开火、挂机刷取或反检测功能。它不是 Wargaming 官方项目，与 Wargaming 没有关联。

## 安全边界

代理没有任意 Shell、任意程序启动或文件管理接口。远程端只能启动配置文件中唯一指定的程序，键盘白名单只有 Enter、Esc、Tab、Space、方向键等菜单键，不包含 W/A/S/D。默认关闭任意单步点击，只允许本机配置的工作流。

所有写操作记录在：

```text
C:\ProgramData\WoWSRemoteAgent\logs\audit.jsonl
```

`start_battle` 工作流还要求 AI 在调用时传入 `confirmed=true`。这不能代替你的监督；请只在你能看到游戏电脑屏幕时使用。

[《战舰世界》规则 5.07](https://legal.wargaming.net/sg/user-documents/game-rules/game-rules-wows/view) 禁止在玩家不参与或被动参与时使用机器人、点击器、宏和类似方案。合作模式没有自动化豁免。因此本项目只面向启动与菜单导航，不应扩展成自动战斗工具。使用前请自行核对你所在地区的最新规则。

## 最快安装

要求：

- 游戏电脑运行 Windows 10/11；
- 使用管理员身份打开 PowerShell；
- Windows 带有 `winget`，或者已经安装 Python 3.11 以上版本；
- 游戏使用无边框窗口，并固定分辨率与 UI 缩放比例。

管理员 PowerShell 中运行：

```powershell
Set-ExecutionPolicy -Scope Process Bypass -Force
irm https://raw.githubusercontent.com/jesson-hh/wows-remote-agent/v0.1.0/scripts/bootstrap.ps1 | iex
```

这是方便首次安装的一行命令，会直接执行 GitHub 上的脚本。安全要求更高时，请先下载并阅读 `bootstrap.ps1`，确认仓库和版本后再运行；生产环境建议固定到具体 release 标签，而不是长期跟随 `main`。

安装器会：

1. 安装或复用 Python 3.11+；
2. 创建独立虚拟环境；
3. 安装 Tailscale，并在需要时引导登录；
4. 生成 64 字符随机访问令牌；
5. 只允许 Tailscale 地址段访问代理端口；
6. 创建“用户登录后”启动的计划任务；
7. 生成 `C:\ProgramData\WoWSRemoteAgent\connection.json`。

如果不希望安装器管理 Tailscale：

```powershell
irm https://raw.githubusercontent.com/jesson-hh/wows-remote-agent/v0.1.0/scripts/bootstrap.ps1 -OutFile "$env:TEMP\wows-bootstrap.ps1"
& "$env:TEMP\wows-bootstrap.ps1" -SkipTailscale
```

> 不要把 `connection.json` 上传到 GitHub、网盘或聊天群。它包含访问令牌。

## 设置游戏路径

如果安装时没有填写，管理员 PowerShell 中运行：

```powershell
& 'C:\ProgramData\WoWSRemoteAgent\scripts\configure.ps1' `
  -GamePath 'D:\Games\World_of_Warships\WorldOfWarships.exe'
```

请填写你电脑上的实际启动程序。安装器不会扫描或修改游戏文件。

## 校准合作模式按钮

保持游戏为固定分辨率和无边框窗口。每次运行命令后，在倒计时结束前把鼠标移到对应按钮上，不要点击：

```powershell
& 'C:\ProgramData\WoWSRemoteAgent\scripts\calibrate.ps1' -Name battle_type_button
& 'C:\ProgramData\WoWSRemoteAgent\scripts\calibrate.ps1' -Name coop_mode
& 'C:\ProgramData\WoWSRemoteAgent\scripts\calibrate.ps1' -Name confirm_mode
& 'C:\ProgramData\WoWSRemoteAgent\scripts\calibrate.ps1' -Name battle_button
```

分别对应：

1. 港口中的战斗类型按钮；
2. 合作模式选项；
3. 模式选择确认按钮；
4. “开始战斗”按钮。

修改分辨率、显示器主次顺序或 Windows 缩放比例后需要重新校准。

## 检查游戏电脑

```powershell
& 'C:\ProgramData\WoWSRemoteAgent\scripts\doctor.ps1'
```

如果本机健康检查失败：

```powershell
Get-ScheduledTask -TaskName 'WoWS Remote Agent'
Start-ScheduledTask -TaskName 'WoWS Remote Agent'
Get-Content 'C:\ProgramData\WoWSRemoteAgent\logs\audit.jsonl' -Tail 30
```

代理必须运行在已经登录的交互式 Windows 会话中。Windows 服务的 Session 0 无法可靠截图和点击桌面，所以安装器使用“登录时启动”的计划任务；锁屏或退出登录后，桌面控制不会工作。

## 在控制电脑上连接 Codex

先让两台电脑登录同一个 Tailscale tailnet。把游戏电脑上的 `connection.json` 安全复制到控制电脑，然后在控制电脑运行：

```powershell
git clone https://github.com/jesson-hh/wows-remote-agent.git
cd wows-remote-agent
& .\scripts\configure-codex.ps1 -ConnectionFile 'D:\Safe\connection.json'
```

脚本会：

- 把访问令牌写入当前 Windows 用户的 `WOWS_REMOTE_AGENT_TOKEN` 环境变量；
- 使用 `codex mcp add` 注册 Streamable HTTP MCP；
- 不把明文令牌写进 Codex `config.toml`。

重启 ChatGPT/Codex 桌面应用后输入 `/mcp`，应该能看到 `wows-remote-agent`。

也可以手动配置：

```toml
[mcp_servers.wows-remote-agent]
url = "http://100.x.y.z:8765/mcp"
bearer_token_env_var = "WOWS_REMOTE_AGENT_TOKEN"
default_tools_approval_mode = "prompt"
tool_timeout_sec = 150
```

## 测试远程连接

在控制电脑运行：

```powershell
& .\scripts\test-connection.ps1 -AgentIP 100.x.y.z
```

测试脚本会隐藏输入令牌，然后验证 `/health` 与需要身份验证的 `/v1/status`。

## 可以对 Codex 说什么

建议按小步骤发出指令：

```text
检查游戏电脑状态，不要执行操作。
```

```text
运行 open_game，等它完成后截图并告诉我当前界面。
```

```text
先截图；只有画面确实是港口时才运行 enter_coop，然后再次截图。
```

```text
我确认现在可以点击开始战斗。运行 start_battle，confirmed=true，然后停止操作。
```

如界面和预期不同：

```text
立即调用 abort，不要尝试猜测按钮。
```

## MCP 工具

| 工具 | 行为 | 默认是否改动电脑 |
|---|---|---:|
| `get_status` | 游戏进程、工作流和急停状态 | 否 |
| `list_workflows` | 工作流是否完成校准 | 否 |
| `capture_screen` | 返回缩小后的 JPEG | 否 |
| `launch_game` | 启动唯一配置的程序 | 是 |
| `focus_game` | 聚焦游戏窗口 | 是 |
| `run_workflow` | 执行本机配置的步骤 | 是 |
| `click_target` | 单击本机校准点，默认禁用 | 是 |
| `press_menu_key` | 点击菜单键，默认禁用 | 是 |
| `abort` | 停止工作流并释放白名单键 | 是 |

REST 等价接口位于 `/v1/*`，全部需要 `Authorization: Bearer ...`，只有 `/health` 不需要令牌。

## 更新

重新运行同一条命令可重装当前固定版本，并保留现有 `config.json`、校准点、访问令牌与日志。升级时把命令中的 `v0.1.0` 替换为 GitHub Releases 页面列出的新版本。安装或升级前仍建议备份：

```powershell
Copy-Item 'C:\ProgramData\WoWSRemoteAgent\config.json' "$env:USERPROFILE\Desktop\wows-agent-config.backup.json"
```

## 卸载

保留配置和日志：

```powershell
& 'C:\ProgramData\WoWSRemoteAgent\scripts\uninstall.ps1' -KeepConfig
```

完整删除代理、配置与日志：

```powershell
& 'C:\ProgramData\WoWSRemoteAgent\scripts\uninstall.ps1'
```

卸载脚本不会卸载 Tailscale、Python 或游戏。

## 开发

```powershell
py -3.12 -m venv .venv
.\.venv\Scripts\python -m pip install -e '.[test]'
.\.venv\Scripts\python -m ruff check .
.\.venv\Scripts\python -m pytest
```

复制示例配置、设置临时令牌后可本地启动：

```powershell
Copy-Item config.example.json .local-config.json
$env:WOWS_AGENT_CONFIG = (Resolve-Path .local-config.json)
$env:WOWS_AGENT_TOKEN = 'development-token-at-least-32-characters'
.\.venv\Scripts\python -m wows_remote_agent --config .local-config.json --host 127.0.0.1
```

更多说明见 [部署与排错](docs/DEPLOYMENT.md) 和 [安全模型](SECURITY.md)。

仓库附带 [GitHub Actions CI 示例](docs/ci.example.yml)。仓库维护者可在令牌具有 `workflow` 权限时把它复制到 `.github/workflows/ci.yml`，即可在 Windows 与 Ubuntu、Python 3.11/3.12 上自动运行检查。