structs-onboarding

name	structs-onboarding
description	将新玩家引入游戏系统（Structs）。负责处理密钥的创建/恢复、玩家信息的生成（通过“reactor-infuse”或“guildsignup”功能）、星球探索以及基础基础设施的搭建。适用于以下场景：初始化游戏环境、创建新玩家、占领第一个星球或搭建基础设施。搭建所需时间因设备类型而异——使用“Command Ship”大约需要17分钟，而使用“Ore Extractor”或“Refinery”则需要约57分钟。

结构体入门指南

个人文件

在开始之前，请检查 SOUL.md、IDENTITY.md、TOOLS.md、COMMANDER.md 或 USER.md 文件中是否已有内容。如果有，请阅读并合并现有内容，切勿覆盖。这些文件可能包含之前代理的身份信息、人类操作员的偏好设置或您自己的配置信息。将您的身份信息添加到现有内容中。

重要提示：包含破折号的实体 ID（例如 1-42、5-10）会被 CLI 解析器误认为是标志。此技能中的所有交易命令都在位置参数前使用 -- 来避免这个问题。在运行 structsd tx structs 命令时，务必始终包含 --。

流程

第 0 步：密钥管理

如果您使用 路径 B（公会注册），create-player.mjs 脚本可以自动生成助记符——您可以跳到第 1 步，让脚本处理密钥的创建。

如果您使用 路径 A（代理拥有 $alpha）或需要在本地 structsd 密钥库中存储密钥：

structsd keys list

如果密钥不存在，请创建或恢复一个：

• 创建新密钥：structsd keys add [key-name] — 会输出一个助记符。请将其安全保存。
• 从助记符恢复密钥：structsd keys add [key-name] --recover — 系统会提示输入助记符。

获取您的地址：

structsd keys show [key-name] -a

助记符的安全性：将助记符存储在环境变量（STRUCTS_MNEMONIC）中、.env 文件中（该文件不会被纳入 Git 版本控制），或者让指挥官提供助记符。切勿将助记符或私钥提交到仓库中。

警告：structsd keys add --output json 会以 明文 形式将助记符输出到标准输出（stdout）。除非您将输出重定向到安全的位置，否则请避免使用 --output json。

---

第 1 步：检查玩家状态

structsd query structs address [your-address]

如果结果显示的玩家 ID 不是 1-0，则表示已有玩家存在。请跳到 第 3 步：探索星球（如果星球已被探索，则执行后续步骤）。

如果玩家 ID 是 1-0，则表示没有玩家存在——请继续执行第 2 步。

---

第 2 步：创建玩家

根据代理是否拥有 $alpha（原生代币）有两种不同的路径：

路径 A：代理拥有 $alpha

如果地址中已经包含 $alpha 代币，可以委托给一个反应器（验证器）来创建玩家记录。

1. 选择一个验证器/反应器进行委托。
2. 运行命令：structsd tx structs reactor-infuse --from [key-name] --gas auto --gas-adjustment 1.5 -y -- [your-address] [reactor-address] [amount]
3. 检查玩家是否存在：structsd query structs address [your-address] — 每 10 秒重复一次，直到玩家 ID 不再是 1-0。

路径 B：代理没有 $alpha（公会注册）

加入一个支持程序化注册的公会。捆绑的 create-player.mjs 脚本会处理整个流程：生成助记符、代理消息签名、发送公会 API 请求以及检查玩家创建情况。该脚本会返回一个包含所有所需信息的 JSON 对象。

1. 选择一个公会 指挥官可以通过 TOOLS.md 或环境配置来指定公会。否则，可以从参考节点查询可用的公会：

curl http://reactor.oh.energy:1317/structs/guild

reactor.oh.energy 是由 Slow Ninja 团队（Orbital Hydro 公会）运营的一个可靠的 Structs 网络节点。

2. 获取公会的 API 端点 每个公会记录都有一个指向其配置的 endpoint URL。获取该 URL 并查找 services.guild_api 和 services.reactor_api。并非所有公会都提供这些信息——如果这些字段为空，说明该公会不支持程序化注册。

注意：某些公会配置可能使用 guildApi（驼峰式命名法）而不是 guild_api（蛇形命名法）。在程序化处理时请同时检查这两个字段。

示例公会配置：

{
  "guild": {
    "id": "0-1",
    "name": "Orbital Hydro",
    "tag": "OH",
    "services": {
      "guild_api": "http://crew.oh.energy/api/",
      "reactor_api": "http://reactor.oh.energy:1317/",
      "client_websocket": "ws://reactor.oh.energy:26657"
    }
  }
}

3. 运行创建玩家的脚本 要求：需要 Node.js 18+ 版本（以支持内置的 fetch 功能）。请先安装相关依赖项：

cd .cursor/skills/structs-onboarding/scripts && npm install

然后从工作区根目录运行脚本：

node .cursor/skills/structs-onboarding/scripts/create-player.mjs \
  --guild-id "0-1" \
  --guild-api "http://crew.oh.energy/api/" \
  --reactor-api "http://reactor.oh.energy:1317" \
  --username "your-chosen-name"

