docs: tighten lark-sheets skill guidance

Validate the example commands embedded in shortcut definitions (the
"Example: lark-cli ..." lines in each shortcut's Tips, shown in --help)
against the real command tree built by cmd.Build. Implemented entirely as
test-only code in cmd/ (package cmd_test), so it ships in no binary and is
not importable by product code; the truth source is cmd.Build, the same
tree the binary uses, so the check cannot drift. It runs in the standard
unit-test CI job (go test ./cmd/...); a renamed command or unaccepted flag
in an example fails that job.

cmd/cmdexample_catalog_test.go

@@ -0,0 +1,160 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmd_test
+
+import (
+	"sort"
+	"strings"
+)
+
+// universalFlags are accepted by every command (cobra auto-injects help; the
+// root injects version). They are never reported as unknown.
+var universalFlags = map[string]bool{"--help": true, "-h": true, "--version": true}
+
+// catalog is the source-of-truth command catalog: command path -> accepted flag
+// tokens. A path is the command words WITHOUT the "lark-cli" root prefix, e.g.
+// "contact +search-user". The root command is the empty path "".
+type catalog struct {
+	flagsByPath map[string]map[string]bool
+	group       map[string]bool // paths that are parent groups (have subcommands)
+	sorted      []string        // cached sorted paths for suggestCommand; invalidated on addCommand
+}
+
+func newCatalog() *catalog {
+	return &catalog{
+		flagsByPath: map[string]map[string]bool{},
+		group:       map[string]bool{},
+	}
+}
+
+// setGroup records whether path is a parent group (has subcommands). Leftover
+// words after a group node are unknown subcommands; after a leaf they are
+// positionals (e.g. "api GET /path").
+func (c *catalog) setGroup(path string, isGroup bool) {
+	if isGroup {
+		c.group[path] = true
+	}
+}
+
+func (c *catalog) isGroup(path string) bool { return c.group[path] }
+
+// addCommand registers a command path and the flags it accepts. Repeated calls
+// for the same path union the flag sets. flags are full tokens ("--query", "-q").
+func (c *catalog) addCommand(path string, flags []string) {
+	set := c.flagsByPath[path]
+	if set == nil {
+		set = map[string]bool{}
+		c.flagsByPath[path] = set
+	}
+	for _, f := range flags {
+		set[f] = true
+	}
+	c.sorted = nil // invalidate cached suggestion list
+}
+
+func (c *catalog) hasCommand(path string) bool {
+	_, ok := c.flagsByPath[path]
+	return ok
+}
+
+// hasFlag reports whether flag is accepted by command path (universal flags
+// always pass).
+func (c *catalog) hasFlag(path, flag string) bool {
+	if universalFlags[flag] {
+		return true
+	}
+	set := c.flagsByPath[path]
+	return set[flag]
+}
+
+// longestPrefix returns the longest known command path that is a prefix of
+// words, plus how many words it consumed. This separates real subcommands from
+// trailing positionals (e.g. "api GET /path" resolves to "api"). When words is
+// empty it falls back to the root command. ok=false means not even the first
+// word names a command.
+func (c *catalog) longestPrefix(words []string) (path string, n int, ok bool) {
+	if len(words) == 0 {
+		if c.hasCommand("") {
+			return "", 0, true
+		}
+		return "", 0, false
+	}
+	for i := len(words); i >= 1; i-- {
+		cand := strings.Join(words[:i], " ")
+		if c.hasCommand(cand) {
+			return cand, i, true
+		}
+	}
+	return "", 0, false
+}
+
+// paths returns all known command paths, sorted.
+func (c *catalog) paths() []string {
+	out := make([]string, 0, len(c.flagsByPath))
+	for p := range c.flagsByPath {
+		out = append(out, p)
+	}
+	sort.Strings(out)
+	return out
+}
+
+// suggestCommand returns the known command path closest to want (small edit
+// distance), for error hints. Returns "" when nothing is reasonably close.
+func (c *catalog) suggestCommand(want string) string {
+	if c.sorted == nil {
+		c.sorted = c.paths() // built once after the catalog is fully populated
+	}
+	return closest(want, c.sorted)
+}
+
+// suggestFlag returns the flag of path closest to flag, for error hints.
+func (c *catalog) suggestFlag(path, flag string) string {
+	set := c.flagsByPath[path]
+	cands := make([]string, 0, len(set))
+	for f := range set {
+		cands = append(cands, f)
+	}
+	sort.Strings(cands)
+	return closest(flag, cands)
+}
+
+// closest returns the candidate with the smallest Levenshtein distance to want,
+// but only if that distance is within a tolerance scaled to want's length
+// (avoids absurd suggestions).
+func closest(want string, cands []string) string {
+	best := ""
+	bestD := 1 << 30
+	for _, cand := range cands {
+		d := levenshtein(want, cand)
+		if d < bestD {
+			bestD, best = d, cand
+		}
+	}
+	tol := len(want)/2 + 1
+	if bestD > tol {
+		return ""
+	}
+	return best
+}
+
+func levenshtein(a, b string) int {
+	ra, rb := []rune(a), []rune(b)
+	prev := make([]int, len(rb)+1)
+	for j := range prev {
+		prev[j] = j
+	}
+	for i := 1; i <= len(ra); i++ {
+		cur := make([]int, len(rb)+1)
+		cur[0] = i
+		for j := 1; j <= len(rb); j++ {
+			cost := 1
+			if ra[i-1] == rb[j-1] {
+				cost = 0
+			}
+			cur[j] = min(prev[j]+1, cur[j-1]+1, prev[j-1]+cost)
+		}
+		prev = cur
+	}
+	return prev[len(rb)]
+}

cmd/cmdexample_check_test.go

@@ -0,0 +1,60 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmd_test
+
+import "strings"
+
+// Finding kinds.
+const (
+	unknownCommand = "unknown_command"
+	unknownFlag    = "unknown_flag"
+)
+
+// finding is a single mismatch between an example command reference and the
+// catalog.
+type finding struct {
+	line    int
+	raw     string
+	kind    string // unknownCommand | unknownFlag
+	path    string // resolved command path (unknownFlag) or attempted path (unknownCommand)
+	flag    string // offending flag (unknownFlag only)
+	suggest string // nearest known command/flag, "" if none close
+}
+
+// checkRefs validates refs against cat and returns all mismatches in order.
+func checkRefs(cat *catalog, refs []ref) []finding {
+	var out []finding
+	for _, r := range refs {
+		path, n, ok := cat.longestPrefix(r.words)
+		if !ok {
+			attempted := strings.Join(r.words, " ")
+			out = append(out, finding{
+				line: r.line, raw: r.raw, kind: unknownCommand,
+				path: attempted, suggest: cat.suggestCommand(attempted),
+			})
+			continue
+		}
+		// Leftover words after a group node are an unknown subcommand (e.g. a
+		// mistyped method like "batch_modify_message"). After a leaf they are
+		// positionals (e.g. "api GET /path"), so only groups trigger this.
+		if n < len(r.words) && cat.isGroup(path) {
+			attempted := strings.Join(r.words, " ")
+			out = append(out, finding{
+				line: r.line, raw: r.raw, kind: unknownCommand,
+				path: attempted, suggest: cat.suggestCommand(attempted),
+			})
+			continue
+		}
+		for _, f := range r.flags {
+			if cat.hasFlag(path, f) {
+				continue
+			}
+			out = append(out, finding{
+				line: r.line, raw: r.raw, kind: unknownFlag,
+				path: path, flag: f, suggest: cat.suggestFlag(path, f),
+			})
+		}
+	}
+	return out
+}

cmd/cmdexample_parse_test.go

@@ -0,0 +1,222 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmd_test
+
+import (
+	"regexp"
+	"strings"
+)
+
+// ref is one lark-cli command reference extracted from a shortcut example.
+type ref struct {
+	line  int      // 1-based line number (the line where the command starts)
+	raw   string   // reconstructed command text, for error display
+	words []string // command words before the first flag (subcommand candidates)
+	flags []string // flag tokens used, e.g. "--query", "-q"
+}
+
+const cliToken = "lark-cli"
+
+// subcommandStart guards against false positives from prose: a real command's
+// first word is ASCII (a service name or a +shortcut). A token starting with
+// CJK / punctuation is treated as narration, not a command.
+var subcommandStart = regexp.MustCompile(`^[A-Za-z+]`)
+
+// shellStops are standalone tokens that terminate a command (pipes, redirects,
+// separators). Separators glued to a token (`get;`, `foo|`) are handled inline.
+var shellStops = map[string]bool{
+	"|": true, "||": true, "&&": true, "&": true, ";": true,
+	">": true, ">>": true, "<": true, "2>": true, "2>&1": true,
+}
+
+// wordTrailPunct is sentence / CJK punctuation that can cling to a command word
+// in prose ("auth login." / "auth login，"); stripped so the word still resolves
+// instead of being dropped as an unknown command or non-ASCII narration.
+const wordTrailPunct = `.,;:!?"')]}，。、；：！？）】」』`
+
+// parseRefs extracts every lark-cli command reference from text (a shortcut's
+// Tips line, which may embed an "Example: lark-cli ..." command). It is
+// deliberately format-agnostic: it keys on the "lark-cli" token whether it sits
+// in a ```bash fence, an inline `code` span, or bare prose. Backslash
+// line-continuations are joined first so a multi-line invocation is parsed as
+// one command; inline-code backticks and trailing # comments terminate it.
+func parseRefs(content string) []ref {
+	var refs []ref
+	lines := strings.Split(content, "\n")
+	for i := 0; i < len(lines); i++ {
+		lineNo := i + 1
+		logical := lines[i]
+		// Shell line continuation: a trailing backslash joins the next physical
+		// line. Without this, flags on the continuation lines of a multi-line
+		// `lark-cli ... \` example are never seen by the checker.
+		for endsWithBackslash(logical) && i+1 < len(lines) {
+			logical = strings.TrimRight(logical, " \t")
+			logical = logical[:len(logical)-1] // drop the trailing backslash
+			i++
+			logical += " " + lines[i]
+		}
+		refs = append(refs, parseLine(logical, lineNo)...)
+	}
+	return refs
+}
+
+func endsWithBackslash(s string) bool {
+	return strings.HasSuffix(strings.TrimRight(s, " \t"), `\`)
+}
+
+func parseLine(line string, lineNo int) []ref {
+	var refs []ref
+	rest := line
+	for {
+		idx := strings.Index(rest, cliToken)
+		if idx < 0 {
+			break
+		}
+		after := rest[idx+len(cliToken):]
+		beforeOK := idx == 0 || isBoundary(rest[idx-1])
+		afterOK := after == "" || isBoundary(after[0])
+		if beforeOK && afterOK {
+			if words, flags, raw, ok := parseCmd(after); ok {
+				refs = append(refs, ref{line: lineNo, raw: cliToken + raw, words: words, flags: flags})
+			}
+		}
+		rest = after
+	}
+	return refs
+}
+
+// parseCmd tokenizes the text following "lark-cli" into leading command words
+// (the subcommand path, up to the first flag) and flag tokens. It stops at a
+// shell separator (standalone or glued), an inline-code backtick, a comment, or
+// a placeholder/prose word. ok=false filters out non-commands.
+func parseCmd(after string) (words, flags []string, raw string, ok bool) {
+	// An inline code span ends at the next backtick; a command never spans one.
+	if i := strings.IndexByte(after, '`'); i >= 0 {
+		after = after[:i]
+	}
+	// Drop $(...) command substitutions so flags belonging to the inner command
+	// (e.g. `--data "$(jq -n --arg x ...)"`) are not mistaken for lark-cli flags.
+	after = stripCmdSubst(after)
+
+	var kept []string
+	inFlags := false
+	for _, orig := range strings.Fields(after) {
+		tok := orig
+		if shellStops[tok] || strings.HasPrefix(tok, "#") {
+			break
+		}
+		// A shell separator glued to a token ends the command mid-token
+		// ("get;", "foo|next"): keep the part before it, handle it, then stop.
+		stop := false
+		if i := strings.IndexAny(tok, ";|"); i >= 0 {
+			tok, stop = tok[:i], true
+		}
+		switch {
+		case tok == "" || tok == "-":
+			// empty (after a glued separator) or a bare stdin marker — skip
+		case strings.HasPrefix(tok, "-"):
+			if f := normalizeFlag(tok); f != "" {
+				inFlags = true
+				flags = append(flags, f)
+				kept = append(kept, tok)
+			}
+		case inFlags:
+			// positional / flag value after the first flag — not a command word
+			kept = append(kept, tok)
+		default:
+			// Command-path word. ASCII placeholder markers (<x>, [x], {x|y},
+			// +<verb>, ...) end the command — checked on the RAW token so the
+			// trailing-punct stripping below cannot erase a "..." ellipsis
+			// ("base +..." must stay a placeholder, not become "+").
+			if strings.ContainsAny(tok, "<>[]{}|") || strings.Contains(tok, "...") {
+				stop = true
+				break
+			}
+			// Strip trailing sentence/CJK punctuation so "login." / "login，"
+			// resolve to "login"; non-ASCII narration ends the command.
+			w := strings.TrimRight(tok, wordTrailPunct)
+			if w == "" || hasNonASCII(w) {
+				stop = true
+				break
+			}
+			words = append(words, w)
+			kept = append(kept, tok)
+		}
+		if stop {
+			break
+		}
+	}
+	if len(kept) > 0 {
+		raw = " " + strings.Join(kept, " ")
+	}
+	// Keep root-only refs ("lark-cli --help") and refs whose first word looks
+	// like a subcommand; drop prose ("lark-cli 就能搞定 ...").
+	if len(words) == 0 {
+		return words, flags, raw, len(flags) > 0
+	}
+	if !subcommandStart.MatchString(words[0]) {
+		return nil, nil, "", false
+	}
+	return words, flags, raw, true
+}
+
+// stripCmdSubst removes $(...) command substitutions (including nested ones)
+// from s, leaving the surrounding text intact. Backtick substitutions are
+// already handled upstream (a command never spans a backtick).
+func stripCmdSubst(s string) string {
+	var b strings.Builder
+	depth := 0
+	for i := 0; i < len(s); i++ {
+		if depth == 0 && i+1 < len(s) && s[i] == '$' && s[i+1] == '(' {
+			depth = 1
+			i++ // skip '('
+			continue
+		}
+		if depth > 0 {
+			switch s[i] {
+			case '(':
+				depth++
+			case ')':
+				depth--
+			}
+			continue
+		}
+		b.WriteByte(s[i])
+	}
+	return b.String()
+}
+
+// isPlaceholderOrProse reports whether a command word is a doc placeholder
+// (<resource>, [flags], {a|b}, +<verb>, ...) or narration (CJK / other
+// non-ASCII), rather than a literal command token.
+func isPlaceholderOrProse(w string) bool {
+	if hasNonASCII(w) {
+		return true
+	}
+	return strings.ContainsAny(w, "<>[]{}|") || strings.Contains(w, "...")
+}
+
+func hasNonASCII(s string) bool {
+	return strings.IndexFunc(s, func(r rune) bool { return r > 127 }) >= 0
+}
+
+// flagShape matches the leading flag token, stripping any trailing junk such as
+// a "=value" suffix or punctuation that bled in from the surrounding markdown
+// ("--help\"", "--help;", "--params={}"). The underscore is allowed because
+// real flags use it ("--input_format", "--output_as"). Returns "" for non-flags.
+var flagShape = regexp.MustCompile(`^--?[A-Za-z][A-Za-z0-9_-]*`)
+
+// normalizeFlag extracts the canonical flag token from tok, or "" if tok is not
+// a real flag (e.g. a shell-string fragment like "-草稿'").
+func normalizeFlag(tok string) string {
+	return flagShape.FindString(tok)
+}
+
+func isBoundary(b byte) bool {
+	switch b {
+	case ' ', '\t', '`', '(', ')', '\'', '"', '*':
+		return true
+	}
+	return false
+}

cmd/cmdexample_test.go

@@ -0,0 +1,113 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// This file and its cmdexample_*_test.go siblings implement a test-only check:
+// the example commands embedded in shortcut definitions (the "Example: lark-cli
+// ..." lines in each shortcut's Tips, shown in --help) must match the real
+// command tree. It lives entirely in _test.go files (package cmd_test) so it
+// ships in no binary and is not importable by product code; the truth source is
+// cmd.Build, the same tree the binary uses, so the check cannot drift.
+//
+// It runs in the standard unit-test CI job (go test ./cmd/...). A mismatch — an
+// example using a renamed command or an unaccepted flag — fails that job.
+
+package cmd_test
+
+import (
+	"context"
+	"sort"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/cmd"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/shortcuts"
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+)
+
+// TestShortcutExampleCommands checks the example commands embedded in every
+// shortcut's Tips against the live command tree. A shortcut that defines no
+// example is simply skipped.
+//
+// Because the examples and the command definitions live in the same Go code,
+// this is a self-consistency check: any mismatch (an example using a renamed
+// command or a flag the command doesn't accept) is a bug to fix at the source.
+// It runs over all shortcuts — no baseline, no diff — since a wrong example is
+// always a defect, never acceptable "pre-existing drift".
+func TestShortcutExampleCommands(t *testing.T) {
+	// Reproducibility: use the embedded API metadata (not a developer's stale
+	// ~/.lark-cli remote cache, which can miss commands) and an empty config
+	// dir so local strict mode / plugins / policy cannot reshape the tree.
+	// t.Setenv auto-restores after the test, so other cmd tests are unaffected.
+	t.Setenv("LARKSUITE_CLI_REMOTE_META", "off")
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	cat := buildCmdExampleCatalog()
+
+	type located struct {
+		shortcut string
+		f        finding
+	}
+	var findings []located
+	for _, sc := range shortcuts.AllShortcuts() {
+		var refs []ref
+		for _, tip := range sc.Tips {
+			refs = append(refs, parseRefs(tip)...)
+		}
+		label := strings.TrimSpace(sc.Service + " " + sc.Command)
+		for _, f := range checkRefs(cat, refs) {
+			findings = append(findings, located{shortcut: label, f: f})
+		}
+	}
+
+	if len(findings) == 0 {
+		return
+	}
+	sort.Slice(findings, func(i, j int) bool { return findings[i].shortcut < findings[j].shortcut })
+	for _, lf := range findings {
+		hint := ""
+		if lf.f.suggest != "" {
+			hint = "  (did you mean " + lf.f.suggest + "?)"
+		}
+		if lf.f.kind == unknownFlag {
+			t.Errorf("shortcut %q example uses unknown flag %s on %q%s\n      %s",
+				lf.shortcut, lf.f.flag, lf.f.path, hint, strings.TrimSpace(lf.f.raw))
+		} else {
+			t.Errorf("shortcut %q example uses unknown command %q%s\n      %s",
+				lf.shortcut, lf.f.path, hint, strings.TrimSpace(lf.f.raw))
+		}
+	}
+	t.Fatalf("%d shortcut example command(s) don't match the real CLI — "+
+		"fix the Example in the shortcut definition.", len(findings))
+}
+
+// buildCmdExampleCatalog walks the live cobra command tree and records every
+// command path (minus the "lark-cli" root prefix) with its accepted flags and
+// whether it is a parent group. This is the same Build() the binary uses, so
+// the catalog can never drift from the real commands.
+func buildCmdExampleCatalog() *catalog {
+	root := cmd.Build(context.Background(), cmdutil.InvocationContext{})
+	cat := newCatalog()
+	var walk func(c *cobra.Command)
+	walk = func(c *cobra.Command) {
+		path := strings.TrimSpace(strings.TrimPrefix(c.CommandPath(), "lark-cli"))
+		var flags []string
+		add := func(fl *pflag.Flag) {
+			flags = append(flags, "--"+fl.Name)
+			if fl.Shorthand != "" {
+				flags = append(flags, "-"+fl.Shorthand)
+			}
+		}
+		c.Flags().VisitAll(add)
+		c.InheritedFlags().VisitAll(add)
+		c.PersistentFlags().VisitAll(add) // root's own persistent flags (e.g. --profile)
+		cat.addCommand(path, flags)
+		cat.setGroup(path, c.HasSubCommands())
+		for _, sub := range c.Commands() {
+			walk(sub)
+		}
+	}
+	walk(root)
+	return cat
+}

cmd/cmdexample_units_test.go

@@ -0,0 +1,233 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmd_test
+
+import (
+	"strings"
+	"testing"
+)
+
+func testCatalog() *catalog {
+	c := newCatalog()
+	c.addCommand("", []string{"--profile"}) // root
+	c.setGroup("", true)
+	c.addCommand("contact", []string{"--profile"})
+	c.setGroup("contact", true)
+	c.addCommand("contact +search-user", []string{"--query", "--as", "--format", "-q"})
+	c.addCommand("api", []string{"--params", "--data", "--as"}) // leaf (no subcommands)
+	c.addCommand("mail", nil)
+	c.setGroup("mail", true)
+	c.addCommand("mail user_mailbox.messages", []string{"--profile"})
+	c.setGroup("mail user_mailbox.messages", true)
+	c.addCommand("mail user_mailbox.messages batch_modify", []string{"--params", "--data"})
+	return c
+}
+
+func TestCmdExampleCatalogHasCommandAndFlag(t *testing.T) {
+	c := testCatalog()
+	if !c.hasCommand("contact +search-user") {
+		t.Fatal("expected contact +search-user to exist")
+	}
+	if c.hasCommand("contact +nope") {
+		t.Fatal("did not expect contact +nope")
+	}
+	if !c.hasFlag("contact +search-user", "--query") {
+		t.Fatal("--query should be valid")
+	}
+	if c.hasFlag("contact +search-user", "--nope") {
+		t.Fatal("--nope should be invalid")
+	}
+	// universal flags pass on any command
+	for _, f := range []string{"--help", "-h", "--version"} {
+		if !c.hasFlag("contact +search-user", f) {
+			t.Fatalf("universal flag %s should pass", f)
+		}
+	}
+}
+
+func TestCmdExampleLongestPrefix(t *testing.T) {
+	c := testCatalog()
+	tests := []struct {
+		words  []string
+		want   string
+		wantN  int
+		wantOK bool
+	}{
+		{[]string{"contact", "+search-user"}, "contact +search-user", 2, true},
+		{[]string{"api", "GET", "/open-apis/x"}, "api", 1, true}, // trailing positionals
+		{[]string{"nope"}, "", 0, false},
+		{nil, "", 0, true}, // empty -> root
+	}
+	for _, tt := range tests {
+		got, n, ok := c.longestPrefix(tt.words)
+		if got != tt.want || n != tt.wantN || ok != tt.wantOK {
+			t.Errorf("longestPrefix(%v) = (%q,%d,%v), want (%q,%d,%v)",
+				tt.words, got, n, ok, tt.want, tt.wantN, tt.wantOK)
+		}
+	}
+}
+
+func refWordsOf(refs []ref) [][]string {
+	var out [][]string
+	for _, r := range refs {
+		out = append(out, r.words)
+	}
+	return out
+}
+
+func TestCmdExampleParseRefsExtractsCommands(t *testing.T) {
+	content := strings.Join([]string{
+		"运行 `lark-cli contact +search-user --query 张三` 搜索", // inline code
+		"```bash",
+		"lark-cli api GET /open-apis/x --params '{}'", // bash block
+		"```",
+		"用 lark-cli mail user_mailbox.messages batch_modify 即可", // bare prose command
+		"npx foo | lark-cli api GET /y",                         // after a pipe
+	}, "\n")
+	refs := parseRefs(content)
+	if len(refs) != 4 {
+		t.Fatalf("expected 4 refs, got %d: %v", len(refs), refWordsOf(refs))
+	}
+	if got := refs[0]; strings.Join(got.words, " ") != "contact +search-user" ||
+		len(got.flags) != 1 || got.flags[0] != "--query" {
+		t.Errorf("ref0 = %+v", got)
+	}
+	if got := refs[1]; strings.Join(got.words, " ") != "api GET /open-apis/x" {
+		t.Errorf("ref1 words = %v", got.words)
+	}
+}
+
+func TestCmdExampleParseRefsFiltersPlaceholdersAndProse(t *testing.T) {
+	// A line whose first word is prose yields no command at all.
+	if refs := parseRefs("lark-cli 就能搞定这件事"); len(refs) != 0 {
+		t.Errorf("prose-first line should yield 0 refs, got %v", refWordsOf(refs))
+	}
+	// Syntax templates / trailing prose may leave a real leading word ("mail"),
+	// but no placeholder or CJK token may leak into the command words — that is
+	// what prevents false positives like an "<resource>" unknown-command report.
+	for _, line := range []string{
+		"lark-cli mail <resource> <method> [flags]",
+		"lark-cli apps +<verb> [flags]",
+		"lark-cli base +...",
+		"lark-cli mail 写信场景下的格式说明",
+	} {
+		for _, r := range parseRefs(line) {
+			for _, w := range r.words {
+				if isPlaceholderOrProse(w) {
+					t.Errorf("%q: placeholder/prose token %q leaked into words %v", line, w, r.words)
+				}
+			}
+		}
+	}
+}
+
+func TestCmdExampleParseRefsStripsTrailingJunk(t *testing.T) {
+	// frontmatter-style quoted value: the trailing quote must not bleed into the flag
+	refs := parseRefs(`cliHelp: "lark-cli contact --help"`)
+	if len(refs) != 1 {
+		t.Fatalf("expected 1 ref, got %d", len(refs))
+	}
+	if len(refs[0].flags) != 1 || refs[0].flags[0] != "--help" {
+		t.Errorf("expected flag --help, got %v", refs[0].flags)
+	}
+	// bare "-" (stdin marker) and "=value" suffix
+	refs = parseRefs("lark-cli api GET /x --params={} --data -")
+	if len(refs) != 1 {
+		t.Fatalf("expected 1 ref, got %d", len(refs))
+	}
+	flags := strings.Join(refs[0].flags, " ")
+	if flags != "--params --data" {
+		t.Errorf("expected '--params --data', got %q", flags)
+	}
+}
+
+func TestCmdExampleCheck(t *testing.T) {
+	c := testCatalog()
+	tests := []struct {
+		name     string
+		r        ref
+		wantKind string // "" = no finding
+		wantPath string
+	}{
+		{"valid shortcut", ref{words: []string{"contact", "+search-user"}, flags: []string{"--query"}}, "", ""},
+		{"valid leaf positional", ref{words: []string{"api", "GET", "/x"}}, "", ""},
+		{"unknown top command", ref{words: []string{"nope"}}, unknownCommand, "nope"},
+		{"group leftover = unknown subcommand",
+			ref{words: []string{"mail", "user_mailbox.messages", "batch_modify_message"}},
+			unknownCommand, "mail user_mailbox.messages batch_modify_message"},
+		{"unknown flag", ref{words: []string{"contact", "+search-user"}, flags: []string{"--nope"}}, unknownFlag, "contact +search-user"},
+		{"universal flag ok", ref{words: []string{"contact", "+search-user"}, flags: []string{"--help"}}, "", ""},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			fs := checkRefs(c, []ref{tt.r})
+			if tt.wantKind == "" {
+				if len(fs) != 0 {
+					t.Fatalf("expected no finding, got %+v", fs)
+				}
+				return
+			}
+			if len(fs) != 1 {
+				t.Fatalf("expected 1 finding, got %d: %+v", len(fs), fs)
+			}
+			if fs[0].kind != tt.wantKind || fs[0].path != tt.wantPath {
+				t.Errorf("got kind=%s path=%q, want kind=%s path=%q", fs[0].kind, fs[0].path, tt.wantKind, tt.wantPath)
+			}
+		})
+	}
+}
+
+func TestCmdExampleCheckSuggestsNearest(t *testing.T) {
+	c := testCatalog()
+	fs := checkRefs(c, []ref{{words: []string{"mail", "user_mailbox.messages", "batch_modify_message"}}})
+	if len(fs) != 1 || fs[0].suggest != "mail user_mailbox.messages batch_modify" {
+		t.Fatalf("expected suggestion 'mail user_mailbox.messages batch_modify', got %+v", fs)
+	}
+}
+
+// TestCmdExampleParseRefsRobustness covers the parser edge cases hardened after
+// review: backslash continuation, underscore flags, $(...) substitution, glued
+// separators, trailing punctuation, and the "..." placeholder.
+func TestCmdExampleParseRefsRobustness(t *testing.T) {
+	cases := []struct {
+		name, content, wantWords, wantFlags string
+		wantRefs                            int
+	}{
+		{"backslash continuation joins flags",
+			"lark-cli contact +search-user \\\n  --query foo \\\n  --as user",
+			"contact +search-user", "--query --as", 1},
+		{"underscore flag not truncated",
+			"lark-cli whiteboard +update --input_format mermaid",
+			"whiteboard +update", "--input_format", 1},
+		{"command-substitution flags ignored",
+			`lark-cli slides x create --data "$(jq -n --arg c '{}')" --as user`,
+			"slides x create", "--data --as", 1},
+		{"glued separator truncates",
+			"lark-cli auth login; echo done",
+			"auth login", "", 1},
+		{"trailing CJK punctuation stripped",
+			"用 lark-cli auth login。",
+			"auth login", "", 1},
+		{"ellipsis placeholder stays placeholder",
+			"lark-cli base +...",
+			"base", "", 1},
+	}
+	for _, tt := range cases {
+		t.Run(tt.name, func(t *testing.T) {
+			refs := parseRefs(tt.content)
+			if len(refs) != tt.wantRefs {
+				t.Fatalf("refs=%d want %d: %v", len(refs), tt.wantRefs, refWordsOf(refs))
+			}
+			if tt.wantRefs == 0 {
+				return
+			}
+			if got := strings.Join(refs[0].words, " "); got != tt.wantWords {
+				t.Errorf("words=%q want %q", got, tt.wantWords)
+			}
+			if got := strings.Join(refs[0].flags, " "); got != tt.wantFlags {
+				t.Errorf("flags=%q want %q", got, tt.wantFlags)
+			}
+		})
+	}
+}

