#MoonHID

#HID 1.11 兼容目标

node scripts/test-compatibility.mjs

#使用场景

1. 自制键盘：生成按键数组和 LED 描述符，按 Usage 按下/释放按键得到 Input 报告，读取主机发来的 LED Output。 见 Usage 级访问。
2. 鼠标与手柄：生成并解释按钮、相对位移、摇杆轴、Hat 和带 Report ID 的报告，按物理量读写角度等数值。 见 物理量换算。
3. 媒体键与自定义设备：用 Consumer Control 模板生成音量、播放键报告；读写厂商 Usage、Feature 配置和超过 32 位的原始数据。 见 模板与值文件样例。
4. 固件与设备工具：在 CI 检查描述符、验证报告往返，在浏览器查看字段布局和真实设备输入。 见 固件 CI 示例。

#已实现功能

#与成熟 HID 库的功能对比

#安装

moon add We1chan/moonhid@0.6.1

import {
  "We1chan/moonhid" @moonhid,
}

#API 示例

///|
test "README: generate encode and edit keyboard LEDs" {
  let descriptor = match
    @moonhid.DescriptorBuilder::new()
    .usage_page(1)
    .usage(6)
    .collection(1)
    .usage_page(8)
    .usage_range(1, 5)
    .logical_range(0L, 1L)
    .report_size(1)
    .report_count(5)
    .output(2)
    .report_size(3)
    .report_count(1)
    .output(1)
    .end_collection()
    .build() {
    Ok(bytes) => bytes
    Err(_) => fail("generated descriptor rejected")
  }
  let layout = match @moonhid.compile_descriptor(descriptor) {
    Ok(layout) => layout
    Err(_) => fail("layout rejected")
  }
  let wire = match
    @moonhid.encode_report(
      layout,
      @moonhid.Output,
      0,
      [1L, 1L, 0L, 0L, 0L].map(value => @moonhid.Integer(value)),
    ) {
    Ok(bytes) => bytes
    Err(_) => fail("encoding rejected")
  }
  assert_eq(wire, b"\x03")
  let caps_lock = match
    @moonhid.find_fields(layout, @moonhid.Output, 0, { page: 8, id: 2, }) {
    Ok([reference]) => reference
    _ => fail("LED Usage not found")
  }
  assert_eq(
    @moonhid.read_field(
      layout,
      @moonhid.Output,
      wire,
      caps_lock.field_index,
      caps_lock.element_index,
    ),
    Ok(@moonhid.Integer(1L)),
  )
  assert_eq(
    @moonhid.write_field(
      layout,
      @moonhid.Output,
      wire,
      caps_lock.field_index,
      caps_lock.element_index,
      @moonhid.Integer(0L),
    ),
    Ok(b"\x01"),
  )
}

