refactor(sheets): sync spec — chart position/offset/size + sparkline split

[zhengzhijiej-tech]

同步 sheet-skill-spec 仓的 refactor 改动（对应 spec MR ee/sheet-skill-spec!3）。

本次范围（仅 reference 文档）

• skills/lark-sheets/references/lark-sheets-chart.md
  +chart-create / +chart-update 拎 6 个 scalar：
  --position-col / --position-row / --offset-col / --offset-row /
  --size-width / --size-height；--properties 收窄为只装 snapshot

• skills/lark-sheets/references/lark-sheets-sparkline.md
  +sparkline-create / +sparkline-update 把 --properties 拆成 --config

  • --sparklines；描述对齐 mcp-tools 新 schema（{config, sparklines[]}）

⚠️ Go 实现层尚未跟进

reference 文档已先行同步，但 shortcuts/sheets/lark_sheet_object_crud.go
里的 chartSpec / sparklineSpec 还没拆 flag——后续会单独提一个 PR 补 Go 代码：

• chart: 加 createExtraFlags + enhanceCreateInput（模仿 pivotSpec 写法）
• sparkline: --properties → --config + --sparklines（factory 扩展或全 hoist）

在 Go PR 合并前，新的 flag（--position-col 等 / --config / --sparklines）
实际不可用；文档已先描绘"目标形态"用于模型 prompt 对齐。

同步方式

在 spec 仓跑 npm run sync:consumers --only larksuite-cli，按
consumers/larksuite-cli.json mirror 到 skills/lark-sheets/。
本次提交仅保留与 spec MR!3 直接相关的 2 个 reference；其他文件即便
sync 时被 mirror，diff 也 reverted 回 origin/feat/lark-sheets-refactor。

Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com

Summary by CodeRabbit

• New Features

  • Added comprehensive workbook and sheet management commands including create, delete, rename, move, copy, hide, and tab color operations.
  • Added batch update capabilities for multi-range style operations and dropdown configurations.
  • Added object management shortcuts for charts, pivots, conditional formatting, filters, sparklines, and floating images.
  • Enhanced sheet operations with search/replace, range transformations, and dimension management.

• Documentation

  • Updated skill references with new operation guides and constraint documentation.

[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]

Caution

Review failed

Failed to post review comments

📝 Walkthrough

Walkthrough

Adds a new Sheets v2 tool-based shortcut suite (workbook, structure, read/write, range ops, search/replace, object list/CRUD, batch update), replaces legacy implementations, reorganizes registry, and updates docs. Extensive new unit/e2e tests validate dry-run/execute payloads, error propagation, and legacy flows.

Changes

Sheets shortcuts v2 and docs

Layer / File(s)	Summary
Core tool gateway (Sheet AI invoke) shortcuts/sheets/sheet_ai_api.go	Implements tool invoke path, request body building, dry-run metadata, and execute-time envelope decoding.
Shared helpers and test utilities shortcuts/sheets/helpers.go, shortcuts/sheets/helpers_test.go	Refactors token/sheet selector and style helpers; adds JSON flag parsers and common test harness.
Workbook and legacy workflows shortcuts/sheets/lark_sheet_workbook.go, shortcuts/sheets/lark_sheet_workbook_test.go	Adds workbook info/create/export and sheet operations; includes legacy create/export and lookup helpers with tests.
Sheet structure and dimensions shortcuts/sheets/lark_sheet_sheet_structure.go, ..._test.go	Adds sheet-info and dim operations plus legacy dim-move; range/index formatting and validations with tests.
Read data (cells, CSV, dropdown get) shortcuts/sheets/lark_sheet_read_data.go, ..._test.go	Adds cells-get, csv-get (row-prefix stripping), dropdown-get; include mapping and validations with tests.
Write cells (values, styles, CSV, dropdown set, image) shortcuts/sheets/lark_sheet_write_cells.go, ..._test.go	Adds cells-set, cells-set-style, csv-put, dropdown-set, and cells-set-image; utilities and tests.
Range operations (clear/merge/resize/move/copy/fill/sort) shortcuts/sheets/lark_sheet_range_operations.go, ..._test.go	Adds clear/merge/unmerge, row/col resize, move/copy/fill/sort with validations and tests.
Search and replace shortcuts/sheets/lark_sheet_search_replace.go, ..._test.go	Adds cells-search and cells-replace with options mapping; guard for required replace flag.
Objects: list and CRUD shortcuts/sheets/lark_sheet_object_list.go, ..._test.go, shortcuts/sheets/lark_sheet_object_crud.go, ..._test.go	Adds list and CRUD for chart/pivot/cond-format/filter/filter-view/sparkline/float-image; float-image flat flags; sheet-level filter helpers.
Batch update and dropdown/style batching shortcuts/sheets/lark_sheet_batch_update.go, ..._test.go	Adds batch-update passthrough, batch style set, dropdown update/delete with range validation and high-risk gating.
Shortcut registry reorganization shortcuts/sheets/shortcuts.go	Rebuilds registry to match new domain grouping.
End-to-end execute-path tests shortcuts/sheets/execute_paths_test.go	Adds e2e tests for tool paths, legacy flows, payload capture, and error surfaces.
Docs overhaul and references skills/lark-sheets/SKILL.md, skills/lark-sheets/references/*	Bumps spec to 2.0.0-draft; adds/updates references (core ops, charts, conditional format, filters, filter views, batch update, float image); removes legacy docs.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant User
  participant CLI
  participant ToolGateway
  participant OpenAPI
  participant Sheets

  User->>CLI: sheets +cells-set ... --dry-run/execute
  CLI->>ToolGateway: buildToolBody(tool_name, input)
  ToolGateway->>OpenAPI: POST invoke_write
  OpenAPI->>Sheets: route to set_cell_range
  Sheets-->>OpenAPI: envelope {code=0, data.output="<json>"}
  OpenAPI-->>ToolGateway: envelope
  ToolGateway-->>CLI: decode output / error

Loading

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~120 minutes

Possibly related PRs

• larksuite/cli#413: Earlier dimension operations; overlaps with new dim insert/delete/move behaviors.
• larksuite/cli#633: Introduced high-risk confirmation gating used by new delete/batch-update shortcuts.
• larksuite/cli#461: Prior dropdown shortcuts replaced by the new dropdown get/set/update/delete suite.

Suggested labels

domain/ccm, size/S

Suggested reviewers

• fangshuyu-768

Poem

A rabbit taps cells in tidy rows,
Batches hop—then safely close.
Charts bloom, filters breeze,
Styles drift like leaves on trees.
Old trails fade; new paths gleam—
Sheets now sing a v2 dream. 🐇✨

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

⚔️ Resolve merge conflicts

• Resolve merge conflict in branch refactor/sync-spec-chart-and-sparkline