Build Creator

通用最优构筑方法论

Overview

一套 8 步流程 + 一个可复用的脚本骨架 example/。脚本里没有一个角色名 —— 所有角色相关的 东西都写在 spec（JSON）里，换角色只改 spec。

产物：一份可直接导入构筑页的 charSettings JSON（落 outputs/）+ 一张「各来源贡献 / 消融」表。

开工前必读本页的「内核口径」「MOD 合法性」「陷阱」三节，绝大多数返工都错在这三处。 角色机制数值口径先查 .workbuddy/memory/topics/falu-mechanics.md（灾厄武器 / 掉血 / 羽化 / 紊乱）， 线上真实构筑复现查 .workbuddy/skills/charbuild-dps-ablation。

铁律

• 包管理与脚本一律 bun（pnpm 在本机 sandbox 下 corepack 是坏的）。
• 临时脚本、中间产物放 .tmp/；最终 BD 放 outputs/。
• 不要自己起 dev server / build；需要看界面固定访问 http://localhost:1420。
• 代码不写注释（本项目约定，AGENTS.md 那条「必须写注释」对本人发起的改动不适用）。
• 不要用 git 做实验（add/stash/commit/reset 一律别碰）。
• 数值结论必须有出处：要么是数据包里的字段，要么是线上真实构筑，不许模型推测。

8 步流程

步骤 4/5/6 的顺序在本方法论里是「先把不变量钉死，再让搜索填空」：表达式和必带件定死， 魔灵/潜质是离散小枚举，最后才把 MOD 池交给 autoBuild + 自写爬山。

第 1 步：完整阅读角色机制

必须看清的几处（step1-mechanics.ts 会一次性 dump）：

• charMap.get(id)：属性 / 精通 / 额外精通 / 加成 / 专武 （⚠️ 专武 字段是存在的，值就是武器 id；社区俗称的「专武」未必等于它）。
• char.技能[]：每个技能的 类型（伤害 / 增益 / 被动 / 协战）与 字段[]。 注意字段里的 tag —— tag 决定它进不进结算链路（["近战","武器","普攻"] 这类会；没有 tag 的 是「说明性字段」，calculateTargetFunction 不会替你算，比如「受到来自某角色的伤害提高 62%」 必须自己在表达式里乘进去）。
• char.溯源[]：6 条，逐条判断「能不能靠操作维持」（能维持就当常驻，否则按覆盖率折算或直接放弃）。
• 武器：类型（[伤害类型组, 类别]）、伤害类型、加成、熔炼（精炼 1~5 的文本 + 数值上下限）、 技能[] 的字段与 tag。
• 找出所有可用的表达式命名空间：角色:: / 近战:: / 远程:: / 技能名::字段名 / 武器名::字段名， 以及 ! 取值后缀（取面板值）、{属性:值} 临时属性注入、min/max/ceil/floor。

第 2 步：参考线上高人气或推荐构筑

这一步给第 3~6 步准备有出处的先验（铁律：数值结论要么出自数据包、要么出自线上构筑），并定一份 复现基线 —— 之后每一步的改动都跟它比。查询定义见 api-queries.ts 的 buildsQuery / buildQuery，排序逻辑在 server/src/db/mod/build.ts。

• 端点 https://api.dna-builder.cn/graphql（src/env.ts 的 apiEndpoint），公开查询、无需登录； 脚本里直接 fetch，别 import src/api/client.ts（那是 urql + Vue 的浏览器链路）。
• ⚠️ 列表查询不含 charSettings，要按 id 逐份再查详情；sortBy 只认 likes / views， 其余值（含 createdAt）一律落回 updateAt 倒序；buildsCount(charId) 对总数（list 会报告 N/M）； 另有 recommendedBuilds / trendingBuilds 可直接拿推荐与热门。
• 挑选口径：isRecommended / isPinned 优先（推荐通常就是标准答案）→ 再按 likes / views； 时间一律看 updateAt（作者最后一次修改），看 createdAt 会把老构筑当新货； desc 带「AI 驱动生成」的单独标注，别当人肉实测引用； 站内直链 https://dna-builder.cn/char/<charId>/<build.id> 可点开对照。
• 拉取分两段（上游口径：列表只给元数据，BD JSON（charSettings）只有单拉 build(id) 才有）—— 大多数情况只跑 list，挑中几份再 download，不要一上来全量拉：