internal/registry/scope_priorities.json

@@ -439,11 +439,6 @@
     "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,12 +217,6 @@ 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)
@@ -1292,8 +1286,6 @@ 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,12 +4,9 @@
 package common
 
 import (
-	"context"
-	"reflect"
 	"strings"
 	"testing"
 
-	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/spf13/cobra"
 )
 
@@ -59,29 +56,3 @@ 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" | "int_array" | "string_array" | "string_slice"
+	Type     string // "string" (default) | "bool" | "int" | "float64" | "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,6 +11,5 @@ func Shortcuts() []common.Shortcut {
 		SlidesCreate,
 		SlidesMediaUpload,
 		SlidesReplaceSlide,
-		SlidesScreenshot,
 	}
 }

shortcuts/slides/slides_screenshot.go

@@ -1,442 +0,0 @@
-// 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

@@ -1,403 +0,0 @@
-// 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-sheets/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-sheets
 version: 2.0.0
-description: "飞书电子表格：创建和操作电子表格。支持创建表格、管理工作表与行列结构（增删/合并/调整尺寸/隐藏/冻结）、读写单元格（值/公式/样式/批注/单元格图片）、查找替换、多操作原子批量更新，以及图表、透视表、条件格式、筛选器、迷你图、浮动图片等对象的创建与维护。当用户需要创建电子表格、管理工作表、批量读写或编辑数据、统计汇总与可视化、表格美化、公式计算（含 Excel 公式迁移）等任务时使用。若用户是想按名称或关键词搜索云空间（云盘/云存储）里的表格文件，请改用 lark-drive 的 drive +search 先定位资源。当用户给出 doubao.com 的 /sheets/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。仅针对飞书在线电子表格，不适用于本地 Excel 文件。"
+description: "飞书电子表格：创建和操作电子表格。支持管理工作表结构、读写单元格数据与样式，以及图表、透视表、条件格式、筛选器、迷你图、浮动图片等对象。当用户需要创建电子表格、管理工作表、批量读写或编辑数据、统计汇总与可视化、表格美化、公式计算（含 Excel 公式迁移）等任务时使用。若用户是想按名称或关键词搜索表格文件，请改用 lark-drive 先定位资源。当用户给出 doubao.com 的 /sheets/ URL/token 时，也应直接使用本 skill；路由依据是 URL 路径模式和 token，而不是域名。仅针对飞书在线电子表格，不适用于本地 Excel 文件。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -13,6 +13,8 @@ metadata:
 
 **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理。**
 
