hackathon-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Join the hackathon

加入黑客松

The

hackathon

CLI does the deterministic work and prints every command it runs on stderr. This skill only sequences the commands and reads their answers. It holds no credential: the participant's own Antasphere login and their own GitHub access do the work.

Pass

--json

to every

hackathon

command and read the answer on stdout. A refusal is

{ "ok": false, "error": { "code", "message" } }

with an exit code (the table at the end). Where a step says ASK, ask the participant and wait: never guess their email, their GitHub username or their folder.

hackathon

CLI 负责执行确定性的工作，并将运行的每条命令打印到 stderr。本 skill 只负责安排命令顺序并读取结果。它不保存任何凭据：实际工作由参与者自己的 Antasphere 登录和自己的 GitHub 访问权限完成。

给每条

hackathon

命令传入

--json

，并从 stdout 读取结果。请求被拒绝时，结果为

{ "ok": false, "error": { "code", "message" } }

，并带有退出码（见文末表格）。凡是步骤中标注 ASK 的地方，都要询问参与者并等待：绝不猜测其邮箱地址、GitHub 用户名或文件夹。

1. Node.js, then the CLI

1. Node.js，然后是 CLI

The CLI installs through npm, so Node.js comes first:

bash

node --version

No Node.js, or a version below 22: point to https://nodejs.org (version 22 or later) and stop until it is installed. Then:

bash

npm i -g @antasphere/hackathon@latest
hackathon --version

This skill needs version 0.7.1 or later (the one-command Antasphere sign-in and

decks link

). An older version prints a

login

help that talks about "an existing hck_ API key": then the event's CLI is not published yet. Say so and stop; an organizer has to publish it.

CLI 通过 npm 安装，因此需要先安装 Node.js：

bash

node --version

如果没有 Node.js，或版本低于 22：指向 https://nodejs.org（要求版本 22 或更高），并停止操作，直到安装完成。然后运行：

bash

npm i -g @antasphere/hackathon@latest
hackathon --version

本 skill 需要 0.7.1 或更高版本（该版本支持一步完成 Antasphere 登录和

decks link

）。如果旧版本输出的

login

帮助中提到“现有的 hck_ API key”，说明本次活动的 CLI 尚未发布。告知参与者并停止操作；需要由组织者发布。

2. The machine, before the sign-in

2. 登录前检查机器

Check the machine now, so nothing about it surprises the participant after the sign-in and the clone:

bash

hackathon doctor --json

It changes nothing. Read

checks

(

{ name, ok, detail, fix?, cls? }

). At this point only the machine checks must pass:

git

git identity

node

docker

docker daemon

docker compose

and

disk

(class

environment

). For each one with

ok

false, show its

fix

and walk the participant through it on their system (

platform

darwin

is macOS,

linux

win32

is Windows), the way the

hackathon-doctor

skill does (

git identity

: ask the name and email they want on their commits, then

git config --global user.name "<name>"

and

git config --global user.email "<email>"

; Docker Desktop not running is the usual one). Run the doctor again after each fix, until every machine check passes.

Every other check is expected to fail here, since nobody is signed in and nothing is cloned yet:

instance

credential

roster

repository

github access

directory

push

installer

app

manifest

. Ignore them now; the steps below settle them, and the final doctor run proves it. Ignore the exit code at this step too: it reflects those checks.

现在检查机器，避免登录和克隆之后才出现意外：

bash

hackathon doctor --json

该命令不会进行任何更改。读取

checks

（

{ name, ok, detail, fix?, cls? }

）。此时只有机器环境检查项必须通过：

git

、

git identity

、

node

、

docker

、

docker daemon

、

docker compose

和

disk

（类别为

environment

）。对于每个

ok

为 false 的检查项，展示其

fix

，并按照

hackathon-doctor

skill 的方式，引导参与者在自己的系统上完成修复（

platform

：

darwin

是 macOS，

linux

是 Linux，

win32

是 Windows）（

git identity

：询问他们希望用于提交的姓名和邮箱地址，然后运行

git config --global user.name "<name>"

和

git config --global user.email "<email>"