///|
test "README: press keys and set a hat angle by Usage" {
  let keyboard = match
    @moonhid.DescriptorBuilder::new()
    .usage_page(1)
    .usage(6)
    .collection(1)
    .usage_page(7)
    .usage_range(0xe0, 0xe7)
    .logical_range(0L, 1L)
    .report_size(1)
    .report_count(8)
    .input(2)
    .usage_range(0, 0x65)
    .logical_range(0L, 0x65L)
    .report_size(8)
    .report_count(6)
    .input(0)
    .end_collection()
    .build() {
    Ok(bytes) => @moonhid.compile_descriptor(bytes)
    Err(error) => Err(error)
  }
  let keyboard = match keyboard {
    Ok(layout) => layout
    Err(_) => fail("keyboard rejected")
  }
  let idle = match @moonhid.new_report(keyboard, @moonhid.Input, 0) {
    Ok(bytes) => bytes
    Err(_) => fail("no Input report")
  }
  let shift_a = match
    @moonhid.set_usages(keyboard, @moonhid.Input, idle, [
      { page: 7, id: 0xe1, },
      { page: 7, id: 4, },
    ]) {
    Ok(bytes) => bytes
    Err(_) => fail("keys rejected")
  }
  assert_eq(shift_a, b"\x02\x04\x00\x00\x00\x00\x00")
  assert_eq(
    @moonhid.active_usages(keyboard, @moonhid.Input, shift_a),
    Ok([{ page: 7, id: 0xe1, }, { page: 7, id: 4, }]),
  )
  assert_eq(
    @moonhid.clear_usages(keyboard, @moonhid.Input, shift_a, [
      { page: 7, id: 4, },
    ]),
    Ok(b"\x02\x00\x00\x00\x00\x00\x00"),
  )
  // Hat switch: 0..7 maps to 0..315 degrees, with a Null State for "centred".
  let hat = match
    @moonhid.DescriptorBuilder::new()
    .usage_page(1)
    .usage(5)
    .collection(1)
    .usage(0x39)
    .logical_range(0L, 7L)
    .physical_range(0L, 315L)
    .unit(0x14)
    .report_size(4)
    .report_count(1)
    .input(0x42)
    .input(1)
    .end_collection()
    .build() {
    Ok(bytes) => @moonhid.compile_descriptor(bytes)
    Err(error) => Err(error)
  }
  let hat = match hat {
    Ok(layout) => layout
    Err(_) => fail("hat rejected")
  }
  let centred = match @moonhid.new_report(hat, @moonhid.Input, 0) {
    Ok(bytes) => bytes
    Err(_) => fail("no Input report")
  }
  assert_eq(centred, b"\x0f")
  let east = match
    @moonhid.set_physical_value(
      hat,
      @moonhid.Input,
      centred,
      { page: 1, id: 0x39, },
      90.0,
    ) {
    Ok(bytes) => bytes
    Err(_) => fail("angle rejected")
  }
  assert_eq(east, b"\x02")
  assert_eq(
    @moonhid.get_physical_value(hat, @moonhid.Input, east, {
      page: 1,
      id: 0x39,
    }),
    Ok(90.0),
  )
}

///|
test "README: decode one relative axis" {
  let descriptor = b"\x05\x01\x09\x30\x15\x81\x25\x7f\x75\x08\x95\x01\x81\x06"
  let layout = match @moonhid.compile_descriptor(descriptor) {
    Ok(layout) => layout
    Err(_) => fail("descriptor rejected")
  }
  let report = match @moonhid.decode_report(layout, @moonhid.Input, b"\xff") {
    Ok(report) => report
    Err(_) => fail("report rejected")
  }
  assert_eq(report.values[0].value, -1L)
  assert_eq(report.values[0].usage, Some({ page: 1, id: 0x30, }))
}

///|
test "README: Buffered Bytes remain one application stream" {
  let descriptor = match
    @moonhid.DescriptorBuilder::new()
    .report_id(5)
    .report_size(8)
    .report_count(4)
    .input(0x102)
    .build() {
    Ok(bytes) => bytes
    Err(_) => fail("descriptor rejected")
  }
  let layout = match @moonhid.compile_descriptor(descriptor) {
    Ok(layout) => layout
    Err(_) => fail("layout rejected")
  }
  assert_eq(
    @moonhid.encode_report(layout, @moonhid.Input, 5, [@moonhid.Raw(b"MOON")]),
    Ok(b"\x05MOON"),
  )
  let report = match
    @moonhid.decode_report(layout, @moonhid.Input, b"\x05MOON") {
    Ok(report) => report
    Err(_) => fail("report rejected")
  }
  assert_eq(report.values, [])
  assert_eq(report.buffered_values[0].bytes, b"MOON")
}

#快速运行

git clone https://github.com/We1chan/moonhid.git
cd moonhid
moon run src/cmd/main
moon run src/cmd/scenarios
moon run src/cmd/moonhid --target native -- generate keyboard
moon run src/cmd/moonhid --target js -- build examples/declarations/keyboard.json
moon run src/cmd/moonhid --target js -- declare examples/codec/keyboard.hex
moon run src/cmd/moonhid --target native -- encode --kind input --id 0 examples/codec/keyboard.hex examples/codec/keyboard-usages.json

