From 56d124890761a46f0e6f082a4be8d5cf15551fec Mon Sep 17 00:00:00 2001 From: guanlili Date: Thu, 12 Nov 2026 17:59:11 +0800 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20=E5=9D=913=20=E8=A1=A5=E5=85=85?= =?UTF-8?q?=E5=AE=9E=E6=B5=8B=E2=80=94=E2=80=94=E6=AC=A1=E7=BA=A7=E9=99=90?= =?UTF-8?q?=E6=B5=81=E9=98=88=E5=80=BC=E9=9A=8F=E5=BD=93=E6=97=A5=E7=B4=AF?= =?UTF-8?q?=E8=AE=A1=E5=86=99=E5=85=A5=E9=87=8F=E4=B8=8B=E9=99=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 2026-11-12 jilin-flex-platform 飞书台账回填(issue #4–#11 + 会话记账 #12)两度撞次级限流: 首轮约 60 次批量写后触发(符合原 40–70 次记录);12 分钟静默冷却已清、单写验证通过后, 仅再连写 5 次即再度触发——冷却后的再触发阈值大幅下降。 处置建议:大批量回填拆天/拆时段跑,或每 ~30 次写预排一段 ≥15min 静默。 --- references/pitfalls.md | 1 + 1 file changed, 1 insertion(+) diff --git a/references/pitfalls.md b/references/pitfalls.md index 67fd615..e689b0c 100644 --- a/references/pitfalls.md +++ b/references/pitfalls.md @@ -6,6 +6,7 @@ 2. **设值**:`gh project item-edit` 用 `--field 名 --value 值`(无 --single-select-option 旗标) 3. **限流两层**:主 5000 点/小时(等 `rateLimit.resetAt`);次级限流=连续写触发(2026-11-09 energy-platform 18 条回填实测细节): - 触发阈值约 **40–70 次连续写**;冷却期 GraphQL **读写全封**——`gh issue list` 等底层走 GraphQL 的命令也挂,报错同为 "rate limit exceeded" + - **阈值随当日累计写入量下降**(2026-11-12 jilin-flex-platform 回填实测):当日已批量写约 60 次且 12 分钟静默冷却已清、单写验证通过后,仅再连写 5 次即再度触发——大批量回填拆天/拆时段跑,或每 ~30 次写预排一段 ≥15min 静默。次级限流**按账号计、跨会话共享**:同机并行会话各自"静默"仍会互相触发,批量回填期间避免并行开其他写 Project 的会话 - 判别法:先查 `gh api rate_limit`,主限流余量充足却报限流 = 次级(REST 端点本身不受次级限流影响,冷却期可用 `gh api repos/...` 读数据) - **重试会续窗口**:300s 间隔的探测性重试让冷却拖过 20 分钟不散;必须真·静默(零 API 调用)10–20 分钟才清 - 批量写策略:操作间 ≥3s 步速、失败退避 ≥120s、设计成断点可续跑(只补差异),撞限流就整段静默冷却而不是逐条硬试 From 4e31199912a28f1fe08f89cc77208675d459018c Mon Sep 17 00:00:00 2001 From: guanlili Date: Thu, 12 Nov 2026 20:27:19 +0800 Subject: [PATCH 2/2] docs: record rate-limit observations and use GitHub retry guidance --- references/pitfalls.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/references/pitfalls.md b/references/pitfalls.md index e689b0c..e15ae14 100644 --- a/references/pitfalls.md +++ b/references/pitfalls.md @@ -4,12 +4,10 @@ 1. **编码**:`gh project item-list` 损坏中文自定义字段名首字节(值正常)→ 读数据一律 `gh api graphql` 直查 ProjectV2 2. **设值**:`gh project item-edit` 用 `--field 名 --value 值`(无 --single-select-option 旗标) -3. **限流两层**:主 5000 点/小时(等 `rateLimit.resetAt`);次级限流=连续写触发(2026-11-09 energy-platform 18 条回填实测细节): - - 触发阈值约 **40–70 次连续写**;冷却期 GraphQL **读写全封**——`gh issue list` 等底层走 GraphQL 的命令也挂,报错同为 "rate limit exceeded" - - **阈值随当日累计写入量下降**(2026-11-12 jilin-flex-platform 回填实测):当日已批量写约 60 次且 12 分钟静默冷却已清、单写验证通过后,仅再连写 5 次即再度触发——大批量回填拆天/拆时段跑,或每 ~30 次写预排一段 ≥15min 静默。次级限流**按账号计、跨会话共享**:同机并行会话各自"静默"仍会互相触发,批量回填期间避免并行开其他写 Project 的会话 - - 判别法:先查 `gh api rate_limit`,主限流余量充足却报限流 = 次级(REST 端点本身不受次级限流影响,冷却期可用 `gh api repos/...` 读数据) - - **重试会续窗口**:300s 间隔的探测性重试让冷却拖过 20 分钟不散;必须真·静默(零 API 调用)10–20 分钟才清 - - 批量写策略:操作间 ≥3s 步速、失败退避 ≥120s、设计成断点可续跑(只补差异),撞限流就整段静默冷却而不是逐条硬试 +3. **限流两层**:主限流以响应中的剩余额度和重置时间为准;次级限流可能影响 REST 和 GraphQL,GitHub 不公开所有触发条件。 + - 2026-11-09 回填 18 条 issue 时,约连续写入 40–70 次后遇到限流,期间 GraphQL 查询和写入均报错。 + - 2026-11-12 回填中,约写入 60 次后遇到限流。静默 12 分钟后单次写入成功,随后再连续写入 5 次又遇到限流。同机另一会话也在等待限流恢复。批量写入时尽量串行,避免多个会话同时写 Project。 + - 限流后暂停写入。优先遵守 `Retry-After`;如果没有该头且 `x-ratelimit-remaining` 为 0,等到 `x-ratelimit-reset`;否则至少等一分钟再试。持续遇到次级限流时指数退避,并设置重试上限。续跑前读回当前状态,只补差异。参见 [GitHub GraphQL 限流说明](https://docs.github.com/en/graphql/overview/rate-limits-and-query-limits-for-the-graphql-api)和 [REST 限流说明](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api)。 4. **视图**:API 建的字段不进已有视图 → `updateProjectV2View` 的 `visibleFieldIds` 配列 5. **mutation 参数**:update/delete 类只收 `fieldId`,不收 `projectId` 6. **选项整体替换**:`updateProjectV2Field.singleSelectOptions` 重交会**清空全部条目已选值** → 改选项后必须全量读回对账重设