feat(mail): HTML lint lib + Feishu-native autofix + lark-mail skill#3
Closed
bubbmon233 wants to merge 1 commit into
Closed
feat(mail): HTML lint lib + Feishu-native autofix + lark-mail skill#3bubbmon233 wants to merge 1 commit into
bubbmon233 wants to merge 1 commit into
Conversation
bubbmon233
force-pushed
the
feat/lark-mail-bundle
branch
16 times, most recently
from
ba31a8f to
4965946
Compare
为 lark-cli mail 写信路径添加完整的 HTML 防御 + LarkSuite mail-editor 原生 autofix lint 体系，并立起 skills/lark-mail/ 一整套（5 个模板 / 2 篇 references / SKILL.md 入口）。
新增 lint 包 + `+lint-html` shortcut + 写信路径强制 lint。
安全 / 兼容 / 飞书原生 三档 rule:
- error（删除）: <script> / <iframe> / <form> / <input> / <link> / <object> / <embed>、on* event handlers、javascript: / vbscript: / file: URL
- warning + 自动修复: HTML4 过时标签 <font> → <span style>、<center> → <div text-align>、<marquee> / <blink> → <span>
- inline style allowlist 过滤: 保留 color / font-* / margin-* / padding-* / border-* / background-color / list-style-* / text-* / line-height / letter-spacing / vertical-align / cursor / opacity / transition / display / box-sizing / width-* / height-*
<style> tag passthrough: 飞书 mail 服务端渲染时加 CSS scope 前缀（`.msg-XXX <selector>`），class 隔离不污染整体页面。
飞书原生 autofix pass (~550 lines):
- <p> → mail-editor 双层 div（外层 `margin:4px 0;line-height:1.6` + 内层 `dir="auto" style="font-size:14px"`）
- <ul> / <ol> / <li> 补 `data-list-bullet/data-list-number` marker + 5 件套 inline style + 内容双层 span 包裹（`<span style="font-family:inherit"><span style="color:rgb(0,0,0)">…</span></span>`）
- <blockquote> 灰边样式（`padding-left:0px;color:rgb(100,106,115);border-left:2px solid rgb(187,191,196);margin:0px`）
- <a> → `not-doclink` class + 飞书蓝 `rgb(20,86,240)` + 无下划线
- ol/ul 直接子节点 whitespace text node strip（pretty-print 缩进 / 换行不渲染为可见空行）
hasInlineStyleProp shorthand 识别: margin / padding shorthand `margin:0 0 0 24px` 视为已声明 margin-left，避免 autofix 误追加 `margin-left:0` 覆盖嵌套列表 24px 缩进。
写信路径强制 lint: `+send` / `+draft-create` / `+reply` / `+reply-all` / `+forward` / `+draft-edit` body op 自动 autofix；新增 `+lint-html` shortcut 支持 `--strict`（0 finding 才返回成功）。
5 MVP templates (pre-rendered Feishu-native, lint --strict 0 error):
- newsletter--weekly-brief.html — 资讯周报（gradient banner / section 标签 / 文章卡）
- weekly--personal-report.html — 个人周报（3 段 + `<div padding-left:24px>` 包 ul 缩进）
- weekly--team-report.html — 团队周报（顶层 ol + 3 级嵌套 ul/ol shorthand margin + 共享 `data-ol-id` 跨 list 接续编号 + mention chips + 黄色高亮）
- research--market-report.html — 市场调研报告（gradient header / 4 stat cards / 8 章节卡 + Bug 风险清单）
- job-application--resume.html — 求职简历（9 sections / 技能 chip / table 个人信息 / 工作-项目 ol+ul 嵌套）
2 篇 references:
- lark-mail-html.md — 邮件 HTML 写法指南：文风规范 + LarkSuite 原生写法 7 铁律 + 4 档处理表 + tag/attr/CSS 白名单 + 可复制片段速查 + 错误示例 + 3 套场景模板
- lark-mail-lint-html.md — `+lint-html` 用法
入口：SKILL.md HTML quickstart + assets/templates/README.md 列出 5 个预制模板。模板数量较少，AI 直接遍历 templates/ 目录选用即可，不附检索脚本。
@用户 mention chip:
<a id="at-user-N" href="mailto:user@bytedance.com"
style="cursor:pointer;color:rgb(20,86,240);padding:2px;text-decoration:none;border-radius:999em;margin:0px 2px"
rel="nofollow noopener noreferrer">@姓名</a>
`id="at-user-N"` 是唯一硬要求（飞书客户端 isAtUserDOM 只查 `id?.startsWith('at-user')`）。`data-user-id` 不写（OAPI 没合法路径拿真实 user-id）。业务方只填 `mailto:` 和 `@姓名` 两处。
文字高亮（荧光笔风格）: 统一黑字 `rgb(31,35,41)` / 不加粗 / 不带 padding / 不带 border-radius。3 色 palette 按语义:
- 粉色 `rgb(255,200,220)`: 关键里程碑 / 重要数据
- 黄色 `rgb(255,225,140)`: 待关注 / 阻塞 / 需跟进
- 浅绿 `rgb(190,230,200)`: 已完成 / 关键成果
- shortcuts/mail/lint/linter_test.go: 涵盖每条 rule 的 error / autofix / strict 模式 + cleaned HTML 对比断言；TestRun_FeishuListShorthandMarginPreserved 守护 nested-list 24px 缩进不被 autofix 覆盖
- shortcuts/mail/mail_lint_html_test.go + mail_lint_writepath_test.go: shortcut 端到端 + 写信路径强制 lint
- 5 个模板 lark-cli mail +lint-html --strict 0 error
- 5 个模板 lark-cli mail +draft-create smoke test 飞书 mail 视觉验收
`go test ./shortcuts/mail/lint/... ./shortcuts/mail/...` 全绿。
Change-Id: Ie1e54d6b4029526951a9f785547c8b93b6a6cb81
bubbmon233
force-pushed
the
feat/lark-mail-bundle
branch
from
4965946 to
bd26efa
Compare
Owner
Author
|
Superseded by #4 (clean history, single commit, refreshed PR description). Closing. |
bubbmon233
pushed a commit
that referenced
this pull request
Jun 5, 2026
…package (larksuite#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 foun…
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
为 lark-cli mail 写信路径添加完整的 HTML 防御 + 飞书原生 autofix lint 体系，并立起
skills/lark-mail/一整套（5 个模板 / 2 篇 references / SKILL.md 入口）。Changes
Lint library (
shortcuts/mail/lint/)新增 lint 包 +
+lint-htmlshortcut + 写信路径强制 lint。安全 / 兼容 / 飞书原生 三档 rule：
<script>/<iframe>/<form>/<input>/<link>/<object>/<embed>、on*event handlers、javascript:/vbscript:/file:URL<font>→<span style>、<center>→<div text-align>、<marquee>/<blink>→<span><style>tag passthrough：飞书 mail 服务端渲染时加 CSS scope 前缀（.msg-XXX <selector>），class 隔离不污染整体页面。飞书原生 autofix pass（~550 行）：
<p>→ mail-editor 双层 div（外层margin:4px 0;line-height:1.6+ 内层dir="auto" style="font-size:14px"）<ul>/<ol>/<li>补data-list-bullet/data-list-numbermarker + 5 件套 inline style + 内容双层 span 包裹<blockquote>灰边样式（padding-left:0px;color:rgb(100,106,115);border-left:2px solid rgb(187,191,196);margin:0px）<a>→not-doclinkclass + 飞书蓝rgb(20,86,240)+ 无下划线hasInlineStylePropshorthand 识别：margin / padding shorthandmargin:0 0 0 24px视为已声明 margin-left，避免 autofix 误追加margin-left:0覆盖嵌套列表 24px 缩进。写信路径强制 lint：
+send/+draft-create/+reply/+reply-all/+forward/+draft-editbody op 自动 autofix；新增+lint-htmlshortcut 支持--strict（0 finding 才返回成功）。Lint 适用范围：
+reply/+reply-all/+forward仅 lint 用户撰写的 body + signature 部分，原始邮件 quote 区（adit-html-block/history-quote-*/lark-mail-doc-quote等飞书原生 markup）原样保留，避免 double-sanitize 破坏合法引用结构。skills/lark-mail/(parallel toskills/lark-slides/)5 MVP 模板（pre-rendered 飞书原生，
lint --strict0 error）：newsletter--weekly-brief.html— 资讯周报（gradient banner / section 标签 / 文章卡）weekly--personal-report.html— 个人周报（3 段 +<div padding-left:24px>包 ul 缩进）weekly--team-report.html— 团队周报（顶层 ol + 3 级嵌套 ul/ol shorthand margin + 共享data-ol-id跨 list 接续编号 + mention chips + 黄色高亮）research--market-report.html— 市场调研报告（gradient header / 4 stat cards / 8 章节卡 + Bug 风险清单）job-application--resume.html— 求职简历（9 sections / 技能 chip / table 个人信息 / 工作-项目 ol+ul 嵌套）2 篇 references：
lark-mail-html.md— 邮件 HTML 写法指南：文风规范 + LarkSuite 原生写法 7 铁律 + 4 档处理表 + tag/attr/CSS 白名单 + 可复制片段速查 + 错误示例 + 3 套场景模板lark-mail-lint-html.md—+lint-html用法入口：
SKILL.mdHTML quickstart +assets/templates/README.md列出 5 个预制模板，直接遍历目录选用即可，不附检索脚本（模板数量较少）Conventions sealed
1. 飞书原生 HTML 7 铁律（lint autofix 实现，AI 写最简陋 HTML 即可，autofix 自动补全）：
<p><ul>/<ol>必带data-list-*marker + 5 件套 inline style；<ol>必带start="1"<li>必带 class（temp-li bullet1/number1） + data marker + 内容双层 span 包裹（<span style="font-family:inherit"><span style="color:rgb(0,0,0)">…</span></span>）<blockquote>左侧 2px 灰边样式<a>加class="not-doclink"+ 飞书蓝 + 无下划线<font>/<center>/<marquee>/<blink>自动现代化2. 多级缩进：lark-cli mail 写信路径推荐
<div style="padding-left:24px">包 ul/ol（lint 不动 div padding，最稳）；mail-editor 原生 wrapper + inner shorthandmargin:0 0 0 24px也支持（lint shorthand 识别已修复）。子层 li class 降一级（bullet1→bullet2→bullet3/number1→number2），list-style-type同步降级（disc→circle→square/decimal→lower-alpha）3. 父项加粗一致性：父项要么都加粗、要么都不加粗（hierarchy 靠 ol 数字编号 + ul circle 子项自然形成）。如需强调具体字段，用文字高亮替代加粗，避免破坏一致性
4. 状态文字嵌入式：参考徐龙 0613 周报样例 — 状态文字嵌入 li 末尾「，已完成 / 进行中 / 评审中 / 阻塞 / 待启动」，不用 badge / chip 标签（保持纯文本流，避免视觉碎片）
5.
<style>块透传：飞书 mail 服务端渲染时加 CSS scope 前缀，inline style allowlist 不支持的属性（gradient / box-shadow / flex / gap）放<style>块即可（research--market-report.html 即用此方案实现 gradient header + stat cards 视觉）6. @用户 mention chip：
id="at-user-N"是唯一硬要求（飞书客户端isAtUserDOM只查id?.startsWith('at-user')）。data-user-id不写（OAPI 没合法路径拿真实 user-id）。业务方只填mailto:和@姓名两处；OAPI 写信路径不触发 IM 通知 — mention chip 仅作客户端识别 + 视觉一致7. 文字高亮（荧光笔风格）：统一黑字
rgb(31,35,41)/ 不加粗 / 不带 padding / 不带 border-radius。3 色 palette 按语义：rgb(255,200,220)rgb(255,225,140)rgb(190,230,200)Test Plan
go test ./shortcuts/mail/lint/... ./shortcuts/mail/...全绿（含TestRun_FeishuListShorthandMarginPreserved守护 nested-list 24px 缩进不被 autofix 覆盖）lark-cli mail +lint-html --strict0 errorlark-cli mail +draft-createsmoke test 飞书 mail 视觉验收Related Issues