；最常见的问题是 Docker Desktop 未运行）。每次修复后重新运行 doctor，直到所有机器环境检查项都通过。

此时，其他所有检查项都预期会失败，因为尚未登录，也尚未克隆任何内容：

instance

、

credential

、

roster

、

repository

、

github access

、

directory

、

push

、

installer

、

app

、

manifest

。现在忽略这些检查项；后续步骤会解决它们，而最后一次 doctor 运行将证明一切正常。此时也要忽略退出码：它反映的正是这些检查项。

3. Sign in (once per machine)

3. 登录（每台机器一次）

bash

hackathon connect --json

Exit 0: signed in already, go to step 4 with this answer.
Exit 3 saying to run
```
hackathon login
```
: sign the participant in, in two commands. ASK their email: "Which email address have you been using with Antasphere? It is the one our emails, your invitation and the briefing call were sent to." Never guess it. Then say a code is on its way and run
```
hackathon login --email <email> --send-only
```
. When they paste the code, run
```
hackathon login --email <email> --code <code>
```
; it prints
```
Signed in as …
```
. A refused code has expired: send a new one with
```
--send-only
```
. (A CLI older than 0.8.1 has no
```
--send-only
```
: run
```
hackathon login --email <email>
```
and pass the code on its standard input.) Then run
```
hackathon connect --json
```
again.
"This account has no access to Antasphere Hackathon in any of its organizations" (exit 3): not fixable here. The organizers must add the participant's email to the event. Say so and stop.
```
not_on_roster
```
(exit 3): the email signed in is not the one on the roster. If the participant used another email, run
```
npx @antasphere/cli logout
```
(it forgets the stored Antasphere login), then sign in again, as above, with the email on the roster. Otherwise an organizer adds them; stop.
```
event_not_configured
```
(exit 3): the event is not open yet. Stop and say to try again later.

Only for an instance an organizer named explicitly (not the cloud):

hackathon login --api-url <url>

, then

hackathon connect --api-url <url> --json

eligibility.eligible

false in the answer (an organizer, a coach, a jury member, or a participant not on a team yet): there is no team app to set up. Say why, and stop.

bash

hackathon connect --json

退出码 0：已经登录，直接使用此结果进入第 4 步。
退出码 3，并提示运行
```
hackathon login
```
：使用两条命令让参与者登录。ASK 其邮箱地址：“你一直使用哪个邮箱地址登录 Antasphere？我们的邮件、你的邀请和说明电话会议都发送到了这个地址。”绝不猜测。然后告知验证码正在发送，并运行
```
hackathon login --email <email> --send-only
```
。参与者粘贴验证码后，运行
```
hackathon login --email <email> --code <code>
```
；它会输出
```
Signed in as …
```
。如果验证码被拒绝，说明验证码已过期：使用
```
--send-only
```
重新发送一个。（低于 0.8.1 的 CLI 没有
```
--send-only
```
：运行
```
hackathon login --email <email>
```
，并通过标准输入传入验证码。）然后再次运行
```
hackathon connect --json
```
。
出现“该账户在其任何组织中都没有 Antasphere Hackathon 访问权限”（退出码 3）：此处无法修复。组织者必须将参与者的邮箱添加到活动中。告知参与者并停止操作。
```
not_on_roster
```
（退出码 3）：登录所用的邮箱不是名册中的邮箱。如果参与者使用了另一个邮箱，运行
```
npx @antasphere/cli logout
```
（这会清除已保存的 Antasphere 登录信息），然后按照上述步骤使用名册中的邮箱重新登录。否则需要由组织者添加参与者；停止操作。
```
event_not_configured
```
（退出码 3）：活动尚未开放。停止操作，并告知参与者稍后再试。

仅当组织者明确指定了某个 instance（而非云端 instance）时，才运行：

bash

hackathon login --api-url <url>
hackathon connect --api-url <url> --json

如果结果中的

eligibility.eligible

为 false（参赛者是组织者、教练、评审团成员，或尚未加入团队的参与者），则没有需要设置的团队应用。说明原因并停止操作。

4. GitHub access

