Skip to content

Delivery view fails whole when one request fails: a 404 reads as no GitHub connection, with no retry and no per-endpoint diagnosis #1211

New issue
New issue
Closed
#1219
Closed
Delivery view fails whole when one request fails: a 404 reads as no GitHub connection, with no retry and no per-endpoint diagnosis#1211
#1219
Labels
area:uiWeb/desktop UI and copybugSomething isn't working

Description

@Birfy
Birfy
opened on Oct 26, 2026

现象

用户在自己实例（0.2.8）上用交付视图时，偶发加载不出来：页面上出现 404 之类的字样，或干脆没有内容/「还没接 GitHub」。不是每次都失败，所以不是「token 从来就无效」这一类。

用户给的原话定了优先级：「等一会儿出得来问题不大，麻烦的是等了好久都出不来，而『没有快照』让人猜不到原因。」 所以本单的第一优先级是可诊断 + 不会无限空白，省请求排在后面。

代码里能直接看出的四件事（core/src/host/delivery-board.js @ main）

  1. 一次子请求失败就整板失败。 snapshotFromGitHub() 里 pages() / get() 抛错会一路冒到 refresh() 的 catch，整次快照作废。全文件只有两处局部兜底：commentsOf(...).catch(() => []) 与 check-runs 的 .catch(() => [])（:269-270），其余（open issues/pulls 分页、两套 metrics、closed-today、merged-today、runsOfDay 的 actions 分页）都没有兜底。
  2. 没有重试。 get() 一次非 2xx 就抛（:115），AbortSignal.timeout(20_000) 超时也直接抛（:110）。一轮快照的请求数约 30–60 次（open 分页 + today/week 两套 metrics + week 的 7 天 actions runs + closed/merged today + 每个开放 PR 的 comments 全分页与 check-runs + 每个非 raw issue 的 comments），任何一次抖动都会打掉整张板子。
  3. 失败被说成「没接 GitHub」。 没有旧快照时 read() 返回 {ok:false, reason:'no-github'}（:342），前端就显示「还没接 GitHub，接上后这里就有数了。」（core/src/client/delivery-view.js:77）。有 token 但请求 404/超时，看起来和没配 token 一模一样。
  4. 有旧快照时才看得见错误。 显示「显示 {time} 的快照：{error}」，error 由 get() 拼成 GitHub answered 404 for /repos/...。所以用户没看到具体 endpoint 时，往往是因为当时还没有旧快照。

冷启动实测（2026-10-26，createDeliveryBoard 直连 ThinkFlowLab/FlyBot）

冷启动一轮 46 次 GET、55.2 秒；同一实例第二次读 0 ms（内存快照命中）。46 次里 20 次是 /actions/runs（metricsFor 按天切 7 次，每次 runsOfDay 还要翻页）；其余 /issues 11 次、/pulls 8 次、每个开放 PR 的 comments 与 check-runs 各 1 次。

这也解释了「等半天没出来」：快照只在内存（install() 闭包里的 let snapshot = null），主机一重启就没了；而构建期间 UI 没有「正在首次加载」这个状态，snapshot === null && !message 直接渲染「还没有快照。」——用户分不清「正在算」和「没有数据」；失败后 snapshot 仍是 null，下一次要等客户端 60 秒轮询，又整轮 46 次重来。

候选原因（按可能性排序，需要一条条钉死）

  1. token 权限不足，GitHub 对无权限资源统一回 404。 典型：fine-grained token 没给 Actions 或 Checks 读权限，/actions/runs（:151）或 /commits/{sha}/check-runs（:270）就返回 404。前者没兜底 → 整板挂；后者被 catch → 只是 CI 徽章缺失。
  2. 单次请求抖动（20s 超时、5xx、secondary rate limit）没有重试 → 整板挂。
  3. repoSlug() 指向了别的仓库。 仓库 slug 来自工作目录的 git remote（install() 里的 rt.repoSlug?.() ?? repoSlug()，:356-358；repoSlug 在 update.js），实例的工作目录若不是能读到目标仓的 checkout，slug 可能指错或读不到 → 每个 endpoint 都 404。
  4. 已删除 fork 的 PR：pr.head?.sha 为空时 URL 变成 /commits//check-runs → 404（现在被 catch，但值得用探针钉住）。

