物品导航与实时检测

概述

本文覆盖两个触发式/调试类任务：

ItemNavigatorTask（界面名称：物品导航）：指向所选物品的最近采集点，并支持按键标记已获取。已有配置默认沿用 master 的本地 WS / 官方地图客户端逻辑；只有显式选择「统一定位」时才读取共享 world.pose。
RealtimeDetectTask（界面名称：实时检测）：循环运行 YOLO 检测，用于在线观察模型、目标类别和置信度表现。

物品导航

使用前提

「旧版兼容」会直接启动本任务的官方地图客户端或本地 WS 服务；旧配置中的 content / 地图账号 会先迁移到全局「导航配置」后继续使用。
「统一定位」推荐在全局「导航配置」中填写「真值content」，或保存账号配置后用「真值地图账号」选择；未配置官方真值时使用本地 ws://127.0.0.1:3001。
「统一定位」会在首次读取坐标时按需启动应用级定位服务；「旧版兼容」不会触碰该服务。
物品点位数据来自 assets/items/map/summary.json 和 assets/items/map/item_names.json。
标记结果写入 configs/marked_points.json，用于避免重复指向已经标记的点位。

配置项

配置项	默认值	说明
`定位实现`	`旧版兼容`	`旧版兼容` 沿用原有 WS / 官方地图客户端；`统一定位` 使用应用级定位服务和全局「导航配置」。
`选择物品`	`[]`	参与导航的物品名称列表；为空时不会筛选出目标。
`标记按键`	`f`	接近目标后用于标记“已获取”的按键。
`标记按住时长`	`2.0`	连续按住标记键的秒数。进入水平距离 20 以内才开始计时，达到该时长即标记为已获取。填 `0`、负数或非数字会回退为默认 2 秒。
`浮层信息`	开	在浮层上显示当前指向目标的物品名、距离、方位与高度。关闭后浮层只保留箭头。
`浮层文字透明度`	`92`	浮层文字的透明度，取值 0-100（0 完全透明，100 完全不透明）。仅在 `浮层信息` 开启时显示。
`浮层背景透明度`	`59`	浮层文字黑色底板的透明度，取值 0-100（0 表示不绘制底板）。仅在 `浮层信息` 开启时显示。
`浮层字号`	`26`	浮层文字字号，按 1080p 窗口高度为基准的像素值，会随窗口高度等比缩放。仅在 `浮层信息` 开启时显示。

透明度与字号每轮读取，改动后在 UI 中即时生效，无需重启任务。浮层文字透明度 / 浮层背景透明度 / 浮层字号 三项在 浮层信息 关闭时会被隐藏。

获取 content

content 是官方地图同步的账号凭证，需要自己从浏览器里取一次。步骤：

打开浏览器，按 F12 打开开发者工具。
访问 https://game.skland.com/map/endfield 并登录。
切到 「网络 / Network」 标签，在筛选框里输入 https://web-api.skland.com/account/info/hg/check。
在筛选后的请求列表里选中该请求，从 「响应 / Response」 中取 data.content 的值（是一长串字符串）。
把该值填入全局「导航配置」的「真值content」；或填入账号配置页后，在「导航配置」中用「真值地图账号」选择该账号。

两种填法二选一即可：直接填全局「真值content」适合临时用一次；存到账号配置页适合多账号长期使用。 content 等同于登录态，不要贴到 issue、聊天群或截图里。

本地 WebSocket（油猴脚本）

未配置 content 时，可以使用浏览器油猴脚本向程序转发位置：

安装浏览器扩展 Tampermonkey（油猴）。
点击任务配置中的「油猴脚本帮助」按钮，打开官网说明并定位到脚本文件；将 assets/scripts/endfield-ws-position-relay.user.js 导入 Tampermonkey 并启用。
访问 https://game.skland.com/map/endfield 并登录，确认脚本允许在该网址运行。
清空任务 content，并取消/清空「地图账号」，确保任务没有取得官方地图凭证。
在「选择物品」中勾选目标，启动物品导航任务。程序监听 ws://127.0.0.1:3001，脚本连接成功后会转发网页地图的位置数据。

如果没有位置数据，检查本机防火墙是否拦截 3001 端口，以及 Tampermonkey 是否允许脚本在目标网址运行。

数据流（统一定位）

flowchart TD
    A[全局真值content / 真值地图账号] --> D{是否有官方真值}
    B[本地 WS 端口 3001] --> C[WorldPoseService 唯一生产者]
    D -->|有| E[官方地图 WS]
    D -->|无| B
    E --> C
    C --> F[RuntimeStateHub: world.pose]
    F --> G[物品导航读取 x/y/z/map_id]
    G --> H[查询 assets/items/map 数据]
    H --> I[绘制方向箭头与目标信息文字]
    I --> J[按住标记键写入 configs/marked_points.json]

注意事项

物品导航依赖当前地图 ID 与坐标数据，点位数据缺失时不会产生有效指向。
任务会在窗口上绘制方向箭头；若看不到箭头，先确认 WebSocket 位置数据是否正常。
浮层在方向箭头下方直接显示当前指向的物品名、水平距离、八方位（北、东北、东、东南、南、西南、西、西北）与上下高度；方位与箭头朝向共用同一坐标系，两者始终一致。附近目标的小箭头以长度表示高差（同高最短、高差越大越长），箭头朝上表示目标在玩家上方。文字块停止刷新 2 秒后自动消失。
文字块的纵向位置会跟随「附近目标」黄色标记云团的原始像素半径下移，因此在 1024×576 到 2560×1440 等各分辨率下都与云团保持约 16px 间隙，不会被标记压住。
关闭 浮层信息 后浮层只保留箭头，并且会立即清掉已显示的文字。headless（无 Qt）模式下浮层没有逐像素透明度：浮层背景透明度 为 0 时不绘制底板，大于 0 时按该值把底板色向中性色混合，近似半透明观感。
「统一定位」的“本地 WS 回退”只发生在全局导航配置没有取得官方 content 时。若已配置官方真值但鉴权或连接失败，当前运行不会自动改用本地 WS；应清空全局「真值content」和「真值地图账号」后再使用本地模式。
标记需要在目标水平距离 20 内连续按住标记键达到「标记按住时长」（默认 2 秒）；中途松键或离开范围会取消本次计时。该配置每轮读取，改动后无需重启任务。
油猴脚本帮助按钮会打开官网物品导航使用说明和脚本目录。

实时检测

使用场景

实时检测用于调试 YOLO 模型，不是面向日常自动化流程的任务。它会持续截图并执行目标检测，便于观察某个模型和目标类别的命中情况。

配置项

配置项	默认值	说明
`YOLO模型`	src/config.py 中 `yolo.default_model`	模型配置键，实际模型和标签维护在 src/yolo/models.py。
`检测目标`	当前模型 labels 的第一个目标	要观察的目标类别。
`检测置信度`	`0.7`	取值范围 `0` 到 `1`，值越高越严格。
`扫描间隔(秒)`	`0.2`	每次检测后的等待时间。

注意事项

目标名称必须存在于所选模型的 labels 中，否则任务会直接报错。
该任务会循环运行，停止时会输出总扫描次数、命中轮次和最高置信度。

相关文档：地图官方 WS 客户端实现 / 账号配置用户指南