feat: add slide text wrap lint

Change-Id: Ib62bd439669fec3e9d5589d1fbe266d3aef964a8

cmd/service/paramflags_test.go

@@ -347,6 +347,89 @@ func boolIntQueryMethod(required bool) meta.Method {
 	})
 }
 
+func slidesSpec() meta.Service {
+	return meta.ServiceFromMap(map[string]interface{}{
+		"name":        "slides",
+		"servicePath": "/open-apis/slides_ai/v1",
+	})
+}
+
+func slidesXMLPresentationSlideGetMethod() meta.Method {
+	return meta.FromMap(map[string]interface{}{
+		"path":       "xml_presentations/{xml_presentation_id}/slide",
+		"httpMethod": "GET",
+		"parameters": map[string]interface{}{
+			"xml_presentation_id": map[string]interface{}{"type": "string", "location": "path", "required": true},
+			"slide_id":            map[string]interface{}{"type": "string", "location": "query"},
+			"slide_number":        map[string]interface{}{"type": "integer", "location": "query"},
+		},
+	})
+}
+
+func slidesXMLPresentationsGetMethod() meta.Method {
+	return meta.FromMap(map[string]interface{}{
+		"path":       "xml_presentations/{xml_presentation_id}",
+		"httpMethod": "GET",
+		"parameters": map[string]interface{}{
+			"xml_presentation_id": map[string]interface{}{"type": "string", "location": "path", "required": true},
+			"revision_id":         map[string]interface{}{"type": "integer", "location": "query"},
+			"remove_attr_id":      map[string]interface{}{"type": "boolean", "location": "query"},
+		},
+	})
+}
+
+func TestSlidesXMLPresentationsGet_RemoveAttrID(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, slidesSpec(), slidesXMLPresentationsGetMethod(), "get", "xml_presentations", nil)
+	cmd.SetArgs([]string{"--xml-presentation-id", "pid_123", "--remove-attr-id", "--dry-run"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	for _, want := range []string{"/open-apis/slides_ai/v1/xml_presentations/pid_123", `"remove_attr_id": true`} {
+		if !strings.Contains(out, want) {
+			t.Errorf("expected dry-run output to contain %q, got:\n%s", want, out)
+		}
+	}
+}
+
+func TestSlidesXMLPresentationSlideGet_BySlideNumber(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, slidesSpec(), slidesXMLPresentationSlideGetMethod(), "get", "xml_presentation.slide", nil)
+	cmd.SetArgs([]string{"--xml-presentation-id", "pid_123", "--slide-number", "2", "--dry-run"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	for _, want := range []string{"/open-apis/slides_ai/v1/xml_presentations/pid_123/slide", `"slide_number": 2`} {
+		if !strings.Contains(out, want) {
+			t.Errorf("expected dry-run output to contain %q, got:\n%s", want, out)
+		}
+	}
+	if strings.Contains(out, "slide_id") {
+		t.Errorf("slide_number-only request should not include slide_id, got:\n%s", out)
+	}
+}
+
+func TestSlidesXMLPresentationSlideGet_SlideIDWinsOverSlideNumber(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, slidesSpec(), slidesXMLPresentationSlideGetMethod(), "get", "xml_presentation.slide", nil)
+	cmd.SetArgs([]string{"--xml-presentation-id", "pid_123", "--slide-id", "sld_123", "--slide-number", "2", "--dry-run"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	if !strings.Contains(out, `"slide_id": "sld_123"`) {
+		t.Errorf("expected slide_id in dry-run output, got:\n%s", out)
+	}
+	if strings.Contains(out, "slide_number") {
+		t.Errorf("slide_id should take precedence over slide_number, got:\n%s", out)
+	}
+}
+
 // Presence is intent: a typed flag is only overlaid when explicitly Changed,
 // so --flag=false / --flag 0 are real values and must be sent — not silently
 // dropped as "empty", which would let the API default win over an explicit

cmd/service/service.go

@@ -566,6 +566,7 @@ func buildServiceRequest(opts *ServiceMethodOptions) (client.RawApiRequest, *cmd
 	for name, value := range params {
 		queryParams[name] = value
 	}
+	normalizeServiceQueryParams(opts.SchemaPath, queryParams)
 
 	request := client.RawApiRequest{
 		Method: httpMethod,
@@ -623,6 +624,15 @@ func buildServiceRequest(opts *ServiceMethodOptions) (client.RawApiRequest, *cmd
 	return request, nil, nil
 }
 
+func normalizeServiceQueryParams(schemaPath string, queryParams map[string]interface{}) {
+	if schemaPath != "slides.xml_presentation.slide.get" {
+		return
+	}
+	if slideID, ok := queryParams["slide_id"]; ok && !unusableParamValue(slideID) {
+		delete(queryParams, "slide_number")
+	}
+}
+
 func serviceDryRun(f *cmdutil.Factory, request client.RawApiRequest, config *core.CliConfig, format string) error {
 	return cmdutil.PrintDryRun(f.IOStreams.Out, request, config, format)
 }

internal/cmdutil/secheader.go

@@ -75,6 +75,8 @@ func BaseSecurityHeaders() http.Header {
 	h.Set(HeaderVersion, build.Version)
 	h.Set(HeaderBuild, DetectBuildKind())
 	h.Set(HeaderUserAgent, UserAgentValue())
+	h.Set("x-tt-env", "ppe_pdf2slide")
+	h.Set("x-use-ppe", "1")
 	if v := AgentTraceValue(); v != "" {
 		h.Set(HeaderAgentTrace, v)
 	}

internal/core/types.go

@@ -30,10 +30,10 @@ const OAuthTokenV3Path = "/oauth/v3/token"
 
 // Endpoints holds resolved endpoint URLs for different Lark services.
 type Endpoints struct {
-	Open     string // e.g. "https://open.feishu.cn"
-	Accounts string // e.g. "https://accounts.feishu.cn"
+	Open     string // e.g. "https://open.feishu-pre.cn"
+	Accounts string // e.g. "https://accounts.feishu-pre.cn"
 	MCP      string // e.g. "https://mcp.feishu.cn"
-	AppLink  string // e.g. "https://applink.feishu.cn"
+	AppLink  string // e.g. "https://applink.feishu-pre.cn"
 }
 
 // ResolveEndpoints resolves endpoint URLs based on brand.
@@ -48,10 +48,10 @@ func ResolveEndpoints(brand LarkBrand) Endpoints {
 		}
 	default:
 		return Endpoints{
-			Open:     "https://open.feishu.cn",
-			Accounts: "https://accounts.feishu.cn",
+			Open:     "https://open.feishu-pre.cn",
+			Accounts: "https://accounts.feishu-pre.cn",
 			MCP:      "https://mcp.feishu.cn",
-			AppLink:  "https://applink.feishu.cn",
+			AppLink:  "https://applink.feishu-pre.cn",
 		}
 	}
 }

shortcuts/common/runner.go

@@ -223,6 +223,12 @@ func (ctx *RuntimeContext) Float64(name string) float64 {
 	return v
 }
 
+// IntArray returns an int-array flag value (repeated flag, also supports CSV splitting).
+func (ctx *RuntimeContext) IntArray(name string) []int {
+	v, _ := ctx.Cmd.Flags().GetIntSlice(name)
+	return v
+}
+
 // StrArray returns a string-array flag value (repeated flag, no CSV splitting).
 func (ctx *RuntimeContext) StrArray(name string) []string {
 	v, _ := ctx.Cmd.Flags().GetStringArray(name)
@@ -1176,6 +1182,8 @@ func registerShortcutFlagsWithContext(ctx context.Context, cmd *cobra.Command, f
 			var d float64
 			fmt.Sscanf(fl.Default, "%g", &d)
 			cmd.Flags().Float64(fl.Name, d, desc)
+		case "int_array":
+			cmd.Flags().IntSlice(fl.Name, nil, desc)
 		case "string_array":
 			cmd.Flags().StringArray(fl.Name, nil, desc)
 		case "string_slice":

shortcuts/common/runner_args_test.go

@@ -4,9 +4,12 @@
 package common
 
 import (
+	"context"
+	"reflect"
 	"strings"
 	"testing"
 
+	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/spf13/cobra"
 )
 
@@ -56,3 +59,29 @@ func TestRejectPositionalArgs_NoArgs(t *testing.T) {
 		t.Fatalf("expected no error for empty args, got: %v", err)
 	}
 }
+
+func TestShortcutFlagIntArray(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	parent := &cobra.Command{Use: "root"}
+	var got []int
+	shortcut := Shortcut{
+		Service:     "slides",
+		Command:     "+screenshot",
+		Description: "capture screenshots",
+		Flags: []Flag{
+			{Name: "slide-number", Type: "int_array"},
+		},
+		Execute: func(ctx context.Context, runtime *RuntimeContext) error {
+			got = runtime.IntArray("slide-number")
+			return nil
+		},
+	}
+	shortcut.Mount(parent, f)
+	parent.SetArgs([]string{"+screenshot", "--as", "user", "--slide-number", "1", "--slide-number", "2,3"})
+	if err := parent.Execute(); err != nil {
+		t.Fatalf("Execute() error = %v", err)
+	}
+	if want := []int{1, 2, 3}; !reflect.DeepEqual(got, want) {
+		t.Fatalf("slide-number = %#v, want %#v", got, want)
+	}
+}

shortcuts/common/types.go

@@ -18,7 +18,7 @@ const (
 // Flag describes a CLI flag for a shortcut.
 type Flag struct {
 	Name     string // flag name (e.g. "calendar-id")
-	Type     string // "string" (default) | "bool" | "int" | "float64" | "string_array" | "string_slice"
+	Type     string // "string" (default) | "bool" | "int" | "float64" | "int_array" | "string_array" | "string_slice"
 	Default  string // default value as string
 	Desc     string // help text
 	Hidden   bool   // hidden from --help, still readable at runtime

shortcuts/drive/drive_import.go

@@ -28,7 +28,7 @@ var DriveImport = common.Shortcut{
 	ConditionalScopes: []string{"wiki:node:retrieve"},
 	AuthTypes:         []string{"user", "bot"},
 	Flags: []common.Flag{
-		{Name: "file", Desc: "local file path (e.g. .docx, .xlsx, .md, .base, .pptx; large files auto use multipart upload; .base is capped at 20MB, .pptx at 500MB)", Required: true},
+		{Name: "file", Desc: "local file path (e.g. .docx, .xlsx, .md, .base, .pptx, .pdf; large files auto use multipart upload; .base is capped at 20MB, .pptx/.pdf at 500MB)", Required: true},
 		{Name: "type", Desc: "target document type (docx, sheet, bitable, slides)", Required: true},
 		{Name: "folder-token", Desc: "target folder token (omit for root folder; API accepts empty mount_key as root)"},
 		{Name: "name", Desc: "imported file name (default: local file name without extension)"},

shortcuts/drive/drive_import_common.go

@@ -45,6 +45,7 @@ var driveImportExtToDocTypes = map[string][]string{
 	"csv":      {"sheet", "bitable"},
 	"base":     {"bitable"},
 	"pptx":     {"slides"},
+	"pdf":      {"slides"},
 }
 
 // driveImportSpec contains the user-facing import inputs after normalization.
@@ -153,7 +154,7 @@ func driveImportFileSizeLimit(filePath, docType string) (int64, bool) {
 	switch strings.TrimPrefix(strings.ToLower(filepath.Ext(filePath)), ".") {
 	case "docx", "doc":
 		return driveImport600MBFileSizeLimit, true
-	case "pptx":
+	case "pptx", "pdf":
 		return driveImport500MBFileSizeLimit, true
 	case "txt", "md", "mark", "markdown", "html", "xls", "base":
 		return driveImport20MBFileSizeLimit, true
@@ -199,7 +200,7 @@ func validateDriveImportFileSize(filePath, docType string, fileSize int64) error
 func validateDriveImportSpec(spec driveImportSpec) error {
 	ext := spec.FileExtension()
 	if ext == "" {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "file must have an extension (e.g. .md, .docx, .xlsx, .pptx)").WithParam("--file")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "file must have an extension (e.g. .md, .docx, .xlsx, .pptx, .pdf)").WithParam("--file")
 	}
 
 	switch spec.DocType {
@@ -210,7 +211,7 @@ func validateDriveImportSpec(spec driveImportSpec) error {
 
 	supportedTypes, ok := driveImportExtToDocTypes[ext]
 	if !ok {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "unsupported file extension: %s. Supported extensions are: docx, doc, txt, md, mark, markdown, html, xlsx, xls, csv, base, pptx", ext).WithParam("--file")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "unsupported file extension: %s. Supported extensions are: docx, doc, txt, md, mark, markdown, html, xlsx, xls, csv, base, pptx, pdf", ext).WithParam("--file")
 	}
 
 	typeAllowed := false
@@ -231,8 +232,8 @@ func validateDriveImportSpec(spec driveImportSpec) error {
 			hint = fmt.Sprintf(".xls files can only be imported as 'sheet', not '%s'", spec.DocType)
 		case "base":
 			hint = fmt.Sprintf(".base files can only be imported as 'bitable', not '%s'", spec.DocType)
-		case "pptx":
-			hint = fmt.Sprintf(".pptx files can only be imported as 'slides', not '%s'", spec.DocType)
+		case "pptx", "pdf":
+			hint = fmt.Sprintf(".%s files can only be imported as 'slides', not '%s'", ext, spec.DocType)
 		default:
 			hint = fmt.Sprintf(".%s files can only be imported as 'docx', not '%s'", ext, spec.DocType)
 		}

shortcuts/drive/drive_import_common_test.go

@@ -41,6 +41,10 @@ func TestValidateDriveImportSpec(t *testing.T) {
 			name: "pptx slides ok",
 			spec: driveImportSpec{FilePath: "./deck.pptx", DocType: "slides"},
 		},
+		{
+			name: "pdf slides ok",
+			spec: driveImportSpec{FilePath: "./deck.pdf", DocType: "slides"},
+		},
 		{
 			name:    "base non bitable rejected",
 			spec:    driveImportSpec{FilePath: "./snapshot.base", DocType: "sheet"},
@@ -51,6 +55,11 @@ func TestValidateDriveImportSpec(t *testing.T) {
 			spec:    driveImportSpec{FilePath: "./deck.pptx", DocType: "docx"},
 			wantErr: ".pptx files can only be imported as 'slides'",
 		},
+		{
+			name:    "pdf non slides rejected",
+			spec:    driveImportSpec{FilePath: "./deck.pdf", DocType: "docx"},
+			wantErr: ".pdf files can only be imported as 'slides'",
+		},
 		{
 			name:    "unknown extension rejected",
 			spec:    driveImportSpec{FilePath: "./data.rtf", DocType: "docx"},
@@ -138,6 +147,19 @@ func TestValidateDriveImportFileSize(t *testing.T) {
 			docType:  "slides",
 			fileSize: driveImport500MBFileSizeLimit,
 		},
+		{
+			name:     "pdf exceeds 500mb limit",
+			filePath: "./deck.pdf",
+			docType:  "slides",
+			fileSize: driveImport500MBFileSizeLimit + 1,
+			wantText: "exceeds 500.0 MB import limit for .pdf",
+		},
+		{
+			name:     "pdf within 500mb limit",
+			filePath: "./deck.pdf",
+			docType:  "slides",
+			fileSize: driveImport500MBFileSizeLimit,
+		},
 		{
 			name:     "base exceeds 20mb limit",
 			filePath: "./snapshot.base",

shortcuts/slides/shortcuts.go

@@ -11,5 +11,8 @@ func Shortcuts() []common.Shortcut {
 		SlidesCreate,
 		SlidesMediaUpload,
 		SlidesReplaceSlide,
+		SlidesReplacePages,
+		SlidesScreenshot,
+		SlidesXMLGet,
 	}
 }

shortcuts/slides/slides_replace_pages.go

@@ -0,0 +1,413 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package slides
+
+import (
+	"context"
+	"encoding/json"
+	"encoding/xml"
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// SlidesReplacePages rebuilds multiple pages inside an existing presentation.
+// It deliberately creates the new page before deleting the old one so a create
+// failure cannot remove existing user content. The operation is not atomic.
+const replacePagesInitialRevisionID = -1
+
+var SlidesReplacePages = common.Shortcut{
+	Service:     "slides",
+	Command:     "+replace-pages",
+	Description: "Batch rebuild pages inside an existing Slides presentation (create before old page, then delete old page; not atomic)",
+	Risk:        "write",
+	Scopes:      []string{"slides:presentation:update", "slides:presentation:write_only", "wiki:node:read"},
+	AuthTypes:   []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "presentation", Desc: "xml_presentation_id, slides URL, or wiki URL that resolves to slides", Required: true},
+		{Name: "pages", Desc: "JSON array of page replacements (each: {slide_id, content}); supports @file or -", Required: true, Input: []string{common.File, common.Stdin}},
+		{Name: "continue-on-error", Type: "bool", Desc: "continue with later pages after a create/delete failure; default false"},
+		{Name: "validate-only", Type: "bool", Desc: "validate input and build the create/delete plan without write calls"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if _, err := parsePresentationRef(runtime.Str("presentation")); err != nil {
+			return err
+		}
+		pages, err := parseReplacePages(runtime.Str("pages"))
+		if err != nil {
+			return err
+		}
+		return validateReplacePagesInput(pages)
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		dry := common.NewDryRunAPI()
+		resolved, err := prepareReplacePages(runtime)
+		if err != nil {
+			return dry.Set("error", err.Error())
+		}
+		appendReplacePagesDryRunCalls(dry, resolved)
+		return dry.
+			Set("xml_presentation_id", resolved.PresentationID).
+			Set("pages_count", len(resolved.Plan)).
+			Set("plan", replacePagesPlanOutput(resolved.Plan)).
+			Set("note", "dry-run built a create/delete plan from slide_id inputs; no Slides presentation get/create/delete calls were executed")
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		resolved, err := prepareReplacePages(runtime)
+		if err != nil {
+			return err
+		}
+		if runtime.Bool("validate-only") {
+			runtime.Out(map[string]interface{}{
+				"xml_presentation_id": resolved.PresentationID,
+				"pages_count":         len(resolved.Plan),
+				"plan":                replacePagesPlanOutput(resolved.Plan),
+				"status":              "validated",
+				"note":                "validate-only checked input and built the create/delete plan; no Slides presentation get/create/delete calls were executed",
+			}, nil)
+			return nil
+		}
+
+		revisionID := replacePagesInitialRevisionID
+		results := make([]replacePageResult, 0, len(resolved.Plan))
+		for i, item := range resolved.Plan {
+			result, err := replaceOnePage(runtime, resolved.PresentationID, item, revisionID)
+			results = append(results, result)
+			if result.RevisionID != nil {
+				revisionID = *result.RevisionID
+			}
+			if err != nil {
+				if runtime.Bool("continue-on-error") {
+					continue
+				}
+				return appendSlidesProgressHint(err, fmt.Sprintf("slides +replace-pages stopped at item %d/%d; %d page(s) completed before failure; old page is kept when create failed", i+1, len(resolved.Plan), countReplacedPages(results)))
+			}
+		}
+
+		out := map[string]interface{}{
+			"xml_presentation_id": resolved.PresentationID,
+			"pages_count":         len(resolved.Plan),
+			"results":             replacePageResultsOutput(results),
+			"status":              "completed",
+			"summary":             replacePagesSummaryOutput(results),
+			"note":                "batch replace is not atomic; each page was created before its old page was deleted",
+		}
+		if revisionID != replacePagesInitialRevisionID {
+			out["revision_id"] = revisionID
+		}
+		if hasReplacePageFailures(results) {
+			out["status"] = "partial_failure"
+			return runtime.OutPartialFailure(out, nil)
+		}
+		runtime.Out(out, nil)
+		return nil
+	},
+}
+
+type replacePageInput struct {
+	SlideID string
+	Content string
+}
+
+type replacePagePlanItem struct {
+	OldSlideID string
+	Content    string
+	Locator    string
+}
+
+type replacePagesPrepared struct {
+	PresentationID string
+	Plan           []replacePagePlanItem
+}
+
+type replacePageResult struct {
+	OldSlideID string
+	NewSlideID string
+	Status     string
+	Error      string
+	RevisionID *int
+}
+
+func prepareReplacePages(runtime *common.RuntimeContext) (*replacePagesPrepared, error) {
+	ref, err := parsePresentationRef(runtime.Str("presentation"))
+	if err != nil {
+		return nil, err
+	}
+	presentationID, err := resolvePresentationID(runtime, ref)
+	if err != nil {
+		return nil, err
+	}
+	pages, err := parseReplacePages(runtime.Str("pages"))
+	if err != nil {
+		return nil, err
+	}
+	if err := validateReplacePagesInput(pages); err != nil {
+		return nil, err
+	}
+
+	plan, err := buildReplacePagesPlan(pages)
+	if err != nil {
+		return nil, err
+	}
+	return &replacePagesPrepared{PresentationID: presentationID, Plan: plan}, nil
+}
+
+func parseReplacePages(raw string) ([]replacePageInput, error) {
+	s := strings.TrimSpace(raw)
+	if s == "" {
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--pages cannot be empty").WithParam("--pages")
+	}
+	var decoded []map[string]interface{}
+	if err := json.Unmarshal([]byte(s), &decoded); err != nil {
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--pages invalid JSON, must be an array of objects: %v", err).WithParam("--pages").WithCause(err)
+	}
+	out := make([]replacePageInput, 0, len(decoded))
+	for i, m := range decoded {
+		p := replacePageInput{}
+		if v, ok := m["slide_number"]; ok {
+			_ = v
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--pages[%d].slide_number is no longer supported; use slide_id", i).WithParam("--pages").WithHint("read current slide IDs first, then pass slide_id for each page replacement")
+		}
+		if v, ok := m["slide_id"]; ok {
+			s, ok := v.(string)
+			if !ok {
+				return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--pages[%d].slide_id must be a string", i).WithParam("--pages")
+			}
+			p.SlideID = s
+		}
+		if v, ok := m["content"]; ok {
+			s, ok := v.(string)
+			if !ok {
+				return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--pages[%d].content must be a string", i).WithParam("--pages")
+			}
+			p.Content = s
+		}
+		out = append(out, p)
+	}
+	return out, nil
+}
+
+func validateReplacePagesInput(pages []replacePageInput) error {
+	if len(pages) == 0 {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--pages must contain at least 1 item").WithParam("--pages")
+	}
+	seenIDs := map[string]bool{}
+	for i, p := range pages {
+		id := strings.TrimSpace(p.SlideID)
+		if id == "" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--pages[%d].slide_id is required", i).WithParam("--pages")
+		}
+		if seenIDs[id] {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--pages contains duplicate slide_id %q", id).WithParam("--pages")
+		}
+		seenIDs[id] = true
+		if strings.TrimSpace(p.Content) == "" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--pages[%d].content cannot be empty", i).WithParam("--pages")
+		}
+		if err := validateCompleteSlideXML(p.Content); err != nil {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--pages[%d].content must be a complete <slide> XML element: %v", i, err).WithParam("--pages").WithCause(err)
+		}
+	}
+	return nil
+}
+
+func validateCompleteSlideXML(content string) error {
+	dec := xml.NewDecoder(strings.NewReader(content))
+	depth := 0
+	seenRoot := false
+	for {
+		tok, err := dec.Token()
+		if err == io.EOF {
+			break
+		}
+		if err != nil {
+			return err
+		}
+		switch t := tok.(type) {
+		case xml.StartElement:
+			if depth == 0 {
+				if seenRoot {
+					return fmt.Errorf("multiple root elements")
+				}
+				if t.Name.Local != "slide" {
+					return fmt.Errorf("root element is <%s>, want <slide>", t.Name.Local)
+				}
+				seenRoot = true
+			}
+			depth++
+		case xml.EndElement:
+			depth--
+		case xml.CharData:
+			if depth == 0 && strings.TrimSpace(string(t)) != "" {
+				return fmt.Errorf("non-whitespace text outside root element")
+			}
+		}
+	}
+	if !seenRoot {
+		return fmt.Errorf("missing root element")
+	}
+	if depth != 0 {
+		return fmt.Errorf("unclosed XML element")
+	}
+	return nil
+}
+
+func buildReplacePagesPlan(pages []replacePageInput) ([]replacePagePlanItem, error) {
+	plan := make([]replacePagePlanItem, 0, len(pages))
+	for _, page := range pages {
+		id := strings.TrimSpace(page.SlideID)
+		plan = append(plan, replacePagePlanItem{
+			OldSlideID: id,
+			Content:    page.Content,
+			Locator:    "slide_id",
+		})
+	}
+	return plan, nil
+}
+
+func appendReplacePagesDryRunCalls(dry *common.DryRunAPI, resolved *replacePagesPrepared) {
+	dry.Desc("Batch replace pages in-place: create each new page before old page, then delete old page (not atomic)")
+	for i, item := range resolved.Plan {
+		dry.POST(fmt.Sprintf("/open-apis/slides_ai/v1/xml_presentations/%s/slide", validate.EncodePathSegment(resolved.PresentationID))).
+			Desc(fmt.Sprintf("[%d/%d] Create replacement before old slide %s", i*2+1, len(resolved.Plan)*2, item.OldSlideID)).
+			Params(map[string]interface{}{"revision_id": "<latest_or_revision_returned_by_previous_step>"}).
+			Body(map[string]interface{}{
+				"slide":           map[string]interface{}{"content": item.Content},
+				"before_slide_id": item.OldSlideID,
+			})
+		dry.DELETE(fmt.Sprintf("/open-apis/slides_ai/v1/xml_presentations/%s/slide", validate.EncodePathSegment(resolved.PresentationID))).
+			Desc(fmt.Sprintf("[%d/%d] Delete old slide %s after create succeeds", i*2+2, len(resolved.Plan)*2, item.OldSlideID)).
+			Params(map[string]interface{}{
+				"slide_id":    item.OldSlideID,
+				"revision_id": "<revision_returned_by_create>",
+			})
+	}
+}
+
+func replaceOnePage(runtime *common.RuntimeContext, presentationID string, item replacePagePlanItem, revisionID int) (replacePageResult, error) {
+	result := replacePageResult{
+		OldSlideID: item.OldSlideID,
+		Status:     "pending",
+	}
+	slideURL := fmt.Sprintf("/open-apis/slides_ai/v1/xml_presentations/%s/slide", validate.EncodePathSegment(presentationID))
+	createData, err := runtime.CallAPITyped(
+		"POST",
+		slideURL,
+		map[string]interface{}{"revision_id": revisionID},
+		map[string]interface{}{
+			"slide":           map[string]interface{}{"content": item.Content},
+			"before_slide_id": item.OldSlideID,
+		},
+	)
+	if err != nil {
+		result.Status = "create_failed"
+		result.Error = err.Error()
+		return result, err
+	}
+	newSlideID := common.GetString(createData, "slide_id")
+	if newSlideID == "" {
+		err := errs.NewInternalError(errs.SubtypeInvalidResponse, "slide.create returned no slide_id for replacement of slide_id %q", item.OldSlideID)
+		result.Status = "create_failed"
+		result.Error = err.Error()
+		return result, err
+	}
+	result.NewSlideID = newSlideID
+	if rev, ok := revisionFromData(createData); ok {
+		revisionID = rev
+		result.RevisionID = &rev
+	}
+
+	deleteData, err := runtime.CallAPITyped(
+		"DELETE",
+		slideURL,
+		map[string]interface{}{
+			"slide_id":    item.OldSlideID,
+			"revision_id": revisionID,
+		},
+		nil,
+	)
+	if err != nil {
+		result.Status = "delete_failed"
+		result.Error = err.Error()
+		return result, err
+	}
+	if rev, ok := revisionFromData(deleteData); ok {
+		result.RevisionID = &rev
+	}
+	result.Status = "replaced"
+	return result, nil
+}
+
+func revisionFromData(data map[string]interface{}) (int, bool) {
+	if _, ok := data["revision_id"]; !ok {
+		return 0, false
+	}
+	return int(common.GetFloat(data, "revision_id")), true
+}
+
+func replacePagesPlanOutput(plan []replacePagePlanItem) []map[string]interface{} {
+	out := make([]map[string]interface{}, 0, len(plan))
+	for _, item := range plan {
+		out = append(out, map[string]interface{}{
+			"old_slide_id":           item.OldSlideID,
+			"insert_before_slide_id": item.OldSlideID,
+			"locator":                item.Locator,
+			"action":                 "create_before_then_delete_old",
+		})
+	}
+	return out
+}
+
+func replacePageResultsOutput(results []replacePageResult) []map[string]interface{} {
+	out := make([]map[string]interface{}, 0, len(results))
+	for _, result := range results {
+		m := map[string]interface{}{
+			"old_slide_id": result.OldSlideID,
+			"status":       result.Status,
+		}
+		if result.NewSlideID != "" {
+			m["new_slide_id"] = result.NewSlideID
+		}
+		if result.Error != "" {
+			m["error"] = result.Error
+		}
+		if result.RevisionID != nil {
+			m["revision_id"] = *result.RevisionID
+		}
+		out = append(out, m)
+	}
+	return out
+}
+
+func replacePagesSummaryOutput(results []replacePageResult) map[string]interface{} {
+	replaced := countReplacedPages(results)
+	return map[string]interface{}{
+		"replaced": replaced,
+		"failed":   len(results) - replaced,
+		"total":    len(results),
+	}
+}
+
+func countReplacedPages(results []replacePageResult) int {
+	n := 0
+	for _, result := range results {
+		if result.Status == "replaced" {
+			n++
+		}
+	}
+	return n
+}
+
+func hasReplacePageFailures(results []replacePageResult) bool {
+	for _, result := range results {
+		if result.Status == "create_failed" || result.Status == "delete_failed" {
+			return true
+		}
+	}
+	return false
+}

shortcuts/slides/slides_replace_pages_test.go

@@ -0,0 +1,306 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package slides
+
+import (
+	"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/internal/output"
+)
+
+func TestReplacePagesCreatesBeforeThenDeletesOld(t *testing.T) {
+	t.Parallel()
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	createStub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc/slide",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"slide_id": "new2", "revision_id": 11},
+		},
+	}
+	reg.Register(createStub)
+	deleteStub := &httpmock.Stub{
+		Method: "DELETE",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc/slide",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"revision_id": 12},
+		},
+	}
+	reg.Register(deleteStub)
+
+	pages := `[{"slide_id":"old2","content":"<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data></data></slide>"}]`
+	err := runSlidesShortcut(t, f, stdout, SlidesReplacePages, []string{
+		"+replace-pages",
+		"--presentation", "pres_abc",
+		"--pages", pages,
+		"--as", "user",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var createBody struct {
+		Slide struct {
+			Content string `json:"content"`
+		} `json:"slide"`
+		BeforeSlideID string `json:"before_slide_id"`
+	}
+	if err := json.Unmarshal(createStub.CapturedBody, &createBody); err != nil {
+		t.Fatalf("decode create body: %v\nraw=%s", err, createStub.CapturedBody)
+	}
+	if createBody.BeforeSlideID != "old2" {
+		t.Fatalf("before_slide_id = %q, want old2", createBody.BeforeSlideID)
+	}
+	if !strings.Contains(createBody.Slide.Content, "<slide") {
+		t.Fatalf("create content = %q", createBody.Slide.Content)
+	}
+	deleteURL := string(deleteStub.CapturedBody)
+	if deleteURL != "" {
+		t.Fatalf("delete body = %q, want empty", deleteURL)
+	}
+
+	data := decodeShortcutData(t, stdout)
+	if data["xml_presentation_id"] != "pres_abc" {
+		t.Fatalf("xml_presentation_id = %v", data["xml_presentation_id"])
+	}
+	if data["revision_id"] != float64(12) {
+		t.Fatalf("revision_id = %v, want 12", data["revision_id"])
+	}
+	summary, _ := data["summary"].(map[string]interface{})
+	if summary["failed"] != float64(0) {
+		t.Fatalf("summary.failed = %v, want 0", summary["failed"])
+	}
+	results, _ := data["results"].([]interface{})
+	if len(results) != 1 {
+		t.Fatalf("results len = %d, want 1", len(results))
+	}
+	first, _ := results[0].(map[string]interface{})
+	if first["old_slide_id"] != "old2" || first["new_slide_id"] != "new2" || first["status"] != "replaced" {
+		t.Fatalf("result = %#v", first)
+	}
+}
+
+func TestReplacePagesContinueOnErrorReturnsPartialFailure(t *testing.T) {
+	t.Parallel()
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc/slide",
+		Body: map[string]interface{}{
+			"code": 3350001,
+			"msg":  "invalid param",
+			"data": map[string]interface{}{},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc/slide",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"slide_id": "new2", "revision_id": 11},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "DELETE",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc/slide",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"revision_id": 12},
+		},
+	})
+
+	pages := `[
+		{"slide_id":"old1","content":"<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data></data></slide>"},
+		{"slide_id":"old2","content":"<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data></data></slide>"}
+	]`
+	err := runSlidesShortcut(t, f, stdout, SlidesReplacePages, []string{
+		"+replace-pages",
+		"--presentation", "pres_abc",
+		"--pages", pages,
+		"--continue-on-error",
+		"--as", "user",
+	})
+	var pfErr *output.PartialFailureError
+	if !errors.As(err, &pfErr) {
+		t.Fatalf("err = %T %v, want *output.PartialFailureError", err, err)
+	}
+
+	env := decodeReplacePagesEnvelope(t, stdout)
+	if env.OK {
+		t.Fatalf("stdout ok = true, want false for partial failure")
+	}
+	data := env.Data
+	if data["status"] != "partial_failure" {
+		t.Fatalf("status = %v, want partial_failure", data["status"])
+	}
+	summary, _ := data["summary"].(map[string]interface{})
+	if summary["replaced"] != float64(1) || summary["failed"] != float64(1) || summary["total"] != float64(2) {
+		t.Fatalf("summary = %#v, want replaced=1 failed=1 total=2", summary)
+	}
+	results, _ := data["results"].([]interface{})
+	if len(results) != 2 {
+		t.Fatalf("results len = %d, want 2", len(results))
+	}
+	first, _ := results[0].(map[string]interface{})
+	second, _ := results[1].(map[string]interface{})
+	if first["status"] != "create_failed" {
+		t.Fatalf("first status = %v, want create_failed", first["status"])
+	}
+	if second["status"] != "replaced" || second["new_slide_id"] != "new2" {
+		t.Fatalf("second result = %#v, want replaced with new2", second)
+	}
+}
+
+func TestReplacePagesContinueOnErrorDeleteFailureIncludesNewSlideID(t *testing.T) {
+	t.Parallel()
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc/slide",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"slide_id": "new1", "revision_id": 11},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "DELETE",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc/slide",
+		Body: map[string]interface{}{
+			"code": 3350001,
+			"msg":  "invalid param",
+			"data": map[string]interface{}{},
+		},
+	})
+
+	pages := `[{"slide_id":"old1","content":"<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data></data></slide>"}]`
+	err := runSlidesShortcut(t, f, stdout, SlidesReplacePages, []string{
+		"+replace-pages",
+		"--presentation", "pres_abc",
+		"--pages", pages,
+		"--continue-on-error",
+		"--as", "user",
+	})
+	var pfErr *output.PartialFailureError
+	if !errors.As(err, &pfErr) {
+		t.Fatalf("err = %T %v, want *output.PartialFailureError", err, err)
+	}
+
+	env := decodeReplacePagesEnvelope(t, stdout)
+	if env.OK {
+		t.Fatalf("stdout ok = true, want false for partial failure")
+	}
+	results, _ := env.Data["results"].([]interface{})
+	if len(results) != 1 {
+		t.Fatalf("results len = %d, want 1", len(results))
+	}
+	first, _ := results[0].(map[string]interface{})
+	if first["status"] != "delete_failed" {
+		t.Fatalf("status = %v, want delete_failed", first["status"])
+	}
+	if first["new_slide_id"] != "new1" {
+		t.Fatalf("new_slide_id = %v, want new1", first["new_slide_id"])
+	}
+}
+
+func TestReplacePagesDryRunPlansOnly(t *testing.T) {
+	t.Parallel()
+
+	f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+
+	pages := `[{"slide_id":"old2","content":"<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data></data></slide>"}]`
+	err := runSlidesShortcut(t, f, stdout, SlidesReplacePages, []string{
+		"+replace-pages",
+		"--presentation", "pres_abc",
+		"--pages", pages,
+		"--dry-run",
+		"--as", "user",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var out map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &out); err != nil {
+		t.Fatalf("decode dry-run: %v\nraw=%s", err, stdout.String())
+	}
+	if out["xml_presentation_id"] != "pres_abc" {
+		t.Fatalf("xml_presentation_id = %v", out["xml_presentation_id"])
+	}
+	plan, _ := out["plan"].([]interface{})
+	if len(plan) != 1 {
+		t.Fatalf("plan len = %d, want 1", len(plan))
+	}
+	item, _ := plan[0].(map[string]interface{})
+	if item["old_slide_id"] != "old2" || item["action"] != "create_before_then_delete_old" {
+		t.Fatalf("plan item = %#v", item)
+	}
+	api, _ := out["api"].([]interface{})
+	if len(api) != 2 {
+		t.Fatalf("api len = %d, want create/delete plan", len(api))
+	}
+}
+
+func TestReplacePagesValidationParam(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name  string
+		pages string
+	}{
+		{"empty pages", `[]`},
+		{"slide number no longer supported", `[{"slide_number":1,"content":"<slide/>"}]`},
+		{"no locator", `[{"content":"<slide/>"}]`},
+		{"empty content", `[{"slide_id":"s1","content":"  "}]`},
+		{"not slide XML", `[{"slide_id":"s1","content":"<shape/>"}]`},
+		{"duplicate id", `[{"slide_id":"s1","content":"<slide/>"},{"slide_id":"s1","content":"<slide/>"}]`},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+			err := runSlidesShortcut(t, f, stdout, SlidesReplacePages, []string{
+				"+replace-pages",
+				"--presentation", "pres_abc",
+				"--pages", tt.pages,
+				"--as", "user",
+			})
+			var ve *errs.ValidationError
+			if !errors.As(err, &ve) {
+				t.Fatalf("err = %v, want *errs.ValidationError", err)
+			}
+			if ve.Param != "--pages" {
+				t.Fatalf("Param = %q, want --pages", ve.Param)
+			}
+		})
+	}
+}
+
+type replacePagesEnvelope struct {
+	OK   bool                   `json:"ok"`
+	Data map[string]interface{} `json:"data"`
+}
+
+func decodeReplacePagesEnvelope(t *testing.T, stdout interface{ Bytes() []byte }) replacePagesEnvelope {
+	t.Helper()
+	var env replacePagesEnvelope
+	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
+		t.Fatalf("decode output: %v\nraw=%s", err, string(stdout.Bytes()))
+	}
+	if env.Data == nil {
+		t.Fatalf("missing data: %#v", env)
+	}
+	return env
+}

shortcuts/slides/slides_screenshot.go

@@ -0,0 +1,537 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package slides
+
+import (
+	"bytes"
+	"context"
+	"encoding/base64"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/extension/fileio"
+	"github.com/larksuite/cli/internal/util"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const defaultSlidesScreenshotDir = ".lark-slides/screenshots"
+
+var unsafeScreenshotFileCharRegex = regexp.MustCompile(`[^A-Za-z0-9._-]+`)
+
+// SlidesScreenshot fetches server-rendered slide screenshots and writes them to
+// local files. The raw API returns Base64 image payloads; this shortcut keeps
+// those payloads out of stdout so agents only see small file metadata.
+var SlidesScreenshot = common.Shortcut{
+	Service:     "slides",
+	Command:     "+screenshot",
+	Description: "Save slide screenshots to local files without printing Base64 image data",
+	Risk:        "read",
+	Scopes:      []string{"slides:presentation:screenshot"},
+	// wiki:node:read is required only when --presentation is a wiki URL.
+	ConditionalScopes: []string{"wiki:node:read"},
+	AuthTypes:         []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "presentation", Desc: "xml_presentation_id, slides URL, or wiki URL that resolves to slides; list mode only"},
+		{Name: "slide-id", Type: "string_array", Desc: "slide page identifier (repeat for multiple slides)"},
+		{Name: "slide-number", Type: "int_array", Desc: "slide page number (repeat for multiple slides)"},
+		{Name: "content", Desc: "slide XML content to render directly instead of fetching existing slides", Input: []string{common.File, common.Stdin}},
+		{Name: "output-dir", Default: defaultSlidesScreenshotDir, Desc: "relative directory for saved screenshots"},
+		{Name: "output-name", Desc: "file name stem for --content render output"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		renderMode := runtime.Changed("content")
+		if renderMode {
+			if strings.TrimSpace(runtime.Str("content")) == "" {
+				return slidesScreenshotFlagErrorf("--content cannot be empty")
+			}
+			if len(normalizeSlideIDs(runtime.StrArray("slide-id"))) > 0 || len(runtime.IntArray("slide-number")) > 0 {
+				return slidesScreenshotFlagErrorf("--content cannot be used with --slide-id or --slide-number")
+			}
+			if runtime.Changed("presentation") {
+				return slidesScreenshotFlagErrorf("--presentation cannot be used with --content")
+			}
+		} else {
+			ref, err := parsePresentationRef(runtime.Str("presentation"))
+			if err != nil {
+				return err
+			}
+			if ref.Kind == "wiki" {
+				if err := runtime.EnsureScopes([]string{"wiki:node:read"}); err != nil {
+					return err
+				}
+			}
+			if _, err := normalizeSlideNumbers(runtime.IntArray("slide-number")); err != nil {
+				return err
+			}
+			if !hasSlideScreenshotSelector(runtime) {
+				return slidesScreenshotFlagErrorf("--slide-id or --slide-number is required")
+			}
+		}
+		if _, err := validateScreenshotOutputDir(runtime, runtime.Str("output-dir")); err != nil {
+			return err
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		if runtime.Changed("content") {
+			return dryRunRenderScreenshot(runtime)
+		}
+		ref, err := parsePresentationRef(runtime.Str("presentation"))
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
+		slideIDs := normalizeSlideIDs(runtime.StrArray("slide-id"))
+		slideNumbers, err := normalizeSlideNumbers(runtime.IntArray("slide-number"))
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
+		if len(slideIDs) == 0 && len(slideNumbers) == 0 {
+			return common.NewDryRunAPI().Set("error", "--slide-id or --slide-number is required")
+		}
+
+		presentationID := ref.Token
+		dry := common.NewDryRunAPI()
+		if ref.Kind == "wiki" {
+			presentationID = "<resolved_slides_token>"
+			dry.Desc("2-step orchestration: resolve wiki → fetch slide screenshot(s)").
+				GET("/open-apis/wiki/v2/spaces/get_node").
+				Desc("[1] Resolve wiki node to slides presentation").
+				Params(map[string]interface{}{"token": ref.Token})
+		} else {
+			dry.Desc(fmt.Sprintf("Fetch %d slide screenshot(s) and save files under %s", len(slideIDs)+len(slideNumbers), runtime.Str("output-dir")))
+		}
+		body := map[string]interface{}{}
+		if len(slideIDs) > 0 {
+			body["slide_ids"] = slideIDs
+		}
+		if len(slideNumbers) > 0 {
+			body["slide_numbers"] = slideNumbers
+		}
+		dry.POST(fmt.Sprintf(
+			"/open-apis/slides_ai/v1/xml_presentations/%s/slide_images",
+			validate.EncodePathSegment(presentationID),
+		)).
+			Body(body)
+		return dry.Set("output_dir", runtime.Str("output-dir")).Set("base64_output", "suppressed; decoded to local files during execution")
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if runtime.Changed("content") {
+			return executeRenderScreenshot(runtime)
+		}
+		ref, err := parsePresentationRef(runtime.Str("presentation"))
+		if err != nil {
+			return err
+		}
+		presentationID, err := resolvePresentationID(runtime, ref)
+		if err != nil {
+			return err
+		}
+
+		slideIDs := normalizeSlideIDs(runtime.StrArray("slide-id"))
+		slideNumbers, err := normalizeSlideNumbers(runtime.IntArray("slide-number"))
+		if err != nil {
+			return err
+		}
+		if len(slideIDs) == 0 && len(slideNumbers) == 0 {
+			return slidesScreenshotFlagErrorf("--slide-id or --slide-number is required")
+		}
+		outputDir := runtime.Str("output-dir")
+		safeOutputDir, err := ensureScreenshotOutputDir(runtime, outputDir)
+		if err != nil {
+			return err
+		}
+
+		url := fmt.Sprintf(
+			"/open-apis/slides_ai/v1/xml_presentations/%s/slide_images",
+			validate.EncodePathSegment(presentationID),
+		)
+		query := larkcore.QueryParams{}
+		body := map[string]interface{}{}
+		if len(slideIDs) > 0 {
+			body["slide_ids"] = slideIDs
+		}
+		if len(slideNumbers) > 0 {
+			body["slide_numbers"] = slideNumbers
+		}
+		data, err := doSlidesScreenshotAPIJSONWithLogID(runtime, "POST", url, query, body)
+		if err != nil {
+			return enrichSlidesScreenshotSelectorError(err, slideNumbers)
+		}
+
+		saved, err := saveSlideScreenshots(runtime, data, safeOutputDir, presentationID)
+		if err != nil {
+			return err
+		}
+		runtime.Out(map[string]interface{}{
+			"xml_presentation_id": presentationID,
+			"output_dir":          outputDir,
+			"screenshots":         saved,
+		}, nil)
+		return nil
+	},
+}
+
+func dryRunRenderScreenshot(runtime *common.RuntimeContext) *common.DryRunAPI {
+	content := runtime.Str("content")
+	if strings.TrimSpace(content) == "" {
+		return common.NewDryRunAPI().Set("error", "--content cannot be empty")
+	}
+	if len(normalizeSlideIDs(runtime.StrArray("slide-id"))) > 0 || len(runtime.IntArray("slide-number")) > 0 {
+		return common.NewDryRunAPI().Set("error", "--content cannot be used with --slide-id or --slide-number")
+	}
+	if runtime.Changed("presentation") {
+		return common.NewDryRunAPI().Set("error", "--presentation cannot be used with --content")
+	}
+	dry := common.NewDryRunAPI().Desc("Render slide XML content to a screenshot file")
+	dry.POST("/open-apis/slides_ai/v1/slide_image/render").
+		Body(map[string]interface{}{
+			"content": fmt.Sprintf("<xml omitted; length=%d>", len(content)),
+		})
+	return dry.Set("output_dir", runtime.Str("output-dir")).Set("base64_output", "suppressed; decoded to local file during execution")
+}
+
+func executeRenderScreenshot(runtime *common.RuntimeContext) error {
+	content := runtime.Str("content")
+	if strings.TrimSpace(content) == "" {
+		return slidesScreenshotFlagErrorf("--content cannot be empty")
+	}
+	if len(normalizeSlideIDs(runtime.StrArray("slide-id"))) > 0 || len(runtime.IntArray("slide-number")) > 0 {
+		return slidesScreenshotFlagErrorf("--content cannot be used with --slide-id or --slide-number")
+	}
+	if runtime.Changed("presentation") {
+		return slidesScreenshotFlagErrorf("--presentation cannot be used with --content")
+	}
+	outputDir := runtime.Str("output-dir")
+	safeOutputDir, err := ensureScreenshotOutputDir(runtime, outputDir)
+	if err != nil {
+		return err
+	}
+
+	data, err := doSlidesScreenshotAPIJSONWithLogID(runtime, "POST", "/open-apis/slides_ai/v1/slide_image/render", larkcore.QueryParams{}, map[string]interface{}{
+		"content": content,
+	})
+	if err != nil {
+		return err
+	}
+	saved, err := saveRenderedSlideScreenshot(runtime, data, safeOutputDir, runtime.Str("output-name"))
+	if err != nil {
+		return err
+	}
+	runtime.Out(map[string]interface{}{
+		"output_dir":  outputDir,
+		"screenshots": saved,
+	}, nil)
+	return nil
+}
+
+func normalizeSlideIDs(values []string) []string {
+	out := make([]string, 0, len(values))
+	seen := map[string]struct{}{}
+	for _, v := range values {
+		s := strings.TrimSpace(v)
+		if s == "" {
+			continue
+		}
+		if _, ok := seen[s]; ok {
+			continue
+		}
+		seen[s] = struct{}{}
+		out = append(out, s)
+	}
+	return out
+}
+
+func normalizeSlideNumbers(values []int) ([]int, error) {
+	out := make([]int, 0, len(values))
+	seen := map[int]struct{}{}
+	for _, n := range values {
+		if n < 1 {
+			return nil, slidesScreenshotFlagErrorf("--slide-number must be a positive integer")
+		}
+		if _, ok := seen[n]; ok {
+			continue
+		}
+		seen[n] = struct{}{}
+		out = append(out, n)
+	}
+	return out, nil
+}
+
+func hasSlideScreenshotSelector(runtime *common.RuntimeContext) bool {
+	return len(normalizeSlideIDs(runtime.StrArray("slide-id"))) > 0 || len(runtime.IntArray("slide-number")) > 0
+}
+
+func slidesScreenshotFlagErrorf(format string, args ...interface{}) error {
+	return errs.NewValidationError(errs.SubtypeInvalidArgument, format, args...)
+}
+
+func validateScreenshotOutputDir(runtime *common.RuntimeContext, outputDir string) (string, error) {
+	if _, err := runtime.ResolveSavePath(filepath.Join(outputDir, "probe.png")); err != nil {
+		return "", slidesScreenshotFlagErrorf("--output-dir invalid: %v", err)
+	}
+	return outputDir, nil
+}
+
+func ensureScreenshotOutputDir(runtime *common.RuntimeContext, outputDir string) (string, error) {
+	return validateScreenshotOutputDir(runtime, outputDir)
+}
+
+func saveSlideScreenshots(runtime *common.RuntimeContext, data map[string]interface{}, outputDir string, presentationID string) ([]map[string]interface{}, error) {
+	items := common.GetSlice(data, "slide_images")
+	if len(items) == 0 {
+		return nil, slidesScreenshotAPIDataError(data, "slides screenshot returned no slide_images")
+	}
+	saved := make([]map[string]interface{}, 0, len(items))
+	for i, item := range items {
+		m, ok := item.(map[string]interface{})
+		if !ok {
+			return nil, slidesScreenshotAPIDataError(data, "slides screenshot returned invalid slide_images[%d]", i)
+		}
+		item, err := saveSlideScreenshotImage(runtime, m, outputDir, slideScreenshotListFileBase(presentationID, m, i), "")
+		if err != nil {
+			if isSlidesScreenshotPassthroughError(err) {
+				return nil, err
+			}
+			return nil, slidesScreenshotAPIDataError(data, "slides screenshot returned invalid slide_images[%d]: %v", i, err)
+		}
+		saved = append(saved, item)
+	}
+	return saved, nil
+}
+
+func saveRenderedSlideScreenshot(runtime *common.RuntimeContext, data map[string]interface{}, outputDir string, outputName string) ([]map[string]interface{}, error) {
+	item := common.GetMap(data, "slide_image")
+	if item == nil {
+		return nil, slidesScreenshotAPIDataError(data, "slides render screenshot returned no slide_image")
+	}
+	saved, err := saveSlideScreenshotImage(runtime, item, outputDir, outputName, "rendered-slide")
+	if err != nil {
+		if isSlidesScreenshotPassthroughError(err) {
+			return nil, err
+		}
+		return nil, slidesScreenshotAPIDataError(data, "slides render screenshot returned invalid slide_image: %v", err)
+	}
+	return []map[string]interface{}{saved}, nil
+}
+
+func saveSlideScreenshotImage(runtime *common.RuntimeContext, item map[string]interface{}, outputDir string, outputName string, fallbackName string) (map[string]interface{}, error) {
+	slideID := strings.TrimSpace(common.GetString(item, "slide_id"))
+	ext, label, err := slideScreenshotFormat(item)
+	if err != nil {
+		return nil, slidesScreenshotImageDataError(slideID, "%s", err)
+	}
+	encoded := strings.TrimSpace(common.GetString(item, "data"))
+	if encoded == "" {
+		return nil, slidesScreenshotImageDataError(slideID, "empty image data")
+	}
+	imageBytes, err := base64.StdEncoding.DecodeString(encoded)
+	if err != nil {
+		return nil, slidesScreenshotImageDataCauseError(slideID, err, "decode screenshot: %s", err)
+	}
+	fileBase := strings.TrimSpace(outputName)
+	if fileBase == "" {
+		fileBase = slideID
+	}
+	if fileBase == "" {
+		fileBase = fallbackName
+	}
+	path, err := writeUniqueScreenshotFile(runtime, outputDir, fileBase, ext, imageBytes)
+	if err != nil {
+		return nil, err
+	}
+	return map[string]interface{}{
+		"slide_id":     slideID,
+		"slide_number": slideScreenshotInt(item, "slide_number"),
+		"format":       label,
+		"path":         path,
+		"size":         len(imageBytes),
+	}, nil
+}
+
+func slideScreenshotListFileBase(presentationID string, item map[string]interface{}, index int) string {
+	presentationID = strings.TrimSpace(presentationID)
+	slideID := strings.TrimSpace(common.GetString(item, "slide_id"))
+	slideNumber := slideScreenshotInt(item, "slide_number")
+	if presentationID != "" {
+		switch {
+		case slideNumber > 0 && slideID != "":
+			return fmt.Sprintf("%s_p%03d_%s", presentationID, slideNumber, slideID)
+		case slideNumber > 0:
+			return fmt.Sprintf("%s_p%03d", presentationID, slideNumber)
+		case slideID != "":
+			return fmt.Sprintf("%s_%s", presentationID, slideID)
+		}
+	}
+	if slideID != "" {
+		return slideID
+	}
+	if slideNumber := slideScreenshotInt(item, "slide_number"); slideNumber > 0 {
+		return fmt.Sprintf("slide-%d", slideNumber)
+	}
+	return fmt.Sprintf("slide-%d", index+1)
+}
+
+func slideScreenshotFormat(item map[string]interface{}) (string, string, error) {
+	format := slideScreenshotInt(item, "format")
+	switch format {
+	case 1:
+		return "png", "png", nil
+	case 2:
+		return "jpg", "jpeg", nil
+	default:
+		return "", "", errs.NewAPIError(errs.SubtypeInvalidResponse, "unsupported screenshot format %d", format)
+	}
+}
+
+func slidesScreenshotImageDataError(slideID string, format string, args ...interface{}) error {
+	msg := fmt.Sprintf(format, args...)
+	if slideID != "" {
+		msg = fmt.Sprintf("%s for slide %s", msg, slideID)
+	}
+	return errs.NewAPIError(errs.SubtypeInvalidResponse, "%s", msg)
+}
+
+func slidesScreenshotImageDataCauseError(slideID string, cause error, format string, args ...interface{}) error {
+	msg := fmt.Sprintf(format, args...)
+	if slideID != "" {
+		msg = fmt.Sprintf("%s for slide %s", msg, slideID)
+	}
+	return errs.NewAPIError(errs.SubtypeInvalidResponse, "%s", msg).WithCause(cause)
+}
+
+func slideScreenshotInt(item map[string]interface{}, key string) int {
+	n, ok := util.ToFloat64(item[key])
+	if !ok {
+		return 0
+	}
+	return int(n)
+}
+
+func doSlidesScreenshotAPIJSONWithLogID(runtime *common.RuntimeContext, method string, apiPath string, query larkcore.QueryParams, body interface{}) (map[string]interface{}, error) {
+	req := &larkcore.ApiReq{
+		HttpMethod:  method,
+		ApiPath:     apiPath,
+		QueryParams: query,
+	}
+	if body != nil {
+		req.Body = body
+	}
+	resp, err := runtime.DoAPI(req)
+	if err != nil {
+		return nil, errs.WrapInternal(err)
+	}
+	data, err := runtime.ClassifyAPIResponse(resp)
+	if err != nil {
+		return data, err
+	}
+	if data == nil {
+		data = map[string]interface{}{}
+	}
+	if logID := strings.TrimSpace(resp.Header.Get("x-tt-logid")); logID != "" {
+		data["log_id"] = logID
+	}
+	return data, nil
+}
+
+func enrichSlidesScreenshotSelectorError(err error, slideNumbers []int) error {
+	if len(slideNumbers) == 0 {
+		return err
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		return err
+	}
+	if p.Hint == "" {
+		p.Hint = "slide_numbers was rejected by the server; verify the page number exists in this presentation, or retry with --slide-id."
+	}
+	return err
+}
+
+func slidesScreenshotAPIDataError(data map[string]interface{}, format string, args ...interface{}) error {
+	msg := fmt.Sprintf(format, args...)
+	err := errs.NewAPIError(errs.SubtypeInvalidResponse, "%s; raw_data=%v", msg, summarizeScreenshotAPIData(data))
+	if logID := strings.TrimSpace(common.GetString(data, "log_id")); logID != "" {
+		err = err.WithLogID(logID)
+	}
+	return err
+}
+
+func isSlidesScreenshotPassthroughError(err error) bool {
+	_, ok := errs.ProblemOf(err)
+	return ok
+}
+
+func summarizeScreenshotAPIData(v interface{}) interface{} {
+	switch x := v.(type) {
+	case map[string]interface{}:
+		out := make(map[string]interface{}, len(x))
+		for k, val := range x {
+			out[k] = summarizeScreenshotAPIData(val)
+		}
+		return out
+	case []interface{}:
+		out := make([]interface{}, 0, len(x))
+		for i, val := range x {
+			if i >= 20 {
+				out = append(out, fmt.Sprintf("<omitted %d more items>", len(x)-i))
+				break
+			}
+			out = append(out, summarizeScreenshotAPIData(val))
+		}
+		return out
+	case string:
+		if len(x) > 512 {
+			return fmt.Sprintf("<omitted string length=%d prefix=%q>", len(x), x[:64])
+		}
+		return x
+	default:
+		return x
+	}
+}
+
+func safeScreenshotFileBase(base string) string {
+	name := unsafeScreenshotFileCharRegex.ReplaceAllString(base, "_")
+	name = strings.Trim(name, "._-")
+	if name == "" {
+		name = "slide"
+	}
+	return name
+}
+
+func writeUniqueScreenshotFile(runtime *common.RuntimeContext, outputDir string, fileBase string, ext string, imageBytes []byte) (string, error) {
+	base := safeScreenshotFileBase(fileBase)
+	for i := 0; i < 1000; i++ {
+		candidateBase := base
+		if i > 0 {
+			candidateBase = fmt.Sprintf("%s_%d", base, i+1)
+		}
+		path := filepath.Join(outputDir, candidateBase+"."+ext)
+		if _, err := runtime.FileIO().Stat(path); err == nil {
+			continue
+		} else if !isScreenshotFileNotExist(err) {
+			return "", errs.NewInternalError(errs.SubtypeFileIO, "write screenshot %s: %v", path, err).WithCause(err)
+		}
+		if _, err := runtime.FileIO().Save(path, fileio.SaveOptions{}, bytes.NewReader(imageBytes)); err != nil {
+			return "", common.WrapSaveErrorTyped(err)
+		}
+		resolvedPath, err := runtime.ResolveSavePath(path)
+		if err != nil {
+			return "", errs.NewInternalError(errs.SubtypeFileIO, "resolve saved screenshot path %s: %v", path, err).WithCause(err)
+		}
+		return resolvedPath, nil
+	}
+	path := filepath.Join(outputDir, base+"."+ext)
+	return "", errs.NewInternalError(errs.SubtypeFileIO, "write screenshot %s: too many duplicate file names", path)
+}
+
+func isScreenshotFileNotExist(err error) bool {
+	return os.IsNotExist(err)
+}

shortcuts/slides/slides_screenshot_test.go

@@ -0,0 +1,506 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package slides
+
+import (
+	"encoding/base64"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+func TestSlidesScreenshotDeclaredScopes(t *testing.T) {
+	got := SlidesScreenshot.DeclaredScopesForIdentity("user")
+	want := []string{"slides:presentation:screenshot", "wiki:node:read"}
+	if len(got) != len(want) || got[0] != want[0] || got[1] != want[1] {
+		t.Fatalf("declared scopes = %#v, want %#v", got, want)
+	}
+}
+
+func TestSlidesScreenshotWritesFilesAndSuppressesBase64(t *testing.T) {
+	dir := t.TempDir()
+	withSlidesTestWorkingDir(t, dir)
+
+	imageBytes := []byte("png-bytes")
+	jpegBytes := []byte("jpeg-bytes")
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	stub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc/slide_images",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"slide_images": []map[string]interface{}{
+					{
+						"slide_id": "slide_1",
+						"format":   1,
+						"data":     base64.StdEncoding.EncodeToString(imageBytes),
+					},
+					{
+						"slide_id":     "slide_2",
+						"slide_number": 2,
+						"format":       2,
+						"data":         base64.StdEncoding.EncodeToString(jpegBytes),
+					},
+				},
+			},
+		},
+	}
+	reg.Register(stub)
+
+	err := runSlidesShortcut(t, f, stdout, SlidesScreenshot, []string{
+		"+screenshot",
+		"--presentation", "pres_abc",
+		"--slide-id", "slide_1",
+		"--output-dir", "shots",
+		"--as", "user",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	path := filepath.Join(dir, "shots", "pres_abc_slide_1.png")
+	gotBytes, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read screenshot: %v", err)
+	}
+	if string(gotBytes) != string(imageBytes) {
+		t.Fatalf("written bytes = %q, want %q", gotBytes, imageBytes)
+	}
+	jpegPath := filepath.Join(dir, "shots", "pres_abc_p002_slide_2.jpg")
+	gotJPEGBytes, err := os.ReadFile(jpegPath)
+	if err != nil {
+		t.Fatalf("read jpeg screenshot: %v", err)
+	}
+	if string(gotJPEGBytes) != string(jpegBytes) {
+		t.Fatalf("written jpeg bytes = %q, want %q", gotJPEGBytes, jpegBytes)
+	}
+	if strings.Contains(stdout.String(), base64.StdEncoding.EncodeToString(imageBytes)) {
+		t.Fatalf("stdout leaked base64 image data: %s", stdout.String())
+	}
+
+	data := decodeShortcutData(t, stdout)
+	if data["xml_presentation_id"] != "pres_abc" {
+		t.Fatalf("xml_presentation_id = %v", data["xml_presentation_id"])
+	}
+	items, ok := data["screenshots"].([]interface{})
+	if !ok || len(items) != 2 {
+		t.Fatalf("screenshots = %#v, want two items", data["screenshots"])
+	}
+	item, _ := items[0].(map[string]interface{})
+	if item["slide_id"] != "slide_1" {
+		t.Fatalf("slide_id = %v, want slide_1", item["slide_id"])
+	}
+	gotPath := item["path"].(string)
+	if !filepath.IsAbs(gotPath) {
+		t.Fatalf("path = %v, want absolute path", gotPath)
+	}
+	if !strings.HasSuffix(gotPath, filepath.Join("shots", "pres_abc_slide_1.png")) {
+		t.Fatalf("path = %v, want shots/pres_abc_slide_1.png suffix", item["path"])
+	}
+	item2, _ := items[1].(map[string]interface{})
+	if item2["format"] != "jpeg" {
+		t.Fatalf("format = %v, want jpeg", item2["format"])
+	}
+	gotPath2 := item2["path"].(string)
+	if !filepath.IsAbs(gotPath2) {
+		t.Fatalf("path = %v, want absolute path", gotPath2)
+	}
+	if !strings.HasSuffix(gotPath2, filepath.Join("shots", "pres_abc_p002_slide_2.jpg")) {
+		t.Fatalf("path = %v, want shots/pres_abc_p002_slide_2.jpg suffix", item2["path"])
+	}
+
+	var body struct {
+		SlideIDs []string `json:"slide_ids"`
+	}
+	if err := json.Unmarshal(stub.CapturedBody, &body); err != nil {
+		t.Fatalf("decode request body: %v", err)
+	}
+	if len(body.SlideIDs) != 1 || body.SlideIDs[0] != "slide_1" {
+		t.Fatalf("slide_ids = %#v, want [slide_1]", body.SlideIDs)
+	}
+}
+
+func TestSlidesScreenshotListBySlideNumber(t *testing.T) {
+	dir := t.TempDir()
+	withSlidesTestWorkingDir(t, dir)
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	stub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc/slide_images",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"slide_images": []map[string]interface{}{
+					{
+						"slide_number": 2,
+						"format":       1,
+						"data":         base64.StdEncoding.EncodeToString([]byte("png-bytes")),
+					},
+				},
+			},
+		},
+	}
+	reg.Register(stub)
+
+	err := runSlidesShortcut(t, f, stdout, SlidesScreenshot, []string{
+		"+screenshot",
+		"--presentation", "pres_abc",
+		"--slide-number", "2",
+		"--as", "user",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var body struct {
+		SlideNumbers []int `json:"slide_numbers"`
+	}
+	if err := json.Unmarshal(stub.CapturedBody, &body); err != nil {
+		t.Fatalf("decode request body: %v", err)
+	}
+	if len(body.SlideNumbers) != 1 || body.SlideNumbers[0] != 2 {
+		t.Fatalf("slide_numbers = %#v, want [2]", body.SlideNumbers)
+	}
+	path := filepath.Join(dir, defaultSlidesScreenshotDir, "pres_abc_p002.png")
+	if _, err := os.ReadFile(path); err != nil {
+		t.Fatalf("read screenshot without slide_id: %v", err)
+	}
+}
+
+func TestSlidesScreenshotAvoidsOverwritingExistingFile(t *testing.T) {
+	dir := t.TempDir()
+	withSlidesTestWorkingDir(t, dir)
+	outputDir := filepath.Join(dir, "shots")
+	if err := os.MkdirAll(outputDir, 0o755); err != nil {
+		t.Fatalf("create output dir: %v", err)
+	}
+	existingPath := filepath.Join(outputDir, "pres_abc_p002.png")
+	if err := os.WriteFile(existingPath, []byte("existing"), 0o644); err != nil {
+		t.Fatalf("write existing screenshot: %v", err)
+	}
+
+	imageBytes := []byte("new-png")
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc/slide_images",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"slide_images": []map[string]interface{}{
+					{
+						"slide_number": 2,
+						"format":       1,
+						"data":         base64.StdEncoding.EncodeToString(imageBytes),
+					},
+				},
+			},
+		},
+	})
+
+	err := runSlidesShortcut(t, f, stdout, SlidesScreenshot, []string{
+		"+screenshot",
+		"--presentation", "pres_abc",
+		"--slide-number", "2",
+		"--output-dir", "shots",
+		"--as", "user",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	gotExisting, err := os.ReadFile(existingPath)
+	if err != nil {
+		t.Fatalf("read existing screenshot: %v", err)
+	}
+	if string(gotExisting) != "existing" {
+		t.Fatalf("existing screenshot = %q, want unchanged", gotExisting)
+	}
+	newPath := filepath.Join(outputDir, "pres_abc_p002_2.png")
+	gotNew, err := os.ReadFile(newPath)
+	if err != nil {
+		t.Fatalf("read deduplicated screenshot: %v", err)
+	}
+	if string(gotNew) != string(imageBytes) {
+		t.Fatalf("deduplicated screenshot = %q, want %q", gotNew, imageBytes)
+	}
+	data := decodeShortcutData(t, stdout)
+	items, ok := data["screenshots"].([]interface{})
+	if !ok || len(items) != 1 {
+		t.Fatalf("screenshots = %#v, want one item", data["screenshots"])
+	}
+	item, _ := items[0].(map[string]interface{})
+	if !strings.HasSuffix(item["path"].(string), filepath.Join("shots", "pres_abc_p002_2.png")) {
+		t.Fatalf("path = %v, want shots/pres_abc_p002_2.png suffix", item["path"])
+	}
+}
+
+func TestSlidesScreenshotListRequiresSelector(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+
+	err := runSlidesShortcut(t, f, stdout, SlidesScreenshot, []string{
+		"+screenshot",
+		"--presentation", "pres_abc",
+		"--as", "user",
+	})
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	if !strings.Contains(err.Error(), "--slide-id or --slide-number is required") {
+		t.Fatalf("error = %v, want missing selector error", err)
+	}
+}
+
+func TestSlidesScreenshotRenderContentWritesFile(t *testing.T) {
+	dir := t.TempDir()
+	withSlidesTestWorkingDir(t, dir)
+
+	content := `<slide xmlns="http://www.larkoffice.com/sml/2.0"><data></data></slide>`
+	if err := os.WriteFile(filepath.Join(dir, "slide.xml"), []byte(content), 0o644); err != nil {
+		t.Fatalf("write input xml: %v", err)
+	}
+	imageBytes := []byte("rendered-png")
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	stub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/slides_ai/v1/slide_image/render",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"slide_image": map[string]interface{}{
+					"slide_id":     "render_slide",
+					"slide_number": 1,
+					"format":       1,
+					"data":         base64.StdEncoding.EncodeToString(imageBytes),
+				},
+			},
+		},
+	}
+	reg.Register(stub)
+
+	err := runSlidesShortcut(t, f, stdout, SlidesScreenshot, []string{
+		"+screenshot",
+		"--content", "@slide.xml",
+		"--output-dir", "shots",
+		"--output-name", "preview",
+		"--as", "user",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	path := filepath.Join(dir, "shots", "preview.png")
+	gotBytes, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read rendered screenshot: %v", err)
+	}
+	if string(gotBytes) != string(imageBytes) {
+		t.Fatalf("written bytes = %q, want %q", gotBytes, imageBytes)
+	}
+	if strings.Contains(stdout.String(), base64.StdEncoding.EncodeToString(imageBytes)) {
+		t.Fatalf("stdout leaked base64 image data: %s", stdout.String())
+	}
+
+	var body struct {
+		Content string `json:"content"`
+	}
+	if err := json.Unmarshal(stub.CapturedBody, &body); err != nil {
+		t.Fatalf("decode request body: %v", err)
+	}
+	if body.Content != content {
+		t.Fatalf("content = %q, want input XML", body.Content)
+	}
+
+	data := decodeShortcutData(t, stdout)
+	items, ok := data["screenshots"].([]interface{})
+	if !ok || len(items) != 1 {
+		t.Fatalf("screenshots = %#v, want one item", data["screenshots"])
+	}
+	item, _ := items[0].(map[string]interface{})
+	if !strings.HasSuffix(item["path"].(string), filepath.Join("shots", "preview.png")) {
+		t.Fatalf("path = %v, want shots/preview.png suffix", item["path"])
+	}
+}
+
+func TestSlidesScreenshotRenderRejectsSlideSelectors(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+
+	err := runSlidesShortcut(t, f, stdout, SlidesScreenshot, []string{
+		"+screenshot",
+		"--content", `<slide xmlns="http://www.larkoffice.com/sml/2.0"><data></data></slide>`,
+		"--slide-id", "slide_1",
+		"--as", "user",
+	})
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	if !strings.Contains(err.Error(), "--content cannot be used with --slide-id or --slide-number") {
+		t.Fatalf("error = %v, want content/slide selector conflict", err)
+	}
+}
+
+func TestSlidesScreenshotRenderRejectsListOnlyFlags(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+
+	err := runSlidesShortcut(t, f, stdout, SlidesScreenshot, []string{
+		"+screenshot",
+		"--content", `<slide xmlns="http://www.larkoffice.com/sml/2.0"><data></data></slide>`,
+		"--presentation", "pres_abc",
+		"--as", "user",
+	})
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	if !strings.Contains(err.Error(), "--presentation cannot be used with --content") {
+		t.Fatalf("error = %v, want presentation/content conflict", err)
+	}
+}
+
+func TestSlidesScreenshotDryRunSelectsListOrRenderAPI(t *testing.T) {
+	t.Run("list", func(t *testing.T) {
+		f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+		err := runSlidesShortcut(t, f, stdout, SlidesScreenshot, []string{
+			"+screenshot",
+			"--presentation", "pres_abc",
+			"--slide-number", "2",
+			"--dry-run",
+			"--as", "user",
+		})
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		out := stdout.String()
+		if !strings.Contains(out, "/xml_presentations/pres_abc/slide_images") {
+			t.Fatalf("dry-run missing list endpoint: %s", out)
+		}
+		if !strings.Contains(out, "slide_numbers") {
+			t.Fatalf("dry-run missing slide_numbers body: %s", out)
+		}
+	})
+
+	t.Run("render", func(t *testing.T) {
+		f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+		err := runSlidesShortcut(t, f, stdout, SlidesScreenshot, []string{
+			"+screenshot",
+			"--content", `<slide xmlns="http://www.larkoffice.com/sml/2.0"><data></data></slide>`,
+			"--dry-run",
+			"--as", "user",
+		})
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		out := stdout.String()
+		if !strings.Contains(out, "/slide_image/render") {
+			t.Fatalf("dry-run missing render endpoint: %s", out)
+		}
+		if !strings.Contains(out, "base64_output") {
+			t.Fatalf("dry-run missing base64 suppression note: %s", out)
+		}
+	})
+}
+
+func TestSlidesScreenshotRejectsBadOutputDir(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+
+	err := runSlidesShortcut(t, f, stdout, SlidesScreenshot, []string{
+		"+screenshot",
+		"--presentation", "pres_abc",
+		"--slide-id", "slide_1",
+		"--output-dir", "../outside",
+		"--as", "user",
+	})
+	if err == nil {
+		t.Fatal("expected error for unsafe output dir")
+	}
+	if !strings.Contains(err.Error(), "--output-dir invalid") {
+		t.Fatalf("error = %v, want output-dir validation", err)
+	}
+}
+
+func TestSlidesScreenshotNoImagesErrorIncludesRawDataAndLogID(t *testing.T) {
+	dir := t.TempDir()
+	withSlidesTestWorkingDir(t, dir)
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc/slide_images",
+		Headers: map[string][]string{
+			"Content-Type": {"application/json"},
+			"X-Tt-Logid":   {"log-123"},
+		},
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"unexpected": "shape",
+			},
+		},
+	})
+
+	err := runSlidesShortcut(t, f, stdout, SlidesScreenshot, []string{
+		"+screenshot",
+		"--presentation", "pres_abc",
+		"--slide-id", "pJJ",
+		"--as", "user",
+	})
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("error type = %T, want typed problem", err)
+	}
+	if p.LogID != "log-123" {
+		t.Fatalf("log_id = %v, want log-123", p.LogID)
+	}
+	if !strings.Contains(p.Message, "unexpected:shape") {
+		t.Fatalf("message = %q, want raw_data summary", p.Message)
+	}
+}
+
+func TestSlidesScreenshotSlideNumberAPIErrorAddsHint(t *testing.T) {
+	dir := t.TempDir()
+	withSlidesTestWorkingDir(t, dir)
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc/slide_images",
+		Headers: map[string][]string{
+			"Content-Type": {"application/json"},
+			"X-Tt-Logid":   {"log-slide-number"},
+		},
+		Body: map[string]interface{}{
+			"code": 99992402,
+			"msg":  "field validation failed",
+		},
+	})
+
+	err := runSlidesShortcut(t, f, stdout, SlidesScreenshot, []string{
+		"+screenshot",
+		"--presentation", "pres_abc",
+		"--slide-number", "25",
+		"--as", "user",
+	})
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("error type = %T, want typed problem", err)
+	}
+	if p.LogID != "log-slide-number" {
+		t.Fatalf("log_id = %v, want log-slide-number", p.LogID)
+	}
+	if !strings.Contains(p.Hint, "--slide-id") {
+		t.Fatalf("hint = %q, want --slide-id guidance", p.Hint)
+	}
+}