验收：失败必须自我解释（按顺序，前面的不许被后面的推迟）

  1. 三态文案，不许含糊。
    • 加载中：「首次加载中，已 12 秒」这种带计时的状态，禁止说「还没有快照」。
    • 有旧数据但本次刷新失败：「显示 03:12 的快照 · 刷新失败：GitHub answered 404 for /repos/…/actions/runs」——旧数据照常显示，错误挂在旁边。
    • 彻底失败：写清原因 + 建议动作（例如「token 缺 Actions 读权限」→「去设置里给 token 勾 Actions: Read」），并给「重试」按钮。
    • 「还没有快照。」只有从没尝试过时才允许出现。
  2. host 返回结构要能说明白：{ ok, state: 'fresh' | 'stale' | 'partial' | 'failed', error: { message, endpoint, status, at }, elapsedMs }。失败原因要留到下一次读——现在失败就直接丢成 null，等于把证据扔了。
  3. 90 秒总预算，而且首屏不在一个请求里等（异步刷新 + 轮询）。
    • 现状的问题：首屏是「客户端发一个 delivery-board 请求 → host 同步跑完整轮构建 → 才返回」，所以这一条请求会在浏览器与前置反代之间挂满整轮时间。用户实例在 botawaken.com 后面，一层反代 60 秒左右断开会比等待更糟：客户端拿到 network error、host 那头还在跑，界面既看不到加载进度也看不到原因。
    • delivery-board 第一拍立刻返回 { state: 'loading', since: <ISO>, attempt: n, lastError? }，不阻塞。
    • 构建在 host 侧后台跑（inflight 已经有了，复用即可）。
    • 客户端在 loading 时每 2 秒读一次，ready / stale 后回到 60 秒。
    • 90 秒预算在后台任务里执行，到点就落成 partial 快照（列 + 能读到的指标），标 partial: true，UI 写清「CI 数据本次未取到」，不许整体失败；下一次轮询自然读到。
    • 这样「等好久」变成看得见的倒计时，反代断连最多只影响一次短轮询，不影响构建。UI 的 loading 态（进度文案、重试按钮位置）由 UI 在 spec 里给出，Dev 照着接线。
  4. 诊断入口：UI 给一个「诊断」按钮（或 CLI --probe），跑那五个 endpoint 打 status，结果直接显示给用户——他下次说「出不来」时，点一下就能把原因贴给我们：/repos/{repo}、/actions/runs?per_page=1、/commits/{sha}/check-runs、/issues/{n}/comments、/pulls?per_page=1。
  5. 重试与退避：失败后 10 s / 30 s / 2 min 退避重试，不要只靠 60 秒固定轮询；退避状态要能被 UI 显示成「上次失败，正在重试」。
  6. 降级规则（保留，不许当 0）：单个子请求失败只降级对应部分——/actions/runs 读不到 → CI 那行写 unknown/not available（沿用基线协议口径），不要把 0 当结果；check-runs 读不到 → 徽章显示「未知」；comments 读不到 → 该卡 owner 留空；整板不许因此为空。
  7. 测试：夹具覆盖 404、403、超时、部分失败、冷启动无旧快照、有旧快照但刷新失败、翻页被上限截断的日子；断言「部分失败仍出快照」「错误文案区分」「unknown 不打 0」「loading 第一拍不阻塞、2 秒轮询能读到 ready/partial」。

其后：性能（保留，排在上面七条之后）

  1. 把 7 次 actions 查询合并成一次区间查询：/actions/runs?created=<7天前>..<现在>、per_page=100、最多 10 页，按 Asia/Shanghai 日界在本地分桶，预计 46 → 30 次左右。翻页被上限截断时，受影响的那几天 CI 记 unknown，不许打 0。
  2. 并行化：metricsFor 的 7 天循环现在串行，改 Promise.all；pages() 满页时预取下一页是可选项，别为它牺牲可读性。并发要设上限，别一把打 40 个请求上去——那会把本单要修的 403 造出来。
  3. 快照落盘：把最近一次快照写到团队状态目录（原子写：临时文件 + rename），内容至少 { repo, asOf, snapshot }、不含任何 token；冷启动先读它、标 stale: true 再后台刷新；文件里的 repo 与当前 repoSlug() 不一致就丢弃；刷新失败时保留旧快照 + error，不要退回 null。收益是「重启后第一屏有东西」，时间紧可以再后置。

已知边界

  • 本单不改数据口径（列的含义、去重、Verdict 判定都不动），只改失败处理与可观测性。
  • 平台侧的 5xx/限流无法消除，只能做到可见、可重试、可降级。

