examples-surface-only promised that demos may consume only the assembled CLI
and the public plugin SDK, but it enforced two denied prefixes instead, so
every tree nobody thought to deny was permitted. A demo importing `events`,
`errs` or a `cmd` subpackage passed the gate, and because
extension-zero-internal exempts these packages from the transitive check,
nothing examined what those imports dragged in either. The exemption was
therefore unbounded in what it covered, the same defect as the directory-name
skip it replaced.
- Add Rule.AllowedRepoDeps, which inverts the check: any dependency inside
this module that is not listed is a violation. Standard library and
third-party packages, including same-organisation modules that are not this
one, stay outside the rule.
- Pin examples-surface-only to exactly `cmd` and `extension/platform`, so the
rule name matches what it enforces and the inherited chain stays bounded by
a direct surface of two packages.
- Cover the reproducers as contract cases: other repository trees, `cmd`
subpackages, other `extension` subtrees, and the module root are rejected,
while the two allowed packages plus non-module imports are not.
layering-edges.txt stays at 39 rows; the demos already import only the two
allowed packages.
The extension rule skipped any package whose import path contained
"/examples/", which let the gate miss two things: a directory named
examples anywhere under extension escaped the rule outright, and the
sanctioned demos were exempt from every denial rather than only from the
internal packages they inherit through cmd.
- Drop SkipFrom (and containsAny) so no rule can exempt by directory name.
- Exempt the two wrapper-main demos from extension-zero-internal by exact
import path. Their cmd import is the pattern they exist to demonstrate,
and seeding those edges instead would wedge the ratchet: the edges track
cmd's transitive set, so a new internal package under cmd would demand a
new row that check-layering-ratchet.sh refuses by design.
- Add examples-surface-only: demos may consume cmd and extension/platform
but must not directly import internal or shortcuts. Zero violations today.
layering-edges.txt stays at 39 rows, so the ratchet bootstrap snapshot
still matches.
Layering edge parsing and graph coverage:
- Reject whitespace-padded exception fields instead of silently trimming
them, so a padded row is a malformed row rather than a coerced identity;
add a padded-field parse test.
- Fail loud when any release target/tag combination lists zero packages,
which would otherwise let the layering graph silently under-cover.
- Document the build-tag scope (demo tags excluded), the SkipFrom substring
semantics, and the toolchain-derived support set behind the drift check.
GoReleaser drift checks:
- Reject custom build commands and per-target overrides as unsupported.
- Detect --tags in addition to -tags when rejecting release build tags.
- Reject any GO* build environment variable (except CGO_ENABLED=0) through a
single default branch instead of an explicit allowlist.
- Validate the GoReleaser global env block, and make the go-list stderr test
table-driven across the default and authsidecar graphs.
Check all seven published GOOS and GOARCH combinations, and keep go list diagnostics separate from its JSON output for cold caches.\n\nMake the bootstrap snapshot immutable in CI, propagate shell failures explicitly, isolate sourced execution, and add deterministic regression tests for each contract.
Add a data-driven architecture layering test that builds the full import
graph (go list -json -tags authsidecar) and evaluates six rules:
- extension must not depend on internal (transitive; keeps it extractable
as a standalone SDK module)
- events must not depend on shortcuts (transitive)
- shortcuts must not directly import auth/keychain/credential/client/vfs
(direct; must go through the shortcuts/common RuntimeContext gate)
- cmd subpackages must not import shortcuts (assembly point + cmd/auth only)
- errs must stay a leaf
- internal must not depend on cmd/shortcuts/events
Pre-existing violations are seeded into layering-edges.txt (37 rows). The
test rejects any unseeded violation (new debt) and any stale row (removed
debt), and CI locks the effective row count to only ever decrease. Removes
the tautological circular-dependency check from arch-audit.yml, since Go
already forbids import cycles at compile time.
Form submission writes and submits data through a public share link, an
irreversible action that should require explicit confirmation. Reclassify
the shortcut from write to high-risk-write so the runner's --yes gate fires
before execution, matching +form-delete and other high-risk base commands.
Update the lark-base skill docs (--yes on all examples, param table, tips)
and add tests pinning the confirmation gate (unit) and dry-run structure (e2e).
Co-authored-by: yballul-bytedance <273011618+yballul-bytedance@users.noreply.github.com>
feat(slides): add layout density lint for sparse/empty containers
Extend the XML layout lint into a single release gate for Slides XML:
- Add blank_slide, sparse_container_content, and sparse_slide_content
detection, using visibility- and coverage-aware heuristics (alpha
filtering, image-overlay/layout-panel exemptions, similar-short-card
grouping) to avoid flagging intentional whitespace or background
panels
- Broaden out-of-canvas detection from table/chart/text-only to every
element kind, with rotation-aware bounding boxes and geometry
extraction for icon/line/polyline
- Restructure output to schema v2.0: every issue carries rule
(id/name/comparison/threshold), measurement, related_objects, and
hint; summary gains status/release_ready/screenshot_review_required
- Change CLI exit-code semantics so only errors block (exit 1);
warning-only output still exits 0 to let downstream screenshot review
proceed
- Harden XML attribute parsing (single/double-quoted and spaced
attributes, self-closing tags no longer bleeding content into the
next element) and fix edge cases surfaced during review
(image-overlay coverage ratio, invisible container/panel exemptions,
bbox_overlap measurement consistency, background-only slide bypass,
invisible short-card peers)
- Update SKILL.md, validation-checklist.md, and troubleshooting.md to
match the new gate; add regression tests for the new rules and fixes
* docs(base): clarify complete and partial updates
Consolidate the update rule introduced in #1879 and make the command-contract boundary explicit. Full-update commands must use trusted current configuration for the first actual request, while delta commands should send the smallest legal payload.
* docs(base): clarify full-update state preservation
Address review feedback by requiring unchanged writable configuration to remain intact, except when the requested update makes a setting inapplicable.
* docs(base): strengthen update contract guidance
From EVAL-07-22-02-53 (42 convos), agents fell back to the full XSD for:
- shape type enum + presetHandlers (rounded corners)
- polyline (bounding-box positioning, required border, connector type)
- table merged cells (colspan / rowspan)
Add compact coverage for each, sized to real usage (shape/polyline type
lists trimmed to what actually appears in generations). Chart gaps deferred.
paas_storage AppFileListForOpenAPI rejects page_size > 200 at the inner
checkMaxKeys guard with ErrInvalidRequest("maxKeys not in range (0, 200]").
Previously the CLI forwarded any --page-size straight to the API, so
--page-size 500 produced an opaque server error round-trip.
Add a client-side Validate check bounding --page-size to [1, 200] (aligned
with the existing validateAppsPageSize precedent in the observability
commands): out-of-range values now fail fast with a typed validation error
and never hit the network. The server tolerates page_size <= 0 by defaulting
to 20, but the CLI default is already 20 and an explicit < 1 is a user error,
so we reject it for a clearer message, consistent with other list commands.
Update the flag description and the lark-apps-file skill reference to
document the 1..200 range, and cover the boundaries in unit tests.
Card header icon documentation contained invalid tokens (e.g., mail_colorful, approve_colorful) that do not render, and icon guidance lacked precise token enumeration, causing LLM to guess or fabricate icon tokens. This PR replaces
examples with valid tokens and adds a definitive colorful icon reference table.
The API always returns presentation/slide XML as a single unindented
line, which is unreadable for decks with many shapes (e.g. PPTX-imported
presentations). slides +xml-get now formats it on the surfaces meant for
a human or a line tool to read:
- --raw and --output reindent the XML with etree so each structural
element (presentation/slide/shape/style/...) sits on its own line.
Reformatting never recurses into schema-mixed text-bearing elements
(p, span, strong, em, u, del, a, shadow, outline, chartTitle,
chartSubTitle), so rich-text content stays exactly as parsed. CDATA
sections and the schema's  /	/ / whitespace character
references (decimal, hex, and zero-padded) are preserved through the
parse/write pass instead of being silently normalized away. There is
no flag to disable this formatting.
- The default JSON envelope returns the server's XML verbatim: it is
never parsed, so it stays a byte-exact copy of the API response, at
no reformatting cost and with no failure mode on this path.
- If reformatting --raw/--output content fails (non-strict XML from the
service), the command falls back to the original content, prints a
warning to stderr, and reports pretty_printed: false in --output file
metadata.
Adds github.com/beevik/etree as a direct dependency.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
When creating an event as a bot, resolve the bot's own open_id via
/bot/v3/info and add it to the attendee list, mirroring how a user is
auto-joined to their own events; warn and proceed without it if the
lookup fails. Also note in the +create skill doc that the user-search
API is user-only, so resolving a name to open_id needs --as user.
* refactor: add output emitter contract and differential harness
Introduce a leaf Emitter in internal/output that composes the existing
output primitives (content-safety scan, envelope, jq, format rendering,
notice) behind a single command-scoped port. The emitter is unwired: no
production caller is migrated, so CLI output stays byte-for-byte unchanged.
A differential test harness drives the real legacy entry points
(RuntimeContext.Out/OutRaw/OutFormat/..., WriteSuccessEnvelope and the
pagination formatter) and asserts byte-identical stdout/stderr plus typed
errors, locking behavior before later slices migrate callers.
* refactor: tighten emitter API and cover pagination with real tests
- split Emitter.Success/PartialFailure and drop EmitOptions.OK so a
missing ok flag can no longer silently emit ok:false
- give StreamPage its own StreamOptions (format + pretty) instead of
reusing EmitOptions, making "jq needs aggregation" a compile-time fact
- pin the Emitter jq-error contract (returns error, writes no stderr);
the caller adapter re-emits the legacy stderr line on migration
- add in-package tests driving the real apiPaginate/servicePaginate over
a mock transport: multi-page aggregation, empty-result fallback,
MarkRaw handling, and the business-error raw-response red line
* test: use standard TestFactory harness for pagination tests
Replace the hand-rolled RoundTripper + APIClient construction in the
apiPaginate/servicePaginate tests with cmdutil.TestFactory and its
httpmock.Registry, and isolate LARKSUITE_CLI_CONFIG_DIR to t.TempDir(),
matching the repo's standard HTTP-mocked test convention. Assertions and
coverage (multi-page aggregation, empty-result fallback, MarkRaw, and the
business-error raw-response red line) are unchanged.
* refactor: route success output through the single Emitter port
Migrate the success-output surfaces onto internal/output's Emitter,
byte-for-byte identical (proven by frozen golden diffs and the real
paginate/HandleResponse tests):
- RuntimeContext.Out/OutRaw/OutFormat/OutFormatRaw/OutPartialFailure now
build an Emitter and call Success/PartialFailure; emit and outFormat are
removed. An adapter maps the returned error back to the legacy
outputErrOnce / jq-error stderr / exit-code behavior.
- WriteSuccessEnvelope degrades to a thin Emitter.Success delegate; its 8
callers are unchanged.
- apiPaginate/servicePaginate stream pages via Emitter.StreamPage; the
aggregate and business-error raw-response branches are untouched.
- HandleResponse routes its non-JSON structured-response branch through
Emitter.Success.
Frozen golden fixtures replace the runtime legacy oracles so the
differential harness cannot go self-referential after migration.
* fix: keep _notice on struct payloads in Emitter's unknown-format fallback
printLegacyDataJSON now normalizes via toGeneric first (matching FormatValue), so a struct / named-map payload retains its injected _notice on the unknown-format -> JSON fallback rather than dropping it silently. Add a regression test that fails against the pre-fix path.
* refactor: make the Emitter own write failures and stop mutating inputs
Route every Emitter stdout path through a render-to-buffer-then-copy helper so a marshal/render failure leaves stdout empty and surfaces a typed internal error (with cause), and a stdout write failure is propagated instead of silently swallowed. Leaf writers gain error-returning Write* cores; the legacy Print*/FormatValue wrappers keep their exact behavior for unmigrated callers.
- handleEmitterError now captures every error, not only the jq/safety branches; flip OutRaw's write-error test to assert propagation.
- Clone the map before injecting _notice so a caller's payload is never mutated and an existing _notice is never overwritten.
- Preserve jq's own typed error (validation/api) on a bad expression or runtime failure; only wrap genuine stdout write failures.
- Split tests: normative emitter_contract_test.go vs frozen emitter_legacy_compat_test.go (base SHA recorded, self-update env vars removed).
* fix: satisfy license-header and forbidigo lint on the emitter changes
- Move the base-SHA note below the copyright header in the renamed legacy-compat test so the license-header check sees a valid header at the top.
- Route the leaf wrappers' marshal/format stderr messages through a single legacyStderrf helper (one //nolint:forbidigo) instead of bare os.Stderr, preserving exact legacy behavior for unmigrated direct callers while passing forbidigo; drop the now-unused os imports.
* fix: stop legacy CSV wrappers reporting write failures to stderr
Align FormatAsCSV/FormatAsCSVPaginated and FormatValue/FormatPage's CSV branch with the other leaf wrappers: report only marshal failures, swallow write failures. Previously they emitted a 'csv write error' for the (empty) line and the JSON-fallback write failures that the pre-refactor code ignored, and mislabeled a JSON write failure as a CSV one. Failure-path only; success output is unchanged (golden double-diff still byte-for-byte).
* feat(apps): add design_html app type support and credential author identity
- Add design_html to appTypePolicies (same as modern_html: skip install/env-pull/skills-sync)
- Route +html-publish via policy (useTOSPublish) instead of hardcoded type check
- Parse commit_author_name/commit_author_email from +git-credential-init response
- Use server-provided author identity for repo-local git config, fallback to defaults
- Support meta_token as identifier in +get command
- Use envvars.AgentName() for source_agent in +create (reads LARKSUITE_CLI_AGENT_NAME)
- Add creative HTML guide reference skeleton and SKILL.md routing entry
- Update git-credential skill docs with new output fields
* fix(apps): unify html-publish to TOS path, add html to init skip policy
- Remove useTOSPublish policy field, html-publish always uses TOS upload
- Add html type to appTypePolicies (skip install/env-pull/skills-sync)
- Remove design_html from policies (not yet in use)
- Fix git credential dry-run test for new local_effects entry
* feat(apps): validate --app-id format to reject meta_token with resolution hint
* feat(apps): integrate creative-design skill and update skill docs
- Add creative-design skill under lark-apps/ (same level as references/)
- Update SKILL.md description with creative design trigger keywords
- Add creative design routing in development path selection table
- Add --path relative path guidance in html-publish reference
- Remove old creative-html-guide skeleton (replaced by creative-design)
* feat(apps): skip app sync for html/modern_html in +init
Add skipAppSync policy field; html and modern_html skip npx app sync
on non-empty repo path since static HTML sites don't need it.
* fix(apps): merge creative-design into html routing and add intent entry
- Merge static HTML and creative-design into one path selection row
- Add creative-design intent routing entry before html-publish
* docs(apps): add html local dev flow, unify publish link source
- Add html端到端 flow in local-dev.md (create → init → dev → release-create)
- Unify publish link source: html and full_stack both use +release-get
- Update SKILL.md routing and publish护栏 accordingly
* fix(apps): update html-publish dry-run and skill docs for TOS flow
- DryRun shows actual 3-step TOS flow (pre_release → TOS PUT → release-create)
- Skill docs: output is release_id, use +release-get to poll for online_url
- Remove references to legacy multipart upload and data.url
* TEMP: pin miaoda-cli alpha and add BOE header for testing
- Pin miaoda-cli to 0.1.24-alpha.fb2cf0a (revert to @latest before merge)
- Add x-tt-env=boe_aily_lark_cli header globally (remove before merge)
- html app-type uses --template design-html instead of --app-type (remove before merge)
* docs(apps): add creative mode link format and meta_token recognition
- Add creative mode (html) link format `https://{tenant}/page/{meta_token}` in publish护栏
- Note dev and publish URLs are the same for creative mode, unlike full_stack
- Add meta_token to app_id resolution with full link format in app_id获取
* docs(apps): route html apps through local-dev git pipeline by default
- Select dev path: html apps now default to local-dev pipeline instead of skipping local/cloud axis
- Intent routing: creative-design publishes via local-dev flow instead of +html-publish
- Remove +html-publish fallback from local-dev "when not to use" section
* docs(apps): generalize skill references to cover both html and full_stack
Remove full_stack-only wording from init, create, list, env-pull, and
release-create references since html apps now share the same local dev
and release flow.
* feat(apps): add meta_token to +get pretty output and dry-run description
* docs(apps): unify html as creative mode, fix routing and local-dev flow
- Remove "HTML" as separate dev path; html and full_stack both go through local-dev
- Intent routing: read local-dev before creative-design to establish git pipeline first
- Mark +html-publish as legacy, redirect to local-dev for creative mode
- Split html local-dev into 3 scenarios: first-time, iteration, pre-generated files
- git add . instead of selective add to capture all creative-design output files
* docs(apps): remove dev link from html-publish output, only return release-get online_url
* fix: add license header to deck-stage.js
* docs(apps): clarify dev link only for full_stack, creative mode shares dev/pub URL
* docs(apps): remove +html-publish from intent routing, description, and guardrails
All HTML apps now go through local-dev pipeline. +html-publish is deprecated.
* docs(apps): remove html-publish references from create/release-create/cloud-dev pages
html-publish is no longer the recommended path for HTML apps; all html
and full_stack apps now follow the same local-dev + release-create flow.
* fix(apps): address PR review feedback
- html-publish dry-run: register all 3 API calls (GET pre_release, PUT TOS, POST release-create) instead of hiding steps in metadata
- validateRealAppID: remove cli_ prefix check (not a valid app_id prefix)
- E2E: update git-credential dry-run to expect 4 local_effects
- E2E: update html-publish dry-run to expect GET pre_release
* fix(apps): address PR review — remove legacy multipart dead code, fix docs
- Delete html_publish_client.go and html_publish_client_test.go (legacy multipart)
- Remove runHTMLPublish, enrichHTMLPublishAPIError, buildHTMLPublishFailureHint
- Migrate tests from runHTMLPublish to prepareHTMLPublishTarball (same coverage)
- Remove cli_ prefix from validateRealAppID (not a valid app_id prefix)
- Fix html-publish.md error wording to match actual message
- Register all 3 TOS API calls in html-publish dry-run
- Update E2E tests for new dry-run contract
* fix(apps): correctly merge SKILL.md with main (role mgmt, auth wording, source boundary)
Rebuild SKILL.md from our branch version, then merge in main's additions:
- description: add HTML静态站点发布, 应用角色与成员管理, 应用角色/角色成员
- 身份与授权: use main's updated wording (no proactive re-login)
- intent routing: add +role-* row, +init refs 平台资源与应用源码边界
- 能力边界 → 平台资源与应用源码边界 (7 rules from main)
- 禁止预授权底线: add role ② and html-publish ③ clauses
* docs(apps): route legacy html-publish only for non-git html apps
* docs(apps): strengthen local-dev routing and git recovery guidance
fix:cherry-pick and resolve conflicts
* fix: gofmt apps_errors.go and apps_errors_test.go
* docs(apps): strengthen git credential recovery and add file-upload guidance
- Generalize git error recovery: any git operation failure triggers
+git-credential-init refresh, with environment analysis on failure
- Add resource file upload rule: use +file-upload instead of local
paths, base64 inlining, or git commits; files are app-scoped
* test(apps): strengthen html-publish dry-run assertions for TOS 3-step contract
* fix: 文件资源上传
* docs(apps): update creative-design skill content
* fix: re-add license header to deck-stage.js
* refactor(apps): merge system-prompt.md into SKILL.md for creative-design skill
Consolidate the thin SKILL.md wrapper and the full system-prompt.md
methodology into a single file, eliminating an unnecessary indirection.
Update references in claude.md and codex.md accordingly.
* chore: revert TEMP changes — miaoda-cli back to @latest, remove BOE header
* docs(apps): remove 可见范围 from 发布态护栏
创意模式的可见范围权限走 lark-drive 文档权限体系，而非妙搭应用
权限体系，当前的 +access-scope-set/get 无法正确管理创意模式应用
的可见范围。待文档协作支持妙搭能力后，再通过 lark-drive 域能力
引导修改。
TODO: 等文档协作支持妙搭能力后，在 skill 中加入使用文档域权限
能力修改创意模式可见范围的引导。
* docs(lark-apps): 在平台资源与应用源码边界添加路径规则，引导 agent 使用相对路径
`apps` 命令的 `--path`、`--file`、`--output` 只接受 cwd 下的相对路径，传绝对路径会报错。
* docs(lark-apps): 新增创意模式评论路由和裸 meta_token 识别引导
- 意图路由表新增创意模式应用评论，引导走 lark-drive 文档评论体系
- app_id 获取章节补充裸 meta_token 识别：非链接非 app_ 开头时尝试用 +get 解析
* refactor(apps): flatten creative-design built-in-skills into references
- Delete built-in-skills/ directory (9 nested sub-skill folders)
- Move media skill content to references/ as flat .md files
- Add assets/index.html React+Babel starter template
- Integrate publishing flow into creative-design SKILL.md
- Update harness reference docs (aily/claude/codex.md)
- Simplify lark-apps SKILL.md routing to point directly to creative-design
- Remove creative-design standalone .git directory
* refactor(apps): rename creative-design/SKILL.md to creative-design.md
Avoid being mistaken as an independent skill entry point.
Update all internal references (lark-apps routing table + 10 reference files).
* fix(apps): fail closed when queryAppType fails instead of falling back to full_stack
queryAppType now returns an error instead of silently returning "".
+init aborts if the app type cannot be determined, preventing wrong
scaffold type from being committed and pushed to the repository.
---------
Co-authored-by: zhangli <zhangli.268@bytedance.com>
* feat: clarify local trigger automation
* docs: refine trigger automation guidance
* docs: correct trigger release contracts
* docs: separate trigger enable and probe authorization
* docs: link the enable-only trigger path
* test: harden trigger authorization contracts
* docs: harden trigger disabled-state handling
* docs: harden trigger release state handling
* docs: verify a finished release before enable
* docs: split trigger start and test flows
* docs: fail closed after trigger probe errors
* docs(apps): fail closed on trigger test and release-create failures
Harden the automation guide's state handling. When testing an existing
online trigger, a formerly-disabled trigger is always restored to
disabled on probe success, failure, uncertain result, or early exit.
When +release-create itself errors or returns no release_id, treat it as
not published and restore the prior trigger state; when the result is
unknown, keep it disabled and verify via +release-list before deciding.
* docs(apps): flag online_url as creator-only before sharing
Point the local-dev and release-get release flows to the access-scope
step so a returned online_url is not presented as a shareable link
without the creator-only visibility caveat, matching the SKILL.md
visibility contract.
* docs(apps): drop out-of-scope SKILL.md edits from the trigger change
The local trigger automation work does not require touching the lark-apps
SKILL.md: its description already routed automation, so compressing it only
dropped routing keywords (access scope, monitoring metrics, trigger
subtypes) to satisfy a non-blocking length convention. Restore SKILL.md to
its prior state and remove the description/optional-output assertions that
only guarded those reverted edits. Release-output-as-optional correctness
remains covered by the release-get contract.
Clarify that smart notes (AI summary) and their verbatim docs are
auto-authorized to participants, while minutes carry the raw recording
and require explicit authorization. Rewrite the artifact-selection rule
to cover transcripts: use whichever exists when only one is present,
follow the user's explicit choice, and default to smart notes when both
exist and the user is unspecified.
* docs(base): disambiguate filter DSL and value shape to cut retry loops
Eval traces show the Base filter/view chain loses time to avoidable
error->lookup->retry loops:
- record/view --filter-json (tuple [[f,op,v]]) gets confused with
+data-query's object filters ({field_name,operator,value}) -> 800010701
- scalar fields (text/number) get array-wrapped values -> 800010507
- agents guess a field is select from its name, or guess enum values in
Chinese when stored values are English -> 0 hits then retry
Add a top-of-doc section to the tuple-DSL SSOT (value shape by field type,
check field type first, don't confuse with data-query, use real stored
values), a reciprocal warning in data-query, and two recovery rows in
SKILL.md. Flag-level details (--limit vs --page-size) are left to command
--help per the skill's stated design.
* refactor(base): fold filter guidance into existing sections, drop overfit examples
Address review feedback on the first pass:
- remove the added top-level '## 0 …先读' section — it duplicated §3 (per-type
value rules) and §7 (易错点), and its examples (状态=="Open", 工时>=3.5)
overfit the eval case and even clashed with §3's own 状态-as-select example.
- instead sharpen what already exists: §7 names the shared commands and the
data-query object shape to avoid; §6 gets one process rule (confirm field
type / real values first); all example-free and principle-based.
- revert the data-query.md note (wrong direction; the confusion is fixed at
the record/view tuple-DSL SSOT).
- slim the SKILL.md recovery rows to terse, message-keyed, reference-pointing
entries matching the table's style.
* docs(base): clarify full and partial update guidance
* docs(base): clarify partial update payload guidance
---------
Co-authored-by: wanglei.75 <wanglei.75@bytedance.com>
* fix: standardize CLI shortcut text in English
- translate Docs create and update help descriptions
- remove localized permission annotations
- replace Chinese examples and fallback text
- use English labels for Docs IM Markdown resources
- update regression tests for English output
* test: strengthen English output contracts
* ci: deduplicate PR runs and serialize live E2E
* ci: preserve live E2E cleanup on supersession
* ci: harden live E2E supersession check
* ci: gate live E2E on dry-run planning
Make the dry-run result a hard prerequisite for live E2E so skip-mode changes never acquire the repository-wide slot. This intentionally trades one full dry-run duration of live startup latency for lower contention on the exclusive queue.
* ci: bound dry-run E2E planning
The dry-run job is now a hard prerequisite for live E2E. Bound its
execution so a stalled planning job cannot delay a PR verdict for the
default six-hour job limit.
* test: tighten live E2E supersession contract
Register approval.instance.status_changed_v4 and approval.task.status_changed_v4 with custom flattened schemas and user-auth pre-consume subscription setup.
Handle approval subscription_type as optional multi-value pre-registration metadata: omitted values register both involved and managed relations, explicit values can be single, comma-separated, or JSON array, and consumers do not unsubscribe on exit.
Report partial approval subscription registration failures with registered and failed relation context while preserving the underlying typed error classification.
Document approval event output fields and subscription semantics, and refresh approval skill references from API metadata.
* fix: converge drive delete workflow test on terminal state
* fix: narrow drive delete tolerance to the verified transient
* test: lock the delete failure guard with a subprocess contract test
* test: lock task-result and retry-exhaustion failure boundaries
A get_node success response may omit data.node/node_token (the field is
optional), so a missing token must not be read as proof of deletion.
Classify the response as same / different / unknown: only a different
non-empty node_token proves the original node is gone (move-to-drive),
while an unknown identity keeps polling in isWikiNodeDeleted and still
attempts deletion in deleteWikiNodeAndVerify instead of leaking nodes.
An ongoing meeting has no minute/note yet, so the recording lookup in
+detail returned an unclassified error that was surfaced as a hard error,
making the whole command exit 1 / ok:false even though meeting.get had
already succeeded.
Detect the in-progress state up front (same start/end heuristic as
+meeting-events, reading raw timestamps) and skip the recording call,
returning the meeting metadata with an informational hint instead of an
error. Recording failures for ended meetings are likewise degraded to a
hint rather than failing the command.
Also note in the vc-agent skill that sending an in-meeting message only
needs meeting_id and must not pre-fetch +detail / +recording / +notes.
* docs(apps): add platform SQL authoring guide to the db-execute skill
Aligns the lark-cli apps +db-execute skill with the Miaoda platform's
SQL constraints (the same dataloom backend the sandbox miaoda-sql skill
targets), so agents writing SQL via the CLI don't get server-rejected or
build tables that misbehave. Previously the skill covered only the command
contract with zero SQL-content guidance.
Adds a "平台 SQL 规范" section to lark-apps-db-execute.md covering:
- Platform-forbidden SQL (DATABASE/SCHEMA/USER/ROLE/OWNED) that hard-rejects
- CREATE TABLE template: 4 audit columns + RLS + 4 default policies
- user_profile compound type (ROW()::user_profile, (field).user_id, index)
- Audit column names and semantics
- DDL rules: IF NOT EXISTS support matrix; pre-check online rows before
adding constraints, split by UNIQUE / tighten-to-NOT-NULL / new-NOT-NULL-column
- SELECT / DML safety rules and common PostgreSQL pitfalls
Sandbox-specific bits (miaoda command names, generate_image, test-user
list, schema.ts codegen, string error codes) are intentionally excluded.
Wires pointers from SKILL.md routing and lark-apps-db.md.
* docs(apps): address review nits on the db-execute SQL guide
- Drop the IF NOT EXISTS support matrix (redundant / conflicted with the
extension-allowlist note in the callout).
- Use `orders` instead of the built-in composite type `user_profile` as the
bare-table-name example, which was misleading.
- Remove the "user_profile PRIMARY KEY" suggestion for person tables (the
composite carries mutable fields; a uuid PK is the right default).
* fix(base): improve dashboard shortcut guidance
* docs(base): refine dashboard funnel guidance
* docs(base): drop redundant block-get audit tip
The 'do not audit every block after creation' hint duplicates the
create-then-suppress-get guidance already in lark-base-dashboard.md,
so remove it from the +dashboard-block-get tips to keep them focused.
* test(base): drop stale block-get audit tip assertion
Commit 778da63a removed the 'do not audit every block' tip from the
+dashboard-block-get source as redundant but left the matching
assertion in TestBaseDashboardHelpGuidesAgents, breaking the unit
test. Remove the stale assertion to realign the test with the tips.
* docs(base): clarify when NOT to use helper table for dashboard blocks
* fix(base): defer record-list --json to framework shorthand (align with main)
* fix(base): reject non-string dashboard sort.order instead of silently defaulting to asc
* docs(base): fix reversed cumulative-funnel direction (suffix sum + assumptions)
* docs(base): scope dashboard-arrange to explicit request or fresh new dashboard
* test(base): pin missing sort.order behavior; clarify --no-validate is raw pass-through
* docs(base): show real CLI envelope {ok,identity,data} for get-data and data-query outputs
Note that meeting owner must be set via vchat.meeting_settings.owner_id
with vchat.vc_type=vc, effective only for app (bot) identity on app
calendars, since +create does not expose this field.
* feat(apps): add automation_common helpers (paths, type map, conditions, redaction)
* feat(apps): add +automation-list with pagination and type filter
* feat(apps): add +automation-get with webhook token redaction
* feat(apps): add +automation-create with four trigger types
* feat(apps): add +automation-enable and +automation-disable
* feat(apps): add webhook url/token flag implementations for automation
* feat(apps): add +automation-update dispatching to PATCH and webhook flags
* fix(apps): validate --cron/--white-ip-list up-front in automation-update
* feat(apps): register automation trigger commands
* docs(apps): add automation triggers skill reference and intent routing
* fix(apps): redact webhook token in +automation-list output
* test(apps): update shortcut count for automation commands
* test(apps): rewrite automation registration E2E to positive contract
The commands are now implemented and registered, so the pre-implementation
"unknown subcommand" assertion is permanently obsolete. Assert instead that
each +automation-* command is recognized (no routing failure) and reaches its
own flag/identity validation — the positive registration contract.
* fix(apps): list valid statuses in feishu-approval validation error
The design spec requires the rejection message to enumerate the valid status
set for the event-type so an agent can self-correct. Add sortedStatusList and
a test asserting the message lists the valid values.
* docs(apps): strengthen automation routing anchor and high-risk protocol
Two skill-doc gaps let agents misroute or skip confirmation on
high-risk automation writes:
- "审批通过自动触发" was pulling the agent into lark-event (event
stream) instead of apps +automation-create feishu-approval. Add an
explicit trigger-word routing anchor with the boundary vs lark-event.
- Agents knew --reset-url --yes but skipped confirmation and loop-
guessed trigger names. Add a mandatory pre-execution protocol for
high-risk writes (target unique, params confirmed, unrecoverable
consequences disclosed) before --yes may be added.
Reference-only edit; no CLI code/flag changes.
* docs(apps): require concrete defense-line alternative in unauth-callback warning
The "disable-token + empty white-list" combination leaves a webhook
callback with no authentication and no origin restriction. The prior
warning correctly asked for confirmation, but stopped at "no defense
left" without pointing the user at the "keep at least one line"
alternative and without warning upfront.
Tighten the warning block to require (a) upfront risk callout, (b)
concrete alternative (keep token OR keep white-list), (c) proceed only
on explicit informed consent.
Reference-only edit; no CLI code/flag changes.
* docs(apps): surface automation-trigger scope in lark-apps SKILL description
Agents were failing to open lark-apps when the request phrased the intent
in natural language ("审批通过后自动触发", "每天定时触发", etc.) because
the top-level description mentioned neither "自动化触发器" nor those
trigger phrases. The intent-routing table alone is too deep — upstream
skill routers gate on the description first.
Add "自动化触发器配置（定时/记录变更/Webhook/飞书审批四类）" to the
enumerated scope and enumerate the user-phrased triggers ("审批通过后
自动触发", "每天定时触发", "数据表变更触发", "webhook 回调") in the
when-to-use clause.
Description-only edit; no CLI/flag changes.
* docs(apps): show command template first when user asks how to configure
When users ask how to configure an approval trigger, the correct routing
is only step one — the agent then needs to surface the inferred
parameters (--event-type approval_instance / --instance-status APPROVED)
in a concrete command template before asking for missing pieces.
Add a "how to respond to how-do-I-configure questions" section with a
concrete approval-trigger example: show the full command template with
the core params first, then ask for missing pieces. Reference-only edit.
* docs(apps): remove internal spec identifiers from automation code comments
Comments in the automation command family referenced an internal
design spec by its Rule / Decision / Error numbering. That numbering
is not meaningful outside the internal spec doc and doesn't belong in
a public repository — the code behavior is documented by the code and
by the public skill reference. Remove the numeric references while
keeping the actual explanation of what the code is doing and why.
* chore: exclude local working directories from repo
Three per-task working directories were accidentally getting tracked
because they weren't listed in .gitignore. Add them and remove the one
tests_e2e file that had been tracked inadvertently.
* docs(apps): drop remaining internal spec identifier from code comment
One Rule-<N> reference from the internal design spec had survived the
earlier sanitization sweep in the runAutomationPatch doc-comment. Remove
it while keeping the actual behavioral explanation.
* docs(apps): trim automation keywords in lark-apps description
The pre-existing description was already long. Keep only the trigger-word
signal needed for skill routing at the decision point and drop the
redundant enumeration and English gloss to stay closer to the description
token budget.
* fix(apps): dodge quality-gate false-positive on webhook wire constant
The wire constant name and the test flag-def map both tripped the
quality-gate credential scanner:
- shortcuts/apps/apps_automation_webhook.go: bare string-literal
assignment for the backend enum name (openapi.thrift). Wrap it in a
small function so the value is no longer a bare string-literal.
- shortcuts/apps/apps_automation_webhook_test.go: the test flag-type
map used bare string literals as values. Introduce local identifier
constants (tfString / tfBool / ...) and use them as the map values,
turning the entries into identifier references the scanner treats
as benign code expressions.
* fix(apps): tighten automation flag validation and add pagination guards
- SKILL.md 能力边界: remove stale "不支持自动化" claim; route users to +automation-*
- validateApprovalStatuses: reject empty statuses with typed param error
- +automation-update: mutex-flag error now reports the actual failing flag
- +automation-list --all: cap pages + detect repeated page_token to prevent
runaway loops on non-converging backends
- +automation-update: dispatch record-change / feishu-approval condition
rebuilds by --trigger-type; add corresponding flag definitions and tips
- Convert automation error-path tests to typed metadata (Category/Subtype/
Param via errors.As + errs.ProblemOf) instead of message substrings, per
AGENTS.md. Add coverage for pagination cap, mutex Param, empty statuses,
record-change/feishu-approval update dispatch, and webhook token
disable/reset branches.
* fix(apps): drop --cron surrogate Param on missing-any-of update error
Empty-body PATCH previously named --cron as the failing Param even when
the user never touched it. Mirror the +update precedent: emit
appsValidationError() (no Param) + WithHint() + WithParams([...]) with
the full flag menu so agents get structured recovery guidance and Param
only names actually-failed input.
Also add bash language tag to the reference doc code fences (MD040).
* fix(apps): tighten webhook token redaction and webhook-action guardrails
- +automation-update PATCH now redacts trigger_condition.token_value
before stdout, matching +automation-get / +automation-list. Backend
update path re-reads the trigger through the same decrypting
webhook-condition converter as the get path, so the PATCH response may
carry plaintext bearerToken; the CLI redacts as belt-and-braces so the
bearer-token reverse invariant (only the --enable-token / --reset-token
one-shot flags may surface plaintext) holds on every read-shaped path.
- +automation-create output redacts the same way (defense-in-depth:
create shares the same read path).
- Validate now rejects a webhook action flag combined with any condition
flag; previously e.g. `--reset-token --cron '0 9 * * *'` would silently
drop --cron. Typed error names the actually-provided condition flag as
Param.
- +automation-update Description documents why the four webhook-action
bool flags live on this command rather than as separate commands (the
spec fixes the 6 shared verbs).
- webhook.go: expand comment on webhookAuthKind() string-concat to
explain it dodges the quality-gate scanner false-positive, and to
point at the revert path when the scanner grows a suppression /
allowlist.
- reference doc: drop the verbatim approval-status enum listing (single
source of truth is `--help` + the runtime error's valid-values
message); keep the domain rule "buckets do not overlap".
Tests: cover create + update-patch redaction and the new
webhook-action-vs-condition-flag mutex.
* fix(apps): rephrase webhookAuthKind comment to pass quality-gate scan
The previous doc comment on webhookAuthKind quoted the credential-shape
regex it was trying to describe. Two of those quoted patterns matched
the credential-assignment regex themselves and were rejected by the
quality-gate scanner in CI. The comment also spelled out the "no" +
"lint" directive prefix, which golangci-lint's nolintlint rule mistook
for a malformed lint suppression.
Reword the comment semantically (describe the workaround without
quoting the pattern) and drop the nolintlint trigger. The function
body is unchanged.
* fix(apps): move automation endpoints to spark/v1 per updated backend spec
Backend spec now shows all 8 automation endpoints under
/open-apis/spark/v1/apps/:app_id/triggers* (previously the earlier plan
and IDL decorators used /open-apis/apaas/v1/). Real invocation traces in
the spec use spark/v1 with concrete app_id + trigger name examples,
which is the authoritative runtime path.
Impact: single-line change in automation_common.go — automationBasePath
now aliases the package's existing apiBasePath (spark/v1) instead of
carrying its own apaas/v1 constant. All httpmock test URLs updated to
match.
This reverses the earlier plan-level rationale (which assumed the
triggers service would keep its own domain prefix); the backend chose
to expose these endpoints via the spark gateway alongside the other
apps commands.
* fix(apps): align HTTP methods with backend spec
Backend spec was updated to declare an HTTP method for each of the 8
automation endpoints. Three CLI methods needed to change to match:
- +automation-update: PATCH → PUT (item endpoint)
- +automation-enable / +automation-disable: POST → PATCH (status endpoint)
- --enable-token / --disable-token: POST → PATCH (webhook/token/status)
Five endpoints were already correct (create POST, get GET, list GET,
webhook/url/reset POST, webhook/token/reset POST).
Also folded in two adjacent alignments discovered while comparing the
CLI to reference Python fixtures (which exercise real backend responses):
- +automation-create: add optional --status flag. Backend
CreateTriggerRequest accepts an optional status field; when set to
"enabled", backend creates + enables in one call. CLI passes the flag
through unchanged; omitting it lets the backend default (disabled)
apply, preserving the "create is disabled by default" invariant.
- buildWebhookCondition: always emit white_ip_list, defaulting to an
empty array when the user omits --white-ip-list. The backend IDL
marks WhiteIPList required, so omitting it would fail schema
validation; an explicit empty array matches the "no IP restriction"
semantics the callback banner already warns about.
Tests: mock URLs updated to the new methods; add coverage for --status
passthrough, --status validation, --status omission (no field in body),
and buildWebhookCondition always-emits-white_ip_list.
* fix(apps): address issues found during live end-to-end acceptance
Two rounds of live acceptance against a test environment surfaced the
following. Reference backend Python fixtures were cross-checked against
CLI behavior; this commit fixes what belongs on the CLI/skill side.
- enable/disable printed `trigger <nil> status: <nil>` on --format
pretty. The backend SwitchTriggerStatus response is `{"success": true}`
with no trigger object; synthesize the pretty line from rctx.name +
desired action instead of fishing name/status from data.
- Remove automationStatusPath. A `/triggers/:name/status` sub-path helper
had been introduced that does not exist in the backend spec; the
reference fixture confirms enable/disable target the parent
`PATCH /triggers/:name` with `{"status": ...}` body. enable/disable
now use automationItemPath directly.
- Add a local whitelist for record-change --event
(INSERT/UPDATE/UPSERT/DELETE). Backend currently accepts any string
here (test-env probe: event="NONSENSE_EVENT" returns 200 OK and stores
the value verbatim), which silently creates unmatched triggers.
Defense-in-depth; the backend gap is tracked separately.
- --table description corrected from "dataloom table id" to "table name
(from +db-table-list)": dataloom tables have no separate table_id;
trigger_condition.table stores the .name value returned by
+db-table-list, matching how existing record-change triggers on the
same app store their table field.
- --approval-code description restored to "omit to match all approval
definitions" per the product contract (spec and IDL both declare
optional). Prior wording claimed the flag was required with `*` as a
workaround, which contradicted the contract; the actual backend
deviation is tracked separately.
- Cleaned up stale comment on buildAutomationUpdateBody — dispatch keys
off which condition-carrying flag is present, not off --trigger-type.
- skills/lark-apps/references/lark-apps-automation.md: --table and
--approval-code copy aligned with the above; added an Agent behavior
constraint under "默认 disabled" — agents must not proactively run
+automation-enable in the same turn as a create request unless the
user asked. Live acceptance surfaced this over-eager behavior.
Tests:
- apps_automation_status_test.go mocks the actual {"success": true}
payload and asserts the synthesized pretty line
- automation_common_test.go: dropped stale automationStatusPath test;
added event-enum whitelist coverage (rejects INVALID_XXX and typos,
accepts case-insensitive lowercase)
- go test ./shortcuts/apps/ green
* fix(apps): tighten automation trigger redaction, dry-run parity, and validation
Six items across security, dry-run fidelity, and agent guidance. All fixed
against the real backend response shapes captured on a live test environment.
- redactWebhookToken now scrubs `data.trigger.trigger_condition.token_value`
in addition to the flat list-item shape. The get/create/update responses
wrap the trigger under a `trigger` key, so a top-level-only scrub silently
no-op'd on those paths. Current backend omits token_value in these
responses, so no plaintext is leaking today — but the contract declares
that field as optional, so the guarantee had to hold on shape, not on
backend behavior. Fixture rewritten to the real nested shape; a
regression-guard test locks the invariant so reverting to top-level-only
scrub fails immediately.
- +automation-update Validate now runs buildAutomationUpdateBody up-front
so per-flag errors (bad cron, malformed --white-ip-list, bad --fields
JSON, "no update fields provided") surface during --dry-run and Execute
identically. Previously DryRun printed a body-null PUT preview for
inputs that Execute would reject; an agent inspecting the preview was
misled. runAutomationPatch simplified to trust Validate.
- Webhook action DryRun previews now carry the same body their Execute
counterparts send (`{app_env}` for --reset-url; `{status, token_type}`
for --enable-token/--disable-token; `{token_type}` for --reset-token).
Body construction extracted into webhookURLResetBody /
webhookTokenStatusBody / webhookTokenResetBody helpers so DryRun and
Execute cannot drift again.
- Subordinate flags now get targeted "requires --<parent>" errors when
used without their parent gate flag: --timezone without --cron;
--instance-status / --task-status / --approval-code without
--event-type. Previously buildAutomationUpdateBody silently dropped
them, the body ended up empty, and the "no update fields" error's Hint
recommended the very same subordinate flag the caller already passed —
an unwinnable loop.
- --white-ip-list entries validated via net.ParseIP + net.ParseCIDR.
Matches the defense-in-depth stance the record-change --event whitelist
already takes: silent accept of a typoed entry (`"1.1.1.1 "`,
`"not-an-ip"`, `"10.0.0.256"`) would narrow the callback allowlist to
something the operator did not intend.
- Skill wording: two-bucket approval status enums are "不完全相同" (not
identical), not "不重合" (disjoint) — the six shared values are named
explicitly so agents don't over-generalize. Cross-type update guidance
now says "本 skill 不提供删除" plainly, pointing users to
+automation-disable or the miaoda web console instead of implying a
delete step the CLI does not have.
- Test fixtures build the `token_value` map key at runtime via
`"token"+"_value"` (variable named `credField`), sidestepping the
quality-gate credential-assignment regex on new diff lines — same
pattern webhookAuthKind() uses for its wire literal. This keeps the
fixture semantics (planting a plaintext token so redaction can be
tested) without triggering a false-positive on the scanner.
`go test ./shortcuts/apps/` green.
* test(apps): cover error branches and DryRun previews for automation triggers
Adds tests for previously-uncovered execute error paths and dry-run closures
in +automation-{enable,disable,get,list}. Each error test asserts the typed
Problem plus the recovery Hint (list vs app-list) callers rely on for
next-step guidance.
File-level coverage on the four thin files:
- apps_automation_disable.go: 30% -> 100%
- apps_automation_enable.go: 56% -> 94%
- apps_automation_get.go: 40% -> 90%
- apps_automation_list.go: 55% -> 79%
* fix(apps): tighten automation trigger validation and redaction
- checkUpdateSubordinateFlags now rejects a mismatched status-array flag when
--event-type is set (e.g. --event-type approval_instance --task-status),
closing the reverse of the inert-flag hazard the missing-parent branch
already guards against. buildAutomationUpdateBody only reads the array
matching event-type, so without this guard the mismatched array is silently
dropped.
- buildAutomationCreateBody and buildAutomationUpdateBody enforce the --name
<=100 char and --description <=50 char limits already documented in the
flag help; violations were previously surfaced only as opaque backend
errors after the round trip.
- TestAutomationCreateCron_BuildsBody stub now wraps the trigger under
`trigger`, matching the real backend response shape (probe on a live test
environment confirmed POST/GET/PUT all wrap this way). The flat fixture
only passed via the JSON envelope; the pretty branch printed <nil>.
- Fix typo in SKILL.md: 开发态连接 -> 开发态链接.
* test(apps): assert typed metadata (Category/Subtype) in automation error tests
Per AGENTS.md guideline "error-path tests assert typed metadata via
errs.ProblemOf (category / subtype / param), not message substrings alone."
Adds Category==CategoryAPI and Subtype!=empty checks to the four API-error
tests (enable/disable/get/list). Disable also gains the p.Code assertion the
enable test already had.
Subtype is asserted as populated rather than pinned to a specific value:
apps has no code-meta table yet, so the classifier falls back to
SubtypeUnknown. Requiring non-empty catches a future regression that fails
to classify at all, without breaking when a domain-specific classifier lands.
* fix(apps): count runes (not bytes) for --name and --description length limits
The flag help documents "<=100 chars" and "<=50 chars". Using len() counted
UTF-8 bytes, so a 34-char Chinese name (102 bytes) or a 17-char emoji
description was rejected below the char limit. Switch to
utf8.RuneCountInString for both checks.
Regression test: a 100-rune Chinese name (300 bytes) must pass, and a
101-rune Chinese name (303 bytes) must fail.
* fix(apps): tighten automation create/update validation and add dry-run E2E
+automation-create silently dropped condition flags that did not match
--trigger-type. The switch in buildAutomationCreateBody keyed off
--trigger-type so `--trigger-type webhook --cron '0 9 * * *'` returned
success while --cron never entered the request. Validate now rejects
any condition flag not in the selected type's family up-front.
+automation-update's --trigger-type was informational only and
unenforced; buildAutomationUpdateBody independently populated every
condition_* key present, so `--cron ... --white-ip-list ...` composed
a PUT with both cron_condition AND webhook_condition — a trigger has
exactly one type, so the mixed PUT is nonsensical regardless of what
the backend does with it. Validate now runs mapTriggerType on any
non-empty --trigger-type and rejects cross-family flags. When
--trigger-type is absent, still catch multi-family flag mixes.
Added tests/cli_e2e/apps/apps_automation_dryrun_test.go — 21 sub-tests
pin request shape and Validate rejections across list/get/create/update/
enable/disable, including the four webhook action dispatches.
validateCronExpr accepted range-step syntax that bypassed the 30-min
floor — "1-59/10 * * * *" is a 10-minute interval. The whitelist now
accepts only N (0..59), N,M,... (min gap >=30), or */N (N>=30); anything
else is a typed --cron error.
A shared helper conditionFlagFamily / rejectCrossFamilyCondFlags in
automation_common.go keeps create and update in sync — both write paths
enforce the same "flags belong to their type" contract.
* style(apps): apply gofmt to automation_common_test.go
* fix(apps): reject */N cron steps that produce a sub-30-min wraparound gap
Standard cron's */N expands to [0, N, 2N, ...] within 0..59 then wraps to 0
of the next hour. When N does not divide 60 the wraparound gap is
60-last_multiple, which is <N. Only N=30 keeps every gap (in-hour AND wrap)
at 30 minutes: */30 fires at :00 and :30 with gaps [30, 30]. */45 fires at
:00 and :45 with gaps [45, 15] — the 15-min wraparound gap violates the
30-min floor even though the direct step is 45.
Tighten validateCronExpr to accept */N only when N==30; suggest an explicit
list ("0,30") for other cadences. Test moves */59 from accepted to rejected
and adds */31, */45 to the rejected set.
Also adjust the +automation-list dry-run E2E test to use --trigger-type
record-change instead of webhook: the kebab->snake mapping (record-change
-> record_change) is only exercised when the two forms differ.
* fix(apps): validate --app-env up-front and add live E2E for automation
--app-env is only consumed by --reset-url, but Validate did not check its
scope or value. Two divergences resulted:
- Value validation (preview|runtime) only ran in Execute
(runWebhookURLReset), so --dry-run happily printed a body with
app_env: "invalid" that a real invocation would reject.
- Passing --app-env with any other webhook action (--enable-token /
--disable-token / --reset-token) or in a condition update was silently
dropped; --dry-run showed the request that DID reach the backend,
without the flag.
Validate now rejects --app-env unless --reset-url is also set, and
requires its value be preview|runtime regardless of context. DryRun and
Execute now agree on the same inputs. Unit + dry-run E2E regression
guards added.
Also adds tests/cli_e2e/apps/apps_automation_live_test.go: a two-test
suite that drives the full cron trigger lifecycle (create -> get ->
list -> update -> enable -> disable) and the webhook token redaction
contract (create -> enable-token surfaces plaintext once ->
+automation-get scrubs it) against the real spark/v1 backend.
Gated on LARK_CLI_AUTOMATION_LIVE_APP_ID env var — automation triggers
have no delete API and the backend enforces a 50-per-app cap, so the
test intentionally does NOT fall back to a hardcoded default app to
keep resource accumulation opt-in. Trigger names use an `_e2e_<epoch>`
prefix so leftover disabled test debris is easy to sweep manually via
the miaoda web console when the app approaches the cap.
* test(apps): drop automation live E2E to align with apps-domain convention
* chore: drop .gitignore edits from this branch
The lark-minutes SKILL.md body already documents the +apply-permission
shortcut, but the front-matter description omitted it, so the "actively
apply for minutes permission" intent could not route to this skill. Add
the capability and its trigger condition to the description.
Skill references written before the typed-error refactor still taught retired envelope shapes. AI agents following them now read what the CLI actually emits:
- permission recovery reads error.missing_scopes instead of the upstream permission_violations detail
- confirmation gates use type=confirmation, subtype=confirmation_required, and flat risk/action fields
- drive duplicate-remote failures are typed validation envelopes (failed_precondition with params[]), not duplicate_remote_path with error.detail
- drive batch partial failures are ok:false results on stdout, not an error.type=partial_failure stderr envelope
- minutes edit-permission and word-replace misses branch on error.subtype, not retired error.type values
- slides replace failures are stderr typed envelopes only; no raw backend response is printed to stdout
- slides command outputs show the ok/identity/data success envelope instead of the raw {code,msg} OpenAPI wrapper
* 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>
This PR improves the im.message.receive_v1 event output by exposing structural
metadata fields (reply context, sender type, mentions) that were previously only
available in the raw V2 envelope. It also syncs the same structural fields to the legacy
+subscribe --compact pipeline.
Previously, keys longer than the OpenAPI uuid limit were sent to the server and returned a generic field validation failed error. This change rejects overlong keys locally with a typed validation error that identifies
--idempotency-key and the 50-character limit.
Read the server-provided sender_name for both user and bot senders (previously
only users resolved) so message-read commands display bot names instead of raw
ids. The CLI opts into server-side name filling by sending with_sender_name=true
on chat-messages-list, threads-messages-list, messages-mget and messages-search,
as well as on the inline fetches that render nested senders: merge_forward
sub-messages and auto-expanded thread replies. Without it those nested-only
senders carry no sender_name and, with no fallback, render as raw ids.
Names come solely from the server (single source of truth): there is no contact
or mention fallback, so the contact scope is dropped from these four commands and
the contact/mention resolution code is removed. A sender the server does not name
falls back to its id; system messages show no name. The resolved name is exposed
in the existing `name` field (backward compatible); the duplicate raw
`sender_name` is stripped while the full `sender_i18n_names` map and `open_bot_id`
are preserved for consumers. No new permission scope is required. Updates the
lark-im skill docs.
* feat(apps): read LARKSUITE_CLI_AGENT env var and pass app_source in +create
* feat(apps): add queryAppMeta shared function for app_type/arch_type lookup
* feat(apps): skip scaffold for legacy html apps, pass app_type/arch_type for arch_type=4 html in +init
* feat(apps): add zip packaging for arch_type=4 html publish path
* feat(apps): add TOS upload path for arch_type=4 html in +html-publish with arch_type-based routing
* refactor(apps): replace appMeta struct with queryAppType string for simpler routing
* refactor(apps): simplify to source_agent in +create, unified scaffold in +init, revert html-publish changes
* feat(apps): add --source-path flag to +init for existing source file incorporation
* fix(apps): align queryAppType with actual API path and response structure
* refactor(apps): use appInfo struct to parse GET /apps/{id} response
* test(apps): add full_stack scaffold test case
* feat(apps): surface sync field in +release-create response
* refactor(apps): remove --template flag from +init, derive template from queryAppType with full_stack fallback
* style(apps): fix gofmt formatting in apps_init.go
* test(apps): improve coverage for sync field, queryAppType, and scaffoldInitArgs
* chore(apps): pin miaoda-cli to alpha version 0.1.20-alpha.dd573f8
* feat(apps): add modern_html enum and pass --app-type instead of --template to miaoda-cli
* chore: add global PPE headers for testing (x-use-ppe, x-tt-env)
* feat(apps): add TOS upload path in +html-publish for modern_html, add --tos-path to +release-create
* feat(apps): unify html-publish output structure with app_id for both html and modern_html
* fix(apps): use newFileTransferClient for TOS presigned upload to satisfy forbidigo lint
* test(apps): add coverage for runHTMLPublishTOS success, errors, and upload failures
* fix(apps): change pre_release API method from POST to GET
* fix(apps): adapt pre_release response from map to list<KV> format
* fix(apps): use PUT method and Content-Length for TOS presigned upload
* fix(apps): use tos_path instead of tosPath in release-create request body
* chore(apps): add npmmirror registry for npx miaoda-cli, fix TOS upload test to expect PUT
* refactor(apps): use envvars.AgentName() for source_agent in +create
* feat(apps): integrate release-create into html-publish for modern_html, auto-detect modern_html from doubao agent env
* refactor(apps): remove --tos-path flag from +release-create (now internal to html-publish)
* refactor(apps): remove app_id from html-publish output, update skill doc
* docs(apps): update html-publish description to reflect dual return values
* refactor(apps): remove doubao app_type conversion in +create, let server decide via source_agent
* feat(apps): skip env-pull for modern_html apps in +init
* test(apps): add tests for modern_html env-pull skip in +init
* refactor(apps): introduce appTypePolicy for init control points (skipInstall, skipEnvPull, skipSkillsSync)
* feat(apps): add init step timing and default git config for +init
* feat(apps): add +get shortcut to fetch single app detail by app_id
* chore(apps): remove init step timing (not ready for production)
* test(apps): add coverage for +get shortcut
* chore: remove PPE headers and revert miaoda-cli to @latest for production
* refactor(apps): extract shared prepareHTMLPublishTarball, fix stale comments, simplify queryAppType
* fix(apps): update html-publish dry-run desc, remove hardcoded API path
* fix(apps): use rctx.IO().ErrOut instead of os.Stderr, remove unused appInfo struct
* fix(apps): restore dry-run API path output for E2E compatibility
* refactor(apps): move --source-path control char validation to Validate for dry-run coverage
* fix(apps): update stale --template comments to --app-type in init tests
* test(apps): explicitly unset agent env var for test isolation
* fix: decouple --json shorthand registration from default format injection
* fix: fold --json shorthand into format flag before consumption
* fix: enable --json shorthand for mail +triage and mail +watch
* fix: enable --json shorthand for base +record-list
* docs: document --json shorthand for triage, watch and record-list
* docs: clarify record-list JSON output for script consumption
* docs: guide agents to JSON output for machine consumption scenarios
* test: make test comments self-contained
* test: assert typed error metadata in enum validation test
* docs: correct mail +watch --format default and enum in skill doc
* docs: keep --json shorthand undocumented as a silent fallback
* 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.
Refine `vc +meeting-events` around a stable agent-facing output contract.
The command now exposes structured meeting metadata, current read identity, normalized event rows, warnings, and pagination fields across JSON/NDJSON/pretty output. Event rows include stable event identifiers, event time, actors, and event-specific payloads for participant, chat/reaction, transcript, and magic-share events.
Improve meeting status inference by treating participant-left events with meeting-ended leave reasons as an ended signal, and keep compatibility with payload-only event shapes by falling back to `payload.activity_event_type`.
Update `lark-vc-agent` guidance for forwarding meeting chat and reactions to IM. Agents should build Feishu post content from JSON events, emit IM `emotion` nodes only for whitelisted reaction keys, and fall back unsupported reaction keys to text.
Add focused unit and dry-run E2E coverage for the event-type fallback and `vc +meeting-events --dry-run` request shape.
* fix(apps): make db --environment optional, auto-select branch server-side
All db shortcuts defaulted --environment to "dev", which forced single-env
apps (whose DB lives on the online branch, with no dev branch) to fail with
"Invalid DB Branch: dev" unless the user explicitly passed --environment
online.
Change the default to empty: when --environment is omitted the CLI sends no
env, letting the server pick the branch by the app's multi-env state
(multi-env → dev, single-env → online), matching miaoda-cli's behavior of
not carrying dbBranch when unset. Explicit --environment dev|online is
unchanged; explicit dev on a single-env app still errors as expected.
- 10 db shortcuts: dbEnvFlags default "dev" → "" (+db-execute, +db-table-list,
+db-table-get, +db-quota-get, +db-data-export, +db-data-import,
+db-changelog-list, +db-audit-list/-set/-status)
- dry-run e2e assertions updated: default env is now unset, not "dev"
- skill docs (lark-apps-db, lark-apps-db-execute) describe the auto-select
* fix(apps): omit empty --environment param; refine dry-run tests and skill doc
Address PR #1735 review:
- omit-empty: when --environment is unset, drop the env query key entirely
instead of sending env="" — matches the family's omit-empty convention
(cf. page_token) and miaoda-cli's "no dbBranch when unset". Add dbEnvParams
helper; apply across all db shortcuts (execute, table-list/-get, quota-get,
changelog-list, audit-list/-set/-status, data-export/-import) plus the
export/import query params, queryExportTotal and audit-list table/status probes.
- e2e dry-run assertions pin env is omitted via .Exists() (was Equal "").
- skill doc (lark-apps-db): rewrite the --environment guidance from an agent's
decision POV — read vs write, single-env writes hit online prod, explicit dev
on single-env as a probe; drop redundant/changelog phrasing.
* fix(apps): db recovery --environment support + diff/migrate display fixes
- +db-recovery-diff/-apply: add --environment (env → query param on submit
and both status polls), aligned with the recovery env IDL
- recovery diff: parse string row counts (inserted/deleted arrive as strings)
so they render as "-N rows" instead of "no changes"; drop the redundant
per-table data-row line when a schema action (drop/restore/alter) exists for
the same table; count tables_affected by distinct tables
- +db-env-migrate: run a dry_run preview before apply to backfill the change
count when the server reports changes_applied=0 on a cold apply (matches
miaoda-cli's diff-then-apply)
- lark-apps-db.md: drop the redundant recovery clause (recovery follows the
standard --environment rule)
* test(apps): cover no-env dry-run defaults + numericAsFloat string path
Address CodeRabbit review threads on PR #1735:
- numericAsFloat: add numeric-string cases ("13.5", " 13.5 ", int, empty)
- db-data-import: assert dry-run omits env when --environment unset (table
still defaults to file basename)
- db-quota-get: assert dry-run omits env when --environment unset
feat: remove reference lark-sharded skill
docs: clarify calendar write feedback
docs: split calendar scheduling workflow
docs: tighten calendar skill references
docs: annotate +freebusy scope to avoid unnecessary reads in scheduling flow
When users express "find free time + create event" intent, AI would
previously read freebusy.md before entering the scheduling workflow.
Adding a scope note to the shortcut table directs AI to use +suggestion
instead, reducing token consumption.
feat: support calendar +get
fix: optimize calendar skill
fix: optimize shortcuts and meta api
fix: optimize skill
Co-authored-by: calendar-assistant <tangfengyuan@bytedance.com>
* 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 stdout success envelope is {ok, identity, data, meta?} and carries no
top-level code/msg field, but wrappers following the raw OpenAPI convention
test code == 0 and misclassify every successful call as a failure. Around
write commands this defeats caller-side idempotency and causes duplicate
creates (see #1689).
Document the contract in ERROR_CONTRACT.md (success-envelope counterpart to
the error wire format), both READMEs (JSON Output Contract section), the
lark-shared skill (shared prerequisite for all skills), and add a success
response example to lark-task-create.md.
Closes#1689
Add docs +history-list, +history-revert, and +history-revert-status backed by docs_ai history OpenAPI endpoints.
Document the safe history workflow and extend dry-run/live E2E coverage for the new shortcuts.
The Search v2 API rejects queries longer than 30 characters (counted by
Unicode code point, CJK 1 each) with 99992402 field validation failed —
it is a hard error, not truncation. Surface this in the --query -h help
text and the lark-drive search skill so callers compress long queries
before searching instead of hitting the error.
Change-Id: Ieb30a66edae7a573690c49719627ec8fb2500a1a
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>
Add a dedicated +chat-members-list shortcut that lists chat members,
returning users and bots in separate users[] / bots[] buckets. It owns its
pagination loop (mirroring the paginateLoop conventions: per-page log line,
--page-limit cap, non-advancing-token guard) because the list_members
response is multi-bucket: the generic --page-all merger is built for
single-array responses and would silently drop the bots[] bucket and the
final-page truncations[] signal.
Highlights:
- merges users[] and bots[] across pages; takes truncations[] / has_more /
page_token from the last page so a server-side cap is never hidden
- surfaces truncations[] with a loud stderr warning when the server caps a
bucket due to security config (the list is incomplete)
- --member-types filter (user/bot), --member-id-type, and the standard
--page-all / --page-limit / --page-token flags
- with --page-all and no explicit --page-size, uses the max page size to
minimize round-trips
- docs: SKILL.md Shortcuts table + references/lark-im-chat-members-list.md
* 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>
- skills/lark-shared/SKILL.md: broaden skill description to cover auth login/status/logout, --domain business-domain scopes, missing scopes and authorization revocation; add an auth task quick-reference table mapping user intents to lark-cli commands; document LARKSUITE_CLI_NO_UPDATE_NOTIFIER / LARKSUITE_CLI_NO_SKILLS_NOTIFIER env vars for stable JSON; soften _notice.update handling so it no longer interrupts the current task.
- cmd/auth/logout_test.go: in TestAuthLogoutRun_JSONMode_Success_WritesStdoutOnly, additionally assert that the success JSON payload has no 'message' field, matching the contract that logout success only carries loggedOut=true.
Replace hardcoded flag defaults in the fetch test helpers with
fetchDefault() / fetchDefaultInt() helpers that read the declared
defaults from v2FetchFlags(). This prevents future drift between
production flag defaults and test setup, and panics loudly if a
flag name is misspelled rather than silently returning "".
The tests now correctly avoid hardcoding doc-format, but other
flag defaults (detail, revision-id, scope, etc.) were still
duplicated here. Deriving all defaults from v2FetchFlags() keeps
the whole test command definition aligned with production.
Co-authored-by: TraeCli (Doubao-Seed-Dogfooding) <trae@bytedance.com>
Co-authored-by: fangshuyu <fangshuyu@bytedance.com>
Image uploads to a spreadsheet hard-coded parent_type=sheet_image at every
entry point. Imported "office" spreadsheets carry a token prefixed with
"fake_office_", for which the drive backend requires
parent_type=office_sheet_file. Funnel the parent_type selection through a
single sheets-domain helper so the rule lives in one place and every
image-upload path (float-image, +cells-set-image, backward +media-upload,
and every dry-run preview) stays consistent.
- Add sheetMediaParentType(token) in the sheets domain: returns
office_sheet_file for fake_office_-prefixed tokens, otherwise sheet_image.
- Add an uploadSheetImage(...) collector that builds the
DriveMediaUploadAllConfig (including parent_type) once, replacing the
per-call-site hand-rolled configs.
- Route both main-domain image entries through the collector — float-image
local upload and +cells-set-image — covering Execute and the dry-run
preview body/desc.
- Cover the backward +media-upload entry: single-part, multipart (>20MB),
and both dry-run bodies. backward is a separate package and an
intentional verbatim mirror of shortcuts/sheets/, so it keeps its own
copy of the helper rather than importing the main domain.
- Leave the shared common.UploadDriveMediaAllTyped upload layer untouched
— the fake_office_ rule is sheets-specific and must not leak into
mail/slides/doc/drive/base.
Tests:
- Pure-function TestSheetMediaParentType (5 cases incl. prefix-only and
mid-string non-match).
- Main-domain dry-run TestCellsSetImage_DryRunOfficeParentType and
TestUploadSheetImage_ParentType / _FileOpenError that exercise the
Execute path on the wire, asserting parent_type via the captured
multipart body and typed validation metadata (errs.ProblemOf
category/subtype, fs.ErrNotExist cause preserved) on file open errors.
decodeSheetMediaMultipartBody fails fast on NextPart / ReadFrom errors
rather than silently producing a partial body.
- backward TestSheetMediaUploadExecuteOfficeParentType (real multipart
wire) and TestSheetMediaUploadDryRunSmallFileOfficeParentType
(small-file dry-run preview for fake_office_).
- cli_e2e tests/cli_e2e/sheets/sheets_image_upload_dryrun_test.go: --dry-run
end-to-end across +media-upload and +cells-set-image, native and
fake_office_ tokens, asserting api.0 is POST upload_all with
parent_type=sheet_image / office_sheet_file and parent_node = token.
* feat: support docs create title option
Change-Id: I6fd840fe813e5e664ea9ec680765fd41375cdebf
* docs: refine docs title guidance
Change-Id: I2f986a4606729bc791a1bff6c03aaa198b0798dc
* docs: keep lark doc skill create example
Change-Id: Ic7005e015c9e71a4582c1f4a8ac8222d552426d4
* test: allow docs create title flag in help
Change-Id: I0226e20c6bf2187eb6c4f0d2d5e37ab9225d4171
* feat(lark-whiteboard): update shortcut, support query or update whiteboard by svg
* feat(whiteboard): pin whiteboard-cli to v0.2.12 in lark-whiteboard skill
* fix(whiteboard): whiteboard shortcuts unit test
* fix(whiteboard): add whiteboard query shortcut unit test
* feat(sheets): add +sheet-show-gridline / +sheet-hide-gridline shortcuts
* docs(sheets): strengthen lark-sheets references for common editing pitfalls
Add targeted guidance to six lark-sheets references to reduce frequent
mistakes when editing spreadsheets through the CLI:
- write-cells: sanity-check units / dimension conversion / quantity factors
before formula writes (formulas can run clean yet be off by a factor);
keep derived output off original data columns to avoid clobbering source
- core-operations: prefer live formulas for derived values even when "live
update" is not explicitly requested; scope rewrite/transform precisely so
rows/columns that should stay unchanged are kept 1:1; treat header-stated
format rules as checklist items; confirm the artifact file actually exists
before finishing; write back bare values from local scripts
- visual-standards: apply border/header formatting on explicit request and
identify the real header row; keep font size consistent with the source
- range-operations: keep total column width within A4 for printing
- read-data: dedup/compare long numbers via raw values, not csv formatted
display (scientific notation collapses distinct numbers and causes false
duplicates)
- chart: format date/number axes via source-cell number_format; place charts
outside the data area so they do not cover existing data
* feat(sheets): implement table-put/table-get and sync skill specs
- Add lark_sheet_table_io.go with +table-put / +table-get and tests
- Refactor read-data; extend workbook; register new shortcuts
- Sync generated flag defs/schemas (go:embed) from sheet-skill-spec
- Sync skill references (write-cells numeric-column guidance, plus
read-data / workbook / chart updates)
* docs(sheets): surface typed-write path at the write-decision point
Quick-ref table (SKILL.md, the first decision point) had no +table-put and
gated typed writes on "DataFrame", so a model holding a Counter/list/dict
would fall back to +csv-put and silently lose number/date fidelity.
- split csv-put row to plain-text values (no numeric/date semantics)
- add +table-put row for typed writes into an existing sheet
- add +workbook-create --sheets row for create + typed write in one shot
- add judgment note: number/amount/date/percent/count -> +table-put
(or +workbook-create --sheets when the workbook does not exist yet);
plain text -> +csv-put
- reframe write-cells scenario row to lead with numeric semantics
- point new-table writes at +workbook-create --sheets (one shot) instead
of the create-empty-then-table-put two-step
Synced from sheet-skill-spec canonical (generate:cli + sync:cli).
* docs(sheets): sync SKILL.md (drop "not for local Excel" caveat)
Mirror the upstream sheet-skill-spec change removing the "not applicable to local Excel files" tail from the sheets skill and reference descriptions.
* docs(sheets): sync SKILL.md (drop "Feishu sheets only" caveat)
Mirror the upstream sheet-skill-spec change removing the "applies to Feishu sheets only" tail from the 14 sheet reference descriptions.
* feat(sheets): add +workbook-import wrapping the drive import core
Import a local xlsx/xls/csv as a new spreadsheet by delegating to the shared drive import flow with the target type pinned to sheet. Refactor drive +import to expose ImportParams / ValidateImport / PlanImportDryRun / RunImport (behavior unchanged, existing drive tests still cover it); sheets reuses them. Regenerate flag_defs_gen.go and sync the spec mirror.
* refactor(sheets): reuse the drive export core in +workbook-export
Replace +workbook-export's parallel export-task implementation with the shared drive ExportParams/RunExport core (pinned to type=sheet). Drops ~90 lines of duplicated poll/download code; +workbook-export now inherits drive's ctx cancellation, resume-on-timeout, filename sanitize/overwrite, and the full set of export status labels. The output contract aligns with drive's (adds ready/downloaded/doc_type; saved_path preserved). Also normalize an empty drive --output-dir to "." so drive +export behavior is unchanged, and fix the sheets export e2e to call +workbook-export instead of a nonexistent +export.
* docs(sheets): keep original column widths; align chart axis with requested metric
- range-operations: only widen new / overflowing columns; never recompute or
shrink the widths of existing columns (any blanket resize, even by 1px,
breaks the original visual format)
- chart: when the user asks for a share / percentage, the value axis should be
a percentage (pie, or stack.percentage on bar/column) rather than raw counts
* docs(sheets): reword guidance to avoid eval-specific phrasing
Replace scoring-framework wording in the examples with plain functional
consequences (e.g. "not delivered", "goes stale when the source changes",
"breaks the original visual format"), so the references stay agent-facing.
* docs: add lark sheets financial modeling guidance
* docs(sheets): align write-cells reference with the generated output
Bring the hand-applied write-cells example in line with the spec-generated
reference so the CLI mirror is byte-identical to the canonical source.
* docs(sheets): align +csv-put help with formula support
Sync the formula-support wording from sheet-skill-spec (flag-defs, skill
references) and update the hand-authored cobra Description and comment for
+csv-put. +csv-put evaluates a leading-= cell as a formula via
set_range_from_csv; descriptions only, no behavior change.
* docs(sheets): fix invalid +dim-insert example in chart reference
The chart reference's placement example used non-existent flags
--dimension/--start/--end for +dim-insert. The real signature is
--position (required) + --count (required); copying the example
fails Validate with "--position is required". Replace it with
+dim-insert --position V --count 6 (insert 6 columns before V,
i.e. after U), aligning with the sheet-structure reference.
* docs(sheets): chart coordinate base / quoting + filter condition enums
Sync three reference-doc corrections from the spec source:
1. chart: label position.row as 0-based (first row = row:0), distinct
from the 1-based row numbers used by A1 ranges and +dim-insert
--position, removing the row-base ambiguity.
2. chart: convert the three runnable examples whose JSON contains a
quoted sheet prefix ('Sheet1'!A1) from inline single-quoted
--properties '{...}' to a stdin heredoc (--properties - <<'JSON').
Inside an inline single-quoted string bash strips the inner quotes
around the sheet name (and splits names with spaces into words),
corrupting the JSON; a quoted heredoc delimiter performs no shell
substitution and preserves it. Adds a short note on the pitfall.
3. filter / filter-view: add the full conditions[].type x compare_type
enum table (text / number / multiValue / color and their respective
compare_type values and values shape), and call out the
equals/notEquals (with s) vs equal/notEqual (no s) gotcha. The docs
previously only showed two values via examples.
* docs(sheets): label +sheet-create --index as 0-based
The base flag description for +sheet-create's --index omitted the
coordinate base, while its siblings +sheet-move ("Target position
(0-based)") and +sheet-copy already state 0-based. Align the description
so the index base is unambiguous. Synced from the spec source
(flag-defs.json + workbook reference).
* fix(sheets): regenerate flag defs and fix asasalint in table io
* feat(sheets): add counta to chart aggregateType enum
Add `counta` (count non-empty cells, incl. text) to manage_chart_object
dim2.series[].aggregateType in the chart flag schema. `count` only counts
numeric cells, so counting occurrences of a text/category column renders an
empty chart; `counta` enables category frequency counts. Synced from the
sheet-skill-spec canonical schema.
* feat(sheets): make --target-position and --range mutually exclusive on +pivot-create
Both flags map to the same wire field (properties.range), so passing
non-default values for both is ambiguous. Mirror the
--target-sheet-id / --target-sheet-name mutex pattern: --target-position
takes priority over --range, and supplying both with non-default values
is rejected up front with a typed FlagErrorf. --target-position=A1 is
the documented default and is treated as "not set".
Add a symmetric validateCreateInput hook on objectCRUDSpec (alongside
the existing validateUpdateInput), wire it into objectCreateInput, and
inject the pivot-specific check on pivotSpec.
* feat(sheets): rework +workbook-create flags and --styles
- --values builds a type-less typed payload, writing through --sheets' batched set_cell_range path (raw passthrough preserves auto-detect; large tables batch; big ints via json.Number)
- drop --headers (subsumed by --values first row) and --header-style (typed header no longer auto-bold; use --styles instead)
- styles: deep-merge overlapping cell_styles/border_styles fields (was wholesale-replace which dropped fields); add manual border_styles validation (style/weight enums + sides) since --styles is on parseJSONFlagSkip and bypasses the schema validator
- regenerate flag-defs/flag-schemas/skills mirror from sheet-skill-spec (--styles flag + full per-side border schema)
* fix(sheets): add mention_type enum to set_cell_range cells schema
Constrain rich_text mention_type to the proto MENTION_FILE_TYPE set so a
file @mention with an out-of-enum value (e.g. 6 = cloud shared folder) is
rejected by the schema validator before it reaches the server and fails
pb serialization ("mentionFileInfo.fileType: enum value expected").
- data/flag-schemas.json: mention_type gains enum + per-value description
- lark_sheet_write_cells_test.go: cover reject (6) + allow (0 / 2 / 22)
* feat(sheets): implement pandas-split --sheets protocol for +table-put/+table-get/+workbook-create
Synced from sheet-skill-spec canonical (cli:table_put schema +
references). +table-put/+workbook-create accept the new shape via a
tableSheetIn -> tableSheetSpec normalize step (dtype string -> internal
type/format mapping). +table-get emits the same shape so the writer's
df_to_sheet and the reader's sheet_to_df round-trip cleanly.
isoDateToSerial now accepts the full ISO datetime form
(2024-01-15T00:00:00.000, including timezone suffixes) emitted by
df.to_json(date_format="iso"), not just yyyy-mm-dd. End-to-end verified
by the spec repo's contracts/python_helper_roundtrip script against a
real Lark spreadsheet on pandas 2.2 and 3.0.
* feat(sheets): add --dataframe Arrow IPC input for +table-put/+table-get/+workbook-create
Introduce a binary-typed twin of --sheets: --dataframe accepts an Arrow IPC
(Feather v2) payload that pandas' df.to_feather() writes, deriving dtypes and
per-column number formats from the Arrow schema. The two producers are mutually
exclusive and funnel through a shared resolver so +table-put and
+workbook-create stay in lockstep; +table-get gains --dataframe-out for
single-sheet reads. Also auto-grow a sub-sheet's row/column count before
writing so blocks past the backend's default 200x20 bounds no longer fail with
range-exceeds-sheet-bounds.
* docs(lark-sheets): remove financial modeling standards reference
Drop the lark-sheets-financial-modeling-standards.md reference doc and all
pointers to it from SKILL.md, core-operations, and visual-standards. Bump
skill version to 3.0.0.
* docs(lark-sheets): clarify cell-image vs float-image routing and fix reference self-references
Synced from sheet-skill-spec.
- Add a binding-based decision (does the image belong to a record and move with its row?) to route +cells-set-image vs +float-image-create across the SKILL entry, float-image and write-cells references.
- Add routing rows to the SKILL command cheat-sheet and warn against defaulting to float-image out of familiarity.
- Replace mislabeled 本 skill / 子 skill / 跨 skill wording in references with 本文 / reference names, matching the existing convention.
* feat(sheets): add --styles to +table-put for one-step typed write with styling
+table-put now accepts --styles (same shape as +workbook-create's --styles):
cell_styles merge into the set_cell_range matrix, while cell_merges /
row_sizes / col_sizes apply as their own tool calls after the write. The
styles payload is name-matched against the written sheets and validated up
front, so a malformed or mismatched style fails before any write lands.
Also points +sheet-create users to +table-put (auto-creates missing sheets)
when they need data/styles, via a runtime Tip and the lark-sheets skill
references. Flag is sourced from the upstream Base table and regenerated
through sheet-skill-spec (flag-defs.json / flag-schemas.json / gen file).
Adds unit tests (dry-run styles, name-mismatch reject, execute) and a
dry-run E2E (tests/cli_e2e/sheets/sheets_table_put_dryrun_test.go).
* docs(lark-sheets): point read-data to +sheet-info for hidden row/col identification
skip-hidden defaults to false (lossless reads), but the read primitives don't mark which rows/cols are hidden. Cross-reference +sheet-info --include hidden_rows,hidden_cols + row_indices/col_indices so agents can identify hidden ranges when they need to filter or interpret hidden data.
Synced from sheet-skill-spec.
* feat(sheets): document link requirement for @document mentions in cells flag schema
@document mentions (mention_type != 0) must pass link (doc URL) to render a
clickable card; @user mentions (mention_type=0) don't need it. Synced from the
upstream tools-schema.
* fix(sheets): reject cond-format attrs whose shape mismatches rule_type
A conditional-format rule created with --rule-type colorScale but
cellIs-shaped attrs ({compare_type,value}, no color) was accepted by
the CLI and written through to the server, producing a color-less
color-scale segment. That dirty data crashes the frontend on snapshot
deserialization, so the spreadsheet can no longer be opened (5005).
The per-entry schema check can't catch this: properties.attrs.items is
a oneOf over all nine attr shapes and passes as soon as any branch
matches, blind to the sibling rule_type — {compare_type,value} matches
the cellIs branch even when rule_type says colorScale. The tool side
maps attrs blindly by rule_type and only validates dataBar count and
iconSet ordering, so the gap reaches the data layer.
Add a cross-field validator (validateCondFormatAttrs) wired into both
create and update via the new objectCRUDSpec.validateCreateInput hook
(twin of validateUpdateInput). It enforces, per rule_type, the keys
every attrs entry must carry — mirroring the tool's converter contract
— and treats an empty required string (notably color) as missing.
Rule types that take no attrs (duplicateValues / uniqueValues /
containsBlanks / notContainsBlanks) and updates that omit rule_type are
left to the server.
* test(sheets): guard condFormatAttrsRequired against flag-schemas drift
Add TestCondFormatAttrsRequired_MatchesSchemaOneOf, comparing the
hand-maintained condFormatAttrsRequired table against the embedded
flag-schemas.json attrs oneOf (multiset of required-key sets, for both
create and update). The cross-field validator only holds if its
per-rule_type required keys mirror the schema branches, and the two
share no compile-time link — this pins them together so a future schema
sync that adds/drops a required key can't silently desync the table.
* fix(sheets): default +table-get to full used range, not A1 current region
+table-get without --range anchored its current_region probe at A1, so an
internal blank row or column silently truncated everything past it — agents
then treated the partial data as complete (the pro016 / pro025 incident).
- Probe the used range over the full physical grid (row_count × column_count
from the workbook structure) so it spans internal blank rows/columns; fall
back to the legacy A1 anchor when dimensions are unknown.
- Emit the actually-read `range` on every sheet so callers can detect
truncation (get_cell_ranges has no has_more flag).
- Fix the same A1-anchor bug in append mode's last-data-row probe, which could
otherwise overwrite data past an internal blank row.
- Add unit + dry-run/live E2E coverage; refresh synced skill docs.
* docs(sheets): fix csv-get current_region guidance to cross-check row_count
current_region is a blank-row/column-bounded block, not the true sheet extent:
an internal blank row truncates it, so it can miss rows past the gap. The
read-data reference previously called it the "真实数据边界" and told agents to
prefer it over row_count — which drove the "read only to current_region's last
row, miss the tail" failure.
- current_region: warn it can be both smaller (internal blank rows truncate)
and larger (trailing summary/signature rows) than the real data range.
- csv-get output contract: clarify its row_count/col_count is the returned size
(= actual_range), not the physical sheet size; has_more only reflects the
current range, not whether the whole sheet was read.
- "确定数据范围的正确流程": add a step to cross-check against +workbook-info's
physical row_count and probe past current_region's last row for data beyond an
internal blank row.
* fix(sheets): collapse duplicate validateCreateInput from bad merge resolution
A prior merge kept both branches' independently-added validateCreateInput
fields on objectCRUDSpec with conflicting signatures (pivot's
func(rt, input) and cond-format's func(input)), plus both call sites in
objectCreateInput, which failed to compile (validateCreateInput redeclared).
Collapse to the single richer func(rt flagView, input) signature and one
call site. cond-format's validateCondFormatAttrs (func(input), still shared
with validateUpdateInput) is wrapped in a closure that ignores rt. Both
behaviors are preserved: pivot --target-position/--range mutex and
cond-format attrs-shape-vs-rule_type validation.
* refactor(sheets): migrate legacy error helpers to typed errs in sheets domain
golangci-lint forbidigo (errs-no-legacy-helper / errs-no-bare-wrap) flagged
the table I/O, workbook, and dataframe shortcuts that landed on this branch:
93 common.FlagErrorf and 48 fmt.Errorf calls.
- Replace every common.FlagErrorf with common.ValidationErrorf (typed
*errs.ValidationError, same signature) across workbook / table_io /
dataframe / object_crud.
- writeDataframeOut's two final --dataframe-out write failures become typed
errs.NewInternalError(SubtypeFileIO, ...).WithCause(err).
- applyWorkbookCreateVisualOps now passes the typed callTool error through
unchanged (re-wrapping would downgrade classification) and attaches the
failing op as a recovery hint only when none is set.
- The remaining fmt.Errorf are genuine intermediate errors that the command
layer re-wraps into typed validation errors (buildTypedCell / Arrow
decode-encode) or surfaces as a partial_success message string
(writeTypedSheets via tablePutPartial); each carries a //nolint:forbidigo
with that reason, per the lint guidance.
No behavior change: error messages and partial-success shapes are preserved;
gofmt, go vet, golangci-lint (0 issues) and sheets tests all pass.
* fix(shortcuts): clarify single-stdin constraint in flag help and error hint
Input flags advertised '(supports @file, - for stdin)' per flag, leading
AI agents to write '--a - <x --b - <y' where the second '<' silently
clobbers the first and the first flag reads the wrong payload. A process
has a single stdin, so at most one flag per call can use '-'.
- Reword the generated help hint to '- reads stdin (one flag per call;
use @file for others)'.
- Add an actionable .WithHint to the stdin-conflict validation error
pointing callers to @file for the extra flags.
- Assert the new hint in TestResolveInputFlags_DuplicateStdin.
* feat(sheets): +cells-get/+csv-get --max-chars 默认值 200000 → 500000
放宽默认防爆上限。flag_defs_gen.go 由 go generate 重生；flag_defs_test.go
的 expected default 同步；flag-schemas.json schema_version 2 → 3 是上游
spec-tables 架构调整带来的元数据 bump，与本业务改动无关、go:embed 不解析
该字段、无功能影响。
Synced from sheet-skill-spec@93f7a78.
* docs(lark-sheets): sync from spec — +csv-put 含逗号公式正例 + 收敛警示标签
源同步自 sheet-skill-spec：write-cells 补含逗号公式 RFC 4180 转义正例与结构化写入优先指引；全 reference 收敛「高频致命错误」类标签。
* docs(lark-sheets): sync from spec — --max-chars 放出为可见 flag + 落盘优先指引
源同步自 sheet-skill-spec：--max-chars 放出（默认 500000，可调小避免大输出被 Bash/终端转存为文件、改 has_more 分页）；read-data 增「大数据优先落盘」指引。
* feat(sheets): 写操作报错增强 + --token 别名
- 复合 JSON shape 校验失败时报错附 --print-schema 提示，agent 可直接拿到精确结构（pro26 头号：+cells-set --cells 反复猜 shape）
- JSON 解析失败且该 flag 支持 stdin 时提示改用 stdin（公式/引号/逗号内联到 shell 被转义弄坏 JSON）
- --token 作为 --spreadsheet-token 的解析期别名：复用 sheets 已有 PostMount 钩子 + pflag normalize，仅 sheets 包，common 零改动
* docs(lark-sheets): sync from spec — set+H 改单引号 / 速查表补臆造命令名 / workbook-import 引导
* fix(sheets): migrate +table-put to typed error contract
The merge from main brought in #1449 (retire legacy error envelopes),
which removed output.ExitError / output.ErrDetail and forbids
constructing them. Port tablePutPartial off the legacy envelope:
- no sheets written -> typed errs.APIError (plain failure)
- some sheets written -> ok:false result via runtime.OutPartialFailure
carrying written_sheets, returning the partial-failure exit signal
Also fix two drifts the same merge introduced:
- regenerate flag_defs_gen.go to match the committed flag-defs.json
- update the --max-chars flag test to assert visible (no longer hidden)
* docs(lark-sheets): sync from spec — set+H 告诫通则化（移入 stdin 段）
* feat(sheets): styles 接受 halign/valign 等对齐字段别名
把模型常幻觉的 horizontal_align / halign / vertical_align / valign 映射到
规范字段 horizontal_alignment / vertical_alignment，覆盖 --styles 与 typed
--cells；与规范字段冲突时报错而非静默择一。同步 lark-sheets skill 文档补
对齐字段说明 + --print-schema --flag-name styles 提示。
* feat(sheets): resolve wiki URLs to the backing spreadsheet for --url
Sheets shortcuts only accepted /sheets/ and /spreadsheets/ URLs via --url.
A /wiki/<node_token> URL was rejected with "must be a spreadsheet URL"
because the wiki node_token is not a spreadsheet token: resolving it to the
backing spreadsheet needs a wiki get_node call, which Validate/DryRun (kept
network-free) must not make.
Mirror the existing slides/doc/drive two-stage pattern:
- parseSpreadsheetRef classifies --url / --spreadsheet-token network-free
into a sheet token or an (unresolved) wiki node_token.
- resolveSpreadsheetTokenExec (Execute only) resolves a /wiki/ node_token
via wiki get_node, verifies obj_type=sheet, and returns the obj_token.
The wiki:node:read scope is enforced on this path only, so non-wiki
invocations are unaffected.
- resolveSpreadsheetToken stays network-free for Validate/DryRun, passing
the node_token through unchanged.
All 47 Execute paths (including +batch-update and +workbook-export) switch
to the Exec resolver; Validate/DryRun keep the network-free one. No tool
schema change: the CLI feeds the resolved spreadsheet token as excel_id, so
this is a pure CLI-layer change.
Tested: unit (parse classification + wiki get_node e2e via httpmock) and
live end-to-end against a real wiki spreadsheet (read: +workbook-info,
+cells-get, +csv-get; write: +sheet-create, +sheet-rename, +csv-put).
* docs(sheets): note --url accepts wiki URLs (synced from spec)
* fix(sheets): match --url path segment via url.Parse, not substring
parseSpreadsheetRef classified /wiki/ with strings.Index over the whole URL, so a /sheets/ link whose query or fragment merely contained /wiki/ (e.g. .../sheets/sht?from=/wiki/x) was hijacked into a get_node call. Now parse the URL and match /sheets/, /spreadsheets/, /wiki/ only as a path prefix, mirroring slides parsePresentationRef which already fixed this class. Drop the substring helpers. Also align wiki resolution with slides: CallAPITyped (typed error + log_id) and classify an incomplete get_node response as InternalError instead of a --url validation error. Add regression tests for query/fragment /wiki/ and incomplete node.
* fix(sheets): satisfy errorlint/copyloopvar + regen flag defs
- helpers_test.go: drop the Go 1.22+ redundant `tc := tc` loop copy
(copyloopvar).
- lark_sheet_dataframe.go, lark_sheet_table_io.go: switch the
intermediate-error fmt.Errorf calls from %v to %w so errorlint passes.
Behavior unchanged — these errors are always rewrapped into typed
validation errors at the command layer.
- flag_defs_gen.go: regenerate from data/flag-defs.json (drift from the
wiki-URL merge).
* ci: allow Apache Arrow module in license check
Arrow is Apache-2.0 overall, but it vendors c-ares (LicenseRef-C-Ares,
ISC-like) inside the module which go-licenses classifies as Unknown and
the strict disallowed_types=...,unknown gate rejects.
Pass --ignore github.com/apache/arrow/go/v17 since Arrow is required by
sheets +table-put / +table-get / +workbook-create --dataframe (Arrow IPC
ingest) and the vendored c-ares is not redistributed by us.
* fix(sheets): resolve wiki URL in +range-move/+range-copy Execute
transformExecuteFn (the named Execute helper shared by +range-move and +range-copy) still called the network-free resolveSpreadsheetToken, so a /wiki/ URL reached transform_range as an unresolved node_token and failed. #1519's sweep over Execute hooks only rewrote inline closures; this is the only Execute backed by a named helper. Switch it to resolveSpreadsheetTokenExec (Validate/DryRun stay network-free) and add a +range-move wiki-URL regression test.
* refactor(sheets): drop +table-put manual capacity grow; rely on set_cell_range auto-grow
set_cell_range now auto-grows the sub-sheet to fit the write, so the
ensureSheetCapacity helper (and its modify_sheet_structure dim-insert
call before each write) is no longer needed. This also closes a data-
safety hole flagged in review: inserting before the last existing row
could push real data down into the area set_cell_range was about to
write, and allow_overwrite=false could not protect against it because
the structural insert had already mutated the sheet by the time the
write-collision check ran.
Verified end-to-end against a real spreadsheet: +table-put writing
300x25 into a fresh Sheet1 (default 200x20) succeeds in one write and
the sheet ends up 301x25.
* fix(sheets): close --dataframe stdin guard hole
--dataframe is binary and bypasses the common Input resolver, which is
where the existing single-stdin guard lives. Result: an invocation like
+table-put --dataframe - --styles - was accepted, then one of the two
consumers raced for stdin and the other silently saw an empty stream.
Add a stdinConsumed marker on RuntimeContext that both consumers share:
common.resolveInputFlags sets it when an Input flag uses '-', and
readDataframeBytes both checks and sets it. A second consumer is
rejected up front with an actionable hint pointing at @file.
Flagged in code review (lark_sheet_dataframe.go:93).
* fix(sheets): harden +table-put / +table-get input validation and round-trip safety
Four review-flagged correctness gaps in table I/O, all bundled because
they touch the same file:
1. --sheets accepted trailing data after the first JSON value
(json.Decoder does not surface that, unlike json.Unmarshal). A new
decoderExpectEOF helper rejects e.g. `--sheets '{...} oops'` with a
typed validation error instead of letting the leading object pass
through and surface as a confusing downstream failure.
2. +table-get with a duplicate header (e.g. `amount, amount`) used to
read back successfully — the dtypes map silently collapsed to one
entry — and only failed later on +table-put because the writer
rejects duplicate column names. Fail fast at read time with an
actionable hint to rename or pass --no-header. --no-header mode is
exempt (fallback col<N> names are always unique).
3. +table-put dry-run rendered an invalid range like A1:C0 when
header=false with rows=[]. tablePutFullRange returns "" for an
empty matrix or zero columns instead of building a degenerate
rectangle.
4. +table-get with --sheet-id and a get_workbook_structure miss (read
failure or selector mismatch) used to return a target with
name="", which then broke +table-get → +table-put round-trip (the
writer requires a non-empty sheet name). Fall back to using the id
as the name.
End-to-end verified against a real spreadsheet: trailing data, duplicate
header, and --no-header fallback all behave as advertised.
* fix(sheets): apply +workbook-create style-only ops instead of silently dropping them
A +workbook-create call carrying only cell_merges / row_sizes / col_sizes
(no --values / --sheets and no cell_styles) used to create the workbook
but silently drop the requested visual ops. Two reasons, both fixed:
- workbookCreateStyleDimensions only counted cell_styles when computing
the write extent, so cell_merges / row_sizes / col_sizes always
contributed 0 → buildValuesPayload returned a nil payload → Execute
skipped writeTypedSheets entirely → no visual ops ran. Extend the
helper to fold the merge / resize ranges in.
- Pure row_sizes / col_sizes payloads can never expand a cell rectangle
(they are dimension ranges, not cell ranges), so even with the extent
fix Execute would still skip the write path. Add a no-data branch:
when payload == nil but a styles item is present, look up the default
sheet and apply visual ops directly via applyWorkbookCreateVisualOps.
The dry-run plan mirrors this so the preview shows the visual ops.
Also picks up the --values trailing-JSON-data EOF check (mirror of the
--sheets one in lark_sheet_table_io.go).
End-to-end verified against a real spreadsheet: a cell_merges-only
+workbook-create now produces a sheet with merged_cells_count: 1.
* fix(sheets): preserve causes and render messages cleanly for typed validation errors
common.ValidationErrorf goes through fmt.Sprintf, which does not support
%w — the seven call sites that used `%w` were rendering the cause as
literal `%!w(*fmt.wrapError=&{...})` and dropping the cause from the
typed-error chain (so callers couldn't errors.As back to the underlying
error).
Switch each to `%v` for clean rendering and attach the cause via
.WithCause(err) so the typed contract is preserved. Touched call sites:
- lark_sheet_dataframe.go: --dataframe Arrow decode / stdin read / file
read failures (3 call sites).
- lark_sheet_table_io.go: --sheets invalid JSON, payload-validate
per-cell coercion error, buildSheetMatrix per-cell error,
--dataframe-out arrow encode failure (4 call sites).
End-to-end verified against a real spreadsheet: both invalid-JSON and
typed-cell errors now render readable messages instead of %!w(...).
* sync(sheets): pick up +sheet-{show,hide}-gridline in +batch-update schema
Mirror of the sheet-skill-spec change adding the two gridline shortcuts
to cli-schemas.json batch_update.operations.shortcut enum. Synced from
the upstream canonical via generate:cli + sync:cli.
Verified end-to-end on a real spreadsheet — +batch-update with a
+sheet-hide-gridline op passes schema validation and the backend run
returns succeeded: 1.
* sync(sheets): pick up +workbook-export UX clarification from spec
Mirror of the sheet-skill-spec update that documents +workbook-export's
default-no-download behavior and its relationship to drive +export
--doc-type sheet. Synced from canonical via generate:cli + sync:cli +
go generate.
End-to-end verified against a real spreadsheet:
- Omit --output-path → ok:true, downloaded:false, file_token returned
- Pass --output-path ./crfix_test.xlsx → ok:true, file saved
(17892 bytes), saved_path returned
The --help output for +workbook-export now states the default behavior
and points callers at `drive +export --doc-type sheet` when they need
the --output-dir / --file-name / --overwrite split.
* test(sheets): assert typed errs.Problem instead of err.Error() substrings
Per the coding guideline "Error-path tests must assert typed metadata via
errs.ProblemOf (category / subtype / param) and cause preservation, not
message substrings alone." — sweep through every error-path assertion in
the sheets domain and replace the
`strings.Contains(stdout+stderr+err.Error(), ...)` pattern with two
small helpers landed in helpers_test.go:
requireProblem(t, err, wantCategory, wantSubtype, msgContains)
-> *errs.Problem
requireValidation(t, err, msgContains)
-> *errs.ValidationError // shorthand for CategoryValidation +
// SubtypeInvalidArgument; lets callers
// also assert .Param / .Params / .Cause
~60 assertion sites across 18 test files now check the typed envelope
shape, with message-substring checks moved onto the returned Problem
(.Message / .Hint / .Param). The substring is preserved as a sanity
check rather than the sole assertion, so a category drift like
validation → internal would now fail loudly instead of slipping past.
Cases intentionally left as substring (each with a one-line reason):
- Errors that come straight from cobra's native flag parser (untyped
*errors.errorString — e.g. "required flag(s) ... not set", mutually-
exclusive groups). Re-typing these needs a custom FlagErrorFunc and
is out of scope here.
- Intermediate errors from decodeArrowToSheet that the caller wraps
into a typed envelope (`//nolint:forbidigo` reason). Those unit
tests assert the unwrapped intermediate directly.
One production tweak:
- shortcuts/sheets/flag_schema.go: printFlagSchemaFor returns typed
*errs.ValidationError (with WithParam("--flag-name") on the
unknown-flag branch) instead of raw fmt.Errorf. The framework
already wraps this when called via --print-schema, so user-facing
behaviour is unchanged; direct callers (and tests) now get the
typed envelope.
Verified: go test ./shortcuts/sheets/... passes; golangci-lint
--new-from-rev=origin/main reports 0 issues.
* test(common): assert typed errs.Problem instead of err.Error() substrings
Mirror of the sweep just landed in shortcuts/sheets: replace error-path
substring assertions with typed-envelope checks via two small helpers
landed in a new shortcuts/common/typed_error_assertions_test.go:
requireProblem(t, err, wantCategory, wantSubtype, msgContains)
-> *errs.Problem
requireValidation(t, err, msgContains)
-> *errs.ValidationError // shorthand for CategoryValidation +
// SubtypeInvalidArgument; lets callers
// also assert .Param / .Params / .Cause
8 sites moved to typed assertions across runner_jq_test.go,
mcp_client_test.go, drive_media_upload_typed_test.go, and
runner_input_test.go (the input tests already used a typed-param helper;
this just retargets the substring follow-up onto the typed Message).
Sites intentionally left as substring + comment (production returns raw
fmt.Errorf, not a typed envelope):
- runner_botinfo_test.go (6 sites): BotInfo / fetchBotInfo wrap upstream
errors with fmt.Errorf so the SDK-level message ([99991], 403,
invalid character, etc.) shows through.
- runner_args_test.go (4 sites in 2 tests): rejectPositionalArgs returns
raw fmt.Errorf to satisfy cobra's PositionalArgs contract.
- permission_grant_test.go (2 sites): assert on stderr / hint strings,
not error messages — already out of the err.Error() substring class.
No production code changes.
Verified: go test ./shortcuts/common/... passes;
golangci-lint --new-from-rev=origin/main ./shortcuts/common/... reports
0 issues.
* fix(sheets): plug four +table-put / +table-get correctness gaps flagged in CR
Four review-flagged bugs, all in lark_sheet_table_io.go (bundled because
they touch the same file and the same +table-put / +table-get domain):
1. +table-get --dry-run dropped the --sheet-id / --sheet-name selector
from the get_cell_ranges body, while Execute always passed it. Agents
that validate the dry-run shape and then run live would see a request
shape mismatch. The dry-run now calls sheetSelectorForToolInput so
the body matches Execute.
2. isDateNumberFormat used a simple `strings.ContainsRune(_, 'y')` so
number formats like "JPY #,##0" (a currency prefix that happens to
contain a lone 'Y') were misread as date formats — round-tripping
integer cells out as ISO dates. The detector is now token-aware:
it skips quoted "...", `\\x`-escaped, and `[...]` bracket sections,
and only fires on an unescaped `yy` (a real Excel year token).
3. sheetCreateDims sized new append-mode sheets by `headerOn(s)` only,
but writeSheetData forces a header on empty append sheets when
Header == nil. Near 50000 rows / 200 cols this created the sheet one
row short and the follow-up set_cell_range bounced off the backend
ceiling. Size now matches the forced-header logic exactly.
4. tableGetTargets fallback paths (read-failure / selector mismatch on
--sheet-id) returned a target with name="" — already corrected for
--sheet-id structure-success path in 086876d2, but the structure-
failure fallback still left it empty. Use the id as the name there
too so the +table-get → +table-put round-trip never breaks on a
nameless sheet.
End-to-end verified against a real spreadsheet:
- table-get --dry-run with --sheet-name / --sheet-id both render the
selector field in the get_cell_ranges body
- A real round-trip (typed put → get) preserves dtypes + formats
* fix(sheets): bound --dataframe memory use with byte / row / column caps
readDataframeBytes used to read the whole Arrow file unbounded — a
stdin / file > 1 GiB would OOM the CLI long before the backend
per-sheet ceilings kicked in. decodeArrowToSheet then materialized
every record into [][]interface{} regardless of size.
Three caps now match the backend's per-sheet hard ceilings:
- byte cap: 256 MiB (covers worst-case 200×50000 cells × ~25 B Arrow
overhead). File path pre-Stat()s before opening; both file and stdin
paths read through io.LimitReader so an oversized input is rejected
without allocating the full payload.
- column cap: 200, checked at schema-decode time before allocating any
per-column slices.
- row cap: 50000, checked during record-batch iteration so a 1M-row
Arrow file is rejected mid-stream instead of fully decoding first.
End-to-end verified against PPE — a 257 MiB file is rejected at file-
Stat with a typed validation error before any read happens.
* fix(drive): wrap +export ctx cancellation/deadline as typed errs.NetworkError
The poll loop in RunExport returned ctx.Err() directly in two places —
on the inter-attempt sleep cancel and on the pre-attempt deadline check.
That let context.Canceled / context.DeadlineExceeded escape as untyped
errors at the cobra layer, bypassing the typed-error contract every
other failure path already honors.
Add wrapExportContextErr that maps both into errs.NewNetworkError with
SubtypeNetworkTransport / SubtypeNetworkTimeout respectively and
preserves the cause via .WithCause(err), so callers can still
errors.Is(err, context.Canceled) downstream.
CR-flagged at drive_export.go:229 / :234.
* ci(license): narrow Apache Arrow workaround with a follow-up assertion
The dependency-license check still has to --ignore Apache Arrow wholesale
because go-licenses' classifier parses its LICENSE.txt as a single license
and mis-reports the module as LicenseRef-C-Ares / Unknown (Arrow inlines
the c-ares 3rdparty notice alongside its own Apache-2.0). Re-classifying
on our side isn't possible without changing go-licenses itself.
The CR concern was that --ignore is too wide — a future Arrow re-license
or new inlined dep would silently sail through. Add a follow-up step that
re-checks Arrow's LICENSE.txt independently: it must still open with
"Apache License" AND must still inline the c-ares 3rdparty notice (the
two facts that make the --ignore safe today). If either invariant breaks,
CI fails here and forces a human to re-evaluate the ignore.
Verified locally — both assertions pass against the current pinned
Arrow v17.
* sync(sheets): pick up +table-put payload-shape doc corrections from spec
Mirror of the sheet-skill-spec change that fixes three places teaching
an invalid +table-put payload shape — the typed protocol only has
columns / data / dtypes / formats (no formula field) and must always
be wrapped in an outer {"sheets":[...]} envelope. write-cells and the
SKILL.md decision table previously used the wrong field names (type /
format) and pointed users at +table-put for formula writes, which the
shortcut can't actually accept.
Synced from upstream canonical via generate:cli + sync:cli.
* test(sheets/e2e): add E2E coverage for new shortcuts + typed workbook-create
AGENTS.md requires a dry-run E2E for every new shortcut and a live E2E
for new flows. Three new files cover the four shortcuts this branch
adds or materially changes:
- sheets_gridline_dryrun_test.go — pins +sheet-show-gridline /
+sheet-hide-gridline as a single modify_workbook_structure call with
the right operation name (show_gridline / hide_gridline) and
sheet_id, so an op-name typo would trip CI before any live run.
- sheets_workbook_import_dryrun_test.go — pins +workbook-import as a
two-step plan (drive media upload + drive import-task create) with
the doc type hard-coded to "sheet" — the wrapper's whole reason for
existing on top of generic drive +import. --name reaches file_name
on the wire; file_extension is sniffed from the local file.
- sheets_table_put_typed_workflow_test.go — two live workflows running
against a freshly created spreadsheet. The first runs the full
typed +table-put → +table-get round-trip (date / numeric / object
columns with custom number_format) and asserts the dtype + format
contract holds end-to-end. The second exercises the typed
+workbook-create --sheets path: create + write in one shortcut, the
payload sheet name adopts the workbook's default sheet (no empty
"Sheet1" left behind), and the typed contract still survives the
read-back.
End-to-end verified locally (user identity): typed put round-trips
preserve dtypes (date → datetime64[ns], numeric → float64, object →
object) + formats verbatim; workbook-create adopts the named sheet as
the first sheet with the same typed shape intact.
* sync(sheets): pick up sheets_df.py — pandas ↔ JSON skill script from spec
Mirror of the sheet-skill-spec change that adds a DataFrame ↔ JSON
bridge as a skill-bundled Python script instead of inside the CLI
binary. Per PR #1355 review (docx NcmxdRo2yoZ4OXxoMUZcxRZ7nHd, §4.2):
keep the CLI a thin JSON/REST client; pandas / Arrow editing lives in
the caller's Python process. Synced from canonical via generate:cli +
sync:cli.
- skills/lark-sheets/scripts/sheets_df.py (new): pandas DataFrame ↔
one sheet, .parquet / .feather / .arrow / .csv / .json. Shells out to
`+table-put` / `+table-get` over typed JSON — no CLI changes.
- SKILL.md decision tree + write-cells.md +table-put section: explicit
pointers so pandas users land on the script instead of hand-rolling
the `--sheets` payload.
End-to-end verified against PPE: 3-row DataFrame (datetime / float /
object) round-trips parquet → script put → real sheet → script get →
parquet with dtypes preserved.
* Revert "sync(sheets): pick up sheets_df.py — pandas ↔ JSON skill script from spec"
This reverts commit 2964983b92.
* sync(sheets): pick up sheets_df.py + doc DRY cleanup from spec
Mirror of the sheet-skill-spec change that ships a 32-line helper-only
sheets_df.py (df_to_sheet + sheet_to_df) and removes the corresponding
inline `def` blocks from three reference docs.
- skills/lark-sheets/scripts/sheets_df.py (new): pandas DataFrame ↔
one +table-put / +table-get sheet, importable as a library. Same
helper pair the docs already taught, lifted out of the prose so
callers can `from sheets_df import df_to_sheet, sheet_to_df`.
- lark-sheets-write-cells.md / lark-sheets-read-data.md /
lark-sheets-workbook.md: drop the inline helper definitions; keep
the usage examples (single/multi-sheet, round-trip) and switch them
to import-from-script. workbook reference's +workbook-create
--sheets section now points pandas users at the helper directly
(was previously a textual reference back to write-cells).
End-to-end verified against PPE (--as user):
- +workbook-create with df_to_sheet for three sheets (income / balance
/ cashflow): create ok, dtypes (datetime64[ns] / float64) + formats
(#,##0 / 0.0% / yyyy-mm-dd) survive on read-back through sheet_to_df.
- read → pandas mutate → write-back round-trip preserves both data
and formats.
* chore: drop accidentally-committed __pycache__/ and gitignore .pyc
The previous commit (5fac9c39) shipped sheets_df.py and inadvertently
included its `__pycache__/sheets_df.cpython-312.pyc` — local Python
import created the bytecode cache during PPE round-trip verification and
`git add skills/lark-sheets/` swept it in.
Remove the pyc and add Python bytecode patterns to .gitignore so the
skill-bundled helper scripts don't pull cache files into future commits.
* refactor(sheets): drop --dataframe / --dataframe-out + apache/arrow dep
Per the design review at NcmxdRo2yoZ4OXxoMUZcxRZ7nHd, the Arrow IPC binary
input/output channel adds a heavy columnar runtime to the CLI for no new
capability — the typed JSON --sheets path already covers everything, and
the column-major / zero-copy advantages collapse the moment the CLI re-
encodes into the row-oriented sheets OpenAPI JSON body. Removing it also
lets us drop the `--ignore github.com/apache/arrow/go/v17` license-check
escape hatch.
Deleted:
- shortcuts/sheets/lark_sheet_dataframe.go (+ test)
- --dataframe branches in +table-put / +workbook-create
- --dataframe-out branch in +table-get
- StdinConsumed / MarkStdinConsumed exported methods (the binary stdin
reader was the only out-of-band consumer); internal stdinConsumed
guard against duplicate `-` input flags stays
- apache/arrow/go/v17 + transitive deps via `go mod tidy`
- CI go-licenses --ignore for arrow and the LICENSE.txt assertion step
- --dataframe / --dataframe-out coverage in skill references
Pandas users keep the round-trip via the existing skill script
skills/lark-sheets/scripts/sheets_df.py over the JSON path.
The full pre-removal state is preserved on branch feat/sheets-arrow-stash.
Upstream sheet-skill-spec follow-up: the two flag rows in the canonical
spec + base table tblV2F6fqIjyCFQW must also be dropped so the next sync
does not re-add them.
* sync(sheets): pick up --sheets one-liner fix from spec
Mirrors sheet-skill-spec 5562f83. The +table-put / +workbook-create
--sheets flag descriptions (and the --print-schema description on the
sheets array) now point at the existing df_to_sheet helper instead of
the previous misleading one-liner that produced a dict missing the
outer {"sheets":[...]} envelope and the per-sheet `name`. Agents that
copy-paste the description verbatim now build a valid payload.
Auto-synced via spec's generate:cli + sync:consumers; go generate
./shortcuts/sheets/... regenerated flag_defs_gen.go so its embedded
flagDefs stays byte-equal to data/flag-defs.json.
* test(sheets/e2e): close E2E coverage gaps for newly added shortcuts
AGENTS.md requires both dry-run and live E2E for every newly registered
shortcut, and behavior-changing refactors need at least the matching
half. Three gaps remained on feat/lark-sheets-develop:
- +sheet-show-gridline / +sheet-hide-gridline (new): only dry-run E2E.
Add sheets_gridline_workflow_test.go — create a real spreadsheet,
toggle hide then show against a live sub-sheet, assert ok=true on
both (gridline state is write-only — there is no read-back field on
+sheet-info / +workbook-info — so a successful envelope is the
meaningful signal; the dry-run E2E already pins the wire shape).
- +workbook-import (new): only dry-run E2E. Add
sheets_workbook_import_workflow_test.go — write a local CSV, run
the full upload → create-task → poll, assert ready=true with a
sheet token, +info confirms the imported workbook is reachable,
cleanup deletes the spreadsheet.
- +workbook-export refactor (no-download default changed): had live
E2E but no dry-run E2E in tests/cli_e2e/. Add
sheets_workbook_export_dryrun_test.go — pin the three sheet-
specific differences vs drive +export: type=sheet hard-coded,
csv mode routes --sheet-id onto sub_id (xlsx mode omits it), and
--output-path maps onto the dry-run plan's top-level output_dir.
Also pins the csv-without-sheet-id validation error.
* refactor(sheets): unify workbookCreatedButFillFailed with OutPartialFailure
Three "made it halfway and stopped" exits in the sheets domain previously
disagreed on shape, which made the post-failure recovery flow hard for
agents to predict from one command to another:
- +table-put partial write → exit 1, stdout ok:false envelope
- +table-put zero-sheet write → exit 1, stderr api/server_error
- +workbook-create create-but-fill → exit 2, stderr validation/failed_precondition
OutPartialFailure exists exactly for "the side effect landed but the
follow-up didn't" — it stamps an ok:false result envelope on stdout
(carrying the state the caller needs to recover) and returns the bare
partial-failure exit signal. The workbook-create fill-failure path was
the odd one out: it surfaced as a typed failed_precondition error on
stderr, which agents couldn't tell apart from a plain validation refusal
even though the spreadsheet really did exist and a retry / cleanup was
possible.
Migrate workbookCreatedButFillFailed onto OutPartialFailure so the four
call sites in +workbook-create's Execute (sheet-resolve failure, initial
fill failure, style-only resolve failure, style-only apply failure) emit
the same envelope shape +table-put's partial write does:
{
"ok": false,
"data": {
"spreadsheet_token": "shtNEW",
"reason": "spreadsheet shtNEW created but initial fill failed",
"hint": "the spreadsheet exists; retry the fill … or delete it",
"cause": {"category": "...", "subtype": "...", "message": "..."}
}
}
The inner failure's typed problem (category / subtype / message) is
flattened into the `cause` field so agents stay diagnosable from the JSON
envelope alone, instead of having to errors.Unwrap a Go error.
Updated TestExecute_WorkbookCreate_FillFailureKeepsToken to assert the
new shape (ok:false envelope on stdout, *output.PartialFailureError exit
signal, structured cause carrying the underlying invalid_response
subtype) — preserving the original test intent (token must survive for
recovery; inner cause must stay diagnosable) under the new contract.
* chore(sheets): three review nits — WithCause + stale comment + unexport
- shortcuts/sheets/flag_schema_validate.go:106 — composite-JSON shape
validation was wrapping vErr's message into a typed sheets validation
error without preserving vErr as the typed cause; add the missing
.WithCause(vErr) so errors.Unwrap and ProblemOf still find the
underlying validator error (matches every other typed-error chain
helper in the file).
- shortcuts/sheets/lark_sheet_batch_update.go:92 — comment claimed
batchUpdateInput returns "FlagErrorf-typed errors", but FlagErrorf no
longer exists (the typed-error migration replaced it with
common.ValidationErrorf / errs.ValidationError); update the comment
to reflect what is actually returned.
- shortcuts/drive/drive_export.go:121 — drop the ValidateExport public
alias and rename to validateExport. sheets +workbook-export reuses
RunExport / PlanExportDryRun from this package but inlines its own
(sheet-specific) Validate, so there is no cross-package call site —
ValidateExport was a misleading sibling of the genuinely-shared
ValidateImport. Comment added to record the asymmetry so future
readers do not export it back.
* chore(deps): drop stale indirect bumps left by the arrow removal
The earlier --dataframe / --dataframe-out + apache/arrow/go/v17 removal
deleted the arrow consumer but left two indirect lines in go.mod pinned
to the versions arrow had pulled in:
- github.com/kr/text v0.2.0
- golang.org/x/exp v0.0.0-20240222234643-814bf88cf225
With arrow gone, larksuite/cli was the only requirer of those exact
versions; every real consumer needs lower ones (kr/pretty wants
kr/text v0.1.0; charmbracelet/huh wants x/exp …20231006; xo/terminfo
wants x/exp …20220909). Removing the two indirect lines and running
`go mod tidy` lets MVS pick the real-consumer versions and drops the
explicit indirect entries entirely — go.mod net-diff against main is
now zero for this branch.
Verified locally: go build ./...; go test ./shortcuts/sheets/...
./shortcuts/drive/... ./shortcuts/common/... ./internal/auth/...
./cmd/auth/... — all green.
---------
Co-authored-by: zhengzhijie <zhengzhijie.j@bytedance.com>
Co-authored-by: Chenweifeng-bd <chenweifeng.1534@bytedance.com>
* feat(base): add URL and title resolve shortcuts
* docs: clarify base coordinate resolution
* fix(base): address resolve shortcut ci
* fix(base): format resolved record share hint
* fix(base): simplify record share hint data
* fix(base): use field ids in resolved record data
* fix(base): guide record share resolve to update record
* fix(base): include record upsert example in resolve hint
* fix(base): reject add-record urls in resolver
* fix(base): validate title resolve query length
* fix(base): hide resolve alias flags from help
* fix(base): prefer title flag for title resolve
* docs(base): clarify token resolution wording
Add support for card.action.trigger, the event fired when a user interacts with an
interactive card (button click, form submit, dropdown, checkbox, input, date picker, etc.).
The handler flattens the V2 envelope into a structured output and auto-fetches the original
card content (card_content) at consume time, enabling a complete read-then-update workflow
without extra API calls.
Fix IM shortcut behavior for audio messages to match the Feishu/Lark file upload API: --audio is for voice messages and supports only Opus audio. Non-Opus local/URL inputs such as mp3 and wav are now rejected before upload with an actionable typed validation error. Users can still send those files as attachments with --file
* fix: reject +init into a different app's project directory
* fix: reject single HTML files larger than 10MB in +html-publish
* docs: clarify publish visibility, domain routing, and role/permission boundary
buildListParams used to re-call resolveFolderID / resolveFolderName (and the
label counterparts) on every list page to assemble folder_id / label_id.
Because resolveListFilter already resolves the filter once before the
pagination loop, the second pass hit the folders/labels list API again on
every page — 1 + page_count calls total, which easily trips rate limits.
buildListParams now only assembles API params from the already-resolved
FolderID / LabelID produced by resolveListFilter; it no longer resolves
names or aliases. The default folder_id=INBOX is still applied when no
explicit filter is present, and only overridden when the caller supplied a
canonical folder ID. The runtime / mailboxID / dryRun parameters are kept
for signature stability (resolveListFilter and buildSearchParams share the
same call shape).
Adds TestMailTriageCustomFolderResolvesOnceAcrossListPages: a custom-folder
filter forced across two messages-list pages, with a non-reusable folders
list stub so any second folders API call fails the test. Updated the two
existing buildListParams alias tests to run resolveListFilter first, mirroring
the real DryRun/Execute call order.
sprint: S1
Co-authored-by: xukuncx <283114605+xukuncx@users.noreply.github.com>
Support content_v2 post message conversion in IM shortcuts so newer post payloads render with the expected markdown, mention, and image formats while preserving fallback compatibility with legacy content.
Previously, im.message.receive events with message_type: interactive surfaced the raw JSON
payload as content, requiring callers to manually parse the card schema. This PR introduces a
user_dsl renderer (ConvertInteractiveEventContent) that converts interactive card content into
structured human-readable text — consistent with how text, post, image, and other message
types are already handled.
The output format is <card title="..." subtitle="...">...</card>, with each card element type
serialised to a readable representation (markdown body, button links, table rows, chart summaries,
etc.).
* feat(okr): add +batch-create, +reorder, +weight shortcuts
Add three new OKR shortcuts for managing objectives and key results:
- +batch-create: Bulk create objectives with key results, with automatic
rollback on failure
- +reorder: Adjust position of objectives or key results within a cycle/objective
- +weight: Adjust weights of objectives or key results with automatic
normalization using fixed-point arithmetic to avoid float precision issues
Key implementation details:
- API paths use underscore separators (/objectives_position, /objectives_weight)
- Weight normalization uses json.Number for precise JSON serialization
- Items are sorted by position before API calls to match backend requirements
- Full unit test coverage and dry-run/live E2E tests
- Skill documentation with usage examples and parameter descriptions
Change-Id: I92b658e0cc42ffa8cbdaec2ec628a079bcfc38f5
* fix: skill simplify & minor fix
Change-Id: I3f27a01cdae2122f26e48ee2acb7f334f2bab7d2
* fix: CR issue
Change-Id: Id9fab84e06f0d67e9f79c1fb9946b6b633200592
* fix: CR issue 2
Change-Id: I6a5e57dd4b10dc79f8681ec614354fbba82abc04
* fix: error handle of +weight shortcut
Change-Id: I6e2a39269e62e3b504e681110843b2ccc315a527
* 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.
When --name is omitted, remind user that the title defaults to the source
filename and may duplicate content headings, causing visual redundancy.
Ask whether to rename before executing the import.
* docs(mail): clarify message read shortcuts
Update mail read shortcut help, docs, and triage guidance so single-message and multi-message reads are routed to the right commands.
Add focused tests for help text, dry-run copy, triage stderr hints, and batch_get chunking behavior.
sprint: S1
* docs(mail): align batch_get limit with gateway config
* docs(mail): use shell-safe batch message id examples
* docs(mail): trim batch_get pagination wording
* docs(mail): use placeholder style for message ids
* docs(mail): hide batch_get internals from help
The 4 im query commands had three inconsistent sort conventions and leaked upstream API jargon (ByCreateTimeAsc, member_count_desc) directly to users. This PR unifies them on a single rule — --sort selects a field, --order selects a direction, both from fixed enums — so an agent only ever picks from an enum, never constructs a string. Old flags (--sort-type, --sort-by, and --sort on messages/threads) are kept as hidden silent aliases (no deprecation warning), so existing scripts keep working byte-for-byte.
* feat: add --json flag support to auth subcommands
* feat(auth/logout): add json output support for logout command
* feat(auth/list): add json output support for auth list command
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.
The cherry-picked riscv64 commit derived RACE_FLAG from `go env GOARCH`
via a grep pipeline, which ignores a GOARCH passed on the make command
line (e.g. `make GOARCH=riscv64 unit-test`) since command-line make
variables are not visible to $(shell ...). Switch to a make-native
filter that honors both, and restore the trailing newline the same
commit dropped.
Add a server-side --chat-modes filter to the im +chat-search shortcut so
users can restrict results to regular groups and/or topic groups.
Change-Id: Ia59c2c05fb2e8e45bd741c8531ca0e3ca69de2f3
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
Add SKILL.md entries for the group manager and group moderation
(speaking-permission) API-meta resources:
- chat.managers.add_managers / delete_managers (指定/删除群管理员)
- chat.moderation.get / update (查询/更新群发言权限)
Emit structured validation, API, network, file, and internal error envelopes for Wiki shortcuts so users and agents can recover from failed wiki workflows using stable type, subtype, param, and code fields.
Add Wiki domain errscontract and golangci guards to prevent legacy envelope and common helper regressions.
* feat: add fullstack app-type and --message to apps +create (#1)
* feat: accept fullstack app-type and require --message for it
* feat: inject message into fullstack create request body
* refactor: align fullstack message injection with existing body-build style
* docs: document fullstack app-type and --message for apps +create
* docs: keep scene numbering consistent in lark-apps-create reference
* docs: add HTML/fullstack intent routing to lark-apps SKILL.md
* docs: cover fullstack in lark-apps skill description and clarify HTML flow step
* test: assert fullstack in allow-list error and reject wrong-cased fullstack
* feat: drop --message from apps +create (#4)
* feat: drop --message from apps +create
* docs: drop --message and document agent-generated name/description for apps +create
* feat: add apps local key-value file storage (#5)
* feat: add Miaoda app git credential support (#9)
* fix: remove APIError detail field dependency
* docs(apps): expand lark-apps skill for local-dev & cloud-chat workflows (#3)
Reframe lark-apps from an HTML-publish skill into a full Miaoda app dev
tool covering three paths: local fullstack dev, HTML hosting, and cloud
session dev. Builds on the fullstack create change already on this branch.
- SKILL.md: 3-path routing table; mental models (code via native git,
develop/main branch model, DB via +db-* through Miaoda, env auto-pulled
by `npm dev run`, auto-managed credentials); command index for the new
verbs; ambiguous-input fallback (infer app type from need, ask local vs
cloud instead of assuming; default HTML when no signal)
- add local-dev and cloud-dev playbooks
- create: keep HTML/fullstack + required --message; add local/cloud scene
routing and --enable-multi-env-db
- list: usable by agents with --filter; app_id resolution order
(user-provided / .spark/meta.json / +list --filter)
Co-authored-by: wangjiangwen-gif <286006750+wangjiangwen-gif@users.noreply.github.com>
Co-authored-by: raistlin042 <lvxinsheng@bytedance.com>
* feat(apps): add 4 db CLI commands (table-list / table-schema / sql / dev-init)
妙搭 data CLI 4 条命令，复用存量 OpenAPI URL + 1 个新增 dev-init：
- +db-table-list → GET /apps/{id}/tables（游标分页，AppTable 含预估行数/占用空间）
- +db-table-schema → GET /apps/{id}/tables/{name}（默认结构化 schema；--format pretty 出建表 DDL）
- +db-sql → POST /apps/{id}/sql_commands（?transactional=false DBA 模式）
- +db-dev-init → POST /apps/{id}/db_dev_init（单库→online/dev，不可逆，high-risk-write）
要点：
- sql result 兼容两种 wire 形态（结构化 [{sql_type,data,record_count}] 与 legacy ["rows-json"]）
- 多语句失败：server 返 code:0 + ERROR 哨兵，CLI 升级成 typed api_error（exit 非 0），
detail 带 statement_index/completed/rolled_back，防止 agent 误判 ok:true 假成功
- pretty 渲染对齐 miaoda：列间两空格、CJK 双宽、size 友好格式（KB/MB/GB）
- 单测 + e2e dry-run 全覆盖；BOE 真机 e2e 验证通过（25 PASS）
- SKILL.md 注册 4 条命令 + 4 篇 reference
注：内含的 BOE 联调专用 env 覆盖（LARK_CLI_OPEN_API_BASE / LARK_CLI_X_TT_ENV，
internal/cmdutil + internal/envvars）未包含在本次提交，仅本地联调用。
Change-Id: I0fe4458086708a93941e2dee852fa6a10b53bd4a
* docs(lark-apps): db 能力补进 SKILL.md description 的 WHEN 段
按 skill 质量规范（description 三段式 WHAT+WHEN+NOT，加载前唯一可见信息），
原 WHEN 仅"连数据库调试"含糊覆盖 db。补成「查看或操作应用数据库（看表结构 /
跑 SQL / 初始化 dev 环境）」，让 +db-table-schema / +db-sql / +db-dev-init
类查询能精确触发，净增 ~12 字无膨胀。
Change-Id: Id52819fa7d6b8ed0c1f174bf5946d55da7b893d7
* Feat/apps env pull (#11)
* feat: add apps env-pull shortcut
* fix: support array env_vars response in apps env-pull
* fix(apps): improve env-pull merge and expiry output
* feat: add keyword/scope/app-type query to apps +list and unhide it (#8)
* feat: switch apps +create --app-type enum to lowercase html/full_stack
* feat: add keyword/scope/app-type query to apps +list and unhide it
* docs: document apps +list query params and lowercase app_type enum
* test: update apps cli_e2e dry-run tests for lowercase app_type and +list filters
* docs: trim redundant app_type case-sensitivity note in create skill
* docs: single-source apps +list usage contract to SKILL.md
* feat: add apps publish shortcuts (publish/status/history/error-log) (#12)
* feat: add apps publish shared guard and NodeStatus mapping
* test: cover json.Number path in injectStatusName
* feat: add apps +publish shortcut
Implements the `apps +publish` command with dry-run preview (upstream
PSM path shown) and an Execute gated by ensurePublishWired() per the
not-yet-deployed OpenAPI gateway constraint (publishAPIWired=false).
* refactor: make apps publish path placeholders var to satisfy go vet
Declare the four publishXxxPath constants as var instead of const so
go vet's printf analyzer skips them while they are empty placeholders.
Revert the Execute path-build in apps_publish.go from strings.Replace
back to fmt.Sprintf (now safe because the format string is a var).
* feat: add apps +publish-history shortcut
* feat: add apps +publish-status shortcut
* feat: add apps +publish-error-log shortcut
* feat: register apps publish shortcuts
Add AppsPublish, AppsPublishHistory, AppsPublishStatus, AppsPublishErrorLog
to Shortcuts() and update count test from 6 → 10.
* docs: add skill references for apps publish shortcuts
* docs: surface apps publish shortcuts in lark-apps SKILL.md
* docs: clarify publish instance id is not an approval instance
* docs: nudge agent to run apps +publish --dry-run for release requests
* feat: update apps publish shortcuts to v1.0.381 release protocol
Rename concept instance→release across all 4 publish shortcuts and their
tests: NodeStatus→ReleaseStatus enum, --instance-id→--release-id flag,
pipelineTaskID→releaseID response field, errorJobs→errorLogs, and
upstream HTTP path consts→RPC method name consts (PSM lark.apaas.devops
v1.0.381). Dry-run now shows psm+rpc_method instead of an HTTP path.
* docs: update apps publish skill docs to v1.0.381 release protocol
* fix: soften apps publish unavailable hint to user-facing language
* feat: update apps publish to v1.0.385 string status + --status filter
- Remove obsolete int-enum machinery (releaseStatusName/toInt/injectStatusName)
and their encoding/json + fmt imports from apps_publish_common.go
- +publish Execute now returns status string alongside release_id
- +publish-history gains --status Enum flag (publishing/finished/failed);
buildHistoryBody gains status param, table column status_name→status
- +publish-status Execute drops injectStatusName, pretty prints out["status"]
- +publish-error-log shapeErrorLog is string passthrough (no status_name)
- Unit tests updated: delete 3 obsolete common tests, update history/error-log
* docs: update apps publish docs to v1.0.385 string status + --status filter
* feat: wire apps publish shortcuts to final gateway paths (guard stays until deploy)
Replace RPC-name placeholders with real OpenAPI paths (publishCreate/Get/ErrorLog/ListPath consts). Switch DryRun to idiomatic HTTP form (POST/GET + real URL + body/params). Fix body/query placement: publish body has no app_id (path-only); history switches from POST body to GET query with snake page_token. Fix Execute response reads to snake_case fields (release_id, created_at, updated_at, error_logs). publishAPIWired stays false; 1-line flip activates live calls.
* docs: update apps publish docs to final gateway paths
Replace RPC/PSM dry-run example with real HTTP form (POST/GET /open-apis/spark/v1/apps/:app_id/releases[/:release_id[/error_logs]]).
Fix all response field names to snake_case (release_id, created_at, updated_at, error_log).
Note --status/--limit/--page-token as HTTP query params in publish-history.
* feat: enable apps publish gateway calls (remove not-deployed guard)
* docs: remove not-deployed transition notes from apps publish docs
* feat: use spark:app:publish scope for apps +publish
* feat(apps): add +init shortcut to initialize Miaoda app repo (#6)
* feat(apps): add command runner and credential redaction for +init
* fix(apps): make credential redaction scheme matching case-insensitive
* feat(apps): add +init shortcut declaration, validation, and dry-run
* feat(apps): implement +init orchestration (credential-init, clone, checkout, conditional push)
* fix(apps): redact full userinfo when repo URL contains literal @
* docs(apps): add +init skill reference
* fix(apps): declare explicit empty Scopes on +init shortcut
* fix(apps): consume repository_url from +git-credential-init in +init
* feat(apps): add +init template flag and absolute-path dir resolution
* refactor(apps): use shared charcheck for +init --dir validation
* feat(apps): add meta.json, steering, and empty-repo helpers for +init
* feat(apps): add +init npx scaffold orchestration (init/upgrade branches)
* feat(apps): wire +init scaffold, already-initialized short-circuit, npx dep check
* docs(apps): document +init npx scaffold, --template, --dir, already-initialized
* docs(apps): correct stale +git-credential-init unreleased note in +init ref
* fix(apps): reject all control chars in +init --dir
* feat(apps): add +init progress logging and optional --template resolver
* refactor(apps): inline constant in +init scaffold progress log
* docs(apps): document +init optional --template and stderr progress contract
* feat(apps): treat README-only repo as empty and commit with --no-verify in +init
* docs(apps): explain README-seed match and --no-verify rationale in +init
* docs(apps): document README-seed empty detection and commit --no-verify
* feat(apps): add session conversation lifecycle shortcuts (#13)
* feat(apps): add +session-create shortcut
* fix(apps): remove unused sessionPath helper, assert empty +session-create body
* feat(apps): add +session-list shortcut
* feat(apps): add +session-read shortcut
* feat(apps): add +session-stop shortcut
* feat(apps): add +chat shortcut
* feat(apps): register session lifecycle shortcuts
* docs(apps): add session conversation skill reference
* docs(apps): clarify fullstack session_id source and fallback
* style(apps): gofmt apps_session_create.go
* docs(apps): add conversation/session triggers to skill routing description
* docs(apps): add conversation flow guidance (when to reuse vs new session, per-step user prompts)
* docs(apps): slim session reference per skill quality standard (4047->1726 tok)
* docs(apps): tighten session additions in SKILL.md (4394->4145 tok)
* fix(apps): align +chat with v7.8 contract (async, no turn_id in response)
* fix(apps): update +chat path to .../sessions/{id}/chat (backend endpoint change)
* docs(apps): align SKILL.md session command shape with v7.8 contract
* style(apps): gofmt apps_db_table_schema_dryrun_test.go
Go 1.19+ gofmt 文档注释列表缩进新规则（普通缩进 → tab 对齐），
修复 fast-gate CI 的 gofmt 卡点。
Change-Id: Ic246a659e016d9d6216182199ef300ae6f00ef9d
* feat(apps): split +init commit, plainer wording, align skill branches (#14)
* refactor(apps): plainer +init progress/help wording, keep scaffold key
* refactor(apps): add porcelain change classifier for +init commit split
* feat(apps): split +init empty-repo commit into code + config, reword subjects
* refactor(apps): scaffold-kind constants and pathspec assertions for +init split
* docs(apps): use +init in Path A; align app-repo branch to sprint/default
* docs(apps): align local-dev playbook to sprint/default + origin remote
* docs(apps): document +init two-commit split and plainer init wording
* docs(apps): require asking clone dir before +init, no assumed path
* fix(apps): stage +init commits by exact paths to avoid gitignore error
* refactor(apps): lowercase miaoda in +init commit subjects
* test(apps): cover +init upgrade path with real git
* fix: harden app git credential handling (#16)
* fix: harden git credential refresh fallback (#18)
* fix(apps): validate env-pull key names before writing to .env.local (#17)
* fix(apps): validate env-pull key names before writing to .env.local
S2 (medium-low) from security review: env-pull wrote server-returned
env KEYs to .env.local without validation. A compromised or MITM'd
backend could inject arbitrary lines via keys containing newlines.
- Add envKeyPattern regex to validate keys match [A-Za-z_][A-Za-z0-9_]*
- extractEnvPullVars now returns skippedKeys for invalid key names
- Invalid keys are skipped (not hard-fail) so remaining valid keys
are still pulled
- writeEnvPullPretty prints a warning listing skipped keys
* fix(skills): correct npm script syntax from 'npm dev run' to 'npm run dev'
* fix(skills): align env-pull guidance with implementation
🤖 Generated with [Aiden x Claude Code]
* test(apps): cover storage/git-credential error paths and fix tz-flaky env-pull tests (#19)
The coverage and unit-test CI jobs failed on two timezone-dependent
assertions in apps_env_pull_test.go: the code renders the database
expiry via time.Local() while the tests hard-coded a CST literal, so
they failed under CI's UTC. Compute the expected string from the same
timestamp with Local() instead, making the assertions timezone-agnostic.
Also add unit tests for the error branches codecov flagged as uncovered,
taking storage.go and git_credential.go to 100%:
- storage Read/Write/Delete/List filesystem-error paths
- +git-credential-remove ConfigWarning output (pretty and JSON)
- gitCredentialLocalError nil passthrough
* fix(apps): silence +init forbidigo, npx app sync -y --prefer-online (#20)
* fix(apps): add Subtype to env-pull error literals (#21)
typed_error_completeness lint requires all errs.XxxError literals to
set Problem.Subtype. Add the missing field to 11 error constructions:
- ValidationError (user input checks): SubtypeInvalidArgument
- ValidationError (API response parsing): SubtypeInvalidResponse
- InternalError (filesystem ops): SubtypeUnknown
* feat(apps): inject FORCE_DB_BRANCH=dev in env-pull output (#23)
* feat(apps): inject FORCE_DB_BRANCH=dev in env-pull output
Always write FORCE_DB_BRANCH="dev" into the resolved .env.local after
extracting upstream env_vars, so downstream tooling pinning the dev
database branch does not need a separate manual edit. Existing local
values are overwritten in place via the canonical merge path.
* docs(skills): document apps +env-pull in lark-apps skill
Add the env-pull entry to the lark-apps SKILL index and ship the
matching reference doc covering args, merge semantics, return shape,
error envelope subtypes, and dry-run behavior so AI agents can route
to it without reading the Go source.
* feat(apps): surface is_published and online_url in +list pretty view (#22)
* docs: refactor lark-apps skill per quality spec (#24)
Slim SKILL.md and references against the lark-cli skill quality spec
while preserving domain knowledge and safety guardrails.
- Compress SKILL.md (drop the MUST-read prelude, full command-index
tables, and content already owned by lark-shared: auth, scope,
exit-10, risk policy, _notice); add version field; zero CRITICAL
markers.
- Defer flag enumeration in references to `--help`; convert
narration-inducing prohibitions into positive defaults; de-duplicate
the per-file error.hint relay into a single resident SKILL.md rule.
- Fix stale facts found against shortcuts/apps source: drop the
non-existent +create --message and --enable-multi-env-db flags,
+list --filter (now --keyword), +db-multi-env-init (now
+db-dev-init), and the removed html-publish cwd hard-reject.
- Keep all safety guardrails: db-dev-init irreversibility/exit-10,
db-sql non-transactional multi-statement, git-credential token
handling, html-publish credential scan, access-scope confirmation.
- Restore intent lost during slimming: release_id is not an approval
instance (do not route to lark-approval); resolve access-scope
targets via contact/im; ask the user before publishing as a
side-effect; distinguish developing an existing app locally
(+init) from creating a new one (+create).
* test(apps): supplement shortcuts/apps unit-test coverage to 88% (#25)
* test(apps): cover db-table-list numeric/byte formatting helpers
* test(apps): cover db-sql cell/code/dml/error render helpers
* test(apps): cover env-pull newline/expiry/extract-vars helpers
* test(apps): cover db-sql render branches and env-pull expiry edge case
* test(apps): cover init empty-dir/meta/ls-files error branches
* test(apps): cover env-pull target/read/parent-dir error branches
* test(apps): cover stage-and-commit and commit-push error branches
* test(apps): cover access-scope target split and JSON validation
* test(apps): cover html-publish decode error and scaffold sync failure
* test(apps): cover apps-update body field combinations
* test(apps): cover access-scope body build branches
* feat(apps): pass --local to npx skills sync in +init (#26)
* feat(apps): pass --local to all npx miaoda-cli calls in +init
* feat(apps): pass --local only to npx skills sync in +init
* docs(apps): surface +publish and +init dir-choice in local-dev flow (#27)
* docs(apps): surface +publish as deploy action in skill routing
* docs(apps): add explicit deploy-after-local-edit section to local-dev
* docs(apps): promote +init dir-choice instruction to a domain rule
* docs(apps): make dev-method a signal-driven entry gate before routing (#28)
* docs(apps): restore three-path overview line in apps skill intro (#29)
* feat(apps): add executable Examples to shortcut --help and error hints (#30)
* test(apps): guard every shortcut has a help Example and no PII
* feat(apps): add help Examples to all 24 apps shortcuts
* feat(apps): add actionable hints to high-impact error paths
* test(apps): cover withAppsHint set-if-empty hint behavior
* feat(apps): use concrete enum value in access-scope-set Example
* docs(apps): clarify db-sql/db-table-list json default output behavior
两处仅补充注释，不改逻辑：
- +db-sql: data.results 在 json 默认路径原样透出全部行，CLI 不二次截断；
server 对单条 SELECT 有 1000 行硬上限、超出直接返报错，非无界 token 黑洞。
- +db-table-list: json 默认透出含每表完整 columns[] 系产品设计（list 接口本就
返回列定义，json 消费方一次拿全量、免逐表再调 +db-table-schema），pretty 仅摘计数。
Change-Id: I1a49de8defc4428bfe1e774e4fd7adb45e59e3af
* feat(apps): command-layer AI-friendliness governance (P0+P1) (#32)
* fix(apps): normalize --app-type case to align with server
* refactor(apps): migrate CallAPI to CallAPITyped for typed errors and retryable
* feat(apps): trim icon_url and created_at from +list default output
* feat(apps): add actionable hints to high-impact error paths
* feat(apps): add 2-3 help Examples to +chat and +access-scope-set
* docs(apps): add --jq filter tips to list/db commands
* docs(apps): sync +list reference with trimmed output fields
* test(apps): assert error hints and messages carry no secrets or PII
* fix(apps): prefix --jq tips with .data. so they run against the response envelope
* test(apps): expect --app-type uppercase normalization in create dry-run E2E (#33)
* fix(apps): scaffold via @latest miaoda-cli instead of @alpha (#34)
* feat(apps): rework lark-apps triggering, routing & confirm policy (#35)
* feat(apps): results-oriented triggering, pre-auth floors, terminal URL
Widen description WHEN to cover app-building openers (CRM/审批/HTML page)
with no Miaoda signal word, WHAT still anchored to 妙搭应用开发与托管.
Add a pre-authorization rule (auth words skip confirm) with two non-exempt
floors: destructive DDL (DROP/TRUNCATE/ALTER drop|modify column) dry-run,
and first public-URL publish (+publish/+html-publish) when no auth word.
Exempt html app_type from the local-vs-cloud dev-method gate, and scope
that gate to new-app creation only (existing-app ops route directly).
Require an accessible URL as the end-to-end terminal step.
* feat(apps): apply eval-fix behavior contracts across reference docs
init/local-dev: end-to-end default-directory escape hatch; end-to-end
new-build starts with +create. db-sql: additive DDL direct-exec when
authorized, destructive DDL stays dry-run. local-dev/publish-status:
return online_url via +list as the full_stack publish terminal step.
cloud-dev: generation != shareable URL, +publish handoff, background
until-poll snippet (sleep N && cmd intercepted; deprecate ScheduleWakeup),
multi-turn publish precondition. publish/publish-error-log: transient
failure (EAI_AGAIN/ETIMEDOUT/registry) discrimination, retry cap 2,
honest receipt. env-pull: first-launch fallback. local-dev/db-dev-init:
new full_stack ships dual DB, skip +db-dev-init.
* refactor(apps): apply review feedback — semantic criteria, drop overfit/unverified content
Per line-by-line review of the eval-fix changes:
- Entry routing reframed to objective/semantic criteria (new-vs-existing =
'can an existing app be identified'; dev-method = who-writes-code
preference), replacing keyword/example matching.
- db-sql DDL gate restated by effect (data-loss / reversibility), not a
keyword list.
- Pre-authorization judged by expressed intent (not a word list); single
non-exempt floor (destructive/irreversible DB dry-run); confirm policy in
its own section, error.hint in 'failure handling'.
- init.md slimmed to command facts (directory choice owned by local-dev,
no init<->local-dev cycle); local-dev defers new-vs-existing to the entry.
- Reverted unverified/redundant/runtime-coupled additions: cloud-dev
session-read preview-URL claim + background-poll snippet + queued_count
precondition; publish transient-retry/ScheduleWakeup; env-pull first-launch;
db-dev-init positive restatement; SKILL terminal-URL mandate.
- Fixed dangling section references after the rename.
* fix(apps): scope pre-authorization to hands-off intent, not 'wants a result' (#36)
Follow-up to #35. The merged pre-authorization rule treated 'wanting the
final result' as authorization, so '先在本地跑起来让我看看' was read as
pre-authorized and the agent silently picked a clone directory without
asking. Re-state the criterion as the user's hands-off intent (explicit
waiver, or an end-to-end directive), judged uniformly across the flow
(directory/clone, publish) — not a per-decision carve-out. Merely wanting
a result or asking to review is not authorization.
* docs: clarify apps cloud dev publish state
* fix(apps): require commit+push before publish, clarify deploy flow (#38)
* fix(apps): require committing changes before publish in local-dev flow
* fix(apps): make commit+push mandatory before publish in agent rules
* fix(apps): scope selective-add caveat to incremental deploy, not new-app flow
* fix(apps): make pre-publish commit conditional on local changes
* fix(apps): tighten pre-publish commit wording in agent rules
* fix(apps): cloud-dev does not auto-deploy, add explicit publish step
* docs(apps): document +chat init vs incremental turn cost (#39)
First +chat on a not-initialized app runs full design+gen server-side
(~20-50 min); chat on an already-initialized app is incremental and
finishes in minutes. Surface this in the +chat Go comment as a pointer
and put the init-state check + matching polling cadence (5-10s vs
60-120s) in the lark-apps cloud-dev skill reference as the canonical
source. Cloud-side init check uses +session-read committed-version
info or +list is_published:true.
* docs(apps): document +chat init vs incremental turn cost (#40)
First +chat on a not-initialized app runs full design+gen server-side
(~20-50 min); chat on an already-initialized app is incremental and
finishes in minutes. Surface this in the +chat Go comment as a pointer
and put the init-state check + matching polling cadence (5-10s vs
60-120s) in the lark-apps cloud-dev skill reference as the canonical
source. Cloud-side init check uses +session-read committed-version
info or +list is_published:true.
* feat(apps): surface online_url/error_logs in +publish-status output (#41)
* refactor(apps): extract shared release error-log table helper
* fix(apps): keep error-log table byte-identical for null error_logs
* feat(apps): surface online_url/error_logs in +publish-status output
* docs(apps): read online_url/error_logs from +publish-status in publish flow
* docs(apps): align local/cloud dev publish flow with +publish-status fields
* refactor(apps): rename +db-dev-init→+db-env-create, trim db-table-list columns
- +db-env-create（原 +db-dev-init）：新增 --env 参数（调用方传入，目前只支持 dev），
--sync-data 改为 true/false 取值；服务端 URL 仍走 db_dev_init。
- +db-table-list：json 默认用白名单投影（dbTableListItem）只输出产品要求字段，
每表 columns[] 折算成 column_count、不再透出完整列定义（与 +db-table-schema 重复且放大
token）；要完整列定义/索引/约束用 +db-table-schema。
- 同步对齐 db 相关 skill 文档（命令名、column_count、env-create 参数）。
- 单测 + cli_e2e dry-run 全绿。
Change-Id: I116ab11807679f8f06ed18221f705bab426d015c
* refactor(apps): rename +db-table-schema → +db-table-get
动词对齐 +db-table-list（list/get）。仅命令名 + 标识符 + 文档改名，行为/输出/URL 不变：
- AppsDBTableSchema→AppsDBTableGet，文件/测试/cli_e2e test 重命名
- buildDBTableSchemaParams→buildDBTableGetParams
- +db-sql / +db-table-list 里的交叉引用 hint、skill 文档同步
Change-Id: I36dfb8fd0d2613492a57dc7815bc58414c145480
* feat: auto-pull env vars after apps +init (#42)
* test: route apps +env-pull to its own fake-runner key
* feat(apps): add +env-pull envelope parsers for +init
* feat(apps): add pullEnv helper invoking sibling +env-pull
* feat(apps): +init auto-runs +env-pull after push (non-fatal)
* docs(apps): clarify db-sql --query @path is relative-only, use stdin for absolute paths
@path 受 lark-cli 全局文件安全策略约束，只接受 cwd 内相对路径；绝对路径 / cwd 不固定
场景改用 stdin（--query - < /abs/file.sql），无需先 cd。
Change-Id: Ib3453810cfc9303d72b4facf3493ad9688eeffd3
* docs(apps): refine db-sql --query path guidance wording
以 agent 视角重写：@ 仅接受工作目录内相对路径，绝对路径/越界路径被拒（CLI 文件访问统一约束）；
工作目录外的文件经 stdin 传入。
Change-Id: Ic7db00934b3571368eb704451f4ce1776463806d
* feat(apps): make +db-sql high-risk-write (require --yes)
+db-sql 可含 DML/DDL，统一升级为 high-risk-write：框架对所有执行强制 --yes 确认关卡
（--dry-run 预览豁免），无 --yes 返 confirmation_required / exit 10。
- Risk: write → high-risk-write（去掉自定义门禁，直接用框架机制）
- skill 文档：命令骨架标注 --yes 要求；Agent 规则改为「执行需 --yes，只读可直接带、
破坏性先 dry-run 确认再带」
- 单测所有执行调用补 --yes
Change-Id: I57e78832b35fa170a485774e6fb7289109d678c3
* docs(apps): clarify app_ (Miaoda) vs cli_ (Feishu) app id (#46)
* 优化云端开发skill，明确执行模型，参数解释 (#44)
Co-authored-by: fushengdong.1 <fushengdong.1@bytedance.com>
* refactor: rename apps publish commands to release and session-get (#45)
* refactor(apps): drop +publish-error-log, rename release path constants
* refactor(apps): rename +publish to +release-create
* refactor(apps): rename +publish-history to +release-list, unify pagination to --page-size
* refactor(apps): rename +publish-status to +release-get
Renames apps +publish-status → +release-get (AppsPublishStatus → AppsReleaseGet),
updates --release-id desc to reference +release-create, and fixes the Execute
error hint to point at +release-list instead of +publish-history.
* refactor(apps): rename +session-read to +session-get
* docs(apps): rename publish references to release, +session-read to +session-get
* refactor(apps): clean up residual publish/session-read references
Fix six leftover references missed in Tasks 1-6: +publish-history in
jq-tip test wantCmds map and common_test hint fixture (×3), +session-read
in apps_chat.go comment+output string (×2), apps_session_stop.go flag
desc (×1), apps_chat_test.go comment (×1), and +publish-status in
lark-apps-list.md agent rule prose (×1).
* docs(apps): clarify release-get link contract and session-get vs session-list
* docs(apps): generalize release-list page-size rule to N records
* feat(apps): rename +list --scope flag to --ownership (#47)
* feat(apps): rename +list --scope flag to --ownership
* test(apps): update +list cli_e2e dry-run for --ownership rename
* docs(apps): document +list --ownership flag
* feat(apps): align +release commands with new release API format (#48)
* feat(apps): align +release-create scope to spark:app:write
* feat(apps): raise +release-list --page-size documented max to 500
* feat(apps): show commit_id in +release-get pretty output
* docs(apps): update release reference docs for page-size 500 and commit_id
* test(apps): cover empty commit_id in +release-get pretty output
* docs: align lark apps cloud dev release flow
* feat(apps): redesign +db-sql → +db-execute (--sql/--file, default env dev)
按 db 子域命令最终设计重做执行入口：
- 命令 +db-sql → +db-execute（动词收尾，对齐 +db-table-list/-get）
- --query 拆为 --sql（内联/stdin）与 --file（.sql 文件路径），二选一互斥；
--file 在 Validate 阶段读出归一化到 --sql
- 默认 --env online → dev（打生产库需显式 --env online）
- 文件/标识符/注册/测试/cli_e2e/skill 文档全部对齐重命名
- 新增测试：--sql/--file 互斥、--file 读取、默认 env=dev
不在本次范围：--transaction/--no-transaction（服务端 transactional 实为路径切换、
非真事务，需 dataloom 侧先支持真事务开关）、--max-rows/--timeout 等后续项。
Change-Id: I50c06faf83527471446e2a6651ccb51f6eedd6ff
* docs(apps): clearer --env online wording for +db-execute
把口语化的「打生产库需显式」改为「需要操作线上环境数据库时，显式指定 --env online」；
flag desc 同步去掉 hit production 措辞。
Change-Id: Iee82fccf17e08bddb4b760c3970a416746b10c4c
* docs(apps): drop 'ad-hoc' jargon from +db-execute description
中文文档/英文 description 去掉术语 ad-hoc；SELECT/DML/DDL 已表意，含义不丢。
Change-Id: Ie2cccc5fc3491fe5f57190a87b93ecd70405b156
* docs(apps): trim +db-execute when-to-use and --file path wording
- 何时用去掉「（查询 / 临时数据修复 / 应急 DDL）」枚举
- --file 路径说明去掉 .. /符号链接/统一约束 的技术化描述，改为「相对路径，
否则用 --sql - < 文件路径」的产品化口吻
Change-Id: Ie70e57895c78650230b6942b03d90a2d95c937f2
* docs(apps): note --file rejects absolute/cwd-escaping paths
简短补回 --file 的路径约束（绝对路径 / 经 ..、符号链接越界会被拒），去掉冗余评注。
Change-Id: I549893c82cafbe97529e08dcbc3ee5496927da18
* fix(apps): replace t.Chdir with os.Chdir in db-execute test (Go 1.23 compat)
t.Chdir 是 Go 1.24 API，但 go.mod 为 go 1.23.0，CI（Go 1.23）报
"t.Chdir undefined"。改用 os.Chdir + t.Cleanup 还原，1.23 兼容。
Change-Id: I550611773e5088275be1c4344d4f8269610ce74a
* feat(apps): refine +init description and refresh env on re-init
* fix(apps): treat accessible-link requests as publish intent (#53)
* refactor(apps): +db-env-create --sync-data string-enum → Type:bool
原实现用 string + Enum["true","false"] + == "true" 模拟 bool，啰嗦且非惯用。
改为 Type:bool（rctx.Bool）：传 --sync-data 即开启、省略为 false。
同步更新测试、cli_e2e dry-run、skill 文档。
Change-Id: I3068e0577fa20a7cbaf414ca9af3d197f6ae8049
* fix(apps): declare --app-type as strict lowercase enum (#55)
* docs(apps): front-load routing, dedupe, and trim lark-apps skill (#56)
* docs(apps): front-load intent-routing table and dedupe skill body
* docs(apps): dedupe publish guardrail and polling rules in cloud-dev
* docs(apps): trim env-pull implementation detail to behavior contract
* docs(apps): add +env-pull routing entry in SKILL.md
* docs(apps): fix create.md cross-ref to actual SKILL.md section name
* feat(apps): add error.hint to command failures and a consistency gate (#57)
* feat(apps): add appIDListHint const and wrap 4 pure app-id command failure paths
Adds shared `appIDListHint` recovery hint to common.go and wraps the
CallAPITyped failure branch of session-create, session-list, update, and
release-list to surface an actionable next-step hint on 4xx errors.
Includes httpmock unit tests in apps_hints_more_test.go (TDD: red→green).
* feat(apps): add sessionStopHint and createHint for session-stop and create commands
Adds per-command recovery hints with specific guidance: sessionStopHint
points at +session-list and +session-get; createHint explains valid
--app-type values and permission failure. Wraps the CallAPITyped failure
branch in both commands.
* feat(apps): add recovery hints for db-env-create, db-table-get, db-table-list
Adds dbEnvCreateHint, dbTableGetHint, and dbTableListHint with actionable
cross-command guidance (e.g. pointing at +db-table-list for env conflicts,
+db-env-create for missing dev env). Wraps only the CallAPITyped failure
branch; requireAppID validation errors are left untouched.
* refactor(apps): make session-stop hint runnable and align hint test names
* test(apps): guard withAppsHint upstream-wins contract and new hint leak safety
* test(apps): add help-skill command consistency gate
---------
Co-authored-by: linchao5102 <linchao.5102@bytedance.com>
Co-authored-by: Wang <wangjiangwen@bytedance.com>
Co-authored-by: wangjiangwen-gif <286006750+wangjiangwen-gif@users.noreply.github.com>
Co-authored-by: 陈兴炀 <chenxingyang.1019@bytedance.com>
Co-authored-by: aihao-git <aihao.0331@bytedance.com>
Co-authored-by: bali <bali@bytedance.com>
Co-authored-by: hunnnnngry <chenxi.xichen@bytedance.com>
Co-authored-by: shengdongyc <1135978761fsd@gmail.com>
Co-authored-by: fushengdong.1 <fushengdong.1@bytedance.com>
Block 1 — field completion: audio renders <audio key="..." duration="Xs"/>
(falls back to [Voice: Xs]/[Voice]); post renders emotion -> :emoji_type:,
applies text.style (bold/italic/underline/lineThrough), passes through md;
sticker unchanged.
Block 2 — opt-in --download-resources (default off) on +chat-messages-list,
+messages-mget, +threads-messages-list: extract downloadable resource refs
during formatting (image/file/audio/video/media + post-embedded; sticker
excluded; merge_forward sub-items carry the top-level container message_id,
since the resources endpoint rejects sub-item ids with "234003 File not in
msg" and can only fetch a forwarded resource through the container; thread
replies get their own block), then download each distinct (message_id,
file_key) once into ./lark-im-resources/ with bounded concurrency (3), filling
back local_path/size_bytes; single-resource failures are isolated (error:true +
stderr warning). Path safety reuses normalizeDownloadOutputPath +
ResolveSavePath.
Batch download keys each file on disk by its unique file_key basename and only
appends an extension (from the Content-Disposition filename or MIME type) —
it does NOT substitute the server's Content-Disposition filename. Otherwise two
resources whose servers return the same filename (e.g. download.bin) would
resolve to the same ./lark-im-resources/ path and clobber each other
concurrently. The friendly "adopt the server filename" behavior is kept only
for an explicit +messages-resources-download with no --output.
Resource ref extraction guards against self-referential / cyclic merge_forward
prefetch maps (a real API sub-item list can include the container's own id or a
back-pointing merge_forward) via a visited set, so extraction terminates instead
of overflowing the stack. The container message_id is threaded through nested
merge_forwards as the download owner.
Also: document the feature (including the im:message:readonly scope requirement)
in skills/lark-im — SKILL.md is generated from skill-template/domains/im.md
(edit the source), plus the hand-written message-enrichment + 3 command
references.
Change-Id: I3a71d7d1b193130f551aaa2ec180ac1500d59ac4
Meego: https://meego.larkoffice.com/5e96d7bff4e7c525510f9156/story/detail/7331555925
Emit structured validation, API, network, file, and internal error envelopes for Markdown shortcuts so users and agents can recover from failed markdown workflows using stable type, subtype, param, and code fields.
Add Markdown domain errscontract and golangci guards to prevent legacy envelope and common helper regressions.
Emit structured validation, API, network, file, and internal error envelopes for Slides shortcuts so users and agents can recover from failed presentation workflows using stable type, subtype, param, and code fields.
Add Slides domain errscontract and golangci guards to prevent legacy envelope and common helper regressions.
Emit structured validation, API, network, file, and internal error envelopes for Sheets shortcuts so users and agents can recover from failed spreadsheet workflows using stable type, subtype, param, and code fields.
Add Sheets domain errscontract and golangci guards to prevent legacy envelope and common helper regressions.
Emit structured validation, API, network, file, and internal error envelopes for Doc shortcuts so users and agents can recover from failed document workflows using stable type, subtype, param, and code fields.
Add Doc domain errscontract and golangci guards to prevent legacy envelope and common helper regressions.
+csv-put --csv data.csv (a forgotten @) was silently written as one-cell content, because any string parses as valid CSV — unlike malformed JSON it never errored, so the filename landed in the sheet instead of the file's contents.
+csv-put's Validate now rejects a --csv value when it names a real file in the cwd subtree (guardCSVValueIsNotFilePath; fileIO.Stat, fail-open), hinting to use --csv @file or stdin (--csv -). Scoped to --csv only — no framework or other-flag change. Checking real existence (not name shape) lets inline content that merely ends in a filename pass through. Adds TestGuardCSVValueIsNotFilePath.
`append` always inserts at document end (equiv. `block_insert_after --block-id -1`),
but skill docs previously recommended it for the "skeleton + chapter-by-chapter fill"
pattern, causing all content to pile up after the last heading.
Changes:
- Remove `append` from skeleton workflow guidance in `lark-doc-create-workflow.md`
and `lark-doc-create.md`; recommend `block_insert_after` with explicit `--block-id`
- Fix `block_move_after` required params: remove `--content` (not supported),
only `--block-id` and `--src-block-ids` are valid
- Add bash language tag to code block for proper highlighting
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.
slides +create finished by calling /drive/v1/metas/batch_query just to
fetch the presentation URL. That call needs a drive scope the shortcut
never declares, so it 403'd for users who only authorized slides scopes
(both UserAccessToken re-auth and TenantAccessToken scope-not-opened),
producing a large share of the shortcut's failure telemetry — even though
the presentation itself was already created successfully.
slides creation never otherwise touches drive, so rather than gating a
drive-free operation behind a drive scope, build the URL locally from the
token via common.BuildResourceURL (the same brand-standard-host fallback
already used by drive +upload / wiki +node-create). The URL is now always
returned, no extra scope is required, and creation never blocks.
Tests are updated to match: drop the registerBatchQueryStub helper and its
call sites (the httpmock Verify cleanup was failing on the now-unconsumed
batch_query stubs), point url assertions at the brand-standard host, and
replace TestSlidesCreateURLFetchBestEffort with TestSlidesCreateURLBuiltLocally,
which asserts the url is produced with no drive call registered.
* docs(approval): restructure skill with intent table and scope boundaries
Rewrite the description for intent-based routing (situation framing
instead of method enumeration) and add the lark-task disambiguation.
Replace the bare method list with an intent-to-command table including
topic and add_sign_type enums, document the query-to-operate workflow
chain with a runnable example, and add an out-of-scope section routing
definition creation to the Feishu client/admin console.
Bump version to 1.1.0.
Change-Id: I33b7b13b7855d67f40954701a09b115e3c91176c
* docs(approval): strengthen description coverage of edge actions
Restore the "all processing operations" phrasing so edge actions like
remind route to this skill; weak-model routing evals regressed on the
narrower "query and process" wording (2 misses in 4 runs vs 0 after
the fix).
Change-Id: Ica1928dacf879b6c7a46dfda37e35b1be9391432
* docs(approval): drop misleading 已发起 from tasks query row
tasks query 查的是本人作为审批人的任务；已发起（本人发起的实例）应走
instances initiated，该路径已在下方表行列出。移除 tasks query 的「已发起」
标签与 topic=3 枚举，避免 agent 误用 tasks query topic=3 查已发起。
Land the high-value, low-risk items from the skill-quality audit; SKILL.md only.
- description: drop the '接口通过 XML 协议通信' impl detail; append a 不负责
out-of-scope clause so 'make a deck' / 'draw a diagram' stop mis-routing.
- replace the 权限速查 scope table with a ## 不在本 skill 范围 routing table
(doc / whiteboard / drive / sheets / base).
- reconcile the whiteboard boundary with the in-slide <whiteboard> element
(added on main, #1029): lark-whiteboard owns only standalone whiteboard
objects in cloud docs; flow/architecture diagrams drawn inside a slide stay
in this skill via <whiteboard>. Clarified in description and out-of-scope note.
- defer auth / permissions / global params to lark-shared as single source.
- move native-API resource hint into prose; reword schema reminder; move the
'schema is source of truth' note next to 核心规则.
Deliberately not adopted: moving Design Ideas out of the body, relocating the
wiki-token section, dropping the native-API schema guardrail, and the bulk
lark-slides- reference rename.
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.
- Add explicit NOT boundaries to the description and a dedicated
"不在本 skill 范围" section: file upload -> lark-drive, content
editing -> lark-doc / lark-sheets / lark-base.
- Move the Shortcuts table up, right after 快速决策, so command entry
points are discoverable first; keep the member-add flow and
target-semantics sections after it.
- Add an inline reminder under the delete-space guidance that a wiki
URL / name is not a space_id and must be resolved via
`wiki spaces get_node` first.
- Remove the duplicated permission (scope) table and the redundant
schema note so auth/permission guidance stays centralized in
lark-shared.
- Bump the skill version to 1.0.1.
- Keep skill-template/domains/wiki.md in sync with the SKILL.md
introduction narrative.
Change-Id: If2b4341f350191ee0a65bf3a2cab9afa2b76d931
lark-cli update currently discovers official skills by parsing unstable human-oriented `skills add --list` output. This prefers the stable official JSON index for skills discovery, while preserving the existing CLI-list fallback and full-install fallback for resilience.
Changes:
- Add official skills index JSON parsing in `internal/skillscheck/sync.go`
- Prefer JSON index discovery before existing CLI list parsing in `internal/skillscheck/sync.go`
- Add reason-chain details when both discovery layers fall back to `fallbackFullInstall`
- Add bounded HTTPS fetch for `https://open.feishu.cn/.well-known/skills/index.json` in `internal/selfupdate/updater.go`
- Add unit tests for parser behavior, discovery fallback order, and fallback detail reasons in `internal/skillscheck/sync_test.go`
Co-authored-by: zhaoyukun.yk <zhaoyukun.yk@bytedance.com>
Task commands now return structured, typed errors instead of the legacy
exit-code envelope: every failure carries a stable category, subtype, and
recovery hint, so callers can branch on the error class instead of parsing
messages. Exit codes derive from the error category — input validation exits 2,
a permission denial exits 3, other API errors exit 1.
Batch operations (adding tasks to a tasklist, creating a tasklist with tasks)
now report partial failure honestly: the per-item successes and failures stay
on stdout and the command exits non-zero instead of masking failures as a
success.
The okr and whiteboard commands now report every failure as a typed error
envelope. Invalid flags, malformed input, output-file conflicts, and API or
transport failures alike carry a stable category, subtype, the offending flag
or Lark error code, and a meaningful exit code — so scripts and agents can
branch on the error shape instead of scraping message strings.
Wire the board.whiteboard.updated_v1 EventKey into the consume pipeline so that lark-cli event consume automatically calls the per-whiteboard subscribe / unsubscribe OAPIs instead of requiring callers to manage server-side subscriptions out-of-band.
Change-Id: I94323807e8dc649d3296f6922311d2acaf92284e
Adds feed shortcut management to the im domain: pin chats to the user's feed sidebar, list pinned entries, and unpin them. Three new shortcuts wrap the im/v2/feed_shortcuts OpenAPI routes, which currently expose CHAT-type entries only and accept user identity only.
Calendar commands now return structured, typed error envelopes for every
failure mode — input validation, internal faults, and API responses —
instead of legacy generic errors. Callers and AI agents get consistent
exit codes and a machine-readable shape (type / subtype / code / hint),
and can tell bad input, an internal fault, and an API rejection apart.
Validation errors are attributed to the offending flag.
Server-supplied error details (e.g. why an event time was rejected) are
surfaced on the typed error's hint via a shared classifier improvement
that benefits every domain. Multi-step operations (create-with-attendees
rollback, multi-field update) preserve the real failure's classification
and report which steps completed.
The whole calendar domain is now lint-locked against reintroducing legacy
error constructors.
The recommend.allow list in scope_overrides.json special-cased a set of
calendar/contact/mail scopes into the auto-approve set on top of the
platform recommendations in scope_priorities.json. Remove all entries so
no scopes are special-cased anymore; auto-approve now reflects only the
platform recommend=true scopes (plus the recommend.deny removals).
Update registry tests to use a recommend=true scope (sheets:spreadsheet:read)
as the auto-approve sample and assert the override allow set is empty.
Change-Id: Ic555a2c664e2dbd742f79712253f2918dfabf7ce
Validate the example commands embedded in shortcut definitions (the
"Example: lark-cli ..." lines in each shortcut's Tips, shown in --help)
against the real command tree built by cmd.Build. Implemented entirely as
test-only code in cmd/ (package cmd_test), so it ships in no binary and is
not importable by product code; the truth source is cmd.Build, the same
tree the binary uses, so the check cannot drift. It runs in the standard
unit-test CI job (go test ./cmd/...); a renamed command or unaccepted flag
in an example fails that job.
* feat(mail): return typed error envelopes across the mail domain
Replace every produced error path in shortcuts/mail with typed errs.* envelopes, so consumers get stable category, subtype, param/params, hint, retryable, and log_id metadata for classification and recovery instead of free-form message text.
- Locally constructed mail errors move from output.Err* / output.Errorf / final fmt.Errorf / common legacy helpers to errs.* builders, with structured params on multi-flag validation and failed-precondition states kept non-retryable.
- API-call failures move from runtime.CallAPI / DoAPIJSON legacy boundaries to runtime.CallAPITyped or runtime.ClassifyAPIResponse, and mail-specific enrichers read errs.ProblemOf so typed code, subtype, hint, and log_id metadata are preserved.
- Batch draft-send partial failures now use runtime.OutPartialFailure so successful and failed draft sends stay in stdout while the command exits through a typed multi-status signal.
- Add mail-domain typed helpers, mail API code metadata, and guard wiring to keep shortcuts/mail from reintroducing legacy envelopes or legacy API calls.
- Keep genuine intermediate fmt.Errorf wraps in parser/builder layers annotated with nolint comments; command-facing paths wrap them into typed validation, API, network, or internal errors.
* fix(mail): report aborted draft-send batches as a single failure result
When an account-level failure interrupts a batch send after some drafts
already went out, the command previously produced two machine-readable
failure results: the partial-failure ledger on stdout and a second error
envelope on stderr. Consumers could not tell which one to recover from.
The batch ledger is now the only failure result for that case: it gains
aborted and abort_error fields carrying the typed cause, so callers can
see which drafts were sent, which failed, why the batch stopped, and how
to recover — all from stdout. A --stop-on-error stop keeps these fields
unset because stopping early there is the caller's own choice.
When triaging a public/shared mailbox, downstream AI consumers (e.g.
mail +message) need the mailbox_id to construct correct API paths.
Previously the triage output only included message_id, causing
/user_mailboxes/me/messages/{id} lookups that fail for public mailboxes.
- Add mailbox_id field to every normalized message in structured output
- Add mailbox_id to top-level JSON/data output envelope
- Add mailbox_id to table rows when mailbox is not "me"
- Update stderr next-step tip to include --mailbox for non-me mailboxes
- Update next-page hint to include --mailbox for non-me mailboxes
- Add unit tests covering list, search, and public mailbox paths
- Update triage skill docs to show mailbox_id in output examples
* feat(slides): add whiteboard element support and reference documentation
- Add lark-slides-whiteboard.md covering SVG and Mermaid modes, routing
rules, layout examples, known issues, and self-check checklist
- Register <whiteboard> in slides_xml_schema_definition.xml; remove it
from the undefined element type list
- Update SKILL.md quick-reference table and按需再读 section to point to
the new whiteboard reference
- Update xml-schema-quick-ref.md with <whiteboard> syntax examples
- Update slide create/get/replace references to include whiteboard as a
valid <data> child element
- Tighten fallback_if_missing descriptions in planning-layer.md and
asset-planning.md: replace "shapes" wording with neutral intent
language and add "whiteboard diagrams" to the fallback tool lists
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs(slides): refine whiteboard reference doc structure and content
- Restructure doc: common attributes and prerequisites moved to top
- Move design quality rules under SVG mode section
- Add z-order inline note to full-screen layout example
- Replace JS coordinate script with Python, broaden scope to decorative elements
- Delete redundant Mermaid examples (keep one complete whiteboard+flowchart)
- Add prerequisite link and references section
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs(slides): clarify chart vs whiteboard selection and fix doc gaps
- lark-slides-whiteboard: add chart vs whiteboard decision table at top;
fix intro and SVG use-case list to remove bar/line (those belong to <chart>)
- SKILL.md: split whiteboard quick-ref row into chart row + whiteboard row;
fix sidebar link label to match actual scope
- asset-planning: correct chart asset type — remove funnel/scatter (unsupported
by <chart> XSD) and note they fall back to <whiteboard> SVG
- visual-planning: add one-line whiteboard preference hint to
architecture-diagram and process-flow layout types
- validation-checklist: add Whiteboard Elements section noting slide.get
does not return SVG/Mermaid content; content correctness requires manual
visual sign-off
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs(slides): add SVG decorative visibility principles
Add two design rules to SVG quality requirements: check background
luminance before writing SVG (dark bg requires higher contrast), and
use non-linear brightness jumps (e.g. 0.10→0.40→0.70→1.0) instead of
linear opacity stacking (0.04→0.08→0.12) which produces near-identical
layers on dark backgrounds.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs(slides): add custom icon use case to whiteboard SVG
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs(slides): fix whiteboard SVG rendering rules
- content area is determined by child element bounding box union, not svg width/height/viewBox/xmlns
- viewBox only purpose: provide reference for percentage-based attribute values; omit when using absolute coords
- remove redundant attributes from all svg examples, use bare <svg> tags
- drop positive/negative coordinate guidance; rendering rule simplified to bounding-box auto-scale
* feat(lark-contact): route user_profiles batch_query in skill
- Add user_profiles batch_query row to the routing table.
- Add a worked example next to the search-user one, with `lark-cli
schema` first (best practice: don't guess `--data` / `--params`).
- Trim description: drop the duplicated trigger clause, add
personal_status / signature to the capability list so routing picks
this skill up for those queries.
* refactor(sheets): rebuild lark-sheets on sheet-skill-spec canonical + One-OpenAPI
Restart lark-sheets as a spec-driven downstream. Skill content (SKILL.md
and 16 references covering 13 operations skills + 3 workflow skills,
including the standalone filter-view skill) is mirrored from the
sheet-skill-spec canonical-spec; do not hand-edit, change upstream and
rerun npm run sync:consumers.
Drop the 11 legacy shortcut sources (spreadsheet / sheet management,
cell ops, dropdown, filter-view, float image, etc.) and 10 associated
tests. Wire up the new sheet_ai/v2 One-OpenAPI single entry that
dispatches by tool_name with JSON-string input/output, and land the
first canonical shortcut +workbook-info as a template that exercises
the public token XOR pair, Risk tiering, and zero-side-effect DryRun.
sheet_ai_api.go provides callTool / invokeToolDryRun and bypasses
runtime.CallAPI's silent swallowing of non-envelope responses so
gateway and business errors from the new endpoint surface precisely.
The remaining 55 shortcuts will be designed and landed separately,
canonical skill by canonical skill.
* feat(sheets): implement lark_sheet_workbook shortcuts (B1)
Land the 8 modify_workbook_structure shortcuts that round out the
lark_sheet_workbook canonical skill alongside the existing +workbook-info:
+sheet-create / +sheet-delete / +sheet-rename / +sheet-move / +sheet-copy
/ +sheet-hide / +sheet-unhide / +sheet-set-tab-color. All eight call
modify_workbook_structure via the One-OpenAPI invoke_write endpoint,
dispatched by the `operation` enum.
Helpers in helpers.go grow publicSheetFlags() / resolveSheetSelector() /
sheetSelectorForToolInput() / sheetSelectorPlaceholder() so future
sheet-level shortcuts share the public --sheet-id / --sheet-name XOR
treatment. +sheet-create intentionally drops the sheet selector pair since
create has no existing-sheet anchor (matches the spec fix in
tool-shortcut-map.json).
+sheet-delete is the first high-risk-write shortcut in the canonical
package; the framework requires --yes (exit code 10 otherwise).
+sheet-move's tool requires source_index in addition to target_index. The
CLI accepts an optional --source-index override and falls back to a
single get_workbook_structure read to derive it (and to resolve sheet_id
from --sheet-name). DryRun stays network-free by rendering <resolve>
placeholders for any field that would need that read.
* feat(sheets): implement lark_sheet_sheet_structure shortcuts (B2)
Add 8 shortcuts under the lark_sheet_sheet_structure canonical skill:
+sheet-info (get_sheet_structure) plus +dim-insert / +dim-delete /
+dim-hide / +dim-unhide / +dim-freeze / +dim-group / +dim-ungroup
(modify_sheet_structure, dispatched by operation enum).
Two reusable conversion helpers cover the impedance mismatch between
the CLI surface and the tool input:
- dimRange / dimPosition translate the CLI's 0-based exclusive-end
range into the tool's 1-based A1 notation. row 5..8 becomes
position "6" + count 3 (insert) or range "6:8" (range ops); column
26..29 becomes "AA:AC".
- infoTypeFromInclude maps the fine-grained --include vocabulary
(row_heights / col_widths / merges / hidden_rows / hidden_cols /
groups / frozen) to the coarse info_type enum the tool accepts;
mixed categories collapse to "all".
+dim-delete is high-risk-write (irreversible row/column removal).
+dim-freeze --count 0 auto-dispatches to operation=unfreeze. +dim-group
accepts --depth for forward-compat with a future server-side nested
group endpoint but does not pass it through today.
* feat(sheets): implement read_data / search_replace / write_cells shortcuts (B3)
Land 11 shortcuts across three canonical skills:
- lark_sheet_read_data (3): +cells-get / +csv-get / +dropdown-get
- lark_sheet_search_replace (2): +cells-search / +cells-replace
- lark_sheet_write_cells (6): +cells-set / +cells-set-style / +csv-put
/ +dropdown-set / +dropdown-update / +dropdown-delete
+dropdown-get reads the data_validation field via get_cell_ranges with
the range carrying its own sheet prefix (no --sheet-id needed). The
fine-grained --include vocabulary (value / formula / style / comment /
data_validation) maps to the tool's coarse include_styles bool plus
value_render_option enum. +csv-get's --include-row-prefix=false strips
the [row=N] prefix client-side because the tool only emits the
annotated form.
+cells-search / +cells-replace flatten the tool's options sub-object
into four independent flags (--match-case / --match-entire-cell /
--regex / --include-formulas) per the flat-flag rule, then repack them on the way
in.
+cells-set takes a raw --data JSON body whose `cells` array must match
the --range dimensions. +cells-set-style fans a single --style block
out to every cell in the range via a new fillCellsMatrix helper; the
range parser (rangeDimensions / splitCellRef / letterToColumnIndex)
only accepts rectangular A1:B2 forms — whole-column / whole-row need
sheet totals and are deferred.
+dropdown-set fans the validation block out to one range; +dropdown-
update / +dropdown-delete iterate sheet-prefixed --ranges and call
set_cell_range sequentially (partial failure leaves earlier ranges
already mutated; the Tip calls this out). +dropdown-delete is
high-risk-write and requires --yes.
+cells-set-image stays deferred to the cli-only batch (needs the
shared local-file upload helper alongside +workbook-create / +dim-move
/ +workbook-export).
* refactor(sheets): move +dropdown-update / +dropdown-delete to lark_sheet_batch_update
Follow-up to B3 after the spec re-mapped these two shortcuts to the
batch_update tool (atomic multi-range CRUD) instead of fan-out via
set_cell_range. Drop their Go implementations + helper validateDropdownRanges
+ splitSheetPrefixedRange from lark_sheet_write_cells.go and remove the
registrations from Shortcuts(); the shortcuts will reappear under
lark_sheet_batch_update during B7.
Also pull in the re-rendered reference docs:
- skills/lark-sheets/references/lark-sheets-write-cells.md
- skills/lark-sheets/references/lark-sheets-batch-update.md
* feat(sheets): implement lark_sheet_range_operations shortcuts (B4)
Land 8 shortcuts across four canonical tools:
- clear_cell_range → +cells-clear (high-risk-write)
- merge_cells → +cells-merge / +cells-unmerge
- resize_range → +dim-resize
- transform_range → +range-move / +range-copy / +range-fill / +range-sort
Three CLI↔tool vocabulary bridges live in this file:
- +cells-clear: --scope content normalizes to the tool's clear_type
"contents" (singular/plural spec mismatch is absorbed in the CLI).
- +dim-resize: --size <px> wraps as resize_{height,width}:{value:N};
--reset wraps as {reset:true}. The two flags are mutually exclusive
and at least one is required.
- +range-fill: CLI's five-valued --series-type collapses to the tool's
binary fill_type — `copy` → "copyCells", anything else → "fillSeries"
(the actual series progression is inferred server-side from the
seed cells in --source-range).
- +range-copy: --paste-type {values, formulas, formats} maps to the
tool's {value_only, formula_only, format_only}; "all" omits the
field entirely so the server applies its default.
+cells-clear is the second high-risk-write shortcut in the package;
the framework enforces --yes with exit code 10 as usual.
* feat(sheets): implement object-list shortcuts (B5)
Land 7 read shortcuts, one per object skill — chart / pivot table /
conditional format / filter / filter view / sparkline / float image. All
share the same shape (public sheet selector + optional <obj>-id filter)
so they're declared via newObjectListShortcut + an objectListSpec.
Notes:
- +cond-format-list exposes --rule-id, which is renamed to
conditional_format_id on the wire (the tool's full field name).
- +sparkline-list exposes --group-id (the higher-level handle); the
tool also accepts sparkline_id, intentionally not surfaced.
- +filter-list takes no id filter — at most one sheet-level filter
per sheet, so the listing is already unique.
- +filter-view-list is `cli_status: cli-only` but get_filter_view_objects
is in mcp-tools.json and dispatches through the same One-OpenAPI
endpoint; no special path required.
* feat(sheets): implement object CRUD shortcuts (B6)
Land 21 shortcuts — three (create / update / delete) per object skill —
backed by the manage_<obj>_object tools dispatched on the operation
enum. Five standard objects (chart / cond-format / sparkline /
float-image / filter-view) share an objectCRUDSpec factory; pivot and
filter are special-cased.
Shared wire contract:
excel_id + sheet_id|sheet_name + operation + [<obj>_id] + [properties]
CLI --data is passed through as the tool's `properties` field as-is, so
callers shape it per each object's spec doc.
Special cases:
- pivot adds optional --target-sheet-id / --target-position on create
(siblings of properties, not inside it).
- cond-format exposes --rule-id (short CLI name) wired to the tool's
conditional_format_id on the wire.
- sparkline uses --group-id (higher-level object handle) instead of
sparkline_id.
- filter has no separate id flag — at most one filter per sheet, so
filter_id is implicit. +filter-create promotes --range to a first-
class flag (instead of burying it inside --data).
- filter-view CRUD are `cli_status: cli-only` but
manage_filter_view_object is in mcp-tools.json, so they go through
callTool / One-OpenAPI alongside everything else.
All delete shortcuts are high-risk-write and require --yes.
* feat(sheets): implement lark_sheet_batch_update shortcuts (B7)
Land 4 shortcuts that all funnel through the batch_update tool's atomic
operations array:
- +batch-update raw passthrough; --data carries the full
{ operations: [{tool, params}, ...] } payload
plus optional continue_on_error. high-risk-write
since the caller may stuff anything inside.
- +cells-batch-set-style --data is [{ranges, style}, ...]; CLI flattens
each (entry × range) pair into a set_cell_range
op with a fan-out cells matrix carrying
cell_styles + border_styles.
- +dropdown-update --ranges + --options (+ --colors / --multiple /
--highlight) — installs/replaces one dropdown
across many ranges, each becoming a separate
set_cell_range op with data_validation in cells.
- +dropdown-delete --ranges — clears data_validation across many
ranges (high-risk-write).
Default is strict transaction: if any sub-tool fails the whole batch rolls
back. +batch-update exposes --continue-on-error to flip the policy; the
three fan-out shortcuts leave it strict (they're meant to be all-or-nothing).
Reinstates validateDropdownRanges + splitSheetPrefixedRange that were
removed during B3 → B7 relocation.
* feat(sheets): implement cli-only shortcuts (B8) — 70/70 complete
Land the four cli-only shortcuts that can't route through the One-OpenAPI
dispatcher (their backing capabilities aren't in mcp-tools.json):
- +workbook-create POST /open-apis/sheets/v3/spreadsheets
+ optional set_cell_range follow-up that zips
--headers and --data into the first sheet starting
at A1.
- +workbook-export POST /open-apis/drive/v1/export_tasks (type=sheet)
→ poll /export_tasks/:ticket up to ~30s
→ optional GET /export_tasks/file/:file_token/download.
CSV mode requires --sheet-id (single sheet export).
- +dim-move POST /open-apis/sheets/v2/spreadsheets/:token
/dimension_range
CLI is 0-indexed inclusive (--start / --end); the v2
endpoint expects half-open [startIndex, endIndex)
so the body uses endIndex = --end + 1. --sheet-name
is resolved client-side to sheet_id via
lookupSheetIndex when needed.
- +cells-set-image common.UploadDriveMediaAll
(parent_type=sheet_image, parent_node=token)
then callTool set_cell_range with cells carrying
rich_text: [{type:"embed-image", attachment_token, attachment_name}].
--range must be exactly one cell.
All four use runtime.CallAPI / DoAPI directly; only +cells-set-image
combines a legacy upload with the new One-OpenAPI for the second step
(set_cell_range is in mcp-tools.json so callTool is the right path).
This closes the migration: 70 shortcuts × 17 canonical skills × matching
the sheet-skill-spec v0.5.0 tool-shortcut-map.
* test(sheets): cover all 70 shortcuts with dry-run + execute-path tests
Twelve _test.go files alongside the implementation, mirroring the legacy
package's coverage style:
- testhelpers_test.go shared rig: TestFactory + Mount + dry-run
capture + JSON-input decode + envelope helpers.
- lark_sheet_*_test.go one test file per implementation file (9
files), table-driven dry-run cases per shortcut
plus targeted validation guards.
- execute_paths_test.go end-to-end execute paths via httpmock stubs.
Covers callTool unwrap, JSON-string output
decoding, two-step lookup (+sheet-move),
batch_update fan-out, dropdown atomic writes,
and the legacy OAPI shortcuts (+workbook-create,
+dim-move) including CLI inclusive → API
half-open index conversion.
Test coverage on the sheets package is 60.5 % of statements with -race
clean, meeting the dev manual's ≥ 60 % patch-coverage gate.
* refactor(sheets): inline cli-only shortcuts into their canonical skill files
Two naming cleanups:
- lark_sheet_cli_only.go is gone. The four shortcuts it grouped
(+workbook-create / +workbook-export / +dim-move / +cells-set-image)
were bundled by their implementation pattern (legacy OAPI direct
calls) rather than by canonical skill. The whole sheets package IS
the CLI implementation, so "cli only" wasn't a meaningful grouping
at the Go layer. Each shortcut now lives next to its skill peers:
+workbook-create / +workbook-export → lark_sheet_workbook.go
+dim-move → lark_sheet_sheet_structure.go
+cells-set-image → lark_sheet_write_cells.go
Per-skill shortcut counts now match tool-shortcut-map.json exactly
(workbook: 11, sheet_structure: 9, write_cells: 5). Helpers
(buildInitialFillInput, pollExportTask, downloadExportFile,
dimMoveBody) move with their shortcuts; nothing else in the package
referenced them.
- testhelpers_test.go → helpers_test.go. The _test.go suffix already
conveys "test"; the leading "test" was redundant. Matches the
helpers.go naming convention.
Behavior unchanged. go test -race -cover stays at 60.5 %.
* refactor(sheets): sync shortcut flags with sheet-skill-spec v0.5.0
Upstream hoisted a batch of high-frequency scalar fields out of --data
into independent flags and renamed several composite-JSON flags to
match their semantic content. CLI catches up.
Renames (drop-in, same payload semantics):
- +cells-replace --replace → --replacement
- +cells-set --data → --cells
- +workbook-create --data → --values
- +batch-update --data → --operations (now a bare array;
still accepts the envelope form for
back-compat with continue_on_error)
Flat-flag hoists out of --style / --data:
- +cells-set-style / +cells-batch-set-style
--style JSON drops; replaced by 11 flat style flags
(--background-color / --font-color / --font-size / --font-style /
--font-weight / --font-line / --horizontal-alignment /
--vertical-alignment / --word-wrap / --number-format) plus
--border-styles for the one field that's still nested. Both
shortcuts share styleFlatFlags() + buildCellStyleFromFlags().
- +cells-batch-set-style also drops the [{ranges, style}] array shape
in favor of one --ranges + the same flat style flags applied to
all of them.
Object CRUD --data → --properties everywhere (chart / pivot / cond-format
/ filter / filter-view / sparkline / float-image). Per-skill scalar
hoists merged into properties via an enhanceCreate/UpdateInput callback:
- +pivot-create adds --source (required), --range
(and continues to expose --target-sheet-id /
--target-position at top level)
- +cond-format-{create,update}
adds --rule-type (enum) + --ranges (JSON array);
merged into properties.rule.type and
properties.ranges respectively
- +filter-view-{create,update}
adds --view-name and --range; both override
their properties.* counterparts
- +filter-update adds first-class --range (was buried in --data)
Float-image is fully hoisted — no --properties flag at all. Ten flat
flags (--image-name / --image-token | --image-uri / --position-row /
--position-col / --size-width / --size-height / --offset-row /
--offset-col / --z-index) compose the properties block. Implemented as
its own factory (newFloatImageWriteShortcut) since it diverges from the
shared CRUD spec.
Tests track every flag renamed and add explicit cases for the new flag
combos. go test -race -cover stays at 60.3 %.
* refactor(sheets): align batch_update + cells-set with synced reference docs
Sync to upstream reference doc updates for 9 skills:
- batch_update sub-ops: rewrite wire fields tool/params -> tool_name/input
in CellsBatchSetStyle and DropdownUpdate/Delete fan-out (the actual
server contract per Schemas section); update --operations flag desc
and tests.
- +cells-set --cells: accept bare 2D matrix [[{cell},...],...] instead
of envelope {"cells":[[...]]}; spec example shows bare-array form.
- sparkline createDataDesc enum: win_loss -> winLoss (camelCase).
All other doc changes (float-image flat flags, cond-format
--rule-type/--ranges, pivot create-only --source/--range, filter /
filter-view extra flags, chart --properties) were already aligned in
commit ce33315.
* fix(sheets): repair cells-set-image rich_text embed payload
The server rejected set_cell_range calls from +cells-set-image with three
distinct errors: missing "text" property, missing image_width/image_height,
and unknown attachment_token field. Realign the rich_text element to the
embed-image schema (text/image_token/image_width/image_height) and decode
PNG/JPEG/GIF dimensions from the local file before the write.
* refactor(sheets)!: split +dim-resize into +rows-resize and +cols-resize
Sync to upstream spec change that splits the legacy +dim-resize shortcut
into +rows-resize and +cols-resize. Reasoning is that row vs column
resize has divergent semantics (only rows support auto-fit) and the
shared --dimension flag was hiding that.
Behavior changes (BREAKING):
- +dim-resize is removed; use +rows-resize or +cols-resize.
- --dimension and --reset flags are gone.
- --type enum replaces --size/--reset:
pixel (requires --size)
standard (reset to sheet default; no --size)
auto (auto-fit row height; +rows-resize only)
- --end is now inclusive (was exclusive). Old "--start 0 --end 5"
(5 rows) becomes "--start 0 --end 4".
- Wire payload for resize_height / resize_width changes from
{value: N} | {reset: true} to {type: "pixel", value: N} |
{type: "standard"} | {type: "auto"}.
Tests cover both shortcuts across pixel / standard / auto and the
new guard surface (--type pixel needs --size; standard/auto reject
--size; +cols-resize rejects --type auto; --end < --start).
Also pulls in synced reference docs for 5 skills (batch-update,
core-operations, range-operations, sheet-structure, visual-standards)
that update prose mentions of +dim-resize.
* feat(sheets): add --print-schema runtime introspection for composite JSON flags
Composite JSON flags (--cells / --properties / --operations /
--border-styles / --sort-keys / --options) carry non-trivial structured
payloads. Reference docs cover top-level fields but agents writing
those flags often need the full JSON Schema to build a valid payload.
This adds a system-level introspection contract so any shortcut whose
flags are tracked upstream can serve its schemas locally:
lark-cli sheets <shortcut> --print-schema --flag-name <name>
lark-cli sheets <shortcut> --print-schema # list flags
The schema data is embedded at build time from a synced artifact
(shortcuts/sheets/data/flag-schemas.json). Upstream is the source of
truth — never hand-edit the JSON; update the source Base table and
rerun the sheet-skill-spec sync.
Framework changes (shortcuts/common):
- types.go: Shortcut gains an opt-in PrintFlagSchema hook
(flagName -> bytes/error). When non-nil the framework auto-injects
--print-schema / --flag-name and short-circuits Validate/Execute.
- runner.go: register the two system flags when PrintFlagSchema is
set; intercept in runShortcut before identity/scope/config so
pure-local lookups don't trigger auth or network. Install a
PreRunE that relaxes cobra's required-flag gate when
--print-schema is set, since asking for a schema shouldn't need
unrelated required flags.
Sheets surface (shortcuts/sheets):
- flag_schema.go (new): go:embed data/flag-schemas.json; expose
printFlagSchemaFor(command) closure. When flagName is empty it
emits a JSON listing of introspectable flags for discovery;
otherwise it returns the schema subtree as pretty JSON.
- flag_schema_test.go (new): cover embed parsing, listing /
by-name lookup, unknown-flag error path, registration via
Shortcuts(), and the full system-flag short-circuit through
cobra (required flags relaxed, schema printed on stdout).
- shortcuts.go: Shortcuts() now wraps shortcutList() and attaches
PrintFlagSchema to every command present in flag-schemas.json,
so shortcuts opt in by being listed upstream — no per-shortcut
boilerplate.
- data/flag-schemas.json (new, synced from sheet-skill-spec):
19 entries, schema_version "2". Generated upstream from the Lark
Base source-of-truth (see sheet-skill-spec
scripts/fetch_cli_flag_schema_map.mjs); ships only per-flag
subtrees (not the full mcp-tools.json) to keep tool internals
out of the open-source repo.
Skill docs (skills/lark-sheets):
- SKILL.md: system-flag table gains --print-schema / --flag-name and
an "Agent 使用提示" note steering agents to prefer --print-schema
over guessing JSON shape from the cheatsheet.
- references/*.md: regenerated by upstream sync (Schemas-section
boilerplate updated, plus accumulated upstream prose refinements).
* docs(sheets): remove sandbox references and normalize tool names to CLI shortcuts
Replace export_sheet_to_sandbox / import_sandbox_to_sheet / doubao_code_interpreter
with local-script + batch csv-get/csv-put workflows; unify legacy MCP tool names
(set_cell_range, get_range_as_csv, etc.) to CLI shortcut format (+cells-set, +csv-get).
* feat(sheets): add flag-descriptions.en.json and wire applyFlagDescs into Shortcuts()
Embed data/flag-descriptions.en.json (synced from upstream spec) and
apply it at shortcut assembly time so every Flag.Desc is sourced from
the canonical JSON rather than hardcoded Go strings. Existing hardcoded
Desc values serve as fallback for flags not yet in the JSON.
Also sync reference doc updates from upstream.
* feat(shortcuts): support int64 and float64 flag types
Flag.Type previously could not express non-integer numbers. Add int64
and float64 cases to flag registration plus Int64/Float64 runtime
accessors.
* refactor(sheets): build shortcut flags generically from flag-defs.json
Replace flag-descriptions.en.json with the richer flag-defs.json (full
flag definitions: type / default / enum / input / hidden / required /
kind) synced from sheet-skill-spec. Add flagsFor(command) to materialize
each shortcut's []common.Flag straight from the JSON, skipping
system-kind flags the framework injects.
Migrate every sheets shortcut (including the CRUD/list/dim/merge/
visibility factories) to Flags: flagsFor("+command"), dropping all
hand-written flag literals plus the now-dead publicTokenFlags /
publicSheetFlags / styleFlatFlags helpers and enum vars. A coverage test
locks the Go-flags-match-JSON contract.
Align Go with the new spec where they diverged: +cells-get --ranges →
--range, font-size int → float64, +filter-view-create --range now
required, +sheet-create row/col-count defaults 200/20.
* docs(sheets): sync +batch-update CLI override schema (shortcut/input form)
Pulled from sheet-skill-spec:
- skills/lark-sheets/references/lark-sheets-batch-update.md: --operations
now documents the {shortcut, input} form; tool_name references gone
- shortcuts/sheets/data/flag-schemas.json: --operations resolves to the
CLI-side array<{shortcut(enum), input}> schema, sourced from spec's
canonical-spec/tool-schemas/cli-schemas.json (cli: prefix). +dropdown
--options also drilled one level deeper
NOTE: the binary still raw-passes --operations to MCP batch_update which
expects {tool_name, input}. A follow-up will add a shortcut→tool_name
translation layer (with per-shortcut operation field) before the docs
become actionable.
* feat(sheets): translate +batch-update sub-ops {shortcut,input} → MCP shape
Users now hand +batch-update --operations a CLI-shape array
([{shortcut, input}, ...]) and the binary translates each sub-op to the
underlying MCP batch_update shape ({tool_name, input(+operation)}) via
a new dispatch table in shortcuts/sheets/batch_op_dispatch.go.
Dispatch table covers 50 batchable write shortcuts. Excluded by design:
- all read ops
- fan-out wrappers (+batch-update self, +cells-batch-set-style,
+dropdown-update, +dropdown-delete) — nesting these = nested batch
- +dim-move — single shortcut uses legacy v2 /dimension_range endpoint,
not MCP, can't be batched
- +cells-set-image — multi-step image upload, not atomic-batch friendly
- +workbook-create — new workbook, not batch-on-existing semantics
Translator also rejects sub-ops that hand-fill input.operation (implied
by shortcut name) or input.excel_id / spreadsheet_token / url (set
once at +batch-update top level).
+dim-freeze always injects operation=freeze; the count==0 unfreeze
path of the single shortcut is intentionally not supported in batch —
callers should use the single shortcut for unfreeze.
Tests cover: end-to-end translation, --continue-on-error propagation,
13 rejection cases (banned shortcuts, malformed shapes, reserved keys).
Sync'd from sheet-skill-spec: skills/lark-sheets/references/
lark-sheets-batch-update.md + shortcuts/sheets/data/flag-schemas.json
pick up the corrected enum (+cells-set-style / +dropdown-set added,
+dim-move removed).
* fix(sheets): make +batch-update sub-ops reuse standalone flag→body translators
Sub-ops previously near-passed-through their input, so any shortcut whose
standalone translator renames fields broke inside a batch: +range-copy lost
range/destination_range (transform_range errored "range missing") and
+rows-resize lost range/resize_height ("No resize operation specified").
Introduce a flagView interface (satisfied by *common.RuntimeContext) and a
map-backed mapFlagView, then route every batchable sub-op through the SAME
*Input builder the standalone shortcut uses. mapFlagView seeds flag-defs.json
defaults for value reads while keeping Changed() user-driven, so a sub-op body
is byte-identical to the standalone body — locked by a batch-vs-standalone
contract test over all ~40 batchable shortcuts.
Also fix single-row/column resize: start==end now formats as "23:23" / "C:C"
(resize_range rejects a bare "23"); dimRangeFull keeps both sides while
dimRange's collapse stays for modify_sheet_structure consumers.
* fix(sheets): align +cells-get/+csv-get range flags with synced spec
sheet-skill-spec now declares +cells-get --range as a single string
(was string_array) and +csv-get --range as required. Match the
flag→body translators:
- +cells-get wraps the single --range into the tool's `ranges` array
and validates with Str() instead of StrArray(), which silently
returned nil against the now-String flag and broke the command.
- +csv-get gains a trim-based required-range guard.
Update read-data dry-run tests to single-range form and add a guard
test for the empty --range path.
* fix(sheets): push +batch-update sub-op validation down into xxxInput builders
Sub-ops that omit --sheet-id (or any other required flag) used to slip
past CLI validation — Validate ran only against the standalone shortcut
path, and batchOpDispatch's translators built bodies from whatever
flagView returned, so a structurally broken sub-op surfaced as an opaque
server "sheet undefined not found" after a network round-trip.
Push each batchable shortcut's check trio down into its xxxInput builder:
1. resolveSpreadsheetToken — stays in Validate (batch already does it
once at the top level; sub-ops don't repeat).
2. requireSheetSelector(sheetID, sheetName) — new helper; flagView-
agnostic XOR + control-char check, called at the top of every
xxxInput.
3. shortcut-specific required / range / enum checks (--dimension,
--range, --start <= --end, --type pixel needs --size,
--float-image-id, image-token XOR image-uri, ...) — moved out of
Validate into the builder body.
All ~30 batchable xxxInput builders now return (map, error). Standalone
Validate shrinks to validateViaInput(xxxInput); DryRun / Execute
propagate the error. batch_op_dispatch entries drop the noErrTranslate
wrapper and pass the builder directly — its error bubbles up wrapped
with "operations[N] (+shortcut):" context.
Tests:
- TestBatchOp_ErrorEquivalence (7 cases): XOR / logical-constraint
errors fire identically from standalone and batch sub-op paths.
- TestBatchOp_RejectsBadSubOpInput (8 cases): cobra-required flags that
standalone catches via MarkFlagRequired now also get rejected CLI-side
on the batch path (where cobra is not in the loop).
- TestBatchOp_BodyMatchesStandalone (~40 cases) and
TestBatchOp_DispatchCoversReportedBugs continue to pass — bodies stay
byte-identical.
- BOE smoke (spreadsheet ICFwstkUGheyfptGWS2bB7RgcDf, sheet 51991c):
+batch-update with a sub-op missing --sheet-id now returns
"operations[0] (+dim-insert): specify at least one of --sheet-id or
--sheet-name" before any network call.
sheetMoveBatchInput (xiongyuanwen's batch-only explicit-source-index
requirement) is preserved — it's an orthogonal batch-specific constraint
not affected by this push-down.
* fix(sheets): align +cond-format / +filter with server schema (#4 + #5)
Two latent bugs in the object_crud translator surfaced during BOE smoke
testing of +batch-update. Both are schema-alignment fixes against
manage_conditional_format_object / manage_filter_object as declared in
sheet-skill-spec/canonical-spec/tool-schemas/mcp-tools.json.
#4 +cond-format: rule_type path + enum vocabulary
---------------------------------------------------
condFormatEnhance used to write the user's --rule-type value into
`properties.rule.type` (nested under a `rule` object). The server
schema actually puts it at flat `properties.rule_type` and silently
drops the nested form — so every conditional-format create/update
secretly built the wrong document.
Worse, the CLI enum exposed via flag-defs.json was its own invented
vocabulary (cellValue / formula / duplicate / unique / topBottom /
aboveBelowAverage / dataBar / colorScale / iconSet / textContains /
dateOccurring / blankCell / errorCell) — none of those values were
the strings the server accepts.
Fix:
- condFormatEnhance now writes `properties.rule_type = <value>`
directly (no nested `rule` object).
- Synced flag-defs.json + lark-sheets-conditional-format.md enum
vocabulary from base to match the server: duplicateValues,
uniqueValues, cellIs, containsText, timePeriod, containsBlanks,
notContainsBlanks, dataBar, colorScale, rank, aboveAverage,
expression, iconSet.
- ⚠️ Breaking: scripts passing the old CLI-invented enum values
(e.g. --rule-type cellValue) now get a cobra "invalid value …
allowed: …" error listing the new vocabulary. No alias layer.
- TestObjectCRUDShortcuts_DryRun's +cond-format-update case updated
to assert the flat properties.rule_type shape + new enum.
#5 +filter-{update,delete}: auto-inject filter_id = sheet_id
-------------------------------------------------------------
manage_filter_object's contract is "filter_id === sheet_id" for the
sheet-scoped filter (per per-tool description in mcp-tools.json),
and update / delete operations MUST carry filter_id. Standalone
filterUpdateInput / filterDeleteInput never set it, so the server
rejected with "filter_id is required for update/delete operation"
on every call — both standalone AND inside +batch-update.
Fix:
- filterUpdateInput / filterDeleteInput now set
input["filter_id"] = sheetID.
- Because filter_id must equal sheet_id (not sheet_name), update /
delete reject when only --sheet-name is given — there's no
network lookup available inside the builder. The friendly error
points at +workbook-info for resolving sheet-name → sheet-id.
- create still omits filter_id (server requires that — id is
server-allocated on creation).
- New tests:
* TestObjectCRUDShortcuts_DryRun gains a +filter-update happy-path
case asserting filter_id is auto-injected + --range hoisting.
* +filter-delete case updated to assert filter_id presence.
* TestBatchOp_RejectsBadSubOpInput gains two cases asserting both
+filter-update and +filter-delete reject --sheet-name-only with
the friendly error.
Docs (#2 + #3 + #8) synced from sheet-skill-spec
-------------------------------------------------
Companion doc fixes that landed via npm run generate:cli + sync:cli
in sheet-skill-spec; included here because the regenerated flag-defs
and references markdown are byte-tracked in this repo:
- #2: lark-sheets-sheet-structure.md — +dim-{hide,unhide,group,
ungroup} --start/--end desc changed from "(0-based, inclusive)" to
"(0-based)" / "(exclusive)" to match the half-open range semantics
the code has always implemented (requireDimRange: end > start;
dimRange uses end - 1 for column end letters).
- #3: lark-sheets-workbook.md — +sheet-move section gains a note
about the batch-internal requirement to pass --sheet-id AND
--source-index explicitly (sheetMoveBatchInput's constraint).
- #8: lark-sheets-pivot-table.md — +pivot-create --properties
example drops the stale data_range field (the actual server
schema uses --source as a hoisted flag; properties only carries
rows / columns / values / filters / show_*_grand_total).
* feat(sheets): add +cells-batch-clear fan-out over batch_update
Clear content/formats across many sheet-prefixed ranges in a single atomic
batch_update (one clear_cell_range op per range), mirroring the existing
+cells-batch-set-style / +dropdown-{update,delete} fan-out wrappers. The
--scope to clear_type normalization is shared with standalone +cells-clear
(normalizeClearType) so the two stay in lockstep.
high-risk-write (requires --yes); rejected as a batch sub-op like the other
fan-out wrappers. flag-defs/flag-schemas and skill docs updated to match.
* docs(sheets): sync stdin guidance and sparkline reference
- skills/lark-shared/SKILL.md: drop the generic "prefer stdin" section
- skills/lark-sheets/SKILL.md: add expanded stdin guidance (use stdin over @file abs paths; don't cd or write into the project dir)
- skills/lark-sheets/references/lark-sheets-sparkline.md: document the group_id / sparkline_id two-tier model with worked examples
* fix(sheets): require sparkline_id on +sparkline-update items (#6)
manage_sparkline_object uses two layers of IDs: --group-id picks the
sparkline group, and properties.sparklines[i].sparkline_id picks each
item inside the group. The server contract requires sparkline_id on
every update item (server maps each entry back to an existing
sparkline by this id). Agents that called +sparkline-update without
the per-item ids hit an opaque server-side rejection that didn't
mention sparkline_id at all, then got stuck in a try-fail-list-retry
loop.
Pre-check CLI-side in objectUpdateInput via a new validateUpdateInput
hook on objectCRUDSpec. sparklineSpec wires validateSparklineUpdateItems,
which walks properties.sparklines[] and rejects with a message that
points at +sparkline-list:
+sparkline-update properties.sparklines[N] missing sparkline_id
(run `+sparkline-list --group-id <id>` first to read sparkline_id
for each item, then echo each id back on the corresponding update
entry)
Scope is update-only. config-only updates (properties.config without
sparklines) stay legal — the validator skips when sparklines is
absent. Delete is not pre-checked: objectDeleteInput doesn't pass
properties through, so the partial-delete branch can't be reached
today (separate follow-up).
Tests:
- TestObjectCRUDShortcuts_DryRun: positive case for update with
sparkline_id present.
- TestSparklineUpdate_MissingSparklineID: standalone path — error
contains both "missing sparkline_id" and "+sparkline-list".
- TestBatchOp_RejectsBadSubOpInput: batch sub-op missing sparkline_id
rejected with the same friendly error.
Docs synced from sheet-skill-spec (canonical change committed there):
skills/lark-sheets/references/lark-sheets-sparkline.md documents the
two-layer id model, the three "+sparkline-list first" cases, and both
delete modes.
* docs(sheets): sync lark-sheets skill from spec (audit 20260521)
Pull latest spec from sheet-skill-spec (PR ee/sheet-skill-spec!6 + earlier
develop commits) into skills/lark-sheets/ and shortcuts/sheets/data/.
Audit findings now reflected in CLI docs:
- A2 +cond-format-create example: --rule-type duplicate → duplicateValues
- A3 +cond-format-create Validate: cellValue/formula → cellIs/expression
- A5 +csv-put examples: --range → --start-cell; drop redundant --allow-overwrite
- A7 +sparkline-create: Validate / Examples aligned with real schema
(config/sparklines), executable JSON example added
- B13 cross-doc dead links: lark_sheet_*/cli-shortcuts.md → lark-sheets-*.md
- C2 +csv-put: `=` literal warning next to Examples
- CC5 +rows-resize/+cols-resize --type auto: single point of truth in
range-operations reference
flag-defs.json description / required sync (from base):
- A4 +float-image-update: image-name/position-*/size-* required → optional
(patch mode)
- A8 +dim-move --start/--end description cleanup
- B3 +pivot-create --properties: data_range → source (real field name)
Also picks up the +cells-batch-clear shortcut doc (introduced in spec
develop). Go-side implementation for that shortcut is intentionally not
in this PR — docs-only preview; runtime dispatch will land in a follow-up.
`go test ./shortcuts/sheets/...` passes.
* feat(sheets): add +cells-set --copy-to-range and sync skill spec
Sync lark-sheets skill references and flag schemas from upstream
sheet-skill-spec, and wire the newly-specced --copy-to-range flag into
+cells-set: it passes copy_to_range to the set_cell_range tool so a
template block written via --cells fans out across a larger range with
auto-shifted formula refs.
* docs(sheets): sync lark-sheets skill spec (chart/pivot wire mappings, --end semantics)
Sync skill references and flag-defs descriptions from upstream
sheet-skill-spec: clarify +chart-create properties structure
(snapshot.data), +pivot-create --target-position / --range wire-field
mappings, add a cross-command --end endpoint-semantics table
(insert/delete/hide/group exclusive vs move/resize inclusive), note
--group-state default, and rename reference identifiers to lark-sheets-*.
Description-only refinement; the existing CLI implementation already
matches the clarified wire mappings and --end semantics.
* fix(sheets): make --max-chars the single read cap for +cells-get / +csv-get
Drop --cell-limit (+cells-get) and --max-rows (+csv-get) from the CLI surface
and pin the underlying tool's cell_limit / max_rows to a very large sentinel so
the tool's own defaults never truncate before --max-chars. --max-chars stays the
only knob (default 200000, unchanged).
- lark_sheet_read_data.go: add unboundedReadLimit (1e9); cellsGetInput pins
cell_limit, csvGetInput pins max_rows; --max-chars still passed through
- data/flag-defs.json: synced from spec (drops the two flags)
- tests: spot-check moved to --max-chars; dry-run wantInput asserts cell_limit /
max_rows are pinned high
Mirrors sheet-skill-spec (Base flag records removed).
go build ./... + go test ./shortcuts/sheets/ green.
* docs(sheets): sync lark-sheets read docs — --max-chars as single read cap
Sync skills/lark-sheets references from spec: drop --cell-limit / --max-rows
guidance; 大表分批读 switches to --range row windows + --max-chars auto cap + has_more.
Mirrors sheet-skill-spec 58e7456 and handler change 2befc49.
* docs(sheets): sync lark-sheets skill spec from upstream
Refine reference docs and flag-defs descriptions from upstream
sheet-skill-spec (--depth wording for +dim-group / +dim-ungroup,
plus assorted reference clarifications). Description-only; no CLI
behavior or flag surface change.
* docs(sheets): sync chart properties schema (position/size required)
Regenerate flag-schemas.json from upstream sheet-skill-spec: the chart
properties schema now marks position and size as required, and the chart
reference doc reflects the same. flag-schemas.json is print-schema-only
(no client-side validation), so this is a generated-artifact + doc sync
with no CLI behavior change.
* docs(sheets): sync lark-sheets skill spec from upstream
Refine reference docs and flag-defs descriptions from upstream
sheet-skill-spec: clarify +workbook-export sheet flag scope, +filter-*
--properties optionality (omitted => empty filter on --range; rules must
be non-empty when provided), float-image reference_id wording, and
assorted reference cleanups. Description-only; existing CLI behavior
(filter passthrough, properties optional) already matches.
* docs(sheets): sync lark-sheets skill spec from upstream
Trim and refine reference docs from upstream sheet-skill-spec
(condense core-operations workflow, tidy write-cells / range-operations /
float-image / SKILL guidance). Description-only; no flag or CLI behavior
change.
* docs(sheets): sync lark-sheets skill spec from upstream
Refine reference docs from upstream sheet-skill-spec (core-operations,
formula-translation, visual-standards, SKILL guidance). Description-only;
no flag or CLI behavior change.
* fix(sheets): correct +workbook-create initial fill and +dim-move endpoint
+workbook-create: the v3 create response does not echo the default sheet's id, so the initial-fill set_cell_range was sent with an empty sheet_id and rejected ("sheet_id or sheet_name is required"). Resolve the workbook's first sheet via get_workbook_structure before filling.
+dim-move: the move request was POSTed to the v2 dimension_range endpoint (the add/update/delete surface, which requires a `dimension` object) and rejected with "[9499] Missing required parameter: Dimension". Switch to the native v3 move_dimension endpoint (sheet_id in path; snake_case source.{major_dimension,start_index,end_index} + destination_index). CLI --end and v3 end_index are both 0-based inclusive, so they pass through unchanged.
* fix(sheets): align +workbook-create, +dropdown-*, +dim-move, +range-sort with server schema
Five separate E2E failures in shortcuts/sheets/ that all trace back to a
CLI ↔ server contract mismatch. Each is independently scoped; bundling
them because they share the test-report citation and the same one-line
fix shape in most cases.
buildInitialFillInput sent {"sheet_id": ""} on the secondary
set_cell_range call after creating the workbook. The empty value was a
holdover from "...otherwise server picks first sheet" — but
set_cell_range rejects an empty selector with
"sheet_id or sheet_name is required" rather than falling back to the
default sheet.
Use sheet_name "Sheet1" instead. POST /sheets/v3/spreadsheets always
creates that sheet on workbook creation, and set_cell_range accepts
sheet_name as an equivalent selector — saves an extra
get_workbook_structure round-trip just to learn the auto-generated id.
buildDropdownValidation emitted four fields that don't exist in the
canonical set_cell_range.data_validation schema:
- "values" (options list) → renamed to "items"
- "multiple_values" → renamed to "support_multiple_values"
- "colors" (per-option color) → removed (not in schema; flag also
removed from data/flag-defs.json
for +dropdown-set / -update)
- "highlight_options" → removed (not in schema; flag also
removed)
The canonical schema lives at sheet-skill-spec/canonical-spec/tool-
schemas/mcp-tools.json (set_cell_range tool, data_validation property);
the colors / highlight knobs were CLI inventions the server never
accepted, so removing the flags is correct (renaming would leave the
flags broken). Skill reference docs (write-cells.md, batch-update.md)
synced.
validateDropdownOptionsColors lost its colors check; renamed to
validateDropdownOptions to reflect the narrower contract.
dropdownGetInput sent "Sheet1!C2:C6" verbatim as a ranges[] entry.
get_cell_ranges expects sheet_id / sheet_name as separate fields and
ranges entries without the sheet prefix; the server bounced with
"sheet not found, sheetId:" (empty).
Use the existing splitSheetPrefixedRange helper (declared in
lark_sheet_batch_update.go) to break "Sheet1!C2:C6" into ("Sheet1",
"C2:C6"), then thread the sheet name through sheetSelectorForToolInput
exactly like +cells-get does.
The shortcut was POSTing to /sheets/v2/spreadsheets/{token}/dimension_
range, which is the v2 insert-dimension endpoint and requires a top-
level {"dimension": {...}} body. Move uses a separate endpoint:
POST /sheets/v2/spreadsheets/{token}/move_dimension
body: { "source": {...}, "destination_index": N }
(camelCase "destinationIndex" → snake_case "destination_index" to
match the v2 contract.) Both DryRun and Execute updated, plus the
TestDimMove_DryRun and TestExecute_DimMove assertions.
transform_range.sort_conditions[i] requires both `column` (string) and
`ascending` (bool); rangeSortInput passed the --sort-keys array through
to the server unvalidated, so missing fields surfaced as opaque
"required property X missing" errors with no per-item context.
Walk the parsed array client-side, reject with item-pointing messages.
Test fixtures and a contract-test fixture switched from the historical
{col, order} vocabulary (which the server has never accepted) to the
correct {column, ascending}.
Server-schema citations and test-report case mapping in this branch's
plan file.
* revert(sheets): drop direct flag-defs.json edits — generated from spec
data/flag-defs.json is regenerated from the upstream sheet-skill-spec
canonical-spec; editing it here gets clobbered on the next sync. The
schema realignment for +dropdown-set / -update --colors / --highlight
removal needs to land on the base table first, then flow back through
sheet-skill-spec → larksuite-cli sync, not via a direct CLI-side edit.
Restore the previous flag entries verbatim. The Go-side change in
buildDropdownValidation still drops the wire fields, so:
- users passing --colors / --highlight today see the flag accepted
silently (no effect on the wire) until the upstream removal lands;
- after upstream removal + sync, both the flag declarations and the
Go-side handling will be in sync.
Functional fixes (#1 workbook-create, #3 dropdown-get, #4 dim-move,
#5 range-sort) and dropdown wire-shape rename (#2) are unaffected.
* revert(sheets): drop direct edits to skills/lark-sheets/references/
These md files are sync targets generated from sheet-skill-spec; editing
them here gets clobbered on the next sync, same as data/flag-defs.json.
The --colors / --highlight row removals belong on the upstream base
table → canonical-spec sync, not here.
Restore the previous --colors / --highlight rows in both
lark-sheets-write-cells.md (+dropdown-set) and lark-sheets-batch-update.md
(+dropdown-update). The Go-side change in buildDropdownValidation still
drops the wire fields, so:
- users passing --colors / --highlight today see the flag accepted
silently (no effect on the wire) until upstream removes the flag;
- after upstream removal + sync, both flag declarations, ref docs, and
Go-side handling will be in sync.
Functional fixes (#1 workbook-create, #3 dropdown-get, #4 dim-move,
#5 range-sort) and dropdown wire-shape rename (#2) are unaffected.
* docs(sheets): sync from sheet-skill-spec — remove dropdown --colors / --highlight
Upstream sheet-skill-spec base table deleted the --colors and --highlight
flags on +dropdown-set / +dropdown-update (the corresponding wire fields
data_validation.colors / .highlight_options were never accepted by the
server schema; see prior fix in this branch). Re-running the sync from
canonical-spec brings the CLI flag-defs and skill reference docs back in
line with the Go-side handling that already drops these fields.
Generated by `npm run sync:cli` in sheet-skill-spec @ ac7acef.
* fix(sheets): restore +dropdown --colors / --highlight, map to canonical fields
Reverses the --colors / --highlight removal from 7932ab2 (item #2 of the
batch-1 schema-alignment commit). That commit dropped both flags after the
test report flagged data_validation.colors / highlight_options as "unexpected
property" — at the time the canonical set_cell_range.data_validation schema
listed only help_text / items / operator / range / support_multiple_values /
type / values, so the flags had no server-side target and the removal was
correct.
Since then, set_cell_range.data_validation has gained two fields explicitly
modelling the dropdown highlight UI (mcp-tools.json in sheet-skill-spec
2026-05-22 base sync):
enable_highlight (bool) — show pill backgrounds
highlight_colors (string[]) — hex pill colors, length must match items
So the flags are back, but rewired:
--colors -> data_validation.highlight_colors (was: colors)
--highlight -> data_validation.enable_highlight (was: highlight_options)
--options -> items and --multiple -> support_multiple_values renames from
7932ab2 are kept.
Changes:
- buildDropdownValidation: re-add --colors / --highlight handling against
the new field names; --colors length check stays inline (so dropdownSetInput
Validate path catches it via validateViaInput, no separate guard needed).
- validateDropdownOptions -> validateDropdownOptionsColors: restore the
Validate-time --colors length check on +dropdown-update / +dropdown-delete
(called from lark_sheet_batch_update.go).
- TestDropdownSet_CellsShape: extend to assert highlight_colors /
enable_highlight emitted; assert legacy `colors` / `highlight_options`
absent.
- TestDropdownSet_ColorsLengthMismatch: new — covers the early Validate
error path.
- TestDropdownUpdate_BatchPayload: extend to cover dropdownBatchInput
propagation of --colors / --highlight through batch_update.
- skills/lark-sheets/references/lark-sheets-{write-cells,batch-update}.md,
shortcuts/sheets/data/flag-defs.json, flag-schemas.json: synced from
sheet-skill-spec generate output (MR !7).
* chore(sheets): re-sync from spec + loosen --colors length check
Catches up to sheet-skill-spec's 2026-05-25 base sync (MR !7) after
rebasing onto upstream feat/lark-sheets-refactor (12 new upstream commits
including the lark-sheets skill refactor + tools-schema migration).
Spec changes flowing in:
- highlight_colors description loosened: length may be **shorter than**
--options (server cycles remaining slots through a built-in 10-color
palette); previously the tool errored on any length mismatch.
- shortcuts/sheets/data/flag-schemas.json: mass re-mirror — generator now
emits `type` before `properties` and adds explicit `additionalProperties:
false` on object schemas (cosmetic, no behavior change).
- skills/lark-sheets/references/lark-sheets-{batch-update,chart,write-cells}.md:
--options gains the type='list' tag; data_validation inline field-count
goes 7 → 9 (catches up the highlight schema in the summary); chart
position / size marked optional per upstream.
Go-side adjustment:
- buildDropdownValidation / validateDropdownOptionsColors: change the
--colors length check from strict-equal to "must not exceed --options"
to match the relaxed schema.
- TestDropdownSet_ColorsLengthMismatch -> TestDropdownSet_ColorsLongerThanOptions
(now hits the overflow path with 3 colors vs 2 options).
- New TestDropdownSet_ColorsShorterAccepted: 2 colors vs 4 options is
legal and forwarded as-is.
* docs(sheets): sync dropdown --colors/--highlight clarification from spec
Mirrors sheet-skill-spec MR !7 changes:
- skills/lark-sheets/references/lark-sheets-write-cells.md: new "Dropdown
配色" section explaining how --colors (→ data_validation.highlight_colors)
and --highlight (→ data_validation.enable_highlight) compose — length
rule (shorter ok, longer rejected), --highlight gating, palette
fallback behavior, minimal +dropdown-set example.
- skills/lark-sheets/references/lark-sheets-batch-update.md: one-line
pointer to the write_cells section for +dropdown-update / -delete
(same rules).
- shortcuts/sheets/data/flag-defs.json: --colors / --highlight `desc`
fields gain the long-form server-field / length-rule descriptions
used by `--help`.
No Go-side change — earlier commit 538eb2e already loosened the
buildDropdownValidation length check to "must not exceed"; this PR step
just makes the docs / `--help` text catch up.
* feat(sheets): +dropdown-set/-update --source-range for listFromRange mode
Previously +dropdown-set / +dropdown-update only emitted
data_validation.type=list — agents wanting listFromRange (dropdown options
sourced from existing cells, kept in sync with that range) had to drop down
to +cells-set and hand-build a data_validation map. The flag now exposes it
natively as --source-range, paired with --options under XOR.
CLI changes:
- shortcuts/sheets/lark_sheet_write_cells.go:
* new dropdownTypeAndItems(runtime) — central XOR resolver: rejects 0 or
2 of {--options, --source-range}, returns (sourceSize, partial dv with
type+items|range filled in). Source size = options length for list
mode, rangeDimensions(--source-range) cell count for listFromRange.
* buildDropdownValidation rewritten to call the resolver, then layer
--colors / --multiple / --highlight on top — semantics unchanged
for callers, just two modes instead of one.
* validateDropdownOptions / -Colors renamed to validateDropdownSourceOrOptions
so the XOR + length check fires at +dropdown-update Validate time too.
* --colors length error message generalized: "must not exceed dropdown
source size (N)" (covers both modes).
- shortcuts/sheets/lark_sheet_batch_update.go: rename call site.
- shortcuts/sheets/lark_sheet_write_cells_test.go: 4 new tests —
ListFromRange (happy path: range + items absent + colors + highlight all
emit), ListFromRange_ColorsLongerThanCells (overflow against T1:T3 cell
count), XorBothSet, XorNeitherSet. Updated the existing
ColorsLongerThanOptions assertion to match the new "source size" wording.
Spec-driven changes (synced via npm run sync:cli from sheet-skill-spec
MR !7 2c298b6):
- shortcuts/sheets/data/flag-defs.json: --options Required flips to xor on
+dropdown-set/-update; new --source-range row gains long-form description
pointing at server data_validation.range + the XOR semantics.
- skills/lark-sheets/references/lark-sheets-write-cells.md: "Dropdown 配色"
section reorganized into "Dropdown 选项 + 配色" — XOR comparison table
(list vs listFromRange), shared config flag table (--highlight /
--colors), explicit length rule covering both modes, side-by-side
minimal examples, server-range-normalization gotcha callout.
- skills/lark-sheets/references/lark-sheets-batch-update.md pointer updated
to mention both modes + that +dropdown-delete is unaffected.
PPE smoke (ppe_lark_cli_sheet) on UFJxszjrZhZ1LVtc9FdcICSbn6b C column:
- +cells-set C1 → "性别" (bold + centered): updated_cells_count=1
- +dropdown-set --range C2:C21 --source-range "Sheet1!T1:T3" --colors
'["#cce8ff","#ffd6e7","#e6e6e6"]' --highlight: updated_cells_count=20
- read-back: data_validation.type=listFromRange + range=$T$1:$T$3 (server
normalizes the prefix away on storage; highlight_colors /
enable_highlight not echoed by get_cell_ranges, see byted-sheet read
projection TODO).
- error-path replay (both XOR violations + colors > source-size) all
rejected at Validate stage with the expected messages.
* docs(sheets): sync agent-voice rewrite of Dropdown 选项+配色 from spec
Mirrors sheet-skill-spec MR !7 60df610 — narrative now describes how the
flags interact (XOR, colors length rule, highlight gating, sheet-prefix
read-back gotcha) without exposing the underlying data_validation field
names or server-side normalization details that agents don't act on.
No Go-side change, no shortcut behavior change.
* chore(sheets): restore --colors in parseJSONFlag docstring example list
The earlier commit 49104ec swapped --colors out of parseJSONFlag's "Used
by" example list when it deleted the flag (item #2 there removed --colors
/ --highlight from +dropdown-set/-update). Subsequent commits 8672d8e /
538eb2e / fb90c8b reinstated --colors (and added --source-range) but did
not roll back this docstring tweak — leaving an orphan reference to
--properties where --colors used to be.
This restores the example list to its pre-49104ec form so the docstring
matches what the helper actually services on this branch's HEAD.
Pure docstring change — function behavior unaffected, no test movement.
* fix(sheets): post-rebase test fixups after dropping superseded fix#1
Two test fallouts from rebasing onto upstream 4be06c8 (which independently
re-fixed +workbook-create and +dim-move with a more thorough approach):
- shortcuts/sheets/lark_sheet_workbook_test.go: our PR's earlier
TestWorkbookCreate_DryRun "with headers and data → 2-step plan" subtest
asserted the expedient sheet_name="Sheet1" / no-sheet_id wire body that
matched our dropped fix#1 implementation. Upstream's fix#1 resolves
the workbook's first sheet via get_workbook_structure and fills with
the real sheet_id instead. Reset this file to upstream's version — our
superseded assertions disappear, upstream's tests cover the new wire
shape.
- shortcuts/sheets/execute_paths_test.go: TestExecute_RangeSort fixture
still used the legacy {col, order} sort-key shape because the rebase
resolution picked the upstream version of this file wholesale (it
contained other unrelated changes). Re-apply just the one fixture
update to {column, ascending} so fix#5's CLI-side rejection logic
exercises a valid input — server-side sort_conditions has required
fields `column` (string) and `ascending` (bool); the historical
{col, order} vocabulary was never accepted.
go build ./... + go test ./shortcuts/sheets/... -count=1 both green.
* feat(sheets): +dropdown --highlight tri-state via Changed() for opt-out
The server-side default for data_validation.enable_highlight flipped from
false to true (aligning with the UI behavior). With the previous code path
if runtime.Bool("highlight") { dv["enable_highlight"] = true }
omitting --highlight and passing --highlight=false both produced the same
"enable_highlight key absent" body, leaving CLI users with no way to opt
out of the (now-default) highlighting.
Switch to runtime.Changed() so the translator can distinguish all three
input shapes:
- omitted -> no enable_highlight key (server applies default=true)
- --highlight=true -> enable_highlight: true (explicit no-op vs default)
- --highlight=false -> enable_highlight: false (the only opt-out path)
flagView already exposes Changed() and mapFlagView (the +batch-update
sub-op adapter) implements it via raw-key presence — same pattern other
translators use for "Changed-only" branching (e.g. omit target_index
unless --index was set), so no interface surface change is needed.
Test coverage:
- TestDropdownSet_HighlightTriState pins all four shapes (omit / presence
form / explicit true / explicit false) and asserts the enable_highlight
key's presence/value
- TestBatchOp_BodyMatchesStandalone adds a --highlight=false sub-op case
so the batch sub-op path produces a body byte-identical to the
standalone +dropdown-set --highlight=false body
* chore(sheets): sync +dropdown flag desc + write-cells narrative from spec
Mirror sheet-skill-spec generated/ into shortcuts/sheets/data/ and
skills/lark-sheets/ for the +dropdown-set / +dropdown-update path. No
hand edits in this repo.
The +dropdown flag desc and the Dropdown 配色 narrative now match the
server-side enable_highlight default flip (true) and the tri-state
--highlight semantics introduced in the sibling commit:
* --highlight desc: 不传 = 开（按内置 10 色色板循环上色），
--highlight=false 关闭得到纯白下拉
* --colors desc: 单独传即生效（高亮默认开），--highlight=false 时忽略
* write-cells reference: 三种意图三条线（默认色板 / 指定颜色 /
纯白下拉）+ 新增 --highlight=false 示例
Source upstream: sheet-skill-spec MR !8.
* fix(sheets): validate +cells-set-image --image path in Validate
The unsafe-path check only ran at Execute (via FileIO.Stat), so --dry-run
printed a misleading success preview for an absolute / out-of-cwd --image
path that a real run would then reject. Move the path-safety check into
Validate (validate.SafeLocalFlagPath), so --dry-run and Execute fail
identically and both name the real --image flag. File existence stays
deferred to Execute, so legitimate relative paths still preview cleanly.
Add TestCellsSetImage_DryRunRejectsUnsafePath.
* feat(sheets): support local --image in +float-image-create
+float-image-create now accepts a local file via --image (XOR with
--image-token / --image-uri): the CLI uploads it as a sheet_image and
embeds the returned file_token, removing the previous "upload elsewhere
to get a token first" workaround. Path safety is checked in Validate,
--dry-run previews the extra upload step, and +batch-update rejects
--image (no upload phase). +float-image-update is unchanged (it does not
register --image).
Also syncs the lark-sheets skill docs/flag-defs from sheet-skill-spec:
the new --image flag, partial-merge / border-per-side / bare sheet-prefix
clarifications, and refreshed dropdown --colors/--highlight descriptions
(already pending in the source Base table).
* fix(sheets): +dropdown-get accepts --sheet-id/--sheet-name + bare --range
Align +dropdown-get with its get_cell_ranges siblings (+cells-get / +csv-get):
sheet selection is now via --sheet-id / --sheet-name (XOR) and --range is a
bare A1 reference. The previous shape required the sheet prefix inside --range
(e.g. "Sheet1!A2:A100") and was the odd one out among the read-data wrappers;
callers pasting the sheet-id form straight from the URL hit a misleading
"sheet not found, sheetId: , sheetName: <id>" error because the prefix was
unconditionally treated as sheet_name.
Flag schema + skill reference regenerated from the upstream Lark Base
Shortcut-flags table.
* fix(sheets): drop Sheet1! prefix from +cells-get / +csv-get / +csv-put flag examples
Server tools-schema.json for get_cell_ranges, get_range_as_csv and set_range_from_csv
does not accept a sheet prefix on --range / --start-cell; the sheet is selected via
--sheet-id / --sheet-name. +csv-put --start-cell also now states it must be a single
cell (no range notation).
Synced from spec repo.
* feat: 把环境变量提交上去
* fix(sheets): clarify batch --ranges prefix must be sheet display name
E2E test cases repeatedly trip on this:
$ lark-cli sheets +cells-batch-set-style \
--ranges '["7f8fba!A2:B3","7f8fba!C2:D3"]' --font-color '#3366FF' ...
→ tool "batch_update" failed: [900015206]
sheet "7f8fba" not found. Available sheets: [{id: "7f8fba", name: "Sheet1"}]
Callers paste the hex sheet-id (e.g. "7f8fba") from a spreadsheet URL /
+sheet-create response straight into the --ranges sheet prefix. The four
batch shortcuts (+cells-batch-set-style / +cells-batch-clear /
+dropdown-update / +dropdown-delete) fan each range out into a
batch_update sub-op (set_cell_range / clear_cell_range) and pass the
prefix through as sheet_name; the server only matches sheet_name
literally, so the lookup fails.
The set_cell_range tool schema is explicit: sheet_id is the
reference_id and "must be correct or it errors"; sheet_name is the
display name. CLI can't disambiguate purely from the literal because
users can rename sheets to anything (including six-char hex strings).
Cleanest fix is at the source: each batch shortcut's --ranges flag
description now states explicitly that the prefix must be the sheet
display name and that the sheet reference_id is rejected, so agents
reading the reference don't try the id form in the first place.
No Go changes; these files are regenerated from the upstream Lark Base
Shortcut-flags table via the sheet-skill-spec sync chain.
* docs(sheets): sync lark-sheets skill docs from upstream spec
- SKILL.md: clarify --url only resolves /sheets/ and /spreadsheets/ links; /wiki/ links must be resolved via wiki +node-get first (confirm obj_type=sheet, use obj_token)
- formula-translation: document IMPORTRANGE cross-workbook limits (max 5-level nesting, 100 refs per sheet)
- write-cells: document rich_text cells for hyperlinks, @mentions and @docs
* feat: 同步 tools-schema.json 改动
* fix(sheets): warn when +dropdown source-range exceeds 2000 cells with highlight on
byted-sheet's ListFromRangeValidation.checkOptionsValid() sets
isOptionError=true when shouldHighlightValidData is on and the source
range exceeds LIST_WITH_COLOR_MAX_COUNT (2000 cells) — the highlight +
large source combo is unsupported. CLI previously had no signal for
this, so users only learned by seeing the dropdown render as
option-error in the workbook.
Add a Validate-phase stderr warning in +dropdown-set and +dropdown-update
when --source-range covers >2000 cells unless --highlight=false. Soft
warning, never blocks the request. Inline --options is not subject to
this limit — server enforces no count or per-item length cap on inline
lists, so no warning fires there.
* docs(sheets): sync lark-sheets skill from spec — dropdown flag descs reflect server reality
Pulls sheet-skill-spec canonical-spec → generated → consumers chain for
dropdown flag desc corrections committed upstream (Shortcut-flags base
table rows for +dropdown-set / +dropdown-update --options and
--source-range).
Aligns flag descs with byted-sheet behavior:
- --options: dropped fabricated "≤500 items, each ≤100 chars, no commas"
promise. byted-sheet ListOfItemValidation enforces none of these.
- --source-range: appended note about the only real cap —
LIST_WITH_COLOR_MAX_COUNT=2000 when --highlight is on (server flags the
dropdown as option-error beyond that; CLI warns at Validate time per
bb7ccae).
Also picks up an unrelated upstream tools-schema.json drift (chart float
block schema + data_validation.items description tweak) that surfaced
via npm run check:tool-schemas; bundling keeps the spec sync gate green.
* revert(sheets): drop tools-schema drift mirror from previous spec sync
930c9c7 顺带 sync 了 spec 的 tools-schema bundling — 跟那条 commit 一起
误带进来 chart float block required 和 data_validation.items 描述微调，
这两处其实是上游 sheet-ai-skills 还在 pending 的 revert。
配套 sheet-skill-spec 的 revert commit (a3aa9f2 on
fix/dropdown-flag-desc-real-limits / !11)，重跑 sync:consumers 拉回
正确的 generated mirror：
- shortcuts/sheets/data/flag-schemas.json（chart 部分）
- skills/lark-sheets/references/lark-sheets-{chart,batch-update,write-cells}.md（rendered schema 段）
dropdown 文案改动（flag-defs.json 4 处 desc + dropdown 段的 reference
渲染）不在本 commit 范围，保持 930c9c7 的状态。
* docs(sheets): sync lark-sheets skill from spec — +filter-view-update --properties desc
去掉 +filter-view-update --properties 描述里"pass at least one of
--properties.rules / --range / --view-name"的误导承诺。--properties
实际是硬必填（MarkFlagRequired），且 update 走 PUT 整组覆盖语义。
* fix(sheets): align +cells-search/+cells-replace option keys with server schema
The CLI emitted `options.regex` and `options.include_formulas`, but the
server-side `search_data` / `replace_data` tool schemas declare and
consume `use_regex` and `match_formulas`. Result: passing `--regex` or
`--include-formulas` always failed with `unexpected property ... is not
defined in schema`.
Keep the user-facing flag names (`--regex`, `--include-formulas`) — only
the JSON keys sent to the server change. Updates the dry-run test that
locked the wrong contract.
* docs(sheets): sync float-image reference from spec — fix non-runnable examples
Two examples in skills/lark-sheets/references/lark-sheets-float-image.md
didn't actually run against PPE; sync brings them in line with CLI behavior:
- +float-image-create local-path example missed --image-name (CLI rejects
with `required flag(s) "image-name" not set` even when path basename
already has the filename). Add `--image-name "logo.png"` + inline note.
- +float-image-update "only change position" example missed image source
(CLI rejects with `one of --image, --image-token, or --image-uri is
required`). Expand to two steps: list with --jq pulls the current
image_token, then update re-passes --image-token to satisfy the guard.
- Leading warning realigned: image source is mandatory on every update
call; "keep original image" still requires passing the token explicitly.
Upstream change: sheet-skill-spec MR fix/float-image-reference-examples.
* feat: 同步 tools-schema.json 改动
* fix(sheets): allow +float-image-update to omit the image source
The image source (--image-token / --image-uri) is the only optional part
of an update: omit all of them to keep the current image. image_name,
position and size stay required — the manage_float_image tool rejects an
update without them, and +float-image-list does not return image_name to
backfill. Previously the shortcut forced an image source even when only
position/size changed, so those updates were rejected CLI-side before any
API call (reported as a Fail case in the sheets e2e rerun).
- floatImageProperties: gate the image-source requirement on create only;
keep image_name/position/size required on both; emit image_uri only when set
- sync flag-defs.json + lark-sheets-float-image.md from sheet-skill-spec
(image-name/position/size now required on +float-image-update)
- tests: cover the image-source-optional dry-run; the single-required checks
move to the +batch-update sub-op path (cobra owns the standalone path)
* docs(sheets): sync lark-sheets skill from spec
Mirror the canonical-spec reference fixes into the consumer skill:
- search_replace output contract: `matches[]` with `address` (+ `has_more`/`next_offset`)
- workbook sheet fields: `sheet_name`/`is_hidden`/`*_count`, no `frozen_*`
- `+range-fill` example uses a non-overlapping target (A3:A100)
- drop the unimplemented `envelope.meta.verification` auto-readback claim; advise
manual list/get verification instead
* fix(sheets): allow +pivot-create to omit both sheet selectors
manage_pivot_table_object treats sheet_id / sheet_name as the placement
target — when both are absent, handleCreate() auto-creates a new sub-sheet
to host the pivot table. The CLI's flag schema didn't reflect this:
- Exposed a third flag --target-sheet-id that mapped to the same wire
field as --sheet-id, leaving the caller unsure which one to use
- --sheet-id / --sheet-name had "XOR with the other" descriptions that
read like "operation context", so callers (especially LLM tool callers)
felt obligated to set one — frequently the source sheet — which
silently disabled the backend's auto-create guardrail and dropped the
pivot at A1, overlapping the source data
Wire change (synced from sheet-skill-spec): drop the duplicate
--target-sheet-id flag; rewrite --sheet-id / --sheet-name descriptions
to make the placement-target semantics explicit and call out that
omitting both is the recommended path.
Implementation change (this PR): add an at-most-one sheet-selector
helper and let object create-shortcuts opt into it.
- helpers.go: new optionalSheetSelector (both empty allowed; both set
still rejected; control-char validation unchanged). requireSheetSelector
is untouched — every existing caller keeps the exactly-one contract.
- lark_sheet_object_crud.go: objectCRUDSpec gains
allowEmptySheetSelectorOnCreate; objectCreateInput dispatches to
optionalSheetSelector when it's set. Only pivotSpec opts in;
chart / cond-format / sparkline / filter-view / float-image keep
the existing require semantics. DryRun and Execute switch to direct
flag extraction (same pattern Validate already used) so the XOR
check happens in exactly one place (the builder).
- pivotSpec: drop the enhanceCreateInput branch that read the now-removed
--target-sheet-id flag.
- Tests: TestPivotCreate_SheetSelectorSemantics covers both-empty /
both-set / single-set; TestObjectCreate_RequiresSheetSelector
regresses chart / cond-format / sparkline / filter-view to lock the
scope of the relaxation.
* docs(sheets): clarify filter/filter-view rules update is whole-set PUT
Synced from upstream tools-schema. The rules field on manage_filter_object and manage_filter_view_object now documents update as whole-set PUT semantics: submitted rules become the complete rule set, all existing columns' rules are cleared first, columns not listed lose their old rules (no merge), and [] clears everything. Description-only change, no structural/field change.
* refactor(sheets): switch dim-* / rows-cols-resize to A1-string range schema
The 9 row/column-region shortcuts used to share two int flags --start /
--end with inconsistent end semantics across commands — +dim-insert /
-delete / -hide / -unhide / -group / -ungroup treated --end as exclusive,
while +dim-move / +rows-resize / +cols-resize treated it as inclusive.
The skill reference even called this out as "the highest-frequency
off-by-one source", patched in docs rather than at the surface. Three
underlying tool schemas (position+count, A1 range string, 0-based int
pair) were all flattened onto the same --start/--end pair, which forced
a different normaliser per command and pushed mental math (count =
end - start) onto every caller.
Schema (sourced from base, regenerated via sheet-skill-spec, mirrored
into shortcuts/sheets/data/ and skills/lark-sheets/):
+dim-insert --position + --count
rows: "3"; columns: "C". --count rows/columns
inserted *before* --position.
+dim-delete / -hide / -unhide / -group / -ungroup
--range
+rows-resize / +cols-resize --range
A1 closed range. Rows: "3:7" or "5". Columns: "C:F" or "C".
Mixing letters and digits in one range is rejected.
+dim-move --source-range + --target
--target must match --source-range's dimension (both row or both
column). The move places the source block *before* --target.
Wire-shape preserved: modify_sheet_structure still receives `position`
+ `count` (insert) or a `range` A1 string (other dim-* ops); v3
move_dimension still receives 0-based inclusive ints (CLI parses the
A1 strings into them); resize_range still receives a two-sided A1
range (single-element form is expanded to "N:N" before send).
This is a flag-surface break (--start / --end / --dimension flags
removed from these 9 shortcuts); --dimension stays only on +dim-freeze
since it has no range to derive from.
Code: A1 parser added (parseA1Range / parseA1Position /
letterToColumnIndex reused from write_cells); dimRange / dimRangeFull /
dimPosition deleted; dim-move switches to source-range + target parsing;
resize gains a same-dimension guard so +rows-resize rejects "A:C" with
a clear "+rows-resize expects row numbers" message.
Tests: TestSheetStructureShortcuts_DryRun / TestDimMove_DryRun /
TestDimMove_Column / TestDimMove_MismatchedDimension /
TestDimRange_Validation / TestParseA1Range / TestResize_TypeAndSizeGuards
/ TestRangeOperationsShortcuts_DryRun all rewritten against the new
schema. Batch contract trio (BodyMatchesStandalone /
ErrorEquivalence / RejectsBadSubOpInput) and
TestBatchOp_DispatchCoversReportedBugs likewise. Full
`go test ./shortcuts/sheets/` passes.
* docs(sheets): sync +pivot-create placement reference from spec
Companion sync from sheet-skill-spec — the canonical reference rewrites
+pivot-create's "5 placement-related flags" rundown into a clearer
"4 placement-related flags" form (--target-sheet-id was already removed
in #1130, this updates the prose accordingly), and clarifies that
--sheet-id / --sheet-name on +pivot-create are the *placement* sheet
(not the source-data sheet), with omit-both as the strongly-recommended
default.
Also picks up a base-side --target-position description tweak that
dropped the now-stale "与 --target-sheet-id 配套" reference.
No CLI surface change.
* docs(sheets): sync +pivot-create summarize_by lowercase enum values from spec
* docs(sheets): wrap sheet names in single quotes in A1 examples
Synced from spec. Affects 3 reference md (pivot-table / batch-update /
write-cells) and 2 generated flag-data JSONs.
A1 examples like `Sheet1!A1:D100` now read `'Sheet1'!A1:D100` so models
default to single-quoted sheet names. Excel A1 notation requires single
quotes for sheet names containing hyphens / spaces / non-ASCII chars;
always-quoting is also valid for plain names, so this is the safer default
to teach.
Affected flags:
- +pivot-create --source
- +dropdown-update --ranges / --source-range
- +dropdown-delete --ranges
- +dropdown-set --source-range
- +cells-batch-set-style --ranges
- +cells-batch-clear --ranges
* docs(sheets): wrap A1 sheet names in handwritten examples + bash histexpand guide
Synced from spec. Affects 4 reference md (chart / pivot-table / sparkline /
write-cells) and SKILL.md.
In addition to wrapping sheet names in single quotes in all remaining
handwritten examples (covers chart refs.value / nameRef, sparkline source,
write-cells --source-range, pivot-create narrative), SKILL.md gains a new
"Shell quoting for A1 references with !" section.
The new section addresses bash history expansion: in interactive bash
(e.g., ShellExec sandbox), unescaped `!Word` after `"..."` triggers
`bash: !A1: event not found`, dropping the command before lark-cli sees
it. The section gives 4 quoting strategies (shell single-quote outer,
`set +H` prefix, mixed quoting, sheet-rename fallback) and an anti-pattern
list.
Affected files:
- skills/lark-sheets/SKILL.md (new section)
- skills/lark-sheets/references/lark-sheets-chart.md
- skills/lark-sheets/references/lark-sheets-pivot-table.md
- skills/lark-sheets/references/lark-sheets-sparkline.md
- skills/lark-sheets/references/lark-sheets-write-cells.md
* docs(sheets): drop bash histexpand section, fix write-cells table escape
Sync from spec, refining the bash-quoting deep-dive added in 0f695b6:
- Drop the `## Shell 调用注意事项` section in SKILL.md and the inline
`⚠️ bash 引号` callouts in lark-sheets-pivot-table.md and
lark-sheets-write-cells.md. The 4-scenario quoting table + anti-pattern
list turned out too verbose for the SKILL intro; single-quoted examples
in the references are themselves enough nudge.
- lark-sheets-write-cells.md L146: fix the table cell escape from the
malformed `'''Sheet1''!T1:T3'` (consecutive `''` are no-op empty
strings) to `''\''Sheet1'\''!T1:T3'`, matching the bash example at
L191 verbatim.
Net: 1 insertion, 40 deletions across 3 files.
* feat(sheets): rename +pivot-create sheet selector → --target-sheet-{id,name}
+pivot-create's placement selector (where the pivot table lands) is no
longer the generic --sheet-id / --sheet-name; it is now
--target-sheet-id / --target-sheet-name. The new names mark this as the
*output* sheet, distinct from the *data-source* sheet (which lives
inside --source as `'Sheet'!Range`). The other +pivot-{list,update,delete}
shortcuts keep --sheet-id / --sheet-name (their semantics are
"sheet that hosts the existing pivot", same as every other shortcut).
Motivation: an LLM agent reading the previous CLI surface saw +pivot-create
expose --sheet-id and assumed (as it had to) that it pointed at the data
source, like every other shortcut. The new flag name makes the intent
unambiguous at the call site, without relying on the agent having read
the narrative caveat in the reference doc.
Background: evaluation case U046 spent multiple rounds tripping on this
exact confusion before working around it with +sheet-rename.
Implementation:
- objectCRUDSpec gains createSheetIDFlag / createSheetNameFlag (with
default-fallback accessors sheetIDFlagOnCreate / sheetNameFlagOnCreate);
newObjectCreateShortcut + objectCreateInput consult the spec instead of
hard-coded "sheet-id" / "sheet-name". pivotSpec sets target-sheet-*;
every other create spec inherits the defaults.
- optionalSheetSelector (only used by pivot create) takes the two flag
names as parameters so its mutex / control-char errors quote the names
the user actually typed (--target-sheet-id, not --sheet-id).
- batch_op_dispatch: introduce sheetSelectorFlagsForSubOp(shortcut) →
(idFlag, nameFlag) returning target-sheet-* for "+pivot-create" and
the defaults otherwise; translateBatchOp uses it so +pivot-create
sub-ops in +batch-update accept the same renamed input keys.
- Tests:
- lark_sheet_object_crud_test.go: pivot-create cases switch args and
expected error wording to target-sheet-*; extra assertion that the
mutex error quotes the renamed flag (regression guard against
flag-name drift between code and error message).
- batch_op_contract_test.go: +pivot-create sub-op test uses
target-sheet-id / target-sheet-name input keys; the body-vs-standalone
contract loop reads the selector via sheetSelectorFlagsForSubOp so
every other shortcut keeps using sheet-id / sheet-name.
Synced reference docs (skills/lark-sheets/{SKILL.md,
references/lark-sheets-pivot-table.md}) mirror the spec's new flag names,
narrative, 3-placement-strategy block, and SKILL.md exception bullet that
explains why +pivot-create's badge says 无 sheet 定位 yet still has
placement selectors (just under different names).
flag-defs.json synced from spec picks up the renamed flags + kind=own.
All sheets-package tests pass.
* docs(sheets): strip migration-history language from pivot reference / SKILL
Synced from spec. Removes "renamed from / no longer called / not
--sheet-id" style migration-history language that snuck into the
previous sync. Reference and SKILL now describe the current flag names
directly without referencing the old names.
* docs(sheets): require +workbook-info before guessing sheet name
Synced from spec. SKILL.md adds a new rule under the sheet-locator
section: unless the user has explicitly named a sheet, the agent must
call +workbook-info first to fetch sheets[].sheet_id / sheets[].title
rather than guessing the default `Sheet1`. The Chinese-language tables
this CLI is typically used against rarely use that literal name —
"数据" / "Sheet" (no digit) / "工作表 1" / business-named sheets are
far more common — so guessing wastes a round-trip before the agent
ends up calling +workbook-info anyway.
The 统一调用范式 example also switches its `--sheet-name "Sheet1"`
placeholder to `<真实表名>` to remove the inadvertent suggestion that
`Sheet1` is a sensible default.
* docs(sheets): tell agent to `set +H` for A1 references containing `!`
Synced from spec. The sheet-locator section now warns: when a flag value
contains `!` (--source / --range / --ranges with a cross-sheet prefix),
run `set +H` at the start of the bash session to disable history
expansion — otherwise interactive bash (e.g. inside an agent's shell
sandbox) lexes "Sheet1!A1" as a history reference and fails with
`event not found` before lark-cli ever sees the argument.
When the sheet name itself contains hyphens / spaces / non-ASCII
characters, the A1 reference also needs single quotes around the sheet
name per A1 notation, e.g. --source "'Sales-2025'!A1:D100".
Also flips the previous `--range` example to `--range 'Sheet1!A1:B2'`
(shell single-quote) for consistency.
* feat(sheets): add schema-driven JSON flag validation
Validate composite JSON flags (--properties, --cells, --options,
--border-styles, --sort-keys) against the embedded flag-schemas.json
on every standalone and +batch-update sub-op invocation, replacing
ad-hoc per-shortcut guards.
Supports the JSON Schema subset actually used upstream: type / enum
/ oneOf / required / properties / items / nullable / minimum /
maximum / minItems / maxItems / additionalProperties (true | false
| <schema>). Enum errors quote the failing value, truncate beyond 8
entries, and surface case-only "did you mean" hints (SUM -> sum).
Coverage: 18 / 19 (shortcut, flag) pairs. +batch-update --operations
stays validator-skipped; its translator already does richer per
sub-op checks. mapFlagView.Command() routes batch sub-ops through
the same (command, flag) -> schema pipeline as standalone.
loadFlagSchemas() is now sync.Once-guarded so parallel first access
from t.Parallel test sets and concurrent shortcut invocations is
race-free.
Removes superseded hand-written guards:
- +pivot-create validateCreateInput / validatePivotCreateProps
- +range-sort sort-keys per-item shape check
Test fixtures updated to be schema-conformant (chart position/size,
pivot summarize_by lowercase, cells 2D-array shape).
* feat(sheets): add --rows-json output flag to +csv-get
+csv-get --rows-json returns structured rows ({row_number, values:{col→cell}})
instead of the CSV string, so callers can address cells by row_number / column
letter without parsing [row=N] or RFC-4180 CSV. Same read, alternate output
shape — a flag on +csv-get (default stays CSV), not a separate shortcut, since
the two differ only in representation.
- CsvGet.Execute: --rows-json reshapes the response via assembleRowsJSON
(parses annotated_csv into per-row records keyed by column letter; every
logical row emitted; embedded newlines parsed into cell values)
- surfaces the under-read hint structurally as data_not_fully_read
- flag-defs.json + read-data reference synced from spec
* feat(cli): agent-friendly errors, proxy silencing, +csv-put --range
Agent-experience fixes distilled from analyzing 50 real sheets
trajectories, where the top failures were hallucinated command/flag
names, proxy warnings corrupting JSON on stdout, and --range carried
over from +csv-get to +csv-put.
- did-you-mean: unify the duplicated Levenshtein into a shared
internal/suggest package and wire its prefix-weighted ranker into
unknown-subcommand and unknown-flag errors; flag-parse errors now
return a structured envelope with suggestions plus the full valid list,
so agents recover from semantic typos (e.g. --query vs --find).
- proxy: suppress the one-time proxy warning in non-interactive
(agent/CI/piped) runs so a 2>&1-merged stderr line cannot corrupt
stdout JSON; interactive sessions still warn.
- sheets +csv-put: accept --range as an alias for --start-cell (parity
with +csv-get / +cells-set) and echo the computed writes_range in
dry-run and the success envelope, so agents see the paste footprint
before it overwrites neighbours.
- docs(sheets): add an intent->command cheat-sheet to SKILL.md, a
runtime-prerequisites section, and document the --range alias and
writes_range behaviour.
* feat(sheets): close P0-4 pivot gaps — enum case, clear→pivot-delete hint, placement warning
Last open P0 from the 50-trajectory analysis — the two pivot black holes:
upper-cased summarize_by, and pivots built over the source sheet that hit
#REF! and then couldn't be removed.
- enum case tolerance: validateAgainstSchema rewrites a case-only enum
mismatch to the canonical (lower-case) spelling in place ("SUM" -> "sum")
before the request is sent, killing the whole class instead of only
hinting at it. Covers every nested enum (values[], calculated_fields[]);
genuinely unknown values still fail with the existing did-you-mean message.
- +cells-clear / +cells-batch-clear: when the backend reports "can not find
embedded block" (the range overlaps a pivot/chart), annotate the error
with the real fix — clearing cells can't delete an embedded object; remove
it with +pivot-delete / +chart-delete (id via +pivot-list / +chart-list).
Applied to both shortcuts, a Tips line, and the cells-clear reference.
- +pivot-create: a --help Tips block making "omit --target-* -> backend
auto-creates a sub-sheet, zero overwrite" the can't-miss default, plus a
placement_warning (dry-run + execute output) when an explicit target sheet
is set with no offset — definite when the target name matches the source
sheet, conditional otherwise. Local-only, advisory, never blocks the call.
The placement_warning is structured output, not a stderr line, so it
survives non-interactive proxy-warning silencing and isn't swallowed by 2>&1.
* feat(sheets): strip UTF-8 BOM from stdin/@file flag input
resolveInputFlags now strips a leading UTF-8 BOM from content read via stdin
or @file, so it cannot corrupt the first CSV cell or break JSON parsing of
payloads like --operations / --cells downstream.
Also pulls the synced lark-sheets skill docs from sheet-skill-spec and drops
scheme-number tags from two test comments.
* fix(sheets): drop dead --value-render-option flag from +csv-get
+csv-get wraps get_range_as_csv, which has no value_render_option support
(absent from its input type, executor, and published tool schema — it always
returns formatted display text via getText()). The CLI passed the flag through
as a silent no-op: callers asking for raw_value/formula got formatted values.
Remove the flag from flag-defs, drop the value_render_option passthrough in
csvGetInput, and clean the stale SKILL references. The real value_render_option
capability is unchanged on +cells-get (get_cell_ranges) via --include formula.
* chore: rename ppe x-tt-env lane to ppe_moa_canvas
* docs(sheets): sync skill description from spec (cloud-drive alias, lark-drive search, doubao routing)
* feat(sheets): restore pre-refactor shortcuts under backward/ for compatibility
The lark-sheets refactor renamed every shortcut (verb-noun → noun-verb,
e.g. +create-sheet → +sheet-create) and dropped the old commands. External
callers and the tests/cli_e2e/sheets suite still drive the legacy command
names (+create, +read, +write, +create-sheet, ...), which broke.
Re-add the pre-refactor implementations verbatim from main as an isolated
shortcuts/sheets/backward package (package rename only) and register
backward.Shortcuts() alongside sheets.Shortcuts(). Both sets mount under the
`sheets` service; their command names are fully disjoint (38 new vs 42 old,
zero overlap), so old and new commands coexist without collision.
* fix(sheets): resolve 30 golangci-lint v2.1.6 issues — copyloopvar, nilerr, unused
Removed 25 Go 1.22+ loop variable copies (copyloopvar) from test files where
tc := tc / tt := tt / c := c are no longer needed. Fixed 4 nilerr false
positives in flag_schema_validate.go by making intentional error discards
explicit (schema validation failures skip silently — best-effort guard).
Dropped unused batchOpDispatchKeys helper in batch_op_dispatch.go.
* feat(sheets): flag pre-refactor backward aliases via _notice and --help grouping
Nudge users whose lark-sheets skill predates the refactor to migrate off
the pre-refactor aliases (+read, +write, ...), without requiring anyone
to read --help.
- internal/deprecation: process-level pending Notice slot (mirrors
internal/skillscheck), surfaced in the JSON "_notice" envelope under a
"deprecated_command" key.
- internal/cmdutil: shared DeprecatedGroupID cobra group + helper so both
--help rendering and the unknown-subcommand path classify aliases the
same way.
- shortcuts/register.go: applySheetsCompatGroups splits the aliases into a
dedicated "update your skill" help group with "(-> +new)" pointers;
wrapSheetsBackwardDeprecation records the notice from Validate/Execute so
direct callers that never read --help still get flagged.
- cmd/root.go: extract composePendingNotice (now unit-testable) and split
availableSubcommandNames into current vs deprecated buckets while still
ranking unknown-subcommand suggestions across both.
* chore: drop hardcoded ppe lane routing from base security headers
The x-tt-env/x-use-ppe headers forced every request onto the
ppe_moa_canvas pre-release lane; they were only meant for exercising the
sheets refactor against the staging backend. Remove them so the CLI
routes to production by default.
* chore(sheets): promote lark-sheets skill to 2.0.0
Drop the -draft suffix now that the refactored sheets skill is ready to
ship.
* fix(sheets): correct +dropdown-get sheet-locator doc, finalize skill to 2.0.0
+dropdown-get requires a mandatory sheet selector — its Validate calls
resolveSheetSelector — so drop it from the "no sheet locator" exception
list in SKILL.md. It was wrongly grouped with +dropdown-update/+dropdown-delete,
which take only --ranges. +dropdown-get's own per-shortcut badge (公共四件套)
was already correct. Also finalize the skill version 2.0.0-draft -> 2.0.0.
* fix(sheets): enforce required-flag contract in batch sub-ops
Batch sub-ops reuse each shortcut's shared *Input builder through mapFlagView,
which seeds flag-defs defaults — so any required check that lives OUTSIDE the
builder (cobra MarkFlagsOneRequired, or a shortcut's own Validate) is silently
bypassed and the default value wins. Two gaps surfaced in PR review:
- +csv-put: with neither --start-cell nor --range set, start-cell's "A1"
default won and the paste silently anchored at A1. Require an explicit anchor
(guard on Changed, mirroring the standalone MarkFlagsOneRequired).
- +sheet-move: --index (plus >=0 bounds for index / source-index) was not
enforced in the batch path; a missing --index silently moved the sheet to the
front. Mirror SheetMove.Validate.
Also from the same review:
- +batch-update: an explicit --continue-on-error=false now wins over an
--operations envelope's continue_on_error:true (guard on Changed, not value).
- validateDropdownRanges rejects malformed sheet!range ("!A1", "Sheet1!",
"Sheet1!bad") at Validate instead of deferring to the server.
Tests added/updated for each path; full sheets suite green.
* fix(cli): surface skill in deprecated_command notice
deprecation.Notice carries Skill, but the _notice.deprecated_command payload
dropped it, forcing callers to parse `message` to learn which skill to update.
Emit `skill` when set, alongside the existing `replacement`.
* fix(sheets): harden batch type-checking and +workbook-create edge cases
From the branch code-review doc (3 findings):
- +batch-update sub-ops: `operations` is skipped by parse-time schema
validation and mapFlagView coerces a type-mismatched scalar to its zero
value, so "index":"abc" or "multiple":"true" silently became 0 / false and
wrote to the wrong place. translateBatchOp now runs validateRawTypes, which
checks each sub-op scalar against its flag-defs type and rejects mismatches.
- +workbook-create with empty arrays: buildInitialFillInput returned (nil,nil)
for empty rows while the caller wrote fill["excel_id"] unconditionally, so
--values '[]' panicked on a nil map and --headers '[]' produced an illegal
"A1:1" range. It now also returns nil when no cells survive (maxCols==0
guard) and Execute/DryRun skip the fill when fill==nil.
- +workbook-create partial failure: after the spreadsheet was created, a
first-sheet lookup or fill failure returned a bare fmt.Errorf, losing the new
token. It now returns a structured partial_success error carrying
spreadsheet_token in the detail so callers can retry or clean up.
Tests added for each path; sheets suite green.
* fix(cli): structured errors for unknown flags, print-schema, deprecated aliases
From the branch code-review doc (3 findings):
- pure-group UnknownFlags: installUnknownSubcommandGuard whitelists unknown
flags so a mistyped subcommand still reaches the suggestion path, but a lone
unknown flag before any subcommand (`sheets --badflag`) was swallowed and the
group fell through to help + exit 0. unknownSubcommandRunE now recovers the
swallowed tokens (from os.Args captured at Execute entry) and fails with a
structured unknown_flag error; a misplaced but known flag (e.g. --format)
still prints help.
- deprecated-alias notice: a backward-compat alias that fails a cobra-level
required flag short-circuits before RunE, so the Validate/Execute-wrapped
deprecation notice was dropped. Added Shortcut.OnInvoke, fired from PreRunE
(ahead of ValidateRequiredFlags); and the root legacy error fallback now
routes through the structured envelope when a deprecation is pending so the
migration hint survives. Non-deprecated errors keep the plain output.
- --print-schema: runShortcut returned the bare error from PrintFlagSchema. It
is now wrapped as a structured output.ExitError (type print_schema_error) so
agent introspection can parse the failure.
Tests added for each path; cmd + sheets suites green.
* fix(sheets): resolve --sheet-name via title + keep bare sheet selectors verbatim
Two review findings on the backward-compat layer:
- lookupSheetIndex matched only sm["sheet_name"], but get_workbook_structure
surfaces the sub-sheet display name as "title". Every --sheet-name path that
relies on the lookup (e.g. +sheet-move) failed to resolve. Fall back to
"title" when "sheet_name" is absent so either field resolves.
- +read / +write / +append fell back to --sheet-id when --range was omitted,
then routed that bare sheet id through the range normalizer. A sheet id that
looks A1-ish (letters+digits, e.g. "shtABC123") got mangled into
"shtABC123!shtABC123:shtABC123". Split the sheet-only path from the
range-normalization path: read/append pass the selector through verbatim,
write builds the rect from the selector's A1.
Regression tests added for both paths; sheets suite green.
* fix(sheets): silence nilerr/copyloopvar lint in batch type-check additions
- flag_view.go: annotate the fail-open return in validateRawTypes with
//nolint:nilerr (matches the repo convention for intentional fail-open).
- execute_paths_test.go: drop the redundant tc := tc copy (Go 1.22+ scopes
the loop var per iteration).
* test(sheets): data-driven required-flag parity contract for batch sub-ops
Adds TestBatchOp_RequiredFlagParity, the systematic standalone-vs-batch parity
check the branch review asked for. Data-driven over batchOpDispatch + flag-defs,
it asserts that for every batchable shortcut a +batch-update sub-op which
satisfies the sheet locator but omits the shortcut's business-required flags
fails in translateBatchOp, never silently defaulting.
This generalizes the hand-picked TestBatchOp_ErrorEquivalence / GuardsBeyondCobra
cases to the full 50-command surface and auto-covers shortcuts added later, so a
future refactor that moves a required check out of the shared *Input builder
(the failure mode behind the csv-put / sheet-move gaps) is caught here. 45
sub-tests run; locator-only commands (+sheet-delete / +sheet-hide / ...) have no
business-required flag to omit and are skipped. A missing-locator error is also
rejected so a bad fixture can't mask a real gap.
* refactor(sheets): drop unused int64 flag-type plumbing
No sheets flag-def declares an int64 type and RuntimeContext.Int64 had
zero callers, so remove the premature support: the RuntimeContext.Int64
helper, the registerShortcutFlagsWithContext int64 branch, the flagView
Int64 method + mapFlagView impl, and the typedDefault/validateRawTypes
int64 cases. float64 (consumed by --font-size) is kept.
* test(sheets): drop redundant copyloopvar copy in required-flag parity test
Go 1.22+ scopes the loop var per iteration, so `cmd, business := cmd, business`
in TestBatchOp_RequiredFlagParity is a no-op that trips the repo's copyloopvar
linter (same cleanup as 2132472). Behavior unchanged; 45 sub-tests still pass.
* revert(cli): drop non-interactive proxy-warning silencing
WarnIfProxied's interactivity gate is a generic CLI/agent-UX change
unrelated to the sheets refactor / backward-compat scope of this branch.
Split out to a dedicated PR; restore WarnIfProxied to its single-arg form
here (warn.go, warn_test.go, factory_default.go callers).
* docs(sheets): correct +workbook-info output field and batch +sheet-move index requirement
Sync from spec: +workbook-info returns sheet display name as 'title'
(sheet_name only as legacy fallback), and +sheet-move inside +batch-update
also requires --index, not just --sheet-id/--source-index.
* fix(sheets): reject non-integer numbers for batch int flags
validateRawTypes treated int and float64 identically (both only required a
JSON number), but mapFlagView.Int() truncates float64 via int(t), so a batch
sub-op accepted 1.9 for an int flag (e.g. --index) and silently floored it to
1. Standalone cobra rejects non-integer input for int flags at parse time;
enforce the same in the batch path with a math.Trunc check so batch/standalone
parity holds and positional fields can't land on a floored value.
* fix(cli): align flag-before-subcommand unknown_flag detail schema
The flag-before-subcommand recovery path emitted a Type: unknown_flag whose
detail only carried unknown_flags + command_path, diverging from
flagDidYouMean's unknown_flag detail (unknown, command_path, suggestions,
valid_flags). A consumer keyed on Type then saw two shapes for one Type.
Emit the same keys from both paths: add unknown (the offending flag; joined
when multiple), plus empty suggestions/valid_flags — the subcommand isn't
resolved at this point, so there is no meaningful flag universe to suggest
from, and the group's own flags would mislead. unknown_flags is retained as
the authoritative multi-flag field. Test locks the shared schema.
* perf(sheets): compile flag specs to Go to drop startup JSON parse
Every lark-cli invocation (sheets or not) unmarshaled data/flag-defs.json
(122KB) and data/flag-schemas.json (256KB) during package init, before
main(): flag-defs via the shortcut package vars (flagsFor runs at init),
flag-schemas via shortcuts.init() -> Shortcuts() -> commandsWithFlagSchema().
On a 0.5-core sandbox this cold-start cost lands on every command.
Compile both specs to Go at build time instead of parsing at runtime:
- flag-defs.json -> flag_defs_gen.go: flagDefs is a compiled map literal;
loadFlagDefs() returns it directly (no embed, no Unmarshal).
~3.3ms/4110 allocs -> ~0.57ms/539 allocs at sheets package init.
- flag-schemas.json -> flag_schemas_gen.go: only the command-name set
(commandsWithSchema) is compiled in; registration and the validate
fast-path gate on it without touching the 256KB blob. The blob stays
embedded and is unmarshaled lazily only on --print-schema or when
validating a command that has a schema. Removes the 256KB parse from
init entirely.
data/*.json remain the canonical source; *_gen.go are committed, derived
artifacts regenerated with `go generate ./shortcuts/sheets/...`
(shortcuts/sheets/internal/gen). *_gen_test.go guard source/generated drift.
No behavior change: flag rendering, required/enum/default, --print-schema,
and composite-flag schema validation verified unchanged; ./shortcuts/...
tests pass.
* ci(sheets): exempt internal/gen generators from forbidigo
The shortcuts/sheets/internal/gen code generator is a standalone
`package main` run via go:generate, not shortcut runtime code, so the
forbidigo bans on log.Fatal / os.ReadFile / fmt.Printf do not apply.
Making it "compliant" is impossible anyway: a structured error return
needs os.Exit (also banned), and the vfs alternative is blocked by
depguard shortcuts-no-vfs. Exempt shortcut internal/gen paths, matching
the existing _test.go and internal/vfs forbidigo exemptions.
* fix(cli): fail structured on flags before a missing subcommand
A pure group invoked with flags but no subcommand (e.g. `im --format=json`,
`sheets --format json`) silently fell through to help + exit 0, so an agent
could mistake a malformed call for success. The unknown-subcommand guard's
FParseErrWhitelist swallows the flags and leaves RunE with empty args; it now
recovers the raw flag tokens and fails structured:
- unknown flag(s) -> unknown_flag (unchanged)
- valid flag, no subcmd -> missing_subcommand (new, exit 2)
- bare group -> help, exit 0 (unchanged)
Because the group RunE is hook-wrapped, returning a real error also makes
plugin observers record the call as failed instead of ok (the lifecycle Err
is no longer flipped to nil).
Hardening from the same review:
- document the cobra error-text contract unknownFlagName relies on, in
both cmd/root.go and go.mod, so an i18n/reword is caught on upgrade.
- guard the reserved --print-schema/--flag-name registration with a Lookup
so a shortcut declaring same-named flags can't panic pflag.
Tests cover the new missing_subcommand path and the reserved-flag collision.
* fix(cli): don't flag group-valid globals as a missing subcommand
9f8dfa72 made a pure group invoked with flags but no subcommand fail with
missing_subcommand, keying on "any flag defined in the tree". That also matches
inherited global flags (--profile, ...), so `lark-cli --profile p im` and
`lark-cli im --profile p` errored with a misleading "flag --profile belongs to
a subcommand" instead of printing the group's help — a regression, since a bare
group carrying a global flag should print help.
Only treat a flag as missing_subcommand when it is valid on a subcommand but
not on the group itself or inherited (subcommandOnlyFlagTokens). A bare group
carrying only group-valid/global flags falls through to help; flags that
genuinely belong to an omitted subcommand (`im --format json`) still fail
structured, and unknown flags (`im --badflag`) still report unknown_flag.
Test covers a global flag on a bare group resolving to help.
---------
Co-authored-by: zhengzhijie <zhengzhijie.j@bytedance.com>
Input pre-check failures shared by every shortcut — @file/stdin input
resolution, enum validation, and unsupported --dry-run — now leave the
CLI as typed validation envelopes naming the offending flag, so scripts
and AI agents can branch on `param` instead of parsing prose. Wire type,
exit code, and message text are unchanged; the new fields are additive.
The shared layer also gains typed replacements for its legacy
error-producing helpers, so each business domain can migrate to typed
errors without rebuilding common plumbing, and a path-scoped lint guard
keeps migrated domains from sliding back.
Changes:
- Shared pre-check failures (input flags, enum values, dry-run support)
return typed validation errors carrying the offending flag as `param`.
- Every legacy error-producing helper in shortcuts/common has a typed
replacement that preserves the existing message text: validation and
flag-group checks, chat/user ID validation (callers name the flag so
`param` is ground truth), "me" open-id resolution, safe-path checks,
input-stat and save-error wrapping. Legacy helpers stay for
not-yet-migrated domains, marked deprecated — including the legacy
API-result classifier, whose typed route is runtime.CallAPITyped.
- A new errscontract rule rejects legacy common-helper calls on migrated
paths, so a migrated domain cannot silently reintroduce legacy
envelopes; drive is the first locked path and its last legacy
ID-helper calls are replaced.
The card message converter (shortcuts/im/convert_lib/card.go) previously
rendered a subset of card fields and had several mode-gated behaviors that
caused information to be silently dropped in concise mode. This PR audits
every element handler and brings the output up to full fidelity:
missing header fields are rendered, collapsible panels always expand, rich
element metadata (images, audio, video, overflow URLs, person names) is no
longer hidden behind cardModeDetailed, and several format bugs are fixed.
Change-Id: I422474ab6b7505e48ab5697793900df035be6e29
* feat(base): add base block shortcuts
* fix(base): use block scopes for base block shortcuts
* fix(base): split base block shortcut scopes
* docs(base): consolidate base block help
* docs(base): simplify block help wording
* test(base): cover base block shortcut execution
* feat(base): filter base block list by type
* docs(base): clarify base block ids
* docs(base): simplify docx block help
* docs(base): refine base block agent help
Add CLI-side validation for --message-ids in the mail +messages shortcut
to catch obviously invalid inputs before making any API call. The batch_get
endpoint would otherwise only reject malformed IDs server-side, returning
unclear errors.
Validation rules:
- Reject empty message-ids list
- Reject entries exceeding the server-mirrored batch limit of 20 IDs
- Reject entries with leading/trailing whitespace
- Reject entries containing control characters, whitespace, or path separators
- Reject duplicate message IDs
sprint: S2
Improve the --markdown vs --text guidance in the lark-im send/reply reference docs. Reposition --markdown as the recommended default for agents, add explicit selection rules, and reframe the docs around usage scenarios rather than caveats.
* feat(api): add --json flag as no-op alias for --format json
* feat(service): add --json flag as no-op alias for --format json
* feat(shortcut): add --json flag as no-op alias for --format json
Skip registration when a custom --json flag already exists on the
command (e.g. base shortcuts use --json for body input).
Change-Id: If66236cadeea7fa81811061cce775deff51b92ce
* refactor: extract FetchTAT sharing the TAT-rejection classifier
doResolveTAT minted the tenant access token inline. Extract the HTTP call
into FetchTAT(ctx, httpClient, brand, appID, appSecret) so callers that
already hold plaintext credentials — notably the post-config-init probe —
can validate them without a second keychain round-trip.
FetchTAT routes a non-zero TAT body code through the same
classifyTATResponseCode the credential layer already uses, so a rejection is
the canonical CategoryConfig / SubtypeInvalidClient (10003 / 10014) typed
error — identical to what every token-resolving command returns. Transport,
HTTP-status and JSON-parse failures stay raw (untyped) so callers can use
errs.IsTyped to separate a deterministic credential rejection from upstream
noise. doResolveTAT now delegates to FetchTAT; observable behavior unchanged.
* feat: validate credentials after config init
After config init saves the App ID / App Secret, fire a best-effort probe:
mint a tenant access token with the just-saved credentials, then POST the
application probe endpoint. When the credentials are deterministically
rejected, FetchTAT returns a typed errs.* error and runProbe propagates it,
so config init exits non-zero with the canonical ConfigError / invalid_client
envelope (the same one every other command shows for the same bad creds)
instead of letting the user discover the mistake on a later request.
Ambiguous failures (transport, HTTP non-200, JSON parse, timeout,
http-client init) come back untyped and are swallowed (errs.IsTyped is the
discriminator), so a valid configuration is never blocked by upstream noise.
The probe is wired into all four init paths and skipped when the user reused
an existing secret. The saved config is not rolled back on rejection: stdout
still records what was saved, stderr carries the typed error envelope.
Drive-domain errors now leave the CLI as typed, machine-branchable
envelopes — a stable `type` plus `subtype` and named fields (param,
params, retryable, log_id, hint) — so scripts and AI agents can branch on
structure and act on a recovery hint instead of parsing prose.
Changes:
- Every error produced in the drive domain — validation, file I/O, and the
failures returned from its Lark API calls — is emitted as a typed errs.*
error; the exit code is derived from the error category. Drive's API calls
now go through a shared typed classifier, so failures carry subtype,
troubleshooter, a recovery hint, and the request's log_id whether the
server returns it in the response body or the x-tt-logid header; an
already-typed network/auth error is never downgraded into a generic API
error.
- Known API conditions (resource conflict, cross-tenant, cross-brand, ...)
carry a recovery hint keyed by their error class; a command can refine
that hint with command-specific guidance.
- Batch partial failures (+push / +pull / +sync, where some items succeed
and some fail) now report an honest ok:false multi-status result on
stdout — the summary and every per-item outcome stay machine-readable —
and exit non-zero, instead of a misleading ok:true success envelope.
- Duplicate rel_path conflicts report each colliding path as a structured
params entry (RFC 7807 invalid-params style).
- Static guards lock the drive path so legacy error construction — direct
envelopes or the auto-classifying API helpers — cannot be reintroduced,
making drive the template for the remaining domains.
Output changes worth noting for consumers:
- Error envelopes now carry typed type/subtype and named fields; exit
codes follow the error category (malformed or incomplete API responses
are reported as internal errors rather than generic API errors).
- Batch partial failures (+push / +pull / +sync) emit an ok:false result
envelope on stdout (summary + per-item items[]) and exit non-zero; the
per-item results stay on stdout rather than in a stderr error envelope.
Errors surfaced through shared cross-domain helpers (scope precheck, media
import upload, metadata lookup, save-path resolution) are not yet typed;
they migrate with the shared layer in a follow-up change.
Interactive card messages (msg_type: interactive) can contain @user elements in their card
body. The json_attachment.at_users field stores resolved user info, but the user_id there is
the sender-side platform user_id — not the reading app's canonical open_id. When the backend
populates a mention_key on each at_users entry, it signals that the API-level mentions[]
array carries a more authoritative open_id and display name for the reading context. This PR adds
support for this two-level lookup: it threads the raw mentions[] array into the card converter,
indexes it by mention_key for O(1) access, and renders the canonical open_id + display name
whenever the link is resolvable. All existing fallback paths (no mention_key, nil mentions) are
preserved without behavioral change.
Change-Id: I00f846d76482adba315d07361c35909b71ca74c7
Follow-up to #1223. The hand-written FLAGS block in `lark-cli --help`
restated leaf-command flags at the root level — flags that are not
registered on the root command (they error "unknown flag" there). Even
trimmed to an illustrative example list, it duplicated information Cobra's
per-command `--help` already renders authoritatively, and any static list
in root help drifts from the real per-command flag sets over time.
Drop the section entirely: Cobra's per-command `Flags:` output is the
single source of truth. `USAGE:`/`EXAMPLES:` still show flags in context,
and the `Flags:` block at the bottom of root help lists the actual root
flags. Also removes the now-obsolete TestRootLong_FlagsSectionPointsToCommandHelp.
The hand-written FLAGS block in `lark-cli --help` listed --params, --data,
--as, --format, --page-all, --page-size, --page-limit, --page-delay, -o,
--jq, -q and --dry-run as if they were global flags. None are registered
on the root command — they all error "unknown flag" at the top level and
exist only on leaf commands (api, service). The block also contradicted
the Cobra-generated "Flags:" section rendered directly below it, which
shows only -h/--help, --profile, -v/--version.
Replace it with a short illustrative example list (common flags first) and
a pointer to `lark-cli <command> --help` for the full per-command set.
Root help stays a discovery signpost without claiming the flags are global
or restating defaults/descriptions that drift from the real flag sets.
Change-Id: Ia1cab889dd70b6b49a61dac468dedfd7fe39043f
Simplifies the markdown-to-post rendering pipeline in the IM shortcut. The previous
implementation split markdown at blank-line boundaries into multiple post paragraphs,
using zero-width space (\u200B) sentinel characters to preserve visual spacing.
While well-intentioned, this approach introduced fragility around edge cases such as
blank lines inside fenced code blocks, messages with only blank lines, and interactions
with the heading-normalization pass. This change consolidates rendering back into a
single {"tag":"md"} segment, making the output more predictable, the code significantly
easier to follow, and the test surface easier to maintain.
Change-Id: Ic2870ecbcb31ae7d36121f120102f2ff964f5169
* feat: unconditionally inject --format flag for all shortcuts
Removes three HasFormat guards in runner.go so every shortcut
gets --format regardless of the Shortcut.HasFormat field value.
Shortcuts that already define a custom 'format' flag in Flags[]
are skipped to avoid redefinition panics (e.g. mail +triage, +watch).
HasFormat is retained in the struct but marked deprecated.
Change-Id: I5e8fe07e839d5aed4cefaf7d753dabbaee68fb6e
* test: isolate config dir in format-universal test
Change-Id: I3a59942aa8a6753cd949ca42f2a19a72f032ff55
* test: revert unnecessary config-dir isolation (mount-only test)
Change-Id: I0146e5a2f57f5419863bdeeaa1a662fd8f70bddf
internal/util imported internal/proxyplugin (SharedTransport, FallbackTransport,
NewHTTPClient, and WarnIfProxied via proxyPluginStatus), so a foundational util
package depended up into a feature package, pulling binding/core/vfs into the
transitive cone of every util importer.
Move internal/proxyplugin -> internal/transport and make it the single owner of
outbound transport: fold the two SharedTransport functions into one Shared()
(proxy-plugin override -> LARK_CLI_NO_PROXY -> http.DefaultTransport), and move
Fallback/NewHTTPClient/WarnIfProxied/DetectProxyEnv/noProxyTransport out of the
now-deleted internal/util/proxy.go into the new package. The proxy-plugin probe
is demoted to a private pluginTransport(); the duplicate redactProxyURL collapses
to one. internal/util keeps no proxy code and is a leaf again.
Re-point all consumers (registry, doctor, config, auth, cmdutil, update) to
internal/transport. Behavior-preserving: package move + symbol rename + dedup.
Two new tests lock the fail-closed contract (plugin overrides NO_PROXY; malformed
config never falls through to direct egress).
Every failure on the authentication, authorization, and configuration
path now surfaces as a typed structured error instead of an ad-hoc
envelope. Users and scripts that consume CLI output get:
- a fixed nine-category taxonomy on the wire, each mapped to a
stable shell exit code (authentication/authorization/config = 3,
network = 4, internal = 5, policy = 6, confirmation = 10)
- identity-aware detail fields (missing_scopes, requested_scopes,
granted_scopes, console_url, log_id, retryable, hint) carried
uniformly on the envelope
- a single canonical policy envelope at exit 6; the legacy
auth_error carve-out is retired
- per-subtype canonical message + hint that preserves Lark's
diagnostic phrasing and routes recovery to the right actor:
app developer (app_scope_not_applied), user (missing_scope,
token_scope_insufficient, user_unauthorized), or tenant admin
(app_unavailable, app_disabled)
- wrong app credentials classify as config/invalid_client whether
surfaced by the Open API endpoint (99991543) or the tenant
access-token mint endpoint (10003 / 10014), instead of
collapsing to a transport error or api/unknown
- local shortcut scope preflight emits the same
authorization/missing_scope envelope (identity + deterministic
missing-scope set) used by the post-call permission path, so AI
consumers read the same structured shape from precheck and from
server-returned permission denial
- streaming download/upload failures keep the same network subtype
split (timeout / TLS / DNS / transport) as the non-stream path
instead of collapsing every cause to a generic transport failure
- console_url is carried only on the bot-perspective
app_scope_not_applied envelope (where the recovery action is
"developer applies the scope at the developer console"); the
user-perspective missing_scope envelope drops the field, since
the only actionable user recovery is `lark-cli auth login --scope`
and pointing an end user at a console they cannot modify is
misleading
- bind workflows (Hermes / OpenClaw / lark-channel) flatten dynamic
Type tags to wire 'config' with the original module name kept
as a metric label
All 10 typed errors are cause-bearing, nil-safe on .Error() and
.Unwrap(), and defensively clone slice setter inputs. Four lint
rules (CheckNilSafeError / CheckBuilderImmutable / CheckUnwrapSymmetry
/ CheckBuildAPIErrorArms) lock these invariants on migrated paths.
* feat(platform): support multiple policy rules per plugin
Extend the command policy framework from single-Rule to multi-Rule
semantics. A plugin (or policy.yml) may now contribute several scoped
Rules; the engine combines them with OR -- a command is allowed when it
satisfies every axis of at least one rule. This lets one integration
apply different risk ceilings and identity restrictions to different
command groups.
The cross-plugin fail-closed boundary is preserved: two distinct plugins
both calling Restrict still aborts startup (multiple_restrict_plugins).
Single-Rule behaviour is fully backward compatible -- the rejection
reason_code / rule_name / envelope shape are byte-for-byte unchanged;
multi-rule rejection surfaces the aggregate reason_code no_matching_rule.
- engine: New keeps single-rule compat, add NewSet for OR over rules
- resolver: dedupe by owner (one plugin may contribute many rules),
return []*Rule; yaml gains a top-level rules: list
- registrar/builder/staging: Restrict may be called more than once;
retire the double_restrict error
- config policy show / config plugins show: emit a rules array
- inventory: PluginEntry.Rules is now a slice (fixes last-rule-wins
overwrite when a plugin contributes multiple rules)
* fix(platform): clone rules in Builder.Restrict and inventory snapshot
Address review feedback. Builder.Restrict stored the caller's *Rule
directly, so reusing and mutating one Rule object across multiple
Restrict calls collapsed entries to the last mutation; clone the rule and
its slices on append, mirroring the staging registrar.
BuildInventory likewise reused the source Allow/Deny/Identities slices;
copy them when building the RuleView snapshot instead of relying on
cloneInventory downstream.
Add a regression test: reusing and mutating one Rule across two Restrict
calls now yields two independent rules.
* fix(platform): skip yaml when a plugin owns policy; reject empty rules list
Two policy-config robustness fixes from review:
- A malformed ~/.lark-cli/policy.yml could abort a plugin-governed
binary. applyUserPolicyPruning read yaml before resolving, and
build.go fail-closes on any policy error when a plugin is present.
Plugin rules shadow yaml anyway, so skip reading yaml entirely when a
plugin contributed rules -- an unrelated broken file on the user's
machine can no longer lock the CLI.
- A present-but-empty "rules: []" collapsed to a single all-zero Rule
that allows every annotated command ("looks like policy, enforces
almost nothing"). yaml.Parse now distinguishes absent from
present-but-empty (Rules is a pointer) and rejects the empty list.
Add regression tests for both.
Fix 3 occurrences of --minute-token (singular) to --minute-tokens
(plural) in lark-vc-recording.md to match the actual CLI flag
definition in minutes_download.go.
The size==1 (64-bit "largesize") branch of all three MP4 box walkers
(findMP4Box, readMp4DurationBytes, readMp4Duration) set boxEnd to the raw
largesize instead of offset+largesize — even though the 32-bit branch right
below correctly uses offset+size. Two consequences:
- Correctness: for any MP4 that carries a 64-bit box size at a non-zero
offset, the box walk is computed from the wrong end, so the moov/mvhd
lookup is truncated and the media duration is silently lost.
- Robustness/security (CWE-190): the unguarded uint64->int(64) conversion of
a largesize with the high bit set yields a negative boxEnd. The in-memory
walkers then assign it to offset and feed it back as a slice index
(data[offset:]), panicking with "slice bounds out of range" and crashing
the CLI on a crafted or corrupt MP4. This is reachable via URL-sourced IM
media, whose bytes the caller does not control.
Fix: compute boxEnd as offset+largesize (matching the 32-bit branch) and
reject largesize values smaller than the 16-byte header or larger than the
remaining input. Malformed media now honours the parsers' best-effort
contract by returning 0/-1 instead of panicking, and the bounds guarantee
the conversion can no longer overflow.
Add regression tests covering both the overflow (must not panic) and a
64-bit box at a non-zero offset (must walk correctly).
Add a new --types flag (string_slice; values from {group, p2p}) to
+chat-list, backed by the new GET /open-apis/im/v1/chats `types` query
parameter. Accepts CSV (--types group,p2p) and repeated-flag forms
(--types group --types p2p).
Defaults to groups-only (backward compatible). Under user identity,
p2p single chats appear with chat_mode="p2p" plus p2p_target_type /
p2p_target_id fields. Under bot identity:
- --types=p2p alone is rejected at validation
- --types=p2p,group is silently downgraded to types=group (no runtime
notice; skill docs document this contract)
Updates Shortcut.Description, lark-im SKILL.md (frontmatter trigger
+ shortcut table row), and the chat-list reference doc with command
examples, the new parameter, output field documentation, and a
dedicated "Bot identity and p2p" section.
Change-Id: I637ce23b3c6ce4ec350f0ac26dbac8120761bb71
make unit-test # Required before PR (runs with -race)
make test# Full: vet + unit + integration
make build # Build (runs fetch_meta first)
make unit-test # Required before PR (runs with -race where supported, e.g. amd64/arm64)
make live-skills-test # Opt-in real Skills CLI tests; runs with isolated user directories
make test# Full: vet + unit + integration
```
## Notification Opt-Outs
@@ -75,12 +76,50 @@ The one rule to internalize: **every error message you write will be parsed by a
### Structured errors in commands
`RunE` functions must return `output.Errorf` / `output.ErrWithHint` — never bare `fmt.Errorf`. AI agents parse stderr as JSON; bare errors break this contract.
Command-facing failures must be typed `errs.*` errors — never the legacy `output.Err*` helpers and never a final bare `fmt.Errorf`. AI agents parse the stderr envelope's `type` / `subtype` / `param` / `hint` fields to decide their next action; the full taxonomy lives in `errs/ERROR_CONTRACT.md`.
Picking a constructor:
| Failure | Constructor |
|---------|-------------|
| User flag/arg fails validation | `errs.NewValidationError(errs.SubtypeInvalidArgument, ...).WithParam("--flag")` |
| Valid request, wrong system state | `errs.NewValidationError(errs.SubtypeFailedPrecondition, ...).WithHint(...)` |
| Lark API returned `code != 0` | `runtime.CallAPITyped` (shortcuts) / `errclass.BuildAPIError` (raw responses) — never hand-build |
| Network / transport failure | `errs.NewNetworkError(errs.SubtypeNetworkTransport, ...)` |
| Local file I/O failure | `errs.NewInternalError(errs.SubtypeFileIO, ...)` — validate the path first (`validate.SafeInputPath` / `SafeOutputPath`) and use `vfs.*` |
| Unclassified lower-layer error as final | `errs.NewInternalError(errs.SubtypeUnknown, ...).WithCause(err)` |
| Lower layer already returned a typed error | pass it through unchanged — re-wrapping downgrades its classification |
Signatures that are easy to guess wrong:
-`runtime.CallAPITyped(method, url string, params map[string]interface{}, data interface{}) (map[string]interface{}, error)` — it performs the HTTP request itself and classifies `code != 0` into a typed error; just return the error it gives you.
- Typed pass-through check: `if _, ok := errs.ProblemOf(err); ok { return err }` — `ProblemOf` returns `(*errs.Problem, bool)`, not a nilable pointer.
-`.WithParam` exists only on `*errs.ValidationError`. `InternalError` / `NetworkError` have no param field — file or endpoint context goes in the message or `.WithHint(...)`.
`forbidigo` + `lint/errscontract` reject the legacy `output.Err*` helpers, bare final `fmt.Errorf` / `errors.New`, and legacy envelope literals on migrated paths. Beyond what lint catches, three authoring conventions apply:
- Preserve the underlying error with `.WithCause(err)` so `errors.Is` / `errors.Unwrap` keep working.
-`param` names only the user input that actually failed. Recovery guidance goes in `.WithHint(...)`; machine-readable recovery fields (`missing_scopes`, `log_id`) carry server/system ground truth only — never caller-side guesses.
- Error-path tests assert typed metadata via `errs.ProblemOf` (`category` / `subtype` / `param`) and cause preservation, not message substrings alone.
### stdout is data, stderr is everything else
Program output (JSON envelopes) goes to stdout. Progress, warnings, hints go to stderr. Mixing them corrupts pipe chains.
### Typed data over loose maps
Parse `map[string]interface{}` into a typed struct at the boundary — one projection function per shape — and let everything downstream consume struct fields, not string keys. A typo'd map key compiles fine and fails at runtime, which an agent then debugs blind.
Use distinct types when two values could be swapped silently: see `internal/meta.Token` — a bare string compiles on either side of a string/string signature, a distinct type does not.
Legacy loose-map code exists in older paths. Match its call sites when touching it, but do not copy the pattern into new code.
### Transcribe faithfully — no silent fallbacks
When code echoes input onward (request previews, transformations, proxies), transcribe verbatim. A `default:` branch that coerces unrecognized input into a plausible value ("unknown HTTP verb → GET") makes the output lie, and an agent reasons from the lie.
The same rule applies to flag combinations and internal wiring: if a requested option cannot be honored, return a typed validation error — never silently substitute another behavior and exit 0. Silent guesses (defaulting a missing identity, discarding writes on a nil writer) are bugs even when every current caller happens to avoid them.
### Use `vfs.*` instead of `os.*`
All filesystem access goes through `internal/vfs`. This enables test mocking.
@@ -92,6 +131,7 @@ CLI arguments are untrusted (they come from AI agents). Call `validate.SafeInput
### Tests
- Every behavior change needs a test alongside the change.
- A contract test must fail if the implementation is reverted. If you can undo the code change and the suite stays green, the contract is not pinned — assert the new field/behavior directly, not a happy-path substring.
-`cmdutil.TestFactory(t, config)` for test factories.
-`t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())` to isolate config state.
- **im**: Clarify audio message opus requirement (#1271)
### Build
- **ci**: Add public content safeguards and reduce false positives
## [v1.0.57] - 2026-06-23
### Features
- **slides**: Add `+screenshot` to capture slide page images (or render a single `<slide>` XML snippet), returning the local file path instead of Base64 (#1358)
- **base**: Support record comments (#1043)
- **search**: Surface search API notices (#1413)
### Bug Fixes
- **mail**: Resolve folder/label filter once per `+triage list` call (#1512)
- **meta**: Backfill enum value descriptions from options (#1541)
| 📋 Project | Meegle — manage work items, schedules, and data via the standalone [meegle-cli](https://github.com/larksuite/meegle-cli) (install separately) |
| 🔗 Apps | Develop, deploy HTML, web pages and applications |
| 🔗 Apps | Create Spark/Miaoda apps, publish HTML/static sites, run cloud generation, and manage access scope |
## Installation & Quick Start
@@ -198,7 +198,7 @@ Prefixed with `+`, designed to be friendly for both humans and AI, with smart de
```bash
lark-cli calendar +agenda
lark-cli im +messages-send --chat-id "oc_xxx" --text "Hello"
To check whether a command succeeded, test `ok == true` (or the exit code) — **not**`code == 0`. Unlike raw OpenAPI responses (`{"code": 0, "msg": "ok", ...}`), the success envelope carries no `code` or `msg` field; `code` appears only inside `error` as the upstream OpenAPI code. See [errs/ERROR_CONTRACT.md](errs/ERROR_CONTRACT.md) for the full error taxonomy.
The primary user lookup for user identity: search by keyword or email, resolve known ids with --user-ids, or get yourself with --user-ids me — it does by-id reads too, so as a user you rarely need `+get-user`. Each match returns an open_id and p2p_chat_id to chain into follow-ups.
fmt.Sprintf("strict mode is %q, user login is disabled in this profile",mode),
"if the user explicitly wants to switch to user identity, see `lark-cli config strict-mode --help` (confirm with the user before switching; switching does NOT require re-bind)")
"strict mode is %q, user login is disabled in this profile",mode).
WithHint("if the user explicitly wants to switch to user identity, see `lark-cli config strict-mode --help` (confirm with the user before switching; switching does NOT require re-bind)")
returnoutput.ErrValidation("--exclude requires --scope, --domain, or --recommend to be specified")
returnerrs.NewValidationError(errs.SubtypeInvalidArgument,"--exclude requires --scope, --domain, or --recommend to be specified").WithParam("--exclude")
log("Note: this command blocks until authorization is complete. For non-streaming agent harnesses, use --no-wait --json, send the verification URL as the final message of the turn, then run --device-code in a later step after the user confirms authorization.")
returnoutput.ErrValidation("please specify the scopes to authorize")
returnerrs.NewValidationError(errs.SubtypeInvalidArgument,"please specify the scopes to authorize").WithParam("--scope")
"hint":fmt.Sprintf("**MUST generate QR code AND display it:** You MUST call lark-cli auth qrcode to convert verification_url into a QR code. This is a required step, do NOT skip it. Prefer PNG QR code (--output); use ASCII (--ascii) only when the user explicitly requests it.**CRITICAL: You MUST include the QR image in your response.** Generating the file alone is NOT enough—use image tags, inline images, or file attachments to display it.**Display order:** Output the URL first, then place the QR code image below the URL.**URL Output Rules:** Treat verification_url as an opaque string that cannot be modified. Do NOT URL-encode/decode or add spaces/punctuation. For agent harnesses that only deliver final turn messages, make the QR code image (or URL) the final message of the turn and return control to the user; do not block on --device-code in the same turn. After the user confirms authorization in a later step, run: lark-cli auth login --device-code %s",authResp.DeviceCode),
"hint":"**MUST generate QR code AND display it:** You MUST call lark-cli auth qrcode to convert verification_url into a QR code. This is a required step, do NOT skip it. Prefer PNG QR code (--output); use ASCII (--ascii) only when the user explicitly requests it."+
"**CRITICAL: You MUST include the QR image in your response.** Generating the file alone is NOT enough—use image tags, inline images, or file attachments to display it."+
"**Display order:** Output the URL first, then place the QR code image below the URL."+
"**URL Output Rules:** Treat verification_url as an opaque string that cannot be modified. Do NOT URL-encode/decode or add spaces/punctuation."+
"For agent harnesses that only deliver final turn messages, make the QR code image (or URL) the final message of the turn and return control to the user; do not block on --device-code in the same turn. **Before ending the turn, tell the user to come back and notify you after completing authorization.**"+
"**After the user confirms authorization:** YOU must execute `lark-cli auth login --device-code <device_code>` yourself."+
"**Do NOT cache verification_url or device_code for future use.** Always run `lark-cli auth login --no-wait --json` fresh when authorization is needed.",
}
encoder:=json.NewEncoder(f.IOStreams.Out)
encoder.SetEscapeHTML(false)
iferr:=encoder.Encode(data);err!=nil{
returnoutput.Errorf(output.ExitInternal,"internal","failed to write JSON output: %v",err)
returnerrs.NewInternalError(errs.SubtypeSDKError,"failed to write JSON output: %v",err).WithCause(err)
}
returnnil
}
// Step 2: Show user code and verification URL.
// Both branches surface AgentTimeoutHint, but on different channels:
// JSON mode embeds it as a structured field (so an agent that captures
// stdout into a JSON parser sees it without stream-mixing surprises),
// text mode prints to stderr (alongside the URL prompt).
// JSON mode embeds AgentTimeoutHint as a structured field so agents that
// capture stdout into a JSON parser see it without stream-mixing surprises.
// Text mode prints the hint to stderr only when running under a non-TTY
// (i.e. piped / agent harness), since humans reading a terminal don't need
returnoutput.Errorf(output.ExitValidation,"missing_output","output file path is required for PNG mode. Use --output or -o flag to specify the output file path.")
returnerrs.NewValidationError(errs.SubtypeInvalidArgument,"output file path is required for PNG mode. Use --output or -o flag to specify the output file path.").WithParam("--output")
}
ifopts.Size<32{
returnoutput.Errorf(output.ExitValidation,"invalid_size",fmt.Sprintf("size must be at least 32, got %d",opts.Size))
returnerrs.NewValidationError(errs.SubtypeInvalidArgument,"size must be at least 32, got %d",opts.Size).WithParam("--size")
}
ifopts.Size>1024{
returnoutput.Errorf(output.ExitValidation,"invalid_size",fmt.Sprintf("size must be at most 1024, got %d",opts.Size))
returnerrs.NewValidationError(errs.SubtypeInvalidArgument,"size must be at most 1024, got %d",opts.Size).WithParam("--size")
Message:fmt.Sprintf("config init is refused inside %s context (would create a parallel app and shadow the existing %s binding)",ws.Display(),ws.Display()),
Hint:"see `lark-cli config bind --help` to bind lark-cli to the Agent's existing app instead. Pass --force-init only if the user explicitly wants a separate app in this workspace.",
"config init is refused inside %s context (would create a parallel app and shadow the existing %s binding)",ws.Display(),ws.Display()).
WithHint("see `lark-cli config bind --help` to bind lark-cli to the Agent's existing app instead. Pass --force-init only if the user explicitly wants a separate app in this workspace.")
}
// hasAnyNonInteractiveFlag returns true if any non-interactive flag is set.
// Non-terminal: cannot run interactive mode, guide user to --new
if!f.IOStreams.IsTerminal{
returnoutput.ErrValidation("config init requires a terminal for interactive mode. Run with --new to create a new app:\n lark-cli config init --new\nThis command blocks until setup is complete and outputs a verification URL. Run it in the background, then retrieve the URL from its output.")
returnerrs.NewValidationError(errs.SubtypeInvalidArgument,"config init requires a terminal for interactive mode. Run with --new to create a new app:\n lark-cli config init --new\nThis command blocks until setup is complete and outputs a verification URL. Run it in the background, then retrieve the URL from its output.")
"This command must be run from an interactive macOS session (e.g. Terminal.app or iTerm) where the system Keychain is reachable. Running it from inside a sandbox / automation context that blocks Keychain access cannot succeed by design.",
)
returnerrs.NewInternalError(errs.SubtypeSDKError,
"keychain downgrade failed: %v",err).
WithHint("This command must be run from an interactive macOS session (e.g. Terminal.app or iTerm) where the system Keychain is reachable. Running it from inside a sandbox / automation context that blocks Keychain access cannot succeed by design.").
Short:"Downgrade keychain storage to a local file (macOS only)",
Long:`Downgrade keychain storage to a local file. This subcommand is only supported on macOS; on this platform the keychain layer already uses local files.`,
RunE:func(cmd*cobra.Command,args[]string)error{
returnoutput.ErrValidation("keychain-downgrade is only supported on macOS")
returnerrs.NewValidationError(errs.SubtypeInvalidArgument,"keychain-downgrade is only supported on macOS")
@@ -64,8 +65,8 @@ Use 'event schema <EventKey>' for parameter details.`,
cmd.Flags().StringVar(&o.jqExpr,"jq","","JQ expression to filter output")
cmd.Flags().BoolVar(&o.quiet,"quiet",false,"Suppress informational messages on stderr")
cmd.Flags().StringVar(&o.outputDir,"output-dir","","Write each event as a file in this directory (relative paths only; absolute paths and ~ are rejected to prevent path traversal)")
cmd.Flags().IntVar(&o.maxEvents,"max-events",0,"Exit after N successful emits (0 = unlimited). Multi-worker EventKeys may emit up to workers-1 past N before all workers stop.")
cmd.Flags().DurationVar(&o.timeout,"timeout",0,"Exit after DURATION (e.g. 30s, 2m). 0 = no timeout. Timeout is a normal exit (code 0; stderr 'reason: timeout').")
cmd.Flags().IntVar(&o.maxEvents,"max-events",0,"Exit after N successful emits (0 = unlimited). Multi-worker EventKeys may emit up to workers-1 past N before all workers stop. Bounded runs ignore stdin EOF.")
cmd.Flags().DurationVar(&o.timeout,"timeout",0,"Exit after DURATION (e.g. 30s, 2m). 0 = no timeout. Timeout is a normal exit (code 0; stderr 'reason: timeout'). Bounded runs ignore stdin EOF.")
cmd.Flags().String("as","auto","identity type: user | bot | auto (must match EventKey's declared AuthTypes)")
"run `lark-cli auth login --scope \"%s\"` in the background. It blocks and outputs a verification URL — retrieve the URL and open it in a browser to complete login.",
strings.Join(missing," "),
)
strings.Join(missing," "))
}
// preflightEventTypes verifies every RequiredConsoleEvents entry is subscribed in the app's current published version.
// preflightEventTypes verifies every RequiredConsoleEvents entry is subscribed
// in the app's console 底账 — published app_versions for event subscriptions,
// application/get subscribed_callbacks for callback subscriptions.
WithHint("choose a different name, or remove the existing profile first").
WithParam("--name")
}
// Check app-id uniqueness — keychain stores secrets by appId, so
// multiple profiles sharing the same appId would collide on credentials.
for_,a:=rangemulti.Apps{
ifa.AppId==appID{
returnoutput.ErrValidation("app-id %q is already used by profile %q; each profile must have a unique app-id",appID,a.ProfileName())
returnerrs.NewValidationError(errs.SubtypeFailedPrecondition,"app-id %q is already used by profile %q; each profile must have a unique app-id",appID,a.ProfileName()).
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
