Files
myrzx_bot/ranch_web/PRODUCT.md
T

9.4 KiB
Raw Blame History

牧羊人之心牧场助手 · Web 2.0.8

产品约束

把现有桌面助手的功能和操作结构迁移至单管理员 Web 工作台。桌面版是页面顺序、信息密度、业务名称、保护条件与交互的依据,保留桌面兼容。Web 2.0.8,源码发布入口 main,游戏数据版本 1.9.68;桌面正式版保留 1.2.0。启动与配置见 运行说明,Docker 与更新条件见 部署说明,功能与验证状态见 2.0.8 发布说明。

使用者在 Windows 本机配置、验证,随后可在 Linux Docker 常驻运行。多个浏览器访问同一个管理员工作台;账号互相隔离,各账号串行执行,账号之间可以并行。

固定工作台结构

  1. 顶部原生风格菜单:账号、策略、配置、帮助。
  2. 多账号页签,支持新增、切换、移除。
  3. 当前角色昵称、等级、经验、金币、氪金、体力;随机刷新间隔、绿色开启/红色停止、刷新/预览、调试,右上角唯一的日志显示/隐藏按钮。
  4. 同桌面顺序的功能页:登录、培育室、背包、牧场、每日事务、自动孵蛋、自动主线、战斗记录、自动赠礼、自动委托、自动探险、自动扫荡、数据分析、执行计划、收益资料。
  5. 所有功能页共用原有可拖动高度的底部日志区及工具栏,保留常驻状态栏;日志按当前功能筛选,整页刷新或重新进入工作台默认收起。

核心操作

  • 账号密码登录后选择区服进入;恢复已保存会话;退出与清除登录记录。游戏凭据仅交给同源服务端,不进入浏览器持久存储或 URL。
  • 手动选服、恢复会话和自动重登成功读取角色后,默认执行已配置且已勾选的功能,不改变各子功能勾选。用户手动“停止”跨掉线、重登和服务重启保留,点击“开启”恢复;导入配置只替换规则,保留用户启停意图。获取区服候选及失败候选不视为登录成功,服务重启后未成功登录时不执行策略,界面以服务端状态为准。
  • 配置通过中文 schema 生成原生控件;逐蛋孵化/补货规则、物品赠礼保留量、逐魔物培养目标、关卡规则等直接在对应页面编辑。自动保存显示待保存、保存中、失败与已保存状态。
  • 培育室扩建、牧场锁定/解锁、批量派遣/喂养、上下文菜单和费用二次确认沿用核心行为。切换功能页只读取视图,不触发游戏写操作。
  • 主线默认当前主线,可切换筛选。地图按地区默认折叠,展示普通关卡、矿洞、难度、次数和工具库存。探险支持队员手选/自动与完成后自动领奖说明。
  • 数据分析用真实 DTO 绘制 SVG 条形图,保留来源筛选、体力效率、样本和不确定性说明。没有样本时明确说明。
  • 策略统一导入导出;收益 CSV/XLSX 导入与可用数据下载。错误展示具体原因,不把不支持的任务伪装成可执行任务。
  • 帮助可检查 GitHub 正式版本并提交受控更新请求。未配置部署器时明确显示原因,更新提交不表示更新成功。
  • 已在 2.0.1 完成私有仓库和 GHCR 认证的部署,稳定 Release 与正式镜像发布后,可直接通过“帮助 → 检查版本更新…”升级,无需先安装 2.0.2、重复初始化或替换宿主机更新器;升级完成后刷新网页以加载新版界面,安装结果以宿主机健康检查为准。

2.0.8 自动委托与每日历史

  • 自动委托包含“当前委托 / 每日记录”。当前页展示原始候选、任务状态、标注奖励及选择 / 回退原因;城市锁定候选显示不可接取。
  • 策略允许且满足城市、次数、资源与步骤支持条件的候选,跨城市按静态预计氪金20→15→10全局排序。高档不可用时日志说明原因,再选择可执行的低档,不保证全部接取20档。
  • 每日记录按账号、区服、角色隔离,以北京时间(UTC+8)自然日查询接取、推进、领奖和待核对事件,刷新和服务重启后可查。每角色保留最近90天、最多5000条事件。
  • 预计奖励与已确认实际奖励分别展示;实际氪金仅来自确认成功的 taskComplete 领奖回包 response.reward.ke,缺失金额显示“未确认”。接取、推进、预计奖励及旧完成标记不作为到账证据。
  • 旧历史仅从本地任务 journal 可证实的操作部分回填,不推造缺失记录。每日历史用于业务进度,运行详情继续使用原单一底部“自动委托”分类日志。