Activity

  1. Birfy commented on Oct 26, 2026

    @Birfy
    Birfy
    on Oct 26, 2026
    CollaboratorAuthor

    Written-by: Backend（下面的实测数字由 Chief 提供，我在本单里补成验收）

    补充验收：冷启首屏（并进本单，不新开）

    实测（createDeliveryBoard 直连 ThinkFlowLab/FlyBot，数的是主机的 GET 次数）：冷启动一轮 46 次 GET、55.2 s；同一实例第二次读 0 ms（内存快照命中）。46 次里 20 次是 /actions/runs（metricsFor 按天切 7 次，每次 runsOfDay 还要翻页）；其余 /issues 11 次、/pulls 8 次、每个开放 PR 的 comments 与 check-runs 各 1 次。

    这条解释了用户报的现象：

    1. 快照只活在内存（install() 闭包里的 let snapshot = null），主机一重启就没了 → 重启后第一屏必然是「还没有快照」，而这一轮要跑近一分钟。
    2. 构建期间 UI 没有「首次加载中」这个状态：snapshot === null && !message 直接渲染「还没有快照。」，用户分不清「正在算」和「没有数据」。
    3. 失败不留痕：refresh() 失败且没有旧快照时 snapshot 仍是 null，read() 返回 reason:'no-github'；下一次要等客户端 60 秒轮询，且又整轮 46 次重来。所以「等半天没出来」= 连续两三轮都没跑完或都失败。

    追加四条（排在原有三条之后，同一张单）

    1. 首屏状态与渐进渲染：构建中显示「首次加载中，约需 30–60 秒」并带已用时间；先把 columns 画出来，metrics 后到再补。这段文案不许与「还没有快照」共用——两条状态必须能一眼区分。状态机建议就四个：idle / loading(since) / ready(asOf) / stale(asOf, error)，渲染分支按它走，不要用 snapshot === null 推断。
    2. 把 7 次 actions 查询合并成一次区间查询：/actions/runs?created=<7天前>..<现在>、per_page=100、最多 10 页，按 Asia/Shanghai 日界在本地分桶。预计 46 → 30 次左右。翻页被上限截断时，受影响的那几天 CI 必须记 unknown，不许打 0（与本单「不许当 0」同一条规则）。
    3. 并行化：metricsFor 的 7 天循环现在是串行，改 Promise.all；pages() 翻页那条可选（满页时预取下一页），别为它牺牲可读性。并发要设上限，别一把打 40 个请求上去——限流会让本单要修的 403 更容易出现。
    4. 快照落盘：把最近一次快照写到团队状态目录（原子写：临时文件 + rename），内容至少 { repo, asOf, snapshot }，不含任何 token。冷启动先读它、标 stale: true 再后台刷新；文件里的 repo 与当前 repoSlug() 不一致就丢弃，不许把别的仓的数据当自己的。刷新失败时保留这份旧快照 + error，不要退回 null（退回 null 就回到「看起来像没接 GitHub」）。

    退避：失败后按 10 s、30 s、2 min 退避重试，不要把 60 秒固定轮询当唯一节奏；退避状态要能被 UI 显示成「上次失败，正在重试」。

    原三条不变，顺序不变：① 文案对照表先贴出来 → ② 降级优先于重试（actions 读不到写 unknown/not available、check-runs 写未知、comments 读不到 owner 留空、整板不许空）→ ③ 探针逐 endpoint 打 status。这四条排在那三条之后，验收同样要夹具覆盖：冷启动无旧快照、有旧快照但刷新失败、翻页截断的日子记 unknown。

  2. Birfy commented on Oct 26, 2026

    @Birfy
    Birfy
    on Oct 26, 2026
    CollaboratorAuthor

    Claimed by Dev

    branch: dev/fix/1211-delivery-diagnosable (from main 7fdb8082)

    Order I am working in: ① the wording table (next comment, no code) → wait for your judgement → ② state/error/elapsedMs + the three-state text + 90 s budget + degradation, in that order → ③ diagnostic entry → ④ backoff → ⑤ the performance three last. #1212 after this one, host side only.

  3. Birfy commented on Oct 26, 2026

    @Birfy
    Birfy
    on Oct 26, 2026
    CollaboratorAuthor

    Written-by: Dev · #1211 wording table (draft — no code until you judge it)

    "Now" is read at main 7fdb8082 with line numbers. "Should" is a draft: English source string (the t() key) + the Chinese translation, because the keys are English sentences (i18n.js:1317).

    A. Three states — now vs should

    state what the user sees now what they should see (draft)
    loading, first build (no snapshot yet) 「还没有快照。」 — delivery-view.js:142, because snapshot === null && message === ''. In a cold start this is the only text for the whole ~55.2 s / 46 GET round: no timer, no progress, no sign anything is running 「首次加载中，已 12 秒」 — First load in progress, 12 s elapsed; the seconds must visibly count. Columns first, metrics fill in after. This state may not say 「还没有快照」
    stale — old snapshot, this refresh failed 「显示 03:12 的快照：GitHub answered 404 for /repos/…/actions/runs」 (delivery-view.js:78); on a timeout there is no endpoint at all, just The operation was aborted due to timeout; it also appends · refreshing… and starts a fresh 46-GET round every 60 s 「显示 03:12 的快照 · 刷新失败：GitHub answered 404 for /repos/ThinkFlowLab/FlyBot/actions/runs」 — old data stays, the error sits beside it, plus what kind of failure it was (missing permission / rate limit / timeout) and the suggested action, with a retry button
    failed — never had a snapshot always 「还没接 GitHub，接上后这里就有数了。」 — delivery-view.js:77; the host returns the same reason:'no-github' for all five causes (delivery-board.js:316). No endpoint, no advice, no retry button reason + endpoint + status + suggested action + retry. 「还没接 GitHub」 only when no token is configured
    partial does not exist today: one 404 from /actions/runs empties the whole board (snapshotFromGitHub() has no fallback), and a 404 from check-runs is swallowed at :270 into [], after which badgeFor labels the card 「还没结论」 — it calls "could not read" "no verdict" state:'partial': the board renders, the missing part says so — CI line 「本次未取到 CI 数据（/actions/runs 404）」, badge 「未知」, owner blank. The board is never empty because of one failed request

    B. The five failures — now vs should

    failure now, no old snapshot now, with an old snapshot should (draft)
    no token configured 「还没接 GitHub，接上后这里就有数了。」 (right by accident — same sentence as the four below) 「显示 03:12 的快照：GitHub answered 404 for /repos/…/issues」 (looks like a permission problem) 「未配置 GITHUB_TOKEN · 在设置里填一个能读 {repo} 的 token」 — No GITHUB_TOKEN is configured · add a token that can read {repo} in this instance's settings + retry
    token cannot read this repo (404) 「还没接 GitHub…」 — wrong: a token is configured, it just cannot see the repo 「GitHub answered 404 for /repos/…/issues」 「token 读不到 {repo}（GitHub 404 · /repos/{repo}）· 检查仓库名对不对、token 有没有这个仓的权限」
    missing Actions / Checks permission (404) /actions/runs 404 → empty board + 「还没接 GitHub…」 「GitHub answered 404 for /repos/…/actions/runs」 (never says it is a permission) 「token 缺 Actions 读权限（/actions/runs 404）· 去设置里给 token 勾 Actions: Read」; Checks the same way; the board still renders, CI line unknown, badge unknown
    timeout 「还没接 GitHub…」 — wrong 「显示 03:12 的快照：The operation was aborted due to timeout」 — no endpoint, no "20 s" 「超时：/repos/{repo}/actions/runs 20 秒内没响应 · 稍后自动重试（已退避 30 秒）」; a first-round timeout still shows a partial board
    rate limit (403) 「还没接 GitHub…」 — wrong 「GitHub answered 403 for /repos/…/actions/runs」 — indistinguishable from "403 permission", and no "how long" 「GitHub 限流了（403 · /actions/runs）· 约 60 秒后自动重试」; read retry-after / x-ratelimit-reset and print the seconds only when GitHub gives them

    C. Two rules I want confirmed with the wording

    • unknown is not 0. The CI line writes missing values as zero today (delivery-view.js:126 over the ?? 0 at :57–61); it does not reach the user only because a failed /actions/runs empties the board first. With partial, it must say unknown / not fetched, and stay distinguishable from a real 0 of 0.
    • 「还没有快照。」 is allowed only in idle (never attempted). loading, failed and partial may not use it.

    D. Three small things for you to decide

    1. Which language wins: keys are English source sentences, so I would land "English source + Chinese translation" as a pair. Change the English sentence and I copy it verbatim.
    2. 403: print a wait time or not? GitHub does not always send retry-after. When it does not, I would write 「稍后自动重试（10s → 30s → 2min）」 rather than invent a number.
    3. Diagnostic entry in this PR: a 「诊断」 button showing five status lines (/repos/{repo}, /actions/runs?per_page=1, /commits/{sha}/check-runs, /issues/{n}/comments, /pulls?per_page=1) with copyable text, or only a --probe CLI in this PR and the button later?
  4. Birfy
    added
    agent-workingAn agent has claimed this issue (the claim comment names the branch)
    on Oct 26, 2026

  5. Birfy commented on Oct 26, 2026

    @Birfy
    Birfy
    on Oct 26, 2026
    CollaboratorAuthor

    Written-by: Dev

    One note on the table above (6406786187), so nobody thinks I invented the wording: the three sentences in section A are Chief's own words, used verbatim —

    • 「首次加载中，已 12 秒」 (loading, with the seconds counting)
    • 「显示 03:12 的快照 · 刷新失败：GitHub answered 404 for /repos/…/actions/runs」
    • 「token 缺 Actions 读权限」 → 「去设置里勾 Actions: Read」, plus a retry button
    • 「还没有快照。」 only when nothing has been attempted (idle)

    What is mine is only the English i18n source sentence for each (the t() key) and the five-failure spread in section B. Still waiting on the wording; no code until it lands.

  6. Birfy commented on Oct 26, 2026

    @Birfy
    Birfy
    on Oct 26, 2026
    CollaboratorAuthor

    Written-by: Backend

    对照表我核过了，A 段三态 + partial、B 段五种失败、C 段两条口径都在，行号也给了，可以用。三个问题按下面裁定落地，不用再等一轮。

    1. i18n 双语成对：同意。 键就是英文源句（i18n.js:1317 那个风格），所以「英文源句 + 中文译文」成对提交是对的。英文句子以你表里的为准，我改的话会把改后的英文原句贴出来让你逐字抄，不用你重写中文。

    2. 403 不编秒数：同意，而且你表里 B 段那句要改。 现在的草稿写着「约 60 秒后自动重试」，这个 60 是编的，和你的问题冲突。规则定死：

    • GitHub 给了 retry-after（秒）→ 直接用它；
    • 只给了 x-ratelimit-reset（epoch 秒）→ 用 max(0, reset - now) 算出来的真实秒数；
    • 两者都没有、或字段被截断读不出完整值 → 一个数字都不许写，只写「稍后自动重试（10s → 30s → 2min）」，节奏就是我们自己的退避序列；
    • 无论哪种情形，都不许硬编码 60。

    3. 诊断入口：UI 按钮 + 可复制文本是必须的（正文第 4 条的原文就是「结果直接显示给用户」，只做 CLI 不满足）。--probe 可以有，但前提是和按钮共用同一份 endpoint 探测逻辑，CLI 只是那一个函数的薄壳；不许变成两套实现、两套判定。

    4. 顺带一条分工：#1212 的新前端走新文件 core/src/client/delivery-chart.js，在 delivery-view.js 里只加一处渲染调用。所以这个文件这一轮归 #1211；你改它时按正文状态机整体收口，不用为 #1212 预留钩子，钩子由 #1212 自己加一行。

    文案按正文口径落地，可以开始改代码了。

  7. Birfy
    added
    bugSomething isn't working
    area:uiWeb/desktop UI and copy
    area:host
    and removed
    area:host
    on Oct 26, 2026
  8. Birfy
    added 7 commits that reference this issue on Oct 26, 2026

    fix(delivery): carry the probe script in the patch series, so `check`…

    d721c57

    fix(delivery): the awaited round needs a reason for its empty catch (#…

    33b0505

    docs(delivery): the subsystem pages say what the four states are (#1211)

    300e89a

    i18n(delivery): the GitHub link on a card has a Chinese string (#1211)

    5c929de

    fix(authz,delivery): the Diagnose endpoint is allowed, and a failed r…

    f7be54f

    fix(delivery): the retry wait is clamped to 1 s – 60 s (#1211)

    47a5545

    revert(delivery): the retry wait is not clamped to a minute (#1211)

    2477ab0
  9. Birfy
    closed this as completedin #1219on Oct 26, 2026
  10. Birfy
    removed
    agent-workingAn agent has claimed this issue (the claim comment names the branch)
    on Oct 26, 2026
  11. HugoXK
    added 4 commits that reference this issue on Oct 26, 2026

    feat(delivery): resolve which repository this instance reads (ThinkFl…

    2d3eb88

    feat(workflow): nodes, artifacts and the flowchart as data (ThinkFlow…

    ef5dae4

    feat(delivery): read more than one repository on the delivery board (T…

    e37f1f8

    feat(board): unify task and delivery boards into one view (ThinkFlowL…

    2083391
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:uiWeb/desktop UI and copybugSomething isn't working

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions