fix(env): route requests to gray lane

This reverts commit 9845fc40622c65b0811da1c9ae4902434377f33e.

AGENTS.md

@@ -15,6 +15,22 @@ make unit-test      # Required before PR (runs with -race)
 make test           # Full: vet + unit + integration
 ```
 
+## Notification Opt-Outs
+
+`lark-cli` emits two notice types into JSON envelope `_notice` to nudge AI agents toward fixes:
+
+- `_notice.update` — a newer binary is available on npm
+- `_notice.skills` — locally installed skills are out of sync with the running binary
+
+To suppress them in non-CI scripts (CI envs are auto-skipped):
+
+| Env var | Effect |
+|---------|--------|
+| `LARKSUITE_CLI_NO_UPDATE_NOTIFIER=1` | Suppress `_notice.update` |
+| `LARKSUITE_CLI_NO_SKILLS_NOTIFIER=1` | Suppress `_notice.skills` |
+
+Both notices recommend the same fix command: `lark-cli update`. The skills notice's `current` field is `""` when skills have never been synced (cold start) and a version string when synced for an older binary (drift).
+
 ## Pre-PR Checks (match CI gates)
 
 1. `make unit-test`

cmd/root.go

@@ -20,6 +20,7 @@ import (
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/registry"
+	"github.com/larksuite/cli/internal/skillscheck"
 	"github.com/larksuite/cli/internal/update"
 	"github.com/spf13/cobra"
 )
@@ -93,9 +94,9 @@ func Execute() int {
 		HideProfile(isSingleAppMode()),
 	)
 
-	// --- Update check (non-blocking) ---
+	// --- Notices (non-blocking) ---
 	if !isCompletionCommand(os.Args) {
-		setupUpdateNotice()
+		setupNotices()
 	}
 
 	if err := rootCmd.Execute(); err != nil {
@@ -104,42 +105,54 @@ func Execute() int {
 	return 0
 }
 
-// setupUpdateNotice starts an async update check and wires the output decorator.
-func setupUpdateNotice() {
-	// Sync: check cache immediately (no network, fast).
+// setupNotices wires both the binary update notice and the skills
+// staleness notice into output.PendingNotice as a composed function.
+// Each provider populates an independent key under _notice; either
+// or both may be present in any given envelope.
+func setupNotices() {
+	// Binary update — synchronous cache check + async refresh
 	if info := update.CheckCached(build.Version); info != nil {
 		update.SetPending(info)
 	}
-
-	// Async: refresh cache for this run (and future runs).
+	ver := build.Version
 	go func() {
 		defer func() {
 			if r := recover(); r != nil {
 				fmt.Fprintf(os.Stderr, "update check panic: %v\n", r)
 			}
 		}()
-		update.RefreshCache(build.Version)
-		// If cache was just populated for the first time, set pending now.
+		update.RefreshCache(ver)
 		if update.GetPending() == nil {
-			if info := update.CheckCached(build.Version); info != nil {
+			if info := update.CheckCached(ver); info != nil {
 				update.SetPending(info)
 			}
 		}
 	}()
 
-	// Wire the output decorator so JSON envelopes include "_notice".
+	// Skills check — synchronous, local-only (no network, no goroutine).
+	skillscheck.Init(build.Version)
+
+	// Composed notice provider — emits keys only when each pending is set.
 	output.PendingNotice = func() map[string]interface{} {
-		info := update.GetPending()
-		if info == nil {
-			return nil
-		}
-		return map[string]interface{}{
-			"update": map[string]interface{}{
+		notice := map[string]interface{}{}
+		if info := update.GetPending(); info != nil {
+			notice["update"] = map[string]interface{}{
 				"current": info.Current,
 				"latest":  info.Latest,
 				"message": info.Message(),
-			},
+			}
 		}
+		if stale := skillscheck.GetPending(); stale != nil {
+			notice["skills"] = map[string]interface{}{
+				"current": stale.Current,
+				"target":  stale.Target,
+				"message": stale.Message(),
+			}
+		}
+		if len(notice) == 0 {
+			return nil
+		}
+		return notice
 	}
 }
 

cmd/root_integration_test.go

@@ -7,6 +7,7 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"os"
 	"reflect"
 	"strings"
 	"testing"
@@ -14,11 +15,14 @@ import (
 	"github.com/larksuite/cli/cmd/api"
 	"github.com/larksuite/cli/cmd/auth"
 	"github.com/larksuite/cli/cmd/service"
+	"github.com/larksuite/cli/internal/build"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/envvars"
 	"github.com/larksuite/cli/internal/httpmock"
 	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/skillscheck"
+	"github.com/larksuite/cli/internal/update"
 	"github.com/larksuite/cli/shortcuts"
 	"github.com/spf13/cobra"
 )
@@ -499,3 +503,181 @@ func TestIntegration_Shortcut_BusinessError_OutputsEnvelope(t *testing.T) {
 		},
 	})
 }
+
+// TestSetupNotices_ColdStart verifies that when no skills stamp exists,
+// the composed PendingNotice provider includes a "skills" key with an
+// empty Current and the cold-start message.
+func TestSetupNotices_ColdStart(t *testing.T) {
+	clearNoticeEnv(t)
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+
+	origVersion := build.Version
+	build.Version = "1.0.21"
+	t.Cleanup(func() { build.Version = origVersion })
+
+	// Reset pending state to ensure a clean test.
+	skillscheck.SetPending(nil)
+	update.SetPending(nil)
+	output.PendingNotice = nil
+	t.Cleanup(func() {
+		skillscheck.SetPending(nil)
+		update.SetPending(nil)
+		output.PendingNotice = nil
+	})
+
+	setupNotices()
+
+	notice := output.GetNotice()
+	if notice == nil {
+		t.Fatal("GetNotice() = nil, want non-nil for cold start")
+	}
+	skills, ok := notice["skills"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("notice.skills missing, got %+v", notice)
+	}
+	if skills["current"] != "" || skills["target"] != "1.0.21" {
+		t.Errorf("notice.skills = %+v, want {current:\"\", target:\"1.0.21\"}", skills)
+	}
+	if msg, _ := skills["message"].(string); msg != "lark-cli skills not installed, run: lark-cli update" {
+		t.Errorf("notice.skills.message = %q, want cold-start message", msg)
+	}
+}
+
+// TestSetupNotices_InSync verifies that a matching stamp produces no
+// skills key in the composed notice.
+func TestSetupNotices_InSync(t *testing.T) {
+	clearNoticeEnv(t)
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := skillscheck.WriteStamp("1.0.21"); err != nil {
+		t.Fatal(err)
+	}
+
+	origVersion := build.Version
+	build.Version = "1.0.21"
+	t.Cleanup(func() { build.Version = origVersion })
+
+	skillscheck.SetPending(nil)
+	update.SetPending(nil)
+	output.PendingNotice = nil
+	t.Cleanup(func() {
+		skillscheck.SetPending(nil)
+		update.SetPending(nil)
+		output.PendingNotice = nil
+	})
+
+	setupNotices()
+
+	notice := output.GetNotice()
+	if notice != nil {
+		if _, ok := notice["skills"]; ok {
+			t.Errorf("notice.skills present in in-sync state: %+v", notice)
+		}
+	}
+}
+
+// TestSetupNotices_Drift verifies a mismatching stamp produces the
+// drift message with both current and target populated.
+func TestSetupNotices_Drift(t *testing.T) {
+	clearNoticeEnv(t)
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := skillscheck.WriteStamp("1.0.20"); err != nil {
+		t.Fatal(err)
+	}
+
+	origVersion := build.Version
+	build.Version = "1.0.21"
+	t.Cleanup(func() { build.Version = origVersion })
+
+	skillscheck.SetPending(nil)
+	update.SetPending(nil)
+	output.PendingNotice = nil
+	t.Cleanup(func() {
+		skillscheck.SetPending(nil)
+		update.SetPending(nil)
+		output.PendingNotice = nil
+	})
+
+	setupNotices()
+
+	notice := output.GetNotice()
+	if notice == nil {
+		t.Fatal("GetNotice() = nil, want non-nil for drift")
+	}
+	skills, ok := notice["skills"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("notice.skills missing, got %+v", notice)
+	}
+	if skills["current"] != "1.0.20" || skills["target"] != "1.0.21" {
+		t.Errorf("notice.skills = %+v, want {current:\"1.0.20\", target:\"1.0.21\"}", skills)
+	}
+	want := "lark-cli skills 1.0.20 out of sync with binary 1.0.21, run: lark-cli update"
+	if msg, _ := skills["message"].(string); msg != want {
+		t.Errorf("notice.skills.message = %q, want %q", msg, want)
+	}
+}
+
+// TestSetupNotices_BothUpdateAndSkills verifies the composed envelope
+// emits BOTH "_notice.update" and "_notice.skills" keys when each
+// pending value is set. Drives the skills key via setupNotices() (drift
+// state) and manually populates the update pending afterwards, since
+// clearNoticeEnv suppresses the update goroutine to avoid network
+// flakiness.
+func TestSetupNotices_BothUpdateAndSkills(t *testing.T) {
+	clearNoticeEnv(t)
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := skillscheck.WriteStamp("1.0.20"); err != nil {
+		t.Fatal(err)
+	}
+
+	origVersion := build.Version
+	build.Version = "1.0.21"
+	t.Cleanup(func() { build.Version = origVersion })
+
+	skillscheck.SetPending(nil)
+	update.SetPending(nil)
+	output.PendingNotice = nil
+	t.Cleanup(func() {
+		skillscheck.SetPending(nil)
+		update.SetPending(nil)
+		output.PendingNotice = nil
+	})
+
+	setupNotices()
+
+	// After setupNotices, skills pending is set (drift). Manually populate
+	// the update side so the composed envelope has both keys — the update
+	// goroutine is suppressed by clearNoticeEnv.
+	update.SetPending(&update.UpdateInfo{Current: "1.0.21", Latest: "1.0.22"})
+
+	notice := output.GetNotice()
+	if notice == nil {
+		t.Fatal("GetNotice() = nil, want both keys")
+	}
+	if _, ok := notice["update"].(map[string]interface{}); !ok {
+		t.Errorf("missing 'update' key: %+v", notice)
+	}
+	if _, ok := notice["skills"].(map[string]interface{}); !ok {
+		t.Errorf("missing 'skills' key: %+v", notice)
+	}
+}
+
+// clearNoticeEnv unsets the env vars that affect either notice. We
+// proactively SUPPRESS the update notifier (LARKSUITE_CLI_NO_UPDATE_NOTIFIER=1)
+// because setupNotices spawns a goroutine that hits the npm registry —
+// tests focused on the skills check should not depend on network state.
+func clearNoticeEnv(t *testing.T) {
+	t.Helper()
+	for _, key := range []string{
+		"LARKSUITE_CLI_NO_SKILLS_NOTIFIER",
+		"CI", "BUILD_NUMBER", "RUN_ID",
+	} {
+		t.Setenv(key, "")
+		os.Unsetenv(key)
+	}
+	// Suppress the update goroutine's network call deterministically.
+	t.Setenv("LARKSUITE_CLI_NO_UPDATE_NOTIFIER", "1")
+}

cmd/update/update.go

@@ -14,13 +14,15 @@ import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/selfupdate"
+	"github.com/larksuite/cli/internal/skillscheck"
 	"github.com/larksuite/cli/internal/update"
 )
 
 const (
-	repoURL      = "https://github.com/larksuite/cli"
-	maxNpmOutput = 2000
-	osWindows    = "windows"
+	repoURL         = "https://github.com/larksuite/cli"
+	maxNpmOutput    = 2000
+	maxStderrDetail = 500
+	osWindows       = "windows"
 )
 
 // Overridable for testing.
@@ -33,6 +35,13 @@ var (
 
 func isWindows() bool { return currentOS == osWindows }
 
+// normalizeVersion canonicalizes a version string for stamp comparison.
+// Strips a leading "v" so versions written from Makefile (git describe →
+// "v1.0.0") and npm (no prefix → "1.0.0") compare equal.
+func normalizeVersion(s string) string {
+	return strings.TrimPrefix(strings.TrimSpace(s), "v")
+}
+
 func releaseURL(version string) string {
 	return repoURL + "/releases/tag/v" + strings.TrimPrefix(version, "v")
 }
@@ -127,16 +136,15 @@ func updateRun(opts *UpdateOptions) error {
 
 	// 3. Compare versions
 	if !opts.Force && !update.IsNewer(latest, cur) {
-		if opts.JSON {
-			output.PrintJson(io.Out, map[string]interface{}{
-				"ok": true, "previous_version": cur, "current_version": cur,
-				"latest_version": latest, "action": "already_up_to_date",
-				"message": fmt.Sprintf("lark-cli %s is already up to date", cur),
-			})
-			return nil
+		// Run skills sync before returning — covers the case where the
+		// binary is already current but skills were never synced.
+		// Stamp dedup makes this a no-op if skills are already in sync.
+		// Skip side-effects under --check (pure report path per spec §3.6).
+		var skillsResult *selfupdate.NpmResult
+		if !opts.Check {
+			skillsResult = runSkillsAndStamp(updater, io, cur, opts.Force)
 		}
-		fmt.Fprintf(io.ErrOut, "%s lark-cli %s is already up to date\n", symOK(), cur)
-		return nil
+		return reportAlreadyUpToDate(opts, io, cur, latest, skillsResult, opts.Check)
 	}
 
 	// 4. Detect installation method
@@ -149,7 +157,7 @@ func updateRun(opts *UpdateOptions) error {
 
 	// 6. Execute update
 	if !detect.CanAutoUpdate() {
-		return doManualUpdate(opts, io, cur, latest, detect)
+		return doManualUpdate(opts, io, cur, latest, detect, updater)
 	}
 	return doNpmUpdate(opts, io, cur, latest, updater)
 }
@@ -169,13 +177,24 @@ func reportError(opts *UpdateOptions, io *cmdutil.IOStreams, exitCode int, errTy
 
 func reportCheckResult(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string, canAutoUpdate bool) error {
 	if opts.JSON {
-		output.PrintJson(io.Out, map[string]interface{}{
+		out := map[string]interface{}{
 			"ok": true, "previous_version": cur, "current_version": cur,
 			"latest_version": latest, "action": "update_available",
 			"auto_update": canAutoUpdate,
 			"message":     fmt.Sprintf("lark-cli %s %s %s available", cur, symArrow(), latest),
 			"url":         releaseURL(latest), "changelog": changelogURL(),
-		})
+		}
+		// skills_status: pure report, no side effect, no stamp write.
+		// ReadStamp errors are silently swallowed — if we can't read the
+		// stamp we just omit the block rather than fail the --check.
+		if stamp, err := skillscheck.ReadStamp(); err == nil {
+			out["skills_status"] = map[string]interface{}{
+				"current": stamp,
+				"target":  cur,
+				"in_sync": stamp == cur,
+			}
+		}
+		output.PrintJson(io.Out, out)
 		return nil
 	}
 	fmt.Fprintf(io.ErrOut, "Update available: %s %s %s\n", cur, symArrow(), latest)
@@ -189,15 +208,19 @@ func reportCheckResult(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest s
 	return nil
 }
 
-func doManualUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string, detect selfupdate.DetectResult) error {
+func doManualUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string, detect selfupdate.DetectResult, updater *selfupdate.Updater) error {
+	skillsResult := runSkillsAndStamp(updater, io, cur, opts.Force)
+
 	reason := detect.ManualReason()
 	if opts.JSON {
-		output.PrintJson(io.Out, map[string]interface{}{
+		out := map[string]interface{}{
 			"ok": true, "previous_version": cur, "latest_version": latest,
 			"action":  "manual_required",
 			"message": fmt.Sprintf("Automatic update unavailable: %s (path: %s)", reason, detect.ResolvedPath),
 			"url":     releaseURL(latest), "changelog": changelogURL(),
-		})
+		}
+		applySkillsResult(out, skillsResult)
+		output.PrintJson(io.Out, out)
 		return nil
 	}
 	fmt.Fprintf(io.ErrOut, "Automatic update unavailable: %s (path: %s).\n\n", reason, detect.ResolvedPath)
@@ -205,7 +228,7 @@ func doManualUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest stri
 	fmt.Fprintf(io.ErrOut, "  Release:   %s\n", releaseURL(latest))
 	fmt.Fprintf(io.ErrOut, "  Changelog: %s\n", changelogURL())
 	fmt.Fprintf(io.ErrOut, "\nOr install via npm:\n  npm install -g %s@%s\n", selfupdate.NpmPackage, latest)
-	fmt.Fprintf(io.ErrOut, "\nAfter updating, also update skills:\n  npx -y skills add larksuite/cli -g -y\n")
+	emitSkillsTextHints(io, skillsResult)
 	return nil
 }
 
@@ -264,8 +287,10 @@ func doNpmUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string,
 		return output.ErrBare(output.ExitAPI)
 	}
 
-	// Skills update (best-effort).
-	skillsResult := updater.RunSkillsUpdate()
+	// Skills update (best-effort) — uses runSkillsAndStamp so the
+	// stamp gets persisted on success and dedup applies if a previous
+	// run already stamped this version.
+	skillsResult := runSkillsAndStamp(updater, io, latest, opts.Force)
 
 	if opts.JSON {
 		result := map[string]interface{}{
@@ -274,28 +299,17 @@ func doNpmUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string,
 			"message": fmt.Sprintf("lark-cli updated from %s to %s", cur, latest),
 			"url":     releaseURL(latest), "changelog": changelogURL(),
 		}
-		if skillsResult.Err != nil {
-			result["skills_warning"] = fmt.Sprintf("skills update failed: %s", skillsResult.Err)
-			if detail := strings.TrimSpace(skillsResult.Stderr.String()); detail != "" {
-				result["skills_detail"] = selfupdate.Truncate(detail, maxNpmOutput)
-			}
-		}
+		applySkillsResult(result, skillsResult)
 		output.PrintJson(io.Out, result)
 		return nil
 	}
 
 	fmt.Fprintf(io.ErrOut, "\n%s Successfully updated lark-cli from %s to %s\n", symOK(), cur, latest)
 	fmt.Fprintf(io.ErrOut, "  Changelog: %s\n", changelogURL())
-	fmt.Fprintf(io.ErrOut, "\nUpdating skills ...\n")
-	if skillsResult.Err != nil {
-		fmt.Fprintf(io.ErrOut, "%s Skills update failed: %s\n", symWarn(), skillsResult.Err)
-		if detail := strings.TrimSpace(skillsResult.Stderr.String()); detail != "" {
-			fmt.Fprintf(io.ErrOut, "  %s\n", selfupdate.Truncate(detail, 500))
-		}
-		fmt.Fprintf(io.ErrOut, "  Run manually: npx -y skills add larksuite/cli -g -y\n")
-	} else {
-		fmt.Fprintf(io.ErrOut, "%s Skills updated\n", symOK())
+	if skillsResult != nil {
+		fmt.Fprintf(io.ErrOut, "\nUpdating skills ...\n")
 	}
+	emitSkillsTextHints(io, skillsResult)
 	return nil
 }
 
@@ -312,3 +326,96 @@ func verificationFailureHint(updater *selfupdate.Updater, latest string) string
 	}
 	return fmt.Sprintf("automatic rollback is unavailable on this platform; reinstall manually: npm install -g %s@%s, or download %s", selfupdate.NpmPackage, latest, releaseURL(latest))
 }
+
+// runSkillsAndStamp triggers updater.RunSkillsUpdate and persists the
+// stamp on success. Skips the npx invocation when the stamp already
+// matches stampVersion (unless force is true). The stamp write failure
+// emits a warning to io.ErrOut but does NOT fail the update command —
+// best-effort. ReadStamp errors are swallowed (fail-closed: treated as
+// out-of-sync, so npx re-runs). Returns nil iff skipped due to stamp
+// dedup; otherwise returns the underlying *NpmResult with Err semantics
+// from RunSkillsUpdate.
+func runSkillsAndStamp(updater *selfupdate.Updater, io *cmdutil.IOStreams, stampVersion string, force bool) *selfupdate.NpmResult {
+	if !force {
+		if existing, _ := skillscheck.ReadStamp(); normalizeVersion(existing) == normalizeVersion(stampVersion) {
+			return nil
+		}
+	}
+	r := updater.RunSkillsUpdate()
+	if r.Err == nil {
+		if err := skillscheck.WriteStamp(stampVersion); err != nil {
+			fmt.Fprintf(io.ErrOut, "warning: skills synced but stamp not written: %v\n", err)
+		}
+	}
+	return r
+}
+
+// reportAlreadyUpToDate emits the JSON / pretty output for the
+// already-up-to-date branch, including any skills_action / skills_warning
+// fields derived from skillsResult. When check is true, this is the pure
+// report path (spec §3.6): no side-effects, JSON envelope uses
+// skills_status (spec §4.2) instead of skills_action.
+func reportAlreadyUpToDate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string, skillsResult *selfupdate.NpmResult, check bool) error {
+	if opts.JSON {
+		out := map[string]interface{}{
+			"ok": true, "previous_version": cur, "current_version": cur,
+			"latest_version": latest, "action": "already_up_to_date",
+			"message": fmt.Sprintf("lark-cli %s is already up to date", cur),
+		}
+		if check {
+			// Pure report — read stamp directly, emit skills_status block.
+			// ReadStamp errors are silently swallowed — if we can't read
+			// the stamp we just omit the block rather than fail the --check.
+			if stamp, err := skillscheck.ReadStamp(); err == nil {
+				out["skills_status"] = map[string]interface{}{
+					"current": stamp,
+					"target":  cur,
+					"in_sync": stamp == cur,
+				}
+			}
+		} else {
+			applySkillsResult(out, skillsResult)
+		}
+		output.PrintJson(io.Out, out)
+		return nil
+	}
+	fmt.Fprintf(io.ErrOut, "%s lark-cli %s is already up to date\n", symOK(), cur)
+	if !check {
+		emitSkillsTextHints(io, skillsResult)
+	}
+	return nil
+}
+
+// applySkillsResult mutates the JSON envelope to include skills_action
+// (and skills_warning when failed). nil result = "in_sync" (dedup hit).
+func applySkillsResult(env map[string]interface{}, r *selfupdate.NpmResult) {
+	switch {
+	case r == nil:
+		env["skills_action"] = "in_sync"
+	case r.Err != nil:
+		env["skills_action"] = "failed"
+		env["skills_warning"] = fmt.Sprintf("skills update failed: %s", r.Err)
+		if detail := strings.TrimSpace(r.Stderr.String()); detail != "" {
+			env["skills_detail"] = selfupdate.Truncate(detail, maxNpmOutput)
+		}
+	default:
+		env["skills_action"] = "synced"
+	}
+}
+
+// emitSkillsTextHints prints human-readable feedback about the skills
+// sync result for non-JSON output.
+func emitSkillsTextHints(io *cmdutil.IOStreams, r *selfupdate.NpmResult) {
+	switch {
+	case r == nil:
+		// dedup hit — silent (already up to date)
+	case r.Err != nil:
+		fmt.Fprintf(io.ErrOut, "%s Skills update failed: %v\n", symWarn(), r.Err)
+		if detail := strings.TrimSpace(r.Stderr.String()); detail != "" {
+			fmt.Fprintf(io.ErrOut, "  %s\n", selfupdate.Truncate(detail, maxStderrDetail))
+		}
+		fmt.Fprintf(io.ErrOut, "  Run manually: npx -y skills add larksuite/cli -g -y\n")
+	default:
+		fmt.Fprintf(io.ErrOut, "%s Skills updated\n", symOK())
+	}
+}

cmd/update/update_test.go

@@ -5,8 +5,11 @@ package cmdupdate
 
 import (
 	"bytes"
+	"encoding/json"
 	"errors"
 	"fmt"
+	"os"
+	"path/filepath"
 	"strings"
 	"testing"
 
@@ -14,6 +17,7 @@ import (
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/selfupdate"
+	"github.com/larksuite/cli/internal/skillscheck"
 )
 
 // newTestFactory creates a test factory with minimal config.
@@ -709,6 +713,7 @@ func TestUpdateWindows_Symbols(t *testing.T) {
 }
 
 func TestUpdateNpm_SkillsSuccess_JSON(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	f, stdout, _ := newTestFactory(t)
 	cmd := NewCmdUpdate(f)
 	cmd.SetArgs([]string{"--json"})
@@ -737,6 +742,7 @@ func TestUpdateNpm_SkillsSuccess_JSON(t *testing.T) {
 }
 
 func TestUpdateNpm_SkillsFail_JSON(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	f, stdout, _ := newTestFactory(t)
 	cmd := NewCmdUpdate(f)
 	cmd.SetArgs([]string{"--json"})
@@ -789,6 +795,7 @@ func TestUpdateNpm_SkillsFail_JSON(t *testing.T) {
 }
 
 func TestUpdateNpm_SkillsFail_Human(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	f, _, stderr := newTestFactory(t)
 	cmd := NewCmdUpdate(f)
 	cmd.SetArgs([]string{})
@@ -836,6 +843,98 @@ func TestUpdateNpm_SkillsFail_Human(t *testing.T) {
 	}
 }
 
+// newTestIO returns a cmdutil.IOStreams backed by bytes.Buffers, suitable
+// for direct calls to internals like runSkillsAndStamp that write to
+// io.ErrOut.
+func newTestIO() *cmdutil.IOStreams {
+	return cmdutil.NewIOStreams(&bytes.Buffer{}, &bytes.Buffer{}, &bytes.Buffer{})
+}
+
+func TestRunSkillsAndStamp_DedupHit(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := skillscheck.WriteStamp("1.0.21"); err != nil {
+		t.Fatal(err)
+	}
+	called := false
+	updater := &selfupdate.Updater{
+		SkillsUpdateOverride: func() *selfupdate.NpmResult {
+			called = true
+			return &selfupdate.NpmResult{}
+		},
+	}
+	got := runSkillsAndStamp(updater, newTestIO(), "1.0.21", false)
+	if got != nil {
+		t.Errorf("runSkillsAndStamp() = %+v, want nil for dedup hit", got)
+	}
+	if called {
+		t.Error("SkillsUpdateOverride called, want skipped due to dedup")
+	}
+}
+
+func TestRunSkillsAndStamp_DedupForceBypass(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := skillscheck.WriteStamp("1.0.21"); err != nil {
+		t.Fatal(err)
+	}
+	called := false
+	updater := &selfupdate.Updater{
+		SkillsUpdateOverride: func() *selfupdate.NpmResult {
+			called = true
+			return &selfupdate.NpmResult{}
+		},
+	}
+	got := runSkillsAndStamp(updater, newTestIO(), "1.0.21", true)
+	if got == nil {
+		t.Fatal("runSkillsAndStamp(force=true) = nil, want non-nil")
+	}
+	if !called {
+		t.Error("SkillsUpdateOverride not called with force=true")
+	}
+}
+
+func TestRunSkillsAndStamp_SuccessWritesStamp(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	updater := &selfupdate.Updater{
+		SkillsUpdateOverride: func() *selfupdate.NpmResult {
+			return &selfupdate.NpmResult{}
+		},
+	}
+	got := runSkillsAndStamp(updater, newTestIO(), "1.0.21", false)
+	if got == nil || got.Err != nil {
+		t.Fatalf("runSkillsAndStamp() = %+v, want non-nil with nil Err", got)
+	}
+	stamp, _ := skillscheck.ReadStamp()
+	if stamp != "1.0.21" {
+		t.Errorf("stamp = %q, want \"1.0.21\"", stamp)
+	}
+}
+
+func TestRunSkillsAndStamp_FailureKeepsOldStamp(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := skillscheck.WriteStamp("1.0.20"); err != nil {
+		t.Fatal(err)
+	}
+	updater := &selfupdate.Updater{
+		SkillsUpdateOverride: func() *selfupdate.NpmResult {
+			r := &selfupdate.NpmResult{}
+			r.Err = fmt.Errorf("npx failed")
+			return r
+		},
+	}
+	got := runSkillsAndStamp(updater, newTestIO(), "1.0.21", false)
+	if got == nil || got.Err == nil {
+		t.Fatalf("runSkillsAndStamp() = %+v, want non-nil with non-nil Err", got)
+	}
+	stamp, _ := skillscheck.ReadStamp()
+	if stamp != "1.0.20" {
+		t.Errorf("stamp = %q, want \"1.0.20\" (failure must not overwrite)", stamp)
+	}
+}
+
 func TestTruncate(t *testing.T) {
 	long := strings.Repeat("x", 3000)
 	got := selfupdate.Truncate(long, 2000)
@@ -849,3 +948,272 @@ func TestTruncate(t *testing.T) {
 		t.Errorf("expected 'hello', got %q", got2)
 	}
 }
+
+func TestUpdateRun_AlreadyLatest_RunsSkillsSync(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+
+	origFetch := fetchLatest
+	origCur := currentVersion
+	t.Cleanup(func() { fetchLatest = origFetch; currentVersion = origCur })
+	fetchLatest = func() (string, error) { return "1.0.21", nil }
+	currentVersion = func() string { return "1.0.21" }
+
+	skillsCalled := false
+	origNew := newUpdater
+	t.Cleanup(func() { newUpdater = origNew })
+	newUpdater = func() *selfupdate.Updater {
+		return &selfupdate.Updater{
+			SkillsUpdateOverride: func() *selfupdate.NpmResult {
+				skillsCalled = true
+				return &selfupdate.NpmResult{}
+			},
+		}
+	}
+
+	f, _, _ := newTestFactory(t)
+	opts := &UpdateOptions{Factory: f, JSON: true}
+	if err := updateRun(opts); err != nil {
+		t.Fatalf("updateRun() err = %v, want nil", err)
+	}
+	if !skillsCalled {
+		t.Error("RunSkillsUpdate not called in already-up-to-date branch (cold stamp), want called")
+	}
+	stamp, _ := skillscheck.ReadStamp()
+	if stamp != "1.0.21" {
+		t.Errorf("stamp = %q, want \"1.0.21\"", stamp)
+	}
+}
+
+func TestUpdateRun_Manual_RunsSkillsSync(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+
+	origFetch := fetchLatest
+	origCur := currentVersion
+	t.Cleanup(func() { fetchLatest = origFetch; currentVersion = origCur })
+	fetchLatest = func() (string, error) { return "1.0.22", nil }
+	currentVersion = func() string { return "1.0.21" }
+
+	skillsCalled := false
+	origNew := newUpdater
+	t.Cleanup(func() { newUpdater = origNew })
+	newUpdater = func() *selfupdate.Updater {
+		return &selfupdate.Updater{
+			DetectOverride: func() selfupdate.DetectResult {
+				return selfupdate.DetectResult{
+					Method:       selfupdate.InstallManual,
+					ResolvedPath: "/usr/local/bin/lark-cli",
+				}
+			},
+			SkillsUpdateOverride: func() *selfupdate.NpmResult {
+				skillsCalled = true
+				return &selfupdate.NpmResult{}
+			},
+		}
+	}
+
+	f, _, _ := newTestFactory(t)
+	opts := &UpdateOptions{Factory: f, JSON: true}
+	if err := updateRun(opts); err != nil {
+		t.Fatalf("updateRun() err = %v, want nil", err)
+	}
+	if !skillsCalled {
+		t.Error("RunSkillsUpdate not called in manual branch, want called")
+	}
+	stamp, _ := skillscheck.ReadStamp()
+	if stamp != "1.0.21" {
+		t.Errorf("stamp = %q, want \"1.0.21\" (manual path stamps cur)", stamp)
+	}
+}
+
+func TestUpdateRun_Npm_RunsSkillsSync_StampsLatest(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+
+	origFetch := fetchLatest
+	origCur := currentVersion
+	t.Cleanup(func() { fetchLatest = origFetch; currentVersion = origCur })
+	fetchLatest = func() (string, error) { return "1.0.22", nil }
+	currentVersion = func() string { return "1.0.21" }
+
+	skillsCalled := false
+	origNew := newUpdater
+	t.Cleanup(func() { newUpdater = origNew })
+	newUpdater = func() *selfupdate.Updater {
+		return &selfupdate.Updater{
+			DetectOverride: func() selfupdate.DetectResult {
+				return selfupdate.DetectResult{
+					Method: selfupdate.InstallNpm, NpmAvailable: true,
+					ResolvedPath: "/usr/local/bin/lark-cli",
+				}
+			},
+			NpmInstallOverride: func(version string) *selfupdate.NpmResult {
+				return &selfupdate.NpmResult{}
+			},
+			VerifyOverride: func(expectedVersion string) error { return nil },
+			SkillsUpdateOverride: func() *selfupdate.NpmResult {
+				skillsCalled = true
+				return &selfupdate.NpmResult{}
+			},
+		}
+	}
+
+	f, _, _ := newTestFactory(t)
+	opts := &UpdateOptions{Factory: f, JSON: true}
+	if err := updateRun(opts); err != nil {
+		t.Fatalf("updateRun() err = %v, want nil", err)
+	}
+	if !skillsCalled {
+		t.Error("RunSkillsUpdate not called in npm branch")
+	}
+	stamp, _ := skillscheck.ReadStamp()
+	if stamp != "1.0.22" {
+		t.Errorf("stamp = %q, want \"1.0.22\" (npm path stamps latest)", stamp)
+	}
+}
+
+func TestUpdateRun_CheckIncludesSkillsStatus(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := skillscheck.WriteStamp("1.0.20"); err != nil {
+		t.Fatal(err)
+	}
+
+	origFetch := fetchLatest
+	origCur := currentVersion
+	t.Cleanup(func() { fetchLatest = origFetch; currentVersion = origCur })
+	fetchLatest = func() (string, error) { return "1.0.22", nil }
+	currentVersion = func() string { return "1.0.21" }
+
+	origNew := newUpdater
+	t.Cleanup(func() { newUpdater = origNew })
+	skillsCalled := false
+	newUpdater = func() *selfupdate.Updater {
+		return &selfupdate.Updater{
+			DetectOverride: func() selfupdate.DetectResult {
+				return selfupdate.DetectResult{Method: selfupdate.InstallNpm, NpmAvailable: true}
+			},
+			SkillsUpdateOverride: func() *selfupdate.NpmResult {
+				skillsCalled = true
+				return &selfupdate.NpmResult{}
+			},
+		}
+	}
+
+	f, stdout, _ := newTestFactory(t)
+	opts := &UpdateOptions{Factory: f, JSON: true, Check: true}
+	if err := updateRun(opts); err != nil {
+		t.Fatalf("updateRun(--check) err = %v, want nil", err)
+	}
+	if skillsCalled {
+		t.Error("RunSkillsUpdate called under --check, want skipped (pure report)")
+	}
+
+	var env map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
+		t.Fatalf("json.Unmarshal stdout: %v\nstdout: %s", err, stdout.String())
+	}
+	status, ok := env["skills_status"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("skills_status missing or wrong type in --check JSON: %s", stdout.String())
+	}
+	if status["current"] != "1.0.20" || status["target"] != "1.0.21" || status["in_sync"] != false {
+		t.Errorf("skills_status = %+v, want {current:\"1.0.20\", target:\"1.0.21\", in_sync:false}", status)
+	}
+}
+
+func TestUpdateRun_CheckAlreadyLatest_NoSideEffect(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := skillscheck.WriteStamp("1.0.20"); err != nil {
+		t.Fatal(err)
+	}
+
+	origFetch := fetchLatest
+	origCur := currentVersion
+	t.Cleanup(func() { fetchLatest = origFetch; currentVersion = origCur })
+	fetchLatest = func() (string, error) { return "1.0.21", nil }
+	currentVersion = func() string { return "1.0.21" }
+
+	skillsCalled := false
+	origNew := newUpdater
+	t.Cleanup(func() { newUpdater = origNew })
+	newUpdater = func() *selfupdate.Updater {
+		return &selfupdate.Updater{
+			SkillsUpdateOverride: func() *selfupdate.NpmResult {
+				skillsCalled = true
+				return &selfupdate.NpmResult{}
+			},
+		}
+	}
+
+	f, stdout, _ := newTestFactory(t)
+	opts := &UpdateOptions{Factory: f, JSON: true, Check: true}
+	if err := updateRun(opts); err != nil {
+		t.Fatalf("updateRun(--check, already-latest) err = %v, want nil", err)
+	}
+	if skillsCalled {
+		t.Error("RunSkillsUpdate called under --check (already-latest), want skipped (pure report)")
+	}
+
+	stamp, _ := skillscheck.ReadStamp()
+	if stamp != "1.0.20" {
+		t.Errorf("stamp mutated to %q under --check, want \"1.0.20\" (pure report must not write stamp)", stamp)
+	}
+
+	var env map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
+		t.Fatalf("json.Unmarshal stdout: %v\n%s", err, stdout.String())
+	}
+	if env["action"] != "already_up_to_date" {
+		t.Errorf("action = %v, want \"already_up_to_date\"", env["action"])
+	}
+	if _, has := env["skills_action"]; has {
+		t.Errorf("skills_action present under --check, want absent: %+v", env)
+	}
+	status, ok := env["skills_status"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("skills_status missing under --check + already-latest: %s", stdout.String())
+	}
+	if status["current"] != "1.0.20" || status["target"] != "1.0.21" || status["in_sync"] != false {
+		t.Errorf("skills_status = %+v, want {current:\"1.0.20\", target:\"1.0.21\", in_sync:false}", status)
+	}
+}
+
+// TestRunSkillsAndStamp_StampWriteFailureWarns verifies the stderr warning
+// emission when RunSkillsUpdate succeeds but WriteStamp fails.
+func TestRunSkillsAndStamp_StampWriteFailureWarns(t *testing.T) {
+	// Force WriteStamp to fail by pointing config dir at a path that exists
+	// as a regular file (so MkdirAll fails).
+	tmp := t.TempDir()
+	badPath := filepath.Join(tmp, "blocker")
+	if err := os.WriteFile(badPath, []byte("not-a-dir"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", badPath)
+
+	f, _, stderr := newTestFactory(t)
+	updater := &selfupdate.Updater{
+		SkillsUpdateOverride: func() *selfupdate.NpmResult {
+			return &selfupdate.NpmResult{} // success
+		},
+	}
+	got := runSkillsAndStamp(updater, f.IOStreams, "1.0.21", false)
+	if got == nil || got.Err != nil {
+		t.Fatalf("runSkillsAndStamp() = %+v, want non-nil with nil Err", got)
+	}
+	if !strings.Contains(stderr.String(), "warning: skills synced but stamp not written") {
+		t.Errorf("stderr does not contain warning: %q", stderr.String())
+	}
+}
+
+// TestEmitSkillsTextHints_Success verifies the "Skills updated" success
+// message is printed to ErrOut on a successful (Err == nil) result.
+func TestEmitSkillsTextHints_Success(t *testing.T) {
+	f, _, stderr := newTestFactory(t)
+	emitSkillsTextHints(f.IOStreams, &selfupdate.NpmResult{}) // Err==nil → success
+	if !strings.Contains(stderr.String(), "Skills updated") {
+		t.Errorf("stderr does not contain 'Skills updated': %q", stderr.String())
+	}
+}

internal/binding/json_pointer.go

@@ -33,8 +33,10 @@ func ReadJSONPointer(data interface{}, pointer string) (interface{}, error) {
 
 	for i, raw := range segments {
 		// RFC 6901 unescaping: ~1 → /, ~0 → ~ (order matters).
-		key := strings.ReplaceAll(raw, "~1", "/")
-		key = strings.ReplaceAll(key, "~0", "~")
+		key, err := decodeJSONPointerSegment(raw)
+		if err != nil {
+			return nil, fmt.Errorf("json pointer %q: segment %q: %w", pointer, raw, err)
+		}
 
 		m, ok := current.(map[string]interface{})
 		if !ok {
@@ -53,3 +55,26 @@ func ReadJSONPointer(data interface{}, pointer string) (interface{}, error) {
 
 	return current, nil
 }
+
+func decodeJSONPointerSegment(raw string) (string, error) {
+	var out strings.Builder
+	for i := 0; i < len(raw); i++ {
+		if raw[i] != '~' {
+			out.WriteByte(raw[i])
+			continue
+		}
+		if i+1 >= len(raw) {
+			return "", fmt.Errorf("invalid escape: ~ must be followed by 0 or 1")
+		}
+		switch raw[i+1] {
+		case '0':
+			out.WriteByte('~')
+		case '1':
+			out.WriteByte('/')
+		default:
+			return "", fmt.Errorf("invalid escape: ~%c must be ~0 or ~1", raw[i+1])
+		}
+		i++
+	}
+	return out.String(), nil
+}

internal/binding/json_pointer_test.go

@@ -98,6 +98,41 @@ func TestReadJSONPointer_RFC6901_Escaping(t *testing.T) {
 	}
 }
 
+func TestReadJSONPointer_InvalidEscape(t *testing.T) {
+	data := map[string]interface{}{
+		"a~2b": "literal",
+		"a~":   "literal",
+	}
+	tests := []struct {
+		name    string
+		pointer string
+		want    string
+	}{
+		{
+			name:    "unsupported escape code",
+			pointer: "/a~2b",
+			want:    `json pointer "/a~2b": segment "a~2b": invalid escape: ~2 must be ~0 or ~1`,
+		},
+		{
+			name:    "dangling tilde",
+			pointer: "/a~",
+			want:    `json pointer "/a~": segment "a~": invalid escape: ~ must be followed by 0 or 1`,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			_, err := ReadJSONPointer(data, tt.pointer)
+			if err == nil {
+				t.Fatal("expected error for invalid escape, got nil")
+			}
+			if err.Error() != tt.want {
+				t.Errorf("error = %q, want %q", err.Error(), tt.want)
+			}
+		})
+	}
+}
+
 func TestReadJSONPointer_InvalidFormat(t *testing.T) {
 	data := map[string]interface{}{"key": "val"}
 	_, err := ReadJSONPointer(data, "no-leading-slash")

internal/binding/types.go

@@ -169,7 +169,7 @@ type ProviderConfig struct {
 const (
 	DefaultFileTimeoutMs      = 5000
 	DefaultFileMaxBytes       = 1024 * 1024 // 1 MiB
-	DefaultExecTimeoutMs      = 5000
+	DefaultExecTimeoutMs      = 10000
 	DefaultExecMaxOutputBytes = 1024 * 1024 // 1 MiB
 )
 

internal/cmdutil/secheader.go

@@ -28,12 +28,14 @@ const (
 	SourceValue = "lark-cli"
 
 	HeaderUserAgent = "User-Agent"
+	HeaderLarkChannel = "Rpc-Persist-Lane-C-Lark-Channel"
 
 	// BuildKindOfficial / BuildKindExtended / BuildKindUnknown are the values
 	// reported in the X-Cli-Build header; see DetectBuildKind for semantics.
 	BuildKindOfficial = "official"
 	BuildKindExtended = "extended"
 	BuildKindUnknown  = "unknown"
+	LarkChannelGray   = "GRAY"
 
 	officialModulePath = "github.com/larksuite/cli"
 )
@@ -50,6 +52,7 @@ func BaseSecurityHeaders() http.Header {
 	h.Set(HeaderVersion, build.Version)
 	h.Set(HeaderBuild, DetectBuildKind())
 	h.Set(HeaderUserAgent, UserAgentValue())
+	h.Set(HeaderLarkChannel, LarkChannelGray)
 	return h
 }
 

internal/skillscheck/check.go

@@ -0,0 +1,38 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package skillscheck
+
+// Init runs the synchronous skills version check. Stores a StaleNotice
+// when the local stamp does not match currentVersion. Safe to call
+// from cmd/root.go before rootCmd.Execute(); zero network, zero
+// subprocess — only a local stamp file read.
+//
+// Skip rules: see shouldSkip (CI envs, DEV builds, non-release semver,
+// LARKSUITE_CLI_NO_SKILLS_NOTIFIER opt-out).
+//
+// Failure modes (all → no notice, no nag):
+//   - shouldSkip rule met
+//   - ReadStamp returns an I/O error other than ENOENT
+//   - Stamp matches currentVersion (in-sync)
+func Init(currentVersion string) {
+	// Clear any stale notice from a prior call so early returns below
+	// (skip rules / read errors / in-sync) leave pending == nil instead
+	// of preserving a stale value from a previous Init invocation.
+	SetPending(nil)
+	if shouldSkip(currentVersion) {
+		return
+	}
+	stamp, err := ReadStamp()
+	if err != nil {
+		// Fail closed — don't nag for a transient FS problem.
+		return
+	}
+	if stamp == currentVersion {
+		return
+	}
+	SetPending(&StaleNotice{
+		Current: stamp, // "" when never synced
+		Target:  currentVersion,
+	})
+}

internal/skillscheck/check_test.go

@@ -0,0 +1,90 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package skillscheck
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func resetPending(t *testing.T) {
+	t.Helper()
+	SetPending(nil)
+	t.Cleanup(func() { SetPending(nil) })
+}
+
+func TestInit_InSync_NoNotice(t *testing.T) {
+	clearSkillsSkipEnv(t)
+	resetPending(t)
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := WriteStamp("1.0.21"); err != nil {
+		t.Fatal(err)
+	}
+	Init("1.0.21")
+	if got := GetPending(); got != nil {
+		t.Errorf("GetPending() = %+v, want nil (in-sync)", got)
+	}
+}
+
+func TestInit_ColdStart_NoticeWithEmptyCurrent(t *testing.T) {
+	clearSkillsSkipEnv(t)
+	resetPending(t)
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	Init("1.0.21")
+	got := GetPending()
+	if got == nil {
+		t.Fatal("GetPending() = nil, want non-nil for cold start")
+	}
+	if got.Current != "" || got.Target != "1.0.21" {
+		t.Errorf("notice = %+v, want {Current:\"\", Target:\"1.0.21\"}", got)
+	}
+}
+
+func TestInit_Drift_NoticeWithStampVersion(t *testing.T) {
+	clearSkillsSkipEnv(t)
+	resetPending(t)
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := WriteStamp("1.0.20"); err != nil {
+		t.Fatal(err)
+	}
+	Init("1.0.21")
+	got := GetPending()
+	if got == nil {
+		t.Fatal("GetPending() = nil, want non-nil for drift")
+	}
+	if got.Current != "1.0.20" || got.Target != "1.0.21" {
+		t.Errorf("notice = %+v, want {Current:\"1.0.20\", Target:\"1.0.21\"}", got)
+	}
+}
+
+func TestInit_Skipped_NoNotice(t *testing.T) {
+	clearSkillsSkipEnv(t)
+	resetPending(t)
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	// Even with an empty config dir (no stamp), DEV version should skip
+	// the check entirely and never emit a notice.
+	Init("DEV")
+	if got := GetPending(); got != nil {
+		t.Errorf("GetPending() = %+v, want nil (skip rules met)", got)
+	}
+}
+
+func TestInit_ReadStampError_FailsClosed(t *testing.T) {
+	clearSkillsSkipEnv(t)
+	resetPending(t)
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	// Make the stamp path a directory so vfs.ReadFile returns a
+	// non-ENOENT I/O error.
+	if err := os.MkdirAll(filepath.Join(dir, "skills.stamp"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	Init("1.0.21")
+	if got := GetPending(); got != nil {
+		t.Errorf("GetPending() = %+v, want nil (fail closed on I/O error)", got)
+	}
+}

internal/skillscheck/notice.go

@@ -0,0 +1,46 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// Package skillscheck verifies that the locally installed lark-cli
+// skills are in sync with the running binary version, by comparing
+// the current binary version against a stamp file written when skills
+// are last synced (by `lark-cli update`). On mismatch it stores a
+// notice for injection into JSON envelopes via output.PendingNotice.
+package skillscheck
+
+import (
+	"fmt"
+	"sync/atomic"
+)
+
+// StaleNotice signals that the locally synced skills version does not
+// match the running binary. Current is the last successfully synced
+// version (or "" when never synced); Target is the running binary
+// version. Mirrors internal/update.UpdateInfo's pending-notice pattern.
+type StaleNotice struct {
+	Current string `json:"current"`
+	Target  string `json:"target"`
+}
+
+// Message returns a single-line, AI-agent-parseable description of the
+// gap plus the canonical fix command. Mirrors internal/update.UpdateInfo.Message
+// in style ("..., run: lark-cli update" suffix).
+func (s *StaleNotice) Message() string {
+	if s.Current == "" {
+		return "lark-cli skills not installed, run: lark-cli update"
+	}
+	return fmt.Sprintf(
+		"lark-cli skills %s out of sync with binary %s, run: lark-cli update",
+		s.Current, s.Target,
+	)
+}
+
+// pending stores the latest stale notice for the current process.
+var pending atomic.Pointer[StaleNotice]
+
+// SetPending stores the stale notice for consumption by output decorators.
+// Pass nil to clear.
+func SetPending(n *StaleNotice) { pending.Store(n) }
+
+// GetPending returns the pending stale notice, or nil.
+func GetPending() *StaleNotice { return pending.Load() }

internal/skillscheck/notice_test.go

@@ -0,0 +1,71 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package skillscheck
+
+import (
+	"sync"
+	"testing"
+)
+
+func TestStaleNotice_Message(t *testing.T) {
+	tests := []struct {
+		name string
+		n    StaleNotice
+		want string
+	}{
+		{
+			"cold_start",
+			StaleNotice{Current: "", Target: "1.0.21"},
+			"lark-cli skills not installed, run: lark-cli update",
+		},
+		{
+			"drift",
+			StaleNotice{Current: "1.0.20", Target: "1.0.21"},
+			"lark-cli skills 1.0.20 out of sync with binary 1.0.21, run: lark-cli update",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := tt.n.Message(); got != tt.want {
+				t.Errorf("Message() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestSetGetPending(t *testing.T) {
+	SetPending(nil)
+	t.Cleanup(func() { SetPending(nil) })
+
+	if got := GetPending(); got != nil {
+		t.Fatalf("initial GetPending() = %+v, want nil", got)
+	}
+
+	want := &StaleNotice{Current: "1.0.20", Target: "1.0.21"}
+	SetPending(want)
+	got := GetPending()
+	if got == nil || got.Current != "1.0.20" || got.Target != "1.0.21" {
+		t.Errorf("GetPending() = %+v, want %+v", got, want)
+	}
+}
+
+func TestSetGetPending_Concurrent(t *testing.T) {
+	SetPending(nil)
+	t.Cleanup(func() { SetPending(nil) })
+
+	var wg sync.WaitGroup
+	for i := 0; i < 100; i++ {
+		wg.Add(2)
+		go func() {
+			defer wg.Done()
+			SetPending(&StaleNotice{Current: "a", Target: "b"})
+		}()
+		go func() {
+			defer wg.Done()
+			_ = GetPending()
+		}()
+	}
+	wg.Wait()
+	// Just verifying no race; -race flag enforces.
+}

internal/skillscheck/skip.go

@@ -0,0 +1,27 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package skillscheck
+
+import (
+	"os"
+
+	"github.com/larksuite/cli/internal/update"
+)
+
+// shouldSkip returns true when the skills check should be silently
+// suppressed. Mirrors internal/update.shouldSkip semantics but uses
+// a dedicated opt-out env var so users can disable the skills nag
+// without also disabling the binary update nag.
+func shouldSkip(version string) bool {
+	if os.Getenv("LARKSUITE_CLI_NO_SKILLS_NOTIFIER") != "" {
+		return true
+	}
+	if update.IsCIEnv() {
+		return true
+	}
+	if version == "DEV" || version == "dev" || version == "" {
+		return true
+	}
+	return !update.IsRelease(version)
+}

internal/skillscheck/skip_test.go

@@ -0,0 +1,68 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package skillscheck
+
+import (
+	"os"
+	"testing"
+)
+
+// clearSkillsSkipEnv unsets the env vars shouldSkip checks so the
+// host environment cannot pollute test results.
+func clearSkillsSkipEnv(t *testing.T) {
+	t.Helper()
+	for _, key := range []string{"LARKSUITE_CLI_NO_SKILLS_NOTIFIER", "CI", "BUILD_NUMBER", "RUN_ID"} {
+		t.Setenv(key, "")
+		os.Unsetenv(key)
+	}
+}
+
+func TestShouldSkip(t *testing.T) {
+	tests := []struct {
+		name    string
+		setup   func(t *testing.T)
+		version string
+		want    bool
+	}{
+		{"release_no_skip", clearSkillsSkipEnv, "1.0.21", false},
+		{"dev_uppercase", clearSkillsSkipEnv, "DEV", true},
+		{"dev_lowercase", clearSkillsSkipEnv, "dev", true},
+		{"empty_version", clearSkillsSkipEnv, "", true},
+		{"git_describe", clearSkillsSkipEnv, "1.0.0-12-g9b933f1-dirty", true},
+		{"opt_out", func(t *testing.T) {
+			clearSkillsSkipEnv(t)
+			t.Setenv("LARKSUITE_CLI_NO_SKILLS_NOTIFIER", "1")
+		}, "1.0.21", true},
+		{"ci_env", func(t *testing.T) {
+			clearSkillsSkipEnv(t)
+			t.Setenv("CI", "true")
+		}, "1.0.21", true},
+		{"build_number_env", func(t *testing.T) {
+			clearSkillsSkipEnv(t)
+			t.Setenv("BUILD_NUMBER", "42")
+		}, "1.0.21", true},
+		{"run_id_env", func(t *testing.T) {
+			clearSkillsSkipEnv(t)
+			t.Setenv("RUN_ID", "abc")
+		}, "1.0.21", true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			tt.setup(t)
+			if got := shouldSkip(tt.version); got != tt.want {
+				t.Errorf("shouldSkip(%q) = %v, want %v", tt.version, got, tt.want)
+			}
+		})
+	}
+}
+
+// Independent opt-out: LARKSUITE_CLI_NO_SKILLS_NOTIFIER must NOT be
+// affected by LARKSUITE_CLI_NO_UPDATE_NOTIFIER (different env vars).
+func TestShouldSkip_OptOutIsIndependent(t *testing.T) {
+	clearSkillsSkipEnv(t)
+	t.Setenv("LARKSUITE_CLI_NO_UPDATE_NOTIFIER", "1") // update opt-out, not us
+	if shouldSkip("1.0.21") {
+		t.Error("shouldSkip(release) = true with only LARKSUITE_CLI_NO_UPDATE_NOTIFIER set, want false")
+	}
+}

internal/skillscheck/stamp.go

@@ -0,0 +1,49 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package skillscheck
+
+import (
+	"errors"
+	"io/fs"
+	"path/filepath"
+	"strings"
+
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/internal/vfs"
+)
+
+const stampFile = "skills.stamp"
+
+// stampPath returns ~/.lark-cli/skills.stamp.
+// Uses the BASE config dir (not workspace-aware) because skills install
+// globally via `npx -g`; per-workspace tracking would produce false
+// drift signals when switching workspaces.
+func stampPath() string {
+	return filepath.Join(core.GetBaseConfigDir(), stampFile)
+}
+
+// ReadStamp returns the version recorded in the stamp file. Returns
+// ("", nil) when the file does not exist (interpreted as "never synced").
+// Other I/O errors are returned as-is so callers can fail closed.
+func ReadStamp() (string, error) {
+	data, err := vfs.ReadFile(stampPath())
+	if err != nil {
+		if errors.Is(err, fs.ErrNotExist) {
+			return "", nil
+		}
+		return "", err
+	}
+	return strings.TrimSpace(string(data)), nil
+}
+
+// WriteStamp records `version` as the last successfully synced skills
+// version. Atomic via tmp + rename (validate.AtomicWrite). Creates
+// the base config directory if it does not exist.
+func WriteStamp(version string) error {
+	if err := vfs.MkdirAll(core.GetBaseConfigDir(), 0o700); err != nil {
+		return err
+	}
+	return validate.AtomicWrite(stampPath(), []byte(version), 0o644)
+}

internal/skillscheck/stamp_test.go

@@ -0,0 +1,113 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package skillscheck
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestReadStamp_Missing(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	got, err := ReadStamp()
+	if err != nil {
+		t.Fatalf("ReadStamp() err = %v, want nil for ENOENT", err)
+	}
+	if got != "" {
+		t.Errorf("ReadStamp() = %q, want \"\" for missing file", got)
+	}
+}
+
+func TestReadStamp_Normal(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := os.WriteFile(filepath.Join(dir, "skills.stamp"), []byte("1.0.21"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	got, err := ReadStamp()
+	if err != nil || got != "1.0.21" {
+		t.Errorf("ReadStamp() = (%q, %v), want (\"1.0.21\", nil)", got, err)
+	}
+}
+
+func TestReadStamp_TrailingNewlineTolerated(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := os.WriteFile(filepath.Join(dir, "skills.stamp"), []byte("1.0.21\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	got, _ := ReadStamp()
+	if got != "1.0.21" {
+		t.Errorf("ReadStamp() = %q, want \"1.0.21\" (newline trimmed)", got)
+	}
+}
+
+func TestReadStamp_EmptyFile(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := os.WriteFile(filepath.Join(dir, "skills.stamp"), []byte(""), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	got, err := ReadStamp()
+	if err != nil || got != "" {
+		t.Errorf("ReadStamp() = (%q, %v), want (\"\", nil)", got, err)
+	}
+}
+
+func TestWriteStamp_CreatesDir(t *testing.T) {
+	dir := filepath.Join(t.TempDir(), "nested")
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := WriteStamp("1.0.21"); err != nil {
+		t.Fatalf("WriteStamp() = %v, want nil", err)
+	}
+	got, _ := os.ReadFile(filepath.Join(dir, "skills.stamp"))
+	if string(got) != "1.0.21" {
+		t.Errorf("file content = %q, want \"1.0.21\"", string(got))
+	}
+}
+
+func TestWriteStamp_OverwritesExisting(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := WriteStamp("1.0.20"); err != nil {
+		t.Fatal(err)
+	}
+	if err := WriteStamp("1.0.21"); err != nil {
+		t.Fatal(err)
+	}
+	got, _ := ReadStamp()
+	if got != "1.0.21" {
+		t.Errorf("ReadStamp() after overwrite = %q, want \"1.0.21\"", got)
+	}
+}
+
+func TestWriteStamp_NoTrailingNewline(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := WriteStamp("1.0.21"); err != nil {
+		t.Fatal(err)
+	}
+	raw, _ := os.ReadFile(filepath.Join(dir, "skills.stamp"))
+	if string(raw) != "1.0.21" {
+		t.Errorf("raw file = %q, want exactly \"1.0.21\" (no newline)", string(raw))
+	}
+}
+
+// TestWriteStamp_MkdirAllFailure verifies WriteStamp returns the mkdir error
+// when the base config dir cannot be created (parent path is a regular file).
+func TestWriteStamp_MkdirAllFailure(t *testing.T) {
+	tmp := t.TempDir()
+	blocker := filepath.Join(tmp, "blocker")
+	// Create a regular file where MkdirAll wants to create a directory.
+	if err := os.WriteFile(blocker, []byte("not-a-dir"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	// Point the config dir at a path UNDER the regular file — MkdirAll must fail.
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", filepath.Join(blocker, "child"))
+
+	if err := WriteStamp("1.0.21"); err == nil {
+		t.Fatal("WriteStamp() = nil, want non-nil error from MkdirAll failure")
+	}
+}

internal/update/update.go

@@ -37,9 +37,12 @@ type UpdateInfo struct {
 	Latest  string `json:"latest"`
 }
 
-// Message returns a concise update notification.
+// Message returns a concise update notification including the canonical
+// fix command. Aligned with skillscheck.StaleNotice.Message style so
+// AI agents can parse a unified "run: lark-cli update" hint across
+// both notice types.
 func (u *UpdateInfo) Message() string {
-	return fmt.Sprintf("lark-cli %s available, current %s", u.Latest, u.Current)
+	return fmt.Sprintf("lark-cli %s available, current %s, run: lark-cli update", u.Latest, u.Current)
 }
 
 // pending stores the latest update info for the current process.
@@ -111,10 +114,8 @@ func shouldSkip(version string) bool {
 		return true
 	}
 	// Suppress in CI environments.
-	for _, key := range []string{"CI", "BUILD_NUMBER", "RUN_ID"} {
-		if os.Getenv(key) != "" {
-			return true
-		}
+	if IsCIEnv() {
+		return true
 	}
 	// No version info at all — can't compare.
 	if version == "DEV" || version == "dev" || version == "" {
@@ -141,6 +142,24 @@ func isRelease(version string) bool {
 	return !gitDescribePattern.MatchString(v)
 }
 
+// IsRelease reports whether version looks like a clean published release
+// (semver "1.0.0", or npm prerelease "1.0.0-beta.1") and not a git-describe
+// dev build like "1.0.0-12-g9b933f1-dirty". Exported so internal/skillscheck
+// can apply the same release-only gating without duplicating the regex.
+func IsRelease(version string) bool { return isRelease(version) }
+
+// IsCIEnv returns true when any of the standard CI environment variables
+// is set. Exported for internal/skillscheck so its skip rules track the
+// same CI-suppression behavior as the update notifier.
+func IsCIEnv() bool {
+	for _, key := range []string{"CI", "BUILD_NUMBER", "RUN_ID"} {
+		if os.Getenv(key) != "" {
+			return true
+		}
+	}
+	return false
+}
+
 // --- state file I/O ---
 
 func statePath() string {

internal/update/update_test.go

@@ -10,7 +10,6 @@ import (
 	"net/url"
 	"os"
 	"path/filepath"
-	"strings"
 	"testing"
 	"time"
 )
@@ -143,28 +142,27 @@ func TestShouldSkip(t *testing.T) {
 
 func TestIsRelease(t *testing.T) {
 	tests := []struct {
-		version string
-		want    bool
+		name string
+		ver  string
+		want bool
 	}{
-		{"1.0.0", true},
-		{"v1.0.0", true},
-		{"0.1.0", true},
-		{"1.0.0-beta.1", true},
-		{"1.0.0-rc.1", true},
-		{"2.0.0-alpha.0", true},
-		{"v1.0.0-12-g9b933f1", false},       // git describe
-		{"v1.0.0-12-g9b933f1-dirty", false}, // git describe dirty
-		{"v2.1.0-3-gabcdef0", false},        // git describe short
-		{"9b933f1", false},                  // bare commit hash
-		{"DEV", false},                      // dev marker
-		{"", false},                         // empty
-		{"1.0", false},                      // incomplete semver
+		{"clean_semver", "1.0.0", true},
+		{"v_prefix", "v1.0.0", true},
+		{"prerelease", "1.0.0-beta.1", true},
+		{"rc", "1.0.0-rc.1", true},
+		{"alpha_prerelease", "2.0.0-alpha.0", true},
+		{"git_describe_dirty", "1.0.0-12-g9b933f1-dirty", false},
+		{"git_describe_clean", "1.0.0-12-g9b933f1", false},
+		{"bare_commit_hash", "9b933f1", false},
+		{"dev_marker", "DEV", false},
+		{"incomplete_semver", "1.0", false},
+		{"empty", "", false},
+		{"invalid", "not-a-version", false},
 	}
 	for _, tt := range tests {
-		t.Run(tt.version, func(t *testing.T) {
-			got := isRelease(tt.version)
-			if got != tt.want {
-				t.Errorf("isRelease(%q) = %v, want %v", tt.version, got, tt.want)
+		t.Run(tt.name, func(t *testing.T) {
+			if got := IsRelease(tt.ver); got != tt.want {
+				t.Errorf("IsRelease(%q) = %v, want %v", tt.ver, got, tt.want)
 			}
 		})
 	}
@@ -172,13 +170,10 @@ func TestIsRelease(t *testing.T) {
 
 func TestUpdateInfoMethods(t *testing.T) {
 	info := &UpdateInfo{Current: "1.0.0", Latest: "2.0.0"}
-
-	msg := info.Message()
-	if !strings.Contains(msg, "2.0.0") {
-		t.Errorf("Message() missing latest version: %s", msg)
-	}
-	if !strings.Contains(msg, "1.0.0") {
-		t.Errorf("Message() missing current version: %s", msg)
+	got := info.Message()
+	want := "lark-cli 2.0.0 available, current 1.0.0, run: lark-cli update"
+	if got != want {
+		t.Errorf("Message() = %q, want %q", got, want)
 	}
 }
 
@@ -264,3 +259,19 @@ func TestPendingAtomicAccess(t *testing.T) {
 	// Clean up for other tests
 	SetPending(nil)
 }
+
+func TestIsCIEnv(t *testing.T) {
+	clearSkipEnv(t)
+	if IsCIEnv() {
+		t.Fatal("IsCIEnv() = true after clearSkipEnv, want false")
+	}
+	for _, key := range []string{"CI", "BUILD_NUMBER", "RUN_ID"} {
+		t.Run(key, func(t *testing.T) {
+			clearSkipEnv(t)
+			t.Setenv(key, "1")
+			if !IsCIEnv() {
+				t.Errorf("IsCIEnv() = false with %s=1, want true", key)
+			}
+		})
+	}
+}

shortcuts/task/shortcuts.go

@@ -13,6 +13,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 )
@@ -106,7 +107,7 @@ func buildTaskCreateBody(runtime *common.RuntimeContext) (map[string]interface{}
 	// Handle generic JSON payload if provided
 	if dataStr := runtime.Str("data"); dataStr != "" {
 		if err := json.Unmarshal([]byte(dataStr), &body); err != nil {
-			return nil, fmt.Errorf("--data must be a valid JSON object: %v", err)
+			return nil, output.ErrValidation("--data must be a valid JSON object: %v", err)
 		}
 	}
 
@@ -142,7 +143,7 @@ func buildTaskCreateBody(runtime *common.RuntimeContext) (map[string]interface{}
 	if dueStr := runtime.Str("due"); dueStr != "" {
 		dueObj, err := parseTaskTime(dueStr)
 		if err != nil {
-			return nil, fmt.Errorf("failed to parse due time: %v", err)
+			return nil, output.ErrValidation("failed to parse due time: %v", err)
 		}
 		body["due"] = dueObj
 	}
@@ -153,7 +154,7 @@ func buildTaskCreateBody(runtime *common.RuntimeContext) (map[string]interface{}
 
 	summary, _ := body["summary"].(string)
 	if strings.TrimSpace(summary) == "" {
-		return nil, fmt.Errorf("task summary is required")
+		return nil, output.ErrValidation("task summary is required")
 	}
 
 	return body, nil
@@ -209,7 +210,7 @@ var CreateTask = common.Shortcut{
 		var result map[string]interface{}
 		if err == nil {
 			if parseErr := json.Unmarshal(apiResp.RawBody, &result); parseErr != nil {
-				return fmt.Errorf("failed to parse response: %v", parseErr)
+				return output.Errorf(output.ExitAPI, "api_error", "failed to parse response: %v", parseErr)
 			}
 		}
 

shortcuts/task/task_body_test.go

@@ -0,0 +1,156 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package task
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/larksuite/cli/internal/output"
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+func TestBuildTaskCreateBody_StructuredErrors(t *testing.T) {
+	tests := []struct {
+		name       string
+		data       string
+		summary    string
+		due        string
+		wantCode   int
+		wantType   string
+		wantSubstr string
+	}{
+		{
+			name:       "invalid JSON data returns ErrValidation",
+			data:       "not-json",
+			summary:    "test",
+			wantCode:   output.ExitValidation,
+			wantType:   "validation",
+			wantSubstr: "--data must be a valid JSON object",
+		},
+		{
+			name:       "missing summary returns ErrValidation",
+			data:       "",
+			summary:    "",
+			wantCode:   output.ExitValidation,
+			wantType:   "validation",
+			wantSubstr: "task summary is required",
+		},
+		{
+			name:       "invalid due time returns ErrValidation",
+			data:       "",
+			summary:    "test task",
+			due:        "not-a-valid-time",
+			wantCode:   output.ExitValidation,
+			wantType:   "validation",
+			wantSubstr: "failed to parse due time",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cmd := &cobra.Command{}
+			cmd.Flags().String("data", tt.data, "")
+			cmd.Flags().String("summary", tt.summary, "")
+			cmd.Flags().String("description", "", "")
+			cmd.Flags().String("assignee", "", "")
+			cmd.Flags().String("follower", "", "")
+			cmd.Flags().String("due", tt.due, "")
+			cmd.Flags().String("tasklist-id", "", "")
+			cmd.Flags().String("idempotency-key", "", "")
+
+			runtime := &common.RuntimeContext{Cmd: cmd}
+			_, err := buildTaskCreateBody(runtime)
+			if err == nil {
+				t.Fatal("expected error, got nil")
+			}
+
+			var exitErr *output.ExitError
+			if !errors.As(err, &exitErr) {
+				t.Fatalf("error type = %T, want *output.ExitError; error = %v", err, err)
+			}
+			if exitErr.Code != tt.wantCode {
+				t.Errorf("exit code = %d, want %d", exitErr.Code, tt.wantCode)
+			}
+			if exitErr.Detail == nil {
+				t.Fatal("expected non-nil error detail")
+			}
+			if exitErr.Detail.Type != tt.wantType {
+				t.Errorf("error type = %q, want %q", exitErr.Detail.Type, tt.wantType)
+			}
+		})
+	}
+}
+
+func TestBuildTaskUpdateBody_StructuredErrors(t *testing.T) {
+	tests := []struct {
+		name       string
+		data       string
+		summary    string
+		due        string
+		wantCode   int
+		wantType   string
+		wantSubstr string
+	}{
+		{
+			name:       "invalid JSON data returns ErrValidation",
+			data:       "not-json",
+			summary:    "",
+			due:        "",
+			wantCode:   output.ExitValidation,
+			wantType:   "validation",
+			wantSubstr: "--data must be a valid JSON object",
+		},
+		{
+			name:       "no fields to update returns ErrValidation",
+			data:       "",
+			summary:    "",
+			due:        "",
+			wantCode:   output.ExitValidation,
+			wantType:   "validation",
+			wantSubstr: "no fields to update",
+		},
+		{
+			name:       "invalid due time returns ErrValidation",
+			data:       "",
+			summary:    "",
+			due:        "not-a-valid-time",
+			wantCode:   output.ExitValidation,
+			wantType:   "validation",
+			wantSubstr: "failed to parse due time",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cmd := &cobra.Command{}
+			cmd.Flags().String("data", tt.data, "")
+			cmd.Flags().String("summary", tt.summary, "")
+			cmd.Flags().String("description", "", "")
+			cmd.Flags().String("due", tt.due, "")
+
+			runtime := &common.RuntimeContext{Cmd: cmd}
+			_, err := buildTaskUpdateBody(runtime)
+			if err == nil {
+				t.Fatal("expected error, got nil")
+			}
+
+			var exitErr *output.ExitError
+			if !errors.As(err, &exitErr) {
+				t.Fatalf("error type = %T, want *output.ExitError; error = %v", err, err)
+			}
+			if exitErr.Code != tt.wantCode {
+				t.Errorf("exit code = %d, want %d", exitErr.Code, tt.wantCode)
+			}
+			if exitErr.Detail == nil {
+				t.Fatal("expected non-nil error detail")
+			}
+			if exitErr.Detail.Type != tt.wantType {
+				t.Errorf("error type = %q, want %q", exitErr.Detail.Type, tt.wantType)
+			}
+		})
+	}
+}

shortcuts/task/task_query_helpers.go

@@ -8,6 +8,8 @@ import (
 	"strconv"
 	"strings"
 	"time"
+
+	"github.com/larksuite/cli/internal/output"
 )
 
 func splitAndTrimCSV(input string) []string {
@@ -44,7 +46,7 @@ func parseTimeRangeMillis(input string) (string, string, error) {
 		}
 		startSecInt, err = strconv.ParseInt(startSec, 10, 64)
 		if err != nil {
-			return "", "", fmt.Errorf("invalid start timestamp: %w", err)
+			return "", "", output.ErrValidation("invalid start timestamp: %v", err)
 		}
 		hasStart = true
 		startMillis = startSec + "000"
@@ -56,13 +58,13 @@ func parseTimeRangeMillis(input string) (string, string, error) {
 		}
 		endSecInt, err = strconv.ParseInt(endSec, 10, 64)
 		if err != nil {
-			return "", "", fmt.Errorf("invalid end timestamp: %w", err)
+			return "", "", output.ErrValidation("invalid end timestamp: %v", err)
 		}
 		hasEnd = true
 		endMillis = endSec + "000"
 	}
 	if hasStart && hasEnd && startSecInt > endSecInt {
-		return "", "", fmt.Errorf("start time must be earlier than or equal to end time")
+		return "", "", output.ErrValidation("start time must be earlier than or equal to end time")
 	}
 	return startMillis, endMillis, nil
 }
@@ -89,7 +91,7 @@ func parseTimeRangeRFC3339(input string) (string, string, error) {
 		}
 		startSecInt, err = strconv.ParseInt(startSec, 10, 64)
 		if err != nil {
-			return "", "", fmt.Errorf("invalid start timestamp: %w", err)
+			return "", "", output.ErrValidation("invalid start timestamp: %v", err)
 		}
 		hasStart = true
 		startTime = time.Unix(startSecInt, 0).Local().Format(time.RFC3339)
@@ -101,13 +103,13 @@ func parseTimeRangeRFC3339(input string) (string, string, error) {
 		}
 		endSecInt, err = strconv.ParseInt(endSec, 10, 64)
 		if err != nil {
-			return "", "", fmt.Errorf("invalid end timestamp: %w", err)
+			return "", "", output.ErrValidation("invalid end timestamp: %v", err)
 		}
 		hasEnd = true
 		endTime = time.Unix(endSecInt, 0).Local().Format(time.RFC3339)
 	}
 	if hasStart && hasEnd && startSecInt > endSecInt {
-		return "", "", fmt.Errorf("start time must be earlier than or equal to end time")
+		return "", "", output.ErrValidation("start time must be earlier than or equal to end time")
 	}
 	return startTime, endTime, nil
 }

shortcuts/task/task_query_helpers_test.go

@@ -4,8 +4,11 @@
 package task
 
 import (
+	"errors"
 	"strings"
 	"testing"
+
+	"github.com/larksuite/cli/internal/output"
 )
 
 func TestSplitAndTrimCSV(t *testing.T) {
@@ -95,6 +98,18 @@ func TestParseTimeRangeMillisAndRequireSearchFilter(t *testing.T) {
 				if err == nil {
 					t.Fatalf("parseTimeRangeMillis(%q) expected error, got nil", tt.input)
 				}
+				if tt.name == "reversed range fails fast" {
+					var exitErr *output.ExitError
+					if !errors.As(err, &exitErr) {
+						t.Fatalf("error type = %T, want *output.ExitError; error = %v", err, err)
+					}
+					if exitErr.Code != output.ExitValidation {
+						t.Errorf("exit code = %d, want %d", exitErr.Code, output.ExitValidation)
+					}
+					if exitErr.Detail == nil || exitErr.Detail.Type != "validation" {
+						t.Errorf("error detail type = %q, want %q", exitErr.Detail.Type, "validation")
+					}
+				}
 				return
 			}
 			if err != nil {
@@ -260,6 +275,15 @@ func TestRenderRelatedTasksPretty(t *testing.T) {
 						if err == nil {
 							t.Fatal("expected error, got nil")
 						}
+						if tt.name == "reversed range fails fast" {
+							var exitErr *output.ExitError
+							if !errors.As(err, &exitErr) {
+								t.Fatalf("error type = %T, want *output.ExitError; error = %v", err, err)
+							}
+							if exitErr.Code != output.ExitValidation {
+								t.Errorf("exit code = %d, want %d", exitErr.Code, output.ExitValidation)
+							}
+						}
 						return
 					}
 					if err != nil {

shortcuts/task/task_update.go

@@ -76,7 +76,7 @@ var UpdateTask = common.Shortcut{
 			var result map[string]interface{}
 			if err == nil {
 				if parseErr := json.Unmarshal(apiResp.RawBody, &result); parseErr != nil {
-					return fmt.Errorf("failed to parse response for task %s: %v", taskId, parseErr)
+					return output.Errorf(output.ExitAPI, "api_error", "failed to parse response for task %s: %v", taskId, parseErr)
 				}
 			}
 
@@ -133,7 +133,7 @@ func buildTaskUpdateBody(runtime *common.RuntimeContext) (map[string]interface{}
 
 	if dataStr := runtime.Str("data"); dataStr != "" {
 		if err := json.Unmarshal([]byte(dataStr), &taskObj); err != nil {
-			return nil, fmt.Errorf("--data must be a valid JSON object: %v", err)
+			return nil, output.ErrValidation("--data must be a valid JSON object: %v", err)
 		}
 		// If data is provided, assume keys are update fields
 		for k := range taskObj {
@@ -158,7 +158,7 @@ func buildTaskUpdateBody(runtime *common.RuntimeContext) (map[string]interface{}
 	if dueStr := runtime.Str("due"); dueStr != "" {
 		dueObj, err := parseTaskTime(dueStr)
 		if err != nil {
-			return nil, fmt.Errorf("failed to parse due time: %v", err)
+			return nil, output.ErrValidation("failed to parse due time: %v", err)
 		}
 		taskObj["due"] = dueObj
 		if !contains(updateFields, "due") {
@@ -167,7 +167,7 @@ func buildTaskUpdateBody(runtime *common.RuntimeContext) (map[string]interface{}
 	}
 
 	if len(updateFields) == 0 {
-		return nil, fmt.Errorf("no fields to update")
+		return nil, output.ErrValidation("no fields to update")
 	}
 
 	return map[string]interface{}{

shortcuts/task/task_util.go

@@ -24,7 +24,7 @@ func isRelativeTime(s string) bool {
 func parseRelativeTime(s string) (time.Time, error) {
 	matches := relativeTimeRe.FindStringSubmatch(s)
 	if len(matches) == 0 {
-		return time.Time{}, fmt.Errorf("invalid relative time format: %s", s)
+		return time.Time{}, output.ErrValidation("invalid relative time format: %s", s)
 	}
 
 	sign := matches[1]
@@ -50,9 +50,8 @@ func parseRelativeTime(s string) (time.Time, error) {
 		return now.Add(time.Duration(amount) * time.Minute), nil
 	case "h":
 		return now.Add(time.Duration(amount) * time.Hour), nil
-	default:
-		return time.Time{}, fmt.Errorf("unknown unit: %s", unit)
 	}
+	panic(fmt.Sprintf("unreachable: relativeTimeRe matched unexpected unit %q", unit))
 }
 
 const (

shortcuts/task/task_util_test.go

@@ -4,8 +4,10 @@
 package task
 
 import (
+	"errors"
 	"testing"
 
+	"github.com/larksuite/cli/internal/output"
 	"github.com/smartystreets/goconvey/convey"
 )
 
@@ -17,3 +19,44 @@ func TestContains(t *testing.T) {
 		convey.So(contains([]string{}, "a"), convey.ShouldBeFalse)
 	})
 }
+
+func TestParseRelativeTime_StructuredErrors(t *testing.T) {
+	tests := []struct {
+		name       string
+		input      string
+		wantCode   int
+		wantType   string
+		wantSubstr string
+	}{
+		{
+			name:       "invalid format returns ErrValidation",
+			input:      "not-relative",
+			wantCode:   output.ExitValidation,
+			wantType:   "validation",
+			wantSubstr: "invalid relative time format",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			_, err := parseRelativeTime(tt.input)
+			if err == nil {
+				t.Fatalf("parseRelativeTime(%q) expected error, got nil", tt.input)
+			}
+
+			var exitErr *output.ExitError
+			if !errors.As(err, &exitErr) {
+				t.Fatalf("error type = %T, want *output.ExitError; error = %v", err, err)
+			}
+			if exitErr.Code != tt.wantCode {
+				t.Errorf("exit code = %d, want %d", exitErr.Code, tt.wantCode)
+			}
+			if exitErr.Detail == nil {
+				t.Fatal("expected non-nil error detail")
+			}
+			if exitErr.Detail.Type != tt.wantType {
+				t.Errorf("error type = %q, want %q", exitErr.Detail.Type, tt.wantType)
+			}
+		})
+	}
+}

shortcuts/vc/shortcuts.go

@@ -11,5 +11,8 @@ func Shortcuts() []common.Shortcut {
 		VCSearch,
 		VCNotes,
 		VCRecording,
+		VCMeetingJoin,
+		VCMeetingLeave,
+		VCMeetingEvents,
 	}
 }

shortcuts/vc/vc_meeting_events.go

@@ -0,0 +1,979 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package vc
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+	"unicode"
+
+	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
+
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const (
+	vcMeetingEventsAPIPath     = "/open-apis/vc/v1/bots/events"
+	defaultVCMeetingEventsSize = 20
+	minVCMeetingEventsPageSize = 20
+	maxVCMeetingEventsPageSize = 100
+	maxVCMeetingEventsPages    = 200
+)
+
+// toUnixSeconds converts a supported CLI time input into a Unix seconds string.
+func toUnixSeconds(input string, hint ...string) (string, error) {
+	ts, err := common.ParseTime(input, hint...)
+	if err != nil {
+		return "", err
+	}
+	if _, err := strconv.ParseInt(ts, 10, 64); err != nil {
+		return "", fmt.Errorf("invalid timestamp %q: %w", ts, err)
+	}
+	return ts, nil
+}
+
+// VCMeetingEvents lists bot meeting events for a meeting.
+var VCMeetingEvents = common.Shortcut{
+	Service:     "vc",
+	Command:     "+meeting-events",
+	Description: "List bot meeting events by meeting ID",
+	Risk:        "read",
+	Scopes:      []string{"vc:meeting.meetingevent:read"},
+	AuthTypes:   []string{"user"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "meeting-id", Required: true, Desc: "meeting ID to query"},
+		{Name: "start", Desc: "time lower bound (ISO 8601, YYYY-MM-DD, or Unix seconds)"},
+		{Name: "end", Desc: "time upper bound (ISO 8601, YYYY-MM-DD, or Unix seconds)"},
+		{Name: "page-token", Desc: "page token for the next page"},
+		{Name: "page-size", Default: "20", Desc: "page size, 20-100 (default 20)"},
+		{Name: "page-all", Type: "bool", Desc: "automatically paginate through all available pages"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if err := validateMeetingEventsMeetingID(runtime.Str("meeting-id")); err != nil {
+			return err
+		}
+		if _, _, err := parseMeetingEventsTimeRange(runtime); err != nil {
+			return err
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		startTime, endTime, err := parseMeetingEventsTimeRange(runtime)
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
+		params, err := buildMeetingEventsParams(runtime, startTime, endTime)
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
+		dryRun := common.NewDryRunAPI()
+		if runtime.Bool("page-all") {
+			dryRun = dryRun.Desc("Auto-paginates through all available pages")
+		}
+		dryRun = dryRun.GET(vcMeetingEventsAPIPath)
+		if flat := flattenQueryParams(params); len(flat) > 0 {
+			dryRun.Params(flat)
+		}
+		return dryRun
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		startTime, endTime, err := parseMeetingEventsTimeRange(runtime)
+		if err != nil {
+			return err
+		}
+		data, events, hasMore, pageToken, err := fetchMeetingEvents(ctx, runtime, startTime, endTime)
+		if err != nil {
+			return err
+		}
+		events = compactMeetingEvents(events)
+		outData := map[string]interface{}{
+			"events":     events,
+			"has_more":   data["has_more"],
+			"page_token": data["page_token"],
+		}
+
+		timeline := buildMeetingEventTimeline(events)
+		runtime.OutFormat(outData, &output.Meta{Count: len(events)}, func(w io.Writer) {
+			if len(timeline.entries) == 0 {
+				fmt.Fprintln(w, "No meeting events.")
+				return
+			}
+			io.WriteString(w, renderMeetingEventsPretty(timeline))
+		})
+		if runtime.Format == "pretty" && pageToken != "" {
+			fmt.Fprintf(runtime.IO().Out, "\npage_token: %s\n", pageToken)
+			if hasMore {
+				fmt.Fprintln(runtime.IO().Out, "more available")
+			}
+		}
+		return nil
+	},
+}
+
+func meetingEventsPageSize(runtime *common.RuntimeContext) (int, error) {
+	if runtime.Bool("page-all") {
+		return maxVCMeetingEventsPageSize, nil
+	}
+	pageSizeStr := strings.TrimSpace(runtime.Str("page-size"))
+	if pageSizeStr == "" {
+		return defaultVCMeetingEventsSize, nil
+	}
+	pageSize, err := strconv.Atoi(pageSizeStr)
+	if err != nil {
+		return 0, common.FlagErrorf("invalid --page-size %q: must be an integer", pageSizeStr)
+	}
+	if pageSize < minVCMeetingEventsPageSize {
+		return minVCMeetingEventsPageSize, nil
+	}
+	if pageSize > maxVCMeetingEventsPageSize {
+		return maxVCMeetingEventsPageSize, nil
+	}
+	return pageSize, nil
+}
+
+func meetingEventsPaginationConfig(runtime *common.RuntimeContext) (bool, int) {
+	if !runtime.Bool("page-all") {
+		return false, 0
+	}
+	return true, maxVCMeetingEventsPages
+}
+
+func validateMeetingEventsMeetingID(meetingID string) error {
+	meetingID = strings.TrimSpace(meetingID)
+	if meetingID == "" {
+		return common.FlagErrorf("--meeting-id is required")
+	}
+	value, err := strconv.ParseInt(meetingID, 10, 64)
+	if err != nil || value <= 0 {
+		return common.FlagErrorf("--meeting-id must be a positive integer, got %q", meetingID)
+	}
+	return nil
+}
+
+// parseMeetingEventsTimeRange validates --start/--end and returns Unix seconds strings.
+func parseMeetingEventsTimeRange(runtime *common.RuntimeContext) (string, string, error) {
+	start := strings.TrimSpace(runtime.Str("start"))
+	end := strings.TrimSpace(runtime.Str("end"))
+	if start == "" && end == "" {
+		return "", "", nil
+	}
+
+	var startTime, endTime string
+	if start != "" {
+		parsed, err := toUnixSeconds(start)
+		if err != nil {
+			return "", "", output.ErrValidation("--start: %v", err)
+		}
+		startTime = parsed
+	}
+	if end != "" {
+		parsed, err := toUnixSeconds(end, "end")
+		if err != nil {
+			return "", "", output.ErrValidation("--end: %v", err)
+		}
+		endTime = parsed
+	}
+	if startTime != "" && endTime != "" {
+		startValue, _ := strconv.ParseInt(startTime, 10, 64)
+		endValue, _ := strconv.ParseInt(endTime, 10, 64)
+		if startValue > endValue {
+			return "", "", output.ErrValidation("--start (%s) is after --end (%s)", start, end)
+		}
+	}
+	return startTime, endTime, nil
+}
+
+func buildMeetingEventsParams(runtime *common.RuntimeContext, startTime, endTime string) (larkcore.QueryParams, error) {
+	pageSize, err := meetingEventsPageSize(runtime)
+	if err != nil {
+		return nil, err
+	}
+
+	params := make(larkcore.QueryParams)
+	params.Set("meeting_id", strings.TrimSpace(runtime.Str("meeting-id")))
+	params.Set("page_size", strconv.Itoa(pageSize))
+	if pageToken := strings.TrimSpace(runtime.Str("page-token")); pageToken != "" {
+		params.Set("page_token", pageToken)
+	}
+	if startTime != "" {
+		params.Set("start_time", startTime)
+	}
+	if endTime != "" {
+		params.Set("end_time", endTime)
+	}
+	return params, nil
+}
+
+func fetchMeetingEvents(ctx context.Context, runtime *common.RuntimeContext, startTime, endTime string) (map[string]interface{}, []interface{}, bool, string, error) {
+	params, err := buildMeetingEventsParams(runtime, startTime, endTime)
+	if err != nil {
+		return nil, nil, false, "", err
+	}
+	autoPaginate, pageLimit := meetingEventsPaginationConfig(runtime)
+	if !autoPaginate {
+		data, err := runtime.DoAPIJSON(http.MethodGet, vcMeetingEventsAPIPath, params, nil)
+		if err != nil {
+			return nil, nil, false, "", err
+		}
+		if data == nil {
+			data = map[string]interface{}{}
+		}
+		events := common.GetSlice(data, "events")
+		hasMore, _ := data["has_more"].(bool)
+		pageToken, _ := data["page_token"].(string)
+		return data, events, hasMore, pageToken, nil
+	}
+
+	var (
+		allEvents     []interface{}
+		lastData      map[string]interface{}
+		lastPageToken string
+		lastHasMore   bool
+	)
+	for page := 0; page < pageLimit; page++ {
+		data, err := runtime.DoAPIJSON(http.MethodGet, vcMeetingEventsAPIPath, params, nil)
+		if err != nil {
+			return nil, nil, false, "", err
+		}
+		if data == nil {
+			data = map[string]interface{}{}
+		}
+		lastData = data
+		events := common.GetSlice(data, "events")
+		allEvents = append(allEvents, events...)
+		lastHasMore, _ = data["has_more"].(bool)
+		lastPageToken, _ = data["page_token"].(string)
+		if !lastHasMore || lastPageToken == "" {
+			break
+		}
+		params.Set("page_token", lastPageToken)
+	}
+	if lastData == nil {
+		lastData = map[string]interface{}{}
+	}
+	lastData["events"] = allEvents
+	lastData["has_more"] = lastHasMore
+	lastData["page_token"] = lastPageToken
+	return lastData, allEvents, lastHasMore, lastPageToken, nil
+}
+
+func flattenQueryParams(params larkcore.QueryParams) map[string]interface{} {
+	if len(params) == 0 {
+		return nil
+	}
+	flat := make(map[string]interface{}, len(params))
+	for key, values := range params {
+		switch len(values) {
+		case 0:
+			continue
+		case 1:
+			flat[key] = values[0]
+		default:
+			copied := make([]string, len(values))
+			copy(copied, values)
+			flat[key] = copied
+		}
+	}
+	return flat
+}
+
+func compactMeetingEvents(events []interface{}) []interface{} {
+	compacted := make([]interface{}, 0, len(events))
+	for _, raw := range events {
+		event, _ := raw.(map[string]interface{})
+		if event == nil {
+			continue
+		}
+		if payload := common.GetMap(event, "payload"); payload != nil {
+			event["payload"] = compactMeetingPayload(payload)
+		}
+		compacted = append(compacted, event)
+	}
+	return compacted
+}
+
+func compactMeetingPayload(payload map[string]interface{}) map[string]interface{} {
+	if payload == nil {
+		return nil
+	}
+	compacted := make(map[string]interface{}, len(payload))
+	for key, value := range payload {
+		if items, ok := value.([]interface{}); ok && len(items) == 0 {
+			continue
+		}
+		compacted[key] = value
+	}
+	return compacted
+}
+
+type meetingTimeline struct {
+	topic     string
+	startTime time.Time
+	hasStart  bool
+	endTime   time.Time
+	hasEnd    bool
+	entries   []meetingTimelineEntry
+}
+
+type meetingTimelineEntry struct {
+	when        time.Time
+	hasWhen     bool
+	sequence    int
+	group       int
+	subject     string
+	description string
+	details     []string
+}
+
+func buildMeetingEventTimeline(events []interface{}) meetingTimeline {
+	timeline := meetingTimeline{}
+	var sequence int
+	var group int
+	for _, raw := range events {
+		event, _ := raw.(map[string]interface{})
+		if event == nil {
+			continue
+		}
+		payload := common.GetMap(event, "payload")
+		if payload == nil {
+			continue
+		}
+		if timeline.topic == "" || !timeline.hasStart || !timeline.hasEnd {
+			populateMeetingHeader(&timeline, common.GetMap(payload, "meeting"))
+		}
+		for _, entry := range buildTimelineEntriesForEvent(event, &sequence, group) {
+			timeline.entries = append(timeline.entries, entry)
+		}
+		group++
+	}
+	sort.SliceStable(timeline.entries, func(i, j int) bool {
+		left := timeline.entries[i]
+		right := timeline.entries[j]
+		switch {
+		case left.hasWhen && right.hasWhen:
+			if left.when.Equal(right.when) {
+				return left.sequence < right.sequence
+			}
+			return left.when.Before(right.when)
+		case left.hasWhen:
+			return true
+		case right.hasWhen:
+			return false
+		default:
+			return left.sequence < right.sequence
+		}
+	})
+	return timeline
+}
+
+func populateMeetingHeader(timeline *meetingTimeline, meeting map[string]interface{}) {
+	if timeline == nil || meeting == nil {
+		return
+	}
+	if timeline.topic == "" {
+		timeline.topic = common.GetString(meeting, "topic")
+	}
+	if !timeline.hasStart {
+		if parsed, ok := parseFlexibleTime(common.GetString(meeting, "start_time")); ok {
+			timeline.startTime = parsed
+			timeline.hasStart = true
+		}
+	}
+	if !timeline.hasEnd {
+		if parsed, ok := parseFlexibleTime(common.GetString(meeting, "end_time")); ok {
+			timeline.endTime = parsed
+			timeline.hasEnd = true
+		}
+	}
+}
+
+func buildTimelineEntriesForEvent(event map[string]interface{}, sequence *int, group int) []meetingTimelineEntry {
+	payload := common.GetMap(event, "payload")
+	if payload == nil {
+		return nil
+	}
+	eventType := meetingEventType(event)
+	eventTime, eventTimeOK := parseFlexibleTime(common.GetString(event, "event_time"))
+	switch eventType {
+	case "participant_joined":
+		return participantJoinedEntries(payload, eventTime, eventTimeOK, sequence, group)
+	case "participant_left":
+		return participantLeftEntries(payload, eventTime, eventTimeOK, sequence, group)
+	case "transcript_received":
+		return transcriptEntries(payload, eventTime, eventTimeOK, sequence, group)
+	case "chat_received":
+		return chatEntries(payload, eventTime, eventTimeOK, sequence, group)
+	case "magic_share_started":
+		return magicShareStartedEntries(payload, eventTime, eventTimeOK, sequence, group)
+	case "magic_share_ended":
+		return magicShareEndedEntries(payload, eventTime, eventTimeOK, sequence, group)
+	default:
+		return []meetingTimelineEntry{newTimelineEntry(eventTime, eventTimeOK, sequence, group, meetingEventUserDisplayName(nil), meetingEventSummary(event), nil)}
+	}
+}
+
+func participantJoinedEntries(payload map[string]interface{}, fallbackTime time.Time, fallbackOK bool, sequence *int, group int) []meetingTimelineEntry {
+	items := common.GetSlice(payload, "participant_joined_items")
+	if len(items) == 0 {
+		return []meetingTimelineEntry{newTimelineEntry(fallbackTime, fallbackOK, sequence, group, "", "加入了会议", nil)}
+	}
+	entries := make([]meetingTimelineEntry, 0, len(items))
+	for _, raw := range items {
+		item, _ := raw.(map[string]interface{})
+		when, ok := parseFlexibleTime(common.GetString(item, "join_time"))
+		if !ok {
+			when, ok = fallbackTime, fallbackOK
+		}
+		subject := meetingEventUserWithID(common.GetMap(item, "participant"))
+		if subject == "" {
+			subject = "未知参会人"
+		}
+		entries = append(entries, newTimelineEntry(when, ok, sequence, group, subject, "加入了会议", nil))
+	}
+	return entries
+}
+
+func participantLeftEntries(payload map[string]interface{}, fallbackTime time.Time, fallbackOK bool, sequence *int, group int) []meetingTimelineEntry {
+	items := common.GetSlice(payload, "participant_left_items")
+	if len(items) == 0 {
+		return []meetingTimelineEntry{newTimelineEntry(fallbackTime, fallbackOK, sequence, group, "", "离开了会议", nil)}
+	}
+	entries := make([]meetingTimelineEntry, 0, len(items))
+	for _, raw := range items {
+		item, _ := raw.(map[string]interface{})
+		when, ok := parseFlexibleTime(common.GetString(item, "leave_time"))
+		if !ok {
+			when, ok = fallbackTime, fallbackOK
+		}
+		subject := meetingEventUserWithID(common.GetMap(item, "participant"))
+		if subject == "" {
+			subject = "未知参会人"
+		}
+		entries = append(entries, newTimelineEntry(when, ok, sequence, group, subject, leaveAction(item), nil))
+	}
+	return entries
+}
+
+func transcriptEntries(payload map[string]interface{}, fallbackTime time.Time, fallbackOK bool, sequence *int, group int) []meetingTimelineEntry {
+	items := common.GetSlice(payload, "transcript_received_items")
+	if len(items) == 0 {
+		return []meetingTimelineEntry{newTimelineEntry(fallbackTime, fallbackOK, sequence, group, "", "产生了转写", nil)}
+	}
+	entries := make([]meetingTimelineEntry, 0, len(items))
+	for _, raw := range items {
+		item, _ := raw.(map[string]interface{})
+		when, ok := parseFlexibleTime(common.GetString(item, "start_time_ms"))
+		if !ok {
+			when, ok = fallbackTime, fallbackOK
+		}
+		subject := meetingEventUserWithID(common.GetMap(item, "speaker"))
+		if subject == "" {
+			subject = "未知发言人"
+		}
+		text := strings.TrimSpace(common.GetString(item, "text"))
+		description := "产生了转写"
+		if text != "" {
+			description = text
+		}
+		entries = append(entries, newTimelineEntry(when, ok, sequence, group, subject, description, nil))
+	}
+	return entries
+}
+
+func chatEntries(payload map[string]interface{}, fallbackTime time.Time, fallbackOK bool, sequence *int, group int) []meetingTimelineEntry {
+	items := common.GetSlice(payload, "chat_received_items")
+	if len(items) == 0 {
+		return []meetingTimelineEntry{newTimelineEntry(fallbackTime, fallbackOK, sequence, group, "", "发送了消息", nil)}
+	}
+	entries := make([]meetingTimelineEntry, 0, len(items))
+	for _, raw := range items {
+		item, _ := raw.(map[string]interface{})
+		when, ok := parseFlexibleTime(common.GetString(item, "send_time"))
+		if !ok {
+			when, ok = fallbackTime, fallbackOK
+		}
+		subject := meetingEventUserWithID(common.GetMap(item, "operator"))
+		if subject == "" {
+			subject = "未知发送者"
+		}
+		typeLabel := chatMessageTypeLabel(item)
+		description := strings.TrimSpace(common.GetString(item, "content"))
+		if description == "" {
+			description = fmt.Sprintf("[%s] 发送了消息", typeLabel)
+		} else {
+			description = fmt.Sprintf("[%s] %s", typeLabel, description)
+		}
+		entries = append(entries, newTimelineEntry(when, ok, sequence, group, subject, description, nil))
+	}
+	return entries
+}
+
+func magicShareStartedEntries(payload map[string]interface{}, fallbackTime time.Time, fallbackOK bool, sequence *int, group int) []meetingTimelineEntry {
+	items := common.GetSlice(payload, "magic_share_started_items")
+	if len(items) == 0 {
+		return []meetingTimelineEntry{newTimelineEntry(fallbackTime, fallbackOK, sequence, group, "", "开始共享内容", nil)}
+	}
+	entries := make([]meetingTimelineEntry, 0, len(items))
+	for _, raw := range items {
+		item, _ := raw.(map[string]interface{})
+		when, ok := parseFlexibleTime(common.GetString(item, "time"))
+		if !ok {
+			when, ok = fallbackTime, fallbackOK
+		}
+		subject := meetingEventUserWithID(common.GetMap(item, "operator"))
+		if subject == "" {
+			subject = "未知用户"
+		}
+		title := strings.TrimSpace(common.GetString(common.GetMap(item, "share_doc"), "title"))
+		url := strings.TrimSpace(common.GetString(common.GetMap(item, "share_doc"), "url"))
+		description := "开始共享内容"
+		if title != "" {
+			description = fmt.Sprintf("开始共享「%s」", title)
+		}
+		var details []string
+		if url != "" {
+			details = append(details, "URL: "+url)
+		}
+		entries = append(entries, newTimelineEntry(when, ok, sequence, group, subject, description, details))
+	}
+	return entries
+}
+
+func magicShareEndedEntries(payload map[string]interface{}, fallbackTime time.Time, fallbackOK bool, sequence *int, group int) []meetingTimelineEntry {
+	items := common.GetSlice(payload, "magic_share_ended_items")
+	if len(items) == 0 {
+		return []meetingTimelineEntry{newTimelineEntry(fallbackTime, fallbackOK, sequence, group, "", "结束共享", nil)}
+	}
+	entries := make([]meetingTimelineEntry, 0, len(items))
+	for _, raw := range items {
+		item, _ := raw.(map[string]interface{})
+		when, ok := parseFlexibleTime(common.GetString(item, "time"))
+		if !ok {
+			when, ok = fallbackTime, fallbackOK
+		}
+		subject := meetingEventUserWithID(common.GetMap(item, "operator"))
+		if subject == "" {
+			subject = "未知用户"
+		}
+		entries = append(entries, newTimelineEntry(when, ok, sequence, group, subject, "结束共享", nil))
+	}
+	return entries
+}
+
+func newTimelineEntry(when time.Time, hasWhen bool, sequence *int, group int, subject, description string, details []string) meetingTimelineEntry {
+	entry := meetingTimelineEntry{
+		when:        when,
+		hasWhen:     hasWhen,
+		sequence:    *sequence,
+		group:       group,
+		subject:     subject,
+		description: description,
+		details:     details,
+	}
+	*sequence = *sequence + 1
+	return entry
+}
+
+func parseFlexibleTime(raw string) (time.Time, bool) {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return time.Time{}, false
+	}
+	if ts, err := strconv.ParseInt(raw, 10, 64); err == nil {
+		switch {
+		case ts > 1_000_000_000_000:
+			return time.UnixMilli(ts), true
+		case ts > 0:
+			return time.Unix(ts, 0), true
+		}
+	}
+	if parsed, err := time.Parse(time.RFC3339, raw); err == nil {
+		return parsed, true
+	}
+	return time.Time{}, false
+}
+
+func renderMeetingEventsPretty(timeline meetingTimeline) string {
+	var b strings.Builder
+	if timeline.topic != "" {
+		fmt.Fprintf(&b, "会议主题：%s\n", escapePrettyText(timeline.topic))
+	}
+	if timeline.hasStart || timeline.hasEnd {
+		fmt.Fprintf(&b, "会议时间：%s\n", escapePrettyText(formatMeetingWindow(timeline.startTime, timeline.hasStart, timeline.endTime, timeline.hasEnd)))
+	}
+	if b.Len() > 0 {
+		b.WriteString("\n")
+	}
+	for _, entry := range timeline.entries {
+		fmt.Fprintf(&b, "[%s] ", formatTimelineOffset(entry.when, entry.hasWhen, timeline.startTime, timeline.hasStart))
+		if entry.subject != "" {
+			if entry.description == "" {
+				fmt.Fprintln(&b, escapePrettyText(entry.subject))
+				for _, detail := range entry.details {
+					fmt.Fprintf(&b, "           %s\n", escapePrettyText(detail))
+				}
+				continue
+			}
+			if needsColon(entry.description) {
+				fmt.Fprintf(&b, "%s: %s\n", escapePrettyText(entry.subject), escapePrettyText(entry.description))
+			} else {
+				fmt.Fprintf(&b, "%s %s\n", escapePrettyText(entry.subject), escapePrettyText(entry.description))
+			}
+			for _, detail := range entry.details {
+				fmt.Fprintf(&b, "           %s\n", escapePrettyText(detail))
+			}
+			continue
+		}
+		fmt.Fprintln(&b, escapePrettyText(entry.description))
+		for _, detail := range entry.details {
+			fmt.Fprintf(&b, "           %s\n", escapePrettyText(detail))
+		}
+	}
+	if b.Len() == 0 {
+		return ""
+	}
+	return b.String()
+}
+
+func escapePrettyText(s string) string {
+	if s == "" {
+		return ""
+	}
+	var b strings.Builder
+	for _, r := range s {
+		switch r {
+		case '\n':
+			b.WriteString(`\n`)
+		case '\r':
+			b.WriteString(`\r`)
+		case '\t':
+			b.WriteString(`\t`)
+		default:
+			if unicode.IsControl(r) {
+				fmt.Fprintf(&b, "\\u%04X", r)
+				continue
+			}
+			b.WriteRune(r)
+		}
+	}
+	return b.String()
+}
+
+func formatMeetingWindow(start time.Time, hasStart bool, end time.Time, hasEnd bool) string {
+	switch {
+	case hasStart && hasEnd:
+		if !end.After(start) {
+			return fmt.Sprintf("%s（进行中）", start.Local().Format("2006-01-02 15:04:05"))
+		}
+		return fmt.Sprintf("%s - %s", start.Local().Format("2006-01-02 15:04:05"), end.Local().Format("2006-01-02 15:04:05"))
+	case hasStart:
+		return start.Local().Format("2006-01-02 15:04:05")
+	case hasEnd:
+		return end.Local().Format("2006-01-02 15:04:05")
+	default:
+		return ""
+	}
+}
+
+func formatTimelineOffset(when time.Time, hasWhen bool, meetingStart time.Time, hasMeetingStart bool) string {
+	if hasWhen && hasMeetingStart {
+		diff := when.Sub(meetingStart)
+		if diff < 0 {
+			diff = 0
+		}
+		totalSeconds := int(diff.Seconds())
+		hours := totalSeconds / 3600
+		minutes := (totalSeconds % 3600) / 60
+		seconds := totalSeconds % 60
+		return fmt.Sprintf("%02d:%02d:%02d", hours, minutes, seconds)
+	}
+	if hasWhen {
+		return when.Local().Format("15:04:05")
+	}
+	return "??:??:??"
+}
+
+func needsColon(description string) bool {
+	switch description {
+	case "发送了消息", "产生了转写":
+		return false
+	default:
+		return !strings.HasPrefix(description, "加入了") &&
+			!strings.HasPrefix(description, "离开了") &&
+			!strings.HasPrefix(description, "被移出") &&
+			!strings.HasPrefix(description, "会议结束") &&
+			!strings.HasPrefix(description, "开始共享") &&
+			!strings.HasPrefix(description, "结束共享")
+	}
+}
+
+func leaveAction(item map[string]interface{}) string {
+	switch int(common.GetFloat(item, "leave_reason")) {
+	case 2:
+		return "因会议结束离开了会议"
+	case 3:
+		return "被移出了会议"
+	default:
+		return "离开了会议"
+	}
+}
+
+func meetingEventUserWithID(user map[string]interface{}) string {
+	if user == nil {
+		return ""
+	}
+	userID := common.GetString(user, "id")
+	userName := common.GetString(user, "user_name")
+	switch {
+	case userName != "" && userID != "":
+		return fmt.Sprintf("%s(%s)", userName, userID)
+	case userName != "":
+		return userName
+	case userID != "":
+		return userID
+	default:
+		return ""
+	}
+}
+
+func meetingEventType(event map[string]interface{}) string {
+	if eventType := common.GetString(event, "event_type"); eventType != "" {
+		return eventType
+	}
+	return common.GetString(common.GetMap(event, "payload"), "activity_event_type")
+}
+
+func meetingEventSummary(event map[string]interface{}) string {
+	payload := common.GetMap(event, "payload")
+	eventType := meetingEventType(event)
+	switch eventType {
+	case "participant_joined":
+		return participantJoinedSummary(payload)
+	case "participant_left":
+		return participantLeftSummary(payload)
+	case "transcript_received":
+		return transcriptReceivedSummary(payload)
+	case "chat_received":
+		return chatReceivedSummary(payload)
+	case "magic_share_started":
+		return magicShareStartedSummary(payload)
+	case "magic_share_ended":
+		return magicShareEndedSummary(payload)
+	default:
+		return fallbackMeetingEventSummary(payload, eventType)
+	}
+}
+
+func participantJoinedSummary(payload map[string]interface{}) string {
+	items := common.GetSlice(payload, "participant_joined_items")
+	switch len(items) {
+	case 0:
+		return "participant joined"
+	case 1:
+		user := common.GetMap(firstSliceMap(payload, "participant_joined_items"), "participant")
+		if label := meetingEventUserLabel(user); label != "" {
+			return fmt.Sprintf("participant %s joined", label)
+		}
+		return "participant joined"
+	default:
+		return fmt.Sprintf("%d participants joined", len(items))
+	}
+}
+
+func participantLeftSummary(payload map[string]interface{}) string {
+	items := common.GetSlice(payload, "participant_left_items")
+	switch len(items) {
+	case 0:
+		return "participant left"
+	case 1:
+		user := common.GetMap(firstSliceMap(payload, "participant_left_items"), "participant")
+		if label := meetingEventUserLabel(user); label != "" {
+			return fmt.Sprintf("participant %s left", label)
+		}
+		return "participant left"
+	default:
+		return fmt.Sprintf("%d participants left", len(items))
+	}
+}
+
+func transcriptReceivedSummary(payload map[string]interface{}) string {
+	items := common.GetSlice(payload, "transcript_received_items")
+	if len(items) > 1 {
+		return fmt.Sprintf("%d transcript items", len(items))
+	}
+	item := firstSliceMap(payload, "transcript_received_items")
+	text := common.GetString(item, "text")
+	speaker := meetingEventUserLabel(common.GetMap(item, "speaker"))
+	switch {
+	case speaker != "" && text != "":
+		return fmt.Sprintf("speaker %s: %s", speaker, text)
+	case speaker != "":
+		return fmt.Sprintf("speaker %s transcript received", speaker)
+	case text != "":
+		return fmt.Sprintf("transcript: %s", text)
+	default:
+		return "transcript received"
+	}
+}
+
+func chatReceivedSummary(payload map[string]interface{}) string {
+	items := common.GetSlice(payload, "chat_received_items")
+	switch len(items) {
+	case 0:
+		return "chat received"
+	case 1:
+		item := firstSliceMap(payload, "chat_received_items")
+		content := common.GetString(item, "content")
+		operator := meetingEventUserDisplayName(common.GetMap(item, "operator"))
+		switch {
+		case operator != "" && content != "":
+			return fmt.Sprintf("%s: %s", operator, content)
+		case operator != "":
+			return fmt.Sprintf("message by %s", operator)
+		case content != "":
+			return fmt.Sprintf("message: %s", content)
+		default:
+			return "chat received"
+		}
+	default:
+		count, operator := summarizeChatOperators(items)
+		switch {
+		case count == 1 && operator != "":
+			return fmt.Sprintf("%d messages by %s", len(items), operator)
+		case count > 1:
+			return fmt.Sprintf("%d messages by %d users", len(items), count)
+		default:
+			return fmt.Sprintf("%d messages", len(items))
+		}
+	}
+}
+
+func magicShareStartedSummary(payload map[string]interface{}) string {
+	items := common.GetSlice(payload, "magic_share_started_items")
+	if len(items) > 1 {
+		return fmt.Sprintf("%d share start events", len(items))
+	}
+	item := firstSliceMap(payload, "magic_share_started_items")
+	shareID := common.GetString(item, "share_id")
+	title := common.GetString(common.GetMap(item, "share_doc"), "title")
+	switch {
+	case shareID != "" && title != "":
+		return fmt.Sprintf("share %s started: %s", shareID, title)
+	case shareID != "":
+		return fmt.Sprintf("share %s started", shareID)
+	case title != "":
+		return fmt.Sprintf("share started: %s", title)
+	default:
+		return "share started"
+	}
+}
+
+func magicShareEndedSummary(payload map[string]interface{}) string {
+	items := common.GetSlice(payload, "magic_share_ended_items")
+	if len(items) > 1 {
+		return fmt.Sprintf("%d share end events", len(items))
+	}
+	item := firstSliceMap(payload, "magic_share_ended_items")
+	if shareID := common.GetString(item, "share_id"); shareID != "" {
+		return fmt.Sprintf("share %s ended", shareID)
+	}
+	return "share ended"
+}
+
+func fallbackMeetingEventSummary(payload map[string]interface{}, eventType string) string {
+	meeting := common.GetMap(payload, "meeting")
+	if topic := common.GetString(meeting, "topic"); topic != "" {
+		if eventType != "" {
+			return fmt.Sprintf("%s: %s", eventType, topic)
+		}
+		return topic
+	}
+	if eventType != "" {
+		return eventType
+	}
+	return "meeting event"
+}
+
+func firstSliceMap(payload map[string]interface{}, key string) map[string]interface{} {
+	items := common.GetSlice(payload, key)
+	if len(items) == 0 {
+		return nil
+	}
+	first, _ := items[0].(map[string]interface{})
+	return first
+}
+
+func meetingEventUserLabel(user map[string]interface{}) string {
+	if user == nil {
+		return ""
+	}
+	userID := common.GetString(user, "id")
+	userName := common.GetString(user, "user_name")
+	switch {
+	case userID != "" && userName != "":
+		return fmt.Sprintf("%s (%s)", userID, userName)
+	case userID != "":
+		return userID
+	case userName != "":
+		return userName
+	default:
+		return ""
+	}
+}
+
+func meetingEventUserDisplayName(user map[string]interface{}) string {
+	if user == nil {
+		return ""
+	}
+	if userName := common.GetString(user, "user_name"); userName != "" {
+		return userName
+	}
+	return common.GetString(user, "id")
+}
+
+func chatMessageTypeLabel(item map[string]interface{}) string {
+	code := int(common.GetFloat(item, "message_type"))
+	switch code {
+	case 1:
+		return "text"
+	case 2:
+		return "system"
+	case 3:
+		return "reaction"
+	case 4:
+		return "encrypted"
+	default:
+		return "unknown"
+	}
+}
+
+func summarizeChatOperators(items []interface{}) (int, string) {
+	seen := make(map[string]struct{}, len(items))
+	for _, raw := range items {
+		item, _ := raw.(map[string]interface{})
+		if item == nil {
+			continue
+		}
+		operator := meetingEventUserDisplayName(common.GetMap(item, "operator"))
+		if operator == "" {
+			continue
+		}
+		seen[operator] = struct{}{}
+	}
+	if len(seen) != 1 {
+		return len(seen), ""
+	}
+	for operator := range seen {
+		return 1, operator
+	}
+	return 0, ""
+}

shortcuts/vc/vc_meeting_events_test.go

@@ -0,0 +1,579 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package vc
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+func newMeetingEventsRuntime() *common.RuntimeContext {
+	cmd := &cobra.Command{Use: "test"}
+	cmd.Flags().String("meeting-id", "", "")
+	cmd.Flags().String("start", "", "")
+	cmd.Flags().String("end", "", "")
+	cmd.Flags().String("page-token", "", "")
+	cmd.Flags().String("page-size", "", "")
+	cmd.Flags().Bool("page-all", false, "")
+	return common.TestNewRuntimeContext(cmd, defaultConfig())
+}
+
+func meetingEventsStub(events []interface{}, hasMore bool, pageToken string) *httpmock.Stub {
+	return &httpmock.Stub{
+		Method: "GET",
+		URL:    vcMeetingEventsAPIPath,
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"total":      len(events),
+				"has_more":   hasMore,
+				"page_token": pageToken,
+				"events":     events,
+			},
+		},
+	}
+}
+
+func participantJoinedEvent() map[string]interface{} {
+	return map[string]interface{}{
+		"event_id":   "event-1",
+		"event_type": "participant_joined",
+		"event_time": "2026-04-17T08:00:00Z",
+		"payload": map[string]interface{}{
+			"activity_event_type": "participant_joined",
+			"meeting": map[string]interface{}{
+				"id":         "7628568141510692381",
+				"topic":      "项目例会",
+				"meeting_no": "724939760",
+				"start_time": "1776407700",
+				"end_time":   "1776411300",
+			},
+			"participant_joined_items": []interface{}{
+				map[string]interface{}{
+					"participant": map[string]interface{}{
+						"id":        "bot_001",
+						"user_name": "Demo Bot",
+					},
+					"join_time": "2026-04-17T08:00:00Z",
+				},
+			},
+		},
+	}
+}
+
+func participantJoinedEventOngoing() map[string]interface{} {
+	event := participantJoinedEvent()
+	payload := common.GetMap(event, "payload")
+	meeting := common.GetMap(payload, "meeting")
+	meeting["start_time"] = "1776410100"
+	meeting["end_time"] = "1776410100"
+	return event
+}
+
+func chatReceivedEvent() map[string]interface{} {
+	return map[string]interface{}{
+		"event_id":   "event-2",
+		"event_type": "chat_received",
+		"event_time": "2026-04-17T08:05:00Z",
+		"payload": map[string]interface{}{
+			"activity_event_type": "chat_received",
+			"meeting": map[string]interface{}{
+				"id":         "7628568141510692381",
+				"topic":      "项目例会",
+				"meeting_no": "724939760",
+				"start_time": "1776407700",
+				"end_time":   "1776411300",
+			},
+			"participant_joined_items":  []interface{}{},
+			"participant_left_items":    []interface{}{},
+			"transcript_received_items": []interface{}{},
+			"magic_share_started_items": []interface{}{},
+			"magic_share_ended_items":   []interface{}{},
+			"chat_received_items": []interface{}{
+				map[string]interface{}{
+					"content":      "hello",
+					"message_type": 3,
+					"operator": map[string]interface{}{
+						"id":        "u1",
+						"user_name": "Alice",
+					},
+				},
+			},
+		},
+	}
+}
+
+func multiChatReceivedEvent() map[string]interface{} {
+	return map[string]interface{}{
+		"event_id":   "event-3",
+		"event_type": "chat_received",
+		"event_time": "2026-04-17T08:06:00Z",
+		"payload": map[string]interface{}{
+			"activity_event_type": "chat_received",
+			"meeting": map[string]interface{}{
+				"id":         "7628568141510692381",
+				"topic":      "项目例会",
+				"meeting_no": "724939760",
+				"start_time": "1776407700",
+				"end_time":   "1776411300",
+			},
+			"chat_received_items": []interface{}{
+				map[string]interface{}{
+					"content":      "第一条\n第二行",
+					"message_type": 3,
+					"send_time":    "1776408061000",
+					"operator": map[string]interface{}{
+						"id":        "u1",
+						"user_name": "Alice",
+					},
+				},
+				map[string]interface{}{
+					"content":      "第二条",
+					"message_type": 3,
+					"send_time":    "1776408062000",
+					"operator": map[string]interface{}{
+						"id":        "u1",
+						"user_name": "Alice",
+					},
+				},
+			},
+		},
+	}
+}
+
+func magicShareStartedEvent() map[string]interface{} {
+	return map[string]interface{}{
+		"event_id":   "event-4",
+		"event_type": "magic_share_started",
+		"event_time": "2026-04-17T08:07:00Z",
+		"payload": map[string]interface{}{
+			"activity_event_type": "magic_share_started",
+			"meeting": map[string]interface{}{
+				"id":         "7628568141510692381",
+				"topic":      "项目例会",
+				"meeting_no": "724939760",
+				"start_time": "1776407700",
+				"end_time":   "1776411300",
+			},
+			"magic_share_started_items": []interface{}{
+				map[string]interface{}{
+					"time": "1776408123000",
+					"operator": map[string]interface{}{
+						"id":        "u2",
+						"user_name": "Bob",
+					},
+					"share_doc": map[string]interface{}{
+						"title": "共享文档",
+						"url":   "https://example.com/doc",
+					},
+				},
+			},
+		},
+	}
+}
+
+func TestChatReceivedSummary_MultipleItems(t *testing.T) {
+	payload := map[string]interface{}{
+		"chat_received_items": []interface{}{
+			map[string]interface{}{"content": "hello"},
+			map[string]interface{}{"content": "world"},
+		},
+	}
+
+	got := chatReceivedSummary(payload)
+	if got != "2 messages" {
+		t.Fatalf("chatReceivedSummary() = %q, want %q", got, "2 messages")
+	}
+}
+
+func TestChatReceivedSummary_MultipleItemsSameOperator(t *testing.T) {
+	payload := map[string]interface{}{
+		"chat_received_items": []interface{}{
+			map[string]interface{}{"content": "hello", "operator": map[string]interface{}{"id": "u1", "user_name": "Alice"}},
+			map[string]interface{}{"content": "world", "operator": map[string]interface{}{"id": "u1", "user_name": "Alice"}},
+		},
+	}
+
+	got := chatReceivedSummary(payload)
+	if got != "2 messages by Alice" {
+		t.Fatalf("chatReceivedSummary() = %q, want %q", got, "2 messages by Alice")
+	}
+}
+
+func TestChatReceivedSummary_MultipleItemsMultipleOperators(t *testing.T) {
+	payload := map[string]interface{}{
+		"chat_received_items": []interface{}{
+			map[string]interface{}{"content": "hello", "operator": map[string]interface{}{"id": "u1", "user_name": "Alice"}},
+			map[string]interface{}{"content": "world", "operator": map[string]interface{}{"id": "u2", "user_name": "Bob"}},
+			map[string]interface{}{"content": "again", "operator": map[string]interface{}{"id": "u3", "user_name": "Carol"}},
+		},
+	}
+
+	got := chatReceivedSummary(payload)
+	if got != "3 messages by 3 users" {
+		t.Fatalf("chatReceivedSummary() = %q, want %q", got, "3 messages by 3 users")
+	}
+}
+
+func TestParticipantJoinedSummary_MultipleItems(t *testing.T) {
+	payload := map[string]interface{}{
+		"participant_joined_items": []interface{}{
+			map[string]interface{}{"participant": map[string]interface{}{"id": "u1", "user_name": "User 1"}},
+			map[string]interface{}{"participant": map[string]interface{}{"id": "u2", "user_name": "User 2"}},
+		},
+	}
+
+	got := participantJoinedSummary(payload)
+	if got != "2 participants joined" {
+		t.Fatalf("participantJoinedSummary() = %q, want %q", got, "2 participants joined")
+	}
+}
+
+func TestMeetingEvents_Validation_InvalidMeetingID(t *testing.T) {
+	runtime := newMeetingEventsRuntime()
+	_ = runtime.Cmd.Flags().Set("meeting-id", "not-a-number")
+
+	err := VCMeetingEvents.Validate(context.Background(), runtime)
+	if err == nil {
+		t.Fatal("expected validation error for invalid meeting ID")
+	}
+	if !strings.Contains(err.Error(), "positive integer") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestMeetingEvents_Validation_InvalidTimeRange(t *testing.T) {
+	runtime := newMeetingEventsRuntime()
+	_ = runtime.Cmd.Flags().Set("meeting-id", "7628568141510692381")
+	_ = runtime.Cmd.Flags().Set("start", "200")
+	_ = runtime.Cmd.Flags().Set("end", "100")
+
+	err := VCMeetingEvents.Validate(context.Background(), runtime)
+	if err == nil {
+		t.Fatal("expected validation error for invalid time range")
+	}
+	if !strings.Contains(err.Error(), "after --end") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestMeetingEvents_Validation_PageSizeBelowMinDoesNotError(t *testing.T) {
+	runtime := newMeetingEventsRuntime()
+	_ = runtime.Cmd.Flags().Set("meeting-id", "7628568141510692381")
+	_ = runtime.Cmd.Flags().Set("page-size", "10")
+
+	err := VCMeetingEvents.Validate(context.Background(), runtime)
+	if err != nil {
+		t.Fatalf("expected no validation error for page-size clamp, got: %v", err)
+	}
+}
+
+func TestMeetingEvents_Validation_PageAllIgnoresInvalidPageSize(t *testing.T) {
+	runtime := newMeetingEventsRuntime()
+	_ = runtime.Cmd.Flags().Set("meeting-id", "7628568141510692381")
+	_ = runtime.Cmd.Flags().Set("page-all", "true")
+	_ = runtime.Cmd.Flags().Set("page-size", "10")
+
+	err := VCMeetingEvents.Validate(context.Background(), runtime)
+	if err != nil {
+		t.Fatalf("expected no validation error when page-all ignores page-size, got: %v", err)
+	}
+}
+
+func TestBuildMeetingEventsParams(t *testing.T) {
+	runtime := newMeetingEventsRuntime()
+	_ = runtime.Cmd.Flags().Set("meeting-id", "7628568141510692381")
+	_ = runtime.Cmd.Flags().Set("page-size", "40")
+	_ = runtime.Cmd.Flags().Set("page-token", "1710000000000000000")
+
+	params, err := buildMeetingEventsParams(runtime, "1710000000", "1710003600")
+	if err != nil {
+		t.Fatalf("buildMeetingEventsParams() error = %v", err)
+	}
+	if got := params["meeting_id"][0]; got != "7628568141510692381" {
+		t.Fatalf("meeting_id = %q, want %q", got, "7628568141510692381")
+	}
+	if got := params["page_size"][0]; got != "40" {
+		t.Fatalf("page_size = %q, want %q", got, "40")
+	}
+	if got := params["page_token"][0]; got != "1710000000000000000" {
+		t.Fatalf("page_token = %q, want %q", got, "1710000000000000000")
+	}
+	if got := params["start_time"][0]; got != "1710000000" {
+		t.Fatalf("start_time = %q, want %q", got, "1710000000")
+	}
+	if got := params["end_time"][0]; got != "1710003600" {
+		t.Fatalf("end_time = %q, want %q", got, "1710003600")
+	}
+}
+
+func TestBuildMeetingEventsParams_PageSizeBelowMinClampsToMin(t *testing.T) {
+	runtime := newMeetingEventsRuntime()
+	_ = runtime.Cmd.Flags().Set("meeting-id", "7628568141510692381")
+	_ = runtime.Cmd.Flags().Set("page-size", "10")
+
+	params, err := buildMeetingEventsParams(runtime, "", "")
+	if err != nil {
+		t.Fatalf("buildMeetingEventsParams() error = %v", err)
+	}
+	if got := params["page_size"][0]; got != "20" {
+		t.Fatalf("page_size = %q, want %q when below min", got, "20")
+	}
+}
+
+func TestBuildMeetingEventsParams_PageSizeAboveMaxClampsToMax(t *testing.T) {
+	runtime := newMeetingEventsRuntime()
+	_ = runtime.Cmd.Flags().Set("meeting-id", "7628568141510692381")
+	_ = runtime.Cmd.Flags().Set("page-size", "999")
+
+	params, err := buildMeetingEventsParams(runtime, "", "")
+	if err != nil {
+		t.Fatalf("buildMeetingEventsParams() error = %v", err)
+	}
+	if got := params["page_size"][0]; got != "100" {
+		t.Fatalf("page_size = %q, want %q when above max", got, "100")
+	}
+}
+
+func TestBuildMeetingEventsParams_PageAllUsesMaxPageSize(t *testing.T) {
+	runtime := newMeetingEventsRuntime()
+	_ = runtime.Cmd.Flags().Set("meeting-id", "7628568141510692381")
+	_ = runtime.Cmd.Flags().Set("page-all", "true")
+	_ = runtime.Cmd.Flags().Set("page-size", "50")
+
+	params, err := buildMeetingEventsParams(runtime, "", "")
+	if err != nil {
+		t.Fatalf("buildMeetingEventsParams() error = %v", err)
+	}
+	if got := params["page_size"][0]; got != "100" {
+		t.Fatalf("page_size = %q, want %q when page-all is set", got, "100")
+	}
+}
+
+func TestMeetingEvents_DryRun(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	err := mountAndRun(t, VCMeetingEvents, []string{
+		"+meeting-events",
+		"--meeting-id", "7628568141510692381",
+		"--page-token", "1710000000000000000",
+		"--page-size", "40",
+		"--start", "1710000000",
+		"--end", "1710003600",
+		"--dry-run",
+		"--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	out := stdout.String()
+	for _, want := range []string{
+		vcMeetingEventsAPIPath,
+		`"meeting_id": "7628568141510692381"`,
+		`"page_token": "1710000000000000000"`,
+		`"page_size": "40"`,
+		`"start_time": "1710000000"`,
+		`"end_time": "1710003600"`,
+	} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("dry-run output missing %q: %s", want, out)
+		}
+	}
+}
+
+func TestMeetingEvents_DryRun_PageAllUsesMaxLimit(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	err := mountAndRun(t, VCMeetingEvents, []string{
+		"+meeting-events",
+		"--meeting-id", "7628568141510692381",
+		"--page-all",
+		"--dry-run",
+		"--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if !strings.Contains(stdout.String(), "Auto-paginates through all available pages") {
+		t.Fatalf("dry-run output missing auto-pagination description: %s", stdout.String())
+	}
+}
+
+func TestMeetingEvents_ExecuteJSON_PageAll(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(meetingEventsStub([]interface{}{participantJoinedEvent()}, true, "pt_2"))
+	reg.Register(meetingEventsStub([]interface{}{participantJoinedEvent()}, false, ""))
+
+	err := mountAndRun(t, VCMeetingEvents, []string{
+		"+meeting-events",
+		"--meeting-id", "7628568141510692381",
+		"--format", "json",
+		"--page-all",
+		"--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	reg.Verify(t)
+
+	out := strings.ReplaceAll(stdout.String(), " ", "")
+	out = strings.ReplaceAll(out, "\n", "")
+	if count := strings.Count(out, `"event_type":"participant_joined"`); count != 2 {
+		t.Fatalf("expected 2 aggregated events, got %d: %s", count, stdout.String())
+	}
+	if !strings.Contains(out, `"has_more":false`) {
+		t.Fatalf("expected final has_more=false: %s", stdout.String())
+	}
+}
+
+func TestMeetingEvents_ExecuteJSON(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(meetingEventsStub([]interface{}{participantJoinedEvent()}, true, "1710000000000000000"))
+
+	err := mountAndRun(t, VCMeetingEvents, []string{
+		"+meeting-events",
+		"--meeting-id", "7628568141510692381",
+		"--format", "json",
+		"--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	reg.Verify(t)
+
+	out := strings.ReplaceAll(stdout.String(), " ", "")
+	out = strings.ReplaceAll(out, "\n", "")
+	for _, want := range []string{
+		`"event_type":"participant_joined"`,
+		`"has_more":true`,
+		`"page_token":"1710000000000000000"`,
+		`"events":[`,
+	} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("json output missing %q: %s", want, stdout.String())
+		}
+	}
+}
+
+func TestMeetingEvents_ExecuteJSON_PrunesEmptySlices(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(meetingEventsStub([]interface{}{chatReceivedEvent()}, false, ""))
+
+	err := mountAndRun(t, VCMeetingEvents, []string{
+		"+meeting-events",
+		"--meeting-id", "7628568141510692381",
+		"--format", "json",
+		"--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	reg.Verify(t)
+
+	out := stdout.String()
+	for _, unwanted := range []string{
+		`"participant_joined_items": []`,
+		`"participant_left_items": []`,
+		`"transcript_received_items": []`,
+		`"magic_share_started_items": []`,
+		`"magic_share_ended_items": []`,
+	} {
+		if strings.Contains(out, unwanted) {
+			t.Fatalf("json output should not contain %q: %s", unwanted, out)
+		}
+	}
+	if !strings.Contains(out, `"message_type": 3`) {
+		t.Fatalf("json output should keep numeric fields: %s", out)
+	}
+}
+
+func TestMeetingEvents_ExecutePretty(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(meetingEventsStub([]interface{}{participantJoinedEventOngoing(), multiChatReceivedEvent(), magicShareStartedEvent()}, true, "1710000000000000000"))
+
+	err := mountAndRun(t, VCMeetingEvents, []string{
+		"+meeting-events",
+		"--meeting-id", "7628568141510692381",
+		"--format", "pretty",
+		"--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	reg.Verify(t)
+
+	out := stdout.String()
+	for _, want := range []string{
+		"会议主题：项目例会",
+		"会议时间：2026-04-17 15:15:00（进行中）",
+		"Demo Bot(bot_001) 加入了会议",
+		"Alice(u1): [reaction] 第一条\\n第二行",
+		"Alice(u1): [reaction] 第二条",
+		"Bob(u2) 开始共享「共享文档」",
+		"URL: https://example.com/doc",
+		"page_token: 1710000000000000000",
+	} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("pretty output missing %q: %s", want, out)
+		}
+	}
+	if strings.Contains(out, "第二条\n\n[") {
+		t.Fatalf("pretty output should not insert blank lines between event entries: %s", out)
+	}
+	if !strings.Contains(out, "第二条\n[") {
+		t.Fatalf("pretty output should keep event entries contiguous: %s", out)
+	}
+}
+
+func TestMeetingEvents_ExecutePretty_PrintsPageTokenWithoutHasMore(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(meetingEventsStub([]interface{}{participantJoinedEventOngoing()}, false, "pt_last"))
+
+	err := mountAndRun(t, VCMeetingEvents, []string{
+		"+meeting-events",
+		"--meeting-id", "7628568141510692381",
+		"--format", "pretty",
+		"--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	reg.Verify(t)
+
+	out := stdout.String()
+	if !strings.Contains(out, "page_token: pt_last") {
+		t.Fatalf("pretty output should print page_token even when has_more is false: %s", out)
+	}
+	if strings.Contains(out, "more available") {
+		t.Fatalf("pretty output should not print more-available hint when has_more is false: %s", out)
+	}
+}
+
+func TestMeetingEvents_ExecuteEmpty(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(meetingEventsStub(nil, false, ""))
+
+	err := mountAndRun(t, VCMeetingEvents, []string{
+		"+meeting-events",
+		"--meeting-id", "7628568141510692381",
+		"--format", "pretty",
+		"--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	reg.Verify(t)
+
+	if !strings.Contains(stdout.String(), "No meeting events.") {
+		t.Fatalf("unexpected output: %s", stdout.String())
+	}
+}

shortcuts/vc/vc_meeting_join.go

@@ -0,0 +1,94 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package vc
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"regexp"
+	"strings"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+var meetingNumberRe = regexp.MustCompile(`^\d{9}$`)
+
+// validMeetingNumber checks whether s is a valid 9-digit meeting number.
+func validMeetingNumber(s string) bool {
+	return meetingNumberRe.MatchString(s)
+}
+
+// VCMeetingJoin joins a meeting by meeting number via /vc/v1/bots/join.
+var VCMeetingJoin = common.Shortcut{
+	Service:     "vc",
+	Command:     "+meeting-join",
+	Description: "Join a meeting by meeting number (bot join)",
+	Risk:        "write",
+	Scopes:      []string{"vc:meeting.bot.join:write"},
+	AuthTypes:   []string{"user"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "meeting-number", Required: true, Desc: "meeting number to join"},
+		{Name: "password", Desc: "meeting password (if required)"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		mn := strings.TrimSpace(runtime.Str("meeting-number"))
+		if !validMeetingNumber(mn) {
+			return common.FlagErrorf("--meeting-number must be exactly 9 digits, got %q", mn)
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		body := buildMeetingJoinBody(runtime)
+		return common.NewDryRunAPI().
+			POST("/open-apis/vc/v1/bots/join").
+			Body(body)
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		body := buildMeetingJoinBody(runtime)
+		data, err := runtime.DoAPIJSON("POST", "/open-apis/vc/v1/bots/join", nil, body)
+		if err != nil {
+			return err
+		}
+		if data == nil {
+			data = map[string]interface{}{}
+		}
+		runtime.OutFormat(data, nil, func(w io.Writer) {
+			meeting, _ := data["meeting"].(map[string]interface{})
+			if meeting == nil {
+				fmt.Fprintln(w, "Joined meeting (no meeting info returned).")
+				return
+			}
+			fmt.Fprintf(w, "Joined meeting successfully.\n")
+			if id := common.GetString(meeting, "id"); id != "" {
+				fmt.Fprintf(w, "  Meeting ID:  %s\n", id)
+			}
+			if no := common.GetString(meeting, "meeting_no"); no != "" {
+				fmt.Fprintf(w, "  Meeting No:  %s\n", no)
+			}
+			if topic := common.GetString(meeting, "topic"); topic != "" {
+				fmt.Fprintf(w, "  Topic:       %s\n", topic)
+			}
+			if startTime := common.GetString(meeting, "start_time"); startTime != "" {
+				fmt.Fprintf(w, "  Start Time:  %s\n", startTime)
+			}
+		})
+		return nil
+	},
+}
+
+func buildMeetingJoinBody(runtime *common.RuntimeContext) map[string]interface{} {
+	meetingNo := strings.TrimSpace(runtime.Str("meeting-number"))
+	body := map[string]interface{}{
+		"join_type": 1,
+		"join_identify": map[string]interface{}{
+			"meeting_no": meetingNo,
+		},
+	}
+	if pw := strings.TrimSpace(runtime.Str("password")); pw != "" {
+		body["password"] = pw
+	}
+	return body
+}

shortcuts/vc/vc_meeting_leave.go

@@ -0,0 +1,57 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package vc
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// VCMeetingLeave leaves a meeting via /vc/v1/bots/leave.
+var VCMeetingLeave = common.Shortcut{
+	Service:     "vc",
+	Command:     "+meeting-leave",
+	Description: "Leave a meeting by meeting ID",
+	Risk:        "write",
+	Scopes:      []string{"vc:meeting.bot.join:write"},
+	AuthTypes:   []string{"user"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "meeting-id", Required: true, Desc: "meeting ID to leave"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if strings.TrimSpace(runtime.Str("meeting-id")) == "" {
+			return common.FlagErrorf("--meeting-id is required")
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		return common.NewDryRunAPI().
+			POST("/open-apis/vc/v1/bots/leave").
+			Body(map[string]interface{}{
+				"meeting_id": strings.TrimSpace(runtime.Str("meeting-id")),
+			})
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		meetingID := strings.TrimSpace(runtime.Str("meeting-id"))
+		body := map[string]interface{}{
+			"meeting_id": meetingID,
+		}
+		data, err := runtime.DoAPIJSON("POST", "/open-apis/vc/v1/bots/leave", nil, body)
+		if err != nil {
+			return err
+		}
+		if data == nil {
+			data = map[string]interface{}{}
+		}
+		runtime.OutFormat(data, nil, func(w io.Writer) {
+			fmt.Fprintf(w, "Left meeting %s successfully.\n", meetingID)
+		})
+		return nil
+	},
+}

shortcuts/vc/vc_meeting_test.go

@@ -0,0 +1,536 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package vc
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// ---------------------------------------------------------------------------
+// Unit tests: pure functions
+// ---------------------------------------------------------------------------
+
+func TestValidMeetingNumber(t *testing.T) {
+	tests := []struct {
+		name string
+		in   string
+		want bool
+	}{
+		{"9 digits", "123456789", true},
+		{"9 digits leading zero", "012345678", true},
+		{"empty", "", false},
+		{"8 digits", "12345678", false},
+		{"10 digits", "1234567890", false},
+		{"with space", "12345 678", false},
+		{"letters mixed", "12345678a", false},
+		{"pure letters", "abcdefghi", false},
+		{"with dash", "123-456-789", false},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := validMeetingNumber(tt.in); got != tt.want {
+				t.Errorf("validMeetingNumber(%q) = %v, want %v", tt.in, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestBuildMeetingJoinBody_WithoutPassword(t *testing.T) {
+	cmd := &cobra.Command{Use: "test"}
+	cmd.Flags().String("meeting-number", "", "")
+	cmd.Flags().String("password", "", "")
+	_ = cmd.Flags().Set("meeting-number", "123456789")
+
+	runtime := common.TestNewRuntimeContext(cmd, defaultConfig())
+	body := buildMeetingJoinBody(runtime)
+
+	if body["join_type"] != 1 {
+		t.Errorf("join_type = %v, want 1", body["join_type"])
+	}
+	ji, ok := body["join_identify"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("join_identify missing or wrong type: %v", body["join_identify"])
+	}
+	if ji["meeting_no"] != "123456789" {
+		t.Errorf("meeting_no = %v, want 123456789", ji["meeting_no"])
+	}
+	if _, exists := body["password"]; exists {
+		t.Errorf("password should be omitted when empty, got %v", body["password"])
+	}
+}
+
+func TestBuildMeetingJoinBody_WithPassword(t *testing.T) {
+	cmd := &cobra.Command{Use: "test"}
+	cmd.Flags().String("meeting-number", "", "")
+	cmd.Flags().String("password", "", "")
+	_ = cmd.Flags().Set("meeting-number", "123456789")
+	_ = cmd.Flags().Set("password", "secret")
+
+	runtime := common.TestNewRuntimeContext(cmd, defaultConfig())
+	body := buildMeetingJoinBody(runtime)
+
+	if body["password"] != "secret" {
+		t.Errorf("password = %v, want secret", body["password"])
+	}
+}
+
+func TestBuildMeetingJoinBody_TrimsWhitespace(t *testing.T) {
+	cmd := &cobra.Command{Use: "test"}
+	cmd.Flags().String("meeting-number", "", "")
+	cmd.Flags().String("password", "", "")
+	_ = cmd.Flags().Set("meeting-number", "  123456789  ")
+	_ = cmd.Flags().Set("password", "  pw  ")
+
+	runtime := common.TestNewRuntimeContext(cmd, defaultConfig())
+	body := buildMeetingJoinBody(runtime)
+
+	ji, _ := body["join_identify"].(map[string]interface{})
+	if ji["meeting_no"] != "123456789" {
+		t.Errorf("meeting_no should be trimmed, got %q", ji["meeting_no"])
+	}
+	if body["password"] != "pw" {
+		t.Errorf("password should be trimmed, got %q", body["password"])
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Validate tests: VCMeetingJoin
+// ---------------------------------------------------------------------------
+
+func TestMeetingJoin_Validate_MissingNumber(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	// cobra MarkFlagRequired should reject missing --meeting-number
+	err := mountAndRun(t, VCMeetingJoin, []string{"+meeting-join", "--as", "user"}, f, nil)
+	if err == nil {
+		t.Fatal("expected error when --meeting-number is missing")
+	}
+	if !strings.Contains(err.Error(), "meeting-number") {
+		t.Errorf("error should mention meeting-number, got: %v", err)
+	}
+}
+
+func TestMeetingJoin_Validate_InvalidFormat(t *testing.T) {
+	tests := []struct {
+		name string
+		num  string
+	}{
+		{"too short", "12345678"},
+		{"too long", "1234567890"},
+		{"with letters", "12345abcd"},
+		{"empty after trim", "   "},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cmd := &cobra.Command{Use: "test"}
+			cmd.Flags().String("meeting-number", "", "")
+			cmd.Flags().String("password", "", "")
+			_ = cmd.Flags().Set("meeting-number", tt.num)
+
+			runtime := common.TestNewRuntimeContext(cmd, defaultConfig())
+			err := VCMeetingJoin.Validate(context.Background(), runtime)
+			if err == nil {
+				t.Fatalf("expected validation error for %q", tt.num)
+			}
+			if !strings.Contains(err.Error(), "9 digits") {
+				t.Errorf("error should mention '9 digits', got: %v", err)
+			}
+		})
+	}
+}
+
+func TestMeetingJoin_Validate_Valid(t *testing.T) {
+	cmd := &cobra.Command{Use: "test"}
+	cmd.Flags().String("meeting-number", "", "")
+	cmd.Flags().String("password", "", "")
+	_ = cmd.Flags().Set("meeting-number", "123456789")
+
+	runtime := common.TestNewRuntimeContext(cmd, defaultConfig())
+	if err := VCMeetingJoin.Validate(context.Background(), runtime); err != nil {
+		t.Errorf("unexpected validation error: %v", err)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// DryRun tests: VCMeetingJoin
+// ---------------------------------------------------------------------------
+
+func TestMeetingJoin_DryRun(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	err := mountAndRun(t, VCMeetingJoin, []string{
+		"+meeting-join", "--meeting-number", "123456789", "--password", "pw123",
+		"--dry-run", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	if !strings.Contains(out, "/open-apis/vc/v1/bots/join") {
+		t.Errorf("dry-run should include API path, got: %s", out)
+	}
+	if !strings.Contains(out, "123456789") {
+		t.Errorf("dry-run should include meeting number, got: %s", out)
+	}
+	if !strings.Contains(out, "pw123") {
+		t.Errorf("dry-run should include password, got: %s", out)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Execute tests: VCMeetingJoin
+// ---------------------------------------------------------------------------
+
+func TestMeetingJoin_Execute_Success(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	stub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/vc/v1/bots/join",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"meeting": map[string]interface{}{
+					"id":         "69999999",
+					"meeting_no": "123456789",
+					"topic":      "Weekly Sync",
+					"start_time": "1700000000",
+				},
+			},
+		},
+	}
+	reg.Register(stub)
+
+	err := mountAndRun(t, VCMeetingJoin, []string{
+		"+meeting-join", "--meeting-number", "123456789",
+		"--format", "json", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	// verify captured request body
+	if len(stub.CapturedBody) == 0 {
+		t.Fatal("expected request body to be captured")
+	}
+	var req map[string]interface{}
+	if err := json.Unmarshal(stub.CapturedBody, &req); err != nil {
+		t.Fatalf("failed to parse request body: %v", err)
+	}
+	if req["join_type"].(float64) != 1 {
+		t.Errorf("join_type = %v, want 1", req["join_type"])
+	}
+	ji, _ := req["join_identify"].(map[string]interface{})
+	if ji["meeting_no"] != "123456789" {
+		t.Errorf("meeting_no = %v, want 123456789", ji["meeting_no"])
+	}
+	if _, exists := ji["password"]; exists {
+		t.Errorf("password should be omitted when not provided, got %v", ji["password"])
+	}
+
+	// verify response envelope carries meeting info under data.meeting
+	var resp map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &resp); err != nil {
+		t.Fatalf("failed to parse stdout: %v", err)
+	}
+	data, _ := resp["data"].(map[string]any)
+	meeting, _ := data["meeting"].(map[string]any)
+	if meeting["id"] != "69999999" {
+		t.Errorf("meeting.id = %v, want 69999999 (envelope: %s)", meeting["id"], stdout.String())
+	}
+}
+
+func TestMeetingJoin_Execute_WithPassword_CapturesBody(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	stub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/vc/v1/bots/join",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{},
+		},
+	}
+	reg.Register(stub)
+
+	err := mountAndRun(t, VCMeetingJoin, []string{
+		"+meeting-join", "--meeting-number", "987654321", "--password", "s3cret",
+		"--format", "json", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var req map[string]interface{}
+	if err := json.Unmarshal(stub.CapturedBody, &req); err != nil {
+		t.Fatalf("failed to parse request body: %v", err)
+	}
+	ji, _ := req["join_identify"].(map[string]interface{})
+	if req["password"] != "s3cret" {
+		t.Errorf("password = %v, want s3cret", req["password"])
+	}
+	if ji["meeting_no"] != "987654321" {
+		t.Errorf("meeting_no = %v, want 987654321", ji["meeting_no"])
+	}
+}
+
+func TestMeetingJoin_Execute_PrettyOutput(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/vc/v1/bots/join",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"meeting": map[string]interface{}{
+					"id":         "69999999",
+					"meeting_no": "123456789",
+					"topic":      "Weekly Sync",
+					"start_time": "1700000000",
+				},
+			},
+		},
+	})
+
+	err := mountAndRun(t, VCMeetingJoin, []string{
+		"+meeting-join", "--meeting-number", "123456789",
+		"--format", "pretty", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	for _, want := range []string{"Joined meeting successfully", "69999999", "123456789", "Weekly Sync", "1700000000"} {
+		if !strings.Contains(out, want) {
+			t.Errorf("pretty output missing %q, got: %s", want, out)
+		}
+	}
+}
+
+func TestMeetingJoin_Execute_PrettyOutput_NoMeetingInfo(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/vc/v1/bots/join",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{},
+		},
+	})
+
+	err := mountAndRun(t, VCMeetingJoin, []string{
+		"+meeting-join", "--meeting-number", "123456789",
+		"--format", "pretty", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !strings.Contains(stdout.String(), "no meeting info returned") {
+		t.Errorf("pretty output should fall back to 'no meeting info' notice, got: %s", stdout.String())
+	}
+}
+
+func TestMeetingLeave_Execute_PrettyOutput(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/vc/v1/bots/leave",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{},
+		},
+	})
+
+	err := mountAndRun(t, VCMeetingLeave, []string{
+		"+meeting-leave", "--meeting-id", "69999999",
+		"--format", "pretty", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	if !strings.Contains(out, "Left meeting 69999999 successfully") {
+		t.Errorf("pretty output should confirm leave, got: %s", out)
+	}
+}
+
+func TestMeetingJoin_Execute_APIError(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/vc/v1/bots/join",
+		Body:   map[string]interface{}{"code": 190001, "msg": "invalid meeting number"},
+	})
+
+	err := mountAndRun(t, VCMeetingJoin, []string{
+		"+meeting-join", "--meeting-number", "123456789",
+		"--as", "user",
+	}, f, &bytes.Buffer{})
+	if err == nil {
+		t.Fatal("expected error for API failure")
+	}
+	if !strings.Contains(err.Error(), "invalid meeting number") {
+		t.Errorf("error should surface API message, got: %v", err)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Validate tests: VCMeetingLeave
+// ---------------------------------------------------------------------------
+
+func TestMeetingLeave_Validate_MissingID(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	err := mountAndRun(t, VCMeetingLeave, []string{"+meeting-leave", "--as", "user"}, f, nil)
+	if err == nil {
+		t.Fatal("expected error when --meeting-id is missing")
+	}
+	if !strings.Contains(err.Error(), "meeting-id") {
+		t.Errorf("error should mention meeting-id, got: %v", err)
+	}
+}
+
+func TestMeetingLeave_Validate_WhitespaceOnly(t *testing.T) {
+	cmd := &cobra.Command{Use: "test"}
+	cmd.Flags().String("meeting-id", "", "")
+	_ = cmd.Flags().Set("meeting-id", "   ")
+
+	runtime := common.TestNewRuntimeContext(cmd, defaultConfig())
+	err := VCMeetingLeave.Validate(context.Background(), runtime)
+	if err == nil {
+		t.Fatal("expected error for whitespace-only meeting-id")
+	}
+	if !strings.Contains(err.Error(), "meeting-id") {
+		t.Errorf("error should mention meeting-id, got: %v", err)
+	}
+}
+
+func TestMeetingLeave_Validate_Valid(t *testing.T) {
+	cmd := &cobra.Command{Use: "test"}
+	cmd.Flags().String("meeting-id", "", "")
+	_ = cmd.Flags().Set("meeting-id", "69999999")
+
+	runtime := common.TestNewRuntimeContext(cmd, defaultConfig())
+	if err := VCMeetingLeave.Validate(context.Background(), runtime); err != nil {
+		t.Errorf("unexpected validation error: %v", err)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// DryRun tests: VCMeetingLeave
+// ---------------------------------------------------------------------------
+
+func TestMeetingLeave_DryRun(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	err := mountAndRun(t, VCMeetingLeave, []string{
+		"+meeting-leave", "--meeting-id", "69999999",
+		"--dry-run", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	if !strings.Contains(out, "/open-apis/vc/v1/bots/leave") {
+		t.Errorf("dry-run should include API path, got: %s", out)
+	}
+	if !strings.Contains(out, "69999999") {
+		t.Errorf("dry-run should include meeting-id, got: %s", out)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Execute tests: VCMeetingLeave
+// ---------------------------------------------------------------------------
+
+func TestMeetingLeave_Execute_Success(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	stub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/vc/v1/bots/leave",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{},
+		},
+	}
+	reg.Register(stub)
+
+	err := mountAndRun(t, VCMeetingLeave, []string{
+		"+meeting-leave", "--meeting-id", "69999999",
+		"--format", "json", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	// verify captured request body
+	var req map[string]interface{}
+	if err := json.Unmarshal(stub.CapturedBody, &req); err != nil {
+		t.Fatalf("failed to parse request body: %v", err)
+	}
+	if req["meeting_id"] != "69999999" {
+		t.Errorf("meeting_id = %v, want 69999999", req["meeting_id"])
+	}
+}
+
+func TestMeetingLeave_Execute_TrimsMeetingID(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	stub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/vc/v1/bots/leave",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{},
+		},
+	}
+	reg.Register(stub)
+
+	err := mountAndRun(t, VCMeetingLeave, []string{
+		"+meeting-leave", "--meeting-id", "  69999999  ",
+		"--format", "json", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var req map[string]interface{}
+	if err := json.Unmarshal(stub.CapturedBody, &req); err != nil {
+		t.Fatalf("failed to parse request body: %v", err)
+	}
+	if req["meeting_id"] != "69999999" {
+		t.Errorf("meeting_id should be trimmed, got %q", req["meeting_id"])
+	}
+}
+
+func TestMeetingLeave_Execute_APIError(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/vc/v1/bots/leave",
+		Body:   map[string]interface{}{"code": 121005, "msg": "no permission"},
+	})
+
+	err := mountAndRun(t, VCMeetingLeave, []string{
+		"+meeting-leave", "--meeting-id", "69999999", "--as", "user",
+	}, f, &bytes.Buffer{})
+	if err == nil {
+		t.Fatal("expected error for API failure")
+	}
+	if !strings.Contains(err.Error(), "no permission") {
+		t.Errorf("error should surface API message, got: %v", err)
+	}
+}

skills/lark-vc-agent/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: lark-vc-agent
+version: 1.0.0
+description: "飞书视频会议：让机器人代当前用户加入/离开正在进行的会议，并读取会议期间的实时事件（参会人加入与离开、发言、聊天、屏幕共享等）。1. 用户提供 9 位会议号、要求代为入会或离会时使用 +meeting-join / +meeting-leave——会真实产生入会/离会记录。2. 会议进行中用户想知道“谁加入了”“谁离开了”“谁在发言”“有人共享屏幕吗”等会中动态时，机器人入会后用 +meeting-events 读取事件时间线。3. 典型场景：参会机器人、会中助手、代为旁听、代为参会。前提：机器人只能读到它自己参会过且仍在进行中的会议的事件；查询已结束会议的参会名单、纪要或逐字稿请使用 lark-vc 技能。"
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli vc --help"
+---
+
+# vc-agent (v1)
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取以下两份 skill 文档：**
+- [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) — 认证、身份切换、权限处理
+- [`../lark-vc/SKILL.md`](../lark-vc/SKILL.md) — 视频会议的核心概念（Meeting / Note / Minutes 等），本 skill 直接复用，不再重复定义
+
+## 定位
+
+本 skill 与 [`lark-vc`](../lark-vc/SKILL.md) 并列：
+- **`lark-vc` 负责"会后查询"**：搜索历史会议、参会人快照、纪要/逐字稿/录制
+- **`lark-vc-agent` 负责"会中动作"**：机器人入会 / 读取进行中会议的实时事件 / 机器人离会
+
+按此分工路由，避免两个 skill 语义混淆。
+
+| 用户意图示例 | 应路由到 |
+|---|---|
+| "帮我入会 123456789"、"代我参会"、"让机器人进会旁听" | **本 skill** `+meeting-join` |
+| "会议现在还开着，谁刚加入了"、"会议里谁在发言"、"有人共享屏幕吗"（**进行中会议**，且**机器人已入会**）| **本 skill** `+meeting-events` |
+| "退出会议"、"让机器人离开" | **本 skill** `+meeting-leave` |
+| "昨天那场会有谁参加过"、"搜昨天的会"、"查纪要/逐字稿/录制" | [`lark-vc`](../lark-vc/SKILL.md) |
+| "帮我参会，结束后把纪要发到群" 等跨阶段场景 | 按序编排：本 skill（入会 → 读事件 → 离会）→ [`lark-vc`](../lark-vc/SKILL.md) / [`lark-minutes`](../lark-minutes/SKILL.md)（拉纪要）→ [`lark-im`](../lark-im/SKILL.md)（发群） |
+
+## 核心场景
+
+### 1. 加入正在进行的会议（写操作）
+
+1. 只有用户明确表达"让 Agent **真实入会**"（参会机器人、会中助手、代为旁听、代参会）时才用 `+meeting-join`。只是查数据不要入会。
+2. `+meeting-join --meeting-number` 只接受 **9 位纯数字**会议号，不是会议链接整串、也不是 `meeting_id`。
+3. 返回体中的 `meeting.id` **必须立刻记录**——后续 `+meeting-events` / `+meeting-leave` 都靠它，**不能用 9 位会议号替代**。
+4. 入会对所有参会人可见，执行前核实 9 位会议号来源，避免误入错会。
+5. 仅支持 `user` 身份，需提前 `lark-cli auth login` 并拥有 `vc:meeting.bot.join:write` scope。
+6. 若入会失败，优先查看 `+meeting-join` reference 的错误排查段落，重点确认会议号、密码、会议状态、等候室 / 审批以及会议是否禁止当前身份加入。
+
+### 2. 感知会中事件（读操作）
+
+1. 用户要看"会议里正在发生什么"（参会人加入/离开、聊天、转写、屏幕共享）时，用 `+meeting-events`。
+2. 输入是 **`meeting_id`**（长数字 ID），不是 9 位会议号。
+3. Bot 必须**真实参会过**（先 `+meeting-join`），否则事件流通常不可见。具体的状态边界、结束后宽限窗口与错误码（如 `10005 / 20001 / 20002`）请查看 `+meeting-events` reference。
+4. **不能做会后复盘**，**不能替代参会人快照查询**。如果会议已结束：
+   - 想拿纪要文档或逐字稿文档 token：用 `lark-cli vc +notes --meeting-ids <meeting.id>`
+   - 想拿 AI 产物（summary / todos / chapters）或导出逐字稿文件：先用 `lark-cli vc +recording --meeting-ids <meeting.id>` 拿 `minute_token`，再用 `lark-cli vc +notes --minute-tokens <minute_token>`
+   - 想看参会人快照：用 `vc meeting get --with-participants`（见 [`lark-vc`](../lark-vc/SKILL.md)）
+5. **默认必须使用 `--page-all`**，除非用户明确要求“只查一页”，或确实需要控制返回体大小。
+6. 输出格式默认优先 `--format pretty`（时间线更易读）；只有在需要完整保留原始消息流与结构化字段时，才使用 `--format json`。
+7. **必须识别分页信号**：只要响应里出现 `has_more=true`、pretty 里的 `more available`，或返回了非空 `page_token`，就不能把当前结果当作完整事件流；默认应继续分页，或明确告诉用户当前只是部分结果。
+8. 保留响应里的 `page_token`，下次增量拉取直接续，不要从头再拉。
+9. **只要你是基于 `+meeting-events` 来回答一场正在进行中的会议内容，就不能直接复用旧结果。** 无论用户是在问“现在/刚刚/最新”的状态，还是让你“总结一下这个会议讲什么”，都必须先重新拉一次当前事件流，确认拿到的是最新信息，再基于最新结果回答。只有在用户明确要求基于某次历史快照继续分析时，才可以复用旧结果。
+
+### 3. 离开会议（写操作）
+
+1. 任务完成、或用户要求结束时，用 `+meeting-leave --meeting-id <从 +meeting-join 拿到的 meeting.id>`。
+2. `--meeting-id` **必须**是 `+meeting-join` 返回的长数字 `meeting.id`，**不接受 9 位会议号**。
+3. 离会**立即生效**，机器人从会议的参会人列表中消失，对其他参会人可见；若需要重新入会，再跑一次 `+meeting-join` 即可（非真正"不可逆"）。
+4. 仅支持 `user` 身份，scope 同 `+meeting-join`（`vc:meeting.bot.join:write`）。
+
+### 4. Agent 参会最小闭环示范
+
+```bash
+# 1. 入会，捕获 meeting.id
+JOIN=$(lark-cli vc +meeting-join --meeting-number 123456789 --format json)
+MID=$(echo "$JOIN" | jq -r '.data.meeting.id')
+
+# 2. 会中轮询事件
+#    默认用 --page-all 拉全当前可见事件；下次增量优先复用 page_token
+#    典型间隔 10-30 秒
+lark-cli vc +meeting-events --meeting-id "$MID" --page-all --format pretty
+
+# 3. 任务完成或用户要求结束时离会
+lark-cli vc +meeting-leave --meeting-id "$MID"
+
+# 4. 会后可选：取纪要 / 逐字稿（跨到 lark-vc）
+lark-cli vc +notes --meeting-ids "$MID"
+```
+
+## Shortcuts
+
+Shortcut 是对常用操作的高级封装（`lark-cli vc +<verb> [flags]`）。
+
+| Shortcut | 类型 | 说明 |
+|----------|------|------|
+| [`+meeting-join`](references/lark-vc-agent-meeting-join.md)   | 写 | Join an in-progress meeting by 9-digit meeting number |
+| [`+meeting-events`](references/lark-vc-agent-meeting-events.md) | 读 | List bot meeting events (participant joined/left, transcript, chat, share) |
+| [`+meeting-leave`](references/lark-vc-agent-meeting-leave.md) | 写 | Leave a meeting by meeting_id |
+
+- 使用 `+meeting-join` 前**必须**阅读 [references/lark-vc-agent-meeting-join.md](references/lark-vc-agent-meeting-join.md)，了解入参格式与写操作可见性风险。
+- 使用 `+meeting-events` 前**必须**阅读 [references/lark-vc-agent-meeting-events.md](references/lark-vc-agent-meeting-events.md)，了解 `meeting_id` 来源、分页、错误码（10005 / 20001 / 20002）与 "bot 仍在会中" 硬约束。
+- 使用 `+meeting-leave` 前**必须**阅读 [references/lark-vc-agent-meeting-leave.md](references/lark-vc-agent-meeting-leave.md)，了解 `meeting_id` 的来源与写操作可见性。
+
+## 权限表
+
+| Shortcut | 所需 scope |
+|----------|-----------|
+| `+meeting-join`  | `vc:meeting.bot.join:write` |
+| `+meeting-events`| `vc:meeting.meetingevent:read` |
+| `+meeting-leave` | `vc:meeting.bot.join:write` |
+
+## 延伸
+
+- 查已结束会议、参会人快照、搜索历史会议 → [`lark-vc`](../lark-vc/SKILL.md)
+- 会议纪要、逐字稿 → [`lark-vc`](../lark-vc/SKILL.md) 的 `+notes`
+- 妙记产物（AI 总结 / 转写 / 章节）→ [`lark-minutes`](../lark-minutes/SKILL.md)
+- 会后把产物发到群 / 私聊 → [`lark-im`](../lark-im/SKILL.md)
+- 认证、身份切换、scope 管理 → [`lark-shared`](../lark-shared/SKILL.md)

skills/lark-vc-agent/references/lark-vc-agent-meeting-events.md

@@ -0,0 +1,248 @@
+
+# vc +meeting-events
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+查询当前 bot 在一场正在进行的视频会议中收到的会中事件列表。该命令是**读操作**。对进行中会议，要求 bot 当前仍在会中；对已结束会议，存在一个**结束后 5 分钟内的宽限窗口**，只要 bot 曾经在这场会里出现过，仍可继续拉取事件。
+
+本 skill 对应 shortcut：`lark-cli vc +meeting-events`（调用 `GET /open-apis/vc/v1/bots/events`）。
+
+## 命令
+
+```bash
+# 默认用法：全量拉取当前可见事件
+lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --page-all --format pretty
+
+# 指定时间范围，并拉全该时间窗内当前可见事件
+lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --start 2026-04-17T15:00:00+08:00 --end 2026-04-17T16:00:00+08:00 --page-all --format pretty
+
+# 基于上一次保存的 page_token 继续查新增事件
+lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --page-token <last_page_token> --page-all --format pretty
+
+# 调试或控制返回体大小时，显式只查一页
+lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --page-size 20 --format json
+
+# 预览 API 调用（不实际请求）
+lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--meeting-id <id>` | 是 | 会议 ID（长数字 ID，不是 9 位会议号） |
+| `--start <time>` | 否 | 起始时间，支持 ISO 8601 / `YYYY-MM-DD` / Unix 秒 |
+| `--end <time>` | 否 | 结束时间，支持 ISO 8601 / `YYYY-MM-DD` / Unix 秒 |
+| `--page-token <token>` | 否 | 从指定分页游标继续拉取下一页 |
+| `--page-size <n>` | 否 | 单页模式每页大小。CLI 会自动夹紧到 `20-100`；传 `--page-all` 时固定使用 `100` |
+| `--page-all` | 否 | 自动分页，直到没有更多页面为止（内部有安全上限） |
+| `--format <fmt>` | 否 | 输出格式：json (CLI 默认) / pretty（本 skill 推荐默认） / table / ndjson / csv |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+## 核心约束
+
+### 1. 输入必须是 meeting_id，不是 9 位会议号
+
+`--meeting-id` 必须是会议的长数字 ID。它通常来自：
+- `+meeting-join` 返回体中的 `meeting.id`
+- `+search` 结果中的 `id`
+
+**不要**把 9 位会议号（`--meeting-number`）传给这个命令。
+
+### 2. 仅支持 user 身份
+
+该命令仅支持 `user` 身份，使用前需完成 `lark-cli auth login`。
+
+### 3. bot 必须在会中，或在会议结束后的 5 分钟宽限窗口内曾经在会中
+
+这是查询“bot 在会中观察到的事件”的接口。若 bot 已离会、未入会、或会议已经无法再判断 bot 身份，后端通常会报：
+- `bot is not in meeting, no permission`
+
+因此，最稳妥的调用顺序通常是：
+
+```bash
+# 先入会
+lark-cli vc +meeting-join --meeting-number 123456789
+
+# 记录返回的 meeting.id
+
+# 再查询事件
+lark-cli vc +meeting-events --meeting-id <meeting.id>
+```
+
+更精确地说，后端当前的判断规则是：
+
+- **会议进行中**：要求 bot **当前仍在会中**
+- **会议已结束后的 5 分钟内**：只要 bot **曾经在这场会中出现过**，仍可拉取事件
+- **会议结束超过 5 分钟**：按会议结束处理，通常不再返回事件流
+- **bot 从未真实入会过**：即使会议仍在进行或刚结束，也会返回 `10005 bot is not in meeting`
+
+### 4. 自动分页规则
+
+- **先分清两层默认值**：
+  - shortcut 本身：不传 `--page-all` 时，只查 1 页。
+  - 本 skill 的默认策略：除非用户明确要求只看一页，或你确实需要控制返回体大小，否则默认**必须主动带 `--page-all`**，把当前可见事件尽量一次拉全。
+- 传 `--page-all`：开启自动分页，直到没有更多页面为止。
+- `--page-all` 时，CLI 固定使用最大 `page_size=100`。
+
+执行准则：
+
+- **默认命令模板**：`lark-cli vc +meeting-events --meeting-id <meeting.id> --page-all --format pretty`
+- 如果你发现自己执行成了不带 `--page-all` 的单页查询，而响应里又出现 `has_more=true` / `more available` / 非空 `page_token`，应立刻意识到这只是部分结果。
+- 遇到上述情况，默认补救方式是继续使用返回的 `page_token` 续拉，例如：`lark-cli vc +meeting-events --meeting-id <meeting.id> --page-token <returned_page_token> --page-all --format pretty`
+- 只有在用户明确要求“就看第一页”“先不要翻页”时，才不要默认带 `--page-all`
+- 只要你是基于 `+meeting-events` 来回答一场**正在进行中的会议内容**，就不能直接复用上一次查询结果。无论用户是在问“现在是谁在说话”“刚刚发生了什么”“最新事件有哪些”，还是让你“总结一下这个会议讲什么”，都必须先重新执行一次 `+meeting-events`，确认拿到的是最新事件流，再回答用户。只有在用户明确要求基于某次历史快照继续分析时，才可以复用旧结果。
+
+### 5. pretty / json 输出差异
+
+- `--format pretty`：输出会议主题、会议时间和逐条时间线，适合快速理解“发生了什么”，也是本 skill 的默认推荐格式。
+- `--format json`：保留完整原始 `events[]` 结构——参会人 open_id、聊天原文、share_doc、分页字段都在原始响应里，适合提取字段、联动其他命令或做进一步程序处理。
+
+**选型原则**：只要目标是告诉用户“发生了什么”，默认就用 `--page-all --format pretty`；只有在需要完整原始消息流和结构化字段时，才改用 `json`。
+
+> **注意**：pretty 输出中的正文文本会做单行转义，真实换行会显示为 `\n`，避免打乱时间线布局。
+
+### 6. 内容理解模式：共享文档不能只看标题
+
+当用户意图是：
+
+- “总结这个会议”
+- “这个会议讲了什么”
+- “有哪些结论 / 待办 / 关键讨论”
+- “共享文档里在讲什么”
+
+不要只基于事件时间线直接回答。此时 `+meeting-events` 只是**线索发现器**，不是最终信息源。
+
+执行准则：
+
+- 这类问题默认先用 `lark-cli vc +meeting-events --meeting-id <meeting.id> --page-all --format json` 拉取最新事件流。
+- 如果事件中出现共享文档线索，例如：
+  - `magic_share_started`
+  - `share_doc.title`
+  - `share_doc.url`
+- 必须继续读取共享文档内容，再生成总结，不能只根据“开始共享了某文档”这条事件和文档标题来概括会议内容。
+- 若存在多个共享文档，优先读取**最近一次共享**的文档。
+- 若文档读取失败，必须明确说明“以下总结仅基于会中事件流，未成功读取共享文档内容”。
+
+### 7. 关于 `page_token` 的返回与续拉
+
+- 不管这次是只查 1 页，还是通过 `--page-all` 已经把当前可见事件都拿完，都应把最后拿到的 `page_token` 一并保留下来并返回给用户。
+- 只要响应里出现 `has_more=true`、pretty 里出现 `more available`，或返回了非空 `page_token`，就必须先判断当前结果是否完整；默认情况下，这意味着你还需要继续分页。
+- 如果没有使用 `--page-all`，但出现了上述分页信号，默认应继续用返回的 `page_token` 拉下一页，而不是直接结束。只有在用户明确不要继续翻页时，才可以停止并明确说明当前结果不完整。
+- 下次继续“查新增事件”时，应优先复用上一次保存的 `page_token`，而不是从头全量再拉一次。
+- 只有在用户明确要求“从头回放全部事件”时，才忽略历史 `page_token`，重新从第一页开始。
+- 但如果用户要你回答的是**当前这场会正在讲什么**，而不是“上一次之后新增了什么”，也要先做一次新的事件查询，再决定是否需要基于旧 `page_token` 继续补拉。
+
+## 返回结构
+
+常见顶层字段：
+
+| 字段 | 说明 |
+|------|------|
+| `events` | 事件列表 |
+| `has_more` | 是否还有下一页 |
+| `page_token` | 下一页游标 |
+
+事件 `event_type` 常见类型：
+
+| event_type | 含义 |
+|-----------|------|
+| `participant_joined` | 有参会人加入会议 |
+| `participant_left` | 有参会人离开会议 |
+| `chat_received` | 收到会中聊天消息 |
+| `transcript_received` | 收到转写文本 |
+| `magic_share_started` | 开始共享内容 / 文档 |
+| `magic_share_ended` | 结束共享 |
+
+## pretty 输出示例
+
+```text
+会议主题：张三的视频会议
+会议时间：2026-04-17 15:28:52（进行中）
+
+[00:00:33] 明日之虾BOE(ou_xxx) 加入了会议
+[00:00:41] 张三(ou_xxx): [text] 6666
+[00:00:44] 张三(ou_xxx) 开始共享《智能纪要：飞书20251022-140223 2026年3月9日》
+           URL: https://...
+[00:01:32] 张三(ou_xxx): [reaction] JIAYI
+```
+
+## 如何获取输入参数
+
+| 输入参数 | 获取方式 |
+|---------|---------|
+| `meeting-id` | `+meeting-join` 返回的 `meeting.id`；或 `+search` 结果中的 `id` |
+| `start` / `end` | 用户给出的时间范围；如未给出则默认取全量可见事件 |
+| `page-token` | 上一页或上一次查询结果中保存的 `page_token`；建议持久化保存，便于下次继续拉取新增事件 |
+
+## Agent 组合场景
+
+### 场景 1：入会后查看会中发生了什么
+
+```bash
+# 第 1 步：加入会议，记录返回的 meeting.id
+lark-cli vc +meeting-join --meeting-number 123456789
+
+# 第 2 步：查询事件流
+lark-cli vc +meeting-events --meeting-id <meeting.id> --page-all --format pretty
+```
+
+### 场景 2：过滤某段时间内的事件
+
+```bash
+lark-cli vc +meeting-events \
+  --meeting-id <meeting.id> \
+  --start 2026-04-17T15:00:00+08:00 \
+  --end 2026-04-17T16:00:00+08:00 \
+  --page-all \
+  --format pretty
+```
+
+### 场景 3：基于上一次的 `page_token` 继续查新增事件
+
+```bash
+# 上一次查询结束后，保留最后返回的 page_token
+# 这次直接从该游标继续拉新增事件
+lark-cli vc +meeting-events \
+  --meeting-id <meeting.id> \
+  --page-token <last_page_token> \
+  --page-all \
+  --format pretty
+```
+
+适用规则：
+
+- 当用户说“继续看新事件”“看上次之后新增了什么”时，优先使用上一次保存的 `page_token`。
+- 如果这次返回里仍有 `has_more=true`、pretty 里出现 `more available`，或又返回了新的 `page_token`，说明新增事件还没拉完，应继续分页，而不是把当前页误当成完整增量结果。
+- 只有在用户明确要求“从头回放全部事件”时，才忽略已有 `page_token`，重新从第一页开始。
+
+## 常见错误与排查
+
+| 错误现象 | 根本原因 | 解决方案 |
+|---------|---------|---------|
+| `--meeting-id is required` | 未传入 `--meeting-id` | 传入长数字 `meeting.id` |
+| `10005 bot is not in meeting` | bot 从未真实入会该会议；或会议已结束但 bot 从未在会中出现过 | 先 `+meeting-join --meeting-number <9位号>` 真实入会再查；如果会议已经结束且当时 bot 没进过会，本接口也拉不到数据。**如果只是想看参会人快照，改用 `vc meeting get --with-participants`**（不依赖 bot 身份参会） |
+| `20001 meeting_status_MEETING_END` | 会议已结束且已超出后端允许的 5 分钟宽限窗口 | 本接口不再适合继续拉取事件。若要拿纪要文档或逐字稿 token，用 `lark-cli vc +notes --meeting-ids <meeting.id>`；若要拿 AI 产物（summary / todos / chapters）或导出逐字稿文件，先用 `lark-cli vc +recording --meeting-ids <meeting.id>` 拿 `minute_token`，再用 `lark-cli vc +notes --minute-tokens <minute_token>`；参会人请用 `vc meeting get --with-participants` |
+| `20002 meeting not exist` | `meeting_id` 错误，或会议实例当前已不可获取（常见于把 9 位会议号当 meeting_id 传） | 确认传入的是长数字 `meeting_id`，不是 9 位会议号 |
+| `HTTP 404` / `HTTP 500` | 服务端当前无法找到或处理该会议实例 | 换一个正在进行且 bot 可见的 meeting_id，或排查后端问题 |
+| `missing required scope(s)` | 未授权 `vc:meeting.meetingevent:read` | 按提示重新 `auth login` 补 scope |
+
+## 提示
+
+- 这是**会中事件流**查询，不适合拿来搜历史会议记录；搜历史会议请用 `+search`。
+- 如果会议已经结束，不要卡在 `+meeting-events`：  
+  - 想拿纪要文档或逐字稿 token：用 `lark-cli vc +notes --meeting-ids <meeting.id>`
+  - 想拿 AI 产物（summary / todos / chapters）或导出逐字稿文件：先用 `lark-cli vc +recording --meeting-ids <meeting.id>` 拿 `minute_token`，再用 `lark-cli vc +notes --minute-tokens <minute_token>`
+- 事件列表是否完整，取决于 bot 何时入会、何时离会，以及后端当前可见的会中事件范围。对于已结束会议，通常只在**结束后 5 分钟内**、且 bot **曾经在会中**时还能继续拉到事件。
+- 查询"谁参加过某会议"请用 `vc meeting get --params '{"meeting_id":"<id>","with_participants":true}'`——这是参会人**快照** API，不依赖 bot 是否参会，对已结束会议也可查；**不要** 用 `+meeting-events` 做参会人查询。
+
+## 参考
+
+- [lark-vc-agent-meeting-join](lark-vc-agent-meeting-join.md) — 先真实入会
+- [lark-vc-agent-meeting-leave](lark-vc-agent-meeting-leave.md) — 完成任务后离会
+- [lark-vc-search](../../lark-vc/references/lark-vc-search.md) — 搜索历史会议（获取 meeting_id）
+- [lark-vc-recording](../../lark-vc/references/lark-vc-recording.md) — 查询 minute_token
+- [lark-vc-notes](../../lark-vc/references/lark-vc-notes.md) — 获取会议纪要
+- [lark-vc-agent](../SKILL.md) — Agent 参会能力（本 skill）
+- [lark-vc](../../lark-vc/SKILL.md) — 视频会议原子域（Meeting / Note 等核心概念）
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

skills/lark-vc-agent/references/lark-vc-agent-meeting-join.md

@@ -0,0 +1,134 @@
+
+# vc +meeting-join
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+通过 9 位会议号加入一场正在进行的视频会议（bot join）。这是一次**写操作**，会实际让当前身份加入会议。
+
+本 skill 对应 shortcut：`lark-cli vc +meeting-join`（调用 `POST /open-apis/vc/v1/bots/join`）。
+
+## 命令
+
+```bash
+# 仅指定会议号（无密码）
+lark-cli vc +meeting-join --meeting-number 123456789
+
+# 指定会议号 + 密码
+lark-cli vc +meeting-join --meeting-number 123456789 --password 8888
+
+# 输出格式
+lark-cli vc +meeting-join --meeting-number 123456789 --format json
+
+# 预览 API 调用（不实际加入会议）
+lark-cli vc +meeting-join --meeting-number 123456789 --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--meeting-number <no>` | 是 | 会议号，必须为 **9 位纯数字** |
+| `--password <pw>` | 否 | 会议密码，仅在该会议设置了入会密码时传入 |
+| `--format <fmt>` | 否 | 输出格式：json (默认) / pretty / table / ndjson / csv |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+## 核心约束
+
+### 1. 仅支持 user 身份
+
+该命令仅支持 `user` 身份，使用前需完成 `lark-cli auth login`。
+
+### 2. 会议号格式严格校验
+
+`--meeting-number` 必须是 9 位纯数字，否则本地校验直接报错：
+`--meeting-number must be exactly 9 digits`。
+
+常见错误来源：
+- 把会议链接整条粘进来（应仅取尾部的 9 位数字）
+- 把 `meeting_id`（长数字 ID）当成会议号传入（两者不是同一个东西）
+
+### 3. 会议必须已开始且允许入会
+
+- 会议必须处于**进行中**状态，bot 无法加入尚未开始或已结束的会议。
+- 若会议设置了**等候室 / 入会审批**，bot 可能需要主持人放行后才真正入会。
+- 若返回 `HTTP 403: no permission`（错误码 `121003`），不要只理解成“账号没权限”。这类报错更常见的原因是：会议参数或会控配置当前不满足入会条件，例如会议号填错、密码未传或错误、会议尚未开始、等候室 / 入会审批未放行、会议禁止外部/特定身份加入等。应先确认这些配置项，再重试。
+
+### 4. 机器人入会后对其他参会人可见
+
+这是一次真实入会操作，机器人会立即出现在参会人列表中，其他参会人可见，并产生会议日志。误入错会的社交成本高于技术成本——执行前优先确认 9 位会议号的来源（用户输入 / 会议链接末尾），不要臆造。参数格式有疑问时可用 `--dry-run` 预览请求体。
+
+## 输出结果
+
+接口返回会议基本信息，字段视具体响应而定，常见字段：
+
+| 字段 | 说明 |
+|------|------|
+| `meeting.id` | 会议 ID（可后续传给 `+meeting-leave --meeting-id`） |
+| `meeting.meeting_no` | 会议号（与入参一致） |
+| `meeting.topic` | 会议主题 |
+| `meeting.start_time` | 会议开始时间 |
+
+> **重要**：拿到 `meeting.id` 后务必保留，退出会议（`+meeting-leave`）需要使用它，而不是会议号。
+
+## 如何获取输入参数
+
+| 输入参数 | 获取方式 |
+|---------|---------|
+| `meeting-number` | 会议号由主持人分享；也可从会议链接尾部解析 9 位数字 |
+| `password` | 若会议设置了入会密码，由主持人提供 |
+
+## Agent 组合场景
+
+### 场景 1：加入会议 → 离开会议（最小闭环）
+
+```bash
+# 第 1 步：加入会议，记录返回的 meeting.id
+lark-cli vc +meeting-join --meeting-number 123456789
+
+# 第 2 步：完成任务后，使用上一步返回的 meeting.id 离开会议
+lark-cli vc +meeting-leave --meeting-id <meeting.id>
+```
+
+### 场景 2：加入会议 → 会后拉取纪要 / 录制
+
+```bash
+# 第 1 步：加入并参会
+lark-cli vc +meeting-join --meeting-number 123456789
+
+# 第 2 步：离会
+lark-cli vc +meeting-leave --meeting-id <meeting.id>
+
+# 第 3 步：会议结束后，查询录制（拿到 minute_token）
+lark-cli vc +recording --meeting-ids <meeting.id>
+
+# 第 4 步：查询会议纪要（总结 / 待办 / 章节 / 逐字稿）
+lark-cli vc +notes --meeting-ids <meeting.id>
+```
+
+## 常见错误与排查
+
+| 错误现象 | 根本原因 | 解决方案 |
+|---------|---------|---------|
+| `--meeting-number must be exactly 9 digits` | 会议号不是 9 位纯数字 | 检查是否误传了会议链接或 meeting_id |
+| `missing required scope(s)` | 未授权 `vc:meeting.bot.join:write` | 按提示运行 `auth login --scope vc:meeting.bot.join:write` |
+| 会议密码错误 | `--password` 错误或未提供 | 向主持人确认会议密码 |
+| 会议不存在 / 已结束 | 会议号错误或会议未进行中 | 确认会议正在进行中 |
+| `HTTP 403: no permission` / `121003` | 入会前置条件不满足，通常不是单纯 scope 问题 | 依次确认：1）会议允许智能体加入；2）会议号正确；3）如有密码，已正确传入 `--password`；4）会议已开始；5）等候室 / 入会审批已放行；6）会议未禁止当前身份加入（如限制外部、限制 bot、仅特定成员可入会）；确认后重试 |
+| 入会被拒绝 | 等候室 / 入会审批 / 限制外部入会 | 联系主持人放行或调整会议设置 |
+
+## 提示
+
+- 仅在 Agent 需要**真实加入**会议（例如参会机器人、会中助手）时使用；只拉取会议数据不需要入会。
+- 入会会让机器人立即出现在参会列表；若要回退，直接 `+meeting-leave` 即可。参数格式不确定时可选 `--dry-run` 预览，但不是必经步骤。
+- 执行成功后，立即记录返回的 `meeting.id`，用于后续 `+meeting-leave` / `+meeting-events`。
+
+## 参考
+
+- [lark-vc-agent-meeting-leave](lark-vc-agent-meeting-leave.md) — 对应的离会命令
+- [lark-vc-agent-meeting-events](lark-vc-agent-meeting-events.md) — 会中事件流
+- [lark-vc-search](../../lark-vc/references/lark-vc-search.md) — 搜索历史会议记录
+- [lark-vc-recording](../../lark-vc/references/lark-vc-recording.md) — 查询 minute_token
+- [lark-vc-notes](../../lark-vc/references/lark-vc-notes.md) — 获取会议纪要
+- [lark-vc-agent](../SKILL.md) — Agent 参会能力（本 skill）
+- [lark-vc](../../lark-vc/SKILL.md) — 视频会议原子域（Meeting / Note 等核心概念）
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

skills/lark-vc-agent/references/lark-vc-agent-meeting-leave.md

@@ -0,0 +1,112 @@
+
+# vc +meeting-leave
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+通过 `meeting_id` 离开当前身份所在的视频会议（bot leave）。这是一次**写操作**，会实际把当前身份从会议中移出。
+
+本 skill 对应 shortcut：`lark-cli vc +meeting-leave`（调用 `POST /open-apis/vc/v1/bots/leave`）。
+
+## 命令
+
+```bash
+# 通过 meeting_id 离会
+lark-cli vc +meeting-leave --meeting-id 69xxxxxxxxxxxxx28
+
+# 输出格式
+lark-cli vc +meeting-leave --meeting-id 69xxxxxxxxxxxxx28 --format json
+
+# 预览 API 调用（不实际离会）
+lark-cli vc +meeting-leave --meeting-id 69xxxxxxxxxxxxx28 --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--meeting-id <id>` | 是 | 会议 ID（**不是 9 位会议号**） |
+| `--format <fmt>` | 否 | 输出格式：json (默认) / pretty / table / ndjson / csv |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+## 核心约束
+
+### 1. 入参是 meeting_id，不是会议号
+
+`--meeting-id` 必须是会议的长数字 ID，通常由 `+meeting-join` 返回体中的 `meeting.id` 提供，也可从 `+search` 结果中的 `id` 字段获取。**传 9 位会议号会失败**。
+
+### 2. 仅支持 user 身份
+
+该命令仅支持 `user` 身份，使用前需完成 `lark-cli auth login`。只能让当前身份自己离会，无法强制移出其他参会人。
+
+### 3. 当前身份必须在会议中
+
+必须先通过 `+meeting-join` 或其他方式在该会议中，否则接口会报错。
+
+### 4. 离会立即生效，对其他参会人可见
+
+机器人会立刻从参会列表消失；若会议启用了录制/纪要，bot 的参会时段到此截止。确认任务完成再调用；如需要重新入会，再跑 `+meeting-join` 即可（非真正"不可逆"）。
+
+## 输出结果
+
+接口成功返回时，默认输出：`Left meeting <meeting-id> successfully.`。
+`--format json` 返回 API 原始响应体。
+
+## 如何获取输入参数
+
+| 输入参数 | 获取方式 |
+|---------|---------|
+| `meeting-id` | `+meeting-join` 返回的 `meeting.id`；或 `+search` 结果中的 `id` 字段 |
+
+## Agent 组合场景
+
+### 场景 1：加入 → 完成任务 → 离开（最小闭环）
+
+```bash
+# 第 1 步：加入会议，记录 meeting.id
+lark-cli vc +meeting-join --meeting-number 123456789
+
+# 第 2 步：在会中完成任务（如监听发言、记录信息等）
+# ...
+
+# 第 3 步：使用上一步记录的 meeting.id 离会
+lark-cli vc +meeting-leave --meeting-id <meeting.id>
+```
+
+### 场景 2：会后补拉产物
+
+```bash
+# 第 1 步：离会后会议仍在进行或已结束
+lark-cli vc +meeting-leave --meeting-id <meeting.id>
+
+# 第 2 步：会议结束后查询录制
+lark-cli vc +recording --meeting-ids <meeting.id>
+
+# 第 3 步：查询会议纪要
+lark-cli vc +notes --meeting-ids <meeting.id>
+```
+
+## 常见错误与排查
+
+| 错误现象 | 根本原因 | 解决方案 |
+|---------|---------|---------|
+| `--meeting-id is required` | 未传入 `--meeting-id` | 传入从 `+meeting-join` 得到的 `meeting.id` |
+| `meeting not found` / `invalid meeting_id` | 误传了 9 位会议号 | 必须使用 `meeting.id`，不是会议号 |
+| `not in meeting` | 当前身份并不在该会议中 | 确认先 `+meeting-join` 成功 |
+| `missing required scope(s)` | 未授权 `vc:meeting.bot.join:write` | 按提示运行 `auth login --scope vc:meeting.bot.join:write` |
+
+## 提示
+
+- 离会会让机器人从参会列表消失，对其他参会人可见；若需要重新入会直接再 `+meeting-join`，不是真正的"不可逆"。参数格式不确定时可选 `--dry-run` 预览。
+- 与 `+meeting-join` 成对使用：能 join 的身份才能 leave。
+- `meeting_id` 必须来自 `+meeting-join` 的返回值，不要用 9 位会议号。
+
+## 参考
+
+- [lark-vc-agent-meeting-join](lark-vc-agent-meeting-join.md) — 对应的入会命令
+- [lark-vc-agent-meeting-events](lark-vc-agent-meeting-events.md) — 会中事件流
+- [lark-vc-search](../../lark-vc/references/lark-vc-search.md) — 搜索历史会议（获取 meeting_id）
+- [lark-vc-recording](../../lark-vc/references/lark-vc-recording.md) — 查询 minute_token
+- [lark-vc-notes](../../lark-vc/references/lark-vc-notes.md) — 获取会议纪要
+- [lark-vc-agent](../SKILL.md) — Agent 参会能力（本 skill）
+- [lark-vc](../../lark-vc/SKILL.md) — 视频会议原子域（Meeting / Note 等核心概念）
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

skills/lark-vc/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-vc
 version: 1.0.0
-description: "飞书视频会议：查询会议记录、获取会议纪要产物（总结、待办、章节、逐字稿）。1. 查询已经结束的会议数量或详情时使用本技能(如历史日期｜ 昨天 | 上周 | 今天已经开过的会议等场景)，查询未开始的会议日程使用 lark-calendar 技能。2. 支持通过关键词、时间范围、组织者、参与者、会议室等筛选条件搜索会议记录。3. 获取或整理会议纪要时使用本技能。"
+description: "飞书视频会议：搜索历史会议、查询会议纪要产物（总结、待办、章节、逐字稿）、查询会议参会人快照。1. 查询已经结束的会议数量或详情时使用本技能（如历史日期｜昨天｜上周｜今天已经开过的会议等场景），查询未开始的会议日程使用 lark-calendar 技能。2. 支持通过关键词、时间范围、组织者、参与者、会议室等筛选条件搜索会议。3. 获取或整理会议纪要、逐字稿、录制产物时使用本技能。4. 查询“谁参加过某会议”“参会人列表”等参会人快照信息用 vc meeting get --with-participants（任意时点可查，含已结束会议）。注意：**Agent 真实入会/离会、感知正在进行中会议的实时事件**请使用 lark-vc-agent 技能，本技能不覆盖写操作和会中事件流。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -14,8 +14,7 @@ metadata:
 
 ## 核心概念
 
-- **视频会议（Meeting）**：飞书视频会议实例，通过 meeting\_id 标识。
-- **会议记录（Meeting Record）**：视频会议结束后生成的记录，支持通过关键词、时间段、参会人、组织者、会议室等筛选条件搜索会议室。
+- **视频会议（Meeting）**：飞书视频会议实例，通过 meeting\_id 标识。已结束的会议支持通过关键词、时间段、参会人、组织者、会议室等条件搜索（见 `+search`）。
 - **会议纪要（Note）**：视频会议结束后生成的结构化文档，包含纪要文档（包含总结、待办、章节）和逐字稿文档。
 - **妙记（Minutes）**：来源于飞书视频会议的录制产物或用户上传的音视频文件，支持视频/音频的转写和会议纪要，通过 minute\_token 标识。
 - **纪要文档（MainDoc）**：AI 智能纪要的主文档，包含 AI 生成的总结和待办，对应 `note_doc_token`。
@@ -67,6 +66,23 @@ lark-cli drive metas batch_query --data '{"request_docs": [{"doc_type": "docx",
 lark-cli docs +fetch --api-version v2 --doc <doc_token> --doc-format markdown
 ```
 
+### 4. 查询参会人快照（读操作）
+
+用户问"谁参加过这场会议""这个会议有哪些参会人""某某参会了吗"等**参会人快照**类问题时，使用 **`vc meeting get --with-participants`**：这是参会人服务端快照 API，不依赖 bot 身份参会，**已结束会议也可查**：
+
+```bash
+lark-cli vc meeting get --params '{"meeting_id":"<meeting_id>","with_participants":true}'
+```
+
+选型判断表：
+
+| 用户意图 | 推荐命令 | 所在 skill |
+|---------|---------|--------|
+| 参会人快照（谁参加过、何时入/离会，任意时点）| `vc meeting get --with-participants` | 本 skill |
+| 已结束会议的发言内容 | `vc +notes` 取 `verbatim_doc_token` 再 `docs +fetch` | 本 skill |
+| **进行中会议**的实时事件流（转写、聊天、共享、会中加入/离开）| `vc +meeting-events` | [`lark-vc-agent`](../lark-vc-agent/SKILL.md) |
+| **Agent 真实入会 / 离会** | `vc +meeting-join` / `vc +meeting-leave` | [`lark-vc-agent`](../lark-vc-agent/SKILL.md) |
+
 ## 资源关系
 
 ```
@@ -109,6 +125,8 @@ Shortcut 是对常用操作的高级封装（`lark-cli vc +<verb> [flags]`）。
 - 使用 `+notes` 命令时，必须阅读 [references/lark-vc-notes.md](references/lark-vc-notes.md)，了解查询参数、产物类型和返回值结构。
 - 使用 `+recording` 命令时，必须阅读 [references/lark-vc-recording.md](references/lark-vc-recording.md)，了解查询参数和返回值结构。
 
+> **Agent 参会相关命令已独立**：`+meeting-join` / `+meeting-leave` / `+meeting-events` 请使用 [`lark-vc-agent`](../lark-vc-agent/SKILL.md) 技能。
+
 ## API Resources
 
 ```bash
@@ -146,3 +164,5 @@ lark-cli vc meeting get --params '{"meeting_id": "<meeting_id>", "with_participa
 | `+recording --calendar-event-ids` | `vc:record:readonly`、`calendar:calendar:read`、`calendar:calendar.event:read` |
 | `+search` | `vc:meeting.search:read` |
 | `meeting.get` | `vc:meeting.meetingevent:read` |
+
+> Agent 参会相关 scope（`vc:meeting.bot.join:write` / `vc:meeting.meetingevent:read`）见 [`lark-vc-agent`](../lark-vc-agent/SKILL.md)。

skills/lark-vc/references/lark-vc-recording.md

@@ -109,7 +109,7 @@ lark-cli vc +notes --minute-tokens <minute_token>
 
 ```bash
 # 第 1 步：搜索历史会议，拿到 meeting_ids
-lark-cli vc +search --query "周会" --start yesterday
+lark-cli vc +search --query "周会" --start 2026-03-10
 
 # 第 2 步：使用上一步返回的 meeting_ids 查询录制，拿到 minute_tokens
 lark-cli vc +recording --meeting-ids <ids>