#文件命令行工具

moon run src/cmd/moonhid --target native -- generate keyboard
moon run src/cmd/moonhid --target native -- inspect descriptor.hex
moon run src/cmd/moonhid --target js -- inspect descriptor.hex
moon run src/cmd/moonhid --target native -- lint descriptor.hex
moon run src/cmd/moonhid --target native -- encode --kind output --id 0 examples/codec/keyboard.hex examples/codec/keyboard-led-values.json
moon run src/cmd/moonhid --target native -- encode --kind input --id 0 examples/codec/keyboard.hex examples/codec/keyboard-usages.json
moon run src/cmd/moonhid --target js -- encode --kind feature --id 7 examples/codec/vendor-feature.hex examples/codec/vendor-feature-values.json
moon run src/cmd/moonhid --target native -- decode --kind input descriptor.hex report.hex
moon run src/cmd/moonhid --target js -- replay --kind input examples/firmware-ci/descriptor.hex examples/firmware-ci/frames.txt --expect examples/firmware-ci/expected.jsonl

moon build src/cmd/moonhid --target native --release
./_build/native/release/build/cmd/moonhid/moonhid.exe lint descriptor.hex

#浏览器检查器

node scripts/build-web.mjs
python3 scripts/serve-web.py

#WebHID 实时输入

#支持范围与边界

• 描述符 lint 在布局编译成功后运行，Warning / Info 不改变编译结果。 规则包括 logical_max_sign、physical_max_sign、null_without_room、usage_count、missing_usage、 unaligned_report、field_outside_application、collection_without_usage、 multiple_applications_without_report_id、report_id_shared_across_applications， 触发条件与级别是契约，见 规则依据与限制。JSON v2、bridge、CLI 与中文网页面板均已接入。
• 支持 Input / Output / Feature、Usage / Usage 范围 / 32 位扩展 Usage、 Logical / Physical 范围、Unit / Unit Exponent、Report Size / Count / ID、Global Push / Pop， 并保留 Collection 的类型、Usage、父索引与字段所属集合。
• 零长度短项的数据按 0 解释；零长度 Collection 表示 Physical，零长度 Main flags 表示 0。 Report ID 0 和 Report Count 0 仍拒绝；Report Size 0 不能用于定义字段。
• 变量字段按声明顺序对应 Usage，数量不足时重复最后一个 Usage。 Usage 按区间保留，不展开大范围；数组值按 value - logical_min 索引 Usage 序列；未映射的值保留原值。
• 保留填充字段的布局，解码输出省略 Constant 字段；超宽值存入 opaque_values，不进行整数或 Usage 索引解释；保留超出逻辑范围的值， 通过 in_logical_range 和 is_null 区分异常值与声明的 Null State。
• 字段位偏移从报告载荷的第 0 位计算，不含 Report ID 字节；解码输入必须包含 描述符要求的 ID 前缀，并且长度必须精确匹配，不能带额外传输层前缀或尾部字节。
• 编码按非 Constant 字段、元素顺序要求完整值列表，省略填充字段；不会截断、钳制或自动补齐缺少的数据。 1..32 位用 Integer，超宽字段用 Raw，末字节高位须为零。默认检查 Logical 范围， 声明 Null State 时接受可表示的范围外值；显式 allow_out_of_range=true 可重放其他范围外原值。 新报告的 Constant 和未用尾位为零；write_field 保留它们及所有相邻位。
• Buffered Bytes 按整个 Main 字段消费一个 Raw，长为 Report Size × Report Count / 8； 起始偏移与总长度必须按 8 位对齐，否则返回 buffered_alignment。 解码输出 buffered_values，保留 00、ff 和顺序；不解释 Logical、Physical、Array 或 Null。 字段读写使用元素索引 0；按 Usage 访问整段缓冲区时使用首个 Usage。
• 构建器为有状态、可链式调用的对象，第一项参数错误保留至 build()。 调用方显式定义 Report ID、填充与集合结束；当前不自动分配 ID、补齐字节、推断位宽或优化全局状态。 Minimum ≥ 0 时 Maximum 采用有符号、无符号读法一致的最短宽度（255 生成 26 ff 00）， 只有 2^31 及以上的值使用 4 字节。原始序列化可保存未知项，生成可编译描述符须通过 build()。
• String / Designator 索引和区间保存为字段与 Collection 元数据，随后清空本地状态； Delimiter 按 Linux 的公共 Usage + 第一个集合规则解码，后续集合保存在 alternate_usages。 嵌套、无开启的关闭和未闭合返回 delimiter；索引范围错误返回 local_range， 每类索引最多 1024 段（local_limit），优选与备选 Usage 合计最多 1024 段（usage_limit）。 长项仅支持原始分词，布局编译会拒绝；保留字也明确报错。Buffered Bytes 的 bit 8 已支持，bit 9..31 仍为保留位。 Physical 范围和 Unit 全局项允许存在， 解码返回原始整数；需要时用 physical_value 等接口按 Physical 范围与 Unit Exponent 换算为双精度物理量。 核心保留数字 Usage；页面只补充常见 Usage 名称，不是完整 HID Usage Tables 数据库。
• Usage 级接口把 Logical 0..1 的 Data Variable 元素视为开关；Array 元素在范围外、超出 Usage 列表或选中 Usage ID 0 时视为空。多个元素共用同一 Usage 时返回 ambiguous_usage，Array 已满返回 array_full； 完整规则见 编解码文档。
• 限制：描述符最多 65536 字节，最多 4096 个 Main 报告字段，整数每值 1..32 位，超过 32 位的 Data Variable 字段按原始字节解码， Constant 字段也允许超宽；Data Array 位宽仍限 1..32。 超宽普通字段及跨越超过四个字节的普通元素属于宽松扩展，超出 HID 1.11 §8.4， 不计入标准兼容证据；编译器当前不拒绝这些布局，lint 也不是完整的 HID 符合性检查器。 每报告最多 65536 位，字段元素数量由报告总位数约束（最多 65536 个值），Usage 最多 1024 个区间，单区间可覆盖同一 page 的全部 65536 个 ID， Collection 最多 4096 项，Collection 与 Global 栈深度最多 64。Global Push/Pop 要求平衡。 Unit Exponent 支持 -8..7 的四位编码及常见符号扩展编码；保留 Unit 的系统与保留位。 Physical 缺少任一端点或两端均为 0 时，有效范围采用 Logical 范围，原声明仍可查询。
• 核心库处理离线字节；网页可选 WebHID 只接收 Input，不发送 Output/Feature。 不提供驱动安装或 Boot Protocol 切换；合成样例测试不能代表已兼容所有 HID 设备。

