MINER 开发者：适配 RigeOS 飞行表
本文面向 MINER（锄头）开发者，说明如何把 Linux MINER 制作为 RigeOS 可下载、可配置、可监控的安装包。适配完成后，用户可以在飞行表中填写矿池、钱包、Worker、算法和附加参数，不需要手工登录每台矿机启动程序。
最短结论
一个新的 MINER 通常只需要完成四件事：提供可直接运行的 Linux 二进制、在包根目录加入 rigeos-miner.json、按要求输出日志，并可选地写入标准统计 JSON。RigeOS 负责下载、启动、停止和运行状态管理。
适用范围
以下两种情况都可以适配：
- 拥有源码：可以完善命令行参数、停止处理和标准统计，能够获得完整体验。
- 只有已授权使用的二进制：可以根据程序已有的命令行参数编写 Manifest；如果程序不能输出标准统计，可以先不声明统计能力。
请只打包你拥有开发权或再发布权的软件，并遵守 MINER、算法组件和第三方依赖的许可证。
飞行表如何启动 MINER
公开适配流程如下：
用户填写飞行表
↓
RigeOS 渲染矿池、钱包和矿机名称
↓
rigeos-miner.json 将字段映射为参数
↓
直接启动 MINER 二进制
↓
采集标准输出、错误输出和可选统计 JSONManifest 中的 arguments 是参数数组，不是 Shell 命令。不要使用 sh -c、eval、管道、重定向或命令替换拼接启动命令。
第 1 步：准备适合飞行表的命令行
MINER 应尽量把下列信息作为独立命令行参数或普通环境变量接收：
- 矿池地址。
- 钱包与矿机模板渲染结果。
- Worker 名称。
- 矿池密码。
- 算法名称。
- TLS 设置。
- 用户附加参数。
同时建议满足以下行为：
- 启动失败时返回非零退出码，并向标准错误输出明确原因。
- 正常日志写入标准输出或标准错误，不依赖固定的系统绝对路径。
- 收到
SIGTERM或SIGINT后停止接收新任务、保存必要状态并及时退出。 - 不自行常驻、后台化或启动无法回收的脱管进程。
- 不把钱包、矿池密码、Token 或测试凭据编译进程序和安装包。
如果某个可选参数不能接受空字符串，不要直接把对应占位符绑定到必传选项。可以让 MINER 接受空值，或者把该选项交给飞行表的“附加参数”。
第 2 步：组织安装包
推荐目录如下：
example-miner/
├── rigeos-miner.json
├── bin/
│ └── example-miner
├── LICENSE
└── README.md要求如下：
rigeos-miner.json必须位于解压后的包根目录。rigeos-miner.json必须是有效的单个 JSON 对象，大小不得超过 64 KiB。- 可执行文件必须带有 Linux 可执行权限。
- 包可以直接包含根目录文件，也可以只包含一个顶层目录。
- 包内路径必须是相对路径，不能包含目录穿越。
- 不能包含符号链接、硬链接、设备文件或其他特殊文件。
- 如果依赖动态库，优先使用构建时 RPATH 或静态链接，不要依赖危险的加载器环境变量。
- 每个发布包只放入与目标矿机架构匹配的二进制；支持多个架构时分别发布文件。
第 3 步：编写 Manifest
文件名固定为 rigeos-miner.json。下面是一个完整示例，参数名称需要按照你的 MINER 实际命令行修改：
{
"schema_version": 1,
"id": "example.miner",
"name": "Example Miner",
"executable": "bin/example-miner",
"working_directory": "bin",
"arguments": [
"--pool",
"{{pool}}",
"--user",
"{{wallet}}",
"--password",
"{{password}}",
"--worker",
"{{worker}}",
"--algorithm",
"{{algorithm}}",
"{{extra_args}}"
],
"environment": {
"EXAMPLE_TLS": "{{tls}}",
"EXAMPLE_RUNTIME_NAME": "{{runtime_name}}"
},
"stats_format": "rigeos_json_v1",
"stop": {
"signal": "TERM",
"grace_seconds": 15
}
}Manifest 字段
| 字段 | 说明 |
|---|---|
schema_version | 当前固定为 1。 |
id | 适配器唯一标识。以小写字母开头，只能包含小写字母、数字、点、下划线和短横线。 |
name | 面向维护者的 MINER 名称。 |
executable | 包内可执行普通文件的相对路径。 |
working_directory | 可选。默认使用可执行文件所在目录。 |
arguments | 启动参数数组，最多 128 项。 |
environment | 可选的普通环境变量，最多 32 项。 |
stats_format | 可选。需要标准统计时填写 rigeos_json_v1。 |
stop.signal | 使用 TERM 或 INT 优雅停止。 |
stop.grace_seconds | 等待优雅退出的时间，范围为 1～120 秒。 |
Manifest 使用严格校验。字段拼写错误、未知字段和未知占位符都会导致准备失败，不会被静默忽略。
飞行表占位符
| 占位符 | 内容 |
|---|---|
| 飞行表中的矿池地址。 |
| 已渲染的钱包与矿机模板。 |
| 当前矿机的可信名称。 |
| 飞行表中的矿池密码。 |
| 飞行表中的算法名称。 |
| 飞行表中的 TLS 设置。 |
| 飞行表中的 MINER 名称。 |
| 用户填写的附加参数。只能作为一个完整数组元素出现一次。 |
只进行普通的引号和反斜杠分词，不展开环境变量、通配符、管道、重定向或命令替换。如果飞行表可能使用附加参数，Manifest 必须声明这个占位符，否则 RigeOS 会拒绝静默丢弃参数。
第 4 步：接入日志和统计
日志
MINER 应把运行日志写到标准输出或标准错误，RigeOS 会把两者收集到当前运行实例的日志中。运行时还会提供 RIGEOS_LOG_FILE，指向当前实例的日志路径；Manifest 不能覆盖这个保留变量。通常无需自行打开该文件，以免与标准输出收集重复。
日志中不要输出完整钱包私密字段、矿池密码、Token 或其他凭据。需要打印启动参数时，应先对敏感值脱敏。
标准统计
需要在 RigeOS 中展示 MINER 算力和份额时，在 Manifest 中声明：
"stats_format": "rigeos_json_v1"运行后，MINER 会收到 RIGEOS_STATS_FILE 环境变量。程序应定期把统计结果写入该路径：
{
"total_hashrate_khs": 1234.5,
"devices": [
{
"index": 0,
"hashrate_khs": 1234.5
}
],
"accepted_shares": 10,
"rejected_shares": 1,
"algorithm": "example",
"version": "1.0.0"
}统计规则：
- 算力统一使用
kH/s，不要写入带单位的字符串。 - 设备编号必须唯一，并与 MINER 识别的设备顺序一致。
- 算力和份额不能为负数、
NaN或无穷大。 - 统计文件最大为 1 MiB，设备数量最多为 128。
- 使用“同目录临时文件 → 完整写入 → 原子重命名”的方式更新，避免 RigeOS 读到半个 JSON。
- 不要通过安装包内的 Shell 脚本临时解析日志并生成统计；优先让 MINER 自身直接写标准统计。
只有二进制且无法生成标准统计时，可以暂时省略 stats_format。此时 MINER 仍可运行并提供日志，但工作台不会获得该 MINER 的标准算力和份额统计。
第 5 步：打包并发布
在 Linux 构建环境执行：
chmod +x example-miner/bin/example-miner
tar -C example-miner -czf example-miner-v1.0.0-linux-amd64.tar.gz .
sha256sum example-miner-v1.0.0-linux-amd64.tar.gz将安装包发布到稳定的 HTTPS 地址，例如：
https://downloads.example.com/miners/example-miner/v1.0.0/example-miner-v1.0.0-linux-amd64.tar.gz发布时注意：
- 下载地址必须使用 HTTPS，并且不能依赖 URL 中的用户名和密码。
- 单个下载包不得超过 512 MiB。
- 新版本使用新的版本目录和文件名，不要原地覆盖已经发布的 URL。
- 不要使用内容会变化的
latest.tar.gz作为飞行表长期地址。 - 在发布页提供版本、架构、文件大小和 SHA-256，方便用户独立核对。
第 6 步：配置测试飞行表
RigeOS 飞行表与 Manifest 的对应关系如下：
| 飞行表字段 | Manifest 中的使用方式 |
|---|---|
| MINER | 用于标识本次运行，对应 |
| MINER 下载地址 | 填写刚发布的 .tar.gz HTTPS 地址。 |
| 钱包与矿机模板 | 支持 %WAL% 和 %WORKER_NAME%，渲染后对应 |
| 矿池地址 | 对应 |
| 矿池密码 | 对应 |
| 算法 | 对应 |
| TLS | 对应 |
| 附加参数 | 对应 |
如果钱包模板已经包含 Worker 名称，不要在 MINER 参数中再次拼接 ，否则可能生成重复的 Worker 后缀。
截图待补充（S04 / S11）
建议图片： 飞行表编辑器中的 MINER 配置区域。 应标出： MINER、下载地址、钱包与矿机模板、矿池、算法、TLS 和附加参数。 脱敏要求： 钱包地址、矿池账户和密码必须打码。
第 7 步：在测试矿机验收
首次测试只选择一台不承载关键任务的矿机：
- 创建测试钱包和测试飞行表。
- 填写与目标矿机架构匹配的 MINER 下载地址。
- 下发飞行表并等待运行结果。
- 在工作台确认飞行表实际版本、MINER 状态、日志和算力。
- 必要时登录测试矿机执行只读检查：
sudo rigectl miner status
sudo rigectl miner logs --lines 200完成以下检查后，才能扩大范围：
- 安装包可以下载并识别 Manifest。
- 参数中的矿池、钱包、Worker 和算法符合预期。
- MINER 能连续稳定运行，并能在失败时输出明确原因。
TERM或INT可以在声明的宽限期内完成退出。- 重新启动后不会留下旧进程或重复挖矿实例。
- 声明标准统计时，工作台能持续显示合理的算力和份额。
- 日志和错误信息没有泄露钱包私密字段或凭据。
常见适配失败
| 现象 | 常见原因 | 处理方法 |
|---|---|---|
| 提示找不到 Manifest | 文件没有位于解压后的包根目录 | 调整压缩包目录结构。 |
| 提示可执行文件不合法 | 路径错误、文件没有执行权限或使用了链接 | 修正 executable 并在打包前执行 chmod +x。 |
| Manifest 字段不合法 | 使用了未知字段、错误 ID 或不支持的停止信号 | 对照本文删除扩展字段并修正取值。 |
| 提示未知占位符 | 占位符拼写错误或自行增加了变量 | 只使用本文列出的占位符。 |
| 附加参数被拒绝 | 飞行表有附加参数，但 Manifest 没有 | 在参数数组中完整声明一次。 |
| 下载后仍是旧版本 | 新内容覆盖了已经使用过的相同 URL | 为每个版本发布新的不可变 URL。 |
| MINER 启动后立即退出 | 参数名不匹配、动态库缺失或工作目录错误 | 在相同 Linux 环境复现命令并查看 MINER 日志。 |
| 没有算力统计 | 未声明统计格式、文件未原子写入或 JSON 字段错误 | 检查 RIGEOS_STATS_FILE 和统计示例。 |
使用 AI 完成适配
使用前准备
把以下材料提供给 AI 编程工具：
- MINER 源码，或者你有权使用的 Linux 二进制。
--help完整输出和一条已经验证可运行的示例命令。- 支持的算法、架构、驱动及 GPU 厂商。
- MINER 当前的日志与统计输出样例。
- 期望的矿池、钱包、Worker、密码、TLS 和附加参数映射。
不要把真实钱包私密字段、矿池密码、Token 或生产凭据交给 AI。使用明确标记为测试用途的假数据。
可直接使用的提示词
复制下面的内容，并替换尖括号中的信息：
你是一名资深 Linux MINER 适配工程师、构建工程师和安全工程师。
目标：
将我提供的 MINER 适配为 RigeOS 飞行表可使用的安装包。最终产物必须包含
Linux 可执行文件和包根目录的 rigeos-miner.json，并提供可复现的构建、打包、
测试和发布说明。
输入资料：
- 适配模式：<拥有源码 / 只有二进制>
- 源码或二进制位置：<路径>
- 目标架构：<linux-amd64 / linux-arm64>
- MINER 版本：<版本>
- --help 输出：<粘贴完整输出>
- 已验证的启动命令：<使用测试钱包和测试矿池的命令>
- 支持的算法：<列表>
- 支持的 GPU/驱动：<列表>
- 日志样例：<粘贴脱敏日志>
- 统计或 API 样例：<没有则写“无”>
RigeOS 公开适配契约：
1. Manifest 文件名固定为 rigeos-miner.json，必须位于压缩包根目录。
2. schema_version 只能为 1。
3. id 以小写字母开头，只能包含小写字母、数字、点、下划线和短横线。
4. executable 和 working_directory 使用包内相对路径。
5. arguments 必须是独立参数数组，禁止 sh -c、eval、管道、重定向和命令替换。
6. 可用占位符只有：{{pool}}、{{wallet}}、{{worker}}、{{password}}、
{{algorithm}}、{{tls}}、{{runtime_name}}、{{extra_args}}。
7. {{extra_args}} 只能作为一个完整数组元素出现一次。如果不支持附加参数，
必须明确说明限制，不能静默丢弃用户参数。
8. stop.signal 只能使用 TERM 或 INT，grace_seconds 范围为 1～120 秒。
9. 如声明 stats_format: rigeos_json_v1，程序必须原子更新 RIGEOS_STATS_FILE。
JSON 使用 total_hashrate_khs、devices[index, hashrate_khs]、
accepted_shares、rejected_shares、algorithm、version；算力单位统一为 kH/s。
10. 普通日志写入 stdout/stderr。不得输出钱包私密字段、密码、Token 或完整凭据。
11. 不得在包中放置符号链接、硬链接、设备文件、真实凭据或未经许可的组件。
12. 新版本必须使用新的不可变 HTTPS URL，不能覆盖旧 URL 的内容。
必须完成的工作：
A. 先检查现有程序的真实命令行和退出行为，列出“已经确认”“需要修改”与
“信息不足”三类结论。不得猜测不存在的参数。
B. 拥有源码时，补充适合飞行表的参数解析、SIGTERM/SIGINT 优雅退出、
脱敏日志，以及可选的 rigeos_json_v1 原子统计输出。
C. 只有二进制时，只能使用它已经支持的参数。不要伪造统计能力；如果无法产生
标准统计，省略 stats_format 并明确说明影响。
D. 生成严格合法的 rigeos-miner.json。不要添加公开契约之外的字段。
E. 生成安装包目录，确保二进制具有执行权限，并给出 tar.gz 打包和 SHA-256 命令。
F. 使用假钱包、测试矿池或本地 Mock 完成参数渲染、启动、退出、异常参数、
统计原子更新和敏感信息泄露测试。
G. 给出 RigeOS 飞行表填写示例，逐项说明 MINER 下载地址、钱包与矿机模板、
矿池地址、密码、算法、TLS 和附加参数应如何填写。
安全和质量要求：
- 不修改 MINER 的挖矿算法或份额计算逻辑，除非我另行明确授权。
- 不下载或执行来源不明的文件，不绕过许可证、签名或安全校验。
- 不使用真实生产凭据做测试。
- 不把“可以编译”当成“已经运行验证”。只报告实际执行过的命令和结果。
- 遇到资料不足时先列出缺少的具体信息，再完成不依赖这些信息的部分。
最终按以下顺序输出：
1. 适配结论与限制。
2. 修改文件和修改原因。
3. 最终安装包目录树。
4. 完整 rigeos-miner.json。
5. 构建、测试、打包和 SHA-256 命令。
6. RigeOS 飞行表字段填写表。
7. 实际测试结果和失败测试结果。
8. 尚未验证的事项、发布风险和回滚方式。AI 生成结果仍需要开发者评审，并在真实但非关键的测试矿机上验收。不要因为生成了 Manifest 就直接向整个矿场发布。