2.0.7 主培养与资质备用

同种只自动培养已养成的高等级主培养;新资质更好的魔物只作为备用保留,不分配经验、礼物或潜能材料。已启用种类按主培养1只、更优备用最多1只整理,新备用严格更优才替换,同分保留已有备用。主培养到上限或冷却时等待,不向同种备用转移资源。硬保护保留,未勾选种类不扩大自动整理范围。

2.0.8 沿用上述修复及现有界面,历史功能与验证记录见 2.0.7 发布说明。

表单布局(2.0.6 起)

勾选框与右侧文字组成一组;数字、文本与下拉框采用标签在上、控件在下的布局。设置区限定合理宽度,并按可用空间排为多列,每日领取项目在单独分组中排列。界面尺寸变化不改变配置路径、自动保存或策略执行规则。

界面精简(2.0.5 起)

删除字段帮助、页面操作说明等重复小字。页面首次读取与刷新使用内容区居中的圆形加载指示,不再在角落显示“正在读取”“已载入”。保留业务数量、资源费用、运行与错误状态,以及必要确认。

持续运行与自动恢复(2.0.4 起)

账号登录后默认执行已勾选策略,只有用户点击“停止”才暂停;点击“开启”恢复。启停选择由服务端持久保存,掉线、重新登录、关闭网页或服务重启不会误改。停止策略不停止连接监控与自动重登。

网络超时先进行只读恢复检查,成功后继续策略;会话失效按登录页等待分钟数重新登录,失败继续等待重试。保存过登录记录的账号在服务启动时自动恢复;只有清除登录记录或删除账号才取消。原有未确认请求核对与禁止重放规则保留。

2.0.3 底部分类日志

2.0.3 修复 2.0.2 的日志布局。所有功能页只复用原有底部日志区,切换页签即按当前账号、当前功能过滤;取消总日志/全部模式及页内日志框,调试入口保留。没有对应执行日志的只读页显示为空,不补入无关日志。

功能页 日志范围
登录 仅登录记录,排除常规、混合旧记录及赠礼日志
每日事务 每日事务记录
牧场 手动牧场操作、自动潜能突破及对应暂停记录
自动孵蛋、培育室 孵蛋与牧场整理策略记录,包括自动喂养、出售、收取及暂停
自动主线 主线推进记录
自动赠礼 赠礼记录
自动委托 委托记录
自动探险 探险记录
自动扫荡 扫荡及地图挑战记录
  • 顶部右侧是唯一显示/隐藏入口。每次整页刷新(F5)或重新进入工作台默认收起,不沿用旧配置自动展开;配置/状态刷新及调试模式不展开日志。同一浏览器会话内显隐按账号保留,手动展开或隐藏后,切换功能页保持该选择。
  • 原底部工具栏保留。搜索、清空显示、下载、跟随/暂停及滚动位置按账号、页签隔离;清空不删除服务端历史,下载遵循当前范围与搜索条件,账号切换不串用内容或操作状态。
  • 同一账号共用日志拉取;浏览器缓存最多 1200 条,底部最多显示最近 600 条。已有分类与保守旧记录推断沿用原实现,无法明确归属的记录不补入登录或其他功能日志。
  • 手动刷新成功时仅显示简短状态,详细日志只在原底部日志区查看,不弹出诊断提示或大段浮动消息,也不自动展开日志;错误与登录认证反馈沿用原有行为。

2.0.3 补丁只调整日志展示与 Web 版本元数据,游戏玩法、策略及后端日志分类/持久化沿用现有实现。功能与验证范围见 2.0.3 发布说明。

安全与验证

2.0.8 共验证739项独立测试:736通过、3项 Windows 跳过;其中非浏览器662项(659通过、3跳过),浏览器77项全部验证通过。证据与发布门禁见 发布说明;历史版本结果不计入本版。

不发真实游戏 API 测试,不读取或更改私人 local_state 账号。浏览器测试仅使用临时目录、fake 后端或服务端离线演示。所有游戏文本用 textContent 呈现;日志使用服务端脱敏数据。管理登录、同源校验与 cookie 由 API 负责。

技术默认假设

原生 HTML/CSS/ES modules,无 React、npm 构建、CDN 或网络字体。FastAPI 同源提供静态资源和 /api。以共享 WebManager/API/视图 DTO 契约为准,前端不构造游戏在线成功数据。桌面/服务端拥有业务规则,前端拥有展示与交互。1280 和 1600 宽桌面均可操作,小屏允许横向滚动。非业务的布局偏好可以存本机,凭据不可持久化。