feat: add iconpark lookup for lark slides

internal/registry/scope_priorities.json

@@ -439,6 +439,11 @@
     "final_score": "78.7030",
     "recommend": "true"
   },
+  {
+    "scope_name": "slides:presentation:screenshot",
+    "final_score": "78.7030",
+    "recommend": "true"
+  },
   {
     "scope_name": "slides:presentation:create",
     "final_score": "79.4755",

shortcuts/common/runner.go

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

shortcuts/common/runner_args_test.go

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

shortcuts/common/types.go

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

shortcuts/slides/shortcuts.go

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

shortcuts/slides/slides_screenshot.go

@@ -0,0 +1,442 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package slides
+
+import (
+	"context"
+	"encoding/base64"
+	"fmt"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
+
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/internal/vfs"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const defaultSlidesScreenshotDir = ".lark-slides/screenshots"
+
+var unsafeScreenshotFileCharRegex = regexp.MustCompile(`[^A-Za-z0-9._-]+`)
+
+// SlidesScreenshot fetches server-rendered slide screenshots and writes them to
+// local files. The raw API returns Base64 image payloads; this shortcut keeps
+// those payloads out of stdout so agents only see small file metadata.
+var SlidesScreenshot = common.Shortcut{
+	Service:     "slides",
+	Command:     "+screenshot",
+	Description: "Save slide screenshots to local files without printing Base64 image data",
+	Risk:        "read",
+	Scopes:      []string{"slides:presentation:screenshot"},
+	// Only wiki URL inputs need wiki:node:read. Keep it conditional so plain
+	// slides IDs/URLs do not require an unrelated wiki scope.
+	ConditionalScopes: []string{"wiki:node:read"},
+	AuthTypes:         []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "presentation", Desc: "xml_presentation_id, slides URL, or wiki URL that resolves to slides; list mode only"},
+		{Name: "slide-id", Type: "string_array", Desc: "slide page identifier (repeat for multiple slides)"},
+		{Name: "slide-number", Type: "int_array", Desc: "slide page number (repeat for multiple slides)"},
+		{Name: "content", Desc: "slide XML content to render directly instead of fetching existing slides", Input: []string{common.File, common.Stdin}},
+		{Name: "output-dir", Default: defaultSlidesScreenshotDir, Desc: "relative directory for saved screenshots"},
+		{Name: "output-name", Desc: "file name stem for --content render output"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		renderMode := runtime.Changed("content")
+		if renderMode {
+			if strings.TrimSpace(runtime.Str("content")) == "" {
+				return common.FlagErrorf("--content cannot be empty")
+			}
+			if len(normalizeSlideIDs(runtime.StrArray("slide-id"))) > 0 || len(runtime.IntArray("slide-number")) > 0 {
+				return common.FlagErrorf("--content cannot be used with --slide-id or --slide-number")
+			}
+			if runtime.Changed("presentation") {
+				return common.FlagErrorf("--presentation cannot be used with --content")
+			}
+		} else {
+			ref, err := parsePresentationRef(runtime.Str("presentation"))
+			if err != nil {
+				return err
+			}
+			if ref.Kind == "wiki" {
+				if err := runtime.EnsureScopes([]string{"wiki:node:read"}); err != nil {
+					return err
+				}
+			}
+			if _, err := normalizeSlideNumbers(runtime.IntArray("slide-number")); err != nil {
+				return err
+			}
+			if !hasSlideScreenshotSelector(runtime) {
+				return common.FlagErrorf("--slide-id or --slide-number is required")
+			}
+		}
+		if _, err := validateScreenshotOutputDir(runtime.Str("output-dir")); err != nil {
+			return err
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		if runtime.Changed("content") {
+			return dryRunRenderScreenshot(runtime)
+		}
+		ref, err := parsePresentationRef(runtime.Str("presentation"))
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
+		slideIDs := normalizeSlideIDs(runtime.StrArray("slide-id"))
+		slideNumbers, err := normalizeSlideNumbers(runtime.IntArray("slide-number"))
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
+		if len(slideIDs) == 0 && len(slideNumbers) == 0 {
+			return common.NewDryRunAPI().Set("error", "--slide-id or --slide-number is required")
+		}
+
+		presentationID := ref.Token
+		dry := common.NewDryRunAPI()
+		if ref.Kind == "wiki" {
+			presentationID = "<resolved_slides_token>"
+			dry.Desc("2-step orchestration: resolve wiki → fetch slide screenshot(s)").
+				GET("/open-apis/wiki/v2/spaces/get_node").
+				Desc("[1] Resolve wiki node to slides presentation").
+				Params(map[string]interface{}{"token": ref.Token})
+		} else {
+			dry.Desc(fmt.Sprintf("Fetch %d slide screenshot(s) and save files under %s", len(slideIDs)+len(slideNumbers), runtime.Str("output-dir")))
+		}
+		body := map[string]interface{}{}
+		if len(slideIDs) > 0 {
+			body["slide_ids"] = slideIDs
+		}
+		if len(slideNumbers) > 0 {
+			body["slide_numbers"] = slideNumbers
+		}
+		dry.POST(fmt.Sprintf(
+			"/open-apis/slides_ai/v1/xml_presentations/%s/slide_images",
+			validate.EncodePathSegment(presentationID),
+		)).
+			Body(body)
+		return dry.Set("output_dir", runtime.Str("output-dir")).Set("base64_output", "suppressed; decoded to local files during execution")
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if runtime.Changed("content") {
+			return executeRenderScreenshot(runtime)
+		}
+		ref, err := parsePresentationRef(runtime.Str("presentation"))
+		if err != nil {
+			return err
+		}
+		presentationID, err := resolvePresentationID(runtime, ref)
+		if err != nil {
+			return err
+		}
+
+		slideIDs := normalizeSlideIDs(runtime.StrArray("slide-id"))
+		slideNumbers, err := normalizeSlideNumbers(runtime.IntArray("slide-number"))
+		if err != nil {
+			return err
+		}
+		if len(slideIDs) == 0 && len(slideNumbers) == 0 {
+			return common.FlagErrorf("--slide-id or --slide-number is required")
+		}
+		outputDir := runtime.Str("output-dir")
+		safeOutputDir, err := ensureScreenshotOutputDir(outputDir)
+		if err != nil {
+			return err
+		}
+
+		url := fmt.Sprintf(
+			"/open-apis/slides_ai/v1/xml_presentations/%s/slide_images",
+			validate.EncodePathSegment(presentationID),
+		)
+		query := larkcore.QueryParams{}
+		body := map[string]interface{}{}
+		if len(slideIDs) > 0 {
+			body["slide_ids"] = slideIDs
+		}
+		if len(slideNumbers) > 0 {
+			body["slide_numbers"] = slideNumbers
+		}
+		data, err := runtime.DoAPIJSONWithLogID("POST", url, query, body)
+		if err != nil {
+			return err
+		}
+
+		saved, err := saveSlideScreenshots(data, safeOutputDir)
+		if err != nil {
+			return err
+		}
+		runtime.Out(map[string]interface{}{
+			"xml_presentation_id": presentationID,
+			"output_dir":          outputDir,
+			"screenshots":         saved,
+		}, nil)
+		return nil
+	},
+}
+
+func dryRunRenderScreenshot(runtime *common.RuntimeContext) *common.DryRunAPI {
+	content := runtime.Str("content")
+	if strings.TrimSpace(content) == "" {
+		return common.NewDryRunAPI().Set("error", "--content cannot be empty")
+	}
+	if len(normalizeSlideIDs(runtime.StrArray("slide-id"))) > 0 || len(runtime.IntArray("slide-number")) > 0 {
+		return common.NewDryRunAPI().Set("error", "--content cannot be used with --slide-id or --slide-number")
+	}
+	if runtime.Changed("presentation") {
+		return common.NewDryRunAPI().Set("error", "--presentation cannot be used with --content")
+	}
+	dry := common.NewDryRunAPI().Desc("Render slide XML content to a screenshot file")
+	dry.POST("/open-apis/slides_ai/v1/slide_image/render").
+		Body(map[string]interface{}{
+			"content": fmt.Sprintf("<xml omitted; length=%d>", len(content)),
+		})
+	return dry.Set("output_dir", runtime.Str("output-dir")).Set("base64_output", "suppressed; decoded to local file during execution")
+}
+
+func executeRenderScreenshot(runtime *common.RuntimeContext) error {
+	content := runtime.Str("content")
+	if strings.TrimSpace(content) == "" {
+		return common.FlagErrorf("--content cannot be empty")
+	}
+	if len(normalizeSlideIDs(runtime.StrArray("slide-id"))) > 0 || len(runtime.IntArray("slide-number")) > 0 {
+		return common.FlagErrorf("--content cannot be used with --slide-id or --slide-number")
+	}
+	if runtime.Changed("presentation") {
+		return common.FlagErrorf("--presentation cannot be used with --content")
+	}
+	outputDir := runtime.Str("output-dir")
+	safeOutputDir, err := ensureScreenshotOutputDir(outputDir)
+	if err != nil {
+		return err
+	}
+
+	data, err := runtime.DoAPIJSONWithLogID("POST", "/open-apis/slides_ai/v1/slide_image/render", larkcore.QueryParams{}, map[string]interface{}{
+		"content": content,
+	})
+	if err != nil {
+		return err
+	}
+	saved, err := saveRenderedSlideScreenshot(data, safeOutputDir, runtime.Str("output-name"))
+	if err != nil {
+		return err
+	}
+	runtime.Out(map[string]interface{}{
+		"output_dir":  outputDir,
+		"screenshots": saved,
+	}, nil)
+	return nil
+}
+
+func normalizeSlideIDs(values []string) []string {
+	out := make([]string, 0, len(values))
+	seen := map[string]struct{}{}
+	for _, v := range values {
+		s := strings.TrimSpace(v)
+		if s == "" {
+			continue
+		}
+		if _, ok := seen[s]; ok {
+			continue
+		}
+		seen[s] = struct{}{}
+		out = append(out, s)
+	}
+	return out
+}
+
+func normalizeSlideNumbers(values []int) ([]int, error) {
+	out := make([]int, 0, len(values))
+	seen := map[int]struct{}{}
+	for _, n := range values {
+		if n < 1 {
+			return nil, common.FlagErrorf("--slide-number must be a positive integer")
+		}
+		if _, ok := seen[n]; ok {
+			continue
+		}
+		seen[n] = struct{}{}
+		out = append(out, n)
+	}
+	return out, nil
+}
+
+func hasSlideScreenshotSelector(runtime *common.RuntimeContext) bool {
+	return len(normalizeSlideIDs(runtime.StrArray("slide-id"))) > 0 || len(runtime.IntArray("slide-number")) > 0
+}
+
+func validateScreenshotOutputDir(outputDir string) (string, error) {
+	safeProbe, err := validate.SafeOutputPath(filepath.Join(outputDir, "probe.png"))
+	if err != nil {
+		return "", common.FlagErrorf("--output-dir invalid: %v", err)
+	}
+	return filepath.Dir(safeProbe), nil
+}
+
+func ensureScreenshotOutputDir(outputDir string) (string, error) {
+	safeOutputDir, err := validateScreenshotOutputDir(outputDir)
+	if err != nil {
+		return "", err
+	}
+	if err := vfs.MkdirAll(safeOutputDir, 0o755); err != nil {
+		return "", output.Errorf(output.ExitAPI, "io_error", "create output directory %s: %v", outputDir, err)
+	}
+	return safeOutputDir, nil
+}
+
+func saveSlideScreenshots(data map[string]interface{}, outputDir string) ([]map[string]interface{}, error) {
+	items := common.GetSlice(data, "slide_images")
+	if len(items) == 0 {
+		return nil, slidesScreenshotAPIDataError(data, "slides screenshot returned no slide_images")
+	}
+	saved := make([]map[string]interface{}, 0, len(items))
+	for i, item := range items {
+		m, ok := item.(map[string]interface{})
+		if !ok {
+			return nil, slidesScreenshotAPIDataError(data, "slides screenshot returned invalid slide_images[%d]", i)
+		}
+		item, err := saveSlideScreenshotImage(m, outputDir, "", slideScreenshotFallbackName(m, i))
+		if err != nil {
+			if _, ok := err.(*output.ExitError); ok {
+				return nil, err
+			}
+			return nil, slidesScreenshotAPIDataError(data, "slides screenshot returned invalid slide_images[%d]: %v", i, err)
+		}
+		saved = append(saved, item)
+	}
+	return saved, nil
+}
+
+func saveRenderedSlideScreenshot(data map[string]interface{}, outputDir string, outputName string) ([]map[string]interface{}, error) {
+	item := common.GetMap(data, "slide_image")
+	if item == nil {
+		return nil, slidesScreenshotAPIDataError(data, "slides render screenshot returned no slide_image")
+	}
+	saved, err := saveSlideScreenshotImage(item, outputDir, outputName, "rendered-slide")
+	if err != nil {
+		if _, ok := err.(*output.ExitError); ok {
+			return nil, err
+		}
+		return nil, slidesScreenshotAPIDataError(data, "slides render screenshot returned invalid slide_image: %v", err)
+	}
+	return []map[string]interface{}{saved}, nil
+}
+
+func saveSlideScreenshotImage(item map[string]interface{}, outputDir string, outputName string, fallbackName string) (map[string]interface{}, error) {
+	slideID := strings.TrimSpace(common.GetString(item, "slide_id"))
+	ext, label, err := slideScreenshotFormat(item)
+	if err != nil {
+		if slideID != "" {
+			return nil, fmt.Errorf("%v for slide %s", err, slideID)
+		}
+		return nil, err
+	}
+	encoded := strings.TrimSpace(common.GetString(item, "data"))
+	if encoded == "" {
+		if slideID != "" {
+			return nil, fmt.Errorf("empty image data for slide %s", slideID)
+		}
+		return nil, fmt.Errorf("empty image data")
+	}
+	imageBytes, err := base64.StdEncoding.DecodeString(encoded)
+	if err != nil {
+		if slideID != "" {
+			return nil, fmt.Errorf("decode screenshot for slide %s: %v", slideID, err)
+		}
+		return nil, fmt.Errorf("decode screenshot: %v", err)
+	}
+	fileBase := strings.TrimSpace(outputName)
+	if fileBase == "" {
+		fileBase = slideID
+	}
+	if fileBase == "" {
+		fileBase = fallbackName
+	}
+	path := filepath.Join(outputDir, safeScreenshotFileName(fileBase, ext))
+	if err := vfs.WriteFile(path, imageBytes, 0o644); err != nil {
+		return nil, output.Errorf(output.ExitAPI, "io_error", "write screenshot %s: %v", path, err)
+	}
+	return map[string]interface{}{
+		"slide_id":     slideID,
+		"slide_number": common.GetInt(item, "slide_number"),
+		"format":       label,
+		"path":         path,
+		"size":         len(imageBytes),
+	}, nil
+}
+
+func slideScreenshotFallbackName(item map[string]interface{}, index int) string {
+	if slideNumber := common.GetInt(item, "slide_number"); slideNumber > 0 {
+		return fmt.Sprintf("slide-%d", slideNumber)
+	}
+	return fmt.Sprintf("slide-%d", index+1)
+}
+
+func slideScreenshotFormat(item map[string]interface{}) (string, string, error) {
+	format := common.GetInt(item, "format")
+	switch format {
+	case 1:
+		return "png", "png", nil
+	case 2:
+		return "jpg", "jpeg", nil
+	default:
+		return "", "", fmt.Errorf("unsupported screenshot format %d", format)
+	}
+}
+
+func slidesScreenshotAPIDataError(data map[string]interface{}, format string, args ...interface{}) error {
+	msg := fmt.Sprintf(format, args...)
+	detail := map[string]interface{}{
+		"raw_data": summarizeScreenshotAPIData(data),
+	}
+	if logID := strings.TrimSpace(common.GetString(data, "log_id")); logID != "" {
+		detail["log_id"] = logID
+	}
+	return &output.ExitError{
+		Code: output.ExitAPI,
+		Detail: &output.ErrDetail{
+			Type:    "api_error",
+			Message: msg,
+			Detail:  detail,
+		},
+	}
+}
+
+func summarizeScreenshotAPIData(v interface{}) interface{} {
+	switch x := v.(type) {
+	case map[string]interface{}:
+		out := make(map[string]interface{}, len(x))
+		for k, val := range x {
+			out[k] = summarizeScreenshotAPIData(val)
+		}
+		return out
+	case []interface{}:
+		out := make([]interface{}, 0, len(x))
+		for i, val := range x {
+			if i >= 20 {
+				out = append(out, fmt.Sprintf("<omitted %d more items>", len(x)-i))
+				break
+			}
+			out = append(out, summarizeScreenshotAPIData(val))
+		}
+		return out
+	case string:
+		if len(x) > 512 {
+			return fmt.Sprintf("<omitted string length=%d prefix=%q>", len(x), x[:64])
+		}
+		return x
+	default:
+		return x
+	}
+}
+
+func safeScreenshotFileName(base string, ext string) string {
+	name := unsafeScreenshotFileCharRegex.ReplaceAllString(base, "_")
+	name = strings.Trim(name, "._-")
+	if name == "" {
+		name = "slide"
+	}
+	return name + "." + ext
+}

shortcuts/slides/slides_screenshot_test.go

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

skills/lark-slides/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-slides
 version: 1.0.0
-description: "飞书幻灯片：创建和编辑幻灯片，接口通过 XML 协议通信。创建演示文稿、读取幻灯片内容、管理幻灯片页面（创建、删除、读取、局部替换）。当用户需要创建或编辑幻灯片、读取或修改单个页面时使用。当用户给出 doubao.com 的 /slides/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。"
+description: "飞书幻灯片：创建和编辑幻灯片，接口通过 XML 协议通信。创建演示文稿、读取幻灯片内容、获取幻灯片截图、管理幻灯片页面（创建、删除、读取、局部替换）。当用户需要创建或编辑幻灯片、读取或修改单个页面时使用。当用户给出 doubao.com 的 /slides/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -18,9 +18,11 @@ metadata:
 | 大幅改写页面 | 先回读现有 XML，写入新 plan，再替换或重建相关页面 | `xml_presentations.get`、`+replace-slide`、`lark-slides-edit-workflows.md` |
 | 编辑单个标题、文本块、图片或局部元素 | 优先块级替换/插入，不改页序 | `slides +replace-slide`、`lark-slides-replace-slide.md` |
 | 读取或分析已有 PPT | 解析 slides/wiki token，回读全文或单页 XML，保存 `xml_presentation_id`、`slide_id`、`revision_id` | `xml_presentations.get`、`xml_presentation.slide.get` |
+| 获取幻灯片页面截图 | 先确认 `slide_id` 列表，再用 shortcut 保存本地图片；不要把 Base64 输出给模型 | `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` |
 | 创建失败、空白页、3350001、布局异常 | 先回读状态，再按排障清单修复，不假设原操作原子成功 | `troubleshooting.md`、`validation-checklist.md` |
 
@@ -81,8 +83,10 @@ 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-screenshot.md`](references/lark-slides-screenshot.md)
 - 图片：[`lark-slides-media-upload.md`](references/lark-slides-media-upload.md)
 - 流程图 / 时序图 / 架构图 / 装饰图案：[`lark-slides-whiteboard.md`](references/lark-slides-whiteboard.md)
+- 图标：[`iconpark.md`](references/iconpark.md)、[`scripts/iconpark_tool.py`](scripts/iconpark_tool.py)
 - 模板：[`template-catalog.md`](references/template-catalog.md)、[`scripts/template_tool.py`](scripts/template_tool.py)
 - 排障：[`troubleshooting.md`](references/troubleshooting.md)
 - 完整协议：[`slides_xml_schema_definition.xml`](references/slides_xml_schema_definition.xml)

skills/lark-slides/references/iconpark.md

@@ -0,0 +1,46 @@
+# IconPark 图标
+
+IconPark 图标通过 `<icon>` 写入 slides XML，`iconType` 必须来自本 skill 的离线索引或已验证模板，避免凭记忆拼路径。
+
+## 机器优先流程
+
+```bash
+python3 skills/lark-slides/scripts/iconpark_tool.py search --query "增长趋势" --limit 8
+python3 skills/lark-slides/scripts/iconpark_tool.py resolve --name chart-line
+python3 skills/lark-slides/scripts/iconpark_tool.py list-categories
+```
+
+`search` 返回 JSON 数组，每项包含 `iconType`、`category`、`name`、`tags`、`score`。直接把选中的 `iconType` 写入 XML，并为图标指定可见颜色：
+
+```xml
+<icon iconType="iconpark/Charts/chart-line.svg" topLeftX="80" topLeftY="120" width="32" height="32">
+  <fill>
+    <fillColor color="rgba(37, 99, 235, 1)"/>
+  </fill>
+</icon>
+```
+
+## 使用规则
+
+- 默认先检索：语义图标需求必须先用 `iconpark_tool.py search --limit 8` 或 `--limit 10`，让 agent 从候选里结合版面语义二次判断；不要阅读全文索引，也不要编造不存在的 `iconType`。
+- 图标用于概念提示、步骤、状态、指标、角色和导航；不要用无关装饰图标填充版面。
+- 常用尺寸：行内状态图标 16-24px，卡片标题图标 28-40px，主视觉图标 56-96px。
+- 图标必须显式指定颜色并和背景有足够对比；深色背景优先放在浅色圆形/方形底上，或使用 `rgba(255, 255, 255, 1)` 作为图标填充色。
+- 查不到合适图标时，用 shape、line、text 画 XML-native fallback，不留空图标位。
+
+## 高频示例
+
+| 语义 | iconType |
+|---|---|
+| 设置/配置 | `iconpark/Base/setting.svg` |
+| 目标 | `iconpark/Base/aiming.svg` |
+| 增长趋势 | `iconpark/Charts/positive-dynamics.svg` |
+| 折线趋势 | `iconpark/Charts/chart-line.svg` |
+| 占比 | `iconpark/Charts/chart-proportion.svg` |
+| 数据看板 | `iconpark/Charts/data-screen.svg` |
+| 成功 | `iconpark/Character/check-one.svg` |
+| 失败/风险 | `iconpark/Character/close-one.svg` |
+| 团队/用户 | `iconpark/Peoples/peoples.svg` |
+| 安全防护 | `iconpark/Safe/protect.svg` |
+| 全球/市场 | `iconpark/Travel/world.svg` |
+| 邮件/联系 | `iconpark/Office/envelope-one.svg` |

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

@@ -84,7 +84,7 @@ lark-cli slides +replace-slide --as user \
 | `<line>` | 直线 | 需 `startX/startY/endX/endY` |
 | `<polyline>` | 折线 | `points` 读回时被服务端规整丢弃（几何已入库） |
 | `<img>` | 图片 | `src` 必须是 [`+media-upload`](lark-slides-media-upload.md) 返回的 `file_token`，不能是 URL |
-| `<icon>` | 图标 | `iconType` 取自 iconpark 资源 |
+| `<icon>` | 图标 | `iconType` 取自 iconpark 资源；语义图标先用 `scripts/iconpark_tool.py search` 检索 |
 | `<table>` | 表格 | 整表替换会**重建内部 td id**，旧 td block_id 立即失效 |
 | `<td>` | 单元格局部替换 | 只能 `block_replace`，不能 `block_insert`；`block_id` 必须是最新 `slide.get` 拿到的 td id |
 | `<chart>` | 图表（line/bar/column/pie/area/radar/combo） | 必须嵌 `<chartPlotArea>` + `<chartData>` + `<dim1>/<dim2>/<chartField>` |

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

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

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

@@ -170,6 +170,8 @@ SVG 模式：`<svg>` 需声明 `xmlns="http://www.w3.org/2000/svg"`，内容大
 Mermaid 模式：内容用 `<![CDATA[...]]>` 包裹，避免 `[`、`>`、`-->` 等字符破坏 XML 解析。\
 详细用法见 [lark-slides-whiteboard.md](lark-slides-whiteboard.md)。
 
+`iconType` 必须来自已验证的 IconPark 路径。需要语义图标时，先运行 `scripts/iconpark_tool.py search --query "<语义>"`，不要凭记忆拼路径。更多规则见 [iconpark.md](iconpark.md)。
+
 ## 颜色与样式
 
 ### fill

skills/lark-slides/scripts/iconpark_tool.py

@@ -0,0 +1,362 @@
+#!/usr/bin/env python3
+# Copyright (c) 2026 Lark Technologies Pte. Ltd.
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+
+SKILL_ROOT = Path(__file__).resolve().parent.parent
+REFERENCES_DIR = SKILL_ROOT / "references"
+DEFAULT_INDEX_PATH = REFERENCES_DIR / "iconpark-index.json"
+DEFAULT_LIMIT = 8
+CURATED_ICON_BOOSTS = {
+    "设置": {"iconpark/Base/setting.svg"},
+    "配置": {"iconpark/Base/setting.svg", "iconpark/Base/config.svg"},
+    "目标": {"iconpark/Base/aiming.svg", "iconpark/Sports/target-one.svg"},
+    "增长": {"iconpark/Charts/positive-dynamics.svg"},
+    "趋势": {"iconpark/Charts/chart-line.svg", "iconpark/Charts/positive-dynamics.svg"},
+    "占比": {"iconpark/Charts/chart-proportion.svg"},
+    "数据": {"iconpark/Charts/data-screen.svg"},
+    "看板": {"iconpark/Charts/data-screen.svg"},
+    "成功": {"iconpark/Character/check-one.svg"},
+    "完成": {"iconpark/Character/check-one.svg"},
+    "失败": {"iconpark/Character/close-one.svg"},
+    "风险": {"iconpark/Character/close-one.svg"},
+    "团队": {"iconpark/Peoples/peoples.svg"},
+    "用户": {"iconpark/Peoples/peoples.svg", "iconpark/Peoples/user.svg"},
+    "安全": {"iconpark/Safe/protect.svg"},
+    "防护": {"iconpark/Safe/protect.svg"},
+    "全球": {"iconpark/Travel/world.svg"},
+    "市场": {"iconpark/Travel/world.svg"},
+    "邮件": {"iconpark/Office/envelope-one.svg"},
+    "联系": {"iconpark/Office/envelope-one.svg"},
+    "会议": {"iconpark/Office/schedule.svg"},
+    "日程": {"iconpark/Office/schedule.svg"},
+    "飞书": {"iconpark/Brand/bydesign.svg"},
+}
+CURATED_BOOST_SCORE = 40
+
+
+class IconParkToolError(Exception):
+    pass
+
+
+def fail(message: str) -> None:
+    raise IconParkToolError(message)
+
+
+def normalize_whitespace(value: str) -> str:
+    return re.sub(r"\s+", " ", value).strip()
+
+
+def normalize_token(value: str) -> str:
+    return normalize_whitespace(value.lower().replace("_", "-"))
+
+
+def append_unique(target: list[str], token: str) -> None:
+    normalized = normalize_token(token)
+    if normalized and normalized not in target:
+        target.append(normalized)
+
+
+def tokenize_query(value: str) -> list[str]:
+    normalized = normalize_token(value)
+    if not normalized:
+        return []
+
+    tokens: list[str] = []
+    for item in re.split(r"[\s,/|，。；;：:（）()【】\[\]《》<>]+", normalized):
+        append_unique(tokens, item)
+
+    for phrase in re.findall(r"[\u3400-\u9fff]+", normalized):
+        if len(phrase) < 2:
+            continue
+        max_size = min(6, len(phrase))
+        for size in range(max_size, 1, -1):
+            for start in range(0, len(phrase) - size + 1):
+                append_unique(tokens, phrase[start : start + size])
+
+    synonym_tokens = {
+        "目标": ["aim", "target", "goal"],
+        "聚焦": ["focus", "target"],
+        "增长": ["growth", "trend", "positive"],
+        "趋势": ["trend", "chart", "line"],
+        "数据": ["data", "analytics", "chart"],
+        "指标": ["metric", "data"],
+        "看板": ["dashboard", "screen", "data"],
+        "成功": ["success", "check", "done"],
+        "完成": ["done", "success", "check"],
+        "失败": ["fail", "close", "risk"],
+        "风险": ["risk", "fail", "protect"],
+        "安全": ["safe", "security", "protect"],
+        "配置": ["config", "setting", "system"],
+        "设置": ["setting", "config"],
+        "团队": ["team", "people", "users"],
+        "用户": ["user", "people"],
+        "全球": ["global", "world", "earth"],
+        "市场": ["market", "world", "business"],
+        "邮件": ["mail", "message"],
+        "mail": ["message", "envelope", "envelope-one"],
+        "计划": ["plan", "schedule"],
+        "时间": ["time", "schedule"],
+        "学习": ["learning", "education", "book"],
+        "培训": ["training", "education"],
+        "自动化": ["automation", "ai"],
+        "ai": ["ai", "automation", "magic"],
+    }
+    for token in list(tokens):
+        for keyword, aliases in synonym_tokens.items():
+            if is_ascii_token(keyword):
+                matches = token == keyword
+            else:
+                matches = keyword in token
+            if matches:
+                for alias in aliases:
+                    append_unique(tokens, alias)
+
+    return tokens
+
+
+def is_ascii_token(value: str) -> bool:
+    return bool(re.fullmatch(r"[a-z0-9-]+", value))
+
+
+def allows_substring_match(value: str) -> bool:
+    return not is_ascii_token(value) or len(value) >= 3
+
+
+def field_tokens(*values: str) -> set[str]:
+    tokens: set[str] = set()
+    for value in values:
+        normalized = normalize_token(value)
+        if not normalized:
+            continue
+        tokens.add(normalized)
+        for part in re.split(r"[-\s]+", normalized):
+            if part:
+                tokens.add(part)
+    return tokens
+
+
+def load_index(path: str | Path = DEFAULT_INDEX_PATH) -> dict[str, Any]:
+    index_path = Path(path)
+    if not index_path.exists():
+        fail(f"iconpark index not found: {index_path}")
+    try:
+        index_data = json.loads(index_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as error:
+        fail(f"invalid iconpark index JSON: {error}")
+    if not isinstance(index_data.get("icons"), list):
+        fail("iconpark index must contain an icons array")
+    return index_data
+
+
+def icon_search_text(entry: dict[str, Any]) -> str:
+    parts = [
+        entry.get("iconType", ""),
+        entry.get("category", ""),
+        entry.get("name", ""),
+        " ".join(entry.get("tags") or []),
+    ]
+    return normalize_token(" ".join(parts))
+
+
+def score_icon(entry: dict[str, Any], query: str, tokens: list[str]) -> int:
+    raw_icon_type = entry.get("iconType", "")
+    icon_type = normalize_token(raw_icon_type)
+    category = normalize_token(entry.get("category", ""))
+    name = normalize_token(entry.get("name", ""))
+    tags = [normalize_token(tag) for tag in entry.get("tags") or []]
+    name_tokens = field_tokens(name)
+    category_tokens = field_tokens(category)
+    tag_tokens = field_tokens(*tags)
+    icon_type_tokens = field_tokens(icon_type)
+    search_text = icon_search_text(entry)
+    normalized_query = normalize_token(query)
+
+    score = 0
+    boosted_keywords: set[str] = set()
+    if normalized_query:
+        if normalized_query == icon_type or normalized_query == name:
+            score += 200
+        elif normalized_query in tag_tokens:
+            score += 120
+        elif normalized_query in icon_type_tokens:
+            score += 60
+        elif allows_substring_match(normalized_query) and normalized_query in search_text:
+            score += 30
+
+    for token in tokens:
+        for keyword, boosted_icon_types in CURATED_ICON_BOOSTS.items():
+            if keyword in boosted_keywords:
+                continue
+            if keyword in token and raw_icon_type in boosted_icon_types:
+                score += CURATED_BOOST_SCORE
+                boosted_keywords.add(keyword)
+        if token == name:
+            score += 80
+        elif token in name_tokens:
+            score += 55
+        elif allows_substring_match(token) and token in name:
+            score += 45
+        if token == category:
+            score += 35
+        elif token in category_tokens:
+            score += 25
+        elif allows_substring_match(token) and token in category:
+            score += 15
+        for tag in tags:
+            if token == tag:
+                score += 60
+            elif token in field_tokens(tag):
+                score += 45
+            elif allows_substring_match(token) and token in tag:
+                score += 20
+        if token in icon_type_tokens:
+            score += 20
+        elif allows_substring_match(token) and token in icon_type:
+            score += 15
+
+    return score
+
+
+def parse_limit(value: Any) -> int:
+    if value is None or value is False:
+        return DEFAULT_LIMIT
+    if value is True:
+        fail("limit requires an integer value")
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        fail(f"limit must be an integer: {value}")
+
+
+def public_icon(entry: dict[str, Any], score: int | None = None) -> dict[str, Any]:
+    result = {
+        "iconType": entry["iconType"],
+        "category": entry["category"],
+        "name": entry["name"],
+        "tags": entry.get("tags") or [],
+    }
+    if score is not None:
+        result["score"] = score
+    return result
+
+
+def search_icons(index_data: dict[str, Any], options: dict[str, Any]) -> list[dict[str, Any]]:
+    query = str(options.get("query") or "")
+    if not normalize_whitespace(query):
+        fail("query is required")
+    limit = parse_limit(options.get("limit"))
+    category_filter = normalize_token(str(options.get("category") or ""))
+    tokens = tokenize_query(query)
+
+    ranked: list[dict[str, Any]] = []
+    for entry in index_data["icons"]:
+        if category_filter and normalize_token(entry.get("category", "")) != category_filter:
+            continue
+        score = score_icon(entry, query, tokens)
+        if query and score == 0:
+            continue
+        ranked.append(public_icon(entry, score))
+
+    ranked.sort(key=lambda item: (-int(item["score"]), item["category"], item["name"]))
+    return ranked[: max(limit, 0)]
+
+
+def resolve_icon(index_data: dict[str, Any], name_or_type: str | None) -> dict[str, Any]:
+    if not name_or_type:
+        fail("name is required")
+    target = normalize_token(name_or_type)
+    matches = []
+    for entry in index_data["icons"]:
+        candidates = {
+            normalize_token(entry["iconType"]),
+            normalize_token(entry["name"]),
+            normalize_token(f'{entry["category"]}/{entry["name"]}.svg'),
+        }
+        if target in candidates:
+            matches.append(entry)
+    if not matches:
+        fail(f"icon not found: {name_or_type}")
+    if len(matches) > 1:
+        names = ", ".join(entry["iconType"] for entry in matches)
+        fail(f"ambiguous icon name: {name_or_type}; matches: {names}")
+    return public_icon(matches[0])
+
+
+def list_categories(index_data: dict[str, Any]) -> list[dict[str, Any]]:
+    counts: dict[str, int] = {}
+    for entry in index_data["icons"]:
+        counts[entry["category"]] = counts.get(entry["category"], 0) + 1
+    return [{"category": category, "count": counts[category]} for category in sorted(counts)]
+
+
+def parse_cli_args(argv: list[str]) -> tuple[str | None, dict[str, Any]]:
+    if not argv:
+        return None, {}
+    command, *rest = argv
+    options: dict[str, Any] = {}
+    index = 0
+    while index < len(rest):
+        token = rest[index]
+        if not token.startswith("--"):
+            fail(f"unexpected argument: {token}")
+        key = token[2:]
+        next_token = rest[index + 1] if index + 1 < len(rest) else None
+        if next_token is None or next_token.startswith("--"):
+            options[key] = True
+            index += 1
+            continue
+        options[key] = next_token
+        index += 2
+    return command, options
+
+
+def print_usage() -> None:
+    usage = [
+        "Usage:",
+        "  python3 iconpark_tool.py search --query <text> [--category <Category>] [--limit 8]",
+        "  python3 iconpark_tool.py resolve --name <name|iconType>",
+        "  python3 iconpark_tool.py list-categories",
+    ]
+    print("\n".join(usage), file=sys.stderr)
+
+
+def write_json(value: Any) -> None:
+    print(json.dumps(value, ensure_ascii=False, indent=2))
+
+
+def run_cli(argv: list[str] | None = None) -> None:
+    command, options = parse_cli_args(argv or sys.argv[1:])
+    if not command or command in {"--help", "help"}:
+        print_usage()
+        raise SystemExit(0)
+
+    index_data = load_index()
+    if command == "search":
+        write_json(search_icons(index_data, options))
+        return
+    if command == "resolve":
+        write_json(resolve_icon(index_data, options.get("name")))
+        return
+    if command == "list-categories":
+        write_json(list_categories(index_data))
+        return
+
+    print_usage()
+    fail(f"unknown command: {command}")
+
+
+if __name__ == "__main__":
+    try:
+        run_cli()
+    except IconParkToolError as error:
+        print(f"iconpark-tool error: {error}", file=sys.stderr)
+        raise SystemExit(1) from error

skills/lark-slides/scripts/iconpark_tool_test.py

@@ -0,0 +1,99 @@
+# Copyright (c) 2026 Lark Technologies Pte. Ltd.
+# SPDX-License-Identifier: MIT
+from __future__ import annotations
+
+import unittest
+
+import iconpark_tool
+
+
+class IconParkToolTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.index_data = iconpark_tool.load_index()
+
+    def test_search_icons_finds_growth_trend(self) -> None:
+        results = iconpark_tool.search_icons(self.index_data, {"query": "增长趋势", "limit": 5})
+        self.assertTrue(results)
+        self.assertTrue(
+            any(entry["iconType"] == "iconpark/Charts/positive-dynamics.svg" for entry in results)
+        )
+
+    def test_search_icons_supports_english_query(self) -> None:
+        results = iconpark_tool.search_icons(self.index_data, {"query": "security protect", "limit": 3})
+        self.assertTrue(results)
+        self.assertEqual(results[0]["iconType"], "iconpark/Safe/protect.svg")
+
+    def test_search_icons_supports_category_filter(self) -> None:
+        results = iconpark_tool.search_icons(
+            self.index_data,
+            {"query": "data", "category": "Charts", "limit": 10},
+        )
+        self.assertTrue(results)
+        self.assertTrue(all(entry["category"] == "Charts" for entry in results))
+
+    def test_search_icons_does_not_expand_ai_inside_words(self) -> None:
+        mail_results = iconpark_tool.search_icons(self.index_data, {"query": "mail", "limit": 5})
+        self.assertEqual(mail_results[0]["iconType"], "iconpark/Office/envelope-one.svg")
+        self.assertNotEqual(mail_results[0]["iconType"], "iconpark/Others/magic.svg")
+
+        fail_results = iconpark_tool.search_icons(self.index_data, {"query": "fail", "limit": 5})
+        self.assertNotEqual(fail_results[0]["iconType"], "iconpark/Others/magic.svg")
+
+    def test_search_icons_supports_template_icon_queries(self) -> None:
+        cases = [
+            ("arrow", "iconpark/Arrows/arrow-right.svg"),
+            ("right", "iconpark/Arrows/right.svg"),
+            ("PPT", "iconpark/Music/ppt.svg"),
+            ("table", "iconpark/Office/table.svg"),
+            ("会议", "iconpark/Office/schedule.svg"),
+            ("飞书", "iconpark/Brand/bydesign.svg"),
+        ]
+        for query, icon_type in cases:
+            with self.subTest(query=query):
+                results = iconpark_tool.search_icons(self.index_data, {"query": query, "limit": 5})
+                self.assertTrue(
+                    any(entry["iconType"] == icon_type for entry in results),
+                    f"{icon_type} not found in {results}",
+                )
+
+    def test_search_icons_defaults_to_wider_candidate_set(self) -> None:
+        results = iconpark_tool.search_icons(self.index_data, {"query": "data"})
+        self.assertEqual(len(results), 8)
+
+    def test_search_icons_boosts_common_slide_terms(self) -> None:
+        results = iconpark_tool.search_icons(self.index_data, {"query": "会议", "limit": 3})
+        self.assertTrue(
+            any(entry["iconType"] == "iconpark/Office/schedule.svg" for entry in results),
+            f"iconpark/Office/schedule.svg not found in {results}",
+        )
+
+    def test_search_icons_requires_query(self) -> None:
+        with self.assertRaises(iconpark_tool.IconParkToolError):
+            iconpark_tool.search_icons(self.index_data, {"limit": 5})
+
+    def test_search_icons_rejects_invalid_limit(self) -> None:
+        with self.assertRaises(iconpark_tool.IconParkToolError):
+            iconpark_tool.search_icons(self.index_data, {"query": "data", "limit": "abc"})
+
+    def test_resolve_icon_accepts_name_and_icon_type(self) -> None:
+        by_name = iconpark_tool.resolve_icon(self.index_data, "chart-line")
+        by_type = iconpark_tool.resolve_icon(self.index_data, "iconpark/Charts/chart-line.svg")
+        self.assertEqual(by_name["iconType"], "iconpark/Charts/chart-line.svg")
+        self.assertEqual(by_name, by_type)
+
+    def test_resolve_icon_accepts_template_icon_type(self) -> None:
+        result = iconpark_tool.resolve_icon(self.index_data, "iconpark/Arrows/arrow-right.svg")
+        self.assertEqual(result["iconType"], "iconpark/Arrows/arrow-right.svg")
+
+    def test_resolve_icon_rejects_unknown_name(self) -> None:
+        with self.assertRaises(iconpark_tool.IconParkToolError):
+            iconpark_tool.resolve_icon(self.index_data, "not-a-real-icon")
+
+    def test_list_categories_counts_index(self) -> None:
+        categories = iconpark_tool.list_categories(self.index_data)
+        self.assertTrue(any(entry["category"] == "Charts" and entry["count"] > 0 for entry in categories))
+
+
+if __name__ == "__main__":
+    unittest.main()