#项目目录

moonhid/
├── moon.mod                 # 模块配置，source = "src"
├── src/                     # MoonBit 源码根目录
│   ├── *.mbt、*_test.mbt    # 核心库及同包测试
│   ├── moon.pkg             # 核心包依赖
│   ├── pkg.generated.mbti   # 核心包公开接口
│   ├── README.mbt.md        # 本文，API 示例参与自动测试
│   ├── browser/             # 浏览器 JS 桥接
│   ├── cmd/                 # 文件 CLI 与演示入口
│   └── examples/            # MoonBit 合成设备样例包
├── examples/                # 设备回归数据与固件 CI 示例
├── web/                     # 检查器页面
├── scripts/                 # 构建、验收与打包脚本
├── docs/                    # 协议说明与验收记录
└── README.md                # 从可执行 README 生成，链接按仓库根目录改写

#开发

moon check --target all --deny-warn
moon build
moon test
moon test --target native
moon test --target js # 需要 Node.js
node scripts/build-web.mjs
node scripts/test-web.mjs
node scripts/test-usability.mjs
node scripts/test-compatibility.mjs
node scripts/firmware-ci.mjs
moon info
moon fmt --check
node scripts/sync-readme.mjs --check

#协议与参考

• USB-IF HID 1.11
• Linux 内核：HID report descriptors

#比赛验收对照

