From f1ead0849f349ea89ea0782539d12428d4915af6 Mon Sep 17 00:00:00 2001
From: niezhiwei <niezhiwei@bytedance.com>
Date: Fri, 14 Aug 2026 16:24:27 +0800
Subject: [PATCH] feat(slides): auto-upload @path images in +update-slide

Bring +update-slide in line with +create and +add-slide: <img src="@local">
placeholders in --content are now extracted, validated, uploaded to the target
presentation, and rewritten to file_token before the page is replaced. This
removes the manual +media-upload round-trip that was tripping agents into
passing unresolved local paths to the backend.

- Validate rejects missing files and directory placeholders locally, before any
  API call, and gates docs:document.media:upload as a conditional scope.
- Execute uploads once per unique path (deduped) and, on partial failure,
  appends a progress hint so a retry does not silently re-upload every image.
- DryRun plans the upload steps ahead of the replace and reports
  images_to_upload so the irreversible half is visible up front.
- Skill reference documents the placeholder pipeline, CWD resolution, the
  docs:document.media:upload scope on 1061004/403, and images_uploaded output.

The command Description and skill intro stay scoped to WHAT the command does;
the @path capability is surfaced through the flag help, Tips, and the reference
section rather than restated in the one-line Description or a cross-command note.
---
 shortcuts/slides/slides_update_slide.go       |  92 +++++-
 shortcuts/slides/slides_update_slide_test.go  | 310 +++++++++++++++++-
 .../cli/lark-slides-update-slide.md           |  19 +-
 .../slides/slides_update_slide_dryrun_test.go |  51 +++
 4 files changed, 457 insertions(+), 15 deletions(-)

diff --git a/shortcuts/slides/slides_update_slide.go b/shortcuts/slides/slides_update_slide.go
index 38288f07bf..83a02d8912 100644
--- a/shortcuts/slides/slides_update_slide.go
+++ b/shortcuts/slides/slides_update_slide.go
@@ -43,13 +43,16 @@ var SlidesUpdateSlide = common.Shortcut{
 	Description: "Apply a full <slide> XML to an existing slide, replacing the page in one request (keeps slide_id and page order)",
 	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"},
+	// Both extras are path-dependent, so they stay conditional rather than
+	// gating every call: wiki:node:read only when --presentation is a wiki URL,
+	// docs:document.media:upload only when --content carries @-placeholders.
+	ConditionalScopes: []string{"wiki:node:read", "docs:document.media:upload"},
 	AuthTypes:         []string{"user", "bot"},
 	Tips: []string{
 		"Read the page first with `slides +xml-get --slide-id <id>`, edit that XML, hand it back whole",
 		"Anything left out of --content is removed from the page — pass the full page, not a fragment",
 		"Editing one element is cheaper with `slides +replace-slide`",
+		"<img src=\"@path\"> placeholders resolve against the current directory, not the directory of an @file passed to --content, and are deduplicated per call",
 	},
 	Flags:    updateSlideFlags,
 	Validate: updateSlideValidate,
@@ -111,8 +114,22 @@ func updateSlideValidate(_ context.Context, runtime *common.RuntimeContext) erro
 	if err != nil {
 		return err
 	}
-	_, err = updateSlideContent(runtime, slideID)
-	return err
+	content, err := updateSlideContent(runtime, slideID)
+	if err != nil {
+		return err
+	}
+	// Check placeholder files before any API call so a typo in a path fails
+	// locally instead of after part of the page's images are uploaded.
+	placeholders := extractImagePlaceholderPaths([]string{content})
+	if len(placeholders) > 0 {
+		if err := runtime.EnsureScopes([]string{"docs:document.media:upload"}); err != nil {
+			return err
+		}
+		if err := validateImagePlaceholderFiles(runtime, "--content", placeholders); err != nil {
+			return err
+		}
+	}
+	return nil
 }
 
 func updateSlideDryRun(_ context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
@@ -132,21 +149,47 @@ func updateSlideDryRun(_ context.Context, runtime *common.RuntimeContext) *commo
 		return fail(err)
 	}
 
