feat: support lark suite hybrid skills layout

feat: add docs history shortcuts (#1612 )
Add docs +history-list, +history-revert, and +history-revert-status backed by docs_ai history OpenAPI endpoints. Document the safe history workflow and extend dry-run/live E2E coverage for the new shortcuts.
2026-07-07 09:11:44 +08:00 · 2026-07-03 17:43:52 +08:00 · 2026-07-03 16:21:18 +08:00 · 2026-07-03 15:55:46 +08:00
35 changed files with 2242 additions and 514 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -27,6 +27,9 @@ Thumbs.db
 # Go
 docs/ref
 docs/
+!tests/cli_e2e/docs/
+!tests/cli_e2e/docs/*.go
+!tests/cli_e2e/docs/*.md
 vendor/


--- a/cmd/api/api_test.go
+++ b/cmd/api/api_test.go
@@ -20,13 +20,28 @@ import (
 	"github.com/spf13/cobra"
 )

+func newTestApiCmd(f *cmdutil.Factory, runF func(*APIOptions) error) *cobra.Command {
+	cmd := NewCmdApi(f, runF)
+	cmd.SilenceErrors = true
+	cmd.SilenceUsage = true
+	return cmd
+}
+
+func newTestRootCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:           "lark-cli",
+		SilenceErrors: true,
+		SilenceUsage:  true,
+	}
+}
+
 func TestApiCmd_FlagParsing(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})

 	var gotOpts *APIOptions
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		gotOpts = opts
 		return nil
 	})
@@ -54,7 +69,7 @@ func TestApiCmd_DryRun(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})

-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/test", "--as", "bot", "--dry-run"})
 	err := cmd.Execute()
 	if err != nil {
@@ -77,7 +92,7 @@ func TestApiCmd_NullParamsWithPageSize(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})

-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/test", "--params", "null", "--page-size", "50", "--as", "bot", "--dry-run"})
 	if err := cmd.Execute(); err != nil {
 		t.Fatalf("--params null with --page-size should not error, got: %v", err)
@@ -98,7 +113,7 @@ func TestApiCmd_BotMode(t *testing.T) {
 		Body: map[string]interface{}{"code": 0, "msg": "ok", "data": map[string]interface{}{"result": "success"}},
 	})

-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/test", "--as", "bot"})
 	err := cmd.Execute()
 	if err != nil {
@@ -125,7 +140,7 @@ func TestApiCmd_MissingArgs(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})

-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET"}) // missing path
 	err := cmd.Execute()
 	if err == nil {
@@ -138,7 +153,7 @@ func TestApiCmd_InvalidParamsJSON(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})

-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/test", "--as", "bot", "--params", "{bad"})
 	err := cmd.Execute()
 	if err == nil {
@@ -151,7 +166,7 @@ func TestApiValidArgsFunction(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})

-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	fn := cmd.ValidArgsFunction

 	tests := []struct {
@@ -217,7 +232,7 @@ func TestNewCmdApi_StrictModeHidesAsFlag(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu, SupportedIdentities: 2,
 	})

-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	flag := cmd.Flags().Lookup("as")
 	if flag == nil {
 		t.Fatal("expected --as flag to be registered")
@@ -236,7 +251,7 @@ func TestApiCmd_PageLimitDefault(t *testing.T) {
 	})

 	var gotOpts *APIOptions
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		gotOpts = opts
 		return nil
 	})
@@ -255,7 +270,7 @@ func TestApiCmd_ParamsAndDataBothStdinConflict(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})

-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"POST", "/open-apis/test", "--as", "bot", "--params", "-", "--data", "-"})
 	err := cmd.Execute()
 	if err == nil {
@@ -272,7 +287,7 @@ func TestApiCmd_OutputAndPageAllConflict(t *testing.T) {
 	})

 	var gotOpts *APIOptions
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		gotOpts = opts
 		return apiRun(opts)
 	})
@@ -297,7 +312,7 @@ func TestApiCmd_BinaryResponse_AutoSave(t *testing.T) {
 		ContentType: "application/octet-stream",
 	})

-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/drive/v1/files/xxx/download", "--as", "bot"})
 	err := cmd.Execute()
 	if err != nil {
@@ -328,7 +343,7 @@ func TestApiCmd_PageAll_NonBatchAPI_FallbackToJSON(t *testing.T) {
 		},
 	})

-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/contact/v3/users/u123", "--as", "bot", "--page-all", "--format", "ndjson"})
 	err := cmd.Execute()
 	if err != nil {
@@ -368,7 +383,7 @@ func TestApiCmd_PageAll_NonBatchAPI_ErrorStillOutputsJSON(t *testing.T) {
 		},
 	})

-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/im/v1/chats/oc_xxx/announcement", "--as", "bot", "--page-all"})
 	err := cmd.Execute()
 	// Should return an error
@@ -409,7 +424,7 @@ func TestApiCmd_PageAll_BatchAPI_StreamsItems(t *testing.T) {
 		},
 	})

-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all", "--format", "ndjson"})
 	err := cmd.Execute()
 	if err != nil {
@@ -448,7 +463,7 @@ func TestApiCmd_PageAll_StreamBusinessErrorDoesNotDumpJSON(t *testing.T) {
 		},
 	})

-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all", "--format", "ndjson"})
 	err := cmd.Execute()
 	if err == nil {
@@ -483,7 +498,7 @@ func TestApiCmd_PageAll_BatchAPI_DefaultJSONEnvelope(t *testing.T) {
 		},
 	})

-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all"})
 	if err := cmd.Execute(); err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -549,8 +564,8 @@ func TestApiCmd_PageAll_DefaultJSONRunsContentSafety(t *testing.T) {
 		},
 	})

-	root := &cobra.Command{Use: "lark-cli"}
-	root.AddCommand(NewCmdApi(f, nil))
+	root := newTestRootCmd()
+	root.AddCommand(newTestApiCmd(f, nil))
 	root.SetArgs([]string{"api", "GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all"})
 	if err := root.Execute(); err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -600,8 +615,8 @@ func TestApiCmd_PageAll_StreamFormatRunsContentSafety(t *testing.T) {
 		},
 	})

-	root := &cobra.Command{Use: "lark-cli"}
-	root.AddCommand(NewCmdApi(f, nil))
+	root := newTestRootCmd()
+	root.AddCommand(newTestApiCmd(f, nil))
 	root.SetArgs([]string{"api", "GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all", "--format", "ndjson"})
 	if err := root.Execute(); err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -656,8 +671,8 @@ func TestApiCmd_PageAll_StreamFormatBlockSkipsBlockedPage(t *testing.T) {
 		},
 	})

-	root := &cobra.Command{Use: "lark-cli"}
-	root.AddCommand(NewCmdApi(f, nil))
+	root := newTestRootCmd()
+	root.AddCommand(newTestApiCmd(f, nil))
 	root.SetArgs([]string{"api", "GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all", "--format", "ndjson"})
 	err := root.Execute()
 	if err == nil {
@@ -721,7 +736,7 @@ func TestApiCmd_JqFlag_Parsing(t *testing.T) {
 	})

 	var gotOpts *APIOptions
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		gotOpts = opts
 		return nil
 	})
@@ -741,7 +756,7 @@ func TestApiCmd_JqFlag_ShortForm(t *testing.T) {
 	})

 	var gotOpts *APIOptions
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		gotOpts = opts
 		return nil
 	})
@@ -760,7 +775,7 @@ func TestApiCmd_JqAndOutputConflict(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})

-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		return apiRun(opts)
 	})
 	cmd.SetArgs([]string{"GET", "/open-apis/test", "--as", "bot", "--jq", ".data", "--output", "file.bin"})
@@ -791,7 +806,7 @@ func TestApiCmd_JqFilter_AppliesExpression(t *testing.T) {
 		},
 	})

-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/test/jq", "--as", "bot", "--jq", ".data.items[].name"})
 	err := cmd.Execute()
 	if err != nil {
@@ -812,7 +827,7 @@ func TestApiCmd_JqAndFormatConflict(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})

-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		return apiRun(opts)
 	})
 	cmd.SetArgs([]string{"GET", "/open-apis/test", "--as", "bot", "--jq", ".data", "--format", "ndjson"})
@@ -830,7 +845,7 @@ func TestApiCmd_JqInvalidExpression(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})

-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		return apiRun(opts)
 	})
 	cmd.SetArgs([]string{"GET", "/open-apis/test", "--as", "bot", "--jq", "invalid["})
@@ -859,7 +874,7 @@ func TestApiCmd_PageAll_WithJq(t *testing.T) {
 		},
 	})

-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all", "--jq", ".data.items[].id"})
 	err := cmd.Execute()
 	if err != nil {
@@ -880,7 +895,7 @@ func TestApiCmd_MethodUppercase(t *testing.T) {
 	})

 	var gotOpts *APIOptions
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		gotOpts = opts
 		return nil
 	})
@@ -899,7 +914,7 @@ func TestApiCmd_FileFlagParsing(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 	var gotOpts *APIOptions
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		gotOpts = opts
 		return nil
 	})
@@ -917,7 +932,7 @@ func TestApiCmd_FileAndOutputConflict(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		return apiRun(opts)
 	})
 	cmd.SetArgs([]string{"POST", "/open-apis/test", "--as", "bot", "--file", "photo.jpg", "--output", "out.json"})
@@ -934,7 +949,7 @@ func TestApiCmd_FileWithGET(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		return apiRun(opts)
 	})
 	cmd.SetArgs([]string{"GET", "/open-apis/test", "--as", "bot", "--file", "photo.jpg"})
@@ -951,7 +966,7 @@ func TestApiCmd_FileStdinConflictWithData(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		return apiRun(opts)
 	})
 	cmd.SetArgs([]string{"POST", "/open-apis/test", "--as", "bot", "--file", "-", "--data", "-"})
@@ -974,7 +989,7 @@ func TestApiCmd_DryRunWithFile(t *testing.T) {
 	f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"POST", "/open-apis/im/v1/images", "--file", "image=" + tmpFile, "--data", `{"image_type":"message"}`, "--dry-run", "--as", "bot"})
 	err := cmd.Execute()
 	if err != nil {
@@ -1015,7 +1030,7 @@ func TestApiCmd_PermissionError_DerivesFirstClassFields(t *testing.T) {
 		},
 	})

-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/docx/v1/documents/test", "--as", "bot"})
 	err := cmd.Execute()
 	if err == nil {
@@ -1041,7 +1056,7 @@ func TestApiCmd_JsonFlag_Accepted(t *testing.T) {
 	})

 	var gotOpts *APIOptions
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		gotOpts = opts
 		return nil
 	})
--- a/cmd/update/update.go
+++ b/cmd/update/update.go
@@ -86,10 +86,13 @@ func symArrow() string {

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

 // NewCmdUpdate creates the update command.
@@ -108,6 +111,7 @@ Detects the installation method automatically:
 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)
 		},
 	}
@@ -115,6 +119,8 @@ 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
@@ -122,6 +128,9 @@ 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()

@@ -147,7 +156,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)
+			skillsResult = runSkillsAndState(updater, io, cur, opts.Force, opts.SkillsLayout, opts.FlatSkills, opts.FlatSet)
 		}
 		return reportAlreadyUpToDate(opts, io, cur, latest, skillsResult, opts.Check)
 	}
@@ -208,7 +217,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)
+	skillsResult := runSkillsAndState(updater, io, cur, opts.Force, opts.SkillsLayout, opts.FlatSkills, opts.FlatSet)

 	reason := detect.ManualReason()
 	if opts.JSON {
@@ -287,7 +296,7 @@ func doNpmUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string,
 		return output.ErrBare(output.ExitAPI)
 	}

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

 	if opts.JSON {
 		result := map[string]interface{}{
@@ -324,16 +333,20 @@ func verificationFailureHint(updater *selfupdate.Updater, latest string) string
 	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) *skillscheck.SyncResult {
-	if !force {
-		if existing, ok := skillscheck.ReadSyncedVersion(); ok && normalizeVersion(existing) == normalizeVersion(stateVersion) {
+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) {
 			return nil
 		}
 	}
 	result := syncSkills(skillscheck.SyncOptions{
-		Version: stateVersion,
-		Force:   force,
-		Runner:  updater,
+		Version:    stateVersion,
+		Layout:     layout,
+		FlatSkills: flat,
+		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)
@@ -341,6 +354,47 @@ 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
@@ -387,6 +441,12 @@ 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
 }

@@ -397,6 +457,7 @@ 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"
@@ -410,10 +471,17 @@ 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
 }

@@ -425,13 +493,17 @@ 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, "  To retry all official skills: lark-cli update --force\n")
+		fmt.Fprintf(io.ErrOut, "  %s\n", skillsFailureHint())
 	case r.Force:
-		fmt.Fprintf(io.ErrOut, "%s Skills updated: restored all %d official skills\n", symOK(), len(r.Official))
+		fmt.Fprintf(io.ErrOut, "%s Skills updated: restored all %d official skills (%s layout)\n", symOK(), len(r.Official), r.Layout)
 	default:
-		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))
+		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)
 		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
@@ -996,7 +996,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"}); err != nil {
+	if err := skillscheck.WriteState(skillscheck.SkillsState{Version: "1.0.21", Layout: skillscheck.LayoutSeparate}); err != nil {
 		t.Fatal(err)
 	}
 	called := false
@@ -1006,7 +1006,7 @@ func TestRunSkillsAndState_DedupHit(t *testing.T) {
 			return &selfupdate.NpmResult{}
 		},
 	}
-	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false)
+	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false, "", "", false)
 	if got != nil {
 		t.Errorf("runSkillsAndState() = %+v, want nil for dedup hit", got)
 	}
@@ -1015,6 +1015,27 @@ 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 {
@@ -1027,7 +1048,7 @@ func TestRunSkillsAndState_DedupForceBypass(t *testing.T) {
 			return successfulSkillsCommand()(args...)
 		},
 	}
-	got := runSkillsAndState(updater, newTestIO(), "1.0.21", true)
+	got := runSkillsAndState(updater, newTestIO(), "1.0.21", true, "", "", false)
 	if got == nil || got.Err != nil {
 		t.Fatalf("runSkillsAndState(force=true) = %+v, want successful result", got)
 	}
@@ -1039,7 +1060,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)
+	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false, "", "", false)
 	if got == nil || got.Err != nil {
 		t.Fatalf("runSkillsAndState() = %+v, want non-nil with nil Err", got)
 	}
@@ -1050,6 +1071,12 @@ 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) {
@@ -1064,7 +1091,7 @@ func TestRunSkillsAndState_FailureKeepsOldState(t *testing.T) {
 			return r
 		},
 	}
-	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false)
+	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false, "", "", false)
 	if got == nil || got.Err == nil {
 		t.Fatalf("runSkillsAndState() = %+v, want non-nil with non-nil Err", got)
 	}
@@ -1077,6 +1104,57 @@ 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)
@@ -1357,7 +1435,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)
+	got := runSkillsAndState(&selfupdate.Updater{}, f.IOStreams, "1.0.21", false, "", "", false)
 	if got == nil || got.Err == nil {
 		t.Fatalf("runSkillsAndState() = %+v, want non-nil with write error", got)
 	}
--- a/internal/selfupdate/updater.go
+++ b/internal/selfupdate/updater.go
@@ -49,6 +49,8 @@ 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.
@@ -242,6 +244,14 @@ 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")
 }
--- a/internal/selfupdate/updater_test.go
+++ b/internal/selfupdate/updater_test.go
@@ -208,6 +208,13 @@ 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 {
@@ -238,6 +245,34 @@ 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"}]}`)
--- a/internal/skillscheck/layout.go
+++ b/internal/skillscheck/layout.go
@@ -0,0 +1,374 @@
+// 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,10 +23,12 @@ 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"`
 }

@@ -76,6 +78,14 @@ 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{}
@@ -89,4 +99,7 @@ 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,6 +21,7 @@ var (

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

 func PlanSync(input SyncInput) SyncPlan {
-	official := uniqueSorted(input.OfficialSkills)
+	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,
+		}
+	}
 	if input.Force {
 		return SyncPlan{
 			Version:        input.Version,
@@ -229,19 +241,12 @@ 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: skipped,
+		SkippedDeleted: skippedDeleted,
 	}
 }

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

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

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

 func SyncSkills(opts SyncOptions) *SyncResult {
@@ -280,16 +291,26 @@ 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)
 	}

@@ -302,12 +323,17 @@ 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",
@@ -316,25 +342,59 @@ 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 {
@@ -346,6 +406,16 @@ 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{}

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

@@ -411,6 +482,7 @@ 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 {
@@ -419,11 +491,13 @@ 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,
@@ -439,6 +513,7 @@ func fallbackFullInstall(opts SyncOptions, reason string, official []string) *Sy
 			SkippedDeleted: []string{},
 			Detail:         reason + "\nstate write failed: " + writeErr.Error(),
 			Force:          opts.Force,
+			Layout:         LayoutSeparate,
 		}
 	}

@@ -450,9 +525,38 @@ 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,6 +8,7 @@ import (
 	"os"
 	"path/filepath"
 	"reflect"
+	"sort"
 	"strings"
 	"testing"
 	"time"
@@ -216,8 +217,10 @@ type fakeSkillsRunner struct {
 	globalErr        error
 	installErr       error
 	installAllErr    error
+	installSuiteErr  error
 	installed        [][]string
 	installedAll     int
+	installedSuite   int
 	listedIndex      int
 	listedOfficial   int
 	listedGlobalJSON int
@@ -319,6 +322,13 @@ 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)
@@ -574,7 +584,7 @@ func TestSyncSkills_LocalListsFailureFallsBackToFullInstall(t *testing.T) {
 	}
 }

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

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

@@ -697,6 +708,115 @@ 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)
@@ -733,6 +853,43 @@ 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) {
@@ -740,6 +897,38 @@ 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
@@ -0,0 +1,33 @@
+---
+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/shortcuts/doc/docs_history.go
+++ b/shortcuts/doc/docs_history.go
@@ -0,0 +1,261 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package doc
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"strconv"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+type docsHistoryListSpec struct {
+	Doc       documentRef
+	PageSize  int
+	PageToken string
+}
+
+type docsHistoryRevertSpec struct {
+	Doc              documentRef
+	HistoryVersionID string
+	WaitTimeoutMs    int
+}
+
+type docsHistoryRevertStatusSpec struct {
+	Doc    documentRef
+	TaskID string
+}
+
+func parseDocsHistoryDocRef(raw, shortcut string) (documentRef, error) {
+	ref, err := parseDocumentRef(raw)
+	if err != nil {
+		return documentRef{}, err
+	}
+	if ref.Kind == "doc" {
+		return documentRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "docs %s only supports docx documents; use a docx token/URL or a wiki URL that resolves to docx", shortcut).WithParam("--doc")
+	}
+	return ref, nil
+}
+
+func validateDocsHistoryPageSize(pageSize int) error {
+	if pageSize < 1 || pageSize > 20 {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --page-size %d: must be between 1 and 20", pageSize).WithParam("--page-size")
+	}
+	return nil
+}
+
+func validateDocsHistoryVersionID(historyVersionID string) error {
+	version, err := strconv.ParseInt(strings.TrimSpace(historyVersionID), 10, 64)
+	if err != nil {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--history-version-id must be a positive integer string returned by docs +history-list").WithParam("--history-version-id").WithCause(err)
+	}
+	if version <= 0 {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--history-version-id must be a positive integer string returned by docs +history-list").WithParam("--history-version-id")
+	}
+	return nil
+}
+
+func validateDocsHistoryWaitTimeout(timeoutMs int) error {
+	if timeoutMs < 0 || timeoutMs > 30000 {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --wait-timeout-ms %d: must be between 0 and 30000", timeoutMs).WithParam("--wait-timeout-ms")
+	}
+	return nil
+}
+
+func docsHistoryListParams(spec docsHistoryListSpec) map[string]interface{} {
+	params := map[string]interface{}{
+		"page_size": spec.PageSize,
+	}
+	if spec.PageToken != "" {
+		params["page_token"] = spec.PageToken
+	}
+	return params
+}
+
+func docsHistoryRevertBody(spec docsHistoryRevertSpec) map[string]interface{} {
+	return map[string]interface{}{
+		"history_version_id": spec.HistoryVersionID,
+		"wait_timeout_ms":    spec.WaitTimeoutMs,
+	}
+}
+
+func docsHistoryStatusParams(spec docsHistoryRevertStatusSpec) map[string]interface{} {
+	return map[string]interface{}{
+		"task_id": spec.TaskID,
+	}
+}
+
+func docsHistoryAPIPath(docToken, suffix string) string {
+	return fmt.Sprintf("/open-apis/docs_ai/v1/documents/%s/%s", validate.EncodePathSegment(docToken), suffix)
+}
+
+var DocsHistoryList = common.Shortcut{
+	Service:     "docs",
+	Command:     "+history-list",
+	Description: "List Lark document history versions",
+	Risk:        "read",
+	Scopes:      []string{"docx:document:readonly"},
+	AuthTypes:   []string{"user", "bot"},
+	PostMount:   installDocsShortcutHelp("+history-list"),
+	Flags: []common.Flag{
+		{Name: "doc", Desc: "document URL or token", Required: true},
+		{Name: "page-size", Type: "int", Default: "20", Desc: "history entries to return, range 1-20"},
+		{Name: "page-token", Desc: "pagination token from the previous page's page_token"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if _, err := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-list"); err != nil {
+			return err
+		}
+		return validateDocsHistoryPageSize(runtime.Int("page-size"))
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		ref, _ := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-list")
+		spec := docsHistoryListSpec{
+			Doc:       ref,
+			PageSize:  runtime.Int("page-size"),
+			PageToken: strings.TrimSpace(runtime.Str("page-token")),
+		}
+		return common.NewDryRunAPI().
+			Desc("OpenAPI: list document history versions").
+			GET("/open-apis/docs_ai/v1/documents/:document_id/histories").
+			Set("document_id", spec.Doc.Token).
+			Params(docsHistoryListParams(spec))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		ref, _ := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-list")
+		spec := docsHistoryListSpec{
+			Doc:       ref,
+			PageSize:  runtime.Int("page-size"),
+			PageToken: strings.TrimSpace(runtime.Str("page-token")),
+		}
+
+		data, err := runtime.CallAPITyped(
+			http.MethodGet,
+			docsHistoryAPIPath(spec.Doc.Token, "histories"),
+			docsHistoryListParams(spec),
+			nil,
+		)
+		if err != nil {
+			return err
+		}
+		runtime.OutRaw(data, nil)
+		return nil
+	},
+}
+
+var DocsHistoryRevert = common.Shortcut{
+	Service:     "docs",
+	Command:     "+history-revert",
+	Description: "Revert a Lark document to a historical version",
+	Risk:        "write",
+	Scopes:      []string{"docx:document:write_only", "docx:document:readonly"},
+	AuthTypes:   []string{"user", "bot"},
+	PostMount:   installDocsShortcutHelp("+history-revert"),
+	Flags: []common.Flag{
+		{Name: "doc", Desc: "document URL or token", Required: true},
+		{Name: "history-version-id", Desc: "history_version_id from docs +history-list to revert to", Required: true},
+		{Name: "wait-timeout-ms", Type: "int", Default: "30000", Desc: "milliseconds to wait for revert completion before returning, range 0-30000"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if _, err := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-revert"); err != nil {
+			return err
+		}
+		if err := validateDocsHistoryVersionID(runtime.Str("history-version-id")); err != nil {
+			return err
+		}
+		return validateDocsHistoryWaitTimeout(runtime.Int("wait-timeout-ms"))
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		ref, _ := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-revert")
+		spec := docsHistoryRevertSpec{
+			Doc:              ref,
+			HistoryVersionID: strings.TrimSpace(runtime.Str("history-version-id")),
+			WaitTimeoutMs:    runtime.Int("wait-timeout-ms"),
+		}
+		return common.NewDryRunAPI().
+			Desc("OpenAPI: revert document history").
+			POST("/open-apis/docs_ai/v1/documents/:document_id/history/revert").
+			Set("document_id", spec.Doc.Token).
+			Body(docsHistoryRevertBody(spec))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		ref, _ := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-revert")
+		spec := docsHistoryRevertSpec{
+			Doc:              ref,
+			HistoryVersionID: strings.TrimSpace(runtime.Str("history-version-id")),
+			WaitTimeoutMs:    runtime.Int("wait-timeout-ms"),
+		}
+
+		data, err := runtime.CallAPITyped(
+			http.MethodPost,
+			docsHistoryAPIPath(spec.Doc.Token, "history/revert"),
+			nil,
+			docsHistoryRevertBody(spec),
+		)
+		if err != nil {
+			return err
+		}
+		runtime.OutRaw(data, nil)
+		return nil
+	},
+}
+
+var DocsHistoryRevertStatus = common.Shortcut{
+	Service:     "docs",
+	Command:     "+history-revert-status",
+	Description: "Get Lark document history revert task status",
+	Risk:        "read",
+	Scopes:      []string{"docx:document:readonly"},
+	AuthTypes:   []string{"user", "bot"},
+	PostMount:   installDocsShortcutHelp("+history-revert-status"),
+	Flags: []common.Flag{
+		{Name: "doc", Desc: "document URL or token", Required: true},
+		{Name: "task-id", Desc: "task_id returned by docs +history-revert", Required: true},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if _, err := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-revert-status"); err != nil {
+			return err
+		}
+		if strings.TrimSpace(runtime.Str("task-id")) == "" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--task-id is required").WithParam("--task-id")
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		ref, _ := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-revert-status")
+		spec := docsHistoryRevertStatusSpec{
+			Doc:    ref,
+			TaskID: strings.TrimSpace(runtime.Str("task-id")),
+		}
+		return common.NewDryRunAPI().
+			Desc("OpenAPI: get document history revert status").
+			GET("/open-apis/docs_ai/v1/documents/:document_id/history/revert_status").
+			Set("document_id", spec.Doc.Token).
+			Params(docsHistoryStatusParams(spec))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		ref, _ := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-revert-status")
+		spec := docsHistoryRevertStatusSpec{
+			Doc:    ref,
+			TaskID: strings.TrimSpace(runtime.Str("task-id")),
+		}
+
+		data, err := runtime.CallAPITyped(
+			http.MethodGet,
+			docsHistoryAPIPath(spec.Doc.Token, "history/revert_status"),
+			docsHistoryStatusParams(spec),
+			nil,
+		)
+		if err != nil {
+			return err
+		}
+		runtime.OutRaw(data, nil)
+		return nil
+	},
+}
--- a/shortcuts/doc/docs_history_test.go
+++ b/shortcuts/doc/docs_history_test.go
@@ -0,0 +1,340 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package doc
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
+	"github.com/spf13/cobra"
+)
+
+func TestDocsHistoryValidation(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name      string
+		shortcut  common.Shortcut
+		args      []string
+		param     string
+		category  errs.Category
+		subtype   errs.Subtype
+		wantCause bool
+	}{
+		{
+			name:     "list rejects legacy doc URL",
+			shortcut: DocsHistoryList,
+			args:     []string{"+history-list", "--doc", "https://example.feishu.cn/doc/old_doc", "--as", "bot"},
+			param:    "--doc",
+			category: errs.CategoryValidation,
+			subtype:  errs.SubtypeInvalidArgument,
+		},
+		{
+			name:     "list rejects invalid page size",
+			shortcut: DocsHistoryList,
+			args:     []string{"+history-list", "--doc", "doxcnHistory", "--page-size", "0", "--as", "bot"},
+			param:    "--page-size",
+			category: errs.CategoryValidation,
+			subtype:  errs.SubtypeInvalidArgument,
+		},
+		{
+			name:      "revert rejects non-numeric history version id",
+			shortcut:  DocsHistoryRevert,
+			args:      []string{"+history-revert", "--doc", "doxcnHistory", "--history-version-id", "abc", "--as", "bot"},
+			param:     "--history-version-id",
+			category:  errs.CategoryValidation,
+			subtype:   errs.SubtypeInvalidArgument,
+			wantCause: true,
+		},
+		{
+			name:     "revert rejects non-positive history version id",
+			shortcut: DocsHistoryRevert,
+			args:     []string{"+history-revert", "--doc", "doxcnHistory", "--history-version-id", "0", "--as", "bot"},
+			param:    "--history-version-id",
+			category: errs.CategoryValidation,
+			subtype:  errs.SubtypeInvalidArgument,
+		},
+		{
+			name:     "revert rejects invalid wait timeout",
+			shortcut: DocsHistoryRevert,
+			args:     []string{"+history-revert", "--doc", "doxcnHistory", "--history-version-id", "10", "--wait-timeout-ms", "30001", "--as", "bot"},
+			param:    "--wait-timeout-ms",
+			category: errs.CategoryValidation,
+			subtype:  errs.SubtypeInvalidArgument,
+		},
+		{
+			name:     "status rejects empty task id",
+			shortcut: DocsHistoryRevertStatus,
+			args:     []string{"+history-revert-status", "--doc", "doxcnHistory", "--task-id", "", "--as", "bot"},
+			param:    "--task-id",
+			category: errs.CategoryValidation,
+			subtype:  errs.SubtypeInvalidArgument,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			f, stdout, _, _ := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-history-validation"))
+			err := mountAndRunDocs(t, tt.shortcut, tt.args, f, stdout)
+			if err == nil {
+				t.Fatal("expected validation error, got nil")
+			}
+			problem, ok := errs.ProblemOf(err)
+			if !ok {
+				t.Fatalf("error is not typed: %T %v", err, err)
+			}
+			if problem.Category != tt.category {
+				t.Fatalf("category = %q, want %q (err: %v)", problem.Category, tt.category, err)
+			}
+			if problem.Subtype != tt.subtype {
+				t.Fatalf("subtype = %q, want %q (err: %v)", problem.Subtype, tt.subtype, err)
+			}
+			var validationErr *errs.ValidationError
+			if !errors.As(err, &validationErr) {
+				t.Fatalf("expected validation error, got %T: %v", err, err)
+			}
+			if validationErr.Param != tt.param {
+				t.Fatalf("param = %q, want %q (err: %v)", validationErr.Param, tt.param, err)
+			}
+			if tt.wantCause && errors.Unwrap(err) == nil {
+				t.Fatalf("expected wrapped cause, got nil (err: %v)", err)
+			}
+		})
+	}
+}
+
+func TestDocsHistoryDryRun(t *testing.T) {
+	t.Parallel()
+
+	listCmd := newDocsHistoryRuntimeCmd(t, DocsHistoryList, map[string]string{
+		"doc":        "doxcnHistoryDryRun",
+		"page-size":  "5",
+		"page-token": "page_token_1",
+	})
+	listDry := decodeDocDryRun(t, DocsHistoryList.DryRun(context.Background(), common.TestNewRuntimeContext(listCmd, nil)))
+	if got, want := listDry.API[0].URL, "/open-apis/docs_ai/v1/documents/doxcnHistoryDryRun/histories"; got != want {
+		t.Fatalf("list dry-run URL = %q, want %q", got, want)
+	}
+	if got := int(listDry.API[0].Params["page_size"].(float64)); got != 5 {
+		t.Fatalf("list page_size = %d, want 5", got)
+	}
+	if got := listDry.API[0].Params["page_token"]; got != "page_token_1" {
+		t.Fatalf("list page_token = %#v, want page_token_1", got)
+	}
+
+	revertCmd := newDocsHistoryRuntimeCmd(t, DocsHistoryRevert, map[string]string{
+		"doc":                "doxcnHistoryDryRun",
+		"history-version-id": "42",
+		"wait-timeout-ms":    "30000",
+	})
+	revertDry := decodeDocDryRun(t, DocsHistoryRevert.DryRun(context.Background(), common.TestNewRuntimeContext(revertCmd, nil)))
+	if got, want := revertDry.API[0].URL, "/open-apis/docs_ai/v1/documents/doxcnHistoryDryRun/history/revert"; got != want {
+		t.Fatalf("revert dry-run URL = %q, want %q", got, want)
+	}
+	if got := revertDry.API[0].Body["history_version_id"]; got != "42" {
+		t.Fatalf("revert history_version_id = %#v, want 42", got)
+	}
+	if got := int(revertDry.API[0].Body["wait_timeout_ms"].(float64)); got != 30000 {
+		t.Fatalf("revert wait_timeout_ms = %d, want 30000", got)
+	}
+
+	statusCmd := newDocsHistoryRuntimeCmd(t, DocsHistoryRevertStatus, map[string]string{
+		"doc":     "doxcnHistoryDryRun",
+		"task-id": "task_1",
+	})
+	statusDry := decodeDocDryRun(t, DocsHistoryRevertStatus.DryRun(context.Background(), common.TestNewRuntimeContext(statusCmd, nil)))
+	if got, want := statusDry.API[0].URL, "/open-apis/docs_ai/v1/documents/doxcnHistoryDryRun/history/revert_status"; got != want {
+		t.Fatalf("status dry-run URL = %q, want %q", got, want)
+	}
+	if got := statusDry.API[0].Params["task_id"]; got != "task_1" {
+		t.Fatalf("status task_id = %#v, want task_1", got)
+	}
+}
+
+func TestDocsHistoryExecuteList(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-history-list"))
+	stub := &httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/docs_ai/v1/documents/doxcnHistory/histories",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"entries": []interface{}{
+					map[string]interface{}{
+						"revision_id":        float64(42),
+						"history_version_id": "11",
+						"edit_time":          "1780000000",
+						"type":               float64(1),
+						"editor_ids":         []interface{}{"ou_1"},
+					},
+				},
+				"has_more":   true,
+				"page_token": "page_token_2",
+			},
+		},
+	}
+	reg.Register(stub)
+
+	err := mountAndRunDocs(t, DocsHistoryList, []string{
+		"+history-list",
+		"--doc", "doxcnHistory",
+		"--page-size", "5",
+		"--page-token", "page_token_1",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data := decodeDocsHistoryEnvelope(t, stdout)
+	if got := data["page_token"]; got != "page_token_2" {
+		t.Fatalf("page_token = %#v, want page_token_2", got)
+	}
+	entries, _ := data["entries"].([]interface{})
+	if len(entries) != 1 {
+		t.Fatalf("entries = %#v, want one entry", data["entries"])
+	}
+}
+
+func TestDocsHistoryExecuteRevert(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-history-revert"))
+	stub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/docs_ai/v1/documents/doxcnHistory/history/revert",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"task_id":            "task_1",
+				"status":             "running",
+				"history_version_id": "42",
+				"poll_after_ms":      float64(10000),
+			},
+		},
+	}
+	reg.Register(stub)
+
+	err := mountAndRunDocs(t, DocsHistoryRevert, []string{
+		"+history-revert",
+		"--doc", "doxcnHistory",
+		"--history-version-id", "42",
+		"--wait-timeout-ms", "0",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var body map[string]interface{}
+	if err := json.Unmarshal(stub.CapturedBody, &body); err != nil {
+		t.Fatalf("decode revert body: %v\nraw=%s", err, stub.CapturedBody)
+	}
+	if got := body["history_version_id"]; got != "42" {
+		t.Fatalf("history_version_id = %#v, want 42", got)
+	}
+	if got := int(body["wait_timeout_ms"].(float64)); got != 0 {
+		t.Fatalf("wait_timeout_ms = %d, want 0", got)
+	}
+
+	data := decodeDocsHistoryEnvelope(t, stdout)
+	if got := data["task_id"]; got != "task_1" {
+		t.Fatalf("task_id = %#v, want task_1", got)
+	}
+}
+
+func TestDocsHistoryExecuteRevertStatus(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-history-status"))
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/docs_ai/v1/documents/doxcnHistory/history/revert_status",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"status":              "partial_failed",
+				"history_version_id":  "11",
+				"failed_block_tokens": []interface{}{"blk_1"},
+			},
+		},
+	})
+
+	err := mountAndRunDocs(t, DocsHistoryRevertStatus, []string{
+		"+history-revert-status",
+		"--doc", "doxcnHistory",
+		"--task-id", "task_1",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data := decodeDocsHistoryEnvelope(t, stdout)
+	if got := data["status"]; got != "partial_failed" {
+		t.Fatalf("status = %#v, want partial_failed", got)
+	}
+	if got := data["history_version_id"]; got != "11" {
+		t.Fatalf("history_version_id = %#v, want 11", got)
+	}
+	failed, _ := data["failed_block_tokens"].([]interface{})
+	if len(failed) != 1 || failed[0] != "blk_1" {
+		t.Fatalf("failed_block_tokens = %#v, want [blk_1]", data["failed_block_tokens"])
+	}
+}
+
+func newDocsHistoryRuntimeCmd(t *testing.T, shortcut common.Shortcut, values map[string]string) *cobra.Command {
+	t.Helper()
+
+	cmd := &cobra.Command{Use: shortcut.Command}
+	for _, flag := range shortcut.Flags {
+		switch flag.Type {
+		case "int":
+			cmd.Flags().Int(flag.Name, 0, flag.Desc)
+		default:
+			cmd.Flags().String(flag.Name, flag.Default, flag.Desc)
+		}
+	}
+	for name, value := range values {
+		if err := cmd.Flags().Set(name, value); err != nil {
+			t.Fatalf("set --%s: %v", name, err)
+		}
+	}
+	return cmd
+}
+
+func decodeDocsHistoryEnvelope(t *testing.T, stdout *bytes.Buffer) map[string]interface{} {
+	t.Helper()
+
+	var envelope map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
+		t.Fatalf("decode envelope: %v\nraw=%s", err, stdout.String())
+	}
+	data, _ := envelope["data"].(map[string]interface{})
+	if data == nil {
+		t.Fatalf("missing data in envelope: %#v", envelope)
+	}
+	return data
+}
+
+func TestDocsHistoryURLValidationMessage(t *testing.T) {
+	t.Parallel()
+
+	_, err := parseDocsHistoryDocRef("https://example.feishu.cn/doc/old_doc", "+history-list")
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	if !strings.Contains(err.Error(), "only supports docx documents") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
--- a/shortcuts/doc/shortcuts.go
+++ b/shortcuts/doc/shortcuts.go
@@ -31,6 +31,8 @@ func docsSkillReadCommandForShortcut(shortcut string) string {
 		return docsSkillReadCommand + " references/lark-doc-fetch.md"
 	case "update":
 		return docsSkillReadCommand + " references/lark-doc-update.md"
+	case "history-list", "history-revert", "history-revert-status":
+		return docsSkillReadCommand + " references/lark-doc-history.md"
 	default:
 		return docsSkillReadCommand
 	}
@@ -44,6 +46,12 @@ func docsHelpCommandForShortcut(shortcut string) string {
 		return "lark-cli docs +fetch --help"
 	case "update":
 		return "lark-cli docs +update --help"
+	case "history-list":
+		return "lark-cli docs +history-list --help"
+	case "history-revert":
+		return "lark-cli docs +history-revert --help"
+	case "history-revert-status":
+		return "lark-cli docs +history-revert-status --help"
 	default:
 		return "lark-cli docs --help"
 	}
@@ -56,6 +64,9 @@ func Shortcuts() []common.Shortcut {
 		DocsCreate,
 		DocsFetch,
 		DocsUpdate,
+		DocsHistoryList,
+		DocsHistoryRevert,
+		DocsHistoryRevertStatus,
 		DocMediaInsert,
 		DocMediaUpload,
 		DocMediaPreview,
--- a/shortcuts/register_test.go
+++ b/shortcuts/register_test.go
@@ -170,6 +170,27 @@ func TestRegisterShortcutsMountsDocsMediaPreview(t *testing.T) {
 	}
 }

+func TestRegisterShortcutsMountsDocsHistoryCommands(t *testing.T) {
+	program := &cobra.Command{Use: "root"}
+	RegisterShortcuts(program, newRegisterTestFactory(t))
+
+	for _, name := range []string{"+history-list", "+history-revert", "+history-revert-status"} {
+		cmd, _, err := program.Find([]string{"docs", name})
+		if err != nil {
+			t.Fatalf("find docs %s shortcut: %v", name, err)
+		}
+		if cmd == nil || cmd.Name() != name {
+			t.Fatalf("docs %s shortcut not mounted: %#v", name, cmd)
+		}
+		if cmd.Flags().Lookup("api-version") != nil {
+			t.Fatalf("docs %s should not expose --api-version", name)
+		}
+		if !strings.Contains(cmd.Long, "lark-cli skills read lark-doc references/lark-doc-history.md") {
+			t.Fatalf("docs %s help missing history skill guidance:\n%s", name, cmd.Long)
+		}
+	}
+}
+
 func TestRegisterShortcutsDocsHelpAddsSkillReadGuidance(t *testing.T) {
 	program := &cobra.Command{Use: "root"}
 	RegisterShortcuts(program, newRegisterTestFactory(t))
--- a/skills/lark-doc/SKILL.md
+++ b/skills/lark-doc/SKILL.md
@@ -5,7 +5,7 @@ description: "飞书云文档（Docx / Wiki 文档）：读取和编辑飞书文
 metadata:
  requires:
    bins: ["lark-cli"]
-  cliHelp: "lark-cli docs --help; lark-cli docs +create --help; lark-cli docs +fetch --help; lark-cli docs +update --help; lark-cli docs +resource-download --help; lark-cli docs +resource-update --help; lark-cli docs +resource-delete --help; lark-cli mindnotes nodes list --help; lark-cli mindnotes nodes create --help"
+  cliHelp: "lark-cli docs --help;lark-cli mindnotes --help"
 ---

 # docs
@@ -21,41 +21,28 @@ lark-cli docs +update --doc "文档URL或token" --command append --content '<p>

 ## 前置条件 — 执行操作前必读

-**CRITICAL — 按任务命中以下阅读规则；执行对应操作前，MUST 先用 Read 工具读取命中的文件，缺一不可：**
+**CRITICAL — 执行对应操作前，MUST 先用 Read 工具读取以下文件，缺一不可：**
+1. [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) — 认证、权限处理、全局参数（所有操作通用）
+2. **读取文档（`docs +fetch`）** → 必读 [`lark-doc-fetch.md`](references/lark-doc-fetch.md)（`--scope` / `--detail` 选择、局部读取策略、`<fragment>` / `<excerpt>` 输出结构）
+3. **创建或编辑文档内容** → 必读 [`lark-doc-xml.md`](references/lark-doc-xml.md)（XML 语法规则，仅当用户明确要求 Markdown 时改读 [`lark-doc-md.md`](references/lark-doc-md.md)）和必读 [`lark-doc-style.md`](references/style/lark-doc-style.md)（写作原则：默认段落、按体裁、组件克制）；从零创建时加读 [`lark-doc-create-workflow.md`](references/style/lark-doc-create-workflow.md)；编辑已有文档时加读 [`lark-doc-update.md`](references/lark-doc-update.md) 和 [`lark-doc-update-workflow.md`](references/style/lark-doc-update-workflow.md)

-1. **所有文档操作** → 必读 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)  
-   用于认证、权限处理、身份选择和全局参数。
-2. **读取文档（`docs +fetch`）** → 必读 [`lark-doc-fetch.md`](references/lark-doc-fetch.md)  
-   用于选择 `--scope` / `--detail`、局部读取策略，以及理解 `<fragment>` / `<excerpt>` 输出结构。
-3. **创建、重写、润色、排版或生成较多正文** → 必读：
-   - [`lark-doc-design-philosophy.md`](references/lark-doc-design-philosophy.md) — 文档设计判断：读者任务、结构取舍、组件选择、体裁路由和反模板化。
-   - [`lark-doc-xml.md`](references/lark-doc-xml.md) — XML 语法规则；仅当用户明确要求 Markdown、提供 `.md` 文件，或明确要求导入 Markdown 时，改读 [`lark-doc-md.md`](references/lark-doc-md.md)。
-
-   进一步按场景加读：
-   - 如果 [`lark-doc-design-philosophy.md`](references/lark-doc-design-philosophy.md) 的体裁路由命中某个 `references/genres/*.md` 文件，只读取该体裁文件；不要读取整个 `genres/` 目录。
-   - 从零创建文档时，加读 [`lark-doc-create.md`](references/lark-doc-create.md)。
-   - 编辑已有文档时，加读 [`lark-doc-update.md`](references/lark-doc-update.md)。
-
-4. **仅做微编辑**，例如明确旧文本 → 新文本的简单替换、错别字修正、日期 / 人名 / 数字替换，不需要读取设计哲学和体裁文件；按 [`lark-doc-update.md`](references/lark-doc-update.md) 执行，并在写后 fetch 验证。
-
-**Philosophy 负责判断；Genre 负责偏好；Create / Update 负责执行；XML / Markdown 负责合法表达。**
-
-**未读完命中的必读文件就执行相应操作，容易导致参数选择错误、格式错误、结构失焦或内容破坏。**
+**未读完以上文件就执行相应操作会导致参数选择错误或格式错误。**

 > **格式选择规则（全局）：**
-> - **创建 / 导入场景**（`docs +create`，或 `docs +update --command append/overwrite` 的整段写入）：XML 和 Markdown 都可以。用户提供 `.md` 本地文件、或明确说"导入 Markdown"时，直接用 Markdown；否则默认 XML（可用 callout、grid、checkbox 等富 block）。
+> - **创建 / 导入场景**（`docs +create`，或 `docs +update --command append/overwrite` 的整段写入）：XML 和 Markdown 都可以。用户提供 `.md` 本地文件、或明确说"导入 Markdown"时，直接用 Markdown；否则默认 XML。
 > - **精准编辑场景**（`docs +update` 的 `str_replace` / `block_insert_after` / `block_replace` / `block_delete` / `block_move_after` 等局部精修指令）：优先使用 XML（`--doc-format xml`，即默认值）。XML 能稳定表达 block 结构和样式，局部精修更可控；不要因为 Markdown 更简单就自行切换。

 ## 快速决策
 - 用户要**复制文档 / 创建文档副本 / 另存为副本**时，切到 [`lark-drive`](../lark-drive/SKILL.md)，按其中的复制指引使用 `lark-cli drive files copy`；不要用 `docs +fetch` + `docs +create` 重建正文，也不要走 `drive +export` / `drive +import`。
- 先判定任务路径：找文档 / 导入导出走 [`lark-drive`](../lark-drive/SKILL.md)；只读 / 摘要用 `docs +fetch` 默认 `simple`；已有文档改写按 [`lark-doc-update.md`](references/lark-doc-update.md) 的 Observe-Diagnose-Patch Loop 先 fetch 再局部 patch；明确旧文本 → 新文本的简单替换可直接 `str_replace`，但写后必须 fetch 验证；只有 block 链接、评论锚点、插入 / 替换 / 删除 / 移动才局部 fetch `with-ids`；保真改写已有内容才读 `full`
+- 先判定任务路径：找文档 / 导入导出走 [`lark-drive`](../lark-drive/SKILL.md)；只读 / 摘要用 `docs +fetch` 默认 `simple`；明确旧文本 → 新文本直接 `str_replace`；只有 block 链接、评论锚点、插入 / 替换 / 删除 / 移动才局部 fetch `with-ids`；保真改写已有内容才读 `full`
 - block 直达链接格式：`文档基础 URL#block_id`；没有 block_id 时局部 fetch `with-ids`
- 连续执行多个文档写操作时，必须按 [`lark-doc-update.md`](references/lark-doc-update.md) 的「Block ID 生命周期」处理：每次更新后都按 block ID 已变更处理；需要继续或重复修改时，先重新 fetch 最新内容和 block ID，不要复用旧 fetch 结果
+- 连续执行多个文档写操作时，必须按 [`lark-doc-update.md`](references/lark-doc-update.md) 的「Block ID 生命周期」判断旧 block ID 是否还能复用；`overwrite` / `block_replace` / `block_delete` 后不要复用受影响的旧 ID，插入 / 复制后要重新 fetch 才能拿到新 block ID
 - 用户需要在文档内**创建、复制或移动**资源块（画板、电子表格、多维表格等）时，必须先读取 [`lark-doc-xml.md`](references/lark-doc-xml.md) 的「三、资源块」章节
 - 写文档时，由内容和用户意图决定表达形式；流程、架构、路线图、关键指标等信息可以使用画板，但不要默认把重要信息都画板化
- 新增画板按复杂度处理：简单 Mermaid / SVG 图可由主 Agent 直接写入草稿；复杂图或需要专门视觉设计的 SVG 交给 SubAgent 产出完整 `<whiteboard type="svg">...</whiteboard>`；特别复杂或已有画板更新，主 Agent 先建 `<whiteboard type="blank"></whiteboard>`，再启动 SubAgent 读取 `lark-whiteboard` 写入
+- 新增或更新画板时，按 [`lark-doc-whiteboard.md`](references/lark-doc-whiteboard.md) 选型；Mermaid 可由主 Agent 直接插入，SVG / 复杂图 / 已有画板更新按其中流程隔离到 SubAgent
 - 用户说"看一下文档里的图片/附件/素材""预览素材" → 用 `lark-cli docs +media-preview`
 - 用户明确说"下载素材" → 用 `lark-cli docs +media-download`
+- 用户想把文档回滚到某个 `revision_id` 或某一时刻 → 先读 [`lark-doc-history.md`](references/lark-doc-history.md)，按其中流程操作
 - 用户明确说"下载/更新/删除文档封面图" → 用 `lark-cli docs +resource-download/+resource-update/+resource-delete --type cover`
 - `resource-*` 目前仅支持 Docx 封面资源；其他图片、附件或素材请走 `+media-*`
 - 如果目标是画板/whiteboard/画板缩略图 → 只能用 `lark-cli docs +media-download --type whiteboard`（不要用 `+media-preview`）
@@ -83,6 +70,7 @@ Shortcut 是对常用操作的高级封装（`lark-cli docs +<verb> [flags]`）
 | [`+create`](references/lark-doc-create.md) | Create a Lark document (XML / Markdown) |
 | [`+fetch`](references/lark-doc-fetch.md) | Fetch Lark document content (XML / Markdown / im-markdown; `im-markdown` only after fetch for `lark-im`) |
 | [`+update`](references/lark-doc-update.md) | Update a Lark document (str_replace / block_insert_after / block_replace / ...) |
+| [`+history-list` / `+history-revert` / `+history-revert-status`](references/lark-doc-history.md) | List document history, revert to a `history_version_id`, and query revert task status |
 | [`+media-insert`](references/lark-doc-media-insert.md) | Insert a local image or file at the end of a Lark document (4-step orchestration + auto-rollback). Prefer `--from-clipboard` when the image is already on the system clipboard (screenshots, copy from Feishu/browser); use `--file` only for on-disk sources. |
 | [`+media-download`](references/lark-doc-media-download.md) | Download document media or whiteboard thumbnail (auto-detects extension) |
 | [`+media-preview`](references/lark-doc-media-preview.md) | Preview document media file (auto-detects extension) |
--- a/skills/lark-doc/references/genres/formal-doc.md
+++ b/skills/lark-doc/references/genres/formal-doc.md
@@ -1,38 +0,0 @@
-# Genre: Formal Document
-
-适用：通知、制度、公告、汇报、立项、正式方案、对外说明、需要归档或跨团队协作的文档。
-
-## Structure patterns
-
-按任务选择结构，不要机械套用：
-
- **事项通知**：事项 → 适用范围 → 具体安排 → 时间节点 → 责任人 / 联系方式。
- **决策汇报**：结论 / 建议 → 背景 → 方案对比 → 风险影响 → 待决策问题。
- **制度规范**：目的 → 适用范围 → 规则正文 → 例外情况 → 执行与解释。
- **正式方案**：问题定义 → 目标与范围 → 方案 → 资源 / 排期 → 风险 → 下一步。
-
-## Style
-
-准确、克制、明确责任边界。优先写清对象、动作、时间、范围和责任人。少用夸张修饰，不使用网感标题。避免用“赋能、闭环、抓手、沉淀、拉通、对齐”等空泛词替代具体动作。
-
-## Component bias
-
- 时间、责任、范围、事项清单：优先 table。
- 风险、待确认、强约束：可用 callout。
- 方案对比：table / grid / 决策矩阵。
- 流程、组织关系、里程碑：必要时用 whiteboard。
- 长期归档、对外说明：少用颜色和 emoji，保持朴素。
-
-## Avoid
-
- 开头铺太长背景，迟迟不给结论。
- 缺少责任人、时间、范围、生效条件。
- 为了正式感堆砌抽象词。
- 为了美观强行加入 callout、grid 或画板。
-
-## Final check
-
- 事项、范围、责任、时间是否明确？
- 结论和待决策问题是否前置？
- 语气是否正式、克制、无夸张？
- 是否适合归档和后续追责？
--- a/skills/lark-doc/references/genres/prd.md
+++ b/skills/lark-doc/references/genres/prd.md
@@ -1,39 +0,0 @@
-# Genre: PRD / Product Requirement
-
-适用：PRD、需求说明、用户故事、产品方案、功能设计、版本范围说明。
-
-## Structure patterns
-
-按任务选择结构：
-
- **标准 PRD**：背景与问题 → 用户与场景 → 目标与非目标 → 方案概述 → 功能范围 → 交互 / 流程 → 数据与埋点 → 边界异常 → 验收标准 → 风险依赖。
- **轻量需求**：问题 → 目标 → 用户故事 → 规则 → 验收标准 → 待确认。
- **产品方案**：现状 → 机会 / 问题 → 方案 → 取舍 → 里程碑 → 风险。
- **功能评审**：结论 → 范围变化 → 核心流程 → 争议点 → 待决策问题。
-
-## Style
-
-具体、可评审、可验收。多写用户行为、系统响应、状态变化和规则，少写抽象愿景。每个需求尽量落到状态、规则、字段、交互或验收条件。
-
-## Component bias
-
- 用户故事、验收标准：列表 / checkbox。
- 字段、规则、状态、埋点：table。
- 用户流程、系统流程、状态机：whiteboard。
- 风险、依赖、待确认：callout。
- 版本范围、需求优先级：table / 小标题。
-
-## Avoid
-
- 只有需求描述，没有验收标准。
- 混淆目标、方案、交互和实现细节。
- 没有非目标，导致范围无限扩大。
- 缺少异常状态、边界条件和数据规则。
- 用“大幅提升体验”替代具体用户收益。
-
-## Final check
-
- 目标、非目标和范围是否清楚？
- 用户、场景、规则和状态是否可评审？
- 验收标准是否可验证？
- 风险、依赖和待确认项是否明确？
--- a/skills/lark-doc/references/genres/retrospective.md
+++ b/skills/lark-doc/references/genres/retrospective.md
@@ -1,39 +0,0 @@
-# Genre: Retrospective / Summary
-
-适用：项目复盘、事故复盘、阶段总结、周报、月报、季度总结、问题回顾。
-
-## Structure patterns
-
-按任务选择结构：
-
- **事故复盘**：结论 → 影响范围 → 时间线 → 根因 → 处置过程 → 暴露问题 → 改进动作 → 负责人 / 截止时间。
- **项目复盘**：目标 → 结果 → 关键事实 → 做得好的地方 → 问题与原因 → 经验沉淀 → 后续动作。
- **周报 / 月报**：核心进展 → 关键结果 → 风险阻塞 → 下阶段计划 → 需要支持。
- **阶段总结**：目标回顾 → 数据 / 事实 → 判断 → 问题 → 后续重点。
-
-## Style
-
-事实和判断分开。避免甩锅，也避免空泛反思。后续动作必须具体到负责人、时间和验收方式。不要用“加强对齐、持续优化、提升意识”替代真实动作。
-
-## Component bias
-
- 时间线：table / whiteboard。
- 根因和影响链路：列表 / 鱼骨图 / 因果图。
- 行动项：checkbox / table。
- 风险和阻塞：callout。
- 数据对比：table / whiteboard 图表。
-
-## Avoid
-
- 只有情绪评价，没有事实。
- 只有“后续加强”，没有负责人和时间。
- 时间线缺失，无法复盘过程。
- 结论与证据不匹配。
- 把复盘写成汇功或甩锅材料。
-
-## Final check
-
- 事实、判断、动作是否分开？
- 时间线和影响范围是否清楚？
- 根因是否有证据支持？
- 后续动作是否有负责人、截止时间和验收标准？
--- a/skills/lark-doc/references/genres/social-xhs.md
+++ b/skills/lark-doc/references/genres/social-xhs.md
@@ -1,41 +0,0 @@
-# Genre: Xiaohongshu / Social Content
-
-适用：小红书笔记、爆文、种草、攻略、经验分享、标题优化、社媒传播型内容。
-
-## Structure patterns
-
-按任务选择结构：
-
- **经验型**：强钩子 → 痛点场景 → 个人经验 / 观察 → 方法清单 → 适用人群 → 互动结尾。
- **攻略型**：结果承诺 → 准备条件 → 步骤 → 避坑点 → 清单总结。
- **种草型**：使用场景 → 核心卖点 → 真实体验 → 对比 / 注意事项 → 行动建议。
- **观点型**：反常识判断 → 论据 → 例子 → 常见误区 → 行动建议。
- **清单型**：适用人群 → 清单分组 → 每项解释 → 收藏提醒 / 使用方式。
-
-## Style
-
-口语化、具体、有节奏。短段落优先，多用场景、例子和清单。可以有情绪，但不能编造经历、数据或效果。标题可以吸引人，但正文必须兑现标题承诺。
-
-## Component bias
-
- 开头钩子：短段落 / callout。
- 方法步骤：列表 / checkbox。
- 避坑、对比、清单：grid / table。
- 可收藏内容：checkbox / table。
- 复杂流程才用 whiteboard；轻内容不要图表化。
- emoji 可用，但要克制并保持语义一致。
-
-## Avoid
-
- 标题党但正文兑现不了。
- 过度使用“绝了、封神、天花板、救命、狠狠爱住”等空泛网感词。
- 编造个人经历、效果数据、医学 / 金融 / 法律结论。
- 信息太散，没有可保存的方法、清单或判断。
- 为了网感牺牲事实准确性。
-
-## Final check
-
- 标题是否有吸引力且不虚假？
- 开头 3 秒内是否说明痛点或利益？
- 正文是否有具体方法、例子或清单？
- 是否适合收藏、转发或执行？
--- a/skills/lark-doc/references/genres/sop-tutorial.md
+++ b/skills/lark-doc/references/genres/sop-tutorial.md
@@ -1,40 +0,0 @@
-# Genre: SOP / Tutorial
-
-适用：SOP、操作手册、培训材料、入门指南、使用说明、FAQ、流程规范。
-
-## Structure patterns
-
-按任务选择结构：
-
- **SOP**：适用范围 → 前置条件 → 操作步骤 → 检查标准 → 异常处理 → 责任边界。
- **入门教程**：适合谁 → 准备什么 → 快速开始 → 分步说明 → 常见问题 → 下一步。
- **操作手册**：任务列表 → 每个任务的步骤 → 注意事项 → 错误处理 → 参考链接。
- **FAQ**：问题分类 → 问题 → 简短答案 → 详细说明 / 操作入口。
-
-## Style
-
-直接、清楚、面向操作者。一句话只承担一个任务。按用户看到的界面命名，不按系统内部实现命名。优先使用动词开头的步骤，例如“打开”“选择”“填写”“确认”。
-
-## Component bias
-
- 步骤：有序列表。
- 检查项：checkbox。
- 命令、配置、日志：pre / code。
- 错误处理、条件分支：table / callout。
- 流程复杂时：whiteboard。
- 入口链接：button / link / url-preview。
-
-## Avoid
-
- 缺少前置条件。
- 步骤跳跃，默认读者知道上下文。
- 用内部术语命名用户界面。
- 没有失败处理或校验方式。
- 一个步骤里塞多个动作。
-
-## Final check
-
- 新手能否按步骤完成任务？
- 前置条件、输入、输出和校验是否清楚？
- 异常情况是否有处理方式？
- 每一步是否只做一件事？
--- a/skills/lark-doc/references/genres/technical-doc.md
+++ b/skills/lark-doc/references/genres/technical-doc.md
@@ -1,40 +0,0 @@
-# Genre: Technical Document
-
-适用：技术方案、架构设计、接口说明、API 文档、部署手册、迁移方案、排障指南、研发交接。
-
-## Structure patterns
-
-按任务选择结构：
-
- **技术方案**：问题 / 背景 → 目标与非目标 → 约束 → 总体设计 → 模块设计 → 数据 / 接口 → 风险 → 验证 → 灰度 / 回滚。
- **接口文档**：适用范围 → 鉴权 → 请求参数 → 响应结构 → 错误码 → 示例 → 兼容性。
- **排障指南**：现象 → 影响范围 → 快速判断 → 排查步骤 → 常见原因 → 修复方式 → 升级路径。
- **迁移方案**：范围 → 前置条件 → 步骤 → 校验 → 回滚 → 风险与窗口期。
- **架构文档**：目标 → 上下文 → 架构图 → 核心链路 → 模块职责 → 数据流 → 边界限制。
-
-## Style
-
-精确、朴素、可实现、可验证。术语保持一致，不为了通俗牺牲准确性。不确定处标注“假设”或“待确认”。不要把技术取舍写成宣传话术。
-
-## Component bias
-
- 命令、代码、配置、日志：pre / code。
- 参数、字段、错误码、兼容性：table。
- 架构、调用链、状态流转、部署拓扑：whiteboard / Mermaid。
- 操作步骤、验收项：列表 / checkbox。
- 风险、限制、回滚条件：callout。
-
-## Avoid
-
- 只有概念，没有接口、数据、边界或验证。
- 忽略失败场景、兼容性、监控、回滚。
- 图很多，但没有说明依赖、调用关系或数据流。
- 使用营销腔描述技术收益。
- 改写时破坏代码、图片、引用、资源块或 token 化内容。
-
-## Final check
-
- 读者能否据此实现、集成、排查或评审？
- 目标、非目标、边界和失败场景是否清楚？
- 参数、命令、接口和示例是否准确？
- 是否有验证、灰度、回滚或排障路径？
--- a/skills/lark-doc/references/lark-doc-create.md
+++ b/skills/lark-doc/references/lark-doc-create.md
@@ -1,30 +1,15 @@
 # docs +create（创建飞书云文档）

 > **前置条件（MUST READ）：** 生成文档内容前，必须先用 Read 工具读取以下文件，缺一不可：
-> 1. [`lark-doc-design-philosophy.md`](lark-doc-design-philosophy.md) — 文档设计判断（读者任务、结构取舍、组件选择、反模板化）
-> 2. [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规则（使用 Markdown 格式时改读 [`lark-doc-md.md`](lark-doc-md.md)）
+> 1. [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规则（使用 Markdown 格式时改读 [`lark-doc-md.md`](lark-doc-md.md)）
+> 2. [`lark-doc-style.md`](style/lark-doc-style.md) — 写作原则（默认段落、按体裁、组件克制）
+> 3. [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) — 从零创作工作流（Code-Act Loop、单 Agent 串行撰写）
 >
-> **未读完以上文件就生成内容会导致结构失焦或格式错误。**
+> **未读完以上文件就生成内容会导致格式错误。**

 从 XML（默认）或 Markdown 内容创建一个新的飞书云文档。

-> **⚠️ 格式选择规则：** 创建 / 导入场景下 XML 和 Markdown 都可以——用户提供 `.md` 本地文件、或明确说"导入 Markdown"时，直接用 Markdown；没有明确指示时默认 XML（表达能力更强，支持 callout、grid、checkbox 等富 block 类型）。不要在用户没要求的情况下主动从 XML 切到 Markdown，也不要在用户已给出 Markdown 时强行改成 XML。
-
-## Document Authoring Loop
-
-从零创作文档时，以本地草稿文件作为唯一正文源（默认 XML；用户明确要求 Markdown 或提供 `.md` 文件时使用 Markdown），主 Agent 串行完成写作、审阅和修订，草稿达标后再调用 `docs +create`。不要先创建线上骨架再让多个 Agent 并行拆章节写入；这容易造成风格漂移、重复铺陈、结构断流和事实口径不一致。
-
-1. **Plan（规划）**：明确受众、目的、范围、体裁、结构和验收标准；事实来源或产品口径不确定时先询问用户，能安全假设时说明假设并继续。
-2. **Draft（起草）**：在当前工作目录创建相对路径草稿文件，主 Agent 按文档顺序串行写作；
-3. **Observe（观察）**：读取当前草稿，检查结构、重复、断流、事实、语气和格式；
-4. **Revise（修订）**：局部修订本地文件，优先调整顺序、补桥接句、删重复、统一术语和修正 XML；不追求第一稿一次完美。
-5. **Enrich（增强）**：决定一篇文档是否真正好读、可信、可传播。必要时加入表格、列表、callout、grid、画板、引用或附件；增强必须降低理解成本，不为了“丰富”而装饰。
-   - 新增画板按复杂度处理：简单 Mermaid 或 SVG 图可由主 Agent 直接写入本地 XML 草稿；复杂 SVG 可启动 SubAgent 只产出完整 `<whiteboard type="svg">...</whiteboard>` 片段；特别复杂或已有画板更新，再创建空白画板并让 SubAgent 读取 `lark-whiteboard` 完成写入。
-   - 创建后才能插入的图片、附件或资源，先在草稿中标记位置和素材路径，Deliver 后用 `docs +media-insert` 等命令补齐并 fetch 验证。
-6. **Validate（验证）**：检查用户要求、字数、格式、事实、可读性和风格；任何一项不满足，就回到 Observe / Revise 继续 loop。
-7. **Deliver（交付）**：本地草稿通过验证后，用 `docs +create --content @lark-doc-draft.xml` 创建 XML 文档；Markdown 草稿用 `docs +create --doc-format markdown --content @lark-doc-draft.md`。如需创建后插入图片、附件或资源，完成后再次 fetch 确认。
-
-`@file` 只接受当前工作目录下的相对路径，不要传 `@/tmp/xxx.xml` 这类绝对路径。SubAgent 只用于边界清晰的视觉或资源片段（如完整 SVG whiteboard XML），主 Agent 必须审核并合并结果；不要让 SubAgent 并行撰写正文。
+> **⚠️ 格式选择规则：** 创建 / 导入场景下 XML 和 Markdown 都可以——用户提供 `.md` 本地文件、或明确说"导入 Markdown"时，直接用 Markdown；没有明确指示时默认 XML（表达能力更强，可承载更丰富的结构化内容）。不要在用户没要求的情况下主动从 XML 切到 Markdown，也不要在用户已给出 Markdown 时强行改成 XML。

 ## 命令

@@ -80,9 +65,15 @@ lark-cli docs +create --doc-format markdown --title "项目计划" --content $'#
 | `--parent-token`    | 否  | 父文件夹或知识库节点 token（与 `--parent-position` 互斥）  |
 | `--parent-position` | 否  | 父节点位置，如 `my_library`（与 `--parent-token` 互斥） |

+## 最佳实践
+
+- **较长文档**：参考 [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) 先建骨架再分段写入；短文档可一次写完整内容
+- **表达形式**：由用户目标和内容决定。需要结构化表达时可参考 [`lark-doc-style.md`](style/lark-doc-style.md)，但不要默认套用固定开头、固定富 block 比例或固定图表
+
 ## 参考

- [`lark-doc-design-philosophy.md`](lark-doc-design-philosophy.md) — 文档设计判断与组件取舍
+- [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) — 从零创作工作流（Code-Act Loop、单 Agent 串行撰写）
+- [`lark-doc-style.md`](style/lark-doc-style.md) — 文档写作原则（默认段落、按体裁、组件克制）
 - [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规范
 - [`lark-doc-fetch.md`](lark-doc-fetch.md) — 获取文档
 - [`lark-doc-update.md`](lark-doc-update.md) — 更新文档
--- a/skills/lark-doc/references/lark-doc-design-philosophy.md
+++ b/skills/lark-doc/references/lark-doc-design-philosophy.md
@@ -1,98 +0,0 @@
-# Lark Doc Design Philosophy
-
- 把飞书云文档当作帮助读者完成理解、判断、决策或行动的界面，而不是内容容器。你的任务不是把信息铺满页面，而是为具体读者设计一条清晰、可信、可执行的阅读路径。
- 本文件负责文档设计判断：读者任务、结构取舍、表达组件、反模板化和质量自检。具体执行流程见 `lark-doc-create.md` 和 `lark-doc-update.md`；XML / Markdown 语法见 `lark-doc-xml.md` / `lark-doc-md.md`；体裁结构和语气差异按下方路由读取 `genres/*.md`。
-
-## 0. Priority order
-
-当目标冲突时，按此顺序取舍：**事实准确性 > 信息层级 > 可扫描性 > 协作可执行性 > 视觉整洁 > 个性化表达**。事实不确定就标注假设 / 待确认；结构混乱先调信息层级；视觉和个性只能增强理解，不能牺牲事实、结构和执行。
-
-## 1. Ground it in the document job
-
-写作或改写前，先判断这篇文档的工作：
-
- 读者是谁：决策者、执行者、评审者、客户、开发者、运营者，还是未来维护者？
- 读者要完成什么：理解背景、做出决策、执行任务、评审方案、排查问题、学习方法、传播内容，还是留档备查？
- 读完后读者应该能做什么：拍板、执行、确认风险、复用、转发、评论、排查或完成任务？
- 文档寿命是什么：一次性沟通、项目周期内维护、长期知识库、正式归档，还是外部传播？
-
-如果用户没有明确这些信息，能安全假设时说明假设并继续；事实来源、产品口径、结论归属不确定时，先询问或标注待确认，不要编造确定性。
-
-## 2. Route by genre
-
-体裁决定结构、语气、证据密度和表达方式。不要用同一套“背景 / 目标 / 方案 / 风险 / 下一步”应对所有任务。
-
-当用户明确或暗示体裁时，只读取一个最匹配的体裁文件；不要读取整个 `genres/` 目录。简单编辑已有文档时，优先沿用原文体裁和风格，不额外读取体裁文件。
-
-| 用户意图 / 信号词 | 读取文件 |
-|---|---|
-| 通知、制度、公告、汇报、立项、正式方案、对外说明 | `genres/formal-doc.md` |
-| 架构、接口、API、部署、迁移、排障、研发方案、技术设计 | `genres/technical-doc.md` |
-| 小红书、爆文、种草、笔记、攻略、社媒传播、标题优化 | `genres/social-xhs.md` |
-| PRD、需求说明、用户故事、产品方案、功能设计 | `genres/prd.md` |
-| 复盘、事故总结、项目总结、周报、月报、阶段总结 | `genres/retrospective.md` |
-| SOP、操作手册、培训材料、入门指南、使用说明、FAQ | `genres/sop-tutorial.md` |
-
-如果任务混合多个体裁，优先选择决定**内容结构**的主文件；语气可以参考用户要求调整，不要为轻微语气差异读取第二个体裁文件。例如“写给领导看的技术方案”优先读 `technical-doc.md`，并采用更正式克制的语气。
-
-## 3. Structure is information
-
- 结构不是装饰。标题、顺序、列表、表格、callout、grid、画板和引用块，都应该表达真实的信息关系。
- 选择结构前先判断：这是顺序、并列、对比、因果、层级、状态、证据，还是行动关系？读者需要先知道什么，才能理解后面的内容？哪些信息应该前置为结论，哪些适合压缩或放到附录？
- 文档开头不是固定的“背景”。决策文档先给结论和待拍板问题；执行文档先给目标、范围和时间线；复盘文档先给事实结论、影响和后续动作；技术文档先给适用范围、前置条件和快速路径；传播文档先给痛点、利益点或钩子。
- 较长、复杂或面向传播 / 汇报 / 决策的文档，最好有一个主组织锚点，如一句话结论、决策矩阵、风险雷达、路线图、架构图、时间线、对比表或 checklist。只保留一个，不要到处制造亮点；短文档、微编辑、正式归档或简单 SOP 不必强行设计。锚点必须服务事实准确、信息层级和协作执行，不能为了个性化表达增加理解成本。
-
-## 4. Rich blocks must earn their place
-
-飞书富 block 是表达手段，不是装饰指标。不要为了“丰富”“高级”“专业”而加入固定比例的 callout、grid、table 或 whiteboard，优先选择最能降低理解成本的表达方式。
-
-| 信息关系 / 场景 | 优先表达 |
-|---|---|
-| 判断、背景、解释、理由 | 段落 / 小标题 |
-| 并列项、短步骤、注意点 | 列表 |
-| 待办、检查项、验收项 | checkbox |
-| 多对象、多字段、排期、指标、接口参数 | table |
-| 少数组并列信息、轻量对比、模块卡片 | grid |
-| 风险、限制、例外、强约束、待确认 | callout |
-| 外部意见、原话、会议纪要、引用材料 | blockquote |
-| 代码、命令、配置、日志 | pre / code |
-| 流程、架构、依赖、路线图、因果链路、复杂模型 | whiteboard |
-
- 组件由信息关系决定，不由重要度决定。重要结论可以是段落、callout、表格或画板，选择标准是它能否让读者更快理解、比较、判断或行动。
- 关键章节需要判断是否存在图示机会，画板用于图示明显降低理解成本的关系：流程、架构、依赖、时间线、因果、分层、组织关系、复杂对比。结构简单或文字更清楚时，不要强行画板化。具体 Mermaid / SVG / SubAgent 路由见 `lark-doc-whiteboard.md`。
- 颜色只在帮助识别语义时使用；正式文档、技术文档、长期知识库和归档材料优先保持朴素。
-
-## 5. Writing style
-
- 从读者一侧写，而不是从系统实现一侧写。用读者能识别和控制的事物命名，默认使用具体、主动、可执行的表达。
- 具体比聪明更好。一致比花哨更重要。文档词汇是读者导航的路标，同一动作、状态、对象在全文中保持同名。
-
-## 6. Calibrate against AI-doc defaults
-
-写作或改写前，主动避开这些 AI 文档默认值：
-
-1. 不管任务是什么都套“背景 / 目标 / 方案 / 风险 / 下一步”。
-2. 用“赋能、闭环、抓手、沉淀、拉通、对齐”等空泛词替代具体动作。
-3. 开头写摘要，但没有结论、取舍、风险或行动。
-4. 为了“丰富”强行加入 callout、table、grid 或 whiteboard。
-5. 把所有重要信息都画板化。
-6. 标题整齐，但章节之间没有真实推进关系。
-7. 章节之间像多个 Agent 拼接，术语、语气、事实口径不一致。
-8. 改写已有文档时全文覆盖，破坏评论、引用、图片、画板或资源块。
-
-如果你的计划看起来像面对任何类似请求都会写出的文档，就修改它，使结构、语气和组件选择更贴合当前读者、任务和体裁。
-
-## 7. Final self-check
-
-交付前检查：
-
-| 指标 | 自检问题 |
-|---|---|
-| 读者任务 | 这篇文档是否帮助目标读者完成理解、判断、决策或行动？ |
-| 体裁匹配 | 结构、语气和证据密度是否符合当前体裁？ |
-| 信息结构 | 标题、顺序、列表、表格和组件是否表达真实关系？ |
-| 阅读负担 | 是否有段落过长、层级过深、表格过宽或组件过多？ |
-| 组件必要性 | callout、grid、table、whiteboard 是否真的降低理解成本？ |
-| 风格一致 | 是否延续用户给定样例或已有文档风格？ |
-| 事实保真 | 改写时是否保留事实、引用、图片、附件、资源块和关键措辞？ |
-| 行动清晰 | 读者下一步应该做什么是否明确？ |
--- a/skills/lark-doc/references/lark-doc-history.md
+++ b/skills/lark-doc/references/lark-doc-history.md
@@ -0,0 +1,107 @@
+# docs history（历史版本与回滚）
+
+用于查看 Docx 历史版本、按 `history_version_id` 回滚，以及查询回滚任务状态。
+
+## 安全流程
+
+1. 先用分页接口 `+history-list` 找到目标版本的 `history_version_id`。
+2. 如果用户指定的是 `revision_id`，不要假设它唯一，也不要把 `revision_id` 直接传给 `+history-revert`。先拉一页并在 `entries[]` 中筛选 `revision_id` 相同的候选；如果未匹配到且 `has_more=true`，继续用 `page_token` 翻页；如果已匹配到候选，最多额外再拉一页补齐可能跨页的相邻候选。最终优先根据用户目标时间与 `edit_time` 的接近程度选择最合适的一条，取同一条的 `history_version_id`；如果没有目标时间，或多个候选无法可靠区分，再向用户展示候选版本（`history_version_id`、`revision_id`、`edit_time`、`name/description`）并确认后回滚。
+3. 如果用户指定的是某一时刻但没有指定 `revision_id`，按 `entries[].edit_time` 匹配；优先选择不晚于目标时刻的最近一条历史记录，无法明确匹配时先向用户确认候选版本。
+4. 再用 `+history-revert --history-version-id <history_version_id>` 发起回滚。默认最多等待 30 秒；如果返回 `status: running`，记录 `task_id`。
+5. 用 `+history-revert-status` 轮询 `task_id`，直到状态不再是 `running`。
+6. 回滚完成后，用 `docs +fetch` 读取文档确认内容。
+
+## 按 revision_id 或时间点回滚
+
+当用户说“回滚到 revision_id=42”“恢复到昨天下午 3 点的版本”这类需求时，流程是：
+
+1. 执行 `docs +history-list --doc <doc>` 获取第一页历史记录；`+history-list` 是分页接口，只有 `has_more=true` 且还需要更多候选时才继续传 `--page-token` 翻页。
+2. 如果用户给出 `revision_id`：先筛选当前页中 `entries[].revision_id == 用户给出的 revision_id`。如果未命中且 `has_more=true`，继续拉下一页；如果已经命中候选，最多额外再拉一页，补齐同一个 `revision_id` 可能跨页出现的相邻 `history_version_id`。若用户同时给出目标时间，在候选里选择 `edit_time` 与目标时间最接近的一条；若未给目标时间但候选只有一条，可直接使用；若多个候选无法可靠区分，不要自行取第一条，向用户展示候选并确认。
+3. 如果用户只给出时间：用 `entries[].edit_time` 匹配，选择目标时刻之前最近的一条；如果用户表达的是“最接近某时刻”，则选择绝对时间差最小的一条。
+4. 从最终匹配条目读取 `history_version_id`。`history_version_id` 对应服务端 `minor_history.version`，这是回滚接口需要的 ID。
+5. 执行 `docs +history-revert --doc <doc> --history-version-id <history_version_id>`。
+
+候选确认时使用类似格式：
+
+```text
+同一个 revision_id 命中多个历史版本，请确认要回滚哪一条：
+- history_version_id=11 revision_id=42 edit_time=2026-06-22T12:24:45Z name=...
+- history_version_id=12 revision_id=42 edit_time=2026-06-22T12:25:14Z name=...
+```
+
+## 命令
+
+```bash
+# 列出历史版本
+lark-cli docs +history-list --doc "<docx_url_or_token>" --page-size 20
+
+# 翻页
+lark-cli docs +history-list --doc "<docx_url_or_token>" --page-size 20 --page-token "<page_token>"
+
+# 回滚到指定 history_version_id（默认等待 30000ms）
+lark-cli docs +history-revert --doc "<docx_url_or_token>" --history-version-id 42
+
+# 只发起任务，不等待
+lark-cli docs +history-revert --doc "<docx_url_or_token>" --history-version-id 42 --wait-timeout-ms 0
+
+# 查询回滚任务状态
+lark-cli docs +history-revert-status --doc "<docx_url_or_token>" --task-id "<task_id>"
+```
+
+## 参数
+
+| 命令 | 参数 | 必填 | 说明 |
+|-|-|-|-|
+| `+history-list` | `--doc` | 是 | Docx URL/token，或可解析为 Docx 的 wiki URL |
+| `+history-list` | `--page-size` | 否 | 返回条数，范围 `1-20`，默认 `20` |
+| `+history-list` | `--page-token` | 否 | 上一页返回的 `page_token` |
+| `+history-revert` | `--doc` | 是 | Docx URL/token，或可解析为 Docx 的 wiki URL |
+| `+history-revert` | `--history-version-id` | 是 | `+history-list` 返回的 `history_version_id`，必须大于 0 |
+| `+history-revert` | `--wait-timeout-ms` | 否 | 等待回滚完成的毫秒数，范围 `0-30000`，默认 `30000` |
+| `+history-revert-status` | `--doc` | 是 | 同一个文档 |
+| `+history-revert-status` | `--task-id` | 是 | `+history-revert` 返回的 `task_id` |
+
+## 返回值要点
+
+`+history-list` 返回：
+
+```json
+{
+  "entries": [
+    {
+      "revision_id": 42,
+      "history_version_id": "11",
+      "edit_time": "1780000000",
+      "type": 1,
+      "name": "版本名",
+      "description": "版本说明",
+      "editor_ids": ["ou_xxx"]
+    }
+  ],
+  "has_more": true,
+  "page_token": "page_token"
+}
+```
+
+`+history-revert` 返回：
+
+```json
+{
+  "task_id": "task_xxx",
+  "status": "running",
+  "history_version_id": "11",
+  "poll_after_ms": 10000
+}
+```
+
+`+history-revert-status` 返回：
+
+```json
+{
+  "status": "partial_failed",
+  "history_version_id": "11",
+  "failed_block_tokens": ["blk_xxx"]
+}
+```
+
+`status` 可能是 `running`、`done`、`partial_failed`、`failed`。当状态是 `partial_failed` 或 `failed` 时，优先检查 `failed_block_tokens`。
--- a/skills/lark-doc/references/lark-doc-update.md
+++ b/skills/lark-doc/references/lark-doc-update.md
@@ -1,11 +1,12 @@

 # docs +update（更新飞书云文档）

-> **前置条件（MUST READ）：**
-> - 仅做明确旧文本 → 新文本的简单替换、错别字修正、日期 / 人名 / 数字替换时，读取本文件即可；写后必须 fetch 验证。
-> - 涉及新增正文、重写段落、调整结构、润色语气、美化排版、补充图表或保真改写时，必须读取：
->   1. [`lark-doc-design-philosophy.md`](lark-doc-design-philosophy.md) — 文档设计判断（读者任务、结构取舍、组件选择、反模板化）
->   2. [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规则（使用 Markdown 格式时改读 [`lark-doc-md.md`](lark-doc-md.md)）
+> **前置条件（MUST READ）：** 生成文档内容前，必须先用 Read 工具读取以下文件，缺一不可：
+> 1. [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规则（使用 Markdown 格式时改读 [`lark-doc-md.md`](lark-doc-md.md)）
+> 2. [`lark-doc-style.md`](style/lark-doc-style.md) — 写作原则（默认段落、按体裁、组件克制）
+> 3. [`lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md) — 改写增强工作流（Code-Act Loop、单 Agent 串行改写）
+>
+> **未读完以上文件就生成内容会导致格式错误。**

 通过八种指令精确更新飞书云文档。支持字符串级别和 block 级别的操作。

@@ -15,26 +16,6 @@
 >
 > **Markdown 局限 & block ID 前提：** Markdown 不携带 block ID，也无样式（颜色、对齐、callout 等）。需要按 block ID 定位（`block_*` 指令的 `--block-id`）时，先 `docs +fetch --detail with-ids` **配合 `--scope`（`outline` / `range` / `keyword` / `section`）局部获取**目标段落，不要全量 fetch。拿到 block ID 后 `--content` 仍可用 Markdown，只是写入内容不带样式。

-## Observe-Diagnose-Patch Loop
-
-适用于修改已有飞书文档：调整语气、精简冗余、增补章节、修复结构混乱、按领导意见修改，或在已有图片、引用、表格、评论、资源块的文档上做保真改写。
-
-> [!IMPORTANT]
-> 核心原则：先观察，再诊断，再局部 patch，最后 fetch 验证。这个流程比全文重写安全；除非用户明确要求完全重建，或文档确实已无保留价值，不要轻易使用 `overwrite`，否则会丢失评论和未支持的资源。
-> 每次 `docs +update` 后，都按 block ID 已发生变更处理。如果需要继续修改、重复修改同一处内容，或引用刚插入 / 替换后的内容，必须先重新 `docs +fetch --detail with-ids` 拉取最新内容和 block ID，再执行下一轮 patch。
-
-1. **Observe（读取现状）**：先 `docs +fetch` 读取当前文档状态，并按意图选择最小范围。
-   - 改某一节或大文档：先 `--scope outline --max-depth 2` 找章节，再 `--scope section --start-block-id <标题id> --detail with-ids`
-   - 精确跨节区间：用 `--scope range --start-block-id xxx --end-block-id yyy`
-   - 只有模糊关键词：用 `--scope keyword --keyword xxx --context-before 1 --context-after 1 --detail with-ids`
-   - 明确整篇重构才读 `--detail with-ids` 全文；只读摘要或确认事实时用更轻的 fetch
-2. **Diagnose（诊断问题）**：判断用户目标、当前结构、语气、重复、断流、事实口径和需要保留的资源；识别哪些 block 必须原样保留。
-3. **Patch Plan（制定局部计划）**：把修改拆成最小安全操作：简单行内替换用 `str_replace`；整段/整块重写用 `block_replace`；增补章节用 `block_insert_after`；删冗余用 `block_delete`；调整顺序用 `block_move_after`。
-4. **Patch（精确修改）**：按 block / section 执行局部命令。保护 `<cite>`、`<img>`、`<source>`、`<whiteboard>`、`<sheet>`、`<bitable>`、`<synced_reference>` 等 token 化内容，不要改成纯文本或占位符。同一 block 的多处修改合并成一次 `block_replace`。
-5. **Verify（fetch 验证）**：每轮写操作后按影响范围重新 fetch，检查用户要求、结构、语气、事实、资源块和 block ID 是否符合预期；不满足就基于最新 fetch 结果继续 Diagnose / Patch，不要沿用上一轮 block ID。
-
-复杂结构重组时，优先“先插入新结构，再删除旧 block”：用 `block_insert_after` 插入 grid / table / callout / 新章节，再用 `block_delete` 删除旧段落。这样比 `overwrite` 更能保住图片、评论、引用、资源块和不相关内容。`str_replace` 的匹配范围取决于格式：XML 模式只适合行内匹配；Markdown 模式可跨行和使用 `前缀...后缀`，但跨 block 或容器级重写仍优先用 block 指令。
-
 ## 参数

 | 参数 | 必填 | 说明 |
@@ -64,12 +45,12 @@

 ## Block ID 生命周期

-安全规则：每次写操作后都按 block ID 已变更处理。需要连续修改、重复修改或操作新插入内容时，必须重新 fetch 最新内容和 block ID；不要默认复用之前 fetch 到的 block ID。
+写操作后不要默认复用之前 fetch 到的 block ID：

- `overwrite` / `block_replace` / `block_delete`：受影响旧 ID 失效，继续 block 级操作前必须重新 fetch
- `block_insert_after` / `append` / `block_copy_insert_after`：新内容一定是新 ID；要操作新内容或继续编辑插入点附近内容，先重新 fetch
- `block_move_after`：位置、章节、range 语义已变化；后续依赖位置或章节边界时重新 fetch
- `str_replace`：即使是简单行内替换，也不要在后续 block 级操作中假设旧 ID 仍正确；跨行 / 大段替换后必须重新 fetch
+- `overwrite` / `block_replace` / `block_delete`：受影响旧 ID 失效，继续 block 级操作前重新 fetch
+- `block_insert_after` / `append` / `block_copy_insert_after`：锚点 / 源 ID 通常保留，新内容是新 ID；要操作新内容先重新 fetch
+- `block_move_after`：被移动 ID 通常保留，但位置、章节、range 语义变化；后续依赖位置时重新 fetch
+- `str_replace`：简单行内替换通常不改变 ID；跨行 / 大段替换后如继续 block 级操作，先重新 fetch

 ## 指令示例

@@ -216,15 +197,63 @@ lark-cli docs +update --doc "<doc_id>" --command block_move_after \
 | `warnings` | 警告信息列表 |
 | `document.new_blocks` | 本次操作新增的 block 列表（如画板）。`block_id` 可用于后续精确编辑；`block_token` 是资源块 token（如画板）可交给 `lark-whiteboard` 等 skill 继续操作 |

+## 典型工作流
+
+### 精确 block 级更新
+
+1. **获取文档内容和 block ID**：
+   ```bash
+   lark-cli docs +fetch --doc "<doc_id>" --detail with-ids
+   ```
+
+2. **定位目标 block**：从返回的 XML 中找到要修改的 block 及其 `id` 属性
+
+3. **执行更新**：
+   ```bash
+   # 替换特定 block
+   lark-cli docs +update --doc "<doc_id>" --command block_replace \
+     --block-id "blkcnXXXX" --content "<p>新内容</p>"
+
+   # 在某 block 后插入
+   lark-cli docs +update --doc "<doc_id>" --command block_insert_after \
+     --block-id "blkcnXXXX" --content "<h2>追加的章节</h2>"
+   ```
+
+### 简单文本替换
+
+不需要 block ID，直接匹配替换：
+
+```bash
+lark-cli docs +update --doc "<doc_id>" --command str_replace \
+  --pattern "v1.0" --content "v2.0"
+```
+
 ## 画板处理

 > **`docs +update` 不能直接编辑已有画板的内容。** 本命令只能**新增**画板块；要修改已有画板，先用 `docs +fetch` 取到 `<whiteboard token="...">`，再按 [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md) 启动 SubAgent 读取 [`lark-whiteboard`](../../lark-whiteboard/SKILL.md) 并写入。

-新增画板的语法选型见 [`lark-doc-xml.md`](lark-doc-xml.md) 的资源块说明；插入和复杂画板处理见 [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md)。
+画板的语法选型与插入示例见 [`lark-doc-xml.md`](lark-doc-xml.md) 与 [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md)。
+
+## 最佳实践
+
+- **精确操作优于全文覆盖**：使用 `block_replace`/`block_insert_after` 精确修改，避免 `overwrite` 全文覆盖
+- **str_replace 的匹配范围取决于格式**：
+  - **XML 模式（默认）**：`--pattern` 只支持**行内**匹配，不支持跨行 / 跨 block。段落、整块或容器级（列表、表格、分栏、引用块等）改动请改用 `block_replace` 指定 block_id 重建。
+  - **Markdown 模式**（`--doc-format markdown`）：`--pattern` 同时支持**行内和跨行**匹配，还支持 `前缀...后缀` 省略号语法（用 `...` 串联首尾片段匹配一大段内容），可以一次替换多行文本；但仍建议优先按最小片段匹配，跨 block 容器级重写仍优先用 `block_replace`，避免副作用。
+- **保护不可重建的内容**：图片、画板、电子表格等以 token 形式存储，替换时避开这些 block
+- **str_replace 的 replacement 支持富文本**：可以用行内标签 `<b>`、`<a>`、`<cite>`、`<latex>` 等替换普通文本为富文本
+- **同一 block 只能被 replace 一次**：多次修改同一 block 请合并为一次 block_replace
+- **block_delete 支持批量**：用逗号分隔多个 block_id 一次删除
+- **复杂结构重组**：将多个段落转换为 grid / table 等复杂布局时，分步操作比 overwrite 更安全：
+  1. 用 `block_insert_after` 在目标位置插入新的富文本结构
+  2. 用 `block_delete` 批量删除旧的 block
+  3. 这样可以保留文档中其他不相关的内容（图片、评论等）
+- **表达形式**：插入或替换内容时，优先沿用用户要求和已有文档风格；需要结构化表达时可参考 [`lark-doc-style.md`](style/lark-doc-style.md)，但不要为了固定丰富度主动添加组件

 ## 参考

- [`lark-doc-design-philosophy.md`](lark-doc-design-philosophy.md) — 文档设计判断与组件取舍
+- [`lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md) — 改写增强工作流（Code-Act Loop、单 Agent 串行改写）
+- [`lark-doc-style.md`](style/lark-doc-style.md) — 文档写作原则（默认段落、按体裁、组件克制）
 - [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规范
 - [`lark-doc-fetch.md`](lark-doc-fetch.md) — 获取文档
 - [`lark-doc-create.md`](lark-doc-create.md) — 创建文档
--- a/skills/lark-doc/references/lark-doc-whiteboard.md
+++ b/skills/lark-doc/references/lark-doc-whiteboard.md
@@ -6,7 +6,7 @@

 | Skill             | 核心职责                                                      | 约束                              |
 |-------------------|-----------------------------------------------------------|---------------------------------|
-| `lark-doc`        | 识别画板机会、使用 Mermaid/SVG 创建图表、调度 SubAgent、插入简单图表或复杂空白画板 | 简单图可由主 Agent 直接写入；复杂图再隔离到 SubAgent |
+| `lark-doc`        | 识别画板机会、使用 Mermaid/SVG 创建图表、调度 SubAgent、插入简单 SVG 画板或复杂空白画板 | 主 Agent 不直接创作画板内容；              |
 | `lark-whiteboard` | 查询/导出已有画板；复杂图表生成（Mermaid/DSL/SVG 路由、场景选型、渲染验证）；写入已有/空白画板  | 仅特别复杂的图表或已有画板更新时由独立 SubAgent 读取 |

 ## 画板适用规则
@@ -29,9 +29,11 @@
 > [!IMPORTANT]
 > ⚠️ **分别对每个图表进行决策**

-如果有多个位置需要插入图表，你需要根据每个图表的内容**分别决定**采用步骤 2A 还是 2B。思维导图、时序图、类图、饼图、甘特图可插入 mermaid 块；其他类型图表使用 SVG，简单图由主 Agent 直接写入，复杂图再启动 SubAgent。
+如果有多个位置需要插入图表，你需要根据每个图表的内容**分别决定**采用步骤 2A 还是 2B
+中的方式插入这个图表。在需要插入思维导图、时序图、类图、饼图、甘特图的时候可以插入 mermaid 块，在需要插入其他类型图表时启动
+SubAgent 插入 SVG。

-简单 Mermaid / SVG 图可由主 Agent 直接写入本地 XML；需要专门视觉设计、信息密度较高或容易布局翻车的 SVG，再启动 SubAgent 产出完整片段。
+建议优先使用 SVG 插入图表，除非其属于思维导图、时序图、类图、饼图、甘特图这类可以直接使用 mermaid 语法描述，且不适宜用 SVG 绘制的图表

 ### 步骤 2A: 使用 mermaid 插入图表

@@ -42,9 +44,9 @@
 </whiteboard>
 ```

-### 步骤 2B: 使用 SVG 插入图表
+### 步骤 2B: SubAgent 使用 SVG 插入图表

-简单 SVG 可由主 Agent 直接写入草稿；复杂 SVG 则启动 SubAgent，让它用 `docs +create` / `docs +update` 插入：
+主 Agent 启动 SubAgent，让它用 `docs +create` / `docs +update` 插入：

 ```xml

@@ -54,7 +56,7 @@
 </whiteboard>
 ```

-复杂 SVG SubAgent 需要携带以下的最小上下文，以及后续的 [SVG 设计 Workflow] 章节指南：
+Sub Agent 需要携带以下的最小上下文，以及后续的 [SVG 设计 Workflow] 章节指南：

 - doc token、插入位置（标题 / block_id / command）
 - 图表目标、受众、源段落或数据
--- a/skills/lark-doc/references/lark-doc-word-stat.md
+++ b/skills/lark-doc/references/lark-doc-word-stat.md
@@ -13,6 +13,13 @@ lark-cli docs +fetch --doc "$URL" --doc-format xml --detail full --format json \

 `$URL` 可以是用户给出的 docx/wiki URL，也可以是可被 `docs +fetch` 解析的 token。

+## 统计范围
+
+先判断用户要求的是**整篇文档**还是**局部内容**：
+
+- 整篇文档的总字数 / 总字符数：按上方「调用方式」抓取 `full` 内容后统计。
+- 本次新增 / 替换 / 改写片段的字数：优先统计拟写内容本身；内容已写入文档时，只 fetch 对应 block / range 后统计。不得用整篇文档字数对比局部目标。
+
 如需在自动化或回归验证中发现未覆盖块类型，追加严格参数：

 ```bash
@@ -36,6 +43,15 @@ lark-cli docs +fetch --doc "$URL" --doc-format xml --detail full --format json \

 如果 `unknown_blocks` 或 `unsupported_blocks` 非空，回复用户时要说明“已统计可提取文本，但存在未覆盖块，结果可能偏低”，并列出对应块类型。为空时可直接给出结果。

+## 字数遵循校验
+
+当用户给了明确字数要求（写 N 字 / x-y 字 / x 字左右 / 上下浮动）时执行；没有明确字数要求则跳过。字数必须按本文流程用脚本统计，不要自己估。
+
+1. 先按「统计范围」确认统计对象，再把要求归一成目标区间：`>x`→`[x+1, +∞)`；`<y`→`(-∞, y-1]`；`x-y`→`[x, y]`；`x 字左右`→`[round(0.9x), round(1.1x)]`
+2. 按统计对象选择对应输入并调用脚本统计实际字数，读取输出里的 `word_count`
+3. 对比 `word_count` 与目标区间：区间内即通过；低于下限 → 补充**实质内容**（非注水）；高于上限 → 删减冗余内容。改完重新统计
+4. **最多 2 轮**。2 轮后仍不达标：停止，不得为达标而注水或删关键内容；如实汇报【目标区间 / 当前字数 / 差值与方向 / 已试 2 轮 / 未达原因】，**禁止谎称达标**
+
 ## 输出示例

 输入正文等价于：`标题` + `一个苹果是 an apple。` 时，输出形态如下：
--- a/skills/lark-doc/references/lark-doc-xml.md
+++ b/skills/lark-doc/references/lark-doc-xml.md
@@ -41,7 +41,7 @@ p, h1-h9, ul, ol, li, table, thead, tbody, tr, th, td, blockquote, pre, code, hr
 文档中可嵌入外部资源块（属于容器标签的特殊形式），需要额外语法创建：

 - `<img>` — `<img href="https://..."/>` 上传网络图片
- `<whiteboard>` — 简单 Mermaid / SVG 图可由主 Agent 直接写入；复杂 SVG 可启动 SubAgent 产出完整 `<whiteboard type="svg">完整自包含 SVG</whiteboard>`；特别复杂或已有画板更新，使用 `<whiteboard type="blank"></whiteboard>` 先创建空白画板，再按 [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md) 启动 SubAgent 调用 `lark-whiteboard` 写入；
+- `<whiteboard>` — 简单图由 SubAgent 直接插入 `<whiteboard type="svg">完整自包含 SVG</whiteboard>`；复杂图使用 `<whiteboard type="blank"></whiteboard>` 先创建空白画板，再按 [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md) 启动 SubAgent 调用 `lark-whiteboard` 写入；
 - `<sheet>` — `<sheet type="blank"></sheet>` 空白；`<sheet sheet-id="SID" token="TOKEN"></sheet>` 复制已有
 - `<task>` — `<task task-id="GUID"></task>`，必传 task-id（任务 guid）
 - `<chat_card>` — `<chat_card chat-id="CHAT_ID"></chat_card>`，必传 chat-id
--- a/skills/lark-doc/references/style/lark-doc-create-workflow.md
+++ b/skills/lark-doc/references/style/lark-doc-create-workflow.md
@@ -0,0 +1,46 @@
+# 从零创作工作流
+
+用户提供主题、需求或简要说明，需要生成一份新的飞书文档时，遵循本工作流。
+
+## 核心方法论 — Code-Act Loop
+
+通过自适应的 **Code-Act Loop** 驱动文档创作，而非固定模板式的工作流。每次任务都循环执行：
+
+1. **Plan（规划）** — 根据用户目标和文档当前状态，评估下一步该做什么
+2. **Execute（执行）** — 由主 Agent 自己运行 `lark-cli docs` 命令推进正文；仅画板渲染按需隔离到 SubAgent（见步骤三）
+3. **Observe（观察）** — 检查命令输出，验证正确性，确认内容是否满足用户目标
+4. **Iterate（迭代）** — 如需调整，回到 Plan 继续循环
+
+循环在文档达到质量标准且满足用户需求时结束。不要试图一次性产出完美内容——迭代打磨效果更好。根据用户实际需求灵活决定文档结构和版块，而不是套用固定模板。
+
+
+## 典型 Code-Act Loop 流程
+
+### 步骤一：规划与撰写（单 Agent 串行）
+
+正文由主 Agent 串行维护，**不按章节拆给并行 Agent**，避免上下文割裂、重复矛盾和全文级约束失效。
+
+1. 分析用户需求：受众、目的、范围
+2. 设计大纲：根据任务自然选择结构。可以是短文、纪要、FAQ、方案、报告、清单或其他形式；不要默认套固定章节、固定开头或固定富 block 配比
+3. `docs +create` 创建并撰写：
+   - **短文档**：一次写入完整内容
+   - **长文档**：先建骨架（标题 + 各级标题），再由主 Agent **顺序逐节**用 `block_insert_after --block-id <章节标题 block_id>` 补全正文；写完一节再写下一节，始终带着已写内容的上下文，保证衔接、不重复
+   - ⚠️ 不要一次性把超长完整内容塞进 `--content`，容易触发字符/参数限制；长文按节分次写入
+   - ⚠️ 同一节内多次插入时，要锚到**上一个新插入的 block**（按 [`lark-doc-update.md`](../lark-doc-update.md) 的「Block ID 生命周期」），否则反复锚同一个标题会让段落顺序颠倒
+   - ⚠️ 若先建骨架写了占位摘要，补正文时**删除占位摘要**，不要留残渣
+   - ⚠️ **`@file` 路径限制**：`--content @file` 只接受当前工作目录下的相对路径，传绝对路径（如 `@/tmp/xxx.md`）会报 `unsafe file path`。需要落盘时，将文件写在 cwd 下，用完自行清理
+
+### 步骤二：整合审查与画板识别（串行）
+
+4. `docs +fetch --api-version v2 --detail with-ids` 获取文档，审查整体效果
+5. 评估内容是否满足用户目标：事实是否完整、结构是否清楚、语气是否匹配、是否保留必要素材；检查跨节有无重复、矛盾或断流。再按 `lark-doc-style.md` 的「写完自检」快速核对，发现问题就地定向修正
+6. **画板识别**：逐章节扫描，判断是否有段落用图明显比文字更易懂（流程 / 架构 / 时间线 / 对比 / 占比等，见 `lark-doc-style.md` 的画板原则）。默认用文字，只有确需图示才记录需要插图的章节、推荐画板类型、mermaid/SVG 路径和用于画图的源内容
+
+### 步骤三：画板处理与润色
+
+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。若执行了专项校验，向用户呈现结果
--- a/skills/lark-doc/references/style/lark-doc-style.md
+++ b/skills/lark-doc/references/style/lark-doc-style.md
@@ -0,0 +1,68 @@
+# 飞书文档写作原则
+
+写飞书文档，像一个该领域资深的人类作者那样写，而不是把内容"装配"成组件。
+本文只讲"何时用、什么风格"；具体标签 / 命令语法见 [`lark-doc-xml.md`](../lark-doc-xml.md)。
+
+## 一、用户明确要求优先
+
+用户点名要某种格式——高亮块、分栏、列表、某编号体例、表格、画板、某模板、某已有文档的风格——**一律照用户的来，下面的"默认克制"全部让位**。用户给了样例或已有文档，就沿用它的结构与语气。
+
+## 二、默认写连贯段落
+
+用户没指定时，**默认是连贯段落**；其余按内容类型分流，别一律"少用结构"，也别什么都升标题：
+
+| 内容 | 用什么 | ❌ 别 |
+|---|---|---|
+| 叙述、论证、分析、说明 | **连贯段落** | 拆成列举 |
+| 真·行列数据（预算、指标、对比、排期、字段说明） | **表格** | 写成段落或把字段堆成一行 |
+| 字段:值（主题、时长、负责人等，少量） | **加粗标签行**或一句话 | 每字段一个标题 |
+| 方法 / 措施 + 每项一段描述 | **加粗引导句段落**（「**全程督导。**…」） | 每项升标题 |
+| 任务清单 / 检查项 / 待办事项 | **`<checkbox>`** | 用普通列表替代可交互待办 |
+| 纯短并列项（无描述，如材料清单） | 列表 | — |
+| 章节（内容成块、需在目录导航） | 标题层级 | — |
+
+- 判断标准：**去掉结构后能顺成段落，就用段落；成行成列的数据，就用表格。**
+- **红线一：标题层级只给"章节"。** "小标题 + 一两句话"的小项（字段、方法、要点）不该占标题层级——按上表降成标签行 / 加粗引导句段落（否则目录里全是没信息量的条目）。
+- **红线二：列举（「一是 / 二是」「第一 / 第二」「(1)(2)(3)」）只给真正并列的具体项，且别每节都用。**
+  - 「一是 / 二是」是党务列举的措辞——只用在列具体的**问题 / 措施**那一处；背景、现状、认识、分析、过渡、总结**一律成段**。
+  - **整篇每段 / 每节都"一是 / 二是"，和"每段一个 bullet"是同一个骨架化的错——不因为是党务就变对**（纯清单 / 台账类除外）。
+
+## 三、按体裁写
+
+- **公文 / 法律 / 学术 / 申报 / 项目方案等严肃正式提交物**：靠规范的标题层级、段落与编号体系表达；**默认不用高亮块、分栏**，要强调用加粗或规范小标题。
+- **面向公众号、微信等外部平台粘贴 / 发布的内容**：不用飞书特有富 block（高亮块、分栏等），粘出去会丢样式 / 错乱；改用标准标题、段落、列表、引用。
+- **一般文档**：以可读为先，不堆砌结构。
+
+## 四、编号与层级
+
+- **一套编号体例、全篇一致；最忌中文大层级与阿拉伯小数编号混用。**
+  - 公文 / 正式材料常用：「一、→（一）→ 1.→（1）」（中文大层级 + 阿拉伯细分层级）。
+  - 学术 / 技术 / 商业报告：「1 → 1.1 → 1.1.1」或「一、→（一）→ 1.」，**择一**。
+  - ⚠️ **「一、」只能配「（一）」；要用阿拉伯小数就从顶层全用「1 / 1.1」。绝不「一、」配「1.1 / 2.1」**——这是最常见的混用。
+  - **不混用**多套（别"第X部分"+"一、"+"1."混着来）；**同级不跳号**；**不跳级**。
+- **编号 / 标题层级只给"章节"**，不要为了凑齐体例把每个小项都编上「（一）」、升成标题（小项处理方式见上文「二、默认写连贯段落」）。
+- 简单的 1.2.3 并列项用原生 `<ol><li seq="auto">…</li></ol>` 让飞书自动编号、自动对齐；「一、(一)」原生产不出，才手打成文字——此时用标题级别表达层次，**不靠手动缩进**、各级顶格（全角括号「（）」叠手动缩进会视觉错位）。
+
+## 五、飞书特有组件，克制使用
+
+- **高亮块 `<callout>`**：很重的强提醒信号，**默认不用**；只给"不提醒就会出错 / 遗漏"的关键项，全文极少（0~1 个），不要每节导语 / 结论都做成高亮块。
+- **分栏 `<grid>`**：仅左右信息量相当、确需并排对照的短内容；否则用段落或表格。
+- **画板**：默认用文字，只在**图示明显比文字更易懂**（流程、架构、时间线、对比、占比等）或用户要求时才用。怎么插、用哪种类型见 [`lark-doc-xml.md`](../lark-doc-xml.md) 与 [`lark-doc-whiteboard.md`](../lark-doc-whiteboard.md)。
+- **颜色**：默认朴素、不上色；需要时保持语义一致，按下表选择对应颜色，不为装饰上色。可用色见 [`lark-doc-xml.md`](../lark-doc-xml.md) 的「美化系统」。
+
+| 语义 | 背景色 | 文字色 |
+|-|-|-|
+| 信息、说明 | `light-blue` | `blue` |
+| 成功、推荐 | `light-green` | `green` |
+| 警告 / 错误 / 风险 | `light-red` | `red` |
+| 注意、待确认 | `light-yellow` | `yellow` |
+| 中性、辅助 | `light-gray` | — |
+
+## 六、写完自检
+
+交付前快速回看：
+- **叙述是否被列举化**：背景 / 现状 / 认识 / 分析 / 成效 / 过渡 / 总结等应成段；列举只用于同层级、可并列处理的信息，如问题、措施、步骤、任务或材料清单。若正文反复使用连续编号、项目符号或固定并列句式，导致内容缺少叙述，应把背景 / 认识 / 分析 / 过渡改写成有承接关系的段落（纯清单 / 台账类除外）。
+- **数据是否正确呈现**：成行成列的数据应使用表格呈现，不要写成段落，也不要用分隔符把多个字段硬串在一起。
+- **标题是否滥用**："小标题 + 一句话"的小项不要升成标题；应改成标签行、加粗引导句段落或普通段落。
+- **编号是否统一**：全篇一套、不跳号、不跳级，尤其不要中文 + 阿拉伯混用（如「一、」配「1.1」）。
+- **组件是否克制且保真**：高亮块 / 分栏 / 画板 / 颜色应符合体裁和用户要求；引用 / 图片 / 资源块必须保留。
--- a/skills/lark-doc/references/style/lark-doc-update-workflow.md
+++ b/skills/lark-doc/references/style/lark-doc-update-workflow.md
@@ -0,0 +1,48 @@
+# 改写增强工作流
+
+用户提供已有文档链接或 token，需要改写、润色、补充或重排版时，遵循本工作流。
+
+## 核心方法论 — Code-Act Loop
+通过自适应的 **Code-Act Loop** 驱动文档改写，而非固定模板式的工作流。每次任务都循环执行：
+1. **Plan（规划）** — 根据用户目标和文档当前状态，评估下一步该做什么
+2. **Execute（执行）** — 由主 Agent 自己运行 `lark-cli docs` 命令推进改写；仅画板渲染按需隔离到 SubAgent（见步骤二）
+3. **Observe（观察）** — 检查命令输出，验证正确性，确认内容是否满足用户目标
+4. **Iterate（迭代）** — 如需调整，回到 Plan 继续循环
+
+## 核心原则：精准手术优于全量覆盖
+1. **精准手术**：只改用户指定的 block，不改其他 block。
+2. **全量覆盖**：如果用户明确要改整篇，才用 `overwrite` 命令。
+3. **保真约束**：改写时原文里的 `<cite type="user">`（@人）、`<cite type="doc">`（@文档）、`<img>`、`<source>`、`<whiteboard>`、`<sheet>`、`<bitable>`、`<synced_reference>` 等行内组件和资源块一律原样保留（含所有 token / user-id / doc-id 属性），不许替换成纯文本姓名、链接或占位符。
+
+## 工作流程
+
+### 步骤一：分析与画板识别（串行）
+
+1. **选择读取范围**（节省上下文的关键）：
+   - 用户只改某一节 / 文档较大 → 先 `docs +fetch --scope outline --max-depth 2` 拿目录，再 `docs +fetch --scope section --start-block-id <目标标题id> --detail with-ids` 精读该节（`section` 会自动展开到下一个同级/更高级标题前，不用手动算结束 block id）
+   - 需要精确跨节区间 → `docs +fetch --scope range --start-block-id xxx --end-block-id yyy`（或 `--end-block-id -1` 读到末尾）
+   - 用户只给了模糊关键词 → `docs +fetch --scope keyword --keyword xxx --context-before 1 --context-after 1 --detail with-ids`
+   - 用户明确要改整篇 → `docs +fetch --detail with-ids`
+   - 详见 [`lark-doc-fetch.md`](../lark-doc-fetch.md) 中「选 `--scope`（读取范围）」小节
+2. 系统性评估：用户想改什么、现有文档风格是什么、哪些内容需要保留、哪些问题影响理解
+3. **画板识别**：逐章节扫描，判断是否有段落用图明显比文字更易懂（流程 / 架构 / 时间线 / 对比 / 占比等，见 `lark-doc-style.md` 的画板原则）。默认用文字，只有确需图示才记录需要插图的章节（block ID）、推荐画板类型、mermaid/SVG路径和源内容片段
+4. 向用户简要说明改进计划（包含识别出的画板机会）
+
+### 步骤二：定向改写（单 Agent 串行）
+
+5. **优先处理步骤一识别出的画板候选段落**：读取并按 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md) 选型和插入；正文本身不交给 SubAgent
+6. 由主 Agent **顺序逐节**改写，**不按章节拆给并行 Agent**，避免上下文割裂、重复矛盾和全文级约束失效：
+   - 沿用或轻微调整已有文档风格，除非用户要求彻底重排版
+   - 优先通过重写段落、调整标题、补充小标题提升可读性；叙述内容保持成段，**不要默认改成列表**，只有确属并列要点 / 步骤才用列表（见 `lark-doc-style.md`）
+   - 富 block 是可选表达手段，不因固定比例而添加，取舍遵循 `lark-doc-style.md` 的写作原则；画板类需求只走第 5 步
+
+### 步骤三：验证（串行）
+
+7. 获取更新后文档局部内容，检查是否符合用户目标和已有风格
+8. 检查是否满足用户目标并保留原有关键内容。再按 `lark-doc-style.md` 的「写完自检」快速核对，发现问题则定向修正
+
+### 步骤四：专项校验（按需执行）
+
+9. 仅当用户预期需要校验字数时，才读取并执行 [`lark-doc-word-stat.md`](../lark-doc-word-stat.md) 的「字数遵循校验」；否则跳过本项，不读取该 workflow。若执行了专项校验，向用户呈现结果
+
+**上下文节省提示**：主 Agent 改某节时如需重新读取，优先用 `docs +fetch --scope section --start-block-id <章节标题id>`（自动覆盖整节），或 `--scope range --start-block-id xxx --end-block-id yyy` 精确区间，只拉当前章节，不要重复拉全文。
--- a/tests/cli_e2e/docs/coverage.md
+++ b/tests/cli_e2e/docs/coverage.md
@@ -1,9 +1,9 @@
 # Docs CLI E2E Coverage

 ## Metrics
- Denominator: 8 leaf commands
- Covered: 3
- Coverage: 37.5%
+- Denominator: 11 leaf commands
+- Covered: 6
+- Coverage: 54.5%

 ## Summary
 - TestDocs_CreateAndFetchWorkflow: proves `docs +create` and `docs +fetch`; key `t.Run(...)` proof points are `create as bot` and `fetch as bot`.
@@ -11,6 +11,8 @@
 - TestDocs_UpdateWorkflow: proves `docs +update` via `update-title-and-content as bot`, then re-fetches the same doc in `verify as bot` to assert persisted title/content changes.
 - TestDocs_DryRunDefaultsToV2OpenAPI: proves `docs +create`, `docs +fetch`, and `docs +update` dry-run all emit `/open-apis/docs_ai/v1/...` requests without MCP or `--api-version` guidance; its fetch case asserts fetch sends the default `extra_param`, and its update case asserts `--reference-map` is sent as request body `reference_map`.
 - TestDocs_CreateTitleDryRunPrependsContent: proves `docs +create --title` dry-run prepends an escaped `<title>...</title>` tag to request body `content`.
+- TestDocs_DryRunDefaultsToV2OpenAPI also proves `docs +history-list`, `docs +history-revert`, and `docs +history-revert-status` dry-run endpoint and query/body shapes.
+- TestDocs_HistoryWorkflow proves the guarded live history flow (`LARK_DOC_HISTORY_E2E=1`): create, update, list prior revisions, revert, poll status when needed, and fetch to verify reverted content.
 - Setup note: docs workflows create a Drive folder through `drive files create_folder` in `helpers_test.go`; that helper is external to the docs domain and is not counted here.
 - Blocked area: media and search shortcuts still need deterministic fixtures and local file orchestration.

@@ -20,6 +22,9 @@
 | --- | --- | --- | --- | --- | --- |
 | ✓ | docs +create | shortcut | docs/helpers_test.go::createDocWithRetry; docs_create_fetch_test.go::TestDocs_CreateAndFetchWorkflowAsUser/create as user; docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/create; docs_update_dryrun_test.go::TestDocs_CreateTitleDryRunPrependsContent | `--parent-token`; `--doc-format markdown`; `--content`; `--title` | helper asserts returned doc id from `data.document.document_id`; dry-run asserts title is prepended into request body content |
 | ✓ | docs +fetch | shortcut | docs_create_fetch_test.go::TestDocs_CreateAndFetchWorkflow/fetch as bot; docs_update_test.go::TestDocs_UpdateWorkflow/verify as bot; docs_create_fetch_test.go::TestDocs_CreateAndFetchWorkflowAsUser/fetch as user; docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/fetch | `--doc <docToken>`; `--doc-format markdown`; default `extra_param.enable_user_cite_reference_map=true` | |
+| ✓ | docs +history-list | shortcut | docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/history list; docs_history_workflow_test.go::TestDocs_HistoryWorkflow | `--doc`; `--page-size`; `--page-token` | live workflow gated by `LARK_DOC_HISTORY_E2E=1` |
+| ✓ | docs +history-revert | shortcut | docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/history revert; docs_history_workflow_test.go::TestDocs_HistoryWorkflow | `--doc`; `--history-version-id`; `--wait-timeout-ms` | live workflow gated by `LARK_DOC_HISTORY_E2E=1` |
+| ✓ | docs +history-revert-status | shortcut | docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/history revert status; docs_history_workflow_test.go::TestDocs_HistoryWorkflow | `--doc`; `--task-id` | live workflow polls only when revert returns `running` |
 | ✕ | docs +media-download | shortcut |  | none | no media fixture workflow yet |
 | ✕ | docs +media-insert | shortcut |  | none | requires deterministic upload fixture and rollback assertions |
 | ✕ | docs +media-preview | shortcut |  | none | requires deterministic media fixture |
--- a/tests/cli_e2e/docs/docs_history_workflow_test.go
+++ b/tests/cli_e2e/docs/docs_history_workflow_test.go
@@ -0,0 +1,137 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package docs
+
+import (
+	"context"
+	"os"
+	"testing"
+	"time"
+
+	clie2e "github.com/larksuite/cli/tests/cli_e2e"
+	"github.com/larksuite/cli/tests/cli_e2e/drive"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"github.com/tidwall/gjson"
+)
+
+func TestDocs_HistoryWorkflow(t *testing.T) {
+	if os.Getenv("LARK_DOC_HISTORY_E2E") != "1" {
+		t.Skip("set LARK_DOC_HISTORY_E2E=1 to run docs history live workflow")
+	}
+	clie2e.SkipWithoutUserToken(t)
+
+	parentT := t
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Minute)
+	t.Cleanup(cancel)
+
+	suffix := clie2e.GenerateSuffix()
+	folderName := "lark-cli-e2e-docs-history-folder-" + suffix
+	docTitle := "lark-cli-e2e-docs-history-" + suffix
+	originalMarker := "original history marker " + suffix
+	updatedMarker := "updated history marker " + suffix
+	const defaultAs = "user"
+
+	folderToken := drive.CreateDriveFolder(t, parentT, ctx, folderName, defaultAs, "")
+	docToken := createDocWithRetry(t, parentT, ctx, folderToken, docTitle, originalMarker, defaultAs)
+
+	updateResult, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args: []string{
+			"docs", "+update",
+			"--doc", docToken,
+			"--command", "overwrite",
+			"--doc-format", "markdown",
+			"--content", "# " + docTitle + "\n\n" + updatedMarker,
+		},
+		DefaultAs: defaultAs,
+	})
+	require.NoError(t, err)
+	updateResult.AssertExitCode(t, 0)
+	updateResult.AssertStdoutStatus(t, true)
+
+	fetchUpdated, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args:      []string{"docs", "+fetch", "--doc", docToken, "--doc-format", "markdown"},
+		DefaultAs: defaultAs,
+	})
+	require.NoError(t, err)
+	fetchUpdated.AssertExitCode(t, 0)
+	fetchUpdated.AssertStdoutStatus(t, true)
+	updatedContent := gjson.Get(fetchUpdated.Stdout, "data.document.content").String()
+	assert.Contains(t, updatedContent, updatedMarker)
+	currentRevision := gjson.Get(fetchUpdated.Stdout, "data.document.revision_id").Int()
+	require.Greater(t, currentRevision, int64(0), "stdout:\n%s", fetchUpdated.Stdout)
+
+	var revertHistoryVersionID string
+	require.Eventually(t, func() bool {
+		listResult, listErr := clie2e.RunCmd(ctx, clie2e.Request{
+			Args: []string{
+				"docs", "+history-list",
+				"--doc", docToken,
+				"--page-size", "20",
+			},
+			DefaultAs: defaultAs,
+		})
+		require.NoError(t, listErr)
+		listResult.AssertExitCode(t, 0)
+		listResult.AssertStdoutStatus(t, true)
+		for _, entry := range gjson.Get(listResult.Stdout, "data.entries").Array() {
+			revisionID := entry.Get("revision_id").Int()
+			historyVersionID := entry.Get("history_version_id").String()
+			if revisionID > 0 && revisionID < currentRevision && historyVersionID != "" {
+				revertHistoryVersionID = historyVersionID
+				return true
+			}
+		}
+		return false
+	}, 45*time.Second, 3*time.Second, "history list did not expose a prior revision")
+	require.NotEmpty(t, revertHistoryVersionID)
+
+	revertResult, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args: []string{
+			"docs", "+history-revert",
+			"--doc", docToken,
+			"--history-version-id", revertHistoryVersionID,
+			"--wait-timeout-ms", "30000",
+		},
+		DefaultAs: defaultAs,
+	})
+	require.NoError(t, err)
+	revertResult.AssertExitCode(t, 0)
+	revertResult.AssertStdoutStatus(t, true)
+
+	status := gjson.Get(revertResult.Stdout, "data.status").String()
+	taskID := gjson.Get(revertResult.Stdout, "data.task_id").String()
+	statusStdout := revertResult.Stdout
+	if status == "running" {
+		require.NotEmpty(t, taskID, "stdout:\n%s", revertResult.Stdout)
+		require.Eventually(t, func() bool {
+			statusResult, statusErr := clie2e.RunCmd(ctx, clie2e.Request{
+				Args: []string{
+					"docs", "+history-revert-status",
+					"--doc", docToken,
+					"--task-id", taskID,
+				},
+				DefaultAs: defaultAs,
+			})
+			require.NoError(t, statusErr)
+			statusResult.AssertExitCode(t, 0)
+			statusResult.AssertStdoutStatus(t, true)
+			statusStdout = statusResult.Stdout
+			status = gjson.Get(statusResult.Stdout, "data.status").String()
+			return status != "" && status != "running"
+		}, 60*time.Second, 5*time.Second, "history revert task did not finish")
+	}
+	require.Equal(t, "done", status, "status stdout:\n%s", statusStdout)
+
+	fetchReverted, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args:      []string{"docs", "+fetch", "--doc", docToken, "--doc-format", "markdown"},
+		DefaultAs: defaultAs,
+	})
+	require.NoError(t, err)
+	fetchReverted.AssertExitCode(t, 0)
+	fetchReverted.AssertStdoutStatus(t, true)
+	revertedContent := gjson.Get(fetchReverted.Stdout, "data.document.content").String()
+	assert.Contains(t, revertedContent, originalMarker)
+	assert.NotContains(t, revertedContent, updatedMarker)
+}
--- a/tests/cli_e2e/docs/docs_update_dryrun_test.go
+++ b/tests/cli_e2e/docs/docs_update_dryrun_test.go
@@ -26,7 +26,10 @@ func TestDocs_DryRunDefaultsToV2OpenAPI(t *testing.T) {
 	tests := []struct {
 		name           string
 		args           []string
+		wantContains   []string
 		wantURL        string
+		wantParams     map[string]any
+		wantBody       map[string]any
 		wantExtraParam string
 		wantRefLabel   string
 	}{
@@ -37,7 +40,7 @@ func TestDocs_DryRunDefaultsToV2OpenAPI(t *testing.T) {
 				"--content", "<title>Dry Run</title><p>hello</p>",
 				"--dry-run",
 			},
-			wantURL: "/open-apis/docs_ai/v1/documents",
+			wantContains: []string{"/open-apis/docs_ai/v1/documents"},
 		},
 		{
 			name: "create api-version v1 compatibility",
@@ -47,7 +50,7 @@ func TestDocs_DryRunDefaultsToV2OpenAPI(t *testing.T) {
 				"--content", "<title>Dry Run</title><p>hello</p>",
 				"--dry-run",
 			},
-			wantURL: "/open-apis/docs_ai/v1/documents",
+			wantContains: []string{"/open-apis/docs_ai/v1/documents"},
 		},
 		{
 			name: "fetch",
@@ -56,7 +59,7 @@ func TestDocs_DryRunDefaultsToV2OpenAPI(t *testing.T) {
 				"--doc", "doxcnDryRunE2E",
 				"--dry-run",
 			},
-			wantURL:        "/open-apis/docs_ai/v1/documents/doxcnDryRunE2E/fetch",
+			wantContains:   []string{"/open-apis/docs_ai/v1/documents/doxcnDryRunE2E/fetch"},
 			wantExtraParam: `{"enable_user_cite_reference_map":true,"return_html5_block_data":true}`,
 		},
 		{
@@ -68,7 +71,7 @@ func TestDocs_DryRunDefaultsToV2OpenAPI(t *testing.T) {
 				"--content", "<p>hello</p>",
 				"--dry-run",
 			},
-			wantURL: "/open-apis/docs_ai/v1/documents/doxcnDryRunE2E",
+			wantContains: []string{"/open-apis/docs_ai/v1/documents/doxcnDryRunE2E"},
 		},
 		{
 			name: "update reference-map",
@@ -80,7 +83,7 @@ func TestDocs_DryRunDefaultsToV2OpenAPI(t *testing.T) {
 				"--reference-map", `{"widget":{"r1":{"label":"widget-ref-value"}}}`,
 				"--dry-run",
 			},
-			wantURL:      "/open-apis/docs_ai/v1/documents/doxcnDryRunE2E",
+			wantContains: []string{"/open-apis/docs_ai/v1/documents/doxcnDryRunE2E"},
 			wantRefLabel: "widget-ref-value",
 		},
 		{
@@ -92,7 +95,50 @@ func TestDocs_DryRunDefaultsToV2OpenAPI(t *testing.T) {
 				"--block-id", "blkA,blkB,blkC",
 				"--dry-run",
 			},
-			wantURL: "/open-apis/docs_ai/v1/documents/doxcnDryRunE2E",
+			wantContains: []string{"/open-apis/docs_ai/v1/documents/doxcnDryRunE2E"},
+		},
+		{
+			name: "history list",
+			args: []string{
+				"docs", "+history-list",
+				"--doc", "doxcnDryRunE2E",
+				"--page-size", "5",
+				"--page-token", "page_token_1",
+				"--dry-run",
+			},
+			wantURL: "/open-apis/docs_ai/v1/documents/doxcnDryRunE2E/histories",
+			wantParams: map[string]any{
+				"page_size":  5,
+				"page_token": "page_token_1",
+			},
+		},
+		{
+			name: "history revert",
+			args: []string{
+				"docs", "+history-revert",
+				"--doc", "doxcnDryRunE2E",
+				"--history-version-id", "42",
+				"--wait-timeout-ms", "0",
+				"--dry-run",
+			},
+			wantURL: "/open-apis/docs_ai/v1/documents/doxcnDryRunE2E/history/revert",
+			wantBody: map[string]any{
+				"history_version_id": "42",
+				"wait_timeout_ms":    0,
+			},
+		},
+		{
+			name: "history revert status",
+			args: []string{
+				"docs", "+history-revert-status",
+				"--doc", "doxcnDryRunE2E",
+				"--task-id", "task_1",
+				"--dry-run",
+			},
+			wantURL: "/open-apis/docs_ai/v1/documents/doxcnDryRunE2E/history/revert_status",
+			wantParams: map[string]any{
+				"task_id": "task_1",
+			},
 		},
 	}

@@ -106,10 +152,7 @@ func TestDocs_DryRunDefaultsToV2OpenAPI(t *testing.T) {
 			result.AssertExitCode(t, 0)

 			combined := result.Stdout + "\n" + result.Stderr
-			for _, want := range []string{
-				tt.wantURL,
-				"docs_ai/v1",
-			} {
+			for _, want := range append(tt.wantContains, "docs_ai/v1") {
 				if !strings.Contains(combined, want) {
 					t.Fatalf("dry-run output missing %q\nstdout:\n%s\nstderr:\n%s", want, result.Stdout, result.Stderr)
 				}
@@ -120,6 +163,15 @@ func TestDocs_DryRunDefaultsToV2OpenAPI(t *testing.T) {
 			if strings.Contains(combined, "--api-version") {
 				t.Fatalf("dry-run output should not ask for --api-version\nstdout:\n%s\nstderr:\n%s", result.Stdout, result.Stderr)
 			}
+			if tt.wantURL != "" {
+				require.Equal(t, tt.wantURL, gjson.Get(result.Stdout, "api.0.url").String(), "stdout:\n%s", result.Stdout)
+			}
+			for key, want := range tt.wantParams {
+				assertDryRunField(t, result.Stdout, "api.0.params."+key, want)
+			}
+			for key, want := range tt.wantBody {
+				assertDryRunField(t, result.Stdout, "api.0.body."+key, want)
+			}
 			if tt.wantExtraParam != "" {
 				extraParam := gjson.Get(result.Stdout, "api.0.body.extra_param").String()
 				require.JSONEq(t, tt.wantExtraParam, extraParam, "stdout:\n%s", result.Stdout)
@@ -132,6 +184,21 @@ func TestDocs_DryRunDefaultsToV2OpenAPI(t *testing.T) {
 	}
 }

+func assertDryRunField(t *testing.T, stdout, path string, want any) {
+	t.Helper()
+
+	got := gjson.Get(stdout, path)
+	require.True(t, got.Exists(), "%s missing in stdout:\n%s", path, stdout)
+	switch want := want.(type) {
+	case int:
+		require.Equal(t, int64(want), got.Int(), "%s in stdout:\n%s", path, stdout)
+	case string:
+		require.Equal(t, want, got.String(), "%s in stdout:\n%s", path, stdout)
+	default:
+		t.Fatalf("unsupported dry-run assertion type %T for %s", want, path)
+	}
+}
+
 func TestDocs_CreateTitleDryRunPrependsContent(t *testing.T) {
 	// Fake creds are enough — dry-run short-circuits before any real API call.
 	t.Setenv("LARKSUITE_CLI_APP_ID", "app")
Author	SHA1	Message	Date
guokexin.02	f151ca9ac1	feat: support lark suite hybrid skills layout	2026-07-03 17:43:52 +08:00
caojie0621	a1506cdffb	feat: add docs history shortcuts (#1612 ) Add docs +history-list, +history-revert, and +history-revert-status backed by docs_ai history OpenAPI endpoints. Document the safe history workflow and extend dry-run/live E2E coverage for the new shortcuts.	2026-07-03 16:21:18 +08:00
liuxin-0319	3595356ea1	chore: sync lark-doc skill from online-doc (#1701 )	2026-07-03 15:55:46 +08:00