fix(wiki): bound node retries and rate-limit recovery

[liujinkun2025]

Summary

• retry wiki +node-copy only when the Wiki API returns lock-contention code 131009
• use two bounded exponential-backoff retries (250 ms and 500 ms) while leaving every other copy error untouched
• return typed network errors when copy retry backoff is canceled or reaches its deadline, preserving the original context cause
• add wiki +node-get recovery guidance for 99991400: honor retry_after_seconds when present, otherwise use exponential backoff with jitter, and stop after 3 total attempts
• preserve upstream typed metadata, hints, retry timing, and causes across both recovery paths

Safety

wiki +node-copy retries only the explicit 131009 write-lock conflict. Network failures and unrelated API errors are not retried, avoiding ambiguous replay of this non-idempotent operation.

wiki +node-get does not retry inside the CLI. It remains retryable=true and gives callers a bounded recovery policy: one initial request plus at most two delayed retries, then stop and try again later.

Testing

• go test ./shortcuts/wiki/...
• node scripts/skill-format-check/index.js
• git diff --check

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Wiki node copy now retries lock-contention errors with bounded exponential backoff and preserves typed error details. Wiki node lookup now adds rate-limit recovery guidance. Tests and references document both behaviors.

Changes

Wiki recovery handling

Layer / File(s)	Summary
Copy retry entrypoint shortcuts/wiki/wiki_node_copy.go	The copy operation defines two retries with a 250 ms base delay. It passes the prepared API path and request body to runWikiNodeCopyWithRetry.
Contention retry and error preservation shortcuts/wiki/wiki_node_copy.go	Lock-contention errors trigger exponential retries. Context cancellation and deadline expiration return non-retryable network errors. Unrelated errors propagate immediately. Exhausted retries preserve typed details and add contention guidance.
Copy retry validation and documentation shortcuts/wiki/wiki_list_copy_test.go, skills/lark-wiki/references/lark-wiki-node-copy.md	Tests cover retry success, unrelated errors, interrupted backoff, exhausted retries, and preserved causes. The reference documents bounded contention retries.
Node lookup rate-limit handling shortcuts/wiki/wiki_node_get.go, shortcuts/wiki/wiki_node_get_test.go, skills/lark-wiki/references/lark-wiki-node-get.md	Rate-limit errors retain their metadata and cause while adding guidance for retry delays, reduced concurrency, request deduplication, and a three-attempt limit.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Mergeability Score: 🔵 Low · up to 72802

The PR adds bounded retries for lock contention while leaving other errors unchanged, so no merge-blocking runtime risk is identified. Before merging, owners should clarify that the limit is three total attempts and document reducing bulk-lookup concurrency after rate-limit responses.

Sequence Diagram(s)

sequenceDiagram
  participant RunWikiNodeCopy
  participant runWikiNodeCopyWithRetry
  participant WikiAPI
  participant Context
  RunWikiNodeCopy->>runWikiNodeCopyWithRetry: prepared API path and request body
  runWikiNodeCopyWithRetry->>WikiAPI: copy wiki node
  WikiAPI-->>runWikiNodeCopyWithRetry: lock-contention error
  runWikiNodeCopyWithRetry->>Context: check cancellation during backoff
  runWikiNodeCopyWithRetry->>WikiAPI: retry copy request
  WikiAPI-->>runWikiNodeCopyWithRetry: success or final wrapped error
  runWikiNodeCopyWithRetry-->>RunWikiNodeCopy: copied node data or preserved error contract

Loading

Possibly related PRs

• larksuite/cli#2233: Both PRs implement context-aware retry and error handling in different code paths.
• larksuite/cli#2238: Both PRs modify Wiki node-copy behavior and its tests and documentation.

Suggested labels: bugfix

Suggested reviewers: liangshuo-1

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the main changes: bounded node-copy retries and rate-limit recovery guidance.
Description check	✅ Passed	The description covers the change scope, safety rationale, and test commands, but it does not use all template headings or include the manual verification checklist.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/wiki-node-copy-lock-retry

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@shortcuts/wiki/wiki_list_copy_test.go`:
- Around line 627-646: Extend TestRunWikiNodeCopyDoesNotRetryOtherErrors to
inspect errs.ProblemOf(err) and assert the returned error has
errs.CategoryAuthorization and errs.SubtypePermissionDenied metadata, while
retaining the existing single-call and cause-preservation assertions.

In `@shortcuts/wiki/wiki_node_copy.go`:
- Around line 125-129: Update the cancellation branch in the backoff select to
return a *errs.NetworkError, using SubtypeNetworkTimeout for deadline expiry and
SubtypeNetworkTransport for other cancellations, while preserving ctx.Err() via
WithCause. Add a backoff-cancellation test that verifies the error metadata and
cause and confirms no additional API call occurs.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 6ec0eb3d-339f-4405-a249-e6461c2ef910

📥 Commits

Reviewing files that changed from the base of the PR and between 79eb16c and fdc5c5a.

📒 Files selected for processing (3)

• shortcuts/wiki/wiki_list_copy_test.go
• shortcuts/wiki/wiki_node_copy.go
• skills/lark-wiki/references/lark-wiki-node-copy.md

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@668b17a84e0f917d745b45fc462dbc0fb25d43fb

🧩 Skill update

npx skills add larksuite/cli#fix/wiki-node-copy-lock-retry -y -g

[codecov]

Codecov Report

❌ Patch coverage is 88.67925% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 74.67%. Comparing base (f98db39) to head (668b17a).

Files with missing lines	Patch %	Lines
shortcuts/wiki/wiki_node_copy.go	88.23%	4 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2292      +/-   ##
==========================================
- Coverage   76.45%   74.67%   -1.78%     
==========================================
  Files        1025     1025              
  Lines      113720   137489   +23769     
==========================================
+ Hits        86939   102675   +15736     
- Misses      20109    28140    +8031     
- Partials     6672     6674       +2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@skills/lark-wiki/references/lark-wiki-node-get.md`:
- Around line 68-73: Update the rate_limit guidance in the bulk lookup retry
instructions to require callers to reduce concurrency after receiving a 99991400
response, in addition to honoring bounded backoff. Preserve the existing
retry-attempt limit and prohibition on identity switching or reauthorization,
and make the concurrency reduction explicit for bulk operations.
- Line 72: Update the retry guidance in the documented operation to state
explicitly that there are three total attempts: one initial request followed by
two retries, with retry delays of 250 ms and 500 ms; avoid wording that could
imply three retries after the initial request.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 39547476-0552-4899-bcb6-ed8effc6b771

📥 Commits

Reviewing files that changed from the base of the PR and between f5c7d3a and 72802fa.

📒 Files selected for processing (2)

• shortcuts/wiki/wiki_node_get.go
• skills/lark-wiki/references/lark-wiki-node-get.md

🚧 Files skipped from review as they are similar to previous changes (1)

• shortcuts/wiki/wiki_node_get.go

[fangshuyu-768]

Re-reviewed the latest head. The simplified retry guidance preserves the bounded retry contract, and the focused verification passes.