+	placeholders := extractImagePlaceholderPaths([]string{content})
 	dry := common.NewDryRunAPI()
+
 	presentationID := ref.Token
+	step := 1
+	total := 1 + len(placeholders)
+	if ref.Kind == "wiki" {
+		total++
+	}
+
 	if ref.Kind == "wiki" {
 		presentationID = "<resolved_slides_token>"
-		dry.Desc("2-step orchestration: resolve wiki → replace slide").
+		dry.Desc(fmt.Sprintf("%d-step orchestration: resolve wiki → replace slide", total)).
 			GET("/open-apis/wiki/v2/spaces/get_node").
-			Desc("[1] Resolve wiki node to slides presentation").
+			Desc(fmt.Sprintf("[%d/%d] Resolve wiki node to slides presentation", step, total)).
 			Params(map[string]interface{}{"token": ref.Token})
+		step++
+	} else if len(placeholders) > 0 {
+		dry.Desc(fmt.Sprintf("Upload %d image(s) + replace slide %s", len(placeholders), slideID))
 	} else {
 		dry.Desc(fmt.Sprintf("Replace slide %s with the supplied page XML", slideID))
 	}
+
+	// Uploads run against the target presentation, so a wiki ref resolves to a
+	// real id first; the placeholder tokens are unknown until then.
+	for _, path := range placeholders {
+		appendSlidesUploadDryRun(dry, path, presentationID, step)
+		step++
+	}
+
+	descSuffix := ""
+	if len(placeholders) > 0 {
+		descSuffix = " (img placeholders auto-replaced)"
+	}
 	dry.POST(slideReplaceAPIPath(presentationID)).
+		Desc(fmt.Sprintf("[%d/%d] Replace slide%s", step, total, descSuffix)).
 		Params(updateSlideQuery(runtime, slideID)).
 		Body(map[string]interface{}{"parts": updateSlideParts(slideID, content)})
-	return dry.Set("slide_id", slideID).Set("content_bytes", len(content))
+	return dry.Set("slide_id", slideID).
+		Set("content_bytes", len(content)).
+		Set("images_to_upload", len(placeholders))
 }
 
 func updateSlideExecute(_ context.Context, runtime *common.RuntimeContext) error {
@@ -167,10 +210,35 @@ func updateSlideExecute(_ context.Context, runtime *common.RuntimeContext) error
 		return err
 	}
 
+	result := map[string]interface{}{
+		"xml_presentation_id": presentationID,
+		"slide_id":            slideID,
+	}
+
+	// Uploads run against the target presentation, so they can only happen
+	// after a wiki ref has been resolved to a real presentation id. A single
+	// part carries the whole page, so an upload failure here means nothing was
+	// written; the hint says how many images already landed so a retry does not
+	// silently upload a second copy.
+	placeholders := extractImagePlaceholderPaths([]string{content})
+	if len(placeholders) > 0 {
+		tokens, uploaded, err := uploadSlidesPlaceholders(runtime, presentationID, placeholders, "--content")
+		if err != nil {
+			return appendSlidesProgressHint(err, fmt.Sprintf("slide was not updated; %d of %d image(s) uploaded before failure", uploaded, len(placeholders)))
+		}
+		content = replaceImagePlaceholders(content, tokens)
+		result["images_uploaded"] = uploaded
+	}
+
 	data, err := runtime.CallAPITyped("POST", slideReplaceAPIPath(presentationID),
 		updateSlideQuery(runtime, slideID),
 		map[string]interface{}{"parts": updateSlideParts(slideID, content)})
 	if err != nil {
+		if len(placeholders) > 0 {
+			// The images are already in the deck's media store; say so, or a
+			// retry silently uploads a second copy of every file.
+			err = appendSlidesProgressHint(err, fmt.Sprintf("%d image(s) were uploaded before the slide failed; re-running will upload them again", len(placeholders)))
+		}
 		return enrichUpdateSlideError(err)
 	}
 
