docs: tighten lark slides template preservation

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,6 +11,8 @@ func Shortcuts() []common.Shortcut {
 		SlidesCreate,
 		SlidesMediaUpload,
 		SlidesReplaceSlide,
+		SlidesReplacePages,
 		SlidesScreenshot,
+		SlidesXMLGet,
 	}
 }

shortcuts/slides/slides_create.go

@@ -204,13 +204,11 @@ var SlidesCreate = common.Shortcut{
 			}
 		}
 
-		// Build the presentation URL locally from the token. The brand-standard
-		// host transparently redirects to the tenant domain (same fallback used by
-		// drive +upload / wiki +node-create). This avoids the prior best-effort
-		// drive metas/batch_query call, which needed an extra drive scope and 403'd
-		// for users who only authorized slides scopes — without ever blocking an
-		// otherwise-successful creation.
-		if url := common.BuildResourceURL(runtime.Config.Brand, "slides", presentationID); url != "" {
+		// Prefer the URL returned by presentation.create. Fall back to a local
+		// brand-standard URL only when the API omits it.
+		if url := common.GetString(data, "url"); url != "" {
+			result["url"] = url
+		} else if url := common.BuildResourceURL(runtime.Config.Brand, "slides", presentationID); url != "" {
 			result["url"] = url
 		}
 

shortcuts/slides/slides_create_test.go

@@ -34,6 +34,7 @@ func TestSlidesCreateBasic(t *testing.T) {
 			"data": map[string]interface{}{
 				"xml_presentation_id": "pres_abc123",
 				"revision_id":         1,
+				"url":                 "https://tenant.example.com/slides/pres_abc123",
 			},
 		},
 	})
@@ -54,10 +55,8 @@ func TestSlidesCreateBasic(t *testing.T) {
 	if data["title"] != "项目汇报" {
 		t.Fatalf("title = %v, want 项目汇报", data["title"])
 	}
-	// URL is built locally from the token (brand-standard host), not fetched from
-	// drive metas, so it is deterministic and needs no drive scope.
-	if data["url"] != "https://www.feishu.cn/slides/pres_abc123" {
-		t.Fatalf("url = %v, want https://www.feishu.cn/slides/pres_abc123", data["url"])
+	if data["url"] != "https://tenant.example.com/slides/pres_abc123" {
+		t.Fatalf("url = %v, want https://tenant.example.com/slides/pres_abc123", data["url"])
 	}
 	if _, ok := data["permission_grant"]; ok {
 		t.Fatalf("did not expect permission_grant in user mode")
@@ -647,12 +646,12 @@ func TestSlidesCreateWithoutSlidesUnchanged(t *testing.T) {
 	}
 }
 
-// TestSlidesCreateURLBuiltLocally verifies the presentation URL is constructed
-// locally from the token — no drive metas/batch_query call is made, so creation
-// works for users who only authorized slides scopes. The httpmock registry has no
-// batch_query stub registered; if the shortcut tried to call it, the request would
-// fail the test (unregistered stub), proving the URL is built without a drive call.
-func TestSlidesCreateURLBuiltLocally(t *testing.T) {
+// TestSlidesCreateURLFallsBackToLocalBuild verifies the presentation URL is
+// constructed locally from the token when presentation.create omits url — no
+// drive metas/batch_query call is made, so creation works for users who only
+// authorized slides scopes. The httpmock registry has no batch_query stub
+// registered; if the shortcut tried to call it, the request would fail the test.
+func TestSlidesCreateURLFallsBackToLocalBuild(t *testing.T) {
 	t.Parallel()
 
 	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
@@ -665,6 +664,7 @@ func TestSlidesCreateURLBuiltLocally(t *testing.T) {
 			"data": map[string]interface{}{
 				"xml_presentation_id": "pres_local_url",
 				"revision_id":         1,
+				"url":                 "",
 			},
 		},
 	})

shortcuts/slides/slides_replace_pages.go

@@ -0,0 +1,426 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package slides
+
+import (
+	"context"
+	"encoding/json"
+	"encoding/xml"
+	"errors"
+	"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 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: "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 {
+		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
+			}
+		}
+		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 errors.Is(err, io.EOF) {
+			break
+		}
+		if err != nil {
+			return err
+		}
+		switch t := tok.(type) {
+		case xml.StartElement:
+			if depth == 0 {
+				if seenRoot {
+					return invalidSlideXMLStructureError("multiple root elements")
+				}
+				if t.Name.Local != "slide" {
+					return invalidSlideXMLStructureError("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 invalidSlideXMLStructureError("non-whitespace text outside root element")
+			}
+		}
+	}
+	if !seenRoot {
+		return invalidSlideXMLStructureError("missing root element")
+	}
+	if depth != 0 {
+		return invalidSlideXMLStructureError("unclosed XML element")
+	}
+	return nil
+}
+
+func invalidSlideXMLStructureError(format string, args ...interface{}) error {
+	return errs.NewValidationError(errs.SubtypeInvalidArgument, format, args...)
+}
+
+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,341 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package slides
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+	"reflect"
+	"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 TestReplacePagesDeclaredScopes(t *testing.T) {
+	if got := SlidesReplacePages.ScopesForIdentity("user"); !reflect.DeepEqual(got, []string{"slides:presentation:update", "slides:presentation:write_only"}) {
+		t.Fatalf("user preflight scopes = %#v, want slides update/write_only only", got)
+	}
+	if got := SlidesReplacePages.ScopesForIdentity("bot"); !reflect.DeepEqual(got, []string{"slides:presentation:update", "slides:presentation:write_only"}) {
+		t.Fatalf("bot preflight scopes = %#v, want slides update/write_only only", got)
+	}
+
+	got := SlidesReplacePages.DeclaredScopesForIdentity("user")
+	want := []string{"slides:presentation:update", "slides:presentation:write_only", "wiki:node:read"}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("declared scopes = %#v, want %#v", got, want)
+	}
+}
+
+func TestReplacePagesCreatesBeforeThenDeletesOld(t *testing.T) {
+	t.Parallel()
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	var requestOrder []string
+	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},
+		},
+		OnMatch: func(req *http.Request) {
+			requestOrder = append(requestOrder, req.Method)
+		},
+	}
+	reg.Register(createStub)
+	var deleteQuery map[string][]string
+	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},
+		},
+		OnMatch: func(req *http.Request) {
+			requestOrder = append(requestOrder, req.Method)
+			deleteQuery = req.URL.Query()
+		},
+	}
+	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)
+	}
+	if !reflect.DeepEqual(requestOrder, []string{"POST", "DELETE"}) {
+		t.Fatalf("request order = %#v, want POST then DELETE", requestOrder)
+	}
+	deleteURL := string(deleteStub.CapturedBody)
+	if deleteURL != "" {
+		t.Fatalf("delete body = %q, want empty", deleteURL)
+	}
+	if got := deleteQuery["slide_id"]; !reflect.DeepEqual(got, []string{"old2"}) {
+		t.Fatalf("delete slide_id = %#v, want old2", got)
+	}
+	if got := deleteQuery["revision_id"]; !reflect.DeepEqual(got, []string{"11"}) {
+		t.Fatalf("delete revision_id = %#v, want 11 from create response", got)
+	}
+
+	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_replace_slide.go