shortcuts/slides/slides_xml_get.go

@@ -0,0 +1,144 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package slides
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/extension/fileio"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// SlidesXMLGet fetches the full XML presentation content and writes it to a
+// local file, keeping the terminal output small for large decks.
+var SlidesXMLGet = common.Shortcut{
+	Service:     "slides",
+	Command:     "+xml-get",
+	Description: "Fetch full presentation XML and save it to a local file",
+	Risk:        "read",
+	Scopes:      []string{"slides:presentation:read"},
+	// wiki:node:read is required only when --presentation is a wiki URL.
+	ConditionalScopes: []string{"wiki:node:read"},
+	AuthTypes:         []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "presentation", Desc: "xml_presentation_id, slides URL, or wiki URL that resolves to slides", Required: true},
+		{Name: "output", Desc: "local XML output path; existing file is overwritten", Required: true},
+		{Name: "revision-id", Type: "int", Default: "-1", Desc: "presentation revision_id; -1 means latest"},
+		{Name: "remove-attr-id", Type: "bool", Desc: "remove XML id attributes in the returned content; useful for read-only inspection, not precise block editing"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		ref, err := parsePresentationRef(runtime.Str("presentation"))
+		if err != nil {
+			return err
+		}
+		if ref.Kind == "wiki" {
+			if err := runtime.EnsureScopes([]string{"wiki:node:read"}); err != nil {
+				return err
+			}
+		}
+		if strings.TrimSpace(runtime.Str("output")) == "" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--output cannot be empty").WithParam("--output")
+		}
+		if _, err := runtime.ResolveSavePath(runtime.Str("output")); err != nil {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--output invalid: %v", err).WithParam("--output").WithCause(err)
+		}
+		if runtime.Int("revision-id") < -1 {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--revision-id must be -1 or a non-negative integer").WithParam("--revision-id")
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		ref, err := parsePresentationRef(runtime.Str("presentation"))
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
+		presentationID := ref.Token
+		dry := common.NewDryRunAPI()
+		if ref.Kind == "wiki" {
+			presentationID = "<resolved_slides_token>"
+			dry.Desc("2-step orchestration: resolve wiki → fetch full presentation XML").
+				GET("/open-apis/wiki/v2/spaces/get_node").
+				Desc("[1] Resolve wiki node to slides presentation").
+				Params(map[string]interface{}{"token": ref.Token})
+		} else {
+			dry.Desc("Fetch full presentation XML and save it to a local file")
+		}
+		params := map[string]interface{}{
+			"revision_id": runtime.Int("revision-id"),
+		}
+		if runtime.Bool("remove-attr-id") {
+			params["remove_attr_id"] = true
+		}
+		dry.GET(fmt.Sprintf(
+			"/open-apis/slides_ai/v1/xml_presentations/%s",
+			validate.EncodePathSegment(presentationID),
+		)).
+			Params(params)
+		return dry.Set("output", runtime.Str("output")).Set("stdout_content", "suppressed; XML content is saved to --output during execution")
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		ref, err := parsePresentationRef(runtime.Str("presentation"))
+		if err != nil {
+			return err
+		}
+		presentationID, err := resolvePresentationID(runtime, ref)
+		if err != nil {
+			return err
+		}
+
+		params := map[string]interface{}{
+			"revision_id": runtime.Int("revision-id"),
+		}
+		if runtime.Bool("remove-attr-id") {
+			params["remove_attr_id"] = true
+		}
+		data, err := runtime.CallAPITyped(
+			"GET",
+			fmt.Sprintf("/open-apis/slides_ai/v1/xml_presentations/%s", validate.EncodePathSegment(presentationID)),
+			params,
+			nil,
+		)
+		if err != nil {
+			return err
+		}
+
+		presentation := common.GetMap(data, "xml_presentation")
+		content := common.GetString(presentation, "content")
+		if content == "" {
+			return errs.NewInternalError(errs.SubtypeInvalidResponse, "slides xml get returned empty xml_presentation.content")
+		}
+		outputPath := runtime.Str("output")
+		result, err := runtime.FileIO().Save(outputPath, fileio.SaveOptions{
+			ContentType:   "application/xml",
+			ContentLength: int64(len(content)),
+		}, bytes.NewReader([]byte(content)))
+		if err != nil {
+			return common.WrapSaveErrorTyped(err)
+		}
+		resolvedPath, err := runtime.ResolveSavePath(outputPath)
+		if err != nil {
+			return errs.NewInternalError(errs.SubtypeFileIO, "resolve saved XML path %s: %v", outputPath, err).WithCause(err)
+		}
+
+		out := map[string]interface{}{
+			"xml_presentation_id": presentationID,
+			"path":                resolvedPath,
+			"size":                result.Size(),
+			"content_saved":       true,
+		}
+		if revisionID := common.GetFloat(presentation, "revision_id"); revisionID > 0 {
+			out["revision_id"] = int(revisionID)
+		}
+		if runtime.Bool("remove-attr-id") {
+			out["remove_attr_id"] = true
+		}
+		runtime.Out(out, nil)
+		return nil
+	},
+}

