hackathon-doctor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Check the clock, the setup, the push and the pitch line

检查时钟、设置、push 和项目简介

Run this at the start of every working session in the team's clone, before any other work: the clock comes first, because a team that loses track of it loses its submission. The

hackathon

CLI does the checks; this skill runs it, reads the

--json

answers and walks the participant through the fixes. Run from the team's clone. If the participant never joined (no

hackathon

command, or

hackathon connect

says to sign in), use the

hackathon-setup

skill instead.

在团队 clone 中、开始任何其他工作之前，于每次协作时段开始时运行此流程：先看时钟，因为团队如果失去对截止时间的掌握，就会失去提交机会。

hackathon

CLI 负责执行检查；此 skill 运行该 CLI、读取

--json

返回结果，并引导参与者完成修复。必须从团队的 clone 目录运行。如果参与者从未加入（没有

hackathon

命令，或

hackathon connect

提示登录），则改用

hackathon-setup

skill。

1. The clock, first

1. 首先检查时钟

bash

hackathon event status --json

Read, from the answer:

phase

(

scheduled

building

grace

closed

serverTime

event.buildEndsAt

event.freezeAt

(always the build end plus 15 minutes),

event.timezone

event.lastReschedule

(the organizers moved the build end, with their reason),

me.project

(the team:

id

name

) and, in the team's line of

projects[]

submission.repository.designatedBranch

and

submission.lastReceipt

(

sha

receivedAt

late

Compute every time left from

serverTime

, never from this machine's clock. Then tell the participant, in two or three lines, in the event's time zone:

the phase, and the time left to the build end and to the freeze (for example: "Building. 3 h 12 min to the build end (17:00), 3 h 27 min to the freeze (17:15).");
the rule, once per session: what counts is the last push to
```
<designatedBranch>
```
that the platform received before the freeze. There is nothing to click and nothing to submit; a commit on this machine is not a submission;
a reschedule, if
```
event.lastReschedule
```
is set, with its reason.

If you are not sure the participant knows a deadline (a new session, a reschedule, a teammate who joined late), ASK: "Do you know the build ends at 17:00 and the freeze is at 17:15?" Wait for the answer before going on.

scheduled

: say when the build starts; the setup can be checked now.

closed

: say the submission is frozen (

submission.frozen.sha

), that nothing pushed now counts, and skip the pacing.

bash

hackathon event status --json

从返回结果中读取：

phase

（

scheduled

、

building

、

grace

、

closed

）、

serverTime

、

event.buildEndsAt

、

event.freezeAt

（始终为开发结束时间加 15 分钟）、

event.timezone

、

event.lastReschedule

（组织者调整了开发结束时间及其原因）、

me.project

（团队：

id

、

name

），以及团队在

projects[]

中对应的条目：

submission.repository.designatedBranch

和

submission.lastReceipt

（

sha

、

receivedAt

、

late

）。

所有剩余时间都必须根据

serverTime

计算，绝不能使用本机时钟。然后用两三行告诉参与者以下信息，并使用赛事所在时区：

当前阶段、距离开发结束和冻结还有多久（例如：“开发中。距离开发结束还有 3 小时 12 分钟（17:00），距离冻结还有 3 小时 27 分钟（17:15）。”）；
每次协作仅说明一次的规则：有效提交取决于平台在冻结前收到的最后一次发往
```
<designatedBranch>
```
的 push。无需点击任何按钮，也无需另行提交；本机上的 commit 不等于提交；
如果设置了
```
event.lastReschedule
```
，说明调整情况及其原因。

如果不确定参与者是否知道截止时间（新手协作、赛程调整，或有队友较晚加入），询问：“你知道开发会在 17:00 结束，并会在 17:15 冻结吗？”等待回答后再继续。

scheduled

：说明开发何时开始；现在可以检查设置。

closed

：说明提交已冻结（

submission.frozen.sha

），现在 push 的内容都不计入，并跳过节奏安排。

2. The doctor

2. 诊断环境

bash

hackathon doctor --directory . --json      # from the clone; without --directory it checks the default folder

It changes nothing. The answer is

{ ok, platform, checks: [{ name, ok, detail, fix?, cls? }] }

: Git and its identity, Node.js 22, Docker, the daemon, Compose, the disk, the instance, the credential, the roster, the repository, the GitHub access, the clone, a dry-run push, the installer, the app and

hackathon.json

. For every check with

ok

false, show its

fix

and offer to walk the participant through it on their system (

platform

darwin

is macOS,

linux

win32

is Windows). Run the doctor again after each fix, until it exits 0.

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>"

```
push
```
refused: GitHub saw another account than the one on the roster. The participant accepts the invitation with the roster's account, or signs in to GitHub with it (
```
gh auth login
```
, which they run themselves).
```
credential
```
or
```
roster
```
(class
```
access
```
): use the
```
hackathon-setup
```
skill; it handles the sign-in.

Never run

sudo

gh auth login

for them: show the command and let them run it.

bash

hackathon doctor --directory . --json      # from the clone; without --directory it checks the default folder

它不会做任何更改。返回结果为

{ ok, platform, checks: [{ name, ok, detail, fix?, cls? }] }

，涵盖 Git 及其身份信息、Node.js 22、Docker、daemon、Compose、磁盘、实例、凭据、名单、仓库、GitHub 访问权限、clone、push 试运行、安装器、应用和

hackathon.json

。对于每项

ok

为 false 的检查，显示其

fix

，并主动提出可以在参与者的系统上逐步指导其修复（

platform

：

darwin

是 macOS，

linux

，

win32

是 Windows）。每次修复后重新运行 doctor，直到它以退出码 0 结束。

git identity

：询问参与者希望用于 commit 的名字和邮箱，然后运行

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

和

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

。

```
push
```
被拒绝：GitHub 看到的账号与名单中的账号不同。参与者需要使用名单中的账号接受邀请，或登录 GitHub（
```
gh auth login
```
，由他们自行运行）。
```
credential
```
或
```
roster
```
（类别
```
access
```
）：使用
```
hackathon-setup
```
skill，由它处理登录。

绝不代参与者运行

sudo

或

gh auth login

：显示命令，让参与者自行运行。

3. The app

3. 应用

If the

app

check failed because nothing answers on the port:

bash

hackathon setup --directory . --json

It keeps the clone and its local changes, builds the image, starts the app and waits for its readiness probe. Exit 4 "not ready in time": run the

docker compose … logs

command it printed and read the error with the participant (a missing key in

.env

is the usual one; they paste keys there themselves, never in the chat).

如果

app

检查失败，原因是端口上没有任何响应：

bash

hackathon setup --directory . --json

它会保留 clone 及其本地更改、构建镜像、启动应用并等待就绪探针。退出码 4（

not ready in time

）：运行它输出的

docker compose … logs

命令，并与参与者一起分析错误（

.env

中缺少 key 是常见原因；参与者自行将 key 粘贴进去，绝不能粘贴到聊天中）。

4. Did the platform receive the last push

4. 平台是否收到了最后一次 push

bash

hackathon submissions list --json
git rev-parse HEAD
git status --short --branch

A participant's answer has one line in

projects[]

: their team's. Compare its

submission.lastReceipt.sha

with the local

HEAD

the same: say it plainly ("The platform has your last commit, received at 14:32.");
different, or
```
lastReceipt
```
null: the platform does not have this machine's work. If the local commits are meant to count, push to the designated branch now (the pacing below), then check again;
```
late
```
true: that push arrived at or after the freeze, is recorded, and never counts.

GitHub delivers a push to the platform in a few seconds, sometimes more. If the revision is not there after a minute,

hackathon submissions show <me.project.id> --json

lists the receipts, refused ones included; if it still does not arrive, open a request for an organizer (

hackathon requests open

bash

hackathon submissions list --json
git rev-parse HEAD
git status --short --branch

参与者收到的结果中，

projects[]

里有一行对应其团队。将

submission.lastReceipt.sha

与本地

HEAD

比较：

两者相同：直接说明结果（“平台已收到你的最后一次 commit，接收时间为 14:32。”）；
两者不同，或
```
lastReceipt
```
为 null：平台尚未收到本机上的工作。如果本地 commits 应计入提交，请立即 push 到指定分支（按照下方的节奏安排），然后再次检查；
```
late
```
为 true：该 push 在冻结时或之后到达，已被记录，但永远不会计入提交。

GitHub 通常会在几秒内将 push 送达平台，有时可能更久。如果一分钟后目标 revision 仍未出现，运行

hackathon submissions show <me.project.id> --json

列出所有接收记录，包括被拒绝的记录；如果仍未到达，就向组织者发起请求（

hackathon requests open

）。

5. The team's project description

5. 团队的项目描述

Each team is a project of the event, and its description is the one line the organizers, the coaches and the jury read about the team. Read it:

bash

hackathon projects get <me.project.id> --json

Read

description

and

myRole

. The description needs work when it is empty, or stale: it no longer matches what the repository and this session show the team is building (the README, the recent commits, what the participant says now), or the participant says the idea changed.

ASK, in one question: "In one or two sentences, what are you building: the problem, for whom, and your approach?" Skip the question when they have just told you.
Propose a crisp description from their answer: one or two sentences, under 300 characters, the problem, who it is for and how, in their words, no marketing. For example, invented: "Cooks waste leftovers because recipes start from a shopping list. Fridgeful starts from a photo of the fridge and proposes three dinners that use what is already there."
Set it only on their OK.

Who sets it.

hackathon projects update

needs the manager role on the project, and a participant is placed on their team's project as an editor, so the command is normally refused for them. So:

myRole

manager

: run

hackathon projects update <me.project.id> --description "<the agreed text>" --json

, then

hackathon projects get <me.project.id> --json

to read it back. A refusal with

insufficient_project_role

means the role changed: go to the next case.

otherwise (the usual case): an organizer sets it. First
```
hackathon requests list --status open --json
```
: if the team already has an open request titled
```
Project description
```
, post the new text in its thread instead of opening another one (
```
hackathon requests show <id> --json
```
names the thread's channel;
```
hackathon chats post <channelId> --file <file>
```
). Else open one:
bash
```
hackathon requests open --title "Project description" \
  --body "Please set our team's description to: <the agreed text>"
```
Tell the participant an organizer sets it, and read it again at the next check.

Keep it current: whenever the participant says the idea, the audience or the approach changed, run this section again.

每个团队都是赛事中的一个项目，其描述是组织者、教练和评审了解团队时看到的那一行。读取它：

bash

hackathon projects get <me.project.id> --json

读取

description

和

myRole

。当描述为空或已经过期时，需要更新：它与仓库和本次协作所体现的团队正在开发的内容不再一致（README、最近的 commits、参与者当前的说明），或者参与者说想法变了。

用一个问题询问：“用一两句话说明你正在构建什么：要解决的问题是什么，面向谁，以及采用什么方法？”如果参与者刚刚已经说明，则跳过此问题。
根据参与者的回答提出一版简洁描述：一到两句话、300 个字符以内，包含问题、目标用户以及方法，使用参与者自己的话，不做营销。例如，假设为：“厨师会浪费剩菜，因为菜谱总是从购物清单开始。Fridgeful 则从一张冰箱照片开始，提出三道利用现有食材的晚餐。”
只有在参与者确认后才进行设置。

由谁设置。

hackathon projects update

需要项目中的 manager 角色，而参与者通常被放在团队项目中作为 editor，所以该命令通常会因权限不足而被拒绝。因此：

myRole

为

manager

：运行

hackathon projects update <me.project.id> --description "<the agreed text>" --json

，然后运行

hackathon projects get <me.project.id> --json

读回内容。如果因

insufficient_project_role

被拒绝，说明角色已经发生变化：转到下一种情况。

其他情况（通常如此）：由组织者设置。首先运行
```
hackathon requests list --status open --json
```
：如果团队已经有一个标题为
```
Project description
```
的未关闭请求，就在该请求的讨论串中发布新文本，不要再创建另一个请求（
```
hackathon requests show <id> --json
```
会给出讨论串的 channel ID；
```
hackathon chats post <channelId> --file <file>
```
）。否则创建一个新请求：
bash
```
hackathon requests open --title "Project description" \
  --body "Please set our team's description to: <the agreed text>"
```
告诉参与者由组织者设置，并在下次检查时重新读取。

持续保持描述为最新状态：每当参与者说想法、目标受众或实现方法发生了变化，就重新执行本节。

6. The pacing for the rest of the session

6. 本次协作剩余时段的节奏安排

This section holds for the whole session, not only while this skill runs.

Push small and often to
```
<designatedBranch>
```
: after every piece that works, and at least every 30 to 45 minutes. Ask once per session: "May I commit and push to
```
<designatedBranch>
```
after each working step?" and push only with that OK; otherwise remind the participant to push at the same pace. Never force-push, never rewrite history.
Confirm the receipt after each push:
```
hackathon submissions list --json
```
,
```
lastReceipt.sha
```
against
```
git rev-parse HEAD
```
(section 4). A push the platform did not receive is not a submission.
Read the clock again (
```
hackathon event status --json
```
) before starting any task that takes more than a few minutes, and after each push. Warn the participant once as each mark passes:
- 60 minutes before the build end: say the time left; scope down to what can work by then; remind that the demo deck is due: the
```
hackathon-deck-demo
```
  skill;
- 30 minutes: no new feature; make what exists work, push, confirm the receipt; the demo deck should be under way;
- 15 minutes: final push of the working state, confirm the receipt, finish the demo deck.
The grace (
```
phase
```
```
grace
```
, between the build end and the freeze): only fixes, no new work. Push each fix at once and confirm its receipt. Do not push in the last minute: a push GitHub accepts just before the freeze but that reaches the platform after it does not count.
Before the end, if the demo deck is not linked yet (
```
hackathon decks show --json
```
), run the
```
hackathon-deck-demo
```
skill.
If the organizers moved the build end (
```
event.lastReschedule
```
), say the new deadlines and their reason.

本节在整个协作时段内都有效，而不仅在此 skill 运行期间。

频繁进行小型 push：发往
```
<designatedBranch>
```
。每完成一项可用的工作后都应 push，并且至少每 30 到 45 分钟 push 一次。每次协作仅询问一次：“我可以在每个工作步骤完成后，向
```
<designatedBranch>
```
commit 并 push 吗？”只有在获得同意后才能 push；否则提醒参与者按照相同节奏 push。绝不 force-push，绝不改写历史。
每次 push 后确认接收情况：运行
```
hackathon submissions list --json
```
，将
```
lastReceipt.sha
```
与
```
git rev-parse HEAD
```
比较（参见第 4 节）。平台没有收到的 push 不算提交。
再次读取时钟（
```
hackathon event status --json
```
）：在开始任何需要超过几分钟的任务前，以及每次 push 后读取。每到一个时间节点时提醒参与者一次：
- 开发结束前 60 分钟：说明剩余时间；缩减范围，确保届时已有可运行的功能；提醒演示文稿即将到期，需要使用
```
hackathon-deck-demo
```
  skill；
- 30 分钟：不再添加新功能；让现有功能可正常运行，push 并确认平台已接收；演示文稿应已开始制作；
- 15 分钟：对当前可用状态执行最后一次 push，确认平台已接收，并完成演示文稿。
宽限期（
```
phase
```
为
```
grace
```
，即开发结束至冻结之间）：只修复问题，不开展新工作。每完成一项修复就立即 push，并确认平台已接收。不要在最后一分钟 push：GitHub 在冻结前刚接受、但平台在冻结后才收到的 push 不计入提交。
结束之前，如果尚未关联演示文稿（
```
hackathon decks show --json
```
），运行
```
hackathon-deck-demo
```
skill。
如果组织者调整了开发结束时间（
```
event.lastReschedule
```
），说明新的截止时间及其原因。

Exit codes

退出码

0 done; 1 an API refusal outside the journey, such as

insufficient_project_role

projects update

(read the

error.code

); 2 a flag is wrong; 3 access (a sign-in to do, not on the roster, no repository yet, GitHub refused): the state has to change before a retry, say who to ask; 4 the machine: install, start or free what the message names; 5 the folder is not the assigned clone.

0：完成；1：正常流程之外的 API 拒绝，例如

projects update

insufficient_project_role

（读取

error.code

）；2：参数错误；3：访问问题（需要登录、不在名单中、尚无仓库、GitHub 拒绝）：必须先改变相应状态再重试，并说明应向谁求助；4：机器问题：安装、启动或释放错误消息所指定的资源；5：当前文件夹不是指定的 clone。

Never

绝不

Never pass a credential to any command, never edit the remote URL, never

git reset --hard

or delete files to make a check pass, never run a real

git push

to test access (the doctor's dry run does that), never push without the participant's OK, never force-push.

绝不把任何凭据传给命令，绝不修改远程 URL，绝不运行

git reset --hard

或删除文件来让检查通过，绝不运行真实的

git push

来测试访问权限（doctor 的 dry run 会执行该测试），未经参与者同意绝不 push，绝不 force-push。