feat: support docs fetch selection anchors

[SunPeiYang996]

Summary

• preserve docs URL fragments and auto-convert #share-* / #part-* fragments to range start_block_id when scope is not explicitly full
• keep ordinary #block_id fragments as normal full-doc fetches
• reject selection anchors passed through --end-block-id and keep --scope full as a full-read override

Validation

• remote Go tests for shortcuts/doc passed
• PPE E2E passed through lark-cli docs +fetch against creation.platform.ai_edit_pre_release / ppe_codex_share_anchor_r2 for URL#share auto-range, explicit range, full override, ordinary fragment, and invalid end-block-id cases

Related

• SDK MR: https://code.byted.org/lark/office_ai_sdk/merge_requests/179

Summary by CodeRabbit

• New Features
  • docs +fetch can infer localized range reads from --doc selection-anchor fragments (#share-...) by auto-setting read_mode=range and using the fragment id as start_block_id (when scope is range-like).
  • --scope full ignores selection-anchor fragments; ordinary or unsupported anchors (e.g., #part-..., #share-) won’t trigger auto-reading.
• Bug Fixes
  • Validation now supports range mode when start/end can be inferred from the effective selection-anchor-derived settings (instead of requiring explicit start/end).
• Documentation
  • Updated --scope range examples and guidance for #share-... behavior.
• Tests
  • Added unit, e2e, and dry-run coverage for selection-anchor handling and request payloads.

[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

This PR adds selection-anchor support for docs fetch v2. Document fragments are parsed and stored on documentRef, and buildReadOption/validateReadModeFlags derive and validate an effective range start block ID from --start-block-id or the --doc URL fragment. Tests, e2e coverage, and docs were updated.

Changes

Selection Anchor Fetch Support

Layer / File(s)	Summary
Document fragment parsing shortcuts/doc/helpers.go, shortcuts/doc/helpers_test.go	documentRef gains a Fragment field populated via extractDocumentFragment for /wiki/, /docx/, and /doc/ URLs; tests validate the extracted fragment.
Effective read mode and start block resolution shortcuts/doc/docs_fetch_v2.go, shortcuts/doc/docs_fetch_v2_test.go	buildReadOption uses selection-anchor-aware helpers to derive range mode and start block ID from --start-block-id or the --doc fragment; fetch-body tests and the Cobra runtime are updated to exercise doc-fragment driven behavior.
Selection anchor validation shortcuts/doc/docs_fetch_v2.go, shortcuts/doc/docs_fetch_v2_test.go	validateReadModeFlags uses the effective read mode, and the range-mode required-field check now accepts inferred anchors; validation tests cover the updated scope acceptance.
Test and guidance updates tests/cli_e2e/docs/docs_fetch_dryrun_test.go, skills/lark-doc/SKILL.md, skills/lark-doc/references/lark-doc-fetch.md	New e2e coverage checks dry-run request shaping for anchor-based fetches, and docs add selection-anchor guidance and examples.

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

Suggested labels: size/L

Suggested reviewers: fangshuyu-768

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description covers summary and validation, but it misses the required Changes and Test Plan sections from the template.	Add a Changes list and a Test Plan with checkbox items matching the template, and ensure Related Issues uses the expected format.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and matches the main change: adding docs fetch selection anchor support.
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 unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/docs-fetch-share-anchor-range-start

---

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

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

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

🧩 Skill update

npx skills add larksuite/cli#codex/docs-fetch-share-anchor-range-start -y -g

[codecov]

Codecov Report

❌ Patch coverage is 92.59259% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 74.45%. Comparing base (cdd9d34) to head (a3fdf5a).
⚠️ Report is 8 commits behind head on main.

Files with missing lines	Patch %	Lines
shortcuts/doc/docs_fetch_v2.go	91.30%	2 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1815      +/-   ##
==========================================
+ Coverage   74.43%   74.45%   +0.01%     
==========================================
  Files         860      860              
  Lines       89827    89906      +79     
==========================================
+ Hits        66864    66940      +76     
+ Misses      17781    17780       -1     
- Partials     5182     5186       +4     

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