# API

## Core Types

| 类型 | 说明 |
| --- | --- |
| `BtStatus` | 节点 tick 结果：`Success`、`Failure`、`Running` |
| `BtValue` | 黑板值：bool、int、text、empty |
| `Blackboard` | 行为树共享状态 |
| `BtNode` | 行为树节点 |
| `BehaviorTree` | 根节点和节点集合 |
| `BtEngine` | 执行引擎，保存 tick、memory 和 trace |

## 建树方式

MoonBit API：

```moonbit
let tree = @moonbtkit.tree_from_nodes("root", [
  @moonbtkit.selector("root", ["fight", "patrol"]),
  @moonbtkit.condition("fight", "enemy_visible", @moonbtkit.Eq, @moonbtkit.BoolValue(true)),
  @moonbtkit.action_success("patrol"),
])
```

DSL：

```text
root root
blackboard enemy_visible true
selector root fight patrol
condition fight enemy_visible eq true
action patrol patrol_area success mode=patrol
```

DSL 中的 `true`、整数和 `<empty>` 分别表示 bool、int 和 empty。需要保留为文本时使用显式形式 `text:"..."`，例如 `text:"true"`、`text:"42"`。序列化器会自动使用该形式，并转义引号、反斜杠、换行、回车和制表符，因此 Builder 创建的 `BtValue` 可以无损 roundtrip。

解析器会拒绝未闭合引号、引号内的尾随转义、未知 action 状态，以及 `Repeat` / `Retry` 的非正计数；错误信息包含 DSL 行号。

Builder：

```moonbit
let builder = @moonbtkit.new_builder("root")
ignore(builder.selector("root", ["work"]))
ignore(builder.action("work", "do_work", [@moonbtkit.Success]))
let tree = builder.finish()
```

## 执行

| API | 说明 |
| --- | --- |
| `new_engine(tree, blackboard?, config?)` | 创建执行引擎 |
| `BtEngine::tick()` | 执行一帧 |
| `BtEngine::run_until_done(max_ticks?)` | 运行到成功或失败 |
| `BtEngine::trace_digest()` | 生成可复现 digest |
| `timeline_text(events)` | 生成按 tick 分组的执行文本 |
| `tree_to_dot(tree)` | 导出 Graphviz DOT |
| `tree_to_mermaid(tree)` | 导出 Mermaid flowchart |
| `coverage_from_trace(tree, events)` | 统计节点覆盖率 |
| `run_matrix(name, base_dsl, variants)` | 批量运行参数化场景 |
| `profile_trace(name, events)` | 聚合节点执行画像 |
| `audit_fixture(name)` | 生成单个 fixture 的综合审计报告 |
| `audit_fixture_catalog()` | 生成内置场景 catalog 审计结果 |
| `diff_trees(before, after)` | 比较两个行为树版本的结构变化和兼容性 |
| `diff_dsl(before, after)` | 解析并比较两个 DSL 资产 |
| `TreeDiff::markdown()` | 导出资产差异 Markdown 报告 |
| `capture_baseline(name, source)` | 捕获状态、digest、tick 和覆盖率基线 |
| `verify_baseline(source, baseline)` | 验证行为资产是否发生确定性回归 |
| `BaselineReport::markdown()` | 导出回归基线检查报告 |
| `asset_spec(name, source)` | 定义一个具名 DSL 资产及验收预期 |
| `audit_asset(spec)` | 解析、lint、运行并规范化单个资产 |
| `audit_asset_catalog(name, specs)` | 批量审计目录且保留所有错误结果 |
| `AssetCatalogReport::markdown()` | 导出批量资产验收报告 |
| `canonicalize_dsl(source)` | 规范化注释、空白和声明顺序 |
| `asset_fingerprint(source)` | 生成稳定的非密码学资产指纹 |
| `inspect_asset(source)` | 返回规范 DSL、指纹和资产元数据 |

## 校验和测试

| API | 说明 |
| --- | --- |
| `BehaviorTree::validate()` | 校验根节点、重复节点、缺失子节点、环和节点约束 |
| `lint_tree(tree)` | 输出可维护性提示 |
| `smoke_run(...)` | 跑单个树并检查最终状态 |
| `run_case`, `run_cases` | 批量运行用例 |
| `fixture_cases`, `recipe_cases` | 内置场景用例 |

## 资产工程

```moonbit
let before = @moonbtkit.patrol_dsl()
let after = @moonbtkit.mission_selector_dsl()

let diff = @moonbtkit.diff_dsl(before, after)
let identity = @moonbtkit.inspect_asset(after)
let baseline = @moonbtkit.capture_baseline("mission", after)
let catalog = @moonbtkit.audit_asset_catalog("game-ai", [
  @moonbtkit.asset_spec("patrol", before),
  @moonbtkit.asset_spec("mission", after),
])
```

- `diff_dsl` 用稳定节点 ID 识别新增、删除、类型、子节点和根节点变化。
- `inspect_asset` 返回规范 DSL、节点数量、黑板数量和带格式版本的非密码学稳定指纹；0.1.6 使用 `asset-v2`。
- `capture_baseline` / `verify_baseline` 校验状态、digest、tick 和覆盖率。
- `audit_asset_catalog` 批量保留成功和失败结果，不因单个坏资产中断。

## 内置场景

`fixture_catalog()` 覆盖 NPC 战斗、巡逻、机器人配送、Agent 工具选择、Boss 阶段、教程提示、潜行守卫、采集工人、问答 Agent 和任务选择器。

`recipe_catalog()` 提供可参数化的 combat、robot、agent 三类模板。