feat(docs): support create title option

[SunPeiYang996]

Summary

• Add docs +create --title for v2 document creation.
• When --title is provided, prepend <title>...</title> to content before sending the request.
• Update lark-doc skill docs to guide Agent title usage and duplicate-title behavior.
• Add focused dry-run and shortcut tests for the new title path.

Validation

• PASS: remote make build
• PASS: remote go test ./shortcuts/doc -count=1
• PASS: remote go test ./tests/cli_e2e/docs -run "^TestDocs_(DryRunDefaultsToV2OpenAPI|CreateTitleDryRunPrependsContent)$" -count=1
• PASS: PPE ppe_sun_ai_test create/fetch checks for Markdown title creation and duplicate title filtering warnings.

Related

• SDK MR: https://code.byted.org/lark/office_ai_sdk/merge_requests/151
• ai_edit MR: https://code.byted.org/ccm-platform/ai_edit/merge_requests/145

Summary by CodeRabbit

• New Features

  • docs +create now supports a separate --title flag, including in dry-run output and help text.
  • When creating documents, the title is added to the generated content automatically and safely escaped.

• Bug Fixes

  • Improved validation so a title can be provided without document content in supported cases.
  • Updated legacy flag handling and error messages to reflect current create behavior.

• Documentation

  • Refreshed create/fetch docs and examples to match the new title/content usage and supported formats.

[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: c32ad0ed-f349-42e0-aa42-ac44389a3b31

📥 Commits

Reviewing files that changed from the base of the PR and between 051f8ef and 66a4b31.

📒 Files selected for processing (2)

• .gitignore
• shortcuts/register_test.go

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

• .gitignore
• shortcuts/register_test.go

---

📝 Walkthrough

Walkthrough

The docs create v2 path now accepts an optional --title, validates it, and prepends escaped title markup into generated content. Tests, help text, coverage notes, and reference docs were updated, and the legacy v1 title mapping was removed.

Changes

Docs create title flow

Layer / File(s)	Summary
Create v2 title handling shortcuts/doc/docs_create_v2.go, shortcuts/doc/v2_only.go	The v2 create path accepts --title, validates it, removes the legacy title mapping, and prefixes escaped title markup into request content.
Validation and help tests shortcuts/doc/doc_errors_test.go, shortcuts/doc/docs_create_test.go, shortcuts/register_test.go	Unit tests cover title-only validation, legacy v1 flag rejection, and the updated docs +create help output.
Dry-run body assertions shortcuts/doc/docs_fetch_v2_test.go, tests/cli_e2e/docs/docs_update_dryrun_test.go, tests/cli_e2e/docs/coverage.md	The dry-run create test parses JSON output and checks the escaped title prefix, and the coverage notes record the testcase and request shape.
Reference updates skills/lark-doc/references/*	The create, fetch, markdown, and XML references update title and --doc-format guidance and remove the old title-heading sections.

Automations ignore pattern

Layer / File(s)	Summary
Ignore automations directory .gitignore	.gitignore adds /automations/ to the ignore patterns.

Sequence Diagram(s)

sequenceDiagram
  participant "docs +create" as DocsCreate
  participant validateCreateV2
  participant buildCreateBody
  participant "/open-apis/docs_ai/v1/documents" as DocsDocumentsAPI
  DocsCreate->>validateCreateV2: --title, --content, --doc-format
  validateCreateV2-->>DocsCreate: validated inputs
  DocsCreate->>buildCreateBody: request inputs
  buildCreateBody->>DocsDocumentsAPI: body.content with escaped <title> prefix

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• larksuite/cli#1291: Same shortcuts/doc validation path and legacy flag handling in validateCreateV2 and v2_only.go.
• larksuite/cli#1346: Also changes validateCreateV2 and related validation tests in shortcuts/doc.
• larksuite/cli#1474: Updates the same skills/lark-doc references for docs +create title handling.

Suggested labels

documentation, feature

Suggested reviewers

• ViperCai

Poem

A rabbit tucked a title in a leafy little bow,
and slipped it into content where the tidy bytes go.
& twinkled softly in the burrow light,
while tests hopped along to keep it right. 🐇

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 11.76% 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 matches the main change: adding support for a create title option in docs v2.
Description check	✅ Passed	The description covers the summary, validation, and related items, but it omits the exact 'Changes'/'Test Plan' template headings.
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/support-doc-title-warning

---

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@66a4b3161054985eaebd7ebd50b434648dc50641

🧩 Skill update

npx skills add larksuite/cli#codex/support-doc-title-warning -y -g

[codecov]

Codecov Report

❌ Patch coverage is 80.00000% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 74.59%. Comparing base (1c92ed8) to head (66a4b31).
⚠️ Report is 2 commits behind head on main.

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

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1536      +/-   ##
==========================================
+ Coverage   74.53%   74.59%   +0.06%     
==========================================
  Files         792      793       +1     
  Lines       78690    79085     +395     
==========================================
+ Hits        58653    58997     +344     
- Misses      15670    15702      +32     
- Partials     4367     4386      +19     

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