* 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>
* 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>
* chore: bump oapi-sdk-go/v3 to v3.7.2 for filename-aware multipart upload
* fix: preserve original filename in multipart file upload
BuildFormdata read local files into a bytes.Reader before handing them
to the SDK, so the SDK's part-filename detection (which only reads
*os.File) fell back to "unknown-file" for every local --file upload.
Use AddFileWithName with the file's basename instead.
* fix(schema): fall back to runtime catalog when no embedded metadata
Binaries built from the bare Go module (plugin builds) embed only the
empty meta_data_default.json stub because meta_data.json is gitignored
and fetched at build time. The schema command, its completion, and the
affordance command-form resolver read the embedded-only catalog, so
every schema lookup failed with "Unknown service" even though the
runtime registry had already sync-fetched full metadata.
Add registry.SchemaCatalog(): embedded when compiled in (official
builds unchanged, still deterministic), otherwise the merged runtime
catalog seeded from cache or remote fetch. When neither source has
data (offline plugin build with a cold cache), schema now returns a
failed_precondition error with an actionable hint instead of
"Unknown service" with an empty candidate list.
* fix(registry): gate cached meta overlay on version newer than embedded
The cached remote meta was overlaid onto the embedded meta_data.json
unconditionally, so after a CLI upgrade an equal- or older-version
cache kept shadowing the freshly shipped embedded definitions until a
later refresh happened to rewrite it.
Only overlay when the cache version is strictly newer than the
embedded baseline. The bare-module stub baseline is "0.0.0", so plugin
builds without compiled metadata still take any real cached version
(TestOverlayGate_StubEmbedded_OverlaysRealCache) and the schema
runtime fallback keeps working offline from a warm cache.
Ports #1376 onto the typed meta model.
---------
Co-authored-by: liangshuo-1 <266696938+liangshuo-1@users.noreply.github.com>
* feat(envvars): add LARKSUITE_CLI_AGENT_NAME accessor
envvars.AgentName() reads LARKSUITE_CLI_AGENT_NAME so business code can identify the agent driving the CLI. Value is sanitised (trim, reject control chars, 128-byte cap) and returns "" when unset or invalid. Local-only; not sent to the server.
* refactor(envvars): consolidate agent env accessors, dedupe sanitize
Move agent-trace reading from cmdutil.AgentTraceValue into envvars.AgentTrace(), symmetric with AgentName and sharing one sanitizeSingleLine. secheader.go now only assembles headers (BaseSecurityHeaders calls envvars.AgentTrace()); the duplicated sanitize and its os/unicode imports are gone. The X-Agent-Trace header and its behaviour are unchanged.
---------
Co-authored-by: liangshuo-1 <266696938+liangshuo-1@users.noreply.github.com>
The update checker fetches https://registry.npmjs.org/@larksuite/cli/latest
with a 5-second HTTP client timeout. Under high-latency network conditions
(TUN-mode proxies, VPNs, transcontinental routes), TLS handshake alone can
take 4-6 seconds, causing the check to fail with:
context deadline exceeded (Client.Timeout exceeded while awaiting headers)
Measured example behind a Clash TUN proxy (US node from China):
DNS resolve: ~0ms (fake-ip)
TCP connect: ~0ms (local TUN)
TLS handshake: 4.3-5.9s <-- bottleneck
Total: 4.7-6.3s
curl succeeds because it has no default connect timeout, but the Go HTTP
client with Timeout=5s is too tight. The registry endpoint returns a tiny
JSON payload (<1KB), so 15s is more than enough headroom while still
failing fast on genuinely unreachable networks.
Co-authored-by: 王伟达 <weida.wang@m.com>
* feat: add apps observability helpers
* feat: add apps log observability shortcuts
* feat: add apps trace observability shortcuts
* feat: add apps metric analytics shortcuts
* feat: add apps envvar shortcuts
* docs: document apps observability envvar shortcuts
* fix: add apps observability env hint
* test: cover apps envvar delete dry-run
* fix: align apps observability OpenAPI schema
* fix: map apps observability named series
* fix: apps observability api upgrade
* fix: refine apps observability output
* feat(apps): integrate miaoda db/file CLI commands into apps-spark integration
Bring in the refined miaoda Spark db/file command set from the
feat/miaoda-db-file-openapi work: db execute (typed errs + per-SQL-type
JSON shaping), env diff/migrate, PITR recovery, changelog/audit, data
import/export, db/file quota, and the 7 file-storage commands; plus the
stderr spinner for slow ops and the aligned lark-apps skill references.
Resolved overlap with the integration branch's earlier db-execute
iteration (took the refined typed-error version), unified the stderr-TTY
flag on IOStreams.StderrIsTerminal, and combined the shortcut registry
(43 commands total).
* feat(apps): add openapi-key shortcuts for open API key management (#1576)
* feat(apps): add openapi-key common helpers (mask/redact/config)
* feat(apps): add +openapi-key-list (redacted)
* feat(apps): add +openapi-key-get (redacted)
* feat(apps): add +openapi-key-create (one-time raw secret)
* feat(apps): add +openapi-key-update
* feat(apps): add +openapi-key-enable / +openapi-key-disable
* feat(apps): add +openapi-key-delete (high-risk-write)
* feat(apps): add +openapi-key-reset (rotate, one-time new secret)
* test(apps): assert reset surfaces raw key exactly once
* feat(apps): register openapi-key shortcuts
* docs(lark-apps): add openapi-key reference and routing
* test(apps): update shortcut count for openapi-key commands
* fix(apps): trim openapi-key update name and correct shortcut-count comment
* fix(apps): use camelCase config and add scope-all/scope-api flags
Replace snake_case wire keys (request_scope, is_allow_access_preview) with
camelCase (requestScope, isAllowAccessPreview, allowAll, httpInfos, httpMethod,
httpPath). Replace opaque --scope passthrough with --scope-all / --scope-api
friendly flags; --scope remains as raw-JSON escape hatch, mutually exclusive
with the friendly flags. Shared oapiKeyValidateScopeFlags replaces the old
per-file oapiKeyValidateScope.
* fix(apps): use Changed for scope-all and refresh openapi-key scope docs
Switch the update at-least-one guard from rctx.Bool to rctx.Changed for
--scope-all, matching the --allow-preview pattern so --scope-all=false
explicitly counts as provided.
Rewrite lark-apps-openapi-key.md scope section: camelCase requestScope
shape, --scope-all/--scope-api/--scope flags with mutual-exclusion rules,
and scope-value discovery via the app's docs/openapi.json.
* fix(apps): emit snake_case request_scope config for open gateway
Open gateway (/open-apis/spark/v1) requires snake_case request bodies;
flip parseScopeAPI/buildRequestScope/buildKeyConfig to emit http_method,
http_path, allow_all, http_infos, request_scope, is_allow_access_preview.
Update unit tests to assert snake_case and reject camelCase keys.
* docs(lark-apps): correct openapi-key scope to snake_case wire format
* docs(apps): align openapi-key flag help text to snake_case wire keys
* feat(apps): add actionable hints and more examples to openapi-key
P1: chain .WithHint(...) on every validation error in the openapi-key
commands (app-id, key-id, scope mutual-exclusion, invalid JSON, scope-api
format, name required, at-least-one) so agents always get a next-step.
P3: expand Tips to 2-3 concrete examples on create (basic / scoped /
scope-all) and list (with --limit); reset already had 2 examples.
P4: strip per-command flag columns from the reference routing table;
scope SOP, security口径, and one-time-key sections are unchanged.
* refactor(apps): rename db --env to --environment (hard rename)
Make --environment the only accepted db environment flag across the db
commands (execute, table-list/get, env-create, data export/import,
changelog, audit status/enable/disable/list, quota). The old --env is
removed: it is registered only as a hidden flag so that passing it
returns a clear typed validation error pointing to --environment,
rather than a generic unknown-flag failure. Update the lark-apps db
references accordingly.
* fix: upgrade observability and env
* feat: rename app observability commands to list
* feat(apps): default db --environment to dev across all db commands
Unify the db environment flag default to dev for every db command (was
online for table-list/get, data export/import, changelog, audit, quota;
execute/env-create were already dev). Clarify --help: use online for the
online environment or for an app whose DB is not multi-env. Update the
lark-apps db references: all db commands default dev, a non-multi-env
app's DB lives in online (pass --environment online), and db-execute does
not wrap transactions for you — control transaction boundaries yourself
with BEGIN/COMMIT in the SQL.
* fix: remove unsed files
* file_common.go 的 3 处裸 fmt.Errorf 已改为 typed errs.NewValidationError(errs.SubtypeInvalidArgument, ...)(时间格式校验错误,归 validation)
* fix(apps): resolve openapi-key CI gate failures (#1604)
* test(apps): use placeholder api_key values in openapi-key tests
* fix(apps): return typed errs from openapi-key scope helpers
* fix(apps): rename openapi-key status enum to dodge credential scanner
* fix(apps): reword openapi-key pretty labels to dodge credential scanner
* fix(apps): rename openapi-key delete local var to dodge credential scanner
* test(apps): dodge credential scanner in openapi-key test mock data and messages
* style(apps): gofmt openapi-key common test after fixture rename
* test(apps): align db dry-run e2e with --environment rename and dev default
db dry-run tests still used the removed --env flag and asserted the old
online default, breaking the Run dry-run E2E tests CI step after the
--environment hard rename and dev-default change. Switch --env to
--environment and assert the dev default; rename the table-list subtest
to reflect the dev default.
* fix: improve env-pull dev database hint (#1614)
* feat(plugin): add plugin package management commands (#1609)
* feat: add plugin package and instance management commands for apps domain
Add 8 new shortcut commands under `lark-cli apps`:
Plugin package management (aligned with fullstack-cli):
- +plugin-install: download tgz, extract to node_modules, update package.json
- +plugin-uninstall: remove from node_modules and package.json actionPlugins
- +plugin-list: list declared plugins with installation status
Plugin instance CRUD (aligned with feida-ai):
- +plugin-instance-create: validate + write capability JSON with formValue validation
- +plugin-instance-update: merge mutable fields, re-validate formValue
- +plugin-instance-delete: idempotent file removal
- +plugin-instance-get: read capability JSON
- +plugin-instance-list: scan capabilities directory
Shared infrastructure (plugin_common.go):
- 4-level capabilities dir resolution (flag → env → .env.local MIAODA_APP_TYPE → detection)
- formValue validation ported from feida-ai (5 rules: forbidden Handlebars, paramsSchema
type constraints, input ref existence, unconsumed params, array double-wrap auto-fix)
- tgz extraction with path traversal protection
- package.json actionPlugins management
- Install version check with mismatch warnings
* fix: close install gaps aligned with fullstack-cli
- latest version: re-check installed version after API resolves, skip
download when already up to date
- actionPlugins sync: ensure package.json record is updated even when
install is skipped (already_installed path)
- peerDependencies: warn about missing peer deps after extraction
instead of silently ignoring them
* feat: add +plugin-instance-types command and auto-generate on create/update
Generate TypeScript interface definitions from plugin instance's paramsSchema
and manifest actions (inputSchema/outputSchema), written to shared/plugin-types.ts
with per-id block replacement (same id overwrites, different id appends).
Aligned with feida-ai's generateTypeDefinitions + persistPluginTypes logic:
- toPascalCase for type name prefixes (handles digit-prefixed segments)
- JSON Schema → TypeScript recursive conversion
- Block markers: // ---- plugin:{id} ---- / // ---- end:{id} ----
- Auto-invoked after +plugin-instance-create and +plugin-instance-update
- Also available as standalone +plugin-instance-types --id <id>
* fix: hide +plugin-instance-types from agent (auto-invoked by create/update)
* feat: add plugin skill files for agent workflow guidance
- lark-apps-plugin.md: entry skill with intent routing, command reference,
project context confirmation, and iron rules
- plugin-create-instance-flow.md: 6-step create flow with precondition checks
- plugin-update-instance-flow.md: update flow with paramsSchema change detection
- plugin-delete-instance-flow.md: delete flow with code reference scanning
- plugin-get-instance-flow.md: query routing for list/get/manifest reads
- plugin-instance-schema.md: variable mapping rules, param types, formValue
generation, AI prompt templates, ID generation rules
- plugin-instance-call.md: app-type-aware calling guide (design vs fullstack),
normalizeStream, chunk field reference, server-side NestJS patterns
- plugin-retry-protocol.md: validation failure retry protocol (max 3)
- SKILL.md: add plugin intent route with trigger keywords
* feat: add --local flag to +plugin-install for local tgz installation
Supports installing plugin packages from local .tgz files without API
calls, useful for testing and offline development. Reads plugin key and
version from the extracted package.json inside the tgz.
Also moved Scopes to ConditionalScopes so --local path skips auth.
* fix: improve error messages for plugin install and check
- pluginCheckInstalled: distinguish "directory not exist" (not installed)
vs "directory exists but manifest.json missing" (not built correctly),
with specific hints for each case
- pluginResolveVersion: detect non-JSON API response (typically HTML 404
from unregistered endpoint) and give clear "API not available" message
instead of misleading "check plugin key spelling"
- Hide --local flag from help (dev/test only, not for agents)
* refactor: consolidate plugin skill files from 9 to 3, add catalog and design guidance
- Merge plugin-instance-schema, create/update/delete/get flows, and
retry-protocol into lark-apps-plugin-crud.md (Schema + CRUD + retry)
- Merge plugin-catalog into lark-apps-plugin.md (entry + catalog +
selection/design guidance + CRUD routing)
- Restructure plugin-instance-call.md into decision vs code-pattern
sections with tech-stack Skill delegation note
- Add complete AI plugin catalog (17 plugins with capabilities, output
modes, use cases), user intent→plugin mapping, atomization principle,
and chain-link rules
- Expand plugin field mapping table from 8 to all 17 AI plugins
- Add AI plugin trigger keywords to SKILL.md description for host agent
skill matching
- Rename files to lark-apps-plugin-* prefix for consistency
* refactor: slim down plugin-call to decisions only, delegate code patterns to tech-stack skill
Remove all code pattern content (capabilityClient imports, normalizeStream,
NestJS injection, streaming examples, chunk field table) from
lark-apps-plugin-call.md. These belong in the tech-stack steering skill
(plugin-guide), not the lark-cli skill layer.
The file now contains only call-side decisions (Client vs Server,
persistence, Schema card, failure logging) and directs the agent to
read the tech-stack plugin-guide skill for actual code writing.
* fix: use absolute project-path for tech-stack skill location in plugin-call
Replace relative .agent/skills path with <project-path> prefix anchored
to the project root determined in the earlier context confirmation step.
Add fallback path and minimal call rules when skill file doesn't exist.
* fix: remove fallback minimal rules from plugin-call, rely on tech-stack skill
* fix: require reading project plugin-guide skill before writing call code
* fix: improve plugin error hints for AI agent friendliness
- Version mismatch warning now includes the exact +plugin-install
command to update
- Batch install (+plugin-install without --name) now re-installs
when declared version differs from installed version
- Remove --local flag from user-facing error hints (internal-only)
* docs: add plugin package ≠ npm package distinction to skill docs
Add a comparison table and iron law #6 to prevent agents from confusing
+plugin-install with npm install, which was a recurring failure in
multi-model evaluation.
* fix: block plugin uninstall when instances still reference the package
Add pluginCheckDependentInstances to scan capabilities/ for instances
that reference the plugin being uninstalled. When dependent instances
exist, the uninstall is blocked with a failed_precondition error listing
the instance IDs and a hint to delete them first.
* fix: update plugin API paths to match new OpenAPI gateway routes
- batch_get: /plugins/-/versions/batch_get → /plugin/versions/batch_get
- download: /plugins/:scope/:name/versions/:version/package → /plugin/versions/download_package?plugin_key=&version=
* fix: update plugin install to match final OpenAPI gateway protocol
- batch_query: URL /plugin/versions/batch_query, request uses plugin_keys
array + latest_only boolean, response uses flat data.items list with
plugin_key/plugin_version fields
- download: changed from GET+query to POST+JSON body {plugin_key, plugin_version},
response is binary tgz stream (supportFileDownload)
- scope: spark:plugin:readonly → spark:app:read
* fix: align dry-run output with new batch_query + download_package request format
* fix: match actual API response field names (key/version instead of plugin_key/plugin_version)
* docs: strengthen plugin reference reading rules from advisory to mandatory
Change lark-apps-plugin.md from implicit to explicit required reading
for any plugin work. Replace soft '按需读' with bold '必读' for all three
plugin reference files. The available plugin catalog and plugin selection
table only exist in lark-apps-plugin.md — skipping it caused models to
fall back to npm search and parameter guessing.
* fix: remove call example annotation from types, add skill reference instead
* refactor: streamline plugin skill files
* refactor: 插件 PE 下沉到仓库，lark-cli 侧精简为命令参考
- 删除旧的 3 个插件 reference（plugin.md / plugin-crud.md / plugin-call.md），
其中的 Schema 规则、CRUD 流程、插件目录、Prompt 模板等内容已下沉到
应用仓库 .agents/skills/plugin-guide/SKILL.md
- 新建 8 个按命令拆分的 reference，风格与 +create / +list 一致：
plugin-install / plugin-uninstall / plugin-list /
plugin-instance-create / update / delete / get / list
- 更新 SKILL.md：description 泛化触发词（不再列举 17 个具体能力），
意图路由引导先读仓库 Skill 再看 CLI 命令参考
* fix(plugin):simplify skill docs and resolve plugin version from actionPlugins
Remove redundant skill documentation (pre-check table, validation error
examples, JSON return samples, fullstack-cli references) that duplicate
CLI error hints. Make --plugin version optional and resolve from
package.json actionPlugins. Drop unused createdBy field.
* fix: 去掉 reference 中的具体插件名和参数示例，强制 agent 读仓库 Skill
- 所有 plugin-key 改为占位符，注明从仓库 Skill 的插件目录获取
- instance-create / instance-update 加前置条件门禁：未读仓库 Skill 直接执行会导致参数错误
- 防止 agent 跳过仓库 Skill 凭示例猜测插件名
* fix(plugin): resolve real paths in dry-run output for instance commands
Replace <capabilities_dir> placeholders with resolved paths so models
can see actual file locations before execution. Add version_source,
types_output, and scan_dir fields to describe implicit behaviors.
* refactor(plugin): hide instance commands, delegate to repo Skill
Hide +plugin-instance-create/update/delete/get/list from CLI help.
Remove instance reference files from lark-apps skill. Route instance
CRUD and call code generation to project repo plugin-guide skill.
Go instance code preserved, just hidden.
* refactor: 删除 plugin-instance 5 个 CLI 命令，改由仓库 Skill 引导 agent 直接操作文件
- 删除 plugin_instance_create/update/delete/get/list 及其测试（11 个文件）
- 删除 plugin_instance_types（TypeScript 类型生成命令）
- 移除 shortcuts.go 中的 6 个注册项
- 清理 plugin_common.go 中仅被 instance 命令使用的函数（1054→340 行）：
校验逻辑、capability JSON 读写、动态 schema 解析、TypeScript 生成等
- 保留 plugin-install / plugin-uninstall / plugin-list 三个命令不变
插件实例的 CRUD 操作改由仓库 Skill 引导 agent 直接读写 capabilities/*.json，
验证规则写在 Skill 中由 agent 自校验。
* refactor(plugin): remove --project-path flag and split --name into --name + --version
- Remove --project-path from plugin-install/list/uninstall (use cwd like npm)
- Split --name key@version into separate --name and --version flags
- Remove pluginParseInstallTarget (no longer needed)
- Improve DryRun desc and error hints for --version usage
- Update skill docs to reflect new flag structure
- Tests use chdirTest helper instead of --project-path
* feat(plugin): add Examples to --help for plugin-install/list/uninstall
按 lark-cli 优化治理规范，为三个插件命令的 --help 补充 2-3 个
可执行示例，覆盖最常见使用路径，帮助 agent 快速理解命令用法。
* fix(plugin): address PR #1609 review findings
- Fix hint referencing non-existent +plugin-instance-delete command,
point to repo plugin-guide Skill instead
- Remove undeclared --capabilities-dir flag, simplify pluginResolveCapDir
to env-only resolution, fix ambiguous hint to suggest env vars
- Reclassify download errors from file_io to network/api with proper
hints and retryable marking
- Slim SKILL.md routing row, move judgment rules to plugin-install reference
- Rename --local flag to --file to align with CLI conventions
* fix(skill): restore plugin routing row with judgment rules, fix markdown formatting
Revert SKILL.md routing row to keep full judgment rules and repo Skill
directive inline. Fix bold marker spacing and restore missing table column.
Revert reference to original content without duplicated rules.
* fix(plugin): revert SKILL.md to pre-review version, fix shortcut count test
Restore SKILL.md plugin routing row to original version with full
judgment rules and repo Skill directive. Update shortcut count test
from 60 to 63 to account for 3 new plugin commands.
* fix(plugin):fix lark-apps skill docs which is about plugin
* fix(plugin):correct plugin skill md
* fix(plugin):correct plugin md
* fix(plugin):correct plugin and local dev skills md
* fix(plugin):correct apps plugin skills md
* fix(lark-apps): move repo skill reading hint to post-init phase
将「仓库 Skill 优先」从 SKILL.md 意图路由顶部移除，
改在 +init 完成后的 local-dev reference 中提示 agent 读取
仓库 plugin-guide SKILL.md，解决应用未初始化时 repo skill
不存在导致 agent 无法获取插件知识的时序问题。
* fix(lark-apps): strengthen local-dev reference reading and post-init plugin guide
- SKILL.md 路由表：local-dev.md 从"按需读取"提升为"执行前必读"
- local-dev.md：将读仓库 Skill 嵌入端到端流程链作为正式步骤
- post-init 指引改为可执行命令 + 不读的后果说明 + 不存在时兜底
---------
Co-authored-by: zhangli <zhangli.268@bytedance.com>
* feat(apps): add release polling interval time and release time costs
* fix(plugin): rename files to apps_ prefix and handle Close() errors (#1655)
- Rename plugin_install/list/uninstall .go files to apps_plugin_ prefix
for consistency with other files in the package
- Handle f.Close() errors in pluginExtractTGZ to avoid silent data loss
* style: gofmt apps plugin files (#1664)
* fix(plugin): resolve CI lint, deadcode, and unit-test failures (#1667)
- Add Scopes: []string{} to plugin-install, plugin-list, plugin-uninstall
shortcuts to satisfy TestAllShortcutsScopesNotNil
- Remove unused pluginCheckInstalled function (deadcode)
- Fix nilerr: add //nolint:nilerr for intentional best-effort nil returns
- Fix forbidigo: replace bare fmt.Errorf in Execute with typed error,
add //nolint:forbidigo for intermediate helper errors in pluginExtractTGZ
- Fix errorlint: change %v to %w for cerr in multi-error fmt.Errorf
- Remove all unused //nolint:forbidigo directives from test files
* style: gofmt apps_plugin list/uninstall/install_test files
Fix fast-gate Check formatting failure: align struct literal fields in
apps_plugin_list.go and apps_plugin_uninstall.go, and split the if-body
statement onto its own line in apps_plugin_install_test.go.
* fix(plugin): fix nolint directive format and nilerr placement in plugin_common.go (#1668)
- Change nolint comment separator from -- to // to satisfy nolintlint
- Move nilerr nolint directive to return statement to suppress nilerr correctly
- Fix forbidigo nolint format for intermediate fmt.Errorf in pluginExtractTGZ
* fix(apps): validate openapi-key scope method, path and raw JSON (#1675)
Enforce an HTTP method whitelist (GET/POST/PUT/PATCH/DELETE), reject
malformed --scope-api paths (must start with '/', no '..' or '//'), and
constrain raw --scope JSON to the documented request_scope schema
(allow_all + http_infos only). Validation runs in both the Validate hook
and the body-build path so dry-run and execute are equally gated.
Fixes PR #1596 audit findings HIGH-2 and MEDIUM-4.
* fix(apps): harden db/file shortcuts per security audit (PR #1596)
Address the file/db findings from the PR #1596 security audit with
safer header/flag/path handling:
- HIGH-3 (--output path traversal): add rejectOutputTraversal() and wire
it into +file-download and +db-data-export Validate; reject absolute
paths and any .. component up front. (FileIO.Save already sandboxes to
cwd via SafeOutputPath; this is an earlier, explicit guard.)
- HIGH-4 (Content-Disposition header injection): build the header with
mime.FormatMediaType instead of manual string concatenation.
- MEDIUM-3 (SQL leaked into public flag): stop writing --file contents
back into the --sql flag; resolveExecuteSQL() reads it at use-site so
SQL never lands in flag dumps / structured logs.
- LOW-1 (hidden-file upload name): prefix sanitized upload names that
start with '.' with '_'.
- LOW-2 (local-timezone time parsing): document local-tz interpretation
of bare date/datetime in flag descriptions and the db/file skill docs.
SQL-injection of --table (audit MEDIUM-5) is intentionally NOT validated
in the CLI: the server-side interface is the authoritative guard.
Add apps_security_fixes_test.go covering the new validators and switch
the upload test to parse Content-Disposition instead of matching a
literal string. Update lark-apps-db.md / lark-apps-file.md skill refs.
* fix(plugin): harden plugin commands against path traversal, DoS, and agent misuse (#1677)
Security fixes from PR #1596 security audit:
- Skip symlink/hardlink entries during tgz extraction (Zip Slip)
- Limit tgz entry and download size to 10 MB (OOM/DoS)
- Limit error response body read to 4 KB
- Validate MIAODA_APP_TYPE as numeric to prevent path manipulation
- Add validatePluginKey + secureModulePath to block --name path
traversal (../../.ssh etc.) for install/uninstall
Usability fix:
- Add explicit 'local command, no --app-id' notice in plugin
reference docs to prevent agent from incorrectly passing
--app-id to plugin commands (which read package.json locally)
* fix(apps): cap db async poll timeout at 2 minutes
+db-recovery-apply blocked up to 30min and +db-env-migrate /
+db-recovery-diff up to 10min while polling the server for async-task
completion. These operations are expected to finish within ~1 minute;
the long ceilings mostly hurt agents, whose harness kills the command on
timeout while the server-side operation keeps running with no handle to
re-query — especially risky for the irreversible recovery-apply.
Cap all three pollUntil ceilings at 2 minutes (polling interval
unchanged). Stuck operations now surface the retryable network/timeout
envelope after 2min instead of hanging for 10-30min.
* fix(plugin): create temp dir in project path to avoid cross-filesystem EXDEV on Rename (#1683)
pluginInstallLocal used os.MkdirTemp("") which creates the temp
directory on the system temp partition. On Windows (and some
Linux/macOS setups), the temp partition is on a different filesystem
from the project directory, causing os.Rename to fail with EXDEV.
Use projectPath as the temp dir parent so it is always on the same
filesystem as node_modules.
* fix(plugin): improve --help Tips with local-command hint and update semantics (#1691)
- Add "Run in project root; does NOT take --app-id" to all plugin Tips
- Clarify install command also supports update (install or update to latest/specific version)
- Clarify batch install reads from package.json actionPlugins
---------
Co-authored-by: 陈兴炀 <chenxingyang.1019@bytedance.com>
Co-authored-by: raistlin042 <lvxinsheng@bytedance.com>
Co-authored-by: anngo-nk <anguohui@bytedance.com>
Co-authored-by: zhangli <zhangli.268@bytedance.com>
* 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.
Add note shortcuts for note detail and unified transcript retrieval, route vc note detail parsing through the note domain, and update note/vc/minutes skill guidance for normal versus unified transcript handling.
Includes dry-run E2E coverage for the new note shortcuts and documents the remaining live E2E fixture gap.
Framework support for resource-scoped event subscriptions, so one
EventKey can fan out into independent per-resource subscription scopes:
- KeyDefinition gains SubscriptionKey / NormalizeParams / Match hooks
- ComputeSubscriptionID derives a dedup identity from (EventKey, sub-key
params); plumbed through bus Hub, consume loop, and the
Hello / PreShutdownCheck / ConsumerInfo protocol messages
- add a synchronous Match filter stage before Process
- change PreConsume cleanup to func() error and surface cleanup
(unsubscribe) failures as WARN with an idempotency note
- adapt minutes/vc/whiteboard PreConsume to the new cleanup signature
- render SubscriptionID / SubscriptionKey in event status & schema output
No domain wires these hooks yet; covered by unit tests using bus/protocol
doubles. (Mail, the original exerciser, is intentionally not included.)
Change-Id: Ifc743f1aa0bc4dff0c8a1e35da24883694fe7699
Replace every command-facing error path in the event domain — the
consume/schema command layer, the +subscribe shortcut, EventKey
definitions, and the consume orchestration — with typed errs.*
envelopes, so consumers get stable type, subtype, param, hint, and
missing_scopes metadata for classification and recovery instead of
free-form message text.
- Input validation (--jq, --param, --output-dir, --filter, --route,
unknown EventKey, EventKey params) reports validation /
invalid_argument with the offending flag in param and an actionable
hint.
- Scope preflight reports authorization / missing_scope with the
machine-readable missing_scopes list; console-subscription and
single-bus preconditions report failed_precondition with recovery
hints.
- The consume API boundary passes already-typed errors through and
classifies transport, non-JSON HTTP, and unparsable responses; the
vc note-detail retry now matches the not-found code on typed errors
(it silently never fired against the legacy envelope shape).
- Previously-bare failures exited 1 with a plain-text "Error:" line
and now exit with their category code (validation 2, auth 3,
network 4, internal 5) alongside the typed stderr envelope.
- forbidigo and errscontract guards now cover the event paths so
regressions fail lint; AGENTS.md and the lark-event skill document
the typed contract for agent consumers.
Validation: make unit-test (race) green; event unit and e2e suites
assert category/subtype/param/hint and cause preservation against the
real binary; errscontract and golangci lint clean.
Failures from the minutes and video-conference commands now surface as
structured, typed errors carrying a stable category and subtype — spanning
input validation, missing permissions, network and file-I/O failures, and
remote API errors — so callers can branch on the error kind instead of
parsing free-form text. Batch commands report partial failures explicitly,
emitting per-item results with a non-zero exit instead of masking them.