脚本将：

1. 生成一个新的助记符（或使用 --mnemonic "..." 来恢复现有的助记符）
2. 推导出地址和公钥
3. 检查该地址是否已有玩家存在
4. 签署加入公会的代理消息并发送到公会 API
5. 检查反应器 API，直到确认玩家 ID（默认超时时间为 120 秒）
6. 将所有结果以 JSON 格式输出到标准输出

注意：当玩家加入公会后，他们的默认等级为 101。公会领导层可以 later 提升成员的等级。有关等级管理的详细信息，请参阅 structs-guild 技能。

输出格式（请解析此 JSON）：

{
  "success": true,
  "mnemonic": "word1 word2 ... word24",
  "address": "structs1...",
  "pubkey": "a1b2c3...",
  "player_id": "1-42",
  "guild_id": "0-1",
  "username": "your-chosen-name",
  "created": true,
  "next_step": "structsd tx structs planet-explore --from [key-name] --gas auto --gas-adjustment 1.5 -y -- 1-42"
}

立即将助记符 保存到安全的位置（.env 文件、环境变量或秘密存储中）。如果您需要在本地 structsd 密钥库中存储密钥以供后续命令使用，请使用 structsd keys add [key-name] --recover 并输入助记符。

重要提示：如果脚本没有接收到 --mnemonic 参数，它将生成一个新的助记符。助记符仅在此输出中显示——请立即保存，否则将会丢失。

编码警告：切勿尝试手动实现公会注册的签名过程。公会 API 需要十六进制编码的压缩 secp256k1 公钥（66 个十六进制字符）和十六进制编码的 R||S 签名（128 个十六进制字符）——请使用正确的编码格式。手动尝试签名的代理几乎总是会失败，因为它们使用了错误的编码方式。

---

第 3 步：探索星球

创建玩家后，这始终是首先要执行的操作：

structsd tx structs planet-explore --from [key-name] --gas auto --gas-adjustment 1.5 -y -- [player-id]

新星球初始时有 5 个矿石单位和 4 个资源槽位（分别对应空间、空气、陆地和水域）。

---

第 4 步：检查指挥舰

新玩家创建时会收到一艘指挥舰（类型 1）。如果能量不足，该舰可能会处于离线状态。

structsd query structs fleet [fleet-id]

舰队 ID 与玩家索引相对应：玩家 1-18 对应舰队 9-18。请检查舰队中是否存在已有的结构体。

---

第 5 步：建造指挥舰（仅当玩家没有获得指挥舰时）

structsd tx structs struct-build-initiate --from [key-name] --gas auto --gas-adjustment 1.5 -y -- [player-id] 1 space 0

类型 1 的指挥舰必须属于某个舰队，且不能位于星球上。然后请在后台执行以下操作：

structsd tx structs struct-build-compute -D 3 --from [key-name] --gas auto --gas-adjustment 1.5 -y -- [struct-id]

建造难度设置为 200；等待约 17 分钟，直到难度降至 3——哈希计算会立即完成。构建完成后，结构体会自动激活——无需手动激活。

---

第 6 步：建造矿石提取器

舰队必须位于站点上，且指挥舰必须处于在线状态。

structsd tx structs struct-build-initiate --from [key-name] --gas auto --gas-adjustment 1.5 -y -- [player-id] 14 land 0

类型 14 的矿石提取器适用于陆地或水域。请在后台执行以下操作：

structsd tx structs struct-build-compute -D 3 --from [key-name] --gas auto --gas-adjustment 1.5 -y -- [struct-id]

建造难度设置为 700；等待约 57 分钟，直到难度降至 3。建造完成后，结构体会自动激活。

---

第 7 步：建造矿石精炼厂

structsd tx structs struct-build-initiate --from [key-name] --gas auto --gas-adjustment 1.5 -y -- [player-id] 15 land 1

类型 15 的矿石精炼厂适用于陆地或水域。建造难度同样设置为 700。建造完成后，结构体会自动激活。

---

第 8 步：验证

检查玩家、星球、舰队和所有结构体的状态，确保它们都处于在线状态。

---

工作量证明（Proof-of-Work）说明

struct-build-compute 命令是一个辅助工具，它会计算哈希值并自动提交 struct-build-complete 结果。您无需在计算完成后单独运行 struct-build-complete 命令。

自动激活：结构体会在建造完成后自动激活。您无需在建造完成后手动运行 struct-activate 命令。只有在结构体被关闭后，才需要使用 struct-activate 命令来重新激活它。

-D 标志（范围 1-64）用于指定计算应在难度降至该水平后才开始。建议使用 -D 3——当难度为 3 时，计算过程几乎瞬间完成，且不会浪费 CPU 资源。较低的难度值需要更长的等待时间，但计算资源消耗较少。

结构体类型	类型 ID	建造难度	等待难度降至 3 的时间
指挥舰	1	200	约 17 分钟
矿石提取器	14	700	约 57 分钟
矿石精炼厂	15	700	约 57 分钟
矿石储藏库	18	3,600	约 4.6 小时

