HSR_Nous:博识尊驱动战斗分析与配装优化

目标

为什么是崩铁:模拟精度天花板

设计哲学

项目结构

src/hsr_nous/
├── pipeline/ # 数据访问层:下载 + 加载 + 查询(StarRailRes + Fandom wiki + 关卡编成)
│ └── README.md # pipeline 模块详细文档(文件清单与数据源以彼处为准)
│
├── raw_schema/ # 原始数据模型(对应 StarRailRes schema;纯类型层,不做文件加载)
│ ├── character.py # 角色
│ ├── light_cone.py # 光锥
│ ├── relic.py # 遗器
│ └── enemy.py # 敌人
│
├── sim_schema/ # 仿真器输入格式(sim 的唯一输入)
│ ├── README.md # 文档索引(含各章主题)
│ ├── docs/ # 分章节数据格式设计(按编号分章,00_overview 起)
│ ├── examples/ # 示例输入(build / stage)
│ └── *.py # 数据类定义(actor/action/encounter/policy/rulebook 等)
│
├── adapters/ # 适配层:外部数据 -> sim_schema(主路径为模板生成器,详见 adapters/README.md)
│ ├── template_generator.py # pipeline 结构化数据 -> per-entity DSL YAML 模板
│ ├── template_verifier.py # 模板回读校验(与生成器双份映射互相盯梢)
│ └── *_adapter.py # 旧路径对象适配器(raw_schema -> sim_schema,服务 account/screen 侧)
│
├── sim/ # 战斗模拟器(纯仿真核心,只依赖 sim_schema;编译器+VM 分层,模块地图详见 sim/README.md)
│ ├── engine.py # CombatEngine 战斗主干(回合四段主循环 + 击破 + 敌人行动 + 波次切换)
│ ├── scheduler.py # 距离制调度器(守恒剩余距离主状态 + 红黑树排序)
│ ├── avtree.py # 数组化红黑树(CFS 同构,整树可序列化)
│ ├── bus.py # 事件总线(发射点 / waterfall-emit / modify_event)
│ ├── hooks.py # 模板 hooks 运行时(订阅 + 条件求值 + 效果执行)
│ ├── modifiers.py # modifier 生命周期 + 护盾吸收
│ ├── pipeline.py # 结算管线(两层求值 → effect 原语 → 伤害公式)
│ ├── state.py # 战斗全状态 dataclass(可序列化快照)
│ ├── resources.py # 能量资源三段式(终结技阈值 / 可用性判定)
│ ├── policy_api.py # 策略接口(legal_action_set + 编译策略运行时)
│ ├── montecarlo.py # 多局统计聚合(roll 模式 N 局 → 伤害分布)
│ └── compile/ # 绑定编译层(build/stage YAML → 不可变 CompiledEncounter)
│
├── agents/ # ReAct 风格多 Agent
│ ├── planner.py # 目标拆解与评估计划
│ ├── builder.py # 配装与配队候选生成
│ ├── search.py # 参数空间搜索
│ ├── evaluator.py # 仿真运行与指标计算
│ └── explainer.py # 对比结论与可解释分析
│
└── api/ # 编排层
 └── orchestrator.py # 多 Agent 协作闭环
docs/ # 战斗规则文档(模拟器"唯一事实来源")
├── README.md # 文档导航与使用说明
├── game_rules.md # 战斗规则总览
└── mechanics/ # 详细机制文档(按章节编号,00_game_basics 起,索引见 docs/README.md)
tests/ # 测试目录
data/ # 数据目录(gitignored)
├── starrailres/ # StarRailRes 索引数据(en/ cn/ 等多语言)
├── stages/ # 关卡编成 + 怪物数值(Hakushin + buhflipexplode,红线过滤后落盘)
├── enemies/ # 敌人数据(来源: theBowja/starrail-data,遗留源,断更于 3.2)
├── fandom_skill_data.json # Fandom wiki 技能机制数据(削韧/回能/SP消耗/嘲讽值加成)
└── fandom_enemy_data.json # Fandom 敌人技能/抗性/弱点(extract_fandom_enemies 提取)

模块边界(严格遵守)

StarRailRes (JSON) ──[pipeline 加载]──→ raw_schema(dict 的类型化视图)
 │
 ▼
 [adapters.template_generator]
 │
 ▼
 data/sim_templates/**/*.yaml
 │
 ▼
 [sim.compile.compile_encounter]
 │
 ▼
 CompiledEncounter(绑定后的不可变纯数据)
 │
 ▼
 [sim.engine.CombatEngine.from_compiled] ──→ 仿真结果

核心设计亮点

事件-响应模型

策略模型

policy:
 name: "march_7th_default"
 action_rules:
 - condition: "energy >= ULT_THRESHOLD"
 action: "ultimate"
 priority: 100
 - condition: "skill_points > 0"
 action: "skill"
 priority: 50
 - condition: "true"
 action: "basic"
 priority: 0
 parameters:
 ULT_THRESHOLD: 120

模块命名与世界观

开发工具

安装

uv venv
uv pip install -e ".[dev]"

CLI 命令

# 更新游戏数据(从 StarRailRes GitHub 拉取)
hsr-data-update
# 更新简体中文数据
hsr-data-update --lang cn
# 下载敌人数据(来源: theBowja/starrail-data)
hsr-data-update --enemies
# 下载关卡编成数据(Hakushin + buhflipexplode,含未发布内容红线过滤)
hsr-data-update --stages
# 使用 SSH 下载(国内网络更快,需配置 GitHub SSH key)
hsr-data-update --ssh
# 指定数据目录
hsr-data-update --data-dir ./my_data

数据来源

运行测试

pytest tests/ -v

决策闭环(autoresearch 形态)

关键指标

MVP 范围

下一步

协议