#MoonHID

#HID 1.11 兼容目标

node scripts/test-compatibility.mjs

#使用场景

1. 自制键盘：生成按键数组和 LED 描述符，按 Usage 按下/释放按键得到 Input 报告，读取主机发来的 LED Output。 见 Usage 级访问。
2. 鼠标与手柄：生成并解释按钮、相对位移、摇杆轴、Hat 和带 Report ID 的报告，按物理量读写角度等数值。 见 物理量换算。
3. 媒体键与自定义设备：用 Consumer Control 模板生成音量、播放键报告；读写厂商 Usage、Feature 配置和超过 32 位的原始数据。 见 模板与值文件样例。
4. 固件与设备工具：在 CI 检查描述符、验证报告往返，在浏览器查看字段布局和真实设备输入。 见 固件 CI 示例。

#已实现功能

#与成熟 HID 库的功能对比

#安装

moon add We1chan/moonhid@0.6.1

import {
  "We1chan/moonhid" @moonhid,
}

#API 示例

///|
test "README: generate encode and edit keyboard LEDs" {
  let descriptor = match
    @moonhid.DescriptorBuilder::new()
    .usage_page(1)
    .usage(6)
    .collection(1)
    .usage_page(8)
    .usage_range(1, 5)
    .logical_range(0L, 1L)
    .report_size(1)
    .report_count(5)
    .output(2)
    .report_size(3)
    .report_count(1)
    .output(1)
    .end_collection()
    .build() {
    Ok(bytes) => bytes
    Err(_) => fail("generated descriptor rejected")
  }
  let layout = match @moonhid.compile_descriptor(descriptor) {
    Ok(layout) => layout
    Err(_) => fail("layout rejected")
  }
  let wire = match
    @moonhid.encode_report(
      layout,
      @moonhid.Output,
      0,
      [1L, 1L, 0L, 0L, 0L].map(value => @moonhid.Integer(value)),
    ) {
    Ok(bytes) => bytes
    Err(_) => fail("encoding rejected")
  }
  assert_eq(wire, b"\x03")
  let caps_lock = match
    @moonhid.find_fields(layout, @moonhid.Output, 0, { page: 8, id: 2, }) {
    Ok([reference]) => reference
    _ => fail("LED Usage not found")
  }
  assert_eq(
    @moonhid.read_field(
      layout,
      @moonhid.Output,
      wire,
      caps_lock.field_index,
      caps_lock.element_index,
    ),
    Ok(@moonhid.Integer(1L)),
  )
  assert_eq(
    @moonhid.write_field(
      layout,
      @moonhid.Output,
      wire,
      caps_lock.field_index,
      caps_lock.element_index,
      @moonhid.Integer(0L),
    ),
    Ok(b"\x01"),
  )
}

