// 将新玩家引入游戏系统（Structs）。负责处理密钥的创建/恢复、玩家信息的生成（通过“reactor-infuse”或“guildsignup”功能）、星球探索以及基础基础设施的搭建。适用于以下场景：初始化游戏环境、创建新玩家、占领第一个星球或搭建基础设施。搭建所需时间因设备类型而异——使用“Command Ship”大约需要17分钟，而使用“Ore Extractor”或“Refinery”则需要约57分钟。
这是AI代理在“Structs”模式中开始游戏所需掌握的基础技能。内容包括选择公会、创建账户、搭建首个采矿基础设施以及提炼“Alpha Matter”资源。请优先学习此技能，因为它与其他所有操作都密切相关。该技能对CPU资源的消耗较低（设置 `-D 1` 即可）。从零开始完成整个采矿流程大约需要3到4小时。
从 YouTube 下载指定的视频；根据指定的开始和结束时间提取视频片段，并将它们保存到您桌面上的文件夹中。
将 YouTube 视频下载到 `~/Downloads` 目录中。适用于用户希望将 YouTube 视频下载到自己电脑上的情况。
在 **Structs** 中，该模块负责处理权限管理、地址分配以及玩家之间的协调工作。适用于以下场景：授予或撤销对象的权限、注册新地址、管理多地址账户、将权限委托给其他玩家，以及设置基于地址的访问控制规则。
通过NATS WebSocket连接到GRASS实时事件系统。当您需要实时游戏更新、希望在事件发生时立即做出响应、需要监控团队行动或攻击情况、观察玩家创建情况、追踪舰队移动轨迹，或者构建基于事件的工具时，可以使用该功能。GRASS是获取银河系内最新动态的最快速途径。
从源代码安装 `structsd` 二进制文件。涵盖了 Go 语言、`Ignite CLI` 的使用，以及为 Linux 和 macOS 系统构建 `structsd` 的过程。适用于以下情况：`structsd` 未被找到时；在设置新机器时；或者当代理需要安装或更新 `Structs` 链接二进制文件时。
| 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 命令时，务必始终包含 --。
如果您使用 路径 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。
structsd query structs address [your-address]
如果结果显示的玩家 ID 不是 1-0，则表示已有玩家存在。请跳到 第 3 步：探索星球（如果星球已被探索，则执行后续步骤）。
如果玩家 ID 是 1-0，则表示没有玩家存在——请继续执行第 2 步。
根据代理是否拥有 $alpha（原生代币）有两种不同的路径：
如果地址中已经包含 $alpha 代币，可以委托给一个反应器（验证器）来创建玩家记录。
structsd tx structs reactor-infuse --from [key-name] --gas auto --gas-adjustment 1.5 -y -- [your-address] [reactor-address] [amount]structsd query structs address [your-address] — 每 10 秒重复一次，直到玩家 ID 不再是 1-0。加入一个支持程序化注册的公会。捆绑的 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"
脚本将：
--mnemonic "..." 来恢复现有的助记符）注意：当玩家加入公会后，他们的默认等级为 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 个十六进制字符）——请使用正确的编码格式。手动尝试签名的代理几乎总是会失败，因为它们使用了错误的编码方式。
创建玩家后，这始终是首先要执行的操作：
structsd tx structs planet-explore --from [key-name] --gas auto --gas-adjustment 1.5 -y -- [player-id]
新星球初始时有 5 个矿石单位和 4 个资源槽位（分别对应空间、空气、陆地和水域）。
新玩家创建时会收到一艘指挥舰（类型 1）。如果能量不足，该舰可能会处于离线状态。
structsd query structs fleet [fleet-id]
舰队 ID 与玩家索引相对应：玩家 1-18 对应舰队 9-18。请检查舰队中是否存在已有的结构体。
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——哈希计算会立即完成。构建完成后，结构体会自动激活——无需手动激活。
舰队必须位于站点上，且指挥舰必须处于在线状态。
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。建造完成后，结构体会自动激活。
structsd tx structs struct-build-initiate --from [key-name] --gas auto --gas-adjustment 1.5 -y -- [player-id] 15 land 1
类型 15 的矿石精炼厂适用于陆地或水域。建造难度同样设置为 700。建造完成后，结构体会自动激活。
检查玩家、星球、舰队和所有结构体的状态，确保它们都处于在线状态。
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] — 确认结构体的状态是否为在线1-0 — 表示玩家不存在。请按照路径 A 或路径 B 的步骤继续操作。create-player.mjs 失败 — 请检查 --guild-api 和 --reactor-api 的 URL 是否正确且可访问。确认公会是否支持程序化注册（services.guild_api 是否存在）。如果提供了 --mnemonic，请确认它是一个有效的 24 个单词的 BIP39 格式助记符。/auth/signup 仅支持 POST 请求。请始终使用 create-player.mjs，因为它会自动处理 POST 请求、签名和后续的轮询操作。