feat(docs): enable user cite reference map on fetch

[SunPeiYang996]

Summary

Enable docs +fetch to explicitly request user cite reference_map export from ai_edit by passing enable_user_cite_reference_map in extra_param. This does not enable HTML5 block data export.

Changes

• Add enable_user_cite_reference_map=true to the docs +fetch extra_param payload.
• Keep drive +export --file-extension markdown on its existing docs_ai fetch body without extra_param, and add regression assertions for that shortcut.
• Cover the docs fetch extra_param contract in unit and dry-run E2E tests, and update docs/drive E2E coverage notes.

Test Plan

• Unit tests pass: remote go test ./shortcuts/doc ./shortcuts/drive -run "TestBuildFetchBodyIncludesFetchExtraParam|TestDocsFetchDryRunDefaultsToV2Endpoint|TestDriveExportMarkdownWritesFile|TestDriveExportMarkdownUsesProvidedFileName|TestDriveExportDryRunIncludesLocalFileNameMetadata|TestDriveExportMarkdownFallsBackToTokenWhenTitleLookupFails" -count=1
• Dry-run E2E passes: remote make build && go test ./tests/cli_e2e/docs ./tests/cli_e2e/drive -run "TestDocs_DryRunDefaultsToV2OpenAPI|TestDriveExportDryRun_MarkdownFetchAPI" -count=1
• PPE smoke: remote-built dev-cite-reference binary via lark-cli-env ppe_sun_cite_reference docs +fetch on KlcwdGrpKoE8jHxuk8zcXreTnVb succeeded; drive +export markdown on the same doc succeeded and kept the existing markdown cite shape.

Related Issues

• None

Summary by CodeRabbit

• New Features

  • Document fetch operations now send an additional option to enable user cite reference mapping.

• Bug Fixes

  • Markdown export flows no longer include Docs fetch extra_param fields.

• Tests

  • Added unit coverage to verify fetch request bodies include only the intended extra_param.
  • Updated CLI end-to-end dry-run validations to assert the presence/absence of extra_param as appropriate.

• Documentation

  • Refreshed dry-run documentation and coverage notes to reflect the updated docs +fetch behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 44f86830-fb18-4362-88c2-f1dd444f1421

📥 Commits

Reviewing files that changed from the base of the PR and between 789d392 and ad913b2.

📒 Files selected for processing (7)

• shortcuts/doc/docs_fetch_v2.go
• shortcuts/doc/docs_fetch_v2_test.go
• shortcuts/drive/drive_export_test.go
• tests/cli_e2e/docs/coverage.md
• tests/cli_e2e/docs/docs_update_dryrun_test.go
• tests/cli_e2e/drive/coverage.md
• tests/cli_e2e/drive/drive_export_dryrun_test.go

✅ Files skipped from review due to trivial changes (2)

• tests/cli_e2e/drive/coverage.md
• tests/cli_e2e/docs/coverage.md

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

• tests/cli_e2e/docs/docs_update_dryrun_test.go
• shortcuts/doc/docs_fetch_v2_test.go
• shortcuts/doc/docs_fetch_v2.go

---

📝 Walkthrough

Walkthrough

A new package-level constant docsFetchExtraParam is added to the v2 docs fetch module, holding a JSON string that enables enable_user_cite_reference_map for cite reference map export. This constant is injected into the buildFetchBody payload as extra_param. Unit and e2e tests validate its presence for docs fetch, while drive export tests explicitly verify markdown export does not include this parameter.

Changes

Add extra_param to docs v2 fetch body

Layer / File(s)	Summary
docsFetchExtraParam constant and fetch body wiring shortcuts/doc/docs_fetch_v2.go	Defines docsFetchExtraParam as a JSON constant enabling enable_user_cite_reference_map, then injects it as extra_param in the v2 fetch request body inside buildFetchBody.
Unit test for extra_param in fetch body shortcuts/doc/docs_fetch_v2_test.go	Adds TestBuildFetchBodyIncludesFetchExtraParam to assert the constant is included and excludes return_html5_block_data and legacy reference_map_mode.
E2E test coverage for extra_param in docs dry-run tests/cli_e2e/docs/docs_update_dryrun_test.go, tests/cli_e2e/docs/coverage.md	Extends the e2e dry-run test struct with wantExtraParam, sets it for the fetch case, and asserts api.0.body.extra_param via gjson + JSONEq. Updates coverage doc to reflect the new assertions.
Markdown export validation excludes extra_param shortcuts/drive/drive_export_test.go, tests/cli_e2e/drive/drive_export_dryrun_test.go, tests/cli_e2e/drive/coverage.md	Adds assertions across markdown export tests to validate that the fetch request must not contain extra_param, covering basic export, named file export, metadata dry-run, and token fallback flows. Updates drive coverage documentation to document the markdown fetch API behavior.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• larksuite/cli#948: Both PRs touch the Drive markdown export's docs_ai/v1/documents/{token}/fetch request path—main PR adds/validates that this request must not include extra_param, while the retrieved PR switches markdown export to that same v2 fetch endpoint (with format=markdown).
• larksuite/cli#1466: Both PRs modify shortcuts/doc/docs_fetch_v2.go's v2 fetch request payload construction (the buildFetchBody path), so the main PR's new extra_param export toggle is added in the same request-building logic that the other PR adjusts.

Suggested labels

size/S, feature

Suggested reviewers

• fangshuyu-768
• caojie0621

Poem

🐰 A constant of JSON, so small and so neat,
Now rides in the fetch body, making it complete.
Cite maps enabled for docs with delight,
But markdown says "no thanks"—it keeps things just right!
Export params flowing, the feature takes flight! 🚀

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 9.09% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: enabling user cite reference map on the docs fetch feature.
Description check	✅ Passed	The description comprehensively covers all required sections with clear explanations of changes, thorough test verification, and follows the repository template structure.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 codex/fetch-doc-user-cite-reference-map

---

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 73.97%. Comparing base (736b131) to head (ad913b2).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1547   +/-   ##
=======================================
  Coverage   73.97%   73.97%           
=======================================
  Files         787      787           
  Lines       76293    76294    +1     
=======================================
+ Hits        56436    56437    +1     
  Misses      15625    15625           
  Partials     4232     4232           

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

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

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

🧩 Skill update

npx skills add larksuite/cli#codex/fetch-doc-user-cite-reference-map -y -g