///|
test "README: press keys and set a hat angle by Usage" {
  let keyboard = match
    @moonhid.DescriptorBuilder::new()
    .usage_page(1)
    .usage(6)
    .collection(1)
    .usage_page(7)
    .usage_range(0xe0, 0xe7)
    .logical_range(0L, 1L)
    .report_size(1)
    .report_count(8)
    .input(2)
    .usage_range(0, 0x65)
    .logical_range(0L, 0x65L)
    .report_size(8)
    .report_count(6)
    .input(0)
    .end_collection()
    .build() {
    Ok(bytes) => @moonhid.compile_descriptor(bytes)
    Err(error) => Err(error)
  }
  let keyboard = match keyboard {
    Ok(layout) => layout
    Err(_) => fail("keyboard rejected")
  }
  let idle = match @moonhid.new_report(keyboard, @moonhid.Input, 0) {
    Ok(bytes) => bytes
    Err(_) => fail("no Input report")
  }
  let shift_a = match
    @moonhid.set_usages(keyboard, @moonhid.Input, idle, [
      { page: 7, id: 0xe1, },
      { page: 7, id: 4, },
    ]) {
    Ok(bytes) => bytes
    Err(_) => fail("keys rejected")
  }
  assert_eq(shift_a, b"\x02\x04\x00\x00\x00\x00\x00")
  assert_eq(
    @moonhid.active_usages(keyboard, @moonhid.Input, shift_a),
    Ok([{ page: 7, id: 0xe1, }, { page: 7, id: 4, }]),
  )
  assert_eq(
    @moonhid.clear_usages(keyboard, @moonhid.Input, shift_a, [
      { page: 7, id: 4, },
    ]),
    Ok(b"\x02\x00\x00\x00\x00\x00\x00"),
  )
  // Hat switch: 0..7 maps to 0..315 degrees, with a Null State for "centred".
  let hat = match
    @moonhid.DescriptorBuilder::new()
    .usage_page(1)
    .usage(5)
    .collection(1)
    .usage(0x39)
    .logical_range(0L, 7L)
    .physical_range(0L, 315L)
    .unit(0x14)
    .report_size(4)
    .report_count(1)
    .input(0x42)
    .input(1)
    .end_collection()
    .build() {
    Ok(bytes) => @moonhid.compile_descriptor(bytes)
    Err(error) => Err(error)
  }
  let hat = match hat {
    Ok(layout) => layout
    Err(_) => fail("hat rejected")
  }
  let centred = match @moonhid.new_report(hat, @moonhid.Input, 0) {
    Ok(bytes) => bytes
    Err(_) => fail("no Input report")
  }
  assert_eq(centred, b"\x0f")
  let east = match
    @moonhid.set_physical_value(
      hat,
      @moonhid.Input,
      centred,
      { page: 1, id: 0x39, },
      90.0,
    ) {
    Ok(bytes) => bytes
    Err(_) => fail("angle rejected")
  }
  assert_eq(east, b"\x02")
  assert_eq(
    @moonhid.get_physical_value(hat, @moonhid.Input, east, {
      page: 1,
      id: 0x39,
    }),
    Ok(90.0),
  )
}

///|
test "README: decode one relative axis" {
  let descriptor = b"\x05\x01\x09\x30\x15\x81\x25\x7f\x75\x08\x95\x01\x81\x06"
  let layout = match @moonhid.compile_descriptor(descriptor) {
    Ok(layout) => layout
    Err(_) => fail("descriptor rejected")
  }
  let report = match @moonhid.decode_report(layout, @moonhid.Input, b"\xff") {
    Ok(report) => report
    Err(_) => fail("report rejected")
  }
  assert_eq(report.values[0].value, -1L)
  assert_eq(report.values[0].usage, Some({ page: 1, id: 0x30, }))
}

///|
test "README: Buffered Bytes remain one application stream" {
  let descriptor = match
    @moonhid.DescriptorBuilder::new()
    .report_id(5)
    .report_size(8)
    .report_count(4)
    .input(0x102)
    .build() {
    Ok(bytes) => bytes
    Err(_) => fail("descriptor rejected")
  }
  let layout = match @moonhid.compile_descriptor(descriptor) {
    Ok(layout) => layout
    Err(_) => fail("layout rejected")
  }
  assert_eq(
    @moonhid.encode_report(layout, @moonhid.Input, 5, [@moonhid.Raw(b"MOON")]),
    Ok(b"\x05MOON"),
  )
  let report = match
    @moonhid.decode_report(layout, @moonhid.Input, b"\x05MOON") {
    Ok(report) => report
    Err(_) => fail("report rejected")
  }
  assert_eq(report.values, [])
  assert_eq(report.buffered_values[0].bytes, b"MOON")
}

#快速运行

git clone https://github.com/We1chan/moonhid.git
cd moonhid
moon run src/cmd/main
moon run src/cmd/scenarios
moon run src/cmd/moonhid --target native -- generate keyboard
moon run src/cmd/moonhid --target js -- build examples/declarations/keyboard.json
moon run src/cmd/moonhid --target js -- declare examples/codec/keyboard.hex
moon run src/cmd/moonhid --target native -- encode --kind input --id 0 examples/codec/keyboard.hex examples/codec/keyboard-usages.json

