docs: clarify local trigger automation

[zhmushan]

Summary

Clarify the safe local full-stack trigger workflow from configuration through verified runtime behavior. The guidance separates configuration, enable-only, test-only, publish-without-start, and changed-handler release paths, with explicit state restoration and operation-scoped authorization.

Changes

• Add independent paths for enabling and testing an existing published trigger without source changes, Git operations, or an application release.
• Route automation changes into the automation SOP before the generic local-dev release sequence, so an enabled trigger cannot bypass the pre-release disabled-state gate.
• For an existing enabled trigger, require disclosure and authorization for temporary downtime before disabling it for release; support creating a missing trigger as disabled.
• Distinguish start-only from test flows: start-only enables and stops without a probe; a successful test-only run restores the recorded state, while any failed, indeterminate, or interrupted probe fails closed to disabled.
• Verify a finished release exists before enable-only/test-existing, while explicitly stating that app release history does not prove a trigger-name-to-handler binding.
• For runtime tests, finish the exact probe authorization and sibling-impact preflight before enabling; start-only never manufactures a probe.
• Fail closed after a failed, indeterminate, or interrupted probe for both test-only and start-and-test flows; only a successful probe may preserve or restore enabled state.
• Separate trigger enablement, runtime-probe, and database-write authorization; require a precise test fixture, inventory sibling record-change triggers, and reuse the DB count/dry-run/confirmation gate for DELETE.
• Clarify that enable-only for UPSERT or feishu-approval changes configuration state but does not prove a handler, delivery, or live runtime contract.
• Preserve the intentional generic app-development trigger phrase while keeping all remote creation behind the existing development-path decision flow.
• Fix all lark-shared relative links and reduce the lark-apps frontmatter description below the 200-token budget.
• Add contract tests that fail if state gates, authorization boundaries, release evidence, generic routing, or cross-repository decoupling regress.

Test Plan

• make build
• make unit-test
• go vet ./...
• gofmt -l .
• go mod tidy leaves go.mod and go.sum unchanged
• incremental golangci-lint check
• skill format check
• targeted Apps contract tests
• GitHub CI: all required checks passed (e2e-live is skipped by the repository workflow)
• local artifact/package consumption verifies the project guide is installed byte-for-byte in both local and sandbox layouts
• isolated live Miaoda app: changed handler commit released successfully, trigger remained disabled for publish-without-start, enable-only changed neither Git HEAD nor release history, and test-only restored disabled state
• real webhook request reached the online environment; the trigger observability log reported phase=dispatch, status=succeed, the exact trigger name, and the unique test case payload
• no webhook URL, token, whitelist value, request headers, or authentication material is recorded in this PR

Skill quality waiver

• Trigger rule: skills/lark-apps/SKILL.md remains above the 4000-token default body budget.
• Why a waiver is appropriate: the file was already 4958 tokens at the PR merge base. Removing roughly one quarter of this high-risk, multi-capability domain guide would be a separate information-architecture change and would make this focused authorization fix substantially harder to review.
• Content that cannot be removed in this PR: identity routing, high-impact/data-loss guards, platform-resource versus application-source boundaries, release evidence, and publication/visibility rules.
• Reduction already made: the frontmatter description was reduced below 200 tokens; the trigger lifecycle remains in an on-demand reference; duplicated lark-shared rules were not added; broken lark-shared links were fixed.
• Follow-up: split lower-frequency domain procedures from the root skill in a dedicated follow-up PR, with evaluation data to ensure routing and safety do not regress.

The repository currently has no quality-waiver label, so the waiver is recorded explicitly here for reviewer tracking.

Related Issues

• None

Summary by CodeRabbit

• Documentation
  • Added guidance for diagnosing triggers that do not execute, with clear configuration-only boundaries for supported trigger types.
  • Documented local full-stack trigger workflows covering creation, testing, release polling, authorization, and enablement.
  • Standardized user context, environment selection, and release command examples.
  • Clarified that online links and failure details should only be shown when returned by the command.
  • Added safeguards preventing enablement before release completion and authorization.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The pull request adds gated automation-trigger and local-development guidance, including release polling, environment selection, trigger-guide boundaries, optional release outputs, and event-specific limitations. New Go contract tests enforce the documented command order, wording, and lifecycle boundaries.

Changes

Automation and local-development guidance

Layer / File(s)	Summary
Automation trigger lifecycle and contract tests skills/lark-apps/references/lark-apps-automation.md, shortcuts/apps/apps_automation_skill_contract_test.go	Documents trigger binding, configuration-only and handler-only paths, release polling, authorization-gated enablement, diagnosis, failure behavior, and UPSERT/approval boundaries; adds tests for these contracts.
Local full-stack setup and trigger-guide boundaries skills/lark-apps/references/lark-apps-local-dev.md, shortcuts/apps/apps_automation_skill_contract_test.go	Updates full-stack initialization commands, defines project trigger-guide boundaries, and tests that steering or synchronization implementation details are not exposed.
Release polling and environment guidance skills/lark-apps/references/lark-apps-local-dev.md, skills/lark-apps/SKILL.md, skills/lark-apps/references/lark-apps-release-get.md, shortcuts/apps/apps_automation_skill_contract_test.go	Adds identity and branch options to release commands, specifies polling and optional online_url/error_logs handling, gates enablement on release completion, replaces --env with --environment, and tests the updated boundaries.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Developer
  participant AutomationSOP
  participant ReleaseAPI
  participant Trigger
  Developer->>AutomationSOP: implement or update handler
  AutomationSOP->>ReleaseAPI: +release-create
  AutomationSOP->>ReleaseAPI: poll +release-get
  ReleaseAPI-->>AutomationSOP: finished, failed, or timeout
  AutomationSOP->>Trigger: enable only after completion and authorization

Loading

Possibly related PRs

• larksuite/cli#1040: Updates skills/lark-apps/SKILL.md content and directly overlaps the release-output and publication-state contracts validated by this pull request.

Suggested labels: documentation, domain/ccm

Suggested reviewers: liangshuo-1, caojie0621

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title is concise and matches the docs-focused trigger automation changes.
Description check	✅ Passed	The description follows the required template and includes summary, changes, test plan, and related issues.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@0561d88bc489668f59f2e4e253be599f3520ce7d

🧩 Skill update

npx skills add zhmushan/cli#feat/trigger-guide-local-flow -y -g