4. GitHub 访问权限

Read

repository

in the connect answer.

repository.state

pending

: the organizers have not created the team repositories yet. Stop and say to come back later. When it is

assigned

, read

repository.access

```
standing
```
is
```
no_username
```
: ASK the participant's GitHub username, then
```
hackathon connect --github <username> --json
```
and read
```
repository.access
```
again.
```
github_login_taken
```
means another person on the roster named it: ask again, or an organizer fixes it.
```
standing
```
is
```
invited
```
: ask the participant to open
```
repository.access.invitationUrl
```
, signed in to GitHub as
```
repository.access.github
```
, and accept. Wait for their word, then
```
hackathon connect --json
```
again.
```
standing
```
is
```
none
```
, or
```
member
```
with
```
canPush
```
false: show
```
repository.access.fix
```
. An organizer has to act. Stop.
```
canPush
```
true, or
```
standing
```
```
unknown
```
(GitHub did not answer): go on.

读取 connect 结果中的

repository

。如果

repository.state

为

pending

，说明组织者尚未创建团队仓库。停止操作，并告知参与者稍后再来。如果为

assigned

，则读取

repository.access

：

```
standing
```
为
```
no_username
```
：ASK 参与者的 GitHub 用户名，然后运行
```
hackathon connect --github <username> --json
```
，并再次读取
```
repository.access
```
。如果出现
```
github_login_taken
```
，说明名册中的另一人使用了该用户名：让参与者重新输入，或由组织者修复。
```
standing
```
为
```
invited
```
：让参与者打开
```
repository.access.invitationUrl
```
，确保其登录的 GitHub 账号是
```
repository.access.github
```
，然后接受邀请。等待参与者确认后，再次运行
```
hackathon connect --json
```
。
```
standing
```
为
```
none
```
，或者
```
member
```
的
```
canPush
```
为 false：展示
```
repository.access.fix
```
。需要由组织者处理。停止操作。
```
canPush
```
为 true，或者
```
standing
```
为
```
unknown
```
（GitHub 未返回结果）：继续下一步。

5. Clone and set up

5. 克隆和设置

ASK where the repository should go, and propose

defaultDirectory

from the connect answer (

~/Antasphere/hackathon/<team>

). With another folder, pass

--directory <path>

to every command below.

First clone without starting, because a team app usually needs its environment file first:

bash

hackathon setup --no-start --json            # or: --directory <path>

The CLI checks the GitHub access, Git, Docker, the daemon and Compose, clones the repository (or keeps an existing correct clone with its local changes) and writes the agent files. Exit 4 names what to install or start (Docker Desktop not running is the usual one): relay the sentence, let the participant do it, run the same command again. Exit 5: the folder is not empty and is not the clone; ASK another folder, never delete anything.

The environment file. If the clone has a

.env.example

and no

.env

: copy it to

.env

, fill every password or secret line that the app generates itself (for example

POSTGRES_PASSWORD

and

AUTH_SECRET

with

openssl rand -hex 16

), and

chmod 600 .env

. Leave every third-party API key empty and tell the participant which ones to paste into

.env

