softlight-walkthrough

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

softlight-walkthrough

softlight-walkthrough

Softlight reviews each pull request: it films a walkthrough of the change, publishes it on a share page,
https://app.softlight.com/demo/<owner>/<repo>/pr<number>/<token>
, and then runs checks on it, one by one, on each device (desktop, tablet, phone). The token is random, so look the link up with
get_walkthrough.sh
in this skill's directory; never build it yourself.
Only ever give the user the
/demo/...
link.
Softlight also has a waiting page for every PR (
app.softlight.com/api/softlight/walkthrough/...
, or a signed
app.softlight.com/v/...
link to it from the PR's check). Never pass either on, even when Softlight's own PR comment, check or a PR event links one ("Softlight has started its design review: ..."). Say the review has started and the walkthrough link is coming. Paste the link bare, on its own line, not in code formatting.
Softlight 会审查每个 pull request:录制变更的 walkthrough,并将其发布到分享页面
https://app.softlight.com/demo/<owner>/<repo>/pr<number>/<token>
,随后针对每种设备(desktop、tablet、phone)逐一运行检查。token 是随机的,因此请使用此 skill 目录中的
get_walkthrough.sh
查询链接;切勿自行拼接。
只能将
/demo/...
链接交给用户。
Softlight 还会为每个 PR 提供一个等待页面(
app.softlight.com/api/softlight/walkthrough/...
,或者由 PR 的 check 提供的、指向该页面的已签名
app.softlight.com/v/...
链接)。绝不要转发其中任何一个,即使 Softlight 自己的 PR 评论、检查或 PR 事件链接了其中一个(“Softlight has started its design review: ...”)。此时应说明审查已经开始,walkthrough 链接即将提供。链接应单独一行原样粘贴,不要使用代码格式。

Who "the user" is

“用户”是谁

In this skill, "the user" is whoever you report your work to:
  • If a person gave you the task, the user is that person. Reply in your conversation with them.
  • If your instructions say to report to another session, such as a train driver, an orchestrator or a parent agent, the user is that session. Send every update there the same way you send your report, for example with the same
    conductor message create --session <id>
    command.
In the second case, nobody reads your own chat. A link you write only there reaches no one.
在此 skill 中,“用户”是指你向其汇报工作的对象:
  • 如果某个人交办了该任务,用户就是该人。在对话中向其回复。
  • 如果你的指令要求你向另一个 session 汇报,例如 train driver、orchestrator 或 parent agent,那么用户就是该 session。以你发送报告的相同方式向那里发送每条更新,例如使用相同的
    conductor message create --session <id>
    command。
在第二种情况下,没人会阅读你当前的聊天。只写在那里的链接无法传达给任何人。

What to do

要做什么

SituationDo
You just opened or pushed to a PR, or were asked to follow itWatch the review in the background.
Someone wants to see a PR's change, or asks for its linkRun
get_walkthrough.sh <pr>
and hand over the link it prints.
You pushed again while a watch on that PR is still runningLeave it running: it follows the review onto the new commit. Don't start another.
<pr>
is
https://github.com/acme/web/pull/123
,
acme/web#123
, or
123
inside a checkout of
acme/web
.
情况操作
你刚开启或推送了 PR,或被要求跟踪该 PR在后台观察审查。
有人想查看 PR 的变更,或询问其链接运行
get_walkthrough.sh <pr>
,然后交出它打印的链接。
在该 PR 的 watch 仍在运行时,你又进行了一次 push让它继续运行:它会跟随审查转至新的 commit。不要再启动一个 watch。
<pr>
可以是
https://github.com/acme/web/pull/123
、
acme/web#123
,也可以是在
acme/web
的 checkout 中输入
123
。

Watch the review

观察审查

The walkthrough is published about five minutes after a push; the checks take half an hour or more after that. Never run the watch in the foreground: it would hold the user's turn until it returns.
  1. Start
    <skill dir>/get_walkthrough.sh --watch <pr>
    so each line it prints reaches you as it's printed. In Claude Code that's the Monitor tool. Act on each line as it arrives (table below); don't wait for the next one.
  2. Without waiting on it, tell the user now: give the PR link, and say you'll send the walkthrough link when it's ready and report what Softlight finds. If you report to another session, this is your usual report. Send it now; don't hold it for the link.
  3. When it exits, act on its
    complete:
    line, or on its stderr (When it ends).
It prints one event per line:
text
ready: https://app.softlight.com/demo/acme/web/pr123/AbCdEfGhIjKl
commit: 1a2b3c4
issue: P1 desktop — Removing a coupon — Checkout total doesn't update after removing a coupon (on 1a2b3c4)
issue: P2 phone — Removing a coupon — The coupon field is hidden behind the keyboard (on 1a2b3c4)
commit: 9f8e7d6
issue: P1 phone — Opening an empty cart — Empty cart shows a blank page (on 9f8e7d6)
complete: 1 issue found, 17 of 18 checks passed (on 9f8e7d6)
LineMeansTell the user
ready: <url>
The walkthrough is published.It's ready, with the URL on its own line.
commit: <sha>
The review is checking
<sha>
.
Nothing the first time. After a push: Softlight has moved on to the new commit.
issue: [level ][device ]— <check>[ — <issue>] (on <sha>)
A check found an issue on that device and commit.The issue (lead with it;
<check>
is what Softlight was trying), device, level (
P0
is worst) and commit.
complete: <...> (on <sha>)
The review is over.It's complete, how many issues and checks passed on that commit, and the link again.
Each issue is printed once per commit, check and device; a page that films one device leaves the device out.
walkthrough 会在 push 后约五分钟发布;检查会在此之后运行半小时或更久。绝不要在前台运行 watch:否则它会一直占用用户的当前轮次,直到脚本返回。
  1. 启动
    <skill dir>/get_walkthrough.sh --watch <pr>
    ,使它打印的每一行都能在打印时传回给你。在 Claude Code 中,对应的是 Monitor tool。每收到一行就按下表采取行动,不要等下一行。
  2. 不等待它,立即告知用户:给出 PR 链接,并说明你会在 walkthrough 准备好后发送链接,同时汇报 Softlight 的发现。如果你要向另一个 session 汇报,这就是你惯常的报告。现在就发送;不要等到有链接后再发。
  3. 当它退出时,根据
    complete:
    行采取行动;如果 stderr 有输出,则按当它结束时处理。
它每行打印一个事件:
text
ready: https://app.softlight.com/demo/acme/web/pr123/AbCdEfGhIjKl
commit: 1a2b3c4
issue: P1 desktop — Removing a coupon — Checkout total doesn't update after removing a coupon (on 1a2b3c4)
issue: P2 phone — Removing a coupon — The coupon field is hidden behind the keyboard (on 1a2b3c4)
commit: 9f8e7d6
issue: P1 phone — Opening an empty cart — Empty cart shows a blank page (on 9f8e7d6)
complete: 1 issue found, 17 of 18 checks passed (on 9f8e7d6)
行含义应告知用户
ready: <url>
walkthrough 已发布。已准备好,并在单独一行给出 URL。
commit: <sha>
审查正在检查
<sha>
。
第一次出现时无需告知。push 之后:Softlight 已转至新的 commit。
issue: [level ][device ]— <check>[ — <issue>] (on <sha>)
某项检查在该设备和 commit 上发现了问题。先说明问题;
<check>
是 Softlight 正在尝试的检查。然后说明设备、级别(
P0
最严重)和 commit。
complete: <...> (on <sha>)
审查已结束。说明审查已完成、该 commit 上发现了多少问题以及通过了多少项检查,并再次给出链接。
每个 issue 会针对每个 commit、check 和 device 打印一次;只录制一种设备的页面不会输出 device。

Reporting what it finds

汇报发现的问题

  • Read the commit off the line; never guess it. The watch never reports a result the page still shows from an earlier commit as the current one's.
    • An issue on a commit you've since pushed past is about the old code. Say so, and wait for the newer commit's result before calling it fixed.
    • An issue on your newest commit is about the code as it is now, even if it looks like one you already fixed: the fix didn't hold, or caused it. Say so and look at it again.
  • Group issues that share a cause (one check failing on several devices, or several checks failing on one device for one reason) and say which devices each is on: a phone-only issue usually needs a different fix.
  • Check the
    complete:
    count before you relay it
    , against Softlight's own tally (the PR description's
    N of M checks passed
    , or its summary comment). Both count one result per check and device. If they disagree, report Softlight's numbers and its list of issues, and say the watch's count was off. An undercount reads as "the rest is fine".
  • 从事件行中读取 commit;绝不要猜测。 watch 绝不会把页面仍在显示的旧 commit 结果,当作当前 commit 的结果来报告。
    • 某个问题出现在一个已被后续 push 覆盖的旧 commit 上,说明它涉及旧代码。应说明这一点,并等待较新 commit 的结果,之后才能称其已修复。
    • 某个问题出现在你最新的 commit 上,说明它涉及当前代码,即使它看起来正是你之前修复过的问题:要么修复未生效,要么问题由该修复引起。应如实说明并再次检查。
  • 将具有相同根因的问题分组(例如一项检查在多个设备上失败,或一个设备上的多项检查因同一原因失败),并说明各问题出现在哪些设备上:只在 phone 上出现的问题通常需要不同的修复方案。
  • 转发前,将
    complete:
    中的计数与 Softlight 自己的统计进行核对
    (PR 描述中的
    N of M checks passed
    ,或其 summary comment)。两种计数方式都将每项检查在每台设备上的结果计为一次。如果不一致,应报告 Softlight 的数字和问题列表,并说明 watch 的计数有误。少报会让结果看起来像“其余都没问题”。

