Files

123 lines
11 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 项目交接入口
> 整理日期:2026-11-16,Asia/Shanghai。面向没有看过历史对话的新模型。
> 当前应用:Web **2.0.12**;游戏资料基线:Android **1.9.68**;桌面历史正式版本:**1.2.0**。
## 先读这些
1. 本文件:当前状态、工作约束、下一步。
2. [项目上下文](docs/handoff/PROJECT_CONTEXT.md):功能、架构、关键决策和失败教训。
3. [运维与发布交接](docs/handoff/OPERATIONS.md):运行、测试、部署、私有更新通道和凭据定位。
4. [README](README.md)、[Web 产品约束](ranch_web/PRODUCT.md)、[2.0.12 发布说明](analysis/RELEASE_2_0_12.md)。按实际任务再读代码,不需要重新遍历全部反编译文件。
新窗口可以直接输入:**“先阅读 HANDOFF.md 和它链接的两份交接文档,再核对 Git 状态,继续处理我的新需求。”**
## 项目目标与当前状态
这是《牧羊人之心》单管理员、多游戏账号的 BOT。现阶段重点是 Python 后端常驻运行、Web 配置与监控、Windows 本地开发、Linux Docker 部署。用户已经放弃跨游戏平台方向,也撤回过侧边栏管理后台重设计;保留当前紧凑的多账号页签、功能 Tab 和原有底部日志布局。
- 应用功能基线提交:`a9b5f73552bf87efe65b4f0d6fd878bcb14dfbc9`。
- 本地稳定标签:`v2.0.12`,指向上述功能基线;本次交接文档提交不会改变应用版本或重打该标签。
- 2.0.12 已在原 GitHub 发布通道发布,Linux CI、GHCR 镜像和更新器资产均核验通过。
- **没有正在进行的功能开发或待合并代码。** 此次任务仅归档上下文、切换 Git 远程并推送文档。
- **没有手动把 2.0.12 部署到 X99。** 用户通过在线更新安装;用户尚未反馈该版本线上安装及隐藏关卡恢复的最终结果,不要声称生产已验收。
- 工作区有用户自己的 `ranch-policies-1.2.0.dev1.json`。它原本就是未跟踪文件,禁止顺手修改、删除或加入提交。
- 以前的子代理已经结束。没有需要接管的常驻代理、SSH 会话或未完成的实验进程。
## 仓库位置与 Git 迁移
实际项目目录是:
```text
C:\Users\11789\Documents\Projects\Codex_ws\myrzx_bot
```
环境或旧会话可能仍显示 `myrzx_fang`,执行命令时应显式指定实际工作目录,先核对 `git rev-parse --show-toplevel`。
用户于 2026-11-16 要求移除原 GitHub `origin` 的本地远程配置,将已有 `gitea` 重命名为 `origin`:
```text
origin = https://gitea.witchercheung.cn/witcher/myrzx_bot.git
```
- 这里只移除本地 remote,不删除 GitHub 上的仓库。
- 后续日常提交和本次文档推送面向 Gitea `origin/main`。
- 提交身份仍为 `AttilaNet <zbolink@foxmail.com>`,仅使用项目配置,不修改全局身份。
- 原远程配置的本地备份在 `local_state/context_handoff/git-config.before-origin-migration.2026-11-16.private`。
- **Git 远程迁移不等于在线更新通道迁移。** 当前应用仍检查 GitHub Release,镜像仍取 GHCR;旧发布脚本还可能假设 `origin` 是 GitHub。下一次发布先阅读运维交接,不能盲跑旧清理脚本。
- 此次只推送文档所在的 `main`,不创建新 Release、不触发新版本标签,也不假定 Gitea 已拥有原站全部标签。
## 最近完成:2.0.12 隐藏关卡恢复
用户症状:
```text
策略等待处理:扫荡(关卡 0211):遭遇隐藏关卡,请在游戏内手动战斗;禁止自动重发,请在游戏内核对结果
```
根因是扫荡路径识别了隐藏事件,却没有接上已有战斗流程。原客户端的行为已经在 `StageStartPanel.as` 中核验:隐藏事件返回 `stageEvent.hideStageId` 后,取消本次扫荡模式,直接进行该隐藏关卡的**难度 1** 战斗,不再发送第二次 `stageStart`。
已完成的行为:
- 新隐藏记录持久保存入场响应、原始队伍快照及交接证据,接入现有快速 HP/DPS 模型,按战斗时钟完成结算。
- 结算和战果记录使用隐藏关卡 ID,计数只预留一次;停止、恢复、重启和重复回包均有专门回归。
- 普通奖励事件直接发奖,与隐藏战斗分开处理,不能把隐藏事件里的 `result` 当成已经发放的奖励。
- 当时现场的旧记录只有父关卡 `0211`、难度 `3`、提示和 `sampleId`;原响应被日志轮转覆盖,无法还原隐藏 ID。只有满足严格证据条件的精确旧记录才会本地归档为“未完成,已放弃”,保留证据与次数,不伪造服务端结算。
- 旧记录即使找回隐藏 ID,缺少原始队伍快照也不能拿当前属性补算,仍须保留具体中文待核对原因。
- 真正已发送但结果未知的入场、结算、领奖等请求仍然不重放,不能为了消除提示直接删除 pending。
最近验证:**491 项唯一仓库测试,489 通过、2 项 Windows 预期跳过**;另外 2 项 Web 离线探针通过。两支当前队伍与 `hd01`~`hd08` 的 16 种代表组合全部获模型支持,重复试算得到 13 种胜利、3 种失败,单次约 0.4~14 毫秒。模型预测不等于实际游戏通关或线上验收。
## 文件定位
| 文件或目录 | 用途 |
| --- | --- |
| `ranch_web/app.py`、`service.py`、`scheduler.py`、`store.py` | HTTP、账号工作线程、常驻调度、持久化与启停意图 |
| `ranch_web/static/`、`views.py`、`policies.py` | 当前 Web 页面、DTO、策略配置 |
| `ranch_assistant/engine.py` | 共享业务调度、策略执行与待核对恢复 |
| `ranch_assistant/sweeping.py`、`battles.py`、`sweep_recovery.py` | 扫荡、隐藏战斗交接、持久化请求与旧记录证据核对 |
| `ranch_assistant/battle_simulator.py` | 现有快速近似战斗模型;不需要重新实现完整 AIR 引擎 |
| `ranch_assistant/progression.py`、`quests.py`、`commission_history.py` | 主线、委托规划与每日历史 |
| `ranch_assistant/cultivation.py`、`gifts.py`、`breakthrough.py`、`exploration.py` | 主培养、赠礼、潜能突破、探险 |
| `ranch_assistant/data/` | 原版导出的静态资料与战斗配置,避免为界面显示重新请求游戏 |
| `deploy/web/`、`.github/workflows/web-image.yml` | Docker、宿主机更新器与现有 GitHub 镜像发布流程 |
| `analysis/RELEASE_*.md`、`analysis/as3/` | 发布说明、可按需核验的原客户端源码证据 |
| `local_state/`、`test-artifacts/` | 本机凭据、缓存、原始快照、报告及发布辅助工具;目前不随 Git 提交 |
## 失败经验与稳定约束
- **界面改版已撤回**:不要再主动改成跨游戏平台或侧边栏后台。
- **日志只有原来底部那一块**:当前 Tab 决定日志分类;右上角唯一开关;刷新与重新进入默认收起,不恢复总日志或新增各页日志框。
- **运行意图与瞬时状态分开**:登录成功默认执行已勾选功能;只有用户明确“停止”才持久暂停。掉线、内部错误或待核对暂停不能伪装成用户停止,也不能仅凭心跳成功声称策略正在运行。
- **多账号隔离、账号内串行**:快速孵化、赠礼、突破、探险定时器不能调用整个全局 poll,避免半秒一次误跑主线或扫荡。
- **资质备用不培养**:每种主培养固定 1 只,严格更优资质备用最多 1 只;赠礼和经验只给主培养,到上限不能转喂同种备用。锁定、在队、装备、委托保留等保护不能自动解除。
- **战斗使用现有近似模型**:用户明确要求快速公式模型,允许近似,不要重新下载 SDK 或长期折腾原生运行时。现有伤害配置的历史与限制见项目上下文;本轮没有修改参数。
- **旧记录原始输入不可补造**:恢复必须依据入场证据;当前等级/属性不是旧战斗的原始输入。
- **正常登录也有本地 info 日志**:`api.py` 的 `进入参数检查 / info / scope=local` 已精确兼容;不能放宽成忽略全部未知日志。
- **Linux 子进程输入故障已修**:大 stdin 与 `communicate(timeout)` 的 POSIX 重试曾导致超时;现在用匿名临时文件传完整输入,保留取消和大小限制。
- **CI 测试依赖要安装**:保留 `ranch_web/requirements-test.txt` 中的 HTTPX 以及工作流安装步骤;Docker 仍只安装运行依赖。
## 当前判断
最近的隐藏关卡问题已经完成离线复现、修复、独立复核与发布,当前没有新的失败现场需要继续开发。下一步应由用户安装版本并反馈实际结果;如果产生新反馈,以实际运行版本和新的原始日志为准。Git 远程切到 Gitea 已完成,线上更新通道迁移尚未实施,不能把两件事视为同一个已完成任务。
## 下一位模型如何接手
1. 确认实际目录、`git status --short --branch`、本地版本和脱敏后的 remote 目标,先了解是否有用户新增改动。
2. 读取上述两份详细交接文档。用户提出新需求后,围绕相关模块定位;目前不用继续修一个已经发布完成的旧任务。
3. 若用户反馈更新后仍异常,先核对**实际运行版本**、具体账号的 `strategy_requested/manual_stop/strategy_state`、原始请求与 pending 证据,再决定改动;不要把缓存页面、心跳成功、模型不支持和真实战败混为一谈。
4. 用户长期偏好“父模型分析指挥、子代理实施、父模型独立核验”。具体实现交给职责不重叠的子代理,先复现再修复,最后检查实际测试报告和源码哈希,不只接受子代理口头通过。
5. 离线验证可自行完成;真实游戏操作由用户控制。不主动部署 X99;正常交付方式是发布后由用户在线更新。
6. 新发布前先解决当前 Gitea 源码仓库与原 GitHub/GHCR 发布通道的关系,再选择发布流程,不自动重建被用户移除的 GitHub remote。
## 验证材料与本地凭据定位
- 公开说明:`analysis/RELEASE_2_0_12.md`。
- 本机完整 QA:`test-artifacts/hidden-stage-qa/final-report.md`、`final-verification.private.json`。
- 实现冻结:`test-artifacts/hidden-sweep-final/verification.json`。
- 最终审查:`test-artifacts/independent-hidden-review/run_20261114T043503_641431Z/review_report.json`。
- 发布交接:`test-artifacts/releases/v2.0.12/final-handoff.json`。
- 管理员访问记录:`local_state/deployment_x99/access.private.json`;更新通道凭据:`local_state/deployment_x99/update_credentials.private.json`。文件只在本机时,不要假定新 clone 也有。
以上 ignored 路径是本机证据定位,不是仓库携带的附件。新模型不需要依赖先前聊天或自动注入的记忆工具;以当前代码、这些文档及能实际读取的证据为准。