feat: support isv block references in docs xml

[ZEden0]

Summary

Add lark-cli docs XML support for generic ISV blocks. Fetch now exposes configured ISV blocks as <isv-block type="..." data-ref="..."> with data stored under reference_map.isv-block, while html5-block behavior remains unchanged.

Changes

• Request ISV block data from ai_edit during docs +fetch.
• Serialize ISV reference data under the stable reference_map.isv-block group.
• Emit inline ISV data for small payloads and path-backed resources for larger payloads.
• Flatten fetched ISV resource paths to doc-fetch-resources/{doc_token}/isv_N.data.
• Add CLI dry-run and resource handling tests for ISV reference behavior.

Test Plan

• go test ./shortcuts/doc
• go build -o ./lark-cli .
• go test ./tests/cli_e2e/docs -run 'TestDocs_DryRunDefaultsToV2OpenAPI|TestDocs_CreateTitleDryRunPrependsContent'
• E2E covered fetch, create, replace, delete, missing reference, unknown type, and Lark-brand write rejection paths.
• Report gate passed for /Users/bytedance/.ccm-harness/worktrees/lark-cli-isv-blocks/larksuite_cli/.lark-cli-e2e-test/reports/isv-timeline-20260703144947/report.md.

Related Issues

N/A

Summary by CodeRabbit

• New Features

  • Added support for ISV block resources alongside existing document block handling.
  • Docs fetch now includes ISV block data by default in request payloads.

• Bug Fixes

  • Large ISV block content is now stored more efficiently during fetch, avoiding oversized output.
  • ISV block markup validation and rewriting now handle invalid attributes and empty-body requirements more consistently.
  • Markdown code fences no longer trigger ISV block processing.

[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: 34989091-9725-47ab-9714-748e7d778c58

📥 Commits

Reviewing files that changed from the base of the PR and between a1506cd and db513b7.

📒 Files selected for processing (5)

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

---

📝 Walkthrough

Walkthrough

Adds ISV block reference map support to docs v2 shortcuts, paralleling the existing HTML5 block workflow. Introduces a return_isv_block_data extra_param toggle, isv-block tag validation/rewriting for create/update, fetch-time offload of large ISV data to .data files, generalized tag parsing/rendering shared with html5-block, and corresponding tests.

Changes

ISV block reference map support

Layer / File(s)	Summary
Extra param toggle and fetch entry point shortcuts/doc/docs_fetch_v2.go, shortcuts/doc/docs_fetch_v2_test.go, tests/cli_e2e/docs/docs_update_dryrun_test.go	Adds return_isv_block_data:true to docsFetchExtraParam and wires processISVBlockReferenceMapForFetch into executeFetchV2; updates unit and e2e test expectations accordingly.
ISV write-path rewriting and validation shortcuts/doc/html5_block_resources.go	Adds isv-block tag/attribute constants and regexes, extends the reference-map preparation pipeline, and adds prepareISVBlockWriteContent/validateISVBlockWriteElementBodies to rewrite and validate <isv-block> elements during create/update.
ISV fetch-time processing shortcuts/doc/html5_block_resources.go	Adds processISVBlockReferenceMapForFetch, referenceMapFromDocumentForBlock, validateFetchedISVBlockRefs, resolveISVReferenceMapPaths, readISVBlockPath, and writeISVBlockReferenceFile to offload oversized ISV data into .data files during fetch.
Shared helpers and generalized tag parsing/rendering shortcuts/doc/html5_block_resources.go	Adds hasProcessableISVBlock, isvReferenceMapFromObject, mergeISVReferenceMap, nextISVBlockRef, and generalizes tag parsing/rendering (parseBlockStartTag, parseISVBlockStartTag, rewriteISVBlockStartTags, renderTag) shared with html5-block.
ISV block tests shortcuts/doc/html5_block_resources_test.go	Adds tests for fetch materializing large ISV data to a flat path, create loading data from path, rejection of invalid attribute combinations, ignoring isv-block inside markdown code fences, and update block_delete omitting reference_map.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant DocsCreateOrUpdate
  participant ReferenceMapPipeline
  participant FileIO

  DocsCreateOrUpdate->>ReferenceMapPipeline: build request body with isv-block content
  ReferenceMapPipeline->>ReferenceMapPipeline: rewrite <isv-block> tags, assign data-ref
  ReferenceMapPipeline->>FileIO: read path="`@relative.data`" if provided
  FileIO-->>ReferenceMapPipeline: file contents
  ReferenceMapPipeline-->>DocsCreateOrUpdate: reference_map.isv-block merged into payload

Loading

sequenceDiagram
  participant DocsFetch
  participant executeFetchV2
  participant processISVBlockReferenceMapForFetch
  participant FileIO

  DocsFetch->>executeFetchV2: fetch document (extra_param includes return_isv_block_data)
  executeFetchV2->>processISVBlockReferenceMapForFetch: fetched document payload
  processISVBlockReferenceMapForFetch->>processISVBlockReferenceMapForFetch: validate data-ref tags resolve
  processISVBlockReferenceMapForFetch->>FileIO: write oversized data to .data file
  FileIO-->>processISVBlockReferenceMapForFetch: written path
  processISVBlockReferenceMapForFetch-->>executeFetchV2: updated reference_map with path
  executeFetchV2-->>DocsFetch: document content with data-ref preserved

Loading

Possibly related PRs

• larksuite/cli#1547: Directly extends the docsFetchExtraParam constant and TestBuildFetchBodyIncludesFetchExtraParamByDefault test introduced in that PR, adding the ISV block data toggle.
• larksuite/cli#1690: Both PRs extend the same docs v2 reference_map plumbing in html5_block_resources.go/docs_fetch_v2.go, with this PR adding isv-block support mirroring the html5-block support added there.

Suggested labels: feature

Suggested reviewers: caojie0621

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: ISV block reference support in docs XML.
Description check	✅ Passed	The description matches the required template and includes summary, changes, test plan, and related issues.
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

---

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@db513b7bbe5f1844eca72f6e9df7a4116b78fc74

🧩 Skill update

npx skills add ZEden0/cli#feat/lark-cli-isv-blocks -y -g