Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 4 additions & 5 deletions references/pitfalls.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,10 @@

1. **编码**:`gh project item-list` 损坏中文自定义字段名首字节(值正常)→ 读数据一律 `gh api graphql` 直查 ProjectV2
2. **设值**:`gh project item-edit` 用 `--field 名 --value 值`(无 --single-select-option 旗标;寻址方式见坑 11)
3. **限流两层**:主 5000 点/小时(等 `rateLimit.resetAt`);次级限流=连续写触发(2026-11-09 energy-platform 18 条回填实测细节):
- 触发阈值约 **40–70 次连续写**;冷却期 GraphQL **读写全封**——`gh issue list` 等底层走 GraphQL 的命令也挂,报错同为 "rate limit exceeded"
- 判别法:先查 `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` 重交会**清空全部条目已选值** → 改选项后必须全量读回对账重设
Expand Down
Loading