Skip to content

docs(okww): 大幅压缩文档，合并配置步骤为快速开始 #15

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
1w1w11w1 wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs(okww): 大幅压缩文档，合并配置步骤为快速开始 #15

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
329 changes: 31 additions & 298 deletions docs/script-guide/okww.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,320 +8,53 @@ date: 2026-05-31

## 什么是 OK-WW？

OK-WW（ok-ww）是一个「鸣潮（Wuthering Waves）」第三方自动化工具，支持日常任务、声骸刷取、肉鸽、凝素领域、梦魇巢穴、模拟领域、无音区等任务的自动化执行。

AUTO-MAS 通过专项适配，支持自动拉起 ok-ww 执行任务、监控日志判定成败、自动管理游戏生命周期，实现完整的无人值守代理体验。

**详情信息请查阅**：
OK-WW（ok-ww）是一个「鸣潮（Wuthering Waves）」第三方自动化工具。

<Box :items="[
{ name: 'OK-WW GitHub', link: 'https://github.com/ok-oldking/ok-wuthering-waves', image: { light: '/icons/github.svg', dark: '/icons/github-dark.svg', }, },]"/>

## 工作原理

AUTO-MAS 接管 ok-ww 的完整运行流程：
## 专项适配说明

1. **配置管理**：MAS 将存储的配置文件下发到 ok-ww 工作目录，确保脚本使用正确的用户配置。
2. **游戏管理**：可选的游戏生命周期管理 —— 任务前启动游戏（防重复）、任务后关闭游戏。
3. **任务启动**：通过 `-t N -e` 命令行参数启动 ok-ww，指定任务序号并在完成后自动退出。
4. **日志监控**：持续读取 ok-ww 日志，按「错误优先于成功」原则判定任务成败。
5. **异常处理**：失败后自动清理进程、回写配置、发送通知，并按重试次数自动重试。

与通用脚本的关键区别：
AUTO-MAS 接管 ok-ww 的配置下发、任务启动（`-t N -e`）、日志监看与游戏生命周期管理，提供比通用脚本更稳定的无人值守体验。

| 特性 | 通用脚本 | OK-WW 专项适配 |
|---|---|---|
| 任务参数 | 用户自行填写 `-t N -e` | 自动拼合，从用户配置的 `TaskIndex` 和 `ExitOnFinish` 生成 |
| 游戏管理 | 通用的 Client/URL/Emulator | 仅 Client/URL，内置 `Client-Win64-Shipping.exe` 防重复检测 |
| 日志判定 | 完全依赖用户配置的 ErrorLog/SuccessLog | 内置致命关键词（`connected:False`、游戏更新重启），用户配置为补充 |
| 配置模式 | 单套配置文件 | 支持「简洁」（多用户共用）和「详细」（每用户独立）两种模式 |
| 进程追踪 | 可选 | 默认启用，自动追踪 `pythonw.exe` |

## 前置准备