@@ -43,8 +43,10 @@ var SlidesReplaceSlide = common.Shortcut{
 	Command:     "+replace-slide",
 	Description: "Replace elements on a slide via block_replace / block_insert parts (auto-injects id + <content/> on shape elements)",
 	Risk:        "write",
-	Scopes:      []string{"slides:presentation:update", "slides:presentation:write_only", "wiki:node:read"},
-	AuthTypes:   []string{"user", "bot"},
+	Scopes:      []string{"slides:presentation:update", "slides:presentation:write_only"},
+	// 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: "slide-id", Desc: "slide page identifier (slide_id)", Required: true},
@@ -53,9 +55,15 @@ var SlidesReplaceSlide = common.Shortcut{
 		{Name: "tid", Desc: "transaction id for concurrent-edit locking (usually empty)"},
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		if _, err := parsePresentationRef(runtime.Str("presentation")); err != nil {
+		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("slide-id")) == "" {
 			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--slide-id cannot be empty").WithParam("--slide-id")
 		}

shortcuts/slides/slides_replace_slide_test.go

@@ -7,6 +7,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"reflect"
 	"strings"
 	"testing"
 
@@ -15,6 +16,21 @@ import (
 	"github.com/larksuite/cli/internal/httpmock"
 )
 
+func TestReplaceSlideDeclaredScopes(t *testing.T) {
+	if got := SlidesReplaceSlide.ScopesForIdentity("user"); !reflect.DeepEqual(got, []string{"slides:presentation:update", "slides:presentation:write_only"}) {
+		t.Fatalf("user preflight scopes = %#v, want slides update/write_only only", got)
+	}
+	if got := SlidesReplaceSlide.ScopesForIdentity("bot"); !reflect.DeepEqual(got, []string{"slides:presentation:update", "slides:presentation:write_only"}) {
+		t.Fatalf("bot preflight scopes = %#v, want slides update/write_only only", got)
+	}
+
+	got := SlidesReplaceSlide.DeclaredScopesForIdentity("user")
+	want := []string{"slides:presentation:update", "slides:presentation:write_only", "wiki:node:read"}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("declared scopes = %#v, want %#v", got, want)
+	}
+}
+
 // TestReplaceSlideBlockReplaceInjectsID is the core regression: users write
 // <shape>…</shape> as replacement and the CLI must stitch id="<block_id>"
 // onto the root before sending. The backend returns 3350001 otherwise.

shortcuts/slides/slides_screenshot.go

@@ -34,7 +34,9 @@ var SlidesScreenshot = common.Shortcut{
 	Command:     "+screenshot",
 	Description: "Save slide screenshots to local files without printing Base64 image data",
 	Risk:        "read",
-	Scopes:      []string{"slides:presentation:screenshot"},
+	Scopes:      []string{},
+	// The screenshot API is allowlist-gated for only a few apps, so do not
+	// advertise/preflight its scope. Let the API fail and let callers degrade.
 	// wiki:node:read is required only when --presentation is a wiki URL.
 	ConditionalScopes: []string{"wiki:node:read"},
 	AuthTypes:         []string{"user", "bot"},

shortcuts/slides/slides_screenshot_test.go

@@ -17,11 +17,23 @@ import (
 )
 
 func TestSlidesScreenshotDeclaredScopes(t *testing.T) {
+	if got := SlidesScreenshot.ScopesForIdentity("user"); len(got) != 0 {
+		t.Fatalf("user preflight scopes = %#v, want empty", got)
+	}
+	if got := SlidesScreenshot.ScopesForIdentity("bot"); len(got) != 0 {
+		t.Fatalf("bot preflight scopes = %#v, want empty", got)
+	}
+
 	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] {
+	want := []string{"wiki:node:read"}
+	if len(got) != len(want) || got[0] != want[0] {
 		t.Fatalf("declared scopes = %#v, want %#v", got, want)
 	}
+	for _, scope := range got {
+		if scope == "slides:presentation:screenshot" {
+			t.Fatalf("declared scopes must not advertise screenshot scope: %#v", got)
+		}
+	}
 }
 
 func TestSlidesScreenshotWritesFilesAndSuppressesBase64(t *testing.T) {

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,165 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package slides
+
+import (
+	"errors"
+	"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.Category != errs.CategoryValidation {
+		t.Fatalf("category = %q, want %q", problem.Category, errs.CategoryValidation)
+	}
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("expected *errs.ValidationError, got %T %v", err, err)
+	}
+	if validationErr.Param != "--output" {
+		t.Fatalf("param = %q, want --output", validationErr.Param)
+	}
+}

skills/lark-drive/SKILL.md

@@ -25,7 +25,7 @@ metadata:
 - 用户给出 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。
 - 用户要在 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）
 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 "导入数据表"
@@ -94,6 +95,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 +105,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 +139,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-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: "飞书幻灯片：创建和编辑幻灯片。创建演示文稿、读取幻灯片内容、管理幻灯片页面（创建、删除、读取、局部替换）。当用户需要创建或编辑幻灯片、读取或修改单个页面时使用；当用户给定 PPTX/PDF 作为模板、底稿或视觉参考时，也用本 skill 统筹导入后的二次创作（导入命令本身走 `lark-drive` 的 `drive +import --type slides`）。当用户给出 doubao.com 的 /slides/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。不负责：云文档内容编辑（走 lark-doc）、云文档里的独立画板对象（走 lark-whiteboard，注意 slide 内嵌的流程图/架构图仍属本 skill）、上传或下载普通文件（走 lark-drive）。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -14,16 +14,17 @@ 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` |
-| 编辑单个标题、文本块、图片或局部元素 | 优先块级替换/插入，不改页序 | `slides +replace-slide`、`lark-slides-replace-slide.md` |
+| 用户提供 PDF/PPTX/slides 材料并要求生成或改写 PPT | 必须先导入/回读材料，并以导入后的 presentation 作为目标底稿二次创作；除非 PDF 明显是长文档/资料而非演示稿，不要跳过导入 | `drive +import --type slides`、`planning-layer.md`、`asset-planning.md`、`lark-slides-edit-workflows.md` |
+| 新建 PPT | 仅在没有用户提供可导入材料、用户明确要求另建，或导入失败/回读失败时，先规划 `slide_plan.json`，再按复杂度创建 | `planning-layer.md`、`visual-planning.md`、`asset-planning.md`、`slides +create` |
+| 已有 PPT 大幅改写 | 优先用 `+replace-pages` 做页面级重建，哪怕只替换 1 页也传 1 个 page item；在完整新页 XML 里复用旧页背景、图片、图表、表格等素材 | `xml_presentations.get`、`lark-slides-replace-pages.md`、`lark-slides-edit-workflows.md` |
+| 编辑单个标题、文本块、图片或局部元素 | 只有明确是小型块级编辑且拿到了最新 block_id 时才用 `+replace-slide` | `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 为准。**
@@ -40,14 +41,16 @@ metadata:
 
 **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。**
+**CRITICAL — 用户提供 PPTX/PDF/slides 作为模板、底稿或视觉参考时，MUST 先导入或回读为 Slides，保存原 XML，并做素材清单：每页的 `<style>` 背景、`<img src="file_token">`、`<chart>`、`<table>`、`<whiteboard>`、关键 shape/motif。二次创作默认在同一个 `xml_presentation_id` 内用 `+replace-pages` 页面级替换；同一 presentation 内旧页的图片 file token 可在新页 XML 中复用。不要用 `slides +create` 新建脱离模板的 deck，除非导入或回读失败。**
+
+**CRITICAL — 如果用户提到“模板”“套用模板”“参考某种主题/风格/版式”，或用户需求明显落在已有场景模板内（如工作汇报、产品介绍、商业计划书、培训、晋升汇报等），只有在用户没有提供本地/在线模板材料时，才用 [`scripts/template_tool.py`](scripts/template_tool.py) 的 `search` 做内置模板检索；默认给出 2-3 个最匹配模板候选供用户选择。锁定模板后用 `summarize` 获取主题和布局摘要；只有需要布局骨架时才用 `extract` 裁切目标页型 XML。不要直接读取完整模板 XML。**
 
 > [!NOTE]
 > `scripts/template_tool.py` 需要 Python 3。`references/template-index.json` 是脚本缓存/轻量路由索引，不是默认给 agent 阅读的文档；`assets/templates/*.xml` 是机器资源，只应通过脚本摘要或裁切，不要全文读取。
 
 **CRITICAL — 使用模板生成或改写页面时，MUST 先 `summarize` 目标页型；只有需要具体布局骨架时才 `extract`。**
 
-**编辑已有幻灯片页面**：优先用 [`+replace-slide`](references/lark-slides-replace-slide.md)（块级替换/插入，不动页序）；选择 action 和完整读-改-写流程见 [`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)。
+**编辑已有幻灯片页面**：页面级重写、导入模板二创、布局/素材保留优先用 [`+replace-pages`](references/lark-slides-replace-pages.md) 在原 presentation 内重建页面，避免 `slides +create` 生成新链接；[`+replace-slide`](references/lark-slides-replace-slide.md) 只用于单个标题、文本块、图片或局部元素的小型块级编辑。选择 action 和完整读-改-写流程见 [`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)。
 
 ## 身份选择
 
@@ -82,7 +85,7 @@ 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)
@@ -133,7 +136,9 @@ lark-cli auth login --domain slides
 - 不要把素材缺失表现为空白图片框；必须按 `fallback_if_missing` 生成 XML-native 视觉。
 - 不要留下模板占位文案、示例公司名、示例日期或与用户主题无关的原模板内容。
 
-### 创建方式选择
+### 无用户导入材料时的创建方式
+
+以下创建方式仅适用于没有用户提供可导入材料、用户明确要求另建 deck，或导入失败/`xml_presentations.get` 无法回读的异常场景。
 
 | 场景 | 推荐方式 |
 |------|----------|
@@ -149,7 +154,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
@@ -159,28 +164,30 @@ 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
+  - 如果用户提供 PPTX/PDF/slides 附件、文件路径、素材目录或类似“附件文件路径：...”的文本，先按 asset-planning.md 解析路径；PPTX 必须导入为 slides，PDF 只在明显不是演示稿/模板时才跳过导入
 
 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 执行
+  - plan 字段、路径命名、模板边界、导入底稿保留策略和 `asset_need` 结构按 planning-layer.md / asset-planning.md 执行
 
 Step 3: 按 slide_plan.json 生成 XML → 创建
   - 逐页消费 plan：key_message 定主结论，layout_type 定几何，visual_focus 定主视觉，text_density 定文本量
+  - 如果 plan 有 `target_xml_presentation_id`，默认在该 presentation 内用 `+replace-pages` 替换页面；生成完整新页 XML 时复用源页 `<style>`、图片 file token、图表、表格、关键装饰 shape 等素材
   - 缺少真实素材时必须用 `fallback_if_missing` 生成 XML-native 兜底视觉；不要留空
-  - 创建方式按“创建方式选择”判断；图片、复杂 XML、转义和 3350001 排查按 lark-slides-create.md、media-upload.md、troubleshooting.md 执行
+  - 只有无导入材料、用户明确要求另建，或导入失败/回读失败时，才按“无用户导入材料时的创建方式”新建 deck
 
 Step 4: 审查 & 交付
   - 创建完成后，必须用 xml_presentations.get 读取全文 XML，并按 validation-checklist.md 做显式验证记录，包括 XML 文本重叠检查
-  - 失败或部分成功按 troubleshooting.md 处理；局部问题优先用 `+replace-slide` 修正
+  - 失败或部分成功按 troubleshooting.md 处理；小型块级问题可用 `+replace-slide` 修正，页面级/素材保留问题继续用 `+replace-pages`
   - 没问题 → 交付：告知用户演示文稿 ID 和访问方式
 ```
 
 ### jq 命令模板（编辑已有 PPT 时使用）
 
-新建 PPT 推荐用 `+create --slides`。以下 jq 模板适用于向已有演示文稿追加页面的场景，可以避免手动转义双引号：
+无用户导入材料的新建 PPT 可用 `+create --slides`。以下 jq 模板适用于向已有演示文稿追加页面的场景，可以避免手动转义双引号：
 
 ```bash
 # 追加到末尾
@@ -268,6 +275,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) | 在原演示文稿内重建一个或多个页面：先创建新页到旧页前，再删除旧页；适合导入模板二创、页面级重写和素材保留，不新建链接 |
 
 没有 Shortcut 覆盖时使用原生 API。高频资源：`xml_presentations.get` 读取全文；`xml_presentation.slide.create/delete/get/replace` 管理单页。
 
@@ -280,13 +288,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. **编辑已有页面优先原链接更新**：页面级重写、导入模板二创、布局/素材保留优先用 `+replace-pages`；修改单个 shape/img 才用 `+replace-slide`（`block_replace` / `block_insert`）。不要用 `slides +create` 新建整份 PPT；不要手动编排 `slide.create` + `slide.delete` 来替代已有 shortcut
+9. **`<img src>` 只能用上传到飞书 drive 的 `file_token`，禁止使用 http(s) 外链 URL**：飞书 slides 渲染端不会代理外链图片，外链 src 在 PPT 里通常不显示或显示破图。流程必须是「先把图存到本地 → 用 `slides +media-upload` 上传或 `+create --slides` 的 `@./path` 占位符自动上传 → 拿 `file_token` 写进 `<img src>`」。如果 `file_token` 来自同一个 `xml_presentation_id` 的旧页，可以在 `+replace-pages` 的新页 XML 中直接复用；如果用户给了网图链接，先 `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

@@ -10,9 +10,25 @@
 - 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.
+- 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 for genuinely missing new assets.
+- If the user provides PPTX/PDF/slides material and it has been imported/read back, its existing slide assets are not "missing assets." Record them in `source_asset_inventory` / `rewrite_contract` in `planning-layer.md` and reuse the original XML or file token in the replacement page.
+- `fallback_if_missing` must not replace an existing source `<img>`, `<table>`, `<chart>`, `<whiteboard>`, or locked motif. It only applies when the page needs a new asset that is absent from the source deck.
 - Do not leave blank image boxes in final XML. If the asset is missing, render the fallback visual.
 
+## Imported Slide Assets
+
+For imported or existing Slides rewrites, first inventory the source XML before writing new page XML. This inventory is a lock list, not a suggestion list:
+
+- Preserve `<style>` when it carries the template background, gradient, image fill, or visual tone.
+- Preserve `<img src="...">` when the image is part of the template, brand, product screenshot, chart export, decorative background, or layout.
+- Preserve `<chart>` / `<table>` when the user asked to keep data visuals or when they anchor the page design; update labels/data only if requested.
+- Preserve `<whiteboard>` position when it represents a diagram to keep, but remember readback XML may not include its inner SVG/Mermaid content.
+- Preserve recurring shape motifs such as side bars, section bands, numbered badges, separators, or card containers.
+
+When using `+replace-pages`, a reused `<img src>` from the same `xml_presentation_id` can be copied directly into the new `<slide>` content. Do not re-upload it and do not replace it with an external URL.
+
+Use `asset_need` for new desired assets. Use `source_asset_inventory` and `rewrite_contract.must_reuse` for old assets that must survive the rewrite. If an old asset should be removed, list that exact block in `rewrite_contract.discarded_blocks` with `type`, `id`, and reason; do not remove whole pages of assets with a broad "old graphics do not match" explanation.
+
 ## JSON Shape
 
 Use an object for one planned asset, or an array when a page genuinely needs multiple assets. Keep each item compact.
@@ -117,8 +133,9 @@ Business comparison page:
 
 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. If an asset exists in the imported/current presentation and the page rewrite stays in that same `xml_presentation_id`, reuse the original XML block or file token in the planned visual region.
+2. Generate from source outward: copy source `<style>` and locked assets first, then replace placeholder text, then add new XML-native visuals.
+3. If no source or new real asset exists, immediately render `fallback_if_missing` with XML-native shapes, text, lines, arrows, tables, whiteboard diagrams, or chart-like elements.
+4. Size the fallback to satisfy `visual_focus`; it should be a real page element, not a tiny decoration.
+5. Keep text-density limits. Do not compensate for missing assets by adding long bullet text.
+6. After creation or replacement, fetch the presentation and verify asset pages are not blank, locked source assets are still present, and each planned fallback is visible only when no source or real asset was available.

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

@@ -1,20 +1,51 @@
 # 编辑已有 PPT：读-改-写闭环
 
-编辑走 **shortcut [`+replace-slide`](lark-slides-replace-slide.md)**（块级替换 / 插入），配合 `xml_presentation.slide.get` 读原页拿 `block_id`。
+页面级重写、导入模板二创、布局/素材保留优先走 **[`+replace-pages`](lark-slides-replace-pages.md)**，保持原 presentation 链接不变。只有很小的局部编辑才走 **[`+replace-slide`](lark-slides-replace-slide.md)**（块级替换 / 插入），并且必须先读原页拿最新 `block_id`。
 
 > 生成 XML 前**必读** [xml-schema-quick-ref.md](xml-schema-quick-ref.md)。
 
-## 决策树：block_replace vs block_insert
+## 决策树：replace-pages vs replace-slide
 
 | 需求 | 推荐 action | 理由 |
 |------|------------|------|
+| 导入 PPTX/PDF 后二次创作、保留模板、背景、图片、图表或页面视觉语言 | `+replace-pages` | 生成完整 `<slide>`，可直接复用旧页 `<style>`、`<img src>` file token、`<chart>`、`<table>`、关键 motif，避开 block 级 patch 易失败点 |
+| 单页也要重排版式或替换大部分页面内容 | `+replace-pages`（pages 数组传 1 项） | 仓库代码命令名是复数；支持 1 个 item，按 create-before-delete-old 执行 |
+| 多页版式重建、整页坐标重排 | `+replace-pages` | 原 presentation 内批量 create-before/delete-old，不生成新 Slides 链接 |
 | 已知某块的 `block_id`，要换这块内容（改标题、换图、挪坐标） | `block_replace` | 精准替换，原子性好；`replacement` 根 `id` 由 CLI 自动注入为 `block_id` |
 | 只加 1~N 个元素、不动现有布局 | `block_insert` | 新增不覆盖，可选 `insert_before_block_id` 指定位置 |
 | 一次动多个元素（如：换标题 + 加图） | 单次 `--parts` 里拼多条 | 整批作为原子事务，任一失败整批不生效；`block_replace` 和 `block_insert` 可混用 |
 
 > **没有字段级 patch**：即便只想改一个 `shape` 的 `topLeftX`，也得把整个块的新 XML 写出来用 `block_replace`。这不是"微调"，是块级重写。
 
-## 最小读-改-写闭环
+## 导入 PPTX/PDF 后的保模板流程
+
+1. 用 `drive +import --type slides` 导入 PPTX/PDF；PPTX 必须导入，PDF 只有明显不是演示稿/模板时才跳过。
+2. 用 `xml_presentations.get` 回读导入后的 XML，保存到 `.lark-slides/plan/<id>/source.xml`。
+3. 为每页列 `source_asset_inventory`：`<style>`、`<img src>`、`<chart>`、`<table>`、`<whiteboard>`、关键 shape/motif 和 bbox。源素材默认是 locked assets。
+4. 在 `slide_plan.json` 里设置 `target_xml_presentation_id`，每页记录 `source_slide_id`、`rewrite_mode: "preserve_template"` 和 `rewrite_contract`。
+5. 生成完整新 `<slide>`：先复制源页 `<style>` 和 locked assets，再替换文案、调整布局、删除逐块列明的模板占位文字，最后补充新业务图形。
+6. 组装 `pages.json`，每项包含旧页 `slide_id` 和完整新页 `content`。
+7. 先跑 `+replace-pages --validate-only` 或 dry-run，再执行 `+replace-pages`。
+8. 回读全文 XML，核对 locked assets、图片 token、图表、表格、背景和页数；如果账号具备截图能力，可额外截图检查视觉效果。
+
+不要从空 `<slide>` 重画后再按感觉补素材。模板二创不是"复用 slide_id 的新 deck"，而是在源页 XML 之上做保留式改写。
+
+`rewrite_contract.discarded_blocks` 必须逐块列出 `type`、`id` 和原因。`discarded_blocks.type = "all"` 默认禁止；只有用户明确要求不保留模板素材或只参考风格重做时，才允许 `rewrite_mode: "style_reference_only"`，并在 plan 中记录用户原话或等价证据。
+
+`+replace-slide` 不作为导入模板二创主路径。它依赖当前页 `block_id`、单根 XML 片段和后端 block replace 约束，出现 3350001 时需要重新读页和修片段；页面级二创通常用 `+replace-pages` 更稳。
+
+最小 `pages.json` 形态：
+
+```json
+[
+  {
+    "slide_id": "old_slide_id",
+    "content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><style>...</style><data>...</data></slide>"
+  }
+]
+```
+
+## 小型块级编辑闭环
 
 ```bash
 PID="xml_presentation_id_here"
@@ -136,6 +167,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,118 @@
+# slides +replace-pages（页面级重建）
+
+批量替换已有演示文稿里的一个或多个页面，保持原 `xml_presentation_id` 和原 Slides 链接不变。适合导入 PPTX/PDF 后二次创作、保留模板素材、版式大改、坐标重排、整页视觉重建；单个文本框、图片或 shape 的小型局部编辑才考虑 [`+replace-slide`](lark-slides-replace-slide.md)。
+
+> 重要：这是多步编排，不是后端原子事务。CLI 对每页执行“先创建新页到旧页前，再删除旧页”；创建失败时旧页会保留。删除失败时可能出现新旧页同时存在，需要按返回结果继续处理。
+
+> 命令名以仓库代码为准：当前 shortcut 是 `slides +replace-pages`（复数）。即使只替换一页，也传一个包含 1 个 item 的 `pages` 数组。
+
+## 命令
+
+```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 阶段会返回对应错误。
+
+## 保留导入模板素材
+
+导入 PPTX/PDF 或改写已有 Slides 时，先用 `xml_presentations.get` 保存当前 XML，再为每页盘点素材。源素材默认锁定保留，不是可随意替换的装饰：
+
+- `<style>`：页面背景、渐变、底色或图片底纹。
+- `<img src="...">`：同一个 `xml_presentation_id` 内的 file token 可直接复制到新页 XML。
+- `<chart>` / `<table>`：优先保留原结构；只在用户要求时改数据或标签。
+- `<whiteboard>`：可保留外层位置；注意回读 XML 可能不包含内部 SVG/Mermaid。
+- 关键 shape/motif：侧边栏、分节条、卡片底、编号徽章、分割线等模板视觉语言。
+
+在 `slide_plan.json` 中把这些事实写入 `source_asset_inventory`，并在每页 `rewrite_contract.must_reuse` 中绑定要保留的 locked assets。生成 replacement `content` 时，顺序必须是：
+
+1. 先复制源页 `<style>` 和 locked assets。
+2. 再替换模板占位文案和必要布局。
+3. 最后补充新业务图形。
+
+不要从空 `<slide>` 重画后再按感觉补素材。不要把导入底稿当成普通参考后重新 `slides +create` 一份脱离素材的新 deck。
+
+`discarded_blocks` 只能逐块删除源元素，必须写 `type`、`id` 和原因。`discarded_blocks.type = "all"` 默认非法；只有用户明确要求"不保留模板素材"或"只参考风格重做"时，才允许 `rewrite_mode: "style_reference_only"`。
+
+## 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. 导入模板二创时，先在 plan 中记录每页要复用的背景、图片 token、图表、表格和 motif，再生成完整新页 XML。
+3. 生成只含 `slide_id` 和完整 `<slide>` content 的 `pages.json` 后先跑 `--dry-run` 或 `--validate-only`。
+4. 默认不要开 `--continue-on-error`，除非能接受部分页面已替换。
+5. 替换后再回读全文 XML，确认页序、背景、图片、图表、表格、locked motif 和文本没有破损；如果当前账号具备截图能力，可额外截图检查视觉效果。

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

@@ -2,7 +2,9 @@
 
 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
-对指定 slide 做块级替换或插入。编辑已有 PPT 的主路径——`slide_id` 不变、页序不动、只影响被指定的块。
+对指定 slide 做块级替换或插入。适合小型局部编辑：`slide_id` 不变、页序不动、只影响被指定的块。
+
+导入 PPTX/PDF 后二次创作、模板素材保留、整页布局重建不要默认用本 shortcut；优先用 [`+replace-pages`](lark-slides-replace-pages.md) 生成完整新页 XML，并在同一个 presentation 内复用旧页背景、图片 file token、图表、表格和 motif。
 
 相比直接调 `xml_presentation.slide.replace`，这个 shortcut 的四个额外价值：
 

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

@@ -4,7 +4,7 @@
 
 获取幻灯片页面截图并保存为本地图片文件。默认用于已存在 PPT 页面截图；传入 `--content` 时用于直接渲染单个 `<slide>` XML 片段预览。本 shortcut 会在 CLI 进程内解码并写入文件，stdout 只返回文件路径、大小、页面 ID 等元信息，避免把图片 Base64 输出给模型。
 
-注意：该截图能力对应的权限受白名单控制。只有在白名单内的应用才能申请该权限；不在白名单内的应用即使命令和参数正确，服务端仍可能返回权限或能力不可用相关错误。
+注意：该截图能力受应用白名单限制，绝大多数应用不可用。截图失败时不要引导用户申请 `slides:presentation:screenshot` 权限；记录错误后降级到 XML 读回、结构 lint、文本重叠检查等非截图检查路径。
 
 ## 命令
 

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

@@ -7,16 +7,34 @@
 ## Required Flow
 
 1. 理解用户需求，必要时澄清主题、受众、页数、风格。
-2. 如果适合模板，先用 `template_tool.py search` 检索，锁定模板后用 `summarize` 获取主题和页型信息。
-3. 选择唯一 plan 目录：`.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 的对应关系。
+2. 如果用户给了 PPTX/PDF/slides 材料，先导入或回读为 Slides；PPTX 必须导入，PDF 只有在明显是长文档/资料而不是演示稿、模板或视觉底稿时才跳过导入。
+3. 如果没有用户提供的模板材料、且适合内置模板，再用 `template_tool.py search` 检索，锁定模板后用 `summarize` 获取主题和页型信息。
+4. 选择唯一 plan 目录：`.lark-slides/plan/<deck-or-task-id>/`。
+5. 先创建目录：`mkdir -p .lark-slides/plan/<deck-or-task-id>`。
+6. 写入 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`。
+7. 读取 `xml-schema-quick-ref.md`、`visual-planning.md` 和 `asset-planning.md`。
+8. 按 plan、visual planning 和 asset planning 规则逐页生成 XML，把 `layout_type`、`visual_focus`、`text_density` 转成具体页面几何和文本量约束；只有缺失的新素材才转成可执行兜底视觉，源页素材不算缺失素材。
+9. 创建或替换后用 `xml_presentations.get` 回读，核对页面数量、关键元素和 plan 到 XML 的对应关系。
 
 模板不能代替 plan。模板搜索和摘要只能影响 `theme_style`、页面流、布局选择和局部布局骨架；最终仍必须有 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`。
 
+## Imported Deck Preservation
+
+当用户提供 PPTX/PDF/slides 作为模板、底稿、版式参考或二创对象时，plan 必须把导入后的 presentation 当成目标，而不是把它当成普通参考图。
+
+流程：
+
+1. 先用 `drive +import --type slides` 导入本地 PPTX/PDF，或用 `xml_presentations.get` 回读已有 Slides。
+2. 保存导入/回读 XML 到 plan 目录，记录 `target_xml_presentation_id`、`revision_id`、每页 `slide_id`。
+3. 做每页 `source_asset_inventory`：`<style>` 背景、`<img src="...">` file token、`<chart>`、`<table>`、`<whiteboard>`、关键 shape/motif 和它们的 bbox。这个清单是事实层，来自 `source.xml`，不要用模型偏好改写事实。
+4. 写 plan 时为每个目标页绑定 `source_slide_id`，并写 `rewrite_contract`。默认 `reuse_policy` 是 `preserve_by_default`：源页素材默认锁定保留。
+5. 生成完整 `<slide>` XML 时，先复制源页 `<style>` 和 locked assets，再替换模板占位文案，最后补充新业务图形。
+6. 默认用 `slides +replace-pages` 执行页面级替换。仓库代码中的命令名是复数 `+replace-pages`；即使只替换一页，也传一个包含 1 个 item 的 `pages` 数组。
+
+`+replace-slide` 只适合小型块级编辑：改一个标题、插入一个图、替换一个已知 block。导入模板二创不要默认走它，因为它依赖最新 `block_id` 和局部 XML 片段，更容易触发 3350001。
+
+禁止把模板二创理解成"按模板风格重画"。`discarded_blocks` 必须逐块列出 `type`、`id` 和具体原因；`discarded_blocks.type = "all"` 默认非法。只有用户明确说"不要保留模板素材"、"只参考风格重做"等同义要求时，才允许 `rewrite_mode: "style_reference_only"`，并必须在 plan 中记录 `user_intent_evidence`。
+
 ## Plan Path
 
 Use a separate plan directory per deck or task so multiple presentations in the same workspace cannot overwrite each other.
@@ -56,6 +74,27 @@ Exception:
 ```json
 {
   "presentation_goal": "Explain the proposal and secure approval for the next phase.",
+  "target_xml_presentation_id": "optional existing/imported presentation id for in-place rewrite",
+  "source_deck": {
+    "source_type": "pptx|pdf|slides|none",
+    "source_path_or_url": "optional original user material",
+    "source_xml_path": ".lark-slides/plan/example/source.xml",
+    "source_slide_count": 12
+  },
+  "source_asset_inventory": {
+    "generated_from": ".lark-slides/plan/example/source.xml",
+    "default_policy": "preserve_by_default",
+    "pages": [
+      {
+        "source_slide_id": "old1",
+        "locked_assets": [
+          {"type": "style", "id": "slide-style", "reason": "template background"},
+          {"type": "img", "id": "bPk", "src": "file_token", "reason": "template hero visual"},
+          {"type": "shape", "id": "bQr", "role": "motif", "reason": "layout structure"}
+        ]
+      }
+    ]
+  },
   "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.",
   "visual_system": {
@@ -83,6 +122,15 @@ Exception:
     {
       "page": 1,
       "title": "Proposal Title",
+      "source_slide_id": "optional original slide id when rewriting an imported/existing deck",
+      "rewrite_mode": "preserve_template",
+      "rewrite_contract": {
+        "reuse_policy": "preserve_by_default",
+        "must_reuse": ["style:slide-style", "img:bPk", "shape:bQr"],
+        "discarded_blocks": [
+          {"type": "shape", "id": "bAb", "reason": "template placeholder text"}
+        ]
+      },
       "key_message": "The initiative is ready for a focused pilot.",
       "layout_type": "title-cover",
       "visual_focus": "Large title area with one concise supporting statement.",
@@ -104,6 +152,9 @@ Exception:
 Top-level fields:
 
 - `presentation_goal`: what the whole deck is trying to achieve.
+- `target_xml_presentation_id`: required when rewriting an imported or existing deck in place.
+- `source_deck`: required when user-provided PPTX/PDF/slides material was imported or read back.
+- `source_asset_inventory`: required when `source_deck.source_type` is `pptx`, `pdf`, or `slides`; record source-page assets before planning new page XML.
 - `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.
@@ -115,6 +166,9 @@ Each slide must include:
 
 - `page`: 1-based page number.
 - `title`: slide title.
+- `source_slide_id`: required when this page rewrites an imported/existing page.
+- `rewrite_mode`: `preserve_template` by default for imported/existing deck rewrites; use `style_reference_only` only when the user explicitly asked not to preserve template assets.
+- `rewrite_contract`: required when `source_slide_id` is present; list locked source assets to reuse and any individually discarded source blocks.
 - `key_message`: the one idea this page must land.
 - `layout_type`: planned page structure.
 - `visual_focus`: dominant visual object or region.
@@ -204,6 +258,8 @@ Before writing each slide XML, map the plan fields to concrete decisions:
 - `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.
+- `source_asset_inventory` determines which source XML blocks are locked by default. Copy source `<style>`, `<img src>` file tokens, charts, tables, whiteboards, and key motif shapes before generating new business visuals.
+- `rewrite_contract.discarded_blocks` only removes individually named source blocks. Do not use `type: "all"` unless `rewrite_mode` is `style_reference_only` and `user_intent_evidence` records the user's explicit instruction.
 
 After creating the PPT, fetch the presentation and verify:
 
@@ -217,3 +273,4 @@ After creating the PPT, fetch the presentation and verify:
 - 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.
+- For imported/template rewrites, replacement/readback XML still contains locked source assets from `source_asset_inventory`, especially background style, image tokens, charts, tables, whiteboards, and recurring motif blocks. If a locked source asset disappears, the plan must contain a block-level discard reason.

skills/lark-slides/references/troubleshooting.md

@@ -21,7 +21,7 @@
 4. 检查标签闭合、属性引号、`<content>` 结构，以及 `<slide>` 直接子元素。
 5. 页面空白、溢出、重叠或越界时，按 [validation-checklist.md](validation-checklist.md) 运行 XML 文本重叠检查，并人工核对越界、截断、图文压盖等视觉风险；工具当前只会报告 `xml_not_well_formed` / `bbox_overlap`。
 6. 如果使用 `--slides '[...]'`，怀疑 shell 截断时直接切到两步创建：先 `slides +create`，再用 `xml_presentation.slide.create` 逐页添加。
-7. 局部问题用 `+replace-slide` 块级修正；整页结构要改时再用 `slide.delete` 旧页 + `slide.create` 新页。
+7. 小型局部问题用 `+replace-slide` 块级修正；整页结构要改、导入模板二创或需要保留页面素材时，用 `+replace-pages`，不要手写 `slide.delete` + `slide.create` 编排。
 
 ## Symptom Fixes
 

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

@@ -14,7 +14,8 @@
 6. 检查页面不是全部退化为标题加 bullet list。
 7. 检查视觉层级：标题、主视觉、支撑信息三者可区分。
 8. 检查明显溢出和布局风险：重叠、越界、底部拥挤、长文本框。
-9. 在最终回复中给出简短验证记录。
+9. 如果是导入 PPTX/PDF/slides 后二创，必须做 XML 级素材核对：`source_asset_inventory` / `rewrite_contract.must_reuse` 中的 locked assets 是否仍在 replacement 或回读 XML 中。
+10. 在最终回复中给出简短验证记录。
 
 回读命令：
 
@@ -61,6 +62,17 @@ python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentatio
 - `visual_focus` 是页面中最醒目或最大的信息区域之一。
 - `text_density` 影响了文本量，没有用长 bullet 框替代规划。
 - `asset_need` 有真实素材时已放入正确区域；没有真实素材时，`fallback_if_missing` 已用 XML 形状、线条、标签、表格或图表兜底。
+- 导入/模板二创任务中，`source_asset_inventory` 里的 `<style>`、`<img src>`、`<chart>`、`<table>`、`<whiteboard>` 或 motif shape 已在最终 XML 中保留，除非 `rewrite_contract.discarded_blocks` 逐块标记了 `type`、`id` 和原因。
+
+## Source Asset Preservation
+
+模板二创默认 `reuse_policy: "preserve_by_default"`。验证时不要只看新页是否有视觉元素，还要核对源素材是否被保留：
+
+- 源页 locked assets 必须出现在 `pages.json` replacement XML 或最终回读 XML 中。
+- 如果源页存在 `<img>`、`<table>`、`<chart>`、`<whiteboard>` 或关键 motif，replacement 里对应类型数量明显归零，且 plan 没有逐块 discard，视为失败。
+- `discarded_blocks.type = "all"` 默认不是有效说明。只有 `rewrite_mode: "style_reference_only"` 且 plan 记录了用户明确要求不保留模板素材时，才可接受。
+- `fallback_if_missing` 不能解释源素材消失；它只适用于源页没有可用素材时的新资产兜底。
+- 截图检查是可选增强能力，不是默认必需项；没有截图能力时，至少完成 XML 级素材核对。
 
 如果用户指定了关键页，例如“架构解释”“Self-Attention 机制解释”“对比或演进视角”“总结页”，最终验证记录必须逐项说明这些页已存在。
 
@@ -72,6 +84,8 @@ python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentatio
 - 关键文本没有出现在回读 XML 中。
 - 图片仍是 `@./path`，或 `<img src>` 是 http(s) 外链。
 - 页面依赖的图片区域为空，且没有 fallback visual。
+- 导入模板的背景、核心图片、图表、表格或品牌/版式 motif 在最终 XML 中消失，且 plan 没有逐块说明丢弃原因。
+- 源页有 `<img>` / `<table>` 等素材，replacement 或最终回读 XML 中对应类型数量归零，且没有 `style_reference_only` 用户意图证据。
 - 返回 XML 缺页、页序明显错误，或某页内容被 shell 截断。
 - 大量形状坐标完全相同，导致主体内容重叠。
 - 渐变背景回退成空白或白底，导致文字不可读。
@@ -104,7 +118,8 @@ python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentatio
 - 回读：已执行 xml_presentations.get，实际页数 N / 预期 N。
 - 关键页：架构解释 / Self-Attention / 对比或演进 / 总结页均存在。
 - 结构：检查了主要 shape/img/table/chart 元素，无明显空白页或破损页。
+- 素材：已核对 source_asset_inventory / rewrite_contract.must_reuse，导入底稿的背景、图片 token、图表/表格或 motif 已按 plan 保留；被删除素材均有逐块 discarded reason。
 - 布局：检查了标题层级、主视觉、重叠/越界/文本溢出风险。
 ```
 
-不要声称完成了人工视觉验收，除非确实打开或获取了可视化结果。仅从 XML 静态检查得出的结论，应表述为“静态检查未发现明显问题”。
+不要声称完成了人工视觉验收，除非确实打开或获取了可视化结果。仅从 XML 静态检查得出的结论，应表述为“静态检查未发现明显问题”。截图能力可能不可用，不要把截图作为默认交付门槛。

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 |