能量消耗

建造操作每次消耗 8 单位能量。能量以每块结构体约 6 秒的速度累积。在连续进行相同结构的建造操作时，至少需要等待 48 秒（即 8 个时间单位）。在入门阶段，能量通常不是瓶颈。有关完整的能量消耗表，请参阅 knowledge/mechanics/building。

异步策略：立即启动所有计划的建造操作——这会启动计时器。在等待难度降低的过程中，您可以探索银河系、评估邻近区域或规划公会成员资格。您可以在后台终端启动计算任务，稍后再检查结果。有关更多信息，请参阅 awareness/async-operations。

注意：每次只能使用一个密钥进行一次计算操作。切勿同时运行两个使用相同签名密钥的计算任务。否则可能会导致任务同时达到目标难度并提交冲突的序列号，从而导致其中一个任务失败。请为同一玩家按顺序安排计算任务。

资源槽位编码

结构体类型具有 possibleAmbit 标志位：

资源槽位类型	标志值
空间	16
空气	8
陆地	4
水域	2

组合这些值可以得到所需的资源槽位数量：6 表示陆地和水域同时可用，30 表示所有资源槽位都可用。在选择资源槽位类型之前，请检查 possibleAmbit 的值。

命令参考

动作	CLI 命令
列出密钥	structsd keys list
创建密钥	structsd keys add [name]
恢复密钥	structsd keys add [name] --recover
显示地址	structsd keys show [name] -a
查找玩家	structsd query structs address [address]
查询玩家	structsd query structs player [id]
委托反应器	structsd tx structs reactor-infuse --from [key] --gas auto -y -- [player-addr] [reactor-addr] [amount]
创建玩家（公会注册）	node .cursor/skills/structs-onboarding/scripts/create-player.mjs --guild-id "..." --guild-api "..." --reactor-api "..." [--mnemonic "..."] [--username "..."]
探索星球	structsd tx structs planet-explore --from [key] --gas auto -y -- [player-id]
启动建造	structsd tx structs struct-build-initiate --from [key] --gas auto -y -- [player-id] [struct-type-id] [operating-ambit] [slot]
建造计算（包含自动完成和自动激活）	structsd tx structs struct-build-compute -D [difficulty] --from [key] --gas auto -y -- [struct-id]
重新激活结构体（仅当结构体被关闭时）	structsd tx structs struct-activate --from [key] --gas auto -y -- [struct-id]
查询星球	structsd query structs planet [id]
查询舰队	structsd query structs fleet [id]
查询结构体	structsd query structs struct [id]

建造顺序：指挥舰（类型 1，属于舰队）→ 矿石提取器（类型 14，位于星球上）→ 矿石精炼厂（类型 15，位于星球上）。常用的交易命令参数为：--from [key-name] --gas auto --gas-adjustment 1.5 -y。

验证

• structsd query structs address [address] — 检查玩家是否存在（ID 是否为 1-0）
• structsd query structs player [id] — 检查玩家是否在线
• structsd query structs planet [id] — 确认星球是否已被占领以及是否有矿石资源
• structsd query structs fleet [id] — 检查舰队是否位于站点上
• structsd query structs struct [id] — 确认结构体的状态是否为在线

错误处理

• 玩家 ID 为 1-0 — 表示玩家不存在。请按照路径 A 或路径 B 的步骤继续操作。
• create-player.mjs 失败 — 请检查 --guild-api 和 --reactor-api 的 URL 是否正确且可访问。确认公会是否支持程序化注册（services.guild_api 是否存在）。如果提供了 --mnemonic，请确认它是一个有效的 24 个单词的 BIP39 格式助记符。
• 公会 API 返回 HTML 或 404 错误 — 表示 URL 错误或您使用的方法不正确。注册端点 /auth/signup 仅支持 POST 请求。请始终使用 create-player.mjs，因为它会自动处理 POST 请求、签名和后续的轮询操作。
• 注册成功但玩家仍未出现 — 请使用相同的助记符重新运行脚本以继续轮询。可能是公会处理速度较慢。如果 120 秒后仍然失败，可能是公会的代理服务器出现故障。
• “资源不足” — 请检查玩家的 Alpha Matter 资源余额。
• “舰队未位于站点上” — 请等待舰队到达站点后再进行建造操作。
• “资源槽位无效” — 请确保使用 0-3 范围内的资源槽位；请检查星球上的结构体是否已被占用。
• “能量不足” — 可能需要增加能量来源或连接到容量更大的变电站。

参考资料

• knowledge/mechanics/building — 建造时间、难度和能量消耗
• knowledge/mechanics/planet — 星球属性、矿石资源和资源槽位
• knowledge/mechanics/fleet — 舰队移动规则和站点要求
• knowledge/entities/struct-types — 所有结构体类型的 ID 和属性
• knowledge/mechanics/power — 能量容量和在线状态
• awareness/async-operations — 背景计算任务和异步操作策略