1. 下载 [OK-WW](https://github.com/ok-oldking/ok-wuthering-waves) 脚本，解压至任意目录。
2. 确认 `ok-ww.exe` 可以正常启动并在 ok-ww 本体中完成过一次基础设置。
3. AUTO-MAS ≥ v5.3.0-beta.2。

::: warning 温馨提醒
请不要将 OK-WW 解压在中文路径下，以免出现不必要的异常。
:::

## 配置脚本

### 第一步：添加 OK-WW 脚本

1. 进入 **脚本管理**，单击 **新建脚本**。
2. 在弹窗中选择 **ok-ww 脚本** 类型。
3. 单击确定，MAS 会创建一个空的 ok-ww 脚本实例。

### 第二步：设置脚本路径

1. 点击新创建的脚本卡片，进入编辑页。
2. 在 **ok-ww 路径** 一栏中点击「选择目录」，选择 ok-ww 的**根目录**（包含 `ok-ww.exe` 的目录，例如 `D:\ok-ww`）。
3. MAS 会自动匹配以下路径：

| 自动匹配项 | 路径规则 |
|---|---|
| 脚本程序 | `{根目录}/ok-ww.exe` |
| 配置目录 | `{根目录}/data/apps/ok-ww/working/configs` |
| 日志文件 | `{根目录}/data/apps/ok-ww/working/logs/ok-script.log` |
| 追踪进程 | `{根目录}/data/apps/ok-ww/python/pythonw.exe` |

### 第三步：配置游戏管理（可选）

若需要 MAS 自动管理游戏客户端，请在「游戏配置」区域进行设置：

| 配置项 | 说明 | 默认值 |
|---|---|---|
| **启用游戏配置** | 总开关。关闭后 MAS 不启动也不关闭游戏 | 关闭 |
| **任务前启动游戏** | 任务开始前由 MAS 启动游戏并等待指定时间 | 关闭 |
| **任务后关闭游戏** | 任务成功后由 MAS 关闭游戏 | 启用 |
| **游戏根目录** | 选择 `Wuthering Waves Game` 根目录，自动匹配到客户端 exe | — |
| **游戏启动参数** | 游戏启动时的额外命令行参数 | 空 |
| **启动等待时间** | 拉起游戏后的等待时间（秒），根据电脑配置调整 | 60 |
| 任务参数 | 用户自行填写 | 自动拼合 |
| 日志判定 | 完全依赖用户配置 | 内置关键词 + 用户配置补充 |
| 配置模式 | 单套 | 简洁（共用）/ 详细（独立） |

> **游戏路径自动匹配**：选择 `Wuthering Waves Game` 根目录（如 `D:\Wuthering Waves Game`）后，MAS 自动拼接为：`D:\Wuthering Waves Game\Client\Binaries\Win64\Client-Win64-Shipping.exe`。
## 快速开始

> **防重复启动**：MAS 在启动游戏前会检查 `Client-Win64-Shipping.exe` 是否已在运行，如已运行则跳过启动，避免重复拉起。
1. 下载 [OK-WW](https://github.com/ok-oldking/ok-wuthering-waves)，解压至纯英文路径。AUTO-MAS ≥ v5.3.0-beta.2。
2. **脚本管理** → **新建脚本** → 选择 **ok-ww 脚本**。
![新建okww脚本](/docs/img/script-guide/okww/step1-new-script.png)
3. 设置 **ok-ww 路径**（包含 `ok-ww.exe` 的根目录），MAS 自动匹配子路径。
![设置路径](/docs/img/script-guide/okww/step2-set-path.png)
4. 点击「**配置 ok-ww**」，在 ok-ww 本体中完成配置，回到 MAS 保存。
![配置okww](/docs/img/script-guide/okww/step3-config-okww.png)
5. **添加用户**，填写账号、密码，选择启动任务。
![添加用户](/docs/img/script-guide/okww/step4-add-user.png)
6. 将脚本加入调度队列即可自动运行。

**三种开关控制关系**：
> **简洁模式 vs 详细模式**：简洁模式下所有用户共用一套 ok-ww 配置；详细模式下每个用户独立配置，在用户编辑页切换模式后点击「**ok-ww 配置**」即可。

```
启用游戏配置（总开关）
├─ 任务前启动游戏 → MAS 在任务前拉起游戏
└─ 任务后关闭游戏 → MAS 在成功后关闭游戏
```
### 支持的任务

- 总开关关闭：MAS 完全不参与游戏管理
- 仅开启「任务前启动」：MAS 负责启动，不负责关闭
- 仅开启「任务后关闭」：MAS 在任务成功时关闭已运行的游戏
- 两者都开启：MAS 全自动管理游戏生命周期

### 第四步：调整运行配置

| 配置项 | 说明 | 默认值 |
| 序号 | 任务 | 说明 |
|---|---|---|
| **单日代理次数上限** | 同一用户每天最大代理次数，`0` = 不限 | 0 |
| **重试次数限制** | 任务失败后最多重试次数 | 1 |
| **代理超时限制** | 日志无新内容超过此时间（分钟）判定超时 | 60 |

## 配置 OK-WW

ok-ww 的配置文件（任务列表、画质设置、按键映射等）需要通过 ok-ww 本体完成编辑。MAS 提供了两种方式来管理这些配置。

### 方式一：简洁模式（推荐初次使用）

所有用户共用一套 ok-ww 配置：

1. 在脚本管理页面，找到 ok-ww 脚本卡片。
2. 点击卡片上的「**配置 ok-ww**」按钮。
3. MAS 会打开 ok-ww 本体，在 ok-ww 中完成所有配置。
4. 配置完成后，回到 MAS 点击「**保存配置**」结束会话。

> 配置会话有 30 分钟超时，超时后自动断开。请在此时间内完成配置并保存。

### 方式二：详细模式（每用户独立配置）

每个用户拥有独立的 ok-ww 配置：

1. 进入用户编辑页，将「用户配置模式」设为 **详细**。
2. 点击「**ok-ww 配置**」按钮。
3. 在 ok-ww 中完成该用户的独立配置。
4. 回到 MAS 点击「保存配置」。

### 配置写入时机

MAS 每次代理完成后会根据 `UpdateConfigMode` 决定是否回写配置：

| 模式 | 行为 |
|---|---|
| `Always`（默认） | 每次代理都回写 |
| `Success` | 仅任务成功时回写 |
| `Failure` | 仅任务失败时回写 |
| `Never` | 从不回写 |

> ok-ww 脚本默认采用 `Always`，确保用户在 ok-ww 中的配置变更同步回 MAS。

### 配置目录结构

```
data/{脚本ID}/
├── Default/
│ └── ConfigFile/ ← 简洁模式：所有用户共用
├── {用户UID}/
│ └── ConfigFile/ ← 详细模式：每用户独立
└── Temp/ ← 临时的脚本原配置备份
```

## 配置用户

1. 在 **脚本管理** 的脚本卡片内，单击 **添加用户** 以添加一个用户。
2. 按照设置卡相关提示填写用户信息。

### 用户配置字段说明

#### 基本信息

| 配置项 | 说明 |
|---|---|
| **用户名** | 用户显示名称，用于区分不同账号 |
| **启用状态** | 是否参与自动代理。关闭后该用户将被跳过 |
| **账号** | 官服输入 11 位手机号。留空则不进行账号切换 |
| **密码** | 登录密码（加密存储）。PC 端账号切换必须填写 |
| **用户配置模式** | `简洁` 共用脚本页 ok-ww 配置；`详细` 每个用户独立配置 |
| **游戏资源** | 当前仅支持 `官服` |
| **剩余天数** | 剩余有效代理天数。`-1` 为无限制，每次成功代理后自动减 1，减至 0 时跳过该用户 |
| **备注** | 自由备注信息 |

::: tip 账号切换说明

- 账号 ID 为 11 位手机号，密码用于 PC 端自动登录。
- 留空账号时，AUTO-MAS 将直接使用当前已登录的账号执行任务，不会进行切换。
- 密码以加密形式存储在本地，不会上传至任何服务器。
:::

#### 任务配置

| 配置项 | 说明 |
|---|---|
| **启动任务（-t N）** | 选择要执行的 ok-ww 任务，对应 `-t` 参数 |
| **当前启动参数** | 自动生成，始终为 `-t N -e` |

> **关于 `-e` 参数**：MAS 始终向 ok-ww 传递 `-e`（完成后自动退出），确保任务完成后脚本进程正常结束。用户不可取消此参数。

### 支持的任务列表

| 序号 | 参数 | 任务名称 | 说明 |
|---|---|---|---|
| 1 | `-t 1` | DailyTask | 日常任务代理 |
| 2 | `-t 2` | MultiAccountDailyTask | 多账号模式执行日常 |
| 3 | `-t 3` | FarmEchoTask | 自动刷取声骸 |
| 4 | `-t 4` | AutoRogueTask | 半自动肉鸽玩法 |
| 5 | `-t 5` | ForgeryTask | 凝素领域副本 |
| 6 | `-t 6` | NightmareNestTask | 梦魇巢穴副本 |
| 7 | `-t 7` | SimulationTask | 模拟领域副本 |
| 8 | `-t 8` | TacetTask | 无音区副本 |

### 通知配置

ok-ww 用户支持以下通知方式，在任务出现异常时自动推送：

- **邮箱通知**：填写收件邮箱地址
- **Server酱**：填写 SENDKEY
- **自定义 Webhook**：支持多个 Webhook 地址

## 运行流程详解

### AutoProxy 自动代理生命周期

每次自动代理按以下流程处理每个用户：

1. **前置校验**
- 检查脚本路径是否存在
- 检查单日代理次数是否已达上限（→ 跳过用户）
- 检查用户剩余天数是否归零（→ 跳过用户）
- 检查 MAS 侧配置文件是否存在（→ 标记异常）
- 检查游戏路径是否有效（需要游戏管理时）
2. **MAS 接管启动游戏**（如启用）
- `Client` 类型：检查 `Client-Win64-Shipping.exe` → 启动 exe → 等待 `WaitTime` 秒
- `URL` 类型：通过协议 URL 启动
3. **配置下发** — MAS 侧 `ConfigFile` 同步到 ok-ww 配置目录
4. **启动 ok-ww.exe -t N -e**
5. **日志监控循环**
6. **结束处理** — 杀掉进程 → 回写配置 → 记录历史日志 → 进入下个用户或重试

### 日志判定规则

MAS 对日志的判断遵循 **「错误优先于成功」** 的原则，检查顺序如下：

| 优先级 | 判据 | 判定结果 |
|---|---|---|
| 1（最高） | 日志包含 `connected:False` | ❌ 异常 — OK-WW 未连接游戏客户端 |
| 2 | 日志包含 `游戏更新成功, 游戏即将重启` | ❌ 异常 — 游戏更新触发了重启 |
| 3 | 日志匹配用户配置的 `ErrorLog` 关键词 | ❌ 异常 |
| 4 | 日志包含「任务执行完成」或 `task completed` | ✅ 成功 |
| 5 | ok-ww 进程意外退出 | ❌ 异常 |
| 6 | 日志超时（长时间无新内容） | ❌ 异常 |

::: warning 注意
内置关键词（`connected:False`、`游戏更新成功, 游戏即将重启`）无法被覆盖或禁用。用户配置的 `ErrorLog` 仅作为**补充**判据。

若用户 `ErrorLog` 清洗后为空（即配置的关键词都过于宽泛被过滤掉），系统会自动回退到默认值：`connected:False|游戏更新成功, 游戏即将重启|错误`。
:::

### 游戏关闭策略

| 场景 | 关闭 ok-ww | 关闭游戏 |
|---|---|---|
| 代理成功 + 「任务后关闭」启用 | ✅ | ✅ |
| 代理成功 + 「任务后关闭」未启用 | ✅ | ❌ |
| 代理失败 / 游戏启动失败 / 异常 | ✅ | ✅（干净重试） |
| 1 | DailyTask | 日常任务 |
| 2 | MultiAccountDailyTask | 多账号日常 |
| 3 | FarmEchoTask | 刷取声骸 |

@sourcery-ai sourcery-ai Bot Jul 2, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

issue (typo)： “刷取声骸”疑为笔误，建议改为“刷取声骸”。

此处在描述任务功能时，“刷取声骸”是更常见、自然的写法，目前的“刷取”应为输入错误。建议修改为“刷取声骸”，以避免歧义。

Suggested change
| 3 | FarmEchoTask | 刷取声骸 |
| 3 | FarmEchoTask | 刷取声骸 |
Original comment in English

issue (typo): “刷取声骸”疑为笔误，建议改为“刷取声骸”

此处描述任务功能时，“刷取声骸”是更常见、自然的写法，目前的“刷取”应为输入错误。建议修改为“刷取声骸”，以避免歧义。

Suggested change
| 3 | FarmEchoTask | 刷取声骸 |
| 3 | FarmEchoTask | 刷取声骸 |

| 4 | AutoRogueTask | 肉鸽 |
| 5 | ForgeryTask | 凝素领域 |
| 6 | NightmareNestTask | 梦魇巢穴 |
| 7 | SimulationTask | 模拟领域 |
| 8 | TacetTask | 无音区 |

## 常见问题

### 启动代理后提示「请设置 ok-ww 脚本路径」

**原因**：脚本根目录未正确设置，或目录下找不到 `ok-ww.exe`。

**解决**：进入脚本编辑页，点击「选择目录」，**选择包含 `ok-ww.exe` 的根目录**（不是 `ok-ww.exe` 本身）。选中后 MAS 会自动匹配所有子路径。

### 提示「未找到共享的 OK-WW 配置文件」或「未找到用户的 OK-WW 配置文件」

**原因**：尚未在 MAS 中完成 ok-ww 配置会话。

**解决**：
- 简洁模式：回到脚本管理页面，在 ok-ww 脚本卡片上点击「**配置 ok-ww**」，完成配置后保存。
- 详细模式：进入用户编辑页，点击「**ok-ww 配置**」，完成配置后保存。

### 游戏启动了但 ok-ww 连接不上游戏

**原因**：游戏启动后需要时间加载，等待时间不够。

**解决**：在脚本编辑页增大「启动等待时间」——SSD 建议 60–80 秒，HDD 建议 120 秒以上。根据你的电脑配置调整。

### 日志显示「OK-WW 未连接游戏客户端」(connected:False)

**可能原因**：
- 游戏未完全加载 → 增大「启动等待时间」
- ok-ww 版本不兼容当前游戏版本 → 更新 ok-ww
- 游戏被安全软件拦截 → 检查杀毒软件日志
- PC 端非官服客户端 → 确认选择了正确的游戏资源

### 游戏更新后任务被自动中断

**原因**：ok-ww 检测到游戏版本更新，主动重启。MAS 将此视为致命中断并标记当前用户为异常。

**行为**：此为预期行为。建议在游戏更新日（通常为维护日）在非代理时段手动登录游戏完成更新，避免代理期间触发。

### 调度台中频繁出现「检测到客户端已在运行，跳过启动」

**原因**：MAS 在启动游戏前检查 `Client-Win64-Shipping.exe` 是否已在运行，避免重复拉起。

**行为**：这是正常的。若你手动或上一次代理已启动了游戏，MAS 会直接使用已有进程。若想每次代理都重新启动游戏，请在代理开始前手动关闭游戏。

### 误判任务失败

**原因**：正常日志中出现了匹配 `ErrorLog` 的关键词。

**解决**：检查 `ErrorLog` 配置（默认：`connected:False|游戏更新成功, 游戏即将重启|错误`）。若你的 ok-ww 正常日志中包含「错误」二字，可修改 `ErrorLog` 去掉该关键词。注意不要移除两个内置关键词（它们由代码强制检查，但放在配置项中也会被检测到）。

### 多用户代理只执行了第一个用户

**原因**：此问题已在 v5.3.0-beta.3 修复（修复多用户 AutoProxy 只执行最后一个用户）。

**解决**：更新 AUTO-MAS 到最新版本。

### 配置保存后 MAS 侧的配置丢失或被覆盖

**原因**：配置会话保存时源配置不存在，导致 MAS 侧被清空。此问题已在 v5.3.0-beta.3 修复。

**解决**：更新到最新版本。在保存配置前，确保在 ok-ww 中已完成配置保存操作（有配置文件产生）。
### 启动任务后莫名其妙中断，状态显示"错误"（ok-ww 3.4.10）

::: tip 通用建议
**原因**：ok-ww 3.4.10 更新日志中的「修复洛瑟菈**错误**/失败战斗」命中了 MAS 的异常关键词「错误」，导致 MAS 误判任务失败。

- 🕐 启动等待时间设置保守一些（60-120 秒），宁可多等也不要太短
- 🔄 游戏更新日建议手动完成更新再启动代理
- 📝 遇到问题时先查看调度台日志，里面包含了游戏配置摘要和详细的流程日志
- 🆘 欢迎加入 AUTO-MAS 官方社群获取更多帮助 — QQ 群：957750551 | Telegram：@AUTO_MAS_top
:::
**解决**：此问题已在 MAS v5.3.1 正式版中修复。如升级后仍有此问题，请尝试重建脚本配置。