+**身份：电子表格通常属于用户云空间资源，优先使用 `--as user`。首次使用前执行 `lark-cli auth login`。**
+
 ## 术语约定
 
 下列词在本 skill 各文档中可能交替出现，但**指同一对象**；解析用户口语时按此映射，不要当成不同概念：
@@ -34,7 +36,7 @@ metadata:
 
 ## 场景 → 命令速查（拿不准命令名先查这里，别按直觉拼）
 
-把高频意图映射到**真实存在**的 shortcut / flag。agent 常从 Excel / Google Sheets / 飞书 OpenAPI 误迁移命令名或 flag，先对照本表，避免一次必然失败的试错。完整 shortcut 见各工具参考。
+把高频意图映射到**真实存在**的 shortcut / flag。先对照本表，避免按直觉拼不存在的命令名或 flag。
 
 | 你要做的事 | ✅ 正确写法 | ❌ 不存在（会被 cobra 拒） |
 | --- | --- | --- |
@@ -57,7 +59,7 @@ metadata:
 
 ## References
 
-本 skill 的 reference 分两组：先读**通用方法与规范**（横切所有任务的工作流、铁律、样式、公式规则，不含具体 shortcut），它们规定了"怎么做对"；再按操作对象进入**工具参考**查具体 shortcut 与调用细节。编辑类任务务必先过一遍通用方法与规范，其中的铁律对所有工具参考一律生效。
+本 skill 的 reference 分两组：先读**通用方法与规范**，再按操作对象进入**工具参考**查具体 shortcut 与调用细节。
 
 ### 通用方法与规范（先读，横切所有任务，不含具体 shortcut）
 
