fix(wiki): guide recovery from node layer limits

[liujinkun2025]

Summary

• classify Wiki error code 131003 as a non-retryable, command-specific node layer limit for wiki +node-create
• provide actionable recovery guidance to choose another parent or introduce an intermediate node
• document the behavior in the wiki +node-create reference and cover metadata, cause preservation, no-retry behavior, and upstream hint preservation

Testing

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

Summary by CodeRabbit

• Bug Fixes

  • Improved wiki node creation errors when node-count, directory-depth, or direct-child limits are reached.
  • These errors are now identified as non-retryable while preserving existing error details and recovery guidance.
  • Added clearer recommendations to use a shallower or alternate parent, reorganize nodes, or use another knowledge space.

• Documentation

  • Expanded guidance for handling wiki layer-limit errors and clarified that repeating the same request will not resolve the issue.

[coderabbitai]

📝 Walkthrough

Walkthrough

Wiki node creation now handles layer-limit error 131003. It marks the error as non-retryable, preserves the original cause, adds recovery guidance, and documents structural remediation options.

Changes

Wiki layer-limit recovery

Layer / File(s)	Summary
Layer-limit error classification and recovery shortcuts/wiki/wiki_node_create.go, shortcuts/wiki/wiki_node_create_test.go, skills/lark-wiki/references/lark-wiki-node-create.md	Wiki node creation detects error code 131003, prevents retries, preserves the upstream cause, combines recovery hints, tests the behavior, and documents structural remediation options.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• larksuite/cli#2266: Both PRs modify Wiki node creation handling, tests, and documentation for different error cases.

Suggested reviewers: liangshuo-1

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes recovery guidance for Wiki node layer-limit errors.
Description check	✅ Passed	The description explains the change and lists verification commands, but omits the template headings and Related Issues section.
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.

✨ 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-layer-limit-guidance

---

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: 1

🤖 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_node_create_test.go`:
- Around line 1026-1064: Extend the regression tests for the recovery paths that
append hints: in shortcuts/wiki/wiki_node_create_test.go lines 1026-1064, seed
limitErr with an upstream Problem.Hint and assert the resulting hint is
"<upstream hint>\n"+wikiNodeCreateLayerLimitHint; in
shortcuts/doc/docs_create_test.go lines 403-421, seed err similarly and assert
"<upstream hint>\n"+docsCreateWikiLayerLimitHint. Update both affected test
sites; no production-code change is requested.

🪄 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: baa77278-badf-446c-ae9f-219d31ef2e0f

📥 Commits

Reviewing files that changed from the base of the PR and between b1167a1 and bea6ece.

📒 Files selected for processing (6)

• shortcuts/doc/docs_create_test.go
• shortcuts/doc/docs_create_v2.go
• shortcuts/wiki/wiki_node_create.go
• shortcuts/wiki/wiki_node_create_test.go
• skills/lark-doc/references/lark-doc-create.md
• skills/lark-wiki/references/lark-wiki-node-create.md

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

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

🧩 Skill update

npx skills add larksuite/cli#fix/wiki-node-layer-limit-guidance -y -g

[codecov]

Codecov Report

❌ Patch coverage is 81.81818% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 76.47%. Comparing base (6d6b688) to head (e1ba458).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
shortcuts/wiki/wiki_node_create.go	81.81%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2290   +/-   ##
=======================================
  Coverage   76.46%   76.47%           
=======================================
  Files        1013     1013           
  Lines      112034   112089   +55     
=======================================
+ Hits        85665    85715   +50     
- Misses      19857    19860    +3     
- Partials     6512     6514    +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]

🧹 Nitpick comments (2)

shortcuts/wiki/wiki_node_create_test.go (2)

1055-1064: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Assert that the classified Subtype is populated.

The test checks Category, Code, Retryable, Hint, and the cause. It does not check problem.Subtype. A regression that drops subtype metadata would still pass. Assert that problem.Subtype is non-empty without requiring a domain-specific subtype constant.

Based on learnings, shortcut error-path tests should verify a populated Subtype while asserting Category == errs.CategoryAPI instead of depending on a layer-specific subtype constant. As per coding guidelines, error tests must assert typed metadata and cause preservation rather than message text alone.

Proposed assertion

 	if !ok {
 		t.Fatalf("error = %T, want typed problem", err)
 	}
+	if problem.Subtype == "" {
+		t.Fatalf("problem subtype is empty")
+	}
 	if problem.Category != errs.CategoryAPI || problem.Code != wikiNodeCreateStructuralLimitCode || problem.Retryable {

🤖 Prompt for 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.

In `@shortcuts/wiki/wiki_node_create_test.go` around lines 1055 - 1064, Extend the
assertions in the wiki node creation error test after errs.ProblemOf to require
that problem.Subtype is non-empty, while keeping the existing CategoryAPI, code,
retryability, hint, and cause checks unchanged; do not require a domain-specific
subtype constant.

Sources: Coding guidelines, Learnings

---

1028-1031: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Pin the upstream code independently from the production constant.

wikiNodeCreateStructuralLimitCode supplies both the simulated upstream code and the expected code. If the production constant changes from 131003, this test changes with it and still passes. Define a test-local const upstreamCode = 131003 and use it for both values.

The PR objective defines 131003 as the fixed upstream code.

Proposed test hardening

 	const upstreamHint = "upstream recovery hint"
+	const upstreamCode = 131003
 	limitErr := errs.NewAPIError(errs.SubtypeUnknown, "opaque upstream message").
-		WithCode(wikiNodeCreateStructuralLimitCode).
+		WithCode(upstreamCode).
...
-	if problem.Category != errs.CategoryAPI || problem.Code != wikiNodeCreateStructuralLimitCode || problem.Retryable {
+	if problem.Category != errs.CategoryAPI || problem.Code != upstreamCode || problem.Retryable {

Also applies to: 1059-1060

🤖 Prompt for 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.

In `@shortcuts/wiki/wiki_node_create_test.go` around lines 1028 - 1031, Define a
test-local constant such as upstreamCode with the fixed value 131003, and use it
both when constructing the simulated API error and when asserting the expected
upstream code in the affected wiki node creation tests. Stop using
wikiNodeCreateStructuralLimitCode for either test value so changes to the
production constant cannot make these tests pass incorrectly.

🤖 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.

Nitpick comments:
In `@shortcuts/wiki/wiki_node_create_test.go`:
- Around line 1055-1064: Extend the assertions in the wiki node creation error
test after errs.ProblemOf to require that problem.Subtype is non-empty, while
keeping the existing CategoryAPI, code, retryability, hint, and cause checks
unchanged; do not require a domain-specific subtype constant.
- Around line 1028-1031: Define a test-local constant such as upstreamCode with
the fixed value 131003, and use it both when constructing the simulated API
error and when asserting the expected upstream code in the affected wiki node
creation tests. Stop using wikiNodeCreateStructuralLimitCode for either test
value so changes to the production constant cannot make these tests pass
incorrectly.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 467c436a-5d5f-4f3b-aa56-75396b1daa73

📥 Commits

Reviewing files that changed from the base of the PR and between d285563 and e1ba458.

📒 Files selected for processing (3)

• shortcuts/wiki/wiki_node_create.go
• shortcuts/wiki/wiki_node_create_test.go
• skills/lark-wiki/references/lark-wiki-node-create.md

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

• shortcuts/wiki/wiki_node_create.go
• skills/lark-wiki/references/lark-wiki-node-create.md