hackathon-deck-demo

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

The demo deck: played, shot, hosted, linked

演示文稿：操作、截图、托管、链接

The jury reads it alone, after the pitches. The app runs on the team's own machine and is not online, so the jury never opens it: the deck shows it working instead. It is a page of one to three episodes, each a short story of one thing the product does (two to six steps), every step one action with the screen's exact labels, what the screen showed, and a screenshot Playwright took of the running app. The jury opens a screenshot large and follows an episode step by step. A feature the app does not have is never in it.

Work from the root of the team's clone; everything goes into

decks/demo/

. The scripts ship with this skill, in the

scripts/

folder beside this SKILL.md (call that folder

$SKILL_DIR/scripts

; under Claude Code it is also

${CLAUDE_PLUGIN_ROOT}/skills/hackathon-deck-demo/scripts

, and after

npx skills add

it is

~/.agents/skills/hackathon-deck-demo/scripts

play.mjs

(the Playwright play, copied into the clone and completed for this app),

fill.mjs

(fills the organizer's template),

check.mjs

(checks the page) and

guide.example.json

(the content filled for an invented tool).

路演结束后，评审会独自阅读它。应用运行在团队自己的机器上，未部署到线上，因此评审绝不会打开应用；演示文稿改为展示其运行情况。它是一个包含 1 至 3 个 演示片段的页面，每个片段以 2 至 6 个步骤简短讲述产品完成的一项事情；每个步骤只包含一个操作，使用屏幕上的准确标签，并说明操作后屏幕显示的内容，同时附上 Playwright 对运行中的应用拍摄的截图。评审可以打开并放大截图，逐步跟随一个演示片段。应用中不存在的功能绝不写入其中。

从团队 clone 的根目录开始工作；所有内容都放入

decks/demo/

。这些脚本随本 skill 一同提供，位于本 SKILL.md 旁边的

scripts/

文件夹（将该文件夹称为

$SKILL_DIR/scripts

；在 Claude Code 下，它也位于

${CLAUDE_PLUGIN_ROOT}/skills/hackathon-deck-demo/scripts

，执行

npx skills add

后则位于

~/.agents/skills/hackathon-deck-demo/scripts

）：

play.mjs

（Playwright 操作脚本，复制到 clone 后针对当前应用补全）、

fill.mjs

（填充主办方模板）、

check.mjs

（检查页面）以及

guide.example.json

（为一个虚构工具填充的内容示例）。

1. The app is running

1. 应用正在运行

bash

hackathon doctor --directory . --json

The

app

check must pass. If it does not, run the

hackathon-doctor

skill first. The app's local URL is

http://127.0.0.1:<port>

, the port being

app.port

hackathon.json

(or the one

hackathon setup

printed when it was started with

--port

bash

hackathon doctor --directory . --json

app

检查必须通过。如果未通过，先运行

hackathon-doctor

skill。应用的本地 URL 是

http://127.0.0.1:<port>

，其中端口为

hackathon.json

中的

app.port

（如果使用

--port

启动，则为

hackathon setup

输出的端口）。

2. The episodes

2. 演示片段

Read the repository (the README, the routes, the dashboard's pages) and open the app, then ASK the participant, in one message, to confirm, each proposed from what you read: the one sentence of what the tool does and for whom; one to three episodes, each a title, a two-sentence situation (who the reader is in it, what is already true) and its two to six steps; what was set up before (the account, the data, what is invented); what the agent does on the computer and what a person still decides; and what is not finished yet.

Write

decks/demo/guide.json

in the shape of

guide.example.json

lang

(

en

fr

occasion

(from

hackathon event status --json

: its name and its start day, as

<name> · <day month year>

team

members

title

(the product),

subtitle

(its one sentence),

forWhom

app.url

intro

worlds

(

setup

agent

name

text

notFinished

episodes[]

(

title

who

minutes

situation

steps[]

closing

(

title

text

). A step is

do

(one action, the screen's exact labels between « »),

see

(what the screen shows after it),

shot

(

screens/NN.jpg

, NN its number counted straight through the episodes: episode 1's steps are 01, 02…, episode 2's carry on), and for the play

path

(a page of the app to open) and

expect

(texts that must be on the screen). A step whose picture would need a real account, a real payment or a real message carries

noshot

(the reason, a few words) instead of

shot

. The team's own words, no marketing.

读取仓库（README、路由、dashboard 的各页面）并打开应用，然后用一条消息 ASK 参赛者，让他确认以下内容；每项提案都应基于你读到的信息：用一句话说明工具的用途及目标用户；1 至 3 个演示片段，每个包含标题、一个两句的情境说明（读者在情境中的身份、已经成立的条件）及其 2 至 6 个步骤；此前设置了什么（账户、数据、哪些内容是虚构的）；Agent 在计算机上执行什么，以及人仍需决定什么；以及哪些部分尚未完成。

按照

guide.example.json

的结构写入

decks/demo/guide.json

：

lang

（

en

或

fr

）、

occasion

（取自

hackathon event status --json

：活动名称和开始日期，格式为

<name> · <day month year>

）、

team

、

members

、

title

（产品名称）、

subtitle

（一句话简介）、

forWhom

、

app.url

、

intro

、

worlds

（

setup

、

agent

各含

name

、

text

）、

notFinished

、

episodes[]

（

title

、

who

、

minutes

、

situation

、

steps[]

）、

closing

（

title

、

text

）。一个步骤包含

do

（一个操作，屏幕上的准确标签置于 « » 之间）、

see

（操作后屏幕显示的内容）、

shot

（

screens/NN.jpg

，NN 是跨各演示片段连续编号的步骤序号：演示片段 1 的步骤为 01、02……，演示片段 2 接着编号），play 中还需要

path

（要打开的应用页面）和

expect

（屏幕上必须出现的文本）。如果某一步的图片需要真实账户、真实付款或发送真实消息，则使用

noshot

（用几个词说明原因）代替

shot

。使用团队自己的措辞，不要加入营销内容。

3. Play it and take the screenshots

3. 运行并截取截图

Playwright, once per machine (skip when the clone already has

playwright

in its

node_modules

bash

npm i --prefix ~/.cache/antasphere-hackathon/playwright playwright@1
npx --prefix ~/.cache/antasphere-hackathon/playwright playwright install chromium

Copy the play into the clone and write its gestures:

bash

cp "$SKILL_DIR/scripts/play.mjs" decks/demo/play.mjs

At the bottom of

decks/demo/play.mjs

, write one gesture per step number (

async 3({ page, open, expect })

) that brings the screen to what the step's

see

says, with Playwright's own locators (

getByRole

getByLabel

getByText

) read from the app's code. A step with only a

path

needs no gesture. A gesture never deletes anything, never sends a real message or a real payment, and never types a real credential: a demo shows, it does not spend.

If the app needs a sign-in, the participant signs in once by hand:

bash

node decks/demo/play.mjs --login     # a browser opens: sign in, then close the window

The session is kept in

~/.cache/antasphere-hackathon/

, outside the repository. Then play:

bash

node decks/demo/play.mjs             # --headed to watch it, --from 3 --until 5 to replay a range

It writes

decks/demo/screens/NN.jpg

and

decks/demo/results.json

. Exit 1 means a step failed: read

results.json

(

missing

texts,

note

), open the screenshot, fix the gesture or the step's

see

, and replay that range. Open every screenshot before going on: a

see

that is not true of its picture is rewritten, never kept.

Playwright 每台机器只需安装一次（如果 clone 的

node_modules

中已经存在

playwright

，则跳过）：

bash

npm i --prefix ~/.cache/antasphere-hackathon/playwright playwright@1
npx --prefix ~/.cache/antasphere-hackathon/playwright playwright install chromium

将 play 脚本复制到 clone 中，并编写其交互动作：

bash

cp "$SKILL_DIR/scripts/play.mjs" decks/demo/play.mjs

在

decks/demo/play.mjs

底部，按步骤编号编写一个交互动作（

async 3({ page, open, expect })

），使用依据应用代码选取的 Playwright locator（

getByRole

、

getByLabel

、

getByText

），让屏幕达到该步骤

see

所描述的状态。只有

path

的步骤不需要交互动作。交互动作绝不删除任何内容，绝不发送真实消息或进行真实付款，也绝不输入真实凭据：演示只做展示，不进行实际消费。

如果应用需要登录，参赛者手动登录一次：

bash

node decks/demo/play.mjs --login     # a browser opens: sign in, then close the window

会话保存在仓库外的

~/.cache/antasphere-hackathon/

中。然后运行：

bash

node decks/demo/play.mjs             # --headed to watch it, --from 3 --until 5 to replay a range

它会写入

decks/demo/screens/NN.jpg

和

decks/demo/results.json

。退出码 1 表示某个步骤失败：读取

results.json

（

missing

文本、

note

），打开截图，修正交互动作或该步骤的

see

，然后重播该范围。继续之前，逐一打开每张截图进行检查：如果

see

与截图的实际内容不符，就重写

see

，绝不能保留不准确的内容。

4. Slideless, in the event's workspace

4. Slideless，在活动所属的 workspace 中

bash

npm i -g @antasphere/slideless@latest
slideless whoami --json

The participant's

hackathon login

is the same Antasphere login. It asks to sign in, or says "Run

antasphere login

": the participant runs

hackathon login

in their own terminal, then again. A refusal that the organization has no access to Slideless: STOP and tell the participant an organizer has to open Slideless to the event's organization; the screenshots and

guide.json

are kept for later.

workspace.name

hackathon whoami --json

is the event's organization; take the workspace with the same name in

slideless workspaces --json

and pass

--workspace <its id>

to every

slideless

command below. When none has that name, say so and ASK; never publish in a personal workspace.

bash

npm i -g @antasphere/slideless@latest
slideless whoami --json

参赛者使用的

hackathon login

与 Antasphere 登录是同一套身份。该命令会要求登录，或提示“Run

antasphere login

”：参赛者在自己的终端中运行

hackathon login

，然后再次运行该命令。如果系统以该组织没有 Slideless 访问权限为由拒绝：STOP，并告知参赛者需要由主办方为活动所属组织开通 Slideless；截图和

guide.json

将保留，供以后使用。

在

hackathon whoami --json

中，

workspace.name

是活动所属组织的名称；在

slideless workspaces --json

中选择同名 workspace，并向下面的每条

slideless

命令传入

--workspace <its id>

。如果不存在同名项，说明情况并 ASK；绝不发布到个人 workspace。

5. Start from the organizer's template, fill, check

5. 从主办方模板开始、填充并检查

bash

slideless template list --json --workspace <id>

Take the template titled

Demo deck

. When there is none, STOP: tell the participant the organizers have not published the event's templates yet (their

event-decks

guide does it) and to ask one of them. Never build the page any other way. Then, once:

bash

slideless template start "Demo deck" decks/demo/deck --workspace <id>
printf 'decks/*/deck/\ndecks/*/check/\n' >> .gitignore    # once per clone, if not there yet

decks/demo/deck/

carries the Antasphere brand's typefaces, whose licence forbids a public repository: it is never committed. When it already exists, keep it: its

.slideless.json

is the link to the published deck. Then:

bash

node "$SKILL_DIR/scripts/fill.mjs" demo decks/demo
node "$SKILL_DIR/scripts/check.mjs" decks/demo

fill.mjs

copies

guide.json

and the screenshots into the deck and renders the page with the template's own renderer. Exit 2, one line per problem (more than three episodes, an episode under two steps, a step without its screenshot or a

noshot

, a text too long): fix

guide.json

or replay the step, run it again.

check.mjs

opens the page with every episode open and its step player, and on a phone, writes

decks/demo/check/

, and prints

ok

. Exit 1, one line per problem. Open the screenshots with the participant (

open decks/demo/check

), or the page itself (

open decks/demo/deck/index.html

);

open

on macOS,

start

on Windows,

xdg-open

on Linux.

bash

slideless template list --json --workspace <id>

选择标题为

Demo deck

的模板。如果不存在，STOP：告知参赛者主办方尚未发布该活动的模板（由主办方的

event-decks

guide 完成此操作），并让参赛者向其中一位主办方询问。绝不以其他方式构建该页面。然后，以下操作只需执行一次：

bash

slideless template start "Demo deck" decks/demo/deck --workspace <id>
printf 'decks/*/deck/\ndecks/*/check/\n' >> .gitignore    # once per clone, if not there yet

decks/demo/deck/

包含 Antasphere 品牌字体，其许可证禁止将其放入公开仓库，因此绝不提交该目录。如果该目录已经存在，则保留它：其中的

.slideless.json

是指向已发布演示文稿的链接。然后：

bash

node "$SKILL_DIR/scripts/fill.mjs" demo decks/demo
node "$SKILL_DIR/scripts/check.mjs" decks/demo

fill.mjs

会将

guide.json

和截图复制到演示文稿中，并使用模板自身的 renderer 渲染页面。退出码 2 时，每个问题占一行（演示片段超过 3 个、某个演示片段少于 2 个步骤、某个步骤缺少截图或

noshot

、文本过长）：修复

guide.json

或重播该步骤，然后再次运行。

check.mjs

会打开页面，展开每个演示片段并显示步骤播放器，同时在手机端检查页面，将结果写入

decks/demo/check/

，并打印

ok

。退出码 1 时，每个问题占一行。与参赛者一起打开截图（

open decks/demo/check

），或直接打开页面（

open decks/demo/deck/index.html

）； macOS 使用

open

，Windows 使用

start

，Linux 使用

xdg-open

。

6. Publish and share

6. 发布并分享

bash

slideless push decks/demo/deck --kind app --title "<Team> · Demo" --template "Demo deck" --no-open --json --workspace <id>
slideless share <deck id> --name "Jury" --json --workspace <id>

--kind app

: the demo is a page that scrolls, not slides. Read

presentation.id

, then

url

(

https://<host>/v/<token>/

, shown once). No password and no expiry: the jury opens it after the event. A refusal about credits: an organizer tops the organization up; say so and stop.

bash

slideless push decks/demo/deck --kind app --title "<Team> · Demo" --template "Demo deck" --no-open --json --workspace <id>
slideless share <deck id> --name "Jury" --json --workspace <id>

--kind app

：该演示是一个滚动页面，而不是幻灯片。读取

presentation.id

，然后读取

url

（

https://<host>/v/<token>/

，只显示一次）。不设密码，也不设过期时间：活动结束后评审仍可打开。如果因 credits 不足而被拒绝：告知参赛者需要由主办方为该组织充值，然后停止。

7. Hand the link to the platform

7. 将链接提交给平台

bash

hackathon decks link --demo <url> --json
hackathon decks show --json

The team is the signed-in participant's own. Exit 2: not a share link

https://<host>/v/<token>/

. Exit 1 with the platform's sentence: the link's host is not one the platform accepts (the sentence names the allowed host). Exit 3: sign in, or not on a team. The pitch and the vote presentation are the two other links (the

hackathon-deck-pitch

skill, the

hackathon-deck-vote

skill); they reuse these screenshots.

Commit

decks/demo/guide.json

play.mjs

screens/

and

results.json

, never

decks/demo/deck/

decks/demo/check/

. Push before the freeze like any other work.

bash

hackathon decks link --demo <url> --json
hackathon decks show --json

该团队必须是当前登录参赛者所属的团队。退出码 2：提供的不是

https://<host>/v/<token>/

格式的分享链接。退出码 1：平台会给出相应说明，表示链接的 host 不在平台允许的 host 列表中（该说明会列出允许的 host）。退出码 3：尚未登录，或当前用户不属于任何团队。 Pitch 和投票演示文稿是另外两个链接（

hackathon-deck-pitch

skill、

hackathon-deck-vote

skill）；它们会复用这些截图。

提交

decks/demo/guide.json

、

play.mjs

、

screens/

和

results.json

，绝不提交

decks/demo/deck/

或

decks/demo/check/

。像处理其他工作一样，在冻结截止前 push。

Never

绝不

Never put a password, an API key or a real person's data in a screenshot or a step.
Never a button or a link that asks the jury to open the app: it is not online.
Never build the page without the organizer's template, and never copy the brand's files elsewhere.
Never share the demo with a password or an expiry: the jury opens it after the event.
Never pass a credential to
```
slideless
```
or
```
hackathon
```
: the Antasphere login does the work.
Never commit
```
~/.cache/antasphere-hackathon/
```
or anything from it.

绝不在截图或步骤中放入密码、API key 或真实人员的数据。
绝不放置要求评审打开应用的按钮或链接：该应用未部署到线上。
绝不在没有主办方模板的情况下构建页面，也绝不将品牌文件复制到其他位置。
绝不使用密码或过期时间分享演示：活动结束后评审仍需能够打开。
绝不向
```
slideless
```
或
```
hackathon
```
传递凭据；由 Antasphere 登录完成身份验证。
绝不提交
```
~/.cache/antasphere-hackathon/
```
或其中的任何内容。