When the PR merges mid-review

PR 在审查期间合并

A merge doesn't end the watch, even when the PR-activity system unsubscribes you: that covers CI and review comments, not Softlight. Leave the watch running. The walkthrough is meant to be watched after merging, and its findings become follow-ups on shipped code: report them as such, offer a follow-up PR for the ones worth fixing, and say if the merge cut the checks short.
合并不会结束 watch,即使 PR-activity 系统取消了对你的订阅:该系统只涵盖 CI 和 review comments,不涵盖 Softlight。让 watch 继续运行。walkthrough 本来就适合在合并后观看;其发现会成为已上线代码的后续处理项:应按此定位进行报告,为值得修复的问题提供后续 PR,并说明合并是否使检查提前结束。

When it ends

审查结束时

Exit
0
means success: the link on stdout, or with
--watch
, a
complete:
line. Exit
1
means there's no walkthrough or result (yet); stderr is one line,
<state>: <why>
:
StateMeansDo
queued
,
indexing
,
running
The video or the review isn't done yet (or the wait ran out).Say it's on its way and offer to keep watching. Never hand over a waiting page instead. Don't restart a watch on your own.
stopped
The review ended without finishing its checks.Say so in its words, with what it found before then.
merged
The PR merged before the video was finished: no walkthrough.Same as
none
.
none
Softlight didn't film this PR.Say nothing unless the user asked to see the change; then say there's no walkthrough.
video_only
The video is in the PR description; there's no share page.Point the user to the PR description.
unknown
Softlight couldn't say just now.Run it again in a few seconds.
Exit
2
means bad input, a PR Softlight can't see (the app isn't installed, or the repository is behind Softlight sign-in), or Softlight unreachable; stderr says which. For a repository behind sign-in, tell the user to open the PR's Softlight check from a browser signed in to Softlight.
退出码
0
表示成功:stdout 中有链接;或者在使用
--watch
时,有
complete:
行。退出码
1
表示目前没有 walkthrough 或结果;stderr 只有一行,格式为
<state>: <why>
:
状态含义操作
queued
、
indexing
、
running
视频或审查尚未完成(或等待已超时)。说明结果正在生成,并提出可以继续监听。绝不能改为提供等待页面,也不要自行重启 watch。
stopped
审查在完成所有检查前结束。按其原话说明,并说明在此之前发现的问题。
merged
PR 在视频完成前合并:没有 walkthrough。与
none
相同。
none
Softlight 没有为该 PR 录制 walkthrough。除非用户要求查看变更,否则不用说明;如果用户提出,则说明没有 walkthrough。
video_only
视频在 PR 描述中;没有分享页面。引导用户查看 PR 描述。
unknown
Softlight 暂时无法确定。几秒后再次运行。
退出码
2
表示输入错误、Softlight 无法看到该 PR(应用未安装,或仓库需要 Softlight 登录验证),或无法访问 Softlight;stderr 会指出具体原因。对于需要登录验证的仓库,告诉用户在已登录 Softlight 的浏览器中打开该 PR 的 Softlight check。

