# 架构说明

## 系统边界

MoonRobots Gate 将调用方提供的策略文本和站点地图文本转换为确定的数据、诊断、决策、差异和抓取计划。网络传输、存储、重试行为和页面解析不属于本包的职责。

这一边界是有意设计的。协议决策核心应当可以在没有时钟、套接字、DNS 或文件系统状态的情况下接受测试。因此，同一套 MoonBit 库可以运行在 CLI 进程、CI 任务、浏览器 WebAssembly 应用、静态站点工具或爬虫服务中。

## 数据流

```text
robots.txt 文本
    |
    v
防御式解析器 -----> 源位置诊断
    |
    v
Policy 模型 ------> 规范化渲染器
    |  |  \
    |  |   +------> 语义检查器
    |  +----------> 结构差异
    +-------------> 决策引擎
                       |
                       +--> 访问矩阵
                       +--> 行为差异
                       +--> 站点地图冲突
                       +--> 抓取规划器
                                  |
                                  v
                         Markdown / JSON 报告
```

## 模块

### 数据模型

`model.mbt` 负责公共类型。源位置和诊断会与解析后的记录一起传递。规则同时保存原始模式和规范化模式，使报告可以展示作者原文，而匹配过程使用稳定表示。

### 解析器

`parser.mbt` 执行一次逐行扫描，并对输入大小、行数、单行长度、分组数和规则数实施可配置限制。标准指令决定分组结构，扩展指令则单独记录，避免它们意外改变分组边界。

首个 `User-agent` 之前出现的规则会被忽略并生成诊断。连续的 `User-agent` 记录属于同一分组；规则之后再次出现 `User-agent` 时会开始新分组。

### 匹配器

`matcher.mbt` 首先选择最高的产品令牌匹配度。所有达到该匹配度的分组都会贡献规则；如果存在匹配度更高的命名分组，则不会再合并通配符分组。路径匹配器随后选择最长有效模式，并在匹配长度相同时由 `Allow` 胜出。

每个 `Decision` 都保存规范化输入、命中的源行号、用户代理和规则匹配度、合并分组数量，以及完整选择轨迹。

### URL 规范化

`url.mbt` 接受绝对 HTTP 和 HTTPS URL，规范化协议与主机，处理默认端口和片段，并提供来源及路径、查询字符串辅助函数。在审计场景中，它会有意拒绝用户信息和不支持的协议。

### 诊断

`lint.mbt` 在解析后增加语义检查。解析器诊断描述语法和输入约束问题，语义检查诊断描述令人意外或存在风险的策略行为。两者都使用稳定代码和统一严重程度模型。

### 策略工程

`render.mbt` 生成确定的策略文本。`matrix.mbt` 运行命名探针并导出 Markdown 或 CSV。`diff.mbt` 报告结构变化，以及调用方指定探针上的访问结论翻转。

### 站点地图集成

`sitemap.mbt` 实现针对 XML URL 集、XML 站点地图索引和逐行文本站点地图的专用解析器，它不是通用 XML 库。系统可以检查重复条目、格式错误的元数据、跨域地址，以及与指定爬虫有效 Robots 规则的冲突。

### 抓取规划

`frontier.mbt` 是确定性模拟器，不是网络爬虫。它按优先级排列任务，并依次应用 URL 有效性、规范化 URL 去重、深度、Robots 决策、请求数、字节数、单主机数量和抓取延迟约束。每个拒绝结果都有类型化原因和解释详情。

### 聚合审计

`audit.mbt` 组合解析、语义检查和访问矩阵，输出有上限的风险分数、等级、Markdown 报告、JSON 报告和面向 CI 的退出码。

## 错误模型

不受信任的文本通常应产生诊断，而不是抛出异常。严重的输入限制违规会将策略标记为已截断。无效 URL 和站点地图记录仍会显示在报告中。调用方可以过滤严重程度，或使用审计退出码决定是否接受警告。

## 确定性

所有公共分析操作都不会读取网络、时钟、文件系统、随机源或进程环境。只要文本、选项、探针和抓取预算相同，输出顺序和决策结果就完全相同。

## 扩展点

未来的传输包可以在不改变核心的情况下获取和缓存策略。新的站点地图编解码器可以向规划器提供 `SitemapEntry`。搜索引擎专用兼容配置可以构建在 `ParseOptions`、`LintOptions`、决策矩阵和已保存扩展指令之上。