@@ -101,7 +103,7 @@ metadata:
 
 1. **spreadsheet 定位（必填）**：`--url` 与 `--spreadsheet-token` 二选一，**必须给其中之一**。两个都不给 → 校验报错 `specify at least one of --url or --spreadsheet-token`；两个都给 → 互斥冲突。
    - **`--url` 只解析 `/sheets/` 与 `/spreadsheets/` 两种链接**（从路径里抽出 token；也可以直接把裸 token 传给 `--spreadsheet-token`）。其它形态的链接不会被解析成表格 token。
-   - ⚠️ **`/wiki/` 知识库链接不能直接当表格定位用**：wiki 链接背后可能是电子表格，也可能是文档 / 多维表格等其它类型，`--url` **不会**自动把 wiki token 解析成 spreadsheet token，直接传会失败。必须先把它解析成真实文档 token —— `lark-cli wiki +node-get --node-token "<wiki 链接或 token>"`，确认返回的 `obj_type` 为 `sheet` 后，取其 `obj_token` 作为 `--spreadsheet-token` 传入（解析细节见 [`../lark-wiki/SKILL.md`](../lark-wiki/SKILL.md)）。
+   - ⚠️ **`/wiki/` 知识库链接不能直接当表格定位用**：先用 `lark-cli drive +inspect --url "<wiki_url>"` 自动解包；当返回 `type=sheet` 时，用 `token` 作为 `--spreadsheet-token`。手动方式见 [`../lark-wiki/SKILL.md`](../lark-wiki/SKILL.md)。
    - **例外**：`+workbook-create` 是新建一个还不存在的表格，**不接受任何 spreadsheet / sheet 定位 flag**（只有 `--title` / `--folder-token` / `--headers` / `--values`）。
 2. **sheet 定位（公共四件套 shortcut 必填）**：`--sheet-id` 与 `--sheet-name` 二选一，**必须给其中之一**。两个都不给 → 校验报错 `specify at least one of --sheet-id or --sheet-name`。
    - ⚠️ **不确定 sheet 名时禁止直接猜 `Sheet1`**：除非用户对话明确说出 sheet 名 / id，或上下文（之前的工具调用 / URL 锚点 `?sheet=xxx`）已经出现过具体值，否则**第一步先调 `+workbook-info --url "..."`**（或 `--spreadsheet-token`）拿 `sheets[].sheet_id` / `sheets[].title` 列表再选。中文环境下子表常叫"数据" / "Sheet"（无数字）/ "工作表 1" / 业务名，猜 `Sheet1` 大概率撞 `sheet not found`，比先查多耗一次失败调用 + 重试。
