海星社区 · 固件仓库

NearLink（星闪）WS63 / BS2x 固件仓库，供 海星社区 的 「固件商城 / 在线烧录」直接同步。仓库里的 .fwpkg 可以在浏览器里通过 Web Serial 直接烧录，无需安装工具链。

This repository is the single source of truth for the StarFish firmware store. Every project directory contains a firmware.json manifest (bilingual) and one or more .fwpkg images. The site syncs this repository with a shallow git clone and reads the manifests — there is no runtime API dependency.

---

一、目录结构

firmware/
├── README.md
├── CONTRIBUTING.md
├── LICENSE
├── schema/
│   └── firmware.schema.json       # firmware.json 的 JSON Schema
├── scripts/
│   └── validate.mjs               # node scripts/validate.mjs
├── ws63/
│   ├── sle-uart/
│   │   ├── README.md              # 使用说明（可选，但强烈建议）
│   │   ├── firmware.json          # 清单（必需）
│   │   ├── sle-uart-client-20251219.fwpkg
│   │   └── sle-uart-server-20251219.fwpkg
│   └── …
└── bs21e/
    └── bs21e-test/
        ├── README.md
        ├── firmware.json
        └── bs21e-test-20260508.fwpkg

第一层是芯片（只能是 ws63 / bs21e），第二层是项目 slug。 一个项目 = 一个功能 = 一个 firmware.json；同一个功能的客户端/服务端、 不同操作系统版本（LiteOS / OpenHarmony）都放在同一个项目里，用 variant 区分。

二、命名规则

项目目录（slug）

• 小写英文 + 数字 + 连字符：^[a-z0-9]+(-[a-z0-9]+)*$
• 例：sle-uart、sle-throughput-v2、littlefs-shell、hh-k01
• slug 一旦发布不要改名（站点用 chip/slug/variant 做稳定 id）。

固件文件

<slug>[-<variant>][-v<version>]-<YYYYMMDD>.fwpkg

部分	规则	示例
slug	与所在目录完全一致	sle-uart
variant	可选，小写标识	client / server / a / b / c / liteos / ohos
version	可选，X.Y.Z（文件名里带 v 前缀）	ws63-at-v1.10.102-20260508.fwpkg
日期	构建日期，YYYYMMDD	20251219

例：

sle-uart-client-20251219.fwpkg
sle-uart-server-20251219.fwpkg
sle-throughput-v3-display-client-20250105.fwpkg
hh-k01-a-20260508.fwpkg
xiaohong-ai-liteos-20260508.fwpkg
bs21e-test-20260508.fwpkg

三、firmware.json

每个项目一个，UTF-8，2 空格缩进。$schema 指向 schema/firmware.schema.json （编辑器可自动补全和校验）。

{
  "$schema": "../../schema/firmware.schema.json",
  "schema": 1,
  "slug": "sle-uart",
  "chip": "ws63",
  "category": "SLE UART",
  "name": { "zh-CN": "SLE UART 透传", "en": "SLE UART Bridge" },
  "summary": {
    "zh-CN": "基于星闪（NearLink）的无线串口透传固件。",
    "en": "Wireless serial bridging over NearLink."
  },
  "notes": {
    "zh-CN": "Client 与 Server 成对烧录，上电后自动建链。",
    "en": "Flash the client and server as a pair; they connect on power-up."
  },
  "author": "GaoXiaolong",
  "license": "Apache-2.0",
  "updated": "2025-12-19",
  "firmware": [
    { "file": "sle-uart-client-20251219.fwpkg", "variant": "client", "date": "2025-12-19" },
    { "file": "sle-uart-server-20251219.fwpkg", "variant": "server", "date": "2025-12-19" }
  ]
}

字段

字段	必填	说明
schema	✅	固定 1
slug	✅	必须与目录名一致
chip	✅	ws63 或 bs21e，必须与第一层目录一致
category	✅	站点左侧分类的显示名，技术名词不翻译（如 SLE UART）
name	✅	双语项目名，zh-CN + en
summary	✅	双语一句话说明，卡片正文用
notes	❌	双语烧录注意事项，烧录弹窗顶部黄条展示；有特殊复位操作的板子务必写
author	❌	作者/维护者，卡片上展示
license	❌	固件本身的授权
updated	✅	项目最后更新日期，必须等于所有文件里最晚的 date
firmware	✅	至少一项
firmware[].file	✅	文件名，必须真实存在
firmware[].variant	❌	客户端/服务端/板号/OS 版本；同一项目内不能重复
firmware[].version	❌	X.Y.Z；写了就必须出现在文件名里（-vX.Y.Z-）
firmware[].date	✅	构建日期，必须与文件名末尾的 YYYYMMDD 一致
firmware[].channel	❌	stable（默认）或 beta

站点会自动从 git 计算文件大小和 blob sha，不要写进清单。

四、版本策略

• 每个 variant 在目录里只保留一个当前版本。发新版时：删掉旧文件，添加新日期的文件， 同步更新 firmware.json。旧版本由 git 历史保留，不在工作区堆叠。
• 文件名里的日期是构建日期，不是版本号；同一天重建请覆盖同名文件（git 会记录变更）。
• 需要保留多个版本时，用 variant 区分（例如 v1 / v2 作为 variant），不要用同一 variant 放多个文件 —— 站点会把它们显示成两张同名卡片。

五、校验

提交前必须跑：

node scripts/validate.mjs

校验内容：

1. 目录只能是 <chip>/<slug>/，chip ∈ {ws63, bs21e}，slug 符合命名规则
2. firmware.json 能解析，必填字段齐全，slug / chip 与路径一致
3. name / summary 中英双语都非空；notes 如果存在也必须双语
4. 每个文件真实存在，文件名符合 <slug>[-<variant>][-v<version>]-<YYYYMMDD>.fwpkg
5. 文件里的日期与文件名一致，updated 等于最晚的文件日期
6. 目录里没有未登记的 .fwpkg，清单里没有缺失的文件
7. 同一个项目内 variant 不重复

站点同步时（pnpm sync:firmware）会用同一套规则再校验一次；规则不通过就不会生成快照。

六、新增一个固件

1. 新建 ws63/<slug>/（或 bs21e/<slug>/）
2. 放入固件，按上面的规则命名
3. 写 firmware.json（可复制邻近项目改）
4. 写 README.md 说明用途、接线、测试步骤（可选但建议）
5. node scripts/validate.mjs
6. 提交 PR / 直接提交到 main

七、站点如何消费

海星社区的同步脚本：

git clone --depth 1 https://gitcode.com/hinearlink/firmware.git
# 读取每个 <chip>/<slug>/firmware.json
# git ls-tree 提供 size + blob sha
# 生成站点快照 src/data/firmware-catalog.json

• 站点运行时不调用 GitCode API，只读快照；仓库不可用时页面和下载都不受影响。
• 下载走站点代理 /api/firmware/file/<path>?v=<sha>，用 git blob sha 校验内容。
• 因此：只要这个仓库的结构和清单是合法的，站点就能自动上架，不需要改代码。

---

License

固件与文档默认按 Apache-2.0 发布；如单个项目另有授权，在该项目的 firmware.json 的 license 字段与 README 中注明。