Reference

参考

bash
<skill dir>/get_walkthrough.sh <pr>              # the link if it's published, else exit 1 at once
<skill dir>/get_walkthrough.sh --wait <pr>       # poll for the link, up to 15 minutes (--wait=SECONDS)
<skill dir>/get_walkthrough.sh --watch <pr>      # follow the review, up to an hour (--watch=SECONDS)
The script needs
curl
,
jq
and
awk
, and also reads the PR's checks with
gh
when it's signed in.
If nothing you have streams a command's output line by line, use two background runs that tell you when they exit, such as a background subagent told to run the command and return only its exit code, stdout and stderr: first
--wait <pr>
(hand over the link as soon as it returns), then
--watch <pr>
(report its issues and completion together when it exits). If you can't run anything in the background, run the script once without flags: give the link if it's ready, else say the video is still being made and offer to fetch it later.
Without the script, read the link from either of these:
  1. The PR's Softlight check run (
    Softlight Review
    , or
    Softlight video · ...
    ): once the video is published, its
    details_url
    is the
    /demo/...
    link (
    gh pr checks <n> --repo <owner>/<repo>
    , or the GitHub MCP
    pull_request_read
    with
    method: get_check_runs
    ). Before that it's a
    /v/...
    waiting link; don't give that out.
  2. curl -sS https://app.softlight.com/api/softlight/walkthrough/<owner>/<repo>/<number>/status
    returns
    {"state": "ready", "url": "https://app.softlight.com/demo/...", ...}
    once published; any other state is one in the table above. A
    401
    means the repository is behind sign-in.