themselves (the event's page says where each key comes from). Never ask them to paste a key into the chat, and never print

.env

. An empty key does not stop the app; they can add it later and restart.

Then start:

bash

hackathon setup --json                       # same --directory if one was chosen

It builds and starts the app from the repository's

hackathon.json

and waits for the readiness probe.

app

null in the answer means the repository has no

hackathon.json

yet: nothing to start, which is fine. Exit 4 "not ready in time": run the

docker compose … logs

command it printed and read the error with the participant.

ASK 仓库应放置在哪个位置，并提出 connect 结果中的

defaultDirectory

（

~/Antasphere/hackathon/<team>

）作为建议。如果选择其他文件夹，则向下面的每条命令传入

--directory <path>

。

先只克隆而不启动，因为团队应用通常需要先准备环境文件：

bash

hackathon setup --no-start --json            # or: --directory <path>

CLI 会检查 GitHub 访问权限、Git、Docker、daemon 和 Compose，克隆仓库（或保留已有且正确、包含本地更改的 clone），并写入 agent 文件。退出码 4 会指出需要安装或启动的内容（最常见的是 Docker Desktop 未运行）：转述相应提示，让参与者亲自处理，然后重新运行同一条命令。退出码 5：文件夹非空，且不是指定的 clone；ASK 参与者改用其他文件夹，绝不删除任何内容。

环境文件。 如果 clone 中存在

.env.example

，但不存在

.env

：将其复制为

.env

，填写应用自行生成所需的每个 password 或 secret 项（例如使用

openssl rand -hex 16

生成

POSTGRES_PASSWORD

和

AUTH_SECRET

），并执行

chmod 600 .env

。所有第三方 API key 均保持为空，并告知参与者需要自行粘贴到

.env

中的具体项目（活动页面会说明每个 key 的来源）。绝不要让参与者把 key 粘贴到聊天中，也绝不要打印

.env

。空的 key 不会阻止应用运行；参与者之后可以补充并重启应用。

然后启动：

bash

hackathon setup --json                       # same --directory if one is chosen

该命令根据仓库中的

hackathon.json

构建并启动应用，同时等待就绪探测完成。如果结果中的

app

为 null，说明仓库中还没有

hackathon.json

，因此没有需要启动的内容，这是正常情况。退出码 4 且提示“未在规定时间内就绪”：运行它输出的

docker compose … logs

命令，并与参与者一起查看错误。

6. Open it

6. 打开应用

Open the local app (

app.url

) and the platform's dashboard (

dashboardUrl

) from the setup answer (

open <url>

on macOS,

xdg-open

on Linux,

start

on Windows). If the app asks to claim the instance on the first boot, the setup token is in its log:

docker compose -p hackathon-<team> logs app | grep 'claim the instance'

, run from the clone.

使用 setup 结果中的本地应用地址（

app.url

）和平台 dashboard 地址（

dashboardUrl

）打开页面（macOS 使用

open <url>

，Linux 使用

xdg-open

，Windows 使用

start

）。如果应用首次启动时要求认领 instance，setup token 会出现在日志中：在 clone 目录中运行

docker compose -p hackathon-<team> logs app | grep 'claim the instance'

。

7. The team's project description

7. 团队的项目描述

Right after the app runs, give the team its one line: each team is a project of the event, and its description is what the organizers, the coaches and the jury read about it. Take the project from

hackathon event status --json

(

me.project.id

), then follow section 5 of the

hackathon-doctor

skill ("The team's project description"): ASK in one question what they are building (the problem, for whom, the approach), propose a crisp description, and on their OK set it, or, as a participant is an editor of their project and only a manager may change it, open the

Project description

request for an organizer with the agreed text. If they do not know yet, say it can wait and the

hackathon-doctor

skill will ask again.

应用运行后，紧接着为团队提供一句话描述：每个团队都是本次活动中的一个项目，其描述是组织者、教练和评审团了解该项目时阅读的内容。从

hackathon event status --json

的结果中获取项目（

me.project.id

），然后遵循

hackathon-doctor

skill 第 5 节（“团队的项目描述”）：用一个问题询问他们正在构建什么（要解决什么问题、面向谁、采用什么方法），提出一段简洁明了的描述，并在他们确认后进行设置；或者，如果参与者只是其项目的 editor，而只有 manager 可以修改，则使用约定好的文本为组织者发起

Project description

请求。如果他们暂时还不知道，说明可以稍后处理，

hackathon-doctor

skill 会再次询问。

8. The clock and the pacing

8. 时间节点和推进节奏

Read

hackathon event status --json

and tell the participant the phase, the time left to the build end and to the freeze (the build end plus 15 minutes) in the event's time zone, and the rule: what counts is the last push to the designated branch (

submission.repository.designatedBranch

in the team's line) that the platform received before the freeze; there is nothing to click. From here, the pacing of the

hackathon-doctor

skill section 6 holds: push small and often (at least every 30 to 45 minutes) and confirm the receipt, warnings at 60, 30 and 15 minutes before the build end, only fixes in the grace, the

hackathon-deck-demo