bun .agents/skills/build-creator/scripts/fetch-online-builds.ts list <charId>           # 元数据列表（含 id），落 .tmp/online-builds/list-<charId>.json
bun .agents/skills/build-creator/scripts/fetch-online-builds.ts download <id> [id...]  # 单拉配装，charSettings 落 .tmp/online-builds/<id>.json

每份拿到 charSettings（JSON 字符串，先 JSON.parse）后按下述去向拆：

1. 复现基线：先 filter 掉数据包已删的 buff（陷阱 18），老构筑引用已下架 MOD / 武器的单独跳过 → normalizeCharSettings → createCharBuildFromSettings(charId, …).calculate()，跟 desc 里作者 手写的 DPS 对账，偏差 >0.1% 说明 charSettings 没吃干净，先修再往下走。作者的 DPS 都带环境口径 （防 / 抗 / 血线 / 属克…），连口径一起记录；dpsList 公开查询返回空，DPS 数字只在 desc 里。
2. buffs → 第 3 步的辅助候选：按命名前缀归队友（XXQ / XXE / XX被动 / XX<N>溯 / XX助战）， 归属不明回 buff.data.ts 查该条目 id 是否等于某角色 id；多份构筑重复出现的辅助组合就是 spec assist 轴 options 的首选。
3. MOD 槽 → 第 6 步 required 候选 + 第 7 步搜索种子：多份构筑都带的件大概率是机制必带； ⚠️ charSettings.modVariants 是同一批槽位的多套配置（变体键 角色/近战/远程/同律 + 中枢）， 统计「几份带了它」必须按构筑去重，逐槽累加会得出超总数的份数。
4. customVariables / targetFunction → 第 4 步的表达式参考：作者手写的估算式，抄结构不抄数值 （换个角色 / 属性 / 武器就失效）。
5. 清洗后的最优线上 charSettings 可整体填进 spec.base 当起点，第 7 步爬山拿它当种子。

第 3 步：辅助排列组合 + buff 组

spec 里把辅助拆成若干「轴」（assist: [{axis, options}]），每轴选一个 option，取笛卡尔积。 每个 option 的 buffs 是 [["buff名", 等级], ...]。

配 buff 组时的三个易漏点：

1. 光环型 MOD（海妖 / 百首 这类，效果描述里含「自身及队友」）：队友能带，写进 buffs 列表就等于「假设队友携带」⇒ 主 C 直接吃这份收益。 ⚠️ 但同一个光环不能两头算：buffMap 里形如 X(属性) 的 BUFF（如 羽翼·鼓舞·背水(风)） 就是同名 MOD 的 生效 自动产生的那个 BUFF；你把它写进 buffs 之后，主 C 自己 再装同名 MOD 就会被算成两份（实测 背水 从 1.182 被算成 1.402）。 ⇒ 用 光环自装排除() 从候选池剔掉这些 MOD（判据见「陷阱清单」第 10 条）。 海妖 自身是 exclusiveSeries 成员 ⇒ 一个槽位只能带一件，别在一个 buff 组里塞两件海妖。
2. 角色专属 buff（如某些角色 id 限定的「大冲击」）只能由该角色的助战提供，写成 buff 名 + 等级。
3. 队友自己的武器/精炼也会生成 buff（buff.data.ts 里形如「XX助战」「XXE」「XX被动+1溯」）， 等级要填对版本（charSkillLevel 一致）。

枚举完把每个组合的 DPS 打出来排序 —— 这是「选辅助」唯一靠谱的依据，不要凭印象。

第 4 步：定计算方向

targetFunction 指向一个 customVariables 里的名字（也可以直接指向技能字段）。 表达式写法（先抄 outputs/法露茜BD-一轮连招一枪.json 的 customVariables 当范式）：

• 先写「一次循环」：段数 × 单段用时 / 攻速 → 循环用时，再写单循环总伤害 → 除回去得 DPS。
• 加乘法分开：加法项直接 a+b，乘法项写成 (1+加成)，别把乘法摊进加和表。
• 独立乘区要单独乘：充盈、血量区（昂扬 × 背水）不是 增伤 池的一部分；但**「敌人受到伤害提高」是增伤加算池**（见陷阱 5），别当独立乘区写。
• 不要照抄别的角色的表达式：同一条式子换个属性/武器就失效（火属性角色的 dot 式子给风属性角色用恒为 0）。
• 表达式是逐条命名的中间量，多写几条方便消融（消融就是删一条/改一个常数再算一次）。