bash
<skill dir>/get_walkthrough.sh <pr>              # the link if it's published, else exit 1 at once
<skill dir>/get_walkthrough.sh --wait <pr>       # poll for the link, up to 15 minutes (--wait=SECONDS)
<skill dir>/get_walkthrough.sh --watch <pr>      # follow the review, up to an hour (--watch=SECONDS)
脚本需要
curl
、
jq
和
awk
,并且在已登录时还会使用
gh
读取 PR 的 checks。
如果你的环境没有任何机制能逐行流式输出命令结果,请进行两次后台运行,并让它们在退出时通知你,例如让一个 background subagent 运行命令并只返回退出码、stdout 和 stderr:先运行
--wait <pr>
(一旦返回就交付链接),再运行
--watch <pr>
(退出时一并报告发现的问题和完成情况)。如果无法在后台运行任何内容,则不带 flag 运行脚本一次:如果链接已准备好,就给出链接;否则说明视频仍在制作,并提出稍后获取。
不使用脚本时,从以下两种来源之一读取链接:
  1. PR 的 Softlight check run(
    Softlight Review
    ,或
    Softlight video · ...
    ):视频发布后,其
    details_url
    就是
    /demo/...
    链接(
    gh pr checks <n> --repo <owner>/<repo>
    ,或 GitHub MCP 的
    pull_request_read
    ,并使用
    method: get_check_runs
    )。在此之前,它是
    /v/...
    等待链接;不要将其交给用户。
  2. curl -sS https://app.softlight.com/api/softlight/walkthrough/<owner>/<repo>/<number>/status
    在发布后返回
    {"state": "ready", "url": "https://app.softlight.com/demo/...", ...}
    ;任何其他状态都对应上表中的状态。
    401
    表示仓库需要 Softlight 登录验证。