@@ -135,13 +137,6 @@ lark-cli sheets <shortcut> <workbook 定位> <sheet 定位> <其它 flag>
 | `--print-schema` | bool | 否 | 本地打印复合 JSON flag 的 JSON Schema 并退出，不发起任何调用、不需要其它 required flag。与 `--flag-name <name>` 搭配指定要查哪个 flag；省略 `--flag-name` 时列出该 shortcut 所有可查询的 flag。**仅在 shortcut 含复合 JSON flag 时有效**——判断方法：该 shortcut 的 Flags 表里出现类型标注为「复合 JSON」的 flag（如 `--cells` / `--properties` / `--operations` / `--border-styles` / `--sort-keys` / `--options`）即支持；纯标量 flag 的 shortcut 不支持。 |
 | `--flag-name` | string | 否 | 配合 `--print-schema` 使用，指定要打印 JSON Schema 的 flag 名（不带 `--` 前缀，如 `cells` / `properties` / `operations`）。 |
 
-**Agent 使用提示**：写复合 JSON flag（`--cells` / `--properties` / `--operations` / `--border-styles` / `--sort-keys` / `--options` 等）时，如果对结构不确定，先跑 `lark-cli sheets <shortcut> --print-schema --flag-name <name>` 把完整 JSON Schema 读出来再构造 payload，比靠 reference 的速查表更精确，也避免因为字段拼写或缺失被服务端拒绝。reference 的 `## Schemas` 段只给一层结构，深层只能靠 `--print-schema` 或 `## Examples` 的真实示例。
-
-### flag 内容类型与输出约定（术语速记）
-
-- flag 表里 JSON 类入参标三类：**复合 JSON** = 深层嵌套对象（用 `--print-schema` 取完整结构）；**简单 JSON** = 一维 / 二维标量数组（如 `["sheet1!A1:B2",...]` / `[["alice",95]]`，结构简单无需 print-schema）；**非 JSON 文本** = 原样文本（如 CSV）。`--print-schema` 只对**复合 JSON** flag 有效（同一 shortcut 的简单 JSON flag 如 `--colors` 不在此列）。
-- **envelope**：所有 shortcut 返回统一外层结构 `{ok, identity, data, ...}`。正文里 `envelope.data` 指业务数据层（如 `+csv-get` 的 `annotated_csv`）；写操作不会自动回读，如需校验请自行调用对应的 `+*-list` / `+*-get` / `+cells-get`。
-
 ## 复合 JSON / 大入参：优先 stdin
 
 flag 帮助里标注支持 **Stdin** 的入参，当 payload 较大、含换行 / 引号等特殊字符，或已经落在某个文件里时，优先用 stdin（`-`）传入，避免命令行超长与 shell 转义问题。
