# Design

MoonBTKit 的核心目标是让行为决策逻辑在 MoonBit 中可描述、可运行、可测试、可回放。

## 设计原则

- 核心功能只依赖 MoonBit，不绑定具体游戏引擎或宿主运行时。
- tick 执行保持确定性，同一输入得到同一 trace digest。
- 黑板使用小型值类型，便于 DSL、测试和 Wasm/JS 目标复现。
- 节点模型覆盖常见行为树能力，但避免在 v1 引入外部脚本执行。
- 示例和 fixture 不是玩具页面，而是可用于回归测试的真实决策场景。

## 模块结构

| 文件 | 说明 |
| --- | --- |
| `moonbtkit.mbt` | 核心类型、黑板、节点、执行引擎 |
| `dsl.mbt` | 行式 DSL 解析和序列化 |
| `analysis.mbt` | 树统计、lint、Markdown 报告和 smoke run |
| `fixtures.mbt` | 内置场景 |
| `checks.mbt` | 断言和批量用例执行 |
| `recipes.mbt` | Builder 和可参数化模板 |
| `timeline.mbt` | trace 分组、过滤、统计和 compact 输出 |
| `visualization.mbt` | Graphviz DOT 与 Mermaid 导出 |
| `coverage.mbt` | 节点访问覆盖率与遗漏节点报告 |
| `matrix.mbt` | 黑板变量场景矩阵与批量回归 |
| `profile.mbt` | 节点执行次数、状态分布和热点画像 |
| `audit.mbt` | 汇总运行、lint、覆盖率、profile 和可视化的审计报告 |
| `asset_diff.mbt` | 行为树资产结构差异与兼容性报告 |
| `baseline.mbt` | 确定性执行基线的捕获、验证与报告 |
| `asset_catalog.mbt` | 任意 DSL 资产目录的批量编译与验收审计 |
| `asset_identity.mbt` | DSL 规范化、稳定指纹和资产身份报告 |

## 确定性与可维护性

- 节点状态由显式数据模型表达，不依赖外部脚本或宿主闭包。
- 同一行为树、黑板和 tick 上限产生相同的执行结果与 trace digest。
- DSL 可以序列化并重新解析；显式 `text:"..."` 编码保留标量样文本的类型，并对引号、反斜杠和控制字符做可逆转义。
- 严格解析会拒绝坏引号、尾随转义、未知状态和非法 Decorator 计数，避免错误资产静默降级。
- 覆盖率、矩阵、profile 和 audit 均消费统一 trace，避免多套执行语义。
- 核心库零第三方依赖，Wasm-GC 与 JS 目标使用同一套测试验证。

## 边界

v1 专注行为决策层，不处理渲染、路径寻路、物理碰撞、外部脚本、网络同步或编辑器 UI。这些能力可以在上层项目中接入，MoonBTKit 保持为可复用基础组件。