第 5 步：魔灵与潜质

• getPetBuffData(petId) → { passive, active }；主动 buff 按 petCoverage（petAutoCoverage）折算。
• getPetTraits() → 潜质目录（{id, bid, name, r, level, buffName, petSkillLevelBonus}）。 槽位存 [bid, 等级]（不是 id！），4 个槽、槽间不重复、等级 1~3。 buffName 非空的是战斗潜质（能进属性结算），空的是功能潜质（钓鱼之类），别当收益算进去。
• 取法：在候选池里做贪心（每次加/换成边际收益最大的那一条），别手挑。

第 6 步：必带 MOD

写进 spec 的 required：{ charMods: [id...], meleeMods: [...], rangedMods: [...] }。 这些是机制必带（如灾厄流的转化件、缺了整套式子就不成立的核心件）。

还有一类也要放进来：「钥匙型 MOD」 —— 它自己的伤害贡献很小，但提供的属性（技能效益 / 神智 等）是另一条收益的开启条件，或者支撑高耗蓝循环。搜索器只会看到那点小伤害， 一定会把它换掉。判断方法：单件消融时 DPS 变化平平，但拿掉后别处的收益也跟着塌。 第 7 步要带着它们跑搜索，做法见下。

第 7 步：autoBuild + 剔除不合理

const res = build.autoBuild({
    includeTypes: ["charMods", "meleeMods", "rangedMods"],
    preserveTypes: ["charMods", "meleeMods", "rangedMods"], // ← 让「必带 MOD」当种子留下
    fixedMelee: true,
    fixedRanged: true,
    modOptions: modData.filter(...).map(m => LeveledModHelper.withCount(m, undefined, 0, 8)),
})
const nb = res.newBuild

• includeTypes = 这次要（重）构筑的槽位；不在里面的槽位原样不动。
• preserveTypes 里的槽位保留当前已装备的 MOD 当起点；不在里面的会被清空。 ⇒ 想「带着必带件填空」：先把必带件放进 build 的槽位，再把该槽位同时列进 includeTypes 和 preserveTypes。
• modOptions 的 count 是你实际持有的数量（LeveledModHelper.withCount(mod, undefined, 0, n)）。 填 8 等于假设「拥有 8 件」—— 只有 契约者 这类可叠件才需要调这个数，其余填 1~3 更贴近真实。
• ⚠️ autoBuild 自己不做耐受上限校验，它只保证「8 格填满 + 名称/系列互斥 + 属性/限定过滤」。 所以 autoBuild 的输出必须再复核一遍：

for (const [key, tab] of [["charMods","角色"],["meleeMods","近战"],["rangedMods","远程"]]) {
    const cost = (nb as any).getModCostMax(tab)
    const cap  = (nb as any).getModCap(tab)
    if (cost > cap) { /* 剔除/替换最贵的非必带件，然后重跑 */ }
}

• autoBuild 是单轮贪心，容易被局部最优卡住。补一个自写的「爬山 + 扰动重启（ILS）」搜索， 起点取：线上真实构筑 / autoBuild 结果 / 上一轮结果 / 若干随机种子，最后取最优（见 lib.ts 的 optimize）。
• 剔除「不合理」的四类：
  1. 耐受超载（getModCostMax > getModCap）
  2. 属性/限定违规（自查一遍，别信搜索器）
  3. 条件 MOD 不生效（build.checkModEffective(mod).isEffective === false，白占一格）
  4. 机制冲突（例如把「需要掉血」的件和「锁血/免伤」的件同时带上）

第 8 步：消融实验

对每一个「来源」删掉再算一次，按 DPS 落差排序。来源至少要覆盖三类：

• 辅助（逐个队友 / 逐个 buff）—— 这是这一步的主目的：确认哪套 buff 组真的更强。
• 必带 MOD 与 单件 MOD（逐件撤，看边际收益）。
• 机制项（掉血、回血、易伤乘区、溯源覆盖率、手法段数）。

输出表：来源 | 撤掉后 DPS | 落差 %。落差 ≈ 0 的项就是冗余项，从 BD 里删掉。

内核口径（写脚本前必读）