# MoonDiscover：MoonBit DNS-SD 服务发现库制作与申报计划

制定日期：2026-10-23。执行方式：按里程碑推进，不赶本期截止日期。

本文是一份待执行的工程计划。文中功能、测试、发布与互通均为目标，不能作为已经完成的证据。项目暂名 MoonDiscover，拟用模块名 `mik1e80/dnssd`；建仓前再核对名称。

**推荐交付：通用 DNS-SD 服务浏览、服务解析、记录缓存与变化事件，配套 Native CLI、独立消费示例、真实网络互通证据与离线回放。** 第一个申报版本不承担服务发布者的完整职责。

## 1. 目标和项目价值

用户希望找到局域网中的一个服务，但事先不知道它的 IP 和端口。这个库把“查找某类服务”变成“可供应用使用的实例、目标主机、端口、属性和地址”，并持续报告变化。

三个完整使用场景：

| 场景 | 输入和动作 | 应用得到的结果 | 验收方式 |
| --- | --- | --- | --- |
| 本地开发服务发现 | 查询 `_http._tcp.local.`，指定网卡；独立发布者发布测试 HTTP 服务 | 服务实例、主机、实际端口、TXT；示例程序请求约定路径 | 请求得到该次演示生成的标识，证明使用了发现结果，而非硬编码端点 |
| 桌面伴随程序连接 | 按应用约定的服务类型浏览；同网段另一进程发布实例 | 新实例可解析；属性或端口变动会更新；撤销或记录到期后状态变化 | 两个独立进程，修改属性后核对事件和解析快照 |
| 局域网服务盘点 | 查询用户指定的服务类型，持续观察或导出 JSONL | 名称、来源接口、解析状态、地址、剩余有效期及变化原因 | 与独立工具对照；未见响应只写“观察窗口内未发现”，不推断设备不存在 |

第二个场景如使用未注册的私有服务类型，只作测试约定，不宣传为正式注册类型。项目不要求购买打印机或其他硬件，优先使用可控服务构造证据。

新增价值在于 DNS-SD 的记录组合、服务生命周期、网络适配和可复用 API。单纯增加命令行、网页或测试数量不足以构成主要差异。

## 2. 现有生态和复用决策

需要修正早期调研：**MoonBit 已经存在 mDNS 实现，不能宣传“首个 MoonBit mDNS 库”。**

| 已有项目 | 本次已核对范围 | 本项目应补充的部分 |
| --- | --- | --- |
| `moonbit-community/rtc/mdns` | 面向 WebRTC 的 `.local` 主机 A/AAAA 查询、注册地址应答、超时及地址缓存 | 通用 PTR/SRV/TXT 服务实例浏览、服务聚合、连续变化事件、按网络来源区分缓存 |
| `jinshengmeng46/moon-dns-stub` | DNS 编解码与 Native 解析器；记录类型包括 PTR、SRV、TXT | mDNS 查询调度与 DNS-SD 语义；不能把普通 DNS resolver 直接当服务浏览器 |
| `moonbitlang/async` | 当前代码已有组播加入、发送接口选择等能力 | 核对固定发布版本是否满足 5353 端口共存、接收接口识别和收发要求 |
| Avahi、Bonjour、python-zeroconf | 独立参考实现和互通对象 | 测试时使用，不作为生产逻辑隐藏调用的替代品 |

RTC 模块公开 API 只暴露名称到地址的查询，不包含完整服务实例模型。已有名称限制也不适合直接处理带下划线的服务类型、中文及含点的实例名。有关判断仅针对本次读取的模块，不评价整个 RTC 项目的成熟度。

第一个里程碑必须写出 `docs/dependency-decision.md`，按以下顺序决策：

1. 验证现有 DNS codec 的 API、许可证、UTF-8/二进制行为及后端限制。
2. 如果可直接复用，适配名称与 TXT；把 mDNS 专用缓存、查询器和服务模型留在本项目。
3. 如果依赖根包限定 Native，评估经许可提炼可移植 codec 或向上游贡献独立包。申报不能依赖尚未合并的提案。
4. 确实不适用时，自行实现所需的有限 DNS wire 子集，解释原因并与既有库对照；不要另外申报一个重复的通用 DNS 项目。

