feat(sheets): add --ai-only to +formula-verify for AI formula status

[wenzhuozhen]

Summary

Add a --ai-only mode to sheets +formula-verify so agents can check the compute status of asynchronous AI formulas (AI_WRITE / AI_CLASSIFY / AI_SENTIMENT / AI_EXTRACT / AI_POLISH / AI_SUMMARY / AI_TRANSLATE), and enrich the lark-sheets skill docs with AI-formula parameter details and clearer verify guidance.

Changes

• sheets +formula-verify: add --ai-only flag, mapped to the verify_formula tool input ai_only=true. It skips the ordinary 7-Excel-error scan and returns the current AI-formula compute status; a single call is a status probe and coexists with --sheet-id / --sheet-name / --range, honoring --exit-on-error.
• Regenerate flag_defs_gen.go and add dry-run cases for --ai-only.
• Skill docs (mirrored from the sheet-skill-spec canonical source):
  • lark-sheets-formula-translation: full AI-function parameter details — range rules, AI_TRANSLATE language keys, AI_EXTRACT extract-type, AI_CLASSIFY three modes, AI_INFER / AI_IMPORTDATA array semantics.
  • lark-sheets-formula-verify: clarify --ai-only convergence expectation (small batches resolve quickly; pending on large batches is normal) and drop implementation-leaking phrasing.

Test Plan

• Unit tests pass (go test ./shortcuts/sheets/ -run 'TestFormulaVerify|FlagDef')
• Manual local verification confirms the lark-cli sheets +formula-verify --ai-only flow works end-to-end against a real spreadsheet (returns ai_formula_total / done / pending / failed + status)

Related Issues

• None

Summary by CodeRabbit

• New Features

  • Added an --ai-only option to formula verification.
  • Check the current computation status of AI formulas without scanning standard spreadsheet errors.
  • Combine AI-only verification with sheet and range filters.
  • Supports asynchronous polling while AI formulas finish computing.

• Documentation

  • Added guidance on supported AI formulas, parameters, language keys, verification statuses, and polling workflows.
  • Clarified usage examples and automation options for AI formula verification.

[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: 6ed62283-9606-49ec-8216-8ce252c4b950

📥 Commits

Reviewing files that changed from the base of the PR and between 6ff1022 and d5e4694.

📒 Files selected for processing (6)

• shortcuts/sheets/data/flag-defs.json
• shortcuts/sheets/flag_defs_gen.go
• shortcuts/sheets/lark_sheet_formula_verify.go
• shortcuts/sheets/lark_sheet_formula_verify_test.go
• skills/lark-sheets/references/lark-sheets-formula-translation.md
• skills/lark-sheets/references/lark-sheets-formula-verify.md

---

📝 Walkthrough

Walkthrough

The +formula-verify shortcut now supports --ai-only, forwarding ai_only: true for asynchronous AI formula status checks. Tests cover standalone and range-scoped requests, while reference documentation describes AI formula parameters and polling behavior.

Changes

AI formula verification

Layer / File(s)	Summary
CLI flag and request wiring shortcuts/sheets/data/flag-defs.json, shortcuts/sheets/flag_defs_gen.go, shortcuts/sheets/lark_sheet_formula_verify.go, shortcuts/sheets/lark_sheet_formula_verify_test.go	Adds the optional --ai-only flag, forwards ai_only: true to verify_formula, and tests standalone and range-scoped request payloads.
AI formula usage and verification documentation skills/lark-sheets/references/lark-sheets-formula-translation.md, skills/lark-sheets/references/lark-sheets-formula-verify.md	Documents AI formula signatures, language keys, asynchronous computation, polling status, selectors, and exit behavior.

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

Sequence Diagram(s)

sequenceDiagram
  participant FormulaVerifyCLI
  participant formulaVerifyInput
  participant verify_formula
  FormulaVerifyCLI->>formulaVerifyInput: parse --ai-only and selectors
  formulaVerifyInput->>verify_formula: send ai_only=true and optional ranges
  verify_formula-->>FormulaVerifyCLI: return current AI formula status

Loading

Possibly related PRs

• larksuite/cli#1626: Introduced the +formula-verify implementation extended by this change.
• larksuite/cli#1833: Earlier work on the same +formula-verify shortcut and related wiring.

Suggested labels: size/L

Suggested reviewers: liangshuo-1

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding --ai-only to +formula-verify for AI formula status.
Description check	✅ Passed	The description matches the template with Summary, Changes, Test Plan, and Related Issues sections filled in.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
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 docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/lark-sheets-develop-ai-formula

---

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

🧩 Skill update

npx skills add larksuite/cli#feat/lark-sheets-develop-ai-formula -y -g