14 Commits

Author	SHA1	Message	Date
liangshuo-1	b8f56dbc0b	feat(apps): support absolute and relative upload paths (#2005)	2026-07-23 17:52:49 +08:00
anngo-nk	3c2cc273f7	feat(apps): design_html support, creative-design skill, unified TOS publish (#1901) ... * 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>	2026-07-20 20:15:43 +08:00
linchao5102	baf6050f8e	feat(apps): add role management shortcuts (#1881)	2026-07-16 14:09:41 +08:00
木杉	8897196dee	feat(apps): add automation trigger commands for Miaoda (#1886) ... * 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	2026-07-15 15:55:53 +08:00
liangshuo-1	37d490a198	fix: unify dry-run output contract (#1870) ... * fix: unify dry-run output contract * fix: address dry-run review feedback * fix(dryrun): tighten preview contract and unify data shape - transcribe HTTP method verbatim in previews (HEAD/OPTIONS were reported as GET); reject an empty method in api with a typed error - unify the dry-run data payload across api/service/shortcut paths: {api, context?: {app_id, user_open_id}}; drop data.as — the envelope top-level identity is the single identity source - mark pretty dry-run stdout with '# dry-run: request not sent' so logs that drop stderr still show it was a preview - extract the shared preview builder, collapse PrintDryRunWithFile's loose params into FileUploadMeta, and fail loudly on nil previews - revert description-marker identity parsing: stale prose must not override corrected accessTokens (blocks legal user calls on images.create); identity gating keys off accessTokens only - pin the new contracts with tests: verbatim method, three-way context parity, nil-preview error, empty-context omission, marker line * docs(agents): add typed-data, faithful-transcription, and contract-test conventions - typed struct at the boundary over map[string]interface{} threading; distinct types where values could swap silently (internal/meta.Token) - transcribe input verbatim in previews/transformations; reject unhonorable flag combinations with typed errors instead of silently substituting behavior - contract tests must fail when the implementation is reverted * test: migrate dry-run tests grown on main to the envelope format main gained raw-format dry-run readers while the PR was in flight (wiki drive export #1802, drive list comments #1845, slash commands, sheets history, docs fetch, mail draft-send/triage, vc meeting events). Migrate them to the envelope accessors (clie2e.DryRunGet / data-wrapped decoders) and drop the now-redundant DryRunData extractions in files unified on DryRunGet. --------- Co-authored-by: guokexin.02 <264159873+Tantanz20020918@users.noreply.github.com>	2026-07-14 10:54:16 +08:00
chenxingyang1019	1a9f637866	fix(apps): make db --environment optional, auto-select branch server-side (#1735) ... * 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	2026-07-08 14:06:22 +08:00
wangwei	75926f9744	feat(apps): add db, file, openapi-key and observability shortcuts (#1596) ... * 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>	2026-06-30 21:11:27 +08:00
evandance	c5b5aece33	refactor: retire legacy error envelopes and enforce typed contract (#1449) ... * refactor: retire legacy error envelopes and enforce typed contract Consolidate all command error reporting onto the typed errs.* contract, remove the legacy error surface that predated it, and tighten the lint guards so the contract holds across the whole repository going forward. Every failure now reaches stderr as one envelope shape: a category, an optional subtype, a human- and agent-readable message, and a recovery hint, with invalid parameters listed under `params`. The legacy ExitError envelope, its constructors, and the boundary bridge that promoted untyped config and authorization errors are deleted, leaving a single path from error to wire. Predicate commands keep their silent-exit behavior through a dedicated signal that carries only an exit code. Infrastructure paths that still emitted ad-hoc envelopes — flag parsing, unknown commands and subcommands, plugin and policy guards, confirmation prompts, and auth/config failures — now classify into the same taxonomy. Business, API, auth, and config exit codes are preserved; the one behavioral change is that Cobra usage failures (missing required flag, unknown command, bad arguments) now emit the typed validation envelope and exit 2, matching the explicit flag and subcommand guards, instead of Cobra's plain-text exit 1. Enforcement is repo-wide rather than per-path: - The errscontract guards run by default everywhere instead of through a migration allowlist, so legacy envelopes cannot be reintroduced anywhere. - errorlint runs across the whole repository: every error wrap must use %w and every comparison must use errors.Is/errors.As, so interior wraps stay legal but can no longer break the chain the typed boundary relies on. - The errs-no-bare-wrap guard is keyed by structural prefix instead of an explicit per-domain allowlist, so new shortcut domains are covered without editing a list. It runs where forbidigo is enabled (the shortcut domains and the auth/config/service command groups); repo-wide chain integrity for the remaining command paths is carried by errorlint above. * test: align cli_e2e success assertions to the ok envelope The api and service success path now emits the {"ok":true} envelope, so the cli_e2e workflow assertions that still expected the old {"code":0} shape via AssertStdoutStatus(t, 0) fail once they run with live credentials. Switch those workflow assertions to AssertStdoutStatus(t, true); the fake-payload helper test in core_test.go keeps its code-shape assertion.	2026-06-17 19:42:38 +08:00
raistlin042	0fbfe68726	docs: drop Miaoda brand word from apps command help text (#1399)	2026-06-13 14:00:30 +08:00
raistlin042	dfa26c38f6	feat: exclude .git directory from apps +html-publish package (#1396) ... * feat: exclude .git from html-publish package walk * docs: note .git auto-exclusion in html-publish reference * test: update html-publish e2e for .git exclusion * docs: simplify .git skip comment in html-publish walker	2026-06-11 14:58:58 +08:00
linchao5102	6d8dc402ac	fix: support git credential dry-run (#1390) ... * fix: support git credential dry-run * test: cover git credential dry-run output	2026-06-11 01:49:06 +08:00
raistlin042	2c703f2fce	feat: apps support multi dev modes (#1175) ... * 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>	2026-06-10 21:45:45 +08:00
raistlin042	e93e2a98e1	feat(apps): replace +html-publish cwd hard-reject with credential-file scan (#1072) ... * feat(apps): replace +html-publish cwd hard-reject with credential-file scan The previous --path == "." block was a coarse heuristic: it caught the common foot-gun of publishing a repo root, but also rejected legitimate clean cwds, and let a ./dist with a forgotten .env ship the secret through anyway (the sensitive-paths scanner was advisory and never ran on the Execute path). Move the gate from path shape to path content: - Validate now walks --path candidates and rejects publishes that include well-known credential files (.env / .env.* / .npmrc / .netrc / .git-credentials / .aws/credentials / .gcloud/credentials* / .docker/config.json / .kube/config). Living in Validate (not DryRun) means dry-run returns non-zero on hit too, so the dry-run preview matches Execute. - Narrow the credential pattern set. .git/, SSH private keys, *.pem and *.key are out of scope -- they're not env-token files and the false-positive rate (public certs, docs about key formats) is high. - Add --allow-sensitive as the escape hatch for legitimate cases (e.g. a docs site shipping .env.example on purpose). DryRun surfaces the waived list in sensitive_waived so the caller can relay it. - Drop the cwd defense-in-depth in runHTMLPublish. A clean cwd is now a valid publish target. The lark-apps skill and the html-publish reference are updated to describe the new gate, the override flag, and the patterns now explicitly out of scope. * feat(apps): drop .gcloud/* from credential-file scan The .gcloud/credentials pattern matched a non-existent path: gcloud's actual config dir is ~/.config/gcloud/ (XDG-based), and the real credential files there are credentials.db / access_tokens.db / application_default_credentials.json -- none of which would land under a .gcloud/ segment in a publish payload. Drop the rule rather than fix it: the realistic gcloud foot-gun would require recognizing the .config/gcloud/* tree by file basename, which is a broader change than the targeted env/cred scan in this PR. The remaining 7 patterns (.env / .env.* / .npmrc / .netrc / .git-credentials / .aws/credentials / .docker/config.json / .kube/config) cover the common Node/Python/CLI-tooling foot-guns. * fix(apps): close credential-scan bypass when --path is the parent dir itself isSensitiveRelPath anchors cloud-SDK matchers on adjacent parent/file segments (.aws/credentials, .docker/config.json, .kube/config), but walker strips that parent via filepath.Rel when --path is the conventional parent dir (e.g. ./.aws), yielding a bare RelPath="credentials" that slipped through silently. Same bypass for the single-file form --path ./.aws/credentials (walker sets RelPath = Base(rootPath)). Wrap the scan in isSensitiveCandidate: keep the fast RelPath scan, and on miss fall back to filepath.Abs(AbsPath) so the parent segment is visible again. isSensitiveRelPath itself is unchanged; existing tests still pin its pure-function contract. * fix(apps): drop filepath.Abs from sensitive scan to satisfy forbidigo lint The previous fix called filepath.Abs(c.AbsPath) — banned by the repo's forbidigo rule because shortcuts must not reach into the filesystem for path resolution. Reframe the same fix without fs access: re-prepend the root's basename (or, for the single-file form, the parent dir's basename of rootPath) to RelPath and re-scan only the parent-anchored credential pairs (.aws/credentials, .docker/config.json, .kube/config). Leaf matchers (.env / .npmrc / ...) stay scoped to RelPath — incidentally closing a latent false-positive where --path /home/alice/.env/dist would have flagged every file under it just because .env appeared in the absolute path.	2026-05-25 23:24:40 +08:00
raistlin042	6cea6c9af0	feat(apps): add miaoda apps domain (6 shortcuts + dry-run e2e) (#1002) ... Adds the apps domain to lark-cli for managing Miaoda (妙搭) applications: 6 shortcuts covering the full lifecycle (+create / +update / +list / +access-scope-set / +access-scope-get / +html-publish). Aligned with the OAPI v2 design — app_type enum (currently HTML), string scope enum (All / Tenant / Range), cursor pagination, in-memory tar.gz multipart publish flow. Namespace registered at /open-apis/spark/v1/ with spark:app.* scopes. --------- Co-authored-by: wangjiangwen-gif <286006750+wangjiangwen-gif@users.noreply.github.com>	2026-05-21 20:30:42 +08:00