词条维护规范

本规范用于约束 src/content/entities/*.mdx 的维护格式。

目标只有三个：

维护者可以直接写自然语言
数值和机制变量有稳定命名，不会在后续维护中互相覆盖
同一份 MDX 既能给用户阅读，也能被站点解析为结构化变量

适用范围

本规范适用于全部实体词条：

英雄
英雄皮肤条目
猴塔
三路径升级
特殊经济条目
特殊机制条目

当前结论

Astro + MDX 原生支持以下能力：

词条正文渲染
Frontmatter 元数据
组件嵌入
内容集合校验

Astro + MDX 不原生支持以下能力：

自动识别“自然语言 + 自定义变量标记”
自动把正文中的变量抽取成结构化字段
自动检查同一变量是否重复定义或语义冲突

因此本项目采用的正式方向是：

MDX 继续作为唯一维护入口
正文允许使用受控的变量标记语法
构建期增加一层变量解析
页面渲染时同时展示自然语言和变量高亮结果

单文件结构

每个实体 MDX 维持以下结构：

Frontmatter
词条标题
版本信息
中文正文
English 正文

英雄正文按等级组织：

## 等级 1
## 等级 2
## 等级 3

塔正文按基础与路径组织：

## 基础
## 上路
## 中路
## 下路

升级节点在对应路径下直接展开，不额外开“升级图标总表”。

变量标记格式

正文内允许出现以下标准变量标记：

{{变量名|默认值}}

含义如下：

变量名：该段正文中引用的唯一变量键
默认值：当前版本显示给读者的实际值

示例：

- 放置价格：{{bonnie.base.place_cost|700}}
- 解锁条件：{{bonnie.base.unlock_cost|5000}} 猴钞
- 升级所需经验倍率：{{bonnie.base.leveling_multiplier|1.0}} 倍琼斯经验曲线
- 尺寸：{{bonnie.base.size|6}}
- 可放置于：{{bonnie.base.placement|陆地}}
- 覆盖范围：{{bonnie.base.range|40}}

该格式是本项目的正式标准。

不再使用以下写法作为长期标准：

$Bonnie_Price(700)
Bonnie_倍数(1.0)

原因有三点：

不利于稳定解析
变量边界不清晰
不利于做重复校验和自动提取

变量命名规则

变量名统一使用小写英文路径，不使用空格，不使用中文，不使用临时缩写。

格式如下：

实体.域.字段

复杂条目允许继续下钻：

实体.域.子域.字段

示例：

bonnie.base.place_cost
bonnie.base.unlock_cost
bonnie.level.3.rapid_shot.cooldown
bonnie.minecart.upgrade.1.purchase_price
bonnie.minecart.upgrade.1.sell_price
banana_farm.path.top.t3.sell_value
dart_monkey.path.top.t2.damage
quincy.level.10.storm_of_arrows.cooldown

命名约束

一个变量名只能表达一个确定语义。

例如：

bonnie.minecart.upgrade.1.purchase_price 只能表示 Bonnie 一级矿车买价
不能同时拿来表示卖价
不能同时拿来表示爆石价

以下情况视为非法：

同一变量名在不同段落指向不同含义
同一含义出现多个不同变量名
使用 damage2、value_new、test_price 这类临时命名
用自然语言短句直接充当变量名

变量域划分

为避免后续吞设定，变量必须先归类到固定域。

推荐域如下：

base：基础属性
level：英雄等级节点
path：塔升级路径
ability：技能本体
attack：攻击模型
economy：经济规则
sell：出售相关
spawn：召唤物、副单位、轨道物
state：储存、累积、受损阶段
table：需要表格呈现的连续数据

文本与变量的关系

词条正文始终以自然语言为主，变量只用于承载可维护的值。

正确示例：

- 邦尼可花费 {{bonnie.minecart.upgrade.1.purchase_price|300}} 购买一级矿车。
- 一级矿车出售时返还 {{bonnie.minecart.upgrade.1.sell_price|210}} 。
- 一级矿车被打爆后掉落价值 {{bonnie.minecart.upgrade.1.bloonstone_value|150}} 的矿石。

错误示例：

- {{bonnie.minecart.upgrade.1.purchase_price|300}}
- {{bonnie.minecart.upgrade.1.sell_price|210}}
- {{bonnie.minecart.upgrade.1.bloonstone_value|150}}

错误原因：

读者无法直接理解
变量失去语义上下文
后续无法判断同一变量对应哪条机制

英雄规范

英雄词条必须满足：

每个等级节点都保留正文
技能解锁等级必须在正文和 abilitySummary 中都能追溯
等级相关的数值变化应尽量变量化

推荐写法：

## 等级 3

- 获得速射技能。
- 冷却：{{quincy.level.3.rapid_shot.cooldown|45s}}
- 持续时间：{{quincy.level.3.rapid_shot.duration|4.5s}}

猴塔规范

猴塔词条必须满足：

基础段落保留基础属性正文
三路径分别分段
每个升级节点保留对应正文描述
升级图标与对应升级节点直接绑定

推荐写法：

## 上路

<UpgradeHeading entityId="dartMonkey" path="top" tier={1} title={"精准飞镖"} price={150} />

- 伤害：{{dart_monkey.path.top.t1.damage|1}}
- 穿透：{{dart_monkey.path.top.t1.pierce|4}}
- 射程：{{dart_monkey.path.top.t1.range|32}}

特殊经济与连续表格规范

以下对象不得只写散乱正文，必须允许表格化：

Bonnie 矿车升级轨
香蕉农场售卖轨
银行、IMF、Monkey-Nomics 储存与产出轨
任何逐级变化的买价、卖价、爆石价、掉落价

推荐写法是正文描述 + 独立表格变量。

示例：

## 等级 7

- 邦尼此时可购买一级矿车。

| 升级级别 | 所需英雄等级 | 买价 | 卖价 | 爆石价 |
| --- | --- | --- | --- | --- |
| 1 | {{bonnie.minecart.upgrade.1.hero_level_required|7}} | {{bonnie.minecart.upgrade.1.purchase_price|300}} | {{bonnie.minecart.upgrade.1.sell_price|210}} | {{bonnie.minecart.upgrade.1.bloonstone_value|150}} |

Bonnie 专项规则

Bonnie 的矿车系统必须拆成独立变量域。

至少包括：

bonnie.minecart.upgrade.N.hero_level_required
bonnie.minecart.upgrade.N.purchase_price
bonnie.minecart.upgrade.N.sell_price
bonnie.minecart.upgrade.N.minecart_hp_after_purchase
bonnie.minecart.upgrade.N.bloonstone_value
bonnie.minecart.upgrade.N.cap_after_purchase

如果存在卡车系统，则继续拆分：

bonnie.truck.*
bonnie.truck_drop.*

农场专项规则

农场的出售价格与路径强相关，不允许只保留一个总卖价字段。

推荐写法：

banana_farm.path.top.t1.sell_value
banana_farm.path.middle.t3.sell_value
banana_farm.path.bottom.t5.sell_value

如同一升级还涉及存款、产出、回合收益，应继续拆开：

banana_farm.path.middle.t3.bank_capacity
banana_farm.path.middle.t3.income_per_round
banana_farm.path.middle.t5.withdraw_bonus

解析规则

构建期解析器应执行以下动作：

扫描正文中的 {{变量名|默认值}}
生成变量索引表
检查变量名是否重复
检查同一变量默认值是否冲突
将正文中的变量包装为可高亮节点

解析结果至少需要输出：

variableKey
defaultValue
entryId
sectionTitle
lineContext

冲突判定

以下情况必须直接报错，而不是静默覆盖：

同一词条中同一变量名出现不同默认值
不同词条中同一变量名出现不同语义
变量名缺少实体前缀
变量名使用非法层级
表格变量与正文变量冲突

维护建议

维护者编辑词条时，应遵循以下顺序：

先写自然语言
再把明确可变的值替换为变量标记
最后检查变量名是否符合域规则

判断是否应该变量化的标准如下：

会在版本更新中变化的值，应变量化
会被读者反复查询的关键值，应变量化
只是修辞性描述，不需要变量化

最小示例

---
entityId: "bonnie"
name: "Bonnie"
version: "V4.11.1"
officialVersion: "V4.11"
siteFixVersion: 1
languages:
  - "zh-CN"
  - "en-US"
category: "heroes"
entityKind: "hero"
summary: "查询 Bonnie 的中英双语词条、矿车经济与等级节点。"
history:
  - version: "V4.11.1"
    date: "2026-03-22"
    summary: "建立 Bonnie 双语词条与变量化维护规范。"
abilitySummary:
  - unlockLabel: "等级 3"
    detail: "获得第一个主动技能。"
---

# Bonnie

## 版本信息

- 当前版本：{{bonnie.meta.version|V4.11.1}}

## 等级 1

- 放置价格：{{bonnie.base.place_cost|700}}
- 解锁条件：{{bonnie.base.unlock_cost|5000}} 猴钞
- 覆盖范围：{{bonnie.base.range|40}}

正式结论

本项目后续的词条维护标准为：

继续使用 Astro + MDX 维护实体词条
正文坚持自然语言优先
可变值统一写为 {{变量名|默认值}}
变量名必须遵守实体前缀与固定域规则
特殊对象使用可复用的专门变量域，不再发明一次性字段