skill before the end.

Then run the doctor a last time, from the clone, to prove the whole setup:

bash

hackathon doctor --directory <clone> --json

Every check must pass now. For any that fails, show its

fix

and settle it as the

hackathon-doctor

skill does, then run it again until it exits 0.

Finish with one short summary: who they are, their team, the clone's folder, the local URL, the dashboard URL, the deadlines, and the two next skills: the

hackathon-doctor

skill at the start of every working session (the clock, the setup, the push), the

hackathon-deck-demo

skill when the demo deck is due.

读取

hackathon event status --json

，并告知参与者当前阶段、距离构建结束和冻结（构建结束后 15 分钟）还剩多长时间，以及活动所在时区。规则是：以平台在冻结前收到的、对指定分支（团队信息中的

submission.repository.designatedBranch

）的最后一次 push 为准；无需点击任何按钮。从现在起，遵循

hackathon-doctor

skill 第 6 节的节奏：小步、频繁地 push（至少每 30 至 45 分钟一次），并确认平台已经收到；在构建结束前 60、30 和 15 分钟时发出提醒；宽限期内只进行修复；在结束前使用

hackathon-deck-demo

skill。

然后从 clone 目录最后运行一次 doctor，以证明整个设置已成功：

bash

hackathon doctor --directory <clone> --json

现在每个检查项都必须通过。对于任何失败的检查项，展示其

fix

，并按照

hackathon-doctor

skill 的方式解决，然后重新运行，直到退出码为 0。

最后给出一段简短总结：参与者是谁、所属团队、clone 的文件夹、本地 URL、dashboard URL、截止时间，以及接下来要使用的两个 skill：每次开始工作时使用

hackathon-doctor

skill（查看时间节点、检查设置、执行 push），演示 deck 到期时使用

hackathon-deck-demo

skill。

Exit codes

退出码

0: done. Read the JSON.
2: a flag is missing or wrong. Read the usage the CLI printed.
3: access: a sign-in to do, not on the roster, no event yet, no team or repository yet, no push access on GitHub, or GitHub refused. The message says who to ask or what to run. Never retry in a loop: the state has to change first.
4: the machine: Git, its identity, Node.js, Docker, the daemon or Compose; the disk; the port taken; the app not ready. The message says what to install, start or free.
5: the folder is not empty and is not the assigned clone.

0：已完成。读取 JSON。
2：缺少参数或参数错误。读取 CLI 输出的用法说明。
3：访问权限问题：需要登录、不在名册中、活动尚未开放、尚无团队或仓库、GitHub 上没有 push 权限，或者 GitHub 拒绝请求。错误消息会说明应联系谁或应运行什么命令。绝不能循环重试：必须先让状态发生变化。
4：机器环境问题：Git、Git identity、Node.js、Docker、daemon 或 Compose、磁盘空间、端口被占用、应用未就绪。错误消息会说明需要安装、启动或释放什么。
5：文件夹非空，且不是指定的 clone。

Never

绝不执行

Never pass a credential to the CLI: no GitHub token, no API key, no hub secret. It needs none.
Never run a command that needs the participant's password (
```
sudo
```
) or their GitHub sign-in (
```
gh auth login
```
) for them: show it and let them run it.
Never edit the clone's remote URL, never
```
git reset --hard
```
, never delete the clone to make a setup pass: run
```
hackathon setup
```
again, it resumes.
Never run a real
```
git push
```
to test access:
```
hackathon doctor
```
proves it with a dry run.

绝不向 CLI 传入任何凭据：不要传 GitHub token、API key 或 hub secret。它不需要这些凭据。
绝不要代替参与者运行需要其 password（
```
sudo
```
）或 GitHub 登录（
```
gh auth login
```
）的命令：展示命令并让参与者亲自运行。
绝不修改 clone 的 remote URL，绝不执行
```
git reset --hard
```
，也绝不删除 clone 来让设置通过：重新运行
```
hackathon setup
```
即可恢复。
绝不要运行真实的
```
git push
```
来测试访问权限：
```
hackathon doctor
```
会通过 dry run 进行验证。