#文件命令行工具

moon run src/cmd/moonhid --target native -- generate keyboard
moon run src/cmd/moonhid --target native -- inspect descriptor.hex
moon run src/cmd/moonhid --target js -- inspect descriptor.hex
moon run src/cmd/moonhid --target native -- lint descriptor.hex
moon run src/cmd/moonhid --target native -- encode --kind output --id 0 examples/codec/keyboard.hex examples/codec/keyboard-led-values.json
moon run src/cmd/moonhid --target native -- encode --kind input --id 0 examples/codec/keyboard.hex examples/codec/keyboard-usages.json
moon run src/cmd/moonhid --target js -- encode --kind feature --id 7 examples/codec/vendor-feature.hex examples/codec/vendor-feature-values.json
moon run src/cmd/moonhid --target native -- decode --kind input descriptor.hex report.hex
moon run src/cmd/moonhid --target js -- replay --kind input examples/firmware-ci/descriptor.hex examples/firmware-ci/frames.txt --expect examples/firmware-ci/expected.jsonl

moon build src/cmd/moonhid --target native --release
./_build/native/release/build/cmd/moonhid/moonhid.exe lint descriptor.hex

#浏览器检查器

node scripts/build-web.mjs
python3 scripts/serve-web.py

#WebHID 实时输入

#支持范围与边界

• 描述符 lint 在布局编译成功后运行，Warning / Info 不改变编译结果。 规则包括 logical_max_sign、physical_max_sign、null_without_room、usage_count、missing_usage、 unaligned_report、field_outside_application、collection_without_usage、 multiple_applications_without_report_id、report_id_shared_across_applications， 触发条件与级别是契约，见 规则依据与限制。JSON v2、bridge、CLI 与中文网页面板均已接入。
• 支持 Input / Output / Feature、Usage / Usage 范围 / 32 位扩展 Usage、 Logical / Physical 范围、Unit / Unit Exponent、Report Size / Count / ID、Global Push / Pop， 并保留 Collection 的类型、Usage、父索引与字段所属集合。
• 零长度短项的数据按 0 解释；零长度 Collection 表示 Physical，零长度 Main flags 表示 0。 Report ID 0 和 Report Count 0 仍拒绝；Report Size 0 不能用于定义字段。
• 变量字段按声明顺序对应 Usage，数量不足时重复最后一个 Usage。 Usage 按区间保留，不展开大范围；数组值按 value - logical_min 索引 Usage 序列；未映射的值保留原值。
• 保留填充字段的布局，解码输出省略 Constant 字段；超宽值存入 opaque_values，不进行整数或 Usage 索引解释；保留超出逻辑范围的值， 通过 in_logical_range 和 is_null 区分异常值与声明的 Null State。
• 字段位偏移从报告载荷的第 0 位计算，不含 Report ID 字节；解码输入必须包含 描述符要求的 ID 前缀，并且长度必须精确匹配，不能带额外传输层前缀或尾部字节。
• 编码按非 Constant 字段、元素顺序要求完整值列表，省略填充字段；不会截断、钳制或自动补齐缺少的数据。 1..32 位用 Integer，超宽字段用 Raw，末字节高位须为零。默认检查 Logical 范围， 声明 Null State 时接受可表示的范围外值；显式 allow_out_of_range=true 可重放其他范围外原值。 新报告的 Constant 和未用尾位为零；write_field 保留它们及所有相邻位。
• Buffered Bytes 按整个 Main 字段消费一个 Raw，长为 Report Size × Report Count / 8； 起始偏移与总长度必须按 8 位对齐，否则返回 buffered_alignment。 解码输出 buffered_values，保留 00、ff 和顺序；不解释 Logical、Physical、Array 或 Null。 字段读写使用元素索引 0；按 Usage 访问整段缓冲区时使用首个 Usage。
• 构建器为有状态、可链式调用的对象，第一项参数错误保留至 build()。 调用方显式定义 Report ID、填充与集合结束；当前不自动分配 ID、补齐字节、推断位宽或优化全局状态。 Minimum ≥ 0 时 Maximum 采用有符号、无符号读法一致的最短宽度（255 生成 26 ff 00）， 只有 2^31 及以上的值使用 4 字节。原始序列化可保存未知项，生成可编译描述符须通过 build()。
• String / Designator 索引和区间保存为字段与 Collection 元数据，随后清空本地状态； Delimiter 按 Linux 的公共 Usage + 第一个集合规则解码，后续集合保存在 alternate_usages。 嵌套、无开启的关闭和未闭合返回 delimiter；索引范围错误返回 local_range， 每类索引最多 1024 段（local_limit），优选与备选 Usage 合计最多 1024 段（usage_limit）。 长项仅支持原始分词，布局编译会拒绝；保留字也明确报错。Buffered Bytes 的 bit 8 已支持，bit 9..31 仍为保留位。 Physical 范围和 Unit 全局项允许存在， 解码返回原始整数；需要时用 physical_value 等接口按 Physical 范围与 Unit Exponent 换算为双精度物理量。 核心保留数字 Usage；页面只补充常见 Usage 名称，不是完整 HID Usage Tables 数据库。
• Usage 级接口把 Logical 0..1 的 Data Variable 元素视为开关；Array 元素在范围外、超出 Usage 列表或选中 Usage ID 0 时视为空。多个元素共用同一 Usage 时返回 ambiguous_usage，Array 已满返回 array_full； 完整规则见 编解码文档。
• 限制：描述符最多 65536 字节，最多 4096 个 Main 报告字段，整数每值 1..32 位，超过 32 位的 Data Variable 字段按原始字节解码， Constant 字段也允许超宽；Data Array 位宽仍限 1..32。 超宽普通字段及跨越超过四个字节的普通元素属于宽松扩展，超出 HID 1.11 §8.4， 不计入标准兼容证据；编译器当前不拒绝这些布局，lint 也不是完整的 HID 符合性检查器。 每报告最多 65536 位，字段元素数量由报告总位数约束（最多 65536 个值），Usage 最多 1024 个区间，单区间可覆盖同一 page 的全部 65536 个 ID， Collection 最多 4096 项，Collection 与 Global 栈深度最多 64。Global Push/Pop 要求平衡。 Unit Exponent 支持 -8..7 的四位编码及常见符号扩展编码；保留 Unit 的系统与保留位。 Physical 缺少任一端点或两端均为 0 时，有效范围采用 Logical 范围，原声明仍可查询。
• 核心库处理离线字节；网页可选 WebHID 只接收 Input，不发送 Output/Feature。 不提供驱动安装或 Boot Protocol 切换；合成样例测试不能代表已兼容所有 HID 设备。