shortcuts/slides/slides_xml_get_test.go

@@ -0,0 +1,157 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package slides
+
+import (
+	"net/http"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+func TestSlidesXMLGetWritesContentToFileAndSuppressesXML(t *testing.T) {
+	dir := t.TempDir()
+	withSlidesTestWorkingDir(t, dir)
+
+	xml := `<presentation><slide id="s1"><shape id="a">hello</shape></slide></presentation>`
+	var capturedQuery url.Values
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"xml_presentation": map[string]interface{}{
+					"presentation_id": "pres_abc",
+					"revision_id":     7,
+					"content":         xml,
+				},
+			},
+		},
+		OnMatch: func(req *http.Request) {
+			capturedQuery = req.URL.Query()
+		},
+	})
+
+	err := runSlidesShortcut(t, f, stdout, SlidesXMLGet, []string{
+		"+xml-get",
+		"--presentation", "pres_abc",
+		"--output", "readback.xml",
+		"--revision-id", "7",
+		"--remove-attr-id",
+		"--as", "user",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	path := filepath.Join(dir, "readback.xml")
+	got, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read saved XML: %v", err)
+	}
+	if string(got) != xml {
+		t.Fatalf("saved XML = %q, want %q", got, xml)
+	}
+	if strings.Contains(stdout.String(), xml) {
+		t.Fatalf("stdout leaked full XML content: %s", stdout.String())
+	}
+	if got := capturedQuery.Get("revision_id"); got != "7" {
+		t.Fatalf("revision_id query = %q, want 7", got)
+	}
+	if got := capturedQuery.Get("remove_attr_id"); got != "true" {
+		t.Fatalf("remove_attr_id query = %q, want true", got)
+	}
+
+	data := decodeShortcutData(t, stdout)
+	if data["xml_presentation_id"] != "pres_abc" {
+		t.Fatalf("xml_presentation_id = %v, want pres_abc", data["xml_presentation_id"])
+	}
+	if data["revision_id"] != float64(7) {
+		t.Fatalf("revision_id = %v, want 7", data["revision_id"])
+	}
+	if data["size"] != float64(len(xml)) {
+		t.Fatalf("size = %v, want %d", data["size"], len(xml))
+	}
+	gotPath, _ := data["path"].(string)
+	if !filepath.IsAbs(gotPath) {
+		t.Fatalf("path = %v, want absolute path", gotPath)
+	}
+	if !strings.HasSuffix(gotPath, "readback.xml") {
+		t.Fatalf("path = %v, want readback.xml suffix", gotPath)
+	}
+}
+
+func TestSlidesXMLGetResolvesWikiPresentation(t *testing.T) {
+	dir := t.TempDir()
+	withSlidesTestWorkingDir(t, dir)
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/wiki/v2/spaces/get_node",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"node": map[string]interface{}{
+					"obj_type":  "slides",
+					"obj_token": "pres_real",
+				},
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_real",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"xml_presentation": map[string]interface{}{
+					"content": `<presentation/>`,
+				},
+			},
+		},
+	})
+
+	err := runSlidesShortcut(t, f, stdout, SlidesXMLGet, []string{
+		"+xml-get",
+		"--presentation", "https://example.feishu.cn/wiki/wikcn123",
+		"--output", "wiki.xml",
+		"--as", "user",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	data := decodeShortcutData(t, stdout)
+	if data["xml_presentation_id"] != "pres_real" {
+		t.Fatalf("xml_presentation_id = %v, want pres_real", data["xml_presentation_id"])
+	}
+}
+
+func TestSlidesXMLGetRejectsUnsafeOutputPath(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	err := runSlidesShortcut(t, f, stdout, SlidesXMLGet, []string{
+		"+xml-get",
+		"--presentation", "pres_abc",
+		"--output", "../readback.xml",
+		"--as", "user",
+	})
+	if err == nil {
+		t.Fatal("expected unsafe output path error, got nil")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed error, got %T %v", err, err)
+	}
+	if problem.Param != "--output" {
+		t.Fatalf("param = %q, want --output", problem.Param)
+	}
+}

skills/lark-drive/SKILL.md

@@ -18,13 +18,14 @@ metadata:
 
 ## 快速决策
 
+- 用户要**检查 / 治理文档权限、公开范围、链接分享、外部访问、复制下载权限、密级标签、owner 转移**，或要“权限风险报告、收紧权限、申请查看 / 编辑权限、转移 / 批量转移 owner”，必须先阅读 [`references/lark-drive-workflow.md`](references/lark-drive-workflow.md)，再按其中 `Workflow Registry` 进入 [`permission_governance`](references/lark-drive-workflow-permission-governance.md) workflow。
 - 用户要**整理云盘 / 文件夹 / 文档库 / 知识库 / 个人文档库**，或要“盘点目录结构、找出未归档/临时/重复/空目录、生成整理方案”，必须先阅读 [`references/lark-drive-workflow-knowledge-organize.md`](references/lark-drive-workflow-knowledge-organize.md)。默认只生成方案；创建目录、移动资源、申请权限都必须单独确认。
 - 用户要**搜文档 / Wiki / 电子表格 / 多维表格 / 云空间（云盘/云存储）对象**，优先使用 `lark-cli drive +search`。自然语言里"最近我编辑过的"、"我创建的"（→ `--created-by-me`，原始创建者语义）、"我负责/owner 的"（→ `--mine`，owner 语义）、"最近一周我打开过的 xxx"、"某人 owner 的 docx" 等直接映射到扁平 flag，避免手写嵌套 JSON。
 - 用户要**根据文档评论定位正文位置**，例如 根据评论 review 文档、根据评论内容回看文档、区分多处相同引用文本时，对于 docx 类型（`file_type=docx`）的文档支持通过 `need_relation=true` 返回评论位置，其他类型暂不支持，具体用法需要先阅读 [`references/lark-drive-comment-location.md`](references/lark-drive-comment-location.md) 了解。
 - 用户给出 doubao.com 的云空间资源 URL/token，或明确提到豆包里的 file/folder/docx/sheet/bitable/wiki 资源时，仍按资源类型、URL 路径和 token 路由到本 skill；不要因为域名不是飞书而回退到 WebFetch。
 - 用户要把本地 `.xlsx` / `.csv` / `.base` 导入成 Base / 多维表格 / bitable，第一步必须使用 `lark-cli drive +import --type bitable`。
 - 用户要把本地 `.md` / `.docx` / `.doc` / `.txt` / `.html` 导入成在线文档，使用 `lark-cli drive +import --type docx`。
-- 用户要把本地 `.pptx` 导入成飞书幻灯片，使用 `lark-cli drive +import --type slides`；当前 PPTX 导入上限是 500MB。
+- 用户要把本地 `.pptx` / `.pdf` 导入成飞书幻灯片，使用 `lark-cli drive +import --type slides`；当前 PPTX/PDF 导入上限是 500MB。PDF 导入 Slides 通常可按每页约 10 秒预估处理时间，轮询或续查时不要过早放弃。
 - 用户要在 Drive 里上传、创建、读取、局部 patch 或覆盖更新**原生 `.md` 文件**（不是导入成 docx），切到 [`lark-markdown`](../lark-markdown/SKILL.md)。
 - 用户要比较原生 `.md` 文件的**历史版本差异**，或比较远端 Markdown 与本地草稿，切到 [`lark-markdown`](../lark-markdown/SKILL.md) 的 `lark-cli markdown +diff`；需要版本号时先用 `drive +version-history`。
 - 用户要查看、下载、回滚或删除文件的**历史版本**，使用 `drive +version-history`、`drive +version-get`、`drive +version-revert`、`drive +version-delete`；这组命令同时支持 `--as user` 和 `--as bot`，自动化场景优先 `--as bot`。

skills/lark-drive/references/lark-drive-import.md

@@ -2,7 +2,7 @@
 
 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
-将本地文件（如 Word、TXT、Markdown、Excel、PPTX 等）导入并转换为飞书在线云文档（docx、sheet、bitable、slides）。底层统一通过 `POST /open-apis/drive/v1/import_tasks` 接口创建导入任务，并在 shortcut 内做有限次数轮询 `GET /open-apis/drive/v1/import_tasks/:ticket`。
+将本地文件（如 Word、TXT、Markdown、Excel、PPTX、PDF 等）导入并转换为飞书在线云文档（docx、sheet、bitable、slides）。底层统一通过 `POST /open-apis/drive/v1/import_tasks` 接口创建导入任务，并在 shortcut 内做有限次数轮询 `GET /open-apis/drive/v1/import_tasks/:ticket`。
 
 > [!IMPORTANT]
 > 当用户说“把本地 Excel / CSV / `.base` 快照导入成 Base / 多维表格 / bitable 文档”时，第一步必须使用 `drive +import --type bitable`。
@@ -45,8 +45,9 @@ lark-cli drive +import --file ./crm.xlsx --type bitable --name "客户台账"
 # 导入 .base 快照为多维表格 / Base (bitable)（文件不能超过 20MB）
 lark-cli drive +import --file ./snapshot.base --type bitable --name "快照还原"
 
-# 导入 PPTX 为飞书幻灯片 (slides)（文件不能超过 500MB）
+# 导入 PPTX / PDF 为飞书幻灯片 (slides)（文件不能超过 500MB；PDF 可按每页约 10 秒预估导入处理时间）
 lark-cli drive +import --file ./deck.pptx --type slides --name "项目汇报"
+lark-cli drive +import --file ./deck.pdf --type slides --name "项目汇报"
 
 # 导入到指定文件夹，并指定导入后的文件名
 lark-cli drive +import --file ./data.csv --type bitable --folder-token <FOLDER_TOKEN> --name "导入数据表"
@@ -78,6 +79,7 @@ lark-cli drive +import --file ./README.md --type docx --dry-run
   3. 自动轮询查询导入任务状态；如果在内置轮询窗口内完成，则直接返回导入结果；如果仍未完成，则返回 `ticket`、当前状态和后续查询命令
 - **默认根目录行为**：不传 `--folder-token` 时，shortcut 会保留空的 `point.mount_key`，Lark Import API 会将其视为"导入到调用者根目录"。
 - **导入到已有 bitable**：当 `--type bitable` 且传了 `--target-token` 时，请求 body 中会增加一个 `token` 字段指向目标多维表格的 token，point 挂载点逻辑不变。数据会挂载到该已有多维表格中，而非创建新文档。
+- **PDF 导入 Slides 耗时预估**：PDF 导入 Slides 是长耗时异步任务，通常按每页约 10 秒估算总处理时间。`drive +import` 内置轮询超时只表示本地等待窗口结束，不代表任务失败。看到 `ready=false` / `timed_out=true` 时，必须继续执行返回的 `next_command` 查询同一个 `ticket`，不要重试导入、不要提前放弃；至少等待到 `页数 * 10 秒` 的预估处理时间后，再结合任务状态判断是否异常。
 
 ### 支持的文件类型转换
 
@@ -94,6 +96,7 @@ lark-cli drive +import --file ./README.md --type docx --dry-run
 | `.csv` | `sheet`, `bitable` | CSV 数据文件 |
 | `.base` | `bitable` | 多维表格快照文件 |
 | `.pptx` | `slides` | Microsoft PowerPoint 演示文稿 |
+| `.pdf` | `slides` | PDF 文档 |
 
 > [!IMPORTANT]
 > 用户口头说的 “Base” / “多维表格” / “bitable”，在命令里统一对应 `--type bitable`。
@@ -103,7 +106,7 @@ lark-cli drive +import --file ./README.md --type docx --dry-run
 > - `.xlsx` / `.csv` 文件**只能**导入为 `sheet` 或 `bitable`
 > - `.xls` 文件**只能**导入为 `sheet`
 > - `.base` 文件**只能**导入为 `bitable`
-> - `.pptx` 文件**只能**导入为 `slides`
+> - `.pptx` / `.pdf` 文件**只能**导入为 `slides`
 > - 例如：`.csv` 文件不能导入为 `docx`，`.md` 文件不能导入为 `sheet`
 
 > [!IMPORTANT]
@@ -137,7 +140,7 @@ lark-cli drive +import --file ./README.md --type docx --dry-run
 | `.csv` | `bitable` | 100MB |
 | `.xls` | `sheet` | 20MB |
 | `.base` | `bitable` | 20MB |
-| `.pptx` | `slides` | 500MB |
+| `.pptx`, `.pdf` | `slides` | 500MB |
 
 - 如果文件超出对应上限，shortcut 会在真正上传前直接返回验证错误。
 - “超过 20MB 自动切换分片上传”只表示上传链路会切到 multipart，不代表所有格式都允许导入超过 20MB 的文件。

skills/lark-drive/references/lark-drive-workflow-permission-governance-commands.md

@@ -0,0 +1,168 @@
+# 权限治理 Command Patterns
+
+本文只提供 `permission_governance` workflow 的具体 `lark-cli` 命令样例。只有进入对应 state 且需要拼装命令时才读取本文；命令可用范围仍以 [`lark-drive-workflow-permission-governance.md`](lark-drive-workflow-permission-governance.md) 的 `Command Map` 为准。
+
+## 目录
+
+- `目标解析`
+- `目标发现`
+- `事实读取`
+- `写前确认与执行`
+
+## 目标解析
+
+```bash
+lark-cli drive +inspect --url '<url>' --as user --format json
+```
+
+`/wiki/space/<space_id>` URL 是 Wiki space 范围，不要用 `drive +inspect` 当作单文档解析；直接提取 `space_id` 后进入 `DISCOVER_TARGETS`。
+
+## 目标发现
+
+发现 Wiki space / node 下目标：
+
+```bash
+lark-cli wiki +node-list \
+  --space-id '<space_id>' --page-size 50 \
+  --page-all --page-limit 0 \
+  --as user --format json
+
+lark-cli wiki +node-list \
+  --space-id '<space_id>' --parent-node-token '<node_token>' --page-size 50 \
+  --page-all --page-limit 0 \
+  --as user --format json
+
+lark-cli wiki +node-list \
+  --space-id '<space_id>' --page-token '<PAGE_TOKEN>' --page-size 50 \
+  --as user --format json
+```
+
+解析返回时使用 `data.nodes`，不要读取顶层 `items`。`--page-limit 0` 表示当前层分页不设页数上限；`--page-all` 只覆盖当前 `space-id` / `parent-node-token` 范围内的分页，不会递归子节点。节点 `has_child=true` 时，必须继续以该节点的 `node_token` 作为 `--parent-node-token` 递归读取。
+
+发现 Drive folder 下目标：
+
+```bash
+lark-cli drive files list \
+  --params '{"folder_token":"<folder_token>","page_size":200}' \
+  --as user --format json
+
+lark-cli drive files list \
+  --params '{"folder_token":"<folder_token>","page_size":200,"page_token":"<PAGE_TOKEN>"}' \
+  --as user --format json
+```
+
+## 事实读取
+
+读取 metadata：
+
+```bash
+lark-cli drive metas batch_query \
+  --data '{"request_docs":[{"doc_token":"<token>","doc_type":"<type>"}],"with_url":true}' \
+  --as user --format json
+```
+
+读取 public permission：
+
+```bash
+lark-cli drive permission.public get \
+  --params '{"token":"<token>","type":"<type>"}' \
+  --as user --format json
+```
+
+按需读取访问统计：
+
+```bash
+lark-cli drive file.statistics get \
+  --params '{"file_token":"<token>","file_type":"<type>"}' \
+  --as user --format json
+```
+
+按需读取最近访问记录：
+
+```bash
+lark-cli drive file.view_records list \
+  --params '{"file_token":"<token>","file_type":"<type>","page_size":50}' \
+  --as user --format json
+```
+
+## 写前确认与执行
+
+patch 前检查 manage-public permission：
+
+```bash
+lark-cli drive permission.members auth \
+  --params '{"token":"<token>","type":"<type>","action":"manage_public"}' \
+  --as user --format json
+```
+
+patch 前读取当前 schema：
+
+```bash
+lark-cli schema drive.permission.public.patch --format json
+```
+
+只 patch 当前 schema 支持的字段；对 Wiki 目标，必须省略 schema 明确标注为 Wiki 不支持的字段。
+
+显式确认后 patch public permission：
+
+```bash
+lark-cli drive permission.public patch \
+  --params '{"token":"<token>","type":"<type>"}' \
+  --data '{"link_share_entity":"closed","external_access":false}' \
+  --as user --yes --format json
+```
+
+显式确认后申请访问权限：
+
+```bash
+lark-cli drive +apply-permission \
+  --token '<url>' \
+  --perm view --remark '<reason>' --as user --format json
+
+lark-cli drive +apply-permission \
+  --token '<bare-token>' --type '<type>' \
+  --perm view --remark '<reason>' --as user --format json
+```
+
+owner 转移前读取当前 schema：
+
+```bash
+lark-cli schema drive.permission.members.transfer_owner --format json
+```
+
+显式确认后转移 owner：
+
+```bash
+lark-cli drive permission.members transfer_owner \
+  --params '{"token":"<token>","type":"<type>","need_notification":true,"remove_old_owner":false,"old_owner_perm":"full_access","stay_put":true}' \
+  --data '{"member_id":"<new_owner_open_id>","member_type":"openid"}' \
+  --as user --yes --format json
+```
+
+`member_type` 只能使用当前 schema 支持的值：`email`、`openid`、`userid`、`appid`。如果用户只给姓名，必须先解析为明确身份或要求用户补充；不要猜测 `member_id`。批量 owner 转移必须逐个目标顺序执行。
+
+secure label 写前枚举可用标签：
+
+```bash
+lark-cli drive +secure-label-list \
+  --page-size 10 --lang zh \
+  --as user --format json
+
+lark-cli drive +secure-label-list \
+  --page-size 10 --page-token '<PAGE_TOKEN>' --lang zh \
+  --as user --format json
+```
+
+当用户给出的是标签名称、密级文案或不确定的 label ID 时，必须先枚举并解析为 `label-id`；写入确认里展示目标标签名称和 ID。找不到唯一标签时，停止并让用户选择，不要猜测。
+
+显式确认后更新 secure label：
+
+```bash
+lark-cli drive +secure-label-update \
+  --token '<url>' \
+  --label-id '<label-id>' --as user --format json
+
+lark-cli drive +secure-label-update \
+  --token '<bare-token>' --type '<type>' \
+  --label-id '<label-id>' --as user --format json
+```

skills/lark-drive/references/lark-drive-workflow-permission-governance-outputs.md

@@ -0,0 +1,424 @@
+# 权限治理输出模板
+
+本文只提供 `permission_governance` workflow 的用户可见输出模板。默认先给简短摘要；只有用户要求完整表格、需要写入确认，或结果大到需要结构化展示时才读取本文。
+
+## 目录
+
+- `输出策略`
+- `Semantic Rendering`
+- `定位与治理动作`
+- `单目标公开性判断`
+- `多目标明确列表诊断`
+- `审计摘要`
+- `容器安全诊断报告摘要`
+- `可操作风险清单`
+- `治理选择交互`
+- `权限设置清单`
+- `访问复核清单`
+- `整改 dry-run`
+- `批量权限申请确认`
+- `owner 转移确认`
+- `确认请求`
+- `最终摘要`
+
+## 输出策略
+
+- 单目标默认输出审计摘要。
+- 多目标明确列表默认输出逐目标诊断摘要；不要因为目标数大于 1 就套用容器递归发现报告。
+- 用户可见结论默认跟随用户当前语言。用户用中文提问时输出中文，用户用英文提问时输出英文；混合语言时跟随主要语言。
+- 单目标公开性判断默认输出业务表达，不直接展示 `link_share_entity`、`external_access_entity`、`external_access` 等底层字段名；只有用户要求 raw evidence、排障，或完整清单 / artifact 场景才展示底层字段。
+- 中文用户可见输出中，`permission_public` / `public permission` 默认译为“文档公共访问和协作权限设置”；可在摘要里简称“公共访问与协作设置”。它在官方语义中包含链接分享、对外分享、协作者管理、复制内容、创建副本、打印、下载和评论；具体可判断字段以当前 CLI schema 和实际响应为准。只有命令名、schema 字段、raw evidence、排障信息和完整 artifact 字段名保留英文原文。
+- 容器目标默认输出安全诊断报告摘要：一句话结论、覆盖情况、风险分级、优先处理对象、建议下一步和剩余限制。
+- 容器目标不要把风险按数量机械排序；外部公开、允许对外分享、缺失密级标签优先于复制 / 下载 / 评论这类依赖策略的候选项。
+- 用户没有提供明确 policy 时，使用“候选风险 / 待复核 / 待策略确认”，不要写“违规 / 已泄露 / 已外部访问”。
+- 容器安全诊断里不要把 `external_access=true` / `external_access_entity=open` 简写成“高风险”或“外部泄露”；用户可见说法应为“允许对外分享，需 owner 复核；这不等于已经存在外部协作者”。
+- 风险对象展示按规模渐进披露：1-10 个全部展示；11-30 个展示全部高优先级待复核对象，中 / 低优先级只做分组摘要；31-100 个按高优先级待复核分组展示 Top 5 和数量；100+ 个只展示分组统计和 Top 样例。
+- 当摘要未展示全部风险对象时，必须明确“完整清单包含 <count> 条”，并提供生成 Markdown / CSV / 飞书文档风险清单或整改 dry-run 的下一步。
+- 只要发现需要处理的对象，最终回复必须给出可执行下一步 CTA。不能因为默认只读，就只报告风险后结束。
+- 完整风险清单是后续治理选择的输入；Markdown / CSV / 飞书文档报告必须使用同一套字段和稳定 `risk_id`。
+- 写入前必须使用确认模板；权限申请、文档公共访问和协作权限设置修改、owner 转移、密级标签更新分别确认。
+- 最终回复必须包含已完成事项、验证结果和剩余限制；异步权限申请审批不能表述为已完成授权。
+
+## Semantic Rendering
+
+面向用户的主结论优先渲染 `per_target_permission_assessment` 中的语义状态，并使用用户当前语言；底层字段名只在 raw evidence、排障或完整清单中保留。下表给出字段值到业务表达的标准映射；其他语言应表达同等业务含义。
+
+字段来源边界：下表同时覆盖官方 OpenAPI 语义和当前 / 未来 CLI schema。只有实际响应或当前 schema 返回的字段和值，才可渲染为确定状态；当前 installed CLI 未返回的字段（例如 `copy_entity`、`manage_collaborator_entity`、`external_access_entity`）或未出现的枚举值，只能在 raw response / schema 实际出现时使用，缺失时必须按 unknown / unsupported 处理，不要臆造。
+
+| Raw field / value | Semantic State | 中文说法 | English phrasing |
+|-------------------|----------------|----------|------------------|
+| `link_share_entity=anyone_readable` | `link_access=public_readable` | 互联网上获得链接的任何人可阅读 | Anyone on the internet with the link can read |
+| `link_share_entity=anyone_editable` | `link_access=public_editable` | 互联网上获得链接的任何人可编辑 | Anyone on the internet with the link can edit |
+| `link_share_entity=partner_tenant_readable` | `link_access=partner_readable` | 关联组织内知道链接可读 | People in partner tenants with the link can read |
+| `link_share_entity=partner_tenant_editable` | `link_access=partner_editable` | 关联组织内知道链接可编辑 | People in partner tenants with the link can edit |
+| `link_share_entity=tenant_readable` | `link_access=tenant_readable` | 公司内知道链接可读 | People in the tenant with the link can read |
+| `link_share_entity=tenant_editable` | `link_access=tenant_editable` | 公司内知道链接可编辑 | People in the tenant with the link can edit |
+| link sharing empty / disabled | `link_access=closed` | 未开启链接分享 | Link sharing is disabled |
+| `external_access_entity=open` or `external_access=true` | `external_sharing=open` | 允许分享到组织外；不等于已经存在外部协作者 | External sharing is open; this does not mean external collaborators already exist |
+| `external_access_entity=allow_share_partner_tenant` | `external_sharing=partner_only` | 仅允许分享到关联组织 | Sharing is allowed only with partner tenants |
+| `external_access_entity=closed` or `external_access=false` | `external_sharing=closed` | 当前不允许分享到组织外 | External sharing is disabled |
+| `invite_external=true` | `external_invitation=enabled` | 当前允许邀请外部用户 | Inviting external users is enabled |
+| `invite_external=false` | `external_invitation=disabled` | 当前不允许邀请外部用户 | Inviting external users is disabled |
+| `share_entity=anyone` | `collaborator_org_scope=all_viewers_or_editors` | 所有可阅读或可编辑者可查看、添加、移除协作者 | All viewers or editors can view, add, and remove collaborators |
+| `share_entity=same_tenant` | `collaborator_org_scope=tenant_viewers_or_editors` | 组织内可阅读或可编辑者可查看、添加、移除协作者 | Tenant viewers or editors can view, add, and remove collaborators |
+| `manage_collaborator_entity=collaborator_can_view` | `collaborator_permission_scope=viewer` | 拥有可阅读权限的协作者可查看、添加、移除协作者 | Collaborators with view permission can view, add, and remove collaborators |
+| `manage_collaborator_entity=collaborator_can_edit` | `collaborator_permission_scope=editor` | 拥有可编辑权限的协作者可查看、添加、移除协作者 | Collaborators with edit permission can view, add, and remove collaborators |
+| `manage_collaborator_entity=collaborator_full_access` | `collaborator_permission_scope=full_access` | 拥有可管理权限的协作者可查看、添加、移除协作者 | Collaborators with full-access permission can view, add, and remove collaborators |
+| `copy_entity=anyone_can_view` | `copy_scope=viewer` | 拥有可阅读权限的用户可复制内容 | Users with view permission can copy content |
+| `copy_entity=anyone_can_edit` | `copy_scope=editor` | 拥有可编辑权限的用户可复制内容 | Users with edit permission can copy content |
+| `copy_entity=only_full_access` | `copy_scope=full_access` | 仅拥有可管理权限的协作者可复制内容 | Only collaborators with full-access permission can copy content |
+| `security_entity=anyone_can_view` | `security_scope=viewer` | 拥有可阅读权限的用户可创建副本、打印、下载 | Users with view permission can create copies, print, and download |
+| `security_entity=anyone_can_edit` | `security_scope=editor` | 拥有可编辑权限的用户可创建副本、打印、下载 | Users with edit permission can create copies, print, and download |
+| `security_entity=only_full_access` | `security_scope=full_access` | 仅拥有可管理权限的用户可创建副本、打印、下载 | Only users with full-access permission can create copies, print, and download |
+| `comment_entity=anyone_can_view` | `comment_scope=viewer` | 拥有可阅读权限的用户可评论 | Users with view permission can comment |
+| `comment_entity=anyone_can_edit` | `comment_scope=editor` | 拥有可编辑权限的用户可评论 | Users with edit permission can comment |
+| `lock_switch=true` | `lock_state=locked_not_inheriting` | 已限制权限，不再继承父级页面权限 | The node is locked and no longer inherits parent-page permissions |
+| `lock_switch=false` | `lock_state=not_locked_or_inheriting` | 未限制权限，可能继承父级页面权限 | The node is not locked and may inherit parent-page permissions |
+| field absent / unsupported | `<state>=unknown` | 当前 schema 未返回，无法判断 | The current schema did not return this field, so it is unknown |
+| `check_scope=current_public_permission_only` | `check_scope=current_public_permission_only` | 本次判断的是当前文档公共访问和协作权限设置，不是协作者名单或历史权限变更审计 | This check covers current public access and collaboration settings, not collaborator-list or historical permission-change auditing |
+| `sec_label_name` missing | `sec_label=missing` | 缺少密级标签 | Security label is missing |
+
+## 定位与治理动作
+
+风险对象必须能让用户直接定位和处理：
+
+- 摘要中的每个优先处理对象必须包含 `risk_id`、`path/title`、`URL`、`type`、owner、sec_label、风险原因、关键证据和建议动作。
+- 完整清单、访问复核清单、整改 dry-run 和写入确认都必须包含 URL。缺少 URL 时，展示 token / node_token，并说明 URL 未能获取。
+- 同名文档、shortcut 或副本必须用 path + URL 区分；不要只输出 title。
+- 完整风险清单中的每条记录必须有稳定 `risk_id`，格式为 `PG-001`、`PG-002`。`risk_id` 在同一次诊断和后续 dry-run / 确认 / 验证中保持不变。
+- 即使摘要只展示 Top 样例，也必须给样例分配稳定 `risk_id`；不能输出无法选择的标题列表。
+- 建议动作必须和风险类型绑定：互联网公开链接优先建议关闭链接分享或收紧为组织内；允许对外分享优先建议 owner 复核或关闭对外分享；缺少密级标签优先建议补齐密级；复制 / 下载 / 评论范围只在用户 policy 明确时建议收紧。
+- 写入动作只能作为下一步选项或确认请求出现。不要在诊断摘要里暗示已经执行缩权。
+
+## 单目标公开性判断
+
+当 `intent=public_exposure_check` 且 `target_scope=single_resource` 时，使用此模板。默认渲染 `target_count=1` 的 `per_target_permission_assessment`，跟随用户当前语言，不直接展示底层字段名；用户要求 raw evidence 时，再追加字段证据。
+
+中文模板：
+
+```text
+结论：<不是对外公开 / 存在互联网公开链接 / 允许对外分享>。
+
+目标：<title>
+URL：<url-or-token-if-url-unavailable>
+类型：<type>
+
+当前链接访问范围：<render link_access>
+对外分享：<render external_sharing>
+外部邀请：<render external_invitation or omit if unknown because field is absent>
+协作者管理（组织维度）：<render collaborator_org_scope>
+协作者管理（权限维度）：<render collaborator_permission_scope or omit if unknown because field is absent>
+复制内容：<render copy_scope or omit if unknown because field is absent>
+创建副本 / 打印 / 下载：<render security_scope>
+评论：<render comment_scope>
+Wiki 继承限制：<render lock_state or omit if unknown because field is absent>
+
+检查边界：<render check_scope>
+```
+
+English template:
+
+```text
+Conclusion: <Not publicly accessible on the internet / A public internet link is enabled / External sharing is enabled>.
+
+Target: <title>
+URL: <url-or-token-if-url-unavailable>
+Type: <type>
+
+Current link access: <render link_access>
+External sharing: <render external_sharing>
+External invitations: <render external_invitation or omit if unknown because field is absent>
+Collaborator management by tenant: <render collaborator_org_scope>
+Collaborator management by permission: <render collaborator_permission_scope or omit if unknown because field is absent>
+Copy content: <render copy_scope or omit if unknown because field is absent>
+Create copies / print / download: <render security_scope>
+Comments: <render comment_scope>
+Wiki inheritance lock: <render lock_state or omit if unknown because field is absent>
+
+Check boundary: <render check_scope>
+```
+
+Raw evidence, only when requested:
+
+```text
+Evidence fields:
+- link_share_entity=<value>
+- external_access_entity=<value>
+- external_access=<value>
+- invite_external=<value>
+- share_entity=<value>
+- manage_collaborator_entity=<value>
+- copy_entity=<value>
+- security_entity=<value>
+- comment_entity=<value>
+- lock_switch=<value>
+```
+
+## 多目标明确列表诊断
+
+当 `target_scope=explicit_list` 时，使用此模板。该场景不执行容器递归发现；对用户提供的每个 URL / token 逐个生成 `per_target_permission_assessment`，再按风险分组聚合。权限语义和单目标、容器诊断完全复用，不新增判断模型。
+
+```text
+已完成只读权限诊断，没有做任何权限修改。
+
+一句话结论：<N> 个目标中，<risk_count> 个存在待复核权限风险；<internet_public_count> 个存在互联网公开链接候选，<external_access_count> 个允许对外分享，<unknown_count> 个无法完整判断。
+
+覆盖情况：
+- 用户提供目标：<input_target_count>；成功解析：<resolved_count>
+- 成功读取文档公共访问和协作权限设置：<permission_checked_count>；读取失败 / 不支持 / 无权限：<failed_or_unsupported_count>
+
+逐目标结果（1-10 个目标默认全部展示；超过 10 个时按 `摘要清单展开规则` 展示，并提示生成完整风险清单）：
+
+- <risk_id-or-item_id> <path-or-title> (<type>)
+  URL: <url-or-token-if-url-unavailable>
+  结论：<not_public / public_link_enabled / external_sharing_enabled / policy_review / unknown>
+  关键权限：<render link_access>; <render external_sharing>; <render security_scope>; <render comment_scope>
+  密级：<sec_label_name-or-missing-or-unknown>
+  待复核原因：<risk reason or none>
+  建议动作：<recommended action or no action>
+
+分组摘要：
+- 互联网公开链接候选：<count>；允许对外分享：<count>；公司内链接可访问 / 可编辑：<count>
+- 复制 / 下载 / 打印 / 评论待策略确认：<count>；无法判断：<count and reason summary>
+
+建议下一步：
+- 处理明确的 <risk_id>，先生成只读 dry-run。
+- 生成完整风险清单 artifact，后续可按 `risk_id`、风险分组、URL 或 `selected=true` 选择治理范围；只看权限设置时改用 `权限设置清单`。
+```
+
+## 摘要清单展开规则
+
+容器安全诊断的摘要必须兼顾可读性和可治理性。不要用固定 Top N 代替可处理清单。
+
+| 风险对象数 | 摘要默认展示 | 必须提供的下一步 |
+|------------|--------------|------------------|
+| `0` | 只展示覆盖情况、未覆盖能力和剩余限制 | 如需更细审计，可生成权限设置清单 |
+| `1-10` | 展示全部风险对象 | 可直接按 `risk_id` 生成 dry-run 或写入确认 |
+| `11-30` | 展示全部高优先级待复核对象；中 / 低优先级做分组摘要 | 生成完整风险清单 artifact，或按风险分组生成 dry-run |
+| `31-100` | 每个高优先级待复核分组展示 Top 5，附未展示数量 | 生成 Markdown / CSV / 飞书文档完整风险清单 |
+| `100+` | 只展示分组统计、Top 样例和覆盖限制，不内联长表 | 强烈建议生成结构化风险清单后再选择治理范围 |
+
+高优先级待复核对象包括：互联网公开链接、允许对外分享、允许对外分享且缺少 / 低于 policy 密级标签、公司内可编辑链接。协作者管理范围较宽默认归入中优先级待复核；只有用户 policy 明确要求严格协作者管理时才提升优先级。复制 / 下载 / 打印、评论范围在用户未提供明确 policy 时归入“待策略确认”，不要挤占高优先级清单。
+
+摘要中的每个待复核对象必须包含 `risk_id`、path/title、URL、type、owner、sec_label、风险原因、关键证据和建议动作。对同一底层文档的多个 Wiki 入口或 shortcut，必须用 URL 区分；如果建议合并治理，在建议动作里说明它们指向同一底层对象。
+
+## 审计摘要
+
+```text
+目标：<title> (<type>)
+URL：<url-or-token-if-url-unavailable>
+结论：<合规 / 待确认风险 / 无法完整判断>
+证据：
+- link_share_entity=<value>
+- external_access_entity=<value>
+- external_access=<value>
+- invite_external=<value>
+- share_entity=<value>
+- manage_collaborator_entity=<value>
+- copy_entity=<value>
+- security_entity=<value>
+- comment_entity=<value>
+- lock_switch=<value>
+- sec_label_name=<value-or-missing>
+限制：<unsupported_checks or none>
+建议动作：<read-only next step or proposed remediation>
+```
+
+## 容器安全诊断报告摘要
+
+```text
+已完成只读安全诊断，没有做任何权限修改。
+
+一句话结论：<未发现互联网公开链接 / 存在互联网公开链接候选风险>；<external_access_count> 个文档允许对外分享，<missing_label_count> 个文档缺少密级标签。建议优先复核 <top_priority_group_or_paths>。
+
+覆盖情况：
+- 当前身份可见目标：<visible_count>
+- 已成功检查文档公共访问和协作权限设置：<permission_checked_count>
+- 读取失败 / 已删除 / 无权限：<failed_count>
+- 未覆盖能力：<collaborator_list / inheritance / audit_log / view_records / none>
+
+风险分级：
+- 高优先级待复核：<internet_public_count> 个互联网公开链接候选；<external_access_count> 个允许对外分享；其中 <external_without_label_count> 个同时缺少密级标签。
+- 中优先级待复核：<tenant_link_count> 个公司内知道链接可访问 / 可编辑；<wide_share_count> 个协作者管理范围较宽。
+- 待策略确认：<security_count> 个复制 / 下载 / 打印范围待复核；<comment_count> 个评论范围待复核。
+- 无法判断：<unsupported_or_unverified_summary>。
+
+分级含义：
+- 互联网公开链接：获得链接的任何人可能访问，最高优先级。
+- 允许对外分享：外部分享能力已开启，需 owner 复核；不等于已经存在外部协作者。
+- 公司内链接可访问：不是对外公开，但组织内扩散范围较宽。
+- 复制 / 下载 / 打印 / 评论：是否需要收紧取决于业务 policy 和文档密级。
+
+高优先级待复核清单：
+> 按 `摘要清单展开规则` 展示。每个对象必须包含 `risk_id` 和 URL；缺少 URL 时展示 token / node_token 和原因。若没有高优先级对象，只展示中优先级或待策略确认分组摘要。
+
+- <risk_id> <path-or-title> (<type>)
+  URL: <url-or-token-if-url-unavailable>
+  Owner: <owner-or-unknown>
+  密级：<sec_label_name-or-missing-or-unknown>
+  待复核原因：<why high priority>
+  证据：<short user-language evidence, e.g. 对外分享=已开启；链接分享=未开启互联网公开链接>
+  建议动作：<recommended action>
+
+未完全展开：
+- 完整风险清单包含 <risk_manifest_count> 条；本摘要已展示 <shown_count> 条，未展示 <hidden_count> 条。
+- 未展示分组：<risk_group=count summary or none>
+
+建议下一步：
+- 生成完整风险清单 artifact，包含 `risk_id`、URL、owner、密级、证据字段、建议动作和 `selected` 列。
+- 基于 risk_id、风险分组、owner、路径、URL 或 artifact 中 `selected=true` 的行生成只读整改 dry-run。
+- 只针对最高优先级目标进入写入确认流程，例如关闭互联网公开链接或收紧对外分享；写入前仍需二次确认。
+- 按 owner / 密级生成复核清单。
+- 继续读取访问记录，判断低活跃高暴露。
+
+剩余限制：
+- <do not claim collaborator-list verification if unsupported>
+- <external_access_entity=open or external_access=true only means sharing outside is allowed, not that external collaborators exist>
+- <missing view_records / DLP / AI index status / audit log limitations>
+```
+
+## 可操作风险清单
+
+完整风险清单用于让用户选择后续治理范围。Markdown / CSV / 飞书文档报告都必须包含以下字段；如果某种格式无法完整展示嵌套证据，使用短文本摘要，保留 `risk_id` 和 URL。
+
+```text
+范围：<explicit_list / wiki_space / wiki_node / drive_folder> <name-or-id>
+生成时间：<timestamp>
+用途：用户可按 risk_id、priority、risk_group、owner、path、URL 或 selected=true 选择治理对象。
+
+| risk_id | priority | Path | URL | Type | Owner | sec_label | risk_group | evidence | recommended_action | current_setting | target_setting | selected | decision | status | skip_reason |
+|---------|----------|------|-----|------|-------|-----------|------------|----------|--------------------|-----------------|----------------|----------|----------|--------|-------------|
+| PG-001 | P1 | <path> | <url-or-token> | <type> | <owner-or-unknown> | <sec-label-or-missing> | <risk_group> | <short evidence> | <recommended-action> | <field=value> | <field=value-or-owner-review> | false | undecided | pending | <none-or-reason> |
+```
+
+字段规则：
+
+- `risk_id` 按 priority、risk_group、normalized path、URL、canonical token / node_token 稳定排序生成；URL 缺失时必须使用 token / node_token 作为 tie-breaker。同名、同路径、shortcut 或多个 Wiki 入口不能只靠 path 生成编号；同一次诊断中不得重复。
+- `priority` 使用 `P0`、`P1`、`P2`、`PolicyReview`、`Unknown`；面向用户展示时可译为“最高优先级 / 高优先级待复核 / 中优先级待复核 / 待策略确认 / 无法判断”。
+- `selected` 默认 `false`；用户可在 CSV / 飞书文档表格中改为 `true`，或在聊天中直接说 “处理 PG-001、PG-003”。
+- `decision` 表示用户决策：`undecided`、`keep`、`dry_run`、`confirm_write`、`skip`。
+- `status` 表示执行状态：`pending`、`dry_run_ready`、`confirmed`、`executed`、`verified`、`failed`、`skipped`。
+- `target_setting` 是建议目标状态，不代表已执行；没有明确 policy 时只能写 owner review / policy review。
+
+## 治理选择交互
+
+用户基于完整风险清单继续治理时，Agent 必须先解析选择范围，再生成只读 dry-run：
+
+```text
+可接受的用户选择：
+- 处理 PG-001、PG-003、PG-008，把互联网公开链接关闭。
+- 先处理所有 risk_group=internet_public_link，不处理 external_access_only。
+- 把 CSV / 飞书文档里 selected=true 的行生成整改 dry-run。
+- PG-003 先跳过，只处理 PG-001。
+
+Agent 必须回复：
+- 已选择对象数：<count>
+- 选择来源：<risk_id list / risk_group / selected=true / URL / path>
+- 将执行的下一步：生成 dry-run；不执行写入
+- 需要跳过或重新确认的对象：<missing risk_id / unsupported / changed_since_report / no manage_public>
+```
+
+如果用户选择来自旧报告或外部 artifact，生成 dry-run 前必须对所选目标重新读取当前权限。当前设置和报告快照不一致时，标记为 `changed_since_report`，不要直接沿用旧字段执行。
+
+## 权限设置清单
+
+```text
+范围：<explicit_list / wiki_space / wiki_node / drive_folder> <name-or-id>
+
+| Path | URL | Type | link_share_entity | external_access_entity / external_access | invite_external | share_entity | manage_collaborator_entity | copy_entity | security_entity | comment_entity | lock_switch | sec_label_name | 建议动作 | 限制 |
+|------|-----|------|-------------------|------------------------------------------|-----------------|--------------|----------------------------|-------------|-----------------|----------------|-------------|----------------|----------|------|
+| <path> | <url-or-token> | <type> | <value> | <value> | <value-or-unknown> | <value> | <value-or-unknown> | <value-or-unknown> | <value> | <value> | <value-or-unknown> | <value-or-missing> | <recommended-action> | <unsupported-or-none> |
+```
+
+## 访问复核清单
+
+```text
+范围：<wiki_space / wiki_node / drive_folder / explicit_list> <name-or-id>
+复核对象数：<count>
+
+| Owner | Path | URL | Type | 密级 | 风险标签 | 当前权限摘要 | 最近访问证据 | 建议动作 |
+|-------|------|-----|------|------|----------|--------------|--------------|----------|
+| <owner-or-unknown> | <path> | <url-or-token> | <type> | <sec-label-or-missing> | <labels> | <link/external/share/security/comment> | <uv/pv/last_view_or_unknown> | <keep / tighten / owner review / unsupported> |
+
+限制：<unsupported_checks / discovery_blockers / none>
+```
+
+## 整改 dry-run
+
+```text
+将生成整改计划，不执行写入：
+- 范围：<scope>
+- 选择来源：<risk_id list / risk_group / selected=true artifact / URL list>
+- 候选目标数：<count>
+- 计划执行命令：<command family>
+- 重新读取：已对所选目标重新读取当前权限；changed_since_report=<count>
+- 字段变更：
+  - <risk_id> <path> (<url-or-token>): <field> <old> -> <new>
+- 跳过项：<unsupported / no manage_public / unsupported type / missing policy>
+- 验证方式：执行后重新读取 <元数据 / 文档公共访问和协作权限设置>
+- 有限回滚范围：<文档公共访问和协作权限设置快照字段 / 不适用>
+
+请确认是否进入写入确认。
+```
+
+## 批量权限申请确认
+
+```text
+将逐个发起 <view / edit> 权限申请：
+- 候选目标数：<count>
+- 命令类型：drive +apply-permission
+- 风险：write；每个请求都会通知 owner
+- 执行方式：按候选列表顺序逐个调用，失败项会单独记录
+
+候选示例：
+- <risk_id> <title> (<type>, <url-or-token>)：<reason>
+
+请确认是否对上述候选目标发起权限申请。
+```
+
+## owner 转移确认
+
+```text
+将逐个转移 owner：
+- 候选目标数：<count>
+- 命令类型：drive permission.members transfer_owner
+- 风险：high-risk-write；会改变文档 owner，可能影响原 owner 权限和文档所在位置
+- 新 owner 映射：<same_new_owner / per_target_new_owner>
+- 全局新 owner：<member_id> (<member_type>)；仅当所有候选目标的新 owner 相同时展示，否则省略
+- 通知新 owner：<need_notification>
+- 原 owner 权限：<remove_old_owner=true / old_owner_perm>
+- 个人空间位置：<stay_put>
+- 执行方式：按候选列表顺序逐个调用，失败项会单独记录
+- 验证方式：执行后重新读取 metadata owner；metadata 不支持的类型标记为 partial
+- 回滚边界：不做自动回滚；如需恢复 owner，必须另起一次反向 owner 转移确认
+
+候选示例：
+- <risk_id> <title> (<type>, <url-or-token>)：当前 owner=<owner-or-unknown> -> 新 owner=<member_id> (<member_type>)
+
+请确认是否对上述候选目标转移 owner。
+```
+
+## 确认请求
+
+```text
+将执行 <operation>：
+- 目标：<risk_id> <title> (<type>, <url-or-token>)
+- 命令类型：<command family>
+- 风险：<risk_level>
+- 字段变更：
+  - <field>: <old> -> <new>
+- 验证方式：执行后重新读取 <元数据 / 文档公共访问和协作权限设置>
+- 有限回滚材料：<文档公共访问和协作权限设置快照 / 不适用>
+
+请确认是否执行。
+```
+
+## 最终摘要
+
+```text
+已完成：<read checks / writes>
+验证：<fresh read result or async permission-request approval note>
+清单状态：<risk_id status updates / not applicable>
+回滚材料：<文档公共访问和协作权限设置快照 / 不适用>
+剩余限制：<unsupported_checks / partial facts / approvals>
+```

skills/lark-drive/references/lark-drive-workflow-permission-governance.md

@@ -0,0 +1,207 @@
+# lark-drive 权限治理 Workflow
+
+Workflow id: `permission_governance`
+
+Risk / Structure: `R2` / `S2`
+
+本文实现已注册的权限治理 workflow。执行前必须先读取 [`lark-drive-workflow.md`](lark-drive-workflow.md) 和 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)，并遵循共享执行协议、Artifact Contract、Workflow Loading、认证和写入确认规则。
+
+## 适用范围
+
+当用户要求检查或治理 Drive / Docs / Wiki 资产访问权限时，使用本 workflow。典型意图包括：
+
+- 单资源公开性、外部访问、公司内链接、分享 / 复制 / 下载 / 评论设置检查。
+- 多资源、Wiki space / node、Drive folder 或个人文档库的权限风险诊断和权限设置清单。
+- 访问复核、低活跃高暴露、权限申请、owner 转移、密级标签调整、AI Agent / RAG 前置权限治理。
+- 只读整改 dry-run，或经确认后的权限收紧 / 权限申请 / owner 转移 / 密级标签更新。
+
+目标可以是明确 URL / token、小规模明确列表、Wiki space / Wiki node 或 Drive folder。容器范围必须先只读 `DISCOVER_TARGETS` 并产出覆盖摘要；这里的"所有文档"只表示当前身份在确认范围内可枚举到的文档。任何写入都必须再次确认。
+
+单目标轻量路径：用户只问“是否对外公开 / 外部可访问 / 公司内链接可见”且目标是单个明确 URL / token 时，设置 `intent=public_exposure_check`、`target_scope=single_resource`，走 `PARSE_INTENT -> TARGET_INSPECT -> FACT_READ -> RISK_ASSESS -> DONE`。该路径是 `target_count=1` 的轻量输出模式，不是独立判断逻辑；不执行 `DISCOVER_TARGETS`、不生成 `risk_manifest` / `risk_id`，只输出结论、权限含义、检查边界和必要下一步。
+
+## Target Set Evaluation
+
+本 workflow 不按“单篇 / 多篇 / 容器”复制权限判断逻辑。所有范围先归一为 target set，再对每个可审计目标生成 `per_target_permission_assessment`，最后按目标数量和风险分组聚合输出。
+
+| target_scope | Target Collection | Output Mode |
+|--------------|-------------------|-------------|
+| `single_resource` | 直接解析一个 URL / token | `target_count=1` 时轻量渲染；不生成 `risk_manifest` |
+| `explicit_list` | 用户给出的多个 URL / token 逐个 inspect / normalize | 逐目标渲染摘要；需要后续治理时生成稳定 `risk_id` |
+| `wiki_space` / `wiki_node` / `drive_folder` | 先只读递归发现，再归一化为 `discovered_targets` | 输出覆盖情况、风险分组、可定位待复核对象和 artifact / dry-run CTA |
+
+特殊的是目标收集和输出聚合，不是权限语义。`link_access`、`external_sharing`、`copy_scope`、`security_scope`、`comment_scope`、`sec_label`、`check_scope` 等语义字段必须在单目标、多目标明确列表和容器发现目标之间复用。
+
+## 非目标
+
+本 workflow 不处理：
+
+- 目录组织、迁移、归档或清理；这类需求应使用知识整理 workflow。
+- 内容审查、过期内容判断或知识质量评分。
+- backup owner 补充、部门 / 项目负责人绑定、协作者创建 / 撤销、成员列表审计；本 workflow 只支持把 owner 转移给每个目标明确指定的新 owner，不建模 backup owner 或负责人绑定关系。
+- 文件夹自身公开权限审计或修复。`drive permission.public get` / `patch` 不支持 `type=folder`；必须记录到 `unsupported_checks`，然后继续读取文件夹下其他支持的文档事实。
+- 当前身份无法枚举到的不可见文档的完整发现；只能处理已发现目标，或用户显式提供的 URL / token。
+- 未按范围确认的批量写入。
+
+不要声称已完成协作者列表验证：当前 CLI surface 没有 `permission.members list` shortcut。
+
+## Progressive Load Map
+
+本表只规定每个 state 需要加载的额外上下文；命令可用范围以 `Command Map` 为准。需要拼装具体 `lark-cli` 命令时，再按需读取 [`lark-drive-workflow-permission-governance-commands.md`](lark-drive-workflow-permission-governance-commands.md)。
+
+| State | Required Reference |
+|-------|--------------------|
+| `PARSE_INTENT` | 本文件、[`lark-drive-workflow.md`](lark-drive-workflow.md)、[`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) |
+| `TARGET_INSPECT` | [`lark-drive-inspect.md`](lark-drive-inspect.md) |
+| `DISCOVER_TARGETS` | 容器范围时读取 [`../../lark-wiki/references/lark-wiki-node-list.md`](../../lark-wiki/references/lark-wiki-node-list.md) 或 [`lark-drive-files-list.md`](lark-drive-files-list.md) |
+| `FACT_READ` | `lark-cli schema drive.metas.batch_query`；涉及公开权限时再读取 `lark-cli schema drive.permission.public.get`；涉及活跃度、访问复核或生命周期判断时再读取 `lark-cli schema drive.file.statistics.get` 和 `lark-cli schema drive.file.view_records.list` |
+| `RISK_ASSESS` | 本文件的 `Risk Classification` |
+| `EXEC_CONFIRM` | 只为用户选择的动作读取 [`lark-drive-apply-permission.md`](lark-drive-apply-permission.md)、[`lark-drive-secure-label.md`](lark-drive-secure-label.md)，或 `lark-cli schema drive.permission.public.patch` / `lark-cli schema drive.permission.members.transfer_owner`；需要确认模板时读取 [`lark-drive-workflow-permission-governance-outputs.md`](lark-drive-workflow-permission-governance-outputs.md) |
+| `EXECUTE` | 复用 `EXEC_CONFIRM` 已加载且已确认的写命令上下文 |
+| `VERIFY` | 复用 `FACT_READ` 阶段使用的 read schemas |
+
+## Runtime State Extension
+
+本 workflow 在共享 `Artifact Contract` 基础上扩展以下字段组：
+
+| Group | Fields | Meaning |
+|-------|--------|---------|
+| Scope | `intent`, `target_scope`, `targets`, `discovered_targets`, `coverage_summary`, `discovery_blockers` | 记录用户意图、确认范围、直接目标、容器发现目标和未覆盖范围 |
+| Facts | `metadata_facts`, `public_permission_facts`, `activity_facts`, `manage_public_auth` | 记录 metadata、公共访问与协作权限、访问证据，以及写前 `manage_public` 校验 |
+| Assessment | `per_target_permission_assessments`, `risk_findings`, `unsupported_checks` | 记录逐目标语义判断、带 `risk_id` / URL / owner / sec_label / evidence / action 的风险发现，以及无法执行的检查 |
+| Governance | `risk_manifest`, `selected_risk_items`, `access_review_items`, `permission_request_candidates`, `owner_transfer_candidates` | 支持用户按 `risk_id`、风险分组、owner、路径、URL 或 artifact `selected=true` 选择治理范围，并记录 owner 转移候选 |
+| Execution | `remediation_plan`, `owner_transfer_plan`, `public_permission_snapshots` | 记录 dry-run / 已确认整改计划、owner 转移计划、字段 diff、验证方式和 public-permission 有限回滚快照 |
+
+## Execution State Machine
+
+| State | Protocol Step | Agent MUST Do | User-Facing Output | wait_for_user | Next State |
+|-------|---------------|---------------|--------------------|---------------|------------|
+| `PARSE_INTENT` | `route` / `scope` | 解析 intent、target scope、desired policy，以及只读审计、单目标公开性判断、权限申请、owner 转移还是修复模式；单目标公开性判断设置 `intent=public_exposure_check`、`target_scope=single_resource` | 范围确认；如果缺少目标、新 owner 或期望动作，只问一个澄清问题 | 缺少 target / new owner / action，或容器范围需要用户确认时为 `true` | `TARGET_INSPECT` |
+| `TARGET_INSPECT` | `scope` | 解析单资源、明确列表、Wiki space / node、Drive folder；保留原始 URL、scope type、canonical token/type | 目标范围表，包含 scope、title/type/token status | 除非解析失败，否则为 `false` | `DISCOVER_TARGETS` or `FACT_READ` |
+| `DISCOVER_TARGETS` | `scope` / `read` | 对 Wiki space / node 或 Drive folder 递归只读枚举，归一化为 `discovered_targets`；记录 `discovery_blockers` | 发现进度和覆盖摘要；不展示内部 cursor/token，除非用户要求 | 除非发现范围无法确认或全部被阻断，否则为 `false` | `FACT_READ` |
+| `FACT_READ` | `read` | 对直接目标或 `discovered_targets` 执行 `drive metas batch_query`；对支持的非 folder 目标执行 `drive permission.public get`；当 `intent=public_exposure_check` 且 `target_scope=single_resource` 时，可复用 `drive +inspect` 返回的 title / URL / type，只补读文档公共访问和协作权限设置；在用户要求活跃度 / 访问复核 / 生命周期判断时读取访问统计和访问记录 | 权限事实摘要、coverage summary、activity facts 和 unsupported checks | 除非所有目标都被 auth 阻断，否则为 `false` | `RISK_ASSESS` |
+| `RISK_ASSESS` | `assess/plan` | 对每个可审计目标生成 `per_target_permission_assessment` 并分类证据；如用户提供 policy，则对照 policy；`public_exposure_check + single_resource` 只渲染单目标结论，不生成 `risk_id`；owner 转移路径生成 `owner_transfer_candidates` / `owner_transfer_plan`；治理路径构建可定位风险清单、访问复核清单、dry-run 整改计划或候选修复计划，完整清单必须生成稳定 `risk_id` | 带 priority、URL、risk_id、owner、sec_label 的 findings、confidence、review items、建议动作和下一步 CTA；单目标公开性判断只输出结论和关键字段 | 治理路径为 `true`，单目标公开性判断为 `false` | `EXEC_CONFIRM` or `DONE` |
+| `EXEC_CONFIRM` | `confirm` | 展示准确写入范围、command family、target count、risk、verification method | 确认请求 | `true` | `EXECUTE` or `DONE` |
+| `EXECUTE` | `execute` | 只执行 `Command Map` 中已确认的写入 | 进度 / 结果摘要 | 除非被阻断，否则为 `false` | `VERIFY` |
+| `VERIFY` | `verify` | 重新执行支持的读取，并与目标状态对比 | 验证表和剩余缺口 | `false` | `DONE` |
+| `DONE` | `done` | 停止 | 最终回复，包含完成事项、验证结果和剩余风险 | `false` | End |
+
+## Command Map
+
+本 workflow 只能使用以下 command families：
+
+| State | Allowed Command Families | Purpose |
+|-------|--------------------------|---------|
+| `TARGET_INSPECT` | `drive +inspect` | 解析 URL、type、canonical token、title 和 wiki unwrap data |
+| `DISCOVER_TARGETS` | `wiki +node-list` | 递归发现 Wiki space / node 下当前身份可见的节点 |
+| `DISCOVER_TARGETS` | `drive files list` | 递归发现 Drive folder 下当前身份可见的文件和子文件夹 |
+| `FACT_READ` | `drive metas batch_query` | 读取 title、URL、owner 和 secure-label metadata |
+| `FACT_READ` | `drive permission.public get` | 读取支持类型的文档公共访问和协作权限设置，包括链接分享、对外分享、协作者管理、复制内容、创建副本、打印、下载和评论 |
+| `FACT_READ` | `drive file.statistics get` | 在用户要求活跃度、闲置暴露、生命周期或访问复核时读取文件访问统计 |
+| `FACT_READ` | `drive file.view_records list` | 在用户要求最近访问人、访问复核或低活跃证据时读取访问记录 |
+| `EXEC_CONFIRM` | `drive +secure-label-list` | 提议 label update 前解析可用 secure-label IDs |
+| `EXEC_CONFIRM` | `drive permission.members auth` | 文档公共访问和协作权限设置修改前检查 `action=manage_public` |
+| `EXEC_CONFIRM` | `lark-cli schema drive.permission.members.transfer_owner` | owner 转移前读取当前字段、支持类型和高风险写入门禁 |
+| `EXECUTE` | `drive +apply-permission` | 向 owner 提交 view/edit access request；只允许单目标、小列表或已明确确认的候选列表逐个执行 |
+| `EXECUTE` | `drive permission.public patch` | 修改已确认的 public/link settings；必须传 `--yes` |
+| `EXECUTE` | `drive permission.members transfer_owner` | 转移已确认目标的 owner；必须传 `--yes` |
+| `EXECUTE` | `drive +secure-label-update` | 设置已确认的 secure-label ID |
+| `VERIFY` | `drive metas batch_query`, `drive permission.public get` | 验证支持的 metadata，包括 owner、secure-label 和文档公共访问与协作权限设置变更；权限申请只能表述为已发起 |
+
+## Command Patterns
+
+本入口不内联命令样例。需要拼装具体 `lark-cli` 命令时，按当前 state 读取 [`lark-drive-workflow-permission-governance-commands.md`](lark-drive-workflow-permission-governance-commands.md)。命令是否允许执行仍以 `Command Map` 和写入规则为准。
+
+## Discovery Rules
+
+容器范围只能先做只读发现和覆盖摘要，不能在发现阶段执行权限申请、权限 patch 或密级更新。
+
+通用规则：
+
+1. "所有文档"只表示当前身份在确认范围内可枚举到的文档。不可见、无权限、API 不返回或工具预算不足的部分必须进入 `discovery_blockers` 或 `unsupported_checks`。
+2. 发现阶段必须生成稳定 `path`。不要只保存 title；同名文档必须能通过 path 或 token 区分。
+3. 只把 `drive.permission.public.get` 当前 schema 支持的类型加入公开权限可审计目标。已知支持包括 `doc`、`sheet`、`file`、`wiki`、`bitable`、`docx`、`mindnote`、`minutes`、`slides`；未来新增类型以运行时 schema 为准。
+4. `minutes` 只能作为 `partial_public_permission` 目标：可读取 / 修改公开权限和 owner 转移能力以运行时 schema 为准，但 `drive metas batch_query` 当前不支持 `minutes`，URL、owner、密级等 metadata 可能进入 `unsupported_checks`。
+5. `folder` 只作为递归容器，不执行 `permission.public get` / `patch`。如果用户明确要求 owner 转移且 schema 支持 `folder`，必须按 owner-transfer 写入规则单独确认。`shortcut`、`catalog` 或缺少 stable token/type 的条目必须记录为 unsupported，除非后续 API 明确解析出支持目标。
+6. 对大范围目标输出进度时，只展示已扫描容器数、已发现目标数、已审计目标数、剩余队列或 blocker；不要默认展示内部 page token / cursor。
+
+Wiki space / node 发现：
+
+1. `/wiki/space/<space_id>` 直接解析为 `target_scope=wiki_space`。不要因为 `drive +inspect` 对该 URL 返回 not found 就停止。
+2. 用 `wiki +node-list --space-id <space_id>` 读取根节点；当节点 `has_child=true` 时，用该节点的 `node_token` 继续递归读取子节点。
+3. Wiki 节点必须同时保留 `node_token`、`obj_token` 和 `obj_type`。权限读取优先用 `type=wiki` + `node_token` 表达 Wiki 节点权限；元数据补充可使用 `obj_type` + `obj_token`。
+4. 如果节点只有 `obj_token` / `obj_type`，但无法确认 Wiki 节点权限 token，保留该目标为 partial，并在 `unsupported_checks` 中说明只能读取底层对象或无法完整判断 Wiki 节点权限。
+
+Drive folder 发现：
+
+1. `/drive/folder/<folder_token>` 解析为 `target_scope=drive_folder`。文件夹自身公开权限不支持；继续枚举其子文档。
+2. 按 [`lark-drive-files-list.md`](lark-drive-files-list.md) 递归处理 `data.files`、`has_more` 和 `next_page_token`。不要把第一页数量当作完整范围。
+3. 只对返回项中的 `folder` 继续递归；对子文档按 `type + token` 归一化为 `discovered_targets`。
+4. 如果某个目录分页失败、无 continuation token、权限不足或 API 报错，只阻断该目录分支，并在 `discovery_blockers` 中记录；继续处理其他可枚举分支。
+
+## Fact Read Rules
+
+1. `drive metas batch_query` 单次最多 200 个 `request_docs`；当 `targets` 或 `discovered_targets` 超过 200 个时，必须分批读取并合并结果。
+2. `drive permission.public get` 没有批量读取接口；对支持目标逐个读取。单个目标失败时记录 `unsupported_checks` 或 `partial`，不要阻断其他目标。
+3. 对 Wiki 发现目标，公开权限读取优先使用 `type=wiki` + `node_token`；metadata 可使用 `obj_type` + `obj_token` 补充 title、owner、URL 和 `sec_label_name`。
+4. 当 intent 是 `list_permission_settings` 时，只输出权限设置清单和覆盖限制，不主动生成修复计划。
+5. 单目标、多目标明确列表和容器发现目标都必须复用同一套逐目标事实读取与语义归一逻辑；差异只体现在目标来源、coverage summary 和输出聚合。
+6. `permission_public` 用户可见含义是“文档公共访问和协作权限设置”，语义以官方 OpenAPI 字段说明为准，同时兼容当前 CLI schema 返回的字段：优先使用 `external_access_entity`，缺失时才用 `external_access` boolean 映射为 `open` / `closed`；`manage_collaborator_entity`、`copy_entity`、`lock_switch` 等字段缺失时标记为 unknown，不要伪造；未识别字段保留在 raw evidence / partial note 中。
+7. `drive file.statistics get` 和 `drive file.view_records list` 只在用户要求最近访问、活跃度、闲置暴露、访问复核，或用户提供的 policy 明确依赖活跃度时执行；不要为普通权限审计默认读取访问记录。
+8. 访问统计 / 访问记录当前只对 `doc`、`docx`、`sheet`、`bitable`、`mindnote`、`wiki`、`file` 作为支持类型处理。其他类型必须进入 `unsupported_checks`，不能推断活跃度。
+9. `view_records` 是访问证据，不是权限列表。没有返回访问记录只能表述为“未获得最近访问证据”或“低活跃候选”，不能表述为“无人有权限”。
+
+## Risk Classification
+
+风险标签只能作为 evidence labels。除非用户提供明确 policy，否则不要表述为绝对违规、已泄露或已外部访问。
+
+默认优先级面向用户决策，而不是制造告警感：
+
+- `P0`：`link_share_entity=anyone_readable/anyone_editable`，互联网公开链接候选风险。
+- `P1`：`external_access_entity=open` / `external_access=true`、关联组织访问、公司内链接可编辑，或外部分享且缺少 / 低于 policy 密级标签。
+- `P2`：公司内知道链接可读、协作者管理范围较宽。
+- `PolicyReview`：复制、创建副本、打印、下载、评论等依赖 policy 的设置；没有明确 policy 时不要称为高风险。
+- `Unknown`：读取失败、已删除、无权限、API 不支持、协作者名单 / 继承链 / DLP / AI 索引 / 审计日志未覆盖。
+
+每个可审计目标都必须先归一化为 `per_target_permission_assessment`，再按 [`lark-drive-workflow-permission-governance-outputs.md`](lark-drive-workflow-permission-governance-outputs.md) 的 `Semantic Rendering` 渲染。`public_exposure_check` 只是 `target_count=1` 的轻量渲染模式；它和多目标、容器诊断复用同一套语义字段与风险分类。该判断只覆盖当前文档公共访问和协作权限设置，不审计协作者名单、历史权限变更、完整继承链或审计日志。
+
+`AI 检索暴露候选风险` 只是基于权限和标签的代理标签。除非另有工具明确返回索引状态，否则不要声称某个文档已经被 Agent、Copilot 或 RAG 索引。
+
+## 写入规则
+
+- 文档公共访问和协作权限设置修改（`drive permission.public patch`）属于高风险写入。请求确认前，必须展示 target title、token、current setting、desired setting 和准确 field changes。
+- 如果 `manage_public_auth.auth_result=false`，禁止 patch。告诉用户需要具备 manage-public 权限的用户，或由 owner 操作。
+- `drive permission.public get` 只用于 `drive +inspect` 或 `DISCOVER_TARGETS` 可解析且运行时 schema 支持的目标类型；类型集合不要硬编码，执行时以 `lark-cli schema drive.permission.public.get` 为准。
+- 不要 patch 已解析类型不支持的字段。对于 wiki 目标，必须省略 schema 明确标注为 wiki 不支持的字段。
+- 不要在同一个写入确认中合并密级标签更新和文档公共访问与协作权限设置修改；必须分别确认。
+- `drive +apply-permission` 默认不批量执行；每次调用都会向 owner 发送通知。
+- `permission_request_candidates` 可以来自用户直接提供的目标、明确列表或容器发现目标；只要能构造 token、type、权限类型和申请理由，就可以进入候选。不要因为目标不在 `discovered_targets` 中而拒绝单目标 / 小列表权限申请。
+- 容器范围内的"统一申请权限"必须先产出 `permission_request_candidates`。未展示候选目标、数量、权限类型和 owner 通知影响前，禁止调用 `drive +apply-permission`。
+- 用户显式确认批量权限申请后，也必须逐个目标顺序调用 `drive +apply-permission`，并在结果中区分已发起申请、失败、无法构造申请请求和未发现目标。
+- `drive permission.members transfer_owner` 属于 owner 转移高风险写入。必须先确认目标、当前 owner、新 owner 的 `member_id` / `member_type`、`need_notification`、`remove_old_owner`、`old_owner_perm`、`stay_put`、执行顺序和验证方式；不能只凭姓名猜测新 owner。
+- owner 转移没有 `permission.members auth` 的等价 precheck。执行前只能用 schema 和当前 metadata 做计划，执行后必须用 `drive metas batch_query` fresh read 验证 owner；metadata 不支持的类型必须把验证标记为 partial。
+- 批量 owner 转移必须逐个顺序执行；失败项进入结果清单，不要重复执行已成功目标。`remove_old_owner=true` 或 `old_owner_perm` 降权必须单独在确认中高亮。
+- 用户要求“生成整改方案 / dry-run / 先看看会改什么”时，只生成 `remediation_plan`，不执行任何写命令。dry-run 必须包含 target count、field changes、跳过原因、验证方式和有限回滚范围。
+- 用户基于完整风险清单选择对象时，必须先解析 `risk_id`、风险分组、URL 或 artifact 中 `selected=true` 的行，生成 `selected_risk_items`。无法匹配到当前 `risk_manifest` 的选择必须要求用户重新确认或重新读取清单。
+- 针对 `selected_risk_items` 生成 dry-run 前，必须重新读取所选目标的 `drive permission.public get`；如果当前设置和清单快照不同，标记为 `changed_since_report` 并跳过或要求用户确认更新后的计划。
+- 执行 `drive permission.public patch` 前，必须把当前 `public_permission_facts` 中会被改动的字段保存为 `public_permission_snapshots`。该快照只用于文档公共访问和协作权限设置字段的有限回滚说明，不覆盖协作者、owner、继承权限或密级标签。
+- 如果用户要求批量收紧权限，必须按风险分层和目标顺序逐个执行；失败项进入结果清单，不要因为单个失败而重复执行已成功目标。
+- 遇到 secure-label downgrade error `1063013` 时，停止重试，并告诉用户需要在文档 UI 中完成审批。
+
+## 未来扩展边界
+
+以下能力已有部分 CLI surface 或用户价值，但不要在当前 workflow 中作为可执行分支直接调用：
+
+- `drive permission.members create` 可创建协作者权限，但当前 workflow 不做协作者 grant / update / revoke；未来需要单独定义授权对象解析、最小权限、确认模板和验证方式。
+- backup owner、部门 / 项目负责人绑定没有当前 workflow 可执行写入面；如用户要落地为 owner 转移，必须先给出明确目标和新 owner，并走本 workflow 的 owner-transfer 确认。
+- `wiki +member-list` 可作为 Wiki space 成员治理的读侧事实来源；当前 workflow 只治理文档 / 节点 / 文件夹下可发现文档的权限，不做 space member governance。
+- 当前 CLI 没有 `permission.members list`、完整继承链、DLP 扫描、AI 索引状态、审计日志和跨平台权限事实。遇到这些需求必须记录为 `unsupported_checks` 或建议新增独立 workflow。
+
+## 输出策略
+
+- 默认 summary-first：单目标输出简短审计摘要；多目标明确列表输出逐目标摘要；容器目标输出安全诊断报告摘要，不堆叠字段计数。
+- 单目标 `public_exposure_check` 按 outputs 的 `Semantic Rendering` 渲染 `per_target_permission_assessment`，输出用户语言结论和检查边界；默认不展示底层字段名、风险清单或整改 CTA。
+- 容器安全诊断必须包含一句话结论、覆盖情况、风险分级、可定位待复核对象、建议下一步和剩余限制。
+- 待复核对象必须包含稳定 `risk_id`、path/title、URL、type、owner、sec_label、风险原因、证据和建议动作；缺少 URL 时展示 token / node_token 和原因。
+- 容器摘要按规模渐进披露，不能固定 Top N；未完全展开时必须说明完整清单总数，并给出生成 artifact / dry-run / owner 复核清单等 CTA。
+- 面向用户优先使用业务语言和“候选风险 / 待复核 / 待策略确认”；底层字段只作为证据。完整模板按需读取 [`lark-drive-workflow-permission-governance-outputs.md`](lark-drive-workflow-permission-governance-outputs.md)。
+- 不要默认创建文件、飞书文档或长表格；最终回复必须包含已完成事项、验证结果和剩余限制。异步权限申请审批只能表述为“已发起申请”。

skills/lark-drive/references/lark-drive-workflow.md

@@ -0,0 +1,130 @@
+# lark-drive Workflow 总框架
+
+本文是 `lark-drive` workflow 总框架的运行协议和注册表。它面向 AI Agent 执行，只负责路由已纳入本总框架的 workflow。
+
+`Workflow Registry` 是本总框架的唯一注册来源。未命中 registry 的请求必须按“未注册 workflow 处理”执行，不要按已有 workflow 类推扩展。
+
+## 必读上下文
+
+执行本总框架内的 workflow 前，必须先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+下游 reference 只能按需逐步加载。不要因为命中本总框架，就预加载所有 workflow 文件或相关 skill。
+
+## 能力边界
+
+`lark-drive` workflow 总框架以 `lark-drive` 作为 Drive / Docs / Wiki 资产编排的总入口。其他领域 skill 只有在已纳入本总框架的 workflow 明确需要时，才作为辅助能力加载。
+
+| Layer | Owns | Must Not Own |
+|-------|------|--------------|
+| `lark-drive/SKILL.md` | 用户意图到具体 workflow entry 的短路由 | 长流程逻辑、未注册场景 |
+| `lark-drive-workflow.md` | 共享运行协议、Artifact Contract、Workflow Registry、加载规则 | 非运行时背景说明、宽泛路线图、场景专项执行细节 |
+| Registered workflow file | 场景范围、状态机、Command Map、确认门槛、验证规则 | 其他场景、隐藏写入、未被 CLI/API 支持的能力声明 |
+
+## 执行协议
+
+每个已纳入本总框架的 workflow 必须遵循同一条执行骨架：
+
+```text
+route -> scope -> read -> assess/plan -> confirm -> execute -> verify -> done
+```
+
+运行规则：
+
+1. 在读取或写入资产前，先把用户意图解析到唯一一个已纳入本总框架的 workflow。
+2. 在昂贵读取或写入规划前，先解析并确认 `target_scope`。
+3. 事实必须来自可执行 CLI 命令或被引用 skill；不要只凭目录结构推断治理结论。
+4. 无法执行的检查必须记录到 `unsupported_checks`，不能静默省略。
+5. 写入前必须产出计划。每一次写入都需要用户对准确范围和 command family 显式确认。
+6. CLI/API 支持验证时，写入后必须用 fresh read 验证。
+7. 结束时进入 `done`，返回已完成事项、验证结果和剩余限制。不要把尚未完成的外部审批描述成已完成。
+
+## Artifact Contract
+
+每个已纳入本总框架的 workflow 必须维护以下内部字段：
+
+| Field | Meaning |
+|-------|---------|
+| `workflow_id` | 本总框架注册的 workflow 名称，例如 `permission_governance` |
+| `current_state` | 当前 workflow 状态 |
+| `target_scope` | 已确认的目标范围和用户原始输入 |
+| `identity` | 当前身份和执行视角，通常为 `user` |
+| `facts` | 从 CLI 读取或引用 skill 获取的证据 |
+| `plan_items` | 候选动作；每项包含 command family、target、risk、verification method |
+| `unsupported_checks` | 因 CLI/API 覆盖、目标类型、认证或范围限制而无法执行的检查 |
+| `partial` | 结果是否不完整，以及不完整原因 |
+| `execution_results` | 已确认写入的执行结果 |
+| `verification_results` | fresh read 验证结果，或明确的异步审批限制 |
+
+用户可见输出默认使用简洁 chat summary。只有在用户要求、结果过大不适合聊天展示，或当前 workflow 明确要求共享产物时，才创建本地文件或飞书文档。
+
+## Workflow Entry Contract
+
+每个已纳入本总框架的 workflow entry file 必须让 Agent 能直接判断和执行：
+
+- 何时进入该 workflow，以及哪些需求不属于该 workflow；
+- 如何映射到共享执行骨架的 state machine；
+- 当前 state 需要按需加载哪些 reference；
+- 哪些 command family 可用，以及读写风险边界；
+- 写入前如何确认，写入后如何验证；
+- 最终回复必须包含哪些字段，或使用哪些 output templates。
+
+每个纳入本总框架的 workflow 默认从一个独立 reference 文件开始。只有当写入、回滚或验证流程复杂到影响可读性时，才继续拆 phase 文件。
+
+## Risk / Structure Gate
+
+每个纳入本总框架的 workflow 都必须同时声明 `Risk Level` 和 `Structure Level`。风险等级决定安全门槛；结构等级决定文件拆分。高风险写入不等于必须拆 phase。
+
+Risk Level：
+
+| Level | Meaning | Runtime Requirement |
+|-------|---------|---------------------|
+| `R0` | read-only：只读发现、分析、报告 | 记录事实来源、`unsupported_checks` 和 `partial` 原因 |
+| `R1` | low-risk write：创建草稿、生成临时产物等低风险写入 | 写前说明范围，写后返回结果链接或标识 |
+| `R2` | high-risk write：权限变更、批量移动、标签修改等高风险写入 | 写前计划、准确 diff、用户显式确认、fresh read 验证 |
+| `R3` | destructive / recovery-sensitive write：删除、自动归档、双向同步、rollback cleanup | 恢复边界、执行日志、分批策略、失败停止条件和单独确认 |
+
+Structure Level：
+
+| Level | File Shape | When To Use |
+|-------|------------|-------------|
+| `S1` | compact entry only | 只读、轻量审计、简单计划，无复杂写入 |
+| `S2` | entry + optional `commands` / `outputs` / `artifacts` references | 有命令样例、输出模板、少量高风险写入，但状态链可集中表达 |
+| `S3` | entry + phase files + optional shared references | 多阶段写入、复杂验证、恢复 / rollback、长任务或分批执行 |
+
+升级规则：
+
+1. 新 workflow 默认从 `S1` 开始。
+2. Entry file 超过约 300 行时，优先拆 `commands`、`outputs` 或 `artifacts` reference。
+3. 只有执行、验证、恢复或 rollback 状态链复杂到影响可读性时，才升级到 `S3` phase files。
+4. 垂直业务包优先作为已有 workflow 的 recipe / policy / template，不默认新增独立 workflow。
+5. 已有样板：`permission_governance` 是 `R2/S2`；已发布的独立 `knowledge_organize` 是 `R2-R3/S3`，当前不作为本总框架 registry entry。
+
+## 加载与拆分边界
+
+- 每个纳入本总框架的场景默认只保留一个紧凑 workflow entry file。
+- 不为未注册或未来场景创建占位 reference / registry entry。
+- 只有 workflow 已经具备可执行规则时，才允许作为本总框架 workflow 出现在 `SKILL.md` 并加入 `Workflow Registry`。
+- 多文件 phase 拆分只用于执行、回滚或验证流程复杂到影响可读性的 `S3` 场景。
+
+## Workflow Registry
+
+| Workflow | Status | Risk | Structure | Entry File | Trigger |
+|----------|--------|------|-----------|------------|---------|
+| `permission_governance` | Registered | `R2` | `S2` | [`lark-drive-workflow-permission-governance.md`](lark-drive-workflow-permission-governance.md) | 权限审计、公开链接/外部访问、复制/下载/评论/分享设置、权限申请、owner 转移 / 批量 owner 转移、密级标签调整 |
+
+## Workflow Loading
+
+当用户意图匹配到本总框架已注册 workflow 时：
+
+1. 先读取本总框架文件。
+2. 只读取 `Workflow Registry` 中命中的 entry file。
+3. 按该 workflow 的 progressive load map 继续加载额外 reference。
+4. 除非用户改变意图，或当前 workflow 明确路由到其他 workflow，否则不要读取其他 workflow 文件。
+
+## 未注册 workflow 处理
+
+`Workflow Registry` 是本总框架的唯一注册来源。用户请求未列入 registry 的 workflow 或组合型治理场景时：
+
+1. 明确说明该需求暂无纳入本总框架的 `lark-drive` workflow。
+2. 只在不新增本总框架 workflow 行为的前提下，将请求收窄为现有 skill / CLI 可执行的原子操作。
+3. 不要类比本总框架任何已注册 workflow 新增 state machine、artifact shape、风险分类、写入行为或验证结论。

skills/lark-slides/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-slides
 version: 1.0.0
-description: "飞书幻灯片：创建和编辑幻灯片。创建演示文稿、读取幻灯片内容、管理幻灯片页面（创建、删除、读取、局部替换）。当用户需要创建或编辑幻灯片、读取或修改单个页面时使用。当用户给出 doubao.com 的 /slides/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。不负责：云文档内容编辑（走 lark-doc）、云文档里的独立画板对象（走 lark-whiteboard，注意 slide 内嵌的流程图/架构图仍属本 skill）、上传或下载普通文件（走 lark-drive）。"
+description: "飞书幻灯片：创建和编辑幻灯片。创建演示文稿、读取幻灯片内容、管理幻灯片页面（创建、删除、读取、局部替换）。当用户需要创建或编辑幻灯片、读取或修改单个页面时使用。当用户给出 doubao.com 的 /slides/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。不负责：本地 `.pptx` / `.pdf` 导入为 slides（走 `lark-drive` 的 `drive +import --type slides`）、云文档内容编辑（走 lark-doc）、云文档里的独立画板对象（走 lark-whiteboard，注意 slide 内嵌的流程图/架构图仍属本 skill）、上传或下载普通文件（走 lark-drive）。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -14,39 +14,33 @@ metadata:
 
 | 用户需求 | 优先动作 | 关键文档 / 命令 |
 |----------|----------|-----------------|
-| 新建 PPT | 先规划 `slide_plan.json`，再按复杂度选择一步或两步创建 | `planning-layer.md`、`visual-planning.md`、`asset-planning.md`、`slides +create` |
-| 大幅改写页面 | 先回读现有 XML，写入新 plan，再替换或重建相关页面 | `xml_presentations.get`、`+replace-slide`、`lark-slides-edit-workflows.md` |
+| 用户提供 PDF/PPTX/slides 材料并要求生成或改写 PPT | 必须先导入/回读材料，并以导入后的 presentation 作为目标底稿二次创作；即使材料“只作为模板/视觉线索”，也要在导入后的 presentation 内替换内容模块 | `drive +import --type slides`、`planning-layer.md`、`asset-planning.md` |
+| 新建 PPT | 仅在没有用户提供可导入材料、用户明确要求另建，或导入失败/回读失败时，先解析并盘点用户附件，规划 `slide_plan.json`，再按复杂度创建 | `planning-layer.md`、`visual-planning.md`、`asset-planning.md`、`slides +create` |
+| 已有 PPT 大幅改写 | 多页整页重建用 `+replace-pages`，单页局部编辑用 `+replace-slide` | `xml_presentations.get`、`lark-slides-replace-pages.md`、`lark-slides-edit-workflows.md` |
 | 编辑单个标题、文本块、图片或局部元素 | 优先块级替换/插入，不改页序 | `slides +replace-slide`、`lark-slides-replace-slide.md` |
 | 读取或分析已有 PPT | 解析 slides/wiki token，回读全文或单页 XML，保存 `xml_presentation_id`、`slide_id`、`revision_id` | `xml_presentations.get`、`xml_presentation.slide.get` |
+| 获取幻灯片页面截图 | 用 `slide_id` 或页号指定页面 | `slides +screenshot`、`lark-slides-screenshot.md` |
 | 上传或使用图片 | 先上传为 `file_token`，禁止直接写 http(s) 外链 | `slides +media-upload`，或 `+create --slides` 的 `@./path` 占位符 |
 | 在 slide 中绘制柱/条/折线/面积/雷达/饼等有数据序列的图表 | 使用原生 `<chart>` 元素 | `xml-schema-quick-ref.md` |
 | 在 slide 中绘制流程图、时序图、架构图、散点图、漏斗图或装饰图案 | 必须先用 Read 工具读取参考文档，再生成 `<whiteboard>` 元素 | [`lark-slides-whiteboard.md`](references/lark-slides-whiteboard.md) |
 | 使用语义图标 | 先检索 IconPark，再写 `<icon iconType="...">` | `iconpark_tool.py search → resolve`、`iconpark.md` |
-| 用户提到模板、主题、版式 | 先检索模板，再摘要，必要时裁切骨架 | `template_tool.py search → summarize → extract` |
+| 用户提到模板、主题、版式但没有提供本地/在线模板材料 | 先检索内置模板，再摘要，必要时裁切骨架 | `template_tool.py search → summarize → extract` |
 | 创建失败、空白页、3350001、布局异常 | 先回读状态，再按排障清单修复，不假设原操作原子成功 | `troubleshooting.md`、`validation-checklist.md` |
 
 **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，认证、权限和全局参数均以 lark-shared 为准。**
 
 **CRITICAL — 生成任何 XML 之前，MUST 先用 Read 工具读取 [xml-schema-quick-ref.md](references/xml-schema-quick-ref.md)，禁止凭记忆猜测 XML 结构。**
 
-**CRITICAL — 新建演示文稿或大幅改写页面时，MUST 先生成 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`，再生成 XML。先创建对应目录，规划层规则和中间产物生命周期见 [planning-layer.md](references/planning-layer.md)。仅替换一个标题、插入一个块等小型已有页编辑可豁免。**
+**CRITICAL — 新建演示文稿或大幅改写页面时，MUST 先生成 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`，再生成 XML。先创建对应目录；规划层、素材处理层、视觉规划和验证分别遵循 [planning-layer.md](references/planning-layer.md)、[asset-planning.md](references/asset-planning.md)、[visual-planning.md](references/visual-planning.md)、[validation-checklist.md](references/validation-checklist.md)。仅替换一个标题、插入一个块等小型已有页编辑可豁免。**
 
-**CRITICAL — 新建演示文稿或大幅改写页面时，生成 XML 前 MUST 读取 [visual-planning.md](references/visual-planning.md)，确保 `layout_type`、`visual_focus`、`text_density` 实际改变页面几何、主视觉和文本量。**
-
-**CRITICAL — 新建演示文稿或大幅改写页面时，规划 `asset_need` MUST 遵循 [asset-planning.md](references/asset-planning.md)：只做元数据规划，必须有 `fallback_if_missing`，不得要求真实搜索、下载或上传素材。**
-
-**CRITICAL — 创建或大幅改写后，MUST 按 [validation-checklist.md](references/validation-checklist.md) 做显式验证：回读全文 XML、核对页数和关键元素、检查空白/破损页、明显溢出、布局风险；XML 语法和文本重叠静态检查优先使用 [`scripts/xml_text_overlap_lint.py`](scripts/xml_text_overlap_lint.py)。**
-
-**CRITICAL — 创建前自检或失败排障时，MUST 按 [troubleshooting.md](references/troubleshooting.md) 检查 XML 转义、结构、shell 截断、图片 token、3350001 和布局风险。**
-
-**CRITICAL — 如果用户提到“模板”“套用模板”“参考某种主题/风格/版式”，或用户需求明显落在已有场景模板内（如工作汇报、产品介绍、商业计划书、培训、晋升汇报等），MUST 先用 [`scripts/template_tool.py`](scripts/template_tool.py) 的 `search` 做模板检索；默认给出 2-3 个最匹配模板候选供用户选择。锁定模板后用 `summarize` 获取主题和布局摘要；只有需要布局骨架时才用 `extract` 裁切目标页型 XML。不要直接读取完整模板 XML。**
+创建前自检或失败排障时，按 [troubleshooting.md](references/troubleshooting.md) 检查 XML 转义、结构、shell 截断、图片 token、3350001 和布局风险。
 
 > [!NOTE]
 > `scripts/template_tool.py` 需要 Python 3。`references/template-index.json` 是脚本缓存/轻量路由索引，不是默认给 agent 阅读的文档；`assets/templates/*.xml` 是机器资源，只应通过脚本摘要或裁切，不要全文读取。
 
-**CRITICAL — 使用模板生成或改写页面时，MUST 先 `summarize` 目标页型；只有需要具体布局骨架时才 `extract`。**
+使用内置模板生成或改写页面时，先 `summarize` 目标页型；只有需要具体布局骨架时才 `extract`。如果用户已经提供本地/在线模板材料，优先按用户材料导入二创，不走内置模板检索。
 
-**编辑已有幻灯片页面**：优先用 [`+replace-slide`](references/lark-slides-replace-slide.md)（块级替换/插入，不动页序）；选择 action 和完整读-改-写流程见 [`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)。
+**编辑已有幻灯片页面**：单个标题、文本块、图片或局部元素优先用 [`+replace-slide`](references/lark-slides-replace-slide.md)（块级替换/插入，不动页序）；已有 Slides 的多页大改优先用 [`+replace-pages`](references/lark-slides-replace-pages.md) 在原 presentation 内批量重建页面，避免 `slides +create` 生成新链接。选择 action 和完整读-改-写流程见 [`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)。
 
 ## 身份选择
 
@@ -81,7 +75,8 @@ lark-cli auth login --domain slides
 按需再读：
 
 - 创建：[`lark-slides-create.md`](references/lark-slides-create.md)
-- 编辑：[`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)、[`lark-slides-replace-slide.md`](references/lark-slides-replace-slide.md)
+- 编辑：[`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)、[`lark-slides-replace-slide.md`](references/lark-slides-replace-slide.md)、[`lark-slides-replace-pages.md`](references/lark-slides-replace-pages.md)
+- 截图：[`lark-slides-screenshot.md`](references/lark-slides-screenshot.md)
 - 图片：[`lark-slides-media-upload.md`](references/lark-slides-media-upload.md)
 - 流程图 / 时序图 / 架构图 / 装饰图案：[`lark-slides-whiteboard.md`](references/lark-slides-whiteboard.md)
 - 图标：[`iconpark.md`](references/iconpark.md)、[`scripts/iconpark_tool.py`](scripts/iconpark_tool.py)
@@ -91,8 +86,6 @@ lark-cli auth login --domain slides
 
 ## Workflow
 
-> **这是演示文稿，不是文档。** 每页 slide 是独立的视觉画面，信息密度要低，排版要留白。
-
 ### Design Ideas
 
 不要生成无设计感的幻灯片。纯白背景 + 标题 + bullets 只能作为极简临时稿，不能作为正式交付。
@@ -131,7 +124,9 @@ lark-cli auth login --domain slides
 - 不要把素材缺失表现为空白图片框；必须按 `fallback_if_missing` 生成 XML-native 视觉。
 - 不要留下模板占位文案、示例公司名、示例日期或与用户主题无关的原模板内容。
 
-### 创建方式选择
+### 无用户导入材料时的创建方式
+
+以下创建方式仅适用于没有用户提供可导入材料、用户明确要求另建 deck，或导入失败/`xml_presentations.get` 无法回读的异常场景。
 
 | 场景 | 推荐方式 |
 |------|----------|
@@ -147,7 +142,7 @@ lark-cli auth login --domain slides
 
 ### 模板与脚本优先流程
 
-模板细则见 [template-catalog.md](references/template-catalog.md)。主流程只记住：先 `search`，锁定后 `summarize`，需要骨架时才 `extract`；不要直接读取完整模板 XML 或照搬占位文案。
+模板细则见 [template-catalog.md](references/template-catalog.md)。仅在用户没有提供本地/在线模板材料时使用内置模板流程：先 `search`，锁定后 `summarize`，需要骨架时才 `extract`；不要直接读取完整模板 XML 或照搬占位文案。
 
 ```bash
 python3 skills/lark-slides/scripts/template_tool.py search --query "<用户需求原文>" --limit 3
@@ -157,18 +152,19 @@ python3 skills/lark-slides/scripts/template_tool.py extract --template <template
 
 ```text
 Step 1: 需求澄清 & 读取知识
-  - 澄清主题、受众、页数、风格；模板需求按“模板与脚本优先流程”处理
+  - 澄清主题、受众、页数、风格；没有用户提供模板材料时，模板需求按“模板与脚本优先流程”处理
   - 读取 xml-schema-quick-ref.md；新建 / 大幅改写时还要读取 planning-layer.md、visual-planning.md、asset-planning.md
+  - 如果用户提供附件、文件路径、素材目录或类似“附件文件路径：...”的文本，先按 asset-planning.md 解析路径、枚举文件、读取/导入/上传可用素材；不要直接跳到大纲或 XML
 
 Step 2: 生成大纲 → 用户确认 → 写入 slide_plan.json
-  - 生成结构化大纲供用户确认；如使用模板，标明基于哪个模板改写
+  - 生成结构化大纲供用户确认；如使用用户附件、导入后的 slides 或模板材料，标明每类素材如何参与二次创作
   - 新建 / 大幅改写必须先创建目录并写入 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`
   - plan 字段、路径命名、模板边界和 `asset_need` 结构按 planning-layer.md / asset-planning.md 执行
 
 Step 3: 按 slide_plan.json 生成 XML → 创建
   - 逐页消费 plan：key_message 定主结论，layout_type 定几何，visual_focus 定主视觉，text_density 定文本量
   - 缺少真实素材时必须用 `fallback_if_missing` 生成 XML-native 兜底视觉；不要留空
-  - 创建方式按“创建方式选择”判断；图片、复杂 XML、转义和 3350001 排查按 lark-slides-create.md、media-upload.md、troubleshooting.md 执行
+  - 如果 plan 有 `target_xml_presentation_id`，默认在该 presentation 内创建、替换或删除页面；只有无导入材料、用户明确要求另建，或导入失败/回读失败时，才按“无用户导入材料时的创建方式”新建 deck
 
 Step 4: 审查 & 交付
   - 创建完成后，必须用 xml_presentations.get 读取全文 XML，并按 validation-checklist.md 做显式验证记录，包括 XML 文本重叠检查
@@ -178,7 +174,7 @@ Step 4: 审查 & 交付
 
 ### jq 命令模板（编辑已有 PPT 时使用）
 
-新建 PPT 推荐用 `+create --slides`。以下 jq 模板适用于向已有演示文稿追加页面的场景，可以避免手动转义双引号：
+无用户导入材料的新建 PPT 可用 `+create --slides`。以下 jq 模板适用于向已有演示文稿追加页面的场景，可以避免手动转义双引号：
 
 ```bash
 # 追加到末尾
@@ -266,6 +262,7 @@ Shortcut 是对常用操作的高级封装（`lark-cli slides +<verb> [flags]`
 | [`+create`](references/lark-slides-create.md) | 创建 PPT（可选 `--slides` 一步添加页面，支持 `<img src="@./local.png">` 占位符自动上传） |
 | [`+media-upload`](references/lark-slides-media-upload.md) | 上传本地图片到指定演示文稿，返回 `file_token`（用作 `<img src="...">`），最大 20 MB |
 | [`+replace-slide`](references/lark-slides-replace-slide.md) | 对已有幻灯片页面进行块级替换/插入（`block_replace` / `block_insert`），自动注入 id 和 `<content/>`，不改变页序 |
+| [`+replace-pages`](references/lark-slides-replace-pages.md) | 在原演示文稿内批量重建多个页面：先创建新页到旧页前，再删除旧页；适合已有 Slides 的多页大改，不新建链接 |
 
 没有 Shortcut 覆盖时使用原生 API。高频资源：`xml_presentations.get` 读取全文；`xml_presentation.slide.create/delete/get/replace` 管理单页。
 
@@ -278,13 +275,14 @@ lark-cli slides <resource> <method> [flags] # 调用 API
 
 ## 核心规则
 
-1. **先规划再写 XML**：新建演示文稿或大幅改写页面时，必须先写入 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`；模板、风格和大纲只能作为规划输入，不能绕过规划层
-2. **创建流程**：简单短 XML（1-3 页、结构简单、特殊字符少）可用 `slides +create --slides '[...]'` 一步创建；复杂内容、含图片/中文大段文本/嵌套引号/较多特殊字符，或超过 10 页时，默认先 `slides +create` 创建空白 PPT，再用 `xml_presentation.slide.create` 逐页添加
-3. **`<slide>` 直接子元素只有 `<style>`、`<data>`、`<note>`**：文本和图形必须放在 `<data>` 内
-4. **文本通过 `<content>` 表达**：必须用 `<content><p>...</p></content>`，不能把文字直接写在 shape 内
-5. **保存关键 ID**：后续操作需要 `xml_presentation_id`、`slide_id`、`revision_id`
-6. **删除谨慎**：删除操作不可逆，且至少保留一页幻灯片
-7. **编辑已有页面优先块级替换**：修改单个 shape/img 用 `+replace-slide`（`block_replace` / `block_insert`），不要整页重建；只有需要替换整页结构时才用 `slide.delete` + `slide.create`
-8. **`<img src>` 只能用上传到飞书 drive 的 `file_token`，禁止使用 http(s) 外链 URL**：飞书 slides 渲染端不会代理外链图片，外链 src 在 PPT 里通常不显示或显示破图。流程必须是「先把图存到本地 → 用 `slides +media-upload` 上传或 `+create --slides` 的 `@./path` 占位符自动上传 → 拿 `file_token` 写进 `<img src>`」。如果用户给了网图链接，先 `curl`/下载到 CWD 内再走上传流程，不要直接把外链 URL 塞进 `src`。**图片最大 20 MB**（slides upload API 不支持分片上传）。
+1. **用户材料默认作为二创底稿**：用户提供 PDF/PPTX/slides 材料并要求生成、改写、二创、压缩页数或保留材料风格/资产时，必须先导入或回读为 slides；默认 `target_xml_presentation_id` 等于导入或已有材料的 `xml_presentation_id`，在该 presentation 内继续创作。“只作为模板/视觉线索”只表示不复制原文案，不表示可以跳过导入或新建脱离材料的 deck
+2. **先规划再写 XML**：新建演示文稿或大幅改写页面时，必须先写入 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`；模板、风格和大纲只能作为规划输入，不能绕过规划层
+3. **创建流程**：仅在没有用户提供可导入材料、用户明确要求新建 deck，或导入失败/`xml_presentations.get` 无法回读时，才使用 `slides +create` 新建目标 deck；页数多、内容不可用、只参考风格、布局复杂或 PDF 是正文资料都不是新建理由
+4. **`<slide>` 直接子元素只有 `<style>`、`<data>`、`<note>`**：文本和图形必须放在 `<data>` 内
+5. **文本通过 `<content>` 表达**：必须用 `<content><p>...</p></content>`，不能把文字直接写在 shape 内
+6. **保存关键 ID**：后续操作需要 `xml_presentation_id`、`slide_id`、`revision_id`
+7. **删除谨慎**：删除操作不可逆，且至少保留一页幻灯片
+8. **编辑已有页面优先块级替换**：修改单个 shape/img 用 `+replace-slide`（`block_replace` / `block_insert`），不要整页重建；已有 Slides 的多页整页重建用 `+replace-pages`，不要用 `slides +create` 新建整份 PPT；只有没有 shortcut 覆盖的特殊单页整页操作才手动 `slide.create` + `slide.delete`
+9. **`<img src>` 只能用上传到飞书 drive 的 `file_token`，禁止使用 http(s) 外链 URL**：飞书 slides 渲染端不会代理外链图片，外链 src 在 PPT 里通常不显示或显示破图。流程必须是「先把图存到本地 → 用 `slides +media-upload` 上传或 `+create --slides` 的 `@./path` 占位符自动上传 → 拿 `file_token` 写进 `<img src>`」。如果用户给了网图链接，先 `curl`/下载到 CWD 内再走上传流程，不要直接把外链 URL 塞进 `src`。**图片最大 20 MB**（slides upload API 不支持分片上传）。
 
 > **注意**：如果 md 内容与 `slides_xml_schema_definition.xml` 或 `lark-cli schema slides.<resource>.<method>` 输出不一致，以后两者为准。

skills/lark-slides/references/asset-planning.md

@@ -1,28 +1,208 @@
-# Asset Planning
+# Material And Asset Planning
 
-新建演示文稿或大幅改写页面时，在写入 `slide_plan.json` 前后都可以参考本文件。目标是让 agent 主动识别有价值的图、图标、图表、流程图、时序图、架构图、装饰图案、截图或示意图需求，同时保持 deck 在没有真实素材时也能完整执行。
+新建演示文稿或大幅改写页面时，planning layer 必须先激活本素材处理层，再写入或更新 `slide_plan.json`。目标是让 agent 先利用用户已经提供的本地素材和上下文，再决定是否需要内置模板、联网搜索或 XML-native 兜底。
 
-本文件只定义轻量资产规划。不要把它理解成素材采集流程。
+本文件覆盖两类对象：
+
+- `material_inventory`：deck 级素材盘点，记录本地素材、链接、缺口、用途和搜索策略。
+- `asset_need`：page 级视觉资产需求，记录每页是否需要图片、图表、截图、图标、文案来源或兜底视觉。
 
 ## Core Rules
 
-- `asset_need` is metadata only. It can guide page design, but it must not require web search, local download, media upload, or external tools.
-- Every planned asset must include a fallback visual plan so the slide can be generated with XML shapes, text, arrows, tables, simple charts, whiteboard diagrams, or placeholder regions.
-- Asset needs must serve the page's `key_message` and `visual_focus`. Do not add decorative assets that do not clarify the page.
-- Prefer a few high-value asset plans over one asset on every page. For a 6-page technical or business deck, plan assets on at least 3 pages when the content allows.
-- If a real local asset already exists or the user provides one, it can be used through the normal media-upload workflow. Still keep `fallback_if_missing` in the plan.
-- Do not leave blank image boxes in final XML. If the asset is missing, render the fallback visual.
+- 本地素材优先。用户给了文件、目录、截图、PDF、PPTX、文案、数据表、链接或已有 slides 时，先按 Attachment Resolution 解析并盘点用途；禁止忽略附件直接生成大纲或 XML。
+- 没有合适本地素材时，才考虑联网搜索、内置模板、IconPark 或 XML-native 兜底。用户已提供模板材料时，这些能力只能补缺，不能替代导入后的目标 presentation 或主视觉系统。
+- 素材进入 plan 前必须分类并写清用途；不要把“有文件”直接等同于“应出现在页面上”。
+- 页面不能依赖不可获得素材才能完成。每个 `asset_need` 都必须有 `fallback_if_missing`。
+- 真实图片进入 slides 前必须走支持的上传路径：`slides +media-upload` 或 `+create --slides` 的 `@./path` 占位符。禁止把 http(s) 外链直接写进 `<img src>`。
+- `.pptx` / `.pdf` / online slides 参与制作或改写 PPT 时，按 Local Material Handling 先判断 `rewrite_source` / `copy_source`；可作为视觉底稿的材料必须导入或回读为 slides。
 
-## JSON Shape
+## Attachment Resolution
 
-Use an object for one planned asset, or an array when a page genuinely needs multiple assets. Keep each item compact.
+在写 `slide_plan.json` 前，先把用户提供的附件文本转成可操作的本地路径清单。
+
+1. 从 prompt 提取所有附件线索：`附件文件路径：...`、`文件：...`、`上传文件：...`、相对路径、绝对路径、目录路径，以及结构化输入中单独列出的文件名。
+2. 逐个解析路径：
+   - 已是绝对路径：直接检查是否存在。
+   - 相对路径：先按当前工作目录解析；如果用户或调用方另行说明了素材根目录，也要按该根目录解析同一相对路径。
+   - 只有文件名：先查用户明确给出的素材目录；没有目录时，只在当前工作目录和任务上下文明确给出的附件目录中查找。
+   - 包含 URL 或在线 slides/wiki/drive/doc 链接：按对应 skill/API 获取内容或 token；不要当成本地路径。
+3. 如果路径文本和真实文件名只有轻微差异（例如 `-` 与 `_`、`.` 与 `_`、URL 转义、空格、中文括号、图片平台后缀中的 `~` 被本地保存为 `_`），在同目录用文件名相似匹配找候选；只有唯一高置信候选时使用，并在 `material_inventory.inputs[].notes` 记录映射。
+4. 对目录路径必须先列出直接子文件并按扩展名分组；不要只记录目录本身。
+5. 找不到的附件写入 `material_inventory.missing`，并说明会用什么 XML-native 或内置能力兜底。找不到附件不能成为空白页的理由。
+
+最小盘点动作：
+
+- 文档/表格/图片/PPT/PDF 至少要记录 `source`、`resolved_path`、`kind`、`usage`、`status`。
+- 如果素材会进入页面，`asset_need.candidate_sources` 必须使用解析后的可用路径，而不是原始不可用的路径文本。
+- 如果素材只用于理解或提供视觉线索，也必须在 `material_inventory.inputs` 中出现，避免后续 XML 生成阶段遗忘。
+
+## Material Roles
+
+将每个输入素材归入以下角色之一；一个素材可以有多个角色，但要分别说明用途。
+
+| Role | 用途 | 常见来源 | 默认处理 |
+|------|------|----------|----------|
+| `background_reference` | 补充主题背景、事实、约束、术语、受众信息 | 文档、网页、PRD、报告、会议纪要 | 读取/摘要后影响叙事和页面重点 |
+| `visual_asset` | 可直接进入页面的视觉素材 | 图片、截图、logo、图表、论文 figure | 上传后放入计划区域；不合适则重绘或兜底 |
+| `copy_source` | 文案、标题、大纲、讲稿、卖点、结论来源 | Markdown、TXT、Docx、用户 prompt、会议纪要 | 改写成低密度 slide 文案 |
+| `data_source` | 生成表格、指标卡、图表的数据来源 | CSV、XLSX、表格截图、结构化数据 | 转成 chart/table/数字卡 |
+| `brand_asset` | 品牌识别和视觉约束 | logo、VI 色板、品牌手册 | 影响 `theme_style` / `visual_system` |
+| `rewrite_source` | 导入后承载二次创作的目标底稿 | 用户已有 PPTX/PDF/slides、背景模板、旧版汇报、待美化稿 | 导入/回读后作为 target presentation，规划保留、替换、删除和重排 |
+
+PDF/PPTX/slides 的主角色只能是 `rewrite_source` 或 `copy_source`。如需表达背景、视觉或品牌信息，只写进 `usage`，不能改变目标 presentation。
+
+## Source Priority
+
+1. 用户显式提供的本地素材。
+2. 当前工作区内与任务明确相关的素材。
+3. 用户给出的在线 slides/wiki/drive/doc 链接。
+4. 内置模板库和 IconPark。
+5. 联网搜索公开素材或背景信息。
+6. XML-native 兜底视觉。
+
+如果多个来源冲突，用户显式提供的素材优先；无法判断时，在 plan 的 `open_issues` 里记录需要用户确认。
+
+## Local Material Handling
+
+- `.pptx` / `.pdf` / online slides 若承担模板、背景模板、旧稿、待美化稿、品牌视觉或页面结构角色，默认是 `rewrite_source`：先导入或回读为 slides，`target_xml_presentation_id` 默认等于导入/已有 presentation，并在同一个 presentation 内创建、替换、删除或重排页面。
+- “内容不可用”“只作为背景模板”“不要使用模板文字”“只参考风格”只表示该材料不是 `copy_source`；它仍默认是 `rewrite_source`，用于保留或重绘背景、版式、图片资产和页面结构。
+- `.pdf` 若只是论文、报告、PRD、教案正文等内容资料，可以作为 `copy_source` 读取/摘要；但 `copy_source` 不得替代已有 `rewrite_source`，也不得成为新建 deck 的理由。
+- 用户明确说“只参考风格”时，不新增单独角色；仍把 PDF/PPTX/slides 作为 `rewrite_source` 导入/回读，只在 `usage` 中说明“不复制模板文案，仅沿用或重绘风格、版式和页面结构”。
+- 已有 online slides：直接回读 XML，默认把它作为 `rewrite_source`；不要再走导入。
+- `.png` / `.jpg` / `.jpeg` 等图片：判断是可直接展示、需要裁切/缩放、还是只用于理解。进入 XML 前必须上传或使用 `@./path` 占位符。
+- `.md` / `.txt` / 文档类内容：作为 `copy_source` 或 `background_reference`，提炼为低密度页面文案，不要整段搬进 slide。
+- `.docx` / `.doc`：通常是 `copy_source` 和 `background_reference`。先读取或转换提取正文、标题层级、表格和内嵌图片线索，再改写为 slide 叙事。用户要求“不要杜撰数据”时，数值和图表只能来自这类源文件或表格源；缺数据则在 plan 中标注缺口。
+- `.xlsx` / `.xls` / `.csv`：通常是 `data_source`。先识别工作表、列名、时间范围、指标和关键数值，再规划 `<chart>` / 表格 / 数字卡。用户明确要求精准图表时，必须让图表数据来自表格，不要手工编造。
+
+## PDF Template Pre-slicing
+
+大 PDF 模板用于二次创作时，可以先切出关键模板页生成小 PDF，再用 `drive +import --type slides` 导入小 PDF。这样减少导入和回读成本，同时仍保留在导入后的 presentation 内二创的主路径。
+
+仅在同时满足这些条件时才切割：
+
+- 任务是制作、改写、二创、压缩页数或替换内容模块，而不是单纯导入 PDF。
+- PDF 是 `rewrite_source`，只需要其中的视觉骨架、背景、版式、图片资产或页面结构。
+- 已能明确选择关键页，例如封面、目录、章节页、图谱/流程页、表格页、结尾页，通常保留 6-10 页或用户指定页。
+
+禁止切割的场景：
+
+- 用户只要求“导入 PDF 为 slides”“转换格式”“保留完整 PDF”“检查导入效果”。
+- 用户要求保留全部页序、全部页面内容或逐页迁移。
+- 无法判断关键页，且切割会丢失用户可能需要的视觉结构。
+
+切割后在 `material_inventory.inputs[]` 中记录原 PDF 和压缩 PDF 的关系：
+
+- 原 PDF 仍记录为 `source`，`usage` 说明只取关键视觉页。
+- 压缩 PDF 记录为实际导入对象，`status: "preprocessed"` 或 `"imported"`。
+- 记录 `selected_pages`、`preprocessed_path`、选择理由，以及后续导入得到的 `imported_xml_presentation_id` / `target_xml_presentation_id`。
+- 生成新页并回读成功后，再按计划删除或替换导入模板中的旧内容页。
+
+## Image Asset Migration
+
+导入的 PPTX/PDF 页面里可能已有 `<img src="file_token">`、背景图或品牌图。这些图片 token 可以在同一个导入后的 presentation 内复用；只有跨到另一个新建 presentation 时，才不能直接复制旧 XML 里的 `<img src>`。
+
+在 `slide_plan.json` 中为模板或原稿记录 `template_asset_strategy`：
+
+- `preserve_imported_page`：模板页含需要复用的背景图、装饰图、品牌图或复杂图片版式。优先在导入页上用 `+replace-slide` / `block_insert` / `block_replace` 做局部编辑，保留现有 `<img>` token。
+- `rebuild_in_imported_presentation`：需要重做 XML-native 页面，但仍在同一个导入后的 presentation 内创建/替换页面。可以复用该 presentation 内已有图片 token，无需下载再上传；删除旧页前先确认新页已创建成功。
+- `mixed`：同一 deck 中部分页面保留导入页图片资产，部分页面重建。每页在 plan 里说明来源页、目标 presentation、是否复用同一 presentation 的图片 token、是否需要重新上传。
+
+首次运行时先判断目标页是否仍在导入后的同一个 presentation 内。只要同一 presentation，就可以复用回读 XML 里的图片 token；不要静默复制图片 token 到新文稿。异常新建只能由用户明确要求另建，或导入失败/回读失败触发；若需要复用导入页图片，必须记录下载/重新上传方案。
+
+如果选择 `preserve_imported_page`、`rebuild_in_imported_presentation` 或 `mixed`，且导入后的 slides 会作为最终交付物继续编辑，完成后必须把在线文件标题改成用户任务对应的新标题，避免仍保留导入时的模板/原附件名称。标题修改走 `lark-drive` 的 `drive files patch`，使用 `new_title` 字段；不要为了改标题重建整份 PPT。
+
+## Imported Material As Draft
+
+当用户提供 PDF/PPTX/slides 材料并要求制作或改写 PPT 时，先在 plan 中定两类来源：
+
+- `rewrite_source`：导入/回读后的目标视觉底稿，记录 `imported_xml_presentation_id`、`target_xml_presentation_id`、`template_asset_strategy` 和 `target_title`；默认策略是 `preserve_imported_page`、`rebuild_in_imported_presentation` 或 `mixed`。
+- `copy_source`：真正提供文案、事实、标题层级、数据或案例的材料。
+
+只有用户明确要求新建，或导入失败/`xml_presentations.get` 无法回读时，才允许新建 deck，并说明原因和图片资产迁移策略。“页数不超过 N 页”、内容不可用、只参考风格、PDF 是正文资料或布局复杂，都不是新建 deck 的理由。如果附件里有素材但 plan 没有使用，必须在 `material_inventory.inputs[].usage` 说明原因。
+
+## Search Policy
+
+联网搜索不是默认动作。只有出现以下情况才搜索：
+
+- 用户要求查找公开事实、行业背景、竞品、logo、截图、图片或最新资料。
+- plan 中存在关键视觉缺口，且用户模板材料无法满足；搜索结果只能补缺，不能替代用户模板的主视觉系统。
+- 用户给出的主题需要真实世界背景才能避免空泛表达。
+
+搜索结果使用规则：
+
+- 图片素材必须先落到本地，再按 Core Rules 的上传路径进入 XML。
+- 背景信息必须转化为 `background_reference` 摘要和页面结论，不要把长文本塞进页面。
+- 无法确认版权或来源可靠性时，只作为风格/信息参考，不直接作为可展示图片。
+- 如果搜索失败或不适合使用，按 `fallback_if_missing` 生成 XML-native 视觉。
+
+## Plan Shape
+
+Deck 级 `material_inventory` 片段示例：
 
 ```json
 {
-  "asset_type": "architecture_diagram",
-  "purpose": "Show how API gateway, planner, XML generator, and Slides API interact.",
-  "suggested_query": "agent native slides runtime architecture diagram",
-  "fallback_if_missing": "Draw grouped boxes connected by arrows with short labels."
+  "material_inventory": {
+    "local_first": true,
+    "inputs": [
+      {
+        "source": "./template.pdf",
+        "resolved_path": "./template.pdf",
+        "kind": "rewrite_source",
+        "usage": "Import key visual pages as slides and use as the target visual draft; do not copy placeholder text.",
+        "preprocessed_path": "./template_key_pages.pdf",
+        "selected_pages": [1, 2, 5, 8, 12, 20],
+        "status": "imported",
+        "imported_xml_presentation_id": "SOURCE_PRESENTATION_ID",
+        "target_xml_presentation_id": "SOURCE_PRESENTATION_ID",
+        "template_asset_strategy": "rebuild_in_imported_presentation",
+        "target_title": "New deck title"
+      },
+      {
+        "source": "./notes.md",
+        "resolved_path": "./notes.md",
+        "kind": "copy_source",
+        "usage": "Condense into slide headlines and speaker intent.",
+        "status": "available"
+      },
+      {
+        "source": "./draft.pptx",
+        "resolved_path": "./draft.pptx",
+        "kind": "rewrite_source",
+        "usage": "Import and read back XML; preserve visual structure and restyle each page.",
+        "status": "available"
+      }
+    ],
+    "missing": [
+      {
+        "need": "Product screenshot for workflow page",
+        "search_policy": "Use local screenshot if provided; otherwise search only if user wants real UI imagery.",
+        "fallback_if_missing": "Draw a simplified UI wireframe with labeled panels."
+      }
+    ]
+  }
+}
+```
+
+For a slide derived from a `rewrite_source`, add source-page mapping inside that slide plan, for example:
+
+```json
+{
+  "source_page": 3,
+  "source_operation": "restyle",
+  "preserve_content": "Keep the original claim, metrics, and section role; improve layout hierarchy and redraw the chart."
+}
+```
+
+Page 级 `asset_need` 示例：
+
+```json
+{
+  "asset_type": "screenshot",
+  "source_preference": "local_first",
+  "purpose": "Show the target workflow state instead of describing it with bullets.",
+  "candidate_sources": ["./assets/workflow.png"],
+  "suggested_query": "product workflow screenshot",
+  "fallback_if_missing": "Draw a simplified UI wireframe with three panels and callout labels."
 }
 ```
 
@@ -31,7 +211,9 @@ For a page without a meaningful asset need, use:
 ```json
 {
   "asset_type": "none",
+  "source_preference": "none",
   "purpose": "No external or simulated asset needed; the page is text-led.",
+  "candidate_sources": [],
   "suggested_query": "",
   "fallback_if_missing": "Use typography, spacing, and simple accent shapes only."
 }
@@ -43,7 +225,7 @@ For a page without a meaningful asset need, use:
 - `architecture_diagram`: system components, data flow, dependency map, or model structure.
 - `icon`: small semantic symbol for a concept, step, role, or status.
 - `logo`: brand, product, team, or customer mark.
-- `chart`: line, bar, pie, radar, area, or combo data visual. Note: `<chart>` does not support funnel or scatter — map those to `<whiteboard>` SVG at generation time.
+- `chart`: line, bar, pie, radar, area, or combo data visual. Note: `<chart>` does not support funnel or scatter; map those to `<whiteboard>` at generation time.
 - `infographic`: composed visual explanation, usually combining labels, numbers, and simple shapes.
 - `screenshot`: product UI, terminal output, workflow state, or page capture.
 - `flow_diagram`: process, sequence, decision tree, or mechanism diagram.
@@ -53,23 +235,23 @@ Do not invent new asset types unless the user asks for a special visual format.
 
 ## Planning Guidance
 
-Match asset type to slide role:
+Match source type to slide role. Detailed geometry belongs in `visual-planning.md`; this mapping only helps choose `asset_need`.
 
 - `architecture-diagram` layout usually pairs with `architecture_diagram` or `flow_diagram`.
 - `process-flow` layout usually pairs with `flow_diagram`, `icon`, or `infographic`.
 - `comparison` layout often works with `icon`, `chart`, or `infographic`.
 - `timeline` layout often works with `icon`, `chart`, or shape-based milestone markers.
-- `big-number` layout often works with `chart` or `infographic`, but only if it supports the metric.
-- `image-left-text-right` and `image-right-text-left` can use `screenshot`, `paper_figure`, `logo`, or `infographic`; if missing, use a large placeholder diagram or stylized panel.
+- `big-number` layout often works with `chart`, `data_source`, or `infographic`.
+- `image-left-text-right` and `image-right-text-left` can use `screenshot`, `paper_figure`, `logo`, `infographic`, or a layout derived from imported material.
 
-`suggested_query` is only a future lookup hint. Write it as a short phrase a human or later workflow could search, but do not execute the search unless the user separately requests real assets.
+`suggested_query` is a future lookup hint. Execute the search only when the search policy says remote material is needed and local sources are insufficient.
 
 `fallback_if_missing` must be concrete enough to turn into XML, for example:
 
 - "Draw a simplified attention matrix with 5 token labels, semi-transparent cells, and arrows to output token."
 - "Use three grouped boxes with arrows from client to gateway to service; add small protocol labels."
 - "Render a mini bar chart with 4 bars using shapes and value labels."
-- "Use a bordered placeholder panel with product area labels, not an empty image."
+- "Use a bordered UI wireframe with product area labels, not an empty image."
 
 Weak fallbacks to avoid:
 
@@ -78,47 +260,14 @@ Weak fallbacks to avoid:
 - "Leave blank if unavailable."
 - "Use generic decoration."
 
-## Examples
-
-Transformer Self-Attention page:
-
-```json
-{
-  "asset_type": "paper_figure",
-  "purpose": "Explain token-to-token attention and why each output token mixes context.",
-  "suggested_query": "Transformer self attention attention matrix diagram",
-  "fallback_if_missing": "Draw a simplified attention matrix with token labels, colored weights, and arrows from input tokens to one highlighted output token."
-}
-```
-
-System architecture page:
-
-```json
-{
-  "asset_type": "architecture_diagram",
-  "purpose": "Show the runtime path from user prompt to plan, XML generation, Slides API creation, and fetch verification.",
-  "suggested_query": "slides generation runtime architecture planner XML API verification",
-  "fallback_if_missing": "Draw four grouped boxes connected left-to-right with arrows; put verification as a return arrow from Slides API to agent."
-}
-```
-
-Business comparison page:
-
-```json
-{
-  "asset_type": "infographic",
-  "purpose": "Make before/after differences scannable without dense bullet lists.",
-  "suggested_query": "before after product workflow comparison infographic",
-  "fallback_if_missing": "Use two side-by-side panels with matching icon circles and three parallel rows of concise labels."
-}
-```
-
 ## Plan To XML Contract
 
 When generating XML:
 
-1. If an asset exists and the workflow supports it, place it in the planned visual region.
-2. If no asset exists, immediately render `fallback_if_missing` with XML-native shapes, text, lines, arrows, tables, whiteboard diagrams, or chart-like elements.
-3. Size the fallback to satisfy `visual_focus`; it should be a real page element, not a tiny decoration.
-4. Keep text-density limits. Do not compensate for missing assets by adding long bullet text.
-5. After creation, fetch the presentation and verify asset pages are not blank and that each planned fallback is visible when no real asset was used.
+1. Apply `material_inventory` first: imported target material, copy sources, data sources, and visual assets decide what each page can use.
+2. If `target_xml_presentation_id` points to imported user material, create, replace, reorder, or delete pages in that presentation; do not call `slides +create` for a detached new deck unless the plan records an explicit user request to create a new deck or an import/readback failure.
+3. If a real visual asset exists and the workflow supports it, place it in the planned visual region.
+4. If no asset exists, immediately render `fallback_if_missing` with XML-native shapes, text, lines, arrows, tables, whiteboard diagrams, or chart-like elements.
+5. Size the fallback to satisfy `visual_focus`; it should be a real page element, not a tiny decoration.
+6. Keep text-density limits. Do not compensate for missing assets by adding long bullet text.
+7. After creation, fetch the presentation and verify asset pages are not blank and that each planned fallback is visible when no real asset was used.

skills/lark-slides/references/lark-slides-edit-workflows.md

@@ -1,6 +1,6 @@
 # 编辑已有 PPT：读-改-写闭环
 
-编辑走 **shortcut [`+replace-slide`](lark-slides-replace-slide.md)**（块级替换 / 插入），配合 `xml_presentation.slide.get` 读原页拿 `block_id`。
+局部编辑走 **shortcut [`+replace-slide`](lark-slides-replace-slide.md)**（块级替换 / 插入），配合 `xml_presentation.slide.get` 读原页拿 `block_id`。已有 Slides 的多页整页重建走 **[`+replace-pages`](lark-slides-replace-pages.md)**，保持原 presentation 链接不变。
 
 > 生成 XML 前**必读** [xml-schema-quick-ref.md](xml-schema-quick-ref.md)。
 
@@ -11,6 +11,7 @@
 | 已知某块的 `block_id`，要换这块内容（改标题、换图、挪坐标） | `block_replace` | 精准替换，原子性好；`replacement` 根 `id` 由 CLI 自动注入为 `block_id` |
 | 只加 1~N 个元素、不动现有布局 | `block_insert` | 新增不覆盖，可选 `insert_before_block_id` 指定位置 |
 | 一次动多个元素（如：换标题 + 加图） | 单次 `--parts` 里拼多条 | 整批作为原子事务，任一失败整批不生效；`block_replace` 和 `block_insert` 可混用 |
+| 多页版式重建、整页坐标重排 | `+replace-pages` | 原 presentation 内批量 create-before/delete-old，不生成新 Slides 链接 |
 
 > **没有字段级 patch**：即便只想改一个 `shape` 的 `topLeftX`，也得把整个块的新 XML 写出来用 `block_replace`。这不是"微调"，是块级重写。
 
@@ -136,6 +137,7 @@ cat parts.json | lark-cli slides +replace-slide --as user --presentation "$PID"
 ## 相关文档
 
 - [lark-slides-replace-slide.md](lark-slides-replace-slide.md) — +replace-slide shortcut 参数详情
+- [lark-slides-replace-pages.md](lark-slides-replace-pages.md) — 多页整页重建 shortcut
 - [lark-slides-xml-presentation-slide-get.md](lark-slides-xml-presentation-slide-get.md) — slide.get 参考（拿 `block_id` / `revision_id`）
 - [lark-slides-xml-presentation-slide-replace.md](lark-slides-xml-presentation-slide-replace.md) — 底层 replace API 参考（一般直接用 shortcut 即可）
 - [lark-slides-media-upload.md](lark-slides-media-upload.md) — 上传图片拿 file_token

skills/lark-slides/references/lark-slides-replace-pages.md

@@ -0,0 +1,95 @@
+# slides +replace-pages（多页整页重建）
+
+批量替换已有演示文稿里的多个页面，保持原 `xml_presentation_id` 和原 Slides 链接不变。适合多页版式大改、坐标重排、整页视觉重建；单个文本框、图片或 shape 的局部编辑仍优先用 [`+replace-slide`](lark-slides-replace-slide.md)。
+
+> 重要：这是多步编排，不是后端原子事务。CLI 对每页执行“先创建新页到旧页前，再删除旧页”；创建失败时旧页会保留。删除失败时可能出现新旧页同时存在，需要按返回结果继续处理。
+
+## 命令
+
+```bash
+lark-cli slides +replace-pages \
+  --as user \
+  --presentation <slides_url_or_xml_presentation_id> \
+  --pages @pages.json
+```
+
+## 参数
+
+| 参数 | 必需 | 说明 |
+|------|------|------|
+| `--presentation` | 是 | `xml_presentation_id`、`/slides/` URL 或 `/wiki/` URL |
+| `--pages` | 是 | JSON 数组，每项包含 `slide_id` 和 `content`；支持 literal、`@file`、stdin `-` |
+| `--dry-run` | 否 | 基于 `slide_id` 输入输出替换计划，不执行 create/delete |
+| `--continue-on-error` | 否 | 默认失败即停；开启后继续处理后续页，并在结果中标记失败项 |
+| `--validate-only` | 否 | 只校验输入并生成替换计划，不执行 Slides get/create/delete |
+
+## pages.json
+
+```json
+[
+  {
+    "slide_id": "slide_short_id_1",
+    "content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data></data></slide>"
+  },
+  {
+    "slide_id": "slide_short_id_2",
+    "content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data></data></slide>"
+  }
+]
+```
+
+规则：
+
+- 每项必须提供 `slide_id`；不支持 `slide_number`。
+- `content` 必须是完整 `<slide>...</slide>` XML。
+- 同一批次不能重复 `slide_id`。
+- CLI 不会回读整份 presentation；如果 `slide_id` 已失效，create/delete 阶段会返回对应错误。
+
+## Dry Run
+
+```bash
+lark-cli slides +replace-pages --as user \
+  --presentation "$PID" \
+  --pages @pages.json \
+  --dry-run
+```
+
+输出包含 `xml_presentation_id`、`pages_count`、`plan`，以及每页的 `old_slide_id`、`insert_before_slide_id` 和动作 `create_before_then_delete_old`。Dry-run 只基于输入的 `slide_id` 构造计划，不会调用 `xml_presentations.get`，也不会执行 create/delete。
+
+## 成功输出
+
+```json
+{
+  "xml_presentation_id": "xxx",
+  "pages_count": 2,
+  "status": "completed",
+  "summary": {
+    "replaced": 2,
+    "failed": 0,
+    "total": 2
+  },
+  "results": [
+    {
+      "old_slide_id": "old3",
+      "new_slide_id": "new3",
+      "status": "replaced"
+    }
+  ],
+  "revision_id": 123
+}
+```
+
+如果使用 `--continue-on-error` 且任一页面失败，CLI 会继续处理后续页，但最终以 partial failure 非零退出；stdout 仍保留完整 `results`，顶层 `ok` 为 `false`，`status` 为 `partial_failure`。
+
+`status` 可能为：
+
+- `replaced`：新页创建成功，旧页删除成功。
+- `create_failed`：新页创建失败，旧页保留。
+- `delete_failed`：新页已创建，但旧页删除失败。
+
+## 使用建议
+
+1. 大幅改写前先 `xml_presentations.get` 保存当前 XML，并记录要替换页面的 `slide_id`。
+2. 生成只含 `slide_id` 的 `pages.json` 后先跑 `--dry-run` 或 `--validate-only`。
+3. 默认不要开 `--continue-on-error`，除非能接受部分页面已替换。
+4. 替换后再回读全文 XML 并截图检查，确认页序、视觉和文本没有破损。

skills/lark-slides/references/lark-slides-screenshot.md

@@ -0,0 +1,94 @@
+# slides +screenshot
+
+## 用途
+
+获取幻灯片页面截图并保存为本地图片文件。默认用于已存在 PPT 页面截图；传入 `--content` 时用于直接渲染单个 `<slide>` XML 片段预览。本 shortcut 会在 CLI 进程内解码并写入文件，stdout 只返回文件路径、大小、页面 ID 等元信息，避免把图片 Base64 输出给模型。
+
+注意：该截图能力对应的权限受白名单控制。只有在白名单内的应用才能申请该权限；不在白名单内的应用即使命令和参数正确，服务端仍可能返回权限或能力不可用相关错误。
+
+## 命令
+
+```bash
+lark-cli slides +screenshot --as user \
+  --presentation '<xml_presentation_id 或 slides/wiki URL>' \
+  --slide-number 1
+```
+
+渲染本地 XML 内容：
+
+```bash
+lark-cli slides +screenshot --as user \
+  --content @slide.xml
+```
+
+## 参数
+
+| 参数 | 必需 | 说明 |
+|------|------|------|
+| `--presentation` | list 模式必需 | `xml_presentation_id`、`/slides/` URL，或解析后为 slides 的 `/wiki/` URL。传 `--content` 时不能使用 |
+| `--slide-id` | list 模式至少提供 `--slide-id` / `--slide-number` 之一 | 页面 short ID；多页截图时重复传入 |
+| `--slide-number` | list 模式至少提供 `--slide-id` / `--slide-number` 之一 | 页面页号；多页截图时重复传入 |
+| `--content` | render 模式必需 | 要直接渲染的 `<slide>` XML 片段；支持直接传值、`@file`、`-` stdin。传入后不能同时传 `--slide-id` / `--slide-number` |
+| `--output-dir` | 否 | 输出目录，默认 `.lark-slides/screenshots`；必须是当前目录内的相对路径 |
+| `--output-name` | 否 | render 模式的输出文件名 stem；未指定时优先用返回的 `slide_id`，否则用 `rendered-slide`。若目标文件已存在，会自动追加递增后缀避免覆盖 |
+
+## 示例
+
+### 单页截图
+
+```bash
+lark-cli slides +screenshot --as user \
+  --presentation slides_example_presentation_id \
+  --slide-number 1
+```
+
+### 多页截图
+
+```bash
+lark-cli slides +screenshot --as user \
+  --presentation slides_example_presentation_id \
+  --slide-number 1 \
+  --slide-number 2 \
+  --output-dir .lark-slides/screenshots/demo
+```
+
+### 渲染 XML 预览
+
+```bash
+lark-cli slides +screenshot --as user \
+  --content @.lark-slides/out/demo/slide.xml \
+  --output-name preview
+```
+
+## 返回值
+
+返回 JSON 不包含 Base64 图片内容：
+
+```json
+{
+  "code": 0,
+  "data": {
+    "xml_presentation_id": "slides_example_presentation_id",
+    "output_dir": ".lark-slides/screenshots",
+    "screenshots": [
+      {
+        "slide_id": "slide_example_id",
+        "slide_number": 1,
+        "format": "png",
+        "path": "/abs/path/.lark-slides/screenshots/slides_example_presentation_id_p001_slide_example_id.png",
+        "size": 12345
+      }
+    ]
+  },
+  "msg": "success"
+}
+```
+
+## 注意事项
+
+1. 优先使用 `slides +screenshot` 保存本地图片，不要把图片 Base64 打到 stdout。
+2. 已存在 PPT 页面截图时，不传 `--content`，用 `--presentation` + `--slide-id` 或 `--slide-number`。
+3. 本地 XML 预览时，传 `--content @file` 或 `--content -`，内容应为单个 `<slide>` XML 片段；此时不要传 `--presentation` / `--slide-id` / `--slide-number`。
+4. `slide_id` 是页面 short ID，页码请用 `--slide-number`。
+5. list 模式默认文件名包含 presentation ID、页码和/或 slide ID；文件已存在时自动追加 `_2`、`_3` 等后缀，避免覆盖旧截图。
+6. 截图来自服务端渲染结果，适合创建/替换后验证页面是否为空白、破图或布局明显异常。

skills/lark-slides/references/lark-slides-xml-presentation-slide-get.md

@@ -2,7 +2,7 @@
 
 ## 用途
 
-按 `slide_id` 拉取指定演示文稿单页的 XML 内容（可指定历史版本）。常用于"读-改-写"编辑闭环的第一步。
+按 `slide_id` 或 1-based `slide_number` 拉取指定演示文稿单页的 XML 内容（可指定历史版本）。常用于"读-改-写"编辑闭环的第一步。
 
 ## 命令
 
@@ -22,6 +22,7 @@ lark-cli slides xml_presentation.slide get --as user --params '<json_params>'
 {
   "xml_presentation_id": "slides_example_presentation_id",
   "slide_id": "slide_example_id",
+  "slide_number": 1,
   "revision_id": -1
 }
 ```
@@ -29,12 +30,13 @@ lark-cli slides xml_presentation.slide get --as user --params '<json_params>'
 | 字段 | 类型 | 必需 | 说明 |
 |------|------|------|------|
 | `xml_presentation_id` | string | 是 | 目标演示文稿唯一标识 |
-| `slide_id` | string | 是 | 目标页面唯一标识 |
+| `slide_id` | string | 否 | 目标页面唯一标识；与 `slide_number` 同时传时优先使用 `slide_id` |
+| `slide_number` | integer | 否 | 目标页码，从 1 开始；未传 `slide_id` 时可用 |
 | `revision_id` | integer | 否 | 版本号，`-1` 表示最新版（默认）|
 
 ## 使用示例
 
-### 读最新版本
+### 按 slide_id 读最新版本
 
 ```bash
 lark-cli slides xml_presentation.slide get --as user --params '{
@@ -43,6 +45,15 @@ lark-cli slides xml_presentation.slide get --as user --params '{
 }'
 ```
 
+### 按页码读取
+
+```bash
+lark-cli slides xml_presentation.slide get --as user --params '{
+  "xml_presentation_id": "slides_example_presentation_id",
+  "slide_number": 2
+}'
+```
+
 ### 只提取 XML 内容
 
 ```bash
@@ -87,14 +98,15 @@ lark-cli slides xml_presentation.slide get --as user --params '{
 
 | 错误码 | 含义 | 解决方案 |
 |--------|------|----------|
-| 404 | 演示文稿或页面不存在 | 检查 `xml_presentation_id` / `slide_id` |
+| 404 | 演示文稿或页面不存在 | 检查 `xml_presentation_id` / `slide_id` / `slide_number` |
 | 403 | 权限不足 | 需要 `slides:presentation:read` scope，并对该 PPT 有访问权限 |
 | 400 | `revision_id` 不存在 | 传了无效版本号，用 `-1` 或真实存在的版本号 |
 
 ## 注意事项
 
 1. **执行前必做**：`lark-cli schema slides.xml_presentation.slide.get` 查看最新参数结构
-2. **block_id 提取**：返回 XML 里每个顶层块（shape、img、table、chart、whiteboard 等）的 `id` 属性即为 `block_id`，通常是 3 字符短码，例如 `<shape id="bUn" ...>`。用以下命令列出当前页所有 block_id：
+2. **选择器优先级**：`slide_id` 和 `slide_number` 至少传一个；如果同时传，CLI 会以 `slide_id` 为准。
+3. **block_id 提取**：返回 XML 里每个顶层块（shape、img、table、chart、whiteboard 等）的 `id` 属性即为 `block_id`，通常是 3 字符短码，例如 `<shape id="bUn" ...>`。用以下命令列出当前页所有 block_id：
 
    ```bash
    lark-cli slides xml_presentation.slide get --as user \

skills/lark-slides/references/lark-slides-xml-presentations-get.md

@@ -21,7 +21,8 @@ lark-cli slides xml_presentations get --as user --params '<json_params>'
 ```json
 {
   "xml_presentation_id": "slides_example_presentation_id",
-  "revision_id": -1
+  "revision_id": -1,
+  "remove_attr_id": false
 }
 ```
 
@@ -29,6 +30,7 @@ lark-cli slides xml_presentations get --as user --params '<json_params>'
 |------|------|------|------|
 | `xml_presentation_id` | string | 是 | 演示文稿的唯一标识符 |
 | `revision_id` | integer | 否 | 版本号，`-1` 表示最新版本 |
+| `remove_attr_id` | boolean | 否 | 是否移除返回 XML 中的 `id` 属性；默认 `false` |
 
 ## 使用示例
 
@@ -44,6 +46,15 @@ lark-cli slides xml_presentations get --as user --params '{"xml_presentation_id"
 lark-cli slides xml_presentations get --as user --params '{"xml_presentation_id":"slides_example_presentation_id"}' | jq -r '.data.xml_presentation.content'
 ```
 
+### 移除 XML id 属性读取
+
+```bash
+lark-cli slides xml_presentations get --as user --params '{
+  "xml_presentation_id": "slides_example_presentation_id",
+  "remove_attr_id": true
+}'
+```
+
 ### 保存到文件
 
 ```bash
@@ -88,8 +99,9 @@ lark-cli slides xml_presentations get --as user --params '{"xml_presentation_id"
 
 1. **执行前必做**: 使用 `lark-cli schema slides.xml_presentations.get` 查看最新的参数结构
 2. 返回的 XML 在 `data.xml_presentation.content` 字段中
-3. 如果只需要部分信息，可以使用 `jq` 等工具过滤返回结果
-4. 建议将获取的 XML 保存为文件，便于后续编辑或备份
+3. `remove_attr_id=true` 会移除返回 XML 中的元素 `id` 属性，适合在重复 id 导致全文读取失败时兜底；但返回内容无法直接用于依赖 `block_id` 的精确替换、插入、评论定位等操作
+4. 如果只需要部分信息，可以使用 `jq` 等工具过滤返回结果
+5. 建议将获取的 XML 保存为文件，便于后续编辑或备份
 
 ## 相关命令
 

skills/lark-slides/references/planning-layer.md

@@ -1,77 +1,106 @@
-# Planning Layer
+# 规划层
 
-新建演示文稿或大幅改写页面时，必须先写 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`，再生成 XML。这个文件是 deck 的设计中间层，用来把叙事、页面角色、布局、视觉重点和文字密度固定下来，避免从用户提示直接跳到 XML。
+新建演示文稿或大幅改写页面时，必须先写 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`，再生成 XML。这个文件是演示文稿的设计中间层，用来把叙事、页面角色、布局、视觉重点和文字密度固定下来，避免从用户提示直接跳到 XML。
 
-小型已有页编辑可豁免，例如只替换一个标题、改一个数字、插入一个块、上传并插入一张图。只要任务会重排多页、生成新 deck、替换整页结构，仍然需要规划层。
+小型已有页编辑可豁免，例如只替换一个标题、改一个数字、插入一个块、上传并插入一张图。只要任务会重排多页、生成新演示文稿、替换整页结构，仍然需要规划层。
 
-## Required Flow
+## 必需流程
 
 1. 理解用户需求，必要时澄清主题、受众、页数、风格。
-2. 如果适合模板，先用 `template_tool.py search` 检索，锁定模板后用 `summarize` 获取主题和页型信息。
-3. 选择唯一 plan 目录：`.lark-slides/plan/<deck-or-task-id>/`。
+2. 激活素材处理层：按 `asset-planning.md` 解析提示词中的附件路径、素材目录、上传文件名和链接，盘点用户提供的本地素材、可引用链接和缺口素材；本地素材优先，没有合适本地素材时再使用内置模板或联网搜索。
+3. 选择唯一规划目录：`.lark-slides/plan/<deck-or-task-id>/`。
 4. 先创建目录：`mkdir -p .lark-slides/plan/<deck-or-task-id>`。
 5. 写入 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`。
 6. 读取 `xml-schema-quick-ref.md`、`visual-planning.md` 和 `asset-planning.md`。
-7. 按 plan、visual planning 和 asset planning 规则逐页生成 XML，把 `layout_type`、`visual_focus`、`text_density` 转成具体页面几何和文本量约束，并把缺失素材转成可执行兜底视觉。
-8. 创建 PPT 后用 `xml_presentations.get` 回读，核对页面数量、关键元素和 plan 到 XML 的对应关系。
+7. 按规划文件、视觉规划和素材规划规则逐页生成 XML，把 `layout_type`、`visual_focus`、`text_density` 转成具体页面几何和文本量约束，并把缺失素材转成可执行兜底视觉。
+8. 创建或大幅改写后，按 `validation-checklist.md` 做显式验证；本文件只要求验证记录能说明规划到 XML 的对应关系。
 
-模板不能代替 plan。模板搜索和摘要只能影响 `theme_style`、页面流、布局选择和局部布局骨架；最终仍必须有 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`。
+素材和模板不能代替规划文件，但素材处理层可以决定材料角色、目标 presentation、改写方式和资产复用策略；最终仍必须有 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`。
 
-## Plan Path
+可导入为 slides 的用户材料（`.pptx`、`.pdf` 或已有 online slides）参与制作/改写 PPT 时，默认是 `rewrite_source`：先导入或回读为 slides，`target_xml_presentation_id` 默认等于导入/已有 presentation，并在该 presentation 内继续创作。
 
-Use a separate plan directory per deck or task so multiple presentations in the same workspace cannot overwrite each other.
+“内容不可用”“只作为背景模板”“不要使用模板文字”“只参考风格”只排除 `copy_source`，不排除 `rewrite_source`。这类材料仍要导入/回读，并在导入后的 presentation 内替换、插入或删除页面内容。只有用户明确要求另建，或导入失败/`xml_presentations.get` 无法回读时，才新建演示文稿，并在 plan 中写明原因。
 
-Recommended IDs:
+如果大 PDF 模板只用于二次创作的视觉底稿，可先按 `asset-planning.md` 选择关键模板页生成压缩版 PDF，再导入这个小 PDF。纯导入、归档、格式转换或用户要求保留完整 PDF 页序的任务，不做切割。
 
-- New deck before creation: title slug plus date/time, such as `q3-review-20260507-1805`.
-- Existing PPT rewrite: the `xml_presentation_id`.
-- Ambiguous or untitled task: short task slug plus date/time.
+不要把附件路径只当作提示词文本。像 `附件文件路径：path/to/report.docx` 这样的路径必须解析到真实文件；相对路径按当前工作目录和用户明确给出的素材根目录解析，不能硬编码某个固定附件目录。
 
-Rules:
+## 规划路径
 
-- Do not reuse `.lark-slides/plan/slide_plan.json` as a shared path.
-- Create the directory before writing the file.
-- Reuse the same plan path for XML generation and post-create verification for that deck.
+每个演示文稿或任务使用独立的规划目录，避免同一工作区内多个演示文稿相互覆盖。
 
-## Artifact Lifecycle
+推荐 ID：
 
-`.lark-slides/` is local agent state. It supports recovery, iteration, and later edits, but it should not be treated as source code or committed by default.
+- 新建演示文稿：标题短标识加日期时间，例如 `q3-review-20260507-1805`。
+- 改写已有 PPT：使用 `xml_presentation_id`。
+- 主题不明确或未命名任务：短任务标识加日期时间。
 
-Keep:
+规则：
 
-- `.lark-slides/plan/<deck-or-task-id>/slide_plan.json` after successful creation or major rewrite. The plan is the editable design state for the deck.
-- A small manifest when useful for follow-up work, such as `xml_presentation_id`, slide IDs, `revision_id`, plan path, and verification status.
+- 不要复用 `.lark-slides/plan/slide_plan.json` 作为共享路径。
+- 写文件前先创建目录。
+- 同一个演示文稿的 XML 生成和创建后验证必须复用同一个规划路径。
 
-Clean or avoid keeping:
+## 产物生命周期
 
-- Transient XML payloads after successful creation and verification. Prefer `/tmp` for throwaway XML, or delete generated XML files after success.
-- Stale XML drafts that no longer match the current presentation state.
+`.lark-slides/` 是本地智能体状态，用于恢复、迭代和后续编辑；默认不要把它当作源码提交。
 
-Exception:
+保留：
 
-- If creation fails or partially succeeds, keep the relevant XML/debug payloads until recovery is complete. Record `xml_presentation_id` first, then fetch current state before retrying.
+- 创建成功或完成大幅改写后，保留 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`。规划文件是该演示文稿后续可编辑的设计状态。
+- 对后续工作有帮助时，保留小型清单，例如 `xml_presentation_id`、页面 ID、`revision_id`、规划路径和验证状态。
 
-## JSON Shape
+清理或避免保留：
+
+- 创建和验证成功后的临时 XML 请求内容。一次性 XML 优先放在 `/tmp`，或成功后删除生成的 XML 文件。
+- 已不匹配当前演示文稿状态的陈旧 XML 草稿。
+
+例外：
+
+- 如果创建失败或部分成功，保留相关 XML 或调试请求内容，直到恢复完成。先记录 `xml_presentation_id`，再拉取当前状态后重试。
+
+## JSON 结构
 
 ```json
 {
-  "presentation_goal": "Explain the proposal and secure approval for the next phase.",
-  "audience": "Product and engineering leaders who know the domain but need a concise decision narrative.",
-  "theme_style": "Clean business style, light background, restrained blue accent, strong visual hierarchy.",
+  "presentation_goal": "说明方案并争取下一阶段批准。",
+  "audience": "了解领域背景、但需要简洁决策叙事的产品和工程负责人。",
+  "theme_style": "清爽商务风格，浅色背景，克制蓝色强调，视觉层级清晰。",
+  "material_inventory": {
+    "local_first": true,
+    "inputs": [
+      {
+        "source": "./reference.pdf",
+        "resolved_path": "./reference.pdf",
+        "kind": "rewrite_source",
+        "usage": "导入为在线幻灯片后，在导入 presentation 内二次创作。",
+        "status": "imported",
+        "imported_xml_presentation_id": "SOURCE_PRESENTATION_ID",
+        "target_xml_presentation_id": "SOURCE_PRESENTATION_ID",
+        "template_asset_strategy": "rebuild_in_imported_presentation"
+      }
+    ],
+    "missing": [
+      {
+        "need": "产品界面截图",
+        "search_policy": "仅在没有本地截图时搜索；否则使用 XML 原生兜底视觉。"
+      }
+    ]
+  },
   "visual_system": {
-    "background_strategy": "Content pages use one light base; cover and closing may use a related dark treatment with the same accent system.",
-    "motif": "A reusable left accent bar and consistent card/header treatments.",
+    "background_strategy": "内容页使用统一浅色基底；封面和结尾页可使用同一强调色体系下的深色处理。",
+    "motif": "可复用的左侧强调条，以及一致的卡片和页眉处理。",
     "color_roles": {
-      "primary": "Used for the dominant structural motif and about 60-70% of visual weight.",
-      "secondary": "Used for grouped regions, comparison panels, or supporting categories.",
-      "accent": "Used only for key numbers, conclusions, or focus markers."
+      "primary": "用于主要结构母题，占约 60-70% 的视觉权重。",
+      "secondary": "用于分组区域、对比面板或辅助类别。",
+      "accent": "仅用于关键数字、结论或焦点标记。"
     }
   },
   "typography_constraints": {
     "title_max_lines": 2,
     "body_max_lines_per_box": 2,
     "footer_max_lines": 1,
-    "long_text_handling": "Shorten, split into multiple boxes, or move detail to speaker notes instead of shrinking into a tight box."
+    "long_text_handling": "先缩短、拆分到多个文本框，或把细节移到演讲者备注；不要靠极小字号硬塞。"
   },
   "verification_plan": {
     "check_background_consistency": true,
@@ -82,49 +111,50 @@ Exception:
   "slides": [
     {
       "page": 1,
-      "title": "Proposal Title",
-      "key_message": "The initiative is ready for a focused pilot.",
+      "title": "方案标题",
+      "key_message": "该方向已经具备小范围试点条件。",
       "layout_type": "title-cover",
-      "visual_focus": "Large title area with one concise supporting statement.",
+      "visual_focus": "大标题区域配一条简洁支撑语。",
       "asset_need": {
         "asset_type": "logo",
-        "purpose": "Signal product or team identity on the opening page.",
-        "suggested_query": "product logo",
-        "fallback_if_missing": "Use a small text badge and abstract shape motif instead of a real logo."
+        "purpose": "在开场页传达产品或团队身份。",
+        "suggested_query": "产品标志",
+        "fallback_if_missing": "使用小型文字徽标和抽象形状母题替代真实标志。"
       },
       "text_density": "low",
-      "speaker_intent": "Frame the decision and establish the deck's point of view."
+      "speaker_intent": "界定本次决策问题，并建立整份演示文稿的观点。"
     }
   ]
 }
 ```
 
-## Required Fields
+## 必需字段
 
-Top-level fields:
+顶层字段：
 
-- `presentation_goal`: what the whole deck is trying to achieve.
-- `audience`: target readers or listeners and their assumed background.
-- `theme_style`: visual tone, palette direction, and professional style.
-- `visual_system`: deck-level visual rules that must stay stable across pages, including background strategy, recurring motif, and color roles.
-- `typography_constraints`: deck-level limits for line count, text box density, and how to handle long text before XML generation.
-- `verification_plan`: explicit checks to perform after creation or major edits; include background consistency, text fit, visual focus, and asset rendering when relevant.
-- `slides`: ordered page plans.
+- `presentation_goal`：整份演示文稿要达成的目标。
+- `audience`：目标读者或听众，以及他们默认具备的背景。
+- `theme_style`：视觉语气、配色方向和专业风格。
+- `material_inventory`：规划层对本地输入、链接参考、选定用途、缺失素材、搜索策略和兜底方案的记录。遵循 `asset-planning.md`。
+- `visual_system`：演示文稿级视觉规则，必须跨页稳定，包括背景策略、复用母题和颜色角色。
+- `typography_constraints`：演示文稿级文字行数、文本框密度和长文本处理限制，用于约束 XML 生成前的文案。
+- `verification_plan`：最终验证记录必须覆盖的规划专属检查项。创建后的详细验证见 `validation-checklist.md`。
+- `slides`：有序页面计划。
 
-Each slide must include:
+每一页必须包含：
 
-- `page`: 1-based page number.
-- `title`: slide title.
-- `key_message`: the one idea this page must land.
-- `layout_type`: planned page structure.
-- `visual_focus`: dominant visual object or region.
-- `asset_need`: planning-only structured asset metadata; no search, download, or upload required. Follow `asset-planning.md`.
-- `text_density`: `low`, `medium`, or `high`.
-- `speaker_intent`: why the speaker needs this page and how it advances the story.
+- `page`：从 1 开始的页码。
+- `title`：页面标题。
+- `key_message`：本页必须传达的单一核心观点。
+- `layout_type`：计划使用的页面结构。
+- `visual_focus`：主导视觉对象或区域。
+- `asset_need`：仅用于规划的结构化素材元数据；不要求立即搜索、下载或上传。遵循 `asset-planning.md`。
+- `text_density`：`low`、`medium` 或 `high`。
+- `speaker_intent`：演讲者为什么需要这一页，以及它如何推进叙事。
 
-## Layout Vocabulary
+## 布局词表
 
-Use one of these `layout_type` values unless the user explicitly needs a custom structure:
+除非用户明确需要自定义结构，否则使用以下 `layout_type` 值之一：
 
 - `title-cover`
 - `section-divider`
@@ -139,81 +169,101 @@ Use one of these `layout_type` values unless the user explicitly needs a custom
 - `quote-highlight`
 - `conclusion`
 
-The value must affect XML geometry, not just appear as a label. For example, `timeline` should create a horizontal or vertical sequence, `comparison` should create distinct side-by-side regions, and `big-number` should reserve dominant space for a large metric.
+该值必须影响 XML 几何结构，不能只是标签。例如，`timeline` 应生成横向或纵向序列，`comparison` 应生成清晰并排区域，`big-number` 应为大指标保留主导空间。
 
-## Text Density Rules
+## 文字密度规则
 
-- `low`: title plus 1 short statement, or 1-3 very short labels.
-- `medium`: title plus 2-4 concise bullets or labeled regions.
-- `high`: allowed only when the user needs detail; use tables, columns, or grouped regions instead of a long bullet list.
+- `low`：标题加 1 条短陈述，或 1-3 个很短的标签。
+- `medium`：标题加 2-4 条简洁要点，或 2-4 个带标签区域。
+- `high`：仅在用户确实需要细节时使用；优先用表格、分栏或分组区域，不要使用长项目符号列表。
 
-Do not let all pages become title + bullet slides. For decks of 4 or more pages, aim for at least 4 different `layout_type` values when the content allows it.
+不要让所有页面都变成“标题 + 项目符号”。对于 4 页及以上的演示文稿，在内容允许时尽量使用至少 4 种不同的 `layout_type`。
 
-Text density must be realistic for the planned geometry. If a page needs long titles, bilingual labels, paper figure captions, legal disclaimers, or dense technical wording, record how the text will be shortened, split, or moved to speaker notes. Do not rely on small font sizes or tight boxes to make text fit.
+文字密度必须匹配计划中的几何结构。如果页面需要长标题、双语标签、论文图注、法律声明或密集技术表述，必须记录如何缩短、拆分或移到演讲者备注。不要依赖小字号或紧凑文本框来塞下内容。
 
-## Visual System Planning
+## 视觉系统规划
 
-Before generating XML, define a visual system that can survive the whole deck:
+生成 XML 前，定义能贯穿整份演示文稿的视觉系统：
 
-- `background_strategy`: specify the default background for normal content pages, and which page roles may intentionally differ. Do not let pages drift through near-identical but inconsistent background colors.
-- `motif`: choose one or two reusable structural devices, such as a side bar, header rail, numbered node, card treatment, diagram lane, or section band. The motif should appear consistently enough that pages feel related.
-- `color_roles`: assign primary, secondary, and accent roles. The same color must not mean unrelated things across pages.
-- `cover_content_relationship`: if the cover uses a different dark or image-led treatment, state how it connects to content pages through shared colors, motifs, or geometry.
-- `closing_relationship`: if the closing page mirrors the cover, state that explicitly so it looks intentional rather than like a new theme.
+- `background_strategy`：说明普通内容页的默认背景，以及哪些页面角色可以有意不同。不要让页面使用接近但不一致的背景色。
+- `motif`：选择一到两个可复用结构装置，例如侧边栏、页眉轨道、编号节点、卡片处理、图示泳道或章节色带。母题要足够一致，让页面看起来属于同一套设计。
+- `color_roles`：分配主色、辅助色和强调色角色。同一种颜色不能在不同页面表达无关含义。
+- `cover_content_relationship`：如果封面使用不同的深色或图片主导处理，说明它如何通过共享颜色、母题或几何关系连接内容页。
+- `closing_relationship`：如果结尾页呼应封面，明确写出，避免看起来像临时换了主题。
 
-These are planning constraints, not decoration notes. They must affect coordinates, background fills, shape styles, and text placement in generated XML.
+这些是规划约束，不是装饰备注。它们必须影响生成 XML 中的坐标、背景填充、形状样式和文本位置。
 
-## Iterative Deck State
+## 迭代状态
 
-When continuing an existing deck, update the same plan path rather than creating a new disconnected plan. Keep the plan aligned with what has actually been created.
+继续编辑已有演示文稿时，更新同一个规划路径，不要创建脱节的新规划文件。规划文件必须和已经实际创建的内容保持一致。
 
-Recommended optional fields for long-running work:
+长任务推荐使用的可选字段：
 
-- `deck_status`: current slide count, target slide count if known, and last verified revision or timestamp.
-- `created_slides`: page number, slide id when known, and the page role.
-- `assets_used`: source, local path when applicable, uploaded token when known, and which page uses it.
-- `open_issues`: known layout, text fit, asset, or consistency risks that still need correction.
+- `deck_status`：当前页数、已知目标页数，以及最后验证的版本或时间戳。
+- `created_slides`：页码、已知页面 ID 和页面角色。
+- `assets_used`：来源、适用时的本地路径、已知上传令牌，以及使用它的页面。
+- `open_issues`：仍需修正的布局、文本适配、素材或一致性风险。
 
-Do not hard-code a page number just because a previous deck used that pattern. Plan by page role and evidence need, such as "method overview pages should use a figure when the source has a readable figure" instead of binding screenshots, charts, or diagrams to a fixed page index. The plan should describe decision rules, not a rigid template sequence.
+不要因为之前的演示文稿用过某个模式就硬编码页码。应按页面角色和证据需求规划，例如“来源中有可读图时，方法概览页应使用图”，而不是把截图、图表或示意图绑定到固定页码。规划文件应描述决策规则，而不是僵硬模板序列。
 
-## Asset Planning
+## 素材规划
 
-`asset_need` is metadata. It can describe a desired figure, diagram, chart, icon, logo, screenshot, or fallback shape-based visual, but it must not require web search, local download, or media upload.
+`material_inventory` 记录 XML 生成前的演示文稿级来源处理；`asset_need` 记录页面级视觉需求。两者都遵循 `asset-planning.md`。
 
-Use an object for one planned asset, an array for multiple real needs, or `asset_type: "none"` when no asset is useful. Each planned asset must include:
+本地素材优先于远程搜索。常见素材角色：
 
-- `asset_type`: one of `paper_figure`, `architecture_diagram`, `icon`, `logo`, `chart`, `infographic`, `screenshot`, `flow_diagram`, or `none`.
-- `purpose`: why this asset helps the page's key message.
-- `suggested_query`: short future lookup hint only; do not execute it unless separately requested.
-- `fallback_if_missing`: concrete XML-native visual plan using shapes, labels, tables, whiteboard diagrams, or placeholder panels.
+- `background_reference`：用于理解主题、事实、受众或约束的非模板文档或链接。
+- `visual_asset`：可能出现在页面中的图片、截图、标志、图标、图表、示意图或论文图。
+- `copy_source`：作为内容输入的正文、提纲、笔记、PRD、报告或转写稿。
+- `data_source`：用于图表或表格的数据表、CSV/XLSX、指标或结构化数值。
+- `rewrite_source`：导入后承载二次创作的目标底稿，可提供背景、版式、图片资产和页面结构；即使其文案不可用，也不应只当作宽泛视觉线索。
 
-For detailed rules and examples, read `asset-planning.md`.
+规划页面前，先解析所有附件路径，并写入 `material_inventory.inputs`。每个可用本地输入应包含：
 
-Good examples:
+- `source`：用户原始提供的路径或文件标签。
+- `resolved_path`：实际存在的本地路径；能被 `lark-cli` 使用时，优先记录相对当前工作目录的路径。
+- `kind`：一个或多个素材角色。
+- `usage`：它将如何影响叙事、视觉、数据或风格。
+- `status`：`available`、`imported`、`uploaded`、`read`、`skipped` 或 `missing`。
+- `notes`：可选映射细节，例如“用户提供的相对路径已按指定素材目录解析”。
 
-- `{"asset_type":"architecture_diagram","purpose":"Explain component relationships.","suggested_query":"service architecture diagram","fallback_if_missing":"Draw a component diagram with grouped boxes, connector arrows, and short labels."}`
-- `{"asset_type":"logo","purpose":"Identify the customer context.","suggested_query":"customer logo","fallback_if_missing":"Use a text label in a small badge."}`
-- `{"asset_type":"chart","purpose":"Show adoption trend.","suggested_query":"monthly adoption trend chart","fallback_if_missing":"Draw a simple trend line chart with axis labels and data points."}`
+如果附件是可导入为 slides 的用户材料，并已导入为在线幻灯片，在已知时记录 `imported_xml_presentation_id` 或 `import_ticket`。按 `asset-planning.md` 判断角色；默认把可作为视觉底稿的导入 XML 作为 `rewrite_source` 使用，并记录 `target_xml_presentation_id`。
 
-## XML Generation Contract
+对导入的用户材料，还要按 `asset-planning.md` 记录 `template_asset_strategy`：`preserve_imported_page`、`rebuild_in_imported_presentation` 或 `mixed`。在同一个已导入演示文稿内创建或替换页面时，可以复用导入页的图片令牌；不要把 `<img src>` 令牌直接复制到另一个新演示文稿。如果导入的在线幻灯片文件会成为编辑后的最终交付物，记录 `target_title`，并在编辑完成后重命名在线文件，避免仍保留源材料或附件标题。异常新建只能由用户明确要求另建，或导入失败/回读失败触发，并必须记录原因和图片资产迁移方式。
 
-Before writing each slide XML, map the plan fields to concrete decisions:
+如果附件是 `rewrite_source`，每个受影响页面计划都应说明来源页或来源章节，以及预期操作：`preserve`、`condense`、`expand`、`reorder`、`restyle`、`replace_visual_only` 或 `delete`。对于“内容不用改”类请求，默认使用 `replace_visual_only` 或 `restyle`，并保持原始论断、数字、名称和页面意图不变。对于“材料页数多于目标页数”的任务，先规划要保留或改写的来源页，再删除无关页；不要因为需要压缩页数就另建脱离材料的新 deck。
 
-- `key_message` determines the headline, dominant claim, or main takeaway.
-- `layout_type` determines the coordinate structure and element types. Use `visual-planning.md` for concrete layout rules.
-- `visual_focus` determines the largest visual region or emphasized object.
-- `text_density` caps visible text volume.
-- `asset_need` informs placeholder diagrams, icons, charts, screenshots, or shape-based fallback visuals only. Missing real assets must use `fallback_if_missing`, not blank regions.
+用户提供的 PDF/PPTX/slides 即使只参考风格，也不能脱离导入后的 presentation 新建；除非用户明确要求另建，或导入失败/回读失败。
 
-After creating the PPT, fetch the presentation and verify:
+单个计划素材使用对象，多个真实需求使用数组；没有有用素材时使用 `asset_type: "none"`。每个计划素材必须包含：
 
-- Page count matches the plan.
-- Every page has the planned title and key message represented.
-- At least several pages have visibly different XML layout structures.
-- Planned `visual_focus` appears as a dominant visual region or object.
-- Asset planning is proportional to the deck topic and length: technical, research, product, and analytical decks should include meaningful planned visuals where they clarify the story, and each planned asset has a visible fallback if no real asset was used.
-- `text_density` is reflected in the amount of visible text.
-- Pages are not crowded, and any planned `timeline`, `comparison`, or `architecture-diagram` page uses its matching visual structure.
-- The actual backgrounds match `visual_system.background_strategy`; any dark, image-led, or emphasis page has an intentional relationship to the rest of the deck.
-- Text boxes respect `typography_constraints`; long labels, captions, footer text, and conclusion bars are not squeezed into boxes that are too short for the intended line count.
-- If real assets are used, the final XML contains renderable asset tokens or supported local placeholders for creation, not http URLs, stale local paths, or blank image boxes.
+- `asset_type`：`paper_figure`、`architecture_diagram`、`icon`、`logo`、`chart`、`infographic`、`screenshot`、`flow_diagram` 或 `none`。
+- `purpose`：该素材为什么能帮助传达本页核心观点。
+- `suggested_query`：仅作为后续查找提示的短查询；除非另有要求，否则不要执行。
+- `fallback_if_missing`：使用形状、标签、表格、白板图或占位面板构成的具体 XML 原生兜底视觉方案。
+
+详细规则和示例见 `asset-planning.md`。
+
+合格示例：
+
+- `{"asset_type":"architecture_diagram","purpose":"解释组件关系。","suggested_query":"服务架构图","fallback_if_missing":"用分组方框、连接箭头和短标签绘制组件图。"}`
+- `{"asset_type":"logo","purpose":"标识客户场景。","suggested_query":"客户标志","fallback_if_missing":"使用小徽标中的文字标签。"}`
+- `{"asset_type":"chart","purpose":"展示采用率趋势。","suggested_query":"月度采用率趋势图","fallback_if_missing":"绘制带轴标签和数据点的简单趋势折线图。"}`
+
+## XML 生成约定
+
+写每页页面 XML 前，把规划字段映射成具体决策：
+
+- `key_message` 决定标题、主导论断或主要结论。
+- `material_inventory` 决定哪些本地素材、导入材料、文案来源、远程搜索结果或兜底方案允许影响页面。
+- `layout_type` 决定坐标结构和元素类型。具体布局规则见 `visual-planning.md`。
+- `visual_focus` 决定最大视觉区域或被强调对象。
+- `text_density` 限制可见文字量。
+- `asset_need` 只用于指导占位图、图标、图表、截图或基于形状的兜底视觉。缺失真实素材时必须使用 `fallback_if_missing`，不能留下空白区域。
+
+创建或改写 PPT 后，以 `validation-checklist.md` 作为验证依据。验证记录还应说明规划专属映射：
+
+- 页数与规划文件一致。
+- 计划中的 `key_message`、`layout_type`、`visual_focus`、`text_density` 和 `asset_need` 已体现在 XML 中。
+- `visual_system` 和 `typography_constraints` 明显影响了背景、结构、层级和文本位置。
+- 维护的 `deck_status`、`created_slides`、`assets_used` 或 `open_issues` 字段已更新为当前演示文稿状态。

skills/lark-slides/references/slides_xml_schema_definition.xml

@@ -150,7 +150,7 @@
     <xs:simpleType name="FontFamilyType">
         <xs:annotation>
             <xs:documentation>
-                字体族名称, 支持任意字体。
+                字体族名称, 支持下列字体。
 
                 常用中文字体：
                 思源宋体、寒蝉德黑体、标小智无界黑、寒蝉锦书宋、站酷小薇体、

skills/lark-slides/references/troubleshooting.md

@@ -23,6 +23,11 @@
 6. 如果使用 `--slides '[...]'`，怀疑 shell 截断时直接切到两步创建：先 `slides +create`，再用 `xml_presentation.slide.create` 逐页添加。
 7. 局部问题用 `+replace-slide` 块级修正；整页结构要改时再用 `slide.delete` 旧页 + `slide.create` 新页。
 
+## Imported Slides And Media Tokens
+
+- 由 `drive +import --type slides` 导入生成的页面，可能可读、可截图，但不保证支持后续 `+replace-slide` / `xml_presentation.slide.replace` 的块级编辑。遇到导入页块级编辑失败时，先回读确认内容；需要重做结构时，优先新建 XML-native 页面或重建对应页，而不是反复尝试块级替换。
+- 一个演示文稿中的图片 `file_token` 不能直接复用于另一个新建演示文稿。跨文稿复用图片时必须在目标演示文稿重新上传，或在 `+create --slides` 中使用 `@./relative/path` 占位符让 CLI 为新文稿上传并替换 token。
+
 ## Symptom Fixes
 
 | 看到的问题 | 处理方式 |
@@ -35,7 +40,9 @@
 | 图表没有显示 | 检查 `chartPlotArea` 和 `chartData` 是否都包含，`dim1` / `dim2` 数据数量是否匹配 |
 | 图片被裁掉一部分 | `<img>` 的 `width` / `height` 是裁剪后尺寸；要整图显示就让 `width:height` 对齐原图比例 |
 | 图片不显示 / `<img src>` 仍是 `@path` | `@` 占位符只在 `+create --slides` 中替换；直接调 `xml_presentation.slide.create` 必须先用 `+media-upload` 拿 `file_token` |
+| 新文稿里复用旧文稿的图片 `file_token` 后图片不显示 | `file_token` 不能跨演示文稿复用；在目标文稿重新 `+media-upload`，或新建时使用 `@./relative/path` 占位符 |
 | 新插入的 `<img>` 挡住原有元素 | `slide.get` 读原页，对照已有块坐标挑空白位置；空间不够就在同一批 `--parts` 里先移动/缩小现有块再插图 |
+| 导入的 PPTX/PDF 页面可读但 `+replace-slide` / `slide.replace` 失败 | 导入页不保证支持块级编辑；改为重建该页或新建 XML-native 页面，再删除/替换旧页 |
 | 渐变背景变成白色 | 渐变必须用 `rgba()` 格式 + 百分比停靠点，如 `linear-gradient(135deg,rgba(30,60,114,1) 0%,rgba(59,130,246,1) 100%)` |
 | 整体风格不统一 | 封面页和结尾页用同一背景，内容页保持一致的配色和字号体系 |
 

skills/lark-slides/references/validation-checklist.md

@@ -1,6 +1,6 @@
 # Validation Checklist
 
-创建或大幅改写演示文稿后，必须做一次显式验证。目标是发现空白页、XML 损坏、内容截断、明显溢出、弱视觉层级和未验证输出。
+创建或大幅改写演示文稿后，必须做一次显式验证。目标是发现空白页、XML 损坏、内容截断、异常换行、明显溢出、弱视觉层级和未验证输出。
 
 小型已有页编辑也要做对应范围的验证：至少读取被改页面或全文 XML，确认目标元素已更新且未破坏周边结构。
 
@@ -9,12 +9,15 @@
 1. 记录创建或编辑返回的 `xml_presentation_id`，以及已知的 `slide_id` / `revision_id`。
 2. 用 `xml_presentations.get` 回读全文 XML。
 3. 检查实际页数是否符合计划或用户要求。
-4. 检查每页 `<data>` 内是否有预期主要元素。
-5. 检查没有明显空白页、破损页、缺失标题或缺失主视觉。
-6. 检查页面不是全部退化为标题加 bullet list。
-7. 检查视觉层级：标题、主视觉、支撑信息三者可区分。
-8. 检查明显溢出和布局风险：重叠、越界、底部拥挤、长文本框。
-9. 在最终回复中给出简短验证记录。
+4. 如果计划基于导入 PDF/PPTX/slides 材料二次创作，检查最终 `xml_presentation_id` 是否等于 `target_xml_presentation_id`；如果另建了 presentation，必须在验证记录中说明用户明确要求另建或导入/回读失败原因。
+5. 如果用户材料只用于模板风格或视觉线索，检查它是否仍作为 `rewrite_source` 导入/回读，并确认最终没有交付脱离该材料的新 deck。
+6. 检查每页 `<data>` 内是否有预期主要元素。
+7. 检查没有明显空白页、破损页、缺失标题或缺失主视觉。
+8. 检查页面不是全部退化为标题加 bullet list。
+9. 检查视觉层级：标题、主视觉、支撑信息三者可区分。
+10. 检查没有遗留模板占位文案、示例公司名、示例日期或与用户主题无关的源模板文字。
+11. 检查明显溢出和布局风险：重叠、越界、底部拥挤、长文本框。
+12. 在最终回复中给出简短验证记录。
 
 回读命令：
 
@@ -34,7 +37,8 @@ python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentatio
 通过标准：
 
 - `summary.error_count == 0`。任何 error 都必须先修复再交付。
-- 当前工具只检查 XML well-formed 和文本元素之间的明显重叠；它不检查越界、文本高度不足、图文压盖、表格/图表压盖或底部拥挤。
+- 对异常换行、文本框高度不足等 wrap quality warning，默认也应修复后再交付；仅当它是普通正文的自然换行且用户明确允许时，才可在验证记录中说明豁免原因。
+- 当前工具检查 XML well-formed、文本元素之间的明显重叠，以及部分规则化异常换行；它不检查越界、图文压盖、表格/图表压盖或底部拥挤。
 - 该工具不能替代页数核对、关键内容核对或真实视觉验收。
 
 常见 code 的处理方向：
@@ -43,6 +47,15 @@ python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentatio
 |------|------|----------|
 | `xml_not_well_formed` | XML 语法错误或文本未转义 | 修复标签闭合、属性引号、`&` / `<` / `>` 转义 |
 | `bbox_overlap` | 文本元素的估算绘制区域明显重叠 | 拉开文本坐标、缩小文本框/字号，或改成明确的分栏/分组结构 |
+| `text_word_split` / `text_phrase_split` | 中文词语或高频短语被异常拆行 | 增宽文本框、降低字号、改写短语或调整换行点，避免把词语/短语拆开 |
+| `text_orphan_line` | 最后一行只有极短中文尾巴 | 增宽文本框、缩小字号或重排文本，让尾行形成可读短句 |
+| `text_unnecessary_wrap` | 短标题或强调文本本应单行却换行 | 增宽文本框或缩小字号，优先保持单行 |
+| `text_center_wrapped` | 非封面/金句场景的多行文本居中 | 改为左对齐，或调整为真正的封面/金句元素 |
+| `text_box_too_short` | 文本框高度低于字号所需高度 | 增加文本框高度、降低字号或减少文本量 |
+
+## Optional Screenshot Upgrade
+
+如果截图或可视化预览能力可用，优先获取页面截图辅助判断最终效果；截图不能替代 XML 回读和页数核对。
 
 ## Page Count And Structure
 
@@ -61,6 +74,8 @@ python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentatio
 - `visual_focus` 是页面中最醒目或最大的信息区域之一。
 - `text_density` 影响了文本量，没有用长 bullet 框替代规划。
 - `asset_need` 有真实素材时已放入正确区域；没有真实素材时，`fallback_if_missing` 已用 XML 形状、线条、标签、表格或图表兜底。
+- `template_asset_strategy` 为 `preserve_imported_page`、`rebuild_in_imported_presentation` 或 `mixed` 时，不能交付一份脱离导入材料的新 deck。
+- 如果计划声明保留材料背景、装饰图、品牌图或复杂图片版式，回读 XML 中应仍存在对应的 `<img src>`、背景图片或等效重绘结构；如果未保留，验证记录必须说明原因。
 
 如果用户指定了关键页，例如“架构解释”“Self-Attention 机制解释”“对比或演进视角”“总结页”，最终验证记录必须逐项说明这些页已存在。
 
@@ -89,6 +104,7 @@ python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentatio
 优先修复这些明显风险：
 
 - 正文或标签框高度不足，文本很可能被截断。
+- 标题、标签、卡片标题或强调文本出现异常换行，例如拆词、拆短语、短尾行或本应单行却换行。
 - 多个主体元素在同一区域重叠，而不是有意叠加背景。
 - 重要内容越过画布边界，或贴近底部超过 `y=500`。
 - 高密度页使用单个长 bullet list，没有分栏、表格或分组。
@@ -102,9 +118,14 @@ python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentatio
 ```text
 验证记录：
 - 回读：已执行 xml_presentations.get，实际页数 N / 预期 N。
+- 导入底稿：如使用导入材料二次创作，最终 presentation 与 target_xml_presentation_id 一致；如不一致，已说明用户明确要求另建或导入/回读失败原因。
+- 视觉底稿：如用户材料只提供模板风格或视觉线索，已确认它仍作为 rewrite_source 导入/回读并承载最终二创。
+- 内容来源：如模板材料内容不可用，已确认未复制其占位文案；正文来自计划中的 copy_source 或用户输入。
+- 截图：截图能力可用时，已用截图辅助判断最终效果。
 - 关键页：架构解释 / Self-Attention / 对比或演进 / 总结页均存在。
 - 结构：检查了主要 shape/img/table/chart 元素，无明显空白页或破损页。
+- 模板清理：未发现模板占位文案、示例公司名、示例日期或无关模板文字。
 - 布局：检查了标题层级、主视觉、重叠/越界/文本溢出风险。
 ```
 
-不要声称完成了人工视觉验收，除非确实打开或获取了可视化结果。仅从 XML 静态检查得出的结论，应表述为“静态检查未发现明显问题”。
+不要声称完成了截图或人工视觉验收，除非确实打开、获取截图或拿到了可视化结果。仅从 XML 静态检查得出的结论，应表述为“静态检查未发现明显问题”。

skills/lark-slides/references/xml-schema-quick-ref.md

@@ -74,7 +74,7 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 | `textAlign` | 文本对齐方式 |
 | `lineSpacing` | 行间距，schema 默认 `multiple:1.5` |
 | `fontSize` | 字号 |
-| `fontFamily` | 字体 |
+| `fontFamily` | 字体，必须来自 `slides_xml_schema_definition.xml` 的 `FontFamilyType` 清单 |
 | `color` | 字体颜色 |
 | `bold` / `italic` / `underline` / `strikethrough` | 文本样式 |
 

skills/lark-slides/scripts/xml_text_overlap_lint.py

@@ -17,6 +17,10 @@ class XmlTextOverlapLintError(Exception):
     pass
 
 
+TITLE_LIKE_TEXT_TYPES = {"title", "headline", "sub-headline", "card_title", "callout"}
+CENTER_ALLOWED_TEXT_TYPES = {"title", "quote", "hero"}
+
+
 def fail(message: str) -> None:
     raise XmlTextOverlapLintError(message)
 
@@ -71,10 +75,49 @@ def strip_xml(value: str) -> str:
     return re.sub(r"\s+", " ", stripped).strip()
 
 
+def collapse_space(value: str) -> str:
+    return re.sub(r"\s+", " ", value).strip()
+
+
+def chinese_char_count(value: str) -> int:
+    return len(re.findall(r"[\u4e00-\u9fff]", value))
+
+
+def chinese_text(value: str) -> str:
+    return "".join(re.findall(r"[\u4e00-\u9fff]", value))
+
+
 def xml_local_name(tag: str) -> str:
     return tag.rsplit("}", 1)[-1] if tag.startswith("{") else tag
 
 
+def extract_content_lines(content_xml: str) -> list[str]:
+    try:
+        root = ET.fromstring(f"<root>{content_xml}</root>")
+    except ET.ParseError:
+        text = strip_xml(content_xml)
+        return [text] if text else []
+
+    lines: list[str] = []
+    for content_node in root.iter():
+        if xml_local_name(content_node.tag) != "content":
+            continue
+        paragraph_lines: list[str] = []
+        for node in content_node.iter():
+            if xml_local_name(node.tag) != "p":
+                continue
+            line = collapse_space("".join(node.itertext()))
+            if line:
+                paragraph_lines.append(line)
+        if paragraph_lines:
+            lines.extend(paragraph_lines)
+        else:
+            line = collapse_space("".join(content_node.itertext()))
+            if line:
+                lines.append(line)
+    return lines
+
+
 def extract_error_context(xml: str, line: int | None, column: int | None, radius: int = 40) -> str | None:
     if line is None or column is None:
         return None
@@ -139,18 +182,23 @@ def extract_elements(slide_xml: str) -> list[dict[str, Any]]:
         height = extract_numeric_attribute(attrs, "height")
         if all(value is not None for value in [x, y, width, height]):
             font_size = float(extract_attribute(content, "fontSize") or extract_attribute(attrs, "fontSize") or 16)
+            lines = extract_content_lines(content)
+            raw_text = "\n".join(lines)
             elements.append(
                 {
                     "id": f"shape-{len(elements) + 1}",
                     "kind": "shape",
                     "type": extract_attribute(attrs, "type") or "shape",
                     "textType": extract_attribute(content, "textType"),
+                    "textAlign": extract_attribute(content, "textAlign") or extract_attribute(attrs, "textAlign"),
                     "x": x,
                     "y": y,
                     "width": width,
                     "height": height,
                     "fontSize": font_size,
                     "text": strip_xml(content),
+                    "rawText": raw_text,
+                    "lines": lines,
                 }
             )
 
@@ -294,10 +342,223 @@ def should_flag_overlap(left: dict[str, Any], right: dict[str, Any]) -> bool:
     return False
 
 
+def estimate_text_width(text: str, font_size: float) -> float:
+    width = 0.0
+    for char in text:
+        if re.match(r"[\u4e00-\u9fff]", char):
+            width += font_size
+        elif char.isspace():
+            width += font_size * 0.32
+        else:
+            width += font_size * 0.55
+    return width
+
+
+def estimated_rendered_line_count(element: dict[str, Any]) -> int:
+    return len(estimate_rendered_lines(element))
+
+
+def estimate_rendered_lines(element: dict[str, Any]) -> list[str]:
+    lines = [line for line in element.get("lines", []) if line]
+    if not lines:
+        return []
+    font_size = float(element.get("fontSize") or 16)
+    usable_width = max(float(element["width"]) - 6, 1)
+    rendered_lines: list[str] = []
+    for line in lines:
+        current = ""
+        current_width = 0.0
+        for char in line:
+            char_width = estimate_text_width(char, font_size)
+            if current and current_width + char_width > usable_width:
+                rendered_lines.append(current)
+                current = char
+                current_width = char_width
+                continue
+            current += char
+            current_width += char_width
+        if current:
+            rendered_lines.append(current)
+    return rendered_lines
+
+
+def has_insufficient_height_for_estimated_wrap(element: dict[str, Any], estimated_line_count: int) -> bool:
+    if estimated_line_count < 2:
+        return False
+    font_size = float(element.get("fontSize") or 16)
+    required_height = estimated_line_count * font_size * 1.12
+    return float(element["height"]) < required_height
+
+
+def has_too_short_text_box(element: dict[str, Any]) -> bool:
+    text = element.get("text") or ""
+    if chinese_char_count(text) < 6:
+        return False
+    font_size = float(element.get("fontSize") or 16)
+    return float(element["height"]) < font_size * 0.95
+
+
+def is_slash_separated_short_label(text: str) -> bool:
+    if "/" not in text:
+        return False
+    parts = [part.strip() for part in text.split("/") if part.strip()]
+    if len(parts) < 2:
+        return False
+    return chinese_char_count(text) <= 14 and all(chinese_char_count(part) <= 4 for part in parts)
+
+
+def is_short_display_text_auto_wrapped(element: dict[str, Any], rendered_lines: list[str]) -> bool:
+    if len(element.get("lines", [])) != 1 or len(rendered_lines) != 2:
+        return False
+    if element.get("textType") in {"title", "caption"}:
+        return False
+    text = element.get("text") or ""
+    chinese_count = chinese_char_count(text)
+    if not (4 <= chinese_count <= 20):
+        return False
+    font_size = float(element.get("fontSize") or 16)
+    if font_size < 20:
+        return False
+    if not has_insufficient_height_for_estimated_wrap(element, len(rendered_lines)):
+        return False
+    return chinese_count / max(len(text), 1) >= 0.6
+
+
+def build_wrap_issue(
+    code: str,
+    element: dict[str, Any],
+    message: str,
+    reason: str,
+) -> dict[str, Any]:
+    return {
+        "level": "warning",
+        "code": code,
+        "element": element["id"],
+        "message": message,
+        "reason": reason,
+        "repair": {
+            "prefer_single_line": True,
+            "allow_font_shrink": True,
+            "max_shrink_ratio": 0.9,
+            "avoid_center_align": True,
+        },
+    }
+
+
+def is_probable_cover_center_title(element: dict[str, Any]) -> bool:
+    text_type = element.get("textType")
+    if text_type == "quote":
+        return True
+    if text_type not in CENTER_ALLOWED_TEXT_TYPES:
+        return False
+    return element["x"] >= 120 and element["y"] >= 150 and element["width"] >= 300 and element["height"] >= 80
+
+
+def lint_wrap_quality(element: dict[str, Any]) -> list[dict[str, Any]]:
+    if not is_text_element(element) or not has_text_content(element):
+        return []
+
+    lines = [line for line in element.get("lines", []) if line]
+    rendered_lines = estimate_rendered_lines(element)
+    estimated_line_count = len(rendered_lines)
+    if len(lines) < 2 and estimated_line_count < 2 and not has_too_short_text_box(element):
+        return []
+
+    issues: list[dict[str, Any]] = []
+    raw_text = element.get("rawText") or "\n".join(lines)
+    joined_chinese = chinese_text("".join(lines))
+    joined_chinese_count = chinese_char_count(joined_chinese)
+    font_size = float(element.get("fontSize") or 16)
+
+    last_line_chinese_count = chinese_char_count(lines[-1])
+    previous_text_chinese_count = chinese_char_count("".join(lines[:-1]))
+    if (
+        len(lines) == 2
+        and 1 <= last_line_chinese_count <= 3
+        and previous_text_chinese_count >= 10
+    ):
+        issues.append(
+            build_wrap_issue(
+                "text_orphan_line",
+                element,
+                f"Last line is very short: {lines[-1]}",
+                "最后一行是过短尾行",
+            )
+        )
+
+    if has_too_short_text_box(element):
+        issues.append(
+            build_wrap_issue(
+                "text_box_too_short",
+                element,
+                f"Text box height is too short for font size: height={element['height']}, fontSize={font_size:g}",
+                "文本框高度低于字号所需高度，渲染后容易截断或压缩显示",
+            )
+        )
+
+    text_type = element.get("textType")
+    estimated_single_line_width = joined_chinese_count * font_size * 0.62
+    if (
+        text_type in TITLE_LIKE_TEXT_TYPES
+        and len(lines) >= 2
+        and 1 <= joined_chinese_count <= 20
+        and font_size >= 20
+        and font_size < 40
+        and chinese_char_count("".join(lines)) == len("".join(lines))
+        and element["width"] >= estimated_single_line_width
+    ):
+        issues.append(
+            build_wrap_issue(
+                "text_unnecessary_wrap",
+                element,
+                f"Short title-like text wraps unnecessarily: {joined_chinese}",
+                "短标题或强调文本不超过 20 个中文字符却出现换行",
+            )
+        )
+
+    if is_short_display_text_auto_wrapped(element, rendered_lines):
+        issues.append(
+            build_wrap_issue(
+                "text_unnecessary_wrap",
+                element,
+                f"Short display text is likely to wrap in a one-line box: {strip_xml(raw_text)}",
+                "短展示文本被放入过窄且只够一行高度的文本框，渲染后容易异常换行",
+            )
+        )
+
+    if (
+        (element.get("textAlign") or "").lower() == "center"
+        and (
+            (len(lines) >= 2 and font_size >= 22)
+            or (
+                len(lines) == 1
+                and joined_chinese_count >= 8
+                and has_insufficient_height_for_estimated_wrap(element, estimated_line_count)
+            )
+        )
+        and text_type not in {"title", "sub-headline", "quote", "hero"}
+        and not is_probable_cover_center_title(element)
+        and not is_slash_separated_short_label(raw_text)
+    ):
+        issues.append(
+            build_wrap_issue(
+                "text_center_wrapped",
+                element,
+                f"Centered multi-line text is hard to scan: {strip_xml(raw_text)}",
+                "非封面、非金句场景的多行文本使用居中对齐",
+            )
+        )
+
+    return issues
+
+
 def lint_slide(slide_xml: str, slide_number: int) -> dict[str, Any]:
     elements = extract_elements(slide_xml)
     issues: list[dict[str, Any]] = []
 
+    for element in elements:
+        issues.extend(lint_wrap_quality(element))
+
     for index, left in enumerate(elements):
         for right in elements[index + 1 :]:
             if not intersects(left, right) or not should_flag_overlap(left, right):

skills/lark-slides/scripts/xml_text_overlap_lint_wrap_test.py

@@ -0,0 +1,230 @@
+# Copyright (c) 2026 Lark Technologies Pte. Ltd.
+# SPDX-License-Identifier: MIT
+from __future__ import annotations
+
+import unittest
+
+import xml_text_overlap_lint
+
+
+def make_slide(shapes: str) -> str:
+    return f"""
+    <presentation xmlns="http://www.larkoffice.com/sml/2.0" width="960" height="540">
+      <slide xmlns="http://www.larkoffice.com/sml/2.0">
+        <data>{shapes}</data>
+      </slide>
+    </presentation>
+    """
+
+
+def text_shape(
+    lines: list[str],
+    *,
+    text_type: str = "body",
+    align: str = "left",
+    x: int = 120,
+    y: int = 120,
+    width: int = 360,
+    height: int = 120,
+    font_size: int = 28,
+) -> str:
+    paragraphs = "".join(f"<p>{line}</p>" for line in lines)
+    return f"""
+    <shape type="text" topLeftX="{x}" topLeftY="{y}" width="{width}" height="{height}">
+      <content textType="{text_type}" textAlign="{align}" fontSize="{font_size}">
+        {paragraphs}
+      </content>
+    </shape>
+    """
+
+
+class XmlTextOverlapWrapLintTest(unittest.TestCase):
+    def lint_one(self, shape_xml: str) -> dict:
+        result = xml_text_overlap_lint.lint_xml(make_slide(shape_xml))
+        self.assertEqual(result["summary"]["error_count"], 0)
+        return result
+
+    def issue_codes(self, result: dict) -> list[str]:
+        return [
+            issue["code"]
+            for slide in result["slides"]
+            for issue in slide["issues"]
+        ]
+
+    def assertWarnsCode(self, shape_xml: str, code: str) -> None:
+        result = self.lint_one(shape_xml)
+        self.assertIn(code, self.issue_codes(result))
+        self.assertGreaterEqual(result["summary"]["warning_count"], 1)
+
+    def assertDoesNotWarnCode(self, shape_xml: str, code: str) -> None:
+        result = self.lint_one(shape_xml)
+        self.assertNotIn(code, self.issue_codes(result))
+
+    def test_wrap_lint_detects_orphan_line(self) -> None:
+        cases = [
+            ["把排版看成一套可维护的规则", "系统"],
+            ["为什么大多数企业知识库最终都会", "失效"],
+            ["让内容生产流程持续保持稳定的", "质量"],
+            ["复杂协作权限需要清晰可读的继承", "边界"],
+            ["自动化检查应该优先发现低级排版", "问题"],
+        ]
+        for lines in cases:
+            with self.subTest(lines=lines):
+                self.assertWarnsCode(text_shape(lines, width=520), "text_orphan_line")
+
+    def test_wrap_lint_allows_orphan_line_controls(self) -> None:
+        cases = [
+            ["把排版看成", "一套可维护的规则系统"],
+            ["为什么大多数企业知识库", "最终都会失效"],
+            ["复杂协作权限需要", "清晰可读的继承边界"],
+            ["自动化检查应该", "优先发现低级排版问题"],
+            ["标题换行质量", "直接影响读者理解效率"],
+        ]
+        for lines in cases:
+            with self.subTest(lines=lines):
+                self.assertDoesNotWarnCode(text_shape(lines, width=520), "text_orphan_line")
+
+    def test_wrap_lint_allows_multiline_body_with_short_final_line(self) -> None:
+        shape_xml = text_shape(
+            ["按行业、阶段、投资年份分层；剔除信息不可得或标签不完整样本。"],
+            align="left",
+            width=146,
+            height=42,
+            font_size=10,
+        )
+        self.assertDoesNotWarnCode(shape_xml, "text_orphan_line")
+
+    def test_wrap_lint_detects_unnecessary_wrap_in_title_like_text(self) -> None:
+        cases = [
+            ["减少手工", "格式"],
+            ["内容", "生产"],
+            ["智能", "生成"],
+            ["质量", "检查"],
+            ["边界", "规则"],
+        ]
+        for lines in cases:
+            with self.subTest(lines=lines):
+                self.assertWarnsCode(text_shape(lines, text_type="headline", width=420), "text_unnecessary_wrap")
+
+    def test_wrap_lint_allows_unnecessary_wrap_controls(self) -> None:
+        cases = [
+            ["减少手工格式"],
+            ["内容生产"],
+            ["智能生成"],
+            ["质量检查"],
+            ["边界规则"],
+        ]
+        for lines in cases:
+            with self.subTest(lines=lines):
+                self.assertDoesNotWarnCode(text_shape(lines, text_type="headline", width=420), "text_unnecessary_wrap")
+
+    def test_wrap_lint_detects_short_display_text_that_will_auto_wrap(self) -> None:
+        cases = [
+            "模型、平台、数据、研究",
+            "产业协同能力研究",
+            "接口边界安全研究",
+            "投后监测策略研究",
+            "评分稳定性复盘研究",
+        ]
+        for text in cases:
+            with self.subTest(text=text):
+                self.assertWarnsCode(
+                    text_shape([text], width=190, height=26, font_size=26),
+                    "text_unnecessary_wrap",
+                )
+
+    def test_wrap_lint_allows_body_text_that_will_auto_wrap(self) -> None:
+        shape_xml = text_shape(
+            ["按行业、阶段、投资年份分层；剔除信息不可得或标签不完整样本。"],
+            width=146,
+            height=42,
+            font_size=10,
+        )
+        self.assertDoesNotWarnCode(shape_xml, "text_unnecessary_wrap")
+
+    def test_wrap_lint_detects_center_wrapped_text(self) -> None:
+        cases = [
+            ["下一代智能", "办公系统"],
+            ["企业知识库", "治理方案"],
+            ["自动化排版", "质量基线"],
+            ["协作权限", "继承模型"],
+            ["内容生产", "智能流程"],
+        ]
+        for lines in cases:
+            with self.subTest(lines=lines):
+                self.assertWarnsCode(text_shape(lines, align="center", y=150), "text_center_wrapped")
+
+    def test_wrap_lint_detects_center_text_that_will_auto_wrap(self) -> None:
+        shape_xml = text_shape(
+            ["平台价值：让数据、模型和流程在同一界面被调用、解释和追踪。"],
+            align="center",
+            width=248,
+            height=12,
+            font_size=10,
+        )
+        self.assertWarnsCode(shape_xml, "text_center_wrapped")
+
+    def test_wrap_lint_allows_center_wrapped_controls(self) -> None:
+        cases = [
+            text_shape(["下一代智能办公系统"], align="center"),
+            text_shape(["企业知识库治理方案"], align="center"),
+            text_shape(["自动化排版质量基线"], align="left"),
+            text_shape(["封面主标题", "副标题"], text_type="title", align="center", y=210),
+            text_shape(["金句内容", "保持居中"], text_type="quote", align="center"),
+            text_shape(["企业筛选 / 排序 / 尽调建议"], align="center", width=132, height=20, font_size=10),
+            text_shape(["经营异动 / 风险预警 / 里程碑"], align="center", width=136, height=12, font_size=10),
+            text_shape(
+                ["建议采用 Top-N 命中率、风险预警召回率和评分稳定性三类指标，不只看单一准确率。"],
+                align="left",
+                width=146,
+                height=42,
+                font_size=10,
+            ),
+        ]
+        for shape_xml in cases:
+            with self.subTest(shape=shape_xml):
+                self.assertDoesNotWarnCode(shape_xml, "text_center_wrapped")
+
+    def test_wrap_lint_detects_text_box_too_short(self) -> None:
+        cases = [
+            "REST API / 批量文件 / 定时同步",
+            "鉴权、审计、脱敏与最小权限",
+            "优先适配现有系统，减少重复建设",
+            "服务化部署、权限隔离、日志留痕",
+            "试运行三个月，终验后三年维保",
+        ]
+        for text in cases:
+            with self.subTest(text=text):
+                self.assertWarnsCode(
+                    text_shape([text], width=280, height=2, font_size=18),
+                    "text_box_too_short",
+                )
+
+    def test_wrap_lint_allows_text_box_with_sufficient_height(self) -> None:
+        cases = [
+            "REST API / 批量文件 / 定时同步",
+            "鉴权、审计、脱敏与最小权限",
+            "优先适配现有系统，减少重复建设",
+            "11",
+            "KR1",
+        ]
+        for text in cases:
+            with self.subTest(text=text):
+                self.assertDoesNotWarnCode(
+                    text_shape([text], width=450, height=48, font_size=18),
+                    "text_box_too_short",
+                )
+
+    def test_wrap_lint_keeps_bbox_overlap_detection(self) -> None:
+        result = xml_text_overlap_lint.lint_xml(
+            make_slide(
+                text_shape(["Title"], text_type="title", x=80, y=80, width=300, height=60)
+                + text_shape(["Body"], text_type="body", x=80, y=80, width=300, height=80)
+            )
+        )
+        self.assertEqual(result["summary"]["error_count"], 1)
+        self.assertIn("bbox_overlap", self.issue_codes(result))
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/cli_e2e/drive/coverage.md

@@ -2,8 +2,8 @@
 
 ## Metrics
 - Denominator: 31 leaf commands
-- Covered: 10
-- Coverage: 32.3%
+- Covered: 11
+- Coverage: 35.5%
 
 ## Summary
 - TestDrive_FilesCreateFolderWorkflow: proves `drive files create_folder` in `create_folder as bot`; helper asserts the returned folder token and registers best-effort cleanup via `drive files delete`.
@@ -15,6 +15,7 @@
 - TestDriveAddCommentMarkdownFileWorkflow: opt-in live workflow skeleton for the same path, gated by `LARK_DRIVE_MD_COMMENT_E2E=1`.
 - TestDrive_SecureLabelDryRun: dry-run coverage for `drive +secure-label-list` and `drive +secure-label-update`; asserts label-list query params and update URL→type inference, request method/URL/type query, and `label-id` body shape. Runs without hitting live APIs because update can trigger document-level security approval flows.
 - TestDriveExportDryRun_FileNameMetadata / TestDriveExportDryRun_BitableBaseOnlySchema: dry-run coverage for `drive +export`; asserts export task request shape, local `--file-name` / `--output-dir` metadata, and `bitable` `.base` `only_schema` request body without calling live APIs.
+- TestDriveImportDryRun_PDFToSlides: dry-run coverage for `drive +import`; asserts PDF-to-slides request shape across media upload `extra` and import task body without calling live APIs.
 - TestDrive_PullDryRun / TestDrive_PullDryRunAcceptsDuplicateRemoteStrategies: dry-run coverage for `drive +pull`; asserts the list-files request shape, Validate-stage safety guards, and acceptance of `--on-duplicate-remote=rename|newest|oldest` by the real CLI binary.
 - TestDrive_PushDryRun / TestDrive_PushDryRunAcceptsDuplicateRemoteStrategies: dry-run coverage for `drive +push`; asserts the list-files request shape, Validate-stage safety guards, conditional delete preflight, and acceptance of `--on-duplicate-remote=newest|oldest` by the real CLI binary.
 - Cleanup note: `drive files delete` is only exercised in cleanup and is intentionally left uncovered.
@@ -31,7 +32,7 @@
 | ✕ | drive +download | shortcut |  | none | no file fixture workflow yet |
 | ✓ | drive +export | shortcut | drive_export_dryrun_test.go::TestDriveExportDryRun_FileNameMetadata + TestDriveExportDryRun_BitableBaseOnlySchema | `--token`; `--doc-type`; `--file-extension`; `--file-name`; `--output-dir`; `--only-schema` | dry-run only; no live export workflow yet |
 | ✕ | drive +export-download | shortcut |  | none | no export-download workflow yet |
-| ✕ | drive +import | shortcut |  | none | no import workflow yet |
+| ✓ | drive +import | shortcut | drive_import_dryrun_test.go::TestDriveImportDryRun_PDFToSlides | `.pdf` source with `--type slides`; media upload `extra.file_extension=pdf`; import task `file_extension=pdf`, `type=slides`, `file_name` | dry-run only; no live import workflow yet |
 | ✕ | drive +move | shortcut |  | none | no move workflow yet |
 | ✓ | drive +pull | shortcut | drive_pull_dryrun_test.go::TestDrive_PullDryRun + drive_duplicate_sync_workflow_test.go::TestDrive_DuplicateRemoteWorkflow | `--local-dir`; `--folder-token`; `--on-duplicate-remote=rename\|newest\|oldest`; `--delete-local --yes` guard | dry-run locks flag/validate shape; live workflow proves duplicate fail-fast and rename recovery |
 | ✓ | drive +push | shortcut | drive_push_dryrun_test.go::TestDrive_PushDryRun + drive_duplicate_sync_workflow_test.go::TestDrive_DuplicateRemoteWorkflow | `--local-dir`; `--folder-token`; `--if-exists`; `--on-duplicate-remote=newest\|oldest`; `--delete-remote --yes` | dry-run locks flag/validate shape; live workflow proves overwrite + duplicate cleanup converges status |