feat(doc): add --width/--height flags to docs +media-insert

[songyoung77]

Summary

Add --width and --height flags to docs +media-insert so users and AI agents can control the display size of inserted images. When only one dimension is specified, the other is auto-calculated from the image's native aspect ratio.

Changes

• Add --width and --height int flags with validation in shortcuts/doc/doc_media_insert.go
• Add computeMissingDimension() and detectImageDimensions() aspect-ratio helpers in shortcuts/doc/doc_media_insert.go
• Wire dimension resolution into Execute (after upload, before batch_update) and DryRun (best-effort preview) in shortcuts/doc/doc_media_insert.go
• Add 13 unit tests covering payload construction, validation, and aspect-ratio calculation in shortcuts/doc/doc_media_insert_test.go
• Update SKILL.md with new flags and usage examples in skills/lark-doc/references/lark-doc-media-insert.md

Test Plan

• make unit-test passed
• make validate passed
• local-eval passed (E2E 7/8 — 1 env-only failure: test app lacks space:document:delete scope for cleanup; skillave 6/6)
• acceptance-reviewer passed (5/5 cases)
• manual verification: lark-cli docs +media-insert --doc <token> --file img.png --width 600 --as bot — confirmed aspect-ratio auto-calc and output fields

Related Issues

Closes #489

Summary by CodeRabbit

• New Features

  • Added optional --width and --height to docs +media-insert for image sizing (pixels).
  • If only one dimension is given, the missing dimension is auto-computed from the image's aspect ratio when detectable.
  • Dry-run and execution now report computed image dimensions when available.

• Bug Fixes / Validation

  • --width/--height are rejected for non-image types; must be positive integers for images.

• Documentation

  • Updated command docs with sizing examples and support details.

[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: 9643765b-b7b9-48a7-a562-a9437260185e

📥 Commits

Reviewing files that changed from the base of the PR and between 9b2fe95 and 9386118.

📒 Files selected for processing (1)

• shortcuts/doc/doc_media_insert.go

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

• shortcuts/doc/doc_media_insert.go

---

📝 Walkthrough

Walkthrough

Adds --width and --height flags to docs +media-insert for images, validates their usage and positivity, detects native image dimensions when needed, computes the missing dimension by aspect ratio, includes resolved sizes in batch_update payloads, updates command output, tests, and docs.

Changes

Image sizing feature

Layer / File(s)	Summary
Flag definitions and imports shortcuts/doc/doc_media_insert.go	Exports new --width and --height int flags on DocMediaInsert restricted to --type=image. Adds image decoder imports.
Validation logic shortcuts/doc/doc_media_insert.go	Rejects --width/--height unless --type=image and ensures provided dimensions are positive integers.
Dimension detection and aspect-ratio helpers shortcuts/doc/doc_media_insert.go	Adds imageDimensions, detectImageDimensions, detectImageDimensionsFromPath, and computeMissingDimension.
Dry-run dimension resolution shortcuts/doc/doc_media_insert.go	Dry-run best-effort: when exactly one dimension set and source is a file, decode native size and pass dryWidth/dryHeight; for clipboard, emit a note deferring calculation.
Execute dimension resolution shortcuts/doc/doc_media_insert.go	At runtime, use both provided values or decode native image size (clipboard bytes or file) and compute the missing dimension; error if decoding fails when only one dimension was provided.
Batch update payload with dimensions shortcuts/doc/doc_media_insert.go	buildBatchUpdateData accepts width/height and conditionally attaches them to replace_image when positive; batch_update call passes resolved sizes.
Command output with dimensions shortcuts/doc/doc_media_insert.go	Includes computed width and/or height in runtime.Out for images when positive.
Implementation tests shortcuts/doc/doc_media_insert_test.go	Updates tests to pass width/height arguments, adds tests for image/file payloads with dimensions, validation rules, aspect-ratio completion, and a test helper for flag setting.
User documentation skills/lark-doc/references/lark-doc-media-insert.md	Adds examples and parameter docs for --width and --height, explaining auto-computation and supported formats.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Possibly related PRs

• larksuite/cli#508: Adds clipboard image-reading support used for native dimension detection.

Suggested labels

size/L

Suggested reviewers

• liujinkun2025
• fangshuyu-768

Poem

A rabbit counts the pixels right,
One dimension set, the other's light,
It reads the bytes or opens files,
Computes the height with merry smiles,
And inserts images sized just right. 🐰🖼️

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 6.25% 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 feature addition: adding --width/--height flags to docs +media-insert.
Description check	✅ Passed	The PR description follows the template with complete Summary, Changes, Test Plan, and Related Issues sections providing all required information.
Linked Issues check	✅ Passed	The PR fully addresses issue #489 by implementing --width/--height flags with auto-computed dimensions and aspect-ratio calculation as requested.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to implementing the width/height feature: flags, validation, helpers, tests, and documentation. No unrelated modifications detected.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

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 and usage tips.}

[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/doc/doc_media_insert.go`:
- Around line 565-571: detectImageDimensionsFromPath opens an untrusted filePath
directly; call validate.SafeInputPath(filePath) at the start of
detectImageDimensionsFromPath (before fio.Open) and return any validation error
to prevent reading unsafe paths. Keep the existing signature and behavior
otherwise (open via fio.Open, defer Close, call detectImageDimensions), and
ensure the validation error is propagated so callers (e.g., DryRun/Execute)
receive the failure.

🪄 Autofix (Beta)

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

Run ID: c198a35c-11cf-45cc-a55e-7bbcbcbfef84

📥 Commits

Reviewing files that changed from the base of the PR and between 7c6abb3 and 9b2fe95.

📒 Files selected for processing (3)

• shortcuts/doc/doc_media_insert.go
• shortcuts/doc/doc_media_insert_test.go
• skills/lark-doc/references/lark-doc-media-insert.md

[CLAassistant]

All committers have signed the CLA.