`moon-dns-stub` 的 class 字段保留原始位，但其普通 Internet-class 判断不等于 mDNS 高位语义；名称和 TXT 也需要字节级适配。不得假设直接传中文 String 或字符串拆点即可正确工作。

来源：

- https://github.com/moonbit-community/rtc.mbt/blob/main/mdns/pkg.generated.mbti
- https://github.com/moonbit-community/rtc.mbt/blob/main/mdns/dns.mbt
- https://github.com/moonbit-community/rtc.mbt/blob/main/mdns/resolver.mbt
- https://github.com/jinshengmeng46/moon-dns-stub/tree/master/src
- https://github.com/moonbitlang/async

建仓时把上述材料固定到实际核对的提交，避免 `main` 后续变化造成证据漂移。

本次 async 源码核对提交为 `021e5c1fbb782485eb6086d6c8c74009ca75b1d6`，其中 [UDP实现](https://github.com/moonbitlang/async/blob/021e5c1fbb782485eb6086d6c8c74009ca75b1d6/src/socket/udp.mbt) 与 [公开接口](https://github.com/moonbitlang/async/blob/021e5c1fbb782485eb6086d6c8c74009ca75b1d6/src/socket/pkg.generated.mbti) 可用于复查能力和限制。源码快照与Mooncakes发布包的关系仍须通过安装和实验核对。

## 3. 首个可申报版本的范围

建议里程碑标签为 `v0.1.0`，按功能完成度冻结，不按日期强行冻结。

| 能力 | v0.1.0 目标 | 完成证据 |
| --- | --- | --- |
| 服务浏览 | 指定一种或多种服务类型，浏览 `.local.` 域内实例 | 独立发布者真实响应、CLI 输出、公开 API 示例 |
| 服务解析 | 组合 PTR → SRV/TXT → A/AAAA，输出完整或部分解析状态 | 乱序、缺项、分包、重复的场景测试与互通记录 |
| 状态事件 | 实例出现、解析完成、内容更新、不可用/移除及明确原因 | 事件顺序断言，不靠人工看日志判断 |
| 缓存 | 记录级有效期、刷新、goodbye、cache-flush；限制资源占用 | 虚拟时间测试和有界资源案例 |
| 查询 | QM 组播查询、退避、订阅取消、已有答案的利用 | 调度测试和实际发包记录 |
| Native 网络 | 首先完成 IPv4；明确选定接口，保存来源；解决 5353 端口收发 | 每个平台单独完成网络适配验证 |
| CLI | `browse`、`resolve`、`doctor`、`replay`；稳定 JSON 输出 | 实际二进制测试；断网时 replay 仍可运行 |
| 可复用库 | 调用方不必启动 CLI 或复制内部源码 | 仓库外独立消费工程调用发布包 |
| 离线回放 | 相同报文、时间和种子得到相同语义结果 | CI 运行并对照预期事件 |
| 文档与开源交付 | 范围、API、示例、来源、CI、发布包、变更记录 | 公开仓库、固定标签、成功发布与消费记录 |

后端目标按层区分：

- 纯协议/状态核心：JS、Wasm 和 Native，具体目标名称以固定工具链为准，各自实际编译和测试。
- 实时网络入口：Native。优先在用户的 Windows 环境打通，同时用 Linux 验证；实际支持清单只列通过的平台。
- 浏览器：离线回放界面，使用与库一致的核心。浏览器本身不能直接获得普通 UDP 组播能力，不设计虚假的“网页扫描局域网”按钮。
- IPv4 组播传输与 AAAA 记录解码是两回事。即便能够显示 AAAA，也不能写成已经完成 IPv6 组播或 IPv6 连接互通。

本版明确暂缓：完整服务发布者、自动重命名、跨子网/广域 DNS-SD、反射器、后台守护进程、自动发现所有服务类型、复杂网络切换策略，以及未验证的全平台支持。

服务子类型、NSEC 负缓存、复杂多包 Known-Answer 等按规范矩阵单独列出。暂未覆盖的行为不能悄悄用简化实现冒充完整支持；影响正确性的输入应给出限制或诊断。

## 4. 最先消除的技术风险

不要先做网站。先投入约 1—2 个工作日完成网络与依赖验证，结果决定适配层投入。

**4.1 固定版本并验证组播能力**

本次注册表快照中的 `moonbitlang/async` 为 0.22.5。固定工具链、依赖和源码后，验证实际安装版本；不能只看上游 `main` 就承诺可安装能力。

测试至少包含：

1. 选择一张实际网卡，加入 `224.0.0.251:5353`，接收独立发布者的响应。
2. 从正确接口和所选源端口发出查询；用抓包或对端证据核对实际发出的内容。
3. 在同机已有 mDNS 服务运行时测试 UDP 5353 共存；记录系统和相关软件版本。
4. 分别确认所选 socket 能否收、能否发，以及单播回复的行为。不能用临时端口客户端隐瞒完整 mDNS 传输层尚未完成。
5. 有多个活动网卡时，确认能识别入站接口，或使用可证明等效的过滤；“加入某接口组播组”并不自动保证全部收包只来自该接口。
6. 正常取消后端口、任务和句柄释放；网络不可达、接口失效、端口绑定失败均有可理解的错误。

现有 async 的普通 UDP API 与组播专用构造各有限制；`recvfrom` 类 API 未必返回目标地址及入站接口。若不足，采用最小 Native socket 扩展或可维护的上游补丁，职责仅限收发与系统元数据。协议解析、缓存和服务聚合仍由 MoonBit 完成。

通过条件：得到 `transport-spike.md` 和实际收发记录。失败时先解决适配，不把录制报文的演示写成实时联网已经完成。

**4.2 独立互通环境**

准备至少一种独立服务发布者，推荐先用 python-zeroconf，再增加 Avahi。测试 HTTP 服务只返回固定格式的演示标识。

Windows 下的 WSL2、虚拟机和容器不能默认等同真实局域网组播环境。记录网络模式；有条件时使用另一台同网段设备，或经过验证的桥接环境。没有 macOS 不影响首版推进，不必为了凑平台数量购买设备。

## 5. 模块架构与公开接口设计

建议一个仓库，按职责组织包，避免为报名拆成多个相似项目。

```text
src/wire/          DNS 有限编解码/现有 codec 适配
src/model/         标签、服务类型、实例、TXT、端点和错误
src/cache/         记录缓存、到期与更新
src/engine/        查询调度、浏览订阅、服务聚合与事件
src/replay/        虚拟时间、报文录制与重放
src/native/        接口、组播 socket、计时和平台资源
cmd/moondiscover/  Native CLI
examples/         独立调用、HTTP 连接、变化订阅
fixtures/         自建与获准分发的输入/预期结果
tests/interop/    独立实现互通脚本与环境说明
docs/             协议矩阵、依赖决策、证据、申报材料
web/              后期离线回放页面
```

核心入口按以下概念设计，具体 MoonBit 签名在实现阶段确定：

| 操作 | 输入 | 输出/作用 |
| --- | --- | --- |
| `browse` | 服务类型、范围、订阅配置 | 订阅句柄，安排查询 |
| `resolve` | 实例的标签结构、来源范围、超时 | 查询句柄，补齐缺少记录 |
| `ingest` | 报文字节、单调时间、接口/网络范围、来源元数据 | 更新记录和服务状态，排队事件 |
| `advance` | 注入的单调时间 | 处理到期、重试和刷新 |
| `next_deadline` | 引擎状态 | 下一次需要唤醒的时间 |
| `poll_outbound` | 引擎状态 | 待发送报文及目的/接口约束 |
| `poll_event` | 引擎状态 | 服务变化或诊断 |
| `cancel`/`close` | 查询或订阅句柄 | 终止相关活动并释放资源 |

核心不读取系统时钟，不创建 socket；随机源可注入，实时适配层提供非固定种子，测试使用固定种子。时间必须单调；时间回退和计时溢出有明确处理。

关键模型：

- `DnsName` 保存标签字节和展示形式。实例名中的点不能误变成标签分隔符；名称比较与原始展示分开。
- `TxtRecord` 保留原始条目字节及受控查询接口，不能要求所有值都是 UTF-8 文本。
- `ServiceSnapshot` 保存实例、目标、端口、属性、地址、来源范围和完整性状态。
- `RecordCache` 的记录身份包含范围、名称、类型、class 和规范化 RDATA；不要只用名称作整个缓存的键。
- `ServiceSeen` 与 `ServiceResolved` 区分“看见 PTR”与“获得可使用的端点”；变化事件必须携带原因。
- TTL 到期表示本地证据不再有效，不等于已证明设备断线。`Removed` 的命名及原因要使调用方能理解这一点。

## 6. 协议实现注意点

依据 RFC 6762、6763 及其更新/勘误建立逐条矩阵。以下是首版应重点实现和验证的部分，不能替代全文审阅。

| 类别 | 容易出错的地方 | 计划中的处理 |
| --- | --- | --- |
| 名称与 TXT | 中文、实例标签内点、二进制值、重复 key | 字节级模型；展示与比较分离；明确重复 key 和空值行为 |
| 高位标记 | Question class 的 QU 与 response RR class 的 cache-flush 不同 | 编解码保留原始位，语义层分别解释 |
| 查询 | 固定频率高强度扫描，忽略缓存 | 抖动、退避、Known-Answer 和订阅生命周期 |
| 缓存 | goodbye 立即删除、分包 flush 误删 | 按所选规范行为处理宽限与 RRSet；虚拟时间断言 |
| 数据来源 | 将其他人的 query 中 Known Answers 直接当作可信 response 缓存 | 分类解析并采用明确接纳规则 |
| 生命周期 | 重复包重复报告新增；缺少 TXT 就伪造完整服务 | 稳定身份、状态机与部分结果 |
| 链路 | 把 RR TTL 当 IP TTL；一律丢弃所有非255入站包 | 两种 TTL 分开；按响应类型检查链路来源；发送参数与接纳规则分别验证 |

突然断电通常没有 goodbye，不能宣传“一秒内一定移除”。缓存到期、接收到撤销和主动重确认是不同情况。

mDNS 使用的多种计时参数应整理进 `docs/protocol-matrix.md`，与测试逐项对应。限制计时或截断 Known-Answer 时必须考虑协议影响，不靠硬编码“每秒发一次”解决。

## 7. 资源与错误边界

申报前设定并记录可配置限制：报文长度、单包记录数、名称解码步数、缓存条目、服务数、并发订阅/查询数和事件队列长度。数值在真实案例与边界测试后冻结，不把任意默认值写成协议规定。

公开错误至少区分：输入格式错误、资源上限、接口不可用、端口绑定失败、能力不支持、解析超时、订阅取消。未见响应与网络入口失败不能共用一个“未找到”结果。

指针循环、越界和长度整数溢出必须在访问内存前检查。未知记录不需要全部解释，但跳过过程有边界；不能因未知类型导致失步。

报文内容和 TXT 不作为可信命令、路径或 HTML。日志、JSON 与网页展示正确转义。是否连接发现出的地址由示例或调用方明确执行，库本身不自动访问任意服务。

## 8. 分阶段制作安排

预算建议：**120—180 小时，按每周约20—25小时投入，预留6—8周；不熟悉网络编程时再增加学习时间。** 这是工作量估计，不是固定交期。以下阶段可以因实际依赖问题调整，但每阶段应有独立可复查成果。

| 阶段 | 参考投入 | 工作内容 | 退出条件 |
| --- | --- | --- | --- |
| M0：立项与风险验证 | 10—16h | 排重、来源、固定版本、组播/5353收发、独立发布者 | 有实际收发记录；确认实现路线；功能矩阵冻结 |
| M1：数据与报文层 | 16—24h | 名称、TXT、记录、codec复用/适配，损坏输入处理 | 公开模型与编解码通过边界用例；后端约束明确 |
| M2：缓存与服务聚合 | 22—32h | 记录生命周期、分包乱序、部分服务、稳定变化事件 | 虚拟时间场景结果正确，重复包不制造新增 |
| M3：查询和联网入口 | 22—32h | 调度、退避、Known-Answer、取消、Native资源、接口范围 | 能对独立发布者发起浏览并解析，停止后无残留任务 |
| M4：CLI、示例与回放 | 14—22h | JSON输出、doctor、replay、独立消费、HTTP演示 | 在仓库外调用公开API；实际CLI与回放结果一致 |
| M5：互通与发布 | 20—30h | 独立实现、平台矩阵、性能/资源实测、CI、打包、Mooncakes | 验收矩阵有原始证据；干净环境安装并运行 |
| 预留 | 16—24h | 环境差异、协议修复、材料复核 | 已知问题有明确处置，最终版本与证据一致 |

典型周安排：第1周M0；第2周M1；第3周M2；第4周M3；第5周M4；第6周M5；第7—8周修复、第二平台与材料。可以完成一个阶段后再进入下一阶段，不依靠压缩测试时间追进度。

建议每次提交围绕一个可说明的行为或修复，保留真实开发过程。不要为了达到提交次数或代码行数人为拆分历史；本计划不把这类数字当作完成指标。

## 9. 验收用例矩阵

以下为项目自定工程门槛，测试名称和数量可调整，不能仅用“全部测试通过”代替具体行为证据。

| ID | 输入/场景 | 必须观察到的结果 |
| --- | --- | --- |
| T01 | 独立实现发布标准HTTP服务 | 得到正确实例、主机、端口、TXT及地址 |
| T02 | 发现后请求测试HTTP端点 | 返回该次演示标识；代码未硬编码端口 |
| T03 | A/SRV/TXT先到，PTR最后到 | 最终聚合结果与正常顺序一致 |
| T04 | 一个服务分多包到达 | 部分状态清楚，完整后产生解析事件 |
| T05 | 重复同一批响应 | 不重复新增，不导致缓存无界增长 |
| T06 | 同类型两个实例 | 两者均保留，属性和端点不串联 |
| T07 | 实例名含中文、空格和点 | 标签身份与展示正确；查询返回相同实例 |
| T08 | TXT的无值、空值、二进制、重复键 | 原始字节保留，查询语义与文档一致 |
| T09 | 更新TXT或SRV端口 | 快照和事件一致更新，不残留错误端点 |
| T10 | 记录自然到期 | 按虚拟时间变为不完整/不可用，原因可追踪 |
| T11 | goodbye及宽限期间重新收到有效记录 | 正确延迟与恢复，不发生错误闪删 |
| T12 | cache-flush含多个地址并分包 | 不误删仍有效的同组记录 |
| T13 | 查询退避与Known-Answer | 输出时序及内容与所选规则一致 |
| T14 | 取消订阅/退出CLI | 停止相关主动查询，资源释放 |
| T15 | 同名实例出现在两个网络范围 | 核心缓存隔离；实际网络支持按平台能力测试 |
| T16 | 接口断开、端口绑定失败或权限限制 | 明确错误，不显示假成功或假空结果 |
| T17 | 截断、错误长度、指针循环及越界 | 有界错误，无崩溃/无限循环 |
| T18 | 未知RR或与当前问题无关的数据 | 按声明规则处理，不误生成服务 |
| T19 | 超过缓存/事件/查询上限 | 诊断和退化策略明确，内存有界 |
| T20 | 丢包、重复、重排、暂时无响应 | 有限重试，部分/超时状态正确 |
| T21 | 两个进程或系统mDNS服务共用5353 | 真实结果及限制可重现，不靠关闭系统服务掩盖 |
| T22 | 发布包在干净消费工程内安装 | 仅依赖公开包即可编译并调用核心/Native入口 |
| T23 | 相同录制输入和种子多次回放 | 语义事件与预期一致，宿主时间不影响结果 |
| T24 | 对关键逻辑注入语义错误 | 相应测试确实失败，证明断言能检出问题 |

T24选少量高价值故障，例如忽略cache-flush、将实例名按点拆分、收到PTR即标记完整、重复包重复Added；不需要为所有函数做形式化的镜像测试。

## 10. 真实互通与演示设计

**必须完成一条完整闭环：** 独立实现发布 → MoonBit主动查询 → MoonBit解析 → 应用实际使用端点 → 服务变化/撤销 → MoonBit给出状态变化。

推荐互通组合：

| 组合 | 目的 | 证据要求 |
| --- | --- | --- |
| python-zeroconf → MoonDiscover | 易准备的独立服务发现与属性更新 | 对端版本、命令、发布内容、MoonBit实际结果 |
| Avahi → MoonDiscover | Linux常见实现的互通 | OS/版本/接口/网络拓扑、报文和解析结果 |
| Bonjour → MoonDiscover（有环境时） | 增强跨实现验证 | 同上；不能用Avahi兼容模式冒充独立Bonjour实现 |

完整报告保存：源码提交、工具链与依赖版本、平台、对端版本、输入/发布内容、命令、预期、实际、退出码和日志/报文散列。抓包需有来源与授权，演示材料使用自建服务和脱敏数据。

演示建议控制在3—5分钟：

1. 展示一个清晰需求：不知道服务地址，但知道服务类型。
2. 运行Native浏览，显示实例和来源接口。
3. 示例程序使用解析结果请求真实端点。
4. 修改TXT，展示更新；撤销后展示对应原因。
5. 切换到离线回放，演示损坏报文和到期，说明核心可测试。

网页回放属于最后一层展示。先做表格、事件时间线与报文摘要即可，不做复杂网络拓扑动画，不另造与MoonBit核心不一致的JS协议实现。

## 11. 性能和持续集成

性能用固定输入和可重复命令报告，不预设“比Avahi更快”或固定内存节省比例。

建议覆盖50、200、500个服务的自建报文序列、重复响应和长时间虚拟运行。记录输入规模、解析/聚合耗时、缓存/事件峰值及宿主环境；RSS与逻辑条目计数分开。

CI按层设计：

- 各声明后端运行协议核心测试；Native在Windows/Linux分别检查、构建和测试。
- 虚拟时间与离线回放是普通CI必跑项目，不能依赖公共runner一定支持真实局域网组播。
- 独立发布者互通放入可重复的受控测试任务，记录成功运行；无法在CI完成的实网测试明确写出执行环境。
- 命令行退出码、JSON契约、示例和实际打包消费均覆盖。
- 固定最终标签与CI结果；工作流文件存在不等于远端运行成功。

README列出的运行命令必须在冻结版本上实际执行。具体检查命令按当时固定MoonBit工具链生成，避免过早承诺可能变化的命令参数。

## 12. 开源、发布和报名材料

建议许可证为Apache-2.0；最终按所用代码和依赖的兼容性确认。外部代码、参考实现、样本和文档分别记录来源、许可证、使用范围与改动。引用成熟实现作为互通对端，不等于可以直接复制其代码。

当前研究所见正式章程要求使用持续集成、提供必要测试及可运行示例，并发布到Mooncakes。未来报名时重新核对适用章程和主办方通知。官网与章程曾出现赛期日期不一致，本计划不依赖本期日期。

具体出处：[5.1阶段一：申报](https://bxup9uklfcb.feishu.cn/wiki/Dx4Bwd6D1i3GfHkajQCcF7SznEd#doxcnVzdeyiFXRUjuZCelRf30fh)、[5.1阶段三：验收](https://bxup9uklfcb.feishu.cn/wiki/Dx4Bwd6D1i3GfHkajQCcF7SznEd#doxcnhJF38hpDWBd4wNdweX6J5b)、[第七节：开源要求](https://bxup9uklfcb.feishu.cn/wiki/Dx4Bwd6D1i3GfHkajQCcF7SznEd#doxcns76oTzE8vI3q5F8Gohxgme)。申报阶段至少三个预期场景，与验收阶段至少一个可运行示例，是两项不同要求；本计划的三个完整示例是进一步的自定交付目标。

建议提交包：

| 文件/产物 | 应写什么 | 避免的问题 |
| --- | --- | --- |
| README | 三分钟运行、核心API、真实用途、平台、限制 | 只有愿景或截图，评审跑不起来 |
| README.mbt.md或等效可执行示例 | 使用公开API的最小程序 | 示例复制内部函数，不代表可复用 |
| docs/SCOPE.md | 支持矩阵、未支持行为、资源上限 | 把浏览器回放说成实时联网；声称完整RFC |
| COMPARISON.md | RTC/mdns、DNS stub、async、Avahi等的交集和新增层 | “生态唯一”或只对比不相关语言项目 |
| docs/protocol-matrix.md | 规范点、实现位置、测试与限制 | 只写协议名称，没有行为对应关系 |
| docs/interop.md | 独立实现、版本、命令和原始证据 | 只用自写发布器和自写解析器互相证明 |
| docs/verification.md | CI、独立消费、发布包和复现步骤 | 将本地成功写成远端成功 |
| docs/KNOWN_LIMITATIONS.md | 错误、部分状态、平台与网络限制 | 超时一律解释为设备不存在 |
| THIRD_PARTY_NOTICES | 代码、样本、参考及许可范围 | 引用链接存在但缺完整适用条款 |
| CHANGELOG和版本标签 | 最终版本变化、兼容说明 | 发布包、网页和README对应不同提交 |
| 一页项目说明 | 问题、至少三个场景、功能边界、技术路线、差异、验证入口 | 将未完成的路线图写进已交付能力 |
| Mooncakes页面与安装记录 | 模块版本、文档、干净消费结果 | 只有moon package，尚未实际发布 |

个人报名信息、最新活动资格和提交次数由参赛者核对。完成项目材料不等于已经通过资格或验收；本计划不代提交报名表。

一页说明在M0可以形成“拟实现”版本；最终提交时改成与冻结版本相符的实际完成清单。不要在开发前写成已经支持全部能力。

## 13. 什么时候可以报名，什么时候可以申请验收

把内部里程碑分开，避免等全部功能写完才发现选题描述不清，也避免只有空仓库就宣传成果。

**R1：可供资格审核的项目状态（建议内部门槛）**

- 有公开仓库、清晰目标、许可证、真实开发记录和差异性对比。
- 三个使用场景写完整，首版范围及暂缓项可解释。
- 至少有一条真实技术验证：成功收发和解析基础报文；保留原始结果。
- 一页说明诚实区分已完成和拟实现，并符合当期资格审核要求。

这只表示“有具体可审查的项目”，不能替代主办方对报名资格的判断。

**R2：建议作为首个完整申报/验收版本的状态**

- 第3节首版承诺全部有实现、测试和实际入口。
- 浏览、解析、记录更新/撤销闭环可运行；至少一个独立实现真实互通。
- 至少三个完整使用示例，包含仓库外公开API消费。
- 所有声明支持的后端与平台有对应检查，网络限制明确。
- 正确处理损坏输入、资源限制、取消和超时；不存在会阻断核心闭环的已知缺陷。
- CI检查/构建/测试通过；最终标签、说明、证据与发布包一致。
- Mooncakes实际发布成功，干净消费工程能安装与运行。
- 第12节材料齐全，实际报名表内容与版本一致。

**如果只能解析自建报文、显示一张表，或者必须调用系统dns-sd命令才能工作，仍不达到本计划的R2。**

## 14. 后续版本

| 版本阶段 | 扩展 | 进入条件 |
| --- | --- | --- |
| v0.1.x | 首版修复、接口稳定、更多独立互通 | 发现/解析主线已经可靠 |
| v0.2 | 服务发布、probe、冲突处理、公告、更新与goodbye | 有完整应答调度和双向互通测试预算 |
| v0.3 | IPv6组播、更多平台、链路变化 | 逐平台完成接口/作用域和端口适配 |
| 后续 | 子类型、域枚举、更多扩展或上游共享模块 | 有明确使用者和兼容性需求 |

服务发布独立增加约3—5周弹性投入。探测仲裁、重名、公告和应答抑制都需要测试；“发出一条PTR”不能作为发布功能完成。

## 15. 开工顺序

第一件事：建公开仓库、冻结首版范围和对比表。

第二件事：固定工具链与async版本，打通独立发布者与MoonBit的真实组播收发，并核对5353共存及接口来源。

第三件事：决定codec复用方式，完成含中文/点的实例名与二进制TXT的两个最小反例。

这三项成立后再推进完整缓存和查询引擎。每周以已通过的里程碑和实际证据推进，不按代码行数、提交次数或漂亮截图判断完成度。

## 参考来源

1. mDNS规范与勘误入口：https://www.rfc-editor.org/rfc/rfc6762
2. DNS-SD规范：https://www.rfc-editor.org/rfc/rfc6763
3. DNS-SD命名更新：https://www.rfc-editor.org/rfc/rfc8553
4. MoonBit async公开代码：https://github.com/moonbitlang/async
5. async包文档：https://mooncakes.io/docs/moonbitlang/async/socket
6. RTC mDNS模块：https://github.com/moonbit-community/rtc.mbt/tree/main/mdns
7. DNS stub：https://github.com/jinshengmeng46/moon-dns-stub
8. Avahi：https://github.com/avahi/avahi
9. python-zeroconf：https://github.com/python-zeroconf/python-zeroconf
10. 活动官网：https://moonbitlang.github.io/Hackathon2026/
11. 官网公开源码：https://github.com/moonbitlang/Hackathon2026/blob/main/src/App.tsx
12. 正式章程：https://bxup9uklfcb.feishu.cn/wiki/Dx4Bwd6D1i3GfHkajQCcF7SznEd

来源核对截至2026-10-23；未来立项与提交前复核版本、API、规则和已有项目变化。