@@ -154,3 +149,9 @@ lark-cli sheets +cells-set --url "..." --sheet-name "Sheet1" --range "A1:B2" --c
 ```
 
 **`@file` 接绝对路径会被拒，且被拒后不要照报错提示做。** `@file` 出于安全只接受 cwd 下的相对路径，传 cwd 之外的绝对路径会被拒。此时报错会建议"先 cd 到目标目录，或改用相对路径"——**两条都不要照做**：cd 过去、或把临时文件写进用户项目目录，都会污染工作目录。正解是改用 stdin（`--<flag> - < 文件`）。
+
+## 不在本 skill 范围
+
+- 搜索云空间里的表格文件：切到 [`lark-drive`](../lark-drive/SKILL.md)
+- 评论、权限和通用 Drive 操作：切到 [`lark-drive`](../lark-drive/SKILL.md)
+- 多维表格 / Base 操作：切到 [`lark-base`](../lark-base/SKILL.md)

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,11 +18,9 @@ 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` |
 
@@ -83,10 +81,8 @@ lark-cli auth login --domain slides
 
 - 创建：[`lark-slides-create.md`](references/lark-slides-create.md)
 - 编辑：[`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)、[`lark-slides-replace-slide.md`](references/lark-slides-replace-slide.md)
-- 截图：[`lark-slides-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

@@ -1,46 +0,0 @@
-# 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 资源；语义图标先用 `scripts/iconpark_tool.py search` 检索 |
+| `<icon>` | 图标 | `iconType` 取自 iconpark 资源 |
 | `<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

@@ -1,104 +0,0 @@
-# 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,8 +170,6 @@ 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

@@ -1,362 +0,0 @@
-#!/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

@@ -1,99 +0,0 @@
-# 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()