feat(sheets): add +formula-verify shortcut for verify_formula tool

[wenzhuozhen]

Summary

把 sheet-skill-spec/canonical-spec/tool-schemas/tools-schema.json 新加的 verify_formula 工具落地为 lark-cli 薄壳 shortcut +formula-verify（read scope，invoke_read），供 AI 在批量公式写入（+cells-set / +csv-put / +batch-update / +workbook-import 等）之后做 R10 zero-error 自检。

PRD: https://bytedance.larkoffice.com/docx/DetAdncvKo0okNx7A08cVyeRngf

Changes

• shortcuts/sheets/data/flag-defs.json: 新增 +formula-verify 命令 flag 定义
  • --url / --spreadsheet-token (XOR)
  • --sheet-id / --sheet-name（各自 string_slice，可重复或逗号分隔；两者互斥；都不传 = 扫描全部可见子表）
  • --range（string_slice，可多段）
  • --error-type（enum string_slice，限定 #REF! / #DIV/0! / #VALUE! / #NAME? / #NULL! / #NUM! / #N/A）
  • --max-locations（int，default 20）
  • --cell-limit（int，default 50000）
  • --exit-on-error（bool）
• shortcuts/sheets/flag_defs_gen.go: go generate 重新生成
• shortcuts/sheets/lark_sheet_formula_verify.go: FormulaVerify shortcut 实现，把 CLI flag 翻成 verify_formula 工具入参；调 AIService.OpenAPIToolCallRead；--exit-on-error 状态映射 → success / partial 静默通过，errors_found 转 errs.SubtypeFailedPrecondition 验证错误（带 hint 引导调用方修公式 / IFERROR 兜底后重跑），未知 status 转 SubtypeInvalidResponse 内部错误（避免静默零退出）
• shortcuts/sheets/shortcuts.go: 注册 FormulaVerify，挂在 lark_sheet_search_replace 之后
• shortcuts/sheets/lark_sheet_formula_verify_test.go: 单测覆盖 dry-run wire 形态、selector 互斥、cap > 0 守卫、exit-on-error 状态矩阵（success / partial / errors_found / unknown / non-object）的 typed-error 断言
• tests/cli_e2e/sheets/sheets_formula_verify_dryrun_test.go: 通过外部 lark-cli 二进制做 dry-run 端到端校验

Test Plan

• go test -race -count=1 ./shortcuts/... 全绿（含新增单测）
• go test -run TestSheets_FormulaVerify ./tests/cli_e2e/sheets/... 全绿（dry-run E2E）
• go vet ./... 干净
• gofmt -l . 干净
• go mod tidy 无 diff
• Live E2E：依赖 upstream BE-1 (sheet.node.cmd_api 落地 VerifyFormula handler) + BE-2 (sheet.facade.agg 注册 ToolName 路由) merge 后再跑

Related Issues

• 上游依赖：sheet-skill-spec MR https://code.byted.org/ee/sheet-skill-spec/merge_requests/39（`verify_formula` schema + lark_sheet_formula_verify skill + R10 自检铁律）
• spec 单页：docs/specs/verify-formula-spec/spec.md（在 cli 仓本地）

Summary by CodeRabbit

• New Features

  • Added a new spreadsheet formula-checking command with support for selecting specific sheets, ranges, and error types.
  • Added options to limit scan size, sample locations per error, and exit with a non-zero status when issues are found.

• Bug Fixes

  • Improved validation for conflicting sheet selectors and invalid limit values.
  • Better handling of command output statuses, including partial and error-found results.

• Tests

  • Added coverage for dry runs, input validation, and exit-status behavior.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[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: 1990a68d-e6f1-4d5c-9eaf-5437edfa10cf

📥 Commits

Reviewing files that changed from the base of the PR and between 8a268aa and 61e15e6.

📒 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
• shortcuts/sheets/shortcuts.go
• tests/cli_e2e/sheets/sheets_formula_verify_dryrun_test.go

---

📝 Walkthrough

Walkthrough

+formula-verify adds Sheets shortcut flags, registers the shortcut, validates selector and limit inputs, builds verify_formula requests from CLI flags, and maps tool statuses to CLI exit behavior. Tests cover dry-run requests, selector validation, and response handling.

Changes

Sheets formula verification

Layer / File(s)	Summary
Flag contract and registration shortcuts/sheets/data/flag-defs.json, shortcuts/sheets/flag_defs_gen.go, shortcuts/sheets/shortcuts.go	+formula-verify adds sheet selectors, ranges, error-type filters, scan limits, and --exit-on-error to the Sheets flag schema, generated definitions, and shortcut registration.
Shortcut validation and request shaping shortcuts/sheets/lark_sheet_formula_verify.go, shortcuts/sheets/lark_sheet_formula_verify_test.go, tests/cli_e2e/sheets/sheets_formula_verify_dryrun_test.go	The shortcut validates selector exclusivity and positive limits, normalizes repeated sheet selectors, and builds the verify_formula request payload; unit and e2e tests cover dry-run requests and CLI validation errors.
Exit-on-error status handling shortcuts/sheets/lark_sheet_formula_verify.go, shortcuts/sheets/lark_sheet_formula_verify_test.go	formulaVerifyExitOnError maps verify_formula output statuses to success, validation errors, or internal errors, and tests cover success, partial, errors_found, and invalid responses.

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant FormulaVerify
  participant invoke_read
  CLI->>FormulaVerify: +formula-verify flags
  FormulaVerify->>invoke_read: POST /tools/invoke_read with verify_formula payload
  invoke_read-->>FormulaVerify: status and output
  FormulaVerify-->>CLI: stdout and exit code

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• larksuite/cli#1348 — introduces the typed Sheets error handling shape that formulaVerifyExitOnError uses for validation and internal response errors.

Suggested labels

feature, size/L

Suggested reviewers

• xiongyuanwen-byted
• caojie0621

Poem

A bunny hopped by moonlit code,
and found a formula-verify road.
With sheets to scan and errors to name,
it bounded forth in CLI flame.
🐇✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: adding the +formula-verify shortcut for the verify_formula tool.
Description check	✅ Passed	The description follows the required template and includes summary, changes, test plan, and related issues with enough detail.
Docstring Coverage	✅ Passed	Docstring coverage is 92.31% 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/sheets-formula-verify

---

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

[codecov]

Codecov Report

❌ Patch coverage is 79.51807% with 17 lines in your changes missing coverage. Please review.
✅ Project coverage is 74.65%. Comparing base (d9330b7) to head (61e15e6).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
shortcuts/sheets/lark_sheet_formula_verify.go	79.26%	14 Missing and 3 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1626      +/-   ##
==========================================
- Coverage   74.66%   74.65%   -0.02%     
==========================================
  Files         804      807       +3     
  Lines       81032    81469     +437     
==========================================
+ Hits        60501    60818     +317     
- Misses      16029    16115      +86     
- Partials     4502     4536      +34     

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

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@61e15e6893d9a3b9278bdf56b0be9b3c09f57b54

🧩 Skill update

npx skills add larksuite/cli#feat/sheets-formula-verify -y -g