docs: clarify fetch metadata and user cites

[SunPeiYang996]

Summary

Clarify document fetch sidecars and user-cite XML import requirements without introducing a new fetch mode.

Changes

• Add the generic document.reference_map response shape.
• Describe the block_type -> ref -> real-attr-key -> real-attr-value mapping.
• Explain that reference_map stays paired with content, while tips carries safe replay or degradation guidance.
• Require every imported, newly created, or edited <cite type="user"> to include user-id with the user open ID.
• Keep --purpose fully removed from the CLI and lark-doc skill.

Test Plan

• go test ./shortcuts/doc
• Verify docs +fetch --help does not expose --purpose
• Skill format check

Related Issues

• None

[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

docs +fetch now accepts read and edit purposes, selecting different extra_param payloads for user citation mapping. Unit tests, E2E tests, coverage documentation, and operational guidance were updated accordingly.

Changes

Purpose-aware document fetching

Layer / File(s)	Summary
Purpose-based fetch request construction shortcuts/doc/docs_fetch_v2.go, shortcuts/doc/docs_fetch_v2_test.go	Fetch request payloads select citation-map settings from --purpose; edit-purpose behavior is covered by unit tests and test runtimes register the new flag.
Purpose selection guidance skills/lark-doc/SKILL.md, skills/lark-doc/references/*	Documentation describes read versus edit, their interaction with detail levels, returned metadata, and refetching requirements.
End-to-end purpose validation tests/cli_e2e/docs/*	E2E tests validate edit-purpose fetches, dry-run payload values, and the updated coverage matrix.

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

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant buildFetchBody
  participant DocsAPI
  CLI->>buildFetchBody: pass --purpose read or edit
  buildFetchBody->>buildFetchBody: select extra_param JSON
  buildFetchBody->>DocsAPI: send fetch request body

Loading

Possibly related PRs

• larksuite/cli#1428: Updates fetch test runtime and flag-default setup used by the purpose-dependent tests.
• larksuite/cli#1547: Changes the same extra_param citation-map field.
• larksuite/cli#1690: Modifies v2 fetch extra_param handling, including HTML5 block data.

Suggested reviewers: fangshuyu-768

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The template is filled out, but the content contradicts the PR by claiming --purpose was removed instead of added.	Rewrite the Summary and Changes to describe the new --purpose read|edit behavior, the user-cite reference-map changes, and the added test coverage.

✅ Passed checks (4 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 is concise and related to the fetch metadata and user-cite changes, though it doesn't name the new --purpose option.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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@113b582755e097b2a366961dab4f73189d824e9b

🧩 Skill update

npx skills add SunPeiYang996/cli#codex/docs-fetch-edit-purpose -y -g