chore: release v1.0.66

refactor(envvars): consolidate agent env value access (#1757 )
* feat(envvars): add LARKSUITE_CLI_AGENT_NAME accessor envvars.AgentName() reads LARKSUITE_CLI_AGENT_NAME so business code can identify the agent driving the CLI. Value is sanitised (trim, reject control chars, 128-byte cap) and returns "" when unset or invalid. Local-only; not sent to the server. * refactor(envvars): consolidate agent env accessors, dedupe sanitize Move agent-trace reading from cmdutil.AgentTraceValue into envvars.AgentTrace(), symmetric with AgentName and sharing one sanitizeSingleLine. secheader.go now only assembles headers (BaseSecurityHeaders calls envvars.AgentTrace()); the duplicated sanitize and its os/unicode imports are gone. The X-Agent-Trace header and its behaviour are unchanged. --------- Co-authored-by: liangshuo-1 <266696938+liangshuo-1@users.noreply.github.com>
2026-07-07 09:11:44 +08:00 · 2026-07-06 21:22:00 +08:00 · 2026-07-06 21:17:51 +08:00 · 2026-07-06 21:11:01 +08:00 · 2026-07-06 20:03:05 +08:00 · 2026-07-06 17:07:10 +08:00
33 changed files with 1129 additions and 1114 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,43 @@

 All notable changes to this project will be documented in this file.

+## [v1.0.66] - 2026-07-06
+
+### Features
+
+- support semantic recurring calendar operations (#1723)
+
+### Bug Fixes
+
+- guide drive import concurrency conflicts (#1751)
+- **calendar**: guide approval room booking fallback (#1637)
+- support pnpm global installs in self-update (#1705)
+
+### Documentation
+
+- tighten doc creation validation workflow (#1759)
+- clarify success envelope contract — judge success by ok, not code (#1730)
+
+### Refactoring
+
+- **envvars**: consolidate agent env value access (#1757)
+
+## [v1.0.65] - 2026-07-03
+
+### Features
+
+- **doc**: Add `+history-list`, `+history-revert`, and `+history-revert-status` shortcuts for document version history (#1612)
+
+### Bug Fixes
+
+- **minutes**: `+speaker-replace` no longer refetches the speaker list — `--from-speaker-id` is passed through as-is (#1731)
+
+### Documentation
+
+- **drive**: Document 30-char query limit for `+search` (#1560)
+- **doc**: Add mindnote guidance to lark-doc skill (#1581)
+- **doc**: Sync lark-doc skill content from online-doc (#1701)
+
 ## [v1.0.64] - 2026-07-02

 ### Features
@@ -1355,6 +1392,8 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.

+[v1.0.66]: https://github.com/larksuite/cli/releases/tag/v1.0.66
+[v1.0.65]: https://github.com/larksuite/cli/releases/tag/v1.0.65
 [v1.0.64]: https://github.com/larksuite/cli/releases/tag/v1.0.64
 [v1.0.62]: https://github.com/larksuite/cli/releases/tag/v1.0.62
 [v1.0.61]: https://github.com/larksuite/cli/releases/tag/v1.0.61
--- a/README.md
+++ b/README.md
@@ -233,6 +233,24 @@ lark-cli api POST /open-apis/im/v1/messages --params '{"receive_id_type":"chat_i
 --format csv       # Comma-separated values
 ```

+### JSON Output Contract
+
+With `--format json` (the default), success and error envelopes are distinct.
+
+Success goes to **stdout**, exit code `0`:
+
+```json
+{ "ok": true, "identity": "user", "data": { "guid": "..." }, "meta": { "count": 1 } }
+```
+
+Errors go to **stderr**, non-zero exit code:
+
+```json
+{ "ok": false, "identity": "user", "error": { "type": "api", "subtype": "...", "code": 99991679, "message": "...", "hint": "..." } }
+```
+
+To check whether a command succeeded, test `ok == true` (or the exit code) — **not** `code == 0`. Unlike raw OpenAPI responses (`{"code": 0, "msg": "ok", ...}`), the success envelope carries no `code` or `msg` field; `code` appears only inside `error` as the upstream OpenAPI code. See [errs/ERROR_CONTRACT.md](errs/ERROR_CONTRACT.md) for the full error taxonomy.
+
 ### Pagination

 ```bash
--- a/README.zh.md
+++ b/README.zh.md
@@ -234,6 +234,24 @@ lark-cli api POST /open-apis/im/v1/messages --params '{"receive_id_type":"chat_i
 --format csv       # 逗号分隔值
 ```

+### JSON 输出契约
+
+`--format json`（默认）下，成功与错误的信封结构不同。
+
+成功信封写入 **stdout**，退出码 0：
+
+```json
+{ "ok": true, "identity": "user", "data": { "guid": "..." }, "meta": { "count": 1 } }
+```
+
+错误信封写入 **stderr**，退出码非 0：
+
+```json
+{ "ok": false, "identity": "user", "error": { "type": "api", "subtype": "...", "code": 99991679, "message": "...", "hint": "..." } }
+```
+
+判断命令是否成功，请检查 `ok == true`（或进程退出码），**不要用 `code == 0`**。与原始 OpenAPI 响应（`{"code": 0, "msg": "ok", ...}`）不同，成功信封没有 `code` 和 `msg` 字段；`code` 只出现在错误信封的 `error` 内，含义是上游 OpenAPI 的 numeric code。完整错误分类见 [errs/ERROR_CONTRACT.md](errs/ERROR_CONTRACT.md)。
+
 ### 分页

 ```bash
--- a/cmd/update/update.go
+++ b/cmd/update/update.go
@@ -86,13 +86,10 @@ func symArrow() string {

 // UpdateOptions holds inputs for the update command.
 type UpdateOptions struct {
-	Factory      *cmdutil.Factory
-	JSON         bool
-	Force        bool
-	Check        bool
-	SkillsLayout string
-	FlatSkills   string
-	FlatSet      bool
+	Factory *cmdutil.Factory
+	JSON    bool
+	Force   bool
+	Check   bool
 }

 // NewCmdUpdate creates the update command.
@@ -105,13 +102,13 @@ func NewCmdUpdate(f *cmdutil.Factory) *cobra.Command {
 		Long: `Update lark-cli to the latest version.

 Detects the installation method automatically:
-  - npm install: runs npm install -g @larksuite/cli@<version>
+  - npm install:  runs npm install -g @larksuite/cli@<version>
+  - pnpm install: runs pnpm add -g @larksuite/cli@<version>
  - manual/other: shows GitHub Releases download URL

 Use --json for structured output (for AI agents and scripts).
 Use --check to only check for updates without installing.`,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			opts.FlatSet = cmd.Flags().Changed("flat-skills")
 			return updateRun(opts)
 		},
 	}
@@ -119,8 +116,6 @@ Use --check to only check for updates without installing.`,
 	cmd.Flags().BoolVar(&opts.JSON, "json", false, "structured JSON output")
 	cmd.Flags().BoolVar(&opts.Force, "force", false, "force reinstall even if already up to date")
 	cmd.Flags().BoolVar(&opts.Check, "check", false, "only check for updates, do not install")
-	cmd.Flags().StringVar(&opts.SkillsLayout, "skills-layout", "", "skills layout: separate or hybrid")
-	cmd.Flags().StringVar(&opts.FlatSkills, "flat-skills", "", "comma-separated skills kept as top-level skills when the effective layout is hybrid")
 	cmdutil.SetRisk(cmd, "high-risk-write")

 	return cmd
@@ -128,9 +123,6 @@ Use --check to only check for updates without installing.`,

 func updateRun(opts *UpdateOptions) error {
 	io := opts.Factory.IOStreams
-	if err := validateSkillsLayoutOptions(opts); err != nil {
-		return reportError(opts, io, "validation_error", err)
-	}
 	cur := currentVersion()
 	updater := newUpdater()

@@ -156,7 +148,7 @@ func updateRun(opts *UpdateOptions) error {
 	if !opts.Force && !update.IsNewer(latest, cur) {
 		var skillsResult *skillscheck.SyncResult
 		if !opts.Check {
-			skillsResult = runSkillsAndState(updater, io, cur, opts.Force, opts.SkillsLayout, opts.FlatSkills, opts.FlatSet)
+			skillsResult = runSkillsAndState(updater, io, cur, opts.Force)
 		}
 		return reportAlreadyUpToDate(opts, io, cur, latest, skillsResult, opts.Check)
 	}
@@ -173,7 +165,7 @@ func updateRun(opts *UpdateOptions) error {
 	if !detect.CanAutoUpdate() {
 		return doManualUpdate(opts, io, cur, latest, detect, updater)
 	}
-	return doNpmUpdate(opts, io, cur, latest, updater)
+	return doAutoUpdate(opts, io, cur, latest, detect, updater)
 }

 // --- Output helpers ---
@@ -217,7 +209,7 @@ func reportCheckResult(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest s
 }

 func doManualUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string, detect selfupdate.DetectResult, updater *selfupdate.Updater) error {
-	skillsResult := runSkillsAndState(updater, io, cur, opts.Force, opts.SkillsLayout, opts.FlatSkills, opts.FlatSet)
+	skillsResult := runSkillsAndState(updater, io, cur, opts.Force)

 	reason := detect.ManualReason()
 	if opts.JSON {
@@ -235,12 +227,23 @@ func doManualUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest stri
 	fmt.Fprintf(io.ErrOut, "To update manually, download the latest release:\n")
 	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 (note: skills will not be synced):\n  npm install -g %s@%s\n  npx skills add larksuite/cli -y -g   # sync skills separately\n", selfupdate.NpmPackage, latest)
+	if detect.Method == selfupdate.InstallPnpm {
+		fmt.Fprintf(io.ErrOut, "\nOr install via pnpm (note: skills will not be synced):\n  pnpm add -g %s@%s\n  pnpm dlx skills add larksuite/cli -y -g   # sync skills separately\n", selfupdate.NpmPackage, latest)
+	} else {
+		fmt.Fprintf(io.ErrOut, "\nOr install via npm (note: skills will not be synced):\n  npm install -g %s@%s\n  npx skills add larksuite/cli -y -g   # sync skills separately\n", selfupdate.NpmPackage, latest)
+	}
 	emitSkillsTextHints(io, skillsResult)
 	return nil
 }

-func doNpmUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string, updater *selfupdate.Updater) error {
+func doAutoUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string, detect selfupdate.DetectResult, updater *selfupdate.Updater) error {
+	pm := "npm"
+	install := updater.RunNpmInstall
+	if detect.Method == selfupdate.InstallPnpm {
+		pm = "pnpm"
+		install = updater.RunPnpmInstall
+	}
+
 	restore, err := updater.PrepareSelfReplace()
 	if err != nil {
 		return reportError(opts, io, "update_error",
@@ -248,19 +251,19 @@ func doNpmUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string,
 	}

 	if !opts.JSON {
-		fmt.Fprintf(io.ErrOut, "Updating lark-cli %s %s %s via npm ...\n", cur, symArrow(), latest)
+		fmt.Fprintf(io.ErrOut, "Updating lark-cli %s %s %s via %s ...\n", cur, symArrow(), latest, pm)
 	}

-	npmResult := updater.RunNpmInstall(latest)
+	npmResult := install(latest)
 	if npmResult.Err != nil {
 		restore()
 		combined := npmResult.CombinedOutput()
 		if opts.JSON {
 			output.PrintJson(io.Out, map[string]interface{}{
 				"ok": false, "error": map[string]interface{}{
-					"type": "update_error", "message": fmt.Sprintf("npm install failed: %s", npmResult.Err),
+					"type": "update_error", "message": fmt.Sprintf("%s install failed: %s", pm, npmResult.Err),
 					"detail": selfupdate.Truncate(combined, maxNpmOutput),
-					"hint":   permissionHint(combined),
+					"hint":   permissionHint(combined, pm),
 				},
 			})
 			return output.ErrBare(output.ExitAPI)
@@ -272,7 +275,7 @@ func doNpmUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string,
 			fmt.Fprint(io.ErrOut, npmResult.Stderr.String())
 		}
 		fmt.Fprintf(io.ErrOut, "\n%s Update failed: %s\n", symFail(), npmResult.Err)
-		if hint := permissionHint(combined); hint != "" {
+		if hint := permissionHint(combined, pm); hint != "" {
 			fmt.Fprintf(io.ErrOut, "  %s\n", hint)
 		}
 		return output.ErrBare(output.ExitAPI)
@@ -283,7 +286,7 @@ func doNpmUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string,
 	if err := updater.VerifyBinary(latest); err != nil {
 		restore()
 		msg := fmt.Sprintf("new binary verification failed: %s", err)
-		hint := verificationFailureHint(updater, latest)
+		hint := verificationFailureHint(updater, latest, pm)
 		if opts.JSON {
 			output.PrintJson(io.Out, map[string]interface{}{
 				"ok":    false,
@@ -296,7 +299,7 @@ func doNpmUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string,
 		return output.ErrBare(output.ExitAPI)
 	}

-	skillsResult := runSkillsAndState(updater, io, latest, opts.Force, opts.SkillsLayout, opts.FlatSkills, opts.FlatSet)
+	skillsResult := runSkillsAndState(updater, io, latest, opts.Force)

 	if opts.JSON {
 		result := map[string]interface{}{
@@ -313,40 +316,46 @@ func doNpmUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string,
 	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())
 	if skillsResult != nil {
-		fmt.Fprintf(io.ErrOut, "\nUpdating skills ...\n")
+		skillsPM := "npx"
+		if detect.Method == selfupdate.InstallPnpm && detect.PnpmAvailable {
+			skillsPM = "pnpm dlx"
+		}
+		fmt.Fprintf(io.ErrOut, "\nUpdating skills via %s ...\n", skillsPM)
 	}
 	emitSkillsTextHints(io, skillsResult)
 	return nil
 }

-func permissionHint(npmOutput string) string {
-	if strings.Contains(npmOutput, "EACCES") && !isWindows() {
-		return "Permission denied. Try: sudo lark-cli update, or adjust your npm global prefix: https://docs.npmjs.com/resolving-eacces-permissions-errors"
+func permissionHint(pmOutput, pm string) string {
+	if !strings.Contains(pmOutput, "EACCES") || isWindows() {
+		return ""
 	}
-	return ""
+	if pm == "pnpm" {
+		return "Permission denied. Ensure your pnpm global directory is writable — re-run `pnpm setup`, or see https://pnpm.io/pnpm-cli"
+	}
+	return "Permission denied. Try: sudo lark-cli update, or adjust your npm global prefix: https://docs.npmjs.com/resolving-eacces-permissions-errors"
 }

-func verificationFailureHint(updater *selfupdate.Updater, latest string) string {
+func verificationFailureHint(updater *selfupdate.Updater, latest, pm string) string {
 	if updater.CanRestorePreviousVersion() {
 		return "the previous version has been restored"
 	}
+	if pm == "pnpm" {
+		return fmt.Sprintf("automatic rollback is unavailable on this platform; reinstall manually (skills will not be synced): pnpm add -g %s@%s && pnpm dlx skills add larksuite/cli -y -g, or download %s", selfupdate.NpmPackage, latest, releaseURL(latest))
+	}
 	return fmt.Sprintf("automatic rollback is unavailable on this platform; reinstall manually (skills will not be synced): npm install -g %s@%s && npx skills add larksuite/cli -y -g, or download %s", selfupdate.NpmPackage, latest, releaseURL(latest))
 }

-func runSkillsAndState(updater *selfupdate.Updater, io *cmdutil.IOStreams, stateVersion string, force bool, requestedLayout, requestedFlat string, flatSet bool) *skillscheck.SyncResult {
-	layout, flat := resolveSkillsSyncOptions(requestedLayout, requestedFlat, flatSet)
-	layoutExplicit := strings.TrimSpace(requestedLayout) != ""
-	if !force && !layoutExplicit && !flatSet {
-		if existing, existingLayout, ok := skillscheck.ReadSyncedVersionAndLayout(); ok && existingLayout != "" && normalizeVersion(existing) == normalizeVersion(stateVersion) {
+func runSkillsAndState(updater *selfupdate.Updater, io *cmdutil.IOStreams, stateVersion string, force bool) *skillscheck.SyncResult {
+	if !force {
+		if existing, ok := skillscheck.ReadSyncedVersion(); ok && normalizeVersion(existing) == normalizeVersion(stateVersion) {
 			return nil
 		}
 	}
 	result := syncSkills(skillscheck.SyncOptions{
-		Version:    stateVersion,
-		Layout:     layout,
-		FlatSkills: flat,
-		Force:      force,
-		Runner:     updater,
+		Version: stateVersion,
+		Force:   force,
+		Runner:  updater,
 	})
 	if result.Err != nil && strings.Contains(result.Err.Error(), "state not written") {
 		fmt.Fprintf(io.ErrOut, "warning: %v\n", result.Err)
@@ -354,47 +363,6 @@ func runSkillsAndState(updater *selfupdate.Updater, io *cmdutil.IOStreams, state
 	return result
 }

-func validateSkillsLayoutOptions(opts *UpdateOptions) errs.TypedError {
-	if _, ok := skillscheck.NormalizeLayout(opts.SkillsLayout); !ok {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--skills-layout must be one of separate or hybrid").WithParam("--skills-layout")
-	}
-	layout, flat := resolveSkillsSyncOptions(opts.SkillsLayout, opts.FlatSkills, opts.FlatSet)
-	if layout != skillscheck.LayoutHybrid {
-		return nil
-	}
-	for _, skill := range flat {
-		if skill == "lark-shared" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "lark-shared cannot be selected by --flat-skills; it is managed automatically for lark-suite compatibility").WithParam("--flat-skills")
-		}
-	}
-	return nil
-}
-
-func resolveSkillsSyncOptions(requestedLayout, requestedFlat string, flatSet bool) (string, []string) {
-	state, readable, err := skillscheck.ReadState()
-	if err != nil {
-		readable = false
-		state = nil
-	}
-
-	layout := skillscheck.LayoutSeparate
-	if strings.TrimSpace(requestedLayout) != "" {
-		layout, _ = skillscheck.NormalizeLayout(requestedLayout)
-	} else if readable && state != nil {
-		if stateLayout, ok := skillscheck.NormalizeLayout(state.Layout); ok && state.Layout != "" {
-			layout = stateLayout
-		}
-	}
-
-	if flatSet {
-		return layout, skillscheck.ParseFlatSkills(requestedFlat)
-	}
-	if readable && state != nil {
-		return layout, state.FlatSkills
-	}
-	return layout, []string{}
-}
-
 // 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
@@ -441,12 +409,6 @@ func applySkillsStatus(env map[string]interface{}, target string) {
 	if len(state.SkippedDeletedSkills) > 0 {
 		status["skipped_deleted"] = state.SkippedDeletedSkills
 	}
-	if state.Layout != "" {
-		status["layout"] = state.Layout
-	}
-	if len(state.FlatSkills) > 0 {
-		status["flat_skills"] = state.FlatSkills
-	}
 	env["skills_status"] = status
 }

@@ -457,7 +419,6 @@ func applySkillsResult(env map[string]interface{}, r *skillscheck.SyncResult) {
 	case r.Err != nil:
 		env["skills_action"] = "failed"
 		env["skills_warning"] = fmt.Sprintf("skills update failed: %s", r.Err)
-		env["skills_hint"] = skillsFailureHint()
 		env["skills_summary"] = skillsSummary(r)
 	default:
 		env["skills_action"] = "synced"
@@ -471,17 +432,10 @@ func skillsSummary(r *skillscheck.SyncResult) map[string]interface{} {
 		"updated":         len(r.Updated),
 		"added":           len(r.Added),
 		"skipped_deleted": len(r.SkippedDeleted),
-		"layout":          r.Layout,
 	}
 	if len(r.Failed) > 0 {
 		summary["failed"] = r.Failed
 	}
-	if len(r.Collected) > 0 {
-		summary["collected"] = r.Collected
-	}
-	if len(r.Flat) > 0 {
-		summary["flat"] = r.Flat
-	}
 	return summary
 }

@@ -493,17 +447,13 @@ func emitSkillsTextHints(io *cmdutil.IOStreams, r *skillscheck.SyncResult) {
 		if len(r.Failed) > 0 {
 			fmt.Fprintf(io.ErrOut, "  Failed skills: %s\n", strings.Join(r.Failed, ", "))
 		}
-		fmt.Fprintf(io.ErrOut, "  %s\n", skillsFailureHint())
+		fmt.Fprintf(io.ErrOut, "  To retry all official skills: lark-cli update --force\n")
 	case r.Force:
-		fmt.Fprintf(io.ErrOut, "%s Skills updated: restored all %d official skills (%s layout)\n", symOK(), len(r.Official), r.Layout)
+		fmt.Fprintf(io.ErrOut, "%s Skills updated: restored all %d official skills\n", symOK(), len(r.Official))
 	default:
-		fmt.Fprintf(io.ErrOut, "%s Skills updated: %d official, %d updated, %d added, %d skipped because deleted locally (%s layout)\n", symOK(), len(r.Official), len(r.Updated), len(r.Added), len(r.SkippedDeleted), r.Layout)
+		fmt.Fprintf(io.ErrOut, "%s Skills updated: %d official, %d updated, %d added, %d skipped because deleted locally\n", symOK(), len(r.Official), len(r.Updated), len(r.Added), len(r.SkippedDeleted))
 		if len(r.SkippedDeleted) > 0 {
 			fmt.Fprintf(io.ErrOut, "  To restore all official skills: lark-cli update --force\n")
 		}
 	}
 }
-
-func skillsFailureHint() string {
-	return "Retry: lark-cli update --force. To switch to separate top-level skills: lark-cli update --skills-layout separate (this saves layout=separate and clears saved flat_skills)."
-}
--- a/cmd/update/update_test.go
+++ b/cmd/update/update_test.go
@@ -57,6 +57,27 @@ func mockDetectAndNpm(t *testing.T, result selfupdate.DetectResult, npmFn func(s
 	t.Cleanup(func() { newUpdater = origNew })
 }

+// mockDetectAndPnpm mirrors mockDetectAndNpm but wires the pnpm install path
+// and fails the test if the npm install path is invoked.
+func mockDetectAndPnpm(t *testing.T, result selfupdate.DetectResult, pnpmFn func(string) *selfupdate.NpmResult) {
+	t.Helper()
+	origNew := newUpdater
+	newUpdater = func() *selfupdate.Updater {
+		u := selfupdate.New()
+		u.DetectOverride = func() selfupdate.DetectResult { return result }
+		u.PnpmInstallOverride = pnpmFn
+		u.NpmInstallOverride = func(string) *selfupdate.NpmResult {
+			t.Errorf("npm install must not be called for a pnpm install")
+			return &selfupdate.NpmResult{}
+		}
+		u.VerifyOverride = func(string) error { return nil }
+		u.SkillsIndexFetchOverride = successfulSkillsIndexFetch()
+		u.SkillsCommandOverride = successfulSkillsCommand()
+		return u
+	}
+	t.Cleanup(func() { newUpdater = origNew })
+}
+
 func successfulSkillsIndexFetch() func() *selfupdate.NpmResult {
 	return func() *selfupdate.NpmResult {
 		r := &selfupdate.NpmResult{}
@@ -81,6 +102,110 @@ func successfulSkillsCommand() func(args ...string) *selfupdate.NpmResult {
 	}
 }

+func TestUpdatePnpm_JSON(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, stdout, _ := newTestFactory(t)
+	cmd := NewCmdUpdate(f)
+	cmd.SetArgs([]string{"--json"})
+	origFetch := fetchLatest
+	fetchLatest = func() (string, error) { return "2.0.0", nil }
+	defer func() { fetchLatest = origFetch }()
+	origVersion := currentVersion
+	currentVersion = func() string { return "1.0.0" }
+	defer func() { currentVersion = origVersion }()
+	mockDetectAndPnpm(t,
+		selfupdate.DetectResult{Method: selfupdate.InstallPnpm, ResolvedPath: "/x/node_modules/.pnpm/@larksuite+cli@1.0.0/node_modules/@larksuite/cli/bin/lark-cli", PnpmAvailable: true},
+		func(string) *selfupdate.NpmResult { return &selfupdate.NpmResult{} },
+	)
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if out := stdout.String(); !strings.Contains(out, `"action": "updated"`) {
+		t.Errorf("expected updated in output, got: %s", out)
+	}
+}
+
+func TestUpdatePnpm_Human(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, _, stderr := newTestFactory(t)
+	cmd := NewCmdUpdate(f)
+	cmd.SetArgs([]string{})
+	origFetch := fetchLatest
+	fetchLatest = func() (string, error) { return "2.0.0", nil }
+	defer func() { fetchLatest = origFetch }()
+	origVersion := currentVersion
+	currentVersion = func() string { return "1.0.0" }
+	defer func() { currentVersion = origVersion }()
+	mockDetectAndPnpm(t,
+		selfupdate.DetectResult{Method: selfupdate.InstallPnpm, ResolvedPath: "/x/node_modules/.pnpm/@larksuite+cli@1.0.0/node_modules/@larksuite/cli/bin/lark-cli", PnpmAvailable: true},
+		func(string) *selfupdate.NpmResult { return &selfupdate.NpmResult{} },
+	)
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stderr.String()
+	if !strings.Contains(out, "via pnpm") {
+		t.Errorf("expected 'via pnpm' in stderr, got: %s", out)
+	}
+	if !strings.Contains(out, "Updating skills via pnpm dlx ...") {
+		t.Errorf("expected skills sync to report pnpm dlx launcher, got: %s", out)
+	}
+	if !strings.Contains(out, "Successfully updated") {
+		t.Errorf("expected success message, got: %s", out)
+	}
+}
+
+func TestUpdatePnpm_InstallError_JSON(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, stdout, _ := newTestFactory(t)
+	cmd := NewCmdUpdate(f)
+	cmd.SetArgs([]string{"--json"})
+	origFetch := fetchLatest
+	fetchLatest = func() (string, error) { return "2.0.0", nil }
+	defer func() { fetchLatest = origFetch }()
+	origVersion := currentVersion
+	currentVersion = func() string { return "1.0.0" }
+	defer func() { currentVersion = origVersion }()
+	mockDetectAndPnpm(t,
+		selfupdate.DetectResult{Method: selfupdate.InstallPnpm, ResolvedPath: "/x/node_modules/.pnpm/@larksuite+cli@1.0.0/node_modules/@larksuite/cli/bin/lark-cli", PnpmAvailable: true},
+		func(string) *selfupdate.NpmResult { return &selfupdate.NpmResult{Err: errors.New("pnpm boom")} },
+	)
+	err := cmd.Execute()
+	if err == nil {
+		t.Fatal("expected error exit")
+	}
+	if out := stdout.String(); !strings.Contains(out, `"ok": false`) || !strings.Contains(out, "update_error") {
+		t.Errorf("expected failure envelope, got: %s", out)
+	}
+	if out := stdout.String(); !strings.Contains(out, "pnpm install failed") {
+		t.Errorf("expected message to report pnpm as the package manager, got: %s", out)
+	}
+}
+
+func TestUpdatePnpm_Unavailable_ManualFallback(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, _, stderr := newTestFactory(t)
+	cmd := NewCmdUpdate(f)
+	cmd.SetArgs([]string{})
+	origFetch := fetchLatest
+	fetchLatest = func() (string, error) { return "2.0.0", nil }
+	defer func() { fetchLatest = origFetch }()
+	origVersion := currentVersion
+	currentVersion = func() string { return "1.0.0" }
+	defer func() { currentVersion = origVersion }()
+	mockDetect(t, selfupdate.DetectResult{Method: selfupdate.InstallPnpm, ResolvedPath: "/x/node_modules/.pnpm/@larksuite+cli@1.0.0/node_modules/@larksuite/cli/bin/lark-cli", PnpmAvailable: false})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stderr.String()
+	if !strings.Contains(out, "installed via pnpm, but pnpm is not available in PATH") {
+		t.Errorf("expected pnpm manual reason, got: %s", out)
+	}
+	if !strings.Contains(out, "pnpm add -g") {
+		t.Errorf("expected pnpm add -g hint, got: %s", out)
+	}
+}
+
 func TestNormalizeVersion(t *testing.T) {
 	tests := []struct {
 		input string
@@ -266,6 +391,9 @@ func TestUpdateNpm_Human(t *testing.T) {
 	if !strings.Contains(out, "Successfully updated") {
 		t.Errorf("expected success message in stderr, got: %s", out)
 	}
+	if !strings.Contains(out, "Updating skills via npx ...") {
+		t.Errorf("expected skills sync to report npx launcher for npm install, got: %s", out)
+	}
 }

 func TestUpdateForce_JSON(t *testing.T) {
@@ -739,9 +867,9 @@ func TestPermissionHint(t *testing.T) {
 	origOS := currentOS
 	defer func() { currentOS = origOS }()

-	// Linux: EACCES should produce a hint with npm prefix guidance.
+	// Linux + npm: EACCES should produce a hint with npm prefix guidance.
 	currentOS = "linux"
-	hint := permissionHint("EACCES: permission denied, access '/usr/local/lib'")
+	hint := permissionHint("EACCES: permission denied, access '/usr/local/lib'", "npm")
 	if !strings.Contains(hint, "npm global prefix") {
 		t.Errorf("expected npm prefix hint on linux, got: %s", hint)
 	}
@@ -749,16 +877,25 @@ func TestPermissionHint(t *testing.T) {
 		t.Errorf("should not suggest raw sudo npm install, got: %s", hint)
 	}

+	// Linux + pnpm: EACCES should point at pnpm setup, not npm prefix/sudo.
+	pnpmHint := permissionHint("EACCES: permission denied, access '/Users/x/Library/pnpm'", "pnpm")
+	if !strings.Contains(pnpmHint, "pnpm setup") {
+		t.Errorf("expected pnpm setup hint, got: %s", pnpmHint)
+	}
+	if strings.Contains(pnpmHint, "npm global prefix") || strings.Contains(pnpmHint, "sudo") {
+		t.Errorf("pnpm hint must not reference npm prefix or sudo, got: %s", pnpmHint)
+	}
+
 	// Windows: EACCES hint is suppressed (no EACCES on Windows).
 	currentOS = "windows"
-	hint = permissionHint("EACCES: permission denied")
+	hint = permissionHint("EACCES: permission denied", "npm")
 	if hint != "" {
 		t.Errorf("expected empty hint on Windows, got: %s", hint)
 	}

 	// Non-EACCES error: always empty.
 	currentOS = "linux"
-	if got := permissionHint("some other error"); got != "" {
+	if got := permissionHint("some other error", "npm"); got != "" {
 		t.Errorf("expected empty hint for non-EACCES, got: %s", got)
 	}
 }
@@ -996,7 +1133,7 @@ func newTestIO() *cmdutil.IOStreams {

 func TestRunSkillsAndState_DedupHit(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	if err := skillscheck.WriteState(skillscheck.SkillsState{Version: "1.0.21", Layout: skillscheck.LayoutSeparate}); err != nil {
+	if err := skillscheck.WriteState(skillscheck.SkillsState{Version: "1.0.21"}); err != nil {
 		t.Fatal(err)
 	}
 	called := false
@@ -1006,7 +1143,7 @@ func TestRunSkillsAndState_DedupHit(t *testing.T) {
 			return &selfupdate.NpmResult{}
 		},
 	}
-	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false, "", "", false)
+	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false)
 	if got != nil {
 		t.Errorf("runSkillsAndState() = %+v, want nil for dedup hit", got)
 	}
@@ -1015,27 +1152,6 @@ func TestRunSkillsAndState_DedupHit(t *testing.T) {
 	}
 }

-func TestRunSkillsAndState_MissingLayoutDoesNotDedup(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	if err := skillscheck.WriteState(skillscheck.SkillsState{Version: "1.0.21"}); err != nil {
-		t.Fatal(err)
-	}
-	called := false
-	updater := &selfupdate.Updater{
-		SkillsCommandOverride: func(args ...string) *selfupdate.NpmResult {
-			called = true
-			return successfulSkillsCommand()(args...)
-		},
-	}
-	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false, "", "", false)
-	if got == nil || got.Err != nil {
-		t.Fatalf("runSkillsAndState() = %+v, want successful sync when state lacks layout", got)
-	}
-	if !called {
-		t.Error("SkillsCommandOverride not called, want resync when state lacks layout")
-	}
-}
-
 func TestRunSkillsAndState_DedupForceBypass(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	if err := skillscheck.WriteState(skillscheck.SkillsState{Version: "1.0.21"}); err != nil {
@@ -1048,7 +1164,7 @@ func TestRunSkillsAndState_DedupForceBypass(t *testing.T) {
 			return successfulSkillsCommand()(args...)
 		},
 	}
-	got := runSkillsAndState(updater, newTestIO(), "1.0.21", true, "", "", false)
+	got := runSkillsAndState(updater, newTestIO(), "1.0.21", true)
 	if got == nil || got.Err != nil {
 		t.Fatalf("runSkillsAndState(force=true) = %+v, want successful result", got)
 	}
@@ -1060,7 +1176,7 @@ func TestRunSkillsAndState_DedupForceBypass(t *testing.T) {
 func TestRunSkillsAndState_SuccessWritesState(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	updater := &selfupdate.Updater{SkillsCommandOverride: successfulSkillsCommand()}
-	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false, "", "", false)
+	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false)
 	if got == nil || got.Err != nil {
 		t.Fatalf("runSkillsAndState() = %+v, want non-nil with nil Err", got)
 	}
@@ -1071,12 +1187,6 @@ func TestRunSkillsAndState_SuccessWritesState(t *testing.T) {
 	if state.Version != "1.0.21" {
 		t.Errorf("state.Version = %q, want \"1.0.21\"", state.Version)
 	}
-	if state.Layout != skillscheck.LayoutSeparate {
-		t.Errorf("state.Layout = %q, want %q", state.Layout, skillscheck.LayoutSeparate)
-	}
-	if len(state.FlatSkills) != 0 {
-		t.Errorf("state.FlatSkills = %#v, want empty", state.FlatSkills)
-	}
 }

 func TestRunSkillsAndState_FailureKeepsOldState(t *testing.T) {
@@ -1091,7 +1201,7 @@ func TestRunSkillsAndState_FailureKeepsOldState(t *testing.T) {
 			return r
 		},
 	}
-	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false, "", "", false)
+	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false)
 	if got == nil || got.Err == nil {
 		t.Fatalf("runSkillsAndState() = %+v, want non-nil with non-nil Err", got)
 	}
@@ -1104,57 +1214,6 @@ func TestRunSkillsAndState_FailureKeepsOldState(t *testing.T) {
 	}
 }

-func TestResolveSkillsSyncOptions_UsesStateAsFallback(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	if err := skillscheck.WriteState(skillscheck.SkillsState{
-		Version:    "1.0.21",
-		Layout:     skillscheck.LayoutHybrid,
-		FlatSkills: []string{"lark-doc"},
-	}); err != nil {
-		t.Fatal(err)
-	}
-
-	layout, flat := resolveSkillsSyncOptions("", "", false)
-	if layout != skillscheck.LayoutHybrid {
-		t.Fatalf("layout = %q, want %q", layout, skillscheck.LayoutHybrid)
-	}
-	if len(flat) != 1 || flat[0] != "lark-doc" {
-		t.Fatalf("flat = %#v, want [lark-doc]", flat)
-	}
-}
-
-func TestValidateSkillsLayoutOptionsRejectsSuiteMode(t *testing.T) {
-	err := validateSkillsLayoutOptions(&UpdateOptions{SkillsLayout: "suite"})
-	if err == nil {
-		t.Fatal("validateSkillsLayoutOptions() err = nil, want validation error")
-	}
-	var validation *errs.ValidationError
-	if !errors.As(err, &validation) {
-		t.Fatalf("errors.As(err, *ValidationError) = false for %T", err)
-	}
-	if validation.Param != "--skills-layout" {
-		t.Fatalf("validation.Param = %q, want --skills-layout", validation.Param)
-	}
-}
-
-func TestValidateSkillsLayoutOptionsRejectsSharedFlatInHybrid(t *testing.T) {
-	err := validateSkillsLayoutOptions(&UpdateOptions{
-		SkillsLayout: skillscheck.LayoutHybrid,
-		FlatSkills:   "lark-shared",
-		FlatSet:      true,
-	})
-	if err == nil {
-		t.Fatal("validateSkillsLayoutOptions() err = nil, want validation error")
-	}
-	var validation *errs.ValidationError
-	if !errors.As(err, &validation) {
-		t.Fatalf("errors.As(err, *ValidationError) = false for %T", err)
-	}
-	if validation.Param != "--flat-skills" {
-		t.Fatalf("validation.Param = %q, want --flat-skills", validation.Param)
-	}
-}
-
 func TestTruncate(t *testing.T) {
 	long := strings.Repeat("x", 3000)
 	got := selfupdate.Truncate(long, 2000)
@@ -1435,7 +1494,7 @@ func TestRunSkillsAndState_StateWriteFailureWarns(t *testing.T) {
 	t.Cleanup(func() { syncSkills = origSync })

 	f, _, stderr := newTestFactory(t)
-	got := runSkillsAndState(&selfupdate.Updater{}, f.IOStreams, "1.0.21", false, "", "", false)
+	got := runSkillsAndState(&selfupdate.Updater{}, f.IOStreams, "1.0.21", false)
 	if got == nil || got.Err == nil {
 		t.Fatalf("runSkillsAndState() = %+v, want non-nil with write error", got)
 	}
--- a/errs/ERROR_CONTRACT.md
+++ b/errs/ERROR_CONTRACT.md
@@ -72,6 +72,28 @@ other category. `error.type` is `"policy"`, `error.subtype` is one of
 `challenge_required` / `access_denied`, and process exit is `6` via
 `CategoryPolicy`.

+### Success envelope (stdout)
+
+For contrast: success responses render to **stdout** as an
+`output.Envelope` (`internal/output/envelope.go`), exit code `0`:
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": { "guid": "e297d3d0-..." },
+  "meta": { "count": 1 }
+}
+```
+
+Consumers must branch on `ok` (or the process exit code). The success
+envelope has **no top-level `code` or `msg` field** — `code` exists only
+inside `error`, where it is the upstream numeric code (invariant 4).
+Wrappers that follow the raw OpenAPI convention and test `code == 0`
+will misclassify every successful call as a failure, which is
+especially dangerous around write commands (e.g. retrying a create that
+already succeeded).
+
 ## Categories

 | Category | When | Exit | Typed struct |
--- a/internal/cmdutil/secheader.go
+++ b/internal/cmdutil/secheader.go
@@ -6,12 +6,10 @@ package cmdutil
 import (
 	"context"
 	"net/http"
-	"os"
 	"reflect"
 	"runtime/debug"
 	"strings"
 	"sync"
-	"unicode"

 	"github.com/larksuite/cli/extension/credential"
 	"github.com/larksuite/cli/extension/fileio"
@@ -40,8 +38,6 @@ const (
 	BuildKindUnknown  = "unknown"

 	officialModulePath = "github.com/larksuite/cli"
-
-	agentTraceMaxLen = 1024
 )

 // UserAgentValue returns the User-Agent value: "lark-cli/{version}".
@@ -49,25 +45,6 @@ func UserAgentValue() string {
 	return SourceValue + "/" + build.Version
 }

-// AgentTraceValue returns a header-safe value from the
-// LARKSUITE_CLI_AGENT_TRACE environment variable. It trims
-// surrounding whitespace, rejects values containing any Unicode
-// control character or exceeding agentTraceMaxLen, and returns ""
-// for any invalid or empty value. Callers can use the result
-// directly in HTTP headers without further sanitisation.
-func AgentTraceValue() string {
-	v := strings.TrimSpace(os.Getenv(envvars.CliAgentTrace))
-	if v == "" || len(v) > agentTraceMaxLen {
-		return ""
-	}
-	for _, r := range v {
-		if unicode.IsControl(r) {
-			return ""
-		}
-	}
-	return v
-}
-
 // BaseSecurityHeaders returns headers that every request must carry.
 func BaseSecurityHeaders() http.Header {
 	h := make(http.Header)
@@ -75,7 +52,7 @@ func BaseSecurityHeaders() http.Header {
 	h.Set(HeaderVersion, build.Version)
 	h.Set(HeaderBuild, DetectBuildKind())
 	h.Set(HeaderUserAgent, UserAgentValue())
-	if v := AgentTraceValue(); v != "" {
+	if v := envvars.AgentTrace(); v != "" {
 		h.Set(HeaderAgentTrace, v)
 	}
 	return h
--- a/internal/cmdutil/secheader_test.go
+++ b/internal/cmdutil/secheader_test.go
@@ -6,7 +6,6 @@ package cmdutil
 import (
 	"context"
 	"net/http"
-	"strings"
 	"testing"

 	"github.com/larksuite/cli/extension/credential"
@@ -264,88 +263,9 @@ func TestBaseSecurityHeaders_AllRequiredHeaders(t *testing.T) {
 }

 // ---------------------------------------------------------------------------
-// AgentTraceValue / HeaderAgentTrace
+// HeaderAgentTrace injection (via BaseSecurityHeaders)
 // ---------------------------------------------------------------------------

-func TestAgentTraceValue_EmptyWhenEnvUnset(t *testing.T) {
-	t.Setenv(envvars.CliAgentTrace, "")
-	if got := AgentTraceValue(); got != "" {
-		t.Fatalf("AgentTraceValue() = %q, want empty when env unset", got)
-	}
-}
-
-func TestAgentTraceValue_ReturnsCleanValue(t *testing.T) {
-	t.Setenv(envvars.CliAgentTrace, "trace-abc-123")
-	if got := AgentTraceValue(); got != "trace-abc-123" {
-		t.Fatalf("AgentTraceValue() = %q, want %q", got, "trace-abc-123")
-	}
-}
-
-func TestAgentTraceValue_TrimsWhitespace(t *testing.T) {
-	t.Setenv(envvars.CliAgentTrace, "  trace-trim  ")
-	if got := AgentTraceValue(); got != "trace-trim" {
-		t.Fatalf("AgentTraceValue() = %q, want %q (whitespace trimmed)", got, "trace-trim")
-	}
-}
-
-func TestAgentTraceValue_OnlyWhitespace_ReturnsEmpty(t *testing.T) {
-	t.Setenv(envvars.CliAgentTrace, "   ")
-	if got := AgentTraceValue(); got != "" {
-		t.Fatalf("AgentTraceValue() = %q, want empty for whitespace-only value", got)
-	}
-}
-
-func TestAgentTraceValue_RejectsCRLF(t *testing.T) {
-	t.Setenv(envvars.CliAgentTrace, "val\r\nX-Evil: attack")
-	if got := AgentTraceValue(); got != "" {
-		t.Fatalf("AgentTraceValue() = %q, want empty for CR/LF value", got)
-	}
-}
-
-func TestAgentTraceValue_RejectsLF(t *testing.T) {
-	t.Setenv(envvars.CliAgentTrace, "val\nX-Evil: attack")
-	if got := AgentTraceValue(); got != "" {
-		t.Fatalf("AgentTraceValue() = %q, want empty for LF value", got)
-	}
-}
-
-func TestAgentTraceValue_RejectsTab(t *testing.T) {
-	t.Setenv(envvars.CliAgentTrace, "val\tinjected")
-	if got := AgentTraceValue(); got != "" {
-		t.Fatalf("AgentTraceValue() = %q, want empty for tab value", got)
-	}
-}
-
-func TestAgentTraceValue_RejectsControlChar(t *testing.T) {
-	t.Setenv(envvars.CliAgentTrace, "val\x01injected")
-	if got := AgentTraceValue(); got != "" {
-		t.Fatalf("AgentTraceValue() = %q, want empty for control char value", got)
-	}
-}
-
-func TestAgentTraceValue_RejectsDEL(t *testing.T) {
-	t.Setenv(envvars.CliAgentTrace, "val\x7finjected")
-	if got := AgentTraceValue(); got != "" {
-		t.Fatalf("AgentTraceValue() = %q, want empty for DEL value", got)
-	}
-}
-
-func TestAgentTraceValue_RejectsOverlongValue(t *testing.T) {
-	longVal := strings.Repeat("a", agentTraceMaxLen+1)
-	t.Setenv(envvars.CliAgentTrace, longVal)
-	if got := AgentTraceValue(); got != "" {
-		t.Fatalf("AgentTraceValue() returned non-empty for %d-byte value (max %d)", len(longVal), agentTraceMaxLen)
-	}
-}
-
-func TestAgentTraceValue_AcceptsMaxLengthValue(t *testing.T) {
-	val := strings.Repeat("a", agentTraceMaxLen)
-	t.Setenv(envvars.CliAgentTrace, val)
-	if got := AgentTraceValue(); got != val {
-		t.Fatalf("AgentTraceValue() = %q, want %d-byte value accepted", got, agentTraceMaxLen)
-	}
-}
-
 func TestBaseSecurityHeaders_NoAgentTraceHeaderWhenEnvUnset(t *testing.T) {
 	t.Setenv(envvars.CliAgentTrace, "")
 	h := BaseSecurityHeaders()
--- a/internal/envvars/envvars.go
+++ b/internal/envvars/envvars.go
@@ -19,6 +19,7 @@ const (
 	// Content safety scanning mode
 	CliContentSafetyMode = "LARKSUITE_CLI_CONTENT_SAFETY_MODE"

+	CliAgentName  = "LARKSUITE_CLI_AGENT_NAME"
 	CliAgentTrace = "LARKSUITE_CLI_AGENT_TRACE"

 	CliProxyEnable  = "LARKSUITE_CLI_PROXY_ENABLE"
--- a/internal/envvars/read.go
+++ b/internal/envvars/read.go
@@ -0,0 +1,36 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package envvars
+
+import (
+	"os"
+	"strings"
+	"unicode"
+)
+
+const (
+	agentNameMaxLen  = 128
+	agentTraceMaxLen = 1024
+)
+
+func AgentName() string {
+	return sanitizeSingleLine(os.Getenv(CliAgentName), agentNameMaxLen)
+}
+
+func AgentTrace() string {
+	return sanitizeSingleLine(os.Getenv(CliAgentTrace), agentTraceMaxLen)
+}
+
+func sanitizeSingleLine(raw string, maxLen int) string {
+	v := strings.TrimSpace(raw)
+	if v == "" || len(v) > maxLen {
+		return ""
+	}
+	for _, r := range v {
+		if unicode.IsControl(r) {
+			return ""
+		}
+	}
+	return v
+}
--- a/internal/envvars/read_test.go
+++ b/internal/envvars/read_test.go
@@ -0,0 +1,131 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package envvars
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestAgentName_EmptyWhenEnvUnset(t *testing.T) {
+	t.Setenv(CliAgentName, "")
+	if got := AgentName(); got != "" {
+		t.Fatalf("AgentName() = %q, want empty when env unset", got)
+	}
+}
+
+func TestAgentName_ReturnsCleanValue(t *testing.T) {
+	t.Setenv(CliAgentName, "claude-code")
+	if got := AgentName(); got != "claude-code" {
+		t.Fatalf("AgentName() = %q, want %q", got, "claude-code")
+	}
+}
+
+func TestAgentName_TrimsWhitespace(t *testing.T) {
+	t.Setenv(CliAgentName, "  cursor  ")
+	if got := AgentName(); got != "cursor" {
+		t.Fatalf("AgentName() = %q, want %q (whitespace trimmed)", got, "cursor")
+	}
+}
+
+func TestAgentName_RejectsCRLFInjection(t *testing.T) {
+	t.Setenv(CliAgentName, "agent\r\nX-Evil: attack")
+	if got := AgentName(); got != "" {
+		t.Fatalf("AgentName() = %q, want empty for CR/LF value", got)
+	}
+}
+
+func TestAgentName_RejectsControlChar(t *testing.T) {
+	t.Setenv(CliAgentName, "agent\x01injected")
+	if got := AgentName(); got != "" {
+		t.Fatalf("AgentName() = %q, want empty for control char value", got)
+	}
+}
+
+func TestAgentName_RejectsOverlongValue(t *testing.T) {
+	longVal := strings.Repeat("a", agentNameMaxLen+1)
+	t.Setenv(CliAgentName, longVal)
+	if got := AgentName(); got != "" {
+		t.Fatalf("AgentName() returned non-empty for %d-byte value (max %d)", len(longVal), agentNameMaxLen)
+	}
+}
+
+func TestAgentTrace_EmptyWhenEnvUnset(t *testing.T) {
+	t.Setenv(CliAgentTrace, "")
+	if got := AgentTrace(); got != "" {
+		t.Fatalf("AgentTrace() = %q, want empty when env unset", got)
+	}
+}
+
+func TestAgentTrace_ReturnsCleanValue(t *testing.T) {
+	t.Setenv(CliAgentTrace, "trace-abc-123")
+	if got := AgentTrace(); got != "trace-abc-123" {
+		t.Fatalf("AgentTrace() = %q, want %q", got, "trace-abc-123")
+	}
+}
+
+func TestAgentTrace_TrimsWhitespace(t *testing.T) {
+	t.Setenv(CliAgentTrace, "  trace-trim  ")
+	if got := AgentTrace(); got != "trace-trim" {
+		t.Fatalf("AgentTrace() = %q, want %q (whitespace trimmed)", got, "trace-trim")
+	}
+}
+
+func TestAgentTrace_OnlyWhitespace_ReturnsEmpty(t *testing.T) {
+	t.Setenv(CliAgentTrace, "   ")
+	if got := AgentTrace(); got != "" {
+		t.Fatalf("AgentTrace() = %q, want empty for whitespace-only value", got)
+	}
+}
+
+func TestAgentTrace_RejectsCRLF(t *testing.T) {
+	t.Setenv(CliAgentTrace, "val\r\nX-Evil: attack")
+	if got := AgentTrace(); got != "" {
+		t.Fatalf("AgentTrace() = %q, want empty for CR/LF value", got)
+	}
+}
+
+func TestAgentTrace_RejectsLF(t *testing.T) {
+	t.Setenv(CliAgentTrace, "val\nX-Evil: attack")
+	if got := AgentTrace(); got != "" {
+		t.Fatalf("AgentTrace() = %q, want empty for LF value", got)
+	}
+}
+
+func TestAgentTrace_RejectsTab(t *testing.T) {
+	t.Setenv(CliAgentTrace, "val\tinjected")
+	if got := AgentTrace(); got != "" {
+		t.Fatalf("AgentTrace() = %q, want empty for tab value", got)
+	}
+}
+
+func TestAgentTrace_RejectsControlChar(t *testing.T) {
+	t.Setenv(CliAgentTrace, "val\x01injected")
+	if got := AgentTrace(); got != "" {
+		t.Fatalf("AgentTrace() = %q, want empty for control char value", got)
+	}
+}
+
+func TestAgentTrace_RejectsDEL(t *testing.T) {
+	t.Setenv(CliAgentTrace, "val\x7finjected")
+	if got := AgentTrace(); got != "" {
+		t.Fatalf("AgentTrace() = %q, want empty for DEL value", got)
+	}
+}
+
+func TestAgentTrace_RejectsOverlongValue(t *testing.T) {
+	longVal := strings.Repeat("a", agentTraceMaxLen+1)
+	t.Setenv(CliAgentTrace, longVal)
+	if got := AgentTrace(); got != "" {
+		t.Fatalf("AgentTrace() returned non-empty for %d-byte value (max %d)", len(longVal), agentTraceMaxLen)
+	}
+}
+
+func TestAgentTrace_AcceptsMaxLengthValue(t *testing.T) {
+	val := strings.Repeat("a", agentTraceMaxLen)
+	t.Setenv(CliAgentTrace, val)
+	if got := AgentTrace(); got != val {
+		t.Fatalf("AgentTrace() = %q, want %d-byte value accepted", got, agentTraceMaxLen)
+	}
+}
--- a/internal/selfupdate/updater.go
+++ b/internal/selfupdate/updater.go
@@ -32,6 +32,7 @@ type InstallMethod int

 const (
 	InstallNpm InstallMethod = iota
+	InstallPnpm
 	InstallManual
 )

@@ -49,28 +50,36 @@ const (
 var (
 	skillsIndexFetchTimeout = 10 * time.Second
 	officialSkillsIndexURL  = "https://open.feishu.cn/.well-known/skills/index.json"
-	isolatedSkillsSourceURL = "https://open.feishu.cn/lark-cli/isolated-skills"
-	isolatedSkillsFallback  = "larksuite/cli/isolated-skills"
 )

 // DetectResult holds installation detection results.
 type DetectResult struct {
-	Method       InstallMethod
-	ResolvedPath string
-	NpmAvailable bool
+	Method        InstallMethod
+	ResolvedPath  string
+	NpmAvailable  bool
+	PnpmAvailable bool
 }

 // CanAutoUpdate returns true if the CLI can update itself automatically.
 func (d DetectResult) CanAutoUpdate() bool {
-	return d.Method == InstallNpm && d.NpmAvailable
+	switch d.Method {
+	case InstallNpm:
+		return d.NpmAvailable
+	case InstallPnpm:
+		return d.PnpmAvailable
+	}
+	return false
 }

 // ManualReason returns a human-readable explanation of why auto-update is unavailable.
 func (d DetectResult) ManualReason() string {
-	if d.Method == InstallNpm && !d.NpmAvailable {
+	switch {
+	case d.Method == InstallNpm && !d.NpmAvailable:
 		return "installed via npm, but npm is not available in PATH"
+	case d.Method == InstallPnpm && !d.PnpmAvailable:
+		return "installed via pnpm, but pnpm is not available in PATH"
 	}
-	return "not installed via npm"
+	return "not installed via npm or pnpm"
 }

 // NpmResult holds the result of an npm install or skills update execution.
@@ -94,6 +103,7 @@ func (r *NpmResult) CombinedOutput() string {
 type Updater struct {
 	DetectOverride           func() DetectResult
 	NpmInstallOverride       func(version string) *NpmResult
+	PnpmInstallOverride      func(version string) *NpmResult
 	SkillsIndexFetchOverride func() *NpmResult
 	SkillsCommandOverride    func(args ...string) *NpmResult
 	VerifyOverride           func(expectedVersion string) error
@@ -103,17 +113,38 @@ type Updater struct {
 	// running binary is successfully renamed to .old. Used by
 	// CanRestorePreviousVersion to report whether rollback is possible.
 	backupCreated bool
+
+	// detectCache memoizes the first real DetectInstallMethod result. How this
+	// binary was installed cannot change during a single process, so caching is
+	// the correct semantics — and it is required for correctness: the update
+	// flow mutates the install (pnpm add -g / npm install -g) before syncing
+	// skills, so a re-detection at skills time could resolve a now-stale
+	// os.Executable path and misclassify. Seeded pre-update by the first call
+	// (updateRun), it keeps the post-update skills launcher consistent with the
+	// launcher reported to the user. Not goroutine-safe; the update flow is
+	// sequential.
+	detectCache *DetectResult
 }

 // New creates an Updater with default (real) behavior.
 func New() *Updater { return &Updater{} }

-// DetectInstallMethod determines how the CLI was installed and whether
-// npm is available for auto-update.
+// DetectInstallMethod determines how the CLI was installed and whether the
+// owning package manager is available for auto-update.
 func (u *Updater) DetectInstallMethod() DetectResult {
 	if u.DetectOverride != nil {
 		return u.DetectOverride()
 	}
+	if u.detectCache != nil {
+		return *u.detectCache
+	}
+	result := u.detectInstallMethod()
+	u.detectCache = &result
+	return result
+}
+
+// detectInstallMethod performs the real (uncached) detection.
+func (u *Updater) detectInstallMethod() DetectResult {
 	exe, err := vfs.Executable()
 	if err != nil {
 		return DetectResult{Method: InstallManual}
@@ -122,24 +153,54 @@ func (u *Updater) DetectInstallMethod() DetectResult {
 	if err != nil {
 		return DetectResult{Method: InstallManual, ResolvedPath: exe}
 	}
+	_, npmErr := exec.LookPath("npm")
+	_, pnpmErr := exec.LookPath("pnpm")
+	return detectFromResolved(resolved, npmErr == nil, pnpmErr == nil)
+}

+// detectFromResolved classifies the resolved binary path into an install
+// method and records package-manager availability. Split out from
+// DetectInstallMethod so the classification is unit-testable without touching
+// the filesystem or PATH.
+func detectFromResolved(resolved string, npmOnPath, pnpmOnPath bool) DetectResult {
 	method := InstallManual
 	if strings.Contains(resolved, "node_modules") {
-		method = InstallNpm
-	}
-
-	npmAvailable := false
-	if method == InstallNpm {
-		if _, err := exec.LookPath("npm"); err == nil {
-			npmAvailable = true
+		if containsPnpmMarker(resolved) {
+			method = InstallPnpm
+		} else {
+			method = InstallNpm
 		}
 	}
-
-	return DetectResult{
-		Method:       method,
-		ResolvedPath: resolved,
-		NpmAvailable: npmAvailable,
+	d := DetectResult{Method: method, ResolvedPath: resolved}
+	switch method {
+	case InstallNpm:
+		d.NpmAvailable = npmOnPath
+	case InstallPnpm:
+		d.PnpmAvailable = pnpmOnPath
 	}
+	return d
+}
+
+// containsPnpmMarker reports whether the resolved binary path belongs to a
+// pnpm-managed install. pnpm exposes two layouts: the classic virtual store
+// (a ".pnpm" directory segment) and the global content-addressable store,
+// whose resolved path runs through pnpm's home directory (e.g.
+// "~/Library/pnpm/store/v11/links/...") — a "pnpm" segment immediately
+// followed by "store". Matching only these two shapes (rather than any bare
+// "pnpm" segment) avoids misclassifying an npm install that merely lives under
+// a directory named "pnpm". Windows separators are normalized to "/" so the
+// classification is OS-independent and unit-testable anywhere.
+func containsPnpmMarker(p string) bool {
+	parts := strings.Split(strings.ReplaceAll(p, `\`, "/"), "/")
+	for i, part := range parts {
+		if part == ".pnpm" {
+			return true
+		}
+		if part == "pnpm" && i+1 < len(parts) && parts[i+1] == "store" {
+			return true
+		}
+	}
+	return false
 }

 // RunNpmInstall executes npm install -g @larksuite/cli@<version>.
@@ -165,6 +226,29 @@ func (u *Updater) RunNpmInstall(version string) *NpmResult {
 	return r
 }

+// RunPnpmInstall executes pnpm add -g @larksuite/cli@<version>.
+func (u *Updater) RunPnpmInstall(version string) *NpmResult {
+	if u.PnpmInstallOverride != nil {
+		return u.PnpmInstallOverride(version)
+	}
+	r := &NpmResult{}
+	pnpmPath, err := exec.LookPath("pnpm")
+	if err != nil {
+		r.Err = fmt.Errorf("pnpm not found in PATH: %w", err)
+		return r
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), npmInstallTimeout)
+	defer cancel()
+	cmd := exec.CommandContext(ctx, pnpmPath, "add", "-g", NpmPackage+"@"+version)
+	cmd.Stdout = &r.Stdout
+	cmd.Stderr = &r.Stderr
+	r.Err = cmd.Run()
+	if ctx.Err() == context.DeadlineExceeded {
+		r.Err = fmt.Errorf("pnpm install timed out after %s", npmInstallTimeout)
+	}
+	return r
+}
+
 func (u *Updater) ListOfficialSkillsIndex() *NpmResult {
 	if u.SkillsIndexFetchOverride != nil {
 		return u.SkillsIndexFetchOverride()
@@ -244,14 +328,6 @@ func (u *Updater) InstallAllSkills() *NpmResult {
 	return r
 }

-func (u *Updater) InstallSuiteSkill() *NpmResult {
-	r := u.runSkillsInstall(isolatedSkillsSourceURL, []string{"lark-suite"})
-	if r.Err != nil {
-		r = u.runSkillsInstall(isolatedSkillsFallback, []string{"lark-suite"})
-	}
-	return r
-}
-
 func (u *Updater) runSkillsAdd(source string) *NpmResult {
 	return u.runSkillsCommand("-y", "skills", "add", source, "-g", "-y")
 }
@@ -271,19 +347,40 @@ func (u *Updater) runSkillsInstall(source string, nameList []string) *NpmResult
 	return u.runSkillsCommand(args...)
 }

+// skillsInvocation decides how to launch the `skills` CLI. When the lark-cli
+// itself was installed via pnpm and pnpm is available, it uses `pnpm dlx` so
+// pnpm-only environments (pnpm's standalone installer bundles Node without
+// putting npm/npx on PATH) can still sync skills after a self-update.
+// Otherwise it uses `npx`. The npx auto-confirm flag "-y", when present as the
+// leading arg, maps to `pnpm dlx`'s default non-interactive behavior and is
+// dropped for the pnpm launcher. Kept pure (no exec/PATH access) so the
+// launcher selection is unit-testable on any platform.
+func skillsInvocation(method InstallMethod, pnpmAvailable bool, args []string) (launcher string, rest []string) {
+	if method == InstallPnpm && pnpmAvailable {
+		r := args
+		if len(r) > 0 && r[0] == "-y" {
+			r = r[1:]
+		}
+		return "pnpm", append([]string{"dlx"}, r...)
+	}
+	return "npx", args
+}
+
 func (u *Updater) runSkillsCommand(args ...string) *NpmResult {
 	if u.SkillsCommandOverride != nil {
 		return u.SkillsCommandOverride(args...)
 	}
 	r := &NpmResult{}
-	npxPath, err := exec.LookPath("npx")
+	det := u.DetectInstallMethod()
+	launcher, cmdArgs := skillsInvocation(det.Method, det.PnpmAvailable, args)
+	binPath, err := exec.LookPath(launcher)
 	if err != nil {
-		r.Err = fmt.Errorf("npx not found in PATH: %w", err)
+		r.Err = fmt.Errorf("%s not found in PATH: %w", launcher, err)
 		return r
 	}
 	ctx, cancel := context.WithTimeout(context.Background(), skillsUpdateTimeout)
 	defer cancel()
-	cmd := exec.CommandContext(ctx, npxPath, args...)
+	cmd := exec.CommandContext(ctx, binPath, cmdArgs...)
 	cmd.Stdout = &r.Stdout
 	cmd.Stderr = &r.Stderr
 	r.Err = cmd.Run()
--- a/internal/selfupdate/updater_test.go
+++ b/internal/selfupdate/updater_test.go
@@ -208,13 +208,6 @@ func TestSkillsCommandsUseExpectedArgs(t *testing.T) {
 			},
 			want: "-y skills add https://open.feishu.cn -s lark-mail -g -y",
 		},
-		{
-			name: "install isolated suite skill",
-			run: func(u *Updater) *NpmResult {
-				return u.runSkillsInstall(isolatedSkillsSourceURL, []string{"lark-suite"})
-			},
-			want: "-y skills add https://open.feishu.cn/lark-cli/isolated-skills -s lark-suite -g -y",
-		},
 	}

 	for _, tt := range tests {
@@ -245,34 +238,6 @@ func TestSkillsCommandsUseExpectedArgs(t *testing.T) {
 	}
 }

-func TestInstallSuiteSkillFallsBackToIsolatedGitHubSource(t *testing.T) {
-	called := []string{}
-	u := &Updater{
-		SkillsCommandOverride: func(args ...string) *NpmResult {
-			called = append(called, strings.Join(args, " "))
-			r := &NpmResult{}
-			if strings.Contains(strings.Join(args, " "), isolatedSkillsSourceURL) {
-				r.Err = fmt.Errorf("isolated source unavailable")
-			}
-			return r
-		},
-	}
-
-	result := u.InstallSuiteSkill()
-	if result.Err != nil {
-		t.Fatalf("InstallSuiteSkill() err = %v, want nil", result.Err)
-	}
-	if len(called) != 2 {
-		t.Fatalf("calls = %#v, want primary and fallback", called)
-	}
-	if !strings.Contains(called[0], isolatedSkillsSourceURL) {
-		t.Fatalf("primary call = %q, want isolated source", called[0])
-	}
-	if !strings.Contains(called[1], isolatedSkillsFallback) {
-		t.Fatalf("fallback call = %q, want isolated GitHub fallback", called[1])
-	}
-}
-
 func TestListOfficialSkillsIndexSuccess(t *testing.T) {
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		fmt.Fprint(w, `{"skills":[{"name":"lark-calendar"}]}`)
@@ -406,3 +371,147 @@ func TestListOfficialSkillsFallsBack(t *testing.T) {
 		t.Fatalf("fallback call = %q, want larksuite/cli --list", called[1])
 	}
 }
+
+func TestContainsPnpmMarker(t *testing.T) {
+	cases := []struct {
+		path string
+		want bool
+	}{
+		// Classic virtual-store layout (.pnpm segment).
+		{"/Users/x/Library/pnpm/global/5/node_modules/.pnpm/@larksuite+cli@1.0.44/node_modules/@larksuite/cli/bin/lark-cli", true},
+		{`C:\Users\x\AppData\Local\pnpm\global\5\node_modules\.pnpm\@larksuite+cli@1.0.44\node_modules\@larksuite\cli\bin\lark-cli.exe`, true},
+		// Global content-addressable store layout (pnpm 11): resolved path runs
+		// through the pnpm home store, a "pnpm" segment with no ".pnpm".
+		{"/Users/x/Library/pnpm/store/v11/links/@larksuite/cli/1.0.59/abc123/node_modules/@larksuite/cli/bin/lark-cli", true},
+		{"/home/x/.local/share/pnpm/store/v10/@larksuite/cli/node_modules/@larksuite/cli/bin/lark-cli", true},
+		{`C:\Users\x\AppData\Local\pnpm\store\v11\links\@larksuite\cli\node_modules\@larksuite\cli\bin\lark-cli.exe`, true},
+		// npm and non-package installs — no pnpm/.pnpm segment.
+		{"/usr/local/lib/node_modules/@larksuite/cli/bin/lark-cli", false},
+		{"/usr/local/bin/lark-cli", false},
+		// Substrings that must NOT match: segment must be exactly .pnpm, or
+		// "pnpm" immediately followed by "store".
+		{"/opt/homebrew/.pnpmfoo/node_modules/@larksuite/cli/bin/lark-cli", false},
+		{"/opt/pnpmfoo/node_modules/@larksuite/cli/bin/lark-cli", false},
+		// A bare "pnpm" directory NOT followed by "store" (e.g. an npm install
+		// living under a dir named pnpm) must not be misclassified as pnpm.
+		{"/opt/pnpm/lib/node_modules/@larksuite/cli/bin/lark-cli", false},
+	}
+	for _, c := range cases {
+		if got := containsPnpmMarker(c.path); got != c.want {
+			t.Errorf("containsPnpmMarker(%q) = %v, want %v", c.path, got, c.want)
+		}
+	}
+}
+
+func TestDetectInstallMethod_Pnpm(t *testing.T) {
+	u := &Updater{DetectOverride: nil}
+	u.DetectOverride = func() DetectResult {
+		// Exercise the real classification by feeding a resolved path via a small shim.
+		return detectFromResolved("/x/node_modules/.pnpm/@larksuite+cli@1.0.44/node_modules/@larksuite/cli/bin/lark-cli", true, true)
+	}
+	got := u.DetectInstallMethod()
+	if got.Method != InstallPnpm {
+		t.Errorf("Method = %v, want InstallPnpm", got.Method)
+	}
+	if !got.PnpmAvailable {
+		t.Errorf("PnpmAvailable = false, want true")
+	}
+}
+
+func TestDetectInstallMethod_NpmVsManual(t *testing.T) {
+	if m := detectFromResolved("/usr/local/lib/node_modules/@larksuite/cli/bin/lark-cli", true, false).Method; m != InstallNpm {
+		t.Errorf("npm path Method = %v, want InstallNpm", m)
+	}
+	if m := detectFromResolved("/usr/local/bin/lark-cli", false, false).Method; m != InstallManual {
+		t.Errorf("manual path Method = %v, want InstallManual", m)
+	}
+}
+
+func TestCanAutoUpdate_Pnpm(t *testing.T) {
+	if !(DetectResult{Method: InstallPnpm, PnpmAvailable: true}).CanAutoUpdate() {
+		t.Error("pnpm available should CanAutoUpdate")
+	}
+	if (DetectResult{Method: InstallPnpm, PnpmAvailable: false}).CanAutoUpdate() {
+		t.Error("pnpm unavailable should not CanAutoUpdate")
+	}
+}
+
+func TestManualReason_Pnpm(t *testing.T) {
+	if got := (DetectResult{Method: InstallPnpm, NpmAvailable: false, PnpmAvailable: false}).ManualReason(); got != "installed via pnpm, but pnpm is not available in PATH" {
+		t.Errorf("pnpm reason = %q", got)
+	}
+	if got := (DetectResult{Method: InstallManual}).ManualReason(); got != "not installed via npm or pnpm" {
+		t.Errorf("manual reason = %q", got)
+	}
+}
+
+func TestRunPnpmInstall_Override(t *testing.T) {
+	u := &Updater{PnpmInstallOverride: func(version string) *NpmResult {
+		r := &NpmResult{}
+		r.Stdout.WriteString("added @larksuite/cli@" + version)
+		return r
+	}}
+	got := u.RunPnpmInstall("2.0.0")
+	if got.Err != nil {
+		t.Fatalf("unexpected err: %v", got.Err)
+	}
+	if !strings.Contains(got.CombinedOutput(), "2.0.0") {
+		t.Errorf("output = %q, want version echoed", got.CombinedOutput())
+	}
+}
+
+func TestRunPnpmInstall_Error(t *testing.T) {
+	wantErr := errors.New("boom")
+	u := &Updater{PnpmInstallOverride: func(string) *NpmResult { return &NpmResult{Err: wantErr} }}
+	if got := u.RunPnpmInstall("2.0.0"); !errors.Is(got.Err, wantErr) {
+		t.Errorf("err = %v, want %v", got.Err, wantErr)
+	}
+}
+
+func TestSkillsInvocation(t *testing.T) {
+	addArgs := []string{"-y", "skills", "add", "https://open.feishu.cn", "-g", "-y"}
+	cases := []struct {
+		name          string
+		method        InstallMethod
+		pnpmAvailable bool
+		args          []string
+		wantLauncher  string
+		wantRest      []string
+	}{
+		{"pnpm install + pnpm available → pnpm dlx, drop leading -y", InstallPnpm, true, addArgs,
+			"pnpm", []string{"dlx", "skills", "add", "https://open.feishu.cn", "-g", "-y"}},
+		{"pnpm install but pnpm unavailable → npx unchanged", InstallPnpm, false, addArgs,
+			"npx", addArgs},
+		{"npm install → npx unchanged", InstallNpm, false, addArgs,
+			"npx", addArgs},
+		{"manual install → npx unchanged", InstallManual, false, []string{"-y", "skills", "ls", "-g"},
+			"npx", []string{"-y", "skills", "ls", "-g"}},
+		{"pnpm without a leading -y → prepend dlx only", InstallPnpm, true, []string{"skills", "ls", "-g"},
+			"pnpm", []string{"dlx", "skills", "ls", "-g"}},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			gotLauncher, gotRest := skillsInvocation(c.method, c.pnpmAvailable, c.args)
+			if gotLauncher != c.wantLauncher {
+				t.Errorf("launcher = %q, want %q", gotLauncher, c.wantLauncher)
+			}
+			if strings.Join(gotRest, " ") != strings.Join(c.wantRest, " ") {
+				t.Errorf("rest = %v, want %v", gotRest, c.wantRest)
+			}
+		})
+	}
+}
+
+// TestDetectInstallMethod_Caches locks the fix for the post-update re-detection
+// hazard: DetectInstallMethod must return the first (pre-update) detection on
+// subsequent calls, so the skills launcher chosen after the binary is replaced
+// stays consistent with what was detected — and reported — before the update.
+func TestDetectInstallMethod_Caches(t *testing.T) {
+	u := New()
+	cached := DetectResult{Method: InstallPnpm, PnpmAvailable: true, ResolvedPath: "/x/pnpm/store/v11/links/@larksuite/cli/1.0.0/node_modules/@larksuite/cli/bin/lark-cli"}
+	u.detectCache = &cached
+	got := u.DetectInstallMethod()
+	if got.Method != InstallPnpm || !got.PnpmAvailable {
+		t.Errorf("expected cached pnpm result to be returned, got %+v", got)
+	}
+}
--- a/internal/skillscheck/layout.go
+++ b/internal/skillscheck/layout.go
@@ -1,374 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package skillscheck
-
-import (
-	"encoding/json"
-	"fmt"
-	"io"
-	"os"
-	"path/filepath"
-	"sort"
-	"strings"
-)
-
-const (
-	LayoutSeparate = "separate"
-	LayoutHybrid   = "hybrid"
-
-	suiteSkillName         = "lark-suite"
-	sharedSkillName        = "lark-shared"
-	suiteRoutesPlaceholder = "<!-- LARK_SUITE_ROUTES -->"
-)
-
-type GlobalSkillInfo struct {
-	Name string
-	Path string
-}
-
-func NormalizeLayout(layout string) (string, bool) {
-	switch strings.TrimSpace(layout) {
-	case "", LayoutSeparate:
-		return LayoutSeparate, true
-	case LayoutHybrid:
-		return LayoutHybrid, true
-	default:
-		return "", false
-	}
-}
-
-func ParseFlatSkills(value string) []string {
-	seen := map[string]bool{}
-	for _, part := range strings.Split(value, ",") {
-		name := strings.TrimSpace(part)
-		if name != "" {
-			seen[name] = true
-		}
-	}
-	return sortedKeys(seen)
-}
-
-func ParseGlobalSkillInfosJSON(text string) []GlobalSkillInfo {
-	infos, _ := parseGlobalSkillInfosJSON(text)
-	return infos
-}
-
-func parseGlobalSkillInfosJSON(text string) ([]GlobalSkillInfo, bool) {
-	type globalSkill struct {
-		Name string `json:"name"`
-		Path string `json:"path"`
-	}
-
-	var skills []globalSkill
-	if err := json.Unmarshal([]byte(text), &skills); err != nil {
-		return nil, false
-	}
-
-	seen := map[string]GlobalSkillInfo{}
-	for _, skill := range skills {
-		name := strings.TrimSpace(skill.Name)
-		path := strings.TrimSpace(skill.Path)
-		if name == "" || path == "" || !skillNamePattern.MatchString(name) {
-			continue
-		}
-		seen[name] = GlobalSkillInfo{Name: name, Path: path}
-	}
-
-	out := make([]GlobalSkillInfo, 0, len(seen))
-	for _, info := range seen {
-		out = append(out, info)
-	}
-	sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
-	return out, true
-}
-
-func installedSkillNamesFromInfos(infos []GlobalSkillInfo) []string {
-	seen := map[string]bool{}
-	for _, info := range infos {
-		seen[info.Name] = true
-		if info.Name == suiteSkillName {
-			for _, subskill := range listSuiteSubskills(info.Path) {
-				seen[subskill] = true
-			}
-		}
-	}
-	return sortedKeys(seen)
-}
-
-func listSuiteSubskills(suitePath string) []string {
-	entries, err := os.ReadDir(filepath.Join(suitePath, "references", "subskills"))
-	if err != nil {
-		return nil
-	}
-	seen := map[string]bool{}
-	for _, entry := range entries {
-		if !entry.IsDir() {
-			continue
-		}
-		name := strings.TrimSpace(entry.Name())
-		if name != "" && skillNamePattern.MatchString(name) {
-			seen[name] = true
-		}
-	}
-	return sortedKeys(seen)
-}
-
-func normalOfficialSkills(skills []string) []string {
-	out := []string{}
-	for _, skill := range uniqueSorted(skills) {
-		if skill != suiteSkillName {
-			out = append(out, skill)
-		}
-	}
-	return out
-}
-
-func deletedOfficialSkills(official, local []string, previous *SkillsState, stateReadable, force bool, layout string) []string {
-	if force || !stateReadable || previous == nil {
-		return []string{}
-	}
-	officialSet := toSet(official)
-	localSet := toSet(local)
-	deleted := map[string]bool{}
-	for _, skill := range previous.OfficialSkills {
-		if !officialSet[skill] || localSet[skill] {
-			continue
-		}
-		if layout != LayoutSeparate && skill == sharedSkillName {
-			continue
-		}
-		deleted[skill] = true
-	}
-	return sortedKeys(deleted)
-}
-
-func suiteEffectiveSkills(official []string, deleted map[string]bool) []string {
-	out := []string{}
-	for _, skill := range normalOfficialSkills(official) {
-		if !deleted[skill] {
-			out = append(out, skill)
-		}
-	}
-	return uniqueSorted(out)
-}
-
-func resolveHybridSkillSets(layout string, requestedFlat, official []string, skippedDeleted []string) ([]string, []string, error) {
-	if layout == LayoutSeparate {
-		return []string{}, []string{}, nil
-	}
-
-	officialSet := toSet(official)
-	deletedSet := toSet(skippedDeleted)
-	configuredFlat := map[string]bool{}
-	effectiveFlat := map[string]bool{}
-	for _, skill := range uniqueSorted(requestedFlat) {
-		if skill == sharedSkillName {
-			return nil, nil, fmt.Errorf("%s cannot be selected by --flat-skills", sharedSkillName)
-		}
-		if !officialSet[skill] {
-			return nil, nil, fmt.Errorf("flat skill %q is not in official skills", skill)
-		}
-		configuredFlat[skill] = true
-		if !deletedSet[skill] {
-			effectiveFlat[skill] = true
-		}
-	}
-
-	collected := []string{}
-	for _, skill := range normalOfficialSkills(official) {
-		if skill == sharedSkillName {
-			collected = append(collected, skill)
-			continue
-		}
-		if deletedSet[skill] || effectiveFlat[skill] {
-			continue
-		}
-		collected = append(collected, skill)
-	}
-	return sortedKeys(configuredFlat), uniqueSortedWithFirst(collected, sharedSkillName), nil
-}
-
-func uniqueSortedWithFirst(values []string, first string) []string {
-	seen := toSet(values)
-	if !seen[first] {
-		return sortedKeys(seen)
-	}
-	delete(seen, first)
-	return append([]string{first}, sortedKeys(seen)...)
-}
-
-func assembleSuiteLayout(layout string, collected []string, keepSharedTopLevel bool, infos []GlobalSkillInfo) error {
-	if layout == LayoutSeparate {
-		return nil
-	}
-
-	infoByName := map[string]GlobalSkillInfo{}
-	for _, info := range infos {
-		infoByName[info.Name] = info
-	}
-	suiteInfo, ok := infoByName[suiteSkillName]
-	if !ok {
-		return fmt.Errorf("%s was not installed from isolated skills source", suiteSkillName)
-	}
-
-	subskillsDir := filepath.Join(suiteInfo.Path, "references", "subskills")
-	if err := os.RemoveAll(subskillsDir); err != nil {
-		return err
-	}
-	if err := os.MkdirAll(subskillsDir, 0o755); err != nil {
-		return err
-	}
-
-	for _, skill := range collected {
-		info, ok := infoByName[skill]
-		if !ok {
-			return fmt.Errorf("suite subskill %q was not installed", skill)
-		}
-		dst := filepath.Join(subskillsDir, skill)
-		if keepSharedTopLevel && skill == sharedSkillName {
-			if err := copyDir(info.Path, dst); err != nil {
-				return err
-			}
-			continue
-		}
-		if err := moveDir(info.Path, dst); err != nil {
-			return err
-		}
-	}
-	return renderSuiteRoutes(suiteInfo.Path, collected)
-}
-
-func renderSuiteRoutes(suitePath string, collected []string) error {
-	skillPath := filepath.Join(suitePath, "SKILL.md")
-	data, err := os.ReadFile(skillPath)
-	if err != nil {
-		return err
-	}
-	text := normalizeSuiteTemplateText(string(data))
-	routes := []string{}
-	for _, skill := range collected {
-		desc := skillDescription(filepath.Join(suitePath, "references", "subskills", skill, "SKILL.md"))
-		if desc == "" {
-			desc = skill
-		}
-		routes = append(routes, fmt.Sprintf("- %s: %s", skill, desc))
-	}
-	if !strings.Contains(text, suiteRoutesPlaceholder) {
-		return fmt.Errorf("%s route placeholder not found", suiteSkillName)
-	}
-	text = strings.Replace(text, suiteRoutesPlaceholder, strings.Join(routes, "\n"), 1)
-	return os.WriteFile(skillPath, []byte(text), 0o644)
-}
-
-func normalizeSuiteTemplateText(text string) string {
-	text = strings.ReplaceAll(text, "--collected-skills", "--flat-skills")
-	oldShared := "`lark-shared` 是共享基础能力，不作为 `--flat-skills` 的可选项。为了保证 suite 内子能力可用，hybrid 布局会同时保留顶层 `lark-shared`，并在 `lark-suite/references/subskills/lark-shared/SKILL.md` 中维护一份副本。"
-	newShared := "`lark-shared` 是共享基础能力，不作为 `--flat-skills` 的可选项。为了保证 suite 内子能力可用，它始终会进入 `lark-suite/references/subskills/lark-shared/SKILL.md`；只有 hybrid 布局存在平铺 skill 时，顶层才会额外保留一份 `lark-shared`。"
-	return strings.ReplaceAll(text, oldShared, newShared)
-}
-
-func skillDescription(path string) string {
-	data, err := os.ReadFile(path)
-	if err != nil {
-		return ""
-	}
-	lines := strings.Split(string(data), "\n")
-	if len(lines) == 0 || strings.TrimSpace(lines[0]) != "---" {
-		return ""
-	}
-	for i, line := range lines[1:] {
-		trimmed := strings.TrimSpace(line)
-		if trimmed == "---" {
-			return ""
-		}
-		if strings.HasPrefix(trimmed, "description:") {
-			value := strings.TrimSpace(strings.TrimPrefix(trimmed, "description:"))
-			if value == ">" || value == "|" {
-				return foldedYAMLScalar(lines[i+2:])
-			}
-			return strings.Trim(value, `"'`)
-		}
-	}
-	return ""
-}
-
-func foldedYAMLScalar(lines []string) string {
-	parts := []string{}
-	for _, line := range lines {
-		trimmed := strings.TrimSpace(line)
-		if trimmed == "" {
-			continue
-		}
-		if trimmed == "---" || !isIndentedYAMLLine(line) {
-			break
-		}
-		parts = append(parts, trimmed)
-	}
-	return strings.Join(parts, " ")
-}
-
-func isIndentedYAMLLine(line string) bool {
-	return strings.HasPrefix(line, " ") || strings.HasPrefix(line, "\t")
-}
-
-func moveDir(src, dst string) error {
-	if err := os.RemoveAll(dst); err != nil {
-		return err
-	}
-	if err := os.MkdirAll(filepath.Dir(dst), 0o755); err != nil {
-		return err
-	}
-	if err := os.Rename(src, dst); err == nil {
-		return nil
-	}
-	if err := copyDir(src, dst); err != nil {
-		return err
-	}
-	return os.RemoveAll(src)
-}
-
-func copyDir(src, dst string) error {
-	info, err := os.Stat(src)
-	if err != nil {
-		return err
-	}
-	if !info.IsDir() {
-		return fmt.Errorf("%s is not a directory", src)
-	}
-	if err := os.RemoveAll(dst); err != nil {
-		return err
-	}
-	return filepath.WalkDir(src, func(path string, entry os.DirEntry, walkErr error) error {
-		if walkErr != nil {
-			return walkErr
-		}
-		rel, err := filepath.Rel(src, path)
-		if err != nil {
-			return err
-		}
-		target := filepath.Join(dst, rel)
-		if entry.IsDir() {
-			return os.MkdirAll(target, 0o755)
-		}
-		return copyFile(path, target)
-	})
-}
-
-func copyFile(src, dst string) error {
-	in, err := os.Open(src)
-	if err != nil {
-		return err
-	}
-	defer in.Close()
-	if err := os.MkdirAll(filepath.Dir(dst), 0o755); err != nil {
-		return err
-	}
-	out, err := os.OpenFile(dst, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0o644)
-	if err != nil {
-		return err
-	}
-	defer out.Close()
-	_, err = io.Copy(out, in)
-	return err
-}
--- a/internal/skillscheck/state.go
+++ b/internal/skillscheck/state.go
@@ -23,12 +23,10 @@ var ErrUnreadableState = errors.New("skills state is unreadable")

 type SkillsState struct {
 	Version              string   `json:"version"`
-	Layout               string   `json:"layout,omitempty"`
 	OfficialSkills       []string `json:"official_skills"`
 	UpdatedSkills        []string `json:"updated_skills"`
 	AddedOfficialSkills  []string `json:"added_official_skills"`
 	SkippedDeletedSkills []string `json:"skipped_deleted_skills"`
-	FlatSkills           []string `json:"flat_skills"`
 	UpdatedAt            string   `json:"updated_at"`
 }

@@ -78,14 +76,6 @@ func ReadSyncedVersion() (string, bool) {
 	return state.Version, true
 }

-func ReadSyncedVersionAndLayout() (version string, layout string, ok bool) {
-	state, readable, err := ReadState()
-	if err != nil || !readable || state.Version == "" {
-		return "", "", false
-	}
-	return state.Version, state.Layout, true
-}
-
 func (s *SkillsState) ensureNonNilSlices() {
 	if s.OfficialSkills == nil {
 		s.OfficialSkills = []string{}
@@ -99,7 +89,4 @@ func (s *SkillsState) ensureNonNilSlices() {
 	if s.SkippedDeletedSkills == nil {
 		s.SkippedDeletedSkills = []string{}
 	}
-	if s.FlatSkills == nil {
-		s.FlatSkills = []string{}
-	}
 }
--- a/internal/skillscheck/sync.go
+++ b/internal/skillscheck/sync.go
@@ -21,7 +21,6 @@ var (

 type SyncInput struct {
 	Version        string
-	Layout         string
 	OfficialSkills []string
 	LocalSkills    []string
 	PreviousState  *SkillsState
@@ -196,18 +195,7 @@ func parseOfficialSkillsList(lines []string) []string {
 }

 func PlanSync(input SyncInput) SyncPlan {
-	official := normalOfficialSkills(input.OfficialSkills)
-	layout, _ := NormalizeLayout(input.Layout)
-	skippedDeleted := deletedOfficialSkills(official, input.LocalSkills, input.PreviousState, input.StateReadable, input.Force, layout)
-	if layout != LayoutSeparate {
-		return SyncPlan{
-			Version:        input.Version,
-			OfficialSkills: official,
-			ToUpdate:       suiteEffectiveSkills(official, toSet(skippedDeleted)),
-			Added:          newlyOfficialSkills(official, input.PreviousState, input.StateReadable),
-			SkippedDeleted: skippedDeleted,
-		}
-	}
+	official := uniqueSorted(input.OfficialSkills)
 	if input.Force {
 		return SyncPlan{
 			Version:        input.Version,
@@ -241,12 +229,19 @@ func PlanSync(input SyncInput) SyncPlan {
 	toUpdate := sortedKeys(updateSet)
 	updateSet = toSet(toUpdate)

+	skipped := []string{}
+	for _, skill := range official {
+		if !updateSet[skill] {
+			skipped = append(skipped, skill)
+		}
+	}
+
 	return SyncPlan{
 		Version:        input.Version,
 		OfficialSkills: official,
 		ToUpdate:       toUpdate,
 		Added:          uniqueSorted(newAddedOfficial),
-		SkippedDeleted: skippedDeleted,
+		SkippedDeleted: skipped,
 	}
 }

@@ -257,16 +252,13 @@ type SkillsRunner interface {
 	ListGlobalSkills() *selfupdate.NpmResult
 	InstallSkill(nameList []string) *selfupdate.NpmResult
 	InstallAllSkills() *selfupdate.NpmResult
-	InstallSuiteSkill() *selfupdate.NpmResult
 }

 type SyncOptions struct {
-	Version    string
-	Layout     string
-	FlatSkills []string
-	Force      bool
-	Runner     SkillsRunner
-	Now        func() time.Time
+	Version string
+	Force   bool
+	Runner  SkillsRunner
+	Now     func() time.Time
 }

 type SyncResult struct {
@@ -279,9 +271,6 @@ type SyncResult struct {
 	Err            error
 	Detail         string
 	Force          bool
-	Layout         string
-	Flat           []string
-	Collected      []string
 }

 func SyncSkills(opts SyncOptions) *SyncResult {
@@ -291,26 +280,16 @@ func SyncSkills(opts SyncOptions) *SyncResult {
 	if opts.Runner == nil {
 		return &SyncResult{Action: "failed", Err: fmt.Errorf("skills runner is nil")}
 	}
-	layout, ok := NormalizeLayout(opts.Layout)
-	if !ok {
-		return &SyncResult{Action: "failed", Err: fmt.Errorf("unsupported skills layout %q", opts.Layout)}
-	}

 	// --- Step 1: List official skills ---
 	official, reason, ok := listOfficialSkills(opts.Runner)
 	if !ok {
-		if layout != LayoutSeparate {
-			return failedSync(layout, opts.Force, fmt.Errorf("failed to discover official skills for %s layout: %s", layout, reason), reason)
-		}
 		return fallbackFullInstall(opts, reason, nil)
 	}

 	// --- Step 2: List local (installed) skills ---
 	local, ok := listLocalSkills(opts.Runner)
 	if !ok {
-		if layout != LayoutSeparate {
-			return failedSync(layout, opts.Force, fmt.Errorf("failed to list local skills for %s layout", layout), "local skills list failed or parsed as empty")
-		}
 		return fallbackFullInstall(opts, "local skills list failed or parsed as empty", official)
 	}

@@ -323,17 +302,12 @@ func SyncSkills(opts SyncOptions) *SyncResult {

 	plan := PlanSync(SyncInput{
 		Version:        opts.Version,
-		Layout:         layout,
 		OfficialSkills: official,
 		LocalSkills:    local,
 		PreviousState:  previous,
 		StateReadable:  readable,
 		Force:          opts.Force,
 	})
-	flat, collected, err := resolveHybridSkillSets(layout, opts.FlatSkills, plan.OfficialSkills, plan.SkippedDeleted)
-	if err != nil {
-		return &SyncResult{Action: "failed", Err: err, Official: plan.OfficialSkills, Force: opts.Force, Layout: layout}
-	}

 	result := &SyncResult{
 		Action:         "synced",
@@ -342,59 +316,25 @@ func SyncSkills(opts SyncOptions) *SyncResult {
 		Added:          plan.Added,
 		SkippedDeleted: plan.SkippedDeleted,
 		Force:          opts.Force,
-		Layout:         layout,
-		Flat:           flat,
-		Collected:      collected,
 	}

 	if len(plan.ToUpdate) == 0 {
-		if layout != LayoutSeparate {
-			return failedSync(layout, opts.Force, fmt.Errorf("no target skills to assemble %s layout", layout), "toUpdate skills empty")
-		}
 		return fallbackFullInstall(opts, "toUpdate skills empty fallback", official)
 	}

 	if len(plan.ToUpdate) > 0 {
 		installResult := opts.Runner.InstallSkill(plan.ToUpdate)
 		if installResult == nil || installResult.Err != nil {
-			if layout != LayoutSeparate {
-				return failedSync(layout, opts.Force, fmt.Errorf("failed to install skills for %s layout: %s", layout, resultDetail(installResult)), resultDetail(installResult))
-			}
 			return fallbackFullInstall(opts, resultDetail(installResult), official)
 		}
 	}
-	if layout != LayoutSeparate {
-		installSuiteResult := opts.Runner.InstallSuiteSkill()
-		if installSuiteResult == nil || installSuiteResult.Err != nil {
-			result.Action = "failed"
-			result.Err = fmt.Errorf("failed to install %s from isolated skills source: %s", suiteSkillName, resultDetail(installSuiteResult))
-			result.Detail = resultDetail(installSuiteResult)
-			return result
-		}
-		infosResult := opts.Runner.ListGlobalSkillsJSON()
-		if infosResult == nil || infosResult.Err != nil {
-			result.Action = "failed"
-			result.Err = fmt.Errorf("failed to list installed skills for %s assembly: %s", suiteSkillName, resultDetail(infosResult))
-			result.Detail = resultDetail(infosResult)
-			return result
-		}
-		infos := ParseGlobalSkillInfosJSON(infosResult.Stdout.String())
-		keepSharedTopLevel := layout == LayoutHybrid && len(flat) > 0
-		if err := assembleSuiteLayout(layout, collected, keepSharedTopLevel, infos); err != nil {
-			result.Action = "failed"
-			result.Err = fmt.Errorf("failed to assemble %s layout: %w", layout, err)
-			return result
-		}
-	}

 	state := SkillsState{
 		Version:              opts.Version,
-		Layout:               layout,
 		OfficialSkills:       plan.OfficialSkills,
 		UpdatedSkills:        plan.ToUpdate,
 		AddedOfficialSkills:  plan.Added,
 		SkippedDeletedSkills: plan.SkippedDeleted,
-		FlatSkills:           stateFlatSkills(layout, flat),
 		UpdatedAt:            opts.Now().UTC().Format(time.RFC3339),
 	}
 	if err := WriteState(state); err != nil {
@@ -406,16 +346,6 @@ func SyncSkills(opts SyncOptions) *SyncResult {
 	return result
 }

-func failedSync(layout string, force bool, err error, detail string) *SyncResult {
-	return &SyncResult{
-		Action: "failed",
-		Err:    err,
-		Detail: detail,
-		Force:  force,
-		Layout: layout,
-	}
-}
-
 func listOfficialSkills(runner SkillsRunner) ([]string, string, bool) {
 	reasons := []string{}

@@ -453,9 +383,8 @@ func listOfficialSkills(runner SkillsRunner) ([]string, string, bool) {
 func listLocalSkills(runner SkillsRunner) ([]string, bool) {
 	jsonResult := runner.ListGlobalSkillsJSON()
 	if jsonResult != nil && jsonResult.Err == nil {
-		infos, valid := parseGlobalSkillInfosJSON(jsonResult.Stdout.String())
-		if valid {
-			return installedSkillNamesFromInfos(infos), true
+		if local := ParseGlobalSkillsJSON(jsonResult.Stdout.String()); len(local) > 0 {
+			return local, true
 		}
 	}

@@ -482,7 +411,6 @@ func fallbackFullInstall(opts SyncOptions, reason string, official []string) *Sy
 			Err:    fmt.Errorf("full skills install failed: empty result (reason: %s)", reason),
 			Detail: reason,
 			Force:  opts.Force,
-			Layout: LayoutSeparate,
 		}
 	}
 	if installResult.Err != nil {
@@ -491,13 +419,11 @@ func fallbackFullInstall(opts SyncOptions, reason string, official []string) *Sy
 			Err:    fmt.Errorf("full skills install failed: %w (reason: %s)", installResult.Err, reason),
 			Detail: reason + "\n" + resultDetail(installResult),
 			Force:  opts.Force,
-			Layout: LayoutSeparate,
 		}
 	}

 	state := SkillsState{
 		Version:              opts.Version,
-		Layout:               LayoutSeparate,
 		OfficialSkills:       official,
 		UpdatedSkills:        official,
 		AddedOfficialSkills:  official,
@@ -513,7 +439,6 @@ func fallbackFullInstall(opts SyncOptions, reason string, official []string) *Sy
 			SkippedDeleted: []string{},
 			Detail:         reason + "\nstate write failed: " + writeErr.Error(),
 			Force:          opts.Force,
-			Layout:         LayoutSeparate,
 		}
 	}

@@ -525,38 +450,9 @@ func fallbackFullInstall(opts SyncOptions, reason string, official []string) *Sy
 		SkippedDeleted: []string{},
 		Detail:         reason,
 		Force:          opts.Force,
-		Layout:         LayoutSeparate,
 	}
 }

-func stateFlatSkills(layout string, requested []string) []string {
-	if layout != LayoutHybrid {
-		return []string{}
-	}
-	out := []string{}
-	for _, skill := range uniqueSorted(requested) {
-		if skill != sharedSkillName {
-			out = append(out, skill)
-		}
-	}
-	return out
-}
-
-func newlyOfficialSkills(official []string, previous *SkillsState, stateReadable bool) []string {
-	previousOfficial := []string{}
-	if stateReadable && previous != nil {
-		previousOfficial = previous.OfficialSkills
-	}
-	previousSet := toSet(previousOfficial)
-	added := []string{}
-	for _, skill := range official {
-		if !previousSet[skill] {
-			added = append(added, skill)
-		}
-	}
-	return uniqueSorted(added)
-}
-
 func resultDetail(result *selfupdate.NpmResult) string {
 	if result == nil {
 		return ""
--- a/internal/skillscheck/sync_test.go
+++ b/internal/skillscheck/sync_test.go
@@ -8,7 +8,6 @@ import (
 	"os"
 	"path/filepath"
 	"reflect"
-	"sort"
 	"strings"
 	"testing"
 	"time"
@@ -217,10 +216,8 @@ type fakeSkillsRunner struct {
 	globalErr        error
 	installErr       error
 	installAllErr    error
-	installSuiteErr  error
 	installed        [][]string
 	installedAll     int
-	installedSuite   int
 	listedIndex      int
 	listedOfficial   int
 	listedGlobalJSON int
@@ -322,13 +319,6 @@ func (f *fakeSkillsRunner) InstallAllSkills() *selfupdate.NpmResult {
 	return r
 }

-func (f *fakeSkillsRunner) InstallSuiteSkill() *selfupdate.NpmResult {
-	f.installedSuite++
-	r := &selfupdate.NpmResult{}
-	r.Err = f.installSuiteErr
-	return r
-}
-
 func TestSyncSkills_WritesStateAndDoesNotWriteStamp(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
@@ -584,7 +574,7 @@ func TestSyncSkills_LocalListsFailureFallsBackToFullInstall(t *testing.T) {
 	}
 }

-func TestSyncSkills_EmptyGlobalJSONInstallsAllOfficialIncrementally(t *testing.T) {
+func TestSyncSkills_ParseEmptyLocalListsFallBackToFullInstall(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
@@ -595,15 +585,14 @@ func TestSyncSkills_EmptyGlobalJSONInstallsAllOfficialIncrementally(t *testing.T
 	}

 	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
-	if result.Action != "synced" {
-		t.Fatalf("SyncSkills() action = %q, want synced", result.Action)
+	if result.Action != "fallback_synced" {
+		t.Fatalf("SyncSkills() action = %q, want fallback_synced", result.Action)
 	}
-	if len(runner.installed) != 1 {
-		t.Fatalf("installed = %#v, want one incremental install", runner.installed)
+	if len(runner.installed) != 0 {
+		t.Fatalf("installed = %#v, want no incremental installs", runner.installed)
 	}
-	assertStrings(t, runner.installed[0], []string{"lark-calendar", "lark-mail"})
-	if runner.installedAll != 0 {
-		t.Fatalf("installedAll = %d, want 0", runner.installedAll)
+	if runner.installedAll != 1 {
+		t.Fatalf("installedAll = %d, want 1", runner.installedAll)
 	}
 }

@@ -708,115 +697,6 @@ func TestSyncSkills_NilRunnerFails(t *testing.T) {
 	}
 }

-func TestSyncSkills_HybridAssemblesSuiteAndMovesCollectedSkills(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	paths := map[string]string{}
-	for _, name := range []string{"lark-calendar", "lark-doc", "lark-shared", "lark-suite"} {
-		paths[name] = filepath.Join(dir, name)
-		writeTestSkill(t, paths[name], name)
-	}
-
-	runner := &fakeSkillsRunner{
-		officialIndexOut: officialSkillsIndexOutput("lark-calendar", "lark-doc", "lark-shared"),
-		globalJSONOut:    globalSkillsJSONFromPaths(paths),
-	}
-
-	result := SyncSkills(SyncOptions{
-		Version:    "1.0.33",
-		Layout:     LayoutHybrid,
-		FlatSkills: []string{"lark-calendar"},
-		Runner:     runner,
-		Now:        time.Now,
-	})
-
-	if result.Err != nil {
-		t.Fatalf("SyncSkills() err = %v, want nil", result.Err)
-	}
-	if runner.installedSuite != 1 {
-		t.Fatalf("installedSuite = %d, want 1", runner.installedSuite)
-	}
-	assertStrings(t, result.Flat, []string{"lark-calendar"})
-	assertStrings(t, result.Collected, []string{"lark-shared", "lark-doc"})
-	if _, err := os.Stat(filepath.Join(paths["lark-suite"], "references", "subskills", "lark-doc", "SKILL.md")); err != nil {
-		t.Fatalf("suite lark-doc missing: %v", err)
-	}
-	if _, err := os.Stat(filepath.Join(paths["lark-suite"], "references", "subskills", "lark-shared", "SKILL.md")); err != nil {
-		t.Fatalf("suite lark-shared missing: %v", err)
-	}
-	if _, err := os.Stat(filepath.Join(paths["lark-calendar"], "SKILL.md")); err != nil {
-		t.Fatalf("flat lark-calendar missing: %v", err)
-	}
-	if _, err := os.Stat(filepath.Join(paths["lark-doc"], "SKILL.md")); !os.IsNotExist(err) {
-		t.Fatalf("collected lark-doc still exists at top level or unexpected err: %v", err)
-	}
-	if _, err := os.Stat(filepath.Join(paths["lark-shared"], "SKILL.md")); err != nil {
-		t.Fatalf("lark-shared should stay top-level when flat set is non-empty: %v", err)
-	}
-
-	state, readable, err := ReadState()
-	if err != nil || !readable {
-		t.Fatalf("ReadState() = (_, %v, %v), want readable", readable, err)
-	}
-	if state.Layout != LayoutHybrid {
-		t.Fatalf("state.Layout = %q, want %q", state.Layout, LayoutHybrid)
-	}
-	assertStrings(t, state.FlatSkills, []string{"lark-calendar"})
-}
-
-func TestSyncSkills_HybridWithNoFlatSkillsDoesNotKeepSharedTopLevel(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	paths := map[string]string{}
-	for _, name := range []string{"lark-shared", "lark-suite"} {
-		paths[name] = filepath.Join(dir, name)
-		writeTestSkill(t, paths[name], name)
-	}
-
-	runner := &fakeSkillsRunner{
-		officialIndexOut: officialSkillsIndexOutput("lark-shared"),
-		globalJSONOut:    globalSkillsJSONFromPaths(paths),
-	}
-
-	result := SyncSkills(SyncOptions{
-		Version: "1.0.33",
-		Layout:  LayoutHybrid,
-		Runner:  runner,
-		Now:     time.Now,
-	})
-
-	if result.Err != nil {
-		t.Fatalf("SyncSkills() err = %v, want nil", result.Err)
-	}
-	if _, err := os.Stat(filepath.Join(paths["lark-shared"], "SKILL.md")); !os.IsNotExist(err) {
-		t.Fatalf("lark-shared should not stay top-level when flat set is empty; err: %v", err)
-	}
-	if result.Flat == nil || len(result.Flat) != 0 {
-		t.Fatalf("result.Flat = %#v, want empty slice", result.Flat)
-	}
-}
-
-func TestSyncSkills_HybridRejectsSharedFlatSkill(t *testing.T) {
-	runner := &fakeSkillsRunner{
-		officialIndexOut: officialSkillsIndexOutput("lark-calendar", "lark-shared"),
-		globalJSONOut:    globalSkillsJSONOutput("lark-calendar", "lark-shared"),
-	}
-
-	result := SyncSkills(SyncOptions{
-		Version:    "1.0.33",
-		Layout:     LayoutHybrid,
-		FlatSkills: []string{"lark-shared"},
-		Runner:     runner,
-		Now:        time.Now,
-	})
-
-	if result.Err == nil || !strings.Contains(result.Err.Error(), "lark-shared") {
-		t.Fatalf("SyncSkills() err = %v, want lark-shared validation error", result.Err)
-	}
-}
-
 func TestSyncSkills_ParseEmptyWithNonEmptyStdoutFallsBack(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
@@ -853,43 +733,6 @@ func TestSyncSkills_ParseEmptyWithNonEmptyStdoutAndFullInstallFails(t *testing.T
 	}
 }

-func TestNormalizeSuiteTemplateTextRewritesLegacyFlatSkillWording(t *testing.T) {
-	input := "`lark-shared` 是共享基础能力，不作为 `--collected-skills` 的可选项。为了保证 suite 内子能力可用，hybrid 布局会同时保留顶层 `lark-shared`，并在 `lark-suite/references/subskills/lark-shared/SKILL.md` 中维护一份副本。"
-	got := normalizeSuiteTemplateText(input)
-	if strings.Contains(got, "--collected-skills") {
-		t.Fatalf("normalized text still contains legacy flag: %s", got)
-	}
-	if !strings.Contains(got, "--flat-skills") {
-		t.Fatalf("normalized text missing --flat-skills: %s", got)
-	}
-	if !strings.Contains(got, "只有 hybrid 布局存在平铺 skill 时，顶层才会额外保留一份") {
-		t.Fatalf("normalized text missing current lark-shared rule: %s", got)
-	}
-}
-
-func TestSkillDescriptionSupportsFoldedYAMLScalar(t *testing.T) {
-	dir := t.TempDir()
-	path := filepath.Join(dir, "SKILL.md")
-	content := `---
-name: lark-whiteboard
-description: >
-  飞书画板：查询和编辑飞书云文档中的画板。
-  当用户需要查看画板内容、导出画板图片、编辑画板时使用此 skill。
-metadata:
-  requires:
-    bins: ["lark-cli"]
---
-`
-	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
-		t.Fatal(err)
-	}
-	got := skillDescription(path)
-	want := "飞书画板：查询和编辑飞书云文档中的画板。 当用户需要查看画板内容、导出画板图片、编辑画板时使用此 skill。"
-	if got != want {
-		t.Fatalf("skillDescription() = %q, want %q", got, want)
-	}
-}
-
 func assertStrings(t *testing.T, got, want []string) {
 	t.Helper()
 	if !reflect.DeepEqual(got, want) {
@@ -897,38 +740,6 @@ func assertStrings(t *testing.T, got, want []string) {
 	}
 }

-func writeTestSkill(t *testing.T, dir, name string) {
-	t.Helper()
-	if err := os.MkdirAll(dir, 0o755); err != nil {
-		t.Fatal(err)
-	}
-	content := fmt.Sprintf("---\nname: %s\ndescription: %s description\n---\n", name, name)
-	if name == suiteSkillName {
-		content = "---\nname: lark-suite\ndescription: Lark suite\n---\n<!-- LARK_SUITE_ROUTES -->\n"
-	}
-	if err := os.WriteFile(filepath.Join(dir, "SKILL.md"), []byte(content), 0o644); err != nil {
-		t.Fatal(err)
-	}
-}
-
-func globalSkillsJSONFromPaths(paths map[string]string) string {
-	names := make([]string, 0, len(paths))
-	for name := range paths {
-		names = append(names, name)
-	}
-	sort.Strings(names)
-	var b strings.Builder
-	b.WriteString("[")
-	for i, name := range names {
-		if i > 0 {
-			b.WriteString(",")
-		}
-		fmt.Fprintf(&b, `{"name":%q,"path":%q,"scope":"global","agents":["Codex"]}`, name, paths[name])
-	}
-	b.WriteString("]")
-	return b.String()
-}
-
 func TestSyncSkills_FallbackWithUnknownOfficialWritesMinimalState(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
--- a/isolated-skills/lark-suite/SKILL.md
+++ b/isolated-skills/lark-suite/SKILL.md
@@ -1,33 +0,0 @@
---
-name: lark-suite
-version: 0.1.0
-description: 飞书/Lark 聚合能力入口：当用户需求涉及本文件列出的任一飞书能力时使用；仅负责选择并加载已安装到本 suite 的 lark-* 子能力，不替代具体子能力的操作细节。
-metadata:
-  requires:
-    bins:
-      - lark-cli
---
-
-# Lark Suite
-
-你是飞书/Lark 能力的聚合路由层。你的职责是先判断用户要使用哪个 `lark-*` 子能力，再读取并遵循对应子能力的说明。
-
-`lark-suite` 不直接承载具体 API 操作步骤。除非对应子能力已被读取，否则不要仅根据本文件拼命令、猜参数或执行复杂操作。
-
-## 使用流程
-
-1. 根据用户意图从下方路由表选择一个或多个子能力；即使用户尚未提供链接、ID 或具体工作表，也先选择能力，再由子能力询问缺失信息。
-2. 读取对应子能力说明，优先使用 `references/subskills/<skill-name>/SKILL.md`。
-3. 如果目标能力没有出现在本文件中，不代表当前环境不可用；检查是否存在相关的独立 `lark-*` skill。
-4. 如果已选中的子能力说明列出必读、前置或继续阅读的文件，只读取该子能力当前任务所需的前置文件；不要读取无关子能力。
-5. 按目标子能力的说明执行；认证、租户、身份、权限和通用排障优先遵循 `lark-shared`。
-
-`lark-shared` 是共享基础能力，不作为 `--flat-skills` 的可选项。为了保证 suite 内子能力可用，它始终会进入 `lark-suite/references/subskills/lark-shared/SKILL.md`；只有 hybrid 布局存在平铺 skill 时，顶层才会额外保留一份 `lark-shared`。
-
-多步任务可以组合多个子能力，但每一步都应由具体子能力驱动。例如“查联系人并发消息”先用 `lark-contact` 解析身份，再用 `lark-im` 发消息。
-
-## 能力路由
-
-根据用户意图从以下条目选择对应子能力；如果一个任务涉及多个能力，按实际操作顺序逐步读取并使用对应子能力。
-
-<!-- LARK_SUITE_ROUTES -->
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
  "name": "@larksuite/cli",
-  "version": "1.0.64",
+  "version": "1.0.66",
  "description": "The official CLI for Lark/Feishu open platform",
  "bin": {
    "lark-cli": "scripts/run.js"
--- a/shortcuts/calendar/calendar_create.go
+++ b/shortcuts/calendar/calendar_create.go
@@ -67,6 +67,26 @@ func parseAttendees(attendeesStr string, currentUserId string) ([]map[string]str
 	return attendees, nil
 }

+func attendeesIncludeRoom(attendees []map[string]string) bool {
+	for _, attendee := range attendees {
+		if attendee["type"] == "resource" || attendee["room_id"] != "" {
+			return true
+		}
+	}
+	return false
+}
+
+func guideApprovalRoomReasonError(err error, attendees []map[string]string) error {
+	if err == nil || !attendeesIncludeRoom(attendees) {
+		return err
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok || !strings.Contains(strings.ToLower(p.Hint), "approval_reason") {
+		return err
+	}
+	return withStepContext(err, "approval meeting rooms require attendees[].approval_reason; calendar +create does not expose this low-frequency field. Create the event with the raw API flow, then use `lark-cli calendar event.attendees create --as user` with attendees[].approval_reason for the room attendee.")
+}
+
 var CalendarCreate = common.Shortcut{
 	Service:     "calendar",
 	Command:     "+create",
@@ -225,6 +245,7 @@ var CalendarCreate = common.Shortcut{
 					"need_notification": true,
 				})
 			if err != nil {
+				err = guideApprovalRoomReasonError(err, attendees)
 				// Rollback: delete the event
 				_, rollbackErr := runtime.CallAPITyped("DELETE",
 					fmt.Sprintf("/open-apis/calendar/v4/calendars/%s/events/%s", validate.EncodePathSegment(calendarId), validate.EncodePathSegment(eventId)),
--- a/shortcuts/calendar/calendar_test.go
+++ b/shortcuts/calendar/calendar_test.go
@@ -673,6 +673,76 @@ func TestCreate_WithAttendees_InvalidParamsWithDetail_RollsBack(t *testing.T) {
 	}
 }

+func TestCreate_ApprovalRoomMissingReason_GuidesRawAttendeesAPI(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/calendar/v4/calendars/cal_test123/events",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"event": map[string]interface{}{
+					"event_id":   "evt_approval_room",
+					"summary":    "Approval Room",
+					"start_time": map[string]interface{}{"timestamp": "1742515200"},
+					"end_time":   map[string]interface{}{"timestamp": "1742518800"},
+				},
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/events/evt_approval_room/attendees",
+		Body: map[string]interface{}{
+			"code": codeInvalidParamsWithDetail,
+			"msg":  "invalid params",
+			"error": map[string]interface{}{
+				"details": []interface{}{
+					map[string]interface{}{"value": "attendees[0].approval_reason is required for approval meeting rooms"},
+				},
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "DELETE",
+		URL:    "/events/evt_approval_room",
+		Body:   map[string]interface{}{"code": 0, "msg": "ok"},
+	})
+
+	err := mountAndRun(t, CalendarCreate, []string{
+		"+create",
+		"--summary", "Approval Room",
+		"--start", "2025-03-21T00:00:00+08:00",
+		"--end", "2025-03-21T01:00:00+08:00",
+		"--calendar-id", "cal_test123",
+		"--attendee-ids", "omm_room1",
+		"--as", "user",
+	}, f, nil)
+
+	if err == nil {
+		t.Fatal("expected error for approval room missing approval_reason, got nil")
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("ProblemOf returned !ok for %T", err)
+	}
+	if p.Category != errs.CategoryAPI {
+		t.Errorf("category=%q, want %q", p.Category, errs.CategoryAPI)
+	}
+	if p.Subtype != errs.SubtypeInvalidParameters {
+		t.Errorf("subtype=%q, want %q", p.Subtype, errs.SubtypeInvalidParameters)
+	}
+	if p.Code != codeInvalidParamsWithDetail {
+		t.Errorf("code=%d, want %d", p.Code, codeInvalidParamsWithDetail)
+	}
+	for _, want := range []string{"approval_reason", "calendar event.attendees create", "--as user", "rolled back successfully"} {
+		if !strings.Contains(p.Hint, want) {
+			t.Errorf("hint should contain %q, got: %q", want, p.Hint)
+		}
+	}
+}
+
 // When the add-attendees call fails AND the rollback DELETE also fails, the
 // primary error stays the add failure (classification preserved) and the Hint
 // must surface BOTH the rollback failure reason and the orphan event_id so the
--- a/shortcuts/drive/drive_import_common.go
+++ b/shortcuts/drive/drive_import_common.go
@@ -8,6 +8,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"path/filepath"
+	"strconv"
 	"strings"
 	"time"

@@ -28,6 +29,8 @@ const (
 	driveImport500MBFileSizeLimit int64 = 500 * 1024 * 1024
 	driveImport600MBFileSizeLimit int64 = 600 * 1024 * 1024
 	driveImport800MBFileSizeLimit int64 = 800 * 1024 * 1024
+
+	driveImportConcurrentOperationHint = "This import conflict means another operation is running in the same Drive location. Run batch imports to the same folder/root or target bitable serially. Wait a few seconds before retrying each failed import; retry each failed item at most 3 times, then stop and report the conflict."
 )

 // driveImportExtToDocTypes defines which source file extensions can be imported
@@ -47,6 +50,8 @@ var driveImportExtToDocTypes = map[string][]string{
 	"pptx":     {"slides"},
 }

+var driveImportConcurrentOperationCodes = []int{232140101, 232140100, 233523001}
+
 // driveImportSpec contains the user-facing import inputs after normalization.
 type driveImportSpec struct {
 	FilePath    string
@@ -427,11 +432,7 @@ func pollDriveImportTask(runtime *common.RuntimeContext, ticket string) (driveIm
 			return status, true, nil
 		}
 		if status.Failed() {
-			msg := strings.TrimSpace(status.JobErrorMsg)
-			if msg == "" {
-				msg = status.StatusLabel()
-			}
-			return status, false, errs.NewAPIError(errs.SubtypeServerError, "import failed with status %d: %s", status.JobStatus, msg)
+			return status, false, driveImportFailureError(status)
 		}
 	}
 	if !hadSuccessfulPoll && lastErr != nil {
@@ -440,3 +441,40 @@ func pollDriveImportTask(runtime *common.RuntimeContext, ticket string) (driveIm

 	return lastStatus, false, nil
 }
+
+func driveImportFailureError(status driveImportStatus) *errs.APIError {
+	msg := strings.TrimSpace(status.JobErrorMsg)
+	if msg == "" {
+		msg = status.StatusLabel()
+	}
+
+	apiErr := errs.NewAPIError(errs.SubtypeServerError, "import failed with status %d: %s", status.JobStatus, msg)
+	if code, ok := driveImportConcurrentOperationCode(msg); ok {
+		apiErr = apiErr.WithCode(code).WithRetryable().WithHint(driveImportConcurrentOperationHint)
+	}
+	return apiErr
+}
+
+func driveImportConcurrentOperationCode(msg string) (int, bool) {
+	for _, code := range driveImportConcurrentOperationCodes {
+		codeText := strconv.Itoa(code)
+		for idx := strings.Index(msg, codeText); idx >= 0; {
+			end := idx + len(codeText)
+			if (idx == 0 || !isASCIIDigit(msg[idx-1])) && (end == len(msg) || !isASCIIDigit(msg[end])) {
+				return code, true
+			}
+
+			nextStart := idx + 1
+			next := strings.Index(msg[nextStart:], codeText)
+			if next < 0 {
+				break
+			}
+			idx = nextStart + next
+		}
+	}
+	return 0, false
+}
+
+func isASCIIDigit(ch byte) bool {
+	return ch >= '0' && ch <= '9'
+}
--- a/shortcuts/drive/drive_import_common_test.go
+++ b/shortcuts/drive/drive_import_common_test.go
@@ -7,6 +7,7 @@ import (
 	"bytes"
 	"errors"
 	"os"
+	"strconv"
 	"strings"
 	"testing"

@@ -211,6 +212,82 @@ func TestDriveImportStatusPendingWithoutToken(t *testing.T) {
 	}
 }

+func TestDriveImportFailureErrorAddsConcurrentOperationGuidance(t *testing.T) {
+	t.Parallel()
+
+	for _, code := range driveImportConcurrentOperationCodes {
+		t.Run(strconv.Itoa(code), func(t *testing.T) {
+			t.Parallel()
+
+			err := driveImportFailureError(driveImportStatus{
+				JobStatus:   3,
+				JobErrorMsg: "call CreateObjNode return error code, code: " + strconv.Itoa(code) + ", message:",
+			})
+			problem, ok := errs.ProblemOf(err)
+			if !ok {
+				t.Fatalf("expected typed error, got %T", err)
+			}
+			if problem.Category != errs.CategoryAPI {
+				t.Fatalf("category = %q, want %q", problem.Category, errs.CategoryAPI)
+			}
+			if problem.Subtype != errs.SubtypeServerError {
+				t.Fatalf("subtype = %q, want %q", problem.Subtype, errs.SubtypeServerError)
+			}
+			if problem.Code != code {
+				t.Fatalf("code = %d, want %d", problem.Code, code)
+			}
+			if !problem.Retryable {
+				t.Fatal("expected retryable error")
+			}
+			if problem.Hint != driveImportConcurrentOperationHint {
+				t.Fatalf("hint = %q, want %q", problem.Hint, driveImportConcurrentOperationHint)
+			}
+		})
+	}
+}
+
+func TestDriveImportFailureErrorLeavesOtherFailuresUnchanged(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name string
+		msg  string
+	}{
+		{
+			name: "ordinary failure",
+			msg:  "unsupported conversion",
+		},
+		{
+			name: "longer numeric code containing known code",
+			msg:  "call CreateObjNode return error code, code: 12321401012, message:",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			err := driveImportFailureError(driveImportStatus{
+				JobStatus:   3,
+				JobErrorMsg: tt.msg,
+			})
+			problem, ok := errs.ProblemOf(err)
+			if !ok {
+				t.Fatalf("expected typed error, got %T", err)
+			}
+			if problem.Code != 0 {
+				t.Fatalf("code = %d, want 0", problem.Code)
+			}
+			if problem.Retryable {
+				t.Fatal("expected non-concurrency failure to remain non-retryable")
+			}
+			if problem.Hint != "" {
+				t.Fatalf("hint = %q, want empty", problem.Hint)
+			}
+		})
+	}
+}
+
 func TestDriveImportTimeoutReturnsFollowUpCommand(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
 	reg.Register(&httpmock.Stub{
--- a/skill-template/domains/drive.md
+++ b/skill-template/domains/drive.md
@@ -6,6 +6,7 @@
 - 用户要把本地 `.xlsx` / `.csv` / `.base` 导入成 Base / 多维表格 / bitable，第一步必须使用 `lark-cli drive +import --type bitable`。
 - 用户要把本地 `.md` / `.docx` / `.doc` / `.txt` / `.html` 导入成在线文档，使用 `lark-cli drive +import --type docx`。
 - 用户要把本地 `.xlsx` / `.xls` / `.csv` 导入成电子表格，使用 `lark-cli drive +import --type sheet`。
+- 批量执行 `drive +import` 且目标是同一个位置（同一 `--folder-token`、默认根目录，或同一 `--target-token`）时，必须串行执行；不要并发导入到同一位置，服务端可能返回并发冲突错误。
 - 用户要在云空间里新建文件夹，优先使用 `lark-cli drive +create-folder`。
 - `lark-base` 只负责导入完成后的 Base 内部操作（表、字段、记录、视图），不要在“本地文件 -> Base”这一步提前切到 `lark-base`。

@@ -194,6 +195,7 @@ lark-cli drive file.comments list --params '{"file_token": "xxx", "file_type": "
 | `not exist` | 使用了错误的 token | 检查 token 类型，wiki 链接必须先查询获取 `obj_token` |
 | `permission denied` | 没有相关操作权限 | 引导用户检查当前身份对文档/文件是否有相应操作权限；如果需要，可以授予相应权限 |
 | `invalid file_type` | file_type 参数错误 | 根据 `obj_type` 传入正确的 file_type（docx/doc/sheet/slides/bitable） |
+| `232140101` / `232140100` / `233523001`（常见于 `drive +import` 的 `job_error_msg`） | 同一位置下存在并发导入 / 创建操作 | 批量导入到同一文件夹、根目录或同一 `--target-token` 时改为串行执行；每个失败项每次重试前等待几秒，总共最多重试 3 次，仍失败就停止并报告冲突 |

 ### 授权当前应用访问文档

--- a/skills/lark-calendar/SKILL.md
+++ b/skills/lark-calendar/SKILL.md
@@ -45,13 +45,15 @@ lark-cli calendar +agenda --as user
 | 场景 | 前置要求 |
 |------|----------|
 | 预约日程/会议、查会议室 | 先读 [lark-calendar-schedule-meeting.md](references/lark-calendar-schedule-meeting.md) |
-| 编辑已有日程 | 先定位目标日程 `event_id`；若是重复性日程，必须定位到具体实例的 `event_id`（禁止使用原重复日程 ID） |
+| 编辑已有日程 | 先定位目标日程 `event_id` |
+| 编辑/删除重复性日程 | 先读 [重复性日程操作规范](references/lark-calendar-recurring.md)，按操作范围（仅此次/全部/此次及后续）执行 |
 | 删除/修改后验证 | 等待 2 秒再查询（API 最终一致性），不要告知用户你等待了 |
 | 调用任何 Shortcut | 先读其对应 reference 文档 |

 ## 核心概念

- **日程实例（Instance）**：重复性日程展开后的具体时间实例。操作重复日程的某次实例时，必须先定位该实例的 `event_id`，禁止使用原重复日程的 `event_id`。
+- **日程实例（Instance）**：重复性日程展开后的具体时间实例。「仅此次」操作时使用具体实例的 `event_id`；「全部」或「此次及后续」操作时需对原重复性日程操作（使用原日程 `event_id`），并按需处理例外。
+- **重复性日程例外（Exception）**：对重复性日程某次实例做过「仅此次」编辑后产生的独立日程（拥有独立 `event_id`）。删除/更新「全部」时必须同时处理例外，否则例外会残留。
 - **全天日程（All-day Event）**：只按日期占用、没有具体起止时刻的日程，结束日期是包含在日程时间内的。
 - **时间块 vs 时间范围**：时间块是具体确定的连续时间段（如 `14:00~15:00`），时间范围是泛指（如"今天下午"）。`+room-find` 必须基于确定时间块，不能基于模糊范围。
 - **会议室（Room）**："room"不是"房间"，是"会议室"。会议室是日程的一种参与人（resource attendee），不能脱离日程单独预定。
@@ -71,6 +73,7 @@ lark-cli calendar +agenda --as user
 | 从日程获取关联的视频会议 ID 或用户绑定的会议纪要文档 | 本 skill（`+meeting`） |
 | 从日程进一步拿 AI 智能纪要 / 逐字稿 / 妙记产物 | 先 `+meeting` 取 `meeting_id`，再 [`vc +detail`](../lark-vc/references/lark-vc-detail.md) → [`note +detail`](../lark-note/references/lark-note-detail.md) / [`minutes +detail`](../lark-minutes/references/lark-minutes-detail.md) |
 | 预约/改约日程、添加/移除参会人、添加/更换会议室、调整时间 | 先判断新建 vs 编辑，再进入 [schedule-meeting 工作流](references/lark-calendar-schedule-meeting.md) |
+| 编辑/删除重复性日程（「改这个重复日程」「删掉后面的」「全部取消」等） | 先读 [重复性日程操作规范](references/lark-calendar-recurring.md)，确认操作范围后执行 |

 ## 任务类型分流

--- a/skills/lark-calendar/references/lark-calendar-create.md
+++ b/skills/lark-calendar/references/lark-calendar-create.md
@@ -47,6 +47,7 @@ lark-cli calendar +create --summary "..." --start "..." --end "..." \
 > 自动设置 `reminders: [{"minutes": 5}]`，默认日程开始前 5 分钟提醒。
 > 自动设置 `vchat: {"vc_type": "vc"}`，默认日程包含飞书视频会议。如需其他视频会议类型或不含视频会议，请使用完整 API 命令。
 > 失败保护：若添加参会人失败（如 open_id 错误），CLI 会自动删除刚创建的空日程（回滚，不通知参会人）。
+> 审批会议室：`+create` 不暴露低频字段 `attendees[].approval_reason`。如果会议室要求审批，请使用用户身份先创建日程，再用完整 API `calendar event.attendees create --as user` 添加会议室并传 `approval_reason`。

 ## 高级用法（完整 API 命令）

@@ -72,9 +73,16 @@ lark-cli calendar events create \
 lark-cli schema calendar.event.attendees.create
 ## 添加参会人
 lark-cli calendar event.attendees create \
+  --as user \
  --params '{"calendar_id":"<CALENDAR_ID>","event_id":"<EVENT_ID>"}' \
  --data '{"attendees": [{"type": "user", "user_id": "ou_xxx"}]}'

+## 添加需要审批的会议室（approval_reason 最大 200 字符）
+lark-cli calendar event.attendees create \
+  --as user \
+  --params '{"calendar_id":"<CALENDAR_ID>","event_id":"<EVENT_ID>"}' \
+  --data '{"attendees": [{"type": "resource", "room_id": "omm_xxx", "approval_reason": "申请原因"}]}'
+
 # 可选第三步（推荐）：若第二步失败，回滚删除空日程
 ## 查看完整参数定义
 lark-cli schema calendar.events.delete
--- a/skills/lark-calendar/references/lark-calendar-recurring.md
+++ b/skills/lark-calendar/references/lark-calendar-recurring.md
@@ -0,0 +1,90 @@
+# 重复性日程操作规范
+
+重复性日程的编辑/删除分为三种范围：「仅此次」「全部」「此次及后续」。用户未明确范围时，**必须询问确认**。
+
+## 关键概念
+
+- **event_id 结构**：`event_id` 的格式为 `{event_uid}_{originalTime}`。普通日程或重复性日程本体的 `originalTime` 为 `0`；例外的 `originalTime > 0`，代表该例外在原重复性序列中本来的时间位置。因此 `{event_uid}_0` 即为原重复性日程的 `event_id`。
+- **原重复性日程**：携带 `rrule` 的日程本体，`event_id` 形如 `{event_uid}_0`。系列的所有属性（标题、时间、rrule、描述等）都挂在本体上。
+- **例外（Exception）**：对某次实例做过「仅此次」编辑后产生的独立日程，`event_id` 形如 `{event_uid}_{originalTime}`（`originalTime > 0`）。通过 `event_uid` 部分即可关联回原重复性日程。
+- 删除/更新原重复性日程 **不会** 级联处理例外——必须手动逐个处理。
+
+## 前置步骤（所有范围通用）
+
+1. 通过 `+agenda` 或 `+search-event` 定位重复性日程，获取原重复性日程的 `event_id`。
+2. 通过 `events instance_view` 或 `+agenda` 列出实例，识别哪些是例外（`event_id` 中 `originalTime > 0` 的即为例外）。
+3. 确认用户的操作范围。
+
+## 编辑全部（更新时间）
+
+| 步骤 | 命令 | 说明 |
+|------|------|------|
+| 1 | `lark-cli calendar +update --event-id <原重复日程ID> --start ... --end ...` | 更新原重复性日程的时间 |
+| 2 | `lark-cli calendar events delete --params '{"calendar_id":"<CAL_ID>","event_id":"<例外ID>","need_notification":false}'` （逐个） | 时间变更后例外已无意义，必须删除 |
+
+> 理由：更新时间会改变重复起止点，例外日程的原始占位已变，若保留会导致时间冲突或残留。
+
+## 编辑全部（更新非时间字段）
+
+| 步骤 | 命令 | 说明 |
+|------|------|------|
+| 1 | `lark-cli calendar +update --event-id <原重复日程ID> --summary ... --description ...` | 更新原重复性日程的标题/描述等 |
+| 2 | `lark-cli calendar +update --event-id <例外ID> --summary ... --description ...` （逐个） | 同步更新例外日程的对应字段 |
+
+> 理由：例外已脱离原重复性日程独立存在，不会自动继承原日程的更新。
+
+## 删除全部
+
+| 步骤 | 命令 | 说明 |
+|------|------|------|
+| 1 | `lark-cli calendar events delete --params '{"calendar_id":"<CAL_ID>","event_id":"<原重复日程ID>","need_notification":true}'` | 删除重复性日程本体 |
+| 2 | `lark-cli calendar events delete --params '{"calendar_id":"<CAL_ID>","event_id":"<例外ID>","need_notification":false}'` （逐个） | 删除所有例外日程 |
+
+> 理由：例外是独立实体，删除原重复性日程不会级联删除例外。
+
+## 编辑此次及后续
+
+| 步骤 | 命令 | 说明 |
+|------|------|------|
+| 1 | `lark-cli calendar +update --event-id <原重复日程ID> --rrule "FREQ=...;UNTIL=<截止日期>"` | 截短原重复性日程（UNTIL 设为指定时间前一次实例的日期） |
+| 2 | `lark-cli calendar events delete ...` （逐个） | 删除指定时间之后（含）的例外日程 |
+| 3 | `lark-cli calendar +create --summary ... --start <指定时间> --end ... --rrule "FREQ=..." --attendee-ids ...` | 从指定时间开始创建新的重复性日程（即「后续」部分，携带编辑后的内容） |
+
+> UNTIL 计算规则：若用户选择「从第 N 次开始编辑」，UNTIL 应设置为第 N-1 次实例的日期（即保留到指定时间之前的最后一次）。
+> 新日程应继承原日程的参会人、会议室等配置（除非用户明确要修改）。
+
+## 删除此次及后续
+
+| 步骤 | 命令 | 说明 |
+|------|------|------|
+| 1 | `lark-cli calendar +update --event-id <原重复日程ID> --rrule "FREQ=...;UNTIL=<截止日期>"` | 截短原重复性日程（UNTIL 设为指定时间前一次实例的日期） |
+| 2 | `lark-cli calendar events delete ...` （逐个） | 删除指定时间之后（含）的例外日程 |
+
+> 与「编辑此次及后续」的区别：不需要步骤 3（创建新的重复性日程），因为目标是删除后续而非替换。
+
+## 仅此次
+
+- **编辑仅此次**：通过 `+agenda` / `+search-event` 定位到具体实例的 `event_id`，然后正常调用 `+update`。
+- **删除仅此次**：定位到具体实例的 `event_id`，调用 `events delete`。
+
+## 用户意图映射
+
+| 用户表达 | 操作范围 |
+|----------|----------|
+| 「改这个重复日程的标题」「全部改」「每次都改」 | 编辑全部 |
+| 「删掉这个重复日程」「取消所有」 | 删除全部 |
+| 「从下周开始改时间」「后面的都改」 | 编辑此次及后续 |
+| 「从下周开始不要了」「后面的都删」 | 删除此次及后续 |
+| 「就改这一次」「只删这一次」 | 仅此次 |
+| 未明确范围 | **必须询问用户** |
+
+## 注意事项
+
+- 涉及时间戳计算（如推算 UNTIL 日期）时，必须调用系统命令或脚本，禁止心算。
+
+## 参考
+
+- [lark-calendar](../SKILL.md) — 日历全部命令
+- [lark-calendar-update](lark-calendar-update.md) — 更新日程 Shortcut
+- [lark-calendar-create](lark-calendar-create.md) — 创建日程 Shortcut
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数
--- a/skills/lark-calendar/references/lark-calendar-update.md
+++ b/skills/lark-calendar/references/lark-calendar-update.md
@@ -43,7 +43,7 @@ lark-cli calendar +update \

 | 参数 | 必填 | 说明 |
 |------|------|------|
-| `--event-id <id>` | 是 | 要更新的日程 ID。重复性日程要先定位到目标实例的 `event_id`，不要直接使用原重复日程 ID |
+| `--event-id <id>` | 是 | 要更新的日程 ID。重复性日程请根据操作范围选择 ID，详见 [重复性日程操作规范](lark-calendar-recurring.md) |
 | `--calendar-id <id>` | 否 | 日历 ID（省略则使用 `primary`） |
 | `--summary <text>` | 否 | 新日程标题。仅在显式传入 `--summary` 时更新；若传空字符串，会把标题清空 |
 | `--description <text>` | 否 | 新日程描述。目前 API 方式不支持编辑富文本描述；如果日程描述通过客户端编辑为富文本内容，则使用 API 更新描述会导致富文本格式丢失。仅在显式传入 `--description` 时更新；若传空字符串，会把描述清空 |
@@ -65,7 +65,7 @@ lark-cli calendar +update \
 - 只想修改标题、描述、时间或重复规则时，不需要同时传 `--add-attendee-ids` 或 `--remove-attendee-ids`。
 - 如需替换某个参与人、群组或会议室，使用 `--remove-attendee-ids <旧ID>` + `--add-attendee-ids <新ID>`。
 - 会议室是 resource attendee，必须使用 `omm_` ID 添加到参会人列表，不能脱离日程单独预定。
- 更新重复性日程的某一次实例时，必须先通过 `+agenda`、`+search-event` 或实例视图定位该实例的 `event_id`。
+- 更新重复性日程时，必须先确定操作范围（仅此次/全部/此次及后续），然后按 [重复性日程操作规范](lark-calendar-recurring.md) 执行。
 - 如果需要验证更新结果，等待至少 2 秒后再查询，避免同步延迟导致读到旧数据。
 - 当同一次命令组合多个动作时，执行顺序为“日程字段 -> 移除参会人 -> 添加参会人”。若中途失败，不会自动回滚已成功步骤；错误信息会说明已完成的步骤。

--- a/skills/lark-doc/references/style/lark-doc-create-workflow.md
+++ b/skills/lark-doc/references/style/lark-doc-create-workflow.md
@@ -23,7 +23,7 @@
 1. 分析用户需求：受众、目的、范围
 2. 设计大纲：根据任务自然选择结构。可以是短文、纪要、FAQ、方案、报告、清单或其他形式；不要默认套固定章节、固定开头或固定富 block 配比
 3. `docs +create` 创建并撰写：
-   - **短文档**：一次写入完整内容
+   - **短文档**：一次写入完整内容。使用 Markdown 时，避免同时传入 `--title` 和同名 `# 标题`
   - **长文档**：先建骨架（标题 + 各级标题），再由主 Agent **顺序逐节**用 `block_insert_after --block-id <章节标题 block_id>` 补全正文；写完一节再写下一节，始终带着已写内容的上下文，保证衔接、不重复
   - ⚠️ 不要一次性把超长完整内容塞进 `--content`，容易触发字符/参数限制；长文按节分次写入
   - ⚠️ 同一节内多次插入时，要锚到**上一个新插入的 block**（按 [`lark-doc-update.md`](../lark-doc-update.md) 的「Block ID 生命周期」），否则反复锚同一个标题会让段落顺序颠倒
@@ -41,6 +41,7 @@
 7. **优先处理步骤二识别出的画板需求**：读取并按 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md) 选型和插入；正文本身不交给 SubAgent
 8. 由**主 Agent 自行润色**（不另起内容子 Agent，正文始终一人维护）：文字密集且不易读时，优先拆段、加小标题或调整顺序——叙述内容保持成段，**不要默认改成列表**，只有确属并列要点 / 步骤才用列表（见 `lark-doc-style.md`）；只有确实存在行列数据时才用 `<table>`。其余富 block 的取舍一律遵循 `lark-doc-style.md` 的写作原则，不主动堆叠。需要明显分隔的主题可补充 `<hr/>`，不强制章节间都使用。本地图片使用 `docs +media-insert` 插入

-### 步骤四：专项校验（按需执行）
+### 步骤四：专项校验

-9. 仅当用户预期需要校验字数时，才读取并执行 [`lark-doc-word-stat.md`](../lark-doc-word-stat.md) 的「字数遵循校验」；否则跳过本项，不读取该 workflow。若执行了专项校验，向用户呈现结果
+9. **字数门禁**：如果用户给出任何明确字数要求（如“700-800 字”“1000 字左右”“不少于 500 字”“控制在 800 字以内”），本步骤必须执行，不属于按需项。读取并执行 [`lark-doc-word-stat.md`](../lark-doc-word-stat.md) 的「字数遵循校验」；未得到脚本统计结果前，不得向用户声明“符合字数要求”。若没有明确字数要求，则跳过本项，不读取该 workflow。若执行了专项校验，向用户呈现目标区间、`word_count` 和达标结论
+10. **重复标题检查**：文档生成后，检查文档标题和正文第一个标题块是否重复；若重复，删除或改写正文第一个标题块，避免读者看到同一标题连续出现
--- a/skills/lark-drive/SKILL.md
+++ b/skills/lark-drive/SKILL.md
@@ -29,6 +29,7 @@ metadata:
 - 用户要把本地 `.xlsx` / `.csv` / `.base` 导入成 Base / 多维表格 / bitable，第一步必须使用 `lark-cli drive +import --type bitable`。
 - 用户要把本地 `.md` / `.docx` / `.doc` / `.txt` / `.html` 导入成在线文档，使用 `lark-cli drive +import --type docx`。
 - 用户要把本地 `.pptx` 导入成飞书幻灯片，使用 `lark-cli drive +import --type slides`；当前 PPTX 导入上限是 500MB。
+- 批量执行 `drive +import` 且目标是同一个位置（同一 `--folder-token`、默认根目录，或同一 `--target-token`）时，必须串行执行；不要并发导入到同一位置，服务端可能返回并发冲突错误。
 - 用户要在 Drive 里上传、创建、读取、局部 patch 或覆盖更新**原生 `.md` 文件**（不是导入成 docx），切到 [`lark-markdown`](../lark-markdown/SKILL.md)。
 - 用户要比较原生 `.md` 文件的**历史版本差异**，或比较远端 Markdown 与本地草稿，切到 [`lark-markdown`](../lark-markdown/SKILL.md) 的 `lark-cli markdown +diff`；需要版本号时先用 `drive +version-history`。
 - 用户要查看、下载、回滚或删除文件的**历史版本**，使用 `drive +version-history`、`drive +version-get`、`drive +version-revert`、`drive +version-delete`；这组命令同时支持 `--as user` 和 `--as bot`，自动化场景优先 `--as bot`。
@@ -102,6 +103,7 @@ lark-cli drive +inspect --url 'https://xxx.feishu.cn/wiki/wikcnXXX'
 | `not exist` | 使用了错误的 token | 检查 token 类型，wiki 链接必须先查询获取 `obj_token` |
 | `permission denied` | 没有相关操作权限 | 引导用户检查当前身份对文档/文件是否有相应操作权限；如果需要，可以授予相应权限 |
 | `invalid file_type` | file_type 参数错误 | 根据 `obj_type` 传入正确的 file_type（docx/doc/sheet/slides/bitable） |
+| `232140101` / `232140100` / `233523001`（常见于 `drive +import` 的 `job_error_msg`） | 同一位置下存在并发导入 / 创建操作 | 批量导入到同一文件夹、根目录或同一 `--target-token` 时改为串行执行；每个失败项每次重试前等待几秒，总共最多重试 3 次，仍失败就停止并报告冲突 |

 ### 权限能力入口

--- a/skills/lark-drive/references/lark-drive-import.md
+++ b/skills/lark-drive/references/lark-drive-import.md
@@ -14,6 +14,13 @@
 > [!IMPORTANT]
 > 当用户**未传 `--name`** 时，文档标题默认取源文件名（去掉扩展名）。在执行导入前，先友好提示用户：「当前未指定文档标题，默认将使用"xxx"作为标题。如果文件内容中也包含相同标题，导入后可能造成视觉重复。是否需要重命名？」让用户确认后再继续。

+## 批量导入串行规则
+
+> [!IMPORTANT]
+> 批量执行 `drive +import` 且目标是同一个位置时，必须串行执行，不要并发发起导入任务。这里的“相同位置”包括同一个 `--folder-token`、都省略 `--folder-token` 导入到默认根目录，或使用同一个 `--target-token` 导入到已有 bitable。
+>
+> 如果在同一位置下并发导入，服务端可能返回并发冲突错误。看到错误信息或 `job_error_msg` 中包含 `232140101`、`232140100`、`233523001` 任一错误码时，按同位置并发操作处理：停止并发导入，改为串行处理失败项；每个失败项每次重试前等待几秒，总共最多重试 3 次；仍失败就停止并向用户报告冲突。
+
 ## 命令

 ```bash
@@ -143,6 +150,7 @@ lark-cli drive +import --file ./README.md --type docx --dry-run
 - “超过 20MB 自动切换分片上传”只表示上传链路会切到 multipart，不代表所有格式都允许导入超过 20MB 的文件。

 - 若导入任务执行失败，会返回失败时的 `job_status` 及错误信息。
+- 若导入失败信息包含 `232140101`、`232140100`、`233523001`，通常表示同一位置下存在并发导入 / 创建操作；批量场景请改为串行执行，每个失败项每次重试前等待几秒，总共最多重试 3 次，仍失败就停止并报告冲突。
 - 若内置轮询超时但任务仍在处理中，shortcut 会成功返回，并带上：
  - `ready=false`
  - `timed_out=true`
--- a/skills/lark-shared/SKILL.md
+++ b/skills/lark-shared/SKILL.md
@@ -146,6 +146,24 @@ lark-cli update

 **重要**：始终使用 `lark-cli update` 更新，它会同时更新 CLI 和 AI Skills。

+## JSON 输出契约
+
+`--format json`（默认）下，成功与错误的信封结构不同：
+
+成功信封写入 **stdout**（退出码 0）：
+
+```json
+{ "ok": true, "identity": "user", "data": { "guid": "..." }, "meta": { "count": 1 } }
+```
+
+错误信封写入 **stderr**（退出码非 0）：
+
+```json
+{ "ok": false, "identity": "user", "error": { "type": "api", "subtype": "...", "code": 99991679, "message": "...", "hint": "..." } }
+```
+
+**判断成功必须用 `ok == true`（或进程退出码 0），不要用 `code == 0`**：成功信封没有顶层 `code` / `msg` 字段，`code` 只出现在错误信封的 `error` 内，含义是上游 OpenAPI 的 numeric code。按 OpenAPI 老格式 `{"code": 0, "msg": "ok"}` 判断会把所有成功调用误判为失败；封装写入类命令（如 `task +create`）时尤其危险，误判会绕过幂等逻辑导致重复创建。
+
 ## 安全规则

 - **禁止输出密钥**（appSecret、accessToken）到终端明文。
--- a/skills/lark-task/references/lark-task-create.md
+++ b/skills/lark-task/references/lark-task-create.md
@@ -46,7 +46,20 @@ lark-cli task +create --summary "Test Task" --dry-run
 1. Confirm with the user: task summary, due date, assignee, and tasklist if necessary.
   - **Crucial Rule for Assignee**: If the user explicitly or implicitly says "create a task for me" (给我创建一个任务), or "help me create a task" (帮我新建/创建一个任务), you MUST assign the task to the current logged-in user. You can get the current user's `open_id` by executing `lark-cli auth status` (it already outputs JSON by default, so do not add `--json`) or `lark-cli contact +get-user` first, extracting `.identities.user.openId` (from `auth status`) or `.data.user.open_id` (from `contact +get-user`), and then passing it to the `--assignee` parameter.
 2. Execute `lark-cli task +create --summary "..." ...`
-3. Report the result: task ID and summary.
+3. Judge success by `ok == true` in the stdout JSON (the success envelope has no `code` field — do not test `code == 0`), then report the result: task ID (`data.guid`) and summary.
+
+Example success response:
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": {
+    "guid": "e297d3d0-4b60-4a5f-a4d4-xxxxxxxxxxxx",
+    "url": "https://applink.larkoffice.com/client/todo/detail?guid=e297d3d0-4b60-4a5f-a4d4-xxxxxxxxxxxx"
+  }
+}
+```

 > [!CAUTION]
 > This is a **Write Operation** -- You must confirm the user's intent before executing.
Author	SHA1	Message	Date
liangshuo-1	6c3649633d	chore: release v1.0.66	2026-07-06 21:22:00 +08:00
liangshuo-1	91d785f92f	refactor(envvars): consolidate agent env value access (#1757 ) * feat(envvars): add LARKSUITE_CLI_AGENT_NAME accessor envvars.AgentName() reads LARKSUITE_CLI_AGENT_NAME so business code can identify the agent driving the CLI. Value is sanitised (trim, reject control chars, 128-byte cap) and returns "" when unset or invalid. Local-only; not sent to the server. * refactor(envvars): consolidate agent env accessors, dedupe sanitize Move agent-trace reading from cmdutil.AgentTraceValue into envvars.AgentTrace(), symmetric with AgentName and sharing one sanitizeSingleLine. secheader.go now only assembles headers (BaseSecurityHeaders calls envvars.AgentTrace()); the duplicated sanitize and its os/unicode imports are gone. The X-Agent-Trace header and its behaviour are unchanged. --------- Co-authored-by: liangshuo-1 <266696938+liangshuo-1@users.noreply.github.com>	2026-07-06 21:17:51 +08:00
leave330	e621c6e50f	fix: support pnpm global installs in self-update (#1705 )	2026-07-06 21:11:01 +08:00
Zee Zheng	869a259d4e	docs: clarify success envelope contract — judge success by ok, not code (#1730 ) The stdout success envelope is {ok, identity, data, meta?} and carries no top-level code/msg field, but wrappers following the raw OpenAPI convention test code == 0 and misclassify every successful call as a failure. Around write commands this defeats caller-side idempotency and causes duplicate creates (see #1689). Document the contract in ERROR_CONTRACT.md (success-envelope counterpart to the error wire format), both READMEs (JSON Output Contract section), the lark-shared skill (shared prerequisite for all skills), and add a success response example to lark-task-create.md. Closes #1689	2026-07-06 20:03:05 +08:00
fangshuyu-768	ee46e22abd	docs: tighten doc creation validation workflow (#1759 )	2026-07-06 17:07:10 +08:00
hhang	b76dc18c2f	fix(calendar): guide approval room booking fallback (#1637 )	2026-07-06 15:04:50 +08:00
calendar-assistant	85679d4258	feat: support semantic recurring calendar operations (#1723 )	2026-07-06 14:10:57 +08:00
wangweiming-01	1ba4f3973c	fix: guide drive import concurrency conflicts (#1751 )	2026-07-06 10:46:46 +08:00
liangshuo-1	c45ff569c4	chore: release v1.0.65 (#1742 )	2026-07-03 20:25:22 +08:00