6 Commits

Author	SHA1	Message	Date
chendaxin-tk	5a72b989c1	feat(sheets): accept the --range / --cells / border shapes callers actually send (#2338) ... * feat(sheets): read a sheet prefix in --range as the sheet selector Eval traces: 707 calls to +cells-get / +csv-get / +csv-put / +cells-set / +cells-clear died on "specify at least one of --sheet-id or --sheet-name", and 53% of them had already named the sheet inside --range ("Sheet1!A1:D20"). The sheet was known, only the flag was missing — so the prefix now fills the selector and the bare A1 range goes to the tool. Wired on both paths: a PreRunE stage in the sheets ergonomics layer for standalone commands, and the sub-op translator for +batch-update. The grammar follows the front-end ref lexer (byted-sheet TractorLexer): the full-width ！ is an equal separator, an unquoted name can contain neither width (so splitting on the first one is safe), and a quoted name keeps its doubled-quote escape and may itself contain a "!". Unquoted names with spaces are accepted here though the lexer rejects them — a --range flag has none of a formula's tokenizing ambiguity. sheetNameFromA1 delegates to the same splitter instead of carrying a second, looser grammar. Scope guards: an explicit --sheet-id / --sheet-name stays authoritative and --range passes through untouched, so a disagreeing prefix cannot silently retarget a write; only --range carries the rewrite, since +range-copy / +range-move / +range-fill name their destination sheet with --target-sheet-id. * fix(sheets): 边框粗细词兜底补齐 hair 与数字线宽 07-28 只修了 border_styles.<side>.style 里的 thin/medium/thick，同族的另外两种 写法仍在报错。对 596 条 trace 做频次统计，边框取值的错法就这几种： weight 槽 "hair" 476 次 / 19 个用例 ← 本次新增 style 槽 "thin" 1795 次 / 39 个用例 （07-28 已修） style 槽 "hair" 76 次 / 2 个用例 ← 本次新增 weight 槽 数字 10 次 / 2 个用例 ← 本次新增（07-28 报告 Case 2） width 键（GSheets） 35 次 / 3 个用例 ← 本次新增 根因是契约把一个视觉概念拆成 style（线型）× weight（粗细）两个字段，而 openpyxl 把两者塞进一个词 Side(border_style="thin")，于是同几个粗细词在两个槽位都会出现。 borderWeightWord 一个函数同时服务两个槽位，挂在 expandBorderAllShorthand 这个唯一 漏斗上，四条载体路径（--border-styles / --cells 内联 / --styles 载荷 / +workbook-create）一起生效。 weight 先于 style 归一是有意的：{"style":"thin","weight":"1"} 只有等 "1" 先变成 "thin"，style 那步才看得出显式 weight 与词义一致而非冲突。显式冲突 （thin + thick）保持报错，不替用户选。 刻意不收：openpyxl 完整线型表（dashDot / mediumDashed / slantDashDot）、VBA xlContinuous、CSS hidden、Google Sheets SOLID_THICK、line_style / thickness 等 键别名、style 与 weight 装反、px/pt 后缀 —— trace 里全是 0 次；solid_thin、 border_width、border_color 各只有 1 个用例。它们继续走 enum 报错（报错带允许值 和 did-you-mean，一轮能改对），符合本文件顶部的静默别名准入门槛：真实词汇 **且** 跨批次/≥3 任务复现。新增用例里有一条反向断言把这条线钉住。 TestCellsSetStyle_BorderWeightNumberNamesEnum 的探针从数字换成布尔——数字现在会被 归一化，不再走报错路径，enum-over-skeleton 那条文案规则改用布尔来钉。 * feat(sheets): accept the openpyxl-habit --cells shapes and prescribe the rest The --cells shape family is the single largest client-side rejection cluster for +cells-set in the eval corpus. Traced against 14,024 real calls it splits into two habits, and each gets the treatment its ambiguity allows. Accepted outright, both unambiguous, both on the existing jsonFlagNormalizers seam (so --writes items and +batch-update sub-ops get them too): - {"cells": […]} envelope — an agent generating the payload in a script writes json.dump({"cells": cells}, f), mistaking the flag name for a JSON key. 11 of 21 traced `expected type "array", got "object"` rejections are this exact shape. Only a lone "cells" key unwraps; siblings mean the object is the whole tool input and dropping them would write elsewhere. - bare scalars in cell slots — the openpyxl / gspread habit of passing a plain values matrix, which real rows mix with cell objects as soon as a formula appears (["1","电动大门",10331.00,{"formula":"=D2*E2"}]). null is deliberately left failing: {} (leave the cell alone) and {"value":""} (write an empty string) are both plausible readings, and the normalizer only rewrites what is beyond doubt. Renamed silently on the same grounds: --values is what gspread calls the payload, and what this CLI's own +workbook-create calls its untyped 2D data. Because bare scalars now lift into {"value":…}, the plain matrix a --values caller passes ('[["工作内容"]]') is already accepted verbatim under --cells — the name was the only thing wrong, which puts it in commandFlagAliases rather than the prescription table. That drops the round trip a prescription costs (eval F8: 170 hits, 1.9% of failures) and covers the +batch-update sub-op path, which reads the same alias table and would otherwise get no hint at all (a prescription only rides on cobra's unknown-flag branch). Inferred, matching the libraries these callers arrive from: a bare single-cell --range is now an anchor, sized from the payload — the same inference +csv-put already does for --start-cell. The range resolves locally and ships in full, so the server still gets the strict match it enforces. An explicit extent ("A1:A1", "A1:C10") is never inferred over. Prescribed, because it cannot be guessed safely: the cells-vs-range mismatch (132 rejections across 93 case-runs) now reports both axes at once and hands back the range that fits the payload, plus the inclusive-end note that explains its biggest sub-bucket — A1:C10 being 10 rows. Growing the range would overwrite rows the caller never mentioned and shrinking it would drop data, so the choice stays with the caller. Ragged rows get their own message instead of being reported as a range mismatch. Supporting refactor: parseCellRange replaces the prefix-strip / split-on-":" / splitCellRef triplication (rangeDimensions becomes a thin wrapper, its error wording kept byte-for-byte since +styles-put surfaces it verbatim), and cellsExtent is the one authority on whether a payload is rectangular, so the anchor expansion and the dimension check cannot disagree. Two bugs fell out of the new tests: a leading space before the sheet name survived into every rendered range, and a payload of empty rows would have rendered a malformed suggestion. * fix(sheets): parse the sheet part of a range with the ref lexer's grammar parseCellRange cut the sheet off with strings.Index(range, "!"), which disagrees with the grammar splitRangeSheetPrefix already implements from the front-end ref lexer (byted-sheet TractorLexer.ts). Two spellings the lexer treats as ordinary therefore failed to parse at all: --range '甘特图！B3' full-width separator (ExclamationMark accepts it) --range "'Q1!Actual'!B3" quoted name owning a "!" (quotes delimit, so it may) An unparsable range is deliberately deferred ("the range validator's job"), so the failure was silent in both directions: the anchor never expanded and the dimension mismatch never got its prescription. Reachable whenever the prefix survives to the shortcut — an explicit --sheet-id/--sheet-name keeps it (the selector rewrite only fires when the pair is empty), as do --source-range / --target-range, which that rewrite deliberately skips. The grammar now lives in one place. scanSheetQualifier reports the parsed sheet name AND the byte offset just past the separator; splitRangeSheetPrefix is rewritten on top of it (all 20 of its grammar cases unchanged), and parseCellRange slices the qualifier off at that offset. The offset is the point: a range rendered from a parse is both shipped to the server and printed for the caller to paste back, so the qualifier has to survive verbatim — quotes, full-width separator and all — which a name parsed and re-quoted could not promise. Naming, while here: cellRange.prefix said where the field sits, not what it holds. It is now sheetQualifier (verbatim, separator included) alongside sheetName (parsed, unquoted) — the sheet a range names is what the type is about, and the next caller that needs it should not reach for the raw string. * fix(sheets): close the four gaps the PR review found Anchor expansion no longer sizes a sheet-qualified range. Such a range only reaches expandAnchorRange beside an explicit --sheet-id / --sheet-name, since all three entry points fold the prefix into the selector when none was given — so the prefix is one that disagrees with the selector, and sizing it shipped {"range":"Sheet1!A1:B2","sheet_name":"Other"} where the pre-anchor CLI had failed locally with the cells-vs-range mismatch. Trading a local prescription for a wire payload whose two halves name different sheets is the wrong direction; a qualified anchor stays a mismatch. --writes items now really do get the payload rewrites. cellsSetWritesOps gives each item the standalone pipeline through a per-item flag view, but that runs after requireJSONArray has validated the array, so an item spelling its payload "values" or wrapping it in a {"cells": …} envelope died on the array schema while the identical +batch-update sub-op was accepted. The rewrites move onto the jsonFlagNormalizers seam for --writes, one step ahead of the schema, so the two spellings of the same write agree. values → cells only when "cells" is absent: two spellings with different payloads stays normalizeSubOpInputKeys' conflict to report. The derived selector is left as the only spelling of itself. normalizeSubOpInputKeys keeps a duplicate key whose two values agree rather than erroring, and two empty strings agree — so an input carrying both "sheet-name":"" and "sheet_name":"" kept the hyphen form, which lookupRaw finds first and which then shadowed the sheet_name just derived from the range prefix, failing as "specify at least one of --sheet-id or --sheet-name". Test coverage the review asked for: a +batch-update dry-run case for the prefix rewrite (the sub-op path had unit coverage but no E2E), and the two tests that grepped a rendered envelope now decode the dry-run body and assert the fields that reach the wire. * test(sheets): cover the accepted input shapes against a real spreadsheet The dry-run E2E pins what the CLI builds; nothing pinned that the backend takes it. That gap matters more for rewrites than for ordinary flags: each one turns a caller spelling into a wire payload the caller never sees, so a payload the server rejects would be a worse outcome than the client-side error it replaced. TestSheets_CallCompatWorkflow writes through a sheet-qualified --range with no selector flag at all, with bare scalars in the cell slots and a bare A1 acting as an anchor — three rewrites composed in one call — then reads back through the same prefix and stamps an openpyxl "hair" border over the result. The sheet is named with a space in it so the prefix takes its quoted form, the spelling the ref-lexer grammar exists for and the one a first-ASCII-"!" split would cut in half. The read-back compares values collected out of the decoded payload rather than a fixed path: get_cell_ranges' response nesting is the backend's to change and is pinned nowhere in this repo, while the values having survived the round trip is the actual claim. The number is compared numerically for the same reason. Self-contained: it builds its own workbook, and createSpreadsheet's cleanup tears it down. Skips without tenant credentials, so local runs are unaffected and CI's e2e-live job is what exercises it. * feat(sheets): answer +sheet-list instead of failing the guess Callers reach for +sheet-list on their own: the sheets surface has a whole +sheet-* family (+sheet-create / +sheet-copy / +sheet-delete / +sheet-info), so "list the sheets" spells itself that way. The miss does not self-correct either, because internal/suggest ranks shared prefixes first: the "did you mean" hint points at +sheet-create and its siblings, never at +workbook-info. Add it as a read-only projection over get_workbook_structure emitting the bare sheets array, entry-for-entry identical to what +workbook-info nests under sheets. Hidden from `sheets --help` here, and from the lark-sheets skill docs via sheet-skill-spec's doc_hidden_shortcuts, so neither surface offers a second name for what +workbook-info already does; the command only ever answers a caller who typed it anyway. data/flag-defs.json and flag_defs_gen.go carry the new shortcut's flag entry, sourced from sheet-skill-spec's spec-tables. * feat(sheets): prescribe the real command for invented subcommand names Callers reach for subcommand names this CLI does not have, borrowed from neighbouring ecosystems. The framework answers an unknown name by edit distance over the group's children; that ranking is prefix-weighted, so it cannot settle a name whose answer shares no prefix with it, or one whose same-prefix siblings crowd the answer out. Those names now get a curated prescription instead: the command they meant plus its exact retry form, so the next attempt needs no --help round trip. Prescribed, never rewritten. Unlike a flag, silently resolving a subcommand would run a write the caller never named, and the same information fits in the error the failed call already returns. Every entry is a naming miss rather than a missing capability — each intent already has a command — and a rare spelling stays with the ranker rather than growing the table. The hook is the group's Args validator, which cobra runs before the group's RunE. That ordering is what keeps this inside sheets: the framework's unknown-subcommand guard installs on RunE and never touches Args, so the two compose and every unclaimed name still reaches the ranked "did you mean one of: …" unchanged. The message stays byte-identical to the guard's, since the name genuinely does not exist; only the hint and the machine-readable suggestion change. Targets resolve against the live tree rather than the table. All of them are write commands, so a concealed distribution or a user policy of max_risk: read replaces one with a hidden deny stub; prescribing it then would name a command that can only answer command_unavailable, and that the ranker has already stopped suggesting. The check mirrors the ranker's filter, and doubles as a runtime backstop when a target vanishes in a rename. Known gap: +batch-update validates sub-op shortcut names against its own allow-list, so an invented name inside --operations still gets the generic "not allowed" dump instead of the prescription. Tests pin the two invariants that make the table safe to extend — a target must exist, and a key must not shadow a real command (checked against backward's aliases too, which mount on the same group) — plus the registration itself, so deleting the wiring fails the suite instead of silently reverting the CLI to generic suggestions. * fix(sheets): keep a non-finite line width off the thickness mapping strconv.ParseFloat answers yes to "Inf" / "Infinity" / "NaN", so a quoted non-finite weight entered the numeric-width branch and came back out as "thick" with exit 0 — the CLI guessing at input that means nothing. NaN only escaped that by accident (every comparison against it is false). borderLineWidth now reports a non-finite result as "not a width", which puts both back on the enum error path that names thin / medium / thick. Also closes the review's test-coverage gaps: hair in the style slot pins the canonical style ("solid") next to the weight in both the corpus and the dry-run e2e, the numeric-width table gains its two ends (3 is where thick starts, 0 keeps its own type error), and splitRangeSheetPrefix covers the backslash-escaped separator after a quoted name. * fix(sheets): parse --ranges prefixes with the shared grammar, budget every cells shape Three gaps the review found, each reproduced against a built binary first. --ranges kept its own strings.Index("!") splitter, so the four separator spellings the rest of the PR unified on stopped at the flag boundary: "工作表1！A1:B2" was rejected as carrying no sheet prefix at all, and "'My Sheet'!A1:B2" shipped sheet_name "'My Sheet'" — quotes included — for the backend to fail on as sheet-not-found. Both the up-front prefix check and splitSheetPrefixedRange now go through scanSheetQualifier / splitRangeSheetPrefix, which keeps the two error messages' division of labour: no qualifier at all is "must include a sheet prefix", an empty side is "must use sheet!range form". estimatedBatchOpCells ran before the translator's normalizers but read the wire shape only, so a {"cells": …} envelope, a lone cell object, and a payload spelled "values" each scored zero cells and materialized outside the batch-wide safety budget. It unwraps the shape now — no mutation, the per-cell rewrites stay the translator's and change no count. sheetNameFromA1 lost "Sheet1!" when it moved onto splitRangeSheetPrefix, which requires a non-empty range; a prefix with no range still names a sheet, and pivotPlacementWarn is more use naming it than falling back to the generic wording. It reads the qualifier directly instead. * fix(sheets): make the +cells-put prescription validate, and type the range assertions The +cells-put hint replaces the ranked candidate list, so it is the whole of what a caller gets back — and it prescribed a 1×2 matrix against A1:B2, which fails the cells-vs-range check the same call would hit, plus prose forbidding the bare scalars this branch now accepts. It spells a matching 2×2 scalar matrix and both accepted cell forms instead. TestPrescribedExamplesActuallyValidate pulls the flags back out of the hint and runs them through +cells-set, so the prose cannot drift from what the validator takes; restoring the old hint fails it with the very error the caller would have seen. splitSheetPrefixedRange's rejection cases asserted only that an error came back, which an untyped one would satisfy. They now go through requireValidation and pin the --range attribution and the offending input in the message.	2026-08-14 17:43:30 +08:00
xiongyuanwen-byted	be2a96f490	feat(sheets): harden error prescriptions, batch updates, and read workflows ... Aggregate the sheets work from feat/lark-sheets-develop: - Improve validation errors with schema hints, aggregated issues, enum guidance, and prescriptive flag/style-field messages. - Harden +batch-update input contracts, key normalization, style vocabulary handling, and resource-budget checks. - Add read offload and truncation handling for cells, csv, and table-get, with typed output-path errors and safer jq/output-path semantics. - Correct freeze semantics by emitting full-state freeze/unfreeze operations and adding --rows/--cols for +dim-freeze. - Improve +styles-put and shared --styles parsing for styles, merges, row/column sizing, freeze, and sheet-prefixed range validation. - Fix dim-insert inherit-style mapping, table-get date/time handling, table-put style anchors, and CSV path-shaped input guards. - Update lark-sheets skill docs, scripts, tests, and generated flag data. Tested with: - go test ./shortcuts/common ./shortcuts/sheets/... - go test ./shortcuts/... ./internal/... - python3 -m py_compile skills/lark-sheets/scripts/*.py	2026-08-07 11:21:12 +08:00
wenzhuozhen	69459321dd	feat(sheets): add ai formula verify (#1959) ... * feat(sheets): add --ai-only to +formula-verify for AI formula status polling BE-2: +formula-verify gains --ai-only, mapping to verify_formula tool input ai_only=true. AI formulas (AI_WRITE / AI_CLASSIFY / …) compute asynchronously; --ai-only is a single-shot polling probe (no built-in wait/timeout) that skips the ordinary 7-Excel-error scan and returns current AI-formula compute status. Coexists with --sheet-id/--range and honors --exit-on-error. BE-4: mirror sheet-skill-spec SoT docs (AI formula list in lark-sheets-formula-translation, --ai-only + async polling section in lark-sheets-formula-verify) and regenerate flag_defs_gen.go. Spec source: active@6fe4ea7389c6d0631dc8279ee7506c357d0600325e28ffabdc97d9a66339e762 * docs(sheets): mirror enriched AI formula params + --ai-only verify wording Mirror from sheet-skill-spec SoT (ee/sheet-skill-spec MR!55): - formula-translation: full AI function param details (range rules, AI_TRANSLATE language keys, AI_EXTRACT type, AI_CLASSIFY modes, AI_INFER/AI_IMPORTDATA array semantics) - formula-verify: clarify --ai-only convergence expectation, drop implementation-leaking phrasing * docs(sheets): mirror unified AI() formula docs from spec Sync the lark-sheets AI formula skill from sheet-skill-spec (SoT) after the product change that merges all AI formulas into one AI() function: - formula-translation reference: single =AI(prompt, [range]) function with syntax (incl. variadic =AI(part1, part2, ...) concatenation), per-case usage table (translate / sentiment / classify / extract / summarize / rewrite / generate / cleanup / keywords / multi-cell prompt), and prompt best practices - formula-verify reference + --ai-only flag def: unified AI() wording - flag_defs_gen.go regenerated from flag-defs.json - lark_sheet_formula_verify.go: drop stale AI_WRITE / AI_CLASSIFY names in the ai_only comment, reference the unified AI() function * docs(sheets): sync lark-sheets skill from spec Mirror the lark-sheets generated artifacts from sheet-skill-spec dwc/lark-sheet-ai: - update AI formula verification delivery guidance - add read-data inspection/profile helper scripts - refresh generated flag definitions for +formula-verify --ai-only * docs(sheets): sync updated AI formula guidance Mirror the latest lark-sheets generated docs from sheet-skill-spec dwc/lark-sheet-ai after c292420: - clarify that #ERROR/readback issues can be formula-write escaping failures rather than AI compute failures - recommend +cells-set JSON formula writes for AI() formulas containing commas and quotes - document <=1000-row serial batching for AI formula copy-to-range workflows * docs(sheets): add license headers to helper scripts Add the repository-standard copyright and SPDX headers to the generated lark-sheets helper scripts so the license-header check passes. * docs(sheets): regenerate sheet flag defs Regenerate shortcuts/sheets/flag_defs_gen.go after the latest sheet-skill-spec sync updated flag-defs.json. * docs(sheets): revert lark-sheets skill sync	2026-08-06 17:20:00 +08:00
zhengzhijiej-tech	e79d49e7e4	Merge lark sheets development branch (#1833) ... * feat(sheets): support font_family in cell styles (#1549) Add a font_family field to cell_styles so a cell's font name can be set and read back through every style entry point: - +cells-set (--cells JSON) and +cells-set-style / +cells-batch-set-style gain a font_family field / --font-family flat flag - +workbook-create / +table-put --styles accept font_family in cell_styles - +cells-get returns font_family helpers.go buildCellStyleFromFlags reads the --font-family flag; lark_sheet_workbook.go allows font_family in the --styles cell_styles whitelist; data/ + skills/ are synced from sheet-skill-spec. * docs(sheets): inline editing rules into SKILL.md and clarify flag descriptions - Move cross-cutting editing rules and execution notes into the root SKILL.md and drop the now-redundant core-operations reference - Clarify flag descriptions: offset must be explicit inside +batch-update, range prefixes written bare (no quotes), chart requires a dim index, untyped --values lose date/number types, ungroup level semantics - Sync the corresponding reference docs * feat(sheets): add --type bitable to +sheet-create for creating bitable sub-sheets (#1520) * perf(sheets): cap fan-out cell-matrix materialization to prevent OOM (#1578) * perf(sheets): cap fan-out cell-matrix materialization to prevent OOM The +cells-set-style / +dropdown-set / +cells-batch-set-style / +dropdown-update shortcuts expand a single A1 range into a rows×cols matrix of per-cell maps client-side (the backing set_cell_range tool takes an explicit cells matrix). rangeDimensions() had no upper bound, so a tiny input like "A1:Z100000" balloons into ~2.6M heap maps (~900MB, doubled again by json.Marshal) and can OOM the process before the request is even sent. Add a 50000-cell safety cap (checkStampMatrixBudget) gating every fan-out materialization point, matching the documented but never-wired --max-cells default. Oversized ranges now fail fast with a clear validation error instead of allocating. Also preallocate the per-op slices now that the range count is known up front. Adds benchmarks + a boundary test as regression guards. * perf(sheets): cap table-put/batch fan-out materialization (siblings of the cell-matrix cap) The single-range fan-out cap (maxStampMatrixCells) left three sibling ingress paths uncapped, each able to materialize an unbounded matrix or op set in memory before the request leaves: - +table-put / +workbook-create --sheets/--values: buildSheetMatrix builds the whole rows×cols matrix before slicing it into per-write batches; tablePutMaxCellsPerWrite only bounds the batch size, not the total input. Add tablePayload.checkCellBudget (1M-cell guardrail), enforced in validate() and in buildValuesPayload (the --values path bypasses validate()). - batch fan-out (+cells-batch-set-style / +dropdown-update): per-range checkStampMatrixBudget can't stop many ranges from summing past the cap. Add an aggregate cell budget (checkBatchStampBudget) and a shared maxBatchRanges (100) count cap in validateDropdownRanges — covering all fan-out commands and replacing the now-redundant +dropdown-delete count check. - +batch-update: cap --operations at maxBatchOperations (100) in translateBatchOperations. Adds boundary regression tests for each cap. go vet + gofmt clean; full shortcuts/sheets + backward suites green. * test(sheets): measure table-put matrix materialization cost Add BenchmarkBuildSheetMatrix_* and TestTablePutMatrixPeakMemory mirroring the fan-out probes. Confirms the +table-put/+workbook-create ingress has the same OOM profile as the single-range stamp: 2.6M cells → ~917 MB / 5.3M allocs (+875 MB resident heap) materialized before the first write — now rejected up front by checkCellBudget. * feat(pivot): lark-sheets pivot reference 补 +pivot-list info 说明与落点覆盖校验 +pivot-list 返回 info（page_range/content_range/error_state 等）： 1) 判断目标单元格在透视表内(改配置 +pivot-update)还是区域外(改值 +cells-set)； 2) 透视表展开后会覆盖已有数据，落点强烈优先默认自动新建子表； 3) 创建后用 info.error_state / content_range 校验有没有覆盖/冲突。 * feat(sheets): add +formula-verify shortcut for verify_formula tool Wraps the new verify_formula read tool in a CLI shortcut so AI agents can run write-then-zero-error verification end-to-end: lark-cli sheets +formula-verify --url <url> Scans formulas + cell error states across one or more sub-sheets and returns a JSON status report (success / errors_found / partial). Aggregates all 7 Excel error categories (#REF! / #DIV/0! / #VALUE! / #NAME? / #NULL! / #NUM! / #N/A) plus compile failures into one envelope; the tool always reports every error in the scan window — callers needing a subset filter the returned error_summary client-side. The internal scan cap is hidden from callers; when it trips the response sets has_more=true and includes a warning_message asking the caller to narrow --range / split --sheet-id and continue. Flags follow the lark-sheets convention: - --url / --spreadsheet-token (XOR public) - --sheet-id / --sheet-name (repeat or comma-separate; mutually exclusive) - --range (repeatable A1) - --max-locations (default 20) - --exit-on-error (CI gate: status='errors_found' → exit 2 with failed_precondition) Generated artifacts (skills/lark-sheets/{SKILL.md, references/ lark-sheets-formula-verify.md}, shortcuts/sheets/data/flag-defs.json, shortcuts/sheets/flag_defs_gen.go) are mirrored from sheet-skill-spec generated/ via 'npm run sync:cli'. shortcuts.go registers FormulaVerify alongside the other lark_sheet_formula_verify skill shortcuts so +formula-verify is discoverable from 'lark-cli sheets --help'. Tests cover the dry-run wire shape (excel_id + sheet_ids/sheet_names/ ranges/max_locations packing), the read scope (invoke_read URL), the mutually-exclusive selector validation, the non-positive --max-locations guard, and the --exit-on-error status matrix (success/partial/errors_found/unknown). * feat(sheets): add +history-list / +history-revert / +history-revert-status shortcuts BE-1 + BE-2 (larksuite/cli lark-sheets) for spec sheet-history-revert. Three thin callTool wrappers over facade-agg history tools, following the existing sheets Validate/DryRun/Execute + --url/--spreadsheet-token(/--token) locator convention: - +history-list (read, history_list): passes the tool output through verbatim; facade-agg already does the minor_histories/4-field/RFC3339 transform. - +history-revert (write, history_revert): --history-version-id required, enforced at Validate stage with a typed *errs.ValidationError (no request on missing); returns the async receipt. - +history-revert-status (read, history_revert_status): polls in-progress / success / failure. Flags declared inline (not via *_gen.go) — flag_defs_gen.go / data/flag-defs.json are synced from sheet-skill-spec (BE-3) and must not be hand-edited. Notes: - history_revert / history_revert_status depend on facade-agg's downstream RPC wiring, a DEFERRED follow-up; the tools return a "not wired yet" guard today. These CLI wrappers are correct and go live when the backend follow-up lands. +history-list is fully functional now. - TestFlagDefsGen_MatchesJSON fails on baseline (pre-existing BE-3 gen/json drift); resolves once BE-3 sync:cli regenerates flag defs for these shortcuts. Validation: go build ./shortcuts/sheets/... PASS; new tests (TestHistoryShortcuts_DryRun, TestHistoryRevert_MissingVersionID) PASS. Spec source: active@2acd94a24ac3f835357a274a02344f78435bcc1c39ad0d695ce587f0cbddfb21 * chore(sheets): sync lark_sheet_history skill + flag defs from sheet-skill-spec (BE-3) Synced artifacts for the history shortcuts from ee/sheet-skill-spec (SSOT), landed surgically (history-only) to avoid regressing this branch's newer skills/lark-sheets content: - skills/lark-sheets/references/lark-sheets-history.md (new, mirrored). - skills/lark-sheets/SKILL.md: + Lark Sheet History references-table row only. - shortcuts/sheets/data/flag-defs.json: + 3 history shortcuts (additive; no existing entries touched). - shortcuts/sheets/flag_defs_gen.go: regenerated via go generate ./shortcuts/sheets/... (this also resolves the pre-existing flag-defs/gen drift — TestFlagDefsGen_MatchesJSON now passes). NOT a full mirror: the rest of skills/lark-sheets/ + flag-schemas.json on this branch (feat/lark-sheets-develop) are NEWER than the sheet-skill-spec worktree's canonical (e.g. /wiki/ URL support, schema_version 3). A wholesale sync:cli would have reverted them, so only the history delta is taken here. Full re-sync should happen once sheet-skill-spec canonical is realigned with this branch. Validation: go generate clean; go test ./shortcuts/sheets/ (TestFlagDefsGen_MatchesJSON, TestHistory*) PASS. Spec source: active@2acd94a24ac3f835357a274a02344f78435bcc1c39ad0d695ce587f0cbddfb21 * fix(sheets): +history-revert-status keys on --transaction-id, not version id BE-2 gap surfaced by PPE E2E: +history-revert-status sent history_version_id, but the facade-agg history_revert_status tool keys on transaction_id (the async receipt returned by +history-revert), so it returned "[40400] transaction_id is required". Give the status shortcut its own --transaction-id flag + input (excel_id + transaction_id); revert keeps --history-version-id. Tests updated. * fix(sheets): align history flag-defs with inline shortcuts (green TestFlagsFor) TestFlagsFor_EveryRegisteredCommandHasDefs was RED: generated flag-defs drifted from the hand-written history shortcuts. - +history-revert-status: flag-defs had --history-version-id; the BE-2 fix switched the shortcut to --transaction-id. Updated the entry to transaction-id. - +history-revert / -status --history-version-id were marked required="required", but the inline flags are cobra-optional (requiredness enforced in Validate). Set required="optional" to match. Regenerated flag_defs_gen.go. NOTE: canonical source is sheet-skill-spec (BE-3); apply the same change upstream or the next sync:cli will regress this. * chore(sheets): sync lark-sheets-history reference from spec (BE-2 transaction-id) Mirror the upstream BE-2 fix in canonical-spec/references/lark_sheet_history/ cli-reference.md: +history-revert-status now uses --transaction-id (taken from the async receipt returned by +history-revert), and +history-revert's --history-version-id flips required→optional (Validate enforces requiredness at runtime). This file is the only history-only delta from the upstream sheet-skill-spec sync; the rest of skills/lark-sheets/ stays on the cli's newer baseline (/wiki/ URL support, +cells-set-image / +float-image-create, etc.) to match commit 8ae516db's history-only mirror policy. Spec source companion change: feat/sheet-history-revert in ee/sheet-skill-spec, canonical-spec/{tool-shortcut-map.json,references/ lark_sheet_history/cli-reference.md}. * feat(sheets): +history-list --end-version for backward pagination Spec follow-up sheet-history-revert: thread the history_list pagination contract through the +history-list shortcut. - shortcuts/sheets/lark_sheet_history_list.go: + --end-version (int, optional). Mapped to the tool input's `end_version` only when explicitly set (so the server treats absence as "first page / latest"), via runtime.Changed / runtime.Int (matches the +formula-verify --max-locations precedent). + Tip: pass next_end_version from the response on the next call; capture exits the pagination loop when the server omits the field. - shortcuts/sheets/lark_sheet_history_test.go: + dry-run case asserting --end-version 12345 lands as input.end_version=12345 (post-JSON unmarshal float64). - skills/lark-sheets/references/lark-sheets-history.md: synced from ee/sheet-skill-spec (commit 39c6b61). Adds the "倒序分页" caveat row + --end-version flag + pagination Examples line. Drops the internal MajorHistory.Version implementation detail per spec follow-up. - shortcuts/sheets/data/flag-defs.json: synced from spec (+history-list +--end-version int optional). - shortcuts/sheets/flag_defs_gen.go: regenerated via `go generate ./shortcuts/sheets/...`. Companion changes: - ee/sheet-skill-spec MR !37: spec-tables + tool-schemas pagination contract (commits 09e8604, 39c6b61). - ee/sheet-facade-agg MR !1028: history_list tool plumbs end_version, emits next_end_version + has_more (omitted at earliest page), defaults PageSize=20 to datarpc. Validation: - go build ./shortcuts/sheets/... PASS - go test ./shortcuts/sheets/... PASS (sheets + backward) - TestHistoryShortcuts_DryRun (5 cases incl. new --end-version case): PASS - TestHistoryRevert_MissingRequiredFlag: PASS - TestFlagsFor_EveryRegisteredCommandHasDefs: PASS - TestFlagDefsGen_MatchesJSON: PASS * fix(sheets): make +history-revert --history-version-id cobra-required + revert max-cells default drift Two issues surfaced during MR !37 review: 1) +history-revert --history-version-id requiredness was set as "optional" in the spec table (BE-2 fix dc5fe0ea) so cobra wouldn't block before Validate. Per upstream review the flag should be required-by-cobra so the user gets the standard "required flag(s)" gate immediately and the runtime contract matches the JSON shape. - shortcuts/sheets/lark_sheet_history_revert.go: historyVersionIDFlag now sets Required: true. Validate keeps a trim/empty-string guard so '--history-version-id ""' still fails as a typed *errs.ValidationError (cobra accepts empty strings as "set"). - shortcuts/sheets/data/flag-defs.json: +history-revert --history-version-id required: optional -> required. - shortcuts/sheets/flag_defs_gen.go: regenerated. - shortcuts/sheets/lark_sheet_history_test.go: TestHistoryRevert_MissingRequiredFlag split into per-shortcut subtests; +history-revert asserts cobra's "required flag(s)" contract (raw err — the test rig calls cmd.Execute directly so it doesn't see the cmd dispatcher's typed envelope wrap); +history-revert-status keeps the typed *errs.ValidationError contract (its --transaction-id stays cobra-optional + Validate-enforced). 2) max-cells safety cap was accidentally rewritten from 200000 to 50000 by the last sync from sheet-skill-spec (the spec canonical side fell out of date — fixed separately on the spec MR follow-up). Restore desc: "Safety cap; default 200000" / default: "200000" so +cells-get / +csv-get keep the documented cap. Validation: - go test ./shortcuts/sheets/... PASS - TestHistoryRevert_MissingRequiredFlag (both subtests) PASS - TestHistoryShortcuts_DryRun (incl. +history-list pagination case) PASS - TestFlagsFor_EveryRegisteredCommandHasDefs PASS - TestFlagDefsGen_MatchesJSON PASS * fix(sheets): make +history-revert-status --transaction-id cobra-required (match +history-revert) Companion to commit 6ca35b06: same gating model now applies to both history receipts. - shortcuts/sheets/lark_sheet_history_revert.go: transactionIDFlag.Required=true. Validate keeps a trim/empty-string guard for '--transaction-id ""'. - shortcuts/sheets/data/flag-defs.json: +history-revert-status --transaction-id required: optional -> required (synced from sheet-skill-spec @9ca814d). - shortcuts/sheets/flag_defs_gen.go: regenerated. - shortcuts/sheets/lark_sheet_history_test.go: TestHistoryRevert_MissingRequiredFlag/+history-revert-status moved to the cobra "required flag(s)" text contract (the test rig invokes the shortcut via cmd.Execute, which sees the raw cobra error directly without the dispatcher's typed wrap). Drop now-unused `errors` and `errs` imports. Validation: - go test ./shortcuts/sheets/... PASS (sheets + backward) - TestFlagsFor_EveryRegisteredCommandHasDefs: PASS - TestFlagDefsGen_MatchesJSON: PASS - TestHistoryRevert_MissingRequiredFlag (both subtests): PASS * docs(sheets): sync history skill reference required badges from spec Companion to commit 9fa73312 (transaction-id) and 6ca35b06 (history-version-id): the two flag tables in skills/lark-sheets/references/lark-sheets-history.md still showed 'optional' even though the canonical contract — and shortcuts/sheets/data/ flag-defs.json — already moved to 'required'. The earlier syncs only picked up the data file from spec; the skill markdown drift slipped through. Pull in the spec-side regenerated reference (ee/sheet-skill-spec @9ca814d) so the human-readable doc matches the wire contract. * fix(sheets): lower cells-set --max-cells default to 50000 * docs(sheets): clarify workbook-import over read-then-recreate in skill * docs(sheets): bump lark-sheets skill version to 3.0.1 * docs(sheets): clarify number-vs-text typing and copy-to-range template guidance in references * docs(sheets): type by data nature, add pre-write reference column and chart/cond-format/filter rows - SKILL.md quick-reference: add a "read before acting" column pointing each intent at its reference doc; add chart / cond-format / filter rows. - Reframe number-vs-text decision to follow the data's nature (measure vs identifier), not whether the current task happens to sort/sum; a leaderboard/report "display only" use does not make a percentage text. - write-cells reference: mirror the same rule and the +cells-set fallback for layouts +table-put cannot express. * docs(sheets): tighten number-vs-text guidance and dedupe write-cells reference * Feat/lark sheets develop wzz (#1719) * feat(sheets): add +changeset-get shortcut for changeset review Wrap the get_changeset read tool: fetch the raw changeset (edit actions) between two versions to review whether an AI edit fulfilled the request. --start-revision required, --end-revision optional (defaults to latest), gap capped at 100. Adds flag-defs entry + regenerated gen, the ChangesetGet shortcut + tests, and skill docs. * feat(sheets): add +get-revision shortcut Return a spreadsheet's current document revision without pulling the full sub-sheet listing. +get-revision is a read-only derivative over get_workbook_structure (the lightest read — token only, no range) that projects the response down to the single revision field. Adds flag-defs entries and a unit test for the projection helper. * feat: 同步 spec 修改 * feat(sheets): rename +get-revision to +revision-get * feat: 移除 ppe 环境请求头 --------- Co-authored-by: wenzhuozhen <wenzhuozhen@bytedance.com> * docs(sheets): dedupe +changeset-get flag def and skill reference entry * feat(sheets): accept local_office_ token prefix for image parent_type The synthetic token prefix for imported office spreadsheets is being renamed from fake_office_ to local_office_. Accept either prefix when mapping a spreadsheet token to the drive media parent_type so image uploads keep working across the rename (main package and backward compat copy). * fix(sheets): replace undefined common.FlagErrorf with sheetsValidationForFlag changesetRevisions called common.FlagErrorf, which does not exist, breaking the build. Use sheetsValidationForFlag so the errors carry the offending flag param like the rest of the sheets validation paths. Also reword two doc comments in lark_sheet_history_revert.go that used '' for an empty shell string: gofmt (Go 1.19+) rewrites '' in doc comments to a curly quote, leaving the file permanently unformatted. * fix(sheets): satisfy errs-no-bare-wrap forbidigo and errorlint rules from main main introduced the errs-no-bare-wrap forbidigo rule and errorlint coverage that flag 27 issues in existing sheets code after the merge: - Replace direct *errs.ValidationError type assertions with errors.As in sheetsInputStatError and validateSheetMediaUploadFile so wrapped errors still match (errorlint). - Type the embedded flag-schemas.json parse failure as an InternalError with cause; it reaches the user directly via --print-schema. - Annotate genuine intermediate errors (recursive schema validator, batch sub-op raw type checks, A1 range/position parsers) with //nolint:forbidigo; every caller wraps them into typed flag validation errors. * docs: tighten formula verify workflow guidance * docs: align formula verify refs with file names * feat(sheets): let typed writes style blank cells past the data extent +workbook-create / +table-put apply cell_styles by writing them into the in-memory matrix, whose size was fixed to the data (cols × rows). A style range reaching past that extent was rejected as "outside the write range", so blank cells (reserved regions, decorative headers, empty borders) could not be styled on the typed --sheets path — only the untyped --values path padded for it. Pad the matrix down/right to cover every cell_styles range before applying (empty cells appended for the uncovered positions), mirroring the --values behavior. writeSheetData now derives the written width/range from the padded matrix; both dry-run previews and sheetCreateDims account for the style extent so the physical grid and the plan match Execute. Ranges above/left of the write anchor stay rejected (the matrix only grows down/right). * docs(sheets): warn that +csv-put silently coerces numeric-looking labels Add guidance that +csv-put numericizes date-like/ID-like columns whose values are all digits (12.10 becomes 12.1 losing the trailing zero, 001 becomes 1 losing the leading zero); recommend +table-put with dtypes=object/datetime64 or +cells-set + number_format="@". Also fix the batch-update example to use sheet_name instead of sheet_id. * docs(sheets): steer import-vs-append onto sheet-copy for existing workbooks * docs(sheets): warn that cells-clear --scope all is irreversibly destructive * docs(sheets): sync chart schema and labels guidance (#1716) * chore(sheets): update chart flag schema * docs(sheets): clarify chart labels field is presence-toggle, not value-toggle Synced from sheet-skill-spec. Chart labels (plotArea.plot.labels and per-series labels) are toggled by object existence — passing labels at all turns data labels on, even when value/category/series/percentage are all false (server falls back to showing value). Models repeatedly try `{ value: false, category: false, series: false }` to disable, which silently shows the value fallback. The reference doc now spells out both directions: pass labels to show, omit the whole labels field to hide. Also picks up earlier spec-side drift not yet propagated: - pivot-table reference: +pivot-list info return + overlap validation - flag-defs: cell-matrix fan-out cap default 200000 -> 50000 (#1578) * feat(sheets): drop pre-refactor aliases from `sheets --help` listing The refactored + commands have been the default for over a month. Hide the deprecated pre-refactor aliases from `sheets --help` via a custom cobra usage template that skips the deprecated group. Aliases stay registered and executable: their own `sheets <alias> --help` still shows the (→ +new-command) pointer, unknown-subcommand suggestions still span them, and execution still returns the _notice. * feat(sheets): let +csv-put fall back to piped stdin when --csv is omitted Agents routinely redirect a CSV into stdin but forget the `--csv -`, so `+csv-put ... < data.csv` failed its first try on a missing --csv and cost an extra round-trip (error, then --help, then retry). Relax --csv's cobra required-gate in the shortcut's PostMount and install a PreRunE that defaults an omitted --csv to "-" when stdin is a non-interactive pipe, so the standard stdin-resolution path reads it. The pipe guard keeps an interactive terminal from blocking on stdin, and a genuine miss (no piped data) still surfaces csvPutInput's typed "--csv is required" instead of cobra's bare "required flag(s) ... not set". Scoped entirely to the sheets domain — no changes to the shared runner or the flag schema. * feat(sheets): rework +rows-resize / +cols-resize to --height / --width 从上游 sheet-skill-spec 同步：+cols-resize 用 --width、+rows-resize 用 --height 直接给像素值， --type 变为可选（省略等价于 pixel）。--type standard/auto 走非像素模式，不能与像素 flag 同传； --type pixel 与 --width/--height 共存时视为等价形式。--size 已删除。 * docs(sheets): 更新 lark-sheets skill 版本至 3.0.2 将 SKILL.md 版本号从 3.0.1 升至 3.0.2，同步近期 sheets 命令改动（+rows-resize/+cols-resize 改 --height/--width、 +csv-put 支持 stdin 回退等）后的技能版本。 * feat(sheets): add --widths / --heights map form for per-column/row sizes 从上游 sheet-skill-spec 同步：+cols-resize --widths / +rows-resize --heights 接收 JSON map（键为单行列或闭区间，值为像素或 "standard"/"auto"），CLI 按起始位置排序后 展开为一次原子 batch_update 的多个 resize_range 操作，多列不同宽 / 多行不同高一次 调用完成，不再需要 +batch-update。map 形态与 --range/--width/--height/--type 互斥， 不可作为 +batch-update 子操作嵌入（batch_update 不支持嵌套）。列宽 < 20px 拒绝并提示 Excel 字符单位换算（px ≈ 字符数×8+16）；--print-schema --flag-name widths/heights 可查 schema。 * fix(sheets): sync flag input/enum fixes from sheet-skill-spec 上游修复 spec-table 的 Input/Enum 字符串惯例后重新生成：--widths/--heights 现在带 file/stdin 输入声明，+sheet-create --type 的枚举正确进入 flag defs 与文档。 * feat(sheets): add sheets-scoped flag ergonomics via PostMount Two recovery loops from the edit-eval traces burn agent round-trips: hallucinated flag names (--cols for --range) whose unknown-flag error only points at --help, and enum values imported from CSS/Excel vocabulary ("center" for the vertical alignment Lark spells "middle"). - unknown-flag errors now inline the full valid-flag list (semantic guesses aren't rankable by edit distance; kills the --help round trip) - enum values with an unambiguous canonical form (casing, known alias) are normalized in place and the call proceeds; edit-distance typos stay errors with a did-you-mean hint and are never auto-applied Both ride the existing PostMount composition (same pattern as withTokenAlias), so the common framework is untouched and no other domain's behavior shifts. * feat(sheets): make validation errors prescriptive for hot failure modes Driven by the edit-eval-extra-35Q reports: ~70% of lark-cli sheets errors were missing-required / JSON-shape / wrong-value classes whose messages said what broke but not how to fix it, pushing agents into --help / --print-schema probe loops. - composite JSON shape errors inline a compact skeleton auto-generated from the schema (e.g. --cells -> [[{"value": ...}]]) when the type mismatch is shallow container confusion - +batch-update: missing 'shortcut' shows the entry template; a disallowed shortcut inlines the full allow-list; exceeding the 100-op cap says how many batches to split into; sub-op translator failures append the shortcut's complete input-key contract - +table-put: dtypes/formats keys that miss every column call out the A1-letter habit and inline the declared column names; empty cells in a date-typed column name the three ways out - schema enum errors suggest across casing, vocabulary aliases, and edit distance * fix(common): steer rejected @file paths to stdin instead of cd The absolute-path rejection hint said "cd to the target directory first" - advice the lark-sheets skill explicitly tells agents not to follow (it pollutes the working directory). The stdin-contention hint also demonstrated @file with an absolute path, which would itself be rejected. - @file failures on stdin-capable flags now show the equivalent stdin invocation (--csv - < /tmp/x.csv) - the path error recommends a relative path or stdin, not cd - the stdin-contention example uses a relative @file path Message-text only; no control-flow change for any domain. * chore(sheets): suppress forbidigo on csv-put stdin pipe detection os.Stdin.Stat is intentional here - pipe detection needs the real process fd; IOStreams.In is a plain io.Reader without Stat. Clears the lint failure left by the stdin-fallback commit. * fix(sheets): pass spreadsheet token to changeset tool (#1839) * fix(sheets): hide bitable sheet creation (#1843) * fix(sheets): resolve revision wiki URLs * fix(sheets): reject overlapping resize ranges * fix(sheets): address remaining review feedback * fix(sheets): avoid credential scanner false positive * fix(sheets): import mislabeled .xls workbooks by sniffing content Local .xls files that are actually OOXML (an .xlsx exported or renamed to .xls) failed +workbook-import with a cryptic backend "xml_version_not_support" because the CLI trusted the file name extension. +workbook-import now sniffs the file's leading magic bytes (PK -> xlsx, OLE2 -> xls) and passes the true extension to the drive import core via a new optional ImportParams.FileExtension override, correcting both the file_extension and the staged media file name (the latter avoids the backend's "import file extension not match", code 1069910). A declared Excel file whose bytes match neither container is rejected locally with a prescriptive error instead of the opaque backend failure. The drive import core gains only the neutral FileExtension override (empty = infer from the file name, i.e. unchanged behavior for drive +import); all Excel sniffing/correction policy lives in the sheets shortcut. * fix(ci): keep semantic waiver fixture active * fix(sheets): close remaining safety gaps * fix(sheets): align history shortcuts with generated flags Use generated flag defs for history revert commands, enforce control-character validation, and sync the refreshed lark-sheets references from sheet-skill-spec. * fix(sheets): require confirmation for history revert * fix(sheets): require explicit csv input --------- Co-authored-by: xiongyuanwen-byted <xiongyuanwen@bytedance.com> Co-authored-by: wuyanchun.anunwu <wuyanchun.anunwu@bytedance.com> Co-authored-by: wenzhuozhen <wenzhuozhen@bytedance.com>	2026-07-13 21:29:43 +08:00
xiongyuanwen-byted	bd898a1d74	feat(sheets): typed table I/O & error contract, workbook import/export, skill refresh (#1355) ... * feat(sheets): add +sheet-show-gridline / +sheet-hide-gridline shortcuts * docs(sheets): strengthen lark-sheets references for common editing pitfalls Add targeted guidance to six lark-sheets references to reduce frequent mistakes when editing spreadsheets through the CLI: - write-cells: sanity-check units / dimension conversion / quantity factors before formula writes (formulas can run clean yet be off by a factor); keep derived output off original data columns to avoid clobbering source - core-operations: prefer live formulas for derived values even when "live update" is not explicitly requested; scope rewrite/transform precisely so rows/columns that should stay unchanged are kept 1:1; treat header-stated format rules as checklist items; confirm the artifact file actually exists before finishing; write back bare values from local scripts - visual-standards: apply border/header formatting on explicit request and identify the real header row; keep font size consistent with the source - range-operations: keep total column width within A4 for printing - read-data: dedup/compare long numbers via raw values, not csv formatted display (scientific notation collapses distinct numbers and causes false duplicates) - chart: format date/number axes via source-cell number_format; place charts outside the data area so they do not cover existing data * feat(sheets): implement table-put/table-get and sync skill specs - Add lark_sheet_table_io.go with +table-put / +table-get and tests - Refactor read-data; extend workbook; register new shortcuts - Sync generated flag defs/schemas (go:embed) from sheet-skill-spec - Sync skill references (write-cells numeric-column guidance, plus read-data / workbook / chart updates) * docs(sheets): surface typed-write path at the write-decision point Quick-ref table (SKILL.md, the first decision point) had no +table-put and gated typed writes on "DataFrame", so a model holding a Counter/list/dict would fall back to +csv-put and silently lose number/date fidelity. - split csv-put row to plain-text values (no numeric/date semantics) - add +table-put row for typed writes into an existing sheet - add +workbook-create --sheets row for create + typed write in one shot - add judgment note: number/amount/date/percent/count -> +table-put (or +workbook-create --sheets when the workbook does not exist yet); plain text -> +csv-put - reframe write-cells scenario row to lead with numeric semantics - point new-table writes at +workbook-create --sheets (one shot) instead of the create-empty-then-table-put two-step Synced from sheet-skill-spec canonical (generate:cli + sync:cli). * docs(sheets): sync SKILL.md (drop "not for local Excel" caveat) Mirror the upstream sheet-skill-spec change removing the "not applicable to local Excel files" tail from the sheets skill and reference descriptions. * docs(sheets): sync SKILL.md (drop "Feishu sheets only" caveat) Mirror the upstream sheet-skill-spec change removing the "applies to Feishu sheets only" tail from the 14 sheet reference descriptions. * feat(sheets): add +workbook-import wrapping the drive import core Import a local xlsx/xls/csv as a new spreadsheet by delegating to the shared drive import flow with the target type pinned to sheet. Refactor drive +import to expose ImportParams / ValidateImport / PlanImportDryRun / RunImport (behavior unchanged, existing drive tests still cover it); sheets reuses them. Regenerate flag_defs_gen.go and sync the spec mirror. * refactor(sheets): reuse the drive export core in +workbook-export Replace +workbook-export's parallel export-task implementation with the shared drive ExportParams/RunExport core (pinned to type=sheet). Drops ~90 lines of duplicated poll/download code; +workbook-export now inherits drive's ctx cancellation, resume-on-timeout, filename sanitize/overwrite, and the full set of export status labels. The output contract aligns with drive's (adds ready/downloaded/doc_type; saved_path preserved). Also normalize an empty drive --output-dir to "." so drive +export behavior is unchanged, and fix the sheets export e2e to call +workbook-export instead of a nonexistent +export. * docs(sheets): keep original column widths; align chart axis with requested metric - range-operations: only widen new / overflowing columns; never recompute or shrink the widths of existing columns (any blanket resize, even by 1px, breaks the original visual format) - chart: when the user asks for a share / percentage, the value axis should be a percentage (pie, or stack.percentage on bar/column) rather than raw counts * docs(sheets): reword guidance to avoid eval-specific phrasing Replace scoring-framework wording in the examples with plain functional consequences (e.g. "not delivered", "goes stale when the source changes", "breaks the original visual format"), so the references stay agent-facing. * docs: add lark sheets financial modeling guidance * docs(sheets): align write-cells reference with the generated output Bring the hand-applied write-cells example in line with the spec-generated reference so the CLI mirror is byte-identical to the canonical source. * docs(sheets): align +csv-put help with formula support Sync the formula-support wording from sheet-skill-spec (flag-defs, skill references) and update the hand-authored cobra Description and comment for +csv-put. +csv-put evaluates a leading-= cell as a formula via set_range_from_csv; descriptions only, no behavior change. * docs(sheets): fix invalid +dim-insert example in chart reference The chart reference's placement example used non-existent flags --dimension/--start/--end for +dim-insert. The real signature is --position (required) + --count (required); copying the example fails Validate with "--position is required". Replace it with +dim-insert --position V --count 6 (insert 6 columns before V, i.e. after U), aligning with the sheet-structure reference. * docs(sheets): chart coordinate base / quoting + filter condition enums Sync three reference-doc corrections from the spec source: 1. chart: label position.row as 0-based (first row = row:0), distinct from the 1-based row numbers used by A1 ranges and +dim-insert --position, removing the row-base ambiguity. 2. chart: convert the three runnable examples whose JSON contains a quoted sheet prefix ('Sheet1'!A1) from inline single-quoted --properties '{...}' to a stdin heredoc (--properties - <<'JSON'). Inside an inline single-quoted string bash strips the inner quotes around the sheet name (and splits names with spaces into words), corrupting the JSON; a quoted heredoc delimiter performs no shell substitution and preserves it. Adds a short note on the pitfall. 3. filter / filter-view: add the full conditions[].type x compare_type enum table (text / number / multiValue / color and their respective compare_type values and values shape), and call out the equals/notEquals (with s) vs equal/notEqual (no s) gotcha. The docs previously only showed two values via examples. * docs(sheets): label +sheet-create --index as 0-based The base flag description for +sheet-create's --index omitted the coordinate base, while its siblings +sheet-move ("Target position (0-based)") and +sheet-copy already state 0-based. Align the description so the index base is unambiguous. Synced from the spec source (flag-defs.json + workbook reference). * fix(sheets): regenerate flag defs and fix asasalint in table io * feat(sheets): add counta to chart aggregateType enum Add `counta` (count non-empty cells, incl. text) to manage_chart_object dim2.series[].aggregateType in the chart flag schema. `count` only counts numeric cells, so counting occurrences of a text/category column renders an empty chart; `counta` enables category frequency counts. Synced from the sheet-skill-spec canonical schema. * feat(sheets): make --target-position and --range mutually exclusive on +pivot-create Both flags map to the same wire field (properties.range), so passing non-default values for both is ambiguous. Mirror the --target-sheet-id / --target-sheet-name mutex pattern: --target-position takes priority over --range, and supplying both with non-default values is rejected up front with a typed FlagErrorf. --target-position=A1 is the documented default and is treated as "not set". Add a symmetric validateCreateInput hook on objectCRUDSpec (alongside the existing validateUpdateInput), wire it into objectCreateInput, and inject the pivot-specific check on pivotSpec. * feat(sheets): rework +workbook-create flags and --styles - --values builds a type-less typed payload, writing through --sheets' batched set_cell_range path (raw passthrough preserves auto-detect; large tables batch; big ints via json.Number) - drop --headers (subsumed by --values first row) and --header-style (typed header no longer auto-bold; use --styles instead) - styles: deep-merge overlapping cell_styles/border_styles fields (was wholesale-replace which dropped fields); add manual border_styles validation (style/weight enums + sides) since --styles is on parseJSONFlagSkip and bypasses the schema validator - regenerate flag-defs/flag-schemas/skills mirror from sheet-skill-spec (--styles flag + full per-side border schema) * fix(sheets): add mention_type enum to set_cell_range cells schema Constrain rich_text mention_type to the proto MENTION_FILE_TYPE set so a file @mention with an out-of-enum value (e.g. 6 = cloud shared folder) is rejected by the schema validator before it reaches the server and fails pb serialization ("mentionFileInfo.fileType: enum value expected"). - data/flag-schemas.json: mention_type gains enum + per-value description - lark_sheet_write_cells_test.go: cover reject (6) + allow (0 / 2 / 22) * feat(sheets): implement pandas-split --sheets protocol for +table-put/+table-get/+workbook-create Synced from sheet-skill-spec canonical (cli:table_put schema + references). +table-put/+workbook-create accept the new shape via a tableSheetIn -> tableSheetSpec normalize step (dtype string -> internal type/format mapping). +table-get emits the same shape so the writer's df_to_sheet and the reader's sheet_to_df round-trip cleanly. isoDateToSerial now accepts the full ISO datetime form (2024-01-15T00:00:00.000, including timezone suffixes) emitted by df.to_json(date_format="iso"), not just yyyy-mm-dd. End-to-end verified by the spec repo's contracts/python_helper_roundtrip script against a real Lark spreadsheet on pandas 2.2 and 3.0. * feat(sheets): add --dataframe Arrow IPC input for +table-put/+table-get/+workbook-create Introduce a binary-typed twin of --sheets: --dataframe accepts an Arrow IPC (Feather v2) payload that pandas' df.to_feather() writes, deriving dtypes and per-column number formats from the Arrow schema. The two producers are mutually exclusive and funnel through a shared resolver so +table-put and +workbook-create stay in lockstep; +table-get gains --dataframe-out for single-sheet reads. Also auto-grow a sub-sheet's row/column count before writing so blocks past the backend's default 200x20 bounds no longer fail with range-exceeds-sheet-bounds. * docs(lark-sheets): remove financial modeling standards reference Drop the lark-sheets-financial-modeling-standards.md reference doc and all pointers to it from SKILL.md, core-operations, and visual-standards. Bump skill version to 3.0.0. * docs(lark-sheets): clarify cell-image vs float-image routing and fix reference self-references Synced from sheet-skill-spec. - Add a binding-based decision (does the image belong to a record and move with its row?) to route +cells-set-image vs +float-image-create across the SKILL entry, float-image and write-cells references. - Add routing rows to the SKILL command cheat-sheet and warn against defaulting to float-image out of familiarity. - Replace mislabeled 本 skill / 子 skill / 跨 skill wording in references with 本文 / reference names, matching the existing convention. * feat(sheets): add --styles to +table-put for one-step typed write with styling +table-put now accepts --styles (same shape as +workbook-create's --styles): cell_styles merge into the set_cell_range matrix, while cell_merges / row_sizes / col_sizes apply as their own tool calls after the write. The styles payload is name-matched against the written sheets and validated up front, so a malformed or mismatched style fails before any write lands. Also points +sheet-create users to +table-put (auto-creates missing sheets) when they need data/styles, via a runtime Tip and the lark-sheets skill references. Flag is sourced from the upstream Base table and regenerated through sheet-skill-spec (flag-defs.json / flag-schemas.json / gen file). Adds unit tests (dry-run styles, name-mismatch reject, execute) and a dry-run E2E (tests/cli_e2e/sheets/sheets_table_put_dryrun_test.go). * docs(lark-sheets): point read-data to +sheet-info for hidden row/col identification skip-hidden defaults to false (lossless reads), but the read primitives don't mark which rows/cols are hidden. Cross-reference +sheet-info --include hidden_rows,hidden_cols + row_indices/col_indices so agents can identify hidden ranges when they need to filter or interpret hidden data. Synced from sheet-skill-spec. * feat(sheets): document link requirement for @document mentions in cells flag schema @document mentions (mention_type != 0) must pass link (doc URL) to render a clickable card; @user mentions (mention_type=0) don't need it. Synced from the upstream tools-schema. * fix(sheets): reject cond-format attrs whose shape mismatches rule_type A conditional-format rule created with --rule-type colorScale but cellIs-shaped attrs ({compare_type,value}, no color) was accepted by the CLI and written through to the server, producing a color-less color-scale segment. That dirty data crashes the frontend on snapshot deserialization, so the spreadsheet can no longer be opened (5005). The per-entry schema check can't catch this: properties.attrs.items is a oneOf over all nine attr shapes and passes as soon as any branch matches, blind to the sibling rule_type — {compare_type,value} matches the cellIs branch even when rule_type says colorScale. The tool side maps attrs blindly by rule_type and only validates dataBar count and iconSet ordering, so the gap reaches the data layer. Add a cross-field validator (validateCondFormatAttrs) wired into both create and update via the new objectCRUDSpec.validateCreateInput hook (twin of validateUpdateInput). It enforces, per rule_type, the keys every attrs entry must carry — mirroring the tool's converter contract — and treats an empty required string (notably color) as missing. Rule types that take no attrs (duplicateValues / uniqueValues / containsBlanks / notContainsBlanks) and updates that omit rule_type are left to the server. * test(sheets): guard condFormatAttrsRequired against flag-schemas drift Add TestCondFormatAttrsRequired_MatchesSchemaOneOf, comparing the hand-maintained condFormatAttrsRequired table against the embedded flag-schemas.json attrs oneOf (multiset of required-key sets, for both create and update). The cross-field validator only holds if its per-rule_type required keys mirror the schema branches, and the two share no compile-time link — this pins them together so a future schema sync that adds/drops a required key can't silently desync the table. * fix(sheets): default +table-get to full used range, not A1 current region +table-get without --range anchored its current_region probe at A1, so an internal blank row or column silently truncated everything past it — agents then treated the partial data as complete (the pro016 / pro025 incident). - Probe the used range over the full physical grid (row_count × column_count from the workbook structure) so it spans internal blank rows/columns; fall back to the legacy A1 anchor when dimensions are unknown. - Emit the actually-read `range` on every sheet so callers can detect truncation (get_cell_ranges has no has_more flag). - Fix the same A1-anchor bug in append mode's last-data-row probe, which could otherwise overwrite data past an internal blank row. - Add unit + dry-run/live E2E coverage; refresh synced skill docs. * docs(sheets): fix csv-get current_region guidance to cross-check row_count current_region is a blank-row/column-bounded block, not the true sheet extent: an internal blank row truncates it, so it can miss rows past the gap. The read-data reference previously called it the "真实数据边界" and told agents to prefer it over row_count — which drove the "read only to current_region's last row, miss the tail" failure. - current_region: warn it can be both smaller (internal blank rows truncate) and larger (trailing summary/signature rows) than the real data range. - csv-get output contract: clarify its row_count/col_count is the returned size (= actual_range), not the physical sheet size; has_more only reflects the current range, not whether the whole sheet was read. - "确定数据范围的正确流程": add a step to cross-check against +workbook-info's physical row_count and probe past current_region's last row for data beyond an internal blank row. * fix(sheets): collapse duplicate validateCreateInput from bad merge resolution A prior merge kept both branches' independently-added validateCreateInput fields on objectCRUDSpec with conflicting signatures (pivot's func(rt, input) and cond-format's func(input)), plus both call sites in objectCreateInput, which failed to compile (validateCreateInput redeclared). Collapse to the single richer func(rt flagView, input) signature and one call site. cond-format's validateCondFormatAttrs (func(input), still shared with validateUpdateInput) is wrapped in a closure that ignores rt. Both behaviors are preserved: pivot --target-position/--range mutex and cond-format attrs-shape-vs-rule_type validation. * refactor(sheets): migrate legacy error helpers to typed errs in sheets domain golangci-lint forbidigo (errs-no-legacy-helper / errs-no-bare-wrap) flagged the table I/O, workbook, and dataframe shortcuts that landed on this branch: 93 common.FlagErrorf and 48 fmt.Errorf calls. - Replace every common.FlagErrorf with common.ValidationErrorf (typed *errs.ValidationError, same signature) across workbook / table_io / dataframe / object_crud. - writeDataframeOut's two final --dataframe-out write failures become typed errs.NewInternalError(SubtypeFileIO, ...).WithCause(err). - applyWorkbookCreateVisualOps now passes the typed callTool error through unchanged (re-wrapping would downgrade classification) and attaches the failing op as a recovery hint only when none is set. - The remaining fmt.Errorf are genuine intermediate errors that the command layer re-wraps into typed validation errors (buildTypedCell / Arrow decode-encode) or surfaces as a partial_success message string (writeTypedSheets via tablePutPartial); each carries a //nolint:forbidigo with that reason, per the lint guidance. No behavior change: error messages and partial-success shapes are preserved; gofmt, go vet, golangci-lint (0 issues) and sheets tests all pass. * fix(shortcuts): clarify single-stdin constraint in flag help and error hint Input flags advertised '(supports @file, - for stdin)' per flag, leading AI agents to write '--a - <x --b - <y' where the second '<' silently clobbers the first and the first flag reads the wrong payload. A process has a single stdin, so at most one flag per call can use '-'. - Reword the generated help hint to '- reads stdin (one flag per call; use @file for others)'. - Add an actionable .WithHint to the stdin-conflict validation error pointing callers to @file for the extra flags. - Assert the new hint in TestResolveInputFlags_DuplicateStdin. * feat(sheets): +cells-get/+csv-get --max-chars 默认值 200000 → 500000 放宽默认防爆上限。flag_defs_gen.go 由 go generate 重生；flag_defs_test.go 的 expected default 同步；flag-schemas.json schema_version 2 → 3 是上游 spec-tables 架构调整带来的元数据 bump，与本业务改动无关、go:embed 不解析 该字段、无功能影响。 Synced from sheet-skill-spec@93f7a78. * docs(lark-sheets): sync from spec — +csv-put 含逗号公式正例 + 收敛警示标签 源同步自 sheet-skill-spec：write-cells 补含逗号公式 RFC 4180 转义正例与结构化写入优先指引；全 reference 收敛「高频致命错误」类标签。 * docs(lark-sheets): sync from spec — --max-chars 放出为可见 flag + 落盘优先指引 源同步自 sheet-skill-spec：--max-chars 放出（默认 500000，可调小避免大输出被 Bash/终端转存为文件、改 has_more 分页）；read-data 增「大数据优先落盘」指引。 * feat(sheets): 写操作报错增强 + --token 别名 - 复合 JSON shape 校验失败时报错附 --print-schema 提示，agent 可直接拿到精确结构（pro26 头号：+cells-set --cells 反复猜 shape） - JSON 解析失败且该 flag 支持 stdin 时提示改用 stdin（公式/引号/逗号内联到 shell 被转义弄坏 JSON） - --token 作为 --spreadsheet-token 的解析期别名：复用 sheets 已有 PostMount 钩子 + pflag normalize，仅 sheets 包，common 零改动 * docs(lark-sheets): sync from spec — set+H 改单引号 / 速查表补臆造命令名 / workbook-import 引导 * fix(sheets): migrate +table-put to typed error contract The merge from main brought in #1449 (retire legacy error envelopes), which removed output.ExitError / output.ErrDetail and forbids constructing them. Port tablePutPartial off the legacy envelope: - no sheets written -> typed errs.APIError (plain failure) - some sheets written -> ok:false result via runtime.OutPartialFailure carrying written_sheets, returning the partial-failure exit signal Also fix two drifts the same merge introduced: - regenerate flag_defs_gen.go to match the committed flag-defs.json - update the --max-chars flag test to assert visible (no longer hidden) * docs(lark-sheets): sync from spec — set+H 告诫通则化（移入 stdin 段） * feat(sheets): styles 接受 halign/valign 等对齐字段别名 把模型常幻觉的 horizontal_align / halign / vertical_align / valign 映射到 规范字段 horizontal_alignment / vertical_alignment，覆盖 --styles 与 typed --cells；与规范字段冲突时报错而非静默择一。同步 lark-sheets skill 文档补 对齐字段说明 + --print-schema --flag-name styles 提示。 * feat(sheets): resolve wiki URLs to the backing spreadsheet for --url Sheets shortcuts only accepted /sheets/ and /spreadsheets/ URLs via --url. A /wiki/<node_token> URL was rejected with "must be a spreadsheet URL" because the wiki node_token is not a spreadsheet token: resolving it to the backing spreadsheet needs a wiki get_node call, which Validate/DryRun (kept network-free) must not make. Mirror the existing slides/doc/drive two-stage pattern: - parseSpreadsheetRef classifies --url / --spreadsheet-token network-free into a sheet token or an (unresolved) wiki node_token. - resolveSpreadsheetTokenExec (Execute only) resolves a /wiki/ node_token via wiki get_node, verifies obj_type=sheet, and returns the obj_token. The wiki:node:read scope is enforced on this path only, so non-wiki invocations are unaffected. - resolveSpreadsheetToken stays network-free for Validate/DryRun, passing the node_token through unchanged. All 47 Execute paths (including +batch-update and +workbook-export) switch to the Exec resolver; Validate/DryRun keep the network-free one. No tool schema change: the CLI feeds the resolved spreadsheet token as excel_id, so this is a pure CLI-layer change. Tested: unit (parse classification + wiki get_node e2e via httpmock) and live end-to-end against a real wiki spreadsheet (read: +workbook-info, +cells-get, +csv-get; write: +sheet-create, +sheet-rename, +csv-put). * docs(sheets): note --url accepts wiki URLs (synced from spec) * fix(sheets): match --url path segment via url.Parse, not substring parseSpreadsheetRef classified /wiki/ with strings.Index over the whole URL, so a /sheets/ link whose query or fragment merely contained /wiki/ (e.g. .../sheets/sht?from=/wiki/x) was hijacked into a get_node call. Now parse the URL and match /sheets/, /spreadsheets/, /wiki/ only as a path prefix, mirroring slides parsePresentationRef which already fixed this class. Drop the substring helpers. Also align wiki resolution with slides: CallAPITyped (typed error + log_id) and classify an incomplete get_node response as InternalError instead of a --url validation error. Add regression tests for query/fragment /wiki/ and incomplete node. * fix(sheets): satisfy errorlint/copyloopvar + regen flag defs - helpers_test.go: drop the Go 1.22+ redundant `tc := tc` loop copy (copyloopvar). - lark_sheet_dataframe.go, lark_sheet_table_io.go: switch the intermediate-error fmt.Errorf calls from %v to %w so errorlint passes. Behavior unchanged — these errors are always rewrapped into typed validation errors at the command layer. - flag_defs_gen.go: regenerate from data/flag-defs.json (drift from the wiki-URL merge). * ci: allow Apache Arrow module in license check Arrow is Apache-2.0 overall, but it vendors c-ares (LicenseRef-C-Ares, ISC-like) inside the module which go-licenses classifies as Unknown and the strict disallowed_types=...,unknown gate rejects. Pass --ignore github.com/apache/arrow/go/v17 since Arrow is required by sheets +table-put / +table-get / +workbook-create --dataframe (Arrow IPC ingest) and the vendored c-ares is not redistributed by us. * fix(sheets): resolve wiki URL in +range-move/+range-copy Execute transformExecuteFn (the named Execute helper shared by +range-move and +range-copy) still called the network-free resolveSpreadsheetToken, so a /wiki/ URL reached transform_range as an unresolved node_token and failed. #1519's sweep over Execute hooks only rewrote inline closures; this is the only Execute backed by a named helper. Switch it to resolveSpreadsheetTokenExec (Validate/DryRun stay network-free) and add a +range-move wiki-URL regression test. * refactor(sheets): drop +table-put manual capacity grow; rely on set_cell_range auto-grow set_cell_range now auto-grows the sub-sheet to fit the write, so the ensureSheetCapacity helper (and its modify_sheet_structure dim-insert call before each write) is no longer needed. This also closes a data- safety hole flagged in review: inserting before the last existing row could push real data down into the area set_cell_range was about to write, and allow_overwrite=false could not protect against it because the structural insert had already mutated the sheet by the time the write-collision check ran. Verified end-to-end against a real spreadsheet: +table-put writing 300x25 into a fresh Sheet1 (default 200x20) succeeds in one write and the sheet ends up 301x25. * fix(sheets): close --dataframe stdin guard hole --dataframe is binary and bypasses the common Input resolver, which is where the existing single-stdin guard lives. Result: an invocation like +table-put --dataframe - --styles - was accepted, then one of the two consumers raced for stdin and the other silently saw an empty stream. Add a stdinConsumed marker on RuntimeContext that both consumers share: common.resolveInputFlags sets it when an Input flag uses '-', and readDataframeBytes both checks and sets it. A second consumer is rejected up front with an actionable hint pointing at @file. Flagged in code review (lark_sheet_dataframe.go:93). * fix(sheets): harden +table-put / +table-get input validation and round-trip safety Four review-flagged correctness gaps in table I/O, all bundled because they touch the same file: 1. --sheets accepted trailing data after the first JSON value (json.Decoder does not surface that, unlike json.Unmarshal). A new decoderExpectEOF helper rejects e.g. `--sheets '{...} oops'` with a typed validation error instead of letting the leading object pass through and surface as a confusing downstream failure. 2. +table-get with a duplicate header (e.g. `amount, amount`) used to read back successfully — the dtypes map silently collapsed to one entry — and only failed later on +table-put because the writer rejects duplicate column names. Fail fast at read time with an actionable hint to rename or pass --no-header. --no-header mode is exempt (fallback col<N> names are always unique). 3. +table-put dry-run rendered an invalid range like A1:C0 when header=false with rows=[]. tablePutFullRange returns "" for an empty matrix or zero columns instead of building a degenerate rectangle. 4. +table-get with --sheet-id and a get_workbook_structure miss (read failure or selector mismatch) used to return a target with name="", which then broke +table-get → +table-put round-trip (the writer requires a non-empty sheet name). Fall back to using the id as the name. End-to-end verified against a real spreadsheet: trailing data, duplicate header, and --no-header fallback all behave as advertised. * fix(sheets): apply +workbook-create style-only ops instead of silently dropping them A +workbook-create call carrying only cell_merges / row_sizes / col_sizes (no --values / --sheets and no cell_styles) used to create the workbook but silently drop the requested visual ops. Two reasons, both fixed: - workbookCreateStyleDimensions only counted cell_styles when computing the write extent, so cell_merges / row_sizes / col_sizes always contributed 0 → buildValuesPayload returned a nil payload → Execute skipped writeTypedSheets entirely → no visual ops ran. Extend the helper to fold the merge / resize ranges in. - Pure row_sizes / col_sizes payloads can never expand a cell rectangle (they are dimension ranges, not cell ranges), so even with the extent fix Execute would still skip the write path. Add a no-data branch: when payload == nil but a styles item is present, look up the default sheet and apply visual ops directly via applyWorkbookCreateVisualOps. The dry-run plan mirrors this so the preview shows the visual ops. Also picks up the --values trailing-JSON-data EOF check (mirror of the --sheets one in lark_sheet_table_io.go). End-to-end verified against a real spreadsheet: a cell_merges-only +workbook-create now produces a sheet with merged_cells_count: 1. * fix(sheets): preserve causes and render messages cleanly for typed validation errors common.ValidationErrorf goes through fmt.Sprintf, which does not support %w — the seven call sites that used `%w` were rendering the cause as literal `%!w(*fmt.wrapError=&{...})` and dropping the cause from the typed-error chain (so callers couldn't errors.As back to the underlying error). Switch each to `%v` for clean rendering and attach the cause via .WithCause(err) so the typed contract is preserved. Touched call sites: - lark_sheet_dataframe.go: --dataframe Arrow decode / stdin read / file read failures (3 call sites). - lark_sheet_table_io.go: --sheets invalid JSON, payload-validate per-cell coercion error, buildSheetMatrix per-cell error, --dataframe-out arrow encode failure (4 call sites). End-to-end verified against a real spreadsheet: both invalid-JSON and typed-cell errors now render readable messages instead of %!w(...). * sync(sheets): pick up +sheet-{show,hide}-gridline in +batch-update schema Mirror of the sheet-skill-spec change adding the two gridline shortcuts to cli-schemas.json batch_update.operations.shortcut enum. Synced from the upstream canonical via generate:cli + sync:cli. Verified end-to-end on a real spreadsheet — +batch-update with a +sheet-hide-gridline op passes schema validation and the backend run returns succeeded: 1. * sync(sheets): pick up +workbook-export UX clarification from spec Mirror of the sheet-skill-spec update that documents +workbook-export's default-no-download behavior and its relationship to drive +export --doc-type sheet. Synced from canonical via generate:cli + sync:cli + go generate. End-to-end verified against a real spreadsheet: - Omit --output-path → ok:true, downloaded:false, file_token returned - Pass --output-path ./crfix_test.xlsx → ok:true, file saved (17892 bytes), saved_path returned The --help output for +workbook-export now states the default behavior and points callers at `drive +export --doc-type sheet` when they need the --output-dir / --file-name / --overwrite split. * test(sheets): assert typed errs.Problem instead of err.Error() substrings Per the coding guideline "Error-path tests must assert typed metadata via errs.ProblemOf (category / subtype / param) and cause preservation, not message substrings alone." — sweep through every error-path assertion in the sheets domain and replace the `strings.Contains(stdout+stderr+err.Error(), ...)` pattern with two small helpers landed in helpers_test.go: requireProblem(t, err, wantCategory, wantSubtype, msgContains) -> *errs.Problem requireValidation(t, err, msgContains) -> *errs.ValidationError // shorthand for CategoryValidation + // SubtypeInvalidArgument; lets callers // also assert .Param / .Params / .Cause ~60 assertion sites across 18 test files now check the typed envelope shape, with message-substring checks moved onto the returned Problem (.Message / .Hint / .Param). The substring is preserved as a sanity check rather than the sole assertion, so a category drift like validation → internal would now fail loudly instead of slipping past. Cases intentionally left as substring (each with a one-line reason): - Errors that come straight from cobra's native flag parser (untyped *errors.errorString — e.g. "required flag(s) ... not set", mutually- exclusive groups). Re-typing these needs a custom FlagErrorFunc and is out of scope here. - Intermediate errors from decodeArrowToSheet that the caller wraps into a typed envelope (`//nolint:forbidigo` reason). Those unit tests assert the unwrapped intermediate directly. One production tweak: - shortcuts/sheets/flag_schema.go: printFlagSchemaFor returns typed *errs.ValidationError (with WithParam("--flag-name") on the unknown-flag branch) instead of raw fmt.Errorf. The framework already wraps this when called via --print-schema, so user-facing behaviour is unchanged; direct callers (and tests) now get the typed envelope. Verified: go test ./shortcuts/sheets/... passes; golangci-lint --new-from-rev=origin/main reports 0 issues. * test(common): assert typed errs.Problem instead of err.Error() substrings Mirror of the sweep just landed in shortcuts/sheets: replace error-path substring assertions with typed-envelope checks via two small helpers landed in a new shortcuts/common/typed_error_assertions_test.go: requireProblem(t, err, wantCategory, wantSubtype, msgContains) -> *errs.Problem requireValidation(t, err, msgContains) -> *errs.ValidationError // shorthand for CategoryValidation + // SubtypeInvalidArgument; lets callers // also assert .Param / .Params / .Cause 8 sites moved to typed assertions across runner_jq_test.go, mcp_client_test.go, drive_media_upload_typed_test.go, and runner_input_test.go (the input tests already used a typed-param helper; this just retargets the substring follow-up onto the typed Message). Sites intentionally left as substring + comment (production returns raw fmt.Errorf, not a typed envelope): - runner_botinfo_test.go (6 sites): BotInfo / fetchBotInfo wrap upstream errors with fmt.Errorf so the SDK-level message ([99991], 403, invalid character, etc.) shows through. - runner_args_test.go (4 sites in 2 tests): rejectPositionalArgs returns raw fmt.Errorf to satisfy cobra's PositionalArgs contract. - permission_grant_test.go (2 sites): assert on stderr / hint strings, not error messages — already out of the err.Error() substring class. No production code changes. Verified: go test ./shortcuts/common/... passes; golangci-lint --new-from-rev=origin/main ./shortcuts/common/... reports 0 issues. * fix(sheets): plug four +table-put / +table-get correctness gaps flagged in CR Four review-flagged bugs, all in lark_sheet_table_io.go (bundled because they touch the same file and the same +table-put / +table-get domain): 1. +table-get --dry-run dropped the --sheet-id / --sheet-name selector from the get_cell_ranges body, while Execute always passed it. Agents that validate the dry-run shape and then run live would see a request shape mismatch. The dry-run now calls sheetSelectorForToolInput so the body matches Execute. 2. isDateNumberFormat used a simple `strings.ContainsRune(_, 'y')` so number formats like "JPY #,##0" (a currency prefix that happens to contain a lone 'Y') were misread as date formats — round-tripping integer cells out as ISO dates. The detector is now token-aware: it skips quoted "...", `\\x`-escaped, and `[...]` bracket sections, and only fires on an unescaped `yy` (a real Excel year token). 3. sheetCreateDims sized new append-mode sheets by `headerOn(s)` only, but writeSheetData forces a header on empty append sheets when Header == nil. Near 50000 rows / 200 cols this created the sheet one row short and the follow-up set_cell_range bounced off the backend ceiling. Size now matches the forced-header logic exactly. 4. tableGetTargets fallback paths (read-failure / selector mismatch on --sheet-id) returned a target with name="" — already corrected for --sheet-id structure-success path in 086876d2, but the structure- failure fallback still left it empty. Use the id as the name there too so the +table-get → +table-put round-trip never breaks on a nameless sheet. End-to-end verified against a real spreadsheet: - table-get --dry-run with --sheet-name / --sheet-id both render the selector field in the get_cell_ranges body - A real round-trip (typed put → get) preserves dtypes + formats * fix(sheets): bound --dataframe memory use with byte / row / column caps readDataframeBytes used to read the whole Arrow file unbounded — a stdin / file > 1 GiB would OOM the CLI long before the backend per-sheet ceilings kicked in. decodeArrowToSheet then materialized every record into [][]interface{} regardless of size. Three caps now match the backend's per-sheet hard ceilings: - byte cap: 256 MiB (covers worst-case 200×50000 cells × ~25 B Arrow overhead). File path pre-Stat()s before opening; both file and stdin paths read through io.LimitReader so an oversized input is rejected without allocating the full payload. - column cap: 200, checked at schema-decode time before allocating any per-column slices. - row cap: 50000, checked during record-batch iteration so a 1M-row Arrow file is rejected mid-stream instead of fully decoding first. End-to-end verified against PPE — a 257 MiB file is rejected at file- Stat with a typed validation error before any read happens. * fix(drive): wrap +export ctx cancellation/deadline as typed errs.NetworkError The poll loop in RunExport returned ctx.Err() directly in two places — on the inter-attempt sleep cancel and on the pre-attempt deadline check. That let context.Canceled / context.DeadlineExceeded escape as untyped errors at the cobra layer, bypassing the typed-error contract every other failure path already honors. Add wrapExportContextErr that maps both into errs.NewNetworkError with SubtypeNetworkTransport / SubtypeNetworkTimeout respectively and preserves the cause via .WithCause(err), so callers can still errors.Is(err, context.Canceled) downstream. CR-flagged at drive_export.go:229 / :234. * ci(license): narrow Apache Arrow workaround with a follow-up assertion The dependency-license check still has to --ignore Apache Arrow wholesale because go-licenses' classifier parses its LICENSE.txt as a single license and mis-reports the module as LicenseRef-C-Ares / Unknown (Arrow inlines the c-ares 3rdparty notice alongside its own Apache-2.0). Re-classifying on our side isn't possible without changing go-licenses itself. The CR concern was that --ignore is too wide — a future Arrow re-license or new inlined dep would silently sail through. Add a follow-up step that re-checks Arrow's LICENSE.txt independently: it must still open with "Apache License" AND must still inline the c-ares 3rdparty notice (the two facts that make the --ignore safe today). If either invariant breaks, CI fails here and forces a human to re-evaluate the ignore. Verified locally — both assertions pass against the current pinned Arrow v17. * sync(sheets): pick up +table-put payload-shape doc corrections from spec Mirror of the sheet-skill-spec change that fixes three places teaching an invalid +table-put payload shape — the typed protocol only has columns / data / dtypes / formats (no formula field) and must always be wrapped in an outer {"sheets":[...]} envelope. write-cells and the SKILL.md decision table previously used the wrong field names (type / format) and pointed users at +table-put for formula writes, which the shortcut can't actually accept. Synced from upstream canonical via generate:cli + sync:cli. * test(sheets/e2e): add E2E coverage for new shortcuts + typed workbook-create AGENTS.md requires a dry-run E2E for every new shortcut and a live E2E for new flows. Three new files cover the four shortcuts this branch adds or materially changes: - sheets_gridline_dryrun_test.go — pins +sheet-show-gridline / +sheet-hide-gridline as a single modify_workbook_structure call with the right operation name (show_gridline / hide_gridline) and sheet_id, so an op-name typo would trip CI before any live run. - sheets_workbook_import_dryrun_test.go — pins +workbook-import as a two-step plan (drive media upload + drive import-task create) with the doc type hard-coded to "sheet" — the wrapper's whole reason for existing on top of generic drive +import. --name reaches file_name on the wire; file_extension is sniffed from the local file. - sheets_table_put_typed_workflow_test.go — two live workflows running against a freshly created spreadsheet. The first runs the full typed +table-put → +table-get round-trip (date / numeric / object columns with custom number_format) and asserts the dtype + format contract holds end-to-end. The second exercises the typed +workbook-create --sheets path: create + write in one shortcut, the payload sheet name adopts the workbook's default sheet (no empty "Sheet1" left behind), and the typed contract still survives the read-back. End-to-end verified locally (user identity): typed put round-trips preserve dtypes (date → datetime64[ns], numeric → float64, object → object) + formats verbatim; workbook-create adopts the named sheet as the first sheet with the same typed shape intact. * sync(sheets): pick up sheets_df.py — pandas ↔ JSON skill script from spec Mirror of the sheet-skill-spec change that adds a DataFrame ↔ JSON bridge as a skill-bundled Python script instead of inside the CLI binary. Per PR #1355 review (docx NcmxdRo2yoZ4OXxoMUZcxRZ7nHd, §4.2): keep the CLI a thin JSON/REST client; pandas / Arrow editing lives in the caller's Python process. Synced from canonical via generate:cli + sync:cli. - skills/lark-sheets/scripts/sheets_df.py (new): pandas DataFrame ↔ one sheet, .parquet / .feather / .arrow / .csv / .json. Shells out to `+table-put` / `+table-get` over typed JSON — no CLI changes. - SKILL.md decision tree + write-cells.md +table-put section: explicit pointers so pandas users land on the script instead of hand-rolling the `--sheets` payload. End-to-end verified against PPE: 3-row DataFrame (datetime / float / object) round-trips parquet → script put → real sheet → script get → parquet with dtypes preserved. * Revert "sync(sheets): pick up sheets_df.py — pandas ↔ JSON skill script from spec" This reverts commit 2964983b92. * sync(sheets): pick up sheets_df.py + doc DRY cleanup from spec Mirror of the sheet-skill-spec change that ships a 32-line helper-only sheets_df.py (df_to_sheet + sheet_to_df) and removes the corresponding inline `def` blocks from three reference docs. - skills/lark-sheets/scripts/sheets_df.py (new): pandas DataFrame ↔ one +table-put / +table-get sheet, importable as a library. Same helper pair the docs already taught, lifted out of the prose so callers can `from sheets_df import df_to_sheet, sheet_to_df`. - lark-sheets-write-cells.md / lark-sheets-read-data.md / lark-sheets-workbook.md: drop the inline helper definitions; keep the usage examples (single/multi-sheet, round-trip) and switch them to import-from-script. workbook reference's +workbook-create --sheets section now points pandas users at the helper directly (was previously a textual reference back to write-cells). End-to-end verified against PPE (--as user): - +workbook-create with df_to_sheet for three sheets (income / balance / cashflow): create ok, dtypes (datetime64[ns] / float64) + formats (#,##0 / 0.0% / yyyy-mm-dd) survive on read-back through sheet_to_df. - read → pandas mutate → write-back round-trip preserves both data and formats. * chore: drop accidentally-committed __pycache__/ and gitignore .pyc The previous commit (5fac9c39) shipped sheets_df.py and inadvertently included its `__pycache__/sheets_df.cpython-312.pyc` — local Python import created the bytecode cache during PPE round-trip verification and `git add skills/lark-sheets/` swept it in. Remove the pyc and add Python bytecode patterns to .gitignore so the skill-bundled helper scripts don't pull cache files into future commits. * refactor(sheets): drop --dataframe / --dataframe-out + apache/arrow dep Per the design review at NcmxdRo2yoZ4OXxoMUZcxRZ7nHd, the Arrow IPC binary input/output channel adds a heavy columnar runtime to the CLI for no new capability — the typed JSON --sheets path already covers everything, and the column-major / zero-copy advantages collapse the moment the CLI re- encodes into the row-oriented sheets OpenAPI JSON body. Removing it also lets us drop the `--ignore github.com/apache/arrow/go/v17` license-check escape hatch. Deleted: - shortcuts/sheets/lark_sheet_dataframe.go (+ test) - --dataframe branches in +table-put / +workbook-create - --dataframe-out branch in +table-get - StdinConsumed / MarkStdinConsumed exported methods (the binary stdin reader was the only out-of-band consumer); internal stdinConsumed guard against duplicate `-` input flags stays - apache/arrow/go/v17 + transitive deps via `go mod tidy` - CI go-licenses --ignore for arrow and the LICENSE.txt assertion step - --dataframe / --dataframe-out coverage in skill references Pandas users keep the round-trip via the existing skill script skills/lark-sheets/scripts/sheets_df.py over the JSON path. The full pre-removal state is preserved on branch feat/sheets-arrow-stash. Upstream sheet-skill-spec follow-up: the two flag rows in the canonical spec + base table tblV2F6fqIjyCFQW must also be dropped so the next sync does not re-add them. * sync(sheets): pick up --sheets one-liner fix from spec Mirrors sheet-skill-spec 5562f83. The +table-put / +workbook-create --sheets flag descriptions (and the --print-schema description on the sheets array) now point at the existing df_to_sheet helper instead of the previous misleading one-liner that produced a dict missing the outer {"sheets":[...]} envelope and the per-sheet `name`. Agents that copy-paste the description verbatim now build a valid payload. Auto-synced via spec's generate:cli + sync:consumers; go generate ./shortcuts/sheets/... regenerated flag_defs_gen.go so its embedded flagDefs stays byte-equal to data/flag-defs.json. * test(sheets/e2e): close E2E coverage gaps for newly added shortcuts AGENTS.md requires both dry-run and live E2E for every newly registered shortcut, and behavior-changing refactors need at least the matching half. Three gaps remained on feat/lark-sheets-develop: - +sheet-show-gridline / +sheet-hide-gridline (new): only dry-run E2E. Add sheets_gridline_workflow_test.go — create a real spreadsheet, toggle hide then show against a live sub-sheet, assert ok=true on both (gridline state is write-only — there is no read-back field on +sheet-info / +workbook-info — so a successful envelope is the meaningful signal; the dry-run E2E already pins the wire shape). - +workbook-import (new): only dry-run E2E. Add sheets_workbook_import_workflow_test.go — write a local CSV, run the full upload → create-task → poll, assert ready=true with a sheet token, +info confirms the imported workbook is reachable, cleanup deletes the spreadsheet. - +workbook-export refactor (no-download default changed): had live E2E but no dry-run E2E in tests/cli_e2e/. Add sheets_workbook_export_dryrun_test.go — pin the three sheet- specific differences vs drive +export: type=sheet hard-coded, csv mode routes --sheet-id onto sub_id (xlsx mode omits it), and --output-path maps onto the dry-run plan's top-level output_dir. Also pins the csv-without-sheet-id validation error. * refactor(sheets): unify workbookCreatedButFillFailed with OutPartialFailure Three "made it halfway and stopped" exits in the sheets domain previously disagreed on shape, which made the post-failure recovery flow hard for agents to predict from one command to another: - +table-put partial write → exit 1, stdout ok:false envelope - +table-put zero-sheet write → exit 1, stderr api/server_error - +workbook-create create-but-fill → exit 2, stderr validation/failed_precondition OutPartialFailure exists exactly for "the side effect landed but the follow-up didn't" — it stamps an ok:false result envelope on stdout (carrying the state the caller needs to recover) and returns the bare partial-failure exit signal. The workbook-create fill-failure path was the odd one out: it surfaced as a typed failed_precondition error on stderr, which agents couldn't tell apart from a plain validation refusal even though the spreadsheet really did exist and a retry / cleanup was possible. Migrate workbookCreatedButFillFailed onto OutPartialFailure so the four call sites in +workbook-create's Execute (sheet-resolve failure, initial fill failure, style-only resolve failure, style-only apply failure) emit the same envelope shape +table-put's partial write does: { "ok": false, "data": { "spreadsheet_token": "shtNEW", "reason": "spreadsheet shtNEW created but initial fill failed", "hint": "the spreadsheet exists; retry the fill … or delete it", "cause": {"category": "...", "subtype": "...", "message": "..."} } } The inner failure's typed problem (category / subtype / message) is flattened into the `cause` field so agents stay diagnosable from the JSON envelope alone, instead of having to errors.Unwrap a Go error. Updated TestExecute_WorkbookCreate_FillFailureKeepsToken to assert the new shape (ok:false envelope on stdout, *output.PartialFailureError exit signal, structured cause carrying the underlying invalid_response subtype) — preserving the original test intent (token must survive for recovery; inner cause must stay diagnosable) under the new contract. * chore(sheets): three review nits — WithCause + stale comment + unexport - shortcuts/sheets/flag_schema_validate.go:106 — composite-JSON shape validation was wrapping vErr's message into a typed sheets validation error without preserving vErr as the typed cause; add the missing .WithCause(vErr) so errors.Unwrap and ProblemOf still find the underlying validator error (matches every other typed-error chain helper in the file). - shortcuts/sheets/lark_sheet_batch_update.go:92 — comment claimed batchUpdateInput returns "FlagErrorf-typed errors", but FlagErrorf no longer exists (the typed-error migration replaced it with common.ValidationErrorf / errs.ValidationError); update the comment to reflect what is actually returned. - shortcuts/drive/drive_export.go:121 — drop the ValidateExport public alias and rename to validateExport. sheets +workbook-export reuses RunExport / PlanExportDryRun from this package but inlines its own (sheet-specific) Validate, so there is no cross-package call site — ValidateExport was a misleading sibling of the genuinely-shared ValidateImport. Comment added to record the asymmetry so future readers do not export it back. * chore(deps): drop stale indirect bumps left by the arrow removal The earlier --dataframe / --dataframe-out + apache/arrow/go/v17 removal deleted the arrow consumer but left two indirect lines in go.mod pinned to the versions arrow had pulled in: - github.com/kr/text v0.2.0 - golang.org/x/exp v0.0.0-20240222234643-814bf88cf225 With arrow gone, larksuite/cli was the only requirer of those exact versions; every real consumer needs lower ones (kr/pretty wants kr/text v0.1.0; charmbracelet/huh wants x/exp …20231006; xo/terminfo wants x/exp …20220909). Removing the two indirect lines and running `go mod tidy` lets MVS pick the real-consumer versions and drops the explicit indirect entries entirely — go.mod net-diff against main is now zero for this branch. Verified locally: go build ./...; go test ./shortcuts/sheets/... ./shortcuts/drive/... ./shortcuts/common/... ./internal/auth/... ./cmd/auth/... — all green. --------- Co-authored-by: zhengzhijie <zhengzhijie.j@bytedance.com> Co-authored-by: Chenweifeng-bd <chenweifeng.1534@bytedance.com>	2026-06-25 10:48:13 +08:00
xiongyuanwen-byted	b07a6003f9	feat(sheets): spec-driven shortcut refactor with backward-compatible package (#1220) ... * refactor(sheets): rebuild lark-sheets on sheet-skill-spec canonical + One-OpenAPI Restart lark-sheets as a spec-driven downstream. Skill content (SKILL.md and 16 references covering 13 operations skills + 3 workflow skills, including the standalone filter-view skill) is mirrored from the sheet-skill-spec canonical-spec; do not hand-edit, change upstream and rerun npm run sync:consumers. Drop the 11 legacy shortcut sources (spreadsheet / sheet management, cell ops, dropdown, filter-view, float image, etc.) and 10 associated tests. Wire up the new sheet_ai/v2 One-OpenAPI single entry that dispatches by tool_name with JSON-string input/output, and land the first canonical shortcut +workbook-info as a template that exercises the public token XOR pair, Risk tiering, and zero-side-effect DryRun. sheet_ai_api.go provides callTool / invokeToolDryRun and bypasses runtime.CallAPI's silent swallowing of non-envelope responses so gateway and business errors from the new endpoint surface precisely. The remaining 55 shortcuts will be designed and landed separately, canonical skill by canonical skill. * feat(sheets): implement lark_sheet_workbook shortcuts (B1) Land the 8 modify_workbook_structure shortcuts that round out the lark_sheet_workbook canonical skill alongside the existing +workbook-info: +sheet-create / +sheet-delete / +sheet-rename / +sheet-move / +sheet-copy / +sheet-hide / +sheet-unhide / +sheet-set-tab-color. All eight call modify_workbook_structure via the One-OpenAPI invoke_write endpoint, dispatched by the `operation` enum. Helpers in helpers.go grow publicSheetFlags() / resolveSheetSelector() / sheetSelectorForToolInput() / sheetSelectorPlaceholder() so future sheet-level shortcuts share the public --sheet-id / --sheet-name XOR treatment. +sheet-create intentionally drops the sheet selector pair since create has no existing-sheet anchor (matches the spec fix in tool-shortcut-map.json). +sheet-delete is the first high-risk-write shortcut in the canonical package; the framework requires --yes (exit code 10 otherwise). +sheet-move's tool requires source_index in addition to target_index. The CLI accepts an optional --source-index override and falls back to a single get_workbook_structure read to derive it (and to resolve sheet_id from --sheet-name). DryRun stays network-free by rendering <resolve> placeholders for any field that would need that read. * feat(sheets): implement lark_sheet_sheet_structure shortcuts (B2) Add 8 shortcuts under the lark_sheet_sheet_structure canonical skill: +sheet-info (get_sheet_structure) plus +dim-insert / +dim-delete / +dim-hide / +dim-unhide / +dim-freeze / +dim-group / +dim-ungroup (modify_sheet_structure, dispatched by operation enum). Two reusable conversion helpers cover the impedance mismatch between the CLI surface and the tool input: - dimRange / dimPosition translate the CLI's 0-based exclusive-end range into the tool's 1-based A1 notation. row 5..8 becomes position "6" + count 3 (insert) or range "6:8" (range ops); column 26..29 becomes "AA:AC". - infoTypeFromInclude maps the fine-grained --include vocabulary (row_heights / col_widths / merges / hidden_rows / hidden_cols / groups / frozen) to the coarse info_type enum the tool accepts; mixed categories collapse to "all". +dim-delete is high-risk-write (irreversible row/column removal). +dim-freeze --count 0 auto-dispatches to operation=unfreeze. +dim-group accepts --depth for forward-compat with a future server-side nested group endpoint but does not pass it through today. * feat(sheets): implement read_data / search_replace / write_cells shortcuts (B3) Land 11 shortcuts across three canonical skills: - lark_sheet_read_data (3): +cells-get / +csv-get / +dropdown-get - lark_sheet_search_replace (2): +cells-search / +cells-replace - lark_sheet_write_cells (6): +cells-set / +cells-set-style / +csv-put / +dropdown-set / +dropdown-update / +dropdown-delete +dropdown-get reads the data_validation field via get_cell_ranges with the range carrying its own sheet prefix (no --sheet-id needed). The fine-grained --include vocabulary (value / formula / style / comment / data_validation) maps to the tool's coarse include_styles bool plus value_render_option enum. +csv-get's --include-row-prefix=false strips the [row=N] prefix client-side because the tool only emits the annotated form. +cells-search / +cells-replace flatten the tool's options sub-object into four independent flags (--match-case / --match-entire-cell / --regex / --include-formulas) per the flat-flag rule, then repack them on the way in. +cells-set takes a raw --data JSON body whose `cells` array must match the --range dimensions. +cells-set-style fans a single --style block out to every cell in the range via a new fillCellsMatrix helper; the range parser (rangeDimensions / splitCellRef / letterToColumnIndex) only accepts rectangular A1:B2 forms — whole-column / whole-row need sheet totals and are deferred. +dropdown-set fans the validation block out to one range; +dropdown- update / +dropdown-delete iterate sheet-prefixed --ranges and call set_cell_range sequentially (partial failure leaves earlier ranges already mutated; the Tip calls this out). +dropdown-delete is high-risk-write and requires --yes. +cells-set-image stays deferred to the cli-only batch (needs the shared local-file upload helper alongside +workbook-create / +dim-move / +workbook-export). * refactor(sheets): move +dropdown-update / +dropdown-delete to lark_sheet_batch_update Follow-up to B3 after the spec re-mapped these two shortcuts to the batch_update tool (atomic multi-range CRUD) instead of fan-out via set_cell_range. Drop their Go implementations + helper validateDropdownRanges + splitSheetPrefixedRange from lark_sheet_write_cells.go and remove the registrations from Shortcuts(); the shortcuts will reappear under lark_sheet_batch_update during B7. Also pull in the re-rendered reference docs: - skills/lark-sheets/references/lark-sheets-write-cells.md - skills/lark-sheets/references/lark-sheets-batch-update.md * feat(sheets): implement lark_sheet_range_operations shortcuts (B4) Land 8 shortcuts across four canonical tools: - clear_cell_range → +cells-clear (high-risk-write) - merge_cells → +cells-merge / +cells-unmerge - resize_range → +dim-resize - transform_range → +range-move / +range-copy / +range-fill / +range-sort Three CLI↔tool vocabulary bridges live in this file: - +cells-clear: --scope content normalizes to the tool's clear_type "contents" (singular/plural spec mismatch is absorbed in the CLI). - +dim-resize: --size <px> wraps as resize_{height,width}:{value:N}; --reset wraps as {reset:true}. The two flags are mutually exclusive and at least one is required. - +range-fill: CLI's five-valued --series-type collapses to the tool's binary fill_type — `copy` → "copyCells", anything else → "fillSeries" (the actual series progression is inferred server-side from the seed cells in --source-range). - +range-copy: --paste-type {values, formulas, formats} maps to the tool's {value_only, formula_only, format_only}; "all" omits the field entirely so the server applies its default. +cells-clear is the second high-risk-write shortcut in the package; the framework enforces --yes with exit code 10 as usual. * feat(sheets): implement object-list shortcuts (B5) Land 7 read shortcuts, one per object skill — chart / pivot table / conditional format / filter / filter view / sparkline / float image. All share the same shape (public sheet selector + optional <obj>-id filter) so they're declared via newObjectListShortcut + an objectListSpec. Notes: - +cond-format-list exposes --rule-id, which is renamed to conditional_format_id on the wire (the tool's full field name). - +sparkline-list exposes --group-id (the higher-level handle); the tool also accepts sparkline_id, intentionally not surfaced. - +filter-list takes no id filter — at most one sheet-level filter per sheet, so the listing is already unique. - +filter-view-list is `cli_status: cli-only` but get_filter_view_objects is in mcp-tools.json and dispatches through the same One-OpenAPI endpoint; no special path required. * feat(sheets): implement object CRUD shortcuts (B6) Land 21 shortcuts — three (create / update / delete) per object skill — backed by the manage_<obj>_object tools dispatched on the operation enum. Five standard objects (chart / cond-format / sparkline / float-image / filter-view) share an objectCRUDSpec factory; pivot and filter are special-cased. Shared wire contract: excel_id + sheet_id|sheet_name + operation + [<obj>_id] + [properties] CLI --data is passed through as the tool's `properties` field as-is, so callers shape it per each object's spec doc. Special cases: - pivot adds optional --target-sheet-id / --target-position on create (siblings of properties, not inside it). - cond-format exposes --rule-id (short CLI name) wired to the tool's conditional_format_id on the wire. - sparkline uses --group-id (higher-level object handle) instead of sparkline_id. - filter has no separate id flag — at most one filter per sheet, so filter_id is implicit. +filter-create promotes --range to a first- class flag (instead of burying it inside --data). - filter-view CRUD are `cli_status: cli-only` but manage_filter_view_object is in mcp-tools.json, so they go through callTool / One-OpenAPI alongside everything else. All delete shortcuts are high-risk-write and require --yes. * feat(sheets): implement lark_sheet_batch_update shortcuts (B7) Land 4 shortcuts that all funnel through the batch_update tool's atomic operations array: - +batch-update raw passthrough; --data carries the full { operations: [{tool, params}, ...] } payload plus optional continue_on_error. high-risk-write since the caller may stuff anything inside. - +cells-batch-set-style --data is [{ranges, style}, ...]; CLI flattens each (entry × range) pair into a set_cell_range op with a fan-out cells matrix carrying cell_styles + border_styles. - +dropdown-update --ranges + --options (+ --colors / --multiple / --highlight) — installs/replaces one dropdown across many ranges, each becoming a separate set_cell_range op with data_validation in cells. - +dropdown-delete --ranges — clears data_validation across many ranges (high-risk-write). Default is strict transaction: if any sub-tool fails the whole batch rolls back. +batch-update exposes --continue-on-error to flip the policy; the three fan-out shortcuts leave it strict (they're meant to be all-or-nothing). Reinstates validateDropdownRanges + splitSheetPrefixedRange that were removed during B3 → B7 relocation. * feat(sheets): implement cli-only shortcuts (B8) — 70/70 complete Land the four cli-only shortcuts that can't route through the One-OpenAPI dispatcher (their backing capabilities aren't in mcp-tools.json): - +workbook-create POST /open-apis/sheets/v3/spreadsheets + optional set_cell_range follow-up that zips --headers and --data into the first sheet starting at A1. - +workbook-export POST /open-apis/drive/v1/export_tasks (type=sheet) → poll /export_tasks/:ticket up to ~30s → optional GET /export_tasks/file/:file_token/download. CSV mode requires --sheet-id (single sheet export). - +dim-move POST /open-apis/sheets/v2/spreadsheets/:token /dimension_range CLI is 0-indexed inclusive (--start / --end); the v2 endpoint expects half-open [startIndex, endIndex) so the body uses endIndex = --end + 1. --sheet-name is resolved client-side to sheet_id via lookupSheetIndex when needed. - +cells-set-image common.UploadDriveMediaAll (parent_type=sheet_image, parent_node=token) then callTool set_cell_range with cells carrying rich_text: [{type:"embed-image", attachment_token, attachment_name}]. --range must be exactly one cell. All four use runtime.CallAPI / DoAPI directly; only +cells-set-image combines a legacy upload with the new One-OpenAPI for the second step (set_cell_range is in mcp-tools.json so callTool is the right path). This closes the migration: 70 shortcuts × 17 canonical skills × matching the sheet-skill-spec v0.5.0 tool-shortcut-map. * test(sheets): cover all 70 shortcuts with dry-run + execute-path tests Twelve _test.go files alongside the implementation, mirroring the legacy package's coverage style: - testhelpers_test.go shared rig: TestFactory + Mount + dry-run capture + JSON-input decode + envelope helpers. - lark_sheet_*_test.go one test file per implementation file (9 files), table-driven dry-run cases per shortcut plus targeted validation guards. - execute_paths_test.go end-to-end execute paths via httpmock stubs. Covers callTool unwrap, JSON-string output decoding, two-step lookup (+sheet-move), batch_update fan-out, dropdown atomic writes, and the legacy OAPI shortcuts (+workbook-create, +dim-move) including CLI inclusive → API half-open index conversion. Test coverage on the sheets package is 60.5 % of statements with -race clean, meeting the dev manual's ≥ 60 % patch-coverage gate. * refactor(sheets): inline cli-only shortcuts into their canonical skill files Two naming cleanups: - lark_sheet_cli_only.go is gone. The four shortcuts it grouped (+workbook-create / +workbook-export / +dim-move / +cells-set-image) were bundled by their implementation pattern (legacy OAPI direct calls) rather than by canonical skill. The whole sheets package IS the CLI implementation, so "cli only" wasn't a meaningful grouping at the Go layer. Each shortcut now lives next to its skill peers: +workbook-create / +workbook-export → lark_sheet_workbook.go +dim-move → lark_sheet_sheet_structure.go +cells-set-image → lark_sheet_write_cells.go Per-skill shortcut counts now match tool-shortcut-map.json exactly (workbook: 11, sheet_structure: 9, write_cells: 5). Helpers (buildInitialFillInput, pollExportTask, downloadExportFile, dimMoveBody) move with their shortcuts; nothing else in the package referenced them. - testhelpers_test.go → helpers_test.go. The _test.go suffix already conveys "test"; the leading "test" was redundant. Matches the helpers.go naming convention. Behavior unchanged. go test -race -cover stays at 60.5 %. * refactor(sheets): sync shortcut flags with sheet-skill-spec v0.5.0 Upstream hoisted a batch of high-frequency scalar fields out of --data into independent flags and renamed several composite-JSON flags to match their semantic content. CLI catches up. Renames (drop-in, same payload semantics): - +cells-replace --replace → --replacement - +cells-set --data → --cells - +workbook-create --data → --values - +batch-update --data → --operations (now a bare array; still accepts the envelope form for back-compat with continue_on_error) Flat-flag hoists out of --style / --data: - +cells-set-style / +cells-batch-set-style --style JSON drops; replaced by 11 flat style flags (--background-color / --font-color / --font-size / --font-style / --font-weight / --font-line / --horizontal-alignment / --vertical-alignment / --word-wrap / --number-format) plus --border-styles for the one field that's still nested. Both shortcuts share styleFlatFlags() + buildCellStyleFromFlags(). - +cells-batch-set-style also drops the [{ranges, style}] array shape in favor of one --ranges + the same flat style flags applied to all of them. Object CRUD --data → --properties everywhere (chart / pivot / cond-format / filter / filter-view / sparkline / float-image). Per-skill scalar hoists merged into properties via an enhanceCreate/UpdateInput callback: - +pivot-create adds --source (required), --range (and continues to expose --target-sheet-id / --target-position at top level) - +cond-format-{create,update} adds --rule-type (enum) + --ranges (JSON array); merged into properties.rule.type and properties.ranges respectively - +filter-view-{create,update} adds --view-name and --range; both override their properties.* counterparts - +filter-update adds first-class --range (was buried in --data) Float-image is fully hoisted — no --properties flag at all. Ten flat flags (--image-name / --image-token | --image-uri / --position-row / --position-col / --size-width / --size-height / --offset-row / --offset-col / --z-index) compose the properties block. Implemented as its own factory (newFloatImageWriteShortcut) since it diverges from the shared CRUD spec. Tests track every flag renamed and add explicit cases for the new flag combos. go test -race -cover stays at 60.3 %. * refactor(sheets): align batch_update + cells-set with synced reference docs Sync to upstream reference doc updates for 9 skills: - batch_update sub-ops: rewrite wire fields tool/params -> tool_name/input in CellsBatchSetStyle and DropdownUpdate/Delete fan-out (the actual server contract per Schemas section); update --operations flag desc and tests. - +cells-set --cells: accept bare 2D matrix [[{cell},...],...] instead of envelope {"cells":[[...]]}; spec example shows bare-array form. - sparkline createDataDesc enum: win_loss -> winLoss (camelCase). All other doc changes (float-image flat flags, cond-format --rule-type/--ranges, pivot create-only --source/--range, filter / filter-view extra flags, chart --properties) were already aligned in commit ce33315. * fix(sheets): repair cells-set-image rich_text embed payload The server rejected set_cell_range calls from +cells-set-image with three distinct errors: missing "text" property, missing image_width/image_height, and unknown attachment_token field. Realign the rich_text element to the embed-image schema (text/image_token/image_width/image_height) and decode PNG/JPEG/GIF dimensions from the local file before the write. * refactor(sheets)!: split +dim-resize into +rows-resize and +cols-resize Sync to upstream spec change that splits the legacy +dim-resize shortcut into +rows-resize and +cols-resize. Reasoning is that row vs column resize has divergent semantics (only rows support auto-fit) and the shared --dimension flag was hiding that. Behavior changes (BREAKING): - +dim-resize is removed; use +rows-resize or +cols-resize. - --dimension and --reset flags are gone. - --type enum replaces --size/--reset: pixel (requires --size) standard (reset to sheet default; no --size) auto (auto-fit row height; +rows-resize only) - --end is now inclusive (was exclusive). Old "--start 0 --end 5" (5 rows) becomes "--start 0 --end 4". - Wire payload for resize_height / resize_width changes from {value: N} | {reset: true} to {type: "pixel", value: N} | {type: "standard"} | {type: "auto"}. Tests cover both shortcuts across pixel / standard / auto and the new guard surface (--type pixel needs --size; standard/auto reject --size; +cols-resize rejects --type auto; --end < --start). Also pulls in synced reference docs for 5 skills (batch-update, core-operations, range-operations, sheet-structure, visual-standards) that update prose mentions of +dim-resize. * feat(sheets): add --print-schema runtime introspection for composite JSON flags Composite JSON flags (--cells / --properties / --operations / --border-styles / --sort-keys / --options) carry non-trivial structured payloads. Reference docs cover top-level fields but agents writing those flags often need the full JSON Schema to build a valid payload. This adds a system-level introspection contract so any shortcut whose flags are tracked upstream can serve its schemas locally: lark-cli sheets <shortcut> --print-schema --flag-name <name> lark-cli sheets <shortcut> --print-schema # list flags The schema data is embedded at build time from a synced artifact (shortcuts/sheets/data/flag-schemas.json). Upstream is the source of truth — never hand-edit the JSON; update the source Base table and rerun the sheet-skill-spec sync. Framework changes (shortcuts/common): - types.go: Shortcut gains an opt-in PrintFlagSchema hook (flagName -> bytes/error). When non-nil the framework auto-injects --print-schema / --flag-name and short-circuits Validate/Execute. - runner.go: register the two system flags when PrintFlagSchema is set; intercept in runShortcut before identity/scope/config so pure-local lookups don't trigger auth or network. Install a PreRunE that relaxes cobra's required-flag gate when --print-schema is set, since asking for a schema shouldn't need unrelated required flags. Sheets surface (shortcuts/sheets): - flag_schema.go (new): go:embed data/flag-schemas.json; expose printFlagSchemaFor(command) closure. When flagName is empty it emits a JSON listing of introspectable flags for discovery; otherwise it returns the schema subtree as pretty JSON. - flag_schema_test.go (new): cover embed parsing, listing / by-name lookup, unknown-flag error path, registration via Shortcuts(), and the full system-flag short-circuit through cobra (required flags relaxed, schema printed on stdout). - shortcuts.go: Shortcuts() now wraps shortcutList() and attaches PrintFlagSchema to every command present in flag-schemas.json, so shortcuts opt in by being listed upstream — no per-shortcut boilerplate. - data/flag-schemas.json (new, synced from sheet-skill-spec): 19 entries, schema_version "2". Generated upstream from the Lark Base source-of-truth (see sheet-skill-spec scripts/fetch_cli_flag_schema_map.mjs); ships only per-flag subtrees (not the full mcp-tools.json) to keep tool internals out of the open-source repo. Skill docs (skills/lark-sheets): - SKILL.md: system-flag table gains --print-schema / --flag-name and an "Agent 使用提示" note steering agents to prefer --print-schema over guessing JSON shape from the cheatsheet. - references/*.md: regenerated by upstream sync (Schemas-section boilerplate updated, plus accumulated upstream prose refinements). * docs(sheets): remove sandbox references and normalize tool names to CLI shortcuts Replace export_sheet_to_sandbox / import_sandbox_to_sheet / doubao_code_interpreter with local-script + batch csv-get/csv-put workflows; unify legacy MCP tool names (set_cell_range, get_range_as_csv, etc.) to CLI shortcut format (+cells-set, +csv-get). * feat(sheets): add flag-descriptions.en.json and wire applyFlagDescs into Shortcuts() Embed data/flag-descriptions.en.json (synced from upstream spec) and apply it at shortcut assembly time so every Flag.Desc is sourced from the canonical JSON rather than hardcoded Go strings. Existing hardcoded Desc values serve as fallback for flags not yet in the JSON. Also sync reference doc updates from upstream. * feat(shortcuts): support int64 and float64 flag types Flag.Type previously could not express non-integer numbers. Add int64 and float64 cases to flag registration plus Int64/Float64 runtime accessors. * refactor(sheets): build shortcut flags generically from flag-defs.json Replace flag-descriptions.en.json with the richer flag-defs.json (full flag definitions: type / default / enum / input / hidden / required / kind) synced from sheet-skill-spec. Add flagsFor(command) to materialize each shortcut's []common.Flag straight from the JSON, skipping system-kind flags the framework injects. Migrate every sheets shortcut (including the CRUD/list/dim/merge/ visibility factories) to Flags: flagsFor("+command"), dropping all hand-written flag literals plus the now-dead publicTokenFlags / publicSheetFlags / styleFlatFlags helpers and enum vars. A coverage test locks the Go-flags-match-JSON contract. Align Go with the new spec where they diverged: +cells-get --ranges → --range, font-size int → float64, +filter-view-create --range now required, +sheet-create row/col-count defaults 200/20. * docs(sheets): sync +batch-update CLI override schema (shortcut/input form) Pulled from sheet-skill-spec: - skills/lark-sheets/references/lark-sheets-batch-update.md: --operations now documents the {shortcut, input} form; tool_name references gone - shortcuts/sheets/data/flag-schemas.json: --operations resolves to the CLI-side array<{shortcut(enum), input}> schema, sourced from spec's canonical-spec/tool-schemas/cli-schemas.json (cli: prefix). +dropdown --options also drilled one level deeper NOTE: the binary still raw-passes --operations to MCP batch_update which expects {tool_name, input}. A follow-up will add a shortcut→tool_name translation layer (with per-shortcut operation field) before the docs become actionable. * feat(sheets): translate +batch-update sub-ops {shortcut,input} → MCP shape Users now hand +batch-update --operations a CLI-shape array ([{shortcut, input}, ...]) and the binary translates each sub-op to the underlying MCP batch_update shape ({tool_name, input(+operation)}) via a new dispatch table in shortcuts/sheets/batch_op_dispatch.go. Dispatch table covers 50 batchable write shortcuts. Excluded by design: - all read ops - fan-out wrappers (+batch-update self, +cells-batch-set-style, +dropdown-update, +dropdown-delete) — nesting these = nested batch - +dim-move — single shortcut uses legacy v2 /dimension_range endpoint, not MCP, can't be batched - +cells-set-image — multi-step image upload, not atomic-batch friendly - +workbook-create — new workbook, not batch-on-existing semantics Translator also rejects sub-ops that hand-fill input.operation (implied by shortcut name) or input.excel_id / spreadsheet_token / url (set once at +batch-update top level). +dim-freeze always injects operation=freeze; the count==0 unfreeze path of the single shortcut is intentionally not supported in batch — callers should use the single shortcut for unfreeze. Tests cover: end-to-end translation, --continue-on-error propagation, 13 rejection cases (banned shortcuts, malformed shapes, reserved keys). Sync'd from sheet-skill-spec: skills/lark-sheets/references/ lark-sheets-batch-update.md + shortcuts/sheets/data/flag-schemas.json pick up the corrected enum (+cells-set-style / +dropdown-set added, +dim-move removed). * fix(sheets): make +batch-update sub-ops reuse standalone flag→body translators Sub-ops previously near-passed-through their input, so any shortcut whose standalone translator renames fields broke inside a batch: +range-copy lost range/destination_range (transform_range errored "range missing") and +rows-resize lost range/resize_height ("No resize operation specified"). Introduce a flagView interface (satisfied by *common.RuntimeContext) and a map-backed mapFlagView, then route every batchable sub-op through the SAME *Input builder the standalone shortcut uses. mapFlagView seeds flag-defs.json defaults for value reads while keeping Changed() user-driven, so a sub-op body is byte-identical to the standalone body — locked by a batch-vs-standalone contract test over all ~40 batchable shortcuts. Also fix single-row/column resize: start==end now formats as "23:23" / "C:C" (resize_range rejects a bare "23"); dimRangeFull keeps both sides while dimRange's collapse stays for modify_sheet_structure consumers. * fix(sheets): align +cells-get/+csv-get range flags with synced spec sheet-skill-spec now declares +cells-get --range as a single string (was string_array) and +csv-get --range as required. Match the flag→body translators: - +cells-get wraps the single --range into the tool's `ranges` array and validates with Str() instead of StrArray(), which silently returned nil against the now-String flag and broke the command. - +csv-get gains a trim-based required-range guard. Update read-data dry-run tests to single-range form and add a guard test for the empty --range path. * fix(sheets): push +batch-update sub-op validation down into xxxInput builders Sub-ops that omit --sheet-id (or any other required flag) used to slip past CLI validation — Validate ran only against the standalone shortcut path, and batchOpDispatch's translators built bodies from whatever flagView returned, so a structurally broken sub-op surfaced as an opaque server "sheet undefined not found" after a network round-trip. Push each batchable shortcut's check trio down into its xxxInput builder: 1. resolveSpreadsheetToken — stays in Validate (batch already does it once at the top level; sub-ops don't repeat). 2. requireSheetSelector(sheetID, sheetName) — new helper; flagView- agnostic XOR + control-char check, called at the top of every xxxInput. 3. shortcut-specific required / range / enum checks (--dimension, --range, --start <= --end, --type pixel needs --size, --float-image-id, image-token XOR image-uri, ...) — moved out of Validate into the builder body. All ~30 batchable xxxInput builders now return (map, error). Standalone Validate shrinks to validateViaInput(xxxInput); DryRun / Execute propagate the error. batch_op_dispatch entries drop the noErrTranslate wrapper and pass the builder directly — its error bubbles up wrapped with "operations[N] (+shortcut):" context. Tests: - TestBatchOp_ErrorEquivalence (7 cases): XOR / logical-constraint errors fire identically from standalone and batch sub-op paths. - TestBatchOp_RejectsBadSubOpInput (8 cases): cobra-required flags that standalone catches via MarkFlagRequired now also get rejected CLI-side on the batch path (where cobra is not in the loop). - TestBatchOp_BodyMatchesStandalone (~40 cases) and TestBatchOp_DispatchCoversReportedBugs continue to pass — bodies stay byte-identical. - BOE smoke (spreadsheet ICFwstkUGheyfptGWS2bB7RgcDf, sheet 51991c): +batch-update with a sub-op missing --sheet-id now returns "operations[0] (+dim-insert): specify at least one of --sheet-id or --sheet-name" before any network call. sheetMoveBatchInput (xiongyuanwen's batch-only explicit-source-index requirement) is preserved — it's an orthogonal batch-specific constraint not affected by this push-down. * fix(sheets): align +cond-format / +filter with server schema (#4 + #5) Two latent bugs in the object_crud translator surfaced during BOE smoke testing of +batch-update. Both are schema-alignment fixes against manage_conditional_format_object / manage_filter_object as declared in sheet-skill-spec/canonical-spec/tool-schemas/mcp-tools.json. #4 +cond-format: rule_type path + enum vocabulary --------------------------------------------------- condFormatEnhance used to write the user's --rule-type value into `properties.rule.type` (nested under a `rule` object). The server schema actually puts it at flat `properties.rule_type` and silently drops the nested form — so every conditional-format create/update secretly built the wrong document. Worse, the CLI enum exposed via flag-defs.json was its own invented vocabulary (cellValue / formula / duplicate / unique / topBottom / aboveBelowAverage / dataBar / colorScale / iconSet / textContains / dateOccurring / blankCell / errorCell) — none of those values were the strings the server accepts. Fix: - condFormatEnhance now writes `properties.rule_type = <value>` directly (no nested `rule` object). - Synced flag-defs.json + lark-sheets-conditional-format.md enum vocabulary from base to match the server: duplicateValues, uniqueValues, cellIs, containsText, timePeriod, containsBlanks, notContainsBlanks, dataBar, colorScale, rank, aboveAverage, expression, iconSet. - ⚠️ Breaking: scripts passing the old CLI-invented enum values (e.g. --rule-type cellValue) now get a cobra "invalid value … allowed: …" error listing the new vocabulary. No alias layer. - TestObjectCRUDShortcuts_DryRun's +cond-format-update case updated to assert the flat properties.rule_type shape + new enum. #5 +filter-{update,delete}: auto-inject filter_id = sheet_id ------------------------------------------------------------- manage_filter_object's contract is "filter_id === sheet_id" for the sheet-scoped filter (per per-tool description in mcp-tools.json), and update / delete operations MUST carry filter_id. Standalone filterUpdateInput / filterDeleteInput never set it, so the server rejected with "filter_id is required for update/delete operation" on every call — both standalone AND inside +batch-update. Fix: - filterUpdateInput / filterDeleteInput now set input["filter_id"] = sheetID. - Because filter_id must equal sheet_id (not sheet_name), update / delete reject when only --sheet-name is given — there's no network lookup available inside the builder. The friendly error points at +workbook-info for resolving sheet-name → sheet-id. - create still omits filter_id (server requires that — id is server-allocated on creation). - New tests: * TestObjectCRUDShortcuts_DryRun gains a +filter-update happy-path case asserting filter_id is auto-injected + --range hoisting. * +filter-delete case updated to assert filter_id presence. * TestBatchOp_RejectsBadSubOpInput gains two cases asserting both +filter-update and +filter-delete reject --sheet-name-only with the friendly error. Docs (#2 + #3 + #8) synced from sheet-skill-spec ------------------------------------------------- Companion doc fixes that landed via npm run generate:cli + sync:cli in sheet-skill-spec; included here because the regenerated flag-defs and references markdown are byte-tracked in this repo: - #2: lark-sheets-sheet-structure.md — +dim-{hide,unhide,group, ungroup} --start/--end desc changed from "(0-based, inclusive)" to "(0-based)" / "(exclusive)" to match the half-open range semantics the code has always implemented (requireDimRange: end > start; dimRange uses end - 1 for column end letters). - #3: lark-sheets-workbook.md — +sheet-move section gains a note about the batch-internal requirement to pass --sheet-id AND --source-index explicitly (sheetMoveBatchInput's constraint). - #8: lark-sheets-pivot-table.md — +pivot-create --properties example drops the stale data_range field (the actual server schema uses --source as a hoisted flag; properties only carries rows / columns / values / filters / show_*_grand_total). * feat(sheets): add +cells-batch-clear fan-out over batch_update Clear content/formats across many sheet-prefixed ranges in a single atomic batch_update (one clear_cell_range op per range), mirroring the existing +cells-batch-set-style / +dropdown-{update,delete} fan-out wrappers. The --scope to clear_type normalization is shared with standalone +cells-clear (normalizeClearType) so the two stay in lockstep. high-risk-write (requires --yes); rejected as a batch sub-op like the other fan-out wrappers. flag-defs/flag-schemas and skill docs updated to match. * docs(sheets): sync stdin guidance and sparkline reference - skills/lark-shared/SKILL.md: drop the generic "prefer stdin" section - skills/lark-sheets/SKILL.md: add expanded stdin guidance (use stdin over @file abs paths; don't cd or write into the project dir) - skills/lark-sheets/references/lark-sheets-sparkline.md: document the group_id / sparkline_id two-tier model with worked examples * fix(sheets): require sparkline_id on +sparkline-update items (#6) manage_sparkline_object uses two layers of IDs: --group-id picks the sparkline group, and properties.sparklines[i].sparkline_id picks each item inside the group. The server contract requires sparkline_id on every update item (server maps each entry back to an existing sparkline by this id). Agents that called +sparkline-update without the per-item ids hit an opaque server-side rejection that didn't mention sparkline_id at all, then got stuck in a try-fail-list-retry loop. Pre-check CLI-side in objectUpdateInput via a new validateUpdateInput hook on objectCRUDSpec. sparklineSpec wires validateSparklineUpdateItems, which walks properties.sparklines[] and rejects with a message that points at +sparkline-list: +sparkline-update properties.sparklines[N] missing sparkline_id (run `+sparkline-list --group-id <id>` first to read sparkline_id for each item, then echo each id back on the corresponding update entry) Scope is update-only. config-only updates (properties.config without sparklines) stay legal — the validator skips when sparklines is absent. Delete is not pre-checked: objectDeleteInput doesn't pass properties through, so the partial-delete branch can't be reached today (separate follow-up). Tests: - TestObjectCRUDShortcuts_DryRun: positive case for update with sparkline_id present. - TestSparklineUpdate_MissingSparklineID: standalone path — error contains both "missing sparkline_id" and "+sparkline-list". - TestBatchOp_RejectsBadSubOpInput: batch sub-op missing sparkline_id rejected with the same friendly error. Docs synced from sheet-skill-spec (canonical change committed there): skills/lark-sheets/references/lark-sheets-sparkline.md documents the two-layer id model, the three "+sparkline-list first" cases, and both delete modes. * docs(sheets): sync lark-sheets skill from spec (audit 20260521) Pull latest spec from sheet-skill-spec (PR ee/sheet-skill-spec!6 + earlier develop commits) into skills/lark-sheets/ and shortcuts/sheets/data/. Audit findings now reflected in CLI docs: - A2 +cond-format-create example: --rule-type duplicate → duplicateValues - A3 +cond-format-create Validate: cellValue/formula → cellIs/expression - A5 +csv-put examples: --range → --start-cell; drop redundant --allow-overwrite - A7 +sparkline-create: Validate / Examples aligned with real schema (config/sparklines), executable JSON example added - B13 cross-doc dead links: lark_sheet_*/cli-shortcuts.md → lark-sheets-*.md - C2 +csv-put: `=` literal warning next to Examples - CC5 +rows-resize/+cols-resize --type auto: single point of truth in range-operations reference flag-defs.json description / required sync (from base): - A4 +float-image-update: image-name/position-*/size-* required → optional (patch mode) - A8 +dim-move --start/--end description cleanup - B3 +pivot-create --properties: data_range → source (real field name) Also picks up the +cells-batch-clear shortcut doc (introduced in spec develop). Go-side implementation for that shortcut is intentionally not in this PR — docs-only preview; runtime dispatch will land in a follow-up. `go test ./shortcuts/sheets/...` passes. * feat(sheets): add +cells-set --copy-to-range and sync skill spec Sync lark-sheets skill references and flag schemas from upstream sheet-skill-spec, and wire the newly-specced --copy-to-range flag into +cells-set: it passes copy_to_range to the set_cell_range tool so a template block written via --cells fans out across a larger range with auto-shifted formula refs. * docs(sheets): sync lark-sheets skill spec (chart/pivot wire mappings, --end semantics) Sync skill references and flag-defs descriptions from upstream sheet-skill-spec: clarify +chart-create properties structure (snapshot.data), +pivot-create --target-position / --range wire-field mappings, add a cross-command --end endpoint-semantics table (insert/delete/hide/group exclusive vs move/resize inclusive), note --group-state default, and rename reference identifiers to lark-sheets-*. Description-only refinement; the existing CLI implementation already matches the clarified wire mappings and --end semantics. * fix(sheets): make --max-chars the single read cap for +cells-get / +csv-get Drop --cell-limit (+cells-get) and --max-rows (+csv-get) from the CLI surface and pin the underlying tool's cell_limit / max_rows to a very large sentinel so the tool's own defaults never truncate before --max-chars. --max-chars stays the only knob (default 200000, unchanged). - lark_sheet_read_data.go: add unboundedReadLimit (1e9); cellsGetInput pins cell_limit, csvGetInput pins max_rows; --max-chars still passed through - data/flag-defs.json: synced from spec (drops the two flags) - tests: spot-check moved to --max-chars; dry-run wantInput asserts cell_limit / max_rows are pinned high Mirrors sheet-skill-spec (Base flag records removed). go build ./... + go test ./shortcuts/sheets/ green. * docs(sheets): sync lark-sheets read docs — --max-chars as single read cap Sync skills/lark-sheets references from spec: drop --cell-limit / --max-rows guidance; 大表分批读 switches to --range row windows + --max-chars auto cap + has_more. Mirrors sheet-skill-spec 58e7456 and handler change 2befc49. * docs(sheets): sync lark-sheets skill spec from upstream Refine reference docs and flag-defs descriptions from upstream sheet-skill-spec (--depth wording for +dim-group / +dim-ungroup, plus assorted reference clarifications). Description-only; no CLI behavior or flag surface change. * docs(sheets): sync chart properties schema (position/size required) Regenerate flag-schemas.json from upstream sheet-skill-spec: the chart properties schema now marks position and size as required, and the chart reference doc reflects the same. flag-schemas.json is print-schema-only (no client-side validation), so this is a generated-artifact + doc sync with no CLI behavior change. * docs(sheets): sync lark-sheets skill spec from upstream Refine reference docs and flag-defs descriptions from upstream sheet-skill-spec: clarify +workbook-export sheet flag scope, +filter-* --properties optionality (omitted => empty filter on --range; rules must be non-empty when provided), float-image reference_id wording, and assorted reference cleanups. Description-only; existing CLI behavior (filter passthrough, properties optional) already matches. * docs(sheets): sync lark-sheets skill spec from upstream Trim and refine reference docs from upstream sheet-skill-spec (condense core-operations workflow, tidy write-cells / range-operations / float-image / SKILL guidance). Description-only; no flag or CLI behavior change. * docs(sheets): sync lark-sheets skill spec from upstream Refine reference docs from upstream sheet-skill-spec (core-operations, formula-translation, visual-standards, SKILL guidance). Description-only; no flag or CLI behavior change. * fix(sheets): correct +workbook-create initial fill and +dim-move endpoint +workbook-create: the v3 create response does not echo the default sheet's id, so the initial-fill set_cell_range was sent with an empty sheet_id and rejected ("sheet_id or sheet_name is required"). Resolve the workbook's first sheet via get_workbook_structure before filling. +dim-move: the move request was POSTed to the v2 dimension_range endpoint (the add/update/delete surface, which requires a `dimension` object) and rejected with "[9499] Missing required parameter: Dimension". Switch to the native v3 move_dimension endpoint (sheet_id in path; snake_case source.{major_dimension,start_index,end_index} + destination_index). CLI --end and v3 end_index are both 0-based inclusive, so they pass through unchanged. * fix(sheets): align +workbook-create, +dropdown-*, +dim-move, +range-sort with server schema Five separate E2E failures in shortcuts/sheets/ that all trace back to a CLI ↔ server contract mismatch. Each is independently scoped; bundling them because they share the test-report citation and the same one-line fix shape in most cases. buildInitialFillInput sent {"sheet_id": ""} on the secondary set_cell_range call after creating the workbook. The empty value was a holdover from "...otherwise server picks first sheet" — but set_cell_range rejects an empty selector with "sheet_id or sheet_name is required" rather than falling back to the default sheet. Use sheet_name "Sheet1" instead. POST /sheets/v3/spreadsheets always creates that sheet on workbook creation, and set_cell_range accepts sheet_name as an equivalent selector — saves an extra get_workbook_structure round-trip just to learn the auto-generated id. buildDropdownValidation emitted four fields that don't exist in the canonical set_cell_range.data_validation schema: - "values" (options list) → renamed to "items" - "multiple_values" → renamed to "support_multiple_values" - "colors" (per-option color) → removed (not in schema; flag also removed from data/flag-defs.json for +dropdown-set / -update) - "highlight_options" → removed (not in schema; flag also removed) The canonical schema lives at sheet-skill-spec/canonical-spec/tool- schemas/mcp-tools.json (set_cell_range tool, data_validation property); the colors / highlight knobs were CLI inventions the server never accepted, so removing the flags is correct (renaming would leave the flags broken). Skill reference docs (write-cells.md, batch-update.md) synced. validateDropdownOptionsColors lost its colors check; renamed to validateDropdownOptions to reflect the narrower contract. dropdownGetInput sent "Sheet1!C2:C6" verbatim as a ranges[] entry. get_cell_ranges expects sheet_id / sheet_name as separate fields and ranges entries without the sheet prefix; the server bounced with "sheet not found, sheetId:" (empty). Use the existing splitSheetPrefixedRange helper (declared in lark_sheet_batch_update.go) to break "Sheet1!C2:C6" into ("Sheet1", "C2:C6"), then thread the sheet name through sheetSelectorForToolInput exactly like +cells-get does. The shortcut was POSTing to /sheets/v2/spreadsheets/{token}/dimension_ range, which is the v2 insert-dimension endpoint and requires a top- level {"dimension": {...}} body. Move uses a separate endpoint: POST /sheets/v2/spreadsheets/{token}/move_dimension body: { "source": {...}, "destination_index": N } (camelCase "destinationIndex" → snake_case "destination_index" to match the v2 contract.) Both DryRun and Execute updated, plus the TestDimMove_DryRun and TestExecute_DimMove assertions. transform_range.sort_conditions[i] requires both `column` (string) and `ascending` (bool); rangeSortInput passed the --sort-keys array through to the server unvalidated, so missing fields surfaced as opaque "required property X missing" errors with no per-item context. Walk the parsed array client-side, reject with item-pointing messages. Test fixtures and a contract-test fixture switched from the historical {col, order} vocabulary (which the server has never accepted) to the correct {column, ascending}. Server-schema citations and test-report case mapping in this branch's plan file. * revert(sheets): drop direct flag-defs.json edits — generated from spec data/flag-defs.json is regenerated from the upstream sheet-skill-spec canonical-spec; editing it here gets clobbered on the next sync. The schema realignment for +dropdown-set / -update --colors / --highlight removal needs to land on the base table first, then flow back through sheet-skill-spec → larksuite-cli sync, not via a direct CLI-side edit. Restore the previous flag entries verbatim. The Go-side change in buildDropdownValidation still drops the wire fields, so: - users passing --colors / --highlight today see the flag accepted silently (no effect on the wire) until the upstream removal lands; - after upstream removal + sync, both the flag declarations and the Go-side handling will be in sync. Functional fixes (#1 workbook-create, #3 dropdown-get, #4 dim-move, #5 range-sort) and dropdown wire-shape rename (#2) are unaffected. * revert(sheets): drop direct edits to skills/lark-sheets/references/ These md files are sync targets generated from sheet-skill-spec; editing them here gets clobbered on the next sync, same as data/flag-defs.json. The --colors / --highlight row removals belong on the upstream base table → canonical-spec sync, not here. Restore the previous --colors / --highlight rows in both lark-sheets-write-cells.md (+dropdown-set) and lark-sheets-batch-update.md (+dropdown-update). The Go-side change in buildDropdownValidation still drops the wire fields, so: - users passing --colors / --highlight today see the flag accepted silently (no effect on the wire) until upstream removes the flag; - after upstream removal + sync, both flag declarations, ref docs, and Go-side handling will be in sync. Functional fixes (#1 workbook-create, #3 dropdown-get, #4 dim-move, #5 range-sort) and dropdown wire-shape rename (#2) are unaffected. * docs(sheets): sync from sheet-skill-spec — remove dropdown --colors / --highlight Upstream sheet-skill-spec base table deleted the --colors and --highlight flags on +dropdown-set / +dropdown-update (the corresponding wire fields data_validation.colors / .highlight_options were never accepted by the server schema; see prior fix in this branch). Re-running the sync from canonical-spec brings the CLI flag-defs and skill reference docs back in line with the Go-side handling that already drops these fields. Generated by `npm run sync:cli` in sheet-skill-spec @ ac7acef. * fix(sheets): restore +dropdown --colors / --highlight, map to canonical fields Reverses the --colors / --highlight removal from 7932ab2 (item #2 of the batch-1 schema-alignment commit). That commit dropped both flags after the test report flagged data_validation.colors / highlight_options as "unexpected property" — at the time the canonical set_cell_range.data_validation schema listed only help_text / items / operator / range / support_multiple_values / type / values, so the flags had no server-side target and the removal was correct. Since then, set_cell_range.data_validation has gained two fields explicitly modelling the dropdown highlight UI (mcp-tools.json in sheet-skill-spec 2026-05-22 base sync): enable_highlight (bool) — show pill backgrounds highlight_colors (string[]) — hex pill colors, length must match items So the flags are back, but rewired: --colors -> data_validation.highlight_colors (was: colors) --highlight -> data_validation.enable_highlight (was: highlight_options) --options -> items and --multiple -> support_multiple_values renames from 7932ab2 are kept. Changes: - buildDropdownValidation: re-add --colors / --highlight handling against the new field names; --colors length check stays inline (so dropdownSetInput Validate path catches it via validateViaInput, no separate guard needed). - validateDropdownOptions -> validateDropdownOptionsColors: restore the Validate-time --colors length check on +dropdown-update / +dropdown-delete (called from lark_sheet_batch_update.go). - TestDropdownSet_CellsShape: extend to assert highlight_colors / enable_highlight emitted; assert legacy `colors` / `highlight_options` absent. - TestDropdownSet_ColorsLengthMismatch: new — covers the early Validate error path. - TestDropdownUpdate_BatchPayload: extend to cover dropdownBatchInput propagation of --colors / --highlight through batch_update. - skills/lark-sheets/references/lark-sheets-{write-cells,batch-update}.md, shortcuts/sheets/data/flag-defs.json, flag-schemas.json: synced from sheet-skill-spec generate output (MR !7). * chore(sheets): re-sync from spec + loosen --colors length check Catches up to sheet-skill-spec's 2026-05-25 base sync (MR !7) after rebasing onto upstream feat/lark-sheets-refactor (12 new upstream commits including the lark-sheets skill refactor + tools-schema migration). Spec changes flowing in: - highlight_colors description loosened: length may be **shorter than** --options (server cycles remaining slots through a built-in 10-color palette); previously the tool errored on any length mismatch. - shortcuts/sheets/data/flag-schemas.json: mass re-mirror — generator now emits `type` before `properties` and adds explicit `additionalProperties: false` on object schemas (cosmetic, no behavior change). - skills/lark-sheets/references/lark-sheets-{batch-update,chart,write-cells}.md: --options gains the type='list' tag; data_validation inline field-count goes 7 → 9 (catches up the highlight schema in the summary); chart position / size marked optional per upstream. Go-side adjustment: - buildDropdownValidation / validateDropdownOptionsColors: change the --colors length check from strict-equal to "must not exceed --options" to match the relaxed schema. - TestDropdownSet_ColorsLengthMismatch -> TestDropdownSet_ColorsLongerThanOptions (now hits the overflow path with 3 colors vs 2 options). - New TestDropdownSet_ColorsShorterAccepted: 2 colors vs 4 options is legal and forwarded as-is. * docs(sheets): sync dropdown --colors/--highlight clarification from spec Mirrors sheet-skill-spec MR !7 changes: - skills/lark-sheets/references/lark-sheets-write-cells.md: new "Dropdown 配色" section explaining how --colors (→ data_validation.highlight_colors) and --highlight (→ data_validation.enable_highlight) compose — length rule (shorter ok, longer rejected), --highlight gating, palette fallback behavior, minimal +dropdown-set example. - skills/lark-sheets/references/lark-sheets-batch-update.md: one-line pointer to the write_cells section for +dropdown-update / -delete (same rules). - shortcuts/sheets/data/flag-defs.json: --colors / --highlight `desc` fields gain the long-form server-field / length-rule descriptions used by `--help`. No Go-side change — earlier commit 538eb2e already loosened the buildDropdownValidation length check to "must not exceed"; this PR step just makes the docs / `--help` text catch up. * feat(sheets): +dropdown-set/-update --source-range for listFromRange mode Previously +dropdown-set / +dropdown-update only emitted data_validation.type=list — agents wanting listFromRange (dropdown options sourced from existing cells, kept in sync with that range) had to drop down to +cells-set and hand-build a data_validation map. The flag now exposes it natively as --source-range, paired with --options under XOR. CLI changes: - shortcuts/sheets/lark_sheet_write_cells.go: * new dropdownTypeAndItems(runtime) — central XOR resolver: rejects 0 or 2 of {--options, --source-range}, returns (sourceSize, partial dv with type+items|range filled in). Source size = options length for list mode, rangeDimensions(--source-range) cell count for listFromRange. * buildDropdownValidation rewritten to call the resolver, then layer --colors / --multiple / --highlight on top — semantics unchanged for callers, just two modes instead of one. * validateDropdownOptions / -Colors renamed to validateDropdownSourceOrOptions so the XOR + length check fires at +dropdown-update Validate time too. * --colors length error message generalized: "must not exceed dropdown source size (N)" (covers both modes). - shortcuts/sheets/lark_sheet_batch_update.go: rename call site. - shortcuts/sheets/lark_sheet_write_cells_test.go: 4 new tests — ListFromRange (happy path: range + items absent + colors + highlight all emit), ListFromRange_ColorsLongerThanCells (overflow against T1:T3 cell count), XorBothSet, XorNeitherSet. Updated the existing ColorsLongerThanOptions assertion to match the new "source size" wording. Spec-driven changes (synced via npm run sync:cli from sheet-skill-spec MR !7 2c298b6): - shortcuts/sheets/data/flag-defs.json: --options Required flips to xor on +dropdown-set/-update; new --source-range row gains long-form description pointing at server data_validation.range + the XOR semantics. - skills/lark-sheets/references/lark-sheets-write-cells.md: "Dropdown 配色" section reorganized into "Dropdown 选项 + 配色" — XOR comparison table (list vs listFromRange), shared config flag table (--highlight / --colors), explicit length rule covering both modes, side-by-side minimal examples, server-range-normalization gotcha callout. - skills/lark-sheets/references/lark-sheets-batch-update.md pointer updated to mention both modes + that +dropdown-delete is unaffected. PPE smoke (ppe_lark_cli_sheet) on UFJxszjrZhZ1LVtc9FdcICSbn6b C column: - +cells-set C1 → "性别" (bold + centered): updated_cells_count=1 - +dropdown-set --range C2:C21 --source-range "Sheet1!T1:T3" --colors '["#cce8ff","#ffd6e7","#e6e6e6"]' --highlight: updated_cells_count=20 - read-back: data_validation.type=listFromRange + range=$T$1:$T$3 (server normalizes the prefix away on storage; highlight_colors / enable_highlight not echoed by get_cell_ranges, see byted-sheet read projection TODO). - error-path replay (both XOR violations + colors > source-size) all rejected at Validate stage with the expected messages. * docs(sheets): sync agent-voice rewrite of Dropdown 选项+配色 from spec Mirrors sheet-skill-spec MR !7 60df610 — narrative now describes how the flags interact (XOR, colors length rule, highlight gating, sheet-prefix read-back gotcha) without exposing the underlying data_validation field names or server-side normalization details that agents don't act on. No Go-side change, no shortcut behavior change. * chore(sheets): restore --colors in parseJSONFlag docstring example list The earlier commit 49104ec swapped --colors out of parseJSONFlag's "Used by" example list when it deleted the flag (item #2 there removed --colors / --highlight from +dropdown-set/-update). Subsequent commits 8672d8e / 538eb2e / fb90c8b reinstated --colors (and added --source-range) but did not roll back this docstring tweak — leaving an orphan reference to --properties where --colors used to be. This restores the example list to its pre-49104ec form so the docstring matches what the helper actually services on this branch's HEAD. Pure docstring change — function behavior unaffected, no test movement. * fix(sheets): post-rebase test fixups after dropping superseded fix #1 Two test fallouts from rebasing onto upstream 4be06c8 (which independently re-fixed +workbook-create and +dim-move with a more thorough approach): - shortcuts/sheets/lark_sheet_workbook_test.go: our PR's earlier TestWorkbookCreate_DryRun "with headers and data → 2-step plan" subtest asserted the expedient sheet_name="Sheet1" / no-sheet_id wire body that matched our dropped fix #1 implementation. Upstream's fix #1 resolves the workbook's first sheet via get_workbook_structure and fills with the real sheet_id instead. Reset this file to upstream's version — our superseded assertions disappear, upstream's tests cover the new wire shape. - shortcuts/sheets/execute_paths_test.go: TestExecute_RangeSort fixture still used the legacy {col, order} sort-key shape because the rebase resolution picked the upstream version of this file wholesale (it contained other unrelated changes). Re-apply just the one fixture update to {column, ascending} so fix #5's CLI-side rejection logic exercises a valid input — server-side sort_conditions has required fields `column` (string) and `ascending` (bool); the historical {col, order} vocabulary was never accepted. go build ./... + go test ./shortcuts/sheets/... -count=1 both green. * feat(sheets): +dropdown --highlight tri-state via Changed() for opt-out The server-side default for data_validation.enable_highlight flipped from false to true (aligning with the UI behavior). With the previous code path if runtime.Bool("highlight") { dv["enable_highlight"] = true } omitting --highlight and passing --highlight=false both produced the same "enable_highlight key absent" body, leaving CLI users with no way to opt out of the (now-default) highlighting. Switch to runtime.Changed() so the translator can distinguish all three input shapes: - omitted -> no enable_highlight key (server applies default=true) - --highlight=true -> enable_highlight: true (explicit no-op vs default) - --highlight=false -> enable_highlight: false (the only opt-out path) flagView already exposes Changed() and mapFlagView (the +batch-update sub-op adapter) implements it via raw-key presence — same pattern other translators use for "Changed-only" branching (e.g. omit target_index unless --index was set), so no interface surface change is needed. Test coverage: - TestDropdownSet_HighlightTriState pins all four shapes (omit / presence form / explicit true / explicit false) and asserts the enable_highlight key's presence/value - TestBatchOp_BodyMatchesStandalone adds a --highlight=false sub-op case so the batch sub-op path produces a body byte-identical to the standalone +dropdown-set --highlight=false body * chore(sheets): sync +dropdown flag desc + write-cells narrative from spec Mirror sheet-skill-spec generated/ into shortcuts/sheets/data/ and skills/lark-sheets/ for the +dropdown-set / +dropdown-update path. No hand edits in this repo. The +dropdown flag desc and the Dropdown 配色 narrative now match the server-side enable_highlight default flip (true) and the tri-state --highlight semantics introduced in the sibling commit: * --highlight desc: 不传 = 开（按内置 10 色色板循环上色）， --highlight=false 关闭得到纯白下拉 * --colors desc: 单独传即生效（高亮默认开），--highlight=false 时忽略 * write-cells reference: 三种意图三条线（默认色板 / 指定颜色 / 纯白下拉）+ 新增 --highlight=false 示例 Source upstream: sheet-skill-spec MR !8. * fix(sheets): validate +cells-set-image --image path in Validate The unsafe-path check only ran at Execute (via FileIO.Stat), so --dry-run printed a misleading success preview for an absolute / out-of-cwd --image path that a real run would then reject. Move the path-safety check into Validate (validate.SafeLocalFlagPath), so --dry-run and Execute fail identically and both name the real --image flag. File existence stays deferred to Execute, so legitimate relative paths still preview cleanly. Add TestCellsSetImage_DryRunRejectsUnsafePath. * feat(sheets): support local --image in +float-image-create +float-image-create now accepts a local file via --image (XOR with --image-token / --image-uri): the CLI uploads it as a sheet_image and embeds the returned file_token, removing the previous "upload elsewhere to get a token first" workaround. Path safety is checked in Validate, --dry-run previews the extra upload step, and +batch-update rejects --image (no upload phase). +float-image-update is unchanged (it does not register --image). Also syncs the lark-sheets skill docs/flag-defs from sheet-skill-spec: the new --image flag, partial-merge / border-per-side / bare sheet-prefix clarifications, and refreshed dropdown --colors/--highlight descriptions (already pending in the source Base table). * fix(sheets): +dropdown-get accepts --sheet-id/--sheet-name + bare --range Align +dropdown-get with its get_cell_ranges siblings (+cells-get / +csv-get): sheet selection is now via --sheet-id / --sheet-name (XOR) and --range is a bare A1 reference. The previous shape required the sheet prefix inside --range (e.g. "Sheet1!A2:A100") and was the odd one out among the read-data wrappers; callers pasting the sheet-id form straight from the URL hit a misleading "sheet not found, sheetId: , sheetName: <id>" error because the prefix was unconditionally treated as sheet_name. Flag schema + skill reference regenerated from the upstream Lark Base Shortcut-flags table. * fix(sheets): drop Sheet1! prefix from +cells-get / +csv-get / +csv-put flag examples Server tools-schema.json for get_cell_ranges, get_range_as_csv and set_range_from_csv does not accept a sheet prefix on --range / --start-cell; the sheet is selected via --sheet-id / --sheet-name. +csv-put --start-cell also now states it must be a single cell (no range notation). Synced from spec repo. * feat: 把环境变量提交上去 * fix(sheets): clarify batch --ranges prefix must be sheet display name E2E test cases repeatedly trip on this: $ lark-cli sheets +cells-batch-set-style \ --ranges '["7f8fba!A2:B3","7f8fba!C2:D3"]' --font-color '#3366FF' ... → tool "batch_update" failed: [900015206] sheet "7f8fba" not found. Available sheets: [{id: "7f8fba", name: "Sheet1"}] Callers paste the hex sheet-id (e.g. "7f8fba") from a spreadsheet URL / +sheet-create response straight into the --ranges sheet prefix. The four batch shortcuts (+cells-batch-set-style / +cells-batch-clear / +dropdown-update / +dropdown-delete) fan each range out into a batch_update sub-op (set_cell_range / clear_cell_range) and pass the prefix through as sheet_name; the server only matches sheet_name literally, so the lookup fails. The set_cell_range tool schema is explicit: sheet_id is the reference_id and "must be correct or it errors"; sheet_name is the display name. CLI can't disambiguate purely from the literal because users can rename sheets to anything (including six-char hex strings). Cleanest fix is at the source: each batch shortcut's --ranges flag description now states explicitly that the prefix must be the sheet display name and that the sheet reference_id is rejected, so agents reading the reference don't try the id form in the first place. No Go changes; these files are regenerated from the upstream Lark Base Shortcut-flags table via the sheet-skill-spec sync chain. * docs(sheets): sync lark-sheets skill docs from upstream spec - SKILL.md: clarify --url only resolves /sheets/ and /spreadsheets/ links; /wiki/ links must be resolved via wiki +node-get first (confirm obj_type=sheet, use obj_token) - formula-translation: document IMPORTRANGE cross-workbook limits (max 5-level nesting, 100 refs per sheet) - write-cells: document rich_text cells for hyperlinks, @mentions and @docs * feat: 同步 tools-schema.json 改动 * fix(sheets): warn when +dropdown source-range exceeds 2000 cells with highlight on byted-sheet's ListFromRangeValidation.checkOptionsValid() sets isOptionError=true when shouldHighlightValidData is on and the source range exceeds LIST_WITH_COLOR_MAX_COUNT (2000 cells) — the highlight + large source combo is unsupported. CLI previously had no signal for this, so users only learned by seeing the dropdown render as option-error in the workbook. Add a Validate-phase stderr warning in +dropdown-set and +dropdown-update when --source-range covers >2000 cells unless --highlight=false. Soft warning, never blocks the request. Inline --options is not subject to this limit — server enforces no count or per-item length cap on inline lists, so no warning fires there. * docs(sheets): sync lark-sheets skill from spec — dropdown flag descs reflect server reality Pulls sheet-skill-spec canonical-spec → generated → consumers chain for dropdown flag desc corrections committed upstream (Shortcut-flags base table rows for +dropdown-set / +dropdown-update --options and --source-range). Aligns flag descs with byted-sheet behavior: - --options: dropped fabricated "≤500 items, each ≤100 chars, no commas" promise. byted-sheet ListOfItemValidation enforces none of these. - --source-range: appended note about the only real cap — LIST_WITH_COLOR_MAX_COUNT=2000 when --highlight is on (server flags the dropdown as option-error beyond that; CLI warns at Validate time per bb7ccae). Also picks up an unrelated upstream tools-schema.json drift (chart float block schema + data_validation.items description tweak) that surfaced via npm run check:tool-schemas; bundling keeps the spec sync gate green. * revert(sheets): drop tools-schema drift mirror from previous spec sync 930c9c7 顺带 sync 了 spec 的 tools-schema bundling — 跟那条 commit 一起 误带进来 chart float block required 和 data_validation.items 描述微调， 这两处其实是上游 sheet-ai-skills 还在 pending 的 revert。 配套 sheet-skill-spec 的 revert commit (a3aa9f2 on fix/dropdown-flag-desc-real-limits / !11)，重跑 sync:consumers 拉回 正确的 generated mirror： - shortcuts/sheets/data/flag-schemas.json（chart 部分） - skills/lark-sheets/references/lark-sheets-{chart,batch-update,write-cells}.md（rendered schema 段） dropdown 文案改动（flag-defs.json 4 处 desc + dropdown 段的 reference 渲染）不在本 commit 范围，保持 930c9c7 的状态。 * docs(sheets): sync lark-sheets skill from spec — +filter-view-update --properties desc 去掉 +filter-view-update --properties 描述里"pass at least one of --properties.rules / --range / --view-name"的误导承诺。--properties 实际是硬必填（MarkFlagRequired），且 update 走 PUT 整组覆盖语义。 * fix(sheets): align +cells-search/+cells-replace option keys with server schema The CLI emitted `options.regex` and `options.include_formulas`, but the server-side `search_data` / `replace_data` tool schemas declare and consume `use_regex` and `match_formulas`. Result: passing `--regex` or `--include-formulas` always failed with `unexpected property ... is not defined in schema`. Keep the user-facing flag names (`--regex`, `--include-formulas`) — only the JSON keys sent to the server change. Updates the dry-run test that locked the wrong contract. * docs(sheets): sync float-image reference from spec — fix non-runnable examples Two examples in skills/lark-sheets/references/lark-sheets-float-image.md didn't actually run against PPE; sync brings them in line with CLI behavior: - +float-image-create local-path example missed --image-name (CLI rejects with `required flag(s) "image-name" not set` even when path basename already has the filename). Add `--image-name "logo.png"` + inline note. - +float-image-update "only change position" example missed image source (CLI rejects with `one of --image, --image-token, or --image-uri is required`). Expand to two steps: list with --jq pulls the current image_token, then update re-passes --image-token to satisfy the guard. - Leading warning realigned: image source is mandatory on every update call; "keep original image" still requires passing the token explicitly. Upstream change: sheet-skill-spec MR fix/float-image-reference-examples. * feat: 同步 tools-schema.json 改动 * fix(sheets): allow +float-image-update to omit the image source The image source (--image-token / --image-uri) is the only optional part of an update: omit all of them to keep the current image. image_name, position and size stay required — the manage_float_image tool rejects an update without them, and +float-image-list does not return image_name to backfill. Previously the shortcut forced an image source even when only position/size changed, so those updates were rejected CLI-side before any API call (reported as a Fail case in the sheets e2e rerun). - floatImageProperties: gate the image-source requirement on create only; keep image_name/position/size required on both; emit image_uri only when set - sync flag-defs.json + lark-sheets-float-image.md from sheet-skill-spec (image-name/position/size now required on +float-image-update) - tests: cover the image-source-optional dry-run; the single-required checks move to the +batch-update sub-op path (cobra owns the standalone path) * docs(sheets): sync lark-sheets skill from spec Mirror the canonical-spec reference fixes into the consumer skill: - search_replace output contract: `matches[]` with `address` (+ `has_more`/`next_offset`) - workbook sheet fields: `sheet_name`/`is_hidden`/`*_count`, no `frozen_*` - `+range-fill` example uses a non-overlapping target (A3:A100) - drop the unimplemented `envelope.meta.verification` auto-readback claim; advise manual list/get verification instead * fix(sheets): allow +pivot-create to omit both sheet selectors manage_pivot_table_object treats sheet_id / sheet_name as the placement target — when both are absent, handleCreate() auto-creates a new sub-sheet to host the pivot table. The CLI's flag schema didn't reflect this: - Exposed a third flag --target-sheet-id that mapped to the same wire field as --sheet-id, leaving the caller unsure which one to use - --sheet-id / --sheet-name had "XOR with the other" descriptions that read like "operation context", so callers (especially LLM tool callers) felt obligated to set one — frequently the source sheet — which silently disabled the backend's auto-create guardrail and dropped the pivot at A1, overlapping the source data Wire change (synced from sheet-skill-spec): drop the duplicate --target-sheet-id flag; rewrite --sheet-id / --sheet-name descriptions to make the placement-target semantics explicit and call out that omitting both is the recommended path. Implementation change (this PR): add an at-most-one sheet-selector helper and let object create-shortcuts opt into it. - helpers.go: new optionalSheetSelector (both empty allowed; both set still rejected; control-char validation unchanged). requireSheetSelector is untouched — every existing caller keeps the exactly-one contract. - lark_sheet_object_crud.go: objectCRUDSpec gains allowEmptySheetSelectorOnCreate; objectCreateInput dispatches to optionalSheetSelector when it's set. Only pivotSpec opts in; chart / cond-format / sparkline / filter-view / float-image keep the existing require semantics. DryRun and Execute switch to direct flag extraction (same pattern Validate already used) so the XOR check happens in exactly one place (the builder). - pivotSpec: drop the enhanceCreateInput branch that read the now-removed --target-sheet-id flag. - Tests: TestPivotCreate_SheetSelectorSemantics covers both-empty / both-set / single-set; TestObjectCreate_RequiresSheetSelector regresses chart / cond-format / sparkline / filter-view to lock the scope of the relaxation. * docs(sheets): clarify filter/filter-view rules update is whole-set PUT Synced from upstream tools-schema. The rules field on manage_filter_object and manage_filter_view_object now documents update as whole-set PUT semantics: submitted rules become the complete rule set, all existing columns' rules are cleared first, columns not listed lose their old rules (no merge), and [] clears everything. Description-only change, no structural/field change. * refactor(sheets): switch dim-* / rows-cols-resize to A1-string range schema The 9 row/column-region shortcuts used to share two int flags --start / --end with inconsistent end semantics across commands — +dim-insert / -delete / -hide / -unhide / -group / -ungroup treated --end as exclusive, while +dim-move / +rows-resize / +cols-resize treated it as inclusive. The skill reference even called this out as "the highest-frequency off-by-one source", patched in docs rather than at the surface. Three underlying tool schemas (position+count, A1 range string, 0-based int pair) were all flattened onto the same --start/--end pair, which forced a different normaliser per command and pushed mental math (count = end - start) onto every caller. Schema (sourced from base, regenerated via sheet-skill-spec, mirrored into shortcuts/sheets/data/ and skills/lark-sheets/): +dim-insert --position + --count rows: "3"; columns: "C". --count rows/columns inserted *before* --position. +dim-delete / -hide / -unhide / -group / -ungroup --range +rows-resize / +cols-resize --range A1 closed range. Rows: "3:7" or "5". Columns: "C:F" or "C". Mixing letters and digits in one range is rejected. +dim-move --source-range + --target --target must match --source-range's dimension (both row or both column). The move places the source block *before* --target. Wire-shape preserved: modify_sheet_structure still receives `position` + `count` (insert) or a `range` A1 string (other dim-* ops); v3 move_dimension still receives 0-based inclusive ints (CLI parses the A1 strings into them); resize_range still receives a two-sided A1 range (single-element form is expanded to "N:N" before send). This is a flag-surface break (--start / --end / --dimension flags removed from these 9 shortcuts); --dimension stays only on +dim-freeze since it has no range to derive from. Code: A1 parser added (parseA1Range / parseA1Position / letterToColumnIndex reused from write_cells); dimRange / dimRangeFull / dimPosition deleted; dim-move switches to source-range + target parsing; resize gains a same-dimension guard so +rows-resize rejects "A:C" with a clear "+rows-resize expects row numbers" message. Tests: TestSheetStructureShortcuts_DryRun / TestDimMove_DryRun / TestDimMove_Column / TestDimMove_MismatchedDimension / TestDimRange_Validation / TestParseA1Range / TestResize_TypeAndSizeGuards / TestRangeOperationsShortcuts_DryRun all rewritten against the new schema. Batch contract trio (BodyMatchesStandalone / ErrorEquivalence / RejectsBadSubOpInput) and TestBatchOp_DispatchCoversReportedBugs likewise. Full `go test ./shortcuts/sheets/` passes. * docs(sheets): sync +pivot-create placement reference from spec Companion sync from sheet-skill-spec — the canonical reference rewrites +pivot-create's "5 placement-related flags" rundown into a clearer "4 placement-related flags" form (--target-sheet-id was already removed in #1130, this updates the prose accordingly), and clarifies that --sheet-id / --sheet-name on +pivot-create are the *placement* sheet (not the source-data sheet), with omit-both as the strongly-recommended default. Also picks up a base-side --target-position description tweak that dropped the now-stale "与 --target-sheet-id 配套" reference. No CLI surface change. * docs(sheets): sync +pivot-create summarize_by lowercase enum values from spec * docs(sheets): wrap sheet names in single quotes in A1 examples Synced from spec. Affects 3 reference md (pivot-table / batch-update / write-cells) and 2 generated flag-data JSONs. A1 examples like `Sheet1!A1:D100` now read `'Sheet1'!A1:D100` so models default to single-quoted sheet names. Excel A1 notation requires single quotes for sheet names containing hyphens / spaces / non-ASCII chars; always-quoting is also valid for plain names, so this is the safer default to teach. Affected flags: - +pivot-create --source - +dropdown-update --ranges / --source-range - +dropdown-delete --ranges - +dropdown-set --source-range - +cells-batch-set-style --ranges - +cells-batch-clear --ranges * docs(sheets): wrap A1 sheet names in handwritten examples + bash histexpand guide Synced from spec. Affects 4 reference md (chart / pivot-table / sparkline / write-cells) and SKILL.md. In addition to wrapping sheet names in single quotes in all remaining handwritten examples (covers chart refs.value / nameRef, sparkline source, write-cells --source-range, pivot-create narrative), SKILL.md gains a new "Shell quoting for A1 references with !" section. The new section addresses bash history expansion: in interactive bash (e.g., ShellExec sandbox), unescaped `!Word` after `"..."` triggers `bash: !A1: event not found`, dropping the command before lark-cli sees it. The section gives 4 quoting strategies (shell single-quote outer, `set +H` prefix, mixed quoting, sheet-rename fallback) and an anti-pattern list. Affected files: - skills/lark-sheets/SKILL.md (new section) - skills/lark-sheets/references/lark-sheets-chart.md - skills/lark-sheets/references/lark-sheets-pivot-table.md - skills/lark-sheets/references/lark-sheets-sparkline.md - skills/lark-sheets/references/lark-sheets-write-cells.md * docs(sheets): drop bash histexpand section, fix write-cells table escape Sync from spec, refining the bash-quoting deep-dive added in 0f695b6: - Drop the `## Shell 调用注意事项` section in SKILL.md and the inline `⚠️ bash 引号` callouts in lark-sheets-pivot-table.md and lark-sheets-write-cells.md. The 4-scenario quoting table + anti-pattern list turned out too verbose for the SKILL intro; single-quoted examples in the references are themselves enough nudge. - lark-sheets-write-cells.md L146: fix the table cell escape from the malformed `'''Sheet1''!T1:T3'` (consecutive `''` are no-op empty strings) to `''\''Sheet1'\''!T1:T3'`, matching the bash example at L191 verbatim. Net: 1 insertion, 40 deletions across 3 files. * feat(sheets): rename +pivot-create sheet selector → --target-sheet-{id,name} +pivot-create's placement selector (where the pivot table lands) is no longer the generic --sheet-id / --sheet-name; it is now --target-sheet-id / --target-sheet-name. The new names mark this as the *output* sheet, distinct from the *data-source* sheet (which lives inside --source as `'Sheet'!Range`). The other +pivot-{list,update,delete} shortcuts keep --sheet-id / --sheet-name (their semantics are "sheet that hosts the existing pivot", same as every other shortcut). Motivation: an LLM agent reading the previous CLI surface saw +pivot-create expose --sheet-id and assumed (as it had to) that it pointed at the data source, like every other shortcut. The new flag name makes the intent unambiguous at the call site, without relying on the agent having read the narrative caveat in the reference doc. Background: evaluation case U046 spent multiple rounds tripping on this exact confusion before working around it with +sheet-rename. Implementation: - objectCRUDSpec gains createSheetIDFlag / createSheetNameFlag (with default-fallback accessors sheetIDFlagOnCreate / sheetNameFlagOnCreate); newObjectCreateShortcut + objectCreateInput consult the spec instead of hard-coded "sheet-id" / "sheet-name". pivotSpec sets target-sheet-*; every other create spec inherits the defaults. - optionalSheetSelector (only used by pivot create) takes the two flag names as parameters so its mutex / control-char errors quote the names the user actually typed (--target-sheet-id, not --sheet-id). - batch_op_dispatch: introduce sheetSelectorFlagsForSubOp(shortcut) → (idFlag, nameFlag) returning target-sheet-* for "+pivot-create" and the defaults otherwise; translateBatchOp uses it so +pivot-create sub-ops in +batch-update accept the same renamed input keys. - Tests: - lark_sheet_object_crud_test.go: pivot-create cases switch args and expected error wording to target-sheet-*; extra assertion that the mutex error quotes the renamed flag (regression guard against flag-name drift between code and error message). - batch_op_contract_test.go: +pivot-create sub-op test uses target-sheet-id / target-sheet-name input keys; the body-vs-standalone contract loop reads the selector via sheetSelectorFlagsForSubOp so every other shortcut keeps using sheet-id / sheet-name. Synced reference docs (skills/lark-sheets/{SKILL.md, references/lark-sheets-pivot-table.md}) mirror the spec's new flag names, narrative, 3-placement-strategy block, and SKILL.md exception bullet that explains why +pivot-create's badge says 无 sheet 定位 yet still has placement selectors (just under different names). flag-defs.json synced from spec picks up the renamed flags + kind=own. All sheets-package tests pass. * docs(sheets): strip migration-history language from pivot reference / SKILL Synced from spec. Removes "renamed from / no longer called / not --sheet-id" style migration-history language that snuck into the previous sync. Reference and SKILL now describe the current flag names directly without referencing the old names. * docs(sheets): require +workbook-info before guessing sheet name Synced from spec. SKILL.md adds a new rule under the sheet-locator section: unless the user has explicitly named a sheet, the agent must call +workbook-info first to fetch sheets[].sheet_id / sheets[].title rather than guessing the default `Sheet1`. The Chinese-language tables this CLI is typically used against rarely use that literal name — "数据" / "Sheet" (no digit) / "工作表 1" / business-named sheets are far more common — so guessing wastes a round-trip before the agent ends up calling +workbook-info anyway. The 统一调用范式 example also switches its `--sheet-name "Sheet1"` placeholder to `<真实表名>` to remove the inadvertent suggestion that `Sheet1` is a sensible default. * docs(sheets): tell agent to `set +H` for A1 references containing `!` Synced from spec. The sheet-locator section now warns: when a flag value contains `!` (--source / --range / --ranges with a cross-sheet prefix), run `set +H` at the start of the bash session to disable history expansion — otherwise interactive bash (e.g. inside an agent's shell sandbox) lexes "Sheet1!A1" as a history reference and fails with `event not found` before lark-cli ever sees the argument. When the sheet name itself contains hyphens / spaces / non-ASCII characters, the A1 reference also needs single quotes around the sheet name per A1 notation, e.g. --source "'Sales-2025'!A1:D100". Also flips the previous `--range` example to `--range 'Sheet1!A1:B2'` (shell single-quote) for consistency. * feat(sheets): add schema-driven JSON flag validation Validate composite JSON flags (--properties, --cells, --options, --border-styles, --sort-keys) against the embedded flag-schemas.json on every standalone and +batch-update sub-op invocation, replacing ad-hoc per-shortcut guards. Supports the JSON Schema subset actually used upstream: type / enum / oneOf / required / properties / items / nullable / minimum / maximum / minItems / maxItems / additionalProperties (true | false | <schema>). Enum errors quote the failing value, truncate beyond 8 entries, and surface case-only "did you mean" hints (SUM -> sum). Coverage: 18 / 19 (shortcut, flag) pairs. +batch-update --operations stays validator-skipped; its translator already does richer per sub-op checks. mapFlagView.Command() routes batch sub-ops through the same (command, flag) -> schema pipeline as standalone. loadFlagSchemas() is now sync.Once-guarded so parallel first access from t.Parallel test sets and concurrent shortcut invocations is race-free. Removes superseded hand-written guards: - +pivot-create validateCreateInput / validatePivotCreateProps - +range-sort sort-keys per-item shape check Test fixtures updated to be schema-conformant (chart position/size, pivot summarize_by lowercase, cells 2D-array shape). * feat(sheets): add --rows-json output flag to +csv-get +csv-get --rows-json returns structured rows ({row_number, values:{col→cell}}) instead of the CSV string, so callers can address cells by row_number / column letter without parsing [row=N] or RFC-4180 CSV. Same read, alternate output shape — a flag on +csv-get (default stays CSV), not a separate shortcut, since the two differ only in representation. - CsvGet.Execute: --rows-json reshapes the response via assembleRowsJSON (parses annotated_csv into per-row records keyed by column letter; every logical row emitted; embedded newlines parsed into cell values) - surfaces the under-read hint structurally as data_not_fully_read - flag-defs.json + read-data reference synced from spec * feat(cli): agent-friendly errors, proxy silencing, +csv-put --range Agent-experience fixes distilled from analyzing 50 real sheets trajectories, where the top failures were hallucinated command/flag names, proxy warnings corrupting JSON on stdout, and --range carried over from +csv-get to +csv-put. - did-you-mean: unify the duplicated Levenshtein into a shared internal/suggest package and wire its prefix-weighted ranker into unknown-subcommand and unknown-flag errors; flag-parse errors now return a structured envelope with suggestions plus the full valid list, so agents recover from semantic typos (e.g. --query vs --find). - proxy: suppress the one-time proxy warning in non-interactive (agent/CI/piped) runs so a 2>&1-merged stderr line cannot corrupt stdout JSON; interactive sessions still warn. - sheets +csv-put: accept --range as an alias for --start-cell (parity with +csv-get / +cells-set) and echo the computed writes_range in dry-run and the success envelope, so agents see the paste footprint before it overwrites neighbours. - docs(sheets): add an intent->command cheat-sheet to SKILL.md, a runtime-prerequisites section, and document the --range alias and writes_range behaviour. * feat(sheets): close P0-4 pivot gaps — enum case, clear→pivot-delete hint, placement warning Last open P0 from the 50-trajectory analysis — the two pivot black holes: upper-cased summarize_by, and pivots built over the source sheet that hit #REF! and then couldn't be removed. - enum case tolerance: validateAgainstSchema rewrites a case-only enum mismatch to the canonical (lower-case) spelling in place ("SUM" -> "sum") before the request is sent, killing the whole class instead of only hinting at it. Covers every nested enum (values[], calculated_fields[]); genuinely unknown values still fail with the existing did-you-mean message. - +cells-clear / +cells-batch-clear: when the backend reports "can not find embedded block" (the range overlaps a pivot/chart), annotate the error with the real fix — clearing cells can't delete an embedded object; remove it with +pivot-delete / +chart-delete (id via +pivot-list / +chart-list). Applied to both shortcuts, a Tips line, and the cells-clear reference. - +pivot-create: a --help Tips block making "omit --target-* -> backend auto-creates a sub-sheet, zero overwrite" the can't-miss default, plus a placement_warning (dry-run + execute output) when an explicit target sheet is set with no offset — definite when the target name matches the source sheet, conditional otherwise. Local-only, advisory, never blocks the call. The placement_warning is structured output, not a stderr line, so it survives non-interactive proxy-warning silencing and isn't swallowed by 2>&1. * feat(sheets): strip UTF-8 BOM from stdin/@file flag input resolveInputFlags now strips a leading UTF-8 BOM from content read via stdin or @file, so it cannot corrupt the first CSV cell or break JSON parsing of payloads like --operations / --cells downstream. Also pulls the synced lark-sheets skill docs from sheet-skill-spec and drops scheme-number tags from two test comments. * fix(sheets): drop dead --value-render-option flag from +csv-get +csv-get wraps get_range_as_csv, which has no value_render_option support (absent from its input type, executor, and published tool schema — it always returns formatted display text via getText()). The CLI passed the flag through as a silent no-op: callers asking for raw_value/formula got formatted values. Remove the flag from flag-defs, drop the value_render_option passthrough in csvGetInput, and clean the stale SKILL references. The real value_render_option capability is unchanged on +cells-get (get_cell_ranges) via --include formula. * chore: rename ppe x-tt-env lane to ppe_moa_canvas * docs(sheets): sync skill description from spec (cloud-drive alias, lark-drive search, doubao routing) * feat(sheets): restore pre-refactor shortcuts under backward/ for compatibility The lark-sheets refactor renamed every shortcut (verb-noun → noun-verb, e.g. +create-sheet → +sheet-create) and dropped the old commands. External callers and the tests/cli_e2e/sheets suite still drive the legacy command names (+create, +read, +write, +create-sheet, ...), which broke. Re-add the pre-refactor implementations verbatim from main as an isolated shortcuts/sheets/backward package (package rename only) and register backward.Shortcuts() alongside sheets.Shortcuts(). Both sets mount under the `sheets` service; their command names are fully disjoint (38 new vs 42 old, zero overlap), so old and new commands coexist without collision. * fix(sheets): resolve 30 golangci-lint v2.1.6 issues — copyloopvar, nilerr, unused Removed 25 Go 1.22+ loop variable copies (copyloopvar) from test files where tc := tc / tt := tt / c := c are no longer needed. Fixed 4 nilerr false positives in flag_schema_validate.go by making intentional error discards explicit (schema validation failures skip silently — best-effort guard). Dropped unused batchOpDispatchKeys helper in batch_op_dispatch.go. * feat(sheets): flag pre-refactor backward aliases via _notice and --help grouping Nudge users whose lark-sheets skill predates the refactor to migrate off the pre-refactor aliases (+read, +write, ...), without requiring anyone to read --help. - internal/deprecation: process-level pending Notice slot (mirrors internal/skillscheck), surfaced in the JSON "_notice" envelope under a "deprecated_command" key. - internal/cmdutil: shared DeprecatedGroupID cobra group + helper so both --help rendering and the unknown-subcommand path classify aliases the same way. - shortcuts/register.go: applySheetsCompatGroups splits the aliases into a dedicated "update your skill" help group with "(-> +new)" pointers; wrapSheetsBackwardDeprecation records the notice from Validate/Execute so direct callers that never read --help still get flagged. - cmd/root.go: extract composePendingNotice (now unit-testable) and split availableSubcommandNames into current vs deprecated buckets while still ranking unknown-subcommand suggestions across both. * chore: drop hardcoded ppe lane routing from base security headers The x-tt-env/x-use-ppe headers forced every request onto the ppe_moa_canvas pre-release lane; they were only meant for exercising the sheets refactor against the staging backend. Remove them so the CLI routes to production by default. * chore(sheets): promote lark-sheets skill to 2.0.0 Drop the -draft suffix now that the refactored sheets skill is ready to ship. * fix(sheets): correct +dropdown-get sheet-locator doc, finalize skill to 2.0.0 +dropdown-get requires a mandatory sheet selector — its Validate calls resolveSheetSelector — so drop it from the "no sheet locator" exception list in SKILL.md. It was wrongly grouped with +dropdown-update/+dropdown-delete, which take only --ranges. +dropdown-get's own per-shortcut badge (公共四件套) was already correct. Also finalize the skill version 2.0.0-draft -> 2.0.0. * fix(sheets): enforce required-flag contract in batch sub-ops Batch sub-ops reuse each shortcut's shared *Input builder through mapFlagView, which seeds flag-defs defaults — so any required check that lives OUTSIDE the builder (cobra MarkFlagsOneRequired, or a shortcut's own Validate) is silently bypassed and the default value wins. Two gaps surfaced in PR review: - +csv-put: with neither --start-cell nor --range set, start-cell's "A1" default won and the paste silently anchored at A1. Require an explicit anchor (guard on Changed, mirroring the standalone MarkFlagsOneRequired). - +sheet-move: --index (plus >=0 bounds for index / source-index) was not enforced in the batch path; a missing --index silently moved the sheet to the front. Mirror SheetMove.Validate. Also from the same review: - +batch-update: an explicit --continue-on-error=false now wins over an --operations envelope's continue_on_error:true (guard on Changed, not value). - validateDropdownRanges rejects malformed sheet!range ("!A1", "Sheet1!", "Sheet1!bad") at Validate instead of deferring to the server. Tests added/updated for each path; full sheets suite green. * fix(cli): surface skill in deprecated_command notice deprecation.Notice carries Skill, but the _notice.deprecated_command payload dropped it, forcing callers to parse `message` to learn which skill to update. Emit `skill` when set, alongside the existing `replacement`. * fix(sheets): harden batch type-checking and +workbook-create edge cases From the branch code-review doc (3 findings): - +batch-update sub-ops: `operations` is skipped by parse-time schema validation and mapFlagView coerces a type-mismatched scalar to its zero value, so "index":"abc" or "multiple":"true" silently became 0 / false and wrote to the wrong place. translateBatchOp now runs validateRawTypes, which checks each sub-op scalar against its flag-defs type and rejects mismatches. - +workbook-create with empty arrays: buildInitialFillInput returned (nil,nil) for empty rows while the caller wrote fill["excel_id"] unconditionally, so --values '[]' panicked on a nil map and --headers '[]' produced an illegal "A1:1" range. It now also returns nil when no cells survive (maxCols==0 guard) and Execute/DryRun skip the fill when fill==nil. - +workbook-create partial failure: after the spreadsheet was created, a first-sheet lookup or fill failure returned a bare fmt.Errorf, losing the new token. It now returns a structured partial_success error carrying spreadsheet_token in the detail so callers can retry or clean up. Tests added for each path; sheets suite green. * fix(cli): structured errors for unknown flags, print-schema, deprecated aliases From the branch code-review doc (3 findings): - pure-group UnknownFlags: installUnknownSubcommandGuard whitelists unknown flags so a mistyped subcommand still reaches the suggestion path, but a lone unknown flag before any subcommand (`sheets --badflag`) was swallowed and the group fell through to help + exit 0. unknownSubcommandRunE now recovers the swallowed tokens (from os.Args captured at Execute entry) and fails with a structured unknown_flag error; a misplaced but known flag (e.g. --format) still prints help. - deprecated-alias notice: a backward-compat alias that fails a cobra-level required flag short-circuits before RunE, so the Validate/Execute-wrapped deprecation notice was dropped. Added Shortcut.OnInvoke, fired from PreRunE (ahead of ValidateRequiredFlags); and the root legacy error fallback now routes through the structured envelope when a deprecation is pending so the migration hint survives. Non-deprecated errors keep the plain output. - --print-schema: runShortcut returned the bare error from PrintFlagSchema. It is now wrapped as a structured output.ExitError (type print_schema_error) so agent introspection can parse the failure. Tests added for each path; cmd + sheets suites green. * fix(sheets): resolve --sheet-name via title + keep bare sheet selectors verbatim Two review findings on the backward-compat layer: - lookupSheetIndex matched only sm["sheet_name"], but get_workbook_structure surfaces the sub-sheet display name as "title". Every --sheet-name path that relies on the lookup (e.g. +sheet-move) failed to resolve. Fall back to "title" when "sheet_name" is absent so either field resolves. - +read / +write / +append fell back to --sheet-id when --range was omitted, then routed that bare sheet id through the range normalizer. A sheet id that looks A1-ish (letters+digits, e.g. "shtABC123") got mangled into "shtABC123!shtABC123:shtABC123". Split the sheet-only path from the range-normalization path: read/append pass the selector through verbatim, write builds the rect from the selector's A1. Regression tests added for both paths; sheets suite green. * fix(sheets): silence nilerr/copyloopvar lint in batch type-check additions - flag_view.go: annotate the fail-open return in validateRawTypes with //nolint:nilerr (matches the repo convention for intentional fail-open). - execute_paths_test.go: drop the redundant tc := tc copy (Go 1.22+ scopes the loop var per iteration). * test(sheets): data-driven required-flag parity contract for batch sub-ops Adds TestBatchOp_RequiredFlagParity, the systematic standalone-vs-batch parity check the branch review asked for. Data-driven over batchOpDispatch + flag-defs, it asserts that for every batchable shortcut a +batch-update sub-op which satisfies the sheet locator but omits the shortcut's business-required flags fails in translateBatchOp, never silently defaulting. This generalizes the hand-picked TestBatchOp_ErrorEquivalence / GuardsBeyondCobra cases to the full 50-command surface and auto-covers shortcuts added later, so a future refactor that moves a required check out of the shared *Input builder (the failure mode behind the csv-put / sheet-move gaps) is caught here. 45 sub-tests run; locator-only commands (+sheet-delete / +sheet-hide / ...) have no business-required flag to omit and are skipped. A missing-locator error is also rejected so a bad fixture can't mask a real gap. * refactor(sheets): drop unused int64 flag-type plumbing No sheets flag-def declares an int64 type and RuntimeContext.Int64 had zero callers, so remove the premature support: the RuntimeContext.Int64 helper, the registerShortcutFlagsWithContext int64 branch, the flagView Int64 method + mapFlagView impl, and the typedDefault/validateRawTypes int64 cases. float64 (consumed by --font-size) is kept. * test(sheets): drop redundant copyloopvar copy in required-flag parity test Go 1.22+ scopes the loop var per iteration, so `cmd, business := cmd, business` in TestBatchOp_RequiredFlagParity is a no-op that trips the repo's copyloopvar linter (same cleanup as 2132472). Behavior unchanged; 45 sub-tests still pass. * revert(cli): drop non-interactive proxy-warning silencing WarnIfProxied's interactivity gate is a generic CLI/agent-UX change unrelated to the sheets refactor / backward-compat scope of this branch. Split out to a dedicated PR; restore WarnIfProxied to its single-arg form here (warn.go, warn_test.go, factory_default.go callers). * docs(sheets): correct +workbook-info output field and batch +sheet-move index requirement Sync from spec: +workbook-info returns sheet display name as 'title' (sheet_name only as legacy fallback), and +sheet-move inside +batch-update also requires --index, not just --sheet-id/--source-index. * fix(sheets): reject non-integer numbers for batch int flags validateRawTypes treated int and float64 identically (both only required a JSON number), but mapFlagView.Int() truncates float64 via int(t), so a batch sub-op accepted 1.9 for an int flag (e.g. --index) and silently floored it to 1. Standalone cobra rejects non-integer input for int flags at parse time; enforce the same in the batch path with a math.Trunc check so batch/standalone parity holds and positional fields can't land on a floored value. * fix(cli): align flag-before-subcommand unknown_flag detail schema The flag-before-subcommand recovery path emitted a Type: unknown_flag whose detail only carried unknown_flags + command_path, diverging from flagDidYouMean's unknown_flag detail (unknown, command_path, suggestions, valid_flags). A consumer keyed on Type then saw two shapes for one Type. Emit the same keys from both paths: add unknown (the offending flag; joined when multiple), plus empty suggestions/valid_flags — the subcommand isn't resolved at this point, so there is no meaningful flag universe to suggest from, and the group's own flags would mislead. unknown_flags is retained as the authoritative multi-flag field. Test locks the shared schema. * perf(sheets): compile flag specs to Go to drop startup JSON parse Every lark-cli invocation (sheets or not) unmarshaled data/flag-defs.json (122KB) and data/flag-schemas.json (256KB) during package init, before main(): flag-defs via the shortcut package vars (flagsFor runs at init), flag-schemas via shortcuts.init() -> Shortcuts() -> commandsWithFlagSchema(). On a 0.5-core sandbox this cold-start cost lands on every command. Compile both specs to Go at build time instead of parsing at runtime: - flag-defs.json -> flag_defs_gen.go: flagDefs is a compiled map literal; loadFlagDefs() returns it directly (no embed, no Unmarshal). ~3.3ms/4110 allocs -> ~0.57ms/539 allocs at sheets package init. - flag-schemas.json -> flag_schemas_gen.go: only the command-name set (commandsWithSchema) is compiled in; registration and the validate fast-path gate on it without touching the 256KB blob. The blob stays embedded and is unmarshaled lazily only on --print-schema or when validating a command that has a schema. Removes the 256KB parse from init entirely. data/*.json remain the canonical source; *_gen.go are committed, derived artifacts regenerated with `go generate ./shortcuts/sheets/...` (shortcuts/sheets/internal/gen). *_gen_test.go guard source/generated drift. No behavior change: flag rendering, required/enum/default, --print-schema, and composite-flag schema validation verified unchanged; ./shortcuts/... tests pass. * ci(sheets): exempt internal/gen generators from forbidigo The shortcuts/sheets/internal/gen code generator is a standalone `package main` run via go:generate, not shortcut runtime code, so the forbidigo bans on log.Fatal / os.ReadFile / fmt.Printf do not apply. Making it "compliant" is impossible anyway: a structured error return needs os.Exit (also banned), and the vfs alternative is blocked by depguard shortcuts-no-vfs. Exempt shortcut internal/gen paths, matching the existing _test.go and internal/vfs forbidigo exemptions. * fix(cli): fail structured on flags before a missing subcommand A pure group invoked with flags but no subcommand (e.g. `im --format=json`, `sheets --format json`) silently fell through to help + exit 0, so an agent could mistake a malformed call for success. The unknown-subcommand guard's FParseErrWhitelist swallows the flags and leaves RunE with empty args; it now recovers the raw flag tokens and fails structured: - unknown flag(s) -> unknown_flag (unchanged) - valid flag, no subcmd -> missing_subcommand (new, exit 2) - bare group -> help, exit 0 (unchanged) Because the group RunE is hook-wrapped, returning a real error also makes plugin observers record the call as failed instead of ok (the lifecycle Err is no longer flipped to nil). Hardening from the same review: - document the cobra error-text contract unknownFlagName relies on, in both cmd/root.go and go.mod, so an i18n/reword is caught on upgrade. - guard the reserved --print-schema/--flag-name registration with a Lookup so a shortcut declaring same-named flags can't panic pflag. Tests cover the new missing_subcommand path and the reserved-flag collision. * fix(cli): don't flag group-valid globals as a missing subcommand 9f8dfa72 made a pure group invoked with flags but no subcommand fail with missing_subcommand, keying on "any flag defined in the tree". That also matches inherited global flags (--profile, ...), so `lark-cli --profile p im` and `lark-cli im --profile p` errored with a misleading "flag --profile belongs to a subcommand" instead of printing the group's help — a regression, since a bare group carrying a global flag should print help. Only treat a flag as missing_subcommand when it is valid on a subcommand but not on the group itself or inherited (subcommandOnlyFlagTokens). A bare group carrying only group-valid/global flags falls through to help; flags that genuinely belong to an omitted subcommand (`im --format json`) still fail structured, and unknown flags (`im --badflag`) still report unknown_flag. Test covers a global flag on a bare group resolving to help. --------- Co-authored-by: zhengzhijie <zhengzhijie.j@bytedance.com>	2026-06-03 20:43:53 +08:00