64 Commits

Author	SHA1	Message	Date
xiongyuanwen-byted	f6353368d7	fix(sheets): drop the Go 1.24-only t.Chdir, and gofmt the ergonomics test ... CI's fast-gate failed on the receipt test added in 01ae4cc5: t.Chdir landed in Go 1.24, and go.mod declares 1.23.0 — which is what CI resolves its toolchain from. Locally it compiled against 1.24.4, so the whole suite looked green. Replaced with the os.Chdir + t.Cleanup pattern the repo already uses elsewhere. Also gofmt'd flag_ergonomics_test.go, whose struct literal alignment shifted when the rejectHint field was added. Verified by reproducing fast-gate under an actual go1.23.0 toolchain: build, vet ./..., gofmt -l, go mod tidy, plus the -race unit tests CI runs.	2026-08-01 00:37:30 +08:00
xiongyuanwen-byted	c4270566ba	test(sheets): pin the flat style flags' wire mapping, found by coverage ... Coverage over the changed lines showed six of buildCellStyleFromFlags' eleven branches never executed. TestStylesAcceptance_VocabularyParity walks the same vocabulary but drives the PAYLOAD path; the flat --font-color / --number-format / … flags are a separate hand-written mapping that nothing exercised. The failure it admits is quiet: write the wrong wire key and the request still succeeds, the sheet just does not change. Verified the current mapping is correct for all eleven fields before pinning it, and confirmed the test is sensitive (renaming font_color's wire key now fails). Derived from flag-defs, so a newly declared style flag is covered as soon as it exists.	2026-08-01 00:22:22 +08:00
xiongyuanwen-byted	75e8063bf2	test(sheets): cover --flag-name dotted-path slicing, which had none ... Mutation testing found the whole feature unpinned: disabling the implicit items/oneOf descent, or the explicit "items" segment, broke no test. It is how SKILL.md tells agents to pull one subtree out of chart-create's ~1,750-line properties schema instead of paging the full dump, so a regression just pushes them back to full dumps — invisible to every output-correctness test. Covers the one-segment walk, implicit descent through array items, the explicit items segment, the underscore spelling of the flag name, that a slice is strictly smaller than the full schema, and that a miss lists the keys actually reachable at that level. Also resyncs the two read-helper script fixes from sheet-skill-spec.	2026-08-01 00:17:36 +08:00
xiongyuanwen-byted	01ae4cc521	test(sheets): pin three guarantees that mutation testing showed nothing held ... Third review pass, run as mutation testing rather than reading: break a behaviour, see whether anything fails. Most of the suite has teeth (removing the coalesce reordering guard, the descending sort in +dim-delete --ranges, the sub-op vocabulary check, the cells-vs-range dimension check, the border weight normalization, the retired-enum tolerance and the batch freeze-collision warning all get caught). Three did not. - coalesceStyleStamps' adjacency rule. Widening the touch test from +1 to +2 fuses ranges separated by one row, painting cells the caller never named, and passed every existing case — they are all contiguous, so they only constrain the rule from one side. Added the negative cases plus a coverage property: the set of cells the expanded stamps touch must equal the set the spec named. Coalescing rewrites a declarative spec, so this is the invariant that matters, not any single fusion. - The --output-path receipt. Hard-coding complete:true passed the whole suite, yet the receipt is the only completeness signal on that path (the data went to a file) and the skill docs tell agents to read it before using the file. Now driven end to end for clean / per-range-truncated / has_more reads, with the file contents and bytes_written checked against the receipt. - +table-get's whole-workbook char budget. Removing the per-sheet clamp lets each sheet spend --max-chars in full — a 30-sheet workbook pulls 30x what was allowed, with every individual request looking compliant. The outer loop's exhaustion check is a different mechanism and kept working, which is why nothing failed. Now asserted on the wire: sheet 2 must ask for less than sheet 1.	2026-07-31 23:53:36 +08:00
xiongyuanwen-byted	99ac5d6906	fix(sheets): resync the profile-script hidden-column fix, drop a tautological test ... Skill/data resync from the spec repo's matching commit: safe_append_col now steps over hidden columns (see sheet-skill-spec), and the +batch-update shortcut enum names +styles-put among the excluded fan-out wrappers. Also fixes the --max-chars 0 test added in f619e34d, which asserted the value equalled maxCharsFallback — the constant it is derived from, so it would have passed unchanged after the flag's declared default moved in flag-defs.json and left the two out of step. It now compares the explicit-zero call against the omitted one, which is the actual contract ("0 means no cap of my own").	2026-07-31 23:39:47 +08:00
xiongyuanwen-byted	fd97e65b55	docs(sheets): record the live +dim-insert side check that the code assumed ... The previous commit sent `side` explicitly on +dim-insert and justified it as guarding a real hazard: that omitting it left placement to an undocumented backend default, which if it were "after" would insert on the wrong side of --position. Running it settles the question the other way. On a sheet with row2 red and row3 blue, inserting at --position 3 places the blank at row 3 under all four spellings — no `side` field at all (the pre-fix binary), omitted, `after`, and `before` — and the blank inherits the following row's blue under omitted/`after`, the preceding row's red under `before`. So the backend already defaults `side` to "before", the pre-existing behaviour was correct, and the flag's documented "omit == after" held on its own. Sending the field explicitly is kept, but as belt-and-braces: it stops the documented default from depending on an undocumented server-side one, and the placement is byte-identical either way. Comments and the test doc now say that instead of claiming a bug that was not there.	2026-07-31 23:29:59 +08:00
xiongyuanwen-byted	4e2c6a2096	docs(sheets): resync skill refs and flag data from sheet-skill-spec ... Regenerated from the spec repo's matching commit: the +styles-put failure guidance (operations[N] indexes are internal, read back and re-send instead), --dry-run rather than --yes in the two canonical +batch-update snippets, and the read-cap wording for --max-chars 0 / --output-path's JSON payload.	2026-07-31 23:21:03 +08:00
xiongyuanwen-byted	f619e34d38	fix(sheets): close review gaps in freeze, styles and error reporting ... Review of the aggregate diff turned up nine places where the surface did not do what this PR says it does. Each is small; the theme they share is that a prescription pointed somewhere the caller could not follow. Contradictions with this PR's own retirements: - The six --frozen-* unknown-flag hints prescribed --dimension row --count N. Those flags are hidden from --help, so the hint named a flag missing from the valid-flags list printed beside it, and following it earned a deprecation note steering back. They now prescribe --rows / --cols, as does the "nothing to freeze" error. - A Sheet! range prefix was only stripped when the styles item carried a name. +workbook-create --values items need none, so row_sizes like "Sheet1!2:3" still failed there as a malformed range — the exact bug this PR reports as fixed across all three --styles carriers. Stripping is now unconditional; only the "names a different sheet" report needs a name to compare against. - Two +dim-freeze sub-ops in one batch cancel each other, and only the CLI can see it (a batch cannot read current state, and +styles-put is not batchable). Per-op "equivalent to --rows 1" notes never said so. A collision note now names the colliding ops, the state actually reached, and the single sub-op that holds both axes. dimFreezeAxes/dimFreezeSpelling became the shared mapping so the request body, the deprecation note and this one cannot drift. - +dim-insert with --inherit-style omitted sent no `side`, so "omitting is the same as after" held only if the backend happened to default it to before — and if it defaulted to after, the insert would land on the wrong side of --position, silently breaking the command's stated contract. It is now sent explicitly; TestDimInsertOmittedMatchesAfter pins the two bodies together. Errors that misdescribed themselves: - "resend only operations[N:]" was emitted for every batch_update caller, but only +batch-update's array is caller-written. +styles-put coalesces and +dim-delete --ranges deliberately re-sorts descending, so the index names nothing the caller can locate. Those callers now get a read-back procedure. - A sub-op carrying both an alias and its target (size + width on +cols-resize) was reported as an unknown input key: the alias branch fell through, and the conflict check never fired because keys are walked in sorted order and "size" sorts first. Identical values now drop the alias; differing ones name both spellings. - Folding per-item failures into one error dropped each inner Hint, so the more mistakes a payload had, the less guidance it got — including the +workbook-info pointer this PR had just added. A lone issue inherits the hint; a folded list inlines each. - --max-chars 0 sent no cap, which makes the read tool apply its own ~50000 fallback: asking for no limit produced the smallest one. It now resolves to the same ceiling as leaving the flag alone. Also: --inherit-style before anchors one row/column earlier, so its dry-run showed a position the caller never typed; a note explains it is not an off-by-one. The style vocabulary now walks sorted keys everywhere, since every one of those loops can abort and map order decided which of several bad fields got reported.	2026-07-31 23:20:48 +08:00
xiongyuanwen-byted	50b1f54bfa	fix(sheets): make a retired enum value read as absent on both paths ... Clearing a retired value left the two paths disagreeing about Changed(): the standalone path went through cobra's Set, which marks a flag as changed, while the batch path deletes the raw key and so reports false. --inherit-style is unaffected because its only consumers switch on the value, but retiredEnumValues is a generic table — the next flag added to it whose logic reads Changed() rather than the value would behave differently standalone than inside +batch-update, and the body-parity contract only catches such a split once it reaches the request body. Both paths now report the flag as absent, pinned by a test that asserts Changed() directly instead of only comparing bodies.	2026-07-31 19:41:18 +08:00
xiongyuanwen-byted	f8ed143bde	fix(sheets): accept the retired --inherit-style none instead of failing ... Dropping "none" from the +dim-insert enum was the only value removal in the whole flag surface, and it broke callers: "none" was valid AND the default before the side mapping was corrected, so existing scripts and any agent carrying older docs pass it. A retired value is now cleared rather than rejected, making the call byte-identical to omitting the flag — on the standalone path and inside +batch-update alike, since +dim-insert is batchable and a divergence there would be invisible. It stays out of the published enum so the docs and --help do not start teaching the redundant spelling again, and a genuinely invalid value is still rejected. The test mounts the shortcut through Shortcuts() rather than the exported var: the rewrite rides the PostMount ergonomics layer, which the raw var does not carry, so a test built on it would not exercise what ships.	2026-07-31 19:22:50 +08:00
xiongyuanwen-byted	47f4fda1d3	fix(sheets): steer legacy +dim-freeze on dry-run and inside +batch-update ... The phase-1 deprecation note for --dimension/--count only fired from the standalone Execute, missing the two paths that matter most. --dry-run is how a caller previews before committing to a spelling, so a note that arrives only on execute arrives too late. It now rides along as the dry-run warning_message. +batch-update never reached the note at all, yet the batch is where the legacy form does the most damage: freeze is full-state replacement, so two per-axis sub-ops both report success while only the last axis stays frozen, and +styles-put — the other way to set both axes — is not batchable. Sub-op notes are rendered from the same helper as the standalone one, prefixed with the operations[i] index, and DryRun and Execute now share one batchWarnings collector so they cannot drift apart on which advisories they report.	2026-07-31 18:57:14 +08:00
xiongyuanwen-byted	7866801115	chore: tag phase-2 deprecation sites with a greppable marker ... Three surfaces are in phase-1 deprecation — executable but superseded — and each described that state in its own prose, so there was no way to enumerate what is pending removal. DEPRECATED(phase-2) tags all three uniformly, each carrying its removal checklist including the cross-repo spec step.	2026-07-31 18:41:28 +08:00
xiongyuanwen-byted	3624499bcb	feat(sheets): +dim-freeze --rows/--cols for both axes in one call ... Freeze is full-state replacement server-side, so --dimension/--count unfreezes the axis it does not name. Two calls cannot hold both axes, and inside +batch-update there was no way at all: sub-ops are a static array that cannot read the current state, and +styles-put is not batchable. --rows/--cols state the complete freeze state in one operation, so the standalone command and the batch sub-op keep producing identical bodies. The legacy pair still works and prints the exact --rows/--cols equivalent on use, but is hidden from --help and from the skill docs.	2026-07-31 18:41:23 +08:00
xiongyuanwen-byted	13d4350557	fix(sheets): unify --styles range prefixes, merge freeze into one op ... A "Sheet!" prefix on a --styles range was only normalized for +styles-put cell_styles. row_sizes like "Sheet1!2:3" therefore failed parseA1Range on all three carriers, while a prefix naming another sheet was rejected only after the section parsers had already reported their own errors. Normalization now runs in the shared item parser, so +workbook-create, +table-put and +styles-put behave alike; a foreign prefix is stripped and reported alongside the item's other issues instead of masking them. Prefix stripping for visual ops moved into workbookCreateVisualOpInput, which every caller goes through. Freeze rows and columns now travel in one operation: the backend replaces the whole freeze state, so two per-axis operations left only the last axis frozen.	2026-07-31 18:41:17 +08:00
xiongyuanwen-byted	daeab10755	fix(sheets): completeness classifier, freeze alias determinism, color arrays ... Fifth-round review findings, each reproduced before fixing: P1: - readResultTruncated missed ranges[] (the shape +cells-get / +csv-get return), so a clipped read could be written to a file and reported as complete:true. It now checks every level — top, ranges[], sheets[], and nesting — under all three flag names the tools use. readSheetAsSpec also keeps the truncation flag on the empty-grid path, where a read clipped before its first row used to be reported as a complete empty sheet. - freeze accepted "cols" and "columns" as aliases and wrote both through a Go map range, so {"cols":1,"columns":2} froze 1 or 2 columns depending on randomized iteration order (observed both across 2000 runs). Conflicting values now reject; identical values and either alias alone still pass. Iteration is sorted so error text is stable too. P2: - the --styles / --writes aggregators returned the raw inner error when there was exactly one issue, leaving Param empty until a second issue appeared. They now attribute the outer flag and keep the cause in every case. checkBatchStampBudget takes the caller's flag name instead of always blaming --ranges. - chart color normalization lost key context when descending into arrays, so schema-supported colorTheme / colorScale / highlight_colors lists kept bare hex and the server rejected them. isColorKey also covers plural and color-prefixed names; the strict hex value check keeps that safe. - detect_subtables split records on any physical line starting with [row=N], so that text inside a multi-line quoted cell forged a record boundary and polluted row numbers. Splitting is now quote-state aware, and annotated mode is entered only when the first meaningful line really carries a prefix. - docs: --output-path no longer described as unlimited anywhere; the read-data reference documents the per-sheet truncated flag and the offload receipt's complete / unread_sheets fields.	2026-07-31 12:08:23 +08:00
xiongyuanwen-byted	f5e0d14ca9	fix(sheets): key uniqueness, order-safe style coalescing, bounded read budget ... Fourth-round review findings, all reproduced before fixing: P1 — silent wrong results: - batch/writes key canonicalization now guarantees ONE logical key per flag. Both sheet-id and sheet_id used to pass the vocabulary check and survive into the body, where the flag view resolves either spelling — so one value silently won and the write could land on the wrong sheet. Conflicting values now reject with a typed error; identical values collapse. - coalesceStyleStamps no longer groups globally by style content. Grouping reordered same-style stamps around differing ones, turning red → blue → red into red → blue and silently changing the final color. Two stamps are merged only when nothing between them touches the cells whose write would move earlier; adjacent and disjoint-intermediate merges still happen. - --output-path is no longer described or treated as an unlimited read. The cap bounds the WHOLE read: +table-get spends one budget across all sheets instead of per sheet, names sheets left unread, and the stdout receipt now reports complete / truncated so a caller need not reopen the file. dry-run echoes the same max_chars / cell_limit execute sends. P2 — contract violations: - style payloads (--styles, typed --cells) assert the scalar types declared in flag-defs, so {"font_weight": true} is rejected instead of reaching the server as a boolean. - aggregated --styles / --writes errors bind their flag as Param and keep the first underlying error as Cause, so agents read the typed envelope instead of parsing prose. - detect/profile scripts handle hidden COLUMNS like hidden rows: visible- column adjacency stops splitting A|C into two components, and profile reports data_col_segments plus a data_range_has_col_gaps warning so a caller cannot write gap-free data back as one contiguous range.	2026-07-30 17:02:59 +08:00
xiongyuanwen-byted	240e523dbf	fix(sheets): drop remaining atomic claims from --help text and errors ... The earlier atomic-wording cleanup covered spec-managed docs and flag descriptions but missed the Go-side Description / Tips fields (which render in --help) and two sub-op rejection messages. All of these batch_update-backed paths are fail-fast without rollback, so they now say so instead of promising atomicity.	2026-07-30 15:46:38 +08:00
xiongyuanwen-byted	3788b6f601	fix: revert retry-command renderer and temp @file exception, bound read offload ... Third-round review (comprehensive CR on PR #2091) — close the P1s by reverting the two global protocol changes and tightening the rest: - cmdutil confirm (F1): drop the argv-rebuilt "re-run:" retry line and every heuristic behind it; the hint is the plain "add --yes to confirm" again. argv cannot faithfully reproduce the invocation (pipelines, stdin, redirections, env, executable path), POSIX quoting breaks on PowerShell/cmd.exe, and the name-based secret guard both leaked free-form payloads and false-positived on ordinary token locators (--spreadsheet-token). Callers append --yes to their own saved argv after user consent, per the lark-shared protocol. - localfileio/validate/cmdutil (F4): remove the SafeTempAbsInputPath @file exception — TMPDIR-defined trust roots are not a security boundary (TMPDIR=/etc widened the allowed region) and the fast path bypassed the caller's FileIO provider. @file is strictly cwd-relative again; out-of-tree content goes through stdin. - csv guard (F5): stop splicing the untrusted --csv value into command-shaped hint text; prescriptions use <path> placeholders, the value is only named as quoted data. - read offload (F8): --output-path now raises max_chars to a bounded 20M-char default instead of the 1e9 sentinel — the read path is not streaming, so the cap is the OOM guard; an explicit --max-chars still overrides. - batch-update tips + skill (F2, synced from sheet-skill-spec): replace "always pass --yes" / "首次调用就带 --yes" with the consent protocol (dry-run, show the plan, get explicit approval, then append --yes). - skill docs (F12, synced): scripts/lark_*.py are an optional enhancement — binary-embedded skills ship without scripts/, so the docs now say so and point at the CLI-equivalent fallback paths.	2026-07-30 11:15:53 +08:00
xiongyuanwen-byted	0e95848dd7	fix: address second-round PR #2091 review findings ... Reviewer findings (fangshuyu-768) plus one CodeRabbit follow-up: - sheets batch recovery: thread the batch's continue_on_error mode into flattenToolErrorMsg — a single listed failure only implies "nothing after it ran" under fail-fast; under continue-on-error the tail already executed, so prescribing operations[i:] would double-apply it - cmdutil confirm: gate the retry line on value shape as well as flag name — free-form payloads (--sql, --json, non-ASCII, over-long) fall back to the plain add-yes hint instead of copying potential passwords or PII into the error envelope - sheets read offload: map FileIO.Save failures through WrapSaveErrorTyped so an escaping --output-path stays a validation error with its path-validation cause, not internal/unknown - styles-put: reject ranges whose sheet prefix names a different sheet than their item (silent strip retargeted them); reject unknown top-level item keys with a did-you-mean (typo'd freezee was silently dropped) — shared with +workbook-create / +table-put - e2e: cover --inherit-style after in the live dim workflow - docs/flag descs (synced from sheet-skill-spec): batch_update-backed paths no longer claim atomic/transactional semantics — reworded to fail-fast + no-rollback across +styles-put, +cells-set --writes, +dim-delete --ranges, resize maps and the related references	2026-07-29 18:55:57 +08:00
xiongyuanwen-byted	a5032bbb55	fix: address PR #2091 review findings across path safety, batch dispatch and read caps ... Review fixes from CodeRabbit / code-quality on PR #2091: - cmdutil: route the @/tmp fast-path read through vfs.ReadFile so fakes keep intercepting it; suppress the confirmation retry line when argv carries a credential-bearing flag (secrets stay out of error envelopes); extract requireConfirmationFor and pin the composed hint in tests - localfileio: reject a degenerate TMPDIR (e.g. "/") so the temp-dir read exception cannot widen into accepting arbitrary absolute paths - sheets batch dispatch: duplicate canonical + variant input keys (sheetName/sheet_name, ranges/range) now reject with a prescriptive error instead of silently overwriting the canonical value - sheets flag ergonomics: curated unknown-flag hints match underscore spellings (--frozen_rows hits the --frozen-rows entry) - sheets read offload: an explicit --max-chars survives --output-path instead of being replaced by the unbounded sentinel - chart: declare --print-example in flag-defs.json (single source with the generated reference tables) instead of imperative registration; assert the validation Param in the unknown-type test - e2e: add live +dim-insert / +dim-delete workflow coverage (insert lands before position, --range delete, atomic scattered --ranges) - docs (synced from sheet-skill-spec): +chart-create flags table gains --print-example, freeze docs state the at-least-one-positive rule, read-data table gets its MD058 blank line, detect-subtables explains its fallback except	2026-07-29 14:24:20 +08:00
xiongyuanwen-byted	d8f6154e2f	chore: add license headers to sheets skill scripts, drop redundant loop-var copies	2026-07-29 12:56:34 +08:00
xiongyuanwen-byted	d219d61be0	Merge remote-tracking branch 'origin/main' into feat/lark-sheets-develop ... # Conflicts: # internal/validate/path.go # internal/vfs/localfileio/path.go	2026-07-29 12:31:44 +08:00
xiongyuanwen-byted	f79908483d	fix(sheets): reject path-shaped --csv values instead of writing them into the sheet ... A +csv-put --csv value naming a file that doesn't resolve used to be written into the anchor cell as literal text, with a success exit code — a wrong value in the sheet that nothing surfaces, which costs more than a rejection. The common source is an absolute path: @ only reads relative paths, so the caller drops the @ and retries, and the path string lands in A1 (07-28 root-cause audit, finding D1). The existing guard only caught values naming a file that does exist (the forgotten-@ case). The guard now also rejects a value that is unmistakably path-shaped: no separator or whitespace, pure ASCII, and either a .csv/.tsv extension or an explicit ./ ../ / ~/ prefix. All three conditions are required — that is what keeps prose that merely mentions a filename, N/A, README.md and CJK content out of it, the misjudgments that retired the previous name-shape heuristic. This flips one pinned case: a bare "nope.csv" was previously written verbatim and now errs with the fix inlined. To make the shape check safe for correct invocations, resolveInputFlags now records which flags had their value replaced from @file or stdin, exposed as RuntimeContext.InputResolvedFromSource; the guard skips resolved values entirely. By Validate time a piped value is indistinguishable from a typed one, so without the origin bit the guard would re-reject a correct `--csv @file` whose content happens to look like a path — and stdin, which the error text prescribes for verbatim writes, would not actually escape it. The @@ escape stays inline and guarded. This origin bit is the one common-layer addition; it carries no domain logic.	2026-07-29 12:00:47 +08:00
xiongyuanwen-byted	0b59556207	feat(sheets): name the enum, the required selector and the missing envelope in errors and help ... Second batch from the 07-28 root-cause analysis, all aimed at the retry that follows a rejection. Enum-bearing type mismatches now answer with the allowed values instead of a whole-payload skeleton. --border-styles with weight:1 used to reply "expected type string, got number; expected shape: {"bottom": {…}, "left": {…}, …}", which never mentions thin/medium/thick; the skeleton is for container-shape confusion, so a field that declares an enum falls through to the hint that names it. The --border-styles help now inlines both vocabularies (style is the line type, weight the thickness and a string, not a pixel number), spells the {all:{…}} shorthand, and states that no --border-all / --border-top / --border-color exist. --word-wrap additionally accepts the Google Sheets wrapStrategy words wrap and clip. The sheet selector states that one of the pair is required rather than only that they are mutually exclusive, in help across all shortcuts that take it, and the rejection hints where the name comes from: a fresh workbook has one sheet named Sheet1, any other needs a +workbook-info lookup. Eval traces recover on the very next call, so the gap was which name to pass. A --sheets payload written as a bare array now says the top level must be {"sheets":[…]} instead of quoting Go's "cannot unmarshal array into Go value of type struct { Sheets []sheets.tableSheetIn }", which names the internal type rather than the fix. The skeleton hint is unchanged.	2026-07-28 20:47:48 +08:00
xiongyuanwen-byted	91743bba99	fix(sheets): make border vocabulary normalization reachable, prescribe flag and style-field fixes ... Three fixes from the 07-28 root-cause analysis of failed agent traces, all aimed at the first-try success rate rather than the recovery loop. Border acceptance layer was unreachable on two of its three carrier paths. expandBorderAllShorthand already moves a weight word out of the style slot ({"style":"thin"} -> style solid + weight thin), but on --border-styles and typed --cells it ran after parseJSONFlag's schema check, so the enum error fired first and the rewrite never happened. Move it ahead of validation via the jsonFlagNormalizers seam; --styles already validated post-expansion and is unchanged. An explicitly conflicting weight still takes the enum error. Unknown-flag prescriptions for the names agents reach for most: +cells-set --values, +dim-freeze --frozen-row-count and siblings, +cells-set-style --font-bold / --bg-color / --wrap-strategy and the whole --border-* family (no such flags; borders take one composite --border-styles). +sheet-rename --new-name / --name alias to --title, matching +sheet-create. Unsupported cell_styles field names now name the right field instead of the nearest string: bold / font_bold -> font_weight, text_align -> horizontal_alignment, a nested openpyxl-style font object -> the flat font_* fields. Where no prescription applies, the edit-distance fallback is capped at two edits, so a concept-swap neighbour (font_bold -> font_color, three edits) stays silent rather than sending the retry the wrong way; a curated prescription also drops the contradicting machine-readable suggestions.	2026-07-28 20:30:23 +08:00
zhengzhijiej-tech	1b173e1953	fix(sheets): recognize OFL0X local office tokens (#2063)	2026-07-28 15:09:42 +08:00
xiongyuanwen-byted	ca7135f582	fix(sheets): correct +dim-insert --inherit-style side mapping, drop redundant none ... The flag name was inverted relative to actual behavior, and `none` was redundant. - Map --inherit-style onto the modify_sheet_structure backend so the name matches behavior (verified on a live sheet): `before` inherits the preceding row/column (side=after, position-1); `after` inherits the following (side=before). Insertion always lands before --position. - Warn only when `before` is used at the first row/column (no preceding dimension to copy from); `after` has no such edge. - Drop the `none` enum value: it was identical to omitting the flag and misleadingly implied "no inheritance" (the backend always copies a neighbour). Omitting the flag inherits the following row/column; `none` is now rejected by enum validation. Clear formats afterwards for a blank one. - Regenerate flag-defs, update tests and the skill reference.	2026-07-24 19:14:18 +08:00
xiongyuanwen-byted	7b58ba1b1d	feat(sheets): batch-update contract hardening and style-vocabulary acceptance (#2028) ... * feat(sheets): harden +batch-update sub-op contract (P0-1/2/3/5) Eval-driven fixes for the top +batch-update error clusters (137 errors across 7 eval batches, attribution in the optimization plan doc): - Reject unknown sub-op input keys with did-you-mean + full key contract instead of silently ignoring them (silent ignore surfaced as misleading 'missing required flag' errors — the largest cluster, ~35 hits). Habitual spellings are rewritten in place: camelCase -> snake_case, commandFlagAliases (new: size -> width/height on the resize pair, the pre-July vocabulary and the --styles protocol spelling, 15+ hits), single-entry ranges unwraps onto range. - Aggregate per-op validation errors into one pass (each op's first error) instead of fail-fast first-error-only; single-error batches keep the standalone-shaped error (contract tests unchanged). - Precheck cells matrix vs range locally: empty cells (prescribes +cells-clear) and row/column count mismatches no longer reach the server mid-batch. - Correct the atomicity story: execution is fail-fast without rollback (verified against live batches; docs promised a rollback that does not happen). Partial-failure errors now spell out that succeeded operations stay applied and prescribe resending only the failed tail, preventing double-apply on retry. * feat(cli): accept @file payload reads from the system temp dir (P0-6) Agents stage generated payloads (batch operations JSON, CSV) in /tmp as a matter of course; the relative-to-cwd-only policy pushed every --operations @/tmp/ops.json through an extra python/stdin round trip (recurring friction cluster in eval traces). Scope is deliberately narrow: a new SafeTempAbsInputPath accepts an absolute READ path only when it resolves (symlinks included) under the canonical os.TempDir(), and only the @file expansion in cmdutil.ReadInputFile uses it. SafeInputPath stays strict — uploads, drive sync and the CI quality gates treat 'absolute paths rejected' as a load-bearing invariant. Absolute paths outside the temp dir now get a prescriptive error naming all three options (relative path, temp-dir path, stdin). * feat(sheets): add +styles-put, +dim-delete --ranges, freeze in --styles Batch-B of the +batch-update overhaul (attribution: ~73% of real batch calls were pure formatting finishers hand-built as operations arrays). - +styles-put: declarative visual spec for existing spreadsheets. Reuses the workbook-create/table-put --styles parser (identical vocabulary and aggregate-all-issues errors), expands client-side into ONE atomic batch_update per spec: cell_merges -> cell_styles -> row_sizes -> col_sizes -> freeze. Style stamps are safe to re-run. Verified live: 6/6 sub-ops applied, frozen rows / merges / row heights confirmed by read-back. - freeze section added to the shared --styles pipeline ({rows, cols}), so +workbook-create and +table-put gain it too — closes the one gap that still forced a separate +dim-freeze call. - +dim-delete --ranges: scattered row/column ranges in one atomic batch, ordered DESCENDING so earlier deletions never shift later indexes (the recurring failure of hand-built dim-delete batches); same-dimension and non-overlap enforced, nesting inside +batch-update rejected with a prescription. - +cells-batch-set-style enters phase-1 deprecation: kept working, docs point at +styles-put, an in-band note steers new usage. Skill docs regenerated from sheet-skill-spec (new lark-sheets-styles-put reference, three-way dispatch in guideline 6, fail-fast-no-rollback wording). * feat(sheets): accept height/width as one-way aliases for size in --styles row/col_sizes size stays the canonical dimension key: it keeps row_sizes and col_sizes items shape-uniform (the array name already carries the dimension), it is what shipped with workbook-create/table-put and what models demonstrably converge on, and it matches the dimension-neutral precedent of comparable APIs. The Excel-vocabulary words are accepted silently only where unambiguous — height inside row_sizes, width inside col_sizes; the wrong dimension's word gets a targeted error instead of a rewrite, and giving both size and the alias is rejected. Shared parser, so +workbook-create / +table-put / +styles-put all gain it. * chore(sheets): sync skill docs — +cells-batch-set-style fully exits the skill surface Regenerated from sheet-skill-spec: the deprecated command no longer appears anywhere in SKILL.md or the references (multi-range styling routes to +styles-put); its flag-defs entry is untouched, so the command and --help keep working for compatibility callers, with the in-band supersedence note steering them to +styles-put. * fix(sheets): forgive habitual vocabulary on the --styles payload path 07-20 rerun attribution: the batch-update dispatch worked (calls 105->25, errors 21->8; +styles-put adopted by 16/35 tasks) but +styles-put itself hit a 56% stateful error rate — the redesign moved traffic from the flag path onto the payload path, and the round-2 forgiveness layers (key aliases, enum-value canonicalization) only existed on the flag path. Both dominant clusters are fixed in the shared styles pipeline, so +styles-put / +table-put / +workbook-create / typed --cells all gain it: - border family folding (largest cluster, up to 88 issues in one retry): borders/border objects, border_top..right objects, border_style/color/ weight scalars, and flattened border_<side>_<attr> keys all fold into the canonical nested border_styles; border_style:"thin" reads as a thin solid line (weight vocabulary in the style slot). - enum VALUE canonicalization inside cell_styles (~10 server-side round trips: vertical_alignment "center" -> "middle"), sourced from the +cells-set-style flag enums; off-enum values now fail client-side with a did-you-mean instead of failing the whole batch server-side. - wrap family: wrap_text/text_wrap -> word_wrap, boolean -> enum. - bare-string cell_merges entries read as {range, merge_type:all}. - fore_color gets a prescription (openpyxl fgColor is the FILL color; a silent pick could color the wrong thing). Replayed the eval-failing payload shapes live: 2/2 applied. * feat(sheets): resize type optional in --styles; acceptance-surface contract tests - {range, size} in row/col_sizes now means a pixel resize (type stays for standard/auto) — the payload path matches the flag path, where --width never required --type. - Two closure tests turn the --styles acceptance surface into a locked contract instead of open-ended patching: * vocabulary parity — every +cells-set-style flag (iterated from flag-defs) must be accepted verbatim by the payload path, so a future flag can never again ship without payload-path support; * prior corpus — every model spelling observed across the 07-08..07-20 eval batches must either normalize to canonical or produce a targeted prescription; silent ignoring and bare rejection both fail the suite. New eval finding -> add a corpus row -> fix -> locked. Skill docs regenerated: the border shorthand ({style,weight,color} on all four sides) is now the teaching form, border_styles demoted to per-side differences; resize examples drop the type ceremony. * fix(sheets): close the 07-21 rerun residuals — full-form thin, range coalescing, typed-cells style key Valid rerun (skill injection verified at ~31k chars/task): +styles-put stateful error rate fell 56.5% -> 34.3% and batch-update stayed at its post-dispatch low. Three residual clusters, all closed: - weight vocabulary in the FULL nested form's style slot (border_styles.<side>.style:"thin" — 8 tasks, the dominant residual; the earlier rewrite only covered the shorthand scalar path). Now normalized in expandBorderAllShorthand, the single border touchpoint shared by the flag, typed-cells and styles-payload paths. - per-row specs blowing the 100-op cap (184/203/861-op expansions): coalesceStyleStamps fuses identical-style entries into rectangles (vertical fixpoint merge on same column span, horizontal on same row span) before the cap — a declarative spec describes intent, execution shape is the CLI's to optimize. Cap message now also routes alternating-row banding to +cond-format-create. - typed --cells habitual keys (recurring server-side 900015206 in both reruns): cells[][].style object rewrites to cell_styles; cells[][].type gets a prescription instead of a server round trip. The content-in-styles message is also neutral now (was workbook-create-specific). Corpus + coalescing + typed-cells tests added; live replay: full-form thin accepted and 3 same-style rows fused, all applied. * refactor(sheets): give the style-vocabulary acceptance layer its own home Pure mechanical move, zero behavior change (locked by the acceptance contract tests). The acceptance layer had grown as an accretion across helpers.go and lark_sheet_workbook.go — deliberate design (one canonical form + wide acceptance, per the divergent-priors evidence), accidental placement. style_vocab.go now holds the whole subsystem — flag-path style builders, key aliases, enum-value canonicalization, border folding/normalization, typed-cells cell-object rewrites — under a header that states the design contract: rewrites must be unambiguous, ambiguity prescribes, silence and bare rejection are both bugs, closure is enforced by the parity + prior-corpus tests. helpers.go shrinks back to generic plumbing (818 -> 542 lines). The other two acceptance surfaces keep their own homes: cobra flag ergonomics in flag_ergonomics.go, batch sub-op key vocabulary in batch_op_dispatch.go. * fix(sheets): enforce the cells-vs-range match on single-cell ranges too The precheck deliberately skipped bare single-cell ranges when server behavior was unverified; the 07-21 rerun supplied the evidence (12 rows against range "A1" failing server-side with row count 1) — +cells-set has no anchor semantics, the strict match applies everywhere. Corpus updated accordingly. * feat(sheets): make +csv-get --range optional — omitted reads the whole sheet The tool requires a range but clips past-grid references and reports the clip in actual_range, so the CLI sends an over-wide whole-columns range (A:ZZZ) when --range is omitted: one call reads the entire sheet, no workbook-info pre-flight to size it first. Eval evidence: 'required flag(s) range not set' was the most-missed required flag on +csv-get (4 tasks in the 07-21 batch) — the models' intent was always 'read it all'. Blank --range now means the same as omitting it. Skill docs updated (quick-reference row, read-data full-read example, flag desc); round-3 backlog item A5. * feat(sheets): add editing rule #10 — never fabricate missing values 补齐 / 扩展 / 按原表格式续填时，查不到或无法确定的值一律留空 + 备注注明，禁止用推算 / 估算 / 凭空数据充数；原表已示范缺失值写法时照抄。 Synced from sheet-skill-spec (SoT). * fix(sheets): accept side-first border word order and wrap_strategy 07-21 evening batch (first run carrying the previous fixes — thin full-form / style/type keys / csv-get range all at zero): the corpus loop caught the next spelling permutations. bottom_border / bottom_border_style (side-first word order, alongside the border_bottom family already folded) and wrap_strategy (the Google Sheets API word) now normalize; three corpus rows lock them. * feat(sheets): universal did-you-mean on unknown style fields; formalize the silent-alias admission bar The alias table was drifting toward per-permutation entries with fast- falling marginal value (first aliases covered 15+ errors each, the last ones 1-2). The asymmetry that matters: rejection is universal, aliases are per-word. So: - unknown style fields now reject with did-you-mean + the full canonical field list (this error had neither — the actual reason word-order permutations turned into multi-issue retry loops). Any future permutation costs one self-healing retry, zero new code, and corrects the whole session (silent aliases never correct the model in-session). - the acceptance-layer contract now states the admission bar for silent aliases: real external vocabularies only (Excel/openpyxl, CSS, Google Sheets API — a finite set), recurring across batches or ≥3 tasks, zero ambiguity. Permutations go to the universal rejection. Existing permutation aliases are grandfathered. * feat(sheets): +cells-set --writes — scattered multi-region writes in one atomic call The last compressible batch-update scenario: eval traces show 'fix all broken formulas across ranges/sheets' (~6 calls / 3 tasks per batch) still hand-assembled as +batch-update operations arrays. --writes takes [{sheet_name|sheet_id, range, cells}, ...] (up to 100 items, cross-sheet) and fans it into ONE atomic batch_update of set_cell_range ops. Design decisions: - the sheet selector LIVES IN EACH ITEM — no top-level fallback, no precedence table; same convention models already learned from +batch-update sub-ops and +styles-put items. A top-level --sheet-name/--sheet-id with --writes is rejected with the fix. - every item runs the exact standalone pipeline via a per-item flag view: key vocabulary (camelCase, aliases, did-you-mean), the style acceptance layer for inline cell_styles, matrix precheck, schema validation; item errors aggregate so one retry fixes all. - XOR with --range/--cells/--copy-to-range; top-level --allow-overwrite propagates to items that don't override it. - nesting inside +batch-update rejected (expands into its own batch). - predictable prior handled: --styles on +cells-set now hints the layering (range-level styling -> +styles-put; per-cell styles ride in the cells objects) instead of a bare unknown-flag error. Live smoke: value + formula regions in one call, 2/2 applied. Expected effect: batch-update calls drop another ~30% to its heterogeneous-atomic-chain steady state. * chore(sheets): bump lark-sheets skill version to 3.1.0 Version roll-up for the batch-update optimization series: cells-set --writes, universal did-you-mean on style fields, border word-order and wrap_strategy acceptance, editing rule #10, and optional +csv-get --range.	2026-07-24 13:18:03 +08:00
anunwu-byted	765b097d44	Merge pull request #2027 from larksuite/feat/error-schema-hints ... Feat/error schema hints	2026-07-23 16:40:10 +08:00
wuyanchun.anunwu	4a5e2c519a	feat(sheets): 校验失败全量收集报错（一次报出所有错误） ... 为什么：fail-fast 单错报错导致「挤牙膏」修复回路——修一处、重试、 撞下一处。评测实测（turbo 三批 247 次失败）约 32% 的失败轮次是 挤牙膏，其中 local→local 类（39 次）本可一次报出。 怎么改： - validateAgainstSchema 重构为 collectSchemaErrors 收集器版：命中 错误后继续遍历，全部问题一次报出（每条带各自的教学信息） - translateBatchOperations 同步做 op 级聚合：多个坏 op 一条报错 编号列出，不再 fail-fast 在第一个 - 三条护栏：单错误输出逐字不变（向后兼容）；显示 cap 5 条 + 收集 到 6 即全树短路（病态大数组不爆炸）；类型错节点不下钻、oneOf 用一次性探测器（防级联噪音/误报泄漏） 验证：gofmt/vet 干净，go test -count=1 全过（既有测试零改动， 新增 5 个聚合测试：多错编号、cap 截断、oneOf 不泄漏、batch 双 op 聚合、单 op 保持原文）。	2026-07-20 21:11:00 +08:00
caojie0621	6ff10229fd	fix: standardize CLI shortcut text in English (#1942) ... * fix: standardize CLI shortcut text in English - translate Docs create and update help descriptions - remove localized permission annotations - replace Chinese examples and fallback text - use English labels for Docs IM Markdown resources - update regression tests for English output * test: strengthen English output contracts	2026-07-20 14:05:42 +08:00
xiongyuanwen-byted	67fc870582	feat(sheets): add --output-path for full-read file offload on cells/csv/table-get ... Reads are capped by max_chars (default 500000; the backend tool also truncates at ~50000 when unset). Add --output-path to +cells-get / +csv-get / +table-get: when set, the result is written to a cwd-relative path as JSON and the char cap is lifted to unbounded, so a large sheet lands on disk in full instead of being clipped for stdout. +table-get previously never sent max_chars, so it silently dropped rows past the backend ~50000 default with no signal. It now takes --max-chars (default 500000, sent explicitly) and surfaces truncated / truncation_warning when the read is clipped, steering callers to --output-path for a lossless full read.	2026-07-20 11:26:46 +08:00
xiongyuanwen-byted	af8e027269	feat(sheets): support --include truncation on +cells-get ... Map the new `truncation` value in --include to include_truncation_info on the get_cell_ranges tool input, so +cells-get can return per-cell isRowTruncated / isColTruncated. Flag metadata and reference synced from sheet-skill-spec; flag_defs_gen.go regenerated.	2026-07-20 11:26:46 +08:00
xiongyuanwen-byted	2efadec335	feat(sheets): cut agent error rate and --help lookups (#1911) ... ## Background Round 2 of eval-driven sheets optimization, rebased onto the latest `feat/lark-sheets-develop` (`8897196d`). ## Changes - **feat(sheets): cut agent error rate and --help lookups (eval round 2)** — targets the top failure modes from round 2 evals, reducing agent error rate and the number of `--help` lookups. - **chore(sheets): sync skill docs and flag data from sheet-skill-spec** — syncs skill docs and flag data from sheet-skill-spec. ## Notes - During rebase, the "import mislabeled .xls workbooks by sniffing content" fix already existed on the target branch (identical patch-id), so it was auto-skipped — no duplicate. - The target branch was force-rewritten and advanced in the meantime; the two new commits were cleanly replayed onto the new tip via `--onto` with no conflicts. One hunk touching the `--type` description in `lark-sheets-workbook.md` was auto-dropped because upstream already has the same end state — no content lost.	2026-07-20 11:26:46 +08:00
zhengzhijiej-tech	6c14c425fc	docs(sheets): use English placeholder in table-get guidance (#1936)	2026-07-17 17:01:22 +08:00
wuyanchun.anunwu	5fb70d326a	feat(sheets): 校验失败报错内联 schema 提示（报错即教学） ... 为什么：豆包 Excel Agent 案例中模型 7 次参数错误，报错只说"错了"不说 "怎么改对"，模型反复试错并静默降级交付（5 张饼图丢数据标签）。 怎么改： - strict unexpected-property 报错附该节点合法 key 列表（cap 15 截断） + did-you-mean（复用 internal/suggest） - required-missing 报错附缺失字段的 type/description/enum 一行提示 - 深层 type mismatch 报错附该字段 enum/description 后缀 - +batch-update 顶层 --sheet-id/--sheet-name（含下划线拼写）特判， 直接指明 per-op locator 契约，不给误导性 fuzzy 建议 - batch sub-op input 拒收 cell_styles/styles/cell_merges 包裹结构， 报错教学扁平 flags 写法 - 守护测试锁定 wrappedSubOpInputKeys 与 batchOpDispatch 的互斥假设 约束：不改 legacy 报错措辞前缀、保留 --print-schema 指针、不动宽松 AdditionalProperties 设计（内嵌 schema 当前无 strict 节点，该路径为预置）。 验证：gofmt -l 无输出、go vet 干净、go test -count=1 ./shortcuts/sheets/ ./internal/suggest/ 全部通过。	2026-07-15 18:13:22 +08:00
liangshuo-1	37d490a198	fix: unify dry-run output contract (#1870) ... * fix: unify dry-run output contract * fix: address dry-run review feedback * fix(dryrun): tighten preview contract and unify data shape - transcribe HTTP method verbatim in previews (HEAD/OPTIONS were reported as GET); reject an empty method in api with a typed error - unify the dry-run data payload across api/service/shortcut paths: {api, context?: {app_id, user_open_id}}; drop data.as — the envelope top-level identity is the single identity source - mark pretty dry-run stdout with '# dry-run: request not sent' so logs that drop stderr still show it was a preview - extract the shared preview builder, collapse PrintDryRunWithFile's loose params into FileUploadMeta, and fail loudly on nil previews - revert description-marker identity parsing: stale prose must not override corrected accessTokens (blocks legal user calls on images.create); identity gating keys off accessTokens only - pin the new contracts with tests: verbatim method, three-way context parity, nil-preview error, empty-context omission, marker line * docs(agents): add typed-data, faithful-transcription, and contract-test conventions - typed struct at the boundary over map[string]interface{} threading; distinct types where values could swap silently (internal/meta.Token) - transcribe input verbatim in previews/transformations; reject unhonorable flag combinations with typed errors instead of silently substituting behavior - contract tests must fail when the implementation is reverted * test: migrate dry-run tests grown on main to the envelope format main gained raw-format dry-run readers while the PR was in flight (wiki drive export #1802, drive list comments #1845, slash commands, sheets history, docs fetch, mail draft-send/triage, vc meeting events). Migrate them to the envelope accessors (clie2e.DryRunGet / data-wrapped decoders) and drop the now-redundant DryRunData extractions in files unified on DryRunGet. --------- Co-authored-by: guokexin.02 <264159873+Tantanz20020918@users.noreply.github.com>	2026-07-14 10:54:16 +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	4c31323de1	feat(sheets): use office_sheet_file parent_type for imported office spreadsheets (#1606) ... Image uploads to a spreadsheet hard-coded parent_type=sheet_image at every entry point. Imported "office" spreadsheets carry a token prefixed with "fake_office_", for which the drive backend requires parent_type=office_sheet_file. Funnel the parent_type selection through a single sheets-domain helper so the rule lives in one place and every image-upload path (float-image, +cells-set-image, backward +media-upload, and every dry-run preview) stays consistent. - Add sheetMediaParentType(token) in the sheets domain: returns office_sheet_file for fake_office_-prefixed tokens, otherwise sheet_image. - Add an uploadSheetImage(...) collector that builds the DriveMediaUploadAllConfig (including parent_type) once, replacing the per-call-site hand-rolled configs. - Route both main-domain image entries through the collector — float-image local upload and +cells-set-image — covering Execute and the dry-run preview body/desc. - Cover the backward +media-upload entry: single-part, multipart (>20MB), and both dry-run bodies. backward is a separate package and an intentional verbatim mirror of shortcuts/sheets/, so it keeps its own copy of the helper rather than importing the main domain. - Leave the shared common.UploadDriveMediaAllTyped upload layer untouched — the fake_office_ rule is sheets-specific and must not leak into mail/slides/doc/drive/base. Tests: - Pure-function TestSheetMediaParentType (5 cases incl. prefix-only and mid-string non-match). - Main-domain dry-run TestCellsSetImage_DryRunOfficeParentType and TestUploadSheetImage_ParentType / _FileOpenError that exercise the Execute path on the wire, asserting parent_type via the captured multipart body and typed validation metadata (errs.ProblemOf category/subtype, fs.ErrNotExist cause preserved) on file open errors. decodeSheetMediaMultipartBody fails fast on NextPart / ReadFrom errors rather than silently producing a partial body. - backward TestSheetMediaUploadExecuteOfficeParentType (real multipart wire) and TestSheetMediaUploadDryRunSmallFileOfficeParentType (small-file dry-run preview for fake_office_). - cli_e2e tests/cli_e2e/sheets/sheets_image_upload_dryrun_test.go: --dry-run end-to-end across +media-upload and +cells-set-image, native and fake_office_ tokens, asserting api.0 is POST upload_all with parent_type=sheet_image / office_sheet_file and parent_node = token.	2026-06-27 16:16:56 +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
evandance	c5b5aece33	refactor: retire legacy error envelopes and enforce typed contract (#1449) ... * refactor: retire legacy error envelopes and enforce typed contract Consolidate all command error reporting onto the typed errs.* contract, remove the legacy error surface that predated it, and tighten the lint guards so the contract holds across the whole repository going forward. Every failure now reaches stderr as one envelope shape: a category, an optional subtype, a human- and agent-readable message, and a recovery hint, with invalid parameters listed under `params`. The legacy ExitError envelope, its constructors, and the boundary bridge that promoted untyped config and authorization errors are deleted, leaving a single path from error to wire. Predicate commands keep their silent-exit behavior through a dedicated signal that carries only an exit code. Infrastructure paths that still emitted ad-hoc envelopes — flag parsing, unknown commands and subcommands, plugin and policy guards, confirmation prompts, and auth/config failures — now classify into the same taxonomy. Business, API, auth, and config exit codes are preserved; the one behavioral change is that Cobra usage failures (missing required flag, unknown command, bad arguments) now emit the typed validation envelope and exit 2, matching the explicit flag and subcommand guards, instead of Cobra's plain-text exit 1. Enforcement is repo-wide rather than per-path: - The errscontract guards run by default everywhere instead of through a migration allowlist, so legacy envelopes cannot be reintroduced anywhere. - errorlint runs across the whole repository: every error wrap must use %w and every comparison must use errors.Is/errors.As, so interior wraps stay legal but can no longer break the chain the typed boundary relies on. - The errs-no-bare-wrap guard is keyed by structural prefix instead of an explicit per-domain allowlist, so new shortcut domains are covered without editing a list. It runs where forbidigo is enabled (the shortcut domains and the auth/config/service command groups); repo-wide chain integrity for the remaining command paths is carried by errorlint above. * test: align cli_e2e success assertions to the ok envelope The api and service success path now emits the {"ok":true} envelope, so the cli_e2e workflow assertions that still expected the old {"code":0} shape via AssertStdoutStatus(t, 0) fail once they run with live credentials. Switch those workflow assertions to AssertStdoutStatus(t, true); the fake-payload helper test in core_test.go keeps its code-shape assertion.	2026-06-17 19:42:38 +08:00
evandance	b07be60068	feat(sheets): emit typed error envelopes across the sheets domain (#1348) ... Emit structured validation, API, network, file, and internal error envelopes for Sheets shortcuts so users and agents can recover from failed spreadsheet workflows using stable type, subtype, param, and code fields. Add Sheets domain errscontract and golangci guards to prevent legacy envelope and common helper regressions.	2026-06-10 11:51:42 +08:00
xiongyuanwen-byted	eed711bb11	feat(sheets): guard +csv-put --csv against a path passed without @ (#1337) ... +csv-put --csv data.csv (a forgotten @) was silently written as one-cell content, because any string parses as valid CSV — unlike malformed JSON it never errored, so the filename landed in the sheet instead of the file's contents. +csv-put's Validate now rejects a --csv value when it names a real file in the cwd subtree (guardCSVValueIsNotFilePath; fileIO.Stat, fail-open), hinting to use --csv @file or stdin (--csv -). Scoped to --csv only — no framework or other-flag change. Checking real existence (not name shape) lets inline content that merely ends in a filename pass through. Adds TestGuardCSVValueIsNotFilePath.	2026-06-09 19:48:28 +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
evandance	fe72e41fb2	feat(errs): add structured CLI error contract (#984) ... Introduce a typed error contract framework for lark-cli so in-process Go callers can branch via errors.As(&errs.XxxError{}) and shell scripts, AI agents, and protocol adapters can branch on stable JSON type/subtype fields instead of regex-parsing free-form messages. Adds: - Canonical taxonomy under errs/ (9 categories + typed Error structs embedding a shared Problem, RFC 7807-aligned) - Centralized Lark code metadata + identity-aware BuildAPIError dispatch - Typed JSON envelope writer alongside the legacy envelope writer - MCP / OAuth (RFC 6750 Bearer) projection adapters - Five CI lint guards preventing ad-hoc taxonomy drift Backward compatibility: legacy *output.ExitError producers (ErrAPI, ErrWithHint, Errorf, ErrBare) and business shortcuts that use them continue to render the legacy envelope unchanged. SecurityPolicyError wire format and exit code are preserved via a carve-out; taxonomy migration is deferred to PR 2. Domain-specific business migration is staged across PR 3+. Framework-direct paths now return typed *errs.*Error: ErrAuth / ErrValidation / ErrNetwork emit category literals on the wire (authentication / validation / network), *core.ConfigError is promoted at the cmd/root boundary with exit code aligned from 2 to 3, and Lark API permission denials classified by BuildAPIError exit 3. At the SDK boundary, WrapDoAPIError preserves any already-classified error (legacy *output.ExitError or typed *errs.*) so output.ErrAuth from missing credentials surfaces with the auth category and exit 3 intact instead of being downgraded to a network error. Policy responses classified by BuildAPIError (codes 21000 / 21001) extract challenge_url and the canonical hint from the response body, matching what the auth transport already surfaces at the HTTP layer; non-https challenge URLs are dropped. First PR in the feat/error-contract-* series.	2026-05-26 11:42:33 +08:00
zed	708cbc2b31	fix: use ErrValidation instead of fmt.Errorf in Validate paths (#1001) ... Replace 8 bare fmt.Errorf calls with output.ErrValidation across 3 files so validation errors consistently return structured JSON (type: validation, exit 2) matching the rest of the codebase. Affected functions: validateExpectedFlag (sheets), validateSendTime, validateComposeInlineAndAttachments, validateEventFlags (mail), validateSignatureWithPlainText (mail) Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>	2026-05-25 11:52:51 +08:00
fangshuyu-768	816927f8b8	fix: surface auto-grant failures via stderr and JSON hint (#1015) ... When a resource is created with bot identity, the CLI attempts to auto-grant full_access to the current user. If the user open_id is missing or the grant API call fails, the result was only written to the JSON permission_grant field and easily overlooked. Changes: - Add stderr warnings when auto-grant is skipped or fails - Add 'hint' field to permission_grant JSON output with failure reason and actionable next step (e.g. auth login, check scope, retry) - Add end-to-end skipped/failed tests across all affected shortcuts (doc, drive, sheets, slides, wiki, markdown, base) Closes #963	2026-05-21 18:17:24 +08:00
caojie0621	56749e70cb	fix(sheets): use FileIO for write-image input (#996)	2026-05-21 15:53:44 +08:00
caojie0621	ce485eb3f5	fix(sheets): declare metadata scope for info shortcut (#994)	2026-05-20 19:43:21 +08:00
史启明（QimingShi）	4b721c0410	fix(sheets): explicitly document safe JSON unmarshal ignore in DryRun (#935) ... Two DryRun functions in the sheets shortcuts called json.Unmarshal without checking the return value. This looks like a bug, but Validate already parses and validates the same --style / --data JSON before DryRun runs, so the error is structurally impossible at this point. Use _ = assignment + comment to silence the unchecked-error lint warning and make the safety invariant explicit to future readers. Co-authored-by: KhanCold <KhanCold@users.noreply.github.com>	2026-05-18 17:34:18 +08:00