#项目目录

moonhid/
├── moon.mod                 # 模块配置，source = "src"
├── src/                     # MoonBit 源码根目录
│   ├── *.mbt、*_test.mbt    # 核心库及同包测试
│   ├── moon.pkg             # 核心包依赖
│   ├── pkg.generated.mbti   # 核心包公开接口
│   ├── README.mbt.md        # 本文，API 示例参与自动测试
│   ├── browser/             # 浏览器 JS 桥接
│   ├── cmd/                 # 文件 CLI 与演示入口
│   └── examples/            # MoonBit 合成设备样例包
├── examples/                # 设备回归数据与固件 CI 示例
├── web/                     # 检查器页面
├── scripts/                 # 构建、验收与打包脚本
├── docs/                    # 协议说明与验收记录
└── README.md                # 从可执行 README 生成，链接按仓库根目录改写

#开发

moon check --target all --deny-warn
moon build
moon test
moon test --target native
moon test --target js # 需要 Node.js
node scripts/build-web.mjs
node scripts/test-web.mjs
node scripts/test-usability.mjs
node scripts/test-compatibility.mjs
node scripts/firmware-ci.mjs
moon info
moon fmt --check
node scripts/sync-readme.mjs --check

#协议与参考

• USB-IF HID 1.11
• Linux 内核：HID report descriptors

#比赛验收对照