@@ -182,15 +250,15 @@ func updateSlideExecute(_ context.Context, runtime *common.RuntimeContext) error
 		if updateSlideReasonIsNotFound(reason) {
 			hint = updateSlideNotFoundHint
 		}
-		return errs.NewAPIError(errs.SubtypeInvalidParameters,
+		err := errs.NewAPIError(errs.SubtypeInvalidParameters,
 			"slide %s was not updated: %s", slideID, reason).
 			WithHint(hint)
+		if len(placeholders) > 0 {
+			return appendSlidesProgressHint(err, fmt.Sprintf("%d image(s) were uploaded before the slide failed; re-running will upload them again", len(placeholders)))
+		}
+		return err
 	}
 
-	result := map[string]interface{}{
-		"xml_presentation_id": presentationID,
-		"slide_id":            slideID,
-	}
 	if v, ok := data["revision_id"]; ok {
 		result["revision_id"] = v
 	}
diff --git a/shortcuts/slides/slides_update_slide_test.go b/shortcuts/slides/slides_update_slide_test.go
index 5b07f0fdba..c04125b66e 100644
--- a/shortcuts/slides/slides_update_slide_test.go
+++ b/shortcuts/slides/slides_update_slide_test.go
@@ -6,8 +6,11 @@ package slides
 import (
 	"encoding/json"
 	"errors"
+	"io/fs"
 	"net/http"
 	"net/url"
+	"os"
+	"path/filepath"
 	"reflect"
 	"strings"
 	"testing"
@@ -21,6 +24,9 @@ const testPageXML = `<slide><style><fill type="solid" color="rgba(0,0,0,1)"/></s
 	`<data><shape id="bUn" type="text"><content fontFamily="思源黑体"><p>hi</p></content></shape></data></slide>`
 
 func TestUpdateSlideDeclaredScopes(t *testing.T) {
+	// Pre-flight stays at the two slides scopes: an XML-only page needs neither
+	// wiki read nor media upload, and gating every call on them would force
+	// unrelated consent.
 	want := []string{"slides:presentation:update", "slides:presentation:write_only"}
 	for _, identity := range []string{"user", "bot"} {
 		if got := SlidesUpdateSlide.ScopesForIdentity(identity); !reflect.DeepEqual(got, want) {
@@ -28,8 +34,9 @@ func TestUpdateSlideDeclaredScopes(t *testing.T) {
 		}
 	}
 	got := SlidesUpdateSlide.DeclaredScopesForIdentity("user")
-	if !reflect.DeepEqual(got, append(append([]string{}, want...), "wiki:node:read")) {
-		t.Fatalf("declared scopes = %#v", got)
+	wantDeclared := []string{"slides:presentation:update", "slides:presentation:write_only", "wiki:node:read", "docs:document.media:upload"}
+	if !reflect.DeepEqual(got, wantDeclared) {
+		t.Fatalf("declared scopes = %#v, want %#v", got, wantDeclared)
 	}
 }
 
@@ -577,3 +584,302 @@ func TestUpdateSlideKeepsUpstreamHint(t *testing.T) {
 		t.Fatalf("hint was clobbered on a second pass: %q -> %q", before, p.Hint)
 	}
 }
+
+// testPageImageXML references the same local image twice so the dedupe path is
+// exercised: two <img> placeholders, one upload, both rewritten.
+const testPageImageXML = `<slide xmlns="https://www.larkoffice.com/sml/2.0"><data>` +
+	`<img src="@./chart.png" topLeftX="10" topLeftY="10" width="100" height="100"/>` +
+	`<img src="@./chart.png" topLeftX="200" topLeftY="10" width="100" height="100"/>` +
+	`</data></slide>`
+
+// TestUpdateSlideUploadsImagePlaceholder is why +update-slide gained @path
+// support: before it, replacing a page with a fresh local image meant calling
+// +media-upload and splicing the token into the XML by hand. The same image
+// referenced twice must still upload once.
+func TestUpdateSlideUploadsImagePlaceholder(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, "chart.png"), []byte("png-bytes"), 0o600); err != nil {
+		t.Fatalf("write fixture: %v", err)
+	}
+	withSlidesTestWorkingDir(t, dir)
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/upload_all",
+		Body:   map[string]interface{}{"code": 0, "data": map[string]interface{}{"file_token": "tok_chart"}},
+	})
+	replaceStub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_img/slide/replace",
+		Body:   map[string]interface{}{"code": 0, "data": map[string]interface{}{"revision_id": 11}},
+	}
+	reg.Register(replaceStub)
+
+	err := runSlidesShortcut(t, f, stdout, SlidesUpdateSlide, []string{
+		"+update-slide",
+		"--presentation", "pres_img",
+		"--slide-id", "pYw",
+		"--content", testPageImageXML,
+		"--as", "user",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var body struct {
+		Parts []struct{ Replacement string } `json:"parts"`
+	}
+	if err := json.Unmarshal(replaceStub.CapturedBody, &body); err != nil {
+		t.Fatalf("decode body: %v raw=%s", err, replaceStub.CapturedBody)
+	}
+	if len(body.Parts) != 1 {
+		t.Fatalf("sent %d parts, want exactly 1: %s", len(body.Parts), replaceStub.CapturedBody)
+	}
+	content := body.Parts[0].Replacement
+	if strings.Contains(content, "@./chart.png") {
+		t.Fatalf("placeholder was not rewritten: %s", content)
+	}
+	if strings.Count(content, `src="tok_chart"`) != 2 {
+		t.Fatalf("both references should carry the uploaded token, got: %s", content)
+	}
+
+	data := decodeShortcutData(t, stdout)
+	if data["images_uploaded"] != float64(1) {
+		t.Fatalf("images_uploaded = %v, want 1 (deduped by path)", data["images_uploaded"])
+	}
+}
+
+// TestUpdateSlideMissingImageFailsBeforeAnyCall proves the placeholder check
+// runs in Validate: a bad path must not reach the API, or the caller is left
+// guessing whether the page was overwritten.
+func TestUpdateSlideMissingImageFailsBeforeAnyCall(t *testing.T) {
+	withSlidesTestWorkingDir(t, t.TempDir())
+
+	// Register nothing on purpose: httpmock rejects any unstubbed request, so
+	// reaching the API surfaces as "no stub for POST ..." rather than the
+	// ValidationError asserted below. That is the no-call assertion.
+	f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+
+	err := runSlidesShortcut(t, f, stdout, SlidesUpdateSlide, []string{
+		"+update-slide",
+		"--presentation", "pres_abc",
+		"--slide-id", "pYw",
+		"--content", `<slide><data><img src="@./missing.png"/></data></slide>`,
+		"--as", "user",
+	})
+	if err == nil {
+		t.Fatal("expected a validation error for a missing image file")
+	}
+	// The Stat failure is wrapped, so a caller can still tell a missing file
+	// apart from an unreadable one without parsing the message.
+	assertValidationProblem(t, err, "--content", fs.ErrNotExist)
+	// The path came from an <img> inside the XML, not from an @file passed to
+	// --content. Naming the element keeps the caller from re-checking the flag
+	// argument.
+	if !strings.Contains(err.Error(), `<img src="@./missing.png">`) {
+		t.Fatalf("error should quote the <img> placeholder, got %v", err)
+	}
+}
+
+// TestUpdateSlideRejectsDirectoryImagePlaceholder covers the placeholder that
+// exists but is not a file: Stat succeeds, so only the mode check stops a
+// directory from being streamed at the upload endpoint.
+func TestUpdateSlideRejectsDirectoryImagePlaceholder(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.Mkdir(filepath.Join(dir, "chart.png"), 0o750); err != nil {
+		t.Fatalf("make fixture dir: %v", err)
+	}
+	withSlidesTestWorkingDir(t, dir)
+
+	f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	err := runSlidesShortcut(t, f, stdout, SlidesUpdateSlide, []string{
+		"+update-slide",
+		"--presentation", "pres_abc",
+		"--slide-id", "pYw",
+		"--content", `<slide><data><img src="@./chart.png"/></data></slide>`,
+		"--as", "user",
+	})
+	if err == nil {
+		t.Fatal("expected a validation error for a directory placeholder")
+	}
+	// No cause: Stat succeeded, so there is no underlying error to wrap.
+	assertValidationProblem(t, err, "--content", nil)
+	if !strings.Contains(err.Error(), "must be a regular file") {
+		t.Fatalf("err = %v, want the regular-file diagnosis", err)
+	}
+}
+
+// TestUpdateSlideDryRunPlansUploadsBeforeReplace proves the plan states the
+// upload cost up front. The uploads are the irreversible half of the command —
+// they land in the deck's media store even if the replace later fails — so a
+// caller who dry-runs first must be able to see them coming.
+func TestUpdateSlideDryRunPlansUploadsBeforeReplace(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, "chart.png"), []byte("png-bytes"), 0o600); err != nil {
+		t.Fatalf("write fixture: %v", err)
+	}
+	withSlidesTestWorkingDir(t, dir)
+
+	f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	slideXML := `<slide xmlns="https://www.larkoffice.com/sml/2.0"><data>` +
+		`<img src="@./chart.png" topLeftX="10" topLeftY="10" width="100" height="100"/>` +
+		`</data></slide>`
+
+	err := runSlidesShortcut(t, f, stdout, SlidesUpdateSlide, []string{
+		"+update-slide",
+		"--presentation", "pres_img",
+		"--slide-id", "pYw",
+		"--content", slideXML,
+		"--dry-run",
+		"--as", "user",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data := decodeShortcutData(t, stdout)
+	if data["images_to_upload"] != float64(1) {
+		t.Fatalf("images_to_upload = %v, want 1", data["images_to_upload"])
+	}
+	steps := decodeShortcutDryRunAPI(t, stdout)
+	if len(steps) != 2 {
+		t.Fatalf("planned %d calls, want upload then replace: %#v", len(steps), steps)
+	}
+	upload := assertDryRunStep(t, steps, 0, "POST", "/open-apis/drive/v1/medias/upload_all")
+	uploadBody, _ := upload["body"].(map[string]interface{})
+	if uploadBody["parent_type"] != slidesMediaParentType {
+		t.Fatalf("upload parent_type = %v, want %q", uploadBody["parent_type"], slidesMediaParentType)
+	}
+	if uploadBody["parent_node"] != "pres_img" {
+		t.Fatalf("upload parent_node = %v, want pres_img", uploadBody["parent_node"])
+	}
+	assertDryRunStep(t, steps, 1, "POST", "/open-apis/slides_ai/v1/xml_presentations/pres_img/slide/replace")
+}
+
+// TestUpdateSlideDryRunPlansSingleReplaceWithoutImages keeps the plain case
+// honest: no @path means one POST and images_to_upload=0.
+func TestUpdateSlideDryRunPlansSingleReplaceWithoutImages(t *testing.T) {
+	t.Parallel()
+
+	f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	err := runSlidesShortcut(t, f, stdout, SlidesUpdateSlide, []string{
+		"+update-slide",
+		"--presentation", "pres_abc",
+		"--slide-id", "pYw",
+		"--content", testPageXML,
+		"--dry-run",
+		"--as", "user",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data := decodeShortcutData(t, stdout)
+	if data["images_to_upload"] != float64(0) {
+		t.Fatalf("images_to_upload = %v, want 0", data["images_to_upload"])
+	}
+	steps := decodeShortcutDryRunAPI(t, stdout)
+	if len(steps) != 1 {
+		t.Fatalf("planned %d calls, want a single POST: %#v", len(steps), steps)
+	}
+	assertDryRunStep(t, steps, 0, "POST", "/open-apis/slides_ai/v1/xml_presentations/pres_abc/slide/replace")
+}
+
+// TestUpdateSlideReportsUploadedImagesWhenReplaceFails covers the partial-
+// failure hint. The images are already in the deck's media store at that point,
+// so a blind retry silently uploads a second copy; the hint is the only thing
+// telling the caller they already landed.
+func TestUpdateSlideReportsUploadedImagesWhenReplaceFails(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, "chart.png"), []byte("png-bytes"), 0o600); err != nil {
+		t.Fatalf("write fixture: %v", err)
+	}
+	withSlidesTestWorkingDir(t, dir)
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/upload_all",
+		Body:   map[string]interface{}{"code": 0, "data": map[string]interface{}{"file_token": "tok_chart"}},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_img/slide/replace",
+		Body:   map[string]interface{}{"code": 3350001, "msg": "invalid slide xml"},
+	})
+
+	slideXML := `<slide xmlns="https://www.larkoffice.com/sml/2.0"><data>` +
+		`<img src="@./chart.png" topLeftX="10" topLeftY="10" width="100" height="100"/>` +
+		`</data></slide>`
+
+	err := runSlidesShortcut(t, f, stdout, SlidesUpdateSlide, []string{
+		"+update-slide",
+		"--presentation", "pres_img",
+		"--slide-id", "pYw",
+		"--content", slideXML,
+		"--as", "user",
+	})
+	if err == nil {
+		t.Fatal("expected the backend rejection to surface")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("err = %v, want typed problem metadata", err)
+	}
+	// The backend rejection must survive the appended hint: only the category
+	// separates a preserved API error from the Internal/Unknown fallback wrap.
+	if problem.Category != errs.CategoryAPI {
+		t.Fatalf("Category = %q, want %q: the backend rejection must survive the hint",
+			problem.Category, errs.CategoryAPI)
+	}
+	if !strings.Contains(problem.Hint, "1 image(s) were uploaded before the slide failed") {
+		t.Fatalf("Hint = %q, want the already-uploaded count", problem.Hint)
+	}
+}
+
+// TestUpdateSlideReportsProgressWhenUploadFails covers the other half of the
+// partial-failure story: the replace was never attempted, so the hint must say
+// the slide was not updated rather than leave the caller checking.
+func TestUpdateSlideReportsProgressWhenUploadFails(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, "chart.png"), []byte("png-bytes"), 0o600); err != nil {
+		t.Fatalf("write fixture: %v", err)
+	}
+	withSlidesTestWorkingDir(t, dir)
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/upload_all",
+		Body:   map[string]interface{}{"code": 1061002, "msg": "params error"},
+	})
+	// The replace endpoint is deliberately unstubbed: reaching it would fail as
+	// "no stub for POST .../slide/replace", which is the no-write assertion.
+
+	slideXML := `<slide xmlns="https://www.larkoffice.com/sml/2.0"><data>` +
+		`<img src="@./chart.png" topLeftX="10" topLeftY="10" width="100" height="100"/>` +
+		`</data></slide>`
+
+	err := runSlidesShortcut(t, f, stdout, SlidesUpdateSlide, []string{
+		"+update-slide",
+		"--presentation", "pres_img",
+		"--slide-id", "pYw",
+		"--content", slideXML,
+		"--as", "user",
+	})
+	if err == nil {
+		t.Fatal("expected the upload failure to surface")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("err = %v, want typed problem metadata", err)
+	}
+	if problem.Category != errs.CategoryAPI || problem.Subtype != errs.SubtypeInvalidParameters {
+		t.Fatalf("problem = %#v, want %s/%s: the upload rejection must survive the hint",
+			problem, errs.CategoryAPI, errs.SubtypeInvalidParameters)
+	}
+	if !strings.Contains(problem.Hint, "slide was not updated") {
+		t.Fatalf("Hint = %q, want it to state the slide was not updated", problem.Hint)
+	}
+}
diff --git a/skills/lark-slides/references/cli/lark-slides-update-slide.md b/skills/lark-slides/references/cli/lark-slides-update-slide.md
index 38712cb64d..4e9dc6ee0f 100644
--- a/skills/lark-slides/references/cli/lark-slides-update-slide.md
+++ b/skills/lark-slides/references/cli/lark-slides-update-slide.md
@@ -54,6 +54,22 @@ lark-cli slides +update-slide --as user \
 
 一次请求就能同时做完改样式、插入、删除、换备注、换背景——这是 `+replace-slide` 逐元素 part 做不到的（它没法寻址背景，也没有 move 操作）。
 
+## 本地图片：`@路径` 占位符
+
+`--content` 的 XML 里写 `<img src="@./chart.png" .../>`，CLI 会：先把每个不重复的本地文件上传到这份演示文稿（`parent_type=slide_file`），再把 `src` 替换成返回的 `file_token`，最后才整页写回。
+
+占位符路径按**执行命令时的 CWD** 解析，跟 `--content @file` 所在目录无关；`@./assets/x.png` 找的是 `$PWD/assets/x.png`。
+
+```bash
+lark-cli slides +update-slide --as user \
+  --presentation "$PRES" --slide-id "$SLIDE" \
+  --content '<slide xmlns="https://www.larkoffice.com/sml/2.0"><data><img src="@./chart.png" topLeftX="100" topLeftY="100" width="320" height="180"/></data></slide>'
+```
+
+- 文件不存在、不是普通文件、超过 20 MB，都在**调用任何接口之前**报错，不会留下半成品。
+- 去重只在**单次调用内**生效：多页共用同一张图时，逐页更新会把它每页重传一次。这种图先用 [`+media-upload`](lark-slides-media-upload.md) 传一次，把 `file_token` 写进各页的 `src`。
+- 整页只发一个 part，所以上传是这条命令里**唯一不可逆的一半**：图先落进演示文稿的 media store，若随后 replace 失败，报错 hint 会告诉你已经传了几张，直接重试会再传一份。先 `--dry-run` 可提前看到 `images_to_upload` 和上传步骤。
+
 ## 标准读-改-写流程
 
 ```bash
@@ -130,6 +146,7 @@ lark-cli slides +xml-get --as user \
 | `xml_presentation_id` | 实际写入的演示文稿 ID |
 | `slide_id` | 与传入相同——整页覆盖不换页 id |
 | `revision_id` | 写入后的新版本号 |
+| `images_uploaded` | 仅当 `--content` 带 `@` 占位符时出现：本次去重后实际上传的图片张数 |
 
 服务端拒绝这次写入时（`failed_reason` 非空）**不会**返回成功输出，而是报错并带上原因——单个 part 承载整页，任何失败都意味着页面没被写入。
 
@@ -143,4 +160,4 @@ lark-cli slides +xml-get --as user \
 | 3350001，原因包含 `not found` | `--presentation` 不匹配，或 `--slide-id` 对应的页面已被删除 | 检查 `--presentation` 和 `--slide-id`，再用 `slides +xml-get` 回读当前页面 ID |
 | 3350001，其他 invalid param | `--content` 的 XML 结构有问题（如 `<shape>` 缺 `<content/>`、包含服务端不支持的元素） | 按 [error-handling.md](../workflow/error-handling.md) 检查 `--content` 的 XML 结构 |
 | 3350002 not found | `--revision-id` 传了不存在的版本号 | 用 `-1` 或真实存在的 `revision_id` |
-| 1061004 / 403 | 当前身份对这份 PPT 没有编辑权限 | 检查是否拥有 `slides:presentation:update` 或 `slides:presentation:write_only` scope；wiki 链接另需 `wiki:node:read`；`--as bot` 还要求该 bot 对目标 PPT 有编辑权限 |
+| 1061004 / 403 | 当前身份对这份 PPT 没有编辑权限 | 检查是否拥有 `slides:presentation:update` 或 `slides:presentation:write_only` scope；wiki 链接另需 `wiki:node:read`，`@` 占位符另需 `docs:document.media:upload`；`--as bot` 还要求该 bot 对目标 PPT 有编辑权限 |
diff --git a/tests/cli_e2e/slides/slides_update_slide_dryrun_test.go b/tests/cli_e2e/slides/slides_update_slide_dryrun_test.go
index 72fbbc8b1f..83c126da8d 100644
--- a/tests/cli_e2e/slides/slides_update_slide_dryrun_test.go
+++ b/tests/cli_e2e/slides/slides_update_slide_dryrun_test.go
@@ -5,6 +5,8 @@ package slides
 
 import (
 	"context"
+	"os"
+	"path/filepath"
 	"testing"
 	"time"
 
@@ -60,6 +62,55 @@ func TestSlidesUpdateSlideDryRunE2E(t *testing.T) {
 		"the caller's own bytes must reach the request unchanged: %s", result.Stdout)
 }
 
+// TestSlidesUpdateSlideImageDryRunE2E pins the @path pipeline through the built
+// binary: an <img src="@local"> placeholder plans an upload_all step ahead of
+// the slide/replace, so the whole-page swap picks up a fresh local image the
+// same way +add-slide and +create do. The upload is the irreversible half, so
+// a caller who dry-runs first must see it coming.
+func TestSlidesUpdateSlideImageDryRunE2E(t *testing.T) {
+	setSlidesDryRunEnv(t)
+
+	dir := t.TempDir()
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "chart.png"), []byte("png-bytes"), 0o600))
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	t.Cleanup(cancel)
+
+	const imagePage = `<slide><data>` +
+		`<img src="@./chart.png" topLeftX="10" topLeftY="10" width="100" height="100"/>` +
+		`</data></slide>`
+
+	result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args: []string{
+			"slides", "+update-slide",
+			"--presentation", "presUpdateImageDryRun",
+			"--slide-id", "pYw",
+			"--content", imagePage,
+			"--dry-run",
+		},
+		DefaultAs: "bot",
+		WorkDir:   dir,
+	})
+	require.NoError(t, err)
+	result.AssertExitCode(t, 0)
+
+	require.Equal(t, int64(1), gjson.Get(result.Stdout, "data.images_to_upload").Int(), result.Stdout)
+
+	api := gjson.Get(result.Stdout, "data.api").Array()
+	require.Len(t, api, 2, "an @path page plans upload then replace: %s", result.Stdout)
+
+	require.Equal(t, "POST", gjson.Get(result.Stdout, "data.api.0.method").String(), result.Stdout)
+	require.Equal(t, "/open-apis/drive/v1/medias/upload_all",
+		gjson.Get(result.Stdout, "data.api.0.url").String(), result.Stdout)
+	require.Equal(t, "slide_file",
+		gjson.Get(result.Stdout, "data.api.0.body.parent_type").String(), result.Stdout)
+	require.Equal(t, "presUpdateImageDryRun",
+		gjson.Get(result.Stdout, "data.api.0.body.parent_node").String(), result.Stdout)
+
+	require.Equal(t, "/open-apis/slides_ai/v1/xml_presentations/presUpdateImageDryRun/slide/replace",
+		gjson.Get(result.Stdout, "data.api.1.url").String(), result.Stdout)
+}
+
 // TestSlidesUpdateAliasDryRunE2E exercises the spellings agents actually type:
 // the singular `slide` service alias, the `+update` command alias and `--xml`
 // instead of `--content`. All three must land on the canonical request.